gitlore/docs/command-surface-analysis.md

Lore Command Surface Analysis

Date: 2026-02-26 Version: v0.9.1 (439c20e) Scope: Full command inventory, overlap analysis, consolidation proposals, robot-mode optimization proposals

---

1. Command Inventory

34 commands across 6 categories.

Category	Commands	Count
Entity Query	issues, mrs, notes, search, count	5
Intelligence	who (5 modes), timeline, related, drift, me, file-history, trace	7 (11 with who sub-modes)
Data Pipeline	sync, ingest, generate-docs, embed	4
Diagnostics	health, auth, doctor, status, stats	5
Setup	init, token, cron, migrate	4
Meta	version, completions, robot-docs	3

1.1 Entity Query Commands

issues (alias: issue)

List or show issues from local database.

Flag	Type	Default	Purpose
[IID]	positional	—	Omit to list, provide to show detail
-n, --limit	int	50	Max results
--fields	string	—	Select output columns (preset: minimal)
-s, --state	enum	—	opened|closed|all
-p, --project	string	—	Filter by project (fuzzy)
-a, --author	string	—	Filter by author username
-A, --assignee	string	—	Filter by assignee username
-l, --label	string[]	—	Filter by labels (AND logic, repeatable)
-m, --milestone	string	—	Filter by milestone title
--status	string[]	—	Filter by work-item status (COLLATE NOCASE, OR logic)
--since	duration/date	—	Filter by created date (7d, 2w, YYYY-MM-DD)
--due-before	date	—	Filter by due date
--has-due	flag	—	Show only issues with due dates
--sort	enum	updated	updated|created|iid
--asc	flag	—	Sort ascending
-o, --open	flag	—	Open first match in browser

DB tables: issues, projects, issue_assignees, issue_labels, labels Detail mode adds: discussions, notes, entity_references (closing MRs)

Robot output (list):

{
  "ok": true,
  "data": {
    "issues": [
      {
        "iid": 42, "title": "Fix auth", "state": "opened",
        "author_username": "jdoe", "labels": ["backend"],
        "assignees": ["jdoe"], "discussion_count": 3,
        "unresolved_count": 1, "created_at_iso": "...",
        "updated_at_iso": "...", "web_url": "...",
        "project_path": "group/repo",
        "status_name": "In progress"
      }
    ],
    "total_count": 150, "showing": 50
  },
  "meta": { "elapsed_ms": 40, "available_statuses": ["Open", "In progress", "Closed"] }
}

Minimal preset: iid, title, state, updated_at_iso

---

mrs (aliases: mr, merge-request, merge-requests)

List or show merge requests.

Flag	Type	Default	Purpose
[IID]	positional	—	Omit to list, provide to show detail
-n, --limit	int	50	Max results
--fields	string	—	Select output columns (preset: minimal)
-s, --state	enum	—	opened|merged|closed|locked|all
-p, --project	string	—	Filter by project
-a, --author	string	—	Filter by author
-A, --assignee	string	—	Filter by assignee
-r, --reviewer	string	—	Filter by reviewer
-l, --label	string[]	—	Filter by labels (AND)
--since	duration/date	—	Filter by created date
-d, --draft	flag	—	Draft MRs only
-D, --no-draft	flag	—	Exclude drafts
--target	string	—	Filter by target branch
--source	string	—	Filter by source branch
--sort	enum	updated	updated|created|iid
--asc	flag	—	Sort ascending
-o, --open	flag	—	Open in browser

DB tables: merge_requests, projects, mr_reviewers, mr_labels, labels, mr_assignees Detail mode adds: discussions, notes, mr_diffs

Minimal preset: iid, title, state, updated_at_iso

---

notes (alias: note)

List discussion notes/comments with fine-grained filters.

Flag	Type	Default	Purpose
-n, --limit	int	50	Max results
--fields	string	—	Preset: minimal
-a, --author	string	—	Filter by author
--note-type	enum	—	DiffNote|DiscussionNote
--contains	string	—	Body text substring filter
--note-id	int	—	Internal note ID
--gitlab-note-id	int	—	GitLab note ID
--discussion-id	string	—	Discussion ID filter
--include-system	flag	—	Include system notes
--for-issue	int	—	Notes on specific issue (requires -p)
--for-mr	int	—	Notes on specific MR (requires -p)
-p, --project	string	—	Scope to project
--since	duration/date	—	Created after
--until	date	—	Created before (inclusive)
--path	string	—	File path filter (exact or prefix with /)
--resolution	enum	—	any|unresolved|resolved
--sort	enum	created	created|updated
--asc	flag	—	Sort ascending
--open	flag	—	Open in browser

