@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/skills/provision/SKILL.md

@@ -1,194 +0,0 @@
----
-name: provision
-description: Ship a Mantle project through its selected host, routing ChatGPT Sites to its integration guide and conventional Cloudflare Workers to production auth and provisioning.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/provision/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: package
-  projectionReason: Platform-specific deploy that handles production secrets; opt-in only.
----
-
-# Provision a Mantle Project
-
-Local cold start deliberately stops before this skill. Provision only after the
-user asks to create remote resources or ship production. This flow is for
-consumer-owned Cloudflare Workers. New direct-authored apps do not need Landing
-artifacts (`.mantle/launch-state.json`, `.mantle/handoff.md`, or a hosted-auth
-allocation). Treat any Landing handoff as **legacy/optional**. For a ChatGPT
-Site, use the installed `docs/handbook/chatgpt-sites/index.md` integration guide and
-the "Publish with Sites" steps in `docs/examples/host-chatgpt-sites/README.md`:
-request D1 and R2 on the Site, set `PUBLIC_ORIGIN` and `OWNER_EMAIL` in Sites
-settings, review the migration, then save and deploy a Sites version. Do not
-run `wrangler deploy` or require R2 S3 credentials merely because Sites exposes
-an R2 binding.
-
-## Source of Truth
-
-1. Read the actual provider config (`wrangler.jsonc` or `wrangler.toml`),
-   application entry and git remotes. Read legacy `.mantle/launch-state.json`
-   and `.mantle/handoff.md` only when present; they are optional leftovers from
-   Landing and must not be created as prerequisites for a new app.
-2. Read installed `@aotter/mantle*` versions from `package.json`.
-3. Use matching embedded docs under `node_modules/@aotter/mantle/docs/`.
-4. Never infer provider authority from launch state. Confirm the active GitHub
-   and Cloudflare accounts before changing them.
-
-Run the local gate first:
-
-```bash
-pnpm install --frozen-lockfile
-pnpm validate
-pnpm typecheck
-git status --short
-```
-
-## Resume From Observed State
-
-Do not branch on how the project was created. Verify these facts and skip
-completed work:
-
-1. `git remote get-url origin` confirms the GitHub repo.
-2. An HTTPS `PUBLIC_ORIGIN` that responds confirms the Cloudflare deploy.
-3. `/admin/sign-in` returning `503 setup_incomplete` means auth is not bound.
-   Use the recorded auth intent only to choose hosted or self-hosted setup;
-   live behavior is authoritative.
-
-If there is no remote, confirm the target account, create a private repo,
-commit, and push `main`. If there is no live Worker, confirm the Cloudflare
-account, prefer an available connector, or use `pnpm exec wrangler login` with
-the user's agreement, then run `pnpm deploy`.
-
-Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
-commit and push non-secret changes. Reuse any repo or Worker already created.
-Do not recreate Landing artifacts for a new direct-authored app. Workers Builds
-is optional after a direct deploy.
-
-When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
-provider's OAuth callback together, then redeploy. Do not patch `site_config`
-directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
-
-## Choose Auth
-
-- **Self-hosted email OTP:** use the application's production transactional-email sender. Replace `ConsoleEmailSender`; never deploy it.
-- **Self-hosted GitHub OAuth — free fallback:** use when the application has no email provider. Configure the owner's per-site GitHub OAuth App and Worker secrets using the steps below.
-- **Mantle hosted auth — paid, legacy/optional:** use only when a **legacy
-  Landing handoff** already records a hosted allocation and client
-  configuration. New direct-authored apps do not get this from Core. Mantle
-  Platform operates the identity provider; do not ask the user for a per-site
-  GitHub OAuth App.
-
-Configure only the selected mode. Core deliberately rejects partial or mixed
-hosted/self-managed bindings with `503 setup_incomplete`.
-
-Do not claim that hosted auth can attach to an arbitrary local repo unless a
-legacy Landing handoff already supplies that configuration.
-
-For the exact boundary, read
-`node_modules/@aotter/mantle/docs/auth-hosting-model.md`.
-
-## Self-hosted email OTP
-
-Keep the application's custom `createAuth()` factory, replace
-`ConsoleEmailSender` with its production `EmailSender`, and retain
-`bootstrapOwner: { match: "email", value: <owner email> }`. Store sender
-credentials and `BETTER_AUTH_SECRET` as Worker secrets, put `PUBLIC_ORIGIN` in
-non-secret vars, deploy, then verify that the owner receives an OTP at
-`/admin/sign-in`. If there is no production email provider, use GitHub OAuth
-below instead of deploying console delivery.
-
-## Self-hosted GitHub OAuth
-
-1. Ask the user to create a GitHub OAuth App:
-
-- Homepage URL: `<worker-url>`
-- Authorization callback URL: `<worker-url>/api/auth/callback/github`
-- Device Flow: unchecked
-
-2. Put non-secret values in `wrangler.toml`:
-
-- `MANTLE_AUTH_MODE = "self-managed"`
-- `PUBLIC_ORIGIN`
-- `GITHUB_CLIENT_ID`
-- `ADMIN_GITHUB_LOGIN`
-- correct Worker `name`
-
-Remove `MANTLE_HOSTED_AUTH_ISSUER` and `MANTLE_HOSTED_AUTH_CLIENT_ID` if they
-were present for a hosted allocation.
-
-3. Keep the Client Secret out of chat. Prefer a Cloudflare connector for
-   secrets; otherwise use hidden shell input:
-
-```bash
-read -rsp "GitHub OAuth client secret: " MANTLE_GITHUB_CLIENT_SECRET && printf "\n"
-printf '%s' "$MANTLE_GITHUB_CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET
-openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
-unset MANTLE_GITHUB_CLIENT_SECRET
-```
-
-Set `BETTER_AUTH_SECRET` once and preserve it. Rotating it invalidates existing
-sessions.
-
-4. Commit and push only non-secret config, then redeploy:
-
-```bash
-git add wrangler.toml AGENTS.md
-git commit -m "mantle: wire production auth"
-git push
-pnpm deploy
-```
-
-## Hosted Auth (legacy Landing)
-
-Skip this section unless a legacy Landing handoff is already present. New
-direct-authored apps use self-hosted email OTP or GitHub OAuth above.
-
-Follow that handoff and its client configuration. Hosted configuration remains
-in landing-managed Cloudflare Worker bindings. Verify:
-
-- `MANTLE_AUTH_MODE = "hosted"`;
-- `MANTLE_HOSTED_AUTH_ISSUER` is the HTTPS root issuer;
-- `MANTLE_HOSTED_AUTH_CLIENT_ID` is the same-origin `/clients/<id>` URL;
-- `PUBLIC_ORIGIN` and `ADMIN_GITHUB_LOGIN` are set;
-- `BETTER_AUTH_SECRET` exists as a Worker secret;
-- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are absent.
-
-Hosted clients use PKCE and have no client secret. Do not write secrets into
-`wrangler.toml`.
-
-Verify that admin sign-in redirects to Mantle Hosted Auth and Staff MCP
-authenticates, then skip the self-hosted flow.
-
-## Smoke Test
-
-- public home route;
-- `/admin/sign-in`;
-- selected admin sign-in path;
-- `/mcp/staff` with an agent client when available;
-- one type-specific core workflow.
-
-Media uploads are optional. Configure R2 only when the owner asks for
-staff-managed files; then read
-`node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md`.
-
-## Handoff
-
-Return:
-
-- public URL;
-- admin sign-in URL;
-- Staff MCP URL;
-- operator setup URL:
-  `https://mantle.tools/connect?site=<url-encoded-worker-url>`;
-- remote resources created or reused;
-- auth mode and any intentionally deferred setup.
-
-## Don't
-
-- Don't create remote resources before the user asks to ship.
-- Don't ask for a Cloudflare API token in the base flow.
-- Don't commit provider secrets.
-- Don't require R2 for first production.
-- Don't invent a second provision orchestrator.
-- Don't use `/admin/auth/github/callback`; the callback is
-  `/api/auth/callback/github`.

