From 7b7d781a190d817da9f6e1a843e21504351b41d3 Mon Sep 17 00:00:00 2001 From: Taylor Eernisse Date: Fri, 30 Jan 2026 16:55:02 -0500 Subject: [PATCH] docs: Update exit codes, add config precedence and shell completions Exit code tables (README + AGENTS.md): - Add codes 14-16 (Ollama unavailable, model not found, embedding failed) - Add code 20 (Config not found, remapped from 2) - Clarify code 1 (now includes health check failed + not implemented) - Clarify code 2 (now exclusively usage/parsing errors from clap) New sections: - Configuration Precedence: CLI flags > env vars > config file > defaults - Shell Completions: bash, zsh, fish, powershell installation instructions Co-Authored-By: Claude (us.anthropic.claude-opus-4-5-20251101-v1:0) --- AGENTS.md | 15 +++++++++++++-- README.md | 35 +++++++++++++++++++++++++++++++++-- 2 files changed, 46 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 44adddf..dcaf8e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,8 +98,8 @@ Errors return structured JSON to stderr: | Code | Meaning | |------|---------| | 0 | Success | -| 1 | Internal error | -| 2 | Config not found | +| 1 | Internal error / health check failed / not implemented | +| 2 | Usage error (invalid flags or arguments) | | 3 | Config invalid | | 4 | Token not set | | 5 | GitLab auth failed | @@ -111,6 +111,17 @@ Errors return structured JSON to stderr: | 11 | Migration failed | | 12 | I/O error | | 13 | Transform error | +| 14 | Ollama unavailable | +| 15 | Ollama model not found | +| 16 | Embedding failed | +| 20 | Config not found | + +### Configuration Precedence + +1. CLI flags (highest priority) +2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`) +3. Config file (`~/.config/lore/config.json`) +4. Built-in defaults (lowest priority) ### Best Practices diff --git a/README.md b/README.md index c62c40e..33c6f32 100644 --- a/README.md +++ b/README.md @@ -406,8 +406,8 @@ Errors return structured JSON to stderr: | Code | Meaning | |------|---------| | 0 | Success | -| 1 | Internal error | -| 2 | Config not found | +| 1 | Internal error / health check failed / not implemented | +| 2 | Usage error (invalid flags or arguments) | | 3 | Config invalid | | 4 | Token not set | | 5 | GitLab auth failed | @@ -419,6 +419,19 @@ Errors return structured JSON to stderr: | 11 | Migration failed | | 12 | I/O error | | 13 | Transform error | +| 14 | Ollama unavailable | +| 15 | Ollama model not found | +| 16 | Embedding failed | +| 20 | Config not found | + +## Configuration Precedence + +Settings are resolved in this order (highest to lowest priority): + +1. CLI flags (`--robot`, `--config`, `--color`) +2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`) +3. Config file (`~/.config/lore/config.json`) +4. Built-in defaults ## Global Options @@ -428,6 +441,24 @@ lore --robot # Machine-readable JSON lore -J # JSON shorthand ``` +## Shell Completions + +Generate shell completions for tab-completion support: + +```bash +# Bash (add to ~/.bashrc) +lore completions bash > ~/.local/share/bash-completion/completions/lore + +# Zsh (add to ~/.zshrc: fpath=(~/.zfunc $fpath)) +lore completions zsh > ~/.zfunc/_lore + +# Fish +lore completions fish > ~/.config/fish/completions/lore.fish + +# PowerShell (add to $PROFILE) +lore completions powershell >> $PROFILE +``` + ## Database Schema Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables: