Skip to content

docs: rewrite README — problem-first, value-first, half the words - #28

Merged
arielshulman29 merged 3 commits into
mainfrom
docs/readme-rewrite
Aug 27, 2026
Merged

arielshulman29 merged 3 commits into
mainfrom
docs/readme-rewrite

Conversation

@arielshulman29

@arielshulman29 arielshulman29 commented Aug 27, 2026 •

Copy link
Copy Markdown
Collaborator

Rewrites the README around the story instead of the mechanics (596 → ~190 lines):

  1. Problem-first opening — the web was built for humans; a new era of AI agents begins, and most sites are invisible to them.
  2. One-time setup — install (npm/pnpm/yarn) + npx ax init; from then on every build generates the artifacts automatically. Also corrects the install guidance to a regular dependency: @ora-ai/ax/middleware is imported by user middleware.ts and ships in the production bundle (devDependencies only worked by accident of bundling, and breaks prune-before-build flows).
  3. Value-first feature section — six benefit→feature entries (agents.md · markdown twins · AI Catalog + llms.txt · auth detection/declared auth/auth.md · agent-aware 404 + wayfinding · JSON-LD), each honest about mechanism (detect vs. scaffold vs. generate).
  4. The report — the coding-agent loop, mapped to Ora's checks.
  5. How it works — prebuild/postbuild map + runtime middleware, placed after the value sections.
  6. Contract sections kept in trimmed form: status note, supported matrix (out-of-scope column folded into its intro sentence), ax init, the ax.config example (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

arielshulman29 and others added 3 commits August 27, 2026 17:20
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>
@arielshulman29
arielshulman29 changed the base branch from feat/declared-entry-auth to main August 27, 2026 14:43
@arielshulman29
arielshulman29 merged commit 084db4f into main Aug 27, 2026
2 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.

1 participant