@port60/template-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PORT 60 LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @port60/template-kit
+
+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.
+
+Templates are small, versioned artifacts of [Liquid](https://liquidjs.com) renderers and CSS.
+They contain no application code: the platform owns data, payments and compliance; your template
+owns how a site looks.
+
+## Quickstart
+
+```bash
+npx @port60/template-kit create my-template --name my-template
+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
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `create <dir>` | A working template from the platform starter, npm scripts wired. |
+| `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. |
+
+## Building with an AI agent
+
+Every scaffold ships `AGENTS.md` (and an identical `CLAUDE.md`) briefing any coding agent on
+the contract rules and the iteration loop; `validate --json` is the machine feedback loop to
+iterate against until `ok: true`. The full documentation is also published as a single
+agent-consumable file at [developers.port60.com/llms-full.txt](https://developers.port60.com/llms-full.txt).
+
+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.
+
+Full documentation: [developers.port60.com](https://developers.port60.com)
+
+## Licence
+
+[MIT](LICENSE) © PORT 60 LTD. Publishing a template on the Port60 marketplace is governed by the
+[Developer Agreement](https://port60.com/developers/agreement/).

package/bin/cli.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// @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';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+const args = parseArgs(rest);
+
+switch (command) {
+  case 'create':
+    create(args);
+    break;
+  case 'validate':
+    await validate(args);
+    break;
+  case 'dev':
+    await dev(args);
+    break;
+  case 'package':
+    await packageCmd(args);
+    break;
+  default:
+    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 validate [dir] [--json]     the platform's exact conformance checks
+  p60-template-kit package [dir]               validate + build the uploadable zip
+
+AI agents: the scaffold's AGENTS.md is your briefing; iterate with \`validate --json\`.
+Docs: https://developers.port60.com (agents: /llms-full.txt)`);
+    process.exit(command ? 2 : 0);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@port60/template-kit",
+  "version": "0.1.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": {
+    "p60-template-kit": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "starter"
+  ],
+  "scripts": {
+    "test": "node --test 'tests/*.test.mjs'"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "liquidjs": "^10.27.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Port60Labs/template-kit.git"
+  },
+  "homepage": "https://developers.port60.com",
+  "bugs": {
+    "url": "https://github.com/Port60Labs/template-kit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/create.mjs

@@ -0,0 +1,73 @@
+import { cpSync, mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+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]$/;
+
+/** `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];
+  if (!dir) {
+    console.error('usage: p60-template-kit create <dir> [--name my-template] [--label "My Template"]');
+    process.exit(2);
+  }
+  const target = resolve(dir);
+  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.');
+    process.exit(1);
+  }
+  if (existsSync(join(target, 'manifest.json'))) {
+    console.error(`✗ ${target} already contains a template.`);
+    process.exit(1);
+  }
+  const label = args.label ?? name.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+
+  mkdirSync(target, { recursive: true });
+  cpSync(resolve(import.meta.dirname, '../../starter'), target, { recursive: true });
+
+  const manifest = JSON.parse(readFileSync(join(target, 'manifest.json'), 'utf8'));
+  manifest.name = name;
+  manifest.version = '0.1.0';
+  manifest.label = label;
+  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');
+
+  const briefing = agentsMd(name);
+  writeFileSync(join(target, 'AGENTS.md'), briefing);
+  writeFileSync(join(target, 'CLAUDE.md'), briefing);
+  writeFileSync(join(target, '.gitignore'), 'node_modules/\n*.zip\n');
+  writeFileSync(join(target, 'package.json'), JSON.stringify({
+    name: `${name}-template`,
+    private: true,
+    scripts: {
+      dev: 'p60-template-kit dev .',
+      validate: 'p60-template-kit validate .',
+      'validate:json': 'p60-template-kit validate . --json',
+      package: 'p60-template-kit package .'
+    },
+    devDependencies: {
+      '@port60/template-kit': '^0.1.0'
+    }
+  }, 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
+
+**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
+`);
+
+  console.log(`✓ ${label} scaffolded at ${target}`);
+  console.log('  npm install && npm run dev   → preview at http://localhost:4400');
+  console.log('  AGENTS.md briefs your AI agent; `npm run validate:json` is its feedback loop.');
+}

package/src/commands/dev.mjs

@@ -0,0 +1,56 @@
+import { createServer } from 'node:http';
+import { watch } from 'node:fs';
+import { resolve } from 'node:path';
+import { renderStudioPreview } from '../vendor/validator/preview.mjs';
+import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { loadArtifactDir } from '../lib/artifactFiles.mjs';
+
+/**
+ * `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.
+ */
+export async function dev(args) {
+  const dir = resolve(args._[0] ?? '.');
+  const port = Number(args.port ?? 4400);
+
+  const server = createServer(async (req, res) => {
+    try {
+      const files = loadArtifactDir(dir);
+      const html = await renderStudioPreview(files);
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(html);
+    } catch (e) {
+      const { errors } = await validateArtifact(loadArtifactDir(dir)).catch(() => ({ errors: [] }));
+      res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(`<!doctype html><meta charset="utf-8"><title>Template error</title>
+<body style="font:14px/1.5 system-ui;padding:2rem;max-width:48rem;margin:auto">
+<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>`);
+    }
+  });
+
+  server.listen(port, () => {
+    console.log(`✓ preview at http://localhost:${port} — refresh after edits`);
+    console.log('  watching for changes; validation runs on save:');
+  });
+
+  let pending = null;
+  watch(dir, { recursive: true }, () => {
+    clearTimeout(pending);
+    pending = setTimeout(async () => {
+      const { errors, warnings } = await validateArtifact(loadArtifactDir(dir))
+          .catch((e) => ({ errors: [String(e)], warnings: [] }));
+      const stamp = new Date().toLocaleTimeString();
+      if (errors.length === 0) {
+        console.log(`  [${stamp}] ✓ valid${warnings.length ? ` (${warnings.length} warning${warnings.length === 1 ? '' : 's'})` : ''}`);
+      } else {
+        console.log(`  [${stamp}] ✗ ${errors.length} error${errors.length === 1 ? '' : 's'}:`);
+        for (const e of errors) console.log(`      - ${e}`);
+      }
+    }, 200);
+  });
+}

package/src/commands/packageCmd.mjs

@@ -0,0 +1,25 @@
+import { writeFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { validateArtifact } from '../vendor/validator/validate.mjs';
+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
+ * 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.
+ */
+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'}:`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  const out = join(dir, `${manifest.name}-${manifest.version}.zip`);
+  writeFileSync(out, buildZip(Object.entries(files).map(([path, content]) => ({ path, content }))));
+  console.log(`✓ ${out}`);
+  console.log('  Upload it from your studio (tenant admin → Studio → your template → Versions).');
+}

package/src/commands/validate.mjs

@@ -0,0 +1,38 @@
+import { resolve } from 'node:path';
+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)
+ * are what turn a declaration into proof. `--json` is the AI agent's feedback loop: iterate
+ * until {ok: true}.
+ */
+export async function validate(args) {
+  const dir = args._[0] ?? '.';
+  const files = loadArtifactDir(resolve(dir));
+  const { errors, warnings, manifest } = await validateArtifact(files);
+  const ok = errors.length === 0;
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      ok,
+      errors,
+      warnings,
+      manifest: manifest == null ? null : { name: manifest.name, version: manifest.version },
+      // Proven by behaviour, not claimed: only a clean pass earns the supports set.
+      provenSupports: ok ? manifest.supports : null
+    }, null, 2));
+    process.exit(ok ? 0 : 1);
+  }
+
+  for (const w of warnings) console.warn(`  ⚠ ${w}`);
+  if (!ok) {
+    console.error(`\n✗ ${manifest?.name ?? dir} FAILED conformance (${errors.length} error${errors.length === 1 ? '' : 's'}):`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  console.log(`\n✓ ${manifest.name}@${manifest.version} conforms to ${manifest.format}`);
+  console.log(`  proven supports: ${JSON.stringify(manifest.supports)}`);
+}

package/src/lib/agentsMd.mjs

@@ -0,0 +1,81 @@
+// 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.
+
+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. 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
+   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}\`; layouts see
+   \`{brand, nav, socials, worship}\`; page templates see their fixture + \`brand\`. Nothing else
+   exists — do not invent variables.
+
+## 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.
+- "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.
+
+## 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
+`;
+}

package/src/lib/artifactFiles.mjs

@@ -0,0 +1,28 @@
+// The contract-shaped file set of an artifact directory — the same selection the platform's
+// upload intake allow-lists: manifest, layout, section/page renderers, css assets. Anything else
+// in the directory is not part of an artifact and is neither validated nor packaged.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function loadArtifactDir(root) {
+  const files = {};
+  const add = (rel) => {
+    const abs = join(root, rel);
+    if (existsSync(abs)) files[rel] = readFileSync(abs, 'utf8');
+  };
+  add('manifest.json');
+  add('layout.liquid');
+  for (const dir of ['sections', 'pages']) {
+    const abs = join(root, dir);
+    if (!existsSync(abs)) continue;
+    for (const name of readdirSync(abs)) {
+      if (name.endsWith('.liquid')) files[`${dir}/${name}`] = readFileSync(join(abs, name), 'utf8');
+    }
+  }
+  if (existsSync(join(root, 'assets'))) {
+    for (const name of readdirSync(join(root, 'assets'))) {
+      if (name.endsWith('.css')) files[`assets/${name}`] = readFileSync(join(root, 'assets', name), 'utf8');
+    }
+  }
+  return files;
+}

package/src/lib/zip.mjs

@@ -0,0 +1,77 @@
+// A minimal STORE-only ZIP writer — no dependency, no compression. Artifacts are ~80KB of text
+// against a 2MB upload cap, so stored entries are fine, and the platform's TemplateArchive reads
+// any conformant zip. Local file headers + central directory + CRC-32, nothing else.
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** entries: Array<{path: string, content: Buffer|string}> → a complete zip Buffer. */
+export function buildZip(entries) {
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const nameBytes = Buffer.from(entry.path, 'utf8');
+    const data = Buffer.isBuffer(entry.content) ? entry.content : Buffer.from(entry.content, 'utf8');
+    const crc = crc32(data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);      // local file header signature
+    local.writeUInt16LE(20, 4);              // version needed
+    local.writeUInt16LE(0x0800, 6);          // flags: UTF-8 names
+    local.writeUInt16LE(0, 8);               // method: stored
+    local.writeUInt16LE(0, 10);              // mod time
+    local.writeUInt16LE(0x21, 12);           // mod date (a fixed valid date)
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);    // compressed size (== stored)
+    local.writeUInt32LE(data.length, 22);    // uncompressed size
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(0, 28);              // extra length
+    localParts.push(local, nameBytes, data);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);    // central directory signature
+    central.writeUInt16LE(20, 4);            // version made by
+    central.writeUInt16LE(20, 6);            // version needed
+    central.writeUInt16LE(0x0800, 8);        // flags: UTF-8 names
+    central.writeUInt16LE(0, 10);            // method: stored
+    central.writeUInt16LE(0, 12);            // mod time
+    central.writeUInt16LE(0x21, 14);         // mod date
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(data.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(nameBytes.length, 28);
+    central.writeUInt32LE(offset, 42);       // local header offset
+    centralParts.push(central, nameBytes);
+
+    offset += 30 + nameBytes.length + data.length;
+  }
+
+  const centralSize = centralParts.reduce((n, b) => n + b.length, 0);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);          // end of central directory
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(centralSize, 12);
+  end.writeUInt32LE(offset, 16);
+
+  return Buffer.concat([...localParts, ...centralParts, end]);
+}

