fix: repair docs site build — replace symlink with path config, create missing pages

The docs site never built after the monorepo consolidation. The symlink
(site/docs -> ../docs) caused Docusaurus SSG to crash — it partially
processes excluded directories through symlinks, hitting MDX-incompatible
content in reference/. Additionally, the sidebar referenced 5 files that
didn't exist.

- Replace docs symlink with `path: '../docs'` in docusaurus.config.ts
- Create getting-started/* pages (installation, telegram-setup, setup-wizard, first-message)
- Create docs/intro.md as docs landing page and docs/development/contributing.md
- Fix sidebar: setup-wizard-internals → setup-wizard
- Move deploy workflow from site/.github/ to .github/ (GitHub Actions only reads repo root)
- Update baseUrl/projectName from adjutant-docs to adjutant
- Exclude reference/web/plans/README.md from Docusaurus build
- Fix homepage link /docs/intro → /docs/
- Update docs/README.md index with memory, news, troubleshooting guides

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: eddiman

site/.github/workflows/deploy.yml .github/workflows/deploy-docs.ymlsite/.github/workflows/deploy.yml renamed to .github/workflows/deploy-docs.yml

@@ -3,6 +3,9 @@ name: Deploy Docs
 on:
   push:
     branches: [main]
+    paths:
+      - 'docs/**'
+      - 'site/**'
   workflow_dispatch:
 
 permissions:
@@ -17,13 +20,17 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: site
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: npm
+          cache-dependency-path: site/package-lock.json
 
       - run: npm ci
       - run: npm run build
@@ -32,7 +39,7 @@ jobs:
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: build
+          path: site/build
 
   deploy:
     environment:

AGENTS.md

@@ -73,7 +73,7 @@ adjutant/                                 # Monorepo
 │       └── package.json
 │
 ├── site/                                 # Docusaurus documentation site
-│   ├── docs -> ../docs                   # Symlink to source of truth
+│   ├── (reads ../docs via config)         # path: '../docs' in docusaurus.config.ts
 │   ├── docusaurus.config.ts
 │   ├── sidebars.ts
 │   └── package.json

docs/README.md

@@ -4,20 +4,35 @@ Adjutant is a persistent autonomous agent framework that runs on your local mach
 
 ---
 
+## Getting Started
+
+| Document | What it covers |
+|----------|---------------|
+| [Installation](getting-started/installation.md) | Prerequisites, clone, install, shell alias |
+| [Telegram Setup](getting-started/telegram-setup.md) | Create a bot, get your chat ID |
+| [Setup Wizard](getting-started/setup-wizard.md) | Run `adjutant setup`, backend selection, repair mode |
+| [First Message](getting-started/first-message.md) | Start the listener, send your first message |
+
+Or read the [comprehensive guide](guides/getting-started.md) for all steps on one page.
+
+---
+
 ## Guides
 
 For people using Adjutant.
 
 | Document | What it covers |
 |----------|---------------|
-| [Getting Started](guides/getting-started.md) | Install, setup wizard, send your first message |
 | [Configuration](guides/configuration.md) | `adjutant.yaml`, `.env`, identity files (`soul.md`, `heart.md`, `registry.md`) |
 | [Commands](guides/commands.md) | All Telegram slash commands and `adjutant` CLI subcommands |
+| [Backends](guides/backends.md) | Choosing, configuring, and switching LLM backends (OpenCode / Claude CLI) |
 | [Knowledge Bases](guides/knowledge-bases.md) | Creating, structuring, and querying knowledge bases |
 | [Schedules](guides/schedules.md) | Cron-based scheduled jobs, KB operations, registry management |
 | [Autonomy](guides/autonomy.md) | Autonomous pulse/review cycles, notification budget, dry-run mode |
 | [Lifecycle](guides/lifecycle.md) | Start, stop, pause, kill, recover, and update |
-| [Backends](guides/backends.md) | Choosing, configuring, and switching LLM backends (OpenCode / Claude CLI) |
+| [Memory](guides/memory.md) | Long-term memory: `/remember`, `/forget`, `/recall`, `/digest` |
+| [News](guides/news.md) | News briefing pipeline: sources, filters, delivery |
+| [Troubleshooting](guides/troubleshooting.md) | Common issues and fixes |
 
 ---
 
@@ -43,11 +58,12 @@ For people extending or contributing to Adjutant.
 
 | Document | What it covers |
 |----------|---------------|
+| [Contributing](development/contributing.md) | Dev setup, code conventions, project structure |
 | [Adaptor Guide](development/adaptor-guide.md) | How to build a new messaging backend (Slack, Discord, CLI, etc.) |
 | [Plugin Guide](development/plugin-guide.md) | How to add a new capability script |
+| [Backend Guide](development/backend-guide.md) | Working with the backend abstraction, adding call sites, testing |
 | [Setup Wizard Internals](development/setup-wizard.md) | `adjutant setup` implementation: steps, dry-run, prompt helpers |
 | [Testing](development/testing.md) | Running the test suite, tier overview, isolation model |
-| [Backend Guide](development/backend-guide.md) | Working with the backend abstraction, adding call sites, testing |
 
 ---
 

docs/development/contributing.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Development setup
+
+```bash
+git clone https://github.com/eddiman/adjutant.git
+cd adjutant
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## Dev commands
+
+```bash
+.venv/bin/pytest tests/ -q              # run tests
+.venv/bin/mypy src/adjutant/ --strict   # type check
+.venv/bin/ruff check src/ tests/        # lint
+```
+
+## Code conventions
+
+- **LLM calls**: `get_backend().run()` — never call backends directly.
+- **Imports**: stdlib, then third-party, then local, alphabetical within each group.
+- **Logging**: `adj_log("component", "msg")` — no `print()`.
+- **Paths**: `get_adj_dir()` — never hardcode.
+- **Capabilities**: return string or raise, no stdout.
+- **Tests**: every module gets `tests/unit/test_<module>.py`.
+
+## Project structure
+
+```
+src/adjutant/
+├── cli.py                 # CLI dispatcher (Click)
+├── core/                  # Backend protocol, config, env, logging, paths
+├── lib/                   # HTTP client, NDJSON/JSON parsers
+├── lifecycle/             # Pause/resume/restart, cron jobs, self-update
+├── capabilities/          # KB, memory, schedule, screenshot, search, vision
+├── messaging/             # Dispatch + Telegram adaptor
+├── news/                  # News fetch, analyze, briefing pipeline
+├── observability/         # Journal rotation, status, usage tracking
+└── setup/                 # Setup wizard, install, repair, uninstall
+```
+
+See [Architecture Overview](../architecture/overview.md) for detailed diagrams and the [Backend Guide](backend-guide.md) for working with the LLM abstraction.
+
+## Adding a new capability
+
+Follow the [Plugin Guide](plugin-guide.md) for step-by-step instructions on adding capability modules.
+
+## Adding a new messaging backend
+
+Follow the [Adaptor Guide](adaptor-guide.md) to implement a new messaging channel (Slack, Discord, CLI, etc.).

docs/getting-started/first-message.md

@@ -0,0 +1,38 @@
+# First Message
+
+With setup complete, start the Telegram listener and verify Adjutant is working.
+
+## Start the listener
+
+```bash
+adjutant start
+```
+
+The Telegram listener starts in the background. Verify it's running:
+
+```bash
+adjutant status
+```
+
+You should see `Adjutant is up and running.` and the listener's PID.
+
+## Send a message
+
+Open Telegram and send a message to your bot. Try these:
+
+| Message | What happens |
+|---------|-------------|
+| `/status` | Adjutant replies with its current operational state |
+| `/help` | Lists all available slash commands |
+| `/models` | Shows available LLM models |
+| `What time is it?` | A natural language question routed to the LLM backend |
+
+That's it. Adjutant is running.
+
+## Next steps
+
+- **Configure what Adjutant knows about you** — [Configuration](../guides/configuration.md)
+- **See all commands** — [Commands](../guides/commands.md)
+- **Add a knowledge base** — [Knowledge Bases](../guides/knowledge-bases.md)
+- **Understand start/stop/pause** — [Lifecycle](../guides/lifecycle.md)
+- **Set up autonomous cycles** — [Autonomy](../guides/autonomy.md)

docs/getting-started/installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+## Prerequisites
+
+Before installing, make sure you have:
+
+- **macOS or Linux**
+- **Python 3.11+** — `python3 --version` to check
+- **An LLM backend** — either [OpenCode](https://opencode.ai) or [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- **curl** (installed on every macOS/Linux system by default)
+
+Check your backend is working:
+
+```bash
+# OpenCode
+opencode --version
+
+# Or Claude Code CLI
+claude --version
+```
+
+## Install
+
+Clone the repository to any location you like — Adjutant can live anywhere:
+
+```bash
+git clone https://github.com/eddiman/adjutant.git /path/to/adjutant
+cd /path/to/adjutant
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+This installs the `adjutant` CLI entry point into `.venv/bin/adjutant`. Add it to your shell profile (adjust the path to match where you cloned):
+
+```bash
+echo 'alias adjutant="/path/to/adjutant/.venv/bin/adjutant"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+The setup wizard will ask for the install path and write it to `adjutant.yaml`. Adjutant resolves its own location from that file — no hardcoded paths required.
+
+## Auto-start on boot (macOS)
+
+To keep Adjutant running across reboots, use `adjutant startup` which installs a LaunchAgent. See [Lifecycle](../guides/lifecycle.md) for details.
+
+## Next step
+
+[Create a Telegram bot](telegram-setup.md) to give Adjutant a messaging channel.

docs/getting-started/setup-wizard.md

@@ -0,0 +1,54 @@
+# Setup Wizard
+
+Run the interactive setup wizard to configure your Adjutant installation:
+
+```bash
+adjutant setup
+```
+
+## Wizard steps
+
+The wizard walks through seven steps:
+
+1. **Prerequisites** — verifies dependencies are in place (Python, backend CLI, curl)
+2. **Install path** — confirms where Adjutant lives on disk
+3. **Backend** — choose between OpenCode and Claude Code CLI (see [Backends](../guides/backends.md))
+4. **Identity** — creates your `soul.md`, `heart.md`, and `registry.md` files (see [Configuration](../guides/configuration.md))
+5. **Messaging** — prompts for your Telegram bot token and chat ID, writes them to `.env`
+6. **Features** — optional news briefing, screenshot, vision, and search configuration
+7. **Service** — installs the shell alias and optionally sets up auto-start on boot
+
+## Backend selection
+
+During step 3, the wizard asks which LLM backend to use:
+
+| Backend | Best for |
+|---------|----------|
+| **OpenCode** | Vision support, model listing, session resume |
+| **Claude Code CLI** | Cost tracking, permission allowlists |
+
+You can switch backends later by editing `adjutant.yaml` — see [Backends](../guides/backends.md).
+
+## Repair mode
+
+If something needs fixing after initial setup, re-run in repair mode:
+
+```bash
+adjutant setup --repair
+```
+
+Repair mode runs health checks and offers to fix each issue found.
+
+## Dry-run mode
+
+Preview what the wizard would do without making changes:
+
+```bash
+adjutant setup --dry-run
+```
+
+For implementation details, see [Setup Wizard Internals](../development/setup-wizard.md).
+
+## Next step
+
+[Send your first message](first-message.md) to verify everything is working.

docs/getting-started/telegram-setup.md

@@ -0,0 +1,29 @@
+# Telegram Setup
+
+Adjutant communicates through Telegram. You need a bot token and your chat ID.
+
+## Create a bot
+
+1. Open Telegram and search for `@BotFather`
+2. Send `/newbot`
+3. Follow the prompts — choose a name and username for your bot
+4. BotFather will give you a token that looks like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz` — save it
+
+## Get your chat ID
+
+1. Start a conversation with your new bot (click Start or send any message)
+2. Open this URL in your browser, replacing `YOUR_TOKEN` with your token:
+   ```
+   https://api.telegram.org/botYOUR_TOKEN/getUpdates
+   ```
+3. Find `"chat":{"id":123456789}` in the response — that number is your chat ID
+
+## Security notes
+
+- Your bot token is stored in `.env` (never committed to git)
+- Only messages from your chat ID are processed — unknown senders are logged and ignored
+- Rate limiting (configurable, default 10 messages/min) prevents abuse
+
+## Next step
+
+[Run the setup wizard](setup-wizard.md) to configure Adjutant with your credentials.

docs/intro.md

@@ -0,0 +1,39 @@
+---
+slug: /
+---
+
+# Introduction
+
+Adjutant is a persistent autonomous agent framework that runs on your local machine. It listens for messages through Telegram, routes them through a backend-agnostic dispatcher, and responds via LLM-powered reasoning or built-in commands.
+
+## What Adjutant does
+
+- **Conversational AI** — send natural-language messages via Telegram; Adjutant responds using OpenCode or Claude Code CLI as its reasoning backend.
+- **Knowledge bases** — register directories as queryable knowledge bases. Adjutant reads, writes, and searches them on your behalf.
+- **Scheduled jobs** — define cron-based tasks that run autonomously and notify you of results.
+- **Autonomous cycles** — periodic pulse and review operations let Adjutant act proactively, within configurable notification budgets.
+- **Long-term memory** — a structured memory system that persists facts, preferences, and decisions across conversations.
+- **News briefings** — aggregated, LLM-ranked news from Hacker News, Reddit, and RSS feeds.
+- **Screenshots and vision** — capture and analyze web pages or images.
+- **Web search** — Brave Search API integration for real-time web queries.
+
+## Dual-backend architecture
+
+Adjutant supports two LLM backends, switchable via configuration:
+
+| | OpenCode | Claude Code CLI |
+|---|---|---|
+| Vision/images | Yes | No |
+| Model listing | Yes | No |
+| Cost tracking | No | Yes |
+| Process reaping | Yes | No |
+| Permission modes | N/A | skip / allowlist |
+
+Both backends share the same protocol — all capabilities work identically regardless of which backend is active. See [Backends](guides/backends.md) for setup and switching.
+
+## Quick start
+
+1. [Install Adjutant](getting-started/installation.md)
+2. [Create a Telegram bot](getting-started/telegram-setup.md)
+3. [Run the setup wizard](getting-started/setup-wizard.md)
+4. [Send your first message](getting-started/first-message.md)