@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/export/export-formats.js

@@ -1,11 +1,28 @@
 import { aggregateActionHints, KnowledgeType } from '@shrkcrft/knowledge';
 import { priorityWeight } from '@shrkcrft/knowledge';
-const DEFAULT_OUTPUT_PATH = {
-    'agents-md': 'AGENTS.md',
-    'claude-md': 'CLAUDE.md',
-    'cursor-rules': '.cursor/rules/sharkcraft.mdc',
-    'copilot-instructions': '.github/copilot-instructions.md',
-};
+function projectSlug(name) {
+    if (!name)
+        return 'project';
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || 'project');
+}
+function defaultOutputFor(format, inspection) {
+    switch (format) {
+        case 'agents-md':
+            return 'AGENTS.md';
+        case 'claude-md':
+            return 'CLAUDE.md';
+        case 'claude-skill':
+            return `.claude/skills/${projectSlug(inspection.config?.projectName)}/SKILL.md`;
+        case 'cursor-rules':
+            return '.cursor/rules/sharkcraft.mdc';
+        case 'copilot-instructions':
+            return '.github/copilot-instructions.md';
+    }
+}
 function selectTopByPriority(entries, limit) {
     return [...entries]
         .sort((a, b) => priorityWeight(b.priority) - priorityWeight(a.priority))
@@ -100,23 +117,131 @@ function renderBody(inspection, options) {
     }
     return sections.join('\n\n');
 }
+/**
+ * Filter rules / paths to the high-signal subset for an inlined skill.
+ *
+ * Every rule the skill carries pays in Claude's context every time the
+ * skill is loaded. Low-priority items dilute the signal of the
+ * load-bearing ones (`Critical` safety + `High` architecture). We keep
+ * only Critical + High by default, falling back to "all" only if the
+ * filtered list is empty (e.g. a repo with no high-priority entries
+ * yet shouldn't ship an empty skill).
+ */
+function filterHighSignal(entries) {
+    const filtered = entries.filter((e) => {
+        const p = String(e.priority).toLowerCase();
+        return p === 'critical' || p === 'high';
+    });
+    return filtered.length > 0 ? filtered : [...entries];
+}
+/**
+ * Render the body in tight, decision-driving form for the Claude Code
+ * Skill format. Skills get loaded into Claude's prompt when the skill's
+ * `description` matches the current task, so the body must be short and
+ * directly actionable — no preamble, no metadata about generation, no
+ * pipelines (Claude can run `shrk task` for those when needed).
+ *
+ * Sections:
+ *   1. Where files belong (path conventions, top N) — most-leveraged signal.
+ *   2. Rules to follow (Critical + High only) — pads context otherwise.
+ *   3. Do / Don't — forbidden actions and verification commands.
+ *   4. How to write code in this repo — the gen → review → apply loop
+ *      verbatim, since Claude needs to know shrk is the write path.
+ */
+function renderSkillBody(inspection, options) {
+    const { rules: allRules, paths: allPaths } = gatherRulesAndPaths(inspection, {
+        ...options,
+        // Pull more upfront, then filter down to high-signal — keeps the
+        // softcap-at-15 default but the inlined skill stays terse.
+        maxRules: options.maxRules ?? 24,
+        maxPaths: options.maxPaths ?? 18,
+    });
+    // Skills are inlined into the prompt — every entry costs Claude
+    // context. Only ship the items the user said are load-bearing.
+    const rules = filterHighSignal(allRules).slice(0, options.maxRules ?? 12);
+    const paths = filterHighSignal(allPaths).slice(0, options.maxPaths ?? 10);
+    const sections = [];
+    if (inspection.config?.description) {
+        sections.push(`## About this codebase\n\n${inspection.config.description}`);
+    }
+    const pathsBody = renderPathsSection(paths);
+    if (pathsBody) {
+        sections.push(`## Where files belong\n\nWhen creating or moving a file, place it according to these conventions:\n\n${pathsBody}`);
+    }
+    const rulesBody = renderRulesSection(rules);
+    if (rulesBody) {
+        sections.push(`## Rules this codebase follows\n\nApply these whenever you generate, modify, or review code:\n\n${rulesBody}`);
+    }
+    const agg = aggregateActionHints(inspection.knowledgeEntries);
+    const doDont = [];
+    if (agg.forbiddenActions.length) {
+        doDont.push('**Do not:**');
+        for (const f of agg.forbiddenActions.slice(0, 8))
+            doDont.push(`- ${f}`);
+        doDont.push('');
+    }
+    if (agg.verificationCommands.length) {
+        doDont.push('**Verify changes with:**');
+        for (const c of agg.verificationCommands.slice(0, 6))
+            doDont.push(`- \`${c}\``);
+    }
+    if (doDont.length) {
+        sections.push(`## Do / Don't\n\n${doDont.join('\n').trim()}`);
+    }
+    sections.push(`## How to write code in this repo\n\n` +
+        `This repository uses [SharkCraft](https://github.com/shrkcrft/sharkcraft) to gate writes — the CLI is the only write path, and writes go through a plan → review → apply loop.\n\n` +
+        `1. **Get a task packet** before non-trivial work: \`shrk task "<one-sentence task>"\` returns the focused rules, paths, templates, and verification commands for that task.\n` +
+        `2. **Scaffold via templates** instead of writing files freehand: \`shrk gen <template-id> <name> --dry-run --save-plan plan.json\` produces a signed plan.\n` +
+        `3. **Apply the plan** through the CLI: \`shrk apply plan.json --verify-signature\` — never write through MCP.\n` +
+        `4. **Check the result**: \`shrk check boundaries\` + the verification commands listed above.\n\n` +
+        `For ad-hoc questions about the codebase, query the MCP server (\`shrk mcp serve\`) or run \`shrk context --task "<query>"\` for token-budgeted context.`);
+    return sections.join('\n\n');
+}
+/**
+ * Build the YAML frontmatter for a Claude Code Skill. The `description`
+ * field is what Claude uses to decide whether to load this skill — keep
+ * it specific (project name + what's covered) so it doesn't trigger on
+ * unrelated tasks.
+ */
+function renderSkillFrontmatter(inspection) {
+    const slug = projectSlug(inspection.config?.projectName);
+    const projectName = inspection.config?.projectName ?? slug;
+    const description = `Codebase rules, path conventions, and review gates for ${projectName}. ` +
+        `Use this skill whenever generating, modifying, or reviewing code in this repository — ` +
+        `it tells you the per-file path conventions, the architecture boundaries, the verification commands, ` +
+        `and the safe write path (CLI plan → review → apply).`;
+    return `---\nname: ${slug}\ndescription: ${JSON.stringify(description)}\n---`;
+}
 export function renderExport(inspection, options) {
-    const body = renderBody(inspection, options);
-    const suggestedPath = DEFAULT_OUTPUT_PATH[options.format];
+    const suggestedPath = defaultOutputFor(options.format, inspection);
     let content = '';
     switch (options.format) {
-        case 'agents-md':
+        case 'agents-md': {
+            const body = renderBody(inspection, options);
             content = `# Agents Guide\n\n${PREAMBLE}\n\n${body}\n`;
             break;
-        case 'claude-md':
+        }
+        case 'claude-md': {
+            const body = renderBody(inspection, options);
             content = `# CLAUDE.md\n\n${PREAMBLE}\n\nThis file is read by Claude Code (claude.ai/code) at session start. Treat it as a compatibility view of the project's SharkCraft knowledge — use the MCP server (\`shrk mcp serve\`) for the live, queryable source of truth.\n\n${body}\n`;
             break;
+        }
+        case 'claude-skill': {
+            // Claude Code Skill: YAML frontmatter declares when to load this,
+            // body is tight decision-driving content. No preamble, no boilerplate
+            // — every token in here costs Claude context when loaded.
+            const frontmatter = renderSkillFrontmatter(inspection);
+            const projectName = inspection.config?.projectName ?? 'this codebase';
+            const body = renderSkillBody(inspection, options);
+            content = `${frontmatter}\n\n# ${projectName} — codebase guide\n\n${body}\n`;
+            break;
+        }
         case 'cursor-rules':
             // Cursor MDC frontmatter: leave alwaysApply off so the user can tune.
-            content = `---\ndescription: SharkCraft project rules (auto-generated)\nalwaysApply: false\n---\n\n${PREAMBLE}\n\n${body}\n`;
+            content = `---\ndescription: SharkCraft project rules (auto-generated)\nalwaysApply: false\n---\n\n${PREAMBLE}\n\n${renderBody(inspection, options)}\n`;
             break;
         case 'copilot-instructions':
-            content = `# Copilot instructions\n\n${PREAMBLE}\n\n${body}\n`;
+            content = `# Copilot instructions\n\n${PREAMBLE}\n\n${renderBody(inspection, options)}\n`;
             break;
     }
     return { format: options.format, suggestedPath, content };
@@ -124,12 +249,14 @@ export function renderExport(inspection, options) {
 export function isExportFormat(value) {
     return (value === 'agents-md' ||
         value === 'claude-md' ||
+        value === 'claude-skill' ||
         value === 'cursor-rules' ||
         value === 'copilot-instructions');
 }
 export const ALL_EXPORT_FORMATS = Object.freeze([
     'agents-md',
     'claude-md',
+    'claude-skill',
     'cursor-rules',
     'copilot-instructions',
 ]);

package/dist/index.d.ts

@@ -17,6 +17,9 @@ export { packsListCommand, packsGetCommand, packsInspectCommand, packsDoctorComm
 export { pipelinesListCommand, pipelinesGetCommand, pipelinesContextCommand, pipelinesPlanCommand, pipelinesScriptCommand, pipelinesNextCommand, } from './commands/pipelines.command.js';
 export { schemasListCommand, schemasGetCommand, schemasWriteCommand, } from './commands/schemas.command.js';
 export { versionCommand } from './commands/version.command.js';
+export { compressCommand, expandCommand } from './commands/compress.command.js';
+export { alignCommand, unalignCommand } from './commands/cache-align.command.js';
 export { makeHelpCommand } from './commands/help.command.js';
 export { buildRegistry, runCli } from './main.js';
+export { buildWatchPlan, maybeRunInWatchMode, runWatchLoop, } from './output/watch-loop.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -17,5 +17,8 @@ export { packsListCommand, packsGetCommand, packsInspectCommand, packsDoctorComm
 export { pipelinesListCommand, pipelinesGetCommand, pipelinesContextCommand, pipelinesPlanCommand, pipelinesScriptCommand, pipelinesNextCommand, } from "./commands/pipelines.command.js";
 export { schemasListCommand, schemasGetCommand, schemasWriteCommand, } from "./commands/schemas.command.js";
 export { versionCommand } from "./commands/version.command.js";
+export { compressCommand, expandCommand } from "./commands/compress.command.js";
+export { alignCommand, unalignCommand } from "./commands/cache-align.command.js";
 export { makeHelpCommand } from "./commands/help.command.js";
 export { buildRegistry, runCli } from "./main.js";
+export { buildWatchPlan, maybeRunInWatchMode, runWatchLoop, } from "./output/watch-loop.js";

package/dist/init/init-templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-templates.d.ts","sourceRoot":"","sources":["../../src/init/init-templates.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EA4Z1C,CAAC"}
+{"version":3,"file":"init-templates.d.ts","sourceRoot":"","sources":["../../src/init/init-templates.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EA2W1C,CAAC"}

package/dist/init/init-templates.js

@@ -1,9 +1,18 @@
+// Self-contained scaffolding for `shrk init --legacy`. Every generated
+// `sharkcraft/*.ts` file must work in a brand-new downstream repo where
+// no `@shrkcrft/*` packages are installed beyond the CLI itself. The
+// loaders (knowledge / templates / pipelines / path-conventions) are
+// shape-agnostic — they accept any object with the required string
+// fields — so each emitted file declares its own minimal helpers +
+// enum-like constants inline.
 export const INIT_FILES = [
     {
         relativePath: 'sharkcraft.config.ts',
-        content: `import { defineSharkCraftConfig } from '@shrkcrft/config';
+        content: `// Generated by \`shrk init --legacy\`. Plain default export — no
+// @shrkcrft/* import required. The config loader validates this object
+// by shape (zod), so the literal works without a helper call.
 
-export default defineSharkCraftConfig({
+export default {
   projectName: 'my-project',
   description: 'A SharkCraft-powered repository.',
   knowledgeFiles: ['knowledge.ts'],
@@ -13,12 +22,36 @@ export default defineSharkCraftConfig({
   docsFiles: ['docs/overview.md', 'docs/architecture.md', 'docs/quick-start.md'],
   defaultMaxTokens: 4000,
   defaultScope: ['typescript'],
-});
+};
 `,
     },
     {
         relativePath: 'knowledge.ts',
-        content: `import { defineKnowledgeEntry, KnowledgeType, KnowledgePriority } from '@shrkcrft/knowledge';
+        content: `// Local helpers — keep this file self-contained (no @shrkcrft/* imports).
+// The knowledge loader is shape-agnostic; it accepts any object whose
+// \`id\`, \`title\`, and \`content\` are strings.
+
+const KnowledgePriority = {
+  Critical: 'critical',
+  High: 'high',
+  Medium: 'medium',
+  Low: 'low',
+} as const;
+
+const KnowledgeType = {
+  Rule: 'rule',
+  Path: 'path',
+  Template: 'template',
+  Architecture: 'architecture',
+  Technical: 'technical',
+  Convention: 'convention',
+  Workflow: 'workflow',
+  Warning: 'warning',
+} as const;
+
+function defineKnowledgeEntry<T>(entry: T): T {
+  return entry;
+}
 
 export const projectOverview = defineKnowledgeEntry({
   id: 'project.overview',
@@ -67,8 +100,20 @@ export default [projectOverview, aiAgentBriefing, generationSafety];
     },
     {
         relativePath: 'rules.ts',
-        content: `import { defineRule } from '@shrkcrft/rules';
-import { KnowledgePriority } from '@shrkcrft/knowledge';
+        content: `// Local helpers — keep this file self-contained (no @shrkcrft/* imports).
+
+const KnowledgePriority = {
+  Critical: 'critical',
+  High: 'high',
+  Medium: 'medium',
+  Low: 'low',
+} as const;
+
+const KnowledgeType = { Rule: 'rule' } as const;
+
+function defineRule<T>(rule: T): T {
+  return { ...rule, type: KnowledgeType.Rule } as T;
+}
 
 export const tsNamingClasses = defineRule({
   id: 'typescript.naming.classes',
@@ -142,81 +187,15 @@ export default [
     },
     {
         relativePath: 'paths.ts',
-        content: `import { definePathConvention } from '@shrkcrft/paths';
-import { KnowledgePriority } from '@shrkcrft/knowledge';
-
-export const appSrc = definePathConvention({
-  id: 'app.src',
-  title: 'Application source root',
-  path: 'src',
-  description: 'All application source lives here.',
-  priority: KnowledgePriority.Critical,
-  scope: ['typescript'],
-  tags: ['source-path', 'root'],
-  appliesWhen: ['generate-code'],
-});
-
-export const services = definePathConvention({
-  id: 'app.services',
-  title: 'Application services',
-  path: 'src/services',
-  description: 'Application services live here.',
-  priority: KnowledgePriority.High,
-  scope: ['typescript', 'backend'],
-  tags: ['service', 'source-path'],
-  appliesWhen: ['generate-service', 'create-business-logic'],
-});
-
-export const utils = definePathConvention({
-  id: 'app.utils',
-  title: 'Utilities',
-  path: 'src/utils',
-  description: 'Pure functions, no side effects.',
-  priority: KnowledgePriority.Medium,
-  scope: ['typescript'],
-  tags: ['util', 'source-path'],
-  appliesWhen: ['generate-utility'],
-});
-
-export const features = definePathConvention({
-  id: 'app.features',
-  title: 'Feature folders',
-  path: 'src/features',
-  description: 'Vertical feature slices. Use this for end-to-end features.',
-  priority: KnowledgePriority.Medium,
-  scope: ['typescript'],
-  tags: ['feature', 'source-path'],
-  appliesWhen: ['generate-feature'],
-});
-
-export const tests = definePathConvention({
-  id: 'app.tests',
-  title: 'Test files',
-  path: 'tests',
-  description: 'Test files (or co-located *.spec.ts next to the unit under test).',
-  priority: KnowledgePriority.Medium,
-  scope: ['typescript', 'testing'],
-  tags: ['test', 'source-path'],
-  appliesWhen: ['generate-test'],
-});
-
-export const docs = definePathConvention({
-  id: 'app.docs',
-  title: 'Documentation',
-  path: 'docs',
-  description: 'Long-form human-readable docs (optional).',
-  priority: KnowledgePriority.Low,
-  scope: ['typescript'],
-  tags: ['docs'],
-  appliesWhen: ['add-docs'],
-});
-
-export default [appSrc, services, utils, features, tests, docs];
-`,
+        content: PATHS_PLACEHOLDER_CONTENT(),
     },
     {
         relativePath: 'templates.ts',
-        content: `import { defineTemplate } from '@shrkcrft/templates';
+        content: `// Local helpers — keep this file self-contained (no @shrkcrft/* imports).
+
+function defineTemplate<T>(template: T): T {
+  return template;
+}
 
 export const tsService = defineTemplate({
   id: 'typescript.service',
@@ -229,8 +208,8 @@ export const tsService = defineTemplate({
     { name: 'name', required: true, description: 'kebab-case file name (e.g. user-profile)' },
     { name: 'className', required: true, description: 'PascalCase class name (e.g. UserProfileService)' },
   ],
-  targetPath: ({ name }) => \`src/services/\${name}.service.ts\`,
-  content: ({ className }) => \`export class \${className} {
+  targetPath: ({ name }: { name: string }) => \`src/services/\${name}.service.ts\`,
+  content: ({ className }: { className: string }) => \`export class \${className} {
   constructor() {}
 
   init(): void {
@@ -253,42 +232,14 @@ export const tsUtility = defineTemplate({
     { name: 'name', required: true, description: 'kebab-case file name' },
     { name: 'camel', required: true, description: 'camelCase function name' },
   ],
-  targetPath: ({ name }) => \`src/utils/\${name}.ts\`,
-  content: ({ camel }) => \`export function \${camel}(input: unknown): unknown {
+  targetPath: ({ name }: { name: string }) => \`src/utils/\${name}.ts\`,
+  content: ({ camel }: { camel: string }) => \`export function \${camel}(input: unknown): unknown {
   return input;
 }
 \`,
   postGenerationNotes: ['Keep utilities pure. No side effects, no shared mutable state.'],
 });
 
-export const tsFeatureFolder = defineTemplate({
-  id: 'typescript.feature',
-  name: 'TypeScript Feature folder',
-  description: 'Creates a vertical feature slice (index + service + types).',
-  tags: ['typescript', 'feature'],
-  scope: ['typescript'],
-  appliesWhen: ['generate-feature'],
-  variables: [
-    { name: 'name', required: true },
-    { name: 'pascal', required: true },
-  ],
-  files: ({ name, pascal }) => [
-    {
-      targetPath: \`src/features/\${name}/index.ts\`,
-      content: \`export * from './\${name}.service.ts';\nexport * from './\${name}.types.ts';\n\`,
-    },
-    {
-      targetPath: \`src/features/\${name}/\${name}.service.ts\`,
-      content: \`import type { I\${pascal}Config } from './\${name}.types.ts';\n\nexport class \${pascal}Service {\n  constructor(private readonly config: I\${pascal}Config) {}\n}\n\`,
-    },
-    {
-      targetPath: \`src/features/\${name}/\${name}.types.ts\`,
-      content: \`export interface I\${pascal}Config {\n  enabled: boolean;\n}\n\`,
-    },
-  ],
-  postGenerationNotes: ['Add tests under tests/<feature> or co-located *.spec.ts.'],
-});
-
 export const tsTest = defineTemplate({
   id: 'typescript.test',
   name: 'TypeScript Test File',
@@ -300,11 +251,18 @@ export const tsTest = defineTemplate({
     { name: 'name', required: true },
     { name: 'pascal', required: true },
   ],
-  targetPath: ({ name }) => \`tests/\${name}.spec.ts\`,
-  content: ({ pascal }) => \`import { describe, expect, test } from 'bun:test';\n\ndescribe('\${pascal}', () => {\n  test('placeholder', () => {\n    expect(true).toBe(true);\n  });\n});\n\`,
+  targetPath: ({ name }: { name: string }) => \`tests/\${name}.spec.ts\`,
+  content: ({ pascal }: { pascal: string }) => \`import { describe, expect, test } from 'bun:test';
+
+describe('\${pascal}', () => {
+  test('placeholder', () => {
+    expect(true).toBe(true);
+  });
+});
+\`,
 });
 
-export default [tsService, tsUtility, tsFeatureFolder, tsTest];
+export default [tsService, tsUtility, tsTest];
 `,
     },
     {
@@ -411,3 +369,65 @@ Lower-priority work for SharkCraft-powered knowledge in this repo.
 `,
     },
 ];
+function PATHS_PLACEHOLDER_CONTENT() {
+    // The legacy seed ships generic path examples. The modern preset path
+    // (`shrk init --preset <id>`) is workspace-aware. To avoid emitting
+    // broken defaults like `src/services/` in repos that don't have them,
+    // the legacy seed now ships *commented* examples plus an `// TODO:`
+    // marker the human is expected to fill in. The runner-instructions in
+    // docs/onboarding.md describe how to derive paths from the live repo.
+    return `// Local helpers — keep this file self-contained (no @shrkcrft/* imports).
+
+const KnowledgePriority = {
+  Critical: 'critical',
+  High: 'high',
+  Medium: 'medium',
+  Low: 'low',
+} as const;
+
+const KnowledgeType = { Path: 'path' } as const;
+
+function definePathConvention<T>(convention: T): T {
+  return { ...convention, type: KnowledgeType.Path } as T;
+}
+
+// TODO: replace the examples below with real path conventions for this
+// repository. Run \`shrk onboard --dry-run\` to see what the inference
+// engine detects from the workspace.
+
+export const appSrc = definePathConvention({
+  id: 'app.src',
+  title: 'Application source root',
+  path: 'src',
+  description: 'All application source lives here. Adjust to match this repo.',
+  priority: KnowledgePriority.Critical,
+  scope: ['typescript'],
+  tags: ['source-path', 'root'],
+  appliesWhen: ['generate-code'],
+});
+
+export const tests = definePathConvention({
+  id: 'app.tests',
+  title: 'Test files',
+  path: 'tests',
+  description: 'Test files. Many repos co-locate \`*.spec.ts\` next to the unit under test instead — pick one.',
+  priority: KnowledgePriority.Medium,
+  scope: ['typescript', 'testing'],
+  tags: ['test', 'source-path'],
+  appliesWhen: ['generate-test'],
+});
+
+export const docs = definePathConvention({
+  id: 'app.docs',
+  title: 'Documentation',
+  path: 'docs',
+  description: 'Long-form human-readable docs (optional).',
+  priority: KnowledgePriority.Low,
+  scope: ['typescript'],
+  tags: ['docs'],
+  appliesWhen: ['add-docs'],
+});
+
+export default [appSrc, tests, docs];
+`;
+}

package/dist/init/paths-advisory.d.ts

@@ -0,0 +1,20 @@
+export interface IPathsAdvisory {
+    missingPaths: readonly string[];
+    existingPaths: readonly string[];
+    /** True when an advisory comment was prepended to the file. */
+    annotated: boolean;
+    pathsFile: string;
+}
+/**
+ * Scan the generated `sharkcraft/paths.ts` for `path: '<x>'` references
+ * and check each `<x>` against the live workspace. When any path is
+ * missing, prepend a clearly-labeled comment block listing the missing
+ * paths so the user knows which defaults to adjust.
+ *
+ * Idempotent — if the file already starts with the advisory marker,
+ * it is left untouched. Non-destructive — never edits, comments, or
+ * removes the original entries. The user is expected to revise them
+ * based on the advisory + `shrk onboard --dry-run` output.
+ */
+export declare function annotatePathsAgainstDisk(cwd: string, sharkcraftDir: string): IPathsAdvisory;
+//# sourceMappingURL=paths-advisory.d.ts.map

package/dist/init/paths-advisory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths-advisory.d.ts","sourceRoot":"","sources":["../../src/init/paths-advisory.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GACpB,cAAc,CAwChB"}

package/dist/init/paths-advisory.js

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const ADVISORY_MARKER = '// ⚠️ Workspace-shape advisory (added by `shrk init`):';
+/**
+ * Scan the generated `sharkcraft/paths.ts` for `path: '<x>'` references
+ * and check each `<x>` against the live workspace. When any path is
+ * missing, prepend a clearly-labeled comment block listing the missing
+ * paths so the user knows which defaults to adjust.
+ *
+ * Idempotent — if the file already starts with the advisory marker,
+ * it is left untouched. Non-destructive — never edits, comments, or
+ * removes the original entries. The user is expected to revise them
+ * based on the advisory + `shrk onboard --dry-run` output.
+ */
+export function annotatePathsAgainstDisk(cwd, sharkcraftDir) {
+    const pathsFile = nodePath.join(sharkcraftDir, 'paths.ts');
+    if (!existsSync(pathsFile)) {
+        return { missingPaths: [], existingPaths: [], annotated: false, pathsFile };
+    }
+    const original = readFileSync(pathsFile, 'utf8');
+    if (original.startsWith(ADVISORY_MARKER)) {
+        // Already annotated. Re-derive sets for caller diagnostics.
+        return classifyOnly(cwd, pathsFile, original);
+    }
+    const { existing, missing } = classifyPathReferences(cwd, original);
+    if (missing.length === 0) {
+        return {
+            missingPaths: [],
+            existingPaths: existing,
+            annotated: false,
+            pathsFile,
+        };
+    }
+    const lines = [
+        ADVISORY_MARKER,
+        '//',
+        '// The following paths referenced below do NOT exist in this repository:',
+        ...missing.map((p) => `//   - ${p}`),
+        '//',
+        '// They are conservative defaults from the chosen preset. Adjust them to',
+        '// match your actual layout. Run `shrk onboard --dry-run` to see what',
+        '// the inference engine detects from your workspace.',
+        '//',
+        '',
+    ];
+    writeFileSync(pathsFile, lines.join('\n') + original, 'utf8');
+    return {
+        missingPaths: missing,
+        existingPaths: existing,
+        annotated: true,
+        pathsFile,
+    };
+}
+function classifyOnly(cwd, pathsFile, original) {
+    const { existing, missing } = classifyPathReferences(cwd, original);
+    return {
+        missingPaths: missing,
+        existingPaths: existing,
+        annotated: false,
+        pathsFile,
+    };
+}
+function classifyPathReferences(cwd, source) {
+    // Match `path: '<x>'` / `path: "<x>"`. Ignore obvious code-context
+    // references (e.g. inside template literals); we only consume the
+    // first plain-string occurrence per entry.
+    const re = /\bpath\s*:\s*['"]([^'"\n]+)['"]/g;
+    const seen = new Set();
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        if (m[1])
+            seen.add(m[1]);
+    }
+    const existing = [];
+    const missing = [];
+    for (const p of [...seen].sort()) {
+        if (isReachable(cwd, p))
+            existing.push(p);
+        else
+            missing.push(p);
+    }
+    return { existing, missing };
+}
+function isReachable(cwd, p) {
+    // Absolute or rooted-relative — resolve as-is.
+    const full = nodePath.isAbsolute(p) ? p : nodePath.resolve(cwd, p);
+    return existsSync(full);
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EACL,eAAe,EAIhB,MAAM,uBAAuB,CAAC;AAyV/B,wBAAgB,aAAa,IAAI,eAAe,CA2V/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AA6FD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAwX/B,wBAAgB,aAAa,IAAI,eAAe,CA4X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAsHD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}