diff --git a/AGENT_SKILL_SPEC.md b/AGENT_SKILL_SPEC.md index c1b688a..1ef118a 100644 --- 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> = { "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 index b215255..d68edfb 100644 --- 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 index 546891c..eefbb56 100644 --- 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 index 9e98bd8..e208501 100644 --- 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 index 1a0daf1..e24ea98 100644 --- 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 index 7ee8fbf..390cde9 100644 --- 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 `