@phtngyn/cms 0.2.0-beta.8 → 0.3.0

package/LICENSE

@@ -1,13 +1,21 @@
-Copyright (c) 2026 Phat (phtngyn). All rights reserved.
+MIT License
 
-This software and its accompanying documentation are proprietary.
-No permission is granted to use, copy, modify, distribute, sublicense, or
-sell this software or its documentation without prior written permission
-from the copyright holder, except as required by applicable law.
+Copyright (c) 2026 Phat (phtngyn)
 
-Public availability of this software does not grant a license to it.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Third-party software included in or used by this project remains subject
-to its own copyright notices and license terms. This notice applies only
-to original code and documentation owned by the copyright holder and does
-not restrict rights granted under those third-party licenses.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,17 @@
-# `@phtngyn/cms`
+# @phtngyn/cms
 
-A CMS for Nuxt with an embedded Studio, collaborative editing, PostgreSQL persistence, and S3-compatible media storage. Install one module, configure your services in `cms.config.ts`, and create your first administrator in Studio. Database migrations and authentication are managed by the module.
+A single-site Nuxt CMS with an embedded Studio. This package includes the CMS server, Studio, database migrations, and the `cms` CLI. Studio runs at `/_cms/app` on your website.
 
-## Working on this package
+## Requirements
 
-This is the consumer guide. For implementation changes, start at [Module](./src/Module.ts) for Nuxt registration, [Configuration](./src/Configuration.ts) and [configuration compilation](./src/internal/configuration.ts) for setup, [runtime](./src/runtime/) for delivery, and [package exports and scripts](./package.json) for the current public surface. Follow the feature into its owning package and tests before changing behavior; examples below illustrate usage rather than define the current contract. The [canonical example](../../examples/nuxt/README.md) exercises the module end to end.
+Use Node 24.11 or later in the Node 24 release line, Nuxt 5 nightly, and Vue 3.6 prerelease. The [package manifest](./package.json) defines the supported ranges. This beta release requires a long-lived Node process, writable persistent storage for SQLite, and an S3-compatible bucket for media. Run one CMS server process per installation.
 
 ## Install
 
-Requires Node.js 24, Nuxt `>=4.5.0 <5`, and Vue `>=3.6.0-rc.6 <4`. Deploy as a Node server with WebSocket support; static hosting is not supported.
+In a Nuxt project, install the CMS and its framework peers. These commands use the nightly and Vue versions tested for this release; recheck them when upgrading the CMS.
 
 ```sh
-pnpm add @phtngyn/cms@beta effect
+pnpm add @phtngyn/cms@0.3.0 nuxt@npm:nuxt-nightly@5.0.0-2610091554-2b103c9 vue@3.6.0-rc.10
 ```
 
 Register the module in `nuxt.config.ts`:
@@ -22,436 +22,91 @@ export default defineNuxtConfig({
 })
 ```
 
-## Configure
+Create `app/cms/collections.ts`:
 
-Create a PostgreSQL database and an S3-compatible bucket. The database user must be able to create and migrate CMS tables. Storage credentials need bucket access and object read, write, copy, list, and delete permissions. Configure public reads through your bucket or CDN; the module does not configure public access policies.
+```ts
+import { defineCmsCollections, defineCmsCollection, field } from '@phtngyn/cms/Collections'
+
+export default defineCmsCollections([
+  defineCmsCollection({
+    collection: 'pages',
+    label: 'Pages',
+    pattern: '/:path*',
+    fields: { title: field.text({ required: true }) },
+  }),
+])
+```
 
-Create `cms.config.ts` beside `nuxt.config.ts`:
+Create `cms.config.ts`. Replace the bucket and region with your own; this example uses an existing bucket and the AWS credential provider chain.
 
 ```ts
