@port60/template-kit 0.9.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.9.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

@@ -7,7 +7,7 @@ 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];
@@ -35,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');
 
@@ -60,11 +60,11 @@ export function create(args) {
 
 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

@@ -3,30 +3,101 @@ 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 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
+ * 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,
+ * 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.
+    // 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
+  // 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');
@@ -45,7 +116,24 @@ export async function dev(args) {
   const server = createServer(async (req, res) => {
     try {
       const files = loadArtifactDir(dir);
-      const html = await renderStudioPreview(files, { behaviorsRuntime, surface: surfaceFor(req.url ?? '/') });
+      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) {
@@ -56,7 +144,7 @@ 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>`);
     }
   });
 
@@ -64,7 +152,7 @@ ${errors.length ? `<h2>Validation says</h2><ul>${errors.map((x) => `<li>${String
   // 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(`✗ 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);
     }
@@ -72,7 +160,7 @@ ${errors.length ? `<h2>Validation says</h2><ul>${errors.map((x) => `<li>${String
   });
 
   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}.
  */

package/src/lib/agentsMd.mjs

@@ -1,13 +1,12 @@
 // The scaffold's AI-agent briefing (T3, user requirement: the kit must let people put an AI
-// engine on template work and be productive immediately). Written for ANY coding agent —
-// AGENTS.md is the cross-tool convention and CLAUDE.md carries the identical content for tools
+// engine on template work and be productive immediately). Written for ANY coding agent, // AGENTS.md is the cross-tool convention and CLAUDE.md carries the identical content for tools
 // that read that name. The briefing is the contract's rules + the iteration loop, so an agent's
 // first move is always the same: read this, edit, validate --json, repeat until clean.
 
 export function agentsMd(name) {
   return `# Working on the "${name}" Port60 template
 
-You are working on a **Port60 site template** — a small, versioned artifact of Liquid renderers
+You are working on a **Port60 site template**, a small, versioned artifact of Liquid renderers
 and CSS that a charity's site is rendered through. It contains **no application code**: no
 JavaScript, no API calls, no payment logic. Templates decide how a site *looks*; the platform
 owns what it *does*.
@@ -22,25 +21,25 @@ npm run package           # validate + produce the uploadable <name>-<version>.z
 \`\`\`
 
 **After every meaningful edit, run \`npm run validate:json\` and fix every error before moving
-on.** The validator is the exact code the platform runs at upload — if it passes here, the
+on.** The validator is the exact code the platform runs at upload, if it passes here, the
 platform accepts it; if it fails here, the upload will fail identically.
 
 ## The file layout (nothing else is accepted)
 
-- \`manifest.json\` — identity + what you support. \`name\` and \`version\` are immutable
+- \`manifest.json\`, identity + what you support. \`name\` and \`version\` are immutable
   identity; bump \`version\` (semver) for every published change.
-- \`layout.liquid\` — the page chrome (header/nav/footer). Must contain **exactly one**
+- \`layout.liquid\`, the page chrome (header/nav/footer). Must contain **exactly one**
   \`{% content %}\` slot. Only needed when \`supports.layout\` is true.
-- \`sections/<type>.liquid\` — one renderer per section type you declare in
+- \`sections/<type>.liquid\`, one renderer per section type you declare in
   \`supports.sections\`. Charities compose pages from a **closed catalogue** of section types
-  (see \`npm run validate\` output or the docs) — you cannot invent new types.
-- \`pages/<page>.liquid\` — optional full-page templates for \`supports.pageTemplates\`.
-- \`assets/theme.css\` — required, your entire look. More \`.css\` files under \`assets/\` are
-  allowed. **No images, no JS** — they are refused at upload.
+  (see \`npm run validate\` output or the docs), you cannot invent new types.
+- \`pages/<page>.liquid\`, optional full-page templates for \`supports.pageTemplates\`.
+- \`assets/theme.css\`, required, your entire look. More \`.css\` files under \`assets/\` are
+  allowed. **No images, no JS**, they are refused at upload.
 
 ## The rules the validator enforces (do not fight them)
 
-1. **Escape-by-default.** Every output is HTML-escaped unless you use \`| raw\` — and the only
+1. **Escape-by-default.** Every output is HTML-escaped unless you use \`| raw\`, and the only
    values you may pass through raw are the contract's sanitised richtext fields.
 2. **The dialect is a whitelist.** \`{% include %}\`, \`{% render %}\`, \`{% layout %}\` and
    several other tags are excluded and fail at parse. Unknown filters throw.
@@ -55,7 +54,7 @@ platform accepts it; if it fails here, the upload will fail identically.
 5. **Render budgets are real.** Runaway loops are killed (~1s per render). Keep renderers simple.
 6. **Context is a whitelist.** Sections see \`{section, brand}\` plus only the collection named by
    that section in the contract; layouts see \`{brand, nav, socials, worship, locale}\`; page
-   templates see their documented fixture + \`brand\`. Nothing else exists — do not invent
+   templates see their documented fixture + \`brand\`. Nothing else exists, do not invent
    variables.
 7. **Capabilities are matching metadata, never entitlements.** Every value in
    \`requiresCapabilities\` must have a declared section, page template or island that presents it.
@@ -77,15 +76,44 @@ platform accepts it; if it fails here, the upload will fail identically.
 - Other platform routes keep their platform body and render inside your layout. Capability flags
   expose documented optional context; they do not transfer transaction or route ownership.
 
+## The content model
+
+Everything you read comes from ONE tree: \`site\`, \`site.brand\`, \`site.nav\`,
+\`site.socials\`, \`site.locale\` and the typed collections under \`site.content.*\`
+(services, events, articles, campaigns, causes, courses, volunteering, media, resources,
+locations, schedules, about). Four rules it never breaks, so neither should you:
+
+- Every collection is BOUNDED (a documented cap plus a \`moreHref\`), link onward, never
+  assume you have everything.
+- Enum fields are OPEN, branch on the values you style and fall back for the rest; the
+  validator proves your template survives values it has never seen.
+- Optional fields are explicitly nullable, always branch.
+- The model only grows. The validator computes your content footprint from the paths you read
+  and stamps the minimum model version at publish; you never declare versions, and dynamic
+  indexing into \`site.content\` is refused so that stays decidable.
+
+SEE the model: \`npm run dev\` serves the full reference with live example data at \`/model\`;
+\`npx p60-template-kit model --json\` prints the machine-readable registry; the same reference
+lives at https://developers.port60.com/reference/content-model/.
+
+Bring your own content and imagery: \`npx p60-template-kit content .\` ejects every collection,
+fully populated, as an editable JSON file; replace the copy and the imageUrl values, then
+\`npx p60-template-kit dev . --content my-org.json\` renders YOUR data (the preview admits
+exactly the image hosts your file names, nothing else).
+
+You may replace the preview DATA with your own via \`preview-content.json\` beside the
+manifest ({ collection: [items] }, schema-checked, hot-reloaded). The shape is fixed, packaging
+excludes it, and conformance proofs always run on the canonical fixtures.
+
 ## What to build with
 
 - Theme via CSS custom properties and the settings knobs you declare in
-  \`manifest.settings.schema\` — they surface in the charity's Appearance editor as
+  \`manifest.settings.schema\`, they surface in the charity's Appearance editor as
   \`--p60s-<key>\` variables and \`data-p60s-<key>\` body attributes.
 - Hero photographs (\`homeHero.images\`, when you declare \`supports.heroImagery\`): render one
   photo directly as a TREATED backdrop (a scrim/tint built from your own palette variables via
-  color-mix — never raw), place the \`hero_carousel\` island for two or more (style its
-  \`.hero-slide-scrim\`), and design the no-photo state as a gradient/colour — never a
+  color-mix, never raw), place the \`hero_carousel\` island for two or more (style its
+  \`.hero-slide-scrim\`), and design the no-photo state as a gradient/colour, never a
   placeholder. The starter's \`.lq-homehero\` is the reference; the validator checks all of this
   behaviourally.
 - "Looks" = named one-click bundles of knob values in \`manifest.looks\`.
@@ -100,12 +128,12 @@ platform accepts it; if it fails here, the upload will fail identically.
   \`search\`, \`language_switch\` and \`next_prayer\` are platform islands. Place and style them;
   never reproduce their API calls or consent behaviour.
 - \`manifest.imagery.hero\` (optional but recommended): declare the photo shape YOUR hero
-  composes best with (\`idealAspect\`, \`minWidth\`, a one-line \`note\`) — the charity's editor
+  composes best with (\`idealAspect\`, \`minWidth\`, a one-line \`note\`), the charity's editor
   measures their actual upload against it and advises. Advice, never enforcement.
 
 ## Which contract this is
 
-The section catalogue, islands and fixtures here are the **Charity Platform contract v1** — the
+The section catalogue, islands and fixtures here are the **Charity Platform contract v1**, the
 platform's first product surface. The dialect, the rules above and this toolchain are
 platform-wide; other Port60 products will ship their own contract packs. Do not assume the
 current section list is universal.
@@ -113,7 +141,7 @@ current section list is universal.
 ## Reference
 
 The full generated reference (sections, islands, context variables, tokens, dialect) lives at
-https://developers.port60.com — also available in one file for agents at
+https://developers.port60.com, also available in one file for agents at
 https://developers.port60.com/llms-full.txt
 `;
 }