@rubytech/create-maxy-code 0.1.383 → 0.1.386

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:6a2a7d9672033ab7af53bc389dfd77c9462949665ee53614374147811c0921ef
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2553,7 +2553,7 @@ either is a regression.
 
 **`/chat` header always shows the account name.** The admin/operator `HeaderMenu` centre always renders the active account's name alongside the brand logo, on every chat surface, regardless of the active conversation — `headerTitle = businessName || brand.productName`. There is no per-conversation header title: the active conversation's label stays in the sidebar and the Conversations flyout (each resolves its own per-session title independently), never in the header. The account name is `LocalBusiness.name`, resolved by `fetchAccountName(accountId)` in `neo4j-store.ts` with **no theme gate** — unlike `fetchBranding` (which returns null unless a colour/logo property is also set, and stays the source for actual theming). The house account is seeded with `LocalBusiness.name = <brand productName>` (`seed-neo4j.sh`, coalesced ON MATCH so a re-seed backfills a name-less node and never clobbers a name the business-profile recorder set later), so the sub-account picker's house row shows the product name (e.g. "SiteDesk"), not the raw accountId UUID. When a name is absent the resolver emits `[branding] account-name-fallback accountId=<id8>… reason=no-name`, and the picker falls back to the accountId; the seed + backfill is the name source. The lite variant header is unchanged.
 
-**`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp reader (`/whatsapp`) omits the prop and keeps the default `renderTimeline`, so its rendering is unchanged; both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
+**`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp/operator reader (`/whatsapp`, `OperatorConversations`) omits the prop and keeps the default `renderTimeline`, so its bubble/DM chrome is unchanged — except that since the attachment-render extraction the default renderer draws inbound `operator-inbound` uploads and `agent-file` deliveries inline (image thumbnail / pdf.js preview / audio player / download chip) via the attachment renderer shared with `/chat`, extracted to `app/chat/attachment-render.tsx` to break the cycle with `transcript-render.tsx`; `renderChatTimeline` is untouched. Both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`, `app/chat/__tests__/pdf-preview.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
 
 **`/chat` live activity line.** While a turn is in flight the transcript tail shows one ephemeral `ChatActivity` line (mounted only while `busy`, admin/operator only). It tracks real activity, not a timer: while a `Task` subagent runs it shows that subagent's headline (`agentType · description`, prefixed `N agents ·` when ≥2 are concurrent), sourced from `agent-<hex>.meta.json` via named `activity` SSE events the admin reader pushes from the session's `subagents/` dir; with no subagent active it shows a neutral word that advances only on a real turn arrival. The line carries a turn-elapsed clock and flips to a `stalled` state once nothing has been written for 5 minutes (`now − lastEmitAt`), so the operator can tell a wedge from progress without SSH. It is never added to the persisted timeline. Detail and the `[webchat-activity]` observability live in [`admin-webchat-native-channel.md`](../../../.docs/admin-webchat-native-channel.md).
 
@@ -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
@@ -2819,6 +2825,17 @@ authoritative. This section names the surfaces and what backs each.
 > operator shell. Unlike the operator root — which forces the canonical session
 > — operator `/chat` honors `?session=`, opening a specific session inside the
 > reduced shell. Admin-host `/chat` is unchanged (full developer shell).
+> **Sub-account switch resets the session target.** Because `/chat` honors
+> `?session=`, the header sub-account switcher (`useSubAccountSwitcher`) drops
+> the `session` query param when it navigates after a switch, rather than
+> reloading verbatim. A verbatim reload would keep the *previous* account's
+> `?session=<id>`, which the reloaded surface re-pins — stranding the operator
+> on the wrong account's session . Dropping the param lands on the
+> account-scoped canonical surface, so `resolveCanonical` resolves the switched
+> account's latest owned session, or the new-session splash when it has none.
+> The pathname is preserved (a switch on `/chat` stays on `/chat`); the operator
+> root `/` and bare `/chat` were always correct (they force-ignore / carry no
+> `?session=`).
 >
 > **Width.** The operator header, the operator chat column, and the `/data`
 > header+toolbar+body all render in one centred column bounded to
@@ -2833,15 +2850,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

@@ -73,7 +73,7 @@ either is a regression.
 
 **`/chat` header always shows the account name.** The admin/operator `HeaderMenu` centre always renders the active account's name alongside the brand logo, on every chat surface, regardless of the active conversation — `headerTitle = businessName || brand.productName`. There is no per-conversation header title: the active conversation's label stays in the sidebar and the Conversations flyout (each resolves its own per-session title independently), never in the header. The account name is `LocalBusiness.name`, resolved by `fetchAccountName(accountId)` in `neo4j-store.ts` with **no theme gate** — unlike `fetchBranding` (which returns null unless a colour/logo property is also set, and stays the source for actual theming). The house account is seeded with `LocalBusiness.name = <brand productName>` (`seed-neo4j.sh`, coalesced ON MATCH so a re-seed backfills a name-less node and never clobbers a name the business-profile recorder set later), so the sub-account picker's house row shows the product name (e.g. "SiteDesk"), not the raw accountId UUID. When a name is absent the resolver emits `[branding] account-name-fallback accountId=<id8>… reason=no-name`, and the picker falls back to the accountId; the seed + backfill is the name source. The lite variant header is unchanged.
 
-**`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp reader (`/whatsapp`) omits the prop and keeps the default `renderTimeline`, so its rendering is unchanged; both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
+**`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp/operator reader (`/whatsapp`, `OperatorConversations`) omits the prop and keeps the default `renderTimeline`, so its bubble/DM chrome is unchanged — except that since the attachment-render extraction the default renderer draws inbound `operator-inbound` uploads and `agent-file` deliveries inline (image thumbnail / pdf.js preview / audio player / download chip) via the attachment renderer shared with `/chat`, extracted to `app/chat/attachment-render.tsx` to break the cycle with `transcript-render.tsx`; `renderChatTimeline` is untouched. Both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`, `app/chat/__tests__/pdf-preview.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
 
 **`/chat` live activity line.** While a turn is in flight the transcript tail shows one ephemeral `ChatActivity` line (mounted only while `busy`, admin/operator only). It tracks real activity, not a timer: while a `Task` subagent runs it shows that subagent's headline (`agentType · description`, prefixed `N agents ·` when ≥2 are concurrent), sourced from `agent-<hex>.meta.json` via named `activity` SSE events the admin reader pushes from the session's `subagents/` dir; with no subagent active it shows a neutral word that advances only on a real turn arrival. The line carries a turn-elapsed clock and flips to a `stalled` state once nothing has been written for 5 minutes (`now − lastEmitAt`), so the operator can tell a wedge from progress without SSH. It is never added to the persisted timeline. Detail and the `[webchat-activity]` observability live in [`admin-webchat-native-channel.md`](../../../.docs/admin-webchat-native-channel.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
@@ -339,6 +345,17 @@ authoritative. This section names the surfaces and what backs each.
 > operator shell. Unlike the operator root — which forces the canonical session
 > — operator `/chat` honors `?session=`, opening a specific session inside the
 > reduced shell. Admin-host `/chat` is unchanged (full developer shell).
+> **Sub-account switch resets the session target.** Because `/chat` honors
+> `?session=`, the header sub-account switcher (`useSubAccountSwitcher`) drops
+> the `session` query param when it navigates after a switch, rather than
+> reloading verbatim. A verbatim reload would keep the *previous* account's
+> `?session=<id>`, which the reloaded surface re-pins — stranding the operator
+> on the wrong account's session . Dropping the param lands on the
+> account-scoped canonical surface, so `resolveCanonical` resolves the switched
+> account's latest owned session, or the new-session splash when it has none.
+> The pathname is preserved (a switch on `/chat` stays on `/chat`); the operator
+> root `/` and bare `/chat` were always correct (they force-ignore / carry no
+> `?session=`).
 >
 > **Width.** The operator header, the operator chat column, and the `/data`
 > header+toolbar+body all render in one centred column bounded to
@@ -353,15 +370,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