docs(skills): the os package publish row points app authors at the marketplace handbook (#28429)

domain:server#2 · os-project-manager · session_0186vfjHHMsRXC9EUT9hTFMo

<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XKLoG4h5tPAWSoK1ZmBeq3F)_

Fixes #27331

Clause-②: no (governed prose only, no accept set moves; the dev
declares)
Metadata-protocol: none

## 维护者速读

- 改了什么：`skills/objectstack-platform/references/operations.md` 的 `os
package publish` 一行加了一句，指向 Marketplace
handbook（`/docs/deployment/marketplace-handbook`）：listing
文件、README、审核、以及客户管理员会经过的每个界面。为付 token 棘轮，删掉了同文件 cloud-connection
引文块的尾巴（`LocalManifestSource` 账本、runtime-identity bind
v2），那是插件内部机制，应用作者不碰。
- 为什么改：写应用的 agent 先读 skills；没有这一句，它永远找不到那页，发布时不知道 listing
由什么组成、审核查什么、客户管理员装进去会经过什么（北极星第④步）。PR #27321 落地 handbook 时刻意没碰受管面，欠下这一句。
- 风险与回滚：只动一个 markdown 文件、两处文字，附 @objectstack/skills patch
changeset；无代码、无 spec。回滚即还原本 PR。
- 先看：`skills/objectstack-platform/references/operations.md` 第 106
行（新句与链接），第 109–114 行（删掉的引文块尾巴）。
- 两分钟验证：`node scripts/check-skills-token-ratchet.mjs`，预期该文件 `3124 tokens
(ceiling 3125; headroom 1)`，全绿。
- 需要你做的：Tier H（`skills/**`），本 PR 保持 draft，需要你批准后由席位落地。附：卡上的
rider（`openapi` `include` 两行）在 PR #28012 已改好，本 PR 不再动它，见 Acceptance
notes。

## What changes

One file, `skills/objectstack-platform/references/operations.md`, two
hunks:

