Skip to content

docs: frame the README around the behavior contract and lane - #233

Draft
IdoGol24 wants to merge 1 commit into
docs/readme-alpha-statusfrom
chore/readme-behavior-contract
Draft

IdoGol24 wants to merge 1 commit into
docs/readme-alpha-statusfrom
chore/readme-behavior-contract

Conversation

@IdoGol24

Copy link
Copy Markdown
Collaborator

Summary

Stacked on #232. Reframes the README around what the system does rather than how it is built: engineers should not need to know how their system is implemented, only how it behaves.

  • Leads with the behavior contract (responses, stored state, runtime effects) using the existing subscription example; the Playwright spec becomes a footnote.
  • Adds the behavior lane (CODE → VERIFY → SHIP) with the verification-loop diagram, relabeled: behavior contract, real system, findings as held / failed / not observed.
  • Relabels the system-boundary diagram to what to run / how to act on it / how to observe it.
  • Moves Playwright and Feature files into a short "Writing contracts today" section.
  • Marks setup in another repository as unavailable until the npm release.

Scope and links

Type of change

  • Docs / tooling only

Validation and evidence

Command Result
npx prettier@3.9.9 --check README.md pass
relative link and anchor check on README.md pass, 13 links
run commands unchanged from #232, not rerun
  • Known limitations: docs/alpha-status.md is unchanged; the six other diagrams in docs/assets/readme/ stay unreferenced.

Security impact

  • Trust boundaries affected: none
  • No secrets or private traces are included in code, logs, or artifacts

Independent review evidence

  • Not requested; draft for discussion.

🤖 Generated with Claude Code

Lead with the behavior contract (responses, stored state, effects) and the
behavior lane (CODE -> VERIFY -> SHIP), using the relabeled verification-loop
and system-boundary diagrams. Move Playwright and Feature files into a short
"Writing contracts today" section and mark the external-repository setup path
as unavailable until the npm release.
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