docs: improve structure, navigation, and coverage across documentation

[svidskiy]

Summary

Complete documentation rewrite: eliminate duplication, fix factual errors, restructure navigation, and split oversized pages. Also remove dead code and fix typography across all files.

Problems addressed

• Duplication: embedding providers table appeared in 4 files, Milvus backends in 4 files, agent examples in 3 files, plugin docs existed as near-identical 770+ line files in both docs/claude-plugin.md and ccplugin/README.md
• Factual errors: mermaid diagrams said "Cosine similarity" but search is hybrid (dense + BM25 + RRF); embedding_batch_size parameter missing from Python API docs; embedding.batch_size config key missing from CLI reference
• Structural issues: claude-plugin.md was 935 lines (too long for one page); getting-started.md conflated tutorial with reference; CONTRIBUTING.md had incomplete project tree; mkdocs nav was flat with no grouping
• Broken/missing: ccplugin/README.md had broken anchor links; no Contributing page in mkdocs nav
• Typography: -- (double hyphen) used instead of — (em dash) across README.md and all docs/ files
• Dead code: unused MilvusStore.existing_hashes(), unused _SECTION_CLASSES import in cli.py, unused Turn.line_index field in transcript.py

---

Navigation restructure (mkdocs.yml)

Before:

Home | Getting Started | Architecture | Python API | CLI Reference | Integrations | Claude Code Plugin | FAQ

After:

Home | Getting Started | Reference (Python API, CLI) | Architecture | Integrations | Claude Code Plugin (Overview, Hooks, Progressive Disclosure, Troubleshooting) | FAQ & Troubleshooting | Contributing

• Grouped Python API + CLI under "Reference"
• Split claude-plugin.md into 4 focused pages
• Added Contributing to nav

---

New files

File	Lines	Content
docs/claude-plugin/index.md	~290	Overview, architecture diagram, quick start, lifecycle diagram, memory storage, plugin files, comparisons (claude-mem + native memory)
docs/claude-plugin/hooks.md	~120	Deep dive into all 4 lifecycle hooks, communication protocol, common.sh
docs/claude-plugin/progressive-disclosure.md	~180	3-layer retrieval system (search → expand → transcript), session anchors, manual invocation
docs/claude-plugin/troubleshooting.md	~310	Observability table, status line, debug mode, CLI diagnostics, watch process, skill execution, memory files, common issues, realpath macOS fix
docs/contributing.md	symlink	Symlink to root CONTRIBUTING.md for mkdocs nav

Deleted files

File	Lines	Reason
docs/claude-plugin.md	935	Replaced by 4 focused pages in docs/claude-plugin/

Rewritten files

File	Key changes
docs/index.md	Slimmed to ~125 lines. Added "Hybrid search" to features. Embedding/Milvus tables now show brief summary + link to canonical location instead of full duplicate
docs/getting-started.md	Fixed mermaid diagram ("Cosine similarity" → "Hybrid search (dense + BM25)"). Added embedding.batch_size to TOML config example. Links to canonical tables in CLI reference
docs/python-api.md	Added missing embedding_batch_size parameter to constructor table. Updated search description to mention hybrid search
docs/cli.md	Added Shared Options section (--provider, --model, --batch-size, --collection, --milvus-uri, --milvus-token) to reduce per-command duplication. Added embedding.batch_size to config keys table and config list output. Per-command option tables now reference shared options
ccplugin/README.md	Shrunk from 773 → ~130 lines: brief overview + architecture diagram + hook table + links to 4 docs pages
docs/architecture.md	Removed duplicated Configuration System section (~50 lines) — now canonical in getting-started.md and cli.md
docs/faq.md	Moved plugin-specific realpath -m issue to plugin troubleshooting page, replaced with cross-link
mkdocs.yml	New nav structure with Reference group, split claude-plugin, added Contributing

Updated files

File	Change
CONTRIBUTING.md	Fixed ccplugin tree: added hooks.json, scripts/derive-collection.sh, skills/memory-recall/SKILL.md, individual hook files. Aligned all # comments to the same column
CLAUDE.md	Fixed ccplugin tree: added .claude-plugin/plugin.json and hooks.json
README.md	Replaced -- with — (em dash) throughout

---

Dead code removal

Code	File	Reason
MilvusStore.existing_hashes()	store.py	Method never called — not in src, tests, or examples
_SECTION_CLASSES import	cli.py	Imported from config.py but never used in cli.py
Turn.line_index field	transcript.py	Field written during parsing but never read by any consumer

Bug fixes

Bug	File	Fix
Mermaid "Cosine similarity"	getting-started.md	Changed to "Hybrid search (dense + BM25)" + "RRF-reranked Top-K matches"
Missing embedding_batch_size	python-api.md	Added parameter row to constructor table
Missing embedding.batch_size	cli.md	Added to config keys table and config list output
Missing "Hybrid search" feature	index.md	Added to Key Features list
Incomplete ccplugin tree	CONTRIBUTING.md, CLAUDE.md	Added hooks.json, scripts/, skills/
Plugin issues in wrong page	faq.md	Moved realpath issue to claude-plugin/troubleshooting.md
Typography -- → —	README.md, all docs/*.md	Replaced double hyphens with proper em dashes
Misaligned comments	CONTRIBUTING.md	Aligned all # in project structure tree to column 33

Single source of truth

Topic	Canonical file	Others
Embedding providers (full table with dims)	cli.md #Embedding Provider Reference	index.md, getting-started.md: short table + link
Milvus backends (code, Docker)	getting-started.md #Milvus Backends	index.md: summary table + link
Config keys (full table)	cli.md #Available Config Keys	getting-started.md: wizard + TOML example
Plugin docs	docs/claude-plugin/ (4 pages)	ccplugin/README.md: brief overview + links

Closes #91

Test plan

• mkdocs build --strict completes with zero errors
• All internal cross-references verified (no stale claude-plugin.md links)
• All 4 new claude-plugin pages render correctly
• Contributing symlink resolves properly in mkdocs build
• Mermaid diagrams use correct "Hybrid search" labels
• embedding_batch_size / embedding.batch_size documented in both Python API and CLI