@orkestrel/scaffold 0.0.1 → 0.0.3

package/README.md

@@ -26,10 +26,10 @@ ctrl-c at any prompt and nothing is written. Prefer scripting instead? Every
 flag from the guided flow works standalone:
 
 ```sh
-npx scaffold new mypackage --surfaces core --apply
+npx scaffold new mypackage --src core --app core,browser,server --apply
 ```
 
-In scripts and CI, every verb is dry-run by default and fully non-interactive —
+In scripts, every verb is dry-run by default and fully non-interactive —
 add `--apply` and/or `--yes` to make it write, `--json` for one machine-readable
 value instead of prose. Every write destination resolves under the current
 directory — equal to it or nested beneath — so the CLI is safe to run as a
@@ -39,14 +39,14 @@ global command anywhere; `--from` may point anywhere (read-only).
 directly — PowerShell mangles npm's `--` passthrough, so avoid
 `npm run scaffold -- …` there.
 
-**TLS:** the CLI trusts the OS certificate store automatically, so `fetch` calls
-succeed behind a corporate TLS-inspecting proxy the same way npm and browsers
-do; `NODE_EXTRA_CA_CERTS` adds custom PEMs on top.
+**TLS:** when the running Node release exposes system-CA controls, the CLI adds
+the operating-system certificate store. Earlier supported Node 22 releases use
+Node's default roots. `NODE_EXTRA_CA_CERTS` adds custom PEMs in either case.
 
 ## CLI
 
 ```sh
-scaffold new [name] [--surfaces <list>] [--deps <list>] [--apply] [--yes] [--json]
+scaffold new [name] [--src <list>] [--app <list>] [--deps <list>] [--apply] [--yes] [--json]
 scaffold pull [--apply] [--yes] [--json]
 scaffold audit [--live] [--json]
 scaffold repair [--prune] [--apply] [--yes] [--json]
@@ -59,7 +59,10 @@ scripting form. Exit codes: `0` clean/success, `1` drift or failure, `2` usage
 error.
 
 - **`new [name]`** — drafts a `Blueprint` and compiles it into a `Plan`; dry-run by
-  default (prints a review), `--apply` writes the package to disk. `--deps` names
+  default (prints a review), `--apply` writes the workspace to disk. `--src`
+  selects published source environments and `--app` independently selects private application
+  environments; at least one is required. App-only workspaces are unscoped and `"private": true`,
+  while mixed workspaces retain the published `@orkestrel/*` package boundary. `--deps` names
   `@orkestrel/*` runtime dependencies (installed as `dependencies`), resolving an
   absent `@range` to the registry's `latest`; run bare on a terminal, it lands as an
   interactive question. Other npm packages are not a `new`-time flag — hand-add them to
@@ -67,18 +70,21 @@ error.
   its plan from your `package.json` and stays clean over the addition.
 - **`pull`** — fetches the latest vendored dependency guides and registry versions
   for an existing package and reports drift.
-- **`audit`** — a whole-plan conformance report: diffs a target against the FULL plan
-  its own manifest implies (host AND generated artifacts alike) and reports drift as
-  data, findings and all; exits nonzero the moment any drift is found, so it gates CI
-  cleanly. `--live` additionally checks upstream guide/version freshness — `audit` is the
-  ONLY verb that carries `--live`.
+- **`audit`** — a conformance report over the artifacts the plan actually gates: the
+  shared host-origin files (presence, or exact bytes once hydrated) AND the generated
+  configs/manifest (exact UTF-8 bytes); reports drift as data, findings and all; exits nonzero
+  the moment any drift is found. Starter files — source/test
+  stubs, starter guides, README — are written once at scaffold time and are
+  legitimately outgrown, so they are birth-only and never audited; the build and
+  parity gates police their substance instead. `--live` additionally checks upstream
+  guide/version freshness — `audit` is the ONLY verb that carries `--live`.
 - **`repair`** — restores the shared HOST set only (generated source/tests/configs are
   never touched); re-derives the plan from the audit and re-applies only the drifted
   host artifacts; dry-run by default, `--apply` writes the fixes, `--prune` also removes
   target-only files the plan no longer declares (asked as a separate destructive
   question when run bare).
 - **`fleet`** — audits/repairs the shared, host-owned files (`AGENTS.md`,
-  `CLAUDE.md`, `.claude/`, `scripts/`, the shared dotfiles, …) across every
+  `CLAUDE.md`, `.agents/` skills, `.claude/`, `.codex/`, `scripts/`, the shared dotfiles, …) across every
   `@orkestrel` repo that is an IMMEDIATE CHILD of the current directory — no root
   flag; the scope is always your checkouts folder, so `cd` there first (`repair`
   is the single-repo counterpart, run from inside one repo); dry-run by default,
@@ -96,18 +102,29 @@ error.
 ```ts
 import { blueprint, createCompiler } from '@orkestrel/scaffold'
 
-const draft = blueprint({ name: '@orkestrel/example', surfaces: ['core'] })
+const draft = blueprint('example', {
+	src: ['core'],
+	app: ['core', 'browser', 'server'],
+})
 const compiler = createCompiler()
-const plan = compiler.compile(draft)
+const scaffolding = compiler.compile(draft)
+scaffolding.plan?.artifacts.length
+compiler.destroy()
 ```
 
-`@orkestrel/scaffold/server` carries the impure surface — `createMaterializer`
+`@orkestrel/scaffold/server` carries the impure API — `createMaterializer`
 (writes a `Plan` to disk) and `createSync` (the only part of the system that
 touches the network, fetching dependency guides and registry versions).
 
+The built host uses an exact `{ entries, roots }` manifest. Staging preflights
+containment and portable file-tree collisions, builds in a temporary sibling,
+and swaps only after completion. Reading validates that every declared storage
+file exists, every staged file is declared, and every destination root is
+complete; a present but corrupt or truncated manifest fails closed.
+
 ## Guides
 
-For the full surface, see [`guides/src/scaffold.md`](guides/src/scaffold.md).
+For the full API, see [`guides/src/scaffold.md`](guides/src/scaffold.md).
 
 ## License