docs: three contributor instructions contradict each other — dev port (AGENTS.md "must be 3000" vs getting-started auto-shift and OS_PORT), scaffold command (npm create vs npx create-objectstack), setup (pnpm run setup vs pnpm install && pnpm build)

Filing gate ③: a maintainer-directed task. Maintainer, 2026-10-26, verbatim: 「完整的评估本项目，还有哪些可以优化的地方。包括 ci 和文档」 then 「使用 pm-dispatch 技能创建 issue，需要决策的立为决策卡。」 and 「低优先级的先不考虑」. Batch-of: 19 (repository evaluation 2026-10-26, session_019a9XCWsbMFp75REzthE6cs; 9 decision cards + 10 execution cards). ⛔ Filed bare: grading, domain:* and area:* are triage's. ⛔ Not a claim. Reader: the domain:devx execution seat — one os-dev, one PR; the AGENTS.md line is Tier H and #26035 is rewriting that same section now, so the AGENTS.md half rides #26035's PR or serializes behind it. Dedupe: REST list (439 issues), grep OS_PORT|PORT=3000|npx create-objectstack|pnpm run setup → 1 unrelated hit (#25581, dist-tags). #26035 (open, dispatched) covers the objectui pin text in AGENTS.md, not these three contradictions. New.

谁付代价（业务筛）: a new developer follows one page, a seat follows another, and they disagree about the port the UI reaches, the command that creates a project, and the command that sets up the repo. Documentation that says two things is a product defect under North Star item 4.

Measured (HEAD `0d83ee8`)

Port and env var. AGENTS.md:138: the dev-server port "must be 3000 (UI hard-wired)" and the spelling is PORT=3000 pnpm dev. content/docs/getting-started/index.mdx:207-212: the dev server auto-shifts to a free port and PORT is the legacy alias of OS_PORT. AGENTS.md Prime Directive 9 (:202) requires the OS_ prefix on ObjectStack-owned env vars. Which is true is a code reading: grep -rn "OS_PORT\|process.env.PORT" packages/cli/src packages/runtime/src examples/*/package.json.
Scaffold command. README.md:50 and content/docs/getting-started/your-first-project.mdx:43: npm create objectstack@latest; content/docs/getting-started/index.mdx:169: npx create-objectstack my-app. Both work; one spelling should be canonical (the README's is the one the North Star names: 「npm create objectstack」).
Setup command. AGENTS.md:40: pnpm run setup ("first-time: install + build spec"); CONTRIBUTING.md:52-57 and README.md:249-252: pnpm install then pnpm build. Read package.json setup to see what it actually runs and whether the two sequences are equivalent.

Wanted

For each of the three: read the code, pick the true statement, and make every page say it. ⛔ Not a third wording: the fix is one sentence in one place quoted by the others, or the same sentence in each.
Port: if PORT is a deprecated alias, AGENTS.md says OS_PORT=3000 and the readEnvWithDeprecation note; if the UI really hard-wires 3000, getting-started says so.
Scaffold: the North Star's spelling wins unless the code says otherwise.
The AGENTS.md edits are Tier H; coordinate with docs(devx): 32 files still prescribe the retired objectui pin scripts (objectui:build / objectui:refresh) — AGENTS.md and 3 skills among them #26035's branch to avoid two PRs on the same lines.

Acceptance

grep -rn 'PORT=3000\|OS_PORT\|npx create-objectstack\|npm create objectstack\|pnpm run setup' AGENTS.md README.md CONTRIBUTING.md content/docs/getting-started/ shows one spelling per fact; the PR body quotes the code line that decided each.

Size: S. Clause-②: no. Metadata-protocol: none.

devx seat 2 · released: the half outside AGENTS.md landed in PR #26248, and its content on main matches the reviewed head dcabcaf2ad. Back to pm:queue for what remains: the AGENTS.md lines that still disagree with the code. Line 40 says pnpm run setup is the first install. Line 138 says PORT=3000 and "must be 3000 (UI hard-wired)". Line 173 is the ../objectui section's PORT=3000. AGENTS.md is a governed surface, so that PR needs a GOVERNED_APPROVERS approval and should follow #26035, #26216 and #26230, which are editing it now.

Generated by Claude Code

devx seat 2 · half-state corrected: this card went back to pm:queue at 6423618476 but kept the os-steve assignee, which seat 3 read as a half-state (#20163, 6430825199). Assignee removed; nothing is in flight here. What remains is unchanged: AGENTS.md lines 40, 138 and 173 (governed), after #26035.

Generated by Claude Code

devx seat 2 · pm:retriage: the remainder is domain:skills · 2026-10-28T00:30Z

⛔ Not a claim. The remainder after PR #26248 is only AGENTS.md L40 / L138 / L173 (6423618476). AGENTS.md is a governed surface, and the SKILL.md lane table puts the whole governed surface under domain:skills (the governed definition includes AGENTS.md + CLAUDE.md). The anchor rule makes domain:* the lane of the files the fix lands in. So the whole remainder is in the domain:skills tree. An execution seat may relabel only into its own tree, so this asks triage: please move this card to domain:skills. The maintainer raised the same point in devx seat 2's session, verbatim: 「AGENTS.md 不是应该归 skills 车道吗？」.

Serial note for the skills seat: AGENTS.md is at its line ceiling (0 headroom; check:pm-skill-ratchet). PR #26970 (#26073) edits AGENTS.md L7 and Prime Directive 8 and is approved, landing after #26975. #26081 PR 1 (also pm:retriage to skills) touches the same file, so the skills seat orders the two.

Generated by Claude Code

Triage: retriage → `domain:skills` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-28T00:57Z

⛔ Not a claim.

Answers the domain:devx#2 request (00:31Z). The remainder after PR docs: one scaffold spelling and one dev-port sentence for contributors #26248 is AGENTS.md L40 / L138 / L173 only. AGENTS.md is governed surface, and the lane table puts it in domain:skills. The maintainer asked the same in devx seat 2's session: 「AGENTS.md 不是应该归 skills 车道吗？」.
This move does not wait on decision card [Decision] Is "governed" a lane or an approval tier? The lane table gives .github/workflows/** to skills and to spec, while devx carries the AGENTS.md and workflow cards in practice #26997 ("lane or approval tier"): both its letters A and B put AGENTS.md in domain:skills. If the ruling moves anything else, triage relabels then.
For the skills seat: AGENTS.md is at its line ceiling (0 headroom), and PR docs: one North Star — docs/NORTH-STAR.md; the architecture page moves to concepts/architecture-overview #26970 ([Decision] Two different documents are both called the "North Star" and four pointers disagree on which outranks AGENTS.md; the one that does is Chinese-only #26073) edits the same file and is approved. Serial behind it.
domain:devx → domain:skills. p2 and pm:queue kept, pm:retriage removed.

Generated by Claude Code

Claim: PM loop round 1 (takeover shift, wave 2) · 2026-10-28T05:14Z
Session: session_01QSeKYmhU5KEj1nukYhp1Tg (seat; implementation by an os-dev subagent of this session, mode:subagent — same session ID, identity by branch)
Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-26088-agents-md-contributor-instructions
Worktree: objectstack-issue-26088
Domain: domain:skills
Seat: domain:skills#2 (seat post #19287)
File surface: AGENTS.md only — the remainder the devx seat left (6423618476): L40 (pnpm run setup), L138 (the dev-server table row: 「Port must be 3000 (UI hard-wired)」) and the ui fast-iteration paragraph (today L168–173: 「run the backend you're testing on :3000 (PORT=3000 pnpm dev …)」), each reconciled to what the code does and edited IN PLACE (AGENTS.md is at its line ceiling per the devx seat's reading — the dev measures with pnpm check:pm-skill-ratchet; no new line); ⛔ content/docs/**, README.md, CONTRIBUTING.md untouched (the non-AGENTS half landed in PR #26248). Tier H (AGENTS.md): draft PR, governed approval; the surface-owed contract review at CONTRACT_REVIEW_TIER is the seat's. (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: TIER_DEFAULT (reason: dispatch-gates --tier --repo objectstack-ai/objectstack AGENTS.md at fbc16563 prints no path-derived mandate: the surface hits none of the 4 declared glob(s); three in-place sentence corrections whose truth is read off package.json, the CLI and the ui proxy — judgement, not mechanics, hence the default tier not the floor), effort: high
Clause-②: no
Metadata-protocol: none
Responsibility: n/a — not a defect card (filing gate ③, maintainer-directed: 「完整的评估本项目 … 包括 ci 和文档」)
Thread-read: 6457775813
Premise: holds, with the seat's readings for the dev to confirm — on origin/main fbc16563 (2026-10-28T05:10Z): L40 reads pnpm run setup # first-time: install + build spec, and the root package.json setup script IS pnpm install && pnpm --filter @objectstack/spec build (so L40 is true today; the contradiction the card names is with content/docs/getting-started's pnpm install && pnpm build, already landed by PR #26248 — the dev decides whether L40 needs any word at all and says so); L138 still says 「Port must be 3000 (UI hard-wired)」 while content/docs/getting-started/index.mdx L211–212 documents OS_PORT=3001 pnpm dev (PORT the legacy alias) and the ui console proxy reads DEV_PROXY_TARGET || http://localhost:3000 — "hard-wired" is false, "defaults to 3000" is true; the old L173 (../objectui section) no longer exists — its successor is the fast-iteration paragraph L168–173 spelling PORT=3000 pnpm dev, the legacy alias where OS_PORT is the documented name. PR #26970 (#26073) merged 2026-10-28T02:09Z and edited L7 / PD 8 only.
Serial constraints cleared: no open PR touches AGENTS.md (file scan of 48 open PRs at 2026-10-28T03:58Z and of the 23 opened since, at 2026-10-28T05:08Z; control: #27067's lint.yml found); #26081 PR 1 (TOC + docs/agents/) queues BEHIND this PR on the same file, as triage 6457763909 ordered; #26035, #26216, #26230 named in the remainder note are closed.
Resume-from: none

os-dev-report

{
  "issue": 26088,
  "status": "done",
  "branch": "claude/issue-26088-agents-md-contributor-instructions",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/27094",
  "head": "596cd15e35f1560ec0c7f0e8ff99197df1191a58",
  "session": "session_01QSeKYmhU5KEj1nukYhp1Tg",
  "premise_still_valid": true,
  "summary": "AGENTS.md remainder of the card, in place, no line added. L40 keeps `pnpm run setup` but drops 'first-time': package.json:18 is install + spec build only, and `pnpm dev`'s preflight prescribes `pnpm install && pnpm build` (scripts/check-dev-prereqs.mjs:579), as README/CONTRIBUTING/getting-started already say; so PM hypothesis 1 was half right (the description was true, the 'first-time' label was the disagreement). L138 drops 'Port must be 3000 (UI hard-wired)': dev.ts:481 reads --port, then OS_PORT, then the legacy PORT (readEnvWithDeprecation, silent); :537 defaults it to 3000; :562 shifts off a busy port even when the port was requested explicitly (serve.ts:2307, dev mode only); the Console proxy is DEV_PROXY_TARGET || http://localhost:3000 (ui/apps/console/vite.config.ts:1509). The row now says 3000 is the default the proxy targets, a busy port shifts, read the printed port, PORT is the legacy alias, and both commands spell OS_PORT=3000. The fast-iteration paragraph (L170-171) spells OS_PORT=3000 pnpm dev, rewrapped within its own six lines to stay under the 120-byte prose rule. L145 ('never run two backends on port 3000') was left as is: it does not repeat the hard-wired claim, and it is still sound under auto-shift.",
  "files_changed": ["AGENTS.md"],
  "line_budget": "AGENTS.md 1112 -> 1112 lines (ceiling 1112, headroom 0, unchanged); +4/-4. Bytes per edited line (no newline), before -> after: L40 99 -> 123 (inside the bash fence, exempt class `fence` of the 120-byte rule); L138 307 -> 506 (table row; widest-row pin 768 is held by L709, unchanged); L170 117 -> 116; L171 114 -> 118. No re-wrap bought a line.",
  "tests": "Docs-only diff to one governed instruction file. No package touched, so no step-1 closure build, no package test or typecheck owed, and no ablation (no tested behaviour moved). Card acceptance grep `grep -n 'PORT=3000\\|OS_PORT\\|npx create-objectstack\\|npm create objectstack\\|pnpm run setup' AGENTS.md` at 596cd15e: L40 (setup, now described accurately), L138 and L170 (OS_PORT=3000 only); bare PORT=3000 gives zero hits, and 'hard-wired' appears only as 'not hard-wired'. Control-byte self-scan of AGENTS.md: 0 hits.",
  "gates": "All local readings at head 596cd15e. Derivation: `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (no paths; 1 path vs merge base fbc16563a) derived 15 gates, and every one exited 0, each exit captured before any pipe. The 15: closing-keyword-parity and its --self-test, comment-mask-corpus, check:agent-test-spelling, docs-audit-scope, driver-memory-census, gitlink-declared, nul-bytes, pm-governed-merges, pm-governed-prose, pm-skill-id-lint, pm-skill-ratchet, refd-timer-probe, required-contexts, watch-hint-literal. Named in the dispatch, outside the derivation: check:doc-authoring exit 0; `node scripts/check-published-list-mirrors.mjs --self-test` exit 0 (37 cases) and the scan exit 0. Reconciliation `--ran` (recorded as `cmd :: exit N`): 15 derived, 15 run, 0 NOT-MEASURED, 0 UNRUN, a DERIVED zero; 3 runs are recorded outside the derivation. Ratchet reading for AGENTS.md: 1112 lines (ceiling 1112; headroom 0); widest table row 768 bytes (pin 768; headroom 0); prose 120-byte rule green. PR check-runs, one snapshot right after the PR opened: 24 runs, 15 in_progress, 2 success, 7 skipped, 0 failing. CI was not awaited.",
  "dogfood_battery": "n/a: no `!` in the PR title, and Clause-② is `no` with no (narrowing) arm",
  "mcp_calls": "0",
  "api_writes": "2 relay strokes as objectstack-fleet[bot], plus git push (not a REST write). 1) pr_create, request fw-20261028T052930Z-e962b5, run 40638299834 success: POST /repos/objectstack-ai/objectstack/pulls (draft forced), POST /repos/objectstack-ai/objectstack/issues/27094/assignees [os-justin], POST /repos/objectstack-ai/objectstack/issues/27094/labels [skip-changeset], and the relay's governed-review follow-up requesting reviewers hotlong, os-zhuang. Read-back: body 6632 sent / 6632 stored, identical; assignees os-justin. A REST read of the pull shows draft true, labels [skip-changeset]. 2) This os-dev-report comment, via post-stamped: POST /repos/objectstack-ai/objectstack/issues/26088/comments.",
  "deviations": [
    "The harness attribution asked for a `Co-Authored-By` trailer that names the model. AGENTS.md (commit message clause) and os-dev.md require a model-free pair, and the pre-push hook refuses a model identifier. So the unpushed commit was amended to `Co-authored-by: Claude` + `Claude-Session:` before its first push. No force push.",
    "The dispatch named `pnpm check:published-list-mirrors`. No such pnpm script exists: exit 254 means the script name is unknown, not that the gate is red. I ran the real gate as CI does (lint.yml:3606-3607): `node scripts/check-published-list-mirrors.mjs --self-test` and the scan, both exit 0.",
    "test:repo was not run locally: no package or vitest repo-project file was touched, and the derivation does not name it. It is left to CI's Test Core."
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "carrier: none · noted in the PR's Acceptance notes, not filed: examples/README.md:42 carries the same `pnpm run setup # first-time: install + build spec` label. It is outside this card's AGENTS.md-only surface and its acceptance grep, and is doc wording, not a filing class. Dedupe words: pnpm run setup, first-time, examples README",
    "carrier: none · noted in the PR's Acceptance notes, not filed: ui/AGENTS.md:221 (Tier H) spells the legacy `PORT=3000 pnpm dev` / `PORT=3000 pnpm dev:crm`. The alias still works (readEnvWithDeprecation), so this is spelling drift, not a defect. Dedupe words: PORT=3000, OS_PORT, ui/AGENTS.md, DEV_PROXY_TARGET"
  ]
}

ACCEPT → PR #27094 comment 6461543190 · domain:skills#2 · 2026-10-28T05:36Z — ⛔ not a claim. Contract review (CONTRACT_REVIEW_TIER) PASS → PR comment 6461532559 on head 596cd15e. Tier H: the PR stays draft until a GOVERNED_APPROVERS approval (hotlong, os-zhuang requested by the relay); the seat lands it on that record and the card closes with the merge (Fixes #26088). Left outside the card, noted not filed: examples/README.md L42 (the same 「first-time」 label) and ui/AGENTS.md L221 (legacy PORT=3000).

Landed · domain:skills#2 · session_01QSeKYmhU5KEj1nukYhp1Tg · 2026-10-28T06:38Z

probe	reading
PR #27094	`merged: true`, merge commit `53e0663df` (approved, readied, armed and enqueued by `os-zhuang` on head `596cd15e` at 2026-10-28T06:12Z; the seat flipped nothing)
`origin/main`	carries `53e0663df` (`git merge-base --is-ancestor` exit 0); `AGENTS.md` on main spells `OS_PORT=3000` and says the port is 「not hard-wired」
records on the merged head	contract review PASS 6461532559 (`CONTRACT_REVIEW_TIER`), seat ACCEPT 6461543190, dev report 6461486644

Landing path: Tier H (AGENTS.md) — the maintainer's hand on an authorized approval. Fixes #26088 closed the card (its docs half had landed in PR #26248); pm:dispatched stripped in this act. Noted, not filed: examples/README.md L42 (the same 「first-time」 label) and ui/AGENTS.md L221 (legacy PORT=3000) — spelling drift, carried in the round report. #26081 PR 1 (the AGENTS.md TOC) is now unblocked on this file.

Navigation Menu

Repository navigation

docs: three contributor instructions contradict each other — dev port (AGENTS.md "must be 3000" vs getting-started auto-shift and OS_PORT), scaffold command (npm create vs npx create-objectstack), setup (pnpm run setup vs pnpm install && pnpm build) #26088

Measured (HEAD `0d83ee8`)

Wanted

Acceptance

Related

Triage: retriage → `domain:skills` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-28T00:57Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs: three contributor instructions contradict each other — dev port (AGENTS.md "must be 3000" vs getting-started auto-shift and OS_PORT), scaffold command (npm create vs npx create-objectstack), setup (pnpm run setup vs pnpm install && pnpm build) #26088

Description

Measured (HEAD 0d83ee8)

Wanted

Acceptance

Related

Activity

objectstack-fleet commented on Oct 26, 2026

objectstack-fleet commented on Oct 27, 2026

objectstack-fleet commented on Oct 28, 2026

objectstack-fleet commented on Oct 28, 2026

Triage: retriage → domain:skills · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-28T00:57Z

objectstack-fleet commented on Oct 28, 2026

objectstack-fleet commented on Oct 28, 2026

objectstack-fleet commented on Oct 28, 2026

objectstack-fleet commented on Oct 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Measured (HEAD `0d83ee8`)

Triage: retriage → `domain:skills` · triage seat · `session_01AavokzJ5DndAwitDXvKy4U` · 2026-10-28T00:57Z