### DNS Setup Example

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Create an A record pointing your subdomain to your VPS IP.

```bash
# Example using DigitalOcean CLI
doctl compute domain records create example.com \
  --record-type A \
  --record-name sync \
  --record-data <VPS_IP> \
  --record-ttl 300

# Verify (may take a few minutes to propagate)
dig sync.example.com +short
```

--------------------------------

### Quick start

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Quick start guide for Docker deployment.

```bash
cd deploy
cp .env.example .env
# Edit .env as needed
docker compose up -d
```

--------------------------------

### Quick Start

Source: https://github.com/marcus/td/blob/main/website/docs/guides/docusaurus-site-guide.md

Commands to install dependencies and start the development server.

```bash
cd website
npm install
npm start    # Dev server at localhost:3000
```

--------------------------------

### Quick Start Table Implementation

Source: https://github.com/marcus/td/blob/main/docs/guides/lipgloss-table-guide.md

Example of creating and rendering a basic table with headers, styling, and visible rows.

```go
import "github.com/charmbracelet/lipgloss/table"

t := table.New().
    Headers("Col1", "Col2", "Col3").
    Width(contentWidth).
    StyleFunc(myStyleFunc).
    Border(lipgloss.HiddenBorder()).
    BorderHeader(false).
    BorderRow(false).
    BorderColumn(false).
    BorderTop(false).
    BorderBottom(false).
    BorderLeft(false).
    BorderRight(false)

// Add only visible rows (avoids ellipsis overflow row)
visibleRows := layout.dataRowsVisible
startIdx := offset
endIdx := min(startIdx+visibleRows, len(data))
rows := make([][]string, endIdx-startIdx)
for i := startIdx; i < endIdx; i++ {
    rows[i-startIdx] = formatRow(data[i])
}
t.Rows(rows...)

return t.Render()
```

--------------------------------

### Install td using Go

Source: https://github.com/marcus/td/blob/main/website/docs/intro.md

Installs the td CLI tool using Go, ensuring the binary directory is in the PATH.

```bash
# Requirements: Go 1.21+
go install github.com/marcus/td@latest

# Ensure ~/go/bin is in PATH
export PATH="$PATH:$HOME/go/bin"
```

--------------------------------

### Configure Auto-Sync on Start

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Enables sync operations to run on command startup in auto-sync mode.

```bash
td config set sync.auto.on_start true
```

--------------------------------

### Install Dependencies on VPS

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Install Docker, certbot, and nginx on the VPS.

```bash
ssh root@<VPS_IP>

# Install Docker
curl -fsSL https://get.docker.com | sh
systemctl enable docker

# Install certbot and nginx
apt update && apt install -y certbot python3-certbot-nginx nginx
```

--------------------------------

### Enable and Start nginx

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Enable the new nginx site and start the service.

```bash
ln -sf /etc/nginx/sites-available/td-sync /etc/nginx/sites-enabled/
nginx -t && systemctl start nginx
```

--------------------------------

### Authenticate with CLI

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Logs in to the CLI for authentication.

```bash
td auth login
```

--------------------------------

### Testing

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Example of setting up a temporary directory and database for testing a command.

```go
func TestMyCommand(t *testing.T) {
    tempDir := t.TempDir()
    baseDirOverride = &tempDir
    defer func() { baseDirOverride = nil }()

    database, _ := db.Open(tempDir)
    defer database.Close()
    // Test...
}
```

--------------------------------

### Quick Start Workflow

Source: https://github.com/marcus/td/blob/main/website/docs/intro.md

A sequence of commands demonstrating the basic usage of td for task tracking, including initialization, creation, starting, logging, and handing off issues.

```bash
cd /path/to/your/project
td init

# Create first issue
td create "Add user auth" --type feature --priority P1

# Start work
td start td-a1b2

# Log progress
td log "OAuth callback working"

# Hand off before context ends
td handoff td-a1b2 --done "OAuth flow" --remaining "Token refresh"

# Submit for review (an independent session records the review)
td review td-a1b2
```

--------------------------------

### Environment File Example

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Copy and configure the environment file for deployment.

```bash
SYNC_LISTEN_PORT=8080
SYNC_ALLOW_SIGNUP=true
SYNC_BASE_URL=https://sync.example.com   # Set to your public URL
SYNC_SHUTDOWN_TIMEOUT=30s
```

--------------------------------

### Quick Start commands

Source: https://github.com/marcus/td/blob/main/docs/primer.md

A sequence of commands to get started with td, including initialization, issue creation, and workflow management.

```bash
# Initialize td in your project
cd /path/to/your/project
td init

# Create your first issue
td create "Add user authentication" --type feature --priority P1

# See what to work on
td usage

# Start work on an issue
td start td-a1b2

# Log progress as you go
td log "OAuth callback implemented"

# Hand off when done
td handoff td-a1b2 --done "OAuth flow" --remaining "Token refresh"

# Submit for review
td review td-a1b2

# Open the live dashboard in a separate terminal
td monitor
```

--------------------------------

### Quick Start for Multi-Environment Deployment

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Steps to quickly set up and deploy to a new environment.

```bash
# 1. Copy the environment template
cp deploy/envs/.env.prod.example deploy/envs/.env.prod

# 2. Fill in your values (DEPLOY_HOST, S3 credentials, etc.)
vim deploy/envs/.env.prod

# 3. Deploy
./deploy.sh prod
```

--------------------------------

### Start server with fixed port

Source: https://github.com/marcus/td/blob/main/website/docs/http-api/overview.md

Example of starting the td serve command with a specific port.

```bash
td serve --port 8080
```

--------------------------------

### Workflow Hints

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Example of handling workflow hints for specific commands.

```go
func handleWorkflowHint(cmd string) bool {
    switch cmd {
    case "done", "complete":
        showWorkflowHint(cmd, "review", "Use 'td close' for admin closures.")
        return true
    }
    return false
}
```

--------------------------------

### Initialize Sync via CLI

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Initializes sync through an interactive CLI process.

```bash
td sync init
```

--------------------------------

### View Current Config

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Commands to view the current configuration settings for the sync feature.

```bash
td config list                     # all settings as JSON
td config get sync.url             # single value
```

--------------------------------

### Join an Existing Sync Project Interactively

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Fetches a list of available projects and allows interactive selection to join.

```bash
td sync-project join
```

--------------------------------

### Start server with authentication and CORS

Source: https://github.com/marcus/td/blob/main/website/docs/http-api/overview.md

Example of starting the td serve command with authentication token and CORS configuration for a React development server.

```bash
td serve --token my-secret --cors http://localhost:3000
```

--------------------------------

### Test Harness Setup

Source: https://github.com/marcus/td/blob/main/docs/sync-testing-guide.md

Go code snippet demonstrating how to initialize the test harness with a specified number of clients and a project.

```go
func TestMyScenario(t *testing.T) {
    h := NewHarness(t, 2, "proj-1")  // 2 clients, 1 project
    // ...
}
```

--------------------------------

### Create a New Sync Project

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Creates a new remote sync project and links the local database.

```bash
td sync-project create "my-project"
```

--------------------------------

### Mutation logging contract example

Source: https://github.com/marcus/td/blob/main/docs/sync-agent-guide.md

Go code demonstrating how to log mutations with previous and new data snapshots.

```go
prevData, _ := json.Marshal(issue)   # snapshot before
issue.Status = models.StatusClosed
m.DB.UpdateIssue(issue)
newData, _ := json.Marshal(issue)    # snapshot after
m.DB.LogAction(&models.ActionLog{
    SessionID:    sessionID,
    ActionType:   models.ActionClose,
    EntityType:   "issue",
    EntityID:     issue.ID,
    PreviousData: string(prevData),
    NewData:      string(newData),
})
```

--------------------------------

### Validation

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Examples of model and argument validation in Go.

```go
// Model validation
if t != "" {
    typ := models.Type(t)
    if !models.IsValidType(typ) {
        output.Error("invalid type: %s", t)
        return fmt.Errorf("invalid type: %s", t)
    }
}

// Argument validation
Args: cobra.ExactArgs(1)
Args: cobra.MinimumNArgs(1)
Args: cobra.RangeArgs(1, 3)
```

--------------------------------

### Undo Support

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Example of capturing previous and new data for undo functionality.

```go
// Capture before mutation
prevData, _ := json.Marshal(issue)

// Mutate
issue.Status = models.StatusInProgress
database.UpdateIssue(issue)

// Log for undo
newData, _ := json.Marshal(issue)
database.LogAction(&models.ActionLog{
    SessionID:    sess.ID,
    ActionType:   models.ActionStart,
    EntityType:   "issue",
    EntityID:     issue.ID,
    PreviousData: string(prevData),
    NewData:      string(newData),
})
```

