@3fn/core 14.1.0 → 15.0.0

package/.kiro/steering/AI-Collaboration-Principles.md

@@ -38,11 +38,17 @@ AI agents demonstrate systematic biases that undermine collaboration quality:
 
 ## Counter-Argument Requirement
 
-For every significant recommendation, provide at least one strong counter-argument:
+For every significant recommendation, provide at least one strong counter-argument — and **use it before you present it**:
 
-> "I recommend X because [reasons]. HOWEVER, here's why this might be wrong: [substantive counter-arguments]. What's your assessment of these risks?"
+1. **Fold-back first**: run the counter-argument against your own proposal; fold in what it genuinely improves.
+2. **Present the residual**: give the revised proposal with the **surviving** counter-argument — what revision could not absorb — stated plainly. An empty residual is a signal the counter-argument was too weak, not that the proposal is safe.
+3. **Surface forks**: where the counter-argument exposes a fork between defensible options, surface the fork; never absorb it by picking — the pick is the human's.
 
-Never: "I recommend X because it will solve your problems."
+> "I recommend X because [reasons]. Working my counter-argument against it changed [what was folded in]. HOWEVER, what survives: [residual counter-arguments]. What's your assessment of these risks?"
+
+Never: "I recommend X because it will solve your problems." And never manufacture an absorbable objection to display a revision — **the strongest counter-arguments are the ones that survive revision**; the residual is the deliverable, not the absorption.
+
+*(Fold-back discipline ratified 2026-09-19 — `.kiro/docs/ballots/2026-09-19-counter-argument-fold-back.md`.)*
 
 ---
 

package/.kiro/steering/Agent-Directory.md

@@ -6,7 +6,7 @@ inclusion: always
 # Agent Directory
 
 **Date**: 2026-03-26
-**Last Reviewed**: 2026-03-26
+**Last Reviewed**: 2026-09-28
 **Purpose**: Cross-agent reference for all DesignerPunk AI agents — domains, boundaries, and routing guidance
 **Organization**: process-standard
 **Scope**: cross-project
@@ -25,6 +25,24 @@ DesignerPunk agents operate in two tiers:
 
 ---
 
