docs(skills): the automation skill's inbound-hook table names config.secretRef (#25708)

Refs #25675

Clause-②: no
Metadata-protocol: none
Ruling-ref: 6386630545

The governed half of #25675, split out of #25703 so that PR's diff stays
ungoverned. **Merge this after #25703.** This row documents
`config.secretRef`, which #25703 adds to the protocol. Landed alone, the
skill would teach a key the runtime does not have yet.

## What changes

`skills/objectstack-automation/SKILL.md`, in the inbound webhook (`api`)
start-node table:

- The `secret` row said a non-blank literal is required or the flow is
refused. Once #25703 lands that is false. The row is now `secretRef` /
`secret`: one of the two is required, a package ships `secretRef:
'NAME'` (an env var the deployment fills, not `OS_*`; unfilled means
`503`), and never a literal.
- The `x-objectstack-signature` header name moved from the row into the
signature line, so it is not lost.

`skills/objectstack-automation/references/_index.md` stays in #25703. It
is `gen:skill-refs` output that `check:skill-refs` requires to ride the
spec change, and `check-governed-merges` lifts it there as a pure
regeneration (measured: #25703's file list reads NOT governed with it).

Changeset: `.changeset/25675-skills-secret-ref-row.md`,
`@objectstack/skills` patch.

## Skill readings (`skills/**`)

- `skills/objectstack-automation/SKILL.md`: 438 → 438 lines; 5755 → 5771
tokens (ceiling 5780, `check-skills-token-ratchet` exit 0).
- Whole pack (all `SKILL.md`): 4389 → 4389 lines; ratcheted authored
tokens +16.

## Verification

All at head `44ca1a08` (on `origin/main` `b77bb37e`). `dispatch-gates
--commands` derived 46 families: 44 exit 0, and 2 exit 3, a refused
prerequisite, so NOT MEASURED (`check:dual-build-cjs-loads`,
`check:lean-entry-closure`: the full workspace build). `--ran`
reconciliation: 46 accounted, 44 run, 2 NOT-MEASURED, 0 UNRUN.
`check-governed-merges --test` on this file list reads governed: 1 of 2
paths hits the register (`skills/**`, Tier H), as intended.

## 维护者速读(草稿)

- **改了什么**：自动化技能文档里 `api` 流程起始节点那一行，从「必须写非空字面 `secret`」改为「`secretRef` 或
`secret` 二选一；包里写 `secretRef: '名字'`，由部署方用同名环境变量填值（不得用 `OS_` 开头），没填值时每次请求回
503；不要提交字面密钥」。
- **为什么改**：#25703 新增了 `config.secretRef`（裁决 A），原句随之变假。这份技能文档会发给客户的 AI
读，不改的话 AI 会继续照抄字面密钥进公开仓库。
- **风险与代价（含回滚）**：只改文档一行，token 增加 16（在上限内），行数不变。必须在 #25703
之后合并，否则文档先于运行时。回滚即还原本 PR。
- **席位意见**：
- **你要做的**：在 #25703 合并后批准并合并本 PR（Tier H，需你的批准）。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01NZJKktPWaz2EZJ95a9XZa8

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

---------

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

Author: objectstack-fleet[bot]

.changeset/25675-skills-secret-ref-row.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the automation skill's inbound-hook table names `config.secretRef`, the form a package ships instead of a literal secret
+
+Clause-②: no
+
+Metadata-protocol: none
+
+The `objectstack-automation` skill's start-node table said an `api` flow needs a non-blank literal `secret`, or the flow is refused at registration. An `api` flow's start node may now name its secret instead, with `secretRef: 'NAME'`: the deployment fills that name (an environment variable in the open tier, never `OS_*`), and the engine reads it at every post, answering `503` while the name is unfilled. The row now says either one is required, and that a package ships `secretRef` and never commits a literal. The signature line names the `x-objectstack-signature` header the row used to carry.

skills/objectstack-automation/SKILL.md

@@ -335,14 +335,14 @@ just never runs. Two pairs are instead **refused** at `os validate` / `build` /
 
 An `api` flow is bound to an inbound HTTP endpoint:
 `POST /api/v1/automation/hooks/:flowName/:hookId`. Configure it on the **start
-node `config`** (the start `config` is a free-form record with no Zod shape):
+node `config`**:
 
 | `config` key | Purpose |
 |:-------------|:--------|
 | `hookId` | URL path token (default `'default'`). **Rotate it to revoke** a leaked endpoint |
-| `secret` | HMAC-SHA256 shared secret. **Required** — without a non-blank one the flow is refused at registration (`os validate` too) and never armed at boot; the signature goes in `x-objectstack-signature` |
+| `secretRef` / `secret` | HMAC-SHA256 secret, **one required** (else refused at registration and `os validate`). Ship `secretRef: 'NAME'`: an env var the deployment fills, not `OS_*`; unfilled ⇒ `503`. Never a literal |
 
-- **Signature:** `t=<unix seconds>,v1=<hex>` — `v1` = HMAC-SHA256 of `<t>.<raw body>` under `secret`; refused when `t` is over 300 s from the server clock.
+- **Signature:** `x-objectstack-signature: t=<unix seconds>,v1=<hex>` — `v1` = HMAC-SHA256 of `<t>.<raw body>` under the secret; refused when `t` is over 300 s from the server clock.
 - **Idempotency:** `x-idempotency-key` dedupes retries — author the flow to be idempotent (delivery is at-least-once).
 - **Queue-backed:** the endpoint ACKs `202` and enqueues; the flow runs on the consumer, never in-band.
 - The JSON body surfaces to the flow as the trigger record (`record.*` / bare fields) plus `params`.