docs: update CLAUDE.md and AGENTS.md with latest session state

AGENTS.md

@@ -50,11 +50,32 @@ This repository is a local-first desktop PDF utility. Keep maintenance changes b
 
 ## MCP Server (AI Agent Integration)
 
-The repository ships `pdfreader_lib/mcp_server.py` — an MCP server exposing all PDF operations as tools for AI agents.
+The repository ships two MCP server entry points:
+
+1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app. 14 tools, stdio + SSE transport.
+2. **`packages/mcp-server/`** — standalone pip package `openreader-mcp`. Install via `pip install openreader-mcp`, run with `python -m openreader_mcp`.
+
+**Improvements made (June 2026):**
+- All 14 tool descriptions rewritten as AI-optimized sentences (what it does, what it returns, when to use vs alternatives).
+- Error messages tiered by type: validation errors, file-not-found, missing params, unexpected errors — each tells the agent what to fix.
+- 43 tests added at `tests/test_mcp_server.py` covering registration, input validation, output shape, and error handling.
+- Standalone package created at `packages/mcp-server/` — users install with one `pip install` command, no repo clone needed.
 
 **Maintenance rules:**
 - `pdfreader_lib/mcp_server.py` must stay in sync with the feature set in `main.py`.
-- When adding a new PDF operation to the GUI, add a matching MCP tool in `mcp_server.py`.
+- When adding a new PDF operation to the GUI, add a matching MCP tool.
 - Do not introduce network behavior beyond the existing GitHub release check (update detection only — no download) and MCP transport.
 - The MCP server is optional — it does not affect the desktop GUI or packaged builds.
-- Keep the `requirements-mcp.txt` dependency list minimal (only `mcp` SDK is required for stdio mode).
+- Keep `requirements-mcp.txt` minimal (only `mcp` SDK required for stdio mode).
+- When adding a tool to the bundled server, add it to `packages/mcp-server/` too.
+- Agent config uses `"args": ["-m", "openreader_mcp"]` for standalone, `"args": ["-m", "pdfreader_lib.mcp_server"]` for bundled.
+
+## Landing Page & Docs
+
+OpenReader has a showcase landing page at **https://reader.kovina.org** (Cloudflare Pages).
+
+- **Source:** `site/` — static HTML + CSS. Huninn font, `#ff255F` accent, dark/light toggle.
+- **Features:** Hero → Story → SVG feature icons → MCP/AI section with copy-paste prompt → CTA.
+- **MCP prompt box:** Users click Copy, paste to any AI assistant to set up `python -m openreader_mcp`.
+- **Docs page:** `site/docs/index.html` — full MCP setup guide for Claude Code, Desktop, Cursor.
+- **Deploy:** Auto via `.github/workflows/deploy-site.yml` on push to `main` touching `site/`. Manual via `npx wrangler pages deploy site/ --project-name reader`.

CLAUDE.md

@@ -92,49 +92,66 @@ python -m pytest tests/ -v
 
 The repository ships two MCP server entry points:
 
-1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app source.
-2. **`packages/mcp-server/`** — standalone installable package published as `openreader-mcp`. Users install via `pip install openreader-mcp` and run with `python -m openreader_mcp`.
+1. **`pdfreader_lib/mcp_server.py`** — bundled with the main app source. 14 tools, stdio + SSE transport.
+   - All tool descriptions rewritten as AI-optimized sentences (what, returns, when-to-use).
+   - Error messages are tiered: validation, file-not-found, missing params, unexpected errors.
+   - Tests at `tests/test_mcp_server.py` — 43 tests covering registration, validation, output shape, error handling.
 
