@rubytech/create-maxy-code 0.1.299 → 0.1.300

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.299",
+  "version": "0.1.300",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/cloudflare/references/manual-setup.md

@@ -6,14 +6,15 @@ Prerequisites: `cloudflared` installed; the brand's VNC running on its own X dis
 
 ---
 
-## Why two hostnames (admin and public)
+## Why several hostnames (admin, public, operator)
 
-Each Maxy installation exposes two distinct surfaces from the same device and the same local port. The platform UI distinguishes them by the inbound `Host:` header.
+Each Maxy installation exposes distinct surfaces from the same device and the same local port. The platform UI distinguishes them by the inbound `Host:` header.
 
 - **admin hostname** — the operator's private chat + admin panel. PIN-protected. Only the owner uses it.
 - **public hostname** — the public-facing agent (customer chat, marketing agent, WhatsApp webhook target). Reachable by anyone on the internet.
+- **operator hostname** (optional) — a trimmed admin dashboard (sessions, chat, data — no graph, no browser). Admin-gated like the admin host, recognised by membership in `operator-domains.json`. See § "Operator dashboard ingress".
 
-Two tunnel hostnames, one connector, one local service. The tunnel's `ingress:` block routes each hostname to `http://localhost:${PORT}`; the platform UI handles the rest.
+Several tunnel hostnames, one connector, one local service. The tunnel's `ingress:` block routes each hostname to `http://localhost:${PORT}`; the platform UI classifies the host (operator → public → admin) and serves the matching surface.
 
 ---
 
@@ -596,36 +597,50 @@ systemctl --user restart "cloudflared-${BRAND}.service"
 
 ---
 
-## Operator dashboard ingress (`operator.<host>`)
+## Operator dashboard ingress (operator host)
 
-Task 822 adds a trimmed operator dashboard served on `operator.<BRAND_HOSTNAME>`. Unlike a prototype surface, it routes to the **same brand UI port** as the admin host (`${MAXY_UI_PORT}`) and is gated by the **same admin gate** (Cloudflare Access / remote-auth + PIN + Claude OAuth) — it is not a public host. A request to `operator.<host>` that is unauthenticated hits the identical login flow as the bare admin host; the UI server classifies the host and serves the operator shell (sessions, chat, WhatsApp reader, data — no graph, no browser).
+The operator dashboard is a trimmed admin surface (sessions, chat, WhatsApp reader, data — no graph, no browser). It routes to the **same brand UI port** as the admin host (`${MAXY_UI_PORT}`) and is gated by the **same admin gate** (Cloudflare Access / remote-auth + PIN + Claude OAuth) — it is not a public host. A request to the operator host that is unauthenticated hits the identical login flow as the bare admin host; the UI server then classifies the host and serves the operator shell.
 
-Add it with the same Multi-ingress flow above, using `SURFACE=operator` and `PORT=${MAXY_UI_PORT}` (the brand UI port, not a separate dev server):
+**The operator hostname is arbitrary** — any FQDN the operator chooses (e.g. `glsops.siteoffice.online`). Task 829 removed the `operator.` prefix rule: the UI classifies a host as operator **only** when the host is listed in `~/.${BRAND}/operator-domains.json`. Provisioning therefore has two scripted parts — the tunnel ingress (so the host reaches the brand UI) and the operator-domains.json write (so the UI serves the operator shell instead of the full admin shell).
+
+Take the operator FQDN from chat:
 
 ```
-SURFACE="operator"
-PORT="${MAXY_UI_PORT}"          # the brand UI port — same service as admin/public
-HOSTNAME="operator.${BRAND_HOSTNAME}"
+OPERATOR_HOSTNAME="glsops.siteoffice.online"   # the operator's chosen FQDN
+PORT="${MAXY_UI_PORT}"                          # the brand UI port — same service as admin/public
 ```
 
-Then run the awk append (step 1), validate (step 2), create the DNS row (step 3), and reload the connector (step 4) exactly as documented above. After the edit the ingress block carries the operator row before the catch-all:
+### 1. Ingress + DNS
+
+Run the Multi-ingress flow above with `HOSTNAME="${OPERATOR_HOSTNAME}"` and `PORT="${MAXY_UI_PORT}"`: the awk append (step 1), validate (step 2), create the DNS row (step 3), reload the connector (step 4). After the edit the ingress block carries the operator row before the catch-all (hostnames are illustrative — yours are whatever the operator registered):
 
 ```yaml
 ingress:
-  - hostname: admin.<BRAND_HOSTNAME>
+  - hostname: glsmith.siteoffice.online   # admin (primary)
     service: http://localhost:<MAXY_UI_PORT>
-  - hostname: public.<BRAND_HOSTNAME>
+  - hostname: gls.siteoffice.online       # public (also in alias-domains.json)
     service: http://localhost:<MAXY_UI_PORT>
-  - hostname: operator.<BRAND_HOSTNAME>
+  - hostname: glsops.siteoffice.online    # operator (also in operator-domains.json)
     service: http://localhost:<MAXY_UI_PORT>
   - service: http_status:404
 ```
 
