@north-light/cli 0.0.0 → 0.3.413

package/dist/core/graph/spaces/app.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var s=(t,n)=>g(t,"name",{value:n,configurable:!0});import{covers as u}from"@north-light/identity";import{identityOf as c}from"./index.js";import{objectPlace as $,runPlace as f,runsSeeEachOther as a}from"../../runs/confinement.js";const _={identity:c,sync:"runtime",canRead(t,n,o,e,r){if(n.class==="person"||e.length===0)return!0;if(n.app.rowid===o.rowid)return m(t,n,e);const i=c(t,o).external_id,l=s(d=>n.scopes!==null&&n.scopes.some(w=>u(w,d)),"held");return e[0].type==="node"?l(`crtr:objects:read:${i}`)||r.type==="document"&&r.kind==="report"&&l(`crtr:conversations:read:${i}`):l(y(t,i,"read",e))},canChange(t,n,o,e){if(n.class==="person")return!0;if(n.app.rowid===o.rowid)return e.length===0||m(t,n,e);if(e.length===0||e[0].type==="node")return!1;const r=y(t,c(t,o).external_id,"rw",e);return n.scopes!==null&&n.scopes.some(i=>u(i,r))}},p=new WeakMap;function m(t,n,o){if(n.class!=="node"&&n.class!=="object"||o.length===0||o[0].type!=="node")return!0;let e=p.get(n);if(e===void 0&&(e=n.class==="node"?f(n.node.id,t):$(n.object.rowid,t),p.set(n,e)),e===null)return!0;const r=f(o[0].id,t);return r===null?!e.isolated:a(e,r)}s(m,"runConfined");function y(t,n,o,e){const r=e[0];return r.type!=="profile"?`crtr:memory:${o}:${n}`:`crtr:memory:${o}:${n}:profile:${c(t,r).external_id}`}s(y,"memoryScope");export{_ as appSpace};

package/dist/core/graph/spaces/index.d.ts

@@ -0,0 +1,19 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow, Reader } from '../types.js';
+export interface IdentityRow {
+    object: number;
+    scheme: string;
+    external_id: string;
+}
+export type SpaceType = 'person' | 'app' | 'repo';
+/** The top of an owner chain. Only a space decides access and sync for what it owns.
+ *  `path` is the owner chain below the space, top first, ending at the object
+ *  (e.g. `[node, document]`); it is empty when the object is the space itself. */
+export interface Space {
+    identity(db: DatabaseSync, space: ObjectRow): IdentityRow;
+    sync: 'runtime' | 'repo-ref';
+    canRead(db: DatabaseSync, reader: Reader, space: ObjectRow, path: ObjectRow[], object: ObjectRow): boolean;
+    canChange(db: DatabaseSync, reader: Reader, space: ObjectRow, path: ObjectRow[], object: ObjectRow): boolean;
+}
+export declare const SPACES: Record<SpaceType, Space>;
+export declare function identityOf(db: DatabaseSync, object: ObjectRow): IdentityRow;

package/dist/core/graph/spaces/index.js

@@ -0,0 +1 @@
+var p=Object.defineProperty;var o=(r,e)=>p(r,"name",{value:e,configurable:!0});import{prepared as i}from"../../sqlite-statements.js";import{appSpace as n}from"./app.js";import{personSpace as a}from"./person.js";import{repoSpace as m}from"./repo.js";const E={person:a,app:n,repo:m};function h(r,e){const t=i(r,"SELECT object, scheme, external_id FROM identities WHERE object = ?").get(e.rowid);if(!t)throw new Error(`${e.type} ${e.id} has no identity`);return t}o(h,"identityOf");export{E as SPACES,h as identityOf};

package/dist/core/graph/spaces/person.d.ts

@@ -0,0 +1,5 @@
+import type { Space } from './index.js';
+/** You: your documents, and nodes started with your own authority. Reads and
+ *  changes use the runtime-spaces memory permission strings; a change also
+ *  requires the document's grantee — the app of the node that wrote its first revision. */
+export declare const personSpace: Space;

package/dist/core/graph/spaces/person.js

@@ -0,0 +1,3 @@
+import{prepared as p}from"../../sqlite-statements.js";import{covers as s}from"@north-light/identity";import{identityOf as f}from"./index.js";const d={identity:f,sync:"runtime",canRead(i,r,o,t,u){return r.class==="person"||r.class==="object"&&r.owner.rowid===o.rowid?!0:r.scopes===null?!1:r.app.rowid===o.rowid||t.length===0?!0:t[0].type!=="document"?!1:r.scopes.some(c=>s(c,"crtr:memory:manage:user"))?!0:u.privacy==="public"},canChange(i,r,o,t,u){if(r.class==="person"||r.class==="object"&&r.owner.rowid===o.rowid||r.app.rowid===o.rowid||r.scopes?.some(e=>s(e,"crtr:memory:manage:user")))return!0;if(t.length===0)return r.scopes?.some(e=>s(e,"crtr:memory:rw:user"))??!1;if(t[0].type!=="document")return!1;const c=`crtr:memory:rw:user:${u.name}`;if(r.scopes===null||!r.scopes.some(e=>s(e,c)))return!1;const n=p(i,`SELECT author.type, author.owner AS app FROM revisions r JOIN objects author ON author.rowid = r.author
+      WHERE r.document = ? ORDER BY r.number, r.created_at LIMIT 1`).get(t[0].rowid);return n?n.type==="person"||n.app===r.app.rowid?!0:p(i,`SELECT g.resolved_scopes_json FROM grants g JOIN identities i ON i.external_id = g.grantee
+      WHERE i.object = ? AND i.scheme = 'app'`).all(n.app).some(({resolved_scopes_json:e})=>JSON.parse(e).some(({scope:a,mode:m})=>m==="always"&&s(a,"crtr:memory:manage:user"))):!1}};export{d as personSpace};

package/dist/core/graph/spaces/repo.d.ts

@@ -0,0 +1,13 @@
+import type { Reader } from '../types.js';
+import type { Space } from './index.js';
+/** Whether a node is working in a checkout of `repo` that its file permissions reach:
+ *  read to read the repo's documents, rw to change them. The cwd alone never lets a run
+ *  in, since a node may be started in any directory. A repo-owned custom object is inside
+ *  its own repo. A Mac terminal node reaches every path. */
+export declare function insideRepo(db: Parameters<Space['canRead']>[0], reader: Reader, repo: {
+    rowid: number;
+}, access: 'read' | 'rw'): boolean;
+/** A repo: read and changed by a run working in a checkout of it that its file
+ *  permissions reach (see `insideRepo`). It owns only public documents, so a
+ *  non-public one is never changed. */
+export declare const repoSpace: Space;

package/dist/core/graph/spaces/repo.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var i=(t,o)=>u(t,"name",{value:o,configurable:!0});import{fileRoot as f}from"../../spaces/file-root.js";import{identityOf as c}from"./index.js";function l(t,o,e,n){if(o.class==="object")return o.repos.some(r=>r.rowid===e.rowid);if(o.class!=="node")return!1;const s=o.checkouts.filter(r=>r.repo.rowid===e.rowid);if(s.length===0)return!1;const p={app:c(t,o.app).external_id,resolved:o.scopes??[],launched:null};return s.some(r=>"root"in f(p,r.root,n))}i(l,"insideRepo");const m={identity:c,sync:"repo-ref",canRead(t,o,e,n){return o.class==="person"||n.length===0?!0:l(t,o,e,"read")},canChange(t,o,e,n,s){return s.privacy!=="public"?!1:o.class==="person"?!0:l(t,o,e,"rw")}};export{l as insideRepo,m as repoSpace};

package/dist/core/graph/types.d.ts

@@ -0,0 +1,94 @@
+/** Shared types of the canvas graph: documents, nodes, jobs and their owners as rows of `objects`. */
+export type Privacy = 'public' | 'friends' | 'private';
+export interface ObjectRow {
+    rowid: number;
+    id: string;
+    /** The kind name (`node`, `document`, `job`, an owner kind); the kind registry validates it on create. */
+    type: string;
+    kind: string | null;
+    owner: number | null;
+    privacy: Privacy;
+    name: string;
+    preview: string;
+    created_at: string;
+    deleted_at: string | null;
+}
+export type Level = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+export type ListenDelivery = 'interrupt' | 'steer' | 'after-turn' | 'next-turn';
+/** Stored as `{"10":"interrupt",...}`. */
+export type ListenConfig = Array<{
+    threshold: Level;
+    delivery: ListenDelivery;
+}>;
+export declare const DEFAULT_LISTEN: ListenConfig;
+export type WatchStart = 'spawn' | 'job-start' | 'ask' | 'read' | 'write' | 'act' | 'message' | 'deliver' | 'fork';
+export interface CanvasEvent {
+    /** An event the object's kind declares; `publish` validates it against the registry. */
+    event: string;
+    object: ObjectRow;
+    actor: ObjectRow | null;
+    /** Omitted: the declared level. Supplied: must equal it or be one of the event's declared `levels`. */
+    level?: Level;
+    /** revision, rationale, exit-code, log-path, request id …; never content */
+    attrs: Record<string, string | number | boolean | null>;
+    /** the act's pointer (inbox entry id, report doc id, revision rev_id) */
+    pointer?: string;
+    /** ONLY for report.* and notice.*: the body today's report delivery carries */
+    messageBody?: unknown;
+    /** The message whose handling caused this publish, named by the publisher. Its depth + 1 is this
+     *  event's depth and is bounded by HOP_LIMIT; omitted, the event starts a new chain at depth 0. */
+    cause?: string;
+}
+/** A repo and the directory it is checked out at. */
+export interface Checkout {
+    repo: ObjectRow;
+    root: string;
+}
+/** Who is asking. Mirrors the router's RequestPrincipal; brokers resolve to their node's object. */
+export type Reader = {
+    class: 'person';
+    person: ObjectRow;
+} | {
+    class: 'app';
+    app: ObjectRow;
+    scopes: readonly string[];
+} | {
+    class: 'node';
+    node: ObjectRow;
+    app: ObjectRow;
+    scopes: readonly string[] | null;
+    cwd: string;
+    /** The repos enclosing `cwd`, nearest first; `checkouts` pairs each with its checkout root. */
+    repos: ObjectRow[];
+    checkouts: Checkout[];
+    profile: ObjectRow | null;
+} | {
+    class: 'object';
+    object: ObjectRow; /** Identity alias for shared actor access; never a node principal. */
+    node: ObjectRow;
+    app: ObjectRow;
+    scopes: readonly string[] | null;
+    repos: ObjectRow[];
+    owner: ObjectRow;
+};
+export type RuleOn = 'boot' | 'workspace-open' | 'file-read' | 'document-read' | 'command' | 'pre-command' | 'slash-command';
+export interface RuleSpec {
+    on: RuleOn;
+    match?: string[];
+    matchFrontmatter?: Record<string, unknown>;
+    if?: unknown;
+    deliver: 'name' | 'preview' | 'content';
+}
+export interface Revision {
+    rowid: number;
+    rev_id: string;
+    number: number;
+    body_hash: string;
+    /** the author object's id; null for revisions imported from another runtime */
+    author: string | null;
+    rationale: string | null;
+    verbatim: boolean;
+    created_at: string;
+    /** parent rev_ids */
+    parents: string[];
+}

package/dist/core/graph/types.js

@@ -0,0 +1 @@
+const e=[{threshold:10,delivery:"interrupt"},{threshold:7,delivery:"steer"},{threshold:5,delivery:"after-turn"},{threshold:3,delivery:"next-turn"}];export{e as DEFAULT_LISTEN};

package/dist/core/graph/watches.d.ts

@@ -0,0 +1,62 @@
+/** Watches and their subscriptions, message-subscription ending, tree walks and fork copies.
+ *  `watches.in_tree` is written only here: it is 1 while any subscription of the watch
+ *  started from spawn, job-start or ask. */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ListenConfig, ObjectRow, Reader, WatchStart } from './types.js';
+export interface Subscription {
+    rowid: number;
+    pattern: string;
+    filter: unknown;
+    config: ListenConfig | null;
+    started_by: WatchStart;
+    ends_on: string | null;
+    created_at: string;
+}
+export interface Watch {
+    rowid: number;
+    watcher: ObjectRow;
+    object: ObjectRow;
+    in_tree: boolean;
+    read_heads_key: string | null;
+    created_at: string;
+    subscriptions: Subscription[];
+}
+export interface RecordWatchOpts {
+    patterns?: string[];
+    config?: ListenConfig;
+    filter?: unknown;
+    /** message subscriptions only: 'final' (the default) or 'result:<request message_id>' */
+    endsOn?: string;
+    readHeadsKey?: string;
+}
+export declare function configToJson(config: ListenConfig): string;
+export declare function configFromJson(json: string): ListenConfig;
+/** Record (or extend) watcher's watch on object. Adds only the subscriptions the watch lacks:
+ *  a pattern already held without an end covers any new one, except that a tree start
+ *  still adds its own subscription when only non-tree ones hold the pattern. */
+export declare function recordWatch(db: DatabaseSync, watcher: ObjectRow, object: ObjectRow, start: WatchStart, opts?: RecordWatchOpts): void;
+/** Remove the whole watch, the subscriptions with one pattern, or (tree-only form) the
+ *  subscriptions one start made. A watch left with no subscription is deleted. */
+export declare function unwatch(db: DatabaseSync, watcher: ObjectRow, object: ObjectRow, which?: string | {
+    startedBy: WatchStart;
+}): void;
+/** Change the listening configuration of the watcher's subscriptions with `pattern`; null = the watcher's default. */
+export declare function setSubscriptionConfig(db: DatabaseSync, watcher: ObjectRow, object: ObjectRow, pattern: string, config: ListenConfig | null): void;
+/** End the message subscriptions on `object` (a node): 'final' and 'done' end all of them;
+ *  `{result}` ends those waiting for that request's answer. */
+export declare function endMessageSubscriptions(db: DatabaseSync, object: ObjectRow, cause: 'final' | 'done' | {
+    result: string;
+}): void;
+/** The watches `watcher` holds that the reader may see (both ends readable). */
+export declare function watchesOf(db: DatabaseSync, reader: Reader, watcher: ObjectRow): Watch[];
+/** The watches held on `object` that the reader may see (both ends readable). */
+export declare function watchersOf(db: DatabaseSync, reader: Reader, object: ObjectRow): Watch[];
+/** Every node below `root` in the tree (in-tree watches, watcher → object), each once. */
+export declare function descendants(db: DatabaseSync, root: ObjectRow): ObjectRow[];
+/** Every node above `leaf` in the tree (in-tree watches, object → watcher), each once. */
+export declare function ancestors(db: DatabaseSync, leaf: ObjectRow): ObjectRow[];
+/** The objects whose in-tree watch covers `object` (its spawner, job starter, explicit watchers). */
+export declare function treeWatchersOf(db: DatabaseSync, object: ObjectRow): ObjectRow[];
+/** Give `fork` a copy of every watch `source` holds, with the same subscriptions, configurations
+ *  and read base; each copied subscription records `fork`, so no copy is in the tree. */
+export declare function copyWatchesForFork(db: DatabaseSync, source: ObjectRow, fork: ObjectRow): void;

package/dist/core/graph/watches.js

