Consolidate the three overlapping "where does contextweaver fit" orientation pages

[dgenio]

Summary

Merge the three top-level docs pages that all answer "where does contextweaver sit in my stack" — docs/comparison.md, docs/ecosystem.md, and docs/interop.md — into one canonical orientation page (plus the existing which_pattern.md decision tree), with redirects from the retired URLs, and use the consolidation to thin the 41-page flat top-level docs inventory.

Why this matters

A new evaluator currently lands on three different orientation pages with substantially overlapping framing; maintainers must keep three narratives synchronized as positioning evolves (and open #433 proposes adding a fourth, the MCP-gateway landscape page). One canonical orientation page reduces drift risk, shortens the evaluation path, and makes nav comprehensible.

Current evidence

• docs/comparison.md — "Where contextweaver fits (and where it doesn't) … a short, honest map of the agent-stack landscape".
• docs/ecosystem.md — opens with "This page is the adopter-facing version of Where contextweaver fits" — a self-described variant of the same page.
• docs/interop.md — "How contextweaver Fits … This page is the orientation map", pointing at docs/which_pattern.md for the decision tree.
• ls docs/*.md counts 41 flat top-level pages, several of which (launch_kit.md, killer_demo.md) target one-off events rather than evergreen reader paths.
• Related open issues: docs: Map capability discovery, tool search, gateways, and context compilation #433 (proposes an MCP-gateway landscape page — should land as a section of the consolidated page, not a fourth sibling), Single-source duplicated README content and fix roadmap staleness; extend readme-version-check to the roadmap table #531 (README duplication/staleness — same disease, different organ; reference it).

External context

Documentation frameworks (Diátaxis and similar) recommend exactly one "explanation/orientation" entry point per audience; mkdocs supports mkdocs-redirects for retired URLs.

Proposed implementation

1. Content audit: diff the three pages section-by-section; classify each section as canonical, duplicate, or unique.
2. Build one consolidated orientation page (likely keeping the ecosystem.md adopter-facing tone), folding in unique material from the other two and a placeholder section for docs: Map capability discovery, tool search, gateways, and context compilation #433's landscape content.
3. Replace comparison.md and interop.md with redirects (mkdocs-redirects plugin) so inbound links and search results keep working.
4. Update mkdocs.yml nav, README links, and any cross-references (grep for the three filenames across docs/, README, and docstrings).
5. Second pass (optional, separate PR): propose grouping the remaining flat pages into nav sections (guides / integrations / reference / project).

AI-agent execution notes

• Inspect first: the three pages in full, docs/which_pattern.md, mkdocs.yml nav, README "docs" links, scripts/ for any llms.txt generation that enumerates docs pages (the llms.txt drift gate must be regenerated).
• Run: mkdocs build --strict (or the repo's docs CI target) to catch broken links; make ci for the llms.txt/readme drift gates.
• Preserve: page content that other docs deep-link to (anchors) must survive or be redirected; do not change the substance of positioning claims, only their location.
• Failure mode: silent loss of a unique paragraph during merging — do the section-by-section audit table first.

Acceptance criteria

• Exactly one orientation page remains in nav; retired URLs redirect to it.
• No broken internal links (mkdocs build --strict passes); llms.txt and README drift gates pass.
• The consolidated page contains every unique section identified in the audit, verified against the audit table.
• docs: Map capability discovery, tool search, gateways, and context compilation #433 is updated to target a section of the consolidated page.

Test plan

Docs build in strict mode; link checker over the built site; drift-gate targets (make ci); manual read-through of the merged page for narrative coherence.

Documentation plan

This issue is a documentation change; additionally note the consolidation in CHANGELOG and update docs/index.md entry points.

Migration and compatibility notes

Redirects preserve external links. No code change.

Risks and tradeoffs

A single long page can become unwieldy — mitigate with a tight table of contents and by pushing detail into the integration guides; merging tone differences (honest-landscape vs adopter-pitch) needs editorial care. Alternative (status quo plus #433) grows the overlap to four pages.

Suggested labels

documentation, deprecation, adoption, good-first-ai-issue

[dgenio]

Audit note (2026-07-03 read-only repository audit, v0.16.0): the README is a strong candidate for the same consolidation this issue describes. It's ~50 KB / ~830 lines, including a 7-part "Why Trust contextweaver?" essay, two overlapping roadmap tables, a Weaver Stack promo section, a 16-row integrations table, an 18-row extras table, and a comparison matrix with 7 footnotes.

Two specific fixes to fold in:

• Trust-language overreach: README says "contextweaver is built for production use," while the same README's stability table declares the package Alpha and lists v1.0 as "planned" — and there's a closed GitHub milestone literally titled "v1.0 — production-ready." Recommend replacing the production language with the stability-table wording.
• Scope vs audience: the 16-integration surface and dedicated Weaver Stack section are heavy for the current adoption level; suggest moving trust/comparison/roadmap/Weaver-Stack material to docs/ pages and cutting the README to ~10 KB (pitch, install, one snippet, one demo, links).

Note (good practice worth preserving): README quickstart snippets were spot-checked against source and are accurate, and the make doc-snippets-check gate keeps them runnable — so the diet is about size, not correctness.