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

Activity

1. objectstack-fleet

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   domain:devx

   pm:blocked

   on Oct 12, 2026
2. objectstack-fleet commented on Oct 12, 2026

   

   objectstack-fleetbot

   on Oct 12, 2026

   ContributorAuthor

   More actions

   Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-12T05:05Z. ⛔ Not a claim, ⛔ not a dispatch. Grade completed: priority:p2 and area:devpath added.

   • The card is maintainer-directed (gate ③, verbatim ruling quoted), and its Blocked-by: #22948 (dispatched) stands. The state stays pm:blocked.
   • Why p2: a published surface (the docs home page), directed by the maintainer, and not release-gating.
   • Lane: apps/docs is domain:devx, as filed.
3. objectstack-fleet

   added

   area:devpathThe road — create, dev, verify, publish/install, connect an agent, iterateThe road — create, dev, verify, publish/install, connect an agent, iterate

   priority:p2Medium: important, M3Medium: important, M3

   pm:queue

   pm:dispatched

   and removed

   pm:blocked

   pm:queue

   on Oct 12, 2026
4. objectstack-fleet

   assigned

   hotlong

   on Oct 12, 2026
5. objectstack-fleet commented on Oct 12, 2026

   

   objectstack-fleetbot

   on Oct 12, 2026

   ContributorAuthor

   More actions

   Claim: PM loop round 4
   Session: session_011hRnra93sK5Q2gTYYTbdJR
   Account: hotlong (the seat's linked user; the card's assignee)
   Branch: claude/issue-22951-home-why
   Worktree: objectstack-issue-22951
   Domain: domain:devx
   Seat: domain:devx#2
   File surface: apps/docs/app/[lang]/page.tsx, apps/docs/lib/layout.shared.tsx (stop on breach; explain in the report)
   Container & model: M, mode:subagent, model: opus (default tier; dispatch-gates --tier: no path-derived mandate)
   Clause-②: no
   Thread-read: none
   Serial constraints cleared: Blocked-by #22948 cleared (PR #22958 merged); no open PR touches the home page or the nav config
6. objectstack-fleet commented on Oct 12, 2026

   

   objectstack-fleetbot

   on Oct 12, 2026

   ContributorAuthor

   More actions

   os-dev-report

   {
     "issue": 22951,
     "status": "done",
     "branch": "claude/issue-22951-home-why",
     "pr": "https://github.com/objectstack-ai/objectstack/pull/22974",
     "session": "session_011hRnra93sK5Q2gTYYTbdJR (subagent run; the parent seat's harness-stamped id, as on the commit trailers)",
     "premise_still_valid": true,
     "summary": "All four ruled items landed in the two named files (diff --stat vs base 246edf5b: 2 files, +61/-11). (1) Hero: a text link 'Why the ontology is the software' with an ArrowRight, between the four-promise paragraph and the unchanged four-button row. (2) New '00 · The idea' section between the hero and '01 · The loop', in the 01-03 shape. It holds OntologyRunsFigure imported from @/components/figures (not copied), the three ruled sentences verbatim (byte-compared with the card body) and 'Read the essay', whose className is byte-identical to 'Browse the full vocabulary in the docs'. (3) Nav: { text: 'Why', url: ESSAY_URL, active: 'url' } before Blog. (4) Closing card: the long-form sentence and its link are gone; the slogan and ObjectOS lines are unchanged. Two choices of mine, flagged in the PR's Acceptance notes. The ruling named an h2 slot but no text, so the h2 is the essay's own heading over this figure ('Why code recedes'), and the caption is the essay's own caption for the figure, verbatim. The essay route became one constant, ESSAY_URL in lib/layout.shared.tsx, read by the nav and both page links. All four mechanism assumptions re-verified at 246edf5b: figure export and signature, server component with lg split; lychee argv scoped to content/**; sitemap lists /blog and the posts. Browser pass on the production build, light and dark x 1280 and 390, each with the right html theme class and no horizontal scroll. Hero link 251x24, 20 px under the paragraph, 33 px above the buttons, contrast 18.2:1 light / 15.7:1 dark. Figure: wide SVG 846x341 in an 896x391 plate at 1280; stacked SVG 316x507 in a 342x533 plate at 390; text fill flips with the theme. Caption 14 px italic, one line at 1280, two at 390. Sentences: three columns at 1280, stacked at 390. Nav Why sits at x=170 before Blog at x=222 at 1280; at 390 it is inside Toggle Menu above Blog. The closing card carries zero essay links. One overclaiming comment line I had added was removed in a second commit (011e8dfe): it said the Why entry lights on its own page, and the build does not deliver that (finding 1 below). Teardown: the next-server tree I started (pids 4675/4713/4724/4740) is killed and port 39417 answers 000. Screenshots stay in the scratchpad, uncommitted. The worktree is removed right after this comment is posted: node_modules first, no --force.",
     "tests": "Head 011e8dfe unless stated. (a) Production build command from apps/docs/vercel.json, under os-verify-lock: 'pnpm turbo run build --filter=@objectstack/docs --concurrency=2' printed 'Tasks: 2 successful, 2 total', 'Cached: 0 cached, 2 total' and BUILD_ID_PRESENT, with 'VERDICT command-exit 0 · held the lock 234s'. (b) 'pnpm --filter @objectstack/docs build' at ba94665b (the only later commit deletes one comment line): 'VERDICT command-exit 0 · held the lock 180s'; git status stayed clean after the generators. (c) 'pnpm --filter @objectstack/docs typecheck': 'VERDICT command-exit 0'; 'tsc --noEmit --listFilesOnly' lists both touched files (count 2). (d) Gates: 'node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack', no paths, change set from merge base 246edf5b3 (2 paths). 27 commands, each run with its exit captured before any pipe, all 27 exit 0. '--ran' with exit codes recorded reads 'Run reconciliation — 27 derived, 27 run, 0 NOT-MEASURED, 0 UNRUN' and 'a DERIVED zero — all 27 recorded an exit code and none of them is 3'. Sample verdict lines: 'check-nul-bytes: OK (scanned 10994 text file(s) ... no raw ASCII control bytes)'; 'check-doc-frontmatter: 2 content root(s) verified'; 'check:published-files — 70 publishable package(s)'. (e) eslint, a declared narrowing to the touched files. Population read from eslint's own config: isPathIgnored false for both, calculateConfigForFile shows 3 active rules. 'eslint --no-inline-config --format json' counts 2 files, 0 errors, 0 warnings, 0 fatal. Invariance: neither file gets parserOptions.project or projectService (both null), so linting is untyped and per-file, and this diff cannot move any untouched file's verdict. Repo-wide pnpm lint belongs to CI. (f) Browser, as in summary, via @playwright/test resolved from examples/app-showcase and executablePath /opt/pw-browsers/chromium; no playwright install. NOT MEASURED, left to CI: the lint.yml type-check lanes (workspace turbo typecheck over packages and apps, examples, downstream-contract), the 53 artifact-roster and 11 wide-population families dispatch-gates lists outside its 27, and the 14 changeset-pending families, which do not apply because there is no changeset. No ablation or reverse verification: no type or contract change, and none is owed for a page edit.",
     "mcp_calls": "0 — no MCP GitHub tool called; reads went through gh api GET (issue 22951, its comments, pull 22974)",
     "api_writes": "3 relay writes plus 3 git pushes. Writes, all as objectstack-fleet[bot] through scripts/pm/fleet-write (POST /repos/objectstack-ai/objectstack/dispatches): (1) pr_create, executed as POST /repos/objectstack-ai/objectstack/pulls with draft forced, giving #22974; read-back 6672 bytes sent and stored, identical. (2) label-write --issue 22974 --assign hotlong --add skip-changeset --add documentation, executed as POST .../issues/22974/labels and POST .../issues/22974/assignees; read-back documentation, size/s (size-labeler's), skip-changeset; assignee hotlong. (3) This os-dev-report comment via post-stamped --comment=22951. Pushes, which are not REST writes: the empty-branch probe, ba94665b, 011e8dfe. The budget names one push line; three pushes is the mandated probe plus one per commit.",
     "open_questions": [],
     "out_of_scope_findings": [
       "class: a · reach: public door, the built site over HTTP. GET /blog/context-window-is-the-constraint serves the nav anchor href=/blog with data-active=false, although baseOptions declares it active: 'nested-url'. GET /blog/the-ontology-is-the-software serves both Why (active: 'url') and Blog with data-active=false. GET /blog serves Blog data-active=true. All three were measured on this branch's production build, both server HTML and after hydration; the Blog line is unchanged by this diff. Evidence: .next/prerender-manifest.json lists the posts as /en/blog/SLUG, so they are prerendered under the internal lang-prefixed path. fumadocs-ui isLinkItemActive / isActive (dist/utils/urls.js) compares the url against usePathname, which during that prerender is /en/blog/SLUG, and hydration does not repaint the attribute. /blog renders on demand and matches. Consequence: the ruled Why highlight never shows, and Blog never lights on a post. File surface for a fix: apps/docs (proxy rewrite or prerender path vs nav active matching). Dedupe words: nav active, nested-url, data-active, prerender /en/blog, usePathname",
       "carrier: none (承接者:无) · noted in the PR's Acceptance notes, not filed: apps/docs/components/figures/primitives.tsx Figure gives its figcaption only 'text-center italic' and relies on the blog's prose wrapper for spacing, size and colour. The home page compensates from its own wrapper div ([&_figcaption]:mt-3 text-sm text-fd-muted-foreground). Any later consumer outside prose meets the same thing.",
       "carrier: none (承接者:无) · noted in the PR's Acceptance notes, not filed: light-mode nav links (Why and Blog alike, the fumadocs nav token text-fd-muted-foreground at 14 px) measure 4.35:1 against the nav bar, under 4.5:1; dark is 9.0:1. Pre-existing and unchanged here."
     ],
     "deviations": [
       "Instruction conflict: the dispatch's step 3 says to pass the changed paths to dispatch-gates; .claude/agents/os-dev.md says not to pass paths and to let the script derive from the merge base. I followed os-dev.md. The script derived the same 2 paths and printed its own provenance line.",
       "Instruction conflict: the harness attribution reminder asked for a model-named Co-Authored-By trailer and a different PR footer. I followed AGENTS.md, os-dev.md and the dispatch: the model-free trailer pair on both commits (the pre-push trailer check passed) and the session-URL footer on the PR body.",
       "Beyond the four items, within the two-file surface: one exported constant ESSAY_URL in lib/layout.shared.tsx, so the essay route is spelled once for the nav and the page.",
       "The first gate-run attempt, a shell loop using bash -c over a variable, was refused by a built-in safety check before anything ran. It was re-run as a literal script whose 27 lines are listed in the scratchpad (tools/run-gates.sh). No removal was involved or attempted."
     ]
   }

   ---

   Generated by Claude Code
7. objectstack-fleet commented on Oct 12, 2026

   

   objectstack-fleetbot

   on Oct 12, 2026

   ContributorAuthor

   More actions

   Append to the os-dev report above (not a new report). PR #22974's branch is now at 39bafe84, with one line changed in apps/docs/app/[lang]/page.tsx: section 00's h2 "Why code recedes" becomes "An ontology written clearly enough runs directly", the deck's thesis title. The eyebrow, figure, caption, three sentences, "Read the essay", nav and closing card are untouched.
   Gates at 39bafe84: pnpm --filter @objectstack/docs typecheck under os-verify-lock answered VERDICT command-exit 0. eslint narrowed to page.tsx (--format json) found 1 file, 0 errors, 0 warnings. pnpm check:nul-bytes exited 0.
   I did not edit the PR body: os-dev.md has the dev write it once, at creation, and name later edits here for the seat to write. Edits for the seat: (1) in "What changed" item 2, after "h2 in --l-display)", add: The h2 reads "An ontology written clearly enough runs directly", the deck's thesis title. (2) In "Acceptance notes", replace the first bullet with: - **Section 00's heading is the deck's thesis title, and the figure caption is the essay's own caption for this figure, verbatim.** Either is a one-line swap if a different wording is wanted.

   ---

   Generated by Claude Code
