Skip to content

docs: lead README with governance; remove build-hero + images#124

Merged
stackbilt-admin merged 1 commit intomainfrom
docs/governance-first-readme
Apr 18, 2026
Merged

docs: lead README with governance; remove build-hero + images#124
stackbilt-admin merged 1 commit intomainfrom
docs/governance-first-readme

Conversation

@stackbilt-admin
Copy link
Copy Markdown
Member

Summary

The repo's own description already reads "Local-first AI agent governance CLI. Modular .ai/ context system (ADF) replaces monolithic CLAUDE.md files." But the README opened with a stackbilt run scaffolding demo and stackbilt-charter-4.png hero, contradicting that framing. This PR aligns the README with the repo's identity — governance-first, with scaffolding flagged as deprecated and moving to @stackbilt/build.

Changes

README opening

  • Replace "Your first Cloudflare Workers project shouldn't take a week" + charter run Quick Start with a governance-first opener built around charter bootstrap --yes.
  • Rewrite "What you get" to lead with ADF, metric ceilings, blast/surface analysis, drift/audit, and the MCP server. The ecosystem-packages table is demoted to a one-line inline reference (still discoverable, no longer the hero).

Auth line

Commands reorder + deprecation

  • New order: Govern → ADF → Analyze → Build (last).
  • Build section now has a callout flagging the four commands as deprecated and pointing at RFC #112 for the @stackbilt/build extraction.
  • charter login --key line annotated with "prefer STACKBILT_API_KEY env var."

Image cleanup

  • Remove stackbilt-charter-{2,3,4}.png (scaffolding hero series — named for the binary that's moving out).
  • Remove ADF_1.png and its reference in packages/adf/README.md.
  • Can be re-added with governance-aligned visuals in a follow-up when those exist.

What this does not change

Test plan

  • Render the new README locally and skim for typos or broken links.
  • Verify no remaining references to removed images: grep -r 'stackbilt-charter\|ADF_1' --include='*.md' returns zero hits.
  • Spot-check the deprecation callout on the Build section reads correctly on GitHub.

🤖 Generated with Claude Code

The repo's identity is already governance-first (description:
"Local-first AI agent governance CLI. Modular .ai/ context system
(ADF) replaces monolithic CLAUDE.md files."), but the README
opened with a `stackbilt run` scaffolding demo and hero image,
contradicting the repo's own framing.

README changes:
- Replace "Your first Cloudflare Workers project shouldn't take a
  week" hero + Quick Start with governance-first opener using
  `charter bootstrap`.
- Rewrite "What you get" to lead with governance bullets (ADF,
  metric ceilings, blast/surface analysis, drift/audit, MCP
  server). Demote the ecosystem-packages table to a one-line
  inline reference.
- Drop the "Free to try — charter login --key ..." line; scaffold
  auth is moving out and is already env-var-authed (#111).
- Reorder Commands: Govern → ADF → Analyze → Build (last).
- Flag Build commands as deprecated with a callout pointing at
  RFC #112 (@stackbilt/build extraction).

Image cleanup:
- Remove stackbilt-charter-{2,3,4}.png (scaffolding hero series).
- Remove ADF_1.png + its reference in packages/adf/README.md.
  Can be re-added with governance-aligned visuals in a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@stackbilt-admin stackbilt-admin merged commit 04cc3a8 into main Apr 18, 2026
3 checks passed
@stackbilt-admin stackbilt-admin deleted the docs/governance-first-readme branch April 18, 2026 12:32
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.

1 participant