diff --git a/README.md b/README.md index 684416a..c43ef95 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ cat docs/issue-description.md | td update td-a1b2 --append --description-file - td start ``` -For complete guides, see the [full documentation](https://marcus.github.io/td/docs/intro). +For complete guides, see the [full documentation](https://marcus.github.io/td/docs/intro), including [Notes](https://marcus.github.io/td/docs/notes), [Sync & Collaboration](https://marcus.github.io/td/docs/sync-collaboration), and the [Command Reference](https://marcus.github.io/td/docs/command-reference). ## Claude Code / OpenAI Codex Skill diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 28e9da1..b7a4d8a 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -1,39 +1,50 @@ --- -sidebar_position: 11 +sidebar_position: 13 --- # Command Reference -Complete reference for all `td` commands. +Complete reference for the `td` CLI, including notes, work sessions, diagnostics, and the feature-gated sync workflow. -## Core Commands +> **Note**: `td auth`, `td config`, `td doctor`, `td sync`, and `td sync-project` are registered only when `sync_cli` is enabled for the current process. Use `export TD_ENABLE_FEATURE=sync_cli` in your shell, or prefix one command with `TD_FEATURE_SYNC_CLI=true`. `td feature set sync_cli true` updates project config, but it does not expose these commands by itself. + +## Core Issue 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. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` | +| `td list [flags]` | List issues. Common filters: `--status`, `--type`, `--priority`, `--epic`, `--all`, `--deferred`, `--surfacing`, `--overdue`, `--due-soon` | +| `td show ` | Display full details for one or more issues | +| `td update [flags]` | Update issue fields, including rich text fields from files or stdin | +| `td delete ` | Soft-delete one or more issues | +| `td restore ` | Restore one or more soft-deleted issues | +| `td deleted` | List soft-deleted issues | +| `td task create "title"` | Create a task shortcut (`--type task`) | +| `td task list` | List task issues only | +| `td epic create "title"` | Create an epic | +| `td epic list` | List epics | ## 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 ` | Move issue to `in_progress` | +| `td unstart ` | Move issue back to `open` | +| `td block ` | Mark one or more issues blocked | +| `td unblock ` | Return blocked issues to `open` | +| `td review ` | Submit one or more issues for review | +| `td approve [--reason "..."]` | Approve and close issues | +| `td reject --reason "..."` | Reject issues back to `open` | +| `td close ` | Close issues directly without review | +| `td reopen ` | Reopen closed issues | +| `td handoff [flags]` | Capture done/remaining/decision/uncertain state before ending a session | +| `td resume [id]` | Show context and set focus | +| `td log "message" [flags]` | Add progress, blocker, decision, hypothesis, tried, or result logs | +| `td comment "text"` | Add a comment shortcut | +| `td comments ` | List comments for an issue | +| `td comments add "text"` | Add a comment via the subcommand form | +| `td workflow` | Print the issue state workflow summary | +| `td check-handoff` | Exit non-zero when the current focus still needs a handoff | ## Deferral & Due Dates @@ -50,18 +61,6 @@ The `--defer` and `--due` flags are also available on `td create` and `td update **List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--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. - -```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 - -``` - ## Query & Search | Command | Description | @@ -77,32 +76,25 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - | Command | Description | |---------|-------------| -| `td dep add ` | Add dependency | +| `td dep add ...` | Add dependencies | | `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 | -## Boards +## Boards, Trees, And Epics | Command | Description | |---------|-------------| | `td board create "name" --query "..."` | Create board | | `td board list` | List boards | -| `td board show ` | Show board | +| `td board show ` | Show board results, optionally filtered by status | | `td board move ` | Position issue | +| `td board unposition ` | Remove a board-specific position override | | `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 | +| `td tree ` | Show the issue tree, with optional `--depth` or `--json` | ## Sessions @@ -111,6 +103,8 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - | `td usage [flags]` | Agent context. Flags: `--new-session`, `-q` | | `td session [name]` | Name session | | `td session --new` | Force new session | +| `td session list` | List branch- and agent-scoped sessions | +| `td session cleanup` | Remove stale session files | | `td status` | Dashboard view | | `td focus ` | Set focus | | `td unfocus` | Clear focus | @@ -122,17 +116,34 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - |---------|-------------| | `td ws start "name"` | Start work session | | `td ws tag ` | Tag issues | +| `td ws tag --no-start` | Tag issues without auto-starting open work | +| `td ws untag ` | Remove issues from the active work session | | `td ws log "message"` | Log to all tagged | | `td ws current` | Show session state | | `td ws handoff` | Handoff all, end session | +| `td ws end` | End the current work session without generating handoffs | +| `td ws list` | List recent work sessions | +| `td ws show ` | Show a past work session | + +## Notes + +| Command | Description | +|---------|-------------| +| `td note add "title"` | Create a freeform note | +| `td note list` | List notes with filters such as `--pinned`, `--archived`, `--all`, `--search`, `--json` | +| `td note show ` | Show a note | +| `td note edit ` | Edit a note title or content | +| `td note pin ` / `td note unpin ` | Pin or unpin a note | +| `td note archive ` / `td note unarchive ` | Archive or restore a note | +| `td note delete ` | Soft-delete a note | ## Files | Command | Description | |---------|-------------| -| `td link ` | Link files to issue | -| `td unlink ` | Unlink files | -| `td files ` | Show file status | +| `td link ` | Link files or globs to an issue | +| `td unlink ` | Remove linked files | +| `td files ` | Show linked files and change status | ## System @@ -140,8 +151,71 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - |---------|-------------| | `td init` | Initialize project | | `td monitor` | Live TUI dashboard | +| `td serve` | Start the td HTTP API server | +| `td info` | Show project overview and database stats | +| `td stats analytics` | Show command usage analytics | +| `td stats errors` / `td errors` | Show failed command attempts | +| `td stats security` / `td security` | Show workflow exception audit events | | `td undo` | Undo last action | +| `td last` | Show the last action performed | | `td version` | Show version | | `td export` | Export database | -| `td import` | Import issues | -| `td stats [subcommand]` | Usage statistics | +| `td import [file]` | Import issues | +| `td upgrade` | Run database migrations | +| `td feature list` | List experimental features and resolved state | +| `td feature get ` | Get one feature flag | +| `td feature set ` | Set a project-level feature override | +| `td feature unset ` | Remove a project-level feature override | +| `td debug-stats` | Print runtime memory and goroutine stats as JSON | + +## Feature-Gated Config Helpers + +The current CLI hides the entire `td config` command family behind `sync_cli`, so these commands use the same env-based enablement as sync. + +| Command | Description | +|---------|-------------| +| `td config set ` | Set a global config value such as `sync.url` or autosync settings | +| `td config get ` | Read one config value | +| `td config list` | Print the global config as JSON | +| `td config associate [dir] ` | Associate a directory with a td project root | +| `td config associations` | List directory-to-project associations | +| `td config dissociate [dir]` | Remove a directory association | + +## Feature-Gated Sync & Collaboration + +These commands are available only when `sync_cli` is enabled through an environment override for the current process. See [Sync & Collaboration](./sync-collaboration.md) for setup and troubleshooting. + +| Command | Description | +|---------|-------------| +| `td auth login` | Authenticate with a sync server | +| `td auth status` | Show current auth status | +| `td auth logout` | Remove local credentials | +| `td doctor` | Run sync diagnostics | +| `td sync init` | Guided sync setup after you have already logged in | +| `td sync` | Push then pull changes | +| `td sync --push` | Push only | +| `td sync --pull` | Pull only | +| `td sync --status` | Show local and server sync state | +| `td sync conflicts` | Show recent overwrite conflicts | +| `td sync tail` | Show recent sync activity, optionally with `-f` | +| `td sync-project create "name"` | Create and link a remote sync project | +| `td sync-project join [name-or-id]` | Join an invited project by picker, name, or ID | +| `td sync-project link ` | Link directly to a known project ID | +| `td sync-project unlink` | Remove the local remote-project link | +| `td sync-project list` | List available remote projects | +| `td sync-project members` | List members on the linked project | +| `td sync-project invite [role]` | Invite a collaborator as `writer`, `reader`, or `owner` | +| `td sync-project role ` | Change a member role | +| `td sync-project kick ` | Remove a member | + +## Agent-Safe Rich Text Input + +Use `--description-file` and `--acceptance-file` for markdown-heavy content so your shell does not mangle code fences, quotes, or blank lines. Pass `-` to read the 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/intro.md b/website/docs/intro.md index 393bad4..3d1339e 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -93,5 +93,9 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI. ## Next Steps - [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth +- [Notes](./notes.md) -- Capture durable context that does not belong to one issue - [Boards](./boards.md) -- Visual overview of issue status across your project +- [Work Sessions](./work-sessions.md) -- Coordinate multi-issue implementation bursts +- [Sync & Collaboration](./sync-collaboration.md) -- Share a project across machines or teammates - [Query Language](./query-language.md) -- Filter and search issues with structured queries +- [Command Reference](./command-reference.md) -- Full CLI surface, including feature-gated commands diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 0000000..1573180 --- /dev/null +++ b/website/docs/notes.md @@ -0,0 +1,113 @@ +--- +sidebar_position: 3 +--- + +# Notes + +Use notes for durable project context that does not belong to a single issue. Notes live next to your `td` data, but they stay outside the issue workflow. + +## When To Use Notes + +Use notes when you want to capture: + +- architecture decisions that span multiple issues +- meeting notes, research, and rough planning +- onboarding context for future agent or human sessions +- checklists or scratchpad content that should not change issue status + +Use issues when the work needs ownership, status, logs, handoffs, review, or acceptance criteria. + +| Use this | When you need | +|----------|---------------| +| `td note` | Durable context, references, brainstorms, or docs-in-progress | +| `td create` / `td task create` | Trackable work with workflow state, logs, handoffs, and review | + +## Create A Note + +Create a note with inline content: + +```bash +td note add "Architecture decisions" --content "Use SQLite locally and sync events remotely." +``` + +If you omit `--content`, `td` opens your `$EDITOR` so you can write longer notes comfortably: + +```bash +td note add "Sprint retro" +``` + +## List And Search Notes + +```bash +td note list +td note list --pinned +td note list --all +td note list --archived +td note list --search "auth" +td note list --json +``` + +By default, `td note list` hides archived notes. Use `--archived` to show only archived notes, or `--all` to include both active and archived notes. + +## Show And Edit Notes + +```bash +td note show nt-abc123 +td note show nt-abc123 --json + +td note edit nt-abc123 --title "Auth architecture" +td note edit nt-abc123 --content "Updated content" +td note edit nt-abc123 +``` + +Running `td note edit ` with no flags opens your editor with the current content loaded. + +## Pin, Archive, And Delete + +Pinned notes stay easy to find, and archived notes stay out of the default listing without being deleted. + +```bash +td note pin nt-abc123 +td note unpin nt-abc123 + +td note archive nt-abc123 +td note unarchive nt-abc123 +``` + +Use `delete` when you want to remove a note entirely: + +```bash +td note delete nt-abc123 +``` + +There is no `td note restore`, so archive is the safer choice when you only want a note out of the default list. + +## Suggested Workflow + +```bash +td note add "Release checklist" +td note pin nt-abc123 +td note list --pinned +td note edit nt-abc123 +td note archive nt-abc123 +``` + +This works well for lightweight project docs, recurring checklists, and context you want available in future agent sessions without opening a new issue. + +## Notes In Shared Projects + +If you are using the sync workflow, notes can sync with the rest of the project data. To keep notes local-only in a shared project, disable note sync for that project: + +```bash +td feature set sync_notes false +``` + +Unlike the `sync_cli` command gate, `sync_notes` is resolved from project config at runtime, so `td feature set` works for this flag. + +Re-enable it later with: + +```bash +td feature set sync_notes true +``` + +For remote setup, see [Sync & Collaboration](./sync-collaboration.md). diff --git a/website/docs/sync-collaboration.md b/website/docs/sync-collaboration.md new file mode 100644 index 0000000..4bce653 --- /dev/null +++ b/website/docs/sync-collaboration.md @@ -0,0 +1,210 @@ +--- +sidebar_position: 9 +--- + +# Sync & Collaboration + +Use sync when you want one local `td` project to stay aligned across machines or teammates. This guide covers command enablement, authentication, project linking, routine sync commands, background sync, and common failure modes. + +## Enable Sync Commands + +The sync surface is feature-gated at command registration time. If `td sync`, `td auth`, `td config`, `td doctor`, or `td sync-project` shows as an unknown command, enable `sync_cli` for the current process before starting `td`. + +For an interactive shell session: + +```bash +export TD_ENABLE_FEATURE=sync_cli +``` + +For a single command: + +```bash +TD_FEATURE_SYNC_CLI=true td sync --help +``` + +Add the export to your shell profile if you use sync regularly. + +> **Important**: `td feature set sync_cli true` writes project config, and `td feature list` may report `sync_cli=on (source=config)`, but that still does not expose the hidden commands. The CLI registers these commands before project config is loaded, so you still need the environment override shown above. + +## Quick Setup + +If you want the shortest path from a fresh machine: + +```bash +export TD_ENABLE_FEATURE=sync_cli +td config set sync.url https://sync.example.com # optional if you are not using localhost:8080 +td auth login +td sync init +td sync +``` + +`td sync init` is a guided setup for server confirmation and project linking. It does **not** perform login for you. If you run it before `td auth login`, it stops and asks you to authenticate first. + +## Manual Setup + +### 1. Configure The Server + +The default server is `http://localhost:8080`. Set a different URL when you are using a hosted or self-hosted sync server: + +```bash +td config set sync.url https://sync.example.com +``` + +Useful config helpers: + +```bash +td config get sync.url +td config list +``` + +### 2. Authenticate + +```bash +td auth login +td auth status +``` + +`td auth login` starts the device login flow. `td auth status` is the fastest way to confirm that the current machine still has a saved credential. + +### 3. Create Or Join A Remote Project + +Project owners usually create a remote project: + +```bash +td sync-project create "team-project" --description "Shared task tracking" +``` + +`create` also links the current local project to the new remote project. + +Teammates usually join an existing project: + +```bash +td sync-project join +td sync-project join "team-project" +td sync-project join "" +``` + +Use `join` when possible. With no argument it opens a numbered picker. With one argument it matches by name first, then by project ID. + +Use `link` when you already know the exact remote project ID or you want a more scriptable flow: + +```bash +td sync-project link +td sync-project unlink +td sync-project list +``` + +### 4. Sync + +```bash +td sync +td sync --push +td sync --pull +td sync --status +``` + +`td sync` pushes local events first, then pulls remote events. `td sync --status` shows both the local sync checkpoint and the current server event counts. + +## Collaboration Commands + +Once a project is linked, owners can invite and manage teammates: + +```bash +td sync-project invite alice@example.com +td sync-project invite bob@example.com reader + +td sync-project members +td sync-project role writer +td sync-project kick +``` + +Roles: + +- `owner`: full access, including invites and role changes +- `writer`: read/write project access +- `reader`: read-only project access + +## Background Sync + +Background sync behavior uses a runtime feature flag plus global config values: + +```bash +td feature set sync_autosync true +td config set sync.auto.enabled true +td config set sync.auto.debounce 5s +td config set sync.auto.interval 5m +td config set sync.auto.pull true +td config set sync.auto.on_start true +``` + +`sync_autosync` is resolved at runtime from project config, so `td feature set sync_autosync true` does take effect. The `sync.auto.*` values live in global config and control whether background hooks run, whether they pull after pushing, and how often they fire. + +Other supported sync config keys: + +- `sync.url` +- `sync.enabled` +- `sync.snapshot_threshold` + +Use `td config get ` to inspect one value, or `td config list` for the full config document. + +## Notes In Shared Projects + +Notes sync by default. To keep notes local in a shared repo, disable note syncing in that project: + +```bash +td feature set sync_notes false +``` + +Unlike `sync_cli`, `sync_notes` is checked at runtime from project config, so this feature flag works without an environment override. + +## Diagnostics And Activity + +Use these commands when setup looks right but behavior does not: + +```bash +td doctor +td sync conflicts +td sync conflicts --since 24h +td sync tail +td sync tail -f +``` + +`td doctor` checks auth config, server reachability, auth validity, local database access, project linkage, and pending local events. `td sync conflicts` shows recent overwrite events. `td sync tail` is useful when you want to watch push and pull activity live. + +## Troubleshooting + +**`unknown command "sync"` or `unknown command "auth"`** + +Enable `sync_cli` with `export TD_ENABLE_FEATURE=sync_cli` or prefix the command with `TD_FEATURE_SYNC_CLI=true`. Project config alone does not expose hidden commands. See [Enable Sync Commands](#enable-sync-commands). + +**`td feature list` says `sync_cli` is on, but commands are still hidden** + +That means the feature is enabled in project config, not for the current process. Add the environment override and rerun the command. + +**`not logged in (run: td auth login)`** + +Your local auth config is missing or expired. Run `td auth login` again, then confirm with `td auth status`. + +**`td sync init` says you are not authenticated** + +That is expected. `td sync init` does not run the login flow for you. Run `td auth login` first, then re-run `td sync init`. + +**`project not linked`** + +Your local project has not been connected to a remote project yet. Run `td sync-project join` or `td sync-project link `. + +**`no projects found` during `td sync-project join`** + +Your account does not currently have any project invites. Ask a project owner to run `td sync-project invite `. + +**`unauthorized` from `td sync --status` or `td doctor`** + +Your API key is no longer valid. Re-run `td auth login`. + +**404s after using `td sync-project link `** + +The local project may be linked to a stale or mistyped ID. Run `td sync-project list` to verify the remote project exists, then use `td sync-project join` when possible. + +**You are not sure whether the server is healthy** + +Run `td doctor` and `td sync --status`. They give better signal than a plain `td sync` run with no pending local events. diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f85..f82ed0d 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -6,6 +6,7 @@ const sidebars = { label: 'Features', items: [ 'core-workflow', + 'notes', 'boards', 'dependencies', 'query-language', @@ -13,6 +14,7 @@ const sidebars = { 'work-sessions', 'deferral', 'file-tracking', + 'sync-collaboration', ], }, {