docs: three pages link the deployment section index under labels that name neither of its two lifecycles

Restart-when: any PR touches content/docs/ui/setup-app.mdx, content/docs/automation/hook-bodies.mdx or content/docs/kernel/index.mdx (relabel rides as a declared rider)

Observation, not a defect with a repro. Found while re-pointing the deployment section index in #8913 (PR #8983); recorded rather than fixed there, because these three labels are no more wrong after that rewrite than before it, and sweeping them would have widened that PR's surface without evidence forcing it.

Three pages outside the deployment section link /docs/deployment under labels that name neither the platform-runtime lifecycle nor the metadata-app one:

File	Line	Current label
`content/docs/ui/setup-app.mdx`	125	`[Cloud Deployment](/docs/deployment)` — "how Setup behaves in cloud mode"
`content/docs/automation/hook-bodies.mdx`	345	`[Cloud Deployment](/docs/deployment)` — "how artifacts travel from Studio to objectos"
`content/docs/kernel/index.mdx`	45	`[Deployment & Operations](/docs/deployment)`

Line numbers are as of origin/main at 8b9eba51b.

Why it is worth recording:

"Cloud Deployment" was already imprecise — the page is not cloud-specific, and cloud is one venue inside the platform-runtime half. A reader following that label from the UI or automation docs expects a cloud page and gets a two-lifecycle fork.
kernel/index.mdx uses the section title (Deployment & Operations, from content/docs/deployment/meta.json) as the label for the page, whose title is now Deployment Overview. Both strings exist in the nav, which makes the mismatch harder to notice than a plain stale name.

None of this breaks a gate: check:doc-anchors only judges #fragment targets, and lychee only judges that the file resolves. Link labels have no owner, which is why this class drifts silently.

Suggested fix if it is worth a card: relabel all three to the page's own title, and give the two "Cloud Deployment" sites a trailing clause that says which half the reader is being sent to. Small and mechanical; the judgement call is whether a label-only sweep earns a PR of its own.

Generated by Claude Code

Triage (first-touch grading, 2026-08-16): finding → pm:on-hold.

Reason: label-only docs polish with zero measured pull — no gate breaks, no reader defect beyond imprecision; a standalone label-sweep PR does not clear the startup-scope bar today.

Restart condition (named trigger files): the next PR touching any of

content/docs/ui/setup-app.mdx
content/docs/automation/hook-bodies.mdx
content/docs/kernel/index.mdx