DB tables: notes, discussions, projects, issues, merge_requests

Minimal preset: id, author_username, body, created_at_iso

---

search (aliases: find, query)

Semantic + full-text search across indexed documents.

Flag	Type	Default	Purpose
<QUERY>	positional	required	Search query string
--mode	enum	hybrid	lexical|hybrid|semantic
--type	enum	—	issue|mr|discussion|note
--author	string	—	Filter by author
-p, --project	string	—	Scope to project
--label	string[]	—	Filter by labels (AND)
--path	string	—	File path filter
--since	duration/date	—	Created after
--updated-since	duration/date	—	Updated after
-n, --limit	int	20	Max results (max: 100)
--fields	string	—	Preset: minimal
--explain	flag	—	Show ranking breakdown
--fts-mode	enum	safe	safe|raw

DB tables: documents, documents_fts (FTS5), embeddings (vec0), document_labels, document_paths, projects

Robot output:

{
  "data": {
    "query": "authentication bug",
    "mode": "hybrid",
    "total_results": 15,
    "results": [
      {
        "document_id": 1234, "source_type": "issue",
        "title": "Fix SSO auth", "url": "...",
        "author": "jdoe", "project_path": "group/repo",
        "labels": ["auth"], "paths": ["src/auth/"],
        "snippet": "...matching text...",
        "score": 0.85,
        "explain": { "vector_rank": 2, "fts_rank": 1, "rrf_score": 0.85 }
      }
    ],
    "warnings": []
  }
}

Minimal preset: document_id, title, source_type, score

---

count

Count entities in local database.

Flag	Type	Default	Purpose
<ENTITY>	positional	required	issues|mrs|discussions|notes|events
-f, --for	enum	—	Parent type: issue|mr

DB tables: Conditional aggregation on issues, merge_requests, discussions, notes, event tables

Robot output:

{
  "data": {
    "entity": "merge_requests",
    "count": 1234,
    "breakdown": { "opened": 100, "closed": 50, "merged": 1084 }
  }
}

---

1.2 Intelligence Commands

who (People Intelligence)

Five sub-modes, dispatched by argument shape.

Mode	Trigger	Purpose
expert	who <path> or who --path <path>	Who knows about a code area?
workload	who @username	What is this person working on?
reviews	who @username --reviews	Review pattern analysis
active	who --active	Unresolved discussions needing attention
overlap	who --overlap <path>	Who else touches these files?

Shared flags:

Flag	Type	Default	Purpose
-p, --project	string	—	Scope to project
-n, --limit	int	varies	Max results (1-500)
--fields	string	—	Preset: minimal
--since	duration/date	—	Time window
--include-bots	flag	—	Include bot users
--include-closed	flag	—	Include closed issues/MRs
--all-history	flag	—	Query all history

Expert-only flags: --detail (per-MR breakdown), --as-of (score at point in time), --explain-score (score breakdown)

DB tables by mode:

Mode	Primary Tables
expert	notes (INDEXED BY idx_notes_diffnote_path_created), merge_requests, mr_reviewers
workload	issues, merge_requests, mr_reviewers
reviews	merge_requests, discussions, notes
active	discussions, notes, issues, merge_requests
overlap	notes, mr_file_changes, merge_requests

Robot output (expert):

{
  "data": {
    "mode": "expert",
    "result": {
      "experts": [
        { "username": "jdoe", "score": 42.5, "detail": { "mr_ids_author": [99, 101] } }
      ]
    }
  }
}

Minimal presets: expert: username, score | workload: iid, title, state | reviews: name, count, percentage | active: entity_type, iid, title, participants | overlap: username, touch_count

---

timeline

Reconstruct chronological event history for a topic/entity with cross-reference expansion.

Flag	Type	Default	Purpose
<QUERY>	positional	required	Search text or entity ref (issue:42, mr:99)
-p, --project	string	—	Scope to project
--since	duration/date	—	Filter events after
--depth	int	1	Cross-ref expansion depth (0=none)
--no-mentions	flag	—	Skip "mentioned" edges, keep "closes"/"related"
-n, --limit	int	100	Max events
--fields	string	—	Preset: minimal
--max-seeds	int	10	Max seed entities from search
--max-entities	int	50	Max expanded entities
--max-evidence	int	10	Max evidence notes

Pipeline: SEED -> HYDRATE -> EXPAND -> COLLECT -> RENDER

DB tables: issues, merge_requests, discussions, notes, entity_references, resource_state_events, resource_label_events, resource_milestone_events, documents (for search seeding)

Robot output:

