zeapsu · zeapsu · Jun 1, 2026 · May 27, 2026 · May 27, 2026 · May 27, 2026
diff --git a/README.md b/README.md
@@ -2,40 +2,42 @@
 
 > A local-first desktop knowledge agent for turning your own sources into chat, reports, quizzes, flashcards, and audio reviews.
 
-Sage is a Tauri + Next.js + FastAPI app for working with a personal knowledge base. The core workflow is simple: bring documents into a local store, organize focused source sets as Tomes, then ask Sage to synthesize grounded outputs from those sources.
+Sage is a Tauri + Next.js + FastAPI app for working with a personal knowledge base. The current default UI is **Tome Home**: a source-first workspace where you add knowledge, choose or create Tomes, and route explicit actions to focused learning/research views.
 
-## Vision
+## Product Truth
 
-Sage is moving toward a NotebookLM-like experience that stays local-first and provider-flexible:
+Sage is no longer centered on an Instagram-style arXiv summarizer. arXiv search and paper summarization remain useful discovery/import paths, but the main product is user-owned local knowledge:
 
-- **Bring your own sources**: PDFs, Markdown, notes, pasted text, and eventually web captures or vault syncs.
-- **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.
-
-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.
+- **Bring your own sources**: text, Markdown, PDFs, pasted notes, and eventually web/vault syncs.
+- **Tomes**: focused workspaces that group source sets and provide a home for chat history and generated artifacts.
+- **Bring your own agent/provider (BYOA)**: local and hosted providers through a small backend abstraction; the next likely roadmap emphasis is deeper BYOA / bring-your-own-agent integration.
+- **Grounded outputs**: chat, reports, quizzes, flashcards, and audio reviews tied to the selected sources.
+- **Explicit command routing**: slash commands and first-party capability chips open generated views; ordinary natural-language questions stay in chat.
+- **Ethereal Console direction**: the interface should keep the lightweight, luminous desktop-command feel while Tome Home remains the default landing experience.
 
 ## 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 default UI** with source, report, quiz, flashcard, audio, chat, history, Tome, and settings navigation.
+- **Local user profile setup** that stores a name and user-specific details in browser `localStorage` for owner-specific greetings and editable settings.
+- **Tauri v2 desktop shell** with a Next.js 15 / React 19 frontend.
+- **FastAPI backend** for knowledge, chat, Tomes, skills, provider config, generation, audio, and legacy research endpoints.
+- **Local knowledge store** under `~/.sage/` with documents, chunks, sessions, and Tome/source links.
+- **Typed frontend API client** that can use a browser backend (`NEXT_PUBLIC_API_URL`) or a Tauri sidecar backend (`NEXT_PUBLIC_DESKTOP_API_URL`).
 - **Tailwind v4 design tokens** for the dark Ethereal Console visual system.
 - **pytest backend suite** and GitHub Actions CI.
 
-## Project Direction Docs
+## Documentation
 
-Several planning/specification files in the repo describe where Sage is headed:
+Root-level planning/spec Markdown has been organized under `docs/`:
 
-- `BRAINSTORM.md`: product direction from arXiv summarizer to local knowledge agent.
-- `DESIGN.md`: Ethereal Console UI/UX specification.
-- `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.
-- `SESSION_CONTEXT.md`: current project state and next-session context.
-- `LEGACY_CLEANUP_PLAN.md`: notes for removing old pre-Ethereal components.
+- [`docs/product/vision.md`](docs/product/vision.md): product direction from arXiv summarizer to local knowledge agent.
+- [`docs/design/ethereal-console.md`](docs/design/ethereal-console.md): Ethereal Console UI/UX specification.
+- [`docs/design/stitch-prompt.md`](docs/design/stitch-prompt.md): original Stitch prompt/reference for the floating UI.
+- [`docs/agents/handoff.md`](docs/agents/handoff.md): fast onboarding context for coding agents and future sessions.
+- [`docs/agents/skill-spec.md`](docs/agents/skill-spec.md): contract between backend skills and frontend UI/components.
+- [`docs/planning/phase-1-plan.md`](docs/planning/phase-1-plan.md): historical implementation plan for the local knowledge foundation.
+- [`docs/planning/legacy-todo.md`](docs/planning/legacy-todo.md): archived early project checklist.
+- [`docs/archive/legacy-cleanup-plan.md`](docs/archive/legacy-cleanup-plan.md): cleanup notes for old pre-Ethereal components.
 
 ## Tech Stack
 
@@ -60,7 +62,7 @@ Several planning/specification files in the repo describe where Sage is headed:
 
 ### Prerequisites
 
-- Node.js 20+
+- Node.js 22 LTS recommended (`cd frontend && nvm use`); supported range is Node.js 20-24. Newer current releases may emit upstream Next/Tailwind deprecation warnings such as `DEP0205` during dev startup.
 - Rust, latest stable
 - Python 3.11+
 - `uv`
@@ -73,7 +75,7 @@ uv sync --group dev
 uv run uvicorn main:app --reload
 ```
 
