docs: say what Interchange, Corbits packages and Builder own

AGENTS.md

@@ -17,9 +17,11 @@ and the
 enforce most code conventions; run them before saying the tree passes.
 These are the ones no check catches:
 
-- Build on Interchange's agent loop, retries, waits, timeouts, mail, approvals
-  and failure handling rather than reimplementing them, and read the area's
-  Interchange doc first.
+- Build on Interchange for anything it owns (agents, workflows, tools,
+  compaction, mail, approvals, credentials, isolation) rather than
+  reimplementing it, and raise what falls between Interchange, Corbits packages
+  and Builder before building it
+  ([who owns what](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what)).
 - The interface talks to the hub through `@corbits-builder/client`.
 - A change to `vendor/interchange` is its own `(vendor)` commit that also
   updates `vendor/interchange.manifest.json`.

apps/hub/README.md

@@ -34,12 +34,12 @@ from `.env.hub.example`; [setup][setup] covers both. `bun run dev` migrates
 the database and starts the hub with the interface, and `bun run start` runs
 the hub alone. `bun run lint`, `bun run format:check`, `bun run typecheck`
 and `bun run test` check it. The
-[Interchange docs map][interchange-docs] lists the Interchange doc for each
-area; read it before building on one.
+[ownership notes][interchange-docs] say what Interchange, Corbits packages
+and the hub each own.
 
 [workflows]: https://github.com/corbitsdev/corbits-builder/tree/main/workflows
 [schemas]: https://github.com/corbitsdev/corbits-builder/tree/main/packages/schemas
 [client]: https://github.com/corbitsdev/corbits-builder/tree/main/packages/client
 [web]: https://github.com/corbitsdev/corbits-builder/tree/main/apps/web
 [setup]: https://github.com/corbitsdev/corbits-builder/blob/main/CONTRIBUTING.md#setup
-[interchange-docs]: https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#interchange-docs-map
+[interchange-docs]: https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what

docs/DEV.md

@@ -32,8 +32,8 @@ The roles:
 Each role runs on the tier its profile assigns
 ([apps/hub/src/config/models.ts](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/config/models.ts)), so any
 connected provider can run any role. The project's conventions are in
-[AGENTS.md](https://github.com/corbitsdev/corbits-builder/blob/main/AGENTS.md), and the Interchange doc for each area in
-[IMPLEMENTATION.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#interchange-docs-map).
+[AGENTS.md](https://github.com/corbitsdev/corbits-builder/blob/main/AGENTS.md), and what Interchange, Corbits packages and Builder each own in
+[IMPLEMENTATION.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what).
 
 ## Model profile choice
 

docs/IMPLEMENTATION.md

@@ -66,8 +66,8 @@ Skills are packed into the bundle at build time with a Bun macro.
 
 ### Hub tools
 
-The tools agents call are tool packages that reach the hub's API with the
-run's own credential:
+The tools agents call live in the hub and reach the hub's API with the run's
+own credential:
 
 - documents: `read_artifact`, `write_artifact`
   ([apps/hub/src/artifacts/tools.ts](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/artifacts/tools.ts));
@@ -83,6 +83,10 @@ run's own credential:
   installs, app status, browser)
   ([apps/hub/src/builds/](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/builds)).
 
+Builder's tool packages (`tools-*`) follow Interchange's tool-package
+convention (`vendor/interchange/packages/agent/CONVENTIONS.md`), and keep each
+tool's logic a plain function so a workflow action can call it directly.
+
 The coder's browser tools are Playwright's MCP server inside its sandbox,
 limited to loopback; its web search is Exa's MCP server
 ([apps/hub/src/config/mcp.ts](https://github.com/corbitsdev/corbits-builder/blob/main/apps/hub/src/config/mcp.ts)).
@@ -173,27 +177,29 @@ updates
 [vendor/interchange.manifest.json](https://github.com/corbitsdev/corbits-builder/blob/main/vendor/interchange.manifest.json).
 `bun run vendor:verify` fails on any unrecorded change.
 
-## Interchange docs map
-
-Read the doc for an area before changing code in it. All are under
-[vendor/interchange/docs/](https://github.com/corbitsdev/corbits-builder/blob/main/vendor/interchange/docs).
-
-| Area                                                 | Doc                                                    |
-| ---------------------------------------------------- | ------------------------------------------------------ |
-| Concepts: definitions, principals, offerings         | `ARCHITECTURE.md`, `IMPLEMENTATION.md`                 |
-| Definitions, triggers, gates, child workflows, loops | `WORKFLOW_AUTHORING.md`                                |
-| Warm agents, step lifecycle, mail drain, cancel      | `unified-execution-host-design.md`                     |
-| Sidecar, workflow child, harness                     | `HARNESS_DESIGN.md`                                    |
-| Inference turns, tool execution, doom loop           | `INFERENCE.md`                                         |
-| Mail transport and admission                         | `MESSAGE.md`, `INBOUND_MAIL_POLICY.md`                 |
-| Approvals, grants, credentials, definition hashes    | `AUTH.md`, `CREDENTIALS.md`                            |
-| Git repositories and tokens                          | `GIT_ACCESS.md`                                        |
-| Lifetimes, cancellation, drain, placement            | `workflow-lifecycle-policy.md`, `SIDECAR_PLACEMENT.md` |
-| Routes                                               | `ROUTES.md` (`API.md` is generated; never edit it)     |
-| Publishing the `@intx/*` packages                    | `PUBLISHING.md`                                        |
-
-A vendor design marked as not yet built is not a capability; confirm the code
-exists in `vendor/interchange` before relying on it.
+## Who owns what
+
+Builder sits on two sets of packages it does not own. Use theirs before
+writing anything of its kind.
+
+- **Interchange** (`@intx/*`) owns running agents: workflows, triggers and
+  gates, the agent loop, tools and tool packages, directors and compaction,
+  inference providers, mail, approvals, grants and credentials, sidecars and
+  isolation, lifetimes and cancellation. Its docs are under
+  [vendor/interchange/docs/](https://github.com/corbitsdev/corbits-builder/blob/main/vendor/interchange/docs),
+  and each package documents itself in `vendor/interchange/packages/<name>/`.
+  A vendor design marked as not yet built is not a capability; confirm the
+  code exists before relying on it.
+- **Corbits packages** (`@corbits/*`) are shared across Corbits products:
+  document storage (`artifacts`), the interface kit (`react-ui`), provider
+  adapters and logins, MCP and agent tokens.
+- **Builder** owns the product on top: projects and their documents, the
+  hub's own routes and tenant state, the role workflows, prompts and skills,
+  its tool packages, product configuration and the interface.
+
+When a change needs something that none of them clearly owns, or that one of
+the first two almost covers, raise it before building: it may belong upstream,
+as a deliberate vendor change, or in a Corbits package.
 
 `@intx/*` packages come from npm where a published version serves. A package
 is vendored only when Builder patches it or needs Interchange's main past the