{
  "data": {
    "query": "authentication", "event_count": 25,
    "seed_entities": [{ "type": "issue", "iid": 42, "project": "group/repo" }],
    "expanded_entities": [
      { "type": "mr", "iid": 99, "project": "group/repo", "depth": 1,
        "via": { "from": { "type": "issue", "iid": 42 }, "reference_type": "closes" } }
    ],
    "events": [
      {
        "timestamp": "2026-01-15T10:30:00Z", "entity_type": "issue",
        "entity_iid": 42, "project": "group/repo",
        "event_type": "state_changed", "summary": "Reopened",
        "actor": "jdoe", "is_seed": true,
        "evidence_notes": [{ "author": "jdoe", "snippet": "..." }]
      }
    ]
  },
  "meta": {
    "elapsed_ms": 150, "search_mode": "fts",
    "expansion_depth": 1, "include_mentions": true,
    "total_entities": 5, "total_events": 25
  }
}

Minimal preset: timestamp, type, entity_iid, detail

---

me (Personal Dashboard)

Personal work dashboard with issues, MRs, activity, and since-last-check inbox.

Flag	Type	Default	Purpose
--issues	flag	—	Open issues section only
--mrs	flag	—	MRs section only
--activity	flag	—	Activity feed only
--since	duration/date	30d	Activity window
-p, --project	string	—	Scope to one project
--all	flag	—	All synced projects
--user	string	—	Override configured username
--fields	string	—	Preset: minimal
--reset-cursor	flag	—	Clear since-last-check cursor

Sections (no flags = all): Issues, MRs authored, MRs reviewing, Activity feed, Inbox (since last check)

DB tables: issues, merge_requests, resource_state_events, projects, issue_labels, mr_labels

Robot output:

{
  "data": {
    "username": "jdoe",
    "summary": {
      "project_count": 3, "open_issue_count": 5,
      "authored_mr_count": 2, "reviewing_mr_count": 1,
      "needs_attention_count": 3
    },
    "since_last_check": {
      "cursor_iso": "2026-02-25T18:00:00Z",
      "total_event_count": 8,
      "groups": [
        {
          "entity_type": "issue", "entity_iid": 42,
          "entity_title": "Fix auth", "project": "group/repo",
          "events": [
            { "timestamp_iso": "...", "event_type": "comment",
              "actor": "reviewer", "summary": "New comment" }
          ]
        }
      ]
    },
    "open_issues": [
      { "project": "group/repo", "iid": 42, "title": "Fix auth",
        "state": "opened", "attention_state": "needs_attention",
        "status_name": "In progress", "labels": ["auth"],
        "updated_at_iso": "..." }
    ],
    "open_mrs_authored": [...],
    "reviewing_mrs": [...],
    "activity": [...]
  }
}

Minimal presets: Items: iid, title, attention_state, updated_at_iso | Activity: timestamp_iso, event_type, entity_iid, actor

---

file-history

Show which MRs touched a file, with linked discussions.

Flag	Type	Default	Purpose
<PATH>	positional	required	File path to trace
-p, --project	string	—	Scope to project
--discussions	flag	—	Include DiffNote snippets
--no-follow-renames	flag	—	Skip rename chain resolution
--merged	flag	—	Only merged MRs
-n, --limit	int	50	Max MRs

DB tables: mr_file_changes, merge_requests, notes (DiffNotes), projects

Robot output:

{
  "data": {
    "path": "src/auth/middleware.rs",
    "rename_chain": [
      { "previous_path": "src/auth.rs", "mr_iid": 55, "merged_at": "..." }
    ],
    "merge_requests": [
      { "iid": 99, "title": "Refactor auth", "state": "merged",
        "author": "jdoe", "merged_at": "...", "change_type": "modified" }
    ],
    "discussions": [
      { "discussion_id": 123, "mr_iid": 99, "author": "reviewer",
        "body_snippet": "...", "path": "src/auth/middleware.rs" }
    ]
  },
  "meta": { "elapsed_ms": 30, "total_mrs": 5, "renames_followed": true }
}

---

trace

File -> MR -> issue -> discussion chain to understand why code was introduced.

Flag	Type	Default	Purpose
<PATH>	positional	required	File path (future: :line suffix)
-p, --project	string	—	Scope to project
--discussions	flag	—	Include DiffNote snippets
--no-follow-renames	flag	—	Skip rename chain
-n, --limit	int	20	Max chains

DB tables: mr_file_changes, merge_requests, issues, discussions, notes, entity_references

Robot output:

