docs: pull Agents docs directly

[rh-hemartin]

Summary

Pull fullsend-ai/agents at main when building the site. This way we don't duplicate docs and we get the current main as we also build from main our docs.

Related Issue

Closes #5710

Changes

• Remove current docs/agents
• Add it to .gitignore
• Pull fullsend-ai/agents@main and put it into docs/agents (just the docs/ folder there)
• Generate the sidebar automatically from the files on docs/agents
• Moved some stuff out of the docs/agents folder into other folders or into the fullsend-ai/agents repository.

Testing

• make lint passes (stage changes first, then run)
• Tests added/updated for new or modified logic

Checklist

• [ x PR title follows Conventional Commits (correct type, ! for breaking changes)
• Commits are signed off (DCO) — human and human-directed agent sessions only
• I wrote this contribution myself and can explain all changes in it

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:31 AM UTC · Completed 10:50 AM UTC
Commit: 05430d6 · View workflow run →

[github-actions]

Site preview

Preview: https://cc4e81b1-site.fullsend-ai.workers.dev

Commit: c015ab020d33631b8a3dce84c8f36fa8f5534f68

[qodo-code-review]

PR Summary by Qodo

Docs: fetch Agents docs during site build and auto-generate sidebar

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Stop vendoring docs/agents and fetch upstream Agents docs during website build.
• Auto-generate the Agents sidebar from fetched markdown files.
• Update internal links to point to the new Agents docs location.

Diagram

graph TD
  A["VitePress prebuild/predev"] --> B["fetch-agent-docs.sh"] --> C{{"GitHub: fullsend-ai/agents"}} --> D["docs/agents/"] --> E["VitePress config"] --> F["Sidebar: getMarkdownFiles"]
  subgraph Legend
    direction LR
    _job["Build step"] ~~~ _script["Script"] ~~~ _ext{{"External repo"}} ~~~ _dir["Docs dir"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Git submodule for `fullsend-ai/agents`

• ➕ Reproducible builds pinned to a commit
• ➕ No custom fetch logic needed once initialized
• ➖ Submodule UX overhead for contributors/CI
• ➖ Harder to pull only the docs/ subtree cleanly

2. Always fetch `main` at build time

• ➕ Docs always reflect current upstream content
• ➕ Matches the stated intent of tracking main
• ➖ Non-reproducible builds; upstream changes can break site without repo changes
• ➖ Harder to debug historic builds

3. Publish agent docs as a versioned artifact/package

• ➕ Deterministic upgrades with explicit versions
• ➕ No git/network operations needed in site build step
• ➖ Requires new release pipeline and maintenance
• ➖ More upfront work than a simple fetch script

Recommendation: The build-time fetch + ignored docs/agents/ directory is a pragmatic way to avoid duplicated docs while keeping the local site structure. One key decision to confirm is versioning: the new script defaults to the latest v* tag (overridable via FULLSEND_AGENTS_REF), which optimizes for reproducibility, not tracking main. If the real goal is 'always main', change the default ref to main; otherwise, update the PR description to match tag-based behavior.

Files changed (17) +74 / -45

Documentation (13) +33 / -33

architecture.mdPoint fix-agent link to hosted Agents docs +1/-1

Point fix-agent link to hosted Agents docs

• Replaces the relative 'agents/fix.md' link with a hosted 'https://fullsend.sh/docs/agents/fix' URL to avoid depending on vendored agent docs.

docs/architecture.md

agent.mdUpdate default-vs-custom link to guides location +1/-1

Update default-vs-custom link to guides location

• Re-points the 'Default, derived, and custom agents' reference from the old 'docs/agents/topics/...' path to 'docs/guides/user/default-vs-custom-agents.md'.

docs/cli/agent.md

glossary.mdUpdate glossary cross-references for agent terminology +4/-4

Update glossary cross-references for agent terminology

• Updates multiple glossary links to use the user-guide location for default/derived/custom agent terminology and links the Agents reference to the hosted docs URL.

docs/glossary.md

README.mdFix default-vs-custom link target in guides index +1/-1

Fix default-vs-custom link target in guides index

• Updates the guides index to link to 'user/default-vs-custom-agents.md' instead of the removed 'agents/topics/...' page.

docs/guides/README.md

configuring-github.mdAdjust Agents-related link to new docs location +1/-1

Adjust Agents-related link to new docs location

• Updates an Agents documentation reference to avoid relying on a local, vendored 'docs/agents' directory.

docs/guides/getting-started/configuring-github.md

org-mode.mdLink Agents section to hosted docs +1/-1

Link Agents section to hosted docs

• Changes the 'Agents' next-step link from a local 'docs/agents/...' path to 'https://fullsend.sh/docs/agents/'.

docs/guides/getting-started/org-mode.md

bring-your-own-agent.mdUpdate default-vs-custom cross-reference +1/-1

Update default-vs-custom cross-reference

• Updates the default-vs-custom reference to point at the user guide instead of the removed agents topic doc.

docs/guides/user/bring-your-own-agent.md

bugfix-workflow.mdReplace fix-agent relative links with hosted URLs +5/-5

Replace fix-agent relative links with hosted URLs

• Replaces several references to the fix agent markdown with hosted 'https://fullsend.sh/docs/agents/fix' URLs.

docs/guides/user/bugfix-workflow.md

building-custom-agents.mdUpdate default-vs-custom cross-reference +1/-1

Update default-vs-custom cross-reference

• Re-points the default-vs-custom reference to the user guide page.

docs/guides/user/building-custom-agents.md

customizing-agents.mdUpdate default-vs-custom cross-reference +1/-1

Update default-vs-custom cross-reference

• Updates the 'See Also' link to default-vs-custom to point at the user guide page.

docs/guides/user/customizing-agents.md

customizing-with-agents-md.mdUpdate default-vs-custom cross-reference +1/-1

Update default-vs-custom cross-reference

• Updates the default-vs-custom reference to the user guide page location.

docs/guides/user/customizing-with-agents-md.md

customizing-with-skills.mdPoint agent docs links to hosted Agents pages +8/-8

Point agent docs links to hosted Agents pages

• Replaces relative links to agent reference pages with hosted 'https://fullsend.sh/docs/agents/...' URLs, and updates the default-vs-custom cross-link to the user guide page.

docs/guides/user/customizing-with-skills.md

default-vs-custom-agents.mdLink agent references to hosted docs and normalize guide links +7/-7

Link agent references to hosted docs and normalize guide links

• Updates references to 'docs/agents/<agent>.md' to use hosted Agents docs and adjusts several intra-guide links to be relative within the user guides section.

docs/guides/user/default-vs-custom-agents.md

Other (4) +41 / -12

.gitignoreIgnore generated 'docs/agents/' directory +1/-0

Ignore generated 'docs/agents/' directory

• Adds 'docs/agents/' to '.gitignore' so fetched agent docs are not committed and can be regenerated during site builds.

.gitignore

config.tsGenerate Agents sidebar from markdown files +3/-10

Generate Agents sidebar from markdown files

• Renames the sidebar group to 'Default Agents' and replaces the hardcoded agent list with 'getMarkdownFiles("agents/", "agents/")' so navigation tracks fetched content. Adds a 'Default vs. Custom Agents' link under User Guides.

website/.vitepress/config.ts

package.jsonFetch agent docs in predev/prebuild lifecycle hooks +2/-2

Fetch agent docs in predev/prebuild lifecycle hooks

• Replaces submodule update hooks with calls to './scripts/fetch-agent-docs.sh'; 'prebuild' forces a refresh to ensure the build uses the intended content.

website/package.json

fetch-agent-docs.shAdd script to populate 'docs/agents/' from upstream repo +35/-0

Add script to populate 'docs/agents/' from upstream repo

• Adds a bash script that clones 'fullsend-ai/agents' (defaulting to latest 'v*' tag, overrideable via 'FULLSEND_AGENTS_REF') and copies its 'docs/' directory into 'docs/agents/'. Supports skipping when already populated and '--force' to re-fetch.

website/scripts/fetch-agent-docs.sh

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

1. Malformed agents sidebar links ✓ Resolved 🐞 Bug ≡ Correctness

Description

The sidebar now calls getMarkdownFiles("agents/", "agents/"), but getMarkdownFiles builds links
as /${base}/${slug} and /${base}/${entry}/. With a trailing slash in base, generated sidebar
links become /agents//<slug> (and /agents//<dir>/), which can break or behave inconsistently
depending on URL normalization.

Code

website/.vitepress/config.ts[R207-210]

+          text: "Default Agents",
          collapsed: true,
          link: "/agents/",
-          items: [
-            { text: "Triage", link: "/agents/triage" },
-            { text: "Code", link: "/agents/code" },
-            { text: "Review", link: "/agents/review" },
-            { text: "Fix", link: "/agents/fix" },
-            { text: "Retro", link: "/agents/retro" },
-            { text: "Prioritize", link: "/agents/prioritize" },
-            { text: "Default vs. Custom", link: "/agents/topics/default-vs-custom" },
-          ],
+          items: getMarkdownFiles("agents/", "agents/"),

Relevance

●●● Strong

Likely real link bug from trailing-slash base; small, localized fix in sidebar generation.

PR-#4020

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The sidebar change passes a trailing-slash base, and the helper concatenates it with additional
slashes when constructing links; other call sites pass base without a trailing slash, indicating the
expected format.

website/.vitepress/config.ts[206-211]
website/.vitepress/config.ts[16-41]
website/.vitepress/config.ts[302-306]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The sidebar passes a `base` argument with a trailing slash (`"agents/"`) into `getMarkdownFiles`, which already inserts slashes when constructing links. This produces double-slash URLs like `/agents//triage`.

## Issue Context
`getMarkdownFiles()` expects `base` to be a path segment without leading/trailing slashes (as shown by other calls like `getMarkdownFiles("experiments", "experiments")`).

## Fix Focus Areas
- website/.vitepress/config.ts[206-211]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Agents docs refresh non-atomic ✓ Resolved 🐞 Bug ☼ Reliability

Description

fetch-agent-docs.sh deletes docs/agents before copying the newly fetched docs into place. If the
copy fails after deletion, the workspace is left without any agent docs until the next successful
fetch, breaking dev/build runs that expect /docs/agents content.

Code

website/scripts/fetch-agent-docs.sh[R32-33]

+rm -rf "$DEST"
+cp -a "$TMPDIR/docs" "$DEST"

Relevance

●●● Strong

Non-atomic delete-then-copy risk is clear; easy to fix with temp+mv pattern.

PR-#2765

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The script performs rm -rf "$DEST" immediately followed by cp -a ... "$DEST", so any failure
between these steps leaves docs/agents missing or incomplete.

website/scripts/fetch-agent-docs.sh[26-35]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The script removes the destination directory before ensuring the new docs have been successfully copied, which can leave the repo in a broken state on partial failures.

## Issue Context
Use a temp destination (e.g., `$DEST.tmp`) and `mv` into place only after copy succeeds.

## Fix Focus Areas
- website/scripts/fetch-agent-docs.sh[26-34]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Fragile tag ref parsing ⊘ Outdated 🐞 Bug ☼ Reliability

Description

The fetch script derives REF by taking the first line of raw git ls-remote --tags output and
stripping the prefix, then passes it to git clone --branch "$REF". This parsing does not filter
out non-checkout tag refs (e.g., peeled refs for annotated tags), which can make REF invalid and
cause the fetch to fail depending on the remote’s tag layout/order.

Code

website/scripts/fetch-agent-docs.sh[R14-16]

+if [[ -z "$REF" ]]; then
+  REF=$(git ls-remote --tags --sort=-v:refname "https://github.com/${REPO}.git" 'v*' \
+    | head -1 | sed 's|.*refs/tags/||')

Relevance

●● Moderate

More robust tag selection is reasonable but subtle; unclear if repo relies on annotated tags/tag
sorting.

PR-#2765

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The script’s REF assignment is based on unfiltered tag refs and is directly fed into `git clone
--branch`, so any non-branch/tag-name ref value produced by the pipeline will break cloning.

website/scripts/fetch-agent-docs.sh[14-17]
website/scripts/fetch-agent-docs.sh[29-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`REF` is computed from `git ls-remote --tags` output without filtering out peeled/auxiliary tag refs, and is then used as the `--branch` argument to `git clone`.

## Issue Context
Harden selection by extracting only `refs/tags/<tag>` (excluding `^{} `) before sorting/selecting, then stripping `refs/tags/`.

## Fix Focus Areas
- website/scripts/fetch-agent-docs.sh[14-17]
- website/scripts/fetch-agent-docs.sh[29-31]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (1)

4. Submodules no longer auto-fetched ✓ Resolved 🐞 Bug ☼ Reliability

Description

website/package.json replaced the predev/prebuild hooks from git submodule update --init to
only fetching agent docs. On fresh local clones this leaves declared submodules (e.g. experiments)
uninitialized, resulting in missing docs content and making docs/doc-site.md's “no manual git
submodule step needed” guidance incorrect.

Code

website/package.json[R7-8]

+    "predev": "./scripts/fetch-agent-docs.sh",
+    "prebuild": "./scripts/fetch-agent-docs.sh --force",

Relevance

●● Moderate

Workflow/expected-dev-setup change; no close historical precedent on keeping submodule init vs fetch
script.

PR-#2853

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The scripts no longer run submodule init, despite the repo still declaring an experiments
submodule and the docs site config still generating an Experiments sidebar section; the doc-site
guide still claims predev/prebuild initialize submodules.

website/package.json[6-11]
.gitmodules[1-8]
website/.vitepress/config.ts[302-306]
docs/doc-site.md[13-23]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The docs site lifecycle hooks no longer initialize git submodules, which can leave sections that depend on submodule-backed content empty for local dev/build.

## Issue Context
The repo still has submodules declared, and the VitePress config expects content under those paths.

## Fix Focus Areas
- website/package.json[6-11]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. getting-started guide mislocated 📜 Skill insight ⌂ Architecture

Description

The modified guide files are under docs/guides/getting-started/ instead of docs/guides/admin/ or
docs/guides/user/, violating the required guides directory structure. This can also mask the
intended audience classification enforced by the guides layout.

Code

docs/guides/getting-started/configuring-github.md[126]

+* Read the [Agents](https://fullsend.sh/docs/agents/) section to learn about the default agents Fullsend

Relevance

● Weak

Prior similar guide-location rule was explicitly rejected; team keeps non-admin/user guide subtrees.

PR-#5454

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062077 requires guides under docs/guides/ to be placed in admin/ or user/.
The diff shows modifications to guide files that remain under docs/guides/getting-started/,
demonstrating the non-compliant placement.

docs/guides/getting-started/configuring-github.md[126-126]
docs/guides/getting-started/org-mode.md[207-207]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Docs guides must live under `docs/guides/admin/` or `docs/guides/user/`. This PR modifies guides located in `docs/guides/getting-started/`, which violates the required guide placement.

## Issue Context
Rule requires each guide under `docs/guides/` to be placed in either `admin/` or `user/`.

## Fix Focus Areas
- docs/guides/getting-started/configuring-github.md[126-126]
- docs/guides/getting-started/org-mode.md[207-207]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[fullsend-ai-review]

Review

Findings

Low

• [scope-creep] docs/guides/user/how-to-upgrade-renovate.md — This PR adds a new file that is unrelated to issue Include fullsend-ai/agents docs in the documentation site #5710. It contains only a title and an incomplete first sentence ending with "the Fullsend". It appears to be accidentally included.
  Remediation: Remove from this PR and submit separately when the content is complete.

• [supply-chain] website/scripts/fetch-agent-docs.sh:13 — FULLSEND_AGENTS_REF defaults to main, a mutable ref. Unlike the previous approach where agent docs were committed directly in this repository (changes visible in PR diffs), the fetched documentation content can now change without any auditable change in this repository. Risk is limited by same-org ownership and content being documentation only.
  Remediation: Pin FULLSEND_AGENTS_REF to a specific commit SHA in the CI workflow, or document the explicit decision to track main.

• [implementation-divergence] website/scripts/fetch-agent-docs.sh — Issue Include fullsend-ai/agents docs in the documentation site #5710 prescribes a git submodule approach. The PR implements a clone-at-build-time script instead. The PR body gives implicit reasoning but does not explicitly justify the alternative approach.
  Remediation: Add a note to the PR description or issue explaining why a build-time fetch was chosen over submodules.

• [error-handling] website/scripts/fetch-agent-docs.sh:26 — The rm -rf "$DEST" / mv "$STAGING" "$DEST" sequence is not atomic: if mv fails after rm, docs/agents/ is deleted with no replacement. The consequence is a failed build that can be re-run, not silent breakage, but the previous content is unrecoverable without re-running.

• [path-traversal] website/scripts/fetch-agent-docs.sh:24 — cp -a preserves symlinks. A compromised source repo could include symlinks pointing outside the destination directory. Risk is limited by same-org ownership.
  Remediation: Use cp -rL instead of cp -a to dereference symlinks.

• [edge-case] website/.vitepress/config.ts:210 — getMarkdownFiles("agents", "agents") reads docs/agents/ dynamically at build time from an external repo whose structure is not controlled by this PR. If the external repo introduces subdirectories with README.md files covered by srcExclude, sidebar links would 404. Currently not a problem but represents fragile coupling.

Previous run

Review

Findings

Medium

• [logic-error] website/.vitepress/config.ts:344 — The editLink.pattern is set to https://github.com/fullsend-ai/fullsend/edit/main/docs/:path. After this PR, agent doc pages (e.g., /agents/triage) are sourced from fullsend-ai/agents, not from fullsend-ai/fullsend. The generated "Edit this page on GitHub" link on every agent doc page will point to https://github.com/fullsend-ai/fullsend/edit/main/docs/agents/triage.md — a path that no longer exists in this repo (docs/agents/ is gitignored). Users clicking the edit link will get a GitHub 404.
  Remediation: Use VitePress's editLink.pattern function form to conditionally route agent doc pages to https://github.com/fullsend-ai/agents/edit/main/docs/:path while keeping the existing pattern for all other pages, or suppress the edit link for agent pages entirely.

Low

• [scope-creep] docs/guides/user/how-to-upgrade-renovate.md — This PR adds a new file that is unrelated to issue Include fullsend-ai/agents docs in the documentation site #5710. It contains only a title and an incomplete first sentence ending with "the Fullsend". It appears to be accidentally included.
  Remediation: Remove from this PR and submit separately when the content is complete.

• [implementation-divergence] website/scripts/fetch-agent-docs.sh — Issue Include fullsend-ai/agents docs in the documentation site #5710 prescribes a git submodule approach ("Add fullsend-ai/agents as a git submodule"), matching the established experiments pattern. The PR implements a clone-at-build-time script instead. This may be a reasonable alternative (avoids submodule pin drift, always pulls latest main), but the divergence from the authorized approach should be explicitly justified in the PR or issue.

• [error-handling] website/scripts/fetch-agent-docs.sh:26 — After rm -rf "$DEST", if mv "$STAGING" "$DEST" fails, docs/agents/ is deleted with no replacement content. getMarkdownFiles returns [] silently, producing a site build with an empty agent documentation sidebar section. While set -euo pipefail will abort the script on failure, the previous content is already lost by that point.

• [supply-chain] website/scripts/fetch-agent-docs.sh:13 — The script clones from a mutable ref (defaults to main via FULLSEND_AGENTS_REF). Unlike the submodule approach which pins to immutable commit SHAs, fetched content can change without an auditable change in this repository. Risk is limited by same-org ownership and content being documentation only.

• [incomplete-authorization] .github/workflows/site-build.yml — Issue Include fullsend-ai/agents docs in the documentation site #5710 step 2 requires registering a trigger in .github/workflows/site-build.yml so agent doc changes auto-trigger site rebuilds. The PR acknowledges this gap in docs/doc-site.md ("Agent doc updates in fullsend-ai/agents do not auto-trigger site rebuilds") but does not create a follow-up issue to track it.

• [intent-alignment] docs/glossary.md — Several cross-references to agent docs now use absolute URLs (https://fullsend.sh/docs/agents/...) instead of relative paths. These resolve only on the deployed site, not when reading markdown locally or on GitHub. Since docs/agents/ is populated at build time, relative paths like agents/triage.md would work during both local dev and production builds.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

Previous run (2)

Review

Findings

Medium

• [logic-error] website/.vitepress/config.ts:337 — The editLink.pattern is set to https://github.com/fullsend-ai/fullsend/edit/main/docs/:path. After this PR, agent doc pages (e.g., /agents/triage) are sourced from fullsend-ai/agents, not from fullsend-ai/fullsend. The generated "Edit this page on GitHub" link on every agent doc page will point to https://github.com/fullsend-ai/fullsend/edit/main/docs/agents/triage.md — a path that no longer exists in this repo (docs/agents/ is gitignored). Users clicking the edit link will get a GitHub 404.
  Remediation: VitePress supports a function form for editLink.pattern. Use a function that checks whether the path starts with agents/ and routes to https://github.com/fullsend-ai/agents/edit/main/docs/ for agent pages, or suppress the edit link for agent pages entirely.

• [implementation-divergence] website/scripts/fetch-agent-docs.sh — Issue Include fullsend-ai/agents docs in the documentation site #5710 prescribes a git submodule approach ("Add fullsend-ai/agents as a git submodule"), matching the established experiments pattern already in use. The PR implements a clone-at-build-time script instead without explaining the divergence. The author may have valid reasons (e.g., avoiding submodule pin drift, always pulling latest main), but the divergence from the authorized approach should be explicitly justified.
  Remediation: Either switch to the submodule approach or add a comment on issue Include fullsend-ai/agents docs in the documentation site #5710 explaining why the clone script is preferable.

Low

• [incomplete-authorization] website/scripts/fetch-agent-docs.sh — Issue Include fullsend-ai/agents docs in the documentation site #5710 step 2 requires registering a trigger in .github/workflows/site-build.yml so agent doc changes auto-trigger site rebuilds. The PR acknowledges this gap in docs/doc-site.md ("Agent doc updates in fullsend-ai/agents do not auto-trigger site rebuilds") but does not create a follow-up issue to track it.

• [supply-chain] website/scripts/fetch-agent-docs.sh:13 — The script clones from a mutable ref (defaults to main via FULLSEND_AGENTS_REF). Unlike the submodule approach which pins to immutable commit SHAs, fetched content can change without an auditable change in this repository. Risk is limited by same-org ownership and content being documentation only.

• [error-handling] website/scripts/fetch-agent-docs.sh:24 — After rm -rf "$DEST", if mv "$STAGING" "$DEST" fails, docs/agents/ is deleted with no replacement content. getMarkdownFiles returns [] silently, producing a site build with no agent documentation section and no build error.

• [intent-alignment] docs/glossary.md — Several cross-references to agent docs now use absolute URLs (https://fullsend.sh/docs/agents/...) instead of relative paths. These resolve only on the deployed site, not when reading markdown locally or on GitHub. Since docs/agents/ is populated at build time, relative paths like agents/triage.md would work during both local dev and production builds.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

Previous run (3)

Review

Findings

High

• [stale-doc] docs/doc-site.md:22 — States the prebuild hook runs git submodule update --init, but this PR changes it to ./scripts/fetch-agent-docs.sh --force. The predev hook description (line 13) is similarly outdated. This file is not updated in the PR, so anyone reading it to understand the build process will get incorrect information.
  Remediation: Update docs/doc-site.md lines 13 and 22 to describe the new fetch-agent-docs.sh script and the experiments submodule init.

Medium

• [logic-error] website/.vitepress/config.ts:210 — getMarkdownFiles("agents/", "agents/") passes base with a trailing slash. The function constructs links as `/${base}/${slug}`, producing double-slash URLs like /agents//triage instead of /agents/triage. Every other call site in this file passes base without a trailing slash (e.g., "contributing", "ADRs").
  Remediation: Change to getMarkdownFiles("agents", "agents").

• [edge-case] website/scripts/fetch-agent-docs.sh:18 — If fullsend-ai/agents uses annotated tags, git ls-remote --tags returns both refs/tags/vX.Y.Z and refs/tags/vX.Y.Z^{} (the dereferenced object). The head -1 may select the ^{} entry, producing a REF like v1.0.0^{} that git clone --branch rejects. The 2>/dev/null on clone suppresses the diagnostic.
  Remediation: Add | grep -v '\^{}' before head -1 in the git ls-remote pipeline.

• [regression] website/package.json:7 — The old predev/prebuild hooks ran git -C .. submodule update --init, initializing all submodules including experiments (used by getMarkdownFiles("experiments", "experiments") in the VitePress config). The replacement only calls fetch-agent-docs.sh, so local npm run dev no longer initializes the experiments submodule.
  Remediation: Chain both commands: "predev": "git -C .. submodule update --init && ./scripts/fetch-agent-docs.sh".

• [scope-exceeded] website/scripts/fetch-agent-docs.sh — Issue Include fullsend-ai/agents docs in the documentation site #5710 prescribes a git submodule approach matching the established experiments pattern. The PR introduces a clone-at-tag script instead without explaining the divergence. If there is a good reason to prefer this approach, capture it in the PR or issue.
  Remediation: Either implement the submodule approach or comment on Include fullsend-ai/agents docs in the documentation site #5710 explaining why the script approach is preferable.

• [scope-exceeded] website/scripts/fetch-agent-docs.sh:18 — The PR description says "Pull fullsend-ai/agents at main" and "we get the current main", but the code fetches the latest v* tag via git ls-remote --tags. These are semantically different — the latest tag could lag behind main significantly.
  Remediation: Align the code with the stated intent (fetch main) or update the PR description to accurately describe the tag-based approach.

• [stale-doc] docs/architecture.md:120 — States "Each agent documents its config vars in docs/agents/<agent>.md" but those files are now gitignored and fetched at build time. The PR updates another reference in this file (line 389) but missed this one.
  Remediation: Update to reference the fullsend-ai/agents repo or the website URL.

Low

• [naming-convention] website/scripts/fetch-agent-docs.sh:28 — TMPDIR shadows the POSIX standard environment variable. Other scripts in this repo use WORKDIR for temporary working directories.

• [architectural-coherence] .github/workflows/site-build.yml — Agent doc changes in fullsend-ai/agents will not auto-trigger site rebuilds since docs are now fetched at build time rather than committed. Any rebuild (triggered by other docs changes) will fetch the latest agent docs, but a standalone agents-repo release won't trigger a site rebuild.

• [intent-alignment] docs/glossary.md:70 — Cross-references to agent docs now use absolute URLs (https://fullsend.sh/docs/agents/) instead of relative paths. These only resolve on the deployed site, not when reading markdown locally or on GitHub.

• [supply-chain] website/scripts/fetch-agent-docs.sh:15 — Git tags are mutable (can be force-pushed). The previous submodule approach pinned to immutable commit SHAs. Both repos are in the same org, limiting practical risk.

• [error-handling-idiom] website/scripts/fetch-agent-docs.sh:31 — git clone suppresses stderr with 2>/dev/null, hiding diagnostic information when clones fail (network errors, auth issues, missing tags).

• [stale-doc] docs/superpowers/specs/2026-06-11-triage-prerequisites-design.md:141 — Implementation plan references docs/agents/triage.md (now removed). Point-in-time design spec.

• [stale-doc] docs/superpowers/specs/2026-06-11-review-agent-contextual-labels-design.md:147 — References docs/agents/review.md (now removed) and contains a broken relative link at line 169.

• [stale-doc] docs/ADRs/0049-agent-configuration-env-var-convention.md:75 — Backtick-quoted path references to docs/agents/<agent>.md in an accepted ADR.

• [stale-doc] docs/ADRs/0080-config-yaml-vs-agent-env-var-scope.md:109 — Path references to docs/agents/<agent>.md in an accepted ADR.

---

Labels: PR modifies documentation infrastructure and content sourcing

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:54 AM UTC · Completed 12:14 PM UTC
Commit: 070bcb9 · View workflow run →

[waynesun09]

Review sweep findings below (4 new issues; 2 additional candidate findings were already substantively covered by earlier automated review comments on this PR and are omitted here — the issue #5710 submodule/rebuild-trigger divergence, and the absolute-vs-relative agent-doc link inconsistency).

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:56 AM UTC · Completed 7:12 AM UTC
Commit: 796bcaf · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:34 AM UTC · Completed 10:54 AM UTC

Commit: c015ab0 · View workflow run →

Superseded by updated review

[fullsend-ai-review]

[low] supply-chain

FULLSEND_AGENTS_REF defaults to main, a mutable ref. Unlike the previous approach where agent docs were committed directly in this repository, the fetched documentation content can now change without any auditable change in this repository. Risk is limited by same-org ownership and content being documentation only.

Suggested fix: Pin FULLSEND_AGENTS_REF to a specific commit SHA in the CI workflow, or document the explicit decision to track main.

[fullsend-ai-review]

[low] error-handling

The rm -rf / mv sequence is not atomic: if mv fails after rm, docs/agents/ is deleted with no replacement. The consequence is a failed build that can be re-run, not silent breakage, but the previous content is unrecoverable without re-running.

[fullsend-ai-review]

[low] path-traversal

cp -a preserves symlinks. A compromised source repo could include symlinks pointing outside the destination directory. Risk is limited by same-org ownership.

Suggested fix: Use cp -rL instead of cp -a to dereference symlinks.

[fullsend-ai-review]

[low] edge-case

getMarkdownFiles agents agents reads docs/agents/ dynamically at build time from an external repo whose structure is not controlled by this PR. If the external repo introduces subdirectories with README.md files covered by srcExclude, sidebar links would 404. Currently not a problem but represents fragile coupling.

[waynesun09]

Review sweep: 1 new finding skipped as an already-covered duplicate (the incomplete docs/guides/user/how-to-upgrade-renovate.md stub was already flagged by an earlier automated review comment on this PR). 2 new findings posted inline below.

[waynesun09]

[HIGH] Fetched agent docs link to harness/policies/scripts dirs that are never fetched — dead links on production site

This script only copies the docs/ subfolder of fullsend-ai/agents (cp -a "$WORKDIR/docs" "$STAGING"). Verified against the live fullsend-ai/agents repo: docs/code.md, docs/fix.md, docs/prioritize.md, docs/retro.md, docs/triage.md, docs/scribe.md, and docs/review.md all contain relative links like [\harness/code.yaml`](../harness/code.yaml)and`scripts/lib/pr-assignee.lib.sh`, and docs/network-policy.mdlinks../policies/, ../policies/code.yaml, ../policies/fix.yaml — all pointing at sibling directories (harness/, policies/, scripts/) that are never copied. Once rendered at /docs/agents/on fullsend.sh, these resolve to nonexistent paths like/docs/harness/code.yaml(404).website/.vitepress/config.tshasignoreDeadLinks: true, so CI will not catch this. This is distinct from the already-resolved absolute-vs-relative link thread for fullsend's own cross-references into docs/agents/` — this is about dead links baked into the vendored content itself once it lands on the live site.

Suggestion: Rewrite these relative links during fetch (e.g. a sed pass turning ../harness/*, ../policies/*, ../scripts/* into absolute https://github.com/fullsend-ai/agents/blob/main/... URLs), or coordinate with fullsend-ai/agents to keep those links absolute at the source so they survive being vendored elsewhere.

[waynesun09]

[MEDIUM] Docs build now has a hard external network dependency with no fallback

predev/prebuild now shell out to git init + git fetch --depth 1 https://github.com/fullsend-ai/agents.git "$REF" under set -euo pipefail. Previously agent docs were static files checked into this repo; now every doc-site build (local dev and CI) requires live network access to github.com and a successful fetch of another repo. If that repo/ref is temporarily unreachable or the requested ref disappears, npm run build/npm run dev fails immediately with no cached fallback to a previously-fetched snapshot, rather than degrading gracefully.

Suggestion: Consider falling back to a previously-fetched docs/agents/ (warn instead of hard-fail) when the network fetch fails, or add retry-on-transient-failure around the git fetch call, especially for CI resilience.

[rh-hemartin]

Closing due to the high nubmer of conflicts. Will reopen.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 7:20 AM UTC · Completed 7:29 AM UTC

Commit: c015ab0 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5973 — docs: pull Agents docs directly

Outcome: Closed without merge (conflicts). Author plans to reopen.

Timeline

1. 2026-08-06 10:30 — PR opened by rh-hemartin to replace vendored agent docs with a build-time fetch from fullsend-ai/agents. Closes Include fullsend-ai/agents docs in the documentation site #5710.
2. 2026-08-06 10:31–10:50 — First review agent run (31093519396). Found 1 High + 6 Medium findings. Inline comments failed with GitHub 422 errors; findings appended to review body instead.
3. 2026-08-06 11:54–12:14 — Second review agent run (31099092717). Found editLink.pattern 404 issue (medium). Again, inline comments failed with 422.
4. 2026-08-06 12:31 — Human reviewer waynesun09 posted 4 findings: 1 CRITICAL (broken glossary link causing actual CI failure), 3 MEDIUM (SHA limitation, inconsistent ADR references, cp -a nesting bug).
5. 2026-08-07 06:54 — Author replied "Fixed." to waynesun09's first 4 findings.
6. 2026-08-07 06:56–07:12 — Third review agent run (31155689660). DISMISSED, 422 inline comment failures again.
7. 2026-08-07 10:34–10:54 — Fourth review agent run (31170503535). All findings Low. APPROVED.
8. 2026-08-07 13:35 — waynesun09 posted 2 more findings: 1 HIGH (dead links in vendored agent docs pointing to unfetched sibling dirs) and 1 MEDIUM (hard network dependency with no fallback).
9. 2026-08-17 07:18 — PR closed by author due to conflicts.

Review quality assessment

What the agent caught well: editLink.pattern routing agent pages to wrong repo (unique find), double-slash URL bug from trailing slash, TMPDIR shadowing POSIX env var, scope-creep detection of accidentally included incomplete file, implementation divergence from issue #5710.

What the human caught that the agent missed:

• CRITICAL: The broken glossary link was the actual cause of the failing CI test check. The agent flagged the same link as Low [intent-alignment] but didn't connect it to the CI failure.
• HIGH: Vendored agent docs contain relative links to ../harness/, ../policies/, ../scripts/ that are never fetched — producing dead links on the live site. The agent never inspected the source content.
• MEDIUM: cp -a nesting bug from stale staging directory, SHA vs branch/tag limitation in git clone, hard network dependency with no fallback.

Evidence for existing issues (skipped as proposals)

• #6039 (422 inline comment failures): 3 of 4 review runs had 100% inline comment posting failure. Findings were appended to the review body, reducing visibility. This PR is additional evidence that the 422 problem affects re-review rounds consistently.
• #4164 (review agent should consult CI check-run results before rating severity): The agent flagged docs/glossary.md as Low [intent-alignment] while the same link was the cause of the failing CI test check. If the agent had correlated its finding with CI status, it would have escalated to Critical.
• #1772 (defer ready-for-merge on documentation-only PRs): The agent APPROVED on the 4th run, but the human reviewer posted HIGH findings 3 hours later.

New proposal

One proposal filed below — review agent should inspect externally-sourced content when reviewing content-vendoring scripts.

Proposals filed

• Review agent should inspect externally-sourced content when reviewing content-vendoring scripts (in fullsend-ai/agents)