fix(docs): repair 4 links broken by #18, add a doc-link gate

Taskfile.yml

@@ -56,6 +56,11 @@ tasks:
     cmds:
       - ./tools/check-yaml-schemas.sh
 
+  doc-links:
+    desc: Check every relative Markdown link resolves
+    cmds:
+      - ./tools/check-doc-links.sh
+
   ai-integrations:
     desc: Validate Codex, ChatGPT, and plugin discovery surfaces
     cmds:
@@ -80,5 +85,6 @@ tasks:
       - task: nushell
       - task: nushell-demo
       - task: yaml-schemas
+      - task: doc-links
       - task: ai-integrations
       - task: test

lefthook.yml

@@ -45,6 +45,14 @@ pre-commit:
       glob: "*.{yml,yaml,cff}"
       run: ./tools/check-yaml-schemas.sh
 
+    # Docs are the product here, so a dangling relative link is a defect. Runs
+    # on any markdown change; self-scans the whole tree because moving one file
+    # breaks links in files the commit never touched -- which is exactly how
+    # #18 shipped four of them.
+    doc-links:
+      glob: "*.md"
+      run: ./tools/check-doc-links.sh
+
     # Codex/ChatGPT discovery surfaces. This is cheap and self-scans, so
     # it runs on every pre-commit to catch extensionless repo-scope skill links.
     ai-integrations:

reference/nushell.md

@@ -234,7 +234,7 @@ the script — ideal for CI and pre-commit. This repo's `task nushell`
   ([nushell/nushell.github.io](https://github.com/nushell/nushell.github.io));
   rules here are summarized, with links back to each source page.
 
-See [`skills/nushell`](../skills/nushell/) for the agent-facing summary and
+See [`skills/shell`](../skills/shell/) for the agent-facing summary and
 [`examples/nushell/`](../examples/nushell/) for parse-clean fragments.
 
 ## Invoking `nu` from an agent or a script

reference/shebang.md

@@ -135,4 +135,4 @@ this guide exists for.
 - Linux shebang doc fix, commit `f718c9fa87be` (Alan Urmancheev, [@alurm](https://github.com/alurm))
   — <https://github.com/torvalds/linux/commit/f718c9fa87be>
 
-See [`skills/shebang`](../skills/shebang/) and [`examples/shebang/`](../examples/shebang/).
+See [`skills/shell`](../skills/shell/) and [`examples/shebang/`](../examples/shebang/).

reference/streams.md

@@ -137,4 +137,4 @@ assumes a green lint means the streams are right.
 - Greg's Wiki — BashFAQ/001, BashPitfalls —
   <https://mywiki.wooledge.org/BashFAQ/001>
 
-See [`skills/streams`](../skills/streams/) and [`examples/streams/`](../examples/streams/).
+See [`skills/shell`](../skills/shell/) and [`examples/streams/`](../examples/streams/).

reference/zsh.md

@@ -178,4 +178,4 @@ Three independent reasons `"${TTY}"` is correct and `$(tty)` is not:
   [Powerlevel10k](https://github.com/romkatv/powerlevel10k),
   [gitstatus](https://github.com/romkatv/gitstatus)
 
-See [`skills/zsh`](../skills/zsh/) for the summary.
+See [`skills/shell`](../skills/shell/) for the router summary.

tools/check-doc-links.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+#
+# check-doc-links.sh — every relative Markdown link must resolve.
+#
+# Why this exists: collapsing seven skills into one router (#18) deleted
+# skills/{nushell,shebang,streams,zsh}/ but left four reference/*.md files
+# linking to them. Every other gate stayed green -- lint, tests, examples,
+# schemas, ai-integrations -- because none of them reads a link. In a repo
+# whose product IS its documentation, a dangling link is a defect.
+#
+# Only relative targets are checked. External URLs are deliberately not
+# fetched: that needs network, is slow, and turns someone else's outage into
+# a red build.
+#
+# One grep+sed per file is a deliberate choice over a single clever pass. A
+# rewrite that hoisted both out of the loop to avoid the subprocesses silently
+# mangled its own field splitting and reported every link as broken. Two
+# subprocesses per markdown file is cheap; a checker that lies is not.
+set -euo pipefail
+
+status=0
+checked=0
+
+while IFS= read -r file; do
+  dir=$(dirname "${file}")
+
+  while IFS= read -r target; do
+    [[ -z ${target} ]] && continue
+    case "${target}" in
+      http://* | https://* | mailto:* | '#'*) continue ;;
+      *) ;;
+    esac
+
+    target=${target%%#*}
+    [[ -z ${target} ]] && continue
+
+    checked=$((checked + 1))
+    if [[ ! -e "${dir}/${target}" ]]; then
+      printf 'broken link: %s -> %s\n' "${file}" "${target}" >&2
+      status=1
+    fi
+    # `[text](target)` with no spaces or parens inside the target, which is
+    # what every link in this repo looks like.
+  done < <(grep -o '\[[^][]*\]([^() ]*)' "${file}" | sed 's/.*(\(.*\))/\1/')
+done < <(git ls-files '*.md')
+
+if [[ ${status} -eq 0 ]]; then
+  printf 'doc-links: OK (%s relative links resolve)\n' "${checked}"
+fi
+
+exit "${status}"