Skip to content

README: promote the honest scope-coverage table (+ interface summary) to a user-facing artifact #7

Description

@paul-hammant

Motivation

blazerules opens its README with a 4-row Interface summary table (Python SDK / CLI / agent / dashboard — "what it is / entry points") and carries a scope-coverage mindset throughout its user-facing docs. It earns trust by stating capability boundaries plainly to users.

aeb already has the best version of this table anywhere — the scope-scoring table in LLM.md with ✓/◐/✗ marks and unembellished per-dimension status. The problem: that honest self-assessment lives in a notes-to-self file a user never reads, while the README undersells what's actually done and hides what's still ✗ TODO.

Proposal

Promote the scope-coverage table (or a user-facing derivative) into README.md as a first-class section.

  • Keep the three-tier honesty: ✓ Done / ◐ Partial / ✗ TODO.
  • Trim the LLM-facing implementation asides; keep "what good looks like" + "aeb status."
  • Add a short Interface summary table above it (à la blazerules): the ways to invoke aeb — aeb <target>, aeb --scan, aeb --graph, aeb --since, aeb gcheckout, aeb --sandbox/--vet, aeb --watch — one row each, "what it is / entry point."
  • LLM.md keeps its own copy with the implementation detail; the README version is the trimmed public one. A note in each points at the other so they don't silently drift.

Acceptance criteria

  • README has an Interface summary table listing every invocation surface with a one-line description.
  • README has a scope-coverage table with ✓/◐/✗ status per dimension, derived from the LLM.md table.
  • Both tables are honest — ✗ TODO rows (remote cache, lockfiles, publishing, IDE/LSP, cross-compile, CI integration) are shown, not omitted.
  • Cross-reference note in both README.md and LLM.md so the two copies are known-linked.

Not being asked

Not asking to auto-generate the table from code, or to make the two copies a single source with an include mechanism. Hand-maintained + cross-referenced is fine at this size.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions