docs/adr/*.md  ──┐
openapi.yaml   ──┤
notion pages   ──┤
confluence     ──┤  aco compile  ──►  Knowledge Graph  ──►  AI Agent context
obsidian vault ──┤                    (typed, anchored,      (via MCP or CLI)
pdf/docx       ──┤                     drift-detected,
ai-exports/    ──┘                     semantically indexed)

git clone https://github.com/<your-username>/aco.git
cd aco
uv tool install .
aco --help

git clone https://github.com/<your-username>/aco.git
cd aco
uv sync
uv run aco --help

git clone https://github.com/<your-username>/aco.git
pipx install ./aco
aco --help

# 1. Initialize a workspace pointing at your project
aco workspace init /path/to/your/project --name "My Project"
# → Workspace created: ws_abc123...

# 2. Add a knowledge source
aco source add --workspace ws_abc123 \
  --connector builtin/local-fs \
  --name "ADRs" \
  --root /path/to/your/project/docs/adr \
  --globs "**/*.md"

# 3. Compile
aco compile run --workspace ws_abc123

# 4. See what was found
aco knowledge list --workspace ws_abc123

# 5. Get a context pack
aco assembly compose --workspace ws_abc123 \
  --role coder \
  --goal "implement the payment service" \
  --path src/payments/handler.py

aco workspace init /path/to/project --name "My Project"
aco workspace list
aco workspace info --workspace ws_<id>
aco workspace remove ws_<id> --confirm

# Local filesystem (auto-detects PDF/docx by MIME type)
aco source add --workspace ws_<id> \
  --connector builtin/local-fs \
  --name "Docs" \
  --root docs/ \
  --globs "**/*.md" "**/*.pdf" "**/*.docx"

# AI export archive
aco source add --workspace ws_<id> \
  --connector builtin/ai-export \
  --name "AI Exports" \
  --archive-path /path/to/exports.tar.gz

# Notion workspace
aco source add --workspace ws_<id> \
  --connector builtin/notion \
  --name "Notion Docs" \
  --token secret_xxx \
  --database-id db_id_1

# GitHub Wiki
aco source add --workspace ws_<id> \
  --connector builtin/github-wiki \
  --name "Wiki" \
  --token ghp_xxx \
  --repo owner/repo-name

# Confluence (API token)
aco source add --workspace ws_<id> \
  --connector builtin/confluence \
  --name "Confluence" \
  --base-url https://company.atlassian.net \
  --token base64token \
  --space-key TEAM

# Confluence (cookie file — e.g. from sap-auth-mcp)
aco source add --workspace ws_<id> \
  --connector builtin/confluence \
  --name "SAP Wiki" \
  --base-url https://wiki.company.com \
  --cookie-file ~/.cookies/wiki.json \
  --space-key ENG

# Obsidian vault
aco source add --workspace ws_<id> \
  --connector builtin/obsidian \
  --name "My Vault" \
  --vault-path /path/to/obsidian-vault

aco source list --workspace ws_<id>
aco source fetch --workspace ws_<id>   # re-fetch without full compile

aco compile run --workspace ws_<id>              # full pipeline (includes embed)
aco compile run --workspace ws_<id> --stage fetch  # single stage
aco compile run --workspace ws_<id> --stage embed  # re-embed only
aco compile status --workspace ws_<id>
aco compile logs <job_id>

aco knowledge list --workspace ws_<id>
aco knowledge list --workspace ws_<id> --type ArchitectureDecision --status ACTIVE
aco knowledge show <object_id>
aco knowledge approve <object_id>   # promote REVIEW_REQUIRED → ACTIVE
aco knowledge reject <object_id>
aco knowledge verify --workspace ws_<id>   # manual drift check

aco review list --workspace ws_<id>
aco review show <review_id>
aco review approve <review_id>
aco review reject <review_id> --reason "outdated"
aco review approve-all --workspace ws_<id> --type DesignInsight --confirm

aco assembly compose --workspace ws_<id> \
  --role coder \
  --goal "refactor the auth module" \
  --path src/auth/handler.py \
  --path src/auth/models.py \
  --budget 8000 \
  --format markdown   # or json, xml

# Install — writes a post-commit hook into your project's .git
aco hooks install --workspace ws_<id> --git-dir /path/to/project/.git

# Every commit now auto-runs drift detection.
# Objects whose anchored code has changed move to DRIFTED.

# Remove
aco hooks remove --git-dir /path/to/project/.git

# Export full workspace state to a portable archive
aco pack export --workspace ws_<id> --out ~/backups/my-project.acopack.tar.gz

# Import on any machine
aco pack import ~/backups/my-project.acopack.tar.gz

{
  "mcpServers": {
    "aco": {
      "command": "aco",
      "args": ["mcp-serve", "--workspace", "ws_<your-workspace-id>"]
    }
  }
}

{
  "mcpServers": {
    "aco": {
      "command": "uv",
      "args": ["run", "aco", "mcp-serve", "--workspace", "ws_<id>"],
      "cwd": "/path/to/aco"
    }
  }
}

# On the old machine — export each workspace
aco workspace list   # note workspace IDs
aco pack export --workspace ws_<id> --out ~/ws-myproject.tar.gz

# Copy to new machine
scp ~/ws-myproject.tar.gz newmachine:~/

# On the new machine — install ACO, then import
aco pack import ~/ws-myproject.tar.gz

# Re-register the workspace path (the registry stores the absolute path to your project)
aco workspace list   # verify it imported

# On the old machine
tar -czf aco-state.tar.gz ~/.aco/

# Copy and restore on new machine
scp aco-state.tar.gz newmachine:~/
ssh newmachine "tar -xzf ~/aco-state.tar.gz -C ~/"

git clone https://github.com/<your-username>/aco.git
cd aco
uv tool install .
aco workspace list   # your workspaces are back

DRAFT → ACTIVE          (rule/human-extracted, passes validation)
DRAFT → REVIEW_REQUIRED (AI-extracted — always requires human approval)
ACTIVE → DRIFTED        (anchored code changed)
DRIFTED → REFRESHING    (refresh triggered)
REFRESHING → ACTIVE     (human approves updated version)

uv sync --extra anthropic   # Claude
uv sync --extra openai      # OpenAI
uv sync --extra llm         # both

aco source add --workspace ws_<id> \
  --connector builtin/local-fs \
  --name "Meeting Notes" \
  --root docs/meetings \
  --globs "**/*.md"

{
  "root": "docs/meetings",
  "globs": ["**/*.md"],
  "exclude": [],
  "extractor": "builtin/llm",
  "provider": "anthropic",
  "model": "claude-sonnet-5",
  "api_key_env": "ANTHROPIC_API_KEY",
  "object_types": ["Requirement", "Constraint", "Risk", "GlossaryTerm"],
  "max_objects_per_doc": 20
}

export ANTHROPIC_API_KEY=sk-ant-...
aco compile run --workspace ws_<id>
aco review list --workspace ws_<id>
aco review approve-all --type Constraint --confirm

[embeddings]
enabled = true
provider = "anthropic"           # or "openai"
model = "voyage-3"               # text-embedding-3-small for OpenAI
api_key_env = "ANTHROPIC_API_KEY"
dimensions = 1024
similarity_threshold = 0.75
max_semantic_candidates = 10

aco compile run --workspace ws_<id> --stage embed
# or included automatically in a full compile:
aco compile run --workspace ws_<id>

aco assembly compose --workspace ws_<id> \
  --role coder \
  --goal "implement rate limiting for the auth service"
# → finds relevant Constraints, Risks, and Architecture Decisions
#   even if they're not anchored to the exact file you're editing

DRAFT → ACTIVE          (rule/human-extracted, passes validation)
DRAFT → REVIEW_REQUIRED (AI-extracted — always requires human approval)
ACTIVE → DRIFTED        (anchored code changed)
DRIFTED → REFRESHING    (refresh triggered)
REFRESHING → ACTIVE     (human approves updated version)