From 9ad77e2a8b3c4d3fe55448c978725d72a9d5f0d9 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Tue, 26 May 2026 20:42:35 -0700
Subject: [PATCH 01/10] feat: add local profile setup and settings

---
 README.md                                     |  71 ++++----
 SESSION_CONTEXT.md                            | 156 ------------------
 docs/README.md                                |  11 ++
 .../agent/skill-spec.md                       |  85 ++++++----
 .../archive/legacy-cleanup-plan.md            |   2 +
 DESIGN.md => docs/design/ethereal-console.md  |   4 +-
 .../design/stitch-prompt.md                   |   2 +
 TODO.md => docs/planning/legacy-todo.md       |   2 +
 PLAN.md => docs/planning/phase-1-plan.md      |   6 +-
 docs/planning/session-context.md              |  72 ++++++++
 BRAINSTORM.md => docs/product/vision.md       |   4 +-
 frontend/scripts/test-command-routing.mjs     |   2 +
 frontend/src/app/page.tsx                     |  88 +++++++++-
 frontend/src/components/ProfileSetup.tsx      | 112 +++++++++++++
 frontend/src/components/SettingsPanel.tsx     | 123 ++++++++++++++
 frontend/src/lib/command-routing.ts           |   4 +-
 16 files changed, 508 insertions(+), 236 deletions(-)
 delete mode 100644 SESSION_CONTEXT.md
 create mode 100644 docs/README.md
 rename AGENT_SKILL_SPEC.md => docs/agent/skill-spec.md (81%)
 rename LEGACY_CLEANUP_PLAN.md => docs/archive/legacy-cleanup-plan.md (91%)
 rename DESIGN.md => docs/design/ethereal-console.md (98%)
 rename STITCH_PROMPT.md => docs/design/stitch-prompt.md (96%)
 rename TODO.md => docs/planning/legacy-todo.md (93%)
 rename PLAN.md => docs/planning/phase-1-plan.md (99%)
 create mode 100644 docs/planning/session-context.md
 rename BRAINSTORM.md => docs/product/vision.md (97%)
 create mode 100644 frontend/src/components/ProfileSetup.tsx
 create mode 100644 frontend/src/components/SettingsPanel.tsx

diff --git a/README.md b/README.md
index 1a0daf1..a175fed 100644
--- 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/agent/skill-spec.md`](docs/agent/skill-spec.md): contract between backend skills and frontend UI/components.
+- [`docs/planning/session-context.md`](docs/planning/session-context.md): current project state and next-session context.
+- [`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
 
@@ -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,7 +122,7 @@ 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
@@ -128,22 +130,23 @@ Sage/
 │   ├── 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, 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
deleted file mode 100644
index 7ee8fbf..0000000
--- a/SESSION_CONTEXT.md
+++ /dev/null
@@ -1,156 +0,0 @@
-# Sage — Session Context (April 23, 2026)
-
-> Auto-generated context file for session continuity. Contains full project state, decisions made, and pending work.
-
----
-
-## Project Overview
-
-**Sage** (renamed from "arXivSage") — a local-first desktop knowledge agent. Tauri + Next.js 15 frontend (Tailwind v4), FastAPI backend.
-
-**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).
-
-**Database:** LanceDB (vector-native) — preferred over SQLite+vector hybrid. Supports metadata filtering (e.g., `notebook_id`) and vector search in one system.
-
-**Upload formats:** PDF, plain text, markdown, URLs (Firecrawl/Jina for scraping)
-
----
-
-## 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
-
-Full spec: `DESIGN.md`
-
----
-
-## Component Inventory (15 components)
-
-### ✅ Ethereal Console Components (8) — Production-ready
-
-All follow `DESIGN.md` glassmorphic spec. Used in `page.tsx`.
-
-| Component | File | Description |
-|-----------|------|-------------|
-| **CommandBar** | `CommandBar.tsx` | Pill input bar (600×48px), sparkle icon, provider badge |
-| **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 |
-| **AudioPlayerWidget** | `AudioPlayerWidget.tsx` | Audio controls, gradient progress bar, transcript with word-highlight |
-| **ReportViewWidget** | `ReportViewWidget.tsx` | Markdown report with sidebar TOC, KaTeX math, copy/MD/PDF export |
-| **HistoryPanel** | `HistoryPanel.tsx` | Searchable history with type filter pills, grouped by time |
-| **TomeSelector** | `TomeSelector.tsx` | Tome picker with search, active state, color-coded icons |
-
-### ⚠️ Legacy Components (7) — ALL ORPHANED (not imported anywhere)
-
-| Component | File | Issue | Action |
-|-----------|------|-------|--------|
-| **TomeList** | `TomeList.tsx` | Old UI, but has real API CRUD (`sage-api.ts`) | **Merge API logic into TomeSelector, then delete** |
-| **KeywordSearch** | `KeywordSearch.tsx` | Old blue/white, uses axios | **Delete** |
-| **SearchBar** | `SearchBar.tsx` | Hardcoded colors, redundant (CommandBar replaces) | **Delete** |
-| **TableOfContents** | `TableOfContents.tsx` | Hardcoded `text-white` | **Delete** (ReportViewWidget has its own TOC) |
-| **Feed** | `Feed.tsx` | Old gray-900 cards | **Delete** |
-| **Post** | `Post.tsx` | Old gray-900 cards with Like/Comment | **Delete** |
-| **LoadingSpinner** | `LoadingSpinner.tsx` | Hardcoded blue-400 | **Delete** |
-
----
-
-## Pending Work: Legacy Cleanup
-
-### Step 1: Merge TomeList API logic into TomeSelector
-
-**What TomeList has that TomeSelector doesn't:**
-- Real API integration: `listTomes()`, `createTome()`, `deleteTome()` from `sage-api.ts`
-- State management: `useEffect` to fetch on mount, `useState` for tomes array
-- Create Tome flow: inline form with name + description inputs
-- Delete Tome: with confirmation via stopPropagation
-- Loading state
-
-**What TomeSelector has that TomeList doesn't:**
-- Ethereal Console glassmorphic design (640px card, backdrop-blur, design tokens)
-- Search/filter functionality
-- Color-coded tome icons (hardcoded per-tome colors like `bg-blue-500/15`)
-- Active state indicator
-- "New Tome" button (decorative — no onClick handler yet)
-
-**Merge plan:**
-1. Add `useEffect` to fetch real tomes on mount
-2. Wire up "New Tome" button → inline create form (name + description)
-3. Wire up delete (✕ icon with stopPropagation)
-4. Add loading state
-5. Keep TomeSelector's search, color-coded icons, glassmorphic design
-
-**Open question:** How to handle per-tome colors?
-- Currently sample data has hardcoded colors (`bg-blue-500/15`, `bg-emerald-500/15`, etc.)
-- Real API tomes don't have a color field
-- Options: (1) rotate through a palette dynamically, (2) drop colors, (3) add color to API
-
-### Step 2: Delete all 7 legacy files
-
-```bash
-rm frontend/src/components/TomeList.tsx
-rm frontend/src/components/KeywordSearch.tsx
-rm frontend/src/components/SearchBar.tsx
-rm frontend/src/components/TableOfContents.tsx
-rm frontend/src/components/Feed.tsx
-rm frontend/src/components/Post.tsx
-rm frontend/src/components/LoadingSpinner.tsx
-```
-
-### Step 3: Verify
-
-- Run `npm run build` to catch any broken imports
-- Confirm `sage-api.ts` exports are intact
-
----
-
-## Agent Skill Spec
-
-Full spec written at `AGENT_SKILL_SPEC.md` (632 lines). Covers:
-- `SkillResult` contract (`ui_component` + `data` → frontend dispatch)
-- 10 skill definitions with YAML schemas and TypeScript prop interfaces
-- Interaction flow diagrams
-- Pending work (AudioPlayerWidget needs real `<audio>`, ChatWidget needs streaming, backend integration)
-
----
-
-## Tech Stack
-
-- **Frontend:** Next.js 15 + Tailwind v4 + shadcn/ui + Framer Motion + Material Symbols
-- **Backend:** FastAPI + uv (pyproject.toml + uv.lock)
-- **Database:** LanceDB
-- **Desktop:** Tauri
-- **Font:** Inter
-- **Tests:** pytest (41 tests) + GitHub Actions CI
-
-## Key Conventions
-
-- Tailwind v4: tokens go in `@theme` block in `globals.css`, NOT `tailwind.config.js`
-- No `--turbopack` (`.next` cache corruption risk)
-- Parent flex containers need `w-full`
-- CSS: use `surface-container` contrast instead of dividers
-- Primary color `#adc6ff` used sparingly ("laser pointer, not paint bucket")
-- All components use `"use client"` (Next.js app router)
-
----
-
-## Git State
-
-~12+ commits ahead of origin. Last commit: `feat: History, TomeSelector, ChatWidget + Report KaTeX fix`
-
----
-
-## What's Next (After Legacy Cleanup)
-
-| Priority | Item |
-|----------|------|
-| 🔴 | **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** |
-| 🟢 | **ComparisonWidget** / **TimelineWidget** — future dedicated components |
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..e96ec99
--- /dev/null
+++ 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.
+- [`agent/`](agent/) — agent, skill, and UI contract docs.
+- [`planning/`](planning/) — current session context and historical implementation plans.
+- [`archive/`](archive/) — preserved legacy cleanup/reference notes.
+
+For current product truth, start with the root [`README.md`](../README.md) and [`planning/session-context.md`](planning/session-context.md). Historical docs may describe older arXiv-first or implementation-plan states; status notes call that out where relevant.
diff --git a/AGENT_SKILL_SPEC.md b/docs/agent/skill-spec.md
similarity index 81%
rename from AGENT_SKILL_SPEC.md
rename to docs/agent/skill-spec.md
index c1b688a..ad2b9a1 100644
--- a/AGENT_SKILL_SPEC.md
+++ b/docs/agent/skill-spec.md
@@ -1,13 +1,31 @@
 # Sage Agent Skill Specification
 
-> The contract between backend skills and frontend UI components.
-> Each skill produces a `SkillResult` with a `ui_component` field that tells the frontend which card to render.
+> The contract between backend skills and frontend UI/components.
+> Product truth: Tome Home is the default UI, ordinary questions stay in chat, and only explicit slash commands / first-party capability chips route to generated views.
 
 ---
 
 ## 1. Architecture Overview
 
+Sage's current implementation is a hybrid of direct routed UI views and backend skills. The next likely roadmap is deeper BYOA / bring-your-own-agent integration, where an external or local agent can call Sage-provided skills while Sage keeps control of source access, grounding, and UI rendering.
+
+```text
+Tome Home / Chat input
+        ↓
+Explicit command routing (`frontend/src/lib/command-routing.ts`)
+        ↓                         ↘
+Focused UI view               Chat / agent loop
+        ↓                         ↓
+Frontend API client       Backend skill registry
+        ↓                         ↓
+Generated artifact        SkillResult / structured data
+        ↓                         ↓
+Ethereal/Tome Home UI renders grounded output
 ```
+
+Historical/target agent loop:
+
+```text
 User Query → Agent Orchestrator → LLM selects tool → Skill executes → SkillResult
                                                                     ↓
                                                          ┌─────────────────────┐
@@ -17,7 +35,7 @@ User Query → Agent Orchestrator → LLM selects tool → Skill executes → Sk
                                                          └──────────┬──────────┘
                                                                     ↓
                                                          Frontend renders the
-                                                         matching React card
+                                                         matching React card/view
 ```
 
 ### SkillResult Contract
@@ -56,40 +74,43 @@ When a `SkillResult` arrives:
 
 ## 2. Component Inventory
 
-### 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. |
-| 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). |
-| 5 | **AudioPlayerWidget** | `AudioPlayerWidget.tsx` | ✅ Ready | Audio controls, gradient progress bar, transcript with word-highlight. |
-| 6 | **ReportViewWidget** | `ReportViewWidget.tsx` | ✅ Ready | Markdown report with sidebar TOC, KaTeX math, copy/MD/PDF export. |
-| 7 | **HistoryPanel** | `HistoryPanel.tsx` | ✅ Ready | Searchable history with type filter pills, grouped by time. |
-| 8 | **TomeSelector** | `TomeSelector.tsx` | ✅ Ready | Tome picker with search, active state, color-coded icons. |
-
-### 2.2 Legacy Components (pre-Ethereal design ⚠️)
-
-These 7 components use the old design system (hardcoded `gray-900`, `blue-500`, `text-white`). They work but don't match the Ethereal Console aesthetic.
-
-| # | Component | File | Status | Description |
-|---|-----------|------|--------|-------------|
-| 9 | **TomeList** | `TomeList.tsx` | ⚠️ Legacy | Older tome manager with real API integration (`sage-api.ts`). **Superseded by TomeSelector** for UI, but has working CRUD. Needs merge. |
-| 10 | **KeywordSearch** | `KeywordSearch.tsx` | ⚠️ Legacy | Keyword search → backend summarize endpoint. Uses axios. Old blue/white styling. |
-| 11 | **SearchBar** | `SearchBar.tsx` | ⚠️ Legacy | Generic search input with `minimal` mode. Hardcoded `gray-900`/`blue-600`. |
-| 12 | **TableOfContents** | `TableOfContents.tsx` | ⚠️ Legacy | Simple TOC sidebar for papers. Hardcoded `text-white`/`text-blue-400`. |
-| 13 | **Feed** | `Feed.tsx` | ⚠️ Legacy | Paper feed with IntersectionObserver tracking. Generic styling. |
-| 14 | **Post** | `Post.tsx` | ⚠️ Legacy | Paper card with author avatar, markdown summary, Like/Comment actions. |
-| 15 | **LoadingSpinner** | `LoadingSpinner.tsx` | ⚠️ Legacy | Simple spinner + message. Hardcoded `blue-400`/`gray-300`. |
+### 2.1 Current Tome Home / Ethereal Components
+
+These components are the current user-facing direction. Tome Home (`frontend/src/app/page.tsx`) routes to focused views directly; backend skills should target these surfaces rather than the old arXiv feed.
+
+| Component | File | Current role |
+|-----------|------|--------------|
+| **Tome Home shell** | `frontend/src/app/page.tsx` | Default UI, capability chips, explicit routing, top-level navigation. |
+| **KnowledgeBaseWidget** | `KnowledgeBaseWidget.tsx` | Sources/documents surface and upload entry point. |
+| **TomeSelector** | `TomeSelector.tsx` | Tome selection/management surface. |
+| **ChatWidget** | `ChatWidget.tsx` | Natural-language chat surface; can hand explicit slash commands back to router. |
+| **QuizView / QuizWidget** | `QuizView.tsx`, `QuizWidget.tsx` | Generated quiz artifact view and interactive card component. |
+| **FlashcardsView / FlashcardWidget** | `FlashcardsView.tsx`, `FlashcardWidget.tsx` | Generated flashcard artifact view and card component. |
+| **AudioView / AudioPlayerWidget** | `AudioView.tsx`, `AudioPlayerWidget.tsx` | Generated audio review/narration view and player component. |
+| **ReportView / ReportViewWidget** | `ReportView.tsx`, `ReportViewWidget.tsx` | Generated report artifact view and markdown/report component. |
+| **HistoryPanel** | `HistoryPanel.tsx` | History surface. |
+| **UploadModal** | `UploadModal.tsx` | Source upload modal. |
+| **CommandBar** | `CommandBar.tsx` | Earlier compact command bar component; still aligned with Ethereal Console direction. |
+
+### 2.2 Legacy Components (pre-Ethereal / arXiv-feed design ⚠️)
+
+These components exist in the tree but are not the current product center. Do not treat them as the target architecture.
+
+| Component | File | Status | Description |
+|-----------|------|--------|-------------|
+| **TomeList** | `TomeList.tsx` | ⚠️ Legacy | Older tome manager with real API integration (`sage-api.ts`). Superseded visually by TomeSelector. |
+| **KeywordSearch** | `KeywordSearch.tsx` | ⚠️ Legacy | Keyword search → backend summarize endpoint. Uses old styling. |
+| **SearchBar** | `SearchBar.tsx` | ⚠️ Legacy | Generic old search input. |
+| **TableOfContents** | `TableOfContents.tsx` | ⚠️ Legacy | Simple old paper TOC. |
+| **Feed** | `Feed.tsx` | ⚠️ Legacy | Old paper feed. |
+| **Post** | `Post.tsx` | ⚠️ Legacy | Old paper/social post card. |
+| **LoadingSpinner** | `LoadingSpinner.tsx` | ⚠️ Legacy | Old spinner styling. |
 
 ---
 
 ## 3. Skill-to-Component Mapping
 
-Each skill below defines its `ui_component` and the `data` schema it passes.
+Each skill below defines its `ui_component` and the `data` schema it passes. The names are a target contract for BYOA/agent integration; the current frontend may wrap these widgets in routed `*View` components.
 
 ### 3.1 `search_docs`
 
diff --git a/LEGACY_CLEANUP_PLAN.md b/docs/archive/legacy-cleanup-plan.md
similarity index 91%
rename from LEGACY_CLEANUP_PLAN.md
rename to docs/archive/legacy-cleanup-plan.md
index e527949..6bb343f 100644
--- a/LEGACY_CLEANUP_PLAN.md
+++ b/docs/archive/legacy-cleanup-plan.md
@@ -1,5 +1,7 @@
 # Legacy Component Cleanup Plan
 
+> **Archive note (May 2026):** Preserved for reference. This docs branch does not remove application code. Verify imports and current product priorities before acting on any deletion plan.
+
 ## Finding: All 7 legacy components are ORPHANED
 
 None of the legacy components are imported or used in `page.tsx` or anywhere else in the app. They're dead code from the pre-Ethereal architecture.
diff --git a/DESIGN.md b/docs/design/ethereal-console.md
similarity index 98%
rename from DESIGN.md
rename to docs/design/ethereal-console.md
index 546891c..058388c 100644
--- a/DESIGN.md
+++ b/docs/design/ethereal-console.md
@@ -1,7 +1,9 @@
-# DESIGN.md — Sage UI/UX Specification
+# Sage Ethereal Console UI/UX Specification
 
 > Based on Stitch.io output "Ethereal Console" — refined and expanded for implementation.
 
+> **Status note (May 2026):** Ethereal Console remains the design direction, but Tome Home is the current default UI. Apply this spec as a visual/interaction language for Tome Home and focused views rather than replacing the current source-first landing experience.
+
 ---
 
 ## Design Philosophy: "The Ethereal Console"
diff --git a/STITCH_PROMPT.md b/docs/design/stitch-prompt.md
similarity index 96%
rename from STITCH_PROMPT.md
rename to docs/design/stitch-prompt.md
index defc264..aa6d4fd 100644
--- a/STITCH_PROMPT.md
+++ b/docs/design/stitch-prompt.md
@@ -1,5 +1,7 @@
 # Stitch.io Prompt — Sage Floating UI
 
+> **Archive/design reference:** Original prompt for the floating Ethereal Console direction. Tome Home is now the default UI; use this as inspiration, not as current app structure.
+
 Use this as the initial prompt for stitch.io. Paste directly into the tool.
 Adjust based on what Stitch outputs — this is a starting point, iterate from here.
 
diff --git a/TODO.md b/docs/planning/legacy-todo.md
similarity index 93%
rename from TODO.md
rename to docs/planning/legacy-todo.md
index 050a9d5..88a6db2 100644
--- a/TODO.md
+++ b/docs/planning/legacy-todo.md
@@ -1,5 +1,7 @@
 ## Project Setup
 
+> **Status note (May 2026):** Archived early TODO from the arXivSage / Electron-era project. Sage is now Tauri + Next.js + FastAPI with Tome Home as the default UI. Keep this file for history only.
+
 - [x] **Initialize FastAPI backend**
   - Set up Python environment (`venv`) and install FastAPI, Uvicorn[^1]
   - Create basic "Hello World" API endpoint[^1]
diff --git a/PLAN.md b/docs/planning/phase-1-plan.md
similarity index 99%
rename from PLAN.md
rename to docs/planning/phase-1-plan.md
index 9e98bd8..a106cfc 100644
--- a/PLAN.md
+++ b/docs/planning/phase-1-plan.md
@@ -2,9 +2,11 @@
 
 > **Goal:** Build the foundation: SQLite knowledge store, provider abstraction, agent orchestrator, skill registry, embeddings, and the floating window shell.
 
+> **Status note (May 2026):** Historical implementation plan. The current branch should treat README and [`session-context.md`](session-context.md) as product truth. Do not replay these steps blindly; many files already exist and Tome Home is now the default UI.
+
 > **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:** [`../product/vision.md`](../product/vision.md), [`../design/ethereal-console.md`](../design/ethereal-console.md) — architecture direction and design spec.
 
 ---
 
@@ -344,7 +346,7 @@ git commit -m "feat: SQLite knowledge store (documents, chunks, collections, ses
 
 ## Task 2: Design Tokens — Tailwind Config
 
-**Objective:** Replace the generic Tailwind config with the Sage "Ethereal Console" design tokens from DESIGN.md.
+**Objective:** Replace the generic Tailwind config with the Sage "Ethereal Console" design tokens from [`../design/ethereal-console.md`](../design/ethereal-console.md).
 
 **Files:**
 - Modify: `frontend/tailwind.config.js` (full rewrite)
