@noir-ai/create 1.19.2-beta.1 → 1.19.3-beta.1

package/dist/index.d.ts

@@ -9,13 +9,13 @@ declare function ancestorsPath(root: string): string;
 declare function readAncestors(root: string): Record<string, string>;
 /** Write the ancestor map. Ensures `.noir/` exists (a standalone caller may
  *  invoke this before the scaffold has created the dir). Derived state, so the
- *  plain write (no tmp) is fine. Content-hash dedup — when the serialized
+ *  plain write (no tmp) is fine. Content-hash dedup: when the serialized
  *  bytes equal what is already on disk, the rewrite is skipped so a no-op sync
  *  leaves ancestors.json untouched (no mtime/git churn). */
 declare function writeAncestors(root: string, map: Record<string, string>): void;
 
 /**
- * Emit a host's lifecycle-hook config on demand — the write-once `mergeJson`
+ * Emit a host's lifecycle-hook config on demand: the write-once `mergeJson`
  * hook the scaffold deliberately does NOT re-emit on `noir init --upgrade` or
  * `noir sync`. This is the explicit restore path (`noir hooks sync`): it runs
  * the same `adapter.emitHooks` seam the scaffold uses and dispatches each entry
@@ -25,7 +25,7 @@ declare function writeAncestors(root: string, map: Record<string, string>): void
  * command instead of being left as-is; the user's other keys and non-Noir hooks
  * are never touched.
  *
- * Pure filesystem work — no daemon, no store, no prompt. A host with no hook
+ * Pure filesystem work: no daemon, no store, no prompt. A host with no hook
  * surface (agents-md, opencode) returns an empty outcome list.
  */
 /** One host hook-config write performed by {@link emitHooksToFile}. */
@@ -47,7 +47,7 @@ declare function emitHooksToFile(root: string, host: HostId, opts?: {
 
 /**
  * READ-ONLY stack detection. Probes for well-known marker files under `root`
- * and reports ONLY what is present — never assumes. The result feeds path
+ * and reports ONLY what is present: never assumes. The result feeds path
  * adaptation (where to drop `.claude/` vs `.cursor/` etc., future), ignore-file
  * selection, and the onboarding TUI's confirm step.
  *
@@ -85,7 +85,7 @@ interface StackInfo {
     ci: string | null;
     /**
      * Existing AI instruction files found under root.
-     * Never clobbered — the scaffold confirms the write strategy (skip/add-section/
+     * Never clobbered: the scaffold confirms the write strategy (skip/add-section/
      * standalone).
      */
     existingAiFiles: {
@@ -233,19 +233,19 @@ declare const SEED_TEMPLATE_HISTORY: readonly SeedTemplateHistoryEntry[];
 declare function isStaleSeed(seed: SeedKind, fileBytes: string, currentRender: string): boolean;
 
 /**
- * The three-mode writer — generalizes the earlier `writeManagedRegion` into
+ * 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 artifact matrix:
  *
- *  - {@link regenerate}    — pure pointers (`.mcp.json`, `NOIR.md` brief, …).
+ *  - {@link regenerate}   : pure pointers (`.mcp.json`, `NOIR.md` brief, …).
  *                           Always overwritten, atomically.
- *  - {@link managedBlock}  — co-owned files (`CLAUDE.md` context/rules,
+ *  - {@link managedBlock} : co-owned files (`CLAUDE.md` context/rules,
  *                           `.gitignore` noir block, …). DELEGATES to
  *                           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.
- *  - {@link skipIfExists}  — user-owned seeds (`RULES.md`, `config.yml`,
+ *  - {@link skipIfExists} : user-owned seeds (`RULES.md`, `config.yml`,
  *                           `project.id`). Write once; never clobber.
  *
  * The orchestrator (`scaffold.ts`) is the only intended caller; the per-mode
@@ -258,7 +258,7 @@ interface WriteOutcome {
     path: string;
     mode: WriteMode;
     /** true when bytes hit disk; false for skipIfExists no-ops. regenerate and
-     *  managedBlock always write (managedBlock may write identical bytes — that
+     *  managedBlock always write (managedBlock may write identical bytes: that
      *  still counts as a write for telemetry purposes; the file IS up to date). */
     written: boolean;
 }
@@ -267,7 +267,7 @@ interface WriteOutcome {
  *  file (the pointer files this is used for are read by the host agent first —
  *  a truncated CLAUDE.md/.mcp.json would break the very startup Noir serves).
  *
- *  Parent directories are NOT created here — the orchestrator does that once
+ *  Parent directories are NOT created here: the orchestrator does that once
  *  for the whole manifest so a missing dir is a single, attributable failure
  *  rather than N silent ones inside the writer.
  */
@@ -281,7 +281,7 @@ declare function managedBlock(absPath: string, block: ManagedBlock, regionText:
 /** Assemble `<begin>\n<body>\n<end>\n` for a managed block. Centralized here so
  *  every caller (manifest rendering, tests, future migrations) produces the
  *  exact byte shape `writeManagedRegion` strips/expects. The trailing newline
- *  is part of the contract — `stripManagedBlock`'s regex eats a trailing `\n`
+ *  is part of the contract: `stripManagedBlock`'s regex eats a trailing `\n`
  *  so re-runs stay idempotent instead of accumulating blank lines.
  *
  *  `body` is `trimEnd()`-ed before wrapping so template authors can keep the
@@ -298,7 +298,7 @@ declare function buildRegion(block: ManagedBlock, body: string): string;
  *  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
  *  target already exists: this writer's whole contract is "never touch an
- *  existing file", and that includes its permissions. POSIX-only — Windows
+ *  existing file", and that includes its permissions. POSIX-only: Windows
  *  permissions are ACL-based and the mode is dropped there.
  *
  *  The write goes through `atomicWriteFile` (tmp + rename) rather than a bare
@@ -312,11 +312,11 @@ declare function buildRegion(block: ManagedBlock, body: string): string;
  *  emit, which tightens a group/world-readable credential to 0600. */
 declare function skipIfExists(absPath: string, content: string, fileMode?: number): WriteOutcome;
 /** What happened when the owner-only mode was re-asserted on a credential
- *  file — see {@link ensureOwnerOnly}. */
+ *  file: see {@link ensureOwnerOnly}. */
 type EnvMode = FileModeOutcome;
 
 /**
- * Declarative scaffold manifest — the single source of truth for what
+ * Declarative scaffold manifest: the single source of truth for what
  * `init` / `create` / `sync` emit. Each entry is one artifact, tagged with its
  * write {@link WriteMode} so the orchestrator can dispatch without knowing
  * what's inside.
@@ -330,7 +330,7 @@ type EnvMode = FileModeOutcome;
  * 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
+ * `noir init` stays BYTE-IDENTICAL to v1.1: REMOVED the additive
  * root `AGENTS.md` (it was double-importing `.noir/NOIR.md` + RULES.md via
  * CLAUDE.md's existing @-imports; claude's native surface is CLAUDE.md alone).
  *
@@ -348,7 +348,7 @@ 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
+    /** 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
@@ -356,14 +356,14 @@ interface ManifestEntry {
      *
      *  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
+     *  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
+     *  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
@@ -375,7 +375,7 @@ interface ManifestEntry {
     /** Required for `managedBlock` mode: the named block to re-emit. */
     block?: ManagedBlock;
     /** Literal content (`regenerate`/`skipIfExists`) or literal region BODY
-     *  (`managedBlock` — the orchestrator wraps it with the block markers).
+     *  (`managedBlock`: the orchestrator wraps it with the block markers).
      *  Mutually exclusive with {@link template}. */
     content?: string;
     /** Template name (resolved by `template-loader`) for content/body.
@@ -384,7 +384,7 @@ interface ManifestEntry {
     /** One-line human description for `noir doctor` + logs. */
     description?: string;
     /** Permission for a NEWLY created file (e.g. `0o600` for a credential seed).
-     *  Applied only on creation — the `skipIfExists` contract means an existing
+     *  Applied only on creation: the `skipIfExists` contract means an existing
      *  file is not even opened. The orchestrator forwards this to the writer and
      *  reports it on the result as {@link ScaffoldResult.fileModes}; the mode of
      *  an existing credential file is re-asserted separately (`ensureOwnerOnly`).
@@ -395,7 +395,7 @@ interface ManifestEntry {
     /** Required for `mergeJson` mode: the JSON patch object (or a template that
      *  renders to one). Merged into the existing file, preserving user keys. */
     patch?: Record<string, unknown>;
-    /** Required for `mergeJson` mode: dedup substring for `hooks.*` entries — an
+    /** Required for `mergeJson` mode: dedup substring for `hooks.*` entries: an
      *  existing entry whose command contains this is NOT re-added. */
     dedupSubstring?: string;
 }
@@ -418,7 +418,7 @@ type BuildManifestContext = {
      *  MCP clients that don't read shell profiles can spawn the server. See
      *  `resolveNoirCommand()` in @noir-ai/core. */
     command: string;
-    /** Detected stack — drives stack-aware ignore emission (.npmignore /
+    /** Detected stack: drives stack-aware ignore emission (.npmignore /
      *  .prettierignore only for JS; .dockerignore only when a Dockerfile is
      *  present; an unknown/empty stack ⇒ all four, for backward compat). */
     stack?: StackInfo;
@@ -429,7 +429,7 @@ type BuildManifestContext = {
      *  drops the working-rules seed from the manifest, so no command emits or
      *  backfills `.noir/rules/RULES.md` for a project that opted out. Undefined
      *  (the schema's default state, and every caller that predates the switch)
-     *  means enabled — a project with no `rules:` block emits the seed exactly
+     *  means enabled: a project with no `rules:` block emits the seed exactly
      *  as before. A file already on disk is never removed: dropping the entry
      *  removes the emission, not the file. */
     rulesEnabled?: boolean;
@@ -453,11 +453,11 @@ declare const MANIFEST_PATH_PARITY: ReadonlyArray<[
  * `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/).
+ * own CLAUDE.md/GEMINI.md: emitting AGENTS.md too would double-import .noir/).
  *
  * 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.
+ *    NOT overwrite: that would orphan the indexed store DB named after it.
  *  - `config.yml`  → skipIfExists. User-owned; the seed is written once.
  *    (The seed renders `host: {{host}}` so a `--host gemini` init persists the
  *    chosen host for `noir sync` to read back.)
@@ -470,7 +470,7 @@ declare const MANIFEST_PATH_PARITY: ReadonlyArray<[
  */
 declare function buildManifest(ctx: BuildManifestContext): ManifestEntry[];
 /** Context shape passed to {@link buildHostArtifacts}. A strict subset of
- *  {@link BuildManifestContext} (no `projectId`/`host` — the adapter IS the
+ *  {@link BuildManifestContext} (no `projectId`/`host`: the adapter IS the
  *  resolved host, and host artifacts never need the project id). Exported
  *  separately so callers + tests can name the narrower contract. */
 interface BuildHostArtifactsContext {
@@ -490,10 +490,10 @@ interface BuildHostArtifactsContext {
 }
 /**
  * Materialize the host-specific manifest entries from a resolved adapter.
- * SINGLE entry point — no scattered `if (host === '…')` conditionals in the
+ * SINGLE entry point: no scattered `if (host === '…')` conditionals in the
  * orchestrator. Returns entries in emission order:
  *
- *   1. **AGENTS.md** (universal baseline) — `regenerate` at
+ *   1. **AGENTS.md** (universal baseline): `regenerate` at
  *      `adapter.agentsMdPath(ctx)` (default `<root>/AGENTS.md`), content from
  *      the shared `emitAgentsMd(ctx)` helper. Emitted ONLY for hosts whose
  *      `emitContext` IS the AGENTS.md content (agents-md, cursor, opencode) —
@@ -503,10 +503,10 @@ interface BuildHostArtifactsContext {
  *      `@`-imports the canonical `.noir/` sources; emitting AGENTS.md too
  *      would IMPORT THOSE FILES TWICE into the host's context (2× tokens +
  *      drift risk), so for those two hosts AGENTS.md is SKIPPED. (Claude Code
- *      still discovers AGENTS.md at the repo root when present — users who
+ *      still discovers AGENTS.md at the repo root when present: users who
  *      want the universal file can drop one in by hand; Noir's auto-emission
  *      stays single-source per host.)
- *   2. **Host-native context file** — emitted ONLY for hosts whose `emitContext`
+ *   2. **Host-native context file**: emitted ONLY for hosts whose `emitContext`
  *      is NOT the AGENTS.md content (i.e. the host has its OWN context file
  *      with a distinct syntax). Concretely: claude → `CLAUDE.md` (CONTEXT +
  *      RULES managed blocks, byte-identical to v1.1 via templates); gemini →
@@ -514,7 +514,7 @@ interface BuildHostArtifactsContext {
  *      import syntax). For `agents-md`/`cursor`/`opencode` the context IS the
  *      AGENTS.md (already emitted in step 1) → SKIP to avoid a duplicate.
  *      Rules live INSIDE the host's context file: claude's in CLAUDE.md,
- *      gemini's in GEMINI.md, agents-md/cursor/opencode's in AGENTS.md — NO
+ *      gemini's in GEMINI.md, agents-md/cursor/opencode's in AGENTS.md: NO
  *      host emits a separate rules file. (The prior cursor
  *      `.cursor/rules/noir-contract.mdc` host-rules pointer was REMOVED: it
  *      collided with the cursor flat-skill prune of `noir-*.mdc` under
@@ -524,20 +524,20 @@ interface BuildHostArtifactsContext {
  *      That rules import/block is dropped for every host when
  *      `ctx.rulesEnabled` is false: the switch withholds the seed, so pointing
  *      a host at it would resolve to nothing. The context import is unaffected
- *      — the switch gates the rules, not the brief. A host file that already
+ *     : the switch gates the rules, not the brief. A host file that already
  *      carries the rules region from when the switch was on keeps it: dropping
  *      the entry stops the emission, and nothing here rewrites a region out of
  *      an existing file.
- *   3. **Host MCP config** — `regenerate` at `adapter.mcpConfigPath(ctx)`
+ *   3. **Host MCP config**: `regenerate` at `adapter.mcpConfigPath(ctx)`
  *      (default `<root>/.mcp.json` for claude), content from
  *      `adapter.emitMcpConfig(ctx, {transport,url})`. Claude KEEPS the template
  *      path (byte-identical parity with v1.1 + the .mcp.json parity test that
  *      compares against `claudeAdapter.emitMcpConfig`) for a repo that has not
- *      joined a workspace; a joined repo — one carrying a `.noir/workspace.json`
- *      marker — gets the workspace entry instead, on every host, whatever
+ *      joined a workspace; a joined repo: one carrying a `.noir/workspace.json`
+ *      marker: gets the workspace entry instead, on every host, whatever
  *      transport the run asked for (see the entry's own comment below).
  *
- * Skills are OUT OF SCOPE here — the cli composes `emitSkillsToDir` with
+ * Skills are OUT OF SCOPE here: the cli composes `emitSkillsToDir` with
  * `adapter.skillsDir` + the host's `CompileTarget` (claude → `.claude/skills/`
  * as SKILL.md; cursor → `.cursor/rules/<skill>.mdc` FLAT; gemini/
  * agents-md/opencode have no skill dir → skip).
@@ -558,7 +558,7 @@ interface MergeResult {
  * `-` red, context dim). Reuses the SAME LCS machinery {@link mergeThreeWay}
  * does so there is exactly one line-diff algorithm in the package.
  *
- * `context` (default 3) — number of unchanged lines to keep around each hunk
+ * `context` (default 3): number of unchanged lines to keep around each hunk
  * (git-style). 0 → every non-equal line stands alone; large → whole-file blob.
  * The resolver uses the default; tests pin to a specific shape.
  */
@@ -577,7 +577,7 @@ declare function lineDiff(base: string, head: string, context?: number): DiffLin
  *   <theirs lines>
  *   `>>>>>>> theirs`
  *
- * `diff3(zdiff3)` writes the SAME shape — included here so the engine + clack
+ * `diff3(zdiff3)` writes the SAME shape: included here so the engine + clack
  * resolver have a single source of truth for marker layout. Returns the marked
  * region body (no outer delimiters); the caller wraps it with surrounding
  * context.
@@ -588,22 +588,22 @@ declare function zdiff3Region(ours: readonly string[], base: readonly string[],
  * new template) with `base` (the last-emitted ancestor). Line-level diff3:
  * changes in disjoint line ranges merge; overlapping changes become inline
  * conflict markers. Default marker shape is the minimal diff3 form
- * (`<<<<<<< ours` / `=======` / `>>>>>>> theirs`) — byte-identical to v1.2 so
+ * (`<<<<<<< ours` / `=======` / `>>>>>>> theirs`): byte-identical to v1.2 so
  * {@link mergeManagedRegion} stays regression-anchored. Pass `'zdiff3'` to
- * include the base section (`||||||| base`) — used by the conflict resolver's
+ * include the base section (`||||||| base`): used by the conflict resolver's
  * 6th "merge (with conflict markers)" option. Pure + deterministic
  * (no IO) so it's unit-testable.
  */
 declare function mergeThreeWay(base: string, ours: string, theirs: string, style?: 'minimal' | 'zdiff3'): MergeResult;
 
 /**
- * Migration model — Nx-style declarative upgrade scripts, hand-rolled.
+ * Migration model: Nx-style declarative upgrade scripts, hand-rolled.
  *
  * 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
- *    same conflict markers again — also safe).
+ *    same conflict markers again: also safe).
  *  - NEVER prompts. `--no-input` CI must survive. When a migration cannot
  *    reconcile a co-edited region, it writes git-style conflict markers
  *    (`<<<<<<<` / `=======` / `>>>>>>>`) into the file and records the path in
@@ -625,7 +625,7 @@ interface MigrationContext {
     dryRun?: boolean;
     /** The project's `rules.enabled` switch, when the caller knows it. False
      *  tells a migration that `.noir/rules/RULES.md` is not part of this project
-     *  — the scaffold withholds the seed — so a migration must not write that
+     * : the scaffold withholds the seed: so a migration must not write that
      *  file back, however convincing its evidence for a refresh. Undefined means
      *  enabled, which is the state of every project that predates the switch. */
     rulesEnabled?: boolean;
@@ -659,7 +659,7 @@ interface MigrationScript {
  * skipped. Within the window, scripts run sorted by `to` ascending so a
  * multi-step upgrade (1.0.0 → 1.1.0 → 1.2.0) composes in order.
  *
- * The runner NEVER throws on a per-script failure — it captures the error,
+ * The runner NEVER throws on a per-script failure: it captures the error,
  * records a synthetic conflict entry (`<path>__error`), and continues so a
  * single broken migration doesn't block the rest of the chain. The orchestrator
  * decides whether non-empty `conflicts` is a hard failure (init --upgrade) or a
@@ -677,7 +677,7 @@ declare function runMigrations(root: string, from: string | null, to: string, op
 };
 
 /** The registry. The runner sorts the selected window by `to`, so declaration
- *  order is documentation only — oldest step first. */
+ *  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 —
@@ -686,7 +686,7 @@ declare function applyInlineConflict(ours: string, theirs: string, oursLabel?: s
 /** Apply `(ours, theirs)` to a region: if they're equal, return `ours` (no
  *  conflict); otherwise emit inline markers. Migration authors should prefer
  *  this over {@link applyInlineConflict} when the "no change needed" case is
- *  common — it keeps re-runs truly idempotent (no spurious markers on a clean
+ *  common: it keeps re-runs truly idempotent (no spurious markers on a clean
  *  tree). */
 declare function applyWithConflict(ours: string, theirs: string, path: string): {
     text: string;
@@ -735,7 +735,7 @@ interface ScaffoldOptions {
     upgrade?: boolean;
     /** 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. */
+     *   : 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. */
@@ -748,10 +748,10 @@ interface ScaffoldOptions {
      *    `'overwrite'` is byte-backward-compatible. `'preserve'` keeps the user's
      *    file (the non-TTY / CI default in the cli). */
     conflictPolicy?: 'overwrite' | 'preserve';
-    /** 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
+     *    accept a rich shape carrying `applyToAll`: the engine then reuses the
      *    decision for the rest of the run (per artifact CLASS). */
     onConflict?: (ctx: ConflictContext) => Promise<ConflictResolverReturn> | ConflictResolverReturn;
     /** Three-way merge managed regions (base/ours/theirs) using a persisted
@@ -760,7 +760,7 @@ interface ScaffoldOptions {
      *  DEFAULT TRUE: ancestor capture is unconditional, so the first merge
      *  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
+     *  multi-region (CLAUDE.md CONTEXT+RULES) managed files: the multi-region
      *  path merges managed regions per block (`managedBlocks` +
      *  `mergeManagedRegion`). */
     mergeManagedRegions?: boolean;
@@ -777,7 +777,7 @@ interface ScaffoldResult {
     /** Repo-relative paths skipIfExists'd (already present). */
     skipped: string[];
     /** Repo-relative `regenerate` paths skipped because byte-identical to
-     *  the template (content-hash dedup — no rewrite). */
+     *  the template (content-hash dedup: no rewrite). */
     identical: string[];
     /** 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 —
@@ -787,7 +787,7 @@ interface ScaffoldResult {
      *  "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
+     *  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
@@ -795,7 +795,7 @@ interface ScaffoldResult {
     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
+     *  gate skills emission + the "initialized" message on this: a no-op must NOT
      *  re-emit skills or claim it initialized. */
     noop: boolean;
     /** Migration steps executed (`<from>→<to>`), when upgrade ran. */
@@ -803,7 +803,7 @@ interface ScaffoldResult {
     /** 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
+     *  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;
@@ -812,7 +812,7 @@ interface ScaffoldResult {
     toVersion: string;
     /** The host actually emitted (post-default). */
     host: HostTag;
-    /** Structured conflict report — one record per file that existed AND
+    /** Structured conflict report: one record per file that existed AND
      *  differed from the proposed bytes (regenerate conflict path). Populated in
      *  `--json`/`--no-input`/non-TTY runs (no prompt fires) so a CI/JSON caller
      *  can see exactly which files diverged + how they were resolved, without
@@ -823,19 +823,19 @@ interface ScaffoldResult {
      *  (repo-relative path → mode), i.e. the {@link ManifestEntry.fileMode} of a
      *  `skipIfExists` entry that had no file on disk. A real run reports the mode
      *  it applied; a `dryRun` reports the mode it WOULD apply (the predictor's
-     *  job — the caller can preview `.noir/.env` at 0600 without writing it).
+     *  job: the caller can preview `.noir/.env` at 0600 without writing it).
      *  Paths the entry skipped (already present) are absent: an existing file's
      *  mode is never changed. Optional so existing external constructors of this
      *  type (test stubs) stay valid; `scaffold()` always populates it. */
     fileModes?: Record<string, number>;
-    /** What the run did to the permissions of `.noir/.env` — the outcome of
+    /** What the run did to the permissions of `.noir/.env`: the outcome of
      *  {@link ensureOwnerOnly}, which is called on every run that may write, in
      *  every mode, because the seeded file's 0600 mode is applied only when it is
      *  created.
      *  `'healed'` means a group/world-readable file was tightened to 0600, so a
      *  caller can report the fix instead of leaving the user to notice it in a
      *  later diagnostic; `'unchanged'` and `'unsupported'` mean nothing needed
-     *  doing (or the platform has no POSIX mode bits) — the `'unchanged'` a fresh
+     *  doing (or the platform has no POSIX mode bits): the `'unchanged'` a fresh
      *  `create` reports, whose seed was written 0600 in the same run. Absent on a
      *  dry run, which must not touch disk. Optional so existing external
      *  constructors of this type stay valid. */
@@ -845,7 +845,7 @@ interface ScaffoldResult {
 interface ConflictRecord {
     /** Repo-relative path of the conflicting file. */
     path: string;
-    /** Artifact class — drives apply-to-all memory scope + report grouping. */
+    /** Artifact class: drives apply-to-all memory scope + report grouping. */
     mode: ConflictContext['mode'];
     /** LCS similarity (0-1) between existing and proposed. */
     similarity?: number;
@@ -865,7 +865,7 @@ interface ConflictContext {
     existing: string;
     /** The content the scaffold would write. */
     proposed: string;
-    /** Artifact class — drives apply-to-all memory scope (`regenerate` shares
+    /** 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 older resolvers
      *  that pre-date the field (the engine always sets it). */
@@ -883,32 +883,32 @@ type ConflictResolution = 'replace' | 'preserve' | 'rename' | 'duplicate' | 'can
  *  `'one'`) OR a rich shape carrying `applyToAll`. The engine unwraps both; when
  *  `applyToAll` is true it stores the choice in its per-run memory keyed by
  *  artifact CLASS (`regenerate` shares one decision across a run; managedBlock
- *  stays per-file regardless — user edits there need individual review). */
+ *  stays per-file regardless: user edits there need individual review). */
 type ConflictResolverReturn = ConflictResolution | {
     resolution: ConflictResolution;
     applyToAll?: boolean;
 };
 /**
- * Refuse to scaffold when `root` is — or is inside — a `.noir/` directory.
+ * Refuse to scaffold when `root` is: or is inside: a `.noir/` directory.
  * 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
+ * `.noir/.claude/skills/`, …): the duplicate-`.noir` bug. The walk ascends the
  * ancestor chain only, so a legitimate project root that merely CONTAINS a
  * `.noir/` store is never flagged. String-based: works whether or not `root`
  * exists on disk yet (so `noir create <new-dir>` is still guarded).
  *
- * Hard against literal `.noir` path segments — NOT bypassable by `--force`
+ * Hard against literal `.noir` path segments: NOT bypassable by `--force`
  * (which is reserved for the already-initialized no-op). NOTE: the walk is
  * string-based, so a symlink whose TARGET is inside `.noir/` is not resolved
- * (a local self-foot-gun only — the caller controls `root` — not externally
+ * (a local self-foot-gun only: the caller controls `root`: not externally
  * exploitable); in practice `--cwd`/positional roots are literal paths.
  */
 declare function assertSafeRoot(root: string): void;
 declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
 
 /**
- * Scaffold version stamp — Noir's equivalent of Copier's `last-applied`.
+ * Scaffold version stamp: Noir's equivalent of Copier's `last-applied`.
  * Stored at `.noir/scaffold-version` as a single `noir-scaffold=<semver>` line
  * so `noir init --upgrade` / `noir doctor` can diff against
  * {@link CURRENT_SCAFFOLD_VERSION} and decide which migrations to run.
@@ -928,7 +928,7 @@ declare const CURRENT_SCAFFOLD_VERSION = "1.5.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.
- *  Never throws — doctor must keep reporting even on a malformed stamp. */
+ *  Never throws: doctor must keep reporting even on a malformed stamp. */
 declare function readScaffoldVersion(root: string): string | null;
 /** Write the stamp, creating `.noir/` if needed. The orchestrator writes it
  *  LAST so a crash mid-scaffold leaves an old/absent stamp rather than a
@@ -946,10 +946,10 @@ declare function writeScaffoldVersion(root: string, version: string): void;
  * map lookup is sufficient and keeps `@noir-ai/create` dependency-light.
  *
  * Semantics (documented):
- *  - Tokens are `{{ name }}` / `{{name}}` — any amount of ASCII whitespace
+ *  - Tokens are `{{ name }}` / `{{name}}`: any amount of ASCII whitespace
  *    inside the braces is permitted. The name is trimmed.
  *  - Known vars (value is a string) are substituted verbatim. NO escaping is
- *    applied — callers must pre-escape for the target format (JSON/YAML/MD).
+ *    applied: callers must pre-escape for the target format (JSON/YAML/MD).
  *    This is intentional: the engine renders into multiple formats and a
  *    single universal escaper would be wrong for at least one of them.
  *  - Unknown vars (not in `vars`, or value `undefined`) → the original token
@@ -964,7 +964,7 @@ declare function writeScaffoldVersion(root: string, version: string): void;
 declare function render(template: string, vars: Record<string, unknown>): string;
 
 /** Read a template's raw text by name (e.g. `noir.md.tmpl`). Throws on missing
- *  — an unknown template is a manifest bug and should fail loudly, not render
+ * : an unknown template is a manifest bug and should fail loudly, not render
  *  an empty string silently. */
 declare function loadTemplate(name: string): string;
 /** Resolve a template name to its absolute path (for diagnostics + tests). */