docs(skills): name the installation-wide uniques stop for a self-hosted os deploy (#31428)

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

Part of #31338

Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么：平台技能 `operations.md` 中 `use-runtime` 目标的退出码 1
段，在「安装被拒」一项里补上全局唯一约束停止：约束确属全平台时用 `--confirm-global-uniques` 重跑，否则改成
`unique: 'organization'`。
- 为什么改：PR #31369（#31338）已让 `os deploy` 在自托管运行时接受
`--confirm-global-uniques`，但技能只教了两个升级确认，agent 读技能时不知道这个停止和开关。
- 风险与回滚：纯技能文字；token 棘轮先删同文件两处重复（-67 字节），余额 +19 tokens 按常设裁定 6513306068
抬高该行（3375 → 3394）；发版 `@objectstack/skills` patch；回滚即 revert。
- 两分钟验证：`node scripts/check-skills-token-ratchet.mjs`（3394 / 3394）；对照
`packages/cli/src/commands/package/install.ts` L445-L456 的停止文案。
- 需要你做的：Tier H（`skills/**`），合并前需席位契约复核与 `os-zhuang` 或 `hotlong` 批准。

## What changes

`skills/objectstack-platform/references/operations.md`, the
`use-runtime` target paragraph (added by #31335, merged). Its
install-refusal clause listed the access and schema upgrade
confirmations only. It now also names the installation-wide uniques stop
(`UNIQUE_SCOPE_CONFIRMATION_REQUIRED`, ADR-0120 D5e), whose printed
retry is `os deploy --confirm-global-uniques`, and the stop's other way
on:

```diff
-… an install refusal (rerun with the `--confirm-access-upgrade` / `--confirm-upgrade <token>` it printed); installed but not loaded …
+… an install refusal (rerun with the `--confirm-access-upgrade` / `--confirm-upgrade <token>` it printed, or `--confirm-global-uniques` if its installation-wide `unique` constraints are meant platform-wide, else set them `unique: 'organization'`); installed but not loaded …
```

Source on `main` (`405a78ea`):
`packages/cli/src/commands/package/install.ts` L445-L456 (the stop
prints `${retry} --confirm-global-uniques` and "…or edit the app's
metadata to `unique: 'organization'` and rebuild");
`packages/cli/src/commands/deploy.ts` L100 (`CONFIRMATION_FLAGS`) and
L160 (the flag, self-hosted target only). `os deploy` rebuilds, so "and
rebuild" is the deploy itself.

## Why

PR #31369's acceptance notes left this line to the skills lane ("Not
edited here … the line it needs is in the report's
`out_of_scope_findings`"). Without it, an agent reading the platform
skill meets the stop with no taught way on.

## Token readings (`scripts/check-skills-token-ratchet.mjs`, tokens =
ceil(bytes / 4))

| File | `main` `e6a0b72a90` | This PR | Ceiling |
|:--|:--|:--|:--|
| `skills/objectstack-platform/references/operations.md` | 13500 B =
3375 | 13574 B = 3394 | 3375 → 3394 |

**Deletions, each with its surviving home (-67 bytes):**

1. Health & observability, Logs bullet: the example `new ObjectKernel({
logger: { level: 'info', format: 'json' } })` becomes "(`new
ObjectKernel({ logger })`)" (-36 B). Home of the shape:
`references/plugin-development.md` § ObjectKernel Configuration
(`logger: { level: 'info', format: 'json' }`). The bullet's own fact (a
kernel construction option, not a `defineStack` key) stays.
2. Metrics bullet: "(per-plugin startup durations)" (-31 B). Home:
`references/plugin-development.md` § Health Monitoring,
`kernel.getPluginMetrics(); // Map<name, startup ms>`.

No eval pins either (`skills/objectstack-platform/evals/*.json` swept
for `getPluginMetrics`, `logger`, `format`).

Added: +141 B. Net +74 B → 3394 tokens; headroom was 0, so the
remainder, +19 measured, raises that one row, pinned at the measurement,
under the standing maintainer ruling 2026-10-27, verbatim and
untranslated: 「A:先削重复,余额按实测提高」 (ruling record 6513306068 on #27847). No
rewrap: every untouched line is byte-identical.

## Not edited

- `skills/objectstack-platform/evals/config-plugins-ops.json` case 21
names only `--confirm-access-upgrade` (already listed in #31335's "Other
sites found").

## Verification

Head `da7c715974` (one commit on `main` `e6a0b72a90`). `node
scripts/pm/dispatch-gates.mjs --commands` derived 62 commands for the 3
paths: **57 × exit 0**; 5 NOT MEASURED (exit 3, prerequisite: a build):
`check:dts-closure`, `check:dual-build-cjs-loads`,
`check:lean-entry-closure`, `check:sourcemap-no-sources-content` read
every package's dist, and no package is touched; `@objectstack/lint
check:doc-formula-expressions` needs the formula and lint builds and
this diff adds no formula. Those go to CI. Per-command record: project
file `pm-orders/server/31338-skills-gates-ran.txt`.

- `node scripts/check-skills-token-ratchet.mjs`: exit 0, 3394 / 3394;
`--self-test` exit 0.
- `node scripts/check-empty-changeset.mjs --base origin/main`,
`check-changeset-no-major.mjs`: exit 0.
- `node scripts/check-commit-card-trailers.mjs --range
origin/main..HEAD`: exit 0.

Changeset `.changeset/31338-platform-skill-global-uniques-stop.md`:
`@objectstack/skills` patch, both declaration lines.

## Human Minimum

- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(not touched)
- [x] 2. Every name I added uses the casing for its kind. (none added)
- [x] 3. No formatter ran; `pnpm lint` passes. (no lintable source
touched; CI)
- [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.
- [x] 6. `packages/spec` touched: n/a.
- [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
follows the project's PR convention)

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

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

Author: os-project-manager

.changeset/31338-platform-skill-global-uniques-stop.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the platform skill names the installation-wide uniques stop on a self-hosted `os deploy`
+
+Clause-②: no
+Metadata-protocol: none
+
+`objectstack-platform`'s operations reference: a `use-runtime` target's install refusal now also covers the installation-wide `unique` constraints stop, with its two ways on: rerun with `--confirm-global-uniques` when those constraints are meant platform-wide, else set them `unique: 'organization'`. `os deploy` already accepts the flag; this release only teaches it. Two logger and metrics restatements whose home is `references/plugin-development.md` are cut.

scripts/check-skills-token-ratchet.mjs

@@ -1216,7 +1216,20 @@ export const CEILINGS = new Map([
   // the remainder, +35 measured, raises the row, pinned at the measurement.
   // Same maintainer ruling, verbatim and untranslated:
   // 「A:先削重复,余额按实测提高」 (ruling record 6513306068 on #27847).
-  ['skills/objectstack-platform/references/operations.md', 3375],
+  // 3375 -> 3394: the `use-runtime` paragraph's install refusal also names the
+  // installation-wide uniques stop: rerun with `--confirm-global-uniques` when
+  // those `unique` constraints are meant platform-wide, else set them
+  // `unique: 'organization'`. Paid first by deleting restatement in the same
+  // file (-67 bytes): the Logs bullet's `{ level: 'info', format: 'json' }`
+  // example (home: references/plugin-development.md § ObjectKernel
+  // Configuration) and the Metrics bullet's "(per-plugin startup durations)"
+  // (home: the same file's § Health Monitoring, `Map<name, startup ms>`).
+  // 13500 -> 13574 bytes (+74 net: -67 cut, +141 added) -> ceil(13574 / 4) =
+  // 3394; headroom was 0, so the remainder, +19 measured, raises the row,
+  // pinned at the measurement. Same maintainer ruling, verbatim and
+  // untranslated: 「A:先削重复,余额按实测提高」 (ruling record 6513306068 on
+  // #27847).
+  ['skills/objectstack-platform/references/operations.md', 3394],
   ['skills/objectstack-platform/references/plugin-development.md', 3137],
   ['skills/objectstack-upgrade/references/examples-upgrade.md', 1197],
 

skills/objectstack-platform/references/operations.md

@@ -99,7 +99,7 @@ Port resolution is the same for `os dev` and `os start` (both spawn `os serve`):
 
 **`os deploy` exit 1, cloud:** a refusal before any write publishes nothing: log in (`os cloud login`), pick an environment (`--env`; none: create one in the ObjectOS Cloud console), or fix the local build or `manifest.version`. `could not build …: <reason>`: the environment's build failed, it keeps serving the previous one; fix and deploy again. `Timed out after …`: the install is recorded and a failing build reads as pending for minutes; deploy again with a longer `--wait-timeout`, or see the build in the ObjectOS Cloud console.
 
-**A `use-runtime` target** (no `--env`) asks for no cloud login: build, dry-run plan, install, live on `hotLoaded`. Exit 1: a failed build; a dry run refused, unserved (no install-local) or ignored (an older runtime installed: upgrade it); an install refusal (rerun with the `--confirm-access-upgrade` / `--confirm-upgrade <token>` it printed); installed but not loaded (live after a restart).
+**A `use-runtime` target** (no `--env`) asks for no cloud login: build, dry-run plan, install, live on `hotLoaded`. Exit 1: a failed build; a dry run refused, unserved (no install-local) or ignored (an older runtime installed: upgrade it); an install refusal (rerun with the `--confirm-access-upgrade` / `--confirm-upgrade <token>` it printed, or `--confirm-global-uniques` if its installation-wide `unique` constraints are meant platform-wide, else set them `unique: 'organization'`); installed but not loaded (live after a restart).
 
 > **Cloud connection & marketplace (`@objectstack/cloud-connection`, ADR-0008/0009):**
 > the open runtime-side cloud client; its `MarketplaceInstallLocalPlugin` serves the
@@ -161,10 +161,9 @@ the other imports: [Using Plugins](./plugin-development.md#using-plugins).
 - **Health endpoints:** the HTTP dispatcher exposes `GET /health` and
   `GET /ready` under the API prefix.
 - **Logs:** plugins log via `ctx.logger`. Logger config is a **kernel
-  construction** option, not a `defineStack` key:
-  `new ObjectKernel({ logger: { level: 'info', format: 'json' } })`.
+  construction** option (`new ObjectKernel({ logger })`), not a `defineStack` key.
 - **Metrics:** use the kernel's built-ins — `kernel.getPluginMetrics()`
-  (per-plugin startup durations) and `await kernel.checkAllPluginsHealth()`.
+  and `await kernel.checkAllPluginsHealth()`.
   There is no `metrics` service and no `@objectstack/plugin-prometheus`.
 
 ## Common ops pitfalls