@port60/template-kit 0.8.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/%40port60%2Ftemplate-kit)](https://www.npmjs.com/package/@port60/template-kit)
 [![CI](https://github.com/Port60Labs/template-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Port60Labs/template-kit/actions/workflows/ci.yml)
 
-The official toolkit for building [Port60](https://port60.com) site templates — scaffold from
+The official toolkit for building [Port60](https://port60.com) site templates, scaffold from
 the starter, preview locally against the platform contract, validate with the exact checks the
 platform runs at upload, and package for review.
 
@@ -14,13 +14,17 @@ owns how a site looks.
 ## Quickstart
 
 ```bash
-npx @port60/template-kit create my-template --name my-template
+npx @port60/template-kit create my-template   # the folder name IS the template name
 cd my-template && npm install
 npm run dev        # live preview at http://localhost:4400
 npm run validate   # the platform's conformance checks
 npm run package    # the uploadable <name>-<version>.zip
 ```
 
+Already building? `npx @port60/template-kit@latest upgrade` moves an existing template onto
+the latest kit and contract, regenerates the agent briefing, and reports what (if anything) the
+newer contract asks of you.
+
 ## Commands
 
 | Command | What it does |
@@ -29,6 +33,9 @@ npm run package    # the uploadable <name>-<version>.zip
 | `dev [dir]` | Live preview over the contract's sample fixtures; validation re-runs on save. |
 | `validate [dir] [--json]` | The exact checks the platform runs at upload. `--json` emits `{ok, errors, warnings, provenSupports}`. |
 | `package [dir]` | Validate, then build the contract-shaped zip the studio accepts as-is. |
+| `model [--json]` | The content model, in hand; `--json` for agents. |
+| `content [dir]` | Eject the model's data as your editable copy; render it with `dev --content`. |
+| `upgrade [dir]` | Latest kit + contract for an existing template; re-briefs and re-validates. |
 
 ## Building with an AI agent
 
@@ -41,7 +48,7 @@ See the [AI quickstart](https://developers.port60.com/guides/ai-quickstart/).
 
 ## The contract
 
-The vendored contract in `src/vendor/contract` is the **Charity Platform contract v1** — the
+The vendored contract in `src/vendor/contract` is the **Charity Platform contract v1**, the
 platform's first product surface. The dialect, validation rules and this toolchain are
 platform-wide; future Port60 products ship their own contract packs for the same kit.
 

package/bin/cli.mjs

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
-// @port60/template-kit — build Port60 site templates locally. AI-agent ready: `create` scaffolds
+// @port60/template-kit, build Port60 site templates locally. AI-agent ready: `create` scaffolds
 // an AGENTS.md-briefed project; `validate --json` is the machine feedback loop; `dev` is the
 // human's live preview; `package` produces the uploadable artifact.
 import { create } from '../src/commands/create.mjs';
 import { validate } from '../src/commands/validate.mjs';
 import { dev } from '../src/commands/dev.mjs';
 import { packageCmd } from '../src/commands/packageCmd.mjs';
+import { model } from '../src/commands/model.mjs';
+import { content } from '../src/commands/content.mjs';
+import { upgrade } from '../src/commands/upgrade.mjs';
+import { refresh } from '../src/commands/refresh.mjs';
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -37,6 +41,18 @@ switch (command) {
   case 'validate':
     await validate(args);
     break;
+  case 'model':
+    model(args);
+    break;
+  case 'content':
+    content(args);
+    break;
+  case 'upgrade':
+    upgrade(args);
+    break;
+  case 'refresh':
+    await refresh(args);
+    break;
   case 'dev':
     await dev(args);
     break;
@@ -44,13 +60,19 @@ switch (command) {
     await packageCmd(args);
     break;
   default:
-    console.log(`@port60/template-kit — build Port60 site templates locally
+    console.log(`@port60/template-kit, build Port60 site templates locally
 
 usage:
-  p60-template-kit create <dir> [--name my-template] [--label "My Template"]
-  p60-template-kit dev [dir] [--port 4400]     live preview over the contract fixtures
+  p60-template-kit create <dir>                scaffold a template (name = the folder;
+                                               --name/--label override the identity)
+  p60-template-kit dev [dir] [--port 4400] [--content my.json]
+                                               live preview; --content renders YOUR data
+  p60-template-kit model [--json]              the content model, in hand (--json for agents)
+  p60-template-kit content [dir] [--out file]  eject the model's data as your editable copy
   p60-template-kit validate [dir] [--json]     the platform's exact conformance checks
   p60-template-kit package [dir]               validate + build the uploadable zip
+  p60-template-kit upgrade [dir]               move an existing template to the latest kit
+                                               and contract, re-brief, re-validate
 
 AI agents: the scaffold's AGENTS.md is your briefing; iterate with \`validate --json\`.
 Docs: https://developers.port60.com (agents: /llms-full.txt)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready — every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
   "type": "module",
   "bin": {

package/src/commands/content.mjs

@@ -0,0 +1,42 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildSiteFixture, validatePreviewContent } from '../vendor/validator/site-context.mjs';
+
+/**
+ * `content [dir] [--out file] [--force]`, EJECT the content model's data as your hard copy.
+ * Writes every overridable `site.content.*` collection, fully populated with the canonical
+ * organisation's data, as one editable JSON file. Replace the copy, swap the imagery for your
+ * own URLs, then hand it back:
+ *
+ *   p60-template-kit content .                 → writes ./preview-content.json
+ *   p60-template-kit dev . --content my.json   → the preview renders YOUR data
+ *
+ * The shape stays the platform's (schema-checked on every read, a field that does not exist in
+ * production cannot exist in a preview); the data becomes yours. `about` is not ejected: it is
+ * your template's own section composition, derived from the manifest.
+ */
+export function content(args) {
+  const dir = resolve(args._[0] ?? '.');
+  const out = resolve(dir, typeof args.out === 'string' ? args.out : 'preview-content.json');
+  if (existsSync(out) && !args.force) {
+    console.error(`✗ ${out} already exists, pass --force to overwrite it.`);
+    process.exit(1);
+  }
+  const site = buildSiteFixture(null);
+  const data = {
+    brand: site.brand,
+    ...Object.fromEntries(Object.entries(site.content).filter(([name]) => name !== 'about'))
+  };
+  const problems = validatePreviewContent(data);
+  if (problems.length > 0) {
+    // The eject is generated FROM the model, so this firing means the kit itself is broken.
+    console.error('✗ internal error, the ejected content does not validate:');
+    for (const problem of problems) console.error(`  - ${problem}`);
+    process.exit(1);
+  }
+  writeFileSync(out, JSON.stringify(data, null, 2) + '\n');
+  console.log(`✓ content model data written to ${out}`);
+  console.log('  Edit the copy, swap imageUrl values for your own hosted images, then:');
+  console.log(`    p60-template-kit dev ${args._[0] ?? '.'} --content ${typeof args.out === 'string' ? args.out : 'preview-content.json'}`);
+  console.log('  Shape is fixed (schema-checked every read); the data is yours. Never packaged.');
+}

package/src/commands/create.mjs

@@ -3,8 +3,11 @@ import { resolve, join, basename } from 'node:path';
 import { agentsMd } from '../lib/agentsMd.mjs';
 
 const NAME_PATTERN = /^[a-z][a-z0-9-]{1,48}[a-z0-9]$/;
+const KIT_PACKAGE = JSON.parse(
+  readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8')
+);
 
-/** `create <dir> [--name x] [--label "X"]` — a working, validating template from the starter,
+/** `create <dir> [--name x] [--label "X"]`, a working, validating template from the starter,
  *  briefed for AI agents (AGENTS.md + CLAUDE.md) and wired with the kit's npm scripts. */
 export function create(args) {
   const dir = args._[0];
@@ -32,7 +35,7 @@ export function create(args) {
   manifest.name = name;
   manifest.version = '0.1.0';
   manifest.label = label;
-  manifest.description = `${label} — a Port60 site template.`;
+  manifest.description = `${label}, a Port60 site template.`;
   manifest.changelog = 'First cut from the starter.';
   writeFileSync(join(target, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
 
@@ -50,18 +53,18 @@ export function create(args) {
       package: 'p60-template-kit package .'
     },
     devDependencies: {
-      '@port60/template-kit': '^0.1.0'
+      '@port60/template-kit': `^${KIT_PACKAGE.version}`
     }
   }, null, 2) + '\n');
   writeFileSync(join(target, 'README.md'), `# ${label}
 
 A Port60 site template. Start with \`npm install\`, then:
 
-- \`npm run dev\` — live preview at http://localhost:4400
-- \`npm run validate\` — conformance against the platform contract
-- \`npm run package\` — the uploadable zip
+- \`npm run dev\`, live preview at http://localhost:4400
+- \`npm run validate\`, conformance against the platform contract
+- \`npm run package\`, the uploadable zip
 
-**Working with an AI agent?** Point it at this directory — \`AGENTS.md\` (and \`CLAUDE.md\`)
+**Working with an AI agent?** Point it at this directory, \`AGENTS.md\` (and \`CLAUDE.md\`)
 brief it on the contract, the rules and the validate loop.
 
 Docs: https://developers.port60.com

package/src/commands/dev.mjs

@@ -1,24 +1,139 @@
 import { createServer } from 'node:http';
-import { watch } from 'node:fs';
+import { watch, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { renderStudioPreview } from '../vendor/validator/preview.mjs';
 import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { applyPreviewContent, buildSiteFixture, validatePreviewContent } from '../vendor/validator/site-context.mjs';
+import { renderModelReferenceHtml } from '../vendor/validator/model-reference.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
+import { join } from 'node:path';
 
 /**
- * `dev <dir> [--port 4400]` — the local preview: your template over the contract's kind fixtures,
- * the SAME render the studio and reviewers see (islands as placeholders, network-dead CSP).
- * Files are re-read on every request, so a browser refresh is the hot reload; file changes also
- * re-run validation into the terminal — the human watches the page, the agent watches the JSON.
+ * The author's optional preview data (content model v1): preview-content.json beside the
+ * manifest replaces site.content collections wholesale for THIS preview, data is free, shape is
+ * fixed (schema-validated every read; problems land in the terminal and the canonical fixtures
+ * render instead). Hot like everything else: re-read on every request, never packaged, refused
+ * by the upload intake.
+ */
+function loadPreviewContent(dir, explicitPath) {
+  const path = explicitPath ?? join(dir, 'preview-content.json');
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    if (explicitPath) console.error(`✗ --content file not found: ${explicitPath}, using the canonical fixtures`);
+    return null; // no file, the canonical fixtures render
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (e) {
+    console.error(`✗ preview-content.json is not valid JSON (${e.message}), using the canonical fixtures`);
+    return null;
+  }
+  const problems = validatePreviewContent(json);
+  if (problems.length > 0) {
+    console.error('✗ preview-content.json ignored, the shape is fixed even though the data is yours:');
+    for (const problem of problems) console.error(`  - ${problem}`);
+    return null;
+  }
+  return json;
+}
+
+/** The origins of every absolute URL in the override, the hosts the dev CSP must admit. */
+function imageOriginsOf(json) {
+  const origins = new Set();
+  const walk = (value) => {
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+    } else if (value && typeof value === 'object') {
+      for (const [key, inner] of Object.entries(value)) {
+        // Imagery fields only (imageUrl, logoUrl, …), a directions link is a URL too, and the
+        // CSP should admit exactly the hosts that will be ASKED for pixels.
+        if (/Url$/.test(key) && typeof inner === 'string' && /^https?:\/\//.test(inner)) {
+          try {
+            origins.add(new URL(inner).origin);
+          } catch {
+            // not a URL after all, nothing to admit
+          }
+        } else {
+          walk(inner);
+        }
+      }
+    }
+  };
+  walk(json);
+  return [...origins];
+}
+
+/**
+ * `dev <dir> [--port 4400]`, the local preview: your template over the contract's kind fixtures,
+ * the SAME render the studio and reviewers see (islands as fixture-hydrated skeletons,
+ * network-dead CSP). ONE addition over the studio render: the platform's own behaviour runtime is
+ * inlined, so data-p60-* carousels, reveals and tabs run for real locally, the only script the
+ * document can execute. Files are re-read on every request, so a browser refresh is the hot
+ * reload; file changes also re-run validation into the terminal, the human watches the page,
+ * the agent watches the JSON.
  */
 export async function dev(args) {
   const dir = resolve(args._[0] ?? '.');
   const port = Number(args.port ?? 4400);
+  // The dev-richer half of the imagery split: point P60_FIXTURE_IMAGES at the platform's fixture
+  // imagery base and the preview loads photographic fixtures from that ONE origin instead of the
+  // sealed inline-SVG art. Unset (the default), the preview stays fully network-dead.
+  const fixtureImageBase = process.env.P60_FIXTURE_IMAGES || null;
+  // `--content my-org.json` points the preview at YOUR data (an ejected, edited copy of the
+  // content model, see the `content` command). Without it, preview-content.json beside the
+  // manifest is picked up by convention. Hot either way: re-read on every request.
+  // Relative --content paths resolve against the TEMPLATE dir (matching the eject hint);
+  // absolute paths pass through untouched.
+  const contentPath = typeof args.content === 'string' ? resolve(dir, args.content) : null;
+  let behaviorsRuntime = null;
+  try {
+    behaviorsRuntime = readFileSync(
+      resolve(import.meta.dirname, '../vendor/validator/behaviors-runtime.js'), 'utf8');
+  } catch {
+    // An older vendored copy without the runtime, the preview degrades to the CSS approximation.
+  }
+
+  // The preview is ROUTED: nav links land on real surfaces, so an author sees every platform
+  // page wearing their chrome, their own page template where they ship one, the platform's
+  // fixture skeleton where the page is platform-owned (ticket purchase, donate, campaigns).
+  const surfaceFor = (rawUrl) => {
+    const url = new URL(rawUrl, 'http://preview.local');
+    const path = url.pathname.replace(/\/+$/, '') || '/';
+    if (path === '/events') return url.searchParams.has('event') ? 'event' : 'events';
+    if (path === '/services') return url.searchParams.has('service') ? 'service' : 'services';
+    if (path === '/donate') return 'donate';
+    if (path === '/articles' || path === '/articles/all') return 'articles';
+    if (path.startsWith('/articles/')) return 'article';
+    if (path === '/campaigns') return 'campaigns';
+    if (path.startsWith('/campaigns/')) return 'campaign';
+    if (path === '/courses') return 'course';
+    return 'home';
+  };
 
   const server = createServer(async (req, res) => {
     try {
       const files = loadArtifactDir(dir);
-      const html = await renderStudioPreview(files);
+      const url = new URL(req.url ?? '/', 'http://preview.local');
+      if (url.pathname === '/model') {
+        // The model, where the developer lives: the registry beside the LIVE data this preview
+        // renders (preview-content.json overlay included).
+        const manifest = JSON.parse(files['manifest.json'] ?? '{}');
+        const site = applyPreviewContent(buildSiteFixture(manifest), loadPreviewContent(dir, contentPath));
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+        res.end(renderModelReferenceHtml(site));
+        return;
+      }
+      const previewContent = loadPreviewContent(dir, contentPath);
+      const html = await renderStudioPreview(files, {
+        behaviorsRuntime,
+        fixtureImageBase,
+        previewContent,
+        contentImageOrigins: imageOriginsOf(previewContent),
+        surface: surfaceFor(req.url ?? '/')
+      });
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
       res.end(html);
     } catch (e) {
@@ -29,12 +144,23 @@ export async function dev(args) {
 <h1>The template didn't render</h1>
 <p><code>${String(e instanceof Error ? e.message : e).replace(/</g, '&lt;')}</code></p>
 ${errors.length ? `<h2>Validation says</h2><ul>${errors.map((x) => `<li>${String(x).replace(/</g, '&lt;')}</li>`).join('')}</ul>` : ''}
-<p>Fix and refresh — files are re-read on every request.</p>`);
+<p>Fix and refresh, files are re-read on every request.</p>`);
+    }
+  });
+
+  // A taken port is the most likely first-run failure (a forgotten dev server from another
+  // template), and a raw EADDRINUSE stack reads like the kit is broken. Name the fix instead.
+  server.on('error', (e) => {
+    if (e.code === 'EADDRINUSE') {
+      console.error(`✗ port ${port} is already in use, another preview is probably still running.`);
+      console.error(`  Stop it, or start this one elsewhere:  p60-template-kit dev ${args._[0] ?? '.'} --port ${port + 1}`);
+      process.exit(1);
     }
+    throw e;
   });
 
   server.listen(port, () => {
-    console.log(`✓ preview at http://localhost:${port} — refresh after edits`);
+    console.log(`✓ preview at http://localhost:${port}, refresh after edits`);
     console.log('  watching for changes; validation runs on save:');
   });
 

package/src/commands/model.mjs

@@ -0,0 +1,34 @@
+import { contentModel } from '../vendor/engine/content-footprint.mjs';
+
+/**
+ * `model [--json]`, the content model, in hand. Prints every `site.content.*` collection with
+ * its bound, its onward link and its fields; `--json` emits the registry verbatim for agents
+ * (the same file the validator and the production renderer enforce, so it cannot drift).
+ * The dev server serves the same reference with live example data at /model.
+ */
+export function model(args) {
+  if (args.json) {
+    console.log(JSON.stringify(contentModel, null, 2));
+    return;
+  }
+  console.log(`site.content, content model ${contentModel.version}`);
+  console.log('site also carries: ' + contentModel.siblings.keys.map((k) => `site.${k}`).join(', '));
+  console.log('');
+  for (const [name, collection] of Object.entries(contentModel.collections)) {
+    const more = collection.moreHref ? ` · more at ${collection.moreHref}` : '';
+    console.log(`site.content.${name}  (bounded at ${collection.cap}${more}, since ${collection.since})`);
+    for (const [field, spec] of Object.entries(collection.item)) {
+      const notes = [
+        spec.nullable ? 'nullable' : null,
+        spec.enumOpen ? `open enum${spec.enumOpen.length ? `: ${spec.enumOpen.join('|')}` : ''}` : null,
+        spec.max ? `max ${spec.max}` : null
+      ].filter(Boolean).join(', ');
+      console.log(`    ${field}: ${spec.type}${notes ? `  (${notes})` : ''}`);
+    }
+    console.log('');
+  }
+  console.log('Rules: collections are bounded (link onward via moreHref); enums are open (branch and');
+  console.log('fall back); nullable fields need a branch; the model only grows. Your footprint and');
+  console.log('minimum model version are computed at publish, you never declare them. Live examples:');
+  console.log('the /model page on your dev preview.');
+}

package/src/commands/packageCmd.mjs

@@ -5,16 +5,16 @@ import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 
 /**
- * `package <dir>` — validate first (the platform will run the identical checks, so failing here
+ * `package <dir>`, validate first (the platform will run the identical checks, so failing here
  * saves the round trip), then zip EXACTLY the contract-shaped file set into
- * `<name>-<version>.zip` — the artifact the studio's upload lane accepts as-is.
+ * `<name>-<version>.zip`, the artifact the studio's upload lane accepts as-is.
  */
 export async function packageCmd(args) {
   const dir = resolve(args._[0] ?? '.');
   const files = loadArtifactDir(dir);
   const { errors, manifest } = await validateArtifact(files);
   if (errors.length > 0) {
-    console.error(`✗ not packaging — ${errors.length} validation error${errors.length === 1 ? '' : 's'}:`);
+    console.error(`✗ not packaging, ${errors.length} validation error${errors.length === 1 ? '' : 's'}:`);
     for (const e of errors) console.error(`  - ${e}`);
     process.exit(1);
   }

package/src/commands/refresh.mjs

@@ -0,0 +1,48 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { agentsMd } from '../lib/agentsMd.mjs';
+import { loadArtifactDir } from '../lib/artifactFiles.mjs';
+import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { contentModel } from '../vendor/engine/content-footprint.mjs';
+import dialect from '../vendor/contract/v1/dialect.json' with { type: 'json' };
+
+const KIT_PACKAGE = JSON.parse(
+  readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8')
+);
+
+/**
+ * `refresh [dir]`, regenerate the GENERATED files against the installed kit and report where the
+ * template stands. Rewrites AGENTS.md and CLAUDE.md (they are the kit's briefing, generated at
+ * create time and stale the moment the contract moves, your own notes belong in README.md),
+ * prints the versions in force, and runs the full conformance check so an upgrade immediately
+ * shows what, if anything, the newer contract asks of you. Template sources are never touched.
+ */
+export async function refresh(args) {
+  const dir = resolve(args._[0] ?? '.');
+  const files = loadArtifactDir(dir);
+  if (!files['manifest.json']) {
+    console.error(`✗ ${dir} does not contain a template (no manifest.json).`);
+    process.exit(1);
+  }
+  const manifest = JSON.parse(files['manifest.json']);
+
+  const briefing = agentsMd(manifest.name);
+  writeFileSync(join(dir, 'AGENTS.md'), briefing);
+  writeFileSync(join(dir, 'CLAUDE.md'), briefing);
+
+  console.log(`✓ kit ${KIT_PACKAGE.version} · contract ${dialect.format} · content model ${contentModel.version}`);
+  console.log('✓ AGENTS.md and CLAUDE.md regenerated for this contract');
+
+  const { errors, warnings, contentFootprint, minContentVersion } = await validateArtifact(files);
+  if (contentFootprint?.length) {
+    console.log(`  content footprint: ${contentFootprint.join(', ')}`
+        + (minContentVersion ? ` (minimum model ${minContentVersion})` : ''));
+  }
+  if (errors.length === 0) {
+    console.log(`✓ ${manifest.name}@${manifest.version} conforms${warnings.length ? ` (${warnings.length} warning${warnings.length === 1 ? '' : 's'})` : ''}, nothing to change.`);
+  } else {
+    console.log(`✗ the current contract asks ${errors.length} thing${errors.length === 1 ? '' : 's'} of this template:`);
+    for (const e of errors) console.log(`    - ${e}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/upgrade.mjs

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * `upgrade [dir]`, bring an EXISTING template onto the latest kit and contract. The scaffold
+ * pins the kit as a devDependency and every script runs the local copy, so the whole enforcement
+ * surface (contract, content model, validator, preview, behaviour runtime) upgrades with one
+ * install; this command does that install and then hands over to the FRESHLY INSTALLED kit's
+ * `refresh` to regenerate the agent briefing and report what the new contract thinks of your
+ * template. Your template sources are never touched, only the generated briefing files.
+ *
+ * Run it as `npx @port60/template-kit@latest upgrade` (or `p60-template-kit upgrade` from an
+ * installed copy, the delegation makes either safe).
+ */
+export function upgrade(args) {
+  const dir = resolve(args._[0] ?? '.');
+  if (!existsSync(join(dir, 'manifest.json'))) {
+    console.error(`✗ ${dir} does not contain a template (no manifest.json).`);
+    process.exit(1);
+  }
+  if (!existsSync(join(dir, 'package.json'))) {
+    console.error(`✗ ${dir} has no package.json, scaffolds created by this kit pin it as a devDependency.`);
+    console.error('  Add it yourself: npm init -y && npm install --save-dev @port60/template-kit@latest');
+    process.exit(1);
+  }
+
+  console.log('▸ installing the latest kit…');
+  const install = spawnSync('npm', ['install', '--save-dev', '@port60/template-kit@latest'],
+      { cwd: dir, stdio: 'inherit' });
+  if (install.status !== 0) {
+    console.error('✗ npm install failed, nothing else was changed.');
+    process.exit(install.status ?? 1);
+  }
+
+  // The refresh must run on the NEW version (this process may be an older one).
+  const localCli = join(dir, 'node_modules', '@port60', 'template-kit', 'bin', 'cli.mjs');
+  const refresh = spawnSync(process.execPath, [localCli, 'refresh', dir], { stdio: 'inherit' });
+  if (refresh.status !== 0) {
+    // An older kit without `refresh` (or a refresh failure): the install still happened.
+    console.log('✓ kit upgraded. This version has no refresh step, run `npm run validate` to see');
+    console.log('  what the new contract thinks of your template.');
+  }
+}

package/src/commands/validate.mjs

@@ -3,9 +3,8 @@ import { validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 
 /**
- * `validate <dir> [--json]` — the exact checks the platform runs at upload, plus the T3 promise:
- * **supports as an OUTPUT**. On a clean pass the manifest's supports block IS the proven set —
- * the validator's two-way honesty checks (declared ⇒ renders the fixture, renders ⇒ declared)
+ * `validate <dir> [--json]`, the exact checks the platform runs at upload, plus the T3 promise:
+ * **supports as an OUTPUT**. On a clean pass the manifest's supports block IS the proven set, * the validator's two-way honesty checks (declared ⇒ renders the fixture, renders ⇒ declared)
  * are what turn a declaration into proof. `--json` is the AI agent's feedback loop: iterate
  * until {ok: true}.
  */