docs: restructure documentation around user journey

docs/src/SUMMARY.md

@@ -1,58 +1,70 @@
 # Summary
 
 [Introduction](introduction.md)
+[Why Zeph?](why-zeph.md)
 
 # Getting Started
 
 - [Installation](getting-started/installation.md)
-- [Quick Start](getting-started/quick-start.md)
-- [Configuration](getting-started/configuration.md)
-
-# Guide
-
-- [CLI Reference](guide/cli.md)
-- [Skills](guide/skills.md)
-- [Semantic Memory](guide/semantic-memory.md)
-- [Context Engineering](guide/context.md)
-- [Conversation Summarization](guide/summarization.md)
-- [Docker Deployment](guide/docker.md)
-- [MCP Integration](guide/mcp.md)
-- [OpenAI Provider](guide/openai.md)
-- [Local Inference (Candle)](guide/candle.md)
-- [Model Orchestrator](guide/orchestrator.md)
-- [Self-Learning Skills](guide/self-learning.md)
-- [Skill Trust Levels](guide/skill-trust.md)
-- [A2A Protocol](guide/a2a.md)
-- [Secrets Management](guide/vault.md)
-- [Channels (CLI, Telegram, TUI)](guide/channels.md)
-- [Tool System](guide/tools.md)
-- [Pipeline API](guide/pipeline.md)
-- [Audio Input](guide/audio-input.md)
-- [Vision (Image Input)](guide/vision.md)
-- [TUI Dashboard](guide/tui.md)
-- [Observability & Cost](guide/observability.md)
-- [Code Indexing](guide/code-indexing.md)
-- [HTTP Gateway](guide/gateway.md)
-- [Daemon Supervisor](guide/daemon.md)
-- [Cron Scheduler](guide/scheduler.md)
-- [Document Loaders](guide/document-loaders.md)
+- [First Conversation](getting-started/first-conversation.md)
+- [Configuration Wizard](getting-started/wizard.md)
+
+# Core Concepts
+
+- [Skills](concepts/skills.md)
+- [Memory & Context](concepts/memory.md)
+- [LLM Providers](concepts/providers.md)
+- [Tools](concepts/tools.md)
+
+# Guides
+
+- [Use a Cloud Provider](guides/cloud-provider.md)
+- [Run via Telegram](guides/telegram.md)
+- [Add Custom Skills](guides/custom-skills.md)
+- [Connect MCP Servers](guides/mcp.md)
+- [Set Up Semantic Memory](guides/semantic-memory.md)
+- [Deploy with Docker](guides/docker.md)
+
+# Advanced
+
+- [Model Orchestrator](advanced/orchestrator.md)
+- [Self-Learning Skills](advanced/self-learning.md)
+- [Skill Trust & Security](advanced/skill-trust.md)
+- [A2A Protocol](advanced/a2a.md)
+- [Code Indexing](advanced/code-indexing.md)
+- [Pipeline API](advanced/pipeline.md)
+- [Context Engineering](advanced/context.md)
+- [Audio & Vision](advanced/multimodal.md)
+- [TUI Dashboard](advanced/tui.md)
+- [HTTP Gateway](advanced/gateway.md)
+- [Daemon & Scheduler](advanced/daemon.md)
+- [Document Loaders](advanced/document-loaders.md)
+- [Observability & Cost](advanced/observability.md)
+- [Channels](advanced/channels.md)
+- [Tool System](advanced/tools.md)
+- [Local Inference (Candle)](advanced/candle.md)
 
 # Architecture
 
 - [Overview](architecture/overview.md)
-- [Crates](architecture/crates.md)
+- [Crate Map](architecture/crates.md)
 - [Token Efficiency](architecture/token-efficiency.md)
 - [Performance](architecture/performance.md)
 
+# Reference
+
+- [CLI Reference](reference/cli.md)
+- [Configuration](reference/configuration.md)
+- [Feature Flags](reference/feature-flags.md)
+- [Security](reference/security.md)
+  - [MCP Security](reference/security/mcp.md)
+
 # Development
 
 - [sccache](development/sccache.md)
 - [TUI Testing](development/tui-testing.md)
 
 ---
 
-- [Security](security.md)
-  - [MCP Security](security/mcp.md)
-- [Feature Flags](feature-flags.md)
 - [Contributing](contributing.md)
 - [Changelog](changelog.md)

docs/src/advanced/channels.md

