totopo 1.0.8 → 2.0.0-rc-1

package/README.md

@@ -10,7 +10,7 @@ A simple CLI to use AI coding agents safely in your local codebase.
 
 ## Why totopo?
 
-Here's the thing about AI agents: they're probabilistic. They occasionally misinterpret instructions, take unexpected shortcuts, or simply get it wrong. Most of the time they're fine. But "most of the time" isn't a great argument for giving them unrestricted access to your machine, your credentials, and your remote repositories.
+Here's the thing about AI agents: they're probabilistic. They occasionally misinterpret instructions or simply get it wrong. Most of the time they're fine. But "most of the time" isn't a great argument for giving them unrestricted access to your machine, your credentials, and your remote repositories.
 
 totopo draws a simple boundary: agents get a full, capable environment to work in — they just can't touch anything outside the project, and they can't reach your remote. That's it. No domain whitelisting, no paranoia, no compromise on what the agent can actually do. Just a reasonable containment for non-deterministic tools.
 
@@ -18,21 +18,23 @@ Note: no sandbox substitutes for good judgment. Consider keeping any sensitive s
 
 ## How totopo Works
 
-- Unified, simple DX: run `npx totopo` from anywhere inside a local git repo.
-- Installed once per git repository in a `.totopo/` directory at the repo root.
-- Manages one Docker container per repository.
+totopo organises work around **projects** — any local directory you register with totopo. The first time you run `npx totopo` in a directory, it walks you through a short setup. Every subsequent run, from anywhere inside that directory tree, totopo resolves the project automatically and shows the project menu:
 
-To start a development session, run `npx totopo`, choose `Open session` and confirm the desired scope: the full repo, the current directory, or selected files and folders.
+- **Open session** — choose a scope and jump into an AI coding session
+- **Stop container** — stop the running container
+- **Runtime Mode** — adjust runtime mode and installed tools
+- **Rebuild container** — rebuild the docker image (upon changing runtime mode)
+
+All config lives in `~/.totopo/` — nothing is written to your project by default.
 
 ### Concurrent Sessions
-totopo uses one container per repository (not per session). This keeps resource usage bounded and makes reconnections fast - you can open as many sessions as you need — they all share the same running container.
+totopo uses one Docker container per project, not one per session. You can open as many terminal sessions as you need — they all connect to the same container, keeping resource usage bounded and reconnections fast.
 
 The tradeoff is that only one scope can be active at a time: if you reopen a session with a different scope, totopo recreates the container to match the new mounts, which would terminate any active sessions connected to the previous container.
 
 ## Requirements
 
-- [Docker](https://www.docker.com/products/docker-desktop/) - used to build and run the dev container
-- [git](https://git-scm.com/) - safeguard to ensure agents only run in projects with version control in place
+- [Docker](https://www.docker.com/products/docker-desktop/) — used to build and run the dev container
 
 ## Quick Start
 
@@ -41,11 +43,11 @@ cd your-project
 npx totopo
 ```
 
-First-time setup — running `npx totopo` in a fresh repo, selecting a runtime mode, and waiting for the Docker image to build for the first time:
-![First-time setup](.github/assets/demo-onboarding.gif)
+<!--First-time setup — running `npx totopo` in a fresh repo, selecting a runtime mode, and waiting for the Docker image to build for the first time:-->
+<!-- ![First-time setup](.github/assets/demo-onboarding.gif) -->
 
-Opening a session when totopo is already initialized is quick. The agent is aware of its scope and sandbox constraints:
-![Quick start](.github/assets/demo-quickstart.gif)
+<!--Opening a session when totopo is already initialized is quick. The agent is aware of its scope and sandbox constraints:-->
+<!-- ![Quick start](.github/assets/demo-quickstart.gif) -->
 
 ## Core features at a glance
 
@@ -75,9 +77,9 @@ Remote git operations are blocked inside the container. Push from your host term
 
 ### Session scope
 
-When you open a session, totopo asks what part of the repository to mount into the container:
+When you open a session, totopo asks what part of the project to mount into the container:
 
-- `Repo root` — the full repository
+- `Repo root` — the full project directory
 - `Current directory` — only the current directory
 - `Selective` — specific files and folders chosen interactively
 
@@ -87,14 +89,14 @@ The selected scope is stored on the container and checked on every later `Open s
 - If the requested scope is different, totopo recreates the container so the mounted paths match the new scope.
 - Parallel terminals on the same scope are fine. totopo connects with `docker exec`, so any concurrency limits are just the normal limits of sharing one running container.
 
-This is an intentional tradeoff: you get predictable resource usage and quick reconnects, but only one active mounted view per repository at a time.
+This is an intentional tradeoff: you get predictable resource usage and quick reconnects, but only one active mounted view per project at a time.
 
 In `Current directory` and `Selective` scopes, `.git` is intentionally not mounted. Mounting `.git` would expose the full commit history of every repository file, including files outside the mounted paths, which defeats the point of scoped access. As a result, git is unavailable inside those scoped sessions and the agent operates without repository history. The agent is instructed to surface these limitations at session start.
 
 Scoped sessions are well-suited for focused tasks where you want to give the agent a narrow, explicit view of your codebase.
 
-Example showcasing agent awareness of selective scope limitations:
-![Scoped access](.github/assets/demo-scoped.gif)
+<!-- Example showcasing agent awareness of selective scope limitations:-->
+<!-- ![Scoped access](.github/assets/demo-scoped.gif) -->
 
 ### AI CLIs with persistent sessions
 
@@ -106,7 +108,7 @@ claude      # Claude Code (Anthropic)
 codex       # Codex (OpenAI)
 ```
 
-Agent session data is isolated per repository, so agents do not bleed context between projects. To clear memory, run `npx totopo` and navigate to `Advanced > Clear agent memory`. This stops the container if running and removes the `.totopo/agents/` directory.
+Agent session data is isolated per project, so agents do not bleed context between projects. To clear memory, run `npx totopo` and navigate to `Manage totopo > Clear agent memory` and select a project. This stops the container if running and removes the agents directory.
 
 ### Dev container runtime
 
@@ -117,27 +119,51 @@ Choose between two modes:
 
 Either way, basic dev tools and all three AI CLIs are always included.
 
-## What gets created in your project
+## What gets installed
+
+All totopo config lives in `~/.totopo/` on your machine — nothing is written to your project directory unless you opt in.
 
 ```text
-your-project/
-└── .totopo/
-    ├── Dockerfile        # container image definition
-    ├── post-start.mjs    # security checks + readiness summary on every start
-    ├── settings.json     # runtime mode + selected tools (committed with project)
-    ├── README.md         # .totopo reference
-    └── agents/           # agent session data — gitignored, created on first session start
-        ├── claude/       # mounted as ~/.claude/
-        ├── opencode/     # mounted as ~/.config/opencode/ + ~/.local/share/opencode/
-        └── codex/        # mounted as ~/.codex/
-
-~/.totopo/.env            # API keys — global, outside all repos, never mounted into container
+~/.totopo/
+├── .env                        # API keys — global, never mounted into container
+└── projects/
+    └── <id>/                   # stable hash of the project root path
+        ├── meta.json           # project root, display name, container name
+        ├── settings.json       # runtime mode + selected tools
+        ├── Dockerfile          # container image definition
+        ├── post-start.mjs      # security checks + readiness summary on every start
+        └── agents/             # agent session data — created on first session start
+            ├── claude/         # mounted as ~/.claude/
+            ├── opencode/       # mounted as ~/.config/opencode/ + ~/.local/share/opencode/
+            └── codex/          # mounted as ~/.codex/
 ```
 
-totopo is initialized at the repository root, and `.totopo/` lives there regardless of which directory you later open a session from. Agent session history and conversation data are persisted in `.totopo/agents/` across container rebuilds and restarts. This directory is gitignored so session data stays local to your machine.
+Agent session history and conversation data are persisted in the `agents/` directory across container rebuilds and restarts.
+
+### Shared onboarding (optional)
+
+If you want contributors to get a one-click setup experience, add a `totopo.yaml` file at your project root:
+
+```yaml
+# totopo.yaml — project anchor
+#
+# name        — shown as: "Welcome to <name>."
+# description — shown as: "<description>"
+
+name: my-project
+description: Our AI coding sandbox. Ask @alice for the API keys.
+```
+
+When a new contributor runs `npx totopo`, totopo reads this file to anchor the project root and displays the welcome message before prompting for setup. Without it, totopo will find the git root and suggest it as the project root, so `totopo.yaml` is purely optional.
+
+To add a project anchor to an existing local-only totopo project, run `npx totopo` and select `Add project anchor` from the project menu.
 
 ## Limitations
 
+**Rename or move** — moving the project directory breaks identity since totopo uses the absolute path as the project key. Re-run `npx totopo` in the new location to onboard again. Orphaned configs can be cleaned up via `Manage totopo`.
+
+**Single machine** — `~/.totopo/` is local. Switching to a new machine requires re-onboarding each project.
+
 **Audio / microphone** — the image includes `sox` (required by Claude Code for voice mode), but audio passthrough from the host depends on your OS. macOS, Linux, and Windows each require different device configuration. If you need voice mode, set up audio passthrough manually for your platform.
 
 ## Disclaimer

package/bin/totopo.js

@@ -1,21 +1,24 @@
 #!/usr/bin/env node
 // =============================================================================
-// bin/totopo.js — totopo entry point
+// bin/totopo.js — totopo entry point (v2)
 // Run this from your project directory (or via npx totopo).
 // =============================================================================
 
 import { execSync, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { basename, dirname } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { cancel, isCancel, select } from "@clack/prompts";
 import { run as advanced } from "../dist/commands/advanced.js";
 import { run as dev } from "../dist/commands/dev.js";
 import { run as doctor } from "../dist/commands/doctor.js";
 import { run as menu } from "../dist/commands/menu.js";
-import { run as onboard } from "../dist/commands/onboard.js";
+import { addProjectAnchor, run as onboard } from "../dist/commands/onboard.js";
+import { run as rebuild } from "../dist/commands/rebuild.js";
+import { run as settings } from "../dist/commands/settings.js";
 import { run as stop } from "../dist/commands/stop.js";
 import { run as syncDockerfile } from "../dist/commands/sync-dockerfile.js";
-import { toDockerName } from "../dist/lib/docker-name.js";
+import { listProjectIds, resolveProject } from "../dist/lib/project-identity.js";
 
 // ─── Guard: inside container ──────────────────────────────────────────────────
 try {
@@ -35,18 +38,7 @@ try {
 // ─── Paths ────────────────────────────────────────────────────────────────────
 // dirname(dirname(...)) walks up from bin/ to the package root.
 const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
-
-let repoRoot;
-try {
-    repoRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf8" }).trim();
-} catch {
-    console.error("");
-    console.error("  No git repository found.");
-    console.error("");
-    console.error("  totopo requires a git repository. Run 'git init' first, then re-run totopo.");
-    console.error("");
-    process.exit(1);
-}
+const cwd = process.cwd();
 
 // ─── Guard: dist/ must exist ─────────────────────────────────────────────────
 if (!existsSync(new URL("../dist/commands/sync-dockerfile.js", import.meta.url))) {
@@ -58,59 +50,106 @@ if (!existsSync(new URL("../dist/commands/sync-dockerfile.js", import.meta.url))
     process.exit(1);
 }
 
-// ─── Onboarding ───────────────────────────────────────────────────────────────
-if (!existsSync(`${repoRoot}/.totopo/Dockerfile`)) {
-    const completed = await onboard(packageDir, repoRoot);
-    if (!completed) process.exit(0);
+// ─── Resolve project from CWD (walk-up through ~/.totopo/projects/) ───────────
+let project = resolveProject(cwd);
+
+// ─── Onboarding (if not in a registered project) ─────────────────────────────
+if (!project) {
+    // Detect project context: git root or totopo.yaml present?
+    let gitRoot = null;
+    try {
+        gitRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+        // Not in a git repo — that's fine
+    }
+
+    const totopoJsonPath = `${gitRoot ?? cwd}/totopo.yaml`;
+    const hasTotopoYaml = existsSync(totopoJsonPath);
+
+    if (gitRoot !== null || hasTotopoYaml) {
+        // Has project context — if other projects already exist, let the user choose first
+        if (listProjectIds().length > 0) {
+            process.stdout.write("\n");
+            const choice = await select({
+                message: "What would you like to do?",
+                options: [
+                    { value: "setup", label: "Set up totopo for this directory" },
+                    { value: "manage", label: "Manage totopo →" },
+                ],
+            });
+            if (isCancel(choice)) {
+                cancel();
+                process.exit(0);
+            }
+            if (choice === "manage") {
+                await advanced(packageDir);
+                process.exit(0);
+            }
+        }
+
+        const ctx = await onboard(packageDir, cwd);
+        if (!ctx) process.exit(0); // cancelled → exit cleanly
+        project = ctx;
+    } else {
+        // No project context → show Manage totopo menu directly
+        await advanced(packageDir);
+        process.exit(0);
+    }
 }
 
 // ─── Sync Dockerfile with host runtimes ───────────────────────────────────────
-await syncDockerfile(packageDir, repoRoot);
+await syncDockerfile(packageDir, project);
 
 // ─── Doctor (silent pre-check) ────────────────────────────────────────────────
-const doctorResult = await doctor(repoRoot, false);
+const doctorResult = await doctor(project.projectDir, false);
 if (!doctorResult.ok) {
     console.error("  Fix the issues above and re-run totopo.");
     console.error("");
     process.exit(1);
 }
 
-// ─── Gather state for menu ────────────────────────────────────────────────────
-const projectName = basename(repoRoot);
-const dockerName = toDockerName(projectName);
+// ─── Gather container state for menu ─────────────────────────────────────────
+const { containerName } = project.meta;
 
-const dockerResult = spawnSync("docker", ["ps", "--filter", "name=totopo-managed-", "--format", "{{.Names}}"], {
+const dockerResult = spawnSync("docker", ["ps", "--filter", "name=totopo-", "--format", "{{.Names}}"], {
     encoding: "utf8",
 });
-const activeCount = dockerResult.stdout ? dockerResult.stdout.trim().split("\n").filter(Boolean).length : 0;
-
-const projectContainerResult = spawnSync("docker", ["ps", "--filter", `name=${dockerName}`, "--format", "{{.Names}}"], {
-    encoding: "utf8",
-});
-const projectRunning = (projectContainerResult.stdout ?? "")
-    .trim()
-    .split("\n")
-    .filter(Boolean)
-    .some((n) => n === dockerName);
+const activeNames = dockerResult.stdout ? dockerResult.stdout.trim().split("\n").filter(Boolean) : [];
+const activeCount = activeNames.length;
+const projectRunning = activeNames.some((n) => n === containerName);
 
 // ─── Interactive menu loop ────────────────────────────────────────────────────
 let showMenu = true;
 while (showMenu) {
     showMenu = false;
 
-    const action = await menu({ projectName, activeCount, projectRunning });
+    // Re-evaluated each iteration so menu options stay in sync (e.g. after "Add project anchor")
+    const hasTotopoYaml = existsSync(`${project.meta.projectRoot}/totopo.yaml`);
+
+    const action = await menu({ ctx: project, activeCount, projectRunning, hasTotopoYaml });
 
     switch (action) {
         case "dev":
-            await dev(packageDir, repoRoot);
+            await dev(packageDir, project);
+            break;
+        case "rebuild":
+            await rebuild(project.meta.containerName);
+            await dev(packageDir, project);
             break;
         case "stop":
-            await stop(projectName);
+            await stop(project.meta.containerName);
+            break;
+        case "settings":
+            await settings(packageDir, project);
+            showMenu = true;
+            break;
+        case "add-anchor":
+            await addProjectAnchor(project);
+            showMenu = true;
             break;
-        case "advanced": {
-            const result = await advanced(packageDir, projectName, repoRoot);
+        case "manage-totopo": {
+            const result = await advanced(packageDir);
             if (result === "back") showMenu = true;
-            if (result === "rebuild") await dev(packageDir, repoRoot);
             break;
         }
         default:

package/dist/commands/advanced.js

@@ -1,50 +1,22 @@
 // =========================================================================================================================================
-// src/core/commands/advanced.ts — Advanced submenu
-// Invoked by bin/totopo.js — do not run directly.
+// src/core/commands/advanced.ts — Manage totopo menu (global, all projects)
+// Invoked by bin/totopo.js — shown directly when outside a project, or via "Manage totopo →" from the project menu.
 // =========================================================================================================================================
 import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { cancel, confirm, isCancel, log, multiselect, outro, select } from "@clack/prompts";
-import { toDockerName } from "../lib/docker-name.js";
+import { cancel, confirm, isCancel, log, multiselect, outro, select, text } from "@clack/prompts";
+import { listProjects } from "../lib/project-identity.js";
 import { run as runDoctor } from "./doctor.js";
-import { run as runRebuild } from "./rebuild.js";
-import { run as runSettings } from "./settings.js";
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function stopAndRemoveContainer(name) {
     spawnSync("docker", ["stop", name], { stdio: "inherit" });
     spawnSync("docker", ["rm", name], { stdio: "inherit" });
 }
-// ─── Clear agent memory ───────────────────────────────────────────────────────
-async function clearAgentMemory(projectName, totopoDir) {
-    const containerName = toDockerName(projectName);
-    // Check if the container is running
-    const inspectResult = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", containerName], {
-        encoding: "utf8",
-        stdio: "pipe",
-    });
-    const isRunning = inspectResult.status === 0 && inspectResult.stdout.trim() === "running";
-    if (isRunning) {
-        const confirmed = await confirm({
-            message: `The dev container for ${projectName} is running. It must be stopped to clear agent memory. Continue?`,
-        });
-        if (isCancel(confirmed) || !confirmed) {
-            cancel("Cancelled.");
-            return;
-        }
-        log.step(`Stopping ${containerName}...`);
-        stopAndRemoveContainer(containerName);
-    }
-    const agentsDir = join(totopoDir, "agents");
-    if (existsSync(agentsDir)) {
-        rmSync(agentsDir, { recursive: true, force: true });
-    }
-    log.success("Agent memory cleared. Context will be regenerated on next session start.");
-}
-// ─── Stop containers ──────────────────────────────────────────────────────────
+// ─── Stop containers (multi-select across all projects) ──────────────────────
 async function stopContainers() {
-    const listResult = spawnSync("docker", ["ps", "--filter", "name=totopo-managed-", "--format", "{{.Names}}"], {
+    const listResult = spawnSync("docker", ["ps", "--filter", "name=totopo-", "--format", "{{.Names}}"], {
         encoding: "utf8",
     });
     const running = (listResult.stdout ?? "").trim().split("\n").filter(Boolean);
@@ -55,7 +27,7 @@ async function stopContainers() {
     let toStop;
     if (running.length === 1) {
         toStop = running;
-        log.info(`Stopping ${running[0]}...`);
+        log.info(`Stopping ${running[0] ?? ""}...`);
     }
     else {
         const selected = await multiselect({
@@ -75,9 +47,60 @@ async function stopContainers() {
     }
     log.success("Done.");
 }
-// ─── Remove images ────────────────────────────────────────────────────────────
+// ─── Clear agent memory (multi-select across all projects) ───────────────────
+async function clearAgentMemory() {
+    const projects = listProjects().filter((p) => existsSync(join(p.projectDir, "agents")));
+    if (projects.length === 0) {
+        log.info("No agent memory found.");
+        return;
+    }
+    let toClear; // project IDs
+    if (projects.length === 1) {
+        const p = projects[0];
+        if (p === undefined)
+            return;
+        toClear = [p.id];
+        log.info(`Clearing agent memory for ${p.meta.displayName}...`);
+    }
+    else {
+        const selected = await multiselect({
+            message: "Select projects to clear agent memory for:",
+            options: projects.map((p) => ({ value: p.id, label: p.meta.displayName, hint: p.meta.projectRoot })),
+            required: false,
+        });
+        if (isCancel(selected)) {
+            cancel();
+            return;
+        }
+        toClear = selected;
+    }
+    for (const id of toClear) {
+        const p = projects.find((x) => x.id === id);
+        if (!p)
+            continue;
+        // Stop the container first if running
+        const inspectResult = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", p.meta.containerName], {
+            encoding: "utf8",
+            stdio: "pipe",
+        });
+        const isRunning = inspectResult.status === 0 && inspectResult.stdout.trim() === "running";
+        if (isRunning) {
+            const confirmed = await confirm({
+                message: `Container for ${p.meta.displayName} is running. Stop it to clear memory?`,
+            });
+            if (isCancel(confirmed) || !confirmed)
+                continue;
+            log.step(`Stopping ${p.meta.containerName}...`);
+            stopAndRemoveContainer(p.meta.containerName);
+        }
+        const agentsDir = join(p.projectDir, "agents");
+        rmSync(agentsDir, { recursive: true, force: true });
+        log.success(`Cleared agent memory for ${p.meta.displayName}.`);
+    }
+}
+// ─── Remove images (multi-select across all projects) ────────────────────────
 async function removeImages() {
-    const listResult = spawnSync("docker", ["images", "--filter", "label=totopo.managed=true", "--format", "{{.Repository}}	{{.ID}}"], {
+    const listResult = spawnSync("docker", ["images", "--filter", "label=totopo.managed=true", "--format", "{{.Repository}}\t{{.ID}}"], {
         encoding: "utf8",
     });
     const lines = (listResult.stdout ?? "").trim().split("\n").filter(Boolean);
@@ -86,16 +109,14 @@ async function removeImages() {
         return;
     }
     const images = lines.map((line) => {
-        const [repo, id] = line.split("	");
-        const workspace = (repo ?? "").replace(/^totopo-managed-/, "");
-        return { repo: repo ?? "", id: id ?? "", workspace };
+        const parts = line.split("\t");
+        const repo = parts[0] ?? "";
+        const id = parts[1] ?? "";
+        return { repo, id };
     });
     const selected = await multiselect({
         message: "Select images to remove:",
-        options: images.map((img) => ({
-            value: img.repo,
-            label: `${img.workspace}  (${img.repo})`,
-        })),
+        options: images.map((img) => ({ value: img.repo, label: img.repo, hint: img.id.slice(0, 12) })),
         required: false,
     });
     if (isCancel(selected)) {
@@ -117,32 +138,6 @@ async function removeImages() {
     }
     log.success("Done.");
 }
-// ─── Uninstall ────────────────────────────────────────────────────────────────
-async function uninstall(projectName, repoRoot) {
-    const dockerName = toDockerName(projectName);
-    const containerName = dockerName;
-    const imageName = dockerName;
-    const confirmed = await confirm({
-        message: `Remove .totopo/, stop containers, and delete the image for ${projectName}?`,
-    });
-    if (isCancel(confirmed) || !confirmed) {
-        cancel();
-        return;
-    }
-    const inspectResult = spawnSync("docker", ["inspect", "--type", "container", containerName], { encoding: "utf8" });
-    if (inspectResult.status === 0) {
-        log.step(`Stopping container ${containerName}...`);
-        stopAndRemoveContainer(containerName);
-    }
-    const imageResult = spawnSync("docker", ["images", "-q", imageName], { encoding: "utf8" });
-    if ((imageResult.stdout ?? "").trim().length > 0) {
-        log.step(`Removing image ${imageName}...`);
-        spawnSync("docker", ["rmi", imageName], { stdio: "inherit" });
-    }
-    log.step("Removing .totopo/...");
-    rmSync(join(repoRoot, ".totopo"), { recursive: true, force: true });
-    outro("Uninstalled. Re-run npx totopo to set up again.");
-}
 // ─── Reset API keys ───────────────────────────────────────────────────────────
 async function resetApiKeys(packageDir) {
     const globalEnvPath = join(homedir(), ".totopo", ".env");
@@ -157,21 +152,54 @@ async function resetApiKeys(packageDir) {
     cpSync(join(packageDir, "templates", "env"), globalEnvPath);
     log.success(`API keys reset. Edit ${globalEnvPath} to add your keys.`);
 }
-// ─── Advanced submenu ─────────────────────────────────────────────────────────
-export async function run(packageDir, projectName, repoRoot) {
-    const totopoDir = join(repoRoot, ".totopo");
+// ─── Uninstall totopo (global — wipes ~/.totopo/ and all containers/images) ──
+async function uninstallTotopo() {
+    const confirmed = await text({
+        message: 'Type "uninstall-totopo" to confirm full uninstall:',
+        validate: (v) => ((v ?? "").trim() !== "uninstall-totopo" ? 'Type exactly "uninstall-totopo" to confirm' : undefined),
+    });
+    if (isCancel(confirmed) || confirmed.trim() !== "uninstall-totopo") {
+        cancel("Uninstall cancelled.");
+        return;
+    }
+    // Stop and remove all totopo containers
+    const psResult = spawnSync("docker", ["ps", "-a", "--filter", "name=totopo-", "--format", "{{.Names}}"], {
+        encoding: "utf8",
+    });
+    const containers = (psResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    for (const c of containers) {
+        log.step(`Stopping and removing container ${c}...`);
+        stopAndRemoveContainer(c);
+    }
+    // Remove all totopo images
+    const imagesResult = spawnSync("docker", ["images", "--filter", "label=totopo.managed=true", "--format", "{{.Repository}}"], {
+        encoding: "utf8",
+    });
+    const imgs = (imagesResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    for (const img of imgs) {
+        log.step(`Removing image ${img}...`);
+        spawnSync("docker", ["rmi", img], { stdio: "inherit" });
+    }
+    // Delete ~/.totopo/
+    const globalTotopoDir = join(homedir(), ".totopo");
+    if (existsSync(globalTotopoDir)) {
+        log.step("Deleting ~/.totopo/...");
+        rmSync(globalTotopoDir, { recursive: true, force: true });
+    }
+    outro("totopo uninstalled. Re-run npx totopo to set up again.");
+}
+// ─── Manage totopo menu ───────────────────────────────────────────────────────
+export async function run(packageDir) {
     while (true) {
         const action = await select({
-            message: "Advanced:",
+            message: "Manage totopo:",
             options: [
-                { value: "runtime-mode", label: "Runtime mode", hint: "switch between host-mirror and full" },
-                { value: "rebuild", label: "Rebuild container", hint: "force a fresh image build for this project" },
-                { value: "clear-memory", label: "Clear agent memory", hint: "wipe conversation history for this project" },
-                { value: "uninstall", label: "Uninstall from this project", hint: "removes .totopo/ and deletes the container and image" },
-                { value: "stop-containers", label: "Stop containers", hint: "all projects" },
-                { value: "remove-images", label: "Remove images", hint: "all projects" },
-                { value: "reset-keys", label: "Reset API keys", hint: "overwrites ~/.totopo/.env — affects all projects" },
-                { value: "doctor", label: "Doctor", hint: "check Docker and container health" },
+                { value: "stop-containers", label: "Stop containers", hint: "pick running containers" },
+                { value: "clear-memory", label: "Clear agent memory", hint: "pick projects to clear" },
+                { value: "remove-images", label: "Remove images", hint: "pick images to remove" },
+                { value: "reset-keys", label: "Reset API keys", hint: "overwrites ~/.totopo/.env" },
+                { value: "doctor", label: "Doctor", hint: "check Docker health" },
+                { value: "uninstall", label: "Uninstall totopo", hint: "wipe ~/.totopo/ and all containers/images" },
                 { value: "back", label: "← Back" },
             ],
         });
@@ -179,30 +207,28 @@ export async function run(packageDir, projectName, repoRoot) {
             return "back";
         }
         switch (action) {
-            case "runtime-mode":
-                await runSettings(packageDir, repoRoot);
+            case "stop-containers":
+                await stopContainers();
                 break;
-            case "rebuild":
-                await runRebuild(projectName);
-                return "rebuild";
             case "clear-memory":
-                await clearAgentMemory(projectName, totopoDir);
+                await clearAgentMemory();
+                break;
+            case "remove-images":
+                await removeImages();
                 break;
             case "reset-keys":
                 await resetApiKeys(packageDir);
                 break;
-            case "uninstall":
-                await uninstall(projectName, repoRoot);
-                return;
             case "doctor":
-                await runDoctor(repoRoot, true);
-                break;
-            case "stop-containers":
-                await stopContainers();
-                break;
-            case "remove-images":
-                await removeImages();
+                await runDoctor(null, true);
+                await sleep(500);
                 break;
+            case "uninstall":
+                await uninstallTotopo();
+                return undefined;
         }
     }
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}