@aotter/mantle 0.1.3 → 0.1.5-alpha.1

package/docs/skills/integrate/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: integrate
+description: Integrate Mantle into an existing application. Use when the application has its own code, routes, storage or deployment and the owner wants to add Mantle, replace part of it, or rebuild with Mantle while migrating frontend and data.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/integrate/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: package
+  projectionReason: Existing-project migration is opt-in; a fresh generated app does not need this brief.
+---
+
+# Integrate Mantle into an existing application
+
+Work in the target application. Read its installed `@aotter/mantle` version,
+CLI help and package-local docs before editing. If Mantle is absent, inspect
+the application first, then install an exact SDK version only after choosing an
+integration strategy. Use the installed version's contract; do not copy
+`develop` branch examples into an older consumer.
+
+## Inspect and decide
+
+Map the actual entry points, router, frontend, auth, storage, data volume and
+relationships, deployment pipeline, URLs, background jobs and existing tests.
+Identify which behavior the owner wants Mantle to own and what must remain
+stable. Compare three approaches using the application's evidence:
+
+1. **Embed selectively:** keep the host and call Mantle's parser, Runtime or
+   selected surfaces through its documented package APIs. The host owns wiring.
+2. **Replace incrementally:** move one bounded capability at a time. Define
+   where reads and writes go during coexistence and how each step is checked.
+3. **Rebuild and migrate:** create a separate new Mantle application, port the
+   frontend and business behavior, and transform/import existing data. Prefer
+   this when adapting the old structure costs more than rebuilding. Preserve
+   relevant IDs, relations, URLs and identity semantics; rehearse the data
+   transfer before a production cutover.
+
+Explain the chosen path and its concrete tradeoffs to the owner. A small
+prototype or read-only inventory may resolve uncertainty. Do not run a generic
+project converter or assume the current application's shape matches a
+generated Cloudflare or ChatGPT Sites skeleton.
+
+## Implement and verify
+
+- For embedding, retain user-owned entry/config/build files. Use the installed
+  direct-authoring docs and CLI to validate manifests and emit bindings; wire
+  the selected Mantle capabilities into the existing host explicitly.
+- For incremental replacement, establish a clear owner for each data write
+  and request route at every stage. Verify old and new behavior together.
+- For rebuilding, generate in a **separate directory** with the installed
+  CLI, move frontend and handlers deliberately, and plan data mapping and
+  import separately. Review database migrations before application or cutover.
+- Run the application's build and representative behavior checks for the
+  changed routes, auth and data. `mantle generate --check` checks generated
+  output against its declared selection; it cannot certify host integration.
+  For live data, record migration counts and a rollback or recovery path
+  appropriate to the project.
+
+Leave existing data and deployment untouched until the requested migration
+and release steps are ready. Report which capabilities Mantle now owns,
+what was verified, and what remains for application deployment or cutover.

package/docs/skills/media-gc/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: media-gc
+description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/media-gc/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: package
+  projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
+---
+
+# Mantle Media GC
+
+Use the connected Cloudflare API. Audit by default; delete only the exact
+objects approved by the user.
+
+## Preflight
+
+1. Read the project's Wrangler config and Mantle config. Resolve the R2 bucket
+   binding, bucket name, and declared public media purpose names.
+2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
+   ask; never choose by name similarity.
+3. Use the Cloudflare OpenAPI search before execution to resolve the current
+   R2 List Objects and Delete Objects endpoints. If the connected account lacks
+   access, stop. Do not create, request, or store credentials.
+4. Stop when the project has no public R2 media binding or no declared purpose.
+
+## Audit
+
+For each declared purpose, list up to 1,000 objects per page under the exact
+`<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
+
+An object is a deletion candidate only when all conditions hold:
+
+- `last_modified` is more than 24 hours old;
+- `custom_metadata.committedAt` is absent or empty;
+- the key matches the exact Mantle layout
+  `<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|svg)`,
+  where `<purpose>` is declared by this project and `<group>` contains only
+  letters, digits, `_`, or `-`.
+
+Skip committed, unknown-prefix, unprefixed, malformed, or ambiguous objects.
+Delete only an uncommitted variant, never its whole group.
+
+Report the account, bucket, purpose prefixes, UTC cutoff, candidate object and
+group counts, total bytes, skipped count, and a SHA-256 digest of the sorted
+`key + etag` candidate set. Do not print object keys, upload group IDs,
+filenames, public URLs, signed URLs, or secrets.
+
+## Apply
+
+1. Show the audit summary and get explicit confirmation for that exact account,
+   bucket, cutoff, count, byte total, and candidate-set digest.
+2. Re-run the complete audit with the same UTC cutoff. If the candidate count,
+   bytes, or digest changed, stop and present the new audit for confirmation.
+3. Call Delete Objects with JSON arrays of exact keys, at most 1,000 keys per
+   request. Never send the `prefix` query parameter: an empty prefix can empty
+   the bucket.
+4. Do not automatically retry failed keys. Report safe API error codes and
+   counts; a later invocation can audit and retry what remains.
+5. Re-list every inspected purpose prefix and report the remaining candidate
+   count and bytes.
+
+## Don't
+
+- Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
+- Don't use prefix deletion or empty-bucket operations.
+- Don't delete private-media buckets or objects outside declared purpose
+  prefixes.
+- Don't treat missing pagination pages, metadata, or permissions as an empty
+  result.
+
+## Diagnostics
+
+| Symptom | Action |
+|---|---|
+| Multiple matching accounts or buckets | Stop and ask the user to select the exact target. |
+| A page is truncated without a cursor | Stop; do not delete from a partial audit. |
+| A candidate has an unexpected key or metadata shape | Skip it and include it only in the aggregate skipped count. |
+| A delete request partially fails | Report safe error codes and leave the remaining objects for a later audit. |
+
+## When You're Done
+
+Return whether the run was audit-only or applied, the aggregate before/after
+counts and bytes, and any safely redacted failures.

package/docs/skills/plugin/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: plugin
+description: Discover, plan, apply, and verify Mantle marketplace plugins through the Core SDK contract. Use when the user wants to add an installable capability without hand-planning provisioning steps.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/plugin/SKILL.md
+  applies_to: mantle grammar v0.1
+  projection: project
+---
+
+# Mantle Plugin
+
+Mantle plugins are Core SDK capability packages. They are not application
+scaffolds (retired in ADR-0021) and they are not provider provisioning scripts.
+
+A plugin may contribute:
+
+- manifests: `Schema`, `View`, `Procedure`, `Trigger`;
+- handler source or handler registration notes;
+- site defaults or media policy additions;
+- expected HTTP, admin, and MCP surfaces;
+- adapter capability requirements and provider setup notes.
+
+## User Install Entry
+
+The user-facing install path is:
+
+```txt
+Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
+Use repo-local mantle:plugin to update <plugin id> in this repo.
+Use repo-local mantle:plugin to remove <plugin id> from this repo.
+```
+
+There is no `mantle plugin add` CLI yet. Do not invent one. Install from a
+marketplace entry, plugin package, or recipe URL that declares enough data for
+an agent to apply the capability deterministically.
+
+A valid marketplace entry must include:
+
+- plugin id, title, source, and version;
+- supported Mantle version range;
+- files, manifests, handlers, routes, MCP tools, and admin surfaces it adds;
+- adapter capabilities and provider resources it requires;
+- required env vars and secrets, without secret values;
+- verification commands and expected surfaces.
+
+If the marketplace page is only marketing copy or lacks an install recipe,
+stop and ask for the recipe instead of guessing.
+
+## First Read
+
+1. `package.json` for Mantle version and adapter package.
+2. The manifest directory selected by project scripts for current atom names
+   and route/tool collisions.
+3. The actual host entry and its handler, template and port registrations;
+   `src/mantle/config.ts` and `src/mantle/handlers/` are conventions, not required paths.
+4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
+5. `.mantle/launch-state.json` only as context, not as plugin authority.
+
+Read version-matched contracts under `node_modules/@aotter/mantle/docs/`,
+starting with `handbook/reference/features.md`. Plugin recipes cannot override
+the installed grammar.
+
+## Plan First
+
+Before applying any plugin, produce a plan:
+
+- files to add or change;
+- atoms to add and their names;
+- HTTP routes and MCP tools that will appear;
+- required runtime ports;
+- adapter-specific resources, env vars, and secrets;
+- checks to run.
+
+If the plugin needs a capability the current adapter does not expose, stop
+with the missing capability instead of inventing provider steps.
+
+## Apply
+
+Apply the smallest deterministic diff. Do not run arbitrary install scripts
+from a plugin package. Copy declared files, wire declared handlers, update the
+plugin ledger, then validate.
+
+Suggested ledger paths:
+
+```txt
+.mantle/plugins.json
+.mantle/plugins.lock.json
+```
+
+Keep optional legacy launch files such as `.mantle/features.json` separate from
+plugin state. They are not the Core plugin ledger.
+
+## Update
+
+Compare the installed lock entry against the marketplace entry or recipe URL.
+Apply only the declared version diff, update `.mantle/plugins.lock.json`, then
+run the same verification checks.
+
+## Remove
+
+Use the lock entry as the removal manifest. Delete only files and atoms owned
+by that plugin, unwind handler registrations it added, remove its ledger entry,
+then validate. If another plugin or local code depends on a removed atom, stop
+and report the dependency instead of deleting through it.
+
+## Verify
+
+Use the project's validation and typecheck scripts when present. Regenerate
+the plan after manifest changes before probing the running host:
+
+```bash
+pnpm exec mantle validate
+pnpm exec mantle generate
+pnpm exec mantle generate --check
+# Run the project's TypeScript check and restart its local server.
+```
+
+Then verify the plugin's declared surfaces:
+
+- public Views via `GET /api/views/<name>`, staff Views via authenticated
+  Admin/staff MCP, and internal Views through the host binding;
+- HTTP Trigger path for public writes;
+- Staff/Public MCP `tools/list` for MCP Trigger or Schema-derived tools;
+- adapter resource presence when the plugin requires optional ports.
+
+## Don't
+
+- Don't treat an application template as a plugin.
+- Don't assume Cloudflare; inspect the active adapter and capability ports.
+- Don't create a second skill namespace for host-specific plugins.
+- Don't commit secrets. Provider secrets stay in the platform secret store.

package/docs/skills/provision/SKILL.md

@@ -0,0 +1,194 @@
+---
+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/docs/skills/theme/SKILL.md

@@ -0,0 +1,77 @@
+---
+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/docs/skills/update/SKILL.md

@@ -0,0 +1,51 @@
+---
+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.

package/docs/spec-only-host-adoption.md

@@ -6,7 +6,7 @@ Runtime. This Spec-only path is allowed by
 [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md), not a new adapter,
 manifest grammar, or fork of Core.
 
-This recipe targets `0.1.3`. Pin the package, record the tested version, and
+This recipe targets `0.1.4`. Pin the package, record the tested version, and
 rerun compatibility checks when upgrading.
 
 ## What stays with the host