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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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