docs(#4886): label deprecated features in user documentation

[fullsend-ai-coder]

Summary

Add visible deprecation notices and migration guidance to user-facing documentation for deprecated features (runner_env, customized/ overlay, per-org mode, admin install), establish a contributor convention for deprecation labeling, and document a documentation versioning feasibility investigation.

Related Issue

Closes #4886

Changes

• Deprecation convention (CONTRIBUTING.md): Add a "Deprecation notices in documentation" section with three templates (blockquote, inline, index entry) and guidance on what to include and when to add notices
• runner_env labeling (bring-your-own-agent.md): Add deprecation notice with migration guidance to env.runner per ADR-0055; mark in field reference table and code examples
• Per-org mode (org-mode.md): Update "Planned deprecation" to "Deprecated" with migration command per ADR-0044; mark in guides/README.md index
• customized/ overlay (customizing-agents.md): Convert inline deprecation annotations to proper blockquote notices linking ADR-0064 for customized/skills/ and customized/agents/ sections
• admin install (cli-internals.md): Add ADR-0069 link and use consistent deprecation format
• ADR link (customizing-with-agents-md.md): Add missing hyperlink to ADR-0064
• Versioning investigation (doc-site.md): Evaluate four approaches (VitePress multi-version, branch-based, git tag snapshots, deprecation-only) with recommendation to revisit when features are removed

Testing

• lychee markdown link checker passes on all changed files (0 errors)
• scan-secrets passes on all changed files
• gitlint passes on commit message
• No Go code changed — docs-only PR

Checklist

• 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

---

Closes #4886

Post-script verification

• Branch is not main/master (agent/4886-label-deprecated-docs)
• Secret scan passed (gitleaks — cb2bcd9f282952232249eca4a281a3392a617d41..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:45 PM UTC · Completed 2:01 PM UTC
Commit: 3db5677 · View workflow run →

[github-actions]

Site preview

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

Commit: 6d7ec235e7933ac906b5c4221e237957ff070ea7

[fullsend-ai-review]

Review

Findings

Medium

• [documentation-accuracy] docs/guides/dev/cli-internals.md:185 — The deprecation notice attributes the admin install deprecation to ADR-0069 ("Ready-made configuration presets for simplified installation"), but ADR-0069 does not make the deprecation decision — it merely mentions the deprecation as pre-existing context in its Context section. The actual deprecation of per-org commands including admin install <org> is decided in ADR-0044 ("Deprecate per-org installation mode"). Readers following the ADR-0069 link will find a decision about config presets and layered configuration, not about admin install deprecation.
  Remediation: Change the ADR reference to ADR-0044, or omit the ADR reference and state the deprecation without attribution.

Low

• [migration-guidance] docs/guides/getting-started/org-mode.md:12 — The new migration guidance says "run fullsend github setup per-repo instead of fullsend admin install per-org." However, ADR-0044 Section 3 prescribes a more detailed migration process using fullsend admin install <owner>/<repo> with specific flags or fullsend admin migrate <org> <repo>. The simplified guidance risks users missing critical migration steps.
  Remediation: Link to the full migration plan in ADR-0044 Section 3, or mention fullsend admin migrate which is the purpose-built migration command.

• [stale-doc] docs/architecture.md — The "Configuration layering" section describes the customized/ overlay mechanism. It mentions deprecation inline but not in the blockquote format established by this PR's new CONTRIBUTING.md convention.
  Remediation: Add a blockquote deprecation notice referencing ADR-0064 to match the new convention.

• [stale-doc] docs/guides/user/running-agents-locally.md — The "Simulating Fullsend's real customization layers" section provides instructions for using the customized/ overlay without a deprecation notice.
  Remediation: Add a deprecation notice referencing ADR-0064 and pointing to config-driven agent registration.

---

Labels: PR is documentation-only work establishing deprecation conventions and labeling deprecated features across user-facing guides

[fullsend-ai-review]

See the review comment for full details.

[rh-hemartin]

/fs-fix remove mentions to ADRs, just that something is deprecated and the alternative.

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 7:23 AM UTC · Completed 7:27 AM UTC
Commit: 3db5677 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Removed all ADR references from deprecation notices across 7 files per human instruction. Each notice now states only what is deprecated and what the alternative is.

Fixed (7):

1. ADR references in CONTRIBUTING.md deprecation convention template (CONTRIBUTING.md): Removed ADR-NNNN link from blockquote template, removed 'Link to the ADR' key element, removed '(ADR 0055)' from inline annotation example, and changed 'When an ADR deprecates' to 'When a feature is deprecated'
2. ADR-0055 reference in doc-site.md versioning investigation (docs/doc-site.md): Removed 'in ADR-0055 Phase 3' from the 'When to revisit' paragraph, keeping only the feature name
3. ADR-0069 reference in cli-internals.md admin install deprecation (docs/guides/dev/cli-internals.md): Removed 'per ADR-0069' from the admin install deprecation notice
4. ADR-0044 reference in org-mode.md deprecation notice (docs/guides/getting-started/org-mode.md): Removed 'per ADR-0044' from the per-org mode deprecation notice
5. ADR-0055 references in bring-your-own-agent.md runner_env deprecation (docs/guides/user/bring-your-own-agent.md): Removed '(ADR 0055)' from inline code comment and 'per ADR-0055' from the Deprecated fields blockquote
6. ADR-0064 references in customizing-agents.md deprecation notices (docs/guides/user/customizing-agents.md): Removed 'per ADR-0064' from both the customized/skills/ and customized/agents/ deprecation notices
7. ADR-0064 reference in customizing-with-agents-md.md (docs/guides/user/customizing-with-agents-md.md): Removed 'per ADR-0064' from the inline deprecation note, keeping just '(deprecated; use config-driven agent registration instead)'

Tests: passed

_{Updated by fullsend fix agent}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 7:52 AM UTC · Completed 8:03 AM UTC
Commit: 6d7ec23 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5462 — Label deprecated features in user documentation

Workflow timeline:

1. Jul 14 — Triage agent created issue Clearly label deprecated features in user documentation #4886 from meeting notes ("Clearly label deprecated features in user documentation")
2. Jul 22 13:31 — Human (rh-hemartin) triggered /fs-code
3. Jul 22 13:33–13:43 — Code agent (run 29924320201) produced an 8-file commit adding deprecation notices with ADR cross-references
4. Jul 22 13:44–14:01 — Review agent (run 29925261633) posted 4 findings: 1 medium (ADR-0069 misattributed — should be ADR-0044), 3 low (migration guidance, 2 stale-doc findings outside the PR diff)
5. Jul 27 07:21 — Human posted /fs-fix remove mentions to ADRs, just that something is deprecated and the alternative.
6. Jul 27 07:22–07:28 — Fix agent (run 30245882735) removed ADR references from 7 files in one clean iteration
7. Jul 27 07:44 — Human approved; 07:49 — merged

Assessment: The pipeline worked well overall. The code agent completed the initial task efficiently (10 min, 8 files). The review agent correctly identified a real accuracy problem (wrong ADR attribution). The fix agent executed the human's broader correction cleanly in a single iteration. Total agent compute was proportionate to the task.

Rework analysis: One fix iteration was needed. The root cause was the code agent citing ADR numbers in user-facing deprecation notices — it got one citation wrong (ADR-0069 instead of ADR-0044), and more broadly, the human decided that ADR references don't belong in user-facing docs at all. The review agent caught the specific error but not the higher-level pattern. The human added the insight that users don't need internal decision-record numbers.

Existing issues cover the improvement opportunities:

• Documentation shouldn't link to ADRs #3862 ("Documentation shouldn't link to ADRs") — directly covers the root cause. This PR provides additional evidence: the code agent added ADR links throughout deprecation notices, and the human explicitly removed all of them. Notably, the merged CONTRIBUTING.md deprecation template now omits the ADR-link requirement, partially implementing Documentation shouldn't link to ADRs #3862 for deprecation-specific cases.
• Code agent should not propagate unverified document references from issue body into commit messages agents#215 ("Code agent should not propagate unverified document references") — the code agent misattributed ADR-0069 (which merely mentions admin install deprecation as context) as the decision source, when ADR-0044 made the actual deprecation decision. This is a related but distinct failure mode: the agent read the ADRs but confused "mentions" with "decides."
• Review agent should surface a summary verdict distinguishing PR-introduced findings from pre-existing ones agents#130 ("Review agent should distinguish PR-introduced findings from pre-existing ones") — the review agent's two stale-doc findings (architecture.md, running-agents-locally.md) were about files outside the PR diff. These were correctly labeled as low but could benefit from clearer pre-existing-issue labeling.

No new proposals filed — the identified improvements are already tracked in the issues above.