@rubytech/create-maxy-code 0.1.383 → 0.1.384

package/payload/platform/plugins/admin/mcp/dist/tools/account-lifecycle.d.ts

@@ -1,3 +1,4 @@
+import type { CreatedBy } from "../../../../../lib/graph-write/dist/index.js";
 export interface AccountSummary {
     accountId: string;
     role: string;
@@ -43,6 +44,53 @@ export declare function provisionClientAccount(opts: {
     accountId: string;
     usersFile: string;
 }): string;
+/** Minimal Neo4j session surface the root seed needs — the admin plugin's
+ *  `getSession()` satisfies it; tests pass an in-memory fake. */
+export interface SeedSessionLike {
+    run(query: string, params?: Record<string, unknown>): Promise<{
+        records: Array<{
+            get(key: string): unknown;
+        }>;
+    }>;
+}
+/** The provenance the root seed represents — matches the properties the cypher
+ *  below stamps (`createdByAgent='system'`, `createdBySource='installer'`), the
+ *  same shape `seed-neo4j.sh` writes for the house root. `agent:"system"` is the
+ *  convention `checkLabelOriginGate` exempts. The seed runs as raw cypher through
+ *  the admin session (not the memory-write chokepoint), so the gate never
+ *  actually evaluates it in production; this constant is not the write's
+ *  provenance carrier — it exists so a unit test can assert the gate *would*
+ *  permit this origin. */
+export declare const SEED_ORIGIN: CreatedBy;
+/** Task 1359 — seed a client account's graph root: a bare :LocalBusiness{accountId}
+ *  plus its owner :AdminUser (fresh per-account userId) joined by :ADMIN_OF, in
+ *  one statement, then read both node existences back. Without this a created
+ *  client account is rootless: `checkGraphWriteGate` refuses every non-root
+ *  write and `checkLabelOriginGate` refuses the agent's attempt to create the
+ *  root, so the graph is unpopulatable.
+ *
+ *  Raw cypher through the admin session bypasses the memory-write gates by
+ *  construction (they guard only the memory-write chokepoint), mirroring
+ *  `seed-neo4j.sh`. The owner AdminUser carries a fresh `ownerUserId` because
+ *  AdminUser is MERGE-keyed on `userId` and COALESCEs `accountId`; reusing the
+ *  install owner's userId would keep `accountId=house` and leave the gate's
+ *  `MATCH (au:AdminUser {accountId: <client>})` empty. Single-shot per account:
+ *  MERGE on `LocalBusiness.accountId` (a UNIQUE key) makes a replay against the
+ *  same accountId safe, but it is NOT replay-idempotent under a different
+ *  `ownerUserId` (that would MERGE a second owner AdminUser); the sole caller
+ *  mints a new accountId per create and never replays. Returns the two
+ *  read-back booleans; the caller treats `businessSeeded && adminSeeded` as the
+ *  verified post-condition. */
+export declare function seedAccountGraphRoot(args: {
+    session: SeedSessionLike;
+    accountId: string;
+    ownerUserId: string;
+    ownerName: string;
+    createdAt: string;
+}): Promise<{
+    businessSeeded: boolean;
+    adminSeeded: boolean;
+}>;
 /** Cypher for the account-scoped node count and the irreversible purge. The
  *  purge deletes every node carrying the accountId (account scope is a property,
  *  never an edge — see CLAUDE.md), detaching its relationships. */

package/payload/platform/plugins/admin/mcp/dist/tools/account-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/account-lifecycle.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;oCAEoC;AACpC,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE,CAoBzE;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;+DAE+D;AAC/D,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAE3E;AAED;;;;;+DAK+D;AAC/D,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED;;;;0EAI0E;AAC1E,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,CAO7F;AAED;;iFAEiF;AACjF,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAO3C;AAED;;;yBAGyB;AACzB,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAoBT;AAED;;mEAEmE;AACnE,eAAO,MAAM,yBAAyB,2DAA2D,CAAC;AAClG,eAAO,MAAM,oBAAoB,sDAAsD,CAAC"}
+{"version":3,"file":"account-lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/account-lifecycle.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8CAA8C,CAAC;AAI9E,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;oCAEoC;AACpC,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE,CAoBzE;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;+DAE+D;AAC/D,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAE3E;AAED;;;;;+DAK+D;AAC/D,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED;;;;0EAI0E;AAC1E,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,CAO7F;AAED;;iFAEiF;AACjF,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAO3C;AAED;;;yBAGyB;AACzB,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAoBT;AAED;iEACiE;AACjE,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAClH;AAED;;;;;;;0BAO0B;AAC1B,eAAO,MAAM,WAAW,EAAE,SAAoD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;+BAkB+B;AAC/B,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAyB7D;AAED;;mEAEmE;AACnE,eAAO,MAAM,yBAAyB,2DAA2D,CAAC;AAClG,eAAO,MAAM,oBAAoB,sDAAsD,CAAC"}

package/payload/platform/plugins/admin/mcp/dist/tools/account-lifecycle.js

@@ -109,6 +109,57 @@ export function provisionClientAccount(opts) {
     });
     return accountDir;
 }