carries the relabel as a declared rider (relabel each link to the page's own title, Deployment Overview; give the two "Cloud Deployment" sites a trailing clause naming which lifecycle the reader is being sent to). domain:devx seat: intersect dispatch file surfaces against this list pre-dispatch and name this card when hit.

Provenance: seat-graded (triage Routine); no maintainer ruling involved.

本评论来自分诊座位 Routine。

Generated by Claude Code

Hold released → pm:queue (triage seat, session session_014qTKTqjme5Fp5BH9iRmy6t, rider-clause audit): "the next PR touching" happened twice without the rider riding — hook-bodies.mdx was touched one hour after the hold (#8996) and kernel/index.mdx on 2026-08-18 (#9634); all three labels are verbatim unchanged on origin/main. Three mechanical label edits stop waiting on a mechanism that isn't firing. Release double-checks passed.

Generated by Claude Code

Claimed by the domain:devx PM seat (#6023), session session_01DdCnBGcHeufjrq7drTD3wt, branch claude/issue-8984-deployment-index-link-labels.

Taken by age, after the lane's priority:p1 (#10032, landed as #10466) and its highest Bug (#10288).

fold-or-serial: serial, folds with nothing. Verified by file, not by keyword — the only content/docs/** file touched by anything this seat has in flight is content/docs/permissions/record-view-auditing.mdx (PR #10450). This card's three files are untouched.

⛔ Two older cards were skipped ahead of it, each for a stated reason rather than by preference: #8331 is serial behind PR #10441 (both edit .github/workflows/lint.yml), and #8901 is both a design act and serial behind the stuck PR #10396.

Generated by Claude Code

{
  "issue": 8984,
  "status": "done",
  "branch": "claude/issue-8984-deployment-index-link-labels",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/10480",
  "premise_still_valid": true,
  "summary": "Relabelled all three /docs/deployment index links named on the card. Read the target page first: it is titled 'Deployment Overview' and forks into 'The platform runtime - you operate it' (Docker/Compose/K8s/bare-Node/ObjectStack Cloud are venues INSIDE this half, per the page's own words) and 'Your metadata app - you build it' (compile to dist/objectstack.json, then catalog install or artifact-pinned boot). setup-app.mdx:125 and hook-bodies.mdx:346 said 'Cloud Deployment' and now use the page title plus a trailing clause naming which half; kernel/index.mdx:46 used the section title from deployment/meta.json and now uses the page title. Each replacement was fitted to its own clause rather than globally substituted: setup-app's Related bullets take no trailing period, hook-bodies' See-also bullets do, and kernel's is mid-sentence prose whose surrounding words ('running the kernel in production') already name the half, so only the label token changed. Line drift from the card: hook-bodies is at 346 on current main, not 345 (card's numbers were as of 8b9eba51b). Labels only - no link target, heading, page structure or meta.json title touched. skip-changeset applied and read back; content/ is outside every pnpm-workspace glob and its only consumer apps/docs is private:true, so nothing here is a published package surface.",
  "tests": "All gates re-run AFTER the final commit and measured at HEAD=6cdb7a9c10 with a clean tree (git status --porcelain empty). Gate families derived by `node scripts/pm/dispatch-gates.mjs` with NO paths passed (it derives its own change set from the merge base) - 12 families, re-derived at the final commit as identical, no additions. All 12 plus check:nul-bytes exited 0; exit codes captured by redirect-then-capture, never through a pipe. Quoting each gate's own verdict line, not $?: check-doc-anchors -> '256 internal #fragment link(s) across 400 source file(s) all resolve to a real heading'; check-docs-redirects -> 'OK (apps/docs/redirects.mjs: 92 entries -- 89 page destination(s) resolved against content/docs, 3 wildcard, 0 outside the /docs route space)'; check-runtime-services-index -> '8 chapter page(s) vs meta.json \"pages\", 8 chapter-list bullet(s) and 8 kernel/index.mdx table row(s) ... all enumerations agree' (this one reads the file I edited); check-docs-audit-scope -> 'docs-accuracy-audit scope is in sync with content/docs/: 181 hand-written doc(s)'; check-role-word -> 'OK, no new occurrences of the reserved word'; check-published-readme-links -> '152 outbound link(s) across 60 published markdown file(s)'; check-nul-bytes -> 'OK (scanned 6141 text file(s) ... no raw ASCII control bytes)'. The four spec-filtered gates (check:liveness, check:empty-state, check:strictness-ledger, check:variant-docs) each echoed '@objectstack/spec@17.1.0 check:...' in their logs, confirming a real run rather than a zero-match --filter no-op that would have exited 0 having run nothing. No unit tests exist for docs prose; lychee link-checking is CI-only and no link target moved. Edits were proven on disk in both directions before being trusted (removed strings now grep to 0 tree-wide, injected strings grep to exactly 1 each) rather than relying on the edit tool's exit code. Heavy steps (pnpm install, gate union) went through scripts/pm/os-verify-lock.sh; one union attempt returned the queue-timeout VERDICT (exit 99) behind another agent's 610s turbo build and was retried to completion rather than reported from the pre-commit run.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #10476: kernel/index.mdx:46 labels /docs/plugins as 'Plugins & Packages' (the section title from plugins/meta.json) while the page it lands on is titled 'Plugin System' - same shape as this card, different target, on the very same line I edited. Deliberately NOT swept in: the correct shape is not pinned by evidence (section-reference vs page-reference is an unmade judgement), and content/docs/index.mdx's module grid uses section titles uniformly for section-root links even where they diverge from the page title (Views & Apps -> UI Engine, API & SDK -> API Overview), which argues the other way. Filed unassigned with both readings and named explicitly in the PR body so the untouched label on an edited line does not read as an oversight."
  ],
  "census": {
    "positive_control": "Proven before trusting any zero-hit: grep -rn '(/docs/deployment)' over the three named files returned exactly the three known instances.",
    "expression": "grep -rnE '/docs/deployment([^/[:alnum:]_-]|$)' content/  (verified byte-identical, diff clean, to the -P negative-lookahead form actually run; the -P literal cannot be carried in GitHub body text because the sanitizer strips its exclamation mark - confirmed on the RENDERED page, then repaired)",
    "result": "9 links to the index across 8 files - 3 defective (fixed), 1 examined and cleared, 5 already correct. So three was what the card noticed, not the count.",
    "already_correct": "api/environment-routing.mdx:128, deployment/single-project-mode.mdx:113, deployment/self-hosting.mdx:14, deployment/self-hosting.mdx:436, deployment/publish-and-preview.mdx:221 - all 'Deployment Overview'. self-hosting.mdx:436 already carries a trailing clause naming both lifecycles and was used as the in-repo precedent for the two rewritten clauses.",
    "examined_and_cleared": "content/docs/index.mdx:51 - a Card in the '## Platform modules' grid labelled 'Deployment & Operations'. Left alone deliberately: that grid uses section titles for section-root links throughout, including where they diverge from the page title (Views & Apps -> UI Engine, API & SDK -> API Overview). Changing only the deployment card would break a uniform nine-card convention, and re-titling the grid is a restructure rather than a relabel.",
    "outside_content": "None. The same expression over *.md/*.mdx/*.ts/*.tsx/*.json outside content/ (excluding node_modules) returned nothing. No trailing-slash or #fragment forms of the index link exist.",
    "not_touched": "content/docs/releases/** (release-owned, review-only - no deployment-label defect seen there) and content/docs/permissions/record-view-auditing.mdx (held by open PR #10450)."
  }
}

Generated by Claude Code

os-dev-report

Supersedes the previous comment: its first-line  marker was stripped by GitHub's body sanitizer (verified by reading the stored body back — it begins with a bare newline), which would have made that copy invisible to the PM's scan. Same JSON, literal-text marker. No comment-edit tool is available to this session, hence a new comment rather than an edit.

{
  "issue": 8984,
  "status": "done",
  "branch": "claude/issue-8984-deployment-index-link-labels",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/10480",
  "premise_still_valid": true,
  "summary": "Relabelled all three /docs/deployment index links named on the card. Read the target page first: it is titled 'Deployment Overview' and forks into 'The platform runtime - you operate it' (Docker/Compose/K8s/bare-Node/ObjectStack Cloud are venues INSIDE this half, per the page's own words) and 'Your metadata app - you build it' (compile to dist/objectstack.json, then catalog install or artifact-pinned boot). setup-app.mdx:125 and hook-bodies.mdx:346 said 'Cloud Deployment' and now use the page title plus a trailing clause naming which half; kernel/index.mdx:46 used the section title from deployment/meta.json and now uses the page title. Each replacement was fitted to its own clause rather than globally substituted: setup-app's Related bullets take no trailing period, hook-bodies' See-also bullets do, and kernel's is mid-sentence prose whose surrounding words ('running the kernel in production') already name the half, so only the label token changed. Line drift from the card: hook-bodies is at 346 on current main, not 345 (card's numbers were as of 8b9eba51b). Labels only - no link target, heading, page structure or meta.json title touched. skip-changeset applied and read back; content/ is outside every pnpm-workspace glob and its only consumer apps/docs is private:true, so nothing here is a published package surface.",
  "tests": "All gates re-run AFTER the final commit and measured at HEAD=6cdb7a9c10 with a clean tree (git status --porcelain empty). Gate families derived by `node scripts/pm/dispatch-gates.mjs` with NO paths passed (it derives its own change set from the merge base) - 12 families, re-derived at the final commit as identical, no additions. All 12 plus check:nul-bytes exited 0; exit codes captured by redirect-then-capture, never through a pipe. Quoting each gate's own verdict line, not $?: check-doc-anchors -> '256 internal #fragment link(s) across 400 source file(s) all resolve to a real heading'; check-docs-redirects -> 'OK (apps/docs/redirects.mjs: 92 entries -- 89 page destination(s) resolved against content/docs, 3 wildcard, 0 outside the /docs route space)'; check-runtime-services-index -> '8 chapter page(s) vs meta.json \"pages\", 8 chapter-list bullet(s) and 8 kernel/index.mdx table row(s) ... all enumerations agree' (this one reads the file I edited); check-docs-audit-scope -> 'docs-accuracy-audit scope is in sync with content/docs/: 181 hand-written doc(s)'; check-role-word -> 'OK, no new occurrences of the reserved word'; check-published-readme-links -> '152 outbound link(s) across 60 published markdown file(s)'; check-nul-bytes -> 'OK (scanned 6141 text file(s) ... no raw ASCII control bytes)'. The four spec-filtered gates (check:liveness, check:empty-state, check:strictness-ledger, check:variant-docs) each echoed '@objectstack/spec@17.1.0 check:...' in their logs, confirming a real run rather than a zero-match --filter no-op that would have exited 0 having run nothing. No unit tests exist for docs prose; lychee link-checking is CI-only and no link target moved. Edits were proven on disk in both directions before being trusted (removed strings now grep to 0 tree-wide, injected strings grep to exactly 1 each) rather than relying on the edit tool's exit code. Heavy steps (pnpm install, gate union) went through scripts/pm/os-verify-lock.sh; one union attempt returned the queue-timeout VERDICT (exit 99) behind another agent's 610s turbo build and was retried to completion rather than reported from the pre-commit run.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #10476: kernel/index.mdx:46 labels /docs/plugins as 'Plugins & Packages' (the section title from plugins/meta.json) while the page it lands on is titled 'Plugin System' - same shape as this card, different target, on the very same line I edited. Deliberately NOT swept in: the correct shape is not pinned by evidence (section-reference vs page-reference is an unmade judgement), and content/docs/index.mdx's module grid uses section titles uniformly for section-root links even where they diverge from the page title (Views & Apps -> UI Engine, API & SDK -> API Overview), which argues the other way. Filed unassigned with both readings and named explicitly in the PR body so the untouched label on an edited line does not read as an oversight."
  ],
  "census": {
    "positive_control": "Proven before trusting any zero-hit: grep -rn '(/docs/deployment)' over the three named files returned exactly the three known instances.",
    "expression": "grep -rnE '/docs/deployment([^/[:alnum:]_-]|$)' content/  (verified byte-identical, diff clean, to the -P negative-lookahead form actually run; the -P literal cannot be carried in GitHub body text because the sanitizer strips its exclamation mark - confirmed on the RENDERED page, then repaired)",
    "result": "9 links to the index across 8 files - 3 defective (fixed), 1 examined and cleared, 5 already correct. So three was what the card noticed, not the count.",
    "already_correct": "api/environment-routing.mdx:128, deployment/single-project-mode.mdx:113, deployment/self-hosting.mdx:14, deployment/self-hosting.mdx:436, deployment/publish-and-preview.mdx:221 - all 'Deployment Overview'. self-hosting.mdx:436 already carries a trailing clause naming both lifecycles and was used as the in-repo precedent for the two rewritten clauses.",
    "examined_and_cleared": "content/docs/index.mdx:51 - a Card in the '## Platform modules' grid labelled 'Deployment & Operations'. Left alone deliberately: that grid uses section titles for section-root links throughout, including where they diverge from the page title (Views & Apps -> UI Engine, API & SDK -> API Overview). Changing only the deployment card would break a uniform nine-card convention, and re-titling the grid is a restructure rather than a relabel.",
    "outside_content": "None. The same expression over *.md/*.mdx/*.ts/*.tsx/*.json outside content/ (excluding node_modules) returned nothing. No trailing-slash or #fragment forms of the index link exist.",
    "not_touched": "content/docs/releases/** (release-owned, review-only - no deployment-label defect seen there) and content/docs/permissions/record-view-auditing.mdx (held by open PR #10450)."
  }
}

Generated by Claude Code

Navigation Menu

Repository navigation

docs: three pages link the deployment section index under labels that name neither of its two lifecycles #8984

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs: three pages link the deployment section index under labels that name neither of its two lifecycles #8984

Description

Activity

os-project-manager commented on Aug 16, 2026

os-zhuang commented on Aug 19, 2026

os-zhuang commented on Aug 21, 2026

os-zhuang commented on Aug 21, 2026

os-zhuang commented on Aug 21, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions