docs: pip-first README + new docs/CONFIGURATION.md

[HumanBean17]

Motivation

We just shipped java-codebase-rag to PyPI as v0.1.0 (PR #205). That makes the README the package's long_description — the first thing a newcomer sees on https://pypi.org/project/java-codebase-rag/ before they decide whether to pip install.

The old README was a 785-line operator manual. It led with "Install from source: git clone ... && pip install -e ." even though the package is now on PyPI, and required scrolling through six sections of env vars, graph layer internals, brownfield mode, and ignore-pattern semantics before reaching anything resembling a quickstart. Great as a reference once you're already onboarded; intimidating as a landing page.

What changes

README.md: 785 → 185 lines. Rewritten as a pip-first landing:

1. Title + the three-paragraph intro (kept verbatim — it sets up correct expectations about the graph-first, deterministic philosophy)
2. Install: pip install java-codebase-rag + Python 3.11+ + early-stage disclaimer
3. 5-minute walkthrough: clone the repo (for the tests/bank-chat-system fixture), java-codebase-rag init, meta, python -m search_lancedb for vector search, then --graph-expand to prove Kuzu is wired
4. Wire into MCP host: Claude Code one-liner using the new java-codebase-rag-mcp console script, plus Claude Desktop inline JSON
5. Five-tool cheat sheet: search / find / describe / resolve / neighbors with required args only
6. Configuration: 6-row pointer table into docs/CONFIGURATION.md §1–§5 + CODEBASE_REQUIREMENTS.md
7. CLI cheat sheet (6 subcommand groups)
8. Further reading (9 docs)
9. Install from source demoted to the bottom — for contributors only
10. Roadmap

docs/CONFIGURATION.md (new, 582 lines) absorbs the long-form material that used to live in README.md §2/§6/§7/§8:

• §1 Environment variables
• §2 Project YAML reference (annotated .java-codebase-rag.yml, path expansion, gotchas)
• §3 Graph layer (ontology, MCP-traversable edges, call-graph notes, injection, chunk enrichment, module vs microservice, re-index callouts for ontology bumps 12→15, capabilities, ranking, debug context)
• §4 Brownfield overrides (config role/route, cross-service resolution, source stubs, caller-side, limitations, Lance/Kuzu consistency)
• §5 Ignore patterns

mcp.json.example: leads with "command": "java-codebase-rag-mcp" (the console script entry point from pyproject.toml) instead of the old /ABSOLUTE/PATH/.venv/bin/python server.py invocation.

Cross-ref sweep

Fixed every stale README anchor that survived the rewrite:

• AGENTS.md — "where to look" bullets retargeted
• CODEBASE_REQUIREMENTS.md — 4 refs (README §3a/b/c, "see README graph section") retargeted to docs/CONFIGURATION.md §3 / §4.3
• docs/AGENT-GUIDE.md — maintenance re-index callout retargeted
• docs/MANUAL-VERIFICATION-CHECKLIST.md — "see README CLI reference" → JAVA-CODEBASE-RAG-CLI.md

Historical refs in propose/completed/ and plans/completed/ are intentionally left alone (out of scope, snapshots of past state).

What this does NOT touch

• No code changes (src/, server.py, CLI behaviour, build, tests — all untouched).
• No pyproject.toml change. The next PyPI release will pick up the new long_description automatically.
• One pre-existing stale ref in docs/skills/java-codebase-explore.md:208 (says ontology 14, actual is 15) is out of scope for this PR.

Verification

• All 15 outbound links from the new README.md resolve.
• All 4 sibling-doc links in docs/CONFIGURATION.md resolve.
• 5-minute walkthrough commands fact-checked against the current CLI surface and pyproject.toml entry points (no fictional mcp subcommand; python -m search_lancedb works because search_lancedb is a top-level py-module shipped in the wheel).

Draft for now — happy to take review on framing, table shapes, and whether the 5-minute walkthrough hits the right depth.

[HumanBean17]

Review: pip-first README + CONFIGURATION.md

Clean docs refactor — content is faithfully migrated, cross-references are consistent, and the new README hits the right depth for a PyPI landing page. A few items worth confirming before merge:

Worth checking

1. MCP v2 response extras paragraph is gone from both files. Old README §4 had a dense paragraph about hints, pagination echo, resolved_identifier, page-full hints, fuzzy-strategy hints, and pointers to HINTS-V3-PROPOSE.md / HINTS-ROAD-SIGNS-PROPOSE.md / HINTS-V2-PROPOSE.md. The new README delegates to AGENT-GUIDE.md, but the AGENT-GUIDE diff only changes the maintenance callout — it doesn't add this content. If the hints contract details aren't already in AGENT-GUIDE.md, this content is now orphaned.

2. python -m search_lancedb in the walkthrough assumes the module ships in the wheel. The PR body asserts this works, but worth confirming search_lancedb is actually included in pyproject.toml [tool.setuptools.packages.find] — pip-only users will get an ImportError otherwise.

Minor nits (non-blocking)

• "Install from source" drops the default embedding model note (sentence-transformers/all-MiniLM-L6-v2). Now only in CONFIGURATION.md §2. Low-risk since pip users get it implicitly, but source-build contributors may not know what model to expect.

• No TOC in the new README. At 185 lines it's arguably skimmable without one, but a tiny TOC could help scroll-fatigued PyPI readers. Style choice.

Otherwise looks good — ship-ready after the two checks above.

[HumanBean17]

Thanks for the careful read. Checked all four items:

1. Hints contract — already in AGENT-GUIDE.md ✅

Not orphaned. docs/AGENT-GUIDE.md already carries the contract:

• L19 — top-level hints list (≤5 next calls), echoed limit/offset on search/find, advisory-only / ignore-on-failure semantics.
• L102 — neighbors pagination semantics (default limit=25, slicing merged flat + composed edge list).
• L231 — specialized hint templates (TPL_NEIGHBORS_CALLS_HIGH_FANOUT, TPL_NEIGHBORS_CALLS_HAS_UNRESOLVED) and their single-origin-only firing rule.
• L237 — full CALLS edge contract including include_unresolved, dedup_calls, edge_filter projection.

The old README §4 paragraph was a duplicate of what AGENT-GUIDE already owned. The propose-doc pointers (HINTS-V3-PROPOSE.md etc.) are findable from docs/AGENT-GUIDE.md and the propose/ directory listing — those are design-history references, not user-facing contract.

2. search_lancedb in the wheel ✅

Confirmed at pyproject.toml:65:

[tool.setuptools]
packages = ["java_codebase_rag"]
py-modules = [
    "ast_java",
    ...
    "search_lancedb",
    ...
]

python -m search_lancedb works for pip-only users.

3. Default embedding model note — agreed, will add

You're right that source-build contributors lose this info. Will add a one-liner under the source-install section pointing at EMBEDDING_MODEL env var + sentence-transformers/all-MiniLM-L6-v2 default.

4. TOC — passing for now

Disagree on this one. 185 lines with ## headers every ~20 lines is below the threshold where a TOC stops being noise and starts being navigation. GitHub renders a sticky outline on the right rail and PyPI renders headings inline — both give skimmers the same affordance a hand-written TOC would. Reconsidering only if the README grows past ~250 lines.

Will push the §3 fix as a fixup commit shortly.

[HumanBean17]

All four items resolved — LGTM, ready to merge.

1. Hints contract — confirmed in AGENT-GUIDE.md (L19, L102, L231, L237). Not orphaned.
2. search_lancedb — confirmed in pyproject.toml py-modules. Pip users are fine.
3. Default embedding model — fixup commit added the one-liner under source-install.
4. TOC — agreed to disagree, rationale is sound.

Ship it.