8. objectstack-fleet commented on Oct 12, 2026

   

   objectstack-fleetbot

   on Oct 12, 2026

   ContributorAuthor

   More actions

   Review: ACCEPT — PR #22974 at head 39bafe84

   Seat domain:devx#2 · session_011hRnra93sK5Q2gTYYTbdJR · reviewed against GitHub, the fetched branch and the developer's screenshots at 2026-10-12T07:28Z, not against the report.

   PR shape. Draft, base main (246edf5b), body opens Fixes #22951, Clause-②: no, session-URL footer, no model identifier in body or commits (three commits, model-free trailer pair). Labels documentation · size/s · skip-changeset; assignee matches the card. 2 files, +61 / −11 at the first reviewed head, plus one line at 39bafe84. check-governed-merges.mjs --pr 22974: 0 governed paths, under the human-merge threshold.

   File surface, exactly the card's. apps/docs/app/[lang]/page.tsx and apps/docs/lib/layout.shared.tsx; no new component (the figure is imported from @/components/figures, landed by PR #22958), no content/**, README.md, packages/**, apps/docs/public/**.

   The four items, read on the diff and on the screenshots (light and dark, 1280 and 390). (1) Hero: "Why the ontology is the software" with the arrow, between the four-promise paragraph and the unchanged four buttons. (2) 00 · The idea between the hero and 01 · The loop, in the 01 to 03 shape: OntologyRunsFigure with the essay's own caption, the three ruled sentences byte-identical to the card, "Read the essay" in the vocabulary link's style. The h2 is "An ontology written clearly enough runs directly" (the deck's thesis title), changed at 39bafe84 on the seat's review from the essay's section heading, which read without context on the home page; the one-line change re-ran docs typecheck (exit 0), narrowed eslint (0/0) and nul-bytes (exit 0). (3) Nav: Why before Blog, active: 'url', the essay route as one constant ESSAY_URL read by the nav and both page links. (4) Closing card: the long-form sentence and link gone, the slogan and ObjectOS lines unchanged. HOME_TITLE, HOME_DESCRIPTION and the metadata blocks untouched.

   Measurements from the first head, unchanged by the one-line edit except the h2's wrap. Hero link 251 × 24 px, contrast 18.2:1 light / 15.7:1 dark; figure 846 × 341 at 1280 and 316 × 507 stacked at 390, text fill flips with the theme; three sentences in three columns at 1280 and stacked at 390; nav Why at x=170 before Blog at 1280 and inside the menu at 390; no horizontal scroll at 390; zero essay links left in the closing card.

   Gates. Production build (vercel.json's turbo command) under the verify lock exit 0; docs build and typecheck exit 0; 27 derived commands all exit 0, --ran 27 / 27 / 0 / 0; narrowed eslint 2 files, 0 / 0 with the untyped-lint invariance read from the config. CI on 39bafe84 still running at this review; landing waits for it and for check-expected-skips.mjs --pr 22974.

   Deviations, accepted. Gate derivation without paths (os-dev.md wins over the dispatch's wording; same two paths derived). PR body not patched after the h2 change (os-dev.md: the body is written once); the body's item 2 and first acceptance note still name the earlier h2 text, and this comment is the record of the final one. ESSAY_URL as one exported constant, within the two-file surface.

   Out-of-scope findings from the report.

   • The nav never lights on a blog post (Blog with nested-url, and the new Why with url): posts prerender under /en/blog/SLUG and fumadocs matches the link url against that pathname → filed docs(site): the top nav never lights on a blog post — posts prerender under /en/blog/SLUG, so the nav's url and nested-url matching against usePathname fails for Blog and for the new Why entry #22977 (class a, reach measured on the production build with /blog as the control).
   • Figure's figcaption relies on the blog's prose wrapper for spacing and colour; the home page compensates in its wrapper → Acceptance notes (no user-visible defect).
   • Light-mode nav links measure 4.35:1 against the nav bar, pre-existing and unchanged → Acceptance notes (observation; the fumadocs token, not this PR's).

   Contract review: not owed (docs site page and nav config).

   ---

   Generated by Claude Code
9. objectstack-fleet

   closed this as completedin #22974on Oct 12, 2026
10. objectstack-fleet commented on Oct 12, 2026

    

    objectstack-fleetbot

    on Oct 12, 2026

    ContributorAuthor

    More actions

    Landed — PR #22974 merged as 712361b7

    Seat domain:devx#2 · session_011hRnra93sK5Q2gTYYTbdJR · verified on origin/main at 2026-10-12T07:58Z.

    Verified on main. apps/docs/app/[lang]/page.tsx and apps/docs/lib/layout.shared.tsx are byte-identical to the reviewed head 39bafe84: the hero's "Why the ontology is the software" link, the 00 · The idea section (the architecture figure, the three sentences, "Read the essay", headed "An ontology written clearly enough runs directly"), the Why nav entry before Blog, and the closing card without the long-form link. Live on https://objectstack.ai once the site deploys from this main. The card closed on the merge; pm:dispatched leaves with this comment.

    Filed from this card's report: #22977 — the top nav never lights on a blog post (posts prerender under /en/blog/SLUG), which also keeps the new Why entry from showing as current on the essay. Awaiting first grading.

    ---

    Generated by Claude Code
11. objectstack-fleet

    removed

    pm:dispatched

    on Oct 12, 2026