@@ -0,0 +1,18 @@
+var D=Object.defineProperty;var c=(e,t)=>D(e,"name",{value:t,configurable:!0});import{prepared as i}from"../sqlite-statements.js";import{canRead as S}from"./access.js";import{receiverForObject as j}from"./receivers.js";import{getByRowid as N}from"./objects.js";const R=["spawn","job-start","ask"],y=["report.final","report.result","notice.>"];function p(e){return JSON.stringify(Object.fromEntries(e.map(t=>[String(t.threshold),t.delivery])))}c(p,"configToJson");function I(e){const t=JSON.parse(e);return Object.entries(t).map(([o,r])=>({threshold:Number(o),delivery:r})).sort((o,r)=>r.threshold-o.threshold)}c(I,"configFromJson");function _(e,t,o){return i(e,"SELECT * FROM watches WHERE watcher = ? AND object = ?").get(t.rowid,o.rowid)}c(_,"watchRow");function d(e,t){return i(e,"SELECT * FROM watch_subscriptions WHERE watch = ? ORDER BY rowid").all(t)}c(d,"subsOf");function h(e,t){const o=d(e,t);if(o.length===0){i(e,"DELETE FROM watches WHERE rowid = ?").run(t);return}const r=o.some(n=>R.includes(n.started_by))?1:0;i(e,"UPDATE watches SET in_tree = ? WHERE rowid = ? AND in_tree != ?").run(r,t,r)}c(h,"settle");function g(e,t){return e==="message"?y:t.patterns?.length?t.patterns:[">"]}c(g,"defaultPatterns");function k(e,t,o,r,n={}){if(r==="fork")throw new Error("recordWatch: fork watches are made by copyWatchesForFork");if(t.type.includes(".")&&!j(e,t))throw new Error(`custom object ${t.id} has no receiver`);const a=new Date().toISOString();i(e,`INSERT INTO watches (watcher, object, in_tree, read_heads_key, created_at) VALUES (?, ?, 0, ?, ?)
+    ON CONFLICT (watcher, object) DO UPDATE SET read_heads_key = COALESCE(excluded.read_heads_key, read_heads_key)`).run(t.rowid,o.rowid,n.readHeadsKey??null,a);const s=_(e,t,o),E=r==="message"?n.endsOn??"final":null,f=R.includes(r),w=d(e,s.rowid),u=i(e,`INSERT INTO watch_subscriptions (watch, pattern, filter_json, config_json, started_by, ends_on, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)`);for(const O of g(r,n))w.some(l=>l.pattern===O&&(l.ends_on===null||l.ends_on===E)&&(!f||R.includes(l.started_by)))||u.run(s.rowid,O,n.filter===void 0?null:JSON.stringify(n.filter),n.config?p(n.config):null,r,E,a);h(e,s.rowid)}c(k,"recordWatch");function H(e,t,o,r){const n=_(e,t,o);n&&(r===void 0?i(e,"DELETE FROM watch_subscriptions WHERE watch = ?").run(n.rowid):typeof r=="string"?i(e,"DELETE FROM watch_subscriptions WHERE watch = ? AND pattern = ?").run(n.rowid,r):i(e,"DELETE FROM watch_subscriptions WHERE watch = ? AND started_by = ?").run(n.rowid,r.startedBy),h(e,n.rowid))}c(H,"unwatch");function M(e,t,o,r,n){const a=_(e,t,o),s=a?i(e,"UPDATE watch_subscriptions SET config_json = ? WHERE watch = ? AND pattern = ?").run(n?p(n):null,a.rowid,r).changes:0;if(Number(s)===0)throw new Error(`${t.id} has no subscription ${r} on ${o.id}`)}c(M,"setSubscriptionConfig");function x(e,t,o){const r=typeof o=="string"?i(e,`DELETE FROM watch_subscriptions WHERE started_by = 'message'
+        AND watch IN (SELECT rowid FROM watches WHERE object = ?) RETURNING watch`).all(t.rowid):i(e,`DELETE FROM watch_subscriptions WHERE started_by = 'message' AND ends_on = ?
+        AND watch IN (SELECT rowid FROM watches WHERE object = ?) RETURNING watch`).all(`result:${o.result}`,t.rowid);for(const n of new Set(r.map(a=>a.watch)))h(e,n)}c(x,"endMessageSubscriptions");function C(e,t){const o=N(e,t.watcher),r=N(e,t.object);return!o||!r?null:{rowid:t.rowid,watcher:o,object:r,in_tree:t.in_tree===1,read_heads_key:t.read_heads_key,created_at:t.created_at,subscriptions:d(e,t.rowid).map(n=>({rowid:n.rowid,pattern:n.pattern,started_by:n.started_by,ends_on:n.ends_on,created_at:n.created_at,filter:n.filter_json===null?null:JSON.parse(n.filter_json),config:n.config_json===null?null:I(n.config_json)}))}}c(C,"hydrate");function T(e,t,o){return o.map(r=>C(e,r)).filter(r=>r!==null&&S(e,t,r.watcher)&&S(e,t,r.object))}c(T,"visible");function U(e,t,o){return T(e,t,i(e,"SELECT * FROM watches WHERE watcher = ? ORDER BY rowid").all(o.rowid))}c(U,"watchesOf");function J(e,t,o){return T(e,t,i(e,"SELECT * FROM watches WHERE object = ? ORDER BY rowid").all(o.rowid))}c(J,"watchersOf");function B(e,t){return i(e,`WITH RECURSIVE walk(rowid) AS (
+      SELECT ?
+      UNION
+      SELECT w.object FROM walk CROSS JOIN watches w INDEXED BY watches_tree_down ON w.watcher = walk.rowid AND w.in_tree = 1
+    ) SELECT o.* FROM walk CROSS JOIN objects o ON o.rowid = walk.rowid
+      WHERE o.type = 'node' AND o.rowid != ?`).all(t.rowid,t.rowid)}c(B,"descendants");function v(e,t){return i(e,`WITH RECURSIVE walk(rowid) AS (
+      SELECT ?
+      UNION
+      SELECT w.watcher FROM walk CROSS JOIN watches w INDEXED BY watches_tree_up ON w.object = walk.rowid AND w.in_tree = 1
+    ) SELECT o.* FROM walk CROSS JOIN objects o ON o.rowid = walk.rowid
+      WHERE o.type = 'node' AND o.rowid != ?`).all(t.rowid,t.rowid)}c(v,"ancestors");function Y(e,t){return i(e,`SELECT o.* FROM watches w INDEXED BY watches_tree_up CROSS JOIN objects o ON o.rowid = w.watcher
+    WHERE w.object = ? AND w.in_tree = 1 ORDER BY w.rowid`).all(t.rowid)}c(Y,"treeWatchersOf");function V(e,t,o){const r=new Date().toISOString(),n=i(e,"SELECT * FROM watches WHERE watcher = ?").all(t.rowid),a=i(e,`INSERT INTO watch_subscriptions (watch, pattern, filter_json, config_json, started_by, ends_on, created_at)
+    VALUES (?, ?, ?, ?, 'fork', ?, ?)`);for(const s of n){if(s.object===o.rowid)continue;i(e,`INSERT INTO watches (watcher, object, in_tree, read_heads_key, created_at) VALUES (?, ?, 0, ?, ?)
+      ON CONFLICT (watcher, object) DO NOTHING`).run(o.rowid,s.object,s.read_heads_key,r);const E=_(e,o,{rowid:s.object}),f=d(e,E.rowid);for(const w of d(e,s.rowid))f.some(u=>u.pattern===w.pattern&&u.ends_on===w.ends_on)||a.run(E.rowid,w.pattern,w.filter_json,w.config_json,w.ends_on,r);h(e,E.rowid)}}c(V,"copyWatchesForFork");export{v as ancestors,I as configFromJson,p as configToJson,V as copyWatchesForFork,B as descendants,x as endMessageSubscriptions,k as recordWatch,M as setSubscriptionConfig,Y as treeWatchersOf,H as unwatch,J as watchersOf,U as watchesOf};

package/dist/core/help.d.ts