-The backend creates default local config under `~/.sage/` when needed.
+The backend creates default local config and data under `~/.sage/` when needed.
 
 Optional provider keys can be configured through environment variables or Sage config, for example:
 
@@ -120,30 +122,31 @@ npm run build
 ```text
 Sage/
 ├── backend/                 # FastAPI backend and local knowledge agent services
-│   ├── api/                 # Chat, knowledge, skills, Tomes, and related routes
+│   ├── api/                 # Chat, knowledge, skills, Tomes, generation, audio routes
 │   ├── providers/           # LLM provider abstraction
 │   ├── services/            # Legacy research/PDF services and shared helpers
 │   ├── skills/              # Backend skill registry and built-in skills
 │   ├── store/               # Local knowledge/session data models and SQLite store
 │   ├── pyproject.toml       # uv-managed backend dependencies
 │   └── main.py              # FastAPI application entry point
 ├── frontend/                # Next.js + Tauri frontend
-│   ├── src/app/             # Next.js app shell
-│   ├── src/components/      # Ethereal Console UI components
-│   ├── src/lib/             # Typed API client and frontend utilities
+│   ├── src/app/             # Tome Home app shell and routed views
+│   ├── src/components/      # Ethereal Console / Tome Home UI components
+│   ├── src/lib/             # Typed API client and explicit command routing
 │   └── src-tauri/           # Tauri desktop configuration
 ├── designs/                 # Design references and generated visual artifacts
-├── *.md                     # Product, design, agent, and implementation docs
+├── docs/                    # Product, design, agent onboarding, planning, and archive docs
 └── README.md
 ```
 
 ## Near-Term Roadmap
 
-- Finish replacing old pre-Ethereal UI paths with the Ethereal Console components.
-- 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.
+- Deepen BYOA / bring-your-own-agent support without locking Sage to one provider or orchestration style.
+- Preserve explicit slash-command routing so natural-language chat is not hijacked into generated views.
+- Continue making Tomes first-class across upload, chat, retrieval, history, and generated artifacts.
+- Keep Ethereal Console as the interaction/design direction while Tome Home remains the default UI.
+- Improve generated artifact rendering/export and evaluation coverage for retrieval, grounding, and generation quality.
+- Add explicit migrations for existing local Sage databases as schemas evolve.
 
 ## Contributing
 

diff --git a/SESSION_CONTEXT.md b/SESSION_CONTEXT.md
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,11 @@
+# Sage Docs
+
+Documentation is organized by purpose:
+
+- [`product/`](product/) — product vision and direction.
+- [`design/`](design/) — Ethereal Console/Tome Home design references.
+- [`agents/`](agents/) — fast onboarding context for coding agents plus agent/skill/UI contracts.
+- [`planning/`](planning/) — historical implementation plans and early project checklists.
+- [`archive/`](archive/) — preserved legacy cleanup/reference notes.
+
+For current product truth, start with the root [`README.md`](../README.md) and [`agents/handoff.md`](agents/handoff.md). Historical docs may describe older arXiv-first or implementation-plan states; status notes call that out where relevant.
diff --git a/docs/agents/README.md b/docs/agents/README.md
@@ -0,0 +1,8 @@
+# Sage Agent Docs
+
+Start here when onboarding a coding agent or resuming a Sage implementation session.
+
+- [`handoff.md`](handoff.md) — current product truth, branch context, constraints, and file map.
+- [`skill-spec.md`](skill-spec.md) — backend skill / frontend component contract for BYOA and generated artifact surfaces.
+
+These docs are intentionally operational. Product narrative belongs in [`../product/`](../product/), UI/design references in [`../design/`](../design/), and historical implementation plans in [`../planning/`](../planning/).