docs: align guide language with configured/derived/custom taxonomy

[ralphbean]

Summary

• Rename guide headings from "Customizing …" to "Configuring …" to align with the three-tier vocabulary in docs/agents/topics/default-vs-custom.md (configured default / derived / custom)
• Update body language in the three guides (customizing-agents.md, customizing-with-agents-md.md, customizing-with-skills.md) to use "configure" for extension-point usage
• Update cross-references across 14 files to match the new headings — filenames unchanged to avoid breaking external links

Test plan

• Verify vitepress sidebar renders correctly with new display text
• Spot-check a few cross-reference links resolve to the right anchors (e.g. #adding-a-skill replaced #adding-a-custom-skill)

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Docs: align “configuring” terminology across agent guides and references

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Rename “Customizing …” guide headings to “Configuring …” to match the default/derived/custom
 taxonomy.
• Update guide body language and examples to use “configure” for extension-point usage.
• Refresh sidebar + cross-references so links and anchors match the new headings.

Diagram

graph TD
  R["Docs readers"] --> S["VitePress sidebar (config.ts)"] --> G["User guides (3)"] --> X["Cross-refs / anchors"]
  A["Agent docs + ADRs"] --> X --> T["Taxonomy topic doc"]
  L["public/llms.txt"] --> G
  subgraph Legend
    direction LR
    _doc["Markdown docs"] ~~~ _cfg["Site config"] ~~~ _idx["Index/link surface"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add backward-compatible anchor aliases for old headings

• ➕ Preserves external deep links that reference old #customizing-* anchors
• ➕ Reduces churn when downstream docs/blog posts reference prior section IDs
• ➖ Adds a small amount of HTML/markdown noise (extra or explicit header IDs)
• ➖ Requires deciding which legacy anchors are worth supporting long-term

2. Rename the files to match new guide names and add redirects

• ➕ URL paths and filenames match the new “Configuring …” terminology end-to-end
• ➕ Cleaner long-term information architecture
• ➖ Requires redirect support and validation across the site
• ➖ Higher risk of breaking external links if redirects are missed or unsupported

3. Keep headings as-is; explain taxonomy distinction via callouts

• ➕ Avoids anchor churn entirely
• ➕ Minimal cross-reference updates
• ➖ Leaves the primary guide titles misaligned with the configured/derived/custom vocabulary
• ➖ Users keep seeing “customize” for routine configuration extension points

Recommendation: The PR’s approach (change displayed heading/link text while keeping filenames/paths stable) is the right default for minimizing breakage. Consider additionally preserving the most common old section anchors via explicit IDs or small hidden anchor tags so existing external deep links (hash fragments) don’t regress when headings change.

Files changed (17) +58 / -58

Documentation (16) +55 / -55

llms.txtUpdate guide link display names in llms.txt +2/-2

Update guide link display names in llms.txt

• Renames the two “Customizing …” link labels to “Configuring …” variants while keeping the same URLs. Keeps the public link surface consistent with the updated guide headings.

cloudflare_site/public/llms.txt

0049-agent-configuration-env-var-convention.mdAdjust ADR cross-reference text to “Configuring …” guides +2/-2

Adjust ADR cross-reference text to “Configuring …” guides

• Updates the link text in the ADR to reference “Configuring with AGENTS.md” and “Configuring with Skills”. Link targets remain the same files.

docs/ADRs/0049-agent-configuration-env-var-convention.md

README.mdUpdate agent README links to “Configuring …” terminology +2/-2

Update agent README links to “Configuring …” terminology

• Rewords the two guide references to use “Configuring …” language while preserving the same destinations. Aligns the agent overview with the configured/derived/custom vocabulary.

docs/agents/README.md

code.mdRename configuration section guide link text +2/-2

Rename configuration section guide link text

• Updates the “Configuration and extension” section to point to “Configuring with …” guides. No behavioral/content structure changes beyond wording.

docs/agents/code.md

fix.mdRename configuration section guide link text +2/-2

Rename configuration section guide link text

• Replaces “Customizing …” link text with “Configuring …” in the configuration/extension section. Keeps the same guide paths.

docs/agents/fix.md

retro.mdRename configuration section guide link text +2/-2

Rename configuration section guide link text

• Updates configuration/extension references to the “Configuring …” wording. This keeps agent docs consistent with the taxonomy topic doc.

docs/agents/retro.md

review.mdRename configuration section guide link text +2/-2

Rename configuration section guide link text

• Updates the “See …” references to use “Configuring …” guide names. No change to link targets.

docs/agents/review.md

default-vs-custom.mdAlign taxonomy doc’s “See also” references with new guide names +4/-4

Align taxonomy doc’s “See also” references with new guide names

• Updates link text and one in-table reference to reflect “Configuring …” guide headings. Keeps the taxonomy doc as the vocabulary source of truth while pointing at the updated guide presentation.

docs/agents/topics/default-vs-custom.md

agent.mdUpdate CLI docs link text to “Configuring with skills” +1/-1

Update CLI docs link text to “Configuring with skills”

• Renames the referenced guide text from “Customizing with skills” to “Configuring with skills” while leaving the URL unchanged.

docs/cli/agent.md

README.mdRename guide index entries to “Configuring …” +3/-3

Rename guide index entries to “Configuring …”

• Updates the guide list display text for the three affected guides. Keeps links pointing at the unchanged file paths.

docs/guides/README.md

private-repositories.mdUpdate “See also” link text for agent configuration guide +1/-1

Update “See also” link text for agent configuration guide

• Renames the “Customizing agents” reference to “Configuring agent behavior”. Link destination remains the same guide file.

docs/guides/infrastructure/private-repositories.md

bring-your-own-agent.mdUpdate cross-references to “Configuring …” guide headings +4/-4

Update cross-references to “Configuring …” guide headings

• Rewords top-level and reference-section links so they render as “Configuring …”. Maintains the same guide URLs while matching the new display terminology.

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

building-custom-agents.mdRefresh narrative and anchors to “Configuring …” terminology +5/-5

Refresh narrative and anchors to “Configuring …” terminology

• Updates cross-references and some narrative language to treat extension-point usage as configuration, including section anchor references (e.g., “Adding a Skill”). Keeps the file as deprecated guidance but consistent with the taxonomy.

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

customizing-agents.mdRename “Customizing Agents” guide to “Configuring Agent Behavior” +19/-19

Rename “Customizing Agents” guide to “Configuring Agent Behavior”

• Changes the H1 and multiple section headings/examples to consistently use “configure/configuration” language. Also updates example text and anchor-relevant headings (e.g., “Adding a Skill”) so internal references match the new heading-derived IDs.

docs/guides/user/customizing-agents.md

customizing-with-agents-md.mdRename guide heading to “Configuring Agents with AGENTS.md” +2/-2

Rename guide heading to “Configuring Agents with AGENTS.md”

• Updates the H1 and a small amount of wording to frame AGENTS.md as configuration rather than customization. Keeps file path unchanged.

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

customizing-with-skills.mdRename guide heading to “Configuring Agents with Skills” +2/-2

Rename guide heading to “Configuring Agents with Skills”

• Updates the H1 and one key sentence to use “configuration” language. Preserves existing structure while aligning terminology.

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

Other (1) +3 / -3

config.tsUpdate sidebar labels for the three renamed guides +3/-3

Update sidebar labels for the three renamed guides

• Renames sidebar display text to “Configuring …” for the three guide entries. Link paths remain the existing /guides/user/customizing-* routes to avoid breaking URLs.

website/.vitepress/config.ts

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:46 AM UTC · Completed 11:58 AM UTC
Commit: 56f8b71 · View workflow run →

[github-actions]

Site preview

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

Commit: 56f8b71f2f51398d4e88961b8c5a1f5c10c43957

[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)

Context used

✅ Compliance rules (platform): 54 rules

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

1. Guide file in infrastructure/ 📜 Skill insight ⌂ Architecture

Description

docs/guides/infrastructure/private-repositories.md is a guide but is not placed under
docs/guides/admin/ or docs/guides/user/, violating the required guide directory taxonomy. This
can cause documentation IA drift and breaks the compliance expectation that each guide targets a
single audience and lives in the corresponding subdirectory.

Code

docs/guides/infrastructure/private-repositories.md[197]

+- [Configuring agent behavior](../user/customizing-agents.md) — Harness configuration and layered overrides

Relevance

● Weak

Same guide-taxonomy move request was explicitly rejected multiple times; team keeps non-admin/user
guide folders (dev/infrastructure).

PR-#5454
PR-#5502
PR-#4901

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The checklist requires all guide files under docs/guides/ to live under either admin/ or
user/. This PR modifies a guide located under docs/guides/infrastructure/, which is outside the
allowed directories.

docs/guides/infrastructure/private-repositories.md[197-197]
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
A modified guide lives at `docs/guides/infrastructure/private-repositories.md`, but guides must be placed under either `docs/guides/admin/` or `docs/guides/user/`.

## Issue Context
This PR updates content in that file, so the location issue is in-scope for compliance.

## Fix Focus Areas
- docs/guides/infrastructure/private-repositories.md[197-197]

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

---

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

[fullsend-ai-review]

Looks good to me

---

Labels: PR modifies only documentation files (guides, agent docs, ADRs, llms.txt, vitepress config)

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 2:16 PM UTC · Completed 2:26 PM UTC
Commit: 56f8b71 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5711 — docs terminology alignment

Workflow went well. This human-authored PR by @ralphbean renamed guide headings from "Customizing" to "Configuring" across 17 documentation files (+58/−58, pure text replacement). The review agent approved in ~13 minutes with "Looks good to me" and correctly labeled it component/docs and ready-for-merge. Human reviewer @rh-hemartin approved ~2 hours later. Merged cleanly with zero rework.

Review quality was appropriate. Independent diff analysis confirms: no broken cross-references (filenames were deliberately preserved), consistent terminology application, correct anchor updates, and no unintended side effects in the one non-markdown file changed (config.ts sidebar labels only). The review agent's LGTM was the right call.

No new proposals — existing issues already cover the improvement opportunities identified:

• Review orchestrator: add fast path for trivial docs/prompt-only changes #1900 (Review orchestrator: fast path for trivial docs/prompt-only changes): This PR is another data point. A pure mechanical text replacement across 17 files used opus-tier model and the full review orchestrator pipeline for ~13 minutes. A fast path could reduce this to seconds.
• Review orchestrator should promote docs sub-agent budget priority for docs-only PRs #5298 (Promote docs sub-agent budget priority for docs-only PRs): The full six-dimension sub-agent dispatch ran on a change with zero code modifications — most dimensions had nothing meaningful to evaluate.
• Track autonomy readiness: review agent fully covered human review on docs-only mechanical path update #5289 (Track autonomy readiness: docs-only mechanical changes): This PR adds another evidence point. The review agent's approval was indistinguishable from the human reviewer's — both approved without substantive comments on a low-risk terminology change.
• migrate-customizations should upgrade deprecated runner_env to env.runner/env.sandbox (ADR 0055) #3339 / Emit deprecation warning when harness YAML contains runner_env field #3730 (runner_env deprecation): The review harness config at fullsend-ai/agents still uses runner_env under forge.github, producing a deprecation warning in the run log. Already tracked for migration.