@agnostic-prompt/aps 1.1.1

package/payload/agnostic-prompt-standard/references/06-logging-and-privacy.md

@@ -0,0 +1,32 @@
+# 06 Logging and privacy
+
+This document defines the normative logging and redaction requirements for APS executors.
+
+## Logging
+
+```yaml
+logging:
+  capture_points: [RUN, USE, CAPTURE, SET, UNSET, ASSERT, RETURN, PAR, JOIN, TELL, SNAP]
+  include:
+    - timestamp
+    - process_id
+    - step_index
+    - action
+    - inputs
+    - outputs
+    - artifacts
+    - prior_hash
+    - new_hash
+    - origin
+    - policy_hash
+```
+
+## Redaction
+
+Engines MUST enforce:
+
+- Secrets/PII MUST be redacted as `[REDACTED]` (`AG-032`).
+- For `SNAP` with `redact=[SYMS]`, engines MUST zeroize the listed symbols in `prior_state`,
+  `new_state`, and `artifacts`.
+- If `TELL` uses `why:SYMBOL` and `SYMBOL` is redacted, only the symbol name may appear; its
+  content MUST NOT.

package/payload/agnostic-prompt-standard/references/07-error-taxonomy.md

@@ -0,0 +1,62 @@
+# 07 Error taxonomy
+
+This document defines the normative error and warning codes.
+
+## Errors
+
+```yaml
+errors:
+  hard:
+    - { code: AG-001, name: UndefinedSymbol, desc: Symbol not defined in <constants> or <runtime>. }
+    - { code: AG-002, name: ReservedTokenMisuse, desc: Reserved word used as ID/Key/Symbol. }
+    - { code: AG-003, name: InvalidId, desc: Process/tool/key not matching naming regex. }
+    - { code: AG-004, name: ProcessIdMismatch, desc: RUN references missing <process id="…">. }
+    - { code: AG-006, name: UnresolvedPlaceholder, desc: Placeholder could not be resolved. }
+    - { code: AG-007, name: BadJSON, desc: Invalid JSON value or pair. }
+    - { code: AG-008, name: CaptureMissing, desc: CAPTURE references unknown/never-executed tool. }
+    - { code: AG-009, name: TagMismatch, desc: Unbalanced or wrong closing tag. }
+    - { code: AG-010, name: CommentDetected, desc: Comment present in executable blocks. }
+    - { code: AG-011, name: TabDetected, desc: Tab characters present. }
+    - { code: AG-012, name: KeyOrder, desc: Keys in where: not lexicographic. }
+    - { code: AG-013, name: DuplicateSymbol, desc: Symbol redefined with incompatible type/origin. }
+    - { code: AG-014, name: TimeFormat, desc: Non-ISO 8601 time/offset where required. }
+    - { code: AG-015, name: CasePolicy, desc: Non-lowercase booleans or non-double-quoted strings. }
+    - { code: AG-016, name: ProcessNameAttrMismatch, desc: <process> Name attr missing/malformed. }
+    - { code: AG-017, name: ToolPolicy, desc: Tools used in <triggers>. }
+    - { code: AG-018, name: ConcurrencyPolicy, desc: PAR/JOIN misuse or nondeterministic ordering. }
+    - { code: AG-019, name: ForbiddenSymbolOrigin, desc: SET origin missing/invalid. }
+    - { code: AG-021, name: STEValidationFailed, desc: ste=true text failed STE lints. }
+    - { code: AG-022, name: RandomnessPolicy, desc: Randomness used without seed where policy forbids. }
+    - { code: AG-023, name: WithScopeError, desc: WITH defaults malformed or leaked across scope boundary. }
+    - { code: AG-024, name: AliasMapError, desc: ALIAS mapping invalid or collides with symbol names. }
+    - { code: AG-027, name: TimeoutRetryPolicy, desc: timeout_ms/retry invalid type/range. }
+    - { code: AG-028, name: CapturePathError, desc: CAPTURE map path invalid or type coercion failed. }
+    - { code: AG-029, name: AssertInvalid, desc: ASSERT expression invalid or unsafely side-effecting. }
+    - { code: AG-030, name: SemicolonDetected, desc: Semicolon ';' used where newline termination is required. }
+    - { code: AG-031, name: PaddingWhitespace, desc: Excess inter-token spaces detected; exactly one ASCII space required in compiled form. }
+    - { code: AG-032, name: SensitiveInLog, desc: Secrets/PII leaked in logs or errors. }
+    - { code: AG-033, name: InstructionsLinePolicy, desc: Multiple sentences per line, blank lines, or non-directive lines present in <instructions>. }
+    - { code: AG-034, name: PredefinedToolCollision, desc: Conflicting tool signatures across host and predefinedTools.json. }
+    - { code: AG-035, name: InPromptConfigOrImports, desc: Presence of <config> or <import> tags in prompt. }
+    - { code: AG-036, name: FormatContractViolation, desc: Output does not match the referenced <format id="…"> template (missing headers/columns/markers/placeholders not resolved). }
+    - { code: AG-037, name: DictReferenceForbidden, desc: DICT-style reference @"…" used; constants must be defined in <constants>. }
+    - { code: AG-038, name: DictInConfigForbidden, desc: config.json contains a DICT key; migrate constants to <constants>. }
+    - { code: AG-039, name: FormatUndefined, desc: A step references a format id that is not defined in <formats>. }
+    - { code: AG-040, name: FormatFenceError, desc: Missing or malformed ```format:<ID> fenced block; multiple format blocks or surrounding prose where a single block is required. }
+    - { code: AG-041, name: FormatWhereMissing, desc: WHERE: section missing or not uppercase when placeholders are present (or required by policy). }
+    - { code: AG-042, name: PlaceholderMismatch, desc: Placeholder appears in body but not in WHERE, or defined in WHERE but not present in body. }
+    - { code: AG-043, name: PlaceholderStyleError, desc: Placeholder not in <UPPER_SNAKE> form or not wrapped in angle brackets. }
+    - { code: AG-044, name: ProcessArgsMismatch, desc: RUN statement arguments do not match the target process signature (missing, extra, or type-incompatible arguments). }
+    - { code: AG-045, name: BlockConstantUnterminated, desc: Block constant missing closing delimiter line >>. }
+    - { code: AG-046, name: BlockConstantTypeUnknown, desc: Block constant uses unknown <BLOCK_TYPE>; expected JSON or TEXT. }
+
+  warnings:
+    - { code: AG-W01, name: SymbolNotUsed, desc: Defined but never used. }
+    - { code: AG-W02, name: LaxTime, desc: Step without explicit time where policy requires. }
+    - { code: AG-W03, name: HeuristicInference, desc: Placeholder resolved by Agent Inference under strict policy. }
+```
+
+## Required behaviors
+
+- Engines MUST treat all `errors.hard` codes as fatal for the current compile/run.
+- Engines MAY continue on `warnings`, but MUST surface them to the caller.

package/scripts/lint.js

@@ -0,0 +1,27 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'payload') continue; // generated
+    const p = join(dir, entry);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walk(p));
+    else if (st.isFile() && p.endsWith('.js')) out.push(p);
+  }
+  return out;
+}
+
+const rootPath = fileURLToPath(new URL('..', import.meta.url));
+
+const files = walk(rootPath);
+let failed = false;
+for (const file of files) {
+  const r = spawnSync(process.execPath, ['--check', file], { stdio: 'inherit' });
+  if (r.status !== 0) failed = true;
+}
+
+process.exit(failed ? 1 : 0);

package/scripts/prepack.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(here, '..');
+const repoRoot = path.resolve(pkgRoot, '..', '..');
+
+const src = path.join(repoRoot, 'skill', 'agnostic-prompt-standard');
+const dst = path.join(pkgRoot, 'payload', 'agnostic-prompt-standard');
+
+async function main() {
+  // Clean target
+  await fs.rm(dst, { recursive: true, force: true });
+  await fs.mkdir(path.dirname(dst), { recursive: true });
+  await fs.cp(src, dst, { recursive: true });
+  console.log(`Synced APS skill payload -> ${dst}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/cli.js

