feat: books.show — the agent puts things on the viewer's screen

books.show asks the viewer to open an entry, an account register, a
report (dates, month/quarter/year columns, prior-period or prior-year
comparison), a document, a search, or a page. The request lives outside
the books (runtime dir, keyed by data dir, written atomically); the
viewer watches it beside the journal and applies books before
navigating. 66 tools.

Site: the dashboard is the hero again; 'Here's what using it looks like'
shows the session beside the viewer, ending in books.show; the cash page
replaces the repeated overview lower down.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MtYEaR6M6Ybdhm6X98BWNu

crates/ledger-gui/src/app.rs

@@ -99,6 +99,102 @@ impl App {
         self.receipts.settle(ctx);
     }
 
+    /// Go where the agent asked (`books.show`).
+    pub fn show(&mut self, target: ledger_store::viewer::ViewerTarget) {
+        use crate::nav::ReportKind;
+        use ledger_store::viewer::ViewerTarget as T;
+        let Some(b) = self.books.clone() else {
+            return;
+        };
+        let date = |s: &Option<String>| {
+            s.as_deref()
+                .and_then(|d| d.parse::<chrono::NaiveDate>().ok())
+        };
+        let route = match target {
+            T::Page { page } => match page.as_str() {
+                "overview" => Route::Overview,
+                "cash" => Route::Cash,
+                "profit" => Route::Profit,
+                "transactions" => Route::Transactions,
+                "reports" => Route::Reports(ReportKind::ProfitAndLoss),
+                "accounts" => Route::Accounts,
+                "documents" => Route::Documents,
+                "company" => Route::Company,
+                "journal" => Route::Journal,
+                _ => return,
+            },
+            T::Entry { entry_id } => Route::Entry(entry_id),
+            T::Account { code, start, end } => {
+                let Some(a) = b.ledger.chart().find_by_code(&code) else {
+                    return;
+                };
+                self.state.accounts.range = match (date(&start), date(&end)) {
+                    (None, None) => None,
+                    (s, e) => Some((
+                        s.unwrap_or_else(|| b.kpis.first_entry.unwrap_or(b.today)),
+                        e.unwrap_or(b.today),
+                    )),
+                };
+                Route::Account(a.id)
+            }
+            T::Report {
+                report,
+                start,
+                end,
+                columns,
+                compare,
+            } => {
+                use crate::pages::reports::{Columns, Compare};
+                self.state.reports.columns = match columns.as_deref() {
+                    Some("month") => Columns::Month,
+                    Some("quarter") => Columns::Quarter,
+                    Some("year") => Columns::Year,
+                    _ => Columns::Total,
+                };
+                self.state.reports.compare = match compare.as_deref() {
+                    Some("prior_period") => Compare::PriorPeriod,
+                    Some("prior_year") => Compare::PriorYear,
+                    _ => Compare::None,
+                };
+                let kind = match report.as_str() {
+                    "profit_and_loss" => ReportKind::ProfitAndLoss,
+                    "balance_sheet" => ReportKind::BalanceSheet,
+                    "cash_flow" => ReportKind::CashFlow,
+                    "members_equity" => ReportKind::MembersEquity,
+                    "trial_balance" => ReportKind::TrialBalance,
+                    "general_ledger" => ReportKind::GeneralLedger,
+                    "tax_summary" => ReportKind::TaxSummary,
+                    "vendor_1099" => ReportKind::Vendor1099,
+                    "ar_aging" => ReportKind::ArAging,
+                    "ap_aging" => ReportKind::ApAging,
+                    _ => return,
+                };
+                if let (s, e) = (date(&start), date(&end))
+                    && (s.is_some() || e.is_some())
+                {
+                    let (ds, de) = crate::pages::reports::Range::YearToDate.dates(&b);
+                    self.state.reports.range =
+                        crate::pages::reports::Range::Custom(s.unwrap_or(ds), e.unwrap_or(de));
+                }
+                Route::Reports(kind)
+            }
+            T::Document { attachment_id } => Route::Document(attachment_id),
+            T::Search { query } => {
+                let st = &mut self.state.transactions;
+                st.query = query;
+                st.filter = Default::default();
+                st.account = None;
+                Route::Transactions
+            }
+        };
+        self.nav.go(route);
+    }
+
+    /// Where the app is (tests).
+    pub fn route(&self) -> &Route {
+        &self.nav.current
+    }
+
     /// Page state (tests).
     /// Label a fixed-books app "Live", as it reads when following a
     /// journal (screenshots of what a running app looks like).