{
  "data": {
    "path": "src/auth/middleware.rs",
    "resolved_paths": ["src/auth/middleware.rs", "src/auth.rs"],
    "trace_chains": [
      {
        "mr_iid": 99, "mr_title": "Refactor auth", "mr_state": "merged",
        "mr_author": "jdoe", "change_type": "modified",
        "merged_at_iso": "...", "web_url": "...",
        "issues": [42],
        "discussions": [
          { "discussion_id": 123, "author_username": "reviewer",
            "body_snippet": "...", "path": "src/auth/middleware.rs" }
        ]
      }
    ]
  },
  "meta": { "tier": "api_only", "total_chains": 3, "renames_followed": 1 }
}

---

related

Find semantically related entities via vector search.

Flag	Type	Default	Purpose
<QUERY_OR_TYPE>	positional	required	Entity type (issues, mrs) or free text
[IID]	positional	—	Entity IID (required with entity type)
-n, --limit	int	10	Max results
-p, --project	string	—	Scope to project

Two modes:

• Entity mode: related issues 42 — find entities similar to issue #42
• Query mode: related "auth flow" — find entities matching free text

DB tables: documents, embeddings (vec0), projects

Requires: Ollama running (for query mode embedding)

---

drift

Detect discussion divergence from original intent.

Flag	Type	Default	Purpose
<ENTITY_TYPE>	positional	required	Currently only issues
<IID>	positional	required	Entity IID
--threshold	f32	0.4	Similarity threshold (0.0-1.0)
-p, --project	string	—	Scope to project

DB tables: issues, discussions, notes, embeddings

Requires: Ollama running

---

1.3 Data Pipeline Commands

sync (Full Pipeline)

Complete sync: ingest -> generate-docs -> embed.

Flag	Type	Default	Purpose
--full	flag	—	Full re-sync (reset cursors)
-f, --force	flag	—	Override stale lock
--no-embed	flag	—	Skip embedding
--no-docs	flag	—	Skip doc generation
--no-events	flag	—	Skip resource events
--no-file-changes	flag	—	Skip MR file changes
--no-status	flag	—	Skip work-item status enrichment
--dry-run	flag	—	Preview without changes
-t, --timings	flag	—	Show timing breakdown
--lock	flag	—	Acquire file lock
--issue	int[]	—	Surgically sync specific issues (repeatable)
--mr	int[]	—	Surgically sync specific MRs (repeatable)
-p, --project	string	—	Required with --issue/--mr
--preflight-only	flag	—	Validate without DB writes

Stages: Ingest -> GraphQL status enrichment -> Generate docs -> Embed

ingest

Fetch data from GitLab API only.

Flag	Type	Default	Purpose
[ENTITY]	positional	—	issues or mrs (omit for all)
-p, --project	string	—	Filter to single project
-f, --force	flag	—	Override stale lock
--full	flag	—	Full re-sync
--dry-run	flag	—	Preview

generate-docs

Create searchable documents from ingested data.

Flag	Type	Default	Purpose
--full	flag	—	Full rebuild
-p, --project	string	—	Single project rebuild

embed

Generate vector embeddings via Ollama.

Flag	Type	Default	Purpose
--full	flag	—	Re-embed all
--retry-failed	flag	—	Retry failed embeddings

Requires: Ollama running with nomic-embed-text

---

1.4 Diagnostic Commands

health

Quick pre-flight check. Exit 0 = healthy, exit 19 = unhealthy.

Checks: config found, DB found, schema current.

{
  "data": {
    "healthy": true,
    "config_found": true, "db_found": true,
    "schema_current": true, "schema_version": 28
  }
}

auth

Verify GitLab authentication.

Checks: token set, GitLab reachable, user identity.

doctor

Comprehensive environment check.

Checks: config validity, token, GitLab connectivity, DB health, migration status, Ollama availability, model status.

{
  "data": {
    "config": { "valid": true, "path": "..." },
    "token": { "set": true, "gitlab": { "reachable": true, "user": "jdoe" } },
    "database": { "exists": true, "version": 28, "tables": 25 },
    "ollama": { "available": true, "model_ready": true }
  }
}

status (alias: st)

Show sync state per project (last sync times, cursors).

{
  "data": {
    "projects": [
      { "project_path": "group/repo", "last_synced_at": "...",
        "document_count": 5000, "discussion_count": 2000 }
    ]
  }
}

stats (alias: stat)

Document and index statistics with optional integrity checks.

Flag	Type	Default	Purpose
--check	flag	—	Run integrity checks
--repair	flag	—	Fix issues (implies --check)
--dry-run	flag	—	Preview repairs

{
  "data": {
    "documents": { "total": 61652, "issues": 5000, "mrs": 2000, "notes": 50000 },
    "embeddings": { "total": 80000, "synced": 79500, "pending": 500 },
    "fts": { "total_docs": 61652 },
    "queues": { "pending": 0, "in_progress": 0, "failed": 0 },
    "integrity": { "ok": true }
  }
}

