@rubytech/create-maxy-code 0.1.562 → 0.1.563

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

@@ -90,6 +90,7 @@ For each person:
 ```bash
 node platform/plugins/cloudflare/bin/portal-enrol.mjs --owner <ownerId> --name <name> \
   --account <accountId> [--storage-model shared|dedicated] [--folders <a,b,c>] \
+  [--record-scope own|account] \
   | npx wrangler d1 execute <portalDbName> --remote --file=-
 ```
 
@@ -124,6 +125,28 @@ the same upsert that rotates the passcode. The grant lives only in the portal's
 below the account's exposed set and never widens past it: a portal compromise returns a person to the
 account set, which the install re-derives and enforces regardless.
 
+`--record-scope` is a different question from `--folders` and answers it for RECORDS rather than
+files: `own` lets the person read only records carrying their own id, `account` lets them read every
+record for the account. Two values and no third; a typo is refused rather than resolved to whichever
+is nearer. Omitting it gives `own`, so nobody is granted account-wide visibility by leaving a flag
+off. Re-enrolment replaces it, the same upsert that rotates the passcode, and that is the only way
+to narrow a person back. The office person who schedules gets `account`; a field worker gets `own`.
+
+The scope's only reader is `functions/api/visits.ts`, which the template ships. An account's own page
+renders what that endpoint returns and never re-implements the filter — a gate written once per
+client is a gate got wrong once per client.
+
+**On a store that predates this column, run the `ALTER` once before enrolling anyone.** `IF NOT
+EXISTS` adds no column to an existing table, so `schema.sql` will not do it for you and enrolment's
+INSERT names the column, which means it fails loudly rather than writing a scopeless row:
+
+```sql
+ALTER TABLE people ADD COLUMN recordScope TEXT NOT NULL DEFAULT 'own';
+```
+
+No backfill follows it. Everyone already enrolled lands on the narrow scope, which is the intended
+outcome, and widening one person is a re-run of enrolment for that person.
+
 **A passcode is never stored in plaintext** — not in `data-portal.json`, not in a log line, nowhere
 on the device. The operator conveys it to the person out of band. Rotating a passcode is a re-run of
 the script for that person; there is no separate editor.

package/payload/platform/plugins/cloudflare/skills/data-portal/schema.sql

@@ -47,6 +47,22 @@
 -- to a `people` table that predates it, and enrolment's INSERT names `folders`,
 -- so it fails loudly on such a table. Add it by hand in that case:
 --   ALTER TABLE people ADD COLUMN folders TEXT NOT NULL DEFAULT '';
+-- `recordScope` is which RECORDS this person may read, as distinct from
+-- `folders` above, which is which FILES they may browse. Two values and no
+-- third: `own` sees only records carrying their ownerId, `account` sees every
+-- record for the account. `functions/api/visits.ts` is its only reader, and it
+-- is deliberately the only one — a gate written once per client is a gate got
+-- wrong once per client.
+--
+-- The default is the NARROW value, and that is the whole of the migration
+-- story. Like `accountId` and `folders`, IF NOT EXISTS will NOT add this column
+-- to a `people` table that predates it, and enrolment's INSERT names it, so
+-- such a table fails loudly. Add it by hand in that case:
+--   ALTER TABLE people ADD COLUMN recordScope TEXT NOT NULL DEFAULT 'own';
+-- Every person already enrolled then lands on the narrow scope. A default of
+-- `account` would have handed all of them account-wide visibility by migration,
+-- which is the one thing a scope column must never do.
+--
 -- The key is (accountId, ownerId), not ownerId alone. On the shared store two
 -- clients may each enrol a person called `rob`, and a bare ownerId key would
 -- reject the second enrolment outright. Worse, the enrolment upsert would treat
@@ -60,6 +76,7 @@ CREATE TABLE IF NOT EXISTS people (
   createdAt  TEXT NOT NULL,
   accountId  TEXT NOT NULL DEFAULT '',
   folders    TEXT NOT NULL DEFAULT '',
+  recordScope TEXT NOT NULL DEFAULT 'own',
   PRIMARY KEY (accountId, ownerId)
 );
 
@@ -228,3 +245,80 @@ CREATE TABLE IF NOT EXISTS directory_state (
   accountId         TEXT PRIMARY KEY,
   currentGeneration INTEGER NOT NULL
 );
