@port60/template-kit 0.20.4 → 1.0.0

package/README.md

@@ -33,6 +33,8 @@ newer contract asks of you.
 | `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. |
+| `release [dir]` | Build separate runtime and independent designer-preview folders for a trusted store release. Does not upload. |
+| `setup-previews [--with-deps]` | Install the pinned headless browser for automatic gallery images. Add `--with-deps` in Linux CI. |
 | `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. |
@@ -48,9 +50,46 @@ 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
-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.
+Kit 1.0.0 authors **port60-liquid@2**, content model **2.0**, using the contract under
+`src/vendor/contract/v2`. Collection envelopes, independent header/footer navigation,
+resolved actions and page-scoped sections are explicit. V1 sources need a deliberate migration,
+not a manifest-only relabel. Historical v1 contracts remain frozen for existing platform pins.
+
+## Designer previews
+
+The scaffold creates `preview/config.json` and `preview/media/`. Optional `content` points to
+fictional v2 sample JSON relative to `preview/`; omission uses contract fixtures. `focus` is
+`none`, `donate` or `volunteer`. Use approved local JPEG, PNG or WebP images via
+`p60preview:filename.jpg` and retain provenance with the source. Never use selecting-tenant data.
+
+`npm run release` writes `dist/release/NAME/VERSION/`: lightweight `template/` files, separate
+`preview/` HTML/media/metadata, and a `release.json` completion record. Every Look is generated
+from actual Liquid/CSS with matching palettes. Existing output is refused. Limits are 24 Looks,
+2 MiB per image/page and 24 MiB per release. Demo forms, navigation and transactions are inactive.
+
+The first-party publisher uploads completion last. The catalogue supplies matching preview
+metadata to tenant-admin; charity-site reads only runtime files. Previews are not bundled into
+admin and do not become tenant content. Preview-only changes also need a new template version.
+The Studio ZIP `package`/`publish` path remains separate and runtime-only.
+
+Before your first release build, run `npm run preview:setup` in a new scaffold, or
+`p60-template-kit setup-previews` in an existing project. Repeat after upgrading the kit.
+The release builder automatically captures each Look from the actual template at 1440x900
+and writes a 960x600 WebP to `preview/gallery/`, capped at 160 KiB. No separate screenshot
+authoring or upload is needed. The gallery uses these images; opening a design loads its HTML.
+The pinned browser is a build dependency only, never part of the live website.
+
+Linux capture requires a working Chromium sandbox. Ubuntu 24.04 hosted CI installs the
+repository's browser-path-scoped AppArmor profile to allow its user namespaces.
+No `--no-sandbox` or global AppArmor disablement is used. On another Linux
+host, configure an administrator-approved sandbox according to
+[Chromium's guidance](https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md).
+Browser installation alone does not change the host's security policy.
+
+Only packaged preview assets and fonts.bunny.net are accessible during capture. Failed required
+imagery or Latin fonts stop generation. Arabic-specific poster font fidelity is deferred;
+full previews and live-site typography are unchanged. Preserve the same kit/browser/OS for
+immutable upload retries; output changes need a new version, not an overwrite.
 
 Full documentation: [developers.port60.com](https://developers.port60.com)
 

package/bin/cli.mjs

@@ -12,6 +12,8 @@ import { upgrade } from '../src/commands/upgrade.mjs';
 import { refresh } from '../src/commands/refresh.mjs';
 import { login, logout, whoami } from '../src/commands/auth.mjs';
 import { publish } from '../src/commands/publish.mjs';
+import { releaseCmd } from '../src/commands/release.mjs';
+import { setupPreviews } from '../src/commands/setupPreviews.mjs';
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -37,6 +39,12 @@ const [command, ...rest] = process.argv.slice(2);
 const args = parseArgs(rest);
 
 switch (command) {
+  case 'setup-previews':
+    setupPreviews(args);
+    break;
+  case 'release':
+    await releaseCmd(args);
+    break;
   case 'create':
     create(args);
     break;
@@ -85,6 +93,8 @@ usage:
   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 release [dir]               build separate template/ and preview/ store bundles
+  p60-template-kit setup-previews [--with-deps] install the release builder's headless browser
   p60-template-kit upgrade [dir]               move an existing template to the latest kit
                                                and contract, re-brief, re-validate
   p60-template-kit login                       sign in from the terminal (the browser does the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.20.4",
+  "version": "1.0.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": {
@@ -16,8 +16,10 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
+    "jsdom": "29.1.1",
     "liquidjs": "^10.27.2",
-    "lucide-static": "^1.41.0"
+    "lucide-static": "^1.41.0",
+    "playwright": "1.63.0"
   },
   "license": "MIT",
   "repository": {

package/src/commands/content.mjs

@@ -1,6 +1,6 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { buildSiteFixture, composePage, validatePreviewContent } from '../vendor/validator/site-context.mjs';
+import { buildSiteFixture, composePage, validatePreviewContent } from '../vendor/validator/site-context-v2.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 
 /**
@@ -34,9 +34,10 @@ export function content(args) {
   }
   const data = {
     brand: site.brand,
-    nav: { items: site.nav?.items ?? [] },
+    nav: site.nav,
+    actions: site.actions,
     ...(manifest ? { pages: { home: composePage(manifest, 'home'), about: composePage(manifest, 'about') } } : {}),
-    ...Object.fromEntries(Object.entries(site.content).filter(([name]) => name !== 'about'))
+    ...site.content
   };
   const problems = validatePreviewContent(data);
   if (problems.length > 0) {

package/src/commands/create.mjs

@@ -19,7 +19,7 @@ export function create(args) {
   const name = (args.name ?? basename(target)).toLowerCase();
   if (!NAME_PATTERN.test(name)) {
     console.error(`✗ '${name}' is not a valid template name (lowercase letters, digits, hyphens, `
-        + '3–50 chars, starting with a letter). Pass --name.');
+        + '3 to 50 chars, starting with a letter). Pass --name.');
     process.exit(1);
   }
   if (existsSync(join(target, 'manifest.json'))) {
@@ -50,7 +50,9 @@ export function create(args) {
       dev: 'p60-template-kit dev .',
       validate: 'p60-template-kit validate .',
       'validate:json': 'p60-template-kit validate . --json',
-      package: 'p60-template-kit package .'
+      package: 'p60-template-kit package .',
+      release: 'p60-template-kit release .',
+      'preview:setup': 'p60-template-kit setup-previews'
     },
     devDependencies: {
       '@port60/template-kit': `^${KIT_PACKAGE.version}`
@@ -58,11 +60,17 @@ export function create(args) {
   }, null, 2) + '\n');
   writeFileSync(join(target, 'README.md'), `# ${label}
 
-A Port60 site template. Start with \`npm install\`, then:
+A Port60 site template using \`port60-liquid@2\`, content model \`2.0\` and kit \`1.0.0\`.
+Existing v1 platform pins keep historical support; this kit accepts v2 authoring only.
+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 in \`dist/\` (recreated on every run)
+- \`npm run release\`, separate runtime and designer-preview folders in \`dist/release/\`
+- \`npm run preview:setup\`, install the pinned browser before your first release build
+- \`preview/config.json\` selects author sample content and widget state; put optional
+  author images in \`preview/media/\` and reference them as \`p60preview:filename.jpg\`.
 
 **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.

package/src/commands/dev.mjs

@@ -3,9 +3,9 @@ import { watch, readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { surfaceFor, knobOverridesFromQuery, previewAssetPath, previewAssetType } from '../lib/previewOptions.mjs';
 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 { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
+import { applyPreviewContent, buildSiteFixture, validatePreviewContent } from '../vendor/validator/site-context-v2.mjs';
+import { renderModelReferenceHtml } from '../vendor/validator/model-reference-v2.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 import { join } from 'node:path';
 
@@ -80,6 +80,12 @@ function imageOriginsOf(json) {
  */
 export async function dev(args) {
   const dir = resolve(args._[0] ?? '.');
+  const initialManifest = JSON.parse(loadArtifactDir(dir)['manifest.json'] ?? '{}');
+  if (initialManifest.format !== 'port60-liquid@2') {
+    console.error('✗ Kit 1.0.0 requires port60-liquid@2. Existing v1 pins remain supported by the platform, not by the new authoring kit.');
+    process.exitCode = 1;
+    return;
+  }
   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

package/src/commands/model.mjs

@@ -1,4 +1,4 @@
-import { contentModel } from '../vendor/engine/content-footprint.mjs';
+import { contentModelV2 as contentModel } from '../vendor/engine/content-footprint.mjs';
 
 /**
  * `model [--json]`, the content model, in hand. Prints every `site.content.*` collection with
@@ -15,7 +15,7 @@ export function model(args) {
   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}` : '';
+    const more = collection.shape === 'envelope' ? ' · {label, href, items, pagination}' : ' · array';
     console.log(`site.content.${name}  (bounded at ${collection.cap}${more}, since ${collection.since})`);
     for (const [field, spec] of Object.entries(collection.item)) {
       const notes = [
@@ -27,7 +27,7 @@ export function model(args) {
     }
     console.log('');
   }
-  console.log('Rules: collections are bounded (link onward via moreHref); enums are open (branch and');
+  console.log('Rules: collections are bounded (link onward via href and pagination); 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

@@ -1,6 +1,6 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir, skippedNotice } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 

package/src/commands/publish.mjs

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir, skippedNotice } from '../lib/artifactFiles.mjs';
 import { buildZip } from '../lib/zip.mjs';
 import { accessToken, api, apiBase, loadCredentials, requireCredentials } from '../lib/auth.mjs';

package/src/commands/refresh.mjs

@@ -2,9 +2,9 @@ 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' };
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
+import { contentModelV2 as contentModel } from '../vendor/engine/content-footprint.mjs';
+import dialect from '../vendor/contract/v2/dialect.json' with { type: 'json' };
 
 const KIT_PACKAGE = JSON.parse(
   readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8')
@@ -25,6 +25,11 @@ export async function refresh(args) {
     process.exit(1);
   }
   const manifest = JSON.parse(files['manifest.json']);
+  if (manifest.format !== dialect.format) {
+    console.error(`✗ Kit ${KIT_PACKAGE.version} requires ${dialect.format}. Migrate the template before refreshing its instructions. No files changed.`);
+    process.exitCode = 1;
+    return;
+  }
 
   const briefing = agentsMd(manifest.name);
   writeFileSync(join(dir, 'AGENTS.md'), briefing);

package/src/commands/release.mjs

@@ -0,0 +1,22 @@
+import { mkdirSync, writeFileSync, existsSync, lstatSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { buildReleaseBundle } from '../lib/releaseBundle.mjs';
+
+export async function releaseCmd(args) {
+  const root = resolve(args._[0] ?? '.');
+  const bundle = await buildReleaseBundle(root);
+  const output = join(root, 'dist', 'release', bundle.manifest.name, bundle.manifest.version);
+  // Never follow a linked build destination or silently mix two builds of an immutable release.
+  for (const dir of [join(root, 'dist'), join(root, 'dist', 'release'), join(root, 'dist', 'release', bundle.manifest.name), output]) {
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error('Linked release destination refused');
+  }
+  if (existsSync(output)) throw new Error(`Release output already exists: ${output}. Review/remove that generated directory or bump the version before rebuilding.`);
+  for (const [path, file] of Object.entries(bundle.files)) {
+    const destination = join(output, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, file.bytes, { flag: 'wx' });
+  }
+  console.log(`Validated release: ${output}`);
+  console.log('template/ is runtime only; preview/ is the independent designer gallery. Publish release.json last.');
+  console.log('Studio package/publish still accepts the runtime ZIP; store release publication uses the first-party pipeline.');
+}

package/src/commands/setupPreviews.mjs

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+
+export function previewSetupCommand(args = {}) {
+  const require = createRequire(import.meta.url);
+  // Playwright exports its manifest, not a ./cli module. Use its declared binary so
+  // this resolves the kit's pinned installation even inside another npm project.
+  const manifestPath = require.resolve('playwright/package.json');
+  const command = [resolve(dirname(manifestPath), require(manifestPath).bin.playwright), 'install', 'chromium', '--only-shell'];
+  if (args['with-deps']) command.push('--with-deps');
+  return command;
+}
+
+export function setupPreviews(args) {
+  const result = spawnSync(process.execPath, previewSetupCommand(args), { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}

package/src/commands/validate.mjs

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { validateNewArtifact as validateArtifact } from '../vendor/validator/validate.mjs';
 import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 
 /**

package/src/lib/agentsMd.mjs

@@ -1,160 +1,113 @@
-// 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
-// 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.
-
+// A contract briefing shared by every generated coding-agent instruction file.
 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
-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*.
-
-## The iteration loop (use this constantly)
-
-\`\`\`bash
-npm run validate          # human-readable conformance check
-npm run validate:json     # machine-readable: {ok, errors[], warnings[], provenSupports}
-npm run dev               # local preview at http://localhost:4400 (re-renders on refresh)
-npm run package           # validate + produce the uploadable <name>-<version>.zip
-\`\`\`
-
-**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
-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
-  identity; bump \`version\` (semver) for every published change.
-- \`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
-  \`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, and the ONLY stylesheet the platform loads
-  (other \`.css\` files under \`assets/\` are packaged but never loaded, so keep everything in
-  it). **No images, no fonts, no JS**: \`package\` and \`publish\` leave them out and list what
-  they left out; the upload refuses them. Photographs belong in the charity's media library;
-  decorative textures go inline in the CSS as data URIs.
-
-## 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
-   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.
-3. **Islands are placed, never implemented.** Live functionality (donations, sign-in, events) is
-   \`{% island 'donation_widget' %}\` etc. Every island you place must be declared in
-   \`supports.islands\` and exist in the platform registry. Style them via their stable class
-   API; never reimplement them.
-4. **Declared ⇒ rendered, rendered ⇒ declared.** Supports flags are PROVEN behaviourally: if you
-   declare \`supports.worship\` the layout must actually render the worship fixture's times, must
-   hide the rail when \`worship\` is null, and rendering it undeclared is equally an error. The
-   same honesty applies across the contract.
-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
-   variables.
-7. **Capabilities are matching metadata, never entitlements.** Every value in
-   \`requiresCapabilities\` must have a declared section, page template or island that presents it.
-   \`suitsProfiles\` describes design intent and changes catalogue ordering only.
-
-## What each declaration owns
-
-- \`supports.layout\` owns the visible header, navigation and footer around platform pages. The
-  platform still owns the document head, consent and identity.
-- \`supports.pages\` owns section based bodies for \`home\` and \`about\` through the declared
-  renderers in \`sections/\`.
-- \`compositions\` owns each page's preferred order: the section types the design is built around,
-  each \`core\`, \`recommended\` or \`optional\`. An organisation may reorder, add or remove;
-  removing a core section warns them, it never stops them.
-- \`supports.pageTemplates: ["events"]\` owns the events listing only. Event details, RSVP and
-  ticket purchase remain platform owned.
-- \`supports.pageTemplates: ["course"]\` owns a course detail presentation only. The course
-  listing stays platform owned and enrolment remains the \`course_enrol\` island.
-- \`supports.pageTemplates: ["articles"]\` owns the article front page and archive listings.
-- \`supports.pageTemplates: ["article"]\` owns article detail presentation; engagement and
-  comments stay the \`article_engagement\` and \`article_comments\` islands.
-- 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, 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
-  \`--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
-  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\`.
-- Fonts: only families from the platform font catalogue, declared with the weights you use.
-- Navigation can contain two levels below a top item. Render every supplied child and branch on
-  optional \`group\`, \`description\`, \`imageUrl\` and \`megaMenu\` promo metadata. Never hardcode
-  menu groups that are not in \`nav\`.
-- Navigation highlights are optional design support, not implied by the \`nav\` behaviour.
-  Declare \`supports.navigationHighlights: true\` only when your layout renders one supplied
-  \`site.nav.items[].megaMenu.promo\` card per expanded top-level menu. Otherwise declare false.
-  The platform resolves linked content into \`title\`, \`text\`, \`href\`, \`label\` and optional
-  \`imageUrl\`; no entity lookup belongs in a template. Preserve a text-only card when its image
-  is absent, omit an absent card and keep normal navigation links. Validation proves the explicit
-  declaration; missing declarations never enable the editor feature automatically.
-- Dynamic sections include appeals (\`causes\`), programmes (\`services\`), resources and
-  locations. Derive or omit when a collection is empty and use the supplied URLs rather than
-  constructing routes.
-- Submission and behaviour surfaces such as \`newsletter_signup\`, \`form\`, \`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
-  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
-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.
-
-## 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/llms-full.txt
+This is a Liquid and CSS artifact, not an application. The platform owns public eligibility,
+routes, consent, authentication, payments and interactive islands. Preserve the design's visual
+identity, authored content and inline editing markers while changing presentation.
+
+## Versions and iteration
+
+Use format port60-liquid@2, content model2.0 and kit1.0.0. Existing v1 platform pins retain
+their historical contract; this kit explicitly rejects v1 for new authoring and uploads.
+Never relabel v1 without migrating its reads. Published name/version identities are immutable.
+
+- npm run validate:json is the machine-readable feedback loop. Fix all errors after each edit.
+- npm run validate checks the same contract as upload.
+- npm run dev previews all supported pages locally.
+- npm run package validates and writes the uploadable zip.
+- npm run release builds a store release with separate template/ and preview/ bundles.
+- p60-template-kit setup-previews installs the pinned build browser once (CI: --with-deps).
+- Check all Looks, empty states, long text and mobile layouts. Validation is not visual QA.
+
+## Artifact shape
+
+manifest.json declares support. layout.liquid has exactly one {% content %} slot.
+sections/<type>.liquid implements catalogued types; pages/<page>.liquid implements declared
+page templates. assets/theme.css is the only loaded stylesheet. No JavaScript, fonts, API calls,
+remote CSS imports or image files belong in the runtime artifact. preview/ contains independent
+author-demo inputs. Its config.json names a content JSON file and optional widget focus. Put
+author JPEG/PNG/WebP imagery in preview/media/ and use p60preview:filename references in that
+content. The release builder seals every Look and publishes that imagery only in the separate
+preview/ bundle. Runtime package/publish ZIPs never contain it. Studio preview-bundle intake is
+separate from the first-party store release lane. Use platform media URLs in runtime content.
+
+Release automatically captures each Look as a 960x600 WebP under preview/gallery/, from a
+1440x900 desktop render. Do not author separate screenshots. Posters have a 160 KiB cap;
+HTML, images and metadata remain beside them. The gallery loads posters; details load HTML.
+The build needs Chromium plus access to fonts.bunny.net, and refuses failed required assets.
+Use the same kit/browser/OS for immutable-upload retries; bump the version for changed output.
+Arabic-specific poster font fidelity is deferred, not proof of Arabic-locale conformance.
+
+## The only public site tree
+
+Read site.brand, site.nav, site.socials, site.locale, site.actions, site.page and site.content.
+No flat brand/nav/collection aliases or site.focus exist. A section also receives section, its
+current instance's raw authored content. Article/course details retain their documented record
+context. impactMap receives the selected map with its contained points, never root locations.
+
+services/events/articles/campaigns/causes/courses/documents are envelopes:
+{label, href, items, pagination}. Iterate site.content.events.items, not the envelope.
+Documents href can be null. Pagination is null outside listings, otherwise it carries page,
+size, totalElements, totalPages, nextHref and previousHref. Use supplied URLs, not guessed routes.
+Only site.content.schedules stays an array. Lists are bounded; enum values are open, so always
+include fallbacks. Nullable values need guards. Metadata-only label/href/pagination reads do
+not fetch items, but whole-envelope aliases do. Dynamic indexing of the site tree is refused.
+
+The current render is site.page = {key, path, sections:[{key,type,content}]}.
+Repeated section types have independent stable keys. Canonical section types include services,
+courses, events and documents. No programmes, whatsOn, infoEvents, resources, locations or
+content.about public aliases exist. Documents remain selected existing public records, never
+an automatically exposed media library. Section support does not confer source entitlements.
+
+## Authored ownership and clearing
+
+For collection introductions, absent section.title inherits site.content.<collection>.label;
+an explicit empty string hides it; other text overrides it. subtitle and eyebrow are authored.
+Use nil checks, not Liquid default, wherever clearing has meaning. Keep generated labels out
+of raw section content. Mark an authored title only in the nonempty override branch. An inherited
+heading has no data-p60-field marker.
+
+Declare supports.fieldMarkers:true when showing authored field markers. A marker such as
+data-p60-field="title" or data-p60-field="items.{{ forloop.index0 }}.label" addresses only that
+section's content. Its node must contain exactly the authored value. Use a span when punctuation
+or generated text surrounds it. Never mark source records, generated labels or resolved actions.
+
+## Navigation and actions
+
+site.nav.header and site.nav.footer are independent arrays. kind link has href; kind group has
+null href and children. Use disclosure controls for groups, not fake links. Render two child
+levels and preserve description, imageUrl and optional megaMenu.promo. No derived menus, CTA
+flags or generated columns exist. The template owns responsive menu layout.
+supports.navigationHighlights:true must render supplied promos, including text-only cards,
+without losing normal links. The nav behaviour alone never enables this feature.
+site.actions.header and site.actions.hero are resolved actions or null. site.actions.widget is
+donate, volunteer or none. Do not infer actions from navigation. Authored hero override text
+retains its field marker; resolved fallback actions do not.
+
+## Safety and design
+
+- Output is escaped. Use raw only for contract-sanitised richtext.
+- The dialect is whitelisted. include/render/layout and unknown filters are rejected.
+- Place declared islands with {% island 'donation_widget' %}. Style their stable API and never
+  recreate transactions, API calls, forms, identity or consent logic.
+- Render collection envelopes with template markup and declared behaviours. The historical
+  events_carousel, whats_on_strip and latest_articles islands are v1-only and rejected by v2.
+  Collection route continuation belongs to the host, not a second template data fetch or pager.
+- Declare only what you render, and render what you declare. Capability matching is metadata,
+  not a transfer of route ownership or tenant entitlements.
+- Hero photos need a palette scrim, a carousel for multiple photos and a designed no-photo state.
+- Preserve settings and Looks. Use platform fonts and declared CSS tokens.
+- Scope behaviour-dependent hidden content under .p60-js so no-JavaScript stays readable.
+- Keep loops bounded. Test empty collections, cleared text and unknown enum values.
+
+## Data and reference
+
+p60-template-kit content . writes editable envelope fixtures, independent header/footer menus
+and keyed page compositions. p60-template-kit dev . --content my.json previews those fixtures.
+Overrides are schema-checked, never packaged and never replace canonical conformance fixtures.
+The dev server /model shows live values beside the registry. p60-template-kit model --json
+prints the current model. Generated reference: https://developers.port60.com/reference/content-model/
+Full agent reference: https://developers.port60.com/llms-full.txt
 `;
 }