Repository navigation
docs(readme): three entry points to the positioning — a Why / How it compares / When to use it line under the demo, two pointer sentences in the ontology section, the deck beside Read why #22952
Description
立卡门类别 ③ — 维护者直派的任务 (maintainer-directed task).
Maintainer ruling (verbatim, untranslated)
github readme 需要修改吗
README 也派
Given in session https://claude.ai/code/session_011hRnra93sK5Q2gTYYTbdJR on 2026-10-12. The seat's answer to the first line was "yes, three small edits, no rewrite"; the second line dispatches it.
Why
The README already opens on the demo GIF and is structured on the four promises, and its "Agents are the first users" section carries the narrative. What it lacks is the door: the essay is linked once, at line 210 inside "You own it", as "Read why"; the compare page and the when-to-use page, live on the site since 2026-10-08, are not linked anywhere in the README; the deck is not linked either. A GitHub visitor's three first questions (why does this exist, how is it different, is it for me) have answers on the site and no entry from the README.
What lands
Three edits to README.md, nothing else in the file; line numbers are main's at filing.
- Entry line under the demo. Inside the centred block that holds the GIF (lines 18 to 24), after the "Watch: ObjectStack in 90 Seconds" line and before the block closes: one more
subline, three links separated by the same · the caption uses: "Why it exists" to https://objectstack.ai/blog/the-ontology-is-the-software, "How it compares" to https://objectstack.ai/docs/concepts/compare, "When to use it" to https://objectstack.ai/docs/concepts/when-to-use. Absolute URLs, like every other site link in the README. - Two pointer sentences in "What we mean by ontology" (the section at lines 77 to 90, which today ends on the Business Ontology and glossary links): one sentence naming where it sits beside knowledge ontologies, semantic layers, operational ontologies, metadata platforms and AI code generation, linking "How it compares"; one sentence on fit, linking "When to use it". The existing sentences do not change.
- The deck beside "Read why" in the quote block at lines 207 to 210: after the "Read why" link, in the same line, "· the talk as a deck (PDF)" linking https://objectstack.ai/decks/the-ontology-is-the-software.pdf.
Net change: at most eight added lines, no removed prose. Everything else in the README, including the architecture image, "Try it in five minutes", the four promise sections, "Ship it", "Hack on the framework", the package directory and Community, stays byte-identical.
Mechanism, with what was measured
- The README is rendered on GitHub and inside the published packages that ship it;
pnpm check:published-readme-linkschecks every relative target in published markdown and leaves absolute URLs alone (measured on PR docs(readme): a 30-second demo GIF opens the README, rendered from a real showcase run #22241: 144 of 144 relative targets found). The three pages and the PDF exist on main:content/docs/concepts/compare.mdx,content/docs/concepts/when-to-use.mdx(PR docs(concepts): add How ObjectStack compares and When to use ObjectStack #22247),content/blog/the-ontology-is-the-software.mdx(PR docs: publish 'The Ontology Is the Software' on the blog, add a Blog entry to the docs nav and home, point README's 'Read why' at it, and bridge the two 2024 posts #21838),apps/docs/public/decks/the-ontology-is-the-software.pdf(PR docs(site): ship the English deck 'The Ontology Is the Software' as a vector PDF under apps/docs/public/decks #22254; PR docs(site): refresh the English deck PDF under apps/docs/public/decks to the 19-slide version #22942 refreshes the file at the same path). - The HTML block the GIF lives in is plain GitHub-flavoured markdown HTML; a
subline with three anchors matches the caption line above it. - Repository topics and the About line are settings-page values, not files; they are not this card's (the About line already reads the four-promise sentence; the topics are the maintainer's click).
Guardrails for the author
- File surface:
README.mdonly, the three hunks above. Nopackages/**, nocontent/**, noapps/docs/**, nodocs/screenshots/**, no CHANGELOG. - English only. No model identifiers anywhere. No new claims, no numbers, no superlatives; link text as given.
- Gates derived with
scripts/pm/dispatch-gates.mjsfrom the real change set (README.md), every one run,pnpm check:published-readme-linksamong them; exit codes captured before any pipe. - Changeset: nothing publishes;
skip-changesetoncepackages/**is confirmed untouched. - Serial constraint: branch from
origin/main; before the final push, list open PRs that touchREADME.md(threecopilot/update-readme-*heads exist on origin; whether any has an open PR is to be read from GitHub, not assumed) and, if one does, confirm the hunks do not overlap; if they overlap, stop and report.
Non-goals
- Rewriting any README prose or section; shortening the package directory; a Chinese README.
- Topics and About (maintainer's clicks). The home page (docs(site): give the core narrative a front door on the home page — a Why link in the hero, a '00 · The idea' section reusing the architecture figure, a Why entry in the top nav, the closing card trimmed #22951) and the blog figures (docs(blog): four hand-drawn SVG figures for 'The Ontology Is the Software' — three interfaces and one user, four places to one definition, the ontology-runtime architecture, the three routes — readable in both themes #22948) are separate cards.
Who acts
domain:devx lane, this seat, one os-dev dispatch at the default tier, one draft PR. Precedent on this file: #22232 via PR #22241 (the demo GIF block this card extends) and #21586 (the four-promise restructure).
Duplicate check (2026-10-12, open and closed)
- Query "README entry links compare page when to use page deck PDF Read why top block positioning": 2 hits — docs(blog): link the English deck PDF from the end of 'The Ontology Is the Software' #22263 (the deck link in the essay, closed) and docs(blog): four hand-drawn SVG figures for 'The Ontology Is the Software' — three interfaces and one user, four places to one definition, the ontology-runtime architecture, the three routes — readable in both themes #22948 (the figures, in flight). Neither touches the README.
Generated by Claude Code
Activity
objectstack-fleet commentedon Oct 12, 2026
Claim: PM loop round 4
Session:
session_011hRnra93sK5Q2gTYYTbdJRAccount:
hotlong(the seat's linked user; the card's assignee)Branch:
claude/issue-22952-readme-entry-pointsWorktree:
objectstack-issue-22952Domain:
domain:devxSeat:
domain:devx#2File surface:
README.md(three hunks named on the card; stop on breach; explain in the report)Container & model:
S,mode:subagent,model: opus (default tier; dispatch-gates --tier: no path-derived mandate for README.md)Clause-②: no
Thread-read: none
Serial constraints cleared: #22948 (in flight) touches
content/blog/andapps/docs/; PR #22942 touchesapps/docs/public/decks/; threecopilot/update-readme-*heads exist on origin, the dev reads GitHub for an open PR on them before the final pushobjectstack-fleet commentedon Oct 12, 2026
os-dev-report
{
"issue": 22952,
"status": "done",
"branch": "claude/issue-22952-readme-entry-points",
"pr": "#22955",
"session": "session_011hRnra93sK5Q2gTYYTbdJR (mode:subagent, the parent's id)",
"premise_still_valid": true,
"summary": "Three README.md hunks landed as written on the card. (1) A sub line under the demo GIF, inside the centred block after the Watch line, with Why it exists / How it compares / When to use it separated by the caption's · . (2) A new paragraph closing 'What we mean by ontology' with two pointer sentences linking the compare and when-to-use pages; the wording restates those pages' own frontmatter descriptions. (3) '· the talk as a deck (PDF)' beside Read why in the 'You own it' quote. All four targets are absolute objectstack.ai URLs. Diff vs base 51b43a8: README.md only, 3 hunks, +8/-1, with no existing sentence removed. PR #22955 is draft; its body was read back byte-identical (5664/5664) and opens with this card's closing line and Clause-②: no. Labels documentation + skip-changeset and assignee hotlong were read back (size/xs was added by the labeler). CI at 6fec6e5 when snapshotted once, not polled: 11 success, 16 skipped, 6 in_progress, 0 failure, so the gates are in_progress.",
"tests": "Docs-only diff; no package touched, so no build, unit test or typecheck is owed and none was run. Gates were derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from the merge base (1 path, README.md; identical to the path-arg derivation). All ran at HEAD 6fec6e5, exit captured before any pipe: check-closing-keyword-parity.mjs exit 0 'OK (3 parsers agree on all 9 keywords...)'; same --self-test exit 0 '40 assertions, 5 mutations...driven to red'; check-comment-mask-corpus.mjs exit 0 '8819 files, 0 disagree, 0 unparseable'; check:doc-anchors exit 0 '484 internal #fragment link(s)...all resolve'; check:driver-memory-census exit 0 OK; check:gitlink-declared exit 0 OK; check:nul-bytes exit 0 'OK (scanned 10974 text file(s)...no raw ASCII control bytes)'; check:refd-timer-probe exit 0 OK; check:watch-hint-literal exit 0 '72 declaration(s)...'. Also, as named by the dispatch: check:published-readme-links exit 0 '226 outbound link(s) across 102 published markdown file(s)...144/144 relative target(s) found'. That green is vacuous for this diff because root README.md is not in its population (publishedDocs() returns 102 docs and root README is absent; the root package is private). --ran reconciliation exit 0: '9 derived, 9 run, 0 NOT-MEASURED, 0 UNRUN' (a DERIVED zero; all 9 recorded exit codes). Link targets were measured directly at base 51b43a8: git cat-file -e found all four files present; the gate's own resolver (pageCandidates/docsRelative from scripts/check-docs-redirects.mjs) maps /docs/concepts/compare and /docs/concepts/when-to-use to their .mdx files, and the negative control /docs/concepts/no-such-page-control maps to NO PAGE. GitHub-rendered README (GET /repos/objectstack-ai/objectstack/readme?ref=BRANCH with the html media type) anchor counts: compare 2, when-to-use 2, essay 2, deck 1; the same read on main has 0 compare anchors (control). Ablation and reverse verification do not apply (no guard or type change).",
"mcp_calls": "0. No MCP GitHub tool was called. Reads went through gh api REST: issue 22952 and its comments; open PR list plus per-PR file lists (18 PRs); pulls?head= for the 3 copilot/update-readme-* heads; the rendered README on the branch and on main; PR 22955 and its files; one check-runs snapshot.",
"api_writes": "3 relay dispatches, each POST /repos/objectstack-ai/objectstack/dispatches, executed as objectstack-fleet[bot]. (1) pr_create, i.e. POST /repos/objectstack-ai/objectstack/pulls (draft), run 38207082939 success. (2) label-write: POST /repos//issues/22955/labels plus POST /issues/22955/assignees, run 38207134592 success. (3) this os-dev-report comment via post-stamped, i.e. POST /repos//issues/22952/comments. Separately, 2 git pushes (empty branch probe, then 6fec6e5), which are not REST writes.",
"deviations": [
"PR body footer: the dispatch asked for two trailing lines (the robot-emoji 'Generated with' line plus the bare session URL). Per AGENTS.md and os-dev.md, which win on conflict, the body instead ends with a blank line, a rule line, and the single session-URL footer Generated by Claude Code. The session URL is carried either way.",
"The dispatch said pnpm check:published-readme-links 'must be among' the derived gates. The derivation for README.md does not place it (9 derived, none of them that gate). It was run anyway as an extra, and its scope gap is recorded in the PR's Acceptance notes.",
"Mechanism assumption 'check:published-readme-links only checks relative targets; absolute URLs are not requested' is half right. The gate makes no network request. It does resolve absolute objectstack.ai/docs URLs against content/docs (its assertion 3), but only for the 102 published package docs, and root README.md is not one of them. This does not change the route, so it was not treated as a fork.",
"Worktree cleanup follows the posting of this comment: node_modules removal, then git worktree remove without --force. The order is forced because the posting script is read from the worktree (the shared checkout's copy of scripts/pm differs)."
],
"open_questions": [],
"out_of_scope_findings": [
"carrier: 承接者:无 · noted, not filed. Observation, not a defect: no CI gate resolves the root README.md's absolute objectstack.ai docs-site links. check:published-readme-links reads only the 102 published package docs (root README absent; the root package is private). The check-links.yml lychee lane globs README.md but runs --offline, which excludes absolute URLs. So a later rename of content/docs/concepts/compare.mdx or when-to-use.mdx would 404 these README links with every gate green. Recorded in PR #22955 Acceptance notes."
]
}
objectstack-fleet commentedon Oct 12, 2026
Review: ACCEPT — PR #22955 at head
6fec6e55Seat
domain:devx#2·session_011hRnra93sK5Q2gTYYTbdJR· reviewed against GitHub and the fetched branch at 2026-10-12T05:19Z, not against the report.PR shape. Draft, base
main(51b43a8d), body opensFixes #22952,Clause-②: noat line start, session-URL footer, no model identifier in body or commit (one commit, model-free trailer pair, no card relation in the message). Labels documentation · size/xs · skip-changeset; assignee matches the card. 1 file, +8 / −1.check-governed-merges.mjs --pr 22955: 0 governed paths, 9 changed lines.The diff, read hunk by hunk against the card. Exactly the three hunks the card names and nothing else. (1) Inside the GIF's centred block, after the "Watch" line: a
brand onesubline with "Why it exists", "How it compares", "When to use it", separated by the caption's own · . (2) A new paragraph closing "What we mean by ontology": one sentence placing ObjectStack beside knowledge ontologies, semantic layers, operational ontologies, metadata platforms and AI code generation, linking the compare page; one sentence on fit, linking the when-to-use page; the existing paragraph byte-identical. (3) The "Read why" line in the "You own it" quote now carries "· the talk as a deck (PDF)" as a second link; the −1 is that line's old form, no sentence removed. All four targets absolute objectstack.ai URLs, and all four exist on main (the two concept pages, the essay, the PDF; the PDF path is the one PR #22942 refreshes in place).Gates. 9 derived commands, all exit 0,
--ranreconciliation 9 / 9 / 0 / 0;check:published-readme-linksrun beside them (exit 0) with its scope gap stated honestly in the PR: the root README is not in that gate's population, so the link targets were measured directly with the docs-site resolver and a negative control, and GitHub's rendered README on the branch carries the new anchors (control on main: none). CI on6fec6e55: everything green or expected skip except Lint & Repo Gates, still in progress at this review; landing waits for it and forcheck-expected-skips.mjs --pr 22955.Deviations from the dispatch, accepted. PR footer in the AGENTS.md form rather than the two-line form the dispatch asked for (AGENTS.md wins).
check:published-readme-linksis outside the derivation forREADME.md; run anyway, scope gap recorded. The mechanism assumption on that gate was half right (no network request, but it does resolve absolute docs URLs for the 102 published docs); it did not change the route.Out-of-scope findings from the report.
Serial constraint. All 18 open PRs read file by file by the developer; none touches
README.md; the threecopilot/update-readme-*heads belong to closed PRs.Contract review: not owed (README only).
Generated by Claude Code
objectstack-fleet commentedon Oct 12, 2026
Landed — PR #22955 merged as
1f312fdfSeat
domain:devx#2·session_011hRnra93sK5Q2gTYYTbdJR· verified onorigin/mainat 2026-10-12T06:28Z.Verified on main.
README.mdcarries the three hunks as reviewed at6fec6e55: the entry line under the demo (Why it exists · How it compares · When to use it), the two pointer sentences closing "What we mean by ontology", and "the talk as a deck (PDF)" beside "Read why"; blob compared to the head and checked by content in case main's README took other landings. The card closed on the merge;pm:dispatchedleaves with this comment.Still the maintainer's, outside this card: repository topics (fourteen set today, none for AI agents or MCP; six slots free) and the About line (already the four-promise sentence).
Generated by Claude Code