---

1.5 Setup Commands

Command	Purpose
init	Initialize config + DB (interactive or --non-interactive)
token set	Store GitLab token (interactive or --token)
token show	Display token (--unmask for full)
cron install	Schedule auto-sync (--interval minutes, default 8)
cron uninstall	Remove cron job
cron status	Check cron installation
migrate	Run pending DB migrations

1.6 Meta Commands

Command	Purpose
version	Show version string
completions <shell>	Generate shell completions (bash/zsh/fish/powershell)
robot-docs	Machine-readable command manifest (--brief for smaller)

---

2. Shared Data Source Map

Which DB tables power which commands. Higher overlap = more consolidation potential.

Table	Read By
issues	issues, me, who-workload, search, timeline, trace, count, stats
merge_requests	mrs, me, who-workload, search, timeline, trace, file-history, count, stats
notes	notes, issues-detail, mrs-detail, who-expert, who-active, search, timeline, trace, file-history
discussions	notes, issues-detail, mrs-detail, who-active, who-reviews, timeline, trace
entity_references	trace, timeline
mr_file_changes	trace, file-history, who-overlap
resource_state_events	timeline, me-activity
resource_label_events	timeline
resource_milestone_events	timeline
documents + FTS	search, stats
embeddings	search, related, drift
document_labels	search
document_paths	search
issue_labels	issues, me
mr_labels	mrs, me
mr_reviewers	mrs, who-expert, who-workload
issue_assignees	issues, me
sync_cursors	status
dirty_sources	stats

---

3. Command Network Graph

3.1 Data Flow (command A feeds into command B)

                    ┌─────────┐
                    │ search  │─────────────────────────────┐
                    └────┬────┘                             │
                         │ iid                              │ topic
                    ┌────▼────┐                        ┌────▼─────┐
              ┌─────│ issues  │◄───────────────────────│ timeline │
              │     │ mrs     │ (detail)               └──────────┘
              │     └────┬────┘                             ▲
              │          │ iid                              │ entity ref
              │     ┌────▼────┐     ┌──────────────┐       │
              │     │ related │     │ file-history  │───────┘
              │     │ drift   │     └──────┬───────┘
              │     └─────────┘            │ MR iids
              │                       ┌────▼────┐
              │                       │  trace  │──── issues (linked)
              │                       └────┬────┘
              │                            │ paths
              │                       ┌────▼────┐
              │                       │   who   │
              │                       │ (expert)│
              │                       └─────────┘
              │
         file paths                   ┌─────────┐
              │                       │   me    │──── issues, mrs (dashboard)
              ▼                       └─────────┘
        ┌──────────┐                       ▲
        │  notes   │                       │ (same data)
        └──────────┘                  ┌────┴──────┐
                                      │who workload│
                                      └───────────┘

3.2 Shared-Data Clusters

Commands that read from the same primary tables form natural clusters:

Cluster A: Issue/MR entities — issues, mrs, me, who workload, count All read from issues + merge_requests with similar filter patterns.

Cluster B: Notes/discussions — notes, issues detail, mrs detail, who expert, who active, timeline All traverse the discussions -> notes join path.

Cluster C: File genealogy — trace, file-history, who overlap All use mr_file_changes with rename chain BFS.

Cluster D: Semantic/vector — search, related, drift All use documents + embeddings (require Ollama).

Cluster E: Diagnostics — health, auth, doctor, status, stats All check system state at various granularities.

---

4. Overlap Analysis

4.1 High Overlap (>70% functional duplication)

who workload vs me

Dimension	who @user (workload)	me --user @user
Assigned issues	Yes	Yes
Authored MRs	Yes	Yes
Reviewing MRs	Yes	Yes
Attention state	No	Yes
Activity feed	No	Yes
Since-last-check inbox	No	Yes
Cross-project	Yes	Yes

Verdict: who workload is a strict subset of me. 85% overlap.

health vs doctor

Check	health	doctor
Config found	Yes	Yes
DB exists	Yes	Yes
Schema current	Yes	Yes
Token valid	No	Yes
GitLab reachable	No	Yes
Ollama available	No	Yes

Verdict: health is a strict subset of doctor. 90% overlap (but health is fast pre-flight with different exit code semantics).

file-history vs trace

Feature	file-history	trace
Find MRs for file	Yes	Yes
Rename chain BFS	Yes	Yes
DiffNote discussions	--discussions	--discussions
Follow to linked issues	No	Yes
--merged filter	Yes	No

