Skip to content

docs: keep the README front door standalone before introducing Weaver Stack #847

Description

@dgenio

Problem

The current README hero has improved toward the #758 capability-surface thesis, but the ecosystem story still appears too early in the evaluation funnel.

On the current v0.18.1 release branch, ## Part of the Weaver Stack appears immediately after the hero, initial problem/context-rot evidence and link row — before a newcomer reaches the core ContextWeaver problem explanation, maintained product workflow, deeper proof, limitations and quickstart.

That creates an avoidable adoption risk: a reader evaluating one small OSS dependency can feel as though they are being asked to understand or adopt an ecosystem before ContextWeaver has independently earned the next scroll.

This is a placement/funnel issue, not a request to remove the Weaver Stack story.

Goal

Make the first ~25–30% of the README fully understandable and useful to someone who knows nothing about Weaver Stack.

The top-level sequence should establish ContextWeaver on its own:

  1. user problem / result;
  2. who it is for and when it is unnecessary;
  3. install / maintained first-success path;
  4. reproducible evidence and current limitations;
  5. canonical product workflow / architecture at the level needed to evaluate this repo;
  6. only then introduce Weaver Stack as an optional composition/ecosystem story.

Proposed change

  • Move Part of the Weaver Stack below the standalone product/evidence/onboarding material, likely into an ecosystem/integrations/community section.
  • Keep the section and its standalone-use statement; do not erase cross-repo composition.
  • Avoid sibling-repo badges/CTAs competing with the primary ContextWeaver evaluation path above the fold.
  • Keep any cross-repo demo links near the moved ecosystem section rather than the first-success path.
  • Coordinate with Consolidate the three overlapping "where does contextweaver fit" orientation pages #647 so the README points to one canonical ecosystem/orientation page after the docs consolidation.

Non-goals

Acceptance criteria

  • A newcomer can reach the primary ContextWeaver problem, evidence, install/first-success path and when not to use guidance without first reading about sibling repositories.
  • Part of the Weaver Stack remains present but appears after the standalone product case is established.
  • The first ~25–30% of README contains no knowledge dependency on ChainWeaver, agent-kernel, agentfence or the Weaver Stack concept.
  • Cross-repo links remain discoverable from the ecosystem section.
  • The resulting ordering is consistent with Epic: Validate and ship a reproducible agent capability surface #758 and docs/demo: Prove the reproducible capability-surface workflow end to end #434: problem/evidence first, architecture/ecosystem terminology later.
  • No existing README anchors/links are broken; docs/link checks pass.

Why separate from existing issues

This issue owns only the README evaluation-funnel ordering and ecosystem placement.

Related

#758, #434, #647, #397, #658, #351.

Metadata

Metadata

Assignees

No one assigned

    Labels

    adoptiondocumentationImprovements or additions to documentationpriority: mediumImportant, clear value, not blocking

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions