@crouton-kit/crouter 0.3.21 → 0.3.23

package/dist/commands/memory/lint.js

@@ -1,20 +1,17 @@
 // `crtr memory lint` — the permanent valid-YAML gate over the bounded corpus
 // (the CTO green-checkpoint: zero frontmatter parse errors at authoring time,
 // so an invalid doc fails HERE instead of being silently isolated at runtime).
-// Bounded corpus = the substrate memory dirs (project/user/builtin) +
-// every installed plugin's skills tree + ~/.claude/skills. Never a
+// Bounded corpus = the substrate memory dirs (project/user/builtin). Never a
 // filesystem-wide scan.
-import { homedir } from 'node:os';
-import { basename, join, relative, sep } from 'node:path';
+import { basename, relative, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { general } from '../../core/errors.js';
 import { warn } from '../../core/output.js';
 import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { listAllPlugins } from '../../core/resolver.js';
-import { scopeMemoryDir } from '../../core/scope.js';
+import { listInstalledPlugins } from '../../core/resolver.js';
+import { pluginMemoryDir, scopeMemoryDir } from '../../core/scope.js';
 import { isDocKind, RUNGS } from '../../core/substrate/index.js';
-import { SKILL_ENTRY_FILE, SKILLS_DIR } from '../../types.js';
 /** The parser normalizes the `always` alias to `content`, so it lints valid. */
 const VALID_RUNGS = [...RUNGS, 'always'];
 const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
@@ -78,14 +75,14 @@ function lintFile(file, substrateStore, findings) {
 export const lintLeaf = defineLeaf({
     name: 'lint',
     description: 'validate frontmatter across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (memory stores, plugin skills, ~/.claude/skills) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
     help: {
         name: 'memory lint',
         summary: 'strict-parse frontmatter across the bounded corpus; non-zero exit on any finding',
         params: [],
         output: [
             { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores, plugin_skills, claude_skills}.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores}.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
         ],
         outputKind: 'object',
@@ -94,40 +91,28 @@ export const lintLeaf = defineLeaf({
     run: async () => {
         const findings = [];
         let memoryCount = 0;
-        let pluginCount = 0;
-        let claudeCount = 0;
-        // 1. Substrate memory stores (project/user/builtin), schema-aware.
+        // Substrate memory stores (project/user/builtin), schema-aware. A scope's
+        // corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
+        // plugin docs are substrate docs and lint through the same schema gate.
         //    MEMORY.md index files are not substrate docs — YAML-parse only.
-        for (const scope of ['project', 'user', 'builtin']) {
-            const dir = scopeMemoryDir(scope);
+        const lintDir = (dir) => {
             if (!dir || !pathExists(dir))
-                continue;
+                return;
             for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
                 if (!relative(dir, file).split(sep).join('/'))
                     continue;
                 memoryCount += 1;
                 lintFile(file, basename(file) !== 'MEMORY.md', findings);
             }
-        }
-        // 2. Every installed plugin's skills tree (builtin + plugin + marketplace).
-        for (const plugin of listAllPlugins()) {
-            const skillsRoot = join(plugin.root, SKILLS_DIR);
-            if (!pathExists(skillsRoot))
-                continue;
-            for (const file of walkFiles(skillsRoot, (n) => n === SKILL_ENTRY_FILE)) {
-                pluginCount += 1;
-                lintFile(file, false, findings);
-            }
-        }
-        // 3. ~/.claude/skills — read by the runtime, so it lints too.
-        const claudeSkills = join(homedir(), '.claude', SKILLS_DIR);
-        if (pathExists(claudeSkills)) {
-            for (const file of walkFiles(claudeSkills, (n) => n === SKILL_ENTRY_FILE)) {
-                claudeCount += 1;
-                lintFile(file, false, findings);
+        };
+        for (const scope of ['project', 'user', 'builtin']) {
+            lintDir(scopeMemoryDir(scope));
+            for (const plugin of listInstalledPlugins(scope)) {
+                if (plugin.enabled)
+                    lintDir(pluginMemoryDir(plugin));
             }
         }
-        const checked = memoryCount + pluginCount + claudeCount;
+        const checked = memoryCount;
         if (findings.length > 0) {
             // Human/agent path renders only the message — surface every offender as
             // a scoped stderr notice (the --json path carries them in details too).
@@ -141,7 +126,7 @@ export const lintLeaf = defineLeaf({
         }
         return {
             checked,
-            corpora: { memory_stores: memoryCount, plugin_skills: pluginCount, claude_skills: claudeCount },
+            corpora: { memory_stores: memoryCount },
             findings: [],
             follow_up: 'Corpus green — zero invalid frontmatter docs.',
         };

package/dist/commands/memory/list.js

@@ -1,7 +1,6 @@
 import { defineLeaf } from '../../core/command.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
-import { parseSubstrateDoc } from '../../core/substrate/index.js';
-import { listAllSkills } from '../../core/resolver.js';
+import { parseSubstrateDoc, isIndexName, indexDirOf } from '../../core/substrate/index.js';
 import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
 export const listLeaf = defineLeaf({
     name: 'list',
@@ -15,7 +14,7 @@ export const listLeaf = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope}. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope, is_dir}. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash); is_dir is false for an ordinary doc. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
         ],
         outputKind: 'object',
@@ -40,21 +39,11 @@ export const listLeaf = defineLeaf({
                 continue;
             if (kindFilter !== undefined && sub.kind !== kindFilter)
                 continue;
-            addItem({ name: sub.name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm });
-        }
-        // Skill-plugin corpus (scope-root skills + plugin/marketplace skills).
-        // Only include when the kindFilter is absent or explicitly 'skill'.
-        if (kindFilter === undefined || kindFilter === 'skill') {
-            try {
-                for (const skill of listAllSkills(scopeFilter)) {
-                    const raw = skill.frontmatter.description;
-                    const desc = typeof raw === 'string' ? raw : '';
-                    addItem({ name: skill.name, kind: 'skill', scope: skill.scope, shortForm: desc });
-                }
-            }
-            catch {
-                /* skill corpus unavailable — list substrate documents alone */
-            }
+            // A directory INDEX surfaces as a dir entry: its dir path with a trailing
+            // slash, flagged is_dir, so the inventory distinguishes it from a doc.
+            const isDir = isIndexName(sub.name);
+            const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
+            addItem({ name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm, isDir });
         }
         items.sort((a, b) => {
             const sr = scopeRank(a.scope) - scopeRank(b.scope);
@@ -72,6 +61,7 @@ export const listLeaf = defineLeaf({
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
+                is_dir: d.isDir,
             })),
             follow_up: 'Read one in full with `crtr memory read <name>`. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
         };

package/dist/commands/memory/read.js

@@ -2,8 +2,6 @@ import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
 import { resolveMemoryDoc } from '../../core/memory-resolver.js';
 import { parseSubstrateDoc } from '../../core/substrate/index.js';
-import { resolveSkill } from '../../core/resolver.js';
-import { parseFrontmatter } from '../../core/frontmatter.js';
 import { readText } from '../../core/fs-utils.js';
 import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
@@ -33,9 +31,9 @@ export const readLeaf = defineLeaf({
         const nameRaw = input['name'];
         const kindFilter = input['kind'];
         const includeFrontmatter = input['frontmatter'];
-        // 1) Primary: resolve a substrate/memory document (memory/ dirs across
-        //    project>user>builtin). A not_found here is not fatal — it falls through
-        //    to the skill resolver below (the D4 union).
+        // Resolve a substrate/memory document across scopes (project>user>builtin,
+        // with leaf-name fallback). The substrate corpus now includes plugin docs
+        // (mounted under <pluginName>/), so this resolves every name.
         let doc;
         try {
             doc = resolveMemoryDoc(nameRaw);
@@ -51,8 +49,7 @@ export const readLeaf = defineLeaf({
                 : typeof doc.frontmatter?.['kind'] === 'string'
                     ? doc.frontmatter['kind']
                     : 'reference';
-            // --kind asserts the resolved kind; a mismatch falls through to skills
-            // (which only satisfy --kind=skill).
+            // --kind asserts the resolved kind; a mismatch falls through to not-found.
             if (kindFilter === undefined || kind === kindFilter) {
                 const content = includeFrontmatter ? readText(doc.path) : doc.body;
                 return {
@@ -65,36 +62,6 @@ export const readLeaf = defineLeaf({
                 };
             }
         }
-        // 2) D4 union fallthrough: the name is not a memory document (or its kind
-        //    did not match --kind) — resolve it as a plugin/marketplace/scope skill
-        //    so skills are readable through `crtr memory read` too. Skills are kind
-        //    "skill", so honor --kind by skipping this path for other kinds.
-        if (kindFilter === undefined || kindFilter === 'skill') {
-            let skill;
-            try {
-                skill = resolveSkill(nameRaw);
-            }
-            catch (e) {
-                // not_found → fall through to the memory-not-found below. A genuine
-                // CrtrError (e.g. ambiguous) propagates. Any other throw means the skill
-                // corpus is currently unparseable (the yaml-parser regression owned by
-                // the frontmatter/skill track) — degrade to not-found rather than 500.
-                if (e instanceof CrtrError && e.code !== 'not_found')
-                    throw e;
-            }
-            if (skill !== undefined) {
-                const raw = readText(skill.path);
-                const content = includeFrontmatter ? raw : parseFrontmatter(raw).body;
-                return {
-                    name: skill.name,
-                    kind: 'skill',
-                    scope: skill.scope,
-                    path: skill.path,
-                    content,
-                    follow_up: 'Add --frontmatter to include the YAML header. Browse the inventory with `crtr memory list`.',
-                };
-            }
-        }
         throw notFound(`memory document not found: ${nameRaw}`, {
             memory: nameRaw,
             next: 'Run `crtr memory find <query>` to discover documents, or `crtr memory list` to browse the inventory.',

package/dist/commands/pkg/bridge.d.ts

@@ -0,0 +1 @@
+export declare const bridgeBranch: import("../../core/command.js").BranchDef;

package/dist/commands/pkg/bridge.js

@@ -0,0 +1,137 @@
+// `crtr pkg bridge` — generate crouter substrate docs from a Claude skills root
+// and file-level reconcile the bridge plugin (design §2). The mapping lives in
+// core/bridge-map.ts (one testable source of truth); the extension shells to
+// this command rather than duplicating the transform.
+import { join, basename, dirname, isAbsolute } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { userScopeRoot } from '../../core/scope.js';
+import { ensureDir, writeJson, writeText, readText, removePath, walkFiles, } from '../../core/fs-utils.js';
+import { parseFrontmatter, parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { buildBridgeDoc } from '../../core/bridge-map.js';
+import { PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE } from '../../types.js';
+/** Enumerate `<source>/**\/SKILL.md`, stopping recursion at the first SKILL.md
+ *  on any branch — a dir that holds SKILL.md is a skill; its subdirs are assets,
+ *  not nested skills. */
+function enumerateSkillFiles(root) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        const hasSkill = entries.some((e) => e.isFile() && e.name === 'SKILL.md');
+        if (hasSkill) {
+            out.push(join(dir, 'SKILL.md'));
+            continue; // stop descent — deeper dirs are assets
+        }
+        for (const e of entries)
+            if (e.isDirectory())
+                stack.push(join(dir, e.name));
+    }
+    return out;
+}
+const bridgeSync = defineLeaf({
+    name: 'sync',
+    description: 'generate substrate docs from a Claude skills root',
+    whenToUse: 'mirroring a Claude Code skills directory into a crtr bridge plugin: maps each SKILL.md to a substrate memory doc and file-level reconciles the plugin (regenerate, prune stale, preserve hand-authored leaves + INDEX)',
+    help: {
+        name: 'pkg bridge sync',
+        summary: 'mirror a Claude skills root into a crtr bridge plugin (idempotent reconcile)',
+        guide: 'Each <source>/skills/<skillname>/SKILL.md becomes ~/.crouter/plugins/<name>/memory/<skillname>.md, stamped generator:claude-bridge. Stamped leaves whose source skill is gone are pruned; hand-authored leaves and any INDEX.md are never touched.',
+        params: [
+            { kind: 'flag', name: 'source', type: 'path', required: true, constraint: 'Absolute path to a Claude skills root (a dir whose <skillname>/SKILL.md leaves are bridged; recursion stops at the first SKILL.md).' },
+            { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Bridge plugin name. Dest plugin dir is ~/.crouter/plugins/<name>/.' },
+            { kind: 'flag', name: 'source-desc', type: 'string', required: false, constraint: 'Optional plugin description written into the generated plugin.json.' },
+        ],
+        output: [
+            { name: 'plugin', type: 'string', required: true, constraint: 'Bridge plugin name.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the bridge plugin directory.' },
+            { name: 'written', type: 'number', required: true, constraint: 'Count of substrate leaves generated from source SKILL.md files.' },
+            { name: 'pruned', type: 'number', required: true, constraint: 'Count of stale generator:claude-bridge leaves deleted (source skill gone).' },
+            { name: 'preserved', type: 'number', required: true, constraint: 'Count of untouched protected leaves (INDEX.md or unstamped hand-authored docs).' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes ~/.crouter/plugins/<name>/.crouter-plugin/plugin.json and memory/*.md. Deletes stale generator:claude-bridge leaves. Never writes or deletes INDEX.md or unstamped docs.'],
+    },
+    run: async (input) => {
+        const source = input['source'];
+        const name = input['name'];
+        const sourceDesc = input['sourceDesc'];
+        if (!isAbsolute(source)) {
+            throw usage(`--source must be an absolute path: ${source}`);
+        }
+        if (!existsSync(source)) {
+            throw usage(`--source does not exist: ${source}`);
+        }
+        const destRoot = join(userScopeRoot(), 'plugins', name);
+        const memoryDir = join(destRoot, 'memory');
+        // 1. Ensure the bridge plugin manifest.
+        const manifestDir = join(destRoot, PLUGIN_MANIFEST_DIR);
+        ensureDir(manifestDir);
+        const manifest = {
+            name,
+            version: '0.0.0',
+            ...(sourceDesc !== undefined ? { description: sourceDesc } : {}),
+            source,
+            generator: 'claude-bridge',
+        };
+        writeJson(join(manifestDir, PLUGIN_MANIFEST_FILE), manifest);
+        // 2 + 3. Regenerate one stamped leaf per source skill.
+        ensureDir(memoryDir);
+        const writtenPaths = new Set();
+        for (const file of enumerateSkillFiles(source)) {
+            const skillName = basename(dirname(file));
+            const parsed = parseFrontmatter(readText(file));
+            const doc = buildBridgeDoc({
+                name: parsed.data?.name ?? skillName,
+                description: parsed.data?.description ?? '',
+                body: parsed.body,
+            });
+            const dest = join(memoryDir, `${skillName}.md`);
+            writeText(dest, doc);
+            writtenPaths.add(dest);
+        }
+        const written = writtenPaths.size;
+        // 4. Reconcile: prune stale stamped leaves; never touch INDEX.md or
+        //    unstamped (hand-authored) leaves.
+        let pruned = 0;
+        let preserved = 0;
+        for (const f of walkFiles(memoryDir, (n) => n.endsWith('.md'))) {
+            if (writtenPaths.has(f))
+                continue; // just regenerated → counted in `written`
+            if (basename(f) === 'INDEX.md') {
+                preserved++;
+                continue;
+            }
+            const generator = parseFrontmatterGeneric(readText(f)).data?.['generator'];
+            if (generator === 'claude-bridge') {
+                removePath(f);
+                pruned++;
+            }
+            else {
+                preserved++;
+            }
+        }
+        return { plugin: name, path: destRoot, written, pruned, preserved };
+    },
+});
+export const bridgeBranch = defineBranch({
+    name: 'bridge',
+    description: 'mirror Claude skills into crtr bridge plugins',
+    whenToUse: 'generating a crtr bridge plugin from a Claude Code skills root — the substrate-doc mapping and file-level reconcile invoked by the pi bridge extension',
+    help: {
+        name: 'pkg bridge',
+        summary: 'mirror Claude skills roots into crtr bridge plugins',
+        model: 'A bridge plugin is a generator:claude-bridge plugin whose memory/ docs are generated from a Claude skills root. Hand-authored leaves and INDEX ceilings are preserved across syncs.',
+    },
+    children: [bridgeSync],
+});

package/dist/commands/pkg/plugin-inspect.js

@@ -1,7 +1,8 @@
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { notFound } from '../../core/errors.js';
 import { paginate } from '../../core/pagination.js';
-import { listInstalledPlugins, findPluginByName, listSkillsInPlugin, } from '../../core/resolver.js';
+import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
+import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 // ---------------------------------------------------------------------------
 // plugin.inspect.list
@@ -78,8 +79,8 @@ const pluginList = defineLeaf({
 // ---------------------------------------------------------------------------
 const pluginShow = defineLeaf({
     name: 'show',
-    description: 'read plugin manifest and skill inventory',
-    whenToUse: 'reading one installed plugin in detail to decide before you enable, disable, or remove it — returns the full manifest, the skills it provides, its scope, and whether it is currently enabled. Use `pkg plugin inspect list` instead to enumerate plugins rather than drill into one',
+    description: 'read plugin manifest and substrate inventory',
+    whenToUse: 'reading one installed plugin in detail to decide before you enable, disable, or remove it — returns the full manifest, the substrate docs it provides (its `<pluginName>/` memory subtree), its scope, and whether it is currently enabled. Use `pkg plugin inspect list` instead to enumerate plugins rather than drill into one',
     help: {
         name: 'pkg plugin inspect show',
         summary: 'read plugin manifest and metadata by name',
@@ -93,7 +94,7 @@ const pluginShow = defineLeaf({
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the plugin directory.' },
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
-            { name: 'skills', type: 'object[]', required: true, constraint: 'Each: {name, path, enabled}. Skills provided by the plugin.' },
+            { name: 'skills', type: 'object[]', required: true, constraint: 'Each: {name, path}. Substrate docs provided by the plugin (its `<pluginName>/` memory subtree).' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -117,7 +118,8 @@ const pluginShow = defineLeaf({
         if (found === null) {
             throw notFound(`plugin not found: ${name}`);
         }
-        const skills = listSkillsInPlugin(found);
+        const prefix = `${found.name}/`;
+        const skills = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
         return {
             name: found.name,
             scope: found.scope,
@@ -127,7 +129,6 @@ const pluginShow = defineLeaf({
             skills: skills.map((s) => ({
                 name: s.name,
                 path: s.path,
-                enabled: s.enabled,
             })),
         };
     },

package/dist/commands/pkg.js

@@ -4,6 +4,7 @@
 import { defineBranch } from '../core/command.js';
 import { pluginBranch } from './pkg/plugin.js';
 import { marketBranch } from './pkg/market.js';
+import { bridgeBranch } from './pkg/bridge.js';
 export function registerPkg() {
     return defineBranch({
         name: 'pkg',
@@ -16,6 +17,6 @@ export function registerPkg() {
             name: 'pkg',
             summary: 'manage plugins and plugin marketplaces',
         },
-        children: [pluginBranch, marketBranch],
+        children: [pluginBranch, marketBranch, bridgeBranch],
     });
 }

package/dist/commands/skill/author.js

@@ -1,14 +1,14 @@
-import { join } from 'node:path';
+import { dirname } from 'node:path';
 import { writeFileSync } from 'node:fs';
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { usage, general, notFound } from '../../core/errors.js';
-import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, } from '../../types.js';
+import { SKILL_TYPES, isSkillType } from '../../types.js';
 import { parseSkillQualifier, findPluginByName, } from '../../core/resolver.js';
-import { resolveScopeArg, requireScopeRoot, scopeSkillsDir, } from '../../core/scope.js';
-import { serializeFrontmatter } from '../../core/frontmatter.js';
+import { resolveScopeArg, requireScopeRoot, scopeMemoryDir, pluginMemoryDir, } from '../../core/scope.js';
 import { ensureScopeInitialized } from '../../core/config.js';
 import { ensureDir, pathExists } from '../../core/fs-utils.js';
 import { skillCreatePrompt, skillTemplatePrompt } from '../../prompts/skill.js';
+import { memoryFilePath, serializeMemoryDoc } from '../memory/shared.js';
 import { VALID_TYPES, resolveWriteScope } from './shared.js';
 export const authorGuide = defineLeaf({
     name: 'guide',
@@ -42,25 +42,25 @@ export const authorGuide = defineLeaf({
 });
 export const authorScaffold = defineLeaf({
     name: 'scaffold',
-    description: 'create an empty SKILL.md stub',
-    whenToUse: 'creating the empty SKILL.md stub at a `<plugin>/<skill>` qualifier before you fill in content — it writes the frontmatter and file, then points you at the authoring guide.',
+    description: 'create an empty skill substrate doc stub',
+    whenToUse: 'creating the empty `kind: skill` substrate doc at a `<plugin>/<skill>` qualifier (or a bare `<skill>` name for a scope-owned doc) before you fill in content — it writes the frontmatter and file, then points you at the authoring guide.',
     help: {
         name: 'skill author scaffold',
-        summary: 'create an empty SKILL.md stub at the given qualifier',
+        summary: 'create an empty kind:skill substrate doc stub at the given qualifier',
         params: [
-            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier in <plugin>/<skill> form.' },
-            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform.' },
-            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Short description written to frontmatter.' },
+            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier: <plugin>/<skill> to scaffold into a plugin\'s memory/, or a bare <skill> for the scope-owned memory/.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform. Drives the follow-up authoring guide only — not stored on the substrate doc.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Read-routing line written to the doc\'s when-and-why-to-read frontmatter.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
         ],
         output: [
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded SKILL.md.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded substrate doc.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call to load the authoring guide.' },
         ],
         outputKind: 'object',
         effects: [
-            'Creates the skill directory and SKILL.md stub at the resolved location.',
-            'Writes frontmatter with name, description (if provided), and type (if provided).',
+            'Creates a `kind: skill` substrate doc stub under the resolved memory/ dir (scope-owned, or the named plugin\'s).',
+            'Writes substrate frontmatter: kind:skill, when-and-why-to-read (from --description if given), system-prompt-visibility:name, file-read-visibility:none.',
         ],
     },
     run: async (input) => {
@@ -82,31 +82,20 @@ export const authorScaffold = defineLeaf({
             throw usage(`unknown skill type: ${typeStr} / valid: ${SKILL_TYPES.join(' | ')}`);
         }
         const skillType = typeStr !== undefined && isSkillType(typeStr) ? typeStr : undefined;
-        let skillFile;
-        // Scope-direct: no plugin qualifier, or explicit `_/` sentinel (internal only)
-        if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
+        // Resolve the memory/ dir to scaffold into: the named plugin's, or the
+        // scope-owned one. One substrate, one author path.
+        let memoryDir;
+        if (pluginName === undefined) {
             const scope = resolveWriteScope(scopeStr);
             const scopeRootPath = requireScopeRoot(scope);
             ensureScopeInitialized(scope, scopeRootPath);
-            const skillsRoot = scopeSkillsDir(scope);
-            if (!skillsRoot) {
-                throw general(`no skills dir for scope ${scope}`);
+            const dir = scopeMemoryDir(scope);
+            if (!dir) {
+                throw general(`no memory dir for scope ${scope}`);
             }
-            const skillDir = join(skillsRoot, ...skillName.split('/'));
-            skillFile = join(skillDir, SKILL_ENTRY_FILE);
-            if (pathExists(skillFile)) {
-                throw general(`skill already exists: ${skillFile}`);
-            }
-            ensureDir(skillDir);
-            const fm = serializeFrontmatter({
-                name: skillName,
-                description,
-                type: skillType,
-            });
-            writeFileSync(skillFile, fm, 'utf8');
+            memoryDir = dir;
         }
         else {
-            // Plugin-scoped scaffold
             const scopeForLookup = scopeStr !== undefined
                 ? (() => {
                     const r = resolveScopeArg(scopeStr);
@@ -119,19 +108,21 @@ export const authorScaffold = defineLeaf({
             if (!plugin) {
                 throw notFound(`plugin not found: ${pluginName}`);
             }
-            const skillDir = join(plugin.root, SKILLS_DIR, ...skillName.split('/'));
-            skillFile = join(skillDir, SKILL_ENTRY_FILE);
-            if (pathExists(skillFile)) {
-                throw general(`skill already exists: ${skillFile}`);
-            }
-            ensureDir(skillDir);
-            const fm = serializeFrontmatter({
-                name: skillName,
-                description,
-                type: skillType,
-            });
-            writeFileSync(skillFile, fm, 'utf8');
+            memoryDir = pluginMemoryDir(plugin);
+        }
+        const skillFile = memoryFilePath(memoryDir, skillName);
+        if (pathExists(skillFile)) {
+            throw general(`skill already exists: ${skillFile}`);
         }
+        ensureDir(dirname(skillFile));
+        // Catalog-default substrate frontmatter (design §1.5): a name-rung,
+        // file-read-none skill doc. --description becomes the read-routing line.
+        const frontmatter = { kind: 'skill' };
+        if (description !== undefined)
+            frontmatter['when-and-why-to-read'] = description;
+        frontmatter['system-prompt-visibility'] = 'name';
+        frontmatter['file-read-visibility'] = 'none';
+        writeFileSync(skillFile, serializeMemoryDoc(frontmatter, ''), 'utf8');
         const typeHint = skillType !== undefined ? `--type ${skillType} ` : '';
         const follow_up = `crtr skill author guide ${typeHint}--topic "${skillName}"`;
         return { path: skillFile, follow_up };

package/dist/commands/skill/shared.d.ts

@@ -1,8 +1,4 @@
-import type { Skill, Scope } from '../../types.js';
-export declare function formatNeighborQualifier(s: Skill): string;
-export declare function formatNeighborKeywords(s: Skill): string;
-export declare function buildNeighborsSection(skill: Skill): string | null;
-export declare function appendNeighbors(skill: Skill, body: string): string;
+import type { Scope } from '../../types.js';
 export declare function resolveWriteScope(scopeStr: string | undefined): Scope;
 export declare const VALID_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
 export type CatalogSource = {