@north-light/crouter 0.3.219 → 0.3.221

package/dist/api/client.d.ts

@@ -12,6 +12,7 @@ import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js
 import type { DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.js';
 import type { MemoryDocRefDTO } from './dto/memory.js';
+import type { ChatInventoryDTO } from './dto/chat-inventory.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
 import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanCancelRequest, HumanCancelResultDTO, HumanResolveRequest, HumanResolveResultDTO } from './dto/human.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
@@ -151,6 +152,11 @@ export declare class CrtrClient {
     /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
      *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
     getSession(id: string): Promise<NodeSessionDTO>;
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id: string): Promise<ChatInventoryDTO>;
     getArtifacts(id: string, q?: ArtifactsQuery): Promise<ArtifactListDTO>;
     getContext(id: string): Promise<ContextListDTO>;
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
@@ -160,6 +166,9 @@ export declare class CrtrClient {
      *  node would read — the node's own precedence chain, not this process's.
      *  Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
     ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
     listProfiles(): Promise<ProfileDTO[]>;
     getProfile(name: string): Promise<ProfileDTO>;

package/dist/api/client.js

@@ -267,6 +267,13 @@ export class CrtrClient {
     getSession(id) {
         return this.request('GET', routes.nodeSession(this.nodePath(id)));
     }
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id) {
+        return this.request('GET', routes.nodeChatInventory(this.nodePath(id)));
+    }
     getArtifacts(id, q) {
         return this.request('GET', withQuery(routes.nodeArtifacts(this.nodePath(id)), q));
     }
@@ -287,6 +294,9 @@ export class CrtrClient {
         return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
     }
     // ---- Profiles ----------------------------------------------------------
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
     ensureProfile(name, req) {
         return this.request('PUT', routes.profile(name), req ?? {});
     }

package/dist/api/dto/chat-inventory.d.ts

@@ -0,0 +1,43 @@
+/** One command a chat surface may advertise. Builtin and non-opted-in rows are
+ *  dropped before this DTO exists, so `source` never carries `'builtin'`. */
+export interface ChatInventoryCommandDTO {
+    /** No leading slash, exactly as the engine dispatches it. */
+    name: string;
+    description: string;
+    source: 'command' | 'template';
+    /** Argument shape to display beside the name, when the command supplies one. */
+    argument_hint?: string;
+    /** Deterministic expansion metadata for a memory-slash command — the same
+     *  material the terminal preview uses, so a chat preview cannot drift from
+     *  what submission sends. */
+    expansion?: {
+        kind: 'memory-slash';
+        commandName: string;
+        body: string;
+    };
+    /** Raw prompt-template content (frontmatter stripped), for `source: 'template'`. */
+    template?: string;
+}
+/** One resolvable inline memory reference. Metadata only — never the document
+ *  body or its source path. `shortForm` stays camelCase to mirror the broker's
+ *  own `RefMeta`, which is where these rows come from. */
+export interface ChatInventoryMemoryRefDTO {
+    /** Canonical `/`-joined name, e.g. `taste/writing`. */
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+}
+/** `GET /v1/nodes/{id}/chat-inventory` result.
+ *
+ *  `broker_live` reports whether the node's engine was reachable at all. There
+ *  is no per-part error flag: a part that failed and a part that is genuinely
+ *  empty both arrive as an empty array, and a client's behavior is identical
+ *  for both. A dormant node answers 200 with `broker_live: false` — this read
+ *  never revives an engine. */
+export interface ChatInventoryDTO {
+    node_id: string;
+    broker_live: boolean;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}

package/dist/api/dto/chat-inventory.js

@@ -0,0 +1,11 @@
+// Chat-inventory DTO. Backs `GET /v1/nodes/{id}/chat-inventory` — the one read
+// a non-terminal chat surface makes to learn what the node's live engine will
+// accept: the slash commands that can complete their outcome from a chat
+// conversation, and the memory documents an inline `/name` token resolves to.
+//
+// Eligibility is decided in crouter and disclosed here. A client never filters
+// by name, infers capability, or invents a row: what is absent from these
+// arrays is not offered.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/api/dto/profiles.d.ts

@@ -1,8 +1,22 @@
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export declare const PROFILE_PROJECT_MEMORY_VALUES: readonly ["none", "name", "preview", "content"];
+/** How much of a project's memory stores the profile relationship lets an
+ *  automatic delivery disclose. */
+export type ProfileProjectMemory = (typeof PROFILE_PROJECT_MEMORY_VALUES)[number];
+/** One project directory in a profile's purview. */
+export interface ProfileProject {
+    /** Absolute, real-path-resolved directory. */
+    path: string;
+    /** Maximum rung automatic boot and workspace-open delivery may reach from
+     *  this project's memory stores, regardless of the node's working directory.
+     *  An authored lower rung stays lower; targeted reads are never capped. */
+    memory: ProfileProjectMemory;
+}
 /** `PUT /v1/profiles/{name}` body — idempotent ensure. Every field applies
  *  only at create; an existing same-named profile is returned untouched. */
 export interface EnsureProfileRequest {
-    /** Absolute project directories in the profile's purview. */
-    projects?: string[];
+    /** Project directories in the profile's purview, each with its memory cap. */
+    projects?: ProfileProject[];
     /** Persona kind for node creates under the profile that omit kind. */
     default_kind?: string;
     /** Profile facts (identity, role); each entry reaches every broker
@@ -37,9 +51,9 @@ export interface ProfileDTO {
     /** Stable profile-directory id (`<slug>-<id>`). */
     id: string;
     name: string;
-    projects: string[];
-    /** Where nodes under this profile run — one of `projects` (the first unless
-     *  re-pointed), or null when the profile owns none. */
+    projects: ProfileProject[];
+    /** Where nodes under this profile run — one of `projects[].path` (the first
+     *  unless re-pointed), or null when the profile owns none. */
     home: string | null;
     /** ISO timestamp when the profile was paused, or null while active. */
     paused_at: string | null;

package/dist/api/dto/profiles.js

@@ -1,3 +1,4 @@
 // Profile DTOs (spec §6.6). Profile deletion crosses profile, canvas, cron,
 // inbox, and review state, so every consumer routes it through crtrd.
-export {};
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export const PROFILE_PROJECT_MEMORY_VALUES = ['none', 'name', 'preview', 'content'];

package/dist/api/index.d.ts

@@ -27,3 +27,4 @@ export * from './dto/memory.js';
 export * from './dto/inbox.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';

package/dist/api/index.js

@@ -28,3 +28,4 @@ export * from './dto/memory.js';
 export * from './dto/inbox.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';

package/dist/api/routes.d.ts

@@ -11,6 +11,7 @@ export declare const routes: {
     readonly nodeSnapshot: (id: string) => string;
     readonly nodeSubject: (id: string) => string;
     readonly nodeSession: (id: string) => string;
+    readonly nodeChatInventory: (id: string) => string;
     readonly nodeTranscript: (id: string) => string;
     readonly nodeContext: (id: string) => string;
     readonly nodeArtifacts: (id: string) => string;

package/dist/api/routes.js

@@ -27,6 +27,7 @@ export const routes = {
     nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
     nodeSubject: (id) => `${V}/nodes/${id}/subject`,
     nodeSession: (id) => `${V}/nodes/${id}/session`,
+    nodeChatInventory: (id) => `${V}/nodes/${id}/chat-inventory`,
     nodeTranscript: (id) => `${V}/nodes/${id}/transcript`,
     nodeContext: (id) => `${V}/nodes/${id}/context`,
     nodeArtifacts: (id) => `${V}/nodes/${id}/artifacts`,

package/dist/build-root.d.ts

@@ -1,13 +1,9 @@
 import type { RootDef } from './core/command.js';
+import { type CoreHookCatalog } from './core/command-hooks/catalog.js';
 /** Every shipped subtree name. Cheap (no module loading) — the front-door
  *  recursion guard and the dispatcher's first-token routing need only names. */
 export declare const SUBTREE_NAMES: readonly string[];
-/** Every core command path, space-joined ("cron", "cron add", …) — the set
- *  plugin `helpAddenda` keys are validated against at the strict gates
- *  (install, bundle parse, doctor/inspect reports). Loads every core subtree,
- *  so call it only from those gates, never on a dispatch path. Passthrough
- *  branches are excluded: crtr never renders their help, so an addendum
- *  targeting one could never appear. */
+export declare function coreHookCatalog(): Promise<CoreHookCatalog>;
 export declare function coreCommandPaths(): Promise<ReadonlySet<string>>;
 /** Build a root that contains only the subtree `first` dispatches into.
  *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,

package/dist/build-root.js

@@ -1,4 +1,7 @@
 import { defineRoot } from './core/command.js';
+import { createCoreHookCatalog } from './core/command-hooks/catalog.js';
+import { composeCoreHooks } from './core/command-hooks/compose.js';
+import { mark } from './core/timing.js';
 const TAGLINE = 'crtr: agentic runtime.';
 /** Flags handled before dispatch, so they belong to no leaf schema and are
  *  stated once at root (help.ts renders them as the Globals footer). */
@@ -43,8 +46,51 @@ export const SUBTREE_NAMES = Object.freeze(Object.keys(SUBTREE_LOADERS));
  *  so call it only from those gates, never on a dispatch path. Passthrough
  *  branches are excluded: crtr never renders their help, so an addendum
  *  targeting one could never appear. */
+/** Every core subtree, built once per process. The hook catalog and the full
+ *  root both need the complete set; a recognized core first token still loads
+ *  only its own subtree until something actually demands the whole tree. */
+let coreSubtrees;
+function loadCoreSubtrees() {
+    coreSubtrees ??= Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    return coreSubtrees;
+}
+/** Complete static catalog of hook-eligible core leaves. Lifecycle and recovery
+ *  inspection share the same memoized subtree load as root composition. */
+let hookCatalog;
+export function coreHookCatalog() {
+    mark('cli.hooks.catalog');
+    hookCatalog ??= loadCoreSubtrees().then(createCoreHookCatalog);
+    return hookCatalog;
+}
+/** A loader for the effective hook registry, compiled over the COMPLETE core
+ *  catalog so a hook targeting any other subtree is never mistaken for a stale
+ *  target. Loading is lazy — only eligible leaf help or dispatch reaches it,
+ *  and static help discovery never runs a plugin executable. The memoization
+ *  is per composed root, never process-global: discovery reads
+ *  stored plugin bytes and the caller's scope stack, so a plugin install,
+ *  update, or disable (and a cwd change in a long-lived host) must govern the
+ *  next root instead of being pinned by the first one. */
+function hookRegistryLoader() {
+    let registry;
+    return () => {
+        // Dynamic import keeps hook discovery (manifest/artifact validation, plugin
+        // resolution) off the module graph of an invocation that neither renders
+        // eligible leaf help nor dispatches one, matching this file's lazy rationale.
+        registry ??= (async () => {
+            const { compileHookRegistry, effectiveHookPlugins } = await import('./core/command-hooks/discovery.js');
+            const plugins = effectiveHookPlugins();
+            mark('cli.hooks.effective_plugins', { count: plugins.length });
+            if (plugins.length === 0) {
+                mark('cli.hooks.empty_registry');
+                return compileHookRegistry(createCoreHookCatalog([]), []);
+            }
+            return compileHookRegistry(await coreHookCatalog(), plugins);
+        })();
+        return registry;
+    };
+}
 export async function coreCommandPaths() {
-    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    const core = await loadCoreSubtrees();
     const paths = new Set();
     const visit = (node, prefix) => {
         if (node.kind === 'branch' && node.passthrough !== undefined)
@@ -67,7 +113,7 @@ export async function coreCommandPaths() {
 export async function resolveRoot(first) {
     const loader = first !== undefined ? SUBTREE_LOADERS[first] : undefined;
     if (loader !== undefined) {
-        return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [await loader()] });
+        return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: composeCoreHooks([await loader()], hookRegistryLoader()) });
     }
     return buildRoot();
 }
@@ -88,7 +134,7 @@ export async function resolveRoot(first) {
  *  HTTP-transport plugin manifest replacement takes effect on the next invocation
  *  automatically. Composition performs no network I/O. */
 export async function buildRoot() {
-    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    const core = await loadCoreSubtrees();
     // Dynamic import keeps external command discovery/compose (plugin +
     // HTTP-transport plugin, and their resolver/manifest/HTTP deps) OFF the hot leaf
     // path's module graph — they load only here, on the fallthrough, matching
@@ -102,5 +148,6 @@ export async function buildRoot() {
     // sys doctor). Reads only stored manifests — zero network.
     const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES));
     const external = composeExternalSubtrees(snapshot);
-    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [...core, ...external] });
+    // Only core leaves are hookable, so external contributions compose unwrapped.
+    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [...composeCoreHooks(core, hookRegistryLoader()), ...external] });
 }

