From 3a0735a8ef88976a045f2cf3181494201023511c Mon Sep 17 00:00:00 2001 From: tester Date: Sat, 25 Apr 2026 02:52:14 -0700 Subject: [PATCH] docs: backfill missing CLI documentation Nightshift-Task: docs-backfill Nightshift-Ref: https://github.com/marcus/nightshift --- README.md | 8 +- docs/guides/README.md | 8 +- website/docs/command-reference.md | 222 +++++++++++++++++++---------- website/docs/notes.md | 75 ++++++++++ website/docs/sync-collaboration.md | 113 +++++++++++++++ website/docs/system-diagnostics.md | 114 +++++++++++++++ website/sidebars.js | 3 + 7 files changed, 463 insertions(+), 80 deletions(-) create mode 100644 website/docs/notes.md create mode 100644 website/docs/sync-collaboration.md create mode 100644 website/docs/system-diagnostics.md diff --git a/README.md b/README.md index 684416ad..71280e45 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](docs/td-logo.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 @@ -521,12 +521,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; optional sync is available when enabled. - **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..f9cda1c0 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 @@ -39,6 +39,12 @@ None yet. ## How To Use Skills (Quick Tutorial) +User-facing sync and notes documentation now lives in: + +- `website/docs/sync-collaboration.md` +- `website/docs/notes.md` +- `website/docs/system-diagnostics.md` + 1. Open the skill metadata and instructions: - `td-task-management/SKILL.md` 2. Follow linked references as needed: diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 28e9da1c..34898a6a 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -4,55 +4,66 @@ sidebar_position: 11 # Command Reference -Complete reference for all `td` commands. +Complete reference for the user-facing `td` command surface. Run `td --help` for the exact flag list on your installed version. + +## Global Flags + +| Flag | Description | +|------|-------------| +| `-h, --help` | Show help for a command | +| `-v, --version` | Show the td version | +| `-w, --work-dir ` | Resolve `.td-root` and git worktrees from a specific project directory | ## 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 ` | Display full issue details | -| `td update [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels` | -| `td delete ` | Soft-delete issue | -| `td restore ` | Restore soft-deleted issue | +| `td create [title]` | Create an issue. Aliases: `add`, `new`. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--parent`, `--epic`, `--points`, `--minor`, `--depends-on`, `--blocks`, `--defer`, `--due` | +| `td task create [title]` | Create a task. Shorthand for `td add --type task` | +| `td task list` | List tasks. Shorthand for `td list --type task` | +| `td list [filters]` | List issues. Aliases: `ls`. Common flags: `--status`, `--type`, `--priority`, `--labels`, `--epic`, `--parent`, `--filter`, `--search`, `--mine`, `--reviewable`, `--json`, `--format`, `--limit`, `--sort`, `--reverse`, `--all` | +| `td show [issue-id...]` | Show issue details. Aliases: `context`, `view`, `get`. Flags: `--children`, `--tree`, `--short`, `--long`, `--json`, `--render-markdown` | +| `td update [issue-id...]` | Update issue fields. Alias: `edit`. Common flags: `--title`, `--type`, `--priority`, `--status`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--append`, `--labels`, `--parent`, `--points`, `--sprint`, `--depends-on`, `--blocks`, `--defer`, `--due`, `--comment` | +| `td delete ` | Soft-delete one or more issues | +| `td deleted [--json]` | Show soft-deleted issues | +| `td restore ` | Restore soft-deleted issues | ## Workflow Commands | Command | Description | |---------|-------------| -| `td start ` | Begin work (status -> in_progress) | -| `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 | -| `td reviewable` | Show reviewable issues | -| `td approve [--reason "..."]` | Approve and close. Reason required for creator-exception approvals | -| `td reject --reason "..."` | Reject back to in_progress | -| `td block ` | Mark as blocked | -| `td unblock ` | Unblock to open | -| `td close ` | Admin close (not for completed work) | -| `td reopen ` | Reopen closed issue | -| `td comment "text"` | Add comment | +| `td start [issue-id...]` | Begin work and record the current session as implementer. Alias: `begin`. Flags: `--force`, `--reason` | +| `td unstart [issue-id...]` | Revert issues from `in_progress` to `open`. Alias: `stop` | +| `td log "message"` | Append a log entry to the current or focused issue. Use `--decision`, `--blocker`, `--hypothesis`, `--tried`, and `--result` for structured log entries | +| `td handoff [message]` | Capture structured handoff state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain`, `--message`, `--note` | +| `td review [issue-id...]` | Submit work for review. Aliases: `submit`, `finish` | +| `td reviewable` | Show issues awaiting review that the current session can review | +| `td approve [issue-id...]` | Approve and close reviewable issues. Flags: `--all`, `--reason`, `--json` | +| `td reject [issue-id...] --reason "..."` | Reject issues back to `open`. Flags include `--reason` and `--json` | +| `td block [issue-id...]` | Mark issues as blocked. Flag: `--reason` | +| `td unblock [issue-id...]` | Move blocked issues back to `open`. Flag: `--reason` | +| `td close [issue-id...]` | Direct admin close for duplicates, won't-fix, or cleanup. Aliases: `done`, `complete`. Agents should use `review` plus `approve` for completed work | +| `td reopen [issue-id...]` | Reopen closed issues back to `open` | +| `td comment [issue-id] "text"` | Add a comment. Alias for `td comments add` | +| `td comments [issue-id]` | List comments on an issue | +| `td comments add [issue-id] "text"` | Add a comment to an issue | ## Deferral & Due Dates | Command | Description | |---------|-------------| -| `td defer ` | Defer issue until a future date | -| `td defer --clear` | Remove deferral, make immediately actionable | -| `td due ` | Set due date on an issue | +| `td defer ` | Defer an issue until a future date | +| `td defer --clear` | Remove deferral | +| `td due ` | Set an issue due date | | `td due --clear` | Remove due date | -Date formats: `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, `2026-03-15` - -The `--defer` and `--due` flags are also available on `td create` and `td update`. +Date inputs support forms such as `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, and `2026-03-15`. -**List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--due-soon` +`td create` and `td update` also accept `--defer` and `--due`. `td list` includes temporal filters: `--deferred`, `--surfacing`, `--overdue`, and `--due-soon`. ## Agent-Safe Rich Text Input -Use `--description-file` and `--acceptance-file` for markdown-heavy fields so shells do not mangle code fences, quotes, or blank lines. Pass `-` to read the full field from stdin. +Use file-backed fields for markdown-heavy descriptions and acceptance criteria so shells do not mangle code fences, quotes, or blank lines. Pass `-` to read from stdin. ```bash td create "Document sync failure modes" \ @@ -66,82 +77,141 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - | 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 issues 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 | Command | Description | |---------|-------------| -| `td dep add ` | Add dependency | -| `td dep rm ` | Remove dependency | -| `td dep ` | Show dependencies | -| `td dep --blocking` | Show what it blocks | -| `td blocked-by ` | Issues blocked by this | -| `td critical-path` | Optimal unblocking sequence | +| `td dep add ` | Add a dependency | +| `td dep rm ` | Remove a dependency | +| `td dep ` | Show what an issue depends on | +| `td dep --blocking` | Show what depends on an issue | +| `td depends-on ` | Alias for showing dependencies | +| `td blocked-by ` | Show issues waiting on this issue | +| `td critical-path` | Show the sequence of issues that unblocks the most work | -## Boards +## Boards, Epics, and Trees | Command | Description | |---------|-------------| -| `td board create "name" --query "..."` | Create board | +| `td board create "name" --query "..."` | Create a query-backed board | | `td board list` | List boards | -| `td board show ` | Show board | -| `td board move ` | Position issue | -| `td board edit [flags]` | Edit board | -| `td board delete ` | Delete board | +| `td board show ` | Show issues on a board | +| `td board move ` | Set an issue position on a board | +| `td board unposition ` | Remove an explicit board position | +| `td board edit [flags]` | Edit a board name or query | +| `td board delete ` | Delete a board | +| `td epic create "title"` | Create an epic | +| `td epic list` | List epics | +| `td tree [issue-id]` | Visualize parent/child relationships. Flags: `--depth`, `--json` | +| `td tree add-child ` | Add a child issue to a parent issue | -## Epics & Trees +## Notes | Command | Description | |---------|-------------| -| `td epic create "title" [flags]` | Create epic | -| `td epic list` | List epics | -| `td tree ` | Show tree | -| `td tree add-child ` | Add child | +| `td note add ` | Create a freeform note. Use `--content` to avoid opening `$EDITOR` | +| `td note list` | List non-archived notes. Aliases: `ls`. Flags: `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json`, `--output json` | +| `td note show <id>` | Show a note. Flag: `--json` | +| `td note edit <id>` | Edit title and/or content. Flags: `--title`, `--content` | +| `td note delete <id>` | Soft-delete a note | +| `td note pin <id>` / `td note unpin <id>` | Pin or unpin a note | +| `td note archive <id>` / `td note unarchive <id>` | Archive or unarchive a note | -## Sessions +## Sessions and Work 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` | Generate an optimized context block for AI agents. Flags: `--new-session`, `--quiet`, `--compact`, `--json` | +| `td session [name]` | Name the current session. `td session --new` forces a new session at context start | +| `td session list` | List sessions scoped by branch and agent | +| `td session cleanup` | Remove stale session files | +| `td status` | Show session, focus, reviews, blocked, and ready issues. Alias: `current`. Flag: `--json` | +| `td focus [issue-id]` | Set the current working issue | | `td unfocus` | Clear focus | -| `td whoami` | Show session identity | +| `td resume [issue-id]` | Show context and set focus | +| `td whoami` | Show current session identity | +| `td check-handoff` | Return exit code 1 when the current session has in-progress work that needs handoff. Flags: `--json`, `--quiet` | +| `td ws start [name]` | Start a named work session. Alias group: `worksession` | +| `td ws tag [issue-ids...]` | Associate issues with the work session. Open issues are auto-started unless `--no-start` is passed | +| `td ws untag [issue-ids...]` | Remove issues from the work session | +| `td ws log "message"` | Log to the work session and tagged issues | +| `td ws current` | Show the current work session | +| `td ws list` | List recent work sessions | +| `td ws show <id>` | Show a past work session | +| `td ws handoff` | Generate handoffs for tagged issues. Flags: `--done`, `--remaining`, `--decision`, `--uncertain`, `--review`, `--continue` | +| `td ws end` | End the work session without handoff | -## Work Sessions +## Files | Command | Description | |---------|-------------| -| `td ws start "name"` | Start work session | -| `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 link [issue-id] [file-pattern...]` | Link files to an issue. Flags: `--role implementation\|test\|reference\|config`, `--recursive` | +| `td link <issue-id> --depends-on <other-id>` | Add a dependency through the link command | +| `td unlink [issue-id] [file-pattern]` | Remove file associations | +| `td files [issue-id]` | Show linked files and change status. Flags: `--changed`, `--untracked`, `--json` | -## Files +## Sync and Collaboration + +Sync commands are feature-gated by `sync_cli`. If they are not available in your process, start td with `TD_FEATURE_SYNC_CLI=true`. | Command | Description | |---------|-------------| -| `td link <id> <files...>` | Link files to issue | -| `td unlink <id> <files...>` | Unlink files | -| `td files <id>` | Show file status | - -## System +| `td auth login` | Log in to the sync server with the device-code flow | +| `td auth logout` | Clear local sync credentials | +| `td auth status` | Show the current sync account, server, and API key prefix | +| `td sync init` | Interactive guided sync setup | +| `td sync` | Push and pull local data with the linked remote project | +| `td sync --push` / `td sync --pull` | Push-only or pull-only sync | +| `td sync --status` | Show local and server sync status | +| `td sync conflicts` | Show recent sync conflicts. Flags: `--limit`, `--since` | +| `td sync tail` | Show recent sync activity. Flags: `--lines`, `--follow` | +| `td sync-project create <name>` | Create a remote project and auto-link the local project when possible | +| `td sync-project list` | List remote sync projects | +| `td sync-project join [name-or-id]` | Choose or match a remote project and link it locally | +| `td sync-project link <project-id>` | Link the local project to a remote project. Flag: `--force` | +| `td sync-project unlink` | Unlink local sync state. Flag: `--force` | +| `td sync-project members` | List members of the linked project | +| `td sync-project invite <email> [role]` | Invite a user. Valid roles are `owner`, `writer`, and `reader`; omitted role defaults to `writer` | +| `td sync-project kick <user-id>` | Remove a member | +| `td sync-project role <user-id> <role>` | Change a member role. Valid roles are `owner`, `writer`, and `reader` | + +## System and Diagnostics | Command | Description | |---------|-------------| -| `td init` | Initialize 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 init` | Initialize a td project | +| `td config get <key>` / `td config set <key> <value>` | Read or write configuration | +| `td config list` | List configuration values | +| `td config associate [dir] <target>` | Associate a directory with a td project in `~/.config/td/associations.json` | +| `td config associations` | List directory associations. Alias: `assoc` | +| `td config dissociate [dir]` | Remove a directory association | +| `td feature list` | List known feature flags and their resolved state | +| `td feature get <name>` | Show a feature flag state | +| `td feature set <name> <true\|false>` | Set a local project feature flag override | +| `td feature unset <name>` | Remove a local feature flag override | +| `td doctor` | Run diagnostic checks for sync setup | +| `td errors` | View failed td command attempts. Flags: `--limit`, `--since`, `--session`, `--count`, `--json`, `--clear` | +| `td security` | View creator-approval and self-close audit events. Flags: `--json`, `--clear` | +| `td stats` | View usage statistics, security events, and errors | +| `td stats analytics` | Show command usage analytics. Flags: `--since`, `--limit`, `--json`, `--clear` | +| `td stats errors` | Alias surface for `td errors` | +| `td stats security` | Alias surface for `td security` | +| `td info` | Show database statistics and project overview. Flag: `--json` | +| `td debug-stats` | Output Go runtime memory and goroutine statistics as JSON | +| `td workflow` | Show the issue status workflow. Flags: `--dot`, `--mermaid` | +| `td upgrade` | Run pending database migrations | +| `td version` | Show version and check for updates. Flags: `--short`, `--check` | +| `td last` | Show the last action, or `-n <count>` recent actions | +| `td export` | Export the database. Flags: `--format json\|md`, `--output`, `--all`, `--render-markdown` | +| `td import [file]` | Import issues. Flags: `--format json\|md`, `--dry-run`, `--force` | +| `td undo` | Undo the last action | +| `td monitor` | Open the live TUI dashboard | +| `td serve` | Start the HTTP API server. Flags: `--addr`, `--port`, `--token`, `--cors`, `--interval` | +| `td completion <shell>` | Generate shell completion scripts | diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 00000000..1b1596d8 --- /dev/null +++ b/website/docs/notes.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 8 +--- + +# Notes + +Notes are freeform project memory that does not belong to a specific issue. Use them for durable context such as design decisions, meeting notes, investigation scratchpads, rollout checklists, or links an agent should keep nearby. + +Issue comments are different: comments are attached to one issue and travel with that issue's activity history. Notes are standalone records with their own lifecycle, pin/archive state, and note IDs. + +## Create Notes + +```bash +td note add "Architecture decisions" +td note add "Meeting notes" --content "Discussed API design" +``` + +If `--content` is omitted, td opens `$EDITOR` and saves the edited buffer as the note content. + +## Find Notes + +```bash +td note list +td note list --pinned +td note list --archived +td note list --all +td note list --search "api" +td note list --limit 100 +``` + +By default, `td note list` hides archived notes. Use `--all` to include archived notes or `--archived` to show only archived notes. + +## View and Export Notes + +```bash +td note show nt-abc123 +td note show nt-abc123 --json +td note list --json +td note list --output json +``` + +JSON output is supported by `note list` and `note show`. Create, edit, pin, unpin, archive, unarchive, and delete print concise status lines instead. + +## Edit Notes + +```bash +td note edit nt-abc123 --title "New title" +td note edit nt-abc123 --content "Updated content" +td note edit nt-abc123 +``` + +With no `--title` or `--content` flag, td opens `$EDITOR` with the current note content. + +## Organize Notes + +```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 +``` + +Pinned notes appear with a `*` marker in table output. Archived notes stay out of the default list without being deleted. `note delete` is a soft delete. + +## When to Use Notes vs. Comments + +Use notes for project-wide context, recurring reminders, and working memory that multiple issues may need. + +Use comments when the information is part of one issue's record, review trail, or implementation discussion: + +```bash +td comment td-a1b2 "Validated the migration path on a copy of production data." +td comments td-a1b2 +``` diff --git a/website/docs/sync-collaboration.md b/website/docs/sync-collaboration.md new file mode 100644 index 00000000..6f8c4e4f --- /dev/null +++ b/website/docs/sync-collaboration.md @@ -0,0 +1,113 @@ +--- +sidebar_position: 9 +--- + +# Sync and Collaboration + +td sync lets multiple devices or collaborators share a project through a remote sync server. The local SQLite database remains the working copy; `td sync` pushes local changes and pulls remote changes for the linked sync project. + +Sync commands are behind the `sync_cli` feature flag. If the commands are not visible in `td --help`, start td with the process-level feature override: + +```bash +export TD_FEATURE_SYNC_CLI=true +td sync --status +``` + +## Authentication + +```bash +td auth login +td auth status +td auth logout +``` + +`td auth login` prompts for an email address, prints a verification URL and code, polls the server until the device flow completes, and stores credentials locally. `td auth status` shows the email, server URL, and API key prefix. `td auth logout` clears local credentials. + +## Project Setup + +For a new shared project: + +```bash +td init +td auth login +td sync-project create "Backend API" +td sync --status +td sync +``` + +`td sync-project create` creates the remote project and attempts to link the local project automatically. If you already have a remote project ID, link it directly: + +```bash +td sync-project link <project-id> +``` + +Use `--force` when relinking a project that already has synced events and you intentionally want to reset local sync state for the new remote project. + +## Joining an Existing Project + +After a collaborator has access: + +```bash +td init +td auth login +td sync-project join +td sync +``` + +`td sync-project join` lists available projects interactively when no argument is provided. It also accepts an exact project name or project ID: + +```bash +td sync-project join "Backend API" +td sync-project join <project-id> +``` + +## Collaboration Commands + +```bash +td sync-project list +td sync-project members +td sync-project invite teammate@example.com +td sync-project invite teammate@example.com reader +td sync-project role <user-id> writer +td sync-project kick <user-id> +td sync-project unlink +``` + +Valid member roles are `owner`, `writer`, and `reader`. Invitations default to `writer` when the role is omitted. + +`td sync-project members`, `invite`, `role`, and `kick` operate on the currently linked local project. + +## Syncing + +```bash +td sync +td sync --push +td sync --pull +td sync --status +``` + +The default `td sync` does both directions: push local pending events, then pull remote events. Use push-only or pull-only modes for troubleshooting or controlled handoffs. + +`td sync --status` shows local cursors, pending event count, and server event position for the linked project. + +## Troubleshooting Sync + +```bash +td doctor +td sync conflicts +td sync conflicts --since 24h --limit 50 +td sync tail +td sync tail -f +td sync tail -n 50 +``` + +`td doctor` runs sync setup diagnostics. `td sync conflicts` shows recent conflict records. `td sync tail` shows sync history, and `-f` follows new sync activity. + +## Unlinking + +```bash +td sync-project unlink +td sync-project unlink --force +``` + +Unlinking removes the local project association. When there are synced events, td can clear local sync state so the events can be pushed to a different project later; `--force` skips prompts. diff --git a/website/docs/system-diagnostics.md b/website/docs/system-diagnostics.md new file mode 100644 index 00000000..3171e63e --- /dev/null +++ b/website/docs/system-diagnostics.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 12 +--- + +# System and Diagnostics + +td keeps most state in the local project database, with small amounts of configuration in project config and `~/.config/td`. These commands help inspect configuration, feature flags, health, audit logs, and import/export state. + +## Configuration + +```bash +td config list +td config get <key> +td config set <key> <value> +``` + +Directory associations let you run td from one directory while using another directory's td project: + +```bash +td config associate /path/to/worktree /path/to/project +td config associate /path/to/project +td config associations +td config dissociate /path/to/worktree +``` + +Associations are stored in `~/.config/td/associations.json`. If only one argument is passed to `config associate`, td treats it as the target project and uses the current directory as the source. + +## Feature Flags + +```bash +td feature list +td feature get sync_cli +td feature set sync_cli true +td feature unset sync_cli +``` + +Feature flags resolve from environment overrides, then local project config, then defaults. Common sync-related flags include `sync_cli`, `sync_autosync`, `sync_monitor_prompt`, and `sync_notes`. + +## Health Checks + +```bash +td doctor +td upgrade +td version +td info +td workflow +``` + +`td doctor` runs sync setup diagnostics. `td upgrade` applies pending database migrations. `td version` checks the installed version, `td info` prints project/database statistics, and `td workflow` displays the issue status state machine. `td workflow --dot` and `td workflow --mermaid` export graph formats. + +## Agent Exit Checks + +```bash +td check-handoff +td check-handoff --quiet +td check-handoff --json +``` + +Agents should run `td check-handoff` before exiting or ending a context window. It returns exit code 0 when no handoff is needed and exit code 1 when the current session has in-progress work that should be handed off. + +## Error and Audit Logs + +```bash +td errors +td errors --since 24h --limit 50 +td errors --session ses_abc123 +td errors --json +td errors --count + +td security +td security --json +``` + +`td errors` records failed td invocations so you can spot CLI friction or repeated agent mistakes. `td security` shows review and close workflow exceptions such as creator-approval and self-close events. + +The same surfaces are available under `td stats`: + +```bash +td stats analytics +td stats errors +td stats security +``` + +`td stats analytics` reports command usage analytics. Set `TD_ANALYTICS=false` to disable analytics collection. + +## Runtime Diagnostics + +```bash +td debug-stats +td last +td last -n 10 +``` + +`td debug-stats` emits Go runtime memory and goroutine statistics as JSON for soak or endurance testing. `td last` shows the last recorded action, or the last `n` actions with `-n`. + +## Import and Export + +```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 `--all` on export to include closed and deleted issues. Use `--dry-run` on import before applying changes to a live project. + +## Local API Server + +```bash +td serve --port 0 +td serve --addr localhost --port 8080 --token secret --cors http://localhost:3000 +``` + +`td serve` starts the local HTTP API. When `--port 0` is used, td chooses an available port and writes it to `.todos/serve-port`. diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f856..c594c7cb 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -12,6 +12,8 @@ const sidebars = { 'epics', 'work-sessions', 'deferral', + 'notes', + 'sync-collaboration', 'file-tracking', ], }, @@ -38,6 +40,7 @@ const sidebars = { label: 'Reference', items: [ 'command-reference', + 'system-diagnostics', 'analytics', ], },