@north-light/crouter 0.3.163 → 0.3.165

package/dist/builtin-memory/product.md

@@ -1,80 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When running a product-discovery effort, shaping a product roadmap, or deciding how to stage problem discovery, competitive teardown, and experience definition, this knowledge should be read so the real user need is tested before solution commitment and downstream specification starts from one evidence-grounded direction.
-short-form: Use when running a product-discovery effort or shaping a product roadmap. Covers the three-stage DISCOVER→GROUND→DEFINE methodology, the Mom Test discovery discipline, the four-risks ownership boundary vs the downstream spec, parallel teardown delegation, and what a finished product brief contains.
-system-prompt-visibility: name
-file-read-visibility: none
-gate:
-  kind:
-    imatches: '^product($|/)'
-needs-refinement: true
----
-
-## The Three Stages
-
-A product-discovery effort runs in this order: **DISCOVER** → **GROUND** → **DEFINE**. GROUND and DEFINE interleave (you ground to inform the definition), but you do not commit a product direction in DEFINE until DISCOVER has cleared its gate. Each stage has a gate; you do not commit the next until the current one is met.
-
-### Stage 1 — Discover (problem-space)
-
-Discover is where you find the real need. A client arrives with a solution in their mouth and a problem in their gut; your job is to reach the problem. Treat the request as a hypothesis, not an order — work the **job-to-be-done**: what the user is hiring this product to accomplish (functional, emotional, and social dimensions), for whom, in what triggering moment, and what they do today instead and why it falls short.
-
-Run discovery with `crtr human ask` using the **Mom Test discipline**: ask about real, specific past behavior and concrete pain ("walk me through the last time you hit this"), never pitch your idea, and never ask hypothetical "would you use…" questions — they invite politeness, not truth. Real pain is validated by current workarounds, emotional language, and evidence of prior spend, not hypothetical enthusiasm. Earn every question: answer what you can yourself by tearing down existing products and reading the codebase first; only judgment-bearing, genuinely unresolved questions reach the human.
-
-Write each core need as a **JTBD statement** — `verb + object + context` ("minimize the time to capture a thought on the go") or `When [situation], I want to [motivation], so I can [outcome]` — across all three dimensions (functional, emotional, social); the emotional and social dimensions are the ones teams skip and are exactly what feed the experience work in Define. Structure the discovery output as an **opportunity solution tree** (Torres): one measurable **outcome** at the root, the **opportunities** (unmet needs/pains, sourced from real evidence) beneath it, and candidate **solutions** each tied to a specific opportunity, with the riskiest **assumptions** to test hanging off them. The tree's whole job is to forbid jumping from the outcome straight to a solution and to force more than one branch — it kills the single-track tunnel vision that order-taking produces.
-
-The request and the real job often diverge. When the asked-for feature does not serve the underlying job, say so and steer — building exactly what was asked when it won't meet the need is the central failure this role exists to prevent.
-
-Gate: the client confirms you have the real problem and the users right — restate the job without correction, and the requested feature is either validated as serving it or consciously redirected.
-
-### Stage 2 — Ground (competitive)
-
-Before committing a direction, study how comparable products solve the same job. This is not a feature survey — it is a teardown of the *experience*: interaction patterns, what each product gets right (borrow), where it fails its users (avoid), and where a new product could beat it (differentiate).
-
-Delegate one `product/teardown` child per comparable product and run them in parallel; each studies one product deeply against the job-to-be-done and returns a verdict. Integrate the teardowns yourself into a single **positioning stance** — borrow / avoid / differentiate — never a concatenation and never a copy. Inspiration becomes a defensible direction only when you can say why you are borrowing or rejecting each pattern *for this job*.
-
-Treat competitor patterns as hypotheses, not proven-optimal truth — their design may never have been tested. Do not chase feature parity; it is easily copied and commoditizes you. Instead find the **market orthodoxy** (what every comparable product does the same way), locate the customer-satisfaction gap that orthodoxy leaves open, and pick an opposite dimension that matters to a specific segment. Express the result as a positioning statement: **"Unlike [competitor], [product] provides [durable outcome] because [verifiable reason to believe]."** The reason must rest on something that *compounds* (proprietary data, domain depth, a unique posture), not a UI tweak or a vague "easier to use" claim.
-
-Gate: a positioning stance exists that names what you will borrow, what you will avoid, and how you will differentiate — on a dimension that compounds.
-
-### Stage 3 — Define (experience)
-
-Define commits the opinionated product direction. It produces: the **use cases** the product serves; **3–7 experience principles** (opinionated, prioritized — "instant over configurable", not platitudes); the **emotional target** ("using this should feel like…"); a **user journey** with its moments of truth — where the product must delight and where it must not fail; and a **product vision + North Star** that names the one outcome the product optimizes. Be opinionated: a definition that lists options without a recommendation has not done the consulting.
-
-Gate: the client aligns on the product direction and the experience — the feel, the use cases, and the vision.
-
----
-
-## The Four Risks — What This Role Owns
-
-Every product idea carries four risks (Cagan): **value** (will anyone want it), **usability** (can they use it), **feasibility** (can we build it), **viability** (does it work for the business — brand, legal, economics). This role **owns value, usability, and experience**: discovering them and defining for them is the job. It **flags viability** when it surfaces (a direction that risks the brand, a legal exposure, an economics problem) but does not adjudicate it. It **defers feasibility** entirely to engineering — never let "is this buildable" narrow the product direction during discovery; that is the downstream spec and design work, and pre-empting it trades a clean problem for a brittle answer.
-
-Discovery exists to attack these risks *cheaply and early* — with the assumption inventory and small tests, not engineering cycles. Treat the opening problem statement as a set of unproven hypotheses: categorize the claims (behavioral / emotional / economic), rank them by risk, and surface the riskiest first — the ranked inventory is the explicit baton of what still needs validating.
-
----
-
-## The Boundary With Spec — Where the Baton Passes
-
-This role stops at **the right product to build and how it should feel and look.** It does NOT write acceptance criteria, EARS requirements, user stories, API or data models, or pixel-level UI. Those belong to the downstream `spec` (buildable behavior, interfaces, edge cases) and `design` (architecture, UI structure) kinds.
-
-The baton handed to spec is four things: the **validated problem** (job, users, pain), the **experiential direction** (use cases, experience principles, emotional target, journey), the **competitive grounding** (positioning stance), and the **ranked open assumptions** the spec stage must resolve. A clean baton is a sharp *problem and direction*, not a half-written solution — pre-deciding the spec's job hands it an answer to verify instead of a problem to specify.
-
----
-
-## What a Finished Product Brief Contains
-
-A product brief is lightweight, living, and decision-driving — not a heavy PRD. It is finished when a spec writer could derive what to build from it without re-discovering the user. It contains:
-
-- **Validated problem / opportunity** — the real job-to-be-done (functional, emotional, social), who has it, the pain, and what they do today.
-- **Use cases** — the concrete situations the product serves, in the user's terms.
-- **Experience definition** — 3–7 opinionated experience principles, the emotional target, and a user journey with its moments of truth (delight points and must-not-fail points).
-- **Competitive grounding + positioning** — what comparable products teach, and the borrow / avoid / differentiate stance.
-- **Product vision + North Star** — the one outcome the product optimizes, and the direction it implies.
-- **Ranked open assumptions** — the value/usability/experience bets the brief is making, risk-ranked, for the next stages to resolve.
-
-A brief that types the request back as a plan, lists options without a recommendation, or smuggles in acceptance criteria and UI specs is not finished. Surface unresolved discovery as ranked assumptions, never as silent guesses.
-
----
-
-## Roadmap Shape for a Product Effort
-
-The goal section states the product being discovered and for whom. Scope assumptions record the audience and the job in scope and what is explicitly not. `## Strategy / phases` holds exactly three phases: Discover (gate: client confirms the real problem + users), Ground (gate: positioning stance exists), Define (gate: client aligns on direction + experience). The current phase carries a one-line status; completed phases are deleted, not summarized. Human-confirmed decisions and teardown findings fold into context files (`context/product-brief-*.md`, teardown reports), not the roadmap.

