@noir-ai/create 1.14.0 → 1.15.0

package/dist/index.d.ts

@@ -19,7 +19,7 @@ declare function writeAncestors(root: string, map: Record<string, string>): void
  * adaptation (where to drop `.claude/` vs `.cursor/` etc., future), ignore-file
  * selection, and the onboarding TUI's confirm step.
  *
- * Design rules (spec §4.5):
+ * Design rules:
  *  - Never throws. A foreign/empty dir returns `{ languages: [], monorepo:
  *    false, frameworks: [], packageManager: null }`.
  *  - Never opens network, never parses code beyond a `package.json`/`pyproject`
@@ -41,18 +41,18 @@ interface StackInfo {
     /** `pnpm` | `npm` | `yarn` when a lockfile is present, else null. */
     packageManager: string | null;
     /**
-     * c4-project-discovery S1: source of the resolved PM. `packageManager-field`
+     * Source of the resolved PM. `packageManager-field`
      * (package.json#packageManager), `lockfile`, `user-agent` (invoke-time
      * npm_config_user_agent), or `unknown`.
      */
     pmSource: 'packageManager-field' | 'lockfile' | 'user-agent' | 'unknown';
     /**
-     * c4-project-discovery S3: detected CI. `github`/`gitlab`/`circleci`/
+     * Detected CI. `github`/`gitlab`/`circleci`/
      * `jenkins`/`none`.
      */
     ci: string | null;
     /**
-     * c4-project-discovery S2: existing AI instruction files found under root.
+     * Existing AI instruction files found under root.
      * Never clobbered — the scaffold confirms the write strategy (skip/add-section/
      * standalone).
      */
@@ -66,15 +66,154 @@ interface StackInfo {
 declare function detectStack(root: string): StackInfo;
 
 /**
- * The three-mode writer — generalizes keystone-K's `writeManagedRegion` into
+ * Template history — the evidence needed to decide whether a shipped seed
+ * file may be refreshed during an upgrade.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `noir init` writes two files whose only job is to be read by a human:
+ * `.noir/.env.example` (documents the variable set) and `.noir/rules/RULES.md`
+ * (the AI working-contract seed). Both are emitted create-only-if-absent, and
+ * that is normally the right contract: once a file exists, the user owns it and
+ * Noir must never overwrite their edits.
+ *
+ * It has one bad consequence. When a later release adds a variable to
+ * `.noir/.env.example`, an already-initialized project keeps the old text
+ * forever — the upgrade path cannot tell "the user rewrote this file" apart
+ * from "the user never touched it, and the shipped text has moved on". Those
+ * two need opposite handling: leave the first alone, refresh the second. A
+ * plain-content check cannot distinguish them, and nothing on disk records the
+ * bytes that were originally written.
+ *
+ * This module supplies the missing evidence. It holds the exact bytes of the
+ * seed templates as they shipped at each past scaffold version, so a caller can
+ * ask: "are the bytes on disk identical to some version Noir once wrote, and
+ * different from what Noir writes today?" If yes, the file is an unedited
+ * leftover and refreshing it loses nothing.
+ *
+ * THE CONTRACT
+ * ------------
+ * {@link isStaleSeed} answers exactly that question. It is deliberately
+ * conservative in one direction: it returns `true` only on an exact match
+ * against a recorded past version, so ANY other byte difference — a user edit,
+ * a re-wrapped line, even a CRLF line-ending conversion from a Windows
+ * checkout — reads as "user-owned" and the file is left untouched. A missed
+ * refresh is a documentation gap; a wrong refresh destroys user work. The
+ * asymmetry is intentional and should not be "fixed" into a fuzzy match.
+ *
+ * Each entry holds the text of BOTH seeds, so the comparison takes the seed it
+ * is about as an argument and scans only that field. Scanning all of them would
+ * let a `.env.example` match the recorded working-rules text (or the reverse),
+ * and since the caller's response to `true` is an overwrite, a mixed-up pairing
+ * would discard an edit the user is entitled to keep. The caller knows which
+ * file it just read; the argument makes it say so.
+ *
+ * RENDERING
+ * ---------
+ * Seed templates are normally interpolated through `render(template, vars)`
+ * before writing. That step is a no-op for the two templates recorded here:
+ * neither contains a `{{...}}` token, so `render(text, vars) === text` for
+ * every possible `vars`. The registry therefore stores raw template text and
+ * {@link isStaleSeed} compares it against raw file bytes — no `vars` argument
+ * is needed, and callers do not have to reconstruct the context that wrote the
+ * file years ago.
+ *
+ * That equivalence is load-bearing, so it is asserted rather than merely
+ * documented: `template-history.test.ts` fails if any recorded template
+ * contains a `{{` token. A future seed template that DOES interpolate needs
+ * `render` applied to the history entry (and a `vars` parameter on the
+ * comparison) before it is added here — the test exists to make that
+ * requirement impossible to overlook.
+ *
+ * APPENDING TO THE HISTORY
+ * ------------------------
+ * Record the template bytes as they shipped, keyed by the scaffold version
+ * whose `init` wrote them, and never edit an existing entry — a user's disk
+ * still holds those old bytes, and rewriting history would silently reclassify
+ * their file as "current" (no refresh) or "unknown" (no refresh). The same
+ * reasoning that keeps npm versions immutable applies here.
+ */
+/**
+ * Which recorded seed a comparison is about. The values mirror the field names
+ * of {@link SeedTemplateHistoryEntry}: every entry carries the text of both
+ * seeds, and a caller must name the one whose bytes it read (see
+ * {@link isStaleSeed} on why the pairing is load-bearing).
+ */
+type SeedKind = 'envExample' | 'rulesSeed';
+/**
+ * The seed templates as they shipped at one past scaffold version.
+ *
+ * Only the doc-only seeds are tracked. Files the user is expected to edit
+ * heavily (`.noir/config.yml`, `.noir/project.id`) are not candidates for
+ * refresh at all, and co-owned files that carry a managed region already have a
+ * three-way merge path of their own.
+ */
+interface SeedTemplateHistoryEntry {
+    /**
+     * Bare `x.y.z` scaffold version whose `init` wrote these bytes — the value
+     * stamped into `.noir/scaffold-version` at the time, with no `v` prefix and
+     * no pre-release suffix.
+     *
+     * Spelled out literally rather than read from `CURRENT_SCAFFOLD_VERSION`:
+     * the version recorded here is a historical fact about these bytes, so it
+     * must not advance when the current version does.
+     */
+    readonly scaffoldVersion: string;
+    /** Raw text of the `env.example` template at this version (see the module
+     *  header on why raw text equals the rendered file for this template). */
+    readonly envExample: string;
+    /** Raw text of the `rules-seed.md` template at this version. */
+    readonly rulesSeed: string;
+}
+/**
+ * The recorded seed-template bytes, oldest first.
+ *
+ * Read-only by intent: this is an append-only ledger of shipped bytes, not
+ * mutable configuration. Entries are never edited or removed (see the module
+ * header on why rewriting a past entry would silently misclassify a user's
+ * file), so a version that changed a seed template appends rather than
+ * updates.
+ */
+declare const SEED_TEMPLATE_HISTORY: readonly SeedTemplateHistoryEntry[];
+/**
+ * Does `fileBytes` look like an unedited `seed` left over from an older scaffold
+ * version?
+ *
+ * `true` iff the bytes are an exact match for that seed's text in a recorded
+ * history entry AND differ from `currentRender` (what Noir writes for that seed
+ * today). Callers pass `currentRender` rather than this module deriving it,
+ * because the current template text is the business of the manifest and the
+ * template loader — and because the compile-time constant that names the
+ * current scaffold version advances independently of the bytes recorded here.
+ *
+ * `seed` names the file the bytes came from. It is a safety argument, not
+ * bookkeeping: because each entry records both seeds, a comparison that scanned
+ * every field would report the recorded working-rules bytes as a stale
+ * `.env.example`, and the caller's response to `true` is to overwrite the file.
+ * Naming the seed keeps the comparison inside its own column, so a mixed-up
+ * pairing cannot silently destroy an edit the user is entitled to keep.
+ *
+ * The `currentRender` guard is checked FIRST: it is what keeps a no-op from
+ * being reported as a refresh. A project initialized at the current version
+ * already holds the current bytes; those bytes also match their own history
+ * entry, so without the second condition every up-to-date project would be told
+ * to rewrite its seeds.
+ *
+ * Callers own the other half of the decision: a file that does not exist has no
+ * bytes to compare and is a plain "create the seed", not a refresh.
+ */
+declare function isStaleSeed(seed: SeedKind, fileBytes: string, currentRender: string): boolean;
+
+/**
+ * The three-mode writer — generalizes the earlier `writeManagedRegion` into
  * the declarative dispatch the scaffold manifest drives. Each mode maps 1:1 to
- * an artifact class in the spec §4.5 matrix:
+ * an artifact class in the artifact matrix:
  *
  *  - {@link regenerate}    — pure pointers (`.mcp.json`, `NOIR.md` brief, …).
  *                           Always overwritten, atomically.
  *  - {@link managedBlock}  — co-owned files (`CLAUDE.md` context/rules,
  *                           `.gitignore` noir block, …). DELEGATES to
- *                           keystone-K's `writeManagedRegion` so user content
+ *                           core's `writeManagedRegion` so user content
  *                           outside the markers is preserved byte-for-byte and
  *                           re-runs are idempotent. Never duplicate the
  *                           managed-region logic.
@@ -82,7 +221,7 @@ declare function detectStack(root: string): StackInfo;
  *                           `project.id`). Write once; never clobber.
  *
  * The orchestrator (`scaffold.ts`) is the only intended caller; the per-mode
- * functions are exported so the cli (S-T2) and tests can drive them directly
+ * functions are exported so the cli and tests can drive them directly
  * when a one-off write is needed outside the manifest.
  */
 type WriteMode = 'regenerate' | 'managedBlock' | 'skipIfExists' | 'mergeJson';
@@ -104,7 +243,7 @@ interface WriteOutcome {
  *  for the whole manifest so a missing dir is a single, attributable failure
  *  rather than N silent ones inside the writer. */
 declare function regenerate(absPath: string, content: string): WriteOutcome;
-/** Re-emit a managed region, delegating to keystone-K's `writeManagedRegion`.
+/** Re-emit a managed region, delegating to core's `writeManagedRegion`.
  *  `regionText` MUST already include the begin/end markers (matches the shape
  *  `writeManagedRegion` expects and that `IGNORE_BLOCK`/`CONTEXT_BLOCK`
  *  callers build in core/cli). Use {@link buildRegion} to assemble it from a
@@ -120,12 +259,12 @@ declare function managedBlock(absPath: string, block: ManagedBlock, regionText:
  *  conventional trailing newline in `.tmpl` files without producing a
  *  double-newline before the end marker. This keeps the output byte-identical
  *  to `claudeAdapter.emitContext`/`emitRules` and core's `syncIgnores`, which
- *  S-T2 relies on for a diff-free refactor. */
+ *  the cli refactor relies on for diff-free output. */
 declare function buildRegion(block: ManagedBlock, body: string): string;
 /** Write `content` to `absPath` only if no file exists there. Returns whether
  *  bytes were written. Parent dirs are created by {@link atomicWriteFile}.
  *
- *  `fileMode` (slice E, §8.1) is the permission for the NEWLY created file —
+ *  `fileMode` is the permission for the NEWLY created file —
  *  `0o600` for the `.noir/.env` credential seed. It is applied to the temp file
  *  BEFORE the rename (see `AtomicWriteOptions.mode`), so the file never exists
  *  at its final path with a laxer mode. It is deliberately ignored when the
@@ -146,12 +285,13 @@ declare function skipIfExists(absPath: string, content: string, fileMode?: numbe
  * write {@link WriteMode} so the orchestrator can dispatch without knowing
  * what's inside.
  *
- * FAITHFULNESS CONTRACT (S-T1 → S-T2 → S10): this table is a strict superset of
- * the artifacts `packages/cli/src/{init,sync}.ts` wrote pre-Slice-S. The cli
- * refactor (S-T2) replaced those ad-hoc writers with a call into `scaffold()`;
- * the byte-for-byte output MUST stay equivalent for first-run init. S10 makes
- * the manifest HOST-PARAMETRIC: {@link buildManifest} now returns host-agnostic
- * entries + a {@link buildHostArtifacts} call that materializes per-host files
+ * FAITHFULNESS CONTRACT: this table is a strict superset of
+ * the artifacts `packages/cli/src/{init,sync}.ts` wrote before the manifest
+ * refactor. The cli refactor replaced those ad-hoc writers with a call into
+ * `scaffold()`; the byte-for-byte output MUST stay equivalent for first-run
+ * init. The manifest is HOST-PARAMETRIC: {@link buildManifest} returns
+ * host-agnostic entries + a {@link buildHostArtifacts} call that materializes
+ * per-host files
  * (CLAUDE.md/GEMINI.md for claude/gemini; AGENTS.md + .cursor/.../opencode.json
  * for agents-md/cursor/opencode) via the resolved adapter. The claude default
  * `noir init` stays BYTE-IDENTICAL to v1.1 — REMOVED the additive
@@ -163,15 +303,36 @@ declare function skipIfExists(absPath: string, content: string, fileMode?: numbe
  * `join(root, entry.path) === paths.X(root)` for every entry layout knows
  * about, so a layout rename is caught here instead of silently drifting.
  */
-/** S10: `HostTag` is now the SAME `HostId` enum the adapter registry uses
- *  (re-exported so existing imports keep working). Pre-S10 this was the
- *  literal `'claude'`; widening to `HostId` lets one manifest serve every host
- *  via the orchestrator's host filter + {@link buildHostArtifacts}. */
+/** `HostTag` is the SAME `HostId` enum the adapter registry uses
+ *  (re-exported so existing imports keep working); it used to be the
+ *  literal `'claude'`. Widening it to `HostId` lets one manifest serve every
+ *  host via the orchestrator's host filter + {@link buildHostArtifacts}. */
 type HostTag = HostId;
 interface ManifestEntry {
     /** Repo-relative POSIX path (forward slashes). Orchestrator joins with root. */
     path: string;
     mode: WriteMode;
+    /** Opt-in flag for a DOC-ONLY seed — a file whose only job is to be read by a
+     *  human. On an upgrade, a seed still byte-identical to what an older Noir
+     *  shipped is refreshed in place rather than staying frozen at that older
+     *  text forever; one the user edited is never refreshed (it goes to the
+     *  ordinary conflict flow, which keeps the user's bytes by default).
+     *
+     *  Honored on the upgrade emit only. A fresh `init`/`create` either creates
+     *  the file or leaves it alone, and `sync` does not emit seeds at all, so
+     *  neither can observe the flag — the behavior change is confined to the one
+     *  command a user runs to bring an initialized project up to date.
+     *
+     *  DOC-ONLY SEEDS ONLY. A file the user owns the contents of must never carry
+     *  this flag: `.noir/.env`, `.noir/config.yml` and `.noir/project.id` are
+     *  theirs to shape, and an upgrade that rewrote one of them would destroy
+     *  exactly the work this engine exists to protect. Co-owned files (managed
+     *  blocks) must not set it either — they have a three-way merge that
+     *  preserves user edits, which is the better tool for a shared file.
+     *
+     *  Which recorded seed the bytes are compared against is declared separately
+     *  in {@link REFRESHABLE_SEED_KIND}. */
+    refreshIfStale?: true;
     /** Host tag; entry is skipped when opts.host !== entry.host.
      *  Undefined = host-agnostic (every host emits it). */
     host?: HostTag;
@@ -202,7 +363,7 @@ interface ManifestEntry {
     dedupSubstring?: string;
 }
 type BuildManifestContext = {
-    /** Absolute repo root. Added in S10 so {@link buildHostArtifacts} can resolve
+    /** Absolute repo root. Needed so {@link buildHostArtifacts} can resolve
      *  absolute adapter paths (`adapter.mcpConfigPath({root})`, etc.) to the
      *  manifest's repo-relative POSIX shape. */
     root: string;
@@ -226,7 +387,7 @@ type BuildManifestContext = {
     stack?: StackInfo;
 };
 /** Co-owned NOIR.md auto-brief region. Defined locally (not exported from
- *  core) because core's keystone-K named instances cover only the three
+ *  core) because core's own named block instances cover only the three
  *  regions core itself writes (context/rules/ignore); the brief is the
  *  scaffold engine's own. Uses the SAME `managedBlock()` factory so marker
  *  shape stays consistent with the rest of the family. */
@@ -239,14 +400,14 @@ declare const MANIFEST_PATH_PARITY: ReadonlyArray<[
  * Build the manifest for a given ctx. Pure (no I/O). The orchestrator calls
  * this once per scaffold run; tests assert the shape is stable.
  *
- * S10 structure: the manifest is now `[...hostAgnosticEntries(ctx), ...hostSpecificEntries(ctx)]`
+ * The manifest is `[...hostAgnosticEntries(ctx), ...hostSpecificEntries(ctx)]`
  * where the host-specific half comes from {@link buildHostArtifacts} (driven by
  * `resolveAdapter(ctx.host)`). The host-agnostic half is unchanged from v1.1
  * (canonical `.noir/` store + ignore files). {@link buildHostArtifacts}
  * emits AGENTS.md ONLY for agents-md/cursor/opencode (claude/gemini use their
  * own CLAUDE.md/GEMINI.md — emitting AGENTS.md too would double-import .noir/).
  *
- * Mode-tagging rationale per artifact (see S-T1 report for the full table):
+ * Mode-tagging rationale per artifact:
  *  - `project.id`  → skipIfExists. First init writes a fresh id; re-init MUST
  *    NOT overwrite — that would orphan the indexed store DB named after it.
  *  - `config.yml`  → skipIfExists. User-owned; the seed is written once.
@@ -374,7 +535,7 @@ declare function mergeThreeWay(base: string, ours: string, theirs: string, style
 /**
  * Migration model — Nx-style declarative upgrade scripts, hand-rolled.
  *
- * Per the Slice S design (S-OQ2 resolved → inline conflict markers, never
+ * Per the migration design (inline conflict markers, never
  * interactive prompts), every migration script:
  *  - is a small, IDEMPOTENT TypeScript function (`run(root, opts) → result`).
  *    Re-running it on an already-migrated tree is a no-op (or produces the
@@ -385,10 +546,10 @@ declare function mergeThreeWay(base: string, ours: string, theirs: string, style
  *    `result.conflicts` so the caller (doctor/CI) can fail loudly with a
  *    reviewable artifact rather than hang on a prompt.
  *
- * The registry ({@link MIGRATIONS}) carries two entries: the synthetic
- * `1.0.0 → 1.0.0` smoke test that exercises the runner end-to-end, and the
- * first real version-to-version migration, `1.0.0 → 1.1.0`. The synthetic one
- * is the copy-pasteable template for the next contributor.
+ * The registry ({@link MIGRATIONS}) carries three entries: the synthetic
+ * `1.0.0 → 1.0.0` smoke test that exercises the runner end-to-end, and two real
+ * version-to-version migrations, `1.0.0 → 1.1.0` and `1.1.0 → 1.2.0`. The
+ * synthetic one is the copy-pasteable template for the next contributor.
  */
 interface MigrationContext {
     /** Absolute repo root the migration operates on. */
@@ -447,8 +608,8 @@ declare function runMigrations(root: string, from: string | null, to: string, op
  *  order is documentation only — oldest step first. */
 declare const MIGRATIONS: readonly MigrationScript[];
 /** Write git-style inline conflict markers around `theirs`/`ours` so a human
- *  or AI agent can resolve later. This is the CI-safe fallback the spec locks
- *  in (S-OQ2) — no interactive prompts, ever. */
+ *  or AI agent can resolve later. This is the CI-safe fallback —
+ *  no interactive prompts, ever. */
 declare function applyInlineConflict(ours: string, theirs: string, oursLabel?: string, theirsLabel?: string): string;
 /** Apply `(ours, theirs)` to a region: if they're equal, return `ours` (no
  *  conflict); otherwise emit inline markers. Migration authors should prefer
@@ -461,7 +622,7 @@ declare function applyWithConflict(ours: string, theirs: string, path: string):
 };
 
 /**
- * Scaffold orchestrator. One function the cli (S-T2) calls for `noir init`,
+ * Scaffold orchestrator. One function the cli calls for `noir init`,
  * `noir create`, and `noir sync`; mode selects the manifest subset + how
  * project identity is resolved.
  *
@@ -500,19 +661,19 @@ interface ScaffoldOptions {
      *  initialization without ever touching a file the user owns. Only meaningful
      *  with mode `'init'`. */
     upgrade?: boolean;
-    /** SP-A: re-scaffold even when the target is already initialized (bypasses
+    /** Re-scaffold even when the target is already initialized (bypasses
      *    the already-initialized no-op guard). Does NOT bypass `assertSafeRoot`
      *    — root-safety is hard, never bypassable. */
     force?: boolean;
     /** Preview: compute the same written/skipped/migrated lists without touching
      *    disk. `noir doctor`/CI use this to report drift. */
     dryRun?: boolean;
-    /** SP-C: policy for a `regenerate` file that exists and DIFFERS from the
+    /** Policy for a `regenerate` file that exists and DIFFERS from the
      *    template, when no {@link onConflict} callback is provided. Default
      *    `'overwrite'` is byte-backward-compatible. `'preserve'` keeps the user's
      *    file (the non-TTY / CI default in the cli). */
     conflictPolicy?: 'overwrite' | 'preserve';
-    /** SP-C: per-file conflict resolver — the UI seam (the engine stays UI-free;
+    /** Per-file conflict resolver — the UI seam (the engine stays UI-free;
      *    the cli injects a @clack-based resolver). Called when a `regenerate`
      *    file exists and differs from the template. The return type widens to
      *    accept a rich shape carrying `applyToAll` — the engine then reuses the
@@ -525,7 +686,8 @@ interface ScaffoldOptions {
      *  run always has a base. Set to `false` (CLI `--no-merge-regions`) to
      *  restore strip-replace. Supports BOTH single-region (NOIR.md, ignores) AND
      *  multi-region (CLAUDE.md CONTEXT+RULES) managed files — the multi-region
-     *  path shipped with SP-H (`managedBlocks` + `mergeManagedRegion` per block). */
+     *  path merges managed regions per block (`managedBlocks` +
+     *  `mergeManagedRegion`). */
     mergeManagedRegions?: boolean;
     /** Explicit interactivity signal. The engine reads THIS (not
      *  `process.env`), so a direct API/embedded caller in a TTY that does NOT
@@ -539,10 +701,24 @@ interface ScaffoldResult {
     written: string[];
     /** Repo-relative paths skipIfExists'd (already present). */
     skipped: string[];
-    /** SP-D: repo-relative `regenerate` paths skipped because byte-identical to
+    /** Repo-relative `regenerate` paths skipped because byte-identical to
      *  the template (content-hash dedup — no rewrite). */
     identical: string[];
-    /** SP-A: true when the already-initialized guard short-circuited (a bare
+    /** Repo-relative doc-only seed paths REPLACED on the upgrade path because the
+     *  copy on disk was still byte-identical to an older Noir's shipped text —
+     *  i.e. the user never edited it, so a newer seed costs nothing. Reported
+     *  separately from {@link written} because the distinction is the whole point
+     *  of the refresh: a caller (and the user reading the summary) can tell
+     *  "Noir updated documentation you never touched" apart from "Noir created
+     *  something new".
+     *
+     *  A seed the user DID edit is never listed here — it goes through the
+     *  ordinary conflict flow, so it appears in {@link written} only when a
+     *  resolver explicitly chose to replace it (or `--force` did). Empty on every
+     *  other run: a fresh `init`/`create` has nothing to compare against and
+     *  `sync` does not emit seeds. */
+    refreshed: string[];
+    /** True when the already-initialized guard short-circuited (a bare
      *  `noir init`/`create` on an initialized project). Callers (init.ts/create.ts)
      *  gate skills emission + the "initialized" message on this — a no-op must NOT
      *  re-emit skills or claim it initialized. */
@@ -551,6 +727,10 @@ interface ScaffoldResult {
     migrationsRan: string[];
     /** Migration conflicts (repo-relative or `<runner>:…`), when upgrade ran. */
     migrationConflicts: string[];
+    /** Repo-relative paths a migration CHANGED (wrote or refreshed), when upgrade
+     *  ran — reported separately from {@link refreshed} so callers can name
+     *  "migrated" files (e.g. `.noir/config.yml`) apart from doc seeds. */
+    migrationChanged: string[];
     stack: StackInfo;
     projectId: string;
     fromVersion: string | null;
@@ -589,7 +769,7 @@ interface ConflictRecord {
     /** Resolution the engine applied (`replace`/`preserve`/`rename`/…). */
     resolution: ConflictResolution;
 }
-/** SP-C — context passed to {@link ScaffoldOptions.onConflict} when a
+/** Context passed to {@link ScaffoldOptions.onConflict} when a
  *  `regenerate` file exists and differs from the template. */
 interface ConflictContext {
     /** Repo-relative path of the conflicting file. */
@@ -600,7 +780,7 @@ interface ConflictContext {
     proposed: string;
     /** Artifact class — drives apply-to-all memory scope (`regenerate` shares
      *  one decision across a run; `managedBlock`/`managedBlocks` stay per-file).
-     *  Defaults to `'regenerate'` for backward compatibility with SP-C resolvers
+     *  Defaults to `'regenerate'` for backward compatibility with older resolvers
      *  that pre-date the field (the engine always sets it). */
     mode?: 'regenerate' | 'managedBlock' | 'managedBlocks' | 'skipIfExists' | 'skill' | 'markdown' | 'artifact';
     /** LCS similarity (0-1) between existing and proposed. Cheap signal for
@@ -610,7 +790,7 @@ interface ConflictContext {
      *  bytes WITH zdiff3 conflict markers (selecting `'merge'` writes this). */
     mergedWithMarkers?: string;
 }
-/** SP-C — how to resolve a `regenerate` conflict. */
+/** How to resolve a `regenerate` conflict. */
 type ConflictResolution = 'replace' | 'preserve' | 'rename' | 'duplicate' | 'cancel' | 'merge';
 /** The resolver may return a bare {@link ConflictResolution} (scope
  *  `'one'`) OR a rich shape carrying `applyToAll`. The engine unwraps both; when
@@ -623,7 +803,7 @@ type ConflictResolverReturn = ConflictResolution | {
 };
 /**
  * Refuse to scaffold when `root` is — or is inside — a `.noir/` directory.
- * (SP-A) Running `noir init`/`create`/`sync` while cwd = `.noir/` would
+ * Running `noir init`/`create`/`sync` while cwd = `.noir/` would
  * otherwise mint a FRESH project id (because `<root>/.noir/project.id` is
  * absent) and build a NESTED second project (`.noir/.noir/`, `.noir/CLAUDE.md`,
  * `.noir/.claude/skills/`, …) — the duplicate-`.noir` bug. The walk ascends the
@@ -652,7 +832,7 @@ declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
  */
 /** The scaffold version this build of @noir-ai/create ships. Bumped atomically
  *  whenever a manifest entry, template, or migration changes shape. */
-declare const CURRENT_SCAFFOLD_VERSION = "1.1.0";
+declare const CURRENT_SCAFFOLD_VERSION = "1.2.0";
 /** Path to the stamp file under `root`. Exposed for tests + doctor. */
 declare function scaffoldVersionPath(root: string): string;
 /** Read the applied scaffold version, or `null` if the stamp is absent/unparseable.
@@ -662,7 +842,7 @@ declare function readScaffoldVersion(root: string): string | null;
  *  LAST so a crash mid-scaffold leaves an old/absent stamp rather than a
  *  misleading fresh one.
  *
- *  N2: routed through the package's atomic `regenerate()` writer (tmp+rename in
+ *  Routed through the package's atomic `regenerate()` writer (tmp+rename in
  *  the same dir) for consistency with the rest of the engine's durable writes —
  *  a half-written stamp would mislead `noir doctor`/`init --upgrade`, so the
  *  stamp deserves the same crash-atomicity as `.mcp.json` and the NOIR.md brief. */
@@ -698,4 +878,4 @@ declare function loadTemplate(name: string): string;
 /** Resolve a template name to its absolute path (for diagnostics + tests). */
 declare function templatesDir(): string;
 
-export { BRIEF_BLOCK, type BuildHostArtifactsContext, type BuildManifestContext, CURRENT_SCAFFOLD_VERSION, type ConflictContext, type ConflictRecord, type ConflictResolution, type ConflictResolverReturn, type DiffLine, type HostTag, MANIFEST_PATH_PARITY, MIGRATIONS, type ManifestEntry, type MergeResult, type MigrationContext, type MigrationResult, type MigrationScript, type ScaffoldMode, type ScaffoldOptions, type ScaffoldResult, type StackInfo, type WriteMode, type WriteOutcome, ancestorsPath, applyInlineConflict, applyWithConflict, assertSafeRoot, buildHostArtifacts, buildManifest, buildRegion, detectStack, lineDiff, loadTemplate, managedBlock, mergeThreeWay, readAncestors, readScaffoldVersion, regenerate, render, runMigrations, scaffold, scaffoldVersionPath, skipIfExists, templatesDir, writeAncestors, writeScaffoldVersion, zdiff3Region };
+export { BRIEF_BLOCK, type BuildHostArtifactsContext, type BuildManifestContext, CURRENT_SCAFFOLD_VERSION, type ConflictContext, type ConflictRecord, type ConflictResolution, type ConflictResolverReturn, type DiffLine, type HostTag, MANIFEST_PATH_PARITY, MIGRATIONS, type ManifestEntry, type MergeResult, type MigrationContext, type MigrationResult, type MigrationScript, SEED_TEMPLATE_HISTORY, type ScaffoldMode, type ScaffoldOptions, type ScaffoldResult, type SeedTemplateHistoryEntry, type StackInfo, type WriteMode, type WriteOutcome, ancestorsPath, applyInlineConflict, applyWithConflict, assertSafeRoot, buildHostArtifacts, buildManifest, buildRegion, detectStack, isStaleSeed, lineDiff, loadTemplate, managedBlock, mergeThreeWay, readAncestors, readScaffoldVersion, regenerate, render, runMigrations, scaffold, scaffoldVersionPath, skipIfExists, templatesDir, writeAncestors, writeScaffoldVersion, zdiff3Region };