docs: rewrite README — problem-first, value-first, half the words - #28
Merged
Merged
Conversation
Opens with the problem (the web was built for humans), one-time setup, the before+after-build map mechanism, six benefit-first feature entries, and the coding-agent report loop. Contract sections (status, design posture, supported matrix, init, config, layout) kept in trimmed form; deep-dive sections folded into the feature entries or cut. 596 → 186 lines. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… the bundle devDependencies worked by accident of bundling (next build inlines @ora-ai/ax/middleware into the middleware chunk, so nothing resolves it at runtime, and build environments install devDeps). But it breaks prune-before-build Docker flows, and code imported by user source that ships in the production bundle is conventionally a dependency — audit and license tooling assume devDeps never reach production. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… pnpm/yarn New-era opening sentence; How-it-works moved below The report so value precedes mechanism; Design posture folded out; the supported matrix drops its out-of-scope column (the intro sentence carries it); install line shows pnpm and yarn. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Aug 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the README around the story instead of the mechanics (596 → ~190 lines):
npx ax init; from then on every build generates the artifacts automatically. Also corrects the install guidance to a regular dependency:@ora-ai/ax/middlewareis imported by usermiddleware.tsand ships in the production bundle (devDependencies only worked by accident of bundling, and breaks prune-before-build flows).ax init, theax.configexample (now showcasing declared auth), repository layout. Design-posture section and deep-dive duplicates folded or cut.Targets
main— #25 (the features this text documents) is already merged.🤖 Generated with Claude Code