@o-a/cms-agent 0.2.0 → 0.2.2

package/README.md

@@ -35,27 +35,18 @@ Granite CMS is the combination neither of those is:
 
 - **Developers** build the theme: Liquid layouts, sections, and blocks,
   each with an embedded JSON Schema for its settings. Start with
-  [`docs/theme-authoring-guide.md`](docs/theme-authoring-guide.md).
+  [`docs/guide-theme-authoring.md`](docs/guide-theme-authoring.md).
 - **Content editors / marketing managers** never touch this repository at
   all - they work entirely through a separate admin application (see
   [Companion projects](#companion-projects) below), browsing pages,
   editing sections, and publishing through the API this package exposes.
   The content model itself is documented in
-  [`docs/content-authoring-guide.md`](docs/content-authoring-guide.md).
+  [`docs/guide-content-authoring.md`](docs/guide-content-authoring.md).
 
 ## Quick start
 
-> **Not yet published to npm.** Until it is, install from a local build -
-> see [`docs/hosting.md`](docs/hosting.md#installing-o-acms-agent-today) for
-> the exact steps. Once published, this becomes:
->
-> ```
-> npx -p @o-a/cms-agent create-site my-site
-> ```
-
-Either way, the result is the same:
-
 ```
+npx -p @o-a/cms-agent create-site my-site
 cd my-site/vhost
 npm install
 npm start
@@ -76,7 +67,7 @@ and the site's own serving configuration lives under `vhost/`:
 
 ```
 my-site/
-  content/   pages, posts, menus, redirects, drafts
+  content/   pages, menus, redirects, drafts
   theme/     layouts, sections, blocks, snippets, assets, root, templates
   media/     uploaded files - gitignored, backed up separately
   vhost/     site.config.json, package.json, server.js
@@ -97,9 +88,9 @@ install.
 
 ## Documentation
 
-- [`docs/theme-authoring-guide.md`](docs/theme-authoring-guide.md) - building a theme
-- [`docs/content-authoring-guide.md`](docs/content-authoring-guide.md) - the content model
-- [`docs/hosting.md`](docs/hosting.md) - running a site somewhere real
+- [`docs/guide-theme-authoring.md`](docs/guide-theme-authoring.md) - building a theme
+- [`docs/guide-content-authoring.md`](docs/guide-content-authoring.md) - the content model
+- [`docs/guide-hosting.md`](docs/guide-hosting.md) - running a site somewhere real
 - [`docs/cms-build-plan.md`](docs/cms-build-plan.md) - full architecture and design rationale
 
 A friendlier, browsable documentation site (covering both this engine and

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

@@ -114,6 +114,6 @@ export function scaffoldSite(targetDir) {
     // runStartupChecks hard-fails not-a-git-repo otherwise - a scaffold
     // without a real git repo cannot boot at all.
     execFileSync('git', ['init', '--quiet'], { cwd: targetDir });
-    commitPaths(targetDir, ['theme', 'content', 'vhost', '.gitignore', '.dockerignore'], 'chore: initial scaffold', CHECKPOINT_AUTHOR);
+    commitPaths(targetDir, ['theme', 'content', 'vhost', 'AGENTS.md', '.gitignore', '.dockerignore'], 'chore: initial scaffold', CHECKPOINT_AUTHOR);
     return { raw: token.raw };
 }

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

@@ -0,0 +1,196 @@
+# AGENTS.md
+
+This file orients an AI coding agent working in this repository. It is written for the task of turning a visual design (a screenshot, a Figma export, a written brief) into working site code - not for general software engineering advice.
+
+This repo is a single site built on Granite CMS: a self-hosted, git-backed CMS. There is no framework source code here to read - the CMS itself is an installed dependency (`vhost/node_modules/@o-a/cms-agent`). Everything that makes this site what it is lives in two folders:
+
+```
+theme/     Liquid templates - the design/markup layer
+content/   JSON files - the actual page content, git-tracked, the source of truth
+media/     uploaded images - not git-tracked, see "Images" below
+vhost/     deploy config (package.json, server.js, site.config.json) - rarely needs editing
+```
+
+Every rule below is exact, not a rough guide - the CMS validates content against real JSON Schemas and will reject anything that deviates. Where this file gives a worked example, prefer copying its shape over improvising a new one.
+
+## Folder structure inside `theme/`
+
+```
+theme/
+  layouts/    *.liquid, flat, no schema - page wrappers (<html>, <head>, nav, footer)
+  sections/   *.liquid, flat, one per section type - markup + embedded settings schema
+  blocks/     *.liquid, flat, one per block type - markup + embedded settings schema
+  snippets/   *.liquid, flat, no schema - small reusable partials, invoked with {% render %}
+  assets/     static files (CSS, JS, images) - served as-is at /assets/<path>
+  root/       static files served at the bare site root (robots.txt, favicon.ico, etc.)
+  templates/  *.json, flat, optional - prebuilt starting pages an editor can pick from
+```
+
+No subfolders inside `layouts/`, `sections/`, `blocks/`, or `snippets/` - one file, one component, named directly. The filename (without `.liquid`) is that component's type identifier and must match `^[a-z0-9][a-z0-9-]*$` (lowercase, digits, hyphens only). This exact string is what page content JSON uses in its own `"type"` field - they must match exactly.
+
+This scaffold already ships real, working examples worth reading before writing anything new: `theme/sections/hero.liquid`, `theme/blocks/button.liquid`, and `theme/layouts/theme.liquid`. Match their conventions rather than inventing a different style.
+
+## 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).
+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".
+
+### Worked example - a section
+
+```liquid
+<section class="hero" data-section-id="{{ section.id }}">
+  <h1>{{ section.settings.heading }}</h1>
+  {% if section.settings.subheading %}<p>{{ section.settings.subheading }}</p>{% endif %}
+  <div class="hero__blocks">{% for html in blocksHtml %}{{ html | raw }}{% endfor %}</div>
+</section>
+{% schema %}
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["heading"],
+  "properties": {
+    "heading": { "type": "string", "minLength": 1, "default": "New section" },
+    "subheading": { "type": "string" }
+  }
+}
+{% endschema %}
+```
+
+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 - 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).
+
+### 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
+{{ 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
+```
+
+### Snippets
+
+Flat `.liquid` files in `snippets/`, invoked with `{% render 'name', param1: value %}` - never `{% include %}`. A snippet only sees parameters explicitly passed to it; the calling scope never leaks in.
+
+## Field format hints
+
+Every setting is plain JSON Schema (`string`, `integer`, `number`, `boolean`, `array`, with `minLength`/`minimum`/`enum`/etc. for real validation). One extra keyword, `"format"`, is a UI hint only (never validated server-side) that the admin reads to choose a richer input widget:
+
+| `format` | On type | Effect |
+|---|---|---|
+| `richtext` | `string` | Rich-text editor; render with `{{ ... | raw }}`, not plain `{{ }}` |
+| `image` | `object` | Image picker with focal point; object shape is exactly `{ "url": "...", "focalX": 0.5, "focalY": 0.5 }` - render `{{ section.settings.<field>.url }}` |
+| `textarea` | `string` | Multi-line `<textarea>` |
+| `uri` | `string` | `<input type="url">` |
+| `date` | `string` | `<input type="date">`, value as `YYYY-MM-DD` |
+| `color` | `string` | Hex value (e.g. `"#ff6600"`); optional sibling `"swatches": ["#c2410c", ...]` for a preset palette (not an `enum` - a custom colour is still always allowed) |
+| `range` | `integer`/`number` | Slider + number box; requires `minimum`/`maximum`; optional `"step"` (default `1`) and `"unit"` (e.g. `"px"`) |
+| `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 |
+
+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.
+
+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
+
+`content/pages/*.json` - nested folders allowed via a **sibling** pattern: a page with children is a `.json` file sitting beside a same-named folder (`about.json` next to `about/team.json`, never `about/about.json`). A URL maps directly to this path; `/` maps to `index.json`.
+
+Required fields, `additionalProperties: false`:
+
+| Field | Type | Notes |
+|---|---|---|
+| `schemaVersion` | integer | Always `6` for new content |
+| `name` | string | Internal label (shown in the admin's page tree) |
+| `title` | string | Rendered as `{{ page.title }}` |
+| `type` | string | Free-form (e.g. `"page"`, `"blog-article"`) - use `pageType` filtering below to distinguish kinds |
+| `layout` | string | A filename in `theme/layouts/` (no extension) - `"theme"` unless a different layout exists |
+| `published` | boolean | `false` behaves as if the page doesn't exist on the live site at all |
+| `sections` | array | Section instances - see below |
+
+Optional fields, any page may carry them: `author` (string), `publishDate` (string, `YYYY-MM-DD` recommended - it's indexed numerically for sorting/range filters), `tags` (array of non-empty strings). There is no separate "post" content type - a blog article is just a page, conventionally nested under a `content/pages/blog/` folder.
+
+Each entry in `sections` requires `id` (any non-empty string, unique within the page), `type` (must exactly match a filename in `theme/sections/`), and `settings` (matching that type's schema). Optional `blocks` array, same shape, referencing `theme/blocks/`.
+
+```json
+{
+  "schemaVersion": 6,
+  "name": "Home",
+  "title": "Welcome",
+  "type": "page",
+  "layout": "theme",
+  "published": true,
+  "sections": [
+    {
+      "id": "sec-hero",
+      "type": "hero",
+      "settings": { "heading": "Welcome" },
+      "blocks": [
+        { "id": "blk-cta", "type": "button", "settings": { "label": "Get started", "url": "/" } }
+      ]
+    }
+  ]
+}
+```
+
+`content/menus/<name>.json` - referenced in layouts as `{{ menus.<name>.items }}`:
+
+```json
+{ "schemaVersion": 6, "items": [{ "label": "Home", "url": "/" }, { "label": "About", "url": "/about" }] }
+```
+
+`content/redirects.json` - a single file, not a folder:
+
+```json
+{ "schemaVersion": 1, "entries": [{ "from": "/old-path", "to": "/new-path" }] }
+```
+
+`to` must be a bare internal path (no `https://`, no leading `//`). A redirect never overrides a real page at the same URL.
+
+`content/pages/404.json`, if present and `published`, renders through the normal page pipeline with the HTTP status forced to 404 - the standard way to give a broken URL a real branded page instead of a bare JSON error.
+
+## Images
+
+Uploads go through `POST /v1/media` (multipart, requires a token with `media` scope) or the admin's own media library UI - never write directly into `media/` from an agent, since the CMS names files by content hash. A successful upload returns `{ "url": "/media/<name>" }`. In theme content, an image is just a plain string setting holding that URL:
+
+```json
+{ "type": "string", "default": "" }
+```
+
+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.
+
+## `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.
+- **`{{ }}` auto-escapes HTML by default.** Only use `| raw` for values the CMS itself already produced as safe HTML (`blocksHtml` entries, `content_for_layout`, a `format: "richtext"` field). Never apply `| raw` to an ordinary setting value.
+- **Every template render is bounded to roughly 50ms.** Keep Liquid logic simple - loops and conditionals, no heavy computation.
+- **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.
+
+## Previewing your work
+
+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
+```
+
+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.

package/dist/create-site/template/vhost/Dockerfile

@@ -1,7 +1,7 @@
 # Generic and site-content-agnostic - this file never needs to change
 # per site. Runs identically via plain `docker build`/`docker run` on a
 # bare VPS, Fly, ECS, or any PaaS - nothing platform-specific is baked
-# in here (see docs/hosting.md for platform-specific deploy config,
+# in here (see docs/guide-hosting.md for platform-specific deploy config,
 # which always layers on top of this, never inside it).
 #
 # Lives in vhost/, not the site root, alongside the rest of the site's

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,
     }));
 }

package/dist/routes/sitemap.js

@@ -29,7 +29,7 @@ function buildSitemapUrls(config) {
     for (const relativePath of listFilesRecursively(config.pagesRoot, config.pagesRoot, '.json')) {
         // The 404 page must never be listed as a real crawlable URL,
         // regardless of its own published flag - it's a fallback
-        // convention (docs/content-authoring-guide.md), not real content.
+        // convention (docs/guide-content-authoring.md), not real content.
         if (relativePath === '404.json') {
             continue;
         }

package/dist/search/rebuild-index.d.ts

@@ -1,2 +1,3 @@
 import type { SiteConfig } from '../config.ts';
 export declare function rebuildIndex(config: SiteConfig): Promise<void>;
+export declare function rebuildIndexIfMissing(config: SiteConfig): Promise<void>;

package/dist/search/rebuild-index.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { listFilesRecursively } from "../services/fs-walk.js";
@@ -106,7 +106,7 @@ function pushFieldValue(blockType, instanceId, fieldKey, value, isDateField, out
 // Reads schema.properties for the given instance's own type, keeping
 // only properties explicitly flagged "api": true (an unvalidated,
 // theme-authored JSON Schema keyword - same status as "format"/
-// "allowedBlocks", see docs/theme-authoring-guide.md and
+// "allowedBlocks", see docs/guide-theme-authoring.md and
 // services/validation.ts's own allowedBlockTypesOf) - and pairs each
 // with its actual value out of instance.settings via pushFieldValue.
 function extractInstanceApiFields(instance, schemaMap, out) {
@@ -302,3 +302,19 @@ async function rebuildIndexJob(config) {
 export function rebuildIndex(config) {
     return enqueue(() => rebuildIndexJob(config));
 }
+// For startServer's own boot-time call: a search index is never
+// git-tracked (constraint 3 - a derived, disposable index), so a fresh
+// clone or a first-ever boot has no index file at all and GET
+// /search.json would stay permanently empty until some content write
+// happened to trigger reindex-on-write.ts, or a caller manually hit
+// POST /v1/search/rebuild. Guarded on existsSync rather than
+// unconditionally rebuilding on every restart - a currently-running
+// site's index is already kept fresh by every publish/unpublish/
+// delete/move/batch (reindex-on-write.ts), so an unconditional rebuild
+// here would just be redundant work on every ordinary restart.
+export function rebuildIndexIfMissing(config) {
+    if (existsSync(config.searchIndexPath)) {
+        return Promise.resolve();
+    }
+    return rebuildIndex(config);
+}

package/dist/server.js

@@ -12,6 +12,7 @@ import { sitemapRoutes } from "./routes/sitemap.js";
 import { CHECKPOINT_AUTHOR, runCheckpoint } from "./services/checkpoint.js";
 import { startDevTunnel } from "./services/dev-tunnel.js";
 import { startIntervalJob } from "./services/interval-job.js";
+import { reindexOnBootIfMissing } from "./services/reindex-on-write.js";
 // Never wrap v1Routes (or any route-group plugin it registers) with
 // fastify-plugin (fp()): plain app.register() gives each file its own
 // encapsulation scope by default, which Group B's auth preHandler
@@ -132,6 +133,15 @@ export async function startServer(siteRoot, options = {}) {
     const booted = bootSite(siteRoot);
     const serverConfig = loadServerConfig(siteRoot);
     const app = buildServer(booted, serverConfig, options);
+    // Previously these three failure cases (missing/invalid {% schema %}
+    // block, or a required property with no valid default) were
+    // completely silent - a broken component just stopped being
+    // selectable, with nothing distinguishing "deliberately excluded"
+    // from "you have a typo". Never a boot failure (loadThemeSchemas's
+    // own contract), just no longer silent about it either.
+    for (const warning of booted.themeSchemas.warnings ?? []) {
+        console.warn(warning);
+    }
     const doCheckpoint = () => runCheckpoint(booted.config, CHECKPOINT_AUTHOR);
     const scheduler = startIntervalJob(doCheckpoint, serverConfig.checkpointIntervalMs, (error) => {
         app.log.error(error, 'background draft checkpoint failed');
@@ -191,6 +201,13 @@ export async function startServer(siteRoot, options = {}) {
     if (address !== null && typeof address !== 'string') {
         console.log(`Site running at http://127.0.0.1:${address.port}`);
     }
+    // A search index is never git-tracked (constraint 3), so a fresh
+    // clone or first-ever boot has no index file - without this,
+    // GET /search.json would stay empty until the first content write.
+    // Fire-and-forget, after the port is already bound: never blocks
+    // startup, and a slow/failed rebuild is never a reason the server
+    // itself fails to come up.
+    reindexOnBootIfMissing(booted.config);
     if (options.tunnel) {
         try {
             tunnel = await (options.startTunnel ?? startDevTunnel)(serverConfig.port);

package/dist/services/batch.js

@@ -4,6 +4,7 @@ import { commitPaths } from "./git.js";
 import { MoveError, prepareMovePage } from "./move.js";
 import { PublishError, preparePublishDrafts } from "./publish.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 export class BatchError extends Error {
     reason;
     // Which part of the batch failed. operationIndex indexes into the
@@ -132,5 +133,13 @@ async function rollbackAndThrow(undoStack, cause, context) {
     throw new BatchError('commit-failed', `Batch failed: ${detail}`, { cause, ...context });
 }
 export function runBatch(config, themeSchemas, operations, publish, message, author) {
-    return enqueue(() => batchJob(config, themeSchemas, operations, publish, message, author));
+    const result = enqueue(() => batchJob(config, themeSchemas, operations, publish, message, author));
+    // One trigger for the whole batch, regardless of which operation
+    // types it contained (content-delete/move/publish affect the index,
+    // draft-write/draft-discard don't) - simpler and no real cost than
+    // inspecting `operations` to decide, since this never blocks the
+    // caller either way. See reindex-on-write.ts for why this is
+    // fire-and-forget, chained onto `result` rather than awaited here.
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/delete-content.js

@@ -5,6 +5,7 @@ import { sanitisePath } from "./path-safety.js";
 import { RedirectError, addRedirect, isValidRedirectTarget, loadRedirects, serialiseRedirects, } from "./redirects.js";
 import { pagePathToUrl } from "./urls.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 const PAGES_PREFIX = 'pages/';
 // Returns null for anything else (menus have no public URL at all, so
 // redirects are meaningless there).
@@ -159,5 +160,7 @@ async function deleteContentJob(config, relativePath, redirectTo, message, autho
     }
 }
 export function deleteContent(config, relativePath, redirectTo, message, author) {
-    return enqueue(() => deleteContentJob(config, relativePath, redirectTo, message, author));
+    const result = enqueue(() => deleteContentJob(config, relativePath, redirectTo, message, author));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/move.js

@@ -6,6 +6,7 @@ import { sanitisePath } from "./path-safety.js";
 import { addRedirect, loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redirects.js";
 import { pagePathToUrl, urlToPagePath } from "./urls.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 export class MoveError extends Error {
     reason;
     constructor(reason, message, options) {
@@ -171,5 +172,7 @@ async function movePageJob(config, fromUrl, toUrl, message, author, options = {}
     }
 }
 export function movePage(config, fromUrl, toUrl, message, author, options = {}) {
-    return enqueue(() => movePageJob(config, fromUrl, toUrl, message, author, options));
+    const result = enqueue(() => movePageJob(config, fromUrl, toUrl, message, author, options));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/publish.js

@@ -6,6 +6,7 @@ import { loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redi
 import { pagePathToUrl } from "./urls.js";
 import { validateContent } from "./validation.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 const PAGES_PREFIX = 'pages/';
 // Mirrors delete-content.ts's urlForDeletedEntry - a tiny duplicated
 // helper, not a shared abstraction. Returns null for anything else
@@ -241,8 +242,18 @@ async function unpublishPageJob(config, relativePath, message, author) {
     }
 }
 export function publishDrafts(config, themeSchemas, relativePaths, message, author) {
-    return enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
+    const result = enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
+    // Only on success - a failed publish changed nothing, so there's
+    // nothing to reindex. Chained onto `result` rather than awaited here:
+    // by the time this callback runs, the write-queue's own tail has
+    // already advanced past this job, so reindexInBackground's own
+    // enqueue()d rebuild queues cleanly behind it (see that function's
+    // own comment on why calling it any earlier would deadlock).
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }
 export function unpublishPage(config, relativePath, message, author) {
-    return enqueue(() => unpublishPageJob(config, relativePath, message, author));
+    const result = enqueue(() => unpublishPageJob(config, relativePath, message, author));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/reindex-on-write.d.ts

@@ -0,0 +1,3 @@
+import type { SiteConfig } from '../config.ts';
+export declare function reindexInBackground(config: SiteConfig): void;
+export declare function reindexOnBootIfMissing(config: SiteConfig): void;

package/dist/services/reindex-on-write.js

@@ -0,0 +1,30 @@
+import { rebuildIndex, rebuildIndexIfMissing } from "../search/rebuild-index.js";
+// Search is a derived, disposable index (constraint 3) - previously
+// nothing ever rebuilt it except a caller manually hitting
+// POST /v1/search/rebuild, so GET /search.json stayed empty forever on
+// a fresh site and stale forever after a real edit. This is the one
+// place that closes that gap: called after a content-affecting write's
+// own enqueue()d promise has already resolved.
+//
+// Deliberately fire-and-forget, never awaited by the caller: rebuildIndex
+// is itself enqueue()d internally (search/rebuild-index.ts) - awaiting it
+// from inside the very job whose own completion is what let this run
+// would deadlock (routes/search.ts's own comment describes the same
+// hazard for a second, nested enqueue() call). A failed reindex must
+// also never surface as a failure of the write that triggered it - the
+// write already succeeded, and the index is rebuildable from content at
+// any time, so a logged-and-swallowed failure here is the correct
+// severity, not a thrown error.
+export function reindexInBackground(config) {
+    void rebuildIndex(config).catch((error) => {
+        console.error('Background search reindex failed:', error);
+    });
+}
+// startServer's own boot-time call - see rebuildIndexIfMissing's own
+// comment for why this is conditional (existsSync), unlike the
+// unconditional reindexInBackground above.
+export function reindexOnBootIfMissing(config) {
+    void rebuildIndexIfMissing(config).catch((error) => {
+        console.error('Background search reindex failed:', error);
+    });
+}

package/dist/services/theme-schemas.js

@@ -12,9 +12,13 @@ import { requiredFieldsHaveValidDefaults } from "./validation.js";
 // loadFlatTemplates walk exactly (already established for snippets/
 // layouts), extended to extract the embedded {% schema %} block instead
 // of returning the raw file contents.
-function loadTypeSchemas(typesDir) {
+//
+// kind is only used to word each warning ("Section" vs "Block") -
+// callers already know which directory they asked for.
+function loadTypeSchemas(typesDir, kind) {
     const schemas = {};
     const acceptsBlocks = {};
+    const warnings = [];
     let entries;
     try {
         entries = readdirSync(typesDir, { withFileTypes: true })
@@ -22,10 +26,11 @@ function loadTypeSchemas(typesDir) {
             .map((entry) => entry.name);
     }
     catch {
-        return { schemas, acceptsBlocks };
+        return { schemas, acceptsBlocks, warnings };
     }
     for (const fileName of entries) {
         const type = fileName.slice(0, -'.liquid'.length);
+        const label = `${kind} type "${type}" (${fileName}) was excluded from the theme`;
         let source;
         try {
             source = readFileSync(join(typesDir, fileName), 'utf-8');
@@ -35,29 +40,32 @@ function loadTypeSchemas(typesDir) {
         }
         const parsed = parseThemeComponentFile(source);
         if (!parsed) {
+            warnings.push(`${label}: no valid {% schema %} block found (missing, or not parseable JSON).`);
             continue;
         }
         // A type whose required settings fields lack usable defaults is
         // skipped the same way a malformed schema block already is -
         // never a boot failure, just excluded from what gets registered
-        // (theme-authoring-guide.md, Group L).
+        // (guide-theme-authoring.md, Group L).
         if (!requiredFieldsHaveValidDefaults(parsed.schema)) {
+            warnings.push(`${label}: a property listed in "required" has no valid "default" (see guide-theme-authoring.md).`);
             continue;
         }
         schemas[type] = parsed.schema;
         // The only place "does this type support nested blocks" is ever
         // expressed - a markup convention (does the template loop
-        // blocksHtml), not a schema field (theme-authoring-guide.md).
+        // blocksHtml), not a schema field (guide-theme-authoring.md).
         acceptsBlocks[type] = parsed.markup.includes('blocksHtml');
     }
-    return { schemas, acceptsBlocks };
+    return { schemas, acceptsBlocks, warnings };
 }
 export function loadThemeSchemas(themeRoot) {
-    const sections = loadTypeSchemas(join(themeRoot, 'sections'));
-    const blocks = loadTypeSchemas(join(themeRoot, 'blocks'));
+    const sections = loadTypeSchemas(join(themeRoot, 'sections'), 'Section');
+    const blocks = loadTypeSchemas(join(themeRoot, 'blocks'), 'Block');
     return {
         sections: sections.schemas,
         blocks: blocks.schemas,
         acceptsBlocks: { sections: sections.acceptsBlocks, blocks: blocks.acceptsBlocks },
+        warnings: [...sections.warnings, ...blocks.warnings],
     };
 }

package/dist/services/validation.d.ts

@@ -14,6 +14,7 @@ export interface ThemeSchemas {
         sections: Record<string, boolean>;
         blocks: Record<string, boolean>;
     };
+    warnings?: string[];
 }
 export declare function requiredFieldsHaveValidDefaults(schema: object): boolean;
 export declare function validateInstance(instance: unknown, kind: 'section' | 'block', themeSchemas: ThemeSchemas): ValidationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-a/cms-agent",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "publishConfig": {
     "access": "public"