Verdict: trace is a superset minus the --merged flag. 75% overlap.

related (query mode) vs search --mode semantic

Feature	related "text"	search "text" --mode semantic
Vector similarity	Yes	Yes
FTS component	No	No (semantic mode)
Filters (labels, author, since)	No	Yes
Explain ranking	No	Yes
Field selection	No	Yes

Verdict: related query mode is search --mode semantic without filters. 80% overlap.

4.2 Medium Overlap (40-70%)

Pair	Overlap %	Notes
who expert vs who overlap	~50%	Both answer "who works on this file"; expert has decay scoring, overlap has raw counts
timeline vs trace	~45%	Both follow entity_references; timeline is entity-centric, trace is file-centric
auth vs doctor	~100% of auth	auth is fully contained within doctor
count vs stats	~40%	Both answer "how much data" at different layers (entity vs document index)
notes vs issues/mrs detail	~50%	Detail embeds notes inline; notes adds independent filtering

4.3 No Significant Overlap

Command	Reason
drift	Unique: semantic divergence detection
timeline	Unique: multi-entity chronological reconstruction
search (hybrid)	Unique: FTS + vector combined ranking
me (inbox)	Unique: cursor-based since-last-check
who expert	Unique: half-life decay scoring with signal types
who reviews	Unique: review pattern analysis

---

5. Agent Workflow Analysis

5.1 Common Workflows with Round-Trip Counts

Flow 1: "What should I work on?" — 4 round trips

me                          → dashboard overview
issues <iid> -p proj       → detail on picked issue
trace src/relevant/file.rs  → understand code context
who src/relevant/file.rs    → find domain experts

Flow 2: "What happened with this feature?" — 3 round trips

search "feature name"       → find relevant entities
timeline "feature name"     → reconstruct chronological history
related issues 42           → discover connected work

Flow 3: "Why was this code changed?" — 3 round trips

trace src/file.rs           → file -> MR -> issue chain
issues <iid> -p proj       → full issue detail
timeline "issue:42"         → full history with cross-refs

Flow 4: "Is the system healthy?" — 2-4 round trips

health                      → quick pre-flight
doctor                      → detailed diagnostics
status                      → sync state per project
stats                       → document/index health

Flow 5: "Who can review this?" — 2-3 round trips

who src/auth/               → find file experts
who @jdoe --reviews         → check reviewer's patterns

Flow 6: "Find and understand an issue" — 4 round trips

search "query"              → discover entities
issues <iid>                → full detail with discussions
timeline "issue:42"         → chronological context
related issues 42           → connected entities

5.2 Token Cost Profiles

Measured typical response sizes in robot mode:

Command	Typical Tokens	Notes
me (full)	2000-5000	Scales with open items
me --fields minimal	500-1500	Good reduction
issues (list, n=50)	1500-3000	Labels inflate it
issues <iid> (detail)	1000-8000	Discussions dominate
timeline (limit=100)	2000-6000	Events + evidence
search (n=20)	1000-3000	Snippets dominate
who expert	300-800	Compact
trace	500-2000	Depends on chain depth
health	~100	Very compact
stats	~500	Fixed structure

---

6. Proposals

6.1 Command Consolidations

A. Absorb file-history into trace --shallow

Rationale: 75% code overlap. Both do rename chain BFS on mr_file_changes, both optionally include DiffNote discussions. trace just follows entity_references one step further.

Change:

• trace <path> — full chain: file -> MR -> issue -> discussions (existing)
• trace <path> --shallow — MR-only, no issue chain (replaces file-history)
• Move --merged flag from file-history to trace
• Deprecate file-history with alias redirect

Impact: -1 command. No functionality lost.

B. Absorb auth into doctor

Rationale: auth checks token + GitLab connectivity. doctor checks the same plus DB + Ollama. auth is 100% contained within doctor.

Change:

• doctor — full check (existing)
• doctor --auth — token + GitLab only (replaces auth)
• Keep health separate (fast pre-flight, different exit code contract)
• Deprecate auth with alias redirect

Impact: -1 command. health stays because its ~50ms pre-flight with exit 0/19 contract is valuable for scripting.

C. Remove related query-mode, keep entity-mode

Rationale: related "auth flow" is functionally identical to search "auth flow" --mode semantic but with fewer filter options.

Change:

