feat(viewer): the agent dock and the first-run page (P11b)

D-27: a terminal panel along the bottom of the viewer (alacritty_terminal over
a PTY) runs Claude Code (default) or Codex in the book's books home, resizable,
collapsible, the choice remembered. The agent is an ordinary child process the
owner describes (agent_start); the viewer stays read-only: the agent writes
through the server like any other. A missing agent is offered through its
vendor's installer (a command to copy), never bundled; no folder is marked
trusted (Q-7, recommended answer: let Codex ask). Windows is not offered until
its ConPTY checks are recorded.

P11a found that onboarding with no terminal was false: the viewer opened only an
existing book. With no books and an owner, wanderbooks gui now shows a first-run
page: the private folder, the owner passphrase (typed in the viewer, optional),
the first books, an agent, then the books open. connect and New books... make
the books home. Tests: dock.rs, welcome.rs, books_home.rs (host and cli).
Docs: testing.md record and For P12, architecture, parity, gui.md, README.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HS8WZziDnyxunC23MUxrLp

crates/ledger-cli/src/main.rs

@@ -71,7 +71,7 @@ impl ledger_gui::owner::Owner for ViewerOwner {
     }
 
     fn new_books(&self, id: &str, currency: &str) -> Result<String, String> {
-        ledger_host::commands::new_books(&self.0, id, currency)
+        ledger_host::commands::new_books_and_home(&self.0, id, currency)
     }
 
     fn back_up_now(&self, book: &str) -> Result<Vec<String>, String> {
@@ -113,7 +113,60 @@ impl ledger_gui::owner::Owner for ViewerOwner {
             ledger_gui::owner::Agent::Claude => "claude",
             ledger_gui::owner::Agent::Codex => "codex",
         };
-        ledger_host::commands::connect_agent(&self.0, agent, book)
+        ledger_host::commands::connect_and_home(&self.0, agent, book)
+    }
+
+    fn first_run(&self) -> ledger_gui::owner::FirstRun {
+        let s = ledger_host::commands::first_run_state(&self.0);
+        ledger_gui::owner::FirstRun {
+            root: s.root,
+            books: s.books,
+            passphrase_set: s.passphrase_set,
+        }
+    }
+
+    fn set_up(&self) -> Result<Vec<String>, String> {
+        ledger_host::commands::set_up_root(&self.0)
+    }
+
+    fn set_passphrase(&self, new: &str) -> Result<(), String> {
+        ledger_host::commands::set_first_passphrase(&self.0, new)
+    }
+
+    fn hold(&self, book: &str) {
+        ledger_host::commands::hold_for_viewer(&self.0, Some(book.to_string()));
+    }
+
+    fn agent_start(
+        &self,
+        agent: ledger_gui::owner::Agent,
+        book: &str,
+    ) -> Result<ledger_gui::owner::AgentStart, String> {
+        use ledger_gui::owner::{AgentStart, Installer};
+        let agent = match agent {
+            ledger_gui::owner::Agent::Claude => "claude",
+            ledger_gui::owner::Agent::Codex => "codex",
+        };
+        Ok(match ledger_host::commands::start_agent(agent, book)? {
+            ledger_host::commands::AgentStart::Ready {
+                label,
+                program,
+                args,
+                dir,
+                env,
+            } => AgentStart::Ready {
+                label: label.to_string(),
+                program,
+                args,
+                dir,
+                env,
+            },
+            ledger_host::commands::AgentStart::Missing(i) => AgentStart::Missing(Installer {
+                label: i.label.to_string(),
+                command: i.command.to_string(),
+                page: i.page.to_string(),
+            }),
+        })
     }
 
     fn upgrade_format(&self, book: &str, passphrase: &str) -> Result<Vec<String>, String> {
@@ -148,14 +201,18 @@ fn run_gui(args: Vec<String>) -> i32 {
         }
         let root = value("--root").map(PathBuf::from);
         let book = value("--book");
-        if known && ledger_gui::book_in_root(root.as_deref(), book.as_deref()).is_ok() {
-            // The viewer asks about a format upgrade in its own window.
+        if known {
+            // The viewer asks about a format upgrade in its own window, makes
+            // the first books when there are none, and starts the agent in
+            // its dock.
             let common = ledger_host::commands::Common {
-                root,
+                root: root.clone(),
                 ..Default::default()
             };
             ledger_gui::owner::set_owner(std::sync::Arc::new(ViewerOwner(common.clone())));
-            ledger_host::commands::hold_for_viewer(&common, book);
+            if ledger_gui::book_in_root(root.as_deref(), book.as_deref()).is_ok() {
+                ledger_host::commands::hold_for_viewer(&common, book);
+            }
         }
     }
     match ledger_gui::run("wanderbooks gui", args) {

crates/ledger-cli/tests/books_home.rs

@@ -0,0 +1,152 @@
+//! `wanderbooks connect` makes the book's books home (P11b, D-27): a folder in
+//! the account's Documents holding the agent's pointer and nothing of the
+//! books. Run with a home of the test's own: nothing here touches the account's
+//! real Documents or data root.
+
+#![cfg(unix)]
+
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+const KNOBS: &str =
+    "close_after=2500,backoff=50,exe_poll=100,init_wait=5000,queue_wait=30000,backup_quiet=300";
+
+struct Home {
+    dir: tempfile::TempDir,
+}
+
+impl Home {
+    fn new() -> Self {
+        let dir = tempfile::Builder::new()
+            .prefix("wb-books-home-")
+            .tempdir()
+            .unwrap();
+        let out = Command::new(env!("CARGO_BIN_EXE_wanderbooks"))
+            .args(["setup", "--home"])
+            .arg(dir.path())
+            .env_remove("XDG_DATA_HOME")
+            .output()
+            .unwrap();
+        assert!(out.status.success(), "{out:?}");
+        Self { dir }
+    }
+
+    fn root(&self) -> PathBuf {
+        self.dir.path().join(".local/share/wanderbooks")
+    }
+
+    fn cmd(&self, mode: &str, path: &Path) -> Command {
+        let mut c = Command::new(env!("CARGO_BIN_EXE_wanderbooks"));
+        c.arg(mode)
+            .arg("--root")
+            .arg(self.root())
+            .args(["--test-knobs", KNOBS])
+            .env_clear()
+            .env("PATH", format!("{}:/usr/bin:/bin", path.display()))
+            .env("HOME", self.dir.path())
+            .stdin(Stdio::null());
+        c
+    }
+}
+
+/// A stand-in `claude` that accepts whatever it is told.
+fn fake_agent(home: &Home) -> PathBuf {
+    use std::os::unix::fs::PermissionsExt;
+    let bin = home.dir.path().join("agent-bin");
+    std::fs::create_dir_all(&bin).unwrap();
+    let script = bin.join("claude");
+    std::fs::write(&script, "#!/bin/sh\nexit 0\n").unwrap();
+    std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();
+    bin
+}
+
+#[test]
+fn connect_makes_the_books_home_and_it_holds_no_books_data() {
+    let home = Home::new();
+    let out = home
+        .cmd("books", Path::new("/nonexistent"))
+        .args(["create", "beta"])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "{out:?}");
+    let docs = home.dir.path().join("Documents/Wanderbooks/beta");
+
+    // An agent that isn't installed: said, and no folder made for nothing.
+    let out = home
+        .cmd("connect", Path::new("/nonexistent"))
+        .args(["claude", "--book", "beta"])
+        .output()
+        .unwrap();
+    assert!(!out.status.success());
+    assert!(!docs.exists(), "a home for an agent that isn't there");
+
+    // Connected: the user-scope entry as ever, and the books home beside it.
+    let bin = fake_agent(&home);
+    let out = home
+        .cmd("connect", &bin)
+        .args(["claude", "--book", "beta"])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "{out:?}");
+    let said = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        said.contains("Claude Code reaches the books beta"),
+        "{said}"
+    );
+    assert!(
+        said.contains(&format!("The books home is {}", docs.display())),
+        "{said}"
+    );
+    let mut names: Vec<String> = Vec::new();
+    for dir in [docs.clone(), docs.join(".claude")] {
+        for e in std::fs::read_dir(&dir).unwrap() {
+            let p = e.unwrap().path();
+            if p.is_file() {
+                names.push(
+                    p.strip_prefix(&docs)
+                        .unwrap()
+                        .to_string_lossy()
+                        .into_owned(),
+                );
+            }
+        }
+    }
+    names.sort();
+    assert_eq!(
+        names,
+        [
+            ".claude/settings.json",
+            ".mcp.json",
+            "AGENTS.md",
+            "CLAUDE.md"
+        ]
+    );
+    // Nothing in it names the data root, a token or a key.
+    let root = home.root();
+    for n in &names {
+        let text = std::fs::read_to_string(docs.join(n)).unwrap();
+        assert!(!text.contains(root.to_str().unwrap()), "{n}: {text}");
+        assert!(!text.contains("wb_"), "{n} holds a token: {text}");
+        assert!(!text.contains("--root"), "{n}: {text}");
+    }
+    let mcp: serde_json::Value =
+        serde_json::from_str(&std::fs::read_to_string(docs.join(".mcp.json")).unwrap()).unwrap();
+    assert_eq!(
+        mcp["mcpServers"]["wanderbooks-beta"]["args"],
+        serde_json::json!(["mcp", "--book", "beta"])
+    );
+    // Run again: still four files, the rule once.
+    let out = home
+        .cmd("connect", &bin)
+        .args(["claude", "--book", "beta"])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "{out:?}");
+    let settings: serde_json::Value =
+        serde_json::from_str(&std::fs::read_to_string(docs.join(".claude/settings.json")).unwrap())
+            .unwrap();
+    assert_eq!(
+        settings["permissions"]["allow"],
+        serde_json::json!(["mcp__wanderbooks-beta__*"])
+    );
+}