Sync cloud's content/docs/ into this site and pin both upstreams (objectstack, cloud) so alignment is a bounded diff review, not a periodic re-read (cloud#3199 ruling D)

Filing gate: ③ a task the maintainer directed — execution of the director ruling D on objectstack-ai/cloud#3199 (ruling comment 6385556953, 2026-10-24), whose execution parameters name "one card in the docs repository covering both upstreams".

Maintainer, cloud project thread, 2026-10-24, verbatim: 「objectos文档仓库在 objectos 项目」 · 「但是代码和文档都在一起是不是容易审核？」 · 「objectos 的仓库也是需要定期和 objectstack 仓库对齐的，目前纯粹靠ai定期复核」 · 「同意，那 objectos 仓库的整个内容可能都面临调整」; 2026-10-26: 「objectos 文档仓仓名就是 objectos」.

Session: session_01AWCFiDMVCc8ePHTmR39SUZ (director seat, summon #50; seat post objectstack-ai/objectstack#12708).

Business reason. This site is the only public documentation for ObjectOS Cloud and Enterprise, in seven locales, and today it has no page that starts a reader on ObjectOS Cloud (#300). The cloud repository already holds the pages that fill that gap — content/docs/ there has an ai/ group (MCP agent access, models and limits, Ask & Build, skills; about 4,800 words), guides/hierarchy-security (2,266 words), getting-started/deploy (707) and concepts/preview (320) — written beside the product code so that a behaviour change and its documentation are reviewed in one pull request. The maintainer ruled that they stay there as the single source, and that this site composes them. Separately, alignment of this site with the open-source framework is done today by a periodic AI re-read of both corpora, an unbounded input that misses whatever that one pass misses (#141 is one such drift). Both problems have the same fix: pin a commit of each upstream in this repository and make every alignment a review of the diff since the last pin.

Reader who acts. The domain:docs lane of this repository; one dev PR, no product-source access needed (both upstream trees are public or readable with the fleet's existing read access: cloud's content/docs/ is the one directory of that private repository this site consumes).

Dedup. GET /repos/objectstack-ai/objectos/issues?state=open read in full (12 open): #300 (no Cloud getting-started path; pm:blocked on #295 and www#215) is the gap the synced pages fill but asks for a different thing (IA and edition vocabulary); #141 (version-pinned quickstart claims) is one instance of the drift the objectstack pin bounds; #334 (facts the docs cannot state from public sources) is unrelated. No existing card asks for a pin or a sync. Related-to: #300, #141.

维护者速读

cloud 仓的 content/docs/（AI/MCP 组、层级可见性、部署、Public Preview 共 9 页有料内容，13 页 stub 已裁删除）按 #3199 的 D 裁决留在 cloud 和代码同 PR 审，这个站点负责把它组装进来。做法：本仓加两个钉文件（.objectstack-sha、.cloud-sha），一个同步脚本把 cloud 的英文页复制到本仓 content/docs/cloud/（作为生成文件，禁止手改，翻译流水线照常从英文派生），一个 bump PR 把两条上游自上次钉点以来的 diff 列出来当复核输入。cloud 的钉点随 cloud 生产部署 bump，不随合并 main。此后「objectos 与 objectstack 对齐」不再是定期全量重读，而是读 bump PR 的 diff。你只需要在 PR 上确认挂载位置（默认新开 cloud/ 一节，#300 的 IA 调整时可再归位）。

Governing text

objectstack-ai/cloud#3199, ruling D (comment 6385556953): "content/docs/ stays in this repository as the single source for cloud and enterprise user-facing pages … the docs repository pins one commit per upstream (objectstack and cloud, the same mechanism as this repository's .objectstack-sha) and composes this tree at build time; the cloud pin is bumped after a successful production deploy, never on merge to main; each bump PR's diff is the bounded input for the alignment review … the synced directory in the docs repository is generated and read-only there."
This repository's AGENTS.md 〈Critical rules〉 1: English is the single source of truth; every locale sibling is derived from the English file by the translation pass, and check-translation-ownership.mjs rejects a PR that mixes the two. A synced English page is therefore a committed file (so that the translation pass and lib/seo.ts see it), not a build-time fetch — this card reads "composes at build time" in the ruling as "composed into the committed English corpus by the sync PR", which keeps the ruling's intent (one source, generated copy, read-only here) inside this repository's own rule.
AGENTS.md 〈Turbo caching and content changes〉: content/docs/** is a declared input of build and type-check, so synced files are hashed like any other page.

Premises (re-check before acting)

P1: cloud origin/main content/docs/ has 27 .mdx pages, 13 of them Status: stub; cloud#3199's own PR deletes the 13 stubs and fixes two drifts (MCP paid-plan wording superseded by cloud#3203; operator env vars in ai/models-and-limits.mdx). Re-check: that PR's state on cloud#3199; sync only after it lands, or exclude the 13 stub paths explicitly.
P2: this repository has no pin file today (ls -a at 9df8a92: none) and no sync workflow; deploy-docs.yml is workflow_call/workflow_dispatch, translations.yml runs on content/docs/** changes. Re-check: ls -a | grep sha.
P3: cloud is a private repository; the fleet App that opens PRs here can read it (it files and reads there today). Re-check: GET /repos/objectstack-ai/cloud/contents/content/docs with the App token.

Done looks like

.objectstack-sha and .cloud-sha at the repo root, each one full commit SHA, with a one-line comment file or README section stating what each pin means and when it is bumped (objectstack: on a published @objectstack/cli release; cloud: after a successful cloud production deploy).
scripts/sync-upstream-docs.mjs (with --self-test): copies cloud's content/docs/ English pages at .cloud-sha into content/docs/cloud/ (frontmatter kept; a generated-file banner in frontmatter, e.g. source: objectstack-ai/cloud@<sha>:content/docs/<path>), prunes pages that no longer exist upstream, and refuses to run if the target directory has hand edits (any file whose source: SHA is not the current pin and that differs from upstream). A meta.json for the section, ordered as upstream's meta.json files say.
A check in CI (reuse .github/scripts/ conventions; English-only, ownership style) that fails a PR which edits a file under content/docs/cloud/ by hand — the error names the upstream path to edit instead.
A bump-upstream-docs.yml workflow (workflow_dispatch + repository_dispatch), run by the fleet, that updates one pin, runs the sync, and opens a PR whose body lists the upstream commits and changed upstream docs/release-note paths since the previous pin — for objectstack: git log <old>..<new> -- content/docs docs/releases CHANGELOG.md paths that exist there; for cloud: content/docs/. That PR body is the alignment review's input.
Locale siblings of synced pages are produced by the existing translation pass, untouched by the sync; the Traditional Chinese generator runs as today.
One AGENTS.md paragraph here: synced section, pin files, "edit upstream, never here", bump cadence. Governed text: draft PR, maintainer merges.
Mount point default: a new top-level cloud entry in content/docs/meta.json; re-homing pages into deploy/operate/use is left to There is no getting-started path for ObjectOS itself: Quickstart boots the open runtime, Deploy/Operate are not marked self-managed, and License & Pricing is buried #300's IA work and is not done by the sync.

Out of scope: rewriting any synced page (edits go to cloud); the objectstack docs themselves (objectstack's content/docs is the framework's site, not composed here — only its pin and diff list are); #300's IA and vocabulary decisions.

Blocked-by: objectstack-ai/cloud#3199 (the cloud PR that deletes the stubs and fixes the two drifts; the sync may land first with the 13 stub paths excluded, in which case this line is dropped in the PR body with the exclusion list shown).

Triage: lands in pm:queue, domain:docs; rationale: filing gate ③ — execution of the director ruling D on objectstack-ai/cloud#3199 (comment 6385556953), with the maintainer's verbatim words in the body; the repository was named by the maintainer on 2026-10-26 (「objectos 文档仓仓名就是 objectos」). Dedup read all 12 open issues: #300 and #141 are related, neither asks for a pin or a sync. This repository has no priority:* family except priority:p0, so none is applied; the card is p2 by the cloud ruling's own parameters. Filed by the director seat through the fleet-write relay, session_01AWCFiDMVCc8ePHTmR39SUZ, 2026-10-26T12:23Z.

Re-scoped · maintainer Sam, project thread "Decide docs.objectos.ai content scope", 2026-10-27: cloud's user docs are maintained here, not synced (amendment recorded on objectstack-ai/cloud#3199).

Stays in this card: "Done looks like" items 1 (.objectstack-sha and .cloud-sha pin files with their bump rules), 4 (bump-upstream-docs.yml: update one pin, open a PR whose body lists the upstream commits and changed paths since the previous pin — for cloud now CHANGELOG.md and .changeset/, since content/docs/ there is going away; for objectstack unchanged) and 6 (the AGENTS.md paragraph, now about pins and the bump cadence only).

Dropped: items 2 (sync script and content/docs/cloud/), 3 (hand-edit gate), 5 (locale siblings of synced pages), 7 (mount point). The pages themselves are written by #344 as ordinary English pages of this site.

The Blocked-by: objectstack-ai/cloud#3199 line no longer applies (that PR merged, and nothing here reads cloud's content/docs/ any more).

Generated by Claude Code

Claim: PM loop round 1 · 2026-10-27T13:08Z
Session: session_01QsR2jTaZ2GeyfjANMwstiw (seat thread; the dev is card thread session_01QsR2jVWW1KcnCambZ59z5f, identity by branch)
Account: zhuangjianguo
Branch: claude/project-thread-4eqcxt (platform-assigned; a card thread can push only this branch)
Worktree: the card thread's own docs.objectos.ai checkout
Domain: domain:docs (single-lane repository)
Seat: repo:docs.objectos.ai#1
File surface: the two pin files .objectstack-sha and .cloud-sha, .github/workflows/bump-upstream-docs.yml, at most one helper under .github/scripts/, AGENTS.md (one paragraph, governed) — stop on breach; explain in the report
Container & model: M, mode:thread, model: default tier (TIER_DEFAULT — sister repository, hand-derived: no packages/spec and no protocol-semantic surface), effort: project default (order asks for high)
Clause-②: no
Metadata-protocol: none
Responsibility: n/a — not a defect card
Thread-read: 6442331663
Premise: holds as re-scoped by 6442331663 (items 1, 4 and 6 stay; 2, 3, 5 and 7 dropped; Blocked-by: objectstack-ai/cloud#3199 no longer applies). origin/main is c622daa.
Serial constraints cleared: #343 (round 1, claude/project-thread-ri8ilt) adds one AGENTS.md rule line in another section, so the later PR merges main. Open PRs: Dependabot only.

File-surface amendment to claim 6442684968 · 2026-10-27T13:12Z · session_01QsR2jTaZ2GeyfjANMwstiw · seat repo:docs.objectos.ai#1

File surface adds: tools/ci-scripts/run-self-tests.mjs (one SELF_TESTED entry for the new .github/scripts/bump-upstream-pin.mjs, plus a short paragraph in its header comment). Reason, measured by the dev: the runner fails pnpm turbo run test in the required build job for any top-level .github/scripts/*.mjs that declares --self-test without being listed, and a self-tested helper is the repository's convention. Everything else in the claim stands.

os-dev-report

{
  "issue": 337,
  "status": "done",
  "branch": "claude/project-thread-4eqcxt",
  "pr": "https://github.com/objectstack-ai/docs.objectos.ai/pull/348",
  "head": "5e4305ec48ce64de4c4ad3643ce2dde9c3730915",
  "session": "session_01QsR2jVWW1KcnCambZ59z5f",
  "premise_still_valid": true,
  "summary": "Items 1, 4 and 6 of the re-scoped card. .objectstack-sha pins 4e4e881427a8b8b57696ad5bdb12792f2dac6556 (the commit tagged @objectstack/cli@17.7.0, the release the site's changelog names as current since #333). .cloud-sha is the placeholder `unpinned`: objectstack-ai/cloud is not reachable from this project. bump-upstream-docs.yml (workflow_dispatch + repository_dispatch type bump-upstream-docs, payload upstream/sha) moves one pin and opens a PR whose body lists upstream commits and changed paths since the previous pin (objectstack: content/docs, docs/releases, CHANGELOG.md; cloud: CHANGELOG.md, .changeset), via the helper .github/scripts/bump-upstream-pin.mjs with a --self-test. One secret UPSTREAM_BUMP_TOKEN, refused-when-absent, because GITHUB_TOKEN cannot read cloud and a PR it opens triggers no CI. AGENTS.md gains one `## Upstream pins` paragraph.",
  "tests": "--self-test: 17 pin/input cases + upstream names, tag peeling, plan, body size cap and fencing, token carriage; red under 3 on-disk mutations (fence escaping removed, same-commit no-op removed, SHA rule widened to 7 chars), each exit 1 naming the check, restored byte-identical by sha256. Real objectstack bump 17.7.0 -> 18.2.0 (npm latest, tag peeled): 570 commits, 243 paths, body 59564 chars, 248 commit lines cut and stated. Refusals exit 1: missing pin file, non-descendant, cloud without sha, cloud without token, unknown upstream, sha=main, abbreviated pin under --check; same commit again exit 0 changed=false. Bump job's three run: steps executed from the parsed YAML against a local bare origin with a gh shim: secret absent exit 1 NOT CONFIGURED; present: commits only .objectstack-sha, pushes bump-upstream-docs/objectstack-27f38ad, calls gh pr create; rerun with branch present exit 1. actionlint NOT MEASURED (binary download refused by this container's classifier); YAML parses and every run: block passes bash -n.",
  "gates": "Local at 220b106, exit codes captured before any pipe: gen-zh-hant --check 0; npm ci doc-samples 0; check-doc-samples 0; check-translations 0; run-self-tests 0 (12 passed); bump-upstream-pin --check 0; check-translation-ownership on the diff 0; pnpm turbo run type-check test 0 (lock VERDICT command-exit 0); pnpm turbo run build 0 (VERDICT command-exit 0, 0 cached); check-locale-surface 0; check-positioning 0; check-search-locales 0. At 5e4305e (job-name-only workflow change): run-self-tests 0, --check 0, bash -n all run: blocks 0. smoke-docs not owed: nothing under apps/docs or content/docs changes. PR check-runs at 5e4305e: build success, Node floor success, Ownership & freshness success, Upstream pins are well-formed success, Deploy docs skipped, Bump an upstream pin skipped (dispatch-only job).",
  "dogfood_battery": "n/a — no `!` in the PR title and no (narrowing) arm",
  "line_budget": "699 insertions, 0 deletions, 6 files; under the 3000-line line, so no five-section 速读 owed (the six-line one is in the body)",
  "files_changed": [
    ".objectstack-sha (+1)",
    ".cloud-sha (+1)",
    ".github/scripts/bump-upstream-pin.mjs (+532)",
    ".github/workflows/bump-upstream-docs.yml (+152)",
    "AGENTS.md (+4, governed)",
    "tools/ci-scripts/run-self-tests.mjs (+9, surface amended by the seat, comment 6442760321)"
  ],
  "deviations": [
    "Second commit 5e4305e after the PR opened: the skipped bump job's name expression rendered verbatim as a PR check, so it now has a static name. The PR body's gate block cites 220b106; the change is the job name only, re-checked as listed in gates. Seat may append that note; the body was not PATCHed.",
    "PR body line 1-2 is the harness attribution block (an HTML comment line), so `Fixes #337` is line 3.",
    "Commit trailers are model-free per the seat's rule 6, overriding the harness reminder's model-named trailer."
  ],
  "mcp_calls": "6, all reads — issue_read x3 (get 337, get_comments 337, get objectstack#9831), search_pull_requests x2, pull_request_read get_check_runs x1",
  "api_writes": "git push x2 (not REST); relay x1 dispatch (POST /repos/objectstack-ai/objectstack/dispatches) executing POST /repos/objectstack-ai/docs.objectos.ai/pulls + POST issues/348/assignees, read back identical; this report comment x1 via post-stamped",
  "open_questions": [
    {
      "question": "UPSTREAM_BUMP_TOKEN is not set; no bump can run until it is.",
      "options": [
        "A: a fine-grained token or fleet App installation token with contents:read on objectstack-ai/cloud and contents:write + pull-requests:write on docs.objectos.ai",
        "B: GITHUB_TOKEN for objectstack bumps only — cannot read cloud, and its PRs run no CI"
      ],
      "recommendation": "A, because B leaves cloud unbumpable and every bump PR without CI."
    },
    {
      "question": "The first .cloud-sha: which commit does cloud production serve?",
      "options": [
        "A: cloud's deploy workflow sends repository_dispatch bump-upstream-docs with upstream=cloud and the deployed sha after each successful production deploy",
        "B: the maintainer runs the workflow by hand with that sha once"
      ],
      "recommendation": "A, because it is the bump cadence the ruling names; B is fine for the first pin."
    },
    {
      "question": "Whether this repository lets Actions open PRs with GITHUB_TOKEN stays NOT MEASURED (Actions-permissions endpoints 403 through the proxy; no PR here was ever opened by github-actions).",
      "options": [
        "A: leave it; the workflow does not depend on it",
        "B: maintainer reads Settings → Actions → General"
      ],
      "recommendation": "A."
    }
  ],
  "out_of_scope_findings": [
    "none"
  ]
}

Generated by Claude Code

Navigation Menu

Repository navigation

Sync cloud's `content/docs/` into this site and pin both upstreams (objectstack, cloud) so alignment is a bounded diff review, not a periodic re-read (cloud#3199 ruling D) #337

维护者速读

Governing text

Premises (re-check before acting)

Done looks like

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Sync cloud's content/docs/ into this site and pin both upstreams (objectstack, cloud) so alignment is a bounded diff review, not a periodic re-read (cloud#3199 ruling D) #337

Description

维护者速读

Governing text

Premises (re-check before acting)

Done looks like

Activity

objectstack-fleet commented on Oct 26, 2026

os-zhuang commented on Oct 27, 2026

objectstack-fleet commented on Oct 27, 2026

objectstack-fleet commented on Oct 27, 2026

objectstack-fleet commented on Oct 27, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Sync cloud's `content/docs/` into this site and pin both upstreams (objectstack, cloud) so alignment is a bounded diff review, not a periodic re-read (cloud#3199 ruling D) #337