@rubytech/create-sitedesk-code 0.1.562 → 0.1.564

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

@@ -0,0 +1,193 @@
+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
+
+/**
+ * The longest work note a person may attach to a day.
+ *
+ * The note reaches `:JobCost.description` through the device-side pull, so it
+ * is graph content arriving from the open web and gets the same treatment the
+ * status gets: refused at the door, never truncated. The size is chosen for a
+ * description cell on the A4 timesheet row, not derived from anything.
+ */
+export const MAX_NOTE_LENGTH = 500
+
+/**
+ * The only date shape a claim may carry.
+ *
+ * The date becomes part of the cost key the pull merges on, so a free-form
+ * string would produce a key nobody can reproduce. A COPY of this check lives
+ * in `platform/ui/server/portal-visits-pull.ts` as the invariant at the writer;
+ * the two cannot share a constant because this file ships to Cloudflare Pages
+ * and cannot import from the platform tree.
+ */
+export const WORK_DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * 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' } }
+  }
+
+  // The working day the edit carries, if any. Absent means a status-only edit,
+  // which is the common case and stays a zero-claim write.
+  const dayHundredths = b.dayHundredths === undefined ? 0 : b.dayHundredths
+  if (
+    typeof dayHundredths !== 'number' ||
+    !Number.isInteger(dayHundredths) ||
+    dayHundredths < 0 ||
+    dayHundredths > 100
+  ) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=bad-day`)
+    return { status: 400, payload: { ok: false, error: 'dayHundredths must be an integer 0..100' } }
+  }
+  const workDate = typeof b.workDate === 'string' ? b.workDate : ''
+  const workNote = typeof b.workNote === 'string' ? b.workNote : ''
+  // A claim the roll-up could not date is refused now rather than queued. The
+  // pull holds the same invariant, so a row reaching the table another way is
+  // still never written under a guessed date.
+  if (dayHundredths > 0 && !WORK_DATE_RE.test(workDate)) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=undated-claim`)
+    return {
+      status: 400,
+      payload: { ok: false, error: 'a day claim requires workDate as YYYY-MM-DD' },
+    }
+  }
+  if (workNote.length > MAX_NOTE_LENGTH) {
+    log(`[data-portal] op=visit-status owner=${q(session.ownerId)} result=note-too-long`)
+    return { status: 400, payload: { ok: false, error: 'note too long' } }
+  }
+
+  const scoped = session.recordScope === 'own'
+  const sql =
+    `INSERT INTO visit_status (accountId, ownerId, status, statusAt, dayHundredths, workDate, workNote, 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,
+        dayHundredths,
+        workDate,
+        workNote,
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        visitId,
+      )
+    : stmt.bind(
+        env.PORTAL_ACCOUNT_ID,
+        session.ownerId,
+        status,
+        statusAt,
+        dayHundredths,
+        workDate,
+        workNote,
+        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, whether a day was claimed, and the outcome. Never the
+  // status text, the date or the note: they describe what a real person was
+  // doing and when.
+  log(
+    `[data-portal] op=visit-status owner=${q(session.ownerId)} account=${q(session.accountId)} ` +
+      `scope=${session.recordScope} labour=${dayHundredths > 0} 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/plugins/docs/references/telegram-guide.md

@@ -56,3 +56,22 @@ Ask {{productName}}: "What messages has the bot received?" or "Show recent Teleg
 **Can't send to a group:** The bot must be a member of the group. Add it via the group settings in Telegram, then try again.
 
 **Messages not arriving:** Make sure the bot hasn't been blocked. Try sending `/start` to the bot directly.
+
+## Sending from the dashboard
+
+Open a Telegram conversation in the dashboard and you can type a reply straight
+into it, the same way you already can with WhatsApp. The message goes out from
+your bot.
+
+Two things to know:
+
+- **Direct messages only.** Group and supergroup chats show no message box. A
+  Telegram conversation is filed under the person who spoke, so a message sent
+  from a group thread would reach that one person privately rather than the
+  group — the box is hidden rather than doing something you did not intend.
+- **History starts now.** Messages are only shown from the point this feature
+  was installed onward. A conversation that was already running looks empty
+  until the next message arrives, and then fills up from there.
+
+Text only for now. Photos, files and voice notes are not available on Telegram
+from the dashboard.

package/payload/platform/plugins/memory/references/schema-construction.md

