@rubytech/create-realagent 1.0.660 → 1.0.662

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.660",
+  "version": "1.0.662",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/neo4j/schema.cypher

@@ -597,6 +597,24 @@ FOR (ag:AccessGrant) ON (ag.status);
 CREATE CONSTRAINT admin_user_id_unique IF NOT EXISTS
 FOR (au:AdminUser) REQUIRE au.userId IS UNIQUE;
 
+// ----------------------------------------------------------
+// GraphPreference — per-(accountId, userId) UI metadata for /graph
+//
+// Carries the operator's persisted default filter view (labels +
+// includeTrashed) so the /graph page opens with the chosen filter
+// applied on next pageload. Never a user-facing node type — hidden
+// from filter chips via HIDDEN_BY_DEFAULT_LABELS.
+//
+// MERGE-keyed on the composite (accountId, userId). No UNIQUE
+// constraint — the composite MERGE keys are idempotent and the
+// preference is UI metadata, not load-bearing data. A constraint
+// would require both keys in a single composite, which Neo4j
+// supports but adds schema surface for no behavioural benefit.
+// ----------------------------------------------------------
+
+CREATE INDEX graph_preference_account_user IF NOT EXISTS
+FOR (p:GraphPreference) ON (p.accountId, p.userId);
+
 // ----------------------------------------------------------
 // ToolCall — durable audit trail for agent tool invocations
 //

package/payload/platform/plugins/docs/references/memory-guide.md

@@ -84,9 +84,11 @@ Ask naturally:
 
 Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
 
-You can also open a visual view of your graph at any time from the burger menu → **Graph**. It renders up to 200 of your most recently updated nodes as a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node to see its properties; type in the search box to highlight matches.
+You can also open a visual view of your graph at any time from the burger menu → **Graph**. Click the **Filter** button in the toolbar to open the filter menu — it lists only the node types that actually exist in your graph (so you won't see chips for types you've never written). Active chips render a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node to see its properties; type in the search box to highlight matches.
 
-**Delete a node:** drag it to the trash icon top-right of the canvas. No confirmation — deletes are reversible for 30 days. To restore, toggle **Show trashed** above the canvas and click **Restore** on the node, or ask Maxy in chat ("restore the <label> I just deleted").
+**Save a default view:** once you have the chips you want, click **Set default view** in the filter menu. Next time you open **Graph**, those chips are pre-selected and your data renders immediately. The default is per-admin, per-account — each admin on each account has their own.
+
+**Delete a node:** drag it to the trash icon top-right of the canvas. No confirmation — deletes are reversible for 30 days. To restore, toggle **Show trashed** inside the filter menu and click **Restore** on the node, or ask Maxy in chat ("restore the <label> I just deleted").
 
 The page reads only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop. No credentials are required; the view inherits your admin session.
 

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

@@ -70,6 +70,10 @@ The tmux session outlives admin-server restarts — running an upgrade inside th
 
 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 and no network traffic flows. On click, the window mounts the terminal and sends the npx command via `RemoteTerminal.onReady`; the terminal output is the only upgrade observability surface. A background version poll flips to the success row when `installed === latest` and reloads the page. 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. Closing the window does not kill the upgrade — the tmux session keeps running upstream — but the window itself starts fresh on every reopen: if you reopen during an in-flight upgrade, click Upgrade again and the scrollback shows the in-progress output.
 
+Because the terminal is the only surface, it narrates its own state when something goes wrong. The moment you click Upgrade, the terminal echoes a timestamped `[upgrade] starting at <UTC> — shell+ws+tmux+xterm chain OK` line before the `npx` invocation begins — that single line confirms the WebSocket, tmux session, shell, and xterm renderer are all working end-to-end. If 5 seconds then pass with no output from `npx`, the terminal itself writes a `[terminal] no bytes from upstream in 5s — ws.readyState=…, bytesReceived=…, attempt=…` diagnostic into its own buffer, and repeats that narration every 30 seconds of continued silence. If even that narration never appears within ~10 seconds of click, the xterm renderer or its WebSocket is broken and reloading the admin UI is the fix. On the server side, `~/.maxy/logs/terminal.log` carries a `terminal-proxy-flow` heartbeat every 5 seconds while bytes are moving and every ~30 seconds while idle, with `clientBytes`, `upstreamBytes`, and `idleMs` fields — so a stuck upstream presents as `upstreamBytes` frozen and `idleMs` climbing, directly visible in a `tail -f` without any client-side evidence needed.
+
+The terminal also opens as a standalone header-menu surface. The burger menu in the admin chat includes a **Terminal** entry next to **Browser**; clicking it mounts a fullscreen overlay that attaches to the same `maxy-pty` tmux session. This surface is pure attach — no upgrade command is sent — so you can run arbitrary shell work without touching the Software Update flow. Closing the overlay (Escape or the `×` button) detaches from tmux; the session on the Pi keeps running, and re-opening re-attaches with full scrollback intact. Both surfaces can be open simultaneously and show the same session via tmux's native multi-attach. Authorisation is identical to the upgrade surface: the same `canAccessAdmin()` gate + same-origin check + public-host rejection the WebSocket proxy enforces for every client. If `ttyd` is unreachable, the overlay renders the same inline "Remote terminal not available" message with a Try again button; server-side you discriminate surfaces via `grep corrId=header-overlay ~/.maxy/logs/terminal.log` (the upgrade modal uses `corrId=upgrade-modal`).
+
 ## AI Content Provenance
 
 When your public agent sends a message to someone — via email, WhatsApp, Telegram, or SMS — the platform automatically includes a brief disclosure that the content was generated by AI. This is transparent and cannot be turned off.

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

@@ -127,17 +127,33 @@ Then return to the upgrade window and click **Try again**. The window re-probes
 
 ## Upgrade terminal stays blank after clicking Upgrade
 
-**Symptom:** You clicked **Upgrade**, the terminal area mounted, but the terminal stays empty for more than about 60 seconds with no output.
+**Symptom:** You clicked **Upgrade**, the terminal area mounted, but the terminal looks empty.
 
-**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.
+**What you should see — the terminal narrates itself.** Within a few hundred milliseconds of click, the terminal echoes a line like `[upgrade] starting at 2026-04-21T11:48:33Z — shell+ws+tmux+xterm chain OK`. That single line confirms the WebSocket, tmux session, shell, and xterm renderer are all working. Within ~2 seconds on a warm npx cache, the installer's own first line arrives on top of that.
 
-**Fix:** SSH to the device and check the ttyd unit:
+**If the terminal is silent for more than 5 seconds:** the terminal itself writes a yellow diagnostic like `[terminal] no bytes from upstream in 5s — ws.readyState=1, bytesReceived=0, attempt=1` into its own buffer, and repeats that narration every 30 seconds of continued silence. If those lines appear, the WebSocket and renderer are fine — the problem is upstream. SSH to the device and check `ttyd`:
 
 ```bash
 sudo systemctl --user status maxy-ttyd
+sudo tail -f ~/.maxy/logs/terminal.log
 ```
 
-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 terminal stays empty, the installer process itself has died — re-run `npx -y @rubytech/create-maxy@latest` from an SSH shell directly.
+In `terminal.log`, look for `terminal-proxy-flow` lines — they're emitted every 5 seconds when bytes are moving and every ~30 seconds while idle, with `clientBytes`, `upstreamBytes`, and `idleMs` fields. A stuck upstream shows `upstreamBytes` frozen and `idleMs` climbing. If `maxy-ttyd` is not running, restart it with `sudo systemctl --user restart maxy-ttyd`, then close and reopen the Software Update window. If `ttyd` is healthy and `idleMs` keeps climbing, the installer process itself has died — re-run `npx -y @rubytech/create-maxy@latest` from an SSH shell directly.
+
+**If no narration appears at all within ~10 seconds of click:** the xterm renderer or its WebSocket is broken — reload the admin UI in your browser. The absence of the self-narration is itself the diagnostic. On reload, if the preamble line does not appear again within a few hundred milliseconds of clicking Upgrade, the admin server cannot reach `ttyd`; follow the "Admin terminal not available" steps above.
+
+## Terminal menu item renders an empty rectangle
+
+**Symptom:** You opened the burger menu, clicked **Terminal**, and the fullscreen overlay mounted but the body area stayed black for more than a second or two — no prompt, no scrollback, just an empty rectangle where the shell should be.
+
+**What it means:** `ttyd` on `127.0.0.1:7681` is not accepting the WebSocket, so `RemoteTerminal` cannot attach to `maxy-pty`. If `maxy-ttyd.service` is unreachable for long enough, the overlay flips to an inline "Remote terminal not available" message with a **Try again** button — but before that trips you get the empty-rectangle window. The quickest check is the same one used for the Software Update path:
+
+```bash
+sudo systemctl --user status maxy-ttyd
+sudo tail -n 50 ~/.maxy/logs/terminal.log
+```
+
+Filter the log to this surface specifically: `grep corrId=header-overlay ~/.maxy/logs/terminal.log` — the Software Update window uses `corrId=upgrade-modal`, so the discriminator lets you tell which client hit the problem. A healthy open looks like `proxy-open corrId=header-overlay` followed by `proxy-flow` heartbeats every 5s; an unreachable backend looks like `proxy-error side=upstream-connect err=ECONNREFUSED`. If `maxy-ttyd` is not running, restart it with `sudo systemctl --user restart maxy-ttyd`, close the overlay, and reopen it from the burger menu — `tmux new-session -A` is idempotent so your session and scrollback come back intact.
 
 ## Orphan Account Directory Archived to `.trash/`