picopilot 0.0.0 → 0.1.1

package/src/engine/skills/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The skills-install engine behind `picopilot init --install-skills`, the one
+ * picopilot path that writes to a shared/global location. Every install-target
+ * knob is a parameter here so tests redirect it to a temp dir and the real agent
+ * skill dirs stay byte-untouched. See `skills.ts` for the isolation contract.
+ */
+export {
+	installSkills,
+	type InstallSkillsOptions,
+	type InstallSkillsResult,
+	SKILL_NAMES,
+	skillsSourceDir,
+	type WiredAgent,
+} from './skills.js';

package/src/engine/skills/skills.test.ts

@@ -0,0 +1,376 @@
+import {execFileSync} from 'node:child_process';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+} from 'node:fs';
+import {homedir, tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {createCli} from '../../cli.js';
+import {installSkills, SKILL_NAMES, skillsSourceDir} from './index.js';
+
+/**
+ * Reads an authored skill's SKILL.md straight from the on-disk source dir, the
+ * same files incur's `include` glob ships. Skill GENERATION output is these
+ * files, so the generation tests assert against them directly.
+ */
+function readSkill(name: string): string {
+	return readFileSync(join(skillsSourceDir(), name, 'SKILL.md'), 'utf8');
+}
+
+describe('picopilot skills: generation output (the authored discipline skills)', () => {
+	it('ships exactly the named authored skills, each with valid frontmatter', () => {
+		expect([...SKILL_NAMES].sort()).toEqual(
+			[
+				'picopilot-art',
+				'picopilot-audio',
+				'picopilot-code',
+				'picopilot-debug',
+				'picopilot-overview',
+				'game-design-reference',
+				'game-jam',
+			].sort(),
+		);
+		for (const name of SKILL_NAMES) {
+			const md = readSkill(name);
+			// incur discovers a skill by its `name:` frontmatter line; a `description:`
+			// is what makes it load on-demand. Both must be present and match.
+			expect(md).toMatch(new RegExp(`^name:\\s*${name}$`, 'm'));
+			expect(md).toMatch(/^description:\s*.+/m);
+		}
+	});
+
+	it('game-design-reference is a USER-INVOKED reference body (no per-turn context load)', () => {
+		const md = readSkill('game-design-reference');
+		// The invocation stance: only game-design-reference disables model
+		// invocation, so it is reached by pointer (from game-jam), never fired on a
+		// vague trigger, and costs no context every turn. game-jam stays
+		// model-invoked (no such line).
+		expect(md).toMatch(/^disable-model-invocation:\s*true$/m);
+		expect(readSkill('game-jam')).not.toMatch(/^disable-model-invocation:/m);
+	});
+
+	it('game-design-reference carries the universal principles + method-not-menu originality', () => {
+		const md = readSkill('game-design-reference');
+		// Fairness: BOTH reachability AND the skipped hazard-avoidability check.
+		expect(md.toLowerCase()).toContain('reachability');
+		expect(md.toLowerCase()).toContain('avoidability');
+		// Human reaction budget in PICO-8's 30fps terms.
+		expect(md).toContain('200-300ms');
+		expect(md).toContain('frame-perfect');
+		// Visibility (draw what you spr()).
+		expect(md).toContain('spr(');
+		// Originality is a METHOD with a self-check, and lists NO concrete
+		// mechanics (the answer-menu trap). Assert the caveat that guards it.
+		expect(md.toLowerCase()).toContain('self-check');
+		expect(md.toLowerCase()).toMatch(/no (example |concrete )?mechanic/);
+		// Progression as a universal principle: a game GOES SOMEWHERE, expressed
+		// as a ladder of FORMS (ramp -> waves -> levels -> worlds). The situated
+		// "how far up given the clock" call lives in game-jam, not here.
+		expect(md.toLowerCase()).toContain('progression');
+		expect(md.toLowerCase()).toContain('goes somewhere');
+		expect(md.toLowerCase()).toContain('waves');
+		expect(md.toLowerCase()).toMatch(/worlds/);
+	});
+
+	it('game-jam carries the clock discipline and POINTS AT game-design-reference (does not re-teach it)', () => {
+		const md = readSkill('game-jam');
+		// Composition: it points at the reference body by name.
+		expect(md).toContain('game-design-reference');
+		// REGRESSION GUARD (see the FLIPRUN observation + re-grill): a
+		// disable-model-invocation reference skill is NOT auto-loaded by pi, so a
+		// bare-name "read and apply X" pointer gets SKIPPED (the agent never opens
+		// the file). The reliable pattern (Matt's, verified on pi + Claude Code) is
+		// an EXPLICIT relative path resolved against THIS skill's dir + an
+		// imperative to read/load it. Assert the pointer has both, so it never
+		// regresses to the weak wording that made the reference body unreachable.
+		expect(md).toContain('../game-design-reference/SKILL.md');
+		expect(md.toLowerCase()).toMatch(/\b(read|load)\b/);
+		// And game-design-reference stays user-invoked (the reason the explicit
+		// pointer is REQUIRED): if someone flips it to model-invoked, this pairing
+		// assumption changes and the pointer guard should be revisited.
+		expect(readSkill('game-design-reference')).toMatch(
+			/^disable-model-invocation:\s*true$/m,
+		);
+		// The jam-specific clock discipline (the slice/deepen/triage phases).
+		expect(md.toLowerCase()).toContain('playable slice');
+		expect(md.toLowerCase()).toContain('triage');
+		// The situated design calls the clock forces (jam-specific, live nowhere
+		// else): the dead state and the frame-perfect superhuman level.
+		expect(md.toLowerCase()).toContain('dead state');
+		expect(md).toContain('frame-perfect');
+		// Budget-scaled ambition (grilled: one skill, no per-tier files): scale to
+		// the clock, reach up the progression ladder as far as you can FINISH,
+		// deepen > polish on a long budget. Intent-framed, not a level-count menu.
+		expect(md.toLowerCase()).toContain('scale your ambition');
+		expect(md.toLowerCase()).toContain('progression ladder');
+		expect(md.toLowerCase()).toMatch(/finish/);
+		// It interprets the theme itself (decision B) and ships JAM.md.
+		expect(md).toContain('JAM.md');
+	});
+
+	it('picopilot-overview carries the #include discipline', () => {
+		const md = readSkill('picopilot-overview');
+		expect(md).toContain('#include main.lua');
+		expect(md).toContain('main.lua');
+		// Edit the Lua, never the binary sections (allow line wrapping between words).
+		expect(md).toMatch(/never\s+hand-write/i);
+		expect(md).toContain('__gfx__');
+	});
+
+	it('picopilot-code carries the token-breakdown discipline', () => {
+		const md = readSkill('picopilot-code');
+		expect(md).toContain('8,192');
+		expect(md).toContain('picopilot tokens');
+		expect(md).toContain('picopilot minify');
+		// A PICO-8 shorthand the skill teaches for reclaiming budget.
+		expect(md).toContain('+=');
+	});
+
+	it('picopilot-art carries the render→look→set→render loop AND the non-multimodal fallback', () => {
+		const md = readSkill('picopilot-art');
+		// The art loop.
+		expect(md).toContain('gfx render');
+		expect(md).toContain('gfx set');
+		expect(md).toContain('gfx show');
+		// The load-bearing non-multimodal fallback: view the PNG if you can read
+		// images, else reason over the grid.
+		expect(md.toLowerCase()).toContain('cannot read images');
+		expect(md.toLowerCase()).toMatch(/reason(ing)?\s+over the[\s\S]*grid/i);
+		// The gfx/map overlap smart-refuse discipline.
+		expect(md.toLowerCase()).toContain('overlap');
+		expect(md).toContain('allowMapOverlap');
+	});
+
+	it('picopilot-audio carries the picopilot-MML authoring model + the honest record-based render framing', () => {
+		const md = readSkill('picopilot-audio');
+		expect(md).toContain('picopilot-MML');
+		// ABC is explicitly NOT used.
+		expect(md).toContain('ABC');
+		// Music is assembled structurally from SFX references.
+		expect(md.toLowerCase()).toContain('structural');
+		// Honest scoping (ADR-0009): audio-to-WAV is a RECORDING, NOT an offline
+		// export, and needs a real audio session (a developer machine).
+		expect(md.toLowerCase()).toContain('recording');
+		expect(md.toLowerCase()).toContain('offline export');
+	});
+
+	it('picopilot-debug carries the static-gate + run loop and the dependency boundaries', () => {
+		const md = readSkill('picopilot-debug');
+		expect(md).toContain('picopilot verify');
+		expect(md).toContain('picopilot run');
+		expect(md).toContain('printh');
+		expect(md).toContain('gate-incapable');
+		expect(md).toContain('pico8-not-found');
+		expect(md).toContain('shrinko-not-found');
+	});
+});
+
+/**
+ * Recursively snapshots a directory tree as a sorted list of `relpath:mtimeMs`
+ * for files and `relpath/` for dirs, so a before/after comparison catches ANY
+ * new/removed entry AND any modified file. Returns `['<absent>']` when the dir
+ * does not exist (so "absent stays absent" is also asserted).
+ */
+function snapshot(root: string): string[] {
+	if (!existsSync(root)) return ['<absent>'];
+	const out: string[] = [];
+	const walk = (dir: string, rel: string) => {
+		for (const entry of readdirSync(dir, {withFileTypes: true}).sort((a, b) =>
+			a.name.localeCompare(b.name),
+		)) {
+			const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+			const abs = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				out.push(`${relPath}/`);
+				walk(abs, relPath);
+			} else {
+				// lstat, not stat: never follow a symlink out of the snapshotted tree.
+				out.push(
+					`${relPath}:${statSync(abs, {throwIfNoEntry: false})?.mtimeMs ?? 'gone'}`,
+				);
+			}
+		}
+	};
+	walk(root, '');
+	return out;
+}
+
+/**
+ * The REAL agent skill dirs this test must prove are byte-untouched. incur
+ * installs canonically to `~/.agents/skills` and symlinks detected non-universal
+ * agents (e.g. `~/.claude/skills`), so those are the dirs the isolation contract
+ * guards. Resolved from the real `homedir()` (which is what incur reads).
+ */
+const REAL_DIRS = [
+	join(homedir(), '.agents', 'skills'),
+	join(homedir(), '.claude', 'skills'),
+	join(homedir(), '.codex', 'skills'),
+	join(homedir(), '.cursor', 'skills'),
+];
+
+describe('picopilot skills: isolated --install-skills (the load-bearing shared-write test)', () => {
+	let target: string;
+	let before: Map<string, string[]>;
+
+	beforeEach(() => {
+		target = mkdtempSync(join(tmpdir(), 'picopilot-skills-install-'));
+		// Snapshot the REAL dirs before the install so we can prove they never moved.
+		before = new Map(REAL_DIRS.map((d) => [d, snapshot(d)]));
+	});
+
+	afterEach(() => {
+		try {
+			execFileSync('rm', ['-rf', target]);
+		} catch {
+			// ignore
+		}
+	});
+
+	it('installs into the redirected temp target, NOT a real dir', async () => {
+		// The lever: global=false + cwd=temp installs under <cwd>/.agents/skills.
+		const result = await installSkills({
+			cli: createCli(),
+			global: false,
+			cwd: target,
+		});
+
+		// Every named discipline skill landed (plus the per-command skills).
+		for (const name of SKILL_NAMES) {
+			expect(result.skills).toContain(name);
+			expect(
+				existsSync(join(target, '.agents', 'skills', name, 'SKILL.md')),
+			).toBe(true);
+		}
+		// Every reported canonical path is INSIDE the temp target.
+		for (const p of result.paths) {
+			expect(p.startsWith(target)).toBe(true);
+		}
+		// Any wired non-universal agent dir is also inside the temp target, never a
+		// real home dir (the symlinks go under cwd for a project install).
+		for (const a of result.agents) {
+			expect(a.path.startsWith(target)).toBe(true);
+		}
+	});
+
+	it('leaves the REAL agent skill dirs BYTE-UNTOUCHED', async () => {
+		await installSkills({cli: createCli(), global: false, cwd: target});
+
+		// The real dirs are identical before and after: no new entry, nothing
+		// modified, and an absent dir stays absent. This is the pollution guard.
+		for (const dir of REAL_DIRS) {
+			expect(snapshot(dir)).toEqual(before.get(dir));
+		}
+	});
+
+	it('a custom sourceDir proves the source is decoupled from the install target', async () => {
+		// Point the include SOURCE at a fixture with a single skill; install TARGET
+		// stays the temp dir. Only that fixture's authored skill (plus the
+		// per-command skills) should appear, proving cwd and source are independent.
+		const source = mkdtempSync(join(tmpdir(), 'picopilot-skills-src-'));
+		try {
+			const skillDir = join(source, 'picopilot-fixture');
+			execFileSync('mkdir', ['-p', skillDir]);
+			execFileSync('sh', [
+				'-c',
+				`printf '%s\\n' '---' 'name: picopilot-fixture' 'description: A fixture skill.' '---' '# fixture' > ${JSON.stringify(join(skillDir, 'SKILL.md'))}`,
+			]);
+
+			const result = await installSkills({
+				cli: createCli(),
+				global: false,
+				cwd: target,
+				sourceDir: source,
+			});
+
+			expect(result.skills).toContain('picopilot-fixture');
+			// The real authored discipline skills are NOT pulled in from this source.
+			expect(result.skills).not.toContain('picopilot-overview');
+			// Still installed into the temp target, and the real dirs stay untouched.
+			expect(
+				existsSync(
+					join(target, '.agents', 'skills', 'picopilot-fixture', 'SKILL.md'),
+				),
+			).toBe(true);
+			for (const dir of REAL_DIRS) {
+				expect(snapshot(dir)).toEqual(before.get(dir));
+			}
+		} finally {
+			execFileSync('rm', ['-rf', source]);
+		}
+	});
+
+	it('ships skill RESOURCE files, not just SKILL.md (incur 0.4.10 workaround)', async () => {
+		// incur's SyncSkills.sync copies only SKILL.md; installSkills backfills the
+		// sibling resources. The genre code references under
+		// picopilot-code/reference/ must reach the installed skill dir, or the
+		// SKILL.md's on-demand pointers dangle.
+		await installSkills({cli: createCli(), global: false, cwd: target});
+
+		const codeSkill = join(target, '.agents', 'skills', 'picopilot-code');
+		expect(existsSync(join(codeSkill, 'SKILL.md'))).toBe(true);
+		for (const res of [
+			'reference/README.md',
+			'reference/platformer.md',
+			'reference/puzzle-grid.md',
+			'reference/twin-stick-arcade.md',
+			'reference/top-down-adventure.md',
+			'reference/mode7-racing.md',
+			'reference/rpg-menus-dialog.md',
+		]) {
+			expect(existsSync(join(codeSkill, res))).toBe(true);
+		}
+		// The resource content is the authored source byte-for-byte (a real copy).
+		expect(
+			readFileSync(join(codeSkill, 'reference/platformer.md'), 'utf8'),
+		).toBe(
+			readFileSync(
+				join(skillsSourceDir(), 'picopilot-code', 'reference/platformer.md'),
+				'utf8',
+			),
+		);
+		// The real dirs stay untouched (resource copy respects isolation).
+		for (const dir of REAL_DIRS) {
+			expect(snapshot(dir)).toEqual(before.get(dir));
+		}
+	});
+
+	it('copies arbitrary nested resources from a custom source, isolated', async () => {
+		// A fixture skill with a nested resource proves the copy is general (not
+		// hard-coded to picopilot-code) and stays inside the temp target.
+		const source = mkdtempSync(join(tmpdir(), 'picopilot-skills-src-'));
+		try {
+			const skillDir = join(source, 'picopilot-fixture');
+			execFileSync('mkdir', ['-p', join(skillDir, 'reference', 'deep')]);
+			execFileSync('sh', [
+				'-c',
+				`printf '%s\n' '---' 'name: picopilot-fixture' 'description: A fixture skill.' '---' '# fixture' > ${JSON.stringify(join(skillDir, 'SKILL.md'))}`,
+			]);
+			execFileSync('sh', [
+				'-c',
+				`printf 'RES' > ${JSON.stringify(join(skillDir, 'reference', 'deep', 'note.md'))}`,
+			]);
+
+			await installSkills({
+				cli: createCli(),
+				global: false,
+				cwd: target,
+				sourceDir: source,
+			});
+
+			const installed = join(target, '.agents', 'skills', 'picopilot-fixture');
+			expect(existsSync(join(installed, 'SKILL.md'))).toBe(true);
+			expect(
+				readFileSync(join(installed, 'reference', 'deep', 'note.md'), 'utf8'),
+			).toBe('RES');
+			for (const dir of REAL_DIRS) {
+				expect(snapshot(dir)).toEqual(before.get(dir));
+			}
+		} finally {
+			execFileSync('rm', ['-rf', source]);
+		}
+	});
+});

