From f6909d822e5be7cedb4f67cb29445642779e0142 Mon Sep 17 00:00:00 2001 From: teernisse Date: Fri, 6 Mar 2026 11:15:28 -0500 Subject: [PATCH] docs: add documentation for me, related, and init --refresh commands Update CLAUDE.md and README.md with documentation for recently added features: CLAUDE.md: - Add robot mode examples for `lore --robot related` - Add example for `lore --robot init --refresh` README.md: - Add full documentation section for `lore me` command including all flags (--issues, --mrs, --mentions, --activity, --since, --project, --all, --user, --reset-cursor) and section descriptions - Add documentation section for `lore related` command with entity mode and query mode examples - Expand `lore init` section with --refresh flag documentation explaining project registration workflow - Add quick examples in the features section - Update version number in example output (0.9.2) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 7 +++++ README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 86 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 52b440d..3d4c548 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -652,6 +652,13 @@ lore --robot me --user jdoe lore --robot me --fields minimal lore --robot me --reset-cursor +# Find semantically related entities +lore --robot related issues 42 +lore --robot related "authentication flow" + +# Re-register projects from config +lore --robot init --refresh + # Agent self-discovery manifest (all commands, flags, exit codes, response schemas) lore robot-docs diff --git a/README.md b/README.md index 6c6fe16..2685e68 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,12 @@ lore timeline "deployment" # Timeline for a specific issue lore timeline issue:42 +# Personal work dashboard +lore me + +# Find semantically related entities +lore related issues 42 + # Why was this file changed? (file -> MR -> issue -> discussion) lore trace src/features/auth/login.ts @@ -406,6 +412,37 @@ Shows: users with touch counts (author vs. review), linked MR references. Defaul | `--as-of` | Score as if "now" is a past date (ISO 8601 or duration like 30d, expert mode only) | | `--include-bots` | Include bot users normally excluded via `scoring.excludedUsernames` | +### `lore me` + +Personal work dashboard showing open issues, authored/reviewing MRs, and activity feed. Designed for quick daily check-ins. + +```bash +lore me # Full dashboard +lore me --issues # Open issues section only +lore me --mrs # Authored + reviewing MRs only +lore me --activity # Activity feed only +lore me --mentions # Items you're @mentioned in (not assigned/authored/reviewing) +lore me --since 7d # Activity window (default: 30d) +lore me --project group/repo # Scope to one project +lore me --all # All synced projects (overrides default_project) +lore me --user jdoe # Override configured username +lore me --reset-cursor # Reset since-last-check cursor +``` + +The dashboard detects the current user from GitLab authentication and shows: +- **Issues section**: Open issues assigned to you +- **MRs section**: MRs you authored + MRs where you're a reviewer +- **Activity section**: Recent events (state changes, comments, etc.) on your items +- **Mentions section**: Items where you're @mentioned but not assigned/authoring/reviewing + +The `--since` flag affects only the activity section. Other sections show current state regardless of time window. + +#### Field Selection (Robot Mode) + +```bash +lore -J me --fields minimal # Compact output for agents +``` + ### `lore timeline` Reconstruct a chronological timeline of events matching a keyword query. The pipeline discovers related entities through cross-reference graph traversal and assembles a unified, time-ordered event stream. @@ -566,6 +603,26 @@ lore drift issues 42 --threshold 0.6 # Higher threshold (stricter) lore drift issues 42 -p group/repo # Scope to project ``` +### `lore related` + +Find semantically related entities via vector search. Accepts either an entity reference or a free text query. + +```bash +lore related issues 42 # Find entities related to issue #42 +lore related mrs 99 -p group/repo # Related to MR #99 in specific project +lore related "authentication flow" # Find entities matching free text query +lore related issues 42 -n 5 # Limit results +``` + +In entity mode (`issues N` or `mrs N`), the command embeds the entity's content and finds similar documents via vector similarity. In query mode (free text), the query is embedded directly. + +| Flag | Default | Description | +|------|---------|-------------| +| `-p` / `--project` | all | Scope to a specific project (fuzzy match) | +| `-n` / `--limit` | `10` | Maximum results | + +Requires embeddings to have been generated via `lore embed` or `lore sync`. + ### `lore cron` Manage cron-based automatic syncing (Unix only). Installs a crontab entry that runs `lore sync --lock -q` at a configurable interval. @@ -710,16 +767,35 @@ Displays: ### `lore init` -Initialize configuration and database interactively. +Initialize configuration and database interactively, or refresh the database to match an existing config. ```bash lore init # Interactive setup +lore init --refresh # Register new projects from existing config lore init --force # Overwrite existing config lore init --non-interactive # Fail if prompts needed ``` When multiple projects are configured, `init` prompts whether to set a default project (used when `-p` is omitted). This can also be set via the `--default-project` flag. +#### Refreshing Project Registration + +When projects are added to the config file, `lore sync` does not automatically pick them up because project discovery only happens during `lore init`. Use `--refresh` to register new projects without modifying the config file: + +```bash +lore init --refresh # Interactive: registers new projects, prompts to delete orphans +lore -J init --refresh # Robot mode: returns JSON with orphan info +``` + +The `--refresh` flag: +- Validates GitLab authentication before processing +- Registers new projects from config into the database +- Detects orphan projects (in database but removed from config) +- In interactive mode: prompts to delete orphans (default: No) +- In robot mode: returns JSON with orphan info without prompting + +Use `--force` to completely overwrite the config file with fresh interactive setup. The `--refresh` and `--force` flags are mutually exclusive. + In robot mode, `init` supports non-interactive setup via flags: ```bash @@ -788,7 +864,7 @@ Show version information including the git commit hash. ```bash lore version -# lore version 0.1.0 (abc1234) +# lore version 0.9.2 (571c304) ``` ## Robot Mode @@ -831,7 +907,7 @@ The `actions` array contains executable shell commands an agent can run to recov ### Field Selection -The `--fields` flag controls which fields appear in the JSON response, reducing token usage for AI agent workflows. Supported on `issues`, `mrs`, `notes`, `search`, `timeline`, and `who` list commands: +The `--fields` flag controls which fields appear in the JSON response, reducing token usage for AI agent workflows. Supported on `issues`, `mrs`, `notes`, `me`, `search`, `timeline`, and `who` list commands: ```bash # Minimal preset (~60% fewer tokens)