usesteady 0.1.0-alpha.52 → 0.1.0-alpha.54

package/CHANGELOG.md

@@ -1,5 +1,261 @@
 # Changelog
 
+## 0.1.0-alpha.54 - Onboarding quickstart and starter templates
+
+**Released:** May 2026
+**npm tag:** `alpha` - `npm install -g usesteady@alpha`
+
+Second ship from the **Product Capability Track**. Goal: a brand-new
+user can go from install to a successful, reviewed workflow in under
+five minutes, without reading internal docs. Bounded scope: two new
+read-only subcommands and a README walkthrough. Zero authority impact.
+
+### What ships
+
+Three onboarding surfaces, all read-only:
+
+- `usesteady quickstart` - one-screen orientation. What UseSteady is,
+  how to discover capabilities, how to pick a template, how to
+  customize and run, plain-language approval explanation, where
+  workflows execute, and how to stop safely. Pure text renderer;
+  byte-for-byte deterministic.
+- `usesteady templates` - prints a list of safe starter workflows
+  with one-line purposes.
+- `usesteady templates <name>` - prints one template in detail
+  (purpose, required/optional fields, example values, safety notes,
+  runnable JSON operations). `--output json` for machine-readable.
+
+Five initial templates:
+
+| Template | Operations |
+|---|---|
+| `append-to-file` | `append` |
+| `safe-rename` | `rename` |
+| `multi-file-replace` | `replace` (x3) |
+| `non-destructive-cleanup` | `create_dir` + `rename` (x2) |
+| `git-safe-review-flow` | `create` + `append` |
+
+**No starter template uses `delete` or `run`.** Tests enforce this:
+starter templates are deliberately non-destructive and command-free.
+Every operation in every template is a member of `ALL_OPERATION_TYPES`
+(`src/input/op-registry.ts`); the registry is the single source of
+truth and tests assert there is no second op list to drift against.
+
+README adds a "First 5 Minutes with UseSteady" section that walks
+the exact happy path: `quickstart` -> `capabilities` -> `templates` ->
+customize -> `batch` run -> approval / stop. No internal-doc
+references required.
+
+Implementation PR: `shortgigs/usesteady-core#304`.
+Implementation modules: `src/shell/cli/quickstart.ts` and
+`src/shell/cli/templates.ts` (pure functions only; no I/O, no
+`process.exit`, no execution).
+
+### Friction -> Fix -> Invariant mapping
+
+The Product Capability Track frictions are internally referenced as
+F-1..F-9 in the design doc. This release closes:
+
+| Friction (track ref) | Coverage | Invariant improved |
+|---|---|---|
+| F-1 Manual batch JSON loading | full | Operators can copy a complete runnable JSON operation set from any template; no hand-crafting from registry summaries. |
+| F-7 Unclear first-run path | full | `usesteady quickstart` is the documented first command. README "First 5 Minutes" walks the full path without internal-doc references. |
+| F-8 Command authoring friction | full | Templates surface required/optional fields, example values, and safety notes for each starter workflow before invocation. |
+| F-2 Workflow scaffolding gap | partial | Five non-destructive templates cover the most common safe starting patterns. Custom workflows still require hand-authoring; that gap is deliberate. |
+| F-5 Approval surprise / opaque flow | partial | Quickstart explains the approval gate, `--yes` semantics, and how to stop safely in plain language; the runtime approval surface itself is unchanged. |
+
+### Authority story
+
+- Deterministic approval model: unchanged.
+- No hidden execution: both new subcommands only print. Quickstart
+  renders static text. Templates renders static catalog data. Neither
+  module imports the planner, the safety gate, the executor, or any
+  approval surface.
+- No autonomous authority expansion: no new authority granted. The
+  set of executable operations did NOT grow. Only inspection
+  surfaces grew.
+- Explain-before-execute: strengthened. Operators now see a
+  pre-formatted, safety-noted recipe before authoring a workflow.
+- Bounded execution semantics: unchanged. Templates are static data;
+  printing a template is not running one.
+- `--yes` semantics: unchanged. `quickstart` and `templates` join
+  `capabilities` in the documented `--yes`-exempt list because they
+  never execute. Every other path still requires `--yes` for
+  `--output json` execution.
+
+### What does NOT change
+
+- No `src/input/` change. No registry change. No IR change.
+- No safety detector, drift detector, sanitizer, or canonicalizer
+  change. PRs #293 / #294 / #297 surfaces are untouched.
+- No execution engine change. Planner, executor, and approval
+  surfaces are byte-identical to alpha.53.
+- No new operation types. Templates compose only operations from the
+  existing `ALL_OPERATION_TYPES`.
+- No new runtime dependencies.
+- No model-insertion path change. No new prompt surfaces. No AI
+  workflow generation. Templates are hand-authored static data.
+- No edits to ShortGigs, YODHA, StructureGuard, or SteadyHealth.
+
+### Tests
+
+73 of 73 tests pass across the three onboarding-adjacent surfaces:
+
+- `tests/shell/capabilities.test.ts` (17, regression)
+- `tests/shell/templates.test.ts` (41 new)
+- `tests/shell/quickstart.test.ts` (15 new)
+
+Key invariants enforced by tests:
+
+- Every operation in every template uses a registered op type.
+- No starter template uses `delete` or `run`.
+- Quickstart text and template output are byte-for-byte deterministic.
+- `--output json` works without `--yes` on all three read-only paths.
+- Unknown template names exit non-zero with a helpful stderr line.
+- Negative-content guarantees on quickstart: no "autonomous", no
+  "ai will fix", no "agent will" language anywhere in the orientation.
+
+### Release engineering
+
+No changes to the release gate. `test:release` retains the `--retry=2`
+flake mitigation from alpha.52. `check-stdin-ownership` runs the same
+git-tracked-only scan.
+
+### Surface-specific monitoring
+
+Stabilization window for the onboarding surface opens with this
+release. Watch for:
+
+- Confusion in the quickstart text (specific lines that mislead a
+  first-time user).
+- Template copy/paste failures (JSON that doesn't parse cleanly
+  when pasted, escape-sequence misreads).
+- Approval-flow surprises after following the quickstart (anything
+  the operator sees at run time that the quickstart did not prepare
+  them for).
+- Trust/perception issues (any place where the operator cannot tell
+  whether something is "just printing" or "about to run").
+
+If real friction surfaces in this window, one bounded follow-up PR
+ships. No multi-candidate expansion.
+
+---
+
+## 0.1.0-alpha.53 - Capability explorer (first Product Capability Track ship)
+
+**Released:** May 2026
+**npm tag:** `alpha` - `npm install -g usesteady@alpha`
+
+First implementation candidate from the **Product Capability Track**
+(`docs/product/useability-and-guided-execution-track.md` section 3.1,
+merged in shortgigs/usesteady-core#299). Bounded scope: one new
+read-only subcommand. Zero authority impact.
+
+### What ships
+
+`usesteady capabilities` - prints a structured catalog of every IR
+operation this build supports. Reads directly from
+`src/input/op-registry.ts` (`ALL_OPERATION_TYPES` +
+`OPERATION_REGISTRY`); no second source of truth.
+
+- Default output: human-readable text.
+- `--output json`: deterministic single-line JSON catalog. Exempt
+  from the global `--output json` + `--yes` rule because the
+  catalog has no execution path; `--yes` is meaningless for it.
+- `--help` on the subcommand: subcommand-specific usage.
+- Listed in `PURE_SUBCOMMANDS` (no stdin sampling).
+- Listed in `HELP_TEXT` for global discoverability.
+
+Implementation PR: `shortgigs/usesteady-core#300`.
+Implementation module: `src/shell/cli/capabilities.ts` (pure
+functions only; no I/O, no `process.exit`, no execution).
+
+### Friction -> Fix -> Invariant mapping
+
+The Product Capability Track frictions are internally referenced
+as F-1..F-9 in the design doc (not public issue numbers, since
+they were proactively identified rather than reported). This
+release closes:
+
+| Friction (track ref) | Coverage | Invariant improved |
+|---|---|---|
+| F-9 Weak discoverability of supported operations | full | Every operation the build supports is enumerable from inside the product itself. No external doc lookup required. |
+| F-1 Manual batch JSON loading | partial | Operators can copy a public-JSON shape from the catalog instead of hand-crafting from source. Curated workflow templates (track section 3.2) remain queued. |
+| F-8 Command authoring friction | partial | Required and optional fields per op surface before invocation. Authoring errors are now visible at catalog read time, not at safety-gate-rejection time. |
+
+### Authority story (preserved verbatim from track section 6)
+
+- Deterministic approval model: unchanged. Catalog never approves.
+- No hidden execution: catalog cannot mutate state. No side effects
+  on import or invocation.
+- No autonomous authority expansion: no new authority granted.
+- Explain-before-execute: unchanged.
+- Replayability: unchanged.
+- Bounded execution semantics: the set of executable operations did
+  NOT grow. Only the surface to **inspect** them grew. This
+  distinction is load-bearing (track section 6.6).
+
+### What does NOT change
+
+- No `src/input/` change. No registry change. No IR change.
+- No safety detector, drift detector, sanitizer, or canonicalizer
+  touch.
+- No approval state machine change.
+- No UCP envelope schema change.
+- No K5 boundary change. No `MODEL_INSERTION_POLICY` touch.
+- No new doctrine, ADR, or governance document.
+- No NL-intake involvement. The catalog is built from the static
+  registry, not from any model.
+
+### Tests
+
+- `tests/shell/capabilities.test.ts` (new): 17 tests covering
+  invariants I1..I7 (catalog coverage of `ALL_OPERATION_TYPES`,
+  deterministic byte-for-byte output, `--yes` not required,
+  `--output json` works without `--yes`, every op has a parseable
+  JSON example, catalog is frozen, registry fields surface
+  verbatim).
+- No existing test modified. Governance test
+  (`tests/governance/input-surface-integrity.test.ts`) and registry
+  test (`tests/input/op-registry.test.ts`) unchanged: 141/141 pass.
+
+Full suite: 4697 passed, 4 skipped (132 files).
+
+### Public demonstration
+
+`README.md` updated with a "Discover what UseSteady can do"
+section under Install, showing the command, its output, and the
+`--output json` variant. The README explicitly notes the catalog
+shares the same registry the executor uses (no doc drift).
+
+### Sequencing posture
+
+- Product Capability Track NOW queue: section 3.1 SHIPPED in this release.
+  Remaining NOW: section 3.2 (curated templates), section 3.6 (execution
+  timeline view), section 3.11 (workflow health diagnostics). Per track
+  section 7, one PR per candidate; the next NOW candidate opens only
+  after this surface stabilizes through one monitoring window.
+- Cluster B (alpha.52) monitoring window: still active through
+  2026-05-18 unless triggers fire. This release does not touch
+  any Cluster B surface; window unaffected.
+- `capabilities` opens its own observation window on landing.
+  Read-only surface; thresholds calibrated narrow:
+  - regression trigger: any deterministic-output drift, any
+    catalog coverage gap (op missing or extra), any exit-code
+    change.
+  - volume trigger: 3+ reports of operator confusion mapped to
+    F-9 / F-1 / F-8 within 14 days indicating the catalog is
+    surfacing the wrong information.
+
+### Release engineering
+
+No changes to `scripts/check-stdin-ownership.mjs` or
+`release:gate`. The alpha.52 release-engineering deltas (scanner
+gitignore-respect; `vitest run --retry=2` in `release:gate`)
+remain in place.
+
+---
+
 ## 0.1.0-alpha.52 - Canonicalization, Workflow Integrity, Process Lifecycle Anchor
 
 **Released:** May 2026

package/README.md

@@ -168,6 +168,107 @@ Requires Node.js 18+. Runs fully local. Optional: set `ANTHROPIC_API_KEY` to ena
 
 ---
 
+## First 5 Minutes with UseSteady
+
+This is the fastest path from a fresh install to a successful, reviewed change.
+
+### 1. Read the orientation
+
+```bash
+npx usesteady quickstart
+```
+
+One screen. What UseSteady is, the steps below, plain-language approval, where workflows execute, how to stop. Read-only - this command does not run anything.
+
+### 2. See what operations exist
+
+```bash
+npx usesteady capabilities
+```
+
+The full catalog of supported operations (`replace`, `append`, `rename`, `create`, etc.), with the exact JSON shape for each. Source of truth - no second list to drift against.
+
+### 3. Pick a starter template
+
+```bash
+npx usesteady templates
+```
+
+Lists five safe, non-destructive starter workflows:
+
+| Template | What it does |
+|---|---|
+| `append-to-file` | Add a block to an existing file (recommended first run). |
+| `safe-rename` | Rename one file with explicit approval. |
+| `multi-file-replace` | Same exact-text replacement across a hand-listed file set. |
+| `non-destructive-cleanup` | Move files into a new directory via rename (no deletions). |
+| `git-safe-review-flow` | Capture review notes in `REVIEW.md` without touching source. |
+
+Print a template in detail:
+
+```bash
+npx usesteady templates append-to-file
+```
+
+You get the purpose, required fields, example values, safety notes, and a runnable JSON operation block.
+
+### 4. Customize and run
+
+Copy the JSON operations from the template into a file (e.g. `ops.json` - as a JSON array), replace the placeholder values with your real values, then:
+
+```bash
+npx usesteady batch ops.json
+```
+
+UseSteady prints **SYSTEM WILL** with the exact operation, waits for your approval, and only runs after you say yes. Every operation. No exceptions.
+
+### 5. If you change your mind
+
+At any approval prompt, choose **Reject** (or press `Ctrl+C`). The current operation is not applied; UseSteady exits. Operations approved earlier in the workflow are filesystem changes you already authorized one at a time; undo them via your version control (`git revert`) or by reversing the operation manually.
+
+### Approval, in one sentence
+
+By default UseSteady stops before every operation. Add `--yes` only when you have already read and reviewed the entire spec (typical in CI).
+
+---
+
+## Discover what UseSteady can do
+
+Print a structured catalog of every operation this build supports - read-only, never executes anything:
+
+```bash
+npx usesteady capabilities
+```
+
+Or machine-readable:
+
+```bash
+npx usesteady capabilities --output json
+```
+
+Sample (truncated):
+
+```
+  UseSteady supported operations:
+
+  replace
+      Replace <from> with <to> in <file> (occurrence: first | all | { index }).
+      Required (IR): file, from, to
+      Optional (IR): occurrence
+      JSON example:  {"type":"replace","file":"src/Button.tsx","from":"old text","to":"new text"}
+
+  rename
+      Rename the file at <from> to <to>.
+      Required (IR): from, to
+      Optional (IR): (none)
+      JSON example:  {"type":"rename","from":"old.ts","to":"new.ts"}
+  ...
+```
+
+The catalog is sourced from the same registry the executor uses. No second source of truth, no documentation drift. Useful for: authoring `--json` and batch payloads, discovering supported operations, scripting validation.
+
+---
+
 ## Core idea
 
 **AI proposes. You approve. Then it runs.**

package/dist/src/shell/cli/capabilities.d.ts

@@ -0,0 +1,76 @@
+/**
+ * usesteady capabilities -- read-only catalog of supported IR operations.
+ *
+ * Pure module. No I/O, no process.exit, no execution. Importing this module
+ * cannot read stdin, write the filesystem, spawn a process, or talk to a
+ * model. It exists to render the operator-facing catalog of operations the
+ * current build supports.
+ *
+ * Source of truth: src/input/op-registry.ts
+ *   - ALL_OPERATION_TYPES (the closed set; coverage is enforced by tests)
+ *   - OPERATION_REGISTRY  (per-op required/optional/summary)
+ *
+ * This module adds presentation metadata only:
+ *   - PUBLIC_JSON_EXAMPLES is the public --json wire shape per op, mirroring
+ *     the HELP_TEXT "JSON op schema" block. The public JSON field names
+ *     diverge from the IR field names for some ops (e.g. `create` uses
+ *     JSON `file` but IR `path`); src/input/json-to-ir.ts owns that
+ *     mapping. The catalog surfaces both views so the operator sees what
+ *     the registry says (IR canonical) and what they actually type (JSON
+ *     public).
+ *
+ * Design: docs/product/useability-and-guided-execution-track.md §3.1.
+ *
+ * Determinism: every exported function is pure and order-stable.
+ *   - operations are returned in ALL_OPERATION_TYPES order;
+ *   - JSON output is single-line with stable key order
+ *     (operations -> [{type, required, optional, summary, jsonExample}]);
+ *   - text output bytes are identical across runs for a given build.
+ *
+ * Authority:
+ *   - This module does not interact with the planner, the safety gate,
+ *     the executor, the model-insertion path, or any approval surface.
+ *   - The output is informational. Nothing in this catalog can be approved
+ *     or executed. To actually run an operation, the operator authors a
+ *     --json or batch payload and goes through the existing approval flow.
+ */
+import { type OperationType } from "../../input/op-registry.js";
+/**
+ * Public catalog entry shape. Stable; this is the JSON output schema.
+ */
+export type CapabilityEntry = {
+    readonly type: OperationType;
+    /** IR canonical field names (from OPERATION_REGISTRY.required). */
+    readonly required: readonly string[];
+    /** IR canonical field names (from OPERATION_REGISTRY.optional). */
+    readonly optional: readonly string[];
+    /** One-line human description (from OPERATION_REGISTRY.summary). */
+    readonly summary: string;
+    /** Public --json / batch wire-shape example. */
+    readonly jsonExample: Readonly<Record<string, unknown>>;
+};
+/**
+ * Top-level catalog shape. Stable; the JSON output is exactly this.
+ */
+export type CapabilitiesCatalog = {
+    readonly operations: readonly CapabilityEntry[];
+};
+/**
+ * Build the catalog. Pure. Deterministic. Operations are in
+ * ALL_OPERATION_TYPES order (which is itself frozen).
+ */
+export declare function buildCapabilitiesCatalog(): CapabilitiesCatalog;
+/**
+ * Render the catalog as a single-line JSON string, terminated by exactly
+ * one newline. Key order is fixed by the CapabilitiesCatalog +
+ * CapabilityEntry shapes above, which are constructed in a fixed order in
+ * buildCapabilitiesCatalog. JSON.stringify preserves insertion order for
+ * string keys per the ECMAScript spec.
+ */
+export declare function renderCapabilitiesJson(): string;
+/**
+ * Render the catalog as a human-readable text block. Bytes are identical
+ * across runs for a given build.
+ */
+export declare function renderCapabilitiesText(): string;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/src/shell/cli/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../../src/shell/cli/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AAuBpC;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAc9D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAoB/C"}

package/dist/src/shell/cli/capabilities.js

@@ -0,0 +1,111 @@
+/**
+ * usesteady capabilities -- read-only catalog of supported IR operations.
+ *
+ * Pure module. No I/O, no process.exit, no execution. Importing this module
+ * cannot read stdin, write the filesystem, spawn a process, or talk to a
+ * model. It exists to render the operator-facing catalog of operations the
+ * current build supports.
+ *
+ * Source of truth: src/input/op-registry.ts
+ *   - ALL_OPERATION_TYPES (the closed set; coverage is enforced by tests)
+ *   - OPERATION_REGISTRY  (per-op required/optional/summary)
+ *
+ * This module adds presentation metadata only:
+ *   - PUBLIC_JSON_EXAMPLES is the public --json wire shape per op, mirroring
+ *     the HELP_TEXT "JSON op schema" block. The public JSON field names
+ *     diverge from the IR field names for some ops (e.g. `create` uses
+ *     JSON `file` but IR `path`); src/input/json-to-ir.ts owns that
+ *     mapping. The catalog surfaces both views so the operator sees what
+ *     the registry says (IR canonical) and what they actually type (JSON
+ *     public).
+ *
+ * Design: docs/product/useability-and-guided-execution-track.md §3.1.
+ *
+ * Determinism: every exported function is pure and order-stable.
+ *   - operations are returned in ALL_OPERATION_TYPES order;
+ *   - JSON output is single-line with stable key order
+ *     (operations -> [{type, required, optional, summary, jsonExample}]);
+ *   - text output bytes are identical across runs for a given build.
+ *
+ * Authority:
+ *   - This module does not interact with the planner, the safety gate,
+ *     the executor, the model-insertion path, or any approval surface.
+ *   - The output is informational. Nothing in this catalog can be approved
+ *     or executed. To actually run an operation, the operator authors a
+ *     --json or batch payload and goes through the existing approval flow.
+ */
+import { ALL_OPERATION_TYPES, OPERATION_REGISTRY, } from "../../input/op-registry.js";
+/**
+ * Public --json / batch wire-shape examples per op. Mirrors the HELP_TEXT
+ * "JSON op schema" block in use-steady.ts. These are the field names the
+ * operator actually types in --json or batch payloads.
+ *
+ * Frozen at module load. Mutation attempts fail loud in strict mode (which
+ * the test runner uses) -- coverage of ALL_OPERATION_TYPES is asserted by
+ * tests in tests/shell/capabilities.test.ts.
+ */
+const PUBLIC_JSON_EXAMPLES = Object.freeze({
+    create: Object.freeze({ type: "create", file: "path/to/file.ts" }),
+    create_dir: Object.freeze({ type: "create_dir", path: "path/to/dir" }),
+    delete: Object.freeze({ type: "delete", file: "path/to/file.ts" }),
+    rename: Object.freeze({ type: "rename", from: "old.ts", to: "new.ts" }),
+    replace: Object.freeze({ type: "replace", file: "src/Button.tsx", from: "old text", to: "new text" }),
+    append: Object.freeze({ type: "append", file: "src/notes.md", to: "text to append" }),
+    prepend: Object.freeze({ type: "prepend", file: "src/notes.md", to: "text to prepend" }),
+    run: Object.freeze({ type: "run", to: "npm test" }),
+});
+/**
+ * Build the catalog. Pure. Deterministic. Operations are in
+ * ALL_OPERATION_TYPES order (which is itself frozen).
+ */
+export function buildCapabilitiesCatalog() {
+    const operations = ALL_OPERATION_TYPES.map((t) => {
+        const schema = OPERATION_REGISTRY[t];
+        const example = PUBLIC_JSON_EXAMPLES[t];
+        const entry = Object.freeze({
+            type: t,
+            required: schema.required,
+            optional: schema.optional,
+            summary: schema.summary,
+            jsonExample: example,
+        });
+        return entry;
+    });
+    return Object.freeze({ operations: Object.freeze(operations) });
+}
+/**
+ * Render the catalog as a single-line JSON string, terminated by exactly
+ * one newline. Key order is fixed by the CapabilitiesCatalog +
+ * CapabilityEntry shapes above, which are constructed in a fixed order in
+ * buildCapabilitiesCatalog. JSON.stringify preserves insertion order for
+ * string keys per the ECMAScript spec.
+ */
+export function renderCapabilitiesJson() {
+    return JSON.stringify(buildCapabilitiesCatalog()) + "\n";
+}
+/**
+ * Render the catalog as a human-readable text block. Bytes are identical
+ * across runs for a given build.
+ */
+export function renderCapabilitiesText() {
+    const catalog = buildCapabilitiesCatalog();
+    const lines = [];
+    lines.push("");
+    lines.push("  UseSteady supported operations:");
+    lines.push("");
+    for (const entry of catalog.operations) {
+        lines.push(`  ${entry.type}`);
+        lines.push(`      ${entry.summary}`);
+        lines.push(`      Required (IR): ${entry.required.length > 0 ? entry.required.join(", ") : "(none)"}`);
+        lines.push(`      Optional (IR): ${entry.optional.length > 0 ? entry.optional.join(", ") : "(none)"}`);
+        lines.push(`      JSON example:  ${JSON.stringify(entry.jsonExample)}`);
+        lines.push("");
+    }
+    lines.push("  This catalog is read-only. It does not execute anything.");
+    lines.push("  IR field names (above) may differ from public JSON field");
+    lines.push("  names in the example -- the example is what you type.");
+    lines.push("  For the full CLI usage, run: usesteady help");
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/src/shell/cli/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../../src/shell/cli/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/src/shell/cli/quickstart.d.ts

@@ -0,0 +1,41 @@
+/**
+ * usesteady quickstart -- guided first-run onboarding text.
+ *
+ * Pure module. No I/O, no process.exit, no execution. Importing this
+ * module cannot read stdin, write the filesystem, spawn a process, or
+ * talk to a model. It exists to render a single-screen orientation that
+ * gets a brand-new user from install to first safe workflow in under five
+ * minutes.
+ *
+ * Determinism: the exported function is pure and returns identical bytes
+ * across runs for a given build. There is no template interpolation, no
+ * environment-dependent text, no clock-based output.
+ *
+ * Authority:
+ *   - This module does not interact with the planner, the safety gate,
+ *     the executor, the model-insertion path, or any approval surface.
+ *   - Quickstart only PRINTS instructions. It never starts a workflow,
+ *     never approves anything, never reads stdin, never writes files.
+ *   - Every command suggested in the text goes through the existing
+ *     CLI dispatcher; nothing new is granted authority by quickstart.
+ *
+ * Source of truth:
+ *   - For the operation catalog, the text directs the user to
+ *     `usesteady capabilities` (src/shell/cli/capabilities.ts).
+ *   - For starter workflows, the text directs the user to
+ *     `usesteady templates` (src/shell/cli/templates.ts).
+ *   - For full CLI usage, the text directs the user to
+ *     `usesteady help`.
+ *   No content is duplicated; quickstart is a curated entry point, not
+ *   a second source of truth.
+ *
+ * Design: docs/product/useability-and-guided-execution-track.md (Product
+ * Capability Track) -- onboarding clarity. Surface added in the first
+ * implementation slice of "first successful workflow in under 5 minutes."
+ */
+/**
+ * Render the quickstart guide as a human-readable text block. Bytes are
+ * identical across runs for a given build. Always succeeds.
+ */
+export declare function renderQuickstartText(): string;
+//# sourceMappingURL=quickstart.d.ts.map

package/dist/src/shell/cli/quickstart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../../../../src/shell/cli/quickstart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAsH7C"}