@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/init/scaffold-agents-md.js

@@ -0,0 +1,182 @@
+/**
+ * Render `catalog/AGENTS.md.tpl` into the consumer's `AGENTS.md`.
+ *
+ * Placeholders:
+ * - {{REPOSITORY_MAP}}: bulleted list of workspace packages, or "single-package" fallback.
+ * - {{TECH_STACK}}: detected from package.json deps.
+ * - {{ESCALATION_MAP}}: TODO placeholder.
+ * - {{DURABLE_PLANNING_ROOT}}: from .webpressorc.json, defaulting to `.agent/planning/`.
+ * - {{BLUEPRINTS_DIR}}: from .webpressorc.json, defaulting to `blueprints`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DEFAULT_DURABLE_PLANNING_ROOT } from './config.js';
+import { writeFileMerged } from './merge.js';
+const TECH_STACK_RULES = [
+    { dep: /^react(-dom)?$/, label: 'React' },
+    { dep: /^next$/, label: 'Next.js' },
+    { dep: /^@remix-run\//, label: 'Remix' },
+    { dep: /^@tanstack\/react-query$/, label: 'TanStack Query' },
+    { dep: /^hono$/, label: 'Hono' },
+    { dep: /^drizzle-orm$/, label: 'Drizzle ORM' },
+    { dep: /^@cloudflare\/workers-types$/, label: 'Cloudflare Workers' },
+    { dep: /^wrangler$/, label: 'Cloudflare Workers (wrangler)' },
+    { dep: /^pg$|^postgres$|^@neondatabase\//, label: 'PostgreSQL' },
+    { dep: /^better-auth$/, label: 'better-auth' },
+    { dep: /^vitest$/, label: 'Vitest' },
+    { dep: /^@playwright\/test$/, label: 'Playwright' },
+    { dep: /^zod$/, label: 'Zod' },
+    { dep: /^typescript$/, label: 'TypeScript' },
+];
+export function renderRepositoryMap(consumer) {
+    const packages = consumer.workspacePackages;
+    if (packages.length === 0) {
+        const name = consumer.packageJson?.name ?? 'this project';
+        return `Single-package project: \`${name}\` (root: \`${consumer.repoRoot}\`).`;
+    }
+    return packages.map((p) => `- \`${p.name}\` — \`${p.relativePath}\``).join('\n');
+}
+export function renderTechStack(consumer) {
+    const deps = {
+        ...consumer.packageJson?.dependencies,
+        ...consumer.packageJson?.devDependencies,
+    };
+    const depNames = Object.keys(deps);
+    const matches = new Set();
+    for (const name of depNames) {
+        for (const rule of TECH_STACK_RULES) {
+            if (rule.dep.test(name))
+                matches.add(rule.label);
+        }
+    }
+    if (matches.size === 0) {
+        return '{{TODO: list the tech stack (frameworks, DB, runtime) for this repo.}}';
+    }
+    return Array.from(matches)
+        .toSorted()
+        .map((label) => `- ${label}`)
+        .join('\n');
+}
+const MANAGED_BEGIN = /^<!-- >>> managed by webpresso \(([^)]+)\) -->$/u;
+const MANAGED_END = /^<!-- <<< managed by webpresso \(([^)]+)\) -->$/u;
+const USER_BEGIN = /^<!-- >>> user-owned \(([^)]+)\) -->$/u;
+const USER_END = /^<!-- <<< user-owned \(([^)]+)\) -->$/u;
+function parseAgentsBlocks(content) {
+    const lines = content.split('\n');
+    const blocks = [];
+    let cursor = 0;
+    while (cursor < lines.length) {
+        const line = lines[cursor] ?? '';
+        const managedStart = MANAGED_BEGIN.exec(line);
+        const userStart = USER_BEGIN.exec(line);
+        if (!managedStart && !userStart) {
+            cursor += 1;
+            continue;
+        }
+        const kind = managedStart ? 'managed' : 'user';
+        const id = managedStart?.[1] ?? userStart?.[1];
+        const endMatcher = kind === 'managed' ? MANAGED_END : USER_END;
+        let endLine = cursor + 1;
+        while (endLine < lines.length && !endMatcher.test(lines[endLine] ?? '')) {
+            endLine += 1;
+        }
+        if (!id || endLine >= lines.length) {
+            cursor += 1;
+            continue;
+        }
+        blocks.push({
+            kind,
+            id,
+            startLine: cursor,
+            endLine,
+            innerLines: lines.slice(cursor + 1, endLine),
+        });
+        cursor = endLine + 1;
+    }
+    return blocks;
+}
+function renderBlock(kind, id, innerLines) {
+    const begin = kind === 'managed'
+        ? `<!-- >>> managed by webpresso (${id}) -->`
+        : `<!-- >>> user-owned (${id}) -->`;
+    const end = kind === 'managed'
+        ? `<!-- <<< managed by webpresso (${id}) -->`
+        : `<!-- <<< user-owned (${id}) -->`;
+    return [begin, ...innerLines, end];
+}
+export function mergeRenderedAgentsMd(rendered, existing) {
+    const renderedBlocks = parseAgentsBlocks(rendered);
+    const existingBlocks = parseAgentsBlocks(existing);
+    if (renderedBlocks.length === 0 || existingBlocks.length === 0)
+        return null;
+    const existingUserBlocks = new Map(existingBlocks
+        .filter((block) => block.kind === 'user')
+        .map((block) => [block.id, block.innerLines]));
+    const lines = rendered.split('\n');
+    const replacements = renderedBlocks
+        .filter((block) => block.kind === 'user')
+        .map((block) => ({
+        ...block,
+        replacement: renderBlock('user', block.id, existingUserBlocks.get(block.id) ?? block.innerLines),
+    }))
+        .toReversed();
+    for (const block of replacements) {
+        lines.splice(block.startLine, block.endLine - block.startLine + 1, ...block.replacement);
+    }
+    return lines.join('\n');
+}
+function writeAgentsMdManaged(targetPath, rendered, opts = {}) {
+    const exists = existsSync(targetPath);
+    if (!exists) {
+        if (opts.dryRun)
+            return { targetPath, action: 'skipped-dry' };
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, rendered);
+        return { targetPath, action: 'created' };
+    }
+    const existing = readFileSync(targetPath, 'utf8');
+    if (existing === rendered)
+        return { targetPath, action: 'identical' };
+    const merged = mergeRenderedAgentsMd(rendered, existing);
+    if (merged === null) {
+        return writeFileMerged(targetPath, rendered, opts);
+    }
+    if (merged === existing)
+        return { targetPath, action: 'identical' };
+    if (opts.dryRun)
+        return { targetPath, action: 'skipped-dry' };
+    writeFileSync(targetPath, merged);
+    return { targetPath, action: 'overwritten' };
+}
+function withTrailingSlash(path) {
+    return path.endsWith('/') ? path : `${path}/`;
+}
+function withoutTrailingSlash(path) {
+    return path.replace(/\/+$/u, '');
+}
+export function renderAgentsMd(template, consumer, config) {
+    const durablePlanningRoot = withTrailingSlash(config.durablePlanningRoot || DEFAULT_DURABLE_PLANNING_ROOT);
+    const replacements = {
+        '{{REPOSITORY_MAP}}': renderRepositoryMap(consumer),
+        '{{TECH_STACK}}': renderTechStack(consumer),
+        '{{ESCALATION_MAP}}': '{{TODO: populate escalation map — who to ping for which subsystem.}}',
+        '{{DURABLE_PLANNING_ROOT}}': durablePlanningRoot,
+        '{{BLUEPRINTS_DIR}}': withoutTrailingSlash(config.blueprintsDir ?? 'blueprints'),
+    };
+    let output = template;
+    for (const [key, value] of Object.entries(replacements)) {
+        output = output.split(key).join(value);
+    }
+    return output;
+}
+export function scaffoldAgentsMd(input) {
+    const { catalogDir, repoRoot, consumer, config, options } = input;
+    const tplPath = join(catalogDir, 'AGENTS.md.tpl');
+    if (!existsSync(tplPath))
+        return null;
+    const template = readFileSync(tplPath, 'utf8');
+    const rendered = renderAgentsMd(template, consumer, config);
+    const target = join(repoRoot, 'AGENTS.md');
+    return writeAgentsMdManaged(target, rendered, options);
+}
+//# sourceMappingURL=scaffold-agents-md.js.map

package/dist/esm/cli/commands/init/scaffold-base-kit.d.ts

@@ -0,0 +1,9 @@
+import { type MergeOptions, type MergeResult } from './merge.js';
+export interface ScaffoldBaseKitInput {
+    catalogDir: string;
+    repoRoot: string;
+    options: MergeOptions;
+    globalInstall?: boolean;
+}
+export declare function scaffoldBaseKit(input: ScaffoldBaseKitInput): MergeResult[];
+//# sourceMappingURL=scaffold-base-kit.d.ts.map

package/dist/esm/cli/commands/init/scaffold-base-kit.js

@@ -0,0 +1,183 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { writeFileMerged } from './merge.js';
+/** Template files relative to `catalog/base-kit/`, and their target paths relative to repoRoot. */
+const TEMPLATE_MAP = [
+    ['.editorconfig.tmpl', '.editorconfig'],
+    ['.secretlintrc.json.tmpl', '.secretlintrc.json'],
+    ['.actrc.tmpl', '.actrc'],
+    ['commitlint.config.ts.tmpl', 'commitlint.config.ts'],
+    ['scripts/check-no-dev-vars.ts.tmpl', 'scripts/check-no-dev-vars.ts'],
+    [
+        'scripts/audit-secret-provider-quarantine.ts.tmpl',
+        'scripts/audit-secret-provider-quarantine.ts',
+    ],
+    ['.husky/pre-commit.tmpl', '.husky/pre-commit'],
+    ['.husky/commit-msg.tmpl', '.husky/commit-msg'],
+    ['.github/workflows/ci.webpresso.yml.tmpl', '.github/workflows/ci.webpresso.yml'],
+    ['test/.gitkeep.tmpl', 'test/.gitkeep'],
+    ['e2e/.gitkeep.tmpl', 'e2e/.gitkeep'],
+];
+/**
+ * Bootstrap-only templates: the scaffolder writes them when absent (so a
+ * fresh repo gets sane defaults) but NEVER overwrites them once they exist
+ * — even under `--overwrite`. These files are consumer-owned and grow with
+ * project-specific content (catalog entries, ignore patterns) that the
+ * generic template can't reproduce. Clobbering them on every `wp setup`
+ * deletes that content silently, breaks `vp install`, and pollutes git
+ * status with thousands of newly-tracked artifacts.
+ *
+ * Verified failure mode (large multi-package workspace, 2026-05-07): the postinstall
+ * `wp setup --overwrite` reduced pnpm-workspace.yaml from 221 lines (full
+ * catalog) to 34 lines (generic template), removing catalog entries
+ * referenced by `pnpm.overrides` and
+ * making subsequent `vp install` fail with ERR_PNPM_CATALOG_IN_OVERRIDES.
+ * The same overwrite stripped workspace-specific .gitignore rules
+ * (.test-reports/, generated outputs, worker-state directories, etc.),
+ * unmasking 23k+ generated artifacts to git status.
+ */
+const BOOTSTRAP_ONLY_MAP = [
+    ['.gitignore.tmpl', '.gitignore'],
+    ['pnpm-workspace.yaml.tmpl', 'pnpm-workspace.yaml'],
+];
+/** Merge `engines` and `packageManager` into the consumer repo's package.json. */
+function mergePackageJson(repoRoot, options, globalInstall = false) {
+    const pkgPath = join(repoRoot, 'package.json');
+    const engines = { node: '>=24' };
+    const packageManager = 'pnpm@11.1.1';
+    if (options.dryRun) {
+        return { targetPath: pkgPath, action: 'skipped-dry' };
+    }
+    let pkg = {};
+    if (existsSync(pkgPath)) {
+        try {
+            pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        }
+        catch {
+            // malformed — leave untouched
+            return { targetPath: pkgPath, action: 'identical' };
+        }
+    }
+    else {
+        pkg = { name: 'my-app', version: '0.0.0', private: true, type: 'module' };
+    }
+    const existing = pkg['engines'];
+    const alreadyHasEngines = existing?.node === engines.node;
+    // Don't downgrade: treat any pnpm@11+ as already-satisfied so wp setup
+    // does not regress repos that have already been migrated to v11.
+    const existingPm = pkg['packageManager'];
+    const alreadyHasPm = existingPm === packageManager ||
+        (typeof existingPm === 'string' && /^pnpm@1[1-9]\./.test(existingPm));
+    const packageName = typeof pkg['name'] === 'string' ? pkg['name'] : undefined;
+    const scripts = (pkg['scripts'] ?? {});
+    const hasSetupAgent = typeof scripts['setup:agent'] === 'string';
+    const hasVerifyPaths = typeof scripts['verify:paths'] === 'string';
+    const hasVerifySecrets = typeof scripts['verify:secrets'] === 'string';
+    const hasSecretQuarantineAudit = typeof scripts['audit:secret-provider-quarantine'] === 'string';
+    const hasPrepareScript = typeof scripts['prepare'] === 'string';
+    const verifyPathsScript = 'WP_SKIP_UPDATE_CHECK=1 wp audit absolute-path-policy --root .';
+    const verifySecretsScript = 'bun scripts/check-no-dev-vars.ts';
+    const secretQuarantineAuditScript = 'bun scripts/audit-secret-provider-quarantine.ts';
+    const devDeps = (pkg['devDependencies'] ?? {});
+    const hasAgentKitDevDep = typeof devDeps['webpresso'] === 'string';
+    const shouldSkipSelfInstall = packageName === 'webpresso';
+    const shouldManageAgentKitAsGlobal = globalInstall && !shouldSkipSelfInstall;
+    if (alreadyHasEngines &&
+        alreadyHasPm &&
+        (shouldSkipSelfInstall || shouldManageAgentKitAsGlobal || hasAgentKitDevDep) &&
+        (shouldSkipSelfInstall || hasSetupAgent) &&
+        (shouldSkipSelfInstall || hasVerifyPaths) &&
+        (shouldSkipSelfInstall || hasVerifySecrets) &&
+        (shouldSkipSelfInstall || hasSecretQuarantineAudit) &&
+        (shouldSkipSelfInstall || hasPrepareScript)) {
+        return { targetPath: pkgPath, action: 'identical' };
+    }
+    pkg['engines'] = { ...existing, node: engines.node };
+    if (!alreadyHasPm)
+        pkg['packageManager'] = packageManager;
+    // Ensure husky is in devDependencies so `vp exec husky init` works
+    if (!devDeps['husky']) {
+        devDeps['husky'] = '^9.0.0';
+    }
+    if (!shouldSkipSelfInstall && !shouldManageAgentKitAsGlobal && !hasAgentKitDevDep) {
+        // Keep consumers on the currently published dist-tag rather than a
+        // repo-internal path. Do not wire this through `prepare`: `wp` is not
+        // reliably on PATH during `vp install`, so `setup:agent` stays opt-in.
+        devDeps['webpresso'] = 'latest';
+    }
+    pkg['devDependencies'] = devDeps;
+    if (!shouldSkipSelfInstall && !hasSetupAgent) {
+        scripts['setup:agent'] = 'wp setup';
+    }
+    if (!shouldSkipSelfInstall && !hasVerifyPaths) {
+        scripts['verify:paths'] = verifyPathsScript;
+    }
+    if (!shouldSkipSelfInstall && !hasVerifySecrets) {
+        scripts['verify:secrets'] = verifySecretsScript;
+    }
+    if (!shouldSkipSelfInstall && !hasSecretQuarantineAudit) {
+        scripts['audit:secret-provider-quarantine'] = secretQuarantineAuditScript;
+    }
+    if (!shouldSkipSelfInstall && !hasPrepareScript) {
+        scripts['prepare'] = 'husky';
+    }
+    if (Object.keys(scripts).length > 0) {
+        pkg['scripts'] = scripts;
+    }
+    mkdirSync(dirname(pkgPath), { recursive: true });
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    return { targetPath: pkgPath, action: 'overwritten' };
+}
+export function scaffoldBaseKit(input) {
+    const { catalogDir, repoRoot, options, globalInstall = false } = input;
+    const baseKitDir = join(catalogDir, 'base-kit');
+    const results = [];
+    for (const [tmplRel, targetRel] of TEMPLATE_MAP) {
+        const tmplPath = join(baseKitDir, tmplRel);
+        if (!existsSync(tmplPath))
+            continue;
+        const content = readFileSync(tmplPath, 'utf8');
+        const targetPath = join(repoRoot, targetRel);
+        results.push(writeFileMerged(targetPath, content, options));
+    }
+    // Bootstrap-only: write template only when target is absent. Never
+    // overwrite (even under --overwrite): the consumer's existing file is the
+    // source of truth once it exists.
+    for (const [tmplRel, targetRel] of BOOTSTRAP_ONLY_MAP) {
+        const tmplPath = join(baseKitDir, tmplRel);
+        if (!existsSync(tmplPath))
+            continue;
+        const targetPath = join(repoRoot, targetRel);
+        if (existsSync(targetPath)) {
+            results.push({ targetPath, action: 'identical' });
+            continue;
+        }
+        const content = readFileSync(tmplPath, 'utf8');
+        if (options.dryRun) {
+            results.push({ targetPath, action: 'skipped-dry' });
+            continue;
+        }
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, content);
+        results.push({ targetPath, action: 'created' });
+    }
+    // Make husky hook files executable
+    if (!options.dryRun) {
+        for (const [tmplRel, targetRel] of TEMPLATE_MAP) {
+            if (tmplRel.startsWith('.husky/')) {
+                const targetPath = join(repoRoot, targetRel);
+                if (existsSync(targetPath)) {
+                    try {
+                        chmodSync(targetPath, 0o755);
+                    }
+                    catch {
+                        /* non-fatal */
+                    }
+                }
+            }
+        }
+    }
+    results.push(mergePackageJson(repoRoot, options, globalInstall));
+    return results;
+}
+//# sourceMappingURL=scaffold-base-kit.js.map

package/dist/esm/cli/commands/init/scaffold-blueprints.d.ts

@@ -0,0 +1,8 @@
+import { type MergeOptions, type MergeResult } from './merge.js';
+export declare const BLUEPRINT_STATES: readonly ["draft", "planned", "in-progress", "completed", "parked", "archived"];
+export interface ScaffoldBlueprintsInput {
+    repoRoot: string;
+    options: MergeOptions;
+}
+export declare function scaffoldBlueprints(input: ScaffoldBlueprintsInput): MergeResult[];
+//# sourceMappingURL=scaffold-blueprints.d.ts.map

package/dist/esm/cli/commands/init/scaffold-blueprints.js

@@ -0,0 +1,84 @@
+/**
+ * Create `blueprints/{draft,planned,in-progress,completed,parked,archived}/`
+ * with `.gitkeep` files and a short README pointing to the relevant templates
+ * and skills.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { writeFileMerged } from './merge.js';
+/**
+ * For scaffolding (first-time setup), `resolveBlueprintRoot` falls back to
+ * `webpresso/blueprints` for repos with no project markers at all.  A fresh
+ * generic repo should get `blueprints/` instead.  We correct this by only
+ * accepting the webpresso fallback when there is an actual webpresso marker on
+ * disk.
+ */
+function resolveScaffoldBlueprintsDir(repoRoot) {
+    const resolved = resolveBlueprintRoot(repoRoot);
+    const webpressoBlueprints = join(repoRoot, 'webpresso', 'blueprints');
+    const isWebpressoRepo = existsSync(join(repoRoot, 'webpresso', 'config.yaml'));
+    if (!isWebpressoRepo && resolved === webpressoBlueprints) {
+        return join(repoRoot, 'blueprints');
+    }
+    return resolved;
+}
+export const BLUEPRINT_STATES = [
+    'draft',
+    'planned',
+    'in-progress',
+    'completed',
+    'parked',
+    'archived',
+];
+const BLUEPRINTS_README = `# Blueprints
+
+This directory is the canonical home for implementation plans (blueprints).
+Each subdirectory represents a lifecycle state:
+
+- \`draft/\` — early-stage sketches. Expect churn; move to \`planned/\` once scoped.
+- \`planned/\` — committed-to specs, ready to pick up.
+- \`in-progress/\` — actively being executed. Exactly one blueprint per lane.
+- \`completed/\` — execution finished and verified. Kept for reference.
+- \`parked/\` — intentionally paused. Include a reason in the spec's frontmatter.
+- \`archived/\` — superseded or abandoned. Not deleted — the record matters.
+
+## Authoring
+
+- Use \`docs/templates/blueprint.md\` as the starting point.
+- Blueprint YAML keys validated against \`docs/templates/blueprint.yaml\`.
+- For iterative refinement, load the \`plan-refine\` skill
+  (\`.agent/skills/plan-refine/SKILL.md\`).
+
+## Moving between states
+
+- \`draft → planned\`: the spec passes the plan-audit checklist
+  (\`.agent/guides/plan-audit-checklist.md\`).
+- \`planned → in-progress\`: work has started in a worktree or a lane.
+- \`in-progress → completed\`: all acceptance criteria verified.
+- Any state → \`archived\`: when the work is dropped or replaced.
+
+Move files with \`git mv\` so history follows the spec through its lifecycle.
+`;
+export function scaffoldBlueprints(input) {
+    const { repoRoot, options } = input;
+    const blueprintsDir = resolveScaffoldBlueprintsDir(repoRoot);
+    const results = [];
+    for (const state of BLUEPRINT_STATES) {
+        const stateDir = join(blueprintsDir, state);
+        const gitkeep = join(stateDir, '.gitkeep');
+        if (!options.dryRun) {
+            if (!existsSync(stateDir))
+                mkdirSync(stateDir, { recursive: true });
+            if (!existsSync(gitkeep))
+                writeFileSync(gitkeep, '');
+        }
+        results.push({
+            targetPath: gitkeep,
+            action: existsSync(gitkeep) ? 'identical' : options.dryRun ? 'skipped-dry' : 'created',
+        });
+    }
+    results.push(writeFileMerged(join(blueprintsDir, 'README.md'), BLUEPRINTS_README, options));
+    return results;
+}
+//# sourceMappingURL=scaffold-blueprints.js.map

