@merittdev/horus 0.20.0 → 0.21.0

package/README.md

@@ -78,10 +78,8 @@ Trace reconstruction is not shipped yet. Connectors are read-only and project-sc
 ## Example output (illustrative)
 
 ```bash
-horus investigate \
-  --project atlas-payments \
-  --env production \
-  "checkout latency spike"
+cd ~/code/atlas-payments
+horus investigate --env production "checkout latency spike"
 ```
 
 ```text
@@ -113,7 +111,9 @@ Hint: checkout latency spike
 
 **Local-first** — Connectors read from your own clusters, not a hosted black box.
 
-**Project-scoped** — Every investigation belongs to a specific project and environment.
+**Project-scoped** — The repo you run in (its `.horus/config.json`) is the project identity; `--config <path>` targets another repo.
+
+**Agent-ready** — Every investigation/analysis command takes `--json` (compact by default, `--full` for the raw structure) with a `nextSteps` array to chain from. `horus packet` builds a compact, honesty-framed briefing sized for an agent's context window.
 
 ## Capabilities
 
@@ -312,35 +312,48 @@ horus investigate --help
 
 | Command | What it does |
 | --- | --- |
-| `horus status [--project --env]` | Per-project/env connector-health matrix |
+| `horus status [--env]` | Per-project/env connector-health matrix |
 | `horus connect <type>` | Add/update a runtime connector — `elasticsearch` / `mongodb` / `postgres` / `sentry` / `axiom` / `grafana` / `redis` (plus `ai` to configure an AI provider) |
-| `horus init --project <p> --env <e>` | Build the queue map (stitcher) for a project |
+| `horus init [--env <e>]` | Set up the current repo: config, source-intelligence host, index, queue map |
 | `horus hosts [--reap]` | List source-intelligence hosts and live status; `--reap` stops orphaned hosts |
 | `horus stop [--all]` | Stop this repo's source-intelligence host (`--all` stops every host) |
-| `horus investigate --project <p> --env <e> "<hint>"` | Full deterministic investigation report |
-| `horus logs [service] --project <p> --env <e>` | Error-signature evidence (`--raw` for lines) |
-| `horus state --project <p> --env <e>` | MongoDB application-state evidence (read-only) |
-| `horus metrics [hint] --project <p> --env <e>` | Grafana metrics evidence |
-| `horus explain <symbol>` · `blast-radius` · `architecture` · `what-changed` | Source-aware code intelligence (requires source intelligence backend) |
+| `horus investigate --env <e> "<hint>"` | Full deterministic investigation report (`--format json` for agents) |
+| `horus packet <hint\|savedId> [--for claude] [--json]` | Compact, honesty-framed briefing for a coding-agent context window |
+| `horus logs [service] --env <e>` | Error-signature evidence (`--raw` for lines) |
+| `horus state --env <e>` | MongoDB application-state evidence (read-only) |
+| `horus metrics [hint] --env <e>` | Grafana metrics evidence |
+| `horus queues [name] [--live]` | Queue topology from source intelligence; `--live` reads real-time Redis/BullMQ state |
+| `horus search <query>` · `explain <symbol>` · `blast-radius` · `architecture` · `what-changed` | Source-aware code intelligence — one canonical resolver, so a query resolves to the same symbol across commands (qualified `Class.method` supported) |
 | `horus memory <show\|add\|list\|link\|...>` | Inspect/author deterministic incident memory; `memory link` adds `supersedes` / `contradicts` / `recurs-with` edges |
 | `horus feedback <id> [--resolved] [--note] [--cause]` | Record outcome feedback on an investigation (improves Horus) |
 | `horus report [hint] [--title --body --labels]` | File a Horus bug or capability gap — opens a pre-filled GitHub issue (no auth, nothing sent automatically) |
 
 ## Local project workflow (git-style)
 
-A repo carries a `.horus/config.json` (discovered by walking up from the working directory, like `.git`), and a global registry (`~/.horus/registry.json`) lets `--name` resolve a project from anywhere.
+A repo carries a `.horus/config.json` (discovered by walking up from the working directory, like `.git`) — the repo's config IS the project identity. Work from inside the repo, or pass `--config <path>` to target another repo explicitly.
 
 ```bash
 cd /repos/atlas-payments
 horus init
 
 horus investigate "checkout latency spike"
-horus investigate --name atlas-payments "checkout latency spike"
-horus projects
+horus investigate --config /repos/atlas-payments/.horus/config.json "checkout latency spike"   # from anywhere
+horus projects   # list registered repos (informational)
 ```
 
 `horus init` reuses an already-running source intelligence host when one is healthy. Runtime connectors are added to the env block of `.horus/config.json` afterwards.
 
+## For coding agents
+
+Horus is built to be an agent's evidence layer. Install a skill that teaches your agent to reach for Horus before guessing:
+
+```bash
+horus skill install claude    # .claude/skills/horus/SKILL.md  (also: codex · gemini · cursor · generic)
+horus mcp                     # expose the local knowledge index to agents over MCP (stdio)
+```
+
+Every investigation/analysis command takes `--json` (`--format json` for `investigate`/`replay`) — compact by default, `--full` for the raw structure — and each result carries a deterministic `nextSteps` array. `horus packet "<hint>" --json` returns a compact briefing sized for a context window.
+
 ## Layout
 
 ```