--------------------------------

### Invite Teammate with Writer Role

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Invites a teammate via email with default writer permissions.

```bash
td sync-project invite alice@example.com
```

--------------------------------

### Join an Existing Sync Project by Name

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Joins an existing sync project by specifying its name.

```bash
td sync-project join "backend-api"
```

--------------------------------

### Enable Auto-Sync

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Enables automatic push and pull operations for sync.

```bash
td config set sync.auto.enabled true
```

--------------------------------

### Set Configuration Values

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Commands to set various configuration values for the sync feature.

```bash
td config set sync.url https://sync.example.com
td config set sync.auto.enabled true
td config set sync.snapshot_threshold 500
```

--------------------------------

### Invite Teammate with Reader Role

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Invites a teammate via email with read-only permissions.

```bash
td sync-project invite bob@example.com reader
```

--------------------------------

### Mouse HitMap Example

Source: https://github.com/marcus/td/blob/main/docs/guides/declarative-modal-guide.md

Illustrates how to use the `mouse.HitMap` to track rectangular regions and test for hits at specific coordinates.

```go
hm := mouse.NewHitMap()

// Add regions (later regions have higher priority)
hm.AddRect("backdrop", 0, 0, screenW, screenH, nil)
hm.AddRect("modal", modalX, modalY, modalW, modalH, nil)
hm.AddRect("button", btnX, btnY, btnW, btnH, "btn-data")

// Test hit at point
region := hm.Test(clickX, clickY)
if region != nil {
    fmt.Println("Hit:", region.ID, region.Data)
}

// Clear for next frame
hm.Clear()
```

--------------------------------

### Panel Height Calculation

Source: https://github.com/marcus/td/blob/main/docs/guides/lipgloss-table-guide.md

Example showing how to correctly calculate panel height to avoid rounding mismatches.

```go
// WRONG - direct multiplication causes rounding mismatch
case PanelActivity:
    panelHeight = int(float64(availableHeight) * m.PaneHeights[2])

// CORRECT - match renderView() which absorbs rounding errors for last panel
panel0 := int(float64(availableHeight) * m.PaneHeights[0])
panel1 := int(float64(availableHeight) * m.PaneHeights[1])
case PanelActivity:
    panelHeight = availableHeight - panel0 - panel1  // Absorbs rounding
```

--------------------------------

### Quick Start

Source: https://github.com/marcus/td/blob/main/deploy/envs/README.md

Steps to copy a template, edit with values, and deploy.

```bash
# 1. Copy the template for your target environment
cp .env.prod.example .env.prod

# 2. Edit with your values
vim .env.prod

# 3. Deploy
cd .. && ./deploy.sh prod
```

--------------------------------

### Metrics JSON Example

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Example JSON output from the /metricz endpoint.

```json
{
  "uptime_seconds": 3600,
  "requests": 15420,
  "server_errors": 2,
  "client_errors": 45,
  "push_events_accepted": 8930,
  "pull_requests": 6200
}
```

--------------------------------

### Status message example

Source: https://github.com/marcus/td/blob/main/docs/guides/monitor-shortcuts-guide.md

Example of setting a status message and clearing it after a delay.

```go
m.StatusMessage = "Copied to clipboard"
return m, m.clearStatusAfterDelay()  // Clears after 2s
```

--------------------------------

### Get Single Issue Example

Source: https://github.com/marcus/td/blob/main/website/docs/http-api/api-reference.md

Example curl command to retrieve a single issue by its ID.

```bash
curl http://localhost:54321/v1/issues/td-abc123
```

--------------------------------

### Build and run

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

Build the server and run it with default or custom configurations.

```bash
# Build the server
go build -o td-sync ./cmd/td-sync

# Run with defaults (listens on :8080, stores data in ./data/)
./td-sync

# Run with custom config
SYNC_LISTEN_ADDR=:9090 \
SYNC_BASE_URL=http://localhost:9090 \
SYNC_SERVER_DB_PATH=./mydata/server.db \
SYNC_PROJECT_DATA_DIR=./mydata/projects \
SYNC_LOG_FORMAT=text \
SYNC_LOG_LEVEL=debug \
./td-sync
```

