Significantly expand the README to serve as complete user documentation
for the CLI tool, reflecting the full CP1 implementation.
Configuration section:
- Add missing config options: heartbeatIntervalSeconds, primaryConcurrency,
dependentConcurrency, backupDir, embedding provider settings
- Document config file resolution order (CLI flag, env var, XDG, local)
- Add environment variables table with GITLAB_TOKEN, GI_CONFIG_PATH,
XDG_CONFIG_HOME, XDG_DATA_HOME, RUST_LOG
Commands section:
- Document --full flag for complete re-sync (resets cursors and watermarks)
- Add output descriptions for list, show, and count commands
- Document assignee filter with @ prefix normalization
- Add gi doctor checks explanation (config, db, GitLab auth, Ollama)
- Add gi sync-status output description
- Add placeholder documentation for backup and reset commands
Database schema section:
- Reformat as table with descriptions
- Add sync_runs, sync_cursors, app_locks, schema_version tables
- Note WAL mode and foreign keys enabled
Development section:
- Add RUST_LOG=gi=trace example for detailed logging
Current status section:
- Document CP1 scope (issues, discussions, incremental sync)
- List not-yet-implemented features (MRs, embeddings, backup/reset)
- Reference SPEC.md for full roadmap
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
README.md provides complete user documentation:
- Installation via cargo install or build from source
- Quick start guide with example commands
- Configuration file format with all options documented
- Full command reference for init, auth-test, doctor, ingest,
list, show, count, sync-status, migrate, and version
- Database schema overview covering projects, issues, milestones,
assignees, labels, discussions, notes, and raw payloads
- Development setup with test, lint, and debug commands
SPEC.md updated from original TypeScript planning document:
- Added note clarifying this is historical (implementation uses Rust)
- Updated sqlite-vss references to sqlite-vec (deprecated library)
- Added architecture overview with Technology Choices rationale
- Expanded project structure showing all planned modules
docs/prd/ contains detailed checkpoint planning:
- checkpoint-0.md: Initial project vision and requirements
- checkpoint-1.md: Revised planning after technology decisions
These documents capture the evolution from initial concept through
the decision to use Rust for performance and type safety.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
