# Install from source
go install go.devnw.com/canary/cmd/canary@latest

# Or clone and build
git clone https://github.com/devnw/canary.git
cd canary
make build

# Create a new project
canary init my-project

# This creates:
# .canary/
#   ├── memory/constitution.md      # Project principles
#   ├── templates/                   # Spec and plan templates
#   ├── specs/                       # Individual requirements
#   └── canary.db                    # Token database
# GAP_ANALYSIS.md                    # Requirement tracking

# Create a specification (AI agent)
/canary.specify Add user authentication with JWT tokens

/canary.plan CBIN-001

/canary.implement

# The primary functions like specify, plan, and implement can be run
# via the CLI but won't really do much for a user. They are designed
# for AI agents to call programmatically.

# User's can find all of the command options through the --help flag

# Build database and query progress
canary index
canary show CBIN-001
canary status CBIN-001

canary deps check CBIN-147        # Check if dependencies satisfied
canary deps graph CBIN-147 --status  # Visualize dependency tree
canary deps reverse CBIN-146      # What depends on this?
canary deps validate              # Check entire graph for cycles

# Scan codebase for tokens
canary scan --out status.json --csv status.csv

# Verify claims in GAP_ANALYSIS.md
canary scan --verify GAP_ANALYSIS.md --strict
# Exits with code 2 if:
# - Claimed requirements lack TESTED/BENCHED status
# - Tokens are stale (>30 days old)

canary show CBIN-105          # Display all tokens for a requirement
canary files CBIN-105         # List implementation files
canary status CBIN-105        # Show progress summary
canary grep "Authentication"  # Search tokens by pattern
canary list --status TESTED --aspect API  # Filtered listing

canary next                   # Get next priority requirement
canary next --prompt          # Generate AI agent prompt
canary implement CBIN-105     # Get implementation guidance
canary implement fuzzy        # Fuzzy match requirement

canary specify                # Create new specification
canary specify update CBIN-105  # Modify existing spec
canary plan CBIN-105          # Generate implementation plan

canary doc status CBIN-105 UserAuth     # Check doc currency
canary doc update --req CBIN-105        # Update doc hashes
canary doc report --show-undocumented   # Coverage report

canary deps check CBIN-147         # Check dependency satisfaction
canary deps graph CBIN-147 --status  # Show dependency tree
canary deps reverse CBIN-146       # Show reverse dependencies
canary deps validate               # Detect circular dependencies

# Global mode (default)
canary index                  # Uses ~/.canary/canary.db

# Local mode (project-specific)
canary index --local          # Uses .canary/canary.db

# Project management
canary projects list          # List all projects
canary projects add my-app    # Register project
canary projects switch my-app # Change context

# Morning routine
canary next                   # See what's next

# Review requirement
cat .canary/specs/CBIN-105-fuzzy-search/spec.md
cat .canary/specs/CBIN-105-fuzzy-search/plan.md

# Implement with test-first
# 1. Write failing test (RED)
# 2. Implement minimum code to pass (GREEN)
# 3. Refactor (REFACTOR)
# 4. Add CANARY tokens
# 5. Update STATUS field

# Verify progress
canary status CBIN-105
canary scan --verify GAP_ANALYSIS.md

# Check what's next
canary next

canary status CBIN-105
# Output:
# Requirement: CBIN-105 (Fuzzy Search)
# Total tokens: 8
# Status breakdown:
#   TESTED: 6 (75%)
#   IMPL: 1 (12.5%)
#   STUB: 1 (12.5%)
# Incomplete work:
#   - FuzzyRanking (Engine): IMPL → needs tests
#   - FuzzyConfig (API): STUB → not implemented

canary grep Authentication
# Searches across:
# - Requirement IDs
# - Feature names
# - Aspects
# - Owners
# - Files
# Returns tokens with file locations and line numbers

canary doc status CBIN-105 FuzzySearch
# Status: DOC_CURRENT (hash matches)

# After editing docs/user/search-guide.md:
canary doc status CBIN-105 FuzzySearch
# Status: DOC_STALE (hash mismatch)

canary doc update --req CBIN-105 --feature FuzzySearch
# Recalculates and updates DOC_HASH

canary deps graph CBIN-147 --status
# Output:
# CBIN-147 (Specification Dependencies)
# ├── ✅ CBIN-146 (Multi-Project Support)
# │   └── ✅ CBIN-129 (Database Migrations)
# └── ✅ CBIN-140:GapRepository,GapService
#     ├── ✅ CBIN-133:Engine
#     └── ❌ CBIN-135:Storage (STATUS=IMPL, needs tests)
#
# Summary: 3 satisfied, 1 blocking

canary init my-project
# Creates .github/instructions/ with CANARY workflow guidance

# Using GitHub Copilot CLI
gh copilot suggest "What is the CANARY token format?"

# Using VS Code Copilot Chat
# Ask: "@workspace What is the CANARY token format?"

# Customize your instructions
echo "# Custom Rule" >> .github/instructions/repository.md

# Re-run init - your customizations are preserved
canary init --local
# ⏭️  Skipping existing instruction file: repository.md

make build          # Build binary
make test           # Run tests
make bench          # Run benchmarks
make verify         # Self-verify with CANARY

# Scan the codebase
canary scan --root . --out status.json --csv status.csv

# Verify claims
canary scan --verify GAP_ANALYSIS.md --strict

# Check dependencies
canary deps validate

# Unit tests
go test ./...

# Integration tests
go test ./internal/specs -run Integration

# Benchmarks
go test ./internal/specs -bench=. -benchmem

# Acceptance tests
go test ./tools/canary/internal -run Acceptance -v