@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/skills/plugin/SKILL.md

@@ -1,132 +0,0 @@
----
-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/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/docs/spec-only-host-adoption.md

@@ -1,157 +0,0 @@
-# Spec-only adoption in an existing host
-
-An existing application can reuse Mantle's Schema grammar and validation by
-consuming the published `@aotter/mantle-spec` package, without running Mantle
-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.4`. Pin the package, record the tested version, and
-rerun compatibility checks when upgrading.
-
-## What stays with the host
-
-| Concern | Spec reuse | Host responsibility |
-|---|---|---|
-| Model definitions | Schema grammar, parse/link diagnostics | Project existing definitions into supported JSON Schema |
-| Input | `EntryDataValidator` and structured errors | Authentication, authorization, normalization, write orchestration |
-| Model browser | Parsed/linked Schema metadata | UI, metadata visibility, field display, graph layout |
-| Relationships | Translation declaration/link validation | Existing slug joins, record integrity, locale policy |
-| Storage and publishing | None in this recipe | Files, database, transactions, revisions, release/recovery |
-| Operations and tools | None in this recipe | No automatic View, Procedure, Trigger, REST or MCP execution |
-
-Mantle's Web, Admin UI and platform adapters remain optional. A Vue host does
-not have to embed the React Admin SPA to reuse Spec. Avoid importing SDK
-internals or maintaining a second manifest interpreter.
-
-## One definition, several projections
-
-The motivating Aotter official-website implementation keeps its existing
-Nuxt/Nitro host and Git/D1 storage. Shared content definitions drive the site's
-content layer, admin write validation, a responsive model/ER browser, and
-Schema export. That website implementation was validated locally; this SDK
-contribution does not deploy it or claim a production rollout.
-
-```text
-Host-owned content definitions
-  ├─ existing CMS/content queries
-  └─ JSON Schema in Mantle Schema manifests
-       ├─ parse + link → model browser / metadata export
-       └─ EntryDataValidator → host-authorized write path
-```
-
-Use the existing definitions as the source of truth. If the host starts with
-Zod or another schema language, conversion is a host concern: verify that the
-result uses supported JSON Schema keywords and preserves the intended
-validation semantics. Do not hand-maintain a second field list for the graph.
-
-## Minimal public-API recipe
-
-Install the exact Spec package and its supported peer, without Runtime:
-
-```sh
-npm install --save-exact @aotter/mantle-spec zod@4.5.4
-```
-
-The [synthetic fixture](../packages/mantle-spec/test/fixtures/spec-only-host.yaml)
-contains categories, articles and article translations. It contains no real
-website records, account configuration or credentials. Given that fixture as
-`manifestYaml`, the application can prepare its validated model once:
-
-```ts
-import {
-  EntryDataValidator,
-  parseManifestSources,
-  ValidateManifestsUseCase,
-} from "@aotter/mantle-spec";
-
-const parsed = parseManifestSources({
-  sources: [{ sourceId: "host:content-model", text: manifestYaml }],
-});
-if (!parsed.ok) throw new Error(JSON.stringify(parsed.diagnostics));
-
-const checked = ValidateManifestsUseCase.run({
-  parsed: parsed.value,
-  siteLocales: ["zh-TW", "en-US"],
-});
-if (checked.errorCount || !checked.linked) {
-  throw new Error(JSON.stringify(checked.diagnostics));
-}
-
-const article = checked.linked.schemas.find(
-  ({ manifest }) => manifest.metadata.name === "articles",
-)!.manifest;
-const validator = new EntryDataValidator();
-const diagnostics = validator.validate(article, { category: 42 }, { partial: true });
-// INPUT_VALIDATION_FAILED at /category. The host must reject the write.
-```
-
-The non-null assertion is specific to this known fixture. A dynamic host must
-handle an unknown collection explicitly and fail closed. Do not fabricate
-sealed parser/linker values or re-parse the same revision in each request.
-
-`EntryDataValidator` returns diagnostics, not a sanitized payload. It does not
-persist, authorize, coerce the original object, or enforce storage integrity.
-Normalize explicitly in the host before validation and write only after
-successful validation and authorization. An `additionalProperties: true`
-compatibility policy accepts legacy fields; it is not a reason to expose those
-fields publicly.
-
-`partial: true` relaxes top-level required fields for drafts, while still
-checking supplied types and nested required fields. Validate without `partial`
-when the host needs a complete record, alongside its own publication rules.
-Create a fresh validator for each model revision: its compiled cache is keyed
-by manifest name (and partial/full mode), not by a changing schema body.
-
-## Honest ER diagrams and metadata export
-
-- Derive model nodes and field details from Schema properties. Use a small
-  host-owned relationship registry for relations not represented by Mantle
-  grammar; show logical joins distinctly from actual database foreign keys.
-- The fixture's `x-example-source` and `x-example-relations` live inside JSON
-  Schema. They are illustrative vendor annotations, **not new Mantle keys or
-  executable relationship definitions**. Core may preserve them without
-  interpreting them. The host must validate their shape and endpoint fields.
-- Do not label a filename/slug join as `x-mantle-ref`: that keyword represents
-  Mantle entry-ID references. A category slug matching a key inside a YAML
-  array remains a host-specific relation, not a generated SQL foreign key.
-- `translates` validates the parent and join-field declarations, not whether
-  actual translation records exist. A Spec-only host still owns allowed
-  locales, uniqueness, fallback, and orphan handling. See
-  [ADR-0010](adr/0010-locale-and-translates.md); Runtime locale/storage gates
-  are not installed by this recipe.
-- A read-only inventory can add derived fields such as filename `slug` or
-  directory `locale` without changing stored files. Document that projection;
-  it is not evidence that existing data is ready for Runtime import.
-- The fixture uses JSON Schema `readOnly` as an inventory annotation. It is
-  not a security boundary: entry validation does not enforce host write
-  permissions. Export only after applying the host's metadata access policy.
-- Exclude credential/account models and private data. Export schemas, not
-  records. Where appropriate, require an administrator and use
-  `Cache-Control: private, no-store` for model and export endpoints.
-- Keep the graph usable on narrow screens: searchable model selection,
-  focused relationships, zoom/scroll, keyboard controls and a field-table
-  alternative. A graph must not be the only accessible representation.
-
-## Reproducible evidence
-
-From this SDK checkout:
-
-```sh
-pnpm --filter @aotter/mantle-spec test -- test/spec-only-host.test.ts
-pnpm --filter @aotter/mantle-spec typecheck
-```
-
-The [regression test](../packages/mantle-spec/test/spec-only-host.test.ts)
-exercises the public export surface, manifest round trips, translation linking,
-and strict/partial entry validation without Runtime. It is an SDK regression
-fixture, not a new Starter workspace or a certification test suite.
-
-An adopting host must also test its own installed package, real content
-compatibility, HTTP authorization/invalid-input paths, metadata exclusions and
-responsive UI. Existing data need not be published or uploaded to prove this.
-Keep sensitive evidence internal and expose only an agreed verification report.
-
-Spec validation against an exact SDK version is not official certification or
-proof of Runtime compatibility, data migration, or security. Recognition policy
-is tracked separately in [#840](https://github.com/aotter/mantle/issues/840).

package/docs/transaction-patterns.md

@@ -1,5 +0,0 @@
-# Transaction patterns
-
-This guide lives in the Examples hub: [`docs/examples/cf-primitives-commerce-inventory.md`](examples/cf-primitives-commerce-inventory.md). The Builder-safe catalog is [`docs/examples/builtin-commerce.md`](examples/builtin-commerce.md).
-
-The handbook and examples hub ship inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/` and describe the installed release.

