@rubytech/create-maxy-code 0.1.469 → 0.1.471

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:c2a25fe4d72c9db00a75f700eb4642cb78ac01835892daf406e7bf0f438a9bb8
+content-hash: sha256:46e07a18921b711849e53f63b8c29b72f3324f91bc682eb5be585ccd64c98971
 brand: maxy-code
 product-name: Maxy
 ---
@@ -606,6 +606,54 @@ Pausing keeps a workflow but stops it running. Editing replaces the steps or the
 
 A workflow can run on a schedule instead of on demand. Tell Maxy when you want it to run, for example "run the daily summary workflow every morning at eight," and it sets up the schedule. Scheduled runs happen with no one present, so a workflow that needs you to supply inputs is best run on demand rather than scheduled.
 
+---
+# Cash Book + AR/AP Ledger
+Source: https://docs.getmaxy.com/ledger.md
+
+# Ledger
+
+A cash book with receivables and payables. It records what you invoiced, what you were billed, what was paid, and money that moved without an invoice, then tells you what is still outstanding.
+
+## What it is not
+
+It is not double-entry bookkeeping. There is no chart of accounts, no journals, no trial balance. It computes no VAT and handles a single currency. It does not read bank feeds and it does not talk to QuickBooks.
+
+If you need statutory accounts, this is not that. It is the answer to "who owes me what, what do I owe, and where did the money go".
+
+## The seven things you can ask for
+
+**Record an invoice you raised.** A reference, who owes you, the amount, and when it is due.
+
+**Record a bill you received.** The same, in the other direction.
+
+**Record a payment.** Against either an invoice or a bill. You give the reference, the amount, the date and how it was paid.
+
+**Record a credit.** Against an invoice you raised. It reduces what is owed exactly as a payment does.
+
+**Record a cash movement.** Money in or out that belongs to no invoice: bank charges, a cash sale, drawings, a refund.
+
+**Ask what is outstanding on one document.** You get the total, what has been paid, what has been credited, and what remains.
+
+**Ask for a statement.** Everything owed to you and everything you owe, sorted into 0-30, 31-60, 61-90 and 90+ days overdue, plus net cash.
+
+## Three behaviours worth knowing about
+
+**What is outstanding is never stored.** It is worked out from the payments each time you ask. This means the figure cannot fall out of step with the payments behind it. If it were stored, a payment recorded by any route that forgot to update it would leave the invoice quietly reporting a wrong number, and nothing would fail.
+
+**Paying more than is owed is refused.** If an invoice has 4,400 left and you try to record 5,000, nothing is written and you are told the figure that would settle it. It is not rounded down to 4,400 and it is not recorded anyway. A ledger that quietly accepts an impossible payment is worse than one that says no.
+
+**Every payment is read back.** After a payment is written, the invoice is re-read from the graph and the outstanding figure is checked against what was expected. If they disagree you are told to stop recording against that invoice until it is sorted out. Writing something is not the same as it having landed.
+
+## The health check
+
+Some ways this can go wrong announce themselves. Others do not: a payment that ends up attached to no invoice, a stale balance field reappearing, or the same payment recorded twice under two different ids. None of those produce an error at the time, because nothing goes wrong at the moment they happen.
+
+So there is a check that runs by itself every fifteen minutes and writes one line to the log beginning `[ledger-census]`. When it is healthy the counters are all zero. When something is wrong the line ends with `alarm=true` and says which of the four it found.
+
+You can also ask for that check on demand at any time, and it reports the same thing in plain words.
+
+If you never see the line at all, that is itself the problem: it means the periodic check is not running.
+
 ---
 # Install Overview
 Source: https://docs.getmaxy.com/install.md
