@rubytech/create-realagent 1.0.682 → 1.0.684

package/package.json

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

package/payload/platform/config/brand.json

@@ -6,6 +6,7 @@
   "configDir": ".realagent",
   "tagline": "Built for agents. By agents.",
   "domain": "realagent.network",
+  "neo4jPort": 7688,
 
  "defaultColors": {
     "primary": "#7C8C72",

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

@@ -76,6 +76,22 @@ Each Maxy device runs one `--user` systemd unit:
 
 If the admin terminal fails to open, check `sudo tail -n 50 ~/.maxy/logs/edge-boot.log` — the `ttyd-ws-upgrade` / `ttyd-proxy-open` / `ttyd-proxy-close` lines carry a `corrId` that ties the full session lifecycle together. For unit health, `systemctl --user status maxy-ttyd` + `journalctl --user -u maxy-ttyd`.
 
+## Running multiple brands on one device
+
+A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.
+
+- **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688).
+- **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
+
+To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:
+
+```bash
+# Already running Maxy on port 20000. Install Real Agent on a different port:
+npx -y @rubytech/create-realagent --port 19500
+```
+
+Uninstalling one brand removes only that brand's state when the other brand is present: this brand's install folder, config folder, its own Neo4j data (if it runs a dedicated instance; shared data is left alone), its Cloudflare tunnel, and its systemd service. Shared binaries (Ollama, `cloudflared`), apt packages, and device-wide caches (`~/.claude`, `~/.ollama`) are left in place because the other brand is still using them. When no other brand is present, the uninstaller performs a full device decommission as before.
+
 ## Upgrading
 
 To upgrade Maxy to the latest version, ask Maxy: "Upgrade Maxy." 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.

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

@@ -93,6 +93,29 @@ If the initial Cloudflare login fails during setup, Maxy will fall back to askin
 
 ---
 
+## Admin terminal renders leading `0`, `1`, or `2` characters (wire-format decoder not running)
+
+**Symptom:** The header-menu Terminal or Software Update modal connects, but the xterm.js buffer shows literal digits where the tmux prompt should be — e.g. `1tmux new-session -A -s maxy-pty -x 200 -y 50 (neo)2{"..."}`. Typing keystrokes does nothing (the terminal looks alive but nothing echoes).
+
+**What it means:** ttyd 1.7.7 frames every WebSocket message with a 1-byte command prefix (`'0'` for output, `'1'` for window title, `'2'` for preferences). The React terminal needs the [ttyd-protocol.ts](../../../../platform/ui/app/lib/ttyd-protocol.ts) decoder to split the prefix and route accordingly. If the decoder isn't wired up — typically because an older bundle was installed or a hotfix reverted the wiring — xterm.js receives the raw bytes and renders the prefix as a literal digit. Outbound keystrokes have the mirror problem: ttyd discards any frame that doesn't start with `'0'` INPUT.
+
+**Check (browser DevTools console on admin.maxy.bot):**
+
+```
+[terminal] connected
+[ttyd-client] protocol negotiated cmd=0 payloadBytes=<n>   ← expected within 3s of connect
+```
+
+- `[terminal] connected` present but `[ttyd-client] protocol negotiated` absent → the decoder is not running. Re-install: `npx -y @rubytech/create-maxy@latest` (or Software Update from the admin header when reachable).
+- `[ttyd-client] unknown cmd prefix=<hex> bytes=<n>` cluster → ttyd version drift. The 1.7.7 pin is expected; a newer ttyd may have added command classes. Safe-ignore on 1.7.7.
+- Neither line appears → the WebSocket itself isn't connecting; see the "Admin terminal blank / flashing cursor" section below (pre-Task-657 sections are historical, not applicable).
+
+**Correlate with server side.** `grep corrId=<id> ~/.maxy/logs/edge-boot.log` reveals whether bytes are flowing end-to-end — `ttyd-proxy-chunk dir=upstream→client` lines prove ttyd is sending output. If those lines exist but the browser shows leading digits, the decode listener isn't wired to the live socket; if those lines are absent, the failure is upstream of the client (maxy-ttyd service, tmux attach).
+
+**Regression boundary:** `platform/ui/app/RemoteTerminal.tsx` must import `decodeFrame`, `encodeInput`, and `encodeResize` from `./lib/ttyd-protocol`. `@xterm/addon-attach` is not a dependency — it pipes WS bytes to `term.write` raw and cannot satisfy the ttyd framing contract.
+
+---
+
 ## Software Update click shows an error instead of opening the terminal
 
 > **Stale content — Task 657 replaced the VNC-terminal surface with byte-stream xterm.js over `/ttyd`.** The VNC launch-upgrade path described below no longer exists. First-line diagnostic for the new surface: `sudo systemctl --user status maxy-ttyd` plus `sudo grep 'ttyd-proxy' ~/.maxy/logs/edge-boot.log | tail -20`. Failure mode signals: `ttyd-ws-upgrade accepted` with no `ttyd-proxy-open` → `maxy-ttyd.service` is down; `ttyd-proxy-open` with no `ttyd-proxy-chunk dir=upstream→client` → ttyd/tmux is not attaching a PTY. Full rewrite tracked in Task 658. The section below is kept only as a historical reference for devices still on pre-Task-657 bundles.