docs: backfill missing CLI documentation

website/docs/ai-integration.md

@@ -53,6 +53,8 @@ Flags:
 - `--new-session` -- start a fresh session (use at conversation start)
 - `-q` -- quiet mode, shorter output (use after first read)
 
+For durable context that is useful across issues, agents can also use [notes](./notes.md). Keep issue-specific progress in `td log` and `td handoff`.
+
 ## Recommended Agent Workflow
 
 ```bash
@@ -104,11 +106,11 @@ The legacy `balanced_review_policy` flag is deprecated; prefer `review_policy_mo
 Pin or change the mode:
 
 ```bash
-td feature set review_policy_mode strict     # or balanced, or delegated
-# or, one-off:
 TD_FEATURE_REVIEW_POLICY_MODE=strict td approve td-a1b2
 ```
 
+For a persistent project setting, store `review_policy_mode` in `.todos/config.json` under `feature_string_flags`. See [Configuration](./configuration.md) for the current config shape.
+
 ### Delegated Review: Orchestrator + Sub-Agents
 
 Under `delegated`, an orchestrator coordinates work across sub-agents. The review must come from a session that did not participate in implementation, but the close may be performed by any session — so the orchestrator can finish the task once a reviewer sub-agent records approval.

website/docs/configuration.md

@@ -0,0 +1,124 @@
+---
+sidebar_position: 4
+---
+
+# Configuration
+
+td has two user-facing configuration surfaces:
+
+- `td config` manages sync settings stored in `~/.config/td/config.json`.
+- `td feature` manages project-local boolean feature flags. String-valued settings such as `review_policy_mode` are stored in `.todos/config.json`.
+
+Some sync commands are rollout-gated. If `td auth`, `td config`, or `td sync` is unavailable in your install, enable the process-level CLI surface in the shell that runs td:
+
+```bash
+export TD_FEATURE_SYNC_CLI=true
+```
+
+## Sync Config
+
+Inspect current sync configuration:
+
+```bash
+td config list
+td config get sync.url
+td config get sync.auto.interval
+```
+
+Set supported keys with `td config set <key> <value>`:
+
+```bash
+td config set sync.url http://localhost:8080
+td config set sync.auto.enabled false
+td config set sync.auto.interval 10m
+td config set sync.snapshot_threshold 250
+```
+
+Supported keys:
+
+| Key | Value | Notes |
+|-----|-------|-------|
+| `sync.url` | URL | Sync server base URL. |
+| `sync.enabled` | boolean | Stored sync preference for compatibility; command availability is controlled by `TD_FEATURE_SYNC_CLI`. |
+| `sync.auto.enabled` | boolean | Enables or disables autosync. |
+| `sync.auto.debounce` | duration | Debounce after local mutations, such as `3s`. |
+| `sync.auto.interval` | duration | Periodic autosync interval, such as `5m`. |
+| `sync.auto.pull` | boolean | Include pull during autosync. |
+| `sync.auto.on_start` | boolean | Sync when td starts. |
+| `sync.snapshot_threshold` | integer | Minimum server event count before snapshot bootstrap is considered. |
+
+`td config` does not currently have an `unset` subcommand. To return optional sync settings to their built-in defaults, remove the key from `~/.config/td/config.json` or set the default-equivalent value explicitly.
+
+## Environment Overrides
+
+Environment variables are useful for one-off commands and CI jobs:
+
+```bash
+TD_SYNC_URL=http://localhost:8080 td auth status
+TD_AUTH_KEY=td_api_key_xxx td sync --status
+TD_SYNC_AUTO=false td list
+TD_SYNC_SNAPSHOT_THRESHOLD=0 td sync
+```
+
+Unset shell overrides with your shell's normal syntax:
+
+```bash
+unset TD_SYNC_URL
+unset TD_AUTH_KEY
+```
+
+## Feature Flags
+
+List feature flags and their resolved source:
+
+```bash
+td feature list
+td feature get sync_autosync
+```
+
+Set and unset project-local overrides:
+
+```bash
+td feature set sync_autosync false
+td feature unset sync_autosync
+```
+
+Known boolean flags include:
+
+| Flag | Purpose |
+|------|---------|
+| `sync_cli` | Records project opt-in for the sync CLI rollout. Hidden command registration is process-level; use `TD_FEATURE_SYNC_CLI=true` when the commands are absent. |
+| `sync_autosync` | Enables background autosync hooks. |
+| `sync_monitor_prompt` | Enables monitor sync setup prompts. |
+| `sync_notes` | Enables notes entity sync. |
+| `balanced_review_policy` | Deprecated compatibility flag; prefer `review_policy_mode=balanced`. |
+
+## Review Policy Mode
+
+`review_policy_mode` selects review behavior:
+
+| Mode | Behavior |
+|------|----------|
+| `delegated` | Default for new installs. Review must be independent; any session may close after an approval is recorded. |
+| `strict` | The reviewer must have no prior involvement. |
+| `balanced` | Legacy mode with a creator-approval exception when a reason is supplied. |
+
+Use a one-off environment override when testing policy behavior:
+
+```bash
+TD_FEATURE_REVIEW_POLICY_MODE=strict td approve td-a1b2
+```
+
+For a persistent project setting, store `review_policy_mode` in `.todos/config.json` under `feature_string_flags`:
+
+```json
+{
+  "feature_string_flags": {
+    "review_policy_mode": "delegated"
+  }
+}
+```
+
+Remove the key to return to the built-in default. The current `td feature` command manages boolean feature flags; it does not set or unset string-valued features.
+
+Prefer `review_policy_mode` over the deprecated `balanced_review_policy` flag.

website/docs/directory-associations.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 9
+---
+
+# Directory Associations
+
+Directory associations let td treat one directory as part of another td project. This is useful for sibling worktrees, nested checkouts, generated sidecar repos, or tools that run outside the directory containing `.todos`.
+
+Associations are stored in `~/.config/td/associations.json`.
+
+## Link The Current Directory
+
+From the directory you want to associate:
+
+```bash
+cd /Users/alex/code/project-worktree
+td config associate /Users/alex/code/project
+```
+
+With one argument, `td config associate` uses the current directory as the source and the argument as the target td project.
+
+## Link A Specific Directory
+
+```bash
+td config associate /Users/alex/code/project-feature /Users/alex/code/project
+```
+
+After this, td commands run from `/Users/alex/code/project-feature` resolve to the canonical td project at `/Users/alex/code/project`.
+
+## List Associations
+
+```bash
+td config associations
+td config assoc
+```
+
+`assoc` is an alias for `associations`.
+
+## Remove An Association
+
+```bash
+td config dissociate
+td config dissociate /Users/alex/code/project-feature
+```
+
+With no argument, `td config dissociate` removes the association for the current directory.
+
+## When To Use Associations
+
+Use associations when multiple directories should share one task database:
+
+- A feature worktree should use the main repo's `.todos` database.
+- A nested app directory should resolve to the parent project.
+- A generated or temporary checkout should report work against the canonical project.
+
+Do not use associations to merge unrelated projects. Each real project should keep its own `.todos` database unless the directories are intentionally part of the same work stream.

website/docs/intro.md

@@ -94,4 +94,6 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI.
 
 - [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth
 - [Boards](./boards.md) -- Visual overview of issue status across your project
+- [Notes](./notes.md) -- Freeform project memory for durable context that is not an issue
 - [Query Language](./query-language.md) -- Filter and search issues with structured queries
+- [Command Reference](./command-reference.md) -- Complete CLI surface, including sync, config, and diagnostic commands

website/docs/notes.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 8
+---
+
+# Notes
+
+`td note` stores freeform project memory that is useful across sessions but does not need an issue lifecycle. Use notes for standing context, decision records, operating reminders, and background material that agents should be able to find later.
+
+Use issues when work needs status, ownership, review, dependencies, or a handoff. Use notes when the information is durable context rather than a task to complete.
+
+## Create Notes
+
+```bash
+td note add "Architecture decisions" --content "Use SQLite WAL for local writes."
+td note add "Research links"
+```
+
+If `--content` is omitted, td opens your editor for the note body.
+
+## Find Notes
+
+```bash
+td note list
+td note list --search "sync"
+td note list --pinned
+td note list --archived
+td note list --all
+td note list --json
+```
+
+By default, `td note list` shows non-archived notes. Use `--all` to include archived notes or `--archived` to show only archived notes.
+
+## Read And Edit
+
+```bash
+td note show nt-a1b2c3
+td note edit nt-a1b2c3 --title "Sync setup notes"
+td note edit nt-a1b2c3 --content "Updated operating notes."
+td note edit nt-a1b2c3
+```
+
+Running `td note edit <id>` without `--title` or `--content` opens the note in your editor.
+
+## Pinning
+
+Pinned notes stay easy to discover for agents and operators.
+
+```bash
+td note pin nt-a1b2c3
+td note list --pinned
+td note unpin nt-a1b2c3
+```
+
+Pin notes that should remain visible during routine orientation, such as project conventions, local setup warnings, or active architectural decisions.
+
+## Archive And Delete
+
+Archive notes that should remain searchable but no longer belong in the default list.
+
+```bash
+td note archive nt-a1b2c3
+td note unarchive nt-a1b2c3
+td note delete nt-a1b2c3
+```
+
+`td note delete` soft-deletes the note. Prefer archive for old-but-useful context; delete for duplicates, mistakes, or content that should no longer be part of project memory.
+
+## Agent Guidance
+
+Agents should use notes for information that helps future sessions but does not need review:
+
+- Stable project facts: repository layout, local services, or deployment caveats.
+- Decisions that explain why a path was chosen.
+- Research summaries that may inform later issues.
+- Operator reminders that should survive context windows.
+
+Do not use notes as a substitute for `td log`, `td handoff`, or `td review`. Progress on a specific issue belongs on that issue so reviewers and future implementers can see the full chain of work.