-When a provisioning script adds this row it logs `[tunnel-install] operator-ingress added host=operator.<BRAND_HOSTNAME> → :${MAXY_UI_PORT}`; the absence of an `operator.` ingress on a brand that should have one is the failure signature.
+### 2. Classify the host as operator
+
+The ingress only gets the request to the brand UI; without this write the UI serves the **full admin shell** on the operator host. Append the hostname to `operator-domains.json` at the **brand root** (not `${CFG_DIR}` — the platform UI watches the brand root and hot-reloads within ~2 s, no restart):
+
+```
+F="${HOME}/.${BRAND}/operator-domains.json"
+[ -f "$F" ] || echo '[]' > "$F"
+jq --arg H "${OPERATOR_HOSTNAME}" 'if index($H) then . else . + [$H] end' "$F" > /tmp/op.json && mv /tmp/op.json "$F"
+cat "$F"
+```
+
+The UI logs `[operator-domains] reloaded <n> operator domain(s): …` within ~2 s of the write. A configured brand whose boot/reload log shows `0 operator domain(s)` while an operator host is expected means the file was written to the wrong path (e.g. under `cloudflared/`).
 
-**Verification.** `curl -I https://operator.<BRAND_HOSTNAME>` returns the admin login (not a 404, not the public agent page). After login the dashboard shows the sessions list and WhatsApp reader, the header menu carries only Dashboard / Chat / Data, and `https://operator.<BRAND_HOSTNAME>/graph` returns 404.
+**Verification.** `curl -I https://${OPERATOR_HOSTNAME}` returns the admin login (not a 404, not the public agent page). After login the dashboard shows the sessions list and WhatsApp reader, the header menu carries only Dashboard / Chat / Data, and `https://${OPERATOR_HOSTNAME}/graph` returns 404. The standing serve signal is `[host-class] host=${OPERATOR_HOSTNAME} class=operator served=operator.html`; `class=admin served=index.html` for a configured operator host is the full-shell leak signature (the operator-domains.json write was missed or written to the wrong path).
 
-> Installer auto-provisioning of this row is out of scope for Task 822 (documented manual/scripted add only); a follow-up task owns wiring it into the installer.
+> Installer auto-provisioning of this host is out of scope here (documented manual/scripted add only); Task 825 owns wiring it into the installer.
 
 ---
 

package/payload/platform/plugins/cloudflare/references/reset-guide.md

@@ -14,7 +14,7 @@ Ask three questions in order. The first `yes` determines the action.
 2. **Is `config.yml` referencing a tunnel UUID that no longer exists on the account, or a hostname that the account no longer owns?**
    → Full reset. The tunnel the config names is unreachable; recovering per-step is slower than starting clean.
 
-3. **Is the only problem a stray CNAME in the dashboard, a rogue token-mode connector process, or an out-of-date `alias-domains.json` entry?**
+3. **Is the only problem a stray CNAME in the dashboard, a rogue token-mode connector process, or an out-of-date `alias-domains.json` / `operator-domains.json` entry?**
    → Patch (see § Patching below). Reset would destroy correct local state alongside the bad record.
 
 When no question reaches `yes`, the state is probably recoverable per-step via `references/manual-setup.md`. Re-run the relevant manual setup steps before reaching for reset.
@@ -102,6 +102,24 @@ jq --arg H "admin.<yourdomain>" 'map(select(. != $H))' "${HOME}/.${BRAND}/alias-
 
 Replace `<yourdomain>` with the actual domain. The platform UI watches the file and reloads without a restart.
 
+### Remove a rogue entry from `operator-domains.json`
+
+`operator-domains.json` controls which hostnames the platform UI classifies as **operator** (serving the trimmed operator dashboard — sessions, chat, data, no graph/browser) rather than admin or public. It lives at `${HOME}/.${BRAND}/operator-domains.json` — the brand root, **not** `${CFG_DIR}` — for the same reason as `alias-domains.json`: the platform UI watches the brand root.
+
+A host wrongly listed here serves the operator shell instead of the full admin shell (or instead of the public agent, since operator wins over public). Remove it manually:
+
+```
+cat "${HOME}/.${BRAND}/operator-domains.json"
+```
+
+If the wrong host is listed, strip it:
+
+```
+jq --arg H "<host-to-remove>" 'map(select(. != $H))' "${HOME}/.${BRAND}/operator-domains.json" > /tmp/op.json && mv /tmp/op.json "${HOME}/.${BRAND}/operator-domains.json"
+```
+
+The platform UI watches the file and reloads without a restart; the next request to the host routes to its corrected surface.
+
 ### Fix a single wrong DNS record without tearing everything down
 
 If a hostname's CNAME is pointing at the wrong tunnel (e.g. after an account switch left old records), `cloudflared` can overwrite it once the correct cert is in place:

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

@@ -36,7 +36,19 @@ Every Cloudflare operation proves itself with a live behavioural signal surfaced
 
 ## Inputs (tunnel)
 
-Four inputs come from the operator in chat: the admin FQDN, optional public FQDN, optional apex FQDN, and the admin password. `BRAND` is derived from disk — never hardcoded — with `BRAND=$(jq -r .hostname ~/.<configDir>/brand.json)`. The same install can host different brands on different ports; `brand.json.hostname` is the only authoritative source.
+Five inputs come from the operator in chat: the admin FQDN, optional public FQDN, optional operator-dashboard FQDN, optional apex FQDN, and the admin password. `BRAND` is derived from disk — never hardcoded — with `BRAND=$(jq -r .hostname ~/.<configDir>/brand.json)`. The same install can host different brands on different ports; `brand.json.hostname` is the only authoritative source.
+
+## Host classes — three peers on one brand UI port
+
+A brand serves three peer host classes, all routed to the **same brand UI port** (`${MAXY_UI_PORT}`); the platform UI classifies each request by its `Host` header. The hostnames are arbitrary — there is no required `admin.`/`public.`/`operator.` prefix.
+
+| Class | How the UI recognises it | What it serves |
+|---|---|---|
+| **admin** (default) | the bare primary host — in neither domains file | full admin shell (chat, data, graph, browser) — admin-gated |
+| **public** | host starts with `public.` **or** is listed in `~/.${BRAND}/alias-domains.json` | the public agent page only — no admin surfaces |
+| **operator** | host is listed in `~/.${BRAND}/operator-domains.json` | the trimmed operator dashboard (sessions, chat, data — no graph, no browser) — admin-gated |
+
+Precedence is operator → public → admin: a host listed in `operator-domains.json` is operator even if it also matches a public rule. Both domains files live at the **brand root** `~/.${BRAND}/` (not under `cloudflared/`) because the platform UI watches the brand root and hot-reloads within ~2 s. Provisioning admin needs no domains-file write; public writes `alias-domains.json`; operator writes `operator-domains.json`. See `references/manual-setup.md` § "Operator dashboard ingress".
 
 ## Execution
 
@@ -48,7 +60,8 @@ Tunnel mutations the agent performs from `references/manual-setup.md` (each one
 - `cloudflared tunnel --origincert <cert> create <name>` — produces `<tunnelId>.json` credentials.
 - Write `~/.${BRAND}/cloudflared/config.yml` (ingress block per the runbook).
 - `cloudflared tunnel --origincert <cert> route dns <tunnelId> <hostname>` — one call per non-apex hostname.
-- For non-admin hostnames not starting with `public.`, append to `~/.${BRAND}/alias-domains.json` so `isPublicHost()` treats them as public.
+- For a public hostname not starting with `public.`, append it to `~/.${BRAND}/alias-domains.json` so `isPublicHost()` treats it as public.
+- For an operator-dashboard hostname, append it to `~/.${BRAND}/operator-domains.json` so the UI serves the trimmed operator shell (admin-gated). See `references/manual-setup.md` § "Operator dashboard ingress".
 - Install + start the `${BRAND}-cloudflared.service` user unit (`systemctl --user daemon-reload && systemctl --user enable --now ${BRAND}-cloudflared.service`).
 
 After the service is up, the agent runs `curl -I https://<admin-hostname>` and pastes the response. The setup-done claim only fires when a `200` line appears in that response.
@@ -67,7 +80,7 @@ When the operator's request touches Cloudflare, the agent's permitted actions ar
 
 - Invoke `cloudflared` via Bash, following `references/manual-setup.md`.
 - Invoke `wrangler` and the Cloudflare API via Bash, following `references/api.md`, `references/hosting-sites.md`, and `references/d1-data-capture.md`, using the reused per-scope narrow token (minted once if absent, then reused).
-- Write `config.yml` and `alias-domains.json` per the runbook.
+- Write `config.yml`, `alias-domains.json`, and `operator-domains.json` per the runbook.
 - Install and start the brand's cloudflared user service.
 - Quote `references/manual-setup.md`, `references/reset-guide.md`, or `references/dashboard-guide.md` verbatim when a dashboard click-path is the right tool.
 - Verify reachability via `curl -I https://<hostname>` and surface the response.

package/payload/platform/scripts/check-no-esm-require.mjs

@@ -51,6 +51,10 @@ const ALLOWLIST = new Set([
   // (server-init-line-stamper.cjs); the test loads it via the sanctioned
   // createRequire(import.meta.url) ESM→CJS bridge, not a raw require.
   'platform/ui/app/lib/__tests__/server-init-line-stamper.test.ts',
+  // Same vi.hoisted pattern: Task 829's operator-domains test builds a tmpdir
+  // before the module's `../paths` mock fires, to redirect MAXY_DIR off the
+  // operator's real home config.
+  'platform/ui/app/lib/__tests__/operator-domains.test.ts',
 ])
 
 const REQUIRE_CALL_RE = /\brequire\s*\(/