@kontourai/flow-agents 2.2.0 → 2.4.0

package/docs/getting-started.md

@@ -24,6 +24,16 @@ npx @kontourai/flow-agents init --runtime opencode    --dest . --yes
 
 The installer copies agents, skills, context contracts, hook scripts, Kit assets, and the Flow Agents telemetry descriptor into the workspace. The Builder Kit installs automatically. Your agent reads those files at startup; no plugin registry required.
 
+For a normal Codex global install, target the Codex home instead of a project workspace:
+
+```bash
+npx @kontourai/flow-agents init --runtime codex --global --activate-kits --yes
+```
+
+That installs into `CODEX_HOME` when it is set, otherwise `~/.codex`. Use `--dest /path/to/codex-home` only when you need an explicit override for an isolated install, CI fixture, or test.
+
+Keep generated Codex base config lean. Put profile-specific model, provider, and approval settings in separate `<profile>.config.toml` files and select them with `codex --profile <name>`.
+
 **What lands in the workspace:**
 
 - `agents/`, `skills/`, `context/` — skill definitions and shared contracts the agent follows
@@ -84,7 +94,7 @@ The agent will run the `builder-shape` / `idea-to-backlog` skill, which:
 3. drafts a shaped work item with a stated outcome, non-goals, acceptance criteria, and a verification expectation
 4. stops at the `breakdown-gate` and waits for you to confirm before creating GitHub issues
 
-You will see the agent write a local artifact at `.flow-agents/<slug>/<slug>--idea-to-backlog.md`. That artifact is the machine-readable input to the next stage — not a summary in the chat window.
+You will see the agent write a local artifact at `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md`. That artifact is the machine-readable input to the next stage — not a summary in the chat window.
 
 To continue and file the GitHub issue:
 
@@ -128,7 +138,7 @@ Use verify-work on the current branch and report what evidence is present.
 
 ### What you observe
 
-- **Between each step**, the agent writes a local session sidecar under `.flow-agents/<slug>/` — `state.json`, `acceptance.json`, `evidence.json`, and `handoff.json`. These survive compaction, tab close, or a new session. A future session resumes from recorded state.
+- **Between each step**, the agent writes a local session sidecar under `.kontourai/flow-agents/<slug>/` — `state.json`, `acceptance.json`, `evidence.json`, and `handoff.json`. These survive compaction, tab close, or a new session. A future session resumes from recorded state.
 - **At each gate**, the agent either presents the evidence and moves forward, or blocks and explains what is missing. It does not make up a confident summary and proceed.
 - **The stop-goal-fit hook** (at L2) prevents the agent from stopping when evidence is still incomplete — you see a warning or block rather than "all done!" on partial work.
 - **If verify fails**, the verify-gate routes back to execution (or plan, or design-probe, depending on the failure class) and tries again — up to three times before hard-blocking.

package/docs/integrations/harness-install.md

@@ -79,7 +79,8 @@ The install appends rather than replaces, so existing hooks are not removed. Rev
       …
   skills/
     …
-  .flow-agents/            ← runtime workflow artifacts (not committed)
+  .kontourai/
+    flow-agents/           ← runtime workflow artifacts (not committed)
 ```
 
 ## opencode

package/docs/kit-authoring-guide.md

@@ -54,7 +54,7 @@ Required fields:
 | `name` | Non-empty display name |
 | `flows` | Non-empty list; each entry must have `id` and `path` |
 
-Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`. Optional fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
+Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)). Optional fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
 
 ## Minimal flow file
 
@@ -91,6 +91,22 @@ A Flow Definition at minimum needs `id`, `version`, `steps`, and `gates`. Steps
 
 The `id` in the flow file should match the `id` declared in `kit.json`'s `flows` list. Look at `kits/builder/flows/shape.flow.json` and `kits/builder/flows/build.flow.json` in this repository for fuller examples of multi-step flows with required and optional gate evidence.
 
+Flow Definitions may compose another declared Flow Definition at a step with `uses_flow`. The parent keeps lifecycle ownership (`active_flow_id` can remain the parent flow), while gate resolution for that step comes from the child flow with the same step id. Use this for reusable extensions such as publish, CI merge readiness, or learning closeout:
+
+```json
+{
+  "id": "builder.build",
+  "steps": [
+    { "id": "verify", "next": "pr-open" },
+    { "id": "pr-open", "next": "merge-ready-ci", "uses_flow": "builder.publish-learn" },
+    { "id": "merge-ready-ci", "next": "learn", "uses_flow": "builder.publish-learn" },
+    { "id": "learn", "next": "done", "uses_flow": "builder.publish-learn" }
+  ]
+}
+```
+
+The child flow should declare the gates for those step ids and list the claim types it intentionally exposes in `exports` (expectation ids are also accepted for non-claim expectations). Composition fails closed when a child gate expectation is not exported. Parent verification is still determined by trust-bundle claims: required child claims that are missing, disputed, or `not_verified` prevent the composed parent from being treated as verified.
+
 ## Validate
 
 Before installing or sharing a kit, run validation from the flow-agents checkout:
@@ -144,13 +160,13 @@ The `codex-local` adapter is selected automatically. To activate for Strands, pa
 
 ### What each adapter activates
 
-Each adapter copies declared assets into `.flow-agents/runtime/<adapter>/` and produces an `activation.json` manifest. The table below shows which asset classes are activated today:
+Each adapter copies declared assets into `.kontourai/flow-agents/projections/<adapter>/` and produces an `activation.json` manifest. The table below shows which asset classes are activated today:
 
 | Asset class | `codex-local` | `strands-local` | Notes |
 |---|---|---|---|
