diff --git a/README.md b/README.md index 684416ad..3edb82a4 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,13 @@ 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) +- [Sync and Collaboration](https://marcus.github.io/td/docs/sync-collaboration) - [Command Reference](https://marcus.github.io/td/docs/command-reference) ## Design Philosophy - **Minimal** — Does one thing. Not a project management suite. -- **Local** — SQLite in `.todos/`. No server, no sync, no account. +- **Local-first** — SQLite in `.todos/` by default, with optional sync when teams need collaboration. - **Portable** — Works with any AI tool that can run shell commands. - **Opinionated** — Enforces handoffs. That's the point. diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 28e9da1c..e3d803b7 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -4,144 +4,239 @@ 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 canonical help text and the latest flag list. All commands accept the global `--work-dir` flag to resolve a td project from another 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" [flags]` | Create an issue. Aliases: `add`, `new`. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` | +| `td task create "title"` | Convenience command for creating a task | +| `td task list` | List task-type issues | +| `td list [flags]` | List issues. Alias: `ls`. Common filters: `--status`, `--type`, `--priority`, `--epic`, `--all`, `--deferred`, `--surfacing`, `--overdue`, `--due-soon`, `--json` | +| `td show ` | Display full details for one or more issues. Aliases: `context`, `view`, `get` | +| `td update [flags]` | Update fields. Alias: `edit`. Common flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--defer`, `--due` | +| `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 | - -## Deferral & Due Dates +| `td start ` | Begin work. Alias: `begin` | +| `td unstart ` | Revert in-progress issues to open. Alias: `stop` | +| `td log [id] "message"` | Append a log entry to the current or specified issue. Supports typed logs such as `--decision`, `--blocker`, `--hypothesis`, `--tried`, and `--result` | +| `td handoff [message] [flags]` | Capture structured working state. Common flags: `--done`, `--remaining`, `--decision`, `--uncertain` | +| `td review ` | Submit issues for review. Aliases: `submit`, `finish` | +| `td reviewable [--include-approved]` | Show issues the current session can review; `--include-approved` also shows reviewed issues this session 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 issues back to open and supersede active approval reviews | +| `td block ` | Mark issues blocked | +| `td unblock ` | Move blocked issues back to open | +| `td close ` | Admin close without review. Aliases: `done`, `complete`. Use `td approve` for reviewed work | +| `td reopen ` | Reopen closed issues | +| `td comment "text"` | Add a comment. Alias for `td comments add` | +| `td comments ` | List comments for an issue | +| `td comments add "text"` | Add a comment to an issue | + +## Deferral And 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 | +| `td defer ` | Defer an issue until a future date | +| `td defer --clear` | Remove deferral and make the issue actionable | +| `td due ` | Set a due date | +| `td due --clear` | Remove a due date | -Date formats: `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, `2026-03-15` +Date formats include `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, and `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` +## Review Flag Details -## Agent-Safe Rich Text Input +`td approve` operates in three modes under `review_policy_mode=delegated`: -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. +| 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 an existing approval | Close using a recorded approval. Any session may close; non-reviewer closes require `--reason` | -```bash -td create "Document sync failure modes" \ - --description-file docs/issue-description.md \ - --acceptance-file docs/issue-acceptance.md +`td reviewable --include-approved` surfaces reviewed issues the current session can close. This is useful for orchestrators that delegate review to another session. -cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - -``` +Under `strict` and `balanced` modes, `--record-only` and `--decision` are unavailable; `td approve` performs a review-and-close in one step. -## Query & Search +## Query And Search | Command | Description | |---------|-------------| -| `td query "expression"` | TDQ query | -| `td search "keyword"` | Full-text search | -| `td next` | Highest-priority open issue | -| `td ready` | Open issues by priority | +| `td query "expression"` | Search with the TDQ query language | +| `td search "keyword"` | Full-text search across issues | +| `td next` | Show the highest-priority open issue | +| `td ready` | List open issues sorted by priority | | `td blocked` | List blocked issues | -| `td in-review` | List in-review issues | +| `td in-review` | List issues currently in review. Alias: `ir` | ## Dependencies | Command | Description | |---------|-------------| -| `td dep add ` | Add dependency | -| `td dep rm ` | Remove dependency | +| `td dep ` | Add a dependency | +| `td dep add ` | Add one or more dependencies | +| `td dep rm ` | Remove a dependency. Alias: `remove` | | `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 --blocking` | Show what depends on the issue | +| `td depends-on ` | Show what the issue depends on. Aliases: `deps`, `dependencies` | +| `td blocked-by ` | Show issues waiting on this issue | +| `td critical-path` | Show the sequence that unblocks the most work | ## Boards | Command | Description | |---------|-------------| -| `td board create "name" --query "..."` | Create board | +| `td board create "name" --query "..."` | Create a 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 board issues | +| `td board move ` | Set an issue position | +| `td board unposition ` | Remove an explicit issue position | +| `td board edit [flags]` | Edit board name or query | +| `td board delete ` | Delete a board | -## Epics & Trees +## Epics And Trees | Command | Description | |---------|-------------| -| `td epic create "title" [flags]` | Create epic | +| `td epic create "title" [flags]` | Create an epic | | `td epic list` | List epics | -| `td tree ` | Show tree | -| `td tree add-child ` | Add child | +| `td tree ` | Visualize parent/child relationships | +| `td tree add-child ` | Add a child 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. Alias: `ls`. Flags: `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--output`, `--json` | +| `td note show [--json]` | 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 ` | Unarchive a note | + +See [Notes](./notes.md) for examples and guidance on when to use notes instead of issue comments. ## 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 usage [flags]` | Generate an agent context block. Flags: `--new-session`, `-q` | +| `td session [name]` | Name the current session | +| `td session --new [name]` | Force a new session at context start. Do not use mid-work | +| `td session list` | List branch and agent-scoped sessions | +| `td session cleanup` | Remove stale session files | +| `td status` | Show dashboard state. Alias: `current` | | `td focus ` | Set focus | | `td unfocus` | Clear focus | -| `td whoami` | Show session identity | +| `td resume ` | Show context and set focus | +| `td check-handoff [flags]` | Return an error if the current session has in-progress work needing handoff. Flags: `--json`, `--quiet` | +| `td whoami` | Show current session identity | ## Work Sessions | Command | Description | |---------|-------------| -| `td ws start "name"` | Start work session | -| `td ws tag ` | Tag issues | -| `td ws log "message"` | Log to all tagged | -| `td ws current` | Show session state | -| `td ws handoff` | Handoff all, end session | +| `td ws start [name]` | Start a named work session. Alias group: `worksession` | +| `td ws tag ` | Associate issues with the current work session and auto-start open issues | +| `td ws untag ` | Remove issues from the work session | +| `td ws log "message"` | Log to the work session | +| `td ws current` | Show current work session state | +| `td ws handoff` | Generate handoffs for tagged issues and end the work session | +| `td ws end` | End the work session without handoff | +| `td ws list` | List recent work sessions | +| `td ws show ` | Show details for a past work session | ## Files | Command | Description | |---------|-------------| -| `td link ` | Link files to issue | -| `td unlink ` | Unlink files | -| `td files ` | Show file status | +| `td link ` | Link files to an issue | +| `td unlink ` | Remove file associations | +| `td files ` | List linked files with change status | + +## Sync And Collaboration -## System +| Command | Description | +|---------|-------------| +| `td auth login` | Log in to the sync server | +| `td auth logout` | Log out from the sync server | +| `td auth status` | Show authentication status | +| `td sync init` | Run interactive guided sync setup | +| `td sync [--push\|--pull\|--status]` | Sync local data with the remote server | +| `td sync tail [-f] [-n N]` | Show recent sync activity | +| `td sync conflicts [flags]` | Show recent sync conflicts. Flags: `--limit`, `--since` | +| `td sync-project create [--description "..."]` | Create a remote sync project | +| `td sync-project link [--force]` | Link the local project to a remote project | +| `td sync-project join [name-or-id]` | Join a remote project by name or ID | +| `td sync-project list` | List remote projects | +| `td sync-project members` | List project members | +| `td sync-project invite [role]` | Invite a user | +| `td sync-project kick ` | Remove a member | +| `td sync-project role ` | Change a member role | +| `td sync-project unlink [--force]` | Unlink the local project from remote sync | + +See [Sync And Collaboration](./sync-collaboration.md) for the normal setup flow. + +## System And Diagnostics | Command | Description | |---------|-------------| -| `td init` | Initialize project | +| `td init` | Initialize a td 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 config set ` | Set a config value | +| `td config get ` | Get a config value | +| `td config list` | List config values | +| `td config associate [dir] ` | Associate a directory with a td project path | +| `td config associations` | List directory associations. Alias: `assoc` | +| `td config dissociate [dir]` | Remove a directory association | +| `td feature list` | List known feature flags and resolved state | +| `td feature get ` | Show a feature flag state | +| `td feature set ` | Set a project-local feature flag override | +| `td feature unset ` | Remove a feature flag override | +| `td doctor` | Run sync setup diagnostics | +| `td doctor fk` | Report orphan-row counts for foreign-key relations | +| `td errors [flags]` | View failed td command attempts. Flags: `--limit`, `--since`, `--session`, `--count`, `--json`, `--clear` | +| `td security [flags]` | View review/close exception audit log. Flags: `--json`, `--clear` | +| `td stats analytics [flags]` | View command usage analytics. Alias: `td stats usage` | +| `td stats security` | Alias for `td security` | +| `td stats errors` | Alias for `td errors` | +| `td info [--json]` | Show database statistics and project overview | +| `td export [flags]` | Export database. Flags: `--format`, `--output`, `--all`, `--render-markdown` | +| `td import [file] [flags]` | Import issues. Flags: `--format`, `--dry-run`, `--force` | +| `td undo` | Undo the last action | +| `td undo last` | Show the last action | +| `td upgrade` | Run database migrations | +| `td version [flags]` | Show version and check for updates. Flags: `--short`, `--check` | +| `td workflow [flags]` | Show issue status workflow. Flags: `--dot`, `--mermaid` | +| `td serve` | Start the td HTTP API server | +| `td debug-stats` | Output runtime memory and goroutine statistics as JSON | +| `td completion ` | Generate shell completion | + +See [System And Diagnostics](./system-diagnostics.md) for operational guidance. + +## 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. + +```bash +td create "Document sync failure modes" \ + --description-file docs/issue-description.md \ + --acceptance-file docs/issue-acceptance.md + +cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - +``` diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 00000000..63ff13aa --- /dev/null +++ b/website/docs/notes.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 9 +--- + +# Notes + +Notes are freeform project memory. Use them for durable context that does not belong to one issue: architecture decisions, recurring commands, release observations, meeting notes, or research that several issues may need. + +Issue comments stay attached to a specific issue timeline. Notes stand on their own, can be pinned, archived, searched, and shown as JSON for scripts. + +## Create Notes + +Create a note with inline content: + +```bash +td note add "Sync rollout checklist" --content "Verify auth, link project, run td sync --status." +``` + +If `--content` is omitted, `td` opens your editor: + +```bash +td note add "API review notes" +``` + +## List And Filter + +By default, `td note list` shows non-archived notes, sorted with pinned notes first. + +```bash +td note list +td note list --pinned +td note list --archived +td note list --all +td note list --search "sync" +td note list --limit 10 +``` + +The list command supports table and JSON output: + +```bash +td note list --output json +td note list --json +``` + +## Show And Edit + +Show one note: + +```bash +td note show nt-abc123 +td note show nt-abc123 --json +``` + +Edit title, content, or both: + +```bash +td note edit nt-abc123 --title "New title" +td note edit nt-abc123 --content "Updated content" +td note edit nt-abc123 +``` + +When no edit flags are passed, `td` opens your editor. + +## Pin, Archive, And Delete + +Pinned notes sort ahead of normal notes: + +```bash +td note pin nt-abc123 +td note unpin nt-abc123 +``` + +Archive notes when they should stay searchable but leave the default list: + +```bash +td note archive nt-abc123 +td note unarchive nt-abc123 +``` + +Delete performs a soft delete: + +```bash +td note delete nt-abc123 +``` + +## Notes Vs Comments + +Use a note when the information should outlive a single issue or apply across issues. + +Use a comment when the information explains one issue's discussion, review, or decision history: + +```bash +td comment td-a1b2 "Reviewer asked for an integration test." +td comments td-a1b2 +``` diff --git a/website/docs/sync-collaboration.md b/website/docs/sync-collaboration.md new file mode 100644 index 00000000..ccd35dd8 --- /dev/null +++ b/website/docs/sync-collaboration.md @@ -0,0 +1,88 @@ +--- +sidebar_position: 10 +--- + +# Sync And Collaboration + +Sync connects a local `.todos` database to a remote td project so teammates can share issues, handoffs, comments, notes, and workflow history. + +Most collaborators follow this path: + +```bash +td auth login +td sync-project join +td sync --status +td sync +``` + +Project owners usually create or link the shared project first: + +```bash +td auth login +td sync-project create "Product CLI" +td sync-project link +td sync-project invite teammate@example.com editor +td sync +``` + +## Authentication + +| Command | Use | +|---------|-----| +| `td auth login` | Authenticate this machine with the sync server | +| `td auth status` | Confirm whether credentials are available | +| `td auth logout` | Remove local sync credentials | + +Run `td auth status` before debugging project membership. A valid login is required before project and sync commands can call the server. + +## Project Setup + +| Command | Use | +|---------|-----| +| `td sync init` | Guided setup for authentication and project linking | +| `td sync-project create ` | Create a remote project | +| `td sync-project link ` | Attach the current local project to a remote project | +| `td sync-project join [name-or-id]` | Join and link to a remote project | +| `td sync-project list` | Show remote projects available to you | +| `td sync-project unlink` | Disconnect the local project from remote sync | + +Use `--force` with `link` or `unlink` only when you intentionally want to skip confirmation prompts. + +## Member Management + +| Command | Use | +|---------|-----| +| `td sync-project members` | List members for the linked project | +| `td sync-project invite [role]` | Invite a collaborator | +| `td sync-project kick ` | Remove a collaborator | +| `td sync-project role ` | Change a collaborator role | + +Roles are project policy. Use the role names configured by your td server. + +## Sync Operations + +| Command | Use | +|---------|-----| +| `td sync` | Push local changes and pull remote changes | +| `td sync --push` | Push local changes only | +| `td sync --pull` | Pull remote changes only | +| `td sync --status` | Show sync state without changing data | +| `td sync tail` | Show recent sync activity | +| `td sync tail -f` | Follow sync activity in real time | +| `td sync conflicts` | Show recent sync conflicts | + +When a new collaborator joins, they should run `td sync --status` first to confirm the link, then `td sync` to pull current project state. + +## Diagnostics + +Run diagnostics when setup or sync behavior looks wrong: + +```bash +td auth status +td sync --status +td doctor +td sync conflicts --since 24h +td sync tail -n 50 +``` + +`td doctor` focuses on sync setup checks. `td sync conflicts` and `td sync tail` help explain what happened after setup succeeded. diff --git a/website/docs/system-diagnostics.md b/website/docs/system-diagnostics.md new file mode 100644 index 00000000..d38eb365 --- /dev/null +++ b/website/docs/system-diagnostics.md @@ -0,0 +1,126 @@ +--- +sidebar_position: 12 +--- + +# System And Diagnostics + +These commands help inspect local state, manage configuration, diagnose sync problems, and support agent workflows. + +## Configuration + +Project configuration is managed through `td config`: + +```bash +td config list +td config get review_policy_mode +td config set review_policy_mode delegated +``` + +Directory associations let a directory resolve to another td project without placing `.td-root` files everywhere: + +```bash +td config associate /path/to/repo /path/to/project +td config associations +td config dissociate /path/to/repo +``` + +## Feature Flags + +Experimental behavior can be inspected and overridden locally: + +```bash +td feature list +td feature get review_policy_mode +td feature set review_policy_mode delegated +td feature unset review_policy_mode +``` + +Use feature flags sparingly in shared projects. Record any workflow-affecting change in a note or issue comment so other sessions understand the environment. + +## Health Checks + +Run `doctor` for sync setup diagnostics: + +```bash +td doctor +``` + +For database relation checks: + +```bash +td doctor fk +``` + +For version and migrations: + +```bash +td version +td version --short +td upgrade +``` + +## Logs And Audit Trails + +`td` records command analytics, failed invocations, and workflow exceptions locally. + +```bash +td stats analytics +td errors +td errors --since 24h --limit 50 +td errors --json +td security +td security --json +``` + +`td security` shows review and close exceptions such as creator approval or self-close audit events. The same views are available through `td stats security` and `td stats errors`. + +## Import, Export, And Project Info + +Use export and import for backups, migration, and human-readable snapshots: + +```bash +td export --format json --output issues.json +td export --format md --render-markdown --output issues.md +td import issues.json --dry-run +td import issues.json +``` + +Inspect project state: + +```bash +td info +td info --json +``` + +## Workflow Diagrams + +Show the issue lifecycle in terminal, GraphViz, or Mermaid format: + +```bash +td workflow +td workflow --dot +td workflow --mermaid +``` + +## Agent Handoff Checks + +Agents should run `td check-handoff` before exiting a session or handing control back to a human: + +```bash +td check-handoff +td check-handoff --quiet +td check-handoff --json +``` + +Exit code `0` means no handoff is needed. Exit code `1` means the current session has in-progress work that should be captured with `td handoff` or `td ws handoff`. + +## Undo And Last Action + +When a supported local action was a mistake: + +```bash +td undo last +td undo +``` + +Review the last action before undoing if the session has been busy. diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f856..db56bbed 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,6 +13,7 @@ const sidebars = { 'work-sessions', 'deferral', 'file-tracking', + 'notes', ], }, { @@ -22,6 +23,7 @@ const sidebars = { 'monitor', 'kanban', 'ai-integration', + 'sync-collaboration', ], }, { @@ -38,6 +40,7 @@ const sidebars = { label: 'Reference', items: [ 'command-reference', + 'system-diagnostics', 'analytics', ], },