@nurix/etna 0.19.64 → 0.19.65

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "6b7cd94d8ed9",
+    "fingerprint": "b0d947332bf0",
     "harnesses": {
         "apollo": {
             "plugin": "apollo",

package/data/harnesses/apollo/harness.json

@@ -15,5 +15,5 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "d01be54a3e94"
+  "digest": "673c1a2ae5b8"
 }

package/data/harnesses/apollo/hooks/approved-packages.md

@@ -39,4 +39,6 @@ Read by the PreToolUse install gate (`compliance.mjs`) — an off-table install
 | `fast-deep-equal` | ^3.1.3 | Deep equality checks | `lodash.isEqual` |
 | `@ngneat/falso` | latest | Fake data generation | `@faker-js/faker`, `chance` |
 | `pino` | ^10.1.0 | Logging | `winston` |
+| `wrangler` | ^4.118.0 | Cloudflare Workers CLI — dev server, deploy | `@cloudflare/wrangler` (deprecated), `miniflare` standalone |
+| `mermaid` | ^11.16.0 | Diagram rendering in the browser | `mermaid` via CDN, `viz.js`, `flowchart.js` |
 

package/data/harnesses/apollo/skills/documentation/references/style-guide.md

@@ -154,6 +154,39 @@ For screen layouts (not data flows), use these conventions:
 
 ---
 
+## Mermaid Diagrams
+
+**Structure at rest is ASCII; behaviour over time is mermaid.** A file tree, an on-disk layout, a load-class split, a wireframe — draw with box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow — write mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
+
+**Docs only**, on the same reasoning as ASCII: a diagram never enters an instruction file.
+
+### When to Use
+
+| Diagram | Use for |
+| --- | --- |
+| `sequenceDiagram` | Who calls whom in what order — a session turn, a hand-off between components |
+| `stateDiagram-v2` | Modes with transitions — a workflow, a record's lifecycle |
+| `flowchart` | A process with branches, gates, or fan-out |
+| `timeline` | A dated lineage, in records only — never in a truth document |
+
+### Rules
+
+- **At most 7 participants and 15 interactions** per diagram. Past that, split it — an unreadable diagram is worse than the prose it replaced.
+- **Labels under 8 words**, no trailing punctuation.
+- **Declare a direction** on every flowchart (`flowchart TD` / `LR`) so the render is stable.
+- **The diagram never carries a fact the prose omits.** It restates structure for a reader who scans; a reader who greps must still find everything in the text.
+- **No styling directives** — no `style`, no `classDef`, no theme overrides. Rendering is the reader's; the source stays portable across GitHub, Obsidian, and a plain editor.
+
+```
+flowchart LR
+  A[Plan approved] --> B{boundary}
+  B -->|BLOCK| C[Re-plan]
+  B -->|PASS| D[testing plan-gate]
+  D --> E[Implement]
+```
+
+---
+
 ## Code Examples
 
 ### Rules
@@ -344,7 +377,7 @@ Always end with:
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
-| Diagrams   | ASCII for all flows — docs only, never instruction files |
+| Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
 | Mechanics  | Inline-code identifiers; bold-assertion bullets |

package/data/harnesses/code/harness.json

@@ -10,5 +10,5 @@
   "seeds": [
     ".mcp.json"
   ],
-  "digest": "b7f0d55f9ba4"
+  "digest": "105461e25748"
 }

package/data/harnesses/code/hooks/approved-packages.md

@@ -39,4 +39,6 @@ Read by the PreToolUse install gate (`compliance.mjs`) — an off-table install
 | `fast-deep-equal` | ^3.1.3 | Deep equality checks | `lodash.isEqual` |
 | `@ngneat/falso` | latest | Fake data generation | `@faker-js/faker`, `chance` |
 | `pino` | ^10.1.0 | Logging | `winston` |
