@rigel-cms/rigel 1.4.0-rc.1 → 1.4.0-rc.3

package/README.md

@@ -18,9 +18,11 @@ Rigel edits content, not `.astro` components. Developers define the editable fie
 
 ## Get started
 
-Use the [Astro starter](https://github.com/rigel-cms/rigel-starter), or follow the [installation guide](https://rigelcms.dev/docs/getting-started/) to add Rigel to an existing site. Requires Node.js 24 and Astro 7.3 or later within Astro 7.
+Use the [Astro starter](https://github.com/rigel-cms/rigel-starter), or follow the [installation guide](docs/getting-started.md) to add Rigel to an existing site. Requires Node.js 24 and Astro 7.3 or later within Astro 7.
 
-[Documentation](https://rigelcms.dev/docs/) · [Content model](https://rigelcms.dev/docs/content-model/) · [Previews](https://rigelcms.dev/docs/preview/) · [GitHub setup](https://rigelcms.dev/docs/github-publishing/)
+[Documentation](docs/README.md) · [Content model](docs/content-model.md) · [Previews](docs/preview.md) · [GitHub setup](docs/github.md)
+
+The guides live in this repository and ship with the npm package. They describe the current source; features on `main` may not yet be in npm's `latest` release. The [documentation website](https://rigelcms.dev/docs/) is also available.
 
 ## Content languages
 

package/docs/README.md

@@ -0,0 +1,28 @@
+# Rigel CMS documentation
+
+Rigel edits content stored in an Astro site's repository. Developers define the fields and templates; editors change content at `/rigel/` and press Save. The site owns routing, HTML, styles and deployment.
+
+These guides follow the SDK source in this repository. Check your installed version before using features that have not reached npm's `latest` release.
+
+## Start here
+
+- [Getting started](getting-started.md): use the starter or add an editable page to an existing Astro site.
+- [Content model](content-model.md): native documents, fields, sections and shared references.
+- [Preview bindings](preview.md): prepare real page templates for unsaved visual editing.
+
+## Configure your site
+
+- [Content navigation](sidebar.md): sidebar entries, categories and page tables.
+- [Content languages](content-locales.md): localized types, template selection and search scope.
+- [Menus](menus.md): JSON menu data and your site's navigation renderer.
+- [Media](media.md): uploads, metadata, providers and image pickers.
+- [Authors and references](authors.md): reusable author records and article selectors.
+- [Content and SEO](seo.md): editable metadata and the HTML your templates must render.
+- [Extensions](extensions.md): custom article controls and saved blocks.
+
+## Save and publish
+
+- [GitHub connection and publishing](github.md): authentication, draft saves and reviewed publishing.
+- [Live and draft previews](preview-hosts.md): preview mappings and deployment hosts.
+
+Content Save and website deployment are separate operations. Local Save writes files without committing them. GitHub Save writes the configured editing branch; publishing follows the configured branch workflow and hosting pipeline.

package/docs/authors.md

@@ -0,0 +1,133 @@
+# Authors and references
+
+Authors are shared content documents. They describe contributors to your site, independently of the account signed into Rigel or the author label attached to a media upload.
+
+## Declare author documents
+
+Add an author type to the site's schema:
+
+```ts
+import { defineDocument, defineSchema } from "@rigel-cms/rigel/content";
+
+const authorDocument = defineDocument({
+  name: "author",
+  title: "Authors",
+  type: "document",
+  folder: "src/content/authors",
+  shared: true,
+  creatable: true,
+  columns: ["photo", "email"],
+  fields: [
+    { key: "name", label: "Name", type: "string", required: true },
+    { key: "description", label: "Description", type: "text" },
+    { key: "photo", label: "Photo", type: "image" },
+    { key: "email", label: "Email", type: "string" },
+    { key: "url", label: "Website", type: "url" },
+  ],
+});
+
+export default defineSchema({
+  documents: [authorDocument],
+  objects: [],
+});
+```
+
+Merge this declaration into your existing schema rather than replacing its document and object lists. Pass that schema to `rigel({ schema })`; see the [content model](content-model.md) and [getting started](getting-started.md).
+
+For an initial author, create `src/content/authors/sam.json`:
+
+```json
+{
+  "_id": "author:sam",
+  "_type": "author",
+  "name": "Sam",
+  "description": "Editor",
+  "photo": "/images/sam.jpg",
+  "email": "sam@example.com",
+  "url": "https://example.com"
+}
+```
+
+The filename supplies the stable slug. `_id`, when present, must match `author:<slug>`, and `_type` must match the declared document type. Only `name` is required by this schema. Use an existing image URL or omit `photo`.
+
+Shared types appear under Shared content. A custom [sidebar](sidebar.md) can link to the author table with `{ kind: "link", target: { kind: "documents", type: "author" }, icon: "users" }`.
+
+The table uses names, slugs and configured columns; image columns lead with square thumbnails. Thumbnails leave the original image unchanged, and missing author photos use a placeholder. Shared documents open in a form rather than a website canvas. Add new starts an in-memory draft; Save writes its JSON using the selected backend. Existing records keep explicit Save and unsaved-navigation protection.
+
+Set `creatable: false` for a developer-maintained list. Rigel then hides Add new and the content stores reject creation. Existing records remain editable. Document deletion is developer-managed. For nonsingletons, creation is enabled by default.
+
+## Reference an author from native content
+
+Native schema fields use an array of allowed document types and store reference objects. Add this field to a document's or object's `fields`:
+
+```ts
+{ key: "author", label: "Author", type: "reference", to: ["author"] }
+```
+
+Its saved value is:
+
+```json
+{ "author": { "_ref": "author:sam" } }
+```
+
+For several contributors, use an array of references:
+
+```ts
+{
+  key: "authors",
+  label: "Authors",
+  type: "array",
+  items: [{ type: "reference", to: ["author"] }],
+}
+```
+
+Each array entry needs its own stable `_key`:
+
+```json
+{
+  "authors": [
+    { "_key": "contributor1", "_ref": "author:sam" }
+  ]
+}
+```
+
+The editor provides the reference and array controls. These are native schema fields, not a separate author selector API. Selection changes the current draft; it does not save it. Validation checks the reference shape, declared target type and target existence. Array entries require unique stable keys. Save the author before referencing it from another document.
+
+## Render referenced data
+
+Native references remain objects in saved content. Resolve them in an Astro template with `derefDocument`:
+
+```astro
+---
+import { derefDocument } from "virtual:rigel-content";
+interface Props { author: unknown }
+const { author: reference } = Astro.props;
+const author = derefDocument(reference);
+const name = author?.type === "author" ? String(author.data.name ?? "") : "";
+---
+{name && <span>{name}</span>}
+```
+
+Pass the saved field as the component's `author` prop. Resolve each entry separately for an author array. `getDocument("author:sam")` also reads a document by its stable ID. Both helpers return `undefined` when resolution fails, so handle missing references in your templates.
+
+The starter's `src/content/schema.ts` demonstrates native references such as its shared primary contact. Its section renderer uses `derefDocument` for shared content. Those patterns apply to authors without changing document bodies or inventing an author-specific field type. See [preview](preview.md) for binding content to an editable website view.
+
+## References in configured article collections
+
+Configured `collections[].fields` use a different reference contract from native schema fields. The starter's Blog and News examples use this collection form:
+
+```ts
+{ key: "author", label: "Author", type: "reference", to: "author" }
+```
+
+Here `to` is a string, and the saved article frontmatter contains the string ID `"author:sam"`. Set `multiple: true` to store an array of string IDs instead. This collection option does not apply to native `FieldDef`; native content uses the reference objects and arrays above.
+
+Collection fields can instead use a fixed `options` array of `{ value, label }` entries. Supply exactly one of `to` or `options`. Optional option metadata includes `description`, `photo`, `email` and `url`, but the selector displays names only. Fixed options live in site configuration and cannot be added through Authors.
+
+Collection validation rejects unknown or duplicate IDs and incorrect single/multiple shapes. Historical unavailable references remain visible in the selector rather than silently clearing. The starter's `src/components/PostPage.astro` resolves collection string IDs with `getDocument` and joins names for multiple authors. References are not automatically expanded in frontmatter or arbitrary templates.
+
+## Public data and shared content
+
+Author email addresses, biographies and photos are site content, not credentials or private account data. Local-mode builds include author records in the CMS manifest; GitHub-mode builds omit document values and load them after authentication. Your website templates may also expose these fields. Publish only details contributors have agreed to share, and render only the fields your website needs.
+
+Shared content without a locale remains available across content languages. See [content locales](content-locales.md), [media](media.md) for photo selection, [GitHub](github.md) for remote saves, and the [documentation index](README.md) for the other guides.

package/docs/content-locales.md

@@ -4,6 +4,7 @@ Content languages are optional. Configure them separately from `languages`, whic
 
 ```js
 rigel({
+  search: { scope: "all" },
   contentLocales: {
     defaultLocale: "en",
     locales: [
@@ -44,7 +45,15 @@ defineDocument({
 
 Each type can have different fields, allowed sections and initial content. You can also annotate an existing `defineCopy` page with `locale`. Rigel reads the annotation, not the folder name.
 
-With multiple configured locales, the editor shows a Content language dropdown. It filters navigation, page lists, collections and search. Switching away from unsaved changes offers the existing Save, Discard and Keep editing choices. New sessions start with `defaultLocale`.
+With multiple configured locales, the editor shows a Content language dropdown. It filters navigation, page lists and collections. Switching away from unsaved changes offers the existing Save, Discard and Keep editing choices. New sessions start with `defaultLocale`.
+
+## Global search
+
+Sidebar search (⌘/Ctrl + K) searches **all content languages** by default. Set `search: { scope: "currentLocale" }` in your Astro integration to default to the selected content language plus shared resources instead. Missing or invalid scope values fall back to `"all"`. This setting does not change the Pages table's language filter or its live search.
+
+In **Settings → Content → Search content languages**, editors can choose **Website default**, **All languages**, or **Current content language**, alongside the article editing preferences. The override applies immediately and persists in `rigelcms.settings.userPref.searchScope` in this browser. Website default removes the override; Erase All Data resets it with the other browser preferences. It is independent of the editor interface language, which lives in **Settings → Interface** after Theme and Accessibility. Current content language is disabled when there are fewer than two configured content languages.
+
+Results include legacy pages, native documents, collections, posts and menus. Shared resources appear once. Localized results show two-character language codes when multiple content languages exist, with the full configured label available on hover and to screen readers. Opening another language's result switches content language and opens that exact resource through the existing unsaved-changes guard; Keep editing leaves the language and draft untouched. Search still shows at most 12 results.
 
 Content without a `locale` remains visible in every language. Use this for common authors, media and other shared records. A shared document type can also have a locale when its records are language-specific. The language filter is an editing convenience, not an access-control boundary: the manifest and publishing batch still contain the site's complete content.
 
@@ -54,8 +63,8 @@ Your Astro routes and templates still own website localization, including public
 
 ## Page categories and templates
 
-Set `category` on a nonshared document definition to group its pages, for example `category: "Articles"`. This is schema metadata, not an editable field in stored documents. Uncategorised native documents and legacy copy pages remain in **Core** without a migration. When categories exist, the Pages table offers Core, All pages and each category visible in the selected content language. Core is the initial filter when uncategorised pages or types exist; category-only sites initially show All pages. Back returns to the originating table/filter, not a filter inferred from the opened page.
+Set `category` on a nonshared document definition to group its pages, for example `category: "Articles"`. This is schema metadata, not an editable field in stored documents. Uncategorised native documents and legacy copy pages remain in **Core** without a migration. Pages initially shows **All pages**. When categories exist, the table offers Core, All pages and each category visible in the selected content language. The live search matches title/name, slug and category substrings, ignores case and surrounding whitespace, and combines with the selected category. Its clear button restores input focus. Back preserves both the query and originating table/filter, not a filter inferred from the opened page. Content-language switches retain the query and reset unavailable categories to All pages.
 
 Add new asks for a page name and a category from the locale-eligible, creatable document types. When a category contains multiple types, the editor also requires a Template choice using each definition's title. Shared, singleton and `creatable: false` types are not creation choices. A single uncategorised type keeps the name-only dialog. Creation uses the selected type's identity, initial values and section template; nothing is written until Save.
 
-A visual variant can be another document definition with its own category, defaults and template—for example a Resources category with a dark-theme initial value. Its native type, folder, preview mapping and host renderer must be configured normally. A category does not change the editor theme, rewrite existing document types or generate website routes.
+Use a per-page theme field for light and dark variants that share the same content structure, and let your host template render that choice. Create a separate document definition when the fields or section template differ. Categories organize content; they do not change the editor theme, rewrite existing document types or generate website routes.

package/docs/content-model.md

@@ -0,0 +1,131 @@
+# Content model
+
+Rigel stores schema documents as JSON files in your site repository. Developers declare fields and render the public pages; editors change the values in `/rigel/`. Schema documents can coexist with `defineCopy` modules, article collections and [menus](menus.md).
+
+For installation, see [Getting started](getting-started.md). For the full guide list, see the [documentation index](README.md).
+
+## Declare documents and sections
+
+Put a schema in `src/content/schema.ts`:
+
+```ts
+import { defineDocument, defineObject, defineSchema } from "@rigel-cms/rigel/content";
+
+export default defineSchema({
+  documents: [
+    defineDocument({
+      name: "page",
+      title: "Pages",
+      type: "document",
+      folder: "src/content/pages",
+
+      fields: [
+        { key: "title", label: "Page name", type: "string", required: true },
+        {
+          key: "sections", label: "Sections", type: "array", min: 1,
+          items: [{ type: "object", name: "intro" }],
+        },
+      ],
+      template: [{ type: "intro", values: { heading: "About the project" } }],
+    }),
+    defineDocument({
+      name: "callout",
+      title: "Callouts",
+      type: "document",
+      folder: "src/content/shared/callouts",
+      shared: true,
+      fields: [{ key: "heading", label: "Heading", type: "string", required: true }],
+    }),
+  ],
+  objects: [
+    defineObject({
+      name: "intro", title: "Introduction", type: "section",
+      fields: [
+        { key: "heading", label: "Heading", type: "string", required: true, initialValue: "Start here" },
+        { key: "body", label: "Body", type: "markdown", initialValue: "Write an introduction." },
+        { key: "callout", label: "Shared callout", type: "reference", to: ["callout"] },
+      ],
+    }),
+  ],
+});
+```
+
+Pass the schema to the integration in `astro.config.mjs`. This is a configuration excerpt:
+
+```js
+import schema from "./src/content/schema";
+
+rigel({
+  schema,
+  preview: { documents: { page: { url: "/{slug}/", index: "/" } } },
+});
+```
+
+The helpers return typed declarations; the integration validates the schema. Import helpers from `@rigel-cms/rigel/content` in site templates to avoid importing the Astro integration. Add `/// <reference types="@rigel-cms/rigel/types" />` to `src/env.d.ts` for the virtual-module types.
+
+`virtual:rigel-content` exposes `documents`, `getDocument(id)` and `derefDocument(value)`. These are build/dev-time content helpers, not a hosted content API. Your Astro routes must enumerate and render the documents. A schema declaration or preview mapping does not create public routes.
+
+## Choose fields
+
+Schema scalar types are `string`, `text`, `markdown`, `boolean`, `number`, `date`, `image`, `file`, `url`, `color`, `code` and `password`. A password control masks its display; the value remains content in the repository, so use a separate secret store for credentials.
+
+An `object` field declares nested `fields` or uses `of: "objectName"`. An `array` declares allowed `items`; named object items use `name` to select an object from `objects`. Section objects use `type: "section"` and belong in the page's `sections` array. Object and reference array items require unique, stable `_key` values. Named object items also store `_type`.
+
+A schema reference declares `to: ["callout"]` and stores `{ "_ref": "callout:notice" }`. That record must exist and belong to an allowed type before the reference can pass Save validation. Embedding an object stores a copy; a reference points to one shared record. See [Authors](authors.md) for article references, whose collection field declaration uses a different shape, and [Media](media.md) for image and file fields.
+
+Schema `markdown` fields store Markdown strings. Article collection bodies store Lexical state in `{ frontmatter, body }` JSON and have a read-only Markdown view. Keep those formats separate. Custom article blocks and widgets are covered in [Extensions](extensions.md).
+
+Markdown fields open in the article block editor when the source survives a conversion round trip. Set `sidebarOnly: true` on a `markdown` field to keep it in the properties panel even when its preview binding is available, for example a FAQ answer edited beside the question that owns it:
+
+```ts
+const faqAnswer = { key: "answer", label: "Answer", type: "markdown", sidebarOnly: true };
+```
+
+The flag applies to `markdown` fields only, and Rigel rejects it on any other type.
+
+## Seed new content
+
+A document's `initialValue` supplies initial field values. Field-level `initialValue` fills values that the document did not supply. The entered title takes precedence for a `title` field, or for `name` when the type has no `title` field.
+
+A document `template` seeds its `sections`. Each entry selects a section type and may supply `values`, which override that section's field defaults. Adding a section in the editor also uses its field defaults. Give required fields useful defaults where possible; placeholders are hints, not saved values. A default reference still needs an existing target, and a default image needs a real asset.
+
+Creation and duplication clone values and regenerate existing nested `_key` values. Each new section gets its own key. Reordering keeps those keys, so preview bindings continue to point to the same items. Defaults do not exempt content from required-field validation.
+
+## Keep identity separate from URLs
+
+For `src/content/pages/about.json`, the storage identity is `page:about`. `_id`, when present, must match that identity, and `_type` must match the document type. The filename remains stable when an editor changes the page name or URL slug.
+
+A non-shared document's `slug` value is an optional URL override. Rigel normalizes edited slugs to lowercase ASCII kebab-case and checks mapped page-route collisions; absent overrides fall back to the filename. Changing `title` alone does not change the URL. Use `effectiveSlug` or `pageRoute` from `@rigel-cms/rigel/content` in host routing rather than assuming every public URL matches the filename. The `index` mapping above maps an effective slug of `home` to `/`.
+
+Rigel checks declared document routes and fixed copy-page mappings, not every route your Astro site might emit. Developers must avoid collisions with unrelated host routes and keep public routing consistent with preview mappings.
+
+## Organize pages and shared records
+
+Non-shared document types appear in All pages. Uncategorized pages belong to Core; set `category: "Legal"` or another name to create a separate group. This is editor metadata, not a route prefix. Shared types use standalone forms rather than a website canvas. Use `singleton: true` for a single settings record and `creatable: false` to disable creation. Provision that record in the repository; the declaration does not generate its file.
+
+A shared edit affects every consuming page after Save and the site's rebuild or development refresh. A preview URL does not turn a shared record into a page editor. See [Sidebar](sidebar.md) for navigation and [Content locales](content-locales.md) for optional language-specific types.
+
+## Bind the page preview
+
+The schema cannot infer which DOM elements display a field. Give rendered elements explicit `data-rigel-*` bindings and an owning document ID. This Astro excerpt assumes `doc` and an `intro` section from the schema above:
+
+```astro
+<section data-rigel-section="intro" data-rigel-key={section._key} data-rigel-doc={doc.id}>
+  <h1 data-rigel-text={`sections.${section._key}.heading`} data-rigel-doc={doc.id}>
+    {section.heading}
+  </h1>
+  <div data-rigel-richtext={`sections.${section._key}.body`} data-rigel-doc={doc.id}>
+    <Fragment set:html={renderedBody} />
+  </div>
+</section>
+```
+
+Here `renderedBody` must be safely rendered Markdown supplied by your host code. Bindings use dot-separated field paths with stable array keys, not CSS selectors or array positions. New sections also need prepared DOM templates. See [Preview](preview.md) for templates, shared-reference bindings and the sandbox limits, and [SEO](seo.md) for native page metadata.
+
+## Save and storage limits
+
+Content stays in memory until explicit Save. Unsaved-navigation guards offer a chance to save, discard or keep editing; failed saves retain the draft. Browser preferences persist independently of content.
+
+The local document endpoint works only in development with the local backend. It validates content and reference targets, requires same-origin writes, rejects unsafe paths and prototype keys, and writes within declared folders. Document files and request bodies have a 1 MiB limit. The request checks Content-Length before reading, then checks the buffered body size; this is not a streaming memory limit.
+
+Local writes use temporary files and atomic replacement; creation refuses an existing target. Local Save writes files without creating a Git commit. The SDK does not provide a general multi-process transaction or reserve arbitrary Astro routes. Schema document deletion remains developer-owned, so check references before removing files or types. For remote saving and publishing, see [GitHub](github.md).

package/docs/getting-started.md

@@ -0,0 +1,139 @@
+# Getting started
+
+Use Node.js 24 and Astro 7.3 or later within Astro 7. These guides describe the SDK in this repository. Features on `main` may not yet be available under npm's `latest` tag.
+
+## Start with a prepared site
+
+Use the [Rigel starter](https://github.com/rigel-cms/rigel-starter) as a GitHub template, then clone your new repository. The starter includes page templates, articles, menus and media examples.
+
+With pnpm installed, run these commands in the site directory:
+
+```sh
+pnpm install
+pnpm dev
+```
+
+Open `/rigel/` on the local server. Change a field and press Save. Local mode writes content files in your checkout; it does not create Git commits. Run `pnpm build` to check the published routes before deploying your site.
+
+## Add Rigel to an existing Astro site
+
+Install the SDK with your site's package manager:
+
+```sh
+npm install @rigel-cms/rigel
+```
+
+To test a prerelease, install `@rigel-cms/rigel@next` instead. Keep the resolved version in your site's lockfile.
+
+The example below creates an editable About page. Keep your existing Astro integrations when adding Rigel.
+
+Create `src/content/schema.ts`:
+
+```ts
+import { defineDocument, defineSchema } from '@rigel-cms/rigel/content';
+
+export default defineSchema({
+  objects: [],
+  documents: [
+    defineDocument({
+      name: 'page',
+      title: 'Pages',
+      type: 'document',
+      folder: 'src/content/pages',
+      fields: [
+        { key: 'title', label: 'Title', type: 'string', required: true },
+        { key: 'intro', label: 'Introduction', type: 'text' },
+        { key: 'draft', label: 'Draft', type: 'boolean', initialValue: true },
+      ],
+    }),
+  ],
+});
+```
+
+Add the integration in `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import { rigel } from '@rigel-cms/rigel';
+import schema from './src/content/schema';
+
+export default defineConfig({
+  integrations: [
+    rigel({
+      backend: 'local',
+      schema,
+      preview: { documents: { page: { url: '/{slug}/' } } },
+    }),
+  ],
+});
+```
+
+Create `src/content/pages/about.json`:
+
+```json
+{
+  "_id": "page:about",
+  "_type": "page",
+  "title": "About",
+  "intro": "A short introduction to the people behind this website.",
+  "slug": "about",
+  "draft": false
+}
+```
+
+The record's ID stays stable when its public slug changes. The saved example is published so that the route below also appears in a production build. Newly created pages start as drafts because of the schema's `initialValue`.
+
+Add Rigel's virtual-module declarations to `src/env.d.ts`:
+
+```ts
+import '@rigel-cms/rigel/types';
+```
+
+Create `src/pages/[slug].astro`:
+
+```astro
+---
+import { documents } from 'virtual:rigel-content';
+import { effectiveSlug } from '@rigel-cms/rigel/content';
+
+export function getStaticPaths() {
+  return documents
+    .filter(doc => doc.type === 'page' && (import.meta.env.DEV || doc.data.draft !== true))
+    .map(doc => ({
+      params: { slug: effectiveSlug(doc.data, doc.slug) },
+      props: { doc },
+    }));
+}
+
+const { doc } = Astro.props;
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>{String(doc.data.metaTitle || doc.data.title)}</title>
+  </head>
+  <body>
+    <main data-rigel-doc={doc.id}>
+      <h1 data-rigel-text="title" data-rigel-doc={doc.id}>{String(doc.data.title)}</h1>
+      <p data-rigel-text="intro" data-rigel-doc={doc.id}>{String(doc.data.intro ?? '')}</p>
+    </main>
+  </body>
+</html>
+```
+
+Run `npm run dev`, open `/rigel/`, then choose Pages and About. The preview mapping loads `/about/`; the `data-rigel-*` bindings connect its text to the editable fields. Your Astro route owns the HTML and draft filtering.
+
+## What saves where
+
+Content edits require Save. Leaving an unsaved editor opens the existing save, discard or keep-editing dialog. Browser preferences, such as interface language and search scope, save separately in browser storage.
+
+Local editing is available through Astro's development server. Deploying a static build does not deploy a filesystem-write service. Configure the [GitHub backend](github.md) for editing a deployed site, then let your hosting pipeline build the saved content.
+
+## Continue
+
+- [Content model](content-model.md): fields, objects, references and page templates.
+- [Preview bindings](preview.md): images, Markdown and repeated sections.
+- [Content languages](content-locales.md): localized pages and search preferences.
+- [Live and draft hosts](preview-hosts.md): connect previews to your deployment workflow.
+- [Documentation index](README.md): menus, media, authors and other guides.

package/docs/github.md

@@ -0,0 +1,112 @@
+# GitHub connection and publishing
+
+Rigel's GitHub backend reads content from a workspace branch and commits changes when an editor chooses Save. Publishing is a separate action: review the saved changes, then confirm a pull request squash merge into the publishing branch. Your hosting provider builds and deploys the result.
+
+For installation and a first local edit, start with [Getting started](getting-started.md). For branch builds and preview URLs, see [Preview hosts](preview-hosts.md).
+
+## Configure the site
+
+Keep your site's schema, collections, menus and preview settings when switching backends. A root-level Astro project can use this configuration:
+
+```js
+import { defineConfig } from "astro/config";
+import { rigel } from "@rigel-cms/rigel";
+
+export default defineConfig({
+  integrations: [
+    rigel({
+      backend: "github",
+      repo: "example-org/website",
+      branch: "drafts",
+      publishBranch: "main",
+      repoRoot: "",
+      authOrigin: "https://auth.rigelcms.dev",
+      appSlug: "rigel-cms",
+    }),
+  ],
+});
+```
+
+Replace `example-org/website` with the repository containing your site's content. The example shows the default branch, path and authentication settings explicitly; only `backend` and `repo` are required to select this backend.
+
+| Option | Meaning |
+| --- | --- |
+| `repo` | GitHub repository in `owner/name` form, not a URL. |
+| `branch` | Editor workspace branch, default `drafts`. Use a dedicated branch; the remote backend rejects `main` and `master` as workspaces. |
+| `publishBranch` | Destination for publishing, default `main`. Set it to `master` or another branch if that is what your production host builds. It must differ from `branch` and already exist. |
+| `repoRoot` | Astro project folder relative to the repository root. Use `""` for a root-level project or, for example, `"sites/website"` for a subfolder. Content folders remain relative to the Astro project. |
+| `authOrigin` | Authentication gateway origin. The default uses the public Rigel gateway. Custom values must be HTTPS origins without paths, credentials, queries or fragments; HTTP is allowed on loopback. |
+| `appSlug` | GitHub App slug, default `rigel-cms`. Override it together with the gateway only when using your own compatible authenticator. |
+
+The default connection uses the [public Rigel CMS GitHub App](https://github.com/apps/rigel-cms). Site developers and editors do not need to deploy a gateway or create an App. The gateway handles the OAuth exchange; the editor uses the resulting GitHub App user token to call GitHub. App secrets belong on the authenticator, never in site configuration.
+
+## Prepare repository access
+
+An editor needs write access to the configured repository. The GitHub App must be installed for that repository, active, and granted Contents read/write permission. Authorizing a GitHub identity alone does not grant editing access.
+
+Publishing also needs Pull requests read/write permission. The connection check verifies Contents write and the user's repository write access; a successful connection does not prove that publishing permissions are available. If an installation needs updated permissions, its owner must approve them, then the editor must reconnect.
+
+For in-editor publishing, enable squash merging and disable automatic head-branch deletion in the repository settings. Rigel checks both settings during review and confirmation so that the workspace survives a publish. It does not change these settings for you.
+
+## Sign in and install the App
+
+- Open `/rigel/` and choose **Sign in with GitHub**. Allow the sign-in popup and approve only an editor origin you trust.
+- Complete GitHub authorization. Rigel checks the configured App's installations, selected repositories, Contents permission and your repository write access before loading the editor.
+- If access is missing, choose **Install / configure GitHub access**. GitHub opens its account or organization and repository picker in a separate tab. Choose **Only select repositories** and include your content repository. An organization owner may need to approve the installation.
+- Return to the editor tab and choose **Check repository access**. Installing the App does not automatically reconnect the editor tab.
+
+For local testing with the public gateway, use `http://localhost`. Use HTTPS for a deployed editor.
+
+Repository selection limits the App's access, not the token to one editor. A GitHub App user token can access repositories available to both the user and the App. Treat the editor origin as trusted code.
+
+The editor stores the short-lived session in `localStorage`, scoped to the gateway, repository, workspace branch and App slug. Reloading can restore an unexpired session, after which Rigel checks access again. This storage is accessible to scripts on the same origin; deploy the editor on an origin you control and trust. The login handshake checks the popup, gateway origin and a fresh nonce before accepting a token.
+
+Expired or revoked access blocks writes. **Reconnect GitHub** checks access again while keeping the current draft. **Sign out** uses the unsaved-changes guard and clears the editor session; it does not revoke the App's authorization in GitHub or clear the gateway's HttpOnly cookie. Manage GitHub grants in your GitHub settings.
+
+## Load content and save drafts
+
+After access verification, Rigel loads content from the current workspace branch, rather than using build-time content values. If the workspace does not exist, this initial load creates it from `publishBranch`. Signing in and connecting can therefore create a branch before the first Save. An existing workspace is never reset or force-pushed.
+
+Content edits stay in memory until you choose **Save**, including the **Save and leave** option in the unsaved-changes dialog. Each Save commits the selected copy page, schema document, article or menu to the workspace. Changing a field does not autosave, and Save does not publish.
+
+Rigel validates content and builds each write from the loaded branch revision, then advances the workspace with a non-force update and verifies the result. If another writer advances the branch, the stale write is rejected rather than replacing their work. This also protects against two editors claiming the same URL slug in different files. Preserve your unsaved edits before reloading after a conflict.
+
+If the connection fails after a write may have completed, retrying Save verifies the pending commit and content before attempting another change. A conflict or failed verification leaves the draft available in the editor.
+
+Legacy copy modules must use data-only `defineCopy({ ... })` literals. Computed values, spreads, functions and template literals are rejected instead of executed. Schema documents, articles and menus keep their JSON formats and validation.
+
+## Review and publish
+
+- Save your edits. If inputs are still unsaved, Publish explains that you must save first; it neither saves nor discards them.
+- Choose **Publish** to open the review. This stage only reads GitHub; it does not create a PR or merge anything.
+- Check the repository, both branches and the complete changed-file list. The review covers the entire repository, including files outside CMS folders and `repoRoot`. It is a file/status review, not a line-by-line diff. Inspect the diff on GitHub if you need that detail.
+- Choose **Confirm publish**. Rigel finds an open PR for the exact repository and branch pair, or creates one. It stops if multiple matching PRs exist. It then attempts a normal synchronous squash merge pinned to the reviewed workspace commit.
+- Wait for confirmation. Rigel reports publishing success only after reading back that exact PR as merged and closed, with the expected source, destination and a valid merge commit SHA.
+
+Canceling a review makes no changes. Identical branch trees mean there is nothing to publish, even if Git history says the workspace is ahead. Rigel rejects truncated trees, incomplete comparisons and reviews containing 300 or more changed-file entries instead of showing a partial list. A rename can appear as one entry with its previous filename.
+
+If a merge response is lost, Rigel checks the existing PR. If it cannot verify the outcome, it reports an unconfirmed result rather than claiming success. Retrying confirmation checks the same PR before attempting another merge. Check that PR on GitHub if the outcome remains uncertain.
+
+### Publish again after a squash merge
+
+Squash merging retains the workspace but gives the destination a different commit history. When the branches have new differences and the publishing revision is no longer an ancestor of the workspace, the review shows provisional net tree differences and offers **Sync drafts first** instead of Confirm publish.
+
+That explicit action creates or reuses the matching PR and asks GitHub to update its source branch from the publishing branch, with the reviewed workspace SHA as the expected head. GitHub merges into the workspace without resetting its history. This step does not publish.
+
+After a verified sync, Rigel reloads draft content. Open a fresh review and separately confirm publishing. If GitHub has not finished its asynchronous update when Rigel checks, wait, reload draft content and review again. Resolve sync conflicts or protection failures on GitHub. You do not need to reset or delete the workspace between publishes.
+
+### Checks, approvals and concurrent changes
+
+Required approvals, status checks and branch protections still apply. Rigel merges only an open, non-draft PR that GitHub reports as mergeable with a `clean` merge state. If approvals or checks block it, complete them on GitHub, then retry or review again if the branches changed. Merge queues or other repository policies may require completing the merge on GitHub. Rigel does not bypass those policies or schedule an automatic merge after checks finish.
+
+Before mutation, Rigel rechecks the reviewed branch revisions and the PR's source and destination. Observed changes invalidate the review. Save, deletion and publishing also have in-process overlap guards; these are not locks across other tabs or GitHub clients.
+
+The merge API pins the source SHA, but has no expected destination SHA or atomic PR-target lock. A destination advance, PR retarget or settings change after the last check can still race the merge. GitHub's merge/conflict/protection rules apply, and Rigel never force-overwrites the destination. The final PR readback checks the target before reporting success, but it cannot make that operation atomic. Signing out prevents subsequent publishing requests; it cannot recall a request already sent.
+
+## Deployment and public data
+
+A confirmed publish means the PR merged into `publishBranch`, not that your site deployed successfully. Connect that branch to your host's production build, configure a workspace branch build for draft previews if needed, and inspect build/deployment results on the host. Rigel does not configure branch builds or verify deployment completion. See [Preview hosts](preview-hosts.md) for that setup.
+
+In GitHub mode, the public editor manifest includes schemas and configuration rather than build-time document, article, menu or copy values. Schemas and initial values are still public configuration; keep credentials out of them. Your website templates decide which content reaches public pages.
+
+The media library is a build-time snapshot in GitHub mode. GitHub media uploads and imports are unavailable; manage media through your repository and rebuild the site when needed.