@rubytech/create-realagent 1.0.655 → 1.0.657

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

@@ -0,0 +1,98 @@
+# Adherence Fidelity
+
+User-facing reference for the attention-weighted correction ledger that makes agent adherence compound. Canonical platform documentation lives at [`.docs/agents.md`](../../../../.docs/agents.md) § Adherence Fidelity — this reference mirrors the same behaviour for operators reading plugin docs.
+
+---
+
+## What it solves
+
+The agent's prerogatives (PRECISE, CONCISE, EVIDENCE-BASED) are prose at the top of every system prompt. Without a compounding mechanism, a rule corrected 50 times has the same attention weight as a rule corrected once. Adherence Fidelity adds a per-agent ledger whose rendered summary is inserted into the system prompt every turn, so the agent sees its own recidivism with counts, samples, and recency.
+
+## How an operator sees it
+
+**In chat:** ask the agent *"what is my adherence score?"* or *"what are my top rule violations?"* The admin agent answers via the `adherence-read` tool, which reads the ledger file on disk — the number is authoritative.
+
+**Via API:** `GET /api/admin/adherence?agent=admin` returns the ledger JSON, plus `constraints` (whether capability routing is active for the next turn) and an optional `rendered` block when called with `?block=1`.
+
+**On the filesystem:** `{accountDir}/agents/{agentName}/adherence-ledger.json` is the source of truth. `jq` queries work directly:
+
+```bash
+jq '{score, top: (.rules | sort_by(-.count) | .[0])}' \
+  ~/.maxy/<accountId>/agents/admin/adherence-ledger.json
+```
+
+## Score
+
+```
+score = 100 × (1 − rules_violating_in_rolling_7d / n_rules)
+```
+
+An agent with three rules, zero of which have a violation in the last 7 days, scores 100%. One out of three scores 67%. All three scores 0%.
+
+## Top offenders
+
+The rendered ledger block bolds the top-3 rules by `count` (all-time, not just the rolling window) and quotes their most recent `last_sample`. Rules 4 through 10 appear as one-liners. Zero-recidivism rules (`count = 0` and `rolling_7d = 0`) are omitted entirely.
+
+Sort order: `count DESC, last_violated_at DESC`.
+
+## Capability routing at threshold
+
+When any rule's `rolling_7d` reaches `5`, the next turn's spawn is clamped:
+
+- `--max-turns` drops to `5` — the agent has fewer turns to sprawl.
+- Non-core tools drop from the allowed set (currently the specialist roles).
+- The offending rule renders with a `BLOCKING:` prefix in the ledger block so it dominates the prompt.
+
+The constraint is computed once per turn at the top of `invokeAgent` and frozen for that spawn — one-turn granularity. The next turn reads the updated ledger and re-evaluates, so a single clean turn begins to lift the constraint as `rolling_7d` decays.
+
+## Data flow per turn
+
+```
+┌─ Pre-turn ────────────────────────────────────┐
+│ loadAdherenceLedger(accountDir, accountId)    │
+│ renderAdherenceLedger(ledger, blockingRules)  │
+│ → inject at <!-- ADHERENCE-LEDGER-INSERT -->  │
+│ computeConstraints(ledger)                    │
+│ → clamp max-turns, drop tools                 │
+└────────────────────────────────────────────────┘
+                    │
+                    ▼
+              Assistant stream
+                    │
+                    ▼
+┌─ Post-turn ───────────────────────────────────┐
+│ criticAndRecord(responseText) — Haiku         │
+│ → verdict=pass   → recordPass()               │
+│ → verdict=violation → recordViolation()       │
+│ Fire-and-forget. Non-blocking.                │
+└────────────────────────────────────────────────┘
+```
+
+## What the ledger file looks like
+
+```json
+{
+  "agent_id": "admin",
+  "account_id": "abc123...",
+  "rules": [
+    {
+      "rule_id": "PRECISE",
+      "canonical_text": "Use exact names...",
+      "rule_family": "prerogative",
+      "count": 7,
+      "violations": ["2026-04-19T10:12:00Z", "..."],
+      "last_violated_at": "2026-04-21T09:30:12Z",
+      "last_sample": "Something that paraphrased tool output…",
+      "current_streak": 2,
+      "rolling_7d": 5
+    }
+  ],
+  "updated_at": "2026-04-21T09:30:13Z"
+}
+```
+
+## Limits and deferrals
+
+v1 covers the admin agent only. Specialist subagents (`personal-assistant`, `project-manager`, `research-assistant`, `content-producer`) do not receive their own ledger injection yet — their `.md` templates load via `--plugin-dir` and have no TS-side assembly site. Follow-up task filed.
+
+No cross-agent rule inheritance, no user-visible correction-ack signal, no blocking-critic retry loop in v1 — each is a separate follow-up task. See [`.docs/agents.md`](../../../../.docs/agents.md) § Adherence Fidelity for the full deferral list with task numbers.

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

@@ -8,7 +8,7 @@ Each installation has its own Cloudflare account. Sign-in is OAuth in the device
 |------|--------|
 | **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
 | **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
-| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard at form-render time via `list-cf-domains.sh`, not `brand.json`. Brand identity has no authority over which domains the operator's CF account holds. |
+| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard at form-render time via `list-cf-domains.sh`, not `brand.json`. Brand identity has no authority over which domains the operator's CF account holds. When the scrape returns an unexpected count (e.g. 1 on a two-zone account), the stream log's per-poll `phase=dom-scrape-poll n=<k> count=<n> domains=[…]` trajectory + the on-disk HTML dump at `~/{configDir}/logs/list-cf-domains-<ts>-count<n>-<mode>-pid<pid>.html` (Task 608 — written on every scrape outcome, not just empty ones) give the operator everything they need to triage the cause without re-running. |
 | **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `tunnel.state`, `alias-domains.json`. |
 
 There is no token-based auth for the operator-owned path (Mode A). To switch Cloudflare accounts, run `reset-tunnel.sh` (which deletes the cert and every tunnel on the current account), then run `setup-tunnel.sh` again — `cloudflared tunnel login` inside the setup script will pick a fresh account when you sign in.

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

@@ -68,7 +68,7 @@ The admin UI includes a live terminal surface that opens a real shell on your Pi
 
 The tmux session outlives admin-server restarts — running an upgrade inside this terminal means you see the live shell output continuously, even through the admin server's own restart mid-upgrade. Closing the browser tab does not kill the running work; re-opening the Software Update window reattaches to the same session during an active upgrade and scrollback shows everything that happened in the meantime. Password-protected `sudo` prompts appear natively inside the terminal, and the password you type never leaves the Pi — the admin-server proxy is a raw byte pipe that never inspects frame payloads.
 
-The Software Update window mounts the terminal lazily: the WebSocket is opened on the first Upgrade click, not when the window opens. Until you click Upgrade, the terminal area shows "Ready to upgrade." and no network traffic flows. If the admin server cannot reach `ttyd`, the window renders an inline "Admin terminal not available" message with the exact re-install command and a Try again button — no silent reconnect loops, no empty black rectangle. The scrollback-across-reopen behaviour above still applies during an active upgrade (a sessionStorage flag remembers that an upgrade is in flight so reopening the window re-mounts the terminal and reattaches).
+The Software Update window mounts the terminal lazily: neither the terminal, its WebSocket, nor its black-backgrounded container render until you click Upgrade. Pre-click, the window shows a small "Ready to upgrade — click Upgrade to begin." line, no network traffic flows, and the upgrade UI is the lifecycle indicator — not the terminal. After you click, the window adds a status row above the terminal ("Upgrading to v… · elapsed: Ns · Downloading installer…" flipping to "Running installer…" on the first byte of installer output) so the 5–30 second npx cold-start window is never silent. The upgrade command is dispatched the moment the WebSocket opens — you won't see "terminal not ready" warnings on a healthy device. If the admin server cannot reach `ttyd`, the window renders an inline "Admin terminal not available" message with the exact re-install command and a Try again button. The scrollback-across-reopen behaviour above still applies during an active upgrade (a sessionStorage flag remembers that an upgrade is in flight so reopening the window re-mounts the terminal and reattaches; the elapsed counter keeps ticking from the original start time).
 
 ## AI Content Provenance
 

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

@@ -125,6 +125,20 @@ npx -y @rubytech/create-maxy@latest
 
 Then return to the upgrade window and click **Try again**. The window re-probes `/api/health` and, once ttyd is listening, the terminal area mounts as normal. If the problem persists, check the boot log for `[ttyd] upstream NOT reachable on 127.0.0.1:7681` and follow the `maxy-ttyd` restart steps above.
 
+## Upgrade spinner turns but terminal stays blank
+
+**Symptom:** You clicked **Upgrade**, the progress row is showing with an elapsed counter ticking, but the terminal area below stays empty for more than about a minute with no output.
+
+**What it means:** The upgrade command was dispatched successfully (`onReady` fired), but `ttyd` is not relaying any bytes back from the installer — the `npx` process may have crashed before it printed anything, or `ttyd` itself has lost its PTY.
+
+**Fix:** SSH to the device and check the ttyd unit:
+
+```bash
+sudo systemctl --user status maxy-ttyd
+```
+
+If it's not running, restart it with `sudo systemctl --user restart maxy-ttyd`. Then close and reopen the Software Update window. If `ttyd` is healthy and the spinner keeps turning with no output, the installer process itself has died — re-run `npx -y @rubytech/create-maxy@latest` from an SSH shell directly.
+
 ## Orphan Account Directory Archived to `.trash/`
 
 **What happened:** During upgrade, the installer detected multiple account directories under `~/maxy/data/accounts/` and identified one as live (its `admins` list matches the device's `users.json`). Non-matching siblings are archived — not deleted — under `~/maxy/data/accounts/.trash/<uuid>-<ISO8601-ts>/`.

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

@@ -16,6 +16,8 @@ Three rules govern every turn. They are load-bearing — when they conflict with
 
 A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writes the noise, the noise compounds. Compress on write; filter on read.
 
+<!-- ADHERENCE-LEDGER-INSERT -->
+
 ---
 
 ## Intent Gate — First Principle

package/payload/server/package.json

@@ -6,6 +6,7 @@
     "neo4j-driver": "^6.0.1",
     "@anthropic-ai/sdk": "^0.55.0",
     "@whiskeysockets/baileys": "7.0.0-rc.9",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "proper-lockfile": "^4.1.2"
   }
 }