docs(deployment): a marketplace handbook for app authors - #27321

Fixes #27240

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：新增一页《Marketplace handbook for app authors》(content/docs/deployment/marketplace-handbook.mdx)，从构建好的 dist/objectstack.json 讲到客户装上、升级、卸载；另加导航项与两处交叉链接。
• 为什么改：上架这一步（North Star 第④步「发布并装进一个环境」）的机制散在五页里，却没有一页告诉作者「上架清单由什么组成、客户管理员会遇到哪些界面」。
• 风险与回滚：纯文档，不发布任何包；回滚即 revert 本 PR。唯一的事实性改动是 publish-and-preview.mdx 里卸载那一句（旧句说必须重启才卸载干净，与 base 上的 DELETE 处理器不符）。
• 先看：① content/docs/deployment/marketplace-handbook.mdx 的「The customer's side」九步（每一步都对着 Console 文案或运行时路由核过）；② 同页 Callout「Two things the file can say that never reach the listing」；③ publish-and-preview.mdx 第 207-210 行。
• 两分钟验证：pnpm docs:dev 后打开 /docs/deployment/marketplace-handbook，预期左侧导航 Deployment 下出现 Marketplace Handbook，页内所有链接可点通。
• 需要你做的：无，席位落地。

What changes

• New page content/docs/deployment/marketplace-handbook.mdx (255 lines), sections in the order an author meets them: what a listing is (ADR-0019 D1/D2); the objectstack.manifest.json keys os package publish actually sends, with HotCRM as the example only for the keys it carries; translations for two locales; the README conventions (credentials as names, values supplied by the administrator); build and verify; publish, --submit and the three listing statuses the CLI prints; the customer's side in nine steps; staying current; dependencies vs build-time modules. Field lists are linked to the generated content/docs/references/marketplace/*.mdx, never restated.
• content/docs/deployment/meta.json: one nav entry.
• content/docs/deployment/publish-and-preview.mdx: one Related link, plus the uninstall sentence corrected (in-place fix, evidence below).
• content/docs/getting-started/your-first-project.mdx: one Next steps card.
• scripts/docs-audit/handwritten-docs.json: regenerated by node scripts/docs-audit/check-audit-scope.mjs --write (+1 page). check:docs-audit-scope reds a new hand-written page that is not listed, so this file is a mechanical consequence of adding the page; it sits outside the claim's declared file surface.

How the premise correction on the claim was applied, point by point: no pnpm verify (the page names the scaffolded validate / lint / typecheck / test / build scripts and os verify); screenshots are stated as not carried by publish and not rendered by the Console, and the listing is built from icon plus two locales; HotCRM shown only for its own keys; credentials described as README prose, naming #27237 / #27238, with no env-var path; uninstall named as the Console action and DELETE /api/v1/marketplace/install-local/:manifestId, no CLI command; enable/disable named as the runtime surface with its real answer for an installed app; nothing about delisting or review internals; field lists linked.

One measured divergence from the correction's wording, point 5 ("plus a restart"). At base the DELETE handler (packages/cloud-connection/src/marketplace-install-local-plugin.ts, handleUninstall, around lines 2243-2312) removes the ledger entry, then withdraws the package from the running kernel, removes the metadata copies, and runs the uninstall cleanups; its note says a restart is still owed only when a withdrawal step did not complete. The Console's own text agrees (installedAdditiveNote: "Uninstall removes the app from the running kernel at once"). The page therefore says the answer's note and cleanups tell whether anything stays loaded until restart, and publish-and-preview.mdx's old "needs a restart to fully unload it, because app registration is additive" sentence is corrected to match.

Follow-up line, deliberately not in this PR (governed surface): skills/objectstack-platform gains one link line to /docs/deployment/marketplace-handbook.

Tests

Docs only: no package is touched, so no package test or typecheck is owed. Readings are on the final head 80f7e2df.

• pnpm --filter @objectstack/docs build under the verify lock: VERDICT command-exit 0, "Compiled successfully", 1428 static pages; the rendered marketplace-handbook.html carries the page's key strings; the gen steps the build runs left the tree clean (git status --porcelain empty).
• node scripts/docs-audit/affected-docs.mjs origin/main: "0 docs name something this change touched (no anchors derived) across 0 changed package(s)" (the diff changes no package); --all lists the new page.

Acceptance notes