• related issues 42 — entity-seeded mode (keep, it's unique)
• related "free text" — print deprecation, suggest search --mode semantic
• Eventually remove query-mode entirely

Impact: -1 mode. Entity-seeded mode stays because it seeds from a specific entity's embedding rather than generating a new one.

D. Merge who overlap into who expert output

Rationale: who overlap reports who touches a file (raw count). who expert reports who knows a file (scored). Overlap is strictly less information.

Change:

• who <path> (expert) adds touch_count and last_touch_at fields to each expert row
• who --overlap <path> becomes an alias for who <path> --fields username,touch_count
• Deprecate --overlap flag with redirect

Impact: -1 sub-mode. Agents get both perspectives in one call.

E. Merge count and status into stats

Rationale: Three commands answer "how much data do I have?":

• count issues — entity counts with state breakdown
• status — sync cursor positions per project
• stats — document/index counts + integrity

Change:

• stats — document/index health (existing)
• stats --entities — adds entity counts (replaces count)
• stats --sync — adds sync cursor positions (replaces status)
• stats --all — everything
• Bare stats keeps current behavior (documents + queues + integrity)
• Deprecate count and status with alias redirects

Impact: -2 commands. Progressive disclosure via flags.

Consolidation Summary

Before	After	Commands Removed
file-history, trace	trace (+ --shallow)	-1
auth, doctor	doctor (+ --auth)	-1
related query-mode	search --mode semantic	-1 mode
who overlap, who expert	who expert (+ touch_count)	-1 sub-mode
count, status, stats	stats (+ --entities, --sync)	-2

Total: 34 commands -> 29 commands (5 fewer entry points for agents to learn).

---

6.2 Robot-Mode Optimizations

These are additive changes that reduce round trips and token waste without removing commands.

A. --include flag for embedded sub-queries

The single highest-impact optimization. Agents constantly fetch an entity and then immediately need related context.

Syntax:

lore -J issues 42 -p proj --include timeline,related
lore -J mrs 99 -p proj --include timeline,trace
lore -J trace src/auth/ -p proj --include experts
lore -J me --include detail

Response shape (embedded data uses _ prefix):

{
  "ok": true,
  "data": {
    "iid": 42, "title": "Fix auth", "state": "opened",
    "discussions": [...],
    "_timeline": {
      "event_count": 15,
      "events": [...]
    },
    "_related": {
      "similar_entities": [...]
    }
  }
}

Include matrix (which includes are valid on which commands):

Base Command	Valid Includes	Default Limits
issues <iid>	timeline, related, trace	20 events, 5 related, 5 chains
mrs <iid>	timeline, related, file-changes	20 events, 5 related
trace <path>	experts, timeline	5 experts, 20 events
me	detail (inline top-N item details)	3 items detailed
search	detail (inline top-N result details)	3 results detailed

Round-trip savings:

Workflow	Before	After	Savings
Understand an issue	4 calls	1 call	75%
Why was code changed	3 calls	1 call	67%
Find and understand	4 calls	2 calls	50%

Implementation notes:

• Each include runs its sub-query with reduced limits (configurable via --include-limit)
• Sub-query errors are non-fatal: returned as "_timeline_error": "Ollama unavailable" instead of failing the whole request
• --fields minimal applies to included data too
• Timing breakdown in meta: "_timeline_ms": 45, "_related_ms": 120

B. --batch flag for multi-entity detail lookups

After search/timeline, agents typically need detail on multiple entities:

# Before: N round trips
lore -J issues 42 -p proj
lore -J issues 55 -p proj
lore -J issues 71 -p proj

# After: 1 round trip
lore -J issues --batch 42,55,71 -p proj

Response:

{
  "data": {
    "results": [
      { "iid": 42, "title": "Fix auth", ... },
      { "iid": 55, "title": "Add SSO", ... },
      { "iid": 71, "title": "Token refresh", ... }
    ],
    "errors": []
  }
}

Constraints:

• Max 20 IIDs per batch
• Errors for individual items don't fail the batch
• Works with --include for maximum efficiency

C. --depth control on me

The me command returns everything by default, which is token-wasteful when an agent just wants to check "do I have work?".

# Counts only (~100 tokens)
lore -J me --depth counts

# Counts + titles (~400 tokens)
lore -J me --depth titles

# Full (current behavior, 2000+ tokens)
lore -J me --depth full

Depth levels:

Level	Returns	Typical Tokens
counts	summary block only	~100
titles	summary + item lists (iid, title, attention_state only)	~400
full	Everything including discussions, activity, inbox	~2000+

D. Composite context command

Purpose-built for the most common agent workflow: "give me everything I need to understand this entity."

lore -J context issues 42 -p proj
lore -J context mrs 99 -p proj

Equivalent to:

lore -J issues 42 -p proj --include timeline,related

But with optimized defaults:

• Timeline limited to 20 most recent events
• Related limited to top 5
• Discussions truncated after 5 threads
• Evidence notes capped at 3

Response: Same shape as issues <iid> --include timeline,related but with tighter defaults.

Rationale: Rather than teaching agents the --include syntax, provide a single "give me full context" command.

E. --max-tokens response budget

Let the agent cap response size. The server truncates arrays, omits low-priority fields, and uses shorter representations to stay within budget.

lore -J me --max-tokens 500
lore -J timeline "feature" --max-tokens 1000
lore -J context issues 42 --max-tokens 2000

Truncation strategy (in priority order):

1. Apply --fields minimal if not already set
2. Reduce array lengths (newest/highest-score items survive)
3. Truncate string fields (description, snippets)
4. Omit null/empty fields
5. Drop included sub-queries (if using --include)

Meta includes truncation notice:

{
  "meta": {
    "elapsed_ms": 50,
    "truncated": true,
    "original_tokens": 3500,
    "budget_tokens": 1000,
    "dropped": ["_related", "discussions[5:]"]
  }
}

F. --format tsv for maximum token efficiency

Beyond JSON, offer a TSV mode for list commands where structured data is simple:

lore -J issues --format tsv --fields iid,title,state -n 10

Output:

iid	title	state
42	Fix auth	opened
55	Add SSO	opened
71	Token refresh	closed

Estimated savings: ~60-70% fewer tokens vs JSON for list responses.

Applicable to: issues (list), mrs (list), notes (list), who expert, count.

Not applicable to: Detail views, timeline, search (nested structures).

---

6.3 Robot-Mode Optimization Impact Matrix

Optimization	Effort	Round-Trip Savings	Token Savings	Breaking?
--include flag	High	50-75%	Moderate	No (additive)
--batch flag	Medium	N-1 per batch	Moderate	No (additive)
--depth on me	Low	None	60-80%	No (additive)
context command	Medium	67-75%	Moderate	No (additive)
--max-tokens	High	None	Variable, up to 80%	No (additive)
--format tsv	Medium	None	60-70% on lists	No (additive)

---

7. Priority Ranking

Ordered by impact on robot-mode efficiency (round-trip reduction x token savings x implementation ease):

Priority	Proposal	Category	Effort	Impact
P0	--include flag	Robot optimization	High	Eliminates 2-3 round trips per workflow
P0	--depth on me	Robot optimization	Low	60-80% token reduction on most-used command
P1	--batch for detail views	Robot optimization	Medium	Eliminates N+1 after search/timeline
P1	Absorb file-history into trace	Consolidation	Low	Cleaner surface, shared code
P1	Merge who overlap into who expert	Consolidation	Low	-1 round trip in review flows
P2	context composite command	Robot optimization	Medium	Single entry point for understanding entities
P2	Merge count+status into stats	Consolidation	Medium	-2 commands, progressive disclosure
P2	Absorb auth into doctor	Consolidation	Low	-1 command
P2	Remove related query-mode	Consolidation	Low	-1 confusing choice
P3	--max-tokens budget	Robot optimization	High	Flexible but hard to implement well
P3	--format tsv	Robot optimization	Medium	High savings but limited applicability

---

8. Appendix: Robot Output Envelope

All robot-mode responses follow:

{
  "ok": true,
  "data": { /* command-specific */ },
  "meta": { "elapsed_ms": 42 }
}

Errors (to stderr):

{
  "error": {
    "code": "CONFIG_NOT_FOUND",
    "message": "Configuration file not found",
    "suggestion": "Run 'lore init'",
    "actions": ["lore init"]
  }
}

Exit codes: 0 (success), 1 (internal), 2 (usage), 3 (config invalid), 4 (token missing), 5 (auth failed), 6 (resource not found), 7 (rate limited), 8 (network), 9 (DB locked), 10 (DB error), 11 (migration), 12 (I/O), 13 (transform), 14 (Ollama unavailable), 15 (model missing), 16 (embedding failed), 17 (not found), 18 (ambiguous match), 19 (health failed), 20 (config not found).

---

9. Appendix: Field Selection Presets

The --fields flag supports both presets and custom field lists:

lore -J issues --fields minimal              # Preset
lore -J mrs --fields iid,title,state,draft   # Custom

Command	Minimal Preset Fields
issues (list)	iid, title, state, updated_at_iso
mrs (list)	iid, title, state, updated_at_iso
notes (list)	id, author_username, body, created_at_iso
search	document_id, title, source_type, score
timeline	timestamp, type, entity_iid, detail
who expert	username, score
who workload	iid, title, state
who reviews	name, count, percentage
who active	entity_type, iid, title, participants
who overlap	username, touch_count
me (items)	iid, title, attention_state, updated_at_iso
me (activity)	timestamp_iso, event_type, entity_iid, actor