docs: improve README and setup navigation

README.md

@@ -1,3 +1,5 @@
+# Odysseus
+
 <p align="center">
   <img src="docs/odysseus-wordmark.png" alt="Odysseus" width="238">
 </p>
@@ -9,6 +11,8 @@
 <p align="center">
   <a href="#quick-start">Quick Start</a> ·
   <a href="docs/setup.md">Setup Guide</a> ·
+  <a href="docs/ARCHITECTURE.md">Architecture</a> ·
+  <a href="SECURITY.md">Security</a> ·
   <a href="CONTRIBUTING.md">Contributing</a> ·
   <a href="ROADMAP.md">Roadmap</a>
 </p>
@@ -51,15 +55,15 @@ Native installs, GPU notes, Windows/macOS instructions, HTTPS, and configuration
 
 ## Demo
 
-A full hover-to-play tour lives on the landing page: [`docs/index.html`](docs/index.html).
+Explore the interface through the [interactive product tour](docs/index.html).
 
 ## Contributing
 
-Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, documentation, and small focused refactors. See [CONTRIBUTING.md](CONTRIBUTING.md), the [public roadmap](ROADMAP.md), and the open [GitHub issues](https://github.com/odysseus-dev/odysseus/issues).
+Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, documentation, and small focused refactors. Read the [contributing guide](CONTRIBUTING.md), review the [public roadmap](ROADMAP.md), and browse the open [GitHub issues](https://github.com/odysseus-dev/odysseus/issues).
 
 ## Security
 
-Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled, keep private data out of Git, and do not expose raw model/service ports publicly. Deployment details are in the [setup guide](docs/setup.md#security-notes).
+Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled, keep private data out of Git, and do not expose raw model or service ports publicly. Read the [security policy](SECURITY.md) and the [deployment security guidance](docs/setup.md#security-notes).
 
 ## Star History
 
@@ -73,4 +77,4 @@ Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled
 
 ## License
 
-AGPL-3.0-or-later -- see [LICENSE](LICENSE) and [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
+Licensed under AGPL-3.0-or-later. See the [license](LICENSE) and [acknowledgments](ACKNOWLEDGMENTS.md).

docs/setup.md

@@ -1,6 +1,28 @@
 # Odysseus Setup Guide
 
-This page keeps the detailed install, deployment, troubleshooting, and configuration notes out of the front README.
+This guide covers installation, deployment, troubleshooting, and configuration.
+For a minimal Docker installation, start with the
+[repository README](../README.md#quick-start).
+
+## On this page
+
+- [Quick Start](#quick-start)
+  - [Docker](#docker-recommended)
+  - [Native Linux and macOS](#native-linux--macos)
+  - [Apple Silicon](#apple-silicon)
+  - [Native Windows](#native-windows)
+- [Troubleshooting and advanced setup](#troubleshooting--advanced-setup)
+- [Security notes](#security-notes)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
+- [Data and backups](#data)
+
+Related guidance:
+
+- [Security policy](../SECURITY.md)
+- [Architecture overview](ARCHITECTURE.md)
+- [Backup and restore guide](backup-restore.md)
+- [Contributing guide](../CONTRIBUTING.md)
 
 ## Quick Start
 
@@ -15,8 +37,8 @@ On first setup, Odysseus creates an admin account (`admin` unless
 For Docker installs, the same line is in `docker compose logs odysseus`.
 Use that for the first login, then change it in **Settings**.
 
-Contributing? See [CONTRIBUTING.md](../CONTRIBUTING.md) for setup, testing, and
+Contributing? See the [contributing guide](../CONTRIBUTING.md) for development
-pull request guidelines.
+setup, testing, and pull request guidelines.
 
 ### Docker (recommended)
 ```bash
@@ -441,8 +463,8 @@ uv pip sync requirements.lock                          # reproduce it exactly la
 ### Outlook / Office 365 email
 Odysseus email accounts currently use IMAP/SMTP username-password auth. Outlook
 and Microsoft 365 generally require OAuth instead, so normal Microsoft mailbox
-passwords will fail. See [email-outlook.md](email-outlook.md) for the
+passwords will fail. See the [Outlook and Microsoft 365 email guide](email-outlook.md)
-current limitation and the planned integration direction.
+for the current limitation and planned integration direction.
 
 ## Security Notes
 Odysseus is a self-hosted workspace with powerful local tools: shell access, file uploads, model downloads, web research, email/calendar integrations, and API tokens. Treat it like an admin console.
@@ -530,19 +552,16 @@ npx -y @playwright/mcp@latest --version
 That installs `@playwright/mcp` plus Playwright (~300MB total). Restart Odysseus and the server will register at startup.
 
 ## Architecture
-```
+
-app.py                   # FastAPI entry point
+For stable high-level runtime structure, subsystem boundaries, and documentation
-core/      auth, database, middleware, constants
+authority, see the [architecture overview](ARCHITECTURE.md).
-src/       llm_core, agent_loop, agent_tools, chat_processor, search/
+
-routes/    chat, session, document, memory, model … endpoints
+Source code, tests, and configuration remain authoritative for
-services/  docs, memory, search, hwfit (Cookbook) …
+implementation-sensitive behaviour.
-static/    index.html + app.js + style.css + js/ (modular front-end)
-docs/      landing page (index.html) + preview clips
-```
 
 ## Data
 All user data lives in `data/` (gitignored): `app.db` (sessions, messages, documents),
 `memory.json`, `presets.json`, `uploads/`, `personal_docs/`, `chroma/`, `settings.json`.
 
-To back up or restore everything in `data/`, see the
+To protect or recover this data, follow the
-[Backup & Restore guide](backup-restore.md).
+[backup and restore guide](backup-restore.md).