@shrkcrft/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/commands/doctor.command.js

@@ -38,7 +38,7 @@ function describeStrictMode(mode) {
         case 'all':
             return 'strict=all (every warning fails)';
         case 'warnings':
-            return 'strict=warnings (structural warnings fail, hint-quality excluded)';
+            return 'strict=warnings (structural warnings fail, advisory excluded)';
         case 'errors':
             return 'strict=errors (only errors fail)';
         case 'off':
@@ -59,8 +59,10 @@ function evaluateStrict(mode, checks, errorCount) {
     for (const c of checks) {
         if (c.severity !== DoctorSeverity.Warning)
             continue;
-        const isHintQuality = c.id.startsWith('actionhints-');
-        if (mode === 'warnings' && isHintQuality) {
+        // `--strict=warnings` excludes anything the inspector flagged as
+        // advisory (action-hint quality today, any future advisory category
+        // tomorrow). `--strict=all` counts every warning, advisory or not.
+        if (mode === 'warnings' && c.advisory === true) {
             excludedWarnings += 1;
         }
         else {
@@ -74,7 +76,7 @@ function evaluateStrict(mode, checks, errorCount) {
         excludedWarnings,
         reason: mode === 'all'
             ? 'any warning'
-            : 'structural warnings only (hint-quality excluded)',
+            : 'structural warnings only (advisory excluded)',
     };
 }
 function buildFilterOptions(args, suppressions) {
@@ -420,7 +422,7 @@ async function doctorCommandImpl(args) {
     void saveDoctorSuppressions;
     void existsSync;
     if (strictMode === 'warnings' && strictEval.excludedWarnings > 0) {
-        process.stdout.write(`  (strict=warnings excluded ${strictEval.excludedWarnings} hint-quality warning(s); use --strict=all to include)\n`);
+        process.stdout.write(`  (strict=warnings excluded ${strictEval.excludedWarnings} advisory warning(s); use --strict=all to include)\n`);
     }
     // Surface acknowledgement state. Bare suppressions don't qualify as
     // acknowledgements; expiring/expired ones get a callout so authors don't
@@ -458,10 +460,27 @@ async function doctorCommandImpl(args) {
     if (!inspection.sharkcraftDir) {
         process.stdout.write('\nNothing here yet — try `shrk init --zero-config` to detect your stack and pick a preset.\n');
     }
-    process.stdout.write(`\nAI-readiness: ${report.score} / 100 (${report.grade})\n`);
+    // Honest binary verdicts come first — yes/no on the two questions
+    // users actually want answered (can I let an agent write here? can
+    // I let an agent read here?). The 0..100 score follows, scoped to
+    // the workspace shape so libraries don't get dinged for "no
+    // pipelines" and apps don't get dinged for "no published API".
+    process.stdout.write(`\nShape: ${report.workspaceShape.label}` +
+        ` (score counts ${report.dimensions.filter((d) => d.applies === 'core').length} of ${report.dimensions.length} dimensions)\n`);
+    process.stdout.write(`  ${report.verdicts.readyForAgentReads ? '✓' : '✗'} Ready for agent reads (context / task lookups)\n`);
+    process.stdout.write(`  ${report.verdicts.readyForAgentWrites ? '✓' : '✗'} Ready for agent writes (apply / generate)\n`);
+    if (report.verdicts.blockers.length > 0) {
+        process.stdout.write(`  Blockers:\n`);
+        for (const b of report.verdicts.blockers) {
+            process.stdout.write(`    • ${b}\n`);
+        }
+    }
+    process.stdout.write(`\nAI-readiness: ${report.score} / 100 (${report.grade}, shape-aware)\n`);
     if (report.topRecommendations.length) {
         // Keep the default doctor output short: top 3 recommendations,
-        // pass `--verbose` for the full list.
+        // pass `--verbose` for the full list. Recommendations only fire
+        // from `core` dimensions now — n/a-for-shape dimensions stop
+        // generating the misleading "add a pipeline" advice for libraries.
         const verbose = flagBool(args, 'verbose');
         const visible = verbose ? report.topRecommendations : report.topRecommendations.slice(0, 3);
         process.stdout.write(`Top recommendations${verbose ? '' : ` (top ${visible.length})`}:\n`);
@@ -471,6 +490,21 @@ async function doctorCommandImpl(args) {
             process.stdout.write(`  … (${report.topRecommendations.length - visible.length} more — pass --verbose to see all)\n`);
         }
     }
+    // Surface N/A dimensions when --show-na is passed, so users can see
+    // what was deliberately skipped and disagree if they want to.
+    if (flagBool(args, 'show-na')) {
+        const skipped = report.dimensions.filter((d) => d.applies !== 'core');
+        if (skipped.length > 0) {
+            process.stdout.write(`\nNot counted in score (${skipped.length} dimensions):\n`);
+            for (const d of skipped) {
+                const tag = d.applies === 'n/a-for-shape' ? 'n/a' : 'advisory';
+                process.stdout.write(`  [${tag}] ${d.title}: ${d.note}`);
+                if (d.appliesReason)
+                    process.stdout.write(` — ${d.appliesReason}`);
+                process.stdout.write('\n');
+            }
+        }
+    }
     if (strictEval.failed) {
         process.stdout.write(`\nStrict mode: failing because ${strictEval.countedWarnings} warning(s) + ${result.summary.errors} error(s) exist (${strictEval.reason}).\n`);
     }

package/dist/commands/export.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.command.d.ts","sourceRoot":"","sources":["../../src/commands/export.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,aAAa,EAAE,eAkF3B,CAAC"}
+{"version":3,"file":"export.command.d.ts","sourceRoot":"","sources":["../../src/commands/export.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,aAAa,EAAE,eAuF3B,CAAC"}

package/dist/commands/export.command.js

@@ -2,8 +2,9 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
 import { ALL_EXPORT_FORMATS, isExportFormat, renderExport, } from "../export/export-formats.js";
+import { buildClaudeCommands } from "../export/claude-commands-export.js";
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
-import { asJson, header } from "../output/format-output.js";
+import { asJson, bullet, header } from "../output/format-output.js";
 import { exportBundleCommand, exportSessionCommand, exportQualityCommand, exportReviewCommand, } from "./export-bundle.command.js";
 const ARCHIVE_SUBCOMMANDS = {
     bundle: exportBundleCommand,
@@ -13,7 +14,7 @@ const ARCHIVE_SUBCOMMANDS = {
 };
 export const exportCommand = {
     name: 'export',
-    description: 'Render SharkCraft knowledge as a flat agent-rule file (AGENTS.md / CLAUDE.md / .cursor/rules / copilot-instructions). Dry-run by default; pass --write to save.',
+    description: 'Inversion — pull SharkCraft rules into the agent\'s prompt instead of the agent calling back to shrk. Single-file outputs: claude-skill (.claude/skills/<name>/SKILL.md, recommended), agents-md (AGENTS.md), claude-md (CLAUDE.md), cursor-rules (.cursor/rules/*.mdc), copilot-instructions. Multi-file output: claude-commands (.claude/commands/*.md — per-project slash commands like /new-service, /check-changes, /follow-shrk). Dry-run by default; pass --write to save.',
     usage: 'shrk [--cwd <dir>] export <format> [--write] [--output <path>] [--task "<task>"] [--max-rules N] [--max-paths N] [--json]',
     async run(args) {
         const format = args.positional[0];
@@ -27,8 +28,13 @@ export const exportCommand = {
             const sub = { ...args, positional: args.positional.slice(1) };
             return archive.run(sub);
         }
+        // Multi-file `claude-commands` dispatches separately — it emits
+        // one .md per slash command, not a single rendered file.
+        if (format === 'claude-commands') {
+            return runClaudeCommandsExport(args);
+        }
         if (!isExportFormat(format)) {
-            process.stderr.write(`Unknown export format "${format}".\nFormats: ${ALL_EXPORT_FORMATS.join(', ')}, bundle, session, quality, review\n`);
+            process.stderr.write(`Unknown export format "${format}".\nFormats: ${ALL_EXPORT_FORMATS.join(', ')}, claude-commands, bundle, session, quality, review\n`);
             return 2;
         }
         const cwd = resolveCwd(args);
@@ -81,3 +87,70 @@ export const exportCommand = {
         return 0;
     },
 };
+/**
+ * `shrk export claude-commands` — multi-file generator for Claude
+ * Code's native `.claude/commands/` slash-command primitive. Produces
+ * one .md per command (static + per-template).
+ *
+ * Unlike single-file exports (claude-skill / claude-md / etc.) this
+ * writes a SET of files. Each file is a complete recipe Claude Code
+ * loads when the user types the matching slash command.
+ */
+async function runClaudeCommandsExport(args) {
+    const cwd = resolveCwd(args);
+    const inspection = await inspectSharkcraft({ cwd });
+    const result = buildClaudeCommands(inspection);
+    const wantJson = flagBool(args, 'json');
+    const doWrite = flagBool(args, 'write');
+    const force = flagBool(args, 'force');
+    if (wantJson) {
+        process.stdout.write(asJson({
+            format: 'claude-commands',
+            write: doWrite,
+            files: result.files.map((f) => ({
+                path: f.path,
+                slash: f.slash,
+                source: f.source,
+            })),
+        }) + '\n');
+        return 0;
+    }
+    if (!doWrite) {
+        process.stdout.write(header('Export (claude-commands) — dry-run'));
+        process.stdout.write(`Would write ${result.files.length} command file(s):\n\n`);
+        for (const f of result.files) {
+            process.stdout.write(`  ${f.path}\n`);
+            process.stdout.write(`    → users type \`/${f.slash}\` in Claude Code (${f.source})\n`);
+        }
+        process.stdout.write('\nRe-run with --write to save.\n');
+        return 0;
+    }
+    const written = [];
+    const skipped = [];
+    for (const file of result.files) {
+        const fullPath = join(cwd, file.path);
+        mkdirSync(dirname(fullPath), { recursive: true });
+        if (existsSync(fullPath) && !force) {
+            skipped.push(file.path);
+            continue;
+        }
+        writeFileSync(fullPath, file.content, 'utf8');
+        written.push(file.path);
+    }
+    process.stdout.write(header('Claude commands exported'));
+    if (written.length) {
+        process.stdout.write(`Wrote ${written.length} command file(s):\n`);
+        for (const p of written) {
+            const f = result.files.find((x) => x.path === p);
+            process.stdout.write(bullet(`${p}  → \`/${f.slash}\``) + '\n');
+        }
+    }
+    if (skipped.length) {
+        process.stdout.write(`\nSkipped ${skipped.length} (already exist; use --force to overwrite):\n`);
+        for (const p of skipped)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    process.stdout.write('\nClaude Code picks up `.claude/commands/*.md` automatically. ' +
+        'Open the project in Claude Code, type `/` — the slash commands are in the palette.\n');
+    return 0;
+}

package/dist/commands/help.command.d.ts

@@ -1,8 +1,9 @@
 import type { CommandRegistry } from '../command-registry.js';
 /**
- * Short product start screen for bare `shrk` / `shrk --help`. Pruned
- * to the core tier set; extended verbs live one link away via
- * `shrk surface list`.
+ * Product start screen for bare `shrk` / `shrk --help`. Shows the
+ * curated ~20-command "starter" surface organized by workflow phase.
+ * Everything else stays callable; users see the full ~70-verb catalog
+ * via `shrk --full-help` or browse it through `shrk surface list`.
  *
  * Returns the lines (without trailing newline). Pulled into a function
  * so tests can assert on the structure without grepping stdout.

package/dist/commands/help.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAuB1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2FpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAiD1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EAyHpF"}

package/dist/commands/help.command.js

@@ -1,8 +1,10 @@
 import { header } from "../output/format-output.js";
+import { COMMAND_CATALOG, defaultShowInHelp } from "./command-catalog.js";
 /**
- * Short product start screen for bare `shrk` / `shrk --help`. Pruned
- * to the core tier set; extended verbs live one link away via
- * `shrk surface list`.
+ * Product start screen for bare `shrk` / `shrk --help`. Shows the
+ * curated ~20-command "starter" surface organized by workflow phase.
+ * Everything else stays callable; users see the full ~70-verb catalog
+ * via `shrk --full-help` or browse it through `shrk surface list`.
  *
  * Returns the lines (without trailing newline). Pulled into a function
  * so tests can assert on the structure without grepping stdout.
@@ -12,20 +14,46 @@ export function renderStartScreen() {
     lines.push('SharkCraft CLI — deterministic, local-first project intelligence for AI coding agents.');
     lines.push('Usage: shrk [--cwd <dir>] <command> [...args]');
     lines.push('');
-    lines.push('Core (always on):');
-    lines.push('  $ shrk recommend "<task>"        — what should I do?');
+    lines.push('Bootstrap:');
+    lines.push('  $ shrk init --infer --write      — scan the repo + populate sharkcraft/ from real signals (recommended for new repos)');
+    lines.push('  $ shrk import claude-md ./CLAUDE.md --populate --write  — populate sharkcraft/ from existing CLAUDE.md / AGENTS.md / .cursor/rules');
+    lines.push('  $ shrk init --with-claude-skill --write  — scaffold sharkcraft/ AND inline rules into .claude/skills/ (one-step)');
+    lines.push('  $ shrk init                      — scaffold sharkcraft/ + config skeleton (preset defaults)');
     lines.push('  $ shrk doctor                    — is the workspace healthy?');
-    lines.push('  $ shrk context --task "<task>"   — focused context for a task');
-    lines.push('  $ shrk init                      — create sharkcraft/ + config skeleton');
-    lines.push('  $ shrk check boundaries          — boundary enforcement');
-    lines.push('  $ shrk surface list              — every command grouped by tier');
+    lines.push('  $ shrk inspect                   — detect frameworks, paths, package manager');
+    lines.push('  $ shrk onboard                   — analyze an existing repo (advisory)');
+    lines.push('');
+    lines.push('Use it for a task:');
+    lines.push('  $ shrk brief                     — single-page brief Claude reads first (project + rules + paths + verification)');
+    lines.push('  $ shrk recommend "<task>"        — what should I do?');
+    lines.push('  $ shrk context --task "<task>"   — token-budgeted relevant context');
+    lines.push('  $ shrk task "<task>"             — full AI-ready task packet (JSON)');
+    lines.push('  $ shrk coverage                  — what knowledge is missing');
+    lines.push('');
+    lines.push('Generate code safely:');
+    lines.push('  $ shrk gen <template> <name>     — generate from template (dry-run by default)');
+    lines.push('  $ shrk apply <plan.json>         — apply a reviewed plan (CLI is the only write path)');
+    lines.push('  $ shrk check boundaries          — enforce layer / import boundaries');
+    lines.push('  $ shrk quality                   — pre-PR gate (doctor + boundaries + coverage + drift)');
+    lines.push('');
+    lines.push('Browse what shrk knows:');
+    lines.push('  $ shrk knowledge list            — knowledge entries');
+    lines.push('  $ shrk rules list                — rules + conventions');
+    lines.push('  $ shrk templates list            — generator templates');
+    lines.push('  $ shrk import                    — parse AGENTS.md / CLAUDE.md / .cursor/rules');
+    lines.push('  $ shrk export                    — render to a flat agent-rule file');
+    lines.push('');
+    lines.push('Run shrk for an agent:');
+    lines.push('  $ shrk export claude-skill --write — generate .claude/skills/<name>/SKILL.md (rules INTO the prompt — no MCP roundtrip)');
+    lines.push('  $ shrk export agents-md --write  — generate AGENTS.md / CLAUDE.md / .cursor/rules / copilot-instructions');
+    lines.push('  $ shrk mcp serve                 — start the MCP server (stdio) for live queries');
+    lines.push('  $ shrk dashboard                 — start the local read-only dashboard');
     lines.push('');
-    lines.push('Discover the rest (extended tier — always callable):');
-    lines.push('  $ shrk surface list              — full surface, grouped by tier and profile');
+    lines.push('Discover the rest (always callable, hidden from this screen by default):');
+    lines.push('  $ shrk surface list              — full ~70-verb catalog by tier');
     lines.push('  $ shrk surface profiles          — named profiles (small-app / monorepo / ci / agent / pack-author)');
-    lines.push('  $ shrk surface explain <cmd>     — why a command has its current tier');
     lines.push('  $ shrk help <command>            — usage for a specific command');
-    lines.push('  $ shrk --full-help               — the long, exhaustive help');
+    lines.push('  $ shrk --full-help               — long, exhaustive help');
     lines.push('  $ shrk --about                   — what shrk is and is not');
     lines.push('');
     lines.push('Free-form input is fine — `shrk "<task>"` routes to `shrk recommend`.');
@@ -89,13 +117,41 @@ export function makeHelpCommand(registry) {
                 process.stdout.write(renderStartScreen());
                 return 0;
             }
+            const wantsAll = args.flags.get('all') === true;
             process.stdout.write(`SharkCraft CLI — structured project intelligence for AI coding agents\n`);
             process.stdout.write(`Usage: shrk [--cwd <dir>] <command> [...args]\n`);
+            // The catalog has ~360 entries; only ~30 top-level verbs pay
+            // rent (see PRIMARY_VERBS_ALLOWLIST in command-catalog.ts).
+            // Default --full-help filters to that set; `--full-help --all`
+            // dumps the entire catalog for power users.
+            const visibleVerbs = new Set();
+            if (!wantsAll) {
+                for (const entry of COMMAND_CATALOG) {
+                    if (defaultShowInHelp(entry)) {
+                        const verb = entry.command.split(/\s+/)[0] ?? '';
+                        if (verb)
+                            visibleVerbs.add(verb);
+                    }
+                }
+            }
+            const visibleTopLevel = registry.list().filter((c) => {
+                if (wantsAll)
+                    return true;
+                return visibleVerbs.has(c.name);
+            });
             process.stdout.write(header('Top-level commands'));
-            for (const c of registry.list()) {
+            for (const c of visibleTopLevel) {
                 process.stdout.write(`  ${c.name.padEnd(10)} — ${c.description}\n`);
             }
-            // Show each canonical group once.
+            if (!wantsAll) {
+                const hiddenCount = registry.list().length - visibleTopLevel.length;
+                if (hiddenCount > 0) {
+                    process.stdout.write(`\n  …and ${hiddenCount} more, hidden from default help. Run \`shrk --full-help --all\` to see them, ` +
+                        `or \`shrk surface list\` to browse by tier.\n`);
+                }
+            }
+            // Show each canonical group once — also filtered by the allowlist
+            // unless --all was passed.
             const canonicalGroups = [];
             const aliasMap = registry.listGroupAliases();
             const seen = new Set();
@@ -103,7 +159,9 @@ export function makeHelpCommand(registry) {
                 const canonical = aliasMap.get(g) ?? g;
                 if (!seen.has(canonical)) {
                     seen.add(canonical);
-                    canonicalGroups.push(canonical);
+                    if (wantsAll || visibleVerbs.has(canonical)) {
+                        canonicalGroups.push(canonical);
+                    }
                 }
             }
             const aliasesByCanonical = new Map();

package/dist/commands/helper.command.js

@@ -85,7 +85,7 @@ export const helperPlanCommand = {
         // profile is available. Today the helper-registry detects this inside
         // buildHelperPlan via requireProfile(); we surface a friendly message.
         if ('requiresProfile' in def && def.requiresProfile) {
-            process.stderr.write(`Helper "${id}" requires a plugin-lifecycle profile. Available:\n  $ shrk plugin lifecycle profiles\n`);
+            process.stderr.write(`Helper "${id}" requires a registered profile. Available:\n  $ shrk profiles list\n`);
             // Still try to build the plan; the registry throws with the same idea.
         }
         const cwd = resolveCwd(args);

package/dist/commands/import.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.command.d.ts","sourceRoot":"","sources":["../../src/commands/import.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyBhC,eAAO,MAAM,aAAa,EAAE,eA8G3B,CAAC"}
+{"version":3,"file":"import.command.d.ts","sourceRoot":"","sources":["../../src/commands/import.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyBhC,eAAO,MAAM,aAAa,EAAE,eA8H3B,CAAC"}

package/dist/commands/import.command.js

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { emitKnowledgeTs, importAgentsMd, importClaudeMd, importCursorRules, } from '@shrkcrft/importer';
+import { emitKnowledgeTs, importAgentsMd, importClaudeMd, importCursorRules, synthesizePopulatedFromImport, } from '@shrkcrft/importer';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
-import { asJson, header, kv } from "../output/format-output.js";
+import { asJson, bullet, header, kv } from "../output/format-output.js";
 function repeatedFlagList(args, name) {
     return flagList(args, name, { dedupe: true });
 }
@@ -22,8 +22,8 @@ function defaultOutput(format) {
 }
 export const importCommand = {
     name: 'import',
-    description: 'Parse existing agent rule files (AGENTS.md / CLAUDE.md / .cursor/rules) into a structured @shrkcrft/knowledge TypeScript draft. Dry-run by default; --write saves the draft to sharkcraft/imports/.',
-    usage: 'shrk [--cwd <dir>] import <format> [<path>] [--prefix <id>] [--tag <t>] [--scope <s>] [--output <file>] [--write] [--force] [--json]',
+    description: 'Parse existing agent rule files (AGENTS.md / CLAUDE.md / .cursor/rules) into shrk\'s structure. By default (`--write`), saves a single draft TS file under sharkcraft/imports/ for the user to adopt by hand. Pass `--populate` to route entries directly into sharkcraft/rules.ts + paths.ts + knowledge.ts (by type) with a confidence triage report — same shape as `shrk init --infer`. Both modes dry-run by default.',
+    usage: 'shrk [--cwd <dir>] import <format> [<path>] [--prefix <id>] [--tag <t>] [--scope <s>] [--output <file>] [--write] [--populate] [--force] [--json]',
     async run(args) {
         const format = args.positional[0];
         if (!format || !KNOWN_FORMATS.includes(format)) {
@@ -57,9 +57,24 @@ export const importCommand = {
         }
         const outPath = nodePath.resolve(cwd, flagString(args, 'output') ?? flagString(args, 'out') ?? defaultOutput(fmt));
         const write = flagBool(args, 'write');
+        const populate = flagBool(args, 'populate');
         const tsSource = emitKnowledgeTs(result.entries, {
             sourceLabel: `${fmt} (${result.sourceFiles.join(', ') || path})`,
         });
+        // ── `--populate` path: distribute entries into populated
+        //    sharkcraft/* files (rules.ts / paths.ts / knowledge.ts) with
+        //    confidence triage. Mirrors `shrk init --infer`'s contract.
+        if (populate) {
+            return runPopulateImport({
+                cwd,
+                fmt,
+                path,
+                result,
+                write,
+                force: flagBool(args, 'force'),
+                wantJson: flagBool(args, 'json'),
+            });
+        }
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 format: fmt,
@@ -113,3 +128,104 @@ export const importCommand = {
         return 0;
     },
 };
+/**
+ * `shrk import <format> --populate` path. Routes parsed entries
+ * into populated `sharkcraft/*.ts` files by KnowledgeType, with
+ * confidence triage and a companion `.imported-report.md`. Same
+ * shape as `shrk init --infer`.
+ */
+function runPopulateImport(args) {
+    const { cwd, fmt, path, result, write, force, wantJson } = args;
+    const sharkcraftDir = nodePath.join(cwd, 'sharkcraft');
+    const projectName = readProjectName(cwd) ?? 'project';
+    const description = `Imported from ${fmt} (${path})`;
+    const populated = synthesizePopulatedFromImport(result.entries, {
+        projectName,
+        description,
+        sourceLabel: `${fmt} (${result.sourceFiles.join(', ') || path})`,
+    });
+    if (wantJson) {
+        process.stdout.write(asJson({
+            format: fmt,
+            source: path,
+            mode: write ? 'populate' : 'populate-dry-run',
+            sharkcraftDir,
+            entryCount: result.entries.length,
+            warnings: result.warnings,
+            files: populated.files.map((f) => ({ path: f.path, kind: f.kind })),
+            report: populated.report,
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Import (${fmt}) — populate`));
+    process.stdout.write(kv('source', path) + '\n');
+    process.stdout.write(kv('files read', String(result.sourceFiles.length)) + '\n');
+    process.stdout.write(kv('entries parsed', String(result.entries.length)) + '\n');
+    process.stdout.write(kv('target', sharkcraftDir) + '\n');
+    process.stdout.write(kv('mode', write ? 'write' : 'dry-run (preview only)') + '\n\n');
+    process.stdout.write(`Triage: ${populated.report.adoptedHigh.length} adopted directly · ` +
+        `${populated.report.adoptedMedium.length} marked for review · ` +
+        `${populated.report.dropped.length} dropped (in report).\n\n`);
+    if (result.warnings.length > 0) {
+        process.stdout.write(header('Parser warnings'));
+        for (const w of result.warnings) {
+            process.stdout.write(`  ${w.origin}: ${w.message}\n`);
+        }
+        process.stdout.write('\n');
+    }
+    if (!write) {
+        process.stdout.write('Would write:\n');
+        for (const f of populated.files)
+            process.stdout.write(bullet(f.path) + '\n');
+        process.stdout.write('\nRe-run with --write to persist.\n');
+        return 0;
+    }
+    const written = [];
+    const skipped = [];
+    for (const file of populated.files) {
+        const fullPath = nodePath.join(sharkcraftDir, file.path);
+        mkdirSync(nodePath.dirname(fullPath), { recursive: true });
+        if (existsSync(fullPath) && !force) {
+            skipped.push(file.path);
+            continue;
+        }
+        writeFileSync(fullPath, file.content, 'utf8');
+        written.push(file.path);
+    }
+    if (written.length) {
+        process.stdout.write('Wrote:\n');
+        for (const p of written)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    if (skipped.length) {
+        process.stdout.write('\nSkipped (already exist; use --force to overwrite):\n');
+        for (const p of skipped)
+            process.stdout.write(bullet(p) + '\n');
+    }
+    process.stdout.write(`\nRead the import report: \`${nodePath.join('sharkcraft', '.imported-report.md')}\`\n` +
+        `It lists what was adopted high-confidence, what's marked for your review, ` +
+        `and what \`shrk import\` deliberately doesn't recover from markdown.\n`);
+    process.stdout.write('\nNext:\n');
+    process.stdout.write(bullet('$ shrk doctor                            — verify the populated setup') + '\n');
+    process.stdout.write(bullet('$ shrk brief                             — single-page brief Claude reads first') + '\n');
+    process.stdout.write(bullet('$ shrk export claude-skill --write       — inline the rules into Claude\'s prompt') + '\n');
+    return 0;
+}
+/**
+ * Best-effort read of `package.json#name` for use as `projectName`
+ * in the generated config. Falls back to undefined; the synthesizer
+ * uses 'project' as a default.
+ */
+function readProjectName(cwd) {
+    const pkgPath = nodePath.join(cwd, 'package.json');
+    try {
+        if (!existsSync(pkgPath))
+            return undefined;
+        const raw = readFileSync(pkgPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed.name ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/commands/init.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.command.d.ts","sourceRoot":"","sources":["../../src/commands/init.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAwB,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAmSjH,eAAO,MAAM,WAAW,EAAE,eA2FzB,CAAC"}
+{"version":3,"file":"init.command.d.ts","sourceRoot":"","sources":["../../src/commands/init.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAwB,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAuSjH,eAAO,MAAM,WAAW,EAAE,eA2HzB,CAAC"}