docs: add Bring Your Own Agent guide and agent CLI reference

docs/ADRs/0058-agent-registration.md

@@ -88,4 +88,5 @@ phasing, schema details, CLI behavior, and migration mechanics.
 - [ADR 0038](0038-universal-harness-access.md) -- URL-based resource references and integrity hashes
 - [ADR 0045](0045-forge-portable-harness-schema.md) -- harness composition via `base:` URLs
 - [ADR 0057](0057-repos-management.md) -- repos management for per-repo installations
+- [Bring Your Own Agent](../guides/user/bring-your-own-agent.md) -- user-facing guide for agent registration
 - [Implementation plan](../plans/agent-registration.md)

docs/ADRs/0065-provider-backed-policy-composition.md

@@ -159,7 +159,8 @@ automatically by `fullsend run`.
   policies continue to work, but the scaffold and guides recommend
   providers as the preferred approach.
 - The building-custom-agents guide is updated to show providers as
-  the recommended way to grant network access.
+  the recommended way to grant network access. (Note: this guide has
+  been superseded by [Bring Your Own Agent](../guides/user/bring-your-own-agent.md).)
 - Requires OpenShell >= v0.0.37 and the `providers_v2_enabled` gateway
   setting (set automatically).
 - GitHub access is split into read-write (`fullsend-github`) and

docs/agents/README.md

@@ -34,4 +34,5 @@ your org-level or per-repo `config.yaml`. Each entry is either a local path
 (relative to the fullsend directory) or a pinned HTTPS URL with an integrity
 hash. Config-registered agents override scaffold defaults when names collide
 (case-insensitive). See [ADR 0058](../ADRs/0058-agent-registration.md) for
-details.
+details and [Bring Your Own Agent](../guides/user/bring-your-own-agent.md)
+for the complete guide to building and registering custom agents.

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

@@ -94,7 +94,7 @@ for a stated purpose, that override does not make the agent derived.
   — project-wide instructions for all agents
 - [Customizing with skills](../../guides/user/customizing-with-skills.md) —
   extending or replacing built-in skills
-- [Building custom agents](../../guides/user/building-custom-agents.md) —
-  creating a new agent from scratch
+- [Bring Your Own Agent](../../guides/user/bring-your-own-agent.md) —
+  building custom agents and configuring existing ones
 - [ADR 0045](../../ADRs/0045-forge-portable-harness-schema.md) — `base`
   composition and harness inheritance

docs/cli/README.md