@@ -116,7 +116,7 @@ MERGE keys per label:
 - `:Contact` — `(accountId, contactId)` — write-time MERGE
 - `:PurchaseOrderLine` — `(accountId, poNumber, lineId)` — child of `:PurchaseOrder`
 - `:Note` — `(accountId, noteId)` — child of `:Job` via `(:Note)-[:ABOUT]->(:Job)`, append-only CREATE (a fresh `noteId` per note, not a content MERGE), so a second note never overwrites the first
-- `:Engineer` — `(accountId, personId)` — additional label on `:Person`, set via `memory-update`
+- `:Engineer` — `(accountId, engineerId)` — additional label on `:Person`, set via `memory-update`
 - `:Supplier` — `(accountId, organizationId)` — additional label on `:Organization`
 
 ---

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
 

package/payload/premium-plugins/sitedesk/agents/sitedesk--payroll-clerk.md

@@ -3,7 +3,7 @@ name: payroll-clerk
 description: "SiteDesk payroll clerk. Delegate when the operator wants to roll up field workers' daily check-ins into a per-worker timesheet and, for CIS subcontractors, an invoice for a period, reconciled to the penny and emailed to the office. Triggers are jobs like 'run the timesheets', 'do this week's invoices', 'roll up Dave's days'. Not for a new quote (that is the quoter) or an interim valuation (that is the valuer)."
 summary: "Your payroll clerk — turns field workers' daily check-ins into per-worker timesheets and CIS invoices, reconciled to the penny."
 model: claude-sonnet-5
-tools: Skill, Read, Write, Edit, Bash, Glob, Grep, mcp__plugin_browser_browser__browser-navigate, mcp__plugin_browser_browser__browser-pdf-save, mcp__plugin_email_email__email-send
+tools: Skill, Read, Write, Edit, Bash, Glob, Grep, mcp__plugin_browser_browser__browser-navigate, mcp__plugin_browser_browser__browser-pdf-save, mcp__plugin_email_email__email-send, mcp__plugin_memory_memory__memory-search
 pattern_deliverable: false
 ---
 
@@ -17,7 +17,7 @@ A message from the agent that dispatched you arrives on the platform's own dispa
 
 You are the SiteDesk payroll clerk — the one owner of timesheet and CIS-invoice work for an independent service business's field crew. You own one deliverable: a per-worker timesheet and, for a CIS subcontractor, the matching invoice for a period, rendered to A4 PDFs and emailed to the office. The admin agent dispatches a brief to you; you run the `timesheet` skill and return the result.
 
-You never invent the operator's business content. Day counts come from the workers' own daily check-ins; rates, the office invoice address and each worker's engagement are the operator's data — you apply them faithfully. A figure you cannot source is a gap you flag, not a number you guess.
+You never invent the operator's business content. Day counts come from the workers' own job sheets, filed on the data portal and carried into the graph as labour costs, which you read with `memory-search` and never write; rates, the office invoice address and each worker's engagement are the operator's data — you apply them faithfully. A figure you cannot source is a gap you flag, not a number you guess.
 
 ## What you own
 

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/timesheet/SKILL.md

@@ -22,12 +22,12 @@ maths ([references/roll-up.md](references/roll-up.md)), and the two documents
 
 - **Worker setup (per worker, once).** Capture the worker's engagement, day rate, UTR (CIS only),
   whether the 20% deduction shows, and the office invoice address. Store it as the `:Engineer` config
-  on his `:Person`. The worker logs his days through the receive-only `worker-checkin` agent; the
-  platform's multi-channel transport delivers those messages into one session.
+  on his `:Person`. The worker files his days as job sheets on the operator's data portal, against
+  his own visits; the device carries each one into the graph as a labour cost within a minute.
 
 - **Roll-up (operator-run, per period).** For a worker (or all workers) and a period:
-  1. Read his check-ins for the period by `personId` — structure the worker's delivered messages
-     into `:JobCost` records (one per working day) at this point.
+  1. Read his labour `:JobCost` rows for the period with `memory-search`, by `engineerId`. They are
+     written by the portal visit exchange; this skill reads them and never creates them.
   2. Run `rollup.mjs compute <worker.json> <checkins.json>` — never compute by hand.
   3. Render the timesheet (and, for CIS, the invoice) from the computed figures.
   4. Run `rollup.mjs reconcile <computed.json> <netPence> <dayHundredths>` — both gates must pass.