diff --git a/docs/planning/session-context.md b/docs/planning/session-context.md
new file mode 100644
index 0000000..8526b3a
--- /dev/null
+++ b/docs/planning/session-context.md
@@ -0,0 +1,72 @@
+# Sage — Session Context (May 26, 2026)
+
+> Current product/development context for humans and coding agents. Main at commit `53b83e0` is the source of truth for this branch.
+
+## Current Product Truth
+
+**Sage** is a local-first desktop knowledge agent built with Tauri + Next.js 15 / React 19 / Tailwind v4 and a FastAPI backend.
+
+The product is no longer an arXiv-first social/feed summarizer. Legacy arXiv search and paper summarization endpoints still exist as discovery/import paths, but the center of the product is **user-owned sources organized into Tomes**.
+
+Current default UI: **Tome Home** (`frontend/src/app/page.tsx`). It presents a source-first workspace with capability buttons for Sources, Report, Quiz, Flashcards, Audio, and Chat.
+
+## Important Directional Constraints
+
+- Preserve **Tome Home as the default landing UI**.
+- Preserve the **Ethereal Console** design direction: dark, luminous, desktop-command interface with depth/soft surfaces rather than old blue/white feed UI.
+- Preserve **explicit slash-command routing**. `frontend/src/lib/command-routing.ts` intentionally routes only slash commands and first-party capability chip prompts; natural-language questions should stay in chat.
+- Next likely roadmap: **BYOA / bring-your-own-agent integration**, while keeping provider flexibility and local-first storage.
+- Keep PR #41 unrelated to this docs housekeeping branch.
+
+## Architecture Snapshot
+
+### Frontend
+
+- `frontend/src/app/page.tsx`: Tome Home app shell, local setup/profile loading, and routed views.
+- `frontend/src/lib/command-routing.ts`: explicit routing for `/quiz`, `/flashcards`, `/audio`, `/report`, `/history`, `/tomes`, `/knowledge`, `/settings`, etc.
+- `frontend/src/lib/user-profile.ts`: local user profile contract and `localStorage` key for owner-specific greetings/settings.
+- `frontend/src/lib/sage-api.ts`: typed API client, browser backend URL, and Tauri sidecar backend startup.
+- Current routed views/components include:
+  - `KnowledgeBaseWidget`
+  - `TomeSelector`
+  - `ChatWidget`
+  - `QuizView` / `QuizWidget`
+  - `FlashcardsView` / `FlashcardWidget`
+  - `AudioView` / `AudioPlayerWidget`
+  - `ReportView` / `ReportViewWidget`
+  - `HistoryPanel`
+  - `ProfileSetup`
+  - `SettingsPanel`
+  - `UploadModal`
+
+### Backend
+
+- `backend/main.py`: FastAPI app setup, Sage routers, legacy arXiv endpoints.
+- `backend/api/`: knowledge, chat, Tomes, skills, generate, audio routes.
+- `backend/store/`: SQLite-backed local knowledge/session store.
+- `backend/skills/`: skill registry plus built-in `search_docs` and `read_document`.
+- `backend/providers/`: provider abstraction direction for local/hosted LLMs.
+- Runtime config/data is created under `~/.sage/` when needed.
+
+## Documentation Map
+
+- Product vision: [`../product/vision.md`](../product/vision.md)
+- UI/design spec: [`../design/ethereal-console.md`](../design/ethereal-console.md)
+- Original Stitch prompt: [`../design/stitch-prompt.md`](../design/stitch-prompt.md)
+- Agent/frontend skill contract: [`../agent/skill-spec.md`](../agent/skill-spec.md)
+- Historical phase plan: [`phase-1-plan.md`](phase-1-plan.md)
+- Early legacy TODO: [`legacy-todo.md`](legacy-todo.md)
+- Archived legacy cleanup notes: [`../archive/legacy-cleanup-plan.md`](../archive/legacy-cleanup-plan.md)
+
+## Known Legacy / Historical Areas
+
+- Old feed-oriented components still exist (`Feed`, `Post`, `KeywordSearch`, `SearchBar`, `TableOfContents`, `LoadingSpinner`, `TomeList`) and are documented in the archive cleanup note. Do not remove them in docs-only work.
+- Some historical docs still contain implementation-plan language from earlier phases. Treat them as planning/archive unless they conflict with this file or README.
+- The backend still includes legacy arXiv summarization paths and DeepSeek-specific service code; describe this as legacy/discovery support, not as the product center.
+
+## Near-Term Follow-Up Notes
+
+1. BYOA/bring-your-own-agent design should clarify provider/tool-call capabilities, local vs hosted execution, and how Sage exposes skills safely.
+2. Tome/source flows should remain first-class across chat, retrieval, generated artifacts, and history.
+3. Generated artifact views need continued grounding/export polish.
+4. Database schema changes should include explicit migration handling for existing `~/.sage/` stores.
diff --git a/BRAINSTORM.md b/docs/product/vision.md
similarity index 97%
rename from BRAINSTORM.md
rename to docs/product/vision.md
index b215255..c735ad5 100644
--- a/BRAINSTORM.md
+++ b/docs/product/vision.md
@@ -2,6 +2,8 @@
 
 > **Goal**: Transform from a RAG-only arXiv summarizer into a local "NotebookLM-like" knowledge app with BYOA (Bring Your Own Agent) and a skill/tool system.
 
+> **Status note (May 2026):** This is a product vision / historical brainstorm, not an exact inventory of the current code. Current truth: Tome Home is the default UI, local SQLite-backed knowledge/Tome APIs exist, arXiv is legacy/discovery support, and the next roadmap emphasis is deeper BYOA while preserving explicit slash-command routing and Ethereal Console direction.
+
 ---
 
 ## Current State (What We Have)
@@ -406,7 +408,7 @@ Eventually users could add custom skills via a simple plugin directory:
 
 ## Layer 4: Frontend UI
 
-> **📋 Full design spec:** See `DESIGN.md` — generated from Stitch.io "Ethereal Console" mockup.
+> **📋 Full design spec:** See [`../design/ethereal-console.md`](../design/ethereal-console.md) — generated from Stitch.io "Ethereal Console" mockup.
 
 ### The Raycast-Style Floating UI
 
diff --git a/frontend/scripts/test-command-routing.mjs b/frontend/scripts/test-command-routing.mjs
index e0a13c0..fba3b39 100644
--- a/frontend/scripts/test-command-routing.mjs
+++ b/frontend/scripts/test-command-routing.mjs
@@ -12,6 +12,8 @@ const routes = [
   ["/tomes", "tomes"],
   ["/knowledge", "knowledge"],
   ["/sources", "knowledge"],
+  ["/settings", "settings"],
+  ["/profile", "settings"],
 ];
 
 for (const [input, expected] of routes) {
diff --git a/frontend/src/app/page.tsx b/frontend/src/app/page.tsx
index 49bda4c..9d81f64 100644
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import type { FormEvent, KeyboardEvent, ReactNode } from "react";
 import { AnimatePresence, motion } from "framer-motion";
 import type { Transition, Variants } from "framer-motion";
@@ -9,13 +9,17 @@ import ChatWidget from "@/components/ChatWidget";
 import FlashcardsView from "@/components/FlashcardsView";
 import HistoryPanel from "@/components/HistoryPanel";
 import KnowledgeBaseWidget from "@/components/KnowledgeBaseWidget";
+import ProfileSetup from "@/components/ProfileSetup";
 import QuizView from "@/components/QuizView";
 import ReportView from "@/components/ReportView";
+import SettingsPanel from "@/components/SettingsPanel";
 import TomeSelector from "@/components/TomeSelector";
 import { detectView } from "@/lib/command-routing";
 import type { RoutedView } from "@/lib/command-routing";
+import { isCompleteUserProfile, USER_PROFILE_STORAGE_KEY } from "@/lib/user-profile";
+import type { SageUserProfile } from "@/lib/user-profile";
 
-type ViewState = "idle" | "dashboard" | "chat" | RoutedView;
+type ViewState = "idle" | "dashboard" | "chat" | "settings" | RoutedView;
 
 const generatedViews = new Set<ViewState>(["quiz", "flashcards", "audio", "report"]);
 
@@ -32,6 +36,33 @@ export default function Home() {
   const [viewState, setViewState] = useState<ViewState>("idle");
   const [generationPrompt, setGenerationPrompt] = useState<string>("");
   const [chatQuery, setChatQuery] = useState<string>("");
+  const [profile, setProfile] = useState<SageUserProfile | null>(null);
+  const [profileLoaded, setProfileLoaded] = useState(false);
+
+  useEffect(() => {
+    const storedProfile = window.localStorage.getItem(USER_PROFILE_STORAGE_KEY);
+    if (storedProfile) {
+      try {
+        const parsedProfile = JSON.parse(storedProfile) as SageUserProfile;
+        if (isCompleteUserProfile(parsedProfile)) {
+          setProfile(parsedProfile);
+        }
+      } catch {
+        window.localStorage.removeItem(USER_PROFILE_STORAGE_KEY);
+      }
+    }
+    setProfileLoaded(true);
+  }, []);
+
+  const saveProfile = (nextProfile: SageUserProfile) => {
+    window.localStorage.setItem(USER_PROFILE_STORAGE_KEY, JSON.stringify(nextProfile));
+    setProfile(nextProfile);
+  };
+
+  const completeSetup = (nextProfile: SageUserProfile) => {
+    saveProfile(nextProfile);
+    setViewState("idle");
+  };
 
   const handleSubmit = (text: string) => {
     const route = detectView(text);
@@ -69,17 +100,33 @@ export default function Home() {
 
   const cardTransition: Transition = { duration: 0.28, ease: [0.25, 0.46, 0.45, 0.94] };
 
+  if (!profileLoaded) {
+    return <main className="min-h-screen w-full bg-[#080807]" />;
+  }
+
+  if (!profile) {
+    return (
+      <main className="relative min-h-screen w-full overflow-hidden bg-[#080807] text-[#ede6d5]">
+        <div className="pointer-events-none absolute inset-x-0 top-[-12rem] h-[36rem] bg-[radial-gradient(circle_at_center,rgba(242,168,93,0.12),transparent_62%)]" />
+        <div className="pointer-events-none absolute right-[-12rem] top-16 h-[32rem] w-[32rem] rounded-full bg-[rgba(171,199,173,0.07)] blur-[110px]" />
+        <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 py-8 sm:px-8 lg:px-10">
+          <ProfileSetup onComplete={completeSetup} />
+        </div>
+      </main>
+    );
+  }
+
   return (
     <main className="relative min-h-screen w-full overflow-hidden bg-[#080807] text-[#ede6d5]">
       <div className="pointer-events-none absolute inset-x-0 top-[-12rem] h-[36rem] bg-[radial-gradient(circle_at_center,rgba(242,168,93,0.12),transparent_62%)]" />
       <div className="pointer-events-none absolute right-[-12rem] top-16 h-[32rem] w-[32rem] rounded-full bg-[rgba(171,199,173,0.07)] blur-[110px]" />
       <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 py-8 sm:px-8 lg:px-10">
-        <TopBar viewState={viewState} onNavigate={setViewState} />
+        <TopBar viewState={viewState} profile={profile} onNavigate={setViewState} />
 
         <AnimatePresence mode="wait">
           {viewState === "idle" && (
             <motion.div key="home" {...cardVariants} transition={cardTransition} className="w-full flex-1">
-              <TomeHome onSubmit={handleSubmit} onNavigate={setViewState} />
+              <TomeHome profile={profile} onSubmit={handleSubmit} onNavigate={setViewState} />
             </motion.div>
           )}
 
@@ -136,13 +183,27 @@ export default function Home() {
               <ChatWidget initialQuery={chatQuery} onCommand={handleChatCommand} />
             </FocusShell>
           )}
+
+          {viewState === "settings" && (
+            <FocusShell keyName="settings" variants={cardVariants} transition={cardTransition} onBack={handleBack}>
+              <SettingsPanel profile={profile} onSave={saveProfile} onBack={handleBack} />
+            </FocusShell>
+          )}
         </AnimatePresence>
       </div>
     </main>
   );
 }
 
-function TopBar({ viewState, onNavigate }: { viewState: ViewState; onNavigate: (view: ViewState) => void }) {
+function TopBar({
+  viewState,
+  profile,
+  onNavigate,
+}: {
+  viewState: ViewState;
+  profile: SageUserProfile;
+  onNavigate: (view: ViewState) => void;
+}) {
   return (
     <header className="flex flex-col gap-4 pb-8 sm:flex-row sm:items-center sm:justify-between">
       <button
@@ -152,7 +213,7 @@ function TopBar({ viewState, onNavigate }: { viewState: ViewState; onNavigate: (
         <span className="grid h-8 w-8 place-items-center rounded-full border border-[#f2a85d]/20 bg-[#f2a85d]/10 text-[#f2a85d]">
           ✦
         </span>
-        <span>Sage · Tome Home</span>
+        <span>Sage · {profile.name}</span>
       </button>
 
       <nav className="flex w-full gap-1 overflow-x-auto rounded-full border border-white/10 bg-[#11110f]/70 p-1 backdrop-blur sm:w-fit">
@@ -160,12 +221,21 @@ function TopBar({ viewState, onNavigate }: { viewState: ViewState; onNavigate: (
         <NavPill active={viewState === "dashboard"} onClick={() => onNavigate("dashboard")}>Dashboard</NavPill>
         <NavPill active={viewState === "history"} onClick={() => onNavigate("history")}>History</NavPill>
         <NavPill active={viewState === "tomes"} onClick={() => onNavigate("tomes")}>Tomes</NavPill>
+        <NavPill active={viewState === "settings"} onClick={() => onNavigate("settings")}>Settings</NavPill>
       </nav>
     </header>
   );
 }
 
-function TomeHome({ onSubmit, onNavigate }: { onSubmit: (text: string) => void; onNavigate: (view: ViewState) => void }) {
+function TomeHome({
+  profile,
+  onSubmit,
+  onNavigate,
+}: {
+  profile: SageUserProfile;
+  onSubmit: (text: string) => void;
+  onNavigate: (view: ViewState) => void;
+}) {
   const [prompt, setPrompt] = useState("");
 
   const submitPrompt = () => {
@@ -196,10 +266,10 @@ function TomeHome({ onSubmit, onNavigate }: { onSubmit: (text: string) => void;
         </div>
 
         <h1 className="font-serif text-[clamp(2.8rem,7vw,5.4rem)] font-normal leading-[0.96] tracking-[-0.05em]">
-          What should this Tome help with next?
+          Welcome back, {profile.name}.
         </h1>
         <p className="mx-auto mt-5 max-w-[650px] text-base leading-7 text-[#9f9788]">
-          Ask questions, generate study materials, manage sources, or jump into focused work for this Tome.
+          What should this Tome help with next? Ask questions, generate study materials, manage sources, or jump into focused work.
         </p>
 
         <button
diff --git a/frontend/src/components/ProfileSetup.tsx b/frontend/src/components/ProfileSetup.tsx
new file mode 100644
index 0000000..c1acbd2
--- /dev/null
+++ b/frontend/src/components/ProfileSetup.tsx
@@ -0,0 +1,112 @@
+"use client";
+
+import { useState } from "react";
+import type { FormEvent } from "react";
+import type { SageUserProfile } from "@/lib/user-profile";
+import { normalizeUserProfile } from "@/lib/user-profile";
+
+interface ProfileSetupProps {
+  onComplete: (profile: SageUserProfile) => void;
+}
+
+export default function ProfileSetup({ onComplete }: ProfileSetupProps) {
+  const [name, setName] = useState("");
+  const [role, setRole] = useState("");
+  const [interests, setInterests] = useState("");
+  const [preferredProvider, setPreferredProvider] = useState("");
+  const [touched, setTouched] = useState(false);
+
+  const nameIsMissing = touched && !name.trim();
+
+  const handleSubmit = (event: FormEvent) => {
+    event.preventDefault();
+    setTouched(true);
+    if (!name.trim()) return;
+
+    onComplete(
+      normalizeUserProfile({
+        name,
+        role,
+        interests,
+        preferredProvider,
+        updatedAt: new Date().toISOString(),
+      }),
+    );
+  };
+
+  return (
+    <section className="grid min-h-[calc(100vh-8rem)] place-items-center pb-16 pt-4">
+      <form
+        onSubmit={handleSubmit}
+        className="w-full max-w-[720px] rounded-[32px] border border-white/10 bg-gradient-to-b from-[#1f1d18]/95 to-[#11100e]/95 p-6 text-left shadow-[0_30px_90px_rgba(0,0,0,0.42),inset_0_1px_0_rgba(255,255,255,0.045)] sm:p-8"
+      >
+        <div className="mb-6 text-center">
+          <div className="mb-4 inline-flex items-center gap-2 rounded-full border border-[#f2a85d]/20 bg-[#f2a85d]/10 px-3 py-1 text-sm text-[#d8b978]">
+            ✦ Local setup
+          </div>
+          <h1 className="font-serif text-[clamp(2.4rem,6vw,4.6rem)] font-normal leading-[0.96] tracking-[-0.05em] text-[#ede6d5]">
+            Make Sage yours.
+          </h1>
+          <p className="mx-auto mt-4 max-w-[560px] text-sm leading-6 text-[#9f9788]">
+            This profile stays in this device&apos;s local browser storage and only personalizes the Tome Home greeting and settings surface for now.
+          </p>
+        </div>
+
+        <div className="grid gap-4">
+          <label className="grid gap-2">
+            <span className="text-sm text-[#ede6d5]">Your name</span>
+            <input
+              value={name}
+              onChange={(event) => setName(event.target.value)}
+              onBlur={() => setTouched(true)}
+              placeholder="e.g. Zeap"
+              className="h-12 rounded-2xl border border-white/10 bg-black/20 px-4 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+              autoFocus
+            />
+            {nameIsMissing && <span className="text-sm text-[#ffb4ab]">Sage needs a name for the greeting.</span>}
+          </label>
+
+          <label className="grid gap-2">
+            <span className="text-sm text-[#ede6d5]">Role or context</span>
+            <input
+              value={role}
+              onChange={(event) => setRole(event.target.value)}
+              placeholder="Researcher, student, builder…"
+              className="h-12 rounded-2xl border border-white/10 bg-black/20 px-4 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+            />
+          </label>
+
+          <label className="grid gap-2">
+            <span className="text-sm text-[#ede6d5]">Interests or working notes</span>
+            <textarea
+              value={interests}
+              onChange={(event) => setInterests(event.target.value)}
+              placeholder="What should Sage keep in mind when helping you?"
+              className="min-h-24 resize-none rounded-2xl border border-white/10 bg-black/20 px-4 py-3 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+            />
+          </label>
+
+          <label className="grid gap-2">
+            <span className="text-sm text-[#ede6d5]">Preferred agent/provider</span>
+            <input
+              value={preferredProvider}
+              onChange={(event) => setPreferredProvider(event.target.value)}
+              placeholder="Ollama, OpenAI-compatible, Anthropic…"
+              className="h-12 rounded-2xl border border-white/10 bg-black/20 px-4 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+            />
+          </label>
+        </div>
+
+        <div className="mt-6 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <p className="text-sm leading-6 text-[#6f675b]">Editable later from Settings. No backend account is created.</p>
+          <button
+            type="submit"
+            className="rounded-full border border-[#f2a85d]/25 bg-[#f2a85d]/10 px-5 py-2.5 text-sm font-medium text-[#ede6d5] transition-colors hover:bg-[#f2a85d]/20"
+          >
+            Continue to Tome Home →
+          </button>
+        </div>
+      </form>
+    </section>
+  );
+}
diff --git a/frontend/src/components/SettingsPanel.tsx b/frontend/src/components/SettingsPanel.tsx
new file mode 100644
index 0000000..05ea898
--- /dev/null
+++ b/frontend/src/components/SettingsPanel.tsx
@@ -0,0 +1,123 @@
+"use client";
+
+import { useState } from "react";
+import type { FormEvent } from "react";
+import type { SageUserProfile } from "@/lib/user-profile";
+import { normalizeUserProfile } from "@/lib/user-profile";
+
+interface SettingsPanelProps {
+  profile: SageUserProfile;
+  onSave: (profile: SageUserProfile) => void;
+  onBack: () => void;
+}
+
+export default function SettingsPanel({ profile, onSave, onBack }: SettingsPanelProps) {
+  const [name, setName] = useState(profile.name);
+  const [role, setRole] = useState(profile.role ?? "");
+  const [interests, setInterests] = useState(profile.interests ?? "");
+  const [preferredProvider, setPreferredProvider] = useState(profile.preferredProvider ?? "");
+  const [saved, setSaved] = useState(false);
+
+  const handleSubmit = (event: FormEvent) => {
+    event.preventDefault();
+    if (!name.trim()) return;
+
+    onSave(
+      normalizeUserProfile({
+        name,
+        role,
+        interests,
+        preferredProvider,
+        updatedAt: new Date().toISOString(),
+      }),
+    );
+    setSaved(true);
+  };
+
+  return (
+    <section className="w-full max-w-[760px] rounded-[30px] border border-white/10 bg-gradient-to-b from-[#1f1d18]/95 to-[#11100e]/95 p-6 text-left shadow-[0_30px_90px_rgba(0,0,0,0.42),inset_0_1px_0_rgba(255,255,255,0.045)] sm:p-8">
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between">
+        <div>
+          <p className="text-sm text-[#9f9788]">Local profile</p>
+          <h1 className="mt-1 text-3xl font-medium tracking-[-0.04em] text-[#ede6d5]">Settings</h1>
+          <p className="mt-3 max-w-[560px] text-sm leading-6 text-[#9f9788]">
+            Edit the personal details Sage keeps on this device for greetings and future agent/provider personalization.
+          </p>
+        </div>
+        <button
+          type="button"
+          onClick={onBack}
+          className="w-fit rounded-full border border-white/10 px-3 py-1.5 text-sm text-[#9f9788] transition-colors hover:border-[#f2a85d]/30 hover:text-[#ede6d5]"
+        >
+          Back to Tome Home
+        </button>
+      </div>
+
+      <form onSubmit={handleSubmit} className="mt-6 grid gap-4">
+        <label className="grid gap-2">
+          <span className="text-sm text-[#ede6d5]">Your name</span>
+          <input
+            value={name}
+            onChange={(event) => {
+              setName(event.target.value);
+              setSaved(false);
+            }}
+            className="h-12 rounded-2xl border border-white/10 bg-black/20 px-4 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+          />
+        </label>
+
+        <label className="grid gap-2">
+          <span className="text-sm text-[#ede6d5]">Role or context</span>
+          <input
+            value={role}
+            onChange={(event) => {
+              setRole(event.target.value);
+              setSaved(false);
+            }}
+            className="h-12 rounded-2xl border border-white/10 bg-black/20 px-4 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+          />
+        </label>
+
+        <label className="grid gap-2">
+          <span className="text-sm text-[#ede6d5]">Interests or working notes</span>
+          <textarea
+            value={interests}
+            onChange={(event) => {
+              setInterests(event.target.value);
+              setSaved(false);
+            }}
+            className="min-h-28 resize-none rounded-2xl border border-white/10 bg-black/20 px-4 py-3 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+          />
+        </label>
+
+        <label className="grid gap-2">
+          <span className="text-sm text-[#ede6d5]">Preferred agent/provider</span>
+          <input
+            value={preferredProvider}
+            onChange={(event) => {
+              setPreferredProvider(event.target.value);
+              setSaved(false);
+            }}
+            className="h-12 rounded-2xl border border-white/10 bg-black/20 px-4 text-[#ede6d5] outline-none placeholder:text-[#70695e] focus:border-[#f2a85d]/35"
+          />
+        </label>
+
+        <div className="flex flex-col gap-3 pt-2 sm:flex-row sm:items-center sm:justify-between">
+          <p className="text-sm text-[#6f675b]">
+            Stored as <code className="text-[#9f9788]">sage:user-profile:v1</code> in localStorage.
+          </p>
+          <div className="flex items-center gap-3">
+            {saved && <span className="text-sm text-[#abc7ad]">Saved locally.</span>}
+            <button
+              type="submit"
+              className="rounded-full border border-[#f2a85d]/25 bg-[#f2a85d]/10 px-5 py-2.5 text-sm font-medium text-[#ede6d5] transition-colors hover:bg-[#f2a85d]/20 disabled:cursor-not-allowed disabled:opacity-50"
+              disabled={!name.trim()}
+            >
+              Save settings
+            </button>
+          </div>
+        </div>
+      </form>
+    </section>
+  );
+}
diff --git a/frontend/src/lib/command-routing.ts b/frontend/src/lib/command-routing.ts
index 1434759..9c259a0 100644
--- a/frontend/src/lib/command-routing.ts
+++ b/frontend/src/lib/command-routing.ts
@@ -1,4 +1,4 @@
-export type RoutedView = "quiz" | "flashcards" | "audio" | "report" | "history" | "tomes" | "knowledge";
+export type RoutedView = "quiz" | "flashcards" | "audio" | "report" | "history" | "tomes" | "knowledge" | "settings";
 
 const slashCommands: Record<string, RoutedView> = {
   "/quiz": "quiz",
@@ -16,6 +16,8 @@ const slashCommands: Record<string, RoutedView> = {
   "/knowledge": "knowledge",
   "/sources": "knowledge",
   "/docs": "knowledge",
+  "/settings": "settings",
+  "/profile": "settings",
 };
 
 const chipPrompts: Record<string, RoutedView> = {

From 2bb8ffccc0309d422497deec88320049e1868525 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Tue, 26 May 2026 20:44:54 -0700
Subject: [PATCH 02/10] fix: track local profile utilities

---
 frontend/src/lib/user-profile.ts | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 frontend/src/lib/user-profile.ts

diff --git a/frontend/src/lib/user-profile.ts b/frontend/src/lib/user-profile.ts
new file mode 100644
index 0000000..4cc95ff
--- /dev/null
+++ b/frontend/src/lib/user-profile.ts
@@ -0,0 +1,23 @@
+export interface SageUserProfile {
+  name: string;
+  role?: string;
+  interests?: string;
+  preferredProvider?: string;
+  updatedAt: string;
+}
+
+export const USER_PROFILE_STORAGE_KEY = "sage:user-profile:v1";
+
+export function normalizeUserProfile(profile: SageUserProfile): SageUserProfile {
+  return {
+    ...profile,
+    name: profile.name.trim(),
+    role: profile.role?.trim() || undefined,
+    interests: profile.interests?.trim() || undefined,
+    preferredProvider: profile.preferredProvider?.trim() || undefined,
+  };
+}
+
+export function isCompleteUserProfile(profile: SageUserProfile | null): profile is SageUserProfile {
+  return Boolean(profile?.name.trim());
+}

From 0f8250e3638fadf7547107758e11fc4db1b18ae6 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Tue, 26 May 2026 21:06:09 -0700
Subject: [PATCH 03/10] Fix Tauri config schema

---
 frontend/src-tauri/tauri.conf.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/frontend/src-tauri/tauri.conf.json b/frontend/src-tauri/tauri.conf.json
index 8013a44..2a7b50c 100644
--- a/frontend/src-tauri/tauri.conf.json
+++ b/frontend/src-tauri/tauri.conf.json
@@ -42,7 +42,6 @@
       "icons/icon.icns",
       "icons/icon.ico"
     ],
-    "identifier": "com.sage.desktop",
     "externalBin": ["binaries/main"]
   },
   "plugins": {

From 23edf2b1a2879523d70fcbc6ea365f9f2c255b73 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Tue, 26 May 2026 21:13:30 -0700
Subject: [PATCH 04/10] test: cover local profile persistence

---
 frontend/package.json                  |  3 +-
 frontend/scripts/test-user-profile.mjs | 59 ++++++++++++++++++++++++++
 frontend/src/app/page.tsx              | 13 ++----
 frontend/src/lib/user-profile.ts       | 15 +++++++
 4 files changed, 79 insertions(+), 11 deletions(-)
 create mode 100644 frontend/scripts/test-user-profile.mjs

diff --git a/frontend/package.json b/frontend/package.json
index d618159..1df4d82 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -9,7 +9,8 @@
     "lint": "next lint",
     "test:routing": "node scripts/test-command-routing.mjs",
     "test:api-client": "node scripts/test-sage-api.mjs",
-    "test:smoke": "npm run test:routing && npm run test:api-client",
+    "test:profile": "node scripts/test-user-profile.mjs",
+    "test:smoke": "npm run test:routing && npm run test:api-client && npm run test:profile",
     "tauri": "tauri",
     "tauri:dev": "tauri dev",
     "tauri:build": "tauri build"
diff --git a/frontend/scripts/test-user-profile.mjs b/frontend/scripts/test-user-profile.mjs
new file mode 100644
index 0000000..7b9c6a9
--- /dev/null
+++ b/frontend/scripts/test-user-profile.mjs
@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import {
+  normalizeUserProfile,
+  readStoredUserProfile,
+  USER_PROFILE_STORAGE_KEY,
+} from "../src/lib/user-profile.ts";
+
+const normalized = normalizeUserProfile({
+  name: "  Ada  ",
+  role: "  researcher  ",
+  interests: "  ",
+  preferredProvider: "  local-agent  ",
+  updatedAt: "2026-05-27T00:00:00.000Z",
+});
+
+assert.deepEqual(normalized, {
+  name: "Ada",
+  role: "researcher",
+  interests: undefined,
+  preferredProvider: "local-agent",
+  updatedAt: "2026-05-27T00:00:00.000Z",
+});
+
+function createStorage(initialValue) {
+  let value = initialValue;
+  let removed = false;
+  return {
+    getItem(key) {
+      assert.equal(key, USER_PROFILE_STORAGE_KEY);
+      return value;
+    },
+    removeItem(key) {
+      assert.equal(key, USER_PROFILE_STORAGE_KEY);
+      removed = true;
+      value = null;
+    },
+    wasRemoved() {
+      return removed;
+    },
+  };
+}
+
+const validStorage = createStorage(
+  JSON.stringify({ name: "Jezelle", updatedAt: "2026-05-27T00:00:00.000Z" }),
+);
+assert.equal(readStoredUserProfile(validStorage)?.name, "Jezelle");
+assert.equal(validStorage.wasRemoved(), false);
+
+const incompleteStorage = createStorage(
+  JSON.stringify({ name: "   ", updatedAt: "2026-05-27T00:00:00.000Z" }),
+);
+assert.equal(readStoredUserProfile(incompleteStorage), null);
+assert.equal(incompleteStorage.wasRemoved(), false);
+
+const corruptStorage = createStorage("not json");
+assert.equal(readStoredUserProfile(corruptStorage), null);
+assert.equal(corruptStorage.wasRemoved(), true);
+
+console.log("user profile tests passed");
\ No newline at end of file
diff --git a/frontend/src/app/page.tsx b/frontend/src/app/page.tsx
index 9d81f64..51d035b 100644
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@@ -16,7 +16,7 @@ import SettingsPanel from "@/components/SettingsPanel";
 import TomeSelector from "@/components/TomeSelector";
 import { detectView } from "@/lib/command-routing";
 import type { RoutedView } from "@/lib/command-routing";
-import { isCompleteUserProfile, USER_PROFILE_STORAGE_KEY } from "@/lib/user-profile";
+import { readStoredUserProfile, USER_PROFILE_STORAGE_KEY } from "@/lib/user-profile";
 import type { SageUserProfile } from "@/lib/user-profile";
 
 type ViewState = "idle" | "dashboard" | "chat" | "settings" | RoutedView;
@@ -40,16 +40,9 @@ export default function Home() {
   const [profileLoaded, setProfileLoaded] = useState(false);
 
   useEffect(() => {
-    const storedProfile = window.localStorage.getItem(USER_PROFILE_STORAGE_KEY);
+    const storedProfile = readStoredUserProfile(window.localStorage);
     if (storedProfile) {
-      try {
-        const parsedProfile = JSON.parse(storedProfile) as SageUserProfile;
-        if (isCompleteUserProfile(parsedProfile)) {
-          setProfile(parsedProfile);
-        }
-      } catch {
-        window.localStorage.removeItem(USER_PROFILE_STORAGE_KEY);
-      }
+      setProfile(storedProfile);
     }
     setProfileLoaded(true);
   }, []);
diff --git a/frontend/src/lib/user-profile.ts b/frontend/src/lib/user-profile.ts
index 4cc95ff..51f00e2 100644
--- a/frontend/src/lib/user-profile.ts
+++ b/frontend/src/lib/user-profile.ts
@@ -8,6 +8,8 @@ export interface SageUserProfile {
 
 export const USER_PROFILE_STORAGE_KEY = "sage:user-profile:v1";
 
+type ProfileStorage = Pick<Storage, "getItem" | "removeItem">;
+
 export function normalizeUserProfile(profile: SageUserProfile): SageUserProfile {
   return {
     ...profile,
@@ -21,3 +23,16 @@ export function normalizeUserProfile(profile: SageUserProfile): SageUserProfile
 export function isCompleteUserProfile(profile: SageUserProfile | null): profile is SageUserProfile {
   return Boolean(profile?.name.trim());
 }
+
+export function readStoredUserProfile(storage: ProfileStorage): SageUserProfile | null {
+  const storedProfile = storage.getItem(USER_PROFILE_STORAGE_KEY);
+  if (!storedProfile) return null;
+
+  try {
+    const parsedProfile = JSON.parse(storedProfile) as SageUserProfile;
+    return isCompleteUserProfile(parsedProfile) ? parsedProfile : null;
+  } catch {
+    storage.removeItem(USER_PROFILE_STORAGE_KEY);
+    return null;
+  }
+}

From 71193bac16f353fa2b8fcce5d512cd31bcd74514 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Wed, 27 May 2026 12:08:54 -0700
Subject: [PATCH 05/10] docs: organize agent context

---
 README.md                                    |  6 +--
 docs/README.md                               |  6 +--
 docs/agents/README.md                        |  8 ++++
 docs/{planning => agents}/session-context.md | 48 +++++++++++++++-----
 docs/{agent => agents}/skill-spec.md         |  2 +
 docs/planning/phase-1-plan.md                |  2 +-
 6 files changed, 54 insertions(+), 18 deletions(-)
 create mode 100644 docs/agents/README.md
 rename docs/{planning => agents}/session-context.md (51%)
 rename docs/{agent => agents}/skill-spec.md (98%)

diff --git a/README.md b/README.md
index a175fed..12e3904 100644
--- a/README.md
+++ b/README.md
@@ -33,8 +33,8 @@ Root-level planning/spec Markdown has been organized under `docs/`:
 - [`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/agent/skill-spec.md`](docs/agent/skill-spec.md): contract between backend skills and frontend UI/components.
-- [`docs/planning/session-context.md`](docs/planning/session-context.md): current project state and next-session context.
+- [`docs/agents/session-context.md`](docs/agents/session-context.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.
@@ -135,7 +135,7 @@ Sage/
 │   ├── src/lib/             # Typed API client and explicit command routing
 │   └── src-tauri/           # Tauri desktop configuration
 ├── designs/                 # Design references and generated visual artifacts
-├── docs/                    # Product, design, agent, planning, and archive docs
+├── docs/                    # Product, design, agent onboarding, planning, and archive docs
 └── README.md
 ```
 
diff --git a/docs/README.md b/docs/README.md
index e96ec99..83928e0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,8 +4,8 @@ Documentation is organized by purpose:
 
 - [`product/`](product/) — product vision and direction.
 - [`design/`](design/) — Ethereal Console/Tome Home design references.
-- [`agent/`](agent/) — agent, skill, and UI contract docs.
-- [`planning/`](planning/) — current session context and historical implementation plans.
+- [`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 [`planning/session-context.md`](planning/session-context.md). Historical docs may describe older arXiv-first or implementation-plan states; status notes call that out where relevant.
+For current product truth, start with the root [`README.md`](../README.md) and [`agents/session-context.md`](agents/session-context.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
new file mode 100644
index 0000000..7008d35
--- /dev/null
+++ 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.
+
+- [`session-context.md`](session-context.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/).
diff --git a/docs/planning/session-context.md b/docs/agents/session-context.md
similarity index 51%
rename from docs/planning/session-context.md
rename to docs/agents/session-context.md
index 8526b3a..dd26d10 100644
--- a/docs/planning/session-context.md
+++ b/docs/agents/session-context.md
@@ -1,6 +1,6 @@
-# Sage — Session Context (May 26, 2026)
+# Sage — Agent Onboarding Context (May 26, 2026)
 
-> Current product/development context for humans and coding agents. Main at commit `53b83e0` is the source of truth for this branch.
+> Fast handoff context for humans and coding agents. Main at commit `53b83e0` is the baseline product truth; this branch layers local owner-profile setup/settings work on top.
 
 ## Current Product Truth
 
@@ -10,11 +10,34 @@ The product is no longer an arXiv-first social/feed summarizer. Legacy arXiv sea
 
 Current default UI: **Tome Home** (`frontend/src/app/page.tsx`). It presents a source-first workspace with capability buttons for Sources, Report, Quiz, Flashcards, Audio, and Chat.
 
+## Current Branch Context
+
+This branch keeps the owner-specific greeting and adds the local profile flow needed to make that greeting work for new users:
+
+- New users see an initial setup flow to enter their name and user-specific details.
+- Profile data lives locally on the user's device via the browser `localStorage` contract in `frontend/src/lib/user-profile.ts`.
+- Returning users keep the owner-specific Tome Home greeting.
+- Users can edit their local profile details from Settings.
+- `ProfileSetup` and `SettingsPanel` are part of the current Tome Home surface, not legacy UI.
+- `/settings` is an explicit slash-command route; natural-language prompts still stay in chat.
+- Local profile persistence has a focused Node test script (`frontend/scripts/test-user-profile.mjs`) wired into `npm test`.
+
+## Completed In This Branch
+
+- Implemented first-run local profile setup and editable settings while preserving the Tome Home default UI.
+- Added a small local profile utility layer for loading, saving, validating, and normalizing owner profile data.
+- Preserved owner-specific default behavior for the existing owner while making new-user setup explicit.
+- Fixed the Tauri config schema issue found during validation.
+- Organized project documentation under `docs/` with purpose-based subdirectories.
+- Moved agent onboarding/contract docs into `docs/agents/` and added `docs/agents/README.md` as the coding-agent entrypoint.
+- Refreshed README/doc links so current product truth points at Tome Home, local-first storage, and the agent onboarding context instead of old root-level or planning paths.
+
 ## Important Directional Constraints
 
 - Preserve **Tome Home as the default landing UI**.
 - Preserve the **Ethereal Console** design direction: dark, luminous, desktop-command interface with depth/soft surfaces rather than old blue/white feed UI.
 - Preserve **explicit slash-command routing**. `frontend/src/lib/command-routing.ts` intentionally routes only slash commands and first-party capability chip prompts; natural-language questions should stay in chat.
+- Preserve owner-specific/local-first behavior: profile details should remain on-device unless a future design explicitly asks otherwise.
 - Next likely roadmap: **BYOA / bring-your-own-agent integration**, while keeping provider flexibility and local-first storage.
 - Keep PR #41 unrelated to this docs housekeeping branch.
 
@@ -22,9 +45,11 @@ Current default UI: **Tome Home** (`frontend/src/app/page.tsx`). It presents a s
 
 ### Frontend
 
-- `frontend/src/app/page.tsx`: Tome Home app shell, local setup/profile loading, and routed views.
+- `frontend/src/app/page.tsx`: Tome Home app shell, local setup/profile loading, owner greeting, and routed views.
 - `frontend/src/lib/command-routing.ts`: explicit routing for `/quiz`, `/flashcards`, `/audio`, `/report`, `/history`, `/tomes`, `/knowledge`, `/settings`, etc.
-- `frontend/src/lib/user-profile.ts`: local user profile contract and `localStorage` key for owner-specific greetings/settings.
+- `frontend/src/lib/user-profile.ts`: local user profile contract, default owner profile, validation/normalization helpers, and `localStorage` key for owner-specific greetings/settings.
+- `frontend/src/components/ProfileSetup.tsx`: first-run local profile setup flow.
+- `frontend/src/components/SettingsPanel.tsx`: editable local profile/settings surface.
 - `frontend/src/lib/sage-api.ts`: typed API client, browser backend URL, and Tauri sidecar backend startup.
 - Current routed views/components include:
   - `KnowledgeBaseWidget`
@@ -53,9 +78,9 @@ Current default UI: **Tome Home** (`frontend/src/app/page.tsx`). It presents a s
 - Product vision: [`../product/vision.md`](../product/vision.md)
 - UI/design spec: [`../design/ethereal-console.md`](../design/ethereal-console.md)
 - Original Stitch prompt: [`../design/stitch-prompt.md`](../design/stitch-prompt.md)
-- Agent/frontend skill contract: [`../agent/skill-spec.md`](../agent/skill-spec.md)
-- Historical phase plan: [`phase-1-plan.md`](phase-1-plan.md)
-- Early legacy TODO: [`legacy-todo.md`](legacy-todo.md)
+- Agent/frontend skill contract: [`skill-spec.md`](skill-spec.md)
+- Historical phase plan: [`../planning/phase-1-plan.md`](../planning/phase-1-plan.md)
+- Early legacy TODO: [`../planning/legacy-todo.md`](../planning/legacy-todo.md)
 - Archived legacy cleanup notes: [`../archive/legacy-cleanup-plan.md`](../archive/legacy-cleanup-plan.md)
 
 ## Known Legacy / Historical Areas
@@ -66,7 +91,8 @@ Current default UI: **Tome Home** (`frontend/src/app/page.tsx`). It presents a s
 
 ## Near-Term Follow-Up Notes
 
-1. BYOA/bring-your-own-agent design should clarify provider/tool-call capabilities, local vs hosted execution, and how Sage exposes skills safely.
-2. Tome/source flows should remain first-class across chat, retrieval, generated artifacts, and history.
-3. Generated artifact views need continued grounding/export polish.
-4. Database schema changes should include explicit migration handling for existing `~/.sage/` stores.
+1. Next MVP step: design and implement BYOA / bring-your-own-agent settings and runtime wiring. Start with a local-first provider configuration surface, then connect it to the existing backend provider abstraction without weakening explicit slash-command routing.
+2. Define the BYOA capability contract: provider/tool-call capabilities, local vs hosted execution, safe skill exposure, and how unavailable capabilities degrade in Tome Home.
+3. Keep Tome/source flows first-class across chat, retrieval, generated artifacts, and history.
+4. Continue grounding/export polish for generated artifact views.
+5. Database schema changes should include explicit migration handling for existing `~/.sage/` stores.
diff --git a/docs/agent/skill-spec.md b/docs/agents/skill-spec.md
similarity index 98%
rename from docs/agent/skill-spec.md
rename to docs/agents/skill-spec.md
index ad2b9a1..d2985c8 100644
--- a/docs/agent/skill-spec.md
+++ b/docs/agents/skill-spec.md
@@ -89,6 +89,8 @@ These components are the current user-facing direction. Tome Home (`frontend/src
 | **AudioView / AudioPlayerWidget** | `AudioView.tsx`, `AudioPlayerWidget.tsx` | Generated audio review/narration view and player component. |
 | **ReportView / ReportViewWidget** | `ReportView.tsx`, `ReportViewWidget.tsx` | Generated report artifact view and markdown/report component. |
 | **HistoryPanel** | `HistoryPanel.tsx` | History surface. |
+| **ProfileSetup** | `ProfileSetup.tsx` | First-run local profile setup for owner-specific greetings and user details. |
+| **SettingsPanel** | `SettingsPanel.tsx` | Editable local profile/settings surface. |
 | **UploadModal** | `UploadModal.tsx` | Source upload modal. |
 | **CommandBar** | `CommandBar.tsx` | Earlier compact command bar component; still aligned with Ethereal Console direction. |
 
diff --git a/docs/planning/phase-1-plan.md b/docs/planning/phase-1-plan.md
index a106cfc..8e3bbfe 100644
--- a/docs/planning/phase-1-plan.md
+++ b/docs/planning/phase-1-plan.md
@@ -2,7 +2,7 @@
 
 > **Goal:** Build the foundation: SQLite knowledge store, provider abstraction, agent orchestrator, skill registry, embeddings, and the floating window shell.
 
-> **Status note (May 2026):** Historical implementation plan. The current branch should treat README and [`session-context.md`](session-context.md) as product truth. Do not replay these steps blindly; many files already exist and Tome Home is now the default UI.
+> **Status note (May 2026):** Historical implementation plan. The current branch should treat README and [`../agents/session-context.md`](../agents/session-context.md) as product truth. Do not replay these steps blindly; many files already exist and Tome Home is now the default UI.
 
 > **For:** Claude Code, Codex, or any coding agent. Follow tasks sequentially. Each task is 2-5 minutes.
 

From 2251fcaf08cda59f996ac72b10c2a722c8841d35 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Wed, 27 May 2026 12:13:00 -0700
Subject: [PATCH 06/10] docs: rename agent handoff context

---
 README.md                                      | 2 +-
 docs/README.md                                 | 2 +-
 docs/agents/README.md                          | 2 +-
 docs/agents/{session-context.md => handoff.md} | 2 +-
 docs/planning/phase-1-plan.md                  | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)
 rename docs/agents/{session-context.md => handoff.md} (99%)

diff --git a/README.md b/README.md
index 12e3904..6e69029 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ Root-level planning/spec Markdown has been organized under `docs/`:
 - [`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/session-context.md`](docs/agents/session-context.md): fast onboarding context for coding agents and future sessions.
+- [`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.
diff --git a/docs/README.md b/docs/README.md
index 83928e0..fb69765 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,4 +8,4 @@ Documentation is organized by purpose:
 - [`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/session-context.md`](agents/session-context.md). Historical docs may describe older arXiv-first or implementation-plan states; status notes call that out where relevant.
+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
index 7008d35..a1ecd64 100644
--- a/docs/agents/README.md
+++ b/docs/agents/README.md
@@ -2,7 +2,7 @@
 
 Start here when onboarding a coding agent or resuming a Sage implementation session.
 
-- [`session-context.md`](session-context.md) — current product truth, branch context, constraints, and file map.
+- [`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/).
diff --git a/docs/agents/session-context.md b/docs/agents/handoff.md
similarity index 99%
rename from docs/agents/session-context.md
rename to docs/agents/handoff.md
index dd26d10..ae68e6e 100644
--- a/docs/agents/session-context.md
+++ b/docs/agents/handoff.md
@@ -1,4 +1,4 @@
-# Sage — Agent Onboarding Context (May 26, 2026)
+# Sage — Agent Handoff (May 26, 2026)
 
 > Fast handoff context for humans and coding agents. Main at commit `53b83e0` is the baseline product truth; this branch layers local owner-profile setup/settings work on top.
 
diff --git a/docs/planning/phase-1-plan.md b/docs/planning/phase-1-plan.md
index 8e3bbfe..5767df1 100644
--- a/docs/planning/phase-1-plan.md
+++ b/docs/planning/phase-1-plan.md
@@ -2,7 +2,7 @@
 
 > **Goal:** Build the foundation: SQLite knowledge store, provider abstraction, agent orchestrator, skill registry, embeddings, and the floating window shell.
 
-> **Status note (May 2026):** Historical implementation plan. The current branch should treat README and [`../agents/session-context.md`](../agents/session-context.md) as product truth. Do not replay these steps blindly; many files already exist and Tome Home is now the default UI.
+> **Status note (May 2026):** Historical implementation plan. The current branch should treat README and [`../agents/handoff.md`](../agents/handoff.md) as product truth. Do not replay these steps blindly; many files already exist and Tome Home is now the default UI.
 
 > **For:** Claude Code, Codex, or any coding agent. Follow tasks sequentially. Each task is 2-5 minutes.
 

From 465c73ae8ce33c46154abac19fcefd6950928760 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Wed, 27 May 2026 12:30:14 -0700
Subject: [PATCH 07/10] fix: enable macOS transparent window support

---
 frontend/src-tauri/tauri.conf.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/frontend/src-tauri/tauri.conf.json b/frontend/src-tauri/tauri.conf.json
index 2a7b50c..dd25400 100644
--- a/frontend/src-tauri/tauri.conf.json
+++ b/frontend/src-tauri/tauri.conf.json
@@ -10,6 +10,7 @@
     "beforeBuildCommand": "npm run build"
   },
   "app": {
+    "macOSPrivateApi": true,
     "windows": [
       {
         "label": "main",

From c5921fe33b9a977666eacc4e2740005ee52ebdfb Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Wed, 27 May 2026 12:44:23 -0700
Subject: [PATCH 08/10] fix: size desktop window for Tome Home

---
 README.md                          |  2 +-
 docs/agents/handoff.md             |  2 ++
 frontend/.nvmrc                    |  1 +
 frontend/package-lock.json         |  3 +++
 frontend/package.json              |  3 +++
 frontend/src-tauri/tauri.conf.json | 10 +++++-----
 6 files changed, 15 insertions(+), 6 deletions(-)
 create mode 100644 frontend/.nvmrc

diff --git a/README.md b/README.md
index 6e69029..926cf04 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ Root-level planning/spec Markdown has been organized under `docs/`:
 
 ### 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`
diff --git a/docs/agents/handoff.md b/docs/agents/handoff.md
index ae68e6e..9300c4e 100644
--- a/docs/agents/handoff.md
+++ b/docs/agents/handoff.md
@@ -28,6 +28,8 @@ This branch keeps the owner-specific greeting and adds the local profile flow ne
 - Added a small local profile utility layer for loading, saving, validating, and normalizing owner profile data.
 - Preserved owner-specific default behavior for the existing owner while making new-user setup explicit.
 - Fixed the Tauri config schema issue found during validation.
+- Updated the Tauri desktop window from the old compact command-bar dimensions to a resizable Tome Home-sized window, and enabled macOS transparent-window support.
+- Documented the frontend Node runtime range and added `frontend/.nvmrc` so macOS/dev environments can use Node 22 LTS instead of newer current Node releases that emit upstream `DEP0205` dev warnings.
 - Organized project documentation under `docs/` with purpose-based subdirectories.
 - Moved agent onboarding/contract docs into `docs/agents/` and added `docs/agents/README.md` as the coding-agent entrypoint.
 - Refreshed README/doc links so current product truth points at Tome Home, local-first storage, and the agent onboarding context instead of old root-level or planning paths.
diff --git a/frontend/.nvmrc b/frontend/.nvmrc
new file mode 100644
index 0000000..2bd5a0a
--- /dev/null
+++ b/frontend/.nvmrc
@@ -0,0 +1 @@
+22
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index c73ea18..944f890 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -40,6 +40,9 @@
         "remark-gfm": "^4.0.1",
         "tailwindcss": "^4",
         "typescript": "^5"
+      },
+      "engines": {
+        "node": ">=20 <25"
       }
     },
     "node_modules/@alloc/quick-lru": {
diff --git a/frontend/package.json b/frontend/package.json
index 1df4d82..d4937f2 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -2,6 +2,9 @@
   "name": "frontend",
   "version": "0.1.0",
   "private": true,
+  "engines": {
+    "node": ">=20 <25"
+  },
   "scripts": {
     "dev": "next dev",
     "build": "next build",
diff --git a/frontend/src-tauri/tauri.conf.json b/frontend/src-tauri/tauri.conf.json
index dd25400..1f325ee 100644
--- a/frontend/src-tauri/tauri.conf.json
+++ b/frontend/src-tauri/tauri.conf.json
@@ -15,11 +15,11 @@
       {
         "label": "main",
         "title": "Sage",
-        "width": 640,
-        "height": 120,
-        "minWidth": 640,
-        "minHeight": 48,
-        "resizable": false,
+        "width": 1180,
+        "height": 820,
+        "minWidth": 900,
+        "minHeight": 640,
+        "resizable": true,
         "fullscreen": false,
         "decorations": false,
         "transparent": true,

From 1e12233dcd4fb59bf15ce88de2cf00b186e53b51 Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Sun, 31 May 2026 17:52:58 -0700
Subject: [PATCH 09/10] fix: polish responsive Tome surfaces

---
 docs/agents/handoff.md                     | 4 ++--
 frontend/src/app/page.tsx                  | 4 ++--
 frontend/src/components/AudioView.tsx      | 2 +-
 frontend/src/components/FlashcardsView.tsx | 2 +-
 frontend/src/components/QuizView.tsx       | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/agents/handoff.md b/docs/agents/handoff.md
index 9300c4e..b976cb4 100644
--- a/docs/agents/handoff.md
+++ b/docs/agents/handoff.md
@@ -26,7 +26,7 @@ This branch keeps the owner-specific greeting and adds the local profile flow ne
 
 - Implemented first-run local profile setup and editable settings while preserving the Tome Home default UI.
 - Added a small local profile utility layer for loading, saving, validating, and normalizing owner profile data.
-- Preserved owner-specific default behavior for the existing owner while making new-user setup explicit.
+- Preserved owner-specific greetings through locally stored setup data instead of a built-in owner profile.
 - Fixed the Tauri config schema issue found during validation.
 - Updated the Tauri desktop window from the old compact command-bar dimensions to a resizable Tome Home-sized window, and enabled macOS transparent-window support.
 - Documented the frontend Node runtime range and added `frontend/.nvmrc` so macOS/dev environments can use Node 22 LTS instead of newer current Node releases that emit upstream `DEP0205` dev warnings.
@@ -49,7 +49,7 @@ This branch keeps the owner-specific greeting and adds the local profile flow ne
 
 - `frontend/src/app/page.tsx`: Tome Home app shell, local setup/profile loading, owner greeting, and routed views.
 - `frontend/src/lib/command-routing.ts`: explicit routing for `/quiz`, `/flashcards`, `/audio`, `/report`, `/history`, `/tomes`, `/knowledge`, `/settings`, etc.
-- `frontend/src/lib/user-profile.ts`: local user profile contract, default owner profile, validation/normalization helpers, and `localStorage` key for owner-specific greetings/settings.
+- `frontend/src/lib/user-profile.ts`: local user profile contract, validation/normalization helpers, and `localStorage` key for owner-specific greetings/settings.
 - `frontend/src/components/ProfileSetup.tsx`: first-run local profile setup flow.
 - `frontend/src/components/SettingsPanel.tsx`: editable local profile/settings surface.
 - `frontend/src/lib/sage-api.ts`: typed API client, browser backend URL, and Tauri sidecar backend startup.
diff --git a/frontend/src/app/page.tsx b/frontend/src/app/page.tsx
index 51d035b..689386f 100644
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@@ -99,7 +99,7 @@ export default function Home() {
 
   if (!profile) {
     return (
-      <main className="relative min-h-screen w-full overflow-hidden bg-[#080807] text-[#ede6d5]">
+      <main className="relative min-h-screen w-full overflow-x-hidden bg-[#080807] text-[#ede6d5]">
         <div className="pointer-events-none absolute inset-x-0 top-[-12rem] h-[36rem] bg-[radial-gradient(circle_at_center,rgba(242,168,93,0.12),transparent_62%)]" />
         <div className="pointer-events-none absolute right-[-12rem] top-16 h-[32rem] w-[32rem] rounded-full bg-[rgba(171,199,173,0.07)] blur-[110px]" />
         <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 py-8 sm:px-8 lg:px-10">
@@ -110,7 +110,7 @@ export default function Home() {
   }
 
   return (
-    <main className="relative min-h-screen w-full overflow-hidden bg-[#080807] text-[#ede6d5]">
+    <main className="relative min-h-screen w-full overflow-x-hidden bg-[#080807] text-[#ede6d5]">
       <div className="pointer-events-none absolute inset-x-0 top-[-12rem] h-[36rem] bg-[radial-gradient(circle_at_center,rgba(242,168,93,0.12),transparent_62%)]" />
       <div className="pointer-events-none absolute right-[-12rem] top-16 h-[32rem] w-[32rem] rounded-full bg-[rgba(171,199,173,0.07)] blur-[110px]" />
       <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 py-8 sm:px-8 lg:px-10">
diff --git a/frontend/src/components/AudioView.tsx b/frontend/src/components/AudioView.tsx
index 432b87f..bba6dcd 100644
--- a/frontend/src/components/AudioView.tsx
+++ b/frontend/src/components/AudioView.tsx
@@ -67,7 +67,7 @@ export default function AudioView({ prompt, tomeId, voice }: AudioViewProps) {
   const audioUrl = data.audio_url ? resolveAudioUrl(data.audio_url) : null;
 
   return (
-    <div className="flex flex-col items-center gap-3">
+    <div className="flex w-full flex-col items-center gap-3">
       <AudioPlayerWidget track={track} audioUrl={audioUrl} script={data.script} />
       {data.sources.length > 0 && <SourcesFooter sources={data.sources} />}
     </div>
diff --git a/frontend/src/components/FlashcardsView.tsx b/frontend/src/components/FlashcardsView.tsx
index 6c824e6..fa4506b 100644
--- a/frontend/src/components/FlashcardsView.tsx
+++ b/frontend/src/components/FlashcardsView.tsx
@@ -58,7 +58,7 @@ export default function FlashcardsView({ prompt, tomeId, count = 6 }: Flashcards
   const title = prompt.trim() ? `Flashcards: ${prompt.trim()}` : "Flashcards";
 
   return (
-    <div className="flex flex-col items-center gap-3">
+    <div className="flex w-full flex-col items-center gap-3">
       <FlashcardWidget title={title} cards={cards} />
       {sources.length > 0 && <SourcesFooter sources={sources} />}
     </div>
diff --git a/frontend/src/components/QuizView.tsx b/frontend/src/components/QuizView.tsx
index 47f77ef..de8a148 100644
--- a/frontend/src/components/QuizView.tsx
+++ b/frontend/src/components/QuizView.tsx
@@ -58,7 +58,7 @@ export default function QuizView({ prompt, tomeId, count = 5 }: QuizViewProps) {
   const title = prompt.trim() ? `Quiz: ${prompt.trim()}` : "Quiz";
 
   return (
-    <div className="flex flex-col items-center gap-3">
+    <div className="flex w-full flex-col items-center gap-3">
       <QuizWidget title={title} questions={questions} />
       {sources.length > 0 && <SourcesFooter sources={sources} />}
     </div>

From 639a9aa7f2ff39d33c61035dff9894c50bf9a6bd Mon Sep 17 00:00:00 2001
From: zeapsu <andryypaez@gmail.com>
Date: Sun, 31 May 2026 18:08:10 -0700
Subject: [PATCH 10/10] fix: add desktop window controls

---
 frontend/src-tauri/capabilities/default.json |   4 +
 frontend/src/app/layout.tsx                  |   2 +-
 frontend/src/app/page.tsx                    | 101 ++++++++++++++++++-
 3 files changed, 104 insertions(+), 3 deletions(-)

diff --git a/frontend/src-tauri/capabilities/default.json b/frontend/src-tauri/capabilities/default.json
index bc679c7..a62a421 100644
--- a/frontend/src-tauri/capabilities/default.json
+++ b/frontend/src-tauri/capabilities/default.json
@@ -5,6 +5,10 @@
   "windows": ["main"],
   "permissions": [
     "core:default",
+    "core:window:allow-start-dragging",
+    "core:window:allow-minimize",
+    "core:window:allow-toggle-maximize",
+    "core:window:allow-close",
     {
       "identifier": "shell:allow-spawn",
       "allow": [
diff --git a/frontend/src/app/layout.tsx b/frontend/src/app/layout.tsx
index ada5907..fbcd864 100644
--- a/frontend/src/app/layout.tsx
+++ b/frontend/src/app/layout.tsx
@@ -18,7 +18,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
           rel="stylesheet"
         />
       </head>
-      <body className="min-h-screen w-full bg-transparent overflow-hidden font-body text-on-surface antialiased">
+      <body className="min-h-screen w-full overflow-x-hidden bg-transparent font-body text-on-surface antialiased">
         {children}
       </body>
     </html>
diff --git a/frontend/src/app/page.tsx b/frontend/src/app/page.tsx
index 689386f..67f1166 100644
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@@ -21,6 +21,26 @@ import type { SageUserProfile } from "@/lib/user-profile";
 
 type ViewState = "idle" | "dashboard" | "chat" | "settings" | RoutedView;
 
+type TauriWindowHandle = {
+  minimize?: () => Promise<void>;
+  maximize?: () => Promise<void>;
+  unmaximize?: () => Promise<void>;
+  toggleMaximize?: () => Promise<void>;
+  isMaximized?: () => Promise<boolean>;
+  close?: () => Promise<void>;
+};
+
+declare global {
+  interface Window {
+    __TAURI__?: {
+      window?: {
+        appWindow?: TauriWindowHandle;
+        getCurrentWindow?: () => TauriWindowHandle;
+      };
+    };
+  }
+}
+
 const generatedViews = new Set<ViewState>(["quiz", "flashcards", "audio", "report"]);
 
 const capabilities: Array<{ label: string; icon: string; prompt?: string; view: ViewState }> = [
@@ -100,9 +120,10 @@ export default function Home() {
   if (!profile) {
     return (
       <main className="relative min-h-screen w-full overflow-x-hidden bg-[#080807] text-[#ede6d5]">
+        <WindowChrome />
         <div className="pointer-events-none absolute inset-x-0 top-[-12rem] h-[36rem] bg-[radial-gradient(circle_at_center,rgba(242,168,93,0.12),transparent_62%)]" />
         <div className="pointer-events-none absolute right-[-12rem] top-16 h-[32rem] w-[32rem] rounded-full bg-[rgba(171,199,173,0.07)] blur-[110px]" />
-        <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 py-8 sm:px-8 lg:px-10">
+        <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 pb-8 pt-12 sm:px-8 lg:px-10">
           <ProfileSetup onComplete={completeSetup} />
         </div>
       </main>
@@ -111,9 +132,10 @@ export default function Home() {
 
   return (
     <main className="relative min-h-screen w-full overflow-x-hidden bg-[#080807] text-[#ede6d5]">
+      <WindowChrome />
       <div className="pointer-events-none absolute inset-x-0 top-[-12rem] h-[36rem] bg-[radial-gradient(circle_at_center,rgba(242,168,93,0.12),transparent_62%)]" />
       <div className="pointer-events-none absolute right-[-12rem] top-16 h-[32rem] w-[32rem] rounded-full bg-[rgba(171,199,173,0.07)] blur-[110px]" />
-      <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 py-8 sm:px-8 lg:px-10">
+      <div className="relative z-10 mx-auto flex min-h-screen w-full max-w-[1180px] flex-col px-5 pb-8 pt-12 sm:px-8 lg:px-10">
         <TopBar viewState={viewState} profile={profile} onNavigate={setViewState} />
 
         <AnimatePresence mode="wait">
@@ -188,6 +210,81 @@ export default function Home() {
   );
 }
 
+function getTauriWindow(): TauriWindowHandle | null {
+  if (typeof window === "undefined") return null;
+  const tauriWindow = window.__TAURI__?.window;
+  return tauriWindow?.getCurrentWindow?.() ?? tauriWindow?.appWindow ?? null;
+}
+
+async function toggleMaximizeWindow(appWindow: TauriWindowHandle) {
+  if (appWindow.toggleMaximize) {
+    await appWindow.toggleMaximize();
+    return;
+  }
+
+  const isMaximized = await appWindow.isMaximized?.();
+  if (isMaximized && appWindow.unmaximize) {
+    await appWindow.unmaximize();
+    return;
+  }
+  await appWindow.maximize?.();
+}
+
+function WindowChrome() {
+  const runWindowAction = (action: "minimize" | "maximize" | "close") => {
+    const appWindow = getTauriWindow();
+    if (!appWindow) return;
+
+    if (action === "minimize") void appWindow.minimize?.();
+    if (action === "maximize") void toggleMaximizeWindow(appWindow);
+    if (action === "close") void appWindow.close?.();
+  };
+
+  return (
+    <div className="fixed inset-x-0 top-0 z-50 flex h-10 items-center justify-end bg-[#080807]/55 px-2 backdrop-blur-md">
+      <div data-tauri-drag-region className="absolute inset-0" />
+      <div className="relative flex items-center gap-1" aria-label="Window controls">
+        <WindowControlButton label="Minimize window" onClick={() => runWindowAction("minimize")}>
+          −
+        </WindowControlButton>
+        <WindowControlButton label="Maximize window" onClick={() => runWindowAction("maximize")}>
+          □
+        </WindowControlButton>
+        <WindowControlButton label="Close window" onClick={() => runWindowAction("close")} tone="danger">
+          ×
+        </WindowControlButton>
+      </div>
+    </div>
+  );
+}
+
+function WindowControlButton({
+  label,
+  onClick,
+  children,
+  tone = "default",
+}: {
+  label: string;
+  onClick: () => void;
+  children: ReactNode;
+  tone?: "default" | "danger";
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      onClick={onClick}
+      className={`grid h-7 w-9 place-items-center rounded-full border text-sm transition-colors ${
+        tone === "danger"
+          ? "border-[#ffb4ab]/20 text-[#ffb4ab] hover:bg-[#ffb4ab]/15"
+          : "border-white/10 text-[#9f9788] hover:bg-white/10 hover:text-[#ede6d5]"
+      }`}
+    >
+      {children}
+    </button>
+  );
+}
+
 function TopBar({
   viewState,
   profile,