--------------------------------

### Get Stats API Response

Source: https://github.com/marcus/td/blob/main/docs/td-serve-spec.md

Example JSON response for the GET /v1/stats endpoint.

```json
{
  "ok": true,
  "data": {
    "total": 142,
    "by_status": { "open": 34, "in_progress": 5, "blocked": 3, "in_review": 2, "closed": 98 },
    "by_type": { "bug": 12, "feature": 45, "task": 60, "epic": 8, "chore": 17 },
    "by_priority": { "P0": 2, "P1": 8, "P2": 55, "P3": 40, "P4": 37 },
    "created_today": 3,
    "created_this_week": 11,
    "total_points": 287,
    "completion_rate": 0.69,
    "total_logs": 534,
    "total_handoffs": 89
  }
}
```

--------------------------------

### Get Sessions API Response

Source: https://github.com/marcus/td/blob/main/docs/td-serve-spec.md

Example JSON response for the GET /v1/sessions endpoint.

```json
{
  "ok": true,
  "data": {
    "sessions": [
      {
        "id": "ses_a1b2c3",
        "name": "td-serve-web",
        "branch": "default",
        "agent_type": "web",
        "started_at": "2026-02-27T03:00:00Z",
        "last_activity": "2026-02-27T04:10:00Z"
      }
    ],
    "current_session_id": "ses_a1b2c3"
  }
}
```

--------------------------------

### Get Single Issue Response Example

Source: https://github.com/marcus/td/blob/main/website/docs/http-api/api-reference.md

Example JSON response for retrieving a single issue, including dependencies.

```json
{
  "ok": true,
  "data": {
    "issue": { "id": "td-abc123", "title": "Fix auth", "status": "open", "..." : "..." },
    "logs": [],
    "comments": [],
    "latest_handoff": null,
    "dependencies": [
      {
        "dep_id": "dep_a1b2c3d4",
        "issue_id": "td-abc123",
        "depends_on_id": "td-111",
        "relation_type": "depends_on"
      }
    ],
    "blocked_by": []
  }
}
```

--------------------------------

### Start work on an issue with a reason

Source: https://github.com/marcus/td/blob/main/docs/implemented/SPEC.md

Example of starting work on an issue, including a reason and capturing git state.

```bash
td start td-5q --reason "Starting OAuth implementation"
# Output:
# STARTED td-5q (session: ses_a1b2c3)
# Git: abc1234 (main) clean
```

--------------------------------

### Start work on an issue with uncommitted changes

Source: https://github.com/marcus/td/blob/main/docs/implemented/SPEC.md

Example of starting work on an issue when the working tree is dirty, including a warning.

```bash
td start td-5q
# Output:
# STARTED td-5q (session: ses_a1b2c3)
# Git: abc1234 (main) 2 modified, 1 untracked
# Warning: Starting with uncommitted changes
```

--------------------------------

### List your projects

Source: https://github.com/marcus/td/blob/main/docs/sync-client-guide.md

Lists all projects associated with the user.

```bash
td sync-project list
# ID                                    NAME                  CREATED
# a1b2c3d4-e5f6-...                     my-team-project       2026-01-31T10:00:00Z
```

--------------------------------

### GET /v1/monitor Response

Source: https://github.com/marcus/td/blob/main/docs/td-serve-spec.md

Example response payload for the GET /v1/monitor endpoint, representing a snapshot of board/list/activity.

```json
{
  "ok": true,
  "data": {
    "timestamp": "2026-02-27T04:20:00Z",
    "change_token": "1824",
    "session_id": "ses_a1b2c3",
    "focused_issue": null,
    "in_progress": [],
    "task_list": {
      "reviewable": [],
      "needs_rework": [],
      "in_progress": [],
      "ready": [],
      "pending_review": [],
      "blocked": [],
      "closed": []
    },
    "activity": [],
    "recent_handoffs": [],
    "active_sessions": []
  }
}
```

--------------------------------

### GET /v1/issues Response

Source: https://github.com/marcus/td/blob/main/docs/td-serve-spec.md

Example response payload for the GET /v1/issues endpoint, listing issues with pagination details.

```json
{
  "ok": true,
  "data": {
    "issues": [],
    "total": 42,
    "limit": 200,
    "offset": 0,
    "has_more": false
  }
}
```

