feat(jrag): ship agent-facing jrag CLI (JRAG-CLI plan, 9 PRs)

.agents/skills/publish-pip/SKILL.md

@@ -47,28 +47,34 @@ adding a runtime dependency to `pyproject.toml`.
    ```bash
    rm -rf dist build *.egg-info
    ```
-4. **Build** sdist + wheel:
+4. **Sync agent artifacts** — ensure install_data copies match dev source:
+   ```bash
+   .venv/bin/python scripts/sync_agent_artifacts.py --check
+   ```
+   If this fails, run `.venv/bin/python scripts/sync_agent_artifacts.py` to sync,
+   then commit the changes before publishing.
+5. **Build** sdist + wheel:
    ```bash
    .venv/bin/python -m build
    ```
    Expect `dist/java_codebase_rag-<ver>-py3-none-any.whl` and `.tar.gz`.
-5. **Verify the built version** before upload (catches a forgotten bump):
+6. **Verify the built version** before upload (catches a forgotten bump):
    ```bash
    .venv/bin/python -c "import zipfile,glob; w=glob.glob('dist/*.whl')[0]; z=zipfile.ZipFile(w); m=[n for n in z.namelist() if n.endswith('METADATA')][0]; print([l for l in z.read(m).decode().splitlines() if l.startswith('Version')][0])"
    ```
-6. **Upload** (permanent — confirm the version is right first):
+7. **Upload** (permanent — confirm the version is right first):
    ```bash
    .venv/bin/twine upload dist/*
    ```
    twine prints the live URL on success:
    `https://pypi.org/project/java-codebase-rag/<ver>/`.
-7. **Verify on PyPI** via the JSON API. ⚠️ Python's `urllib`/`requests` SSL
+8. **Verify on PyPI** via the JSON API. ⚠️ Python's `urllib`/`requests` SSL
    verification fails locally (missing CA bundle) — set `SSL_CERT_FILE`:
    ```bash
    CERT=$(.venv/bin/python -c "import certifi; print(certifi.where())")
    SSL_CERT_FILE="$CERT" .venv/bin/python -c "import urllib.request,json; d=json.load(urllib.request.urlopen('https://pypi.org/pypi/java-codebase-rag/json')); print('latest:', d['info']['version'])"
    ```
-8. **Commit + push the version bump** so the repo matches what was published
+9. **Commit + push the version bump** so the repo matches what was published
    (commit convention: `bump version to X.Y.Z`). `dist/`, `build/`, and
    `*.egg-info` are gitignored — do not commit them.
 
@@ -79,6 +85,7 @@ adding a runtime dependency to `pyproject.toml`.
 | Bump | edit `pyproject.toml` `version` |
 | Tooling | `.venv/bin/pip install build twine` |
 | Clean | `rm -rf dist build *.egg-info` |
+| Sync | `.venv/bin/python scripts/sync_agent_artifacts.py --check` |
 | Build | `.venv/bin/python -m build` |
 | Verify wheel | read `Version:` from `dist/*.whl` METADATA |
 | Upload | `.venv/bin/twine upload dist/*` |

README.md

