Index and query

Layer 0 is offline and deterministic. Indexing scans your corpus; querying never re-scans and never calls a model.

Index

ak-docs index
ak-docs index --watch   # rebuild on doc changes

Outputs (defaults):

After ownership or corpus changes, always re-index (or gate in CI will fail).

Query ownership

ak-docs query package <id> --agent
ak-docs query ownership <id> --agent
ak-docs query package <id> --text      # human-readable

--agent returns validated AgentHandoff JSON:

{
  "startHere": "docs/for-agents/packages/auth.md",
  "editRoots": ["packages/auth"],
  "checks": ["pnpm test --filter auth"],
  "humanDoc": "docs/guides/auth.md"
}

Use this before an agent edits code. The model should not invent ownership from the full monorepo dump.

Search and ask (local)

ak-docs list packages --text
ak-docs ask "where is authentication?"

ask stays on the deterministic plane when a known match exists. Only unresolved questions should escalate to optional backend/RAG (see Chat and RAG).

Agent workflow

resolve ownership  →  read startHere  →  edit only editRoots  →  run checks

1. ak-docs query ownership <module> --agent
2. Open startHere / readBeforeEditing
3. Edit paths under editRoots only
4. Run every command in checks
5. Promote durable learnings via memory pipeline when ready

Related

• Install and run
• For agents
• MCP
• AgentHandoff schema
• CLI reference