@@ -0,0 +1,95 @@
+# Channels
+
+Zeph supports five I/O channels. Each implements the `Channel` trait and can be selected at runtime.
+
+## Overview
+
+| Channel | Activation | Streaming | Confirmation |
+|---------|-----------|-----------|--------------|
+| CLI | Default | Token-by-token to stdout | y/N prompt |
+| Discord | `ZEPH_DISCORD_TOKEN` (requires `discord` feature) | Edit-in-place every 1.5s | Reply "yes" |
+| Slack | `ZEPH_SLACK_BOT_TOKEN` (requires `slack` feature) | `chat.update` every 2s | Reply "yes" |
+| Telegram | `ZEPH_TELEGRAM_TOKEN` | Edit-in-place every 10s | Reply "yes" |
+| TUI | `--tui` flag (requires `tui` feature) | Real-time in chat panel | Auto-confirm |
+
+## CLI Channel
+
+Default channel. Reads from stdin, writes to stdout with immediate streaming. Persistent input history (rustyline): arrow keys to navigate, prefix search, Emacs keybindings (Ctrl+A/E, Alt+B/F, Ctrl+W). History stored in SQLite across restarts.
+
+## Telegram Channel
+
+See [Run via Telegram](../guides/telegram.md) for the setup guide. User whitelisting required (`allowed_users` must not be empty). MarkdownV2 formatting, voice/image support, 10s streaming throttle, 4096 char message splitting.
+
+## Discord Channel
+
+### Setup
+
+1. Create an application at the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Copy the bot token, select `bot` + `applications.commands` scopes
+3. Configure:
+
+```bash
+ZEPH_DISCORD_TOKEN="..." ZEPH_DISCORD_APP_ID="..." zeph
+```
+
+```toml
+[discord]
+allowed_user_ids = []
+allowed_role_ids = []
+allowed_channel_ids = []
+```
+
+When all allowlists are empty, the bot accepts messages from all users.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ask <message>` | Send a message to the agent |
+| `/clear` | Reset conversation context |
+
+Streaming: 1.5s throttle, messages split at 2000 chars.
+
+## Slack Channel
+
+### Setup
+
+1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
+2. Add `chat:write` scope, install to workspace, copy Bot User OAuth Token
+3. Copy Signing Secret from Basic Information
+4. Enable Event Subscriptions, set URL to `http://<host>:<port>/slack/events`
+5. Subscribe to `message.channels` and `message.im` bot events
+
+```bash
+ZEPH_SLACK_BOT_TOKEN="xoxb-..." ZEPH_SLACK_SIGNING_SECRET="..." zeph
+```
+
+Security: HMAC-SHA256 signature verification, 5-minute replay protection, 256 KB body limit. Self-message filtering via `auth.test` at startup.
+
+Streaming: 2s throttle via `chat.update`.
+
+## TUI Dashboard
+
+Rich terminal interface based on ratatui. See [TUI Dashboard](tui.md) for full documentation.
+
+```bash
+zeph --tui
+```
+
+## Channel Selection Priority
+
+1. `--tui` flag or `ZEPH_TUI=true` → TUI
+2. Discord config with token → Discord
+3. Slack config with bot_token → Slack
+4. `ZEPH_TELEGRAM_TOKEN` set → Telegram
+5. Default → CLI
+
+Only one channel is active per session.
+
+## Message Queueing
+
+Bounded FIFO queue (max 10 messages) handles input received during model inference. Consecutive messages within 500ms are merged. CLI is blocking (no queue). TUI shows a `[+N queued]` badge; press `Ctrl+K` to clear.
+
+## Attachments
+
+Audio and image attachments are supported on Telegram, Slack, CLI/TUI (via `/image`). See [Audio & Vision](multimodal.md).

docs/src/advanced/daemon.md

@@ -0,0 +1,98 @@
+# Daemon and Scheduler
+
+Run Zeph as a long-running process with component supervision and cron-based periodic tasks.
+
+## Daemon Supervisor
+
+The daemon manages component lifecycles (gateway, scheduler, A2A server), monitors for unexpected exits, and tracks restart counts.
+
+### Feature Flag
+
+```bash
+cargo build --release --features daemon
+```
+
+### Configuration
+
+```toml
+[daemon]
+enabled = true
+pid_file = "~/.zeph/zeph.pid"
+health_interval_secs = 30
+max_restart_backoff_secs = 60
+```
+
+### Component Lifecycle
+
+Each registered component is tracked with a status (`Running`, `Failed(reason)`, or `Stopped`) and a restart counter. The supervisor polls all components at `health_interval_secs` intervals.
+
+### PID File
+
+Written on startup for instance detection and stop signals. Tilde (`~`) expands to `$HOME`. Parent directory is created automatically.
+
+## Cron Scheduler
+
+Run periodic tasks on cron schedules with SQLite-backed persistence.
+
+### Feature Flag
+
+```bash
+cargo build --release --features scheduler
+```
+
+### Configuration
+
+```toml
+[scheduler]
+enabled = true
+
+[[scheduler.tasks]]
+name = "memory_cleanup"
+cron = "0 0 0 * * *"          # daily at midnight
+kind = "memory_cleanup"
+config = { max_age_days = 90 }
+
+[[scheduler.tasks]]
+name = "health_check"
+cron = "0 */5 * * * *"        # every 5 minutes
+kind = "health_check"
+```
+
+Cron expressions use 6 fields: `sec min hour day month weekday`. Standard features supported: ranges (`1-5`), lists (`1,3,5`), steps (`*/5`), wildcards (`*`).
+
+### Built-in Tasks
+
+| Kind | Description |
+|------|-------------|
+| `memory_cleanup` | Remove old conversation history entries |
+| `skill_refresh` | Re-scan skill directories for changes |
+| `health_check` | Internal health verification |
+| `update_check` | Query GitHub Releases API for newer versions |
+
+### Update Check
+
+Controlled by `auto_update_check` in `[agent]` (default: true):
+
+- **With scheduler**: runs daily at 09:00 UTC via cron task
+- **Without scheduler**: single one-shot check at startup
+
+### Custom Tasks
+
+Implement the `TaskHandler` trait:
+
+```rust
+pub trait TaskHandler: Send + Sync {
+    fn execute(
+        &self,
+        config: &serde_json::Value,
+    ) -> Pin<Box<dyn Future<Output = Result<(), SchedulerError>> + Send + '_>>;
+}
+```
+
+### Persistence
+
+Job metadata is stored in a `scheduled_jobs` SQLite table. The scheduler ticks every 60 seconds and checks whether each task is due based on `last_run` and the cron expression.
+
+## Shutdown
+
+Both daemon and scheduler listen on the global shutdown signal and exit gracefully.