-import { defineCmsConfig } from '@phtngyn/cms/Configuration'
-import { pageSchema } from './page.schema'
+import { defineCmsConfig } from '@phtngyn/cms/Config'
 
 export default defineCmsConfig({
-  documents: {
-    collections: {
-      pages: {
-        label: 'Page',
-        route: '/:path*',
-        schema: pageSchema,
-      },
-    },
+  seo: { siteName: 'My website' },
+  runtime: {
+    origin: 'http://127.0.0.1:3000',
+    s3: { bucket: 'my-cms-media', region: 'us-east-1' },
   },
-  installation: {
-    database: { schema: 'cms' },
-    media: {
-      prefix: 'cms/',
-    },
+  $development: {
+    bootstrap: { administrator: { name: 'Administrator' } },
   },
 })
 ```
 
-Keep environment-specific values in Nuxt runtime configuration. The module supplies empty `runtimeConfig.cms` defaults, so a production build needs no credentials. Nitro reads these values only when the built server starts:
+For another S3 provider, set `runtime.s3.endpoint` and, if required, `forcePathStyle`. Give each installation a separate bucket or prefix. Supply credentials and initial administrator details in a git-ignored `.env`:
 
 ```dotenv
-NUXT_CMS_BASE_URL=http://localhost:3000
-NUXT_CMS_DATABASE_URL=postgres://cms:cms@localhost:5432/cms
-NUXT_CMS_INITIALIZATION_TOKEN=replace-with-a-distinct-32-character-random-token
-NUXT_CMS_SECRET=replace-with-at-least-32-random-characters
-NUXT_CMS_MEDIA_BUCKET=cms-media
-NUXT_CMS_MEDIA_PUBLIC_BASE_URL=http://localhost:8333/cms-media
-NUXT_CMS_MEDIA_REGION=us-east-1
-NUXT_CMS_MEDIA_ENDPOINT=http://localhost:8333
-NUXT_CMS_MEDIA_FORCE_PATH_STYLE=true
-NUXT_CMS_MEDIA_ACCESS_KEY_ID=cms-media
-NUXT_CMS_MEDIA_SECRET_ACCESS_KEY=cms-media-secret
+NUXT_CMS_S3_ACCESS_KEY_ID=your-access-key
+NUXT_CMS_S3_SECRET_ACCESS_KEY=your-secret-key
+NUXT_CMS_BOOTSTRAP_ADMINISTRATOR_EMAIL=you@example.com
+NUXT_CMS_BOOTSTRAP_ADMINISTRATOR_PASSWORD=choose-a-password-of-at-least-eight-characters
 ```
 
-Generate distinct random values of at least 32 characters for the secret and initialization token, and keep them server-side. The same built artifact can be started against another environment by changing only these runtime values.
-
-For storage using the AWS credential chain, omit both credential variables. Set `NUXT_CMS_MEDIA_PROVISION_BUCKET=true` to create a missing bucket automatically and grant bucket-creation permission. Set authored `installation.media: false` to build without uploads.
-
-The PostgreSQL schema and S3 prefix are the installation's ownership boundary. CMS creates and migrates only the configured schema, and every media object stays under the configured prefix.
-
-## Local development lifecycle
-
-Use the supported lifecycle before starting Nuxt:
+Start the installation:
 
 ```sh
-cms dev doctor
-cms configuration check
-cms --json configuration check > configuration-report.json
-CMS_EMAIL=admin@example.test CMS_PASSWORD=admin@example.test cms dev bootstrap --content ./content --publish
-cms dev reset --database --media
-cms dev reset --database --media --yes --bootstrap --content ./content --publish
+pnpm exec cms dev
 ```
 
-All lifecycle commands accept `--root <directory>`, `--env-file <path>`, `--verbose`, and `--json`. Values already present in the process override the explicit environment file, which overrides `<root>/.env`, which overrides Nuxt runtime-config defaults.
-
-`doctor` is read-only and reports pass, fail, or not-verified for configuration, PostgreSQL, migrations, S3, public media, packaged assets, readiness, and WebSockets. Add `--full` to validate pending migrations in a rolled-back transaction and probe database writes plus an actual publicly readable S3 object, or `--json` for editor and CI integrations. `bootstrap` prepares the Nuxt authoring catalog, provisions infrastructure, runs migrations, creates or updates the requested local administrator, and optionally plans and applies content without requiring a running server. Passwords come from `CMS_PASSWORD` or a private prompt.
+The CLI generates a private installation secret in `.env`, starts Nuxt, and creates the initial administrator for a fresh installation. SQLite defaults to `.data/cms.sqlite`. In a second terminal, run `pnpm exec cms doctor`; once ready, open `http://127.0.0.1:3000/_cms/app` and sign in. Distributed installations use the included Studio assets.
 
-`reset` is a dry run unless `--yes` is present. It refuses to run while the configured CMS is live and can remove only the configured PostgreSQL schema and S3 prefix. Choose `--database`, `--media`, or both.
-
-`configuration check` is the read-only local and CI gate for authored configuration changes. It compares `cms.config.ts` plus discovered blocks and forms with the installation's accepted serializable catalog, validates every authored and published Document, and emits the same underlying report used during startup. Human output names each required remediation; `--json` emits the versioned report without presentation text. Compatible reports exit successfully. Reports with affected Documents exit unsuccessfully, so CI can use the command directly.
-
-Runtime startup records the first valid catalog and later compatible candidates. It never rewrites Documents to make a candidate fit. Field renames or removals, route or locale changes, unavailable blocks, narrower block permissions, and narrower form capabilities must be resolved through a separate explicit content change before startup can adopt the candidate.
-
-## Content CLI
-
-The installed package provides a `cms` command for importing a plain Markdown folder, exporting Studio-authored Markdown, and moving content between running CMS installations. Create the first administrator in Studio, then sign in to the CLI with that administrator's email and password. The CLI prompts for the site URL, administrator email, and password when they are missing. For noninteractive use, set `CMS_URL`, `CMS_EMAIL`, and `CMS_PASSWORD`; `--url` and `--email` can replace the first two variables. Use HTTPS outside localhost.
+## Build and deploy
 
 ```sh
-CMS_URL=https://source.example.com CMS_EMAIL=admin@example.com cms content export ./content
-CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content diff ./content
-CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content plan ./content
-CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content apply ./content
-CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content plan ./seed --publish
-CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content apply ./seed --publish
-```
-
-Export chooses deterministic filesystem paths and writes a version 2 `.cms-content.json` index containing each document's stable identity, revisioned placement, revision ID, publication state, and content hash. Filesystem paths are only an import/export concern; moving a document in Studio does not rename anything in core document state. Commit the Markdown and index together to review changes. Export preserves indexed paths when possible, refuses to replace locally edited Markdown or index entries, and does not delete files that disappeared from the CMS. Remove stale files and index entries yourself after review. `diff` compares local Markdown, placement, and publication state with the current target and reports target-only documents. `plan` validates the whole incoming set and lists creates, updates, publications, unpublications, and conflicts without writing. `apply` plans again, then commits the batch atomically against the generation it just inspected. Run `plan` and `diff` before applying, especially when targeting another environment.
-
-The export index and every indexed Markdown path must stay inside the selected content directory without symlinked path components. Import and export reject symlinks at those boundaries.
-
-For a folder without `.cms-content.json`, the CLI reads nested `.md` and `.mdc` files and infers an initial collection, locale, parent, and slug from folders. A collection or locale directory is optional when configuration makes it unambiguous; `index.md` represents the home document or the entry represented by its containing folder. This inference happens only on the first unindexed import. These sources are eligible for publication with `--publish`. Imports create drafts by default. Existing content with different Markdown is a conflict until you pass `--overwrite` to `plan` and `apply`. For an exported folder, `--publish` synchronizes the indexed publication state: entries marked `published: true` are published and entries marked `published: false` are unpublished. Without it, imported changes remain drafts and existing target publication stays unchanged. The CLI does not delete target documents or move a target-only document. A concurrent change after planning causes `apply` to fail; review and retry.
-
-The command tree is intentionally shared: future CMS operations can be added beside `content` without separate executables.
-
-The same workflow is available to Node scripts without parsing CLI output:
-
-```ts
-import { createCmsContentClient, readCmsContentDirectory } from '@phtngyn/cms/Content'
-
-const source = await readCmsContentDirectory('./content')
-const client = createCmsContentClient({
-  baseUrl: 'http://localhost:3000',
-  credentials: {
-    email: process.env.CMS_EMAIL!,
-    password: process.env.CMS_PASSWORD!,
-  },
-})
-
-const plan = await client.plan(source, { overwrite: false, publish: true })
-
-if (plan.valid) await client.apply(plan)
-
-const document = await client.readDocument('8c62d2a7-b839-450a-bc08-5eccb420dc60')
-await client.export({ directory: './content' })
-```
-
-Plans expose creates, updates, publications, unpublications, conflicts, issues, unchanged entries, and target-only sources. They are bound to their client, source, options, and generation; `apply(plan)` never replans. `readDocument(id)` returns the authored Markdown and exact publication state. `CmsContentError.code` provides stable authentication, not-found, conflict, validation, generation, filesystem, response, and network failure categories.
-
-## Search and sharing
-
-The module installs the focused Nuxt robots, sitemap, schema.org, and SEO utility modules. Published CMS pages receive canonical, robots, social-sharing, and structured-data metadata automatically. The sitemap contains only published, indexable documents and uses their publication revision time for `lastmod`; localized variants are emitted as alternatives when they share a document key.
-
-Administrators can edit and publish site-wide SEO defaults at `/_cms/seo`. Editors can override search and sharing fields per document, while omitted values inherit the site-wide revision. Draft preview uses working SEO settings; ordinary website requests use published settings.
-
-The initial site-wide revision is derived from `baseUrl`. To seed explicit defaults and restrict the structured identity choices Studio offers, add `seo` to `cms.config.ts`:
-
-```ts
-seo: {
-  defaults: {
-    canonicalOrigin: 'https://example.com',
-    siteName: 'Example',
-    titleTemplate: '%s · Example',
-    defaultDescription: 'Example publishes useful things.',
-    index: true,
-    follow: true,
-    identity: {
-      type: 'Organization',
-      name: 'Example',
-      url: 'https://example.com',
-    },
-  },
-  capabilities: {
-    identityTypes: ['Organization'],
-    structuredDataTypes: ['WebPage', 'Article'],
-    generatedSocialImageTemplateIds: [],
-  },
-},
-```
-
-Keep raw robots directives and Nuxt module configuration in application code. The CMS owns semantic index/follow choices and generated page metadata; it does not accept arbitrary JSON-LD or inline HTML.
-
-## Collection schemas
-
-Collections use **Standard Schema V1** for validation and **Standard JSON Schema V1** for the input structure Studio renders. This lets you keep your chosen validation library. Both contracts must be available on the collection schema; Standard Schema validation alone cannot describe controls. Studio requests draft 2020-12 JSON Schema input, resolves non-recursive local references, and runs the original validator when validating documents.
-
-The public standards types come directly from `@standard-schema/spec`. For a validator whose JSON Schema adapter is separate, `defineCmsSchema()` combines both contracts and applies library-neutral presentation to nested field paths:
-
-```ts
-import { defineCmsSchema } from '@phtngyn/cms/DocumentModel'
-
-const pageSchema = defineCmsSchema({
-  validator: page,
-  jsonSchema: {
-    input: () => createInputSchema(page),
-    output: () => createOutputSchema(page),
-  },
-  fields: {
-    description: { label: 'Description', input: 'textarea' },
-    'seo.description': { input: 'textarea' },
-  },
-})
+pnpm exec nuxt build
+node .output/server/index.mjs
 ```
 
-For a validator that already implements both standards, pass it directly as `schema`. Otherwise, adapt its validator and input/output JSON Schema converters:
-
-```ts
-const pageSchema = {
-  '~standard': {
-    ...validator['~standard'],
-    jsonSchema: {
-      input: () => inputJsonSchema,
-      output: () => outputJsonSchema,
-    },
-  },
-}
-```
-
-Supply actual draft 2020-12 schemas from the chosen library, using its input and output conversion modes respectively. Studio reads the input structure; the validator remains responsible for execution. A missing input converter produces a configuration error naming Standard JSON Schema V1. Foreign schemas use JSON Schema `title`, `description`, `default`, `x-cms-input`, and `x-cms-options` for presentation.
-
-Effect schemas are also accepted directly. The CMS derives Studio inputs from their encoded structure and runs the original decoder, preserving defaults, transformations, and asynchronous validation. Decoders must not require external Effect services, and their output must be a JSON-compatible object.
-
-```ts
-import { Schema } from 'effect'
-import { CalendarDate, field, managedMediaReference } from '@phtngyn/cms/DocumentModel'
-
-const pageSchema = Schema.Struct({
-  description: field(Schema.String, { default: '', input: 'textarea' }),
-  publishedAt: Schema.optionalKey(field(CalendarDate, { label: 'Published on' })),
-  contributors: field(
-    Schema.Array(
-      Schema.Struct({
-        id: Schema.String,
-        name: Schema.NonEmptyString,
-        role: field(Schema.String, { default: 'Contributor' }),
-      }),
-    ),
-    { default: [], label: 'Contributors' },
-  ),
-  socialImage: Schema.optionalKey(managedMediaReference),
-  title: Schema.NonEmptyString,
-})
-```
-
-Use `Schema.optionalKey` for optional fields, `Schema.NullOr` for explicit nulls, and `Schema.Finite` for numeric fields. A `field` default supplies Studio's initial value and applies only when the containing key is absent; invalid explicit values still fail. `field` can also give enum values distinct human labels through `options`. `CalendarDate` validates calendar dates stored as `YYYY-MM-DD` strings. Advanced Effect schemas, transformations, and defaults remain supported directly. `effect` is an intentional runtime dependency and is installed explicitly because authored schemas expose its public types.
-
-Studio supports strings, calendar dates, finite numbers, booleans, string arrays, choices, nested objects, repeatable objects, document references, and managed-media references. Repeatable object schemas must contain a required string `id`; Studio owns that identity and provides add, duplicate, remove, and reorder operations. `documentReference` and `managedMediaReference` store identity-backed source strings and project them to current routes or URLs for preview and delivery. Non-recursive local references are resolved. Ambiguous unions, structural intersections, recursive schemas, and unsupported field shapes fail configuration rather than producing incomplete forms.
-
-## Start editing
-
-1. Start your Nuxt application and open its `/_cms` route. In this repository, `pnpm dev` runs the canonical example at `http://localhost:3000/_cms`.
-2. Enter your initialization token and create the first administrator. Initialization then closes.
-3. Create a page in Studio, edit it, and publish it. The module provides page routing and rendering; your app must render `<NuxtPage />` in `app/app.vue` if it has a custom app shell. Existing app routes can provide custom page layouts.
-
-Studio is bundled with the module; no separate Studio deployment or auth setup is required. Readiness is available at `/_cms/health/ready`. Component schemas update through HMR during development. CMS configuration changes use Nuxt’s restart lifecycle.
-
-## Preview drafts
+Set `NUXT_CMS_ORIGIN` to the public website origin, `NUXT_CMS_DATABASE_FILE` to a persistent SQLite path, `NUXT_CMS_INSTALLATION_SECRET` to the retained installation secret, and the matching `NUXT_CMS_S3_*` values for media storage. Builds accept missing deployment credentials; server readiness requires usable configuration. Prepare a new secret with `cms prepare` before startup. For a fresh production installation, configure `bootstrap` in the production profile and run `cms setup --envName production` against the running server to create the administrator.
 
-Studio previews render authored documents through the same Nuxt routes, layouts, components, `useDocument`, and `useDocumentQuery` used by the website. A page can be previewed before its first publication. Preview mode follows internal navigation and survives iframe reloads; ordinary website requests continue to read published content.
+## Authoring and operations
 
-Draft delivery requires the current Studio session and document access permission. Preview URLs contain only iframe coordination information, never an access token. Preview HTML and draft API responses are private and uncached. Once the page renders, the editor bridge overlays current collaborative edits without waiting for publication or replacing Nuxt HMR.
+Define editable Vue blocks in `app/cms/blocks/` with `@phtngyn/cms/Authoring`. The module registers `CmsDocumentRenderer`, `CmsImage`, and document, query, SEO, and locale composables. Use `@phtngyn/cms/Delivery` for explicit imports.
 
-## Customize
+`cms --help` lists installed commands and flags. Configuration belongs in `cms.config.ts`; `nuxt.config.ts` registers the module. Use `$development`, `$production`, or `$env` profiles for environment-specific values, and select a CLI profile with `--envName`. Paths are relative to the consuming project; use `--project <directory>` from another directory.
 
-- Define collections with Effect Schema in `documents.collections`. Import `field` from `@phtngyn/cms/DocumentModel` to add field labels and input hints.
-- Use the auto-imported `useDocument` and `useDocumentQuery` composables and `DocumentRenderer`, `DocumentScope`, and `DocumentField` components for custom rendering.
-- Import `defineCmsBlock` from `@phtngyn/cms/Authoring` to declare editable props and slots in your Nuxt Vue components.
-- Import Markdown folders with `cms content plan` and `cms content apply` after creating the first administrator.
+For local S3 provisioning, declare `provision: { compose: { file: './compose.yaml', service: 'your-s3-service' }, createBucket: true }` in the development profile. The site owns that Compose file and its credentials. `cms prepare` starts the configured service and creates a missing bucket; omit `provision` when managing storage yourself.
 
-Nuxt generates `#cms/types` whenever configuration, collection schemas, or authored blocks change. It includes collection, form, block, locale, message-key, and interpolation-parameter types. Collection schema outputs, including repeatable objects and references, flow through `useDocument<'pages'>()` and `useDocumentQuery()`. Filtering and sorting remain limited to typed scalar paths and scalar lists; repeatable-object predicates are intentionally excluded. Registered form names and configured capabilities narrow `CmsFormDefinition<'contact-form'>`.
-
-```ts
-import type { CmsCollection, CmsFormDefinition, CmsLocale } from '#cms/types'
-
-const page: CmsCollection<'pages'> | null = useDocument<'pages'>('/').data.value
-const locale: CmsLocale = 'de'
-const form = {} as CmsFormDefinition<'contact-form'>
-```
-
-`useCmsI18n().t()` autocompletes configured keys and requires the exact placeholders in each message. Nuxt preparation rejects extra locale keys and inconsistent placeholders. Missing translations are allowed only when the configured fallback locale supplies the canonical message.
-
-CMS also synchronizes owned document routes with Nuxt Site Config. The delivered document locale wins, the route prefix applies while delivery resolves, and non-CMS routes retain the application's Site Config. Set `i18n.siteConfig: 'localized-routes'` to give CMS-derived language metadata to custom localized routes too; document canonical URLs, alternates, and SEO remain document-only. The default `documents` scope avoids conflicts with another application i18n module.
-
-## Studio and authoring during development
-
-Studio at `/_cms` is a separate HTML document, Vue application, and Tailwind build. It owns its Nuxt UI settings, styles, and overlays independently of the website. Your app root and layouts apply only to the website. Both applications use the same Nuxt server; no separate Studio server or port is required.
-
-Only components that declare `defineCmsBlock` appear in the authoring catalog. Nuxt compiles their Vue props, slots, imported types, and presentation into one generated `#cms/authoring` module. Studio’s entry imports this module through Nuxt’s Vite graph, so isolation does not require a custom HMR transport. A separate Vue component map supplies Comark’s renderer, so adding or removing a block does not reinitialize Studio. Valid semantic changes update Studio and rebuild the Nitro worker automatically, keeping the development listener running. Invalid changes show a Vite error and retain the last valid catalog.
-
-An open editor reads the new catalog without reseeding content or replacing its collaborative document. Publishing waits until the collaboration server and editor use the same catalog revision. Installation configuration changes still use Nuxt’s configuration restart lifecycle.
-
-## Component authoring and collection permissions
-
-Keep the Vue props, slots, defaults, and `defineCmsBlock` declaration together in the component's `<script setup lang="ts">`. Only declared fields and regions appear in Studio. Text regions accept one plain paragraph. Inline-text regions keep that single-paragraph shape while offering their declared inline formatting `features`. Rich-text regions accept multiple paragraphs and offer only their declared inline and list `features`. Optional slots can be removed and added again. Initial content seeds new blocks; it never overwrites existing content when a declaration changes. Render optional slot wrappers conditionally to avoid empty layout space.
-
-Render declared fields through ordinary Vue slot outlets. Studio follows each slot's rendered content through application components automatically: clicking a card title selects its title content, clicking its description selects the description, and clicking the remaining card surface selects the card block. Nuxt rejects an authored block when a declared slot has no matching outlet, so rendered fields cannot silently disappear from preview selection.
-
-A collection can restrict available component blocks:
-
-```ts
-pages: {
-  label: 'Page',
-  route: '/:path*',
-  schema: Schema.Struct({ title: Schema.String }),
-  body: {
-    blocks: ['content-hero'],
-    groups: ['Editorial'],
-  },
-},
-```
-
-Block names and groups form a union. Omitting `body` permits all declared blocks; `body: {}` permits none. Ordinary text remains available. Unknown selectors fail configuration validation. Studio insertion and server publication use the same document-owned rules, including blocks inside other content. A restriction change preserves existing content and reports what must be corrected before publication.
-
-Clearing an optional property removes its stored override, so a Vue default can apply. Reset writes the current declared default. Nullable fields also offer an explicit no-value choice; empty strings, zero, and false remain actual values.
-
-### Images, links, and composition
-
-String props can declare `input: 'image'` or `input: 'link'`. Studio uses the existing media library for image selection/upload and the document catalog for internal links. Internal selections are stored as `cms-document:<uuid>?route=<last-known-route>`: identity remains authoritative while the readable route provides a fallback when the target is unavailable. Studio resolves these references against authored documents and website delivery resolves them against published documents, so moving a target changes rendered links without rewriting Markdown. External links remain ordinary URLs. Image descriptions belong to a separate Vue prop; Studio does not invent an alt-text field or change your component's rendering. URL syntax and allowed schemes are checked before publication, and semantic props participate in the existing document/media reference index, including inside objects and lists.
-
-Slots with `input: 'blocks'` accept nested components. Optional `blocks` and `groups` selectors restrict direct children; omitting both permits all collection-allowed blocks. Collection permissions apply at every depth. Studio offers insertion, selection, deletion and sibling reordering inside each region. Existing content is retained when a schema change makes it invalid.
-
-For repeatable cards or chapters with formatted copy, give the parent a blocks slot restricted to an item block. Declare the item's title, icon, link, and layout choices as props, and its copy as a `rich-text` slot. Studio keeps each child block's identity and order, so the item needs no separate `id` prop. The [example section](../../examples/nuxt/app/components/documents/ContentSection.vue) hosts repeatable [cards](../../examples/nuxt/app/components/documents/ContentCard.vue); the English and German homepages show their Markdown source.
-
-Use object props for structured data and slots for composed content:
-
-```ts
-interface Props {
-  settings?: { compact: boolean }
-  features?: Array<{ id: string; title: string; link?: string }>
-}
-// Inside the component's defineCmsBlock declaration:
-props: {
-  settings: {
-    label: 'Settings', input: 'object',
-    fields: { compact: { label: 'Compact spacing', input: 'toggle' } },
-  },
-  features: {
-    label: 'Features', input: 'list',
-    fields: {
-      title: { label: 'Title', input: 'text' },
-      link: { label: 'Link', input: 'link' },
-    },
-  },
-},
-```
-
-Every list item needs a required `id: string` in its Vue type. Studio generates and preserves this value; use it as the item's Vue `:key`. Do not declare an editable control for `id`. Object/list shapes, requiredness and string choices come from Vue, including nested fields. Literal factory defaults such as `() => []` and `() => ({ compact: false })` are supported. Computed defaults and recursive types are not editable contracts.
-
-Collaboration merges object fields and list-item fields independently. List ordering is separate from item values; simultaneous insertions at the same position retain both items in deterministic identity order. Removing an item takes precedence over concurrent edits to it. Competing edits to the same field use Yjs conflict resolution. Authoring schemas and controls update through the existing HMR path without reseeding content.
-
-## Headless forms
-
-Register a form under the kebab-case name of your Nuxt Vue renderer. `defineCmsForm` is a normal TypeScript helper, not a compiler macro. It declares the question types and validation rules editors may use:
-
-```ts
-import { defineCmsConfig } from '@phtngyn/cms/Configuration'
-import { defineCmsForm } from '@phtngyn/cms/Forms'
-
-// Inside your existing defineCmsConfig configuration:
-forms: {
-  'contact-form': {
-    definition: defineCmsForm({
-      label: 'Contact form',
-      fieldTypes: ['text', 'email', 'textarea', 'number', 'checkbox', 'select'],
-      rules: ['required', 'minLength', 'maxLength', 'min', 'max'],
-    }),
-    onSubmit: async ({ form, request, values }) => {
-      // Server only: deliver or persist validated answers here.
-      // values are keyed by stable question IDs; form.steps contains their labels.
-      return { status: 'accepted', reference: request.id }
-    },
-  },
-},
-```
-
-Create `ContactForm.vue` with an optional `cmsForm?: CmsFormDefinition` prop. The registration supplies its Studio authoring controls; do not also declare `defineCmsBlock` for that renderer. Forms appear in the Forms block group and follow collection block permissions. Editors add steps, questions, choices and permitted rules in the property panel. One step produces a single-step form. Question and option IDs are managed by Studio; labels can change without changing identities. Select answers contain option IDs. There is no website input markup or CSS supplied by CMS.
-
-A valid authored form receives `cmsForm` from `DocumentRenderer`. Incomplete drafts do not; show a helpful placeholder until the form is valid. Mount your custom form contents only when that definition exists:
-
-```ts
-import type { CmsFormDefinition } from '#cms/types'
-
-const props = defineProps<{ definition: CmsFormDefinition<'contact-form'> }>()
-const {
-  steps,
-  errors,
-  currentStep,
-  stepIndex,
-  isFirstStep,
-  isLastStep,
-  submitting,
-  isSuccess,
-  isPreview,
-  submitError,
-  canSubmit,
-  visibleControls,
-  invalidControls,
-  firstInvalidControlId,
-  control,
-  next,
-  previous,
-  validate,
-  submit,
-  reset,
-} = useCmsForm(() => props.definition)
-```
-
-The composable accepts a value, ref, or getter and returns destructurable refs and functions. Iterate `visibleControls`; each reactive control exposes plain template properties: `field`, writable `value`, `dirty`, `touched`, `valid`, `error`, `attrs`, `helpAttrs`, `errorAttrs`, and `touch()`. Bind `attrs` to the native control. CMS keeps stable IDs and ARIA relationships aligned without nested `.value` access inside a `v-for`. Valid number answers become numbers, empty answers become null, and invalid number text remains visible to validation. `canSubmit`, `invalidControls`, and `firstInvalidControlId` centralize form-level behavior, while `submitError` and `errors._form` cover transport and server failures.
-
-`next()` validates the current step, `previous()` preserves answers, and `submit()` validates every step and returns whether submission succeeded. A required checkbox must be checked.
-
-Definition replacements preserve answers for matching IDs and field types within the same form, clear validation state, and cancel pending client requests. `reset()` clears answers and submission state. The composable prevents overlapping submissions and repeat submission after success until reset. Scope disposal cancels client work. Cancellation cannot undo a server handler that has already started. An optional `submit(payload, signal)` transport override supports advanced integrations; it must return `CmsFormResult` and preserve server-side validation.
-
-The endpoint resolves the current published form and checks its exact serialized revision, including capabilities and question settings. Stale pages must reload. Draft preview validates locally without invoking the handler. Invalid structure prevents publication; invalid answers and unknown answer keys never reach the handler. The application handler explicitly returns `accepted`, `invalid`, or `unavailable`; trusted validation errors may target current field IDs or `_form`. Unexpected failures are correlated by request ID in server logs without recording answers and return only a generic public failure.
-
-Requests are limited to 128 KiB and 60 submissions per minute per server process, shared across forms. Browser requests with a foreign Origin are rejected. For deployments with multiple replicas or stronger spam protection, enforce a shared limit or challenge at your edge. There is no automatic retry, durable deduplication, inbox, email delivery, upload, branching, or save-and-resume in this release. Application handlers should account for retries after an uncertain network outcome. Configuration changes use Nuxt's restart lifecycle.
-
-See `examples/nuxt/app/components/FormContents.vue` for a Tailwind-rendered example. Its server handler acknowledges submissions without storing answers.
-
-## Website languages
-
-Declare languages and developer-owned website strings together in `cms.config.ts`:
-
-```ts
-i18n: {
-  defaultLocale: 'en',
-  fallbackLocale: 'en',
-  prefix: 'always',
-  locales: {
-    en: { name: 'English', messages: {
-      navigation: { home: 'Home' },
-      footer: { copyright: '© {year} Acme' },
-    } },
-    de: { name: 'Deutsch', messages: {
-      navigation: { home: 'Startseite' },
-    } },
-  },
-},
-```
-
-Omit `prefix` to keep the default locale unprefixed (`/` for English and `/de` for German). Set it to
-`'always'` to prefix every locale (`/en` and `/de`); requests to a non-canonical form redirect permanently.
-
-Locale is part of stable document identity and route derivation. For an unindexed import, locale codes may be inferred from the first directory (`en/index.md`, `de/index.md`); the generated export index preserves the identity afterward. Markdown contains the editor-authored language already and needs no translation key. Revisions store identity, placement, and Markdown, while collaborative working edits checkpoint into Markdown. Import a Markdown folder with the admin CLI; subsequent changes require another plan and apply, with `--overwrite` for different Markdown.
-
-Use the auto-imported composable in website components:
-
-```ts
-const { t, locale, localePath, switchLocalePath } = useCmsI18n()
-const navigation = computed(() => [{ label: t('navigation.home'), to: localePath('/') }])
-const germanVersion = computed(() => switchLocalePath('de'))
-t('footer.copyright', { year: 2026 })
-```
+To transfer authored content and media, use `cms export ./site.cms.zip`, then `cms import ./site.cms.zip --dry-run` on the destination before importing. A populated destination requires `--replace` to replace its content. Credentials and sessions remain local. To seed a fresh installation, set `bootstrap.snapshot` to an exported archive's project-relative path.
 
-`locale` is a read-only computed value derived from the current URL, including in Studio's website preview. `localePath(path, code?)` builds a path using the configured locale prefix policy; the code defaults to the current locale. `switchLocalePath(code)` changes the current URL's prefix while preserving its query and fragment. For documents with different authored slugs, pass the destination's unprefixed path as the second argument: `switchLocalePath('de', '/ueber-uns')`. The CMS does not infer relationships between different slugs. The Nuxt module sets the document's HTML `lang` automatically. Lists can explicitly pass `locale.value` to `useDocumentQuery`.
+Public entry points include:
 
-Message keys receive generated TypeScript completion. Dictionaries contain nested plain strings; dots are reserved for key paths. Named `{parameters}` accept strings and numbers; missing parameters remain visible. Messages fall back from the URL locale to `fallbackLocale`, then to the key. Omit `fallbackLocale` (or set it to `null`) to disable fallback. The same explicit fallback policy applies to document lookup. Development warns about missing requested-locale messages. Render messages as text, and use native `Intl` for date and number formatting.
+| Entry point                 | Purpose                                              |
+| --------------------------- | ---------------------------------------------------- |
+| `@phtngyn/cms/Config`       | Site configuration                                   |
+| `@phtngyn/cms/Collections`  | Collection and field definitions                     |
+| `@phtngyn/cms/Authoring`    | Editable block and form metadata                     |
+| `@phtngyn/cms/Delivery`     | Document, query, SEO, and locale composables         |
+| `@phtngyn/cms/Forms`        | Visitor form controls and submission state           |
+| `@phtngyn/cms/Locales`      | Content language registry and URL helpers            |
+| `@phtngyn/cms/I18n`         | Site-owned message catalogs and translation          |
+| `@phtngyn/cms/Client`       | Node client for administrator scripts                |
+| `@phtngyn/cms/Operations`   | Offline installation backup and restore              |
+| `@phtngyn/cms/StudioServer` | Protect site-owned server tools with Studio sessions |
 
-Only validated public i18n data enters the website bundle. Installation credentials and handlers stay server-side. Small dictionaries can stay inline; larger ones can be imported into the same config. Configuration changes restart Nuxt. Omitting `i18n` creates unlocalized document identities; the composable returns an empty locale and untranslated keys.
+The installed exports include TypeScript declarations. Snapshot transfer is separate from offline backup: stop the installation before accessing its SQLite and media stores for recovery.
 
 ## License
 
-Proprietary. Copyright (c) 2026 Phat (phtngyn). All rights reserved. Use, copying, modification, and redistribution require prior written permission. Third-party components retain their own licenses.
+Original CMS code is licensed under [MIT](./LICENSE). Bundled Studio dependencies retain their own licenses, included in `studio/THIRD-PARTY-LICENSES.md`.