@rubytech/create-maxy-code 0.1.194 → 0.1.196

package/dist/__tests__/samba-provision.test.js

@@ -62,7 +62,7 @@ test("pickLanInterface: returns null when the only non-loopback iface has no IPv
 // renderBrandStanza — exact spec match
 // ---------------------------------------------------------------------------
 test("renderBrandStanza emits the spec directives in order", () => {
-    const stanza = renderBrandStanza({ brand: "maxy-code", sharePath: "/home/admin/maxy-code" });
+    const stanza = renderBrandStanza({ brand: "maxy-code", sharePath: "/home/admin/maxy-code", installOwner: "admin" });
     assert.equal(stanza, [
         "[maxy-code]",
         "   path = /home/admin/maxy-code",
@@ -76,11 +76,34 @@ test("renderBrandStanza emits the spec directives in order", () => {
     ].join("\n"));
 });
 test("renderBrandStanza handles realagent-code with its own share path", () => {
-    const stanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code" });
+    const stanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code", installOwner: "admin" });
     assert.match(stanza, /^\[realagent-code\]\n/);
     assert.match(stanza, /\n   path = \/home\/admin\/realagent-code\n/);
     assert.match(stanza, /\n   force user = admin\n/);
 });
+test("renderBrandStanza substitutes a non-admin install owner into valid users and force user", () => {
+    // Laptop case (Task 534): the install owner is the operator's Unix user
+    // (`neo` etc.), not the literal `admin`. The same renderer must produce a
+    // stanza whose `valid users` and `force user` name that owner, so SMB
+    // clients authenticate as a Unix user that actually exists on the device.
+    const stanza = renderBrandStanza({ brand: "maxy-code", sharePath: "/home/neo/maxy-code", installOwner: "neo" });
+    assert.match(stanza, /\n   valid users = neo\n/);
+    assert.match(stanza, /\n   force user = neo\n/);
+    assert.doesNotMatch(stanza, /valid users = admin/);
+    assert.doesNotMatch(stanza, /force user = admin/);
+});
+test("mergeSmbConf preserves a peer brand stanza when the new install owner differs", () => {
+    // Peer-brand isolation must hold across owners: a laptop install
+    // (installOwner=neo) adding its `[maxy-code]` stanza to a conf that
+    // already holds a peer `[realagent-code]` stanza provisioned for owner
+    // `admin` must leave the peer stanza byte-identical. The new stanza
+    // carries the laptop owner; the peer keeps its own. Task 534.
+    const peerStanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code", installOwner: "admin" });
+    const existing = renderGlobalSection({ lanInterface: "eth0" }) + peerStanza;
+    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/neo/maxy-code", lanInterface: "wlan0", installOwner: "neo" });
+    assert.ok(merged.includes(peerStanza), "peer brand stanza must survive unchanged");
+    assert.match(merged, /\[maxy-code\][\s\S]+valid users = neo[\s\S]+force user = neo/);
+});
 // ---------------------------------------------------------------------------
 // renderGlobalSection — LAN-only enforcement
 // ---------------------------------------------------------------------------
@@ -96,7 +119,7 @@ test("renderGlobalSection binds to lo + LAN interface only", () => {
 // renderFullSmbConf — composition order
 // ---------------------------------------------------------------------------
 test("renderFullSmbConf places globals before the brand stanza", () => {
-    const conf = renderFullSmbConf({ brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
+    const conf = renderFullSmbConf({ brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
     const globalIdx = conf.indexOf("[global]");
     const brandIdx = conf.indexOf("[maxy-code]");
     assert.ok(globalIdx >= 0 && brandIdx > globalIdx, "[global] must come before [maxy-code]");
@@ -105,13 +128,13 @@ test("renderFullSmbConf places globals before the brand stanza", () => {
 // mergeSmbConf — idempotency and section preservation
 // ---------------------------------------------------------------------------
 test("mergeSmbConf: empty existing conf gets globals + brand stanza", () => {
-    const merged = mergeSmbConf({ existing: "", brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
+    const merged = mergeSmbConf({ existing: "", brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
     assert.match(merged, /\[global\][\s\S]+\[maxy-code\]/);
     assert.match(merged, /interfaces = lo wlan0/);
 });
 test("mergeSmbConf: idempotent on second application", () => {
-    const once = mergeSmbConf({ existing: "", brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
-    const twice = mergeSmbConf({ existing: once, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
+    const once = mergeSmbConf({ existing: "", brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
+    const twice = mergeSmbConf({ existing: once, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
     assert.equal(twice, once, "second merge must produce byte-identical output");
 });
 test("mergeSmbConf: replaces an existing global section in place, preserving peer stanzas", () => {
@@ -125,26 +148,26 @@ test("mergeSmbConf: replaces an existing global section in place, preserving pee
         "   guest ok = yes",
         "",
     ].join("\n");
-    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
+    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
     assert.match(merged, /interfaces = lo wlan0/);
     assert.doesNotMatch(merged, /workgroup = OLDGROUP/);
     assert.match(merged, /\[printers\][\s\S]+path = \/var\/spool\/samba/, "[printers] stanza must survive");
     assert.match(merged, /\[maxy-code\][\s\S]+path = \/home\/admin\/maxy-code/);
 });
 test("mergeSmbConf: replaces an existing brand stanza in place, leaves peer brand alone", () => {
-    const peerStanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code" });
+    const peerStanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code", installOwner: "admin" });
     const oldBrandStanza = "[maxy-code]\n   path = /OLD/PATH\n   read only = yes\n\n";
     const existing = renderGlobalSection({ lanInterface: "eth0" }) + oldBrandStanza + peerStanza;
-    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
+    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
     assert.doesNotMatch(merged, /\/OLD\/PATH/, "old maxy-code path must be replaced");
     assert.doesNotMatch(merged, /read only = yes/, "old maxy-code directives must be replaced");
     assert.match(merged, /\[realagent-code\][\s\S]+path = \/home\/admin\/realagent-code/, "peer brand stanza must survive");
     assert.match(merged, /\[maxy-code\][\s\S]+path = \/home\/admin\/maxy-code/);
 });
 test("mergeSmbConf: appends brand stanza when not present, keeps existing peer stanzas", () => {
-    const peerStanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code" });
+    const peerStanza = renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code", installOwner: "admin" });
     const existing = renderGlobalSection({ lanInterface: "eth0" }) + peerStanza;
-    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
+    const merged = mergeSmbConf({ existing, brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
     assert.match(merged, /\[realagent-code\]/, "peer brand stanza must survive");
     assert.match(merged, /\[maxy-code\][\s\S]+path = \/home\/admin\/maxy-code/, "new brand stanza must be appended");
 });
@@ -153,10 +176,11 @@ test("mergeSmbConf: appends brand stanza when not present, keeps existing peer s
 // ---------------------------------------------------------------------------
 test("removeBrandStanza: removes only this brand, leaves peer brand and global intact", () => {
     const conf = mergeSmbConf({
-        existing: renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code" }),
+        existing: renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code", installOwner: "admin" }),
         brand: "maxy-code",
         sharePath: "/home/admin/maxy-code",
         lanInterface: "wlan0",
+        installOwner: "admin",
     });
     const after = removeBrandStanza({ existing: conf, brand: "maxy-code" });
     assert.doesNotMatch(after, /\[maxy-code\]/);
@@ -164,7 +188,7 @@ test("removeBrandStanza: removes only this brand, leaves peer brand and global i
     assert.match(after, /\[global\]/);
 });
 test("removeBrandStanza: returns input unchanged when stanza is absent", () => {
-    const conf = mergeSmbConf({ existing: "", brand: "realagent-code", sharePath: "/home/admin/realagent-code", lanInterface: "wlan0" });
+    const conf = mergeSmbConf({ existing: "", brand: "realagent-code", sharePath: "/home/admin/realagent-code", lanInterface: "wlan0", installOwner: "admin" });
     const after = removeBrandStanza({ existing: conf, brand: "maxy-code" });
     assert.equal(after, conf);
 });
@@ -177,12 +201,12 @@ test("hasAnyBrandStanza: false when only [global] is present", () => {
 });
 test("hasAnyBrandStanza: true when any non-global stanza is present", () => {
     const conf = renderGlobalSection({ lanInterface: "wlan0" }) +
-        renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code" });
+        renderBrandStanza({ brand: "realagent-code", sharePath: "/home/admin/realagent-code", installOwner: "admin" });
     assert.equal(hasAnyBrandStanza(conf), true);
 });
 test("hasAnyBrandStanza: false when both brand stanzas have been removed", () => {
-    let conf = renderFullSmbConf({ brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0" });
-    conf = mergeSmbConf({ existing: conf, brand: "realagent-code", sharePath: "/home/admin/realagent-code", lanInterface: "wlan0" });
+    let conf = renderFullSmbConf({ brand: "maxy-code", sharePath: "/home/admin/maxy-code", lanInterface: "wlan0", installOwner: "admin" });
+    conf = mergeSmbConf({ existing: conf, brand: "realagent-code", sharePath: "/home/admin/realagent-code", lanInterface: "wlan0", installOwner: "admin" });
     conf = removeBrandStanza({ existing: conf, brand: "maxy-code" });
     conf = removeBrandStanza({ existing: conf, brand: "realagent-code" });
     assert.equal(hasAnyBrandStanza(conf), false);

package/dist/index.js

@@ -18,7 +18,7 @@ import { classifyPortHolder } from "./preflight-port-classifier.js";
 import { parsePluginList, computeInstallActions, computeConfigureActions, parseExternalPlugins, } from "./lib/plugin-install.js";
 import { findPremiumMcpDirs } from "./lib/premium-mcp-discover.js";
 import { pickLanInterface, mergeSmbConf, formatSambaMarker, } from "./samba-provision.js";
-import { networkInterfaces } from "node:os";
+import { networkInterfaces, userInfo } from "node:os";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -3371,12 +3371,16 @@ WantedBy=multi-user.target
 // marker:
 //   apt   — install the `samba` package
 //   conf  — write the brand stanza + LAN-only globals to /etc/samba/smb.conf
-//   user  — smbpasswd the admin Linux user; deferred at install time on fresh
-//           Pi installs (no plaintext PIN until the operator runs set-pin)
+//   user  — smbpasswd the install-owner Linux user; deferred at install time
+//           on fresh Pi installs (no plaintext PIN until the operator runs set-pin)
 //   units — systemctl enable --now smbd nmbd
 //
 // The platform's set-pin route handler closes the deferral loop by running
-// `smbpasswd -a admin` inline whenever the PIN is set or rotated.
+// `smbpasswd -a -s <install-owner>` inline whenever the PIN is set or
+// rotated. Install owner is the Unix user the installer is running as —
+// `admin` on a Pi/Hetzner box, `neo` (etc.) on a self-hosted laptop. It is
+// persisted to `~/.<brand>/.install-owner` so every later read uses the same
+// value the installer wrote.
 // ---------------------------------------------------------------------------
 function emitSambaMarker(step, state) {
     const line = formatSambaMarker(step, state);
@@ -3390,6 +3394,16 @@ function provisionSamba() {
     }
     const brand = BRAND.hostname;
     const sharePath = INSTALL_DIR;
+    // Install owner — the Unix user that owns this brand's install on the
+    // device. On a Pi/Hetzner box this is `admin`; on a self-hosted laptop it
+    // is the operator's Unix user (`neo` etc.). Persisted to a file next to
+    // the other install identity (`.neo4j-password`, `.admin-pin`) so the
+    // platform's set-pin route and the uninstall path read the same value the
+    // installer wrote, rather than re-detecting at request time. Task 534.
+    const installOwner = userInfo().username;
+    const installOwnerPersistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    mkdirSync(installOwnerPersistDir, { recursive: true });
+    writeFileSync(join(installOwnerPersistDir, ".install-owner"), `${installOwner}\n`, { mode: 0o644 });
     // Step 1 — apt install samba. Precheck `dpkg -s samba` first; if the
     // package is already installed, skip apt entirely so the install does not
     // contend with `unattended-upgrades` for `/var/lib/dpkg/lock-frontend`
@@ -3426,7 +3440,7 @@ function provisionSamba() {
         }
         catch { /* treat as empty */ }
     }
-    const merged = mergeSmbConf({ existing, brand, sharePath, lanInterface });
+    const merged = mergeSmbConf({ existing, brand, sharePath, lanInterface, installOwner });
     try {
         const tee = spawnSync("sudo", ["tee", SMB_CONF], { input: merged, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 });
         if (tee.status !== 0) {
@@ -3436,15 +3450,18 @@ function provisionSamba() {
         if (testparm.status !== 0) {
             throw new Error(`testparm rejected merged smb.conf: ${(testparm.stderr ?? "").trim()}`);
         }
-        // Grant passwordless sudo to the admin user for the two smbpasswd
-        // invocations the platform's set-pin route makes (add-user-with-stdin
-        // and remove-user). Without this, the user systemd-unit-spawned admin
-        // server cannot sync the SMB password when the operator sets/rotates
-        // the PIN. Scoped tight: only these two literal arg-vectors are
-        // permitted; every other smbpasswd flavour still prompts.
+        // Grant passwordless sudo to the install-owner Unix user for the two
+        // smbpasswd invocations the platform's set-pin route makes (add-user-
+        // with-stdin and remove-user). Without this, the user systemd-unit-
+        // spawned admin server cannot sync the SMB password when the operator
+        // sets/rotates the PIN. Scoped tight: only these two literal arg-vectors
+        // are permitted; every other smbpasswd flavour still prompts. Principal
+        // and `-a -s <user>` / `-x <user>` arguments are the install owner, not
+        // a literal `admin`, so the grant works on a Pi (owner=admin) and on a
+        // laptop (owner=neo) without divergence. Task 534.
         const SUDOERS = "/etc/sudoers.d/maxy-samba";
         const sudoersBody = "# maxy-code Samba provisioning (smbpasswd sync from platform set-pin route).\n" +
-            "admin ALL=(root) NOPASSWD: /usr/bin/smbpasswd -a -s admin, /usr/bin/smbpasswd -x admin\n";
+            `${installOwner} ALL=(root) NOPASSWD: /usr/bin/smbpasswd -a -s ${installOwner}, /usr/bin/smbpasswd -x ${installOwner}\n`;
         const sudoersTee = spawnSync("sudo", ["tee", SUDOERS], { input: sudoersBody, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5_000 });
         if (sudoersTee.status !== 0) {
             throw new Error(`sudo tee ${SUDOERS} exited ${sudoersTee.status}: ${(sudoersTee.stderr ?? "").trim()}`);
@@ -3454,18 +3471,20 @@ function provisionSamba() {
         if (visudoCheck.status !== 0) {
             throw new Error(`visudo rejected ${SUDOERS}: ${(visudoCheck.stderr ?? "").trim()}`);
         }
-        emitSambaMarker("conf", `ok lan=${lanInterface}`);
+        emitSambaMarker("conf", `ok lan=${lanInterface} owner=${installOwner}`);
     }
     catch (err) {
         const stderr = err instanceof Error ? err.message : String(err);
         emitSambaMarker("conf", `fail: ${stderr}`);
         throw err;
     }
-    // Step 3 — smbpasswd for the admin user. At install time the plaintext PIN
-    // is not in any file on disk (users.json stores the SHA-256 hash only); the
-    // platform's set-pin route is responsible for syncing on PIN set/rotate.
-    // Mark as deferred so the four-marker contract still fires unbroken.
-    emitSambaMarker("user", "deferred reason=no-plaintext-pin-at-install (set-pin route syncs)");
+    // Step 3 — smbpasswd for the install-owner Unix user. At install time the
+    // plaintext PIN is not in any file on disk (users.json stores the SHA-256
+    // hash only); the platform's set-pin route is responsible for syncing on
+    // PIN set/rotate. Mark as deferred so the four-marker contract still fires
+    // unbroken. Owner is recorded in the marker state so the install log shows
+    // which Unix user the smbpasswd entry will target. Task 534.
+    emitSambaMarker("user", `deferred reason=no-plaintext-pin-at-install owner=${installOwner} (set-pin route syncs)`);
     // Step 4 — enable + start smbd and nmbd.
     try {
         shell("systemctl", ["enable", "--now", "smbd", "nmbd"], { sudo: true, timeout: 30_000 });

package/dist/samba-provision.js

@@ -19,17 +19,20 @@
 // ---------------------------------------------------------------------------
 /**
  * Render the `[<brand>]` share stanza. Exact directives are the task's spec
- * verbatim: share rooted at `sharePath`, writable by `admin` only, force-uid
- * to admin so files created via SMB are owned by the same uid as files
- * created over SSH, and standard create/dir masks for an ext4 home directory.
+ * verbatim: share rooted at `sharePath`, writable by `installOwner` only,
+ * force-uid to `installOwner` so files created via SMB are owned by the same
+ * uid as files created over SSH, and standard create/dir masks for an ext4
+ * home directory. `installOwner` is the Unix user that owns this brand's
+ * install on the device — `admin` on a Pi or Hetzner box, the operator's
+ * Unix user on a self-hosted laptop. Task 534.
  */
 export function renderBrandStanza(input) {
     return [
         `[${input.brand}]`,
         `   path = ${input.sharePath}`,
         `   read only = no`,
-        `   valid users = admin`,
-        `   force user = admin`,
+        `   valid users = ${input.installOwner}`,
+        `   force user = ${input.installOwner}`,
         `   browseable = yes`,
         `   create mask = 0664`,
         `   directory mask = 0775`,
@@ -69,7 +72,7 @@ export function renderGlobalSection(input) {
  */
 export function renderFullSmbConf(input) {
     return renderGlobalSection({ lanInterface: input.lanInterface }) +
-        renderBrandStanza({ brand: input.brand, sharePath: input.sharePath });
+        renderBrandStanza({ brand: input.brand, sharePath: input.sharePath, installOwner: input.installOwner });
 }
 // ---------------------------------------------------------------------------
 // LAN interface detection
@@ -148,9 +151,9 @@ function findSectionRange(conf, section) {
  *     brand stanzas (other `[…]` blocks) are preserved verbatim.
  */
 export function mergeSmbConf(input) {
-    const { existing, brand, sharePath, lanInterface } = input;
+    const { existing, brand, sharePath, lanInterface, installOwner } = input;
     const newGlobals = renderGlobalSection({ lanInterface });
-    const newBrand = renderBrandStanza({ brand, sharePath });
+    const newBrand = renderBrandStanza({ brand, sharePath, installOwner });
     let conf = existing;
     // Replace or insert the global section.
     const globalRange = findSectionRange(conf, "global");

package/dist/uninstall.js

@@ -759,9 +759,25 @@ function removeSamba() {
     catch (err) {
         console.log(`  Failed to disable smbd/nmbd: ${err instanceof Error ? err.message : String(err)}`);
     }
-    // Drop the admin smbpasswd entry. `smbpasswd -x` exits 0 on success, non-zero
-    // if the user isn't in the passdb — both are acceptable end-states.
-    spawnSync("sudo", ["smbpasswd", "-x", "admin"], { stdio: "pipe", timeout: 10_000 });
+    // Drop the install-owner's smbpasswd entry. `smbpasswd -x` exits 0 on
+    // success, non-zero if the user isn't in the passdb — both are acceptable
+    // end-states. Owner is read from the persisted file the installer wrote
+    // so the cleanup targets the same Unix user the provisioning step keyed
+    // on (Task 534): `admin` on a Pi/Hetzner box, `neo` (etc.) on a laptop.
+    // Missing file falls back to `admin` because an install that ran before
+    // the install-owner persistence existed only ever provisioned `admin`.
+    const installOwnerFile = join(CONFIG_DIR, ".install-owner");
+    let installOwner = "admin";
+    if (existsSync(installOwnerFile)) {
+        try {
+            const raw = readFileSync(installOwnerFile, "utf-8").trim();
+            if (raw.length > 0)
+                installOwner = raw;
+        }
+        catch { /* keep default */ }
+    }
+    spawnSync("sudo", ["smbpasswd", "-x", installOwner], { stdio: "pipe", timeout: 10_000 });
+    console.log(`  smbpasswd -x ${installOwner}`);
     try {
         shell("apt-get", ["remove", "--purge", "-y", "samba", "samba-common-bin"], { sudo: true, timeout: 120_000 });
         console.log("  Purged samba package.");

package/package.json

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

package/payload/platform/plugins/docs/references/access-control.md

@@ -78,3 +78,7 @@ Tell {{productName}} to change which actions require approval:
 - "What actions currently require my approval?" — lists the current policy
 
 Changes are per-account and take effect immediately.
+
+## Filesystem Access (SMB Share)
+
+Brand isolation extends to the device filesystem. Every {{productName}} install provisions an SMB share scoped to that brand's install folder, credentialled by the brand's install owner and the {{productName}} PIN. A device that hosts more than one brand carries one share per brand; tearing one brand down never exposes another brand's files. See [Samba Share](./samba.md) for the credential model, per-OS mount syntax, and peer-brand lifecycle.

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

@@ -121,25 +121,7 @@ If you need to restart the service manually (rare), ask {{productName}} to do it
 
 ## Browsing the brand filesystem on your LAN (SMB)
 
-{{productName}} exposes its install folder (`/home/admin/<brand>` on the Pi) as a network share so you can drop files in, drag files out, and edit them from your Mac, Windows PC, iPhone, or Android device. It uses SMB — the same protocol Windows file sharing uses — which every modern OS speaks natively. No client install required.
-
-The share is **LAN-only**: it binds to the loopback and your Pi's Wi-Fi/Ethernet interface only. Cloudflare tunnels carry HTTPS for the web UI, not SMB, so the share is invisible from the public internet. Off-LAN access for travelling operators is handled by a separate route (in progress).
-
-**Credentials:** SMB user is `admin`; password is your {{productName}} PIN. The installer wires the sync so every time you set or rotate the PIN in the admin UI, the SMB password updates with it.
-
-The SMB username is the Linux user that owns the install on the device — `admin` on a Pi or a Hetzner box, your own Linux user (for example `neo`) on a self-hosted laptop install. The password is your {{productName}} PIN. Changing the PIN in the admin UI re-syncs the SMB password for that same Unix user automatically.
-
-**macOS Finder**: Press `Cmd-K` from any Finder window, type `smb://<hostname>.local` (use the hostname your installer printed — for example `smb://maxy-code.local` or `smb://realagent-code.local`), click Connect, sign in as the install owner with your PIN. The share appears in the Finder sidebar; drag-and-drop works in both directions.
-
-**Windows Explorer**: Open File Explorer, type `\\<hostname>.local\<brand>` in the address bar (for example `\\maxy-code.local\maxy-code`), press Enter, sign in as the install owner with your PIN. To keep it across reboots, right-click → "Map network drive".
-
-**iOS Files**: Open Files → tap the `…` menu (top-right) → "Connect to Server" → enter `smb://<hostname>.local` → "Registered User" → username is the install owner, password is your PIN.
-
-**Android (Solid Explorer, CX File Explorer)**: Add a new connection of type SMB / Network. Host = `<hostname>.local`, share = `<brand>` (same as your install folder name), user = the install owner, password = your PIN.
-
-**Troubleshooting:** if the mount fails with "logon failure", change your PIN in the admin UI and try again — that re-triggers the smbpasswd sync. If the share doesn't show up at all, your client may need `<hostname>.local` resolved by mDNS — try the Pi's LAN IP address as a fallback (`smb://192.168.1.50` on macOS, `\\192.168.1.50\<brand>` on Windows).
-
-The installer maintains the share automatically. To remove it, uninstalling the brand strips its stanza from `/etc/samba/smb.conf` and (when no peer brand remains on the device) stops `smbd`, drops the smbpasswd entry, and purges the samba package.
+Every install provisions a per-brand SMB share against the brand's install folder. See [Samba Share](./samba.md) for the share path, credentials, per-OS mount instructions, peer-brand lifecycle, and the LAN-only binding posture.
 
 ## Remote Access via Cloudflare
 

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

@@ -0,0 +1,80 @@
+# Samba Share
+
+Every {{productName}} install provisions a per-brand SMB network share so you can read and write the brand's install folder from Finder, File Explorer, the Files app on iOS, or any SMB-capable client on Android or Linux. No client install required — every modern OS speaks SMB natively.
+
+The share lives next to the rest of the brand. On a device that runs more than one brand, each brand gets its own stanza, its own credentials, and its own lifecycle. Tearing one brand down never touches another brand's share.
+
+## What gets provisioned
+
+The installer runs the same Samba step on every supported footprint — Raspberry Pi, Hetzner Cloud server, and self-hosted Linux laptop. Four sub-steps emit `[install-invariant] samba-provision-<step>` markers in order:
+
+1. **apt** — installs the `samba` package (skipped if `dpkg -s samba` already reports installed, so re-runs don't fight `unattended-upgrades` for the dpkg lock).
+2. **conf** — writes `/etc/samba/smb.conf` with a LAN-only `[global]` section plus a `[<brand>]` stanza pointing at the brand's install directory. The stanza is owned by the install owner (see below) and is marked `read only = no`, `browseable = yes`.
+3. **user** — deferred at install time on a fresh Pi or Hetzner box because there is no PIN to hand to `smbpasswd` yet. The user is created the moment the operator sets a PIN in the admin UI (see "PIN rotation" below).
+4. **units** — `systemctl enable --now smbd nmbd` so the share is reachable as soon as the install finishes.
+
+macOS install is a no-op for this step — the installer logs `samba-provision skipped: platform=darwin` and returns. Mac operators do not get an SMB share against their laptop.
+
+## Share path
+
+| Client | Address |
+|---|---|
+| macOS Finder | `smb://<hostname>.local` then pick the `<brand>` share |
+| Windows Explorer | `\\<hostname>.local\<brand>` |
+| Linux (`mount.cifs`, Nautilus, KDE) | `//<hostname>.local/<brand>` |
+| iOS Files | `smb://<hostname>.local` |
+| Android (Solid Explorer, CX File Explorer) | Host `<hostname>.local`, share `<brand>` |
+
+`<hostname>` is whatever the installer printed at the end of `npx @rubytech/create-<brand>-code install` — usually the brand name on a fresh Pi (`maxy-code.local`, `realagent-code.local`). `<brand>` is the same string — it is also the install folder name under the install owner's home.
+
+If `<hostname>.local` does not resolve from your client (some networks do not route mDNS), fall back to the LAN IP: `smb://192.168.1.50` on macOS, `\\192.168.1.50\<brand>` on Windows.
+
+## Credentials
+
+- **Username** — the Unix user that owns the install on the device. On a Pi or Hetzner box this is `admin`; on a self-hosted Linux laptop it is whatever Linux user ran the installer (for example `neo`). The installer persists this value to `~/.<brand>/.install-owner` so every later read uses the same identity the installer wrote.
+- **Password** — your current {{productName}} PIN. The same PIN that unlocks the admin UI unlocks the SMB share.
+
+Both halves are required. SMB never accepts a guest connection; `map to guest = bad user` is set in the global stanza.
+
+## PIN rotation
+
+There is no separate "SMB password." When you set or rotate the PIN in the admin UI, the platform's `set-pin` route runs `sudo -n smbpasswd -a -s <install-owner>` inline with the new PIN, behind a `NOPASSWD` sudoers grant written at install time and scoped to that exact command.
+
+So:
+
+- On a fresh Pi or Hetzner box, the share is reachable as soon as you set the first PIN. Before that point the `smbpasswd` entry does not exist and the mount fails with a logon error — that is expected.
+- Rotating the PIN re-syncs the SMB password to the new value on the next set-pin request. Mounts using the old PIN start failing immediately; remount with the new PIN.
+- If `set-pin` cannot read `~/.<brand>/.install-owner` (file missing or empty), it logs `[set-pin] smbpasswd sync failed owner=<unknown> rc=-1 reason=install-owner-file-missing` and skips the sync. The PIN still writes to the admin UI, but the SMB mount keeps refusing the new password until the install-owner file is restored.
+
+## LAN-only binding
+
+The `[global]` section binds smbd to loopback plus one LAN interface:
+
+```
+interfaces = lo <lan>
+bind interfaces only = yes
+```
+
+`<lan>` is whichever non-loopback interface has an IPv4 address — `wlan0` preferred, then `eth0`, then the first other interface with an address. If the device has no LAN interface at all, the installer refuses to provision and exits — there is nothing safe to bind to.
+
+This is the structural guarantee that SMB never leaves the LAN, even if upstream firewall rules are misconfigured. The Cloudflare tunnel that fronts the admin UI carries HTTPS only; it does not route SMB. **On a Hetzner box the share is therefore not reachable from the public internet** — operators reach it by `ssh -L 4445:localhost:445 admin@<tunnel-host>` and then mounting `smb://localhost:4445`, or by running the Hetzner box on a private network that the operator's machine also joins.
+
+## Peer-brand lifecycle
+
+A device that hosts more than one brand carries one stanza per brand in `/etc/samba/smb.conf`. The provisioner is idempotent and peer-safe:
+
+- **Install a second brand** — the new brand's stanza is appended next to the existing one. The shared `[global]` section is rewritten to keep the LAN-only directives current but is otherwise unchanged. Peer-brand stanzas are preserved byte-for-byte.
+- **Re-run the installer on an existing brand** — the brand's own stanza is replaced in place. Peer stanzas are not touched.
+- **Uninstall one brand** — only that brand's stanza is stripped. `smbd` is then `reload`ed so the brand share disappears from the running config without dropping connections to peer shares.
+- **Uninstall the last brand** — after the stanza is removed, the uninstaller checks `hasAnyBrandStanza()` and, if false, stops and disables `smbd`/`nmbd`, runs `smbpasswd -x <install-owner>` to drop the smbpasswd entry, and `apt-purge samba`. If any peer stanza remains, the units stay running and the package stays installed — the uninstaller logs `Leaving smbd/nmbd + samba package in place — other brand stanza remains`.
+
+The brand-stanza name is the only identifier the uninstaller matches on, so two brands with different `BRAND.hostname` values cannot collide.
+
+## Troubleshooting
+
+- **"Logon failure" on mount.** The PIN you typed does not match the current `smbpasswd` entry. Set a new PIN in the admin UI and remount. If the PIN was just rotated and the mount still fails, check `~/.<brand>/.install-owner` exists and is non-empty.
+- **Share does not show up in Finder / network browser.** mDNS may not be routed on your network. Mount by LAN IP instead of `<hostname>.local`.
+- **`smbd` not running after install.** Check the install log for the four `[install-invariant] samba-provision-<step>` markers. The `units` step running `systemctl enable --now smbd nmbd` is the last to fire; if it failed the marker prints `fail: <reason>`.
+- **Hetzner share not reachable from outside the box.** This is by design — see "LAN-only binding" above. Use SSH port forwarding.
+
+Also see [Deployment Guide](./deployment.md) for the surrounding install flow, and [Access Control](./access-control.md) for how the brand isolation extends from the admin UI to the SMB share.

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

@@ -134,6 +134,20 @@ tail -200 ~/.maxy/logs/maxy-ui.log | rg '\[remote-auth\].*resolvedKind='
 
 ---
 
+## Cannot Mount the SMB Share
+
+**Symptom:** Mounting `smb://<hostname>.local` (or `\\<hostname>.local\<brand>`) fails with a "logon failure" or the share does not appear in your network browser.
+
+**Check:**
+1. Confirm you have set a PIN in the admin UI at least once. On a fresh Pi or Hetzner box the `smbpasswd` entry does not exist until the first set-pin runs — mounts before that point always fail.
+2. Use the install owner as the username (`admin` on a Pi or Hetzner box; the Linux user that ran the installer on a self-hosted laptop) and the current {{productName}} PIN as the password. The SMB password is not stored separately — it is the PIN.
+3. If `<hostname>.local` does not resolve from your client, mount by LAN IP instead (`smb://192.168.1.50` on macOS, `\\192.168.1.50\<brand>` on Windows).
+4. Rotate the PIN in the admin UI. That re-triggers the `smbpasswd` sync on the device. If the resync log line reads `[set-pin] smbpasswd sync failed owner=<unknown> rc=-1 reason=install-owner-file-missing`, restore `~/.<brand>/.install-owner` from the installer log.
+
+See [Samba Share](./samba.md) for the full credential model and per-OS mount syntax.
+
+---
+
 ## Restarting the Platform
 
 From the admin interface, ask {{productName}}: "Restart the platform."

package/payload/platform/services/claude-session-manager/dist/http-server.d.ts

@@ -4,9 +4,6 @@ import type { FsWatcher } from './fs-watcher.js';
 import type { RateLimiter } from './spawn-rate-limiter.js';
 import type { AuditRegistry } from './public-tool-audit.js';
 import { type UserTitleStore } from './user-title-store.js';
-/** Test-only — clear the dedup cache between vitest cases so module state
- *  does not leak across describe blocks. */
-export declare function __resetResumeDedupCacheForTests(): void;
 export declare const SESSION_ID_PATTERN: RegExp;
 export interface HttpDeps extends Omit<SpawnDeps, 'onSessionReady' | 'watcher'> {
     watcher: FsWatcher;

package/payload/platform/services/claude-session-manager/dist/http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,EAcL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAYzB,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAwB9E;4CAC4C;AAC5C,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAwED,eAAO,MAAM,kBAAkB,QAA2B,CAAA;AAI1D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;CAC/B;AA4LD;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAo5CpD"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,EAcL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAYzB,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AA+E9E,eAAO,MAAM,kBAAkB,QAA2B,CAAA;AAI1D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;CAC/B;AA4LD;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CA+oCpD"}