-| `flows` | Activated — `.flow-agents/runtime/codex/flows/<kit-id>/<asset-id>.flow.json` | Activated — `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` | Gate definitions read by each adapter's flow-routing layer. |
-| `skills` | Activated — `.flow-agents/runtime/codex/skills/<kit-id>/<filename>` | Activated — `.flow-agents/runtime/strands/skills/<kit-id>/<filename>` | Agent guidance markdown. For codex-local, reference these paths from AGENTS.md. For strands-local, the Strands steering layer can glob for `*.md` under `skills/` during system-prompt injection. |
-| `docs` | Activated — `.flow-agents/runtime/codex/docs/<kit-id>/<filename>` | Activated — `.flow-agents/runtime/strands/docs/<kit-id>/<filename>` | Documentation assets. Co-located with skill files for easy reference. |
+| `flows` | Activated — `.kontourai/flow-agents/projections/codex/flows/<kit-id>/<asset-id>.flow.json` | Activated — `.kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json` | Gate definitions read by each adapter's flow-routing layer. |
+| `skills` | Activated — `.kontourai/flow-agents/projections/codex/skills/<kit-id>/<filename>` | Activated — `.kontourai/flow-agents/projections/strands/skills/<kit-id>/<filename>` | Agent guidance markdown. For codex-local, reference these paths from AGENTS.md. For strands-local, the Strands steering layer can glob for `*.md` under `skills/` during system-prompt injection. |
+| `docs` | Activated — `.kontourai/flow-agents/projections/codex/docs/<kit-id>/<filename>` | Activated — `.kontourai/flow-agents/projections/strands/docs/<kit-id>/<filename>` | Documentation assets. Co-located with skill files for easy reference. |
 | `adapters` | `skipped_assets` | `skipped_assets` | Framework or runtime adapter code — not copied by the activation layer. |
 | `evals` | `skipped_assets` | `skipped_assets` | Evaluation suites — not run or copied during activation. |
 | `assets` | `skipped_assets` | `skipped_assets` | General supporting assets — not copied during activation. |
@@ -179,6 +195,14 @@ For path errors: all declared paths must be relative, must not contain `..`, and
 
 For conflicts on re-install: if you install a different source with an existing kit id, the command fails unless you pass `--update`. Use `--force` to re-copy an existing same-source install after validation.
 
+For cross-kit dependency errors:
+
+- `kit.json: dependencies[N].kit_id must be a kebab-case kit id` — the entry's `kit_id` is missing or not lowercase kebab-case. Fix the id.
+- `kit.json: dependencies[N].kit_id must not reference the declaring kit itself` — remove the self-referential entry; a kit cannot depend on itself.
+- `kit.json: dependencies[N].kit_id duplicates '<id>'` — collapse the duplicate declaration to a single entry.
+- `warning: kit '<id>' declares a dependency on '<dep>' ... which is not installed` (at install) — advisory only; install the depended-on kit with `flow-agents kit install <source>` before activating, or activation will fail.
+- `<id>: declares a dependency on kit '<dep>' ... which is not installed or activated` (at activate, non-zero exit) — install the missing kit and re-activate, or remove the dependency declaration if it is no longer needed.
+
 See the [Flow Kit Repository Contract](flow-kit-repository-contract.md) for the full validation rules, registry schema, activation diagnostics, and the install/update/force semantics.
 
 ## Layering: container vs. agent extension
@@ -212,6 +236,41 @@ The **agent extension** is owned by Flow Agents. It defines the optional asset c
 
 Each extension field is an optional array of entries with `id`, `path`, and optional `description`. Extension fields are validated by Flow Agents using the same path rules as the container layer (relative, no `..`, must exist). Unknown extension entries are recorded as `skipped_assets` during activation rather than treated as errors.
 
