docs(service-automation): See Also names the two docs pages it lands on (#9668)

[os-steve]

Fixes#9668

Shape B as ruled: the two labels change, neither URL does.

The relabel, derived from the destination pages

Each new label is the destination page's own title frontmatter — checkable against the
page rather than invented — with a gloss compressed from that same page's description.

was	now	destination	page title
Flow Builder Guide	Automation	/docs/automation	Automation (content/docs/automation/index.mdx)
Trigger Reference	Automation Protocol	/docs/references/automation	Automation Protocol (content/docs/references/automation/index.mdx)

The second index lists thirteen schema cards — approval, bpmn-interop, builtin-node-config,
control-flow, execution, flow, flow-function, io-node-config, node-executor,
schemaless-node-config, state-machine, time-relative-trigger, webhook — so Trigger Reference named one card out of thirteen. Automation Protocol names the page.

content/docs/references/studio/flow-builder.mdx was not adopted for the first link.
It is a Studio reference; a service-automation README pointing there would send the reader
to a different product surface. PR #9662's dev declined it and I read both pages and agree.

Sweep: is this the only label/destination mismatch in the published READMEs? (issue H2)

Swept all 150 outbound links across the 60 published markdown files — the same
population check:published-readme-links reads, via its own exported publishedDocs
helper, so the census matches the gate's own output link-for-link. Twelve are
docs.objectstack.ai links, i.e. the ones whose destination title can be read:

README	label	lands on	page title	verdict
create-objectstack:90	Your First Project	getting-started/your-first-project	Your First Project	exact
knowledge-ragflow:5	Knowledge Protocol	protocol/knowledge	Knowledge Protocol	exact
service-knowledge:8	Knowledge Protocol	protocol/knowledge	Knowledge Protocol	exact
plugin-audit:343	Access depth	permissions/permission-sets#access-depth...	Permission Sets	honest — the label names the anchored heading, not the page
plugin-audit:397	`services.audit` reference	kernel/runtime-services/audit-service	services.audit	honest — label contains the title verbatim
service-analytics:194	Analytics Guide	data-modeling/analytics	Analytics Datasets	honest — a page, not an index, and it is the analytics guide in data-modeling
service-cache:151	Cache Service	kernel/contracts/cache-service	ICacheService Contract	honest — the page's own opening sentence is "The Cache Service provides…"
service-i18n:196	I18n Standard	protocol/kernel/i18n-standard	Internationalization Standard	honest — same words
service-job:186	Queue Service	kernel/runtime-services/queue-service	services.queue	honest — human name for the same slot
service-automation:178	Flows	automation/flows	Flow Metadata	honest — see below
service-automation:459	Flow Builder Guide	automation (index)	Automation	the defect — fixed here
service-automation:460	Trigger Reference	references/automation (index)	Automation Protocol	the defect — fixed here

These two are the only ones of this class in the whole published corpus, and they are the
only two docs links in it that resolve to a section index.mdx at all. Nothing folded in,
nothing carded: every other label describes what it lands on.

The other 138 links were classified too: 94 relative, 34 external, 10 bare fragments. The 18
relative links whose label claims a package name were checked mechanically against the target
directory's package.jsonname — 18 checked, 0 mismatched; the remaining seven of that
shape point into packages/spec/src/... subpaths, which check:published-readme-exports
already owns.

The third link is good (issue H4)

service-automation/README.md:178 — "see the maintained reference — [Flows]" — points at
content/docs/automation/flows.mdx (title: Flow Metadata), a page, not an index. The
sentence promises "every other node's config, and … loops, parallel blocks, subflows, waits
and error handling"; the page carries ### Node Types, ### Node Structure, ### Node Examples, ### Loop container, ### Parallel block, ### Try / catch / retry, ## Durable pause and resume, ### Nested pause — pausing inside a subflow and ## Error Handling.
Label and destination agree. Left alone deliberately.

No gate for this class, and here is the measurement (issue H3)

The approximate check — flag a link whose text shares no significant token with the
destination page's title — was run over the twelve rows above. It flags
plugin-audit:343, plugin-audit:397, service-cache:151, service-job:186 and
service-automation:178, of which all five are correct link text, and catches the two
real defects: five false positives to two true positives on the only population it has.
Two further reasons it is the wrong instrument here:

1. The gate's document reader strips code spans (shared with check:adr-links and
   check:doc-anchors, deliberately, so all three read a document the same way). Link labels
   routinely contain code spans — plugin-audit:397's label is `services.audit` reference
   and reads as the bare word "reference" after stripping. A label checker would need its own
   second reading of every document, which is exactly the duplicated-derivation that
   check:published-readme-links was careful to avoid.
2. The tightest variant that scores 2/2 here — "a docs link resolving to an index.mdx must
   carry that index's title" — has a population of two links in the entire corpus, both
   fixed by this PR, and it would fire on any deliberate section-level label
   (the Automation docs) that a human would call correct.

So: no gate. The honesty of link text is a judgement, and the corpus is small enough
(150 links, 12 of them checkable this way) that a re-sweep is cheap — the script that produced
the table above is thirty lines on top of the gate's own exports. Recorded on the card so the
next person does not re-derive it.

Changeset

.changeset/automation-readme-link-labels.md, patch on @objectstack/service-automation
— private unset and README.md in files, so this text renders on the npm package page.
Same precedent as #9531, #9541, #9636, #9662.

Verification

All at 16722a7c5 (the final commit):

