Skip to content

docs: restructure README for clarity and professionalism#150

Merged
LucasErcolano merged 1 commit into
masterfrom
docs/readme-restructure
Apr 26, 2026
Merged

docs: restructure README for clarity and professionalism#150
LucasErcolano merged 1 commit into
masterfrom
docs/readme-restructure

Conversation

@theaayushstha1

Copy link
Copy Markdown
Collaborator

Summary

Standalone README restructure ahead of the hackathon submission — pure documentation change, no code touched.

  • Single, consistent heading hierarchy with a clickable TOC at the top — judges can jump to whichever section matters.
  • Killed every duplicate section — Quickstart appeared twice, Modes vs Mode taxonomy appeared twice, Grounding gate appeared twice, UI vs UI status, Implementation notes vs Architecture. Each topic now lives in exactly one place.
  • Consolidated Modes + trust tags + tiers into one section near the bottom (pitch first, taxonomy second).
  • Merged Memory + Managed-Agents-memory + Memory CLI into one clean section with a single table for the lifecycle commands.
  • Collapsed the giant capability matrix inside <details> so the shipped/partial/roadmap legend stays visible but the wall of rows doesn't drown the page.
  • Promoted Demo + 60-second quickstart to the top so judges hit it before the trust-tag taxonomy.
  • Trimmed the Docs list to judge-relevant items only — dropped TESTIMONIAL, FLAG_PLANT, REHEARSAL, RISKS, ONBOARDING, SUBMISSION, the redundant Token discipline section, and the hackathon-internal "Open backlog" PR-number noise.

What did NOT change

  • Every concrete claim, file pointer, code block, mermaid diagram, and benchmark number is preserved.
  • Reference run numbers ($0.46 total spend, 2 of 3 non-skeleton matches, file path) unchanged.
  • Hero-case narrative, grounding-gate thresholds, frozen 7-class taxonomy, memory stack details unchanged.

Test plan

  • Render the README on github.com/LucasErcolano/BlackBox/tree/docs/readme-restructure and skim
  • Click each TOC anchor — confirms heading IDs all resolve
  • Expand the capability <details> block — confirms the full table is intact
  • Confirm every internal link (docs/SMOKE_TEST.md, SCOPE_FREEZE.md, etc.) still resolves

🤖 Generated with Claude Code

- single, consistent heading hierarchy with a clickable TOC at the top
- consolidated duplicate sections — Quickstart, Modes, Grounding gate,
  UI/UI status, Implementation notes/Architecture each now live in
  exactly one place
- merged Mode taxonomy + Modes + trust-tag definitions into one
  "Modes and trust tags" section
- merged the Memory stack + Managed Agents memory + Memory CLI material
  under one section, with a clean table for the lifecycle commands
- collapsed the long capability table inside <details>; the high-level
  shipped/partial/roadmap legend stays visible above the fold
- promoted Demo + 60-second quickstart to the top so judges hit it
  before the trust-tag taxonomy
- trimmed Docs to judge-relevant items (dropped TESTIMONIAL, FLAG_PLANT,
  REHEARSAL, RISKS, ONBOARDING, SUBMISSION, redundant Token discipline
  section, hackathon-internal Open backlog noise)

Substance unchanged — every file pointer, code block, mermaid diagram,
and benchmark number preserved.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@LucasErcolano LucasErcolano merged commit 905a759 into master Apr 26, 2026
1 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants