@orkestrel/scaffold 0.0.50 → 0.0.52

package/dist/host/guides/scaffold.md

@@ -12,8 +12,8 @@ does not work. Scaffold makes the shared set data — a vendored data root shipp
 — and gives it verbs: create a workspace from it, report how a workspace differs from it, and
 write the difference back.
 
-Every code fence below is illustrative. [`tests/guides.test.ts`](../tests/guides.test.ts) keeps the
-command reference aligned with the executable and transcribes the pure blueprint-default,
+Every following code fence is illustrative. [`tests/guides.test.ts`](../tests/guides.test.ts)
+keeps the command reference aligned with the executable and transcribes the pure blueprint-default,
 compile-refusal, and error-narrowing fences. A trailing comment in another fence is this guide's
 claim rather than a measured answer; the driven examples are the ones the shipped declarations
 print. Limits states what that leaves unproven and what covers it instead.
@@ -391,8 +391,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
 
 `Compiler` implements `CompilerInterface`, `Materializer` implements `MaterializerInterface`, and
 `Upstream` implements `UpstreamInterface`. Each class exposes exactly its interface's members and
-nothing more, so the interface tables below describe the classes too. `WriteTransaction` publishes
-no interface and is documented directly.
+nothing more, so the following interface tables describe the classes too. `WriteTransaction`
+publishes no interface and is documented directly.
 
 #### `CompilerInterface`
 
@@ -566,9 +566,9 @@ carries the fact and the vendor list keeps its own separate job.
 The root Vite configuration defines and registers the fixed `guides` project only when the derived
 blueprint carries `guides`. Reading verbs set that fact only when `tests/guides.test.ts` is a
 physical file with that exact path case. A directory or a case-folded spelling does not select it. A
-fresh workspace therefore carries no guides project or script. A developer who adds the proof must
-also add the exact `test:guides` script line that the plan reports; the manifest remains
-birth-owned.
+fresh workspace therefore carries no guides project or script. When a developer adds the proof,
+`audit` reports the exact `test:guides` script line until `repair` or `overwrite` appends it through
+the writable script region. The rest of the manifest remains birth-owned.
 
 The plan-reading verbs compare the Vitest project set named by the target manifest with the
 project set the planned root configuration registers. Every planned proof project must also be
@@ -585,31 +585,36 @@ static Vitest fact to infer.
 `audit` still completes the comparison and reports one non-blocking `projects` question when its
 selection includes `configs`. A scoped audit that excludes `configs` omits that question. For a
 literal absent project, its advisory tells the developer to register the project or remove the
-script. For a planned project absent from the gate chains, the advisory checks the direct
-`test:<project>` script. When the script is absent, the advisory gives the exact line to add to
-`package.json`. When the script is declared but ungated, the advisory names the script and the gate
-chain that must invoke it, without repeating a script line. When `configs` is selected, `repair` and
-`overwrite` refuse either mismatch before writing. Their refusal names the `configs` group, the
-manifest and planned `vite.config.ts` conflict, and the option to exclude `configs` from
-`--groups`. A selection that excludes `configs` proceeds. An advisory alone does not make an aligned
-target drift.
-
-Scaffold writes one part of the manifest rather than advising on it: the script region a publishing
-workspace needs for the generated distribution proof. `repair` and `overwrite` write
-`test:distribution` and `prepublishOnly` there. A declared value is overwritten only when it is
-already the value being written, or, for `prepublishOnly`, the one predecessor the region accepts —
-the same gate chain without the release row. The overwrite happens in place, so every byte outside
-the replaced ranges survives, and a description, a keyword, a key order, and a script the workspace
-added are untouched. A script the manifest does not declare is appended after the last declared one,
-copying that section's indentation. `catalog` writes no script region; it names the ranges alone.
-
-A value matching neither is a chain the workspace author wrote. The region is then refused whole,
-without a byte moving, and the range region is still written. The `projects` advisory reads the
-manifest as a write would leave it, so a region scaffold writes for itself raises no question, while
-a refused region leaves the target's own text standing and the advisory reports whichever half is
-outstanding: the exact `test:distribution` line to paste, or the gate chain that must invoke a
-script the manifest already declares. The refusal covers the region rather than one script, so a
-manifest never holds one written value beside one refused one.
+script. For a planned project absent from the gate chains, the advisory reads the manifest after a
+writable script projection. The `scripts` question owns an absent direct `test:<project>` line. The
+`projects` question names the direct script and the gate chain that must invoke it when the projected
+region still leaves the project ungated. When `configs` is selected, `repair` and `overwrite` refuse
+an unregistered or ungated project before writing. Their refusal names the `configs` group, the
+manifest and planned `vite.config.ts` conflict, and the option to exclude `configs` from `--groups`.
+A selection that excludes `configs` proceeds. An advisory alone does not make an aligned target
+drift.
+
+Scaffold writes one part of the manifest rather than advising on it: the writable script region.
+`repair` and `overwrite` write every direct `test:<project>` script the blueprint computes,
+`test:probe`, and `test:bench`. A publishing workspace also receives `test:distribution`, `prepack`,
+and `prepublishOnly`. The `test`, `check`, `build`, `dev`, `serve`, `show`, `format`, `lint`, `clean`,
+and `copy` gate chains stay maintainer-owned. A declared value is overwritten only when it is already
+the value being written or is a recognized generated predecessor. The overwrite happens in place,
+so every byte outside the replaced ranges survives. A target's descriptions, keywords, extra
+scripts, and manifest key order survive byte-for-byte. A script the manifest does not declare is
+appended after the last declared one, copying that section's indentation. `catalog` writes no script
+region; it names the ranges alone.
+
+A value matching neither is a script the workspace author wrote. The region writer retains that
+value byte-for-byte and reports its name, declared value, and planned value. Each other planned
+script is decided independently: an absent script appends, the planned value stands, and an accepted
+predecessor upgrades in place. Extra scripts remain byte-identical. A planned key holding a
+non-string value or a `scripts` field that is not an object still refuses the whole region with no
+script byte moving. `audit` reports absent and differing scripts separately in its non-blocking
+`scripts` question, and the terminal audit in `repair` and `overwrite` keeps every retained
+difference visible. Other selected writes still proceed. The `projects` question reports only a
+direct script the manifest declares but the maintainer-owned gate chain does not invoke after
+projection.
 
 The same plan-reading verbs compare the tooling set the derived blueprint plans against
 `dependencies` and `devDependencies` together. A missing planned package produces one non-blocking
@@ -640,7 +645,8 @@ maintainer wrote rather than what scaffold seeded.
 That reading carries a release-skew limit. A seeded setup module is birth-owned, so `repair` reports
 it aligned and never rewrites it. A target keeps the seed of the release that materialized it. When
 a release moves a planned seed, scaffold raises the question on every target materialized before it,
-against a module scaffold wrote and no maintainer touched.
+against a module scaffold wrote and no maintainer touched. `audit` compares each setup module only
+with the seed the installed release plans, and it retains no earlier seed bytes.
 `tests/setupGlobal.ts` is the module that can meet it, because it is the one seeded with more than
 the empty string. A maintainer meeting that question closes it by writing the proof it asks for, or
 by taking the seed the installed release plans.
@@ -741,7 +747,7 @@ One published environment owns the package root directly. Several published envi
 never runs. The gate reports that as a non-blocking `src` question rather than refusing the compile,
 because the shape is chosen once and read afterwards: `new` refuses the advisory, while `audit` and
 `repair` need the plan to describe and restore a target that already has that shape. A library
-caller creating a workspace holds the same refusal, and the Compile section below states it.
+caller creating a workspace holds the same refusal, and the Compile section states it.
 
 `bin`, `setup`, `guides`, `integration`, `conformance`, `service`, `vendors`, `global`, and
 `showcase` are structural facts. Each is set only when the workspace physically ships the directory
@@ -758,14 +764,12 @@ generated before that file existed and still registers no `integration` project,
 fails with `integration has no project factory or configuration` until a plan-writing verb
 regenerates it.
 
-`repair` alone does not close that, and refusing is correct rather than a gap. `package.json` is
-birth-owned, so the verb cannot add the project's script, and it will not register a project the
-manifest reaches from no gate. It exits 1 naming the target and writes nothing.
+`repair` closes the direct-script half through the writable manifest region. It still refuses to
+register a project that the maintainer-owned gate chains do not reach.
 
-Adding a structural proof is therefore these steps, in order: write the file; declare its
-`test:<project>` script and invoke that script from a gate chain; then run `repair`, which
-regenerates the root configuration and registers the project. `audit` reports whichever piece is
-still outstanding at each step.
+When you add a structural proof, write the file and invoke its planned `test:<project>` script from
+a gate chain. Then run `repair`; it appends the direct script, regenerates the root configuration,
+and registers the project. `audit` reports whichever piece is still outstanding at each step.
 
 `distribution` is not a field at all. A published `src` environment is its whole condition, read
 from the `src` axis the blueprint already carries. The proof packs and installs the published
@@ -1184,9 +1188,9 @@ A workspace's file set is a function of its axes plus its structural facts. Noth
 except the manifest.
 
 - One computed artifact: `package.json`, with the entry points, `exports` map, scripts, and
-  development dependencies its selection implies. A publishing manifest carries
-  `"prepack": "npm run build"` so a publish rebuilds `dist/` and cannot ship a stale artifact;
-  the hook is publish-time only, and every generated distribution proof passes
+  development dependencies its selection implies. In publishing workspaces, the emitted `prepack`
+  script runs `npm run build` so a publish rebuilds `dist/` and cannot ship a stale artifact; the
+  hook is publish-time only, and every generated distribution proof passes
   `--ignore-scripts` to `npm pack` so a suite never re-runs the build it already gates.
 - One template artifact per configuration file the selection needs: the root `tsconfig.json` and
   `vite.config.ts`, plus a Vite config and a scoped TypeScript config per selected environment and