@o-a/cms-agent 0.1.7 → 0.2.1

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/boot.d.ts

@@ -1,5 +1,6 @@
 import type { Liquid } from 'liquidjs';
 import type { SiteConfig } from './config.ts';
+import type { RenderCache } from './renderer/render-cache.ts';
 import type { ThemeTemplates } from './renderer/theme-templates.ts';
 import type { StartupCheckOptions } from './services/startup-checks.ts';
 import type { ThemeSchemas } from './services/validation.ts';
@@ -11,5 +12,6 @@ export interface BootedSite {
     layouts: Record<string, string>;
     pageTemplates: PageTemplate[];
     engine: Liquid;
+    renderCache: RenderCache;
 }
 export declare function bootSite(siteRoot: string, options?: StartupCheckOptions): BootedSite;

package/dist/boot.js

@@ -1,5 +1,6 @@
 import { loadSiteConfig } from "./config.js";
 import { createEngine } from "./renderer/engine.js";
+import { createRenderCache } from "./renderer/render-cache.js";
 import { loadLayouts, loadSnippets, loadThemeTemplates } from "./renderer/theme-templates.js";
 import { runStartupChecks } from "./services/startup-checks.js";
 import { loadThemeSchemas } from "./services/theme-schemas.js";
@@ -29,5 +30,6 @@ export function bootSite(siteRoot, options) {
     // page.
     const pageTemplates = loadPageTemplates(config.templatesRoot, themeSchemas);
     const engine = createEngine(snippets);
-    return { config, themeSchemas, themeTemplates, layouts, pageTemplates, engine };
+    const renderCache = createRenderCache();
+    return { config, themeSchemas, themeTemplates, layouts, pageTemplates, engine, renderCache };
 }

package/dist/config.d.ts

@@ -8,7 +8,6 @@ export interface SiteConfig {
     rootMirrorRoot: string;
     templatesRoot: string;
     pagesRoot: string;
-    postsRoot: string;
     menusRoot: string;
     redirectsPath: string;
     vhostRoot: string;

package/dist/config.js

@@ -33,7 +33,6 @@ export function loadSiteConfig(siteRoot) {
         rootMirrorRoot: join(themeRoot, 'root'),
         templatesRoot: join(themeRoot, 'templates'),
         pagesRoot: join(contentRoot, 'pages'),
-        postsRoot: join(contentRoot, 'posts'),
         menusRoot: join(contentRoot, 'menus'),
         // Also nested inside contentRoot, for the same reason.
         redirectsPath: join(contentRoot, 'redirects.json'),

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,191 @@
+# 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>`, 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.
+
+**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.
+
+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 (the ONLY page field exposed to layouts)
+{{ 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.
+
+## 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/media/filename.js

@@ -27,5 +27,8 @@ export function buildMediaFilename(originalFilename, bytes) {
     const cleaned = base.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
     const slug = cleaned.length > 0 ? cleaned : 'file';
     const extension = extname(originalFilename).toLowerCase();
-    return `${hash}-${slug}${extension}`;
+    // Slug first, hash last (requested directly) - the readable part of
+    // the filename sorts and scans first in a directory listing/URL,
+    // with the hash as a suffix rather than something to read past.
+    return `${slug}-${hash}${extension}`;
 }

package/dist/migrations/index.d.ts

@@ -1,3 +1,3 @@
 import type { MigrationMap } from '../services/migration-runner.ts';
-export declare const CURRENT_SCHEMA_VERSION = 5;
+export declare const CURRENT_SCHEMA_VERSION = 6;
 export declare const migrations: MigrationMap;

package/dist/migrations/index.js

@@ -1,7 +1,7 @@
 // The current content schema version. Bumping this and adding a new
 // migrations[N] entry is the only way a content shape may change
 // (constraint 4) - never a manual edit convention.
-export const CURRENT_SCHEMA_VERSION = 5;
+export const CURRENT_SCHEMA_VERSION = 6;
 // A trivial identity migration, proving the mechanism (per the build
 // plan's Phase 1 scope): no shape change, only the version bump. Safe
 // against page.schema.json's schemaVersion: { minimum: 1 } (not an
@@ -41,9 +41,32 @@ function migrateV4ToV5(content) {
     const title = typeof content.title === 'string' ? content.title : '';
     return { ...content, schemaVersion: 5, name: title };
 }
+// Folds the distinct "post" content type into "page" - author,
+// publishDate, and tags become optional fields any page may carry
+// (page.schema.json), and the post-only schema (which required them,
+// but had no "name" field at all) is retired. Ordinary pages already
+// at v5 already have "name"; this is only ever a genuine backfill for
+// a legacy content/posts/*.json file, which never had one. Mirrors the
+// admin's own backfillPageName (derivePageLabel.ts) precisely: fills
+// name from title only when name is genuinely absent, never overwrites
+// an existing one (a page's name may deliberately differ from its
+// title - migrateV4ToV5's own unconditional set was safe only because
+// no content reaching it could already have a name).
+// migration-runner.ts's runMigrationsJob is what physically relocates
+// a legacy content/posts/<slug>.json file to content/pages/blog/<slug>.json
+// alongside this shape change - this function only ever transforms
+// content, never a path.
+function migrateV5ToV6(content) {
+    if ('name' in content) {
+        return { ...content, schemaVersion: 6 };
+    }
+    const title = typeof content.title === 'string' ? content.title : '';
+    return { ...content, schemaVersion: 6, name: title };
+}
 export const migrations = {
     1: migrateV1ToV2,
     2: migrateV2ToV3,
     3: migrateV3ToV4,
     4: migrateV4ToV5,
+    5: migrateV5ToV6,
 };

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

@@ -0,0 +1,10 @@
+export interface RenderCacheEntry {
+    html: string;
+    pageMtimeMs: number;
+    menusMtimeMs: number;
+}
+export interface RenderCache {
+    get(renderPath: string): RenderCacheEntry | undefined;
+    set(renderPath: string, entry: RenderCacheEntry): void;
+}
+export declare function createRenderCache(): RenderCache;

package/dist/renderer/render-cache.js

@@ -0,0 +1,11 @@
+export function createRenderCache() {
+    const map = new Map();
+    return {
+        get(renderPath) {
+            return map.get(renderPath);
+        },
+        set(renderPath, entry) {
+            map.set(renderPath, entry);
+        },
+    };
+}

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

@@ -26,3 +26,5 @@ export type RenderMode = 'public' | 'preview';
 export declare function parsePageContent(raw: string): PageContent;
 export declare function renderLoadedPage(page: PageContent, config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid): Promise<string>;
 export declare function renderPage(config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid, relativePath: string, mode: RenderMode): Promise<string>;
+export declare function getPageMtimeMs(config: SiteConfig, relativePath: string): number | null;
+export declare function getMenusMtimeMs(config: SiteConfig): number;

package/dist/renderer/render-page.js

@@ -1,4 +1,5 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
+import { listFilesRecursively } from "../services/fs-walk.js";
 import { loadMenus } from "../services/menus.js";
 import { sanitisePath } from "../services/path-safety.js";
 export class PageRenderError extends Error {
@@ -141,3 +142,41 @@ export async function renderPage(config, themeTemplates, layouts, engine, relati
     const page = loadPageForRender(config, relativePath, mode);
     return renderLoadedPage(page, config, themeTemplates, layouts, engine);
 }
+// For public.ts's render cache: the page's own current mtime, so a
+// cached render can be validated against real filesystem state rather
+// than needing every write path (publish/unpublish/delete/move/batch)
+// to remember to invalidate something. null means "not cacheable this
+// time" (the file vanished between resolveUrl confirming it exists and
+// this call - vanishingly unlikely, not a hard failure) rather than
+// throwing, since a cache-freshness check is never the place to
+// surface a real error - the ordinary render path below still will.
+export function getPageMtimeMs(config, relativePath) {
+    try {
+        return statSync(sanitisePath(config.contentRoot, relativePath)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// A menu edit affects every page's rendered nav, not just one page, so
+// the cache's freshness check needs one value covering all menus
+// together rather than per-page tracking. The max mtime across every
+// menu file serves that - any single menu changing bumps it. 0 (never
+// stale relative to anything) when there are no menus at all, matching
+// listFilesRecursively's own "missing directory returns []" behaviour.
+export function getMenusMtimeMs(config) {
+    let max = 0;
+    for (const relativePath of listFilesRecursively(config.menusRoot, config.menusRoot, '.json')) {
+        try {
+            const { mtimeMs } = statSync(sanitisePath(config.menusRoot, relativePath));
+            if (mtimeMs > max) {
+                max = mtimeMs;
+            }
+        }
+        catch {
+            // Vanished between the directory walk and this stat (e.g. a
+            // concurrent delete) - doesn't contribute, not fatal.
+        }
+    }
+    return max;
+}

package/dist/routes/admin-redirect.d.ts

@@ -0,0 +1,5 @@
+import type { FastifyPluginAsync } from 'fastify';
+export interface AdminRedirectRouteOptions {
+    adminBaseUrl: string;
+}
+export declare const adminRedirectRoutes: FastifyPluginAsync<AdminRedirectRouteOptions>;

package/dist/routes/admin-redirect.js

@@ -0,0 +1,26 @@
+import { NO_AUTH_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
+// Only ever registered by server.ts when serverConfig.adminBaseUrl is
+// actually set - that's what makes this genuinely opt-in, not a
+// reserved namespace like /media or /assets. A site that hasn't
+// configured this can still use "admin" as an ordinary page path,
+// same reasoning as GET /search.json over reserving all of /search.
+//
+// Redirects to adminBaseUrl with the requesting host appended as
+// ?site=, never a deep link with a site ID baked in - keeps this
+// agent completely decoupled from any particular admin app's own URL
+// scheme, so a self-hoster running a different admin frontend just
+// points adminBaseUrl at it. request.host (not request.hostname,
+// which strips the port - same reasoning sitemap.ts already
+// documents) so the admin side can match it directly against
+// new URL(registeredSiteUrl).host.
+//
+// Deliberately unauthenticated: this is a discovery aid an operator
+// (or anyone) can hit before they have a token, same class of
+// zero-credential route as GET /v1/capabilities and GET /search.json.
+export const adminRedirectRoutes = async (fastify, opts) => {
+    fastify.get('/admin', { config: NO_AUTH_ROUTE_RATE_LIMIT }, async (request, reply) => {
+        const target = new URL(opts.adminBaseUrl);
+        target.searchParams.set('site', request.host);
+        reply.code(302).header('location', target.toString()).send();
+    });
+};

package/dist/routes/capabilities.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CURRENT_SCHEMA_VERSION } from "../migrations/index.js";
-import { CAPABILITIES_RATE_LIMIT } from "../services/rate-limit-config.js";
+import { NO_AUTH_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
 import { DRIVER_NAME } from "../search/drivers/node-sqlite-driver.js";
 // The agent's own bundled package.json, not site data - the same
 // import.meta.dirname-relative pattern already established in
@@ -12,7 +12,7 @@ function readAgentVersion() {
     return packageJson.version ?? '0.0.0';
 }
 export const capabilitiesRoutes = async (fastify, opts) => {
-    fastify.get('/capabilities', { config: CAPABILITIES_RATE_LIMIT }, async () => ({
+    fastify.get('/capabilities', { config: NO_AUTH_ROUTE_RATE_LIMIT }, async () => ({
         agentVersion: readAgentVersion(),
         contentSchemaVersion: CURRENT_SCHEMA_VERSION,
         sqliteDriver: DRIVER_NAME,

package/dist/routes/media-public.js

@@ -25,9 +25,15 @@ async function handleMediaRequest(request, reply, config) {
     // <base href> fix), making genuinely cross-origin browser requests
     // for what looks like a same-origin path. Consistent with this
     // route already being deliberately unauthenticated and public.
+    //
+    // Cache-Control: immutable, a full year - safe unconditionally
+    // because filenames are content-addressed (a hash of the file's own
+    // bytes, see media/filename.ts): a given URL's content can never
+    // change, so there is no invalidation case to ever design for here.
     reply
         .header('X-Content-Type-Options', 'nosniff')
         .header('Access-Control-Allow-Origin', '*')
+        .header('Cache-Control', 'public, max-age=31536000, immutable')
         .type(mimeTypeFor(relativePath))
         .send(bytes);
 }

package/dist/routes/preview-revision.js

@@ -3,7 +3,6 @@ import { PageRenderError, parsePageContent, renderLoadedPage } from "../renderer
 import { GitShowError, readFileAtRevision } from "../services/git-history.js";
 import { isValidGitRef } from "../services/git.js";
 import { PathSafetyError } from "../services/path-safety.js";
-import { isBlogUrl, urlToPostPath } from "../services/post-urls.js";
 import { requireScope } from "../services/token-auth.js";
 import { urlToPagePath } from "../services/urls.js";
 // A dedicated top-level route rather than nesting under /preview/*
@@ -20,14 +19,11 @@ import { urlToPagePath } from "../services/urls.js";
 // readFileAtRevision resolves paths relative to config.siteRoot, not
 // config.contentRoot (confirmed by git-history.ts/git.test.ts's own
 // "content/pages/about.json" usage) - so unlike preview.ts's
-// toRenderPath/toPostsRenderPath (contentRoot-relative), the path
-// built here is prefixed with "content/".
+// toRenderPath (contentRoot-relative), the path built here is prefixed
+// with "content/".
 function toRevisionPath(pagesRelativePath) {
     return join('content', 'pages', pagesRelativePath);
 }
-function toPostsRevisionPath(postsRelativePath) {
-    return join('content', 'posts', postsRelativePath);
-}
 async function handlePreviewRevisionRequest(request, reply, config, themeTemplates, layouts, engine) {
     const { ref } = request.params;
     const url = `/${request.params['*']}`;
@@ -36,19 +32,7 @@ async function handlePreviewRevisionRequest(request, reply, config, themeTemplat
         return;
     }
     try {
-        const isPost = isBlogUrl(url);
-        let repoRelativePath;
-        if (isPost) {
-            const relativePath = urlToPostPath(url);
-            if (relativePath === null) {
-                reply.code(404).send({ statusCode: 404, error: 'Not Found', message: `No page at "${url}"` });
-                return;
-            }
-            repoRelativePath = toPostsRevisionPath(relativePath);
-        }
-        else {
-            repoRelativePath = toRevisionPath(urlToPagePath(url));
-        }
+        const repoRelativePath = toRevisionPath(urlToPagePath(url));
         const raw = readFileAtRevision(config, ref, repoRelativePath);
         const page = parsePageContent(raw.toString('utf-8'));
         const html = await renderLoadedPage(page, config, themeTemplates, layouts, engine);

package/dist/routes/preview.js

@@ -1,7 +1,6 @@
 import { join } from 'node:path';
 import { PageRenderError, renderPage } from "../renderer/render-page.js";
 import { PathSafetyError } from "../services/path-safety.js";
-import { isBlogUrl, urlToPostPath } from "../services/post-urls.js";
 import { requireScope } from "../services/token-auth.js";
 import { urlToPagePath } from "../services/urls.js";
 // Same pagesRoot/contentRoot seam as public.ts - see that file's
@@ -11,26 +10,9 @@ import { urlToPagePath } from "../services/urls.js";
 function toRenderPath(pagesRelativePath) {
     return join('pages', pagesRelativePath);
 }
-// Same seam as toRenderPath above, for posts.
-function toPostsRenderPath(postsRelativePath) {
-    return join('posts', postsRelativePath);
-}
 async function handlePreviewRequest(request, reply, config, themeTemplates, layouts, engine) {
     const url = `/${request.params['*']}`;
     try {
-        // /blog is a permanently reserved namespace, same as public.ts -
-        // no redirects.json fallback here either way (preview never
-        // consults it, per this file's own established comment above).
-        if (isBlogUrl(url)) {
-            const relativePath = urlToPostPath(url);
-            if (relativePath === null) {
-                reply.code(404).send({ statusCode: 404, error: 'Not Found', message: `No page at "${url}"` });
-                return;
-            }
-            const html = await renderPage(config, themeTemplates, layouts, engine, toPostsRenderPath(relativePath), 'preview');
-            reply.type('text/html; charset=utf-8').send(html);
-            return;
-        }
         const relativePath = urlToPagePath(url);
         const html = await renderPage(config, themeTemplates, layouts, engine, toRenderPath(relativePath), 'preview');
         reply.type('text/html; charset=utf-8').send(html);

package/dist/routes/public.d.ts

@@ -1,11 +1,13 @@
 import type { FastifyPluginAsync } from 'fastify';
 import type { Liquid } from 'liquidjs';
 import type { SiteConfig } from '../config.ts';
+import type { RenderCache } from '../renderer/render-cache.ts';
 import type { ThemeTemplates } from '../renderer/theme-templates.ts';
 export interface PublicRouteOptions {
     config: SiteConfig;
     themeTemplates: ThemeTemplates;
     layouts: Record<string, string>;
     engine: Liquid;
+    renderCache: RenderCache;
 }
 export declare const publicRoutes: FastifyPluginAsync<PublicRouteOptions>;