@wardby/cli 0.6.0 → 0.7.0

package/docs/knowledge/http-dispatcher-bootstrap.md

@@ -0,0 +1,61 @@
+---
+type: invariant
+title: HTTP compatibility depends on bootstrap order
+description: A Kubernetes client import can change built-in fetch behavior even when jobs use Docker.
+tags: [bootstrap, http, providers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: compatibility
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/http-runtime.ts#L5-L28
+  - id: install
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/http-runtime.ts#L92-L109
+  - id: bootstrap
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/env.ts#L11-L27
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects:
+    [
+      "src/env.ts",
+      "src/core/http-runtime.ts",
+      "src/providers/executor/composition.ts",
+      "src/cli.ts",
+      "src/coding-proxy/main.ts",
+    ]
+  citations:
+    - id: compatibility
+      repo: github:wardby/wardby
+      path: src/core/http-runtime.ts
+      lines: [5, 28]
+      symbol: HTTP dispatcher compatibility
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:de45288094aaa10edabef6a2d28ee308536acda9d0a4b9cedb84794c6b4ee72d
+    - id: install
+      repo: github:wardby/wardby
+      path: src/core/http-runtime.ts
+      lines: [92, 109]
+      symbol: installHttpRuntime
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:9799d701991e03e908d4a357cad85121fe8bcd147259d03be6e1c95345a0471c
+    - id: bootstrap
+      repo: github:wardby/wardby
+      path: src/env.ts
+      lines: [11, 27]
+      symbol: bootstrap imports
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:71c46404eb01aceb2d30a7617bff1df60437a1ded819b7016fd9d8bc08a08363
+  confidence: high
+---
+
+Importing the Kubernetes client loads a different Undici generation, whose compatibility dispatcher can expose HTTP/2 headers in a shape Node's built-in fetch does not understand. The result is loss of response headers, affecting decompression and redirects across unrelated adapters. Executor composition imports that client even outside Kubernetes deployments.[^compatibility]
+
+The shared environment bootstrap installs an HTTP/1-only dispatcher before other runtime work. Its installed marker makes repeated calls a no-op; it does not continuously enforce which dispatcher remains installed.[^install][^bootstrap]
+
+**What to do:** keep the environment import first in runtime entry points and do not replace the global dispatcher later without preserving compatibility. Keep this bootstrap in the control-plane dependency tree; isolated coding-worker images have their own dependencies. See [configuration](overview-config.md) for the startup flow.
+
+[^compatibility]: src/core/http-runtime.ts, lines 5-28.
+
+[^install]: src/core/http-runtime.ts, lines 92-109.
+
+[^bootstrap]: src/env.ts, lines 11-27.

package/docs/knowledge/import-rename-target.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Import rename targets must be checked before creation
+description: Renaming a colliding entity onto another existing name would silently adopt that entity through idempotent creation.
+tags: [import, ownership, identity]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: rename
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/preflight.ts#L38-L61
+  - id: abort
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/index.ts#L98-L106
+  - id: upsert
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/create.ts#L134-L155
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/import/**"]
+  citations:
+    - id: rename
+      repo: github:wardby/wardby
+      path: src/import/preflight.ts
+      lines: [38, 61]
+      symbol: resolveCollision
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:c9d7a0099b2a8da51423969af1f92d314287f0ae32fb708ebec731b2796fbee5
+    - id: abort
+      repo: github:wardby/wardby
+      path: src/import/index.ts
+      lines: [98, 106]
+      symbol: runImport
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:e7463bf861fefd8157eaa21c951c8f635fe2b41d25f80e4d77c500eae82021a4
+    - id: upsert
+      repo: github:wardby/wardby
+      path: src/import/create.ts
+      lines: [134, 155]
+      symbol: createFromBundle
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:010d97c925923a101c0cedb4d148e39f6ba70aec7b0f4e1d2355fddb4855e6a8
+  confidence: high
+---
+
+Preflight treats an occupied prefixed rename target as fatal even under the rename policy. The orchestrator returns before creation on fatal collisions; creation later upserts agents with an empty update branch.[^rename][^abort][^upsert]
+
+**Why:** a free-looking rename that lands on an existing name can return the existing agent without changing it, after which import attachments would target that identity. Preserve target validation before idempotent creation; it is an identity boundary, not just nicer collision reporting.
+
+[^rename]: src/import/preflight.ts, lines 38-61.
+
+[^abort]: src/import/index.ts, lines 98-106.
+
+[^upsert]: src/import/create.ts, lines 134-155.

package/docs/knowledge/index.md

@@ -0,0 +1,57 @@
+# Architecture knowledge
+
+## Overviews
+
+- [MCP management and authorization](overview-mcp.md) — Transport identity becomes scoped management calls over owned resources and explicit grants.
+- [Configuration and process bootstrap](overview-config.md) — Environment loading precedes typed feature settings and provider composition.
+- [Run admission and execution](overview-core.md) — Dispatch persists admitted work before executors drive native or coding runs and recovery settles orphans.
+- [Coding inputs and isolated workers](overview-coding.md) — Shared protocols connect trusted run preparation to Codex or Claude Code workers and host finalization.
+- [Coding proxy and package mediation](overview-coding-proxy.md) — Run capabilities gate model reservations, package policy and optional dependency snapshots.
+- [Native tool and worker isolation](overview-sandbox.md) — QuickJS evaluates user tools while a run-bound gateway retains privileged effects and native worker authority.
+- [Provider composition and routing](overview-providers.md) — Interfaces separate orchestration from concrete model, execution, identity, persistence and source-control adapters.
+- [Durable data and migration boundaries](overview-prisma.md) — Relational definitions and migrations persist identity, run lifecycle, accounting and integration state.
+- [Deployment topology and infrastructure](overview-deploy.md) — Terraform, Compose and Kubernetes assets connect trusted services to isolated workers and durable storage.
+- [CLI bootstrap and bundle import](overview-cli.md) — Command entry points assemble local installations, invoke runtime services and reconcile imported resources.
+- [Viewer, observability and knowledge tooling](overview-surfaces.md) — Read projections, metrics and cited knowledge expose runtime state and architecture without owning execution.
+
+## Invariants
+
+- [HTTP compatibility depends on bootstrap order](http-dispatcher-bootstrap.md) — A Kubernetes client import can change built-in fetch behavior even when jobs use Docker.
+- [Pricing races must use the persisted winner](run-pricing-first-writer.md) — Concurrent native attempts must reuse the catalog terms that won the conditional pricing write.
+- [Private datastore wrappers must reject shared methods](private-datastore-shared-boundary.md) — Prefix restrictions on private keys cannot authorize the provider shared-store methods.
+- [Failed workspace fills must remain untrusted](workspace-staging-failure.md) — Collection failure must not expose a partially materialized worker tree to validation or trusted replacement.
+- [Import rename targets must be checked before creation](import-rename-target.md) — Renaming a colliding entity onto another existing name would silently adopt that entity through idempotent creation.
+- [Viewer notifications must not abort authoritative writes](viewer-notify-write-isolation.md) — The viewer trigger contains notification errors so event delivery cannot fail run persistence.
+- [Blob absence must distinguish missing infrastructure](blob-not-found-semantics.md) — Mapping a storage outage to not_found can delete valid dependency snapshot metadata.
+- [Warm input publication must refuse replacement](warm-input-publication.md) — Atomic visibility alone is insufficient when one warm worker may receive its capability only once.
+- [Proxy usage projections must not govern settlement](proxy-settlement-projections.md) — Run totals are rebuilt from settled requests while per-model reporting failures are isolated by a savepoint.
+- [Untrusted file bounds belong to the open descriptor](bounded-file-descriptor.md) — Checking a path before reading it leaves file substitution and growth races across worker boundaries.
+- [Agent authorization must share the mutation transaction](transactional-agent-authorization.md) — Using the default access client inside a transaction disconnects grant reads from mutation isolation.
+- [Budget-waiting delegations retain admission slots](delegation-admission-slots.md) — Releasing the delegation gate during a budget wait must preserve duplicate-child and delegation-limit accounting.
+- [Schedule deduplication belongs to the transaction](schedule-claim-transaction.md) — A scheduler lease cannot replace the atomic schedule-window claim and run creation.
+- [Terminal run state belongs to the first writer](terminal-run-first-writer.md) — Run completion must conditionally write pending or running rows and read back the persisted winner.
+- [Task cancellation takes precedence over run status](mcp-cancelled-task-precedence.md) — A cancelled task remains cancelled even if its underlying run finishes with a different terminal outcome.
+- [Secret entry replicas must share token verification](secret-entry-replica-contract.md) — A shared outcome database cannot complete a secret-entry round trip when replicas use independent signing keys.
+
+## Decisions
+
+- [MCP schemas cross the SDK boundary as JSON](mcp-schema-module-boundary.md) — Using the SDK schema converter avoids incompatible Zod instances at tool registration.
+
+## Pitfalls
+
+- [Nullable tool ownership leaves a uniqueness gap](nullable-tool-uniqueness.md) — The owner-and-name unique index does not deduplicate ownerless tools in PostgreSQL.
+- [HTTP prompt discovery cannot use per-call identity](mcp-http-prompt-discovery.md) — The HTTP factory exposes everyone-readable agent prompts rather than the authenticated caller’s full agent set.
+
+## Coverage
+
+1. src/mcp/ (tools, auth, access, grants): covered 2026-10-17 (6 concepts)
+2. src/config/ and env handling: covered 2026-10-17 (2 concepts)
+3. src/core/ runner, scheduler, dispatch, budgets, delegation: covered 2026-10-17 (7 concepts)
+4. src/coding/ and src/coding-worker/, src/claude-*/ (coding runs, workers): covered 2026-10-17 (2 concepts)
+5. src/providers/coding-proxy/ (proxy, package registry): covered 2026-10-17 (3 concepts)
+6. src/sandbox/ and src/native-worker/ (native sandbox, isolation): covered 2026-10-17 (3 concepts)
+7. src/providers/ other seams (LLM, auth, storage, VCS, executors): covered 2026-10-17 (7 concepts)
+8. prisma/ (schema, migrations): covered 2026-10-17 (3 concepts)
+9. deploy/ (Terraform, Kubernetes, scripts): covered 2026-10-17 (2 concepts)
+10. src/quickstart/, src/import/, the CLI files in src/: covered 2026-10-17 (4 concepts)
+11. src/viewer/, src/observability/, src/knowledge/, src/tools/: covered 2026-10-17 (2 concepts)

package/docs/knowledge/log.md

@@ -0,0 +1,9 @@
+# Knowledge changes
+
+- 2026-10-15: Created the bundle index; added invariants for transactional agent authorization, delegation admission slots, transactional schedule claims, and first-writer terminal run state.
+
+- 2026-10-15: Added the coverage map, retaining existing MCP and core coverage; completed MCP and config discovery, added schema-boundary, HTTP prompt-discovery, task-cancellation and secret-entry replica contracts, and re-anchored three moved delegation citations. Later uncovered areas remain for the next coverage run.
+
+- 2026-10-16: Completed coverage discovery for areas 4–11; added descriptor-bound file reads, proxy settlement projections, warm input publication, blob absence semantics, nullable tool uniqueness, viewer notification isolation, and import rename-target contracts. Re-anchored eight moved citations across delegation admission, schedule claims, terminal run state, and transactional authorization; existing claims remain current.
+
+- 2026-10-17: Added one overview for each of the eleven coverage areas and completed discovery across all areas; added HTTP dispatcher bootstrap, first-writer pricing, private/shared datastore separation and failed workspace staging contracts. Existing citations and claims remain unchanged; refreshed coverage dates and counts, including overviews and cross-area concepts.

package/docs/knowledge/mcp-cancelled-task-precedence.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Task cancellation takes precedence over run status
+description: A cancelled task remains cancelled even if its underlying run finishes with a different terminal outcome.
+tags: [mcp, execution, cancellation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: read
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/tasks/manager.ts#L108-L144
+  - id: cancel
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/tasks/manager.ts#L155-L171
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/tasks/**", "src/mcp/tools/trigger.ts"]
+  citations:
+    - id: read
+      repo: github:wardby/wardby
+      path: src/mcp/tasks/manager.ts
+      lines: [108, 144]
+      symbol: getTask
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:57fcf902067b811f63548e01e7008a5dfadd4504156904dc96ad26c68c323ea8
+    - id: cancel
+      repo: github:wardby/wardby
+      path: src/mcp/tasks/manager.ts
+      lines: [155, 171]
+      symbol: cancelTask
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:68e640003a1eb74a96bab385cde0c8a658df6a2902ca10cb76a39d35ad5f60b7
+  confidence: high
+---
+
+Ordinary task reads derive status from the run, but first return a persisted task cancellation without reading that run. Cancellation checks that the run is active, invokes the stop hook, then stamps the task cancelled; it does not stamp tasks whose runs were already terminal.[^read][^cancel]
+
+**Why:** the run can finish between the active-state check and cancellation. Preserve the task-level precedence rather than synchronizing its status back from the run: cancellation of the task and the authoritative run outcome are separate facts. [Native sandbox](../native-sandbox.md) describes stopping execution; this concept records the task projection consequence.
+
+[^read]: src/mcp/tasks/manager.ts, lines 108-144.
+
+[^cancel]: src/mcp/tasks/manager.ts, lines 155-171.

package/docs/knowledge/mcp-http-prompt-discovery.md

@@ -0,0 +1,41 @@
+---
+type: pitfall
+title: HTTP prompt discovery cannot use per-call identity
+description: The HTTP factory exposes everyone-readable agent prompts rather than the authenticated caller’s full agent set.
+tags: [mcp, access, discovery]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: context
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L211-L235
+  - id: prompts
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L300-L332
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/server.ts", "src/mcp/transport/**"]
+  citations:
+    - id: context
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [211, 235]
+      symbol: resolveCtx
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:e44772fb56c6bd94fe80f9a217ad26e1a5a580cd380f363db476fa206d4ba288
+    - id: prompts
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [300, 332]
+      symbol: factory
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:e2b7273522836d35f55b7bf068062a488b1eae0cd47520d35a67f89acd0f731f
+  confidence: high
+---
+
+HTTP identity is resolved from each dispatched call, after the server factory builds the prompt list. The factory therefore registers only agents granted at least read to everyone; stdio can use its already established fixed context. Failure to build this optional list does not prevent tool registration.[^context][^prompts]
+
+**What to do:** do not treat a missing HTTP prompt as proof that the caller lacks agent access, or widen the factory’s query to all agents. Caller-specific discovery needs request identity before prompt registration.
+
+[^context]: src/mcp/server.ts, lines 211-235.
+
+[^prompts]: src/mcp/server.ts, lines 300-332.

package/docs/knowledge/mcp-schema-module-boundary.md

@@ -0,0 +1,41 @@
+---
+type: decision
+title: MCP schemas cross the SDK boundary as JSON
+description: Using the SDK schema converter avoids incompatible Zod instances at tool registration.
+tags: [mcp, schemas, providers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: schema
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L55-L65
+  - id: registration
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L256-L263
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/server.ts", "src/mcp/tools/**"]
+  citations:
+    - id: schema
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [55, 65]
+      symbol: ToolSpec
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:bac668c827f34c5a3c952226092c734f54e2c50d0f66ac55a3c15a369b4cfb1b
+    - id: registration
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [256, 263]
+      symbol: factory
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:6d9cdfe4089e7c9f1be23fb35e8a348407bfc70a2dd611d04875f32ef287f0d3
+  confidence: high
+---
+
+The SDK bundles its own Zod module instance, so matching the package version does not make application Zod shapes compatible with its registration overload. Tool specs carry JSON Schema and registration converts it with the SDK’s own `fromJsonSchema`.[^schema][^registration]
+
+**What to do:** keep schemas crossing this seam as plain JSON; replacing the converter with an application Zod shape can break registration even without a version mismatch.
+
+[^schema]: src/mcp/server.ts, lines 55-65.
+
+[^registration]: src/mcp/server.ts, lines 256-263.

package/docs/knowledge/nullable-tool-uniqueness.md

@@ -0,0 +1,52 @@
+---
+type: pitfall
+title: Nullable tool ownership leaves a uniqueness gap
+description: The owner-and-name unique index does not deduplicate ownerless tools in PostgreSQL.
+tags: [database, tools, ownership]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: index
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/prisma/migrations/20260925030000_tool_name_per_owner/migration.sql#L1-L11
+  - id: import
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/create.ts#L112-L128
+  - id: cli
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/cli.ts#L311-L318
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["prisma/schema.prisma", "prisma/migrations/**", "src/cli.ts", "src/import/create.ts"]
+  citations:
+    - id: index
+      repo: github:wardby/wardby
+      path: prisma/migrations/20260925030000_tool_name_per_owner/migration.sql
+      lines: [1, 11]
+      symbol: Tool_ownerId_name_key
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:d1a29163bd0e6398e8dd99442e8c24d32490d3c85dbc671e1636bd16ac8343f5
+    - id: import
+      repo: github:wardby/wardby
+      path: src/import/create.ts
+      lines: [112, 128]
+      symbol: createFromBundle
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:ad43b75b4bbf957fbf0bffa2003df56bcf120d96261ef7d322101e69f1aaa903
+    - id: cli
+      repo: github:wardby/wardby
+      path: src/cli.ts
+      lines: [311, 318]
+      symbol: toolCreate
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:bec79921d22a9a3264b81b1996624bb967a79acd2884f58659650ceda1db4b08
+  confidence: high
+---
+
+PostgreSQL treats NULL owners as distinct in the compound tool-name index. CLI creation explicitly checks the ownerless namespace, and the importer uses findFirst plus create rather than a nullable compound upsert.[^index][^import][^cli]
+
+**What to do:** preserve owner-scoped lookups, and do not assume the database index arbitrates concurrent ownerless creates. A read-before-create check can still race; any stronger uniqueness guarantee needs database enforcement for the NULL-owner case. For schema changes, see [CLAUDE.md, Database / Prisma](../../CLAUDE.md#database--prisma--strict).
+
+[^index]: prisma/migrations/20260925030000_tool_name_per_owner/migration.sql, lines 1-11.
+
+[^import]: src/import/create.ts, lines 112-128.
+
+[^cli]: src/cli.ts, lines 311-318.

package/docs/knowledge/overview-cli.md

@@ -0,0 +1,74 @@
+---
+type: overview
+title: CLI bootstrap and bundle import
+description: Command entry points assemble local installations, invoke runtime services and reconcile imported resources.
+tags: [cli, quickstart, import]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:23:52.509Z }
+sources:
+  - id: config
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/quickstart/index.ts#L433-L484
+  - id: seed
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/quickstart/index.ts#L484-L507
+  - id: import
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/import/index.ts#L72-L106
+  - id: serve
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/cli.ts#L1013-L1030
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/quickstart/**", "src/import/**", "src/cli*.ts", "src/serve.ts"]
+  citations:
+    - id: config
+      repo: github:wardby/wardby
+      path: src/quickstart/index.ts
+      lines: [433, 484]
+      symbol: quickstartCommand
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:b37adfe4a639a53624a0ce50e771657129e6998d27f655b4f7c40d3f31aa7c8f
+    - id: seed
+      repo: github:wardby/wardby
+      path: src/quickstart/index.ts
+      lines: [484, 507]
+      symbol: quickstartCommand
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:f4cf2db2dd78a46baa7b60419db278165a5784c6b1b644010e4c4784930966b2
+    - id: import
+      repo: github:wardby/wardby
+      path: src/import/index.ts
+      lines: [72, 106]
+      symbol: runImport
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:5c2ae39ee543fad3e0a12717a7358556137a40f1dd6b64a7b8b962daeaf5f57d
+    - id: serve
+      repo: github:wardby/wardby
+      path: src/cli.ts
+      lines: [1013, 1030]
+      symbol: serve
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:b2e4a9d5adf84699138e39a87b134e8eb8bbec07ceaf842e54ba3bcabef18116
+  confidence: high
+---
+
+The CLI is the bootstrap and operations entry point around [MCP](overview-mcp.md) and [core execution](overview-core.md). Quickstart owns project-local configuration and installation state; import converts a neutral bundle into owned definitions and bindings after reconciliation.[^config][^import]
+
+A local installation proceeds through these steps:
+
+1. Quickstart resolves the project directory, reuses saved configuration and chooses provider settings.
+2. It writes the local environment and state, starts PostgreSQL and applies migrations.
+3. It can seed and run a demo, configure coding agents and connect MCP clients. Doctor and lifecycle commands operate on that saved installation.
+4. Runtime commands construct the appropriate process; serve starts the combined runtime and installs shutdown handling.[^config][^seed][^serve]
+
+An import opens the bundle, determines routable models and supported tool globals, checks existing names and capabilities, and renders a reconciliation report. Dry runs and fatal collisions return before creation; approved imports then create resources and attachments.[^import]
+
+This area owns local state files, command orchestration and import reports. Durable resources belong to [Prisma](overview-prisma.md); [configuration](overview-config.md) establishes environment precedence, [providers](overview-providers.md) supply adapters, and [deployment assets](overview-deploy.md) supply local service topologies.
+
+**What to do:** preserve [rename-target validation](import-rename-target.md) and [ownerless tool uniqueness checks](nullable-tool-uniqueness.md) when changing creation. See [getting started](../getting-started.md) for operator setup.
+
+[^config]: src/quickstart/index.ts, lines 433-484.
+
+[^seed]: src/quickstart/index.ts, lines 484-507.
+
+[^import]: src/import/index.ts, lines 72-106.
+
+[^serve]: src/cli.ts, lines 1013-1030.

package/docs/knowledge/overview-coding-proxy.md

@@ -0,0 +1,72 @@
+---
+type: overview
+title: Coding proxy and package mediation
+description: Run capabilities gate model reservations, package policy and optional dependency snapshots.
+tags: [proxy, packages, budgets]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:32.722Z }
+sources:
+  - id: runtime
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/coding-proxy/runtime.ts#L83-L159
+  - id: session
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/coding-proxy/proxy.ts#L978-L1020
+  - id: model
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/coding-proxy/proxy.ts#L1041-L1094
+  - id: plan
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/coding-proxy/registry/service.ts#L585-L632
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/providers/coding-proxy/**"]
+  citations:
+    - id: runtime
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/runtime.ts
+      lines: [83, 159]
+      symbol: startConfiguredCodingProxy
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:e0c409bf7f5d1198dc24c3e98979f711519b4b3c0630ad841d87b27db4d11206
+    - id: session
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/proxy.ts
+      lines: [978, 1020]
+      symbol: CodingProxy.createSession
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:976389493738ea51632f2dfbcf503b96f2506aa5105f82942efce825e075fb9e
+    - id: model
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/proxy.ts
+      lines: [1041, 1094]
+      symbol: CodingProxy.execute
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:b439b84431007b244f246836807cbae4b4a075c4bf1a1f618c11877e7d0082b7
+    - id: plan
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/registry/service.ts
+      lines: [585, 632]
+      symbol: RegistryService.planLockfile / runPlan
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:f3a6b41a918c6c88275abf0f72536341483cdcd1d3aceaf8e3b7e4821513413d
+  confidence: high
+---
+
+The coding proxy is the trusted egress and metering boundary for coding workers. Its runtime composes the persistent model ledger, registry service, vulnerability auditing and optional blob-backed dependency cache. Model and registry access use distinct credentials derived for the run.[^runtime][^session]
+
+Requests proceed through these steps:
+
+1. The executor creates a session with a model allowlist, deadline, budget and optional pinned catalog terms. Only hashes of run capabilities are persisted.
+2. A model request authenticates the capability, checks protocol and body shape, verifies the model and reserves an estimated maximum cost before forwarding.
+3. Authoritative provider usage settles the request and rebuilds run totals; uncertain requests retain accounting protection.
+4. Package requests use the registry-only token. Lockfile planning authenticates the live run and holds a bounded plan slot before reading the body; policy and auditing determine which package bytes can be served. Optional dependency snapshots belong to the preparation phase.[^session][^model][^plan]
+
+The area owns model-session and request accounting, registry facts and approvals, fetch records and snapshot metadata in [Prisma](overview-prisma.md). [Coding workers](overview-coding.md) consume its routes; [storage providers](overview-providers.md) hold cache blobs; [deployment](overview-deploy.md) enforces the worker-to-proxy network boundary.
+
+**What to do:** preserve [settlement versus reporting isolation](proxy-settlement-projections.md) and [blob absence semantics](blob-not-found-semantics.md). See [package policy](../coding-packages.md) and [worker isolation](../coding-worker-isolation.md) for operator guidance.
+
+[^runtime]: src/providers/coding-proxy/runtime.ts, lines 83-159.
+
+[^session]: src/providers/coding-proxy/proxy.ts, lines 978-1020.
+
+[^model]: src/providers/coding-proxy/proxy.ts, lines 1041-1094.
+
+[^plan]: src/providers/coding-proxy/registry/service.ts, lines 585-632.

package/docs/knowledge/overview-coding.md

@@ -0,0 +1,72 @@
+---
+type: overview
+title: Coding inputs and isolated workers
+description: Shared protocols connect trusted run preparation to Codex or Claude Code workers and host finalization.
+tags: [coding, workers, protocol]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:32.722Z }
+sources:
+  - id: protocol
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/coding/protocol.ts#L455-L496
+  - id: codex
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/coding-worker/driver.ts#L254-L294
+  - id: claude
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/claude-coding-worker/driver.ts#L190-L230
+  - id: finalize
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/executor/container.ts#L1418-L1456
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/coding/**", "src/coding-worker/**", "src/claude-*/**"]
+  citations:
+    - id: protocol
+      repo: github:wardby/wardby
+      path: src/coding/protocol.ts
+      lines: [455, 496]
+      symbol: CodingTaskInputSchema
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:36844670fcf073f1e0878415464265f3451b71a9cecf461c29c26b8fe7d92070
+    - id: codex
+      repo: github:wardby/wardby
+      path: src/coding-worker/driver.ts
+      lines: [254, 294]
+      symbol: runCodingWorker
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:78250a51b5f468adbc3e4ce1ff44ce90b392b2f888076e509c4b702371378549
+    - id: claude
+      repo: github:wardby/wardby
+      path: src/claude-coding-worker/driver.ts
+      lines: [190, 230]
+      symbol: runClaudeCodingWorker
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:9b1a14069b42a6e00381e6f2ace9cdd8db4b750ab5c0487740dd05e2c1b92a45
+    - id: finalize
+      repo: github:wardby/wardby
+      path: src/providers/executor/container.ts
+      lines: [1418, 1456]
+      symbol: ContainerExecutor.finishTerminal
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:b3cdeb7fcdff43795af9bd3d0c18c02fa29d59c787adc3504a2c60be126d9fbc
+  confidence: high
+---
+
+This area defines bounded coding inputs and outputs, repository profiles and policies, and isolated execution programs. A shared protocol carries the task, model, deadline, budget and permitted run environment; both worker families return structured results for the trusted host to interpret.[^protocol]
+
+A coding run proceeds through these steps:
+
+1. [Core dispatch](overview-core.md) snapshots the coding profile; the [executor provider](overview-providers.md) prepares a workspace and launches the selected worker.
+2. The Codex driver prepares package configuration and optional dependencies before starting its agent. Claude Code prepares dependencies and repository context before constructing its query; command execution is relayed to the separate tool runner.
+3. Model traffic passes through the [coding proxy](overview-coding-proxy.md). Workers produce bounded structured output and workspace changes.
+4. The host materializes the result, normalizes lockfiles, checks cost and repository access again, verifies the run remains active, then asks VCS finalization to publish the permitted outcome.[^codex][^claude][^finalize]
+
+The area owns wire schemas, worker preparation and output artifacts. Durable CodingRun state belongs to [Prisma](overview-prisma.md); job isolation and VCS authority belong to providers, with images and network policy supplied by [deployment modules](overview-deploy.md).
+
+**What to do:** read [descriptor-bound artifact reads](bounded-file-descriptor.md) and [staged workspace replacement](workspace-staging-failure.md) when changing collection. Keep operator details in [coding-agent setup](../coding-agent-setup.md) and [worker isolation](../coding-worker-isolation.md).
+
+[^protocol]: src/coding/protocol.ts, lines 455-496.
+
+[^codex]: src/coding-worker/driver.ts, lines 254-294.
+
+[^claude]: src/claude-coding-worker/driver.ts, lines 190-230.
+
+[^finalize]: src/providers/executor/container.ts, lines 1418-1456.

package/docs/knowledge/overview-config.md

@@ -0,0 +1,60 @@
+---
+type: overview
+title: Configuration and process bootstrap
+description: Environment loading precedes typed feature settings and provider composition.
+tags: [config, environment, bootstrap]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:13.475Z }
+sources:
+  - id: bootstrap
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/env.ts#L11-L27
+  - id: providers
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/config/providers.ts#L74-L87
+  - id: cache
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/config/dependency-cache.ts#L36-L53
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/config/**", "src/env.ts"]
+  citations:
+    - id: bootstrap
+      repo: github:wardby/wardby
+      path: src/env.ts
+      lines: [11, 27]
+      symbol: dotenvFlow.config
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:71c46404eb01aceb2d30a7617bff1df60437a1ded819b7016fd9d8bc08a08363
+    - id: providers
+      repo: github:wardby/wardby
+      path: src/config/providers.ts
+      lines: [74, 87]
+      symbol: loadProviderConfig
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:32457f939e01bc19814b04ef4ed3d7d944416518080247c7d0e1eb318c5cc5f6
+    - id: cache
+      repo: github:wardby/wardby
+      path: src/config/dependency-cache.ts
+      lines: [36, 53]
+      symbol: loadDependencyCacheConfig
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:643c0433fac3665962e6b995781cabf909aa7bc43bd150d62c61bca7b140c564
+  confidence: high
+---
+
+Configuration turns process environment into provider selections and feature settings. Bootstrap first installs the process HTTP runtime, then loads the project-local Wardby environment before the project's own cascade. Existing process variables take precedence.[^bootstrap]
+
+Startup proceeds through these steps:
+
+1. An entry point imports bootstrap before modules consume environment values.
+2. Loaders select provider kinds and parse settings for enabled integrations. The provider selector supplies defaults; feature loaders own additional validation.
+3. Composition roots build adapters using those settings. A feature may remain unavailable without its prerequisite: dependency caching needs both its enable flag and blob-store configuration.[^bootstrap][^providers][^cache]
+
+The area owns configuration shapes and validation, not durable settings or credential storage. [Providers](overview-providers.md) construct adapters; [coding workers](overview-coding.md), [native isolation](overview-sandbox.md) and the [coding proxy](overview-coding-proxy.md) consume their own subsets. [CLI bootstrap](overview-cli.md) writes project-local configuration, and [deployment modules](overview-deploy.md) supply remote process settings.
+
+**What to do:** keep initialization order intact and validate through the relevant loader before starting listeners. The [HTTP dispatcher contract](http-dispatcher-bootstrap.md) explains why bootstrap order affects network correctness even without Kubernetes jobs. See [getting started](../getting-started.md) for operator configuration.
+
+[^bootstrap]: src/env.ts, lines 11-27.
+
+[^providers]: src/config/providers.ts, lines 74-87.
+
+[^cache]: src/config/dependency-cache.ts, lines 36-53.