package/skills/README.md

@@ -1,125 +0,0 @@
-# SKILL.md briefs (mantle)
-
-Agent-readable skill briefs for consumers of `@aotter/mantle-*`. Discoverable by URL — no plugin install needed.
-
-| Skill | When to invoke |
-|---|---|
-| [`develop`](../docs/skills/develop/SKILL.md) | `mantle:develop`: Core-owned workflow for manifest, runtime, handler, adapter, validation, and MCP work in any Mantle project. |
-| [`media-gc`](../docs/skills/media-gc/SKILL.md) | `mantle:media-gc`: audit or remove stale uncommitted public media objects with the connected Cloudflare API. |
-| [`plugin`](../docs/skills/plugin/SKILL.md) | `mantle:plugin`: Core-owned marketplace workflow for plan-first capability installs across applications and adapters. |
-| [`theme`](../docs/skills/theme/SKILL.md) | `mantle:theme`: Core-owned visual workflow. Reads project-owned theme and UI contracts. |
-| [`update`](../docs/skills/update/SKILL.md) | `mantle:update`: Core-owned drift check workflow for SDK dependencies, local skills, and plugin lockfiles. |
-| [`mantle`](install/SKILL.md) | User wants to author a local Mantle application or continue an existing project. |
-| [`provision`](../docs/skills/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.
-
-## Disclosure audit
-
-Every skill ships as one `SKILL.md` with no reference files, scripts, or
-assets, so nothing is deferred behind a second load. Progressive disclosure
-here is section routing inside one file: the agent reads the entry constraints,
-then only the section its selected path names. `scripts/check-skills.mjs`
-enforces the columns below.
-
-| Skill | Routes on | Entry-path constraints (read before acting) | Path-gated sections | Projection | Restricted because |
-|---|---|---|---|---|---|
-| `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` | user wants an installable capability | plan before apply; lock entry is the removal manifest; delete only plugin-owned files and atoms | apply; remove | project | — |
-| `theme` | brand or visual direction in a project | repo-owned theme and UI contracts | — | project | — |
-| `update` | SDK upgrade or plugin lock review | never blindly overwrite user-owned code | — | project | — |
-| `mantle` | 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 | package | 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 | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
-
-Deliberately monolithic:
-
-- `develop` is the widest file, but its adapter, auth, and data-ownership rules
-  constrain every path through it. Splitting them behind routing would let an
-  agent reach a write path without them, which is the failure this audit
-  exists to prevent.
-- `media-gc` keeps its full audit-confirm-reapply sequence inline for the same
-  reason: each safeguard is a precondition of the delete that follows it.
-
-## Skill authority
-
-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 consumer project, and a skill that
-withholds `project` must say why. `plugin` is the bootstrap skill and `package`
-is an opt-in brief in the installed SDK. `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.
-Application files and plugin recipes are project context, not competing
-contracts.
-
-## Source-repository marketplace install
-
-`skills/install/SKILL.md` declares `name: mantle`. It is the only repository
-skill discovered by the no-flag command and copied as a small directory.
-The other six skills live in `docs/skills/` and ship with the npm package.
-`mantle skills` projects the four ongoing workflows after package installation.
-
-Other marketplace hosts point to the same entry:
-
-```sh
-npx skills add aotter/mantle
-```
-
-```bash
-# Claude Code — two separate prompts
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
-
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
-```
-
-Read the path printed by the installer (for project-local Codex,
-`.agents/skills/mantle/SKILL.md`). Only the selected brief is installed, not
-the SDK or handbook. After choosing and installing an exact SDK version, read
-`node_modules/@aotter/mantle/skills/install/SKILL.md` and its embedded docs;
-that package supersedes the bootstrap Git-ref instructions. After packages are
-installed, `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:
-
-- Claude Code: `.claude-plugin/plugin.json` plus `.claude-plugin/marketplace.json`.
-- Codex: `.codex-plugin/plugin.json` plus `.agents/plugins/marketplace.json`.
-- Cursor: `.cursor-plugin/plugin.json`.
-- VS Code + GitHub Copilot: `.copilot-plugin/plugin.json`.
-
-## Audience
-
-These are written for **AI agents acting on behalf of consumers of mantle**,
-not for contributors maintaining the Mantle SDK itself. SDK contributors use
-the repo-root `CONTRIBUTING.md`; it is intentionally not shipped inside the npm
-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"). Official cold start is `npx skills add aotter/mantle`. Point the agent at the repository or pass the version-matched markdown content directly.
-
-## Conventions
-
-Each SKILL.md ships:
-
-- **Front-matter** with a stable `name`, trigger-complete
-  `description`, and optional source/version `metadata`. Plugin hosts add the
-  external `mantle:` namespace.
-- **Preflight** section — environment + user-confirmation gates.
-- **Step-by-step** — concrete commands (`pnpm validate`, `mantle emit-openapi`, etc.).
-- **Diagnostic recipes** — `Symptom → Cause → Fix` table for the common failure modes.
-- **Don't** — reviewer-style list of patterns the agent must reject (often citing ADRs).
-- **When you're done** — what to report back to the user.
-
-If you're writing a new SKILL, follow the same structure. Commands and prose
-must match the package version that carries the skill; later prereleases may
-revise both together.