diff --git a/.changeset/25675-skills-secret-ref-row.md b/.changeset/25675-skills-secret-ref-row.md
new file mode 100644
index 00000000000..893a889cf7a
--- /dev/null
+++ b/.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.
diff --git a/skills/objectstack-automation/SKILL.md b/skills/objectstack-automation/SKILL.md
index 792d7619b58..be3f4fa3e60 100644
--- a/skills/objectstack-automation/SKILL.md
+++ b/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`.