@aotter/mantle 0.2.1-alpha.1 → 0.2.1-alpha.3

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

@@ -1,109 +0,0 @@
----
-name: media-gc
-description: Audit and safely remove stale, uncommitted media uploads from a Mantle 0.2 Cloudflare R2 bucket. Use when an operator asks to inspect or clean objects left under uploads/ by an upload that was created but never committed.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/media-gc/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
-  projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
----
-
-# Mantle Media GC
-
-## Generated native applications (alpha.7 and later)
-
-If the installed README describes generated native queries, read
-`docs/handbook/cloudflare/media-r2.md` and app-owned site/media wiring instead of Core storage
-options. Resolve the exact configured bucket and declared purposes. The
-`uploads/` candidate audit below still applies. Committed copies live under
-`committed/` and must never be candidates. Attempt-isolated committed copies
-retained after an uncertain DB outcome require reconciliation with live DB
-references before any separately authorized cleanup.
-
-Use the connected Cloudflare API. Audit by default; delete only the exact
-objects approved by the user.
-
-## Preflight
-
-1. Read `wrangler.jsonc`, the app-owned entry (`src/worker.ts` by default,
-   or the generation command's `--entry`) and its media wiring. Resolve the R2
-   bucket that `r2MediaStorage` uses and the media purpose names in
-   `siteDefaults.media.purposes` selected by `--site`.
-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 service passes no `r2MediaStorage` or declares no purpose.
-
-## How 0.2 lays out media
-
-`POST /admin/api/media/uploads` issues presigned PUT URLs that expire after 15
-minutes, for keys under `uploads/<purpose>/<group>/<role>.<ext>`. Commit
-copies each checked object to `committed/<group>/<attempt>/<role>.<ext>` (with
-`committedAt` metadata); the attempt UUID isolates concurrent commits. Upload
-keys are removed after the database commit succeeds, or when a group is
-rejected. An old upload key may also be leftover cleanup from a successful or
-uncertain commit: it is not evidence that the media row is absent. Once expired,
-it cannot create a new asset. Objects outside `uploads/` are never candidates;
-reconcile attempt copies separately with live database references.
-
-## Audit
-
-For each declared purpose, list up to 1,000 objects per page under the exact
-`uploads/<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 upload layout
-  `uploads/<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|bin)`,
-  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 objects outside `uploads/<declared purpose>/`, and never
-  committed media.
-- 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/provision/SKILL.md

@@ -1,44 +0,0 @@
----
-name: provision
-description: Ship a Mantle 0.2 project to production — Cloudflare Workers with D1, production sign-in and secrets, or ChatGPT Sites through its guide — and verify the deployed service.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/provision/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
-  projectionReason: Creates remote resources and handles production secrets; opt-in only.
----
-
-# Provision a Mantle project
-
-## Workflow
-
-Read the installed SDK README, then follow the version-matched [project and CLI
-workflow](../../handbook/start/project-and-cli.md) before editing.
-
-Deploy/create resources only within the user's authorization; reuse configured
-host resources. Apply reviewed and rehearsed migrations before routing traffic;
-imports/first requests perform no DDL or schema checks. Keep auth dynamic, production
-secrets in the host store, trusted HTTPS origin and verified bootstrap rule,
-production email and selected media wiring. Configure Admin ASSETS worker-first
-as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#workers-assets-and-secrets). Hyperdrive caching stays off; PG settings are deployment-owned.
-Keep the Workers [public-fetch flags](../../handbook/cloudflare/deploy-and-operate.md#public-fetch-routing),
-including environment overrides; verify deployed MCP with a real OAuth bearer
-(`initialize` and `tools/list`), not only a browser session cookie.
-For MCP Apps, also follow [deployed host acceptance](../../handbook/guides/mcp-apps.md#verify-a-deployed-app-in-chatgpt):
-compare the current resource URI and visibly verify a newly invoked render tool.
-Archive deployed Admin pages using the guide's `previous` recipe and carry them
-through clean builds. Test the same old conversation after changing the UI build,
-without reconnecting, refreshing host tools or clearing caches. A deliberate tool
-contract change has its own migration/host rediscovery step. OAuth renewal, `tools/call` success and a
-local official-host replay do not establish that the deployed App rendered.
-Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
-(role admin), denied access, public reads, a persisted write, MCP and selected UI.
-Report artifact/resources/checks and keep rollback artifacts.
-
-For ChatGPT Sites, follow [Mantle on ChatGPT Sites](../../handbook/cloudflare/chatgpt-sites.md).
-
-The app builds Admin with `mantle bundle`; serve it as [Native
-Admin](../../handbook/guides/native-admin.md) describes. Verify both member and
-admin OTP/UI flows. Deployment of an authorized application does not authorize
-SDK publication; a workspace preview remains a preview.

package/docs/skills/update/SKILL.md

@@ -1,42 +0,0 @@
----
-name: update
-description: Upgrade a Mantle project's @aotter/mantle packages to a new exact version, including the move from 0.1.x to 0.2, without overwriting application-owned code.
-metadata:
-  source: "@aotter/mantle"
-  sourcePath: docs/skills/update/SKILL.md
-  applies_to: mantle 0.2
-  projection: package
----
-
-# Mantle Update
-
-## Workflow
-
-Read the installed SDK README, then follow the version-matched [project and CLI
-workflow](../../handbook/start/project-and-cli.md) before editing.
-
-For 0.1.x, follow [Upgrade 0.1 to 0.2](../../upgrade-0.1-to-0.2.md). Mantle
-ships no migration tool: plan the data move from
-[Moving data from 0.1.x](../../upgrade-0.1-to-0.2.md#moving-data-from-01x),
-verify each fact against the generated `schema.sql` and the 0.1.4 export, and
-have the plan reviewed. Give the 0.2 service a new database, rehearse the load
-on a copy, never boot 0.2 against a 0.1.x database, and keep exports out of the
-repository. The guide's appendix is historical; do not follow it. Between 0.2
-versions, apply reviewed migrations rehearsed on a copy.
-
-For the stable 0.2 line, pin every selected Mantle package to `0.2.0`; to try the 0.2.1 prerelease, pin all of them to `0.2.1-alpha.1` and read its release notes. Do not upgrade an existing application by following a moving dist-tag.
-
-Pin exact target SDK/peer versions and read its release notes and Admin build
-instructions. Core-to-native replaces app imports/wiring; it is not
-a package-only update. For 0.2-to-0.2 updates, preserve users, sessions, content
-and application code; review emitted SQL/policy diffs and rehearse explicit
-data-preserving schema/auth/role migrations on a copy. Initial schema.sql never
-authorizes rebuilding production tables. Verify auth/Admin/MCP/REST, locks and
-persistence before authorized cutover.
-
-Follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin)
-for the current application-built Admin; old UI subpaths have no compatibility
-aliases. Pin only actually published versions, or explicitly use a matching
-workspace preview. Recheck member and Admin OTP, all affected native routes,
-private field visibility, OCC and unknown outcomes. Do not publish a package as
-part of an application dependency update.