diff --git a/.kagi/SETUP.md b/.kagi/SETUP.md
new file mode 100644
index 0000000..d62adeb
--- /dev/null
+++ b/.kagi/SETUP.md
@@ -0,0 +1,63 @@
+# Kagi x Zed workflow - build spec
+
+## Context
+- macOS, Apple Silicon. `kagi` v0.16.0 at `/opt/homebrew/bin/kagi`. Auth: session-token, verified.
+- Kagi MCP server already wired in Zed user settings. Do not modify Zed user settings.
+- `kagi assistant custom list` currently returns `[]`.
+- `kagi assistant` default `--format` is `json`. Markdown must be requested explicitly.
+- Repo lives on a OneDrive-synced path. Keep file writes minimal and avoid bulk rewrites.
+
+## Hard constraints
+1. Do NOT edit `~/.config/zed/settings.json`. It is outside the worktree and already correct.
+2. Do NOT invent CLI flags. Run `kagi <subcommand> --help` and use only flags it prints.
+3. Custom assistants must be created via the `kagi` CLI. The MCP server is read-only
+   (`--enable-mutating-tools` is off); `kagi_assistant_custom_list`/`_get` exist but no `_create`.
+4. Every file you create goes inside this worktree.
+5. Show me each file as a diff before running anything that writes outside `.kagi/`.
+
+## Deliverables
+
+### D1 - `bin/kagi-ask` (executable shell script)
+Wrapper invoked by Zed tasks.
+- Usage: `kagi-ask <mode> <selected-text> [language]`
+- Modes: `prompt-refine`, `explain`, `review`, `ask`
+- Maps mode -> a custom assistant name (see D4).
+- Writes output to `$ZED_WORKTREE_ROOT/.kagi/out/<timestamp>-<mode>.md`, also echoes to stdout.
+- Must pass `--format markdown` and `--stream`.
+- Must `set -euo pipefail`, `mkdir -p` the out dir, and handle empty selection with a clear error.
+- After writing, open the file in Zed via the `zed` CLI if it is on PATH; skip silently if not.
+- Reads stdin if no selection argument is supplied.
+
+### D2 - `.zed/tasks.json`
+One task per mode. Fields to use: `label`, `command`, `args`, `cwd`, `use_new_terminal`,
+`allow_concurrent_runs`, `reveal`, `hide`, `save`.
+- `command` = `$ZED_WORKTREE_ROOT/bin/kagi-ask`
+- Pass `$ZED_SELECTED_TEXT` and `$ZED_LANGUAGE` as args.
+- `"save": "current"`, `"use_new_terminal": false`, `"allow_concurrent_runs": true`,
+  `"reveal": "always"`, `"hide": "on_success"`.
+- Label every task with a `kagi: ` prefix.
+
+### D3 - keymap snippet
+Output a snippet for me to paste into `~/.config/zed/keymap.json` (do not write that file).
+Bind each task with `["task::Spawn", { "task_name": "<exact label>" }]` under `"context": "Editor"`.
+Avoid collisions with the VSCode base keymap.
+
+### D4 - custom assistants
+Model slugs are unavailable: `kagi assistant models` returns `[]`. This is expected and is NOT a
+blocker. Do not investigate it. Create all three WITHOUT `--model`; the account default applies.
+Use only flags confirmed by `kagi assistant custom create --help`.
+- `prompt-smith`  - rewrites a prompt to be minimal-token, unambiguous, agent-ready.
+  Outputs ONLY the rewritten prompt in a fenced block. No web access.
+- `code-reader`   - explains code concisely; does not restate the code back.
+- `code-reviewer` - bug/edge-case/security focus; terse bullets; no style nits.
+Verify with `kagi assistant custom list` after creation.
+
+### D5 - housekeeping
+- Append `.kagi/out/` to `.gitignore`.
+- `.kagi/SETUP.md` and `bin/kagi-ask` stay tracked.
+- Create `.kagi/README.md`: table of task label -> keybinding -> assistant.
+
+## Acceptance
+- `bin/kagi-ask prompt-refine "write a function" Python` produces a markdown file in `.kagi/out/`.
+- `kagi assistant custom list` returns the three assistants.
+- Each task appears in the `task: spawn` modal.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8357cb4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,28 @@
+
+## Research & web access
+
+Kagi MCP tools are available and are the ONLY approved way to reach the web.
+Never use a built-in fetch, web-search, or browser tool.
+
+Tool selection:
+- Facts, docs, current info  -> mcp__kagi__kagi_search
+- 2+ independent queries     -> mcp__kagi__kagi_batch_search (one call, not N)
+- Read a known URL           -> mcp__kagi__kagi_extract  (returns markdown; cheaper than raw HTML)
+- One-line factual lookup    -> mcp__kagi__kagi_quick
+- Delegate reasoning         -> mcp__kagi__kagi_assistant
+
+Token discipline:
+- Omit `format` so the server default (TOON) applies. Do not request `pretty` or `json`.
+- Ask for the narrowest result set that answers the question; use `limit`.
+- Do not paste full tool output into your reply. Quote only what you use, with the URL.
+- Prefer one kagi_extract over three kagi_search calls when you already know the source.
+
+Never call - no API token configured, these will fail:
+kagi_fastgpt, kagi_enrich_web, kagi_enrich_news
+
+Never call unless I ask by name:
+kagi_translate, kagi_news_chaos, kagi_custom_bang_*, kagi_redirect_*,
+kagi_site_pref_list, kagi_history_*
+
+Model slugs: `kagi assistant models` returns []. This is expected. Do not investigate it.
+Create custom assistants without `--model`; the account default applies.