package/dist/clients/attach/render/frozen-history.js

@@ -1,100 +0,0 @@
-// frozen-history.ts — condensed, frozen rendering of a node's OLD cycles.
-//
-// A node that has yielded several times carries every prior cycle in its welcome
-// snapshot (cycleAwareMessages, session-cycles.ts), and the viewer used to build a
-// live component for each message in all of them. Measured across six real
-// sessions (2788 entries, rendered at width 120 with tool output collapsed):
-//
-//     tool calls + results   20448 lines (62.9%)   1376 ms (69%) of build time
-//     user                    6078 lines (18.7%)    431 ms
-//     assistant prose         5960 lines (18.3%)    202 ms
-//
-// So the tool traffic of cycles you are no longer working in dominates both the
-// transcript's line count and the cost of attaching to it. Cycles older than the
-// trailing `live_cycles` (config, default 2) are therefore CONDENSED — reduced to
-// the cycle dividers plus whichever messages `condensed_history` (config, default
-// `none`) admits — and FROZEN: rendered once into a flat `string[]` that is handed
-// back verbatim on every subsequent frame.
-//
-// Freezing means the block never re-wraps. Widening the pane leaves the old lines
-// short (harmless); narrowing CLIPS them at the right edge rather than reflowing,
-// because emitting a line wider than the pane would desync pi-tui's line
-// accounting against the terminal's own wrapping and garble everything below it.
-//
-// The full detail of a condensed cycle is never lost — it is in the node's session
-// file, and `/tree` still navigates the real branches.
-import { sliceByColumn } from '@earendil-works/pi-tui';
-import { CRTR_CYCLE_DIVIDER_CUSTOM_TYPE } from '../../../core/runtime/session-cycles.js';
-/** Roles admitted by each `condensed_history` mode. `toolResult`,
- *  `bashExecution`, and every non-divider `custom` message (crtr output,
- *  injected context blocks) are never kept, nor are the tool-call components an
- *  assistant message would otherwise spawn — only its prose. The cycle dividers
- *  survive every mode, so `none` leaves the seams and nothing else. */
-const ROLES_BY_MODE = {
-    none: new Set(),
-    user: new Set(['user']),
-    agent: new Set(['assistant', 'compactionSummary', 'branchSummary']),
-    both: new Set(['user', 'assistant', 'compactionSummary', 'branchSummary']),
-};
-export function isCycleDivider(message) {
-    return message.role === 'custom' && message.customType === CRTR_CYCLE_DIVIDER_CUSTOM_TYPE;
-}
-/** Does this message survive condensation into the frozen block? */
-export function keepWhenCondensed(message, mode) {
-    if (isCycleDivider(message))
-        return true;
-    return (ROLES_BY_MODE[mode] ?? ROLES_BY_MODE.none).has(message.role ?? '');
-}
-/**
- * Index into `messages` at which the LIVE (fully rendered) region begins.
- *
- * The snapshot is `[cycle 0][divider][cycle 1][divider]…[current cycle]`, so a
- * transcript with D dividers holds D+1 cycles. Keeping the trailing
- * `liveCycles` of them means everything up to and including divider
- * `D - liveCycles` is condensed. Returns 0 — condense nothing — when the node
- * has not yielded often enough to have older cycles, so a fresh or
- * single-yield node renders exactly as it always did.
- */
-export function liveRegionStart(messages, liveCycles) {
-    const keep = Math.max(1, Math.floor(liveCycles));
-    const dividers = [];
-    for (let i = 0; i < messages.length; i++) {
-        if (isCycleDivider(messages[i]))
-            dividers.push(i);
-    }
-    const cycles = dividers.length + 1;
-    if (cycles <= keep)
-        return 0;
-    // The last divider that closes a condensed cycle; the live region opens just
-    // after it (the divider itself stays in the frozen block as the seam).
-    return dividers[cycles - keep - 1] + 1;
-}
-/**
- * A settled block of pre-rendered transcript lines. Renders in O(1) at the width
- * it was frozen at, and clips (never reflows) when the pane is narrower. Ctrl+O /
- * Ctrl+T do not reach it: it holds no components to expand, only text.
- */
-export class FrozenHistoryComponent {
-    lines;
-    frozenWidth;
-    /** Last clip result, so a stable narrow pane clips once rather than per frame. */
-    clipped;
-    constructor(lines, frozenWidth) {
-        this.lines = lines;
-        this.frozenWidth = frozenWidth;
-    }
-    get lineCount() {
-        return this.lines.length;
-    }
-    /** Nothing to recompute — the block is text, already laid out. */
-    invalidate() { }
-    render(width) {
-        if (width >= this.frozenWidth)
-            return this.lines;
-        if (this.clipped?.width === width)
-            return this.clipped.lines;
-        const lines = this.lines.map((line) => sliceByColumn(line, 0, width, true));
-        this.clipped = { width, lines };
-        return lines;
-    }
-}