@@ -401,17 +497,18 @@ fn live_status(ui: &mut Ui, b: &Books, since_update: f64, live: bool) {
 
 impl eframe::App for App {
     fn ui(&mut self, ui: &mut Ui, _frame: &mut eframe::Frame) {
-        if let Some(loader) = &self.loader {
-            match loader.poll() {
-                Some(Update::Books(b)) => {
+        let updates = self.loader.as_ref().map(|l| l.poll()).unwrap_or_default();
+        for u in updates {
+            match u {
+                Update::Books(b) => {
                     if self.books.is_some() {
                         self.updated_at = ui.input(|i| i.time);
                     }
                     self.books = Some(b);
                     self.error = None;
                 }
-                Some(Update::Error(e)) => self.error = Some(e),
-                None => {}
+                Update::Error(e) => self.error = Some(e),
+                Update::Show(target) => self.show(target),
             }
         }
         self.receipts.pump(ui.ctx());

crates/ledger-gui/src/data.rs

@@ -30,6 +30,8 @@ pub struct Source {
 pub enum Update {
     Books(Arc<Books>),
     Error(String),
+    /// The agent asked the viewer to show something (`books.show`).
+    Show(ledger_store::viewer::ViewerTarget),
 }
 
 pub struct Loader {
@@ -46,13 +48,10 @@ impl Loader {
         Loader { rx }
     }
 
-    /// The newest update, if any arrived since the last call.
-    pub fn poll(&self) -> Option<Update> {
-        let mut last = None;
-        while let Ok(u) = self.rx.try_recv() {
-            last = Some(u);
-        }
-        last
+    /// Every update since the last call, in order (books before the
+    /// navigation that refers to them).
+    pub fn poll(&self) -> Vec<Update> {
+        self.rx.try_iter().collect()
     }
 
     /// Block until the first update (tests, headless).
@@ -121,6 +120,26 @@ fn run(source: Source, ctx: egui::Context, tx: Sender<Update>) {
     let mut last_disk = Some(disk);
     send(first);
 
+    // Requests to show something: apply new ones, and on start one made in
+    // the last two minutes (the agent said "open the viewer"); never an
+    // old one.
+    let started = chrono::Utc::now();
+    let mut last_show = 0u64;
+    let mut check_show = |send: &dyn Fn(Update)| {
+        if let Some(cmd) = ledger_store::viewer::read(&source.data_dir)
+            && cmd.seq != last_show
+        {
+            let first_look = last_show == 0;
+            last_show = cmd.seq;
+            let recent = chrono::DateTime::parse_from_rfc3339(&cmd.at)
+                .is_ok_and(|t| started.signed_duration_since(t) < chrono::Duration::minutes(2));
+            if !first_look || recent {
+                send(Update::Show(cmd.target));
+            }
+        }
+    };
+    check_show(&send);
+
     let (ev_tx, ev_rx) = channel();
     let mut watcher = notify::recommended_watcher(move |res: notify::Result<notify::Event>| {
         if res.is_ok() {
@@ -130,6 +149,11 @@ fn run(source: Source, ctx: egui::Context, tx: Sender<Update>) {
     .ok();
     if let Some(w) = watcher.as_mut() {
         let _ = w.watch(&source.data_dir, RecursiveMode::NonRecursive);
+        let cmd = ledger_store::viewer::command_path(&source.data_dir);
+        if let Some(dir) = cmd.parent() {
+            let _ = std::fs::create_dir_all(dir);
+            let _ = w.watch(dir, RecursiveMode::NonRecursive);
+        }
         if let Some(t) = &source.books_toml
             && let Some(dir) = t.parent()
         {
@@ -174,5 +198,6 @@ fn run(source: Source, ctx: egui::Context, tx: Sender<Update>) {
             last_disk = Some(disk);
             send(update);
         }
+        check_show(&send);
     }
 }

crates/ledger-gui/src/lib.rs

@@ -11,7 +11,7 @@ pub mod data;
 pub mod demo;
 mod fmt;
 pub mod nav;
-mod pages;
+pub mod pages;
 mod palette;
 mod receipts;
 mod theme;

crates/ledger-gui/tests/live.rs

@@ -64,5 +64,27 @@ fn a_change_in_another_process_shows_up_live() {
     assert!(b.fresh.contains(&e), "the new entry is highlighted as new");
     assert!(b.seq() > first.seq());
     eprintln!("live update arrived in {:?}", started.elapsed());
+
+    // The agent asks the viewer to show the entry (books.show).
+    let asked = Instant::now();
+    ledger_store::viewer::request(
+        &data,
+        ledger_store::viewer::ViewerTarget::Entry { entry_id: e },
+    )
+    .unwrap();
+    let deadline = Instant::now() + Duration::from_secs(10);
+    let mut shown = false;
+    while Instant::now() < deadline {
+        if let Some(Update::Show(ledger_store::viewer::ViewerTarget::Entry { entry_id })) =
+            loader.wait(Duration::from_millis(200))
+        {
+            assert_eq!(entry_id, e);
+            shown = true;
+            break;
+        }
+    }
+    assert!(shown, "the show request never reached the viewer");
+    eprintln!("show request arrived in {:?}", asked.elapsed());
+    let _ = std::fs::remove_file(ledger_store::viewer::command_path(&data));
     let _ = std::fs::remove_dir_all(&dir);
 }

crates/ledger-gui/tests/show.rs

@@ -0,0 +1,73 @@
+//! books.show requests drive the viewer to the right place.
+
+use egui_kittest::Harness;
+use ledger_gui::nav::{ReportKind, Route};
+use ledger_gui::{App, Source, data};
+use ledger_store::viewer::ViewerTarget;
+
+#[test]
+fn show_requests_navigate_the_viewer() {
+    let today = chrono::NaiveDate::from_ymd_opt(2026, 10, 12).unwrap();
+    let dir = std::env::temp_dir().join(format!("ledger-gui-show-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    ledger_gui::demo::build(&dir, today).unwrap();
+    let source = Source {
+        data_dir: dir.join("books-data"),
+        books_toml: Some(dir.join("wanderbooks.toml")),
+        today: Some(today),
+    };
+    let books = data::load_once(&source).unwrap();
+    let rent = books.ledger.chart().find_by_code("6200").unwrap().id;
+    let mut h = Harness::builder()
+        .with_size(egui::vec2(1440.0, 920.0))
+        .build_eframe(|cc| App::with_books(&cc.egui_ctx, books, true, Route::Overview));
+
+    // "Compare this quarter's P&L with the same quarter last year, by month."
+    h.state_mut().show(ViewerTarget::Report {
+        report: "profit_and_loss".into(),
+        start: Some("2026-07-01".into()),
+        end: Some("2026-09-30".into()),
+        columns: Some("month".into()),
+        compare: Some("prior_year".into()),
+    });
+    h.run_steps(2);
+    assert_eq!(
+        h.state_mut().route(),
+        &Route::Reports(ReportKind::ProfitAndLoss)
+    );
+    let st = &h.state_mut().state_mut().reports;
+    assert_eq!(
+        st.range,
+        ledger_gui::pages::reports::Range::Custom(
+            chrono::NaiveDate::from_ymd_opt(2026, 7, 1).unwrap(),
+            chrono::NaiveDate::from_ymd_opt(2026, 9, 30).unwrap()
+        )
+    );
+    assert_eq!(st.columns, ledger_gui::pages::reports::Columns::Month);
+
+    // "Show me the rent account for the summer."
+    h.state_mut().show(ViewerTarget::Account {
+        code: "6200".into(),
+        start: Some("2026-06-01".into()),
+        end: Some("2026-08-31".into()),
+    });
+    h.run_steps(2);
+    assert_eq!(h.state_mut().route(), &Route::Account(rent));
+
+    // "Find every Adobe charge."
+    h.state_mut().show(ViewerTarget::Search {
+        query: "adobe".into(),
+    });
+    h.run_steps(2);
+    assert_eq!(h.state_mut().route(), &Route::Transactions);
+    assert_eq!(h.state_mut().state_mut().transactions.query, "adobe");
+
+    // Unknown accounts are ignored, not crashes.
+    h.state_mut().show(ViewerTarget::Account {
+        code: "9999".into(),
+        start: None,
+        end: None,
+    });
+    assert_eq!(h.state_mut().route(), &Route::Transactions);
+    let _ = std::fs::remove_dir_all(&dir);
+}