@aotter/mantle 0.1.3-alpha.6 → 0.1.3

package/skills/install/SKILL.md

@@ -16,6 +16,23 @@ provider configuration. There is no Starter/type picker or `mantle create`.
 Do not use the SDK checkout as the application, copy an old Starter tree, or
 turn `generate` into implicit scaffolding.
 
+## Locate the version-matched instructions
+
+`npx skills add aotter/mantle --skill install` installs this brief, not the SDK,
+a project, or the handbook. Read the path printed by the installer (Codex's
+project-local path is `.agents/skills/install/SKILL.md`); `metadata.sourcePath`
+is repository provenance, not a consumer path. A repository install follows
+the selected Git ref and does not pin an npm release.
+
+After selecting the host and exact version, install `@aotter/mantle` locally
+with the selected optional packages. All `docs/...` paths below then mean
+`node_modules/@aotter/mantle/docs/...`; package skills are under
+`node_modules/@aotter/mantle/skills/`. Read that package's
+`skills/install/SKILL.md` before authoring: it supersedes this bootstrap copy.
+If the user requested a prerelease, resolve that channel explicitly; `latest`
+need not contain prerelease features. Never mix versioned npm code with branch
+docs. No local CLI exists until the package is installed.
+
 ## New application
 
 1. Determine the actual host and required surfaces from the request. Reuse an
@@ -30,8 +47,9 @@ turn `generate` into implicit scaffolding.
    version. Install only the adapter/optional packages the application needs.
    If a global scope registry overrides public npmjs, use a project-owned
    `.npmrc` with `@aotter:registry=https://registry.npmjs.org/`.
-3. Interview the human for host and required surfaces. Do not assume Admin,
-   public HTML or Cloudflare. Scale:
+3. Use the host and surfaces already established in step 1; ask only for
+   information still missing. Read `docs/handbook/start/overview.md` and
+   `docs/handbook/reference/features.md`, then select the matching path:
    - Spec + generate / embed Runtime — `docs/handbook/start/project-and-cli.md`.
    - Adapter without Admin — `docs/examples/host-minimal-worker/`.
    - Opt-in Admin / Dev UI — only when a human needs a console: interview
@@ -108,7 +126,9 @@ a bundle comparison command.
 
 ## Ship and report
 
-When deployment is requested, follow the installed provision skill and the
+When deployment is requested, read
+`node_modules/@aotter/mantle/skills/provision/SKILL.md` (not projected by
+`mantle skills`) and follow that version-matched skill and the
 observed host configuration. Legacy Landing remains a pre-stable product; it
 is not a launch dependency for new Core projects.
 

package/skills/plugin/SKILL.md

@@ -50,11 +50,17 @@ stop and ask for the recipe instead of guessing.
 ## First Read
 
 1. `package.json` for Mantle version and adapter package.
-2. `manifests/site.yaml` for current atom names and route/tool collisions.
-3. `src/mantle/config.ts` and `src/mantle/handlers/` for registered handlers, templates, and optional ports. Older projects may use `src/mantleConfig.ts`.
+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:
@@ -100,14 +106,20 @@ 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 validate
-pnpm typecheck
+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:
 
-- `GET /api/views/<name>` for View reads;
+- 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.

package/skills/theme/SKILL.md

@@ -13,13 +13,20 @@ metadata:
 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. `manifests/site.yaml` to understand which content shape drives the public UI.
+4. The manifest directory selected by project scripts to understand which
+   content shape drives the public UI.
 
 ## Ownership
 

package/skills/update/SKILL.md

@@ -17,8 +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 entry in
-   `docs/handbook/releases/index.md` plus that version's GitHub release notes.
+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
@@ -39,6 +41,9 @@ 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