+
+-- One row per :Visit the device has published, per staging generation
+-- (Task 2425). Metadata only, and only what the ontology already declares
+-- (schema-construction.md): a job sheet's contents are files, which the
+-- manifest above already carries.
+--
+-- READ THE ASYMMETRY WITH THE COLUMN NOTES ABOVE. Those warn that
+-- IF NOT EXISTS adds no COLUMN to an existing table. It does create an absent
+-- TABLE, so these three need no hand step on a database that predates them.
+-- Stated because a reader who has just absorbed the column warning would
+-- otherwise carry it across and go looking for a migration that is not needed.
+--
+-- `ownerId` is the enrolled portal person the visit is assigned to, resolved by
+-- the push from an explicit `portalOwnerId` on the :Person carrying :Engineer.
+-- It is '' when the engineer carries no such property. That row is NOT dropped:
+-- it stays invisible to every own-scoped person, visible to account-scoped
+-- ones, and counted by the audit as `unboundVisits`, so an unbound engineer is
+-- found in the journal rather than by a worker opening an empty day.
+--
+-- `generation` and `visits_state` mirror `directory`/`directory_state` exactly,
+-- and for the same reason: the push writes a whole generation, moves a pointer
+-- in one forward-only statement, then sweeps what the pointer no longer names.
+-- A listing that races a push reads the old set or the new one, never a
+-- half-built one.
+CREATE TABLE IF NOT EXISTS visits (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  accountId  TEXT NOT NULL,
+  visitId    TEXT NOT NULL,
+  ownerId    TEXT NOT NULL DEFAULT '',
+  jobId      TEXT NOT NULL DEFAULT '',
+  status     TEXT NOT NULL DEFAULT '',
+  startDate  TEXT NOT NULL DEFAULT '',
+  purpose    TEXT NOT NULL DEFAULT '',
+  generation INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (accountId, visitId, generation)
+);
+
+CREATE INDEX IF NOT EXISTS visits_account ON visits (accountId);
+-- The own-scoped read filters on both columns, so it carries its own index
+-- rather than riding the account one.
+CREATE INDEX IF NOT EXISTS visits_owner ON visits (accountId, ownerId);
+
+-- Which generation of an account's visit rows is the live one. The flip of this
+-- single row is the atomic point of a push, exactly as directory_state is.
+-- An account with no row here has never completed one, and every reader joins
+-- through this table, so it shows nothing rather than a staged generation that
+-- no flip ever blessed.
+CREATE TABLE IF NOT EXISTS visits_state (
+  accountId         TEXT PRIMARY KEY,
+  currentGeneration INTEGER NOT NULL
+);
+
+-- The inbound half: a status a person set on the portal, waiting for the device
+-- to carry it into the graph (Task 2425).
+--
+-- `claimed` is set only AFTER the graph write returns. Claiming first is
+-- unrecoverable: if the write then failed, the row would read as delivered and
+-- the person's edit would be gone with nothing saying so. Claiming after costs
+-- a repeated MERGE on a lost response, which is idempotent.
+--
+-- A row whose visitId resolves to no :Visit in that account stays unclaimed and
+-- is counted by the audit. It is never written under another id and never
+-- dropped: a dropped edit is a promise broken to the person who made it, and it
+-- emits nothing at the time it happens.
+CREATE TABLE IF NOT EXISTS visit_status (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  accountId TEXT NOT NULL,
+  visitId   TEXT NOT NULL,
+  ownerId   TEXT NOT NULL,
+  status    TEXT NOT NULL,
+  statusAt  TEXT NOT NULL,
+  claimed   INTEGER NOT NULL DEFAULT 0
+);
+
+-- The pull selects unclaimed rows for one account every sixty seconds, so the
+-- pair carries its own index or every cycle is a full scan.
+CREATE INDEX IF NOT EXISTS visit_status_pending ON visit_status (accountId, claimed);

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/_lib/session.ts

@@ -60,16 +60,32 @@ export async function mintSession(
   return sessionId
 }
 
+/**
+ * Which records a person may read.
+ *
+ * Two values and no third: `own` sees only records carrying their ownerId,
+ * `account` sees every record for the account. Distinct from `folders`, which
+ * governs which FILES they browse — a person can hold any combination, and
+ * neither narrows or widens the other.
+ */
+export type RecordScope = 'own' | 'account'
+
 export async function resolveSession(
   db: D1Database,
   sessionId: string,
   accountId: string,
   nowMs: number,
-): Promise<{ ownerId: string; accountId: string; folders: string[] } | null> {
+): Promise<{
+  ownerId: string
+  accountId: string
+  folders: string[]
+  recordScope: RecordScope
+} | null> {
   if (!sessionId) return null
   const row = await db
     .prepare(
-      `SELECT s.ownerId AS ownerId, p.accountId AS accountId, p.folders AS folders
+      `SELECT s.ownerId AS ownerId, p.accountId AS accountId, p.folders AS folders,
+              p.recordScope AS recordScope
          FROM sessions s
          JOIN people p ON p.ownerId = s.ownerId AND p.accountId = s.accountId
         WHERE s.sessionId = ?
@@ -78,7 +94,12 @@ export async function resolveSession(
           AND s.pcCheck = substr(p.hash, 1, 16)`,
     )
     .bind(sessionId, accountId, nowMs)
-    .first<{ ownerId: string; accountId: string; folders: string }>()
+    .first<{
+      ownerId: string
+      accountId: string
+      folders: string
+      recordScope: unknown
+    }>()
   if (!row || typeof row.ownerId !== 'string') return null
   // The join matches on BOTH columns and the lookup is already scoped to this
   // portal's own account, which is what stops a same-named person in another
@@ -92,7 +113,13 @@ export async function resolveSession(
   // means no grant, which the two client surfaces read as no filter (full set).
   const folders =
     typeof row.folders === 'string' ? row.folders.split(',').map((s) => s.trim()).filter(Boolean) : []
-  return { ownerId: row.ownerId, accountId, folders }
+  // ONLY the exact token widens the scope. An empty string, an unknown value, a
+  // null, a legacy row with no such column: every one of them is `own`. An
+  // unreadable scope is the narrow scope, because the alternative is a read
+  // failure that hands out account-wide visibility — the one outcome this
+  // column exists to prevent.
+  const recordScope: RecordScope = row.recordScope === 'account' ? 'account' : 'own'
+  return { ownerId: row.ownerId, accountId, folders, recordScope }
 }
 
 /** Whether a person's folder grant admits `relPath`. An empty grant admits

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/visit-status.ts

@@ -0,0 +1,136 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+
+/**
+ * The longest status a person may set.
+ *
+ * The value reaches `:Visit.status` through the device-side pull, so it is
+ * graph content arriving from the open web. It is refused at the door rather
+ * than truncated: a truncated status is a different status, silently, and the
+ * person who set it is never told.
+ */
+export const MAX_STATUS_LENGTH = 64
+
+/**
+ * Record a status a person set against one of their visits.
+ *
+ * THE GATE IS THE SELECT, not a check beside it. The insert is
+ * `INSERT ... SELECT` over the same `visits` join, under the same two filters
+ * the read applies — the account from the baked-in var, and the owner when and
+ * only when the person's scope is `own`. A visit the person may not see admits
+ * no row, so `meta.changes` is 0 and the handler answers 404. There is no
+ * separate authorisation step that a later edit could reorder past the write.
+ *
+ * This ships in the platform template for the same reason the read does, and
+ * more sharply. A read leak shows someone a working day that is not theirs; a
+ * write leak lets them change it. Neither gate is something to re-implement per
+ * client.
+ *
+ * `ownerId` is stamped from the resolved session and never from the body. A
+ * request that names one is ignored rather than refused, because the field
+ * carries no authority here — the session already decided who is writing.
+ */
+export async function processVisitStatus(
+  body: unknown,
+  sessionId: string,
+  env: PortalEnv,
+  log: Logger,
+  nowMs: number,
+): Promise<Handler> {
+  const session = await resolveSession(env.DB, sessionId, env.PORTAL_ACCOUNT_ID, nowMs)
+  if (!session) {
+    log('[data-portal] op=visit-status owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+
+  const b = (body ?? {}) as Record<string, unknown>
+  const visitId = typeof b.visitId === 'string' ? b.visitId : ''
+  const status = typeof b.status === 'string' ? b.status : ''
+  if (!visitId || !status) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=bad-request`)
+    return { status: 400, payload: { ok: false, error: 'visitId and status are required' } }
+  }
+  if (status.length > MAX_STATUS_LENGTH) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=status-too-long`)
+    return { status: 400, payload: { ok: false, error: 'status too long' } }
+  }
+
+  const scoped = session.recordScope === 'own'
+  const sql =
+    `INSERT INTO visit_status (accountId, ownerId, status, statusAt, claimed, visitId)
+     SELECT ?, ?, ?, ?, 0, v.visitId
+       FROM visits v
+       JOIN visits_state s
+         ON s.accountId = v.accountId AND s.currentGeneration = v.generation
+      WHERE v.accountId = ?` +
+    (scoped ? ' AND v.ownerId = ?' : '') +
+    ' AND v.visitId = ?'
+  const statusAt = new Date(nowMs).toISOString()
+  const stmt = env.DB.prepare(sql)
+  const bound = scoped
+    ? stmt.bind(
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        status,
+        statusAt,
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        visitId,
+      )
+    : stmt.bind(
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        status,
+        statusAt,
+        env.PORTAL_ACCOUNT_ID,
+        visitId,
+      )
+  const result = await bound.run()
+  const changes = result.meta?.changes ?? 0
+
+  if (changes === 0) {
+    // One answer for "no such visit" and "not yours", deliberately. The two are
+    // the same fact to a caller who may not see it, and distinguishing them
+    // would let anyone enumerate the account's visit ids.
+    log(
+      `[data-portal] op=visit-status owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
+        `scope=${session.recordScope} result=not-found`,
+    )
+    return { status: 404, payload: { ok: false, error: 'not found' } }
+  }
+
+  // Counts, the scope and the outcome. Never the status text: it describes what
+  // a real person was doing.
+  log(
+    `[data-portal] op=visit-status owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
+      `scope=${session.recordScope} queued=${changes} result=ok`,
+  )
+  return { status: 200, payload: { ok: true, queued: changes } }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestPost(context: PagesContext): Promise<Response> {
+  const sessionId = readSessionCookie(context.request.headers.get('cookie')) ?? ''
+  let body: unknown = null
+  try {
+    body = await context.request.json()
+  } catch {
+    // A malformed body is a bad request, not a crash. processVisitStatus
+    // resolves the session first, so an unauthenticated caller still gets 401
+    // rather than learning that the body parse is what failed.
+    body = null
+  }
+  const { status, payload } = await processVisitStatus(
+    body,
+    sessionId,
+    context.env,
+    (line) => console.log(line),
+    Date.now(),
+  )
+  return Response.json(payload, { status })
+}

package/payload/platform/plugins/cloudflare/skills/data-portal/template/functions/api/visits.ts

@@ -0,0 +1,93 @@
+import type { Handler, Logger, PortalEnv } from './_lib/types'
+import { readSessionCookie, resolveSession } from './_lib/session'
+import { q } from './_lib/log'
+
+/**
+ * One published visit, as an account's own page renders it.
+ *
+ * The ontology's own fields (`schema-construction.md`) and the portal person the
+ * visit is assigned to, and nothing else. A job sheet's contents are the
+ * account's to design, and they are files, which the Task 1910 exchange already
+ * carries — so nothing of theirs belongs in this shape.
+ */
+export interface VisitRow {
+  visitId: string
+  ownerId: string
+  jobId: string
+  status: string
+  startDate: string
+  purpose: string
+}
+
+/**
+ * The visits a signed-in person may read.
+ *
+ * TWO FILTERS, BOTH SERVER-SIDE, NEITHER REACHABLE FROM THE REQUEST. The
+ * account comes from the baked-in var for the reason `types.ts` gives at
+ * PORTAL_ACCOUNT_ID; the owner filter is applied when, and only when, the
+ * person's scope is `own`, read off the `people` join. No request parameter
+ * names either one, so there is no widening a caller can ask for.
+ *
+ * THIS FUNCTION IS THE ONLY READER OF `recordScope`, and that is deliberate. A
+ * scope column with no reader would be an unused column rather than a boundary.
+ * It ships here rather than being left for each account to write in its own copy
+ * of this tree, because a gate written once per client is a gate got wrong once
+ * per client — and this is the boundary that lets the surface sit on the open
+ * web.
+ */
+export async function processVisits(
+  sessionId: string,
+  env: PortalEnv,
+  log: Logger,
+  nowMs: number,
+): Promise<Handler> {
+  const session = await resolveSession(env.DB, sessionId, env.PORTAL_ACCOUNT_ID, nowMs)
+  if (!session) {
+    log('[data-portal] op=visits owner=none result=denied')
+    return { status: 401, payload: { ok: false, error: 'denied' } }
+  }
+
+  const scoped = session.recordScope === 'own'
+  // Read through the generation pointer, so a listing that races a push sees one
+  // generation whole rather than a half-built one — the same join `files.ts`
+  // makes against directory_state, for the same reason.
+  const sql =
+    `SELECT v.visitId AS visitId, v.ownerId AS ownerId, v.jobId AS jobId,
+            v.status AS status, v.startDate AS startDate, v.purpose AS purpose
+       FROM visits v
+       JOIN visits_state s
+         ON s.accountId = v.accountId AND s.currentGeneration = v.generation
+      WHERE v.accountId = ?` +
+    (scoped ? ' AND v.ownerId = ?' : '') +
+    ' ORDER BY v.startDate ASC, v.visitId ASC'
+  const stmt = env.DB.prepare(sql)
+  const bound = scoped
+    ? stmt.bind(env.PORTAL_ACCOUNT_ID, session.ownerId)
+    : stmt.bind(env.PORTAL_ACCOUNT_ID)
+  const rows = await bound.all<VisitRow>()
+  const visits = rows.results ?? []
+
+  // Counts and the scope, never a visitId or a purpose: those are a real
+  // person's job, and a Pages log is not where they belong.
+  log(
+    `[data-portal] op=visits owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
+      `scope=${session.recordScope} visits=${visits.length} result=ok`,
+  )
+  return { status: 200, payload: { ok: true, visits } }
+}
+
+interface PagesContext {
+  request: Request
+  env: PortalEnv
+}
+
+export async function onRequestGet(context: PagesContext): Promise<Response> {
+  const sessionId = readSessionCookie(context.request.headers.get('cookie')) ?? ''
+  const { status, payload } = await processVisits(
+    sessionId,
+    context.env,
+    (line) => console.log(line),
+    Date.now(),
+  )
+  return Response.json(payload, { status })
+}

package/payload/platform/plugins/docs/references/deployment.md

@@ -201,11 +201,11 @@ The logs will show which service failed to start and why. Common causes:
 Each installed brand runs two per-brand `--user` systemd units (earlier platform fixes + — unit filenames are prefixed with the brand's `hostname` so two brands on the same device never share a unit file):
 
 - `{hostname}.service` — the admin + public HTTP server on `127.0.0.1:19201` (public port + 1). Restarted by the upgrade flow; short downtime is expected during steps 8→11 of an upgrade. An earlier fix: the unit carries two port env vars — `PORT=<public>` (canonical public port, read by the upgrade detector) and `MAXY_UI_INTERNAL_PORT=<public+1>` (the port maxy-ui actually binds).
-- `{hostname}-edge.service` — the always-on public listener on the configured port (default 19200). Reverse-proxies HTTP to the main brand service and handles `/websockify` (VNC) WebSocket upgrades locally. An earlier fix: also hosts `/api/admin/actions/*` and `/api/admin/version*` — the Software Update modal's own routes — so the log stream survives the brand service's restart window. Does NOT restart during an upgrade — the browser WebSocket stays connected by construction. The operator views the device's Chromium in the admin UI via the standalone `/browser` page (peer to `/graph` and `/data`) and on the Claude sign-in screen; both render CDP screencast frames over `/cdp-screencast`, not the framebuffer. Virtual-mode Chromium is headless, so nothing renders onto the X display and the `/websockify` upgrade has no remaining consumer; deleting that stack is separate work.
+- `{hostname}-edge.service` — the always-on public listener on the configured port (default 19200). Reverse-proxies HTTP to the main brand service and handles `/websockify` (VNC) WebSocket upgrades locally. An earlier fix: also hosts `/api/admin/actions/*` and `/api/admin/version*` — the Software Update modal's own routes — so they survive the brand service's restart window. It is restarted by the upgrade flow too (`packages/create-maxy-code/src/index.ts:5143`, after the brand service is stopped and before it is restarted), so the update stream drops near the end of every run and resumes by byte offset. It is not a connection that survives; the log file is what survives, and the browser's `EventSource` replays `Last-Event-ID` to pick the tail back up. The operator views the device's Chromium in the admin UI via the standalone `/browser` page (peer to `/graph` and `/data`) and on the Claude sign-in screen; both render CDP screencast frames over `/cdp-screencast`, not the framebuffer. Virtual-mode Chromium is headless, so nothing renders onto the X display and the `/websockify` upgrade has no remaining consumer; deleting that stack is separate work.
 
-Upgrade and Cloudflare setup run as detached actions: `systemd-run --user` transient units per invocation with stdout+stderr persisted to `~/.maxy/logs/actions/<actionId>.log` and streamed to the UI via SSE. No boot-time service file exists for these.
+The upgrade runs as a detached action: a `systemd-run --user --unit=maxy-action-<actionId> --collect` transient unit per invocation, with stdout+stderr persisted to `~/.<brand>/logs/actions/<actionId>.log` and streamed to the UI via SSE. The unit has its own cgroup, so it outlives both service restarts the installer performs. Its final log line is `[action-exit] code=<n>`, written by the wrapper, which is how the exit code survives a unit that `--collect` has already reaped. A sidecar `~/.<brand>/logs/actions/<actionId>.json` holds the package, start time and pre-upgrade version, so a modal reopened after a reload can still report what changed. No boot-time service file exists for these. Cloudflare setup is not an action; it runs PTY-native from admin chat.
 
-If an action looks stuck, read `~/.maxy/logs/actions/<actionId>.log` directly for the full output, or `journalctl --user --identifier=maxy-action-<actionId>` for systemd's record.
+If an action looks stuck, read `~/.<brand>/logs/actions/<actionId>.log` directly for the full output, or `journalctl --user --identifier=maxy-action-<actionId>` for systemd's record. The lifecycle lines are tagged `[admin-action]` and keyed by `actionId`; they land in `~/.<brand>/logs/edge.log`, not `server.log`, because these routes run on the edge process.
 
 ## Linux laptops: snap-confined Chromium replacement
 
@@ -314,14 +314,20 @@ Empty output from step 3 = brand.json resolved cleanly and the badge reflects th
 
 ## Upgrading
 
-To upgrade {{productName}} to the latest version, ask {{productName}}: "Upgrade {{productName}}." The platform checks the current device identity (hostname and port via `system-status`), then re-runs the installer with explicit `--hostname` and `--port` flags to preserve them across the upgrade.
+There are two ways to upgrade, and both run the same installer.
+
+From the dashboard, press the download icon in the sidebar header (see below). From chat, ask {{productName}}: "Upgrade {{productName}}." The platform checks the current device identity (hostname and port via `system-status`), then re-runs the installer with explicit `--hostname` and `--port` flags to preserve them across the upgrade.
 
 The docs plugin (this plugin) is upgraded in the same step — you always have the documentation that matches your installed version.
 
-### Automatic upgrade alert
+### Upgrading from the dashboard
+
+The sidebar header shows the version you are running, under the product name, at all times. When a newer one is published a download icon appears beside it. There is no icon when you are already up to date, so the icon appearing is itself the news. If you work with the sidebar collapsed to the narrow rail, the version and the icon are hidden with the rest of the header text and a small coloured dot on the brand icon carries the same signal.
+
+Pressing the icon opens the Software Update window, which shows the version you have against the version available and an Update button. Pressing Update runs the installer and streams its output into the window as it happens.
 
-{{productName}} checks for new releases on every admin session start — whenever you log in, reload the page, or return to the admin chat. When a newer version is available, the Software Update window opens automatically showing your current and the latest version, with a one-click Upgrade button. Dismissing the window (click outside or the close button) defers the alert until your next login or reload; no alert is shown when you are already on the latest version.
+Closing the window does not cancel the upgrade. The installer runs in its own background unit, so it keeps going whether or not anything is watching, and reopening the window reattaches to the run in progress.
 
-The upgrade runs inside a live terminal embedded in the Software Update window — you see each installation step stream as it happens, and any password prompts from `sudo` appear directly in the terminal for you to answer. Closing the window does not cancel the upgrade; re-opening it reattaches to the same shell so you can see what happened while disconnected.
+**The connection drops near the end of every upgrade, and that is expected.** The installer restarts the server as its last step, which cuts the browser's connection to it. The window says "Reconnecting" while that happens, then picks the output back up from exactly where it left off. Nothing is lost and nothing needs restarting. When it finishes, the window reports the exit code and whether the version actually moved.
 
-The header menu's version indicator still reflects real-time status: a green dot means you are up to date, and an accent-coloured dot means an upgrade is available. Opening the menu refreshes the version check, so a long-lived session can still surface an upgrade that became available after login without reloading the page.
+The window reports a genuine failure in two shapes worth knowing. If the installer exits non-zero it says so with the code. If it exits cleanly but the version did not change, it says that too, rather than claiming success.

package/payload/platform/plugins/docs/references/platform.md

@@ -167,9 +167,11 @@ The Data search panel ranks results by combining vector similarity with keyword
 
 ## Software Update and Cloudflare Setup
 
-Both flows run on the native Claude Code PTY surface in admin chat. There is no in-app upgrade modal and no Cloudflare setup form — the agent invokes the relevant Bash command directly and its stdout streams into chat verbatim.
+Cloudflare setup runs on the native Claude Code PTY surface in admin chat: there is no Cloudflare setup form, the agent invokes the relevant Bash command directly and its stdout streams into chat verbatim.
 
-- **Software update.** Re-run the installer (`npx -y @rubytech/create-<brand>@latest`) from a shell; HeaderMenu's version row turns sage when `installed === latest`.
+Software update has two doors. The PTY one is the same shape: the agent runs the installer via Bash and its stdout streams into chat. The dashboard one is a modal over the edge-hosted `/api/admin/actions` routes, which run the installer as a `systemd-run` transient unit and stream its log back by byte offset. Both re-run the same installer; neither mutates state directly.
+
+- **Software update.** Re-run the installer (`npx -y @rubytech/create-<brand>@latest`), from a shell, from admin chat via the `upgrade` skill, or from the dashboard control in the sidebar brand head. The brand head shows the installed version at all times and grows a download icon only while `updateAvailable` is true.
 - **Cloudflare setup.** Operator asks in chat; the agent invokes `cloudflared` directly via the Bash tool, following the numbered steps in `plugins/cloudflare/references/manual-setup.md`. cloudflared's stdout and stderr stream into the PTY; the OAuth URL printed by `cloudflared tunnel login` is linkified by the terminal so the operator clicks it and authorises Cloudflare in their own browser.
 
 **Mid-turn stream-drop banners.** If a chat turn ends abruptly the bubble shows one of two messages depending on what actually happened. You see "Server is restarting — reconnect will happen automatically." only when the app server itself emits the restart signal — typically during a Software Update or a Cloudflare setup that re-launches the brand service. You see "Lost connection — retrying." when your browser's connection to the Pi dropped mid-stream while the server was still up — typically a flaky Wi-Fi moment or the tunnel hiccupping. Either way the chat resumes once the connection is back; the previously-rendered messages stay on screen so you don't lose context.

package/payload/platform/templates/agents/public/IDENTITY.md

@@ -6,9 +6,9 @@ You are a public-facing agent for a business. Your soul and your knowledge are p
 
 Everything you know is in this prompt — your soul and the knowledge given with it. Answer only from it. If the answer is not there, say plainly that it is outside what you can help with, and offer to pass the question to the business. Never fill a gap from general training knowledge, and never invent a fact about the business, its products, prices, or people.
 
-## You have no tools
+## You have one tool
 
-You have no tools. Do not search, look anything up, read files, run commands, or load skills. There is nothing for you to call — so do not try. If a visitor asks for something that would need a lookup or an action, treat it as outside what you can help with and offer to pass it on. You cannot act, only answer.
+You have exactly one tool: the reply tool for the channel you are talking on. It is how your answer reaches the visitor, so you call it for every reply you make. There is nothing else to call. You cannot search, look anything up, read files, run commands, or load skills, and there is no tool for any of it, so do not try. If a visitor asks for something that would need a lookup or an action, treat it as outside what you can help with and offer to pass it on. You answer; you do not act.
 
 ## How you behave
 
@@ -16,7 +16,7 @@ In your first message of every conversation, make clear in a natural way that th
 
 You are read-only. You cannot create, change, or delete anything. If a visitor uploads a file, it is saved for the business to review — you cannot read it or act on its contents, so say so honestly.
 
-Never describe your own workings, limits, or the fact that you have no tools unless a visitor asks. Visitors care about the business, not how you are built. Stay within the scope of the knowledge you were given, and decline politely when a request falls outside it.
+Never describe your own workings, limits, or what you can and cannot call unless a visitor asks. Visitors care about the business, not how you are built. Stay within the scope of the knowledge you were given, and decline politely when a request falls outside it.
 
 ## Grounding