package/dist/esm/cli/commands/init/scaffold-catalog-ignore.d.ts

@@ -0,0 +1,14 @@
+import type { MergeResult } from './merge.js';
+export interface ScaffoldCatalogIgnoreOptions {
+    cwd: string;
+    catalogDir: string;
+    dryRun?: boolean;
+    overwrite?: boolean;
+}
+export interface ScaffoldCatalogIgnoreResult {
+    results: readonly MergeResult[];
+    skillNames: readonly string[];
+    ruleNames: readonly string[];
+}
+export declare function scaffoldCatalogIgnore(opts: ScaffoldCatalogIgnoreOptions): ScaffoldCatalogIgnoreResult;
+//# sourceMappingURL=scaffold-catalog-ignore.d.ts.map

package/dist/esm/cli/commands/init/scaffold-catalog-ignore.js

@@ -0,0 +1,48 @@
+/**
+ * Scaffold a `.gitignore` block listing every catalog-shipped skill and rule
+ * name, so a consumer repo never accidentally tracks a duplicate of a
+ * canonical webpresso source under `agent-skills/<name>/` or
+ * `agent-rules/<name>.md`.
+ *
+ * Couples the consumer's `.gitignore` to the catalog snapshot at scaffold
+ * time. Re-run `wp setup` to pick up new catalog entries; the managed block
+ * is overwritten in-place.
+ *
+ * Consumer-authored skills/rules with names that DO NOT match a catalog
+ * entry remain trackable. A consumer-authored skill that collides with a
+ * catalog name will be ignored — that is the documented trade-off of this
+ * blanket-by-name strategy.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { patchGitignore } from './gitignore-patcher.js';
+function listCatalogSkills(catalogDir) {
+    const dir = join(catalogDir, 'agent', 'skills');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => !name.startsWith('.') && statSync(join(dir, name)).isDirectory())
+        .sort();
+}
+function listCatalogRules(catalogDir) {
+    const dir = join(catalogDir, 'agent', 'rules');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.endsWith('.md') && name !== 'README.md' && statSync(join(dir, name)).isFile())
+        .map((name) => name.replace(/\.md$/, ''))
+        .sort();
+}
+export function scaffoldCatalogIgnore(opts) {
+    const { cwd, catalogDir, dryRun, overwrite } = opts;
+    const mergeOpts = { dryRun, overwrite };
+    const skillNames = listCatalogSkills(catalogDir);
+    const ruleNames = listCatalogRules(catalogDir);
+    const patterns = [
+        ...skillNames.map((name) => `agent-skills/${name}/`),
+        ...ruleNames.map((name) => `agent-rules/${name}.md`),
+    ];
+    const result = patchGitignore(join(cwd, '.gitignore'), { id: 'catalog-installed', patterns }, mergeOpts);
+    return { results: [result], skillNames, ruleNames };
+}
+//# sourceMappingURL=scaffold-catalog-ignore.js.map

package/dist/esm/cli/commands/init/scaffold-docs.d.ts

@@ -0,0 +1,8 @@
+import { type MergeOptions, type MergeResult } from './merge.js';
+export interface ScaffoldDocsInput {
+    catalogDir: string;
+    repoRoot: string;
+    options: MergeOptions;
+}
+export declare function scaffoldDocs(input: ScaffoldDocsInput): MergeResult[];
+//# sourceMappingURL=scaffold-docs.d.ts.map

package/dist/esm/cli/commands/init/scaffold-docs.js

@@ -0,0 +1,15 @@
+/**
+ * Copy `catalog/docs/templates/` into the consumer's `docs/templates/`.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { copyDirectoryMerged } from './merge.js';
+export function scaffoldDocs(input) {
+    const { catalogDir, repoRoot, options } = input;
+    const src = join(catalogDir, 'docs', 'templates');
+    if (!existsSync(src))
+        return [];
+    const dst = join(repoRoot, 'docs', 'templates');
+    return copyDirectoryMerged(src, dst, options);
+}
+//# sourceMappingURL=scaffold-docs.js.map

package/dist/esm/cli/commands/init/scaffold-monorepo-nav.d.ts

@@ -0,0 +1,19 @@
+import type { ConsumerContext, WorkspacePackageInfo } from './detect-consumer.js';
+import { type MergeOptions, type MergeResult } from './merge.js';
+export interface ScaffoldMonorepoNavInput {
+    catalogDir: string;
+    repoRoot: string;
+    consumer: ConsumerContext;
+    options: MergeOptions;
+}
+export declare function renderPackagesTable(packages: readonly WorkspacePackageInfo[]): string;
+/**
+ * Infer coarse key locations from package naming. Always leaves a TODO so
+ * the human can refine. Never fabricates paths — only reports what we saw.
+ */
+export declare function renderKeyLocations(packages: readonly WorkspacePackageInfo[]): string;
+export declare function renderCrossPackageImports(packages: readonly WorkspacePackageInfo[]): string;
+export declare function renderPackageNames(packages: readonly WorkspacePackageInfo[]): string;
+export declare function renderTemplate(template: string, consumer: ConsumerContext): string;
+export declare function scaffoldMonorepoNav(input: ScaffoldMonorepoNavInput): MergeResult[];
+//# sourceMappingURL=scaffold-monorepo-nav.d.ts.map