trak_flow 0.1.3

data/docs/assets/stylesheets/extra.css

@@ -0,0 +1,53 @@
+/* Hero section grid layout */
+.md-content .grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+  align-items: start;
+}
+
+/* Responsive: stack on mobile */
+@media screen and (max-width: 768px) {
+  .md-content .grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* Hero image styling */
+.md-content .grid img {
+  border-radius: 8px;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+}
+
+/* Definition list in hero - more compact */
+.md-content .grid dl {
+  margin: 1rem 0;
+}
+
+.md-content .grid dt {
+  margin-top: 0.5rem;
+  font-weight: 600;
+}
+
+.md-content .grid dd {
+  margin-left: 1.5rem;
+  margin-bottom: 0.25rem;
+  font-size: 0.9rem;
+  opacity: 0.85;
+}
+
+/* Button spacing */
+.md-content .md-button {
+  margin-right: 0.5rem;
+  margin-top: 1rem;
+}
+
+/* Make icons in definition list slightly larger */
+.md-content .grid dt .twemoji,
+.md-content .grid dt .emojione,
+.md-content .grid dt svg {
+  height: 1.2rem;
+  width: 1.2rem;
+  vertical-align: text-bottom;
+  margin-right: 0.3rem;
+}

data/docs/cli/admin-commands.md

@@ -0,0 +1,369 @@
+# Admin Commands
+
+Commands for system administration, data management, and analysis.
+
+## Initialize TrakFlow
+
+Set up TrakFlow in a project directory.
+
+```bash
+tf admin init [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Overwrite existing configuration |
+| `--dir` | Custom data directory (default: `.trak_flow`) |
+
+### Examples
+
+```bash
+# Initialize in current directory
+tf admin init
+
+# Use custom directory
+tf admin init --dir .tasks
+
+# Reinitialize (overwrite)
+tf admin init --force
+```
+
+### Created Structure
+
+```
+.trak_flow/
+├── issues.jsonl    # Task data
+├── trak_flow.db    # SQLite cache
+└── config.json     # Configuration
+```
+
+## Export Data
+
+Export tasks to JSONL format.
+
+```bash
+tf admin export [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--output`, `-o` | Output file (default: stdout) |
+| `--format` | Output format (jsonl, json) |
+| `--status` | Filter by status |
+| `--type` | Filter by type |
+| `--include-closed` | Include closed tasks |
+
+### Examples
+
+```bash
+# Export to stdout
+tf admin export
+
+# Export to file
+tf admin export -o backup.jsonl
+
+# Export only open tasks
+tf admin export --status open
+
+# Export as JSON array
+tf admin export --format json
+```
+
+## Import Data
+
+Import tasks from JSONL format.
+
+```bash
+tf admin import FILE [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--merge` | Merge with existing data |
+| `--replace` | Replace all existing data |
+| `--dry-run` | Show what would be imported |
+
+### Examples
+
+```bash
+# Import and merge
+tf admin import backup.jsonl --merge
+
+# Replace all data
+tf admin import backup.jsonl --replace
+
+# Preview import
+tf admin import backup.jsonl --dry-run
+```
+
+## Generate Dependency Graph
+
+Create a visual representation of task dependencies.
+
+```bash
+tf admin graph [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--format` | Output format: dot, svg, png (default: dot) |
+| `--output`, `-o` | Output file |
+| `--filter` | Filter expression |
+| `--cluster` | Group by label or type |
+
+### Examples
+
+```bash
+# DOT format to stdout
+tf admin graph
+
+# Generate SVG
+tf admin graph --format svg -o deps.svg
+
+# Generate PNG
+tf admin graph --format png -o deps.png
+
+# Filter by status
+tf admin graph --filter "status=open"
+
+# Cluster by type
+tf admin graph --cluster type
+```
+
+### Using Graphviz
+
+If you have Graphviz installed:
+
+```bash
+# Generate and render in one step
+tf admin graph | dot -Tsvg -o deps.svg
+
+# View immediately (macOS)
+tf admin graph | dot -Tpng | open -f -a Preview
+```
+
+## Analyze Project
+
+Analyze project health and statistics.
+
+```bash
+tf admin analyze [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+### Output
+
+```
+TrakFlow Project Analysis
+=========================
+
+Tasks: 47
+  - open: 12
+  - in_progress: 5
+  - blocked: 3
+  - closed: 27
+
+Types:
+  - task: 30
+  - bug: 8
+  - feature: 5
+  - epic: 3
+  - chore: 1
+
+Priorities:
+  - critical (0): 2
+  - high (1): 8
+  - medium (2): 25
+  - low (3): 10
+  - backlog (4): 2
+
+Dependencies:
+  - Total relationships: 34
+  - Orphan tasks: 5
+  - Circular dependencies: 0
+
+Labels:
+  - Most used: frontend (12), backend (8), urgent (3)
+  - Unused labels: 0
+
+Plans:
+  - Blueprints: 3
+  - Active workflows: 2
+  - Ephemeral workflows: 1
+
+Health Score: 85/100
+  - No circular dependencies ✓
+  - Few blocked tasks ✓
+  - Good label usage ✓
+  - Recommendation: Close stale tasks (5 tasks open > 30 days)
+```
+
+## Rebuild Cache
+
+Rebuild the SQLite cache from JSONL source.
+
+```bash
+tf admin rebuild
+```
+
+The cache is normally rebuilt automatically, but this forces a full rebuild.
+
+## Archive Tasks
+
+Archive old closed tasks.
+
+```bash
+tf admin archive [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--older-than` | Age threshold (default: 90d) |
+| `--status` | Archive tasks with status |
+| `--dry-run` | Show what would be archived |
+
+### Examples
+
+```bash
+# Archive tasks closed > 90 days ago
+tf admin archive
+
+# Archive tasks closed > 30 days ago
+tf admin archive --older-than 30d
+
+# Preview
+tf admin archive --dry-run
+```
+
+Archived tasks are marked with status `tombstone` and excluded from normal queries.
+
+## Garbage Collection
+
+Clean up ephemeral workflows and temporary data.
+
+```bash
+tf admin gc [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--older-than` | Age threshold (default: 7d) |
+| `--dry-run` | Show what would be deleted |
+
+### Examples
+
+```bash
+# Default cleanup
+tf admin gc
+
+# More aggressive
+tf admin gc --older-than 24h
+
+# Preview
+tf admin gc --dry-run
+```
+
+## Configuration
+
+### View Configuration
+
+```bash
+tf admin config
+```
+
+### Set Configuration
+
+```bash
+tf admin config KEY VALUE
+```
+
+### Examples
+
+```bash
+# View all settings
+tf admin config
+
+# Set default priority
+tf admin config default_priority 2
+
+# Set retention period
+tf admin config gc_retention 7d
+```
+
+## Validate Data
+
+Check data integrity.
+
+```bash
+tf admin validate
+```
+
+### Checks Performed
+
+- JSONL syntax validity
+- Required fields present
+- Valid status values
+- Valid priority values
+- Valid type values
+- Reference integrity (parent_id, dependencies)
+- No circular dependencies
+
+### Output
+
+```
+Validation Results
+==================
+
+✓ JSONL syntax: valid
+✓ Required fields: present
+✓ Status values: valid
+✓ Priority values: valid
+✓ Type values: valid
+✓ Parent references: valid
+✓ Dependency references: valid
+✓ No circular dependencies
+
+All checks passed!
+```
+
+## Backup and Restore
+
+### Create Backup
+
+```bash
+tf admin export -o "backup-$(date +%Y%m%d).jsonl"
+```
+
+### Restore from Backup
+
+```bash
+tf admin import backup-20240115.jsonl --replace
+tf admin rebuild
+```
+
+### Automated Backups
+
+Add to your git workflow:
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/bash
+cp .trak_flow/issues.jsonl .trak_flow/issues.jsonl.bak
+```

data/docs/cli/dependency-commands.md

@@ -0,0 +1,321 @@
+# Dependency Commands
+
+Commands for managing task dependencies and relationships.
+
+## Add Dependency
+
+Create a dependency between tasks.
+
+```bash
+tf dep add SOURCE TARGET [OPTIONS]
+```
+
+The SOURCE task blocks/relates-to the TARGET task.
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--type` | `-t` | Dependency type |
+
+### Dependency Types
+
+| Type | Description |
+|------|-------------|
+| `blocks` | Hard dependency (default) - SOURCE must complete before TARGET |
+| `related` | Soft link - Reference between related tasks |
+| `parent-child` | Hierarchical relationship |
+| `discovered-from` | Traceability - Track where a task originated |
+
+### Examples
+
+```bash
+# Design must complete before implementation
+tf dep add tf-design tf-implement
+
+# Explicit blocking dependency
+tf dep add tf-design tf-implement --type blocks
+
+# Related tasks (soft link)
+tf dep add tf-bug1 tf-bug2 -t related
+
+# Track origin
+tf dep add tf-issue123 tf-task456 -t discovered-from
+```
+
+## Remove Dependency
+
+Remove a dependency between tasks.
+
+```bash
+tf dep remove SOURCE TARGET
+```
+
+### Examples
+
+```bash
+tf dep remove tf-design tf-implement
+```
+
+## View Dependency Tree
+
+Show dependencies for a task.
+
+```bash
+tf dep tree TASK_ID [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--depth` | Maximum depth to display |
+| `--all` | Include all dependency types |
+
+### Output
+
+```
+tf-implement
+├── blocked by:
+│   └── tf-design (closed)
+│       └── tf-research (closed)
+└── blocks:
+    ├── tf-test (open)
+    │   └── tf-deploy (open)
+    └── tf-docs (open)
+```
+
+## Find Ready Tasks
+
+Find tasks with no open blocking dependencies.
+
+```bash
+tf ready [OPTIONS]
+```
+
+A task is "ready" when:
+- Status is `open`
+- All blocking dependencies are `closed`
+- Not a Plan (Plans can't be executed directly)
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--type` | `-t` | Filter by type |
+| `--priority` | `-p` | Filter by priority |
+| `--assignee` | `-a` | Filter by assignee |
+| `--label` | `-l` | Filter by label |
+| `--limit` | `-n` | Max results |
+
+### Examples
+
+```bash
+# All ready tasks
+tf ready
+
+# Ready bugs
+tf ready -t bug
+
+# Ready high-priority
+tf ready -p 0,1
+
+# Top 5 ready tasks
+tf ready -n 5
+```
+
+## Dependency Graph
+
+Generate a visual dependency graph.
+
+```bash
+tf admin graph [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--format` | Output format (dot, svg, png) |
+| `--output` | Output file path |
+| `--filter` | Filter expression |
+
+### Examples
+
+```bash
+# Generate DOT format to stdout
+tf admin graph
+
+# Generate SVG file
+tf admin graph --format svg --output deps.svg
+
+# Generate PNG file
+tf admin graph --format png --output deps.png
+
+# Filter by status
+tf admin graph --filter "status=open"
+```
+
+### DOT Output
+
+```dot
+digraph dependencies {
+  rankdir=LR;
+  node [shape=box];
+
+  "tf-design" [label="Design API" style=filled fillcolor=lightgreen];
+  "tf-implement" [label="Implement API" style=filled fillcolor=lightyellow];
+  "tf-test" [label="Write Tests"];
+  "tf-docs" [label="Update Docs"];
+
+  "tf-design" -> "tf-implement";
+  "tf-implement" -> "tf-test";
+  "tf-implement" -> "tf-docs";
+}
+```
+
+## Common Patterns
+
+### Sequential Workflow
+
+Tasks that must be done in order:
+
+```bash
+tf create "Step 1: Research"
+tf create "Step 2: Design"
+tf create "Step 3: Implement"
+tf create "Step 4: Test"
+
+tf dep add tf-step1 tf-step2
+tf dep add tf-step2 tf-step3
+tf dep add tf-step3 tf-step4
+```
+
+```
+Research → Design → Implement → Test
+```
+
+### Parallel Tasks with Sync Point
+
+Multiple tasks that converge:
+
+```bash
+tf create "Frontend work"
+tf create "Backend work"
+tf create "Integration"
+
+tf dep add tf-frontend tf-integration
+tf dep add tf-backend tf-integration
+```
+
+```
+Frontend ─┐
+          ├→ Integration
+Backend  ─┘
+```
+
+### Feature with Prerequisites
+
+A feature that requires setup first:
+
+```bash
+tf create "Add payment support" -t feature
+tf create "Set up Stripe account"
+tf create "Get API keys"
+tf create "Implement payment flow"
+
+tf dep add tf-stripe tf-implement
+tf dep add tf-keys tf-implement
+```
+
+```
+Stripe Account ─┐
+                ├→ Implement Payment
+Get API Keys  ──┘
+```
+
+### Epic with Subtasks
+
+Breaking down a large task:
+
+```bash
+tf create "User Authentication" -t epic
+tf create "Login page" --parent tf-auth
+tf create "Logout" --parent tf-auth
+tf create "Password reset" --parent tf-auth
+
+# Login before logout
+tf dep add tf-login tf-logout
+```
+
+## Validation
+
+TrakFlow validates dependencies:
+
+| Rule | Error |
+|------|-------|
+| No self-reference | "Cannot add dependency to itself" |
+| Tasks must exist | "Task not found: {id}" |
+| No cycles (optional) | "Creates circular dependency" |
+
+### Cycle Detection
+
+TrakFlow can detect circular dependencies:
+
+```bash
+# This would create a cycle: A → B → C → A
+tf dep add tf-c tf-a
+# Warning: Creates circular dependency
+```
+
+## Query Dependencies
+
+### Find Blocked Tasks
+
+```bash
+tf list --status blocked
+```
+
+### Find Tasks Blocking Others
+
+```bash
+tf dep tree tf-abc123
+```
+
+### Find Orphan Tasks
+
+Tasks with no dependencies:
+
+```bash
+tf admin analyze
+```
+
+## Impact on Operations
+
+### Closing Tasks
+
+When you close a task, dependent tasks may become ready:
+
+```bash
+tf close tf-design
+# tf-implement is now ready (if it was only blocked by tf-design)
+```
+
+### Reopening Tasks
+
+Reopening a task re-blocks its dependents:
+
+```bash
+tf reopen tf-design
+# tf-implement is blocked again
+```
+
+## Best Practices
+
+1. **Keep graphs simple** - Avoid overly complex chains
+2. **Use meaningful types** - Choose the right dependency type
+3. **Document why** - Add notes explaining dependencies
+4. **Review regularly** - Clean up stale dependencies
+5. **Check for cycles** - Before adding dependencies
+6. **Don't over-connect** - Not everything needs to be linked
+7. **Use labels for grouping** - Instead of `related` dependencies for categorization