--------------------------------

### Output Patterns

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Provides examples of different output patterns, including errors, warnings, standard output, JSON, and action confirmations.

```go
// Errors
output.Error("failed: %v", err)

// Warnings
output.Warning("issue blocked: %s", id)

// Standard output
fmt.Println(output.FormatIssueShort(&issue))

// JSON
if jsonOutput, _ := cmd.Flags().GetBool("json"); jsonOutput {
    return output.JSON(result)
}

// Action confirmation (uppercase)
fmt.Printf("CREATED %s\n", issue.ID)
```

--------------------------------

### Create a new remote project

Source: https://github.com/marcus/td/blob/main/docs/sync-client-guide.md

Creates a new remote project with an optional description.

```bash
td sync-project create "my-team-project"
# ✓ Created project my-team-project (a1b2c3d4-...)

td sync-project create "my-project" --description "Sprint tracker"
```

--------------------------------

### Boolean Logic

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of boolean logic in TDQ queries.

```bash
td query "type = bug AND status = open"
td query "priority = P0 OR priority = P1"
td query "NOT status = closed"
```

--------------------------------

### Running Tests

Source: https://github.com/marcus/td/blob/main/docs/sync-testing-guide.md

Command-line examples for running various test suites, including all tests, specific packages, verbose output, and end-to-end chaos runs.

```bash
# All tests
go test ./...

# Sync engine (event application, push/pull logic)
go test ./internal/sync/...

# Server API (HTTP handlers, auth, push/pull endpoints)
go test ./internal/api/...

# Server database (users, keys, projects, memberships)
go test ./internal/serverdb/...

# Multi-client integration (convergence, conflicts, edge cases)
go test ./test/syncharness/...

# Verbose output
go test -v ./test/syncharness/...

# E2E chaos oracle (black-box, builds real binaries, starts real server)
go test -v -count=1 -timeout 5m -run TestSmoke ./test/e2e/

# Full chaos run
go test -v -count=1 -timeout 30m -run TestChaosSync ./test/e2e/ \
    -args -chaos.actions=500 -chaos.seed=42

# Individual conflict scenarios
go test -v -count=1 -timeout 5m -run TestPartitionRecovery ./test/e2e/
```

--------------------------------

### Text Search

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of text search queries in TDQ.

```bash
# Searches title, description, ID
td query "authentication"
# Title contains "auth"
td query 'title ~ "auth"'
```

--------------------------------

### Configure Auto-Sync Interval

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Sets the periodic sync interval for auto-sync.

```bash
td config set sync.auto.interval 5m
```

--------------------------------

### Local Development

Source: https://github.com/marcus/td/blob/main/website/README.md

Starts a local development server for live previewing changes.

```bash
yarn start
```

--------------------------------

### td board creation examples

Source: https://github.com/marcus/td/blob/main/docs/primer.md

Demonstrates how to create boards in td with specific queries to filter issues.

```bash
td board create "Sprint 1" --query "priority <= P1"
```

```bash
td board create "Bug Triage" --query "type = bug AND status = open"
```

--------------------------------

### Check Authentication Status

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Checks the current authentication status of the CLI.

```bash
td auth status
```

--------------------------------

### Running the sync server

Source: https://github.com/marcus/td/blob/main/docs/primer.md

Commands to set up and run the td sync server and clients.

```bash
# On the server: run the sync server
td-sync serve

# On each client: authenticate and link
td auth login
td sync-project create "my-project"   # first client creates the project
td sync-project join "my-project"     # other clients join it
td sync                                # push/pull events
```

--------------------------------

### GET /v1/issues/{id} Response

Source: https://github.com/marcus/td/blob/main/docs/td-serve-spec.md

Example response payload for GET /v1/issues/{id}, including issue details, logs, comments, and dependency information.

```json
{
  "ok": true,
  "data": {
    "issue": {},
    "logs": [],
    "comments": [],
    "latest_handoff": null,
    "dependencies": [
      {
        "dep_id": "dep_a1b2c3d4",
        "issue_id": "td-abc123",
        "depends_on_id": "td-111",
        "relation_type": "depends_on"
      }
    ],
    "blocked_by": [
      {
        "dep_id": "dep_z9y8x7w6",
        "issue_id": "td-333",
        "depends_on_id": "td-abc123",
        "relation_type": "depends_on"
      }
    ]
  }
}
```

