diff --git a/website/docs/ai-integration.md b/website/docs/ai-integration.md index 30557855..8e15655d 100644 --- a/website/docs/ai-integration.md +++ b/website/docs/ai-integration.md @@ -53,6 +53,8 @@ Flags: - `--new-session` -- start a fresh session (use at conversation start) - `-q` -- quiet mode, shorter output (use after first read) +For durable context that is useful across issues, agents can also use [notes](./notes.md). Keep issue-specific progress in `td log` and `td handoff`. + ## Recommended Agent Workflow ```bash @@ -104,11 +106,11 @@ The legacy `balanced_review_policy` flag is deprecated; prefer `review_policy_mo Pin or change the mode: ```bash -td feature set review_policy_mode strict # or balanced, or delegated -# or, one-off: TD_FEATURE_REVIEW_POLICY_MODE=strict td approve td-a1b2 ``` +For a persistent project setting, store `review_policy_mode` in `.todos/config.json` under `feature_string_flags`. See [Configuration](./configuration.md) for the current config shape. + ### Delegated Review: Orchestrator + Sub-Agents Under `delegated`, an orchestrator coordinates work across sub-agents. The review must come from a session that did not participate in implementation, but the close may be performed by any session — so the orchestrator can finish the task once a reviewer sub-agent records approval. diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index b81278c3..d4979d7c 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -4,51 +4,67 @@ sidebar_position: 11 # Command Reference -Complete reference for all `td` commands. +Complete reference for public `td` commands. For task-oriented guides, see [Core Workflow](./core-workflow.md), [Notes](./notes.md), [Configuration](./configuration.md), [Sync CLI](./sync-cli.md), and [Directory Associations](./directory-associations.md). + +## Global Flags + +| Flag | Description | +|------|-------------| +| `-h, --help` | Show help for a command. | +| `-v, --version` | Show version information. | +| `-w, --work-dir ` | Resolve the td project from a specific directory. Useful for scripts and worktrees. | + +Example: + +```bash +td -w /path/to/project list --status open +``` ## 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 | +| Command | Description | Example | +|---------|-------------|---------| +| `td create "title" [flags]` | Create an issue. Aliases: `add`, `new`. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--parent`, `--epic`, `--minor`, `--defer`, `--due`. | `td create "Add user auth" --type feature --priority P1` | +| `td list [flags]` | List issues. Alias: `ls`. Common filters: `--status`, `--type`, `--priority`, `--epic`, `--all`, `--deferred`, `--surfacing`, `--overdue`, `--due-soon`, `--json`. | `td list --status in_progress` | +| `td show ` | Display full issue details. Aliases: `context`, `view`, `get`. | `td show td-a1b2` | +| `td update [flags]` | Update issue fields. Alias: `edit`. Common flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--defer`, `--due`. | `td update td-a1b2 --priority P1` | +| `td delete ` | Soft-delete issues. | `td delete td-a1b2` | +| `td restore ` | Restore soft-deleted issues. | `td restore td-a1b2` | +| `td task create "title"` | Create a task. Shorthand for `td add --type task`. | `td task create "Update docs"` | +| `td task list` | List tasks. Shorthand for `td list --type task`. | `td task list` | +| `td epic create "title"` | Create an epic. Shorthand for `td add --type epic`. | `td epic create "Docs backlog"` | +| `td epic list` | List epics. Shorthand for `td list --type epic`. | `td epic list` | ## 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. 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 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 | - -## 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 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`. - -**List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--due-soon` +| Command | Description | Example | +|---------|-------------|---------| +| `td start ` | Begin work and record the current session as implementer. Alias: `begin`. | `td start td-a1b2` | +| `td unstart ` | Revert in-progress issues to open and clear implementer session. Alias: `stop`. | `td unstart td-a1b2` | +| `td log [id] "message" [flags]` | Log progress on an issue or the current focus. Common flags: `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result`. | `td log td-a1b2 --decision "Use SQLite WAL"` | +| `td handoff [message] [flags]` | Capture structured working state. Common flags: `--done`, `--remaining`, `--decision`, `--uncertain`. | `td handoff td-a1b2 --done "Parser complete" --remaining "Tests"` | +| `td review ` | Submit issues for independent review. Aliases: `submit`, `finish`. | `td review td-a1b2` | +| `td reviewable [--include-approved]` | Show issues the current session can review; include recorded approvals that can be closed with `--include-approved`. | `td reviewable --include-approved` | +| `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 approve td-a1b2 --record-only --reason "Diff and tests reviewed"` | +| `td reject --reason "..."` | Reject reviewed issues back to open and supersede active approval reviews. | `td reject td-a1b2 --reason "Missing regression test"` | +| `td close ` | Admin close for duplicates, won't-fix, and cleanup. Aliases: `done`, `complete`. Use `td approve` for reviewed work. | `td close td-a1b2 --reason "Duplicate"` | +| `td block ` | Mark issues blocked. | `td block td-a1b2` | +| `td unblock ` | Return blocked issues to open. | `td unblock td-a1b2` | +| `td reopen ` | Reopen closed issues. | `td reopen td-a1b2` | +| `td comment "text"` | Add a comment. Alias for `td comments add`. | `td comment td-a1b2 "Follow up with reviewer"` | +| `td comments ` | List comments for an issue. | `td comments td-a1b2` | +| `td comments add "text"` | Add a comment through the comments command group. | `td comments add td-a1b2 "Needs screenshots"` | + +## Deferral And Due Dates + +| Command | Description | Example | +|---------|-------------|---------| +| `td defer ` | Hide an issue until a future date. | `td defer td-a1b2 +7d` | +| `td defer --clear` | Remove deferral. | `td defer td-a1b2 --clear` | +| `td due ` | Set a due date. | `td due td-a1b2 next-week` | +| `td due --clear` | Remove due date. | `td due td-a1b2 --clear` | + +Date formats include `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, and `2026-03-15`. ## Review Flag Details @@ -56,14 +72,14 @@ The `--defer` and `--due` flags are also available on `td create` and `td update | Invocation | Effect | |------------|--------| -| `td approve ` | Direct reviewer-close: caller must be an eligible reviewer with no active approval recorded | -| `td approve --record-only --reason "..."` | Record an approval review without closing. Caller must be an eligible reviewer | -| `td approve --record-only --decision changes_requested --reason "..."` | Record a non-approving review | -| `td approve --reason "..."` (with existing approval) | Close using a recorded approval. Any session may close; non-reviewer closes require `--reason` | +| `td approve ` | Direct reviewer close. Caller must be an eligible reviewer with no active approval recorded. | +| `td approve --record-only --reason "..."` | Record an approval without closing. Caller must be an eligible reviewer. | +| `td approve --record-only --decision changes_requested --reason "..."` | Record a non-approving review. | +| `td approve --reason "..."` with an existing approval | Close using a recorded approval. Any session may close; non-reviewer closes require `--reason`. | -`td reviewable --include-approved` surfaces reviewed issues the current session can close — useful for orchestrators that delegated review to a sub-agent. +`td reviewable --include-approved` surfaces reviewed issues the current session can close, which is useful for orchestrators that delegated review to a sub-agent. -Under `strict` and `balanced` modes, `--record-only` and `--decision` are unavailable; `td approve` performs a review-and-close in one step. +Under `strict` and `balanced` modes, `--record-only` and `--decision` are unavailable; `td approve` performs review-and-close in one step. ## Agent-Safe Rich Text Input @@ -77,86 +93,160 @@ td create "Document sync failure modes" \ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - ``` -## Query & 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 blocked` | List blocked issues | -| `td in-review` | List in-review issues | - -## 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 | +## Query And Search + +| Command | Description | Example | +|---------|-------------|---------| +| `td query "expression"` | Search issues with TDQ. | `td query 'status:open priority:P1'` | +| `td search "keyword"` | Full-text search across titles, descriptions, logs, and handoffs. | `td search "snapshot"` | +| `td next` | Show the highest-priority open issue. | `td next` | +| `td ready` | List open issues sorted by priority. | `td ready` | +| `td blocked` | List blocked issues. | `td blocked` | +| `td deleted` | List soft-deleted issues. | `td deleted` | +| `td in-review` | List issues currently in review. Alias: `ir`. | `td in-review` | + +## Dependencies And Trees + +| Command | Description | Example | +|---------|-------------|---------| +| `td dep ` | Show dependencies for an issue. | `td dep td-a1b2` | +| `td dep add ` | Add dependencies. | `td dep add td-a1b2 td-c3d4` | +| `td dep rm ` | Remove a dependency. Alias: `remove`. | `td dep rm td-a1b2 td-c3d4` | +| `td dep --blocking` | Show issues blocked by this issue. | `td dep td-a1b2 --blocking` | +| `td depends-on ` | Show what an issue depends on. Aliases: `deps`, `dependencies`. | `td depends-on td-a1b2` | +| `td blocked-by ` | Show what issues are waiting on this issue. | `td blocked-by td-a1b2` | +| `td critical-path` | Show the issue sequence that unblocks the most work. | `td critical-path` | +| `td tree ` | Visualize parent/child relationships. | `td tree td-a1b2` | +| `td tree add-child ` | Add a child issue to a parent. | `td tree add-child td-a1b2 td-c3d4` | ## Boards -| Command | Description | -|---------|-------------| -| `td board create "name" --query "..."` | Create 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 | - -## Epics & Trees - -| Command | Description | -|---------|-------------| -| `td epic create "title" [flags]` | Create epic | -| `td epic list` | List epics | -| `td tree ` | Show tree | -| `td tree add-child ` | Add child | +| Command | Description | Example | +|---------|-------------|---------| +| `td board list` | List boards. | `td board list` | +| `td board create --query "..."` | Create a query-backed board. | `td board create "Review" --query "status:in_review"` | +| `td board show ` | Show issues in a board. | `td board show Review` | +| `td board edit [flags]` | Edit board name or query. | `td board edit Review --query "status:open"` | +| `td board move ` | Set an issue position. | `td board move Review td-a1b2 1` | +| `td board unposition ` | Remove an explicit board position. | `td board unposition Review td-a1b2` | +| `td board delete ` | Delete a board. | `td board delete Review` | + +## Notes + +See [Notes](./notes.md) for the full notes workflow. + +| Command | Description | Example | +|---------|-------------|---------| +| `td note add [--content "..."]` | Create a freeform note. | `td note add "Architecture decisions" --content "Use WAL"` | +| `td note list [flags]` | List notes. Alias: `ls`. Flags: `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json`, `--output`. | `td note list --search sync` | +| `td note show <id>` | Show note details. | `td note show nt-a1b2c3` | +| `td note edit <id> [flags]` | Edit a note title or content, or open the editor. Flags: `--title`, `--content`. | `td note edit nt-a1b2c3 --title "Sync notes"` | +| `td note delete <id>` | Soft-delete a note. | `td note delete nt-a1b2c3` | +| `td note pin <id>` / `td note unpin <id>` | Pin or unpin a note. | `td note pin nt-a1b2c3` | +| `td note archive <id>` / `td note unarchive <id>` | Archive or unarchive a note. | `td note archive nt-a1b2c3` | ## 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 unfocus` | Clear focus | -| `td whoami` | Show session identity | +| Command | Description | Example | +|---------|-------------|---------| +| `td usage [flags]` | Generate an agent context block. Flags: `--new-session`, `-q`. | `td usage --new-session` | +| `td session [name]` | Name the current session. | `td session "docs backfill"` | +| `td session --new` | Force a new session at context start. Do not use mid-work to bypass review. | `td session --new` | +| `td session list` | List branch and agent-scoped sessions. | `td session list` | +| `td session cleanup` | Remove stale session files. | `td session cleanup` | +| `td status` | Show current session dashboard. Alias: `current`. | `td status` | +| `td focus <id>` | Set the focused issue. | `td focus td-a1b2` | +| `td unfocus` | Clear focus. | `td unfocus` | +| `td resume [id]` | Show context and set focus. | `td resume td-a1b2` | +| `td check-handoff` | Exit non-zero when in-progress work needs handoff. | `td check-handoff` | +| `td whoami` | Show current session identity. | `td whoami` | ## Work Sessions -| 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 | +| Command | Description | Example | +|---------|-------------|---------| +| `td ws start [name]` | Start a named multi-issue work session. | `td ws start "Docs pass"` | +| `td ws tag <ids...>` | Add issues to the work session. By default, open issues are started. | `td ws tag td-a1b2 td-c3d4` | +| `td ws untag <ids...>` | Remove issues from the work session. | `td ws untag td-a1b2` | +| `td ws log "message"` | Log to the work session and all tagged issues. | `td ws log "Updated shared parser"` | +| `td ws current` | Show current work session state. | `td ws current` | +| `td ws handoff` | Generate handoffs for all tagged issues and end the session. | `td ws handoff` | +| `td ws end` | End a work session without handoff. | `td ws end` | +| `td ws list` | List recent work sessions. | `td ws list` | +| `td ws show [session-id]` | Show details for a past work session. | `td ws show ws-a1b2` | ## Files -| Command | Description | -|---------|-------------| -| `td link <id> <files...>` | Link files to issue | -| `td unlink <id> <files...>` | Unlink files | -| `td files <id>` | Show file status | - -## System - -| 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 | +| Command | Description | Example | +|---------|-------------|---------| +| `td link <id> <file-pattern...>` | Link files to an issue. | `td link td-a1b2 cmd/root.go docs/plan.md` | +| `td unlink <id> <file-pattern>` | Remove file associations. | `td unlink td-a1b2 docs/plan.md` | +| `td files <id>` | List linked files and change status. | `td files td-a1b2` | + +## Configuration + +See [Configuration](./configuration.md) and [Directory Associations](./directory-associations.md) for details. + +| Command | Description | Example | +|---------|-------------|---------| +| `td config list` | Print sync config JSON from `~/.config/td/config.json`. | `td config list` | +| `td config get <key>` | Read a sync config value. | `td config get sync.url` | +| `td config set <key> <value>` | Set a sync config value. | `td config set sync.auto.interval 10m` | +| `td config associate [dir] <target>` | Associate a directory with a canonical td project. | `td config associate ../feature-worktree .` | +| `td config associations` | List directory associations. Alias: `assoc`. | `td config assoc` | +| `td config dissociate [dir]` | Remove a directory association. | `td config dissociate ../feature-worktree` | +| `td feature list` | List known boolean feature flags and resolved state. | `td feature list` | +| `td feature get <name>` | Show one boolean feature state. | `td feature get sync_autosync` | +| `td feature set <name> <true\|false>` | Set a boolean feature override. | `td feature set sync_autosync false` | +| `td feature unset <name>` | Remove a boolean feature override. | `td feature unset sync_autosync` | + +## Sync And Auth + +See [Sync CLI](./sync-cli.md) for the operational sync flow. + +If sync commands are hidden in your build, run td with `TD_FEATURE_SYNC_CLI=true` so the process registers `td auth`, `td config`, `td sync`, and `td sync-project`. + +| Command | Description | Example | +|---------|-------------|---------| +| `td auth login` | Log in to the configured sync server. | `td auth login` | +| `td auth status` | Show stored authentication status. | `td auth status` | +| `td auth logout` | Clear stored sync credentials. | `td auth logout` | +| `td sync init` | Interactive sync setup for server, auth, and project link. | `td sync init` | +| `td sync [flags]` | Push and pull sync events. Flags: `--status`, `--push`, `--pull`. | `td sync --status` | +| `td sync tail [flags]` | Show recent sync activity. Flags: `-f`, `--follow`, `-n`, `--lines`. | `td sync tail -f` | +| `td sync conflicts [flags]` | Show recent conflicts. Flags: `--since`, `--limit`. | `td sync conflicts --since 24h` | +| `td sync-project create <name>` | Create a remote project and try to link the local database. | `td sync-project create "Docs project"` | +| `td sync-project link <project-id>` | Link local project to a remote project. Flag: `--force`. | `td sync-project link prj_abc123` | +| `td sync-project unlink` | Unlink local project from remote sync. | `td sync-project unlink` | +| `td sync-project list` | List remote projects. | `td sync-project list` | +| `td sync-project join [name-or-id]` | Join a project by name or ID. | `td sync-project join "Docs project"` | +| `td sync-project members` | List project members. | `td sync-project members` | +| `td sync-project invite <email> [role]` | Invite a member. Roles: `owner`, `writer`, `reader`. | `td sync-project invite dev@example.com writer` | +| `td sync-project role <user-id> <role>` | Change a member role. | `td sync-project role usr_abc reader` | +| `td sync-project kick <user-id>` | Remove a member. | `td sync-project kick usr_abc` | +| `td doctor` | Run sync setup diagnostics. | `td doctor` | + +## System And Diagnostics + +| Command | Description | Example | +|---------|-------------|---------| +| `td init` | Initialize `.todos` for a project. | `td init` | +| `td monitor` | Launch the live TUI dashboard. | `td monitor` | +| `td serve [flags]` | Start the local HTTP API server. Common flags: `--port`, `--addr`, `--token`, `--cors`, `--interval`. | `td serve --port 8080` | +| `td undo` | Undo the last reversible action in this session. | `td undo` | +| `td last [-n <count>]` | Show the last recorded actions. | `td last -n 5` | +| `td version` | Show version and check for updates. | `td version` | +| `td info` | Show database statistics and project overview. | `td info --json` | +| `td stats` | Unified statistics command. | `td stats` | +| `td stats analytics` | Show local CLI usage analytics. Alias: `td stats usage`. | `td stats analytics` | +| `td stats errors` | Show failed td command attempts. Alias: `td errors`. | `td stats errors` | +| `td stats security` | Show review/close exception audit log. Alias: `td security`. | `td stats security` | +| `td errors` | Show failed td command attempts. | `td errors --limit 20` | +| `td security` | Show review/close exception audit log. | `td security` | +| `td debug-stats` | Output runtime memory and goroutine stats as JSON. | `td debug-stats` | +| `td export` | Export the database. | `td export > td-export.json` | +| `td import <file>` | Import issues. | `td import td-export.json` | +| `td upgrade` | Run pending database migrations. | `td upgrade` | +| `td workflow` | Show the issue status workflow. | `td workflow` | +| `td completion <shell>` | Generate shell completion. | `td completion zsh` | +| `td help [command]` | Show command help. | `td help sync` | diff --git a/website/docs/configuration.md b/website/docs/configuration.md new file mode 100644 index 00000000..6cea0462 --- /dev/null +++ b/website/docs/configuration.md @@ -0,0 +1,124 @@ +--- +sidebar_position: 4 +--- + +# Configuration + +td has two user-facing configuration surfaces: + +- `td config` manages sync settings stored in `~/.config/td/config.json`. +- `td feature` manages project-local boolean feature flags. String-valued settings such as `review_policy_mode` are stored in `.todos/config.json`. + +Some sync commands are rollout-gated. If `td auth`, `td config`, or `td sync` is unavailable in your install, enable the process-level CLI surface in the shell that runs td: + +```bash +export TD_FEATURE_SYNC_CLI=true +``` + +## Sync Config + +Inspect current sync configuration: + +```bash +td config list +td config get sync.url +td config get sync.auto.interval +``` + +Set supported keys with `td config set <key> <value>`: + +```bash +td config set sync.url http://localhost:8080 +td config set sync.auto.enabled false +td config set sync.auto.interval 10m +td config set sync.snapshot_threshold 250 +``` + +Supported keys: + +| Key | Value | Notes | +|-----|-------|-------| +| `sync.url` | URL | Sync server base URL. | +| `sync.enabled` | boolean | Stored sync preference for compatibility; command availability is controlled by `TD_FEATURE_SYNC_CLI`. | +| `sync.auto.enabled` | boolean | Enables or disables autosync. | +| `sync.auto.debounce` | duration | Debounce after local mutations, such as `3s`. | +| `sync.auto.interval` | duration | Periodic autosync interval, such as `5m`. | +| `sync.auto.pull` | boolean | Include pull during autosync. | +| `sync.auto.on_start` | boolean | Sync when td starts. | +| `sync.snapshot_threshold` | integer | Minimum server event count before snapshot bootstrap is considered. | + +`td config` does not currently have an `unset` subcommand. To return optional sync settings to their built-in defaults, remove the key from `~/.config/td/config.json` or set the default-equivalent value explicitly. + +## Environment Overrides + +Environment variables are useful for one-off commands and CI jobs: + +```bash +TD_SYNC_URL=http://localhost:8080 td auth status +TD_AUTH_KEY=td_api_key_xxx td sync --status +TD_SYNC_AUTO=false td list +TD_SYNC_SNAPSHOT_THRESHOLD=0 td sync +``` + +Unset shell overrides with your shell's normal syntax: + +```bash +unset TD_SYNC_URL +unset TD_AUTH_KEY +``` + +## Feature Flags + +List feature flags and their resolved source: + +```bash +td feature list +td feature get sync_autosync +``` + +Set and unset project-local overrides: + +```bash +td feature set sync_autosync false +td feature unset sync_autosync +``` + +Known boolean flags include: + +| Flag | Purpose | +|------|---------| +| `sync_cli` | Records project opt-in for the sync CLI rollout. Hidden command registration is process-level; use `TD_FEATURE_SYNC_CLI=true` when the commands are absent. | +| `sync_autosync` | Enables background autosync hooks. | +| `sync_monitor_prompt` | Enables monitor sync setup prompts. | +| `sync_notes` | Enables notes entity sync. | +| `balanced_review_policy` | Deprecated compatibility flag; prefer `review_policy_mode=balanced`. | + +## Review Policy Mode + +`review_policy_mode` selects review behavior: + +| Mode | Behavior | +|------|----------| +| `delegated` | Default for new installs. Review must be independent; any session may close after an approval is recorded. | +| `strict` | The reviewer must have no prior involvement. | +| `balanced` | Legacy mode with a creator-approval exception when a reason is supplied. | + +Use a one-off environment override when testing policy behavior: + +```bash +TD_FEATURE_REVIEW_POLICY_MODE=strict td approve td-a1b2 +``` + +For a persistent project setting, store `review_policy_mode` in `.todos/config.json` under `feature_string_flags`: + +```json +{ + "feature_string_flags": { + "review_policy_mode": "delegated" + } +} +``` + +Remove the key to return to the built-in default. The current `td feature` command manages boolean feature flags; it does not set or unset string-valued features. + +Prefer `review_policy_mode` over the deprecated `balanced_review_policy` flag. diff --git a/website/docs/directory-associations.md b/website/docs/directory-associations.md new file mode 100644 index 00000000..96c40d1d --- /dev/null +++ b/website/docs/directory-associations.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 9 +--- + +# Directory Associations + +Directory associations let td treat one directory as part of another td project. This is useful for sibling worktrees, nested checkouts, generated sidecar repos, or tools that run outside the directory containing `.todos`. + +Associations are stored in `~/.config/td/associations.json`. + +## Link The Current Directory + +From the directory you want to associate: + +```bash +cd /Users/alex/code/project-worktree +td config associate /Users/alex/code/project +``` + +With one argument, `td config associate` uses the current directory as the source and the argument as the target td project. + +## Link A Specific Directory + +```bash +td config associate /Users/alex/code/project-feature /Users/alex/code/project +``` + +After this, td commands run from `/Users/alex/code/project-feature` resolve to the canonical td project at `/Users/alex/code/project`. + +## List Associations + +```bash +td config associations +td config assoc +``` + +`assoc` is an alias for `associations`. + +## Remove An Association + +```bash +td config dissociate +td config dissociate /Users/alex/code/project-feature +``` + +With no argument, `td config dissociate` removes the association for the current directory. + +## When To Use Associations + +Use associations when multiple directories should share one task database: + +- A feature worktree should use the main repo's `.todos` database. +- A nested app directory should resolve to the parent project. +- A generated or temporary checkout should report work against the canonical project. + +Do not use associations to merge unrelated projects. Each real project should keep its own `.todos` database unless the directories are intentionally part of the same work stream. diff --git a/website/docs/intro.md b/website/docs/intro.md index 2201fe12..b0cc74f2 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -94,4 +94,6 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI. - [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth - [Boards](./boards.md) -- Visual overview of issue status across your project +- [Notes](./notes.md) -- Freeform project memory for durable context that is not an issue - [Query Language](./query-language.md) -- Filter and search issues with structured queries +- [Command Reference](./command-reference.md) -- Complete CLI surface, including sync, config, and diagnostic commands diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 00000000..eabc50af --- /dev/null +++ b/website/docs/notes.md @@ -0,0 +1,77 @@ +--- +sidebar_position: 8 +--- + +# Notes + +`td note` stores freeform project memory that is useful across sessions but does not need an issue lifecycle. Use notes for standing context, decision records, operating reminders, and background material that agents should be able to find later. + +Use issues when work needs status, ownership, review, dependencies, or a handoff. Use notes when the information is durable context rather than a task to complete. + +## Create Notes + +```bash +td note add "Architecture decisions" --content "Use SQLite WAL for local writes." +td note add "Research links" +``` + +If `--content` is omitted, td opens your editor for the note body. + +## Find Notes + +```bash +td note list +td note list --search "sync" +td note list --pinned +td note list --archived +td note list --all +td note list --json +``` + +By default, `td note list` shows non-archived notes. Use `--all` to include archived notes or `--archived` to show only archived notes. + +## Read And Edit + +```bash +td note show nt-a1b2c3 +td note edit nt-a1b2c3 --title "Sync setup notes" +td note edit nt-a1b2c3 --content "Updated operating notes." +td note edit nt-a1b2c3 +``` + +Running `td note edit <id>` without `--title` or `--content` opens the note in your editor. + +## Pinning + +Pinned notes stay easy to discover for agents and operators. + +```bash +td note pin nt-a1b2c3 +td note list --pinned +td note unpin nt-a1b2c3 +``` + +Pin notes that should remain visible during routine orientation, such as project conventions, local setup warnings, or active architectural decisions. + +## Archive And Delete + +Archive notes that should remain searchable but no longer belong in the default list. + +```bash +td note archive nt-a1b2c3 +td note unarchive nt-a1b2c3 +td note delete nt-a1b2c3 +``` + +`td note delete` soft-deletes the note. Prefer archive for old-but-useful context; delete for duplicates, mistakes, or content that should no longer be part of project memory. + +## Agent Guidance + +Agents should use notes for information that helps future sessions but does not need review: + +- Stable project facts: repository layout, local services, or deployment caveats. +- Decisions that explain why a path was chosen. +- Research summaries that may inform later issues. +- Operator reminders that should survive context windows. + +Do not use notes as a substitute for `td log`, `td handoff`, or `td review`. Progress on a specific issue belongs on that issue so reviewers and future implementers can see the full chain of work. diff --git a/website/docs/sync-cli.md b/website/docs/sync-cli.md new file mode 100644 index 00000000..4a746c92 --- /dev/null +++ b/website/docs/sync-cli.md @@ -0,0 +1,132 @@ +--- +sidebar_position: 11 +--- + +# Sync CLI + +td sync connects a local `.todos` database to a remote sync project. This page covers the user-facing CLI flow. For server endpoints and integration details, see the [HTTP API docs](./http-api/overview.md). + +## Enable The Sync Commands + +Some builds hide sync commands unless the process-level feature flag is enabled. Enable it in the shell that runs td: + +```bash +export TD_FEATURE_SYNC_CLI=true +``` + +Then confirm the commands are available: + +```bash +td auth status +td sync --help +``` + +## Configure The Server + +Set the server URL explicitly instead of relying on private defaults: + +```bash +td config set sync.url http://localhost:8080 +td config get sync.url +``` + +For one command, use an environment override: + +```bash +TD_SYNC_URL=http://localhost:8080 td auth status +``` + +## Authenticate + +```bash +td auth login +td auth status +td auth logout +``` + +`td auth login` starts a device login flow. It prompts for an email address, prints a verification URL and code, then stores credentials in `~/.config/td/auth.json` after the server completes the login. + +For automation, an API key can be supplied with `TD_AUTH_KEY`. + +## Link A Project + +Create a remote project and link the current local project: + +```bash +td sync-project create "Website rebuild" +``` + +Or link to an existing project: + +```bash +td sync-project list +td sync-project link prj_abc123 +td sync-project join "Website rebuild" +``` + +Useful project commands: + +| Command | Purpose | +|---------|---------| +| `td sync-project create <name>` | Create a remote project and try to link the current local database. | +| `td sync-project link <project-id>` | Link the current local database to an existing remote project. | +| `td sync-project unlink` | Remove the local link. | +| `td sync-project list` | List remote projects visible to the authenticated user. | +| `td sync-project members` | List members of the linked project. | +| `td sync-project invite <email> [role]` | Invite a user as `owner`, `writer`, or `reader`. | +| `td sync-project role <user-id> <role>` | Change a member role. | +| `td sync-project kick <user-id>` | Remove a member. | + +## Guided Setup + +`td sync init` walks through server URL, authentication, and project linking: + +```bash +td sync init +``` + +Run `td auth login` first if the setup reports that you are not authenticated. + +## Push, Pull, And Status + +```bash +td sync +td sync --status +td sync --push +td sync --pull +``` + +`td sync` pushes local action-log events and pulls remote events. `--status` prints the linked project ID, local push/pull positions, pending local events, and server event state. + +## Activity And Conflicts + +```bash +td sync tail +td sync tail -f +td sync tail -n 50 +td sync conflicts +td sync conflicts --since 24h --limit 50 +``` + +Use `td sync tail` when checking whether sync is moving. Use `td sync conflicts` when a sync run reports conflicting changes. + +## Diagnostics + +```bash +td doctor +``` + +`td doctor` runs read-only checks for sync setup. It is the first command to run when authentication, project linking, or sync state does not look right. + +## Minimal Setup Checklist + +```bash +export TD_FEATURE_SYNC_CLI=true +td config set sync.url http://localhost:8080 +td auth login +td sync-project create "My project" +td sync --status +td sync +``` + +Keep sync settings explicit in shared setup docs so agents and operators know which server a project is meant to use. diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f856..0c822ace 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,6 +13,8 @@ const sidebars = { 'work-sessions', 'deferral', 'file-tracking', + 'notes', + 'directory-associations', ], }, { @@ -22,6 +24,7 @@ const sidebars = { 'monitor', 'kanban', 'ai-integration', + 'sync-cli', ], }, { @@ -38,6 +41,7 @@ const sidebars = { label: 'Reference', items: [ 'command-reference', + 'configuration', 'analytics', ], },