usesteady 0.1.0-alpha.53 → 0.1.0-alpha.54

package/CHANGELOG.md

@@ -1,5 +1,146 @@
 # 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

package/README.md

@@ -168,6 +168,70 @@ 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:

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"}

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

@@ -0,0 +1,159 @@
+/**
+ * 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 function renderQuickstartText() {
+    const lines = [];
+    lines.push("");
+    lines.push("  UseSteady -- first 5 minutes");
+    lines.push("");
+    lines.push("  What UseSteady is");
+    lines.push("      A command-line tool for governed workflow execution.");
+    lines.push("      You describe a change, review the exact operation, and approve");
+    lines.push("      it before anything runs. No hidden execution, no surprise");
+    lines.push("      actions, nothing happens without your explicit approval.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Step 1. See what UseSteady can do");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("      usesteady capabilities");
+    lines.push("");
+    lines.push("  Prints the full catalog of supported operations. Read-only; this");
+    lines.push("  command never executes anything. Add --output json for a");
+    lines.push("  machine-readable shape.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Step 2. Pick a starter template");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("      usesteady templates");
+    lines.push("");
+    lines.push("  Prints the list of safe starter workflows. Each one is a small,");
+    lines.push("  non-destructive recipe you can copy and customize. To see the");
+    lines.push("  full body of one template:");
+    lines.push("");
+    lines.push("      usesteady templates <name>");
+    lines.push("");
+    lines.push("  Recommended first template: append-to-file");
+    lines.push("");
+    lines.push("      usesteady templates append-to-file");
+    lines.push("");
+    lines.push("  Append is the safest starter: it never overwrites existing");
+    lines.push("  content and is reversible by editing the file back.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Step 3. Customize the template");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("  Copy the JSON operations from the template output into a file");
+    lines.push("  (for example ops.json) and replace the placeholder values with");
+    lines.push("  your real values. The file is a JSON array of operations, e.g.:");
+    lines.push("");
+    lines.push("      [");
+    lines.push("        { \"type\": \"append\", \"file\": \"NOTES.md\", \"to\": \"hello from usesteady\\n\" }");
+    lines.push("      ]");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Step 4. Run the workflow (with approval)");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("      usesteady batch ops.json");
+    lines.push("");
+    lines.push("  UseSteady will:");
+    lines.push("");
+    lines.push("      1. Show you the exact operation (SYSTEM WILL).");
+    lines.push("      2. Wait for your approval before doing anything.");
+    lines.push("      3. Only run after you say yes.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Approval, in plain language");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("  By default, UseSteady stops and asks you before every operation.");
+    lines.push("  You see the exact file, the exact text, the exact change.");
+    lines.push("");
+    lines.push("      - To approve interactively: type the approve key when prompted.");
+    lines.push("      - To skip approval (CI/automation only): add --yes.");
+    lines.push("      - --yes means \"I have already reviewed this spec\".");
+    lines.push("        Do not use --yes for workflows you have not read.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Where do workflows execute?");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("  Operations run locally, in your current working directory, as");
+    lines.push("  your user. UseSteady does not:");
+    lines.push("");
+    lines.push("      - upload your files anywhere;");
+    lines.push("      - run a background daemon;");
+    lines.push("      - spawn workers that outlive the command;");
+    lines.push("      - perform any operation you did not approve.");
+    lines.push("");
+    lines.push("  A CLI invocation ends when it ends. Its authority ends with it.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  How to stop safely");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("  At any approval prompt, choose Reject (or press Ctrl+C). The");
+    lines.push("  current operation is not applied; UseSteady exits. Operations");
+    lines.push("  already approved earlier in the workflow remain applied (they");
+    lines.push("  were filesystem changes you authorized one at a time).");
+    lines.push("");
+    lines.push("  To undo an applied change:");
+    lines.push("");
+    lines.push("      - For tracked files: git checkout / git revert.");
+    lines.push("      - For renames: rename back with the values swapped.");
+    lines.push("      - For appends: edit the file to remove the added block.");
+    lines.push("");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("  Next steps");
+    lines.push("  ---------------------------------------------------------------");
+    lines.push("");
+    lines.push("      usesteady help                Full CLI usage");
+    lines.push("      usesteady capabilities        Catalog of operations");
+    lines.push("      usesteady templates           List of starter workflows");
+    lines.push("      usesteady templates <name>    One template, in detail");
+    lines.push("");
+    lines.push("  Quickstart is read-only. Running this command does not execute");
+    lines.push("  anything; it only prints this guide.");
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=quickstart.js.map

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

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

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

@@ -0,0 +1,142 @@
+/**
+ * usesteady templates -- read-only catalog of safe starter workflows.
+ *
+ * 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 operator-facing example workflows that the
+ * operator can copy, customize, and run through the existing approval flow.
+ *
+ * Source of truth: every operation referenced in every template MUST be a
+ * member of ALL_OPERATION_TYPES (src/input/op-registry.ts). Tests assert
+ * this. There is no second op list to drift against.
+ *
+ * Wire shape: each operation in a template matches the same public JSON
+ * shape exposed by `usesteady capabilities` (src/shell/cli/capabilities.ts
+ * PUBLIC_JSON_EXAMPLES). The operator can take the printed JSON, replace
+ * the placeholder values, and run it through `usesteady --json '...' --yes`
+ * (single op) or via a batch file (`usesteady batch <file> --yes`).
+ *
+ * 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. Printing a template does NOT approve or
+ *     execute anything. To actually run a customized template the operator
+ *     must invoke a separate `usesteady run` / `--json` / `batch` command
+ *     which then goes through the standard approval flow.
+ *   - Templates contain placeholder values only (e.g. "path/to/file.ts").
+ *     No template targets a real file in the operator's workspace.
+ *
+ * Determinism: every exported function is pure and order-stable.
+ *   - templates are returned in TEMPLATE_NAMES order (frozen);
+ *   - JSON output is single-line with stable key order;
+ *   - text output bytes are identical across runs for a given build.
+ *
+ * Design: docs/product/useability-and-guided-execution-track.md section 3.2.
+ */
+import { type OperationType } from "../../input/op-registry.js";
+/**
+ * Stable identifiers for templates. Frozen. Tests assert that every name
+ * here has a matching entry in TEMPLATE_REGISTRY and vice versa.
+ */
+export declare const TEMPLATE_NAMES: readonly ["append-to-file", "safe-rename", "multi-file-replace", "non-destructive-cleanup", "git-safe-review-flow"];
+export type TemplateName = typeof TEMPLATE_NAMES[number];
+/**
+ * Public template entry shape. Stable; this is the JSON output schema for
+ * `usesteady templates <name> --output json`.
+ *
+ *   - `name`            : kebab-case identifier (stable across versions).
+ *   - `purpose`         : one-sentence description of what the template does.
+ *   - `requiredFields`  : placeholder field names the operator MUST replace.
+ *   - `optionalFields`  : placeholder field names the operator MAY replace.
+ *   - `exampleValues`   : ordered (key, description) pairs documenting what
+ *                         realistic values look like for each placeholder.
+ *   - `safetyNotes`     : short bullet list of what to verify before running.
+ *   - `operations`      : array of public-JSON-shape operation objects with
+ *                         placeholder values. Operator copies, customizes,
+ *                         and runs through the standard approval flow.
+ */
+export type TemplateEntry = {
+    readonly name: TemplateName;
+    readonly purpose: string;
+    readonly requiredFields: readonly string[];
+    readonly optionalFields: readonly string[];
+    readonly exampleValues: readonly {
+        readonly field: string;
+        readonly example: string;
+    }[];
+    readonly safetyNotes: readonly string[];
+    readonly operations: readonly Readonly<Record<string, unknown>>[];
+};
+/**
+ * Top-level catalog shape. Stable; the JSON output of
+ * `usesteady templates --output json` is exactly this.
+ */
+export type TemplatesCatalog = {
+    readonly templates: readonly {
+        readonly name: TemplateName;
+        readonly purpose: string;
+    }[];
+};
+/**
+ * Look up a template by name. Pure data accessor. Returns undefined for
+ * unknown names -- callers decide how to surface that (exit code, error
+ * message, etc.).
+ */
+export declare function getTemplate(name: string): TemplateEntry | undefined;
+/**
+ * Type guard for unknown values. Used by the CLI dispatcher to decide
+ * whether `usesteady templates <name>` should print a template or report
+ * an unknown-template error.
+ */
+export declare function isKnownTemplateName(value: unknown): value is TemplateName;
+/**
+ * Build the top-level catalog. Pure. Deterministic. Templates are returned
+ * in TEMPLATE_NAMES order (which is itself frozen).
+ */
+export declare function buildTemplatesCatalog(): TemplatesCatalog;
+/**
+ * Internal helper: assert every operation in every template uses a known
+ * operation type. Exported for the test suite -- the assertion runs at test
+ * time so a future template addition that introduces a typo or an unknown
+ * op type fails CI rather than shipping broken JSON wire shapes.
+ */
+export declare function getAllTemplateOperationTypes(): readonly string[];
+/**
+ * Returns true if every operation in every template uses an operation type
+ * present in ALL_OPERATION_TYPES. Pure. Tests assert this.
+ */
+export declare function allTemplateOperationsUseRegisteredOps(): boolean;
+/**
+ * Render the top-level catalog as a single-line JSON string terminated by
+ * exactly one newline. Determinism: JSON.stringify preserves insertion
+ * order for string keys per the ECMAScript spec.
+ */
+export declare function renderTemplatesListJson(): string;
+/**
+ * Render the top-level catalog as a human-readable text block. Bytes are
+ * identical across runs for a given build.
+ */
+export declare function renderTemplatesListText(): string;
+/**
+ * Render one template as JSON. Returns undefined for unknown names so the
+ * caller can decide the exit-code policy.
+ */
+export declare function renderTemplateDetailJson(name: string): string | undefined;
+/**
+ * Render one template as a human-readable text block. Returns undefined
+ * for unknown names so the caller can decide the exit-code policy.
+ */
+export declare function renderTemplateDetailText(name: string): string | undefined;
+/**
+ * Render an unknown-template error as a text block. Centralized so the CLI
+ * dispatcher and tests see the same wording.
+ */
+export declare function renderUnknownTemplateText(name: string): string;
+/**
+ * Re-export OperationType to keep callers that need to inspect template
+ * operations from having to import op-registry separately. Read-only --
+ * the registry itself is in op-registry.ts and is the single source of
+ * truth.
+ */
+export type { OperationType };
+//# sourceMappingURL=templates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../../src/shell/cli/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,cAAc,qHAMhB,CAAC;AAEZ,MAAM,MAAM,YAAY,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACnE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC1F,CAAC;AAwIF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAGzE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAMxD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,SAAS,MAAM,EAAE,CAShE;AAED;;;GAGG;AACH,wBAAgB,qCAAqC,IAAI,OAAO,CAM/D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAyBhD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIzE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgDzE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO9D;AAED;;;;;GAKG;AACH,YAAY,EAAE,aAAa,EAAE,CAAC"}