@stacksjs/defaults 0.75.109 → 0.75.110

package/ai/skills/stacks-calendar/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-calendar
-description: Use when working with calendar functionality in Stacks - exporting events to Google Calendar, Outlook, Yahoo, or ICS format, the CalendarLink interface for event definitions, timezone handling, all-day events, or calendar URL generation. Covers @stacksjs/calendar-api.
+description: Use when exporting calendar links or ICS bodies, building subscribable event feeds, or expanding supported recurrence rules. Covers @stacksjs/calendar-api.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,106 +8,70 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Calendar
 
-Calendar event export to 4 calendar providers.
+Use `@stacksjs/calendar-api` for add-to-calendar links, downloadable ICS,
+subscribable feeds and the supported server-side recurrence subset. A calendar
+export is different from a scheduler task or a provider calendar CRUD API.
 
-## Key Paths
-- Core package: `storage/framework/core/calendar-api/src/`
-- Package: `@stacksjs/calendar-api`
+## Single-event links and files
 
-## Export Functions
+~~~ts
+import { exportCalendarGoogle, exportCalendarIcs, exportCalendarIcsBody } from '@stacksjs/calendar-api'
 
-```typescript
-import { exportCalendarGoogle, exportCalendarIcs, exportCalendarOutlook, exportCalendarYahoo } from '@stacksjs/calendar-api'
-
-const event: CalendarLink = {
-  title: 'Team Meeting',
+const event = {
+  title: 'Team meeting',
   description: 'Weekly standup',
-  from: new Date('2024-06-15T10:00:00'),
-  to: new Date('2024-06-15T11:00:00'),
-  address: '123 Main St, City',
+  from: new Date('2026-10-12T17:00:00Z'),
+  to: new Date('2026-10-12T18:00:00Z'),
   timezone: 'America/New_York',
-  allDay: false
+  allDay: false,
 }
-
-// Generate URLs
 const googleUrl = exportCalendarGoogle(event)
-// → https://calendar.google.com/calendar/render?action=TEMPLATE&text=...
-
-const icsContent = exportCalendarIcs(event)
-// → BEGIN:VCALENDAR\nBEGIN:VEVENT\n...
-
-const outlookUrl = exportCalendarOutlook(event)
-// → https://outlook.live.com/calendar/0/deeplink/compose?...
-
-const yahooUrl = exportCalendarYahoo(event)
-// → https://calendar.yahoo.com/?v=60&title=...
-```
-
-## CalendarLink Interface
-
-```typescript
-interface CalendarLink {
-  title: string
-  description?: string
-  from: Date              // start time
-  to: Date                // end time
-  allDay?: boolean        // all-day event (ignores time)
-  address?: string        // location
-  timezone?: string       // IANA timezone (e.g., 'America/New_York')
-}
-```
-
-## Calendar Store Types
-
-```typescript
-interface CalendarStore {
-  day: number
-  month: number
-  year: number
-  currentMonthYear: string
-  datesOfMonth: number[]
-  currentWeekView: WeekDates[]
-}
-
-interface Events {
-  date: string
-  title: string
-  description?: string
-  month: number
-  day: number
-  year: number
-  time?: Time
-}
-
-interface Time { from: string, to: string }
-interface WeekDates { month: number, date: number }
-```
-
-## All-Day Events
-
-```typescript
-const allDayEvent: CalendarLink = {
-  title: 'Company Holiday',
-  from: new Date('2024-12-25'),
-  to: new Date('2024-12-25'),
-  allDay: true  // only date matters, no time component
-}
-```
-
-## Format Differences
-
-| Feature | Google | ICS | Outlook | Yahoo |
-|---------|--------|-----|---------|-------|
-| URL-based | Yes | No (file) | Yes | Yes |
-| Timezone | URL param | VTIMEZONE | URL param | URL param |
-| All-day | Date only | DATE value | isAllDay=true | st= format |
-| Description | details= | DESCRIPTION | body= | desc= |
-
-## Gotchas
-- Note package name is `@stacksjs/calendar-api` (not `@stacksjs/calendar`)
-- ICS export returns file content (not a URL) — serve as `.ics` download
-- All-day events use date-only format, ignoring time components
-- Timezone handling varies by provider — ICS includes VTIMEZONE block
-- Google Calendar uses UTC format in URLs
-- For task scheduling (cron), use `@stacksjs/scheduler` instead
-- ICS generates a unique UID per event for calendar deduplication
+const downloadUrl = exportCalendarIcs(event)
+const fileBody = exportCalendarIcsBody(event)
+~~~
+
+Google/Outlook/Yahoo exports return provider compose URLs. exportCalendarIcs
+returns a base64 data URL for an anchor; exportCalendarIcsBody returns raw
+text/calendar for a route or mail attachment. Do not serve the data URL string
+as if it were an ICS file. The single-event CalendarLink source type has from/to,
+title, required allDay and optional description/address/timezone; the root entry
+does not re-export that type. Infer a literal or read src/types.ts when extending
+the package.
+
+The older single-event generator has its own timezone/time-format rules and
+does not emit a VTIMEZONE block. Its UID derives from event timing/title, so
+editing those changes the UID. Do not promise subscription update semantics
+from a generated single-event link. Prefer the feed builder for stable records,
+escaping and folded lines.
+
+## Native subscribable feeds
+
+buildCalendarFeed({ name, events, timezone?, refreshInterval?, prodId? }) returns
+a complete VCALENDAR body. Use calendarFeedHeaders for the response and an
+authorized route for private calendars. CalendarFeedEvent has a stable uid,
+title/start/end plus optional allDay/description/location/url/rrule/sequence/
+updatedAt. Keep uid stable, increment sequence and update updatedAt on edits.
+
+The builder escapes ICS text and folds UTF-8 lines. Times are UTC; timezone is
+advisory calendar metadata. All-day feed end dates are inclusive input, converted
+to exclusive DTEND. Individual client refresh cadence is outside the framework's
+control, even when the feed declares a suggested interval.
+
+## Recurrence
+
+parseRRule(value) returns RecurrenceRule or null for unsupported frequency.
+expandRecurrence(rule, dtstart, windowStart, windowEnd) returns matching UTC
+start instants, capped defensively. Supported fields include DAILY/WEEKLY/
+MONTHLY/YEARLY, INTERVAL, COUNT, UNTIL, BYDAY and BYMONTHDAY. This is a subset;
+unknown fields are not a proof of full RFC conformance. Callers own timezone
+interpretation and DST policy. Calendar clients can expand a feed's raw rrule
+independently from the server subset.
+
+## Sources and evidence
+
+`storage/framework/core/calendar-api/src/index.ts`, types.ts, feed.ts,
+recurrence.ts and generators/ own the contracts. Retained tests:
+core/calendar-api/tests/calendar.test.ts and feed-recurrence.test.ts.
+For scheduled application work use stacks-scheduler; for a calendar extension's
+models/dashboard use its installed package metadata, not a fictional calendar
+API in this small export package.