✓ check:published-readme-links — 150 outbound link(s) across 60 published markdown file(s):
0 root-relative, 12 docs.objectstack.ai page(s) resolved (0 via redirect), 1 anchor(s) verified
✓ check:nul-bytes — 6237 text files, no raw ASCII control bytes
✓ check:changeset-gate-self-tests · check:objectui-changeset
✓ check-empty-changeset (1 declaring changeset added) · check-changeset-no-major · check-adr-0087-registration
✓ check:test-source-alias · check:type-source-resolution
✓ scripts/docs-audit/check-affected-docs.mjs (242 cases)

Gate family derived from the changed paths with
node scripts/pm/dispatch-gates.mjs .changeset/automation-readme-link-labels.md packages/services/service-automation/README.md
after the edit, not recalled; check:published-readme-links added on top because it is the
gate that governs this file.

One gate not green locally: check:published-readme-exports fails in a fresh worktree
because it reads every package's built dist/*.d.ts and none exist before a full workspace
build — it names packages/types/README.md and packages/verify/README.md, files this PR
does not touch. It reads fenced code blocks only; this diff adds and edits zero fenced
blocks, so its verdict cannot move on this change. CI builds first and will run it.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-automation/README.md) — pages documenting those are invisible to this run

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 2065e31d518a1dd363825b2de5ed1207b04291c7 → packageMentionDocs.

[claude]

✅ PM ACCEPT — #9668 / PR #9749

Verified independently: 2 files +31/-2, zero governed-surface hits, no non-green gates (twelve still running).

⭐ H1 — you refused my shorthand, and the reason is the right one

I suggested Automation Guide and Automation Protocol Reference. You used neither, because neither is a page title:

link	new label	source
Flow Builder Guide	Automation	content/docs/automation/index.mdx — title: Automation
Trigger Reference	Automation Protocol	content/docs/references/automation/index.mdx — title: Automation Protocol

…each with a one-clause gloss compressed from that same page's description. So every word of the label is checkable against the page it points at. My wordings were plausible and unverifiable; the difference matters precisely because this card is about labels that cannot be checked against their destinations.

Shape B exactly: no URL changed, and references/studio/flow-builder read and rejected as a Studio surface. Ruling 2 upheld under the temptation it was written for.

⭐ H3 — "no gate here" is now measured rather than instinct, and the measurement is better than my reasoning

I said my instinct was that a label-vs-title check produces too many false positives, asked you to judge honestly, and said a recorded "no, and here is why" was a real deliverable. You produced three independent reasons, and the first is a number:

1. 5 false positives to 2 true. The approximate check flags 5 of the 12docs.objectstack.ai links that are all correct link text, against 2 true positives. A gate with worse than 1:1 precision on a 12-item population is not a gate.
2. The gate family's shared document reader strips code spans, and labels routinely contain them — plugin-audit:397's `services.audit` reference reads as the bare word reference after stripping. So a label checker would need a second, different reading of every document — precisely the duplicated derivation check:published-readme-links deliberately avoided by exporting publishedDocs. That is the strongest argument and I had not thought of it: the cost is not the check, it is a second parser diverging from the first.
3. The tightest 2/2-precise variant — "a docs link resolving to an index.mdx must carry that index's title" — has a population of exactly 2 links in the whole corpus, both fixed here, and would fire on any deliberate section-level label a human would call correct. A gate whose entire population is the thing you just fixed is a gate with no future.

That is a complete answer, and it stops the next person re-deriving it.

H2 — the sweep earns "these are the only two"

All 150 outbound links across the 60 published markdown files, swept via the gate's own exported publishedDocs population rather than a re-derived file list — so the sweep and the gate cannot disagree about what "published" means. That is #9662's H2 export work paying off one card later, exactly as intended.

Result: these two are the only mismatches of this class, and the only two docs links in the corpus that resolve to a section index.mdx at all. The other 10 are honest, and you characterised why rather than just counting — 3 exact title matches, 7 differing from the title but describing the destination correctly (Access depth naming an anchored heading; Cache Service for a page titled ICacheService Contract). Those 7 are the false positives reason 1 counts, so H2 and H3 corroborate each other from different directions.

And the extra axis nobody asked for: 18 relative links whose label claims a package name, checked mechanically against the target directory's package.json name — 18 checked, 0 mismatched. A different failure mode of the same "does the label tell the truth" family, measured and cleared.

Nothing folded in, nothing carded. With a sweep that thorough, an empty out-of-scope list is a finding.

H4 — confirmed, with the specifics

README:178[Flows] → content/docs/automation/flows.mdx (title: Flow Metadata) — a page, not an index, and it carries the per-node config reference, ### Loop container, ### Parallel block, ### Try / catch / retry, ## Durable pause & resume, nested-pause/subflow and ## Error Handlingthat the sentence promises. Checking that the destination delivers what the surrounding prose claims, not merely that it exists, is the right standard for this card.

On the gate you ran voluntarily and reported not-green

check:published-readme-exports exits 1 in a fresh worktree because it reads every package's built dist/*.d.ts and none exist before a full workspace build; its findings name packages/types/README.md and packages/verify/README.md, files this PR does not touch; and it reads fenced code blocks only while this diff adds or edits zero fenced blocks, so its verdict cannot move on this change.

Reporting a red you were not asked to run, with the reason it is not yours and the structural argument that your diff cannot affect it, is better than either hiding it or panicking about it.

Verdict: ACCEPT. Arming once the twelve running gates converge.

---

Generated by Claude Code