Files

Taylor Eernisse 9b63671df9 docs: Update documentation for search pipeline and Phase A spec

- README.md: Add hybrid search and robot mode to feature list. Update
  quick start to use new noun-first CLI syntax (lore issues, lore mrs,
  lore search). Add embedding configuration section. Update command
  examples throughout.

- AGENTS.md: Update robot mode examples to new CLI syntax. Add search,
  sync, stats, and generate-docs commands to the robot mode reference.
  Update flag conventions (-n for limit, -s for state, -J for JSON).

- docs/prd/checkpoint-3.md: Major expansion with gated milestone
  structure (Gate A: lexical, Gate B: hybrid, Gate C: sync). Add
  prerequisite rename note, code sample conventions, chunking strategy
  details, and sqlite-vec rowid encoding scheme. Clarify that Gate A
  requires only SQLite + FTS5 with no sqlite-vec dependency.

- docs/phase-a-spec.md: New detailed specification for Gate A (lexical
  search MVP) covering document schema, FTS5 configuration, dirty
  queue mechanics, CLI interface, and acceptance criteria.

- docs/api-efficiency-findings.md: Analysis of GitLab API pagination
  behavior and efficiency observations from production sync runs.
  Documents the missing x-next-page header issue and heuristic fix.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-30 15:47:33 -05:00

2.8 KiB

Raw Blame History

AGENTS.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

TDD Requirements

Test-first development is mandatory:

RED - Write failing test first
GREEN - Minimal implementation to pass
REFACTOR - Clean up while green

Key Patterns

Find the simplest solution that meets all acceptance criteria. Use third party libraries whenever there's a well-maintained, active, and widely adopted solution (for example, date-fns for TS date math) Build extensible pieces of logic that can easily be integrated with other pieces. DRY principles should be loosely held. Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.

Third-Party Library Usage

If you aren't 100% sure how to use a third-party library, SEARCH ONLINE to find the latest documentation and mid-2025 best practices.

Gitlore Robot Mode

The lore CLI has a robot mode optimized for AI agent consumption with structured JSON output, meaningful exit codes, and TTY auto-detection.

Activation

# Explicit flag
lore --robot issues -n 10

# JSON shorthand (-J)
lore -J issues -n 10

# Auto-detection (when stdout is not a TTY)
lore issues | jq .

# Environment variable
LORE_ROBOT=1 lore issues

Robot Mode Commands

# List issues/MRs with JSON output
lore --robot issues -n 10
lore --robot mrs -s opened

# Show detailed entity info
lore --robot issues 123
lore --robot mrs 456 -p group/repo

# Count entities
lore --robot count issues
lore --robot count discussions --for mr

# Search indexed documents
lore --robot search "authentication bug"

# Check sync status
lore --robot status

# Run full sync pipeline
lore --robot sync

# Run ingestion only
lore --robot ingest issues

# Check environment health
lore --robot doctor

# Document and index statistics
lore --robot stats

Response Format

All commands return consistent JSON:

{"ok":true,"data":{...},"meta":{...}}

Errors return structured JSON to stderr:

{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'"}}

Exit Codes

Code	Meaning
0	Success
1	Internal error
2	Config not found
3	Config invalid
4	Token not set
5	GitLab auth failed
6	Resource not found
7	Rate limited
8	Network error
9	Database locked
10	Database error
11	Migration failed
12	I/O error
13	Transform error

Best Practices

Use lore --robot or lore -J for all agent interactions
Check exit codes for error handling
Parse JSON errors from stderr
Use -n / --limit to control response size
TTY detection handles piped commands automatically

2.8 KiB Raw Blame History