package/dist/commands/pkg/cli-inspect.d.ts

@@ -1,17 +0,0 @@
-import { type ConfiguredCliRegistration } from '../../core/configured-clis/registration.js';
-import type { CommandRegistrySnapshot } from '../../core/command-manifests/registry.js';
-/** Whether a registration's STORED manifest reads as present. Mirrors the
- *  discovery classifier exactly (§3.3): a missing/metadata-mismatched/unreadable
- *  manifest, or one whose bytes do not parse as JSON, reads as `absent`; a
- *  parseable manifest — even one that later fails §4 validation — is `stored`.
- *  Never fetches. */
-export declare function configuredCliManifestStored(registration: ConfiguredCliRegistration): boolean;
-/** The stored-manifest state string for a registration. */
-export declare function configuredCliManifestState(registration: ConfiguredCliRegistration): 'stored' | 'absent';
-export declare const cliList: import("../../core/command.js").LeafDef;
-/** Build the show/refresh report body for one registration from the unified
- *  snapshot: its stored-manifest state, every command it currently contributes
- *  (each with its full mount path and subtree), and every validation/collision
- *  issue attributed to it. Zero network. */
-export declare function configuredCliReport(registration: ConfiguredCliRegistration, snapshot: CommandRegistrySnapshot): Record<string, unknown>;
-export declare const cliShow: import("../../core/command.js").LeafDef;

package/dist/commands/pkg/cli-inspect.js

@@ -1,190 +0,0 @@
-import { defineLeaf } from '../../core/command.js';
-import { notFound } from '../../core/errors.js';
-import { paginate } from '../../core/pagination.js';
-import { resolveScopeArg } from '../../core/scope.js';
-import { SUBTREE_NAMES } from '../../build-root.js';
-import { listConfiguredCliRegistrations, resolveConfiguredCli, } from '../../core/configured-clis/registration.js';
-import { isCacheMetadataValid, readConfiguredCliCacheManifest } from '../../core/configured-clis/cache.js';
-import { buildExternalCommandSnapshot } from '../../core/configured-clis/discovery.js';
-// ---------------------------------------------------------------------------
-// Shared inspection helpers (zero network — read stored manifest bytes only)
-// ---------------------------------------------------------------------------
-/** Whether a registration's STORED manifest reads as present. Mirrors the
- *  discovery classifier exactly (§3.3): a missing/metadata-mismatched/unreadable
- *  manifest, or one whose bytes do not parse as JSON, reads as `absent`; a
- *  parseable manifest — even one that later fails §4 validation — is `stored`.
- *  Never fetches. */
-export function configuredCliManifestStored(registration) {
-    if (!isCacheMetadataValid(registration))
-        return false;
-    const bytes = readConfiguredCliCacheManifest(registration);
-    if (bytes === null)
-        return false;
-    try {
-        JSON.parse(Buffer.from(bytes).toString('utf8'));
-        return true;
-    }
-    catch {
-        return false; // unparseable → reads as absent
-    }
-}
-/** The stored-manifest state string for a registration. */
-export function configuredCliManifestState(registration) {
-    return configuredCliManifestStored(registration) ? 'stored' : 'absent';
-}
-/** The core top-level subtree names — the closed set a remote may never mount
- *  onto or shadow. Passed to the unified snapshot as `reservedCoreNames`. */
-function reservedCoreNames() {
-    return new Set(SUBTREE_NAMES);
-}
-/** Every full command path (space-joined tokens) in a contributed node's
- *  subtree, starting at the node itself — the top-level mount path plus every
- *  descendant. e.g. `["device", "device reboot", "device status"]`. */
-function enumerateCommandPaths(node, prefix) {
-    const here = [...prefix, node.name];
-    const out = [here.join(' ')];
-    if (node.kind === 'branch') {
-        for (const child of node.children)
-            out.push(...enumerateCommandPaths(child, here));
-    }
-    return out;
-}
-/** The accepted top-level command names a registration currently contributes,
- *  read from THE unified collision-resolved snapshot (a collided command is
- *  dropped and appears only in issues). */
-function contributedTopLevel(snapshot, name) {
-    return snapshot.contributions
-        .filter((c) => c.contributor.kind === 'configured-cli' && c.contributor.name === name)
-        .map((c) => c.node.name)
-        .sort((a, b) => a.localeCompare(b));
-}
-/** Serialize a single configured-CLI issue to the received/expected/next shape. */
-function issueOut(issue) {
-    return {
-        code: issue.code,
-        ...(issue.path !== undefined ? { path: issue.path } : {}),
-        message: issue.message,
-        received: issue.received,
-        expected: issue.expected,
-        next: issue.next,
-    };
-}
-// ---------------------------------------------------------------------------
-// list
-// ---------------------------------------------------------------------------
-export const cliList = defineLeaf({
-    name: 'list',
-    description: 'list registered configured CLIs',
-    whenToUse: 'enumerating configured-CLI registrations across scopes with endpoint, scope, stored-manifest state, and the top-level command(s) each currently contributes',
-    help: {
-        name: 'pkg cli list',
-        summary: 'list registered configured CLIs (zero network)',
-        params: [
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
-            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Default 50, max 200.' },
-            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
-        ],
-        output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, endpoint, scope, manifest_state, top_level_commands}. manifest_state is "stored" or "absent". top_level_commands are the accepted top-level command names from the unified snapshot (empty when absent, invalid, or collided). Sorted by scope (project first) then name ascending.' },
-            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
-            { name: 'total', type: 'integer | null', required: true, constraint: 'Exact count.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only. Reads stored manifests only — never fetches, never revalidates.'],
-    },
-    run: async (input) => {
-        const scopeInput = input['scope'];
-        const limitRaw = input['limit'];
-        const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
-        const cursor = input['cursor'];
-        let scopeFilter;
-        if (scopeInput !== undefined) {
-            const resolved = resolveScopeArg(scopeInput);
-            if (resolved !== 'all')
-                scopeFilter = resolved;
-        }
-        const snapshot = buildExternalCommandSnapshot(reservedCoreNames());
-        const all = listConfiguredCliRegistrations()
-            .filter((r) => scopeFilter === undefined || r.scope === scopeFilter)
-            .sort((a, b) => {
-            if (a.scope === 'project' && b.scope !== 'project')
-                return -1;
-            if (a.scope !== 'project' && b.scope === 'project')
-                return 1;
-            return a.name.localeCompare(b.name);
-        });
-        const result = paginate(all, { limit, cursor: cursor !== undefined ? cursor : undefined }, { defaultLimit: 50, maxLimit: 200, keyOf: (r) => `${r.scope}:${r.name}`, total: 'count' });
-        return {
-            items: result.items.map((r) => ({
-                name: r.name,
-                endpoint: r.endpoint,
-                scope: r.scope,
-                manifest_state: configuredCliManifestState(r),
-                top_level_commands: contributedTopLevel(snapshot, r.name),
-            })),
-            next_cursor: result.next_cursor,
-            total: result.total,
-        };
-    },
-});
-// ---------------------------------------------------------------------------
-// show
-// ---------------------------------------------------------------------------
-/** Build the show/refresh report body for one registration from the unified
- *  snapshot: its stored-manifest state, every command it currently contributes
- *  (each with its full mount path and subtree), and every validation/collision
- *  issue attributed to it. Zero network. */
-export function configuredCliReport(registration, snapshot) {
-    const commands = snapshot.contributions
-        .filter((c) => c.contributor.kind === 'configured-cli' && c.contributor.name === registration.name)
-        .map((c) => ({
-        command: c.node.name,
-        paths: enumerateCommandPaths(c.node, []),
-    }))
-        .sort((a, b) => a.command.localeCompare(b.command));
-    const issues = snapshot.issues
-        .filter((i) => i.contributor.kind === 'configured-cli' && i.contributor.name === registration.name)
-        .map(issueOut);
-    return {
-        name: registration.name,
-        scope: registration.scope,
-        endpoint: registration.endpoint,
-        manifest_state: configuredCliManifestState(registration),
-        commands,
-        issues,
-    };
-}
-export const cliShow = defineLeaf({
-    name: 'show',
-    description: 'inventory one configured CLI',
-    whenToUse: 'reading one configured-CLI registration in detail: resolved endpoint, whether a manifest is stored, every command it currently contributes with full mount path and subtree, and every current validation/collision issue',
-    help: {
-        name: 'pkg cli show',
-        summary: 'inventory one configured CLI from its stored manifest (zero network)',
-        params: [
-            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution. Default: the effective registration (project outranks user).' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration lives in.' },
-            { name: 'endpoint', type: 'string', required: true, constraint: 'Resolved manifest endpoint URL.' },
-            { name: 'manifest_state', type: 'string', required: true, constraint: '"stored" or "absent". Absent is a valid inventory state (register-time fetch failed), not an error.' },
-            { name: 'commands', type: 'object[]', required: true, constraint: 'Every accepted command this CLI contributes. Each: {command (top-level mount name), paths (every full command path in its subtree, space-joined)}. Empty when the manifest is absent, invalid, or collided.' },
-            { name: 'issues', type: 'object[]', required: true, constraint: 'Every current validation/collision issue for this CLI, from the unified snapshot. Each: {code, path?, message, received, expected, next}.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only. Serves the stored manifest — never fetches, never revalidates.'],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const scopeInput = input['scope'];
-        const scope = scopeInput !== undefined ? resolveScopeArg(scopeInput) : undefined;
-        const registration = resolveConfiguredCli(name, scope);
-        if (registration === null) {
-            throw notFound(`configured CLI not found: ${name}`);
-        }
-        const snapshot = buildExternalCommandSnapshot(reservedCoreNames());
-        return configuredCliReport(registration, snapshot);
-    },
-});

