@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/init/merge.d.ts

@@ -0,0 +1,33 @@
+export type MergeAction = 'created' | 'identical' | 'drifted' | 'overwritten' | 'skipped-dry';
+export type MergeOwnership = 'consumer-owned' | 'generated-whole-file';
+export interface MergeOptions {
+    overwrite?: boolean;
+    dryRun?: boolean;
+    ownership?: MergeOwnership;
+}
+export interface MergeResult {
+    targetPath: string;
+    action: MergeAction;
+    note?: string;
+}
+export declare function writeFileMerged(targetPath: string, incoming: string, opts?: MergeOptions): MergeResult;
+/**
+ * Copy a single file from the catalog to the consumer, applying merge policy.
+ */
+export declare function copyFileMerged(sourcePath: string, targetPath: string, opts?: MergeOptions): MergeResult;
+/**
+ * Recursively copy a directory. Applies merge policy to every file.
+ * Returns one MergeResult per file processed.
+ */
+export declare function copyDirectoryMerged(sourceDir: string, targetDir: string, opts?: MergeOptions): MergeResult[];
+/**
+ * Read, patch, and write a JSON file. The patcher receives the parsed object
+ * (or `{}` if the file doesn't exist) and returns the new object to write.
+ *
+ * Unlike raw template files, structured JSON patch targets are merged in-place:
+ * the patcher already preserves unknown fields, so reporting drift would strand
+ * required hook/config updates behind an extra manual merge step.
+ */
+export declare function patchJsonFile(targetPath: string, patcher: (existing: Record<string, unknown>) => Record<string, unknown>, opts?: MergeOptions): MergeResult;
+export declare function summarizeResults(results: readonly MergeResult[]): Record<MergeAction, number>;
+//# sourceMappingURL=merge.d.ts.map

package/dist/esm/cli/commands/init/merge.js

@@ -0,0 +1,111 @@
+/**
+ * Conflict policy for `wp init` file writes.
+ *
+ * Default: don't clobber consumer edits. If the target exists and differs
+ * from the incoming content, report drift and leave the file untouched. In
+ * overwrite mode: replace unconditionally. In dry-run: log the would-be change
+ * only.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function writeFileMerged(targetPath, incoming, opts = {}) {
+    const exists = existsSync(targetPath);
+    const existingContent = exists ? readFileSync(targetPath, 'utf8') : null;
+    if (!exists) {
+        if (opts.dryRun)
+            return { targetPath, action: 'skipped-dry' };
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, incoming);
+        return { targetPath, action: 'created' };
+    }
+    if (existingContent === incoming) {
+        return { targetPath, action: 'identical' };
+    }
+    const shouldOverwrite = opts.overwrite === true || opts.ownership === 'generated-whole-file';
+    if (shouldOverwrite) {
+        if (opts.dryRun)
+            return { targetPath, action: 'skipped-dry' };
+        writeFileSync(targetPath, incoming);
+        return { targetPath, action: 'overwritten' };
+    }
+    if (opts.dryRun)
+        return { targetPath, action: 'skipped-dry' };
+    return { targetPath, action: 'drifted' };
+}
+/**
+ * Copy a single file from the catalog to the consumer, applying merge policy.
+ */
+export function copyFileMerged(sourcePath, targetPath, opts = {}) {
+    const incoming = readFileSync(sourcePath, 'utf8');
+    return writeFileMerged(targetPath, incoming, opts);
+}
+/**
+ * Recursively copy a directory. Applies merge policy to every file.
+ * Returns one MergeResult per file processed.
+ */
+export function copyDirectoryMerged(sourceDir, targetDir, opts = {}) {
+    const results = [];
+    if (!existsSync(sourceDir))
+        return results;
+    const stack = [{ src: sourceDir, dst: targetDir }];
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (!entry)
+            break;
+        const { src, dst } = entry;
+        if (!opts.dryRun)
+            mkdirSync(dst, { recursive: true });
+        const items = readdirSync(src);
+        for (const item of items) {
+            const srcFull = join(src, item);
+            const dstFull = join(dst, item);
+            const st = statSync(srcFull);
+            if (st.isDirectory()) {
+                stack.push({ src: srcFull, dst: dstFull });
+            }
+            else if (st.isFile()) {
+                results.push(copyFileMerged(srcFull, dstFull, opts));
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Read, patch, and write a JSON file. The patcher receives the parsed object
+ * (or `{}` if the file doesn't exist) and returns the new object to write.
+ *
+ * Unlike raw template files, structured JSON patch targets are merged in-place:
+ * the patcher already preserves unknown fields, so reporting drift would strand
+ * required hook/config updates behind an extra manual merge step.
+ */
+export function patchJsonFile(targetPath, patcher, opts = {}) {
+    const exists = existsSync(targetPath);
+    const existing = exists
+        ? JSON.parse(readFileSync(targetPath, 'utf8'))
+        : {};
+    const patched = patcher(existing);
+    const incoming = `${JSON.stringify(patched, null, 2)}\n`;
+    const existingContent = exists ? readFileSync(targetPath, 'utf8') : null;
+    if (existingContent === incoming) {
+        return { targetPath, action: 'identical' };
+    }
+    if (opts.dryRun) {
+        return { targetPath, action: 'skipped-dry' };
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, incoming);
+    return { targetPath, action: exists ? 'overwritten' : 'created' };
+}
+export function summarizeResults(results) {
+    const summary = {
+        created: 0,
+        identical: 0,
+        drifted: 0,
+        overwritten: 0,
+        'skipped-dry': 0,
+    };
+    for (const r of results)
+        summary[r.action]++;
+    return summary;
+}
+//# sourceMappingURL=merge.js.map

package/dist/esm/cli/commands/init/preflight.d.ts

@@ -0,0 +1,15 @@
+export interface PreflightResult {
+    ok: boolean;
+    score: number;
+    warnings: readonly string[];
+}
+export declare const DOCS_URL = "https://github.com/webpresso/webpresso/blob/main/docs/is-webpresso-for-me.md";
+/**
+ * Run the 5-point compatibility preflight.
+ *
+ * @param repoRoot - Absolute path to the consumer repo root.
+ * @param strict   - When true, `ok` is false if any check fails.
+ *                   When false, `ok` is always true (warn-only mode).
+ */
+export declare function runPreflight(repoRoot: string, strict: boolean): Promise<PreflightResult>;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/esm/cli/commands/init/preflight.js

@@ -0,0 +1,87 @@
+/**
+ * Soft compatibility preflight for `wp setup`.
+ *
+ * Checks the 5-point compatibility matrix from docs/is-webpresso-for-me.md.
+ * In non-strict mode: warns and continues. In strict mode: aborts on mismatch.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { resolveBlueprintRoot } from '#utils/blueprint-root';
+export const DOCS_URL = 'https://github.com/webpresso/webpresso/blob/main/docs/is-webpresso-for-me.md';
+/**
+ * Returns the major version number from a semver string like "24.0.0" or "v24.0.0".
+ * Returns null when the string is not parseable.
+ */
+function parseMajor(version) {
+    const cleaned = version.startsWith('v') ? version.slice(1) : version;
+    const major = parseInt(cleaned.split('.')[0] ?? '', 10);
+    return isNaN(major) ? null : major;
+}
+function checkTypeScriptWorkspace(repoRoot) {
+    const hasConfig = existsSync(join(repoRoot, 'tsconfig.json'));
+    if (!hasConfig) {
+        return 'tsconfig.json not found at repo root — TypeScript workspace required (see docs)';
+    }
+    const nodeMajor = parseMajor(process.version);
+    if (nodeMajor === null || nodeMajor < 24) {
+        return `Node ${process.version} detected — Node ≥ 24 required (see docs)`;
+    }
+    return null;
+}
+function checkVp() {
+    const result = spawnSync('vp', ['--version'], { encoding: 'utf8' });
+    if (result.error !== undefined || (result.status !== null && result.status !== 0)) {
+        return 'vp not found on PATH — install Vite+ and use vp as the package-command facade (see docs)';
+    }
+    return null;
+}
+function checkWorkersOrVite(repoRoot) {
+    const hasWrangler = existsSync(join(repoRoot, 'wrangler.toml'));
+    const hasVite = existsSync(join(repoRoot, 'vite.config.ts'));
+    if (!hasWrangler && !hasVite) {
+        return 'Neither wrangler.toml nor vite.config.ts found at repo root — Workers or Vite project required (see docs)';
+    }
+    return null;
+}
+function checkBlueprintLifecycle(repoRoot) {
+    const blueprintRoot = resolveBlueprintRoot(repoRoot);
+    if (!existsSync(blueprintRoot)) {
+        const displayPath = relative(repoRoot, blueprintRoot).replaceAll('\\', '/') || 'blueprints';
+        return `${displayPath}/ directory not found — blueprint lifecycle required (run \`wp setup --with base-kit\` to scaffold it)`;
+    }
+    return null;
+}
+function checkLoreCommitProtocol(repoRoot) {
+    if (!existsSync(join(repoRoot, '.agent'))) {
+        return '.agent/ directory not found — lore commit protocol required (run `wp setup --with lore-commits` to scaffold it)';
+    }
+    return null;
+}
+/**
+ * Run the 5-point compatibility preflight.
+ *
+ * @param repoRoot - Absolute path to the consumer repo root.
+ * @param strict   - When true, `ok` is false if any check fails.
+ *                   When false, `ok` is always true (warn-only mode).
+ */
+export async function runPreflight(repoRoot, strict) {
+    const checks = [
+        () => checkTypeScriptWorkspace(repoRoot),
+        () => checkVp(),
+        () => checkWorkersOrVite(repoRoot),
+        () => checkBlueprintLifecycle(repoRoot),
+        () => checkLoreCommitProtocol(repoRoot),
+    ];
+    const warnings = [];
+    for (const check of checks) {
+        const warning = check();
+        if (warning !== null) {
+            warnings.push(warning);
+        }
+    }
+    const score = checks.length - warnings.length;
+    const ok = strict ? warnings.length === 0 : true;
+    return { ok, score, warnings };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/esm/cli/commands/init/prompts.d.ts

@@ -0,0 +1,24 @@
+export declare const TIER3_SKILLS: readonly ["base-kit", "tanstack-query", "better-auth-best-practices", "react-doctor", "frontend-design", "web-design-guidelines", "vercel-react-best-practices"];
+export type Tier3Skill = (typeof TIER3_SKILLS)[number];
+export interface ResolveSkillsInput {
+    withFlag?: string;
+    withoutFlag?: string;
+    allFlag?: boolean;
+    yesFlag?: boolean;
+    existing?: readonly string[];
+    isTTY?: boolean;
+    inputStream?: NodeJS.ReadableStream;
+    outputStream?: NodeJS.WritableStream;
+}
+export interface ResolveSkillsResult {
+    selected: string[];
+    aborted: boolean;
+    source: 'all' | 'with' | 'existing' | 'interactive' | 'default';
+}
+export declare function parseWithFlag(raw: string | undefined): string[];
+export declare function validateTier3Names(names: readonly string[]): {
+    valid: string[];
+    invalid: string[];
+};
+export declare function resolveTier3Selection(input: ResolveSkillsInput): Promise<ResolveSkillsResult>;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/esm/cli/commands/init/prompts.js

@@ -0,0 +1,126 @@
+/**
+ * Tier-3 skill selection — `--with`, `--all`, and an optional TTY prompt.
+ *
+ * Kept deliberately minimal: we don't pull in an interactive prompt library.
+ * If the user runs `wp init` in a TTY without flags, we use `node:readline/promises`
+ * to ask a single yes/no per Tier-3 skill. If stdin isn't a TTY and no flags
+ * are provided, we default to installing the `base-kit` Tier-3 bootstrap.
+ * `base-kit` is default-on for every selection mode; use `--without base-kit`
+ * to opt out explicitly.
+ */
+import { createInterface } from 'node:readline/promises';
+export const TIER3_SKILLS = [
+    'base-kit',
+    'tanstack-query',
+    'better-auth-best-practices',
+    'react-doctor',
+    'frontend-design',
+    'web-design-guidelines',
+    'vercel-react-best-practices',
+];
+const DEFAULT_TIER3_SKILLS = ['base-kit'];
+export function parseWithFlag(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function validateTier3Names(names) {
+    const valid = [];
+    const invalid = [];
+    const allowed = new Set(TIER3_SKILLS);
+    for (const name of names) {
+        if (allowed.has(name))
+            valid.push(name);
+        else
+            invalid.push(name);
+    }
+    return { valid, invalid };
+}
+function validateWithoutFlag(raw) {
+    const requested = parseWithFlag(raw);
+    const { valid, invalid } = validateTier3Names(requested);
+    if (invalid.length > 0) {
+        throw new Error(`Unknown Tier-3 skills in --without: ${invalid.join(', ')}\nAvailable: ${TIER3_SKILLS.join(', ')}`);
+    }
+    return valid;
+}
+function defaultOnUnlessOptedOut(selected, withoutFlag) {
+    const without = new Set(validateWithoutFlag(withoutFlag));
+    const withDefault = new Set([...DEFAULT_TIER3_SKILLS, ...selected]);
+    for (const skill of without)
+        withDefault.delete(skill);
+    return TIER3_SKILLS.filter((skill) => withDefault.has(skill));
+}
+export async function resolveTier3Selection(input) {
+    if (input.allFlag) {
+        return {
+            selected: defaultOnUnlessOptedOut(TIER3_SKILLS, input.withoutFlag),
+            aborted: false,
+            source: 'all',
+        };
+    }
+    if (input.withFlag !== undefined) {
+        const requested = parseWithFlag(input.withFlag);
+        const { valid, invalid } = validateTier3Names(requested);
+        if (invalid.length > 0) {
+            throw new Error(`Unknown Tier-3 skills: ${invalid.join(', ')}\nAvailable: ${TIER3_SKILLS.join(', ')}`);
+        }
+        return {
+            selected: defaultOnUnlessOptedOut(valid, input.withoutFlag),
+            aborted: false,
+            source: 'with',
+        };
+    }
+    if (input.existing && input.existing.length > 0) {
+        const { valid } = validateTier3Names(input.existing);
+        return {
+            selected: defaultOnUnlessOptedOut(valid, input.withoutFlag),
+            aborted: false,
+            source: 'existing',
+        };
+    }
+    if (input.yesFlag || !input.isTTY) {
+        return {
+            selected: defaultOnUnlessOptedOut([], input.withoutFlag),
+            aborted: false,
+            source: 'default',
+        };
+    }
+    const result = await interactivePrompt(input);
+    return {
+        ...result,
+        selected: defaultOnUnlessOptedOut(result.selected, input.withoutFlag),
+    };
+}
+async function interactivePrompt(input) {
+    const rl = createInterface({
+        input: input.inputStream ?? process.stdin,
+        output: input.outputStream ?? process.stdout,
+    });
+    const selected = [];
+    try {
+        ;
+        (input.outputStream ?? process.stdout).write('Tier-3 skill selection (press Enter to skip, y to include, q to abort):\n');
+        for (const skill of TIER3_SKILLS) {
+            if (skill === 'base-kit') {
+                selected.push(skill);
+                (input.outputStream ?? process.stdout).write('  base-kit is default-on; pass --without base-kit to opt out.\n');
+                continue;
+            }
+            const answer = (await rl.question(`  include ${skill}? [y/N/q] `)).trim().toLowerCase();
+            if (answer === 'q') {
+                return { selected: [], aborted: true, source: 'interactive' };
+            }
+            if (answer === 'y' || answer === 'yes')
+                selected.push(skill);
+        }
+        return { selected, aborted: false, source: 'interactive' };
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=prompts.js.map

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

@@ -0,0 +1,11 @@
+import { type MergeResult } from './merge.js';
+export interface ScaffoldAgentRulesOptions {
+    cwd: string;
+    dryRun?: boolean;
+    overwrite?: boolean;
+}
+export interface ScaffoldAgentRulesResult {
+    results: readonly MergeResult[];
+}
+export declare function scaffoldAgentRules(opts: ScaffoldAgentRulesOptions): ScaffoldAgentRulesResult;
+//# sourceMappingURL=scaffold-agent-rules.d.ts.map

package/dist/esm/cli/commands/init/scaffold-agent-rules.js

@@ -0,0 +1,58 @@
+/**
+ * Scaffold `agent-rules/` — consumer-owned canonical rules directory whose
+ * contents are projected into the various AI surfaces (`.agent/rules/`,
+ * `.cursor/rules/`, etc.) by the symlink/sync layer. Source-of-truth lives in
+ * `agent-rules/` and is committed; the projected surfaces are gitignored.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { patchGitignore } from './gitignore-patcher.js';
+import { writeFileMerged } from './merge.js';
+const AGENT_RULES_README = `# agent-rules/
+
+This directory holds consumer-owned **agent rules** — the canonical source
+of behavioural guidelines that get projected into per-tool surfaces
+(\`.agent/rules/\`, \`.cursor/rules/\`, \`.windsurf/rules/\`, etc.) by
+\`wp sync\`.
+
+## Authoring
+
+- Add a new rule with \`wp rule new <slug>\`.
+- Each rule is a markdown file with frontmatter (\`title\`, \`scope\`).
+- Edit files here — never the projected copies under \`.agent/\` etc.
+
+## Lifecycle
+
+- Files in \`agent-rules/\` are committed.
+- Projected surfaces (\`.agent/rules/\`, \`.cursor/rules/\`, …) are gitignored.
+- Run \`wp sync\` after editing to refresh derived surfaces.
+`;
+const RULE_IGNORE_PATTERNS = [
+    '.agent/rules/',
+    '.cursor/rules/',
+    '.windsurf/rules/',
+    '.claude/rules/',
+    '.gemini/commands/',
+];
+export function scaffoldAgentRules(opts) {
+    const { cwd, dryRun, overwrite } = opts;
+    const mergeOpts = { dryRun, overwrite };
+    const dir = join(cwd, 'agent-rules');
+    const gitkeep = join(dir, '.gitkeep');
+    const results = [];
+    const gitkeepExisted = existsSync(gitkeep);
+    if (!dryRun) {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        if (!gitkeepExisted)
+            writeFileSync(gitkeep, '');
+    }
+    results.push({
+        targetPath: gitkeep,
+        action: gitkeepExisted ? 'identical' : dryRun ? 'skipped-dry' : 'created',
+    });
+    results.push(writeFileMerged(join(dir, 'README.md'), AGENT_RULES_README, mergeOpts));
+    results.push(patchGitignore(join(cwd, '.gitignore'), { id: 'rule-sync', patterns: [...RULE_IGNORE_PATTERNS] }, mergeOpts));
+    return { results };
+}
+//# sourceMappingURL=scaffold-agent-rules.js.map

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

@@ -0,0 +1,11 @@
+import { type MergeResult } from './merge.js';
+export interface ScaffoldAgentSkillsOptions {
+    cwd: string;
+    dryRun?: boolean;
+    overwrite?: boolean;
+}
+export interface ScaffoldAgentSkillsResult {
+    results: readonly MergeResult[];
+}
+export declare function scaffoldAgentSkills(opts: ScaffoldAgentSkillsOptions): ScaffoldAgentSkillsResult;
+//# sourceMappingURL=scaffold-agent-skills.d.ts.map

package/dist/esm/cli/commands/init/scaffold-agent-skills.js

@@ -0,0 +1,58 @@
+/**
+ * Scaffold `agent-skills/` — consumer-owned canonical skills directory whose
+ * contents are projected into the various AI surfaces (`.agent/skills/`,
+ * `.cursor/skills/`, `.claude/skills/`, etc.) by the symlink/sync layer.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { patchGitignore } from './gitignore-patcher.js';
+import { writeFileMerged } from './merge.js';
+const AGENT_SKILLS_README = `# agent-skills/
+
+This directory holds consumer-owned **agent skills** — the canonical source
+of executable skill definitions that get projected into per-tool surfaces
+(\`.agent/skills/\`, \`.cursor/skills/\`, \`.claude/skills/\`, etc.) by
+\`wp sync\`.
+
+## Authoring
+
+- Add a new skill with \`wp skill new <slug>\`.
+- Each skill is a directory with a \`SKILL.md\` and optional supporting files.
+- Edit files here — never the projected copies under \`.agent/\` etc.
+
+## Lifecycle
+
+- Files in \`agent-skills/\` are committed.
+- Projected surfaces (\`.agent/skills/\`, \`.claude/skills/\`, …) are gitignored.
+- Run \`wp sync\` after editing to refresh derived surfaces.
+`;
+const SKILL_IGNORE_PATTERNS = [
+    '.agent/skills/',
+    '.cursor/skills/',
+    '.windsurf/skills/',
+    '.claude/skills/',
+    '.gemini/commands/',
+    '.agents/skills/',
+];
+export function scaffoldAgentSkills(opts) {
+    const { cwd, dryRun, overwrite } = opts;
+    const mergeOpts = { dryRun, overwrite };
+    const dir = join(cwd, 'agent-skills');
+    const gitkeep = join(dir, '.gitkeep');
+    const results = [];
+    const gitkeepExisted = existsSync(gitkeep);
+    if (!dryRun) {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        if (!gitkeepExisted)
+            writeFileSync(gitkeep, '');
+    }
+    results.push({
+        targetPath: gitkeep,
+        action: gitkeepExisted ? 'identical' : dryRun ? 'skipped-dry' : 'created',
+    });
+    results.push(writeFileMerged(join(dir, 'README.md'), AGENT_SKILLS_README, mergeOpts));
+    results.push(patchGitignore(join(cwd, '.gitignore'), { id: 'skill-sync', patterns: [...SKILL_IGNORE_PATTERNS] }, mergeOpts));
+    return { results };
+}
+//# sourceMappingURL=scaffold-agent-skills.js.map

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

@@ -0,0 +1,15 @@
+import { type MergeOptions, type MergeResult } from './merge.js';
+export declare const TIER1_SKILLS: readonly ["fix", "verify", "testing-philosophy", "plan-refine", "pll"];
+export declare const TIER2_SKILLS: readonly ["systematic-debugging", "test-driven-development", "deep-research"];
+/** Always-installed skill (rendered separately). Excluded from the generic copy. */
+export declare const RENDERED_SKILLS: readonly ["monorepo-navigation"];
+export interface ScaffoldAgentInput {
+    catalogDir: string;
+    repoRoot: string;
+    options: MergeOptions;
+}
+export interface ScaffoldAgentReport {
+    results: MergeResult[];
+}
+export declare function scaffoldAgent(input: ScaffoldAgentInput): ScaffoldAgentReport;
+//# sourceMappingURL=scaffold-agent.d.ts.map

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

@@ -0,0 +1,63 @@
+/**
+ * Copy `catalog/agent/` into the consumer's `.agent/`, honouring tier rules.
+ *
+ * Wave-3 narrowing: rules and skills are NO LONGER copied here. They flow
+ * exclusively through the `agent-rules/` / `agent-skills/` consumer-owned
+ * scaffolders + `runUnifiedSync` projection. This module now only handles
+ * commands, workflows, guides, and the top-level catalog README.
+ *
+ * Tier exports remain because the init orchestrator uses them to compute
+ * the allowed-skill set passed to the unified sync filter.
+ *
+ * - Tier-1 (fix, verify, testing-philosophy, plan-refine, pll) — always.
+ * - Tier-2 (systematic-debugging, test-driven-development, deep-research) — always.
+ * - monorepo-navigation — always (rendered via a separate scaffold step).
+ * - Tier-3 — only on opt-in via --with / --all / interactive prompt.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { copyDirectoryMerged, copyFileMerged, } from './merge.js';
+export const TIER1_SKILLS = ['fix', 'verify', 'testing-philosophy', 'plan-refine', 'pll'];
+export const TIER2_SKILLS = [
+    'systematic-debugging',
+    'test-driven-development',
+    'deep-research',
+];
+/** Always-installed skill (rendered separately). Excluded from the generic copy. */
+export const RENDERED_SKILLS = ['monorepo-navigation'];
+const ALWAYS_COPY_SUBDIRS = ['commands', 'workflows', 'guides'];
+const GENERATED_WHOLE_FILE = { ownership: 'generated-whole-file' };
+/** Top-level catalog files emitted once on fresh setup (never overwritten). */
+const FRESH_COPY_FILES = ['correlate.allow.yaml'];
+export function scaffoldAgent(input) {
+    const { catalogDir, repoRoot, options } = input;
+    const catalogAgent = join(catalogDir, 'agent');
+    const targetAgent = join(repoRoot, '.agent');
+    const results = [];
+    for (const subdir of ALWAYS_COPY_SUBDIRS) {
+        const src = join(catalogAgent, subdir);
+        const dst = join(targetAgent, subdir);
+        if (existsSync(src)) {
+            results.push(...copyDirectoryMerged(src, dst, { ...options, ...GENERATED_WHOLE_FILE }));
+        }
+    }
+    // Top-level catalog README is a generated surface owned by webpresso.
+    const topReadme = join(catalogAgent, 'README.md');
+    if (existsSync(topReadme)) {
+        results.push(copyFileMerged(topReadme, join(targetAgent, 'README.md'), {
+            ...options,
+            ...GENERATED_WHOLE_FILE,
+        }));
+    }
+    // Fresh-only top-level files — emitted once to the consumer's .agent/.
+    // These are committed to the consumer repo (not gitignored) so cloud agents
+    // and CI can read them. Only written on first setup (absent = fresh).
+    for (const file of FRESH_COPY_FILES) {
+        const src = join(catalogAgent, file);
+        if (existsSync(src)) {
+            results.push(copyFileMerged(src, join(targetAgent, file), options));
+        }
+    }
+    return { results };
+}
+//# sourceMappingURL=scaffold-agent.js.map

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

@@ -0,0 +1,16 @@
+import type { AgentkitConfig } from './config.js';
+import type { ConsumerContext } from './detect-consumer.js';
+import { type MergeOptions, type MergeResult } from './merge.js';
+export declare function renderRepositoryMap(consumer: ConsumerContext): string;
+export declare function renderTechStack(consumer: ConsumerContext): string;
+export interface ScaffoldAgentsMdInput {
+    catalogDir: string;
+    repoRoot: string;
+    consumer: ConsumerContext;
+    config: AgentkitConfig;
+    options: MergeOptions;
+}
+export declare function mergeRenderedAgentsMd(rendered: string, existing: string): string | null;
+export declare function renderAgentsMd(template: string, consumer: ConsumerContext, config: AgentkitConfig): string;
+export declare function scaffoldAgentsMd(input: ScaffoldAgentsMdInput): MergeResult | null;
+//# sourceMappingURL=scaffold-agents-md.d.ts.map