@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/auth-hosting-model.md

@@ -1,166 +0,0 @@
-# Auth Hosting Model
-
-Mantle treats authentication as a runtime capability, not a paywall on
-basic login. The split is:
-
-- **Mantle SDK** gives every generated site the primitives needed to
-  run its own auth.
-- **Mantle's conventional Cloudflare adapter** runs the generated site's
-  selected self-hosted or Mantle Platform hosted client configuration.
-- **The application owner/host** declares the explicit auth mode and provider
-  configuration.
-- **Mantle Platform** can sell hosted identity, provider setup, email,
-  and billing convenience for site owners who do not want to operate
-  those pieces.
-
-This document is the source of truth for the product and SDK boundary.
-Do not duplicate this model in starter handoff copy or landing prose;
-link here and keep downstream docs short.
-
-## Free Self-Hosted Auth
-
-A free Mantle site can run every login method the SDK exposes through
-`createAuth()`:
-
-- social OAuth providers supported by Better Auth;
-- provider-specific options through Better Auth's native `socialProviders` types;
-- email OTP;
-- magic link;
-- passkey or another Better Auth method through the raw `plugins` path when the
-  application owns its callback and UI;
-- first-party same-domain or same-parent-domain SSO when the site owner
-  controls every participating subdomain.
-
-The site owner supplies their own provider client ids/secrets,
-transactional email sender, DNS, cookie policy, and operational
-maintenance. Mantle must not block self-hosted login behind a paid
-feature flag.
-
-## Hosted Platform Auth
-
-Paid hosted auth is a convenience and operations product. The value is
-that Mantle Platform can:
-
-- hold OAuth provider configuration;
-- hold email provider credentials;
-- send OTP and magic-link email;
-- manage deliverability and provider rotation;
-- register generated sites as clients;
-- check billing/license entitlements before hosted capabilities are
-  enabled;
-- expose a stable hosted identity broker for generated sites.
-
-The generated site still owns local grants, member records, content,
-orders, forms, and legal copy. Platform returns identity. The site maps
-that identity into `ctx.user`, `ctx.staff`, and its own grant model.
-
-## Same Parent Domain SSO
-
-When the apps share a parent domain that the same party controls, SSO
-can use browser cookies:
-
-```ts
-createAuth({
-  // ...
-  trustedOrigins: ["https://mantle.tools", "https://www.mantle.tools"],
-  cookiePrefix: "mantle-platform",
-  crossSubDomainCookies: {
-    enabled: true,
-    domain: "mantle.tools",
-  },
-});
-```
-
-Use this only for a trusted first-party app family, for example
-`platform.mantle.tools` and `mantle.tools`.
-
-`cookiePrefix` is required whenever more than one Better Auth app can
-write cookies under the same parent domain. Without it, Platform and
-Landing can overwrite each other's default Better Auth cookie names.
-
-`trustedOrigins` is a Better Auth auth-flow trust list. It is not a
-general API CORS policy and must not be documented as one.
-
-## Customer Domain SSO
-
-Shared cookies do not work across different registrable domains:
-
-```text
-platform.mantle.tools  ->  customer.com
-```
-
-Browsers will not send a `mantle.tools` cookie to `customer.com`. For a
-customer-owned domain, hosted auth must use OAuth/OIDC:
-
-```text
-customer.com/login
-  -> platform.mantle.tools/api/auth/oauth2/authorize
-  -> user signs in with Platform-supported methods
-  -> customer.com/api/auth/callback/mantle
-  -> customer.com verifies the authorization response
-  -> customer.com creates its own local session
-```
-
-That local session is the customer's site session. Platform remains the
-identity broker and entitlement authority; it does not become the
-customer site's member database or authorization system.
-
-## Landing Provisioning Split
-
-Landing should branch before GitHub or Cloudflare side effects:
-
-- **Continue free**: commit a self-hosted auth-ready site with docs,
-  env placeholders, and the user's own provider setup path.
-- **Use hosted auth**: check Platform entitlement, register the site as
-  a Platform auth client, and commit the generated site's Platform auth
-  client config.
-
-Landing can probe Platform staff/session state, but provisioning's
-GitHub OAuth token is still Landing-owned unless a separate token
-handoff design is introduced.
-
-The conventional hosted-auth client wiring belongs in Core's Cloudflare
-adapter. Applications declare its environment bindings; a provisioning host supplies an
-allocated client. A site can still replace Auth construction through
-`createMantleWorker({ auth })` when it needs a different curated identity
-design. Core continues to own the normalized manifest/runtime credential
-vocabulary (`ctx.user`, `ctx.staff`, `ctx.auth`) and guard orchestration.
-
-## API and MCP Authorization
-
-Login hosting and business API authorization are related but separate. Core
-provides a normalized verified-credential context (`ctx.auth`), closed scope
-predicates, one Cloudflare consumer credential resolver seam, and a
-Procedure-backed guard that REST and MCP both execute. A generated site owns
-API keys, personal tokens, grants, transactions, subscriptions, and the guard
-handler that checks current business state.
-
-Mantle Platform may be the identity or OAuth token authority for a hosted
-flow. That does not make token claims the generated site's live membership or
-entitlement authority. The target site's guard reads its authoritative state
-on every call. See [API and MCP authorization](examples/cf-primitives-guarded-api.md) for
-the exact public API and four consumer examples.
-
-## SDK Surface Rule
-
-Mantle owns only integration fields with a real Mantle use case. Method
-configuration uses Better Auth's official provider/plugin option types; do not
-copy those unions or add a generic `Partial<BetterAuthOptions>` deep merge.
-
-The current first-party SSO use case justifies these optional fields on
-`CreateAuthConfig`:
-
-- `trustedOrigins`
-- `crossSubDomainCookies`
-- `cookiePrefix`
-
-The cross-site API use case additionally justifies these fields and facades:
-
-- native generic OAuth `authorizationUrlParams`, `tokenUrlParams`, and
-  `refreshTokenParams` for RFC 8707 `resource`
-- OAuth provider `resources` and the curated `mcpResource`
-- `Auth.getProviderAccessToken(request, providerId)`
-- `Auth.verifyOAuthAccessToken(tokenOrRequest, { audience, scopes })`
-
-Generic OAuth providers use Better Auth 1.7's official `GenericOAuthConfig`,
-standard social sign-in and `/api/auth/callback/:id` path.