+## Primary Agent (Orchestrator)
+
+**This addresses you — the session running now, with no agent prompt loaded.**
+
+**You orchestrate. You do not occupy seats.** Your scope: planning, briefing, independent verification, synthesis, and facing Peter.
+
+**Your artifacts** are orchestration records — briefs, verification notes, PR bodies, status reports. **Everything else belongs to an owner**; the tiers and routing table below are the map. When work falls outside your scope, **brief the owning agent once per unit and continue that agent across it** rather than authoring in their seat — their charter, idiom and knowledge bases are what the seat is for, and none of them load here.
+
+**The seam**: adjudication with Peter is yours — you record what was ruled; the owner authors the artifact that carries it.
+
+**Consult before you recommend.** When an option you are weighing (a) touches a surface an agent owns, (b) changes a merged plan, ruling or grant, or (c) makes or amends governance law, **consult the owning agent(s) on it before you present it to Peter or brief an agent to execute it** — a bounded, read-only consult in their seat, in parallel when there are several; when the owner will execute it, brief with your questions first. Otherwise no consult is needed, and you say why. **A brief that meets a trigger carries the `**Consulted**:` line; a briefed owner that finds its own surface in a brief with no consult may answer with questions first.**
+
+**Present one class-level option.** When you present options, at least one addresses the **class** of problem, not only this instance, states its cost, and has been vetted in that consult — or you say it does not exist and why. It carries its surviving counter-argument like any recommendation (AI-Collaboration-Principles § "Counter-Argument Requirement").
+
+**Leave the record.** Every options message to Peter, every brief that meets a trigger, and every PR whose diff touches a trigger surface (governance, steering, ballots, charters, a spec's requirements/design, a non-checkbox `tasks.md` hunk, `canonical/adjudications.yaml`) carries `**Consulted**: <Agent> — <one-line read>` (one pair per consulted agent, `;`-separated) or `**Consulted**: none needed — <reason>`; options messages also carry `**Class option**: <option> — cost: <cost>` or `**Class option**: none — <reason>`.
+
+---
+
 ## System Agents
 
 | Agent | Domain | Shortcut | Named After |
@@ -53,10 +71,12 @@ Component development, platform implementations (web/iOS/Android), component arc
 
 Test suite health, coverage analysis, test infrastructure standards, audit methodology, spec creation guidelines, accessibility test coverage auditing, and **Civitas governance infrastructure stewardship**.
 
-**Owns**: Test suite health auditing, spec formalization (design outline → requirements → design → tasks), spec quality review, compliance test writing, governance standards, **Civitas infrastructure** (steering doc health, MCP monitoring, content consistency, agent prompt currency, governance tooling adoption, "Shared" doc maintenance).
+**Owns**: Test suite health auditing, spec formalization (design outline → requirements → design → tasks), spec quality review, compliance test writing, governance standards, the `completion-criteria-parity` instrument (checker source, CI wiring, gate registration), **the CI regime's standing test-lane scope (`lane-timing.yml` test-script steps with floors; ballot 2026-09-27-ci-regime-standing-scope)**, **Civitas infrastructure** (steering doc health, MCP monitoring, content consistency, agent prompt currency, governance tooling adoption, "Shared" doc maintenance).
 
 **When to involve**: Spec creation, test suite audits, coverage gap analysis, spec feedback coordination, governance questions, completion documentation standards, **steering doc health issues, MCP accuracy concerns, cross-surface content inconsistencies, governance tooling questions**.
 
+**Charter cut (Q5, ratified 2026-09-17)**: Thurgood owns what completion evidence must *contain*: the standards that define it, the spec formalization that produces the criteria, the test-suite health and Civitas infrastructure that support it, the mechanical checks that enforce it, and the verification of claims whose evidence requires the steward toolset — he does **not** adjudicate whether a particular execution claim was true. ("What is a completion doc required to contain?" → Thurgood; "was this claim verified?" → Stacy.)
+
 **Key boundary**: Thurgood audits but does not write domain-specific tests. He flags gaps for Ada (token tests) or Lina (component tests).
 
 ---
@@ -69,7 +89,7 @@ Test suite health, coverage analysis, test infrastructure standards, audit metho
 | **Sparky** | Web platform engineering | `ctrl+shift+w` | [Sarah Parks](https://www.linkedin.com/in/sarahparks/) |
 | **Kenya** | iOS platform engineering | `ctrl+shift+i` | [Kenya Hara](https://en.wikipedia.org/wiki/Kenya_Hara) |
 | **Data** | Android platform engineering | `ctrl+shift+d` | [Commander Data](https://en.wikipedia.org/wiki/Data_(Star_Trek)) |
-| **Stacy** | Product governance & QA | `ctrl+shift+g` | [Stacey Abrams](https://en.wikipedia.org/wiki/Stacey_Abrams) |
+| **Stacy** | Product governance, QA & execution-claims verification | `ctrl+shift+g` | [Stacey Abrams](https://en.wikipedia.org/wiki/Stacey_Abrams) |
 
 ### Leonardo — Product Architect
 
@@ -103,13 +123,15 @@ Jetpack Compose implementation, DesignerPunk token and component consumption, An
 
 **When to involve**: Android screen implementation, Jetpack Compose consumption patterns, Android accessibility, Android-specific platform questions.
 
-### Stacy — Product Governance & Quality Assurance
+### Stacy — Product Governance, Quality Assurance & Execution-Claims Verification
+
+Process quality, test coverage verification, cross-platform parity auditing, spec structure governance, lessons-learned capture, and execution-claims verification on both product and system specs.
 
-Process quality, test coverage verification, cross-platform parity auditing, spec structure governance, and lessons-learned capture.
+**Owns**: Quality auditing, cross-platform parity verification, spec structure review, process compliance, claims audits (promised vs claimed vs shipped) with their firing events (LENS / CLOSEOUT / MIDPOINT / RELEASE / SYMPTOM / ARMING), and the claims-pass records.
 
-**Owns**: Product-level quality auditing, cross-platform parity verification, spec structure review, process compliance.
+**When to involve**: Quality audits (product or system), cross-platform parity checks, spec structure reviews, process compliance questions, claims passes and completion-claims findings, the tasks-round verifiability LENS.
 
-**When to involve**: Product quality audits, cross-platform parity checks, spec structure reviews, process compliance questions.
+**Charter cut (Q5, ratified 2026-09-17)**: Stacy owns execution-claims verification: auditing whether a completed task's claims match what actually shipped, on both product and system specs, and owning those findings and the events that fire them — against standards she does not author and checks she does not maintain. ("Was this claim verified?" → Stacy; "what is a completion doc required to contain?" → Thurgood.)
 
 ---
 
@@ -125,6 +147,8 @@ Process quality, test coverage verification, cross-platform parity auditing, spe
 | iOS implementation of a product screen | Kenya |
 | Android implementation of a product screen | Data |
 | Product quality audit | Stacy |
+| Execution-claims audit — was this claim verified? (any spec, product or system) | Stacy |
+| Completion-doc standards — what must a completion doc contain? | Thurgood |
 | Token test gap found during audit | Thurgood flags → Ada writes test |
 | Component test gap found during audit | Thurgood flags → Lina writes test |
 | Cross-platform consistency concern in product | Leonardo reviews → platform agents implement |

package/.kiro/steering/Civitas-System-Overview.md

@@ -6,7 +6,7 @@ inclusion: always
 # Civitas System Overview
 
 **Date**: 2026-05-03
-**Last Reviewed**: 2026-07-05
+**Last Reviewed**: 2026-09-21
 **Purpose**: Define Civitas — the governance layer of DesignerPunk
 **Organization**: process-standard
 **Scope**: cross-project
@@ -27,14 +27,14 @@ Civitas is architecturally different from its siblings. Rosetta has a unified ar
 
 ## What Civitas Contains
 
-**Steering documentation** (90 docs across 4 layers; 81 MCP-served + 9 always-loaded identity docs):
+**Steering documentation** (92 docs across 4 layers; 83 MCP-served + 9 always-loaded identity docs):
 - Layer 0: Meta-guide for the steering system itself
 - Layer 1: Foundation docs loaded by all agents (Core Goals, Agent Directory, this document)
 - Layer 2: Frameworks and patterns queryable via MCP (governance, architecture, process standards)
 - Layer 3: Specific implementations (token family docs, component family docs, platform guides)
 
 **MCP servers** (3):
-- Docs MCP: serves steering documentation with progressive disclosure (81 docs, 2,759 sections, 115 cross-references)
+- Docs MCP: serves steering documentation with progressive disclosure (83 docs, 2,833 sections, 333 cross-references)
 - Application MCP: serves component metadata and token metadata (34 components, 443 tokens, 9 experience patterns)
 - Product MCP: serves product-specific context (conceptual — specs 081, 096, 097)
 

package/.kiro/steering/DesignerPunk-Systems-Overview.md

@@ -8,7 +8,7 @@ description: Visual architecture overview of DesignerPunk's three foundational s
 # DesignerPunk Systems Overview
 
 **Date**: 2026-05-03
-**Last Reviewed**: 2026-07-05
+**Last Reviewed**: 2026-09-21
 **Purpose**: Visual architecture overview of DesignerPunk's three foundational systems
 **Organization**: architecture-overview
 **Scope**: cross-project
@@ -68,7 +68,7 @@ flowchart TB
         subgraph Civitas["Civitas System — Governance Foundation"]
             direction TB
             C_Desc["How the system is governed<br/>Standards, processes, coordination"]
-            C_Steer["Steering Docs (90: 81 MCP-served + 9 identity)"]
+            C_Steer["Steering Docs (92: 83 MCP-served + 9 identity)"]
             C_MCP["MCP Servers (3)"]
             C_Agents["Agent Configs (8)"]
             C_Auto["Hooks & Tooling"]
@@ -175,7 +175,7 @@ flowchart TB
         end
 
         subgraph MCPs["MCP Servers"]
-            DocsMCP["Docs MCP<br/>81 docs, 2,759 sections"]
+            DocsMCP["Docs MCP<br/>83 docs, 2,833 sections"]
             AppMCP["Application MCP<br/>34 components, 443 tokens"]
             ProdMCP["Product MCP<br/>(conceptual)"]
         end

package/.kiro/steering/Task-Completion-Protocol.md

@@ -8,7 +8,7 @@ description: Operational law for ending a task — when to write completion docs
 # Task Completion Protocol
 
 **Date**: 2026-06-29
-**Last Reviewed**: 2026-08-12
+**Last Reviewed**: 2026-09-29
 **Purpose**: The end-of-task operational sequence (completion docs, tiers, parent vs. subtask, stop-and-wait, PR flow) — operational law, always loaded
 **Organization**: process-standard
 **Scope**: cross-project
@@ -35,29 +35,29 @@ get_section({ path: "completion-documentation-guide", heading: "Documentation Ti
 
 ### For SUBTASKS
 1. [ ] Run targeted tests relevant to the change (not the full suite)
-2. [ ] Create completion doc: `.kiro/specs/[spec]/completion/task-N-M-completion.md`
+2. [ ] Create completion doc: `.kiro/specs/[spec]/completion/task-N-M-completion.md` — **enforced (S-4, ratified 2026-09-19)**: the claims passes count subtask-doc presence, and a ticked subtask without its doc is a **finding** on the authoring agent. The floor is three light elements (what changed · targeted tests + result · application-time adaptations, `none` written, never implied) — Completion Documentation Guide § "The subtask completion doc"
 3. [ ] Mark subtask complete (use the `taskStatus` tool)
-4. [ ] **Commit is optional and judgment-based — not mechanical per subtask.** When you commit, **commit AND push the unit branch** (`task/<spec>-<unit-slug>` or `task/<spec>-<N>-<slug>`, created at the first subtask — `git switch -c` or the completion tooling's equivalent); the two stay coupled because the push is the off-machine backup guarantee (a local-only commit is not backed up). Commit-and-push at a **checkpoint** (delicate or potentially-breaking work — a restore point worth having), when **backup-worthy work has accumulated** (a unit branch is longer-lived than a single task, so more unpushed work sits at risk between merges — push before the pile grows), or at a **session/handoff boundary**. Do NOT commit mechanically after every trivial subtask — the unit squash-merges anyway, so subtask granularity is cosmetic to `main`'s history. No PR opens and no required checks fire until unit completion. Subtasks do NOT open PRs.
+4. [ ] **Commit is optional and judgment-based — not mechanical per subtask.** When you commit, **commit AND push the unit branch** (`task/<spec>-<unit-slug>` or `task/<spec>-<N>-<slug>`, created at the first subtask — `git switch -c` or the completion tooling's equivalent); the two stay coupled because the push is the off-machine backup guarantee (a local-only commit is not backed up). Commit-and-push at a **checkpoint** (delicate or potentially-breaking work — a restore point worth having), when **backup-worthy work has accumulated** (a unit branch is longer-lived than a single task, so more unpushed work sits at risk between merges — push before the pile grows), or at a **session/handoff boundary**. Do NOT commit mechanically after every trivial subtask — the unit squash-merges anyway, so subtask granularity is cosmetic to `main`'s history. No PR opens until unit completion, and subtasks do NOT open PRs. Make the checkpoint with the completion tooling (`complete-task.sh --subtask`): it commits, pushes, **dispatches the required workflows against the unit branch**, and prints the run URLs (`--no-ci` skips the dispatch for a checkpoint you know is red). Those runs are **feedback, not the gate**: they report under non-required context names and test the branch head, not the merge ref. The gate runs on the unit PR.
 5. [ ] **STOP** and wait for user authorization
 
 ### For PARENT TASKS (Implementation or Architecture type)
 1. [ ] Local validation: the unit PR's required checks run the full suite at the gate — validating locally first catches failures before they block the merge (test-command selection: Start Up Tasks)
 2. [ ] Mark parent task complete (use the `taskStatus` tool) — the status change commits with the work and takes effect at merge; a failing suite blocks that merge at the gate
-3. [ ] Create completion doc: `.kiro/specs/[spec]/completion/task-N-completion.md` (on the task branch)
+3. [ ] Create completion doc: `.kiro/specs/[spec]/completion/task-N-completion.md` (on the task branch) — reproduce every tasks.md success-criterion row verbatim with Status + Evidence, and carry the forced-negative line (Completion Documentation Guide § 'Parent Success-Criteria Fidelity'), and the `**Instruments**:` header line naming the parent's Instruments block (§ 'The instruments line and block').
 4. [ ] Create summary doc: `docs/specs/[spec]/task-N-summary.md` (on the task branch)
 5. [ ] Complete the parent on its unit branch: `./.kiro/hooks/complete-task.sh "..."`.
    - **If this parent IS its own merge unit** (a standalone task, or a small single-unit spec): the tooling opens the PR and reports the URL.
-   - **If this parent is one of several in a declared multi-parent unit** (see the spec's tasks.md unit grouping): the tooling commits the completion+summary docs on the branch — **no PR yet**. The PR opens when the UNIT completes (its final/gating parent).
+   - **If this parent is one of several in a declared multi-parent unit** (see the spec's tasks.md unit grouping): the tooling commits the completion+summary docs on the branch, pushes, and **dispatches the required workflows against the unit branch**, printing the run URLs — **no PR yet**. The PR opens when the UNIT completes (its final/gating parent). Completion docs declare where their run results were measured (Completion Documentation Guide § "CI provenance — where a green was measured").
 6. [ ] **STOP** — if a PR opened, report the PR URL; otherwise report the on-branch parent completion. **The task is accepted when Peter merges the UNIT's PR** (merge on green = the authorization act). Never merge your own PR.
 
 ### For PARENT TASKS (Setup or Documentation type)
 1. [ ] Verify artifacts created/updated as specified
 2. [ ] Mark parent task complete (use the `taskStatus` tool)
-3. [ ] Create completion doc: `.kiro/specs/[spec]/completion/task-N-completion.md` (on the task branch)
+3. [ ] Create completion doc: `.kiro/specs/[spec]/completion/task-N-completion.md` (on the task branch) — reproduce every tasks.md success-criterion row verbatim with Status + Evidence, and carry the forced-negative line (Completion Documentation Guide § 'Parent Success-Criteria Fidelity'), and the `**Instruments**:` header line naming the parent's Instruments block (§ 'The instruments line and block').
 4. [ ] Create summary doc: `docs/specs/[spec]/task-N-summary.md` (on the task branch)
 5. [ ] Complete the parent on its unit branch: `./.kiro/hooks/complete-task.sh "..."`.
    - **If this parent IS its own merge unit**: the tooling opens the PR and reports the URL.
-   - **If this parent is one of several in a declared multi-parent unit** (spec's tasks.md unit grouping): the tooling commits the completion+summary docs on the branch — **no PR yet**; the PR opens at UNIT completion.
+   - **If this parent is one of several in a declared multi-parent unit** (spec's tasks.md unit grouping): the tooling commits the completion+summary docs on the branch, pushes, and **dispatches the required workflows against the unit branch**, printing the run URLs — **no PR yet**; the PR opens at UNIT completion. Completion docs declare where their run results were measured (Completion Documentation Guide § "CI provenance — where a green was measured").
 6. [ ] **STOP** — if a PR opened, report the PR URL; otherwise report the on-branch parent completion. **The task is accepted when Peter merges the UNIT's PR** (merge on green = the authorization act). Never merge your own PR.
 
 ---
@@ -71,9 +71,9 @@ Branch → PR → required checks → merge.
 **The merge unit is the coherent unit.** A PR carries a **coherent unit** — the smallest chunk of a spec's work that is coherent on its own AND reviewable as a single diff. For a small spec the unit is the whole spec (one PR). For a large spec the units are **declared in that spec's own tasks.md** as a task grouping (e.g., a substrate group / each per-agent cutover / a closeout) — named up front, never judged at merge time. One branch per unit; the unit's completion opens the PR; Peter merges the unit.
 
 1. Work happens on a **task branch**, never on `main`. The branch is created at the task's first subtask (or at task start): plain `git switch -c task/<spec>-<N>-<slug>`, or the completion tooling's equivalent.
-2. **Subtask mechanics** (one rule — commit method, push semantics, branch creation, PR timing): subtask commits are **optional and judgment-based, not mechanical per subtask** — and when made, they **commit AND push the branch** with plain git (the two stay coupled; the push is the off-machine backup). Commit-and-push at a **checkpoint** (delicate or potentially-breaking work), when **backup-worthy work has accumulated** (a unit branch is longer-lived than a single task — push before the unpushed pile grows), or at a **session/handoff boundary** — not after every trivial subtask, since the unit squash-merges anyway and subtask granularity is cosmetic to `main`. No PR opens and no required checks fire until unit completion; subtasks do NOT open PRs.
-   **AMENDED FROM THE OLD FLOW — a deliberate process change (Peter, 2026-07-05), not a carry-over.** Under the outgoing law, subtasks had NO commit/push step at all: the commit+push hook fired at PARENT completion only, so subtask work stayed local until the parent finished. Subtask commits-and-pushes are NEW behavior, justified forward-looking: (a) branches remove the old reason not to push — nothing lands on `main`; (b) a pushed branch is off-machine backup of in-progress work; (c) optional visibility for Peter on GitHub; (d) zero cost — pre-PR branch pushes trigger no pull_request workflows, and post-PR pushes re-running checks is already the change-request/failed-check resume path (points 7–8 below).
-   **Hook ergonomics**: one completion command, context-aware (`./.kiro/hooks/complete-task.sh`) — invoked for a subtask (at a judgment-based checkpoint, not mechanically) it commits and pushes the branch (no PR); invoked for a parent that is NOT the unit's final parent it commits the completion docs on the branch (no PR); invoked at **unit completion** (a single-parent unit, or the final/gating parent of a multi-parent unit) it commits, pushes, and opens the PR.
+2. **Subtask mechanics** (one rule — commit method, push semantics, branch creation, PR timing): subtask commits are **optional and judgment-based, not mechanical per subtask** — and when made, they **commit AND push the branch through the completion tooling** (`complete-task.sh --subtask`, which also dispatches the required workflows — see Hook ergonomics; the two stay coupled; the push is the off-machine backup). A plain-git push is not a checkpoint: it dispatches nothing. Commit-and-push at a **checkpoint** (delicate or potentially-breaking work), when **backup-worthy work has accumulated** (a unit branch is longer-lived than a single task — push before the unpushed pile grows), or at a **session/handoff boundary** — not after every trivial subtask, since the unit squash-merges anyway and subtask granularity is cosmetic to `main`. No PR opens until unit completion; subtasks do NOT open PRs. **Required workflows are dispatched against the unit branch** at each subtask checkpoint and each non-final parent completion that the completion tooling fires (a subtask checkpoint may pass `--no-ci`). Those runs are **feedback, not the gate**: they report under non-required context names and test the branch head, not the merge ref. The gate runs on the unit PR.
+   **AMENDED FROM THE OLD FLOW — a deliberate process change (Peter, 2026-07-05), not a carry-over.** Under the outgoing law, subtasks had NO commit/push step at all: the commit+push hook fired at PARENT completion only, so subtask work stayed local until the parent finished. Subtask commits-and-pushes are NEW behavior, justified forward-looking: (a) branches remove the old reason not to push — nothing lands on `main`; (b) a pushed branch is off-machine backup of in-progress work; (c) optional visibility for Peter on GitHub; (d) zero cost — pre-PR branch pushes trigger no pull_request workflows, and post-PR pushes re-running checks is already the change-request/failed-check resume path (points 7–8 below). *(Annotated by ballot B-CI, 2026-09-27: the unit-branch dispatches add CI runs, so the cost is no longer zero; they are feedback, not the gate, and still trigger no pull_request workflows.)*
+   **Hook ergonomics**: one completion command, context-aware (`./.kiro/hooks/complete-task.sh`) — invoked for a subtask (at a judgment-based checkpoint, not mechanically) it commits and pushes the branch and dispatches the required workflows against it, printing the run URLs (no PR; `--no-ci` skips the dispatch); invoked for a parent that is NOT the unit's final parent it commits the completion docs on the branch, pushes, and dispatches the required workflows (no PR); invoked at **unit completion** (a single-parent unit, or the final/gating parent of a multi-parent unit) it commits, pushes, and opens the PR, then **fails loudly — non-zero exit, with the remedy printed — if CI started zero runs on it** (the #148/#194 dropped-event class).
 3. **Dependent tasks branch from `main` after the prior task's PR merges.** Starting a dependent task before the prior merge is not sanctioned by default — this composes with stop-and-wait (Peter's go for the next task typically follows his merge of the prior one), so the wait costs nothing in practice. Exception, only on Peter's explicit direction: branch from the prior task branch and declare `Stacked-on: #<PR>` in the PR body; stacked PRs merge in base-first order.
 4. At **unit** completion (a standalone task, a small single-unit spec, or the final/gating parent of a declared multi-parent unit), the tooling commits, pushes the branch, **opens a PR**, and reports the PR URL. A parent completing *inside* a multi-parent unit commits its completion+summary docs on the branch and does NOT open a PR — its acceptance is the unit's merge.
 5. Required checks run on the PR. A failing check blocks merge at the platform.
@@ -99,6 +99,7 @@ Branch → PR → required checks → merge.
 - **Large spec → units DECLARED in tasks.md**: the spec's tasks.md names its units as a task grouping (substrate / each cutover / closeout, etc.). Units are named up front and reviewed in the tasks feedback round — never judged at merge time.
 - **One branch per unit**: subtasks commit+push the branch at judgment-based checkpoints (not mechanically per subtask); parent completions commit their docs on the branch; the unit's completion opens the PR; Peter merges (squash).
 - **Dependent units branch from `main` after the prior unit's PR merges** — the unit is the dependency grain (stacking only on Peter's explicit direction, `Stacked-on: #<PR>`).
+- **Write scope inside a unit**: a parent's assignment row in a **merged** `tasks.md` grants its PRIMARY and tiered secondary agents write access to **exactly that parent's listed Primary Artifacts**, on the unit's branch, until the unit merges. It supplements the charter's write scope, grants no ratification authority, and an out-of-list edit is a claims-pass finding. Rule and limits: `.kiro/docs/ballots/2026-09-26-tasks-row-write-scope-grant.md` (register row `tasks-row-write-scope-grant`).
 - **On merge, the unit's branch is deleted** (remote auto-deleted by repo setting; local deleted on return to `main`); stale/unmerged branches are swept in the monthly Civitas health check — see § "Branch Cleanup".
 
 ### Branch Cleanup
@@ -151,4 +152,4 @@ When the gate must be bypassed (broken gate, urgent fix the checks themselves bl
 - **A task is accepted at the MERGE of its unit.** Agents open PRs at unit completion; Peter merges on green. Never merge your own PR. Pushes to `main` are rejected by branch protection (admins included).
 - **On merge, the unit's branch is cleaned up** — remote auto-deleted by repo setting; local deleted on return to `main`; stale/unmerged branches swept in the monthly Civitas health check.
 - **A checks-only merge is NOT ratification**: governance-law changes still ratify via the record-first ballot protocol (`.kiro/docs/ballots/README.md`).
-- **Delegated-tier capture (exception-based)**: if the agent/model that actually did the work **diverged** from the task's planned `**Agent**: <agent> (<Model>)` — a different tier, or additional agents pulled in — record the delta and a one-line reason in the completion doc. A plan that held needs no note. This is a cheap data-point, **not** a justification to defend (overriding a stale or rote stamp is the *correct* move) — it feeds model-tier recalibration and process audits. Agent-evolution (routing/scope estimate was off) and model-evolution (cognitive-demand estimate was off) are distinct signals — note which. See `process-orchestration-model-selection`.
+- **Delegated-tier capture (UNCONDITIONAL — amended by the 2026-09-19 delegated-tier-capture ballot; previously exception-based)**: every parent completion doc carries, in its header block, exactly one fixed-form line — `**Delegated-tier**: plan held`, or the divergence form `**Delegated-tier**: planned <agent> (<tier>) → actual <agent> (<tier>) — <one-line reason>; class: agent-evolution` (or `model-evolution`, or `both`). **Silence is no longer a recordable state**: exception-based capture made a missing note ambiguous between plan-held and unrecorded divergence. A recorded divergence is a cheap data-point, **not** a justification to defend (overriding a stale or rote stamp is the *correct* move) — it feeds model-tier recalibration and the claims passes, which verify presence and audit accuracy. Agent-evolution (routing/scope estimate was off) and model-evolution (cognitive-demand estimate was off) are distinct signals. Forms + grammar: Completion Documentation Guide § "The delegated-tier line — unconditional". See `process-orchestration-model-selection`.

package/.kiro/steering/start-up-tasks.md

@@ -8,7 +8,7 @@ description: Essential pre-task checklist — date verification, governance heal
 # Start Up Tasks
 
 **Date**: 2025-10-20
-**Last Reviewed**: 2026-07-09
+**Last Reviewed**: 2026-09-29
 **Purpose**: Essential pre-task checklist for every task (date check, governance health, Jest commands, test selection, authorization-to-start). End-of-task sequence: see Task Completion Protocol.
 **Organization**: process-standard
 **Scope**: cross-project
@@ -19,7 +19,7 @@ description: Essential pre-task checklist — date verification, governance heal
 
 2. **Civitas Governance Health Check**
    
-   IF it's been >30 days since last governance health check **[2026-08-25]**, THEN flag: "Governance health check overdue — Thurgood (Civitas steward) should run the monthly health check before proceeding."
+   IF it's been >30 days since last governance health check **[2026-09-19]**, THEN flag: "Governance health check overdue — Thurgood (Civitas steward) should run the monthly health check before proceeding."
    
    *Only Thurgood runs the health check. All agents check the date and flag if overdue.*
 
@@ -107,7 +107,9 @@ description: Essential pre-task checklist — date verification, governance heal
    
    **Default assumption**: Use `npm test` for parent tasks unless working on performance systems.
 
-6. **Model-tier calibration — when this task will delegate to subagents**
+6. **Delegation and model tier — before delegating, and before deciding whether to**
+   
+   **First ask WHETHER this work is yours to do at all** (Agent-Directory § "Primary Agent (Orchestrator)"). Then, for anything you do delegate:
    
    Before delegating to a subagent, choose its model tier by the task's cognitive demand — do NOT let it silently inherit the session model:
    - **Implementing** an already-settled design/spec/contract → the cheaper capable tier (currently **Sonnet**).
@@ -122,4 +124,10 @@ description: Essential pre-task checklist — date verification, governance heal
    
    The end-of-task sequence (when to write completion docs, which tier, the parent-vs-subtask distinction, and the stop-and-wait-for-authorization rule) is **operational law in the always-loaded Task Completion Protocol** — it is already in context. Follow it when completing any task or subtask.
    
-   **One rule worth restating here at the start:** when you report a task complete, **STOP and wait for user authorization** before starting the next one (see #3 above). Task Completion Protocol owns the rest of the end-of-task sequence.
+   **One rule worth restating here at the start:** when you report a task complete, **STOP and wait for user authorization** before starting the next one (see #3 above). Task Completion Protocol owns the rest of the end-of-task sequence.
+
+8. **Starting a PARENT task: write its Instruments block first**
+
+   Before a parent's first subtask starts, the PRIMARY writes `.kiro/specs/<spec>/completion/task-<N>-instruments.md` — one row per instrument each success criterion's evidence depends on (test, check, fixture, file, command, upstream artifact), each `exists (<path> @ <sha>)` with a one-line fit clause, `built here (<subtask>)`, or `MISSING → <owner>: <record>`; a criterion needing no instrument gets a `none — <why>` row — and commits it on the unit branch. **Any MISSING stops the subtasks that depend on it, before code**; report it for routing (a consult, then an amendment if the plan changes). A `MISSING` row is never overwritten: its resolution is appended in the row. A gap found later is appended under `## Found later` with its kind (`unlisted` or `misfit`), never silently fixed. Format and the completion-doc header line: Completion Documentation Guide § "The instruments line and block". *(Ballot 2026-09-28-parent-instrument-existence-check.)*
+
+   **From the first tasks round after `P`** (the instruments parser PR's squash SHA — ballot § 4a, M4), a spec also declares its instruments in `tasks.md` at planning time; for such a spec this file is written at branch cut as M4's execution file — the pasted command-output existence delta, one fit line per row keyed by row id, rows found at the cut, `## Found later` — never restating a plan row's state or path.

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable consumer-facing changes to `@3fn/core` are recorded here, one entry per release, in plain language for the people who install this package. Internal-only changes (governance, test infrastructure, spec process) are not listed — see this repository's release history (https://github.com/3fn/DesignerPunk/releases) for the full hand-authored delta if you need that detail.
+
+This file starts with Spec 123 ("Consumer Distribution"). Earlier releases are not backfilled here.
+
+## [15.0.0] — 2026-10-02
+
+**This is a breaking (major) release for anyone running an earlier `@3fn/core`.** It ships, as one release, what was planned as two: the distribution substrate and the generated agent layer. To upgrade a 14.x install, see "Upgrading from 14.x" at the end of this entry. **In 15.0.0, the web path and the generated agent layer are ready; native (iOS/Android) onboarding is not supported yet** (see "Known limitations").
+
+### Breaking
+
+- **`init` no longer copies `.kiro/agents/`, `.kiro/steering/`, `governance/`, `src/types` or `src/components/core` into your repo.** It creates an empty `src/components/` for your own components and generates DesignerPunk's agent layer for one target (see "Added"). Token types are imported from `@3fn/core/types`; DesignerPunk's own components stay in the package. The MCP servers serve DesignerPunk's docs from the installed package.
+- **`src/` no longer ships wholesale.** The package ships only the source files it still needs: the token source `init` copies, the files that token source imports, the iOS and Android component and blend sources, and a small declared set of styles, fonts and component metadata.
+- **No longer in the package: `designerpunk.config.ts`, `product-template/`, the steward agent prompts (`.kiro/agents/`), and the full `.kiro/steering/` folder.** In place of the steering folder the package ships, by name, the eight identity documents the generated agent layer reads.
+- **The Inter font is removed: `@3fn/core/fonts/inter.css` no longer resolves**, and the Inter font files no longer ship. Drop the import, or use `@3fn/core/fonts/rajdhani.css`, `figtree.css` or `commit-mono.css`.
+- **Four semantic colours are no longer in the iOS and Android base token files** (`dist/DesignTokens.ios.swift`, `dist/DesignTokens.android.kt`): `colorFeedbackSuccessText`, `colorTextDefault`, `colorTextMuted`, `colorTextSubtle` (Kotlin: `color_feedback_success_text`, `color_text_default`, `color_text_muted`, `color_text_subtle`). Their dark-mode values were corrected for contrast, which makes them theme-varying, and the native files do not emit theme-varying colours (see "Known limitations"). If your native code references them, keep your 14.1.0 values for these four. The web CSS still carries all four.
+- **`init` now refuses to run against a born, partial, or package-mode repository**, printing a named error instead of silently re-copying or half-copying files. `--re-scaffold` lists every file it would re-add before writing anything.
+- **`generate` now refuses to run in a half-set-up repo** (for example, a config file whose `tokenSource` points at no token tree), printing a named error that says what is missing, instead of guessing from the current directory.
+- **`sync` no longer refreshes your token tier, your `src/types`, or your pre-existing component copies.** Once `init` has copied your tokens into your repo, they are yours — DesignerPunk's own token updates never flow back into them again. `sync` now manages only what DesignerPunk itself still owns: its MCP configuration keys, and the generated agent files for the targets you have attached.
+- **`sync --force` and `--accept-all` are retired** (they print a notice and are ignored). `sync` now prints its full report before changing anything: run from a script or CI (no terminal), it writes nothing unless you pass `--apply`; at a terminal it asks once. A file you edited is overwritten only with `--overwrite <path>`, and a file you deleted is restored only with `--restore <path>`.
+- **The sync manifest moved** from `.kiro/sync-manifest.json` to `designerpunk.manifest.json` at the repo root. `sync` converts the old file and leaves a one-line pointer in it for this release. Commit the new file.
+- **A `tsconfig.test.json` written by an earlier `init` no longer resolves**: it pinned `@3fn/core` subpaths to raw `src/` files, several of which no longer ship. `sync` offers `--repair-tsconfig` to remove just those entries (and `--repair-npmrc` for an old `.npmrc` GitHub Packages pin).
+- **Component-copy migration, opt-in**: if you installed before this release, `sync --migrate-components` judges each of your existing component copies against what DesignerPunk actually shipped in each version up to the one you have installed, and can relocate your own edits and remove copies you never touched. Nothing changes without the flag; undecidable cases are reported as "cannot tell" with an explanation, never guessed.
+
+### Added
+
+- **A generated agent layer.** `init` generates DesignerPunk's agents for your agent tool instead of copying prompt files into your repo. It generates the agent definitions, the always-loaded identity files, and the MCP configuration and approvals, for one target: Claude Code (`--target=cc`, the default) or Kiro (`--target=kiro`).
+- **`npx designerpunk attach --target=<cc|kiro>`** adds a target to a repo: a second agent tool, or a repo that `init` did not create. **`attach --reference`** sets up only the MCP configuration and approvals. Use it to read DesignerPunk's docs and components without setting up a design system.
+- **`sync --migrate-legacy`**, offered only together with `attach`. It removes the agent, steering and governance files that an earlier `init` copied into your repo, then attaches the generated layer, in the same run. Copies you edited stay on disk as yours and are no longer tracked. Nothing changes unless you pass the flag.
+- **Generation warns instead of failing when the installed package is missing a member.** If a document, identity file or tool that an agent expects is missing from the installed package, that agent is generated without it. A warning names what is missing and ends: "If a clean reinstall (remove node_modules, then npm install) does not restore it, the package you installed does not contain it." The command still exits 0.
+- **The generator ships compiled** (`dist/generator/`), so generating agents needs no TypeScript runtime.
+- **`generate` warns about a `tokens.ts` / `*.tokens.ts` file that exports no `defineComponentTokens` value** — usually a plain reference map that should not wear that filename.
+- **`@3fn/core/types` exports the `Oklch` type.**
+- **The application MCP server indexes your own `src/components/` alongside DesignerPunk's**, and reindexes when your components change. Its `get_token_details` gains a `themeResolutions.dark` field.
+
+### Changed
+
+- **`sync` keeps the generated agent files up to date** for the targets you have attached.
+- **`sync`'s MCP-key management is now key-grained, not whole-file.** A config key DesignerPunk owns (in `.kiro/settings/mcp.json`, `.mcp.json`, or `.claude/settings.json`) is compared by its parsed value, so your own keys and rules living in the same file are left untouched. If none of DesignerPunk's keys changed, the file isn't rewritten at all.
+- **Both harnesses' MCP scaffolds (Kiro and Claude Code) now auto-approve exactly the tools each server marks read-only** — generated at build time from each server's own tool registrations, not a hand-maintained list. (The previous static list was already out of date: it was missing an approval for the main discovery tool and had one for a tool no server provides.) An existing install is not corrected automatically: if `sync` lists an approval under "Removed from package", it leaves it in place — remove it yourself.
+- **A third MCP server entry, `designerpunk-product`, is now scaffolded** alongside the existing docs and application servers.
+- **`sync` now reports two new seams instead of silently drifting**: a *name contract* (which token names DesignerPunk's web components reference, checked against your own generated web CSS) and a *type contract* (what changed in the public token type surface since your last sync). Neither writes your tokens for you — they tell you what to look at.
+- **The Integration Guide** now teaches `attach` in its "Set up agent prompts" step, says plainly that native onboarding is not supported in this version, distinguishes DesignerPunk's base web CSS from your own generated CSS, and points its "Upgrading" section at this release's upgrade path.
+- **The published tarball is meaningfully smaller** (about 6.4MB packed, down from about 8.4MB in 14.1.0).
+
+### Fixed
+
+- **DTCG and Figma exports now read the same OKLCH colour source as CSS, Swift and Kotlin**, resolving the colour divergence disclosed as a known issue in 14.1.0; dark-mode values now reach the Figma export.
+- **Contrast corrections (WCAG AA)**: `color.feedback.success.text` (green500 light, green300 dark) and the dark-mode text hierarchy (`color.text.default`, `.muted`, `.subtle`). In an existing install, the light-mode change is in the token source, so it does not reach the token tier you already copied. The dark-mode and WCAG values come from the installed package on your next `generate`, so an existing install picks those up.
+- **`generate` no longer crashes with a stack trace when one of your component-token files declares a token in the wrong family's `defineComponentTokens()` call.** It stops with one message that names the file and the fix, and writes nothing.
+- **`sync`'s suggested fix for an old `MCP_STEERING_DIR` value now points at the installed package's docs** (`./node_modules/@3fn/core/governance`). For the value an earlier `init` wrote, it used to suggest `./governance`, a folder a consumer repo does not have. The "already has an entry" advice now names `attach`, not `init`.
+- Container-Base and Input-Text referenced CSS variables that did not exist; they now resolve. The Input-Text-Password visibility toggle now has a hover state.
+- Button-VerticalList-Item no longer throws when `.disabled` is set (the value is ignored), and Input-Radio-Base ignores a consumer-set `disabled` so it can no longer drop its value from form submission — consistent with 14.0.0's no-disabled-states rule.
+- The published browser bundles (`designerpunk.esm.js`, `designerpunk.umd.js`) no longer embed the publishing machine's filesystem path in an internal module comment — a build-machine-identity leak with no functional effect on consumers, now removed.
+- Removed four unused `Input-Text-*` browser-build files (`InputTextBase.browser.ts`, `InputTextEmail.browser.ts`, `InputTextPassword.browser.ts`, `InputTextPhoneNumber.browser.ts`, and their compiled `.js`/`.d.ts` output) from the package. They were never imported by the shipped bundle or by any documented usage path; removing them has no effect on any documented integration.
+
+### Known limitations
+
+- **Native (iOS/Android) onboarding is not supported in 15.0.0.** DesignerPunk's iOS and Android components read a theme surface that neither the package's token files nor your own `generate` emits in this version, so copying the native files does not yield a compiling target.
+- **The iOS and Android token files do not emit theme-varying colours**, neither as constants nor through a theme type. Fourteen semantic colours are affected (among them `colorActionPrimary` and `colorStructureCanvas`), including the four listed under "Breaking"; ten of them were already missing in 14.1.0.
+- **A theme you register in `designerpunk.config.ts` is not emitted yet, on any platform.** No `[data-theme="<name>"]` block is generated for web, and no theme structs or instances for iOS/Android. The web CSS carries DesignerPunk's base light/dark values and the built-in `data-theme="wcag"` block.
+- **In a consumer repo, the application MCP's health check reports `degraded`**, with one "companion path not found: governance/Component-Family-….md" warning per component family. Component and token queries still answer; the companion docs are served by the docs MCP.
+- **`--migrate-components` reports every copy as "cannot tell" when your registry access fails** (for example, an `.npmrc` pin to GitHub Packages with an expired token), including the version you have installed.
+- **`sync --migrate-legacy` does not set up your personal note.** See step 4 of "Upgrading from 14.x".
+
+### Upgrading from 14.x
+
+1. `npm install @3fn/core@15.0.0`
+2. `npx designerpunk sync` — review the report. Nothing is written before it prints.
+3. `npx designerpunk sync --migrate-legacy --target=cc` (or `--target=kiro`), adding `--repair-tsconfig`, `--repair-npmrc` or `--migrate-components` if the report offers them. This converts the manifest, removes the copies you never edited, and generates the agent layer, in one run.
+4. Create `.designerpunk/personal-note.local.md` (who you are and how you want to be worked with). Your agents read it every session; the migration does not create it.
+5. Run `npx designerpunk generate`. If it stops on a component-token file an earlier `init` copied (`src/tokens/component/progress.ts` or `src/components/core/Button-Icon/buttonIcon.tokens.ts`), use the fix its message names: split the file's `defineComponentTokens()` into one call per family; or, for the `src/tokens/` file, replace it with the package's version and change its `'../../build/tokens'` import to `'@3fn/core/build'`; or, for an unedited `src/components/core/` copy, delete it.
+6. Restart your agent session, then run `npx designerpunk sync` once more to review.

package/README.md

@@ -1,10 +1,10 @@
 # DesignerPunk
 
-[![Version](https://img.shields.io/badge/Version-12.0.5-purple)](docs/releases/RELEASE-NOTES-12.0.0.md)
+[![Version](https://img.shields.io/badge/Version-15.0.0-purple)](docs/releases/release-15.0.0.md)
 [![Repository](https://img.shields.io/badge/GitHub-DesignerPunk-blue)](https://github.com/3fn/DesignerPunk)
 [![License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/Tests-8936%2B-brightgreen)](.)
+[![Tests](https://img.shields.io/badge/Tests-9377%2B-brightgreen)](.)
 
 ---
 
@@ -38,7 +38,7 @@ Its three foundational systems (Rosetta, Stemma, Civitas) are interdependent: to
 
 **What it solves:** Every value is mathematical, not arbitrary. Machines validate relationships; humans define intent.
 
-**Deliverables:** 437 tokens across spacing, sizing, color, typography, radius, shadow, glow, motion, opacity, blend, and blur. Cross-platform generation to CSS, Swift, Kotlin, and DTCG JSON. Three-tier architecture: Primitive → Semantic → Component.
+**Deliverables:** 443 tokens (217 primitive, 193 semantic, 33 component) across spacing, sizing, color, typography, radius, shadow, glow, motion, opacity, blend, and blur. Cross-platform generation to CSS, Swift, Kotlin, and DTCG JSON. Three-tier architecture: Primitive → Semantic → Component.
 
 **How AI agents access it:**
 ```
@@ -54,7 +54,7 @@ get_token_details({ name: "space150" })
 
 **What it solves:** Every component makes explicit behavioral promises. Machines validate contracts; humans define interaction intent.
 
-**Deliverables:** 34 production components with behavioral contracts. 10 contract categories, 136 concepts. True native implementations (Web Components, SwiftUI, Jetpack Compose). Formal inheritance with intentional exclusions.
+**Deliverables:** 34 production components with behavioral contracts. 10 contract categories, 137 concepts. True native implementations (Web Components, SwiftUI, Jetpack Compose). Formal inheritance with intentional exclusions.
 
 **How AI agents access it:**
 ```
@@ -70,7 +70,7 @@ find_components({ context: "login-forms" })
 
 **What it solves:** Institutional knowledge persists across sessions. Machines query what they need progressively; humans maintain the source of truth.
 
-**Deliverables:** 88 steering documents with progressive disclosure. 3 MCP servers (docs, application, product). 8 specialized AI agents with domain boundaries. 13 validation hooks. Automated release detection and completion documentation system. 109+ specs encoding institutional decisions.
+**Deliverables:** 83 governance documents served by MCP with progressive disclosure, plus 8 always-loaded identity documents. 3 MCP servers (docs, application, product). 8 specialized AI agents with domain boundaries. 13 validation hooks. A PR-gated workflow with required checks and a completion documentation system. 130+ specs encoding institutional decisions.
 
 **The agent system:**
 
@@ -89,7 +89,7 @@ Each agent knows what it owns, what it doesn't, and who to defer to. No agent op
 
 **How AI agents access it:**
 ```
-get_section({ path: "Token-Governance.md", heading: "Token Selection Matrix" })
+get_section({ path: "token-governance", heading: "Token Selection Matrix" })
 → Exactly the governance context needed for this decision, not the entire 2,000-line document
 ```
 
@@ -100,18 +100,18 @@ get_section({ path: "Token-Governance.md", heading: "Token Selection Matrix" })
 The architecture is the argument. The numbers are the evidence.
 
 **By the numbers:**
-- 8,936 tests passing across 369 test suites
+- 9,377 tests passing across 390 test suites
 - 34 production components with full cross-platform implementations
-- 437 design tokens with mathematical relationships
+- 443 design tokens with mathematical relationships
 - 3 MCP servers enabling progressive, context-efficient AI access
 - 8 AI agents with domain-scoped expertise operating within defined boundaries
-- 109+ specs documenting every architectural decision and its rationale
-- Published as `@3fn/core` on GitHub Packages with a working CLI (`npx designerpunk`)
+- 130+ specs documenting every architectural decision and its rationale
+- Published as `@3fn/core` on npm with a working CLI (`npx designerpunk`)
 
 **What this enables:**
 - An AI agent can select the right component for a login form, validate the assembly, and generate platform-native code without a human explaining the system from scratch every session
-- Products define their own tokens (`product/tokens/*.yaml`) with structured governance — the system generates platform-native output and makes them queryable via MCP alongside system tokens
-- The system self-documents its own evolution: every completed task produces completion documentation and triggers release analysis automatically
+- Products own their token tier: `init` copies DesignerPunk's token source into the product's repo, and `generate` builds the product's own platform output and token index from it
+- The system self-documents its own evolution: every completed task produces completion documentation, and every change reaches `main` through a pull request with required checks
 - A new agent (or a new human) can onboard by querying the MCP servers rather than reading thousands of lines of documentation linearly
 - Token changes propagate to all three platforms through a single generation pipeline with mathematical validation at every step
 - Design tokens export to DTCG JSON and Figma Variables, enabling canvas tools to sync with live code
@@ -126,21 +126,26 @@ Guiding agents to apply tokens and components to product design specs is the cur
 
 ## Getting Started
 
+**Status:** onboarding is still being built. 15.0.0 is for existing installs and early adopters: the web path and the generated agent layer (Claude Code and Kiro) are ready; native (iOS/Android) onboarding is not supported yet.
+
 **Use it in your project:**
 ```bash
 npm install @3fn/core
-npx designerpunk init
-npx designerpunk generate
-npx designerpunk sync        # after upgrades — detects and applies stale files
+npx designerpunk init        # copies the token source into your repo; generates the agent layer (--target=cc or --target=kiro)
+npx designerpunk generate    # builds your own token output from your token source
+npx designerpunk sync        # after upgrades — reports first; on your go, updates DesignerPunk's MCP config and generated agent files
+npx designerpunk attach --target=kiro   # add another agent tool, or set up a repo init did not create
 ```
-Not comfortable with terminal commands? Ask your AI agent to follow these steps. That's the point.
+`sync` never touches your tokens: after `init`, they are yours. Not comfortable with terminal commands? Ask your AI agent to follow these steps. That's the point.
+
+Upgrading from 14.x? Follow the [15.0.0 release notes](docs/releases/release-15.0.0.md).
 
-[Full integration guide →](docs/integration-guide.md)
+[Full integration guide →](governance/DesignerPunk-Integration-Guide.md)
 
 **Study the architecture:**
 - [DesignerPunk Systems Overview](.kiro/steering/DesignerPunk-Systems-Overview.md)
-- [Steering documentation](.kiro/steering/) (88 docs, the governance layer in practice)
-- [AI Collaboration Framework](.kiro/steering/AI-Collaboration-Framework.md)
+- [Governance documentation](governance/) (83 docs, the governance layer in practice)
+- [AI Collaboration Framework](governance/AI-Collaboration-Framework.md)
 
 ---
 
@@ -160,9 +165,9 @@ I provide architectural direction, design decisions, and quality standards. AI a
 
 The system is tool-agnostic by design. The architecture is the constant; which AI, IDE, CLI, or design tool you use is interchangeable. This isn't a workaround. It's the methodology the system was built to prove.
 
-Note: primarily developed on Kiro IDE and CLI. Broader tool support is in progress.
+Note: primarily developed on Kiro IDE and CLI. As of 15.0.0, the generated agent layer supports both Kiro and Claude Code.
 
-8,936 tests. 34 components across three platforms. A published package with a working CLI. All architected through this model.
+9,377 tests. 34 components across three platforms. A published package with a working CLI. All architected through this model.
 
 ---