package/src/engine/skills/skills.ts

@@ -0,0 +1,205 @@
+import {cpSync, existsSync, readdirSync} from 'node:fs';
+import {basename, dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {Cli, SyncSkills} from 'incur';
+
+/**
+ * The engine behind `picopilot init --install-skills`: the ONE picopilot path
+ * that writes to a SHARED/GLOBAL location. incur's `skills add` defaults to a
+ * GLOBAL install (into `~/.agents/skills` plus symlinks into detected agent
+ * dirs like `~/.claude/skills`), so this module is where the work-contract's
+ * shared-write isolation obligation is discharged: every knob that decides the
+ * install TARGET (`global`, `cwd`) is a parameter a test can redirect to a temp
+ * dir, so installing skills can never pollute the real environment in tests.
+ *
+ * The install runs IN-PROCESS through incur's `SyncSkills.sync`. NOTE (incur
+ * 0.4.10): `SyncSkills.sync` / the `skills add` built-in resolve their target
+ * from `os.homedir()` and `process.env` captured AT MODULE LOAD, NOT from the
+ * `env` DI you can pass to `cli.serve(argv, { env })`, so overriding the serve
+ * env does NOT move the install target. The effective in-process lever is
+ * `global: false` + `cwd: <temp dir>`, which installs under `<cwd>/.agents/skills`
+ * (and `<cwd>/.claude/skills` etc.) and leaves the real dirs byte-untouched.
+ */
+
+/**
+ * The authored picopilot skills (US #20 discipline skills + the game skills),
+ * as SKILL.md files under {@link skillsSourceDir}. They load on-demand by
+ * concern and carry the hard-won workflow knowledge (the `#include` discipline,
+ * the token breakdown, the `gfx render`→look→`gfx set`→fix loop incl. the
+ * non-multimodal fallback, composing in picopilot-MML) so an agent gets it
+ * without bloating every turn.
+ *
+ * The GAME skills are a composed pair (grilled design in
+ * work/notes/ideas/game-jam-design-skill.md): `game-jam` (model-invoked, the
+ * clock+theme discipline) POINTS AT `game-design-reference` (a user-invoked
+ * reference body of universal design principles, `disable-model-invocation`, so
+ * it costs no per-turn context and is reached only by pointer, not fired on a
+ * vague trigger). Both ship engine-packaged here; `game-design-reference`'s
+ * CONTENT is engine-agnostic.
+ *
+ * They ship ALONGSIDE the per-command skills incur auto-generates from the
+ * command surface (`sync: { depth: 1 }`), pulled in via an `include` glob; the
+ * command surface is still growing, so the named discipline skills are authored
+ * rather than tied to a command-group shape that does not exist yet.
+ */
+export const SKILL_NAMES = [
+	'picopilot-overview',
+	'picopilot-code',
+	'picopilot-art',
+	'picopilot-audio',
+	'picopilot-debug',
+	'game-design-reference',
+	'game-jam',
+] as const;
+
+/**
+ * Resolves the on-disk directory that holds the authored `picopilot-*` SKILL.md
+ * files (`<packageRoot>/src/skills`). The files ship in the npm package (the
+ * package `files` includes `src`), so the same path works from the built
+ * `dist/` runtime and from `src/` under tsx: we walk up from THIS module to the
+ * package root (the nearest ancestor with a `package.json`) and join `src/skills`,
+ * rather than a `dist`-relative path that would not exist (SKILL.md is not
+ * compiled).
+ */
+export function skillsSourceDir(): string {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	const seen = new Set<string>();
+	while (!seen.has(dir)) {
+		seen.add(dir);
+		if (existsSync(join(dir, 'package.json'))) {
+			return join(dir, 'src', 'skills');
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	// Fallback: two levels up from src/engine/skills is the package root.
+	return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
+}
+
+/** One agent whose skill dir picopilot's install wired up (from incur's result). */
+export interface WiredAgent {
+	readonly agent: string;
+	readonly path: string;
+	readonly mode: string;
+}
+
+/** The outcome of installing picopilot's skills. */
+export interface InstallSkillsResult {
+	/** Canonical install paths (one per skill, under `<base>/.agents/skills`). */
+	readonly paths: string[];
+	/** Non-universal agents whose dirs were symlinked/copied to the canonical skills. */
+	readonly agents: WiredAgent[];
+	/** The skill names that were installed. */
+	readonly skills: string[];
+}
+
+/** Options controlling WHERE and HOW picopilot's skills are installed. */
+export interface InstallSkillsOptions {
+	/**
+	 * The picopilot CLI whose command surface the per-command skills are generated
+	 * from. Its command map (via {@link Cli.toCommands}) is handed to incur.
+	 */
+	readonly cli: Cli.Cli;
+	/**
+	 * Install globally (the real default, into `~/.agents/skills` + detected agent
+	 * dirs) when true; install project-locally (into `<cwd>/.agents/skills`) when
+	 * false. This is the shared-write isolation lever: tests pass `false`.
+	 */
+	readonly global: boolean;
+	/**
+	 * The install base for a project-local (`global: false`) install and, when a
+	 * non-universal agent is detected, the base its symlinks are written under.
+	 * Ignored for a global install (that goes to the real home). Tests point this
+	 * at a temp dir.
+	 */
+	readonly cwd?: string;
+	/**
+	 * Override the authored-skills source dir. Defaults to {@link skillsSourceDir}.
+	 * Exists so a test can prove isolation using its own fixture skills.
+	 */
+	readonly sourceDir?: string;
+}
+
+/**
+ * Installs picopilot's skills (the authored `picopilot-*` discipline skills plus
+ * the per-command skills incur generates from the CLI) via incur's
+ * `SyncSkills.sync`. This is the real work `init --install-skills` performs.
+ *
+ * The authored skills are pulled in with an ABSOLUTE `include` glob into
+ * {@link skillsSourceDir}, DECOUPLED from `cwd` on purpose: `cwd` selects the
+ * install TARGET, the include glob selects the skills SOURCE. That decoupling is
+ * what lets a test install to a temp `cwd` while still reading the real authored
+ * skills (or its own fixtures), the crux of the isolation contract.
+ */
+export async function installSkills(
+	options: InstallSkillsOptions,
+): Promise<InstallSkillsResult> {
+	const commands = Cli.toCommands.get(options.cli);
+	if (commands === undefined) {
+		throw new Error(
+			'installSkills: the given CLI has no command map (was it built by Cli.create?)',
+		);
+	}
+
+	const source = options.sourceDir ?? skillsSourceDir();
+
+	const result = await SyncSkills.sync('picopilot', commands, {
+		depth: 1,
+		description: 'An agent-first toolchain for PICO-8 game development.',
+		global: options.global,
+		cwd: options.cwd,
+		// Absolute glob → resolves against `source`, independent of `cwd`.
+		include: [join(source, '*')],
+	});
+
+	// Ship skill RESOURCE files (everything a skill dir carries besides SKILL.md).
+	// incur 0.4.10's SyncSkills.sync copies ONLY SKILL.md and drops sibling files
+	// (see work/notes/observations/incur-syncskills-drops-skill-resource-files.md),
+	// so genre code references under e.g. `picopilot-code/reference/` would never
+	// reach the installed skill. We backfill them here: for each installed skill
+	// path (canonical + each wired agent), copy the matching source skill's
+	// non-SKILL.md contents in. This stays inside the already-isolated installSkills
+	// seam, so the shared-write isolation test still governs it, and it becomes a
+	// no-op (safe to delete) once incur copies full skill dirs.
+	const installPaths = [...result.paths, ...result.agents.map((a) => a.path)];
+	for (const installedSkillDir of installPaths) {
+		copySkillResources(
+			join(source, basename(installedSkillDir)),
+			installedSkillDir,
+		);
+	}
+
+	return {
+		paths: result.paths,
+		agents: result.agents.map((a) => ({
+			agent: a.agent,
+			path: a.path,
+			mode: a.mode,
+		})),
+		skills: result.skills.map((s) => s.name),
+	};
+}
+
+/**
+ * Copies a source skill directory's RESOURCE files (everything except SKILL.md)
+ * into an already-installed skill directory. This is the workaround for incur
+ * 0.4.10 shipping only SKILL.md (see the observation referenced in installSkills):
+ * SKILL.md is left to incur (it is already written and may be transformed), and
+ * only the sibling resources are backfilled, recursively, preserving structure.
+ *
+ * Both the source skill and any resources are optional: a skill with no resource
+ * files, or a source dir that does not exist (a command-generated skill with no
+ * authored source), is a silent no-op. Nothing here reaches outside `destDir`,
+ * which is one of the install paths SyncSkills already chose, so it inherits the
+ * shared-write isolation of installSkills (tests redirect those paths to a temp).
+ */
+function copySkillResources(sourceSkillDir: string, destDir: string): void {
+	if (!existsSync(sourceSkillDir) || !existsSync(destDir)) return;
+	for (const entry of readdirSync(sourceSkillDir)) {
+		if (entry === 'SKILL.md') continue; // incur owns the manifest; do not clobber it
+		cpSync(join(sourceSkillDir, entry), join(destDir, entry), {
+			recursive: true,
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import type {Cli} from 'incur';
+import {createCli} from './cli.js';
+
+export {createCli} from './cli.js';
+export {VERSION} from './version.js';
+
+/**
+ * The default CLI instance, exported for `incur gen` (typed CTAs) and for
+ * embedding picopilot as a Fetch API handler / MCP server.
+ */
+const cli: Cli.Cli = createCli();
+
+export default cli;