@@ -14,6 +14,7 @@ Download the latest binary from [GitHub Releases](https://github.com/fullsend-ai
 
 | Command group | Description |
 |--------------|-------------|
+| [`fullsend agent`](agent.md) | Manage agent registrations — add, list, update, remove, and migrate-customizations |
 | [`fullsend github`](github.md) | Configure GitHub orgs and repos — setup, enrollment, day-2 operations |
 | [`fullsend inference`](inference.md) | Manage GCP Workload Identity Federation for Agent Platform access |
 | [`fullsend mint`](mint.md) | Deploy and manage the OIDC token mint service |
@@ -24,7 +25,6 @@ Download the latest binary from [GitHub Releases](https://github.com/fullsend-ai
 | Command | Description |
 |---------|-------------|
 | `fullsend run` | Execute an agent locally in a sandbox. See [running agents locally](../guides/user/running-agents-locally.md). |
-| `fullsend agent` | Manage agent registrations in config. Subcommands: `add`, `list`, `update`, `remove` (CRUD) and `migrate-customizations` (one-time migration of `customized/` overrides to config-driven agents per ADR-0064) |
 | `fullsend lock [agent-name]` | Pin remote dependencies to `lock.yaml` |
 | `fullsend scan` | Run security scanners on agent input/output |
 

docs/cli/agent.md

@@ -0,0 +1,126 @@
+---
+sidebar_label: fullsend agent
+---
+
+# fullsend agent
+
+Manage agent registrations in fullsend config. Add, list, update, and remove agents, or migrate legacy `customized/` overrides to config-driven agents.
+
+`agent add`, `agent update`, and `agent migrate-customizations` (non-dry-run) fetch remote content and resolve GitHub URLs. Authentication is via `gh` CLI or `GH_TOKEN` environment variable.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `fullsend agent add <url-or-path>` | Register an agent in config |
+| `fullsend agent list` | List registered agents |
+| `fullsend agent update <name> [sha]` | Update a URL agent to a new commit SHA |
+| `fullsend agent remove <name>` | Remove an agent from config |
+| `fullsend agent migrate-customizations` | Migrate `customized/` overrides to config-driven agents |
+
+## `agent add`
+
+Register an agent in config by URL or local path. URL sources are automatically pinned to a specific commit SHA and annotated with a `#sha256=...` integrity hash. The URL prefix is added to `allowed_remote_resources` if not already present.
+
+```bash
+fullsend agent add https://github.com/my-org/agents/blob/main/harness/lint.yaml --fullsend-dir .fullsend
+fullsend agent add harness/custom-review.yaml --name my-review --fullsend-dir .fullsend
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fullsend-dir` | | Base directory containing the `.fullsend` layout (required) |
+| `--name` | derived from filename | Explicit agent name |
+
+GitHub blob URLs are resolved to pinned `raw.githubusercontent.com` URLs. Non-GitHub URLs must already contain a commit SHA in the path. Local paths must be relative, must not contain path traversal (`..`), and the file must exist. If an agent with the same name already exists, the command fails.
+
+## `agent list`
+
+List all agents registered in config, showing each agent's name and source.
+
+```bash
+fullsend agent list --fullsend-dir .fullsend
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fullsend-dir` | | Base directory containing the `.fullsend` layout (required) |
+
+Read-only. Displays a table with `NAME` and `SOURCE` columns. For URL agents, the `#sha256=...` integrity hash suffix is stripped from the displayed source for readability.
+
+Example output:
+```
+NAME     SOURCE
+triage   https://raw.githubusercontent.com/fullsend-ai/agents/abc123/harness/triage.yaml
+my-lint  harness/my-lint.yaml
+```
+
+## `agent update`
+
+Update a URL-based agent to a new commit SHA and recompute the `#sha256=...` integrity hash. If no SHA is provided, the default branch HEAD is resolved automatically.
+
+```bash
+fullsend agent update triage --fullsend-dir .fullsend
+fullsend agent update triage a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 --fullsend-dir .fullsend
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fullsend-dir` | | Base directory containing the `.fullsend` layout (required) |
+
+Only URL agents can be updated — local path agents have nothing to pin. Non-GitHub URL agents require an explicit SHA argument. The integrity hash is recomputed by fetching the content at the new SHA.
+
+## `agent remove`
+
+Remove an agent from config. If the removed agent was the last one using a given `allowed_remote_resources` prefix, that prefix is also cleaned up.
+
+```bash
+fullsend agent remove triage --fullsend-dir .fullsend
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fullsend-dir` | | Base directory containing the `.fullsend` layout (required) |
+
+## `agent migrate-customizations`
+
+Scan the `customized/` directory and migrate each override to a config-driven agent. Changes are committed to a branch and delivered via pull request. Use `--dry-run` to preview changes without creating a PR.
+
+```bash
+fullsend agent migrate-customizations --fullsend-dir .fullsend --dry-run
+fullsend agent migrate-customizations --fullsend-dir .fullsend --repo owner/repo
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fullsend-dir` | | Base directory containing the `.fullsend` layout (required) |
+| `--repo` | | Target repository (`owner/repo`) for the migration PR (required unless `--dry-run`) |
+| `--dry-run` | `false` | Show what would change without creating a PR |
+
+### Override classification
+
+The tool classifies each override and takes the appropriate action:
+
+| Override type | Detection | Action |
+|---------------|-----------|--------|
+| Dead | Agent already registered in config | Delete `customized/` files |
+| Custom | Not in upstream scaffold | Move files to regular directories, register local path in config |
+| Modified | Standard scaffold agent, not yet in config | Generate a `base:` composition harness with the minimal diff, register in config |
+
+For modified agents, the migration produces a thin `base:` harness containing only the fields that differ from upstream.
+
+## See also
+
+- [Bring Your Own Agent](../guides/user/bring-your-own-agent.md) — building custom agents and configuring existing ones
+- [Default, derived, and custom agents](../agents/topics/default-vs-custom.md) — terminology and classification
+- [Customizing with skills](../guides/user/customizing-with-skills.md) — extending agents with skills

docs/glossary.md

@@ -45,7 +45,7 @@ See [Default, derived, and custom agents](agents/topics/default-vs-custom.md).
 ### Custom Agent
 
 An agent whose `base` chain does not trace back to a default agent harness in `fullsend-ai/fullsend`, or that has no `base` at all. A custom agent is built from scratch, even if it happens to resemble a default agent. Contrast with [derived agent](#derived-agent), which starts from a default.
-See [Default, derived, and custom agents](agents/topics/default-vs-custom.md) and [Building custom agents](guides/user/building-custom-agents.md).
+See [Default, derived, and custom agents](agents/topics/default-vs-custom.md) and [Bring Your Own Agent](guides/user/bring-your-own-agent.md).
 
 ## D
 

docs/guides/README.md

@@ -37,7 +37,8 @@ Guides for developers working in repositories where fullsend is active.
 - [Customizing agents](user/customizing-agents.md) — Harness configurations and layered content resolution for your org and repos
 - [Customizing with AGENTS.md](user/customizing-with-agents-md.md) — Guide agents using your repo's AGENTS.md file
 - [Customizing with skills](user/customizing-with-skills.md) — Extend or replace built-in agent skills with custom skill documents
-- [Building custom agents from scratch](user/building-custom-agents.md) — Create a new agent from scratch on a per-repo fullsend installation
+- [Bring Your Own Agent](user/bring-your-own-agent.md) — Add a custom agent or configure an existing one, from harness file to CI
+- [Building custom agents from scratch](user/building-custom-agents.md) — _(deprecated — see [Bring Your Own Agent](user/bring-your-own-agent.md))_
 - [Default, derived, and custom agents](../agents/topics/default-vs-custom.md) — When configuration crosses into derived or custom agent territory
 
 ## Development

docs/guides/infrastructure/private-repositories.md

@@ -194,6 +194,6 @@ Not all private repos are equal. A repo containing open-source code that happens
 ## See also
 
 - [Getting Started](../getting-started/) — Initial fullsend setup
-- [Configuring agents](../user/customizing-agents.md) — Harness configuration and layered overrides
+- [Customizing agents](../user/customizing-agents.md) — Harness configuration and layered overrides
 - [Security threat model](../../problems/security-threat-model.md) — Threat priority and defense considerations
 - [#1189](https://github.com/fullsend-ai/fullsend/issues/1189) — Retro agent private content leak risk

docs/guides/infrastructure/standalone-mint.md

@@ -353,5 +353,5 @@ gh api -X POST /orgs/myorg/actions/variables \
 ## See also
 
 - [Mint service administration](mint-administration.md) — Managing the hosted GCP mint
-- [Building custom agents](../user/building-custom-agents.md) — Creating new agents for your repos
+- [Bring Your Own Agent](../user/bring-your-own-agent.md) — Building custom agents and configuring existing ones
 - [Getting Started](../getting-started/) — End-user setup