@@ -42,6 +42,6 @@ total disagrees with the compute.
 
 ## Observability
 
-- one line per check-in read into a roll-up (worker id, source channel, date, site);
+- one line per labour cost read into a roll-up (engineer id, source, date, site);
 - one line on generation: worker id, period, day-count, artefact filenames, email recipient;
 - the `op=reconcile-fail` line whenever a gate stops a send.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/timesheet/references/checkin-contract.md

@@ -4,33 +4,51 @@ This skill ships these shapes, never a worker's data.
 
 ## `:Engineer` (operator config, one per worker)
 
-`(:Engineer { personId, accountId, name, engagement: "employee"|"cis", dayRatePence,
+`(:Engineer { engineerId, accountId, name, engagement: "employee"|"cis", dayRatePence,
             utr?, showCisDeduction: bool, invoiceEmail, createdAt })`
 
-`personId` ties the worker to his `:Person`. `dayRatePence` is integer pence. `utr` is present
-only for `engagement: "cis"`. `invoiceEmail` is the office invoice address. Captured by the
-operator at runtime (see [setup.md](setup.md)), never written into this tree.
+`engineerId` is the worker's key and the write-time MERGE key `(accountId, engineerId)`.
+`dayRatePence` is integer pence. `utr` is present only for `engagement: "cis"`. `invoiceEmail` is
+the office invoice address. Captured by the operator at runtime (see [setup.md](setup.md)), never
+written into this tree.
 
-## `:JobCost` (one labour cost per working day, `costType: "labour"`)
+`Engineer` is an additional label on that worker's `:Person`; there is no standalone node. The rate
+lives here, office-side, and never reaches the portal the worker files his day on.
 
-`(:JobCost { costId, costType: "labour", personId, accountId, source, receivedAt,
+## `:JobCost` (one labour cost per visit worked, `costType: "labour"`)
+
+`(:JobCost { costId, costType: "labour", engineerId, accountId, jobId, source, receivedAt,
              date, site, description, dayHundredths, createdAt })`
 
-A logged labour day is an incurred labour cost. `costType` is `"labour"` and `costId` is the
-write-time MERGE key (`(accountId, costId)`) — use a deterministic id such as `${personId}-${date}`
-so re-delivery of the same day stays idempotent. `personId` is the roll-up read key: the roll-up
-reads every labour `:JobCost` for the worker regardless of which channel produced it. `source`
-records the channel the message arrived on (`web`, `whatsapp`, …). `dayHundredths` is 100 for a
-full day; a smaller value only when the operator enabled part-day handling. One labour `:JobCost`
-per working day.
+Time worked is an incurred labour cost. `costType` is `"labour"` and `costId` is the write-time
+MERGE key (`(accountId, costId)`), formed as `${engineerId}-${visitId}`, so re-filing the same
+visit merges rather than duplicating and the later sheet corrects the earlier one.
+
+**One cost per visit, not per day.** A worker who attends two sites in a day files two sheets and
+holds two labour costs on that date, each with its own `site` and its own share of the day. Keying
+on the date instead would merge the second over the first and pay him for one of them; the roll-up
+sums `dayHundredths` across every cost in the period, so several on one date add up to that day.
+
+`engineerId` is the roll-up read key: the roll-up reads every labour `:JobCost` for the worker.
+`date` is the day worked, which is what the roll-up filters a period on and what the timesheet
+prints. `source` records where it came from (`portal`). `dayHundredths` is 100 for a full day; a
+smaller value when the day is split across visits, or when the operator enabled part-day handling.
 
 Each `:JobCost` is linked to the engineer who incurred it with the canonical edge
-`(:JobCost)-[:INCURRED_BY]->(:Engineer)` (an additional label on that worker's `:Person`), and to
-its job with `(:Job)-[:HAS_COST]->(:JobCost)` — the edge types are fixed by
-`schema-construction.md`; write no edge type absent from it. The edge satisfies the write-doctrine
-adjacency requirement (a node is written with at least one relationship); `personId` carries the
-same identity for roll-up reads.
-
-These records come from the worker's delivered messages. The platform's multi-channel transport
-delivers those messages into one session; the step that turns them into `:JobCost` records is this
-skill's roll-up (structure at roll-up — see [roll-up.md](roll-up.md)).
+`(:JobCost)-[:INCURRED_BY]->(:Engineer)`, and to its job with `(:Job)-[:HAS_COST]->(:JobCost)` — the
+edge types are fixed by `schema-construction.md`; write no edge type absent from it. The edges
+satisfy the write-doctrine adjacency requirement (a node is written with at least one relationship);
+`engineerId` carries the same identity for roll-up reads.
+
+## Where these records come from
+
+The worker files a job sheet against one of his own visits on the operator's data portal, stating
+the day worked and how much of it. The device carries that edit into the graph every sixty seconds,
+writing the labour cost in the same statement as the visit's status, so a visit never reads as done
+with the working day missing behind it. The day is attributed to the engineer the visit names rather
+than to whoever filed the sheet, so an office person completing a worker's day still produces that
+worker's cost.
+
+A claim the device cannot date, or one on a visit with no attending engineer, is left unwritten and
+counted in the journal rather than dated or attributed by guess. This skill reads these rows; it
+never creates them.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/timesheet/references/roll-up.md

@@ -3,13 +3,26 @@
 Days × rate and the CIS deduction are universal maths; they must reconcile to the penny, so they
 are computed by `rollup.mjs`, never by hand. The engine carries no operator content.
 
-## Turning messages into check-ins (structure at roll-up)
-
-A worker's daily messages arrive over whatever channel and the platform delivers them into one session.
-At roll-up time, read the worker's messages for the period and structure each working day into one
-`:JobCost` (see [checkin-contract.md](checkin-contract.md)): `date`, `site`, `description`,
-`dayHundredths`. One message-day = one check-in. Structuring happens here, in the operator-run step,
-not in the unattended receive path — so the operator can review before anything is sent.
+## Reading the period's days
+
+The days already exist as records. A worker files a job sheet against one of his own visits on the
+operator's data portal, and the device writes that as one labour `:JobCost` (see
+[checkin-contract.md](checkin-contract.md)) carrying `date`, `site`, `description` and
+`dayHundredths`, within a minute of him filing it.
+
+At roll-up time, read the worker's labour costs for the period with `memory-search`, by
+`engineerId`, and filter on `date`. Never create them here. The key is `${engineerId}-${visitId}`,
+so a re-filed sheet merges rather than duplicating; writing a record at roll-up would put a second,
+differently-keyed entry beside one that already exists.
+
+A worker who attends two sites in a day holds two costs on that date, each with its own site and
+its own share of the day. The engine sums `dayHundredths` across every cost you hand it, so several
+on one date add up to that day and each prints its own timesheet row.
+
+A day the worker filed that the device could not use — no date it can key on, or a visit with no
+attending engineer — was never written, and is counted in the journal as `undatedClaims` or as a
+`labourClaims` count that does not drain. A period whose day total looks short is worth checking
+there before it is treated as the worker's own record.
 
 ## The figures (integer pence; day amounts integer hundredths)
 

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/timesheet/references/setup.md

@@ -2,7 +2,9 @@
 
 The skill defines the questions; the operator's answers are his data. Per worker:
 
-- **Name** and the **`:Person`** he maps to.
+- **Name**, the **`:Person`** he maps to, and his **`engineerId`** — the key everything else about
+  his days is read by. A worker with no `engineerId` has his job sheets refused rather than recorded
+  under a key nobody can reproduce.
 - **Engagement** — `employee` or `cis` (CIS subcontractor).
 - **Day rate** — captured in pounds, stored as integer pence (`dayRatePence`).
 - **UTR** — required when `engagement: cis`; omitted for employees.
@@ -14,7 +16,9 @@ Install-level, once:
 
 - **Invoice frequency** — weekly or monthly; this only sets the default roll-up period, never a
   scheduler. The roll-up is always operator-run.
-- **Part-day / overtime rule** — whether `dayHundredths` other than 100 are accepted, and how a
-  part day is expressed. If disabled, every check-in is a full day.
+- **Part-day rule** — whether `dayHundredths` below 100 are accepted, and how a part day is
+  expressed. If disabled, every day filed is a full day. The portal accepts an integer from 0 to
+  100 and refuses anything above it, so a day longer than a full day cannot be filed and no
+  overtime rule is expressible here.
 
 No value is invented. A missing required value is a gap the agent flags, never a guess.