package/skills/theme/SKILL.md

@@ -1,77 +0,0 @@
----
-name: theme
-description: Apply brand and visual direction in a Mantle application using its repo-owned theme and UI contracts.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/theme/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: project
----
-
-# Mantle Theme
-
-Theme work is project-owned source editing. Use the actual frontend and its
-tokens/recipes; Core does not install a default home page or UI tree.
-
-For requests to change the Admin console, first read installed
-`node_modules/@aotter/mantle/docs/handbook/guides/admin-ui.md` and use the
-develop skill. Labels, widgets, list columns, filters and actions may already
-be manifest-driven. Visitor CSS does not style the prebuilt Admin SPA, and
-`uiSchema` does not accept arbitrary CSS, components or layout keys.
-
-## First Read
-
-1. `.mantle/handoff.md` and `.mantle/recipes/` if present.
-2. `styles/`, `components/`, `src/web/`, `src/theme*`, and UI-library config
-   if present.
-3. A vendored UI palette's manifest and license, if present.
-4. The manifest directory selected by project scripts to understand which
-   content shape drives the public UI.
-
-## Ownership
-
-- Use the actual token contract (for example `styles/globals.css`) when present.
-  Check its light/dark values before changing components.
-- `components/` is the runtime-facing component surface when present.
-  `src/web/` is project-owned composition; put new sections there.
-- `public/site-icon.svg` and `public/site-icon.png` are one site identity.
-  Keep both listed in the actual entry/config `siteDefaults.icons`: PNG first as
-  the 64x64 compatibility rendition, then SVG as the editable `any` size source.
-  The same list drives browser favicons, Admin chrome, and MCP
-  `serverInfo.icons`; do not edit generated files under `public/_mantle/`.
-- If the project includes a vendored UI reference palette, treat it as
-  offline source material and provenance, not runtime source. Copy only a
-  needed primitive or block into the project's runtime directories, or
-  fork/wrap it under `src/web/sections/`; do not import the palette from
-  Worker or runtime code.
-
-## Work
-
-- Use existing tokens, CSS, components, and installed dependencies first.
-- When replacing the site mark, regenerate PNG from the same SVG artwork so
-  every surface presents the same identity. Check it at the Admin's 28px slot
-  in both light and dark themes; a single high-contrast rendition is preferred
-  over theme-specific variants unless the artwork genuinely needs both.
-- For a standard hero image, set the section's `image: { src, alt }`; use
-  `showImage: false` for text-only hero/content blocks. Put non-image media in
-  a project-owned section.
-- Keep accessibility basics: semantic HTML, focus states, contrast, and
-  keyboard reachability. Against a non-default background, check
-  `--foreground-muted` and `--primary`, not only `--foreground`; keep normal
-  text at 4.5:1 or better.
-- Do not require registry access for a project that already vendors UI source.
-- Add UI dependencies only when existing source cannot cover the requested
-  change.
-
-## Check
-
-```bash
-pnpm validate
-pnpm typecheck
-pnpm dev
-```
-
-If utility classes changed, rebuild `styles/generated.css` with the project's
-`build:styles`, `check`, or `dev` script. Remove routes/imports for replaced
-assets or styles, then visually verify light/dark contrast and responsive
-behavior before calling the work done.

