@o-a/cms-agent 0.2.1 → 0.3.0

package/dist/create-site/generate-site.js

@@ -86,6 +86,13 @@ export function scaffoldSite(targetDir) {
     // could lose or that leaks into version control.
     const token = generateToken();
     writeFileSync(join(vhostDir, 'site.config.json'), JSON.stringify({
+        // Written explicitly, matching server-config.ts's own
+        // DEFAULT_PORT, rather than left absent - a real value here
+        // is a visible, editable config knob; an absent key is
+        // invisible until something else is already using the
+        // default port, at which point the failure is a raw
+        // EADDRINUSE crash instead of an obvious setting to change.
+        port: 3000,
         tokens: [{ hash: token.hash, scopes: ['content', 'theme', 'media'] }],
     }, null, 2));
     const packageName = sanitisePackageName(basename(targetDir));
@@ -100,9 +107,23 @@ export function scaffoldSite(targetDir) {
         // straight to one of those (no Dockerfile in the loop) simply
         // wouldn't boot. "tunnel" mirrors the --tunnel flag create-site
         // already tells the operator about in its own next-steps output.
+        // "dev" is Node's own --watch-path, not custom fs-watching code
+        // - confirmed empirically that it both picks up changes to a
+        // plain file under a watched directory that's never imported
+        // (theme/*.liquid is only ever read via readFileSync) and sends
+        // a real SIGTERM on restart, which server.js's own shutdown
+        // handling already listens for. "../theme" because npm run dev
+        // runs with cwd vhost/, a sibling of theme/. Deliberately not
+        // content/ - that's already read fresh on every request, so
+        // watching it would only cause pointless restarts on every
+        // content edit. "check" is check-site, the package's own
+        // installed CLI bin - runs from vhost/ (site-check/cli.ts's own
+        // assumed cwd relationship), same pattern as start/tunnel/dev.
         scripts: {
             start: 'node server.js',
             tunnel: 'node server.js --tunnel',
+            dev: 'node --watch-path=../theme server.js',
+            check: 'check-site',
         },
         dependencies: {
             // Pinned exact, never a ^range - at v0.x even a minor bump

package/dist/create-site/template/AGENTS.md

@@ -33,9 +33,12 @@ This scaffold already ships real, working examples worth reading before writing
 ## Turning a design into code - the actual workflow
 
 1. Break the design into distinct repeating/reusable visual components. Each one becomes a `theme/sections/<name>.liquid` (a self-contained region of a page) or `theme/blocks/<name>.liquid` (a smaller item nested inside a section, e.g. one card in a grid, one FAQ row).
-2. Each file has two parts: ordinary Liquid/HTML markup, and a `{% schema %} ... {% endschema %}` block containing a single JSON object - a plain [JSON Schema draft-07](https://json-schema.org/draft-07) description of that component's `settings`. The schema block is stripped out before rendering, so a real Liquid tag never sees it - place it anywhere in the file (convention: at the end).
+2. Each file has two parts: ordinary Liquid/HTML markup, and a `{% schema %} ... {% endschema %}` block containing a single JSON object - a settings description using *only* the JSON Schema draft-07 keywords listed below, never the full spec. The schema block is stripped out before rendering, so a real Liquid tag never sees it - place it anywhere in the file (convention: at the end).
+
+**Only these keywords are supported**: `type`, `properties`, `required`, `additionalProperties`, `default`, `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `enum`, `items`, `minItems`, `maxItems`, plus the custom `format`/`title`/`description`/`allowedBlocks`/`api`/`swatches`/`step`/`unit` keywords documented below. **Never `$ref`, `$defs`, `definitions`, `allOf`, `anyOf`, `oneOf`, `not`, or `if`/`then`/`else`** - every property's schema must be fully self-contained, written out in full where it's used. If the same shape (e.g. an image object) repeats across several properties or several component files, write it out each time rather than trying to share/reference a definition - there is no cross-referencing mechanism here, in a single schema block or across files, regardless of what standard JSON Schema itself supports elsewhere.
 3. Once the theme components exist, compose an actual page by writing a file under `content/pages/` whose `sections` array references those types by filename, with a `settings` object matching each one's schema (see "Content JSON model" below).
-4. Preview the result before considering the task done - see "Previewing your work".
+4. **For any page type the site will have more than one of** - a project, an article, a case study, a team member - also write a starting point for it under `theme/templates/<name>.json`. This is easy to skip and worth not skipping: without a template, every new page an editor creates starts completely blank, and they have to rebuild the same section stack by hand every time. A template is just a real page file kept in a different folder - the same shape as anything under `content/pages/` (`schemaVersion`, `name`, `title`, `type`, `layout`, `published`, `sections`), validated identically, using the section types this theme already defines. Its `"title"` is the label an editor picks from, so name it for the page type (`"Project"`, `"Article"`), never `"Untitled"`. Fill each section's settings with short placeholder copy rather than leaving them empty - a template is a starting point to edit, not a blank form. A template that fails validation is skipped silently at boot, so preview a page built from it.
+5. Preview the result before considering the task done - see "Previewing your work".
 
 ### Worked example - a section
 
@@ -58,19 +61,39 @@ This scaffold already ships real, working examples worth reading before writing
 {% endschema %}
 ```
 
-Available variables in a section: `section.id`, `section.settings.<key>`, and `blocksHtml` (an array of already-rendered child block HTML strings - a section never sees raw block data, only finished HTML, output with `{{ html | raw }}`). A block template gets the same shape: `block.id`, `block.settings.<key>`, and (rarely) its own `blocksHtml` if it nests further blocks.
+Available variables in a section: `section.id`, `section.settings.<key>`, `blocksHtml` (an array of already-rendered child block HTML strings - a section never sees raw block data, only finished HTML, output with `{{ html | raw }}`), and `page` - the same built-in envelope a layout gets (`page.title`, `page.author`, `page.publishDate`, `page.tags`; see "Content JSON model" below). A block template gets the same shape: `block.id`, `block.settings.<key>`, `page`, and (rarely) its own `blocksHtml` if it nests further blocks. `page.author`/`publishDate`/`tags` render as empty/absent, not an error, on a page that doesn't set them - useful for printing a byline/date inside the page body without duplicating the value into a settings field.
 
-**Every property listed in a schema's `"required"` array must also declare a `"default"`** that itself satisfies the property's own constraints (e.g. not `"default": ""` against `"minLength": 1`). A schema that violates this is silently excluded from the theme entirely - it simply won't be selectable, with no error printed anywhere obvious. If a new section/block isn't showing up, check this first.
+**Every property listed in a schema's `"required"` array must also declare a `"default"`** that itself satisfies the property's own constraints (e.g. not `"default": ""` against `"minLength": 1`). A schema that violates this - or one with no `{% schema %}` block at all, or invalid JSON inside it - is excluded from the theme entirely (it simply won't be selectable), but never silently: boot prints a warning naming the type and the specific reason. If a new section/block isn't showing up, check the server's console output first.
 
 To restrict which block types are allowed under a given section/block, add `"allowedBlocks": ["button", "logo-mark"]` alongside `"properties"` in its schema - omit it entirely for no restriction (the default).
 
+### Naming a section or block for the admin
+
+Give every section and block a `"title"` and a `"description"`, as plain annotations on the schema object alongside `"properties"`:
+
+```json
+{
+  "title": "Image band",
+  "description": "A full width photograph with an optional caption.",
+  "type": "object",
+  "properties": { }
+}
+```
+
+Neither affects validation. The admin's "Add a Section" dialog lists one row per type showing the title with the description beside it, so a type with no description shows a bare name and an editor has to guess what it is for. Omit the `"title"` and the type's filename is shown instead (`image-band`), which reads as code, not as a choice.
+
+Write the description as one short sentence about what the section **is**, not which fields it has - the fields are already visible the moment the section is added. "A full width photograph with an optional caption" is useful; "Heading, image and caption fields" is not.
+
 ### Layouts
 
 `theme/layouts/theme.liquid` is required - every theme must define a layout named exactly `theme` as the default (a page can opt into a different one via its own `"layout"` field). A layout only ever sees:
 
 ```liquid
 {{ content_for_layout | raw }}   the page's fully-rendered sections, concatenated
-{{ page.title }}                 the page's title (the ONLY page field exposed to layouts)
+{{ page.title }}                 the page's title
+{{ page.author }}                the page's author, if set
+{{ page.publishDate }}           the page's publish date, if set
+{% for tag in page.tags %}...{% endfor %}   the page's tags, if any
 {{ menus.<name>.items }}         every menu in content/menus/, keyed by filename
 ```
 
@@ -94,9 +117,136 @@ Every setting is plain JSON Schema (`string`, `integer`, `number`, `boolean`, `a
 | `toggle` | `boolean` | Switch instead of a checkbox (same underlying data) |
 | (none) | `boolean` | Plain checkbox |
 | (none) | `string` + `"enum"` | Segmented tabs (few short options) or a `<select>` (more/longer) - decided automatically, not choosable |
+| (none) | `array` + `items.type: "string"` | Repeatable list of text lines, with add/remove/drag-to-reorder - `minItems`/`maxItems` bound how many lines the admin UI allows; `items.minLength`/`items.maxLength` apply per line |
+| (none) | `array` + `items.type: "object", items.format: "image"` | A gallery: a grid of image thumbnails, add via the media picker, remove/drag-to-reorder - `minItems`/`maxItems` bound how many images the admin UI allows. Each item is exactly `{ "url": "...", "focalX": 0.5, "focalY": 0.5 }`, the same shape a lone `format: "image"` field stores - **no other properties are supported on a gallery item** (see "This is a closed set" below) |
 
 A `format` on the wrong `type` (e.g. `image` on a `string`) is a mistake, not something the admin guesses around - it silently falls back to a plain widget for that type.
 
+### Minimal form - prefer this
+
+Every type/format combination above needs nothing beyond what triggers it - no `additionalProperties`, no `required`, no `default`, no nested `properties` describing an object's own shape. None of that is what makes the admin recognise a field; it only matters if you actually need the stricter validation or a guaranteed starting value (see below). Default to the minimal form:
+
+```json
+"heading": {
+  "type": "string"
+}
+
+"columns": {
+  "type": "integer"
+}
+
+"enabled": {
+  "type": "boolean"
+}
+
+"enabled": {
+  "type": "boolean",
+  "format": "toggle"
+}
+
+"bio": {
+  "type": "string",
+  "format": "textarea"
+}
+
+"body": {
+  "type": "string",
+  "format": "richtext"
+}
+
+"link": {
+  "type": "string",
+  "format": "uri"
+}
+
+"publishDate": {
+  "type": "string",
+  "format": "date"
+}
+
+"accent": {
+  "type": "string",
+  "format": "color"
+}
+
+"align": {
+  "type": "string",
+  "enum": ["left", "center", "right"]
+}
+
+"fontSize": {
+  "type": "integer",
+  "format": "range",
+  "minimum": 12,
+  "maximum": 24
+}
+
+"poster": {
+  "type": "object",
+  "format": "image"
+}
+
+"tags": {
+  "type": "array",
+  "items": { "type": "string" }
+}
+
+"gallery": {
+  "type": "array",
+  "items": { "type": "object", "format": "image" }
+}
+```
+
+`fontSize`'s `minimum`/`maximum` are the one exception - they're not optional boilerplate, the `range` widget genuinely doesn't trigger without both.
+
+A custom display label uses the standard JSON Schema `"title"` keyword (`"title": "Section Heading"`) - skip it and the property key auto-humanizes instead (`backgroundImage` -> "Background Image"), which is why none of the examples above bother with one.
+
+Only reach for `"required"` + `"default"` (and, for stricter content validation, `"additionalProperties": false` on an object/`minLength`/`pattern`/etc.) when a field genuinely must always have a value from the moment a component is added - skip both and it just starts empty/unset, which is a valid state for every type above. See "Worked example - a section" above for what that fuller form looks like once it's actually needed, and remember the L1 rule if you do use it: a required field's `default` is validated against that field's *own* full schema, including `minItems`/`minLength`/etc. - `"default": []` against `"minItems": 1` fails just as surely as an empty string against `"minLength": 1` does.
+
+### This is a closed set - do not invent a new field shape
+
+**The table above is exhaustive.** These are the only setting shapes the admin has a real editor for. A setting whose shape doesn't match one of these rows exactly still technically works - Ajv validates it, the content saves - but the admin can only offer a raw JSON textarea for it, which is a bad editing experience for a human, not a fallback to design around. Never invent a new combination of `type`/`format`/`items` hoping the admin will render something sensible for it; if a design need doesn't map onto one of these rows, use the pattern below instead of a wider array shape.
+
+**A repeating item with more than one independent field is a block, never an array-shaped setting.** For example, a "before/after" or "lightbox" style section needing several frames, each with its own image *and* a caption *and* a timestamp, is not `"type": "array", "items": { "type": "object", "properties": { "image": ..., "caption": ..., "time": ... } } }` - that shape has no admin widget and never will (it's an open-ended amount of nested field types, not a closed set like the table above). Model it as a block type instead:
+
+```liquid
+{# theme/blocks/frame.liquid #}
+<figure class="lightstudy__frame">
+  <img src="{{ block.settings.image.url }}" alt="{{ block.settings.caption }}">
+  <figcaption><span class="numeral">{{ block.settings.time }}</span> {{ block.settings.caption }}</figcaption>
+</figure>
+{% schema %}
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["image", "caption", "time"],
+  "properties": {
+    "image": { "type": "object", "format": "image", "default": { "url": "", "focalX": 0.5, "focalY": 0.5 } },
+    "caption": { "type": "string", "minLength": 1, "default": "The room in a particular light" },
+    "time": { "type": "string", "minLength": 1, "default": "12:00" }
+  }
+}
+{% endschema %}
+```
+
+Then the parent section just loops `blocksHtml`, exactly as it already does for any other block type - see "Section markup" above. This gets real add/remove/drag-to-reorder and a proper per-field settings form (image picker, text inputs) for every one of `image`/`caption`/`time` independently, for free - a single array setting never gets that, no matter how its `items` schema is shaped.
+
+A multi-line field (e.g. an animated headline, one line per array entry) uses the array shape above rather than a single `format: "textarea"` string - each line is edited and reordered independently:
+
+```json
+{
+  "type": "array",
+  "minItems": 1,
+  "maxItems": 4,
+  "items": { "type": "string", "minLength": 1 },
+  "default": ["New section"]
+}
+```
+
+```liquid
+{% for line in section.settings.heading %}<span>{{ line }}</span>{% endfor %}
+```
+
 A separate keyword, `"api": true`, can be added to any scalar property to expose its value through `GET /search.json` for structured filtering, independent of full-text search - see that section below.
 
 ## Content JSON model
@@ -166,10 +316,28 @@ Uploads go through `POST /v1/media` (multipart, requires a token with `media` sc
 
 unless the design needs a focal point for a cropped image, in which case use `"format": "image"` (see the table above) instead of a plain string.
 
+If you're writing starter content before a server is even running - so `POST /v1/media` isn't reachable yet - use the `seed-media` CLI instead of placing images under `theme/root/`. It computes the exact same content-addressed filename a real upload would, so the result is indistinguishable from one:
+
+```
+npx seed-media <site-directory> photo.jpg another.png
+# photo.jpg -> /media/photo-3f9a2b7c1e04.jpg
+# another.png -> /media/another-91cd4a08f2b1.png
+```
+
+Then use the printed URL exactly like a real upload's:
+
+```json
+{ "type": "string", "default": "/media/photo-3f9a2b7c1e04.jpg" }
+```
+
+This is only for seeding starter content offline - once a server is running, a later image change from an editor still goes through `POST /v1/media` or the admin's media library as normal.
+
 ## `GET /search.json`
 
 A public, unauthenticated, read-only endpoint - safe to call directly from a section's own client-side JavaScript with a plain `fetch()`, no token needed. Only ever returns already-published content. Query params: `q` (full-text), `filter=field:op:value` (repeatable, ANDed; `op` is `eq`/`gt`/`gte`/`lt`/`lte`), `pageType`, `sort` (`-publishDate` for newest-first), `limit`, `offset`. Useful for a blog listing, a filterable directory, or a live search box.
 
+The index behind this endpoint keeps itself current automatically - it rebuilds in the background after every publish/unpublish/delete/move, and once at boot if no index exists yet (a fresh clone, since the index itself is never git-tracked). No manual step is needed for a blog listing built on this endpoint to work on a freshly deployed site.
+
 ## Hard constraints - do not deviate from these
 
 - **No dynamically registered Liquid tags or filters, ever.** Only standard LiquidJS built-ins (`if`, `for`, `assign`, `render`, filters like `upcase`, `times`) plus the CMS-provided context objects described above. Never invent a custom tag.
@@ -178,6 +346,7 @@ A public, unauthenticated, read-only endpoint - safe to call directly from a sec
 - **One file, one type, no subfolders** inside `layouts/`, `sections/`, `blocks/`, `snippets/` - and the filename must match `^[a-z0-9][a-z0-9-]*$` exactly.
 - **The `{% schema %}` block must be valid, parseable JSON.** A malformed or missing schema fails the whole component, not just the settings half.
 - **`additionalProperties: false` applies everywhere in content JSON** - don't add a field "just in case"; anything not in the tables above fails validation.
+- **Never invent a new setting field shape.** The "Field format hints" table is the complete, closed list of what the admin can actually edit - a plain type, a type plus one of the listed `format` values, `array` of plain strings, or `array` of plain images. A repeating item with more than one field of its own (an image plus a caption, a date, anything else) is a block type, not a wider array setting - see "This is a closed set" above.
 
 ## Previewing your work
 
@@ -186,6 +355,21 @@ From `vhost/`:
 ```
 npm start          # boots the site on the port set in vhost/site.config.json
 npm run tunnel      # same, plus a public tunnel URL for sharing a preview
+npm run dev         # same, plus auto-restart whenever a theme/ file changes - use this one while iterating
 ```
 
+`npm run dev` only watches `theme/` - content changes (via the API) already show up on the next request with no restart needed, so there's nothing to gain watching `content/` too.
+
 Then request the page you changed (`curl http://localhost:<port>/<path>`, or open it in a browser) and confirm it actually renders as expected before considering a change finished - a page that fails schema validation or references a non-existent section type won't crash the server, but the specific page/component involved will misbehave silently.
+
+## Checking your work: `npm run check`
+
+From `vhost/`, with the site's dependencies already installed (no need for the server to be running):
+
+```
+npm run check
+```
+
+Renders every published page for real and reports, in one pass: any theme component excluded at boot (same warnings the server itself prints, see "Minimal form" above); any `<img src>`/`srcset`/`<a href>` in the rendered HTML pointing at a `/media/`, `/assets/`, or root-static file that doesn't actually exist on disk; and any internal link that doesn't point at a real, published page. Exits non-zero if it finds anything - safe to run after generating content, not just as a manual spot-check.
+
+This catches the specific failure mode a snippet like `responsive-image` can introduce silently: a `widths` list that includes a size nothing was actually uploaded/generated for renders a perfectly normal-looking page with one broken image at that breakpoint - nothing about the page itself is wrong, so nothing else would ever flag it.

package/dist/create-site/template/content/menus/footerCompany.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "About", "url": "/about" },
     { "label": "Careers", "url": "/careers" },

package/dist/create-site/template/content/menus/footerProduct.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "Features", "url": "#features" },
     { "label": "Pricing", "url": "#pricing" },

package/dist/create-site/template/content/menus/footerResources.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "Documentation", "url": "/docs" },
     { "label": "Theme authoring guide", "url": "/docs/themes" },

package/dist/create-site/template/content/menus/main.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "Features", "url": "#features" },
     { "label": "How it works", "url": "#how-it-works" },

package/dist/create-site/template/content/pages/404.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Page not found — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/about/careers.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Careers — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/about/team.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Team — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/about.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "About — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs/deployment.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Deployment — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs/getting-started/quickstart.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Quickstart — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs/getting-started.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Getting Started — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Docs — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/index.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Granite CMS — Solid foundations for client sites",
   "type": "page",
   "layout": "theme",

package/dist/media/filename.d.ts

@@ -1 +1,2 @@
+export declare const ALLOWED_UPLOAD_EXTENSIONS: Set<string>;
 export declare function buildMediaFilename(originalFilename: string, bytes: Buffer): string;

package/dist/media/filename.js

@@ -21,6 +21,19 @@ import { basename, extname } from 'node:path';
 // lowercase, non [a-z0-9-] runs collapsed to a single "-", trimmed -
 // not a second, independently-invented convention.
 const HASH_LENGTH = 12;
+// Images only - confirmed with the user, not a general document
+// library. .svg is rejected regardless of this list even though it's
+// technically an image format - docs/cms-build-plan.md's own "SVG
+// rejected outright, not sanitised" decision (a real stored-XSS path
+// otherwise: mime-types.ts maps .svg to a real image/svg+xml content
+// type, and an SVG loaded as a top-level navigation, not just <img>-
+// embedded, can execute a script it carries).
+//
+// Exported from here, not left as routes/media.ts's own private
+// constant, specifically so seed-media.ts (an offline tool with no
+// HTTP request to validate) enforces the exact same rule rather than
+// a second, independently-maintained copy of it.
+export const ALLOWED_UPLOAD_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
 export function buildMediaFilename(originalFilename, bytes) {
     const hash = createHash('sha256').update(bytes).digest('hex').slice(0, HASH_LENGTH);
     const base = basename(originalFilename, extname(originalFilename));

package/dist/media/seed-media-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/media/seed-media-cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { seedMedia } from "./seed-media.js";
+const [targetArg, ...sourceArgs] = process.argv.slice(2);
+if (!targetArg || sourceArgs.length === 0) {
+    console.error('Usage: seed-media <site-directory> <path> [<path> ...]');
+    process.exit(1);
+}
+const siteDir = resolve(process.cwd(), targetArg);
+const sourcePaths = sourceArgs.map((sourceArg) => resolve(process.cwd(), sourceArg));
+const result = seedMedia(siteDir, sourcePaths);
+for (const entry of result.entries) {
+    if (entry.status === 'seeded') {
+        console.log(`${entry.sourcePath} -> ${entry.url}`);
+    }
+    else {
+        console.log(`${entry.sourcePath}: skipped (${entry.reason})`);
+    }
+}
+if (!result.ok) {
+    process.exit(1);
+}

package/dist/media/seed-media.d.ts

@@ -0,0 +1,11 @@
+export interface SeedMediaEntry {
+    sourcePath: string;
+    status: 'seeded' | 'skipped-invalid-type';
+    url?: string;
+    reason?: string;
+}
+export interface SeedMediaResult {
+    ok: boolean;
+    entries: SeedMediaEntry[];
+}
+export declare function seedMedia(siteRoot: string, sourcePaths: string[]): SeedMediaResult;

package/dist/media/seed-media.js

@@ -0,0 +1,76 @@
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { ALLOWED_UPLOAD_EXTENSIONS, buildMediaFilename } from "./filename.js";
+// A directory argument expands to its own direct child files only -
+// one level, not recursive, matching theme-schemas.ts's own flat-
+// directory convention for exactly the same reason (a predictable,
+// easy-to-reason-about walk, not a surprise deep scan).
+function expandSourcePaths(sourcePaths) {
+    const files = [];
+    for (const sourcePath of sourcePaths) {
+        if (statSync(sourcePath).isDirectory()) {
+            for (const entry of readdirSync(sourcePath, { withFileTypes: true })) {
+                if (entry.isFile()) {
+                    files.push(join(sourcePath, entry.name));
+                }
+            }
+        }
+        else {
+            files.push(sourcePath);
+        }
+    }
+    return files;
+}
+// Seeds one or more local image files directly into a site's media/,
+// computing the exact same content-addressed filename a real
+// POST /v1/media upload would - see this module's own filename.ts for
+// why that's safe to do offline (a pure function of a filename and the
+// file's own bytes, no server/database involved). For an AI agent (or
+// any offline tool) generating a site's starter content before a
+// server is even running - GET /media/* just serves whatever file
+// exists at the requested path, so the result is indistinguishable
+// from a real upload.
+//
+// siteRoot is an operator/agent-supplied directory, the same category
+// as scaffoldSite/mintToken - not a web request's own :path, so
+// sanitisePath's traversal concern doesn't apply here (see
+// mint-token.ts's own comment on this exact point).
+//
+// Never a git commit - media is never git-tracked (constraint 2,
+// matching manage-media.ts's own "no commit, no author... Media is
+// never git-tracked" comment).
+//
+// A disallowed file type is skipped, not a reason to abort the whole
+// batch - an agent seeding a dozen images should still get the eleven
+// good ones, with the one bad one clearly reported. The allowlist
+// itself is the one thing that must not be relaxed here: it's the
+// same rule the real upload route enforces (ALLOWED_UPLOAD_EXTENSIONS,
+// shared, not a second copy), because skipping it would reopen the
+// real stored-XSS path SVG rejection exists to close, for whoever
+// later visits the live site - not a concern about this tool's own
+// caller, who already has full local trust.
+export function seedMedia(siteRoot, sourcePaths) {
+    const mediaRoot = join(siteRoot, 'media');
+    mkdirSync(mediaRoot, { recursive: true });
+    const entries = [];
+    for (const sourcePath of expandSourcePaths(sourcePaths)) {
+        const extension = extname(sourcePath).toLowerCase();
+        if (!ALLOWED_UPLOAD_EXTENSIONS.has(extension)) {
+            entries.push({
+                sourcePath,
+                status: 'skipped-invalid-type',
+                reason: `"${extension}" is not an accepted image type`,
+            });
+            continue;
+        }
+        const bytes = readFileSync(sourcePath);
+        const name = buildMediaFilename(basename(sourcePath), bytes);
+        // No existence check first: content-addressed naming means
+        // re-seeding the same bytes writes identical bytes over identical
+        // bytes - a harmless idempotent overwrite, matching
+        // local-fs-driver.ts's own put() precedent exactly.
+        writeFileSync(join(mediaRoot, name), bytes);
+        entries.push({ sourcePath, status: 'seeded', url: `/media/${name}` });
+    }
+    return { ok: entries.every((entry) => entry.status === 'seeded'), entries };
+}

package/dist/renderer/render-page.d.ts

@@ -20,6 +20,9 @@ export interface PageContent {
     published: boolean;
     layout: string;
     sections: SectionOrBlockInstance[];
+    author?: string;
+    publishDate?: string;
+    tags?: string[];
 }
 export declare function renderSections(page: PageContent, themeTemplates: ThemeTemplates, engine: Liquid): Promise<string>;
 export type RenderMode = 'public' | 'preview';

package/dist/renderer/render-page.js

@@ -10,13 +10,16 @@ export class PageRenderError extends Error {
         this.reason = reason;
     }
 }
+function pageEnvelope(page) {
+    return { title: page.title, author: page.author, publishDate: page.publishDate, tags: page.tags };
+}
 // Renders one section or block, recursively rendering any nested blocks
 // first (instance.schema.json is self-referential, so a block can carry
 // its own nested blocks). Never uses {% include %}/{% render %}: block
 // HTML is pre-rendered here in JS and handed to the parent template as
 // a plain array, which sidesteps LiquidJS's own filesystem include
 // resolution entirely.
-async function renderInstance(instance, kind, themeTemplates, engine) {
+async function renderInstance(instance, kind, themeTemplates, engine, page) {
     const templates = kind === 'section' ? themeTemplates.sections : themeTemplates.blocks;
     const template = templates[instance.type];
     if (!template) {
@@ -24,13 +27,16 @@ async function renderInstance(instance, kind, themeTemplates, engine) {
     }
     const blocksHtml = [];
     for (const block of instance.blocks ?? []) {
-        blocksHtml.push(await renderInstance(block, 'block', themeTemplates, engine));
+        blocksHtml.push(await renderInstance(block, 'block', themeTemplates, engine, page));
     }
     // Shopify-style scope shape: settings nested under the instance, not
     // flattened, so templates read section.settings.x / block.settings.x.
+    // `page` is the same built-in envelope a layout gets (title plus the
+    // optional author/publishDate/tags fields) - lets a section print a
+    // byline/date without duplicating it into a settings field.
     const scope = kind === 'section'
-        ? { section: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml }
-        : { block: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml };
+        ? { section: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml, page }
+        : { block: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml, page };
     try {
         return (await engine.parseAndRender(template, scope));
     }
@@ -46,9 +52,10 @@ async function renderInstance(instance, kind, themeTemplates, engine) {
 // No page-level layout/wrapper concept in Phase 1 - this is the whole
 // output.
 export async function renderSections(page, themeTemplates, engine) {
+    const envelope = pageEnvelope(page);
     const html = [];
     for (const section of page.sections) {
-        html.push(await renderInstance(section, 'section', themeTemplates, engine));
+        html.push(await renderInstance(section, 'section', themeTemplates, engine, envelope));
     }
     return html.join('');
 }
@@ -134,7 +141,7 @@ export async function renderLoadedPage(page, config, themeTemplates, layouts, en
     // outputEscape: 'escape' double-escapes it into literal text.
     return (await engine.parseAndRender(layoutTemplate, {
         content_for_layout: bodyHtml,
-        page: { title: page.title },
+        page: pageEnvelope(page),
         menus,
     }));
 }