docs: add documentation hub and settings reference (#49)

CHANGELOG.md

@@ -10,4 +10,11 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 
 ### Added
 
-- Created initial CHANGELOG.md structure following the Keep a Changelog standard.
+- Documentation hub at `docs/README.md` with introduction, settings reference, and cross-links to all guides.
+- `docs/introduction.md` — short onboarding and quick start.
+- `docs/SETTINGS.md` — consolidated YAML key reference, `.env` guidance, and Ollama preflight documentation.
+- Created initial CHANGELOG.md structure following the Keep a Changelog standard.
+
+### Changed
+
+- README documentation section now points to the docs hub; project structure tree updated to match the current package layout.

CONTRIBUTING.md

@@ -8,6 +8,8 @@
 
 Thank you for your interest in contributing to Rooms. We welcome contributions from the community to help make this framework even better for local-first multi-agent orchestration.
 
+**Documentation:** see the [docs hub](docs/README.md) for architecture, settings, examples, and testing guides.
+
 ---
 
 ## How to Contribute

README.md

@@ -53,33 +53,39 @@ The framework allows extreme granularity in handling session configurations:
 
 ## Documentation Library
 
-For deeper insights into how to leverage and modify the framework, please refer to our dedicated documentation guides:
-
-- [Architecture & LiteLLM Guide](docs/ARCHITECTURE.md) - Understand local API routing, session memory, orchestration, and tool logging.
-- [Use Cases, Examples & Best Practices](docs/EXAMPLES.md) - Parameter cheat sheet, deep persona guide, scenario walkthroughs, and an edge case reference table.
-- [Skillware Integration Guide](docs/SKILLWARE.md) - Skills CLI commands, wizard assignment flow, and optional dependency behavior.
-- [Testing Strategy](docs/TESTING.md) - How to write and run deterministic tests for multi-agent and skills logic.
-- [Contributing Guide](CONTRIBUTING.md) - Learn how to contribute to the project, report bugs, and follow our design philosophy.
-- [Project Changelog](CHANGELOG.md) - Track all notable updates, fixes, and pre-release changes to the framework.
+**[Documentation hub](docs/README.md)** — start here for the full index (introduction, settings, architecture, examples, skills, testing).
+
+| Guide | Description |
+|-------|-------------|
+| [Introduction](docs/introduction.md) | What Rooms is and a five-minute quick start |
+| [Settings & preflight](docs/SETTINGS.md) | YAML keys, `.env`, search paths, Ollama preflight |
+| [Architecture & LiteLLM](docs/ARCHITECTURE.md) | Session memory, orchestration, transcripts, custom models |
+| [Examples & best practices](docs/EXAMPLES.md) | Parameter cheat sheet, personas, scenarios, edge cases |
+| [Skillware integration](docs/SKILLWARE.md) | Skills CLI, wizard assignment, runtime behavior |
+| [Testing](docs/TESTING.md) | Pytest, mocking, CI smoke tests |
+| [Contributing](CONTRIBUTING.md) | Bugs, PRs, design philosophy |
+| [Changelog](CHANGELOG.md) | Notable updates |
 
 ## Project Structure
 
 ```bash
 Rooms/
-├── rooms/              # Core Package
-│   ├── __init__.py
-│   ├── config.py       # Pydantic Configuration Models
-│   ├── agent.py        # Agent & LiteLLM/Custom Logic
-│   ├── session.py      # Turn Orchestration & Memory
-│   ├── settings.py     # YAML settings loader
-│   └── storage.py      # Secure Log Serialization
-├── tests/              # Unit Tests
-│   └── test_session.py # Logic Verification
-├── outputs/            # Session Transcripts
-├── cli.py                      # Interactive Wizard Entry Point      
+├── rooms/                      # Core package
+│   ├── agent.py                # Agent inference (LiteLLM / custom functions)
+│   ├── config.py               # Pydantic session & agent models
+│   ├── env.py                  # Optional .env bootstrap
+│   ├── ollama_preflight.py     # Local Ollama connectivity check
+│   ├── session.py              # Turn orchestration & memory
+│   ├── settings.py             # YAML settings loader
+│   ├── skills_cli.py           # Rooms-native Skillware CLI helpers
+│   ├── skills_runtime.py       # Lazy skill load & tool execution
+│   └── storage.py              # Transcript export (Markdown / CSV)
+├── docs/                       # Documentation hub (see docs/README.md)
+├── tests/                      # Pytest suite
+├── cli.py                      # Interactive wizard entry point
 ├── rooms.settings.example.yaml # Settings template (commit this)
-├── requirements.txt            # Core Project Dependencies
-└── requirements-memory.txt     # Optional Vector Memory Dependencies
+├── requirements.txt            # Core dependencies (includes skillware)
+└── requirements-memory.txt     # Optional vector memory dependencies
 ```
 
 `rooms.settings.yaml` is gitignored — create it locally with `python cli.py config init` or by copying the example file.
@@ -108,13 +114,15 @@ pip install -r requirements-memory.txt
 
 ### 2. Configure defaults (optional)
 
-You do **not** need a settings file to run the CLI — built-in defaults apply (see `rooms.settings.example.yaml` for the shape). To customize per machine, create a local file (gitignored):
+You do **not** need a settings file to run the CLI — built-in defaults apply. For the full YAML key reference, search paths, and Ollama preflight, see **[docs/SETTINGS.md](docs/SETTINGS.md)**.
+
+To customize per machine, create a local file (gitignored):
 
 | File | In git? | Purpose |
 |------|---------|---------|
 | `rooms.settings.example.yaml` | Yes (template) | Committed reference; copy or use `config init` |
 | `rooms.settings.yaml` | No (gitignored) | Your local overrides (model tag, user name, personas) |
-| `.env` | No (gitignored) | API keys and secrets for cloud LiteLLM providers |
+| `.env` | No (gitignored) | API keys and skill secrets (see [SETTINGS.md](docs/SETTINGS.md)) |
 
 ```bash
 python cli.py config init    # copies example → rooms.settings.yaml in cwd
@@ -124,13 +132,14 @@ python cli.py config reset   # remove user file; revert to shipped defaults
 python cli.py --config path/to/settings.yaml
 ```
 
-**API keys (cloud models only)**
+**API keys and skill secrets**
 
-LiteLLM reads provider credentials from the process environment (not from YAML). For local development, copy `.env.example` to `.env` and set keys such as `DEEPSEEK_API_KEY` or `OPENAI_API_KEY`. Rooms loads `.env` automatically at startup (shell/CI env vars take precedence).
+LiteLLM and Skillware read credentials from the **process environment** (not from YAML). Rooms loads `.env` automatically at startup (shell/CI env vars take precedence). See [docs/SETTINGS.md](docs/SETTINGS.md) for details and skill variables such as `ETHERSCAN_API_KEY`.
 
 ```bash
 copy .env.example .env   # Windows
-# edit .env with your provider key(s)
+# cp .env.example .env   # macOS / Linux
+# edit .env with your provider and skill keys
 ```
 
 ### 3. Usage

docs/ARCHITECTURE.md

@@ -1,5 +1,7 @@
 # Multi-Agent Rooms Architecture
 
+> **Navigation:** [Documentation hub](README.md) · [Settings & preflight](SETTINGS.md) · [Introduction](introduction.md)
+
 ## How LiteLLM Works
 **LiteLLM is a universal routing library, not an AI model or an API endpoint itself.**
 
@@ -16,6 +18,8 @@ When the Agents reply to you in the terminal, it means your computer's local CPU
 
 ## User settings (optional)
 
+> **Full reference:** YAML keys, search paths, `.env`, and preflight are documented in [SETTINGS.md](SETTINGS.md).
+
 Default model strings, timeouts, user profile, and optional persona overrides are loaded from YAML at CLI startup (`rooms/settings.py`). **No file is required** — if `rooms.settings.yaml` is missing, built-in defaults apply (same values as `rooms.settings.example.yaml`).
 
 | File | Committed? | Role |

docs/EXAMPLES.md

@@ -1,5 +1,7 @@
 # Use Cases, Examples & Best Practices
 
+> **Navigation:** [Documentation hub](README.md) · [Settings & preflight](SETTINGS.md) · [Introduction](introduction.md)
+
 The Multi-Agent Rooms framework is extremely versatile. This guide covers practical use cases, how to configure agents for best results, scenario tips, and common edge cases to be aware of.
 
 ---
@@ -225,6 +227,9 @@ The quality of your agents is entirely determined by the quality of their system
 ## Advanced CLI Reference
 
 ### Skipping Preflight Checks
+
+See [SETTINGS.md — Ollama preflight](SETTINGS.md#ollama-preflight) for when preflight runs and how to configure Ollama.
+
 If you are running the application in a CI/CD automation environment, running automated test configurations, or simply wish to bypass the local Ollama connectivity and model verification sequence, append the `--skip-preflight` flag alongside your execution statement:
 
 ```bash

docs/README.md

@@ -0,0 +1,40 @@
+# Rooms Documentation
+
+Welcome to the Rooms documentation hub. Start here to find the right guide by audience and task.
+
+## Start here
+
+| If you want to… | Read |
+|-----------------|------|
+| Understand what Rooms is and run your first session | [Introduction](introduction.md) |
+| Configure models, YAML, `.env`, and Ollama preflight | [Settings & preflight](SETTINGS.md) |
+| See scenario walkthroughs and parameter tips | [Examples & best practices](EXAMPLES.md) |
+
+## Deep dives
+
+| Topic | Guide |
+|-------|--------|
+| LiteLLM routing, session memory, orchestration, transcripts | [Architecture](ARCHITECTURE.md) |
+| Skillware skills CLI, wizard assignment, runtime behavior | [Skillware integration](SKILLWARE.md) |
+| Pytest strategy, mocking, CI smoke tests | [Testing](TESTING.md) |
+
+## Project meta
+
+| Topic | Location |
+|-------|----------|
+| Contributing, design philosophy, PR workflow | [CONTRIBUTING.md](../CONTRIBUTING.md) |
+| Notable changes | [CHANGELOG.md](../CHANGELOG.md) |
+| Roadmap and open work | [GitHub Issues](https://github.com/arpahls/Rooms/issues) |
+
+## Related issues
+
+- **Settings key semantics and override rules** are tracked separately from this hub; see the settings reference in [SETTINGS.md](SETTINGS.md) and `rooms.settings.example.yaml`.
+- **This hub** focuses on navigation and discoverability so architecture, examples, and configuration are easy to find in one place.
+
+## Install paths
+
+| Method | Status | Command |
+|--------|--------|---------|
+| Clone from GitHub | **Supported** | `git clone https://github.com/arpahls/Rooms.git` |
+| Editable local install | **Supported** | `pip install -r requirements.txt` in a venv after clone |
+| PyPI package | **Planned** | Not published yet — install from source for now |

docs/SETTINGS.md

@@ -0,0 +1,169 @@
+# Settings & preflight
+
+Rooms separates **configuration** (YAML), **credentials** (environment / `.env`), and **runtime checks** (Ollama preflight). This page is the single reference for all three.
+
+For deep architecture context (memory, orchestration, LiteLLM), see [ARCHITECTURE.md](ARCHITECTURE.md). For scenario tuning, see [EXAMPLES.md](EXAMPLES.md).
+
+---
+
+## Configuration files
+
+| File | In git? | Purpose |
+|------|---------|---------|
+| `rooms.settings.example.yaml` | Yes | Committed template — documents every supported key |
+| `rooms.settings.yaml` | No (gitignored) | Your local overrides (model, personas, user profile) |
+| `.env` | No (gitignored) | API keys and skill-related secrets (never put keys in YAML) |
+| `.env.example` | Yes | Template for optional provider keys |
+
+**Rule:** `rooms.settings.yaml` holds non-secrets only. LiteLLM provider keys and skill `env_vars` (e.g. `ETHERSCAN_API_KEY`) belong in the process environment or `.env`.
+
+---
+
+## Settings search order
+
+The CLI loads the **first file that exists**:
+
+1. `--config path/to/settings.yaml` (explicit)
+2. `./rooms.settings.yaml` (current working directory)
+3. User config directory:
+   - Windows: `%APPDATA%\rooms\settings.yaml`
+   - macOS / Linux: `~/.config/rooms/settings.yaml`
+
+If none exist, **built-in defaults** apply (same shape as `rooms.settings.example.yaml`).
+
+### CLI helpers
+
+```bash
+python cli.py config init    # copy example → ./rooms.settings.yaml
+python cli.py config reset   # remove local settings file(s)
+python cli.py --config path/to/settings.yaml
+```
+
+---
+
+## YAML key reference
+
+Top-level keys in `rooms.settings.yaml`:
+
+### `defaults`
+
+Global fallbacks for personas and orchestrator unless overridden per persona.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `litellm_model` | string | `ollama/gemma4:e2b` | LiteLLM model string (`ollama/tag`, `openai/gpt-4o`, etc.) |
+| `orchestrator_model` | string | *(same as `litellm_model`)* | Model for the global orchestrator when enabled |
+| `temperature` | float | `0.7` | Default sampling temperature |
+| `timeout` | int | `30` | Inference timeout in seconds |
+
+### `presets`
+
+Named model shortcuts (optional). Used when selecting a preset in tooling; keys are arbitrary names.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `litellm_model` | string | Model string for this preset |
+| `api_key_env` | string | Env var name hint for cloud providers (documentation only) |
+
+### `ollama`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `base_url` | string | `http://localhost:11434` | Ollama API base; sets `OLLAMA_API_BASE` when loaded |
+| `auto_select_first` | bool | `false` | Reserved for future auto-model selection |
+
+### `user`
+
+Wizard defaults for the human participant.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `name` | string | `User` | Display name in the room |
+| `background` | string | `""` | Role / bio shown to agents |
+
+### `use_shipped_personas`
+
+| Value | Behavior |
+|-------|----------|
+| `true` (default) | Use built-in Elena, Viktor, Nyx personas |
+| `false` | Use custom `personas` list below (or fall back to shipped if list empty) |
+
+### `personas` (optional list)
+
+Override or replace shipped personas entirely when `use_shipped_personas: false`.
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | string | yes | Agent display name |
+| `system_prompt` | string | yes | Persona instructions |
+| `expertise` | list[string] | no | Keywords for `dynamic` mode routing |
+| `model` | string | no | Per-agent model; falls back to `defaults.litellm_model` |
+| `temperature` | float | no | Falls back to `defaults.temperature` |
+| `color` | string | no | Rich terminal color (e.g. `yellow`, `magenta`) |
+| `skills` | list[string] | no | Skillware skill IDs (e.g. `finance/wallet_screening`) |
+| `skill_settings` | object | no | Per-skill override map (`skill_id` → `{key: value}`) |
+
+**Override rule:** Persona-level `model` / `temperature` / `timeout` win over `defaults` for that agent only. Session wizard choices can still override per run.
+
+---
+
+## Environment variables (`.env`)
+
+Rooms separates credentials from YAML. LiteLLM and Skillware read keys from the **process environment**.
+
+Rooms bootstraps `.env` automatically at CLI startup and when settings load (`rooms/env.py`):
+
+1. Existing shell/CI environment variables (highest priority)
+2. `.env` in the current working directory
+3. `.env` in the repository root
+
+For local development, copy `.env.example` to `.env` and set provider keys (`OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, …) and any skill `env_vars` (e.g. `ETHERSCAN_API_KEY`).
+
+```bash
+copy .env.example .env   # Windows
+# cp .env.example .env   # macOS / Linux
+```
+
+Never commit `.env`. Skill-specific requirements are listed in each skill manifest (`python cli.py skills inspect <skill_id>`).
+
+---
+
+## Ollama preflight
+
+Before the wizard starts, Rooms checks whether:
+
+1. Ollama is reachable at `ollama.base_url`, and
+2. The configured `defaults.litellm_model` tag exists locally (when model starts with `ollama/`).
+
+If the check fails, the CLI prints actionable fixes (`ollama serve`, `ollama pull <tag>`, edit settings).
+
+### Skip preflight
+
+For CI, automation, or when you know Ollama is not needed:
+
+```bash
+python cli.py --skip-preflight
+```
+
+Preflight is implemented in `rooms/ollama_preflight.py` and only applies to `ollama/` models.
+
+---
+
+## Local Ollama tips
+
+```bash
+ollama list          # installed models
+ollama ps            # models loaded in memory right now
+ollama pull <tag>    # download a model
+```
+
+Set `defaults.litellm_model` to `ollama/<tag>` matching `ollama list` (e.g. `ollama/qwen3.5:4b`).
+
+---
+
+## See also
+
+- [Introduction](introduction.md) — first run
+- [Examples](EXAMPLES.md) — parameter cheat sheet and scenarios
+- [Architecture](ARCHITECTURE.md) — session memory and orchestration
+- [Documentation index](README.md)

docs/SKILLWARE.md

@@ -1,5 +1,7 @@
 # Skillware Integration
 
+> **Navigation:** [Documentation hub](README.md) · [Settings & preflight](SETTINGS.md) (skill `env_vars` in `.env`)
+
 Rooms supports optional Skillware-based tool use for agents.
 
 ## Design Principles

docs/TESTING.md

@@ -1,5 +1,7 @@
 # Testing Strategy
 
+> **Navigation:** [Documentation hub](README.md) · [Settings & preflight](SETTINGS.md) (CLI smoke tests)
+
 The Multi-Agent Rooms framework places paramount importance on reliability and predictable logic flow, particularly concerning the orchestration of multiple AI agents and the preservation of human-in-the-loop interventions.
 
 ## Our Testing Approach