From 62290cfad3ea9fe5e19224979a4cef8c9e7a951c Mon Sep 17 00:00:00 2001 From: tester Date: Sun, 26 Apr 2026 02:52:59 -0700 Subject: [PATCH] docs: backfill website CLI docs Add focused website documentation for notes, sync and collaboration, configuration, and troubleshooting. Refresh the command reference and sidebar so implemented CLI features are discoverable against current main. Nightshift-Task: docs-backfill Nightshift-Ref: https://github.com/marcus/nightshift --- website/docs/ai-integration.md | 8 +- website/docs/analytics.md | 6 +- website/docs/command-reference.md | 69 +++++++++- website/docs/configuration.md | 145 +++++++++++++++++++++ website/docs/core-workflow.md | 6 +- website/docs/intro.md | 11 ++ website/docs/notes.md | 119 ++++++++++++++++++ website/docs/sync.md | 187 +++++++++++++++++++++++++++ website/docs/troubleshooting.md | 202 ++++++++++++++++++++++++++++++ website/sidebars.js | 10 ++ 10 files changed, 752 insertions(+), 11 deletions(-) create mode 100644 website/docs/configuration.md create mode 100644 website/docs/notes.md create mode 100644 website/docs/sync.md create mode 100644 website/docs/troubleshooting.md diff --git a/website/docs/ai-integration.md b/website/docs/ai-integration.md index 30557855..17adfec0 100644 --- a/website/docs/ai-integration.md +++ b/website/docs/ai-integration.md @@ -101,14 +101,16 @@ td supports three review policy modes via `review_policy_mode`: The legacy `balanced_review_policy` flag is deprecated; prefer `review_policy_mode=balanced` instead. -Pin or change the mode: +Use the default `delegated` mode unless your project needs a stricter policy. For one-off commands, set the environment override: ```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 override, set `feature_string_flags.review_policy_mode` in `.todos/config.json` to `strict`, `balanced`, or `delegated`. + +When agents move between machines or shared environments, [Sync and Collaboration](./sync.md) covers the commands for linking a project, inviting teammates, and pulling remote updates. + ### 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. diff --git a/website/docs/analytics.md b/website/docs/analytics.md index ac4b7d05..ca56a2e0 100644 --- a/website/docs/analytics.md +++ b/website/docs/analytics.md @@ -20,7 +20,7 @@ Shows which commands are used most, frequency patterns, and usage over time. td stats security ``` -Shows self-close exceptions (when issues were closed without proper review workflow). +Shows review workflow exceptions, such as administrative closes or legacy creator-approval exceptions. ## Error Tracking @@ -30,6 +30,8 @@ td stats errors Shows failed command attempts - useful for debugging agent issues. +For filters and cleanup commands, see [Troubleshooting](./troubleshooting.md#command-error-logs). + ## Monitor Stats Press `s` in the monitor to view: @@ -50,4 +52,4 @@ Set this environment variable to disable local analytics collection. ## Data Storage -All analytics stored in local SQLite database (`.todos/db.sqlite`). Nothing leaves your machine. +All analytics are stored in the local SQLite database (`.todos/issues.db`). Nothing leaves your machine. diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index b81278c3..689ab1b6 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -17,6 +17,20 @@ Complete reference for all `td` commands. | `td delete ` | Soft-delete issue | | `td restore ` | Restore soft-deleted issue | +## Notes + +| Command | Description | +|---------|-------------| +| `td note add "title" [--content "..."]` | Create a freeform note. Opens `$EDITOR` when content is omitted | +| `td note list [flags]` | List notes. Flags: `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json` | +| `td note show ` | Display a note | +| `td note edit [flags]` | Edit note title or content. Flags: `--title`, `--content` | +| `td note delete ` | Soft-delete a note | +| `td note pin ` | Pin a note | +| `td note unpin ` | Unpin a note | +| `td note archive ` | Archive a note | +| `td note unarchive ` | Restore an archived note | + ## Workflow Commands | Command | Description | @@ -25,15 +39,16 @@ Complete reference for all `td` commands. | `td unstart ` | Revert to open | | `td log "message" [flags]` | Log progress. Flags: `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result` | | `td handoff [flags]` | Capture state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain` | -| `td review ` | Submit for review. Submitting session is recorded as `review_requested_by_session` | +| `td review [flags]` | Submit for review. Flags: `--reason`, `--minor`, `--json`. Submitting session is recorded as `review_requested_by_session` | | `td reviewable [--include-approved]` | Show issues you can review; with `--include-approved`, also show reviewed issues you can close | -| `td approve [flags]` | Approve and close, record-only review, or close using a recorded approval. Flags: `--reason`, `--record-only`, `--decision approved\|changes_requested`, `--all` | -| `td reject --reason "..."` | Reject back to open. Supersedes any active approval review | +| `td approve [flags]` | Approve and close, record-only review, or close using a recorded approval. Flags: `--reason`, `--record-only`, `--decision approved\|changes_requested`, `--all`, `--json` | +| `td reject --reason "..."` | Reject back to open. Supersedes any active approval review. Flags: `--reason`, `--json` | | `td block ` | Mark as blocked | | `td unblock ` | Unblock to open | | `td close ` | Admin close only (duplicates, won't-fix, cleanup). Use `td approve` for reviewed work | | `td reopen ` | Reopen closed issue | | `td comment "text"` | Add comment | +| `td workflow [--mermaid\|--dot]` | Show the issue status workflow | ## Deferral & Due Dates @@ -127,6 +142,7 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - | `td session [name]` | Name session | | `td session --new` | Force new session | | `td status` | Dashboard view | +| `td resume ` | Show issue context and set focus | | `td focus ` | Set focus | | `td unfocus` | Clear focus | | `td whoami` | Show session identity | @@ -149,6 +165,44 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - | `td unlink ` | Unlink files | | `td files ` | Show file status | +## Sync & Collaboration + +These commands are registered when the `sync_cli` feature is enabled, for example with `TD_ENABLE_FEATURE=sync_cli`. + +| Command | Description | +|---------|-------------| +| `td auth login` | Log in to a sync server with the device flow | +| `td auth status` | Show saved auth status | +| `td auth logout` | Remove local sync credentials | +| `td sync [flags]` | Push and pull local project data. Flags: `--push`, `--pull`, `--status` | +| `td sync init` | Interactive sync setup | +| `td sync tail [flags]` | Show recent sync activity. Flags: `--follow`, `--lines` | +| `td sync conflicts [flags]` | Show recent sync conflicts. Flags: `--limit`, `--since` | +| `td sync-project create "name" [--description "..."]` | Create and link a remote project | +| `td sync-project join [name-or-id]` | Join a remote project by prompt, name, or ID | +| `td sync-project link [--force]` | Link local database to a remote project | +| `td sync-project unlink [--force]` | Unlink local database from remote sync | +| `td sync-project list` | List remote projects visible to the current user | +| `td sync-project members` | List project members | +| `td sync-project invite [role]` | Invite a member as `owner`, `writer`, or `reader` | +| `td sync-project role ` | Change a member role | +| `td sync-project kick ` | Remove a project member | + +## Configuration + +| Command | Description | +|---------|-------------| +| `td config list` | List sync config as JSON | +| `td config get ` | Read a sync config key | +| `td config set ` | Set a sync config key | +| `td config associate [dir] ` | Associate a directory with a td project | +| `td config associations` | List directory associations | +| `td config dissociate [dir]` | Remove a directory association | +| `td feature list` | List known feature flags and resolved state | +| `td feature get ` | Show one feature flag | +| `td feature set ` | Set a project-local feature flag | +| `td feature unset ` | Remove a project-local feature override | + ## System | Command | Description | @@ -156,7 +210,16 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - | `td init` | Initialize project | | `td monitor` | Live TUI dashboard | | `td undo` | Undo last action | +| `td undo --list` | List recent undoable actions in the current session | +| `td last [-n N]` | Show recent actions in the current session | +| `td doctor` | Run sync diagnostics | +| `td doctor fk` | Report foreign-key orphan counts without modifying data | +| `td errors [flags]` | View failed command attempts. Flags: `--since`, `--session`, `--limit`, `--json`, `--count`, `--clear` | +| `td security [flags]` | View review/close exception audit log. Flags: `--json`, `--clear` | | `td version` | Show version | | `td export` | Export database | | `td import` | Import issues | | `td stats [subcommand]` | Usage statistics | +| `td stats analytics` | Command usage analytics | +| `td stats errors` | Failed command attempts | +| `td stats security` | Security exception log | diff --git a/website/docs/configuration.md b/website/docs/configuration.md new file mode 100644 index 00000000..1a9fd2e5 --- /dev/null +++ b/website/docs/configuration.md @@ -0,0 +1,145 @@ +--- +sidebar_position: 16 +--- + +# Configuration + +td stores configuration in a few places because some settings are global to your user account, while others belong to the current project. + +## Config Locations + +| Location | Scope | Contains | +|----------|-------|----------| +| `~/.config/td/config.json` | User-global | Sync URL, sync enablement, auto-sync settings | +| `~/.config/td/auth.json` | User-global | Sync API key, email, server URL, device ID | +| `~/.config/td/associations.json` | User-global | Directory-to-project associations | +| `.todos/config.json` | Project-local | Focus, active work session, monitor filters, feature flags | +| `.todos/issues.db` | Project-local database | Issues, boards, notes, logs, handoffs, sync state, board positions | + +Project-local config is safe to keep with a project. User-global auth files should not be committed. + +## Sync Config + +`td config` manages sync settings in `~/.config/td/config.json`. + +```bash +td config list +td config get sync.url +td config set sync.url https://sync.example.com +``` + +Supported keys: + +| Key | Default | Description | +|-----|---------|-------------| +| `sync.url` | `http://localhost:8080` | Sync server URL | +| `sync.enabled` | `false` when omitted | Stored sync enablement flag | +| `sync.auto.enabled` | `true` | Master switch for auto-sync hooks | +| `sync.auto.debounce` | `3s` | Minimum time between post-mutation syncs | +| `sync.auto.interval` | `5m` | Periodic sync interval used by monitor workflows | +| `sync.auto.pull` | `true` | Pull as part of auto-sync | +| `sync.auto.on_start` | `true` | Sync when td commands start | +| `sync.snapshot_threshold` | `100` | Server event count before snapshot bootstrap is attempted | + +:::info +`td config` is registered with the sync CLI. If the command is unavailable, enable `sync_cli` with `TD_ENABLE_FEATURE=sync_cli`. +::: + +## Feature Flags + +Use `td feature` for project-local feature flags stored in `.todos/config.json`. + +```bash +td feature list +td feature get sync_cli +td feature set sync_cli true +td feature unset sync_cli +``` + +Known flags include: + +| Feature | Default | Purpose | +|---------|---------|---------| +| `balanced_review_policy` | `false` | Deprecated compatibility flag; prefer `review_policy_mode=balanced` | +| `sync_cli` | `false` | Registers sync, auth, project, doctor, and config commands | +| `sync_autosync` | `false` | Enables startup and post-mutation auto-sync hooks | +| `sync_monitor_prompt` | `false` | Enables monitor sync setup prompts | +| `sync_notes` | `true` | Allows notes to sync as an entity type | + +Environment overrides win over project config: + +```bash +TD_FEATURE_SYNC_CLI=true td sync --status +TD_ENABLE_FEATURE=sync_cli,sync_autosync td sync +TD_DISABLE_FEATURE=sync_autosync td list +TD_DISABLE_EXPERIMENTAL=1 td list +``` + +Feature override forms: + +| Variable | Effect | +|----------|--------| +| `TD_FEATURE_` | Set a specific feature, such as `TD_FEATURE_SYNC_CLI=true` | +| `TD_ENABLE_FEATURE` or `TD_ENABLE_FEATURES` | Comma-separated features to enable | +| `TD_DISABLE_FEATURE` or `TD_DISABLE_FEATURES` | Comma-separated features to disable | +| `TD_DISABLE_EXPERIMENTAL` | Disable all experimental features | + +## Review Policy + +Review behavior is controlled by the string feature `review_policy_mode`. New installs default to `delegated`, where an independent reviewer can record an approval and any session can close using that recorded approval. + +```bash +TD_FEATURE_REVIEW_POLICY_MODE=delegated td approve td-a1b2 +``` + +Supported values: + +| Mode | Behavior | +|------|----------| +| `delegated` | Default. Reviewers can record approval; any session may close after that independent approval exists | +| `strict` | Reviewer must have no prior involvement, and review plus close happen together | +| `balanced` | Strict plus a creator-approval exception for externally implemented work | + +For a persistent project override, edit `.todos/config.json`: + +```json +{ + "feature_string_flags": { + "review_policy_mode": "delegated" + } +} +``` + +`td feature` manages boolean feature flags. The legacy boolean `balanced_review_policy` still resolves to `balanced` or `strict` when explicitly set, but it is deprecated. Do not set both `review_policy_mode` and `balanced_review_policy`; conflicting values fail closed. See [AI Agent Integration](./ai-integration.md#review-policy-modes) for multi-agent examples. + +## Environment Variables + +Common environment variables: + +| Variable | Purpose | +|----------|---------| +| `TD_WORK_DIR` | Use a project directory without changing the shell cwd | +| `TD_SESSION_ID` | Pin the current agent/session identity | +| `TD_LOG_FILE` | Write td debug logs to a file | +| `TD_ANALYTICS` | Set to `false` to disable local analytics | +| `TD_SYNC_URL` | Override the sync server URL | +| `TD_AUTH_KEY` | Override sync API key | +| `TD_SYNC_SNAPSHOT_THRESHOLD` | Override snapshot bootstrap threshold | +| `TD_SYNC_AUTO` | Override auto-sync enablement | +| `TD_SYNC_AUTO_START` | Override startup auto-sync | +| `TD_SYNC_AUTO_DEBOUNCE` | Override post-mutation debounce | +| `TD_SYNC_AUTO_INTERVAL` | Override periodic auto-sync interval | +| `TD_SYNC_AUTO_PULL` | Override whether auto-sync pulls | + +## Directory Associations + +Associations let td use one project database while commands run from another directory. This is useful for monorepos, generated worktrees, or tools that launch from nested folders. + +```bash +td config associate /path/to/project +td config associate /path/to/nested/dir /path/to/project +td config associations +td config dissociate /path/to/nested/dir +``` + +Associations are stored in `~/.config/td/associations.json`. diff --git a/website/docs/core-workflow.md b/website/docs/core-workflow.md index c7600403..301120bc 100644 --- a/website/docs/core-workflow.md +++ b/website/docs/core-workflow.md @@ -98,14 +98,14 @@ td exposes three policy modes via `review_policy_mode`: The legacy `balanced_review_policy` flag is **deprecated**; prefer `review_policy_mode=balanced` instead. Setting the legacy flag still works but emits a one-time deprecation warning. -Set the mode per-project or via env: +Use the default `delegated` mode unless your project needs a stricter policy. For one-off commands, set the environment override: ```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 override, set `feature_string_flags.review_policy_mode` in `.todos/config.json` to `strict`, `balanced`, or `delegated`. + ### Balanced (Legacy) — Creator Exception Under `balanced`, a session that *created* a task (but didn't implement it) can approve with a reason: diff --git a/website/docs/intro.md b/website/docs/intro.md index 2201fe12..50582cf1 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -78,6 +78,15 @@ td review td-a1b2 Issue IDs like `td-a1b2` are generated automatically when you create an issue. Use `td list` to see your current issues and their IDs. ::: +## Project Memory + +Use issues for reviewed work and handoffs. Use [notes](./notes.md) for freeform project memory that should survive across sessions but does not need status, priority, or review. + +```bash +td note add "Release runbook" --content "Test, build, tag, publish." +td note pin nt-abc123 +``` + ## Setting Up with AI Agents Add this to your `CLAUDE.md`, system prompt, or agent instructions: @@ -94,4 +103,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 +- [Sync and Collaboration](./sync.md) -- Share a td project across machines or teammates +- [Configuration](./configuration.md) -- Config files, feature flags, environment variables - [Query Language](./query-language.md) -- Filter and search issues with structured queries diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 00000000..b038f806 --- /dev/null +++ b/website/docs/notes.md @@ -0,0 +1,119 @@ +--- +sidebar_position: 8 +--- + +# Notes + +Notes are freeform project memory. Use them for context that does not fit a task lifecycle: architecture decisions, meeting notes, release checklists, debugging breadcrumbs, or "remember this later" material. + +Notes live in the same local td database as issues, but they are not issues. They do not have status, priority, review state, or dependencies. + +## Create Notes + +Create a note with inline content: + +```bash +td note add "Release checklist" --content "Tag, build, smoke test, publish." +``` + +Create a longer note in your editor: + +```bash +td note add "Auth design notes" +``` + +When `--content` is omitted, td opens `$EDITOR` and saves the final buffer as the note content. If `$EDITOR` is not set, td falls back to `vi`. + +## Find Notes + +List active notes: + +```bash +td note list +``` + +Filter the list: + +```bash +td note list --search "sync" +td note list --pinned +td note list --archived +td note list --all +td note list --limit 50 +``` + +Get machine-readable output: + +```bash +td note list --json +td note list --output json +``` + +## Read and Edit + +Show a note: + +```bash +td note show nt-abc123 +td note show nt-abc123 --json +``` + +Update the title or content directly: + +```bash +td note edit nt-abc123 --title "Sync launch notes" +td note edit nt-abc123 --content "New content" +``` + +Open the existing content in your editor: + +```bash +td note edit nt-abc123 +``` + +## Pin, Archive, and Delete + +Pin notes you want near the top of the list: + +```bash +td note pin nt-abc123 +td note unpin nt-abc123 +``` + +Archive notes that should stay searchable but leave the default list: + +```bash +td note archive nt-abc123 +td note unarchive nt-abc123 +``` + +Delete soft-removes a note: + +```bash +td note delete nt-abc123 +``` + +## Practical Workflows + +Use notes for stable project context: + +```bash +td note add "API invariants" --content "Project IDs are UUIDs. Issue IDs keep the td- prefix." +td note pin nt-abc123 +``` + +Use notes to preserve investigation state outside a single issue: + +```bash +td note add "SQLite lock investigation" +td note list --search "SQLite" +``` + +Use notes as lightweight runbooks: + +```bash +td note add "Release runbook" --content "1. go test ./...\n2. build website\n3. tag release" +td note pin nt-release +``` + +For work that needs review, dependencies, ownership, or handoff state, create an issue instead. For durable background memory, use a note. diff --git a/website/docs/sync.md b/website/docs/sync.md new file mode 100644 index 00000000..9ec55352 --- /dev/null +++ b/website/docs/sync.md @@ -0,0 +1,187 @@ +--- +sidebar_position: 12 +--- + +# Sync and Collaboration + +Sync shares a local td project with a remote sync server. It lets multiple people or agents push issues, logs, comments, handoffs, boards, dependencies, file links, work sessions, and notes to the same project. + +Sessions stay local. Review history and issue data sync, but each machine keeps its own session identity. + +:::info +Sync commands are gated by the `sync_cli` feature. If `td sync` or `td auth` is not available, enable the feature first: + +```bash +export TD_ENABLE_FEATURE=sync_cli +``` + +You can also set it in project config with `td feature set sync_cli true`, but command registration happens when td starts, so environment variables are the most reliable way to expose gated commands. +::: + +## Quick Setup + +Run the guided setup: + +```bash +td sync init +``` + +The wizard checks the server URL, verifies authentication, and helps create or join a remote project. + +For manual setup: + +```bash +td config set sync.url https://sync.example.com +td auth login +td sync-project create "backend-api" +td sync +``` + +Teammates usually join an existing project: + +```bash +td auth login +td sync-project join +td sync +``` + +## Authentication + +Log in with the device flow: + +```bash +td auth login +``` + +td prompts for your email, prints a verification URL and code, then stores credentials in `~/.config/td/auth.json`. + +Check or clear auth state: + +```bash +td auth status +td auth logout +``` + +Use `TD_AUTH_KEY` for CI or short-lived automation: + +```bash +TD_AUTH_KEY=td_live_xxx td sync --status +``` + +## Projects + +Create and link a remote project in one step: + +```bash +td sync-project create "launch-plan" --description "Shared release tracker" +``` + +List, join, link, or unlink projects: + +```bash +td sync-project list +td sync-project join "launch-plan" +td sync-project link +td sync-project unlink +``` + +Prefer `td sync-project join` for humans because it validates the project against the server. Use `td sync-project link ` for scripts that already have the exact project ID. + +If you need to relink a database that already has synced events, use `--force` only after confirming you want to reset local sync state: + +```bash +td sync-project link --force +td sync-project unlink --force +``` + +## Push, Pull, and Status + +Run a full bidirectional sync: + +```bash +td sync +``` + +Push or pull only: + +```bash +td sync --push +td sync --pull +``` + +Inspect local and server state: + +```bash +td sync --status +td sync tail +td sync tail -f +``` + +On first pull, td may bootstrap from a server snapshot when the server has enough events. Before replacing the local database with a snapshot, td writes a `.todos/issues.db.pre-snapshot-backup` file. + +## Auto-Sync + +Auto-sync can push and pull on command startup, after mutating commands, and periodically in the monitor. + +```bash +td config set sync.auto.enabled true +td config set sync.auto.on_start true +td config set sync.auto.debounce 3s +td config set sync.auto.interval 5m +td config set sync.auto.pull true +``` + +Environment variables override config: + +| Variable | Purpose | +|----------|---------| +| `TD_SYNC_AUTO` | Enable or disable auto-sync | +| `TD_SYNC_AUTO_START` | Enable or disable startup sync | +| `TD_SYNC_AUTO_DEBOUNCE` | Debounce post-mutation sync, such as `3s` | +| `TD_SYNC_AUTO_INTERVAL` | Periodic monitor sync interval, such as `5m` | +| `TD_SYNC_AUTO_PULL` | Include pull during auto-sync | + +Auto-sync is quiet by design. Use `td sync --status`, `td sync tail`, or `td doctor` when you need explicit feedback. + +## Collaboration Roles + +Project members can be owners, writers, or readers. + +| Role | What it can do | +|------|----------------| +| `owner` | Read, write, invite members, remove members, and change roles | +| `writer` | Read and write project data | +| `reader` | Read project data without pushing local edits | + +Manage members: + +```bash +td sync-project members +td sync-project invite alice@example.com writer +td sync-project role reader +td sync-project kick +``` + +## Conflicts + +Sync uses last-write-wins conflict handling. If remote changes overwrite local records during pull, td preserves conflict records for review. + +```bash +td sync conflicts +td sync conflicts --limit 10 +td sync conflicts --since 24h +``` + +Use the conflict list to identify what changed, then manually restore or reapply anything that should win. + +## Common Recovery Commands + +```bash +td doctor +td auth login +td sync-project join +td sync --status +td sync --pull +``` + +For broader diagnostics, see [Troubleshooting](./troubleshooting.md). diff --git a/website/docs/troubleshooting.md b/website/docs/troubleshooting.md new file mode 100644 index 00000000..ce918902 --- /dev/null +++ b/website/docs/troubleshooting.md @@ -0,0 +1,202 @@ +--- +sidebar_position: 17 +--- + +# Troubleshooting + +Start with the command that matches the failure mode: + +```bash +td doctor +td errors +td stats errors +td security +td last +``` + +## Sync Diagnostics + +Run the sync doctor: + +```bash +td doctor +``` + +It checks authentication config, server reachability, API key validity, local database access, project linking, and pending events. + +If sync commands are unavailable, enable the gated sync CLI first: + +```bash +export TD_ENABLE_FEATURE=sync_cli +td doctor +``` + +For database integrity checks, `td doctor fk` reports orphaned foreign-key relations without modifying data: + +```bash +td doctor fk +``` + +## Command Error Logs + +td records failed command attempts so agent runs can be debugged later. + +```bash +td errors +td errors --since 24h +td errors --session ses_abc123 +td errors --limit 50 +td errors --json +td errors --count +td errors --clear +``` + +`td stats errors` is an alias-style stats view for the same class of failures. + +## Security Exceptions + +Review workflow exceptions are written to the security log. + +```bash +td security +td security --json +td security --clear +td stats security +``` + +Use this when a task was closed through a creator exception, an administrative close, or another review-policy exception that should be audited. + +## Undo and Recovery + +Show recent actions in the current session: + +```bash +td undo --list +td last +td last -n 5 +``` + +Undo the most recent reversible action: + +```bash +td undo +``` + +Undo supports common issue, dependency, file-link, board, handoff, and review-state actions. It is session-scoped, so it only sees actions from the current td session. + +## Common Sync Failures + +### `unknown command "sync"` or `unknown command "auth"` + +Enable the sync CLI: + +```bash +export TD_ENABLE_FEATURE=sync_cli +``` + +Add it to your shell profile if you use sync regularly. + +### `not logged in` + +Credentials are missing or expired: + +```bash +td auth login +td auth status +``` + +For CI, set `TD_AUTH_KEY`. + +### `project not linked` + +The local database is not connected to a remote project: + +```bash +td sync-project join +td sync --status +``` + +Use `td sync-project list` to confirm you have access to the project. + +### `unauthorized` + +Your API key is invalid, expired, or revoked: + +```bash +td auth logout +td auth login +td sync --status +``` + +### 404 or missing remote project + +The local project may be linked to an old or mistyped project ID: + +```bash +td sync-project list +td sync-project join +``` + +Prefer `join` over raw `link` for interactive setup because it validates the project against the server. + +### Local changes are not appearing remotely + +Check pending events and push state: + +```bash +td sync --status +td sync --push +td sync tail +``` + +`Nothing to push` means the local action log has no unsynced events. It does not prove the server is healthy; use `td sync --status` or `td doctor` for that. + +### Remote changes overwrite local edits + +Review conflict records: + +```bash +td sync conflicts +td sync conflicts --since 24h +``` + +td uses last-write-wins conflict handling. Reapply the desired local change after reviewing the conflict. + +## Config Problems + +Show active config: + +```bash +td config list +td feature list +``` + +Check the most common overrides: + +```bash +echo "$TD_WORK_DIR" +echo "$TD_ENABLE_FEATURE" +echo "$TD_DISABLE_FEATURE" +echo "$TD_SYNC_URL" +echo "$TD_AUTH_KEY" +``` + +If td is reading the wrong project, use a work directory or association: + +```bash +TD_WORK_DIR=/path/to/project td list +td config associate /path/to/current/dir /path/to/project +td config associations +``` + +## Database and Snapshot Recovery + +Sync snapshot bootstrap creates a backup before replacing the local database: + +```bash +.todos/issues.db.pre-snapshot-backup +``` + +If a snapshot bootstrap produced an unexpected local state, stop running mutating td commands, copy the current `.todos/issues.db` somewhere safe, and restore the pre-snapshot backup manually. + +For routine issue mistakes, use `td undo` before editing database files directly. diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f856..3ad0962a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -12,6 +12,7 @@ const sidebars = { 'epics', 'work-sessions', 'deferral', + 'notes', 'file-tracking', ], }, @@ -24,6 +25,13 @@ const sidebars = { 'ai-integration', ], }, + { + type: 'category', + label: 'Collaboration', + items: [ + 'sync', + ], + }, { type: 'category', label: 'HTTP API', @@ -39,6 +47,8 @@ const sidebars = { items: [ 'command-reference', 'analytics', + 'configuration', + 'troubleshooting', ], }, ],