From aa78d6a22f13bc52f4125de7917a0ec2b522c858 Mon Sep 17 00:00:00 2001
From: Sylvain Gougouzian <sylvain.gougouzian@gmail.com>
Date: Mon, 13 Jul 2026 20:35:18 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20add=20Di=C3=A1taxis=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tutorial, how-to guides, reference and explanation covering setup, the
DMR connection, speed/context, workflow slash commands, theming,
keybindings, CLI and built-in tools, and the architecture.
---
 docs/_Sidebar.md                        | 27 +++++++++
 docs/explanation/architecture.md        | 68 +++++++++++++++++++++
 docs/explanation/speed-and-context.md   | 62 ++++++++++++++++++++
 docs/explanation/workflow-frise.md      | 51 ++++++++++++++++
 docs/how-to/configure-dmr-connection.md | 52 +++++++++++++++++
 docs/how-to/customize-appearance.md     | 40 +++++++++++++
 docs/how-to/drive-the-workflow.md       | 47 +++++++++++++++
 docs/how-to/speed-up-responses.md       | 43 ++++++++++++++
 docs/index.md                           | 23 ++++++++
 docs/reference/cli.md                   | 49 ++++++++++++++++
 docs/reference/configuration.md         | 47 +++++++++++++++
 docs/reference/keybindings.md           | 66 +++++++++++++++++++++
 docs/reference/tools.md                 | 59 +++++++++++++++++++
 docs/tutorials/getting-started.md       | 78 +++++++++++++++++++++++++
 14 files changed, 712 insertions(+)
 create mode 100644 docs/_Sidebar.md
 create mode 100644 docs/explanation/architecture.md
 create mode 100644 docs/explanation/speed-and-context.md
 create mode 100644 docs/explanation/workflow-frise.md
 create mode 100644 docs/how-to/configure-dmr-connection.md
 create mode 100644 docs/how-to/customize-appearance.md
 create mode 100644 docs/how-to/drive-the-workflow.md
 create mode 100644 docs/how-to/speed-up-responses.md
 create mode 100644 docs/index.md
 create mode 100644 docs/reference/cli.md
 create mode 100644 docs/reference/configuration.md
 create mode 100644 docs/reference/keybindings.md
 create mode 100644 docs/reference/tools.md
 create mode 100644 docs/tutorials/getting-started.md

diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
new file mode 100644
index 0000000..bd0ef83
--- /dev/null
+++ b/docs/_Sidebar.md
@@ -0,0 +1,27 @@
+# paikea
+
+- [Home](index.md)
+
+## Tutorials
+
+- [Getting started](tutorials/getting-started.md)
+
+## How-to guides
+
+- [Configure the DMR connection](how-to/configure-dmr-connection.md)
+- [Speed up responses](how-to/speed-up-responses.md)
+- [Drive the OpenSpec workflow](how-to/drive-the-workflow.md)
+- [Customize the appearance](how-to/customize-appearance.md)
+
+## Reference
+
+- [Configuration file](reference/configuration.md)
+- [Keyboard shortcuts & commands](reference/keybindings.md)
+- [CLI commands](reference/cli.md)
+- [Built-in tools](reference/tools.md)
+
+## Explanation
+
+- [Architecture](explanation/architecture.md)
+- [The workflow frise](explanation/workflow-frise.md)
+- [Speed & context on local models](explanation/speed-and-context.md)
diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
new file mode 100644
index 0000000..08cb9f1
--- /dev/null
+++ b/docs/explanation/architecture.md
@@ -0,0 +1,68 @@
+# Architecture
+
+This page explains how paikea is put together and why. It is background reading,
+not a how-to — you don't need any of it to use the tool.
+
+## A terminal app built like a web app
+
+paikea renders with [Ink](https://github.com/vadimdemedes/ink), which is React
+for the terminal. The interface is a tree of components laid out with flexbox
+(Yoga), and it re-renders from state exactly like a browser app would. That
+choice is what makes the marine theming, live scrolling, and pane focus feel
+natural to build — they are just props and state, not cursor arithmetic.
+
+The screen is a fixed vertical stack:
+
+```
+Header        masthead: logo, model, horizon rule
+Timeline      the workflow frise
+─ content ─   thinking pane (conditional)
+              agent steps  (conditional)
+              response pane (fills remaining height)
+PromptInput   the input line + suggestions
+StatusBar     model, current step, hints
+```
+
+The three content panes share the flexible middle region; the layout hook sizes
+them from the terminal height, capping the thinking and agent-step panes so the
+response always keeps room.
+
+## State lives in one place
+
+All UI state is a single object in `App.tsx`. There is no store and no context —
+the app is small enough that one `useState` and a merge helper (`update`) are
+clearer than any abstraction. Keyboard handling is one `useInput` callback that
+branches on mode (normal vs palette) and key.
+
+This centralization is deliberate: features like scroll focus or the thinking
+toggle touch a couple of fields and one or two components, and you can see the
+whole flow in a single file.
+
+## The agent loop
+
+Submitting a prompt runs an agent loop (`runAgentLoop`). It streams a completion
+from the model; if the model asks to call tools, paikea executes them, appends
+the results as `tool` messages, and streams again — up to a fixed iteration cap.
+When a completion arrives with no tool calls, that text is the final answer.
+
+Streaming is Server-Sent Events from the Docker Model Runner OpenAI-compatible
+endpoint (`dmr-client`). Each chunk is classified as reasoning
+(`reasoning_content`), content, or a tool-call fragment, and routed to the
+thinking pane, the response pane, or a tool-call accumulator respectively.
+
+## Services and registries
+
+Logic that isn't UI lives under `src/services/` and the registries:
+
+- **dmr-client** — talks to the model runner (streaming, tool payloads,
+  thinking control).
+- **openspec-hook** — shells out to the OpenSpec CLI to build the frise and the
+  per-step guidance.
+- **skills / rules / tools registries** — load bundled defaults plus project
+  overrides from `.paikea/` and `.claude/`.
+- **state/config, state/session** — the JSON config and saved conversations
+  under `~/.paikea/`.
+
+The system prompt for a turn is assembled from these: a skills manifest,
+the rules, and the active step's guidance. Keeping that assembly cheap is a
+recurring theme — see [Speed & context](speed-and-context.md).
diff --git a/docs/explanation/speed-and-context.md b/docs/explanation/speed-and-context.md
new file mode 100644
index 0000000..98a3495
--- /dev/null
+++ b/docs/explanation/speed-and-context.md
@@ -0,0 +1,62 @@
+# Speed & context on local models
+
+Local models feel slower than hosted ones, and the reasons are specific and
+fixable. This page explains what actually costs time in a paikea turn, and the
+design choices paikea makes because of it. For the knobs themselves, see
+[Speed up responses](../how-to/speed-up-responses.md).
+
+## Two clocks: prompt-eval and generation
+
+A turn has two costs. First the model must **read** the whole prompt — the
+system prompt plus the conversation so far — before it can emit a single token.
+Then it **generates** the answer token by token. On a small quantized model
+running locally, prompt-eval is often the larger, and it is paid *every turn*
+because the prompt is re-read each time.
+
+The practical consequence: the length of your system prompt is a latency tax on
+every message, not a one-time cost.
+
+## Why the system prompt is a manifest
+
+Earlier, paikea injected every skill's full `SKILL.md` body into the system
+prompt. That was around 3,000 tokens of instructions the model re-read on each
+turn — measured at roughly four seconds of prompt-eval before the first token
+appeared, on a 4-billion-parameter model.
+
+So skills became a **manifest**: the prompt lists each skill's name and one-line
+description and tells the model to call `read_skill` to load the full text when
+a task calls for it. The prompt dropped by about 16×, first-token latency fell
+with it, and — just as importantly — the context freed up was returned to the
+conversation and the answer.
+
+## The context window is a fixed budget
+
+Docker Model Runner loads a model with a fixed context window (4,096 tokens is
+common for small models). Everything competes for it: system prompt,
+conversation history, the model's reasoning, and the answer. A bloated system
+prompt doesn't just cost time — it crowds out the very space the model needs to
+respond, which is why answers can look truncated or forgetful.
+
+You cannot change this per request; the window is set when the model loads
+(`docker model configure --context-size`). Enlarging it buys room, not speed —
+the way to buy speed is to send fewer tokens.
+
+## Why reasoning is off by default
+
+Thinking-capable models (the Qwen3 family, DeepSeek-R1, the o-series) spend
+tokens *reasoning* before answering. On a cramped local context that reasoning
+is both slow and space-hungry, and for most quick questions it isn't worth it —
+so paikea leaves it off by default and lets you switch it on per task.
+
+When you do disable it, paikea doesn't just hide the output: it tells the model
+not to reason at all, via `chat_template_kwargs.enable_thinking = false`, which
+the Qwen3 chat template honours. (Prompt-level tricks like appending `/no_think`
+are unreliable and were measured to sometimes make things *worse*.) The result
+is a direct answer that both arrives sooner and leaves more of the window for
+your conversation.
+
+## The through-line
+
+Every one of these choices — the manifest, on-demand skills, reasoning off by
+default — is the same idea: **on a fixed, re-read context budget, the cheapest
+token is the one you don't send.**
diff --git a/docs/explanation/workflow-frise.md b/docs/explanation/workflow-frise.md
new file mode 100644
index 0000000..90fbf66
--- /dev/null
+++ b/docs/explanation/workflow-frise.md
@@ -0,0 +1,51 @@
+# The workflow frise
+
+The row of steps across the top — the *frise* — is more than decoration. It is
+how paikea ties a free-form chat to the structured OpenSpec lifecycle. This page
+explains what it represents and how it shapes a session.
+
+## What the steps are
+
+The frise always opens with **Discuss**, a free-form step that never touches
+OpenSpec. After it come the real artifacts of the active change —
+**Proposal**, **Design**, **Specs**, **Tasks** — followed by **Apply**
+(implementation) and **Archive**.
+
+Those middle steps are not hard-coded. paikea shells out to the OpenSpec CLI
+(`openspec list`, `openspec status`) and reads the artifacts of the change
+you're working on. If the CLI isn't installed or the directory isn't an OpenSpec
+project, the frise collapses to just **Discuss** and paikea behaves as a plain
+chat.
+
+## Which change is "active"
+
+When several changes exist, paikea picks the most recently modified one that
+isn't complete or archived, falling back to the most recent overall. Each step's
+done/pending state comes from that change's real artifact status, and the
+earliest not-done step is highlighted as *current* — the natural thing to work
+on next.
+
+## Why the selected step matters
+
+Selecting a step is not just navigation; it reconfigures the session:
+
+- **Prompt suggestions** change to starters appropriate to the step.
+- **Skills** are filtered — step-specific `openspec-*` skills are offered only
+  on the steps they belong to.
+- **Guidance** for that step is injected into the model's system prompt (for
+  example, *Proposal* tells the model to run `openspec new change` and write
+  `proposal.md`).
+
+So moving to `/specs` doesn't just move a highlight — it changes what paikea
+tells the model to do next.
+
+## Selecting vs. tracking
+
+paikea distinguishes the *detected current* step (from the filesystem) from the
+*selected* step (what you're pointing at). It defaults the selection to the
+current step and refreshes after each turn, but you stay in control: a slash
+command or the palette moves the selection wherever you want, and it is clamped
+if the underlying change changes shape.
+
+To actually move between steps, see
+[Drive the OpenSpec workflow](../how-to/drive-the-workflow.md).
diff --git a/docs/how-to/configure-dmr-connection.md b/docs/how-to/configure-dmr-connection.md
new file mode 100644
index 0000000..452b820
--- /dev/null
+++ b/docs/how-to/configure-dmr-connection.md
@@ -0,0 +1,52 @@
+# Configure the DMR connection
+
+By default paikea connects to Docker Model Runner at
+`http://localhost:12434/engines/v1`. To reach a runner on another scheme, host,
+or port, set the connection fields in `~/.paikea/config.json`.
+
+## Point at a remote runner
+
+Edit `~/.paikea/config.json` (create it if it does not exist):
+
+```json
+{
+  "dmrScheme": "https",
+  "dmrHost": "dmr.example.com",
+  "dmrPort": 443
+}
+```
+
+Restart paikea. Requests now go to
+`https://dmr.example.com:443/engines/v1`.
+
+## Change only the port
+
+You only need the fields you want to override — the rest keep their defaults:
+
+```json
+{
+  "dmrPort": 8080
+}
+```
+
+This connects to `http://localhost:8080/engines/v1`.
+
+## Rules and fallbacks
+
+- `dmrScheme` — only `https` overrides the default; anything else stays `http`.
+- `dmrHost` — a hostname or IP with **no scheme**; a blank value falls back to
+  `localhost`.
+- `dmrPort` — an integer in `1..65535`; out-of-range or non-integer values fall
+  back to `12434`.
+
+If a value is malformed paikea silently uses the default rather than failing, so
+a bad edit degrades to the local runner instead of breaking startup.
+
+## Verify it worked
+
+Start paikea. If the model pill in the masthead shows a model name, the
+connection succeeded. If you see "No models found in Docker Model Runner",
+paikea reached nothing at that address — re-check the scheme/host/port and that
+the runner is up.
+
+See also: [Configuration file](../reference/configuration.md).
diff --git a/docs/how-to/customize-appearance.md b/docs/how-to/customize-appearance.md
new file mode 100644
index 0000000..22792e1
--- /dev/null
+++ b/docs/how-to/customize-appearance.md
@@ -0,0 +1,40 @@
+# Customize the appearance
+
+## Switch theme
+
+paikea ships five marine themes: `deep-sea` (default dark), `dawn` (light),
+`storm`, `lagoon`, and `polar-night`.
+
+- **From the UI:** press **Ctrl+P**, scroll to a `Theme: …` entry, press
+  **Enter**. The whole interface recolors immediately and the choice is saved.
+- **From config:** set `"theme": "lagoon"` in `~/.paikea/config.json`.
+
+On first run with no saved theme, paikea picks `dawn` for light terminals
+(detected via `COLORFGBG`) and `deep-sea` otherwise. A theme name that no longer
+exists falls back to `deep-sea`.
+
+## Scroll the output
+
+Both the thinking and response panes scroll independently. The scroll keys act
+on the **focused** pane (its border is drawn in the accent color):
+
+- **↑** / **↓** — one line
+- **PageUp** / **PageDown** or **Shift+↑** / **Shift+↓** — five lines
+
+Offsets count from the bottom, so `0` follows the latest output. Sending a new
+prompt re-anchors both panes to the tail.
+
+## Move focus between panes
+
+When a thinking pane is on screen, press **Ctrl+T** to move scroll focus between
+it and the response pane. Use it to scroll back through a long chain of thought
+while the answer stays put.
+
+## Show or hide the thinking pane
+
+**Ctrl+P → Toggle Thinking Pane** hides or shows the pane without changing
+whether the model reasons. (To change *whether the model reasons*, use
+**Model Thinking** instead — see
+[Speed up responses](speed-up-responses.md).)
+
+See also: [Keyboard shortcuts & commands](../reference/keybindings.md).
diff --git a/docs/how-to/drive-the-workflow.md b/docs/how-to/drive-the-workflow.md
new file mode 100644
index 0000000..2a93b44
--- /dev/null
+++ b/docs/how-to/drive-the-workflow.md
@@ -0,0 +1,47 @@
+# Drive the OpenSpec workflow
+
+paikea's frise mirrors the OpenSpec lifecycle. The selected step shapes the
+session: the prompt suggestions, the guidance injected into the model's system
+prompt, and which skills are offered. This guide shows how to move between
+steps.
+
+## Switch step with a slash command
+
+Type a `/` command and press **Enter**:
+
+```
+/proposal
+```
+
+The active step changes; nothing is sent to the model. The commands come from
+the steps currently in the frise:
+
+`/discuss` · `/proposal` · `/design` · `/specs` · `/tasks` · `/apply` · `/archive`
+
+## Let autocompletion do the typing
+
+As soon as the prompt starts with `/`, the matching command is shown as a
+suggestion. Type a few letters and press **Tab** to complete it:
+
+- `/de` + Tab → `/design`
+- `/ap` + Tab → `/apply`
+
+## Shorthands
+
+You don't have to type the full id:
+
+- **Unique prefix** — `/pro` resolves to proposal, `/ta` to tasks.
+- **Alias** — `/propose` is accepted for proposal.
+- **Ambiguous input is ignored** — `/d` (both *discuss* and *design*) does not
+  switch; type one more letter.
+
+If a slash string isn't a valid command it is sent to the model as an ordinary
+prompt, so `/` text is never lost.
+
+## The palette still works
+
+The command palette (**Ctrl+P**) also has **Step: Previous** / **Step: Next**
+entries, and **Refresh Workflow** to re-read the frise from the OpenSpec CLI
+after you create or advance a change.
+
+See also: [The workflow frise](../explanation/workflow-frise.md).
diff --git a/docs/how-to/speed-up-responses.md b/docs/how-to/speed-up-responses.md
new file mode 100644
index 0000000..86ea697
--- /dev/null
+++ b/docs/how-to/speed-up-responses.md
@@ -0,0 +1,43 @@
+# Speed up responses
+
+On small local models, responses are gated by two things: how long the model
+spends reasoning, and how many tokens it must read every turn. paikea is already
+tuned for speed out of the box, but here is how to push it further.
+
+## Keep reasoning off (default)
+
+Chain-of-thought is **disabled by default** — the model answers directly. If you
+turned it on and want speed back, turn it off again:
+
+- **From the UI:** press **Ctrl+P**, select **Model Thinking: off**, Enter.
+- **From config:** set `"thinking": false` (or remove the field) in
+  `~/.paikea/config.json`.
+
+The choice is persisted, so it survives restarts.
+
+## Enable reasoning only when you need it
+
+Reasoning helps on hard, multi-step questions and hurts on quick ones. Toggle it
+per task from the palette rather than leaving it on globally.
+
+## Give the model more room
+
+The context window is fixed when Docker Model Runner loads the model. If answers
+get truncated or the model "forgets" earlier turns, raise it:
+
+```bash
+docker model configure <model> --context-size 16384
+```
+
+A larger window gives more room for the conversation, but it does **not** make
+each turn faster — reducing what the model must read does.
+
+## What paikea already does for you
+
+- **Small system prompt.** Skill instructions are not injected in full; the
+  prompt lists them as a manifest and the model loads a skill's full text on
+  demand with the `read_skill` tool. This keeps the per-turn prompt roughly 16×
+  smaller than injecting every skill body.
+
+If you want the reasoning behind these choices, read
+[Speed & context on local models](../explanation/speed-and-context.md).
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..ffec9a5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,23 @@
+# paikea documentation
+
+🏄 **paikea** is a full-screen terminal agent that talks to local LLMs through
+[Docker Model Runner](https://docs.docker.com/desktop/features/model-runner/),
+built around the OpenSpec propose → design → specs → tasks → apply → archive
+workflow.
+
+This documentation follows the [Diátaxis](https://diataxis.fr) framework — four
+kinds of documentation, each with a distinct job:
+
+- **[Tutorials](tutorials/)** — learning-oriented. Start here if you are new:
+  a guided path from install to your first change.
+- **[How-to guides](how-to/)** — task-oriented recipes for a specific goal
+  (configure the connection, speed up responses, drive the workflow, theme it).
+- **[Reference](reference/)** — information-oriented, dry and complete:
+  configuration keys, keybindings, commands, and built-in tools.
+- **[Explanation](explanation/)** — understanding-oriented: how the TUI and
+  agent loop are put together, how the workflow frise works, and why local
+  models feel slow (and what to do about it).
+
+If you are unsure where to look: to **learn**, read a tutorial; to **do** a
+specific thing, find a how-to; to **look something up**, use the reference; to
+**understand** a design choice, read an explanation.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
new file mode 100644
index 0000000..8b41215
--- /dev/null
+++ b/docs/reference/cli.md
@@ -0,0 +1,49 @@
+# CLI commands
+
+paikea is a single binary. In development, replace `paikea` with `bun run dev`.
+
+## `paikea`
+
+Launch the full-screen interactive TUI. This is the default command.
+
+```bash
+paikea
+```
+
+Requires Docker Model Runner to be running with at least one model pulled.
+
+## `paikea init`
+
+Scaffold a new project directory with a full paikea/OpenSpec dev environment.
+
+```bash
+paikea init
+```
+
+Creates:
+
+- **Devcontainer** — Dockerfile, docker-compose.yml, devcontainer.json
+- **OpenSpec** — `openspec/changes/` and `openspec/specs/`
+- **Vault** — `Context/`, `Daily/`, `Intelligence/`, `Resources/` for Obsidian
+- **Skills** — obsidian-cli, obsidian-markdown, defuddle, openspec-\*, json-canvas
+- **Rules** — TypeScript strict, conventional commits, devcontainer, testing…
+- **AGENTS.md** — workflow rules and vault conventions
+- **Docs** — a Diátaxis documentation scaffold
+
+## `paikea doc`
+
+Generate Diátaxis documentation for the current project.
+
+```bash
+paikea doc                 # generate into ./docs
+paikea doc -o ./my-docs    # custom output directory
+paikea doc -s src          # scope the scan to src/ only
+```
+
+| Flag | Description |
+|------|-------------|
+| `-o <dir>` | Output directory (default `./docs`) |
+| `-s <dir>` | Restrict source scanning to this directory |
+
+The output is organized into `tutorials/`, `how-to/`, `reference/`, and
+`explanation/`, with an `index.md` and `_Sidebar.md`.
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
new file mode 100644
index 0000000..f9b8b4d
--- /dev/null
+++ b/docs/reference/configuration.md
@@ -0,0 +1,47 @@
+# Configuration file
+
+paikea reads `~/.paikea/config.json`. The file is created and updated
+automatically when you change settings from the command palette, and can be
+edited by hand. All fields are optional.
+
+```json
+{
+  "theme": "deep-sea",
+  "dmrScheme": "http",
+  "dmrHost": "localhost",
+  "dmrPort": 12434,
+  "thinking": false
+}
+```
+
+## Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `theme` | string | terminal-detected | Active theme. One of `deep-sea`, `dawn`, `storm`, `lagoon`, `polar-night`. Unknown names fall back to `deep-sea`. |
+| `dmrScheme` | string | `http` | Scheme of the DMR API. Only `https` overrides the default. |
+| `dmrHost` | string | `localhost` | Host of the DMR API (hostname or IP, no scheme). Blank falls back to the default. |
+| `dmrPort` | number | `12434` | Port of the DMR API. Must be an integer in `1..65535`; otherwise falls back to the default. |
+| `thinking` | boolean | `false` | Whether thinking-capable models reason before answering. `true` enables chain-of-thought. |
+
+## Default theme detection
+
+When `theme` is absent, paikea inspects the `COLORFGBG` environment variable. A
+background index of `7` or `15` (light terminal) selects `dawn`; anything else
+selects `deep-sea`.
+
+## Connection base URL
+
+`dmrScheme`, `dmrHost`, and `dmrPort` combine into
+`<scheme>://<host>:<port>/engines/v1`. Each is resolved independently, so an
+invalid value for one does not affect the others.
+
+## Related files
+
+| Path | Purpose |
+|------|---------|
+| `~/.paikea/config.json` | This configuration file |
+| `~/.paikea/sessions/` | Saved conversation history |
+| `~/.config/paikea/tools/` | User-global custom tools (`*.tool.json`) |
+| `.paikea/skills/`, `.claude/skills/` | Project skill overrides |
+| `.paikea/tools/` | Project custom tools (override bundled + user) |
diff --git a/docs/reference/keybindings.md b/docs/reference/keybindings.md
new file mode 100644
index 0000000..e23f272
--- /dev/null
+++ b/docs/reference/keybindings.md
@@ -0,0 +1,66 @@
+# Keyboard shortcuts & commands
+
+## Global
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit prompt (or run a `/step` command) |
+| `Escape` | Cancel generation while streaming; when idle, press twice to quit |
+| `Ctrl+C` / `Ctrl+D` | Cancel generation, or quit |
+| `Ctrl+P` | Open the command palette |
+| `Tab` | Accept the current suggestion; if there is none, switch to the next model |
+| `Shift+Tab` | Previous model |
+
+## Scrolling
+
+Scroll keys act on the **focused** pane (its border shows the accent color).
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Scroll the focused pane one line |
+| `PageUp` / `PageDown` | Scroll five lines |
+| `Shift+↑` / `Shift+↓` | Scroll five lines |
+| `Ctrl+T` | Toggle scroll focus between the thinking and response panes (only when the thinking pane is visible) |
+
+## Prompt editing
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Move the cursor |
+| `Home` / `End` · `Ctrl+A` / `Ctrl+E` | Jump to start / end of the prompt |
+| `Backspace` / `Delete` | Delete a character |
+| `Ctrl+W` | Delete the previous word |
+| `Ctrl+U` | Delete to the start of the line |
+
+## Workflow steps
+
+Type a slash command and press `Enter` to switch step (Tab autocompletes):
+
+| Command | Step |
+|---------|------|
+| `/discuss` | Discuss |
+| `/proposal` (alias `/propose`) | Proposal |
+| `/design` | Design |
+| `/specs` | Specs |
+| `/tasks` | Tasks |
+| `/apply` | Apply |
+| `/archive` | Archive |
+
+A unique prefix works too (`/pro` → proposal). Ambiguous or unknown slash text
+is sent to the model as an ordinary prompt.
+
+`Alt+←` / `Alt+→` also move between steps on terminals that forward Alt+arrow
+keys, but slash commands are the reliable path.
+
+## Command palette (`Ctrl+P`)
+
+| Entry | Action |
+|-------|--------|
+| Switch Model | Cycle to the next available model |
+| Refresh Workflow | Re-read the frise from the OpenSpec CLI |
+| Model Thinking: on/off | Enable/disable model reasoning (persisted) |
+| Toggle Thinking Pane | Show/hide the thinking pane (does not change reasoning) |
+| Step: Previous / Next | Move between workflow steps |
+| Theme: … | Switch theme (persisted) |
+| Clear | Clear the current output |
+| Quit | Exit paikea |
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
new file mode 100644
index 0000000..4be3ce7
--- /dev/null
+++ b/docs/reference/tools.md
@@ -0,0 +1,59 @@
+# Built-in tools
+
+During a turn the model can call tools; paikea executes them and feeds the
+result back into the conversation. Read-only tools run immediately; destructive
+tools require confirmation.
+
+## Bundled tools
+
+| Tool | Parameters | Destructive | Description |
+|------|-----------|:-----------:|-------------|
+| `web_search` | `query` | no | Search the web via DuckDuckGo; returns titles, URLs, snippets |
+| `get_webpage` | `url` | no | Fetch a page and return its text content |
+| `read_skill` | `name` | no | Load a skill's full instructions on demand by name |
+| `read_file` | `path` | no | Read a file (relative to the project root) |
+| `list_files` | `path` | no | List files and directories at a path |
+| `write_file` | `path`, `content` | **yes** | Create or overwrite a file |
+| `shell_exec` | `command` | **yes** | Run a shell command in the project directory |
+| `git_propose` | — | no | Create a `feat/<name>` branch for the latest OpenSpec change |
+| `git_commit` | `message` | no | Stage all changes and commit (conventional format) |
+| `git_archive` | — | no | Push the feature branch and archive the OpenSpec change |
+
+`read_skill` pairs with the skills manifest in the system prompt: the prompt
+lists skills by name and description, and the model calls `read_skill` to pull a
+skill's full text only when it needs it.
+
+## Custom tools
+
+Tools are loaded from three sources, later ones overriding earlier ones by name:
+
+1. **Bundled** — compiled into the binary (the table above)
+2. **User-global** — `~/.config/paikea/tools/*.tool.json`
+3. **Project** — `.paikea/tools/*.tool.json`
+
+A `*.tool.json` file defines one tool:
+
+```json
+{
+  "name": "search_npm",
+  "description": "Search npm packages",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "Package name or keywords" }
+    },
+    "required": ["query"]
+  },
+  "handler": "shell",
+  "command": "npm search {{query}} --json | head -20",
+  "sandbox": true,
+  "destructive": false
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `handler` | `shell` (run `command`), `http` (fetch `url`), or `js` (run a `.js` script) |
+| `command` / `url` / `method` / `script` | Handler-specific payload, with `{{param}}` interpolation |
+| `sandbox` | Validate that file paths stay within the project root |
+| `destructive` | Require a confirmation prompt before running |
diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md
new file mode 100644
index 0000000..2197e91
--- /dev/null
+++ b/docs/tutorials/getting-started.md
@@ -0,0 +1,78 @@
+# Getting started
+
+This tutorial takes you from nothing to a running paikea session and your first
+OpenSpec change. Follow every step in order; by the end you will have chatted
+with a local model and switched between workflow steps.
+
+You will need [Bun](https://bun.sh) (v1.3+) and
+[Docker Desktop](https://www.docker.com/products/docker-desktop/) with Model
+Runner enabled.
+
+## 1. Pull a model
+
+paikea talks to whatever models Docker Model Runner has loaded. Pull one:
+
+```bash
+docker model pull ai/qwen3
+```
+
+## 2. Install and run
+
+From the project directory:
+
+```bash
+bun install
+bun run dev
+```
+
+The full-screen interface opens. Along the top you see the masthead (`🏄 paikea`
+and the active model), then the **workflow frise** — a row of steps
+(`Discuss`, `Proposal`, `Design`, …). At the bottom is the prompt, showing
+`cast off — set a course…`.
+
+## 3. Have a conversation
+
+Type a question and press **Enter**:
+
+```
+What does this project do?
+```
+
+The response streams into the response pane. Responses are direct by default —
+the model answers without a visible reasoning step.
+
+## 4. Turn on reasoning (optional)
+
+Press **Ctrl+P** to open the command palette, move to **Model Thinking: on**
+with the arrow keys, and press **Enter**. Ask another question — this time a
+**thinking** pane appears above the response and shows the model reasoning
+before it answers. Press **Ctrl+T** to move scroll focus to the thinking pane,
+then **↑**/**↓** to scroll through it.
+
+Toggle it back off from the palette when you want speed again.
+
+## 5. Move through the workflow
+
+The frise mirrors the OpenSpec lifecycle. Switch to a step by typing a slash
+command. Type `/` and watch the suggestion appear; press **Tab** to complete
+`/proposal`, then **Enter**:
+
+```
+/proposal
+```
+
+The selected step in the frise moves to **Proposal**, and the status bar shows
+`cap proposal`. Nothing was sent to the model — a slash command only changes the
+step, which in turn changes the prompt suggestions and the guidance paikea gives
+the model. Try `/discuss` to go back.
+
+## 6. Quit
+
+Press **Esc** once (paikea asks you to confirm), then **Esc** again.
+
+## Where to go next
+
+- Point paikea at a different runner: [Configure the DMR connection](../how-to/configure-dmr-connection.md)
+- Make answers faster: [Speed up responses](../how-to/speed-up-responses.md)
+- Look up every key: [Keyboard shortcuts & commands](../reference/keybindings.md)
+- Understand the frise: [The workflow frise](../explanation/workflow-frise.md)
-- 
2.51.2