@wardby/cli 0.6.0 → 0.8.0

package/docs/knowledge/private-datastore-shared-boundary.md

@@ -0,0 +1,54 @@
+---
+type: invariant
+title: Private datastore wrappers must reject shared methods
+description: Prefix restrictions on private keys cannot authorize the provider shared-store methods.
+tags: [datastores, capabilities, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: deny
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/datastore/scoped.ts#L33-L52
+  - id: wiring
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/runner.ts#L1368-L1388
+  - id: shared
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/datastores.ts#L119-L151
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/providers/datastore/scoped.ts", "src/core/datastores.ts", "src/core/runner.ts", "src/sandbox/**"]
+  citations:
+    - id: deny
+      repo: github:wardby/wardby
+      path: src/providers/datastore/scoped.ts
+      lines: [33, 52]
+      symbol: scopeDatastore shared methods
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:ab019d2d34268011795717728e7d3a3f37b0e9c106c6f515b935abd4e94a8760
+    - id: wiring
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [1368, 1388]
+      symbol: createNativeRunTools.scopedHost
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:61bb446c6ed2a1fde4c53951680588ac75de28d6b3219eebb8ae801cd4438816
+    - id: shared
+      repo: github:wardby/wardby
+      path: src/core/datastores.ts
+      lines: [119, 151]
+      symbol: scopeSharedDatastoreAccessor
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:508ad8dbaa811b4528d626431b84eda9dd6fe5a2929ffc6005106c9b2eb23703
+  confidence: high
+---
+
+Private and shared datastore operations originate from the same provider interface but pass through different authorization wrappers. The runner gives a tool a private prefix-scoped datastore and a separately scoped shared accessor; forwarding shared methods through the private wrapper would bypass the shared accessor's bound-name and prefix checks.[^wiring][^shared]
+
+The private wrapper therefore rejects every shared method, including reads, even though those methods are unreachable through its current call sites. This prevents a future wiring change from silently inheriting the unscoped provider's shared-store authority.[^deny]
+
+**What to do:** retain the rejecting shared methods when extending the provider interface. Construct shared access through its dedicated accessor instead of treating private key prefixes as a grant on shared stores. The [native capabilities guide](../../help/native-capabilities.md) describes attachment scope; this concept records the consequence at the provider boundary. See [native isolation](overview-sandbox.md) and [providers](overview-providers.md).
+
+[^deny]: src/providers/datastore/scoped.ts, lines 33-52.
+
+[^wiring]: src/core/runner.ts, lines 1368-1388.
+
+[^shared]: src/core/datastores.ts, lines 119-151.

package/docs/knowledge/proxy-settlement-projections.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Proxy usage projections must not govern settlement
+description: Run totals are rebuilt from settled requests while per-model reporting failures are isolated by a savepoint.
+tags: [proxy, budgets, transactions]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: settle
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/coding-proxy/prisma-ledger.ts#L274-L309
+  - id: totals
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/coding-proxy/prisma-ledger.ts#L316-L369
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/providers/coding-proxy/prisma-ledger.ts", "deploy/gke/database-grants.sql"]
+  citations:
+    - id: settle
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/prisma-ledger.ts
+      lines: [274, 309]
+      symbol: complete
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:1e1afa8d2b3ac5786e85308f314d76d5cb955b81a05320bad70d37ab398026d1
+    - id: totals
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/prisma-ledger.ts
+      lines: [316, 369]
+      symbol: recomputeRunTotals
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:f43cf2ec538c24cd65f4a454e6940007226750e06b3cb3ee6668f6ffe2b48a06
+  confidence: high
+---
+
+Completion locks the session before changing the request. Totals are assigned from completed requests and estimated uncertain requests, rather than incremented; RunModelUsage is also rebuilt, but its write runs inside a savepoint and rolls back independently on failure.[^settle][^totals]
+
+**Why:** settling an uncertain request can replace an estimate with actual usage. Incrementing would count both, while allowing a reporting-table failure to abort the transaction would discard the authoritative settlement. Keep ledger and Run writes authoritative and the per-model projection best effort.
+
+[^settle]: src/providers/coding-proxy/prisma-ledger.ts, lines 274-309.
+
+[^totals]: src/providers/coding-proxy/prisma-ledger.ts, lines 316-369.

package/docs/knowledge/run-pricing-first-writer.md

@@ -0,0 +1,43 @@
+---
+type: invariant
+title: Pricing races must use the persisted winner
+description: Concurrent native attempts must reuse the catalog terms that won the conditional pricing write.
+tags: [pricing, concurrency, models]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: pin
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/run-pricing.ts#L45-L69
+  - id: adapter
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/llm/routing.ts#L74-L79
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/core/run-pricing.ts", "src/providers/llm/routing.ts", "src/core/runner.ts"]
+  citations:
+    - id: pin
+      repo: github:wardby/wardby
+      path: src/core/run-pricing.ts
+      lines: [45, 69]
+      symbol: pinNativeRunPricing
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:ceb81fd7d2aa2c29b19b333e93f3838a002aa45498f2b90f6d1aca1f6aed0385
+    - id: adapter
+      repo: github:wardby/wardby
+      path: src/providers/llm/routing.ts
+      lines: [74, 79]
+      symbol: RoutingLlmProvider.forRun
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:5511b7ed50630042519c07b0ef699eaa44cf10951933aeb1db69434f5160f278
+  confidence: high
+---
+
+[Model guidance](../models.md) already describes retaining a run's original catalog terms. The additional concurrency consequence is that two attempts can resolve different live entries before either pins the run. Pricing is written only while pricingVersion is null; an attempt that loses that write reads the stored terms back rather than using its local resolution.[^pin]
+
+The router can bind an adapter to the stored entry, so request shaping and prices stay coupled to the same terms.[^adapter]
+
+**What to do:** preserve both the conditional write and read-back when refactoring load or resume paths. An unconditional update can reprice an active run; ignoring the winning row can make an attempt's provider behavior disagree with durable accounting. See [core execution](overview-core.md).
+
+[^pin]: src/core/run-pricing.ts, lines 45-69.
+
+[^adapter]: src/providers/llm/routing.ts, lines 74-79.

package/docs/knowledge/schedule-claim-transaction.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Schedule deduplication belongs to the transaction
+description: A scheduler lease cannot replace the atomic schedule-window claim and run creation.
+tags: [scheduling, concurrency]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:22:57.651Z }
+sources:
+  - id: claim
+    url: https://github.com/wardby/wardby/blob/9c0f910f919dec4f1a2149bae78612cda41f6007/src/core/scheduler.ts#L50-L82
+  - id: lock
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/dispatch.ts#L667-L684
+wardby:
+  schema: 1
+  roles: [builder, reviewer, planner]
+  affects: ["src/core/scheduler.ts", "src/core/dispatch.ts"]
+  citations:
+    - id: claim
+      repo: github:wardby/wardby
+      path: src/core/scheduler.ts
+      lines: [50, 82]
+      symbol: claimDueRun
+      sha: 9c0f910f919dec4f1a2149bae78612cda41f6007
+      spanHash: sha256:1464539e5b1ac8acf09d9869aaab0fd7ce71ff9647384366537280c850de7b89
+    - id: lock
+      repo: github:wardby/wardby
+      path: src/core/dispatch.ts
+      lines: [667, 684]
+      symbol: dispatchRun
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:88f506bcf07c8b1df9dfd039c4a694fbdd658c9d93948eab6db9575626af0515
+  confidence: high
+---
+
+The scheduler rechecks the due window under an agent row lock, advances `lastScheduledAt`, and creates the run in the same dispatch transaction.[^claim][^lock]
+
+**Why:** the lease coordinates ticking processes, but cannot prevent overlapping claims within a process. Moving the schedule advance outside the transaction can consume a window without a run or admit the same window twice. Keep the claim and persistence together.
+
+[^claim]: src/core/scheduler.ts, lines 50-82.
+
+[^lock]: src/core/dispatch.ts, lines 667-684.

package/docs/knowledge/secret-entry-replica-contract.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Secret entry replicas must share token verification
+description: A shared outcome database cannot complete a secret-entry round trip when replicas use independent signing keys.
+tags: [mcp, secrets, configuration]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: key
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L139-L155
+  - id: codec
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L191-L202
+  - id: outcome
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/tools/secret-elicitation.ts#L79-L104
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/server.ts", "src/mcp/tools/secret-elicitation*"]
+  citations:
+    - id: key
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [139, 155]
+      symbol: loadRequestStateKey
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:09a8e266ca81faa6a3af750f87ab4b7892dba80a2fde187a3af16df22e3e8aa9
+    - id: codec
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [191, 202]
+      symbol: buildMcpServer
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:32779f2edf44c96fb4b295df8feceecaf9f9034c67513ac7074ad6423abf766b
+    - id: outcome
+      repo: github:wardby/wardby
+      path: src/mcp/tools/secret-elicitation.ts
+      lines: [79, 104]
+      symbol: recordOutcome
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:1733171e7240fc8f206a4c0b3a4e45a4e587c252a9f72e0a2d8fc25f2ceae9fd
+  confidence: high
+---
+
+Secret entry can mint a link, accept the browser submission, and poll the result on different HTTP replicas. Outcomes are stored in Postgres, but request-state verification still requires the same signing key on those replicas: `REQUEST_STATE_KEY` when set, otherwise a key each HTTP replica derives from the `SECRET_APP_KEY` they share (a stdio server keeps a random key of its own).[^key][^codec][^outcome]
+
+**What to do:** preserve both shared verification and shared outcome storage when scaling this flow. Database sharing alone leaves browser links unverifiable on another replica. [Secrets and tools](../tool-secrets.md) already describes browser entry; this concept records the replica contract.
+
+[^key]: src/mcp/server.ts, lines 139-155.
+
+[^codec]: src/mcp/server.ts, lines 191-202.
+
+[^outcome]: src/mcp/tools/secret-elicitation.ts, lines 79-104.

package/docs/knowledge/terminal-run-first-writer.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Terminal run state belongs to the first writer
+description: Run completion must conditionally write pending or running rows and read back the persisted winner.
+tags: [execution, recovery, concurrency]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:22:57.651Z }
+sources:
+  - id: states
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L460-L472
+  - id: finish
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L499-L516
+wardby:
+  schema: 1
+  roles: [builder, reviewer, planner]
+  affects: ["src/core/runner.ts", "src/core/reconciler.ts", "src/core/dispatch.ts"]
+  citations:
+    - id: states
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [460, 472]
+      symbol: DRIVABLE
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:77bd85d5b8025e9319afba8477923d068afa0e9bfaea46be28d68b2c41996e7b
+    - id: finish
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [499, 516]
+      symbol: finishRunClaimed
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:258b0ccb1bf328fef95a5e459858eb3f02ecc3d600f6ff4a7aae562a6416936c
+  confidence: high
+---
+
+`finishRunClaimed` restricts its update to pending or running rows, then reads the stored run even when its update lost the race.[^states][^finish] The step-ownership behavior is already described in [Durable executor](../security-deployment.md#durable-executor); this contract covers the terminal database write and its return value.
+
+**What to do:** preserve the status predicate and read-back when adding completion paths. An unconditional write can overwrite a completed or lost run; returning a locally assembled result can report an outcome that never became authoritative.
+
+[^states]: src/core/runner.ts, lines 460-472.
+
+[^finish]: src/core/runner.ts, lines 499-516.

package/docs/knowledge/transactional-agent-authorization.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Agent authorization must share the mutation transaction
+description: Using the default access client inside a transaction disconnects grant reads from mutation isolation.
+tags: [access, transactions]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:20:14.397Z }
+sources:
+  - id: access
+    url: https://github.com/wardby/wardby/blob/9c0f910f919dec4f1a2149bae78612cda41f6007/src/mcp/auth/access.ts#L47-L70
+  - id: mutation
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/mcp/tools/agents.ts#L847-L857
+  - id: isolation
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/mcp/tools/agents.ts#L975-L985
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/auth/**", "src/mcp/tools/**"]
+  citations:
+    - id: access
+      repo: github:wardby/wardby
+      path: src/mcp/auth/access.ts
+      lines: [47, 70]
+      symbol: assertAgentAccess
+      sha: 9c0f910f919dec4f1a2149bae78612cda41f6007
+      spanHash: sha256:04c8d3accf60339956706f501fbf628ae620e8f368bd93c20825f6ef4f915cbb
+    - id: mutation
+      repo: github:wardby/wardby
+      path: src/mcp/tools/agents.ts
+      lines: [847, 857]
+      symbol: update_agent
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:f6b5789fc562f8de5ad3e905513cd239c4ac447229ee1ee6bf4378cadffaeaa6
+    - id: isolation
+      repo: github:wardby/wardby
+      path: src/mcp/tools/agents.ts
+      lines: [975, 985]
+      symbol: update_agent
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:d3c25b8684e11ec56311649d617f6e933d380d4d063257e2f21804f502b2b832
+  confidence: high
+---
+
+The access helpers default to `ctx.db`; callers inside a mutation transaction must explicitly pass `tx` so grant reads participate in the same isolation boundary.[^access] Agent updates re-check write access through `tx` and commit under Serializable isolation.[^mutation][^isolation]
+
+**Why:** checking access only before a mutation, or using the default client within it, lets a concurrent grant revocation escape the transaction’s conflict detection. The operator-facing revocation behavior is described in [Security deployment, Sharing agents](../security-deployment.md); this concept records the transaction contract behind that behavior.
+
+[^access]: src/mcp/auth/access.ts, lines 47-70.
+
+[^mutation]: src/mcp/tools/agents.ts, lines 847-857.
+
+[^isolation]: src/mcp/tools/agents.ts, lines 975-985.

package/docs/knowledge/viewer-notify-write-isolation.md

@@ -0,0 +1,30 @@
+---
+type: invariant
+title: Viewer notifications must not abort authoritative writes
+description: The viewer trigger contains notification errors so event delivery cannot fail run persistence.
+tags: [database, viewer, observability]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: notify
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql#L1-L47
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["prisma/migrations/**", "src/viewer/**"]
+  citations:
+    - id: notify
+      repo: github:wardby/wardby
+      path: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql
+      lines: [1, 47]
+      symbol: wardby_viewer_notify
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:8c16b83ca66d420cd0ccc5824e496625baa8ebc6b1010a0721e4ac36d6419b93
+  confidence: high
+---
+
+The trigger formats the already-UTC timestamp without time-zone conversion and catches errors around pg_notify, including oversized payload failures. Its notification is a projection of the write, not a prerequisite for it.[^notify]
+
+**What to do:** preserve the exception boundary when changing event payloads. [Viewer API](../viewer-api.md) already documents resynchronizing after stream gaps; this concept records the database consequence: viewer delivery must never roll back the write it observes.
+
+[^notify]: prisma/migrations/20261003030000_viewer_notify_fixes/migration.sql, lines 1-47.

package/docs/knowledge/warm-input-publication.md

@@ -0,0 +1,30 @@
+---
+type: invariant
+title: Warm input publication must refuse replacement
+description: Atomic visibility alone is insufficient when one warm worker may receive its capability only once.
+tags: [native, isolation, workers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: publish
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/native-worker/warm-delivery.ts#L19-L36
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/native-worker/warm-delivery.ts", "src/native-worker/main.ts"]
+  citations:
+    - id: publish
+      repo: github:wardby/wardby
+      path: src/native-worker/warm-delivery.ts
+      lines: [19, 36]
+      symbol: warmDeliveryCommand
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:cfb11a192eec28b8296f9e7d56d79dd9b70c2aae4f57ef888c7e4173e1f1219b
+  confidence: high
+---
+
+Warm delivery writes stdin to an exclusive temporary file, then hard-links it to the input filename. Unlike rename, the link cannot replace an input already published by another delivery.[^publish]
+
+**What to do:** retain both complete-file visibility and no-replacement semantics. [Native sandbox, claim isolation](../native-sandbox.md#how-claims-keep-the-isolation-guarantees) already documents single-use workers and capability delivery over stdin; this is the file-publication consequence of that contract.
+
+[^publish]: src/native-worker/warm-delivery.ts, lines 19-36.

package/docs/knowledge/workspace-staging-failure.md

@@ -0,0 +1,54 @@
+---
+type: invariant
+title: Failed workspace fills must remain untrusted
+description: Collection failure must not expose a partially materialized worker tree to validation or trusted replacement.
+tags: [coding, collection, isolation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: swap
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/jobs/workspace-swap.ts#L16-L51
+  - id: docker
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/jobs/docker.ts#L385-L400
+  - id: kubernetes
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/providers/jobs/kubernetes.ts#L738-L750
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects: ["src/providers/jobs/workspace-swap.ts", "src/providers/jobs/docker.ts", "src/providers/jobs/kubernetes.ts"]
+  citations:
+    - id: swap
+      repo: github:wardby/wardby
+      path: src/providers/jobs/workspace-swap.ts
+      lines: [16, 51]
+      symbol: replaceDirectoryFromStaging
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:0d7e951e15553a190b064604ec72c49998f79ebff84b8983aae37b212cc56069
+    - id: docker
+      repo: github:wardby/wardby
+      path: src/providers/jobs/docker.ts
+      lines: [385, 400]
+      symbol: DockerJobLauncher.materializeWorkspace
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:3e9525156cbd3c0791e79ff7ce86b16c92b0d62d8acc92a104b604fc6f54c08f
+    - id: kubernetes
+      repo: github:wardby/wardby
+      path: src/providers/jobs/kubernetes.ts
+      lines: [738, 750]
+      symbol: KubernetesJobLauncher.materializeWorkspace
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:44a85cadf23fdb1d77c0f4e1738873327756c029ce114c4efb47276d18abac84
+  confidence: high
+---
+
+Both job launchers materialize collected worker content through a sibling staging directory. Only a successful fill proceeds to validation and replacement of the trusted workspace; a rejected fill can leave escaping symlinks and must go straight to removal without walking that tree.[^swap][^docker][^kubernetes]
+
+The swap keeps the original workspace until filling and validation succeed, then uses a backup during renames. Failure after moving the original attempts to restore it before cleanup; restoration is best effort, so this is not a crash-safe transaction.[^swap]
+
+**What to do:** keep fill, validation and replacement in that order. Never catch a collection error and continue validating or publishing the partial tree. Preserve cleanup that unlinks symlinks rather than traversing them. This complements [descriptor-bound reads](bounded-file-descriptor.md) at the directory boundary; see [coding execution](overview-coding.md).
+
+[^swap]: src/providers/jobs/workspace-swap.ts, lines 16-51.
+
+[^docker]: src/providers/jobs/docker.ts, lines 385-400.
+
+[^kubernetes]: src/providers/jobs/kubernetes.ts, lines 738-750.

package/docs/knowledge.md

@@ -21,7 +21,43 @@ docs/knowledge/
 ```
 
 `index.md` and `log.md` are reserved names and are never concepts. The default
-bundle path is `docs/knowledge`.
+bundle path is `docs/knowledge`; a repository can choose another folder (see
+[Where the bundle lives](#where-the-bundle-lives)).
+
+## Where the bundle lives
+
+Wardby itself reads the bundle in three places: the knowledge note it adds to
+every coding run, the merge watcher's drift scoping, and `wardby knowledge
+check`. For those, it uses the first of these that applies:
+
+1. **`.wardby/knowledge.yaml` on the branch names a folder.** The file has one
+   key:
+
+   ```yaml
+   path: .okf
+   ```
+
+   `path` is a folder relative to the repository root (a leading `./` and a
+   trailing `/` are ignored). It may not be absolute, contain `..`, or point
+   into `.wardby/` or `.git/`.
+
+2. **Otherwise, `docs/knowledge/`.** This is also used when
+   `.wardby/knowledge.yaml` cannot be used (invalid YAML, an unknown key, or a
+   path that breaks the rules above): Wardby logs a warning and falls back to
+   `docs/knowledge/`, and `wardby knowledge check` reports
+   `knowledge_config_invalid`. A bad file never fails a run or a dispatch.
+
+3. **No bundle at either place.** Wardby adds no knowledge note and the merge
+   watcher finds no concepts. Your agents can still keep knowledge in any folder
+   you like: say where in their system prompts or in `AGENTS.md`, and they read
+   and write it there. You give up only the automatic note and drift scoping on
+   merge; a scheduled architecture agent still re-verifies every citation on
+   its next run.
+
+Coding runs cannot change `.wardby/knowledge.yaml` (everything under `.wardby/`
+except `.wardby/services.yaml` is protected), so a person sets it, in a normal
+commit. Prompts that name the bundle folder, such as the architecture agent's
+below, should use the folder you chose.
 
 ## Concept format
 
@@ -108,7 +144,9 @@ The `spanHash` above is a placeholder; compute the real one from the cited lines
 
 ## How coding runs use the bundle
 
-When `docs/knowledge/index.md` exists on the run's base branch, Wardby adds a
+When the bundle's `index.md` (in `docs/knowledge/`, or the folder
+[`.wardby/knowledge.yaml`](#where-the-bundle-lives) names) exists on the run's
+base branch, Wardby adds a
 knowledge note to the coding run's task automatically. The note tells the agent
 that the knowledge is recalled context rather than authority (the repository's
 own instructions, such as `AGENTS.md`, win on conflict), includes the index, and
@@ -116,8 +154,8 @@ asks the agent to read the concepts covering files it will touch and to update a
 concept's prose if its change alters the behavior the concept describes.
 
 - The note is capped at 8 KiB. When the index does not fit it is cut at a line
-  boundary and a `[index truncated — list docs/knowledge/ for the rest]` marker
-  is added. The note always ends with an `[end of architecture knowledge]` line.
+  boundary and an `[index truncated — list <bundle folder>/ for the rest]`
+  marker is added. The note always ends with an `[end of architecture knowledge]` line.
 - It is dropped when the task leaves no room for it.
 - It never fails or changes a dispatch: an unreadable or oversized index, or any
   problem reading the branch, simply means no note.
@@ -138,21 +176,23 @@ Anything that writes citations must take the `sha` value from this line.
 wardby knowledge check [dir] [--root <repo root>] [--strict] [--json]
 ```
 
-`dir` defaults to `docs/knowledge` and `--root` to the current directory;
+`dir` defaults to the folder `.wardby/knowledge.yaml` under `--root` names, else
+`docs/knowledge`, and `--root` to the current directory;
 citation paths resolve against `--root`. The command prints one line per issue
 (`<severity> <code> <file>: <message>`) and a summary. It exits 1 when there is
 any error, or, with `--strict`, any warning. `--json` prints
 `{ "issues": [...] }` instead.
 
-| Code                    | Severity | Meaning                                                         | Fix                                                |
-| ----------------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------- |
-| `concept_invalid`       | error    | Front-matter is missing, is not valid YAML, or fails the schema | Fix the field the message names                    |
-| `concept_secret`        | error    | The file contains a secret-shaped value                         | Remove it and rotate the credential                |
-| `index_missing`         | error    | The bundle has no root `index.md`                               | Create it                                          |
-| `index_link_broken`     | error    | An index links to a file that does not exist                    | Fix or remove the link                             |
-| `concept_not_indexed`   | warning  | A concept is not linked from any `index.md`                     | Add its line to the index                          |
-| `citation_unverifiable` | warning  | The cited file is missing or the lines are out of range         | Re-anchor the citation, or deprecate the concept   |
-| `citation_stale`        | warning  | The cited span no longer matches `spanHash`                     | Re-read the code, update the claim, then re-anchor |
+| Code                       | Severity | Meaning                                                                           | Fix                                                |
+| -------------------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `concept_invalid`          | error    | Front-matter is missing, is not valid YAML, or fails the schema                   | Fix the field the message names                    |
+| `concept_secret`           | error    | The file contains a secret-shaped value                                           | Remove it and rotate the credential                |
+| `index_missing`            | error    | The bundle has no root `index.md`                                                 | Create it                                          |
+| `index_link_broken`        | error    | An index links to a file that does not exist                                      | Fix or remove the link                             |
+| `concept_not_indexed`      | warning  | A concept is not linked from any `index.md`                                       | Add its line to the index                          |
+| `citation_unverifiable`    | warning  | The cited file is missing or the lines are out of range                           | Re-anchor the citation, or deprecate the concept   |
+| `citation_stale`           | warning  | The cited span no longer matches `spanHash`                                       | Re-read the code, update the claim, then re-anchor |
+| `knowledge_config_invalid` | error    | `.wardby/knowledge.yaml` cannot be used, so `docs/knowledge/` was checked instead | Fix the file as the message says                   |
 
 Use plain `wardby knowledge check` while editing and `--strict` for the agent or
 CI job that maintains the bundle.