agent-templates 0.4.5 → 0.4.8

package/ADOPTING.md

@@ -39,6 +39,17 @@ Preconditions: git repo + remote, authenticated tracker CLI (`gh auth login` / `
 
 Same `adopt.mjs` run — skip-existing protects your files. The differences:
 
+**Updating to a newer catalog version:** a plain re-run only adds files that don't exist yet; it will not update a file the previous version already installed. To pull the latest, re-run with `--force` (it overwrites, including `.claude/settings.json`), so commit first and review the diff to re-apply local customizations:
+
+```
+git add -A && git commit -m "checkpoint before agent-templates update"
+npx agent-templates@latest adopt three-agent-architect-builder-reviewer . --force
+git diff
+```
+
+`--force` refreshes the scaffold and tracker/settings files, but not the `CLAUDE.md` pipeline section or `.gitattributes` (both marker-guarded) — re-apply any pipeline-rule changes from a release by hand.
+
+
 - `CLAUDE.md` gets the snippet **appended**: read the merged result once and resolve contradictions with your existing rules (the pipeline rules assume no agent judges its own work).
 - An existing `.claude/settings.json` is kept; merge the scaffold's `hooks.PreToolUse` (write guard) and `permissions.allow` entries by hand.
 - Formalize `docs/PRD.md` for the area you will pipeline first — it can cover a single module; you do not need to spec the whole codebase to start.

package/CLAUDE.md

@@ -116,7 +116,7 @@ Upstream docs convention assumed by patterns (exemplar: `fx-eye-tracking`): `doc
 
 1. **Issues are the decision record; commits are only the change record.** Every unit of work starts as a GitHub issue stating what + why (use the universal templates — work items follow `task`/`bug-report`, records follow `decision-record`). The work lands via a PR referencing it (`Closes #N`), written against `.github/PULL_REQUEST_TEMPLATE.md` (byte-synced from `templates/tracker/github/`). **No direct merges to main.** Bootstrap exception: the rounds merged on 2026-07-17 before this rule existed are backfilled as `decision-record` issues #1–#4.
 2. **Self-hosted nightly sweep.** This repo runs the pattern's own `/nightly-issues`: other projects file pattern-tweak requests here (templates in `.github/ISSUE_TEMPLATE/`), and the sweep triages — and where fixable, fixes — them overnight. The machinery at `.claude/` (four agents, two workflows, `nightly-issues` + `verify-delivery` commands) is a **byte-synced copy of the scaffold**, enforced by the E2E integrity suite: change the scaffold first, then re-copy.
-3. **This repo's test suite** is `node testbed/e2e/run-e2e.mjs` — the Builder/Reviewer run it exactly like any project's tests.
+3. **This repo's test suite** is `node testbed/e2e/run-e2e.mjs` — the Builder/Reviewer run it exactly like any project's tests. **CI enforces it server-side**: `.github/workflows/test.yml` runs the suite on every PR and push to `main` (ubuntu + windows × Node 18/20). Releases publish from a `v*` tag via `.github/workflows/publish.yml` (E2E gate → tag-matches-version check → `npm publish` with the `NPM_TOKEN` secret) — see README § "CI & releasing".
 4. The scaffold's main-session write guard is **not installed here** — interactive doc-editing with the maintainer is this repo's norm. Revisit if orchestrator role leakage appears in this repo's own pipeline runs.
 5. Labels in use: `decision-record` · `triage:invalid` · `nightly:escalated` · `needs-human`.
 

package/README.md

@@ -1,6 +1,6 @@
 # agent-templates
 
-[![npm](https://img.shields.io/npm/v/agent-templates)](https://www.npmjs.com/package/agent-templates) · **[Catalog site →](https://ruihang2017.github.io/agent-templates/)**
+[![npm](https://img.shields.io/npm/v/agent-templates)](https://www.npmjs.com/package/agent-templates) · [![test](https://github.com/Ruihang2017/agent-templates/actions/workflows/test.yml/badge.svg)](https://github.com/Ruihang2017/agent-templates/actions/workflows/test.yml) · **[Catalog site →](https://ruihang2017.github.io/agent-templates/)**
 
 Catalog of reusable multi-agent development architecture patterns. Each entry is a design write-up plus drop-in scaffolding (subagent definitions, slash commands, CLAUDE.md snippets) so a new project reuses a proven pattern instead of redesigning one.
 
@@ -18,6 +18,18 @@ npx agent-templates@latest adopt three-agent-architect-builder-reviewer .
 3. **Gate 1** — review the breakdown, then **`/start-milestone docs/prd/00-<module> supervised`**: tickets publish as tracker issues; each ticket runs plan → build → fresh-context review to CLEAR, pausing for your merge.
 4. When it holds, flip to `autonomous` — whole milestones run hands-off. **Gate 2** = your smoke test at the end. Full guide: [ADOPTING.md](ADOPTING.md).
 
+### Updating an existing install
+
+Re-run adopt with `--force` to pull the latest catalog version. A plain re-run only adds new files (existing ones are skipped); `--force` overwrites changed ones. Because it overwrites (including `.claude/settings.json`), commit first, then review the diff and re-apply any local customizations:
+
+```
+git add -A && git commit -m "checkpoint before agent-templates update"
+npx agent-templates@latest adopt three-agent-architect-builder-reviewer . --force
+git diff        # re-apply your customizations (esp. .claude/settings.json)
+```
+
+`--force` refreshes the scaffold and tracker/settings files. It does **not** rewrite the `CLAUDE.md` pipeline section or `.gitattributes` (both marker-guarded, so a re-run reports them as already present) — if a release changes the pipeline rules in the snippet, re-apply those by hand.
+
 | Pattern | Status | As of | Summary |
 |---|---|---|---|
 | [three-agent-architect-builder-reviewer](patterns/three-agent-architect-builder-reviewer/README.md) | trialed | 2026-07-17 | Architect plans → Builder implements → independent Reviewer (fresh context, different model tier) clears or bounces; `/start-milestone` runs a whole module autonomously |
@@ -42,6 +54,18 @@ Installed into your project by `adopt`; run them in Claude Code. Full list is ge
 - Adding a pattern: start from [templates/pattern-README.template.md](templates/pattern-README.template.md), process in [CLAUDE.md](CLAUDE.md) § "Adding a new pattern"
 - E2E testing for the pattern chain: [testbed/README.md](testbed/README.md) — `node testbed/e2e/run-e2e.mjs` is the merge gate for scaffold changes
 
+## CI & releasing
+
+CI ([`.github/workflows/test.yml`](.github/workflows/test.yml)) runs the E2E suite on every PR and push to `main`, across ubuntu + windows × Node 18/20 — the merge gate is enforced server-side and cross-platform.
+
+Releases publish from a version tag ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)): bump `package.json`, then
+
+```
+git tag vX.Y.Z && git push origin vX.Y.Z   # X.Y.Z = the version in package.json
+```
+
+CI re-runs the E2E gate, checks the tag matches `package.json`, and publishes to npm. **One-time setup:** add an `NPM_TOKEN` repo secret (Settings → Secrets and variables → Actions).
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Carve-out: files installed **into your project** by `adopt.mjs` (the scaffold, templates, and anything generated from them) may be used in your projects without attribution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-templates",
-  "version": "0.4.5",
+  "version": "0.4.8",
   "description": "Catalog of multi-agent development architecture patterns - design write-ups plus drop-in scaffolding (agents, slash commands, workflows, templates).",
   "license": "MIT",
   "author": "Horace Hou",

package/patterns/three-agent-architect-builder-reviewer/README.md

@@ -4,8 +4,8 @@
 |---|---|
 | **Pattern name** | `three-agent-architect-builder-reviewer` |
 | **Status** | `trialed` — signed off as the team standard 2026-07-17; promotes to `adopted` after its first real-ticket run (CLAUDE.md promotion rule) |
-| **As-of date** | 2026-07-17 |
-| **Expiry trigger** | First successor release to any listed model, or 2027-01-17 (+6 months), whichever comes first |
+| **As-of date** | 2026-07-21 (model/effort revised; §7) |
+| **Expiry trigger** | First successor release to any listed model, or 2027-01-21 (+6 months), whichever comes first |
 | **Sign-off** | Horace Hou (repo maintainer), 2026-07-17 |
 
 One ticket flows through three agents in sequence: **Architect** plans → **Builder** implements → **Reviewer** (fresh context, different model tier) clears or bounces. No agent judges its own work.
@@ -40,16 +40,16 @@ The Reviewer is **deliberately a different model tier from the Builder** so the
 
 Related in-house variant: fx-eye-tracking's `planner` / `generator` / `evaluator` harness — same independence principle, heavier machinery (spec decomposition, file-scope parallelism, sprint contracts, tracker governance). That harness runs a whole project; this pattern runs one ticket.
 
-## 3. Model + effort assignment (as of 2026-07-17)
+## 3. Model + effort assignment (as of 2026-07-21)
 
 | Role | Model | Effort | Reasoning | Source labels |
 |---|---|---|---|---|
-| Architect | Claude Sonnet 5 | `xhigh` | Planning is terminal/tool-call-heavy work, where Sonnet 5 benchmarks strongest in the lineup: Terminal-Bench 2.1 **80.4** vs Opus 4.8's **74.6**. `xhigh` is Anthropic's documented recommendation for agentic exploration workloads. | Benchmark: `[third-party]` (link not captured — attach at first re-verification). Effort guidance: `[official]` |
+| Architect | Claude Opus 4.8 | `max` | The plan is the pattern's cold-start contract: Builder and Reviewer consume it in fresh contexts, so anything the plan leaves vague drifts downstream. Field runs showed `sonnet-5 @ xhigh` plans coming out too general — the highest-leverage stage under-invested. Moved to the top model at `max`: token budget is explicitly not the constraint here, and plan depth pays for itself in reduced downstream drift and bounces. Sharing the Builder's model at a higher effort is fine — the independence constraint applies only to the Reviewer. | Plan-vagueness observation: `[internal]` (maintainer, 2026-07-21, across the recent autonomous runs). Investment choice: `[team-policy]` |
 | Builder | Claude Opus 4.8 | `xhigh` | Anthropic's official guidance is to start at `xhigh` for coding and agentic use cases. Opus 4.8 leads Sonnet 5 on the hardest agentic-coding benchmark: SWE-bench Pro **69.2** vs **63.2**. One effort setting for all tickets — no per-ticket downgrades; team priority is predictable delivery over token cost. | Benchmark: `[vendor-benchmark]` (Anthropic-reported). Effort guidance: `[official]`. No-downgrade rule: `[team-policy]` |
-| Reviewer | Claude Fable 5 | `max` | The Reviewer is the last quality gate before merge. Fable 5 has the largest capability margin on the hardest problems (SWE-bench Pro **~80.3**), and catching missed edge cases is where that margin pays off most. `max` because token cost is explicitly not the constraint at this gate. | Benchmark: `[unverified]` — recorded as "reported" without a named source; treat as unverified until linked. `max` choice: `[team-policy]` |
-| Triage (nightly only) | Claude Sonnet 5 | `xhigh` | Classification + ticket synthesis is planning-shaped work; profile inherited from the Architect row rather than separately derived. | `[team-policy]` — no separate benchmark basis |
+| Reviewer | Claude Fable 5 | `xhigh` | The Reviewer is the last quality gate before merge, and Fable 5 has the largest capability margin on the hardest problems (SWE-bench Pro **~80.3**) — at this gate that raw margin, not effort headroom, is what catches edge cases. Dropped from `max` to `xhigh`: `max` carries a documented overthinking/latency risk (§4), and with the stronger Architect producing tighter plans the Reviewer's burden drops. | Benchmark: `[unverified]` — recorded as "reported" without a named source; treat as unverified until linked. Effort choice: `[team-policy]` (+ §4 `max`-overthinking pitfall) |
+| Triage (nightly only) | Claude Sonnet 5 | `xhigh` | Classification + ticket synthesis is planning-shaped work; profile derived separately from the Architect row (nightly triage does not need the Architect's full planning tier). | `[team-policy]` — no separate benchmark basis |
 
-Figures are transcribed from the team-finalized specification dated 2026-07-17 (§7). Do not re-derive or silently alter them; update only via the process in the repo CLAUDE.md (new as-of date + provenance entry in the same commit).
+Figures dated 2026-07-17 are from the team-finalized specification (§7); the Architect and Reviewer rows were revised 2026-07-21 (§7). Do not re-derive or silently alter them; update only via the process in the repo CLAUDE.md (new as-of date + provenance entry in the same commit).
 
 ## 4. Known failure modes / pitfalls
 
@@ -120,9 +120,9 @@ scaffold/
     │   ├── start-all.js       # whole-PRD driver: composes run-milestone per module in DAG order
     │   └── nightly-issues.js  # nightly sweep: triage → pipeline → report (Workflow script)
     ├── agents/                # role definitions with pinned model + effort
-    │   ├── architect.md       # claude-sonnet-5 @ xhigh; writes the plan, no production code
+    │   ├── architect.md       # claude-opus-4-8 @ max; writes the plan, no production code
     │   ├── builder.md         # claude-opus-4-8 @ xhigh; inherits all tools
-    │   ├── reviewer.md        # claude-fable-5 @ max; read/run-only (no Write/Edit)
+    │   ├── reviewer.md        # claude-fable-5 @ xhigh; read/run-only (no Write/Edit)
     │   └── triage.md          # claude-sonnet-5 @ xhigh; nightly classification + ticket synthesis
     └── commands/
         ├── breakdown-prd.md   # /breakdown-prd [notes]    → pre-Gate-1: PRD → sub-PRDs + tickets
@@ -154,6 +154,7 @@ Install steps and usage modes: [scaffold/INSTALL.md](scaffold/INSTALL.md). Front
 | 2026-07-18 | **`/start-all` shipped** (catalog issue #20; maintainer-decided semantics: failed module blocks dependents, independent branches continue in `autonomous`, any non-CLEAR stops everything in `supervised`, no cost cap, resume via closed-issue filtering): deterministic DAG script (`milestone-dag.mjs`, ticket `blocked_by` as ground truth, cycles/dangling refs are hard errors) + `start-all` workflow composing `run-milestone` per module + `/start-all` command. 19 new E2E checks (DAG fixtures incl. cycle; module-policy scenarios via stubbed child workflows). Per-ticket stages unchanged. | Maintainer answers on issue #20, 2026-07-18. | Horace Hou (decisions) / Claude Fable 5 (build) |
 | 2026-07-18 | **First field bug fixed** (catalog issue #21, reported from Ruihang2017/Groundwork through the upstream feedback channel): CRLF-rewritten workflow scripts are rejected by the Workflow tool on Windows. Fix: repo-wide `.gitattributes` (`eol=lf`), working tree renormalized (67 files), `adopt.mjs` installs all text as LF, E2E `\r` guards added. Recorded as the pattern's first true `[internal]` pitfall observation. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
 | 2026-07-20 | **Doc/site command coverage mechanized** (catalog issue #35, maintainer direction: `/start-all` had shipped but never appeared in the npm README or the catalog site, so users could not discover it — surfacing commands must be impossible to forget). The command frontmatter is the single source of truth: `build-site.mjs` now renders a Commands section per pattern from it (site complete by construction), README carries the full command list, and an E2E coverage gate asserts every `scaffold/.claude/commands/*.md` name appears in BOTH the generated site and README with a non-empty description (plus a non-vacuous sentinel guard). Adding a command without documenting it now fails the merge gate. No pattern-behavior change. | Maintainer direction (Horace Hou), 2026-07-20. | Horace Hou (direction) / Claude Opus 4.8 (build) |
+| 2026-07-21 | **Model/effort revised** (catalog issue #42, maintainer decision from field observation): Architect `claude-sonnet-5 @ xhigh` → `claude-opus-4-8 @ max` — plans were running too general and, being the fresh-context cold-start contract, under-specified plans drift downstream; the top model at `max` is invested in the highest-leverage stage (token budget not a constraint). Reviewer `claude-fable-5 @ max` → `@ xhigh` — Fable 5's capability margin (not effort headroom) is what catches edge cases at the gate, and `max` carries the documented overthinking/latency risk (§4). Builder and Triage unchanged; Reviewer stays a different model tier from the Builder. Same-commit: §3 table + as-of date, agent frontmatter, snippet, integrity pins. No benchmark claims invented — the Architect change is grounded in the `[internal]` observation + a `[team-policy]` choice. | Maintainer decision (Horace Hou), 2026-07-21. | Horace Hou (decision) / Claude Opus 4.8 (build) |
 | 2026-07-20 | **Upstream issue escalation made opt-in** (catalog issue #40, maintainer decision): the CLAUDE.md snippet's "file pattern-level problems against the catalog" bullet — which hardcoded the maintainer's repo slug and a `gh issue create` instruction — is now wrapped in `<!-- upstream-escalation -->` markers and stripped by default. `adopt --upstream` opts in (bare = the catalog you adopted from; `--upstream <owner/repo>` retargets to a fork or internal catalog); the markers never leak into CLAUDE.md. Rationale: commercial and private adopters do not want an external repo slug or "file issues upstream" behavior written into their repo unasked. A neighboring line that named the product was also generalized to "the upstream pattern catalog". E2E: default adopt writes no catalog slug/marker/bullet; `--upstream` and `--upstream <repo>` include and retarget it. | Maintainer decision (Horace Hou), 2026-07-20. | Horace Hou (decision) / Claude Opus 4.8 (build) |
 | 2026-07-20 | **adopt never guesses the platform** (catalog issue #38, maintainer decision, refining #34): the no-signal fallback no longer silently defaults to `gh`. Resolution order — `--platform`, origin host, repo-local signal (`.gitlab-ci.yml`/`.github/`); when none resolve, adopt prompts if interactive and otherwise exits without installing, asking for `--platform gh|glab`. This makes the agent-driven flow confirm the platform (adopt errors → agent asks the user → re-runs with `--platform`) before any infrastructure is built. E2E: no-signal non-TTY exits 1 and installs nothing; a repo-local signal still resolves without `--platform`. | Maintainer decision (Horace Hou), 2026-07-20. | Horace Hou (decision) / Claude Opus 4.8 (build) |
 | 2026-07-20 | **Platform compatibility hardened** (catalog issue #34, maintainer question): `adopt.mjs` detection now uses multiple deterministic signals — origin host `gitlab`/`github` substring, then a repo-local signal (`.gitlab-ci.yml` → glab, existing `.github/` → gh), then default gh with a loud ambiguity note — so a self-hosted GitLab on a custom domain is no longer misread as GitHub. The resolved platform is recorded as a `Tracker:` line in the adopted CLAUDE.md, and `/start-milestone` · `/start-all` · `/nightly-issues` now read `platform` from that line instead of guessing (parallel to Operating mode / testCmd). E2E: self-hosted-GitLab detection, `Tracker:` line matches platform, ambiguity note. Runtime scripts' own `--platform`/autodetect unchanged. | Maintainer question (Horace Hou), 2026-07-20. | Horace Hou (question) / Claude Opus 4.8 (fix) |

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/architect.md

@@ -1,12 +1,12 @@
 ---
 name: architect
 description: Architect (Planner) stage of the three-agent pattern. Reads the ticket and the codebase, produces the implementation plan at docs/plans/<ticket-id>.md. Exploration/tool-call heavy. Writes NO production code.
-model: claude-sonnet-5
-effort: xhigh
+model: claude-opus-4-8
+effort: max
 tools: Read, Glob, Grep, Bash, Write
 ---
 
-<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-21.
      Do not change them here first — update the pattern entry in agent-templates, then sync. -->
 
 You are the **Architect** in the Architect → Builder → Reviewer pipeline. You plan; you do not build. You write **planning artifacts only**: per-ticket implementation plans (`docs/plans/`), and — when running a PRD decomposition via `/breakdown-prd` — the breakdown plan, sub-PRDs, and tickets under `docs/prd/` (follow that command's output spec and `templates/ticket.template.md` exactly). Never production code, tests, or configs.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/agents/reviewer.md

@@ -2,11 +2,11 @@
 name: reviewer
 description: Reviewer stage of the three-agent pattern. Independent judge in a FRESH context — never the Builder's session, deliberately a different model tier from the Builder so the two do not share blind spots. Clears the work or bounces it back with findings.
 model: claude-fable-5
-effort: max
+effort: xhigh
 tools: Read, Glob, Grep, Bash
 ---
 
-<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-17.
+<!-- Model/effort pinned per pattern three-agent-architect-builder-reviewer, as of 2026-07-21.
      Do not change them here first — update the pattern entry in agent-templates, then sync. -->
 
 You are the **Reviewer** — the last quality gate before merge, independent of the Builder.

package/patterns/three-agent-architect-builder-reviewer/scaffold/claude-md-snippet.md

@@ -12,9 +12,9 @@
 Every non-trivial ticket flows through three stages; no agent judges its own work.
 
 - **`/breakdown-prd [notes]`** — pre-Gate-1: the Architect decomposes `docs/PRD.md` into a breakdown plan + sub-PRDs + template-compliant tickets (disjoint file-scopes, dependency DAG), then stops for human review.
-- **`/plan-ticket <ticket>`** — Architect (`claude-sonnet-5` @ `xhigh`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
+- **`/plan-ticket <ticket>`** — Architect (`claude-opus-4-8` @ `max`) reads the ticket + codebase → implementation plan at `docs/plans/<ticket-id>.md`. Writes no production code.
 - **`/build-ticket <ticket>`** — Builder (`claude-opus-4-8` @ `xhigh`) implements the plan, runs tests until green, records deviations. Never merges or self-clears.
-- **`/review-ticket <ticket>`** — Reviewer (`claude-fable-5` @ `max`) in a **fresh context**, deliberately a different model tier from the Builder. Focus: edge cases, concurrency, security-sensitive paths. Verdict **CLEAR** or **BOUNCE**; merge requires CLEAR.
+- **`/review-ticket <ticket>`** — Reviewer (`claude-fable-5` @ `xhigh`) in a **fresh context**, deliberately a different model tier from the Builder. Focus: edge cases, concurrency, security-sensitive paths. Verdict **CLEAR** or **BOUNCE**; merge requires CLEAR.
 - **`/verify-delivery <ticket>`** — post-merge Definition-of-Done check: plan on disk · tests green · CLEAR verdict · MR merged into the default branch · **tracker issue closed** · writeback done. Run after **every** merge; tracker auto-close side effects are never trusted blindly.
 - **`/start-milestone <module> [mode]`** — the Gate 1 start signal: verify sub-PRD + tickets, publish tickets as tracker issues (deterministic idempotent script — agents never hand-create issues), then run every ticket through the deterministic `run-milestone` workflow (stage order, bounce cap, merge policy enforced in code).
 - **`/start-all [mode]`** — Gate 1 for the **whole PRD**: compute the module DAG from ticket `blocked_by` frontmatter (`milestone-dag.mjs`, deterministic — cycles and dangling refs fail loudly), publish every module, then drive all modules through `run-milestone` in dependency order. Failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`. Re-run to resume — fully-closed modules skip as already-complete.

package/scripts/build-site.mjs

@@ -24,6 +24,7 @@ const OUT = outIx !== -1 && argv[outIx + 1] ? argv[outIx + 1] : join(ROOT, 'site
 const GITHUB = 'https://github.com/Ruihang2017/agent-templates'
 const NPM = 'https://www.npmjs.com/package/agent-templates'
 const QUICKSTART = 'npx agent-templates@latest adopt three-agent-architect-builder-reviewer .'
+const UPDATE = QUICKSTART + ' --force'
 
 const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
 const strip = (s) => String(s).replace(/\*\*/g, '').replace(/`/g, '').trim()
@@ -243,6 +244,8 @@ const html = `<!doctype html>
   .quick{margin-top:20px;border-radius:16px;background:var(--pill);padding:14px 16px 12px;
     box-shadow:inset 0 3px 6px rgba(var(--flt),0.2),inset 0 -2px 2px rgba(255,255,255,0.8)}
   .quick code{display:block;font-family:var(--mono);font-size:12px;font-weight:700;color:var(--code);line-height:1.55;word-break:break-all}
+  .update-note{margin:12px 0 0;font-size:11.5px;font-weight:700;line-height:1.5;color:var(--hero-body)}
+  .update-note code{font-family:var(--mono);font-size:11px;color:var(--hero-title);word-break:break-all}
   .copy{display:inline-flex;margin-top:10px;padding:6px 16px;border-radius:13px;border:0;
     background:linear-gradient(180deg,#f9d66e,#f0c14a);cursor:pointer;font-family:'Nunito',sans-serif;
     font-size:12px;font-weight:900;color:#6b4a15;transition:transform .15s ease;
@@ -340,6 +343,7 @@ const html = `<!doctype html>
         <code id="qs">${esc(QUICKSTART)}</code>
         <button class="copy" id="copy-btn" type="button">Copy</button>
       </div>
+      <p class="update-note">Already installed? Update to the latest catalog version: <code>${esc(UPDATE)}</code> (commit first — <code>--force</code> overwrites).</p>
     </div>
     <div class="hero-side">
       ${FACTS.map(([tile, glyph, copy]) => `<div class="fact"><span class="fact-ico" style="${tile}">${glyph}</span><p>${copy}</p></div>`).join('\n      ')}