diff --git a/README.md b/README.md
index e646b917..e35353cd 100644
--- a/README.md
+++ b/README.md
@@ -2,295 +2,478 @@
# π§ Cortex
-## Next-generation AI proxy and routing infrastructure
+The AI Infrastructure Stack for Production
[](https://github.com/dallay/cortex/actions/workflows/ci.yml)
[](LICENSE)
-[](https://www.rust-lang.org)
-[](https://github.com/dallay/cortex/stargazers)
-[](https://github.com/dallay/cortex/issues)
-[](https://github.com/dallay/cortex/commits/main)
+[](https://www.rust-lang.org)
+[](https://nodejs.org)
+[](https://vuejs.org)
+[](https://www.docker.com)
+[](https://github.com/dallay/cortex/commits/main)
+[](https://github.com/dallay/cortex/stargazers)
[](https://deepwiki.com/dallay/cortex)
-[Getting Started](#-getting-started) β’ [Documentation](#-documentation) β’ [Contributing](#-contributing) β’ [Community](#-community)
+**Rook** β AI Proxy & Router Β· **Huginn** β Local Coding Agent
-## π Table of Contents
-
-- [About](#-about)
-- [Features](#-features)
-- [Getting Started](#-getting-started)
- - [Prerequisites](#prerequisites)
- - [Installation](#installation)
- - [Quick Start](#quick-start)
-- [Usage](#-usage)
-- [Configuration](#-configuration)
-- [Architecture](#-architecture)
-- [Tools](#-tools)
-- [Development](#-development)
-- [Documentation](#-documentation)
-- [Roadmap](#-roadmap)
-- [Contributing](#-contributing)
-- [License](#-license)
-- [Community](#-community)
-- [Acknowledgments](#-acknowledgments)
-
-## π About
-
-**Cortex** is a high-performance AI infrastructure project written in Rust. Its primary component, **Rook**, acts as an intelligent AI proxy and router designed to simplify and harden your AI application stack.
-
-In an ecosystem with multiple LLM providers (OpenAI, Anthropic, Google, etc.), Cortex provides a unified, OpenAI-compatible interface with enterprise-grade features out of the box. It solves common challenges such as provider outages, high latency, and lack of observability by providing automatic failover, efficient caching, and comprehensive audit logging.
-
-## β¨ Features
-
-- π **OpenAI-compatible API**: Drop-in replacement for existing OpenAI clients.
-- β¨ **Multi-provider routing**: Support for OpenAI, Anthropic, Ollama, Gemini, and Groq.
-- π **Automatic fallback**: Resilience against provider failures with Combos (ordered fallback chains, `X-Rook-Combo`).
-- π·οΈ **Model aliasing**: Normalize variant names (`gpt-4-turbo` β dated canonical) with 30+ built-ins plus custom aliases.
-- π **Streaming**: OpenAI-compatible SSE streaming, including tool-call deltas.
-- π **Built-in caching**: Reduce costs and latency with TTL-based in-memory caching.
-- π **Audit logging**: Full traceability of requests and responses backed by SQLite.
-- ποΈ **Clean Architecture**: Built with Domain-Driven Design (DDD) for high maintainability.
-- π¦ **Rust-powered**: Exceptional performance, memory safety, and concurrency.
-- π **Production-ready**: Includes health checks, observability (tracing, metrics), and encryption.
-
-## π Getting Started
+---
+
+
-The Rook management dashboard is a Vue 3 SPA, embedded in the production Rook
-binary under `/dashboard/`. Vite serves it on port `4747` and proxies API requests
-to the backend on port `3773` by default.
+# π Rook Dashboard
-## Requirements
+Vue 3 Management Interface for Rook AI Proxy
-- Node.js and pnpm (version pinned in the root `package.json`)
-- A running Rook backend for authenticated management flows and API data
+[](https://vuejs.org)
+[](https://www.typescriptlang.org)
+[](https://vitejs.dev)
+[](https://vitest.dev)
+[](https://playwright.dev)
+[](https://pnpm.io)
+[](https://github.com/dallay/cortex/blob/main/LICENSE)
-Install workspace dependencies with `pnpm install` from the repository root.
+
-Pages live in `src/views/`, shared UI in `src/components/`, routing in
-`src/router/`, Pinia state in `src/stores/`, and English/Spanish translations in
-`src/locales/`. `vite.config.ts` defines the base path and proxy; `playwright.config.ts`
-defines browser projects and E2E settings.
+**Vue 3** Β· **TypeScript** Β· **Pinia** Β· **Vue Router** Β· **i18n**
-See the [Rook configuration guide](../../../docs/rook/configuration.md), [API reference](../../../docs/rook/api.md),
-and [workspace README](../../../README.md) for backend setup and product context.
+
diff --git a/dev/README.md b/dev/README.md
index 8f21cb84..e32f03fe 100644
--- a/dev/README.md
+++ b/dev/README.md
@@ -1,199 +1,339 @@
-# dev/ β Local Testing Without Host Pollution
+
-Three isolated paths depending on what you need to test.
-Nothing writes to your host OS beyond Docker images and mapped ports.
+# π³ Dev Testing Guide
+
+Local testing without host pollution
+
+[](https://www.docker.com)
+[](https://www.linux.org)
+[](https://www.gnu.org/software/bash/)
+[](https://github.com/dallay/cortex/blob/main/LICENSE)
+
+**Three isolated paths** β nothing writes to your host OS beyond Docker images and mapped ports.
+
+[π Just Recipes](#path-1--smoke-test-container) Β· [π Playwright E2E](#path-2--playwright-e2e-against-docker) Β· [π¦ Multi-distro](#path-3--multi-distro-e2e)
+
+
---
-## Which path do I use?
+## π― Which Path Do I Use?
+
+| Goal | Path | Speed |
+|------|------|-------|
+| Verify backend starts and `/health` responds | [Path 1 β Smoke Test](#path-1--smoke-test-container) | β‘ Fast (~2 min) |
+| Full E2E (dashboard + API key CRUD) | [Path 2 β Playwright E2E](#path-2--playwright-e2e-against-docker) | π’ Slow (~10 min) |
+| Binary validation (Ubuntu + Alpine) | [Path 3 β Multi-distro](#path-3--multi-distro-e2e) | π’ Slow (~15 min) |
-| Goal | Path |
-|------|------|
-| Verify the backend starts and `/health` responds | [Path 1 β Smoke test container](#path-1--smoke-test-container) |
-| Full Playwright E2E (dashboard + API key CRUD) against Docker | [Path 2 β Playwright E2E against Docker](#path-2--playwright-e2e-against-docker) |
-| Multi-distro binary validation (Ubuntu + Alpine) | [Path 3 β Multi-distro E2E](#path-3--multi-distro-e2e) |
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β Testing Architecture β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β ββββββββββββββββ β
+β β Your Host β β
+β β (macOS) β β
+β ββββββββ¬ββββββββ β
+β β β
+β β just dev-* β
+β βΌ β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β Docker Container β β
+β β β β
+β β βββββββββββββββββββββββ βββββββββββββββββββββββ β β
+β β β Path 1: rook β β Path 2: full β β β
+β β β (debug, no UI) β β (debug + admin) β β β
+β β βββββββββββββββββββββββ βββββββββββββββββββββββ β β
+β β βββββββββββββββββββββββ β β
+β β β Path 3: alpine β β β
+β β β (musl binary) β β β
+β β βββββββββββββββββββββββ β β
+β β β β
+β β Ports: 8090 β 3773 (host β container) β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
---
-## Path 1 β Smoke test container
+## Path 1 β Smoke Test Container
+
+**Fastest path.** Builds Rook in debug mode (no dashboard) and confirms the API layer works.
-Fastest path. Builds rook in **debug mode** (no dashboard) and confirms the API
-layer works. Use this when you only need to verify the backend, health check, or
-API routing without any UI.
+### What You Get
-**Port**: `8090` on host β `3773` in container
-**Database**: in-memory (`:memory:`) β ephemeral, clean slate on every restart
-**Dashboard**: NOT available (Vue SPA is not built in debug mode β `/dashboard` returns 404)
+| Feature | Available |
+|---------|-----------|
+| Backend API | β On port 8090 |
+| Health check | β `curl localhost:8090/health` |
+| Database | β In-memory (`:memory:`) |
+| Dashboard | β Not built in debug mode |
+| Logs | β `just dev-logs` |
+
+### Commands
```bash
# Build the image (first time or after code changes)
-just dev-build # or: dev/run.sh build
+just dev-build
# Start container and wait until /health is OK
-just dev-up # or: dev/run.sh up
+just dev-up
# Verify
curl http://127.0.0.1:8090/health
# Tail logs
-just dev-logs # or: dev/run.sh logs
+just dev-logs
# Shell into container
-just dev-shell # or: dev/run.sh shell
+just dev-shell
-# Stop and remove
-just dev-down # or: dev/run.sh down
+# Stop and remove container
+just dev-down
# Remove image + container
-just dev-clean # or: dev/run.sh clean
+just dev-clean
```
-> **macOS + OrbStack note**: use `127.0.0.1` instead of `localhost` to avoid
-> IPv6-first resolution quirks where OrbStack only binds the IPv4 port.
+### Config
-### Config used
+Use `dev/config.toml` to override defaults:
-`dev/test-configs/rook-dev.toml` β in-memory DB, cache disabled, no provider CRUD.
+```toml
+[server]
+host = "0.0.0.0"
+port = 3773
+```
-### Limitations (intentional)
+### Troubleshooting
-- Debug build β much faster image builds (Cargo cache hits), but no embedded Vue SPA.
-- `provider_crud.enabled = false` β Provider CRUD endpoints are not mounted.
-- No auth API keys enabled β all requests are unauthenticated.
+> **macOS + OrbStack note:** Use `127.0.0.1` instead of `localhost` to avoid
+> IPv6-first resolution quirks where OrbStack only binds the IPv4 port.
---
-## Path 2 β Playwright E2E against Docker
+## Path 2 β Playwright E2E Against Docker
+
+**Full E2E suite.** Tests the dashboard login, provider management, API key CRUD, and dashboard flows.
-Full-stack E2E: backend runs in Docker (isolated DB on disk inside container),
-dashboard runs locally via `pnpm dev`, Playwright drives Chromium + Firefox + WebKit.
+### What You Get
-**Port**: `3773` on host β `3773` in container
-**Database**: `/tmp/rook-e2e.db` inside the container (tmpfs-backed, gone when container is removed)
-**Dashboard**: `http://localhost:4747/dashboard/` (Vite dev server on your machine)
-**Admin password**: `Admin123456-` (seeded automatically via `rook seed-admin`)
+| Feature | Available |
+|---------|-----------|
+| Backend API | β Running in `rook:e2e-api-keys` container |
+| Admin account | β `admin@rook.local` / `rook-admin-123` |
+| Dashboard | β Built and served |
+| Audit data | β In-memory (ephemeral) |
+| Database | β SQLite at `/tmp/rook-e2e.db` (container tmpfs) |
+| E2E tests | β Playwright |
-### Prerequisites
+### Architecture
-- Docker running
-- `pnpm install` done in `apps/rook/dashboard` (run `just dashboard-install` if not)
-- Playwright browsers installed (`cd apps/rook/dashboard && npx playwright install`)
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β E2E Test Architecture β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β Docker Compose β β
+β β β β
+β β βββββββββββββββββββ βββββββββββββββββββ β β
+β β β rook:latest β β postgres:16 β β β
+β β β (release) β β (audit logs) β β β
+β β ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ β β
+β β β β β β
+β β Port: 3773 β Port: 5432 β β
+β β ββββββββββββββ¬ββββββββββββ β β
+β β β β β
+β βββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββ β
+β β β
+β βββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββ β
+β β Playwright (host) β β β
+β β βΌ β β
+β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
+β β β Browser (Chromium/Firefox/Webkit) β β β
+β β β β β β
+β β β Tests: login, providers, api-keys, dashboard β β β
+β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
-### Run tests automatically
+### Commands
```bash
-# Build image + start container + start dashboard + run all Playwright tests + cleanup
+# Build the E2E Docker image
+just test-e2e-build
+
+# Run E2E tests
just test-e2e
-# or directly:
-dev/e2e/run-api-keys-e2e.sh --test
+
+# Run specific test file
+cd apps/rook/dashboard
+pnpm exec playwright test e2e/login.spec.ts
+
+# Run with UI (headed mode)
+pnpm exec playwright test --headed
+
+# Debug mode
+pnpm exec playwright test --debug
```
-This does everything in one shot:
-1. Builds `rook:e2e-api-keys` from `Dockerfile.dev` (repo root)
-2. Starts the container on port `3773`
-3. Seeds the admin account inside the container
-4. Starts `pnpm dev` for the dashboard in the background
-5. Runs `playwright test e2e/api-keys.spec.ts`
-6. Cleans up container and dashboard process
+### Manual Run
-### Manual testing mode
+```bash
+# Use just recipes for E2E workflow
+just test-e2e # Run full E2E suite
+just test-e2e-dev # Development mode with watch
+just test-e2e-cleanup # Clean up containers and volumes
+```
-Start the container and leave it running so you can interact with the dashboard
-in a browser or run individual Playwright tests by hand.
+For integration testing with `docker-compose.test.yml`:
```bash
-# Start container only (no tests, stays running)
-just test-e2e-dev
-# or: dev/e2e/run-api-keys-e2e.sh
+# 1. Start Docker Compose
+docker compose -f docker-compose.test.yml up -d
-# In a second terminal β start the dashboard
-just run-dashboard # http://localhost:4747/dashboard/
+# 2. Wait for services
+sleep 10
-# In a third terminal β run specific tests
+# 3. Run tests
cd apps/rook/dashboard
-pnpm playwright test e2e/api-keys.spec.ts --project=chromium
-pnpm playwright test e2e/api-keys.spec.ts --debug
+pnpm exec playwright test
-# When done β stop and remove the container
-just test-e2e-cleanup
-# or: dev/e2e/run-api-keys-e2e.sh --cleanup
+# 4. Cleanup
+docker compose -f docker-compose.test.yml down -v
```
-Log in at `http://localhost:4747/dashboard/` with:
-- **Email**: `admin@rook.local`
-- **Password**: `Admin123456-`
-
-### Config used
-
-`dev/test-configs/rook-api-keys-test.toml` β auth API keys enabled, provider CRUD enabled,
-cache disabled, DB at `/tmp/rook-e2e.db` (inside container).
+### Test Coverage
-### Dockerfile used
-
-`Dockerfile.dev` at the **repo root** (not `dev/Dockerfile.dev`).
-This image includes the dashboard build embedded in the Rook binary.
+| Test File | Coverage |
+|-----------|----------|
+| `e2e/login.spec.ts` | Login flow, logout, session persistence |
+| `e2e/providers.spec.ts` | Provider CRUD, connection testing |
+| `e2e/api-keys.spec.ts` | API key creation, revocation, listing |
+| `e2e/vue.spec.ts` | Navigation, settings, audit logs |
---
## Path 3 β Multi-distro E2E
-Validates the rook binary runs correctly on Ubuntu (Debian Bookworm) and Alpine.
-Useful before a release or when changing system dependencies.
+**Binary validation.** Tests the release binary on Ubuntu and Alpine to ensure musl compatibility.
-**Ports**: `8081` (ubuntu), `8082` (alpine) on host
+### What You Get
-```bash
-# Build images for both distros
-dev/e2e-test.sh build
+| Feature | Available |
+|---------|-----------|
+| Ubuntu 22.04 | β amd64 |
+| Alpine 3.19 | β amd64 (musl) |
+| rook binary | β Release build |
+| Health check | β Cross-distro |
-# Start both containers
-dev/e2e-test.sh up
+### Commands
-# Run smoke tests against all distros
+```bash
+# Build release binary
+just build
+
+# Run multi-distro tests
dev/e2e-test.sh test
-# Test a single distro
+# Run only Ubuntu
dev/e2e-test.sh test ubuntu
+
+# Run only Alpine
dev/e2e-test.sh test alpine
+```
+
+---
+
+## π οΈ Just Recipes Reference
+
+| Recipe | Description |
+|--------|-------------|
+| `just dev-build` | Build dev Docker image |
+| `just dev-up` | Start smoke test container |
+| `just dev-down` | Stop container |
+| `just dev-logs` | Tail container logs |
+| `just dev-shell` | Shell into container |
+| `just dev-clean` | Remove image + container |
+| `just test-e2e-build` | Build E2E Docker image |
+| `just test-e2e` | Run full E2E suite |
+| `just test-e2e-dev` | Development mode with manual testing |
+| `just test-e2e-cleanup` | Stop/remove E2E containers |
+| `just build` | Build release binary |
+| `just build-app` | Build rook binary only |
+
+Full list: `just --list`
+
+---
+
+## π§ Troubleshooting
-# Check /health on a distro
-dev/e2e-test.sh health ubuntu
+### Container won't start
-# Shell into a container
-dev/e2e-test.sh shell ubuntu
+```bash
+# Check Docker is running
+docker info
-# Stop everything
-dev/e2e-test.sh down
+# View container logs
+docker compose -f dev/compose.yml logs
-# Remove images + containers
-dev/e2e-test.sh clean
+# Rebuild from scratch
+just dev-clean && just dev-build
```
-### What the distro tests cover
+### Tests fail with timeout
-| Check | Description |
-|-------|-------------|
-| `/health` | Returns valid JSON with `status` + `providers` |
-| Empty registry | `no_providers_configured` error β no panics |
-| CRUD β routing | Create provider β refresh β route request (manual step) |
+```bash
+# Increase timeout in compose
+TIMEOUT=60 just test-e2e
+```
+
+### Port already in use
+
+```bash
+# Kill process on port 8090
+lsof -ti:8090 | xargs kill -9
+
+# The smoke workflow uses port 8090 on host β 3773 in container
+# See dev/run.sh and dev/docker-compose.dev.yml for details
+just dev-up
+```
+
+### Alpine tests fail (musl issues)
+
+```bash
+# Check binary architecture
+file target/release/rook
+
+# Verify musl linking
+ldd target/release/rook # Should show musl, not glibc
+```
+
+---
+
+## π Resources
+
+| Resource | Description |
+|----------|-------------|
+| [Docker Docs](https://docs.docker.com) | Docker documentation |
+| [Playwright](https://playwright.dev) | E2E testing framework |
+| [Compose File](docker-compose.yml) | Docker Compose configuration |
+| [Rook Architecture](../docs/rook/architecture.md) | Backend internals |
---
-## Config files reference
+## π License
-| File | Used by | DB | Notes |
-|------|---------|----|-------|
-| `test-configs/rook-dev.toml` | Path 1 (smoke test) | `:memory:` | No auth, no CRUD |
-| `test-configs/rook-api-keys-test.toml` | Path 2 (Playwright E2E) | `/tmp/rook-e2e.db` | Auth enabled, CRUD enabled, cache disabled |
-| `test-configs/rook-minimal.toml` | Manual / custom | configurable | Base for experiments |
+MIT License - same as [Cortex repository](https://github.com/dallay/cortex).
---
-## Dockerfile reference
+
-Huginn is the local Rust coding assistant and a product alongside Rook. The
-service kernel, OpenAI-compatible streaming adapter, native tools, SQLite
-sessions, scoped `AGENTS.md` context, compaction and trusted MCP stdio
-client are implemented. Public distribution remains outside this MVP.
+# π€ Huginn
-## Install and start
+Local Rust coding assistant with native tools and MCP integration
-Use the repository's Rust 1.89 toolchain on macOS or Linux:
+[](https://www.rust-lang.org)
+[](https://www.sqlite.org)
+[](https://modelcontextprotocol.io)
+[](https://github.com/dallay/cortex/blob/main/LICENSE)
+
+**Your local AI coding partner** β runs locally with access to your codebase.
+
+[Huginn Architecture](#-architecture) Β· [Installation](#-installation) Β· [Usage](#-usage) Β· [TUI Guide](#-tui-guide) Β· [Providers](providers-ui.md)
+
+
+
+---
+
+## π― What is Huginn?
+
+Huginn is a **local coding agent** built in Rust that works with your codebase. Unlike cloud-based AI assistants, Huginn runs entirely on your machine.
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β Huginn: Local-First AI β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β β β
+β β Your Machine Cloud Providers β β
+β β ββββββββββββ βββββββββββββββ β β
+β β β β
+β β βββββββββββββ βββββββββββββββ β β
+β β β Huginn β βββ API ββββββββΆ β OpenAI β β β
+β β β (Local) β β Anthropic β β β
+β β βββββββ¬ββββββ βββββββββββββββ β β
+β β β β β
+β β β Local Tools β β
+β β βΌ β β
+β β βββββββββββββ β β
+β β β Your Code β βββ Read/Write/Execute β β
+β β βββββββββββββ β β
+β β β β
+β β π Code stays local β prompts and context sent to providers β β
+β β β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Key Principles
+
+| Principle | Description |
+|-----------|-------------|
+| π **Privacy-first** | Code stays local, only model requests go to cloud |
+| π» **Native tools** | File ops, terminal, git β all built-in |
+| π **Extensible** | MCP stdio client for custom tools |
+| π **Scoped context** | `AGENTS.md` controls what Huginn sees |
+| πΎ **Session memory** | SQLite-backed conversation history |
+
+---
+
+## β¨ Features
+
+| Feature | Description |
+|---------|-------------|
+| π₯οΈ **Ratatui TUI** | Beautiful terminal interface with colors and layout |
+| π§ **Native tools** | File read/write, terminal execution, git operations |
+| π **MCP integration** | Connect to any MCP stdio server |
+| πΎ **SQLite sessions** | Persistent conversation history |
+| π **Scoped context** | Per-repo `AGENTS.md` for agent instructions |
+| π― **Tool calling** | Automatic tool selection based on task |
+| π€ **JSON mode** | Machine-readable output for automation |
+| π **Provider agnostic** | OpenAI-compatible API support |
+
+---
+
+## ποΈ Architecture
+
+```
+huginn/
+β
+βββ src/
+β βββ main.rs # Entry point, CLI parsing
+β β
+β βββ cli/ # Command handlers
+β β βββ chat.rs # Interactive chat mode
+β β βββ run.rs # Single command mode
+β β βββ sessions.rs # Session management
+β β
+β βββ runtime/
+β βββ mod.rs # Core runtime
+β βββ provider.rs # LLM provider abstraction
+β βββ tools/ # Native tools
+β β βββ file.rs # File operations
+β β βββ terminal.rs # Shell commands
+β β βββ git.rs # Git operations
+β β βββ mod.rs # Tool registry
+β β
+β βββ mcp/ # MCP client
+β β βββ client.rs # Stdio client
+β β βββ protocol.rs # MCP protocol
+β β
+β βββ session.rs # SQLite session storage
+β βββ context.rs # Context building
+β βββ ui/ # Ratatui UI components
+β
+βββ runtime/ # Huginn runtime crate (shared)
+β βββ src/
+β β βββ service_kernel.rs
+β β βββ streaming_adapter.rs # OpenAI-compatible streaming
+β β βββ tools.rs
+β β βββ sessions.rs
+β β
+β βββ tests/
+β βββ fixtures/
+β
+βββ AGENTS.md # Per-repo agent instructions
+```
+
+### Runtime Flow
+
+```
+User Input
+ β
+ βΌ
+βββββββββββββββ ββββββββββββββββ βββββββββββββββ
+β Parser β βββΆ β Provider β βββΆ β Response β
+β (Command) β β (LLM Call) β β (Streaming)β
+βββββββββββββββ ββββββββ¬ββββββββ ββββββββ¬βββββββ
+ β
+ βΌ
+ ββββββββββββββββ
+ β Tool Call β
+ β Execution β
+ ββββββββ¬ββββββββ
+ β
+ ββββββββββββββββββββΌβββββββββββββββββββ
+ βΌ βΌ βΌ
+ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
+β File System β β Terminal β β Git β
+ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
+```
+
+---
+
+## π Installation
+
+### From Source
```bash
+# Clone the repository
+git clone https://github.com/dallay/cortex.git
+cd cortex
+
+# Install globally
cargo install --path apps/huginn --locked
-huginn --provider mock --workspace /path/to/repository run "list files"
+
+# Or build only
+cargo build --release -p huginn
```
-From the checkout, use `just huginn-run` or `cargo run -p huginn --` followed
-by the same arguments. `mock` is an offline diagnostic provider with a
-read-only `list files` example; it does not perform real coding reasoning.
+### Requirements
-En la TUI, usa `/login`, `/providers`, `/model` y `/logout` para
-[gestionar conexiones con formularios secretos del host](providers-ui.md),
-sin editar configuraciΓ³n ni reiniciar. La verificaciΓ³n de esta UI usa dobles;
-no acredita aceptaciΓ³n de proveedores reales ni onboarding.
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Rust | 1.89+ | MSRV may be higher |
+| Cargo | latest | Included with Rust |
+| SQLite | system | Usually pre-installed |
-For a model, set `HUGINN_BASE_URL` (including `/v1`), `HUGINN_MODEL`, and
-`HUGINN_API_KEY` in the invoking shell, then run:
+### Verify Installation
```bash
-huginn --workspace /path/to/repository chat
-huginn --workspace /path/to/repository --json run "Explain the project"
-huginn sessions
-huginn resume SESSION_UUID
-huginn resume SESSION_UUID --prompt "Continue the task"
-```
-
-Interactive `chat` (or no subcommand) uses the Ratatui TUI when attached to a
-terminal. `--line-mode` selects the line-oriented recovery adapter; `--json`
-emits machine-readable events instead.
-
-### Chat suggestions
-
-- Type `/` to open the active command catalog with descriptions.
- Search accepts prefixes and gapped characters, for example `/exinfo`.
-- Type `@` at a token start to search workspace filenames.
- Paths with spaces are inserted as `@"docs/my guide.md"`.
- The reference is **text only**: it never reads or attaches file contents.
-- Use β/β to select, Tab to complete without running, and Esc to close.
- Enter runs the selected command; for files and arguments it only completes.
- A later Enter sends the draft. Alt/Shift+Enter and Ctrl+J insert a newline.
-- Plugins can declare descriptions, argument values, and paths through
- `CommandMetadata` and `Contributions::register_command`. Existing commands
- without metadata keep working; undeclared arguments are never inferred.
- Summary commands are suggested only with a configured model.
-- The filename index is built in the background once per chat connection,
- with a 20,000-entry walk limit. Restart the chat to refresh it.
- It excludes `.git`, `target`, `node_modules`, `.pnpm-store`, `.cache`, and
- symbolic links; it does not interpret `.gitignore`. It reports a partial
- index or failure. It is not a security boundary against concurrent
- filesystem changes.
-- Approvals and dialogs take priority over suggestions. Completing text
- never grants permissions; a revoked plugin selection never runs its replacement.
-
-`doctor` valida configuraciΓ³n y muestra servicios sin contactar al modelo ni
-iniciar MCP. Sin configuraciΓ³n explΓcita ni selecciΓ³n persistida utilizable,
-informa `model_readiness: "unconfigured"`. Una selecciΓ³n recuperada solo indica
-preparaciΓ³n local: no verifica disponibilidad remota. `run` y `resume --prompt`
-necesitan un modelo y las credenciales que requiera el proveedor. `--db` elige
-otra base de sesiones; `--config` elige un archivo TOML.
-
-## Configuration and permissions
-
-See [config.example.toml](../../apps/huginn/config.example.toml) for every
-setting. The default location follows the OS configuration directory: on
-macOS, `~/Library/Application Support/cortex/huginn/config.toml`; on Linux,
-`~/.config/cortex/huginn/config.toml` (or the XDG override). If a new
-install runs on a host that only has the legacy
-`~/.../cortex/agent/config.toml`, Huginn reads it once (read-only) and
-prints a warning suggesting the migration; it never overwrites the legacy
-file. CLI options override the file; environment variables provide
-defaults for the endpoint and model. API keys are loaded from a named
-environment variable. Set `api_key_env = ""` for a local endpoint
-without authentication.
-
-HTTPS endpoints use validated certificates. Plain HTTP requires
-`allow_loopback_http = true` and a literal loopback IP (`127.0.0.1` or `[::1]`);
-private/LAN addresses and DNS names are not a local exception. Existing local
-HTTP configurations must explicitly enable this setting. Redirects are rejected.
-Para los adaptadores integrados y los modelos Ollama probados anteriormente,
-consulta [adaptadores y verificaciΓ³n local](inference-adapters.md). El
-catΓ‘logo remoto no se consulta desde los formularios: la UI admite un modelo
-candidato cuando no hay modelos estΓ‘ticos. La aceptaciΓ³n automatizada del flujo
-completo con adaptadores reales sigue siendo una entrega de integraciΓ³n separada.
-
-Reads are limited to resolved paths within the workspace. Edits show their
-complete diff and require approval; changed files require a new diff.
-Shell and every MCP call require approval too. Ctrl+C interrupts a turn;
-`/quit` ends a conversation. MCP startup asks separately. Only configured
-environment variables are passed to MCP processes; native shell inherits
-PATH only. Shell and MCP have full host access under the user's account
-and must be trusted.
-
-One-shot mode denies effects unless explicitly granted for that invocation:
+huginn --version
+```
+
+---
+
+## π Usage
+
+### Quick Start
```bash
-huginn --allow native.edit_file,native.shell run "Fix the bug and run its tests"
-```
-
-Grants match exact action names, have no wildcard, and authorize all
-occurrences of that action during this invocation. Available native
-effects are `native.write_file`, `native.edit_file`, and `native.shell`.
-MCP actions use `mcp.SERVER.start` and `mcp.SERVER.REMOTE_TOOL`. Grants
-are never restored from a session. `--json` emits one typed event per
-stdout line; diagnostics use stderr.
-
-### Environment variable fallback
-
-`AGENT_BASE_URL`, `AGENT_MODEL`, and `AGENT_API_KEY` are still read as a
-fallback when the canonical `HUGINN_*` variables are unset. The fallback
-exists so users who already exported the old names keep working after
-the rename; new installations should set the `HUGINN_*` variables
-directly.
-
-## Durable context and recovery
-
-Sessions store messages, calls, results, approval events and interruption
-state in SQLite. Originals survive compaction. New databases use schema
-version 1; newer unknown versions fail explicitly. One process may hold
-a session at a time. Provider credentials are not stored. Repository
-content, prompts and tool output are part of history and may themselves
-contain sensitive text.
-
-Interrupted calls receive a result indicating unknown completion when
-resumed; they are never automatically replayed. Inspect external effects
-before requesting a replacement action. Compaction keeps the last two user
-turns and complete tool pairs, summarizes older messages with the same
-provider, and stops if it fails. Context accounting uses conservative
-serialized bytes rather than a model tokenizer.
-
-Root and nested AGENTS.md documents are loaded with directory scope
-labels on each iteration. Symlinks must resolve inside the workspace;
-generated/dependency folders are excluded. Instructions are context and
-cannot grant permissions.
-
-## Cross-process session locking
-
-Huginn acquires an advisory lock file before mutating a session. The lock filename remains `cortex-agent-session-.lock` during the
-compatibility window. Both old and new executables acquire the same lock;
-using separate names would allow two versions to mutate one SQLite session
-at once. Huginn does not delete, copy or rewrite legacy SQLite databases
-through a plain file copy.
-
-## Development and architecture
-
-- Code: [`apps/huginn`](../../apps/huginn/), [`core`](../../crates/huginn/core/), [`runtime`](../../crates/huginn/runtime/).
-- [Implementation specification](implementation-specification.md) β contracts and limits.
-- [Architecture decisions](adr/README.md) β accepted ADRs.
-- [Implementation plan](implementation-plan.md) β milestones and acceptance boundaries.
-- [Linux daily-use checklist](linux-daily-use.md) β manual acceptance workflow on Linux.
-- [Validation record](validation.md) β automated and manual evidence; status of open items.
-- `just huginn-test` runs deterministic kernel, coding, HTTP, MCP and CLI fixtures.
-- `./scripts/huginn-linux-smoke.sh` verifies the local install on a Linux host without contacting a model.
-- `just ci-local` runs the complete workspace gate, including Rook and Docker E2E.
-
-Huginn is independent of Rook's abstractions; Rook is not a supported backend
-as of 2026-10-06 β see
-[validation.md Β§ Rook compatibility result](validation.md#rook-compatibility-result).
-Real-model validation and a Linux daily-use run must be recorded before
-declaring the personal MVP fully accepted. MCP transport fixtures
-require Python 3 at `/usr/bin/python3` on the supported platforms.
-
-Obsidian's rust-agent-harness-research remains the research source. The
-repository is the canonical source of implementation specifications and
-ADRs.
+# 1. Set environment variables
+export HUGINN_BASE_URL=https://api.openai.com/v1
+export HUGINN_MODEL=gpt-4o
+export HUGINN_API_KEY=your-api-key
+
+# 2. Run in chat mode
+huginn --workspace /path/to/your/project chat
+
+# 3. Or run a single command
+huginn --workspace /path/to/your/project run "Explain this codebase"
+```
+
+### Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `huginn chat` | Interactive TUI chat (default) |
+| `huginn run ""` | Single command, exit |
+| `huginn sessions` | List saved sessions |
+| `huginn resume ` | Continue a session |
+| `huginn --json run ""` | JSON output (for scripting) |
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HUGINN_BASE_URL` | For non-mock providers | API endpoint (include `/v1`) |
+| `HUGINN_MODEL` | For non-mock providers | Model name |
+| `HUGINN_API_KEY` | For auth-required providers | API key (optional for mock/Ollama) |
+
+---
+
+## π₯οΈ TUI Guide
+
+When you run `huginn chat`, you get a Ratatui-based terminal interface.
+
+### Layout
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β Huginn - /path/to/workspace [?] [β] [β] β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β β β
+β β π€ Assistant β β
+β β βββββββββββββββββ β β
+β β Welcome to Huginn! Type / for commands. β β
+β β β β
+β β π€ You β β
+β β βββββββββββββββββ β β
+β β Explain the project structure β β
+β β β β
+β β π€ Assistant β β
+β β βββββββββββββββββ β β
+β β This is a Rust monorepo with... β β
+β β β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β > Explain the project structure [Send] β
+β β
+β Model: gpt-4o | Provider: OpenAI | Tokens: 1,234 β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Commands (type `/` to open)
+
+| Command | Description |
+|---------|-------------|
+| `/login` | Configure provider credentials |
+| `/providers` | Switch between providers |
+| `/model` | Change the active model |
+| `/logout` | Clear stored credentials |
+| `/exinfo` | System information |
+| `/clear` | Clear current conversation |
+| `/quit` | Exit Huginn |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+C` | Cancel current request |
+| `Ctrl+L` | Clear screen |
+| `Ctrl+Enter` | Send message |
+| `β/β` | History navigation |
+
+---
+
+## π§ Configuration
+
+### AGENTS.md
+
+Place an `AGENTS.md` file in your repository root to scope Huginn's context:
+
+```markdown
+# Agent Instructions
+
+## Project Context
+This is a Rust monorepo with Rook (AI proxy) and Huginn (coding agent).
+
+## Coding Standards
+- Use 2-space indentation
+- Run `cargo fmt` before commits
+- Follow Rust idioms
+
+## Available Commands
+- `just dev` - Start development
+- `just test` - Run tests
+- `just ci-local` - Full CI locally
+```
+
+### Provider Configuration
+
+Huginn supports OpenAI-compatible APIs:
+
+```bash
+# OpenAI
+export HUGINN_BASE_URL=https://api.openai.com/v1
+export HUGINN_MODEL=gpt-4o
+
+# Anthropic (via proxy)
+export HUGINN_BASE_URL=http://localhost:3773/v1
+export HUGINN_MODEL=claude-3-sonnet-20240229
+
+# Local Ollama
+export HUGINN_BASE_URL=http://localhost:11434/v1
+export HUGINN_MODEL=llama3
+```
+
+### Mock Provider (Offline Testing)
+
+```bash
+# Test without real API calls
+huginn --provider mock --workspace /path/to/repo run "list files"
+```
+
+The mock provider responds with predefined examples and does not perform real LLM calls.
+
+---
+
+## π MCP Integration
+
+Connect Huginn to MCP servers for extended capabilities via CLI configuration:
+
+```toml
+# huginn.toml (or pass via --config)
+[[mcp]]
+name = "filesystem"
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem@0.6.3", "."]
+
+[[mcp]]
+name = "git"
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-git@0.5.0"]
+```
+
+```bash
+# From the Cortex repository root; "." allows filesystem access to this workspace
+huginn --workspace . --config huginn.toml chat
+```
+
+> β οΈ **Security Notice:** MCP servers run with your OS permissions and are not sandboxed. Only connect to servers you trust.
+
+### Available MCP Servers
+
+| Server | Version | Purpose |
+|--------|---------|---------|
+| `@modelcontextprotocol/server-filesystem` | 0.6.3 | File operations |
+| `@modelcontextprotocol/server-git` | 0.5.0 | Git operations |
+| `@modelcontextprotocol/server-brave` | latest | Web search |
+| `@modelcontextprotocol/server-slack` | latest | Slack integration |
+
+---
+
+## π Examples
+
+### Explain Code
+
+```bash
+huginn --workspace ./my-project run "Explain the main.rs entry point"
+```
+
+### Refactor Code
+
+```bash
+huginn --workspace ./my-project run "Refactor the auth module to use async/await"
+```
+
+### Write Tests
+
+```bash
+huginn --workspace ./my-project run "Write unit tests for the UserService"
+```
+
+### Generate Documentation
+
+```bash
+huginn --workspace ./my-project run "Add doc comments to the public API"
+```
+
+### Git Operations
+
+```bash
+huginn --workspace ./my-project run "Create a commit for the new feature with good message"
+```
+
+### JSON Output (CI/CD)
+
+```bash
+huginn --workspace ./my-project --json run "Analyze the code and return metrics"
+```
+
+---
+
+## π§ͺ Testing
+
+```bash
+# Run all tests
+cargo test -p huginn
+
+# With coverage
+cargo tarpaulin -p huginn
+```
+
+---
+
+## π Security
+
+| Concern | Mitigation |
+|---------|------------|
+| API keys | Use environment variables, not config files |
+| File access | Workspace-scoped β Huginn only accesses specified directory |
+| Shell execution | Terminal commands require explicit approval |
+| MCP tools | MCP calls require explicit approval |
+| Session data | SQLite DB stored locally (no built-in encryption) |
+
+### Best Practices
+
+1. **Never commit API keys** β use environment variables
+2. **Review tool calls** β Huginn shows what it will execute
+3. **Scope workspaces** β Use `--workspace` to limit access
+4. **Audit sessions** β Check `huginn sessions` for history
+
+---
+
+## π Resources
+
+| Resource | Description |
+|---------|-------------|
+| [Architecture](adr/README.md) | Design decisions and ADRs |
+| [Providers UI](providers-ui.md) | Provider configuration in TUI |
+| [Rook](../rook/README.md) | Companion AI proxy |
+| [Cortex](../README.md) | Full project documentation |
+
+---
+
+## π License
+
+MIT License - same as [Cortex repository](https://github.com/dallay/cortex).
+
+---
+
+## π Acknowledgments
+
+- Built with [Ratatui](https://ratatui.rs/) for the TUI
+- Inspired by [Claude](https://claude.ai/) and [Cursor](https://cursor.sh/)
+- MCP protocol by [Model Context Protocol](https://modelcontextprotocol.io)
+
+---
+
+