From 42a4bca6dfa1abec825df820caf075ec3074b2dd Mon Sep 17 00:00:00 2001 From: Taylor Eernisse Date: Thu, 5 Feb 2026 11:22:50 -0500 Subject: [PATCH] docs: Update README and AGENTS.md with new features and options README.md: - Add cross-reference tracking feature description - Add resource event history feature description - Add observability feature description (verbosity, JSON logs, metrics) - Document --no-events flag for sync command - Add sync timing/progress bar behavior note - Document verbosity flags (-v, -vv, -vvv) - Document --log-format json option - Add new database tables to schema reference: - resource_state_events - resource_label_events - resource_milestone_events - entity_references AGENTS.md: - Add --no-events example for sync command - Document verbosity flags (-v, -vv, -vvv) - Document --log-format json option Co-Authored-By: Claude Opus 4.5 --- AGENTS.md | 5 +++++ README.md | 14 ++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b427fd0..a239495 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -633,6 +633,9 @@ lore --robot status # Run full sync pipeline lore --robot sync +# Run sync without resource events +lore --robot sync --no-events + # Run ingestion only lore --robot ingest issues @@ -712,6 +715,8 @@ Errors return structured JSON to stderr: - Use `-n` / `--limit` to control response size - Use `-q` / `--quiet` to suppress progress bars and non-essential output - Use `--color never` in non-TTY automation for ANSI-free output +- Use `-v` / `-vv` / `-vvv` for increasing verbosity (debug/trace logging) +- Use `--log-format json` for machine-readable log output to stderr - TTY detection handles piped commands automatically - Use `lore --robot health` as a fast pre-flight check before queries - The `-p` flag supports fuzzy project matching (suffix and substring) diff --git a/README.md b/README.md index b203fa1..0297558 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,10 @@ Local GitLab data management with semantic search. Syncs issues, MRs, discussion - **Hybrid search**: Combines FTS5 lexical search with Ollama-powered vector embeddings via Reciprocal Rank Fusion - **Raw payload storage**: Preserves original GitLab API responses for debugging - **Discussion threading**: Full support for issue and MR discussions including inline code review comments +- **Cross-reference tracking**: Automatic extraction of "closes", "mentioned" relationships between MRs and issues +- **Resource event history**: Tracks state changes, label events, and milestone events for issues and MRs - **Robot mode**: Machine-readable JSON output with structured errors and meaningful exit codes +- **Observability**: Verbosity controls, JSON log format, structured metrics, and stage timing ## Installation @@ -254,8 +257,11 @@ lore sync --full # Reset cursors, fetch everything lore sync --force # Override stale lock lore sync --no-embed # Skip embedding step lore sync --no-docs # Skip document regeneration +lore sync --no-events # Skip resource event fetching ``` +The sync command displays animated progress bars for each stage and outputs timing metrics on completion. In robot mode (`-J`), detailed stage timing is included in the JSON response. + ### `lore ingest` Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings). @@ -478,6 +484,10 @@ lore -J # JSON shorthand lore --color never # Disable color output lore --color always # Force color output lore -q # Suppress non-essential output +lore -v # Debug logging +lore -vv # More verbose debug logging +lore -vvv # Trace-level logging +lore --log-format json # JSON-formatted log output to stderr ``` Color output respects `NO_COLOR` and `CLICOLOR` environment variables in `auto` mode (the default). @@ -518,6 +528,10 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables: | `mr_reviewers` | Many-to-many MR-reviewer relationships | | `discussions` | Issue/MR discussion threads | | `notes` | Individual notes within discussions (with system note flag and DiffNote position data) | +| `resource_state_events` | Issue/MR state change history (opened, closed, merged, reopened) | +| `resource_label_events` | Label add/remove events with actor and timestamp | +| `resource_milestone_events` | Milestone add/remove events with actor and timestamp | +| `entity_references` | Cross-references between entities (MR closes issue, mentioned in, etc.) | | `documents` | Extracted searchable text for FTS and embedding | | `documents_fts` | FTS5 full-text search index | | `embeddings` | Vector embeddings for semantic search |