@rubytech/create-maxy 1.0.648 → 1.0.649

package/dist/index.js

@@ -208,7 +208,7 @@ function canSudo() {
 // ---------------------------------------------------------------------------
 // Installation steps
 // ---------------------------------------------------------------------------
-const TOTAL = "11";
+const TOTAL = "12";
 function installSystemDeps() {
     log("1", TOTAL, "System dependencies and network...");
     if (!isLinux()) {
@@ -220,6 +220,11 @@ function installSystemDeps() {
         shell("apt-get", ["install", "-y", "curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg"], { sudo: true });
         shell("apt-get", ["install", "-y", "tigervnc-standalone-server", "python3-websockify", "novnc", "xdg-utils", "chromium"], { sudo: true });
         shell("apt-get", ["install", "-y", "hostapd", "dnsmasq"], { sudo: true });
+        // ttyd + tmux power the admin terminal surface (Task 591) — ttyd serves a
+        // WebSocket PTY on 127.0.0.1:7681, tmux provides the persistent named
+        // session that outlives admin-server restarts. Both are in Debian/Raspbian
+        // repos; no third-party source needed.
+        shell("apt-get", ["install", "-y", "ttyd", "tmux"], { sudo: true });
     }
     else {
         console.log("  Skipping apt-get (sudo unavailable non-interactively — deps assumed present from prior install)");
@@ -1499,8 +1504,65 @@ function installCrons() {
         logFile(`  crontab write failed: ${write.stderr}`);
     }
 }
+function installTerminalService() {
+    log("11", TOTAL, "Installing admin terminal service (ttyd + tmux)...");
+    if (!isLinux()) {
+        console.log("  Skipping admin terminal service (not Linux). On macOS start manually:");
+        console.log("    brew install ttyd tmux && ttyd -p 7681 -i 127.0.0.1 -W tmux new-session -A -s maxy-pty");
+        return;
+    }
+    // Default ~/.tmux.conf — only written if the operator doesn't already have
+    // one. `history-limit 50000` is load-bearing: a closed-tab + reopen during
+    // an upgrade must show every line the operator missed in scrollback.
+    const homeDir = process.env.HOME ?? "/root";
+    const tmuxConfDest = resolve(homeDir, ".tmux.conf");
+    if (!existsSync(tmuxConfDest)) {
+        const tmuxConfTemplate = resolve(INSTALL_DIR, "platform/templates/dotfiles/.tmux.conf");
+        try {
+            if (existsSync(tmuxConfTemplate)) {
+                writeFileSync(tmuxConfDest, readFileSync(tmuxConfTemplate, "utf-8"));
+                console.log(`  Wrote default ~/.tmux.conf (history-limit 50000)`);
+            }
+            else {
+                // Fallback if the template was not in the payload for any reason —
+                // preserves the load-bearing scrollback-size guarantee.
+                writeFileSync(tmuxConfDest, "set -g history-limit 50000\n");
+                console.log(`  Wrote default ~/.tmux.conf (fallback — template missing)`);
+            }
+        }
+        catch (err) {
+            console.error(`  WARNING: failed to write ~/.tmux.conf: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Install and enable the maxy-ttyd.service --user unit. Independent of
+    // BRAND.serviceName — a single device runs one admin terminal regardless of
+    // brand, because the unit binds to 127.0.0.1:7681 which only one process can
+    // hold anyway. On a multi-brand device, the first brand's install writes the
+    // unit and every subsequent install is a no-op (idempotent overwrite).
+    const systemdUserDir = resolve(homeDir, ".config/systemd/user");
+    mkdirSync(systemdUserDir, { recursive: true });
+    const ttydUnitTemplate = resolve(INSTALL_DIR, "platform/templates/systemd/maxy-ttyd.service");
+    const ttydUnitDest = join(systemdUserDir, "maxy-ttyd.service");
+    try {
+        if (existsSync(ttydUnitTemplate)) {
+            writeFileSync(ttydUnitDest, readFileSync(ttydUnitTemplate, "utf-8"));
+        }
+        else {
+            console.error(`  WARNING: maxy-ttyd.service template missing at ${ttydUnitTemplate} — admin terminal will not work`);
+            return;
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to write ${ttydUnitDest}: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", "maxy-ttyd"], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", "maxy-ttyd"], { stdio: "inherit" });
+    console.log("  maxy-ttyd.service enabled — admin terminal available on 127.0.0.1:7681");
+}
 function installService() {
-    log("11", TOTAL, `Starting ${BRAND.productName}...`);
+    log("12", TOTAL, `Starting ${BRAND.productName}...`);
     if (!isLinux()) {
         console.log("  Skipping systemd service (not Linux). Start manually with:");
         console.log(`  cd ${INSTALL_DIR}/server && MAXY_PLATFORM_ROOT=${INSTALL_DIR}/platform PORT=${PORT} HOSTNAME=0.0.0.0 KEEP_ALIVE_TIMEOUT=61000 node --require ./server-init.cjs server.js`);
@@ -2042,6 +2104,7 @@ try {
     setupVncViewer();
     setupAccount();
     installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract
+    installTerminalService(); // Task 591: ttyd + tmux systemd --user unit (sibling of maxy-ui)
     installService();
     console.log("");
     console.log("================================================================");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.648",
+  "version": "1.0.649",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

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

@@ -66,6 +66,15 @@ The logs will show which service failed to start and why. Common causes:
 - **Port 19200 already in use** — check for another process: `lsof -i :19200`
 - **Claude OAuth expired** — the next admin session will prompt you to re-authenticate
 
+## Systemd units on each device
+
+Each Maxy device runs two independent `--user` systemd units:
+
+- `maxy-ui.service` — the admin + public HTTP server (default port 19200). Restarted by the upgrade flow; short downtime is expected during steps 8→12 of an upgrade.
+- `maxy-ttyd.service` — a persistent PTY over WebSocket on `127.0.0.1:7681` attached to a tmux session named `maxy-pty`. Independent of `maxy-ui` — restarting the UI does not interrupt shell work, which is exactly the property the upgrade flow relies on to survive its own admin-server restart.
+
+If the Software Update window's terminal goes blank and does not reconnect, `sudo systemctl --user status maxy-ttyd` is the first thing to check. Restarting the unit (`sudo systemctl --user restart maxy-ttyd`) is safe: the tmux session survives because `tmux new-session -A -s maxy-pty` is idempotent.
+
 ## 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.
@@ -76,4 +85,6 @@ The docs plugin (this plugin) is upgraded in the same step — you always have t
 
 Maxy 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.
 
+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 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.

package/payload/platform/plugins/docs/references/getting-started.md

@@ -40,6 +40,8 @@ When you first open the admin interface:
 
 This setup is resumable — if you close the browser mid-setup, Maxy picks up where you left off next time.
 
+After install, a live admin terminal is available inside the Software Update window — your Pi's shell, accessible through the admin UI, for upgrades and any other shell work without needing to SSH.
+
 ## How to Use Maxy
 
 Conversation is the only interface. Type or speak what you need:

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

@@ -84,9 +84,9 @@ 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 the Neo4j Browser at any time from the burger menu → **Graph**. Sign in with your Neo4j username (`neo4j`) and password (stored in `config/.neo4j-password` on the device). Run `MATCH (n) RETURN n LIMIT 25` for a visual overview of your graph, or write your own Cypher for ad-hoc exploration.
+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.
 
-The browser reaches only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop.
+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.
 
 ## Privacy
 

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

@@ -62,6 +62,12 @@ There is no dashboard, no settings panel, no menus. Everything is done through c
 
 The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
 
+## Admin Terminal
+
+The admin UI includes a live terminal surface that opens a real shell on your Pi in the browser, reached via the Software Update modal. Under the hood it's a WebSocket (`/admin/terminal/ws`) attached through `@xterm/xterm` to `ttyd` on `127.0.0.1:7681`, backed by a persistent tmux session named `maxy-pty`.
+
+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 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.
+
 ## 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

@@ -90,3 +90,19 @@ If the tunnel won't reconnect, re-run the Cloudflare setup: ask Maxy "Reconnect
 If the initial Cloudflare login fails during setup, Maxy will fall back to asking you for a connection key. You can create one in the Cloudflare dashboard (Maxy will guide you through this in the browser).
 
 **If you switched Cloudflare accounts or are stuck on the wrong one:** ask Maxy "Reset my Cloudflare login and start over." This is a clean reset — Maxy clears every stored credential, then opens a fresh browser sign-in. The next sign-in binds to whichever Cloudflare account you choose, with no risk of the previous account's stored credentials silently coming back.
+
+---
+
+## Admin Terminal Stuck Disconnected After Upgrade
+
+**Symptom:** The Software Update window's terminal goes blank, says "server restart detected — reconnecting…" and never comes back, or the window sits empty after you open it.
+
+**Check:** `sudo systemctl --user status maxy-ttyd` — the unit should be `active (running)`. If it is, the admin-server proxy should reattach automatically within a few seconds.
+
+**Fix:** Restart the unit:
+
+```bash
+sudo systemctl --user restart maxy-ttyd
+```
+
+This is safe — the tmux session survives the ttyd restart because `tmux new-session -A -s maxy-pty` is idempotent. Any upgrade or other shell command still running inside the session continues uninterrupted; ttyd simply re-attaches to it. If the session itself is wedged, you can kill it explicitly with `tmux kill-session -t maxy-pty` and the next attach will create a fresh one.

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -17,11 +17,11 @@ filter in the query.
 
 For visual exploration ("can I see this graphically?", "show me the graph"),
 tell the user to open the **Graph** menu item in the burger menu — it opens
-Neo4j Browser pointed at their own brand's graph. Do not build ad-hoc HTML
-visualizations, do not start a static file server, do not `Write` an
-`.html` file and navigate Playwright to it. The one-sentence reply
-("Open the Graph menu item in the top-right — it opens a visual browser
-for your graph") is the correct answer.
+a Maxy-native force-directed view of their own brand's subgraph (Task 587).
+Do not build ad-hoc HTML visualizations, do not start a static file server,
+do not `Write` an `.html` file and navigate Playwright to it. The one-sentence
+reply ("Open the Graph menu item in the top-right — it opens a visual view
+of your graph") is the correct answer.
 
 ## When the graph tools are absent
 

package/payload/platform/templates/dotfiles/.tmux.conf

@@ -0,0 +1 @@
+set -g history-limit 50000

package/payload/platform/templates/systemd/maxy-ttyd.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Maxy admin terminal (ttyd + tmux) — persistent PTY for admin UI
+After=default.target
+
+[Service]
+Type=simple
+# -p 7681   listen on 127.0.0.1:7681 (same-origin proxy in maxy-ui binds to it)
+# -i 127.0.0.1   reject non-loopback connections at the ttyd layer as well
+# -W        writable (allow client → server input bytes)
+# tmux new-session -A -s maxy-pty   attach if session exists, create otherwise.
+#   Lifetime = user session / device lifetime. Outlives maxy-ui restarts because
+#   this unit has no After=maxy-ui.service and no Requires= — independent.
+# -x 200 -y 50  initial geometry; xterm.js fit-addon drives runtime resizes.
+ExecStart=/usr/bin/ttyd -p 7681 -i 127.0.0.1 -W tmux new-session -A -s maxy-pty -x 200 -y 50
+Environment=TERM=xterm-256color
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target