From 7c67f827a21fd187778c2a444eca975802537408 Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 18:43:59 -0700
Subject: [PATCH 1/8] =?UTF-8?q?feat(6.8):=20role-template=20management=20U?=
 =?UTF-8?q?I=20=E2=80=94=20versioning=20+=20promote-to-production?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New top-level "Agents" tab in the web UI for editing the instruction
templates each agent role reads. Each role gets:
  - A bundled cf² default (always selectable, read-only, never deletable).
  - Any number of saved versions stored under
    `~/.cfcf/templates-managed/<name>/{manifest.json, v_<id>.md}`.
  - A "Promote to production" action that writes the selected version's
    content to `~/.cfcf/templates/<name>` — the existing user-global
    override path that `getTemplate()` already reads. Reverting to default
    deletes the override file so cf² falls back to the embedded template.
    No runtime changes to agent spawning.

Decoupled from the prior "blocked on 6.11/ADLC" framing: the user's
vision (edit + version + promote) operates at per-role-template
granularity — whatever role abstraction ADLC eventually settles on
can layer on top of this without rework.

**Shipped (round 1)**

- `packages/core/src/role-templates.ts` — versioning manager.
  list / get / save / update / delete / promote, manifest self-heal
  on corruption, orphan detection, automatic revert when deleting the
  promoted version, automatic override-file refresh when editing it.
  Bundled defaults sourced via a new `getEmbeddedTemplate(name)`
  exported from `templates.ts`.
- HTTP routes at `/api/role-templates/*` with uniform error envelope.
- Web UI: new `/agents` route (Header link between Memory and Settings),
  tab strip across managed roles, version selector, monospace textarea
  editor, action buttons (Edit / Save as new version / Save changes /
  Promote / Revert / Delete), inline help block. Deep-linkable via
  `/agents?template=<name>`.

**Managed templates (round 1)**: cfcf-architect-instructions.md,
cfcf-judge-instructions.md, cfcf-documenter-instructions.md,
cfcf-reflection-instructions.md, process.md.

**Out of scope (deferred follow-ups)**: dev-role custom-directions
block (Tier-2 from the original 6.8 design — needs the sentinel-merge
insertion-point design first), Product Architect / Help Assistant
system-prompt management (their prompts are programmatically assembled),
per-project override management UI, diff viewer, search-within-content.

**Tests**: 30 unit tests in `role-templates.test.ts` (every flow +
manifest corruption recovery + cross-template isolation), 15 endpoint
tests in `routes/role-templates.test.ts`, 3 new route-parser tests for
the new `/agents` + `?template=` routes. All 834 core+cli+web tests
pass; clean typecheck; web build clean.

Pre-existing `app.test.ts` config-merge failure on main is unrelated
(verified earlier in this iter).

**Design doc**: `docs/design/role-template-management.md`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  44 ++
 docs/design/role-template-management.md       | 190 +++++++
 docs/plan.md                                  |   4 +-
 packages/core/src/index.ts                    |   2 +
 packages/core/src/role-templates.test.ts      | 304 +++++++++++
 packages/core/src/role-templates.ts           | 467 ++++++++++++++++
 packages/core/src/templates.ts                |  14 +
 packages/server/src/app.ts                    |   5 +
 .../server/src/routes/role-templates.test.ts  | 243 +++++++++
 packages/server/src/routes/role-templates.ts  | 143 +++++
 packages/web/src/App.tsx                      |   3 +
 packages/web/src/api.ts                       |  81 +++
 packages/web/src/components/Header.tsx        |   9 +
 packages/web/src/hooks/useRoute.test.ts       |  23 +
 packages/web/src/hooks/useRoute.ts            |  12 +-
 packages/web/src/pages/AgentTemplates.tsx     | 512 ++++++++++++++++++
 16 files changed, 2053 insertions(+), 3 deletions(-)
 create mode 100644 docs/design/role-template-management.md
 create mode 100644 packages/core/src/role-templates.test.ts
 create mode 100644 packages/core/src/role-templates.ts
 create mode 100644 packages/server/src/routes/role-templates.test.ts
 create mode 100644 packages/server/src/routes/role-templates.ts
 create mode 100644 packages/web/src/pages/AgentTemplates.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index decdaf6..beda073 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,50 @@ Changes are tracked via git tags. Each release tag corresponds to an entry here.
 
 ## [Unreleased]
 
+### Added — Item 6.8 (round 1): role-template management UI
+
+- **New top-level "Agents" tab** in the web UI (between Memory and
+  Settings). One sub-tab per managed role template; each tab shows
+  the template content in a scrollable monospace editor with version
+  selector, edit / save / promote / revert / delete actions, and an
+  inline help block.
+- **Versioning + promote-to-production**: every role's bundled cf²
+  default is always selectable (read-only, never deletable). Saving
+  edits creates a new labelled version under
+  `~/.cfcf/templates-managed/<name>/`. Promoting a version writes its
+  content to the existing `~/.cfcf/templates/<name>` user-global
+  override path that `getTemplate()` already reads — no runtime
+  changes to agent spawning. Reverting to default deletes the override
+  file so cf² falls back to the embedded default. Editing a
+  promoted version refreshes the override file in-place so the
+  change is live for the next agent run.
+- **Managed templates (round 1)**: `cfcf-architect-instructions.md`,
+  `cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`,
+  `cfcf-reflection-instructions.md`, `process.md`. Per-project
+  overrides at `<repo>/cfcf-templates/<name>` continue to take
+  precedence over the user-global override (the power-user escape
+  hatch, unmanaged from the UI).
+- **HTTP API**: `GET /api/role-templates`, `GET .../:name`,
+  `GET .../:name/versions/:versionId`, `POST .../:name/versions`,
+  `PUT .../:name/versions/:versionId`,
+  `DELETE .../:name/versions/:versionId`,
+  `POST .../:name/promote`. Uniform `{ error: string }` envelope.
+- **New core module** `packages/core/src/role-templates.ts` with
+  list / get / save / update / delete / promote helpers, manifest
+  self-heal on corruption, orphan detection. `getEmbeddedTemplate(name)`
+  newly exported from `templates.ts` for read-only access to the
+  bundled default.
+- **Out of scope for round 1 (deferred follow-ups)**: dev-role
+  custom-directions block (Tier-2 from the original design — needs
+  the sentinel-merge insertion-point design first), Product Architect /
+  Help Assistant system-prompt management (their prompts are
+  programmatically assembled, not file-loaded), per-project override
+  management UI, diff viewer between versions.
+- **Tests**: 30 unit tests in `role-templates.test.ts`, 15 endpoint
+  tests in `routes/role-templates.test.ts`, 3 new route-parser tests
+  for `/agents` + `?template=`.
+- **Design doc**: [`docs/design/role-template-management.md`](docs/design/role-template-management.md).
+
 ### Added — Item 6.33: ollama-models refresh
 
 - **Auto-refresh on server boot.** `cfcf server start` now calls