@@ -2152,6 +2200,79 @@ Latency triage: `mail-list count=0 elapsedMs<200` consistent → permissions iss
 
 Mail move to arbitrary folders / flag, hard (permanent) delete, removing an attachment from a **sent** message (Graph forbids it), ingesting reviewed mail into the business graph (the `email-ingest` analogue), contacts write, recurring-series occurrence editing, the `scheduling` Neo4j calendar and any auto-sync with it, OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`), public-agent exposure, multi-tenant federation. Mail read, full-body read, inbound attachment list/download, reply, delete (to Deleted Items), and compose — all four outbound paths carrying attachments, with a draft's attachments editable in place (add, remove, replace) — are supported (`outlook-mail-fetch-body`, `outlook-mail-attachment`, `outlook-mail-reply`, `outlook-mail-delete`, `outlook-mail-otp-extract`, `outlook-mail-send`, `outlook-draft`, `outlook-draft-edit`, `outlook-draft-send`), and the calendar is read plus control. See `platform/plugins/outlook/PLUGIN.md` for the full out-of-scope list.
 
+---
+# Google Calendar
+Source: https://docs.getmaxy.com/google-guide.md
+
+# Google Calendar
+
+Live Google Calendar for one account: read the user's real events, and create,
+update, cancel, respond to and check availability against them. Eleven tools,
+admin agent only.
+
+There is deliberately no Gmail surface here. Mail runs on the `email` plugin's
+IMAP/SMTP path, and Gmail's read/modify scopes are *restricted*, which would
+force Google's annual third-party security assessment. Calendar is only a
+*sensitive* scope, so it needs the lighter brand verification.
+
+## Connecting an account
+
+`google-account-register` returns a consent URL. Relay it to the user: they open
+it on any device, sign in, and approve. Google redirects to this install's
+public host at `/api/google/oauth/callback`, which exchanges the code and stores
+encrypted tokens. `google-account-register-poll` then reports the outcome.
+
+The register tool does not block and does not wait. A second register while one
+is already live is refused rather than overwriting it; that refusal names how
+long the live one has been pending.
+
+One account can connect several Google accounts. Every operational tool takes an
+optional `account` (the email address). Omit it when there is one; with two or
+more, omitting it returns a refusal listing them.
+
+## Reading and controlling
+
+- `google-calendar-list` — events in the next `rangeDays` days (default 7).
+  Recurring series are expanded into instances, so this returns what the user
+  actually sees in their calendar.
+- `google-calendar-event` — one event by id.
+- `google-calendar-create` — times are RFC3339 (`2026-07-20T09:00:00Z`) unless
+  `allDay` is true, in which case they are plain dates (`2026-07-20`).
+- `google-calendar-update` — changes only the fields you name. Omitted fields
+  are left alone, so an update never blanks something by accident.
+- `google-calendar-cancel` — deletes the event and notifies attendees.
+- `google-calendar-respond` — accept, decline or tentatively accept an
+  invitation. Every other attendee's response is preserved.
+- `google-calendar-freebusy` — busy blocks between two times. Free time is the
+  complement, which you work out.
+
+## Checking health
+
+`google-account-list` answers "is anything connected?" from local stores with no
+network call. Read each entry's `status` — a count alone is not "connected", and
+an unreadable store still counts. `google-account-info` gives one account's auth
+state, including whether its access token is near expiry and which scopes were
+granted.
+
+## When something is wrong
+
+**"GOOGLE_CLIENT_ID is not configured"** — this brand has no Google vendor app
+yet. Nothing the operator does on the device fixes it; the brand needs its own
+Google Cloud OAuth client. See `platform/plugins/google/references/auth.md`.
+
+**A 403 naming insufficient scope** — the connected account approved something
+narrower than the full calendar scope. Re-run `google-account-register` so they
+re-consent.
+
+**The user re-consents every week** — the brand's Google app is still in
+Testing, where Google caps refresh tokens at seven days and limits the app to
+100 named test users. Completing brand verification removes both. This is a
+property of the vendor app, not a fault in the connection.
+
+**A registration never completes** — the consent URL was opened but not
+approved, or the callback could not be reached. `google-account-register-poll`
+reports `expired` once the pending entry outlives Google's code lifetime.
+
 ---
 # QuickBooks Online
 Source: https://docs.getmaxy.com/quickbooks.md
@@ -3065,6 +3186,54 @@ A 0.000 reading that persists across many polls while `top` shows load
 is the delta-cache regression signature (the single-flight promise was
 not released).
 
+## Activity view
+
+Source:
+[`server/routes/admin/activity.ts`](../../../ui/server/routes/admin/activity.ts)
+(house-gated proxy) and
+[`platform/ui/app/activity/page.tsx`](../../../ui/app/activity/page.tsx)
+(page). CSS lives under `.activity*` in
+[`platform/ui/app/globals.css`](../../../ui/app/globals.css).
+
+**What it shows.** `/activity` lists every live session across every account
+in the install, one row per session: account, title, model, status, age, idle,
+turn count, RSS, CPU %, cumulative tokens, and imputed GBP cost. Columns sort
+on click. The sidebar session list is scoped to the caller's own account, so
+this is the only surface that answers "where is the activity" install-wide.
+
+**House account only.** The manager binds loopback and gates nothing, so the
+scoping lives on the admin route. The house is resolved by the same three-arm
+predicate the spawn path uses (`resolveAccountDir`): exactly one `role:"house"`
+account, else a sole account declaring no role, else deny — two houses is
+corruption and denies rather than picking one. Both operands are null-checked,
+because `caller === house` alone is true for two nulls. A caller pinned
+elsewhere receives 403 and a logged `op=gate decision=deny` carrying its
+reason. The `HeaderMenu` item is admin-variant only for the same reason.
+
+Be precise about what this is. Under the install-wide access model every
+authenticated install admin can re-pin to any account via
+`POST /api/admin/session/switch-account`, so the gate is a scope selector, not
+an authority boundary between privilege levels.
+
+**Where the numbers come from.** The manager assembles them at its own
+`GET /activity`, joining the live PTY set, the watcher's per-row `accountId`,
+the JSONL enumerator (turns, model, tokens, last message), the PTY census
+(RSS and CPU), and a bounded metering fan-out. The admin route adds the one
+fact the manager cannot see: the `data/accounts` directory count, taken
+independently of `listValidAccounts()` so a rejected account shows as
+`onDisk > valid` rather than silently shortening the list.
+
+**Reading the cells.** A dash means unmeasured, never zero — an unmeasured CPU
+is not an idle session. Cost is the price arm matching the row's own model,
+because the metering core prices one token count under both Opus and Sonnet
+assumptions without knowing which ran; a model in neither family shows a dash.
+Every dashed cost carries its reason as a tooltip, so an unpriced model, a
+failed parse and a session with no transcript are distinguishable rather than
+three readings of the same glyph.
+A session whose sidecar carries no account shows `untagged` rather than being
+folded into the house. The census age is rendered because the snapshot is a 60s
+sample and a dead collector emits nothing.
+
 ## Sidebar surfaces
 
 The sidebar is the entire left column of the admin UI. Its full layout,
@@ -3900,7 +4069,7 @@ This tool is read-only and available to both public and admin agents.
 
 ### When conversations are created
 
-`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — Maxy only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: every inbound — DM or group, allowed or activation-off, agent-invoked or gated — MERGEs the `:Conversation` and writes a forensic `:Message:WhatsAppMessage` row before any access-control decision. The graph is the durable record of every message the device received, not just the ones the agent replied to. See `.docs/web-chat.md` "Deferred conversation persistence" and `.docs/whatsapp.md` "Session continuity" for the full contract.
+`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — Maxy only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: every inbound — DM or group, allowed or activation-off, agent-invoked or gated — MERGEs the `:Conversation` and writes a forensic `:Message:WhatsAppMessage` row before any access-control decision. The graph is the durable record of every message the device received, not just the ones the agent replied to. That forensic row is addressed by cacheKey (`default:<phone>`) on the socket-owning account and deliberately has no session behind it. A WhatsApp sender therefore carries a **second** `:Conversation`: the anchored row written at spawn on the account the session actually runs under, keyed by the session's own deterministic id, which is the row every `MATCH (c:Conversation {sessionId: $SESSION_ID})` resolves. Two rows, two jobs, not duplicates. See `.docs/web-chat.md` "Deferred conversation persistence", `.docs/whatsapp.md` "Session continuity", and `.docs/session-conversation-identity.md` for the per-channel identity contract.
 
 Each row in the Conversations modal exposes a `View logs` row-action that opens a popover with three links — **Stream**, **Errors**, **SSE** — each of which targets `/api/admin/logs?type={stream|error|sse}&sessionId={full-id}` in a new tab. The row's 8-char id chip is click-to-copy; hover reveals the full `sessionId` as a tooltip. See `.docs/web-chat.md` "In-chat retrieval" for the route contract and `console.debug` observability.
 

package/payload/platform/plugins/cloudflare/bin/__tests__/portal-brand-css.test.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Regression test for portal-brand-css.mjs - the assemble-time :root rewriter
+# that bakes a brand's consent.palette into an assembled data portal's
+# stylesheet. Pure file transformation: no network, no Cloudflare credential,
+# no wrangler.
+#
+# Covers:
+#   1. a full palette sets all five mapped variables, exit 0
+#   2. everything outside the :root block is byte-identical to the template
+#   3. a brand with no consent.palette leaves the file byte-identical, exit 0
+#   4. a partial palette sets only the fields it carries
+#   5. --dp-muted is never brand-written, even if the palette carries a muted
+#   6. a value failing the CSS colour rule fails closed: exit 1, file unchanged
+#   7. running twice is idempotent
+#   8. a stylesheet with no :root block fails closed: exit 1, file unchanged
+#   9. a missing --css argument fails closed (exit 1)
+set -u
+
+BIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SCRIPT="$BIN_DIR/portal-brand-css.mjs"
+TEMPLATE="$BIN_DIR/../skills/data-portal/template/public/portal.css"
+[ -f "$SCRIPT" ] || { echo "FAIL: $SCRIPT not found" >&2; exit 1; }
+[ -f "$TEMPLATE" ] || { echo "FAIL: $TEMPLATE not found" >&2; exit 1; }
+# Case 2 strips the :root block with perl and diffs what is left. Without perl
+# both sides strip to nothing and the diff succeeds, so the one check that
+# guards byte-identity would report PASS while asserting nothing. Refuse instead.
+command -v perl >/dev/null || { echo "FAIL: perl not found; case 2 would pass vacuously" >&2; exit 1; }
+
+PASS=0; FAIL=0
+ok()  { echo "PASS: $1"; PASS=$((PASS+1)); }
+bad() { echo "FAIL: $1" >&2; FAIL=$((FAIL+1)); }
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Write a brand.json carrying the given consent.palette object literal, or no
+# palette at all when passed NONE. Echoes the path.
+brand() {
+  local path="$WORK/$1"
+  if [ "$2" = "NONE" ]; then
+    printf '{"name":"t","consent":{}}\n' > "$path"
+  else
+    printf '{"name":"t","consent":{"palette":%s}}\n' "$2" > "$path"
+  fi
+  echo "$path"
+}
+
+# Fresh copy of the real template stylesheet. Using the real file rather than a
+# fixture is deliberate: a template edit that breaks the rewriter fails here.
+css() { local path="$WORK/$1"; cp "$TEMPLATE" "$path"; echo "$path"; }
+
+run() {
+  local of ef
+  of=$(mktemp); ef=$(mktemp)
+  node "$SCRIPT" "$@" >"$of" 2>"$ef"
+  RC=$?
+  OUT=$(cat "$of"); ERR=$(cat "$ef"); rm -f "$of" "$ef"
+}
+
+# The file with its :root block removed, for byte-identity comparison.
+sans_root() { perl -0777 -pe 's/:root\s*\{[^}]*\}//' "$1"; }
+
+FULL='{"bg":"#FAFAF8","fg":"#1a1a1a","accent":"#ea7232","accentFg":"#FFFFFF","border":"#E0E0DB"}'
+
+# 1. full palette sets all five
+B=$(brand full.json "$FULL"); C=$(css full.css)
+run --css "$C" --brand "$B"
+{ [ "$RC" -eq 0 ] \
+  && grep -q -- '--dp-accent: #ea7232;' "$C" \
+  && grep -q -- '--dp-accent-ink: #FFFFFF;' "$C" \
+  && grep -q -- '--dp-paper: #FAFAF8;' "$C" \
+  && grep -q -- '--dp-ink: #1a1a1a;' "$C" \
+  && grep -q -- '--dp-rule: #E0E0DB;' "$C"; } \
+  && ok "full palette sets all five mapped variables (exit=$RC)" \
+  || bad "full palette (exit=$RC err='$ERR')"
+
+# 2. everything outside :root is byte-identical to the template
+{ [ -n "$(sans_root "$TEMPLATE")" ] && diff <(sans_root "$TEMPLATE") <(sans_root "$C") >/dev/null; } \
+  && ok "substitution touched only the :root block" \
+  || bad "bytes outside :root changed, or the strip produced nothing to compare"
+
+# 3. no consent.palette -> file byte-identical, exit 0
+B=$(brand none.json NONE); C=$(css none.css)
+run --css "$C" --brand "$B"
+{ [ "$RC" -eq 0 ] && diff "$TEMPLATE" "$C" >/dev/null; } \
+  && ok "brand with no consent.palette leaves the file untouched (exit=$RC)" \
+  || bad "no-palette case (exit=$RC err='$ERR')"
+
+# 4. partial palette sets only what it carries
+B=$(brand part.json '{"accent":"#CCFF00"}'); C=$(css part.css)
+run --css "$C" --brand "$B"
+{ [ "$RC" -eq 0 ] \
+  && grep -q -- '--dp-accent: #CCFF00;' "$C" \
+  && grep -q -- '--dp-accent-ink: #ffffff;' "$C" \
+  && grep -q -- '--dp-ink: #14181f;' "$C"; } \
+  && ok "partial palette leaves unmapped fields at template defaults (exit=$RC)" \
+  || bad "partial palette (exit=$RC err='$ERR')"
+
+# 5. --dp-muted is never brand-written
+B=$(brand muted.json '{"muted":"#123456","accent":"#ea7232"}'); C=$(css muted.css)
+run --css "$C" --brand "$B"
+{ [ "$RC" -eq 0 ] && grep -q -- '--dp-muted: #667085;' "$C" && ! grep -q '#123456' "$C"; } \
+  && ok "--dp-muted keeps the template default (exit=$RC)" \
+  || bad "--dp-muted (exit=$RC err='$ERR')"
+
+# 6. an unsafe value fails closed and writes nothing
+B=$(brand bad.json '{"accent":"red;background:url(//x)"}'); C=$(css bad.css)
+BEFORE=$(cat "$C")
+run --css "$C" --brand "$B"
+{ [ "$RC" -ne 0 ] && [ "$(cat "$C")" = "$BEFORE" ] && [ -n "$ERR" ]; } \
+  && ok "a value failing the CSS colour rule exits $RC and writes nothing" \
+  || bad "unsafe value not refused (exit=$RC)"
+
+# 7. idempotent
+B=$(brand idem.json "$FULL"); C=$(css idem.css)
+run --css "$C" --brand "$B"; ONCE=$(cat "$C")
+run --css "$C" --brand "$B"; TWICE=$(cat "$C")
+{ [ "$RC" -eq 0 ] && [ "$ONCE" = "$TWICE" ]; } \
+  && ok "second run is a no-op (exit=$RC)" \
+  || bad "not idempotent (exit=$RC)"
+
+# 8. no :root block fails closed
+B=$(brand root.json "$FULL"); C="$WORK/noroot.css"
+printf 'body { color: red; }\n' > "$C"; BEFORE=$(cat "$C")
+run --css "$C" --brand "$B"
+{ [ "$RC" -ne 0 ] && [ "$(cat "$C")" = "$BEFORE" ]; } \
+  && ok "a stylesheet with no :root block is refused (exit=$RC)" \
+  || bad "missing :root not refused (exit=$RC)"
+
+# 9. missing --css fails closed
+B=$(brand args.json "$FULL")
+run --brand "$B"
+{ [ "$RC" -ne 0 ] && [ -n "$ERR" ]; } \
+  && ok "missing --css is refused (exit=$RC)" \
+  || bad "missing --css not refused (exit=$RC)"
+
+echo
+echo "passed: $PASS  failed: $FAIL"
+[ "$FAIL" -eq 0 ]

package/payload/platform/plugins/cloudflare/bin/portal-brand-css.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Bake a brand's client-facing palette into an assembled data portal's
+// stylesheet, by rewriting the one `:root` block in place.
+//
+// This is a script and not a sentence in SKILL.md for the same reason
+// portal-enrol.mjs is one: "replace the :root block and leave the rest alone"
+// is not a constraint when a model performs it by hand. The portal's done-gate
+// asks for the rest of the stylesheet to be byte-identical to the template, and
+// only a transformation that can be run and diffed makes that checkable.
+//
+// The palette read is `consent.palette`, not `defaultColors`. consent.palette
+// is the brand's existing answer to "what colours does this brand show a
+// customer on a surface that is not the install", which is exactly what the
+// portal is; and its accent/accentFg and bg/fg are designed contrast pairs.
+// Taking the accent from defaultColors.primary while taking the foreground from
+// consent.palette.accentFg mixes two palettes, and on a shipped brand that
+// yields #0F3A61 text on a #0F3A61 button.
+//
+// Usage:
+//   node platform/plugins/cloudflare/bin/portal-brand-css.mjs \
+//     --css <accountDir>/pages/<project>/public/portal.css
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+/** The install's stamped brand manifest. Resolved from this file's own location
+ * rather than cwd, because the skill's other commands run from the install root
+ * and this one must not silently depend on that. `--brand` overrides it, which
+ * is what lets the regression test run off-device: platform/config/ is written
+ * by the bundler and does not exist in the source tree. */
+const DEFAULT_BRAND = fileURLToPath(new URL('../../../config/brand.json', import.meta.url))
+
+/** Copied verbatim from packages/create-maxy-code/scripts/bundle.js, which
+ * applies it to defaultColors for the same reason: a brand value lands inside a
+ * CSS declaration, so anything that is not a colour is an injection. The
+ * bundler does NOT validate consent.palette, so this is the only gate on it. */
+const CSS_COLOR_RE = /^(#[0-9a-fA-F]{3,8}|rgba?\([^)]{1,60}\))$/
+
+/** The whole mapping. `--dp-muted` is deliberately absent: no brand carries a
+ * muted tone, and deriving one from another field would be a colour the brand
+ * never chose. It keeps the template default on every brand. */
+const MAP = [
+  ['--dp-accent', 'accent'],
+  ['--dp-accent-ink', 'accentFg'],
+  ['--dp-paper', 'bg'],
+  ['--dp-ink', 'fg'],
+  ['--dp-rule', 'border'],
+]
+
+/** @param {string} message */
+function die(message) {
+  console.error(`portal-brand-css: ${message}`)
+  process.exit(1)
+}
+
+/** @param {string} flag @returns {string | undefined} */
+function arg(flag) {
+  const i = process.argv.indexOf(flag)
+  return i === -1 ? undefined : process.argv[i + 1]
+}
+
+const cssPath = arg('--css')
+const brandPath = arg('--brand') ?? DEFAULT_BRAND
+
+if (!cssPath) die('--css <path to the assembled portal.css> is required')
+
+let css
+try {
+  css = readFileSync(/** @type {string} */ (cssPath), 'utf8')
+} catch (err) {
+  die(`cannot read --css ${cssPath}: ${/** @type {Error} */ (err).message}`)
+}
+
+let brand
+try {
+  brand = JSON.parse(readFileSync(brandPath, 'utf8'))
+} catch (err) {
+  // An unreadable or malformed brand manifest is a broken install, not a brand
+  // that declined to declare a palette. Refuse, rather than silently shipping
+  // the template's default and calling it the brand's colour.
+  die(`cannot read brand manifest ${brandPath}: ${/** @type {Error} */ (err).message}`)
+}
+
+const palette = brand?.consent?.palette
+if (!palette || typeof palette !== 'object') {
+  // Not a failure. A brand that declares no client-facing palette gets the
+  // template defaults, which are legible on their own.
+  console.log('portal-brand-css: brand declares no consent.palette; template defaults kept')
+  process.exit(0)
+}
+
+// Exactly one :root block, or refuse. Two would make "which one wins" a
+// question the stylesheet answers by source order and this script would answer
+// by position; none means the template this tree was assembled from is not the
+// template this script knows.
+const roots = css.match(/:root\s*\{[^}]*\}/g) ?? []
+if (roots.length !== 1) {
+  die(`expected exactly one :root block in ${cssPath}, found ${roots.length}`)
+}
+const root = roots[0]
+
+let next = root
+const applied = []
+for (const [cssVar, field] of MAP) {
+  const value = palette[field]
+  if (value === undefined || value === null || value === '') continue
+  if (typeof value !== 'string' || !CSS_COLOR_RE.test(value)) {
+    die(`consent.palette.${field} is not a valid CSS colour: ${JSON.stringify(value)}`)
+  }
+  // The declaration must already be in the block. If it is not, the template
+  // and this mapping have drifted apart, and appending a declaration the
+  // template never had would hide that.
+  const declRe = new RegExp(`(${cssVar}\\s*:\\s*)[^;]*(;)`)
+  if (!declRe.test(next)) {
+    die(`${cssVar} is not declared in the :root block of ${cssPath}`)
+  }
+  next = next.replace(declRe, `$1${value}$2`)
+  applied.push(`${cssVar}=${value}`)
+}
+
+// Function replacement, so a `$` sequence in the rewritten block is never read
+// as a replacement pattern.
+if (next !== root) {
+  writeFileSync(/** @type {string} */ (cssPath), css.replace(root, () => next), 'utf8')
+}
+console.log(
+  `portal-brand-css: ${applied.length ? applied.join(' ') : 'no mapped fields in consent.palette'}`,
+)

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-enrol.test.ts

@@ -39,7 +39,7 @@ async function d1(dir: string) {
   const db = resolve(root, 'portal.db')
   const schema = resolve(
     dirname(fileURLToPath(import.meta.url)),
-    '../../skills/data-portal/template/schema.sql',
+    '../../skills/data-portal/schema.sql',
   )
   // SQL as an argv entry, not stdin: execFile has no `input` option. The schema
   // goes via `.read` because it opens with a `--` comment, which sqlite3 would

package/payload/platform/plugins/cloudflare/mcp/__tests__/skill-contract.test.ts

@@ -4,6 +4,31 @@ import { join } from 'node:path'
 
 const skill = () => readFileSync(join(__dirname, '../../skills/data-portal/SKILL.md'), 'utf8')
 
+// resolveSiteDir (platform/ui/server/routes/storage-broker.ts) resolves
+// <accountsDir>/<account>/sites/<site> and refuses anything else with
+// invalid-site. A tree assembled where the skill used to say could not be
+// deployed at all.
+describe('data-portal SKILL.md names paths the broker accepts', () => {
+  it('assembles into sites/, not pages/', () => {
+    expect(skill()).toMatch(/<accountDir>\/sites\/<project>\//)
+    expect(skill()).not.toMatch(/assembled tree.*\bpages\/<project>\//)
+    expect(skill()).not.toMatch(/Copy `template\/` to [^\n]*pages\//)
+  })
+
+  it('never tells the assembler to copy a public/ level', () => {
+    expect(skill()).not.toMatch(/template\/public/)
+  })
+
+  // site-deploy's canonical-tree section names pages/<project>/ and instructs
+  // reconciling stray trees into it. An assembler that follows it after
+  // assembling at sites/ moves the tree somewhere the broker refuses, so the
+  // skill has to say not to, for as long as the two disagree.
+  it('warns against relocating the tree to site-deploy canonical path', () => {
+    expect(skill()).toMatch(/Leave the tree where you assembled it/)
+    expect(skill()).toMatch(/invalid-site/)
+  })
+})
+
 describe('data-portal SKILL.md', () => {
   it('opens with frontmatter carrying name and description', () => {
     // Without these the skill is invisible to the available-skills reminder and

package/payload/platform/plugins/cloudflare/mcp/__tests__/template-config.test.ts

@@ -1,10 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { readFileSync } from 'node:fs'
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 
-const TEMPLATE = join(__dirname, '../../skills/data-portal/template')
+const SKILL = join(__dirname, '../../skills/data-portal')
+const TEMPLATE = join(SKILL, 'template')
 const wrangler = () => readFileSync(join(TEMPLATE, 'wrangler.toml'), 'utf8')
-const schema = () => readFileSync(join(TEMPLATE, 'schema.sql'), 'utf8')
+const schema = () => readFileSync(join(SKILL, 'schema.sql'), 'utf8')
 
 describe('wrangler.toml', () => {
   it('binds D1 as DB', () => {
@@ -53,3 +54,54 @@ describe('schema.sql', () => {
     expect(schema()).toMatch(/CREATE UNIQUE INDEX IF NOT EXISTS auth_attempts_scope_window/i)
   })
 })
+
+// The broker runs `wrangler pages deploy <dir>` with <dir> = the site root, so
+// the positional directory IS the asset root and pages_build_output_dir is
+// overridden. A nested public/ therefore publishes the site one level too deep
+// and `/` returns 404 — the live failure Task 1774 closes.
+describe('template layout matches what the deploy publishes', () => {
+  it('has no public/ level', () => {
+    expect(existsSync(join(TEMPLATE, 'public'))).toBe(false)
+  })
+
+  it('serves index.html, portal.css and portal.js from the tree root', () => {
+    for (const f of ['index.html', 'portal.css', 'portal.js']) {
+      expect(existsSync(join(TEMPLATE, f))).toBe(true)
+    }
+  })
+
+  it('keeps functions/ at the tree root', () => {
+    expect(existsSync(join(TEMPLATE, 'functions', 'api', 'auth.ts'))).toBe(true)
+  })
+
+  it('sets pages_build_output_dir to the tree root', () => {
+    expect(wrangler()).toMatch(/pages_build_output_dir\s*=\s*"\."/)
+  })
+
+  // Wrangler's Pages upload ignore list is fixed (_worker.js, _redirects,
+  // _headers, _routes.json, functions, .DS_Store, node_modules, .git,
+  // .wrangler) and Pages honours no .assetsignore, so every other file in the
+  // tree is served publicly. schema.sql has no reason to be, so it lives beside
+  // template/ rather than inside it. wrangler.toml has to stay and its exposure
+  // is tracked separately.
+  it('keeps schema.sql out of the publishable tree', () => {
+    expect(existsSync(join(TEMPLATE, 'schema.sql'))).toBe(false)
+    expect(existsSync(join(SKILL, 'schema.sql'))).toBe(true)
+  })
+
+  // Dotfiles are excluded because the ignore list already covers the ones that
+  // matter (.DS_Store, .git, .wrangler) and a stray Finder .DS_Store would
+  // otherwise fail this test for a reason it does not name.
+  it('publishes nothing beyond the site files, functions/ and wrangler.toml', () => {
+    const published = readdirSync(TEMPLATE)
+      .filter((e) => !e.startsWith('.'))
+      .sort()
+    expect(published).toEqual([
+      'functions',
+      'index.html',
+      'portal.css',
+      'portal.js',
+      'wrangler.toml',
+    ])
+  })
+})

package/payload/platform/plugins/cloudflare/skills/data-portal/SKILL.md

@@ -76,12 +76,39 @@ files. The gate enforces it too, but do not enrol a name it will reject.
 
 ## Assemble the canonical tree
 
-Copy `template/` to `<accountDir>/pages/<project>/` and fill `wrangler.toml`'s `__PROJECT_NAME__`,
+Copy `template/` to `<accountDir>/sites/<project>/` and fill `wrangler.toml`'s `__PROJECT_NAME__`,
 `__D1_DATABASE_NAME__`, `__D1_DATABASE_ID__`, and `__R2_BUCKET_NAME__`. **Leave no `__...__`
 placeholder in the assembled tree.**
 
-Name the D1 database with the same `bin/cf-store-name.sh` scheme as the bucket, and apply
-`schema.sql` to the remote database. It is `IF NOT EXISTS` throughout, so re-applying is safe.
+`sites/<project>/` is the only location the broker will publish: `resolveSiteDir` resolves
+`<accountDir>/sites/<name>` and refuses anything else with `invalid-site`. The tree is flat because
+the deploy publishes the directory it is handed — `index.html`, `portal.css`, `portal.js`,
+`functions/` and `wrangler.toml` all sit at its root, with no nested asset level, and
+`pages_build_output_dir` reads `"."` to match. A nested asset level publishes the site one level too
+deep, which serves 404 at the domain root.
+
+The deploy serves everything in that tree except a fixed ignore list — `functions/`, `_worker.js`,
+`_redirects`, `_headers`, `_routes.json`, `node_modules`, `.git`, `.DS_Store`, `.wrangler` — and
+`pages deploy` reads no `.assetsignore`, so anything else you leave there is public. Nothing else
+belongs in it. `schema.sql` therefore lives beside `template/` in the skill, not inside it. Name the D1 database
+with the same `bin/cf-store-name.sh` scheme as the bucket, and apply
+`platform/plugins/cloudflare/skills/data-portal/schema.sql` to the remote database from there. It is
+`IF NOT EXISTS` throughout, so re-applying is safe.
+
+The copied `portal.css` carries the template's default palette, which is nobody's brand. Apply the
+install's before handing the tree to the deploy:
+
+```bash
+node platform/plugins/cloudflare/bin/portal-brand-css.mjs \
+  --css <accountDir>/pages/<project>/public/portal.css
+```
+
+It rewrites that stylesheet's one `:root` block from `consent.palette` in the install's brand
+manifest and touches nothing else in the file. Do not set the colours by hand: the script validates
+every value against the same rule the bundler applies to brand colours, refuses without writing
+anything if the stylesheet or a value is not what it expects, and leaves the template defaults in
+place for a brand that declares no palette — which is the case a hand-edit turns into an empty
+declaration nobody sees until the page loads.
 
 ## Deploy through site-deploy
 
@@ -97,6 +124,14 @@ Hand the assembled tree to `cloudflare:site-deploy`. Both bindings — D1 and R2
 config in `wrangler.toml`, carried in the deploy payload under the Pages scope; the deploy needs no
 R2 token. Only the bucket *creation* in step 1 needs R2 write, and the broker holds that.
 
+Read `site-deploy` for its auth, custom-domain and DNS guidance, but **not** for the tree location.
+Its canonical-tree section names `<accountDir>/pages/<project>/` and tells you to reconcile stray
+trees into it; that section describes the house path, which publishes with an explicit positional
+output dir. A portal publishes through `storage-pages-deploy`, which accepts `<accountDir>/sites/`
+and nothing else. Leave the tree where you assembled it. Moving it to `pages/` to satisfy that
+section is the one way to turn a working portal into `invalid-site`. The two skills disagree on this
+today and the disagreement is tracked, not resolved.
+
 ## Done-gate
 
 The portal is not done until all five hold on the live domain: