diff --git a/README.md b/README.md
index 684416ad..2f8aa296 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context
 
 **Key Features**: Query-based boards, dependency graphs, epic tracking, powerful query language (TDQ), session analytics, and state machine workflows.
 
-![td](docs/td.png)
+![td](website/static/img/td.png)
 
 ## Table of Contents
 
@@ -172,7 +172,7 @@ td/
 2. Git integration captures snapshots at start/handoff
 3. Session manager auto-rotates context IDs based on terminal/agent identity
 
-See [SPEC.md](./SPEC.md) for detailed schemas and workflows.
+See [SPEC.md](./docs/implemented/SPEC.md) for detailed schemas and workflows.
 
 ## Development
 
@@ -477,8 +477,6 @@ Shows current focus, activity log across sessions, and ready tasks. Useful for k
 
 **Statistics Dashboard** — Press `s` to open the stats modal and see key metrics:
 
-![td stats modal](docs/stats-modal.png)
-
 The dashboard displays:
 
 - **Status Breakdown** — Visual bar chart showing task distribution across statuses (open, in_progress, blocked, in_review, closed)
@@ -521,12 +519,14 @@ Full documentation is available at [marcus.github.io/td](https://marcus.github.i
 - [Getting Started](https://marcus.github.io/td/docs/intro)
 - [Core Workflow](https://marcus.github.io/td/docs/core-workflow)
 - [AI Agent Integration](https://marcus.github.io/td/docs/ai-integration)
+- [Notes](https://marcus.github.io/td/docs/notes)
+- [Sync and Collaboration](https://marcus.github.io/td/docs/sync-collaboration)
 - [Command Reference](https://marcus.github.io/td/docs/command-reference)
 
 ## Design Philosophy
 
 - **Minimal** — Does one thing. Not a project management suite.
-- **Local** — SQLite in `.todos/`. No server, no sync, no account.
+- **Local-first** — SQLite in `.todos/` by default, with optional sync when teams need collaboration.
 - **Portable** — Works with any AI tool that can run shell commands.
 - **Opinionated** — Enforces handoffs. That's the point.
 
diff --git a/docs/guides/README.md b/docs/guides/README.md
index 7b096dd2..46f02cc6 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -2,7 +2,7 @@
 
 This directory contains legacy and in-repo implementation guides.
 
-The long-term direction is to keep **task workflow guidance** in skills and keep **project-specific architecture/design docs** in `docs/`.
+The long-term direction is to keep **task workflow guidance** in skills, **user-facing guides** in the Docusaurus site under `website/docs/`, and **project-specific architecture/design docs** in `docs/`.
 
 ## Where Skills Live
 
@@ -52,5 +52,6 @@ None yet.
 ## Link Policy During Migration
 
 - Active, authoritative workflow guidance should point to skill paths when a skill fully replaces a guide.
+- User-facing notes, sync/collaboration, and system diagnostics guidance should point to `website/docs/notes.md`, `website/docs/sync-collaboration.md`, and `website/docs/system-diagnostics.md`.
 - Historical/spec references should point to `docs/deprecated/guides/` **after** a covered guide is moved there.
 - If a guide is not fully covered, keep links pointed at `docs/guides/`.
diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md
index 28e9da1c..00df4cba 100644
--- a/website/docs/command-reference.md
+++ b/website/docs/command-reference.md
@@ -4,51 +4,69 @@ sidebar_position: 11
 
 # Command Reference
 
-Complete reference for all `td` commands.
+Complete reference for the user-facing `td` CLI command surface.
+
+Run `td <command> --help` for the exact flags accepted by your installed version.
 
 ## Core Commands
 
 | Command | Description |
 |---------|-------------|
-| `td create "title" [flags]` | Create issue. Flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor` |
-| `td list [flags]` | List issues. Flags: `--status`, `--type`, `--priority`, `--epic` |
-| `td show <id>` | Display full issue details |
-| `td update <id> [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels` |
-| `td delete <id>` | Soft-delete issue |
-| `td restore <id>` | Restore soft-deleted issue |
+| `td create "title" [flags]` | Create an issue. Aliases: `add`, `new`. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` |
+| `td list [flags]` | List issues matching filters. Alias: `ls`. Common flags: `--status`, `--type`, `--priority`, `--epic`, `--json` |
+| `td show <id...>` | Display full issue details. Aliases: `context`, `view`, `get` |
+| `td update <id> [flags]` | Update fields on an issue. Alias: `edit`. Common flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--append`, `--defer`, `--due` |
+| `td delete <id...>` | Soft-delete one or more issues |
+| `td deleted [--json]` | Show soft-deleted issues |
+| `td restore <id...>` | Restore soft-deleted issues |
+| `td task ...` | Shortcuts for working with tasks |
+| `td epic ...` | Shortcuts for working with epics |
 
 ## Workflow Commands
 
 | Command | Description |
 |---------|-------------|
-| `td start <id>` | Begin work (status -> in_progress) |
-| `td unstart <id>` | Revert to open |
-| `td log "message" [flags]` | Log progress. Flags: `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result` |
-| `td handoff <id> [flags]` | Capture state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain` |
-| `td review <id>` | Submit for review |
-| `td reviewable` | Show reviewable issues |
-| `td approve <id> [--reason "..."]` | Approve and close. Reason required for creator-exception approvals |
-| `td reject <id> --reason "..."` | Reject back to in_progress |
-| `td block <id>` | Mark as blocked |
-| `td unblock <id>` | Unblock to open |
-| `td close <id>` | Admin close (not for completed work) |
-| `td reopen <id>` | Reopen closed issue |
-| `td comment <id> "text"` | Add comment |
-
-## Deferral & Due Dates
+| `td start <id...>` | Begin work. Alias: `begin` |
+| `td unstart <id...>` | Revert in-progress issues to open. Alias: `stop` |
+| `td log "message" [flags]` | Append progress to the current issue. Flags include `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result` |
+| `td handoff <id> [flags]` | Capture structured working state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain` |
+| `td review <id...>` | Submit issues for review. Aliases: `submit`, `finish` |
+| `td reviewable [--include-approved]` | Show issues the current session can review; optionally include reviewed issues that can be closed |
+| `td approve <id...> [flags]` | Approve and close, record-only review, or close using a recorded approval. Flags include `--reason`, `--record-only`, `--decision approved\|changes_requested`, `--all` |
+| `td reject <id> --reason "..."` | Reject an issue and return it to open |
+| `td block <id...>` | Mark issues as blocked |
+| `td unblock <id...>` | Unblock issues back to open |
+| `td close <id...>` | Admin close without review. Aliases: `done`, `complete` |
+| `td reopen <id...>` | Reopen closed issues |
+| `td comment <id> "text"` | Add a comment. Alias for `td comments add` |
+| `td comments <id>` | List comments for an issue |
+| `td comments add <id> "text"` | Add a comment to an issue |
+
+## Review Flag Details
+
+`td approve` can be used in delegated review flows:
+
+| Invocation | Effect |
+|------------|--------|
+| `td approve <id>` | Direct reviewer-close. The caller must be an eligible reviewer when no active approval is already recorded |
+| `td approve <id> --record-only --reason "..."` | Record an approval review without closing. The caller must be an eligible reviewer |
+| `td approve <id> --record-only --decision changes_requested --reason "..."` | Record a non-approving review without closing |
+| `td approve <id> --reason "..."` | Close using an existing recorded approval. Non-reviewer closes require a reason |
+
+Use `td reviewable --include-approved` to find reviewed issues that can be closed after an independent approval has been recorded.
+
+## Deferral and Due Dates
 
 | Command | Description |
 |---------|-------------|
-| `td defer <id> <date>` | Defer issue until a future date |
-| `td defer <id> --clear` | Remove deferral, make immediately actionable |
-| `td due <id> <date>` | Set due date on an issue |
-| `td due <id> --clear` | Remove due date |
-
-Date formats: `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, `2026-03-15`
+| `td defer <id> <date>` | Defer an issue until a future date |
+| `td defer <id> --clear` | Remove deferral |
+| `td due <id> <date>` | Set a due date |
+| `td due <id> --clear` | Remove a due date |
 
-The `--defer` and `--due` flags are also available on `td create` and `td update`.
+Date formats include `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, and `2026-03-15`.
 
-**List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--due-soon`
+List filters include `--all`, `--deferred`, `--surfacing`, `--overdue`, and `--due-soon`.
 
 ## Agent-Safe Rich Text Input
 
@@ -62,16 +80,16 @@ td create "Document sync failure modes" \
 cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
 ```
 
-## Query & Search
+## Query and Search
 
 | Command | Description |
 |---------|-------------|
-| `td query "expression"` | TDQ query |
-| `td search "keyword"` | Full-text search |
-| `td next` | Highest-priority open issue |
-| `td ready` | Open issues by priority |
+| `td query "expression"` | Search with the TDQ query language |
+| `td search "keyword"` | Full-text search across issues |
+| `td next` | Show the highest-priority open issue |
+| `td ready` | List open issues sorted by priority |
 | `td blocked` | List blocked issues |
-| `td in-review` | List in-review issues |
+| `td in-review` | List issues currently in review. Alias: `ir` |
 
 ## Dependencies
 
@@ -80,9 +98,10 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
 | `td dep add <issue> <depends-on>` | Add dependency |
 | `td dep rm <issue> <depends-on>` | Remove dependency |
 | `td dep <issue>` | Show dependencies |
-| `td dep <issue> --blocking` | Show what it blocks |
-| `td blocked-by <issue>` | Issues blocked by this |
-| `td critical-path` | Optimal unblocking sequence |
+| `td dep <issue> --blocking` | Show issues blocked by this issue |
+| `td depends-on <issue>` | Show what an issue depends on. Aliases: `deps`, `dependencies` |
+| `td blocked-by <issue>` | Show issues waiting on this issue |
+| `td critical-path` | Show the sequence that unblocks the most work |
 
 ## Boards
 
@@ -95,53 +114,115 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
 | `td board edit <board> [flags]` | Edit board |
 | `td board delete <board>` | Delete board |
 
-## Epics & Trees
+## Epics and Trees
 
 | Command | Description |
 |---------|-------------|
 | `td epic create "title" [flags]` | Create epic |
 | `td epic list` | List epics |
-| `td tree <id>` | Show tree |
+| `td tree <id>` | Show parent/child tree |
 | `td tree add-child <parent> <child>` | Add child |
 
+## Notes
+
+| Command | Description |
+|---------|-------------|
+| `td note add <title> [--content "..."]` | Create a freeform note. Opens `$EDITOR` when content is omitted |
+| `td note list [flags]` | List notes. Alias: `ls`. Flags include `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json`, `--output table\|json` |
+| `td note show <id> [--json]` | Display note details |
+| `td note edit <id> [flags]` | Edit title or content. Flags: `--title`, `--content`; opens `$EDITOR` if neither is provided |
+| `td note delete <id>` | Soft-delete a note |
+| `td note pin <id>` | Pin a note |
+| `td note unpin <id>` | Unpin a note |
+| `td note archive <id>` | Archive a note |
+| `td note unarchive <id>` | Unarchive a note |
+
 ## Sessions
 
 | Command | Description |
 |---------|-------------|
-| `td usage [flags]` | Agent context. Flags: `--new-session`, `-q` |
-| `td session [name]` | Name session |
-| `td session --new` | Force new session |
-| `td status` | Dashboard view |
-| `td focus <id>` | Set focus |
+| `td usage [flags]` | Generate optimized context for agents. Flags: `--new-session`, `-q` |
+| `td session [name]` | Name the current session |
+| `td session --new` | Force a new session at context start |
+| `td status` | Show dashboard view. Alias: `current` |
+| `td focus <id>` | Set current focus |
 | `td unfocus` | Clear focus |
-| `td whoami` | Show session identity |
+| `td resume [id]` | Show context and set focus |
+| `td check-handoff [flags]` | Exit nonzero when in-progress work needs handoff. Flags: `--json`, `--quiet` |
+| `td whoami` | Show current session identity |
 
 ## Work Sessions
 
 | Command | Description |
 |---------|-------------|
-| `td ws start "name"` | Start work session |
+| `td ws start "name"` | Start a multi-issue work session. Alias: `worksession` |
 | `td ws tag <ids...>` | Tag issues |
-| `td ws log "message"` | Log to all tagged |
-| `td ws current` | Show session state |
-| `td ws handoff` | Handoff all, end session |
+| `td ws log "message"` | Log to all tagged issues |
+| `td ws current` | Show work session state |
+| `td ws handoff` | Handoff tagged issues and end the work session |
 
 ## Files
 
 | Command | Description |
 |---------|-------------|
-| `td link <id> <files...>` | Link files to issue |
-| `td unlink <id> <files...>` | Unlink files |
-| `td files <id>` | Show file status |
+| `td link <id> <files...>` | Link files to an issue |
+| `td unlink <id> <files...>` | Remove file associations |
+| `td files <id>` | List linked files with change status |
+
+## Sync and Collaboration
 
-## System
+| Command | Description |
+|---------|-------------|
+| `td auth login` | Log in to the sync server |
+| `td auth logout` | Log out from the sync server |
+| `td auth status` | Show authentication status |
+| `td sync` | Push and pull local events with the linked remote project |
+| `td sync --push` | Push only |
+| `td sync --pull` | Pull only |
+| `td sync --status` | Show sync status only |
+| `td sync init` | Interactive guided sync setup |
+| `td sync conflicts` | Show recent sync conflicts |
+| `td sync tail` | Show recent sync activity |
+| `td sync-project create <name> [--description "..."]` | Create and auto-link a remote sync project. Alias: `sp` |
+| `td sync-project link <project-id> [--force]` | Link local project to a remote sync project |
+| `td sync-project join [name-or-id]` | Join a remote sync project by name or ID |
+| `td sync-project list` | List remote sync projects |
+| `td sync-project members` | List project members |
+| `td sync-project invite <email> [role]` | Invite a member. Valid roles: `owner`, `writer`, `reader`; default: `writer` |
+| `td sync-project kick <user-id>` | Remove a member |
+| `td sync-project role <user-id> <role>` | Change a member role. Valid roles: `owner`, `writer`, `reader` |
+| `td sync-project unlink [--force]` | Unlink local project from remote sync |
+| `td doctor` | Run sync setup diagnostics |
+
+## System and Diagnostics
 
 | Command | Description |
 |---------|-------------|
-| `td init` | Initialize project |
+| `td init` | Initialize a project |
 | `td monitor` | Live TUI dashboard |
-| `td undo` | Undo last action |
-| `td version` | Show version |
-| `td export` | Export database |
-| `td import` | Import issues |
-| `td stats [subcommand]` | Usage statistics |
+| `td serve` | Start the td HTTP API server |
+| `td undo` | Undo the last action |
+| `td last` | Show the last action performed |
+| `td version [--short] [--check]` | Show version and optionally check for updates |
+| `td export [flags]` | Export issues. Flags: `--format json\|md`, `--output`, `--all`, `--render-markdown` |
+| `td import [file] [flags]` | Import issues. Flags: `--format json\|md`, `--dry-run`, `--force` |
+| `td info [--json]` | Show database statistics and project overview. Alias: `stats` |
+| `td stats analytics` | Show command usage analytics. Alias: `td stats usage` |
+| `td stats security` | Show security exception log. Alias for `td security` |
+| `td stats errors` | Show failed command attempts. Alias for `td errors` |
+| `td config list` | List all config values |
+| `td config get <key>` | Get a config value |
+| `td config set <key> <value>` | Set a config value |
+| `td config associate [dir] <target>` | Associate a directory with a td project |
+| `td config associations` | List directory associations. Alias: `assoc` |
+| `td config dissociate [dir]` | Remove a directory association |
+| `td feature list` | List known feature flags and resolved states |
+| `td feature get <flag>` | Get feature flag state |
+| `td feature set <flag> <value>` | Set a local feature flag override |
+| `td feature unset <flag>` | Remove a local feature flag override |
+| `td errors [flags]` | View failed td command attempts. Flags: `--limit`, `--since`, `--session`, `--json`, `--count`, `--clear` |
+| `td security [flags]` | View security exception audit log. Flags: `--json`, `--clear` |
+| `td workflow [--dot] [--mermaid]` | Show issue status workflow |
+| `td upgrade` | Run pending database migrations |
+| `td completion <shell>` | Generate shell completion |
+| `td debug-stats` | Output runtime memory and goroutine statistics as JSON |
diff --git a/website/docs/notes.md b/website/docs/notes.md
new file mode 100644
index 00000000..9fcd2076
--- /dev/null
+++ b/website/docs/notes.md
@@ -0,0 +1,75 @@
+---
+sidebar_position: 9
+---
+
+# Notes
+
+Notes are project-scoped, freeform markdown records for information that should live near the work but is not itself an issue. Use them for decisions, investigation scratchpads, meeting notes, release prep, or durable context that multiple future sessions may need.
+
+Notes are separate from issue comments:
+
+| Use | Best command |
+|-----|--------------|
+| Progress or discussion tied to one issue | `td comment <issue-id> "text"` |
+| Durable context that applies across issues or the whole project | `td note ...` |
+| Agent handoff for active implementation | `td handoff <issue-id> ...` |
+
+## Create Notes
+
+```bash
+td note add "Release checklist" --content "Verify docs build before tagging."
+td note add "Architecture decisions"
+```
+
+When `--content` is omitted, td opens `$EDITOR` for note content. If `$EDITOR` is unset, it falls back to `vi`.
+
+## List and Filter
+
+```bash
+td note list
+td note list --pinned
+td note list --archived
+td note list --all
+td note list --search "sync"
+td note list --limit 10
+```
+
+By default, `td note list` shows non-archived notes. Pinned notes are useful for context that should remain easy to find during repeated agent sessions.
+
+For scripts, use JSON output:
+
+```bash
+td note list --json
+td note list --output json
+```
+
+## Show Notes
+
+```bash
+td note show nt-abc123
+td note show nt-abc123 --json
+```
+
+Use `--json` when another tool needs stable fields rather than terminal formatting.
+
+## Edit Notes
+
+```bash
+td note edit nt-abc123 --title "Updated release checklist"
+td note edit nt-abc123 --content "Updated content"
+td note edit nt-abc123
+```
+
+When neither `--title` nor `--content` is provided, td opens `$EDITOR` with the current content.
+
+## Pin, Archive, and Delete
+
+```bash
+td note pin nt-abc123
+td note unpin nt-abc123
+td note archive nt-abc123
+td note unarchive nt-abc123
+td note delete nt-abc123
+```
+
+Archive notes that are still useful historically but no longer belong in the default list. Delete notes that should be hidden from normal note workflows.
diff --git a/website/docs/sync-collaboration.md b/website/docs/sync-collaboration.md
new file mode 100644
index 00000000..0cf85b38
--- /dev/null
+++ b/website/docs/sync-collaboration.md
@@ -0,0 +1,110 @@
+---
+sidebar_position: 10
+---
+
+# Sync and Collaboration
+
+td is local-first. Sync adds a remote project so multiple machines or collaborators can share the same issue history.
+
+The collaboration role names accepted by the CLI are:
+
+| Role | Intended access |
+|------|-----------------|
+| `owner` | Manage project membership |
+| `writer` | Pull and push project events |
+| `reader` | Pull project events |
+
+The default invite role is `writer`.
+
+## First-Time Setup
+
+A typical owner setup:
+
+```bash
+td auth login
+td auth status
+td sync-project create "api-redesign" --description "Shared td project"
+td sync
+td doctor
+```
+
+`td sync-project create` creates the remote project and attempts to link the current local td project automatically.
+
+A typical collaborator setup:
+
+```bash
+td init
+td auth login
+td sync-project join api-redesign
+td sync
+td doctor
+```
+
+If the collaborator already knows the project ID, they can link directly:
+
+```bash
+td sync-project link <project-id>
+td sync --pull
+```
+
+Use `td sync-project link <project-id> --force` only when replacing an existing link and intentionally resetting local sync state.
+
+## Authentication
+
+```bash
+td auth login
+td auth status
+td auth logout
+```
+
+Authentication stores local sync credentials. Use `td auth status` before debugging sync failures so you know whether the CLI can see a login.
+
+## Project Management
+
+```bash
+td sync-project create "project-name" --description "Optional description"
+td sync-project list
+td sync-project link <project-id>
+td sync-project join [name-or-id]
+td sync-project unlink
+```
+
+`sync-project` has the alias `sp`, so `td sp list` and `td sync-project list` are equivalent.
+
+## Members
+
+```bash
+td sync-project members
+td sync-project invite alex@example.com
+td sync-project invite alex@example.com reader
+td sync-project role <user-id> writer
+td sync-project kick <user-id>
+```
+
+Only `owner`, `writer`, and `reader` are valid roles. Owners manage membership; writers are the normal role for collaborators who should push work; readers are useful for read-only observers.
+
+## Sync Operations
+
+```bash
+td sync
+td sync --push
+td sync --pull
+td sync --status
+td sync conflicts
+td sync tail
+```
+
+Run plain `td sync` for normal bidirectional operation. Use `--push` or `--pull` for troubleshooting or controlled migration steps.
+
+`td sync conflicts` shows recent sync conflicts. `td sync tail` shows recent sync activity.
+
+## Diagnostics
+
+```bash
+td doctor
+td auth status
+td sync --status
+td sync-project members
+```
+
+`td doctor` checks the sync setup. It does not accept JSON or repair flags; use the other status commands alongside it when you need more detail.
diff --git a/website/docs/system-diagnostics.md b/website/docs/system-diagnostics.md
new file mode 100644
index 00000000..7a0474a9
--- /dev/null
+++ b/website/docs/system-diagnostics.md
@@ -0,0 +1,106 @@
+---
+sidebar_position: 13
+---
+
+# System and Diagnostics
+
+This page collects operational commands for configuration, diagnostics, exports, migration checks, and agent safety hooks.
+
+## Configuration
+
+```bash
+td config list
+td config get <key>
+td config set <key> <value>
+td config associate [dir] <target>
+td config associations
+td config dissociate [dir]
+```
+
+Use directory associations when a command needs to resolve the right td project from outside the project root. With one argument, `td config associate` treats that argument as the target and uses the current directory as the source.
+
+## Feature Flags
+
+```bash
+td feature list
+td feature get <flag>
+td feature set <flag> <value>
+td feature unset <flag>
+```
+
+Feature flags resolve from known defaults plus local project overrides. Use `td feature list` before changing a flag so the current state is visible.
+
+## Error and Security Logs
+
+```bash
+td errors
+td errors --limit 50 --since 24h
+td errors --session ses_abc123
+td errors --json
+td errors --count
+td security
+td security --json
+```
+
+`td errors` records failed td invocations for troubleshooting agent behavior and workflow friction. `td security` records review and close workflow exceptions such as creator approvals or self-close exceptions.
+
+Both commands support `--clear` when you intentionally want to reset the local log.
+
+## Sync Diagnostics
+
+```bash
+td doctor
+td auth status
+td sync --status
+```
+
+`td doctor` runs sync setup checks. It currently accepts no operational flags beyond `--help`, so combine it with `td auth status` and `td sync --status` for more context.
+
+## Workflow Inspection
+
+```bash
+td workflow
+td workflow --mermaid
+td workflow --dot
+```
+
+Use `td workflow` to inspect valid issue status transitions. The diagram flags are useful when documenting or reviewing state-machine changes.
+
+## Export and Import
+
+```bash
+td export --format json --output td-export.json
+td export --format md --render-markdown --output td-export.md
+td import td-export.json --dry-run
+td import td-export.json --force
+```
+
+Use `--dry-run` before imports that may overwrite existing issue data. Use `--all` on export when closed or deleted issues should be included.
+
+## Version, Migration, and Project Info
+
+```bash
+td version
+td version --short
+td version --check=false
+td upgrade
+td info
+td info --json
+td stats analytics
+td stats security
+td stats errors
+td last
+td debug-stats
+```
+
+`td upgrade` runs pending database migrations. `td info --json` is the machine-readable project overview; `td stats analytics`, `td stats security`, and `td stats errors` are the usage and diagnostic views.
+
+## Agent Exit Safety
+
+```bash
+td check-handoff
+td check-handoff --quiet
+td check-handoff --json
+```
+
+Agents should use `td check-handoff` before stopping work or ending a context window. It returns exit code 0 when no handoff is needed and exit code 1 when in-progress work needs a `td handoff`.
diff --git a/website/sidebars.js b/website/sidebars.js
index 4da1f856..74ad7c32 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -13,6 +13,8 @@ const sidebars = {
         'work-sessions',
         'deferral',
         'file-tracking',
+        'notes',
+        'sync-collaboration',
       ],
     },
     {
@@ -39,6 +41,7 @@ const sidebars = {
       items: [
         'command-reference',
         'analytics',
+        'system-diagnostics',
       ],
     },
   ],