package/skills/update/SKILL.md

@@ -1,51 +0,0 @@
----
-name: update
-description: Review and upgrade Mantle SDK dependencies and project-local skills while preserving application source, provider identities and plugin lockfiles.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/update/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: project
----
-
-# Mantle Update
-
-Upgrade SDK dependencies deliberately; never overwrite application-owned code.
-The old Starter bundle comparison command `mantle update` is removed. This
-skill remains the version-matched upgrade workflow, not a replacement CLI.
-
-1. Inspect git status, package.json, lockfile, actual project scripts and
-   installed versions. Preserve unrelated local changes. Read plugin locks
-   and legacy `.mantle` metadata if present; they are context, not required.
-2. Select an explicit target release and read that version's GitHub release
-   notes. Installed docs live under `node_modules/@aotter/mantle/docs/`;
-   `handbook/releases/index.md` is a stable-release index, so a prerelease
-   need not appear there. Do not use the old package's docs as the new API contract.
-   Do not resolve new Starter refs or compare the project to a baseline
-   template.
-3. Update only selected `@aotter/mantle*` dependencies to the same exact target
-   version, preserving dependency sections. Use the package manager to update
-   the lockfile; inspect the dependency diff and required peer changes.
-4. Remove scripts that invoke retired create/bundle-update commands. Keep all
-   application manifests, handlers, routes, theme, Worker/D1/KV names, origins,
-   provider bindings, secrets, and legacy metadata. Apply API migration edits
-   individually; do not copy the reference consumer over a real application.
-5. Use the upgraded package to regenerate machine-owned bindings and project
-   its skills, then run the application's validation, types and tests:
-
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-pnpm exec mantle validate
-```
-
-Read the refreshed `mantle-develop` skill and the upgraded package's embedded
-docs before continuing application edits.
-
-Start the local application and test its actual routes, including configured
-auth behavior. Review the final source/lockfile/generated diff; unexpected
-provider or user-source changes block completion. Provider credentials must
-never enter git or logs. Report exact old/new versions, checks, and remaining
-migration work. A dependency update does not authorize a production deploy.