docs(readme): rewrite around the AI-writes-it narrative#3121
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
xuyushun441-sys
pushed a commit
that referenced
this pull request
Jul 17, 2026
…g the ratchet #3113's lifecycle walkthrough re-stated a warning the page already makes better 80 lines up (§3 The approval node: position vs the membership tier, including the `os lint` rule that flags it). The duplicate pushed the reserved-word count (ADR-0090 D3) from 5 to 9, so check-role-word failed on every PR cut from main since — #3121 tripped over it. Removing the duplicate and pointing at the original brings the count back to exactly the baselined 5: **no baseline change needed**. The walkthrough keeps a one-line pointer that names the approver kinds and links to the existing callout, which is what a reader needs at that point anyway. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
os-zhuang
added a commit
that referenced
this pull request
Jul 17, 2026
…g the ratchet (#3130) #3113's lifecycle walkthrough re-stated a warning the page already makes better 80 lines up (§3 The approval node: position vs the membership tier, including the `os lint` rule that flags it). The duplicate pushed the reserved-word count (ADR-0090 D3) from 5 to 9, so check-role-word failed on every PR cut from main since — #3121 tripped over it. Removing the duplicate and pointing at the original brings the count back to exactly the baselined 5: **no baseline change needed**. The walkthrough keeps a one-line pointer that names the approver kinds and links to the existing callout, which is what a reader needs at that point anyway. Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
The README opened with a category label ("A metadata protocol and
TypeScript toolkit") and spent its first 100 lines on architecture layers
and protocol theory — none of it the point a visitor is here for. It now
mirrors the landing page (objectstack.ai, #3090) and tells the story the
project is actually about:
- hero: "AI writes the app. ObjectStack is what it writes." + the
correctness chain (typed → validated → reviewed → governed)
- The loop: create → describe to Claude Code → preview in the browser;
requirement changes run the same loop
- What can it actually build? — the 12 metadata capabilities, framed
against the alternative (an agent on an empty repo writes a one-off
codebase; here it composes from a vocabulary the runtime already runs)
- Why the mistakes don't ship — the four gates, why TypeScript was the
right host language (errors become corrective text the agent fixes
itself), and the context-window argument
- Your app is AI-operable, for free — MCP in three lines
- This repo / architecture / ObjectOS cross-link, compressed to the tail
Reference sections (packages, CLI, scripts) are kept as-is. Drops the
stale v4.0.1 version badge (CLI is 15.x — the badge had drifted three
majors). Quick Start's duplicate scaffold snippet folds into the loop.
Also fixes a third missing-braces decision expression in flows.mdx:155
(same class as the two fixed in #3113 — without braces the comparison
degrades to a string compare that never matches as intended).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
xuyushun441-sys
force-pushed
the
docs/readme-rewrite
branch
from
July 17, 2026 12:23
9ba9153 to
e4c011f
Compare
github-actions
Bot
added
the
documentation
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
1 participant
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.
背景
用户反馈:"目前开源项目的 docs、readme 我觉得写的很多不是重点"。README 开头是类目词("A metadata protocol and TypeScript toolkit"),前 100 行讲架构分层与协议理论——都不是访客来这里要看的东西。本 PR 按已定稿的叙事(landing v2 / #3090)重写。
新结构(与首页同构)
npx os dev --ui浏览器预览;需求变更同一循环参考性章节(Package Directory / CLI / Monorepo Scripts)原样保留。
顺带
🤖 Generated with Claude Code