Repository navigation
docs(deployment): rewrite publish-and-preview to name both ways a metadata app reaches the platform #8910
Description
Card 03 of the deployment restructure. Maintainer question, 2026-08-15: 「元数据应用又是独立的，如何加载到平台？」
The defect
There are two mechanisms for getting a compiled metadata app onto a running platform. They are documented on two different pages, and neither page mentions the other exists:
| Mechanism | Documented in | Shape |
|---|---|---|
| Catalog install | content/docs/deployment/publish-and-preview.mdx (101 lines) |
compile → dist/objectstack.json → publish a package version → install into an environment |
| Artifact-pinned boot | content/docs/deployment/self-hosting.mdx, under "Artifact-pinned boot" |
OS_ARTIFACT_URL — the runtime fetches the artifact at boot |
A reader who lands on either page has no way to learn the other option exists, let alone which one fits them. There is no page whose subject is "a metadata app is a separate thing from the platform; here is how it gets in."
Scope
Rewrite content/docs/deployment/publish-and-preview.mdx so it is that page. It must:
- Open with the independence — the app is versioned in your catalog, the platform on our release train; they move on separate clocks. This framing is the whole point of the restructure and this is the page that states it for Axis B.
- Name both mechanisms side by side, with a stated rule for choosing. The rule is the deliverable, not the enumeration — a reader who finishes the page unsure which one they want has not been served.
- Keep the existing compile → publish → install → preview flow. It is correct; it is being framed, not replaced.
OS_ARTIFACT_URL's operational detail stays in self-hosting.mdx (that is Axis A, and card 04 owns that file — do not edit it here). Reference it; do not move it. If you find the split genuinely unworkable without touching self-hosting.mdx, stop and report rather than reaching across the card boundary.
Verify the mechanisms before writing about them
The issue text is a clue, not a specification. Read the CLI and runtime sources for how OS_ARTIFACT_URL and the catalog install actually behave today — including whether they can be combined, and what happens when both are configured. If the measured behaviour contradicts the framing above, report it: premise_still_valid: false is a valued outcome here, because a page that documents a choice the runtime does not actually offer is worse than the current split.
Relevant: content/docs/deployment/cli.mdx (## Commands, lines 68–1283) is the command reference — link to it, do not restate it.
Independence
Touches only content/docs/deployment/publish-and-preview.mdx. No overlap with cards 01, 02, 04. Safe to run in parallel with all three.
Docs-only, skip-changeset.
Activity
os-project-manager commentedon Aug 16, 2026
Claiming this card.
session_011RB4waLuNbdruCo6X9oobmclaude/issue-8910-publish-and-preview../objectstack-8910File surface:
content/docs/deployment/publish-and-preview.mdxonly. Will not touchself-hosting.mdx(#8911),upgrading.mdx(#8909), ordeployment/meta.json(#8913).Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
{ "issue": 8910, "status": "done", "branch": "claude/issue-8910-publish-and-preview", "pr": "https://github.com/objectstack-ai/objectstack/pull/8962", "premise_still_valid": true, "summary": "Rewrote content/docs/deployment/publish-and-preview.mdx (101 -> 223 lines, the only file touched) as the page whose subject is the app/platform independence and how an app gets in. It opens with the two-clocks framing, puts catalog install and artifact-pinned boot in one comparison table, and states the choosing rule as a single question - 'is this app the reason the runtime exists?' - with three tie-breakers (auditable bytes ⇒ pin; no-restart or several apps ⇒ install; air-gapped ⇒ both work, so decide on the first two) plus a 'using both at once' section. The compile ⇒ publish ⇒ install ⇒ preview flow is kept and framed, not replaced; section 3 now names both install targets because 'install' was the half the choosing rule needed defined. Premise verified against origin/main before writing and it holds: the page had 0 mentions of OS_ARTIFACT_URL, self-hosting.mdx had 3, and the mechanisms behave as the card describes. Combination behaviour was measured, not assumed - the install surface in packages/cli/src/commands/serve.ts mounts on resolveCloudUrl()/the offline arm and is never gated on the artifact-pinned boot resolved earlier in the same file, so a pinned runtime still accepts installs of OTHER apps; two sources naming the same manifest id answer 409 MANIFEST_CONFLICT via findConflict's bootUserCodeIds snapshot (pinned by marketplace-install-local-conflict.test.ts) rather than merging; precedence is --artifact > OS_ARTIFACT_URL > OS_ARTIFACT_PATH > cwd/dist, with OS_ARTIFACT_URL also outranking a local objectstack.config.ts. self-hosting.mdx, upgrading.mdx and deployment/meta.json were not touched; OS_ARTIFACT_URL's operational detail stays there and is linked through the stable #artifact-pinned-boot-os_artifact_url anchor (the same one cli.mdx and environment-variables.mdx already use, and which the PM confirmed #8960 preserves). No 'Option N' heading text is referenced.", "tests": "Docs-only change; no package build or unit tests are implicated. Gate union run at the final commit b46c28da8 (git rev-parse --short HEAD from that run), all four green: (1) pnpm check:docs-audit-scope -> 'docs-accuracy-audit scope is in sync with content/docs/: 177 hand-written doc(s)' + 'release-owned pages are in scope and read-only: 9 page(s)'; (2) pnpm check:role-word -> 'check-role-word: OK (43 baselined file(s), no new occurrences)' - this page is NOT in the baseline so it had to stay at 0 occurrences, verified independently (grep -oci role = 0); (3) pnpm check:nul-bytes -> '75 assertions' self-test + 'OK (scanned 5935 text file(s); no raw ASCII control bytes)', plus a targeted self-scan of the edited file with grep -naP over the control-byte class, clean; (4) pnpm check:doc-anchors -> '218 internal #fragment link(s) across 395 source file(s) all resolve to a real heading' - NOT in the dispatched list, re-derived and run because the change adds anchor links; it needs node_modules, so pnpm install --ignore-scripts was run first under flock -E 99 -w 540 /tmp/os-heavy-verify.lock (5.1s, lock uncontended). check:doc-authoring also run and green (375 files clean). node scripts/pm/dispatch-gates.mjs content/docs/deployment/publish-and-preview.mdx re-derived exactly the two dispatched families and added none. skip-changeset applied to PR #8962 and read back before this report: labels = [\"skip-changeset\"].", "open_questions": [], "out_of_scope_findings": [ "filed as #8965: content/docs/deployment/cli.mdx - the CLI command reference - has no entry for `os package publish` or `os package install`; measured on d6e80b28b the only occurrence of either string is prose inside the `os cloud login` section, and `os package install` is documented nowhere in the Deployment group at all. Directly downstream of this card, which points readers at that reference for the flag-level detail. Filed unassigned, no pm:queue." ] }Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
✅ ACCEPT — PR #8962 armed (03:10:53Z)
publish-and-preview.mdx(101 → 223 行)self-hosting.mdx(#8911)、upgrading.mdx(#8909)、deployment/meta.json(#8913)#artifact-pinned-boot-os_artifact_url;我已在 #8960 上独立核实该锚点存活,两边一致交付物是选择规则,不是并列枚举 —— 这一条做到了。 规则收敛成一个问句(「这个 app 是这个 runtime 存在的理由吗?」)加三条 tie-breaker,并且补了「两个一起用」的情形。一个读完仍不知道该选哪个的读者,不算被服务到 —— 这是卡片的原话,交付对上了。
没有把机制当传闻写。 组合行为是实测的,不是从卡片抄的:install 面挂在
resolveCloudUrl()/离线臂上,不受同文件里更早解析的 artifact-pinned boot 门控,所以被钉住的 runtime 仍接受其它 app 的安装;两个来源指向同一 manifest id 时走findConflict的bootUserCodeIds快照答409 MANIFEST_CONFLICT(有marketplace-install-local-conflict.test.ts钉住),不是合并;优先级实测为--artifact>OS_ARTIFACT_URL>OS_ARTIFACT_PATH>cwd/dist。这些正是卡片说「issue 正文是线索不是规格」要求去量的东西。门禁自扩也对:
check:doc-anchors不在我派发的清单里,dev 因为改动新增了锚点链接而自行推导并运行(218 个#fragment全部解析)。派发清单是下限不是上限,这是正确读法。派生已立 #8965(
cli.mdx这份命令参考里os package publish/os package install都没有条目)—— 直接下游:本页把读者指向那份参考要 flag 级细节,而那里没有。落地判据:
publish-and-preview.mdx含两机制对照表与选择规则,且total_count == 1。Generated by Claude Code
docs(deployment): add os package publish and os package install to th…