package/docs/cloudflare-low-level-composition.md

@@ -1,5 +0,0 @@
-# Cloudflare low-level composition
-
-This guide moved into the handbook: [`docs/handbook/cloudflare/low-level-composition.md`](handbook/cloudflare/low-level-composition.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/consumer-onboarding-audit.md

@@ -1,65 +0,0 @@
-# Consumer onboarding audit for 0.1.3
-
-Scope: source skill install → pinned npm package → CLI → generated skills and
-handbook → application manifest and Admin customization. This is maintainer
-evidence, not a release announcement. Baseline: develop `b90cebbd`, package
-version `0.1.3-alpha.5`; the package version alone does not identify unreleased
-commits on develop. Tracking: [#1042](https://github.com/aotter/mantle/issues/1042).
-
-## Clean source install
-
-Executed in an empty temporary directory:
-
-```sh
-npx --yes skills add aotter/mantle --skill install --agent codex --yes
-```
-
-Observed output: repository cloned, **7 skills found**, **1 selected**, copied
-to `./.agents/skills/install`. `skills-lock.json` records source `aotter/mantle`,
-source type `github`, and source path `skills/install/SKILL.md`. The installed
-file's hash in that lock was
-`8a6fd26aea97ae8bdf3e05fef22196c247b3f95aa049204a6ac51259d87e4e29`.
-No SDK, handbook or application is installed by that command. The explicit
-Codex and noninteractive flags make the audited destination reproducible;
-other selected agents/global scope can use another destination.
-
-This source install follows the repository's default ref. It does not test the
-unreleased edits in this PR or establish an npm version. The packed-consumer
-check below tests this branch's shipped instructions separately.
-
-## White-box path and fixes
-
-| Stage / owner | Finding before this change | Correction |
-|---|---|---|
-| README → external skills installer | Prompt told the agent to read `skills/install/SKILL.md` and `docs/agent-prompts.md`, neither installed there. | Read the installer-reported destination, then the installed SDK's embedded docs. |
-| `skills/install/SKILL.md` | Bootstrap Git instructions did not explicitly hand off to the installed package's own install skill; `docs/...` root was implicit. Host interview was repeated. | Explicit package-root resolution and version authority; ask only for missing requirements. |
-| Install → CLI | It was possible to try the local CLI before installing Core; `generate` in an empty directory fails rather than creating a project. | Spell out package installation before CLI and manifest authoring before generation. |
-| Quickstart versions | Floating `latest` dependency examples contradicted exact-pin advice. | Resolve the requested channel once and save exact Mantle versions before the first build. |
-| `mantle skills` | Correctly projected four project skills, but success output did not tell the agent what to read next. | Print the projected develop skill and installed handbook entry. Document overwrite, drift and opt-in behavior. |
-| `sync-package-docs.mjs` → npm `files` | Docs and all seven skills already shipped; presence checks did not protect the new entry paths or exercise projection from the tarball. | Assert handbook/skill files and byte-identical `.agents`/`.claude` projection in the existing packed-consumer check. |
-| View concepts → grammar/runtime | Concepts denied internal Views and recommended SQL for every new View; reference `surface` table omitted `internal`. SQL admission text was stale. | Match implemented surfaces, typed declarative reads, SQLite admission sandbox and native-dialect limits. |
-| Manifest reference | View's allowed spec keys omitted `cache`; Schema list-column prose omitted native columns. | Reconcile with parser and Admin UI checker. |
-| Plugin/update skills | Assumed conventional source paths, missed regeneration after plugin manifest edits, and treated every View as publicly callable. | Use actual project paths, regenerate the plan, verify the declared surface and distinguish stable index from target prerelease docs. |
-| Feature discovery | No task-to-manifest capability map or usable human entry; reference was buried after host-specific sections. | Add overview, capability table and task guides; move reference before host guides without breaking existing URLs. |
-| Typed query discovery | APIs existed but lacked a complete internal-View calling example or clear reader authorization distinction. | Explain generated params/results, runtime `result` versus REST `data`, SQL `unknown`, indexed reader limits and plan-based emission. |
-| Admin requests → theme/develop skills | Theme skill targeted visitor source; no routing from an Admin request to manifest-controlled presentation. | Route to Admin guide, with Schema/View/Procedure rendering table and supported customization ceiling. |
-| Auth operations | Store-bound session cache behavior existed in code/ADR but was missing from the handbook. | Explain store identity, preparation order and KV propagation limits. |
-
-## Verification and regression coverage
-
-- `packages/mantle-spec/test/handbook-contract.test.ts`: complete handbook YAML
-  examples parse and validate; navigation covers pages; relative links resolve.
-- `packages/mantle/test/cli/generate.test.ts`: extracts the new internal-View
-  YAML and TypeScript directly from the handbook, generates bindings and runs
-  strict TypeScript checking on the real example.
-- CLI surface/projection tests assert the concrete next-read destinations;
-  existing drift checks verify `--check` is read-only.
-- `scripts/check-optional-packages.mjs`: packs and installs the actual Core
-  tarball, checks embedded entry pages/skills, runs `skills` and `skills --check`,
-  and compares each project projection byte-for-byte with the installed package.
-- Repository gate: `pnpm check`. Exact execution results and any environment
-  limitations are recorded in the PR, rather than frozen as a future guarantee.
-
-No npm publish, tag, deployment or grammar change is part of this audit. Source
-skill consumers receive the corrections only once they reach the installed Git
-ref; npm consumers receive them only in a package built from the corrected tree.

package/docs/deferred-lifecycle-queues.md

@@ -1,5 +0,0 @@
-# Deferred lifecycle hooks on Cloudflare Queues
-
-This guide moved into the handbook: [`docs/handbook/cloudflare/deferred-hooks-queues.md`](handbook/cloudflare/deferred-hooks-queues.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/design-atoms.md

@@ -1,16 +0,0 @@
-# Manifest reference has moved
-
-The version-matched [handbook](handbook/reference/manifest.md) is the single
-grammar reference. This compatibility URL contains no duplicate grammar.
-
-- [Four atoms](handbook/concepts/four-atoms.md)
-- [Schema](handbook/reference/schema.md)
-- [View](handbook/reference/view.md)
-- [Procedure and builtin handlers](handbook/reference/procedure.md)
-- [Trigger](handbook/reference/trigger.md)
-- [Authorization](handbook/reference/authorization.md)
-- [Diagnostics](handbook/reference/diagnostics.md)
-
-Builder consumers must load these pages from the same installed SDK as their
-runtime. The old Markdown section headings are retired; see
-[#837](https://github.com/aotter/mantle/issues/837).

package/docs/design-references/editorial-blog-2026-05-05.md

@@ -1,218 +0,0 @@
-# Editorial Blog Design Reference (2026-05-05)
-
-This document preserves the visual system from the retired
-`blog-editorial-2026-05-05` starter. The runnable starter was removed because
-it looked like a maintained template, but the design work is still useful as a
-reference for future themes.
-
-Use this as a design specimen, not as implementation guidance. Apply it through
-the version-matched `mantle:theme` workflow and the generated project's owned
-theme paths, such as `styles/globals.css`, `components/`, and `src/web/`.
-
-## Design Thesis
-
-The direction was a quiet literary journal: warm paper, dark ink, a narrow
-reading measure, editorial serif typography, and one vermilion accent. The UI
-avoided dashboard styling and treated the site chrome as magazine furniture:
-small caps, rules, careful spacing, and minimal controls.
-
-The design was intentionally opinionated. That is why it should be reused as a
-theme preset or design prompt, not shipped as the default blog starter.
-
-## Visual Tokens
-
-| Token | Light | Dark | Role |
-|---|---:|---:|---|
-| `paper` | `#f6f1e7` | `#1a1814` | Page background |
-| `ink` | `#1a1814` | `#f1ebdf` | Primary text |
-| `rule` | `#d4c8b3` | `#3d342a` | Hairlines, subtle borders |
-| `rule-strong` | `#3d342a` | `#5a4d40` | Form underlines, stronger separators |
-| `mute` | `#7a6d5e` | `#9a8d7e` | Metadata and secondary copy |
-| `accent` | `#a3331f` | `#e6594a` | Links, drop caps, error states, preview banner |
-| `accent-soft` | `#c9614a` | `#c9614a` | Secondary accent |
-| `selection` | `#f0d6a3` | `#4a3520` | Text selection background |
-
-Layout tokens:
-
-| Token | Value | Role |
-|---|---:|---|
-| `measure` | `38rem` | Main article measure |
-| `main max-width` | `48rem` | Single-column shell, slightly wider than the article |
-| `gutter` | `clamp(1.25rem, 4vw, 3rem)` | Responsive page padding |
-| `base font size` | `18px` | Reading-first default |
-| `line height` | `1.65` | Long-form prose rhythm |
-
-## Typography
-
-The type system used four families:
-
-| Use | Font stack |
-|---|---|
-| Display | `Fraunces`, `Noto Serif TC`, `Source Serif 4`, `Georgia`, `serif` |
-| Body | `Source Serif 4`, `Noto Serif TC`, `Georgia`, `serif` |
-| Mono/meta | `JetBrains Mono`, `ui-monospace`, `SF Mono`, `Menlo`, `monospace` |
-| CJK fallback | `Noto Serif TC` |
-
-Important behaviors:
-
-- Body text enables `kern`, `liga`, and `onum`.
-- Headings use Fraunces variable optical sizing with `opsz` and `SOFT`.
-- `h1` scales from `2.2rem` to `3.4rem`; hero `h1` scales up to `4rem`.
-- Metadata uses JetBrains Mono at `0.75rem`, uppercase, and `0.04em` tracking.
-- Paragraphs indent after the first paragraph with `p + p { text-indent: 1.5em; }`.
-- Post bodies reset the first paragraph indent and add a vermilion drop cap.
-
-## Page Chrome
-
-Header:
-
-- Sticky top header with a one-pixel rule.
-- Warm translucent paper background using `color-mix`, `saturate(140%)`, and
-  `blur(10px)`.
-- Wordmark uses display serif and inserts a vermilion middle dot between the
-  first word and the remaining brand words.
-- Navigation is centered, uppercase, display serif, and tracked at `0.18em`.
-- Current nav item is shown by a one-pixel underline in `ink`; hover uses
-  `accent`.
-
-Controls:
-
-- Language and theme are small popovers in the header.
-- Popover trigger typography follows mono/meta styling.
-- The language trigger shows a globe icon, full locale label, and chevron.
-- The theme trigger is icon-only and supports system, light, and dark.
-- Menu items use `menuitemradio` semantics and show a check icon for the active
-  value.
-- Popovers close on outside click and `Escape`.
-
-Footer:
-
-- One-pixel top rule.
-- Mono text at `0.75rem`.
-- Left side shows `site.brand` and `site.description`.
-- Right side links to `mantle`.
-
-## Templates
-
-Home:
-
-- Starts with a `hero` block: mono eyebrow, large display title, muted intro,
-  and markdown body.
-- Recent posts appear below the hero as an `entry-list`.
-
-Post:
-
-- Uses a narrow `article` measure.
-- Header contains optional publish date and title.
-- Optional cover image is bordered by `rule`.
-- Body markdown supports headings, blockquotes, inline code, code blocks, and
-  lists.
-- First body paragraph gets an editorial drop cap.
-
-Post list:
-
-- Reuses the hero grammar with an index eyebrow.
-- Entries render as a two-column grid: fixed `7rem` date rail plus flexible
-  title/excerpt column.
-- On narrow screens, entries collapse to one column.
-
-Page:
-
-- Same article shell as posts.
-- Uses page `intro` as muted mono metadata under the title.
-- `about` and `contact` slugs drive active nav hints.
-
-Contact:
-
-- Article intro and body are followed by a vertical form.
-- Field labels are uppercase mono.
-- Text inputs use underline-only styling; textarea uses a bordered box.
-- Submit button uses display serif, uppercase tracking, and an inverted
-  `ink`/`paper` fill.
-- Cloudflare Turnstile is mounted explicitly so it can re-render when the site
-  theme changes.
-
-404:
-
-- Centered block with a huge display-serif `404` glyph in `accent`.
-- Copy follows the same i18n bundle pattern as the rest of the chrome.
-
-## Interaction Model
-
-Theme preference is a three-way choice:
-
-- `system`: no stored value, follows `prefers-color-scheme`.
-- `light`: explicit localStorage override.
-- `dark`: explicit localStorage override.
-
-A bootstrap script runs in `<head>` before paint to avoid theme flash. Runtime
-theme changes dispatch a `mantle:theme` event. The contact page listens to that
-event and re-renders Turnstile with the resolved light/dark value.
-
-Language switching rewrites the leading locale segment in the current path. It
-does not translate content itself; it navigates to the equivalent route under
-the selected locale.
-
-## I18n Surface
-
-The archived design included two UI bundles:
-
-| Locale | Label |
-|---|---|
-| `en` | `English` |
-| `zh-TW` | `繁體中文` |
-
-The bundles covered:
-
-- Header labels: posts, about, contact.
-- Theme labels: auto, light, dark.
-- Language aria label.
-- Home and post-list eyebrows.
-- 404 title, body, and return link.
-- Contact labels, submit states, success message, and error prefix.
-
-Content translations were intentionally separate from UI chrome translations.
-Posts and pages came from CMS entries; nav and form labels came from the local
-i18n bundles.
-
-## Icons
-
-The icon system was deliberately tiny:
-
-- Inline SVG strings injected by templates.
-- Monochrome `currentColor` stroke.
-- Default size `16`.
-- Default stroke width `2`, with check icons at `2.5`.
-- No runtime icon dependency until the set grows beyond roughly 20 icons.
-
-The archived set included `sun`, `moon`, `monitor`, `globe`,
-`chevron-down`, `check`, `menu`, and `x`.
-
-## Reuse With The Current Theme Stack
-
-Map the design into the maintained starter layers instead of reviving the old
-runnable starter:
-
-| Current layer | What to reuse |
-|---|---|
-| L1 tokens | Colors, font stacks, measure, gutter, base rhythm |
-| L2 components | Popover styling, entry list, post body, drop cap, contact form |
-| L3 slots | Header, footer, language switcher, theme switcher |
-| L4 templates | Home, post, post list, page, contact, 404 composition |
-
-Do not copy the old package metadata, Wrangler config, fixtures, workspace
-dependencies, or smoke tests. Those belonged to the removed runnable starter and
-will drift from the maintained SDK packages.
-
-## If Reviving This Direction
-
-Revive it as one of these:
-
-- A documented visual preset selectable during agent seeding.
-- A project-owned theme preset applied through `mantle:theme`.
-- A generated design prompt that tells the provisioning agent how to style a
-  user's own brand.
-
-Do not bring it back as a runnable starter in this SDK repository. Agents treat
-runnable code as current product surface, so the preserved design belongs only
-in this reference.

package/docs/direct-authoring.md

@@ -1,5 +0,0 @@
-# Direct authoring
-
-This guide moved into the handbook: [`docs/handbook/start/project-and-cli.md`](handbook/start/project-and-cli.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.