1. **The `os package publish` row** (Environments & deploy table) gains
one sentence: "Listing file, README, review and every screen the
customer's administrator meets: [Marketplace
handbook](https://objectstack.ai/docs/deployment/marketplace-handbook)".
This is the reference file where an app-authoring agent reads about `os
package publish` (the card allows the reference file in place of
`SKILL.md`; `SKILL.md` names the `marketplace` service token once and
nothing about publishing). The link form matches the four existing docs
links in `skills/**`, all `https://objectstack.ai/docs/...`. The page is
on `main` and listed in `content/docs/deployment/meta.json`.
- **Reader:** the app-authoring agent at the moment it runs `os package
publish`.
- **Mistake it prevents:** publishing with no listing file or README
(the publish answers with marketplace policy violations), and shipping
an app with no idea what review checks or what the customer's
administrator goes through (credentials, sample data, enable/disable,
upgrade).
2. **Paid for under the skills token ratchet** by deleting, in the same
file, the tail of the cloud-connection blockquote: ", and maintain
`LocalManifestSource` (a local desired-state ledger) plus
runtime-identity bind v2 (environment-less self-hosted binding)". Those
are plugin internals an app author never acts on; their home is the
plugin's own source
(`packages/cloud-connection/src/connection-credential-store.ts` names
the `LocalManifestSource` ledger and the runtime-identity-binding ADR;
`cloud-connection-plugin.ts` carries the binding). What the blockquote
still teaches (the package, its plugins, the install-local endpoint `os
package install` targets, the Installed Apps page and Setup nav) is
unchanged. No re-wrap: the two hunks are a content addition and a
content deletion.

### Skills readings (two, as the landing rule asks)

| Reading | Before (`origin/main` 5da3a8c) | After (head) |
|:--|:--|:--|
| `operations.md` lines | 202 | 200 |
| `operations.md` tokens (ratchet unit, ceil(bytes/4)) | 3117 / ceiling
3125 (headroom 8) | 3124 / ceiling 3125 (headroom 1) |
| Whole package, all `skills/*/SKILL.md` lines summed | 4607 | 4607 (no
`SKILL.md` touched) |
| Whole shipped bundle, tokens | 219807 | 219814 |

## Why

The card: a follow-up PR #27321 owed when it landed the handbook and
deliberately left the governed `skills/**` line out. The agent that
writes an app reads the skills first; without this line it never finds
the page that says what a listing is made of and what the customer's
administrator will go through, North Star step ④.

## Tests

No code changes; no package test suite reads this file. The gate that
prices it:

```
node scripts/check-skills-token-ratchet.mjs                     exit 0
  ✓ skills/objectstack-platform/references/operations.md is 3124 tokens (ceiling 3125; headroom 1).
  ✓ 56 authored bundle file(s) within their ceilings; 10 generator-owned file(s) and 28 eval fixture(s) measured, not ratcheted.
```

## Acceptance notes

- **The rider on the card (the `openapi` `include` lines) is already
delivered on `main`, so this PR does not touch the two automation files
the claim's file surface lists.** The epic PM's request 6488631558 asked
that, once PR #27387 merged,
`skills/objectstack-automation/references/integration-recipes.md` line
63 ("The `openapi` provider has no `include` key — the trimmed document
is the allowlist.") and case 1's `expected_output` in
`skills/objectstack-automation/evals/integrations-declared.json` be
rewritten in the same skills PR. Read at `origin/main` 5da3a8c on
2026-10-31, both already teach `include`: the recipe reads
"`providerConfig.include` allowlists operation keys as the `mcp`
provider's does (absent = every operation; a non-array or unknown entry
is fatal)", and the eval reads "(or `providerConfig.include` names those
three operation keys, the `mcp` provider's allowlist meaning, where a
non-array or unknown entry is fatal)". The commit list for both files
names PR #28012 (merged 2026-10-30, "docs(skills): teach
connector_action input as an evaluated value slot and the openapi
include allowlist") as the change, and its body says in so many words
that items 3, 4 and 5 are those two lines. Measured against
`packages/connectors/connector-openapi/src/openapi-provider.ts` on
`main` (`resolveIncludeList`: absent returns undefined, a non-array or a
non-string or empty entry throws; an entry the document does not carry
is refused after generation), the published text is exact. Nothing to
change; the token ratchet shows `integration-recipes.md` at headroom 0,
so a re-touch would have cost a deletion for no gain.
- **Governed surface.** `node scripts/pm/check-governed-merges.mjs
--branch claude/project-thread-ce0xlt`, exit 3: "derived from `git diff
--name-only --no-renames 5da3a8c 1212152` (three-dot): 1 path(s).
governed-surface predicate: 1 of 1 path(s) hit the register (13 surfaces
govern objectstack). ⛔ GOVERNED — a human merge is the review record for
this PR. landing tier: H(人合). skills/** ×1 — the published skills
catalog: skills/objectstack-platform/references/operations.md. size: 6
changed line(s) (+2 / -4) ≤ 3000". The PR stays draft for the
maintainer's approval; no seat readies, queues or arms it.
- **Changeset:** the change ships in `@objectstack/skills`
(`dist/skills` via `sync-catalog.mjs`, and `dist` is in its `files[]`),
so `.changeset/27331-skills-marketplace-handbook-link.md` carries a
patch bump with the two declaration lines; no `skip-changeset` label
(the one sent on the `pr_create` was removed).
- **`pnpm lint` scoped to touched packages:** no package is touched (the
diff is one markdown file under `skills/`, which eslint does not lint),
so there is no scoped lint run to cite; `pnpm lint` repo-wide belongs to
CI's `Lint & Repo Gates`.
- Nothing else found; no cards to file.

## Verification

Local gate subset (derived by `node scripts/pm/dispatch-gates.mjs
--commands --repo objectstack-ai/objectstack` from the diff at 1212152;
each exit code captured before any pipe; reconciled with `--ran`):

```
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-dts-emitted.mjs --self-test :: exit 0
node scripts/check-skills-token-ratchet.mjs :: exit 0
node scripts/check-skills-token-ratchet.mjs --self-test :: exit 0
node scripts/ci/assert-turbo-remote-cache.mjs --self-test :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
node scripts/ci/prune-turbo-cache.mjs --self-test :: exit 0
pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0
pnpm --filter @objectstack/spec run check:skill-refs :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:ci-filter-parity :: exit 0
pnpm check:corpus-claim-drift :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:doc-authoring :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:dts-closure :: exit 3
pnpm check:dual-build-cjs-loads :: exit 3
pnpm check:gitlink-declared :: exit 0
pnpm check:lean-entry-closure :: exit 3
pnpm check:nul-bytes :: exit 0
pnpm check:pm-governed-merges :: exit 0
pnpm check:pm-skill-id-lint :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:role-word :: exit 0
pnpm check:skill-compatibility :: exit 0
pnpm check:skill-frame-sync :: exit 0
pnpm check:skill-identifier-liveness :: exit 0
pnpm check:sourcemap-no-sources-content :: exit 3
pnpm check:watch-hint-literal :: exit 0
```

`node scripts/pm/dispatch-gates.mjs --ran`: "33 derived famil(ies)
accounted for — 29 run, 4 NOT-MEASURED (4 DERIVED from a recorded exit
3)". The four exit-3 families (`check:dts-closure`,
`check:dual-build-cjs-loads`, `check:lean-entry-closure`,
`check:sourcemap-no-sources-content`) read every package's built `dist/`
and refuse before measuring on a tree with no full build; this diff
touches no package, so no build closure is owed locally (os-dev.md
local-verification scope ①) and CI's `Lint & Repo Gates` runs them on
the PR. `check:doc-formula-expressions` does read `skills/`, so
`@objectstack/formula` and `@objectstack/lint` were built under the
verify lock (VERDICT command-exit 0, 1m40s) and the gate re-run: exit 0.
Governed check and the token ratchet are quoted under Acceptance notes
and Tests.

Head d9530dd (the changeset commit) re-derived the gates: 44 derived,
40 run green (the changeset adds 11 families, all exit 0), 4 NOT
MEASURED (the four exit-3 families above). Token ratchet re-run at
d9530dd: exit 0, headroom 1.

Every CI family runs on this PR's check-runs; the seat reads them there.

## Human Minimum

- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(No schema touched.)
- [x] 2. Every name I added uses the casing for its kind. (No name
added.)
- [x] 3. No formatter ran; `pnpm lint` passes. (Nothing in the diff is
lint input; CI runs the repo-wide lint.)
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset. (A patch
changeset for `@objectstack/skills` carries both lines; they are also
above.)
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (Not touched.)
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English (the 维护者速读 block is the
Chinese maintainer digest the landing rule asks for).
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5p7yCAhAMSXLu1fXaZ)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/27331-skills-marketplace-handbook-link.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the `os package publish` row of objectstack-platform's operations reference points app authors at the Marketplace handbook
+
+Clause-②: no
+Metadata-protocol: none
+
+- **Before.** The platform skill's operations reference described `os package publish` as an upload to the cloud catalog and nothing more. An agent authoring an app from the skills never found the page that says what a listing is made of (`objectstack.manifest.json`, the README), what review checks, and what the customer's administrator goes through after installing.
+- **Now.** That row names the listing file, the README, review and the administrator's screens, and links `https://objectstack.ai/docs/deployment/marketplace-handbook`.
+- Paid for under the skills token ratchet by deleting the cloud-connection note's tail (the `LocalManifestSource` ledger and runtime-identity bind v2), plugin internals an app author never acts on. The file stays under its ceiling; no ceiling moves, no frontmatter, schema, key or behaviour changes.

skills/objectstack-platform/references/operations.md

@@ -103,17 +103,15 @@ Port resolution is the same for `os dev` and `os start` (both spawn `os serve`):
 | `os environments list` / `create` / `switch` | Manage cloud environments (prod/staging/dev) |
 | `os register` | Register the local stack as a deployable target |
 | `os cloud login` / `logout` / `whoami` | Cloud auth subcommands (these three only — there are no `os cloud logs/metrics/status`) |
-| `os package publish [dist/objectstack.json] [--env … --install --visibility org]` | Upload the compiled artifact as a versioned package to the cloud catalog (ADR-0008 P3) |
+| `os package publish [dist/objectstack.json] [--env … --install --visibility org]` | Upload the compiled artifact as a versioned package to the cloud catalog (ADR-0008 P3). Listing file, README, review and every screen the customer's administrator meets: [Marketplace handbook](https://objectstack.ai/docs/deployment/marketplace-handbook) |
 | `os package install <manifest-id │ ./dist/objectstack.json> [--version │ --runtime http://localhost:3000]` | Install a package into a **running** runtime via its install-local endpoint. Catalog mode (by manifest id) or air-gapped local-artifact mode. Auths with the **target runtime's** session (`--email/--password` or `OS_RUNTIME_EMAIL`/`OS_RUNTIME_PASSWORD`), not the cloud login |
 
 > **Cloud connection & marketplace (`@objectstack/cloud-connection`, ADR-0008/0009).**
 > The open runtime-side cloud client. Its plugins —
 > `CloudConnectionPlugin`/`createCloudConnectionPlugin`, `MarketplaceProxyPlugin`,
 > `MarketplaceInstallLocalPlugin`, `RuntimeConfigPlugin` — expose the install-local
 > endpoint that `os package install` targets, ship the **Installed Apps** page and
-> marketplace Setup nav as plugin metadata, and maintain `LocalManifestSource`
-> (a local desired-state ledger) plus runtime-identity bind v2 (environment-less
-> self-hosted binding).
+> marketplace Setup nav as plugin metadata.
 
 ## Shipping a plugin