# AgentsKitOS — Documentation for Agents

This directory exists so the in-OS copilot has reliable context when
indexing the workspace knowledge base. The folder structure mirrors the
shipped package + screen layout so RAG retrieval surfaces the right
chunk for the right task.

## Layout

```
docs/for-agents/
  packages/            # one markdown per packages/os-* package
    os-core.md
    os-headless.md
    …
  screens/             # one markdown per desktop screen
    flows.md
    runs.md
    …
  flows/               # canonical workflow recipes (14; each maps a human guide)
    prd-to-pr.md
    eval-suite.md
    …
  components/          # shared desktop form/copilot frames (6)
    catalog-combobox.md
    …
  contracts/           # JSON-RPC method reference, indexed by name
```

## Conventions

For workspace-wide code conventions (file size targets, function size targets, sub-path layout after RFC-0017, navigation rules), see [`conventions.md`](./conventions.md). Read this first if you're touching any package.

For monorepo-maintenance work (CI/script cleanup, cross-cutting package
ownership, stale docs, or adding packages), see
[`ecosystem-maintenance.md`](./ecosystem-maintenance.md).

Every package doc has the same six sections so the copilot can extract
predictable answers:

1. **Purpose** — one-paragraph what the package does.
2. **Public exports** — entry points + key types.
3. **Wired stores** — persistence dependencies.
4. **Calls** — JSON-RPC methods the package implements.
5. **Calls** — methods the package consumes.
6. **Common questions** — recipe-shaped Q&A pairs the copilot can quote.

Screen docs are shorter (four sections when a human guide exists): human
guide (optional), purpose, wired methods, edge cases. Flow recipes and
component docs follow the same pattern.

Human-guide mappings consumed by `pnpm docs:internal:query`:

| Mapping file | Covers |
|---|---|
| `scripts/lib/human-screen-docs.mjs` | Desktop + admin screen ids → MDX / operator README |
| `scripts/lib/human-flow-docs.mjs` | 14 flow recipes → MDX / enterprise guides |
| `scripts/lib/human-component-docs.mjs` | 6 shared components → owner-screen MDX |
| `scripts/sync-human-guide-links.mjs` | Adds resolvable relative links under `## Human guide` |

After adding a screen, flow, or component doc, run
`pnpm docs:sync-human-guides` and `pnpm check:human-guide-links` (also in `check:hygiene`).

## Indexing

This corpus is **not** indexed into the assistant automatically at workspace
creation. Two paths feed the in-OS copilot:

1. **Contract catalog (always on).** `packages/os-headless/src/copilot-bootstrap.ts`
   builds `llms.txt` from `@agentskit/os-contracts` and injects a truncated
   `INDEX.md` link summary into the system prompt via
   `for-agents-doc-summary.ts`.
2. **RAG folder sources (operator opt-in).** `prod.seed.*` handlers in
   `packages/os-headless/src/transport/handlers/prod-seed-handlers.ts` register
   four ledgered folder sources when you run
   `agentskit-os prod seed --target assistant-knowledge --apply`, then rebuild
   each source with `agentskit-os knowledge rebuild <source-id>`:

   | Source id | Path |
   |---|---|
   | `assistant-knowledge-for-agents` | `docs/for-agents` |
   | `assistant-knowledge-user-docs` | `apps/web/content/docs` |
   | `assistant-knowledge-demo-docs` | `docs/demo` |
   | `assistant-knowledge-runbooks` | `docs/runbooks` |

   The chunker is markdown-aware so each section becomes its own retrieval
   target. Full operator steps: [`docs/demo-runbook.md`](../demo-runbook.md)
   (assistant-knowledge section).

## Finding docs (agents)

| Need | Command |
|---|---|
| Search any doc, package, screen, or flow | `pnpm docs:internal:query search <term> --agent` |
| Desktop or admin screen guide | `pnpm docs:internal:query screen <id> --agent` |
| Workflow recipe (+ human doc when mapped) | `pnpm docs:internal:query flow <id> --agent` |
| Shared desktop component | `pnpm docs:internal:query component <id> --agent` |
| Package ownership + checks | `pnpm docs:internal:query ownership <pkg> --agent` |
| Curated reading path | `pnpm docs:internal:query intent find-documentation-for-agents-or-humans` |
| Regenerate machine index | `pnpm docs:internal` |
| Validate doc drift gates | `pnpm check:knowledge-map && pnpm check:contracts-doc && pnpm check:doc-code-accuracy` |