@uipath/skills 1.195.0

package/skills/uipath-ixp/references/project-setup-guide.md

@@ -0,0 +1,90 @@
+# Project Setup Guide
+
+Complete workflow for creating a **new** IXP project, labelling all documents, and getting initial metrics. Run all steps end-to-end automatically.
+
+> **Wrong page if the project already exists.** Use `uip ixp documents upload <project-name> <file>` — see [CLI Reference § Uploading documents](cli-reference.md#uploading-documents-to-an-existing-project).
+
+## Step 1 — Create the Project
+
+If the user provides a name, use it. If not, generate a temporary name (e.g., `ixp_project_NNNN` with a random number) — the project will be renamed in Step 3 after the taxonomy reveals the document type.
+
+`<folder-path>` is filtered to supported document files — see [CLI Reference § Supported document files](cli-reference.md#supported-document-files).
+
+**Option A — Auto-suggest taxonomy (default):**
+
+```bash
+uip ixp projects create "<name>" <folder-path> --output json
+```
+
+If the user specified what to extract, add `-d` for a better taxonomy suggestion:
+
+```bash
+uip ixp projects create "<name>" <folder-path> -d "<what to extract>" --output json
+```
+
+This uploads documents and auto-suggests a taxonomy based on the document content (and the description if provided).
+
+**Option B — Blank project + import taxonomy from file:**
+
+If the user provides a taxonomy file, create a blank project and import separately:
+
+```bash
+uip ixp projects create "<name>" <folder-path> --skip-taxonomy --output json
+uip ixp projects import-taxonomy <project-name> <taxonomy-file> --output json
+```
+
+The taxonomy file can be in either format — the CLI auto-detects based on which keys are present:
+
+- `{ "field_types": [...], "label_group": {...} }` — use when importing a taxonomy suggested by a previous `project create` run
+- `{ "entity_defs": [...], "label_groups": [...] }` — use when importing a taxonomy file provided by the user, or cloning from an existing project (exported via `uip ixp projects get-taxonomy`)
+
+Use the `ProjectName` from the create output for all subsequent commands. This is the lowercase slug with UUID and `-ixp` suffix (e.g., `my_invoices-f1afa9ef-ixp`), NOT the Title.
+
+Create the working directory using the returned `ProjectName`:
+
+```bash
+mkdir -p /tmp/ixp/<project-name>/{docs,text,taxonomies,prompts}
+```
+
+## Step 2 — Configure the Model
+
+Before labelling, configure the extraction model based on what the documents look like. Download 2-3 sample document images and view them:
+
+```bash
+uip ixp documents list <project-name> --output json
+uip ixp documents download <project-name> <document-id> -o /tmp/ixp/<project-name>/docs/sample --output json
+```
+
+View with the **Read tool**, then decide:
+
+| Document characteristics | Pre-processing | Model |
+|--------------------------|---------------|-------|
+| Simple documents, no tables | `none` | `gemini_2_5_flash` |
+| Documents with simple tables or multiple tables | `table_mini` | `gemini_2_5_flash` |
+| Complex nested tables, merged cells, multi-page tables | `table` | `gemini_2_5_flash` |
+| Very long documents (100+ pages) | `none` or `table_mini` | `gemini_2_5_pro` |
+
+Apply the configuration:
+
+```bash
+uip ixp projects configure-model <project-name> \
+  --model gemini_2_5_flash \
+  --preprocessing <none|table_mini|table> \
+  --output json
+```
+
+**Default recommendation:** `--model gemini_2_5_flash --preprocessing table_mini` — works well for most invoice/document types.
+
+## Step 3 — Name the Project
+
+Based on the taxonomy from Step 1 (e.g., if it has "Invoice Details", "Line Items", "Bill-To" → it's an invoices project), give the project a descriptive title:
+
+```bash
+uip ixp projects update-title <project-name> "Vendor Invoices" --output json
+```
+
+Skip this step if the user already provided a meaningful name in Step 1.
+
+## Step 4 — Label All Documents
+
+Follow the [Label Documents Guide](label-documents-guide.md) to label every document in the project.

package/skills/uipath-maestro-bpmn/.maintenance/README.md

@@ -0,0 +1,241 @@
+# Skill Maintenance
+
+Internal tooling and conventions for maintaining the `uipath-maestro-bpmn` skill structure. Not loaded by agents during normal use.
+
+## Structure
+
+The skill is organized into three peer capabilities:
+
+```text
+SKILL.md                                ← capability router (universal rules + 3-bucket intent)
+references/
+├── shared/                             ← cross-capability primitives
+│   ├── bpmn-xml-contract.md            ← model-owned vs CLI-owned XML
+│   ├── cli-conventions.md              ← JSON output, login, side effects
+│   ├── project-layout.md               ← BPMN source + generated package files
+│   ├── public-safety.md                ← sanitized/public-safe content rules
+│   └── variables-bindings-expressions.md
+├── author/
+│   ├── CAPABILITY.md                   ← capability index
+│   └── references/                     ← author's supporting docs
+│       ├── greenfield.md               ← create-new-BPMN-project journey
+│       ├── brownfield.md               ← edit-existing-BPMN-project journey
+│       ├── validation.md               ← local validation checklist
+│       └── plugins/                    ← per-node-type planning + impl
+├── operate/
+│   ├── CAPABILITY.md                   ← capability index
+│   └── references/                     ← operate's supporting docs
+│       ├── ship.md                     ← package/upload/publish/deploy
+│       ├── run.md                      ← debug/run + status/traces
+│       └── manage.md                   ← instance lifecycle
+└── diagnose/
+    ├── CAPABILITY.md                   ← capability index
+    └── references/                     ← diagnose's supporting docs
+        ├── troubleshooting-guide.md    ← diagnostic priority ladder
+        └── failure-modes.md            ← pattern catalog
+```
+
+**Recursive pattern.** Skill = `SKILL.md` + `references/`. Capability = `CAPABILITY.md` + `references/`. The same "index next to its references" shape at two scales. Future capabilities (e.g., `governance/`) get the template for free.
+
+**Convention:** each capability is a self-contained folder. Every file under `<capability>/references/` is implicitly that-capability-scoped — path = provenance. The `CAPABILITY.md` index is always at `<capability>/CAPABILITY.md` (uniform shape across all three).
+
+### Capability boundary
+
+- **Author** = on disk, locally, usually **without login** (BPMN edits, local validation, enrichment planning)
+- **Operate** = touches the cloud, usually **requires login** (package/upload/publish/debug/run/instance lifecycle)
+- **Diagnose** = postmortem on a failed run, usually **requires login** (incidents, variables, deployed asset, element executions, traces)
+
+Author terminates at validation and hands off to Operate. Operate hands off to Diagnose when a run faults. Diagnose hands off back to Author for the underlying fix.
+
+### Capability-index template
+
+`AUTHOR.md`, `OPERATE.md`, `DIAGNOSE.md` all follow the same 6-section structure:
+
+1. `# <Capability> — <one-line purpose>`
+2. `## When to use this capability`
+3. `## Critical rules`
+4. `## Workflow`
+5. `## Common tasks`
+6. `## Anti-patterns`
+7. `## References`
+
+## Markdown anchor slugs (`[link](file.md#section-name)`)
+
+Anchor links are computed exactly as GitHub does — getting them wrong silently produces a dead link that markdown lint won't catch.
+
+### Slug rule
+
+1. Lowercase the heading
+2. Strip these characters entirely: `` ` ``, `*`, `_`, and any non-alphanumeric/non-space/non-dash character
+3. Replace each remaining space with `-`
+4. **Separator characters do not collapse** — each space (or em-dash that became a space-pair) becomes its own dash
+
+### Common gotchas
+
+| Heading | Wrong slug | Correct slug | Why |
+| --- | --- | --- | --- |
+| `## 5. \`--folder-key\` requirement` | `#5--folder-key-requirement` | `#5---folder-key-requirement` | After `.` strips and backticks strip: `5 --folder-key requirement`. The space between `5` and `--` becomes a dash, joining the two literal dashes from `--folder-key` → 3 dashes |
+| `## Reused reference ID — cross-connection ID leakage` | `#reused-reference-id-cross-connection-id-leakage` | `#reused-reference-id--cross-connection-id-leakage` | The em-dash (`—`) is stripped (non-alphanumeric/space/dash), but the spaces on either side of it survive and both become dashes → 2 dashes |
+| `## MST-9107 — \`=js:\` prefix missing` | `#mst-9107-js-prefix-missing` | `#mst-9107--js-prefix-missing` | Backticks strip from around `=js:`, then the em-dash, `=`, and `:` strip (non-alphanumeric/space/dash). The space before and after the em-dash both survive → 2 consecutive dashes between `9107` and `js` |
+
+### Verifying anchor links
+
+Run the anchor-checker script before committing changes that add or edit anchor links:
+
+```bash
+bash .maintenance/check-anchors.sh
+```
+
+Returns `anchors_checked=N anchors_bad=0` on success. Any non-zero `anchors_bad` lists which file → which target slug failed to resolve.
+
+## Verifying file-path links
+
+Run the link-checker script to catch broken `[text](path)` links:
+
+```bash
+bash .maintenance/check-links.sh
+```
+
+Returns `checked=N broken=M`. Both checkers skip links inside fenced code blocks and inline code spans, so example links in this README and in REFACTOR-PROPOSAL.md don't trigger false positives.
+
+## Verifying link text agrees with link URL
+
+Run the link-text checker to catch links whose **text looks like a file** but whose **URL points elsewhere**:
+
+```bash
+bash .maintenance/check-link-text.sh
+```
+
+Returns `checked=N broken=M`. Exits non-zero on any mismatch. Three failure modes, all hard failures:
+
+- **basename-mismatch** — text basename ≠ URL basename (e.g., text `AUTHOR.md`, URL `../CAPABILITY.md`).
+- **prefix-mismatch** — basenames agree but the directory hint in the text contradicts the URL's directory (e.g., text `operate/manage.md`, URL `references/manage.md`). Tolerated when the text directory is a suffix of the URL directory (e.g., text `author/greenfield.md`, URL `references/author/greenfield.md`).
+- **folder-url-but-text-is-file** — URL ends with `/` but text claims a file.
+
+Only links whose text contains a file-like token (extension `.md`, `.sh`, `.json`, `.js`, `.ts`, `.py`, `.cs`, `.xaml`, `.flow`, `.yaml`, `.yml`) are evaluated; descriptive text like `[Edit/Write: Variable Operations](...)` is skipped. Same skip rules as `check-links.sh` (fenced code, inline code, http(s), slash commands, anchor-only).
+
+## Verifying reachability depth
+
+Run the depth-checker script to verify every file under `references/` is reachable from `SKILL.md` within the configured max hops (default 2):
+
+```bash
+bash .maintenance/check-depth.sh
+```
+
+Pass a custom max-hops value as the first argument:
+
+```bash
+bash .maintenance/check-depth.sh 3
+```
+
+Returns `total_files=N reachable_within=R unreachable=U exceeds_depth=E`. Folder links count as reachability for every file in the folder (per the agent-navigation convention below). Exits non-zero if any file is unreachable or exceeds the configured depth.
+
+## Verifying capability-index template conformance
+
+Run the template-checker script to verify each `CAPABILITY.md` follows the canonical 6-section structure (When to use / Critical rules / Workflow / Common tasks / Anti-patterns / References):
+
+```bash
+bash .maintenance/check-template.sh
+```
+
+Returns `capabilities_checked=N missing_sections=M`. Exits non-zero if any `CAPABILITY.md` is missing a required section. Catches drift if a future edit removes or renames a canonical section.
+
+## Verifying no orphaned files
+
+Run the orphan-checker script to find `.md` files under `references/` that no other `.md` file links to:
+
+```bash
+bash .maintenance/check-orphans.sh
+```
+
+Returns `files_checked=N orphans=M`. Exits non-zero if any orphans are found. `CAPABILITY.md` files are excluded (they are entry points linked from SKILL.md and peer indexes; SKILL.md itself is excluded as the root entry point).
+
+Orphans typically appear after a refactor that removed inbound links but didn't delete the now-unreferenced file. Folder links count as inbound for every `.md` inside the folder, matching the agent-navigation convention used by `check-depth.sh`.
+
+## Verifying plugin folder pairs
+
+Run the plugin-pairs checker to verify every plugin folder has both `planning.md` and `impl.md` (the per-plugin convention):
+
+```bash
+bash .maintenance/check-plugin-pairs.sh
+```
+
+Returns `plugins_checked=N missing_files=M`. Exits non-zero if any plugin folder is missing a required file. Catches half-deleted plugins or new plugin folders that haven't been completed.
+
+## Verifying BPMN validation fixtures
+
+Run the validation-fixtures checker to verify the public-safe synthetic BPMN corpus and generated package metadata:
+
+```bash
+bash .maintenance/check-validation-fixtures.sh
+```
+
+Returns `validation_fixture_projects=N bpmn_files=N errors=0` on success. The checker validates standard BPMN parseability, UiPath moddle/extension elements, resource binding references, Integration Service enrichment fields, generated `bindings_v2.json`, `entry-points.json`, `operate.json`, and `package-descriptor.json`, plus public-safety guardrails for fixture content.
+
+## Verifying `uip` command references
+
+Run the uip-command checker to verify every `uip ...` invocation resolves to a real command in the installed CLI:
+
+```bash
+bash .maintenance/check-uip-commands.sh
+```
+
+Returns `commands_checked=N unknown=M`. Exits non-zero if any referenced command path is unknown to `uip`. Verification is **help-only** — the checker walks each command path with `uip <prefix> --help`, confirms the requested segment appears in the parent's `Subcommands` list, and never executes the command for real. Help responses are cached per prefix.
+
+The checker:
+
+- Scans `SKILL.md` and `references/**/*.md`. Skips `.maintenance/` and root-level scratch files (`PLAN.md`, `PR_BODY.md`).
+- Scans both **fenced code blocks** tagged `bash`, `sh`, `shell`, `zsh`, `console`, or unlabelled, **and inline backtick spans** like `` `uip maestro flow init` ``. Inline scanning catches doc-narrative drift that fenced-only scanning misses.
+- Stops the path at the first flag, placeholder (`<...>`), shell metachar, comment (`#`), path-literal, or non-kebab-case token — so positional args like `uip maestro flow registry search outlook` don't get mistreated as subcommands.
+- Treats trailing tokens after a leaf-with-positional-args (e.g. `uip maestro flow registry search <keyword>`) as arguments, not missing subcommands.
+- Falls back gracefully if `uip` is not installed: warns and exits 0. Pass `--strict` to fail in CI.
+
+Pass specific files to scan only those (e.g. for pre-commit on staged files):
+
+```bash
+bash .maintenance/check-uip-commands.sh references/shared/cli-commands.md
+```
+
+### Skipping intentional historical references
+
+Some docs reference removed commands on purpose — for example, a CLI version-comparison table that documents a pre-restructure prefix. Add `<!-- uip-check-skip -->` anywhere on the line to suppress checking for that line:
+
+```markdown
+> Replace `uip maestro flow` with `uip flow` if version < 0.3.4. <!-- uip-check-skip -->
+```
+
+For table rows, place the marker **inside a cell** so it doesn't break table structure (HTML comments render as nothing):
+
+```markdown
+| **< 0.3.4** | `uip flow` | `uip flow init MyProject` <!-- uip-check-skip --> |
+```
+
+## Running the full suite
+
+Run all nine checkers in one invocation:
+
+```bash
+bash .maintenance/check-all.sh
+```
+
+Continues running all checkers even when one fails — the goal is to surface every issue in a single pass. Exits non-zero if any checker fails.
+
+## When to run these checkers
+
+- Before committing changes that move files or rewrite link paths — `check-all.sh` covers everything in one pass
+- Before merging a PR that touches `references/`
+- After a refactoring phase
+- After deleting a doc — run `check-orphans.sh` to confirm nothing else became orphaned
+- Before adding a new capability — run `check-template.sh` against the new `CAPABILITY.md`
+- After adding a new plugin — run `check-plugin-pairs.sh` to confirm both `planning.md` and `impl.md` are present
+- After a `uip` CLI version bump — run `check-uip-commands.sh` to catch any commands that were renamed or removed
+
+The checkers are not currently wired into CI or pre-commit hooks. They are kept as lightweight tooling in this directory so future maintainers can run them on demand.
+
+## Reachability convention
+
+Plugin docs (`references/author/references/plugins/<name>/{planning,impl}.md`) are linked from `author/CAPABILITY.md` via **folder links** (e.g., `[integration-service](references/plugins/integration-service/)`), not individual file links. Agents navigating to the folder discover both `planning.md` and `impl.md` there. This satisfies practical 2-hop reachability from `SKILL.md`.
+
+The depth checker (`check-depth.sh`) treats folder links as reachability for every `.md` file inside the folder, matching this agent-navigation model. A strict file-link-only reachability check would flag plugin docs as "unreachable" — that's a false negative.
+
+If a future change requires explicit file links (e.g., a task table needs a specific `impl.md` anchor), add the file link inline rather than relying on folder discovery.

package/skills/uipath-maestro-bpmn/.maintenance/check-all.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Run the full audit suite for this skill.
+# Usage: bash .maintenance/check-all.sh
+#
+# Runs each checker in turn and prints its summary line.
+# Exits non-zero if any checker fails. Continues running all checkers
+# even when one fails — the goal is to surface every issue in a single pass.
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+CHECKERS=(
+  "check-links.sh"
+  "check-link-text.sh"
+  "check-anchors.sh"
+  "check-depth.sh"
+  "check-template.sh"
+  "check-orphans.sh"
+  "check-plugin-pairs.sh"
+  "check-validation-fixtures.sh"
+  "check-real-pack.sh"
+  "check-uip-commands.sh"
+)
+
+overall=0
+
+for checker in "${CHECKERS[@]}"; do
+  echo "=== $checker ==="
+  if ! /bin/bash ".maintenance/$checker"; then
+    overall=1
+  fi
+  echo ""
+done
+
+if [ "$overall" -eq 0 ]; then
+  echo "All checks passed."
+else
+  echo "One or more checks failed. See output above for details."
+fi
+
+exit "$overall"

package/skills/uipath-maestro-bpmn/.maintenance/check-anchors.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Verify every markdown anchor link (`[text](file.md#anchor)`) resolves to an actual heading in the target file.
+# Usage: bash .maintenance/check-anchors.sh
+# Output: BAD ANCHOR lines per failure, then "anchors_checked=N anchors_bad=M" summary.
+#
+# Skips:
+# - links inside fenced code blocks (```...```)
+# - links inside inline code spans (`...`)
+# - links without a `#anchor` fragment
+# - http(s):// links
+# - slash-command links
+# - same-file anchor-only links (#anchor without a path)
+# - links to files that don't exist (those are caught by check-links.sh, not this checker)
+#
+# Slug rule (matches GitHub heading-anchor generation):
+# 1. Lowercase the heading
+# 2. Strip backtick, asterisk, underscore, and any non-alphanumeric/non-space/non-dash character
+# 3. Replace each remaining space with `-`
+# 4. Separator characters do not collapse
+#
+# See .maintenance/README.md for common gotchas.
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+heading_anchors() {
+  /usr/bin/awk '
+    /^#{1,6} /{
+      sub(/^#+ /, "");
+      gsub(/[`*_]/, "");
+      anchor = tolower($0);
+      gsub(/[^a-z0-9 -]/, "", anchor);
+      gsub(/ /, "-", anchor);
+      print anchor;
+    }' "$1"
+}
+
+# Per-file: strip fenced code blocks and inline code spans, then extract links.
+extract_links() {
+  /usr/bin/awk '
+    /^```/ { fenced = !fenced; next }
+    !fenced {
+      gsub(/`[^`]*`/, "", $0)
+      while (match($0, /\]\([^)]+\)/)) {
+        link = substr($0, RSTART, RLENGTH)
+        sub(/^\]\(/, "", link)
+        sub(/\)$/, "", link)
+        print link
+        $0 = substr($0, RSTART + RLENGTH)
+      }
+    }
+  ' "$1"
+}
+
+broken=0
+checked=0
+
+while IFS= read -r srcfile; do
+  while IFS= read -r raw; do
+    case "$raw" in
+      \#*) continue ;;
+      http*|/uipath*) continue ;;
+    esac
+    [[ "$raw" != *#* ]] && continue
+    target_path="${raw%%#*}"
+    anchor="${raw#*#}"
+    [ -z "$target_path" ] && continue
+    srcdir=$(/usr/bin/dirname "$srcfile")
+    full="$srcdir/$target_path"
+    resolved=$(cd "$(/usr/bin/dirname "$full")" 2>/dev/null && /bin/pwd)/$(/usr/bin/basename "$full")
+    [ ! -f "$resolved" ] && continue
+    checked=$((checked+1))
+    if heading_anchors "$resolved" | /usr/bin/grep -qx "$anchor"; then
+      :
+    else
+      echo "BAD ANCHOR  $srcfile -> $raw"
+      broken=$((broken+1))
+    fi
+  done < <(extract_links "$srcfile")
+done < <(/usr/bin/find . -name "*.md" -type f)
+
+echo ""
+echo "anchors_checked=$checked anchors_bad=$broken"

package/skills/uipath-maestro-bpmn/.maintenance/check-depth.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# Verify every markdown file under references/ is reachable from SKILL.md within the configured max hops.
+# Usage: bash .maintenance/check-depth.sh [MAX_HOPS]
+# Default MAX_HOPS=2. Output per file: "DEPTH=N  path/to/file.md" + summary.
+#
+# Counts BFS hops via outbound links. Folder links count as reachability for every file in the folder
+# (per the convention documented in .maintenance/README.md — folder links satisfy practical reachability).
+#
+# Skips:
+# - Links inside fenced code blocks (```...```)
+# - Links inside inline code spans (`...`)
+# - http(s):// links
+# - Anchor-only links (#anchor)
+# - Slash-command links (/uipath:..., /uipath-feedback)
+#
+# Exits non-zero if any file exceeds MAX_HOPS or is unreachable.
+# Compatible with bash 3.2 (no associative arrays — uses tab-separated state files).
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+MAX_HOPS="${1:-2}"
+
+# State files: each line is "<depth>\t<absolute_path>"
+visited=$(/usr/bin/mktemp)
+frontier=$(/usr/bin/mktemp)
+next_frontier=$(/usr/bin/mktemp)
+trap 'rm -f "$visited" "$frontier" "$next_frontier"' EXIT
+
+# Per-file: strip fenced code blocks and inline code spans, then extract links.
+extract_links() {
+  /usr/bin/awk '
+    /^```/ { fenced = !fenced; next }
+    !fenced {
+      gsub(/`[^`]*`/, "", $0)
+      while (match($0, /\]\([^)]+\)/)) {
+        link = substr($0, RSTART, RLENGTH)
+        sub(/^\]\(/, "", link)
+        sub(/\)$/, "", link)
+        print link
+        $0 = substr($0, RSTART + RLENGTH)
+      }
+    }
+  ' "$1"
+}
+
+resolve_link() {
+  local from_file="$1"
+  local link="$2"
+  link="${link%%#*}"
+  [ -z "$link" ] && return 1
+  case "$link" in
+    http://*|https://*) return 1 ;;
+    /uipath:*|/uipath-feedback*) return 1 ;;
+  esac
+  local from_dir
+  from_dir=$(/usr/bin/dirname "$from_file")
+  local target="$from_dir/$link"
+  local resolved_dir
+  resolved_dir=$(cd "$(/usr/bin/dirname "$target")" 2>/dev/null && /bin/pwd)
+  [ -z "$resolved_dir" ] && return 1
+  echo "$resolved_dir/$(/usr/bin/basename "$target")"
+}
+
+is_visited() {
+  /usr/bin/grep -q "	$1$" "$visited"
+}
+
+mark_visited() {
+  printf "%s\t%s\n" "$1" "$2" >> "$visited"
+}
+
+depth_of() {
+  /usr/bin/awk -F'\t' -v p="$1" '$2 == p { print $1; exit }' "$visited"
+}
+
+# Seed with SKILL.md at depth 0
+mark_visited 0 "$ROOT/SKILL.md"
+echo "$ROOT/SKILL.md" > "$frontier"
+
+current_depth=0
+while [ -s "$frontier" ] && [ "$current_depth" -lt "$MAX_HOPS" ]; do
+  : > "$next_frontier"
+  while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    while IFS= read -r raw_link; do
+      target=$(resolve_link "$file" "$raw_link") || continue
+      [ -z "$target" ] && continue
+      if [ -d "$target" ]; then
+        while IFS= read -r f; do
+          [ -z "$f" ] && continue
+          if ! is_visited "$f"; then
+            mark_visited $((current_depth + 1)) "$f"
+            echo "$f" >> "$next_frontier"
+          fi
+        done < <(/usr/bin/find "$target" -name "*.md" -type f)
+      elif [ -f "$target" ]; then
+        if ! is_visited "$target"; then
+          mark_visited $((current_depth + 1)) "$target"
+          echo "$target" >> "$next_frontier"
+        fi
+      fi
+    done < <(extract_links "$file")
+  done < "$frontier"
+  /bin/cp "$next_frontier" "$frontier"
+  current_depth=$((current_depth + 1))
+done
+
+# Report — every .md under references/ should be visited within MAX_HOPS
+total=0
+unreachable=0
+exceeded=0
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  total=$((total + 1))
+  d=$(depth_of "$f")
+  if [ -z "$d" ]; then
+    echo "UNREACHABLE  ${f#$ROOT/}"
+    unreachable=$((unreachable + 1))
+  elif [ "$d" -gt "$MAX_HOPS" ]; then
+    echo "EXCEEDS_DEPTH ($d > $MAX_HOPS)  ${f#$ROOT/}"
+    exceeded=$((exceeded + 1))
+  fi
+done < <(/usr/bin/find "$ROOT/references" -name "*.md" -type f | /usr/bin/sort -u)
+
+echo ""
+echo "max_hops=$MAX_HOPS total_files=$total reachable_within=$((total - unreachable - exceeded)) unreachable=$unreachable exceeds_depth=$exceeded"
+
+if [ "$unreachable" -gt 0 ] || [ "$exceeded" -gt 0 ]; then
+  exit 1
+fi
+exit 0