create-contractor-site 2.2.0 → 2.3.0

package/README.md

@@ -2,16 +2,18 @@
 
 Scaffold a client contractor website from the [website-multipages](https://github.com/glacayo/website-multipages) Astro template.
 
-**Package version:** `2.2.0` · **Default template ref:** `v2.2.0` (`CREATE_CONTRACTOR_TEMPLATE_REF`)
+**Package version:** `2.3.0` · **Default template ref:** `v2.3.0` (`CREATE_CONTRACTOR_TEMPLATE_REF`)
 
 The CLI validates the target, copies the template, replaces placeholder values in `src/data/*.json`, installs with **pnpm**, validates data, builds, and initializes git **only after** success.
 
-## What's new in 2.2.0
+## What's new in 2.3.0
 
-- **`siteType`** — choose `one-page`, `multipage`, or `seo` (aliases accepted). Written to `site.json.site_type`. Default for new scaffolds: `multipage`.
-- **Expanded intake** — payment methods, hours, free-estimate wording, years of experience, license, insurance, social links, and directories (interactive, `--yes` defaults, or `CREATE_CONTRACTOR_SITE_ANSWERS_JSON`).
-- **Template clone default** — published fallback uses git ref **`v2.2.0`** unless you set `CREATE_CONTRACTOR_TEMPLATE_ROOT` or `CREATE_CONTRACTOR_TEMPLATE_REF`.
-- After scaffold, treat `business.json` + `site.json` as authoritative identity; leftover demo trade content is expected seed material to rewrite.
+- **Page-shell reuse** — shared page header shell extracted across about/contact/remaining pages, reducing duplicated layout markup.
+- **Isolated smart-image capsule** — optional image helpers live in a separate pnpm workspace at `tools/smart-image/`, outside the root dependency graph; root lockfile/workspace stay separate.
+- **Scaffold/state protections** — `CUSTOMER-IMAGES/` and `.img-ia/` are gitignored and scaffold-denied; capsule `node_modules/` stays ignored; no credential/state bytes reach `dist/`.
+- **Agent-owned image fulfillment** — `images:check` / `images:setup` / `images:run` wrappers; the active agent autonomously copies compliant candidates from `<image-root>/_out/` into `src/assets/images/` and updates JSON values + alt text (no human promotion step).
+- **pnpm/Corepack compatibility fix** — pnpm pinned for Corepack compatibility so `pnpm install` is deterministic across environments.
+- **Template clone default** — published fallback uses git ref **`v2.3.0`** unless you set `CREATE_CONTRACTOR_TEMPLATE_ROOT` or `CREATE_CONTRACTOR_TEMPLATE_REF`.
 
 Full release notes: repository root [`CHANGELOG.md`](../../CHANGELOG.md).
 
@@ -61,7 +63,7 @@ CREATE_CONTRACTOR_TEMPLATE_ROOT=/path/to/website-multipages \
 1. Checks that **pnpm** and **git** are available
 2. Resolves the template source (see env vars below)
 3. Validates the target directory and refuses targets equal to or inside the template root
-4. Copies the template into the target directory (denylist excludes `node_modules`, `dist`, `.astro`, `.git`, `.codegraph`, `docs_trash`, `openspec`, `.atl`, `logs`, `*.log`, `.env*`, `package-lock.json`, and `packages/`)
+4. Copies the template into the target directory (denylist excludes `node_modules`, `dist`, `.astro`, `.git`, `.codegraph`, `docs_trash`, `openspec`, `.atl`, `logs`, `*.log`, `.env*`, `package-lock.json`, and `packages/`)
 5. Replaces **values only** in target `src/data/*.json` (schema/shape preserved)
 6. Runs `pnpm install`
 7. Runs `pnpm run validate:data`
@@ -88,7 +90,7 @@ See the template root `AGENTS.md`, `SKILL.md`, and `README.md` for the full agen
 | `CREATE_CONTRACTOR_SITE_ANSWERS_JSON` | JSON object with client answers for scripted/non-interactive scaffolds |
 | `CREATE_CONTRACTOR_TEMPLATE_ROOT` | Path to a local template checkout (preferred for monorepo/dev) |
 | `CREATE_CONTRACTOR_TEMPLATE_REPO` | Git URL for the published fallback clone (default: this template repo) |
-| `CREATE_CONTRACTOR_TEMPLATE_REF` | Git branch/tag/ref to clone (default: `v2.2.0`) |
+| `CREATE_CONTRACTOR_TEMPLATE_REF` | Git branch/tag/ref to clone (default: `v2.3.0`) |
 
 Template source precedence: `CREATE_CONTRACTOR_TEMPLATE_ROOT` → local monorepo discovery → temporary clone of repo @ ref.
 

package/bin/create-contractor-site.mjs

@@ -46,7 +46,7 @@ Environment:
       Default: https://github.com/glacayo/website-multipages.git
 
   CREATE_CONTRACTOR_TEMPLATE_REF
-      Git branch/tag/ref to clone for the published fallback. Default: v2.2.0
+      Git branch/tag/ref to clone for the published fallback. Default: v2.3.0
 
   Answer defaults (buildAnswers; blank/whitespace → these; --yes omits trust/payment/hours/social/directories/siteType):
   freeEstimate      Free On-Site Estimate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-contractor-site",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Scaffold a client contractor website from the placeholder multipage template",
   "type": "module",
   "bin": {
@@ -26,13 +26,13 @@
   },
   "homepage": "https://github.com/glacayo/website-multipages/tree/main/packages/create-contractor-site",
   "engines": {
-    "node": ">=22.12.0",
+    "node": ">=22.13.0",
     "pnpm": ">=11.1.2"
   },
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": ">=11.1.2",
+      "version": "11.18.0",
       "onFail": "error"
     }
   },

package/scripts/smoke-test.mjs

@@ -6,12 +6,15 @@
  * 1. Missing target argument
  * 2. Existing non-empty target
  * 3. Target equal to / inside template root
- * 4. Published DEFAULT_TEMPLATE_REF / CREATE_CONTRACTOR_TEMPLATE_REF contract (v2.2.0)
+ * 4. Published DEFAULT_TEMPLATE_REF / CREATE_CONTRACTOR_TEMPLATE_REF contract (v2.3.0)
  * 5. Duplicate service input normalization + slug uniqueness + business/services alignment
  * 6. Service-area name parse/dedupe (Chesapeake duplicate-slug case) + areas rebuild
  *    without leaking stale template county/ZIP metadata into new areas
  * 7. CREATE_CONTRACTOR_SITE_ANSWERS_JSON real CLI spawn (copy+replace, skip setup)
- * 8. Temp-target --yes scaffold (install/validate/build) unless SKIP_CLI_E2E=1
+ * 8. Root workspace isolation vs tools/smart-image capsule (scope, sharp/zod, dist/)
+ * 9. Smart-image wrapper/lifecycle (argv safety, Windows bin, setup/check, no hooks)
+ * 10. Scaffold deny/gitignore/required retention (isDeniedName, check-ignore, copyTemplate)
+ * 11. Temp-target --yes scaffold (install/validate/build) unless SKIP_CLI_E2E=1
  */
 
 import { spawnSync } from 'node:child_process';
