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..21584942 --- /dev/null +++ b/website/docs/configuration.md @@ -0,0 +1,152 @@ +--- +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` | User config switch for auto-sync after the `sync_autosync` feature is enabled | +| `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, post-mutation, and monitor 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 +``` + +Auto-sync requires both `sync_autosync=true` and `sync.auto.enabled=true`. The config defaults can be present while the feature flag is still off, so enable the feature first when you expect automatic startup, post-mutation, or monitor sync to run: + +```bash +td feature set sync_autosync true +td config set sync.auto.enabled true +``` + +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..05d61416 --- /dev/null +++ b/website/docs/sync.md @@ -0,0 +1,205 @@ +--- +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. + +Auto-sync has two switches: + +- `sync_autosync` is the feature flag that allows startup, post-mutation, and monitor hooks to run. It defaults to `false`. +- `sync.auto.enabled` is the user config switch for those hooks once the feature is enabled. It defaults to `true`. + +Enable both when setting up automatic sync: + +```bash +td feature set sync_autosync true +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 +``` + +For one-off use, enable the feature through the environment before the command starts: + +```bash +TD_ENABLE_FEATURE=sync_cli,sync_autosync td list +``` + +Environment variables override config: + +| Variable | Purpose | +|----------|---------| +| `TD_FEATURE_SYNC_AUTOSYNC` | Enable or disable the auto-sync feature flag | +| `TD_ENABLE_FEATURE` | Enable gated features, such as `sync_cli,sync_autosync` | +| `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 | + +If `sync_autosync` is disabled, `sync.auto.*` values are still saved but no startup, post-mutation, or monitor auto-sync work runs. + +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', ], }, ],