zeapsu · zeapsu · May 13, 2026 · May 14, 2026 · May 14, 2026 · May 25, 2026
diff --git a/AGENT_SKILL_SPEC.md b/AGENT_SKILL_SPEC.md
@@ -20,6 +20,28 @@ User Query → Agent Orchestrator → LLM selects tool → Skill executes → Sk
                                                          matching React card
 ```
 
+## Frontend Surface Hierarchy
+
+The frontend has three conceptual layers:
+
+1. **Tome Home**
+   - Default in-app landing surface.
+   - Collects user intent through a large composer and visible capability chips.
+   - Routes natural-language prompts or capability clicks into focused skill views.
+
+2. **Focused Skill Views**
+   - Render skill outputs such as `ChatWidget`, `ReportViewWidget`, `QuizWidget`, `FlashcardWidget`, `AudioPlayerWidget`, `HistoryPanel`, and `TomeSelector`.
+   - These are the primary targets for `SkillResult.ui_component`.
+
+3. **Global Command Bar**
+   - Future macOS desktop overlay.
+   - Uses the same backend skill/orchestrator contract.
+   - Can route into Tome Home or directly into a focused skill view.
+
+Tome Home itself should remain the neutral starting state; do not treat it as a normal skill result component unless a future route-level registry is added.
+
+---
+
 ### SkillResult Contract
 
 ```python
@@ -44,25 +66,37 @@ const COMPONENT_REGISTRY: Record<string, React.ComponentType<any>> = {
   "ReportViewWidget": ReportViewWidget,
   "HistoryPanel": HistoryPanel,
   "TomeSelector": TomeSelector,
-  "CommandBar": CommandBar,
+  "CommandBar": CommandBar, // future/global overlay entry point
 };
 ```
 
 When a `SkillResult` arrives:
-1. If `ui_component` is set → render the matching card with `data` as props
+1. If `ui_component` is set → route to the matching focused view/card with `data` as props
 2. If `ui_component` is null → append `content` as a markdown chat message
+3. Tome Home remains the neutral starting surface; skill results should not replace it permanently
 
 ---
 
 ## 2. Component Inventory
 
+### 2.0 App-Level Surfaces
+
+These currently live in `frontend/src/app/page.tsx`:
+
+| Surface | Role |
+|---------|------|
+| **TomeHome** | Default composer-first home after opening Sage or selecting a Tome |
+| **TomeDashboard** | Secondary overview for artifact/source status and generated work management |
+| **TopBar** | Navigation among Home, Dashboard, History, and Tomes |
+| **FocusShell** | Wrapper that hosts focused skill views and returns to Tome Home |
+
 ### 2.1 Ethereal Console Components (DESIGN.md compliant ✅)
 
 These 8 components follow the glassmorphic "Ethereal Console" design system — dark surfaces, `backdrop-blur-[32px]`, design tokens (`bg-surface`, `text-primary`, etc.), Material Symbols, `max-w-[640px]`.
 
 | # | Component | File | Status | Description |
 |---|-----------|------|--------|-------------|
-| 1 | **CommandBar** | `CommandBar.tsx` | ✅ Ready | Pill input bar (600×48px), sparkle icon, provider badge. The entry point. |
+| 1 | **CommandBar** | `CommandBar.tsx` | ✅ Ready | Pill input bar. Future global overlay entry point / reusable command input. |
 | 2 | **ChatWidget** | `ChatWidget.tsx` | ✅ Ready | Chat card with message bubbles, typing indicator, auto-scroll. Has sample data. |
 | 3 | **QuizWidget** | `QuizWidget.tsx` | ✅ Ready | Interactive quiz with progress dots, confirm/skip flow, completion ring. |
 | 4 | **FlashcardWidget** | `FlashcardWidget.tsx` | ✅ Ready | 3D flip cards (Framer Motion), shuffle/reset, keyboard nav (arrows + space). |

diff --git a/BRAINSTORM.md b/BRAINSTORM.md
@@ -8,7 +8,7 @@
 
 **Architecture**: Tauri desktop app (Next.js + Tailwind frontend, FastAPI backend)
 **What it does**: Search arXiv → download PDFs → extract text → summarize with DeepSeek → Instagram-style feed
-**Strengths**: 
+**Strengths**:
 - Working Tauri desktop app (cross-platform)
 - Clean FastAPI backend with caching
 - PDF extraction pipeline (pdfplumber)
@@ -26,8 +26,19 @@
 
 ## The Vision: "Sage" — Local Knowledge Agent
 
+### Updated UI Direction: Tome Home + Command Overlay
+
+The current product direction is not “only a floating palette.” Sage should have a calm default Tome Home for focused work, plus a lightweight global command overlay for quick macOS interactions.
+
+- **Tome Home**: default in-app surface after opening Sage or selecting a Tome.
+- **Tome Dashboard**: secondary overview, not the first impression.
+- **Command overlay**: Spotlight/Raycast-style hotkey layer for quick search, capture, and skill launch.
+- **Web version**: out of scope for now; browser mode is a development convenience.
+
+See `docs/PRODUCT_SURFACES.md` for current surface hierarchy.
+
 ### Core Idea
-A local-first desktop app where users:
+A local-first macOS desktop app where users:
 1. **Import documents** (PDFs, markdown, Obsidian vault, web clips, etc.) into a local knowledge store
 2. **Connect any agent provider** (OpenAI, Anthropic, local Ollama, DeepSeek, etc.) via BYOA config
 3. **Use skills/tools** that the app supplies to the agent, enabling: quizzes, flashcards, reports, Q&A, comparisons, timelines, and more
@@ -172,7 +183,7 @@ CREATE TABLE messages (
 ```python
 class AgentProvider(ABC):
     """Abstract interface for any LLM provider."""