@@ -50,9 +53,17 @@ import {
 import { isSameOrInside, validateTarget, TargetValidationError } from '../src/validate-target.mjs';
 import {
   DEFAULT_TEMPLATE_REF,
+  REQUIRED_AFTER_COPY,
+  assertRequiredCopied,
+  copyTemplate,
   findLocalTemplateRoot,
+  isDeniedName,
 } from '../src/copy-template.mjs';
-import { isVersionAtLeast, resolveCommandPath } from '../src/run-command.mjs';
+import {
+  isVersionAtLeast,
+  resolveCommandPath,
+  runCommand,
+} from '../src/run-command.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI = path.resolve(__dirname, '../bin/create-contractor-site.mjs');
@@ -145,25 +156,25 @@ async function main() {
   });
 
   await test(
-    'DEFAULT_TEMPLATE_REF / CREATE_CONTRACTOR_TEMPLATE_REF published contract is v2.2.0',
+    'DEFAULT_TEMPLATE_REF / CREATE_CONTRACTOR_TEMPLATE_REF published contract is v2.3.0',
     () => {
       const copySrcPath = path.join(PKG_ROOT, 'src', 'copy-template.mjs');
       const copySrc = fs.readFileSync(copySrcPath, 'utf8');
       // Pin the source fallback so a silent ref bump cannot ship without updating this test.
       assert(
-        /CREATE_CONTRACTOR_TEMPLATE_REF\s*\|\|\s*['"]v2\.2\.0['"]/.test(copySrc),
-        'copy-template.mjs DEFAULT_TEMPLATE_REF fallback must be v2.2.0',
+        /CREATE_CONTRACTOR_TEMPLATE_REF\s*\|\|\s*['"]v2\.3\.0['"]/.test(copySrc),
+        'copy-template.mjs DEFAULT_TEMPLATE_REF fallback must be v2.3.0',
       );
       const expected =
-        process.env.CREATE_CONTRACTOR_TEMPLATE_REF || 'v2.2.0';
+        process.env.CREATE_CONTRACTOR_TEMPLATE_REF || 'v2.3.0';
       assert(
         DEFAULT_TEMPLATE_REF === expected,
-        `DEFAULT_TEMPLATE_REF must equal CREATE_CONTRACTOR_TEMPLATE_REF or v2.2.0 (got ${DEFAULT_TEMPLATE_REF})`,
+        `DEFAULT_TEMPLATE_REF must equal CREATE_CONTRACTOR_TEMPLATE_REF or v2.3.0 (got ${DEFAULT_TEMPLATE_REF})`,
       );
       if (!process.env.CREATE_CONTRACTOR_TEMPLATE_REF) {
         assert(
-          DEFAULT_TEMPLATE_REF === 'v2.2.0',
-          `published default template ref must be v2.2.0 (got ${DEFAULT_TEMPLATE_REF})`,
+          DEFAULT_TEMPLATE_REF === 'v2.3.0',
+          `published default template ref must be v2.3.0 (got ${DEFAULT_TEMPLATE_REF})`,
         );
       }
 
@@ -175,8 +186,8 @@ async function main() {
         'help must document CREATE_CONTRACTOR_TEMPLATE_REF',
       );
       assert(
-        /v2\.2\.0/.test(helpOut),
-        'help must document default template ref v2.2.0',
+        /v2\.3\.0/.test(helpOut),
+        'help must document default template ref v2.3.0',
       );
     },
   );
@@ -1105,10 +1116,521 @@ async function main() {
     fs.rmSync(tmp, { recursive: true, force: true });
   });
 
+  // --- image-tooling capsule isolation (Unit 1) ---
+  await test('root workspace stays two projects and excludes tools/*', () => {
+    assert(REPO_ROOT, 'expected local template root');
+    const wsPath = path.join(REPO_ROOT, 'pnpm-workspace.yaml');
+    const wsText = fs.readFileSync(wsPath, 'utf8');
+    assert(/\n\s*-\s*\.\s*$/m.test(wsText) || /packages:\s*\n\s*-\s*\./.test(wsText),
+      'root workspace must include "."');
+    assert(/-\s*packages\/\*/.test(wsText), 'root workspace must include packages/*');
+    assert(!/tools\//.test(wsText), 'root workspace must not absorb tools/*');
+    assert(
+      !/better-sqlite3/.test(wsText),
+      'root pnpm-workspace.yaml must not declare allowBuilds.better-sqlite3',
+    );
+
+    const list = runCommand('pnpm', ['list', '-r', '--depth', '-1'], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+    });
+    // pnpm prints one name@version line per workspace package
+    const names = (list.stdout || '').match(/^[^\s].*@\d/gm) || [];
+    assert(
+      names.length === 2,
+      `expected exactly 2 root workspace projects, got ${names.length}: ${names.join(', ')}`,
+    );
+    assert(
+      !/smart-image/i.test(list.stdout || ''),
+      'root workspace listing must not include smart-image capsule',
+    );
+  });
+
+  await test('root sharp/zod ranges stay unchanged with no overrides', () => {
+    assert(REPO_ROOT, 'expected local template root');
+    const pkg = readJson(path.join(REPO_ROOT, 'package.json'));
+    const sharp = pkg.devDependencies?.sharp ?? pkg.dependencies?.sharp;
+    const zod = pkg.devDependencies?.zod ?? pkg.dependencies?.zod;
+    assert(sharp === '^0.34.5', `root sharp range must stay ^0.34.5, got ${sharp}`);
+    assert(zod === '^4.1.5', `root zod range must stay ^4.1.5, got ${zod}`);
+    assert(pkg.overrides == null, 'root package.json must not declare overrides');
+    assert(
+      pkg.pnpm?.overrides == null,
+      'root package.json must not declare pnpm.overrides',
+    );
+    assert(
+      !pkg.dependencies?.['smart-image-cli'] && !pkg.devDependencies?.['smart-image-cli'],
+      'root package.json must not depend on smart-image-cli',
+    );
+  });
+
+  await test('dist holds zero capsule or smart-image-cli references', () => {
+    assert(REPO_ROOT, 'expected local template root');
+    const distDir = path.join(REPO_ROOT, 'dist');
+    if (!fs.existsSync(distDir)) {
+      console.log('    (dist/ absent — skip content scan; build harness covers post-build)');
+      return;
+    }
+    /** @type {string[]} */
+    const hits = [];
+    const needles = ['smart-image-cli', 'better-sqlite3', 'tools/smart-image', 'tools\\smart-image'];
+    /**
+     * @param {string} dir
+     */
+    function walk(dir) {
+      for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, ent.name);
+        if (ent.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        // Skip large binary assets; scan text-ish build outputs only.
+        if (!/\.(html|js|mjs|cjs|css|json|txt|xml|svg|map)$/i.test(ent.name)) continue;
+        let text;
+        try {
+          text = fs.readFileSync(full, 'utf8');
+        } catch {
+          continue;
+        }
+        for (const n of needles) {
+          if (text.includes(n)) hits.push(`${path.relative(distDir, full)}:${n}`);
+        }
+      }
+    }
+    walk(distDir);
+    assert(hits.length === 0, `dist/ must not reference capsule/CLI: ${hits.slice(0, 10).join(', ')}`);
+  });
+
+  // --- image-tooling wrapper + lifecycle (Unit 2) ---
+  const capDir = REPO_ROOT ? path.join(REPO_ROOT, 'tools', 'smart-image') : '';
+  const runJs = capDir ? path.join(capDir, 'run.mjs') : '';
+  const checkJs = capDir ? path.join(capDir, 'check.mjs') : '';
+
+  /** @param {string} v */
+  const qCmd = (v) =>
+    v === '' ? '""' : /[\s"&<>|^%!]/.test(v) ? `"${String(v).replace(/"/g, '""')}"` : v;
+
+  /**
+   * @param {string} cmd
+   * @param {string[]} args
+   * @param {{ env?: NodeJS.ProcessEnv, cwd?: string }} [o]
+   */
+  function spawnArgv(cmd, args, o = {}) {
+    let c = cmd;
+    let a = [...args];
+    let verbatim = false;
+    if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(cmd)) {
+      c = process.env.ComSpec || 'cmd.exe';
+      a = ['/d', '/s', '/c', `"${[cmd, ...args].map(qCmd).join(' ')}"`];
+      verbatim = true;
+    }
+    return spawnSync(c, a, {
+      encoding: 'utf8',
+      cwd: o.cwd || REPO_ROOT || process.cwd(),
+      env: { ...process.env, ...(o.env || {}) },
+      shell: false,
+      windowsHide: true,
+      windowsVerbatimArguments: verbatim,
+    });
+  }
+
+  /** @param {string[]} args @param {{ env?: NodeJS.ProcessEnv, cwd?: string }} [o] */
+  function runPnpm(args, o = {}) {
+    const bin = resolveCommandPath('pnpm');
+    assert(Boolean(bin), 'pnpm required');
+    return spawnArgv(/** @type {string} */ (bin), args, o);
+  }
+  /** @param {string[]} args @param {{ env?: NodeJS.ProcessEnv }} [o] */
+  const imgRun = (args, o = {}) =>
+    spawnSync(process.execPath, [runJs, ...args], {
+      encoding: 'utf8',
+      cwd: REPO_ROOT,
+      env: { ...process.env, ...(o.env || {}) },
+      shell: false,
+      windowsHide: true,
+    });
+  /** @param {{ env?: NodeJS.ProcessEnv }} [o] */
+  const imgCheck = (o = {}) =>
+    spawnSync(process.execPath, [checkJs], {
+      encoding: 'utf8',
+      cwd: REPO_ROOT,
+      env: { ...process.env, ...(o.env || {}) },
+      shell: false,
+      windowsHide: true,
+    });
+  /** @param {import('node:child_process').SpawnSyncReturns<string>} r */
+  const out = (r) => `${r.stdout || ''}\n${r.stderr || ''}`;
+
+  await test('images:run passes shell metacharacters as literal argv (exit 3, no side effects)', () => {
+    assert(REPO_ROOT && fs.existsSync(runJs), 'run.mjs required');
+    const marker = path.join(os.tmpdir(), `si-side-${process.pid}.txt`);
+    if (fs.existsSync(marker)) fs.rmSync(marker, { force: true });
+    for (const payload of [
+      '--json; rm -rf /',
+      `$(echo pwned > "${marker}")`,
+      `&& echo pwned > "${marker}"`,
+    ]) {
+      for (const r of [runPnpm(['run', 'images:run', '--', payload]), imgRun([payload])]) {
+        assert(r.status === 3, `exit 3 expected, got ${r.status}: ${out(r).slice(0, 300)}`);
+        assert(/invalid_input|unknown|error/i.test(out(r)), `invalid_input for ${payload}`);
+      }
+      assert(!fs.existsSync(marker), `no side-effect file for ${payload}`);
+    }
+  });
+
+  await test('Windows smart-img bin is silent while wrapper emits parseable doctor JSON', () => {
+    assert(REPO_ROOT && fs.existsSync(runJs), 'run.mjs required');
+    const binCmd = path.join(capDir, 'node_modules', '.bin', 'smart-img.CMD');
+    assert(
+      fs.existsSync(binCmd) || fs.existsSync(path.join(capDir, 'node_modules', '.bin', 'smart-img')),
+      'smart-img bin required',
+    );
+    if (process.platform === 'win32' && fs.existsSync(binCmd)) {
+      const bin = spawnArgv(binCmd, ['doctor', '--json']);
+      assert(
+        `${bin.stdout || ''}${bin.stderr || ''}`.trim().length === 0,
+        `bin must be silent, got ${out(bin).slice(0, 200)}`,
+      );
+    }
+    for (const wrap of [runPnpm(['run', 'images:run', '--', 'doctor', '--json']), imgRun(['doctor', '--json'])]) {
+      assert(wrap.status === 0, `wrapper exit 0, got ${wrap.status}: ${wrap.stderr}`);
+      const parsed = JSON.parse((wrap.stdout || '').trim());
+      assert(parsed.command === 'doctor' || parsed.ok === true, 'doctor JSON');
+      assert(Array.isArray(parsed.details?.checks) || parsed.status === 'success', 'doctor checks');
+    }
+  });
+
+  await test('images:* never hooked from install/build/validate/CI; scripts exist', () => {
+    assert(REPO_ROOT, 'repo root');
+    const pkg = readJson(path.join(REPO_ROOT, 'package.json'));
+    const s = pkg.scripts || {};
+    assert(/frozen-lockfile/.test(s['images:setup'] || '') && /tools\/smart-image/.test(s['images:setup'] || ''));
+    assert(/tools\/smart-image\/run\.mjs/.test(s['images:run'] || ''));
+    assert(/tools\/smart-image\/check\.mjs/.test(s['images:check'] || ''));
+    for (const k of ['preinstall', 'postinstall', 'prepare', 'prepublishOnly', 'build', 'validate:data', 'ci:install']) {
+      assert(!/images:/.test(s[k] || ''), `${k} must not reference images:`);
+    }
+    const ci = path.join(REPO_ROOT, '.github');
+    if (fs.existsSync(ci)) {
+      /** @param {string} d */
+      const walk = (d) => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+          const f = path.join(d, e.name);
+          if (e.isDirectory()) walk(f);
+          else if (/\.ya?ml$/i.test(e.name)) {
+            assert(!/images:(check|setup|run)/.test(fs.readFileSync(f, 'utf8')), `CI ${f}`);
+          }
+        }
+      };
+      walk(ci);
+    }
+  });
+
+  await test('missing capsule / corrupt lock / offline setup remediate; provider is warning', () => {
+    assert(REPO_ROOT && fs.existsSync(checkJs) && fs.existsSync(capDir), 'capsule required');
+    for (const p of [
+      path.join(REPO_ROOT, 'tools', 'smart-image-MISSING', 'check.mjs'),
+      path.join(REPO_ROOT, 'tools', 'smart-image-MISSING', 'run.mjs'),
+    ]) {
+      const r = spawnSync(process.execPath, [p], { encoding: 'utf8', shell: false, windowsHide: true });
+      assert(r.error || r.status !== 0, `missing path must fail: ${p}`);
+    }
+
+    const tmpCap = fs.mkdtempSync(path.join(os.tmpdir(), 'si-cap-'));
+    const emptyStore = fs.mkdtempSync(path.join(os.tmpdir(), 'si-store-'));
+    try {
+      for (const f of ['package.json', 'pnpm-workspace.yaml', 'pnpm-lock.yaml', 'check.mjs', 'run.mjs']) {
+        fs.copyFileSync(path.join(capDir, f), path.join(tmpCap, f));
+      }
+      const noNm = spawnSync(process.execPath, [path.join(tmpCap, 'check.mjs')], {
+        encoding: 'utf8',
+        shell: false,
+        windowsHide: true,
+      });
+      assert(noNm.status === 1 && /images:setup|not ready|not installed/i.test(out(noNm)));
+      const noRun = spawnSync(process.execPath, [path.join(tmpCap, 'run.mjs'), 'doctor', '--json'], {
+        encoding: 'utf8',
+        shell: false,
+        windowsHide: true,
+      });
+      assert(noRun.status === 1 && /images:setup/i.test(out(noRun)));
+      const offline = runPnpm(
+        ['install', '--frozen-lockfile', '--dir', tmpCap, '--offline', '--store-dir', emptyStore],
+      );
+      assert(offline.status !== 0 && /ERR_|error|failed|offline|not found|ENOENT/i.test(out(offline)));
+    } finally {
+      fs.rmSync(tmpCap, { recursive: true, force: true });
+      fs.rmSync(emptyStore, { recursive: true, force: true });
+    }
+
+    const lockPath = path.join(capDir, 'pnpm-lock.yaml');
+    const lockOrig = fs.readFileSync(lockPath);
+    try {
+      fs.writeFileSync(lockPath, 'this: is: not: valid: lockfile\n');
+      const setup = runPnpm(['run', 'images:setup']);
+      assert(setup.status !== 0 && /ERR_|error|failed|lock/i.test(out(setup)));
+      const bad = imgCheck();
+      assert(bad.status === 1 && /corrupt|lockfile|not ready|Remediation|images:setup/i.test(out(bad)));
+    } finally {
+      fs.writeFileSync(lockPath, lockOrig);
+    }
+
+    const healthy = imgCheck();
+    assert(healthy.status === 0 && /ready/i.test(healthy.stdout || ''));
+
+    const emptyCfg = fs.mkdtempSync(path.join(os.tmpdir(), 'si-cfg-'));
+    try {
+      const env = {
+        ...process.env,
+        APPDATA: emptyCfg,
+        XDG_CONFIG_HOME: emptyCfg,
+        HOME: emptyCfg,
+        USERPROFILE: emptyCfg,
+      };
+      const warn = imgCheck({ env });
+      assert(warn.status === 0 && /ready/i.test(warn.stdout || ''));
+      assert(/warning:.*provider/i.test(warn.stderr || ''), warn.stderr);
+      const pick = imgRun(
+        [
+          'pick',
+          REPO_ROOT,
+          '--source',
+          'pixabay',
+          '--category',
+          'exterior',
+          '--orientation',
+          'landscape',
+          '--width',
+          '800',
+          '--height',
+          '600',
+          '--json',
+        ],
+        { env },
+      );
+      assert(pick.status !== 0, `provider pick must fail, got ${pick.status}`);
+      assert(
+        pick.status === 4 || /provider|api.?key|pixabay|failed|error/i.test(out(pick)),
+        out(pick).slice(0, 300),
+      );
+    } finally {
+      fs.rmSync(emptyCfg, { recursive: true, force: true });
+    }
+  });
+
+  // --- image-tooling scaffold / git isolation (Unit 3) ---
+  await test('isDeniedName covers every deny entry, rules, and near-miss negatives', () => {
+    const denyDirs = [
+      'node_modules',
+      'dist',
+      '.astro',
+      '.git',
+      '.codegraph',
+      'docs_trash',
+      'openspec',
+      'logs',
+      'packages',
+      '.atl',
+      'CUSTOMER-IMAGES',
+      '.img-ia',
+    ];
+    const denyFiles = ['package-lock.json'];
+    for (const name of denyDirs) {
+      assert(isDeniedName(name) === true, `deny dir ${name}`);
+    }
+    for (const name of denyFiles) {
+      assert(isDeniedName(name) === true, `deny file ${name}`);
+    }
+    assert(isDeniedName('debug.log') === true, '*.log rule');
+    assert(isDeniedName('app.log') === true, '*.log rule (app.log)');
+    assert(isDeniedName('.env') === true, '.env* rule');
+    assert(isDeniedName('.env.local') === true, '.env* rule (.env.local)');
+    assert(isDeniedName('.env.production') === true, '.env* rule (.env.production)');
+    // Near-miss / unrelated basenames must stay allowed
+    assert(isDeniedName('CUSTOMER-IMAGES.md') === false, 'CUSTOMER-IMAGES.md near-miss');
+    assert(isDeniedName('my-CUSTOMER-IMAGES') === false, 'my-CUSTOMER-IMAGES near-miss');
+    assert(isDeniedName('tools') === false, 'tools must never be denied');
+    assert(isDeniedName('smart-image') === false, 'smart-image basename allowed');
+    assert(isDeniedName('_out') === false, 'bare _out must never be denied');
+    assert(isDeniedName('README.sh') === false, 'README.sh alone is not denied');
+  });
+
+  await test('git check-ignore is root-relative for state and capsule node_modules only', () => {
+    assert(REPO_ROOT, 'expected local template root');
+    /**
+     * @param {string} rel
+     * @returns {boolean} true when git treats path as ignored
+     */
+    function isIgnored(rel) {
+      const r = spawnSync('git', ['check-ignore', '-q', '--', rel], {
+        cwd: REPO_ROOT,
+        encoding: 'utf8',
+        shell: false,
+        windowsHide: true,
+      });
+      if (r.error) throw r.error;
+      return r.status === 0;
+    }
+
+    // Directory patterns use trailing slash; also prove bare dir names when they exist.
+    assert(isIgnored('CUSTOMER-IMAGES/') === true, 'root CUSTOMER-IMAGES/ ignored');
+    assert(isIgnored('.img-ia/') === true, 'root .img-ia/ ignored');
+    assert(isIgnored('tools/smart-image/node_modules') === true, 'capsule node_modules ignored');
+    assert(isIgnored('tools/smart-image/node_modules/') === true, 'capsule node_modules/ ignored');
+
+    const probeCi = path.join(REPO_ROOT, 'CUSTOMER-IMAGES');
+    const probeImg = path.join(REPO_ROOT, '.img-ia');
+    /** @type {string[]} */
+    const probes = [];
+    try {
+      if (!fs.existsSync(probeCi)) {
+        fs.mkdirSync(probeCi, { recursive: true });
+        probes.push(probeCi);
+      }
+      if (!fs.existsSync(probeImg)) {
+        fs.mkdirSync(probeImg, { recursive: true });
+        probes.push(probeImg);
+      }
+      assert(isIgnored('CUSTOMER-IMAGES') === true, 'root CUSTOMER-IMAGES dir ignored');
+      assert(isIgnored('.img-ia') === true, 'root .img-ia dir ignored');
+      assert(isIgnored('CUSTOMER-IMAGES/secret.jpg') === true, 'root CUSTOMER-IMAGES child ignored');
+      assert(isIgnored('.img-ia/_out/x.png') === true, 'root .img-ia child ignored');
+    } finally {
+      for (const p of probes) {
+        try {
+          fs.rmSync(p, { recursive: true, force: true });
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    // Nested lookalikes remain trackable (root-anchored / patterns only).
+    // Avoid bare trailing-slash probes here: CRLF blank gitignore lines can
+    // confuse check-ignore's directory-only matching on some Windows git builds.
+    assert(isIgnored('src/CUSTOMER-IMAGES') === false, 'nested CUSTOMER-IMAGES trackable');
+    assert(isIgnored('src/CUSTOMER-IMAGES/photo.jpg') === false, 'nested CUSTOMER-IMAGES file trackable');
+    assert(isIgnored('docs/.img-ia') === false, 'nested .img-ia trackable');
+    assert(isIgnored('docs/.img-ia/readme') === false, 'nested .img-ia child trackable');
+    assert(isIgnored('packages/create-contractor-site/.img-ia') === false, 'nested package .img-ia trackable');
+
+    // Capsule source / manifest / lock / wrapper remain trackable
+    for (const rel of [
+      'tools/smart-image/package.json',
+      'tools/smart-image/pnpm-workspace.yaml',
+      'tools/smart-image/pnpm-lock.yaml',
+      'tools/smart-image/run.mjs',
+      'tools/smart-image/check.mjs',
+    ]) {
+      assert(isIgnored(rel) === false, `${rel} must remain trackable`);
+    }
+  });
+
+  await test('copyTemplate excludes denied parents, keeps unrelated _out, required misses loud', () => {
+    const src = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-deny-src-'));
+    const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-deny-dst-'));
+    try {
+      // Minimal template-shaped tree
+      fs.writeFileSync(path.join(src, 'keep.txt'), 'safe');
+      fs.mkdirSync(path.join(src, 'CUSTOMER-IMAGES'), { recursive: true });
+      fs.writeFileSync(path.join(src, 'CUSTOMER-IMAGES', 'secret.jpg'), 'NOCOPY');
+      fs.mkdirSync(path.join(src, '.img-ia', '_out'), { recursive: true });
+      fs.writeFileSync(path.join(src, '.img-ia', 'README.sh'), '#!/bin/sh\necho leak\n');
+      fs.writeFileSync(path.join(src, '.img-ia', '_out', 'candidate.png'), 'NOCOPY');
+      fs.mkdirSync(path.join(src, '_out'), { recursive: true });
+      fs.writeFileSync(path.join(src, '_out', 'client-keep.txt'), 'KEEP');
+      fs.mkdirSync(path.join(src, 'tools', 'smart-image'), { recursive: true });
+      fs.writeFileSync(path.join(src, 'tools', 'smart-image', 'run.mjs'), '// wrapper');
+
+      const { skipped } = copyTemplate(src, dest);
+      const skippedNorm = skipped.map((s) => s.replaceAll('\\', '/'));
+
+      assert(fs.existsSync(path.join(dest, 'keep.txt')), 'unrelated file copies');
+      assert(fs.existsSync(path.join(dest, '_out', 'client-keep.txt')), 'unrelated _out copies');
+      assert(fs.existsSync(path.join(dest, 'tools', 'smart-image', 'run.mjs')), 'tools/smart-image retained');
+      assert(!fs.existsSync(path.join(dest, 'CUSTOMER-IMAGES')), 'CUSTOMER-IMAGES excluded');
+      assert(!fs.existsSync(path.join(dest, '.img-ia')), '.img-ia excluded (parent deny)');
+      assert(
+        !fs.existsSync(path.join(dest, '.img-ia', 'README.sh')),
+        '.img-ia/README.sh absent — no recurse into denied parent',
+      );
+      assert(
+        !fs.existsSync(path.join(dest, '.img-ia', '_out', 'candidate.png')),
+        '.img-ia/_out bytes never copied',
+      );
+      assert(skippedNorm.includes('CUSTOMER-IMAGES'), 'skipped lists CUSTOMER-IMAGES');
+      assert(skippedNorm.includes('.img-ia'), 'skipped lists .img-ia');
+      assert(!skippedNorm.some((s) => s === '_out' || s.startsWith('_out/')), '_out not skipped');
+
+      // assertRequiredCopied: every required capsule/wrapper/skill path missing is reported
+      const stubRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-req-'));
+      try {
+        for (const rel of REQUIRED_AFTER_COPY) {
+          const full = path.join(stubRoot, ...rel.split('/'));
+          const looksFile = path.extname(rel) !== '' || rel.endsWith('package.json');
+          if (looksFile) {
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, 'x');
+          } else {
+            fs.mkdirSync(full, { recursive: true });
+          }
+        }
+        assert(assertRequiredCopied(stubRoot).length === 0, 'full stub must pass required check');
+
+        const requiredMustExist = [
+          'tools/smart-image/package.json',
+          'tools/smart-image/pnpm-workspace.yaml',
+          'tools/smart-image/pnpm-lock.yaml',
+          'tools/smart-image/run.mjs',
+          'tools/smart-image/check.mjs',
+          '.agents/skills/smart-image-cli/SKILL.md',
+        ];
+        for (const rel of requiredMustExist) {
+          assert(
+            REQUIRED_AFTER_COPY.includes(rel),
+            `REQUIRED_AFTER_COPY must list ${rel}`,
+          );
+        }
+
+        for (const rel of requiredMustExist) {
+          const full = path.join(stubRoot, ...rel.split('/'));
+          fs.rmSync(full, { force: true });
+          const missing = assertRequiredCopied(stubRoot);
+          assert(missing.includes(rel), `missing must report ${rel}, got ${missing.join(',')}`);
+          // restore for next iteration
+          fs.mkdirSync(path.dirname(full), { recursive: true });
+          fs.writeFileSync(full, 'x');
+        }
+      } finally {
+        fs.rmSync(stubRoot, { recursive: true, force: true });
+      }
+    } finally {
+      fs.rmSync(src, { recursive: true, force: true });
+      fs.rmSync(dest, { recursive: true, force: true });
+    }
+  });
+
   const skipE2E = process.env.SKIP_CLI_E2E === '1';
   if (skipE2E) {
     console.log('\n  ↷ SKIP_CLI_E2E=1 — skipping temp-target full scaffold');
   } else {
+    /** @type {string[]} */
+    const e2eSeeds = [];
+    if (REPO_ROOT) {
+      const seedCi = path.join(REPO_ROOT, 'CUSTOMER-IMAGES');
+      const seedImgIaRoot = path.join(REPO_ROOT, '.img-ia');
+      if (!fs.existsSync(seedCi)) {
+        fs.mkdirSync(seedCi, { recursive: true });
+        fs.writeFileSync(path.join(seedCi, 'e2e-secret.jpg'), 'NOCOPY');
+        e2eSeeds.push(seedCi);
+      }
+      if (!fs.existsSync(seedImgIaRoot)) {
+        fs.mkdirSync(path.join(seedImgIaRoot, '_out'), { recursive: true });
+        fs.writeFileSync(path.join(seedImgIaRoot, '_out', 'e2e-candidate.png'), 'NOCOPY');
+        e2eSeeds.push(seedImgIaRoot);
+      }
+    }
+    try {
     await test('temp-target --yes scaffold install/validate/build/git', () => {
       assert(REPO_ROOT, 'expected local template root for E2E');
       const target = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-e2e-'));
@@ -1138,6 +1660,21 @@ async function main() {
         !fs.existsSync(path.join(targetDir, 'packages')),
         'packages/ must not be copied',
       );
+      assert(!fs.existsSync(path.join(targetDir, 'CUSTOMER-IMAGES')), 'CUSTOMER-IMAGES excluded');
+      assert(!fs.existsSync(path.join(targetDir, '.img-ia')), '.img-ia excluded');
+      assert(fs.existsSync(path.join(targetDir, 'tools', 'smart-image', 'package.json')), 'capsule manifest');
+      assert(fs.existsSync(path.join(targetDir, 'tools', 'smart-image', 'pnpm-workspace.yaml')), 'capsule workspace');
+      assert(fs.existsSync(path.join(targetDir, 'tools', 'smart-image', 'pnpm-lock.yaml')), 'capsule lock');
+      assert(fs.existsSync(path.join(targetDir, 'tools', 'smart-image', 'run.mjs')), 'wrapper run.mjs');
+      assert(fs.existsSync(path.join(targetDir, 'tools', 'smart-image', 'check.mjs')), 'wrapper check.mjs');
+      assert(
+        fs.existsSync(path.join(targetDir, '.agents', 'skills', 'smart-image-cli', 'SKILL.md')),
+        'skill retained',
+      );
+      const tgtPkg = JSON.parse(fs.readFileSync(path.join(targetDir, 'package.json'), 'utf8'));
+      for (const k of ['images:check', 'images:setup', 'images:run']) {
+        assert(typeof tgtPkg.scripts?.[k] === 'string', `scaffold scripts must include ${k}`);
+      }
 
       const business = JSON.parse(
         fs.readFileSync(path.join(targetDir, 'src/data/business.json'), 'utf8'),
@@ -1198,6 +1735,15 @@ async function main() {
         console.warn(`    (could not fully remove ${targetDir})`);
       }
     });
+    } finally {
+      for (const p of e2eSeeds) {
+        try {
+          fs.rmSync(p, { recursive: true, force: true });
+        } catch {
+          // ignore seed cleanup failures
+        }
+      }
+    }
   }
 
   console.log(`\n${passed} passed, ${failed} failed`);

package/src/copy-template.mjs

@@ -17,6 +17,9 @@ const DENY_DIR_NAMES = new Set([
   // CLI package + internal agent tooling — not part of a client site
   'packages',
   '.atl',
+  // Image-tooling runtime state only (exact basename; never bare _out or tools)
+  'CUSTOMER-IMAGES',
+  '.img-ia',
 ]);
 
 const DENY_FILE_NAMES = new Set(['package-lock.json']);
@@ -27,7 +30,7 @@ export const DEFAULT_TEMPLATE_REPO =
   'https://github.com/glacayo/website-multipages.git';
 
 export const DEFAULT_TEMPLATE_REF =
-  process.env.CREATE_CONTRACTOR_TEMPLATE_REF || 'v2.2.0';
+  process.env.CREATE_CONTRACTOR_TEMPLATE_REF || 'v2.3.0';
 
 /**
  * @param {string} name basename
@@ -267,6 +270,13 @@ export const REQUIRED_AFTER_COPY = [
   'scripts/enforce-package-manager.cjs',
   'src/assets/images',
   'src/data/business.json',
+  // Smart-image capsule + agent skill (must scaffold with every client site)
+  'tools/smart-image/package.json',
+  'tools/smart-image/pnpm-workspace.yaml',
+  'tools/smart-image/pnpm-lock.yaml',
+  'tools/smart-image/run.mjs',
+  'tools/smart-image/check.mjs',
+  '.agents/skills/smart-image-cli/SKILL.md',
 ];
 
 /**