diff --git a/docs/design/role-template-management.md b/docs/design/role-template-management.md
new file mode 100644
index 0000000..e313fa6
--- /dev/null
+++ b/docs/design/role-template-management.md
@@ -0,0 +1,190 @@
+# Role-template management (item 6.8) — design
+
+## Problem
+
+cf² ships a fixed set of agent-role instruction templates (`cfcf-architect-
+instructions.md`, `cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`,
+`cfcf-reflection-instructions.md`, plus the workspace process template
+`process.md`). Today users can override any of them by dropping a file into
+`~/.cfcf/templates/<name>` (user-global) or `<repo>/cfcf-templates/<name>`
+(project-local). The override is binary — one file wins; there's no way to
+keep multiple drafts, revert easily, or compare against the bundled default.
+
+This design adds a **versioning + promote-to-production layer** on top of
+the existing override mechanism, plus a web UI for editing.
+
+## Vision (from user, 2026-05-08)
+
+- New top-level **"Agents"** tab in the web UI.
+- One sub-tab per role with the template content visible (scrollable,
+  searchable).
+- Edit-and-save flow that creates **versions** rather than overwriting.
+- Selector to view / load any saved version.
+- **Promote-to-production** button — the promoted version is what cf² uses
+  at runtime.
+- The bundled default is always available + promoteable (never deletable).
+
+## Constraints (existing system this needs to fit)
+
+- `getTemplate(name)` resolves: project-local → user-global → embedded
+  ([packages/core/src/templates.ts](../../packages/core/src/templates.ts)).
+- The embedded default is compiled into the cfcf binary via `import ...
+  with { type: "text" }`.
+- Sentinel-merge of `<!-- cfcf:begin --> ... <!-- cfcf:end -->` (in
+  `CLAUDE.md` / `AGENTS.md`) is dev-agent-specific and lives in
+  `context-assembler.ts` — separate concern from this item.
+
+## Design
+
+### Two layers
+
+1. **Existing**: `~/.cfcf/templates/<name>` is the single override file
+   `getTemplate()` reads. **Unchanged.** No runtime-code touched.
+2. **New**: `~/.cfcf/templates-managed/<name>/` is a managed directory of
+   saved versions + a manifest pointer to which one is "promoted". The
+   manager writes the promoted version's content to
+   `~/.cfcf/templates/<name>` (the existing override path) so the agent
+   runners pick it up automatically without any wiring change.
+
+### Storage layout
+
+```
+~/.cfcf/templates-managed/
+  cfcf-architect-instructions.md/
+    manifest.json     {
+                        currentVersionId: "v_<id>" | "default",
+                        versions: [
+                          { id, label, savedAt, contentHash }
+                        ]
+                      }
+    v_<id>.md         each saved version's content
+  cfcf-judge-instructions.md/
+    ...
+```
+
+`"default"` is a sentinel value meaning "no override active". When a user
+"promotes default", `~/.cfcf/templates/<name>` is **deleted** so
+`getTemplate` falls through to the embedded default.
+
+### Templates managed
+
+MVP scope:
+- `cfcf-architect-instructions.md`
+- `cfcf-judge-instructions.md`
+- `cfcf-documenter-instructions.md`
+- `cfcf-reflection-instructions.md`
+- `process.md` (workspace process template)
+
+**Out of scope for MVP**:
+- Dev role: no single template file (instructions are programmatically
+  generated by `context-assembler.generateInstructionContent()`). A
+  separate "custom directions" insertion-point design will follow.
+- Product Architect / Help Assistant: their system prompts are
+  programmatically assembled, not single template files.
+- Per-project (workspace-local) override management. The user-global
+  layer is the simpler scope for MVP; project-local stays the manual
+  power-user path (drop a file into `<repo>/cfcf-templates/`).
+
+### API
+
+`packages/core/src/role-templates.ts` exports:
+
+```ts
+type TemplateManaged = {
+  name: string;            // e.g. "cfcf-judge-instructions.md"
+  displayName: string;     // human label e.g. "Judge"
+  defaultContent: string;  // bundled default (read-only)
+  currentVersionId: string;        // "default" | "v_<id>"
+  currentContent: string;          // resolved content currently in effect
+  versions: TemplateVersion[];     // saved user versions
+};
+
+type TemplateVersion = {
+  id: string;              // "v_<random hex>"
+  label: string;           // user-supplied
+  savedAt: string;         // ISO timestamp
+  contentHash: string;     // sha256 short prefix
+};
+
+listManagedTemplates(): Promise<TemplateManaged[]>
+getManagedTemplate(name): Promise<TemplateManaged>
+saveVersion(name, { label, content }): Promise<TemplateVersion>
+updateVersion(name, versionId, { label?, content? }): Promise<TemplateVersion>
+deleteVersion(name, versionId): Promise<void>
+promoteVersion(name, versionId | "default"): Promise<void>
+getVersionContent(name, versionId | "default"): Promise<string>
+```
+
+### HTTP endpoints
+
+- `GET    /api/role-templates`                                  → list of TemplateManaged (sans full content)
+- `GET    /api/role-templates/:name`                            → full TemplateManaged
+- `GET    /api/role-templates/:name/versions/:versionId`        → { content }  (versionId = "default" or "v_<id>")
+- `POST   /api/role-templates/:name/versions`                   → { label, content }
+- `PUT    /api/role-templates/:name/versions/:versionId`        → { label?, content? }
+- `DELETE /api/role-templates/:name/versions/:versionId`        → 204
+- `POST   /api/role-templates/:name/promote`                    → { versionId } (or "default")
+
+### Web UI
+
+Top-level "Agents" route. Page renders left sidebar (role list) + main
+panel (textarea + version selector + actions).
+
+Main panel sections:
+1. **Heading**: role display name + "Currently in production: <label>".
+2. **Version selector**: dropdown listing "Default (built-in)" + each
+   user version. Selecting one loads its content into the textarea
+   (read-only by default).
+3. **Edit toggle**: "Edit" button toggles textarea to editable.
+4. **Save**: "Save as new version" → prompts for label, posts to
+   `POST .../versions`. New version appears in the dropdown.
+5. **Promote**: "Promote to production" button (active when current
+   selection ≠ promoted). Posts to `POST .../promote`.
+6. **Delete**: per-version "Delete" affordance (disabled for default).
+
+Search-within-content: deferred to Phase 2 (browser Cmd-F is fine for
+MVP scrollable textarea).
+
+Diff view between versions: deferred.
+
+### Why no template registry refactor
+
+The embedded `EMBEDDED` map in `templates.ts` already lists every
+managed template. The new layer reads the same list (we just import the
+constant). Adding a new role template in the future = add it to the
+embedded map, and the management UI picks it up automatically.
+
+### Risks + mitigations
+
+- **Storage growth**: each version is a full copy of the template
+  (~5-30 KB). Even 100 versions per role × 5 roles × 30 KB = 15 MB.
+  Negligible. No retention policy needed.
+- **Concurrent edits from multiple cfcf instances**: the manifest is
+  read-modify-write. Two simultaneous saves could race. Out of scope
+  for MVP — single-user-on-one-machine is the model. If it becomes a
+  concern, file-locking via `fcntl` or a Bun `lock`-style primitive.
+- **Content drift between manifest hash + file**: if a user edits
+  `v_<id>.md` directly outside cfcf, the hash won't match. Treat the
+  file as authoritative; the hash is informational only (UI display
+  for "has been edited externally").
+
+## Out of scope (deferred)
+
+- **Dev custom-directions block** (Tier 2 from the original 6.8 design)
+  — wait until ADLC research (6.11) settles the role model.
+- **Process-template versioning** — `process.md` IS in the MVP scope
+  above (it's just another managed template), but the broader idea of
+  "process versions per workspace, picked at workspace creation" is a
+  different feature.
+- **Diff viewer between versions**.
+- **Search within the textarea content** (browser Cmd-F suffices).
+- **Project-local override management UI** — the file-based path
+  remains the power-user escape hatch.
+
+## Tests
+
+- Core `role-templates.ts`: storage round-trip, save/list/promote/revert
+  flows, hash collision handling, manifest corruption recovery.
+- API endpoints: each verb, error paths.
+- Manual web smoke: edit, save, promote, revert, page reload preserves
+  state.
diff --git a/docs/plan.md b/docs/plan.md
index d8b094d..1f430e1 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -296,14 +296,14 @@ The tables below are the authoritative view of iteration progress. The **Notes**
 5. **Cerefox-parity Clio improvement** — *Shipped in v0.19.0:* FTS title boosting (**6.24**).
 6. **Adapter expansion driven by Anthropic harness policy** (**6.28**, surfaced 2026-05-07) — Anthropic's Jan→Apr 2026 clarification ([Cherny 2026-04-04](https://x.com/bcherny/status/1808066717213728812)) ties subscription OAuth tokens to interactive use only; cfcf's unattended iteration loop is the third-party-harness pattern the rule targets. Add ollama detection + three new adapters (`opencode` direct, `claude-code-ollama`, `opencode-ollama`) so unattended roles (dev / judge / reflection / documenter / auto-architect) can route to local ollama-served models via the `ollama launch <agent> --model <local-model>` exec wrapper (not via env-var proxy — explicit single command). Skills repository (**6.27**) also entered iter-6 as a research/design item on 2026-05-03.
 
-**Iter-6 active set after the cleanup**: 6.9, 6.11, 6.13, 6.18, 6.27, 6.28, 6.29, 6.30, 6.31, 6.32 (plus 6.19 partial: pre-warm-during-installer). 6.29 + 6.30 + 6.31 + 6.32 surfaced 2026-05-08 during 6.28's dogfood pass — kept in iter-6 to fix-while-debugging rather than defer. **Shipped in v0.18.0**: 6.20, 6.12, 6.26. **Shipped in v0.19.0**: 6.24. **Shipped 2026-05-02 on `feat/structured-pause-actions`**: 6.25. **Shipped in v0.20.0 (2026-05-08)**: 6.28. **Shipped in v0.21.0 (2026-05-08)**: 6.31, 6.30. **Shipped post-v0.21.0 (2026-05-08)**: 6.33. Items 6.1, 6.2, 6.10, 6.15 dropped to ⏸ (with rationales in their Notes columns); 6.8 marked ❌ but blocked on 6.11. See the status legend at the end of the section for what each icon means.
+**Iter-6 active set after the cleanup**: 6.9, 6.11, 6.13, 6.18, 6.27, 6.28, 6.29, 6.30, 6.31, 6.32 (plus 6.19 partial: pre-warm-during-installer). 6.29 + 6.30 + 6.31 + 6.32 surfaced 2026-05-08 during 6.28's dogfood pass — kept in iter-6 to fix-while-debugging rather than defer. **Shipped in v0.18.0**: 6.20, 6.12, 6.26. **Shipped in v0.19.0**: 6.24. **Shipped 2026-05-02 on `feat/structured-pause-actions`**: 6.25. **Shipped in v0.20.0 (2026-05-08)**: 6.28. **Shipped in v0.21.0 (2026-05-08)**: 6.31, 6.30. **Shipped post-v0.21.0 (2026-05-08)**: 6.33, 6.8 (round 1). Items 6.1, 6.2, 6.10, 6.15 dropped to ⏸ (with rationales in their Notes columns); 6.8 marked ❌ but blocked on 6.11. See the status legend at the end of the section for what each icon means.
 
 | # | Status | Title | Notes |
 |---|--------|-------|-------|
 | 6.1 | ⏸ | Diff viewer per iteration | **Dropped from iter-6 2026-05-02** — superseded by F.13 (rich diff viewer with annotation, in Backlog). The annotation layer is the differentiating value over plain syntax-highlighted diff; building 6.1 first would require redoing the whole surface as part of F.13 later. CLI users today have `git diff main..cfcf/iteration-N`; web users have the History tab + iteration-logs/handoffs/reviews archives. If demand for a richer in-UI diff materialises, F.13 is the canonical record. |
 | 6.2 | ⏸ | `cfcf log <workspace-name>` CLI | **Dropped from iter-6 2026-05-02** — subsumed by 6.12 (CLI ↔ web parity audit). Today's web History tab + `cfcf-docs/iteration-history.md` cover read-on-demand needs; manufacturing a dedicated `cfcf log` command before knowing what gap it closes is feature-shaped. Let the parity audit drive scope: if it surfaces a real CLI deficiency, scope a command then. |
 | 6.3 | ⏸ | `cfcf push <project-name>` CLI | **Dropped 2026-04-20.** Intended to wrap `git push` with project awareness + notification hooks, but (a) post-SUCCESS push is already handled automatically by the iteration loop (`gitManager.push(project.repoPath)` at end of a successful loop), (b) manual pushes are trivially `git push` from inside the repo -- no cfcf state needed, (c) the project-awareness value disappeared when `ProjectConfig.repoUrl` was removed in v0.7.5 (it was the only cfcf-specific piece the command would have consulted). Retaining the row as ⏸ so the decision is preserved; the surrounding CLI ↔ web parity question is still covered by 6.12. |
-| 6.8 | ❌ | Custom directions per role + process template versioning | **Resolved 2026-05-02 — blocked on 6.11.** Don't schedule independently in iter-6: the two-tier design is sound (see below), but the ADLC research (6.11) will sharpen what role-customisation actually needs to support — committing to a customisation surface before 6.11 risks a shape that doesn't fit ADLC's role abstraction. Pick up 6.8 as a follow-up to 6.11 once the role model is settled. **Two-tier design (preserved for reference)** that avoids fork-vs-upgrade pain: *(Tier 1, default for everyone)* cfcf ships current templates and upgrades them in place -- user gets new defaults on `cfcf` upgrade, no migration step. *(Tier 2, opt-in additional-directions block)* each role template gains a documented insertion point; if the user provides `cfcf-templates/custom-directions/<role>.md` (project-local) or `<CFCF_CONFIG_DIR>/templates/custom-directions/<role>.md` (user-global), cfcf splices it verbatim into the generated instruction file at that point, **in addition to** the default template. The block is user-owned -- cfcf never touches it on upgrade, so migration pain goes away because the defaults don't fork. Examples: "Documenter: use our internal report format, include X section"; "Dev: every commit message must reference a JIRA ticket ID"; "Architect: always include an accessibility review section". *(Tier 3, power-user fallback)* the existing full-template override path (`cfcf-templates/<name>.md`) remains available, documented as "you own the upgrade path for any template you fork". **Versioning piece:** track which cfcf version's defaults the project was created with, for debugging. |
+| 6.8 | 🔄 | Role-template management UI (full-template versioning + promote-to-production) | **Shipped 2026-05-08, post-v0.21.0 (round 1)**. Design doc: [`docs/design/role-template-management.md`](../design/role-template-management.md). **Decoupled from 6.11**: the 2026-05-02 "blocked on ADLC" framing assumed customisation needed to wait for the role-model to settle. Re-evaluated — the user's vision (concrete UI for editing + saving versions + promote-to-prod, with the cf²-shipped default always available) is independent of ADLC since it operates at the per-role-template granularity. Whatever role abstraction ADLC eventually settles on can layer on top of this without rework. **Shipped scope (round 1)**: (a) `packages/core/src/role-templates.ts` — versioning manager that hooks into the existing user-global override path (`~/.cfcf/templates/<name>`) without touching `getTemplate()`. Saved versions live under `~/.cfcf/templates-managed/<name>/{manifest.json, v_<id>.md}`. **Promoting a version** writes its content to the override file; **promoting "default"** deletes it (revert to bundled). Order-insensitive, self-healing manifest (corrupt JSON or missing version files fall back gracefully). Full CRUD: `listManagedTemplates`, `getManagedTemplate`, `getVersionContent`, `saveVersion`, `updateVersion` (refreshes override file when editing the promoted version), `deleteVersion` (auto-reverts if deleting the promoted), `promoteVersion`, `findOrphanedVersions`. New `getEmbeddedTemplate(name)` exported from `templates.ts` for read-only access to the bundled default. (b) HTTP API at `/api/role-templates/*` — list / get / per-version content / create / update / delete / promote, all backed by the core module with consistent `{ error: string }` response envelopes. (c) Web UI: new top-level **"Agents"** tab in the header (between Memory and Settings); `/agents` route with optional `?template=<name>` query for deep-linking; tab strip for the five managed templates; main panel shows version selector + editor (textarea, monospace, scrollable), promote/revert/delete actions, and an inline help block. The bundled default is always selectable but read-only — "Save as new version" forks it. (d) Tests: 30 unit tests (`role-templates.test.ts`) covering every flow + manifest-corruption recovery + cross-template isolation; 15 endpoint tests (`role-templates.test.ts` in server routes); 3 new route-parser tests for `/agents` + `?template=`. Total 808 core+cli pass + clean web build. **Managed templates (round 1)**: `cfcf-architect-instructions.md`, `cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`, `cfcf-reflection-instructions.md`, `process.md`. **Out of scope for round 1 (carried over)**: dev-role custom-directions block (the original Tier-2 idea — needs the sentinel-merge insertion-point design first; not blocking the rest of the UI), Product Architect / Help Assistant system-prompt management (their prompts are programmatically assembled rather than file-loaded), per-project (workspace-local) override management UI (the file-based path stays the power-user escape hatch), diff viewer between versions, search-within-content (browser Cmd-F suffices on a textarea). **Original two-tier design (preserved for reference, partly applies to deferred dev-role work)** that avoids fork-vs-upgrade pain: *(Tier 1, default for everyone)* cfcf ships current templates and upgrades them in place -- user gets new defaults on `cfcf` upgrade, no migration step. *(Tier 2, opt-in additional-directions block)* each role template gains a documented insertion point; if the user provides `cfcf-templates/custom-directions/<role>.md` (project-local) or `<CFCF_CONFIG_DIR>/templates/custom-directions/<role>.md` (user-global), cfcf splices it verbatim into the generated instruction file at that point, **in addition to** the default template. The block is user-owned -- cfcf never touches it on upgrade, so migration pain goes away because the defaults don't fork. Examples: "Documenter: use our internal report format, include X section"; "Dev: every commit message must reference a JIRA ticket ID"; "Architect: always include an accessibility review section". *(Tier 3, power-user fallback)* the existing full-template override path (`cfcf-templates/<name>.md`) remains available, documented as "you own the upgrade path for any template you fork". The shipped UI implements Tier 3 with versioning + promote-to-prod ergonomics on top; Tier 2 (custom-directions block for dev role) deferred to a follow-up branch. |
 | 6.9 | ❌ | Rationalise Clio usage across agent roles | **Reframed 2026-05-02** from "Optional Cerefox memory backend" — Clio shipped in 5.7 (local SQLite-backed memory layer with FTS + hybrid search). The new scope: **standardise how each agent role queries and writes Clio**, document the canonical patterns, ensure roles use semantic/hybrid search rather than grepping repo files. The main Clio benefits are (a) cross-workspace persistent memory and (b) efficient retrieval (semantic + FTS) — much more efficient than `grep` over `*.md` in the repo, especially as cfcf-docs and decision-log grow. **Scope**: audit each role's instructions template (dev / judge / architect / reflection / documenter / PA / HA) for current Clio guidance; rewrite to a consistent "search Clio for X before doing Y" pattern; document agent-side Clio patterns in `docs/research/`; possibly extract a shared "Clio cheat sheet" that gets injected into every role's prompt. **Out of scope**: a remote `CerefoxRemote` backend adapter (the original 6.9 item) — that stays optional/future, the `MemoryBackend` interface already exists for it. **Clio Project namespace convention (surfaced 2026-05-02 during 6.12 dogfooding)**: a few projects today have de-facto special meaning — `default` is the catch-all global bucket; `cfcf-memory-pa` is owned by the Product Architect; `cfcf-memory-global` is the cross-workspace shared bucket. Today every web picker (workspace creation, "Change Clio Project", Memory page sidebar) lists ALL projects unfiltered, including these system-managed ones. 6.9 should formalise the convention: pick a naming prefix (e.g. `cfcf-memory-*`) or an explicit registry of "system projects", document who owns each, and decide which projects are user-pickable vs. system-only at the picker site. Once the convention lands, web pickers add a one-line filter; until then, the unfiltered list is fine but users may pick a system project by mistake. **Read-audit gap (surfaced 2026-05-02 during 6.18 round-3 actor-convention work)**: cfcf's audit log captures mutations only (`ingest`, `update`, `delete`, `restore`, `edit-metadata`). Cerefox additionally maintains a `usage_log` for read operations (each `search` / `docs get` records the requestor + query). 6.9 should evaluate whether cfcf needs read-audit parity — likely yes for the same actor-convention reason (so analytics can answer "which roles search Clio most often?", "which queries return zero hits?"). New event type(s) + a new SQL table or a column on the audit table; CLI surface for query (`cfcf clio audit --reads`); also a privacy review (does logging every search query risk capturing sensitive prompt-leakage if the agent quotes problem.md content into a query?). |
 | 6.10 | ⏸ | Sandbox / guardrails research + POC | **Dropped from iter-6 2026-05-02** — moved to Backlog F.5 as durable record. Threat model that would justify sandbox engineering (untrusted Problem Pack from a third party? cfcf-as-a-service?) doesn't exist today: users run cfcf on their own machines under their own account; iteration isolation is already provided by git branches; Codex `--dangerously-skip-permissions` + Claude Code's matched mode give the unattended-loop permission profile cfcf needs. If/when a multi-tenant scenario emerges, macOS `sandbox-exec` / Linux `nsjail` / Anthropic's sandbox concept are the right primitives — research with concrete use cases at that point. F.5 in the Backlog carries the trigger note. |
 | 6.11 | ❌ | Generalisation research → Agent Development Life Cycle (ADLC) extension | **Iter-6 headline; research-only scope locked 2026-05-02.** Extend cfcf to non-coding iterative work, framed as researching a **parallel/configurable workflow alongside the current SDLC**, hardwired into the harness rather than bolted on. End game: refactor cfcf into a more dynamic, configurable harness where the SDLC is one of N built-in workflows (ADLC, content production, research projects, data analysis, strategy planning). **Research questions**: Is the Problem Pack shape general enough across workflow types? Does the dev / judge / architect / reflection / documenter role split map to non-coding workers, or do roles need to be workflow-specific too? Does the signal schema need workflow-specific shapes (no tests to pass for content production)? What's the "success criteria" surrogate when the artifact is a report rather than passing tests? **Output (iter-6)**: research doc at `docs/research/adlc-extension-design.md` enumerating options, decision points, and a concrete proposal. **Implementation deferred to iter-7+** — committing to a first-implementation stretch in iter-6 would commit to a deadline before the design is settled; if the research lands fast we'll re-evaluate at that point. Likely overlaps with the Cerefox Agent v0.1 vision. Pairs with 6.13 (scheduled execution) for the periodic-content use case. **6.8 (custom directions per role) is blocked on this** — pick up 6.8 once 6.11 settles the role model. |
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index d8c9520..2edf365 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -30,5 +30,7 @@ export * from "./update-check.js";
 export * from "./agent-models.js";
 export * from "./ollama-detection.js";
 export * from "./orphan-reaper.js";
+export * from "./role-templates.js";
+export { listTemplates, getEmbeddedTemplate } from "./templates.js";
 export { SEED_MODELS, getSeedModels } from "./adapters/seed-models.js";
 export type { SeedModelMap } from "./adapters/seed-models.js";
diff --git a/packages/core/src/role-templates.test.ts b/packages/core/src/role-templates.test.ts
new file mode 100644
index 0000000..a7e8192
--- /dev/null
+++ b/packages/core/src/role-templates.test.ts
@@ -0,0 +1,304 @@
+/**
+ * Tests for the role-template management layer (item 6.8).
+ *
+ * Covers:
+ * - listing managed templates
+ * - reading the bundled default vs user versions
+ * - save / update / delete / promote / revert flows
+ * - the override-file write/delete that hooks into the existing
+ *   `getTemplate()` resolution chain
+ * - manifest corruption recovery
+ * - orphan-version detection
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  listManagedTemplateNames,
+  listManagedTemplates,
+  getManagedTemplate,
+  getVersionContent,
+  saveVersion,
+  updateVersion,
+  deleteVersion,
+  promoteVersion,
+  findOrphanedVersions,
+  DEFAULT_VERSION_ID,
+} from "./role-templates.js";
+import { getTemplate, getEmbeddedTemplate } from "./templates.js";
+
+let tmpDir: string;
+let originalEnv: string | undefined;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "cfcf-role-tpl-"));
+  originalEnv = process.env.CFCF_CONFIG_DIR;
+  process.env.CFCF_CONFIG_DIR = tmpDir;
+});
+
+afterEach(() => {
+  if (originalEnv === undefined) delete process.env.CFCF_CONFIG_DIR;
+  else process.env.CFCF_CONFIG_DIR = originalEnv;
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+const JUDGE = "cfcf-judge-instructions.md";
+const ARCHITECT = "cfcf-architect-instructions.md";
+
+describe("listManagedTemplateNames", () => {
+  test("includes the four iteration roles + process template", () => {
+    const names = listManagedTemplateNames().map((t) => t.name);
+    expect(names).toContain("cfcf-architect-instructions.md");
+    expect(names).toContain("cfcf-judge-instructions.md");
+    expect(names).toContain("cfcf-documenter-instructions.md");
+    expect(names).toContain("cfcf-reflection-instructions.md");
+    expect(names).toContain("process.md");
+  });
+
+  test("provides display names for each", () => {
+    const items = listManagedTemplateNames();
+    for (const t of items) {
+      expect(t.displayName.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("listManagedTemplates", () => {
+  test("returns one summary per managed template, all on default initially", async () => {
+    const summaries = await listManagedTemplates();
+    expect(summaries.length).toBe(listManagedTemplateNames().length);
+    for (const s of summaries) {
+      expect(s.currentVersionId).toBe("default");
+      expect(s.versionCount).toBe(0);
+    }
+  });
+});
+
+describe("getManagedTemplate", () => {
+  test("returns the bundled default content + empty versions list initially", async () => {
+    const t = await getManagedTemplate(JUDGE);
+    expect(t.name).toBe(JUDGE);
+    expect(t.displayName).toBe("Judge");
+    expect(t.currentVersionId).toBe("default");
+    expect(t.versions).toEqual([]);
+    expect(t.defaultContent).toBe(getEmbeddedTemplate(JUDGE));
+    expect(t.currentContent).toBe(t.defaultContent);
+  });
+
+  test("rejects unknown template names", async () => {
+    expect(getManagedTemplate("nonexistent.md")).rejects.toThrow();
+  });
+
+  test("rejects template names that exist in EMBEDDED but aren't in the managed list", async () => {
+    // `iteration-handoff.md` is embedded but is internal scaffolding —
+    // not in MANAGED_TEMPLATES, so it should not be manageable.
+    expect(getManagedTemplate("iteration-handoff.md")).rejects.toThrow();
+  });
+});
+
+describe("saveVersion", () => {
+  test("creates a version, persists content, and adds to manifest", async () => {
+    const v = await saveVersion(JUDGE, { label: "stricter judge", content: "## Custom\nBe strict." });
+    expect(v.id).toMatch(/^v_/);
+    expect(v.label).toBe("stricter judge");
+    expect(v.savedAt).toMatch(/T/); // ISO
+    expect(v.contentHash.length).toBe(12);
+
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.versions).toHaveLength(1);
+    expect(managed.versions[0]).toEqual(v);
+    // Promoted is still default until explicitly promoted.
+    expect(managed.currentVersionId).toBe("default");
+  });
+
+  test("rejects empty labels", async () => {
+    expect(saveVersion(JUDGE, { label: "  ", content: "x" })).rejects.toThrow();
+  });
+
+  test("multiple saves produce distinct ids", async () => {
+    const v1 = await saveVersion(JUDGE, { label: "a", content: "A" });
+    const v2 = await saveVersion(JUDGE, { label: "b", content: "B" });
+    expect(v1.id).not.toBe(v2.id);
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.versions.map((v) => v.id).sort()).toEqual([v1.id, v2.id].sort());
+  });
+});
+
+describe("getVersionContent", () => {
+  test("returns the bundled default for 'default'", async () => {
+    const content = await getVersionContent(JUDGE, DEFAULT_VERSION_ID);
+    expect(content).toBe(getEmbeddedTemplate(JUDGE));
+  });
+
+  test("returns the saved content for a real version id", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "saved body" });
+    const content = await getVersionContent(JUDGE, v.id);
+    expect(content).toBe("saved body");
+  });
+
+  test("rejects unknown version ids", async () => {
+    expect(getVersionContent(JUDGE, "v_doesnotexist")).rejects.toThrow();
+  });
+
+  test("rejects malformed version ids", async () => {
+    expect(getVersionContent(JUDGE, "not-a-version-id")).rejects.toThrow();
+  });
+});
+
+describe("promoteVersion", () => {
+  test("writing the override file makes getTemplate() pick it up", async () => {
+    const v = await saveVersion(JUDGE, { label: "custom", content: "MY CUSTOM JUDGE" });
+    await promoteVersion(JUDGE, v.id);
+
+    // The override file must exist now.
+    const overridePath = join(tmpDir, "templates", JUDGE);
+    expect(existsSync(overridePath)).toBe(true);
+    expect(readFileSync(overridePath, "utf-8")).toBe("MY CUSTOM JUDGE");
+
+    // getTemplate must return the override content.
+    const resolved = await getTemplate(JUDGE);
+    expect(resolved).toBe("MY CUSTOM JUDGE");
+
+    // Manifest reflects the promoted version.
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.currentVersionId).toBe(v.id);
+    expect(managed.currentContent).toBe("MY CUSTOM JUDGE");
+  });
+
+  test("promoting 'default' deletes the override file and reverts to embedded", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "OVERRIDE" });
+    await promoteVersion(JUDGE, v.id);
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(true);
+
+    await promoteVersion(JUDGE, DEFAULT_VERSION_ID);
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(false);
+
+    const resolved = await getTemplate(JUDGE);
+    expect(resolved).toBe(getEmbeddedTemplate(JUDGE));
+  });
+
+  test("promoting an unknown version id throws", async () => {
+    expect(promoteVersion(JUDGE, "v_unknown")).rejects.toThrow();
+  });
+});
+
+describe("updateVersion", () => {
+  test("updates label only", async () => {
+    const v = await saveVersion(JUDGE, { label: "old", content: "body" });
+    const updated = await updateVersion(JUDGE, v.id, { label: "new label" });
+    expect(updated.label).toBe("new label");
+    expect(updated.contentHash).toBe(v.contentHash); // content unchanged
+    const content = await getVersionContent(JUDGE, v.id);
+    expect(content).toBe("body");
+  });
+
+  test("updates content only and refreshes hash", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "before" });
+    const updated = await updateVersion(JUDGE, v.id, { content: "after" });
+    expect(updated.contentHash).not.toBe(v.contentHash);
+    const content = await getVersionContent(JUDGE, v.id);
+    expect(content).toBe("after");
+  });
+
+  test("editing the promoted version refreshes the override file", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "v1" });
+    await promoteVersion(JUDGE, v.id);
+    expect(readFileSync(join(tmpDir, "templates", JUDGE), "utf-8")).toBe("v1");
+
+    await updateVersion(JUDGE, v.id, { content: "v2" });
+    expect(readFileSync(join(tmpDir, "templates", JUDGE), "utf-8")).toBe("v2");
+  });
+
+  test("rejects updating the bundled default", async () => {
+    expect(updateVersion(JUDGE, DEFAULT_VERSION_ID, { label: "x" })).rejects.toThrow();
+  });
+
+  test("rejects empty label", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "body" });
+    expect(updateVersion(JUDGE, v.id, { label: "  " })).rejects.toThrow();
+  });
+});
+
+describe("deleteVersion", () => {
+  test("removes the version + manifest entry + content file", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "body" });
+    await deleteVersion(JUDGE, v.id);
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.versions).toHaveLength(0);
+  });
+
+  test("deleting the promoted version reverts to default automatically", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "promoted" });
+    await promoteVersion(JUDGE, v.id);
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(true);
+
+    await deleteVersion(JUDGE, v.id);
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.currentVersionId).toBe("default");
+    // Override file deleted.
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(false);
+  });
+
+  test("rejects deleting the bundled default", async () => {
+    expect(deleteVersion(JUDGE, DEFAULT_VERSION_ID)).rejects.toThrow();
+  });
+});
+
+describe("isolation between templates", () => {
+  test("a version on judge doesn't appear under architect", async () => {
+    await saveVersion(JUDGE, { label: "x", content: "judge content" });
+    const arch = await getManagedTemplate(ARCHITECT);
+    expect(arch.versions).toHaveLength(0);
+  });
+
+  test("promoting one template doesn't write the other's override file", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "judge" });
+    await promoteVersion(JUDGE, v.id);
+    expect(existsSync(join(tmpDir, "templates", ARCHITECT))).toBe(false);
+  });
+});
+
+describe("findOrphanedVersions", () => {
+  test("returns ids whose v_*.md file was deleted out of band", async () => {
+    const v1 = await saveVersion(JUDGE, { label: "a", content: "A" });
+    const v2 = await saveVersion(JUDGE, { label: "b", content: "B" });
+    // Manually nuke v1's content file.
+    rmSync(join(tmpDir, "templates-managed", JUDGE, `${v1.id}.md`));
+    const orphans = await findOrphanedVersions(JUDGE);
+    expect(orphans).toEqual([v1.id]);
+    // v2 still on disk.
+    expect(orphans).not.toContain(v2.id);
+  });
+
+  test("returns empty list when everything is consistent", async () => {
+    await saveVersion(JUDGE, { label: "a", content: "A" });
+    const orphans = await findOrphanedVersions(JUDGE);
+    expect(orphans).toEqual([]);
+  });
+});
+
+describe("manifest corruption recovery", () => {
+  test("a malformed manifest returns the empty default state without throwing", async () => {
+    // Manually scaffold a corrupt manifest.
+    const dir = join(tmpDir, "templates-managed", JUDGE);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "manifest.json"), "{ broken json", "utf-8");
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.currentVersionId).toBe("default");
+    expect(managed.versions).toEqual([]);
+  });
+});
+
+describe("self-heal: stale promoted-version pointer", () => {
+  test("if the manifest points at a missing v_*.md, currentContent falls back to default", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "promoted" });
+    await promoteVersion(JUDGE, v.id);
+    // Externally remove the version content file but leave the manifest intact.
+    rmSync(join(tmpDir, "templates-managed", JUDGE, `${v.id}.md`));
+    const managed = await getManagedTemplate(JUDGE);
+    // The currentContent must fall back to default rather than throw.
+    expect(managed.currentContent).toBe(getEmbeddedTemplate(JUDGE));
+  });
+});
diff --git a/packages/core/src/role-templates.ts b/packages/core/src/role-templates.ts
new file mode 100644
index 0000000..e7a8d13
--- /dev/null
+++ b/packages/core/src/role-templates.ts
@@ -0,0 +1,467 @@
+/**
+ * Role-template management (item 6.8) — versioning + promote-to-production
+ * layer on top of the existing `getTemplate()` override mechanism in
+ * `templates.ts`.
+ *
+ * **Design** (full doc: `docs/design/role-template-management.md`):
+ *
+ * - The bundled default for each role is read from the EMBEDDED registry
+ *   in `templates.ts` (already shipped). Read-only, never deletable.
+ * - User-saved versions live under `~/.cfcf/templates-managed/<name>/`:
+ *
+ *   ```
+ *   ~/.cfcf/templates-managed/cfcf-judge-instructions.md/
+ *     manifest.json   { currentVersionId, versions: [{id, label, savedAt, contentHash}] }
+ *     v_<id>.md       content for each saved version
+ *   ```
+ *
+ * - When the user **promotes a version to production**, the manager writes
+ *   that version's content to `~/.cfcf/templates/<name>` (the existing
+ *   override path that `getTemplate()` already reads). No runtime change.
+ * - **Promoting "default"** deletes that override file so `getTemplate()`
+ *   falls through to the bundled default.
+ *
+ * **Managed templates (MVP)**: the four iteration-role instruction
+ * templates + the workspace process template. Dev's instructions are
+ * generated programmatically by `context-assembler.generateInstructionContent()`
+ * — a separate "custom directions" insertion-point design will follow.
+ */
+
+import { readFile, writeFile, mkdir, readdir, rm } from "fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "path";
+import { createHash, randomBytes } from "crypto";
+import { getConfigDir } from "./constants.js";
+import { listTemplates, getEmbeddedTemplate } from "./templates.js";
+
+// --- Public types ---
+
+export interface TemplateVersion {
+  id: string;
+  label: string;
+  savedAt: string;
+  /** Short prefix of sha256(content). Display-only. */
+  contentHash: string;
+}
+
+export interface ManagedTemplate {
+  name: string;
+  displayName: string;
+  /** The bundled default content, read-only. */
+  defaultContent: string;
+  /** "default" or a saved version id. The version that's currently the override file. */
+  currentVersionId: string;
+  /** The content currently in effect (default or the promoted version). */
+  currentContent: string;
+  /** User-saved versions. Empty array when nothing has been saved yet. */
+  versions: TemplateVersion[];
+}
+
+export interface ManagedTemplateSummary {
+  name: string;
+  displayName: string;
+  currentVersionId: string;
+  /** Number of user-saved versions (excludes default). */
+  versionCount: number;
+}
+
+// --- Managed-template registry ---
+
+/**
+ * The set of templates exposed via the management UI. Order matters —
+ * it's the tab order in the web UI. Only templates listed here can be
+ * managed; everything else in `EMBEDDED` is internal scaffolding (signal
+ * files, markdown stubs) that wouldn't make sense to expose.
+ *
+ * If you add a new role-instruction template to the embedded registry,
+ * add it here too to surface it in the management UI.
+ */
+const MANAGED_TEMPLATES: Array<{ name: string; displayName: string }> = [
+  { name: "cfcf-architect-instructions.md", displayName: "Solution Architect" },
+  { name: "cfcf-judge-instructions.md", displayName: "Judge" },
+  { name: "cfcf-documenter-instructions.md", displayName: "Documenter" },
+  { name: "cfcf-reflection-instructions.md", displayName: "Reflection" },
+  { name: "process.md", displayName: "Workspace Process" },
+];
+
+export function listManagedTemplateNames(): Array<{ name: string; displayName: string }> {
+  return [...MANAGED_TEMPLATES];
+}
+
+// --- Storage paths ---
+
+const DEFAULT_VERSION_ID = "default";
+const VERSION_ID_PREFIX = "v_";
+
+function templatesManagedRoot(): string {
+  return join(getConfigDir(), "templates-managed");
+}
+
+function templateDir(name: string): string {
+  return join(templatesManagedRoot(), name);
+}
+
+function manifestPath(name: string): string {
+  return join(templateDir(name), "manifest.json");
+}
+
+function versionFilePath(name: string, versionId: string): string {
+  return join(templateDir(name), `${versionId}.md`);
+}
+
+/** The override path read by `getTemplate()`. Promotion writes here. */
+function overrideFilePath(name: string): string {
+  return join(getConfigDir(), "templates", name);
+}
+
+// --- Manifest I/O ---
+
+interface Manifest {
+  currentVersionId: string;
+  versions: TemplateVersion[];
+}
+
+function emptyManifest(): Manifest {
+  // **Always return a fresh object + array** — earlier we kept a single
+  // shared EMPTY_MANIFEST constant and shallow-copied via `{...}`,
+  // which leaked the inner `versions: []` array between calls.
+  // `manifest.versions.push(...)` in saveVersion was mutating the
+  // shared array, so every subsequent fresh-manifest read started
+  // with stale versions.
+  return { currentVersionId: DEFAULT_VERSION_ID, versions: [] };
+}
+
+async function readManifest(name: string): Promise<Manifest> {
+  try {
+    const raw = await readFile(manifestPath(name), "utf-8");
+    const parsed = JSON.parse(raw) as Manifest;
+    // Defensive against partial / corrupt manifests.
+    if (
+      typeof parsed.currentVersionId !== "string" ||
+      !Array.isArray(parsed.versions)
+    ) {
+      return emptyManifest();
+    }
+    return parsed;
+  } catch {
+    return emptyManifest();
+  }
+}
+
+async function writeManifest(name: string, manifest: Manifest): Promise<void> {
+  await mkdir(templateDir(name), { recursive: true });
+  await writeFile(manifestPath(name), JSON.stringify(manifest, null, 2), "utf-8");
+}
+
+// --- Validators ---
+
+function assertManagedTemplate(name: string): void {
+  if (!MANAGED_TEMPLATES.some((t) => t.name === name)) {
+    throw new Error(
+      `Template "${name}" is not managed. Managed templates: ${MANAGED_TEMPLATES.map((t) => t.name).join(", ")}`,
+    );
+  }
+}
+
+function assertEmbeddedTemplate(name: string): void {
+  if (!listTemplates().includes(name)) {
+    throw new Error(`Unknown template: ${name}`);
+  }
+}
+
+function isVersionId(id: string): boolean {
+  return id === DEFAULT_VERSION_ID || id.startsWith(VERSION_ID_PREFIX);
+}
+
+// --- Helpers ---
+
+function generateVersionId(): string {
+  return VERSION_ID_PREFIX + randomBytes(6).toString("hex");
+}
+
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+
+/**
+ * Resolve the "default" content (bundled, read-only). Reads the
+ * embedded constant directly so we never pick up an override.
+ */
+function readDefaultContent(name: string): string {
+  return getEmbeddedTemplate(name);
+}
+
+/**
+ * Read the saved version content from disk.
+ *
+ * - `versionId === "default"` → embedded default (read-only).
+ * - any other id → `~/.cfcf/templates-managed/<name>/<id>.md`
+ */
+async function readVersionContent(name: string, versionId: string): Promise<string> {
+  if (versionId === DEFAULT_VERSION_ID) {
+    return readDefaultContent(name);
+  }
+  return readFile(versionFilePath(name, versionId), "utf-8");
+}
+
+// Note: `readDefaultContent` returns synchronously (it reads an
+// already-bundled string constant), but `readVersionContent` is async
+// because it touches disk. Callers `await` `readDefaultContent`
+// without harm (await on a non-promise is a no-op).
+
+// --- Public API ---
+
+/**
+ * List every managed template with summary info (no full content).
+ * Used by the web UI's role-tab list.
+ */
+export async function listManagedTemplates(): Promise<ManagedTemplateSummary[]> {
+  const out: ManagedTemplateSummary[] = [];
+  for (const t of MANAGED_TEMPLATES) {
+    const manifest = await readManifest(t.name);
+    out.push({
+      name: t.name,
+      displayName: t.displayName,
+      currentVersionId: manifest.currentVersionId,
+      versionCount: manifest.versions.length,
+    });
+  }
+  return out;
+}
+
+/**
+ * Get the full management state for one role template.
+ */
+export async function getManagedTemplate(name: string): Promise<ManagedTemplate> {
+  assertManagedTemplate(name);
+  const meta = MANAGED_TEMPLATES.find((t) => t.name === name)!;
+  const manifest = await readManifest(name);
+  const defaultContent = readDefaultContent(name);
+  const currentContent =
+    manifest.currentVersionId === DEFAULT_VERSION_ID
+      ? defaultContent
+      : await readVersionContent(name, manifest.currentVersionId).catch(() => {
+          // Promoted version's file is missing — manifest is stale.
+          // Self-heal: fall back to default.
+          return defaultContent;
+        });
+  return {
+    name,
+    displayName: meta.displayName,
+    defaultContent,
+    currentVersionId: manifest.currentVersionId,
+    currentContent,
+    versions: manifest.versions,
+  };
+}
+
+/**
+ * Read a specific version's content.
+ *
+ * `versionId === "default"` returns the bundled default.
+ */
+export async function getVersionContent(name: string, versionId: string): Promise<string> {
+  assertManagedTemplate(name);
+  if (!isVersionId(versionId)) {
+    throw new Error(`Invalid version id: ${versionId}`);
+  }
+  if (versionId === DEFAULT_VERSION_ID) {
+    return readDefaultContent(name);
+  }
+  // Verify the version exists in the manifest before reading the file
+  // (defends against passing in a guessed id).
+  const manifest = await readManifest(name);
+  if (!manifest.versions.some((v) => v.id === versionId)) {
+    throw new Error(`Version not found: ${versionId}`);
+  }
+  return readFile(versionFilePath(name, versionId), "utf-8");
+}
+
+/**
+ * Save a new user version.
+ */
+export async function saveVersion(
+  name: string,
+  opts: { label: string; content: string },
+): Promise<TemplateVersion> {
+  assertManagedTemplate(name);
+  const label = opts.label.trim();
+  if (!label) throw new Error("Version label cannot be empty");
+  const content = opts.content;
+  if (typeof content !== "string") throw new Error("Version content must be a string");
+
+  await mkdir(templateDir(name), { recursive: true });
+  const id = generateVersionId();
+  await writeFile(versionFilePath(name, id), content, "utf-8");
+
+  const version: TemplateVersion = {
+    id,
+    label,
+    savedAt: new Date().toISOString(),
+    contentHash: hashContent(content),
+  };
+
+  const manifest = await readManifest(name);
+  manifest.versions.push(version);
+  await writeManifest(name, manifest);
+  return version;
+}
+
+/**
+ * Update a saved version's label or content (or both).
+ */
+export async function updateVersion(
+  name: string,
+  versionId: string,
+  opts: { label?: string; content?: string },
+): Promise<TemplateVersion> {
+  assertManagedTemplate(name);
+  if (versionId === DEFAULT_VERSION_ID) {
+    throw new Error("The bundled default version is read-only");
+  }
+  if (!versionId.startsWith(VERSION_ID_PREFIX)) {
+    throw new Error(`Invalid version id: ${versionId}`);
+  }
+  const manifest = await readManifest(name);
+  const idx = manifest.versions.findIndex((v) => v.id === versionId);
+  if (idx === -1) throw new Error(`Version not found: ${versionId}`);
+  const existing = manifest.versions[idx];
+
+  let nextLabel = existing.label;
+  let nextHash = existing.contentHash;
+
+  if (typeof opts.label === "string") {
+    const label = opts.label.trim();
+    if (!label) throw new Error("Version label cannot be empty");
+    nextLabel = label;
+  }
+  if (typeof opts.content === "string") {
+    await writeFile(versionFilePath(name, versionId), opts.content, "utf-8");
+    nextHash = hashContent(opts.content);
+    // If the user edits the currently-promoted version, refresh the
+    // override file too so runtime picks up the change without a
+    // separate re-promote step.
+    if (manifest.currentVersionId === versionId) {
+      await writeOverrideFile(name, opts.content);
+    }
+  }
+
+  const updated: TemplateVersion = {
+    ...existing,
+    label: nextLabel,
+    contentHash: nextHash,
+  };
+  manifest.versions[idx] = updated;
+  await writeManifest(name, manifest);
+  return updated;
+}
+
+/**
+ * Delete a saved version. Cannot delete "default". If the deleted
+ * version was the promoted one, automatically reverts to default.
+ */
+export async function deleteVersion(name: string, versionId: string): Promise<void> {
+  assertManagedTemplate(name);
+  if (versionId === DEFAULT_VERSION_ID) {
+    throw new Error("Cannot delete the bundled default version");
+  }
+  if (!versionId.startsWith(VERSION_ID_PREFIX)) {
+    throw new Error(`Invalid version id: ${versionId}`);
+  }
+  const manifest = await readManifest(name);
+  const idx = manifest.versions.findIndex((v) => v.id === versionId);
+  if (idx === -1) throw new Error(`Version not found: ${versionId}`);
+
+  manifest.versions.splice(idx, 1);
+
+  // If we deleted the promoted version, fall back to default.
+  if (manifest.currentVersionId === versionId) {
+    manifest.currentVersionId = DEFAULT_VERSION_ID;
+    await deleteOverrideFile(name);
+  }
+
+  // Best-effort delete of the version file. Manifest write is the
+  // canonical source of truth — if the file removal fails (read-only
+  // FS, etc.) the manifest update is still saved.
+  try {
+    await rm(versionFilePath(name, versionId), { force: true });
+  } catch {
+    /* swallow */
+  }
+
+  await writeManifest(name, manifest);
+}
+
+/**
+ * Promote a version (or "default") to production. Writes the override
+ * file (or deletes it for "default") so `getTemplate()` picks up the
+ * change for every subsequent agent spawn.
+ */
+export async function promoteVersion(name: string, versionId: string): Promise<void> {
+  assertManagedTemplate(name);
+  if (!isVersionId(versionId)) {
+    throw new Error(`Invalid version id: ${versionId}`);
+  }
+
+  if (versionId === DEFAULT_VERSION_ID) {
+    await deleteOverrideFile(name);
+  } else {
+    const manifest = await readManifest(name);
+    if (!manifest.versions.some((v) => v.id === versionId)) {
+      throw new Error(`Version not found: ${versionId}`);
+    }
+    const content = await readFile(versionFilePath(name, versionId), "utf-8");
+    await writeOverrideFile(name, content);
+  }
+
+  const manifest = await readManifest(name);
+  manifest.currentVersionId = versionId;
+  await writeManifest(name, manifest);
+}
+
+// --- Override-file helpers ---
+
+async function writeOverrideFile(name: string, content: string): Promise<void> {
+  assertEmbeddedTemplate(name);
+  const path = overrideFilePath(name);
+  await mkdir(join(getConfigDir(), "templates"), { recursive: true });
+  await writeFile(path, content, "utf-8");
+}
+
+async function deleteOverrideFile(name: string): Promise<void> {
+  assertEmbeddedTemplate(name);
+  const path = overrideFilePath(name);
+  if (existsSync(path)) {
+    await rm(path, { force: true });
+  }
+}
+
+// --- Maintenance / diagnostics ---
+
+/**
+ * Detect manifest entries whose corresponding `v_<id>.md` file is
+ * missing on disk. Useful for `cfcf doctor` and as a self-heal hook.
+ */
+export async function findOrphanedVersions(name: string): Promise<string[]> {
+  const manifest = await readManifest(name);
+  const orphans: string[] = [];
+  let onDisk: string[] = [];
+  try {
+    const entries = await readdir(templateDir(name));
+    onDisk = entries.filter((e) => e.startsWith(VERSION_ID_PREFIX) && e.endsWith(".md"))
+      .map((e) => e.slice(0, -3));
+  } catch {
+    /* dir doesn't exist; every manifest version is orphaned */
+  }
+  for (const v of manifest.versions) {
+    if (!onDisk.includes(v.id)) orphans.push(v.id);
+  }
+  return orphans;
+}
+
+// --- Shared internal export for templates.ts integration ---
+
+export {
+  DEFAULT_VERSION_ID,
+  templatesManagedRoot,
+};
diff --git a/packages/core/src/templates.ts b/packages/core/src/templates.ts
index 89eb9a8..09135d9 100644
--- a/packages/core/src/templates.ts
+++ b/packages/core/src/templates.ts
@@ -150,6 +150,20 @@ export function listTemplates(): string[] {
   return Object.keys(EMBEDDED);
 }
 
+/**
+ * Return the embedded (bundled) default for a template, ignoring any
+ * project-local or user-global overrides. Used by `role-templates.ts`
+ * to surface "the cfcf-shipped default" as a non-deletable version
+ * the user can always revert to. Throws if the template name isn't
+ * known.
+ */
+export function getEmbeddedTemplate(name: string): string {
+  if (!(name in EMBEDDED)) {
+    throw new Error(`Unknown template: ${name}. Known templates: ${Object.keys(EMBEDDED).join(", ")}`);
+  }
+  return EMBEDDED[name];
+}
+
 // --- Helpers ---
 
 async function tryRead(path: string): Promise<string | null> {
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index a1c38ee..53b41c4 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -16,6 +16,7 @@ import { registerClioRoutes } from "./routes/clio.js";
 import { registerHelpRoutes } from "./routes/help.js";
 import { registerUpdateRoutes } from "./routes/update.js";
 import { registerAgentModelsRoutes } from "./routes/agent-models.js";
+import { registerRoleTemplatesRoutes } from "./routes/role-templates.js";
 import {
   createWorkspace,
   listWorkspaces,
@@ -1111,6 +1112,10 @@ export function createApp() {
   // pickers (Settings + workspace Config). Item 6.26.
   registerAgentModelsRoutes(app);
 
+  // /api/role-templates/* -- role-instruction template versioning
+  // and promote-to-production layer (item 6.8).
+  registerRoleTemplatesRoutes(app);
+
   // --- Static file serving (Web GUI) ---
   //
   // The web bundle is embedded into the server module (via
diff --git a/packages/server/src/routes/role-templates.test.ts b/packages/server/src/routes/role-templates.test.ts
new file mode 100644
index 0000000..5c7ebce
--- /dev/null
+++ b/packages/server/src/routes/role-templates.test.ts
@@ -0,0 +1,243 @@
+/**
+ * `/api/role-templates/*` HTTP tests (item 6.8).
+ *
+ * The route delegates to `@cfcf/core/role-templates`, which is
+ * exhaustively unit-tested at `packages/core/src/role-templates.test.ts`.
+ * These tests focus on the HTTP shape: status codes, body validation,
+ * error envelopes, and round-trip behaviour from the network surface.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createApp } from "../app.js";
+
+let tmpDir: string;
+let originalEnv: string | undefined;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "cfcf-role-tpl-api-"));
+  originalEnv = process.env.CFCF_CONFIG_DIR;
+  process.env.CFCF_CONFIG_DIR = tmpDir;
+});
+
+afterEach(() => {
+  if (originalEnv === undefined) delete process.env.CFCF_CONFIG_DIR;
+  else process.env.CFCF_CONFIG_DIR = originalEnv;
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+const JUDGE = "cfcf-judge-instructions.md";
+const JUDGE_ENC = encodeURIComponent(JUDGE);
+
+describe("GET /api/role-templates", () => {
+  it("returns one summary per managed template, all on default", async () => {
+    const app = createApp();
+    const res = await app.request("/api/role-templates");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(Array.isArray(body.templates)).toBe(true);
+    expect(body.templates.length).toBeGreaterThanOrEqual(5);
+    for (const t of body.templates) {
+      expect(t.currentVersionId).toBe("default");
+      expect(t.versionCount).toBe(0);
+    }
+  });
+});
+
+describe("GET /api/role-templates/:name", () => {
+  it("returns the full state with bundled default content", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.name).toBe(JUDGE);
+    expect(body.displayName).toBe("Judge");
+    expect(body.currentVersionId).toBe("default");
+    expect(body.defaultContent.length).toBeGreaterThan(0);
+    expect(body.currentContent).toBe(body.defaultContent);
+    expect(body.versions).toEqual([]);
+  });
+
+  it("returns 404 for unknown template names", async () => {
+    const app = createApp();
+    const res = await app.request("/api/role-templates/nonexistent.md");
+    expect(res.status).toBe(404);
+    const body = await res.json();
+    expect(typeof body.error).toBe("string");
+  });
+});
+
+describe("POST /api/role-templates/:name/versions", () => {
+  it("creates a new version and returns 201", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "stricter judge", content: "## Custom\nBody" }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.id).toMatch(/^v_/);
+    expect(body.label).toBe("stricter judge");
+    expect(body.contentHash.length).toBe(12);
+  });
+
+  it("rejects non-JSON body with 400", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      body: "not json",
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects missing label or content with 400", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "no body" }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects empty label with 400", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "  ", content: "x" }),
+    });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("GET /api/role-templates/:name/versions/:versionId", () => {
+  it("returns the bundled default for versionId='default'", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions/default`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(typeof body.content).toBe("string");
+    expect(body.content.length).toBeGreaterThan(0);
+  });
+
+  it("returns 404 for unknown version id", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions/v_nope`);
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("PUT /api/role-templates/:name/versions/:versionId", () => {
+  it("updates the label", async () => {
+    const app = createApp();
+    const create = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "old", content: "body" }),
+    });
+    const v = await create.json();
+    const update = await app.request(`/api/role-templates/${JUDGE_ENC}/versions/${v.id}`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "new label" }),
+    });
+    expect(update.status).toBe(200);
+    const body = await update.json();
+    expect(body.label).toBe("new label");
+  });
+
+  it("rejects updating the bundled default with 400", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions/default`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "x" }),
+    });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("POST /api/role-templates/:name/promote", () => {
+  it("promotes a version, writes the override file, returns refreshed state", async () => {
+    const app = createApp();
+    const create = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "custom", content: "MY OVERRIDE" }),
+    });
+    const v = await create.json();
+    const promote = await app.request(`/api/role-templates/${JUDGE_ENC}/promote`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ versionId: v.id }),
+    });
+    expect(promote.status).toBe(200);
+    const body = await promote.json();
+    expect(body.currentVersionId).toBe(v.id);
+    expect(body.currentContent).toBe("MY OVERRIDE");
+
+    // Override file written.
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(true);
+    expect(readFileSync(join(tmpDir, "templates", JUDGE), "utf-8")).toBe("MY OVERRIDE");
+  });
+
+  it("promoting 'default' deletes the override file", async () => {
+    const app = createApp();
+    // First create + promote a version.
+    const create = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "x", content: "OVERRIDE" }),
+    });
+    const v = await create.json();
+    await app.request(`/api/role-templates/${JUDGE_ENC}/promote`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ versionId: v.id }),
+    });
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(true);
+
+    // Now revert to default.
+    const revert = await app.request(`/api/role-templates/${JUDGE_ENC}/promote`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ versionId: "default" }),
+    });
+    expect(revert.status).toBe(200);
+    const body = await revert.json();
+    expect(body.currentVersionId).toBe("default");
+    // Override file gone.
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(false);
+  });
+});
+
+describe("DELETE /api/role-templates/:name/versions/:versionId", () => {
+  it("deletes a version and returns refreshed template state", async () => {
+    const app = createApp();
+    const create = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "x", content: "body" }),
+    });
+    const v = await create.json();
+    const del = await app.request(`/api/role-templates/${JUDGE_ENC}/versions/${v.id}`, {
+      method: "DELETE",
+    });
+    expect(del.status).toBe(200);
+    const body = await del.json();
+    expect(body.deleted).toBe(true);
+    expect(body.template.versions).toHaveLength(0);
+  });
+
+  it("rejects deleting the bundled default with 400", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions/default`, {
+      method: "DELETE",
+    });
+    expect(res.status).toBe(400);
+  });
+});
diff --git a/packages/server/src/routes/role-templates.ts b/packages/server/src/routes/role-templates.ts
new file mode 100644
index 0000000..1b48e4b
--- /dev/null
+++ b/packages/server/src/routes/role-templates.ts
@@ -0,0 +1,143 @@
+/**
+ * `/api/role-templates/*` -- versioning + promote-to-production layer
+ * for role-instruction templates (item 6.8). Backed by
+ * `@cfcf/core/role-templates`.
+ *
+ * Endpoints:
+ *   GET    /api/role-templates                                  list summaries
+ *   GET    /api/role-templates/:name                            full state
+ *   GET    /api/role-templates/:name/versions/:versionId        content body
+ *   POST   /api/role-templates/:name/versions                   create version
+ *   PUT    /api/role-templates/:name/versions/:versionId        update label/content
+ *   DELETE /api/role-templates/:name/versions/:versionId        delete version
+ *   POST   /api/role-templates/:name/promote                    promote to prod
+ *
+ * Names are URL-encoded (templates contain `.md`). Errors return 4xx
+ * with `{ error: string }`.
+ */
+
+import type { Hono } from "hono";
+import {
+  listManagedTemplates,
+  getManagedTemplate,
+  getVersionContent,
+  saveVersion,
+  updateVersion,
+  deleteVersion,
+  promoteVersion,
+} from "@cfcf/core";
+
+function errorBody(err: unknown): { error: string } {
+  return { error: err instanceof Error ? err.message : String(err) };
+}
+
+export function registerRoleTemplatesRoutes(app: Hono): void {
+  app.get("/api/role-templates", async (c) => {
+    try {
+      const summaries = await listManagedTemplates();
+      return c.json({ templates: summaries });
+    } catch (err) {
+      return c.json(errorBody(err), 500);
+    }
+  });
+
+  app.get("/api/role-templates/:name", async (c) => {
+    const name = decodeURIComponent(c.req.param("name"));
+    try {
+      const t = await getManagedTemplate(name);
+      return c.json(t);
+    } catch (err) {
+      return c.json(errorBody(err), 404);
+    }
+  });
+
+  app.get("/api/role-templates/:name/versions/:versionId", async (c) => {
+    const name = decodeURIComponent(c.req.param("name"));
+    const versionId = decodeURIComponent(c.req.param("versionId"));
+    try {
+      const content = await getVersionContent(name, versionId);
+      return c.json({ content });
+    } catch (err) {
+      return c.json(errorBody(err), 404);
+    }
+  });
+
+  app.post("/api/role-templates/:name/versions", async (c) => {
+    const name = decodeURIComponent(c.req.param("name"));
+    let body: { label?: unknown; content?: unknown };
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "Body must be JSON" }, 400);
+    }
+    if (typeof body.label !== "string" || typeof body.content !== "string") {
+      return c.json({ error: "Body must include `label` and `content` (both strings)" }, 400);
+    }
+    try {
+      const v = await saveVersion(name, { label: body.label, content: body.content });
+      return c.json(v, 201);
+    } catch (err) {
+      return c.json(errorBody(err), 400);
+    }
+  });
+
+  app.put("/api/role-templates/:name/versions/:versionId", async (c) => {
+    const name = decodeURIComponent(c.req.param("name"));
+    const versionId = decodeURIComponent(c.req.param("versionId"));
+    let body: { label?: unknown; content?: unknown };
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "Body must be JSON" }, 400);
+    }
+    const opts: { label?: string; content?: string } = {};
+    if (typeof body.label === "string") opts.label = body.label;
+    if (typeof body.content === "string") opts.content = body.content;
+    if (opts.label === undefined && opts.content === undefined) {
+      return c.json({ error: "Body must include at least one of `label` or `content`" }, 400);
+    }
+    try {
+      const v = await updateVersion(name, versionId, opts);
+      return c.json(v);
+    } catch (err) {
+      return c.json(errorBody(err), 400);
+    }
+  });
+
+  app.delete("/api/role-templates/:name/versions/:versionId", async (c) => {
+    const name = decodeURIComponent(c.req.param("name"));
+    const versionId = decodeURIComponent(c.req.param("versionId"));
+    try {
+      await deleteVersion(name, versionId);
+      // Return the refreshed template so the UI can update local
+      // state without an extra GET (mirrors POST /promote's
+      // response shape).
+      const refreshed = await getManagedTemplate(name);
+      return c.json({ deleted: true, template: refreshed });
+    } catch (err) {
+      return c.json(errorBody(err), 400);
+    }
+  });
+
+  app.post("/api/role-templates/:name/promote", async (c) => {
+    const name = decodeURIComponent(c.req.param("name"));
+    let body: { versionId?: unknown };
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "Body must be JSON" }, 400);
+    }
+    if (typeof body.versionId !== "string") {
+      return c.json({ error: "Body must include `versionId`" }, 400);
+    }
+    try {
+      await promoteVersion(name, body.versionId);
+      // Return the refreshed template so the UI can update without
+      // an extra GET.
+      const refreshed = await getManagedTemplate(name);
+      return c.json(refreshed);
+    } catch (err) {
+      return c.json(errorBody(err), 400);
+    }
+  });
+}
diff --git a/packages/web/src/App.tsx b/packages/web/src/App.tsx
index 957b85c..d292e0b 100644
--- a/packages/web/src/App.tsx
+++ b/packages/web/src/App.tsx
@@ -5,6 +5,7 @@ import { WorkspaceDetail } from "./pages/WorkspaceDetail";
 import { ServerInfo } from "./pages/ServerInfo";
 import { HelpPage } from "./pages/Help";
 import { MemoryPage } from "./pages/Memory";
+import { AgentTemplatesPage } from "./pages/AgentTemplates";
 import { useRoute } from "./hooks/useRoute";
 import { ServerStatusProvider } from "./hooks/useServerStatus";
 
@@ -25,6 +26,8 @@ export function App() {
             <HelpPage />
           ) : route.page === "memory" ? (
             <MemoryPage />
+          ) : route.page === "agents" ? (
+            <AgentTemplatesPage initialTemplate={route.agentTemplate} />
           ) : (
             <Dashboard />
           )}
diff --git a/packages/web/src/api.ts b/packages/web/src/api.ts
index daa4e10..3cfff8f 100644
--- a/packages/web/src/api.ts
+++ b/packages/web/src/api.ts
@@ -336,6 +336,87 @@ export function refreshOllamaModels(): Promise<RefreshOllamaModelsResponse> {
   return request<RefreshOllamaModelsResponse>("/api/agents/refresh-ollama-models", { method: "POST" });
 }
 
+// --- Role-template management (item 6.8) ---
+
+export interface RoleTemplateVersion {
+  id: string;
+  label: string;
+  savedAt: string;
+  contentHash: string;
+}
+
+export interface RoleTemplateSummary {
+  name: string;
+  displayName: string;
+  currentVersionId: string;
+  versionCount: number;
+}
+
+export interface RoleTemplateFull {
+  name: string;
+  displayName: string;
+  defaultContent: string;
+  currentVersionId: string;
+  currentContent: string;
+  versions: RoleTemplateVersion[];
+}
+
+export function listRoleTemplates(): Promise<{ templates: RoleTemplateSummary[] }> {
+  return request<{ templates: RoleTemplateSummary[] }>("/api/role-templates");
+}
+
+export function getRoleTemplate(name: string): Promise<RoleTemplateFull> {
+  return request<RoleTemplateFull>(`/api/role-templates/${encodeURIComponent(name)}`);
+}
+
+export function getRoleTemplateVersionContent(name: string, versionId: string): Promise<{ content: string }> {
+  return request<{ content: string }>(
+    `/api/role-templates/${encodeURIComponent(name)}/versions/${encodeURIComponent(versionId)}`,
+  );
+}
+
+export function createRoleTemplateVersion(
+  name: string,
+  body: { label: string; content: string },
+): Promise<RoleTemplateVersion> {
+  return request<RoleTemplateVersion>(
+    `/api/role-templates/${encodeURIComponent(name)}/versions`,
+    { method: "POST", body: JSON.stringify(body), headers: { "content-type": "application/json" } },
+  );
+}
+
+export function updateRoleTemplateVersion(
+  name: string,
+  versionId: string,
+  body: { label?: string; content?: string },
+): Promise<RoleTemplateVersion> {
+  return request<RoleTemplateVersion>(
+    `/api/role-templates/${encodeURIComponent(name)}/versions/${encodeURIComponent(versionId)}`,
+    { method: "PUT", body: JSON.stringify(body), headers: { "content-type": "application/json" } },
+  );
+}
+
+export function deleteRoleTemplateVersion(
+  name: string,
+  versionId: string,
+): Promise<{ deleted: boolean; template: RoleTemplateFull }> {
+  return request<{ deleted: boolean; template: RoleTemplateFull }>(
+    `/api/role-templates/${encodeURIComponent(name)}/versions/${encodeURIComponent(versionId)}`,
+    { method: "DELETE" },
+  );
+}
+
+export function promoteRoleTemplateVersion(name: string, versionId: string): Promise<RoleTemplateFull> {
+  return request<RoleTemplateFull>(
+    `/api/role-templates/${encodeURIComponent(name)}/promote`,
+    {
+      method: "POST",
+      body: JSON.stringify({ versionId }),
+      headers: { "content-type": "application/json" },
+    },
+  );
+}
+
 // --- Reflect (item 5.6 / web surface in 6.12) ---
 
 export interface ReflectState {
diff --git a/packages/web/src/components/Header.tsx b/packages/web/src/components/Header.tsx
index fe34a64..97c0535 100644
--- a/packages/web/src/components/Header.tsx
+++ b/packages/web/src/components/Header.tsx
@@ -67,6 +67,15 @@ export function Header() {
         >
           Memory
         </a>
+        <a
+          href="#/agents"
+          onClick={(e) => {
+            e.preventDefault();
+            navigateTo("/agents");
+          }}
+        >
+          Agents
+        </a>
         <a
           href="#/server"
           onClick={(e) => {
diff --git a/packages/web/src/hooks/useRoute.test.ts b/packages/web/src/hooks/useRoute.test.ts
index 1879b51..4f2e12b 100644
--- a/packages/web/src/hooks/useRoute.test.ts
+++ b/packages/web/src/hooks/useRoute.test.ts
@@ -96,4 +96,27 @@ describe("parseRouteHash", () => {
       memoryDocId: undefined,
     });
   });
+
+  // Agents page (item 6.8) — role-template management.
+
+  test("/agents → agents page (no template selected)", () => {
+    expect(parseRouteHash("/agents")).toEqual({
+      page: "agents",
+      agentTemplate: undefined,
+    });
+  });
+
+  test("/agents?template=cfcf-judge-instructions.md → agents page with selected template", () => {
+    expect(parseRouteHash("/agents?template=cfcf-judge-instructions.md")).toEqual({
+      page: "agents",
+      agentTemplate: "cfcf-judge-instructions.md",
+    });
+  });
+
+  test("agents template name with URL encoding is decoded", () => {
+    expect(parseRouteHash("/agents?template=cfcf-architect-instructions.md")).toEqual({
+      page: "agents",
+      agentTemplate: "cfcf-architect-instructions.md",
+    });
+  });
 });
diff --git a/packages/web/src/hooks/useRoute.ts b/packages/web/src/hooks/useRoute.ts
index 3cf3d68..bc5e333 100644
--- a/packages/web/src/hooks/useRoute.ts
+++ b/packages/web/src/hooks/useRoute.ts
@@ -3,13 +3,15 @@ import { useState, useEffect } from "react";
 export type MemoryTab = "search" | "browse" | "ingest" | "audit" | "projects" | "trash";
 
 interface Route {
-  page: "dashboard" | "workspace" | "server" | "help" | "memory";
+  page: "dashboard" | "workspace" | "server" | "help" | "memory" | "agents";
   workspaceId?: string;
   helpTopic?: string;
   /** Memory page sub-tab (item 6.18). Defaults to "search". */
   memoryTab?: MemoryTab;
   /** Memory page document detail overlay (item 6.18). */
   memoryDocId?: string;
+  /** Agents page selected role-template name (item 6.8). */
+  agentTemplate?: string;
 }
 
 /**
@@ -37,6 +39,14 @@ function parseHashImpl(hash: string): Route {
   if (hash === "/server") {
     return { page: "server" };
   }
+  // Agents page (item 6.8): `/agents` lands on the first role; an
+  // optional `?template=<name>` selects a specific role-template tab.
+  if (hash === "/agents" || hash.startsWith("/agents?")) {
+    const qIdx = hash.indexOf("?");
+    const params = qIdx >= 0 ? new URLSearchParams(hash.slice(qIdx + 1)) : new URLSearchParams();
+    const tpl = params.get("template");
+    return { page: "agents", agentTemplate: tpl ?? undefined };
+  }
   // Memory: support `?tab=…&doc=…` query string, e.g. `#/memory?tab=ingest`.
   // Hash routers don't get the URL's real query string, so we parse a
   // query-like fragment after the hash path manually.
diff --git a/packages/web/src/pages/AgentTemplates.tsx b/packages/web/src/pages/AgentTemplates.tsx
new file mode 100644
index 0000000..90b9999
--- /dev/null
+++ b/packages/web/src/pages/AgentTemplates.tsx
@@ -0,0 +1,512 @@
+/**
+ * Agents page (item 6.8): role-template management UI.
+ *
+ * Top-level layout: a tab strip across the top (one tab per managed
+ * role template), then the main panel for the selected role with:
+ *   - Heading + "currently in production" indicator
+ *   - Version selector dropdown
+ *   - Editor (textarea) — read-only by default; toggle Edit to make
+ *     it editable. Save creates a new version with a label.
+ *   - Promote-to-production / Revert-to-default actions
+ *   - Per-version delete affordance (disabled for default)
+ *
+ * State model: the currently-selected version is tracked locally
+ * (`selectedVersionId`); when the user picks a different version
+ * we re-fetch the content. The "promoted" version is whatever the
+ * server says — independent of which version the user is viewing.
+ */
+
+import { useEffect, useState } from "react";
+import {
+  listRoleTemplates,
+  getRoleTemplate,
+  getRoleTemplateVersionContent,
+  createRoleTemplateVersion,
+  updateRoleTemplateVersion,
+  deleteRoleTemplateVersion,
+  promoteRoleTemplateVersion,
+  type RoleTemplateSummary,
+  type RoleTemplateFull,
+  type RoleTemplateVersion,
+} from "../api";
+import { navigateTo } from "../hooks/useRoute";
+
+const DEFAULT_VERSION_ID = "default";
+
+interface Props {
+  /** Optional preselected template name (from `?template=` query). */
+  initialTemplate?: string;
+}
+
+export function AgentTemplatesPage({ initialTemplate }: Props) {
+  const [summaries, setSummaries] = useState<RoleTemplateSummary[]>([]);
+  const [activeName, setActiveName] = useState<string | null>(initialTemplate ?? null);
+  const [template, setTemplate] = useState<RoleTemplateFull | null>(null);
+  const [selectedVersionId, setSelectedVersionId] = useState<string>(DEFAULT_VERSION_ID);
+  const [content, setContent] = useState<string>("");
+  const [isEditing, setIsEditing] = useState(false);
+  const [editingDirty, setEditingDirty] = useState(false);
+  const [statusMsg, setStatusMsg] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  // Bumped after a save / delete / promote to refresh dependent data.
+  const [rev, setRev] = useState(0);
+
+  // Initial load: fetch summary list + auto-select first if none chosen
+  // (or if the URL points at a template name that doesn't exist).
+  useEffect(() => {
+    listRoleTemplates()
+      .then((r) => {
+        setSummaries(r.templates);
+        if (r.templates.length === 0) return;
+        const requestedExists = activeName && r.templates.some((s) => s.name === activeName);
+        if (!requestedExists) {
+          setActiveName(r.templates[0].name);
+        }
+      })
+      .catch((e) => setError(String(e)));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Whenever activeName or rev changes, fetch full template state.
+  useEffect(() => {
+    if (!activeName) return;
+    setError(null);
+    getRoleTemplate(activeName)
+      .then((t) => {
+        setTemplate(t);
+        // Default to viewing the currently-promoted version.
+        setSelectedVersionId(t.currentVersionId);
+        setContent(t.currentContent);
+        setIsEditing(false);
+        setEditingDirty(false);
+        // Update URL (without page reload) so the back button works.
+        if (window.location.hash !== `#/agents?template=${encodeURIComponent(t.name)}`) {
+          window.history.replaceState(null, "", `#/agents?template=${encodeURIComponent(t.name)}`);
+        }
+      })
+      .catch((e) => setError(String(e)));
+  }, [activeName, rev]);
+
+  // When the user picks a different version (without editing), fetch its content.
+  useEffect(() => {
+    if (!activeName || !template) return;
+    if (isEditing) return; // don't blow away in-flight edits
+    if (selectedVersionId === template.currentVersionId) {
+      setContent(template.currentContent);
+      return;
+    }
+    if (selectedVersionId === DEFAULT_VERSION_ID) {
+      setContent(template.defaultContent);
+      return;
+    }
+    getRoleTemplateVersionContent(activeName, selectedVersionId)
+      .then((r) => setContent(r.content))
+      .catch((e) => setError(String(e)));
+  }, [selectedVersionId, activeName, template, isEditing]);
+
+  // --- Action handlers ---
+
+  async function handleSaveAsNew() {
+    if (!activeName) return;
+    const label = window.prompt("Label for this version (e.g. 'stricter judge', 'opus run')");
+    if (!label || !label.trim()) return;
+    setBusy(true);
+    setStatusMsg(null);
+    try {
+      const v = await createRoleTemplateVersion(activeName, { label: label.trim(), content });
+      setStatusMsg(`✓ Saved as "${v.label}". (Not yet promoted — click Promote below.)`);
+      setIsEditing(false);
+      setEditingDirty(false);
+      setRev((n) => n + 1);
+      setSelectedVersionId(v.id);
+    } catch (e) {
+      setError(`Save failed: ${String(e)}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function handleSaveExisting() {
+    if (!activeName || !template) return;
+    if (selectedVersionId === DEFAULT_VERSION_ID) {
+      setError("Cannot edit the bundled default. Save as a new version instead.");
+      return;
+    }
+    setBusy(true);
+    setStatusMsg(null);
+    try {
+      await updateRoleTemplateVersion(activeName, selectedVersionId, { content });
+      setStatusMsg(
+        selectedVersionId === template.currentVersionId
+          ? "✓ Saved. (This version is currently promoted, so the change is live for the next agent run.)"
+          : "✓ Saved. (Promote this version to make it live.)",
+      );
+      setIsEditing(false);
+      setEditingDirty(false);
+      setRev((n) => n + 1);
+    } catch (e) {
+      setError(`Save failed: ${String(e)}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function handlePromote() {
+    if (!activeName) return;
+    setBusy(true);
+    setStatusMsg(null);
+    try {
+      const refreshed = await promoteRoleTemplateVersion(activeName, selectedVersionId);
+      setTemplate(refreshed);
+      setStatusMsg(
+        selectedVersionId === DEFAULT_VERSION_ID
+          ? "✓ Reverted to bundled default. The next agent run will use cf²'s default template."
+          : `✓ Promoted to production. The next agent run will use this version.`,
+      );
+      setRev((n) => n + 1);
+    } catch (e) {
+      setError(`Promote failed: ${String(e)}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function handleDelete() {
+    if (!activeName || !template) return;
+    if (selectedVersionId === DEFAULT_VERSION_ID) return; // can't happen UI-wise
+    const v = template.versions.find((x) => x.id === selectedVersionId);
+    if (!v) return;
+    if (!window.confirm(`Delete version "${v.label}"? This cannot be undone.`)) return;
+    setBusy(true);
+    setStatusMsg(null);
+    try {
+      await deleteRoleTemplateVersion(activeName, selectedVersionId);
+      setStatusMsg(`✓ Deleted "${v.label}".`);
+      setSelectedVersionId(DEFAULT_VERSION_ID);
+      setRev((n) => n + 1);
+    } catch (e) {
+      setError(`Delete failed: ${String(e)}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // --- Render ---
+
+  if (!activeName) {
+    return (
+      <div style={{ padding: "1rem" }}>
+        <h2>Agents</h2>
+        <p>Loading role templates…</p>
+        {error && <div className="dashboard__error">{error}</div>}
+      </div>
+    );
+  }
+
+  const promotedLabel = (() => {
+    if (!template) return "—";
+    if (template.currentVersionId === DEFAULT_VERSION_ID) return "Default (built-in)";
+    const v = template.versions.find((x) => x.id === template.currentVersionId);
+    return v ? v.label : template.currentVersionId;
+  })();
+
+  const selectionIsPromoted = template?.currentVersionId === selectedVersionId;
+  const selectionIsDefault = selectedVersionId === DEFAULT_VERSION_ID;
+
+  return (
+    <div style={{ padding: "1rem", maxWidth: "1100px", margin: "0 auto" }}>
+      <h2 style={{ marginTop: 0 }}>Agents</h2>
+      <p style={{ marginTop: 0, color: "var(--color-text-muted, #888)", fontSize: "var(--text-sm)" }}>
+        Manage the instruction templates each agent role reads. Each role has a built-in default
+        (always available) and any number of saved versions you create. <strong>Promote</strong> a
+        version to make cf² use it on the next agent run.
+      </p>
+
+      {/* Tab strip */}
+      <div
+        role="tablist"
+        style={{
+          display: "flex",
+          gap: "0.25rem",
+          borderBottom: "1px solid var(--color-border, #444)",
+          marginBottom: "1rem",
+          flexWrap: "wrap",
+        }}
+      >
+        {summaries.map((s) => {
+          const isActive = s.name === activeName;
+          return (
+            <button
+              key={s.name}
+              role="tab"
+              aria-selected={isActive}
+              onClick={() => {
+                if (editingDirty && !window.confirm("Discard unsaved changes?")) return;
+                setActiveName(s.name);
+              }}
+              style={{
+                padding: "0.5rem 0.9rem",
+                border: "none",
+                borderBottom: isActive ? "2px solid var(--color-accent, #4a8ee6)" : "2px solid transparent",
+                background: "transparent",
+                color: isActive ? "var(--color-text)" : "var(--color-text-muted, #888)",
+                cursor: "pointer",
+                fontWeight: isActive ? "bold" : "normal",
+                fontSize: "var(--text-sm)",
+              }}
+            >
+              {s.displayName}
+              {s.currentVersionId !== DEFAULT_VERSION_ID && (
+                <span
+                  title="Custom version is currently promoted"
+                  style={{ marginLeft: "0.4rem", color: "var(--color-accent, #4a8ee6)" }}
+                >
+                  •
+                </span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      {error && (
+        <div className="dashboard__error" style={{ marginBottom: "1rem" }}>
+          {error}
+        </div>
+      )}
+
+      {template && (
+        <>
+          {/* Heading + promoted indicator */}
+          <div
+            style={{
+              display: "flex",
+              alignItems: "baseline",
+              justifyContent: "space-between",
+              flexWrap: "wrap",
+              gap: "0.75rem",
+              marginBottom: "0.75rem",
+            }}
+          >
+            <h3 style={{ margin: 0 }}>{template.displayName}</h3>
+            <span style={{ fontSize: "var(--text-sm)", color: "var(--color-text-muted, #888)" }}>
+              In production:{" "}
+              <strong style={{ color: "var(--color-text)" }}>{promotedLabel}</strong>
+            </span>
+          </div>
+          <p style={{ marginTop: 0, fontSize: "var(--text-sm)", color: "var(--color-text-muted, #888)" }}>
+            Template file: <code>{template.name}</code>. Override path:{" "}
+            <code>~/.cfcf/templates/{template.name}</code>{" "}
+            <span style={{ opacity: 0.7 }}>
+              (written by cf² when you promote a non-default version; deleted when you revert).
+            </span>
+          </p>
+
+          {/* Version selector + actions */}
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "0.5rem",
+              flexWrap: "wrap",
+              marginBottom: "0.75rem",
+            }}
+          >
+            <label htmlFor="version-select" style={{ fontSize: "var(--text-sm)" }}>
+              Version:
+            </label>
+            <select
+              id="version-select"
+              value={selectedVersionId}
+              disabled={isEditing}
+              onChange={(e) => setSelectedVersionId(e.target.value)}
+              style={{ minWidth: "16rem" }}
+            >
+              <option value={DEFAULT_VERSION_ID}>
+                Default (built-in)
+                {template.currentVersionId === DEFAULT_VERSION_ID ? " — promoted" : ""}
+              </option>
+              {template.versions.map((v) => (
+                <option key={v.id} value={v.id}>
+                  {v.label} ({new Date(v.savedAt).toLocaleString()})
+                  {template.currentVersionId === v.id ? " — promoted" : ""}
+                </option>
+              ))}
+            </select>
+
+            {!isEditing ? (
+              <>
+                <button
+                  type="button"
+                  className="btn btn--small btn--secondary"
+                  disabled={busy}
+                  onClick={() => setIsEditing(true)}
+                >
+                  Edit
+                </button>
+                <button
+                  type="button"
+                  className="btn btn--small btn--primary"
+                  disabled={busy || selectionIsPromoted}
+                  onClick={handlePromote}
+                  title={selectionIsPromoted ? "Already promoted" : "Make cf² use this version on the next agent run"}
+                >
+                  {selectionIsDefault ? "Revert to default" : "Promote to production"}
+                </button>
+                {!selectionIsDefault && (
+                  <button
+                    type="button"
+                    className="btn btn--small btn--danger"
+                    disabled={busy}
+                    onClick={handleDelete}
+                    title="Delete this saved version (cannot be undone)"
+                  >
+                    Delete version
+                  </button>
+                )}
+              </>
+            ) : (
+              <>
+                {!selectionIsDefault && (
+                  <button
+                    type="button"
+                    className="btn btn--small btn--primary"
+                    disabled={busy || !editingDirty}
+                    onClick={handleSaveExisting}
+                  >
+                    Save changes
+                  </button>
+                )}
+                <button
+                  type="button"
+                  className="btn btn--small btn--primary"
+                  disabled={busy || !editingDirty}
+                  onClick={handleSaveAsNew}
+                  title="Save as a new version (with a label) — original stays untouched"
+                >
+                  Save as new version
+                </button>
+                <button
+                  type="button"
+                  className="btn btn--small btn--secondary"
+                  disabled={busy}
+                  onClick={() => {
+                    if (editingDirty && !window.confirm("Discard unsaved changes?")) return;
+                    setIsEditing(false);
+                    setEditingDirty(false);
+                    // Re-fetch original content for the selected version.
+                    setRev((n) => n + 1);
+                  }}
+                >
+                  Cancel
+                </button>
+              </>
+            )}
+          </div>
+
+          {statusMsg && (
+            <div
+              style={{
+                marginBottom: "0.75rem",
+                padding: "0.5rem 0.75rem",
+                background: "color-mix(in srgb, var(--color-success, #6ec06e) 12%, transparent)",
+                borderLeft: "3px solid var(--color-success, #6ec06e)",
+                fontSize: "var(--text-sm)",
+                borderRadius: "4px",
+              }}
+            >
+              {statusMsg}
+            </div>
+          )}
+
+          {/* Content editor */}
+          <textarea
+            value={content}
+            readOnly={!isEditing || selectionIsDefault}
+            onChange={(e) => {
+              setContent(e.target.value);
+              setEditingDirty(true);
+            }}
+            spellCheck={false}
+            style={{
+              width: "100%",
+              minHeight: "60vh",
+              fontFamily: "var(--font-mono, monospace)",
+              fontSize: "var(--text-sm)",
+              padding: "0.75rem",
+              border: "1px solid var(--color-border, #444)",
+              borderRadius: "4px",
+              background: isEditing && !selectionIsDefault
+                ? "var(--color-bg)"
+                : "var(--color-bg-muted, var(--color-bg))",
+              color: "var(--color-text)",
+              resize: "vertical",
+            }}
+          />
+          {isEditing && selectionIsDefault && (
+            <p
+              style={{
+                marginTop: "0.5rem",
+                fontSize: "var(--text-sm)",
+                color: "var(--color-text-muted, #888)",
+              }}
+            >
+              The bundled default is read-only. Use <strong>Save as new version</strong> to fork
+              it into an editable version.
+            </p>
+          )}
+
+          {/* Inline help below editor */}
+          <div
+            style={{
+              marginTop: "1rem",
+              padding: "0.75rem 1rem",
+              background: "color-mix(in srgb, var(--color-info, #4a8ee6) 8%, transparent)",
+              borderLeft: "3px solid var(--color-info, #4a8ee6)",
+              fontSize: "var(--text-sm)",
+              borderRadius: "4px",
+              lineHeight: 1.5,
+            }}
+            role="status"
+          >
+            <strong style={{ display: "block", marginBottom: "0.25rem" }}>How this works</strong>
+            <div style={{ marginBottom: "0.4rem" }}>
+              cf² ships a built-in default for every role. Saved versions live under{" "}
+              <code>~/.cfcf/templates-managed/{template.name}/</code>. When you promote a version,
+              its content is written to <code>~/.cfcf/templates/{template.name}</code> — the
+              existing user-global override path that <code>getTemplate()</code> already reads.
+            </div>
+            <div style={{ marginBottom: "0.4rem" }}>
+              <strong>"Promote to production"</strong> activates the selected version for the next
+              agent run. <strong>"Revert to default"</strong> deletes the override file so cf²
+              falls back to the bundled default.
+            </div>
+            <div>
+              Existing per-project overrides at <code>&lt;repo&gt;/cfcf-templates/{template.name}</code>{" "}
+              still take precedence over the user-global override — that's the power-user escape
+              hatch and isn't managed from this UI.
+            </div>
+          </div>
+
+          {/* Subtle skip-link to Settings (the user might be looking for the global config). */}
+          <p style={{ marginTop: "1.5rem", fontSize: "var(--text-sm)", color: "var(--color-text-muted, #888)" }}>
+            Looking for adapter / model settings?{" "}
+            <a
+              href="#/server"
+              onClick={(e) => {
+                e.preventDefault();
+                navigateTo("/server");
+              }}
+              style={{ color: "var(--color-info)" }}
+            >
+              Go to Settings
+            </a>
+            .
+          </p>
+        </>
+      )}
+    </div>
+  );
+}

From c2773ac97f8f7d9ed9e7ce581dd5fdfe99c5fdbd Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 18:45:11 -0700
Subject: [PATCH 2/8] fix(6.8): react to back/forward URL changes + show
 "unsaved changes" indicator
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two small follow-ups on top of 7c67f82:

1. The page only honoured `initialTemplate` on first mount; subsequent
   hash changes (browser back/forward through `?template=...`) were
   silently ignored. Added an effect that syncs activeName when the
   prop changes (and the requested template exists in the loaded
   summary list).

2. When in edit mode with local changes, the page heading now shows
   a yellow "• unsaved changes" indicator. Doesn't replace the
   button-disabled-state cue; just adds a visual signal so the user
   doesn't lose track of dirty state when scrolled away from the
   action buttons.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/web/src/pages/AgentTemplates.tsx | 30 ++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/packages/web/src/pages/AgentTemplates.tsx b/packages/web/src/pages/AgentTemplates.tsx
index 90b9999..2027843 100644
--- a/packages/web/src/pages/AgentTemplates.tsx
+++ b/packages/web/src/pages/AgentTemplates.tsx
@@ -69,6 +69,19 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // React to back/forward navigation: when the URL's `?template=` query
+  // changes, sync activeName so the page actually shows the new tab.
+  // Without this effect, only the first mount's initialTemplate was
+  // honoured; later hash changes were silently ignored.
+  useEffect(() => {
+    if (!initialTemplate) return;
+    if (initialTemplate === activeName) return;
+    if (summaries.some((s) => s.name === initialTemplate)) {
+      setActiveName(initialTemplate);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [initialTemplate, summaries]);
+
   // Whenever activeName or rev changes, fetch full template state.
   useEffect(() => {
     if (!activeName) return;
@@ -290,7 +303,22 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
               marginBottom: "0.75rem",
             }}
           >
-            <h3 style={{ margin: 0 }}>{template.displayName}</h3>
+            <h3 style={{ margin: 0 }}>
+              {template.displayName}
+              {isEditing && editingDirty && (
+                <span
+                  style={{
+                    marginLeft: "0.5rem",
+                    fontSize: "var(--text-sm)",
+                    color: "var(--color-warning, #c8861a)",
+                    fontWeight: "normal",
+                  }}
+                  title="You have unsaved changes"
+                >
+                  • unsaved changes
+                </span>
+              )}
+            </h3>
             <span style={{ fontSize: "var(--text-sm)", color: "var(--color-text-muted, #888)" }}>
               In production:{" "}
               <strong style={{ color: "var(--color-text)" }}>{promotedLabel}</strong>

From 008f5efbcd380ec53bbe64a5a519c52da10b4815 Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 18:46:08 -0700
Subject: [PATCH 3/8] docs(6.8): mention the new Agents tab in manual.md web-UI
 section

Brief mention of all five top-level web tabs in the Server / web UI
concept block. Adds discoverability for the new Agents tab without
expanding into a full guide section (the inline help on the page
itself covers the mechanics).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/guides/manual.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/guides/manual.md b/docs/guides/manual.md
index 0f09f4d..7daf55e 100644
--- a/docs/guides/manual.md
+++ b/docs/guides/manual.md
@@ -103,6 +103,13 @@ A grouping of workspaces that share knowledge. Clio is cfcf's persistent memory
 
 `cfcf server start` boots a local Hono server (default port `7233`) that hosts the HTTP API and a React web UI. Most cfcf CLI commands hit this server. The web UI is the easiest way to watch the loop in real time — `http://127.0.0.1:7233` after start.
 
+The web UI has five top-level tabs:
+- **Workspaces** — dashboard + per-workspace iteration history, log viewer, config tab.
+- **Memory** — Clio cross-workspace memory: search, browse, ingest, audit, projects.
+- **Agents** (item 6.8) — per-role instruction template editor with versioning + promote-to-production. Each role has a built-in default (always available) and any number of saved versions you create. Promote a version to make cf² use it on the next agent run; revert to default to fall back to the cf²-shipped template.
+- **Settings** — global config (per-role agent + model, ollama models, notifications, model registry).
+- **Help** — in-shell version of these guides.
+
 ### Pause actions
 
 When the loop pauses, you can resume with one of five structured actions (`continue` / `finish_loop` / `stop_loop_now` / `refine_plan` / `consult_reflection`) instead of a bare "Resume." Each action routes the harness — and any free-text feedback you provide — to a different destination. See [Workflow → User actions at pause points](workflow.md#user-actions-at-pause-points) for the full table and CLI examples.

From 99b30aea9d552cb35758ff0e436e0aa9cee5507f Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 18:56:17 -0700
Subject: [PATCH 4/8] fix(6.8): textarea is now editable in edit mode
 regardless of selected version
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous readOnly gate was `!isEditing || selectionIsDefault` —
so clicking Edit on the bundled-default tab left the textarea
read-only and the user couldn't type at all. The intent was "we
never overwrite the bundled-default file on disk" but the user still
needs to TYPE in the editor to draft a new version that gets saved
via "Save as new version". The save action is what's gated by
selection-is-default (no "Save changes" button on default — only
"Save as new version"); typing should always work in edit mode.

Updated the inline help below the editor to reframe accordingly:
"You're editing a copy of the bundled default. Click Save as new
version to fork your changes into a new version (the cf²-shipped
default itself stays untouched and remains available in the
dropdown)."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/web/src/pages/AgentTemplates.tsx | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/web/src/pages/AgentTemplates.tsx b/packages/web/src/pages/AgentTemplates.tsx
index 2027843..ee36a01 100644
--- a/packages/web/src/pages/AgentTemplates.tsx
+++ b/packages/web/src/pages/AgentTemplates.tsx
@@ -449,10 +449,15 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
             </div>
           )}
 
-          {/* Content editor */}
+          {/* Content editor.
+              readOnly is gated ONLY by `!isEditing` — the bundled default
+              "lives" on disk read-only (we never overwrite the embedded
+              constant), but the user still needs to TYPE in this editor
+              to draft a new version that gets saved via "Save as new
+              version". The save action is what's gated, not the typing. */}
           <textarea
             value={content}
-            readOnly={!isEditing || selectionIsDefault}
+            readOnly={!isEditing}
             onChange={(e) => {
               setContent(e.target.value);
               setEditingDirty(true);
@@ -466,7 +471,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
               padding: "0.75rem",
               border: "1px solid var(--color-border, #444)",
               borderRadius: "4px",
-              background: isEditing && !selectionIsDefault
+              background: isEditing
                 ? "var(--color-bg)"
                 : "var(--color-bg-muted, var(--color-bg))",
               color: "var(--color-text)",
@@ -481,8 +486,10 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
                 color: "var(--color-text-muted, #888)",
               }}
             >
-              The bundled default is read-only. Use <strong>Save as new version</strong> to fork
-              it into an editable version.
+              You're editing a copy of the bundled default. Click{" "}
+              <strong>Save as new version</strong> to fork your changes
+              into a new version (the cf²-shipped default itself stays
+              untouched and remains available in the dropdown).
             </p>
           )}
 

From 7a737d517a812ed3acfe660098f5d3963be7da32 Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 23:17:46 -0700
Subject: [PATCH 5/8] =?UTF-8?q?feat(6.8=20round=202):=20augmented=20type?=
 =?UTF-8?q?=20=E2=80=94=20auto-upgrade-friendly=20customisation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a second customisation mode alongside round-1's full-template
editing. Each saved version now has a type:

- type="full":      body REPLACES the bundled default at promote time.
                    Maximum flexibility (delete sections, restructure);
                    doesn't auto-pick-up cf² upgrades. UI shows a
                    "Forked from cf² vX.Y.Z" badge so the user knows
                    their version may be drifting.
- type="augmented": body is APPENDED to the live bundled default at
                    promote time AND every server boot. The bundled
                    default is read live (never duplicated on disk),
                    so when cf² ships a new default, the user's
                    extension automatically rides along on the new
                    version. THIS is the upgrade-friendly mode.

Composition lives in `composeForOverride(name, type, body)`:
- "full"      → body verbatim
- "augmented" → getEmbeddedTemplate(name) + AUGMENTATION_SEPARATOR + body

Boot-time auto-recompose: every cfcf server start runs
`refreshAugmentedOverrides()` which, for every managed template whose
promoted version is augmented, re-writes the override file IF the
on-disk content differs from the live composition. Cheap idempotent
pass, single log line on change. Full versions are explicitly NOT
touched (frozen by design — auto-merging would be wrong).

UI changes:
- New "Augment" button next to "Edit" in the action row. Augment
  always creates a new augmented version on top of the bundled
  default (regardless of which version is currently selected).
- Split editor view for augmented versions: bundled default
  rendered read-only at the top (~25vh, smaller for visual emphasis
  on the extension) + extension textarea below (~30vh) with a
  placeholder showing example custom directions. Editing toggles
  only the extension.
- Forked-from-cf²-vX.Y.Z hint below the selector for full versions.
- Version dropdown suffixes each entry with its type.
- "Creating new <type> version" indicator in the heading during
  create flows.

Also addresses the round-1 polish requests:
- Status messages moved above the version-selector row.
- Directional words removed from messages ("click Promote" not
  "click Promote below").
- Editor textarea is now editable on the bundled-default tab in
  edit mode (was read-only in round 1; the user couldn't type to
  draft a fork).

Back-compat: round-1 manifests without a `type` field are read as
type="full" automatically. Existing tests pass unchanged.

API extension: POST /api/role-templates/:name/versions accepts an
optional `type` field defaulting to "full". Invalid values return 400.

Tests:
- 41 unit tests in role-templates.test.ts (was 30) — augmented
  composition, boot refresh idempotency, full-versions-untouched,
  back-compat with round-1 manifests.
- 17 endpoint tests (was 15) — type validation in POST /versions.
- 845 total core+cli+web pass.

Pre-existing app.test.ts config-merge failure on main is unrelated.

Design doc + plan + CHANGELOG updated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  95 +++-
 docs/design/role-template-management.md       |  44 +-
 docs/plan.md                                  |   4 +-
 packages/core/src/role-templates.test.ts      | 162 ++++++
 packages/core/src/role-templates.ts           | 185 ++++++-
 .../server/src/routes/role-templates.test.ts  |  26 +
 packages/server/src/routes/role-templates.ts  |  11 +-
 packages/server/src/start.ts                  |  24 +
 packages/web/src/api.ts                       |   8 +-
 packages/web/src/pages/AgentTemplates.tsx     | 506 ++++++++++++++----
 10 files changed, 913 insertions(+), 152 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index beda073..3bc46b0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,9 @@ Changes are tracked via git tags. Each release tag corresponds to an entry here.
 
 ## [Unreleased]
 
-### Added — Item 6.8 (round 1): role-template management UI
+### Added — Item 6.8: role-template management UI (rounds 1 + 2)
+
+**Round 1: full-template editing**
 
 - **New top-level "Agents" tab** in the web UI (between Memory and
   Settings). One sub-tab per managed role template; each tab shows
@@ -24,34 +26,79 @@ Changes are tracked via git tags. Each release tag corresponds to an entry here.
   override path that `getTemplate()` already reads — no runtime
   changes to agent spawning. Reverting to default deletes the override
   file so cf² falls back to the embedded default. Editing a
-  promoted version refreshes the override file in-place so the
-  change is live for the next agent run.
-- **Managed templates (round 1)**: `cfcf-architect-instructions.md`,
-  `cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`,
-  `cfcf-reflection-instructions.md`, `process.md`. Per-project
-  overrides at `<repo>/cfcf-templates/<name>` continue to take
-  precedence over the user-global override (the power-user escape
-  hatch, unmanaged from the UI).
+  promoted version refreshes the override file in-place.
 - **HTTP API**: `GET /api/role-templates`, `GET .../:name`,
   `GET .../:name/versions/:versionId`, `POST .../:name/versions`,
   `PUT .../:name/versions/:versionId`,
   `DELETE .../:name/versions/:versionId`,
   `POST .../:name/promote`. Uniform `{ error: string }` envelope.
-- **New core module** `packages/core/src/role-templates.ts` with
-  list / get / save / update / delete / promote helpers, manifest
-  self-heal on corruption, orphan detection. `getEmbeddedTemplate(name)`
-  newly exported from `templates.ts` for read-only access to the
-  bundled default.
-- **Out of scope for round 1 (deferred follow-ups)**: dev-role
-  custom-directions block (Tier-2 from the original design — needs
-  the sentinel-merge insertion-point design first), Product Architect /
-  Help Assistant system-prompt management (their prompts are
-  programmatically assembled, not file-loaded), per-project override
-  management UI, diff viewer between versions.
-- **Tests**: 30 unit tests in `role-templates.test.ts`, 15 endpoint
-  tests in `routes/role-templates.test.ts`, 3 new route-parser tests
-  for `/agents` + `?template=`.
-- **Design doc**: [`docs/design/role-template-management.md`](docs/design/role-template-management.md).
+- **New core module** `packages/core/src/role-templates.ts` with full
+  CRUD, manifest self-heal on corruption, orphan detection.
+  `getEmbeddedTemplate(name)` newly exported from `templates.ts` for
+  read-only access to the bundled default.
+
+**Round 2: augmented-type versions (auto-upgrade-friendly)**
+
+- **`type: "full" | "augmented"`** added to every saved version.
+  Round-1 manifests (no `type`) are read as `"full"` for back-compat.
+  - **`type: "full"`** — body REPLACES the bundled default at
+    promote time. Maximum flexibility (delete sections, restructure);
+    no auto-upgrade. UI shows a `ℹ Forked from cf² vX.Y.Z` badge so
+    the user knows their version may have drifted from the latest
+    bundled default.
+  - **`type: "augmented"`** — body is APPENDED to the live bundled
+    default at promote time. The harness composes
+    `<bundled-default> + separator + <extension>` and writes that to
+    the override file. The bundled default is read live (never
+    duplicated on disk), so when cf² ships a new default, the user's
+    extension automatically rides along on the new version. **This is
+    upgrade-friendly by default.**
+- **Boot-time auto-recompose**: every server boot re-composes any
+  promoted augmented version (`refreshAugmentedOverrides()` in core,
+  called from `start.ts` after the orphan reaper). Cheap idempotent
+  pass — only writes when the on-disk override actually differs from
+  the live composition. Single log line on change:
+  `[server] Re-composed N augmented role-template override(s)…`.
+  Full versions are NOT touched (frozen by design).
+- **New "Augment" button** in the action row, next to "Edit". Augment
+  always creates a new augmented version on top of the bundled
+  default (regardless of which version is currently selected — keeps
+  the upgrade-friendly contract).
+- **Split editor view** for augmented versions: bundled default
+  rendered read-only at the top (~25vh, smaller so the extension
+  editor has visual prominence), extension textarea below (~30vh)
+  with a placeholder showing example custom directions. Editing
+  toggles only the extension to editable.
+- **Version dropdown** suffixes each entry with its type:
+  `My stricter judge — full (2026-05-09) — promoted`.
+- **API extension**: `POST /api/role-templates/:name/versions` body
+  now accepts an optional `type: "full" | "augmented"` (defaults to
+  `"full"`). Invalid values return 400.
+- **UI polish (also round 2)**: status messages moved above the
+  version-selector row (so "click Promote" reads naturally below the
+  buttons), directional words removed from messages, "creating new
+  X version" indicator added to the heading when appropriate.
+
+**Managed templates (rounds 1 + 2)**: `cfcf-architect-instructions.md`,
+`cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`,
+`cfcf-reflection-instructions.md`, `process.md`. Per-project overrides
+at `<repo>/cfcf-templates/<name>` continue to take precedence over the
+user-global override (the power-user escape hatch, unmanaged from the UI).
+
+**Out of scope (deferred)**: dev-role custom-directions block (dev's
+instructions are programmatically generated by `context-assembler`,
+not file-loaded — needs a different mechanism), Product Architect /
+Help Assistant system-prompt management, per-project override
+management UI, diff viewer between versions.
+
+**Tests**: 41 unit tests in `role-templates.test.ts` (every flow +
+manifest corruption recovery + cross-template isolation +
+back-compat with round-1 manifests + augmented composition + boot
+refresh), 17 endpoint tests in `routes/role-templates.test.ts`
+(including round-2 type validation), 3 route-parser tests for
+`/agents` + `?template=`.
+
+**Design doc**: [`docs/design/role-template-management.md`](docs/design/role-template-management.md).
 
 ### Added — Item 6.33: ollama-models refresh
 
diff --git a/docs/design/role-template-management.md b/docs/design/role-template-management.md
index e313fa6..880150e 100644
--- a/docs/design/role-template-management.md
+++ b/docs/design/role-template-management.md
@@ -1,5 +1,8 @@
 # Role-template management (item 6.8) — design
 
+> **Round 1 shipped 2026-05-08** (full-template editing).
+> **Round 2 shipped 2026-05-09** (augmented-type versions for upgrade-friendly customisation).
+
 ## Problem
 
 cf² ships a fixed set of agent-role instruction templates (`cfcf-architect-
@@ -54,10 +57,11 @@ the existing override mechanism, plus a web UI for editing.
     manifest.json     {
                         currentVersionId: "v_<id>" | "default",
                         versions: [
-                          { id, label, savedAt, contentHash }
+                          { id, label, savedAt, contentHash, type, cfcfVersion }
                         ]
                       }
-    v_<id>.md         each saved version's content
+    v_<id>.md         body — full template body for type="full",
+                      extension only for type="augmented"
   cfcf-judge-instructions.md/
     ...
 ```
@@ -66,6 +70,42 @@ the existing override mechanism, plus a web UI for editing.
 "promotes default", `~/.cfcf/templates/<name>` is **deleted** so
 `getTemplate` falls through to the embedded default.
 
+### Two version types (round 2)
+
+Each version has a `type` field:
+
+| `type` | What's stored on disk | What gets written to the override file at promote time | Auto-upgrade with cf²? |
+|---|---|---|---|
+| `"full"` | The complete template body | The body verbatim | ❌ Frozen — UI shows "Forked from cf² vX.Y.Z" |
+| `"augmented"` | Just the user's extension | `<bundled-default> + separator + <extension>` | ✅ Boot-time recompose picks up the new default |
+
+**Why both**: full edits give maximum flexibility (delete sections, restructure
+the prompt, etc.) but lose the auto-upgrade benefit. Augmented edits are
+upgrade-friendly but constrained to additions on top of cf²'s default. Each
+serves a real use case; the user picks per version.
+
+**Round-1 manifests** (saved before the type field existed) read back as
+`type: "full"` automatically — no migration needed.
+
+### Composition + boot refresh (augmented type)
+
+`composeForOverride(name, type, body)`:
+- `type === "full"`: pass-through.
+- `type === "augmented"`: `getEmbeddedTemplate(name) + AUGMENTATION_SEPARATOR + body`.
+
+`AUGMENTATION_SEPARATOR` is `\n\n---\n\n## Custom additions\n\n*(Managed via the
+cf² Agents tab — edit this section there, not in this file.)*\n\n` so the
+rendered template has a clean visual + textual demarcation.
+
+`refreshAugmentedOverrides()` runs at every server boot. For every managed
+template whose currently-promoted version is augmented, it re-composes against
+the live bundled default and writes to the override file **only if the on-disk
+content differs**. Cheap, idempotent, transparent to the user. This is the
+mechanism that makes cf² upgrades hands-off for augmented versions.
+
+Full versions are explicitly NOT touched by the boot refresh — the user
+fully owns those, and any auto-merge against a new default would be wrong.
+
 ### Templates managed
 
 MVP scope:
diff --git a/docs/plan.md b/docs/plan.md
index 1f430e1..6cfed9f 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -296,14 +296,14 @@ The tables below are the authoritative view of iteration progress. The **Notes**
 5. **Cerefox-parity Clio improvement** — *Shipped in v0.19.0:* FTS title boosting (**6.24**).
 6. **Adapter expansion driven by Anthropic harness policy** (**6.28**, surfaced 2026-05-07) — Anthropic's Jan→Apr 2026 clarification ([Cherny 2026-04-04](https://x.com/bcherny/status/1808066717213728812)) ties subscription OAuth tokens to interactive use only; cfcf's unattended iteration loop is the third-party-harness pattern the rule targets. Add ollama detection + three new adapters (`opencode` direct, `claude-code-ollama`, `opencode-ollama`) so unattended roles (dev / judge / reflection / documenter / auto-architect) can route to local ollama-served models via the `ollama launch <agent> --model <local-model>` exec wrapper (not via env-var proxy — explicit single command). Skills repository (**6.27**) also entered iter-6 as a research/design item on 2026-05-03.
 
-**Iter-6 active set after the cleanup**: 6.9, 6.11, 6.13, 6.18, 6.27, 6.28, 6.29, 6.30, 6.31, 6.32 (plus 6.19 partial: pre-warm-during-installer). 6.29 + 6.30 + 6.31 + 6.32 surfaced 2026-05-08 during 6.28's dogfood pass — kept in iter-6 to fix-while-debugging rather than defer. **Shipped in v0.18.0**: 6.20, 6.12, 6.26. **Shipped in v0.19.0**: 6.24. **Shipped 2026-05-02 on `feat/structured-pause-actions`**: 6.25. **Shipped in v0.20.0 (2026-05-08)**: 6.28. **Shipped in v0.21.0 (2026-05-08)**: 6.31, 6.30. **Shipped post-v0.21.0 (2026-05-08)**: 6.33, 6.8 (round 1). Items 6.1, 6.2, 6.10, 6.15 dropped to ⏸ (with rationales in their Notes columns); 6.8 marked ❌ but blocked on 6.11. See the status legend at the end of the section for what each icon means.
+**Iter-6 active set after the cleanup**: 6.9, 6.11, 6.13, 6.18, 6.27, 6.28, 6.29, 6.30, 6.31, 6.32 (plus 6.19 partial: pre-warm-during-installer). 6.29 + 6.30 + 6.31 + 6.32 surfaced 2026-05-08 during 6.28's dogfood pass — kept in iter-6 to fix-while-debugging rather than defer. **Shipped in v0.18.0**: 6.20, 6.12, 6.26. **Shipped in v0.19.0**: 6.24. **Shipped 2026-05-02 on `feat/structured-pause-actions`**: 6.25. **Shipped in v0.20.0 (2026-05-08)**: 6.28. **Shipped in v0.21.0 (2026-05-08)**: 6.31, 6.30. **Shipped post-v0.21.0**: 6.33 (2026-05-08), 6.8 round 1 (2026-05-08), 6.8 round 2 (2026-05-09). Items 6.1, 6.2, 6.10, 6.15 dropped to ⏸ (with rationales in their Notes columns); 6.8 marked ❌ but blocked on 6.11. See the status legend at the end of the section for what each icon means.
 
 | # | Status | Title | Notes |
 |---|--------|-------|-------|
 | 6.1 | ⏸ | Diff viewer per iteration | **Dropped from iter-6 2026-05-02** — superseded by F.13 (rich diff viewer with annotation, in Backlog). The annotation layer is the differentiating value over plain syntax-highlighted diff; building 6.1 first would require redoing the whole surface as part of F.13 later. CLI users today have `git diff main..cfcf/iteration-N`; web users have the History tab + iteration-logs/handoffs/reviews archives. If demand for a richer in-UI diff materialises, F.13 is the canonical record. |
 | 6.2 | ⏸ | `cfcf log <workspace-name>` CLI | **Dropped from iter-6 2026-05-02** — subsumed by 6.12 (CLI ↔ web parity audit). Today's web History tab + `cfcf-docs/iteration-history.md` cover read-on-demand needs; manufacturing a dedicated `cfcf log` command before knowing what gap it closes is feature-shaped. Let the parity audit drive scope: if it surfaces a real CLI deficiency, scope a command then. |
 | 6.3 | ⏸ | `cfcf push <project-name>` CLI | **Dropped 2026-04-20.** Intended to wrap `git push` with project awareness + notification hooks, but (a) post-SUCCESS push is already handled automatically by the iteration loop (`gitManager.push(project.repoPath)` at end of a successful loop), (b) manual pushes are trivially `git push` from inside the repo -- no cfcf state needed, (c) the project-awareness value disappeared when `ProjectConfig.repoUrl` was removed in v0.7.5 (it was the only cfcf-specific piece the command would have consulted). Retaining the row as ⏸ so the decision is preserved; the surrounding CLI ↔ web parity question is still covered by 6.12. |
-| 6.8 | 🔄 | Role-template management UI (full-template versioning + promote-to-production) | **Shipped 2026-05-08, post-v0.21.0 (round 1)**. Design doc: [`docs/design/role-template-management.md`](../design/role-template-management.md). **Decoupled from 6.11**: the 2026-05-02 "blocked on ADLC" framing assumed customisation needed to wait for the role-model to settle. Re-evaluated — the user's vision (concrete UI for editing + saving versions + promote-to-prod, with the cf²-shipped default always available) is independent of ADLC since it operates at the per-role-template granularity. Whatever role abstraction ADLC eventually settles on can layer on top of this without rework. **Shipped scope (round 1)**: (a) `packages/core/src/role-templates.ts` — versioning manager that hooks into the existing user-global override path (`~/.cfcf/templates/<name>`) without touching `getTemplate()`. Saved versions live under `~/.cfcf/templates-managed/<name>/{manifest.json, v_<id>.md}`. **Promoting a version** writes its content to the override file; **promoting "default"** deletes it (revert to bundled). Order-insensitive, self-healing manifest (corrupt JSON or missing version files fall back gracefully). Full CRUD: `listManagedTemplates`, `getManagedTemplate`, `getVersionContent`, `saveVersion`, `updateVersion` (refreshes override file when editing the promoted version), `deleteVersion` (auto-reverts if deleting the promoted), `promoteVersion`, `findOrphanedVersions`. New `getEmbeddedTemplate(name)` exported from `templates.ts` for read-only access to the bundled default. (b) HTTP API at `/api/role-templates/*` — list / get / per-version content / create / update / delete / promote, all backed by the core module with consistent `{ error: string }` response envelopes. (c) Web UI: new top-level **"Agents"** tab in the header (between Memory and Settings); `/agents` route with optional `?template=<name>` query for deep-linking; tab strip for the five managed templates; main panel shows version selector + editor (textarea, monospace, scrollable), promote/revert/delete actions, and an inline help block. The bundled default is always selectable but read-only — "Save as new version" forks it. (d) Tests: 30 unit tests (`role-templates.test.ts`) covering every flow + manifest-corruption recovery + cross-template isolation; 15 endpoint tests (`role-templates.test.ts` in server routes); 3 new route-parser tests for `/agents` + `?template=`. Total 808 core+cli pass + clean web build. **Managed templates (round 1)**: `cfcf-architect-instructions.md`, `cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`, `cfcf-reflection-instructions.md`, `process.md`. **Out of scope for round 1 (carried over)**: dev-role custom-directions block (the original Tier-2 idea — needs the sentinel-merge insertion-point design first; not blocking the rest of the UI), Product Architect / Help Assistant system-prompt management (their prompts are programmatically assembled rather than file-loaded), per-project (workspace-local) override management UI (the file-based path stays the power-user escape hatch), diff viewer between versions, search-within-content (browser Cmd-F suffices on a textarea). **Original two-tier design (preserved for reference, partly applies to deferred dev-role work)** that avoids fork-vs-upgrade pain: *(Tier 1, default for everyone)* cfcf ships current templates and upgrades them in place -- user gets new defaults on `cfcf` upgrade, no migration step. *(Tier 2, opt-in additional-directions block)* each role template gains a documented insertion point; if the user provides `cfcf-templates/custom-directions/<role>.md` (project-local) or `<CFCF_CONFIG_DIR>/templates/custom-directions/<role>.md` (user-global), cfcf splices it verbatim into the generated instruction file at that point, **in addition to** the default template. The block is user-owned -- cfcf never touches it on upgrade, so migration pain goes away because the defaults don't fork. Examples: "Documenter: use our internal report format, include X section"; "Dev: every commit message must reference a JIRA ticket ID"; "Architect: always include an accessibility review section". *(Tier 3, power-user fallback)* the existing full-template override path (`cfcf-templates/<name>.md`) remains available, documented as "you own the upgrade path for any template you fork". The shipped UI implements Tier 3 with versioning + promote-to-prod ergonomics on top; Tier 2 (custom-directions block for dev role) deferred to a follow-up branch. |
+| 6.8 | 🔄 | Role-template management UI (rounds 1 + 2: full-template versioning + augmented type for upgrade-friendly customisation) | **Round 1 shipped 2026-05-08, round 2 shipped 2026-05-09, both post-v0.21.0**. **Round 2 highlights (item 6.8 round 2)**: added a `type: "full" \| "augmented"` field to every saved version. **`type="full"`** behaves like round 1 — body REPLACES the bundled default; max flexibility; doesn't auto-pick-up cf² upgrades; UI shows a "Forked from cf² vX.Y.Z" badge so the user knows their version may be drifting. **`type="augmented"`** is the upgrade-friendly mode: body is APPENDED to the live bundled default at promote time + boot time, so when cf² ships a new bundled default, the user's extension automatically rides along on the new version. Composition is `<bundled-default> + AUGMENTATION_SEPARATOR + <extension>`; the bundled default is read live (never duplicated on disk). **Boot-time recompose** (`refreshAugmentedOverrides()` in core, called from `start.ts`) rewrites the override file when on-disk content differs from the live composition — cheap, idempotent, transparent. Full versions are explicitly NOT touched by boot refresh (frozen by design). New "Augment" button in the action row creates augmented versions; new split editor view renders the bundled default read-only on top (~25vh, smaller for visual emphasis on the extension below) + extension textarea (~30vh) with placeholder example directions. Version dropdown suffixes each entry with its type. Round-1 manifests without a `type` field read back as `"full"` for back-compat — no migration needed. **Round 1 highlights (preserved)**: Design doc: [`docs/design/role-template-management.md`](../design/role-template-management.md). **Decoupled from 6.11**: the 2026-05-02 "blocked on ADLC" framing assumed customisation needed to wait for the role-model to settle. Re-evaluated — the user's vision (concrete UI for editing + saving versions + promote-to-prod, with the cf²-shipped default always available) is independent of ADLC since it operates at the per-role-template granularity. Whatever role abstraction ADLC eventually settles on can layer on top of this without rework. **Shipped scope (round 1)**: Design doc: [`docs/design/role-template-management.md`](../design/role-template-management.md). **Decoupled from 6.11**: the 2026-05-02 "blocked on ADLC" framing assumed customisation needed to wait for the role-model to settle. Re-evaluated — the user's vision (concrete UI for editing + saving versions + promote-to-prod, with the cf²-shipped default always available) is independent of ADLC since it operates at the per-role-template granularity. Whatever role abstraction ADLC eventually settles on can layer on top of this without rework. **Shipped scope (round 1)**: (a) `packages/core/src/role-templates.ts` — versioning manager that hooks into the existing user-global override path (`~/.cfcf/templates/<name>`) without touching `getTemplate()`. Saved versions live under `~/.cfcf/templates-managed/<name>/{manifest.json, v_<id>.md}`. **Promoting a version** writes its content to the override file; **promoting "default"** deletes it (revert to bundled). Order-insensitive, self-healing manifest (corrupt JSON or missing version files fall back gracefully). Full CRUD: `listManagedTemplates`, `getManagedTemplate`, `getVersionContent`, `saveVersion`, `updateVersion` (refreshes override file when editing the promoted version), `deleteVersion` (auto-reverts if deleting the promoted), `promoteVersion`, `findOrphanedVersions`. New `getEmbeddedTemplate(name)` exported from `templates.ts` for read-only access to the bundled default. (b) HTTP API at `/api/role-templates/*` — list / get / per-version content / create / update / delete / promote, all backed by the core module with consistent `{ error: string }` response envelopes. (c) Web UI: new top-level **"Agents"** tab in the header (between Memory and Settings); `/agents` route with optional `?template=<name>` query for deep-linking; tab strip for the five managed templates; main panel shows version selector + editor (textarea, monospace, scrollable), promote/revert/delete actions, and an inline help block. The bundled default is always selectable but read-only — "Save as new version" forks it. (d) Tests: 30 unit tests (`role-templates.test.ts`) covering every flow + manifest-corruption recovery + cross-template isolation; 15 endpoint tests (`role-templates.test.ts` in server routes); 3 new route-parser tests for `/agents` + `?template=`. Total 845 core+cli+web pass + clean web build (round 2: 41 unit + 17 endpoint + 3 route-parser tests, vs round 1's 30 + 15 + 3). **Managed templates (rounds 1 + 2)**: `cfcf-architect-instructions.md`, `cfcf-judge-instructions.md`, `cfcf-documenter-instructions.md`, `cfcf-reflection-instructions.md`, `process.md`. **Out of scope (carried over)**: dev-role custom-directions block (dev's instructions are programmatically generated by `context-assembler.generateInstructionContent()` not loaded as a single template — the augmented type doesn't apply directly; needs a different sentinel-merge insertion-point design), Product Architect / Help Assistant system-prompt management (their prompts are programmatically assembled rather than file-loaded), per-project (workspace-local) override management UI (the file-based path stays the power-user escape hatch), diff viewer between versions, search-within-content (browser Cmd-F suffices on a textarea). **Original two-tier design (preserved for reference, partly applies to deferred dev-role work)** that avoids fork-vs-upgrade pain: *(Tier 1, default for everyone)* cfcf ships current templates and upgrades them in place -- user gets new defaults on `cfcf` upgrade, no migration step. *(Tier 2, opt-in additional-directions block)* each role template gains a documented insertion point; if the user provides `cfcf-templates/custom-directions/<role>.md` (project-local) or `<CFCF_CONFIG_DIR>/templates/custom-directions/<role>.md` (user-global), cfcf splices it verbatim into the generated instruction file at that point, **in addition to** the default template. The block is user-owned -- cfcf never touches it on upgrade, so migration pain goes away because the defaults don't fork. Examples: "Documenter: use our internal report format, include X section"; "Dev: every commit message must reference a JIRA ticket ID"; "Architect: always include an accessibility review section". *(Tier 3, power-user fallback)* the existing full-template override path (`cfcf-templates/<name>.md`) remains available, documented as "you own the upgrade path for any template you fork". The shipped UI implements Tier 3 with versioning + promote-to-prod ergonomics on top; Tier 2 (custom-directions block for dev role) deferred to a follow-up branch. |
 | 6.9 | ❌ | Rationalise Clio usage across agent roles | **Reframed 2026-05-02** from "Optional Cerefox memory backend" — Clio shipped in 5.7 (local SQLite-backed memory layer with FTS + hybrid search). The new scope: **standardise how each agent role queries and writes Clio**, document the canonical patterns, ensure roles use semantic/hybrid search rather than grepping repo files. The main Clio benefits are (a) cross-workspace persistent memory and (b) efficient retrieval (semantic + FTS) — much more efficient than `grep` over `*.md` in the repo, especially as cfcf-docs and decision-log grow. **Scope**: audit each role's instructions template (dev / judge / architect / reflection / documenter / PA / HA) for current Clio guidance; rewrite to a consistent "search Clio for X before doing Y" pattern; document agent-side Clio patterns in `docs/research/`; possibly extract a shared "Clio cheat sheet" that gets injected into every role's prompt. **Out of scope**: a remote `CerefoxRemote` backend adapter (the original 6.9 item) — that stays optional/future, the `MemoryBackend` interface already exists for it. **Clio Project namespace convention (surfaced 2026-05-02 during 6.12 dogfooding)**: a few projects today have de-facto special meaning — `default` is the catch-all global bucket; `cfcf-memory-pa` is owned by the Product Architect; `cfcf-memory-global` is the cross-workspace shared bucket. Today every web picker (workspace creation, "Change Clio Project", Memory page sidebar) lists ALL projects unfiltered, including these system-managed ones. 6.9 should formalise the convention: pick a naming prefix (e.g. `cfcf-memory-*`) or an explicit registry of "system projects", document who owns each, and decide which projects are user-pickable vs. system-only at the picker site. Once the convention lands, web pickers add a one-line filter; until then, the unfiltered list is fine but users may pick a system project by mistake. **Read-audit gap (surfaced 2026-05-02 during 6.18 round-3 actor-convention work)**: cfcf's audit log captures mutations only (`ingest`, `update`, `delete`, `restore`, `edit-metadata`). Cerefox additionally maintains a `usage_log` for read operations (each `search` / `docs get` records the requestor + query). 6.9 should evaluate whether cfcf needs read-audit parity — likely yes for the same actor-convention reason (so analytics can answer "which roles search Clio most often?", "which queries return zero hits?"). New event type(s) + a new SQL table or a column on the audit table; CLI surface for query (`cfcf clio audit --reads`); also a privacy review (does logging every search query risk capturing sensitive prompt-leakage if the agent quotes problem.md content into a query?). |
 | 6.10 | ⏸ | Sandbox / guardrails research + POC | **Dropped from iter-6 2026-05-02** — moved to Backlog F.5 as durable record. Threat model that would justify sandbox engineering (untrusted Problem Pack from a third party? cfcf-as-a-service?) doesn't exist today: users run cfcf on their own machines under their own account; iteration isolation is already provided by git branches; Codex `--dangerously-skip-permissions` + Claude Code's matched mode give the unattended-loop permission profile cfcf needs. If/when a multi-tenant scenario emerges, macOS `sandbox-exec` / Linux `nsjail` / Anthropic's sandbox concept are the right primitives — research with concrete use cases at that point. F.5 in the Backlog carries the trigger note. |
 | 6.11 | ❌ | Generalisation research → Agent Development Life Cycle (ADLC) extension | **Iter-6 headline; research-only scope locked 2026-05-02.** Extend cfcf to non-coding iterative work, framed as researching a **parallel/configurable workflow alongside the current SDLC**, hardwired into the harness rather than bolted on. End game: refactor cfcf into a more dynamic, configurable harness where the SDLC is one of N built-in workflows (ADLC, content production, research projects, data analysis, strategy planning). **Research questions**: Is the Problem Pack shape general enough across workflow types? Does the dev / judge / architect / reflection / documenter role split map to non-coding workers, or do roles need to be workflow-specific too? Does the signal schema need workflow-specific shapes (no tests to pass for content production)? What's the "success criteria" surrogate when the artifact is a report rather than passing tests? **Output (iter-6)**: research doc at `docs/research/adlc-extension-design.md` enumerating options, decision points, and a concrete proposal. **Implementation deferred to iter-7+** — committing to a first-implementation stretch in iter-6 would commit to a deadline before the design is settled; if the research lands fast we'll re-evaluate at that point. Likely overlaps with the Cerefox Agent v0.1 vision. Pairs with 6.13 (scheduled execution) for the periodic-content use case. **6.8 (custom directions per role) is blocked on this** — pick up 6.8 once 6.11 settles the role model. |
diff --git a/packages/core/src/role-templates.test.ts b/packages/core/src/role-templates.test.ts
index a7e8192..47e84fe 100644
--- a/packages/core/src/role-templates.test.ts
+++ b/packages/core/src/role-templates.test.ts
@@ -24,7 +24,9 @@ import {
   updateVersion,
   deleteVersion,
   promoteVersion,
+  refreshAugmentedOverrides,
   findOrphanedVersions,
+  AUGMENTATION_SEPARATOR,
   DEFAULT_VERSION_ID,
 } from "./role-templates.js";
 import { getTemplate, getEmbeddedTemplate } from "./templates.js";
@@ -105,6 +107,9 @@ describe("saveVersion", () => {
     expect(v.label).toBe("stricter judge");
     expect(v.savedAt).toMatch(/T/); // ISO
     expect(v.contentHash.length).toBe(12);
+    // Round 2: type defaults to "full" + cfcfVersion stamped
+    expect(v.type).toBe("full");
+    expect(typeof v.cfcfVersion).toBe("string");
 
     const managed = await getManagedTemplate(JUDGE);
     expect(managed.versions).toHaveLength(1);
@@ -113,6 +118,24 @@ describe("saveVersion", () => {
     expect(managed.currentVersionId).toBe("default");
   });
 
+  test("creates an augmented version when type='augmented' is passed", async () => {
+    const v = await saveVersion(JUDGE, {
+      label: "with project hints",
+      content: "Always reference Linear ticket IDs in summaries.",
+      type: "augmented",
+    });
+    expect(v.type).toBe("augmented");
+    // The body file holds ONLY the extension (no bundled default).
+    const stored = await getVersionContent(JUDGE, v.id);
+    expect(stored).toBe("Always reference Linear ticket IDs in summaries.");
+  });
+
+  test("rejects invalid type values", async () => {
+    expect(
+      saveVersion(JUDGE, { label: "x", content: "y", type: "patch" as never }),
+    ).rejects.toThrow();
+  });
+
   test("rejects empty labels", async () => {
     expect(saveVersion(JUDGE, { label: "  ", content: "x" })).rejects.toThrow();
   });
@@ -302,3 +325,142 @@ describe("self-heal: stale promoted-version pointer", () => {
     expect(managed.currentContent).toBe(getEmbeddedTemplate(JUDGE));
   });
 });
+
+describe("augmented type — round 2 composition + boot refresh", () => {
+  test("promoting an augmented version writes <default> + separator + <extension> to the override", async () => {
+    const ext = "Project-specific: cite Linear ticket in every summary.";
+    const v = await saveVersion(JUDGE, { label: "linear-augmented", content: ext, type: "augmented" });
+    await promoteVersion(JUDGE, v.id);
+
+    const overridePath = join(tmpDir, "templates", JUDGE);
+    expect(existsSync(overridePath)).toBe(true);
+    const onDisk = readFileSync(overridePath, "utf-8");
+    const expected = getEmbeddedTemplate(JUDGE) + AUGMENTATION_SEPARATOR + ext;
+    expect(onDisk).toBe(expected);
+
+    // getTemplate() returns the composed version too.
+    const resolved = await getTemplate(JUDGE);
+    expect(resolved).toBe(expected);
+  });
+
+  test("editing the promoted augmented version recomposes against the live default", async () => {
+    const v = await saveVersion(JUDGE, {
+      label: "v1",
+      content: "ext-v1",
+      type: "augmented",
+    });
+    await promoteVersion(JUDGE, v.id);
+
+    await updateVersion(JUDGE, v.id, { content: "ext-v2" });
+    const onDisk = readFileSync(join(tmpDir, "templates", JUDGE), "utf-8");
+    expect(onDisk).toBe(getEmbeddedTemplate(JUDGE) + AUGMENTATION_SEPARATOR + "ext-v2");
+  });
+
+  test("promoting 'default' over an augmented version deletes the override file", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "ext", type: "augmented" });
+    await promoteVersion(JUDGE, v.id);
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(true);
+
+    await promoteVersion(JUDGE, DEFAULT_VERSION_ID);
+    expect(existsSync(join(tmpDir, "templates", JUDGE))).toBe(false);
+  });
+
+  test("getVersionContent returns the EXTENSION only for augmented versions (not the composed text)", async () => {
+    const v = await saveVersion(JUDGE, {
+      label: "x",
+      content: "extension only",
+      type: "augmented",
+    });
+    const content = await getVersionContent(JUDGE, v.id);
+    expect(content).toBe("extension only");
+  });
+});
+
+describe("refreshAugmentedOverrides (boot-time refresh)", () => {
+  test("rewrites a stale augmented override (simulating a cf² upgrade where the default changed)", async () => {
+    const ext = "my custom directions";
+    const v = await saveVersion(JUDGE, { label: "x", content: ext, type: "augmented" });
+    await promoteVersion(JUDGE, v.id);
+    // Simulate cf² upgrade: the override on disk reflects the OLD
+    // composed content. We mimic that by clobbering the override with
+    // a stale composition (the bundled default has "drifted" to a new
+    // value the user hasn't seen).
+    const stalePath = join(tmpDir, "templates", JUDGE);
+    writeFileSync(stalePath, "OLD DEFAULT" + AUGMENTATION_SEPARATOR + ext, "utf-8");
+
+    const result = await refreshAugmentedOverrides();
+    expect(result.refreshed).toContain(JUDGE);
+
+    const fresh = readFileSync(stalePath, "utf-8");
+    expect(fresh).toBe(getEmbeddedTemplate(JUDGE) + AUGMENTATION_SEPARATOR + ext);
+  });
+
+  test("no-op when the on-disk content already matches the composed text (idempotent)", async () => {
+    const v = await saveVersion(JUDGE, {
+      label: "x",
+      content: "ext",
+      type: "augmented",
+    });
+    await promoteVersion(JUDGE, v.id);
+
+    const result = await refreshAugmentedOverrides();
+    // Just promoted → already up to date → not refreshed again.
+    expect(result.refreshed).not.toContain(JUDGE);
+  });
+
+  test("does NOT touch full versions (they're frozen by design)", async () => {
+    const v = await saveVersion(JUDGE, { label: "x", content: "FULL CUSTOM", type: "full" });
+    await promoteVersion(JUDGE, v.id);
+    // Even if the bundled default changes, full versions keep their content.
+    // Simulate a stale override (user's hand-edited the file, etc.).
+    const overridePath = join(tmpDir, "templates", JUDGE);
+    writeFileSync(overridePath, "FULL CUSTOM (out of sync but user owns this)", "utf-8");
+
+    const result = await refreshAugmentedOverrides();
+    expect(result.refreshed).not.toContain(JUDGE);
+    // Override file untouched.
+    expect(readFileSync(overridePath, "utf-8")).toBe(
+      "FULL CUSTOM (out of sync but user owns this)",
+    );
+  });
+
+  test("does NOT touch templates whose currentVersionId is 'default'", async () => {
+    // No version saved + promoted → boot refresh is a no-op.
+    const result = await refreshAugmentedOverrides();
+    expect(result.refreshed).toEqual([]);
+    expect(result.errors).toEqual([]);
+  });
+});
+
+describe("back-compat: round-1 manifests without `type`", () => {
+  test("a manifest written by round-1 code (no type field) loads as type='full'", async () => {
+    // Manually scaffold a round-1-shaped manifest.
+    const dir = join(tmpDir, "templates-managed", JUDGE);
+    mkdirSync(dir, { recursive: true });
+    const v_id = "v_legacy";
+    writeFileSync(join(dir, `${v_id}.md`), "legacy body", "utf-8");
+    writeFileSync(
+      join(dir, "manifest.json"),
+      JSON.stringify({
+        currentVersionId: "default",
+        versions: [
+          {
+            id: v_id,
+            label: "legacy",
+            savedAt: "2026-01-01T00:00:00Z",
+            contentHash: "abc",
+            // no type, no cfcfVersion
+          },
+        ],
+      }),
+      "utf-8",
+    );
+
+    const managed = await getManagedTemplate(JUDGE);
+    expect(managed.versions[0].type).toBe("full");
+    // Promoting a back-compat full version keeps current behaviour.
+    await promoteVersion(JUDGE, v_id);
+    const onDisk = readFileSync(join(tmpDir, "templates", JUDGE), "utf-8");
+    expect(onDisk).toBe("legacy body");
+  });
+});
diff --git a/packages/core/src/role-templates.ts b/packages/core/src/role-templates.ts
index e7a8d13..9656bea 100644
--- a/packages/core/src/role-templates.ts
+++ b/packages/core/src/role-templates.ts
@@ -5,21 +5,51 @@
  *
  * **Design** (full doc: `docs/design/role-template-management.md`):
  *
+ * Two version types (item 6.8 round 2):
+ *
+ *   1. **`type: "full"`** — the user's body REPLACES the bundled default
+ *      entirely. Maximum flexibility (delete sections, restructure,
+ *      anything). Caveat: when cf² ships a new bundled default, the user
+ *      doesn't pick it up automatically — their version is frozen until
+ *      they manually re-fork. Surfaced in the UI as a "forked from cf²
+ *      vX.Y.Z" badge so the user knows their version may be drifting.
+ *
+ *   2. **`type: "augmented"`** — the user's body is APPENDED to the
+ *      bundled default with a separator. The bundled default is always
+ *      read live (never duplicated on disk), so when cf² upgrades the
+ *      default, the user's extension automatically rides along on the
+ *      new version — no migration. The harness recomposes
+ *      `<bundled-default> + <separator> + <extension>` at promote time
+ *      AND at every server boot (cheap, idempotent — only writes if the
+ *      composed content actually differs from what's on disk). Less
+ *      flexibility than full (you can't delete sections from the
+ *      default), but upgrade-friendly by default.
+ *
  * - The bundled default for each role is read from the EMBEDDED registry
  *   in `templates.ts` (already shipped). Read-only, never deletable.
  * - User-saved versions live under `~/.cfcf/templates-managed/<name>/`:
  *
  *   ```
  *   ~/.cfcf/templates-managed/cfcf-judge-instructions.md/
- *     manifest.json   { currentVersionId, versions: [{id, label, savedAt, contentHash}] }
- *     v_<id>.md       content for each saved version
+ *     manifest.json   {
+ *                       currentVersionId,
+ *                       versions: [{ id, label, savedAt, contentHash, type, cfcfVersion }]
+ *                     }
+ *     v_<id>.md       content body — full template body for type="full",
+ *                     extension only for type="augmented"
  *   ```
  *
- * - When the user **promotes a version to production**, the manager writes
- *   that version's content to `~/.cfcf/templates/<name>` (the existing
- *   override path that `getTemplate()` already reads). No runtime change.
+ * - When the user **promotes a version to production**, the manager
+ *   writes a content file to `~/.cfcf/templates/<name>` (the existing
+ *   override path that `getTemplate()` already reads). No runtime change
+ *   to the agent-spawn pipeline. For `type="augmented"`, the manager
+ *   composes `<bundled-default> + <separator> + <extension>` before
+ *   writing.
  * - **Promoting "default"** deletes that override file so `getTemplate()`
  *   falls through to the bundled default.
+ * - **Boot-time refresh** (`refreshAugmentedOverrides`) re-composes any
+ *   promoted augmented version on every server boot, picking up cf²
+ *   upgrades to the bundled default transparently.
  *
  * **Managed templates (MVP)**: the four iteration-role instruction
  * templates + the workspace process template. Dev's instructions are
@@ -31,17 +61,50 @@ import { readFile, writeFile, mkdir, readdir, rm } from "fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "path";
 import { createHash, randomBytes } from "crypto";
-import { getConfigDir } from "./constants.js";
+import { getConfigDir, VERSION } from "./constants.js";
 import { listTemplates, getEmbeddedTemplate } from "./templates.js";
 
+// --- Composition constants ---
+
+/**
+ * Separator inserted between the bundled default and the user extension
+ * when composing a promoted augmented version. The h2 heading is meant
+ * to be unambiguous in the rendered template (any agent reading the
+ * file will see it cleanly), and the parenthetical points editors at
+ * the right surface.
+ */
+export const AUGMENTATION_SEPARATOR =
+  "\n\n---\n\n## Custom additions\n\n*(Managed via the cf² Agents tab — edit this section there, not in this file.)*\n\n";
+
 // --- Public types ---
 
+export type TemplateVersionType = "full" | "augmented";
+
 export interface TemplateVersion {
   id: string;
   label: string;
   savedAt: string;
   /** Short prefix of sha256(content). Display-only. */
   contentHash: string;
+  /**
+   * Version type (item 6.8 round 2).
+   * - `"full"`: body replaces the bundled default entirely.
+   * - `"augmented"`: body is appended to the bundled default at promote time.
+   *
+   * Defaults to `"full"` for back-compat with versions saved before
+   * round 2 (manifests written by the round-1 code don't have this
+   * field — we backfill on read).
+   */
+  type: TemplateVersionType;
+  /**
+   * The cf² version that was running when this version was saved.
+   * Used by the UI's "forked from cf² vX.Y.Z" badge on full versions
+   * so the user knows their version may have drifted from the current
+   * bundled default. Augmented versions don't drift (they always
+   * compose against the live default), so the badge is only shown for
+   * `type="full"`. Optional for back-compat.
+   */
+  cfcfVersion?: string;
 }
 
 export interface ManagedTemplate {
@@ -142,6 +205,11 @@ async function readManifest(name: string): Promise<Manifest> {
     ) {
       return emptyManifest();
     }
+    // Back-compat: round 1 manifests don't have a `type` field on each
+    // version. Fill it in as "full" since that was the only mode shipped.
+    for (const v of parsed.versions) {
+      if (!v.type) v.type = "full";
+    }
     return parsed;
   } catch {
     return emptyManifest();
@@ -279,16 +347,26 @@ export async function getVersionContent(name: string, versionId: string): Promis
 
 /**
  * Save a new user version.
+ *
+ * `type` (item 6.8 round 2):
+ * - `"full"` (default): body replaces the bundled default at promote
+ *   time. Maximum flexibility; doesn't auto-pick-up cf² upgrades.
+ * - `"augmented"`: body is appended to the live bundled default at
+ *   promote/recompose time. Less flexibility; auto-picks-up upgrades.
  */
 export async function saveVersion(
   name: string,
-  opts: { label: string; content: string },
+  opts: { label: string; content: string; type?: TemplateVersionType },
 ): Promise<TemplateVersion> {
   assertManagedTemplate(name);
   const label = opts.label.trim();
   if (!label) throw new Error("Version label cannot be empty");
   const content = opts.content;
   if (typeof content !== "string") throw new Error("Version content must be a string");
+  const type: TemplateVersionType = opts.type ?? "full";
+  if (type !== "full" && type !== "augmented") {
+    throw new Error(`Invalid version type: ${type}. Must be "full" or "augmented".`);
+  }
 
   await mkdir(templateDir(name), { recursive: true });
   const id = generateVersionId();
@@ -299,6 +377,8 @@ export async function saveVersion(
     label,
     savedAt: new Date().toISOString(),
     contentHash: hashContent(content),
+    type,
+    cfcfVersion: VERSION,
   };
 
   const manifest = await readManifest(name);
@@ -340,9 +420,11 @@ export async function updateVersion(
     nextHash = hashContent(opts.content);
     // If the user edits the currently-promoted version, refresh the
     // override file too so runtime picks up the change without a
-    // separate re-promote step.
+    // separate re-promote step. For augmented versions, recompose
+    // against the live bundled default.
     if (manifest.currentVersionId === versionId) {
-      await writeOverrideFile(name, opts.content);
+      const composed = composeForOverride(name, existing.type, opts.content);
+      await writeOverrideFile(name, composed);
     }
   }
 
@@ -396,6 +478,10 @@ export async function deleteVersion(name: string, versionId: string): Promise<vo
  * Promote a version (or "default") to production. Writes the override
  * file (or deletes it for "default") so `getTemplate()` picks up the
  * change for every subsequent agent spawn.
+ *
+ * For `type="augmented"` versions, the override file is the composed
+ * `<bundled-default> + separator + <extension>`. For `type="full"`
+ * versions, the override file is the body verbatim.
  */
 export async function promoteVersion(name: string, versionId: string): Promise<void> {
   assertManagedTemplate(name);
@@ -407,11 +493,13 @@ export async function promoteVersion(name: string, versionId: string): Promise<v
     await deleteOverrideFile(name);
   } else {
     const manifest = await readManifest(name);
-    if (!manifest.versions.some((v) => v.id === versionId)) {
+    const version = manifest.versions.find((v) => v.id === versionId);
+    if (!version) {
       throw new Error(`Version not found: ${versionId}`);
     }
-    const content = await readFile(versionFilePath(name, versionId), "utf-8");
-    await writeOverrideFile(name, content);
+    const body = await readFile(versionFilePath(name, versionId), "utf-8");
+    const composed = composeForOverride(name, version.type, body);
+    await writeOverrideFile(name, composed);
   }
 
   const manifest = await readManifest(name);
@@ -419,6 +507,79 @@ export async function promoteVersion(name: string, versionId: string): Promise<v
   await writeManifest(name, manifest);
 }
 
+/**
+ * Compose the content that gets written to the override file for a
+ * given version type.
+ *
+ * - `type === "full"`: pass-through. The user's body IS the override.
+ * - `type === "augmented"`: `<bundled-default> + separator + <body>`.
+ *   The bundled default is read live, so cf² upgrades automatically
+ *   propagate the next time this function runs (promote OR boot
+ *   refresh — see `refreshAugmentedOverrides`).
+ */
+function composeForOverride(name: string, type: TemplateVersionType, body: string): string {
+  if (type === "augmented") {
+    return getEmbeddedTemplate(name) + AUGMENTATION_SEPARATOR + body;
+  }
+  return body;
+}
+
+/**
+ * Boot-time refresh (item 6.8 round 2): for every managed template
+ * whose promoted version is augmented, re-compose `<bundled-default> +
+ * separator + <extension>` and write to the override file if it
+ * differs from what's already there. This is what makes cf²
+ * upgrades transparent for augmented versions — when the bundled
+ * default changes (because a new cf² version is installed), the
+ * boot refresh picks up the new default automatically without any
+ * user action.
+ *
+ * Only writes when content actually differs (cheap idempotent
+ * recompose). Returns the count of templates whose override was
+ * rewritten + any errors. Best-effort: per-template failures don't
+ * stop the loop.
+ *
+ * Full versions are NOT touched — they're frozen by design (the user
+ * has fully replaced the template; we have no safe way to merge
+ * upgrades).
+ */
+export async function refreshAugmentedOverrides(): Promise<{
+  refreshed: string[];
+  errors: Array<{ name: string; error: string }>;
+}> {
+  const refreshed: string[] = [];
+  const errors: Array<{ name: string; error: string }> = [];
+  for (const t of MANAGED_TEMPLATES) {
+    try {
+      const manifest = await readManifest(t.name);
+      const currentId = manifest.currentVersionId;
+      if (currentId === DEFAULT_VERSION_ID) continue;
+      const version = manifest.versions.find((v) => v.id === currentId);
+      if (!version || version.type !== "augmented") continue;
+
+      const body = await readFile(versionFilePath(t.name, currentId), "utf-8");
+      const composed = composeForOverride(t.name, "augmented", body);
+      const overridePath = overrideFilePath(t.name);
+      let onDisk: string | null = null;
+      try {
+        onDisk = await readFile(overridePath, "utf-8");
+      } catch {
+        onDisk = null;
+      }
+      if (onDisk !== composed) {
+        await writeOverrideFile(t.name, composed);
+        refreshed.push(t.name);
+      }
+    } catch (err) {
+      errors.push({
+        name: t.name,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return { refreshed, errors };
+}
+
 // --- Override-file helpers ---
 
 async function writeOverrideFile(name: string, content: string): Promise<void> {
diff --git a/packages/server/src/routes/role-templates.test.ts b/packages/server/src/routes/role-templates.test.ts
index 5c7ebce..4253146 100644
--- a/packages/server/src/routes/role-templates.test.ts
+++ b/packages/server/src/routes/role-templates.test.ts
@@ -112,6 +112,32 @@ describe("POST /api/role-templates/:name/versions", () => {
     });
     expect(res.status).toBe(400);
   });
+
+  it("creates an augmented version when type='augmented' is supplied (round 2)", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        label: "augmented test",
+        content: "Append-only directions.",
+        type: "augmented",
+      }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.type).toBe("augmented");
+  });
+
+  it("rejects invalid type with 400 (round 2)", async () => {
+    const app = createApp();
+    const res = await app.request(`/api/role-templates/${JUDGE_ENC}/versions`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label: "x", content: "y", type: "patch" }),
+    });
+    expect(res.status).toBe(400);
+  });
 });
 
 describe("GET /api/role-templates/:name/versions/:versionId", () => {
diff --git a/packages/server/src/routes/role-templates.ts b/packages/server/src/routes/role-templates.ts
index 1b48e4b..649b374 100644
--- a/packages/server/src/routes/role-templates.ts
+++ b/packages/server/src/routes/role-templates.ts
@@ -64,7 +64,7 @@ export function registerRoleTemplatesRoutes(app: Hono): void {
 
   app.post("/api/role-templates/:name/versions", async (c) => {
     const name = decodeURIComponent(c.req.param("name"));
-    let body: { label?: unknown; content?: unknown };
+    let body: { label?: unknown; content?: unknown; type?: unknown };
     try {
       body = await c.req.json();
     } catch {
@@ -73,8 +73,15 @@ export function registerRoleTemplatesRoutes(app: Hono): void {
     if (typeof body.label !== "string" || typeof body.content !== "string") {
       return c.json({ error: "Body must include `label` and `content` (both strings)" }, 400);
     }
+    let type: "full" | "augmented" = "full";
+    if (body.type !== undefined) {
+      if (body.type !== "full" && body.type !== "augmented") {
+        return c.json({ error: "`type` must be 'full' or 'augmented' if provided" }, 400);
+      }
+      type = body.type;
+    }
     try {
-      const v = await saveVersion(name, { label: body.label, content: body.content });
+      const v = await saveVersion(name, { label: body.label, content: body.content, type });
       return c.json(v, 201);
     } catch (err) {
       return c.json(errorBody(err), 400);
diff --git a/packages/server/src/start.ts b/packages/server/src/start.ts
index 1d58ce8..7ebd33d 100644
--- a/packages/server/src/start.ts
+++ b/packages/server/src/start.ts
@@ -28,6 +28,7 @@ import {
   reapOrphans,
   formatOrphanLine,
   refreshOllamaModelsInConfig,
+  refreshAugmentedOverrides,
 } from "@cfcf/core";
 import { closeClioBackend } from "./clio-backend.js";
 
@@ -157,6 +158,29 @@ export async function startServer(port: number): Promise<ReturnType<typeof Bun.s
     console.log(`Marked ${staleLoopCount} stale active loop(s) as failed`);
   }
 
+  // Re-compose any promoted "augmented" role-template overrides
+  // (item 6.8 round 2). Each augmented version stores only the user's
+  // extension; the override file on disk is `<bundled-default> +
+  // separator + <extension>`. When cf² is upgraded, the bundled
+  // default may have changed — this pass detects that and rewrites
+  // the override file with the new composition. Best-effort: errors
+  // are logged but never block boot.
+  try {
+    const result = await refreshAugmentedOverrides();
+    if (result.refreshed.length > 0) {
+      console.log(
+        `[server] Re-composed ${result.refreshed.length} augmented role-template override(s) after default change: ${result.refreshed.join(", ")}`,
+      );
+    }
+    for (const e of result.errors) {
+      console.warn(`[server] augmented-template refresh failed for ${e.name}: ${e.error}`);
+    }
+  } catch (err) {
+    console.warn(
+      `[server] augmented-template refresh pass failed (best-effort): ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
   // Refresh ollama models on every boot (item 6.33). The
   // `availableOllamaModels` list is captured at `cfcf init` and never
   // re-detected by the server itself. If the user pulls a new model
diff --git a/packages/web/src/api.ts b/packages/web/src/api.ts
index 3cfff8f..5724dfa 100644
--- a/packages/web/src/api.ts
+++ b/packages/web/src/api.ts
@@ -338,11 +338,17 @@ export function refreshOllamaModels(): Promise<RefreshOllamaModelsResponse> {
 
 // --- Role-template management (item 6.8) ---
 
+export type RoleTemplateVersionType = "full" | "augmented";
+
 export interface RoleTemplateVersion {
   id: string;
   label: string;
   savedAt: string;
   contentHash: string;
+  /** Round-2 type. Optional only for back-compat reads of round-1 manifests. */
+  type: RoleTemplateVersionType;
+  /** cf² version when this version was saved (display-only "forked from cf² vX.Y.Z" badge). */
+  cfcfVersion?: string;
 }
 
 export interface RoleTemplateSummary {
@@ -377,7 +383,7 @@ export function getRoleTemplateVersionContent(name: string, versionId: string):
 
 export function createRoleTemplateVersion(
   name: string,
-  body: { label: string; content: string },
+  body: { label: string; content: string; type?: RoleTemplateVersionType },
 ): Promise<RoleTemplateVersion> {
   return request<RoleTemplateVersion>(
     `/api/role-templates/${encodeURIComponent(name)}/versions`,
diff --git a/packages/web/src/pages/AgentTemplates.tsx b/packages/web/src/pages/AgentTemplates.tsx
index ee36a01..71953ee 100644
--- a/packages/web/src/pages/AgentTemplates.tsx
+++ b/packages/web/src/pages/AgentTemplates.tsx
@@ -1,19 +1,35 @@
 /**
  * Agents page (item 6.8): role-template management UI.
  *
- * Top-level layout: a tab strip across the top (one tab per managed
- * role template), then the main panel for the selected role with:
- *   - Heading + "currently in production" indicator
- *   - Version selector dropdown
- *   - Editor (textarea) — read-only by default; toggle Edit to make
- *     it editable. Save creates a new version with a label.
- *   - Promote-to-production / Revert-to-default actions
- *   - Per-version delete affordance (disabled for default)
+ * Round 2 (item 6.8 round 2 — augmented type added):
  *
- * State model: the currently-selected version is tracked locally
- * (`selectedVersionId`); when the user picks a different version
- * we re-fetch the content. The "promoted" version is whatever the
- * server says — independent of which version the user is viewing.
+ * Two version types coexist:
+ *   - "full"      → the version body REPLACES the bundled default.
+ *                   Maximum flexibility; no auto-upgrade.
+ *   - "augmented" → the version body is APPENDED to the bundled default
+ *                   at promote/recompose time. Auto-picks-up cf² upgrades.
+ *
+ * Two creation entry points:
+ *   - "Edit"    button → enters full-edit mode (single textarea
+ *                        prefilled with the currently-selected version).
+ *   - "Augment" button → enters augmented-edit mode (split view: bundled
+ *                        default read-only on top, empty extension below).
+ *
+ * Existing-version display:
+ *   - Full version    → single textarea, the version's body.
+ *   - Augmented version → split view: bundled default (read-only) on top,
+ *                         the version's extension on bottom (read-only or
+ *                         editable depending on isEditing).
+ *
+ * Save actions vary by editType:
+ *   - Editing existing full      → Save changes / Save as new full version
+ *   - Editing existing augmented → Save changes / Save as new augmented version
+ *   - Creating new full          → Save as new full version
+ *   - Creating new augmented     → Save as new augmented version
+ *
+ * Storage + composition + auto-recompose-on-cf²-upgrade live in
+ * `@cfcf/core/role-templates` (`refreshAugmentedOverrides`); this
+ * component is just the UI surface.
  */
 
 import { useEffect, useState } from "react";
@@ -28,6 +44,7 @@ import {
   type RoleTemplateSummary,
   type RoleTemplateFull,
   type RoleTemplateVersion,
+  type RoleTemplateVersionType,
 } from "../api";
 import { navigateTo } from "../hooks/useRoute";
 
@@ -43,8 +60,22 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
   const [activeName, setActiveName] = useState<string | null>(initialTemplate ?? null);
   const [template, setTemplate] = useState<RoleTemplateFull | null>(null);
   const [selectedVersionId, setSelectedVersionId] = useState<string>(DEFAULT_VERSION_ID);
+  /**
+   * Body content shown in the editor.
+   * - For full-type display: the entire template body.
+   * - For augmented-type display: just the user's EXTENSION
+   *   (the bundled default is rendered separately above it).
+   */
   const [content, setContent] = useState<string>("");
   const [isEditing, setIsEditing] = useState(false);
+  /**
+   * What kind of edit/creation flow the user is in. Only meaningful
+   * while `isEditing === true`. Set by the Edit / Augment buttons.
+   * For editing existing versions it mirrors the version's type.
+   */
+  const [editType, setEditType] = useState<RoleTemplateVersionType>("full");
+  /** True when the user clicked Augment (creates new augmented from default). */
+  const [creatingNew, setCreatingNew] = useState(false);
   const [editingDirty, setEditingDirty] = useState(false);
   const [statusMsg, setStatusMsg] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -53,8 +84,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
   // Bumped after a save / delete / promote to refresh dependent data.
   const [rev, setRev] = useState(0);
 
-  // Initial load: fetch summary list + auto-select first if none chosen
-  // (or if the URL points at a template name that doesn't exist).
+  // Initial load: fetch summary list + auto-select first.
   useEffect(() => {
     listRoleTemplates()
       .then((r) => {
@@ -69,10 +99,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // React to back/forward navigation: when the URL's `?template=` query
-  // changes, sync activeName so the page actually shows the new tab.
-  // Without this effect, only the first mount's initialTemplate was
-  // honoured; later hash changes were silently ignored.
+  // React to back/forward navigation through `?template=...`.
   useEffect(() => {
     if (!initialTemplate) return;
     if (initialTemplate === activeName) return;
@@ -82,56 +109,99 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [initialTemplate, summaries]);
 
-  // Whenever activeName or rev changes, fetch full template state.
+  // Load full state for the active template.
   useEffect(() => {
     if (!activeName) return;
     setError(null);
     getRoleTemplate(activeName)
       .then((t) => {
         setTemplate(t);
-        // Default to viewing the currently-promoted version.
         setSelectedVersionId(t.currentVersionId);
-        setContent(t.currentContent);
+        // Fetch the body for the currently-promoted version (just the
+        // extension if it's augmented; the full body otherwise).
+        return loadBodyForSelection(t, t.currentVersionId);
+      })
+      .then(() => {
         setIsEditing(false);
         setEditingDirty(false);
-        // Update URL (without page reload) so the back button works.
-        if (window.location.hash !== `#/agents?template=${encodeURIComponent(t.name)}`) {
-          window.history.replaceState(null, "", `#/agents?template=${encodeURIComponent(t.name)}`);
-        }
+        setCreatingNew(false);
       })
       .catch((e) => setError(String(e)));
+
+    if (window.location.hash !== `#/agents?template=${encodeURIComponent(activeName)}`) {
+      window.history.replaceState(null, "", `#/agents?template=${encodeURIComponent(activeName)}`);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [activeName, rev]);
 
-  // When the user picks a different version (without editing), fetch its content.
+  // When the user picks a different version (without editing), re-fetch
+  // the body for that version.
   useEffect(() => {
     if (!activeName || !template) return;
     if (isEditing) return; // don't blow away in-flight edits
-    if (selectedVersionId === template.currentVersionId) {
-      setContent(template.currentContent);
-      return;
-    }
-    if (selectedVersionId === DEFAULT_VERSION_ID) {
-      setContent(template.defaultContent);
+    loadBodyForSelection(template, selectedVersionId).catch((e) => setError(String(e)));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedVersionId, activeName]);
+
+  async function loadBodyForSelection(t: RoleTemplateFull, versionId: string): Promise<void> {
+    if (versionId === DEFAULT_VERSION_ID) {
+      setContent(t.defaultContent);
       return;
     }
-    getRoleTemplateVersionContent(activeName, selectedVersionId)
-      .then((r) => setContent(r.content))
-      .catch((e) => setError(String(e)));
-  }, [selectedVersionId, activeName, template, isEditing]);
+    const r = await getRoleTemplateVersionContent(t.name, versionId);
+    setContent(r.content);
+  }
 
   // --- Action handlers ---
 
+  function startEdit() {
+    if (!template) return;
+    const v = template.versions.find((x) => x.id === selectedVersionId);
+    setEditType(v ? v.type : "full");
+    setCreatingNew(selectedVersionId === DEFAULT_VERSION_ID); // Edit on default = creating new
+    setIsEditing(true);
+    setEditingDirty(false);
+    setStatusMsg(null);
+  }
+
+  function startAugment() {
+    if (!template) return;
+    if (editingDirty && !window.confirm("Discard unsaved changes?")) return;
+    // Augment ALWAYS creates a new augmented version on top of the
+    // bundled default — regardless of which version is currently
+    // selected. This keeps the upgrade-friendly contract: augmented
+    // versions ride along on whatever cf² ships next.
+    setSelectedVersionId(DEFAULT_VERSION_ID);
+    setEditType("augmented");
+    setCreatingNew(true);
+    setIsEditing(true);
+    setEditingDirty(false);
+    setContent(""); // empty extension; user types their additions
+    setStatusMsg(null);
+  }
+
   async function handleSaveAsNew() {
     if (!activeName) return;
-    const label = window.prompt("Label for this version (e.g. 'stricter judge', 'opus run')");
+    const promptText =
+      editType === "augmented"
+        ? "Label for this augmented version (e.g. 'jira-hint', 'team-style')"
+        : "Label for this version (e.g. 'stricter judge', 'opus run')";
+    const label = window.prompt(promptText);
     if (!label || !label.trim()) return;
     setBusy(true);
     setStatusMsg(null);
     try {
-      const v = await createRoleTemplateVersion(activeName, { label: label.trim(), content });
-      setStatusMsg(`✓ Saved as "${v.label}". (Not yet promoted — click Promote below.)`);
+      const v = await createRoleTemplateVersion(activeName, {
+        label: label.trim(),
+        content,
+        type: editType,
+      });
+      setStatusMsg(
+        `✓ Saved as "${v.label}" (${v.type}). Not yet promoted — click Promote to make it live.`,
+      );
       setIsEditing(false);
       setEditingDirty(false);
+      setCreatingNew(false);
       setRev((n) => n + 1);
       setSelectedVersionId(v.id);
     } catch (e) {
@@ -154,7 +224,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
       setStatusMsg(
         selectedVersionId === template.currentVersionId
           ? "✓ Saved. (This version is currently promoted, so the change is live for the next agent run.)"
-          : "✓ Saved. (Promote this version to make it live.)",
+          : "✓ Saved. Promote this version to make it live.",
       );
       setIsEditing(false);
       setEditingDirty(false);
@@ -176,7 +246,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
       setStatusMsg(
         selectedVersionId === DEFAULT_VERSION_ID
           ? "✓ Reverted to bundled default. The next agent run will use cf²'s default template."
-          : `✓ Promoted to production. The next agent run will use this version.`,
+          : "✓ Promoted to production. The next agent run will use this version.",
       );
       setRev((n) => n + 1);
     } catch (e) {
@@ -188,7 +258,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
 
   async function handleDelete() {
     if (!activeName || !template) return;
-    if (selectedVersionId === DEFAULT_VERSION_ID) return; // can't happen UI-wise
+    if (selectedVersionId === DEFAULT_VERSION_ID) return;
     const v = template.versions.find((x) => x.id === selectedVersionId);
     if (!v) return;
     if (!window.confirm(`Delete version "${v.label}"? This cannot be undone.`)) return;
@@ -206,7 +276,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
     }
   }
 
-  // --- Render ---
+  // --- Derived state ---
 
   if (!activeName) {
     return (
@@ -222,11 +292,30 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
     if (!template) return "—";
     if (template.currentVersionId === DEFAULT_VERSION_ID) return "Default (built-in)";
     const v = template.versions.find((x) => x.id === template.currentVersionId);
-    return v ? v.label : template.currentVersionId;
+    return v ? `${v.label} (${v.type})` : template.currentVersionId;
   })();
 
   const selectionIsPromoted = template?.currentVersionId === selectedVersionId;
   const selectionIsDefault = selectedVersionId === DEFAULT_VERSION_ID;
+  const selectedVersion: RoleTemplateVersion | undefined = template?.versions.find(
+    (x) => x.id === selectedVersionId,
+  );
+  /**
+   * Type the editor should render in.
+   * - When editing: editType (set by the Edit / Augment button).
+   * - When viewing: the selected version's type, defaulting to "full"
+   *   for the bundled default (single textarea read-only).
+   */
+  const displayType: RoleTemplateVersionType = isEditing
+    ? editType
+    : (selectedVersion?.type ?? "full");
+  const showSplitView = displayType === "augmented";
+  // The textarea(s) are editable only in edit mode AND when the user
+  // is actually authoring the body (default tab is "view-only" for the
+  // standard template even in augment mode — that's what the read-only
+  // top panel is).
+  const extensionEditable = isEditing && displayType === "augmented";
+  const fullEditable = isEditing && displayType === "full";
 
   return (
     <div style={{ padding: "1rem", maxWidth: "1100px", margin: "0 auto" }}>
@@ -273,7 +362,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
               {s.displayName}
               {s.currentVersionId !== DEFAULT_VERSION_ID && (
                 <span
-                  title="Custom version is currently promoted"
+                  title="A custom version is currently promoted"
                   style={{ marginLeft: "0.4rem", color: "var(--color-accent, #4a8ee6)" }}
                 >
                   •
@@ -318,6 +407,18 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
                   • unsaved changes
                 </span>
               )}
+              {creatingNew && isEditing && (
+                <span
+                  style={{
+                    marginLeft: "0.5rem",
+                    fontSize: "var(--text-sm)",
+                    color: "var(--color-accent, #4a8ee6)",
+                    fontWeight: "normal",
+                  }}
+                >
+                  • creating new {editType} version
+                </span>
+              )}
             </h3>
             <span style={{ fontSize: "var(--text-sm)", color: "var(--color-text-muted, #888)" }}>
               In production:{" "}
@@ -328,10 +429,29 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
             Template file: <code>{template.name}</code>. Override path:{" "}
             <code>~/.cfcf/templates/{template.name}</code>{" "}
             <span style={{ opacity: 0.7 }}>
-              (written by cf² when you promote a non-default version; deleted when you revert).
+              (cf² writes the composed override file here when a non-default version is promoted;
+              deletes it when you revert.)
             </span>
           </p>
 
+          {/* Status message — moved ABOVE the version selector so the
+              "Promote to make it live" hint is below the action buttons
+              when the user reads it. */}
+          {statusMsg && (
+            <div
+              style={{
+                marginBottom: "0.75rem",
+                padding: "0.5rem 0.75rem",
+                background: "color-mix(in srgb, var(--color-success, #6ec06e) 12%, transparent)",
+                borderLeft: "3px solid var(--color-success, #6ec06e)",
+                fontSize: "var(--text-sm)",
+                borderRadius: "4px",
+              }}
+            >
+              {statusMsg}
+            </div>
+          )}
+
           {/* Version selector + actions */}
           <div
             style={{
@@ -350,7 +470,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
               value={selectedVersionId}
               disabled={isEditing}
               onChange={(e) => setSelectedVersionId(e.target.value)}
-              style={{ minWidth: "16rem" }}
+              style={{ minWidth: "20rem" }}
             >
               <option value={DEFAULT_VERSION_ID}>
                 Default (built-in)
@@ -358,7 +478,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
               </option>
               {template.versions.map((v) => (
                 <option key={v.id} value={v.id}>
-                  {v.label} ({new Date(v.savedAt).toLocaleString()})
+                  {v.label} — {v.type} ({new Date(v.savedAt).toLocaleString()})
                   {template.currentVersionId === v.id ? " — promoted" : ""}
                 </option>
               ))}
@@ -370,10 +490,26 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
                   type="button"
                   className="btn btn--small btn--secondary"
                   disabled={busy}
-                  onClick={() => setIsEditing(true)}
+                  onClick={startEdit}
+                  title={
+                    selectionIsDefault
+                      ? "Fork the bundled default into a new full version"
+                      : selectedVersion?.type === "augmented"
+                      ? "Edit this augmented version's extension"
+                      : "Edit this full version's body"
+                  }
                 >
                   Edit
                 </button>
+                <button
+                  type="button"
+                  className="btn btn--small btn--secondary"
+                  disabled={busy}
+                  onClick={startAugment}
+                  title="Add custom directions on top of the bundled default (auto-upgrades when cf² ships a new default)"
+                >
+                  Augment
+                </button>
                 <button
                   type="button"
                   className="btn btn--small btn--primary"
@@ -397,7 +533,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
               </>
             ) : (
               <>
-                {!selectionIsDefault && (
+                {!creatingNew && !selectionIsDefault && (
                   <button
                     type="button"
                     className="btn btn--small btn--primary"
@@ -410,11 +546,15 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
                 <button
                   type="button"
                   className="btn btn--small btn--primary"
-                  disabled={busy || !editingDirty}
+                  disabled={busy || (!editingDirty && !creatingNew)}
                   onClick={handleSaveAsNew}
-                  title="Save as a new version (with a label) — original stays untouched"
+                  title={
+                    editType === "augmented"
+                      ? "Save as a new augmented version (extension only — auto-upgrades with cf²)"
+                      : "Save as a new full version (frozen — does not auto-upgrade)"
+                  }
                 >
-                  Save as new version
+                  Save as new {editType} version
                 </button>
                 <button
                   type="button"
@@ -424,7 +564,7 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
                     if (editingDirty && !window.confirm("Discard unsaved changes?")) return;
                     setIsEditing(false);
                     setEditingDirty(false);
-                    // Re-fetch original content for the selected version.
+                    setCreatingNew(false);
                     setRev((n) => n + 1);
                   }}
                 >
@@ -434,63 +574,44 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
             )}
           </div>
 
-          {statusMsg && (
-            <div
+          {/* Forked-from-cf²-vX.Y.Z badge for full versions */}
+          {!isEditing && selectedVersion?.type === "full" && selectedVersion.cfcfVersion && (
+            <p
               style={{
+                marginTop: "-0.25rem",
                 marginBottom: "0.75rem",
-                padding: "0.5rem 0.75rem",
-                background: "color-mix(in srgb, var(--color-success, #6ec06e) 12%, transparent)",
-                borderLeft: "3px solid var(--color-success, #6ec06e)",
                 fontSize: "var(--text-sm)",
-                borderRadius: "4px",
+                color: "var(--color-text-muted, #888)",
               }}
             >
-              {statusMsg}
-            </div>
+              ℹ Forked from cf² <code>v{selectedVersion.cfcfVersion}</code>'s bundled default. Full
+              versions don't auto-upgrade — compare against the latest <strong>Default
+              (built-in)</strong> if cf² has shipped a newer template since.
+            </p>
           )}
 
-          {/* Content editor.
-              readOnly is gated ONLY by `!isEditing` — the bundled default
-              "lives" on disk read-only (we never overwrite the embedded
-              constant), but the user still needs to TYPE in this editor
-              to draft a new version that gets saved via "Save as new
-              version". The save action is what's gated, not the typing. */}
-          <textarea
-            value={content}
-            readOnly={!isEditing}
-            onChange={(e) => {
-              setContent(e.target.value);
-              setEditingDirty(true);
-            }}
-            spellCheck={false}
-            style={{
-              width: "100%",
-              minHeight: "60vh",
-              fontFamily: "var(--font-mono, monospace)",
-              fontSize: "var(--text-sm)",
-              padding: "0.75rem",
-              border: "1px solid var(--color-border, #444)",
-              borderRadius: "4px",
-              background: isEditing
-                ? "var(--color-bg)"
-                : "var(--color-bg-muted, var(--color-bg))",
-              color: "var(--color-text)",
-              resize: "vertical",
-            }}
-          />
-          {isEditing && selectionIsDefault && (
-            <p
-              style={{
-                marginTop: "0.5rem",
-                fontSize: "var(--text-sm)",
-                color: "var(--color-text-muted, #888)",
+          {/* Editor area — split for augmented, single for full */}
+          {showSplitView ? (
+            <SplitEditor
+              defaultContent={template.defaultContent}
+              extension={content}
+              extensionEditable={extensionEditable}
+              onExtensionChange={(next) => {
+                setContent(next);
+                setEditingDirty(true);
               }}
-            >
-              You're editing a copy of the bundled default. Click{" "}
-              <strong>Save as new version</strong> to fork your changes
-              into a new version (the cf²-shipped default itself stays
-              untouched and remains available in the dropdown).
-            </p>
+              creatingNew={creatingNew}
+            />
+          ) : (
+            <FullEditor
+              content={content}
+              editable={fullEditable}
+              onChange={(next) => {
+                setContent(next);
+                setEditingDirty(true);
+              }}
+              showFullEditFromDefaultHint={isEditing && selectionIsDefault && !creatingNew}
+            />
           )}
 
           {/* Inline help below editor */}
@@ -506,12 +627,16 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
             }}
             role="status"
           >
-            <strong style={{ display: "block", marginBottom: "0.25rem" }}>How this works</strong>
+            <strong style={{ display: "block", marginBottom: "0.4rem" }}>How this works</strong>
             <div style={{ marginBottom: "0.4rem" }}>
-              cf² ships a built-in default for every role. Saved versions live under{" "}
-              <code>~/.cfcf/templates-managed/{template.name}/</code>. When you promote a version,
-              its content is written to <code>~/.cfcf/templates/{template.name}</code> — the
-              existing user-global override path that <code>getTemplate()</code> already reads.
+              <strong>Two ways to customise a role.</strong> <em>Edit</em> opens a single editor
+              prefilled with the selected version's content; saving creates a <strong>full</strong>
+              {" "}version that <strong>replaces</strong> the bundled default entirely. <em>Augment</em>
+              {" "}keeps cf²'s default read-only and lets you add a section below it; saving creates
+              an <strong>augmented</strong> version. The harness composes
+              {" "}<code>&lt;default&gt; + separator + &lt;your additions&gt;</code> at promote
+              time, and re-composes on every server boot — so when cf² ships a new default,
+              your augmented additions automatically ride along. Full versions don't migrate.
             </div>
             <div style={{ marginBottom: "0.4rem" }}>
               <strong>"Promote to production"</strong> activates the selected version for the next
@@ -525,7 +650,6 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
             </div>
           </div>
 
-          {/* Subtle skip-link to Settings (the user might be looking for the global config). */}
           <p style={{ marginTop: "1.5rem", fontSize: "var(--text-sm)", color: "var(--color-text-muted, #888)" }}>
             Looking for adapter / model settings?{" "}
             <a
@@ -545,3 +669,167 @@ export function AgentTemplatesPage({ initialTemplate }: Props) {
     </div>
   );
 }
+
+// --- Sub-components ---
+
+/**
+ * Single-textarea editor for full-type versions (and the bundled
+ * default, which renders here as a read-only full template).
+ */
+function FullEditor({
+  content,
+  editable,
+  onChange,
+  showFullEditFromDefaultHint,
+}: {
+  content: string;
+  editable: boolean;
+  onChange: (next: string) => void;
+  showFullEditFromDefaultHint: boolean;
+}) {
+  return (
+    <>
+      <textarea
+        value={content}
+        readOnly={!editable}
+        onChange={(e) => onChange(e.target.value)}
+        spellCheck={false}
+        style={{
+          width: "100%",
+          minHeight: "60vh",
+          fontFamily: "var(--font-mono, monospace)",
+          fontSize: "var(--text-sm)",
+          padding: "0.75rem",
+          border: "1px solid var(--color-border, #444)",
+          borderRadius: "4px",
+          background: editable
+            ? "var(--color-bg)"
+            : "var(--color-bg-muted, var(--color-bg))",
+          color: "var(--color-text)",
+          resize: "vertical",
+        }}
+      />
+      {showFullEditFromDefaultHint && (
+        <p
+          style={{
+            marginTop: "0.5rem",
+            fontSize: "var(--text-sm)",
+            color: "var(--color-text-muted, #888)",
+          }}
+        >
+          You're editing a copy of the bundled default. Click <strong>Save as new full
+          version</strong> to fork your changes — the cf²-shipped default itself stays untouched
+          and remains available in the dropdown.
+        </p>
+      )}
+    </>
+  );
+}
+
+/**
+ * Split editor for augmented-type versions: bundled default at top
+ * (always read-only — that's the whole point of the type) + extension
+ * textarea at bottom (editable when `extensionEditable`).
+ *
+ * Shorter standard panel by design (~25vh) so the extension editor
+ * has visual prominence, since that's what the user is actually
+ * working with.
+ */
+function SplitEditor({
+  defaultContent,
+  extension,
+  extensionEditable,
+  onExtensionChange,
+  creatingNew,
+}: {
+  defaultContent: string;
+  extension: string;
+  extensionEditable: boolean;
+  onExtensionChange: (next: string) => void;
+  creatingNew: boolean;
+}) {
+  return (
+    <>
+      <div
+        style={{
+          marginBottom: "0.5rem",
+          fontSize: "var(--text-sm)",
+          color: "var(--color-text-muted, #888)",
+          display: "flex",
+          alignItems: "baseline",
+          justifyContent: "space-between",
+          gap: "0.5rem",
+          flexWrap: "wrap",
+        }}
+      >
+        <strong style={{ color: "var(--color-text)" }}>cf² standard template (read-only)</strong>
+        <span>
+          Updated automatically when cf² ships a new default; your extension below rides along.
+        </span>
+      </div>
+      <textarea
+        value={defaultContent}
+        readOnly
+        spellCheck={false}
+        style={{
+          width: "100%",
+          minHeight: "25vh",
+          fontFamily: "var(--font-mono, monospace)",
+          fontSize: "var(--text-sm)",
+          padding: "0.75rem",
+          border: "1px solid var(--color-border, #444)",
+          borderRadius: "4px",
+          background: "var(--color-bg-muted, var(--color-bg))",
+          color: "var(--color-text)",
+          resize: "vertical",
+          marginBottom: "1rem",
+        }}
+      />
+      <div
+        style={{
+          marginBottom: "0.5rem",
+          fontSize: "var(--text-sm)",
+          color: "var(--color-text-muted, #888)",
+          display: "flex",
+          alignItems: "baseline",
+          justifyContent: "space-between",
+          gap: "0.5rem",
+          flexWrap: "wrap",
+        }}
+      >
+        <strong style={{ color: "var(--color-text)" }}>
+          Your custom additions{" "}
+          {extensionEditable ? "" : "(read-only)"}
+        </strong>
+        <span>
+          Appended after the standard template at promote time + every server boot.
+        </span>
+      </div>
+      <textarea
+        value={extension}
+        readOnly={!extensionEditable}
+        onChange={(e) => onExtensionChange(e.target.value)}
+        spellCheck={false}
+        placeholder={
+          creatingNew
+            ? "Write your custom directions here. Examples:\n• Always cite the Linear ticket ID in summaries.\n• Use AAA test naming.\n• Prefer functional patterns over classes."
+            : ""
+        }
+        style={{
+          width: "100%",
+          minHeight: "30vh",
+          fontFamily: "var(--font-mono, monospace)",
+          fontSize: "var(--text-sm)",
+          padding: "0.75rem",
+          border: "1px solid var(--color-border, #444)",
+          borderRadius: "4px",
+          background: extensionEditable
+            ? "var(--color-bg)"
+            : "var(--color-bg-muted, var(--color-bg))",
+          color: "var(--color-text)",
+          resize: "vertical",
+        }}
+      />
+    </>
+  );
+}

From e8de21badeeb82d6882ca7ed9079d737a431dca7 Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 23:19:48 -0700
Subject: [PATCH 6/8] =?UTF-8?q?fix(6.8):=20rename=20"Workspace=20Process"?=
 =?UTF-8?q?=20=E2=86=92=20"Developer"=20+=20reorder=20tabs=20to=20match=20?=
 =?UTF-8?q?agent=20execution=20flow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The user spotted that the tab labelled "Workspace Process" is
functionally the **dev agent's** primary instruction template — the
file's content literally opens with "You are a dev agent working on
a cfcf-managed workspace. This document defines how you operate
within each iteration."

The historical name `process.md` predates the explicit per-role
instruction files (cfcf-architect-instructions.md, etc.) so it never
got renamed to `cfcf-dev-instructions.md`. The display name in the
Agents tab should reflect the role, not the historical filename. The
inline "Template file: process.md" hint on the page still surfaces
the real filename for users who grep the override directory.

Also reorders the tabs to match the natural agent execution
sequence within an iteration loop:
  Solution Architect → Developer → Judge → Reflection → Documenter

(Architect runs pre-loop and on refine_plan / NEEDS_REFINEMENT;
dev does the work; judge assesses; reflection optionally analyses
across iterations; documenter runs post-SUCCESS. Reading top-to-
bottom in the UI now mirrors the firing order.)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/core/src/role-templates.ts | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/role-templates.ts b/packages/core/src/role-templates.ts
index 9656bea..fd9ab62 100644
--- a/packages/core/src/role-templates.ts
+++ b/packages/core/src/role-templates.ts
@@ -132,19 +132,31 @@ export interface ManagedTemplateSummary {
 
 /**
  * The set of templates exposed via the management UI. Order matters —
- * it's the tab order in the web UI. Only templates listed here can be
- * managed; everything else in `EMBEDDED` is internal scaffolding (signal
- * files, markdown stubs) that wouldn't make sense to expose.
+ * it's the tab order in the web UI, chosen to match the **natural
+ * agent execution sequence** within an iteration loop: architect runs
+ * pre-loop (and on refine_plan / NEEDS_REFINEMENT), dev does the work,
+ * judge assesses, reflection optionally analyses cross-iteration, and
+ * documenter runs post-SUCCESS. Surfacing in this order means the user
+ * reads top-to-bottom in the same direction the agents fire.
+ *
+ * `process.md` is the **dev agent's primary instruction template** —
+ * the file's content literally opens with "You are a dev agent…". It's
+ * named "process.md" historically (it predates the explicit per-role
+ * instruction files for architect / judge / etc.), but functionally
+ * serves as `cfcf-dev-instructions.md`. The display name "Developer"
+ * reflects the role; the inline "Template file: process.md" hint on
+ * the page surfaces the actual filename for users who need to grep
+ * the override directory.
  *
  * If you add a new role-instruction template to the embedded registry,
  * add it here too to surface it in the management UI.
  */
 const MANAGED_TEMPLATES: Array<{ name: string; displayName: string }> = [
   { name: "cfcf-architect-instructions.md", displayName: "Solution Architect" },
+  { name: "process.md", displayName: "Developer" },
   { name: "cfcf-judge-instructions.md", displayName: "Judge" },
-  { name: "cfcf-documenter-instructions.md", displayName: "Documenter" },
   { name: "cfcf-reflection-instructions.md", displayName: "Reflection" },
-  { name: "process.md", displayName: "Workspace Process" },
+  { name: "cfcf-documenter-instructions.md", displayName: "Documenter" },
 ];
 
 export function listManagedTemplateNames(): Array<{ name: string; displayName: string }> {

From 804824ccf46f8fd6a60ba3f7610df219d678b297 Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 23:31:29 -0700
Subject: [PATCH 7/8] =?UTF-8?q?docs(audit):=20full=20sweep=20=E2=80=94=20f?=
 =?UTF-8?q?ix=20stale=20"manually-invoked=20SA=20=3D=20interactive"=20clai?=
 =?UTF-8?q?ms=20+=20document=20new=20features?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A documentation audit pass over all user-facing docs to align with
recent changes (items 6.30, 6.31, 6.33, 6.8 rounds 1+2).

Stale "manually-invoked SA via cfcf review = interactive" framing
removed from:
- README.md (top-level policy heads-up)
- docs/guides/installing.md (Claude Code install recommendation)
- docs/guides/cli-usage.md (cfcf init warnings section)
- docs/guides/workflow.md (adapter-choice block)
- docs/guides/troubleshooting.md (harness-policy warning entry)

Reality (verified in code 6.30): ALL architect spawns are headless
`claude -p` regardless of how they're invoked. `cfcf review` is just
a polling client to a server-side background spawn — there's no
`stdio: "inherit"` anywhere in the architect path. Only PA + HA
truly take over the user's shell. All five surfaces now reflect this.

Also fixed:
- docs/guides/installing.md: dropped "auto-architect" qualifier from
  the unattended-roles enumeration; architect is always unattended.

New feature documentation:
- docs/api/server-api.md: added `GET /api/agents/models`,
  `POST /api/agents/refresh-ollama-models` (item 6.33), and the full
  `/api/role-templates/*` surface (item 6.8).
- docs/guides/cli-usage.md: added `cfcf server reap` section
  (item 6.31, v0.21.0); ollama-models auto-refresh + button
  reference (item 6.33); five-tab web UI navigation overview
  (Workspaces / Memory / Agents / Settings / Help) including a brief
  description of the new Agents tab and its full+augmented version
  types.
- docs/guides/manual.md: expanded Agents-tab bullet to mention
  round-2 full vs augmented version types + execution-order tab
  layout.
- docs/README.md: refreshed the directory map with the design docs +
  guides that have been added since the last update
  (role-template-management.md, anthropic-policy.md, etc.).
- CLAUDE.md: added bullets for role-template management (item 6.8),
  orphan reaper (item 6.31), ollama auto-refresh (item 6.33), and
  the architect-always-unattended classification (item 6.30). File
  structure section now lists role-templates.ts, orphan-reaper.ts,
  ollama-detection.ts, AgentTemplatesPage, and the cfcf server reap
  CLI verb.

Plan + decisions-log + design + research files left unchanged —
those are historical and shouldn't be retroactively edited.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                      |  30 +++++++-
 README.md                      |   2 +-
 docs/README.md                 |  32 +++++---
 docs/api/server-api.md         | 135 +++++++++++++++++++++++++++++++++
 docs/guides/cli-usage.md       |  42 ++++++++--
 docs/guides/installing.md      |   6 +-
 docs/guides/manual.md          |   2 +-
 docs/guides/troubleshooting.md |   2 +-
 docs/guides/workflow.md        |   4 +-
 9 files changed, 227 insertions(+), 28 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1079a70..f6747a3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,7 +15,10 @@ cfcf (Cerefox Code Factory, also written cf², pronounced "cf square") is a dete
 - Agents run as **local processes** (not containers) in the user's dev environment
 - **Git branches** provide isolation between iterations (feature branch per iteration, merge to main)
 - **Seven agent roles**: five run inside the iteration loop — dev (writes code), judge (per-iteration assessment), architect (reviews / extends Problem Pack; verdicts: READY / NEEDS_REFINEMENT / BLOCKED / SCOPE_COMPLETE), reflection (cross-iteration strategic review), documenter (produces final docs); two are interactive — Product Architect (live spec iteration before the loop, item 5.14) and Help Assistant (in-shell guidance). Each role independently configurable (adapter + model).
-- **Per-adapter model registry** (item 6.26): pickers in web Settings, web workspace Config, and `cfcf init` / `cfcf config edit` source their model dropdown from `packages/core/src/adapters/seed-models.ts` (the bundled seed) merged with the user's optional override on `CfcfGlobalConfig.agentModels[<adapter>]`. Resolution lives in `resolveModelsForAdapter()`. The seed is intentionally minimal — generic aliases (`opus`, `sonnet`, `haiku` for claude-code; `gpt-5-codex`, `gpt-5`, `o3` for codex) so it ages slowly. **Single edit surface**: web Settings → Model registry is the one place to add/remove/reset per-adapter models; pickers themselves are read-only dropdowns (no inline "custom name" affordance — kept the UI predictable: one place to manage models). Hand-edited config values that aren't in the registry are preserved as `(custom)` entries on first render so back-compat doesn't break. **Maintenance**: when an upstream agent CLI ships a new headline model, edit the relevant array in `seed-models.ts` and ship in the next release; user overrides survive the upgrade.
+- **Per-adapter model registry** (item 6.26): pickers in web Settings, web workspace Config, and `cfcf init` / `cfcf config edit` source their model dropdown from `packages/core/src/adapters/seed-models.ts` (the bundled seed) merged with the user's optional override on `CfcfGlobalConfig.agentModels[<adapter>]`. Resolution lives in `resolveModelsForAdapter()`. The seed is intentionally minimal — generic aliases (`opus`, `sonnet`, `haiku` for claude-code; `gpt-5-codex`, `gpt-5`, `o3` for codex) so it ages slowly. **Single edit surface**: web Settings → Model registry is the one place to add/remove/reset per-adapter models; pickers themselves are read-only dropdowns (no inline "custom name" affordance — kept the UI predictable: one place to manage models). Hand-edited config values that aren't in the registry are preserved as `(custom)` entries on first render so back-compat doesn't break. **Maintenance**: when an upstream agent CLI ships a new headline model, edit the relevant array in `seed-models.ts` and ship in the next release; user overrides survive the upgrade. **Ollama-models refresh** (item 6.33, v0.21.x): for `*-ollama` adapters the model list comes from `availableOllamaModels` in the global config (populated at `cfcf init`). To pick up newly-pulled ollama models, the list is auto-refreshed on every `cfcf server start` (`refreshOllamaModelsInConfig()` in `@cfcf/core`, called from `start.ts`) AND on demand via the "Refresh ollama models" button in the web UI Agent-roles section (Settings + workspace Config). `POST /api/agents/refresh-ollama-models` is the underlying endpoint.
+- **Role-template management** (item 6.8): top-level **Agents** tab in the web UI lets users edit the instruction templates each role reads (`cfcf-architect-instructions.md`, `process.md` for the dev role, `cfcf-judge-instructions.md`, `cfcf-reflection-instructions.md`, `cfcf-documenter-instructions.md`). Each role has a bundled cf² default (always selectable, read-only) and any number of saved versions stored under `~/.cfcf/templates-managed/<name>/`. Two version types: **`full`** REPLACES the default (max flexibility, no auto-upgrade — UI shows a "Forked from cf² vX.Y.Z" badge); **`augmented`** APPENDS to the live default (extension-only on disk; composed at promote time + every server boot via `refreshAugmentedOverrides()` so cf² upgrades automatically propagate). Promoting a version writes the (composed-for-augmented) content to the existing user-global override path `~/.cfcf/templates/<name>` that `getTemplate()` already reads — no runtime changes to the agent-spawn pipeline. Reverting to default deletes the override. Project-local overrides at `<repo>/cfcf-templates/<name>` continue to take precedence (power-user escape hatch, unmanaged from the UI). Core: `packages/core/src/role-templates.ts`. API: `/api/role-templates/*`. UI: `packages/web/src/pages/AgentTemplates.tsx`. Design doc: `docs/design/role-template-management.md`.
+- **Orphan agent-process reaper** (item 6.31, v0.21.0): cf² spawns agents with `detached: true` so SIGTERM at server shutdown can kill the whole process group. **Graceful shutdown** (SIGINT/SIGTERM) sends group SIGTERM, waits 1.5s, then group SIGKILL — handles the common case. **Boot-time orphan scan** (`refreshAugmentedOverrides`'s sibling, in `packages/core/src/orphan-reaper.ts`) closes the hard-crash hole: when the previous server died via SIGKILL or OS panic, its agent children get reparented to PID 1; on next `cfcf server start`, the boot scan finds them via three conjoined filters (PPID==1 + same effective user + cfcf-spawned command shape) and reaps them. Orphans on `ollama launch <agent>` are particularly important — they hold ollama's model serializer for up to 10 min after their inference times out. **`cfcf server reap`** is the manual interactive variant (list + y/N + kill); doesn't require the cfcf server to be running. See `findOrphanAgentProcesses()` + `reapOrphans()` in `@cfcf/core`.
+- **Architect role is unattended for ALL invocation paths** (item 6.30, v0.21.0): the previous "manually-invoked SA via `cfcf review` is interactive" framing was wrong — verified in code that ALL architect spawns (pre-loop autoReviewSpecs, mid-loop refine_plan, manual `cfcf review`) use `spawnProcess` with `stdout: "pipe"` + log file. There's no `stdio: "inherit"` anywhere in the architect path; `cfcf review` is just a polling client to a server-side background spawn. So architect is in `UNATTENDED_ROLE_NAMES` always (no `autoReviewSpecs=true` gate); `cfcf doctor`'s harness check + the web UI's policy callout fire on architect+claude-code regardless of `autoReviewSpecs`; fresh `cfcf init` defaults architect to `codex` instead of `claude-code` (behaviour change for new installs only — existing user configs unaffected). Only **PA (`cfcf spec`)** and **HA (`cfcf help assistant`)** use `Bun.spawn(... { stdio: "inherit" })` and are within Anthropic's allowed-interactive scope.
 - **Structured pause actions** (item 6.25, shipped 2026-05-02): when a paused loop is resumed via `cfcf resume --action <…>`, the user picks one of `continue` / `finish_loop` / `stop_loop_now` / `refine_plan` / `consult_reflection`. `loop-stopped` is a workspace-history event type for user-initiated `stop_loop_now`.
 - **Three commits per iteration** when reflection runs: `cfcf iteration N dev (...)`, `cfcf iteration N judge (...)`, `cfcf iteration N reflect (<health>): <key_observation>`.
 - **Async execution**: iterate endpoint returns 202, CLI polls for status.
@@ -74,8 +77,25 @@ packages/
     iteration-loop.ts    # Main iteration loop controller + decision engine
                          #   (preparing -> dev -> judging -> reflecting? -> deciding)
     workspace-history.ts # history.json: review / iteration / reflection / document events
-    adapters/            # Agent adapter implementations (claude-code, codex)
+    adapters/            # Agent adapter implementations (claude-code, codex,
+                         #   opencode, claude-code-ollama, opencode-ollama —
+                         #   five total since item 6.28)
+    ollama-detection.ts  # detectOllama, listOllamaModels (item 6.28),
+                         #   refreshOllamaModelsInConfig (item 6.33 boot-time
+                         #   refresh + button-triggered re-detection)
+    orphan-reaper.ts     # findOrphanAgentProcesses + reapOrphans for boot-time
+                         #   reap of stale agents from a hard-crashed prior
+                         #   server PID (item 6.31, v0.21.0)
+    role-templates.ts    # Role-instruction-template versioning + promote-to-
+                         #   production layer (item 6.8). Two types: full
+                         #   (replace default) + augmented (append to live
+                         #   default; auto-recomposed on cf² upgrade via
+                         #   refreshAugmentedOverrides at server boot).
     templates/           # cfcf-docs/ file templates (17 entries incl. reflection + iteration-log + clio-guide)
+    templates.ts         # Template resolver: project-local override → user-global
+                         #   override (~/.cfcf/templates/) → embedded default.
+                         #   getEmbeddedTemplate(name) exposes the bundled
+                         #   default verbatim for role-templates.ts.
     clio/                # Clio memory layer (item 5.7)
       backend/
         types.ts           # MemoryBackend interface (swap point for future CerefoxRemote)
@@ -110,7 +130,7 @@ packages/
     commands/            # CLI command implementations
       init.ts            # First-run interactive setup (numbered agent picker, embedder
                          #   pick + inline HF download with progress bar, error classifier)
-      server.ts          # Server start/stop/status
+      server.ts          # Server start/stop/status/reap (item 6.31 added `reap`)
       workspace.ts       # Workspace init/list/show/delete (--project for Clio assignment)
       config.ts          # Global config show/edit
       run.ts             # Start iteration loop (agent) or single iteration (manual)
@@ -131,7 +151,9 @@ packages/
                          #   + cfcf memory alias
   web/src/
     App.tsx              # Root router (dashboard / workspace / server)
-    pages/               # Dashboard, WorkspaceDetail, ServerInfo
+    pages/               # Dashboard, WorkspaceDetail, ServerInfo, MemoryPage,
+                         #   HelpPage, AgentTemplatesPage (item 6.8 — /agents
+                         #   route, role-template management UI)
     components/          # Header, PhaseIndicator, WorkspaceHistory,
                          #   ArchitectReview, JudgeDetail, ReflectionDetail, …
     api.ts               # Client for all /api/* endpoints incl. /activity + /reflect
diff --git a/README.md b/README.md
index 9c1f286..c9221c2 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ cfcf can be driven from the CLI or from the web GUI served by the same Hono serv
   - **[Opencode](https://opencode.ai)** (sst.dev) — alternative to Codex; runs against your provider's API or via local ollama models
   - **[Ollama](https://ollama.com)** — optional, enables `claude-code-ollama` and `opencode-ollama` adapters that drive the agent CLI against locally-served models
 
-> ⚠️ **Anthropic policy + log-visibility heads-up.** `claude-code` (direct, talking to Anthropic's API/subscription) is **only recommended for interactive roles**: Product Architect (`cfcf spec`), Help Assistant (`cfcf help assistant`), and manually-invoked Solution Architect (`cfcf review`). Anthropic's third-party-harness policy restricts subscription OAuth to interactive use; cf²'s unattended dev / judge / reflection / documenter loop is the violation pattern the rule targets. **`claude-code-ollama` is policy-clean** (no Anthropic credential involved — local ollama serves the model) but shares Claude Code's `-p` stdout-buffering behaviour: log files stay silent during the entire run and dump the final response only when the agent exits. If you want live progress monitoring, use `codex` or the opencode adapters for unattended roles. See [`docs/guides/anthropic-policy.md`](docs/guides/anthropic-policy.md) for the full breakdown + the recommended adapter-per-role table. cf² surfaces warnings in `cfcf init` and the web UI Settings / workspace Config when these recommendations are violated; neither blocks the choice.
+> ⚠️ **Anthropic policy + log-visibility heads-up.** `claude-code` (direct, talking to Anthropic's API/subscription) is **only recommended for the two truly-interactive roles** that take over your shell via `stdio: "inherit"`: Product Architect (`cfcf spec`) and Help Assistant (`cfcf help assistant`). All other roles — dev, judge, reflection, documenter, **and Solution Architect** — are spawned headlessly with `claude -p` regardless of how they're invoked (including `cfcf review`, which polls a status endpoint while the server runs the architect in the background). Anthropic's third-party-harness policy restricts subscription OAuth to interactive use, so unattended `claude -p` under a personal subscription is the violation pattern. **`claude-code-ollama` is policy-clean** (no Anthropic credential involved — local ollama serves the model) but shares Claude Code's `-p` stdout-buffering behaviour: log files stay silent during the entire run and dump the final response only when the agent exits. If you want live progress monitoring, use `codex` or the opencode adapters for unattended roles. See [`docs/guides/anthropic-policy.md`](docs/guides/anthropic-policy.md) for the full breakdown + the recommended adapter-per-role table. cf² surfaces warnings in `cfcf init` and the web UI Settings / workspace Config when these recommendations are violated; neither blocks the choice.
 
 cfcf is distributed as a standard npm package (`@cerefox/codefactory`); `bun install -g` resolves the heavy native deps (transformers, ORT, sharp) the same way every JS-ecosystem CLI does. A per-platform `@cerefox/codefactory-native-<platform>` package provides the pinned libsqlite3 + sqlite-vec libs. See [`docs/guides/installing.md`](docs/guides/installing.md) for the install one-liner + local / file-URL install paths.
 
diff --git a/docs/README.md b/docs/README.md
index 82fb178..fa70dc1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,24 +8,34 @@ docs/
   decisions-log.md      Working docs: failed experiments, non-obvious choices
 
   design/               Specs and architecture (stabilize over time)
-    cfcf-requirements-vision.md   What cfcf is and why
-    cfcf-stack.md                 Technology choices
-    technical-design.md           How components fit together
-    agent-process-and-context.md  Iteration process, file formats, signal specs
+    cfcf-requirements-vision.md     What cfcf is and why
+    cfcf-stack.md                   Technology choices
+    technical-design.md             How components fit together
+    agent-process-and-context.md    Iteration process, file formats, signal specs
+    clio-memory-layer.md            Clio architecture (item 5.7+)
+    clio-memory-web-ui.md           Clio web UI design (item 6.18)
+    scheduler-and-update-notification.md  JobScheduler primitive + update banner (item 6.20)
+    role-template-management.md     Role-template versioning + promote-to-production (item 6.8)
+    skills-repository.md            Skills system design (item 6.27)
 
   api/                  API reference (grows with every endpoint)
     server-api.md       Server REST API endpoints
 
-  research/             Ideas, brainstorms, explorations
+  research/             Ideas, brainstorms, explorations (promoted to design/ when committed)
     reflection-role-and-iterative-planning.md   Item 5.6 design (shipped in v0.6.0 + v0.7.0)
+    product-architect-design.md                  Item 5.14 design (shipped)
+    structured-pause-actions-design.md           Item 6.25 design (shipped)
+    …                                            (other historical research files)
 
   guides/               User-facing how-tos
-    manual.md           User-manual hub -- 3-min getting started + concepts + pointers
-    workflow.md         Full workflow walkthrough (canonical for "run a loop end-to-end")
-    cli-usage.md        CLI command reference (verb-by-verb)
-    clio-quickstart.md  Clio (cross-workspace memory) onboarding
-    installing.md       Install + upgrade + uninstall
-    troubleshooting.md  Common issues + fixes
+    manual.md             User-manual hub — 3-min getting started + concepts + pointers
+    workflow.md           Full workflow walkthrough (canonical for "run a loop end-to-end")
+    cli-usage.md          CLI command reference (verb-by-verb)
+    clio-quickstart.md    Clio (cross-workspace memory) onboarding
+    installing.md         Install + upgrade + uninstall
+    troubleshooting.md    Common issues + fixes
+    anthropic-policy.md   Anthropic third-party-harness policy + adapter strategy (item 6.28+6.30)
+    product-architect.md  Product Architect interactive role (item 5.14)
 ```
 
 ## What Goes Where
diff --git a/docs/api/server-api.md b/docs/api/server-api.md
index 4152015..e30eee5 100644
--- a/docs/api/server-api.md
+++ b/docs/api/server-api.md
@@ -1367,6 +1367,141 @@ Rewire a workspace's Clio Project assignment. Backs the `cfcf workspace set --pr
 
 ---
 
+## Agent Models (item 6.26 + 6.33)
+
+### GET /api/agents/models
+
+Returns the resolved per-adapter model registry. Each entry is a list of model names the picker should offer for that adapter. For `*-ollama` adapters, the list comes from `availableOllamaModels` in the global config (last refreshed by `cfcf init` or by the boot-time / button-triggered refresh below). For seed-sourced adapters (`claude-code`, `codex`), the list is the user override on `CfcfGlobalConfig.agentModels[<adapter>]` if set + non-empty, otherwise the bundled seed in `packages/core/src/adapters/seed-models.ts`.
+
+**Response:** `200 OK`
+```json
+{
+  "adapters": {
+    "claude-code": ["sonnet", "opus", "haiku"],
+    "codex": ["gpt-5-codex", "gpt-5", "o3"],
+    "claude-code-ollama": ["gemma4:31b", "qwen3-coder:latest"],
+    "...": []
+  },
+  "seed": { "claude-code": ["sonnet", "opus", "haiku"], "...": [] }
+}
+```
+
+The `seed` field is surfaced alongside so the Settings → Model registry editor can show users what they'd revert to if they cleared their override.
+
+### POST /api/agents/refresh-ollama-models (item 6.33)
+
+On-demand re-detection of locally-pulled ollama models. Runs `ollama list` live, persists the result to `availableOllamaModels` in the global config if the live list differs from what's saved (order-insensitive comparison, since `ollama list` reorders by mtime). After the call, re-fetch `/api/agents/models` to pick up the new list in the per-adapter resolved registry.
+
+Always returns `200 OK` — "ollama not installed" is surfaced as a hint in the body, not an HTTP failure.
+
+**Response:** `200 OK`
+```json
+{ "models": ["gemma4:31b", "qwen3-coder:latest"], "updated": false }
+```
+
+Or, when ollama isn't installed:
+```json
+{ "models": [], "updated": false, "error": "ollama not detected" }
+```
+
+`updated: true` means the saved list differed from the live list and was rewritten.
+
+The boot-time auto-refresh in `start.ts` calls the same underlying helper (`refreshOllamaModelsInConfig` from `@cfcf/core`) so this endpoint and `cfcf server start` share their behaviour.
+
+---
+
+## Role-Template Management (item 6.8)
+
+Versioning + promote-to-production layer for the role-instruction templates each agent reads (`cfcf-architect-instructions.md`, `process.md` for the dev role, `cfcf-judge-instructions.md`, `cfcf-reflection-instructions.md`, `cfcf-documenter-instructions.md`). Two version types:
+
+- **`type: "full"`** — body REPLACES the bundled default at promote time. Maximum flexibility; doesn't auto-pick-up cf² upgrades. Carries a `cfcfVersion` field stamped at save time so the UI can show a "Forked from cf² vX.Y.Z" badge.
+- **`type: "augmented"`** — body is APPENDED to the live bundled default at promote time AND every server boot (`refreshAugmentedOverrides()` in core, called from `start.ts`). The bundled default is read live and never duplicated on disk, so the user's extension automatically rides along when cf² ships a new template.
+
+The user-global override path `~/.cfcf/templates/<name>` (read by `getTemplate()`) is what the runtime sees. Promote writes the (composed-for-augmented) content there; revert-to-default deletes it.
+
+### GET /api/role-templates
+
+List managed templates with summary info. Tab order matches the natural agent execution sequence (architect → dev → judge → reflection → documenter).
+
+**Response:** `200 OK`
+```json
+{
+  "templates": [
+    { "name": "cfcf-architect-instructions.md", "displayName": "Solution Architect", "currentVersionId": "default", "versionCount": 0 },
+    { "name": "process.md", "displayName": "Developer", "currentVersionId": "v_abc123", "versionCount": 2 }
+  ]
+}
+```
+
+### GET /api/role-templates/:name
+
+Full state for one template.
+
+**Response:** `200 OK`
+```json
+{
+  "name": "cfcf-judge-instructions.md",
+  "displayName": "Judge",
+  "defaultContent": "...",
+  "currentVersionId": "v_abc123",
+  "currentContent": "...",
+  "versions": [
+    {
+      "id": "v_abc123",
+      "label": "stricter judge",
+      "savedAt": "2026-05-09T12:00:00Z",
+      "contentHash": "abc123def456",
+      "type": "full",
+      "cfcfVersion": "0.21.0"
+    }
+  ]
+}
+```
+
+For an augmented promoted version, `currentContent` is the **composed** text (matches what's in the override file).
+
+### GET /api/role-templates/:name/versions/:versionId
+
+Returns the body of a specific version. For `versionId === "default"` returns the bundled default. For an augmented version returns the **extension only** (not the composed text). 404 on unknown name or version.
+
+**Response:** `200 OK` -- `{ "content": "..." }`
+
+### POST /api/role-templates/:name/versions
+
+Save a new version.
+
+**Request body:** `{ "label": "string", "content": "string", "type"?: "full" | "augmented" }`
+
+`type` defaults to `"full"` when omitted. Invalid types return 400.
+
+**Response:** `201 Created` -- the new `TemplateVersion` object.
+
+### PUT /api/role-templates/:name/versions/:versionId
+
+Update an existing version's label and/or content. If the version is the currently-promoted one, the override file is refreshed automatically (with re-composition for augmented).
+
+**Request body:** `{ "label"?: "string", "content"?: "string" }` (at least one required).
+
+**Response:** `200 OK` -- the updated `TemplateVersion` object. 400 if attempting to update `versionId === "default"` (read-only).
+
+### DELETE /api/role-templates/:name/versions/:versionId
+
+Delete a saved version. Cannot delete `"default"`. If the deleted version was the promoted one, automatically reverts to default (override file deleted).
+
+**Response:** `200 OK` -- `{ "deleted": true, "template": <refreshed full state> }`.
+
+### POST /api/role-templates/:name/promote
+
+Promote a version (or `"default"`) to production.
+
+**Request body:** `{ "versionId": "string" }`
+
+For `"default"` the override file is deleted (revert). For a saved version, the body is composed (per its `type`) and written to the override file.
+
+**Response:** `200 OK` -- the refreshed `RoleTemplateFull` object so the UI can update local state without an extra GET.
+
+---
+
 ## Server Lifecycle
 
 ### POST /api/shutdown
diff --git a/docs/guides/cli-usage.md b/docs/guides/cli-usage.md
index e73a48b..98259d6 100644
--- a/docs/guides/cli-usage.md
+++ b/docs/guides/cli-usage.md
@@ -26,12 +26,13 @@ What it does:
 1. Scans for installed agents (Claude Code, Codex CLI) and reports what it finds
 2. Verifies git is available
 3. Asks you to choose agents for **seven roles**: five iteration roles (dev, judge, architect, reflection, documenter) plus two interactive roles (Product Architect, Help Assistant). Each prompt asks for both adapter and model.
-4. Asks for model selection per role via a numbered picker driven by each adapter's bundled model registry (e.g. `opus` / `sonnet` / `haiku` for Claude Code; `gpt-5-codex` / `gpt-5` / `o3` for Codex). Pick `0` for "(use adapter default)". Edit the per-adapter model list later from the web UI's **Settings → Model registry** section; the CLI picker reads the augmented list on each subsequent run. For the `*-ollama` adapters (item 6.28), the model list is sourced from `ollama list` rather than the cfcf seed registry; for the standalone `opencode` adapter the picker shows just the "(adapter default)" + custom-name options because opencode's provider auth (and therefore its valid model list) lives outside cfcf's view.
-5. **Detects ollama** (item 6.28) and surfaces the count of locally-pulled models. When ollama is present alongside `claude` and/or `opencode`, the agent picker for each role conditionally includes `claude-code-ollama` and `opencode-ollama` so you can route unattended roles through a local model server.
-6. **Surfaces two related warnings for the Claude Code paths** (item 6.28) when picking adapters for unattended roles (dev / judge / reflection / documenter, plus architect when `autoReviewSpecs=true`):
+4. Asks for model selection per role via a numbered picker driven by each adapter's bundled model registry (e.g. `opus` / `sonnet` / `haiku` for Claude Code; `gpt-5-codex` / `gpt-5` / `o3` for Codex). Pick `0` for "(use adapter default)" — note: NOT offered for `claude-code-ollama` / `opencode-ollama`, which require an explicit `--model` flag (item 6.33). Edit the per-adapter model list later from the web UI's **Settings → Model registry** section; the CLI picker reads the augmented list on each subsequent run. For the `*-ollama` adapters (item 6.28), the model list is sourced from `ollama list` rather than the cfcf seed registry; for the standalone `opencode` adapter the picker shows just the "(adapter default)" + custom-name options because opencode's provider auth (and therefore its valid model list) lives outside cfcf's view.
+5. **Detects ollama** (item 6.28) and surfaces the count of locally-pulled models. When ollama is present alongside `claude` and/or `opencode`, the agent picker for each role conditionally includes `claude-code-ollama` and `opencode-ollama` so you can route unattended roles through a local model server. After init, ollama models are auto-refreshed on every `cfcf server start` (item 6.33) — newly-pulled models propagate to role-picker dropdowns without re-running `cfcf init`. There's also a "Refresh ollama models" button in the web UI Agent-roles section (Settings + workspace Config) for the impatient between-restarts case.
+6. **Surfaces three related warnings for the Claude Code paths** (items 6.28 + 6.30) when picking adapters for unattended roles (dev / judge / reflection / documenter / architect — note: architect counts as unattended for ALL invocation paths, including manual `cfcf review`, since its spawn pipeline is headless `claude -p` regardless of how it's invoked):
    - **Yellow / policy-grade**: fires when `claude-code` (direct, talking to Anthropic's API) is picked. Anthropic's third-party-harness policy restricts subscription OAuth to interactive use; the unattended cf² loop is the violation pattern. Recommendation: switch to `codex`, `claude-code-ollama`, `opencode`, or `opencode-ollama`.
+   - **Blue / API-parse-error note** (item 6.30, May 2026): fires when `claude-code-ollama` is picked. Some non-coder-tuned local models (notably `gemma4:31b`) produce tool-use / tool-result content blocks that Anthropic's strict Messages API parser rejects with `API Error: Content block not found`. If you hit this, switch to `opencode-ollama` for the same model — its OpenAI-compatible endpoint is more tolerant.
    - **Blue / log-visibility note**: fires when `claude-code-ollama` is picked. The ollama path is policy-clean, but `claude -p` still buffers stdout for the entire run — log files stay silent until the agent exits, then dump the final response. If you want live progress monitoring during long iterations, prefer `codex` (streams natively) or the opencode adapters.
-   - Both warnings are informational; neither blocks the save. PA / HA / manually-invoked SA on any Claude variant do NOT trigger either warning (interactive scope; live progress visible in the user's TUI). See `cfcf help anthropic-policy` for the full breakdown.
+   - All three warnings are informational; neither blocks the save. Only PA and HA on Claude variants do NOT trigger any warning (they take over your shell via `stdio: "inherit"` — the only paths actually within Anthropic's allowed-interactive scope). See `cfcf help anthropic-policy` for the full breakdown.
 5. Asks for default iteration limits (max iterations, pause cadence) and the reflection safeguard ceiling (`reflectSafeguardAfter`, default `3` -- the maximum consecutive iterations the judge may skip reflection before cfcf forces it)
 6. Asks for the pre-loop review + post-SUCCESS documenter flags (item 5.1):
    - `autoReviewSpecs` (default `false`) -- if `true`, Start Loop first runs the Solution Architect and gates on its readiness signal
@@ -92,7 +93,38 @@ The same information (plus the full global config) is available in the
 web GUI at `http://localhost:7233/#/server`. Since v0.7.3 that page is
 a full editor -- wire-compatible with `cfcf config edit` via the same
 `PUT /api/config` endpoint. Reach it from the **Settings** link in the
-top bar.
+top bar. The web UI's full top-level navigation:
+
+- **Workspaces** — dashboard + per-workspace iteration history, log viewer, config tab.
+- **Memory** — Clio (cross-workspace memory): search, browse, ingest, audit, projects, trash.
+- **Agents** (item 6.8) — per-role instruction-template editor with versioning + promote-to-production. One sub-tab per role; the bundled cf² default is always selectable (read-only). Save edits as either a `full` version (replaces the default; doesn't auto-upgrade) or an `augmented` version (extension-only on top of the live default; auto-upgrades when cf² ships a new template).
+- **Settings** — global config (per-role agent + model, ollama-models refresh button, model registry, notifications).
+- **Help** — in-shell version of the documentation guides.
+
+### `cfcf server reap` (item 6.31, v0.21.0)
+
+Detect + interactively kill orphan agent processes left behind by a
+previous server PID — typically when the server died via SIGKILL or
+an OS panic, bypassing the SIGINT/SIGTERM signal handlers that
+normally clean up child agents on graceful shutdown. Pure system
+call — does NOT require the cfcf server to be running.
+
+```bash
+cfcf server reap                 # interactive: lists candidates, asks y/N before killing
+cfcf server reap --yes           # non-interactive: kill anything detected
+```
+
+The matcher is conservative — three conjoined filters (PPID==1 +
+same effective user + cfcf-spawned command shape). Empty case:
+
+```
+No zombie agent processes detected.
+```
+
+Boot-time auto-reap runs the same logic on every `cfcf server start`,
+so manual reaping is only needed if you don't want to bounce the
+server. See [`troubleshooting.md`](troubleshooting.md) → "Loop appears
+hung / silent" if you suspect orphans.
 
 ---
 
diff --git a/docs/guides/installing.md b/docs/guides/installing.md
index cd896f2..c0b374b 100644
--- a/docs/guides/installing.md
+++ b/docs/guides/installing.md
@@ -19,8 +19,8 @@ cf² is published on npmjs.com as [`@cerefox/codefactory`](https://www.npmjs.com
 
 cf² needs **at least one** AI coding agent on PATH; `cfcf init` only offers adapters whose underlying CLI it can detect. Per the policy + log-visibility note above, **`claude-code` alone is not a complete setup** if you plan to run unattended loops — those need a non-Anthropic-OAuth path. **Recommended minimum** for typical use:
 
-- **`claude-code`** (Anthropic) — for the interactive roles (PA / HA / manual SA). Optional if you don't use those.
-- **One of**: `codex` / `opencode` / `ollama` — for the unattended roles (dev / judge / reflection / documenter / auto-architect).
+- **`claude-code`** (Anthropic) — for the interactive roles (PA / HA). Optional if you don't use those.
+- **One of**: `codex` / `opencode` / `ollama` — for the unattended roles (dev / judge / reflection / documenter / architect — note: architect is always unattended in cf², including via manual `cfcf review`, since the architect spawn pipeline is headless `claude -p` regardless of how it's invoked).
 
 Mix as you like; cf² surfaces a warning at `cfcf init` if your unattended-role adapter choices conflict with the policy. The full role-to-adapter mapping table lives in [`anthropic-policy.md`](anthropic-policy.md).
 
@@ -32,7 +32,7 @@ claude --version    # confirm install
 claude              # first run prompts for Anthropic OAuth login (browser)
 ```
 
-Recommended for: **Product Architect (`cfcf spec`)**, **Help Assistant (`cfcf help assistant`)**, **manually-invoked Solution Architect (`cfcf review`)** — the interactive roles where Claude Code's TUI takes over your shell. Anthropic's third-party-harness policy restricts subscription OAuth to interactive use, so cf²'s automated dev / judge / reflection / documenter loop should NOT use direct `claude-code` (use `claude-code-ollama` or another adapter instead — see below).
+Recommended for: **Product Architect (`cfcf spec`)** and **Help Assistant (`cfcf help assistant`)** — the two roles where Claude Code's TUI literally takes over your shell (via `stdio: "inherit"`). Anthropic's third-party-harness policy restricts subscription OAuth to interactive use, so cf²'s headless `claude -p` paths — dev, judge, reflection, documenter, and Solution Architect (yes, even via `cfcf review`, which polls a status endpoint while the server runs the architect in the background) — should NOT use direct `claude-code` (use `claude-code-ollama` or another adapter instead — see below).
 
 ### Codex CLI (OpenAI)
 
diff --git a/docs/guides/manual.md b/docs/guides/manual.md
index 7daf55e..0ea3284 100644
--- a/docs/guides/manual.md
+++ b/docs/guides/manual.md
@@ -106,7 +106,7 @@ A grouping of workspaces that share knowledge. Clio is cfcf's persistent memory
 The web UI has five top-level tabs:
 - **Workspaces** — dashboard + per-workspace iteration history, log viewer, config tab.
 - **Memory** — Clio cross-workspace memory: search, browse, ingest, audit, projects.
-- **Agents** (item 6.8) — per-role instruction template editor with versioning + promote-to-production. Each role has a built-in default (always available) and any number of saved versions you create. Promote a version to make cf² use it on the next agent run; revert to default to fall back to the cf²-shipped template.
+- **Agents** (item 6.8) — per-role instruction template editor with versioning + promote-to-production. One sub-tab per role (Solution Architect → Developer → Judge → Reflection → Documenter, matching the natural agent execution sequence). Each role has a built-in default (always available, read-only) and any number of saved versions. Two version types: **`full`** replaces the default entirely (max flexibility, doesn't auto-upgrade — UI shows a "Forked from cf² vX.Y.Z" badge); **`augmented`** appends to the live default (extension-only on disk; auto-recomposes when cf² ships a new template, so the upgrade is hands-off). Promote a version to make cf² use it on the next agent run; revert to default to fall back to the cf²-shipped template.
 - **Settings** — global config (per-role agent + model, ollama models, notifications, model registry).
 - **Help** — in-shell version of these guides.
 
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 553523a..8ace282 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -161,7 +161,7 @@ Re-run `cfcf init --force` afterwards so cfcf picks up the new ollama snapshot.
 
 ### Anthropic harness-policy warning during `cfcf init`
 
-The warning fires when you've picked `claude-code` (direct, talking to Anthropic's API/subscription) for an unattended role (dev / judge / reflection / documenter, plus architect when `autoReviewSpecs=true`). It's **informational, not blocking** — your config saves. To clear the warning, re-run `cfcf init --force` or `cfcf config edit` and pick `codex` / `claude-code-ollama` / `opencode-ollama` / `opencode` for those roles instead. PA / HA / manually-invoked SA on `claude-code` do NOT trigger the warning — they're within Anthropic's allowed-interactive scope. Full background: [`anthropic-policy.md`](anthropic-policy.md).
+The warning fires when you've picked `claude-code` (direct, talking to Anthropic's API/subscription) for an unattended role (dev / judge / reflection / documenter / architect — note: architect counts as unattended in all three loop paths AND for manual `cfcf review`, since the architect spawn pipeline is always headless `claude -p` regardless of how it's invoked). It's **informational, not blocking** — your config saves. To clear the warning, re-run `cfcf init --force` or `cfcf config edit` and pick `codex` / `claude-code-ollama` / `opencode-ollama` / `opencode` for those roles instead. Only **PA and HA** on `claude-code` skip the warning — they're the two roles that take over your shell via `stdio: "inherit"`, the only paths actually within Anthropic's allowed-interactive scope. Full background: [`anthropic-policy.md`](anthropic-policy.md).
 
 ### Log-visibility note during `cfcf init` (claude-code-ollama on unattended role)
 
diff --git a/docs/guides/workflow.md b/docs/guides/workflow.md
index 81ab7b6..9210ba7 100644
--- a/docs/guides/workflow.md
+++ b/docs/guides/workflow.md
@@ -70,8 +70,8 @@ Each role can use a different agent and model. Reflection is the strongest-conte
 
 **Adapter choice — Anthropic policy + log visibility**:
 
-- **Interactive roles** (`Product Architect`, `Help Assistant`, manually-invoked `Solution Architect` via `cfcf review`): **`claude-code` is the recommended choice.** TUI takes over your shell; you watch progress live in the terminal. No policy concern (Anthropic permits interactive subscription use) and no log-visibility concern.
-- **Unattended roles** (dev / judge / reflection / documenter / auto-architect when `autoReviewSpecs=true`): the loop spawns the agent CLI without you driving — that's where the trade-offs matter:
+- **Interactive roles** (`Product Architect`, `Help Assistant`): **`claude-code` is the recommended choice.** These are the only two roles that take over your shell via `Bun.spawn(... { stdio: "inherit" })` — you watch progress live in the terminal. No policy concern (Anthropic permits interactive subscription use) and no log-visibility concern.
+- **Unattended roles** (dev / judge / reflection / documenter / **architect**): the loop — and `cfcf review`, since it just polls a status endpoint while the server runs the architect headlessly in the background — spawns the agent CLI with `claude -p` (or equivalent) and pipes stdout to a log file. No TUI takeover anywhere. That's where the trade-offs matter:
     - **`codex`** is the recommended unattended default — streams progress live to the log file (visible during the run), policy-clean (OpenAI's API-key path explicitly endorses CLI automation).
     - **`opencode-ollama` / `opencode`** — also stream live, also policy-clean.
     - **`claude-code-ollama`** — policy-clean (no Anthropic credential involved; local ollama serves the model), but shares Claude Code's `-p` stdout-buffering behaviour: the log file stays silent during the run and only dumps the final response when the agent exits. Pick this if you specifically prefer Claude's tool-call format / instruction-file conventions and don't need live monitoring.

From 4351325c60a072da8681e1c01c48a069f4bde851 Mon Sep 17 00:00:00 2001
From: Fotis Stamatelopoulos <f.stamatelopoulos@ebs.gr>
Date: Fri, 8 May 2026 23:38:22 -0700
Subject: [PATCH 8/8] fix(6.8): match FullEditor textarea height to
 augmented-mode standard panel (25vh)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The single-textarea FullEditor was 60vh tall while the augmented-mode
"cf² standard template (read-only)" panel was 25vh. Switching between
the two views (e.g. Default tab → an augmented-version tab) felt
jarring because the bundled-default content rendered at noticeably
different heights.

Aligned FullEditor to 25vh as well. The textarea keeps `resize:
vertical` so users editing a long full version can drag it taller —
just lowers the floor height from 60vh to 25vh for consistency.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/web/src/pages/AgentTemplates.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/web/src/pages/AgentTemplates.tsx b/packages/web/src/pages/AgentTemplates.tsx
index 71953ee..af22437 100644
--- a/packages/web/src/pages/AgentTemplates.tsx
+++ b/packages/web/src/pages/AgentTemplates.tsx
@@ -696,7 +696,10 @@ function FullEditor({
         spellCheck={false}
         style={{
           width: "100%",
-          minHeight: "60vh",
+          // Match the augmented-mode "cf² standard template (read-only)"
+          // panel height (~25vh). Users can drag taller via the
+          // resize handle when editing a full template.
+          minHeight: "25vh",
           fontFamily: "var(--font-mono, monospace)",
           fontSize: "var(--text-sm)",
           padding: "0.75rem",