@shrkcrft/cli 0.1.0-alpha.2

package/dist/surface/about.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Long-form `--about` rendering. Pulls from
+ * `docs/overview.md` + `docs/philosophy.md` content, baked at build
+ * time so it works offline.
+ *
+ * Keep this short — one screen. The authoritative docs live under
+ * `docs/`; this is the in-binary summary.
+ */
+export declare function renderAbout(): string;
+//# sourceMappingURL=about.d.ts.map

package/dist/surface/about.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"about.d.ts","sourceRoot":"","sources":["../../src/surface/about.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CA2CpC"}

package/dist/surface/about.js

@@ -0,0 +1,53 @@
+import { SHARKCRAFT_VERSION } from '@shrkcrft/shared';
+/**
+ * Long-form `--about` rendering. Pulls from
+ * `docs/overview.md` + `docs/philosophy.md` content, baked at build
+ * time so it works offline.
+ *
+ * Keep this short — one screen. The authoritative docs live under
+ * `docs/`; this is the in-binary summary.
+ */
+export function renderAbout() {
+    return `SharkCraft v${SHARKCRAFT_VERSION}
+
+What it is
+  A deterministic, local-first toolkit that gives AI coding agents
+  durable project context. Ships as a CLI (\`shrk\`) — the only write
+  path — plus a read-only MCP server, plus a library of structured
+  assets (knowledge, rules, paths, templates, pipelines, presets,
+  boundaries).
+
+What it is NOT
+  There is no AI inside the engine. Every output is a pure function
+  of the workspace + the asset registries. The agent uses the engine;
+  the engine never calls a model.
+
+The safety contract
+  - All write paths are preview-first. \`--apply\` is opt-in, scoped,
+    and idempotent.
+  - MCP is read-only. Every MCP tool returns data + a next-command
+    hint; the human runs the CLI for any write.
+  - Apply requires \`--verify-signature\` for signed plans, refuses
+    on divergence unless \`--allow-divergent\`.
+
+Calibration to project size
+  Surface tiers (\`shrk surface list\`):
+    - core         always on
+    - extended     visible in --help, callable
+    - experimental hidden until enabled (\`shrk surface enable\`)
+  Project shape (\`shrk doctor\`) drives the default surface for a
+  fresh repo.
+
+Where to read more
+  docs/overview.md        what SharkCraft is and isn't
+  docs/philosophy.md      the non-negotiable design rules
+  docs/surface-tiers.md   the tier model
+  docs/safety-model.md    plan / review / apply contract
+
+Quick start
+  shrk doctor             health check
+  shrk task "<what>"      full task packet (rules + templates + commands)
+  shrk recommend "<what>" what command should I reach for?
+  shrk surface list       what is available in this repo
+`;
+}

package/dist/surface/load-surface-context.d.ts

@@ -0,0 +1,34 @@
+import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import { type ISurfaceProfile } from './profiles.js';
+import type { ITierResolverContext } from './tier.js';
+export interface LoadSurfaceContextOptions {
+    cwd: string;
+    /** Optional pre-loaded inspection to avoid the double-load cost. */
+    inspection?: ISharkcraftInspection;
+}
+export interface ILoadedSurfaceContext {
+    context: ITierResolverContext;
+    inspection: ISharkcraftInspection;
+    /**
+     * Profiles in effect for this resolution: built-in
+     * profiles known to the resolver + any pack-contributed profiles.
+     * Sorted: builtin first, then pack contributions.
+     */
+    availableProfiles: readonly ISurfaceProfile[];
+    /** The resolved profile (after config.surface.profile lookup), if any. */
+    activeProfile?: ISurfaceProfile;
+}
+/**
+ * Build the {@link ITierResolverContext} from a workspace.
+ *
+ * Steps:
+ *   1. Load (or reuse) the inspector for `cwd`.
+ *   2. Extract spine commands from the pipeline registry.
+ *   3. Collect pack-contributed commands (currently empty in the
+ *      engine repo — `ICommandPlugin` exists in the plugin-api but no
+ *      pack contributes commands today; future packs will populate
+ *      the inspection's pack discovery).
+ *   4. Read the user's `surface{}` config block.
+ */
+export declare function loadSurfaceContext(options: LoadSurfaceContextOptions): Promise<ILoadedSurfaceContext>;
+//# sourceMappingURL=load-surface-context.d.ts.map

package/dist/surface/load-surface-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-surface-context.d.ts","sourceRoot":"","sources":["../../src/surface/load-surface-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAGpF,OAAO,EAAgC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,UAAU,EAAE,qBAAqB,CAAC;IAClC;;;;OAIG;IACH,iBAAiB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,0EAA0E;IAC1E,aAAa,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,qBAAqB,CAAC,CAmChC"}

package/dist/surface/load-surface-context.js

@@ -0,0 +1,100 @@
+import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { extractSpineCommands } from "./spine-extractor.js";
+import { BUILTIN_PROFILES, getProfile } from "./profiles.js";
+/**
+ * Build the {@link ITierResolverContext} from a workspace.
+ *
+ * Steps:
+ *   1. Load (or reuse) the inspector for `cwd`.
+ *   2. Extract spine commands from the pipeline registry.
+ *   3. Collect pack-contributed commands (currently empty in the
+ *      engine repo — `ICommandPlugin` exists in the plugin-api but no
+ *      pack contributes commands today; future packs will populate
+ *      the inspection's pack discovery).
+ *   4. Read the user's `surface{}` config block.
+ */
+export async function loadSurfaceContext(options) {
+    const inspection = options.inspection ?? (await inspectSharkcraft({ cwd: options.cwd }));
+    const spineCommands = extractSpineCommands(inspection.pipelines);
+    const packContributions = collectPackContributions(inspection);
+    const packProfiles = collectPackProfiles(inspection);
+    const rawConfig = inspection.config?.surface ?? undefined;
+    // Resolve profile (built-in or pack-contributed).
+    const profileId = rawConfig?.profile;
+    const activeProfile = profileId
+        ? getProfile(profileId, packProfiles)
+        : undefined;
+    // Compose profile.hidden + config.hidden / profile.enabled + config.enabled.
+    // Config wins on conflicts (explicit user choice over profile default).
+    const mergedHidden = mergeUnique(activeProfile?.hidden, rawConfig?.hidden);
+    const mergedEnabled = mergeUnique(activeProfile?.enabled, rawConfig?.enabled);
+    const surfaceConfig = rawConfig || activeProfile
+        ? {
+            ...(profileId ? { profile: profileId } : {}),
+            ...(mergedHidden.length > 0 ? { hidden: mergedHidden } : {}),
+            ...(mergedEnabled.length > 0 ? { enabled: mergedEnabled } : {}),
+        }
+        : undefined;
+    return {
+        inspection,
+        context: { spineCommands, packContributions, surfaceConfig },
+        availableProfiles: [...BUILTIN_PROFILES, ...packProfiles],
+        ...(activeProfile ? { activeProfile } : {}),
+    };
+}
+function mergeUnique(a, b) {
+    const set = new Set([...(a ?? []), ...(b ?? [])]);
+    return [...set].sort();
+}
+/**
+ * Collect pack-contributed surface profiles. Pack
+ * manifests can declare `contributions.surfaceProfiles[]`. Today this
+ * is a new manifest slot — older packs return zero.
+ */
+function collectPackProfiles(inspection) {
+    const out = [];
+    const packs = inspection.packs?.discoveredPacks ?? [];
+    for (const pack of packs) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        const raw = contributions.surfaceProfiles ?? [];
+        for (const r of raw) {
+            if (typeof r?.id !== 'string' || r.id.length === 0)
+                continue;
+            out.push({
+                id: r.id,
+                description: typeof r.description === 'string' ? r.description : `Pack profile (${pack.packageName})`,
+                source: 'pack',
+                pack: pack.packageName,
+                ...(Array.isArray(r.hidden) ? { hidden: r.hidden.filter((s) => typeof s === 'string') } : {}),
+                ...(Array.isArray(r.enabled) ? { enabled: r.enabled.filter((s) => typeof s === 'string') } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Collect pack-contributed CLI command names. Today the pack
+ * manifest schema has no `commandFiles[]` contribution slot, so this
+ * always returns an empty map in the current engine repo. The
+ * future-proofing is intentional: when packs gain command-contribution
+ * support, the tier resolver immediately starts marking them
+ * `experimental` by default.
+ *
+ * The lookup walks `IDiscoveredPack.manifest.contributions.commands[]`
+ * defensively — the field doesn't exist in the v1 manifest schema, but
+ * a future schema bump can add it without changing this code.
+ */
+function collectPackContributions(inspection) {
+    const map = new Map();
+    const packs = inspection.packs?.discoveredPacks ?? [];
+    for (const pack of packs) {
+        const contributions = (pack.manifest?.contributions ?? {});
+        const commands = contributions.commands ?? [];
+        for (const cmd of commands) {
+            if (typeof cmd?.name === 'string' && cmd.name.length > 0) {
+                map.set(cmd.name, pack.packageName);
+            }
+        }
+    }
+    return map;
+}

package/dist/surface/no-args-landing.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The curated landing rendered when a user runs bare `shrk`
+ * (no args). Falls back to four hardcoded suggestions when the
+ * inspector / recommender fails (fresh repo without a config).
+ */
+export declare function renderNoArgsLanding(cwd: string): Promise<string>;
+//# sourceMappingURL=no-args-landing.d.ts.map

package/dist/surface/no-args-landing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-args-landing.d.ts","sourceRoot":"","sources":["../../src/surface/no-args-landing.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BtE"}

package/dist/surface/no-args-landing.js

@@ -0,0 +1,36 @@
+import { SHARKCRAFT_VERSION } from '@shrkcrft/shared';
+import { loadSurfaceContext } from "./load-surface-context.js";
+import { buildSurfaceSummary } from "./surface-summary.js";
+/**
+ * The curated landing rendered when a user runs bare `shrk`
+ * (no args). Falls back to four hardcoded suggestions when the
+ * inspector / recommender fails (fresh repo without a config).
+ */
+export async function renderNoArgsLanding(cwd) {
+    const lines = [];
+    lines.push(`shrk v${SHARKCRAFT_VERSION} — deterministic context for AI coding agents.`);
+    lines.push('');
+    let totals = '';
+    try {
+        const { context } = await loadSurfaceContext({ cwd });
+        const summary = buildSurfaceSummary(context);
+        totals = `Surface: ${summary.totals.core} core + ${summary.totals.extended} extended (${summary.tiers.extended.filter((c) => c.hidden).length} hidden, ${summary.tiers.experimental.filter((c) => c.enabled).length} experimental enabled).`;
+    }
+    catch {
+        totals = 'Surface: (run `shrk doctor` to load the workspace).';
+    }
+    lines.push(totals);
+    lines.push('');
+    lines.push('Most useful next:');
+    lines.push('  shrk doctor                 health check');
+    lines.push('  shrk task "<what>"          full packet for a task');
+    lines.push('  shrk recommend "<what>"     what should I do?');
+    lines.push('  shrk surface list           what is available in this repo');
+    lines.push('');
+    lines.push('See:');
+    lines.push('  shrk --help                 every visible command');
+    lines.push('  shrk surface explain <cmd>  why a command is/is not visible');
+    lines.push('  shrk --about                what shrk is and is not');
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/surface/not-enabled-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured error returned when a user / agent invokes an
+ * experimental command that is not enabled in the current repo's
+ * `sharkcraft.config.ts surface.enabled[]`.
+ *
+ * Exit code distinguishes "command exists but is gated" from
+ * "command unknown" (which exits 2 via the did-you-mean path in
+ * main.ts).
+ */
+export declare const SURFACE_NOT_ENABLED_EXIT_CODE = 78;
+export declare const SURFACE_NOT_ENABLED_SCHEMA = "sharkcraft.surface.not-enabled.v1";
+export interface ISurfaceNotEnabledError {
+    schema: typeof SURFACE_NOT_ENABLED_SCHEMA;
+    command: string;
+    tier: 'experimental';
+    reason: string;
+    enableCommand: string;
+    explainCommand: string;
+}
+export declare function makeSurfaceNotEnabledError(command: string, options?: {
+    reason?: string;
+}): ISurfaceNotEnabledError;
+export declare function renderSurfaceNotEnabledText(err: ISurfaceNotEnabledError): string;
+//# sourceMappingURL=not-enabled-error.d.ts.map

package/dist/surface/not-enabled-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-enabled-error.d.ts","sourceRoot":"","sources":["../../src/surface/not-enabled-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,uBAAuB,CAWzB;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,uBAAuB,GAC3B,MAAM,CAaR"}

package/dist/surface/not-enabled-error.js

@@ -0,0 +1,36 @@
+/**
+ * Structured error returned when a user / agent invokes an
+ * experimental command that is not enabled in the current repo's
+ * `sharkcraft.config.ts surface.enabled[]`.
+ *
+ * Exit code distinguishes "command exists but is gated" from
+ * "command unknown" (which exits 2 via the did-you-mean path in
+ * main.ts).
+ */
+export const SURFACE_NOT_ENABLED_EXIT_CODE = 78;
+export const SURFACE_NOT_ENABLED_SCHEMA = 'sharkcraft.surface.not-enabled.v1';
+export function makeSurfaceNotEnabledError(command, options = {}) {
+    return {
+        schema: SURFACE_NOT_ENABLED_SCHEMA,
+        command,
+        tier: 'experimental',
+        reason: options.reason ??
+            `Command \`${command}\` is an experimental tier — not enabled in this repo.`,
+        enableCommand: `shrk surface enable ${command}`,
+        explainCommand: `shrk surface explain ${command}`,
+    };
+}
+export function renderSurfaceNotEnabledText(err) {
+    const lines = [];
+    lines.push(`Command \`${err.command}\` exists but is not enabled in this repo.`);
+    lines.push('');
+    lines.push(`It is tier=${err.tier}. ${err.reason}`);
+    lines.push('');
+    lines.push('Enable it:');
+    lines.push(`  $ ${err.enableCommand}`);
+    lines.push('');
+    lines.push('Or see why it is gated:');
+    lines.push(`  $ ${err.explainCommand}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/surface/profiles.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Surface profiles.
+ *
+ * A profile is a named set of `surface.hidden` + `surface.enabled`
+ * adjustments. Built-in profiles ship from the engine; packs can
+ * contribute additional profiles via the pack manifest (see
+ * load-surface-context.ts). The user selects one via
+ * `sharkcraft.config.ts surface.profile`.
+ *
+ * Profiles are PURE DATA — no logic, no AI. Adding a profile is just
+ * adding an entry here (or in a pack manifest).
+ */
+export interface ISurfaceProfile {
+    /** Stable id used by `surface.profile` config + CLI selection. */
+    id: string;
+    /** One-line description shown in `surface profiles list`. */
+    description: string;
+    /** Extended commands this profile hides from `--help`. */
+    hidden?: readonly string[];
+    /**
+     * Experimental commands this profile enables. Use sparingly —
+     * profiles should compose with packs' default `experimental`
+     * classification, not paper over it.
+     */
+    enabled?: readonly string[];
+    /** Where the profile comes from (annotation for `surface explain`). */
+    source: 'builtin' | 'pack' | 'local';
+    /** When source='pack', the pack name. */
+    pack?: string;
+}
+/** Catalog of built-in profiles. */
+export declare const BUILTIN_PROFILES: readonly ISurfaceProfile[];
+/** Build a map of all profiles (builtin + pack-contributed). */
+export declare function indexProfiles(packProfiles?: readonly ISurfaceProfile[]): Map<string, ISurfaceProfile>;
+/** Look up a profile by id; returns undefined if unknown. */
+export declare function getProfile(id: string, packProfiles?: readonly ISurfaceProfile[]): ISurfaceProfile | undefined;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/surface/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/surface/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uEAAuE;IACvE,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgID,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAOrD,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,aAAa,CAC3B,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,eAAe,GAAG,SAAS,CAE7B"}

package/dist/surface/profiles.js

@@ -0,0 +1,151 @@
+/**
+ * Surface profiles.
+ *
+ * A profile is a named set of `surface.hidden` + `surface.enabled`
+ * adjustments. Built-in profiles ship from the engine; packs can
+ * contribute additional profiles via the pack manifest (see
+ * load-surface-context.ts). The user selects one via
+ * `sharkcraft.config.ts surface.profile`.
+ *
+ * Profiles are PURE DATA — no logic, no AI. Adding a profile is just
+ * adding an entry here (or in a pack manifest).
+ */
+/**
+ * `developer` profile. Default for monorepo / app-with-libs shapes.
+ * Hides nothing — pack authors / power users see the full extended
+ * surface.
+ */
+const DEVELOPER_PROFILE = {
+    id: 'developer',
+    description: 'Full visible surface for power users / pack authors / engine contributors. Hides nothing.',
+    source: 'builtin',
+};
+/**
+ * `small-app` profile. Default for single-app shape (Angular, Next,
+ * etc.). Hides monorepo-only verbs from --help; the commands remain
+ * CALLABLE (use `surface unhide` to restore).
+ */
+const SMALL_APP_PROFILE = {
+    id: 'small-app',
+    description: 'Single-app / small-team default. Hides monorepo + pack-authoring + bundle verbs from --help.',
+    source: 'builtin',
+    hidden: [
+        // Bundle / replay machinery — not used in single-app workflows.
+        'bundle',
+        'bundle apply-assist',
+        'bundle apply-assist --resume',
+        'bundle create',
+        'bundle diff',
+        'bundle graph',
+        'bundle list',
+        'bundle plan',
+        'bundle replay',
+        'bundle show',
+        'bundle validate',
+        // Reposet / multi-repo orchestration — irrelevant for a single app.
+        'reposet',
+        'reposet init',
+        'reposet doctor',
+        'reposet list',
+        'reposet map',
+        // Pack authoring — single apps rarely author packs.
+        'pack',
+        'pack author preview',
+        'pack author pending',
+        'pack author status',
+        'pack author validate',
+        'packs new',
+        'packs sign',
+        'packs verify',
+        'packs release-check',
+        'packs compat',
+        'packs dev-status',
+        'packs watch',
+    ],
+};
+/**
+ * `monorepo` profile. Default for monorepo / app-with-libs shapes.
+ * Same as developer; explicit so a user can opt in.
+ */
+const MONOREPO_PROFILE = {
+    id: 'monorepo',
+    description: 'Monorepo default. Full visible surface, including bundle / reposet / pack-authoring.',
+    source: 'builtin',
+};
+/**
+ * `pack-author` profile. Hides app-only verbs; keeps pack authoring
+ * + signing + release-check prominent.
+ */
+const PACK_AUTHOR_PROFILE = {
+    id: 'pack-author',
+    description: 'Pack author default. Hides app / runtime verbs; surfaces pack-* prominently.',
+    source: 'builtin',
+    hidden: [
+        'dev',
+        'dev start',
+        'dev status',
+        'dev report',
+        'review',
+        'review render-comment',
+    ],
+};
+/**
+ * `ci` profile. Hides interactive / app verbs; keeps gates +
+ * read-only checks visible.
+ */
+const CI_PROFILE = {
+    id: 'ci',
+    description: 'CI default. Hides interactive / write-source verbs; keeps gates + read-only checks visible.',
+    source: 'builtin',
+    hidden: [
+        'dev',
+        'dev start',
+        'dev status',
+        'dev report',
+        'session',
+        'ask',
+        'orchestrate',
+    ],
+};
+/**
+ * `agent` profile. Optimized for MCP / agent use. Hides interactive
+ * verbs; keeps JSON / read-only verbs visible.
+ */
+const AGENT_PROFILE = {
+    id: 'agent',
+    description: 'Agent / MCP-friendly default. Hides interactive verbs; favors JSON-pipe surfaces.',
+    source: 'builtin',
+    hidden: [
+        'dev',
+        'dev start',
+        'dev status',
+        'dev report',
+        'orchestrate',
+        'ask',
+    ],
+};
+/** Catalog of built-in profiles. */
+export const BUILTIN_PROFILES = Object.freeze([
+    DEVELOPER_PROFILE,
+    SMALL_APP_PROFILE,
+    MONOREPO_PROFILE,
+    PACK_AUTHOR_PROFILE,
+    CI_PROFILE,
+    AGENT_PROFILE,
+]);
+/** Build a map of all profiles (builtin + pack-contributed). */
+export function indexProfiles(packProfiles = []) {
+    const map = new Map();
+    for (const p of BUILTIN_PROFILES)
+        map.set(p.id, p);
+    // Pack profiles can override builtin profiles by id (intentional —
+    // a pack that ships e.g. a 'monorepo-developer' profile gets first
+    // dibs over any namespace collision).
+    for (const p of packProfiles)
+        map.set(p.id, p);
+    return map;
+}
+/** Look up a profile by id; returns undefined if unknown. */
+export function getProfile(id, packProfiles = []) {
+    return indexProfiles(packProfiles).get(id);
+}

package/dist/surface/shape-defaults.d.ts

@@ -0,0 +1,21 @@
+import { ProjectShape } from '@shrkcrft/workspace';
+/**
+ * Default `surface.hidden[]` seeding by project shape.
+ *
+ * Conservative cut: each list is small and explicitly justified. The
+ * shape detector seeds these only when the user runs `shrk init
+ * --write` (preview-first). Existing repos are not touched.
+ *
+ * Rationale:
+ *   - `single-app` repos don't need monorepo-only commands by
+ *     default. They stay callable; just hidden from --help.
+ *   - `library` repos hide app/runtime-only commands.
+ *   - `monorepo` and `app-with-libs` keep the full default surface.
+ */
+export declare const SHAPE_HIDDEN_DEFAULTS: Readonly<Record<ProjectShape, readonly string[]>>;
+export declare function defaultHiddenForShape(shape: ProjectShape): readonly string[];
+export declare function renderShapeLine(detection: {
+    shape: ProjectShape;
+    evidence: readonly string[];
+}): string;
+//# sourceMappingURL=shape-defaults.d.ts.map

package/dist/surface/shape-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-defaults.d.ts","sourceRoot":"","sources":["../../src/surface/shape-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC,CA4BlF,CAAC;AAEH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAE5E;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE;IACzC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,GAAG,MAAM,CAGT"}

package/dist/surface/shape-defaults.js

@@ -0,0 +1,50 @@
+import { ProjectShape } from '@shrkcrft/workspace';
+/**
+ * Default `surface.hidden[]` seeding by project shape.
+ *
+ * Conservative cut: each list is small and explicitly justified. The
+ * shape detector seeds these only when the user runs `shrk init
+ * --write` (preview-first). Existing repos are not touched.
+ *
+ * Rationale:
+ *   - `single-app` repos don't need monorepo-only commands by
+ *     default. They stay callable; just hidden from --help.
+ *   - `library` repos hide app/runtime-only commands.
+ *   - `monorepo` and `app-with-libs` keep the full default surface.
+ */
+export const SHAPE_HIDDEN_DEFAULTS = Object.freeze({
+    [ProjectShape.SingleApp]: Object.freeze([
+        'bundle',
+        'bundle apply-assist',
+        'bundle create',
+        'bundle diff',
+        'bundle list',
+        'bundle plan',
+        'bundle replay',
+        'bundle show',
+        'bundle validate',
+        'reposet',
+        'pack',
+        'packs new',
+        'packs sign',
+        'packs verify',
+        'packs release-check',
+        'packs compat',
+    ]),
+    [ProjectShape.Library]: Object.freeze([
+        'dev',
+        'dev start',
+        'dev status',
+        'dev report',
+    ]),
+    [ProjectShape.AppWithLibs]: Object.freeze([]),
+    [ProjectShape.Monorepo]: Object.freeze([]),
+    [ProjectShape.Unknown]: Object.freeze([]),
+});
+export function defaultHiddenForShape(shape) {
+    return SHAPE_HIDDEN_DEFAULTS[shape] ?? [];
+}
+export function renderShapeLine(detection) {
+    const ev = detection.evidence.length > 0 ? ` (${detection.evidence[0]})` : '';
+    return `Project shape: ${detection.shape}${ev}`;
+}

package/dist/surface/spine-extractor.d.ts

@@ -0,0 +1,38 @@
+import type { IPipelineDefinition } from '@shrkcrft/pipelines';
+/**
+ * IDs of pipelines treated as the "spine" — pipelines whose
+ * referenced commands are tier=Core regardless of any other catalog
+ * derivation rule.
+ *
+ * Today only `engine.feature-dev` exists in the engine repo.
+ * `engine.safe-generation` is a planned second spine pipeline; if a
+ * project ships it, it's automatically picked up here.
+ */
+export declare const SPINE_PIPELINE_IDS: readonly string[];
+/**
+ * Extract the catalog command names referenced from spine
+ * pipelines AND in the core verb allowlist. The function does NOT
+ * execute any pipeline — it walks `steps[].cliCommands[]` and parses
+ * out the verb path.
+ *
+ * Parsing rule: each `cliCommands` entry is a shell-style string like
+ * `bun run shrk plan review /tmp/plan.json`. The parser strips a
+ * leading `bun run shrk` or `shrk` and returns the first 1-2 tokens
+ * as a command path. Multi-token paths are joined with a space so
+ * they match {@link ICommandCatalogEntry.command} entries that already
+ * use this form (`pack author status`, `plan review`).
+ */
+export declare function extractSpineCommands(pipelines: readonly IPipelineDefinition[]): ReadonlySet<string>;
+/**
+ * Parse a single CLI command string into its catalog `command`
+ * path. Returns `undefined` if the string doesn't reference shrk.
+ *
+ * Examples:
+ *   `bun run shrk doctor`                      → `doctor`
+ *   `bun run shrk plan review /tmp/plan.json`  → `plan review`
+ *   `bun run shrk pack author status`          → `pack author status`
+ *   `bun run shrk context --task "<task>"`     → `context`
+ *   `bun x tsc`                                → undefined
+ */
+export declare function parseCommandVerb(raw: string): string | undefined;
+//# sourceMappingURL=spine-extractor.d.ts.map

package/dist/surface/spine-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine-extractor.d.ts","sourceRoot":"","sources":["../../src/surface/spine-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAG9C,CAAC;AAeH;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,mBAAmB,EAAE,GACxC,WAAW,CAAC,MAAM,CAAC,CAerB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA+BhE"}