@@ -0,0 +1,292 @@
+import { Command } from 'commander';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  checkbox,
+  confirm,
+  input,
+  select,
+} from '@inquirer/prompts';
+
+import {
+  SKILL_ID,
+  copyDir,
+  copyTemplates,
+  defaultPersonalSkillPath,
+  defaultProjectSkillPath,
+  ensureDir,
+  findRepoRoot,
+  inferPlatformId,
+  isDirectory,
+  pathExists,
+  removeDir,
+  resolvePayloadSkillDir,
+  loadPlatforms,
+} from './core.js';
+
+const EXIT_USAGE = 2;
+
+function isTTY() {
+  return Boolean(process.stdout.isTTY && process.stdin.isTTY);
+}
+
+function normalizePlatform(value) {
+  if (!value) return undefined;
+  if (value === 'none') return null;
+  return value;
+}
+
+async function pickWorkspaceRoot(cliRoot) {
+  if (cliRoot) return path.resolve(cliRoot);
+  const repo = await findRepoRoot(process.cwd());
+  return repo;
+}
+
+function fmtPath(p) {
+  return p.replace(process.env.HOME ?? '', '~');
+}
+
+async function runInit(options) {
+  const payloadSkillDir = await resolvePayloadSkillDir();
+  const repoRoot = await findRepoRoot(process.cwd());
+  const guessedWorkspaceRoot = await pickWorkspaceRoot(options.root);
+
+  // Determine scope
+  let installScope = options.personal ? 'personal' : options.repo ? 'repo' : undefined;
+
+  // Determine workspace root
+  let workspaceRoot = guessedWorkspaceRoot;
+
+  // Determine platform
+  const detectedPlatform = workspaceRoot ? inferPlatformId(workspaceRoot) : null;
+  let platformId = normalizePlatform(options.platform) ?? undefined;
+
+  // Determine extras
+  let installTemplates = Boolean(options.templates);
+
+  if (!options.yes && isTTY()) {
+    // Scope prompt
+    if (!installScope) {
+      installScope = await select({
+        message: 'Where should APS be installed?',
+        default: repoRoot ? 'repo' : 'personal',
+        choices: [
+          {
+            name: repoRoot ? `Project skill in this repo (${fmtPath(repoRoot)})` : 'Project skill (choose a workspace folder)',
+            value: 'repo',
+          },
+          {
+            name: `Personal skill for your user (${fmtPath(defaultPersonalSkillPath({ claude: options.claude }).replace(SKILL_ID, ''))})`,
+            value: 'personal',
+          },
+        ],
+      });
+    }
+
+    if (installScope === 'repo' && !workspaceRoot) {
+      const rootAnswer = await input({
+        message: 'Workspace root path (the folder that contains .github/):',
+        default: process.cwd(),
+      });
+      workspaceRoot = path.resolve(rootAnswer);
+    }
+
+    if (!platformId && workspaceRoot) {
+      const platforms = await loadPlatforms(payloadSkillDir);
+      const choices = [
+        ...(detectedPlatform ? [{ name: `Auto-detected: ${detectedPlatform}`, value: detectedPlatform }] : []),
+        { name: 'None (skip platform templates)', value: null },
+        ...platforms
+          .filter((p) => p.platformId !== detectedPlatform)
+          .map((p) => ({
+            name: `${p.displayName} (${p.platformId})`,
+            value: p.platformId,
+          })),
+      ];
+
+      platformId = await select({
+        message: 'Select a platform adapter to apply:',
+        default: detectedPlatform ?? null,
+        choices,
+      });
+    }
+
+    if (platformId && workspaceRoot) {
+      const extras = await checkbox({
+        message: 'Extras to apply to the workspace:',
+        choices: [
+          {
+            name: 'Install platform templates (e.g. VS Code agent file + AGENTS.md)',
+            value: 'templates',
+            checked: true,
+          },
+        ],
+      });
+      installTemplates = extras.includes('templates');
+    }
+  } else {
+    // Non-interactive defaults
+    if (!installScope) installScope = repoRoot ? 'repo' : 'personal';
+    if (!platformId && workspaceRoot) platformId = detectedPlatform;
+    if (platformId && !options.templates) installTemplates = true;
+  }
+
+  // Compute destinations
+  let skillDest;
+  if (installScope === 'repo') {
+    if (!workspaceRoot) {
+      throw new Error('Repo install selected but no workspace root found. Run in a git repo or pass --root <path>.');
+    }
+    skillDest = defaultProjectSkillPath(workspaceRoot, { claude: options.claude });
+  } else {
+    skillDest = defaultPersonalSkillPath({ claude: options.claude });
+  }
+
+  // Preflight
+  const actions = [];
+  actions.push({ kind: 'skill', from: payloadSkillDir, to: skillDest });
+
+  let templatesDir = null;
+  if (platformId && installTemplates) {
+    templatesDir = path.join(payloadSkillDir, 'platforms', platformId, 'templates');
+    if (!(await isDirectory(templatesDir))) {
+      templatesDir = null;
+    } else if (!workspaceRoot) {
+      // If personal scope but we still want templates, default to current directory.
+      workspaceRoot = process.cwd();
+    }
+    if (templatesDir && workspaceRoot) {
+      actions.push({ kind: 'templates', from: templatesDir, to: workspaceRoot });
+    }
+  }
+
+  if (options.dryRun) {
+    console.log('Dry run — planned actions:');
+    for (const a of actions) {
+      console.log(`- ${a.kind}: ${a.from} -> ${a.to}`);
+    }
+    return;
+  }
+
+  // Execute
+  for (const a of actions) {
+    const destExists = await pathExists(a.to);
+    if (destExists && !options.force) {
+      if (!options.yes && isTTY()) {
+        const ok = await confirm({
+          message: `Destination already exists: ${a.to}\nOverwrite?`,
+          default: false,
+        });
+        if (!ok) {
+          console.log('Cancelled.');
+          return;
+        }
+      } else {
+        throw new Error(`Destination exists: ${a.to} (use --force to overwrite)`);
+      }
+    }
+
+    if (destExists && options.force) {
+      await removeDir(a.to);
+    }
+
+    await ensureDir(path.dirname(a.to));
+
+    if (a.kind === 'skill') {
+      await copyDir(a.from, a.to);
+      console.log(`Installed APS skill -> ${a.to}`);
+    } else if (a.kind === 'templates') {
+      await copyTemplates(a.from, a.to, { force: options.force });
+      console.log(`Applied platform templates -> ${a.to}`);
+    }
+  }
+
+  console.log('\nNext steps (VS Code):');
+  console.log('- Ensure VS Code has Agent Skills + instruction files enabled as needed.');
+  console.log(`- Skill location: ${skillDest}`);
+}
+
+async function runDoctor(options) {
+  const root = await pickWorkspaceRoot(options.root);
+  const detected = root ? inferPlatformId(root) : null;
+
+  const rows = [];
+
+  if (root) {
+    const repoSkill = defaultProjectSkillPath(root, { claude: false });
+    const repoSkillClaude = defaultProjectSkillPath(root, { claude: true });
+    rows.push(['repo', repoSkill, await pathExists(path.join(repoSkill, 'SKILL.md'))]);
+    rows.push(['repo (claude)', repoSkillClaude, await pathExists(path.join(repoSkillClaude, 'SKILL.md'))]);
+  }
+
+  const personalSkill = defaultPersonalSkillPath({ claude: false });
+  const personalSkillClaude = defaultPersonalSkillPath({ claude: true });
+  rows.push(['personal', personalSkill, await pathExists(path.join(personalSkill, 'SKILL.md'))]);
+  rows.push(['personal (claude)', personalSkillClaude, await pathExists(path.join(personalSkillClaude, 'SKILL.md'))]);
+
+  console.log('APS Doctor');
+  console.log('----------');
+  console.log(`Workspace root: ${root ?? '(not detected)'}`);
+  console.log(`Detected platform: ${detected ?? '(none)'}`);
+  console.log('');
+  console.log('Installed skills:');
+  for (const [scope, p, ok] of rows) {
+    console.log(`- ${scope}: ${p} ${ok ? '✓' : '✗'}`);
+  }
+}
+
+export async function main(argv) {
+  const program = new Command();
+  program
+    .name('aps')
+    .description('Install and manage the Agnostic Prompt Standard (APS) skill.')
+    .version('1.1.1');
+
+  program
+    .command('init')
+    .description('Install APS skill + (optionally) platform templates')
+    .option('--root <path>', 'Workspace root path (defaults to git repo root if found)')
+    .option('--repo', 'Install as a project skill (under .github/skills)')
+    .option('--personal', 'Install as a personal skill (under ~/.copilot/skills)')
+    .option('--platform <id>', 'Platform adapter to apply (e.g. vscode-copilot). Use "none" to skip.')
+    .option('--templates', 'Apply platform templates (default true when a platform is selected)')
+    .option('--claude', 'Use Claude platform .claude/skills paths instead of .github/skills and ~/.copilot/skills', false)
+    .option('-y, --yes', 'Non-interactive; accept defaults', false)
+    .option('-f, --force', 'Overwrite existing files', false)
+    .option('--dry-run', 'Print planned actions without writing', false)
+    .action((opts) => runInit(opts).catch((e) => {
+      console.error(`Error: ${e.message ?? e}`);
+      process.exit(1);
+    }));
+
+  program
+    .command('doctor')
+    .description('Check APS installation status + basic platform detection')
+    .option('--root <path>', 'Workspace root path (defaults to git repo root if found)')
+    .action((opts) => runDoctor(opts).catch((e) => {
+      console.error(`Error: ${e.message ?? e}`);
+      process.exit(1);
+    }));
+
+  program
+    .command('info')
+    .description('Print bundled APS payload info')
+    .action(async () => {
+      const payloadSkillDir = await resolvePayloadSkillDir();
+      const platforms = await loadPlatforms(payloadSkillDir);
+      console.log(`CLI version: 1.1.1`);
+      console.log(`Bundled skill path: ${payloadSkillDir}`);
+      console.log('Platforms:');
+      for (const p of platforms) {
+        console.log(`- ${p.platformId}: ${p.displayName} (templates: ${p.hasTemplates ? 'yes' : 'no'})`);
+      }
+    });
+
+  await program.parseAsync(argv);
+
+  // If no command was provided, show help and exit with usage.
+  if (!program.args.length) {
+    program.help({ error: true });
+    process.exit(EXIT_USAGE);
+  }
+}