@@ -0,0 +1,309 @@
+import type { DeclaredOutputField } from '../api/command-manifest/result.js';
+export type Field = DeclaredOutputField;
+/** Positional argument. A repeatable positional consumes every remaining positional token. */
+export interface PositionalParam {
+    kind: 'positional';
+    name: string;
+    /** Display hint only; always parsed as string. `file` names a
+     *  capability-provider file argument, sent locally as the string typed. */
+    type?: 'string' | 'path' | 'file';
+    required: boolean;
+    constraint: string;
+    /** When true, every positional token is collected into an array in argv order. */
+    repeatable?: boolean;
+    /** Local-file materialization contract, valid only on a `path` param. The
+     *  CLI-side value is a path to a local file; the invoker reads that file and
+     *  sends its CONTENT as the mapped value — 'text' as UTF-8, 'base64' as the
+     *  base64 of its raw bytes. The path string itself never crosses the wire. */
+    encoding?: FileEncoding;
+    /** Ambient default: when the caller omits this param and the named client
+     *  environment variable is set and non-empty, that value is used and counts as
+     *  supplied — see FlagParam.defaultFromEnv. */
+    defaultFromEnv?: string;
+}
+/** How a local file named by a `path` param is encoded into the request. */
+export type FileEncoding = 'text' | 'base64';
+/** Additional guidance for an uncommon flag whose safe selection, value
+ *  grammar, dynamic choices, or effects do not fit in its compact leaf-schema
+ *  row. The compact row routes the agent to `crtr <leaf> --<flag> -h`; that
+ *  focused continuation renders only this parameter contract. */
+export interface FocusedFlagHelp {
+    /** Concrete cases that justify overriding the default, plus when to omit. */
+    whenToUse: string;
+    /** Complete accepted-value grammar and default/inheritance behavior. */
+    value: string;
+    /** Flag-specific persistent or lifecycle effects and coupled interactions. */
+    effects?: string[];
+    /** Bounded dynamic choices owned by this flag, rendered only in focused help. */
+    dynamicState?: () => string | null;
+}
+/** Long-form flag (`--name`). */
+export interface FlagParam {
+    kind: 'flag';
+    name: string;
+    /** 'bool' flags take no value — presence = true. 'file' names a
+     *  capability-provider file argument, sent locally as the string typed. */
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file';
+    /** Required only when type is 'enum'. */
+    choices?: string[];
+    required: boolean;
+    /** Compact discovery contract. When focusedHelp is present, state what the
+     *  flag changes and the condition that could justify it; the renderer adds
+     *  the exact focused-help road sign automatically. */
+    constraint: string;
+    /** Opt into focused `--flag -h` guidance. Use only when omission is normal
+     *  and the complete safe contract cannot fit in one compact row. */
+    focusedHelp?: FocusedFlagHelp;
+    default?: string | number | boolean;
+    /** When true, the flag may appear multiple times; values accumulate into an
+     *  array (parseArgv collects them; body-placed REST params ship as a JSON array). */
+    repeatable?: boolean;
+    /** When true, the flag is PARSED normally but never rendered in `-h`. For a
+     *  deliberately-undiscoverable confirmation gate the agent must be TOLD about
+     *  in the command's own output (not by reading the schema), never advertised. */
+    hidden?: boolean;
+    /** The value is a secret. Parse errors for the leaf then withhold every stray
+     *  argv value, since a mistyped invocation is how a secret lands in one. */
+    sensitive?: boolean;
+    /** Local-file materialization contract, valid only on a `path` flag — see
+     *  PositionalParam.encoding. */
+    encoding?: FileEncoding;
+    /** Ambient default sourced from the CALLER's environment: when the param is
+     *  not supplied on the command line and this environment variable is set and
+     *  non-empty, its value fills the param and counts as explicitly supplied (it
+     *  therefore satisfies `required` and ships like a typed value — unlike a
+     *  static `default`, which is a display/parse convenience only). This is how a
+     *  leaf picks up ambient identity a caller should not have to retype, e.g.
+     *  CRTR_NODE_ID, which every broker exports into its node's environment. */
+    defaultFromEnv?: string;
+}
+/** Raw stdin content blob (piped text, not parsed as JSON). */
+export interface StdinParam {
+    kind: 'stdin';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Whether one positional token may supply stdin instead of a pipe. Defaults
+     * to true for existing stdin-body leaves; false requires actual stdin. */
+    allowPositional?: boolean;
+    /** Optional leaf-specific recovery when a positional stdin body collides with
+     * piped stdin. Return undefined to keep the generic collision error. */
+    positionalStdinConflict?: (input: Readonly<Record<string, unknown>>) => {
+        message: string;
+        field?: string;
+        next: string;
+    } | undefined;
+}
+/** --context-file PATH: reads and JSON-parses the file at PATH. */
+export interface ContextFileParam {
+    kind: 'context-file';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Optional description of the expected JSON shape. */
+    shape?: string;
+}
+export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** How prominently a subcommand surfaces in ancestor (parent / root) -h
+ *  listings. Set per child in the parent branch's `help.children`. Default
+ *  'normal'.
+ *   - hidden    — never listed anywhere, not even in this branch's own -h.
+ *                 You must already know it exists to invoke it.
+ *   - normal    — listed in this branch's own -h only (the default).
+ *   - common    — ALSO promoted into the parent's -h, as a bare qualified name.
+ *   - important — ALSO promoted into the parent's -h, name + shortform desc. */
+export type SubTier = 'hidden' | 'normal' | 'common' | 'important';
+/** A child's assembled parent-level listing entry — computed by defineBranch
+ *  from each child def's own self-description (`description`/`whenToUse`/`tier`).
+ *  renderBranch consumes this; it is never authored by hand and there is no
+ *  parent-side copy of a child's description (principle 16: each node owns its
+ *  representation one level up). */
+export interface ListingChild {
+    name: string;
+    /** Plugin that contributed this child to an extensible core branch. */
+    plugin?: string;
+    /** Short description for this child's <subcommand> row. */
+    description: string;
+    /** Selection rubric — plainly states when to reach for this command. Expansive
+     *  with a variety of examples for judgment-heavy commands; concise for
+     *  genuinely single-purpose ones. Rendered verbatim (no prefix). */
+    whenToUse: string;
+    /** Visibility tier in ancestor listings (see SubTier). 'hidden' children are
+     *  dropped from every listing. */
+    tier: SubTier;
+    /** Whether the child is a leaf or a branch. */
+    kind?: 'leaf' | 'branch';
+    /** How many non-hidden subcommands this child itself owns — drives the
+     *  `subcommands="N"` attribute when a branch child is listed without
+     *  expansion. Absent for leaves and childless branches. */
+    subCount?: number;
+}
+/** A subtree's self-description at the parent (root) level. Each subtree owns
+ *  the content that represents it one level up: its vocabulary line, its
+ *  selection rubric, and any bounded block it contributes to the parent's -h.
+ *  defineRoot assembles the root help from these — root never hardcodes a
+ *  subtree's representation. See cli-design "Each node owns its parent-level
+ *  representation". */
+export interface RootEntry {
+    /** One-line vocabulary desc — what this subtree is. Rendered first in the
+     *  subtree's <name> block at root. */
+    concept: string;
+    /** Operations summary (verb list). Carried for completeness; the root block
+     *  leads with concept + rubric, so this is available but not rendered. */
+    desc: string;
+    /** The selection rubric — `use when X` in the subtree's <name> block. */
+    useWhen: string;
+    /** Optional bounded block this subtree contributes to its <name> block at
+     *  root. Returns a complete self-named state element (build it with
+     *  stateBlock), e.g. `<kinds count="7">…</kinds>`. Aggregate, never an
+     *  unbounded enumeration on a cold path. Soft-fails to omission on
+     *  null/throw. */
+    dynamicState?: () => string | null;
+}
+export interface RootHelp {
+    tagline: string;
+    /** One entry per listed subtree. Each renders as its own <name> XML block at
+     *  root, carrying the subtree's concept, selection rubric, and any nested
+     *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
+     *  root hardcodes none of it. */
+    commands: RootCommand[];
+    globals: {
+        name: string;
+        desc: string;
+    }[];
+}
+/** A single command block at root. Most fields come from the subtree's
+ *  RootEntry; `subcommands`/`otherSubcommandCount` are computed by defineRoot
+ *  from the subtree's children tiers. */
+export interface RootCommand {
+    name: string;
+    concept: string;
+    desc: string;
+    useWhen: string;
+    dynamicState?: () => string | null;
+    /** Promoted subcommands surfaced inline under this command at root, in
+     *  declaration order. `desc` is present only for 'important' tier; 'common'
+     *  tier carries the bare qualified path. */
+    subcommands?: {
+        path: string;
+        desc?: string;
+    }[];
+    /** How many of this command's other (non-hidden, not-promoted) direct
+     *  subcommands are not shown. Drives the "[+N (other) subcommands]" line. */
+    otherSubcommandCount?: number;
+}
+export interface BranchHelp {
+    name: string;
+    /** The command's own description — rendered as the `description` attribute of
+     *  its <command> card at its own -h. */
+    summary: string;
+    /** Local model prose orienting the agent to what the subtree contains and how
+     *  the children differ as a group — never a per-child restatement (each
+     *  child's purpose lives in its own listing row). */
+    model?: string;
+    /** Bounded runtime aggregate as a complete self-named state element (build
+     *  it with stateBlock), e.g. `<kinds count="7">…</kinds>`. Renderer
+     *  soft-fails to omission if this returns null or throws. */
+    dynamicState?: () => string | null;
+    /** Parent-level listing assembled by defineBranch from the actual child defs.
+     *  renderBranch reads this; never author it by hand. */
+    listing?: ListingChild[];
+    /** A rejected repository fragment is visible only on its owning extensible branch. */
+    extensionIssue?: {
+        fragment: string;
+        message: string;
+    };
+}
+/** Viewer-only hint about how a leaf's result should preview in the attach
+ *  viewer's chat — never part of `-h` output and never reaches agent-facing
+ *  stdout (see renderLeafArgv / renderResult, neither of which read this
+ *  field). Declared on the leaf that owns the behavior, so the attach viewer
+ *  asks the command tree instead of guessing from rendered text. */
+export interface PreviewMeta {
+    /** When true, the attach viewer collapses this leaf's successful result to
+     *  a one-line status by default (still expandable with Ctrl+O). For a
+     *  command whose result is a machine-readable dump meant for a browser/tool
+     *  rather than a human glance (e.g. a snapshot leaf). Never suppresses a
+     *  failed run — errors always show in full. */
+    suppressOutput?: boolean;
+}
+export interface LeafHelp {
+    name: string;
+    summary: string;
+    /** Optional long-form workflow prose rendered immediately after the summary
+     *  line, before the schema. Carried only by leaves whose correct use needs
+     *  prose beyond the schema (e.g. node new's prompt-writing guidance,
+     *  node yield's pre-yield checklist). */
+    guide?: string;
+    params?: InputParam[];
+    /** Note appended when there is no input (replaces the Input block). */
+    inputNote?: string;
+    output: Field[];
+    outputKind: 'object' | 'jsonl';
+    /** Every persistent change the command makes to the world. For read-only
+     *  leaves use exactly: ["None. Read-only."] */
+    effects: string[];
+    /** Bounded runtime aggregate as a complete self-named state element (build it
+     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
+     *  render time so it reflects the caller's cwd/project scope; appended after
+     *  the schema. Renderer soft-fails to omission if it returns null or throws.
+     *  Mirrors BranchHelp.dynamicState. */
+    dynamicState?: () => string | null;
+    /** Attach-viewer preview hint (see PreviewMeta). Optional; omit for the
+     *  default preview behaviour. */
+    preview?: PreviewMeta;
+}
+/** Invocation-local help view for one hook-eligible core leaf. It shares every
+ *  non-effects field with the frozen core help and owns a separately frozen
+ *  effects list that describes the effective pipeline. */
+export type EffectiveLeafHelp = Readonly<Omit<LeafHelp, 'effects'> & {
+    effects: readonly string[];
+}>;
+/** State elements a leaf reads asynchronously (e.g. from the daemon) when its
+ *  help renders: `leaf` stands in for `dynamicState`, `flags` for a named
+ *  flag's `focusedHelp.dynamicState`. */
+export interface AsyncHelpState {
+    leaf?: () => Promise<string>;
+    flags?: Readonly<Record<string, () => Promise<string>>>;
+}
+/** `help` with the async state the render shows read once: the leaf's for
+ *  ordinary help, only `focusedFlag`'s for focused help. A read that throws
+ *  renders no element, the same soft failure `evalDynamic` gives a sync one. */
+export declare function withAsyncHelpState(help: LeafHelp, state: AsyncHelpState, focusedFlag?: string): Promise<LeafHelp>;
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
+export declare function renderRoot(h: RootHelp): string;
+/** A branch with more visible children than this lists only its promoted
+ *  (`common` / `important`) children in its own -h and counts the rest. A
+ *  plugin that mounts one command per catalog entry (a provider with >1,000
+ *  services) would otherwise print every one on each `-h`. Unlisted children
+ *  still route, and their own `-h` still renders. */
+export declare const WIDE_BRANCH_LISTING_LIMIT = 40;
+/** Split a branch's non-hidden children into the ones its -h lists and the count
+ *  it leaves out. A branch at or under the limit, or one with no promoted child
+ *  to fall back on, lists everything. */
+export declare function collapseWideChildren<T extends {
+    tier?: SubTier;
+}>(visible: readonly T[]): {
+    listed: T[];
+    unlisted: number;
+};
+/** The children of a branch that its parent's (root) -h promotes inline: its
+ *  `common` / `important` ones. On a wide branch only leaves are promoted, so a
+ *  promoted service branch shows in the branch's own -h but does not widen the
+ *  root listing every agent reads. */
+export declare function rootPromotedChildren<T extends {
+    tier?: SubTier;
+    kind?: 'leaf' | 'branch';
+}>(visible: readonly T[]): T[];
+export declare function renderBranch(h: BranchHelp): string;
+/** Render one leaf's ordinary contract, or the focused continuation for one
+ *  uncommon flag selected through `--flag -h`. The caller reaches focused help
+ *  from the ordinary row, so that view contains only leaf identity and the new
+ *  parameter detail instead of repeating information already in context. */
+export declare function renderLeafArgv(h: LeafHelp | EffectiveLeafHelp, focusedFlag?: string): string;

package/dist/core/help.js

@@ -0,0 +1,9 @@
+var w=Object.defineProperty;var r=(e,n)=>w(e,"name",{value:n,configurable:!0});async function O(e,n,t){const s=r(async a=>{try{const i=await a();return()=>i}catch{return()=>null}},"read"),o=t===void 0?void 0:n.flags?.[t],u=new Map(o===void 0?[]:[[t,await s(o)]]);return{...e,...t===void 0&&n.leaf!==void 0?{dynamicState:await s(n.leaf)}:{},params:e.params?.map(a=>{const i=a.kind==="flag"?u.get(a.name):void 0;return a.kind==="flag"&&a.focusedHelp!==void 0&&i!==void 0?{...a,focusedHelp:{...a.focusedHelp,dynamicState:i}}:a})}}r(O,"withAsyncHelpState");function j(e,n,t){const s=Object.entries(n).map(([o,u])=>` ${o}="${u}"`).join("");return`<${e}${s}>
+${t}
+</${e}>`}r(j,"stateBlock");function f(e){if(e===void 0)return null;try{const n=e();return n!==null&&n!==""?n:null}catch{return null}}r(f,"evalDynamic");function l(e){let n=0;for(const t of e)t.length>n&&(n=t.length);return n}r(l,"maxLen");function p(e,n){return e+" ".repeat(Math.max(0,n-e.length))}r(p,"pad");const S=`I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you
+act on directly \u2014 read it as a continuation of your prompt, don't parse it as data.
+Exit 0 on success, non-zero on failure. Schemas appear at leaf -h; a leaf may route an uncommon flag to focused --flag -h guidance.`,I="Before running a crtr command that changes state \u2014 creates, mutates, or deletes anything \u2014 whose exact contract (args, flags, effects) you haven't verified this session, run `-h` on it and read the schema first \u2014 a reliable read beats a guess that wastes a turn or triggers an unintended effect. When a leaf routes a flag to focused help, read that focused help before using the flag; the compact row is discovery, not its invocation contract. Same when the user names a capability you don't fully recognize: `-h` it before acting.";function N(e){const n=e.subcommands??[],t=e.otherSubcommandCount??0;if(n.length===0&&t===0)return[];const s=[];if(n.length>0){const o=l(n.map(u=>u.path));for(const u of n)s.push(u.desc!==void 0&&u.desc!==""?`  ${p(u.path,o)}  ${u.desc}`:`  ${u.path}`)}if(t>0){const o=n.length>0?"other subcommand":"subcommand";s.push(`  [+${t} ${o}${t===1?"":"s"} \u2014 \`crtr ${e.name} -h\`]`)}return s}r(N,"rootSubcommandLines");function E(e){const n=[];n.push(`${e.tagline}`),n.push("");for(const t of e.commands){n.push(`<command name="${t.name}">`),n.push(t.concept),n.push(`use when ${t.useWhen}`);for(const o of N(t))n.push(o);const s=f(t.dynamicState);s!==null&&n.push(s),n.push("</command>"),n.push("")}if(e.globals.length>0){n.push("Globals");const t=l(e.globals.map(s=>s.name));for(const s of e.globals)n.push(`  ${p(s.name,t)}  ${s.desc}`);n.push("")}return n.push(S),n.push(""),n.push(I),n.join(`
+`)}r(E,"renderRoot");function d(e){return e.replace(/"/g,"'")}r(d,"attr");const $=40;function k(e){if(e.length<=$)return{listed:[...e],unlisted:0};const n=e.filter(t=>t.tier==="common"||t.tier==="important");return n.length===0?{listed:[...e],unlisted:0}:{listed:n,unlisted:e.length-n.length}}r(k,"collapseWideChildren");function W(e){const n=e.length>$;return e.filter(t=>(t.tier==="common"||t.tier==="important")&&(!n||t.kind==="leaf"))}r(W,"rootPromotedChildren");function A(e){const n=[];n.push(`<command name="${e.name}" description="${d(e.summary)}">`);const t=f(e.dynamicState);t!==null&&n.push(t),e.model!==void 0&&n.push(e.model);const{listed:s,unlisted:o}=k((e.listing??[]).filter(u=>u.tier!=="hidden"));for(const u of s){const a=u.plugin===void 0?"":` plugin="${d(u.plugin)}"`,i=u.subCount!==void 0&&u.subCount>0?` subcommands="${u.subCount}"`:"";n.length>1&&n.push(""),n.push(`<subcommand name="${u.name}" description="${d(u.description)}" whenToUse="${d(u.whenToUse)}"${a}${i}/>`)}return o>0&&(n.push(""),n.push(`<unlisted-subcommands count="${o}">${o} more subcommands are not listed here. Each one runs by name, and \`crtr ${e.name} <name> -h\` prints its help.</unlisted-subcommands>`)),e.extensionIssue!==void 0&&n.push(`<extension-issue fragment="${d(e.extensionIssue.fragment)}">This repository's contributed commands were rejected: ${e.extensionIssue.message}. Run \`crtr sys doctor\` for the full report.</extension-issue>`),n.push("</command>"),n.join(`
+`)}r(A,"renderBranch");function C(e){if(e.kind==="positional")return`${e.name.toUpperCase()}${e.repeatable===!0?"...":""}`;if(e.kind==="stdin")return"stdin";if(e.kind==="context-file")return"--context-file PATH";const n=e;return n.type==="bool"?`--${n.name}`:`--${n.name} ${n.name.toUpperCase().replace(/-/g,"_")}`}r(C,"paramLabel");function g(e){return e===void 0?"":e==="base64"?" Local file path: the file is read and its raw bytes are base64-encoded into the request; the path itself is never sent.":" Local file path: the file is read as UTF-8 text and its content is sent as the value; the path itself is never sent."}r(g,"fileEncodingNote");function y(e){return e===void 0?"":` Defaults to $${e} when that is set and non-empty in the environment, and counts as supplied.`}r(y,"envDefaultNote");function b(e){return e==="file"?" A file: pass its path.":""}r(b,"fileParamNote");function v(e,n){return e.focusedHelp===void 0?"":` Before using this flag, run \`crtr ${n} --${e.name} -h\` and read its focused guidance.`}r(v,"focusedFlagHelpNote");function T(e,n){const t=e.required?"required":"optional";if(e.kind==="positional"){const c=e.repeatable===!0?" Repeatable \u2014 pass multiple values to accumulate in argv order.":"";return`positional, ${t}.${b(e.type)}${g(e.encoding)}${y(e.defaultFromEnv)} ${e.constraint}${c}`}if(e.kind==="stdin")return`${t}. ${e.constraint}`;if(e.kind==="context-file"){const c=e.shape!==void 0?` Shape: ${e.shape}`:"";return`${t}. Path to a JSON file.${c} ${e.constraint}`.trim()}const s=e,o=v(s,n);if(s.type==="bool")return`${t} boolean. Presence means true. ${s.constraint}${o}`.trim();const u=s.default!==void 0?` Default: ${String(s.default)}.`:"",a=s.type==="enum"&&s.choices!==void 0?` One of: ${s.choices.join(", ")}.`:"",i=s.repeatable===!0?" Repeatable \u2014 pass multiple times to accumulate.":"";return`${s.type}, ${t}.${a}${u}${b(s.type)}${g(s.encoding)}${y(s.defaultFromEnv)} ${s.constraint}${i}${o}`.trim()}r(T,"paramDesc");function m(e){if(e.items===void 0)return e.type;const n=/\|\s*null\s*$/i.test(e.type)?", or null":"";return`array of ${m(e.items)}${n}`}r(m,"outputTypePhrase");function x(e){return e.values!==void 0?` One of: ${e.values.join(", ")}.`:""}r(x,"outputValuesNote");function h(e,n,t){const s=l(e.map(o=>o.name));for(const o of e){const u=o.constraint.length>0?` ${o.constraint}`:"";t.push(`${n}${p(o.name,s)}  ${m(o)}.${x(o)}${u}`),H(o,`${n}  `,t)}}r(h,"renderOutputFields");function H(e,n,t){e.children!==void 0&&e.children.length>0&&h(e.children,n,t);let s=e.items;for(;s!==void 0;){const o=x(s);if((s.constraint.length>0||o.length>0)&&t.push(`${n}each element: ${m(s)}.${o}${s.constraint.length>0?` ${s.constraint}`:""}`),s.children!==void 0&&s.children.length>0){h(s.children,n,t);return}s=s.items}}r(H,"renderOutputShapeBody");function B(e,n){const t=[`${e.name}: ${e.summary}.`],s=(e.params??[]).filter(a=>!(a.kind==="flag"&&a.hidden===!0)),o=n===void 0?void 0:s.find(a=>a.kind==="flag"&&a.name===n&&a.focusedHelp!==void 0);if(o?.focusedHelp!==void 0){const a=o.focusedHelp;if(t.push(""),t.push(`<parameter name="${o.name}">`),t.push("When to use"),t.push(`  ${a.whenToUse}`),t.push(""),t.push("Value"),t.push(`  ${a.value}`),(a.effects??[]).length>0){t.push(""),t.push("Effects");for(const c of a.effects??[])t.push(`  ${c}`)}const i=f(a.dynamicState);return i!==null&&(t.push(""),t.push(i)),t.push("</parameter>"),t.join(`
+`)}if(e.guide!==void 0&&(t.push(""),t.push(e.guide)),t.push(""),s.length>0){t.push("Input");const a=s.map(C),i=l(a);for(let c=0;c<s.length;c++)t.push(`  ${p(a[c],i)}  ${T(s[c],e.name)}`)}else t.push(e.inputNote!==void 0?e.inputNote:"No input parameters.");t.push(""),t.push("Output (fields carried in the rendered result)"),h(e.output,"  ",t),t.push(""),t.push("Effects");for(const a of e.effects)t.push(`  ${a}`);const u=f(e.dynamicState);return u!==null&&(t.push(""),t.push(u)),t.join(`
+`)}r(B,"renderLeafArgv");export{$ as WIDE_BRANCH_LISTING_LIMIT,k as collapseWideChildren,A as renderBranch,B as renderLeafArgv,E as renderRoot,W as rootPromotedChildren,j as stateBlock,O as withAsyncHelpState};

package/dist/core/host-exports/builtins.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Built-in export registry for crtr-generated host artifacts.
+ *
+ * Slash-command templates are one-way exports: code is the single source of
+ * truth, so crtr renders them into host prompt/command dirs with marker-guarded
+ * writes (see export.ts). Legacy generated Agent Skills are listed only as
+ * cleanup targets; crouter's first-class guidance surface is memory docs.
+ */
+import type { RootDef } from '../command.js';
+/** A host runtime crtr exports generated artifacts into. */
+export type Host = 'claude' | 'pi';
+/** One destination for an export artifact. Only targets whose host root exists
+ *  are written — crtr never creates `~/.claude` or `~/.pi` itself (export.ts). */
+export interface HostTarget {
+    host: Host;
+    /** The leaf dir the artifact is written into (never the host root). */
+    dir: () => string;
+    /** `bundle` → `<dir>/<name>/SKILL.md` ; `file` → `<dir>/<name>.md`. */
+    layout: 'bundle' | 'file';
+}
+/** One crtr-generated export artifact and every host it reaches. */
+export interface ExportPair {
+    /** Stable id for logging, e.g. `@cmd/<name>`. */
+    id: string;
+    /** On-disk artifact name (bundle dir name or file stem). */
+    name: string;
+    /** Marker prefix identifying a crtr-owned file (the clobber guard). */
+    markerPrefix: string;
+    /** Full file content incl. frontmatter + version marker. */
+    render: () => string;
+    /** Every host destination. Targets with an absent host root are skipped. */
+    targets: HostTarget[];
+}
+/** A legacy crtr-generated artifact that should be removed if still present. */
+export interface LegacyExportArtifact {
+    /** Stable id for logging/debugging. */
+    id: string;
+    /** On-disk artifact name (bundle dir name or file stem). */
+    name: string;
+    /** Marker prefix identifying a crtr-owned file. Markerless files are user-owned. */
+    markerPrefix: string;
+    /** Every host destination. Targets with an absent host root are skipped. */
+    targets: HostTarget[];
+}
+export declare const SLASH_CMD_MARKER_PREFIX = "<!-- crtr-mode-cmd v";
+/** Legacy crtr-generated exports that should not survive after the memory cutover. */
+export declare function legacyExportArtifacts(): LegacyExportArtifact[];
+/** The crtr-generated export artifacts for this command tree: one pair per
+ *  opted-in slash command (both hosts, file layout). */
+export declare function builtinExportPairs(root: RootDef): ExportPair[];