+/** The provenance the root seed represents — matches the properties the cypher
+ *  below stamps (`createdByAgent='system'`, `createdBySource='installer'`), the
+ *  same shape `seed-neo4j.sh` writes for the house root. `agent:"system"` is the
+ *  convention `checkLabelOriginGate` exempts. The seed runs as raw cypher through
+ *  the admin session (not the memory-write chokepoint), so the gate never
+ *  actually evaluates it in production; this constant is not the write's
+ *  provenance carrier — it exists so a unit test can assert the gate *would*
+ *  permit this origin. */
+export const SEED_ORIGIN = { agent: "system", source: "installer" };
+/** Task 1359 — seed a client account's graph root: a bare :LocalBusiness{accountId}
+ *  plus its owner :AdminUser (fresh per-account userId) joined by :ADMIN_OF, in
+ *  one statement, then read both node existences back. Without this a created
+ *  client account is rootless: `checkGraphWriteGate` refuses every non-root
+ *  write and `checkLabelOriginGate` refuses the agent's attempt to create the
+ *  root, so the graph is unpopulatable.
+ *
+ *  Raw cypher through the admin session bypasses the memory-write gates by
+ *  construction (they guard only the memory-write chokepoint), mirroring
+ *  `seed-neo4j.sh`. The owner AdminUser carries a fresh `ownerUserId` because
+ *  AdminUser is MERGE-keyed on `userId` and COALESCEs `accountId`; reusing the
+ *  install owner's userId would keep `accountId=house` and leave the gate's
+ *  `MATCH (au:AdminUser {accountId: <client>})` empty. Single-shot per account:
+ *  MERGE on `LocalBusiness.accountId` (a UNIQUE key) makes a replay against the
+ *  same accountId safe, but it is NOT replay-idempotent under a different
+ *  `ownerUserId` (that would MERGE a second owner AdminUser); the sole caller
+ *  mints a new accountId per create and never replays. Returns the two
+ *  read-back booleans; the caller treats `businessSeeded && adminSeeded` as the
+ *  verified post-condition. */
+export async function seedAccountGraphRoot(args) {
+    const { session, accountId, ownerUserId, ownerName, createdAt } = args;
+    const res = await session.run(`MERGE (lb:LocalBusiness {accountId: $accountId})
+       ON CREATE SET lb.createdBySource = 'installer',
+                     lb.createdByAgent = 'system',
+                     lb.createdAt = datetime()
+     MERGE (au:AdminUser {userId: $ownerUserId})
+       ON CREATE SET au.accountId = $accountId,
+                     au.role = 'owner',
+                     au.name = $ownerName,
+                     au.createdAt = $createdAt
+       ON MATCH SET au.accountId = COALESCE(au.accountId, $accountId)
+     MERGE (au)-[r:ADMIN_OF]->(lb)
+       ON CREATE SET r.role = 'owner', r.grantedAt = $createdAt
+     WITH lb.accountId AS acct
+     RETURN COUNT { MATCH (b:LocalBusiness {accountId: acct}) } > 0 AS hasBusiness,
+            COUNT { MATCH (a:AdminUser {accountId: acct}) } > 0 AS hasAdmin`, { accountId, ownerUserId, ownerName, createdAt });
+    const rec = res.records[0];
+    return {
+        businessSeeded: Boolean(rec?.get("hasBusiness")),
+        adminSeeded: Boolean(rec?.get("hasAdmin")),
+    };
+}
 /** Cypher for the account-scoped node count and the irreversible purge. The
  *  purge deletes every node carrying the accountId (account scope is a property,
  *  never an edge — see CLAUDE.md), detaching its relationships. */

package/payload/platform/plugins/admin/mcp/dist/tools/account-lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"account-lifecycle.js","sourceRoot":"","sources":["../../src/tools/account-lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"account-lifecycle.js","sourceRoot":"","sources":["../../src/tools/account-lifecycle.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:86a7d5decfa1f569dcb4a23a7506fe36f23947c44dc68d4c43277be01c6418e2
+content-hash: sha256:6ab87c68af715d29cae2a3fa1273c434fb8c88cdbe96eb86e0c7216895625085
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2803,13 +2803,19 @@ authoritative. This section names the surfaces and what backs each.
 > **Admin variant only.** Every surface below belongs to the `admin` shell
 > variant. The **operator** variant (`operator.<host>`) mounts no sidebar at
 > all: its dashboard is the persistent admin webchat at `/` and the data
-> browser at `/data`, plus a read-only **Conversations** reader reached from a
-> dynamic burger item — header order Chat → Conversations → Data → Log out, in
-> a single-column `.platform.platform-operator` grid. The operator never sees
-> the sessions list or the nav rows; the Conversations reader lists the agent's
-> inbound channel conversations (WhatsApp, Telegram, public webchat) read-only
-> via the same admin-gated reader routes, never the operator's own session. The
-> operator surface is documented in full in the internal doc
+> browser at `/data`, plus a **Conversations** item reached from a dynamic
+> burger item — header order Chat → Conversations → Data → Log out, in a
+> single-column `.platform.platform-operator` grid. On the operator **chat**
+> surface the Conversations item opens the same in-chat session
+> switcher the admin `/chat` surface uses (`ChatSurface`'s `SessionList` flyout):
+> the operator's own admin webchat conversations, newest-first, each resuming
+> live via `/chat?session=<id>`, with rename / archive / delete / end / new — not
+> a read-only reader. The item gates on the flyout handler being wired, exactly
+> like the admin and lite items. The read-only inbound-channel **Conversations**
+> reader (WhatsApp, Telegram, public webchat, via the admin-gated
+> `/api/whatsapp-reader/conversations` route) remains on `/data`'s Conversations
+> item and in the admin Sidebar; it is no longer reachable from the operator chat
+> surface. The operator surface is documented in full in the internal doc
 > `maxy-code/.docs/operator-dashboard.md`.
 >
 > **Operator `/chat`.** The reduced operator chrome renders on
@@ -2833,15 +2839,17 @@ authoritative. This section names the surfaces and what backs each.
 > surface; the rest of the admin shell stays edge-to-edge. The public webchat
 > (`.public-surface`) inherits the same value.
 >
-> **Conversations item.** The dynamic Conversations burger item appears on
-> **both** the operator chat surface and `/data` whenever ≥1 reviewable
-> conversation exists (the count/channels are fetched per surface from
-> `/whatsapp-reader/conversations` with the operator's session key). On `/data`
-> selecting it renders the same read-only reader in place (the file browser is
-> swapped for it; Back returns). The flyout-open signal
-> `[operator-ui] op=conversations-menu present=<bool> channels=[…] count=<n>`
-> fires on `/data` too — `present=false` there while the chat surface shows the
-> item is the props-not-wired signature.
+> **Conversations item.** The dynamic Conversations burger item gates on the
+> host wiring its open-handler (like the admin and lite items), not on a channel
+> count. On the operator **chat** surface the handler is always wired, so the
+> item is always present and opens the live session switcher (above). On `/data`
+> the handler is wired only when ≥1 reviewable inbound conversation exists
+> (fetched from `/whatsapp-reader/conversations` with the operator's session
+> key), and selecting it renders the read-only reader in place (the file browser
+> is swapped for it; Back returns) — so `/data` keeps its hide-when-empty
+> behaviour. The flyout-open signal `[operator-ui] op=conversations-menu
+> present=<bool>` fires for the operator variant on both surfaces; `present=false`
+> while the operator expects the item is the handler-not-wired signature.
 
 | Surface | What it does | Backed by |
 |---|---|---|

package/payload/platform/plugins/cloudflare/references/hosting-sites.md

@@ -33,15 +33,18 @@ If the site captures form data, add the `[[d1_databases]]` binding from `d1-data
 
 ## 3. Load the reused deploy token
 
-A Pages deploy needs **Account · Cloudflare Pages · Edit**. If the site has Pages Functions hitting D1, the token also needs **Account · D1 · Edit** (the single most common breakage — see `d1-data-capture.md`). Load the stable per-scope token — minting it once only if absent — per `api.md` § Provisioning and reusing a stable per-scope token:
+A Pages deploy needs **Account · Cloudflare Pages · Edit**. If the site has Pages Functions hitting D1, the token also needs **Account · D1 · Edit** (the single most common breakage — see `d1-data-capture.md`). The `pages` scope resolves the stable `<brand>-pages-d1` token, which carries both. Resolve it with the deterministic helper, which mints it once only if absent and reuses it thereafter. This is the one command; do not source the secrets file and hand the resulting `CLOUDFLARE_API_TOKEN` to `wrangler` — that variable holds the **master**, not the per-scope token, and `wrangler pages` then returns `Authentication error [code: 10000]`:
 
 ```bash
+KEY=$(bash platform/plugins/cloudflare/bin/cf-token.sh pages "${SECRETS_DIR}/cloudflare.env")
 set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
-: "${CLOUDFLARE_API_TOKEN:?credentials not loaded}"; : "${CLOUDFLARE_ACCOUNT_ID:?account id not loaded}"
-# PAGES_D1 = the reused per-scope token (Pages Edit, + D1 Edit if the site uses D1),
-# loaded from cloudflare.env and minted once if absent — see api.md § Provisioning and reusing.
+: "${CLOUDFLARE_ACCOUNT_ID:?account id not loaded}"
+PAGES_D1="${!KEY}"   # the active Pages(+D1) per-scope token — NOT the sourced CLOUDFLARE_API_TOKEN (that is the master)
+: "${PAGES_D1:?per-scope token not resolved — re-run cf-token.sh and read its output}"
 ```
 
+A `10000` here is a token-selection symptom, not a permissions wall: it means the master reached `wrangler`. Re-run the helper line and retry with `${PAGES_D1}`; never fall back to a manual step on the strength of a `10000`. The mint-once, reuse, prefix-routing, and redaction details live in `api.md` § Provisioning and reusing a stable per-scope token; this command is self-contained and does not depend on reading that section first.
+
 ## 4. Deploy
 
 ```bash

package/payload/platform/plugins/cloudflare/skills/cloudflare/SKILL.md

@@ -9,7 +9,9 @@ Run by the admin/main session, the operator-infra surface that holds the `Bash`
 
 This is the entry point for every Cloudflare task on the install. Pick the operation class, read the matching reference, run the command via Bash, relay the literal output, and prove the outcome with a live signal. There are no Cloudflare MCP tools; the plugin registers none. The agent never browser-automates the dashboard — the operator clicks where a click is genuinely required.
 
-| You want to… | Read | Outcome contract |
+**How to open every `references/…` file named in this skill.** These reference files live at the plugin root (`platform/plugins/cloudflare/references/`), one directory above this skill. They are not children of the directory this skill announces as its base. Read each one with the `plugin-read` tool, which resolves the path plugin-root-relative: `plugin-read` with `file="references/api.md"` returns the file. A plain `Read` of `references/api.md` against this skill's announced base directory resolves to `.../skills/cloudflare/references/api.md`, which does not exist and returns "File does not exist". That miss is not a reason to skip the reference, to substitute a non-canonical file, or to improvise the command from memory. Use `plugin-read` for every `references/…` mention below, the same way the sibling `site-deploy` and `calendar-site` skills do.
+
+| You want to… | Read via `plugin-read` | Outcome contract |
 |---|---|---|
 | Stand up / diagnose / reset a tunnel so a hostname is reachable | `references/manual-setup.md` | external `curl -I https://<hostname>` → `200` |
 | Switch accounts, edit an apex CNAME by hand, or other dashboard-only clicks | `references/dashboard-guide.md` | the click-path completed in the operator's browser |
@@ -27,19 +29,20 @@ This is the entry point for every Cloudflare task on the install. Pick the opera
 
 Neither the master token nor any per-scope token is ever written into a project tree, committed, or echoed into chat — the per-scope tokens persist only in the account-scoped secrets file, never in a deployable project tree.
 
-### Token operations: run the helper first (binding)
+### Resolve the per-scope token before any `wrangler` / API call (binding)
 
-Before **any** Cloudflare API token operation (verify, list, mint, reuse), resolve the per-scope token with the deterministic helper, never a hand-built `curl`:
+This binding governs **every** Pages, D1, DNS, or Access operation, not only calls you think of as "token operations." Before the first `wrangler pages …`, `wrangler d1 …`, or Cloudflare-API `curl` of a task, resolve the per-scope token with the deterministic helper and pass **that** token to the command:
 
 ```bash
 KEY=$(bash platform/plugins/cloudflare/bin/cf-token.sh <scope> <secrets-file>)   # scope: pages | d1 | dns | access
 set -a; . <secrets-file>; set +a
-# the active, persisted per-scope token is now in the variable named by $KEY
+# ${!KEY} now holds the active, persisted per-scope token. Pass it explicitly:
+CLOUDFLARE_API_TOKEN="${!KEY}" wrangler pages project list
 ```
 
-The helper owns the one decision the false-negative failure turns on: it reads the master's `cfat_`/`cfut_` prefix and routes verify, `permission_groups`, and mint to the matching endpoint family, mints once if absent (no expiry), verifies through the transient post-mint window, persists to the secrets file, and prints only the secrets key name. It never prints a token value.
+**The antipattern this exists to stop.** Sourcing the secrets file loads the **master** token into `CLOUDFLARE_API_TOKEN`. If you then run `wrangler pages …` (or a Cloudflare-API `curl`) with the environment as-sourced, you hand the **master** to the tool, not the per-scope token. The master is the wrong token for these endpoints, so Cloudflare rejects the call, and the rejection reads like a permissions wall when it is really a token-selection mistake. `. <secrets-file>` immediately followed by `wrangler pages …` is the exact sequence that trips this; the helper line above is what prevents it. Never let `CLOUDFLARE_API_TOKEN` reach `wrangler`/`curl` still holding the sourced master.
 
-A raw `curl` to a token endpoint chosen **before** the master's prefix is established is out of bounds. The wrong endpoint returns a stable false-negative that reads as "cannot mint" but is not: a `cfat_` master at `/user/tokens/verify` returns `Invalid API Token`, and a `cfut_` master at any `/accounts/{id}/...` endpoint returns `9109`. If you see either from a token probe, the cause is the endpoint, not the token. Stop and run the helper. Doing the verify or mint by hand is permitted only after reading the `references/api.md` section on routing token endpoints by prefix, and routing by the established prefix.
+**A `10000` / `Invalid API Token` / `9109` from a `wrangler` or API call is a token-selection symptom, never "this token lacks permission."** The recovery is always the same: run `cf-token.sh <scope> <secrets-file>` and re-issue the command with the resolved per-scope token. Concretely: a just-sourced master handed to `wrangler pages …` returns `Authentication error [code: 10000]`; a `cfat_` master at `/user/tokens/verify` returns `Invalid API Token`; a `cfut_` master at any `/accounts/{id}/...` endpoint returns `9109`. None of these means "cannot deploy" or "lacks Pages/DNS permission." Do not fall back to a manual DNS record, a tunnel workaround, or an operator ask on the strength of one of these codes — run the helper and retry. The helper reads the master's `cfat_`/`cfut_` prefix, routes verify/`permission_groups`/mint to the matching endpoint family, mints once if absent (no expiry), verifies through the transient post-mint window, persists to the secrets file, and prints only the secrets key name; it never prints a token value. Doing verify or mint by hand is permitted only after reading the `references/api.md` section on routing token endpoints by prefix, and routing by the established prefix.
 
 ## Outcome contracts — what "done" means
 

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -323,13 +323,19 @@ authoritative. This section names the surfaces and what backs each.
 > **Admin variant only.** Every surface below belongs to the `admin` shell
 > variant. The **operator** variant (`operator.<host>`) mounts no sidebar at
 > all: its dashboard is the persistent admin webchat at `/` and the data
-> browser at `/data`, plus a read-only **Conversations** reader reached from a
-> dynamic burger item — header order Chat → Conversations → Data → Log out, in
-> a single-column `.platform.platform-operator` grid. The operator never sees
-> the sessions list or the nav rows; the Conversations reader lists the agent's
-> inbound channel conversations (WhatsApp, Telegram, public webchat) read-only
-> via the same admin-gated reader routes, never the operator's own session. The
-> operator surface is documented in full in the internal doc
+> browser at `/data`, plus a **Conversations** item reached from a dynamic
+> burger item — header order Chat → Conversations → Data → Log out, in a
+> single-column `.platform.platform-operator` grid. On the operator **chat**
+> surface the Conversations item opens the same in-chat session
+> switcher the admin `/chat` surface uses (`ChatSurface`'s `SessionList` flyout):
+> the operator's own admin webchat conversations, newest-first, each resuming
+> live via `/chat?session=<id>`, with rename / archive / delete / end / new — not
+> a read-only reader. The item gates on the flyout handler being wired, exactly
+> like the admin and lite items. The read-only inbound-channel **Conversations**
+> reader (WhatsApp, Telegram, public webchat, via the admin-gated
+> `/api/whatsapp-reader/conversations` route) remains on `/data`'s Conversations
+> item and in the admin Sidebar; it is no longer reachable from the operator chat
+> surface. The operator surface is documented in full in the internal doc
 > `maxy-code/.docs/operator-dashboard.md`.
 >
 > **Operator `/chat`.** The reduced operator chrome renders on
@@ -353,15 +359,17 @@ authoritative. This section names the surfaces and what backs each.
 > surface; the rest of the admin shell stays edge-to-edge. The public webchat
 > (`.public-surface`) inherits the same value.
 >
-> **Conversations item.** The dynamic Conversations burger item appears on
-> **both** the operator chat surface and `/data` whenever ≥1 reviewable
-> conversation exists (the count/channels are fetched per surface from
-> `/whatsapp-reader/conversations` with the operator's session key). On `/data`
-> selecting it renders the same read-only reader in place (the file browser is
-> swapped for it; Back returns). The flyout-open signal
-> `[operator-ui] op=conversations-menu present=<bool> channels=[…] count=<n>`
-> fires on `/data` too — `present=false` there while the chat surface shows the
-> item is the props-not-wired signature.
+> **Conversations item.** The dynamic Conversations burger item gates on the
+> host wiring its open-handler (like the admin and lite items), not on a channel
+> count. On the operator **chat** surface the handler is always wired, so the
+> item is always present and opens the live session switcher (above). On `/data`
+> the handler is wired only when ≥1 reviewable inbound conversation exists
+> (fetched from `/whatsapp-reader/conversations` with the operator's session
+> key), and selecting it renders the read-only reader in place (the file browser
+> is swapped for it; Back returns) — so `/data` keeps its hide-when-empty
+> behaviour. The flyout-open signal `[operator-ui] op=conversations-menu
+> present=<bool>` fires for the operator variant on both surfaces; `present=false`
+> while the operator expects the item is the handler-not-wired signature.
 
 | Surface | What it does | Backed by |
 |---|---|---|

package/payload/platform/plugins/email/skills/email-composition/SKILL.md

@@ -21,7 +21,7 @@ Activate when the operator asks for any of:
 Do **not** activate for:
 
 - Listing or searching emails as the end-goal (no draft intent) — let `email-search` / `email-graph-query` answer directly.
-- Setup, status checks, OTP extraction — those are direct tool calls. (For Google/Workspace setup the agent must require an app password, never the regular password — see the email plugin's `references/email-reference.md` § Setup → Google. For Microsoft / Microsoft 365 addresses there is no email-plugin path at all — register via the `outlook` Graph plugin's `outlook-account-register`, not `email-setup` — see § Setup → Microsoft.)
+- Setup, status checks, OTP extraction — those are direct tool calls. (For Google/Workspace setup the agent must require an app password, never the regular password — see the email plugin's `references/email-reference.md` § Setup → Google, opened with the `plugin-read` tool (`file="references/email-reference.md"`), which resolves it at the plugin root; a plain `Read` against this skill's base directory misses. For Microsoft / Microsoft 365 addresses there is no email-plugin path at all — register via the `outlook` Graph plugin's `outlook-account-register`, not `email-setup` — see § Setup → Microsoft.)
 - Any automated send loop. If the operator asks for drip / scheduled / broadcast sends, decline and explain that this skill is human-in-the-loop only.
 
 ## Flow — reply to an existing thread

package/payload/platform/plugins/outlook/skills/outlook/SKILL.md

@@ -63,5 +63,7 @@ Subsequent tool calls use the persisted refresh token to mint access tokens tran
 
 ## Reference files
 
+Open each with the `plugin-read` tool (`file="references/auth.md"`), which resolves the path at the plugin root. A plain `Read` of `references/auth.md` against this skill's base directory misses, because these files live one level up at the plugin root, not under the skill.
+
 - [`references/auth.md`](references/auth.md) — Entra app registration + PKCE flow + re-vendor procedure
 - [`references/graph-surfaces.md`](references/graph-surfaces.md) — Graph endpoint and response shape per tool

package/payload/platform/plugins/telegram/skills/configure/SKILL.md

@@ -22,6 +22,8 @@ A finished Telegram setup has all of these, and the skill is not done until each
 
 ## Flow
 
+Read `references/setup-guide.md` (cited throughout this flow) with the `plugin-read` tool (`file="references/setup-guide.md"`), which resolves it at the plugin root. A plain `Read` against this skill's base directory misses, because the file lives one level up at the plugin root, not under the skill.
+
 ### Step 1 — Get the bot token
 
 Follow `references/setup-guide.md` "Creating a Bot": the operator creates the bot via @BotFather and gives you the token (e.g. `123456:ABC-DEF…`). Confirm you have it before continuing.

package/payload/platform/scripts/__tests__/check-plugin-references.test.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Task 1362 — the reference-reachability guard.
+# A SKILL.md's plugin-root-only bare `references/…` citation is reachable ONLY
+# when the SKILL.md declares the `plugin-read` convention. Without it, a plain
+# Read against the announced skill base dir misses, so the citation is a
+# violation. Skill-local references, full `plugins/<name>/references/…` paths,
+# and PLUGIN.md plugin-root references are unaffected.
+set -u
+GATE="$(cd "$(dirname "$0")/.." && pwd)/check-plugin-references.mjs"
+[[ -f "$GATE" ]] || { echo "FAIL: gate script missing at $GATE" >&2; exit 1; }
+PASS=0; FAIL=0
+
+ROOT=$(mktemp -d)
+PREMIUM="$ROOT/premium-empty"
+mkdir -p "$PREMIUM"
+trap 'rm -rf "$ROOT"' EXIT
+
+reset_root() { rm -rf "$ROOT/platform"; }
+
+# Write a SKILL.md for plugin "$1" (skill slug == plugin name) with body "$2".
+make_skill() {
+  local plugin="$1" body="$2"
+  local dir="$ROOT/platform/plugins/$plugin/skills/$plugin"
+  mkdir -p "$dir"
+  { printf -- '---\nname: %s\ndescription: test skill\n---\n\n' "$plugin"; printf '%s\n' "$body"; } > "$dir/SKILL.md"
+}
+
+# Create a reference file at an arbitrary path under $ROOT.
+make_ref() { local rel="$1"; mkdir -p "$ROOT/$(dirname "$rel")"; printf 'ref body\n' > "$ROOT/$rel"; }
+
+check() {
+  local desc="$1" expected="$2"
+  node "$GATE" "$ROOT/platform" "$PREMIUM" >/dev/null 2>&1
+  local got=$?
+  if [[ "$got" -eq "$expected" ]]; then echo "PASS: $desc"; ((PASS++))
+  else echo "FAIL: $desc (expected exit $expected, got $got)"; ((FAIL++)); fi
+}
+
+# CASE 1: plugin-root-only ref, NO plugin-read declared → violation.
+reset_root
+make_ref "platform/plugins/foo/references/api.md"
+make_skill "foo" 'Read \`references/api.md\` before the API call.'
+check "plugin-root-only ref without plugin-read fails" 1
+
+# CASE 2: same ref, plugin-read declared → passes.
+reset_root
+make_ref "platform/plugins/foo/references/api.md"
+make_skill "foo" 'Open \`references/api.md\` with the \`plugin-read\` tool before the API call.'
+check "plugin-root-only ref with plugin-read passes" 0
+
+# CASE 3: skill-local ref, NO plugin-read → passes (plain Read resolves it).
+reset_root
+make_ref "platform/plugins/foo/skills/foo/references/local.md"
+make_skill "foo" 'Read \`references/local.md\` for the details.'
+check "skill-local ref without plugin-read passes" 0
+
+# CASE 4: full plugins/<name>/references/... path, NO plugin-read → passes.
+reset_root
+make_ref "platform/plugins/foo/references/api.md"
+make_skill "foo" 'Read \`plugins/foo/references/api.md\` before the API call.'
+check "full plugin-path ref without plugin-read passes" 0
+
+# CASE 5: genuinely missing ref (neither skill-local nor plugin-root) → violation.
+reset_root
+make_skill "foo" 'Open \`references/ghost.md\` with \`plugin-read\`.'
+check "missing ref fails even with plugin-read" 1
+
+# CASE 6: a MISSING full plugins/<name>/references/... path from a SKILL.md without
+# plugin-read → violation, and the plugin-root "declare plugin-read" hint must NOT
+# fire (the hint is scoped to the bare references/ shape only; a full path is not
+# reachability-limited by the missing convention). Guards the Task 1362 hint-scope fix.
+reset_root
+make_skill "foo" 'Read \`plugins/foo/references/ghost.md\` before the API call.'
+OUT=$(node "$GATE" "$ROOT/platform" "$PREMIUM" 2>&1); GOT=$?
+if [[ "$GOT" -eq 1 ]] && ! grep -q "exists at plugin root" <<<"$OUT"; then
+  echo "PASS: missing full-path ref fails without a false plugin-read hint"; ((PASS++))
+else
+  echo "FAIL: missing full-path ref (exit=$GOT, hint present=$(grep -qc 'exists at plugin root' <<<"$OUT" && echo yes || echo no))"; ((FAIL++))
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ "$FAIL" -eq 0 ]] && exit 0 || exit 1

package/payload/platform/scripts/check-plugin-references.mjs

@@ -17,6 +17,21 @@
 //   2. `plugins/<name>/references/<file>.md` (optionally prefixed by
 //      `platform/`) — resolves at `<platformRoot>/plugins/<name>/references/
 //      <file>.md`.
+//
+// Task 1362 — access-method tightening for SKILL.md bare references.
+// A SKILL.md announces its own skill directory as the base dir. An agent that
+// reads "references/foo.md" with a plain file `Read` resolves it against that
+// base dir → `<skill-dir>/references/foo.md`. When the reference actually lives
+// at the plugin root (`<plugin-root>/references/foo.md`, the shared layout the
+// cloudflare/outlook/telegram/email plugins use) that plain read MISSES, and the
+// agent gets "File does not exist" — the reliability trap Task 1362 removes.
+// The plugin-root path is only reachable if the SKILL.md tells the agent to read
+// via the `plugin-read` tool (which resolves plugin-root-relative). So for a bare
+// reference cited from a SKILL.md, the plugin-root candidate counts ONLY when that
+// SKILL.md declares the `plugin-read` convention; without it, the skill-local path
+// is the sole candidate and a plugin-root-only reference is a violation. PLUGIN.md
+// is itself a plugin-root doc always read via plugin-read, so its plugin-root
+// candidate is unconditional (unchanged).
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { resolve, relative, join, dirname } from "node:path";
@@ -85,23 +100,25 @@ function owningPluginRoot(filePath) {
 
 // Directories to resolve a bare `references/<file>.md` citation against.
 // Returns an array of candidate directories; the citation passes if the file
-// exists under ANY of them. Both candidate paths for SKILL.md are reachable
-// via `plugin-read` — the agent may construct `file=references/foo.md`
-// (plugin-root form) or `file=skills/<slug>/references/foo.md` (skill-local
-// form), depending on how the plugin organises its references.
+// exists under ANY of them.
 //
 //   PLUGIN.md       — plugin-root only.       → [<plugin-root>]
-//   SKILL.md        — skill-local OR plugin-root.
-//                                              → [<skill-dir>, <plugin-root>]
+//   SKILL.md        — skill-local always; plugin-root ONLY when the SKILL.md
+//                     declares the `plugin-read` convention (Task 1362). A plain
+//                     `Read` from a SKILL.md resolves against the announced skill
+//                     dir, so a plugin-root-only reference is unreachable unless
+//                     the SKILL.md routes the read through `plugin-read`.
+//                                              → [<skill-dir>] or
+//                                                [<skill-dir>, <plugin-root>]
 //   specialist template — no owning context.   → []
-function bareReferenceContextDirs(filePath) {
+function bareReferenceContextDirs(filePath, declaresPluginRead) {
   if (filePath.endsWith("/PLUGIN.md")) {
     return [dirname(filePath)];
   }
   if (filePath.endsWith("/SKILL.md")) {
     const skillDir = dirname(filePath);
     const pluginRoot = owningPluginRoot(filePath);
-    return pluginRoot ? [skillDir, pluginRoot] : [skillDir];
+    return pluginRoot && declaresPluginRead ? [skillDir, pluginRoot] : [skillDir];
   }
   return [];
 }
@@ -110,7 +127,7 @@ function bareReferenceContextDirs(filePath) {
 // citation passes the existence check if ANY candidate exists. Returns an
 // empty array if the citation has no resolvable shape (bare reference cited
 // from a non-plugin file).
-function candidateTargets({ raw, sourcePath, platformRoot }) {
+function candidateTargets({ raw, sourcePath, platformRoot, declaresPluginRead }) {
   // Strip an optional leading `platform/` so `platform/plugins/<name>/...`
   // and `plugins/<name>/...` resolve identically.
   const normalised = raw.replace(/^platform\//, "");
@@ -130,7 +147,7 @@ function candidateTargets({ raw, sourcePath, platformRoot }) {
   }
 
   // Bare `references/<file>.md`.
-  const ctxDirs = bareReferenceContextDirs(sourcePath);
+  const ctxDirs = bareReferenceContextDirs(sourcePath, declaresPluginRead);
   return ctxDirs.map(d => resolve(d, normalised));
 }
 
@@ -141,6 +158,10 @@ function scanFile(filePath, { platformRoot, repoRoot }) {
   } catch {
     return { violations: [], citations: 0 };
   }
+  // Whether this file routes its bare references through the `plugin-read` tool.
+  // Governs whether a SKILL.md's plugin-root reference candidate is reachable
+  // (Task 1362 — see bareReferenceContextDirs). PLUGIN.md ignores this.
+  const declaresPluginRead = /plugin-read/.test(body);
   const violations = [];
   let citations = 0;
   const lines = body.split("\n");
@@ -153,7 +174,7 @@ function scanFile(filePath, { platformRoot, repoRoot }) {
       // 1-based column, pointing at the start of the captured citation.
       const column = (m.index + m[0].indexOf(raw)) + 1;
       citations++;
-      const candidates = candidateTargets({ raw, sourcePath: filePath, platformRoot });
+      const candidates = candidateTargets({ raw, sourcePath: filePath, platformRoot, declaresPluginRead });
       if (candidates.length === 0) {
         violations.push({
           source: relative(repoRoot, filePath),
@@ -171,12 +192,39 @@ function scanFile(filePath, { platformRoot, repoRoot }) {
         const targetMsg = candidates.length === 1
           ? candidates[0]
           : `none of [${candidates.join(", ")}]`;
+        // Task 1362 hint: a SKILL.md BARE `references/<file>.md` citation that
+        // misses skill-local but DOES exist at the plugin root is an access-method
+        // defect, not a missing file. The fix is to declare `plugin-read` (or write
+        // the full `plugins/<name>/references/...` path), not to create a skill-local
+        // copy. Restrict the hint to the bare shape: a citation already written as a
+        // full `plugins/.../references/...` (or `skills/.../references/...`) path is
+        // resolved elsewhere and is not reachability-limited by a missing convention,
+        // so it gets no hint (and its `raw` would resolve to a bogus nested path here).
+        let hint;
+        const isBareRef = raw.replace(/^platform\//, "").startsWith("references/");
+        if (
+          isBareRef &&
+          filePath.endsWith("/SKILL.md") &&
+          !declaresPluginRead &&
+          owningPluginRoot(filePath)
+        ) {
+          const rootCandidate = resolve(
+            owningPluginRoot(filePath),
+            raw.replace(/^platform\//, ""),
+          );
+          if (existsSync(rootCandidate)) {
+            hint =
+              `exists at plugin root (${relative(repoRoot, rootCandidate)}) but this SKILL.md does not declare the \`plugin-read\` convention, ` +
+              `so a plain Read misses it — declare \`plugin-read\` or cite the full \`plugins/<name>/references/...\` path`;
+          }
+        }
         violations.push({
           source: relative(repoRoot, filePath),
           line: i + 1,
           column,
           target: targetMsg,
           raw,
+          ...(hint ? { hint } : {}),
         });
       }
     }
@@ -244,6 +292,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
       console.error(`  source: ${v.source}:${v.line}:${v.column}`);
       console.error(`  cites:  ${v.raw}`);
       console.error(`  target: ${v.target}`);
+      if (v.hint) console.error(`  hint:   ${v.hint}`);
     }
     console.error(
       `FATAL: ${r.violations.length} broken reference citation(s) across ${r.scanned} scanned file(s) (${r.citations} citations).`,