@@ -149,12 +149,16 @@ See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (
 
 ### Driving the MCP from an agent
 
-Pick **one** of two options (not both — they cover the same navigation intents):
+Pick **one** of two surfaces (`java-codebase-rag install --surface mcp|cli`; default `mcp`). Within the MCP surface, pick **one** delivery mechanism (not both — they cover the same navigation intents):
 
 1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
 
 2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
 
+Alternatively, for hosts that prefer shell-driven exploration (no MCP server), use the **CLI surface**:
+
+3. **`--surface cli`** — `java-codebase-rag install --surface cli` deploys the **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** skill + **[`explorer-rag-cli`](./agents/explorer-rag-cli.md)** subagent instead of the MCP entry. The agent drives the `jrag` CLI (`jrag callers`, `jrag inspect`, `jrag search`, …) — one command per engineering intent, no MCP tools. Same graph underneath; picks this surface when the host cannot run a stdio MCP server or you prefer the CLI vocabulary.
+
 Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
 
 ---
@@ -173,7 +177,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (5 MCP tools **or** the `jrag` CLI) → Layer 3 (skill). The MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the 5-tool MCP; the CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -209,6 +213,114 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 
 ---
 
+## jrag — agent CLI
+
+`jrag` is a separate console script (alongside `java-codebase-rag`) built for AI
+coding agents. It gives the agent **one command per engineering intent** and
+takes human-readable identifiers (FQN / simple name / route path / topic) —
+never raw node IDs. Every `<query>` command resolves the identifier via
+`resolve_v2` as the first step; on `many` it returns candidates and stops, on
+`none` it returns `not_found`. Auto-pick is forbidden.
+
+The default output is compact text (a deliberate divergence from the operator
+CLI's TTY heuristic — `jrag` is agent-facing/non-TTY). `--format json` emits the
+shared envelope verbatim. Every command emits the same envelope shape:
+
+```json
+{
+  "status": "ok",
+  "nodes": {"<id>": {"id": "...", "kind": "...", "fqn": "..."}},
+  "edges": [{"other_id": "...", "edge_type": "CALLS", "confidence": 0.9}],
+  "root": "<resolved-id>",
+  "agent_next_actions": ["jrag callees com.example.Foo#bar()"],
+  "truncated": false
+}
+```
+
+`agent_next_actions` carries up to 5 contextual next-step hints (e.g. after
+`inspect`, the agent sees `jrag callers <fqn>`, `jrag callees <fqn>`, etc. for
+the edges the root actually has). Omitted from JSON when empty.
+
+### Commands
+
+```bash
+# Orientation
+jrag status                    # index health (ontology version, freshness, counts)
+jrag microservices             # microservices with resolved type counts
+jrag map                       # counts per kind per service/module
+jrag map --module              # group by module instead
+jrag conventions               # dominant roles + framework tallies
+jrag overview chat-core        # bundle for a microservice
+jrag overview /chat/assign     # route flow (inbound callers + outbound CALLS)
+jrag overview banking.chat     # topic producers + consumers
+jrag overview chat-core --as microservice  # override auto-detection
+
+# Locate
+jrag find ChatService          # exact name/FQN lookup (symbols)
+jrag find --role CONTROLLER    # filter mode (NodeFilter flags)
+jrag inspect ChatService       # full node details + edge_summary
+jrag outline src/main/.../Foo.java  # all symbols declared in a file
+jrag imports src/main/.../Foo.java   # imports resolved to graph nodes
+
+# Listings
+jrag routes                    # HTTP routes
+jrag clients                   # HTTP clients (Feign / RestTemplate / WebClient)
+jrag producers                 # async message producers (Kafka / StreamBridge)
+jrag topics                    # message topics grouped by producer
+jrag jobs                      # scheduled tasks (@Scheduled)
+jrag listeners                 # message listeners (@KafkaListener etc.)
+jrag entities                  # JPA entities
+
+# Traversals (all resolve-first)
+jrag callers ChatService#assign(Request)   # who calls me?
+jrag callees ChatService#assign(Request)   # what do I call?
+jrag hierarchy AbstractBase               # type tree (parents + children)
+jrag implementations PaymentProcessor     # classes implementing an interface
+jrag subclasses AbstractRepository        # classes extending a type
+jrag overrides Impl#run()                 # methods this overrides (dispatch UP)
+jrag overridden-by Iface#run()            # methods overriding this (dispatch DOWN)
+jrag dependents PaymentGateway            # who injects this type?
+jrag dependencies ChatService             # types this injects
+jrag impact PaymentGateway                # fleet-wide blast radius
+jrag decompose ChatIngressController#assign   # role-waterfall flow
+jrag flow /chat/assign                    # request flow through a route
+jrag connection chat-core                 # cross-service connections
+
+# Semantic search
+jrag search "assign a chat agent"         # semantic over Lance (java table)
+jrag search "kafka" --table all           # java + sql + yaml tables
+jrag search "audit" --hybrid              # vector + keyword hybrid
+jrag search "audit" --offset 5            # paginated
+```
+
+### Flags
+
+| Flag | Scope | Effect |
+|------|-------|--------|
+| `--format text\|json` | all | output format (default: text) |
+| `--service <name>` | listings/traversals | filter by microservice |
+| `--module <name>` | listings/traversals | filter by module |
+| `--limit <n>` | listings/traversals | cap results (default 20; `limit+1` fetch detects truncation) |
+| `--offset <n>` | `find`, `search` only | paginate (other commands reject it) |
+| `--kind symbol\|route\|client\|producer` | `<query>` commands | resolve hint |
+| `--java-kind`, `--role`, `--fqn-prefix` | `<query>` commands | client-side post-filters |
+| `--index-dir <path>` | all | override index directory |
+
+`--offset` is intentionally NOT a global flag: only `find` and `search` route
+through backends that accept it. Every other command rejects it.
+
+A missing or stale index produces an actionable `status: error` envelope (exit
+2) rather than a traceback:
+
+```
+error: No index at /path/to/code_graph.lbug. Run: java-codebase-rag init --source-root <root>
+```
+
+See [`plans/active/PLAN-JRAG-CLI.md`](./plans/active/PLAN-JRAG-CLI.md) for the
+full design and per-PR breakdown.
+
+---
+
 ## Further reading
 
 | Document | What's in it |
@@ -218,7 +330,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | Single `/explore-codebase` skill — complete MCP operating manual for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | `/explore-codebase` (MCP surface) + `/explore-codebase-cli` (CLI surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |