@minamocms/framework 0.0.0-stage → 0.10.2

package/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Changelog
+
+All notable changes to this package are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/). Nothing before `0.2.0` was tracked in this file - see git history for anything earlier.
+
+## [Unreleased]
+
+## [0.10.2] - 2026-11-04
+
+### Fixed
+
+- **A site with no `media/` folder serves and stores media normally.** `media/` is git-ignored, so a site deployed by a host that builds from its repository (Railway, for one) starts without it. Until now every request for a media file there answered 500 instead of 404, and the first upload failed the same way. A missing folder now reads as an empty one, and the first upload creates it.
+
+## [0.10.1] - 2026-10-15
+
+### Changed
+
+- **Published as `@minamocms/framework`**, the first release under the new name, with everything listed under 0.10.0. 0.10.0 was tagged but never published: npm refused the unscoped name `minamo` as too like existing packages' names. Start a new site with `npx -p @minamocms/framework create-site my-site`.
+- **Moving a site from `@o-a/cms-agent`:** from `vhost/`, run `npm run upgrade`. On 0.9.3 that moves the site over to `@minamocms/framework`, switching its dependency and `server.js` to the new name; on 0.6.0 to 0.9.2 it first upgrades to 0.9.3, so run it a second time. On 0.5.x, run `npm install @o-a/cms-agent@0.9.3 --save-exact` and `npx upgrade-site --finish` first. Then test and `npm run push --cms` as for any upgrade.
+
+## [0.10.0] - 2026-10-15 (not published)
+
+### Changed
+
+- **Renamed to Minamo.** The CMS is now called Minamo, and this package replaces `@o-a/cms-agent`. New sites depend on it and their `vhost/server.js` imports it. The licence is unchanged (FSL-1.1-ALv2) and now named in `package.json`.
+- **A redeploy also refreshes `vhost/server.js`** on the live volume, alongside the installed CMS, since it imports the CMS by name. Nothing else on the volume changes.
+- **New sites' starter content is Minamo's**, in place of Granite CMS: its copy, logo, page titles and footer, and the comparison section's `minamo`/`minamoLabel` settings (were `granite`/`graniteLabel`; existing sites' themes are their own and unchanged). Its sample commands are real ones, and its GitHub link is the framework's repository. A live site that isn't a CMS site is now reported as "not a Minamo site".
+- Commits the CMS makes itself (checkpoints, and a recovered `.git` on first boot) are authored as `Minamo` in place of `CMS Agent`.
+
+## [0.9.3] - 2026-10-15
+
+### Changed
+
+- **`npm run upgrade` looks for the CMS as `@minamocms/framework`.** npm refused the unscoped name `minamo`, so 0.9.2's handover never finds anything to move to. From 0.9.3, once `@minamocms/framework` has a newer version, the upgrade moves the site over to it.
+
+## [0.9.2] - 2026-10-15
+
+### Changed
+
+- **The CMS is now called Minamo, and from 0.10.0 it is published as `minamo`** in place of `@o-a/cms-agent`. `npm run upgrade` looks for it under the new name: once `minamo` has a newer version, the upgrade moves the site over, swapping the dependency in `vhost/package.json`, then finishes as any upgrade does. Until then it upgrades exactly as before.
+
+## [0.9.1] - 2026-10-01
+
+### Added
+
+- **`GET /v1/deleted-pages`** now also returns each page's `name` (as the admin's page tree shows it), alongside its `title`.
+
+## [0.9.0] - 2026-10-01
+
+### Added
+
+- **`GET /v1/deleted-pages`** lists pages deleted in the last 90 days that aren't back, newest first, with who deleted them and when, and the version to restore each from with `POST /v1/git/revert`. Read from git's own record of deletions; a moved page isn't a deletion, and a page that exists again (live or as a draft) isn't listed.
+
+## [0.8.0] - 2026-09-29
+
+### Added
+
+- **Moving a page keeps links to it working.** Every internal link to the page, or to a page under it, is rewritten to the new address in live pages, drafts, menus and the site settings, in the same commit as the move (whole-value paths such as link fields and menu items, and `href`s in rich text; `?query`, `#fragment` and a trailing slash are kept). The 301 redirect is still added for links from elsewhere. `GET /v1/links?to=/a-page` lists what links to a page, for the admin to show before a delete.
+- **Link fields suggest the site's pages.** `"format": "url"` is the documented name for a link field (Shopify's word); in the admin it suggests the site's pages by title or path, stores the page's path, still takes any external, `mailto:`, `tel:` or `#anchor` address, and says which page a path reaches or that none is there. The menu item editor and the rich-text link dialog use the same field. `"format": "uri"`, the name before, still works, and `npm run check` now lists it under Suggestions, which never fail the check. Neither is enforced as a strict URI, so a site path such as `/about` is always accepted, and neither prints an "unknown format" warning.
+- **Field groups.** A `"group"` on a field in a section, block or site settings schema puts it under a collapsible heading in the admin, with others sharing that group. A plain annotation like `"title"`: names and templates are unchanged. New sites group their settings into Social links and Typography.
+
+### Changed
+
+- **AGENTS.md and the guides catch up.** New sites' AGENTS.md documents the `url` link field, field groups (with advice on grouping well), `theme/config/`, the rule that internal links are paths, `npm run check`'s Suggestions, and the current pull/push model (the old text said push never touches the theme). Favicons are now documented as belonging in `theme/assets/`, linked from the layout; `theme/root/` is optional and only for files that must sit at an exact root path. The content guide's `schemaVersion` is corrected to 7.
+
+### Fixed
+
+- **Moving a page takes its draft with it.** The draft used to stay at the old address, where it became a draft-only page. A move is also refused when a draft-only page already sits at the destination.
+- **A site with no `content/drafts` folder can preview and save drafts.** Git keeps no empty folders, so a site cloned or deployed from git with no drafts has none, and every preview and draft save failed with a 500. The folder is now made at start-up.
+- **`npm run push` no longer waits in vain on a CMS upgrade the host can't build.** A deploy builds the version `vhost/package.json` names, so if that disagrees with the version installed here (seen on a real site: package.json put back to the old version after an upgrade), the live site stays on the old version and push used to wait ten minutes for it. Push now stops before deploying and says how to fix `package.json`.
+- **Site settings move to `theme/config/site_settings.json`.** Shopify's VS Code extension checks any `config/settings_schema.json` against Shopify's own format and marks Granite's as wrong (on one real site, the file was then rewritten into Shopify's form and stopped working). The form is unchanged: JSON Schema, like a section's `{% schema %}`. A `settings_schema.json` in that form is still read, with a warning to rename it; one in Shopify's form is left alone.
+
+## [0.7.1] - 2026-09-29
+
+### Added
+
+- **Preview unsaved site settings.** `GET /v1/preview/*` takes `?settings=<JSON>`: site settings changed in the admin but not saved, rendered in place of the saved ones and written nowhere. Values the theme's schema rejects are ignored and the saved settings shown. The admin's Settings screen uses it to preview changes as they are made.
+
+## [0.7.0] - 2026-09-28
+
+### Added
+
+- **Site settings.** A theme defines site-wide settings in `theme/config/settings_schema.json` - social links, a font choice, anything a whole site shares - in the same JSON Schema form as a section's `{% schema %}`. Every layout, section, block and snippet reads them as `{{ settings.<name> }}`, with the theme's defaults filling anything not yet saved. The values are content, in `content/settings.json`: `GET /v1/settings` returns the schema, the saved values and what templates see; `PUT /v1/settings` (If-Match) validates, commits and puts them live at once, like a menu. Saving refreshes every cached page. New sites' footer links and body font are site settings. `npm run pull` and `npm run push` carry site settings with content, protected the same way (settings changed on the live site since the pull stop a push; a copy with no `settings.json` never clears the live ones). The admin has a matching Settings screen.
+
+## [0.6.1] - 2026-09-28
+
+### Changed
+
+- **`npm run push` works on a copy that has never pulled** - a site built locally and deployed, for example. The live site as it is now stands in for the pull: everything that differs locally is listed as a new or updated page, theme file or redirect, with a warning to check it, and nothing is deleted from the live site (a live page missing locally may be one an editor made). Afterwards only what the copy and the live site agree on is recorded, so live pages the copy never had are left alone by later pushes too. A CMS upgrade on its own no longer needs a pull. With no record, push asks for the site's address.
+
+## [0.6.0] - 2026-09-28
+
+### Added
+
+- **`npm run pull` and `npm run push` handle the theme too.** Both now ask what to include, with checkboxes for **Content** and **Theme** (`--content` and `--theme` choose without asking); push shows how many changes each has. Theme sync uses three new routes, all needing the `theme` token scope: `GET /v1/theme/files`, `GET /v1/theme/files/*` and `POST /v1/theme/push`. A theme push is protected like content (a file changed on the live site since the pull stops it), is refused if a Liquid template can't be parsed, commits once, and takes effect immediately with no restart. The theme is pushed before content, so pages using a new section type arrive after the theme that defines it.
+
+- **`npm run upgrade` upgrades the CMS on your computer** (`upgrade-site`, a new bin), for testing before `npm run push` puts it live. It shows the new version's changelog entries, asks, installs it, and then hands over to the new version, which puts back its own files in `vhost/` (`Dockerfile`, `docker-entrypoint.sh`, `server.js`, `.dockerignore`, and its scripts in `package.json`, keeping the developer's own), updates content to the new format, and runs the site check. Nothing is committed. `CHANGELOG.md` now ships in the package so the upgrade can show it. Sites on 0.5.x run their first upgrade as `npm install @o-a/cms-agent@0.6.0 --save-exact` then `npx upgrade-site --finish`.
+
+- **`npm run push` can upgrade the live site's CMS.** When the CMS here is newer than the live site's, push offers a third choice, **CMS upgrade** (`--cms` for scripts). It deploys, after the site's address is typed, using the command in `vhost/deploy.json` if there is one (`{ "command": "git push" }`, or any command that deploys the site), otherwise Railway (`railway up`) or Fly.io (`fly deploy`) when the site is set up for them, otherwise it pauses while you deploy by hand. It then waits for the live site to report the new version and for its home page to load, and only then plans and sends content and theme, with their own list and confirmation. A live site on an older content format only accepts content and theme together with the upgrade.
+
+### Fixed
+
+- **A pull rewrote `redirects.json` even when the live redirects were the same,** which showed as a change (only the file's formatting differed). It's now left alone unless the redirects differ.
+- **Nine of the scaffold's starter pages had no `name`,** which the page format has required since content schema 5. They rendered, because the display falls back to the title, but updating their content format validates them, so every new site's first upgrade would have failed on its own starter pages.
+
+### Changed
+
+- **A running site reloads its theme without a restart** after a theme push. Routes now read the theme from one shared `ThemeState` rather than a copy taken at start-up, and cached pages are keyed on the theme too.
+- **The content-format update can leave its changes uncommitted** (`runMigrations(..., { commit: false })`), which `npm run upgrade` uses.
+- **The pull record is kept per part** (content, theme), so either can be pulled alone. Records written by 0.5.5 are still read, as the content part.
+
+## [0.5.5] - 2026-09-28
+
+### Added
+
+- **`npm run push` sends local content changes back to the live site** (`push-site`, a new bin). It compares each page and menu as last pulled, as it is locally, and as it is live now, and pushes only local changes: a page changed on the live site since the pull is never overwritten (it stops the push and is listed as a conflict), and a live page is only deleted if it was deleted locally. Missing images the pushed pages use are uploaded under the same names. It lists every change, warns that it overwrites the live site, and asks for the site's address to be typed; `--dry-run` only lists. Page and menu changes go as one batch, one commit, or not at all. `npm run pull` now records what it pulled, which push needs. Existing sites add `"push": "push-site"` to `vhost/package.json`'s scripts.
+
+### Changed
+
+- **`npm run pull` asks for what it needs**: the live site's address when none is given, then the token when neither `CMS_TOKEN` nor `--token` is, without showing what is typed or pasted, so the token never lands in shell history. An address can be typed as `my-site.example` (taken as `https://`) or `localhost:3600` (`http://`), and is checked before the token is asked for. Piped input still works (address, then token, one per line), so scripts are unaffected.
+
+## [0.5.4] - 2026-09-28
+
+### Added
+
+- **`npm run pull` copies a running site's content and media into a local one** (`pull-site`, a new bin): `CMS_TOKEN=<token> npm run pull -- <url>` from `vhost/`. Pages, menus, drafts and redirects are mirrored and missing media downloaded, through the `/v1/` API, so it works wherever the site is hosted. The theme is never touched and nothing is committed. It refuses while `content/` has uncommitted changes (`--force` overrides), refuses a live site on a newer content schema, and checks every server-supplied path before it becomes a local file. Existing sites add `"pull": "pull-site"` to `vhost/package.json`'s scripts.
+
+## [0.5.3] - 2026-09-24
+
+### Added
+
+- **`npm run stop` stops a site from any terminal**, not only the one it was started in (`stop-site`, a new bin). The server records the process to stop in `vhost/data/server.pid`; under `npm run dev` that is the watcher, so both it and the server end. It sends `SIGTERM` (the same graceful shutdown as Ctrl+C) and only to a process still answering as a site on the recorded port. Starting a site that is already running now says so instead of reporting a bare port conflict. Existing sites add `"stop": "stop-site"` to `vhost/package.json`'s scripts.
+
+## [0.5.2] - 2026-09-24
+
+### Added
+
+- **A menu can have a display name**, separate from its handle: an optional, non-empty `"name"` in `content/menus/<handle>.json` (content schema 7, with an identity migration - no existing menu needs a value). Layouts can print it as `{{ menus.<handle>.name }}`, for example as a footer column heading. Renaming a menu this way never affects a layout.
+- **A menu's handle can be changed** with `POST /v1/menus/rename` (`{ from, to, message, author }`, If-Match): one commit through the write queue, refusing a handle that is taken, a stale ETag, a missing menu, and anything but letters, numbers, hyphens and underscores. It returns the theme files still using the old handle, since every one of them now renders an empty menu until updated.
+- **`GET /v1/menus/references?handle=<handle>`** lists the theme files that use a handle (`menus.<handle>` or `menus['<handle>']`, as a whole name only), so a client can warn before a rename or delete.
+
+### Fixed
+
+- **Redeploying never upgraded the agent on an existing volume.** The scaffolded `docker-entrypoint.sh` copied the image onto `/site` on first boot only, so the installed `@o-a/cms-agent` on a persistent volume was never replaced, and the only way to upgrade was destroying the volume and every live edit with it. Every later boot now refreshes `vhost/package.json`, `package-lock.json` and `node_modules` from the image and touches nothing else. Existing sites need this script copied into their own `vhost/` once.
+- **A renamed or deleted menu left cached pages showing their old navigation.** The render cache's menu freshness check used the newest menu file's modification time; a rename keeps that time and a delete removes a file, so when the changed menu was not the most recently edited one, nothing moved. The menus directory's own modification time now counts too.
+
+## [0.5.1] - 2026-09-19
+
+### Fixed
+
+- **`seed-media` could not be run the way every document said to run it.** `npx seed-media . <file>` from the site directory never worked: there is no `package.json` or `node_modules` at the site root - the CMS is installed under `vhost/` - so npx resolves nothing locally, asks the public registry for a package called "seed-media" and fails with a 404, *while still exiting 0*. A generated site consequently put all 28 of its images in `theme/root/images/`, because the one documented route into `media/` was a dead end that reported no error. The generated `vhost/package.json` now exposes a `seed-media` script, exactly as it already did for `check`, and both documents give the working form: `npm run seed-media -- .. <file>` from `vhost/`.
+- **`npm run check` now reports a content image or video served from `theme/root/` or `theme/assets/`** as a `misplaced-media` finding. This had no other way of being noticed: the file exists, so the page renders perfectly, and the only symptom is that the media library never shows the image and an editor can never replace it. The rule keys off the same extension list the upload route accepts, so the two cannot drift, and only examines `src`/`srcset`/`poster` - an `href` is a link or a favicon, and `.svg` is absent from that list, so a site's own icon and an inline logo are not mistaken for misplaced photographs.
+- **A `mailto:` link was reported as a missing file**, because the text after the "@" contains a dot and so looked like a filename. One real site produced 39 such findings and not a single true one - output that noisy trains whoever reads it to ignore the check entirely. Any non-http scheme (`mailto:`, `tel:`, and anything future) is now skipped.
+- **A video's `poster` was never checked at all.** It is a real content image reference and is now scanned alongside `src` and `srcset`.
+- **A site with no `media/`, `theme/assets/` or `theme/root/` directory crashed the check** with a raw `ENOENT` instead of reporting the missing file, because path sanitisation resolves its root argument unconditionally. The guard fell over on exactly the sites most likely to hold a broken reference. A root directory that does not exist now means the file does not exist, which is an ordinary finding.
+
+## [0.5.0] - 2026-09-18
+
+### Added
+
+- **Every scaffolded site now ships `theme/snippets/responsive-media.liquid`**, and the scaffold uses it: `hero` gains an image setting and `cta-banner` a short silent background loop. It renders a `format: "image"` or `format: "video"` setting and marks the result as a drag-and-drop target, so an editor can drag a file from the admin's media library straight onto the picture in the live preview. Until now the scaffold shipped no image snippet at all, and not one of its sections or blocks even had an image setting, so a theme author had nothing to copy.
+  - It deliberately builds no `srcset`. Uploaded files are named by a hash of their own bytes, so a resized variant's name is not derivable from the original's URL - hand-built variant URLs point at files that do not exist, producing a page that looks perfect except at one breakpoint, which is precisely the failure `npm run check` exists to catch.
+  - An unset image renders nothing at all rather than a placeholder. A theme cannot tell whether it is rendering for the admin preview or for the public site, so an editor-only affordance would show to real visitors.
+  - A video slot emits `data-cms-media`/`data-cms-media-kind` but never `data-cms-image`. An admin predating video support understands only the older attribute and would write an image-shaped value (`{ url, focalX, focalY }`) straight over the field's own `{ url, poster }` - better it ignores the slot than corrupts it.
+
+### Fixed
+
+- **The attribute that makes an image editable was documented nowhere.** Drag-and-drop finds a drop target purely by looking for `data-cms-image` in the previewed page, and no document in this project mentioned it. A real generated site consequently shipped with every image un-editable: the theme rendered perfectly, images simply were not droppable, and nothing about the page looked wrong. `AGENTS.md` and `guide-theme-authoring.md` now both spell out the contract, and do so at each point an image actually comes up rather than in one section near the end.
+- **`AGENTS.md` said an image "is just a plain string setting"**, treating `format: "image"` as the exception for when a focal point is wanted. That is backwards: a drop writes an object, so a string-declared field fails validation outright. The object form is now the documented default, and the `seed-media` example that still produced a plain string has been corrected to match.
+- **Both guides told authors to hand-write the markup** - `{{ section.settings.<field>.url }}` for an image, a bare `<video>` for a loop. Both now point at the snippet, including the format table rows, the worked example a section is copied from, and the snippets section itself.
+
+## [0.4.0] - 2026-09-17
+
+### Added
+
+- **The media library now accepts and serves video** (`.mp4` and `.webm`), for the short silent loops that stand in for a hero image rather than long-form video. Same 10MB cap as any other upload - anything longer belongs on YouTube or Vimeo, embedded. `.svg` stays rejected (it is never sanitised, so it is a stored-XSS path when loaded as a top-level navigation), and `.mov` with it, since QuickTime frequently will not play in Chrome or Firefox at all.
+- **Real HTTP Range support on `/media/*`**: `Accept-Ranges: bytes` on every response, a `206` with `Content-Range` for a satisfiable range, and a `416` for one starting past the end. This is not a bandwidth optimisation. Safari and iOS open a `<video>` with `Range: bytes=0-1` and refuse to play at all without a `206` in reply, so hosted video simply did not work before this. A suffix range (`bytes=-500`) correctly means the *last* 500 bytes rather than the first, an end past the last byte is clamped rather than rejected (browsers routinely overshoot), and a multi-range request falls back to sending the whole file rather than answering with an incorrect multipart body.
+- **`format: "video"`** is now a recognised UI hint on an `"type": "object"` setting, storing `{ url, poster }`. The admin renders a video picker with a poster picker for it, in place of the raw-JSON fallback an unrecognised object shape otherwise gets.
+
+### Documentation
+
+- **The scaffold's `AGENTS.md` now says where images actually go.** An agent building a real site from it put every image in the site root, twice running. `assets/` is now described as design assets only, the workflow names the `seed-media` step and `npm run check` explicitly, and the Images section leads with where images live. It also states plainly that one image is one file and one URL, and that the CMS does not generate resized variants - previously left to inference.
+- **`format: "video"` is documented in both `AGENTS.md` and `guide-theme-authoring.md`.** Both present their format table as an exhaustive, closed set ("never invent a new setting field shape"), so leaving the new value out did not merely omit it - it actively told theme authors the field did not exist.
+
+## [0.3.1] - 2026-09-17
+
+### Fixed
+
+- **The scaffold's own `AGENTS.md` now explains what a page's `type` does.** It was described only as "free-form", with nothing saying that a template's `type` is inherited by every page created from it, or that the value is what `GET /search.json?pageType=...` filters on. An Article template left at `"type": "page"` therefore produces articles no blog index can find - and because it still validates and previews perfectly, nothing signals the mistake. Documentation only; no code change.
+
+## [0.3.0] - 2026-09-17
+
+### Added
+
+- **`POST /v1/publish-page/:path`**: sets `published: true` on a live page in place and commits - the exact twin of the existing `POST /v1/unpublish/:path`. Deliberately separate from `POST /v1/publish`, which promotes drafts: a page that is live but unpublished has no draft to promote, so publish could not reach it at all, and promoting a draft would push every pending edit live alongside the flag. Like unpublish, it never touches a draft, so a page with unpublished edits keeps them.
+
+## [0.2.2] - 2026-09-09
+
+Three gaps found by having a different AI agent build a real demo site from `AGENTS.md` and report back what it wished were different.
+
+### Fixed
+
+- **The search index now keeps itself current automatically.** Previously `GET /search.json` stayed empty forever on a fresh site and stale forever after a real edit - nothing ever rebuilt it except a caller manually hitting `POST /v1/search/rebuild`. It now rebuilds in the background after every publish/unpublish/delete/move/batch write, and once at boot if no index exists yet (the index is never git-tracked, so a fresh clone starts with none). Fire-and-forget in both cases - a slow or failed reindex never blocks or fails the write that triggered it.
+
+### Added
+
+- **Sections and blocks can now render `page.author`, `page.publishDate`, and `page.tags`** - the same built-in envelope a layout already got (previously just `page.title`), widened and made available to section/block templates too, not just layouts. Closes a real gap: these fields were already indexed for search but had no way to actually appear on the rendered page without duplicating the value into a settings field.
+- **A broken theme component now prints a boot warning instead of vanishing silently.** A section/block with no `{% schema %}` block, invalid JSON in it, or a required property with no valid default was already excluded from the theme (unchanged, still never a boot failure) - it just did so with zero output anywhere. `loadThemeSchemas` now names each excluded type and the specific reason.
+
+## [0.2.1] - 2026-09-09
+
+### Added
+
+- **A new `AGENTS.md` in every scaffolded site**, onboarding an AI coding agent to this specific CMS's conventions: theme folder structure, the section/block `{% schema %}` pattern with worked examples, the `format` field-hint table, the current content JSON model, image handling, `GET /search.json`, and the hard constraints. Self-contained - no external link, since generated content shouldn't depend on a live docs site being reachable.
+
+## [0.2.0] - 2026-09-09
+
+### Breaking changes
+
+- **The distinct "post" content type is gone.** `author`, `publishDate`, and `tags` are now optional fields any page may carry - there is no separate schema, and `/blog` is no longer a reserved URL namespace (a page can live at `/blog/<slug>` the same way it can live anywhere else, by nesting it under a `blog` page). A new `schemaVersion` 6 migration relocates any existing `content/posts/<slug>.json` file to `content/pages/blog/<slug>.json`, preserving its old URL, and backfills a `name` field if it doesn't already have one.
+  - **Known gap**: there's no automatic migration trigger at boot, and no CLI command runs one either (`runMigrations` exists in `src/services/migration-runner.ts` but nothing currently calls it outside tests). No adopter currently has content under `content/posts/`, so this doesn't affect anyone today - but the migration path itself needs a real trigger mechanism before it would.
+- **`GET /v1/search` has moved to `GET /search.json`, unprefixed.** The old path is removed outright, not kept as an alias. Update any theme code calling it directly. The endpoint's behaviour (full-text search, structured filters, sort, pagination) is unchanged - only the path moved, out from under the versioned `/v1/` admin/integration surface to reflect that it's a stable, public, front-end-facing contract instead.
+- **Uploaded media filenames changed shape**: `<slug>-<hash>.<ext>` instead of `<hash>-<slug>.<ext>` for new uploads. Still the same content-addressed name (a sha256 hash of the file's own bytes); only the order changed, so the readable part sorts first in a directory listing or URL. Existing uploaded files are untouched - this only affects new uploads going forward.
+
+### Added
+
+- **`GET /search.json`**: one unified, genuinely public query endpoint - no bearer token required, full-text search (`q`), structured filters (`filter=field:op:value`, repeatable, AND'd together), sort, and pagination in a single response. Replaces an earlier, narrower `GET /v1/search/fields` that queried one field at a time.
+- **A new `"api": true` JSON Schema keyword** for section/block settings, exposing that field's value through the search index for structured filtering (e.g. `filter=price:lt:50`) - independent of full-text search.
+- **`GET /admin`**: a configurable, opt-in redirect to your admin instance. Set `adminBaseUrl` in `site.config.json` and visiting `yoursite.com/admin` redirects there with `?site=<host>` appended, so the admin can resolve straight to this site's own dashboard. Leave it unset and the route doesn't exist at all - a site can still use "admin" as an ordinary page path.
+- **An in-process render cache for public pages.** Previously every request re-read and re-rendered a page from scratch; rendered HTML is now cached and validated against real file mtimes (the page's own file, plus every menu file, since menus render into every page's nav), so a repeat request for an unchanged page skips rendering entirely.
+- **`Cache-Control: public, max-age=31536000, immutable`** on every media response - safe unconditionally, since filenames are content-addressed and a given URL's bytes can never change.
+
+### Fixed
+
+- **`engines.node` was wrong and is now `>=22.16.0`, not `>=22.6.0`.** The old floor was never actually verified against real Node builds: `node:sqlite` needs `--experimental-sqlite` below Node 22.13.0 (never passed anywhere in this package), and FTS5 support itself - the search index's own full-text engine - isn't compiled in at all until Node 22.16.0. Every version from the old floor up to 22.15.x would hard-crash the moment a search index rebuild ran. Confirmed by downloading and testing real Node builds directly, not assumed from release notes.
+- **A search index rebuild no longer blocks the entire server.** `rebuildIndexJob` was `async` but had no real `await` in its body, so on a busy site a rebuild froze every other request (not just search) for its whole duration. It now yields to the event loop periodically during a rebuild.
+- **A search index rebuild is now atomic.** Previously the index file was deleted then recreated in place, a real window where a concurrent read could see a missing file or one with no tables yet. It's now built into a temp file and swapped in via an atomic rename.
+
+### Documentation
+
+- Caught up `guide-theme-authoring.md` (then named `theme-authoring-guide.md`) on several already-shipped theme field conventions that were undocumented or stale: `format: "richtext"`, `format: "image"` (with focal-point support), `format: "color"`'s `swatches` keyword, the range field format, the consolidated toggle/select field formats.

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Scott Gray
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# Minamo framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Own your content, forever.**
+
+The Minamo framework is a self-hosted web framework for content sites,
+built on Liquid templates. Every page is a plain JSON file. Every publish
+is a real git commit. There is no database standing between you and your
+own content, and there never will be. Editors manage a site through the
+Minamo CMS, or any tool that speaks its versioned API.
+
+If you've ever had a headless CMS raise its prices, change its export
+format, or go down and take your site's editing with it - this is built to
+make that structurally impossible. Your site and its content stay yours:
+moving away is `git clone`. That's the whole migration story.
+
+## Why this is different
+
+Most self-hosted, code-first CMS options give you an API and a database.
+Most git-based CMS tools give you markdown files and a static-site rebuild.
+The Minamo framework is the combination neither of those is:
+
+- **Git-native content.** Pages, posts, menus, and redirects are JSON files
+  in your own git repository. No database is ever the source of truth.
+  History, diffs, and rollback are real git operations, not a bolted-on
+  revisions table.
+- **A real page builder, not just files.** Themes define reusable, schema
+  validated **sections** and **blocks** - a Shopify-style content model - so
+  a non-technical editor arranges and fills in components a developer
+  already built, instead of hand-editing markdown or JSON.
+- **A real versioned HTTP API.** `/v1/...` is the only thing a site exposes.
+  Drafts, publishing, optimistic concurrency (ETags + `If-Match`), batch
+  writes, and git history are all first-class API operations - what the
+  Minamo admin (or your own tooling) talks to, never the filesystem
+  directly.
+
+## Two audiences, one framework
+
+- **Developers** build the theme: Liquid layouts, sections, and blocks,
+  each with an embedded JSON Schema for its settings. Start with
+  [`docs/guide-theme-authoring.md`](docs/guide-theme-authoring.md).
+- **Content editors / marketing managers** never touch this repository at
+  all - they work entirely through the Minamo admin (see
+  [Editing with Minamo](#editing-with-minamo) below), browsing pages,
+  editing sections, and publishing through the API this package exposes.
+  The content model itself is documented in
+  [`docs/guide-content-authoring.md`](docs/guide-content-authoring.md).
+
+## Quick start
+
+```
+npx -p @minamocms/framework create-site my-site
+cd my-site/vhost
+npm install
+npm start
+```
+
+Visit `http://localhost:3000`. `create-site` prints a real access token to
+your terminal when it scaffolds the site - that's what the Minamo admin
+(or a plain `curl`) uses to authenticate against the site's
+`/v1/` API. Lost it, or need a second one? See the `mint-token` command in
+the same docs page.
+
+## Project layout
+
+A scaffolded site is a thin, four-folder scaffold - everything a content
+editor touches lives under `content/`, everything a developer touches lives
+under `theme/`, uploaded media lives under `media/` (never git-tracked),
+and the site's own serving configuration lives under `vhost/`:
+
+```
+my-site/
+  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
+```
+
+This repository (the framework itself, the `@minamocms/framework` package) is developed
+separately and installed as a versioned dependency - see [`docs/cms-build-plan.md`](docs/cms-build-plan.md)
+for the full architecture and the reasoning behind it.
+
+## Tech stack
+
+Node.js 22+ and TypeScript, compiled to plain JavaScript for distribution.
+Fastify, LiquidJS (sandboxed - no dynamically registered tags or filters,
+ever), SQLite via `node:sqlite` for a fully disposable, rebuildable search
+index, and the real `git` binary for every content mutation. Dependencies
+are kept deliberately minimal - this ships as a package other people
+install.
+
+## Documentation
+
+- [`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
+
+Friendlier, browsable documentation, covering both this framework and the
+Minamo admin, is at [docs.minamocms.com](https://docs.minamocms.com).
+
+## Editing with Minamo
+
+The framework has no user interface of its own by design - it's an API.
+Day-to-day editing happens in the Minamo admin, a hosted service that
+manages any number of independently hosted sites. Your sites stay yours:
+they run wherever you host them, their content is in your own git
+repository, and the admin reaches them only through the versioned `/v1/`
+API above, with the site's own token. Anything else that speaks that API
+works too.
+
+## Upgrading from `@o-a/cms-agent`
+
+Up to 0.9.x this package was published as `@o-a/cms-agent` (and the
+project was called Granite CMS). From `vhost/`, run `npm run upgrade`: on
+0.9.3 it moves the site over to `@minamocms/framework`, and on 0.6.0 to 0.9.2 it first
+reaches 0.9.3, so run it a second time. On 0.5.x, run
+`npm install @o-a/cms-agent@0.9.3 --save-exact` and
+`npx upgrade-site --finish` first.
+
+## Project status
+
+This is young, real software - it runs a genuine production site today,
+not just a demo, but it has one tenant so far, not thousands. Expect rough
+edges, expect things to improve in the open rather than arrive finished,
+and please open an issue if something doesn't work the way this README
+says it should.
+
+## License
+
+[Functional Source License, Version 1.1, Apache 2.0 Future Grant](LICENSE)
+(FSL-1.1-ALv2). In short: free to use, modify, and self-host for anything
+except offering it as a competing hosted service. Every version converts
+automatically to the fully permissive Apache License 2.0 two years after
+its own release - this is a head start, not a permanent restriction.

package/dist/boot.d.ts

@@ -0,0 +1,19 @@
+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';
+import type { PageTemplate } from './services/theme-page-templates.ts';
+import { ThemeState } from './theme-state.ts';
+export interface BootedSite {
+    config: SiteConfig;
+    themeSchemas: ThemeSchemas;
+    themeTemplates: ThemeTemplates;
+    layouts: Record<string, string>;
+    pageTemplates: PageTemplate[];
+    engine: Liquid;
+    theme: ThemeState;
+    renderCache: RenderCache;
+}
+export declare function bootSite(siteRoot: string, options?: StartupCheckOptions): BootedSite;

package/dist/boot.js

@@ -0,0 +1,22 @@
+import { loadSiteConfig } from "./config.js";
+import { createRenderCache } from "./renderer/render-cache.js";
+import { runStartupChecks } from "./services/startup-checks.js";
+import { ensureDraftsRoot } from "./services/drafts.js";
+import { loadTheme, ThemeState } from "./theme-state.js";
+export function bootSite(siteRoot, options) {
+    runStartupChecks(siteRoot, options);
+    const config = loadSiteConfig(siteRoot);
+    ensureDraftsRoot(config);
+    const initial = loadTheme(config);
+    const renderCache = createRenderCache();
+    return {
+        config,
+        themeSchemas: initial.themeSchemas,
+        themeTemplates: initial.themeTemplates,
+        layouts: initial.layouts,
+        pageTemplates: initial.pageTemplates,
+        engine: initial.engine,
+        theme: new ThemeState(config, initial),
+        renderCache,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export declare const VHOST_DIR_NAME = "vhost";
+export interface SiteConfig {
+    siteRoot: string;
+    contentRoot: string;
+    draftsRoot: string;
+    themeRoot: string;
+    assetsRoot: string;
+    rootMirrorRoot: string;
+    templatesRoot: string;
+    pagesRoot: string;
+    menusRoot: string;
+    redirectsPath: string;
+    vhostRoot: string;
+    dataRoot: string;
+    searchIndexPath: string;
+    mediaRoot: string;
+}
+export declare function loadSiteConfig(siteRoot: string): SiteConfig;

package/dist/config.js

@@ -0,0 +1,44 @@
+import { isAbsolute, join, resolve } from 'node:path';
+// Single source of truth for the runtime/serving folder's name, reused
+// by server-config.ts (site.config.json lives inside it) rather than a
+// second hardcoded literal. A real vhost, in hosting terms (Apache/
+// nginx/CyberPanel): the per-site serving configuration, not a
+// multi-tenancy concept - this folder holds exactly that (package.json,
+// server.js, site.config.json's access-control/serving parameters).
+export const VHOST_DIR_NAME = 'vhost';
+// Pure path derivation, no fs calls. siteRoot must be supplied by the
+// caller (agent configuration) and must already be absolute: the agent
+// never assumes it lives inside the site repo, and never falls back to
+// resolving against its own module location or process.cwd().
+export function loadSiteConfig(siteRoot) {
+    if (!isAbsolute(siteRoot)) {
+        throw new Error(`siteRoot must be an absolute path, got "${siteRoot}"`);
+    }
+    const normalisedRoot = resolve(siteRoot);
+    const contentRoot = join(normalisedRoot, 'content');
+    const themeRoot = join(normalisedRoot, 'theme');
+    const vhostRoot = join(normalisedRoot, VHOST_DIR_NAME);
+    const dataRoot = join(vhostRoot, 'data');
+    return {
+        siteRoot: normalisedRoot,
+        contentRoot,
+        // Nested inside contentRoot (content/drafts), not a sibling of it -
+        // marketing-manager-managed content lives entirely under content/.
+        // See content-read.ts/migration-runner.ts for the inclusion-based
+        // walk fix this requires, and checkpoint.ts for the derived (not
+        // hardcoded) pathspec fix.
+        draftsRoot: join(contentRoot, 'drafts'),
+        themeRoot,
+        assetsRoot: join(themeRoot, 'assets'),
+        rootMirrorRoot: join(themeRoot, 'root'),
+        templatesRoot: join(themeRoot, 'templates'),
+        pagesRoot: join(contentRoot, 'pages'),
+        menusRoot: join(contentRoot, 'menus'),
+        // Also nested inside contentRoot, for the same reason.
+        redirectsPath: join(contentRoot, 'redirects.json'),
+        vhostRoot,
+        dataRoot,
+        searchIndexPath: join(dataRoot, 'search-index.sqlite'),
+        mediaRoot: join(normalisedRoot, 'media'),
+    };
+}

package/dist/create-site/cli.d.ts

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