From 3b4c9f72d3fe8e72ef413414b2247a84a5ce4f29 Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 6 Apr 2026 02:54:00 -0700 Subject: [PATCH 1/2] docs: backfill website docs for notes and sync Nightshift-Task: docs-backfill Nightshift-Ref: https://github.com/marcus/nightshift --- README.md | 2 +- website/docs/command-reference.md | 256 ++++++++++++++++------------- website/docs/intro.md | 2 + website/docs/notes.md | 104 ++++++++++++ website/docs/sync-collaboration.md | 185 +++++++++++++++++++++ website/sidebars.js | 4 +- 6 files changed, 440 insertions(+), 113 deletions(-) create mode 100644 website/docs/notes.md create mode 100644 website/docs/sync-collaboration.md diff --git a/README.md b/README.md index 684416ad..9700ac89 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 [Getting Started](https://marcus.github.io/td/docs/intro), [Notes](https://marcus.github.io/td/docs/notes), and [Sync & Collaboration](https://marcus.github.io/td/docs/sync-collaboration). ## Claude Code / OpenAI Codex Skill diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 28e9da1c..33c9c136 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -1,147 +1,181 @@ --- -sidebar_position: 11 +sidebar_position: 13 --- # Command Reference -Complete reference for all `td` commands. +Complete reference for the `td` CLI, including note management, work session helpers, diagnostics, and the feature-gated sync workflow. -## Core Commands +> **Note**: Sync and config commands are hidden unless the `sync_cli` feature is enabled. Use `export TD_ENABLE_FEATURE=sync_cli`, or run `td feature set sync_cli true` and restart your shell before using `td sync`, `td auth`, `td config`, `td doctor`, or `td sync-project`. + +## 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 <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 | +| `td note add "title"` | Create a freeform note | +| `td note list` | List notes with filters such as `--pinned`, `--archived`, `--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 | ## 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 - -| 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` - -## 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 +| `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 active work | +| `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 comment subcommand | +| `td workflow` | Print the issue state workflow summary | +| `td check-handoff` | Exit non-zero when the current focus still needs a handoff | + +## Query, Dependencies, And Boards | 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"` | Run a TDQ query | +| `td search "keyword"` | Full-text search across issues | +| `td next` | Show the highest-priority open issue | +| `td ready` | List ready 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 | +| `td in-review` | List issues in review | +| `td reviewable` | List issues you can review from this session | +| `td dep add <issue> <depends-on>...` | Add dependencies | +| `td dep rm <issue> <depends-on>` | Remove dependencies | +| `td dep <issue>` | Show dependencies for an issue | +| `td dep <issue> --blocking` | Show issues this work item blocks | +| `td blocked-by <issue>` | Show issues waiting on this issue | +| `td depends-on <issue>` | Show issues this issue depends on | +| `td critical-path` | Show the best unblocking order | +| `td tree <id>` | Show the issue tree, with optional `--depth` or `--json` | +| `td board create "name" --query "..."` | Create a board from a TDQ query | +| `td board list` | List boards | +| `td board show <board>` | Show board results, optionally filtered by status | +| `td board move <board> <id> <position>` | Set explicit ordering for a card on a board | +| `td board unposition <board> <id>` | Remove a board-specific position override | +| `td board edit <board>` | Rename a board or change its query | +| `td board delete <board>` | Delete a board | -## Boards +## Sessions And Work Sessions | 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 +| `td usage [--new-session] [-q]` | Generate AI-friendly context for the current project | +| `td session [name]` | Label the current session | +| `td session --new` | Force a new session at context start | +| `td session list` | List branch- and agent-scoped sessions | +| `td session cleanup` | Remove stale session files | +| `td whoami` | Show the current session identity | +| `td status` | Show the dashboard view | +| `td focus <id>` | Set the focused issue | +| `td unfocus` | Clear the focus | +| `td ws start "name"` | Start a multi-issue work session | +| `td ws tag <ids...>` | Tag issues into the active work session | +| `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 once to the work session and all tagged issues | +| `td ws current` | Show the active work session | +| `td ws handoff` | Generate handoffs for tagged issues and end the session | +| `td ws end` | End the current work session without handoff generation | +| `td ws list` | List recent work sessions | +| `td ws show <session-id>` | Show a past work session | + +## Files And Directory Associations | 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 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 | +| `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 | -## Sessions +## System And Diagnostics | 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 ` | Set focus | -| `td unfocus` | Clear focus | -| `td whoami` | Show session identity | - -## Work Sessions +| `td init` | Initialize a td project | +| `td monitor` | Launch the 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 the last action | +| `td last` | Show the last action performed | +| `td export` | Export the database | +| `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 | +| `td version` | Show the current version and update info | + +## Sync And Collaboration Commands + +These commands are available only when `sync_cli` is enabled. See [Sync & Collaboration](./sync-collaboration.md) for setup and troubleshooting. | 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 auth login` | Authenticate with a sync server | +| `td auth status` | Show current auth status | +| `td auth logout` | Remove local credentials | +| `td config set <key> <value>` | Set sync config such as `sync.url` or autosync behavior | +| `td config get <key>` | Read one config value | +| `td config list` | Print config as JSON | +| `td doctor` | Run sync diagnostics | +| `td sync init` | Guided sync setup | +| `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 | -## Files +## Agent-Safe Rich Text Input -| Command | Description | -|---------|-------------| -| `td link ` | Link files to issue | -| `td unlink ` | Unlink files | -| `td files ` | Show file status | +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. -## System +```bash +td create "Document sync failure modes" \ + --description-file docs/issue-description.md \ + --acceptance-file docs/issue-acceptance.md -| 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 | +cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file - +``` diff --git a/website/docs/intro.md b/website/docs/intro.md index 393bad49..76d6c123 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -93,5 +93,7 @@ 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 freeform project context without creating an issue - [Boards](./boards.md) -- Visual overview of issue status across your project +- [Sync & Collaboration](./sync-collaboration.md) -- Enable shared projects, auth, and remote sync - [Query Language](./query-language.md) -- Filter and search issues with structured queries diff --git a/website/docs/notes.md b/website/docs/notes.md new file mode 100644 index 00000000..f37d9c3a --- /dev/null +++ b/website/docs/notes.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 6 +--- + +# Notes + +Use notes for freeform project context that does not belong to a single issue. Notes live alongside your td data, but they are separate from the issue workflow. + +## When To Use Notes + +Use notes when you want to capture: + +- architecture decisions that span multiple issues +- meeting notes, research snippets, and rough plans +- onboarding context for future agent or human sessions +- checklists or scratchpad content that should not change issue status + +Use issues when the work has a clear owner, status, review path, 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 a longer note 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 --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 + +td note delete nt-abc123 +``` + +## 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 And 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 +``` + +Re-enable it later with: + +```bash +td feature set sync_notes true +``` + +For the full 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 00000000..83470108 --- /dev/null +++ b/website/docs/sync-collaboration.md @@ -0,0 +1,185 @@ +--- +sidebar_position: 9 +--- + +# Sync & Collaboration + +Use td sync when you want one local project database to stay in sync across machines or teammates. This guide covers the feature gate, auth, project linking, routine sync commands, and common failure modes. + +## Enable Sync Commands + +The sync surface is feature-gated. If `td sync` or `td auth` shows as an unknown command, enable `sync_cli` first. + +Recommended for immediate use in a shell: + +```bash +export TD_ENABLE_FEATURE=sync_cli +``` + +Project-level alternative: + +```bash +td feature set sync_cli true +``` + +`td feature set` writes the flag to project config, but command registration happens when the process starts, so restart your shell after setting it. + +## Quick Setup + +If you want the shortest path, run: + +```bash +td sync init +``` + +The guided flow walks through server selection, auth, and linking to a remote project. + +## 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 auth flow. `td auth status` is the fastest way to confirm whether the current machine still has a valid 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" +``` + +Teammates usually join an existing project: + +```bash +td sync-project join +td sync-project join "team-project" +``` + +Use `join` when possible. It validates what you pick from the server. `link` is better for scripts and known IDs: + +```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 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 access + +## 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, server reachability, and local project linkage. `td sync conflicts` shows recent overwrite events. `td sync tail` is useful when you want to watch push and pull activity live. + +## Autosync Configuration + +You can keep sync manual, or enable background sync behavior: + +```bash +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 +``` + +Other supported sync config keys: + +- `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 with the rest of the project by default. If you want notes to stay local in a shared repo, disable note syncing in that project: + +```bash +td feature set sync_notes false +``` + +## Troubleshooting + +**`unknown command "sync"` or `unknown command "auth"`** + +Enable `sync_cli` first. See [Enable Sync Commands](#enable-sync-commands). + +**`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`. + +**`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 check more than a plain `td sync` run with no pending local events. diff --git a/website/sidebars.js b/website/sidebars.js index 4da1f856..100b84c7 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -8,11 +8,13 @@ const sidebars = { 'core-workflow', 'boards', 'dependencies', - 'query-language', 'epics', + 'notes', 'work-sessions', + 'sync-collaboration', 'deferral', 'file-tracking', + 'query-language', ], }, { From b6e294e47b5cb794f591c6c542526860b6e402f7 Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 6 Apr 2026 03:02:50 -0700 Subject: [PATCH 2/2] docs: fix sync command enablement guidance Nightshift-Task: docs-backfill Nightshift-Ref: https://github.com/marcus/nightshift --- website/docs/command-reference.md | 4 ++-- website/docs/notes.md | 2 ++ website/docs/sync-collaboration.md | 16 ++++++++++------ 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/website/docs/command-reference.md b/website/docs/command-reference.md index 33c9c136..44ec14b8 100644 --- a/website/docs/command-reference.md +++ b/website/docs/command-reference.md @@ -6,7 +6,7 @@ sidebar_position: 13 Complete reference for the `td` CLI, including note management, work session helpers, diagnostics, and the feature-gated sync workflow. -> **Note**: Sync and config commands are hidden unless the `sync_cli` feature is enabled. Use `export TD_ENABLE_FEATURE=sync_cli`, or run `td feature set sync_cli true` and restart your shell before using `td sync`, `td auth`, `td config`, `td doctor`, or `td sync-project`. +> **Note**: Sync and config commands are hidden unless `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 register hidden commands. ## Core Issue Commands @@ -140,7 +140,7 @@ Complete reference for the `td` CLI, including note management, work session hel ## Sync And Collaboration Commands -These commands are available only when `sync_cli` is enabled. See [Sync & Collaboration](./sync-collaboration.md) for setup and troubleshooting. +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 | |---------|-------------| diff --git a/website/docs/notes.md b/website/docs/notes.md index f37d9c3a..ca75e9c9 100644 --- a/website/docs/notes.md +++ b/website/docs/notes.md @@ -95,6 +95,8 @@ If you are using the sync workflow, notes can sync with the rest of the project td feature set sync_notes false ``` +Unlike the `sync_cli` command gate, `sync_notes` is resolved from project config at runtime, so this flag takes effect without needing an environment override. + Re-enable it later with: ```bash diff --git a/website/docs/sync-collaboration.md b/website/docs/sync-collaboration.md index 83470108..6e8167e3 100644 --- a/website/docs/sync-collaboration.md +++ b/website/docs/sync-collaboration.md @@ -8,21 +8,23 @@ Use td sync when you want one local project database to stay in sync across mach ## Enable Sync Commands -The sync surface is feature-gated. If `td sync` or `td auth` shows as an unknown command, enable `sync_cli` first. +The sync surface is feature-gated. If `td sync` or `td auth` shows as an unknown command, enable `sync_cli` for the current process before starting `td`. -Recommended for immediate use in a shell: +Recommended for an interactive shell session: ```bash export TD_ENABLE_FEATURE=sync_cli ``` -Project-level alternative: +For a single command, prefix the invocation instead: ```bash -td feature set sync_cli true +TD_FEATURE_SYNC_CLI=true td sync --help ``` -`td feature set` writes the flag to project config, but command registration happens when the process starts, so restart your shell after setting it. +Add the export to your shell profile if you use sync regularly. + +> **Important**: `td feature set sync_cli true` writes project config, but these commands are registered before project config is loaded. It is not enough to make `td sync`, `td auth`, `td config`, `td doctor`, or `td sync-project` appear. ## Quick Setup @@ -154,11 +156,13 @@ Notes sync with the rest of the project by default. If you want notes to stay lo td feature set sync_notes false ``` +Unlike `sync_cli`, `sync_notes` is read at runtime from project config, so `td feature set` works for this flag. + ## Troubleshooting **`unknown command "sync"` or `unknown command "auth"`** -Enable `sync_cli` first. See [Enable Sync Commands](#enable-sync-commands). +Enable `sync_cli` with `export TD_ENABLE_FEATURE=sync_cli` or prefix the command with `TD_FEATURE_SYNC_CLI=true`. Project config alone will not expose the hidden commands. See [Enable Sync Commands](#enable-sync-commands). **`not logged in (run: td auth login)`**