--------------------------------

### Quick Start - Initialize

Source: https://github.com/marcus/td/blob/main/README.md

Commands to initialize td in a project directory.

```bash
cd /path/to/your/project
td init
```

--------------------------------

### Relative Dates

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of using relative dates in TDQ queries.

```bash
td query "created >= -7d"  # Created in last 7 days
td query "updated >= today" # Updated today
```

--------------------------------

### Using Description and Acceptance Files

Source: https://github.com/marcus/td/blob/main/website/docs/core-workflow.md

Demonstrates using `--description-file` and `--acceptance-file` for markdown-heavy content, including reading from stdin.

```bash
cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
```

--------------------------------

### Basic Field Queries

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of basic field queries in TDQ.

```bash
td query "status = open"
td query "type = bug"
td query "priority <= P1"
```

--------------------------------

### Configure Auto-Sync Pull

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Enables or disables pull operations in auto-sync mode.

```bash
td config set sync.auto.pull true
```

--------------------------------

### Go tests

Source: https://github.com/marcus/td/blob/main/docs/sync-agent-guide.md

Commands to run Go tests for different parts of the sync engine.

```bash
go test ./...                           # everything
go test ./internal/sync/...             # sync engine
go test ./internal/api/...              # HTTP layer
go test ./internal/serverdb/...         # server DB
go test ./test/syncharness/...          # multi-client integration (18 scenarios)
go test ./cmd/ -run AutoSyncPush        # push batching
```

--------------------------------

### Flag Aliases

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Demonstrates how to implement aliases for flags and resolve them in priority order.

```go
createCmd.Flags().StringP("labels", "l", "", "Labels")
createCmd.Flags().String("label", "", "Alias for --labels")
createCmd.Flags().String("tags", "", "Alias for --labels")

// Resolve in priority order
labelsStr, _ := cmd.Flags().GetString("labels")
if labelsStr == "" {
    if s, _ := cmd.Flags().GetString("label"); s != "" {
        labelsStr = s
    }
}
```

--------------------------------

### Self-hosting sync server with Docker

Source: https://github.com/marcus/td/blob/main/docs/guides/collaboration.md

Steps to clone the repository, configure environment variables, and start the sync server using Docker Compose.

```bash
# Clone the repository
git clone https://github.com/marcus/td
cd td/server

# Configure environment
cp .env.example .env
# Edit .env: set AUTH_SECRET, database paths, Litestream backup credentials

# Start server + Litestream backup
docker-compose up -d
```

--------------------------------

### JSON Report Structure

Source: https://github.com/marcus/td/blob/main/docs/sync-testing-guide.md

Example structure of the JSON report generated by the chaos test.

```json
{
  "seed": 42,
  "actions": 500,
  "duration_ms": 45000,
  "actors": 2,
  "results": {
    "total": 500,
    "ok": 380,
    "expected_fail": 45,
    "unexpected_fail": 0,
    "skipped": 75
  },
  "per_action": { "create": {"ok": 60, ...}, ... },
  "verifications": [
    {"name": "issues match", "passed": true},
    {"name": "monotonic server_seq", "passed": true, "details": "450 events, range [1..620]"}
  ],
  "sync_stats": {"count": 85},
  "pass": true
}
```

--------------------------------

### Link to a new project (automatic handling)

Source: https://github.com/marcus/td/blob/main/docs/sync-client-guide.md

CLI command to link to a new project, automatically clearing sync state and re-linking.

```bash
td sync-project link <new-project-id>
# ⚠ Already linked to project old-proj-id.
# Re-link to new-proj-id and clear sync state? [y/N]: y
# ✓ Cleared sync state and linked to project new-proj-id
```

--------------------------------

### Inline Sort

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of applying sorting directly within the query string.

```bash
# Sort by priority (ascending)
td query "type = bug sort:priority"

# Sort by priority descending
td query "type = bug sort:-priority"

# Multiple sort fields
td query "status = open sort:-priority sort:created"
```

--------------------------------

### Test the full auth + sync flow locally

Source: https://github.com/marcus/td/blob/main/docs/sync-server-ops-guide.md

A step-by-step guide to test the authentication and synchronization flow locally.

```bash
# 1. Start server
./td-sync &

# 2. Login from td CLI (uses localhost:8080 by default)
td auth login
# Enter email, then open the verification URL in browser and enter the code

# 3. Create a remote project
td sync-project create "my-project"
# Note the project ID

# 4. Link local project to remote
td sync-project link <project-id>

# 5. Push local changes
td sync --push

# 6. Pull remote changes
td sync --pull

# 7. Check status
td sync --status
```

--------------------------------

### Complex Queries

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of combining multiple conditions for sophisticated issue filtering.

```bash
# High priority bugs created this week, not in review
td query "type = bug AND priority <= P1 AND created >= this_week AND status != in_review"

# Open features with no labels
td query "type = feature AND is(open) AND NOT has(labels)"

# All tasks in an epic that are blocked
td query "descendant_of(td-epic1) AND is(blocked)"

# Bugs or features with urgent label
td query "(type = bug OR type = feature) AND labels ~ urgent"
```

--------------------------------

### Quick Start - Create first issue

Source: https://github.com/marcus/td/blob/main/README.md

Command to create the first issue with type and priority.

```bash
td create "Add user auth" --type feature --priority P1
```

--------------------------------

### Panel-specific issue access

Source: https://github.com/marcus/td/blob/main/docs/guides/monitor-shortcuts-guide.md

Examples of accessing issues based on specific panels.

```go
- PanelCurrentWork: `m.FocusedIssue` or `m.InProgress[]`
- PanelTaskList: `m.TaskListRows[cursor].Issue`
- PanelActivity: Only has `IssueID`
```

--------------------------------

### Adding dependencies

Source: https://github.com/marcus/td/blob/main/docs/primer.md

Example of adding a dependency between issues.

```bash
td dep add td-abc td-xyz   # td-abc depends on td-xyz (td-abc is blocked until td-xyz is done)
```

--------------------------------

### Basic Filtering

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of basic filtering by status, priority, points, and labels.

```bash
# All open issues
td query "status = open"

# High priority bugs
td query "type = bug AND priority <= P1"

# Large issues (8+ points)
td query "points >= 8"

# Issues with specific label
td query "labels ~ urgent"
```

--------------------------------

### Installation

Source: https://github.com/marcus/td/blob/main/website/README.md

Installs project dependencies using Yarn.

```bash
yarn
```

--------------------------------

### Configure Auto-Sync Debounce

Source: https://github.com/marcus/td/blob/main/docs/guides/sync-setup-guide.md

Sets the debounce time for post-mutation syncs in auto-sync mode.

```bash
td config set sync.auto.debounce 5s
```

--------------------------------

### Session-Aware Shortcuts

Source: https://github.com/marcus/td/blob/main/docs/guides/cli-commands-guide.md

Illustrates how a shortcut command can access and utilize session information.

```go
RunE: func(cmd *cobra.Command, args []string) error {
    baseDir := getBaseDir()
    sess, err := session.GetOrCreate(baseDir)
    if err != nil {
        output.Error("%v", err)
        return err
    }

    result, err := runListShortcut(db.ListIssuesOptions{
        ReviewableBy: sess.ID,
    })
    // ...
}
```

--------------------------------

### Network Partition Test Example

Source: https://github.com/marcus/td/blob/main/scripts/e2e/e2e-sync-test-guide.md

Example command for running the network partition test.

```bash
bash scripts/e2e/test_network_partition.sh --phase1-actions 20 --offline-actions 40 --online-actions 30
```

--------------------------------

### Date Queries

Source: https://github.com/marcus/td/blob/main/docs/guides/query-guide.md

Examples of filtering issues based on creation, update, and closure dates.

```bash
# Created in last 7 days
td query "created >= -7d"

# Updated today
td query "updated >= today"

# Stale open issues (not updated in 30 days)
td query "status = open AND updated < -30d"

# Closed this week
td query "status = closed AND closed >= this_week"
```

--------------------------------

### CLI Command Examples

Source: https://github.com/marcus/td/blob/main/docs/plans/orchestrator-review-closure-plan.md

Illustrative examples of how CLI commands will behave or be modified.

```bash
td close
```

```bash
td approve --record-only
```

```bash
td approve --record-only --reason "Summary of review comments"
```

```bash
td approve --record-only --decision changes_requested
```

```bash
td approve --reason "Issue requires fresher review"
```

```bash
td list --reviewable
```

```bash
td list --include-approved
```