@wardby/cli 0.5.3 → 0.7.0

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.

package/docs/knowledge/overview-core.md

@@ -0,0 +1,72 @@
+---
+type: overview
+title: Run admission and execution
+description: Dispatch persists admitted work before executors drive native or coding runs and recovery settles orphans.
+tags: [execution, budgets, scheduling]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:13.475Z }
+sources:
+  - id: schedule
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/scheduler.ts#L55-L82
+  - id: dispatch
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/dispatch.ts#L634-L684
+  - id: engine
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/engine-native.ts#L90-L156
+  - id: finish
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/runner.ts#L499-L516
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/core/**"]
+  citations:
+    - id: schedule
+      repo: github:wardby/wardby
+      path: src/core/scheduler.ts
+      lines: [55, 82]
+      symbol: claimDueRun
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:73b642e5042e6553e4585eed6577d243f772826f7cf84a63a3b57a85d28318f5
+    - id: dispatch
+      repo: github:wardby/wardby
+      path: src/core/dispatch.ts
+      lines: [634, 684]
+      symbol: dispatchRun
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:2e9f0d8d431b6e7d2571f0126a39763be2f87f8ff2f0147a17c7fb69f144054e
+    - id: engine
+      repo: github:wardby/wardby
+      path: src/core/engine-native.ts
+      lines: [90, 156]
+      symbol: NativeEngine.run
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:c38a58677db93241b5ddb7ffd85cae0af88d69903f018d47ca6282c9bb402070
+    - id: finish
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [499, 516]
+      symbol: finishRunClaimed
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:258b0ccb1bf328fef95a5e459858eb3f02ecc3d600f6ff4a7aae562a6416936c
+  confidence: high
+---
+
+Core coordinates admission, run state, native execution, budgets, delegation and event-driven work. The scheduler uses the same dispatch path as other triggers; its due-window update participates in run creation.[^schedule][^dispatch]
+
+A run proceeds through these steps:
+
+1. A schedule, management call or event selects an agent and calls dispatch. Dispatch reads external declarations before persistence, then re-reads the agent inside the transaction.
+2. Dispatch records the run and execution snapshot. Coding admission resolves its reservation and profile; the native runner loads its effective execution context.
+3. The executor routes work to a native engine, isolated native worker or coding job. The native engine estimates input with tool definitions, checks budget before a model call, streams usage and invokes attached tools.
+4. Completion conditionally changes an active run and reads back the persisted result. Reconciliation handles abandoned managed executions and downstream status cleanup.[^dispatch][^engine][^finish]
+
+Core orchestrates Run, delegation edges, budget reservations and integration state in [Prisma](overview-prisma.md). It receives [provider interfaces](overview-providers.md), exposes operations through [MCP](overview-mcp.md), and hands isolated execution to [native isolation](overview-sandbox.md) or [coding workers](overview-coding.md). See [runtime architecture](../architecture-runtime.md) for the process model.
+
+**What to do:** consult [schedule claims](schedule-claim-transaction.md), [delegation admission](delegation-admission-slots.md), [terminal-state ownership](terminal-run-first-writer.md) and [pricing races](run-pricing-first-writer.md) before changing admission or resume paths.
+
+[^schedule]: src/core/scheduler.ts, lines 55-82.
+
+[^dispatch]: src/core/dispatch.ts, lines 634-684.
+
+[^engine]: src/core/engine-native.ts, lines 90-156.
+
+[^finish]: src/core/runner.ts, lines 499-516.

package/docs/knowledge/overview-deploy.md

@@ -0,0 +1,83 @@
+---
+type: overview
+title: Deployment topology and infrastructure
+description: Terraform, Compose and Kubernetes assets connect trusted services to isolated workers and durable storage.
+tags: [deployment, infrastructure, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:23:52.509Z }
+sources:
+  - id: compose
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/deploy/production/compose.yml#L34-L47
+  - id: lifecycle
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/deploy/production/compose.yml#L71-L110
+  - id: gke
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/deploy/gke/cluster.tf#L16-L47
+  - id: eks
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/deploy/aws/cluster.tf#L30-L64
+  - id: network
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/deploy/kind-coding/manifests/base/default-deny.yaml#L1-L13
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["deploy/**"]
+  citations:
+    - id: compose
+      repo: github:wardby/wardby
+      path: deploy/production/compose.yml
+      lines: [34, 47]
+      symbol: services.mcp
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:16c6106c64fb7258e4e5109435f63e1ba9c8c89d770169610dcf137e9a1c973b
+    - id: lifecycle
+      repo: github:wardby/wardby
+      path: deploy/production/compose.yml
+      lines: [71, 110]
+      symbol: services.scheduler / services.migrate
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:52c2fde67bc922bfab91a1cba555c4145cb5adc3ce66001cd64c85df71a88311
+    - id: gke
+      repo: github:wardby/wardby
+      path: deploy/gke/cluster.tf
+      lines: [16, 47]
+      symbol: google_container_cluster.runs
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:954c2c77aa5346317df383e5283a7a3727a03ce275f87e61d6e15659d40a91ec
+    - id: eks
+      repo: github:wardby/wardby
+      path: deploy/aws/cluster.tf
+      lines: [30, 64]
+      symbol: aws_eks_cluster.main
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:df66bf2b8dac435db26e67d6f9777d60e98c949c3d0842c591450ee904b9ea56
+    - id: network
+      repo: github:wardby/wardby
+      path: deploy/kind-coding/manifests/base/default-deny.yaml
+      lines: [1, 13]
+      symbol: default-deny-all
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:7eabaec3b06d0df67886d9c34099a1b7138d1d48a9f8ee53a4d93ba97f9fcf28
+  confidence: high
+---
+
+Deployment assets materialize process and isolation boundaries: runtime and migration images, local and production Compose topologies, Kubernetes bases and overlays, cloud Terraform modules and supporting scripts. The production Compose reference separates edge, MCP, scheduler and migration services; database lifecycle is external to that topology.[^compose][^lifecycle]
+
+Deployment connects the system through these steps:
+
+1. Operators supply infrastructure variables, images and environment configuration. Terraform modules define cloud resources, including the Autopilot cluster on GKE and the EKS cluster on AWS.
+2. The migration entry point prepares the database before runtime services depend on its schema.
+3. MCP serves management requests; scheduler execution runs separately in the Compose reference.
+4. Kubernetes worker namespaces start under default-deny policy. Additional policies and launcher-created resources permit the connections required by worker execution.[^gke][^eks][^lifecycle][^network]
+
+The area owns infrastructure definitions, service accounts, network policy, resource envelopes and deployment wiring. [Configuration](overview-config.md) interprets supplied settings; [providers](overview-providers.md) launch jobs and use cloud identities; [coding workers](overview-coding.md), [native workers](overview-sandbox.md) and the [proxy](overview-coding-proxy.md) depend on the resulting isolation. [Prisma](overview-prisma.md) owns database definitions.
+
+**What to do:** use [deployment targets](../../deploy/README.md), the [production reference](../../deploy/production/README.md) and each cloud module's guide for operational steps. Follow [CLAUDE.md, Deployment](../../CLAUDE.md#deployment-deploy--strict). Preserve database permissions needed for [proxy settlement](proxy-settlement-projections.md) when changing service identities.
+
+[^compose]: deploy/production/compose.yml, lines 34-47.
+
+[^lifecycle]: deploy/production/compose.yml, lines 71-110.
+
+[^gke]: deploy/gke/cluster.tf, lines 16-47.
+
+[^eks]: deploy/aws/cluster.tf, lines 30-64.
+
+[^network]: deploy/kind-coding/manifests/base/default-deny.yaml, lines 1-13.

package/docs/knowledge/overview-mcp.md

@@ -0,0 +1,61 @@
+---
+type: overview
+title: MCP management and authorization
+description: Transport identity becomes scoped management calls over owned resources and explicit grants.
+tags: [mcp, access, auth]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:21:57.208Z }
+sources:
+  - id: composition
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/mcp/index.ts#L109-L167
+  - id: dispatch
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/mcp/server.ts#L256-L276
+  - id: access
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/mcp/auth/access.ts#L47-L70
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/mcp/**"]
+  citations:
+    - id: composition
+      repo: github:wardby/wardby
+      path: src/mcp/index.ts
+      lines: [109, 167]
+      symbol: localOperatorContext / registerAllTools
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:6aa95fcc8cdc1954cd86a19e435870c3b23f5c4f0ec6d003839181c5e67c50cf
+    - id: dispatch
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [256, 276]
+      symbol: factory
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:4fe5d3d2e93961fb1d044450ab050dcfe7429a5f7fc588af677dc710c05ae222
+    - id: access
+      repo: github:wardby/wardby
+      path: src/mcp/auth/access.ts
+      lines: [47, 70]
+      symbol: assertAgentAccess / requireAgentAccess
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:04c8d3accf60339956706f501fbf628ae620e8f368bd93c20825f6ef4f915cbb
+  confidence: high
+---
+
+MCP is the management boundary for agents, bindings, budgets, tools, secrets, schedules and run inspection. Its composition root registers the tool modules and supplies provider and database context. Stdio uses a fixed local operator identity; HTTP calls resolve authenticated context at dispatch.[^composition][^dispatch]
+
+A management call proceeds through these steps:
+
+1. The transport establishes identity and the server resolves a request context.
+2. The registration wrapper requires the tool's OAuth scopes and maps database errors before they reach the client.
+3. The handler checks resource access separately from scopes. Agent access hides unreadable resources and distinguishes insufficient access on readable ones.
+4. Mutations persist definitions and grants; execution requests enter [core dispatch](overview-core.md), while MCP tasks project the run's progress and result.[^dispatch][^access]
+
+The area owns request context, tool registration and task presentation; durable principals, grants and task rows live in [Prisma](overview-prisma.md). Authentication adapters come from [provider seams](overview-providers.md), and transport settings come from [configuration](overview-config.md).
+
+**What to do:** preserve independent scope and resource checks. Read the area's contracts on [transactional authorization](transactional-agent-authorization.md), [schema conversion](mcp-schema-module-boundary.md), [HTTP prompt discovery](mcp-http-prompt-discovery.md), [task cancellation](mcp-cancelled-task-precedence.md) and [secret-entry replicas](secret-entry-replica-contract.md). Operator setup belongs in [identity provider guidance](../getting-started-identity-provider.md).
+
+[^composition]: src/mcp/index.ts, lines 109-167.
+
+[^dispatch]: src/mcp/server.ts, lines 256-276.
+
+[^access]: src/mcp/auth/access.ts, lines 47-70.