Skip to content

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

Open
Open
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
Labels
area:devpathThe road — create, dev, verify, publish/install, connect an agent, iteratedocumentationImprovements or additions to documentationdomain:skillspm:queuepriority:p2Medium: important, M3

Description

@objectstack-fleet
objectstack-fleet
bot
opened on Oct 26, 2026

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)

  1. 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.
  2. 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」).
  3. 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

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.

Related

#26035 (open, dispatched).

Activity

  1. objectstack-fleet
    added
    documentationImprovements or additions to documentation
    on Oct 26, 2026

  2. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 26, 2026
    ContributorAuthor

    Triage: first grade — documentation · priority:p2 · domain:docs · area:devpath · pm:queue · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-26T12:11Z

    ⛔ Not a claim, ⛔ not a dispatch. On the maintainer's 「完整的评估本项目…」 / 「低优先级的先不考虑」 (repository evaluation, Batch-of 19). Low priorities were excluded at filing, so the execution cards grade p2.

    Generated by Claude Code

  3. objectstack-fleet
    added
    area:devpathThe road — create, dev, verify, publish/install, connect an agent, iterate
    domain:docs
    pm:queue
    priority:p2Medium: important, M3
    domain:devx
    and removed
    domain:docs
    on Oct 26, 2026

  4. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 26, 2026
    ContributorAuthor

    Claim: PM loop round 5 · non-AGENTS.md half · 2026-10-26T16:24Z
    Session: session_01Q4MDXRbEJCNdPAP4SiXwp9 (devx seat 2) · card thread session_01VekRRVKWXqJbHnFKvo9Bak
    Account: os-steve
    Branch: claude/project-thread-k0qyr1 (the harness-pinned branch of the card thread; it names no issue, so this claim is the identity record; amended on spawn)
    Worktree: objectstack-issue-26088
    Domain: domain:devx
    Seat: domain:devx#2 (seat post #20163)
    File surface: README.md, CONTRIBUTING.md, content/docs/getting-started/** — for each of the three facts (dev port + env var spelling, scaffold command, setup command) read the code, pick the true statement, make these pages say it. ⛔ AGENTS.md is NOT in this claim: three open PRs touch it now (#26216, #26230, and #26035's work), so its half rides #26035 or a later round on this card; the PR says which AGENTS.md lines still disagree (stop on breach; explain in the report)
    Container & model: S, mode:thread, model: default tier (TIER_DEFAULT, from dispatch-gates --tier: no path-derived mandate), effort: medium
    Clause-②: no
    Metadata-protocol: none
    Responsibility: n/a — not a defect card
    Thread-read: 6415687206
    Premise: holds on origin/main (to be re-read by the dev against the card's line numbers, measured at 0d83ee8f77)
    Serial constraints cleared: #26215 (draft, brand) touches README.md on other lines; whichever lands second rebases. No other open PR touches CONTRIBUTING.md or content/docs/getting-started/**

    Generated by Claude Code

  5. objectstack-fleet
    assigned
    os-steve
    on Oct 26, 2026
  6. objectstack-fleet
    added
    pm:dispatched
    and removed
    pm:queue
    on Oct 26, 2026

  7. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 26, 2026
    ContributorAuthor

    os-dev-report

    {
  "issue": 26088,
  "status": "done",
  "branch": "claude/project-thread-k0qyr1",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/26248",
  "session": "session_01VekRRVKWXqJbHnFKvo9Bak",
  "premise_still_valid": true,
  "summary": "Non-AGENTS.md half only (PR body opens Part of #26088). Premise re-read on origin/main df8aac41: the scaffold contradiction moved to getting-started/index.mdx:169 and is fixed to npm create objectstack@latest; the port fact (default 3000, dev auto-shift, OS_PORT with PORT as legacy alias, decided by packages/cli/src/commands/dev.ts:718/:765 and serve.ts:2274) is now stated in CONTRIBUTING.md in getting-started's terms, plus the console proxy's DEV_PROXY_TARGET (ui/apps/console/vite.config.ts:1486). Setup needed no edit in this half: README/CONTRIBUTING/getting-started already say pnpm install then pnpm build, which is what pnpm dev's preflight demands (scripts/check-dev-prereqs.mjs:579); package.json:17 setup builds spec only. AGENTS.md lines still disagreeing, left for a later round: AGENTS.md:40 (pnpm run setup as first-time), AGENTS.md:138 (PORT=3000, 'must be 3000 (UI hard-wired)', PORT=3000 pnpm dev:crm), AGENTS.md:173 (PORT=3000 in the ../objectui section).",
  "tests": "docs-only diff, no package code touched: no package test or typecheck owed; no tested behaviour changed, so no ablation. Card grep over README.md CONTRIBUTING.md content/docs/getting-started/ at dcabcaf2: OS_PORT only (CONTRIBUTING.md:67, index.mdx:211-212), PORT=3000 zero hits, npx create-objectstack zero hits, npm create objectstack 8 hits, pnpm run setup zero hits.",
  "gates": "local at dcabcaf2: dispatch-gates --commands --repo objectstack-ai/objectstack derived 41; all 41 exit 0 (each exit captured before any pipe). check:skill-examples first exit 3 PREREQUISITE NOT MET (client-react dist unbuilt), exit 0 after pnpm --filter '@objectstack/client-react...' build (lock VERDICT command-exit 0). --ran reconciliation: 41 derived, 41 run, 0 NOT-MEASURED (derived zero, every line carries its exit code). check:doc-authoring exit 0. Link check (check-links.yml, lychee): NOT MEASURED locally, reason: lychee not installed; diff adds no link lychee reads (CONTRIBUTING.md outside its globs; the one URL added is localhost, excluded in lychee.toml:84). CI families: in_progress at report time, not waited on.",
  "line_budget": "+8 / -1, 2 files, under the 3000 human-merge threshold",
  "files_changed": [
    "CONTRIBUTING.md",
    "content/docs/getting-started/index.mdx"
  ],
  "deviations": [
    "branch is the harness-pinned claude/project-thread-k0qyr1, not claude/issue-26088-*; the claim's Branch line names it",
    "the primary checkout had the pinned branch checked out; it was detached so the worktree objectstack-issue-26088 could own the branch",
    "skip-changeset declared on the pr_create stroke; read back on the pull: labels [skip-changeset], assignees [os-steve]"
  ],
  "dogfood_battery": "n/a — no ! in the PR title and Clause-② no without an arm",
  "mcp_calls": "4 — all reads: issue_read get x1, issue_read get_comments x2, pull_request_read get x1; zero MCP writes",
  "api_writes": "2 relay strokes (objectstack-fleet[bot]): pr_create (POST /repos/objectstack-ai/objectstack/pulls + POST /issues/26248/assignees + POST /issues/26248/labels) and this os-dev-report comment (POST /repos/objectstack-ai/objectstack/issues/26088/comments); git push is not a REST write",
  "open_questions": [],
  "out_of_scope_findings": []
}

    Generated by Claude Code

  8. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 26, 2026
    ContributorAuthor

    devx seat 2 · review: ACCEPT → PR #26248 (the half outside AGENTS.md, Part of) comment 6422121118 on head dcabcaf2ad. Every check is green or skipped. Not governed. Landing: ready + auto-merge. The card stays open for the AGENTS.md lines that still disagree (40, 138, 173). They are governed, so a maintainer-approved PR handles them in a later round.

    Generated by Claude Code

  9. objectstack-fleet
    added
    pm:queue
    and removed
    pm:dispatched
    on Oct 26, 2026

  10. objectstack-fleet commented on Oct 26, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 26, 2026
    ContributorAuthor

    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

  11. objectstack-fleet
    unassigned
    os-steve
    on Oct 27, 2026

  12. objectstack-fleet commented on Oct 27, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 27, 2026
    ContributorAuthor

    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

  13. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 28, 2026
    ContributorAuthor

    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

  14. objectstack-fleet
    added
    pm:retriageQuestion for triage, answered each fire; coexists with the standing pm:* label; no dispatch
    on Oct 28, 2026

  15. objectstack-fleet commented on Oct 28, 2026

    @objectstack-fleet
    objectstack-fleetBot
    on Oct 28, 2026
    ContributorAuthor

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

    ⛔ Not a claim.

    Generated by Claude Code

  16. objectstack-fleet
    added
    domain:skills
    and removed
    domain:devx
    pm:retriageQuestion for triage, answered each fire; coexists with the standing pm:* label; no dispatch
    on Oct 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:devpathThe road — create, dev, verify, publish/install, connect an agent, iteratedocumentationImprovements or additions to documentationdomain:skillspm:queuepriority:p2Medium: important, M3

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions