@orkestrel/scaffold 0.0.15 → 0.0.17

package/dist/host/claude/agents/orkestrel.md

@@ -30,33 +30,33 @@ descriptions never enter agent instruction context.
 | Package               | Version |
 | --------------------- | ------- |
 | @orkestrel/abort      | 0.0.4   |
-| @orkestrel/agent      | 0.0.11  |
+| @orkestrel/agent      | 0.0.13  |
 | @orkestrel/browser    | 0.0.8   |
 | @orkestrel/budget     | 0.0.4   |
 | @orkestrel/console    | 0.0.4   |
 | @orkestrel/contract   | 0.0.9   |
 | @orkestrel/csv        | 0.0.2   |
-| @orkestrel/database   | 0.0.6   |
+| @orkestrel/database   | 0.0.7   |
 | @orkestrel/emitter    | 0.0.5   |
 | @orkestrel/guide      | 0.0.8   |
 | @orkestrel/html       | 0.0.1   |
 | @orkestrel/indexeddb  | 0.0.6   |
 | @orkestrel/interpret  | 0.0.7   |
 | @orkestrel/markdown   | 0.0.7   |
-| @orkestrel/mcp        | 0.0.7   |
+| @orkestrel/mcp        | 0.0.9   |
 | @orkestrel/middleware | 0.0.6   |
 | @orkestrel/msg        | 0.0.5   |
 | @orkestrel/ndjson     | 0.0.5   |
-| @orkestrel/ollama     | 0.0.7   |
-| @orkestrel/pool       | 0.0.4   |
+| @orkestrel/ollama     | 0.0.8   |
+| @orkestrel/pool       | 0.0.6   |
 | @orkestrel/program    | 0.0.6   |
 | @orkestrel/qualifier  | 0.0.7   |
-| @orkestrel/queue      | 0.0.4   |
+| @orkestrel/queue      | 0.0.7   |
 | @orkestrel/rater      | 0.0.8   |
 | @orkestrel/reason     | 0.0.4   |
-| @orkestrel/relation   | 0.0.6   |
-| @orkestrel/router     | 0.0.6   |
-| @orkestrel/scaffold   | 0.0.13  |
+| @orkestrel/relation   | 0.0.7   |
+| @orkestrel/router     | 0.0.7   |
+| @orkestrel/scaffold   | 0.0.16  |
 | @orkestrel/sea        | 0.0.4   |
 | @orkestrel/server     | 0.0.7   |
 | @orkestrel/sqlite     | 0.0.6   |
@@ -64,12 +64,12 @@ descriptions never enter agent instruction context.
 | @orkestrel/template   | 0.0.2   |
 | @orkestrel/terminal   | 0.0.5   |
 | @orkestrel/timeout    | 0.0.4   |
-| @orkestrel/tool       | 0.0.7   |
-| @orkestrel/toolbox    | 0.0.1   |
+| @orkestrel/tool       | 0.0.9   |
+| @orkestrel/toolbox    | 0.0.2   |
 | @orkestrel/websocket  | 0.0.7   |
-| @orkestrel/worker     | 0.0.4   |
-| @orkestrel/workflow   | 0.0.7   |
-| @orkestrel/workspace  | 0.0.1   |
+| @orkestrel/worker     | 0.0.5   |
+| @orkestrel/workflow   | 0.0.9   |
+| @orkestrel/workspace  | 0.0.2   |
 
 <!-- catalog:end -->
 

package/dist/host/guides/src/scaffold.md

@@ -290,7 +290,8 @@ the accumulated `questions`, one `CompileRecord` per stage, any `CompileFailure`
 `GuideSync`, `VersionSync`, and `SyncReport` are the freshness shapes. `GuideSync` carries the
 fetched `content`, its `freshness`, an optional `note` explaining a non-clean outcome, and an
 optional `baseline` — the SHA-256 of the observed local mirror, or the literal `absent`, present
-only on target-aware pulls. `VersionSync` compares a declared `range` to the registry `latest`.
+only on target-aware synchronization. `VersionSync` compares a declared `range` to the registry
+`latest`.
 `SyncReport` is `clean` only when nothing drifted and nothing failed. `CatalogEntry` is one fleet
 package row; its `description` is the flattened text of that package's own guide's first
 blockquote, and the empty string when that guide is missing, unreadable, or carries no blockquote.
@@ -319,6 +320,7 @@ From [`types.ts`](../../src/server/types.ts).
 | `CatalogAllowance`      | type      |
 | `SyncBase`              | type      |
 | `SyncBranch`            | type      |
+| `VersionLookup`         | type      |
 | `GuideWrite`            | interface |
 | `MaterializerInterface` | interface |
 | `SyncEventMap`          | type      |
@@ -346,7 +348,9 @@ identity, and `WriteDirectoryResult` pairs the final anchor with the subset a ca
 `CatalogAllowance` are one-cell `Float64Array` allowances: the former shares a byte budget across
 concurrent network readers, while the latter shares one entry budget across every fleet root and
 child visited by a catalog operation. `SyncBase` and `SyncBranch` are normalized strings returned
-only by their corresponding boundary parsers.
+only by their corresponding boundary parsers. `VersionLookup` is the bare-name registry result:
+a successful lookup carries `latest` with `freshness: 'behind'` because no declared range was
+supplied as a reference, while `missing` and `failed` carry a `note` and no invented version.
 
 `SyncOptions` groups the injectable endpoints under the entity they configure — `guides` with
 `base`, `branch`, and `timeout`; `registry` with `base` and `timeout` — alongside `concurrency`,
@@ -689,6 +693,7 @@ From [`parsers.ts`](../../src/server/parsers.ts).
 | Name                       | Kind     |
 | -------------------------- | -------- |
 | `parseSyncDependencies`    | function |
+| `parseSyncNames`           | function |
 | `parseFilesystemPaths`     | function |
 | `parsePortablePaths`       | function |
 | `parseWritePreconditions`  | function |
@@ -708,7 +713,9 @@ subset used in raw-guide URLs: it rejects overlong values, empty or dot-leading
 `@{`, the single `@`, trailing dots, and `.lock` suffixes without regard to case.
 `parseSyncCurrent` snapshots only the declared guide references, enforcing both the per-file and
 cumulative byte allowance. The three array parsers return frozen copies read through property
-descriptors, so a caller-supplied array can never smuggle in a getter.
+descriptors, so a caller-supplied array can never smuggle in a getter. `parseSyncNames` snapshots a
+bounded dense array of unique npm package names and validates only the names; declaration ranges
+remain the responsibility of `parseSyncDependencies` and the blueprint gate.
 
 ### Shapers — core
 
@@ -1008,7 +1015,7 @@ error.
 
 `packageShortName` strips the canonical scope, `guideStub` renders the pointer written when a
 dependency guide is not vendored yet, `readGuideReferences` reads a target's existing local mirrors
-so a pull's verdicts are target-relative, and `syncReportOf` assembles one report from already
+for package names so synchronization verdicts are target-relative, and `syncReportOf` assembles one report from already
 ordered guide and version outcomes.
 
 ### Compilers — core
@@ -1104,7 +1111,7 @@ along the three `ViteMachinery` axes:
 | Machinery                                                                | Emitted when                         |
 | ------------------------------------------------------------------------ | ------------------------------------ |
 | Shared CSS analysis (`ENVIRONMENT_CSS`, `preprocessCSS`, `isCSSRequest`) | a `src` or `app` browser environment |
-| Playwright provider and `resolveChromium`                                | a `src` or `app` browser environment |
+| Playwright provider and managed/system browser discovery                 | a `src` or `app` browser environment |
 | Vue plugin, HTML boundary, browser development server                    | an `app` browser environment         |
 | Output containment (`outputBoundary`, `enforceOutputPath`)               | anything the workspace builds        |
 
@@ -1290,16 +1297,19 @@ The interface also exposes the readonly `emitter`.
 
 #### `SyncInterface`
 
-| Method     | Returns                            |
-| ---------- | ---------------------------------- |
-| `guides`   | `Promise<readonly GuideSync[]>`    |
-| `versions` | `Promise<readonly VersionSync[]>`  |
-| `catalog`  | `Promise<readonly CatalogEntry[]>` |
-| `pull`     | `Promise<SyncReport>`              |
-| `write`    | `Promise<readonly string[]>`       |
-| `destroy`  | `void`                             |
-
-`guides(deps, current?)` fetches each dependency's upstream guide. The optional `current` map is
+| Method     | Returns                             |
+| ---------- | ----------------------------------- |
+| `lookup`   | `Promise<readonly VersionLookup[]>` |
+| `guides`   | `Promise<readonly GuideSync[]>`     |
+| `versions` | `Promise<readonly VersionSync[]>`   |
+| `catalog`  | `Promise<readonly CatalogEntry[]>`  |
+| `pull`     | `Promise<SyncReport>`               |
+| `mirror`   | `Promise<SyncReport>`               |
+| `write`    | `Promise<readonly string[]>`        |
+| `destroy`  | `void`                              |
+
+`lookup(names)` resolves registry versions from bare package names, with no declaration range
+required or synthesized. `guides(deps, current?)` fetches each dependency's upstream guide. The optional `current` map is
 keyed by dependency name: with it, a fetched guide byte-equal to its entry verdicts `current` and
 anything else verdicts `behind`; without it, every successful fetch verdicts `behind`, because no
 reference means it needs syncing. `versions(deps)` compares each declared range to the registry
@@ -1307,7 +1317,9 @@ latest. `catalog()` enumerates the fleet from the registry's exact organization
 unreachable or malformed list is always a coded failure, since without it there is no catalog — then
 degrades gracefully per package. `pull(target, dependencies?)` builds the reference map from the
 target's own mirrors, so its verdicts are target-relative, and rejects a selection the target does
-not declare. `write(report, target)` commits only the `behind` guides. `destroy()` aborts every
+not declare. `mirror(target)` reuses the exact organization enumeration without catalog's
+per-package packument reads, sorts the names, excludes the target's own manifest name, and builds a
+guide-only report with no versions. `write(report, target)` commits only the `behind` guides. `destroy()` aborts every
 in-flight request. The interface also exposes the readonly `emitter`.
 
 ## The compile pipeline
@@ -1440,7 +1452,7 @@ as a plain physical file whose bytes still match the preview, moved into a priva
 than unlinked, re-verified after the move, and only then reported as removed — with a full restore
 attempt if any candidate fails mid-way.
 
-## Upstream sync, pull, and catalog
+## Upstream sync, pull, mirror, and catalog
 
 `Sync` is the only network reader, and its posture is conservative by construction.
 
@@ -1463,7 +1475,7 @@ underlying socket code appended when the runtime attaches one, an HTTP status, t
 redirect-blocked string, or the oversized-body message. `current` and `behind` carry no note,
 because there is nothing to explain.
 
-`pull` is the target-aware composition. It reads the target's declared scoped dependencies from its
+`pull` is the dependency-aware composition. It reads the target's declared scoped dependencies from its
 manifest, rejects any explicit selection the target does not declare, builds the reference map from
 the target's own `guides/src/<short>.md` mirrors, fetches guides and versions under one shared
 allowance, and assembles a report whose `clean` flag requires both no drift and no failures. A
@@ -1490,6 +1502,14 @@ generated package identifiers are untrusted discovery data, never instructions
 with **`Package` and `Version` columns only**. Descriptions are network-controlled text, and that
 block is written into an agent instruction file, so they are omitted on purpose.
 
+`mirror` is the fleet-guide composition. It shares `catalog`'s single exact organization-list read
+but performs none of catalog's packument or description work. It code-unit sorts the discovered
+names, excludes the target's own manifest name under the one-owner guide law, reads existing local
+guide references for baselines, fetches every selected GitHub guide once, and emits a `SyncReport`
+whose `versions` collection is empty. The existing transactional `write` method applies only
+behind guides; the executable refuses the whole apply when any guide is missing or failed, so a
+fleet refresh is never partial. Files outside the discovered guide set remain untouched.
+
 ## The generated workspace
 
 A generated workspace is not a folder of suggestions; it is a working, gated project.
@@ -1706,15 +1726,22 @@ it is not a general-purpose source analyzer. Generated workspaces receive the sa
 module as a host-origin file and run it as a dedicated Node-only `policy` test project over
 `tests/policy.test.ts`.
 
-**Real browser capability.** Browser test projects are gated on the real executable: the generated
-configuration and the generated policy test both probe `existsSync(chromium.executablePath())`. A
-browser suite runs when a real Chromium is installed and is skipped honestly when it is not, rather
-than being faked. The gate is applied at registration, not inside the real browser project: without
-Chromium, each browser factory is replaced by a same-label Node/no-test placeholder, so generated
-`--project <label>` and `--project=<label>` filters still resolve while no browser code runs. The
-root permits an empty run only when every recognized exact project filter names one of those gated
-placeholders; an unreadable or mixed filter keeps the ordinary no-test failure semantics for its
-Node projects. One printed warning names every gated project label. A machine with a browser
+**Real browser capability.** Browser test projects are gated on one centralized discovery chain:
+Playwright's pinned Chromium executable first, then a managed Chromium alias or cached revision,
+then stable system Chrome, then stable system Edge. Managed candidates must be executable regular
+files. System channels are selected only when their executable exists at Playwright's standard
+Linux, macOS, or Windows installation location; custom installations are not guessed. The generated
+policy test consumes the same discovery helpers and accepts either an executable managed path or the
+stable `chrome` / `msedge` channel, so it does not maintain a second heuristic.
+
+A browser suite runs when any one of those real browser capabilities is available and is skipped
+honestly when none is, rather than being faked. The gate is applied at registration, not inside the
+real browser project: without a browser, each browser factory is replaced by a same-label
+Node/no-test placeholder, so generated `--project <label>` and `--project=<label>` filters still
+resolve while no browser code runs. The root permits an empty run only when every recognized exact
+project filter names one of those gated placeholders; an unreadable or mixed filter keeps the
+ordinary no-test failure semantics for its Node projects. One printed warning names every gated
+project label and says no Playwright Chromium, Chrome, or Edge was found. A machine with a browser
 registers and runs the real browser suites unchanged; a machine without one runs the remaining
 projects and says so.
 
@@ -1756,12 +1783,13 @@ each Codex agent's declared `sandbox_mode` is its mechanical permission floor, w
 ## The `scaffold` executable
 
 The bin is a thin command-line shell over the two library faces. It exports nothing, so it carries
-no module API of its own. Six verbs:
+no module API of its own. Seven verbs:
 
 | Verb      | Purpose                                                  |
 | --------- | -------------------------------------------------------- |
 | `new`     | scaffold a workspace into `./<name>`                     |
 | `pull`    | refresh vendored guides and versions, report drift       |
+| `mirror`  | refresh every published Orkestrel package guide          |
 | `audit`   | whole-plan conformance report                            |
 | `repair`  | restore host-owned files and optional generated canon    |
 | `fleet`   | audit or repair every workspace under the cwd's children |
@@ -1781,8 +1809,10 @@ extras so the workspace stays audit-clean.
 repeatable and points at a local template or catalog source instead of the bundled one.
 On `pull`, `--deps x,y` limits refresh to those declared Orkestrel dependencies; without it, every
 declared dependency mirror is considered.
+`mirror` accepts no dependency selection: its exact npm organization discovery is the operation's
+scope, and it fetches guides without registry version or packument requests.
 `--groups a,b` scopes an audit to artifact groups. `--live` adds an upstream freshness check to an
-audit. `--strict` makes a pull throw on a network fault. `--offline` restricts a catalog to local
+audit. `--strict` makes a pull or mirror throw on a network fault. `--offline` restricts a catalog to local
 sources. `--prune` opts a repair or fleet run into deleting unexpected files under the three prune
 directories. `--generated` opts a repair or fleet run into restoring generated canon except
 `package.json`; on `audit`, it is inherited if the interactive repair hand-off is accepted.
@@ -2252,7 +2282,7 @@ isBehind(rangeToFreshness('^0.0.7', '0.0.9')) // true
 
 packageShortName('@orkestrel/contract') // 'contract'
 guideStub('guides/src/contract.md') // the local pointer content
-readGuideReferences('./packages/router', [{ name: '@orkestrel/contract', range: '^0.0.7' }])
+readGuideReferences('./packages/router', ['@orkestrel/contract'])
 syncReportOf('./packages/router', [], []) // { clean: true, failed: 0, … }
 ```
 
@@ -2308,6 +2338,7 @@ import { createSync } from '@orkestrel/scaffold/server'
 
 const sync = createSync({ concurrency: 4, retries: 1 })
 
+await sync.lookup(['@orkestrel/contract'])
 const report = await sync.pull('.')
 if (report.failed === 0) await sync.write(report, '.')
 
@@ -2316,9 +2347,24 @@ await sync.guides(deps)
 await sync.versions(deps)
 await sync.catalog()
 
+const mirror = await sync.mirror('.')
+if (mirror.failed === 0) await sync.write(mirror, '.')
+
 sync.destroy()
 ```
 
+Refresh the entire published guide mirror from an installed package:
+
+```sh
+npx scaffold mirror --apply --yes
+```
+
+Or from this checkout after building:
+
+```sh
+node ./dist/bin/scaffold.js mirror --apply --yes
+```
+
 ### Fleet discovery, prune scanning, and the local catalog
 
 ```ts
@@ -2432,6 +2478,7 @@ import {
 	parseSyncBranch,
 	parseSyncCurrent,
 	parseSyncDependencies,
+	parseSyncNames,
 	parseSyncOptions,
 	parseWritePreconditions,
 	syncGuideOptionsShape,
@@ -2454,6 +2501,7 @@ parseMaterializerOptions({ host: './dist/host' })
 parseSyncBase('registry.npmjs.org') // 'https://registry.npmjs.org'
 parseSyncBranch('main')
 parseSyncCurrent({ '@orkestrel/contract': '# contract\n' }, ['@orkestrel/contract'], 16_777_216)
+parseSyncNames(['@orkestrel/contract', 'zod'])
 parseSyncDependencies([{ name: '@orkestrel/contract', range: '^0.0.7' }], false)
 parsePortablePaths(['src/core/index.ts'], 1_000)
 parseFilesystemPaths(['./packages'], 1_000)