package/src/core.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const SKILL_ID = 'agnostic-prompt-standard';
+
+export function homeDir() {
+  return os.homedir();
+}
+
+export async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirectory(p) {
+  try {
+    const st = await fs.stat(p);
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function findRepoRoot(startDir) {
+  let cur = path.resolve(startDir);
+  while (true) {
+    const gitDir = path.join(cur, '.git');
+    if (existsSync(gitDir)) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+export function defaultProjectSkillPath(repoRoot, opts = {}) {
+  const claude = Boolean(opts.claude);
+  return claude
+    ? path.join(repoRoot, '.claude', 'skills', SKILL_ID)
+    : path.join(repoRoot, '.github', 'skills', SKILL_ID);
+}
+
+export function defaultPersonalSkillPath(opts = {}) {
+  const claude = Boolean(opts.claude);
+  return claude
+    ? path.join(homeDir(), '.claude', 'skills', SKILL_ID)
+    : path.join(homeDir(), '.copilot', 'skills', SKILL_ID);
+}
+
+export function inferPlatformId(workspaceRoot) {
+  // Heuristic: VS Code + Copilot convention folders/files.
+  // If more platforms are added, extend this with adapter-specific heuristics.
+  const gh = path.join(workspaceRoot, '.github');
+  const hasAgents = existsSync(path.join(gh, 'agents'));
+  const hasPrompts = existsSync(path.join(gh, 'prompts'));
+  const hasInstructions = existsSync(path.join(gh, 'copilot-instructions.md')) || existsSync(path.join(gh, 'instructions'));
+  if (hasAgents || hasPrompts || hasInstructions) return 'vscode-copilot';
+  return null;
+}
+
+export async function readSkillFrontmatter(skillDir) {
+  const skillPath = path.join(skillDir, 'SKILL.md');
+  const raw = await fs.readFile(skillPath, 'utf8');
+  const match = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const yaml = match[1];
+  const out = {};
+  // Extremely small YAML subset parser: key: "value" / key: value
+  for (const line of yaml.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const idx = trimmed.indexOf(':');
+    if (idx === -1) continue;
+    const key = trimmed.slice(0, idx).trim();
+    let val = trimmed.slice(idx + 1).trim();
+    // strip quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+export async function loadPlatforms(skillDir) {
+  const platformsDir = path.join(skillDir, 'platforms');
+  const entries = await fs.readdir(platformsDir, { withFileTypes: true });
+  const platforms = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name.startsWith('_')) continue;
+    const manifestPath = path.join(platformsDir, e.name, 'manifest.json');
+    if (!(await pathExists(manifestPath))) continue;
+    try {
+      const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+      platforms.push({
+        platformId: manifest.platformId ?? e.name,
+        displayName: manifest.displayName ?? e.name,
+        adapterVersion: manifest.adapterVersion ?? null,
+        hasTemplates: await isDirectory(path.join(platformsDir, e.name, 'templates')),
+      });
+    } catch {
+      // ignore malformed platform manifests
+    }
+  }
+  platforms.sort((a, b) => a.displayName.localeCompare(b.displayName));
+  return platforms;
+}
+
+export function resolveThisDir() {
+  return path.dirname(fileURLToPath(import.meta.url));
+}
+
+export async function resolvePayloadSkillDir() {
+  // Priority:
+  // 1) packaged payload/...
+  // 2) repo dev checkout: ../../skill/...
+  const thisDir = resolveThisDir();
+  const packaged = path.resolve(thisDir, '..', 'payload', SKILL_ID);
+  if (await isDirectory(packaged)) return packaged;
+  const dev = path.resolve(thisDir, '..', '..', '..', 'skill', SKILL_ID);
+  if (await isDirectory(dev)) return dev;
+  throw new Error('APS payload not found (payload directory missing).');
+}
+
+export async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+export async function removeDir(p) {
+  await fs.rm(p, { recursive: true, force: true });
+}
+
+export async function copyDir(src, dst) {
+  // Node 18+ supports fs.cp
+  await fs.cp(src, dst, {
+    recursive: true,
+    force: true,
+  });
+}
+
+export async function copyTemplates(templatesDir, workspaceRoot, { force }) {
+  // Merge-copy everything from templatesDir into workspaceRoot.
+  // If force=false, we will not overwrite existing files.
+  // We implement this with a manual tree walk to make overwrite policy explicit.
+  async function walk(rel) {
+    const abs = path.join(templatesDir, rel);
+    const st = await fs.stat(abs);
+    if (st.isDirectory()) {
+      const entries = await fs.readdir(abs);
+      for (const ent of entries) await walk(path.join(rel, ent));
+      return;
+    }
+    // file
+    const dest = path.join(workspaceRoot, rel);
+    await ensureDir(path.dirname(dest));
+    if (!force && (await pathExists(dest))) {
+      return { skipped: [rel], copied: [] };
+    }
+    await fs.copyFile(abs, dest);
+    return { skipped: [], copied: [rel] };
+  }
+
+  const summary = { copied: [], skipped: [] };
+  const entries = await fs.readdir(templatesDir);
+  for (const ent of entries) {
+    const res = await walk(ent);
+    if (!res) continue;
+    summary.copied.push(...res.copied);
+    summary.skipped.push(...res.skipped);
+  }
+  return summary;
+}