• objectstack.manifest.json keys the schema accepts but publish never sends: tags, publisher, isStarter and preview.* parse under TemplateManifestSchema, and packages/cli/src/commands/package/publish.ts reads none of them. HotCRM's manifest at 353dace carries tags, publisher and isStarter. In the other direction publish reads and sends a top-level tagline that the schema does not declare (the non-strict object strips it on parse), and HotCRM also carries an undeclared top-level engines. The page warns about the first set and uses only translations for tagline. Reported for the PM's filing seat as a metadata-authoring trap.
• The CLI's listing-status hints read pending_review, while ListingStatusSchema in packages/spec/src/marketplace/marketplace.zod.ts enumerates submitted / in-review. The wire value is the control plane's (cloud); the page names only what the CLI prints.
• packages/cloud-connection/src/cloud-connection-route-ledger.ts row DELETE /api/v1/marketplace/install-local/:manifestId still says "the kernel must restart to fully unload", which the handler no longer requires. Ledger prose, not served to anyone; noted, not changed.
• The page runs to 255 lines against the suggested 250.

Verification

Gate families derived by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (change set from the merge base, 53 commands), each run with its exit code captured before any pipe, reconciled with --ran.

Gate run on 80f7e2df:

exit 0  node scripts/check-adr-links.mjs
exit 0  node scripts/check-adr-links.mjs --self-test
exit 0  node scripts/check-closing-keyword-parity.mjs
exit 0  node scripts/check-closing-keyword-parity.mjs --self-test
exit 0  node scripts/check-comment-mask-corpus.mjs
exit 0  node scripts/check-doc-route-spelling.mjs --advisory
exit 0  node scripts/check-doc-route-spelling.mjs --self-test
exit 0  node scripts/check-docs-section-name.mjs
exit 0  node scripts/check-docs-section-name.mjs --self-test
exit 0  node scripts/check-section-landing-index.mjs
exit 0  node scripts/check-section-landing-index.mjs --self-test
exit 0  node scripts/ci/plan-test-core-shards.mjs --self-test
exit 0  node scripts/docs-audit/check-affected-docs.mjs
exit 0  node scripts/docs-audit/check-drift-comment.mjs
exit 0  pnpm --filter @objectstack/lint run check:doc-formula-expressions
exit 0  pnpm --filter @objectstack/lint run check:doc-security-posture
exit 0  pnpm --filter @objectstack/spec run check:docs
exit 0  pnpm --filter @objectstack/spec run check:empty-state
exit 0  pnpm --filter @objectstack/spec run check:liveness
exit 0  pnpm --filter @objectstack/spec run check:skill-examples
exit 0  pnpm --filter @objectstack/spec run check:strictness-ledger
exit 0  pnpm --filter @objectstack/spec run check:variant-docs
exit 0  pnpm --filter @objectstack/spec run check:yaml-examples
exit 0  pnpm check:agent-test-spelling
exit 0  pnpm check:bash32-floor
exit 0  pnpm check:ci-filter-parity
exit 0  pnpm check:cli-command-ids
exit 0  pnpm check:closed-ceremony-text
exit 0  pnpm check:corpus-claim-drift
exit 0  pnpm check:cross-package-test-inputs
exit 0  pnpm check:doc-anchors
exit 0  pnpm check:doc-authoring
exit 0  pnpm check:doc-frontmatter
exit 0  pnpm check:docs-audit-scope
exit 0  pnpm check:docs-redirects
exit 0  pnpm check:docs-single-h1
exit 0  pnpm check:docs-spec-enumerations
exit 0  pnpm check:docs-transcript-drift
exit 0  pnpm check:driver-memory-census
exit 0  pnpm check:entry-guard
exit 0  pnpm check:gitlink-declared
exit 0  pnpm check:nul-bytes
exit 0  pnpm check:parse-guard
exit 0  pnpm check:pnpm-filter-targets
exit 0  pnpm check:pnpm-flag-spellings
exit 0  pnpm check:published-readme-links
exit 0  pnpm check:react-page-adapter-contract
exit 0  pnpm check:refd-timer-probe
exit 0  pnpm check:role-word
exit 0  pnpm check:scripts-symbol-anchors
exit 0  pnpm check:skill-identifier-liveness
exit 0  pnpm check:vendor-version-stamps
exit 0  pnpm check:watch-hint-literal

Run reconciliation — 53 derived, 53 run, 0 NOT-MEASURED, 0 UNRUN.
docs build: os-verify-lock VERDICT command-exit 0; Compiled successfully in 37.0s; Generating static pages (1428/1428)

Generated by Claude Code