fix: CI build-docs link validation + non-portable cp -n warning #164

2026-09-22T02:30:41Z

rootiest commented

2026-09-22 02:30:41 +00:00

Summary

Two unrelated CI-only fixes found while triaging run #964 (build-docs job failure):

starlight-links-validator failure: docs/manual/08-components-reference/01-c1-command-shadows.md linked to docs/function-classification-schema.md with a manual-tree-relative path. That path resolves fine in docs/manual/, but the file it points at isn't a published Starlight page, so the same relative link breaks once copied into docs/site/src/content/docs/. Rewritten as an absolute Gitea blob URL — the same pattern _rewrite_repo_links already uses for CONTRIBUTING.md/LICENSE.
cp: warning: behavior of -n is non-portable: every CI test run logged this from the four call sites that used cp -rn. Switched to cp -r --update=none, the portable long form with identical behavior.

docs/fish-config.md's stale-concat test failure (verify-manual.py) is pre-existing on bare main and unrelated — CI regenerates that file itself before verifying (.github/workflows/ci.yml), so left untouched.

What / Why

docs/manual/08-components-reference/01-c1-command-shadows.md: relative link → absolute Gitea URL.
functions/_agents_repo_ensure_symlink.fish, functions/agents-init.fish, functions/agents-vault.fish: cp -rn → cp -r --update=none.

Verification

fish -n on all touched .fish files
fish tests/run-tests.fish — 759/759 assertions passed
python3 docs/verify-manual.py — 83/84 (pre-existing, unrelated concat-drift failure only)
npm run build in docs/site — starlight-links-validator reports "All internal links are valid."

Manual verification checklist

Confirm the build-docs CI job passes end to end on this branch
Spot-check the rendered link on the live docs site (Command Shadows page) opens the schema file on Gitea
Run agents-init or agents-vault locally against a populated directory and confirm no cp warning appears and files still merge correctly

## Summary Two unrelated CI-only fixes found while triaging run #964 (`build-docs` job failure): - **`starlight-links-validator` failure**: `docs/manual/08-components-reference/01-c1-command-shadows.md` linked to `docs/function-classification-schema.md` with a manual-tree-relative path. That path resolves fine in `docs/manual/`, but the file it points at isn't a published Starlight page, so the same relative link breaks once copied into `docs/site/src/content/docs/`. Rewritten as an absolute Gitea blob URL — the same pattern `_rewrite_repo_links` already uses for `CONTRIBUTING.md`/`LICENSE`. - **`cp: warning: behavior of -n is non-portable`**: every CI test run logged this from the four call sites that used `cp -rn`. Switched to `cp -r --update=none`, the portable long form with identical behavior. `docs/fish-config.md`'s stale-concat test failure (`verify-manual.py`) is pre-existing on bare `main` and unrelated — CI regenerates that file itself before verifying (`.github/workflows/ci.yml`), so left untouched. ## What / Why - `docs/manual/08-components-reference/01-c1-command-shadows.md`: relative link → absolute Gitea URL. - `functions/_agents_repo_ensure_symlink.fish`, `functions/agents-init.fish`, `functions/agents-vault.fish`: `cp -rn` → `cp -r --update=none`. ## Verification - [x] `fish -n` on all touched `.fish` files - [x] `fish tests/run-tests.fish` — 759/759 assertions passed - [x] `python3 docs/verify-manual.py` — 83/84 (pre-existing, unrelated concat-drift failure only) - [x] `npm run build` in `docs/site` — `starlight-links-validator` reports "All internal links are valid." ## Manual verification checklist - [ ] Confirm the `build-docs` CI job passes end to end on this branch - [ ] Spot-check the rendered link on the live docs site (Command Shadows page) opens the schema file on Gitea - [ ] Run `agents-init` or `agents-vault` locally against a populated directory and confirm no `cp` warning appears and files still merge correctly

rootiest added the Area/CI Area/Docs Area/Functions Kind/Bug labels 2026-09-22 02:31:15 +00:00

rootiest added 2 commits 2026-09-22 02:34:02 +00:00

fix(docs): point classification-schema link at Gitea, not a relative path 18e04dd5fb

The schema file lives at docs/function-classification-schema.md but is
not a published Starlight page, so a relative link resolves fine in the
manual source tree but breaks once copied into
docs/site/src/content/docs/ — starlight-links-validator failed CI's
build-docs job on it. Rewrite it as an absolute Gitea blob URL, the same
pattern _rewrite_repo_links already uses for CONTRIBUTING.md/LICENSE.

fix(functions): use cp --update=none instead of non-portable -n 86aecf0d9d

GNU cp warns that -n's behavior is non-portable and may change; the
long form is stable and silences the CI warning.

rootiest force-pushed fix/classification-schema-link-validation from e624744555 to 86aecf0d9d

2026-09-22 02:34:02 +00:00

Compare

gitea-actions bot added 1 commit 2026-09-22 02:42:12 +00:00

chore(docs): regenerate manual, man page, and component registry 694b084ff1

rootiest merged commit 6156aa7cb9 into main

2026-09-22 02:52:44 +00:00

rootiest deleted branch fix/classification-schema-link-validation

2026-09-22 02:52:44 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#164