+| `wrangler` | ^4.118.0 | Cloudflare Workers CLI — dev server, deploy | `@cloudflare/wrangler` (deprecated), `miniflare` standalone |
+| `mermaid` | ^11.16.0 | Diagram rendering in the browser | `mermaid` via CDN, `viz.js`, `flowchart.js` |
 

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -154,6 +154,39 @@ For screen layouts (not data flows), use these conventions:
 
 ---
 
+## Mermaid Diagrams
+
+**Structure at rest is ASCII; behaviour over time is mermaid.** A file tree, an on-disk layout, a load-class split, a wireframe — draw with box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow — write mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
+
+**Docs only**, on the same reasoning as ASCII: a diagram never enters an instruction file.
+
+### When to Use
+
+| Diagram | Use for |
+| --- | --- |
+| `sequenceDiagram` | Who calls whom in what order — a session turn, a hand-off between components |
+| `stateDiagram-v2` | Modes with transitions — a workflow, a record's lifecycle |
+| `flowchart` | A process with branches, gates, or fan-out |
+| `timeline` | A dated lineage, in records only — never in a truth document |
+
+### Rules
+
+- **At most 7 participants and 15 interactions** per diagram. Past that, split it — an unreadable diagram is worse than the prose it replaced.
+- **Labels under 8 words**, no trailing punctuation.
+- **Declare a direction** on every flowchart (`flowchart TD` / `LR`) so the render is stable.
+- **The diagram never carries a fact the prose omits.** It restates structure for a reader who scans; a reader who greps must still find everything in the text.
+- **No styling directives** — no `style`, no `classDef`, no theme overrides. Rendering is the reader's; the source stays portable across GitHub, Obsidian, and a plain editor.
+
+```
+flowchart LR
+  A[Plan approved] --> B{boundary}
+  B -->|BLOCK| C[Re-plan]
+  B -->|PASS| D[testing plan-gate]
+  D --> E[Implement]
+```
+
+---
+
 ## Code Examples
 
 ### Rules
@@ -344,7 +377,7 @@ Always end with:
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
-| Diagrams   | ASCII for all flows — docs only, never instruction files |
+| Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
 | Mechanics  | Inline-code identifiers; bold-assertion bullets |

package/data/harnesses/delivery/harness.json

@@ -8,5 +8,5 @@
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "3d15299f4b1f"
+  "digest": "83870917a79b"
 }

package/data/harnesses/delivery/skills/documentation/references/style-guide.md

@@ -154,6 +154,39 @@ For screen layouts (not data flows), use these conventions:
 
 ---
 
+## Mermaid Diagrams
+
+**Structure at rest is ASCII; behaviour over time is mermaid.** A file tree, an on-disk layout, a load-class split, a wireframe — draw with box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow — write mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
+
+**Docs only**, on the same reasoning as ASCII: a diagram never enters an instruction file.
+
+### When to Use
+
+| Diagram | Use for |
+| --- | --- |
+| `sequenceDiagram` | Who calls whom in what order — a session turn, a hand-off between components |
+| `stateDiagram-v2` | Modes with transitions — a workflow, a record's lifecycle |
+| `flowchart` | A process with branches, gates, or fan-out |
+| `timeline` | A dated lineage, in records only — never in a truth document |
+
+### Rules
+
+- **At most 7 participants and 15 interactions** per diagram. Past that, split it — an unreadable diagram is worse than the prose it replaced.
+- **Labels under 8 words**, no trailing punctuation.
+- **Declare a direction** on every flowchart (`flowchart TD` / `LR`) so the render is stable.
+- **The diagram never carries a fact the prose omits.** It restates structure for a reader who scans; a reader who greps must still find everything in the text.
+- **No styling directives** — no `style`, no `classDef`, no theme overrides. Rendering is the reader's; the source stays portable across GitHub, Obsidian, and a plain editor.
+
+```
+flowchart LR
+  A[Plan approved] --> B{boundary}
+  B -->|BLOCK| C[Re-plan]
+  B -->|PASS| D[testing plan-gate]
+  D --> E[Implement]
+```
+
+---
+
 ## Code Examples
 
 ### Rules
@@ -344,7 +377,7 @@ Always end with:
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
-| Diagrams   | ASCII for all flows — docs only, never instruction files |
+| Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
 | Mechanics  | Inline-code identifiers; bold-assertion bullets |

package/data/harnesses/etna/harness.json

@@ -8,5 +8,5 @@
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "5ddc026fa3b1"
+  "digest": "4d6b33a51517"
 }

package/data/harnesses/etna/skills/documentation/references/style-guide.md

@@ -154,6 +154,39 @@ For screen layouts (not data flows), use these conventions:
 
 ---
 
+## Mermaid Diagrams
+
+**Structure at rest is ASCII; behaviour over time is mermaid.** A file tree, an on-disk layout, a load-class split, a wireframe — draw with box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow — write mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted.
+
+**Docs only**, on the same reasoning as ASCII: a diagram never enters an instruction file.
+
+### When to Use
+
+| Diagram | Use for |
+| --- | --- |
+| `sequenceDiagram` | Who calls whom in what order — a session turn, a hand-off between components |
+| `stateDiagram-v2` | Modes with transitions — a workflow, a record's lifecycle |
+| `flowchart` | A process with branches, gates, or fan-out |
+| `timeline` | A dated lineage, in records only — never in a truth document |
+
+### Rules
+
+- **At most 7 participants and 15 interactions** per diagram. Past that, split it — an unreadable diagram is worse than the prose it replaced.
+- **Labels under 8 words**, no trailing punctuation.
+- **Declare a direction** on every flowchart (`flowchart TD` / `LR`) so the render is stable.
+- **The diagram never carries a fact the prose omits.** It restates structure for a reader who scans; a reader who greps must still find everything in the text.
+- **No styling directives** — no `style`, no `classDef`, no theme overrides. Rendering is the reader's; the source stays portable across GitHub, Obsidian, and a plain editor.
+
+```
+flowchart LR
+  A[Plan approved] --> B{boundary}
+  B -->|BLOCK| C[Re-plan]
+  B -->|PASS| D[testing plan-gate]
+  D --> E[Implement]
+```
+
+---
+
 ## Code Examples
 
 ### Rules
@@ -344,7 +377,7 @@ Always end with:
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
-| Diagrams   | ASCII for all flows — docs only, never instruction files |
+| Diagrams   | ASCII for structure at rest, mermaid for behaviour over time — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
 | Mechanics  | Inline-code identifiers; bold-assertion bullets |

package/lib/install/materialize.mjs

