@nurix/etna 0.19.66 → 0.19.67

package/bin/etna.js

@@ -232,7 +232,16 @@ async function main(args) {
   await sleep(2000);
   boot.stop('Ready');
 
-  const harnessName = await resolveHarnessName(name, harnesses);
+  // Transition alias: the `apollo` harness merged into `code` (the code harness is pre-baked —
+  // it ships the docs scaffold as seeds and auto-baselines on first contact). Scripts and docs
+  // that pin the old name keep working through the alias; it retires after one window.
+  let requested = name;
+  if (requested === 'apollo' && !harnesses.apollo) {
+    p.log.info('`apollo` merged into `code` — installing `code` (the pre-baked harness).');
+    requested = 'code';
+  }
+
+  const harnessName = await resolveHarnessName(requested, harnesses);
   if (!harnessName) return; // user cancelled the interactive pick
 
   await installHarness(harnessName, harnesses);

package/data/harness-index.json

@@ -1,10 +1,6 @@
 {
-    "fingerprint": "774efa3ae2da",
+    "fingerprint": "546f4bccb873",
     "harnesses": {
-        "apollo": {
-            "plugin": "apollo",
-            "description": "the pre-baked `code` harness, built for Apollo Studio exports"
-        },
         "code": {
             "plugin": "code",
             "description": "the foundation every Nurix project starts with"

package/data/harnesses/code/CLAUDE.md

@@ -6,6 +6,8 @@ How AI coding agents — any vendor, any runtime — work on this project. Rules
 
 ## Maintenance
 
+**Baseline first**: if `docs/structure.md` lacks a `harness-version` frontmatter marker, or it is behind the `version` in `.claude/harness.json`, dispatch the `maintenance` agent **as a sub-agent** before taking up the user's first ask — baseline is bulky mechanical work, and dispatching it keeps this context clean for the ask. Tell the user what it will do; on a repo with existing docs or `.bkp` files, name what the fold will touch. No dispatch mechanism ⇒ run it inline.
+
 Invoke the `maintenance` agent when a mechanical condition holds: `docs/structure.md` is missing (the repo isn't reconciled — baseline first), the `harness-version` marker is behind the installed version, a doc contradicts code being touched, or source paths are unowned — not on prose that merely looks stale. Structural reconciliation is never done by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Single-glob or single-line doc corrections are done inline, per § Documentation. Each component's internals live in the component, not here.
 
 ---

package/data/harnesses/code/agents/maintenance.md

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -186,6 +186,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/code/harness.json

@@ -1,14 +1,19 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.7.3",
+  "version": "3.8.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [
+    "docs/README.md",
+    "docs/structure.md",
+    "docs/history/CHANGELOG.md",
+    "docs/history/backlog.md",
+    "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "5e3c8dcf55ff"
+  "digest": "f120a269e99c"
 }

package/data/harnesses/code/hooks/compliance.mjs

@@ -192,6 +192,7 @@ function stagedExempt(files) {
       HARNESS_FILES.includes(f) ||
       f.startsWith("docs/history/changelog/") ||
       f.startsWith("docs/history/sessions/") ||
+      f.includes(".bkp.") ||
       f === "docs/history/CHANGELOG.md"
   );
 }

package/data/harnesses/code/hooks/lib/frozen.mjs

@@ -29,6 +29,9 @@ function readSafe(projectDir, filePath) {
 
 // The predicate. Returns { frozen: boolean, reason?: string }.
 export function frozenStatus(projectDir, filePath) {
+  // *.bkp.* siblings are install-time backups, not records — the maintenance fold edits and
+  // deletes them, which a frozen verdict would forbid.
+  if (relPosix(projectDir, filePath).includes(".bkp.")) return { frozen: false };
   const rel = relPosix(projectDir, filePath);
   if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
     if (isCommitted(projectDir, rel)) {

package/data/harnesses/code/hooks/lib/ownership.mjs

@@ -117,7 +117,9 @@ export function asList(v) {
 // Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
 export function scanFeatureDocs(projectDir) {
   const featuresDir = path.join(projectDir, "docs", "features");
-  const files = listMarkdown(featuresDir);
+  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up feature
+  // doc still carries owns: frontmatter, and scanning it would double-own every path it names.
+  const files = listMarkdown(featuresDir).filter((f) => !f.includes(".bkp."));
   const docs = [];
   for (const file of files) {
     let text;

package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.

package/data/harnesses/delivery/agents/maintenance.md

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -186,6 +186,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/delivery/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "5384fce602a8"
+  "digest": "99afecb2c42f"
 }

package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.

package/data/harnesses/etna/agents/maintenance.md

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -186,6 +186,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "1c440d72ea9f"
+  "digest": "dca4815bd3d5"
 }

package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.

package/lib/install/materialize.mjs

@@ -24,7 +24,6 @@ import {
   readFileSync,
   writeFileSync,
   renameSync,
-  cpSync,
   readdirSync,
   lstatSync,
   rmSync,
@@ -50,23 +49,25 @@ export function isSymlink(path) {
   }
 }
 
-// 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;
+// The .bkp path for a colliding file: the marker goes BEFORE the final extension
+// (CHANGELOG.md → CHANGELOG.bkp.md, .prettierrc.json → .prettierrc.bkp.json), so one glob —
+// `*.bkp.*` — matches every backup, and every harness scanner ignores exactly that glob. A file
+// with no extension appends `.bkp`.
+export function bkpPathFor(path) {
+  const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  const dot = path.lastIndexOf('.');
+  if (dot <= slash + 1) return `${path}.bkp`; // no extension, or a leading-dot name like `.env`
+  return `${path.slice(0, dot)}.bkp${path.slice(dot)}`;
 }
 
-// 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 });
+// Move a colliding FOREIGN file aside as its .bkp sibling. First backup wins: if the .bkp
+// already exists (a re-run before any baseline folded it), the older backup is the more
+// original and is kept; the collision file is simply overwritten by the install.
+function bkpRename(path) {
+  if (!existsSync(path) && !isSymlink(path)) return null;
+  const backup = bkpPathFor(path);
+  if (existsSync(backup) || isSymlink(backup)) return null;
+  renameSync(path, backup);
   return backup;
 }
 
@@ -300,43 +301,17 @@ export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, p
   // 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}`,
-        );
-      }
-    }
-  }
+  // FIRST CONTACT vs REFRESH is the entire backup question, and the marker decides it. On a
+  // refresh, every colliding file at a harness path is the harness's own previous version —
+  // overwritten in place, git or no git; backing up our own stale copies would bury every upgrade
+  // in .bkp noise. On first contact, a colliding file is the USER'S — it is moved aside as its
+  // .bkp sibling, ours installs, and the maintenance baseline folds docs-side .bkp content into
+  // the reconciled tree (top-level config .bkp files are never merged — they are listed and left
+  // to the human). Git is not the distinction: history protects bytes, but the .bkp file is what
+  // makes the fold duty visible to the next session. The harness is deliberately unapologetic
+  // about its own process; the backup is how it stays honest about yours.
+  const firstContact = !existsSync(join(targetDir, '.claude', 'harness.json'));
+  void projectHasGit; // kept for caller compatibility; the .bkp rule does not branch on it
 
   // 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
@@ -346,13 +321,18 @@ export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, p
 
   let written = 0;
   let seeded = 0;
+  const backedUp = [];
   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.
+    // A seed is one-time scaffolding: once installed, the path is the project's living copy and a
+    // refresh never touches it. On FIRST contact a pre-existing file at a seed path is the user's
+    // — it moves aside as .bkp and the pristine seed installs, so the baseline has both to fold.
     if (file.policy === 'seed') {
-      if (existsSync(dest)) continue;
+      if (existsSync(dest)) {
+        if (!firstContact) continue;
+        const backup = bkpRename(dest);
+        if (backup) backedUp.push(file.path);
+      }
       mkdirSync(dirname(dest), { recursive: true });
       writeFileSync(dest, file.content);
       seeded += 1;
@@ -362,12 +342,26 @@ export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, p
     // 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;
+    if (firstContact && (existsSync(dest) || isSymlink(dest))) {
+      const backup = bkpRename(dest);
+      if (backup) backedUp.push(file.path);
+    }
     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)`);
+  if (backedUp.length > 0) {
+    warnings.push(
+      `${backedUp.length} pre-existing file(s) moved aside as .bkp siblings (${backedUp.join(', ')}). ` +
+        'The maintenance baseline folds docs-side .bkp content into the reconciled tree and deletes the .bkp; ' +
+        'top-level config .bkp files are never merged — review those yourself.',
+    );
+  }
+  if (!firstContact) {
+    notices.push('Refresh: harness-owned files updated in place; seeds and .bkp files untouched.');
+  }
 
   // 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.66",
+    "version": "0.19.67",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {
@@ -42,5 +42,5 @@
         "agent",
         "plugin"
     ],
-    "etnaFingerprint": "774efa3ae2da"
+    "etnaFingerprint": "546f4bccb873"
 }

package/data/harnesses/apollo/.mcp.json

@@ -1,8 +0,0 @@
-{
-    "mcpServers": {
-        "design": {
-            "type": "http",
-            "url": "https://apollo.nustack.tech/design/mcp"
-        }
-    }
-}

package/data/harnesses/apollo/.prettierignore

@@ -1,29 +0,0 @@
-# Dependencies & build output
-node_modules
-dist
-build
-
-# Lockfiles
-pnpm-lock.yaml
-package-lock.json
-yarn.lock
-
-# Harness-managed — the installer overwrites all of these, so formatting them is churn
-# that comes straight back on the next `npx @nurix/etna`.
-.claude
-.codex
-.agents
-CLAUDE.md
-AGENTS.md
-
-# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
-# artifact that is never edited after it freezes. Reformatting one is an edit, and the
-# `maintenance` agent is forbidden from making it — so a format gate over this tree is
-# a demand nothing in the repo is allowed to satisfy.
-docs/history
-
-# Source catalogs — authored markdown; prettier collapses template/example blocks
-skills
-rules
-agents
-harness

package/data/harnesses/apollo/.prettierrc.json

@@ -1,3 +0,0 @@
-{
-  "proseWrap": "never"
-}

package/data/harnesses/apollo/.vscode/settings.json

@@ -1,19 +0,0 @@
-{
-  // Markdown: Prettier unwraps prose to one logical line per paragraph
-  // (see .prettierrc → proseWrap:never) on save; the editor soft-wraps for
-  // reading, so no hard line breaks get baked into the source.
-  "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "editor.formatOnSave": true,
-    "editor.wordWrap": "on"
-  },
-  // Hide harness-authoring scaffolding from the file explorer
-  "files.exclude": {
-    ".claude": true,
-    ".vscode": true,
-    ".agents": true,
-    ".codex": true,
-    "**/node_modules": true,
-    "**/apollo.service.json": true
-  }
-}