@wardby/cli 0.6.0 → 0.8.0

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.

package/docs/knowledge/overview-prisma.md

@@ -0,0 +1,72 @@
+---
+type: overview
+title: Durable data and migration boundaries
+description: Relational definitions and migrations persist identity, run lifecycle, accounting and integration state.
+tags: [database, schema, migrations]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:57.805Z }
+sources:
+  - id: run
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/schema.prisma#L327-L379
+  - id: proxy
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/schema.prisma#L807-L845
+  - id: notify
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql#L1-L47
+  - id: package
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/prisma/migrate.config.mjs#L1-L20
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["prisma/**"]
+  citations:
+    - id: run
+      repo: github:wardby/wardby
+      path: prisma/schema.prisma
+      lines: [327, 379]
+      symbol: Run
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:52761459ccb0f62de1ca181d8c506ad51ebfc470b56440eabd80e23c01d0699a
+    - id: proxy
+      repo: github:wardby/wardby
+      path: prisma/schema.prisma
+      lines: [807, 845]
+      symbol: CodingProxySession
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:992812db47e0a461bab6f9527a8e0d8bb9708b0452bbeba1d23169293532d338
+    - id: notify
+      repo: github:wardby/wardby
+      path: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql
+      lines: [1, 47]
+      symbol: wardby_viewer_notify
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:8c16b83ca66d420cd0ccc5824e496625baa8ebc6b1010a0721e4ac36d6419b93
+    - id: package
+      repo: github:wardby/wardby
+      path: prisma/migrate.config.mjs
+      lines: [1, 20]
+      symbol: default migration configuration
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:836356e707ee9b510637dbf067182af05fbb54f548dcdb84f9cbcb8eeeaffb48
+  confidence: high
+---
+
+Prisma defines the durable relational boundary shared by the control plane, executors, gateways and coding proxy. The schema contains agents and attachments, principals and grants, schedules, budgets, runs, accounting ledgers, repository and issue workflow state, authentication state and notification delivery records. Run carries execution ownership, heartbeat and pinned model terms; CodingRun and proxy tables specialize coding execution.[^run][^proxy]
+
+Persistence and consumption proceed through these steps:
+
+1. A deployment or [CLI bootstrap](overview-cli.md) applies migrations using its migration configuration. The packaged configuration resolves the shipped schema and migration directory without importing development-only configuration dependencies.
+2. [Core](overview-core.md) and [MCP](overview-mcp.md) write definitions, ownership and run transitions through transactions.
+3. [Executors and providers](overview-providers.md), the [native gateway](overview-sandbox.md) and [coding proxy](overview-coding-proxy.md) persist their own lifecycle and accounting records linked to runs.
+4. Database triggers publish selected changes to the [viewer](overview-surfaces.md). Notification failures are contained so observation cannot roll back an authoritative write.[^package][^run][^proxy][^notify]
+
+The database owns durable identity, accounting and recovery state; blob contents and worker workspaces live outside it. Runtime database privileges are supplied by [deployment modules](overview-deploy.md).
+
+**What to do:** follow [CLAUDE.md, Database / Prisma](../../CLAUDE.md#database--prisma--strict) for schema work. Review [nullable tool uniqueness](nullable-tool-uniqueness.md) and [viewer notification isolation](viewer-notify-write-isolation.md) for database behavior that the declarative schema alone does not convey.
+
+[^run]: prisma/schema.prisma, lines 327-379.
+
+[^proxy]: prisma/schema.prisma, lines 807-845.
+
+[^notify]: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql, lines 1-47.
+
+[^package]: prisma/migrate.config.mjs, lines 1-20.

package/docs/knowledge/overview-providers.md

@@ -0,0 +1,89 @@
+---
+type: overview
+title: Provider composition and routing
+description: Interfaces separate orchestration from concrete model, execution, identity, persistence and source-control adapters.
+tags: [providers, routing, composition]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:57.805Z }
+sources:
+  - id: registry
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/index.ts#L33-L47
+  - id: execution
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/executor/composition.ts#L87-L126
+  - id: model
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/llm/routing.ts#L67-L79
+  - id: vcs
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/vcs/routing.ts#L26-L53
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects:
+    [
+      "src/providers/index.ts",
+      "src/providers/llm/**",
+      "src/providers/auth/**",
+      "src/providers/storage/**",
+      "src/providers/vcs/**",
+      "src/providers/executor/**",
+      "src/providers/jobs/**",
+      "src/providers/datastore/**",
+      "src/providers/memory/**",
+      "src/providers/engine/**",
+      "src/providers/secrets/**",
+      "src/providers/email/**",
+      "src/providers/review-host/**",
+      "src/providers/issue-tracker/**",
+      "src/providers/chat/**",
+    ]
+  citations:
+    - id: registry
+      repo: github:wardby/wardby
+      path: src/providers/index.ts
+      lines: [33, 47]
+      symbol: ProviderRegistry
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:c78fde4ca7f425d997cece136728d75d49e6c8ada349a77cc4f29c0596e4b9c9
+    - id: execution
+      repo: github:wardby/wardby
+      path: src/providers/executor/composition.ts
+      lines: [87, 126]
+      symbol: buildConfiguredExecutor
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:68bdd107cd1d591a2ac700c253fa8449e7316347e48e23055fca286612685275
+    - id: model
+      repo: github:wardby/wardby
+      path: src/providers/llm/routing.ts
+      lines: [67, 79]
+      symbol: RoutingLlmProvider.entryFor / forRun
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:4b757bc28723803469e6625fb8ba7f9ca6d48cb496b669193d3fa4fb3023d475
+    - id: vcs
+      repo: github:wardby/wardby
+      path: src/providers/vcs/routing.ts
+      lines: [26, 53]
+      symbol: RoutingVcsProvider.target
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:338d5bc2f7ab53f490045d41a6db1639351fc50d958887c77afee4855d46cc6e
+  confidence: high
+---
+
+Provider interfaces are the dependencies passed to [core orchestration](overview-core.md). Adapters implement model access, jobs, execution, identity, secrets, blob storage, datastores, memory, engines and VCS; review-host, issue-tracker and chat registries support external workflows.[^registry]
+
+Composition and execution proceed through these steps:
+
+1. [Configuration](overview-config.md) chooses adapter kinds; composition roots construct implementations and hand them to core.
+2. Executor composition routes persisted run kinds between native execution, optional native sandbox execution and container execution. Coding launchers require a usable worker-image configuration.
+3. Model routing resolves a catalog entry for new work, then can bind an adapter to a run's stored entry. Source-control routing selects local or GitHub implementations from repository kind and refuses unconfigured kinds at use time.
+4. Jobs isolate [coding workers](overview-coding.md); model credentials and VCS finalization remain on the trusted side, while the [coding proxy](overview-coding-proxy.md) meters worker model traffic.[^execution][^model][^vcs]
+
+Adapters own external API translation, lifecycle handles and error semantics. [Prisma](overview-prisma.md) holds durable accounting and workflow state, while storage adapters hold blobs. [Deployment modules](overview-deploy.md) supply infrastructure and identities.
+
+**What to do:** review [blob error semantics](blob-not-found-semantics.md), [bounded artifact reads](bounded-file-descriptor.md), [staging failure isolation](workspace-staging-failure.md) and [private/shared datastore scoping](private-datastore-shared-boundary.md) before replacing an adapter. See [runtime architecture](../architecture-runtime.md) for the process model.
+
+[^registry]: src/providers/index.ts, lines 33-47.
+
+[^execution]: src/providers/executor/composition.ts, lines 87-126.
+
+[^model]: src/providers/llm/routing.ts, lines 67-79.
+
+[^vcs]: src/providers/vcs/routing.ts, lines 26-53.

package/docs/knowledge/overview-sandbox.md

@@ -0,0 +1,83 @@
+---
+type: overview
+title: Native tool and worker isolation
+description: QuickJS evaluates user tools while a run-bound gateway retains privileged effects and native worker authority.
+tags: [sandbox, native, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:22:57.805Z }
+sources:
+  - id: tool
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/sandbox/user-tool.ts#L20-L46
+  - id: composition
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/composition.ts#L30-L92
+  - id: worker
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/worker.ts#L37-L100
+  - id: gateway
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/gateway-server.ts#L101-L139
+  - id: model
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/native-worker/gateway-server.ts#L215-L241
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/sandbox/**", "src/native-worker/**"]
+  citations:
+    - id: tool
+      repo: github:wardby/wardby
+      path: src/sandbox/user-tool.ts
+      lines: [20, 46]
+      symbol: runUserToolCall
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:434c5356f9d2f11b7619a6c8aa38e652dc2425a550152ca00e7813f1764f7a0e
+    - id: composition
+      repo: github:wardby/wardby
+      path: src/native-worker/composition.ts
+      lines: [30, 92]
+      symbol: buildNativeSandboxExecutor
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:efd8be98646c541fd49bb8e5881b15e9e63c6419179113cebfc9d02b7e55c725
+    - id: worker
+      repo: github:wardby/wardby
+      path: src/native-worker/worker.ts
+      lines: [37, 100]
+      symbol: runNativeWorker
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:a5ecda1addcbf4acd895a94c3a1670e865342601d5d4028b9bd208119a51ad62
+    - id: gateway
+      repo: github:wardby/wardby
+      path: src/native-worker/gateway-server.ts
+      lines: [101, 139]
+      symbol: handle
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:75818d5d25ee6ecf6c77c802fc123a7f5f396589d4c99325bb37a9b2ec6fb43a
+    - id: model
+      repo: github:wardby/wardby
+      path: src/native-worker/gateway-server.ts
+      lines: [215, 241]
+      symbol: streamModel
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:d3122b8a90bb9b4345ed411b8ddc73fedb0ea9e979f069d1a2f1615ca3eb97dd
+  confidence: high
+---
+
+Native isolation has two layers: user tool bodies execute in QuickJS, and sandbox-mode native agents run their turn loop in a separate worker. The same user-tool function validates arguments and evaluates tool code against an explicitly supplied privileged host.[^tool]
+
+An isolated native run proceeds through these steps:
+
+1. Composition selects the Docker or Kubernetes launcher and optionally wraps it with a single-use warm-worker pool.
+2. The executor establishes a run-bound gateway session and delivers worker input through the launcher's isolation and delivery gates.
+3. The worker drives NativeEngine with model calls and privileged tool effects represented as gateway requests. User tools stay in local QuickJS; built-ins are served remotely.
+4. The gateway validates request shape, run identity and current drivability before serving operations; model calls are restricted to the run's model. Results return to [core settlement](overview-core.md), whose authoritative accounting comes from the trusted side.[^composition][^worker][^gateway][^model]
+
+The area owns worker protocol, sandbox bridges and launch lifecycle. Session, call and warm-worker ledgers live in [Prisma](overview-prisma.md). [Provider adapters](overview-providers.md) remain on the trusted side; [deployment](overview-deploy.md) supplies the network and container boundary. [Coding workers](overview-coding.md) use a separate execution protocol.
+
+**What to do:** preserve [warm input publication](warm-input-publication.md) and the [private/shared datastore boundary](private-datastore-shared-boundary.md) behind privileged effects. See [native sandbox](../native-sandbox.md) for configuration and isolation guarantees.
+
+[^tool]: src/sandbox/user-tool.ts, lines 20-46.
+
+[^composition]: src/native-worker/composition.ts, lines 30-92.
+
+[^worker]: src/native-worker/worker.ts, lines 37-100.
+
+[^gateway]: src/native-worker/gateway-server.ts, lines 101-139.
+
+[^model]: src/native-worker/gateway-server.ts, lines 215-241.

package/docs/knowledge/overview-surfaces.md

@@ -0,0 +1,83 @@
+---
+type: overview
+title: Viewer, observability and knowledge tooling
+description: Read projections, metrics and cited knowledge expose runtime state and architecture without owning execution.
+tags: [viewer, observability, knowledge, tooling]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:23:52.509Z }
+sources:
+  - id: viewer
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/viewer/http.ts#L109-L137
+  - id: events
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/viewer/event-bus.ts#L59-L113
+  - id: metrics
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/observability/metrics-server.ts#L21-L43
+  - id: knowledge
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/knowledge/check.ts#L68-L86
+  - id: fixtures
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/tools/codex-request-shape.ts#L48-L76
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/viewer/**", "src/observability/**", "src/knowledge/**", "src/tools/**"]
+  citations:
+    - id: viewer
+      repo: github:wardby/wardby
+      path: src/viewer/http.ts
+      lines: [109, 137]
+      symbol: createViewerApi.handle
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:03dea11ad42963e9244fcd1b0ecc870b56dd2c2f71524de88138dfe852fbdea5
+    - id: events
+      repo: github:wardby/wardby
+      path: src/viewer/event-bus.ts
+      lines: [59, 113]
+      symbol: createViewerEventBus
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:6a7a2ebbe033f611c7a94ab29f2fcdaf8c1957bf680a36e502406232d81a0301
+    - id: metrics
+      repo: github:wardby/wardby
+      path: src/observability/metrics-server.ts
+      lines: [21, 43]
+      symbol: startMetricsServer
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:19b994cd518149718981334eefc2beca5508501f131b2fab8b1f046764920700
+    - id: knowledge
+      repo: github:wardby/wardby
+      path: src/knowledge/check.ts
+      lines: [68, 86]
+      symbol: checkBundle
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:819ec7779ed8ce9529dfe3364d02936c31f88d98125ad3429094729510151bf1
+    - id: fixtures
+      repo: github:wardby/wardby
+      path: src/tools/codex-request-shape.ts
+      lines: [48, 76]
+      symbol: requestShape
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:e0dfb71fb14012af5b9a41cc893fda12418fd55e11a83ec1ca813c476a07cd79
+  confidence: high
+---
+
+These supporting surfaces turn authoritative state into operator views and engineering evidence. Viewer serves authenticated graph and run-detail projections plus live events; observability exposes Prometheus data; knowledge tooling parses, checks and selects cited concepts; developer tools record and compare provider request fixtures.[^viewer][^metrics][^knowledge][^fixtures]
+
+The main flows are:
+
+1. Viewer authenticates a request and requires admin:view before serving graph, run, infrastructure or event routes.
+2. A lazy Postgres LISTEN connection validates notifications and fans them out to subscribers. The SSE layer signals reconnection gaps so clients can refetch authoritative projections.
+3. The metrics listener exposes its supplied registry at a separate endpoint; the coding proxy supplies request observations.
+4. Knowledge checks parse each concept and compare citation hashes against repository content. Fixture-shape tooling summarizes request keys and types so SDK changes can be reviewed against proxy validation.[^viewer][^events][^metrics][^knowledge][^fixtures]
+
+The area owns API schemas, projections, stream subscriptions, metric registries and knowledge validation results. [Prisma](overview-prisma.md) owns durable run state and notification triggers. [MCP](overview-mcp.md) composes viewer authentication, the [proxy](overview-coding-proxy.md) supplies metering events, and [coding dispatch](overview-core.md) incorporates repository knowledge.
+
+**What to do:** preserve [viewer write isolation](viewer-notify-write-isolation.md); observation must not become a dependency of authoritative state changes. See [viewer API](../viewer-api.md), [observability](../observability.md), [architecture knowledge](../knowledge.md) and [Codex request compatibility](../coding-worker-isolation.md) for the owning guides.
+
+[^viewer]: src/viewer/http.ts, lines 109-137.
+
+[^events]: src/viewer/event-bus.ts, lines 59-113.
+
+[^metrics]: src/observability/metrics-server.ts, lines 21-43.
+
+[^knowledge]: src/knowledge/check.ts, lines 68-86.
+
+[^fixtures]: src/tools/codex-request-shape.ts, lines 48-76.