@@ -0,0 +1,402 @@
+// packages/cli/lib/install/materialize.mjs
+// Turn one bundled harness into an installed project tree. THE SINGLE AUTHORITY on where a
+// harness's files land — a bundle says `skills/design/SKILL.md`, a project says
+// `.claude/skills/design/SKILL.md`, and this module is the only place that mapping exists.
+//
+// TWO SHIPPERS, ONE MAPPING. `bin/etna.js` calls this against the user's cwd; the Apollo push
+// (`.github/scripts/push-harnesses.mjs`) calls it against a throwaway directory and ships the
+// result, so an App's export from Apollo extracts as the same tree `npx @nurix/etna` writes.
+// They diverged once — the push sent the BUNDLE layout, so a downloaded project had its
+// instruction tree at the archive root, no AGENTS.md, and no wired hooks, while the manifest
+// claimed otherwise. One function is what stops that recurring.
+//
+// ZERO DEPENDENCIES, BY NECESSITY. The push runs in CI without an `npm install` (that workflow
+// reaches `npm publish` → `prepack` and nothing else), so this module and everything it imports
+// may use only what Node ships. That rules out importing `bin/etna.js`, which pulls in
+// @clack/prompts for its UI — hence the extraction rather than a re-export.
+//
+// PURE FILE OPS, NO UI. Every human-facing string is RETURNED (installed/notices/warnings) and
+// printed by the caller, so the push can discard what the CLI renders.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  cpSync,
+  readdirSync,
+  lstatSync,
+  rmSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { planHarnessFiles, PRUNABLE_SUBDIRS, CODEX_REBUILT_DIRS } from './plan.mjs';
+
+// Hook scripts shipped by earlier harness versions (the legacy memory-ledger tier) and since retired.
+// mergeHooks is additive, so an upgrade must explicitly remove both the stale settings.json
+// entries pointing at these and the leftover script files they reference.
+const RETIRED_HOOKS = [
+  'session-stop.js',
+  'post-tool-failure.js',
+  'post-commit.js',
+  'generate-ownership-index.mjs', // folded into awareness.mjs — unretired, the index would inject twice
+];
+
+export function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+// Move <path> to <path>.bak.<timestamp> if it exists. Returns the backup path, or null.
+function backupIfExists(path) {
+  if (!existsSync(path) && !isSymlink(path)) return null;
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = `${path}.bak.${ts}`;
+  renameSync(path, backup);
+  return backup;
+}
+
+// Copy a directory to <path>.bak.<timestamp>, leaving the original in place. Returns the
+// backup path, or null. Used for .claude/, which is refreshed in place (not overwritten
+// wholesale), so the live tree must survive for the in-place update — snapshot, don't move.
+function snapshotDirIfExists(path) {
+  if (!existsSync(path)) return null;
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = `${path}.bak.${ts}`;
+  cpSync(path, backup, { recursive: true });
+  return backup;
+}
+
+// Throws rather than exiting: the CLI turns this into its own `die`, and the push into a
+// non-zero exit naming the harness.
+export function readJson(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    throw new Error(`failed to parse ${path}: ${e.message}`);
+  }
+}
+
+// 2-space indent matches Claude Code's own writes to settings.json.
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+
+// Clean up any leftover marketplace/enabledPlugins entries from a previous 0.1.x
+// install. After 0.2.0 we don't use the marketplace flow at all — leaving stale
+// entries causes Claude Code to also resolve the plugin from the global cache,
+// double-loading the same skills under a different namespace.
+function migrateFromPluginInstall(targetDir, pluginName) {
+  const removed = [];
+  const projectSettingsPath = join(targetDir, '.claude', 'settings.json');
+  if (existsSync(projectSettingsPath)) {
+    const s = readJson(projectSettingsPath);
+    if (s.enabledPlugins) {
+      const keys = Object.keys(s.enabledPlugins).filter((k) => k.startsWith(`${pluginName}@`));
+      for (const k of keys) {
+        delete s.enabledPlugins[k];
+        removed.push(`enabledPlugins["${k}"] in ${projectSettingsPath}`);
+      }
+      if (Object.keys(s.enabledPlugins).length === 0) delete s.enabledPlugins;
+      writeJson(projectSettingsPath, s);
+    }
+  }
+  return removed;
+}
+
+// Remove settings.json hook entries and .claude/hooks/ files for retired hook scripts.
+// Bundle-aware: a name on the retired list is skipped while THIS bundle still ships it —
+// several harnesses share the list, and they retire the same script at different versions.
+function retireOldHooks(targetDir, bundledHarnessDir) {
+  const removed = [];
+  const bundledHooksDir = join(bundledHarnessDir, 'hooks');
+  const stillShipped = new Set(
+    existsSync(bundledHooksDir)
+      ? readdirSync(bundledHooksDir, { withFileTypes: true })
+          .filter((e) => e.isFile())
+          .map((e) => e.name)
+      : [],
+  );
+  const retired = RETIRED_HOOKS.filter((name) => !stillShipped.has(name));
+  const settingsPath = join(targetDir, '.claude', 'settings.json');
+  if (existsSync(settingsPath)) {
+    const settings = readJson(settingsPath);
+    const isRetired = (h) => retired.some((name) => (h.command || '').includes(`/hooks/${name}`));
+    let pruned = 0;
+    for (const [event, groups] of Object.entries(settings.hooks || {})) {
+      for (const group of groups) {
+        const before = (group.hooks || []).length;
+        group.hooks = (group.hooks || []).filter((h) => !isRetired(h));
+        pruned += before - group.hooks.length;
+      }
+      settings.hooks[event] = groups.filter((g) => (g.hooks || []).length > 0);
+      if (settings.hooks[event].length === 0) delete settings.hooks[event];
+    }
+    if (pruned > 0) {
+      writeJson(settingsPath, settings);
+      removed.push(`${pruned} retired hook entr${pruned === 1 ? 'y' : 'ies'} in settings.json`);
+    }
+  }
+  for (const name of retired) {
+    const file = join(targetDir, '.claude', 'hooks', name);
+    if (existsSync(file)) {
+      rmSync(file, { force: true });
+      removed.push(`stale hook script ${name}`);
+    }
+  }
+  return removed;
+}
+
+// Read the `owned` manifest the PREVIOUS install recorded in the project's harness.json.
+// Absent (first install, or pre-pruning version) ⇒ {} ⇒ nothing is pruned this round.
+function readInstalledOwned(targetDir) {
+  const path = join(targetDir, '.claude', 'harness.json');
+  if (!existsSync(path)) return {};
+  const owned = readJson(path).owned;
+  return owned && typeof owned === 'object' ? owned : {};
+}
+
+// Remove vendored components a prior harness version owned but this one no longer ships
+// (e.g. a retired agent like harness-manager). Only names present in the PRIOR `owned`
+// manifest are eligible, so a project's own components — never in that manifest — survive.
+function pruneOrphanedComponents(targetDir, priorOwned, newOwned) {
+  const removed = [];
+  for (const sub of PRUNABLE_SUBDIRS) {
+    const had = priorOwned[sub] || [];
+    const has = new Set(newOwned[sub] || []);
+    for (const name of had) {
+      if (has.has(name)) continue;
+      const target = join(targetDir, '.claude', sub, name);
+      if (existsSync(target)) {
+        rmSync(target, { recursive: true, force: true });
+        removed.push(`orphaned ${sub.replace(/s$/, '')} ${name}`);
+      }
+    }
+  }
+  return removed;
+}
+
+// Every file inside dir, as paths relative to dir.
+export function listFilesRecursive(dir, prefix = '') {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFilesRecursive(join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+// Remove directories left empty by a prune, depth-first.
+function removeEmptyDirs(dir) {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir, { withFileTypes: true }))
+    if (entry.isDirectory()) removeEmptyDirs(join(dir, entry.name));
+  if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true, force: true });
+}
+
+// Remove files inside an installed component that this bundle no longer ships. copyHarnessSubdir
+// merges, so a component that SURVIVES an upgrade while shedding a file keeps the stale copy
+// forever — that is how a retired reference file goes on being read as live doctrine. Scoped to
+// components the bundle still ships (a project's own components are never in that set, so they
+// are never touched), and needs no prior manifest, so one refresh clears orphans left by any
+// earlier version. Whole components that disappear are pruneOrphanedComponents' job.
+function pruneStaleComponentFiles(bundledSubdir, projectSubdir) {
+  const removed = [];
+  if (!existsSync(bundledSubdir)) return removed;
+  for (const entry of readdirSync(bundledSubdir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const shipped = new Set(listFilesRecursive(join(bundledSubdir, entry.name)));
+    const installedDir = join(projectSubdir, entry.name);
+    for (const rel of listFilesRecursive(installedDir)) {
+      if (shipped.has(rel)) continue;
+      rmSync(join(installedDir, rel), { force: true });
+      removed.push(`${entry.name}/${rel}`);
+    }
+    removeEmptyDirs(installedDir);
+  }
+  return removed;
+}
+
+// True if an event's matcher-group already carries a hook with this command string.
+function groupHasCommand(group, command) {
+  return (group.hooks || []).some((h) => h.command === command);
+}
+
+// Deep-merge the bundle's hooks.json object into <project>/.claude/settings.json under
+// "hooks", preserving every existing key. Idempotent: for each event, an incoming entry
+// merges into the matcher-group of the same matcher, skipping any hook whose command
+// already exists there; a new matcher creates a new group. Returns count of hooks added.
+function mergeHooks(targetDir, bundledHooksJson) {
+  if (!existsSync(bundledHooksJson)) return 0;
+  const bundled = readJson(bundledHooksJson);
+  const incoming = bundled.hooks || {};
+  const settingsPath = join(targetDir, '.claude', 'settings.json');
+  const settings = readJson(settingsPath);
+  settings.hooks = settings.hooks || {};
+  let added = 0;
+  // Harness-shipped permission defaults (e.g. Edit on docs/** flows without prompts —
+  // the deny hooks still hard-block frozen/protected paths underneath). Additive, idempotent.
+  for (const rule of bundled.permissions?.allow || []) {
+    settings.permissions = settings.permissions || {};
+    const allowList = (settings.permissions.allow = settings.permissions.allow || []);
+    if (!allowList.includes(rule)) {
+      allowList.push(rule);
+      added += 1;
+    }
+  }
+  for (const [event, groups] of Object.entries(incoming)) {
+    const existingGroups = (settings.hooks[event] = settings.hooks[event] || []);
+    for (const group of groups) {
+      const match = existingGroups.find((g) => g.matcher === group.matcher);
+      if (!match) {
+        existingGroups.push(group);
+        added += (group.hooks || []).length;
+        continue;
+      }
+      match.hooks = match.hooks || [];
+      for (const hook of group.hooks || []) {
+        if (groupHasCommand(match, hook.command)) continue;
+        match.hooks.push(hook);
+        added += 1;
+      }
+    }
+  }
+  if (added > 0) writeJson(settingsPath, settings);
+  return added;
+}
+
+/**
+ * Write one compiled harness into `targetDir` as an installed project tree.
+ *
+ * THE PLAN DECIDES WHAT AND WHERE; THIS DECIDES HOW IT MEETS AN EXISTING PROJECT. Placement lives
+ * in `plan.mjs` and is shared with the Apollo push, so the two shippers cannot disagree about a
+ * path. Everything here is the part a payload has no use for: backing up what git cannot recover,
+ * rebuilding the Codex mirrors wholesale, pruning components a prior version owned, retiring hook
+ * entries pointing at scripts this bundle no longer carries, and folding the harness's hooks into
+ * a settings.json that already belongs to somebody.
+ *
+ * `pluginName` is used only for the legacy marketplace cleanup. `projectHasGit` decides the backup
+ * policy for the harness-owned artifacts a refresh overwrites — git is the safety net when it is
+ * there, a `.bak.<timestamp>` copy when it is not.
+ *
+ * Returns the accounting the caller renders: `installed`, `notices`, `warnings`, plus `owned` (the
+ * manifest written into `.claude/harness.json`) and `meta` (the bundle marker).
+ */
+export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, projectHasGit }) {
+  const { files, owned, meta } = planHarnessFiles(bundledHarnessDir);
+
+  const installed = [];
+  const notices = [];
+  const warnings = [];
+
+  // Read BEFORE anything is written: this is what a prior install recorded as harness-owned, and
+  // the marker that holds it is one of the files about to be overwritten.
+  const priorOwned = readInstalledOwned(targetDir);
+
+  // The safety net, for the two artifacts a refresh overwrites outright. A git repo recovers them
+  // from history, so we only say so; without git there is no net, so we take a copy and warn. The
+  // .claude/ tree is SNAPSHOTTED rather than moved — it is refreshed in place, so the live tree has
+  // to survive for the writes below.
+  for (const [rel, kind] of [
+    ['CLAUDE.md', 'file'],
+    ['AGENTS.md', 'file'],
+  ]) {
+    const dest = join(targetDir, rel);
+    if (!existsSync(dest) && !isSymlink(dest)) continue;
+    if (projectHasGit) {
+      notices.push(
+        `Overwrote existing ${rel} (tracked by git — \`git checkout ${rel}\` to restore).`,
+      );
+    } else {
+      warnings.push(
+        `No .git here, so no version-control safety net — backed up existing ${rel} → ${backupIfExists(dest)}`,
+      );
+    }
+    void kind;
+  }
+  for (const rel of ['.claude', ...CODEX_REBUILT_DIRS]) {
+    const dest = join(targetDir, rel);
+    if (!existsSync(dest)) continue;
+    if (projectHasGit) {
+      notices.push(
+        `Refreshed existing ${rel}/ in place (tracked by git — \`git checkout ${rel}\` to restore).`,
+      );
+    } else {
+      const backup = snapshotDirIfExists(dest);
+      if (backup) {
+        warnings.push(
+          `No .git here, so no version-control safety net — snapshotted existing ${rel}/ → ${backup}`,
+        );
+      }
+    }
+  }
+
+  // The Codex mirrors are rebuilt wholesale, not merged: they are byte projections of the Claude
+  // tree, so a file left behind from a prior version is a skill Codex still sees after the harness
+  // dropped it. Removed before the writes, never after.
+  for (const rel of CODEX_REBUILT_DIRS)
+    rmSync(join(targetDir, rel), { recursive: true, force: true });
+
+  let written = 0;
+  let seeded = 0;
+  for (const file of files) {
+    const dest = join(targetDir, file.path);
+    // A seed is one-time scaffolding: once the path exists it is the project's living copy, and a
+    // refresh must not touch it. This is also the rule that lets an Apollo export carry an App's
+    // own `docs/history/backlog.md` instead of the harness's.
+    if (file.policy === 'seed') {
+      if (existsSync(dest)) continue;
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, file.content);
+      seeded += 1;
+      continue;
+    }
+    // settings.json belongs to the project, not the harness — it carries the user's own hooks and
+    // permissions. The plan's copy is what a FRESH install would hold; against an existing file the
+    // authority is mergeHooks below, which is additive and idempotent.
+    if (file.policy === 'merge') continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content);
+    written += 1;
+  }
+  installed.push(`${written} harness file(s) → ./ and .claude/`);
+  if (seeded > 0) installed.push(`${seeded} seed file(s) → ./ (only where absent)`);
+
+  // Prune components a prior harness version owned but this bundle no longer ships (e.g. a retired
+  // agent). Only prior-owned names are eligible, so the project's own files survive.
+  for (const r of pruneOrphanedComponents(targetDir, priorOwned, owned))
+    notices.push(`removed ${r}`);
+
+  // Then prune stale files INSIDE components the bundle still ships — the case the name-level diff
+  // above cannot see, since the component itself is still present. Without it, a component that
+  // survives an upgrade while shedding a file keeps the stale copy for ever, and a retired
+  // reference file goes on being read as live doctrine.
+  for (const sub of PRUNABLE_SUBDIRS) {
+    for (const stale of pruneStaleComponentFiles(
+      join(bundledHarnessDir, sub),
+      join(targetDir, '.claude', sub),
+    )) {
+      notices.push(`removed stale ${sub.replace(/s$/, '')} file ${stale}`);
+    }
+  }
+
+  // Retire hooks earlier harness versions shipped, before merging, so the additive merge never
+  // resurrects an entry pointing at a script this bundle no longer carries.
+  for (const r of retireOldHooks(targetDir, bundledHarnessDir)) notices.push(`removed ${r}`);
+
+  const added = mergeHooks(targetDir, join(bundledHarnessDir, 'hooks', 'hooks.json'));
+  if (added > 0) installed.push(`${added} hook(s) → .claude/settings.json`);
+
+  for (const entry of migrateFromPluginInstall(targetDir, pluginName)) {
+    notices.push(`removed stale ${entry}`);
+  }
+
+  return { installed, notices, warnings, owned, meta };
+}