@aotter/mantle 0.1.2 → 0.1.3-alpha.1

package/skills/README.md

@@ -6,11 +6,11 @@ Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by
 |---|---|
 | [`develop`](develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
 | [`media-gc`](media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
-| [`plugin`](plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across starters and adapters. |
-| [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project context but does not depend on starter-owned skill semantics. |
+| [`plugin`](plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across applications and adapters. |
+| [`theme`](theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
 | [`update`](update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
-| [`install`](install/SKILL.md) | User wants to create a local Mantle site by direct authoring or continue an existing local / landing-generated project. |
-| [`provision`](provision/SKILL.md) | User wants a local or landing-generated project shipped to Cloudflare with production auth and operator handoff. |
+| [`install`](install/SKILL.md) | User wants to author a local Mantle application or continue an existing project. |
+| [`provision`](provision/SKILL.md) | User wants a local project shipped to Cloudflare with production auth and operator handoff. |
 
 The skills target Mantle's v0.1 grammar. The installed package version, not
 duplicated skill prose, selects the exact runtime and embedded docs.
@@ -27,9 +27,9 @@ enforces the columns below.
 |---|---|---|---|---|---|
 | `develop` | existing project; manifest, runtime, handler, adapter, or MCP work | four-atom model; adapter neutrality; no direct D1/KV/Postgres writes; no committed secrets | performance harness; local MCP client; locale rules | project, plugin | — |
 | `plugin` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project, plugin | — |
-| `theme` | brand or visual direction in a generated project | repo-owned theme and UI contracts | — | project, plugin | — |
+| `theme` | brand or visual direction in a project | repo-owned theme and UI contracts | — | project, plugin | — |
 | `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project, plugin | — |
-| `install` | new site, or opening an existing generated one | do not use the SDK checkout as the application; no push/deploy/provider config during cold start | author local project; continue existing project | plugin | Creates a new project; nothing to project into an existing one. |
+| `install` | new application, or opening an existing project | do not use the SDK checkout as the application; no push/deploy/provider config during cold start | author local project; continue existing project | plugin | Creates a new project; nothing to project into an existing one. |
 | `provision` | ship to Cloudflare and finish production auth | secrets never enter source or logs; explicit auth mode | hosted auth; self-managed auth | plugin | Platform-specific deploy that handles production secrets; opt-in only. |
 | `media-gc` | audit or remove stale uncommitted media objects | audit by default; confirm exact account, bucket, cutoff, and candidate digest; re-audit before applying; never prefix-delete; never print keys | apply | plugin | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
 
@@ -46,33 +46,39 @@ Deliberately monolithic:
 
 The `mantle:*` namespace is owned by `@aotter/mantle`. Every skill declares its
 own distribution scope in front matter: `metadata.projection: project` marks a
-skill `mantle skills` should place in a generated project, and a skill that
+skill `mantle skills` should place in a consumer project, and a skill that
 withholds `project` must say why. `scripts/check-skills.mjs` holds that
 declaration and the audit table below to each other.
 
 Run `mantle skills` to project the installed package's skills into a project;
 use `mantle skills --check` to fail closed on drift. The installed package and
 `node_modules/@aotter/mantle/docs/` are the single version-matched authority.
-Starter launch files and plugin recipes are project context, not competing
+Application files and plugin recipes are project context, not competing
 contracts.
 
 ## Source-repository marketplace install
 
-The source repository is also an agent plugin bundle:
+Cold start is the pinned install skill. Other marketplace hosts are pointers
+to the same pin:
+
+```sh
+npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install
+```
 
 ```bash
 # Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle
+/plugin marketplace add aotter/mantle@v0.1.3-alpha.1
 /plugin install mantle@mantle
 
 # Codex
-codex plugin marketplace add aotter/mantle
+codex plugin marketplace add aotter/mantle --ref v0.1.3-alpha.1
 codex plugin add mantle@mantle
 ```
 
-These are authoring workflows and do not track a release. Version matching is
-the job of `mantle skills`, which projects the installed package's own skills
-into the project, and `mantle skills --check`, which fails on drift.
+Then follow the install skill to the CLI and handbook. Do not use an untagged
+`aotter/mantle` marketplace add as the official entry. After packages are
+pinned, `mantle skills` projects the installed package's own skills into the
+project, and `mantle skills --check` fails on drift.
 
 Cursor and GitHub Copilot read their manifests from the repository directly.
 These manifests are not duplicated into the npm package:
@@ -91,7 +97,7 @@ package. Two audiences, two artifacts.
 
 ## Discoverability
 
-The skills target ADR-0007's "AI as primary author" thesis: agents reach these files by URL when the user invokes them by intent ("install mantle", "develop my Mantle site", "deploy"). No `/skill install` slash command is required — point the agent at a version tag or pass the version-matched markdown content directly.
+The skills target ADR-0007's "AI as primary author" thesis: agents reach these files by URL when the user invokes them by intent ("install mantle", "develop my Mantle site", "deploy"). Official cold start is `npx skills add aotter/mantle@v0.1.3-alpha.1 --skill install`. Point the agent at tag `v0.1.3-alpha.1` or pass the version-matched markdown content directly.
 
 ## Conventions
 

package/skills/install/SKILL.md

@@ -101,15 +101,15 @@ Install the frozen dependency graph, project installed Core skills, then read
 those skills and embedded docs. Never apply develop docs to an older package.
 Use the installed `mantle --help` and the project's scripts as authority.
 
-For legacy alpha.17 projects, retain their pinned behavior until an explicit
-upgrade is requested; read `docs/migration-0.1.2.md` before upgrading. Do not
-rewrite provider identities, delete metadata or fetch a nonexistent new Starter
-tag. SDK upgrades follow the update skill, not a bundle comparison command.
+For a legacy pre-stable project, retain its pinned behavior until an explicit
+upgrade is requested. Do not rewrite provider identities, delete metadata or
+fetch a nonexistent new Starter tag. SDK upgrades follow the update skill, not
+a bundle comparison command.
 
 ## Ship and report
 
 When deployment is requested, follow the installed provision skill and the
-observed host configuration. Legacy Landing remains an alpha.17 product; it
+observed host configuration. Legacy Landing remains a pre-stable product; it
 is not a launch dependency for new Core projects.
 
 Report the project path, exact SDK version, local URL/HTTP result and checks,

package/skills/plugin/SKILL.md

@@ -10,8 +10,8 @@ metadata:
 
 # Mantle Plugin
 
-Mantle plugins are Core SDK capability packages. They are not starter overlays
-and they are not provider provisioning scripts.
+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:
 
@@ -82,8 +82,8 @@ Suggested ledger paths:
 .mantle/plugins.lock.json
 ```
 
-Keep starter launch state separate from plugin state. `.mantle/features.json`
-is launch/starter context, not the Core plugin ledger.
+Keep optional legacy launch files such as `.mantle/features.json` separate from
+plugin state. They are not the Core plugin ledger.
 
 ## Update
 
@@ -114,7 +114,7 @@ Then verify the plugin's declared surfaces:
 
 ## Don't
 
-- Don't treat a starter archetype as a plugin.
+- 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 starter-specific plugins.
+- Don't create a second skill namespace for host-specific plugins.
 - Don't commit secrets. Provider secrets stay in the platform secret store.

package/skills/provision/SKILL.md

@@ -13,18 +13,22 @@ metadata:
 
 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. For a ChatGPT Site, use the installed
-`docs/handbook/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.
+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/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; do not create them as prerequisites.
+   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
@@ -56,8 +60,9 @@ 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
-by landing. Workers Builds is optional after a direct deploy.
+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`
@@ -67,15 +72,17 @@ directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
 
 - **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:** use only when the landing handoff records a
-  hosted allocation and client configuration. Mantle Platform operates the
-  identity provider; do not ask the user for a per-site GitHub OAuth App.
+- **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 the
-current Mantle landing flow explicitly supplies that handoff.
+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`.
@@ -131,10 +138,13 @@ git push
 pnpm deploy
 ```
 
-## Hosted Auth
+## Hosted Auth (legacy Landing)
 
-Follow the landing handoff and generated client configuration. Hosted
-configuration remains in landing-managed Cloudflare Worker bindings. Verify:
+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;

package/skills/update/SKILL.md

@@ -17,9 +17,10 @@ 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 its migration notes, including
-   `docs/migration-0.1.2.md` when leaving alpha.17. Do not resolve new Starter
-   refs or compare the project to a baseline template.
+2. Select an explicit target release and read its entry in
+   `docs/handbook/releases/index.md` plus that version's GitHub release notes.
+   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.