package/ai/skills/stacks-charts/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: stacks-charts
+description: Use when rendering native dashboard charts, configuring scales or tooltips, or managing canvas chart lifecycle. Covers @stacksjs/charts and its Chart.js-compatible subset.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Native charts
+
+Import Chart from @stacksjs/charts. The package supplies a canvas renderer over
+ts-charts primitives with a compatibility-shaped configuration. It is not a
+promise of complete Chart.js plugin, animation or chart-type parity.
+
+## Lifecycle and supported behavior
+
+Mount a chart once its canvas is available; update data/options and call update,
+then destroy it when the view is removed. Use stx refs and lifecycle helpers
+rather than global DOM lookups in a template. Keep dimensions and device pixel
+ratio under the renderer's sizing contract to avoid compounding canvas resize.
+
+Line, bar, pie and doughnut have their native rendering paths. Radar currently
+falls back to a line layout. Advanced animation/plugin options are not a full
+implementation; inspect the chosen option before promising a visual effect.
+Chart.register/registerables are compatibility shims, not a third-party plugin
+registry. Scales, legend, colors, ticks and tooltip callbacks have native helpers.
+
+Read ChartConfig/ChartData/ChartOptions from the package types and reuse the
+dashboard's established chart integration. Test zero/negative values, sizing,
+dual axes where used, updates and destruction. Provide meaningful accessible
+text or tabular data alongside a canvas chart.
+
+Source: core/charts/src/{chart,types,colors,ticks,sizing}.ts. Retained tests:
+scales.test.ts, ticks.test.ts and sizing.test.ts.

package/ai/skills/stacks-chat/SKILL.md

@@ -438,13 +438,29 @@ All three drivers implement `sendWithRetry()`:
 
 ## Gotchas
 - The default driver for `send()` is `'slack'`, not auto-detected
-- Each driver has two modes: webhook (simpler) and bot token (richer, returns message IDs)
+- Slack and Discord support webhook or bot-token sends; Teams uses its Workflows webhook
 - Slack bot token mode uses `https://slack.com/api/chat.postMessage`, not a webhook
 - Discord webhook returns `204` on success with no body -- this is handled as success
 - Discord bot token mode uses `message.to` as the channel ID
 - Teams accepts only Workflows webhook URLs; the retired `webhook.office.com` connectors are refused
 - Teams uses `message.to` as fallback webhook URL if `config.webhookUrl` is not set
-- All drivers set `mrkdwn: true` or equivalent by default
+- Slack supports mrkdwn; Discord embeds and Teams Adaptive Cards use their own provider payloads
+
+## Results and native notification integration
+
+Direct send returns ChatResult, with success false for a handled provider failure;
+inspect it before persisting sent state. Awaiting a send only proves the promise
+settled. Webhook configuration does not replace ChatMessage's to/content or
+template fields. The generic notify chat channel supplies a body-only shape and
+does not normalize every structured transport failure, so use this package's
+direct API when application behavior depends on valid chat delivery.
+
+Settings resolve per send after app config readiness, with explicit configure
+overrides taking precedence. Retained request/config coverage lives under
+`storage/framework/core/chat/tests/`; it is distinct from live workspace
+delivery evidence. Inbox reads/archive operations use separate provider grants
+and optional native controllers; sending credentials do not automatically grant
+those operations.
 - Block Kit blocks are only built when `message.template` is set (Slack) or when `message.subject`/`message.template` is set (Discord/Teams)
 - `validateMessage()` requires both `to` and either `content` or `template`
 - The `handle()` callback runs before `onSuccess()` -- both results are merged

