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

CONTRIBUTING.md

@@ -73,6 +73,67 @@ Human contributors may include an ADR and its implementation in the same PR when
 
 ADR filenames use a four-digit number (`NNNN-short-description.md`). When multiple PRs add ADRs concurrently, number collisions can happen. Before merging, use the `/renumber-adr` skill to check whether your ADR number is still available on the target branch and renumber if needed.
 
+## Deprecation notices in documentation
+
+When a feature, field, command, or workflow is deprecated, label it clearly in
+the user-facing documentation so readers can distinguish current functionality
+from deprecated functionality. Use the following conventions consistently.
+
+### Blockquote notice (preferred for sections)
+
+Place a blockquote at the top of the section that describes the deprecated
+feature. Use this format:
+
+```markdown
+> **Deprecated:** `<feature>` is deprecated. Use `<replacement>` instead.
+> <Migration guidance — one or two sentences explaining how to migrate.>
+```
+
+Key elements:
+- Start with **`> **Deprecated:**`** (bold, followed by a colon).
+- Name the deprecated feature explicitly.
+- Describe the replacement and how to migrate.
+
+### Inline annotation (for field references and tables)
+
+When a deprecated item appears in a table, code block, or field reference,
+add a short inline annotation:
+
+```yaml
+runner_env:    # ⚠ Deprecated: use env.runner instead
+```
+
+```markdown
+| `env`, `runner_env` (deprecated) | Merged; child keys win |
+```
+
+### Sidebar or guide index entry
+
+When an entire guide page is deprecated, annotate the link in the index:
+
+```markdown
+- [Building custom agents](path) — _(deprecated — see [Replacement](path))_
+```
+
+### What to include
+
+Every deprecation notice should answer three questions:
+1. **What** is deprecated?
+2. **What replaces it?** (link to the replacement feature or guide)
+3. **How do I migrate?** (command, config change, or link to migration docs)
+
+If there is no replacement yet, say so explicitly (e.g., "removal is planned
+for a future release; no migration is needed").
+
+### When to add notices
+
+- When a feature is deprecated, update the affected user-facing docs in the
+  same PR or a follow-up.
+- When touching a doc page that references a deprecated feature without a
+  notice, add one.
+- Do not remove deprecated content from docs — label it so users on older
+  versions can still find the reference material.
+
 ## Building from source
 
 ```bash

docs/doc-site.md

@@ -44,3 +44,37 @@ The `predev` and `prebuild` hooks in `website/package.json` handle initializatio
 - **`.github/workflows/site-deploy.yml`** — deploys the built artifact to Cloudflare Workers on `main` pushes, uploads preview versions on PRs
 
 For Cloudflare Worker setup, secrets, and troubleshooting, see [`web-admin-deployment.md`](web-admin-deployment.md).
+
+## Documentation versioning (investigation)
+
+Users on older fullsend releases may encounter docs that describe features or
+behaviors not present in their version. Versioned docs would let users view
+documentation matching their installed release. This section captures the
+feasibility investigation for future implementation.
+
+### Options evaluated
+
+| Approach | How it works | Effort | Trade-offs |
+|----------|-------------|--------|------------|
+| **VitePress multi-version** | Build docs from each release tag into a versioned path (e.g., `/docs/v0.21/`, `/docs/v0.22/`). Add a version switcher dropdown in the nav bar. | Medium–high | Requires CI changes to build and deploy per-tag. Storage grows linearly with releases. VitePress does not have built-in versioning — it must be implemented via custom config and multi-build CI. |
+| **Branch-based versioning** | Maintain a `docs-vN` branch per major/minor release. Deploy each branch to a path prefix. | Medium | Backport burden — fixes to docs must be cherry-picked to each active branch. Works well for projects with long-lived release branches. |
+| **Git tag snapshots** | At release time, snapshot `docs/` into a versioned archive or static build. Serve from a `/docs/archive/vN.N/` path. | Low–medium | Read-only archives — no live editing of old versions. Simple to implement but less polished than a version switcher. |
+| **Deprecation notices only** (current approach) | Label deprecated features inline; do not version the docs. Users read one set of docs with deprecation markers. | Low (done) | Sufficient when the deprecation surface is small and migration paths are clear. Does not help users find docs for removed features. |
+
+### Recommendation
+
+The current approach — deprecation notices with migration guidance — is
+sufficient for the near term. The project has a small number of deprecated
+features, all with clear replacements and migration tooling
+(`fullsend agent migrate-customizations`, `env.runner` migration). Versioned
+docs add ongoing maintenance cost (per-release builds, backport burden) that
+is not yet justified.
+
+**When to revisit:** If a future release removes deprecated features entirely
+(e.g., `runner_env` removal, `customized/` removal), users
+on older versions will lose reference material. At that point, the git tag
+snapshot approach offers the best effort-to-value ratio: snapshot the docs at
+the last release before removal and serve them as a read-only archive.
+
+See [#4886](https://github.com/fullsend-ai/fullsend/issues/4886) for the
+original discussion.

docs/guides/README.md

@@ -9,7 +9,7 @@ Guides for onboarding organizations and configuring GitHub — the first thing m
 - [Mint enrollment](getting-started/README.md) — Enroll your org or repo in a token mint before configuring anything else
 - [Getting Inference](getting-started/getting-inference.md) — Provision GCP inference access for your org or repo
 - [Configuring GitHub](getting-started/configuring-github.md) — Install GitHub Apps and run the setup CLI
-- [Organization Mode](getting-started/org-mode.md) — Org-wide setup with a shared `.fullsend` config repo
+- [Organization Mode](getting-started/org-mode.md) — _(deprecated — see [per-repo Getting Started](getting-started/configuring-github.md))_ Org-wide setup with a shared `.fullsend` config repo
 
 ## Operations & Advanced Setup
 

docs/guides/dev/cli-internals.md

@@ -182,7 +182,10 @@ The `mint`, `inference`, and `github` subcommands decompose setup into role-spec
 
 The typical handoff: a GCP admin runs `mint deploy`, `mint enroll`, and `inference provision`, then passes the mint URL and WIF provider resource name to a GitHub maintainer who runs `github setup --mint-url=... --inference-wif-provider=...`. See [Advanced setup](../infrastructure/advanced-setup.md).
 
-> **Note:** The legacy `admin install` command wraps all phases into a single invocation but is deprecated. The standalone commands above are the recommended path. See the [Unified Installation Flow](#unified-installation-flow) section below for how the phases are structured internally.
+> **Deprecated:** The `admin install` command is deprecated. Use the
+> standalone commands above instead. See the
+> [Unified Installation Flow](#unified-installation-flow) section below for
+> how the phases are structured internally.
 
 ### Token Resolution Chain
 

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

@@ -4,7 +4,11 @@ sidebar_position: 4
 
 # Per-Org Mode
 
-> **Planned deprecation.** Per-org installation mode will be deprecated in favor of per-repo installation ([ADR 0044](../../ADRs/0044-deprecate-per-org-installation-mode.md)). New installations should use the [per-repo Getting Started guides](README.md). Existing per-org installations continue to work and are fully supported during the transition.
+> **Deprecated:** Per-org installation mode is deprecated in favor of per-repo
+> installation. New installations should use the [per-repo Getting Started guides](README.md).
+> Existing per-org installations continue to work and are fully supported during
+> the transition. To migrate, run `fullsend github setup` per-repo instead of
+> `fullsend admin install` per-org.
 
 The goal of this document is that you install Fullsend for your whole
 GitHub organization, so different repositories share inference and infrastructure.

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

@@ -232,7 +232,7 @@ env:
     MY_VAR: "${MY_VAR}"
   sandbox:                           # Available inside sandbox
     MY_SETTING: "value"
-runner_env:                          # Legacy (same as env.runner)
+runner_env:                          # ⚠ Deprecated: use env.runner instead
   MY_VAR: "${MY_VAR}"
 
 # ── Timeouts ──────────────────────────────────────────────────
@@ -270,6 +270,13 @@ security:
   fail_mode: closed                  # "closed" (default) or "open"
 ```
 
+### Deprecated fields
+
+> **Deprecated:** `runner_env` is deprecated. Use `env.runner`
+> instead. The `runner_env` field still works but emits a deprecation warning
+> at runtime. Migration: move `runner_env:` entries under `env: runner:` and
+> delete the `runner_env:` block.
+
 ### Field merge rules (for `base` and `forge`)
 
 | Field type | Behavior |
@@ -278,7 +285,7 @@ security:
 | `skills` | Merged with deduplication by basename (child overrides base) |
 | `plugins`, `providers`, `api_servers`, `openshell.profiles` | Concatenated (base + child) |
 | `host_files` | Concatenated; child overrides by `dest` |
-| `env`, `runner_env` | Merged; child keys win |
+| `env`, `runner_env` (deprecated) | Merged; child keys win |
 | `validation_loop`, `security` | Child replaces entirely |
 | `allowed_remote_resources`, `allow_runtime_fetch`, `max_runtime_fetches` | NOT inherited (child must declare its own) |
 

docs/guides/user/customizing-agents.md

@@ -404,8 +404,11 @@ variables to protect sandbox operation.
 
 ### Adding a Custom Skill
 
-Create `.fullsend/customized/skills/my-skill/SKILL.md` in your config repo
-(deprecated — use config-driven agent registration instead):
+> **Deprecated:** The `customized/skills/` path is deprecated.
+> Use config-driven agent registration instead — see
+> [Bring Your Own Agent](bring-your-own-agent.md).
+
+Create `.fullsend/customized/skills/my-skill/SKILL.md` in your config repo:
 
 ```markdown
 # My Custom Skill
@@ -421,8 +424,12 @@ The skill will be automatically available to all agents that include `skills/my-
 
 ### Overriding an Agent Definition
 
+> **Deprecated:** The `customized/agents/` override is deprecated.
+> Use `base:` composition instead — see
+> [Configuring existing agents](bring-your-own-agent.md#configuring-existing-agents).
+
 Create `.fullsend/customized/agents/code.md` to override the default code agent
-with org-specific instructions (deprecated — use `base:` composition instead):
+with org-specific instructions:
 
 ```markdown
 # Code Agent (Customized)

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

@@ -120,7 +120,7 @@ takes precedence.
   cannot write files regardless of what AGENTS.md says)
 - Remove or replace built-in skills — use
   [`customized/skills/`](customizing-with-skills.md#overriding-built-in-skills)
-  for that (deprecated per ADR-0064; use config-driven agent registration instead)
+  for that (deprecated; use config-driven agent registration instead)
 - Change the agent's model or execution parameters
 
 ### Injection handling