package/src/vendor/contract/v1/content-bounds.json

@@ -0,0 +1,117 @@
+{
+  "description": "The maximum lengths of every admin-entered display field a template renders. The admin screens stop input at these caps and the API rejects anything longer, so a template can design cards, headings and captions against known worst cases. Additive-only within a contract major: a bound may loosen, never tighten. Long-form bodies (article bodies, course About pages, service pages) are deliberately outside this table — they are sanitised HTML rendered in dedicated full-width regions, never inside cards.",
+  "groups": [
+    {
+      "name": "Brand (layout chrome)",
+      "fields": [
+        {
+          "field": "brand.name",
+          "max": 60,
+          "note": "The masthead/wordmark text."
+        },
+        {
+          "field": "brand.tagline",
+          "max": 140,
+          "note": "One line under the masthead; may be empty."
+        }
+      ]
+    },
+    {
+      "name": "Articles",
+      "fields": [
+        {
+          "field": "Article title",
+          "max": 200
+        },
+        {
+          "field": "Excerpt",
+          "max": 500,
+          "note": "The card/front-page summary."
+        },
+        {
+          "field": "Author name / role",
+          "max": 120,
+          "note": "Each."
+        },
+        {
+          "field": "Articles nav label",
+          "max": 30,
+          "note": "The tenant's name for the section (\"Latest\", \"News\", …)."
+        },
+        {
+          "field": "Categories",
+          "max": null,
+          "note": "≤5 per article; names come from a tenant catalogue capped at 20 entries."
+        }
+      ]
+    },
+    {
+      "name": "Events",
+      "fields": [
+        {
+          "field": "Event name",
+          "max": 200
+        },
+        {
+          "field": "Summary (description)",
+          "max": 200,
+          "note": "A sentence or two for cards and listings. The long-form About body is separate sanitised HTML on the detail page."
+        },
+        {
+          "field": "Venue name",
+          "max": 200
+        },
+        {
+          "field": "Venue address",
+          "max": 500
+        },
+        {
+          "field": "Tag",
+          "max": 40,
+          "note": "Each — rendered as chips."
+        }
+      ]
+    },
+    {
+      "name": "Courses",
+      "fields": [
+        {
+          "field": "Course title",
+          "max": 200
+        },
+        {
+          "field": "Description",
+          "max": 500,
+          "note": "The card/detail summary; the long-form About page is separate sanitised HTML."
+        },
+        {
+          "field": "Venue label",
+          "max": 200
+        }
+      ]
+    },
+    {
+      "name": "Donations",
+      "fields": [
+        {
+          "field": "Cause name",
+          "max": 200
+        },
+        {
+          "field": "Cause description",
+          "max": 500
+        }
+      ]
+    },
+    {
+      "name": "Service pages",
+      "fields": [
+        {
+          "field": "Page name",
+          "max": 200,
+          "note": "The body is sanitised HTML rendered full-width — not card content."
+        }
+      ]
+    }
+  ]
+}