package/dist/builtin-memory/internal/agent-shaping.md

@@ -63,6 +63,8 @@ Every kind has both a `base` and an `orchestrator` persona; mode picks which one
 
 A profile is a stable **agent identity**: a fixed id, a display name, its own memory store, and a **purview** of project directories it resolves memory and config from. Select it at spawn with `crtr node new --profile <id-or-name>`; omit and a child inherits the caller's profile. Pin a directory's default profile with `crtr profile default` so the startup chooser stops asking. Manage the identity and purview with `crtr profile new/show/project/rename/delete` (see `crtr profile -h`).
 
+Each project in the purview carries its own `memory` value, capping how much of that project's stores reach a node's automatic boot and workspace-open context from any directory that node works in. Give `content` to the repos whose front doors the profile's nodes should operate inside, `preview` or `name` to a project the profile must know exists but rarely enters, and `none` to purview held for config, plugins, and deliberate reads alone. It is a delivery dial, not an access one: `crtr memory read` and file- and command-routed docs still see those stores whole.
+
 Reach for a **new** profile when a distinct body of work has its own set of directories and its own conventions worth a dedicated store — not for every repo. The **profile memory scope** is exactly where cross-repo conventions and your stance toward that body of work belong (see the memory tiers below); a profile spanning several related dirs lets one doc reach every node working anywhere in that bundle.
 
 ## Memory tiers — where a doc lives decides who sees it