package/ai/skills/stacks-chief-of-staff/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+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:
+
+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/ai/skills/stacks-chief-of-staff/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## chief-of-staff
+
+Source: [skills/in-progress/chief-of-staff/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/in-progress/chief-of-staff/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`. This workflow is in progress upstream.
+
+Ported with Stacks skill names, canonical guidance, local-tracker fallback, TypeScript/Bun tooling, and conditional external actions.

package/ai/skills/stacks-chief-of-staff/PLAYBOOK.md

@@ -0,0 +1,42 @@
+> Adapted playbook. Read [the Stacks rules](../stacks-flow/ENGINEERING.md) first. Commit, push, publish, and tracker mutations are conditional on the user's authorization.
+
+
+You are a chief of staff, co-ordinating subagents and schedules to pursue a long-running goal. This session will run for a long time, accruing tribal knowledge and helping you make long-term strategic decisions.
+
+You are the Directly Responsible Individual for this goal. You are empowered to think much longer-term than you're used to. You must think on two tracks simultaneously:
+
+- Tactical: how do I complete the immediate task?
+- Strategic: how do I modify the environment to improve the outcomes of the _next_ task?
+
+## Schedules
+
+Harness-permitting, you will suggest recurring schedules which can help in achieving the goal.
+
+## Subagents
+
+All work should be done in subagents. Protect your context window.
+
+Use background agents so you can stay in active dialogue with the user.
+
+Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: research notes, previous commits, and others. Don't duplicate information already available via pointers.
+
+## Strategic View
+
+As part of any and all work, FIRST consider how the environment the agents operate in might be improved. Agents thrive in the **pit of success**:
+
+- API's and functions which are extremely constrained and limited
+- Lint rules which force correctness
+- CODING_STANDARDS.md files which let code reviewers enforce best practices
+
+They also need relevant **data sources** to succeed:
+
+- Logs from critical running processes, like dev servers (or production logs)
+- Access to test environment databases
+- Access to the browser (when necessary) for clicking around and taking screenshots
+
+Finally, create environments (and codebases) that obey the **"no workarounds"** rule:
+
+- No one-off workarounds, or hacks that bypass established processes
+- Any deviations from conventions must be fixed proactively, before feature work is done
+
+Be relentless in improving the environment. Use every user message as an excuse to search for these improvements.

package/ai/skills/stacks-chief-of-staff/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: stacks-chief-of-staff
+description: Pursue a long-running goal in a single session by co-ordinating subagents. Covers Stacks engineering workflows.
+disable-model-invocation: true
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Chief Of Staff
+
+Read [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md), then
+[PLAYBOOK.md](PLAYBOOK.md). The playbook preserves this workflow's decision
+criteria; the Stacks rules govern APIs, tooling, tracking, and authorization.
+
+Credit: adapted from Matt Pocock's `chief-of-staff` skill, MIT licensed.
+See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).
+
+This source is in upstream's in-progress collection. Use it explicitly as an
+optional workflow; do not install tooling or start background work merely
+because the skill is present.
+
+## Completion
+
+Produce the requested behavior or reviewable artifact and satisfy the
+playbook's completion criteria. Preserve existing decisions and user edits.
+Use the native Stacks skills for implementation and verification, and carry
+existing authorization through the workflow.

package/ai/skills/stacks-cli/SKILL.md

@@ -97,9 +97,9 @@ export default defineCommands({
 ```
 
 ### Registration Methods
-1. **Drop a file in `app/Commands/`** — auto-discovered, nothing else to do
-2. **Event listeners** — CLI events in `app/Listeners/Console.ts`
-3. **`app/Commands.ts`** — optional, for ordering / aliases / disabling
+1. **Drop a file in `app/Commands/`** - auto-discovered, nothing else to do
+2. **Event listeners** - CLI events in `app/Listeners/Console.ts`
+3. **`app/Commands.ts`** - optional, for ordering / aliases / disabling
 
 ## CLI Event Listeners
 
@@ -111,7 +111,7 @@ export default function(cli: CLI) {
   })
 
   cli.on('my:*', () => {
-    // Wildcard — matches my:anything
+    // Wildcard - matches my:anything
   })
 
   cli.on('unknown:!', () => {
@@ -145,7 +145,7 @@ console.log(dim('Subtle info'))
 ```
 
 ## CLI Commands
-- `buddy make:command [name]` — scaffold a new command
+- `buddy make:command [name]` - scaffold a new command
 
 ## Compiled Binaries
 
@@ -158,7 +158,23 @@ buddy build:cli                    # build CLI binary
 - Application commands go in `app/Commands/`, framework commands in `storage/framework/core/buddy/src/commands/`
 - Commands are auto-discovered from `app/Commands/`; `app/Commands.ts` is optional and additive
 - CLI events support wildcards (`*`) and default handlers (`!`)
-- The buddy CLI lazy-loads commands — not all load at startup
+- The buddy CLI lazy-loads commands - not all load at startup
 - Output formatting uses ANSI colors from `@stacksjs/utils`
 - Custom CLIs can be compiled to platform-specific binaries
-- The CLI framework is separate from buddy — buddy uses it internally
+- The CLI framework is separate from buddy - buddy uses it internally
+
+
+## Native terminal primitives
+
+The public `@stacksjs/cli` entry re-exports table, progress, tasks, note,
+getTerminalSize and isInteractive from `core/cli/src/terminal.ts`. Import
+dump/dd/echo from `@stacksjs/logging`, where those debug helpers live. Read their
+options/types before building a new terminal formatter or adding another CLI
+dependency. Commands can also use the native prompt, spinner, exec and signal
+helpers from the same package. A command file is discovered recursively; its
+handler's argument order comes from defineCommand, not a copied CAC action shape.
+
+Source evidence: `storage/framework/core/cli/src/index.ts`,
+`commands.ts` and `terminal.ts`; command discovery is owned by buddy's
+runtime registry. `buddy list` and `buddy <command> --help` are the
+authoritative command/flag inventory, including package-contributed commands.

package/ai/skills/stacks-cloud/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Cloud & Deployment
 
-Cloud infrastructure for Stacks, across three deploy targets, all driven through
+Cloud infrastructure for Stacks, across provider-specific deploy targets, all driven through
 `@stacksjs/ts-cloud`.
 
 ## Targets
@@ -204,7 +204,7 @@ export default [
     instance: 't3.micro',
     disk: 20,                  // GB
     os: 'ubuntu-20-lts-x86_64',
-    bun: '1.1.26',
+    bun: '1.3.0', // use the project's required/installed release
     database: { type: 'sqlite', name: 'stacks' }
   },
   // ... more servers
@@ -247,26 +247,25 @@ buddy domains:remove <domain>         # remove domain
 
 ## config/cloud.ts
 
-```typescript
-{
+~~~ts
+import type { CloudConfig } from '@stacksjs/types'
+import type { CloudConfig as TsCloudConfig } from '@stacksjs/ts-cloud'
+
+export const tsCloud: TsCloudConfig = {
   project: { name: 'my-app', slug: 'my-app', region: 'us-east-1' },
-  mode: 'server',             // 'server' | 'serverless'
-  environments: {
-    production: { domain: 'app.com', region: 'us-east-1' },
-    staging: { domain: 'staging.app.com' }
-  },
-  infrastructure: {
-    compute: { type: 't3.micro', spot: false },
-    loadBalancer: { enabled: true, type: 'application' },
-    ssl: { enabled: true },
-    dns: { provider: 'route53' },
-    storage: { buckets: [] },
-    cdn: { enabled: true },
-    cache: { enabled: false },
-    queue: { enabled: false }
-  }
+  cloud: { provider: 'hetzner' },
+  mode: 'server',
 }
-```
+
+const config: CloudConfig = { tenants: ['attached-project'] }
+export default config
+~~~
+
+Extend the named tsCloud object using its typed sites, environments and
+infrastructure options. The default Stacks wrapper holds surrounding settings
+such as tenant isolation. Provider configuration does not belong at an invented
+flat provider property. Preserve each site's gateway domains/path declarations
+when changing shared-box config.
 
 ## Infrastructure Stack (storage/framework/cloud/)
 
@@ -301,3 +300,21 @@ Stack naming: `{slugified-app-name}-cloud`
 - Environment mapping: `local` → `development`, others preserved
 - Deploy hooks run before/after deployment for custom logic
 - The cloud package has its own `package.json` with framework dependencies
+
+
+## Configuration and provider evidence
+
+The named `tsCloud` export in `config/cloud.ts` owns the provider and
+infrastructure options; the default export is Stacks' surrounding cloud config.
+The short infrastructure examples above show concepts, not a substitute for the
+installed TsCloudConfig type. Refer to that file and the provider's implementation
+before copying a server definition, mode or storage schema.
+
+Fly.io is another native deploy branch (Docker registry image and leased Machines),
+documented in `stacks-deploy`. The capability matrix at
+`core/config/src/capabilities.ts` only retains experimental Hetzner/SSH
+deploy contracts. Provider availability is separate from live conformance and
+rollback evidence; no registry entry should be invented to make the table look
+complete. Serverless resources, realtime topology and application queue drivers
+each have their own runtime contract. Provisioned infrastructure does not
+automatically wire the corresponding application adapter.

package/ai/skills/stacks-cms/PAGES.md

@@ -0,0 +1,70 @@
+# Block documents and public CMS pages
+
+The root `@stacksjs/cms` entry exports this surface alongside the legacy
+posts/authors/tags/comments namespace. Page documents are site-scoped; resolve
+the site's identity once at the route boundary and pass it explicitly.
+
+## Authoring a document
+
+```ts
+import { createPageDocument, registerDefaultBlocks } from '@stacksjs/cms'
+
+registerDefaultBlocks()
+const page = await createPageDocument(siteId, {
+  title: 'About us',
+  slug: 'about',
+  blocks: [],
+  status: 'draft',
+})
+```
+
+`SavePageDocumentInput` carries title, slug, parentId, template, blocks,
+metaDescription, status, scheduledAt, authorId and note. `slug: '/'` creates
+a root page. Child paths derive from the parent; path collisions are resolved
+within the site. An empty document is valid, but a block type must be registered
+before it is accepted. `fetchPageDocument(siteId, pageId)` returns the editable
+parsed document or null.
+
+`defineBlock` and `registerBlocks` define the type/schema/template registry.
+Application registrations can replace a default type. `validateBlocks` rejects
+unknown types, unknown props, missing required props and invalid values; it
+returns either validated blocks or structured errors. `parseStoredBlocks` is
+a defensive storage reader, not a substitute for write-time validation.
+
+## Updates, revisions and redirects
+
+`updatePageDocument(siteId, pageId, input)` validates blocks, snapshots the old
+document as a revision, recomputes changed paths, moves descendant paths and
+records redirects for old paths. Supply the complete intended document fields;
+do not assume every optional field behaves like a sparse PATCH. Invalid input
+raises `PageDocumentError` with status 422. A cross-site page id is refused.
+
+`fetchRevisions`, `storeRevision` and `restoreRevision` support history. A
+restore is itself undoable. `recordSlugChangeRedirects` and `resolveRedirect`
+provide the redirect layer. Route ids and CMS paths are distinct identifiers.
+
+## Publish, render and navigate
+
+Statuses are draft, published, scheduled and archived. `publishDuePages`
+publishes due scheduled rows; schedule that operation in an enabled scheduler
+instead of assuming a scheduled_at value wakes a worker by itself.
+
+`resolvePublishedPage(siteId, path)` resolves published content and normalizes
+a trailing slash. Draft/scheduled rows are invisible. `renderCmsPage` renders
+registered block templates, `sanitizeRichText` constrains editorial markup,
+and `cmsPageFallback`/`cmsNotFoundFallback` integrate with public serving.
+Existing coded views win over CMS fallback content. A page row is not a wildcard
+override of every application route.
+
+`fetchMenuTree` resolves page links to current paths and omits unpublished
+page links. Menus, redirects, revisions and page models all participate in CMS
+feature migration ownership. Public reads follow host-resolved sites; admin
+editing follows authenticated ownership, not an ambient public site guess.
+
+## Source and evidence
+
+Read `storage/framework/core/cms/src/pages/document.ts`, `blocks/registry.ts`,
+`public/resolve.ts`, `public/fallback.ts`, `publish/`, `menus/`, `revisions/`
+and `redirects/`. Retained tests are `src/tests/pages-document.test.ts`,
+`pages-crud.test.ts` and `public-serving.test.ts`, including tenant isolation,
+redirect flattening, document validation and real STX serving precedence.

package/ai/skills/stacks-cms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-cms
-description: Use when working with the CMS in a Stacks application - posts, authors, pages, categories, tags, comments, blog configuration, RSS feeds, or sitemaps. Covers @stacksjs/cms, CMS models, routes, and actions.
+description: Use when working with Stacks CMS posts, authors, block-document pages, revisions, menus, redirects, scheduled publishing, blog feeds, or public page serving. Covers @stacksjs/cms, site-scoped CMS models, routes, and actions.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -19,7 +19,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Source Files
 ```
 cms/src/
-├── index.ts              # CmsNamespace — top-level API
+├── index.ts              # CmsNamespace - top-level API
 ├── posts/
 │   ├── fetch.ts          # fetchById, fetchAll, fetchByStatus, fetchByCategory, fetchByAuthor
 │   ├── store.ts          # store, attach, detach, sync (pivot tables)
@@ -41,6 +41,12 @@ cms/src/
 
 ## CMS Namespace
 
+Enable/install the CMS feature through its supported lifecycle, then generate
+and review migrations for changed models. The legacy posts/authors/pages
+namespace below coexists with the document-page exports described in
+[PAGES.md](PAGES.md). For a real page editor or public CMS fallback, start with
+the validated document APIs rather than raw `pages` column writes.
+
 ```typescript
 interface CmsNamespace {
   posts: PostsModule
@@ -61,14 +67,14 @@ interface CmsNamespace {
 
 | Field | Type | Validation | Default |
 |-------|------|------------|---------|
-| title | string | required, 3-255 chars | — |
-| content | string | required, 10-1000 chars | — |
-| excerpt | string | optional, 10-500 chars | — |
-| poster | string | optional, valid URL | — |
-| views | number | — | 0 |
-| publishedAt | timestamp | optional | — |
+| title | string | required, 3-255 chars | - |
+| content | string | required, 10-1000 chars | - |
+| excerpt | string | optional, 10-500 chars | - |
+| poster | string | optional, valid URL | - |
+| views | number | - | 0 |
+| publishedAt | timestamp | optional | - |
 | status | enum | published/draft/archived | draft |
-| isFeatured | number | 0 or 1 | — |
+| isFeatured | number | 0 or 1 | - |
 
 ### Author
 - **Table**: `authors`, **Relationships**: `hasMany(['Post'])`, `belongsTo(['User'])`
@@ -241,12 +247,18 @@ Tune the look with custom properties (`--me-radius`, `--me-gap`, `--me-block-spa
 | `categorizable_models` | Polymorphic pivot: category ↔ model |
 
 ## Gotchas
-- **Polymorphic relations** — categories, tags, and comments use `*_type` fields to support multiple model types
-- **Post `content` maps from `body`** — the model attribute is `content` but the DB column mapping comes from `body`
-- **Author uses findOrCreate** — `PostStoreAction` auto-creates authors if they don't exist
-- **Post store auto-attaches** — creating a post with category/tag data automatically calls `attach()` on pivot tables
-- **Post update uses sync** — updating categories/tags uses `sync()` (detaches removed, attaches new)
-- **Views increment is atomic** — `PATCH /cms/posts/{id}/views` increments by 1
-- **RSS returns 20 items** — hardcoded to 20 most recent published posts
-- **Sitemap priorities** — posts 0.8, categories 0.6, blog homepage 0.9
-- **Comment status flow** — starts `pending`, can be approved, rejected (→ spam), or trashed
+- CMS document pages are scoped to an explicit site id. Pair them with
+  `stacks-sites`; background work has no implicit request site.
+- CMS post categories use `categorizables`. The Post model's
+  `belongsToMany(Category)` currently resolves commerce `categories`, a separate
+  id space (tracked in #2584). Use the CMS categorization module for CMS ids;
+  do not treat that relationship as an interchangeable alias.
+- **Polymorphic relations** - categories, tags, and comments use `*_type` fields to support multiple model types
+- **Post `content` maps from `body`** - the model attribute is `content` but the DB column mapping comes from `body`
+- **Author uses findOrCreate** - `PostStoreAction` auto-creates authors if they don't exist
+- **Post store auto-attaches** - creating a post with category/tag data automatically calls `attach()` on pivot tables
+- **Post update uses sync** - updating categories/tags uses `sync()` (detaches removed, attaches new)
+- **Views increment is atomic** - `PATCH /cms/posts/{id}/views` increments by 1
+- **RSS returns 20 items** - hardcoded to 20 most recent published posts
+- **Sitemap priorities** - posts 0.8, categories 0.6, blog homepage 0.9
+- **Comment status flow** - starts `pending`, can be approved, rejected (→ spam), or trashed