Add user-facing docs site (mkdocs-material) + GH Pages deploy

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# GITHUB_TOKEN permissions required by actions/deploy-pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one in-flight deploy at a time so a fast follow-up commit
+# doesn't race the previous build.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: latest
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: uv sync --extra docs
+
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/assets/extra.css

@@ -0,0 +1,132 @@
+/*
+ * Agent Library docs — Arcade brand overrides.
+ *
+ * Brand palette pulled directly from arcade.dev:
+ *   - background:   #0f0f0f  (near-black, primary)
+ *   - surface:      #1a1a2e  (dark navy, raised)
+ *   - accent:       #00e0e0  (signature cyan)
+ *   - foreground:   #ffffff
+ */
+
+:root {
+  --arcade-cyan: #00e0e0;
+  --arcade-cyan-dim: #00b0b0;
+  --arcade-bg: #0f0f0f;
+  --arcade-surface: #1a1a2e;
+  --arcade-surface-2: #232342;
+  --arcade-fg: #ffffff;
+  --arcade-fg-muted: #c8c8d4;
+}
+
+/* Dark scheme — primary brand experience. */
+[data-md-color-scheme="slate"] {
+  --md-default-bg-color: var(--arcade-bg);
+  --md-default-bg-color--light: var(--arcade-surface);
+  --md-default-fg-color: var(--arcade-fg);
+  --md-default-fg-color--light: var(--arcade-fg-muted);
+  --md-default-fg-color--lighter: rgba(255, 255, 255, 0.6);
+  --md-default-fg-color--lightest: rgba(255, 255, 255, 0.07);
+
+  --md-primary-fg-color: var(--arcade-bg);
+  --md-primary-fg-color--light: var(--arcade-surface);
+  --md-primary-fg-color--dark: #050505;
+  --md-primary-bg-color: var(--arcade-fg);
+  --md-primary-bg-color--light: var(--arcade-fg-muted);
+
+  --md-accent-fg-color: var(--arcade-cyan);
+  --md-accent-fg-color--transparent: rgba(0, 224, 224, 0.12);
+  --md-accent-bg-color: var(--arcade-bg);
+
+  --md-code-bg-color: var(--arcade-surface);
+  --md-code-fg-color: var(--arcade-fg);
+  --md-code-hl-color: rgba(0, 224, 224, 0.18);
+  --md-code-hl-keyword-color: var(--arcade-cyan);
+  --md-code-hl-string-color: #c4ff8a;
+
+  --md-typeset-a-color: var(--arcade-cyan);
+
+  --md-footer-bg-color: var(--arcade-bg);
+  --md-footer-bg-color--dark: #050505;
+}
+
+/* Light scheme — keep the cyan accent, white background, near-black text. */
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color: var(--arcade-bg);
+  --md-primary-fg-color--light: var(--arcade-surface);
+  --md-primary-fg-color--dark: #050505;
+  --md-primary-bg-color: var(--arcade-fg);
+
+  --md-accent-fg-color: var(--arcade-cyan-dim);
+  --md-accent-fg-color--transparent: rgba(0, 176, 176, 0.12);
+
+  --md-typeset-a-color: var(--arcade-cyan-dim);
+
+  --md-footer-bg-color: var(--arcade-bg);
+  --md-footer-bg-color--dark: #050505;
+}
+
+/* Header tweaks: slightly darker than page background, hairline accent border. */
+.md-header {
+  background-color: var(--arcade-bg);
+  border-bottom: 1px solid rgba(0, 224, 224, 0.18);
+}
+
+/* Logo: enforce a fixed height so the SVG wordmark doesn't dominate. */
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+  height: 1.5rem;
+  width: auto;
+}
+
+/* Brighter cyan on hover for nav links + table-of-contents items. */
+[data-md-color-scheme="slate"] .md-nav__link:hover,
+[data-md-color-scheme="slate"] .md-nav__link.md-nav__link--active {
+  color: var(--arcade-cyan);
+}
+
+/* Code: navy surface tone, body color text. Earlier draft tinted inline
+ * `code` cyan, which made every backticked term in prose loud and wore
+ * down the eye fast. Cyan stays reserved for links and accents. */
+[data-md-color-scheme="slate"] .md-typeset code {
+  background-color: var(--arcade-surface-2);
+  color: var(--arcade-fg);
+  border-radius: 3px;
+}
+[data-md-color-scheme="slate"] .md-typeset pre > code {
+  background-color: var(--arcade-surface);
+  color: var(--arcade-fg);
+}
+
+/* Admonitions: tint the title bar with cyan for note/tip; keep warning/danger. */
+[data-md-color-scheme="slate"] .md-typeset .admonition.note,
+[data-md-color-scheme="slate"] .md-typeset .admonition.tip,
+[data-md-color-scheme="slate"] .md-typeset .admonition.info {
+  border-color: var(--arcade-cyan);
+}
+[data-md-color-scheme="slate"] .md-typeset .admonition.note > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .admonition.tip > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .admonition.info > .admonition-title {
+  background-color: rgba(0, 224, 224, 0.15);
+}
+
+/* Buttons: cyan accent, dark text. */
+[data-md-color-scheme="slate"] .md-button--primary {
+  background-color: var(--arcade-cyan);
+  border-color: var(--arcade-cyan);
+  color: var(--arcade-bg);
+}
+[data-md-color-scheme="slate"] .md-button--primary:hover {
+  background-color: var(--arcade-fg);
+  border-color: var(--arcade-fg);
+  color: var(--arcade-bg);
+}
+
+/* Search bar: cyan focus ring. */
+[data-md-color-scheme="slate"] .md-search__input {
+  background-color: var(--arcade-surface);
+  color: var(--arcade-fg);
+}
+[data-md-color-scheme="slate"] .md-search__input:focus {
+  background-color: var(--arcade-surface-2);
+  box-shadow: 0 0 0 2px rgba(0, 224, 224, 0.4);
+}

docs/cli.md

@@ -0,0 +1,196 @@
+# CLI reference
+
+Every command Agent Library exposes, with copy-paste examples. The binary name is `librarian` (with `libr` as a shorter alias). Examples below use `librarian`.
+
+!!! note "Reminder"
+    These all assume you've set up the `librarian` alias from the [Quickstart](quickstart.md). If you haven't, prepend each command with:
+
+    ```
+    uvx --from "agent-library[all]==0.13.0"
+    ```
+
+---
+
+## `librarian add`
+
+Add a file or directory as a source and index its contents.
+
+```bash
+librarian add ~/notes
+```
+
+**Options:**
+
+| Flag | What it does |
+|---|---|
+| `-n NAME` / `--name` | Give the source a friendly name (defaults to the directory name) |
+| `-d N` / `--depth` | Limit recursion. `0` = the directory itself only. Default: unlimited |
+| `-p PATTERN` / `--pattern` | Glob filter (e.g. `'notes/*.md'`) |
+| `-e PATTERN` / `--exclude` | Glob to skip. Can be passed multiple times |
+| `--dry-run` | Show what would be indexed without doing anything |
+| `-v` / `--verbose` | Print every file as it's indexed |
+
+```bash
+# Index just the top-level files of a folder
+librarian add ~/notes --depth 0
+
+# Index only Python files in a project, excluding tests
+librarian add ~/code/myproject --pattern '**/*.py' --exclude '**/tests/**'
+
+# Preview without writing
+librarian add ~/notes --dry-run
+```
+
+---
+
+## `librarian list`
+
+Show every source you've added, with document counts.
+
+```bash
+librarian list
+```
+
+**Options:**
+
+| Flag | What it does |
+|---|---|
+| `-a` / `--all` | Include sources marked hidden/test |
+| `--json` | Output as JSON (good for scripting) |
+
+---
+
+## `librarian rm`
+
+Remove a source from the index. Files on disk are **not** deleted — only the database entries.
+
+```bash
+librarian rm notes
+```
+
+**Options:**
+
+| Flag | What it does |
+|---|---|
+| `-f` / `--force` | Skip the confirmation prompt |
+| `--path PATH` | Disambiguate if two sources share the same name |
+
+---
+
+## `librarian search`
+
+Search across everything you've indexed.
+
+```bash
+librarian search "retry policy"
+```
+
+**Options:**
+
+| Flag | What it does |
+|---|---|
+| `-l N` / `--limit` | Max results (default 10) |
+| `-m MODE` / `--mode` | `hybrid` (default), `semantic`, `vector` (alias for semantic), or `keyword` |
+| `-s NAME` / `--source` | Search within a single source |
+| `-t TIMEFRAME` / `--timeframe` | `today`, `yesterday`, `week`, `month`, `year` |
+| `-f FORMAT` / `--format` | Output as `table` (default), `json`, or `paths` |
+| `-v` / `--verbose` | Include the matched content snippet inline |
+| `-o` / `--open` | Open the top result in your editor |
+| `-c` / `--copy` | Copy the top result's content to clipboard |
+| `--code` | Search code files only |
+| `--images` | Search images only (uses CLIP if vision is installed) |
+| `--type TYPE` | Filter by asset type: `text`, `code`, `pdf`, `image` |
+
+```bash
+# Find conceptual matches, not just keyword
+librarian search "graceful degradation" --mode semantic
+
+# Just the file paths, one per line, useful for piping
+librarian search "deploy" --format paths | xargs cat | less
+
+# Things from this week, code only
+librarian search "TODO" --timeframe week --code
+```
+
+---
+
+## `librarian serve`
+
+Start the MCP server. This is what your AI assistant invokes — you usually configure it once in Claude/Cursor and never run it by hand. But it's available for testing.
+
+```bash
+librarian serve stdio    # for Claude Desktop, Claude Code, Cursor
+librarian serve http --port 7878   # for HTTP-based MCP clients
+```
+
+**Options:**
+
+| Flag | What it does |
+|---|---|
+| `--host HOST` / `-h` | HTTP-only: bind address |
+| `--port N` / `-p` | HTTP-only: port number |
+| `--log-level LEVEL` | `debug`, `info`, `warning` (default), or `error` |
+
+---
+
+## Subcommand groups
+
+Three command groups bundle less-common operations:
+
+### `librarian config`
+
+The most useful of the three. **Persist config changes** to `~/.librarian/settings.json` so they survive across sessions:
+
+```bash
+librarian config show               # table of every setting with source attribution
+librarian config get HYBRID_ALPHA   # one value
+librarian config set HYBRID_ALPHA 0.5
+librarian config path               # show the four config-file locations
+librarian config edit               # open settings.json in your editor
+librarian config models             # check / download embedding models
+librarian config reset              # back to defaults
+```
+
+See [Configuration](configuration.md) for the full list of settable keys.
+
+### `librarian index`
+
+Lower-level index operations:
+
+```bash
+librarian index build      # rebuild the entire index from scratch
+librarian index clean      # remove all indexed data (keeps sources list)
+librarian index clobber    # remove everything and reinitialize the database
+```
+
+### `librarian docs`
+
+Per-document operations:
+
+```bash
+librarian docs list        # list every indexed document
+librarian docs search "title text"   # search by title only (not contents)
+```
+
+---
+
+## Environment variables
+
+Override defaults without editing config files:
+
+| Variable | Default | Effect |
+|---|---|---|
+| `DATABASE_PATH` | `~/.librarian/index.db` | Where the search index is stored |
+| `DOCUMENTS_PATH` | `./documents` | Default directory used when no `path` is given |
+| `EMBEDDING_PROVIDER` | `local` | Switch to `openai` for hosted embeddings |
+| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model name |
+| `HYBRID_ALPHA` | `0.7` | Vector ↔ keyword blend (0 = keyword only, 1 = vector only) |
+| `MMR_LAMBDA` | `0.7` | Relevance ↔ diversity (0 = max diversity, 1 = max relevance) |
+| `SEARCH_LIMIT` | `10` | Default result count |
+
+```bash
+# One-off override for a single search
+DATABASE_PATH=/tmp/test.db librarian search "anything"
+```
+
+For permanent overrides, add them to your shell profile or a `.env` file in the directory you launch `librarian` from.