Skip to content

docs: rewrite README for a public audience#29

Merged
adworzynski merged 1 commit into
mainfrom
docs/readme-rewrite
Jul 8, 2026
Merged

docs: rewrite README for a public audience#29
adworzynski merged 1 commit into
mainfrom
docs/readme-rewrite

Conversation

@adworzynski

Copy link
Copy Markdown
Owner

What

Phase 1 of taking EAaC public — rewrite the README for a stranger, not a maintainer. Docs-only,
no design impact.

  • README top now leads with the thesis ("EA as deterministic, validated code; AI supplies
    only judgment") and a verified quick-look demo before the dev instructions, which move to
    the bottom. Adds license / CI / python badges and a contract diagram with P1/P2.
  • Install documents pip install git+… via pipx/uvx (no PyPI — decided out of scope
    for now), with a @v0.1.0 version-pin example.
  • ea pack fetch is wired into install + quick-look: fetching the method library (packs +
    presets) into ~/.cache/ea resolves offline, so the quick-look no longer needs
    EA_PACK_PATH/EA_PRESET_PATH exports
    .
  • Fixes a latent inaccuracy: the old demo adopted startup-light, which is a test fixture, not
    a production preset
    → switched to lean-ux.
  • examples/README notes the read-only verbs resolve from each example's materialized
    definitions/ (need nothing), with ea pack fetch . for authoring your own.

Proof

Docs-only — no src/ change, so no new tests. Every command documented was run against the
live CLI
and returns what the README claims:

  • ea pack fetch .ok, fetches 6 packs + 3 presets into the cache; ea preset list then
    resolves them offline with no path vars.
  • Build flow ea initea manifest adopt lean-uxea validate --all → all status: ok.
  • Example poking (validate --all, type show, graph dependency, report coverage in
    examples/retailco-enterprise/repo) → all ok standalone, no packs on path.
  • examples/payments-oaa/repo: ea validate --allok (exit 0), ea manifest showok.

No agent-facing behavior changed.

Notes

  • The git+https://… install/clone/fetch commands and the @v0.1.0 pin assume the repo is
    public (Phase 2) — intentional; they're the documented public-facing commands.

Lead with the thesis (EA as deterministic, validated code; AI supplies only judgment) and a verified quick-look demo before dev setup, add license/CI/python badges, and document install via 'pip install git+' (pipx/uvx) with a version-pin example.

Wire 'ea pack fetch' into the install + quick-look flow: fetching the method library (packs + presets) into ~/.cache/ea resolves offline, so the quick-look no longer needs EA_PACK_PATH/EA_PRESET_PATH exports. Fix the demo preset id (startup-light was a test fixture -> lean-ux, a real production preset). examples/README: note read-only verbs resolve from materialized definitions/, with pack fetch for authoring.
@adworzynski adworzynski merged commit 3bd54d6 into main Jul 8, 2026
2 checks passed
@adworzynski adworzynski deleted the docs/readme-rewrite branch July 8, 2026 14:24
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