-### Standalone package (`packages/mcp-server/`)
-
-- `src/openreader_mcp/server.py` — mirrors `pdfreader_lib/mcp_server.py` but imports from bundled `_search_index` and `_comparison` modules instead of `pdfreader_lib.*`.
-- Update it whenever the original `pdfreader_lib/mcp_server.py` gains new tools or features.
-- `pyproject.toml` defines the pip package metadata.
+2. **`packages/mcp-server/`** — standalone pip package `openreader-mcp`. Install via `pip install openreader-mcp`, run with `python -m openreader_mcp`.
+   - Mirrors the bundled server but imports bundled `_search_index` and `_comparison` modules.
+   - `pyproject.toml` defines metadata. Update whenever `pdfreader_lib/mcp_server.py` gains new tools.
 
 ### Rules
 
 - `pdfreader_lib/mcp_server.py` must stay in sync with `main.py`'s feature set.
 - When adding a new PDF operation to the GUI, add a matching MCP tool.
 - Keep `requirements-mcp.txt` minimal (only `mcp` SDK required for stdio mode).
 - When adding a tool to the bundled server, add it to `packages/mcp-server/` too.
+- Agent config uses `"args": ["-m", "openreader_mcp"]` (standalone) or `"args": ["-m", "pdfreader_lib.mcp_server"]` (bundled).
 
 ## Design Playbooks
 
-Three canonical playbooks govern all design and architecture decisions for this project and all Kovina apps. They are loaded at `docs/playbooks/`:
+Three canonical playbooks govern all design and architecture decisions. Loaded at `docs/playbooks/`:
 
 | File | What it covers |
 |------|---------------|
 | `docs/playbooks/PRODUCT_ARCHITECTURE_PLAYBOOK.md` | Structural canvas — spatial system, grids, containers, responsive, layout archetypes, reading tempo, motion |
 | `docs/playbooks/DESIGN_PLAYBOOK.md` | Visual design — machine metaphor, color, typography, component rules, buttons, navigation, states |
 | `docs/playbooks/MCP-SERVER-BUILD-GUIDE.md` | MCP server blueprint — SHA-256 token auth, Streamable HTTP, user isolation, tool patterns, testing |
 
-**Every design or architectural decision starts from these playbooks first.** If a playbook covers the case, follow it. If it doesn't, extend the playbook.
+**Every design or architectural decision starts from these playbooks first.**
 
 ## Landing Page
 
-OpenReader has a showcase landing page at **https://reader.kovina.org**, hosted on Cloudflare Pages.
+OpenReader's showcase landing page at **https://reader.kovina.org**, hosted on Cloudflare Pages.
+
+- **Source:** `site/` — static HTML + CSS, no build step.
+- **Font:** Huninn (rounded sans-serif), hosted TTF.
+- **Accent:** `#ff255F` (pink/red).
+- **Dark mode toggle:** sun/moon icon at right screen edge, persists to localStorage.
+- **Features:** SVG icons replace numbered list. Hero icon at 512×512px.
+- **Nav:** logo left, links centered, theme toggle far right. Seamless (no border).
+- **Sections:** Hero → Story → Features (SVG icons) → MCP/AI (with copy-paste prompt) → Ribbon (#ff255F filled) → CTA → Footer.
+- **MCP prompt box:** Click-to-copy JSON config users paste to any AI assistant.
+- **Docs page:** `site/docs/index.html` — full MCP setup guide for Claude Code, Desktop, Cursor.
+
+### Deploy
+
+- **Manual:** `npx wrangler pages deploy site/ --project-name reader` (requires `CLOUDFLARE_API_TOKEN`).
+- **Auto:** `.github/workflows/deploy-site.yml` deploys on push to `main` touching `site/`.
+
+## GitHub Repo
 
-- Source: `site/` directory at repo root
-- Built as static HTML + CSS — no build step
-- Follows the Landing Page archetype from the Architecture Playbook
-- Deploy via Cloudflare Pages dashboard or Wrangler CLI
+- **Website URL:** `https://reader.kovina.org`
+- **Description:** Includes Microsoft Store ID (`9MXDVW2645LL`) for discoverability.
+- **Release page:** v1.2.4 release body has Store link at top + direct download assets below.
 
 ## App Identity Card
 
 | Property | Definition |
 |----------|-----------|
 | Core metaphor | Reading desk / Document workbench |
-| Primary brand color | #2952CC (focus blue) |
+| Primary brand color | #ff255F (accent) |
 | Emotional tone | Focused, calm |
 | Main user action | Read & annotate PDFs |
-| Navigation | Features · Store · GitHub |
+| Navigation | Features · AI Access · Docs · Store · GitHub |