-    
+
     @abstractmethod
     async def chat(
         self,
@@ -201,22 +212,22 @@ class AgentProvider(ABC):
 # ~/.sage/config.yaml
 providers:
   default: "ollama"
-  
+
   ollama:
     base_url: "http://localhost:11434"
     default_model: "llama3.1:8b"
-    
+
   openai:
     api_key: "${OPENAI_API_KEY}"
     default_model: "gpt-4o-mini"
-    
+
   anthropic:
     api_key: "${ANTHROPIC_API_KEY}"
     default_model: "claude-sonnet-4-20250514"
 
 knowledge_store:
   path: "~/.sage/knowledge.db"
-  
+
 obsidian:
   vault_path: "~/Documents/ObsidianVault"
   sync_interval: 300  # seconds

diff --git a/DESIGN.md b/DESIGN.md
@@ -13,6 +13,32 @@ No 1px solid borders for internal sectioning. Boundaries are defined through **b
 
 ---
 
+
+## Product Surface Model
+
+Sage now has two complementary desktop surfaces:
+
+1. **Tome Home — default in-app surface**
+   - Calm, centered, composer-first, and Tome-aware.
+   - Appears after opening Sage or selecting a Tome.
+   - Provides natural-language input, visible capability chips, selected Tome context, and a path to the expanded dashboard.
+   - Optimized for deliberate work inside a Tome.
+
+2. **Global Command Bar — OS overlay**
+   - Spotlight/Raycast-style layer invoked by a macOS global hotkey.
+   - Used for quick capture, search, opening a Tome, or launching a skill from anywhere.
+   - Lightweight and transient; it can route into Tome Home or focused skill views when deeper work is needed.
+
+Tome Home does **not** replace the command bar. It gives Sage a calmer home base, while the command bar preserves the original “intelligence layer over the OS” direction.
+
+3. **Focused Views**
+   - Deep-work surfaces for chat, reports, quizzes, flashcards, audio, history, sources/Tomes, and future skills.
+   - These are the primary render targets for backend skill results.
+
+Near-term interaction design should optimize for macOS desktop. Browser rendering remains useful for frontend development, but a hosted web product is out of scope for now.
+
+---
+
 ## Design Tokens
 
 ### Color Palette (Dark Only)
@@ -89,7 +115,29 @@ No 1px solid borders for internal sectioning. Boundaries are defined through **b
 
 The floating window is a **card stack**. The input bar is always the bottom layer; content cards stack on top based on interaction.
 
-### State 1: Compact Input (Default)
+
+### State 0: Tome Home
+
+Default in-app surface after opening Sage or selecting a Tome.
+
+```
+Good afternoon, zeap.
+[Selected Tome chip]
+┌──────────────────────────────────────────────────────────┐
+│ Ask Sage about this Tome, or type / for Tome skills...   │
+│                                              [+] [model] │
+└──────────────────────────────────────────────────────────┘
+[Sources] [Report] [Quiz] [Flashcards] [Audio] [Chat]
+                 View expanded Tome dashboard →
+```
+
+- **Role:** Calm home base for deliberate Tome work
+- **Content:** Selected Tome context, large composer, capability chips, dashboard affordance
+- **Default:** Opening the app or selecting a Tome lands here
+- **Dashboard:** Secondary overview for freshness/status, reached intentionally
+- **Interaction:** Capability chips route to focused views; composer routes natural language intent
+
+### State 1: Global Command Overlay
 
 ```
 ┌──────────────────────────────────────────────────────────┐
@@ -98,6 +146,7 @@ The floating window is a **card stack**. The input bar is always the bottom laye
 ```
 
 - **Size:** 600px × 48px
+- **Role:** Transient macOS overlay, not the primary in-app home page
 - **Position:** Centered horizontally, **upper third** of screen (~20–25% from top)
 - **Shape:** Full rounded (pill)
 - **Background:** `surface` at 80% opacity + `backdrop-blur: 32px` — slightly lighter than the deepest background to create floating effect
@@ -303,9 +352,11 @@ The floating window is a **card stack**. The input bar is always the bottom laye
 1. **Window position** persists across sessions (user can drag to reposition)
 2. **Going back** collapses the top card (Esc key or back gesture)
 3. **Pin mode** (optional): Click pin icon to keep window visible
-4. **Global hotkey** activates the palette (configurable, default: `Cmd+Shift+S`)
+4. **Global hotkey** activates the command overlay (configurable, default: `Cmd+Shift+S`)
 5. **X button** appears on hover (top-right, like Raycast)
 6. **No window chrome** — no title bar, no system decorations
+7. **Opening the full app** lands on Tome Home, not the compact overlay
+8. **Tome Dashboard** is secondary and reached intentionally from Tome Home
 
 ---
 

diff --git a/PLAN.md b/PLAN.md
@@ -4,7 +4,9 @@
 
 > **For:** Claude Code, Codex, or any coding agent. Follow tasks sequentially. Each task is 2-5 minutes.
 
-> **Read first:** `BRAINSTORM.md`, `DESIGN.md` — full architecture and design spec.
+> **Read first:** `BRAINSTORM.md`, `DESIGN.md`, `docs/PRODUCT_SURFACES.md` — full architecture, design spec, and current product-surface direction.
+
+> **Current direction override:** this Phase 1 plan is historical in places. Current frontend direction is Tome Home as the default in-app surface, Tome Dashboard as secondary, focused skill views for deep work, and a future macOS Spotlight/Raycast-style command overlay. Near-term target is macOS desktop; hosted/web product work is out of scope for now.
 
 ---
 
@@ -29,7 +31,7 @@
 # Backend
 pip install sentence-transformers aiohttp pyyaml
 
-# Frontend  
+# Frontend
 cd frontend && npm install framer-motion zustand clsx tailwind-merge
 ```
 

diff --git a/README.md b/README.md
@@ -12,16 +12,22 @@ Sage is moving toward a NotebookLM-like experience that stays local-first and pr
 - **Tomes**: focused workspaces that isolate source sets and chat history.
 - **Bring your own agent/provider**: local models, Ollama, OpenAI-compatible APIs, Anthropic, DeepSeek, and other providers through a small backend abstraction.
 - **Grounded outputs**: chat, reports, quizzes, flashcards, and audio reviews that cite or otherwise remain tied to the selected sources.
-- **Floating desktop UX**: an Ethereal Console style interface that feels like a lightweight intelligence layer over the OS.
+- **Tome Home default**: a calm, composer-first surface after opening Sage or selecting a Tome.
+- **Floating desktop UX**: a future Spotlight/Raycast-style command bar that feels like a lightweight intelligence layer over macOS.
 
 arXiv support and paper summarization remain useful discovery paths, but they are no longer the center of the product. The main direction is user-owned local knowledge.
 
+The desktop UI has two complementary layers: **Tome Home** for deliberate in-app work, and a future **global command bar** for quick macOS capture/search/skill launch from anywhere. Tome Dashboard remains a secondary overview for artifact status and management, not the default first impression.
+
+Near-term scope is macOS desktop-first. The Next.js frontend can run in a browser for development, but a hosted/user-facing web version is out of scope until the desktop UX, local data model, privacy story, and sync requirements are stable.
+
 ## Current Features
 
 - **Tauri desktop shell** with a Next.js 15 frontend.
 - **FastAPI backend** for knowledge, chat, Tomes, providers, and research discovery endpoints.
 - **Local knowledge store** with document chunks, embeddings, sessions, and Tome/source links.
-- **Floating command UI** with chat, report, quiz, flashcard, audio, history, and Tome-oriented components.
+- **Tome Home** composer-first UI with capability chips for chat, report, quiz, flashcards, audio, history, and Tome-oriented components.
+- **Secondary Tome Dashboard** for artifact/source status and generated work management.
 - **Tailwind v4 design tokens** for the dark Ethereal Console visual system.
 - **pytest backend suite** and GitHub Actions CI.
 
@@ -31,6 +37,7 @@ Several planning/specification files in the repo describe where Sage is headed:
 
 - `BRAINSTORM.md`: product direction from arXiv summarizer to local knowledge agent.
 - `DESIGN.md`: Ethereal Console UI/UX specification.
+- `docs/PRODUCT_SURFACES.md`: current Tome Home, command-bar overlay, desktop/web scope context for humans and agents.
 - `PLAN.md`: implementation plan for the local knowledge agent foundation.
 - `AGENT_SKILL_SPEC.md`: contract between backend skills and frontend UI components.
 - `STITCH_PROMPT.md`: original design prompt/reference for the floating UI.
@@ -133,17 +140,20 @@ Sage/
 │   ├── src/lib/             # Typed API client and frontend utilities
 │   └── src-tauri/           # Tauri desktop configuration
 ├── designs/                 # Design references and generated visual artifacts
+├── docs/                    # Current product-surface notes and feature references
 ├── *.md                     # Product, design, agent, and implementation docs
 └── README.md
 ```
 
 ## Near-Term Roadmap
 
-- Finish replacing old pre-Ethereal UI paths with the Ethereal Console components.
+- Keep Tome Home as the default composer-first app surface and Tome Dashboard as a secondary overview.
+- Design the macOS global command bar as a separate Spotlight/Raycast-style overlay for quick capture, search, and skill launch.
 - Make Tomes first-class across upload, chat, retrieval, history, and generated artifacts.
 - Improve report rendering and exports, likely moving toward an HTML-friendly artifact model.
 - Add explicit schema migrations for existing local Sage databases.
 - Expand evaluation coverage for retrieval quality, grounding, and generated artifact correctness.
+- Defer hosted/web product work until macOS desktop behavior and local data assumptions are stable.
 
 ## Contributing
 

diff --git a/SESSION_CONTEXT.md b/SESSION_CONTEXT.md
@@ -6,7 +6,7 @@
 
 ## Project Overview
 
-**Sage** (renamed from "arXivSage") — a local-first desktop knowledge agent. Tauri + Next.js 15 frontend (Tailwind v4), FastAPI backend.
+**Sage** (renamed from "arXivSage") — a local-first desktop knowledge agent. Tauri + Next.js 15 frontend (Tailwind v4), FastAPI backend. Near-term product target is macOS desktop.
 
 **Core concept:** User-uploads sources as the primary workflow (like NotebookLM). arXiv search is a secondary "discover more" feature. "Tomes" = isolated sessions with focused sources, each with their own chat history. Sources can belong to multiple tomes (many-to-many).
 
@@ -18,25 +18,26 @@
 
 ## Design Vision: "The Ethereal Console"
 
-A floating command palette UI (Raycast-style). Core principles:
-- **No 1px solid borders** — boundaries via color shifts + depth
-- **Dark theme only** — rich charcoal palette, never pure `#000`
-- **Floating pill input bar** — centered upper third, 600×48px, `backdrop-blur: 32px`
-- **7 window states** that stack as cards: Compact Input, Chat, Quiz, Flashcards, Audio Player, Report, History
+Current direction is **Tome Home + command overlay**, not “only a floating palette.”
 
-Full spec: `DESIGN.md`
+- **Tome Home**: default in-app surface implemented in `frontend/src/app/page.tsx`; calm, composer-first, selected-Tome aware, with capability chips.
+- **Tome Dashboard**: secondary overview for artifact/source status and generated work management.
+- **Global command bar**: future Spotlight/Raycast-style macOS overlay for quick capture, search, Tome opening, and skill launch from anywhere.
+- **Focused views**: Chat, Quiz, Flashcards, Audio, Report, History, and Tomes/Sources.
+
+Core principles remain: no heavy chrome, dark charcoal palette, depth over hard dividers, and sparse accent use. Full spec: `DESIGN.md`; current product-surface context: `docs/PRODUCT_SURFACES.md`.
 
 ---
 
 ## Component Inventory (15 components)
 
-### ✅ Ethereal Console Components (8) — Production-ready
+### ✅ Ethereal Console Components and Surfaces — Production-ready
 
-All follow `DESIGN.md` glassmorphic spec. Used in `page.tsx`.
+Focused components follow `DESIGN.md` glassmorphic spec. `page.tsx` also owns app-level surfaces: `TomeHome`, `TomeDashboard`, `TopBar`, and `FocusShell`.
 
 | Component | File | Description |
 |-----------|------|-------------|
-| **CommandBar** | `CommandBar.tsx` | Pill input bar (600×48px), sparkle icon, provider badge |
+| **CommandBar** | `CommandBar.tsx` | Pill input bar. Keep for future global overlay / focused command input patterns. |
 | **ChatWidget** | `ChatWidget.tsx` | Chat card with message bubbles, typing indicator, auto-scroll |
 | **QuizWidget** | `QuizWidget.tsx` | Interactive quiz with progress dots, confirm/skip, completion ring |
 | **FlashcardWidget** | `FlashcardWidget.tsx` | 3D flip cards (Framer Motion), shuffle/reset, keyboard nav |
@@ -144,13 +145,15 @@ Full spec written at `AGENT_SKILL_SPEC.md` (632 lines). Covers:
 
 ---
 
-## What's Next (After Legacy Cleanup)
+## What's Next
 
 | Priority | Item |
 |----------|------|
+| 🔴 | **Global command bar overlay** — design macOS Spotlight/Raycast-style layer separately from Tome Home |
 | 🔴 | **AudioPlayerWidget** — needs `audio_url` prop + real `<audio>` element (currently simulated with setInterval) |
 | 🔴 | **ChatWidget** — needs streaming support (SSE/WebSocket, currently static) |
 | 🔴 | **Backend integration** — wire up `/api/agent/chat` → Agent Orchestrator → Skill Registry |
 | 🟡 | **Piper TTS setup** — voice models + pipeline for `generate_audio_review` |
 | 🟡 | **Responsive/viewport testing** |
+| 🟡 | **Web scope** — keep hosted/browser product out of scope; browser mode is for development only |
 | 🟢 | **ComparisonWidget** / **TimelineWidget** — future dedicated components |