+### Cross-kit dependencies
+
+A kit may declare that it depends on **another kit** whose skills it invokes at runtime. This is a Flow Agents extension-layer concern (a skill in one kit calling a skill in another), not part of the Flow-owned container contract — see [ADR 0019](adr/0019-kit-dependency-ownership.md) for the ownership rationale (grounded in the container schema's `additionalProperties: true` and ADR 0008's Dividing Test). It is **not** a package manager: it declares and validates *presence*, it does not fetch kits or resolve versions.
+
+Shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "builder",
+  "name": "Builder Kit",
+  "flows": [ /* ... */ ],
+  "dependencies": [
+    {
+      "kit_id": "knowledge",
+      "reason": "learning-review invokes knowledge-capture for durable knowledge storage"
+    }
+  ],
+  "skills": [ /* ... */ ]
+}
+```
+
+| Field | Rule |
+|---|---|
+| `kit_id` | Required. Kebab-case kit id (`^[a-z][a-z0-9-]*$`) of the depended-on kit. Must not reference the declaring kit itself, and must not be duplicated across entries. |
+| `reason` | Optional string explaining why the dependency exists (which skill invokes which). |
+
+Where it is checked:
+
+- **Shape** — at `flow-agents kit install`, `inspect`, and `validate` time. A malformed entry (bad `kit_id`, self-reference, duplicate) is a **hard error**.
+- **Presence at install** — `flow-agents kit install` prints a **non-blocking warning** when a declared dependency is not present in the destination's **local** registry, then exits 0. This check sees only the local installed-kits registry, not the built-in Kit Catalog (an accepted v1 limitation).
+- **Presence at activation** — `flow-agents kit activate` is a **hard error** (non-zero exit) when a declared `kit_id` is not present among the union of built-in catalog kits and locally-installed kits.
+
+`dependencies` is metadata, not evaluable-gate content, so it does **not** affect K0/K1/K2 conformance scoring (see the K-levels section below).
+
 ### When a kit "is" a Flow Agents Kit
 
 A kit is a **Flow Agents Kit** when it satisfies both layers:

package/docs/knowledge-kit.md

@@ -43,7 +43,11 @@ The vector detector is fail-closed: infrastructure failures throw `EMBED_FAILURE
 ## Quick reference
 
 ```bash
-# Install the kit into a workspace
+# Install the kit into the default Codex/global kit destination:
+# CODEX_HOME, or ~/.codex when CODEX_HOME is unset
+npx @kontourai/flow-agents kit install kits/knowledge
+
+# Override the destination for a workspace, isolated home, or test
 npx @kontourai/flow-agents kit install kits/knowledge --dest /path/to/workspace
 
 # Run the contract suite against the default adapter

package/docs/learnings/2026-07-improvement-program.md

@@ -0,0 +1,203 @@
+---
+title: "2026-07 Improvement Program — Learning Review"
+---
+
+# 2026-07 Improvement Program — Learning Review
+
+This document records durable learnings from a multi-week, multi-repository improvement
+program run across the Kontour portfolio in June and July 2026. The program touched
+Flow Agents, Surface, Veritas, Flow, Survey, Traverse, and the shared hachure trust-bundle
+schema. Every finding below was hit empirically during the program and resolved or worked
+around; none are speculative.
+
+It is written for a future maintainer who was not present for the program. Where a finding
+implies a rule you should keep following, that rule is stated explicitly. Cross-repository
+pull requests and issues are linked so you can trace the underlying change.
+
+## Scope and source material
+
+- Corroborating provider issues: [flow-agents#267](https://github.com/kontourai/flow-agents/issues/267),
+  [flow-agents#268](https://github.com/kontourai/flow-agents/issues/268),
+  [flow-agents#281](https://github.com/kontourai/flow-agents/issues/281).
+- Representative pull requests:
+  - Flow Agents: [#264](https://github.com/kontourai/flow-agents/pull/264) (cross-kit
+    dependencies, skill-collision fixes, sidecar governance),
+    [#266](https://github.com/kontourai/flow-agents/pull/266) (manifest-based reconcile,
+    claim classification, loud attestations),
+    [#269](https://github.com/kontourai/flow-agents/pull/269) (veritas-governance kit —
+    readiness→trust-bundle adapter),
+    [#277](https://github.com/kontourai/flow-agents/pull/277) (migrate to
+    `@kontourai/surface` 2.0.0, `Claim.facet` rename).
+  - Surface: [#103](https://github.com/kontourai/surface/pull/103) (order-independent
+    multi-producer merge; hachure 0.7.0 conformance),
+    [#104](https://github.com/kontourai/surface/pull/104) (sync to hachure 0.8.0,
+    vendor-neutral `$id`s), [#105](https://github.com/kontourai/surface/pull/105)
+    (`Claim.surface` → `facet`, spec 0.9.0 parity — a breaking change).
+  - Veritas: [#107](https://github.com/kontourai/veritas/pull/107) (blocking failures win
+    over `promotion_allowed` short-circuit), [#109](https://github.com/kontourai/veritas/pull/109)
+    (migrate `Claim.surface` → `facet`, Surface ^2.0.0, schemaVersion 5).
+  - Flow: [#100](https://github.com/kontourai/flow/pull/100) (migrate to Surface 2.0.0 —
+    shipped as a `chore:` and therefore went unreleased; see Finding 6),
+    [#101](https://github.com/kontourai/flow/pull/101) (trust bundles emit `facet` +
+    schemaVersion 5; Surface 2.0, hachure 0.9).
+  - Survey: [#100](https://github.com/kontourai/survey/pull/100) (migrate to Surface 2.0.0
+    facet rename), released via [#99](https://github.com/kontourai/survey/pull/99) /
+    [#101](https://github.com/kontourai/survey/pull/101).
+  - hachure trust-bundle schema releases 0.6.0 through 0.9.0, which drove the coordinated
+    Surface / Veritas / Flow / Survey / Flow Agents migrations above.
+
+The rest of this document is organized by finding. Each finding states what happened, why
+it matters, and the working discipline or fix to carry forward.
+
+## 1. Trust-ledger write discipline
+
+The trust ledger (`trust.bundle` plus its `evidence.json` / critique inputs) has write
+semantics that are easy to corrupt if you interleave commands:
+
+- `record-evidence` **replaces** `trust.bundle` wholesale. At the time of the program it
+  rebuilt the bundle with a hardcoded `critiques: []`, so any previously recorded critique
+  was silently dropped.
+- `record-critique` is **append-only** and has no supersession mechanism: a reviewer cannot
+  close or retract a disputed finding once written ([flow-agents#267](https://github.com/kontourai/flow-agents/issues/267)).
+- The checks/critiques round-trip through the bundle is contaminating: prior critique claims
+  get re-absorbed as command-less `test_output` checks, turning a critique claim into a
+  divergent, command-less check ([flow-agents#268](https://github.com/kontourai/flow-agents/issues/268)).
+  This is amplified under `--flow-id`, where a **single** critique write is enough to
+  contaminate the ledger.
+
+**Working discipline until the tooling is fixed:**
+
+1. Record **all** evidence first.
+2. Record **at most one** critique write, and make it the **last** write.
+3. Never run any `record-*` command after that final critique write.
+4. If a ledger becomes contaminated, **restart the session** rather than trying to iterate
+   or repair a contaminated ledger in place.
+
+This program's learning-review session itself follows the rule: it was created with
+`ensure-session` **without** `--flow-id` precisely to avoid the single-critique-write
+amplification described above.
+
+## 2. Post-merge ledger staleness
+
+A session whose `trust.bundle` was frozen mid-iteration causes stop-gate "caught
+false-completion" storms after the branch merges. The stale iteration claims are recomputed
+in a changed context (the merged tree no longer matches the frozen claims), and the stop gate
+repeatedly flags the session as falsely complete.
+
+**Pattern to recover:** rebuild the bundle from the current `evidence.json` via
+`record-evidence`, then re-advance state. Do not hand-edit the frozen bundle; regenerate it
+from current evidence so the claims match the post-merge tree.
+
+## 3. Evidence must be executable in the CI/backstop context
+
+Evidence checks are re-run by CI and by the backstop reconciler, not just locally. Several
+checks passed locally but failed in CI because they were not executable in that context. Keep
+evidence portable:
+
+- Check commands must be **repo-root-relative** and must reference files that live **inside
+  the session directory** (for example under `verify-scratch/`), never an agent's private
+  scratchpad that does not exist in CI.
+- Summaries must be **runnable commands**. For prose that is not a command, use the
+  `true # ...` form so the "command" still exits zero when executed.
+- Reconcilable claims need **manifest-exact bare labels** — no environment-variable
+  annotations on the label — so the reconciler can match them against the manifest.
+- Keep reconcilable sets **small**. `runCommand` enforces a 180-second per-command timeout;
+  heavy test suites trip that timeout in CI while passing locally. Split or scope the suite
+  so each reconciled command finishes well under the limit.
+
+## 4. Critique semantics and resolved sessions
+
+Under the current validator rule, a top-level `pass` verdict forbids any `fail` or
+`not_verified` member claims. Consequently a **resolved** session cannot retain historical
+`verdict: fail` critiques — the validator rejects the bundle even though the failure was
+genuine and later fixed.
+
+**Reconciliation pattern:** move the historical failing critique to `superseded` and then
+`comment`, preserving the original outcome in the summary text so the audit trail survives.
+The `fail` verdict is not deleted from history; it is superseded, and the summary records
+what the original verdict was and how it was resolved.
+
+This deserves an explicit convention note, and possibly a validator/schema affordance for a
+first-class `superseded_by` relationship so the original verdict can be preserved structurally
+rather than only in prose. That tooling gap is filed as a follow-up issue (see below).
+
+## 5. Shim scope coupling in cross-repo schema migrations
+
+Surface 2.0's read-tolerance shim (the compatibility layer that accepts both the old
+`Claim.surface` and new `Claim.facet` shapes) only protects consumers that go through
+**Surface's JavaScript API**. Anything that validates against the hachure JSON Schema
+**directly** bypasses the shim and breaks. During this program that included:
+
+- Flow's Ajv gate (validates bundles against the raw schema),
+- Veritas's schema dependency,
+- Flow Agents `attach-evidence` using a **vendored** copy of the old hachure schema.
+
+Each of these had to bump hachure **in lockstep** with the Surface bump; the shim did not
+cover them.
+
+**Rule for future cross-repo schema migrations:** map **both** axes before you start —
+(a) the JS-API consumers, which the shim protects, and (b) the raw-schema validators, which
+it does not. Every raw-schema validator (including vendored schema copies) must be bumped in
+the same coordinated wave. See Surface [#105](https://github.com/kontourai/surface/pull/105),
+Veritas [#109](https://github.com/kontourai/veritas/pull/109), Flow
+[#101](https://github.com/kontourai/flow/pull/101), Survey
+[#100](https://github.com/kontourai/survey/pull/100), and Flow Agents
+[#277](https://github.com/kontourai/flow-agents/pull/277) for the coordinated set.
+
+## 6. Release mechanics
+
+Two independent release-mechanics traps surfaced:
+
+- **release-please ignores `chore:` commits.** Flow [#100](https://github.com/kontourai/flow/pull/100)
+  shipped real functionality (the Surface 2.0 migration) as a `chore:` commit, so
+  release-please never cut a release and the functionality sat unreleased until a subsequent
+  `feat!:` signal commit ([#101](https://github.com/kontourai/flow/pull/101)) triggered the
+  release. If a `chore:` PR changes shipped behavior, it will not be released on its own —
+  pair it with a `feat:`/`fix:`/`feat!:` signal commit or it stays dark.
+- **GitHub App installation repo-access is a separate axis from org secrets/vars grants.**
+  A Traverse release was blocked because the GitHub App was not installed on that repository,
+  which is distinct from whether org-level secrets and variables were granted. App
+  installation repo-access is org-owner-only, so this class of block cannot be self-resolved
+  by the release author and must be escalated to an org owner.
+
+## 7. Runtime-artifact hygiene
+
+Bulk worktree operations reset filesystem `mtime`s en masse. Any recency heuristic based on
+`mtime` is therefore unreliable after a sweep. Session recency must be read from
+`state.json`'s `updated_at` field, not from file `mtime` (established during the WS6 sweep —
+the WS6 sweep was the pass that audited and pruned stale local runtime sessions).
+
+The `workflow-artifact-cleanup-audit` CLI is **dry-run only**: it classifies sessions into
+active WIP, cleanup candidates, terminal done records, active learning follow-ups, and
+invalid sidecars, but it does not delete, archive, or rewrite anything and has no apply mode.
+An apply mode may be worth filing so cleanup can be executed, not just recommended. That
+tooling gap is filed as a follow-up issue (see below).
+
+## 8. Gate operations
+
+Operational discipline for running gates and merging, learned the hard way during parallel
+waves:
+
+- **Never dispatch fixes while gates are running.** Wait for **all** outstanding gates to
+  finish before acting on any result; dispatching a fix mid-run races the gate and produces
+  confusing, interleaved state.
+- **Run mutation testing only in scratch copies**, never against the working tree the gate is
+  evaluating.
+- **Keep `gh pr merge` stderr visible.** Do not swallow it; the merge failure reasons you
+  need (behind-base, pending checks, blocked) come through stderr.
+- Use `gh pr merge --auto` for pending checks so the merge lands when checks go green, and use
+  branch update (`update-branch`) when a PR is `BEHIND` the base.
+
+## Follow-up tooling issues
+
+Findings 4 and 7 imply concrete Flow Agents tool changes. Both were checked against the open
+issue list for duplicates and filed fresh:
+
+- Finding 4 → [flow-agents#282](https://github.com/kontourai/flow-agents/issues/282): a
+  validator/schema affordance for `superseded_by` on critique claims, so a resolved session
+  can preserve a historical `fail` verdict structurally rather than only in the summary prose.
+- Finding 7 → [flow-agents#283](https://github.com/kontourai/flow-agents/issues/283): an
+  apply mode for `workflow-artifact-cleanup-audit`, so the dry-run classification can be
+  executed.
+
+Both issues were checked against the open issue list before filing; no duplicates existed.

package/docs/migrations.md

@@ -6,11 +6,12 @@ title: Migrations
 
 ## Unreleased
 
-- Workflow runtime artifacts now live under `.flow-agents/` instead of
-  `.agents/flow-agents/`. Move any local session directories, sidecars, or
-  `current.json` pointers you want to keep into the new root. Runtime state
-  remains ignored; promote durable outcomes into docs, source, schemas, or
-  provider records before merge.
+- Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
+  of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
+  Move any local session directories, sidecars, or `current.json` pointers you
+  want to keep into the new root. Runtime readers do not fall back to old roots.
+  Runtime state remains ignored; promote durable outcomes into docs, source,
+  schemas, or provider records before merge.
 - Flow Agents setup no longer accepts Console bearer tokens as CLI arguments.
   Replace `--console-token TOKEN` with `--console-token-file PATH` for
   headless installs, or use the prompted `flow-agents init` flow. Interactive

package/docs/north-star.md

@@ -206,7 +206,7 @@ Exit criteria:
 
 - A workflow can resume from artifacts without relying on the model remembering prior turns.
 - Goal Fit, evidence status, and next action can be read mechanically.
-- Multiple agents can share one workflow root by resolving `.flow-agents/current.json` and appending agent-local events instead of racing on root state.
+- Multiple agents can share one workflow root by resolving `.kontourai/flow-agents/current.json` and appending agent-local events instead of racing on root state.
 
 ## Phase 3: Add Just-In-Time Guidance
 
@@ -261,7 +261,7 @@ Tasks:
 - Add promotion gates so guidance becomes stricter only after evidence shows it helps.
 - Make dashboards answer whether Flow Agents is improving outcomes over time.
 - Dogfood the workflow artifacts on Flow Agents changes: each substantial pass should produce sidecars, run artifact validation, delegate critique, update durable docs, and route accepted critique into the next slice. **Started:** `npm run workflow:sidecar -- dogfood-pass` records evidence, required critique, optional release readiness, optional learning, state, and handoff in one fail-closed validated pass.
-- Automatically create or select the current session artifact so self-validation does not depend on the user or orchestrator hand-picking `.flow-agents/<slug>`. **Started:** `npm run workflow:sidecar -- ensure-session` creates or selects a delivery session artifact plus initial state, acceptance, and handoff sidecars.
+- Automatically create or select the current session artifact so self-validation does not depend on the user or orchestrator hand-picking `.kontourai/flow-agents/<slug>`. **Started:** `npm run workflow:sidecar -- ensure-session` creates or selects a delivery session artifact plus initial state, acceptance, and handoff sidecars.
 
 Exit criteria:
 

package/docs/operating-layers.md

@@ -18,7 +18,7 @@ For the concrete directory-by-directory source map, generated output policy, run
 | Skills | Reusable procedures an agent can invoke when a task matches | Always-on policy, credentials, or long-lived memory | Agent Skills / `SKILL.md` |
 | Powers | Tool bundles, MCP configs, and activation guidance | Workflow gates or repo-specific policy semantics | MCP, OpenAPI, OAuth/OIDC |
 | Agents | Role prompts, delegation boundaries, and scoped tool access | Generic task procedures that should be skills | Harness-native subagents/profiles |
-| Workflows | Durable state, gates, handoffs, acceptance criteria, and phase transitions | Domain-specific knowledge records or tool internals | JSON Schema sidecars plus Markdown summaries |
+| Workflows | Resumable state, gates, handoffs, acceptance criteria, and phase transitions | Domain-specific knowledge records or tool internals | JSON Schema sidecars plus Markdown summaries |
 | Knowledge | People, organizations, meetings, decisions, commitments, notes, and follow-ups | Verification verdicts or runtime telemetry | CommonMark, JSContact, iCalendar, JMAP, WebVTT/SRT, JSON-LD |
 | Evidence | Proof, telemetry, findings, evals, provenance, and quality outcomes | User-facing procedure instructions | OpenTelemetry, SARIF, CycloneDX, SLSA, JSON Schema |
 
@@ -37,7 +37,8 @@ Governance tools such as Veritas belong at the Evidence boundary. Flow Agents sh
 | `kits/` | Flow Kits | Kit Catalog entries, Flow Kit manifests, Flow Definitions, and supporting assets. Builder Kit is the first proof point. |
 | `prompts/` | Skills / Rules | Saved invocations. Promote repeatable procedures into skills when they grow stable. |
 | `docs/workflow-*.md` | Workflows | Human-readable workflow contracts and usage guidance. |
-| `.flow-agents/` | Workflows | Cross-session task artifacts. Runtime state stays local and ignored; durable outcomes are promoted into docs, source, schemas, or provider records before merge. |
+| `.kontourai/flow-agents/` | Workflows | Non-durable cross-session task artifacts and generated projections. Runtime state stays local and ignored; durable outcomes are promoted into docs, source, schemas, or provider records before merge. |
+| `.flow-agents/` | Workflows | Flow Agents-owned durable config/install state when a distribution explicitly owns that path. Not a runtime artifact fallback. |
 | `scripts/` | Evidence / Workflows / Packaging | Validation, build, telemetry, hooks, and artifact tooling. |
 | `src/` | Workflows / Evidence / Packaging | TypeScript CLI, runtime adapter, Flow Kit, shared library, build, validation, context-map, packaging, and CLI helper source compiled into `build/src/`. |
 | `evals/` | Evidence | Static, behavioral, integration, and acceptance checks. |
@@ -80,7 +81,7 @@ Builder Kit evidence gates can reference Surface trust state without naming a pr
 Workflow artifacts have their own lifecycle policy:
 https://github.com/kontourai/flow-agents/blob/main/docs/workflow-artifact-lifecycle.md
 
-Use `.flow-agents/<slug>/` for local runtime/session state. If in-progress planning needs review or handoff, promote the durable decision, behavior, and evidence summary into normal docs or provider records before merge; keep runtime artifacts out of git.
+Use `.kontourai/flow-agents/<slug>/` for local runtime/session state. Keep `.flow-agents/` for explicit durable Flow Agents config/install state. If in-progress planning needs review or handoff, promote the durable decision, behavior, and evidence summary into normal docs or provider records before merge; keep runtime artifacts out of git.
 
 If a proposed artifact seems to belong to multiple layers, split it. For example, a dependency-checking capability may have:
 

package/docs/repository-structure.md

@@ -10,7 +10,7 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
 
 - Edit canonical source in the repo root areas listed below, then regenerate derived output with the documented commands.
 - Do not edit `dist/`, `build/`, or `_site/` by hand. They are generated from tracked source.
-- Do not commit local runtime state from `.flow-agents/<slug>/`, `.kontourai/`, `.codex/`, `.claude/`, `.omx/`, `.promptfoo/`, `.telemetry/`, `.surface/`, generated `.veritas/` output, or tool caches; intentionally tracked `.veritas/` governance/config remains durable source.
+- Do not commit local runtime state from `.kontourai/flow-agents/<slug>/`, `.codex/`, `.claude/`, `.omx/`, `.promptfoo/`, `.telemetry/`, `.surface/`, generated `.veritas/` output, or tool caches; intentionally tracked `.veritas/` governance/config remains durable source.
 - Runtime workflow artifacts stay local and ignored; promote reviewable or durable outcomes to docs, source, schemas, or provider records before merging to `main`.
 - Treat generated exports and installed runtime config as products of `packaging/manifest.json`, `src/tools/build-universal-bundles.ts`, `scripts/install-*.sh`, and the source directories they copy.
 - Use `.kontourai/` for non-durable local or generated Kontour workspace state. Keep durable tracked files in intuitive product-owned paths such as `.veritas/`, `.flow/`, `.agents/`, `.claude/commands`, and `docs/`; existing transition ignores remain during migration.
@@ -33,15 +33,15 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
   docs/                        # durable docs and GitHub Pages source
   integrations/                # optional external integration config
   dist/ build/ _site/           # generated output; ignored
-  .flow-agents/ .kontourai/ .codex/ .claude/ ... # local runtime state; ignored by default
+  .kontourai/ .flow-agents/ .codex/ .claude/ ... # local/generated or installed state; ignored by default
 ```
 
 ## Top-Level Inventory
 
 | Path | Classification | Source of truth | Generated or runtime policy | Safe cleanup rule |
 | --- | --- | --- | --- | --- |
-| `.flow-agents/` | runtime state | Workflow tools write local session artifacts. | Ignored. | Do not commit task runtime roots; promote durable decisions to docs, source, schemas, or providers before merge. |
-| `.kontourai/` | local/generated workspace state | Local Kontour tools and developer workflows. | Ignored. | Safe local cleanup when no active workflow needs it; durable source and decisions stay in product-owned tracked paths. |
+| `.kontourai/` | local/generated workspace state | Local Kontour tools and developer workflows, including `.kontourai/flow-agents/<slug>/` runtime sessions. | Ignored. | Safe local cleanup when no active workflow needs it; durable source and decisions stay in product-owned tracked paths. |
+| `.flow-agents/` | durable local Flow Agents state | Explicit Flow Agents config/install records when documented. | Ignored unless a repo-specific contract intentionally tracks a durable file. | Do not use for non-durable workflow sessions; migrate old runtime artifacts into `.kontourai/flow-agents/`. |
 | `.claude/` | installed runtime config | Generated bundle or local runtime install. | Ignored. | Reinstall from `dist/claude-code/` instead of editing as source. |
 | `.codex/` | installed runtime config | Generated bundle or local runtime install. | Ignored. | Reinstall from `dist/codex/` or `scripts/install-codex-home.sh`; do not treat local hooks as canonical. |
 | `.githooks/` | canonical repo tooling | Tracked repository hook scripts. | Source, not runtime agent hooks. | Keep compatible with `npm run setup:repo-hooks` and `npm run validate:repo-hooks --`. |
@@ -115,7 +115,7 @@ The package requires Node `>=22`, and GitHub Actions runs CI on Node 22. Keep `@
 
 `.codex/` and `.claude/` at the repo root are installed runtime configuration surfaces. They can be useful for local testing, but canonical hook scripts and runtime config live in `scripts/hooks/`, `context/`, `packaging/`, and generated bundle output. The stale local `.codex/hooks.json` incident came from treating an installed runtime file as if it were canonical source. The fix is to regenerate or reinstall runtime config and update the canonical builder/install sources when behavior must change.
 
-`.flow-agents/<slug>/` is workflow working memory. Keep plans, sidecars, evidence, and handoffs there while work is active. Promote stable outcomes into `docs/`, schemas, source, or provider records before final acceptance.
+`.kontourai/flow-agents/<slug>/` is workflow working memory. Keep plans, sidecars, evidence, and handoffs there while work is active. `.flow-agents/` is reserved for Flow Agents-owned durable config/install state when explicitly documented; do not use it for non-durable sessions. Promote stable outcomes into `docs/`, schemas, source, or provider records before final acceptance.
 
 Across Kontour repos, `.kontourai/` is the simple ignored home for non-durable local/generated workspace state. It is not a durable source root. Keep durable governance, Flow config, agent source, command source, and documentation in the product-owned tracked paths where developers expect them, including `.veritas/`, `.flow/`, `.agents/`, `.claude/commands`, and `docs/`. Existing transition ignores such as `.flow-agents/`, `.kontour/`, `.surface/`, `.veritas/evidence/`, `.flow/runs/`, and `.telemetry/` remain in place during migration.
 

package/docs/skills-map.md

@@ -82,7 +82,7 @@ This view shows how each phase is composed. The left rail is the durable phase s
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
       <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.flow-agents/&lt;slug&gt;/</code>.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.kontourai/flow-agents/&lt;slug&gt;/</code>.</p></section>
     </div>
   </article>
   <article class="phase-row">
@@ -137,15 +137,15 @@ The highest-leverage future extractions are likely `shape-work`, `test-map`, `sc
 
 Each workflow phase ends with an explicit gate and durable artifact:
 
-- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
-- `idea-to-backlog` writes `.flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
-- `pull-work` writes `.flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
-- `plan-work` and `deliver` write `.flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
+- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
+- `idea-to-backlog` writes `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
+- `pull-work` writes `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
+- `plan-work` and `deliver` write `.kontourai/flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
 - `review-work` writes reviewer artifacts when available and updates `critique.json` with quality, security, architecture, standards, and resolution state.
 - `verify-work` writes verification artifacts and updates `evidence.json` with behavior evidence mapped to acceptance criteria.
-- `evidence-gate` writes `.flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
-- `release-readiness` writes `.flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
-- `learning-review` writes `.flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
+- `evidence-gate` writes `.kontourai/flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
+- `release-readiness` writes `.kontourai/flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
+- `learning-review` writes `.kontourai/flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
 
 Core gates:
 

package/docs/spec/runtime-hook-surface.md

@@ -86,8 +86,8 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 **Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls)
 
 **Inputs consumed**:
-- `.flow-agents/<slug>/state.json` — current workflow phase and status
-- `.flow-agents/<slug>/critique.json` — open critique findings
+- `.kontourai/flow-agents/<slug>/state.json` — current workflow phase and status
+- `.kontourai/flow-agents/<slug>/critique.json` — open critique findings
 - `docs/context-map.md` — structure hint for repo navigation
 
 **Decision contract**: Non-blocking. Always exits 0. Appends steering text to the agent's context via `additionalContext` in the hook response. Does not block any action. It re-grounds the active workflow goal (status, phase, recorded next step) at the start of every user turn — not only for flagged/blocked states — and on `SessionStart`, which fires after context compaction and on resume. This is the mechanism that keeps an in-flight goal alive across context loss instead of relying on the model voluntarily re-reading the sidecar.
@@ -125,12 +125,14 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 **Canonical trigger event**: `stop`
 
 **Inputs consumed**:
-- `.flow-agents/<slug>/*.md` — workflow artifact files (scanned for active status, DOD, Goal Fit Gate sections)
-- `.flow-agents/<slug>/state.json` — workflow phase and next action
-- `.flow-agents/<slug>/evidence.json` — verification verdict and NOT_VERIFIED gaps
-- `.flow-agents/<slug>/critique.json` — critique status and open findings
-- `.flow-agents/<slug>/command-log.jsonl` — the deterministic capture log written by the Evidence Capture policy (see §2.5); cross-referenced against `evidence.json` claimed-pass command checks
-- `.flow-agents/<slug>/acceptance.json` — acceptance criteria; a criterion's `command`-kind `evidence_ref` (`excerpt`) is the most-trusted backstop command
+- `.kontourai/flow-agents/<slug>/*.md` — workflow artifact files (scanned for active status, DOD, Goal Fit Gate sections)
+- `.kontourai/flow-agents/<slug>/state.json` — workflow phase and next action
+- `.kontourai/flow-agents/<slug>/evidence.json` — verification verdict and NOT_VERIFIED gaps
+- `.kontourai/flow-agents/<slug>/critique.json` — critique status and open findings
+- `.kontourai/flow-agents/<slug>/command-log.jsonl` — the deterministic capture log written by the Evidence Capture policy (see §2.5); cross-referenced against `evidence.json` claimed-pass command checks
+- `.kontourai/flow-agents/<slug>/acceptance.json` — acceptance criteria; a criterion's `command`-kind `evidence_ref` (`excerpt`) is the most-trusted backstop command
+- `.kontourai/flow-agents/current.json` (`active_flow_id`/`active_step_id`) — when present, resolves the active kit FlowDefinition's gate `expects[]` via the compiled `build/src/lib/flow-resolver.js` (`loadActiveFlowStep`, ADR 0016 Abstraction A P-c); requires `build/` to exist and fails open to the legacy `workflow.*`-only behavior when it does not (the `hasBuild` guard — the same fail-open pattern already used for the trust-bundle validator)
+- The active kit's `kits/<kit>/flows/<flow>.flow.json` — the FlowDefinition file `current.json` resolves against; the matching gate's `expects[].bundle_claim.claimType` values become the declared claim types enforced for the active step (see FlowDefinition-driven claim selection below)
 - `FLOW_AGENTS_GOAL_FIT_MODE` env var — `block` | `warn` | `off` (the legacy `FLOW_AGENTS_GOAL_FIT_STRICT=true` is an alias for `block`)
 - `FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS` env var — consecutive-identical-block cap before the escape hatch releases (default 3)
 - `FLOW_AGENTS_GOAL_FIT_BACKSTOP` env var — `block` (default) | `off`/`warn` | `skip`; controls the capture backstop re-run (see Capture cross-reference below)
@@ -143,6 +145,8 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 - `off`: silent (exits 0, no stderr).
 - Escape hatch: in `block` mode the same goal-fit gap is refused up to `FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS` (default 3) consecutive times, then released (exit 0 with a loud notice) so a genuinely-unsatisfiable goal cannot trap the agent. A changing gap resets the streak.
 
+**FlowDefinition-driven claim selection (ADR 0016 Abstraction A)**: When `current.json` resolves an active flow/step, `bundleEnforcement`'s claim-selection predicate (`isSelectedClaim`) is a **union**: `workflow.*`-prefixed claims are always selected as a baseline floor, and the active gate's declared `claimType` set (from `expects[].bundle_claim.claimType`, e.g. `builder.verify.tests`) is selected *in addition to* that floor — never instead of it. An earlier design used a pure if/else (declared types selected only when a FlowDefinition was active, with no `workflow.*` fallback) and was found in PR #215 to compose into a HIGH-severity gate-bypass chain: a forged `current.json` pointing at an `expects: []` flow made the if/else select zero claims, silently skipping all re-derivation, tamper-detection, and high/critical enforcement. The union floor closed that chain and is a **permanent** design decision, not a transitional step toward the if/else — see [ADR 0016](../adr/0016-three-hard-boundary-model.md) and the PR #215 post-mortem in [ADR 0015](../adr/0015-flow-flow-agents-boundary-reconciliation.md). Consequently, an active FlowDefinition whose gate resolves to an **empty** `expects[]` is always a `HARD_BLOCK` (`gate misconfiguration: active FlowDefinition has empty expects[]...`) — an empty declared set is treated as a possible tampered flow definition, never as a legitimately-empty gate that quietly enforces nothing beyond the floor.
+
 **Capture cross-reference (capture-first determinism)**: For each `evidence.checks[]` of `kind:"command"` claiming `status:"pass"` that carries a `command`, the gate cross-references the deterministic capture log (`command-log.jsonl`, §2.5) *before* trusting the model's claim:
 
 1. **Log shows the command ran and FAILED** → this is a caught false-completion → a blocking goal-fit gap (feeds the existing block/`MAX_BLOCKS` machinery).
@@ -186,9 +190,9 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 **Inputs consumed**:
 - `tool_name` + `tool_input.command` — identifies a command/shell execution (a command string present, with a command-shaped tool name; when no tool name is present but a command string is, it is still captured).
 - `tool_response` / `tool_output` / `error` — the host tool result (per §1, `postToolUse`); the source of the deterministically-observed outcome.
-- `.flow-agents/current.json` (`active_slug` / `artifact_dir`) then newest-mtime `state.json` — resolves the active artifact dir, the same way Workflow Steering and Stop-Goal-Fit do.
+- `.kontourai/flow-agents/current.json` (`active_slug` / `artifact_dir`) then newest-mtime `state.json` — resolves the active artifact dir, the same way Workflow Steering and Stop-Goal-Fit do.
 
-**Output**: appends one JSON object per line to `.flow-agents/<slug>/command-log.jsonl`:
+**Output**: appends one JSON object per line to `.kontourai/flow-agents/<slug>/command-log.jsonl`:
 
 ```json
 { "command": "npm test", "observedResult": "pass", "exitCode": 0, "capturedAt": "2026-06-23T00:00:00Z", "source": "postToolUse-capture" }
@@ -561,7 +565,7 @@ The CLI command is:
 flow-agents kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
 ```
 
-This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).
+This writes activated flow files to `.kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).
 
 ### 9.2 Steering context surfacing (AC2)
 
@@ -572,7 +576,7 @@ This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>
 ```
 hooks = FlowAgentsHooks(workspace=".")
 system_prompt = base_prompt + hooks.steering_context()
-# steering_context() includes KIT FLOWS section if .flow-agents/runtime/strands/flows/ is populated
+# steering_context() includes KIT FLOWS section if .kontourai/flow-agents/projections/strands/flows/ is populated
 ```
 
 **TypeScript usage**:
@@ -580,14 +584,14 @@ system_prompt = base_prompt + hooks.steering_context()
 ```typescript
 const hooks = new FlowAgentsHooks({ workspace: "." });
 const systemPrompt = basePrompt + hooks.steeringContext();
-// steeringContext() includes KIT FLOWS section if .flow-agents/runtime/strands/flows/ is populated
+// steeringContext() includes KIT FLOWS section if .kontourai/flow-agents/projections/strands/flows/ is populated
 ```
 
 ### 9.3 Co-existence with codex-local
 
 The `codex-local` and `strands-local` runtime directories are independent:
 
-- `codex-local` writes to `.flow-agents/runtime/codex/`
-- `strands-local` writes to `.flow-agents/runtime/strands/`
+- `codex-local` writes to `.kontourai/flow-agents/projections/codex/`
+- `strands-local` writes to `.kontourai/flow-agents/projections/strands/`
 
 Running either adapter does not affect the other's runtime directory. Both adapters skip non-flow asset classes (skills, docs, adapters, evals, assets) with `reason: "asset class is diagnostic-only for <adapter>"`.