@@ -71,6 +73,6 @@ A memory doc's **scope** is a reach dial: the wider the scope, the more agents p
 
 - **node** (`nodes/<id>/context/memory/`) — only *this* running node sees it; rides its boot context and dies with the node. Scratch memory for one goal's cross-refresh state.
 - **profile** (the profile's own store) — every node running under that profile, across all the dirs in its purview. Cross-repo conventions and the user's stance toward that bundle of work.
-- **project** (`<project>/.crouter/memory/`) — any agent operating in that one repo. Facts and procedures tied to that codebase. Resolves to the nearest ancestor `.crouter/` walking up from cwd; `--dir` pins an exact repo.
+- **project** (`<project>/.crouter/memory/`) — any agent operating in that one repo. Facts and procedures tied to that codebase. Resolves to the nearest ancestor `.crouter/` walking up from cwd, plus every project in the selected profile's purview; `--dir` pins an exact repo.
 - **user** (`~/.crouter/memory/`) — person-wide facts and preferences that follow the user everywhere, regardless of repo or profile.
 - **builtin** (`src/builtin-memory/` in the crouter repo) — ships inside crtr, so *every crtr user on every host* carries it. This tier is the runtime's own self-documentation (this doc lives here); a change here is a change to the product. Author here only for guidance every crouter user needs, never for anything person- or repo-specific.

package/dist/builtin-memory/internal/memory-loading.md

@@ -47,6 +47,10 @@ Every delivery dedups per transcript keyed on (doc, rung), higher rungs piercing
 
 At boot/first-message assembly the runtime mounts: builtin docs, the user store (`~/.crouter/memory/`), the selected profile's store, and every project store — ancestor `.crouter/memory/` dirs walking up from cwd plus each project in the profile's purview. Physical duplicates are deduplicated; name collisions resolve nearest-first (project over profile over user over builtin), which is what lets a project doc shadow a builtin one.
 
+Each project the selected profile has a relationship with carries a `memory` value — `none`, `name`, `preview`, or `content` — and that value is the maximum rung anything in that project's stores delivers at boot and workspace-open, whatever directory the node is working in. It only lowers: an entry authored below the maximum delivers at its authored rung. `none` contributes nothing to either automatic event, so a `none` project cannot shadow a same-named doc from a wider scope — that wider doc becomes the winner. A project store the selected profile has no relationship with delivers exactly what it authored.
+
+The maximum reaches those two events and nothing else. Read, memory-read, and command entries fire at their authored rungs; directory listings, `crtr memory read`, `crtr memory find`, config resolution, and plugin discovery all see the full corpus. An explicit `crtr memory read` is itself a content delivery, so reading a capped doc returns its whole body and records content — the upgrade path for a doc the automatic events disclosed only by name or preview.
+
 A workspace's front door is an ordinary doc carrying the entry pair `{on: workspace-open, at: content}` + `{on: read, match: "./**", at: content}` — the operating guide loads when that workspace mounts or its files are read, not in every boot catalog. `crtr memory lint` requires exactly one workspace-open content doc per profile-managed project store. Multiple mounted roots render broad-to-specific.
 
 A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its read-routed docs, deduplicated against everything already in the transcript. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's boot entries are inert (lint warns; drop them).

package/dist/builtin-memory/plan/roadmap.md

@@ -4,7 +4,7 @@ when-and-why-to-read: When shaping a planning roadmap, deciding plan structure,
 short-form: Use when shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation.
 gate: {kind: plan}
 rationale: >-
-  The original playbook required five parallel plan reviewers before every consequential implementation and made “passes all five lenses” the ready bar. Combined with the plan persona's re-review loop, this turned lenses into agents and resolution into reviewer polling rather than plan-owner judgment.
+  The original playbook required five parallel plan reviewers before every consequential implementation and made “passes all five lenses” the ready bar. Combined with the plan persona's re-review loop, this turned lenses into agents and resolution into reviewer polling rather than plan-owner judgment. Planners also turned plausible improvements outside the specification into implementation tasks without asking, silently expanding scope.
 surfaces:
   - on: boot
     at: preview
@@ -12,6 +12,12 @@ surfaces:
 
 # Planning Playbook
 
+## Hold the specified scope
+
+Plan the simplest complete implementation of the specification and what it necessarily requires. Codebase opportunities do not expand the contract: speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out.
+
+When something seems likely desirable but is not explicitly or implicitly required by the specification, ask the user whether to include it through `crtr human` before finishing the plan (`crtr human send -h`), wait for their answer, and make the resulting boundary explicit. Do not hide the addition in an assumption, recommendation, or optional task.
+
 ## Plan Shapes and the Decomposition Decision
 
 Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choose decomposition for worthwhile parallel planning, not raw size: a flat plan can span many yields, while part-plans add delegation and synthesis cost that independent slices must repay.

package/dist/builtin-memory/spec/guide.md

@@ -2,7 +2,7 @@
 kind: knowledge
 when-and-why-to-read: When eliciting or writing a specification, this knowledge should be read because downstream design and planning need settled intent without making the user answer avoidable questions or forcing every request through the same ceremony.
 short-form: Elicit only consequential uncertainty, then write a right-sized behavioral contract a downstream reader can use without guessing.
-rationale: Specification quality and elicitation guidance lived inside an always-loaded spec persona while the lightweight /spec command had almost none, leaving agents to choose between a vague one-shot and a fixed discovery workflow.
+rationale: Specification quality and elicitation guidance lived inside an always-loaded spec persona while the lightweight /spec command had almost none, leaving agents to choose between a vague one-shot and a fixed discovery workflow. Spec writers also promoted plausible nice-to-haves into requirements without asking, silently expanding the requested work.
 ---
 
 # Writing a specification
@@ -17,6 +17,12 @@ Reflect a concrete interpretation of the request so the user can confirm or corr
 
 Spend attention where judgment is load-bearing, not where detail is merely available. Keep settled points moving and fold each answer into the specification as current truth. Stop eliciting when another answer would not materially change the behavioral contract. Explicit approval is warranted when the user is co-authoring the document or the remaining decision is consequential; ordinary reversible work does not need a ritual approval loop.
 
+## Hold the requested scope
+
+Specify the smallest complete outcome the request and its necessary implications support. Discovered possibilities do not become requirements: speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out.
+
+When something seems likely desirable but is not explicitly or implicitly required by the request, ask the user whether to include it through `crtr human` before finishing the specification (`crtr human send -h`), wait for their answer, and make the resulting boundary explicit. Do not hide the addition in an assumption, recommendation, or optional requirement.
+
 ## The finished specification
 
 A downstream reader should be able to understand the required outcome and produce a design or plan without inventing intent. Include the dimensions that matter for this request rather than forcing a section template:

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/claude-plugin-commands.ts

@@ -164,7 +164,7 @@ function selectedProfileProjects(): string[] {
   const profileId = process.env["CRTR_PROFILE_ID"] ?? "";
   if (profileId === "") return [];
   try {
-    return loadProfileManifest(profileId).manifest.projects;
+    return loadProfileManifest(profileId).manifest.projects.map((project) => project.path);
   } catch {
     // A deleted or invalid selected profile must not hide cwd-local commands.
     return [];

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crtr-commands/index.ts

@@ -4,6 +4,7 @@ import { promisify } from "node:util";
 import { readFileSync, existsSync, realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, join } from "node:path";
+import type { ChatCommandMetadata } from "../../../../core/runtime/command-surface.js";
 
 const exec = promisify(execFile);
 
@@ -149,6 +150,11 @@ export default async function (pi: ExtensionAPI) {
     const invocation = `Run \`crtr ${path.join(" ")} -h\` (pass args to run the real command)`;
     pi.registerCommand(name, {
       description: node.description ? `${node.description} — ${invocation}` : invocation,
+      // Chat-capable: the handler's outcome is the command's output placed into
+      // the conversation as a displayed message. The transient status line is
+      // decoration a surface without one simply does not show.
+      gateway: true as const,
+      argumentHint: "[args]",
       handler: async (args, ctx) => {
         const extra = (args ?? "").trim();
         // No args -> show help. With args -> run the real command.
@@ -165,7 +171,7 @@ export default async function (pi: ExtensionAPI) {
           { triggerTurn: TRIGGER_TURN },
         );
       },
-    });
+    } as Parameters<ExtensionAPI["registerCommand"]>[1] & ChatCommandMetadata);
   };
 
   const filters = loadFilters();

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts

@@ -6,6 +6,7 @@ import {
   type DeterministicCommandExpansion,
 } from "../../../core/runtime/command-expansion.js";
 import { expandShellBlocks, hasShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from "../../../core/runtime/shell-expansion.js";
+import type { ChatCommandMetadata } from "../../../core/runtime/command-surface.js";
 import { piShellRunner } from "./pi-shell-runner.js";
 
 // ---------------------------------------------------------------------------
@@ -126,7 +127,11 @@ export default async function (pi: ExtensionAPI) {
     // drift from submission. A failed/dynamic command has no expansion metadata.
     pi.registerCommand(doc.commandName, {
       description: doc.description,
-      ...(expansion === undefined ? {} : { expansion }),
+      // Chat-capable: the handler's whole outcome is a conversation turn
+      // carrying the expanded document, which any surface hosting the
+      // conversation receives. Only when the expansion loaded — without it the
+      // sole outcome is a terminal-only error notify, so it stays undisclosed.
+      ...(expansion === undefined ? {} : { expansion, gateway: true as const }),
       handler: async (args, ctx) => {
         if (expansion === undefined) {
           ctx.ui.notify(
@@ -157,6 +162,6 @@ export default async function (pi: ExtensionAPI) {
           { triggerTurn: true },
         );
       },
-    } as Parameters<ExtensionAPI["registerCommand"]>[1] & { expansion?: DeterministicCommandExpansion });
+    } as Parameters<ExtensionAPI["registerCommand"]>[1] & { expansion?: DeterministicCommandExpansion } & ChatCommandMetadata);
   }
 }

package/dist/clients/attach/__tests__/ref-autocomplete.test.js

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import { findRefCompletionContext, RefAwareAutocompleteProvider } from '../input/ref-autocomplete.js';
 function ref(name, shortForm = `${name} docs`) {
-    return { name, kind: 'knowledge', scope: 'user', shortForm };
+    return { name, kind: 'knowledge', scope: 'user', shortForm, gatewayVisible: true };
 }
 /** The wrapped provider; ref handling must never reach it in a ref context. */
 const inertDelegate = {

package/dist/clients/attach/__tests__/titled-editor-preview.test.js

@@ -47,7 +47,7 @@ test('Enter-confirming a non-leading ref completion accepts the token and return
     editor.onSubmit = (text) => {
         submitted = text;
     };
-    const refs = [{ name: 'dev', kind: 'knowledge', scope: 'user', shortForm: 'dev docs' }];
+    const refs = [{ name: 'dev', kind: 'knowledge', scope: 'user', shortForm: 'dev docs', gatewayVisible: true }];
     const delegate = {
         async getSuggestions() {
             return null;

package/dist/clients/attach/overlays/file-review.js

@@ -2,7 +2,7 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { Input, SelectList, getKeybindings, } from '@earendil-works/pi-tui';
 import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
-import { openReviewSurface } from '../../inbox/review/launch.js';
+import { openReviewWindow } from '../../inbox/review/launch.js';
 import { createReviewClient, ReviewTerminalError, terminalRefusalNotice } from '../../inbox/review/review-client.js';
 import { checkReviewableFile, extractFilePaths } from '#core/human/visible-paths';
 const MAX_VISIBLE_ROWS = 12;
@@ -123,6 +123,6 @@ export async function launchFileReview(host, file, opts) {
         opts.onNotice(err instanceof ReviewTerminalError ? terminalRefusalNotice(err) : err instanceof Error ? err.message : String(err));
         return;
     }
-    await openReviewSurface(host, { review });
+    openReviewWindow(host, review);
 }
 export { extractFilePaths };

package/dist/clients/attach/session/keys.d.ts

@@ -31,7 +31,7 @@ export interface KeyHooks {
     toggleInboxStrip: () => void;
     cycleModelLadder: (direction: 'forward' | 'backward') => void;
     inspectLoadedCommand: () => void;
-    /** The file-review chord — open the transcript-file picker + review surface. */
+    /** The file-review chord — pick a transcript file and open its review window. */
     openFileReview: () => void;
     /** Search the current node's local profile project files. */
     openProfileFiles: () => void;

package/dist/clients/attach/session/profile-files.js

@@ -50,7 +50,7 @@ function profileSearchRoots(profileId) {
         return { projects: [], memory: null };
     try {
         const { profileId: resolvedId, manifest } = loadProfileManifest(profileId);
-        return { projects: manifest.projects, memory: profileMemoryDir(resolvedId) };
+        return { projects: manifest.projects.map((project) => project.path), memory: profileMemoryDir(resolvedId) };
     }
     catch {
         return { projects: [], memory: null };