package/dist/commands/pkg/cli-manage.d.ts

@@ -1,3 +0,0 @@
-export declare const cliRegister: import("../../core/command.js").LeafDef;
-export declare const cliRemove: import("../../core/command.js").LeafDef;
-export declare const cliRefresh: import("../../core/command.js").LeafDef;

package/dist/commands/pkg/cli-manage.js

@@ -1,206 +0,0 @@
-import { defineLeaf } from '../../core/command.js';
-import { notFound, usage } from '../../core/errors.js';
-import { resolveScopeArg, requireScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.js';
-import { updateConfig, ensureScopeInitialized, readConfig } from '../../core/config.js';
-import { SUBTREE_NAMES } from '../../build-root.js';
-import { resolveConfiguredCli, normalizeEndpoint, validateRegistrationName, validateEndpoint, validateEnvVarName, } from '../../core/configured-clis/registration.js';
-import { removeConfiguredCliCache } from '../../core/configured-clis/cache.js';
-import { registerFetchConfiguredCli, refreshConfiguredCli } from '../../core/configured-clis/fetch.js';
-import { buildExternalCommandSnapshot } from '../../core/configured-clis/discovery.js';
-import { configuredCliManifestState, configuredCliReport } from './cli-inspect.js';
-/** Resolve the target scope for `register`. Spec default is **user** (register
- *  declares a remote surface; it does not install a local artifact). Only
- *  user/project are valid. */
-function resolveRegisterScope(scopeInput) {
-    if (scopeInput === undefined)
-        return 'user';
-    const resolved = resolveScopeArg(scopeInput);
-    if (resolved === 'all' || resolved === 'builtin') {
-        throw usage('scope must be "user" or "project"');
-    }
-    return resolved;
-}
-export const cliRegister = defineLeaf({
-    name: 'register',
-    description: 'register a configured CLI and load its manifest',
-    whenToUse: 'declaring a configured CLI — a remote command surface defined by a manifest endpoint and executed as declarative HTTP. Records {name, endpoint, auth-env} to scope config and fetches-and-stores the manifest. Re-run on every guest boot to reload the manifest: a byte-identical re-register is an idempotent record but still re-fetches. To change an existing endpoint/auth-env, `remove` first.',
-    help: {
-        name: 'pkg cli register',
-        summary: 'register a configured CLI and fetch its manifest',
-        params: [
-            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Registration name (kebab-case, unique among this scope\'s configured-CLI registrations). A local handle — NOT a command name; the top-level command(s) a CLI contributes are named by its manifest mounts.' },
-            { kind: 'flag', name: 'endpoint', type: 'string', required: true, constraint: 'Absolute https:// URL crtr GETs to fetch the manifest (http:// permitted for loopback hosts only — local dev). Its origin is the default REST base for leaf calls. No credentials or fragment.' },
-            { kind: 'flag', name: 'auth-env', type: 'string', required: false, constraint: 'Name of an env var holding a bearer token (e.g. NL_CORE_TOKEN). crtr reads process.env[NAME] at fetch/invocation time and sends Authorization: Bearer. Omit for an unauthenticated endpoint. The credential is never stored.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: user.' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { name: 'endpoint', type: 'string', required: true, constraint: 'Normalized manifest endpoint URL as stored.' },
-            { name: 'auth_env', type: 'string', required: false, constraint: 'Configured auth env var name. Absent when unauthenticated.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration was written to.' },
-            { name: 'manifest_state', type: 'string', required: true, constraint: '"stored" (fetch succeeded, or a prior manifest was preserved) or "absent" (fetch failed and nothing was stored).' },
-            { name: 'unchanged', type: 'boolean', required: false, constraint: 'True when the record already existed identically (idempotent re-register). The manifest was still re-fetched.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes configuredClis.<name> to the scope config.json (atomic, lock-guarded), then performs exactly one authenticated GET of the endpoint and stores the returned bytes as the manifest (replacing any prior one on success).',
-            'A byte-identical re-register (same endpoint + auth-env) skips the config write but still re-fetches and replaces the stored manifest — the guest-boot reload path.',
-            'A fetch failure (network / non-2xx) preserves any prior stored manifest and exits success with a stderr diagnostic suggesting `pkg cli refresh <name>`. A named-but-unset auth env, a differing endpoint/auth-env for an existing name, or an invalid name/endpoint fails before writing or fetching.',
-        ],
-    },
-    run: async (input) => {
-        const name = input['name']?.trim();
-        const endpointRaw = input['endpoint'];
-        const authEnvVar = input['authEnv'];
-        const scopeInput = input['scope'];
-        // ---- Validate inputs (a failure writes nothing and fetches nothing) ----
-        const nameCheck = validateRegistrationName(name);
-        if (!nameCheck.isValid) {
-            throw usage(`invalid --name: ${nameCheck.errors.join('; ')}`);
-        }
-        const endpointCheck = validateEndpoint(endpointRaw);
-        if (!endpointCheck.isValid) {
-            throw usage(`invalid --endpoint: ${endpointCheck.errors.join('; ')}`);
-        }
-        if (authEnvVar !== undefined) {
-            const envCheck = validateEnvVarName(authEnvVar);
-            if (!envCheck.isValid) {
-                throw usage(`invalid --auth-env: ${envCheck.errors.join('; ')}`);
-            }
-        }
-        const endpoint = normalizeEndpoint(endpointRaw);
-        const scope = resolveRegisterScope(scopeInput);
-        if (scope === 'project')
-            ensureProjectScopeRoot();
-        ensureScopeInitialized(scope, requireScopeRoot(scope));
-        // ---- Resolve any existing same-scope registration (idempotent / conflict) ----
-        const existing = readConfig(scope).configuredClis[name];
-        let unchanged = false;
-        if (existing !== undefined) {
-            const sameEndpoint = normalizeEndpoint(existing.endpoint) === endpoint;
-            const sameAuth = (existing.authEnvVar ?? undefined) === (authEnvVar ?? undefined);
-            if (sameEndpoint && sameAuth) {
-                unchanged = true; // idempotent record — still re-fetch below
-            }
-            else {
-                throw usage(`configured CLI "${name}" already registered in ${scope} scope with ` +
-                    `endpoint=${existing.endpoint}` +
-                    `${existing.authEnvVar !== undefined ? ` auth-env=${existing.authEnvVar}` : ' (no auth-env)'}. ` +
-                    `Run \`crtr pkg cli remove ${name} --scope ${scope}\` first to change it.`);
-            }
-        }
-        // ---- Auth-env precondition: a named-but-unset var fails usage before any
-        //      fetch AND before any config write (a usage error mutates nothing). ----
-        if (authEnvVar !== undefined && !process.env[authEnvVar]) {
-            throw usage(`auth env var "${authEnvVar}" is required but not set or empty — export it before registering. ` +
-                `crtr never prompts, mints, or refreshes a token.`);
-        }
-        // ---- Record the registration (skip the write when byte-identical) ----
-        if (!unchanged) {
-            updateConfig(scope, (cfg) => {
-                cfg.configuredClis[name] = {
-                    endpoint,
-                    ...(authEnvVar !== undefined ? { authEnvVar } : {}),
-                };
-            });
-        }
-        const registration = resolveConfiguredCli(name, scope);
-        // ---- One authenticated fetch-and-store (register always fetches) ----
-        const result = await registerFetchConfiguredCli(registration);
-        if (result.status !== 200) {
-            if (result.status === 'auth_env_missing') {
-                // Precondition re-check above should have caught this; fail loud.
-                throw usage(result.message);
-            }
-            // Network / non-2xx: registration stands, prior manifest preserved,
-            // exit success with a one-line stderr diagnostic + refresh remedy.
-            process.stderr.write(`crtr: configured CLI "${registration.name}": ${result.message}\n`);
-            process.stderr.write(`next: run \`crtr pkg cli refresh ${registration.name}\` once the endpoint is reachable\n`);
-        }
-        return {
-            name: registration.name,
-            endpoint: registration.endpoint,
-            ...(registration.authEnvVar !== undefined ? { auth_env: registration.authEnvVar } : {}),
-            scope: registration.scope,
-            manifest_state: configuredCliManifestState(registration),
-            ...(unchanged ? { unchanged: true } : {}),
-        };
-    },
-});
-export const cliRemove = defineLeaf({
-    name: 'remove',
-    description: 'remove a configured CLI registration and its stored manifest',
-    whenToUse: 'deregistering a configured CLI: deletes its config entry and its stored manifest directory. Takes effect on the next invocation with no restart',
-    help: {
-        name: 'pkg cli remove',
-        summary: 'remove a configured CLI registration and its stored manifest',
-        params: [
-            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Registration name to remove.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution. Default: the effective registration (project outranks user).' },
-        ],
-        output: [
-            { name: 'removed', type: 'boolean', required: true, constraint: 'Always true (a miss throws not_found).' },
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name removed.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration was removed from.' },
-        ],
-        outputKind: 'object',
-        effects: ['Deletes configuredClis.<name> from the scope config.json, then removes <scopeRoot>/configured-clis/<name>/. Config is authoritative — removed first.'],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const scopeInput = input['scope'];
-        const scope = scopeInput !== undefined ? resolveScopeArg(scopeInput) : undefined;
-        const registration = resolveConfiguredCli(name, scope);
-        if (registration === null) {
-            throw notFound(`configured CLI not found: ${name}`);
-        }
-        // Config is authoritative: delete the entry first so a crash between steps
-        // can only leave an inert orphan store, never an active registration that
-        // reported removed.
-        updateConfig(registration.scope, (cfg) => {
-            delete cfg.configuredClis[name];
-        });
-        removeConfiguredCliCache(registration);
-        return { removed: true, name: registration.name, scope: registration.scope };
-    },
-});
-export const cliRefresh = defineLeaf({
-    name: 'refresh',
-    description: 'refetch and replace a configured CLI manifest',
-    whenToUse: 'pulling a backend manifest change into an already-stored CLI: unconditionally refetches and replaces the stored manifest, then reports the accepted command surface and issues. The only way to update a stored manifest short of a re-register',
-    help: {
-        name: 'pkg cli refresh',
-        summary: 'refetch and replace a configured CLI manifest, report the surface',
-        params: [
-            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Registration name to refresh.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution. Default: the effective registration (project outranks user).' },
-        ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Registration name.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the registration lives in.' },
-            { name: 'endpoint', type: 'string', required: true, constraint: 'Resolved manifest endpoint URL.' },
-            { name: 'manifest_state', type: 'string', required: true, constraint: '"stored" after a successful refresh.' },
-            { name: 'commands', type: 'object[]', required: true, constraint: 'Every accepted command after the refresh. Each: {command, paths}. Empty when the new manifest is invalid or collided.' },
-            { name: 'issues', type: 'object[]', required: true, constraint: 'Every current validation/collision issue. Each: {code, path?, message, received, expected, next}.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Performs one unconditional authenticated GET of the endpoint and replaces the stored manifest with the returned bytes on success.',
-            'On failure (network / non-2xx / named-but-unset auth env) it fails loud and KEEPS the previously stored manifest — the command still composes from it.',
-        ],
-    },
-    run: async (input) => {
-        const name = input['name'];
-        const scopeInput = input['scope'];
-        const scope = scopeInput !== undefined ? resolveScopeArg(scopeInput) : undefined;
-        const registration = resolveConfiguredCli(name, scope);
-        if (registration === null) {
-            throw notFound(`configured CLI not found: ${name}`);
-        }
-        // Unconditional fetch-and-replace. Throws on failure (auth→usage,
-        // unreachable→network, protocol→general), preserving the old manifest.
-        await refreshConfiguredCli(registration);
-        const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES));
-        return configuredCliReport(registration, snapshot);
-    },
-});

package/dist/commands/pkg/cli.d.ts

@@ -1 +0,0 @@
-export declare const cliBranch: import("../../core/command.js").BranchDef;

package/dist/commands/pkg/cli.js

@@ -1,14 +0,0 @@
-import { defineBranch } from '../../core/command.js';
-import { cliRegister, cliRemove, cliRefresh } from './cli-manage.js';
-import { cliList, cliShow } from './cli-inspect.js';
-export const cliBranch = defineBranch({
-    name: 'cli',
-    description: 'register and manage configured CLIs',
-    whenToUse: 'working with configured CLIs: a command surface whose tree is defined by a remote manifest and executed as declarative HTTP (definition + HTTP, never remote code). Register one against a manifest endpoint, remove, list, show, or refresh it. Use `pkg plugin` for local plugins that ship an executable, and `pkg market` for marketplace sources.',
-    help: {
-        name: 'pkg cli',
-        summary: 'configured-CLI lifecycle and inspection',
-        model: 'A configured CLI is the CLI analogue of an MCP client: crtr fetches a manifest (an extension of the command-plugin schema) from a remote endpoint, stores it locally, renders native -h help from it, and runs each leaf as a declarative REST call. No remote code — the trust surface is definition + HTTP. Registration records {name, endpoint, auth-env NAME} in scope config and stores the fetched manifest; the credential itself is never stored. The stored manifest is authoritative with zero freshness checks — it reloads only on a re-register or an explicit refresh.',
-    },
-    children: [cliRegister, cliRemove, cliList, cliShow, cliRefresh],
-});