@jlongo78/agent-spaces 0.10.0-beta.2 → 0.10.0-beta.4

package/.next/standalone/docs/plans/2026-03-07-service-command-design.md

@@ -1,146 +0,0 @@
-# Design: `spaces service` subcommand
-
-**Date:** 2026-03-07
-
-## Purpose
-
-Allow customers to install Spaces as a persistent system service so it starts automatically on boot/login without manual intervention.
-
-## CLI Interface
-
-```
-spaces service install     # prompts: system or user level
-spaces service uninstall   # stops, disables, removes service config
-spaces service start       # starts via service manager
-spaces service stop        # stops via service manager
-spaces service status      # shows running state
-spaces service logs        # tails service logs
-```
-
-## Config Capture
-
-`install` reads the current resolved config (port, tier, base-path, allowed-origins) from `~/.spaces/server.json` and bakes them into the service definition as environment variables. Also captures:
-
-- `process.execPath` — exact node binary (handles nvm/fnm)
-- Resolved path to `bin/spaces.js`
-
-Running `install` again overwrites the existing definition and restarts — idempotent, safe to re-run after config changes.
-
-## Install Prompt
-
-```
-  Install as:
-    1. System service (starts on boot, runs as root)
-    2. User service (starts on login, runs as your user)
-  Choice [2]:
-```
-
-Default is user-level (most customers won't have root/admin).
-
-## Platform: Linux (systemd)
-
-**User service:** `~/.config/systemd/user/spaces.service`, managed with `systemctl --user`.
-
-**System service:** `/etc/systemd/system/spaces.service`, managed with `systemctl`. Runs as the installing user (`User=`/`Group=` directives). Re-execs with `sudo` if needed.
-
-Unit file template (user-level):
-
-```ini
-[Unit]
-Description=Spaces - Agent Workspace Manager
-After=network.target
-
-[Service]
-Type=simple
-ExecStart=/path/to/node /path/to/spaces.js
-WorkingDirectory=/path/to/spaces/project
-Environment=SPACES_PORT=3457
-Environment=SPACES_TIER=community
-Environment=SPACES_BASE_PATH=
-Environment=SPACES_ALLOWED_ORIGINS=
-Restart=on-failure
-RestartSec=5
-
-[Install]
-WantedBy=default.target
-```
-
-System-level uses `multi-user.target` and adds `User=`/`Group=`.
-
-After writing, `install` runs `daemon-reload`, `enable`, and `start`.
-
-**Logs:** `journalctl --user -u spaces -f` (user) or `journalctl -u spaces -f` (system).
-
-## Platform: macOS (launchd)
-
-**User service:** `~/Library/LaunchAgents/com.agentspaces.spaces.plist`
-
-**System service:** `/Library/LaunchDaemons/com.agentspaces.spaces.plist` (requires sudo, uses `UserName` key).
-
-Plist template:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
-  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.agentspaces.spaces</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/path/to/node</string>
-        <string>/path/to/spaces.js</string>
-    </array>
-    <key>WorkingDirectory</key>
-    <string>/path/to/spaces/project</string>
-    <key>EnvironmentVariables</key>
-    <dict>
-        <key>SPACES_PORT</key><string>3457</string>
-        <key>SPACES_TIER</key><string>community</string>
-    </dict>
-    <key>RunAtLoad</key><true/>
-    <key>KeepAlive</key><true/>
-    <key>StandardOutPath</key>
-    <string>/path/to/.spaces/logs/spaces.out.log</string>
-    <key>StandardErrorPath</key>
-    <string>/path/to/.spaces/logs/spaces.err.log</string>
-</dict>
-</plist>
-```
-
-**Logs:** `tail -f ~/.spaces/logs/spaces.out.log`
-
-`install` runs `launchctl load -w` / `launchctl bootstrap`. `uninstall` runs `launchctl unload` then deletes the plist.
-
-## Platform: Windows (Task Scheduler)
-
-Both user and system level use Task Scheduler (avoids needing `node-windows` or similar deps).
-
-**User service:** `schtasks /Create /TN "Spaces" /TR "..." /SC ONLOGON /RL HIGHEST`
-
-**System service:** `schtasks /Create /TN "Spaces" /TR "..." /SC ONSTART /RU SYSTEM`
-
-**Logs:** Output redirected to `%USERPROFILE%\.spaces\logs\spaces.out.log`.
-
-## Implementation
-
-Single file: `bin/spaces-service.js`. Detects platform via `process.platform` and dispatches to platform-specific functions. Each platform's install/uninstall is ~40-60 lines — small enough for one file.
-
-Routing in `bin/spaces.js` follows the same pattern as `spaces install`:
-
-```js
-if (subcommand === 'service') {
-  const serviceScript = path.join(__dirname, 'spaces-service.js');
-  const { status } = spawnSync(process.execPath, [serviceScript, ...args.slice(1)], {
-    stdio: 'inherit', env: process.env
-  });
-  process.exit(status || 0);
-}
-```
-
-## What's NOT in scope
-
-- No dependency on `node-windows`, `node-mac`, or `node-linux`
-- `uninstall` does not touch `~/.spaces/` data — only removes the service config
-- No Docker/container support (services don't make sense inside containers)

package/.next/standalone/docs/plans/2026-03-07-service-command-plan.md

@@ -1,254 +0,0 @@
-# `spaces service` Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add a `spaces service` subcommand that installs/manages Spaces as a persistent OS service on Linux (systemd), macOS (launchd), and Windows (Task Scheduler).
-
-**Architecture:** Single file `bin/spaces-service.js` dispatched from `bin/spaces.js`. Platform detection via `process.platform` routes to platform-specific install/uninstall/start/stop/status/logs functions. Config is read from `~/.spaces/server.json` and baked into service definitions.
-
-**Tech Stack:** Node.js (no new dependencies). Uses `child_process.execFileSync`/`spawnSync` for service manager commands. `readline` for interactive prompt.
-
-**Design doc:** `docs/plans/2026-03-07-service-command-design.md`
-
----
-
-### Task 1: Route `service` subcommand in `bin/spaces.js`
-
-**Files:**
-- Modify: `bin/spaces.js:29-46` (help text)
-- Modify: `bin/spaces.js:56-65` (subcommand routing)
-
-**Step 1: Add service to help text**
-
-In `bin/spaces.js`, find the help text block and add the service commands. Change:
-
-```js
-    spaces --help                Show this help
-```
-
-to:
-
-```js
-    spaces service install       Install as OS service (systemd/launchd/Task Scheduler)
-    spaces service uninstall     Remove OS service
-    spaces service start         Start the service
-    spaces service stop          Stop the service
-    spaces service status        Show service status
-    spaces service logs          Tail service logs
-    spaces --help                Show this help
-```
-
-**Step 2: Add routing for `service` subcommand**
-
-In `bin/spaces.js`, after the install/uninstall/verify/upgrade routing block (line 57-65), add a new block before the setup wizard section:
-
-```js
-// ─── Route service commands to spaces-service.js ─────
-if (subcommand === 'service') {
-  const serviceScript = path.join(__dirname, 'spaces-service.js');
-  const { status } = require('child_process').spawnSync(
-    process.execPath, [serviceScript, ...args.slice(1)],
-    { stdio: 'inherit', env: process.env }
-  );
-  process.exit(status || 0);
-}
-```
-
-**Step 3: Verify routing works**
-
-Run: `node bin/spaces.js --help`
-Expected: Service commands appear in help output.
-
-Run: `node bin/spaces.js service`
-Expected: Error about missing `spaces-service.js` (we haven't created it yet) or "Unknown command" -- confirms routing is wired.
-
-**Step 4: Commit**
-
-```bash
-git add bin/spaces.js
-git commit -m "Add service subcommand routing and help text"
-```
-
----
-
-### Task 2: Create `bin/spaces-service.js` -- scaffolding, config capture, and prompt
-
-**Files:**
-- Create: `bin/spaces-service.js`
-
-**Step 1: Create the file with shared helpers and CLI dispatch**
-
-Create `bin/spaces-service.js` with:
-- Shared constants: `SPACES_DIR`, `CONFIG_PATH`, `LOGS_DIR`, `SERVICE_NAME` (`spaces`), `LABEL` (`com.agentspaces.spaces`), `TASK_NAME` (`Spaces`)
-- Helper functions: `log()`, `logOk()`, `logErr()` (same pattern as spaces-install.js)
-- `resolveConfig()` -- reads `~/.spaces/server.json`, returns `{ port, tier, basePath, allowedOrigins }` with defaults
-- `resolveSpacesPath()` -- returns `path.join(__dirname, 'spaces.js')`
-- `resolveProjectDir()` -- returns `path.join(__dirname, '..')`
-- `resolveNodePath()` -- returns `process.execPath`
-- `promptLevel()` -- uses readline to ask system vs user, defaults to user (choice 2)
-- `ensureLogsDir()` -- creates `~/.spaces/logs/` via `fs.mkdirSync` with recursive
-- `LEVEL_PATH` (`~/.spaces/service-level`) -- tracks installed level so start/stop/status/logs know which to target
-- `saveLevel(level)` and `loadLevel()` -- write/read the level file
-- `getPlatform()` -- returns `linux`/`darwin`/`win32` or exits with error
-- Dispatch table mapping platform to `{ install, uninstall, start, stop, status, logs }` functions
-- `main()` async function that reads `process.argv[2]` as action, dispatches to platform function
-- Stub function declarations for all 18 platform functions (will be filled in Tasks 3-5)
-
-**Step 2: Verify scaffolding runs**
-
-Run: `node bin/spaces-service.js`
-Expected: Prints usage message and exits cleanly.
-
-**Step 3: Commit**
-
-```bash
-git add bin/spaces-service.js
-git commit -m "Add spaces-service.js scaffolding with config capture and prompt"
-```
-
----
-
-### Task 3: Implement Linux (systemd) functions
-
-**Files:**
-- Modify: `bin/spaces-service.js` (fill in Linux stubs)
-
-**Step 1: Implement all Linux functions**
-
-- `linuxServicePath(level)` -- returns `/etc/systemd/system/spaces.service` for system, `~/.config/systemd/user/spaces.service` for user (creates dir with `mkdirSync` recursive)
-- `linuxUnitFile(level)` -- generates systemd unit file string:
-  - `[Unit]` with `Description` and `After=network.target`
-  - `[Service]` with `Type=simple`, `ExecStart` (node + spaces.js), `WorkingDirectory`, `Environment` lines for port/tier/basePath/allowedOrigins, `Restart=on-failure`, `RestartSec=5`
-  - System level adds `User=` and `Group=` from `os.userInfo().username`
-  - `[Install]` with `WantedBy=multi-user.target` (system) or `default.target` (user)
-- `linuxSystemctl(level, ...args)` -- runs `sudo systemctl ...args` for system, `systemctl --user ...args` for user, via `execFileSync` with `stdio: 'inherit'`
-- `linuxInstall()` -- prompts level, writes unit file (via `sudo tee` for system, `fs.writeFileSync` for user), saves level, runs daemon-reload + enable + start. For user level, also runs `loginctl enable-linger` so service survives logout.
-- `linuxUninstall()` -- loads saved level, stops + disables + removes unit file + daemon-reload + removes level file
-- `linuxStart()` / `linuxStop()` -- loads level, runs systemctl start/stop
-- `linuxStatus()` -- loads level, runs systemctl status (catches non-zero exit from stopped services)
-- `linuxLogs()` -- loads level, runs `journalctl -u spaces -f --no-pager` (with `--user` for user level, `sudo` for system level) via `spawnSync` with `stdio: 'inherit'`
-
-All service manager calls use `execFileSync` (not `exec`) to prevent shell injection.
-
-**Step 2: Test on this Linux machine**
-
-Run: `node bin/spaces-service.js install` (choose user)
-Then: `node bin/spaces-service.js status`
-Then: `node bin/spaces-service.js uninstall`
-
-**Step 3: Commit**
-
-```bash
-git add bin/spaces-service.js
-git commit -m "Implement Linux systemd service management"
-```
-
----
-
-### Task 4: Implement macOS (launchd) functions
-
-**Files:**
-- Modify: `bin/spaces-service.js` (fill in macOS stubs)
-
-**Step 1: Implement all macOS functions**
-
-- `darwinPlistPath(level)` -- returns `/Library/LaunchDaemons/com.agentspaces.spaces.plist` for system, `~/Library/LaunchAgents/com.agentspaces.spaces.plist` for user
-- `darwinPlistContent(level)` -- generates XML plist string with:
-  - `Label`: `com.agentspaces.spaces`
-  - `ProgramArguments`: array with node path and spaces.js path
-  - `WorkingDirectory`: project dir
-  - `EnvironmentVariables`: dict with port, tier, basePath (if set), allowedOrigins (if set)
-  - `RunAtLoad`: true, `KeepAlive`: true
-  - `StandardOutPath` / `StandardErrorPath`: `~/.spaces/logs/spaces.out.log` and `.err.log`
-  - System level adds `UserName` key
-- `darwinInstall()` -- prompts level, unloads existing if present, writes plist (via `sudo tee` + `chown root:wheel` + `chmod 644` for system, `fs.writeFileSync` for user), saves level, loads with `launchctl load -w`
-- `darwinUninstall()` -- loads level, runs `launchctl unload -w`, deletes plist file, removes level file
-- `darwinStart()` / `darwinStop()` -- loads level, runs `launchctl load -w` / `launchctl unload -w`
-- `darwinStatus()` -- runs `launchctl list`, filters output for the label
-- `darwinLogs()` -- runs `tail -f ~/.spaces/logs/spaces.out.log` via `spawnSync`
-
-**Step 2: Commit**
-
-```bash
-git add bin/spaces-service.js
-git commit -m "Implement macOS launchd service management"
-```
-
----
-
-### Task 5: Implement Windows (Task Scheduler) functions
-
-**Files:**
-- Modify: `bin/spaces-service.js` (fill in Windows stubs)
-
-**Step 1: Implement all Windows functions**
-
-- `win32WrapperScript()` -- writes a `.cmd` file to `~/.spaces/spaces-service.cmd` that sets environment variables and runs `node spaces.js` with stdout/stderr redirected to log files. Returns the wrapper path. This is needed because `schtasks /TR` doesn't handle multi-arg commands or env vars well.
-- `win32Install()` -- prompts level, generates wrapper script, deletes existing task (`schtasks /Delete /TN Spaces /F`), creates task with `/SC ONLOGON /RL HIGHEST` (user) or `/SC ONSTART /RU SYSTEM` (system), saves level, starts immediately with `/Run`
-- `win32Uninstall()` -- ends task (`/End`), deletes task (`/Delete /F`), removes wrapper script and level file
-- `win32Start()` / `win32Stop()` -- runs `schtasks /Run` / `schtasks /End`
-- `win32Status()` -- runs `schtasks /Query /TN Spaces /V /FO LIST`
-- `win32Logs()` -- runs `powershell -Command "Get-Content path -Wait -Tail 50"` via `spawnSync`
-
-All `schtasks` calls use `execFileSync` with array args (no shell).
-
-**Step 2: Commit**
-
-```bash
-git add bin/spaces-service.js
-git commit -m "Implement Windows Task Scheduler service management"
-```
-
----
-
-### Task 6: Update documentation
-
-**Files:**
-- Modify: `docs/server-install.md`
-
-**Step 1: Add "Running as a Service" section**
-
-After the "CLI Reference" section (~line 295), add a new section covering:
-- `spaces service install` with explanation of the system/user prompt
-- Table of all service subcommands (status, stop, start, logs, uninstall)
-- Note about re-running install after config changes
-- Platform details table (Linux/macOS/Windows with paths for user and system level)
-- Logs info (journalctl for Linux, file-based for macOS/Windows)
-
-**Step 2: Update CLI Reference**
-
-Add `spaces service <action>` line to the existing CLI Reference block.
-
-**Step 3: Commit**
-
-```bash
-git add docs/server-install.md
-git commit -m "Add service management docs to server-install.md"
-```
-
----
-
-### Task 7: End-to-end test on Linux
-
-**Step 1: Test full lifecycle**
-
-```bash
-node bin/spaces.js service install    # choose user
-node bin/spaces.js service status     # should show active
-node bin/spaces.js service logs       # Ctrl+C after seeing output
-node bin/spaces.js service stop       # should stop
-node bin/spaces.js service status     # should show inactive
-node bin/spaces.js service start      # should restart
-node bin/spaces.js service uninstall  # should clean up
-```
-
-**Step 2: Verify cleanup**
-
-Confirm no leftover files at `~/.config/systemd/user/spaces.service` or `~/.spaces/service-level`.
-
-**Step 3: Commit any fixes**
-
-```bash
-git add -A
-git commit -m "Fix issues found during service e2e testing"
-```

package/.next/standalone/docs/plans/2026-04-23-consolidate-addons-design.md

@@ -1,212 +0,0 @@
-# Consolidating Spaces Addons — Design
-
-**Status:** proposed
-**Author:** jlongo78 (with Claude)
-**Date:** 2026-04-23
-**Paired plan:** `docs/plans/2026-04-23-consolidate-addons-plan.md`
-
-## Problem
-
-Spaces currently ships as an open-source core (`@jlongo78/agent-spaces`, AGPL-3.0) with three optional addons loaded at runtime via `createRequire`:
-
-- `@spaces/pro` — federation/network (private)
-- `@spaces/teams` — auth, admin, collaboration bus, MCP server (private)
-- `@spaces/cortex` — RAG knowledge engine (separate repo, heavier product)
-
-The addon architecture exists to gate features behind tiers (`community | team | federation`). In practice:
-
-- The tier/install machinery is a persistent source of setup friction (`bin/spaces-install.js`, NODE_PATH resolution in `bin/spaces.js:309-349`, `@spaces/teams` peer-dep dance, `createRequire` anchor files).
-- We are not monetizing Spaces and have no near-term plans to. The tier abstraction pays no dividend.
-- ~30 Next.js route handlers are thin proxies (`pro?.network.api.X.Y(req) ?? notAvailable()`) whose only purpose is to handle the absent-addon case.
-- The two stub shims (`src/lib/pro.ts`, `src/lib/teams.ts`) add cognitive load for anyone reading the auth/federation code.
-
-## Goals
-
-1. Fold `@spaces/pro` source into `spaces/src/lib/network/`.
-2. Fold `@spaces/teams` source into `spaces/src/lib/{auth,admin,collab}/` and `spaces/bin/`.
-3. Delete the `createRequire` stub layer, the tier install workflow, and the `@spaces/*` NODE_PATH resolution in the launcher.
-4. Preserve current behavior for existing installs (desktop users stay logged out by default; server operators still gate with auth + admin DB).
-5. Keep `@spaces/cortex` as an external optional addon — unchanged.
-
-## Non-goals
-
-- No conversion of `.js` files to TypeScript during the move. Defer TS conversion of `bus/broker.js`, `db/queries.js`, `db/migrations.js`, and collab route handlers to a follow-up.
-- No changes to cortex, to the `src/lib/cortex/*` stub layer, or to the `@spaces/cortex` package.
-- No rewrite of auth UX, session format, or TOTP flow. Same wire format, same DB schema.
-- No changes to the federation protocol or `/api/network/*` contract. Same wire format.
-
-## Current architecture
-
-```
-spaces/
-├── src/
-│   ├── middleware.ts                 ← auth gate keyed off HAS_AUTH (from tier.ts)
-│   ├── lib/
-│   │   ├── auth.ts                   ← getAuthUser/withUser (AsyncLocalStorage)
-│   │   ├── tier.ts                   ← TIER/HAS_AUTH/HAS_NETWORK/IS_DESKTOP flags
-│   │   ├── pro.ts                    ← createRequire shim → @spaces/pro
-│   │   ├── teams.ts                  ← createRequire shim → @spaces/teams
-│   │   └── config.ts                 ← calls getTeams() for shell-user resolution
-│   └── app/api/
-│       ├── admin/*/route.ts          ← thin proxy → teams.admin.api.X.Y(req)
-│       ├── auth/*/route.ts           ← thin proxy → teams.auth.api.X.Y(req)
-│       ├── network/*/route.ts        ← thin proxy → pro.network.api.X.Y(req)
-│       └── workspaces/[id]/
-│           ├── messages/*/route.ts   ← thin proxy → teams.api.messages.X(req)
-│           └── context/*/route.ts    ← thin proxy → teams.api.context.X(req)
-└── bin/
-    ├── spaces.js                     ← lines 242-360: tier detect, NODE_PATH, addon probe
-    ├── spaces-install.js             ← install/remove @spaces/{pro,teams,cortex}
-    └── lib/auto-setup.js             ← session secret + admin.db bootstrap
-
-spaces-pro/                            ← private, 27 src files, network-only
-└── src/network/                      ← identity, auth, db, client, aggregator + 18 API handlers
-
-spaces-teams/                          ← private, 18 TS + 9 JS files under src/
-└── src/
-    ├── auth/{session,totp}.ts + api/{login,logout,me,totpSetup,totpStatus,totpVerify}.ts
-    ├── admin/{db.ts,index.ts} + api/{analytics,users,usersById}.ts
-    ├── bus/broker.js
-    ├── db/{migrations,queries}.js
-    ├── api/{messages,messageById,context,contextByKey}.js   ← collab route handlers
-    ├── terminal/collaboration.js
-    ├── init.js
-    └── middleware.ts                 ← stale; spaces/src/middleware.ts is canonical
-bin/
-    ├── spaces-msg.js                 ← CLI: post messages from a pane
-    ├── mcp-server.js                 ← MCP server for agent→workspace messaging
-    └── spaces-hook.js                ← Claude Code hook
-```
-
-## Target architecture
-
-```
-spaces/
-├── src/
-│   ├── middleware.ts                 ← keyed off IS_MULTIUSER (renamed from HAS_AUTH)
-│   ├── lib/
-│   │   ├── auth/                     ← folder, preserves @/lib/auth imports
-│   │   │   ├── index.ts              ← re-exports: getAuthUser, withUser, session, totp
-│   │   │   ├── context.ts            ← getAuthUser, withUser (from current auth.ts)
-│   │   │   ├── session.ts            ← from spaces-teams/src/auth/session.ts
-│   │   │   └── totp.ts               ← from spaces-teams/src/auth/totp.ts
-│   │   ├── admin/
-│   │   │   ├── index.ts              ← from spaces-teams/src/admin/index.ts
-│   │   │   └── db.ts                 ← from spaces-teams/src/admin/db.ts
-│   │   ├── collab/
-│   │   │   ├── broker.js             ← from spaces-teams/src/bus/broker.js (unchanged)
-│   │   │   ├── queries.js            ← from spaces-teams/src/db/queries.js
-│   │   │   └── migrations.js         ← from spaces-teams/src/db/migrations.js
-│   │   ├── network/                  ← from spaces-pro/src/network/ (whole dir)
-│   │   │   ├── index.ts, identity.ts, auth.ts, db.ts, client.ts, aggregator.ts
-│   │   │   └── api/ …                ← the 18 API handler modules
-│   │   ├── terminal/
-│   │   │   └── collaboration.js      ← from spaces-teams/src/terminal/collaboration.js
-│   │   ├── flags.ts                  ← replaces tier.ts: single IS_MULTIUSER flag
-│   │   ├── config.ts                 ← imports resolveShellUser from @/lib/admin
-│   │   └── pro.ts, teams.ts          ← DELETED
-│   └── app/api/
-│       ├── admin/*/route.ts          ← calls @/lib/admin directly (no proxy)
-│       ├── auth/*/route.ts           ← calls @/lib/auth directly
-│       ├── network/*/route.ts        ← calls @/lib/network directly
-│       └── workspaces/[id]/
-│           ├── messages/*/route.ts   ← calls @/lib/collab directly
-│           └── context/*/route.ts    ← calls @/lib/collab directly
-└── bin/
-    ├── spaces.js                     ← tier block deleted; always sets up secret + admin.db
-    ├── spaces-install.js             ← install/remove of @spaces/cortex only
-    ├── spaces-msg.js                 ← from spaces-teams/bin/spaces-msg.js
-    ├── spaces-mcp.js                 ← from spaces-teams/bin/mcp-server.js
-    ├── spaces-hook.js                ← from spaces-teams/bin/spaces-hook.js
-    └── lib/auto-setup.js             ← runs unconditionally now
-
-~/archive/
-├── spaces-pro/                       ← moved out of active dev tree
-└── spaces-teams/
-```
-
-## Design decisions
-
-### D1 — Desktop-vs-server flag
-
-**Problem:** Today `HAS_AUTH` is derived from `TIER`. Folding teams in removes the tier concept but we still need the middleware to skip login for solo desktop users.
-
-**Decision:** Replace `tier.ts` with `flags.ts` exposing a single `IS_MULTIUSER` flag (default `false`). The launcher (`bin/spaces.js`) leaves it unset for the desktop npm install; a server operator sets `SPACES_MULTIUSER=1` (or equivalent CLI flag) to enable login + admin UI.
-
-**Federation is always on.** The network/federation routes (`/api/network/*`) are live regardless of mode — with no peer nodes configured, list endpoints just return empty arrays. There is no flag gate and no `IS_FEDERATION` constant. Rationale: the routes are harmless without configured nodes, and adding a gate adds friction for solo users who want to pair a second node later.
-
-**Future (not in this plan):** eventually drop `SPACES_MULTIUSER` entirely and auto-detect multiuser mode from the presence of users in `admin.db`. Requires a different startup flow that bootstraps `admin.db` on first launch; deferred.
-
-**Rationale:** Inverts current `HAS_AUTH` without changing the wire format of sessions, cookies, or APIs. One knob, one behavior.
-
-**Impact on `middleware.ts`:**
-```ts
-// before
-import { HAS_AUTH } from '@/lib/tier';
-if (!HAS_AUTH) return NextResponse.next();
-
-// after
-import { IS_MULTIUSER } from '@/lib/flags';
-if (!IS_MULTIUSER) return NextResponse.next();
-```
-
-### D2 — Auth folder layout
-
-**Problem:** `src/lib/auth.ts` already exists in spaces and is imported by ~25 files as `@/lib/auth`. It exports `getAuthUser`/`withUser`. Teams' auth code exports `issueSessionToken`/`verifySessionToken`/`setSessionCookie`/TOTP helpers.
-
-**Decision:** Convert `src/lib/auth.ts` → `src/lib/auth/context.ts`, create `src/lib/auth/index.ts` that re-exports from `context.ts` + `session.ts` + `totp.ts`. Existing `from '@/lib/auth'` imports continue to resolve to the folder's index.ts — zero churn for consumers.
-
-### D3 — Admin DB stays separate
-
-**Problem:** Teams writes to `~/.spaces/admin.db`; spaces writes per-workspace to `~/.spaces/spaces.db` (or per-user). Should we merge?
-
-**Decision:** Keep them separate. Admin DB is operator/account data (users, login events, session telemetry). Spaces DB is app data (workspaces, messages, context). Different lifecycle, different backup semantics. Merging would force a schema migration for existing installs with zero upside.
-
-### D4 — `.js` files move as-is
-
-**Problem:** Teams ships 9 JavaScript files (`bus/broker.js`, `db/{queries,migrations}.js`, `api/*.js`, `terminal/collaboration.js`) that could be converted to TS during the move.
-
-**Decision:** Move as-is. Next.js build accepts `.js` and `.ts` side-by-side. Converting to TS during a move multiplies risk (move + type-fix in the same commit) and triggers a pile of type errors to triage. A follow-up plan can do the TS conversion module-by-module on a quiet week.
-
-### D5 — Binary names
-
-**Problem:** Teams exposes `spaces-msg` as a bin; `mcp-server.js` and `spaces-hook.js` are invoked via absolute path by agent configs. What do we publish from the combined package?
-
-**Decision:**
-- Expose `spaces-msg` as a bin in `package.json` (CLI users rely on it).
-- Move `mcp-server.js` → `bin/spaces-mcp.js` (no bin entry; invoked via absolute path from MCP server configs that point at the file).
-- Move `spaces-hook.js` → `bin/spaces-hook.js` (no bin entry; invoked via absolute path by Claude Code hook config).
-
-### D6 — Cortex unchanged
-
-The `src/lib/cortex/*` stub layer, the `@spaces/cortex` runtime loader, and the separate `spaces-cortex` / `spaces-cortex-gravity` repos all stay as-is. Cortex is excluded because:
-- Install size: `@huggingface/transformers` + `@lancedb/lancedb` + `pdf-parse` push install footprint beyond what a baseline workspace manager should demand.
-- Active divergence: `spaces-cortex-gravity` is a parallel line of development, suggesting cortex will keep evolving independently.
-
-### D7 — `src/lib/config.ts#getUserPaths` shell-user resolution
-
-**Problem:** `getUserPaths` calls `getTeams()?.admin.resolveShellUser(username)` under `HAS_MULTIUSER`. After fold-in, `resolveShellUser` lives at `@/lib/admin`.
-
-**Decision:** Replace the `getTeams()?.admin.resolveShellUser(...)` call with a direct `import { resolveShellUser } from '@/lib/admin'` gated on `IS_MULTIUSER`.
-
-## Phases
-
-1. **A — Pro fold-in.** Lowest blast radius (federation is opt-in; breaking `/api/network/*` doesn't affect local workflow).
-2. **B — Teams fold-in.** Higher risk; touches auth, middleware, config, bus.
-3. **C — Flag + launcher simplification.** Renames `tier.ts` → `flags.ts`, cuts ~100 lines from `bin/spaces.js`.
-4. **D — Deps, docs, archive.** Add npm deps, update README, move `spaces-pro`/`spaces-teams` to `~/archive/`.
-5. **E — Smoke verification.** Run the app locally in both desktop and multiuser modes; exercise representative routes.
-
-## Risks
-
-| Risk | Mitigation |
-|---|---|
-| Existing server installs break when they `npm i -g @jlongo78/agent-spaces@0.10` because their `admin.db` schema or session format diverges | Keep admin DB path (`~/.spaces/admin.db`) and schema identical to teams package. Session token format is already identical (verified in design). |
-| Hooks configured to absolute path `node_modules/@spaces/teams/bin/spaces-hook.js` stop working | Keep the teams package published for one more release cycle as a compatibility shim that just requires the new bin path. (Out of scope for this plan — only affects third-party consumers, of which there are none.) |
-| `@spaces/teams` is imported from somewhere we missed | `grep -rE "@spaces/(pro\|teams)"` after each phase; CI build surfaces unresolved imports. |
-| Folder rename `src/lib/auth.ts` → `src/lib/auth/` breaks partial-path imports | TS path `@/lib/auth` resolves to `src/lib/auth/index.ts` — same import specifier. Verified no deep imports (`@/lib/auth/...`) exist. |
-
-## Open questions
-
-- Should we publish `0.10.0` as a breaking release, or continue the `0.9.x` line with a note in the changelog? **Leaning breaking.**
-- After fold-in, do we delete `spaces-pro`/`spaces-teams` from GitHub or archive the repos? **Archive, don't delete — git history matters.**