Skip to content

docs: backfill website docs #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcus wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: backfill website docs #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ cat docs/issue-description.md | td update td-a1b2 --append --description-file -
td start <issue-id>
```

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

Expand Down
176 changes: 125 additions & 51 deletions website/docs/command-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <id>` | Display full issue details |
| `td update <id> [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels` |
| `td delete <id>` | Soft-delete issue |
| `td restore <id>` | 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 <id>` | Display full details for one or more issues |
| `td update <id> [flags]` | Update issue fields, including rich text fields from files or stdin |
| `td delete <id>` | Soft-delete one or more issues |
| `td restore <id>` | 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 <id>` | Begin work (status -> in_progress) |
| `td unstart <id>` | Revert to open |
| `td log "message" [flags]` | Log progress. Flags: `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result` |
| `td handoff <id> [flags]` | Capture state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain` |
| `td review <id>` | Submit for review |
| `td reviewable` | Show reviewable issues |
| `td approve <id> [--reason "..."]` | Approve and close. Reason required for creator-exception approvals |
| `td reject <id> --reason "..."` | Reject back to in_progress |
| `td block <id>` | Mark as blocked |
| `td unblock <id>` | Unblock to open |
| `td close <id>` | Admin close (not for completed work) |
| `td reopen <id>` | Reopen closed issue |
| `td comment <id> "text"` | Add comment |
| `td start <id>` | Move issue to `in_progress` |
| `td unstart <id>` | Move issue back to `open` |
| `td block <id>` | Mark one or more issues blocked |
| `td unblock <id>` | Return blocked issues to `open` |
| `td review <id>` | Submit one or more issues for review |
| `td approve <id> [--reason "..."]` | Approve and close issues |
| `td reject <id> --reason "..."` | Reject issues back to `open` |
| `td close <id>` | Close issues directly without review |
| `td reopen <id>` | Reopen closed issues |
| `td handoff <id> [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 <id> "text"` | Add a comment shortcut |
| `td comments <id>` | List comments for an issue |
| `td comments add <id> "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

Expand All @@ -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 |
Expand All @@ -77,32 +76,25 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -

| Command | Description |
|---------|-------------|
| `td dep add <issue> <depends-on>` | Add dependency |
| `td dep add <issue> <depends-on>...` | Add dependencies |
| `td dep rm <issue> <depends-on>` | Remove dependency |
| `td dep <issue>` | Show dependencies |
| `td dep <issue> --blocking` | Show what it blocks |
| `td blocked-by <issue>` | 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 <board>` | Show board |
| `td board show <board>` | Show board results, optionally filtered by status |
| `td board move <board> <id> <pos>` | Position issue |
| `td board unposition <board> <id>` | Remove a board-specific position override |
| `td board edit <board> [flags]` | Edit board |
| `td board delete <board>` | Delete board |

## Epics & Trees

| Command | Description |
|---------|-------------|
| `td epic create "title" [flags]` | Create epic |
| `td epic list` | List epics |
| `td tree <id>` | Show tree |
| `td tree add-child <parent> <child>` | Add child |
| `td tree <id>` | Show the issue tree, with optional `--depth` or `--json` |

## Sessions

Expand All @@ -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 <id>` | Set focus |
| `td unfocus` | Clear focus |
Expand All @@ -122,26 +116,106 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
|---------|-------------|
| `td ws start "name"` | Start work session |
| `td ws tag <ids...>` | Tag issues |
| `td ws tag <ids...> --no-start` | Tag issues without auto-starting open work |
| `td ws untag <ids...>` | 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 <session-id>` | 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 <id>` | Show a note |
| `td note edit <id>` | Edit a note title or content |
| `td note pin <id>` / `td note unpin <id>` | Pin or unpin a note |
| `td note archive <id>` / `td note unarchive <id>` | Archive or restore a note |
| `td note delete <id>` | Soft-delete a note |

## Files

| Command | Description |
|---------|-------------|
| `td link <id> <files...>` | Link files to issue |
| `td unlink <id> <files...>` | Unlink files |
| `td files <id>` | Show file status |
| `td link <id> <files...>` | Link files or globs to an issue |
| `td unlink <id> <files...>` | Remove linked files |
| `td files <id>` | Show linked files and change status |

## System

| Command | Description |
|---------|-------------|
| `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 <name>` | Get one feature flag |
| `td feature set <name> <true\|false>` | Set a project-level feature override |
| `td feature unset <name>` | 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 <key> <value>` | Set a global config value such as `sync.url` or autosync settings |
| `td config get <key>` | Read one config value |
| `td config list` | Print the global config as JSON |
| `td config associate [dir] <project>` | 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 <project-id>` | 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 <email> [role]` | Invite a collaborator as `writer`, `reader`, or `owner` |
| `td sync-project role <user-id> <role>` | Change a member role |
| `td sync-project kick <user-id>` | 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 -
```
4 changes: 4 additions & 0 deletions website/docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
113 changes: 113 additions & 0 deletions website/docs/notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <id>` 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).
Loading
Loading