diff --git a/docs/ADRs/0058-agent-registration.md b/docs/ADRs/0058-agent-registration.md
index 5a25379af9..f67fc62170 100644
--- a/docs/ADRs/0058-agent-registration.md
+++ b/docs/ADRs/0058-agent-registration.md
@@ -94,3 +94,11 @@ in the sections below.
 - [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
+
+## Notes
+
+- `fullsend agent new` (added for
+  [#6966](https://github.com/fullsend-ai/fullsend/issues/6966)) generates a
+  complete custom agent and then registers it through the `agent add` path
+  described here. It adds a generator in front of this decision; the
+  registration model itself is unchanged.
diff --git a/docs/ADRs/0102-generate-custom-agents-from-the-cli.md b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
new file mode 100644
index 0000000000..be4b6d13ba
--- /dev/null
+++ b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
@@ -0,0 +1,127 @@
+---
+title: "102. Generate custom agents from the CLI"
+status: Accepted
+relates_to:
+  - agent-architecture
+topics:
+  - cli
+  - harness
+  - onboarding
+---
+
+# 102. Generate custom agents from the CLI
+
+Date: 2026-09-03
+
+## Status
+
+Accepted
+
+## Context
+
+Building a custom agent from scratch is the most common piece of negative user
+feedback on fullsend. The
+[Bring Your Own Agent guide](../guides/user/bring-your-own-agent.md) asks the
+author to hand-write a harness with roughly thirty fields, an agent definition
+whose `tools:` must stay consistent with its body, a result schema, a
+post-script that safely turns model output into a forge mutation, a CEL
+`trigger`, and a `policies/base.yaml` that a per-repo install does not vendor.
+
+Most of those mistakes are invisible until the first dispatch after merge
+(#6830). Three of them are invisible even then:
+
+- A harness with no `trigger:` registers, validates, and appears in
+  `fullsend agent list`, and is then skipped by dispatch with a bare `continue`
+  and no annotation — while resolve and load failures both emit `::error::`.
+  None of the seven fleet harnesses has a `trigger:` to copy from, because the
+  fleet is dispatched by stage workflows instead.
+- A `role:` the hosted mint does not serve is only regex-checked locally and
+  surfaces as an opaque `403` at run time (#6563).
+- A `policy:` or provider path naming a file that is not there fails at run
+  time, or worse degrades to a warning and a sandbox that cannot reach Vertex
+  (#6834).
+
+[#4839](https://github.com/fullsend-ai/fullsend/issues/4839) records a July
+decision to prefer guides over a CLI for this. That decision was taken in Slack
+and was never written up as an ADR, so this is a new decision rather than a
+superseding one. Two things have changed since: user feedback that the guides
+are not enough, and the precedent of
+[GitHub Agentic Workflows](https://github.com/github/gh-aw), which solved the
+same onboarding problem with `gh aw new` — a generator that writes a minimal
+valid source, leaving the user to edit prose rather than plumbing.
+
+## Options
+
+**Improve the guides further.** Cheapest, and the status quo. But the failure
+modes above are not comprehension failures — a reader who understands the guide
+perfectly still cannot tell that an omitted `trigger:` means the agent will
+never run, because nothing reports it.
+
+**Ship the stub templates from `fullsend-ai/agents` and have the CLI fetch and
+pin them like `agent add` does.** Keeps template changes on the agents repo's
+release cadence. Rejected for the first cut: it makes the generator's happy
+path depend on network and `allowed_remote_resources` state, which reintroduces
+the "fails only at first dispatch" class this change exists to remove, and it
+creates a merge-order dependency between the two repositories. Revisitable
+later as an opt-in `--template-ref`.
+
+**Generate from templates embedded in the CLI.** Chosen.
+
+## Decision
+
+Add `fullsend agent new <name>`, which writes a complete, valid, registered
+agent from a minimum of parameters and validates the result before returning.
+
+Four properties make it worth having rather than being a scaffolding
+convenience:
+
+1. **A trigger is mandatory.** The command refuses to write a trigger-less
+   harness, and `--on` presets emit expressions taken verbatim from the CEL
+   reference — a test asserts the generator and the documentation stay the same
+   text. The `command:` and `pr-opened` presets both refuse events from forks,
+   which matters because the default trigger is attached to every generated
+   agent, including agents with role `coder`.
+2. **The role table is closed and checked.** `--role` accepts the five fleet
+   roles the hosted mint serves. It is hardcoded rather than derived from
+   `mintcore.BuiltInRoles()`, because derivation would re-admit `scribe` —
+   which `config.ValidRoles()` deliberately excludes as a mint-only dogfood
+   role — and would fail open for any future canonical role with no provider
+   pairing. A unit test asserts each row still matches
+   `mintcore.RolePermissionsFor`.
+3. **The generator writes what a per-repo install does not vendor.**
+   `policies/base.yaml`, and the providers and profiles the chosen role needs,
+   are written when absent and never overwritten. Providers are referenced by
+   path rather than bare name, because the embedded provider fallback fills in
+   only the OpenAI provider.
+4. **The result is validated in process.** Everything is rendered into a
+   scratch directory and loaded through the same loader dispatch uses, so a
+   harness that would fail validation never leaves a partially written
+   `.fullsend` behind.
+
+Templates are embedded with `go:embed`, matching how the repository already
+ships scaffold content.
+
+## Consequences
+
+- Creating a working custom agent becomes one command, and the three
+  silently-fatal mistakes above become generation-time errors with actionable
+  text. The Bring Your Own Agent guide keeps its hand-written path as the
+  explanation of what was generated.
+- Harness shape is now encoded in a second place. Mitigated but not
+  eliminated: the harness is built as a `harness.Harness` value and marshalled
+  rather than formatted as text, so the generator cannot emit a field the
+  validator does not know about; golden tests pin the generated bytes; and the
+  role table has a drift test against the mint. A new *required* harness field
+  would still need a matching change here, and the golden tests are what would
+  catch it.
+- `ValidateRunnerEnvWith` is not run at generation time — it requires every
+  `${VAR}` in the harness `env` blocks to be set in the calling process, which
+  is true in CI and false on a developer's machine — so an unset variable
+  still surfaces at `fullsend run`.
+- The default sandbox image digests are compiled in, so they are repinned by
+  hand on the same cadence as the fleet repin PRs. A golden test makes a repin
+  visible in review.
+- `fullsend lock` and `fullsend run` are unchanged and do not share the
+  generator's check helper: they interleave minting, runner-env validation and
+  `${VAR}` expansion between the same steps in different orders, so sharing one
+  helper would change their behaviour.
diff --git a/docs/architecture.md b/docs/architecture.md
index c7128f52dc..68b08f7cac 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -396,6 +396,7 @@ the inheritance model: fullsend defaults, then repo baseline (`config.base.yaml`
 - Runtime resolution: `fullsend run <name>` resolves agents in two tiers: (1) config entries from `OrgConfig.Agents` (highest priority), (2) runtime fallback to the `fullsend-ai/agents` repository for known first-party agents not in config. The agents-repo fallback is a transitional mechanism for the agent extraction; it will be removed once all users have migrated to config-driven registration (ADR 0058 Phase 5).
 - Config lookup: config entries are looked up directly via `findConfigAgentEntry`; the agents-repo fallback operates independently when the agent is not found in config. Builds on [ADR 0045](ADRs/0045-forge-portable-harness-schema.md) harness identity model.
 - CLI management: `fullsend agent add|list|set|update|remove` manages config entries and auto-pins URLs to a commit SHA with an integrity hash.
+- Agent generation: `fullsend agent new <name>` writes a complete custom agent — harness, agent definition, result schema, post-script, and the policy, providers and profiles a per-repo install does not vendor — validates it with the loader dispatch uses, and registers it through the `agent add` path above. A `trigger:` is mandatory, because a trigger-less harness registers and validates and is then silently never dispatched; `--role` is a closed table of the roles the hosted mint serves, so an unservable role fails locally rather than as a `403` at first dispatch ([ADR 0102](ADRs/0102-generate-custom-agents-from-the-cli.md)).
 
 **Open questions:**
 
diff --git a/docs/cli/agent.md b/docs/cli/agent.md
index 63a2b05822..47c6049d88 100644
--- a/docs/cli/agent.md
+++ b/docs/cli/agent.md
@@ -4,7 +4,7 @@ sidebar_label: fullsend agent
 
 # fullsend agent
 
-Manage agent registrations in fullsend config. Add, list, set (runtime, model, effort), update, and remove agents.
+Manage agents in fullsend config. Generate a new agent, add, list, set (runtime, model, effort), update, and remove agents.
 
 `agent add` and `agent update` fetch remote content and resolve GitHub URLs. Authentication is via `gh` CLI or `GH_TOKEN` environment variable.
 
@@ -12,12 +12,365 @@ Manage agent registrations in fullsend config. Add, list, set (runtime, model, e
 
 | Command | Description |
 |---------|-------------|
+| `fullsend agent new <name>` | Generate a complete custom agent and register it |
 | `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 set <name>` | Set an agent's runtime, model or effort |
 | `fullsend agent remove <name>` | Remove an agent from config |
 
+## `agent new`
+
+Generate a complete, valid, runnable custom agent and register it. Every file
+an agent needs is written for you; the only one you have to edit is the
+instructions the agent follows.
+
+```bash
+fullsend agent new lint-docs --fullsend-dir .fullsend \
+  --role triage --description "Check docs changes for broken links"
+```
+
+```
+  ✓ Created agent "lint-docs" in .fullsend
+  harness/lint-docs.yaml
+  agents/lint-docs.md
+  schemas/lint-docs-result.schema.json
+  scripts/post-lint-docs.sh
+  policies/base.yaml
+  providers/vertex-ai.yaml
+  providers/github-ro.yaml
+  profiles/fullsend-vertex-ai.yaml
+  profiles/fullsend-github-ro.yaml
+  ✓ Added agent "lint-docs"
+
+Next:
+  1. Fill in the marked sections of agents/lint-docs.md — that file is the agent's prompt.
+  2. Test locally:
+       fullsend run lint-docs --fullsend-dir .fullsend \
+         --target-repo . --env-file .env.local
+     .env.local needs GITHUB_ISSUE_URL, ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION
+     and GH_TOKEN. See docs/guides/user/running-agents-locally.md.
+  3. Commit .fullsend, then comment `/fs-lint-docs` on an issue or pull request to run it in CI.
+```
+
+The generated tree:
+
+```bash
+find .fullsend -type f | sort
+```
+
+```
+.fullsend/agents/lint-docs.md
+.fullsend/config.yaml
+.fullsend/harness/lint-docs.yaml
+.fullsend/policies/base.yaml
+.fullsend/profiles/fullsend-github-ro.yaml
+.fullsend/profiles/fullsend-vertex-ai.yaml
+.fullsend/providers/github-ro.yaml
+.fullsend/providers/vertex-ai.yaml
+.fullsend/schemas/lint-docs-result.schema.json
+.fullsend/scripts/post-lint-docs.sh
+```
+
+Only `agents/lint-docs.md` needs your attention — it is the agent's prompt and
+it ships with marked sections to fill in. Everything else is complete.
+
+### What gets written
+
+| File | Written | Overwritten by `--force` |
+|------|---------|--------------------------|
+| `harness/<name>.yaml` | always | yes |
+| `agents/<name>.md` | always | yes |
+| `schemas/<name>-result.schema.json` | always | yes |
+| `scripts/post-<name>.sh` (mode 0755) | always | yes |
+| `policies/base.yaml` | when absent | **no** |
+| `providers/*.yaml` (per role) | when absent | **no** |
+| `profiles/*.yaml` (per role) | when absent | **no** |
+| `scripts/validate-output-schema.sh` | with `--validation-loop`, when absent | **no** |
+| `config.yaml` `agents:` entry | unless `--no-register` | n/a |
+
+The policy, provider and profile files are shared by every agent in the
+directory, so they are never overwritten — including with `--force`.
+`fullsend github setup` does not copy these into your repository, which is why
+`agent new` writes them when they are absent.
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--fullsend-dir` | | Path to the `.fullsend` configuration directory (required) |
+| `-f`, `--file` | | Read the agent definition from a spec YAML file |
+| `--role` | `triage` | Mint role the agent runs as (see the table below) |
+| `--description` | `Custom <name> agent.` | One-line description; written to both the harness and the agent definition |
+| `--on` | `command:/fs-<name>` | Trigger preset; mutually exclusive with `--trigger` |
+| `--trigger` | | A trigger written by hand, in CEL (the expression language dispatch evaluates); mutually exclusive with `--on` |
+| `--model` | `opus` | Model for the agent |
+| `--effort` | `high` | Effort level (`low`, `medium`, `high`, `xhigh`, `max`) |
+| `--runtime` | | Agent runtime recorded in `config.yaml` (`claude`, `pi` or `codex`) |
+| `--slug` | `<owner>-<name>` | Names the GitHub App to look for when the agent is installed; `<owner>` comes from the `origin` remote |
+| `--image` | per-role pin | Container image the agent runs inside |
+| `--timeout-minutes` | `15` | Agent timeout in minutes |
+| `--validation-loop` | `false` | Add a `validation_loop` checking output against the schema |
+| `--no-register` | `false` | Write the files but do not touch `config.yaml` |
+| `--force` | `false` | Overwrite generated files (never shared assets) |
+| `--dry-run` | `false` | Validate and print what would be written, writing nothing |
+
+### Roles
+
+`--role` is not the agent's name. It decides which GitHub identity the agent
+acts as and what that identity may do.
+
+Agents do not carry long-lived credentials. At run time they ask a service
+called the **mint** for a short-lived GitHub token, and `role:` is what they
+ask for. The mint only issues tokens for roles it knows, so a role it does not
+serve fails at the first run rather than at generation time — which is why this
+command refuses an unknown one up front. The hosted mint serves these:
+
+| `--role` | Permissions | Providers |
+|----------|-------------|-----------|
+| `triage` (default) | `contents:read`, `issues:write`, `metadata:read` | vertex-ai, github-ro |
+| `review` | `contents:read`, `pull_requests:write`, `issues:write`, `checks:read`, `metadata:read` | vertex-ai, github-ro |
+| `coder` | `contents:write`, `packages:read`, `pull_requests:write`, `issues:write`, `checks:read`, `metadata:read` | vertex-ai, github |
+| `retro` | `actions:read`, `contents:read`, `pull_requests:write`, `issues:write`, `metadata:read` | vertex-ai, github-ro, github-artifacts |
+| `prioritize` | `contents:read`, `issues:write`, `organization_projects:write`, `metadata:read` | vertex-ai, github-ro |
+
+Pick the role whose permissions fit what the agent does. An unknown role fails
+immediately with this table, rather than returning `403` from the mint the
+first time the agent runs. To use a role the hosted mint does not serve, you
+need to run your own — see
+[Custom Agent Identity](../guides/user/custom-agent-identity.md).
+
+### Triggers
+
+A trigger is the rule that decides which GitHub events start the agent —
+a comment, a label, a new issue, a pull request. Every generated agent gets
+one, because an agent without a trigger is accepted everywhere and then simply
+never runs, with nothing reported anywhere to tell you why. `agent new`
+therefore refuses to write one without a trigger. `--on` takes a preset:
+
+| `--on` | Fires when |
+|--------|-----------|
+| `command:/<command>` (default `/fs-<name>`) | Someone comments the slash command on an issue, or on a pull request that is not from a fork |
+| `label:<label>` (default `<name>`) | The label is added |
+| `issue-opened` | A new issue is opened |
+| `pr-opened` | A non-fork pull request is opened, updated, or marked ready |
+
+The expressions these presets produce are exactly the ones written out in the
+[CEL Triggers Reference](../guides/user/cel-triggers-reference.md#common-trigger-patterns),
+and a test keeps the two identical. For anything the presets do not cover, pass
+`--trigger` with your own expression — it is compiled and checked before any
+file is written, so a mistake fails here rather than at the first event.
+
+Both `command:` and `pr-opened` refuse comments and pull requests from forks.
+That matters most for `--role coder`, which can write to the repository.
+
+### Spec files
+
+`-f` reads the same settings from a YAML document, so a local coding agent can
+produce one:
+
+```yaml
+version: "1"
+name: link-check
+role: review
+description: Check that links in changed docs resolve
+on: label:needs-link-check
+model: opus
+timeout_minutes: 20
+```
+
+```bash
+fullsend agent new -f link-check.agent.yaml --fullsend-dir .fullsend
+```
+
+```
+  ✓ Created agent "link-check" in .fullsend
+  harness/link-check.yaml
+  agents/link-check.md
+  schemas/link-check-result.schema.json
+  scripts/post-link-check.sh
+  policies/base.yaml  (already present, left unchanged)
+  providers/vertex-ai.yaml  (already present, left unchanged)
+  providers/github-ro.yaml  (already present, left unchanged)
+  profiles/fullsend-vertex-ai.yaml  (already present, left unchanged)
+  profiles/fullsend-github-ro.yaml  (already present, left unchanged)
+  ✓ Added agent "link-check"
+```
+
+Unknown keys are rejected rather than ignored, so a typo does not silently
+produce a different agent. Command-line flags override spec keys.
+
+### Checking the result
+
+`agent new` validates what it generates before it writes anything. To re-check
+later — after you have edited the harness by hand, for example — load it with
+the same loader dispatch uses:
+
+```bash
+fullsend lock lint-docs --fullsend-dir .fullsend --offline
+```
+
+```
+⚡ fullsend dev
+  Autonomous agentic development for Git-hosted organizations
+→ Locking dependencies: lint-docs
+
+  ✓ Harness has no remote dependencies — nothing to lock
+```
+
+`--offline` proves the agent needs no network. Note that `fullsend agent list`
+shows **registrations** and does not open harness files, so it is not a
+validity check:
+
+```bash
+fullsend agent list --fullsend-dir .fullsend
+```
+
+```
+NAME       SOURCE
+lint-docs  harness/lint-docs.yaml
+```
+
+Per-agent overrides compose on top of the generated harness:
+
+```bash
+fullsend agent set lint-docs --fullsend-dir .fullsend --model sonnet
+```
+
+```
+  ✓ Set agent "lint-docs": runtime="" model="sonnet" effort="" (empty = inherit)
+```
+
+To see what would be generated without writing anything, use `--dry-run`. It
+prints the file list and every rendered body:
+
+```bash
+fullsend agent new report --fullsend-dir .fullsend --dry-run
+```
+
+```
+    Dry run: would create agent "report" in .fullsend
+  harness/report.yaml
+  agents/report.md
+  schemas/report-result.schema.json
+  scripts/post-report.sh
+  policies/base.yaml  (already present, would be left unchanged)
+  ...
+    Nothing was written and no agent was registered
+```
+
+And to undo a generated registration:
+
+```bash
+fullsend agent remove link-check --fullsend-dir .fullsend
+```
+
+```
+  ✓ Removed agent "link-check"
+```
+
+`agent remove` unregisters the agent; the generated files stay on disk for you
+to delete or keep.
+
+### Running it
+
+Generation is step one. Fill in the marked sections of `agents/<name>.md`,
+then run it. A real run needs GCP credentials, a sandbox image, and the
+environment listed in
+[Running agents locally](../guides/user/running-agents-locally.md).
+
+You can exercise the whole pipeline without spending any inference by using
+the `dummy` runtime, which runs the real sandbox and the real post-script but
+replaces the model with a scripted result. Set `POST_<NAME>_DRY_RUN=1` so the
+post-script prints its comment instead of posting it:
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json
+POST_LINT_DOCS_DRY_RUN=1 \
+  GITHUB_ISSUE_URL="https://github.com/OWNER/REPO/pull/99" \
+  GH_TOKEN="$(gh auth token)" \
+  ANTHROPIC_VERTEX_PROJECT_ID=... CLOUD_ML_REGION=us-east5 \
+  fullsend run lint-docs --fullsend-dir .fullsend \
+    --runtime dummy --forge github --target-repo .
+```
+
+The tail of a successful run:
+
+```
+    Agent exit code: 0
+    Agent runs: 1
+
+  • Cleaning up sandbox
+  ✓ Sandbox deleted (45.7s)
+  • Running post-script: .fullsend/scripts/post-lint-docs.sh
+**2 broken links added in docs/**
+
+### Broken links
+
+- `docs/a.md:14` -> `../missing.md`
+- `docs/b.md:3` -> `/docs/gone.md`
+post-lint-docs: dry run, not posting
+  ✓ Post-script completed (0.1s)
+```
+
+With `--runtime claude`, the same agent against a real pull request — the
+model does the work, the schema gate runs, and the post-script still only
+prints:
+
+```
+  ✓ Extracted 1 output file(s)
+  • Running validation: .fullsend/scripts/validate-output-schema.sh
+  ✓ Validation passed: PASS: output validated against schema
+    Agent exit code: 0
+    Agent runs: 1
+    Validation: passed
+  • Running post-script: .fullsend/scripts/post-link-check.sh
+post-link-check: status=ok, nothing to post
+  ✓ Post-script completed (0.3s)
+```
+
+That run is the reference agent from
+[fullsend-ai/agents](https://github.com/fullsend-ai/agents) `examples/link-check/`,
+not the generated stub — the stub has sections still to fill in, so it has no
+work to do. Both runtimes exercise the same harness, sandbox, validation loop
+and post-script; only the agent's own reasoning differs.
+
+The `dummy` runtime reads a scripted result from
+`.fullsend/behaviour/current-scenario.yaml`; write one that produces
+`output/agent-result.json` to try this. That last block is the whole contract
+working: the sandbox started, the agent wrote its result, and the post-script
+found it and rendered the comment.
+
+Three things that stop a local run before it starts, all of them easy to hit:
+
+- `--forge github` is required. Without it no forge overlay applies, so the
+  environment the harness expects is never assembled.
+- `GOOGLE_APPLICATION_CREDENTIALS` must point at a real file. The harness
+  copies it into the sandbox, so the run fails validation without it — even
+  under `dummy`, which does no inference.
+- `GH_TOKEN` must be a real token. A GitHub connectivity check runs before the
+  agent, and a placeholder fails it with `Bad credentials (HTTP 401)`.
+
+In CI, commit `.fullsend/` and fire the agent with whatever its trigger
+describes — for the default preset, comment `/fs-<name>` on an issue or pull
+request.
+
+### Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `unknown role "scribe"` followed by the role table | The role is not one the hosted mint serves | Use one of the five listed; for a custom role see [Custom Agent Identity](../guides/user/custom-agent-identity.md) |
+| `agent name "..." contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)` | The name would not be safe to interpolate into a shell script | Rename. Nothing is written when this fires |
+| `these files already exist:` followed by a list | An agent of that name was already generated | Pick another name, or pass `--force`. `--force` never overwrites `policies/`, `providers/` or `profiles/` |
+| `agent "..." already exists in config` | The name is registered in `config.yaml` | `fullsend agent remove <name>` first. `--force` deliberately does not override this |
+| `trigger does not compile: ERROR: <input>:1:5: Syntax error: ...` | A `--trigger` expression is not valid CEL, or does not return a boolean | Compare against the `--on` presets above |
+| `unknown --on preset "..."` followed by the preset list | `--on` is not one of the four presets | Use a listed preset, or pass raw CEL with `--trigger` |
+| `a trigger is required: pass --on with a preset, or --trigger` | `--trigger ""` was passed explicitly | Give a real trigger. A trigger-less agent is silently never dispatched |
+| `fullsend dir ... does not exist; run ` + "`fullsend github setup`" + ` first` | `--fullsend-dir` points at nothing | Scaffold the repo first |
+| `validating files: policy: stat .../policies/base.yaml: no such file or directory` | A hand-edited harness references a file that is not there | Re-run `agent new`, which writes the policy when absent |
+| Agent crashes at 0s in CI | The sandbox cannot reach Vertex — a provider or profile file is missing | Confirm `providers/` and `profiles/` exist next to the harness |
+| `runner env ... is not set` at `fullsend run` | A `${VAR}` in the harness `env` block is unset | `agent new` does not check host variables at generation time; supply them via `--env-file` locally or the workflow `env:` block in CI |
+
 ## `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. When a URL references a branch or tag (rather than a commit SHA), the original ref is stored in the config entry's `ref` field so that subsequent `agent update` calls re-resolve against the same branch. The URL prefix is added to `allowed_remote_resources` if not already present.
diff --git a/docs/guides/dev/cli-internals.md b/docs/guides/dev/cli-internals.md
index 01d7ef0c55..d3409f520b 100644
--- a/docs/guides/dev/cli-internals.md
+++ b/docs/guides/dev/cli-internals.md
@@ -87,7 +87,16 @@ fullsend
 │   │   ├── --json                           #   Emit JSON output instead of table
 │   │   ├── --repo <owner/repo>              #   Filter to specific repos (repeatable)
 │   │   └── --concurrency <int>              #   Max parallel API calls (default: 8)
-├── agent                                    # Manage agent registrations in config
+├── agent                                    # Generate and manage agents in config
+│   ├── new          <name>                   # Generate a complete custom agent and register it
+│   │   ├── --role <name>                    #   Mint role: triage|review|coder|retro|prioritize
+│   │   ├── --on <preset>                    #   Trigger preset (command:/label:/issue-opened/pr-opened)
+│   │   ├── --trigger <cel>                  #   Raw CEL trigger (mutually exclusive with --on)
+│   │   ├── -f, --file <spec.yaml>           #   Read the agent definition from a spec file
+│   │   ├── --validation-loop                #   Add a schema validation_loop
+│   │   ├── --no-register                    #   Write files without touching config.yaml
+│   │   ├── --force                          #   Overwrite generated files (never shared assets)
+│   │   └── --dry-run                        #   Validate and print, writing nothing
 │   ├── add          <url-or-path>            # Register an agent (URL auto-pinned)
 │   ├── list                                  # List registered agents
 │   ├── set          <name>                   # Set an agent's runtime, model or effort (per-repo)
diff --git a/docs/guides/getting-started/operations.md b/docs/guides/getting-started/operations.md
index 4e2e7d8b55..ab6beed350 100644
--- a/docs/guides/getting-started/operations.md
+++ b/docs/guides/getting-started/operations.md
@@ -116,6 +116,7 @@ For organizations that separate GCP and GitHub responsibilities across teams, fu
 | Fleet Admin | `fullsend repos status` | Compare manifest against actual per-repo state: detect missing or drifted components, ref drift, and scaffold content drift |
 | Fleet Admin | `fullsend repos set-default <key> <value>` | Set or remove a platform-level default in the manifest |
 
+| Developer | `fullsend agent new <name>` | Generate a complete custom agent and register it |
 | Developer | `fullsend agent add <url-or-path>` | Register an agent in config (URL auto-pinned to commit SHA) |
 | Developer | `fullsend agent list` | List registered agents and their sources |
 | Developer | `fullsend agent set <name>` | Set an agent's runtime, model or effort |
diff --git a/docs/guides/user/bring-your-own-agent.md b/docs/guides/user/bring-your-own-agent.md
index 07e506d0f1..2b957ac99a 100644
--- a/docs/guides/user/bring-your-own-agent.md
+++ b/docs/guides/user/bring-your-own-agent.md
@@ -14,6 +14,58 @@ This guide uses the [fullsend-ai/agents](https://github.com/fullsend-ai/agents)
 
 ## Overview
 
+Building a custom agent takes four steps. `fullsend agent new` does the
+first one, which is most of the work:
+
+0. **Generate the skeleton** with `fullsend agent new`. It writes every file
+   an agent needs — how it runs, what it is allowed to do, which events start
+   it, and what happens to its output — and registers it. See below.
+1. **Write the instructions the agent follows.** This is the one file the
+   generator cannot fill in for you, because it is the actual job.
+2. **Test locally** with `fullsend run`. See [Testing locally](#testing-locally).
+3. **Commit and trigger it in CI.**
+
+The rest of this guide explains what step 0 generated, names each file, and
+shows how to change it. Read it when you need to go beyond the defaults, or if
+you would rather write everything yourself — the
+[four steps by hand](#the-four-steps-by-hand) below are the long form.
+
+### Step 0: generate the skeleton
+
+First complete [Before you begin](#before-you-begin) — `agent new` needs the
+fullsend CLI on your PATH and a repository you have already run
+`fullsend github setup` on. Actually running the agent afterwards needs the
+inference and GitHub App setup listed there too.
+
+Then [`fullsend agent new`](../../cli/agent.md#agent-new) writes a complete,
+valid, registered agent from a name and a role, so you edit prose rather than
+plumbing:
+
+```bash
+fullsend agent new lint-docs --fullsend-dir .fullsend \
+  --role triage --description "Check docs changes for broken links"
+```
+
+```
+  ✓ Created agent "lint-docs" in .fullsend
+  harness/lint-docs.yaml
+  agents/lint-docs.md
+  schemas/lint-docs-result.schema.json
+  scripts/post-lint-docs.sh
+  policies/base.yaml
+  providers/vertex-ai.yaml
+  providers/github-ro.yaml
+  profiles/fullsend-vertex-ai.yaml
+  profiles/fullsend-github-ro.yaml
+  ✓ Added agent "lint-docs"
+```
+
+That covers steps 1, 2 and 4 of the by-hand sequence below. Fill in the marked
+sections of `agents/lint-docs.md`, then go to
+[Testing locally](#testing-locally).
+
+### The four steps, by hand
+
 Building and deploying a custom agent takes four steps:
 
 1. **Create the harness and agent definition** — write a harness YAML file that defines _how_ the agent runs and a Markdown file that defines _what_ it does. See [Minimum viable agent](#minimum-viable-agent).
@@ -24,7 +76,7 @@ Building and deploying a custom agent takes four steps:
 ## Before you begin
 
 - **fullsend CLI** installed and available on your PATH.
-- **Repository scaffolded.** Run [`fullsend github setup`](../getting-started/configuring-github.md) first — it creates the `.fullsend/` directory with `policies/`, `providers/`, and `profiles/` from the scaffold. For a standalone agent repo, you can create these files manually (see [Minimum viable agent](#minimum-viable-agent)).
+- **Repository scaffolded.** Run [`fullsend github setup`](../getting-started/configuring-github.md) first — it creates `.fullsend/config.yaml` and the dispatch workflow. Note that a per-repo install does **not** vendor `policies/`, `providers/` or `profiles/` into the repository; [`fullsend agent new`](#step-0-generate-the-skeleton) writes the ones your agent needs, and CI layers providers in at run time. If you are writing a harness by hand, create them yourself (see [Minimum viable agent](#minimum-viable-agent)).
 - **GCP inference provisioned (CI only).** For agents running in GitHub Actions, run [`fullsend inference provision`](../../cli/inference.md) to set up Workload Identity Federation.
 - **GitHub Apps installed (CI only).** Your org needs the fullsend GitHub Apps — see [Configuring GitHub](../getting-started/configuring-github.md).
 
@@ -68,7 +120,7 @@ For local development and debugging, you can also run an agent directly with `fu
 
 ## Minimum viable agent
 
-You need a harness, an agent definition, and supporting scaffold files. If your repo was set up with `fullsend github setup`, the `.fullsend/` directory already contains `policies/`, `providers/`, and `profiles/` from the scaffold — you only need to add `harness/my-agent.yaml` and `agents/my-agent.md`. For a standalone agent repo, copy the scaffold files or create the full layout:
+You need a harness, an agent definition, and supporting scaffold files. [`fullsend agent new`](#step-0-generate-the-skeleton) writes all of them for you; the layout below is what it produces, and what you need to create by hand if you are building a harness from scratch. A per-repo install does not vendor `policies/`, `providers/` or `profiles/`, so a hand-written agent must supply them:
 
 ```
 .fullsend/
@@ -359,6 +411,8 @@ allowed_remote_resources:
 |---------|-----|
 | `API Error: Error code policy_denied` on the first model call (agent exits after ~2 s, 0 tokens) | The sandbox gateway denied the agent's *binary*, not the model. Check your profile's `binaries:` list has both `**/claude` and `**/claude.exe` (Claude Code 2.1.2xx runs as `claude.exe`). To see exactly which binary was denied: `grep DENIED <run-dir>/logs/openshell-sandbox.log` — see [Debugging network policies locally](running-agents-locally.md#debugging-network-policies-locally) |
 | Agent crashes at 0s | Sandbox can't reach Vertex AI — verify that `providers/vertex-ai.yaml` is listed in your harness `providers:` and that `ANTHROPIC_VERTEX_PROJECT_ID`/`CLOUD_ML_REGION` are set (in your `--env-file` for local runs, or in the workflow `env` block for CI) |
+| `unknown role "..."` from `agent new` | The hosted mint serves five roles — see the table in [`agent new`](../../cli/agent.md#roles); for a custom role see [Custom Agent Identity](custom-agent-identity.md) |
+| Agent never fires, no error anywhere | The harness has no `trigger:`. A trigger-less agent registers and validates but is silently skipped by dispatch — `fullsend agent new` always writes one |
 | "role field is required" | Add `role:` to harness |
 | `403` / "role not allowed" from the mint | Your `role:` is not one the mint serves. On the hosted mint use a built-in role (`triage`, `coder`, `review`, `retro`, `prioritize`, `fullsend`); for a custom role, point `FULLSEND_MINT_URL` at your own mint — see [Custom Agent Identity](custom-agent-identity.md) |
 | Agent can't find input files | Pre-script output paths must match `host_files` entries |
diff --git a/docs/guides/user/building-custom-agents.md b/docs/guides/user/building-custom-agents.md
index 7b0935bd83..82546a33f7 100644
--- a/docs/guides/user/building-custom-agents.md
+++ b/docs/guides/user/building-custom-agents.md
@@ -1,8 +1,10 @@
 # Building custom agents from scratch
 
-> **Note:** For new custom agents, register them in `config.yaml` with a
-> local `source:` path instead of the patterns shown below. See
-> [Bring Your Own Agent](bring-your-own-agent.md) for the recommended approach.
+> **Note:** For new custom agents, run
+> [`fullsend agent new <name>`](../../cli/agent.md#agent-new) — it generates a
+> complete, valid, registered agent and is the recommended starting point. See
+> [Bring Your Own Agent](bring-your-own-agent.md) for the full workflow. The
+> patterns below are retained for understanding an existing hand-written agent.
 
 This guide walks through creating a custom from-scratch agent on a per-repo
 fullsend installation.
diff --git a/docs/guides/user/cel-triggers-reference.md b/docs/guides/user/cel-triggers-reference.md
index 92163e32cc..68916bdc4e 100644
--- a/docs/guides/user/cel-triggers-reference.md
+++ b/docs/guides/user/cel-triggers-reference.md
@@ -98,17 +98,32 @@ trigger: >
     && event.transition.label.action == "added"
 ```
 
-**Run on a slash command (on a PR, non-fork):**
+**Run on a slash command (issues and non-fork PRs):**
 ```yaml
 trigger: >
   event.transition.kind == "comment_added"
+    && event.entity.kind == "work_item"
     && has(event.transition.comment.command)
     && event.transition.comment.command == "/my-command"
-    && event.entity.kind == "work_item"
-    && event.state.change_proposal != null
-    && !event.state.change_proposal.is_fork
+    && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
 ```
 
+This is exactly what [`fullsend agent new --on command:/my-command`](../../cli/agent.md#agent-new)
+emits, so a generated trigger and a hand-written one stay the same expression.
+
+`event.entity.kind == "work_item"` restricts this to issues and pull requests.
+A comment on a GitHub Discussion arrives with `entity.kind` of `conversation`,
+so without that clause the agent also fires on discussions.
+
+Use `!has(...)` rather than `!= null` for the fork guard. `state.change_proposal`
+is **absent** on a comment posted to a plain issue, not present-and-null — the
+[NormalizedEvent schema](../../normative/normalized-event/v1/normalized-event.schema.json)
+requires only `labels` under `state`. Comparing an absent key against `null`
+raises a missing-key error, and dispatch reports that as
+`::error:: harness dispatch: skipping agent <name>: trigger eval failed` on
+**every** issue comment in the repository, so the agent looks permanently
+broken. The `!has(...)` form evaluates cleanly on both surfaces.
+
 **Run when a PR is opened or updated (non-fork):**
 ```yaml
 trigger: >
diff --git a/docs/guides/user/customizing-agents.md b/docs/guides/user/customizing-agents.md
index c62043673b..665f817e3a 100644
--- a/docs/guides/user/customizing-agents.md
+++ b/docs/guides/user/customizing-agents.md
@@ -8,6 +8,8 @@ disabling agents.
 For a quick overview of all customization options, see
 [Customizing Agents](customizing-overview.md). For the complete harness field
 reference, see [Harness Field Reference](../../reference/harness-reference.md).
+To create a new agent rather than configure an existing one, start with
+[`fullsend agent new`](../../cli/agent.md#agent-new).
 
 ## What you can configure
 
diff --git a/docs/guides/user/customizing-with-skills.md b/docs/guides/user/customizing-with-skills.md
index 06f7b16274..5c7a0b1be4 100644
--- a/docs/guides/user/customizing-with-skills.md
+++ b/docs/guides/user/customizing-with-skills.md
@@ -189,6 +189,8 @@ Bring Your Own Agent covers the same decision frame in
 
 ## See also
 
+- [`fullsend agent new`](../../cli/agent.md#agent-new) — generate a custom agent that can then mount these skills
+
 - [Customizing Agents](customizing-overview.md) — overview of all customization approaches
 - [Bring Your Own Agent](bring-your-own-agent.md) — building, registering, and
   [tuning existing agents](customizing-agents.md#tuning-agents-with-augmentation-skills)
diff --git a/internal/agentnew/assets.go b/internal/agentnew/assets.go
new file mode 100644
index 0000000000..422a8aa9c3
--- /dev/null
+++ b/internal/agentnew/assets.go
@@ -0,0 +1,55 @@
+package agentnew
+
+import (
+	"fmt"
+
+	"github.com/fullsend-ai/fullsend/internal/scaffold"
+)
+
+// sharedAssets returns the scaffold files a generated agent depends on but
+// does not own: the sandbox policy, the role's providers and profiles, and
+// the schema validator when the validation loop is enabled.
+//
+// These are written only when absent and are never overwritten, because they
+// are shared by every agent in the directory. They are needed at all because
+// a per-repo install vendors none of them: CollectPerRepoInstallFiles returns
+// only the shim workflow and one thin caller, and CI's workspace layering
+// skips policies/ (the embedded scaffold has no policies/ directory, so the
+// [[ -d ]] guard fails) and never had profiles/ in LAYERED_DIRS at all.
+//
+// The bytes come from the existing scaffold embed wherever possible, so a
+// generated tree is byte-identical to what CI layers in and to what the
+// fleet runs.
+func sharedAssets(role Role, validationLoop bool) ([]File, error) {
+	files := []File{}
+
+	policy, err := templates.ReadFile("templates/policies/base.yaml")
+	if err != nil {
+		return nil, fmt.Errorf("reading base policy: %w", err)
+	}
+	files = append(files, File{Path: "policies/base.yaml", Data: policy, Mode: 0o644, Shared: true})
+
+	// Providers and profiles are referenced by path rather than by bare
+	// name. A bare name with no definition on disk does not fail loudly: the
+	// embedded provider fallback fills in only the OpenAI provider, so every
+	// other name degrades to a warning and then a sandbox that cannot reach
+	// Vertex — the "agent crashes at 0s" symptom in the BYOA guide.
+	for _, path := range append(append([]string{}, role.Providers...), role.Profiles...) {
+		data, err := scaffold.FullsendRepoFile(path)
+		if err != nil {
+			return nil, fmt.Errorf("reading %s from the embedded scaffold: %w", path, err)
+		}
+		files = append(files, File{Path: path, Data: data, Mode: 0o644, Shared: true})
+	}
+
+	if validationLoop {
+		script, err := templates.ReadFile("templates/scripts/validate-output-schema.sh")
+		if err != nil {
+			return nil, fmt.Errorf("reading validation script: %w", err)
+		}
+		files = append(files, File{
+			Path: "scripts/validate-output-schema.sh", Data: script, Mode: 0o755, Shared: true,
+		})
+	}
+	return files, nil
+}
diff --git a/internal/agentnew/checkgenerated_test.go b/internal/agentnew/checkgenerated_test.go
new file mode 100644
index 0000000000..69d05c97f3
--- /dev/null
+++ b/internal/agentnew/checkgenerated_test.go
@@ -0,0 +1,115 @@
+package agentnew
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+// loadAndCheck mirrors what the command does after writing the tree.
+func loadAndCheck(t *testing.T, dir, name string) ([]harness.Diagnostic, error) {
+	t.Helper()
+	h, err := harness.Load(filepath.Join(dir, "harness", name+".yaml"))
+	if err != nil {
+		return nil, err
+	}
+	return harness.CheckGenerated(h, dir)
+}
+
+func generateInto(t *testing.T, dir string, opts Options) {
+	t.Helper()
+	files, err := Render(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	writeTree(t, dir, files)
+}
+
+func TestCheckGeneratedAcceptsAFreshTree(t *testing.T) {
+	for _, role := range RoleNames() {
+		t.Run(role, func(t *testing.T) {
+			dir := t.TempDir()
+			generateInto(t, dir, testOptions("lint-docs", role))
+			diags, err := loadAndCheck(t, dir, "lint-docs")
+			if err != nil {
+				t.Fatalf("freshly generated tree failed CheckGenerated: %v", err)
+			}
+			if len(diags) != 0 {
+				t.Errorf("unexpected lint diagnostics: %v", diags)
+			}
+		})
+	}
+}
+
+// TestCheckGeneratedCatchesMissingResources is the reason the fourth step
+// exists. ValidateFilesExist skips providers and profiles on purpose, so
+// without validateResourceFilesExist a missing one is invisible until run
+// time. Each file is deleted individually and the error must name it.
+func TestCheckGeneratedCatchesMissingResources(t *testing.T) {
+	role, err := LookupRole("retro") // the role with the most resources
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, victim := range append(append([]string{}, role.Providers...), role.Profiles...) {
+		t.Run(victim, func(t *testing.T) {
+			dir := t.TempDir()
+			opts := testOptions("lint-docs", "retro")
+			generateInto(t, dir, opts)
+
+			if err := os.Remove(filepath.Join(dir, victim)); err != nil {
+				t.Fatal(err)
+			}
+			_, err := loadAndCheck(t, dir, "lint-docs")
+			if err == nil {
+				t.Fatalf("deleting %s was not detected", victim)
+			}
+			if !strings.Contains(err.Error(), filepath.Base(victim)) {
+				t.Errorf("error should name the missing file %q, got: %v", victim, err)
+			}
+		})
+	}
+}
+
+// TestCheckGeneratedCatchesMissingOwnedFiles covers the #6834 class: a
+// policy:, agent: or post_script: pointing at a file that is not there.
+func TestCheckGeneratedCatchesMissingOwnedFiles(t *testing.T) {
+	for _, victim := range []string{
+		"policies/base.yaml",
+		"agents/lint-docs.md",
+		"scripts/post-lint-docs.sh",
+	} {
+		t.Run(victim, func(t *testing.T) {
+			dir := t.TempDir()
+			generateInto(t, dir, testOptions("lint-docs", "triage"))
+			if err := os.Remove(filepath.Join(dir, victim)); err != nil {
+				t.Fatal(err)
+			}
+			_, err := loadAndCheck(t, dir, "lint-docs")
+			if err == nil {
+				t.Fatalf("deleting %s was not detected", victim)
+			}
+		})
+	}
+}
+
+// TestCheckGeneratedCatchesMissingSchema: with the validation loop on, the
+// schema is a validated file too.
+func TestCheckGeneratedCatchesMissingSchema(t *testing.T) {
+	dir := t.TempDir()
+	opts := testOptions("lint-docs", "triage")
+	opts.ValidationLoop = true
+	generateInto(t, dir, opts)
+
+	if _, err := loadAndCheck(t, dir, "lint-docs"); err != nil {
+		t.Fatalf("tree with --validation-loop should be valid: %v", err)
+	}
+	if err := os.Remove(filepath.Join(dir, "schemas", "lint-docs-result.schema.json")); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := loadAndCheck(t, dir, "lint-docs"); err == nil {
+		t.Fatal("deleting the schema was not detected")
+	}
+}
diff --git a/internal/agentnew/generate.go b/internal/agentnew/generate.go
new file mode 100644
index 0000000000..6890fecc57
--- /dev/null
+++ b/internal/agentnew/generate.go
@@ -0,0 +1,401 @@
+package agentnew
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+// ValidateFullsendDir reports whether fullsendDir is usable as a target.
+// Exported so a caller can fail with this message before running any other
+// check, rather than reporting a missing directory as some downstream error.
+func ValidateFullsendDir(fullsendDir string) error {
+	absDir, err := filepath.Abs(fullsendDir)
+	if err != nil {
+		return fmt.Errorf("resolving fullsend dir: %w", err)
+	}
+	// Lstat, not Stat: a symlink AT the root would be followed, and every
+	// path check below is relative to it — so a repository that ships
+	// .fullsend as a symlink could redirect every generated file outside
+	// the tree, which the per-segment check cannot see because it only
+	// walks segments beneath this directory.
+	info, err := os.Lstat(absDir)
+	if err != nil {
+		return fmt.Errorf("fullsend dir %s does not exist; run `fullsend github setup` first", fullsendDir)
+	}
+	if info.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("fullsend dir %s is a symlink; refusing to write through it", fullsendDir)
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("fullsend dir %s is not a directory", fullsendDir)
+	}
+	return nil
+}
+
+// Result describes what Generate did, so the caller can print next steps and
+// tests can assert on it without reparsing output.
+type Result struct {
+	// Written lists the files created, in generation order. On a dry run it
+	// lists what would have been created.
+	Written []string
+	// Rendered carries the same files with their bodies, for --dry-run.
+	Rendered []File
+	// SkippedShared lists shared scaffold assets that were already present
+	// and therefore left alone.
+	SkippedShared []string
+	// Diagnostics are non-fatal lint warnings from the generated harness.
+	Diagnostics []harness.Diagnostic
+	// HarnessPath is the generated harness, relative to the fullsend dir.
+	HarnessPath string
+}
+
+// Generate renders an agent, validates it, and writes it into fullsendDir.
+//
+// Ordering matters and is the reason this is not a straight loop of writes:
+// everything is rendered and validated against a temporary tree first, so a
+// harness that would fail validation never leaves a half-written .fullsend
+// directory behind. Options must already have passed Validate.
+func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, error) {
+	absDir, err := filepath.Abs(fullsendDir)
+	if err != nil {
+		return nil, fmt.Errorf("resolving fullsend dir: %w", err)
+	}
+	if err := ValidateFullsendDir(fullsendDir); err != nil {
+		return nil, err
+	}
+
+	files, err := Render(opts)
+	if err != nil {
+		return nil, err
+	}
+
+	// Collisions are checked before anything is written. --force overwrites
+	// the four files this agent owns, but never a shared scaffold asset:
+	// those belong to every agent in the directory.
+	//
+	// Lstat, not Stat: a symlink at a destination — or at any directory
+	// leading to one — would otherwise be followed, and a repository that
+	// ships a `.fullsend/harness` symlink could redirect a generated file
+	// outside the fullsend directory entirely.
+	var collisions []string
+	writable := make([]File, 0, len(files))
+	result := &Result{HarnessPath: filepath.Join("harness", opts.Name+".yaml")}
+	for _, f := range files {
+		if err := checkNoSymlinks(absDir, f.Path); err != nil {
+			return nil, err
+		}
+		info, statErr := os.Lstat(filepath.Join(absDir, f.Path))
+		exists := statErr == nil
+		if exists && !info.Mode().IsRegular() {
+			return nil, fmt.Errorf("%s exists and is not a regular file; refusing to write it", f.Path)
+		}
+		switch {
+		case exists && f.Shared:
+			result.SkippedShared = append(result.SkippedShared, f.Path)
+		case exists && !force:
+			collisions = append(collisions, f.Path)
+		default:
+			writable = append(writable, f)
+		}
+	}
+	if len(collisions) > 0 {
+		sort.Strings(collisions)
+		return nil, fmt.Errorf("these files already exist:\n  %s\n\nPass --force to overwrite them, or pick another agent name",
+			strings.Join(collisions, "\n  "))
+	}
+
+	if err := validateInTempTree(absDir, opts, files, result); err != nil {
+		return nil, err
+	}
+
+	// Planned before the write loop so --dry-run can report exactly what a
+	// real run would create, including the rendered bodies.
+	for _, f := range writable {
+		result.Written = append(result.Written, f.Path)
+		result.Rendered = append(result.Rendered, f)
+	}
+	if dryRun {
+		return result, nil
+	}
+
+	// Undo log for a failure part-way through, which would otherwise leave a
+	// partial agent behind: some files present, the harness perhaps missing,
+	// and nothing registered. Under --force some destinations already exist,
+	// and deleting those would be worse than the failure — the user would
+	// lose a working agent definition — so their original bytes are kept and
+	// restored instead.
+	type undo struct {
+		path     string
+		existed  bool
+		original []byte
+		mode     os.FileMode
+	}
+	var written []undo
+	rollback := func() {
+		for i := len(written) - 1; i >= 0; i-- {
+			u := written[i]
+			if u.existed {
+				_ = os.WriteFile(u.path, u.original, u.mode)
+				continue
+			}
+			_ = os.Remove(u.path)
+		}
+	}
+
+	for _, f := range writable {
+		path := filepath.Join(absDir, f.Path)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			rollback()
+			return nil, fmt.Errorf("creating %s: %w", filepath.Dir(f.Path), err)
+		}
+
+		entry := undo{path: path, mode: os.FileMode(f.Mode)}
+		if prior, statErr := os.Stat(path); statErr == nil {
+			original, readErr := os.ReadFile(path)
+			if readErr != nil {
+				rollback()
+				return nil, fmt.Errorf("reading the existing %s before overwriting it: %w", f.Path, readErr)
+			}
+			entry.existed = true
+			entry.original = original
+			entry.mode = prior.Mode().Perm()
+		}
+
+		// Written directly rather than renamed in from the temp tree: a
+		// rename across filesystems fails, and the bytes are already here.
+		if err := writeFile(path, f.Data, os.FileMode(f.Mode)); err != nil {
+			rollback()
+			return nil, fmt.Errorf("writing %s: %w", f.Path, err)
+		}
+		// os.WriteFile does not change the mode of a file that already
+		// exists, so an overwritten post-script would keep whatever bits it
+		// had — including no execute bit, which the runner needs.
+		if err := os.Chmod(path, os.FileMode(f.Mode)); err != nil {
+			rollback()
+			return nil, fmt.Errorf("setting the mode on %s: %w", f.Path, err)
+		}
+		written = append(written, entry)
+	}
+	return result, nil
+}
+
+// writeFile is os.WriteFile, indirected so a test can inject a failure
+// part-way through the write loop and assert the rollback.
+var writeFile = os.WriteFile
+
+// checkNoSymlinks refuses a destination whose final component, or any parent
+// between the fullsend directory and it, is a symlink. Called before any
+// write, so a rejected path leaves the directory untouched.
+func checkNoSymlinks(absDir, relPath string) error {
+	current := absDir
+	for _, segment := range strings.Split(filepath.ToSlash(relPath), "/") {
+		current = filepath.Join(current, segment)
+		info, err := os.Lstat(current)
+		if err != nil {
+			if errors.Is(err, os.ErrNotExist) {
+				// Nothing here yet: neither this segment nor anything below
+				// it can be a symlink.
+				return nil
+			}
+			return fmt.Errorf("checking %s: %w", relPath, err)
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("refusing to write through a symlink: %s",
+				strings.TrimPrefix(current, absDir+string(filepath.Separator)))
+		}
+	}
+	return nil
+}
+
+// validateInTempTree writes the rendered files to a scratch directory and
+// runs the generated harness through the real loader there.
+//
+// Where a shared asset already exists in the target, the target's copy is
+// validated rather than the embedded one, so the check reflects what the
+// agent will actually run against — a hand-edited policies/base.yaml is
+// common and its content matters.
+func validateInTempTree(absDir string, opts Options, files []File, result *Result) error {
+	tmp, err := os.MkdirTemp("", "fullsend-agent-new-")
+	if err != nil {
+		return fmt.Errorf("creating scratch directory: %w", err)
+	}
+	defer os.RemoveAll(tmp)
+
+	for _, f := range files {
+		data := f.Data
+		if f.Shared {
+			// Validate against what is actually on disk, not the embedded
+			// copy: a hand-edited policy is common and its content matters.
+			// An existing-but-unreadable asset — a directory in its place,
+			// or bad permissions — must fail naming the path rather than
+			// silently validating a copy that will not be the one used.
+			target := filepath.Join(absDir, f.Path)
+			existing, readErr := os.ReadFile(target)
+			switch {
+			case readErr == nil:
+				data = existing
+			case errors.Is(readErr, os.ErrNotExist):
+				// Not there yet; this run writes it.
+			default:
+				return fmt.Errorf("reading the existing %s: %w", f.Path, readErr)
+			}
+		}
+		path := filepath.Join(tmp, f.Path)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			return fmt.Errorf("preparing scratch directory: %w", err)
+		}
+		if err := os.WriteFile(path, data, os.FileMode(f.Mode)); err != nil {
+			return fmt.Errorf("preparing scratch directory: %w", err)
+		}
+	}
+
+	h, err := harness.Load(filepath.Join(tmp, "harness", opts.Name+".yaml"))
+	if err != nil {
+		return fmt.Errorf("the generated harness is not valid — this is a bug in `fullsend agent new`: %w", err)
+	}
+	diags, err := harness.CheckGenerated(h, tmp)
+	result.Diagnostics = diags
+	if err != nil {
+		return fmt.Errorf("the generated agent did not validate — this is a bug in `fullsend agent new`: %w", err)
+	}
+	return nil
+}
+
+// DeriveSlug builds the default harness slug from the repository owner.
+// The slug is install-time App discovery only — the mint never reads it —
+// so falling back to a constant is safe, but the fallback is reported so the
+// user can pass --slug if they care.
+func DeriveSlug(name string, owner string) string {
+	if owner == "" {
+		owner = "fullsend"
+	}
+	return owner + "-" + name
+}
+
+// RepoOwner returns the owner segment of the origin remote in gitDir's
+// repository, or "" when it cannot be determined.
+type RepoOwner func(dir string) string
+
+// GitConfigOwner walks up from dir looking for a repository, and returns the
+// owner segment of its origin remote. Pass an absolute path: the walk stops
+// when filepath.Dir stops changing, which for a relative path is ".", so a
+// relative one can never ascend above the process working directory. Returns "" when there is no repository,
+// no origin, or an owner that would not be a valid slug segment.
+func GitConfigOwner(dir string) string {
+	for depth := 0; depth < 20; depth++ {
+		if cfg, ok := readGitConfig(dir); ok {
+			return ownerFromGitConfig(cfg)
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			return ""
+		}
+		dir = parent
+	}
+	return ""
+}
+
+// readGitConfig reads the config of the repository whose .git lives directly
+// in dir. In a linked worktree .git is a FILE containing "gitdir: <path>"
+// rather than a directory, and the config lives in the main repository's
+// common directory — so a naive dir/.git/config read finds nothing. Worktrees
+// are the normal way to work in this project, so that path matters.
+func readGitConfig(dir string) (string, bool) {
+	dotGit := filepath.Join(dir, ".git")
+	info, err := os.Stat(dotGit)
+	if err != nil {
+		return "", false
+	}
+
+	gitDir := dotGit
+	if !info.IsDir() {
+		pointer, readErr := os.ReadFile(dotGit)
+		if readErr != nil {
+			return "", false
+		}
+		rest, found := strings.CutPrefix(strings.TrimSpace(string(pointer)), "gitdir:")
+		if !found {
+			return "", false
+		}
+		gitDir = strings.TrimSpace(rest)
+		if !filepath.IsAbs(gitDir) {
+			gitDir = filepath.Join(dir, gitDir)
+		}
+		// <main>/.git/worktrees/<name> — config lives two levels up, in the
+		// main repository's .git directory.
+		if commonDir, commonErr := os.ReadFile(filepath.Join(gitDir, "commondir")); commonErr == nil {
+			common := strings.TrimSpace(string(commonDir))
+			if !filepath.IsAbs(common) {
+				common = filepath.Join(gitDir, common)
+			}
+			gitDir = filepath.Clean(common)
+		}
+	}
+
+	data, err := os.ReadFile(filepath.Join(gitDir, "config"))
+	if err != nil {
+		return "", false
+	}
+	return string(data), true
+}
+
+func ownerFromGitConfig(cfg string) string {
+	inOrigin := false
+	for _, line := range strings.Split(cfg, "\n") {
+		trimmed := strings.TrimSpace(line)
+		// Reset on ANY section header, not just [remote ...]. An origin
+		// section with no url line — a pushurl-only or insteadOf remote —
+		// would otherwise leave this true, and the next url anywhere in the
+		// file (a [submodule ...] one, say) would be read as origin's.
+		if strings.HasPrefix(trimmed, "[") {
+			inOrigin = strings.HasPrefix(trimmed, `[remote "origin"]`)
+			continue
+		}
+		if !inOrigin || !strings.HasPrefix(trimmed, "url") {
+			continue
+		}
+		_, url, found := strings.Cut(trimmed, "=")
+		if !found {
+			continue
+		}
+		return ownerFromRemoteURL(strings.TrimSpace(url))
+	}
+	return ""
+}
+
+func ownerFromRemoteURL(url string) string {
+	url = strings.TrimSuffix(strings.TrimSuffix(url, "/"), ".git")
+
+	// scp-like form, git@host:owner/repo. Checked by the absence of a
+	// scheme rather than by the presence of a colon: ssh://git@host/o/r
+	// has both a colon and a scheme, and belongs to the path form below.
+	if !strings.Contains(url, "://") {
+		if _, rest, found := strings.Cut(url, ":"); found {
+			owner, _, _ := strings.Cut(rest, "/")
+			return sanitiseSlugSegment(owner)
+		}
+		return ""
+	}
+
+	// scheme://host/owner/repo — the owner is the second-to-last segment.
+	parts := strings.Split(url, "/")
+	if len(parts) < 2 {
+		return ""
+	}
+	return sanitiseSlugSegment(parts[len(parts)-2])
+}
+
+// sanitiseSlugSegment drops anything that would fail harness.ValidSlug, so a
+// remote with an unusual owner degrades to the fallback rather than
+// producing a harness that fails validation.
+func sanitiseSlugSegment(s string) string {
+	if s == "" || !harness.ValidSlug(s) {
+		return ""
+	}
+	return s
+}
diff --git a/internal/agentnew/generate_slug_test.go b/internal/agentnew/generate_slug_test.go
new file mode 100644
index 0000000000..55d5adf426
--- /dev/null
+++ b/internal/agentnew/generate_slug_test.go
@@ -0,0 +1,133 @@
+package agentnew
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestOwnerFromRemoteURL(t *testing.T) {
+	for _, tc := range []struct{ url, want string }{
+		{"git@github.com:my-org/my-repo.git", "my-org"},
+		{"git@github.com:my-org/my-repo", "my-org"},
+		{"https://github.com/my-org/my-repo.git", "my-org"},
+		{"https://github.com/my-org/my-repo", "my-org"},
+		{"https://gitlab.cee.example.com/group/sub/my-repo", "sub"},
+		{"ssh://git@github.com/my-org/my-repo.git", "my-org"},
+		// Owners that would not survive harness.ValidSlug fall back rather
+		// than producing a harness that fails validation.
+		{"https://github.com/-bad/my-repo", ""},
+		{"https://github.com/o.k/my-repo", ""},
+		{"nonsense", ""},
+		{"", ""},
+	} {
+		if got := ownerFromRemoteURL(tc.url); got != tc.want {
+			t.Errorf("ownerFromRemoteURL(%q) = %q, want %q", tc.url, got, tc.want)
+		}
+	}
+}
+
+func TestOwnerFromGitConfig(t *testing.T) {
+	cfg := `[core]
+	repositoryformatversion = 0
+[remote "upstream"]
+	url = git@github.com:upstream-org/repo.git
+	fetch = +refs/heads/*:refs/remotes/upstream/*
+[remote "origin"]
+	url = git@github.com:my-org/my-repo.git
+	fetch = +refs/heads/*:refs/remotes/origin/*
+[branch "main"]
+	remote = origin
+`
+	if got := ownerFromGitConfig(cfg); got != "my-org" {
+		t.Errorf("ownerFromGitConfig = %q, want my-org", got)
+	}
+	if got := ownerFromGitConfig("[core]\n\tbare = false\n"); got != "" {
+		t.Errorf("config with no origin should yield \"\", got %q", got)
+	}
+	if got := ownerFromGitConfig("[remote \"origin\"]\n\turl\n"); got != "" {
+		t.Errorf("malformed url line should yield \"\", got %q", got)
+	}
+}
+
+// TestGitConfigOwnerWalksUp: --fullsend-dir is normally .fullsend inside the
+// repository, so the owner lookup has to climb to the repository root.
+func TestGitConfigOwnerWalksUp(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, ".git", "config"),
+		[]byte("[remote \"origin\"]\n\turl = https://github.com/my-org/my-repo.git\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	nested := filepath.Join(root, ".fullsend")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if got := GitConfigOwner(nested); got != "my-org" {
+		t.Errorf("GitConfigOwner = %q, want my-org", got)
+	}
+	if got := GitConfigOwner(t.TempDir()); got != "" {
+		t.Errorf("a directory outside any repository should yield \"\", got %q", got)
+	}
+}
+
+func TestDeriveSlug(t *testing.T) {
+	if got := DeriveSlug("lint-docs", "my-org"); got != "my-org-lint-docs" {
+		t.Errorf("DeriveSlug = %q", got)
+	}
+	if got := DeriveSlug("lint-docs", ""); got != "fullsend-lint-docs" {
+		t.Errorf("DeriveSlug fallback = %q", got)
+	}
+}
+
+// TestGitConfigOwnerInLinkedWorktree: in a linked worktree .git is a FILE
+// containing "gitdir: <path>", and the config lives in the MAIN repository's
+// common directory. Worktrees are the normal way to work in this project, so
+// a naive dir/.git/config read would silently fall back to the default slug
+// for most real users.
+func TestGitConfigOwnerInLinkedWorktree(t *testing.T) {
+	root := t.TempDir()
+
+	// The main repository.
+	mainGit := filepath.Join(root, "main", ".git")
+	if err := os.MkdirAll(filepath.Join(mainGit, "worktrees", "wt1"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(mainGit, "config"),
+		[]byte("[remote \"origin\"]\n\turl = git@github.com:my-org/my-repo.git\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// The worktree's private gitdir points back at the common directory.
+	if err := os.WriteFile(filepath.Join(mainGit, "worktrees", "wt1", "commondir"),
+		[]byte("../..\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// The linked worktree: .git is a file, not a directory.
+	wt := filepath.Join(root, "wt1")
+	if err := os.MkdirAll(filepath.Join(wt, ".fullsend"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(wt, ".git"),
+		[]byte("gitdir: "+filepath.Join(mainGit, "worktrees", "wt1")+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	if got := GitConfigOwner(filepath.Join(wt, ".fullsend")); got != "my-org" {
+		t.Errorf("GitConfigOwner in a linked worktree = %q, want my-org", got)
+	}
+}
+
+// TestGitConfigOwnerMalformedWorktreePointer degrades to the fallback rather
+// than erroring.
+func TestGitConfigOwnerMalformedWorktreePointer(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, ".git"), []byte("not a pointer\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := GitConfigOwner(dir); got != "" {
+		t.Errorf("malformed .git pointer should yield \"\", got %q", got)
+	}
+}
diff --git a/internal/agentnew/generate_write_test.go b/internal/agentnew/generate_write_test.go
new file mode 100644
index 0000000000..154bd96740
--- /dev/null
+++ b/internal/agentnew/generate_write_test.go
@@ -0,0 +1,304 @@
+package agentnew
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func newTargetDir(t *testing.T) string {
+	t.Helper()
+	dir := filepath.Join(t.TempDir(), ".fullsend")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+
+func TestValidateFullsendDir(t *testing.T) {
+	if err := ValidateFullsendDir(newTargetDir(t)); err != nil {
+		t.Errorf("an existing directory should be accepted: %v", err)
+	}
+	if err := ValidateFullsendDir(filepath.Join(t.TempDir(), "nope")); err == nil {
+		t.Error("a missing directory should be refused")
+	} else if !strings.Contains(err.Error(), "github setup") {
+		t.Errorf("error should point at github setup: %v", err)
+	}
+	// A file where a directory is expected.
+	file := filepath.Join(t.TempDir(), "afile")
+	if err := os.WriteFile(file, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := ValidateFullsendDir(file); err == nil {
+		t.Error("a regular file should be refused as a fullsend dir")
+	}
+}
+
+func TestGenerateWritesAndIsIdempotentlyRefused(t *testing.T) {
+	dir := newTargetDir(t)
+	opts := testOptions("lint-docs", "triage")
+
+	result, err := Generate(opts, dir, false, false)
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if len(result.Written) == 0 {
+		t.Fatal("nothing was reported as written")
+	}
+	for _, w := range result.Written {
+		if _, err := os.Stat(filepath.Join(dir, w)); err != nil {
+			t.Errorf("%s reported as written but is missing: %v", w, err)
+		}
+	}
+
+	// A second run refuses, listing the collisions, and changes nothing.
+	_, err = Generate(opts, dir, false, false)
+	if err == nil {
+		t.Fatal("a second run without --force should be refused")
+	}
+	if !strings.Contains(err.Error(), "already exist") || !strings.Contains(err.Error(), "--force") {
+		t.Errorf("collision error should list the files and mention --force: %v", err)
+	}
+}
+
+func TestGenerateForceRewritesOwnedFilesOnly(t *testing.T) {
+	dir := newTargetDir(t)
+	opts := testOptions("lint-docs", "triage")
+	if _, err := Generate(opts, dir, false, false); err != nil {
+		t.Fatal(err)
+	}
+
+	sentinel := []byte("# hand-edited\n")
+	policy := filepath.Join(dir, "policies", "base.yaml")
+	if err := os.WriteFile(policy, sentinel, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	harnessPath := filepath.Join(dir, "harness", "lint-docs.yaml")
+	if err := os.WriteFile(harnessPath, []byte("clobbered\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := Generate(opts, dir, true, false)
+	if err != nil {
+		t.Fatalf("--force run failed: %v", err)
+	}
+	if got, _ := os.ReadFile(harnessPath); string(got) == "clobbered\n" {
+		t.Error("--force should rewrite an owned file")
+	}
+	if got, _ := os.ReadFile(policy); string(got) != string(sentinel) {
+		t.Error("--force must never rewrite a shared asset")
+	}
+	if len(result.SkippedShared) == 0 {
+		t.Error("existing shared assets should be reported as skipped")
+	}
+}
+
+func TestGenerateDryRunWritesNothing(t *testing.T) {
+	dir := newTargetDir(t)
+	result, err := Generate(testOptions("lint-docs", "triage"), dir, false, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(result.Written) == 0 || len(result.Rendered) == 0 {
+		t.Error("a dry run should still report what it would create")
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) != 0 {
+		t.Errorf("dry run created %d entries", len(entries))
+	}
+}
+
+// TestGenerateRollsBackPartialWrites: a failure part-way through must leave
+// the directory as it found it, rather than a half-written agent.
+func TestGenerateRollsBackPartialWrites(t *testing.T) {
+	dir := newTargetDir(t)
+
+	original := writeFile
+	t.Cleanup(func() { writeFile = original })
+
+	var calls int
+	writeFile = func(name string, data []byte, perm os.FileMode) error {
+		calls++
+		if calls == 3 {
+			return errors.New("injected failure on the third write")
+		}
+		return original(name, data, perm)
+	}
+
+	if _, err := Generate(testOptions("lint-docs", "triage"), dir, false, false); err == nil {
+		t.Fatal("the injected failure should have propagated")
+	}
+
+	var found []string
+	_ = filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if err == nil && !d.IsDir() {
+			found = append(found, path)
+		}
+		return nil
+	})
+	if len(found) != 0 {
+		t.Errorf("a failed run left files behind: %v", found)
+	}
+}
+
+// TestGenerateRefusesSymlinkedDestination: a repository-controlled symlink at
+// a destination, or at a directory leading to one, would otherwise redirect a
+// generated file outside the fullsend directory.
+func TestGenerateRefusesSymlinkedDestination(t *testing.T) {
+	t.Run("symlinked parent directory", func(t *testing.T) {
+		dir := newTargetDir(t)
+		outside := t.TempDir()
+		if err := os.Symlink(outside, filepath.Join(dir, "harness")); err != nil {
+			t.Skipf("symlinks unavailable: %v", err)
+		}
+		_, err := Generate(testOptions("lint-docs", "triage"), dir, false, false)
+		if err == nil {
+			t.Fatal("writing through a symlinked parent should be refused")
+		}
+		if !strings.Contains(err.Error(), "symlink") {
+			t.Errorf("error should name the symlink: %v", err)
+		}
+		if entries, _ := os.ReadDir(outside); len(entries) != 0 {
+			t.Error("a file was written outside the fullsend directory")
+		}
+	})
+
+	t.Run("dangling symlink at the destination", func(t *testing.T) {
+		dir := newTargetDir(t)
+		if err := os.MkdirAll(filepath.Join(dir, "harness"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		target := filepath.Join(t.TempDir(), "does-not-exist")
+		if err := os.Symlink(target, filepath.Join(dir, "harness", "lint-docs.yaml")); err != nil {
+			t.Skipf("symlinks unavailable: %v", err)
+		}
+		if _, err := Generate(testOptions("lint-docs", "triage"), dir, true, false); err == nil {
+			t.Fatal("a dangling symlink destination should be refused even with --force")
+		}
+		if _, err := os.Stat(target); err == nil {
+			t.Error("the dangling symlink target was created")
+		}
+	})
+}
+
+// TestGenerateRejectsUnreadableSharedAsset: an existing shared asset that
+// cannot be read must fail naming the path, rather than silently validating
+// the embedded copy that will not be the one in use.
+func TestGenerateRejectsUnreadableSharedAsset(t *testing.T) {
+	dir := newTargetDir(t)
+	// A directory where policies/base.yaml should be.
+	if err := os.MkdirAll(filepath.Join(dir, "policies", "base.yaml"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	_, err := Generate(testOptions("lint-docs", "triage"), dir, false, false)
+	if err == nil {
+		t.Fatal("a directory in place of a shared asset should be refused")
+	}
+	if !strings.Contains(err.Error(), "policies/base.yaml") {
+		t.Errorf("error should name the path: %v", err)
+	}
+}
+
+func TestGenerateRejectsMissingDir(t *testing.T) {
+	if _, err := Generate(testOptions("lint-docs", "triage"), filepath.Join(t.TempDir(), "nope"), false, false); err == nil {
+		t.Fatal("a missing fullsend dir should be refused")
+	}
+}
+
+// TestGenerateRefusesSymlinkedRoot: checkNoSymlinks only walks segments
+// BENEATH the fullsend directory, so a symlink at the root itself is
+// invisible to it — every generated path is joined onto that root.
+func TestGenerateRefusesSymlinkedRoot(t *testing.T) {
+	base := t.TempDir()
+	real := filepath.Join(base, "real")
+	if err := os.MkdirAll(real, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(base, "link")
+	if err := os.Symlink(real, link); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+
+	if err := ValidateFullsendDir(link); err == nil {
+		t.Fatal("a symlinked fullsend dir should be refused")
+	} else if !strings.Contains(err.Error(), "symlink") {
+		t.Errorf("error should name the symlink: %v", err)
+	}
+	if _, err := Generate(testOptions("lint-docs", "triage"), link, false, false); err == nil {
+		t.Fatal("Generate through a symlinked root should be refused")
+	}
+	entries, _ := os.ReadDir(real)
+	if len(entries) != 0 {
+		t.Errorf("wrote %d entries through the symlink", len(entries))
+	}
+}
+
+// TestGenerateForceRollbackRestoresOriginals: under --force the destinations
+// already exist, so removing them on failure would destroy a working agent
+// definition rather than undo the run.
+func TestGenerateForceRollbackRestoresOriginals(t *testing.T) {
+	dir := newTargetDir(t)
+	opts := testOptions("lint-docs", "triage")
+	if _, err := Generate(opts, dir, false, false); err != nil {
+		t.Fatal(err)
+	}
+
+	harnessPath := filepath.Join(dir, "harness", "lint-docs.yaml")
+	original := []byte("# the user's working harness\n")
+	if err := os.WriteFile(harnessPath, original, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	restore := writeFile
+	t.Cleanup(func() { writeFile = restore })
+	var calls int
+	writeFile = func(name string, data []byte, perm os.FileMode) error {
+		calls++
+		if calls == 3 {
+			return errors.New("injected failure on the third write")
+		}
+		return restore(name, data, perm)
+	}
+
+	if _, err := Generate(opts, dir, true, false); err == nil {
+		t.Fatal("the injected failure should have propagated")
+	}
+	got, err := os.ReadFile(harnessPath)
+	if err != nil {
+		t.Fatalf("the pre-existing harness was deleted rather than restored: %v", err)
+	}
+	if string(got) != string(original) {
+		t.Errorf("harness was not restored\n got: %q\nwant: %q", got, original)
+	}
+}
+
+// TestGenerateForceRestoresExecutableBit: os.WriteFile leaves an existing
+// file's mode alone, so a post-script overwritten on top of a 0644 file would
+// stay non-executable and the runner could not invoke it.
+func TestGenerateForceRestoresExecutableBit(t *testing.T) {
+	dir := newTargetDir(t)
+	opts := testOptions("lint-docs", "triage")
+	if _, err := Generate(opts, dir, false, false); err != nil {
+		t.Fatal(err)
+	}
+	script := filepath.Join(dir, "scripts", "post-lint-docs.sh")
+	if err := os.Chmod(script, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Generate(opts, dir, true, false); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(script)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm()&0o111 == 0 {
+		t.Errorf("--force left the post-script non-executable: %v", info.Mode())
+	}
+}
diff --git a/internal/agentnew/golden_test.go b/internal/agentnew/golden_test.go
new file mode 100644
index 0000000000..7429855291
--- /dev/null
+++ b/internal/agentnew/golden_test.go
@@ -0,0 +1,128 @@
+package agentnew
+
+import (
+	"bytes"
+	"flag"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden files in testdata/golden")
+
+// TestGolden pins the exact bytes of a generated tree. A template edit that
+// changes generated output shows up as a reviewable diff rather than passing
+// silently — which matters because these files land in users' repositories
+// and nothing regenerates them afterwards.
+//
+// Regenerate with: go test ./internal/agentnew/ -run TestGolden -update
+func TestGolden(t *testing.T) {
+	// Two trees, not one per role. The roles differ only in table data —
+	// image, providers, profiles — which TestRoleTableMatchesMint and its
+	// siblings assert directly and more precisely than a byte diff does.
+	// validation-loop is kept because it is the only variant that exercises
+	// an actual conditional in the generator: `if opts.ValidationLoop` in
+	// both buildHarness and sharedAssets.
+	cases := []struct {
+		name string
+		opts func() Options
+	}{
+		{"triage", func() Options { return testOptions("lint-docs", "triage") }},
+		{"validation-loop", func() Options {
+			o := testOptions("lint-docs", "triage")
+			o.ValidationLoop = true
+			return o
+		}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			files, err := Render(tc.opts())
+			if err != nil {
+				t.Fatal(err)
+			}
+			got := renderTree(files)
+			goldenPath := filepath.Join("testdata", "golden", tc.name+".txt")
+
+			if *update {
+				if err := os.MkdirAll(filepath.Dir(goldenPath), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(goldenPath, []byte(got), 0o644); err != nil {
+					t.Fatal(err)
+				}
+				return
+			}
+
+			want, err := os.ReadFile(goldenPath)
+			if err != nil {
+				t.Fatalf("reading golden file (run with -update to create it): %v", err)
+			}
+			if got != string(want) {
+				t.Errorf("generated tree differs from %s\n"+
+					"If the change is intended, re-run with -update and review the diff.\n\n%s",
+					goldenPath, firstDifference(string(want), got))
+			}
+		})
+	}
+}
+
+// renderTree renders a file set as a stable, diffable document. The harness
+// digest is the one value that legitimately changes on a fleet repin, so it
+// is left in: a repin SHOULD show up as a golden diff.
+func renderTree(files []File) string {
+	sorted := append([]File(nil), files...)
+	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Path < sorted[j].Path })
+
+	var b strings.Builder
+	for _, f := range sorted {
+		shared := ""
+		if f.Shared {
+			shared = " (shared, written only when absent)"
+		}
+		b.WriteString("=== " + f.Path + " mode=" + octal(f.Mode) + shared + "\n")
+		// Shared assets are byte-identical copies of files that already live
+		// in the repo; their contents are asserted elsewhere, and inlining
+		// them here would bury the generated files in noise.
+		if f.Shared {
+			b.WriteString("<copied verbatim from the embedded scaffold>\n")
+			continue
+		}
+		b.Write(f.Data)
+		if !bytes.HasSuffix(f.Data, []byte("\n")) {
+			b.WriteString("\n")
+		}
+	}
+	return b.String()
+}
+
+func octal(mode uint32) string {
+	const digits = "01234567"
+	if mode == 0 {
+		return "0"
+	}
+	var out []byte
+	for mode > 0 {
+		out = append([]byte{digits[mode%8]}, out...)
+		mode /= 8
+	}
+	return string(out)
+}
+
+// firstDifference reports the first differing line, which is far easier to
+// read than a whole-tree diff when a template changes.
+func firstDifference(want, got string) string {
+	wantLines := strings.Split(want, "\n")
+	gotLines := strings.Split(got, "\n")
+	for i := 0; i < len(wantLines) && i < len(gotLines); i++ {
+		if wantLines[i] != gotLines[i] {
+			return "first difference at line " + strconv.Itoa(i+1) + ":\n" +
+				"  want: " + wantLines[i] + "\n" +
+				"   got: " + gotLines[i] + "\n"
+		}
+	}
+	return "want " + strconv.Itoa(len(wantLines)) + " lines, got " + strconv.Itoa(len(gotLines)) + "\n"
+}
diff --git a/internal/agentnew/options.go b/internal/agentnew/options.go
new file mode 100644
index 0000000000..852190bb5c
--- /dev/null
+++ b/internal/agentnew/options.go
@@ -0,0 +1,77 @@
+package agentnew
+
+import (
+	"fmt"
+
+	"github.com/fullsend-ai/fullsend/internal/config"
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+// Default values for the generated harness.
+const (
+	DefaultModel          = "opus"
+	DefaultEffort         = "high"
+	DefaultTimeoutMinutes = 15
+	// DefaultOn is the trigger preset used when neither --on nor --trigger
+	// is given. A trigger is mandatory: ListTriggeredHarnesses skips a
+	// trigger-less harness with a bare `continue` and no annotation, so such
+	// an agent registers, validates, lists, and then never fires.
+	DefaultOn = PresetCommand
+)
+
+// Options is the fully-resolved input to Render, after defaults, spec file
+// and command-line flags have been merged. Every field is already validated:
+// Render assumes it can use them without further checking.
+type Options struct {
+	Name           string
+	Role           string
+	Description    string
+	Trigger        string
+	Model          string
+	Effort         string
+	Slug           string
+	Image          string
+	TimeoutMinutes int
+	ValidationLoop bool
+}
+
+// Validate checks every field that reaches a generated file, and does so
+// before anything touches disk. Name is checked first and most strictly: it
+// is interpolated into a shell script, so it must satisfy the same pattern
+// harness.Validate relies on for shell safety.
+func (o *Options) Validate() error {
+	// Both rules apply. harness.ValidAgentBasename is the shell-safety check
+	// the harness loader relies on; config.ValidConfigAgentName is what
+	// registration will demand later. Checking only the first would let a
+	// name like "_lint" generate every file and then fail at registration,
+	// leaving the directory changed by a run that failed.
+	if !harness.ValidAgentBasename(o.Name) || !config.ValidConfigAgentName(o.Name) {
+		return fmt.Errorf("agent name %q is not valid: it must start with a letter or digit and contain only letters, digits, underscores and hyphens", o.Name)
+	}
+	if _, err := LookupRole(o.Role); err != nil {
+		return err
+	}
+	if o.Trigger == "" {
+		return fmt.Errorf("a trigger is required: pass --on with a preset, or --trigger with a CEL expression.\n" +
+			"An agent with no trigger registers and validates but is silently never dispatched")
+	}
+	if err := harness.ValidateTriggerExpression(o.Trigger); err != nil {
+		return fmt.Errorf("trigger does not compile: %w", err)
+	}
+	if o.Model != "" && !config.ValidModelRef(o.Model) {
+		return fmt.Errorf("model %q contains invalid characters", o.Model)
+	}
+	if o.Effort != "" && !config.ValidEffort(o.Effort) {
+		return fmt.Errorf("effort %q is not valid (allowed: %v)", o.Effort, config.ValidEffortLevels())
+	}
+	if o.Slug != "" && !harness.ValidSlug(o.Slug) {
+		return fmt.Errorf("slug %q contains invalid characters (allowed: a-z, A-Z, 0-9, _, -; must start with a letter or digit)", o.Slug)
+	}
+	if o.TimeoutMinutes < 0 {
+		return fmt.Errorf("timeout_minutes must be non-negative, got %d", o.TimeoutMinutes)
+	}
+	if o.Image == "" {
+		return fmt.Errorf("image must not be empty")
+	}
+	return nil
+}
diff --git a/internal/agentnew/options_test.go b/internal/agentnew/options_test.go
new file mode 100644
index 0000000000..561443c78c
--- /dev/null
+++ b/internal/agentnew/options_test.go
@@ -0,0 +1,87 @@
+package agentnew
+
+import (
+	"strings"
+	"testing"
+)
+
+func validOptions() Options {
+	o := testOptions("lint-docs", "triage")
+	return o
+}
+
+// TestOptionsValidateRejects covers every field that reaches a generated
+// file. Name is the security-relevant one: it is interpolated into a shell
+// script, so an invalid name must be refused before anything is written.
+func TestOptionsValidateRejects(t *testing.T) {
+	tests := []struct {
+		name    string
+		mutate  func(*Options)
+		wantErr string
+	}{
+		{"empty name", func(o *Options) { o.Name = "" }, "is not valid"},
+		{"name with semicolon", func(o *Options) { o.Name = "a;rm -rf /" }, "is not valid"},
+		{"name with slash", func(o *Options) { o.Name = "../escape" }, "is not valid"},
+		{"name with space", func(o *Options) { o.Name = "lint docs" }, "is not valid"},
+		{"name with dollar", func(o *Options) { o.Name = "a$(id)" }, "is not valid"},
+		{"name with backtick", func(o *Options) { o.Name = "a`id`" }, "is not valid"},
+		{"leading underscore", func(o *Options) { o.Name = "_lead" }, "is not valid"},
+		{"leading hyphen", func(o *Options) { o.Name = "-lead" }, "is not valid"},
+		{"unknown role", func(o *Options) { o.Role = "scribe" }, "unknown role"},
+		{"empty trigger", func(o *Options) { o.Trigger = "" }, "trigger is required"},
+		{"uncompilable trigger", func(o *Options) { o.Trigger = "this is not CEL" }, "does not compile"},
+		{"non-boolean trigger", func(o *Options) { o.Trigger = `"a string"` }, "does not compile"},
+		{"bad model", func(o *Options) { o.Model = "opus!!" }, "model"},
+		{"bad effort", func(o *Options) { o.Effort = "extreme" }, "effort"},
+		{"bad slug", func(o *Options) { o.Slug = "-leading-dash" }, "slug"},
+		{"negative timeout", func(o *Options) { o.TimeoutMinutes = -1 }, "non-negative"},
+		{"empty image", func(o *Options) { o.Image = "" }, "image"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			o := validOptions()
+			tc.mutate(&o)
+			err := o.Validate()
+			if err == nil {
+				t.Fatalf("Validate() accepted %s", tc.name)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Errorf("error %q should mention %q", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestOptionsValidateAccepts(t *testing.T) {
+	for _, role := range RoleNames() {
+		o := testOptions("lint-docs", role)
+		if err := o.Validate(); err != nil {
+			t.Errorf("role %q: %v", role, err)
+		}
+	}
+	// Optional fields may be empty.
+	o := validOptions()
+	o.Model, o.Effort, o.Slug, o.Description = "", "", "", ""
+	o.TimeoutMinutes = 0
+	if err := o.Validate(); err != nil {
+		t.Errorf("optional fields should be allowed to be empty: %v", err)
+	}
+}
+
+// TestTriggerlessAgentIsRefusedLoudly: an agent with no trigger registers,
+// validates and lists, then is silently skipped by dispatch with no
+// annotation. The error has to explain that, or the user will not understand
+// why the command refused.
+func TestTriggerlessAgentIsRefusedLoudly(t *testing.T) {
+	o := validOptions()
+	o.Trigger = ""
+	err := o.Validate()
+	if err == nil {
+		t.Fatal("want error")
+	}
+	for _, want := range []string{"--on", "--trigger", "never dispatched"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error should mention %q, got: %v", want, err)
+		}
+	}
+}
diff --git a/internal/agentnew/postscript_exec_test.go b/internal/agentnew/postscript_exec_test.go
new file mode 100644
index 0000000000..0ad06c0acf
--- /dev/null
+++ b/internal/agentnew/postscript_exec_test.go
@@ -0,0 +1,132 @@
+package agentnew
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeRunDir lays out a run directory the way internal/cli/run.go does:
+// postCmd.Dir is the RUN directory, and each iteration's output lives in
+// iteration-<N>/output/agent-result.json.
+func writeRunDir(t *testing.T, results map[string]any) string {
+	t.Helper()
+	runDir := t.TempDir()
+	for iter, result := range results {
+		dir := filepath.Join(runDir, iter, "output")
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		data, err := json.Marshal(result)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "agent-result.json"), data, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return runDir
+}
+
+// runPostScript executes the generated post-script from runDir, in dry-run
+// mode so it never posts anything.
+func runPostScript(t *testing.T, script, runDir string, extraEnv ...string) (string, string, error) {
+	t.Helper()
+	cmd := exec.Command("bash", script)
+	cmd.Dir = runDir
+	cmd.Env = append(os.Environ(),
+		"ISSUE_URL=https://github.com/fullsend-ai/demo/pull/99",
+		"GH_TOKEN=test-token",
+		DryRunEnvVar("lint-docs")+"=1",
+	)
+	cmd.Env = append(cmd.Env, extraEnv...)
+	var stdout, stderr strings.Builder
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	err := cmd.Run()
+	return stdout.String(), stderr.String(), err
+}
+
+// renderPostScriptTo writes the generated post-script to disk and returns its
+// path.
+func renderPostScriptTo(t *testing.T, dir string) string {
+	t.Helper()
+	files, err := Render(testOptions("lint-docs", "triage"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(dir, "post-lint-docs.sh")
+	if err := os.WriteFile(path, fileByPath(t, files, "scripts/post-lint-docs.sh").Data, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// TestGeneratedPostScriptRunsFromTheRunDirectory executes the generated
+// script against the directory layout run.go actually provides.
+//
+// Every other test of this template matches substrings, and none of them
+// could have caught the script looking in the wrong directory: `output/` is
+// present in both the correct and incorrect forms. Running it is the only
+// check that distinguishes them.
+func TestGeneratedPostScriptRunsFromTheRunDirectory(t *testing.T) {
+	if _, err := exec.LookPath("jq"); err != nil {
+		t.Skip("jq not available")
+	}
+	script := renderPostScriptTo(t, t.TempDir())
+
+	t.Run("finds the result under iteration-N/output", func(t *testing.T) {
+		runDir := writeRunDir(t, map[string]any{
+			"iteration-1": map[string]any{"status": "findings", "summary": "two broken links", "comment": "- a.md"},
+		})
+		stdout, stderr, err := runPostScript(t, script, runDir)
+		if err != nil {
+			t.Fatalf("post-script failed against a real run directory: %v\nstderr: %s", err, stderr)
+		}
+		if !strings.Contains(stdout, "two broken links") {
+			t.Errorf("summary missing from output: %q", stdout)
+		}
+	})
+
+	t.Run("takes the last iteration", func(t *testing.T) {
+		runDir := writeRunDir(t, map[string]any{
+			"iteration-1": map[string]any{"status": "findings", "summary": "first", "comment": "c"},
+			"iteration-2": map[string]any{"status": "findings", "summary": "second", "comment": "c"},
+		})
+		stdout, stderr, err := runPostScript(t, script, runDir)
+		if err != nil {
+			t.Fatalf("post-script failed: %v\nstderr: %s", err, stderr)
+		}
+		if !strings.Contains(stdout, "second") {
+			t.Errorf("expected the last iteration, got: %q", stdout)
+		}
+	})
+
+	t.Run("a validated iteration wins over the scan", func(t *testing.T) {
+		runDir := writeRunDir(t, map[string]any{
+			"iteration-1": map[string]any{"status": "findings", "summary": "validated", "comment": "c"},
+			"iteration-2": map[string]any{"status": "findings", "summary": "later", "comment": "c"},
+		})
+		stdout, stderr, err := runPostScript(t, script, runDir,
+			"FULLSEND_VALIDATED_ITERATION_DIR="+filepath.Join(runDir, "iteration-1", "output"))
+		if err != nil {
+			t.Fatalf("post-script failed: %v\nstderr: %s", err, stderr)
+		}
+		if !strings.Contains(stdout, "validated") {
+			t.Errorf("FULLSEND_VALIDATED_ITERATION_DIR should win, got: %q", stdout)
+		}
+	})
+
+	t.Run("no output anywhere is an error", func(t *testing.T) {
+		_, stderr, err := runPostScript(t, script, t.TempDir())
+		if err == nil {
+			t.Fatal("expected a failure when no iteration produced output")
+		}
+		if !strings.Contains(stderr, "no agent-result.json found") {
+			t.Errorf("unexpected error text: %q", stderr)
+		}
+	})
+}
diff --git a/internal/agentnew/render.go b/internal/agentnew/render.go
new file mode 100644
index 0000000000..03fb3bd4db
--- /dev/null
+++ b/internal/agentnew/render.go
@@ -0,0 +1,281 @@
+package agentnew
+
+import (
+	"bytes"
+	"embed"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+//go:embed all:templates
+var templates embed.FS
+
+// yamlIndent matches the indentation the fleet harnesses use. yaml.v3
+// defaults to 4, which would make a generated harness look unlike every
+// hand-written one next to it.
+const yamlIndent = 2
+
+// agentNamePlaceholder and dryRunPlaceholder are replaced by fixed string
+// substitution, never by a template engine. The only user-supplied value that
+// reaches a generated shell script is the agent name, and it has already
+// passed harness.ValidAgentBasename by the time Render is called.
+const (
+	agentNamePlaceholder = "__AGENT_NAME__"
+	dryRunPlaceholder    = "__DRY_RUN_VAR__"
+)
+
+// File is one generated file. Shared is true for scaffold assets that are
+// written only when absent and are never overwritten, even with --force:
+// they are shared between every agent in the directory.
+type File struct {
+	Path   string
+	Data   []byte
+	Mode   uint32
+	Shared bool
+}
+
+// Render produces the full set of files for one agent. It performs no I/O
+// beyond reading the embedded templates, so every branch is unit-testable
+// without a filesystem.
+func Render(opts Options) ([]File, error) {
+	role, err := LookupRole(opts.Role)
+	if err != nil {
+		return nil, err
+	}
+
+	h, err := buildHarness(opts, role)
+	if err != nil {
+		return nil, err
+	}
+	harnessYAML, err := marshalHarness(h, opts.Name)
+	if err != nil {
+		return nil, err
+	}
+
+	agentMD, err := renderAgentDefinition(opts)
+	if err != nil {
+		return nil, err
+	}
+	schemaJSON, err := renderSchema(opts.Name)
+	if err != nil {
+		return nil, err
+	}
+	postScript, err := renderPostScript(opts.Name)
+	if err != nil {
+		return nil, err
+	}
+
+	files := []File{
+		{Path: "harness/" + opts.Name + ".yaml", Data: harnessYAML, Mode: 0o644},
+		{Path: "agents/" + opts.Name + ".md", Data: agentMD, Mode: 0o644},
+		{Path: "schemas/" + opts.Name + "-result.schema.json", Data: schemaJSON, Mode: 0o644},
+		{Path: "scripts/post-" + opts.Name + ".sh", Data: postScript, Mode: 0o755},
+	}
+
+	shared, err := sharedAssets(role, opts.ValidationLoop)
+	if err != nil {
+		return nil, err
+	}
+	return append(files, shared...), nil
+}
+
+// buildHarness assembles the Harness value that becomes the generated YAML.
+// Building the real struct rather than formatting text means the generator
+// cannot emit a field the validator does not know about.
+func buildHarness(opts Options, role Role) (*harness.Harness, error) {
+	h := &harness.Harness{
+		Agent:       "agents/" + opts.Name + ".md",
+		Description: opts.Description,
+		Role:        role.Name,
+		Slug:        opts.Slug,
+		Image:       opts.Image,
+		Policy:      "policies/base.yaml",
+		Providers:   append([]string(nil), role.Providers...),
+		OpenShell:   &harness.OpenShellConfig{Profiles: append([]string(nil), role.Profiles...)},
+		HostFiles: []harness.HostFile{
+			{Src: "${GOOGLE_APPLICATION_CREDENTIALS}", Dest: "/tmp/.gcp-credentials.json"},
+			{Src: "${GCP_OIDC_TOKEN_FILE}", Dest: "/sandbox/workspace/.gcp-oidc-token", Optional: true},
+		},
+		Model:          opts.Model,
+		Effort:         opts.Effort,
+		PostScript:     "scripts/post-" + opts.Name + ".sh",
+		TimeoutMinutes: opts.TimeoutMinutes,
+		Trigger:        opts.Trigger,
+		Env: &harness.EnvConfig{
+			Runner: map[string]string{
+				"ISSUE_URL":      "${GITHUB_ISSUE_URL}",
+				"GH_TOKEN":       "${GH_TOKEN}",
+				"FULLSEND_FORGE": "github",
+			},
+			// The scaffold ships no env/ directory and nothing in fullsend
+			// sets CLAUDE_CODE_USE_VERTEX, so the Vertex variables the fleet
+			// delivers via host_files: env/gcp-vertex.env are set here.
+			Sandbox: map[string]string{
+				"CLAUDE_CODE_USE_VERTEX":         "1",
+				"ANTHROPIC_VERTEX_PROJECT_ID":    "${ANTHROPIC_VERTEX_PROJECT_ID}",
+				"CLOUD_ML_REGION":                "${CLOUD_ML_REGION}",
+				"GOOGLE_APPLICATION_CREDENTIALS": "/tmp/.gcp-credentials.json",
+				"ISSUE_URL":                      "${GITHUB_ISSUE_URL}",
+				"GH_TOKEN":                       "${GH_TOKEN}",
+				"FULLSEND_FORGE":                 "github",
+			},
+		},
+	}
+	if opts.ValidationLoop {
+		h.ValidationLoop = &harness.ValidationLoop{
+			Script:        "scripts/validate-output-schema.sh",
+			Schema:        "schemas/" + opts.Name + "-result.schema.json",
+			MaxIterations: 2,
+			// The validation script hard-fails when python3 or the
+			// jsonschema package is missing, and it does so only after the
+			// agent has already run. preflight_check is evaluated before
+			// sandbox creation, so the same missing dependency is reported
+			// up front instead of costing a full inference run.
+			PreflightCheck: `python3 -c "import jsonschema"`,
+		}
+	}
+	return h, nil
+}
+
+func marshalHarness(h *harness.Harness, name string) ([]byte, error) {
+	var buf bytes.Buffer
+	fmt.Fprintf(&buf, "---\n# Generated by `fullsend agent new %s`. Edit freely — nothing\n", name)
+	buf.WriteString("# regenerates this file.\n#\n")
+	buf.WriteString("# `image:` is the container image this agent runs inside, recorded as\n")
+	buf.WriteString("# an exact digest so every run uses the same one. Pass --image to\n")
+	buf.WriteString("# choose a different one.\n#\n")
+	buf.WriteString("# This agent handles GitHub only. To add GitLab or Jira, see\n")
+	buf.WriteString("# docs/guides/user/bring-your-own-agent.md.\n")
+
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(yamlIndent)
+	if err := enc.Encode(h); err != nil {
+		return nil, fmt.Errorf("marshalling harness: %w", err)
+	}
+	if err := enc.Close(); err != nil {
+		return nil, fmt.Errorf("marshalling harness: %w", err)
+	}
+	return buf.Bytes(), nil
+}
+
+// agentFrontmatter is the YAML block at the top of an agent definition. It is
+// marshalled rather than interpolated: a --description containing a colon,
+// a leading ">" or a newline would otherwise produce a broken document.
+type agentFrontmatter struct {
+	Name        string `yaml:"name"`
+	Description string `yaml:"description"`
+	Tools       string `yaml:"tools"`
+	Model       string `yaml:"model"`
+}
+
+func renderAgentDefinition(opts Options) ([]byte, error) {
+	body, err := templates.ReadFile("templates/agent-body.md.tmpl")
+	if err != nil {
+		return nil, fmt.Errorf("reading agent template: %w", err)
+	}
+
+	var buf bytes.Buffer
+	buf.WriteString("---\n")
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(yamlIndent)
+	if err := enc.Encode(agentFrontmatter{
+		Name:        opts.Name,
+		Description: opts.Description,
+		// Must cover what the generated body actually instructs, and no
+		// more (fullsend-ai/agents#992). The body runs `gh` and `jq`,
+		// reads files to resolve links, and writes one JSON result — so
+		// Write is required, and under the pi runtime the Bash list is a
+		// hard first-token allowlist rather than a hint.
+		Tools: toolsFor(opts),
+		Model: opts.Model,
+	}); err != nil {
+		return nil, fmt.Errorf("marshalling agent frontmatter: %w", err)
+	}
+	if err := enc.Close(); err != nil {
+		return nil, fmt.Errorf("marshalling agent frontmatter: %w", err)
+	}
+	buf.WriteString("---\n\n")
+	buf.Write(bytes.ReplaceAll(body, []byte(agentNamePlaceholder), []byte(opts.Name)))
+
+	// The in-sandbox self-check reads FULLSEND_OUTPUT_SCHEMA, which the
+	// runner only exports when validation_loop.schema is set (or via the
+	// deprecated runner_env, which this generator will not emit). Telling
+	// the agent to run it without that is telling it to run a command that
+	// always fails, so the instruction is rendered only when it will work.
+	if opts.ValidationLoop {
+		buf.WriteString("\nBefore you finish, run " +
+			"`fullsend-check-output \"$FULLSEND_OUTPUT_DIR/agent-result.json\"`\n" +
+			"to catch schema violations while you can still fix them.\n")
+	}
+	return buf.Bytes(), nil
+}
+
+func renderSchema(name string) ([]byte, error) {
+	// encoding/json sorts map keys, so the emitted document is
+	// alphabetical rather than in the order written here. That is stable
+	// and diffable, which is what matters for a generated file; the golden
+	// fixtures pin the exact bytes.
+	schema := map[string]any{
+		"$schema": "https://json-schema.org/draft/2020-12/schema",
+		// Absolute: JSON Schema 2020-12 requires $id to resolve to an
+		// absolute URI, and a file-local schema has no base to resolve a
+		// bare relative reference against.
+		"$id":                  "https://fullsend.sh/schemas/" + name + "-result.schema.json",
+		"title":                name + " Agent Result",
+		"description":          "Structured output from the " + name + " agent, consumed by scripts/post-" + name + ".sh.",
+		"type":                 "object",
+		"additionalProperties": false,
+		"required":             []string{"status", "summary", "comment"},
+		"properties": map[string]any{
+			"status": map[string]any{"type": "string", "enum": []string{"ok", "findings", "error"}},
+			// pattern, not just maxLength: the generated post-script refuses
+			// a multi-line summary (it is interpolated into a bold heading),
+			// and without this the validation loop would pass it and the
+			// failure would surface only after the agent had finished.
+			"summary": map[string]any{
+				"type": "string", "minLength": 1, "maxLength": 200,
+				"pattern": `^[^\r\n]*$`,
+			},
+			"comment": map[string]any{"type": "string", "minLength": 1, "maxLength": 16384},
+		},
+	}
+	data, err := json.MarshalIndent(schema, "", "  ")
+	if err != nil {
+		return nil, fmt.Errorf("marshalling schema: %w", err)
+	}
+	return append(data, '\n'), nil
+}
+
+func renderPostScript(name string) ([]byte, error) {
+	tmpl, err := templates.ReadFile("templates/post.sh.tmpl")
+	if err != nil {
+		return nil, fmt.Errorf("reading post-script template: %w", err)
+	}
+	out := bytes.ReplaceAll(tmpl, []byte(agentNamePlaceholder), []byte(name))
+	out = bytes.ReplaceAll(out, []byte(dryRunPlaceholder), []byte(DryRunEnvVar(name)))
+	return out, nil
+}
+
+// toolsFor returns the frontmatter tools list matching the rendered body.
+// fullsend-check-output is only instructed when the validation loop is on,
+// so it only appears in the Bash allowlist then.
+func toolsFor(opts Options) string {
+	bash := "gh,jq"
+	if opts.ValidationLoop {
+		bash = "gh,jq,fullsend-check-output"
+	}
+	return "Bash(" + bash + "), Read, Grep, Glob, Write"
+}
+
+// DryRunEnvVar is the environment variable that makes a generated
+// post-script print instead of commenting. Derived from the agent name,
+// which has already passed harness.ValidAgentBasename, so the result is always a
+// valid shell identifier.
+func DryRunEnvVar(name string) string {
+	return "POST_" + strings.ToUpper(strings.ReplaceAll(name, "-", "_")) + "_DRY_RUN"
+}
diff --git a/internal/agentnew/render_test.go b/internal/agentnew/render_test.go
new file mode 100644
index 0000000000..387ff4c21d
--- /dev/null
+++ b/internal/agentnew/render_test.go
@@ -0,0 +1,365 @@
+package agentnew
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+// writeTree writes a rendered file set into dir, as the command does.
+func writeTree(t *testing.T, dir string, files []File) {
+	t.Helper()
+	for _, f := range files {
+		path := filepath.Join(dir, f.Path)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, f.Data, os.FileMode(f.Mode)); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func testOptions(name, role string) Options {
+	trigger, err := ExpandTrigger(DefaultOn, name)
+	if err != nil {
+		panic(err)
+	}
+	r, err := LookupRole(role)
+	if err != nil {
+		panic(err)
+	}
+	return Options{
+		Name:           name,
+		Role:           role,
+		Description:    "Check docs changes for broken links",
+		Trigger:        trigger,
+		Model:          DefaultModel,
+		Effort:         DefaultEffort,
+		Slug:           "my-org-" + name,
+		Image:          r.Image,
+		TimeoutMinutes: DefaultTimeoutMinutes,
+	}
+}
+
+// TestGeneratedHarnessLoads is the test that matters most: for every role,
+// the generated tree must load through the same loader dispatch uses. It is
+// the check that would have caught #6834 (a policy: with no policies/
+// directory) and the missing profiles/ layering.
+func TestGeneratedHarnessLoads(t *testing.T) {
+	for _, role := range RoleNames() {
+		t.Run(role, func(t *testing.T) {
+			dir := t.TempDir()
+			opts := testOptions("lint-docs", role)
+			if err := opts.Validate(); err != nil {
+				t.Fatalf("Validate: %v", err)
+			}
+			files, err := Render(opts)
+			if err != nil {
+				t.Fatalf("Render: %v", err)
+			}
+			writeTree(t, dir, files)
+
+			h, err := harness.Load(filepath.Join(dir, "harness", "lint-docs.yaml"))
+			if err != nil {
+				t.Fatalf("generated harness does not load: %v", err)
+			}
+			if err := h.ResolveRelativeTo(dir); err != nil {
+				t.Fatalf("ResolveRelativeTo: %v", err)
+			}
+			if err := h.ValidateFilesExist(); err != nil {
+				t.Fatalf("ValidateFilesExist: %v", err)
+			}
+			if diags := h.Lint(); len(diags) != 0 {
+				t.Errorf("generated harness produces lint diagnostics: %v", diags)
+			}
+			if h.Role != role {
+				t.Errorf("role = %q, want %q", h.Role, role)
+			}
+		})
+	}
+}
+
+// TestGeneratedHarnessHasNoDeprecatedShapes pins decision 6: no forge: block
+// (deprecated by ADR 0088) and no runner_env (deprecated by ADR 0055). Lint
+// would warn, and a generator must never emit a shape the repo has deprecated.
+func TestGeneratedHarnessHasNoDeprecatedShapes(t *testing.T) {
+	files, err := Render(testOptions("lint-docs", "triage"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	yaml := string(fileByPath(t, files, "harness/lint-docs.yaml").Data)
+	for _, banned := range []string{"\nforge:", "runner_env:", "overlays:"} {
+		if strings.Contains(yaml, banned) {
+			t.Errorf("generated harness contains %q:\n%s", banned, yaml)
+		}
+	}
+	if !strings.Contains(yaml, "policy: policies/base.yaml") {
+		t.Error("generated harness must always set policy:")
+	}
+}
+
+// TestValidationLoopIsOptional: the block is off by default and the
+// validator script is only written when it is on. Once the block exists,
+// script: is mandatory, so the two must move together.
+func TestValidationLoopIsOptional(t *testing.T) {
+	off, err := Render(testOptions("lint-docs", "triage"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(fileByPath(t, off, "harness/lint-docs.yaml").Data), "validation_loop") {
+		t.Error("validation_loop must be absent by default")
+	}
+	if hasPath(off, "scripts/validate-output-schema.sh") {
+		t.Error("validator script must not be written without --validation-loop")
+	}
+
+	opts := testOptions("lint-docs", "triage")
+	opts.ValidationLoop = true
+	on, err := Render(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	yaml := string(fileByPath(t, on, "harness/lint-docs.yaml").Data)
+	if !strings.Contains(yaml, "validation_loop:") || !strings.Contains(yaml, "script: scripts/validate-output-schema.sh") {
+		t.Errorf("validation_loop block missing or incomplete:\n%s", yaml)
+	}
+	if !hasPath(on, "scripts/validate-output-schema.sh") {
+		t.Error("--validation-loop must write the validator script")
+	}
+}
+
+// TestDescriptionIsMarshalledNotInterpolated: a description containing YAML
+// metacharacters must not break either document.
+func TestDescriptionIsMarshalledNotInterpolated(t *testing.T) {
+	nasty := `weird: "value" #comment` + "\n" + `>folded: yes`
+	opts := testOptions("lint-docs", "triage")
+	opts.Description = nasty
+	files, err := Render(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dir := t.TempDir()
+	writeTree(t, dir, files)
+	h, err := harness.Load(filepath.Join(dir, "harness", "lint-docs.yaml"))
+	if err != nil {
+		t.Fatalf("harness with an awkward description does not load: %v", err)
+	}
+	if h.Description != nasty {
+		t.Errorf("description round-trip failed:\n got: %q\nwant: %q", h.Description, nasty)
+	}
+	md := string(fileByPath(t, files, "agents/lint-docs.md").Data)
+	if !strings.HasPrefix(md, "---\n") || strings.Count(md, "\n---\n") < 1 {
+		t.Errorf("agent definition frontmatter is malformed:\n%s", md[:200])
+	}
+}
+
+// TestSchemaIsValidJSON: the post-script and the validation loop both parse
+// it, so a malformed schema is a run-time failure.
+func TestSchemaIsValidJSON(t *testing.T) {
+	files, err := Render(testOptions("lint-docs", "triage"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(fileByPath(t, files, "schemas/lint-docs-result.schema.json").Data, &doc); err != nil {
+		t.Fatalf("schema is not valid JSON: %v", err)
+	}
+	if doc["additionalProperties"] != false {
+		t.Error("schema must set additionalProperties: false")
+	}
+	// Absolute per JSON Schema 2020-12: a bare relative reference has no
+	// base URI to resolve against in a file-local schema.
+	if doc["$id"] != "https://fullsend.sh/schemas/lint-docs-result.schema.json" {
+		t.Errorf("$id = %v", doc["$id"])
+	}
+	if doc["$schema"] != "https://json-schema.org/draft/2020-12/schema" {
+		t.Errorf("$schema = %v", doc["$schema"])
+	}
+}
+
+// TestPostScriptSubstitution: the agent name is the only user value that
+// reaches the shell script, and every placeholder must be consumed.
+func TestPostScriptSubstitution(t *testing.T) {
+	files, err := Render(testOptions("lint-docs", "triage"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	f := fileByPath(t, files, "scripts/post-lint-docs.sh")
+	script := string(f.Data)
+	if strings.Contains(script, "__") {
+		t.Errorf("unsubstituted placeholder remains in the post-script:\n%s", script)
+	}
+	if !strings.Contains(script, "POST_LINT_DOCS_DRY_RUN") {
+		t.Error("dry-run variable not derived from the agent name")
+	}
+	if !strings.Contains(script, "<!-- fullsend:lint-docs-agent -->") {
+		t.Error("sticky marker not derived from the agent name")
+	}
+	if f.Mode != 0o755 {
+		t.Errorf("post-script mode = %o, want 755", f.Mode)
+	}
+}
+
+func TestDryRunEnvVar(t *testing.T) {
+	for in, want := range map[string]string{
+		"lint-docs": "POST_LINT_DOCS_DRY_RUN",
+		"a":         "POST_A_DRY_RUN",
+		"a_b-c":     "POST_A_B_C_DRY_RUN",
+	} {
+		if got := DryRunEnvVar(in); got != want {
+			t.Errorf("DryRunEnvVar(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// TestSharedAssetsAreMarked: everything a generated agent does not own must
+// be flagged Shared so --force never overwrites it.
+func TestSharedAssetsAreMarked(t *testing.T) {
+	opts := testOptions("lint-docs", "retro")
+	opts.ValidationLoop = true
+	files, err := Render(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	owned := map[string]bool{
+		"harness/lint-docs.yaml":               true,
+		"agents/lint-docs.md":                  true,
+		"schemas/lint-docs-result.schema.json": true,
+		"scripts/post-lint-docs.sh":            true,
+	}
+	for _, f := range files {
+		if owned[f.Path] == f.Shared {
+			t.Errorf("%s: Shared = %v, want %v", f.Path, f.Shared, !owned[f.Path])
+		}
+	}
+	// retro is the two-forge-provider role: 3 providers + 3 profiles.
+	if got := len(files); got != 4+1+6+1 {
+		t.Errorf("retro with --validation-loop produced %d files, want 12", got)
+	}
+}
+
+func TestRenderRejectsUnknownRole(t *testing.T) {
+	opts := testOptions("lint-docs", "triage")
+	opts.Role = "scribe"
+	if _, err := Render(opts); err == nil {
+		t.Fatal("Render with an unknown role should fail")
+	}
+}
+
+func fileByPath(t *testing.T, files []File, path string) File {
+	t.Helper()
+	for _, f := range files {
+		if f.Path == path {
+			return f
+		}
+	}
+	t.Fatalf("no generated file at %q", path)
+	return File{}
+}
+
+func hasPath(files []File, path string) bool {
+	for _, f := range files {
+		if f.Path == path {
+			return true
+		}
+	}
+	return false
+}
+
+// TestPostScriptTruncatesWithinTheCap: the generated script advertises a
+// 16384-character limit and the result schema enforces it, so appending the
+// truncation marker after cutting at the cap would overshoot it.
+func TestPostScriptTruncatesWithinTheCap(t *testing.T) {
+	files, err := Render(testOptions("lint-docs", "triage"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	script := string(fileByPath(t, files, "scripts/post-lint-docs.sh").Data)
+
+	if strings.Contains(script, `comment="${comment:0:${MAX_COMMENT_CHARS}}"`) {
+		t.Error("comment is cut at the cap and then has the marker appended, which overshoots it")
+	}
+	for _, want := range []string{
+		"TRUNCATION_MARKER=",
+		"keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))",
+	} {
+		if !strings.Contains(script, want) {
+			t.Errorf("truncation should reserve room for the marker; missing %q", want)
+		}
+	}
+}
+
+// TestRoleImageReachesTheHarness covers what the per-role golden trees used
+// to: that each role's image constant actually lands in the generated
+// harness. The role table test asserts the table is right; this asserts the
+// value survives into the output, which is the half a table test cannot see.
+func TestRoleImageReachesTheHarness(t *testing.T) {
+	seen := map[string]bool{}
+	for _, name := range RoleNames() {
+		role, err := LookupRole(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		dir := t.TempDir()
+		files, err := Render(testOptions("lint-docs", name))
+		if err != nil {
+			t.Fatal(err)
+		}
+		writeTree(t, dir, files)
+
+		h, err := harness.Load(filepath.Join(dir, "harness", "lint-docs.yaml"))
+		if err != nil {
+			t.Fatalf("role %q: %v", name, err)
+		}
+		if h.Image != role.Image {
+			t.Errorf("role %q: harness image = %q, want %q", name, h.Image, role.Image)
+		}
+		if !reflect.DeepEqual(h.Providers, role.Providers) {
+			t.Errorf("role %q: providers = %v, want %v", name, h.Providers, role.Providers)
+		}
+		if h.OpenShell == nil || !reflect.DeepEqual(h.OpenShell.Profiles, role.Profiles) {
+			t.Errorf("role %q: profiles = %v, want %v", name, h.OpenShell, role.Profiles)
+		}
+		seen[role.Image] = true
+	}
+	// Both image constants must be reachable, or one is dead configuration.
+	if len(seen) != 2 {
+		t.Errorf("expected the role table to use both image constants, saw %d: %v", len(seen), seen)
+	}
+}
+
+// TestTriggerReachesTheHarness covers what the label-trigger golden used to.
+// The preset text itself is pinned by TestTriggerPresetsArePinned; this
+// asserts the chosen preset survives marshalling into the harness.
+func TestTriggerReachesTheHarness(t *testing.T) {
+	for _, on := range []string{"command", "label:needs-docs", "issue-opened", "pr-opened"} {
+		trigger, err := ExpandTrigger(on, "lint-docs")
+		if err != nil {
+			t.Fatal(err)
+		}
+		opts := testOptions("lint-docs", "triage")
+		opts.Trigger = trigger
+
+		dir := t.TempDir()
+		files, err := Render(opts)
+		if err != nil {
+			t.Fatal(err)
+		}
+		writeTree(t, dir, files)
+
+		h, err := harness.Load(filepath.Join(dir, "harness", "lint-docs.yaml"))
+		if err != nil {
+			t.Fatalf("--on %s: %v", on, err)
+		}
+		if strings.TrimSpace(h.Trigger) != strings.TrimSpace(trigger) {
+			t.Errorf("--on %s: trigger did not survive marshalling\n got: %q\nwant: %q", on, h.Trigger, trigger)
+		}
+	}
+}
diff --git a/internal/agentnew/roles.go b/internal/agentnew/roles.go
new file mode 100644
index 0000000000..461672b81b
--- /dev/null
+++ b/internal/agentnew/roles.go
@@ -0,0 +1,147 @@
+package agentnew
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/fullsend-ai/fullsend/internal/config"
+)
+
+// DefaultRole is the role assigned when --role is not given. It matches the
+// role the Bring Your Own Agent guide's examples use.
+const DefaultRole = "triage"
+
+// Role describes one mint role that `fullsend agent new` will generate for,
+// together with the sandbox resources a harness needs to run under it.
+//
+// The table is deliberately hardcoded rather than derived from
+// mintcore.BuiltInRoles(). Derivation would re-admit roles the rest of the
+// CLI excludes on purpose — config.ValidRoles() documents that mint-only
+// dogfood roles such as scribe "must not silently pass config validation" —
+// and it would fail open for any future canonical role that has no provider
+// pairing here. RoleTableMatchesMint (roles_test.go) fails CI if the mint
+// and this table drift apart.
+type Role struct {
+	// Name is the harness `role:` value and the mint role.
+	Name string
+	// Permissions mirrors mintcore's canonicalRolePermissions for this role.
+	// It is reproduced here so the CLI can explain what a role grants
+	// without importing the mint's internals into its help text.
+	Permissions map[string]string
+	// Providers are harness `providers:` entries, by path. Paths rather than
+	// bare names: a bare name that has no definition on disk degrades to a
+	// warning and then a sandbox that cannot reach Vertex, because the
+	// embedded provider fallback covers only the OpenAI provider.
+	Providers []string
+	// Profiles are harness `openshell.profiles:` entries, by path.
+	Profiles []string
+	// Image is the sandbox image this role's agents run under.
+	Image string
+}
+
+// roleTable is the set of roles `agent new` will generate for. Excluded on
+// purpose: `fix` (dispatch mints `coder` for both the code and fix stages, so
+// no fix App is enrolled), `fullsend` and `e2e` (infrastructure identities),
+// and `scribe` (recognised by the mint but absent from config.ValidRoles(),
+// DefaultAgentRoles() and PerRepoDefaultRoles(), and its fleet harness has no
+// forge provider pair to copy).
+var roleTable = map[string]Role{
+	"triage": {
+		Name:        "triage",
+		Permissions: map[string]string{"contents": "read", "issues": "write", "metadata": "read"},
+		Providers:   []string{"providers/vertex-ai.yaml", "providers/github-ro.yaml"},
+		Profiles:    []string{"profiles/fullsend-vertex-ai.yaml", "profiles/fullsend-github-ro.yaml"},
+		Image:       config.DefaultSandboxImage,
+	},
+	"review": {
+		Name: "review",
+		Permissions: map[string]string{
+			"contents": "read", "pull_requests": "write", "issues": "write",
+			"checks": "read", "metadata": "read",
+		},
+		Providers: []string{"providers/vertex-ai.yaml", "providers/github-ro.yaml"},
+		Profiles:  []string{"profiles/fullsend-vertex-ai.yaml", "profiles/fullsend-github-ro.yaml"},
+		Image:     config.DefaultCodeImage,
+	},
+	"coder": {
+		Name: "coder",
+		Permissions: map[string]string{
+			"contents": "write", "packages": "read", "pull_requests": "write",
+			"issues": "write", "checks": "read", "metadata": "read",
+		},
+		Providers: []string{"providers/vertex-ai.yaml", "providers/github.yaml"},
+		Profiles:  []string{"profiles/fullsend-vertex-ai.yaml", "profiles/fullsend-github.yaml"},
+		Image:     config.DefaultCodeImage,
+	},
+	"retro": {
+		Name: "retro",
+		Permissions: map[string]string{
+			"actions": "read", "contents": "read", "pull_requests": "write",
+			"issues": "write", "metadata": "read",
+		},
+		// retro is the only role taking two forge providers: github-ro for
+		// the repository and github-artifacts for workflow run artifacts.
+		Providers: []string{"providers/vertex-ai.yaml", "providers/github-ro.yaml", "providers/github-artifacts.yaml"},
+		Profiles: []string{
+			"profiles/fullsend-vertex-ai.yaml",
+			"profiles/fullsend-github-ro.yaml",
+			"profiles/fullsend-github-artifacts.yaml",
+		},
+		Image: config.DefaultSandboxImage,
+	},
+	"prioritize": {
+		Name: "prioritize",
+		Permissions: map[string]string{
+			"contents": "read", "issues": "write",
+			"organization_projects": "write", "metadata": "read",
+		},
+		Providers: []string{"providers/vertex-ai.yaml", "providers/github-ro.yaml"},
+		Profiles:  []string{"profiles/fullsend-vertex-ai.yaml", "profiles/fullsend-github-ro.yaml"},
+		Image:     config.DefaultSandboxImage,
+	},
+}
+
+// RoleNames returns the offered role names in table order.
+func RoleNames() []string {
+	names := make([]string, 0, len(roleTable))
+	for name := range roleTable {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// LookupRole returns the Role for name. An unknown role is an error carrying
+// the whole table, so the user sees the valid choices and their permissions
+// rather than discovering the problem as an opaque 403 from the mint at first
+// dispatch.
+func LookupRole(name string) (Role, error) {
+	if r, ok := roleTable[name]; ok {
+		return r, nil
+	}
+	return Role{}, fmt.Errorf("unknown role %q\n\n%s", name, RoleHelp())
+}
+
+// RoleHelp renders the role table for error messages and --help text.
+func RoleHelp() string {
+	var b strings.Builder
+	b.WriteString("The hosted mint serves these roles:\n\n")
+	for _, name := range RoleNames() {
+		r := roleTable[name]
+		perms := make([]string, 0, len(r.Permissions))
+		for k, v := range r.Permissions {
+			perms = append(perms, k+":"+v)
+		}
+		sort.Strings(perms)
+		suffix := ""
+		if name == DefaultRole {
+			suffix = "  (default)"
+		}
+		fmt.Fprintf(&b, "  %-11s %s%s\n", name, strings.Join(perms, ", "), suffix)
+	}
+	b.WriteString("\n\"scribe\" is recognised by the mint but is not wired for dispatch, so it is\n")
+	b.WriteString("not offered here. To use a role the hosted mint does not serve you need\n")
+	b.WriteString("your own mint — see docs/guides/user/custom-agent-identity.md.\n")
+	return b.String()
+}
diff --git a/internal/agentnew/roles_test.go b/internal/agentnew/roles_test.go
new file mode 100644
index 0000000000..0208526ac0
--- /dev/null
+++ b/internal/agentnew/roles_test.go
@@ -0,0 +1,128 @@
+package agentnew
+
+import (
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/fullsend-ai/fullsend/internal/config"
+	"github.com/fullsend-ai/fullsend/internal/mintcore"
+)
+
+// TestRoleTableMatchesMint is the anti-drift gate that lets roleTable stay
+// hardcoded. Deriving the table from mintcore.BuiltInRoles() would re-admit
+// roles the rest of the CLI excludes on purpose; this test instead fails CI
+// if the mint's permissions and this table stop agreeing.
+func TestRoleTableMatchesMint(t *testing.T) {
+	builtIn := mintcore.BuiltInRoles()
+	valid := config.ValidRoles()
+
+	for _, name := range RoleNames() {
+		t.Run(name, func(t *testing.T) {
+			role, err := LookupRole(name)
+			if err != nil {
+				t.Fatalf("LookupRole(%q): %v", name, err)
+			}
+			// BuiltInRoles, not HasRole: HasRole returns a unified view that
+			// includes standalone-mint custom roles registered at runtime,
+			// so it would pass for a role the hosted mint does not serve.
+			if !slices.Contains(builtIn, name) {
+				t.Errorf("role %q is not in mintcore.BuiltInRoles() %v", name, builtIn)
+			}
+			if !slices.Contains(valid, name) {
+				t.Errorf("role %q is not in config.ValidRoles() %v", name, valid)
+			}
+			if want := mintcore.RolePermissionsFor(name); !reflect.DeepEqual(role.Permissions, want) {
+				t.Errorf("permissions drifted from the mint\n got: %v\nwant: %v", role.Permissions, want)
+			}
+			if role.Name != name {
+				t.Errorf("roleTable[%q].Name = %q", name, role.Name)
+			}
+			if role.Image == "" {
+				t.Error("role has no image")
+			}
+			if len(role.Providers) != len(role.Profiles) {
+				t.Errorf("each provider needs a matching profile: %d providers, %d profiles",
+					len(role.Providers), len(role.Profiles))
+			}
+		})
+	}
+}
+
+// TestExcludedRolesAreRejected pins the roles agent new must never offer.
+// Each is excluded for a different reason and a regression on any of them
+// produces an opaque 403 from the mint at first dispatch rather than a
+// config error, so they are asserted individually.
+func TestExcludedRolesAreRejected(t *testing.T) {
+	for _, name := range []string{"fix", "fullsend", "e2e", "scribe", "", "Triage", "nonsense"} {
+		t.Run("role="+name, func(t *testing.T) {
+			if _, err := LookupRole(name); err == nil {
+				t.Fatalf("LookupRole(%q) succeeded; it must be rejected", name)
+			} else if !strings.Contains(err.Error(), "triage") {
+				t.Errorf("error should print the role table, got: %v", err)
+			}
+		})
+	}
+}
+
+// TestRoleHelpNamesScribe: a user who copies the fleet's scribe harness needs
+// a direct answer, since scribe IS a real mint role but is not wired for
+// dispatch. fix and fullsend are deliberately not mentioned.
+func TestRoleHelpNamesScribe(t *testing.T) {
+	help := RoleHelp()
+	if !strings.Contains(help, "scribe") {
+		t.Error("role help should explain why scribe is not offered")
+	}
+	for _, hidden := range []string{"fix", "fullsend", "e2e"} {
+		if strings.Contains(help, hidden) {
+			t.Errorf("role help should not mention %q", hidden)
+		}
+	}
+	for _, name := range RoleNames() {
+		if !strings.Contains(help, name) {
+			t.Errorf("role help omits %q", name)
+		}
+	}
+}
+
+func TestRetroIsTheOnlyTwoForgeProviderRole(t *testing.T) {
+	for _, name := range RoleNames() {
+		role, err := LookupRole(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		forge := 0
+		for _, p := range role.Providers {
+			if strings.Contains(p, "github") {
+				forge++
+			}
+		}
+		want := 1
+		if name == "retro" {
+			want = 2
+		}
+		if forge != want {
+			t.Errorf("role %q has %d forge providers, want %d (%v)", name, forge, want, role.Providers)
+		}
+	}
+}
+
+// TestCoderUsesEmbeddedGithubProvider guards the one provider-name trap: the
+// fleet's code harness uses providers/github-code.yaml, which the embedded
+// scaffold does not ship. A generated coder harness must name the bare
+// github provider that the scaffold does have.
+func TestCoderUsesEmbeddedGithubProvider(t *testing.T) {
+	role, err := LookupRole("coder")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, p := range role.Providers {
+		if strings.Contains(p, "github-code") {
+			t.Errorf("coder must not reference %q; the embedded scaffold has no github-code provider", p)
+		}
+	}
+	if !slices.Contains(role.Providers, "providers/github.yaml") {
+		t.Errorf("coder should use providers/github.yaml, got %v", role.Providers)
+	}
+}
diff --git a/internal/agentnew/spec.go b/internal/agentnew/spec.go
new file mode 100644
index 0000000000..09412f713c
--- /dev/null
+++ b/internal/agentnew/spec.go
@@ -0,0 +1,85 @@
+package agentnew
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+// SpecVersion is the only accepted `version:` value in a spec file.
+const SpecVersion = "1"
+
+// AgentSpec is the document accepted by `fullsend agent new -f <file>`. Keys
+// mirror the command-line flags one for one so a local coding agent can emit
+// either form. Command-line flags override spec keys.
+type AgentSpec struct {
+	Version        string `yaml:"version"`
+	Name           string `yaml:"name"`
+	Role           string `yaml:"role,omitempty"`
+	Description    string `yaml:"description,omitempty"`
+	On             string `yaml:"on,omitempty"`
+	Trigger        string `yaml:"trigger,omitempty"`
+	Model          string `yaml:"model,omitempty"`
+	Effort         string `yaml:"effort,omitempty"`
+	Runtime        string `yaml:"runtime,omitempty"`
+	Slug           string `yaml:"slug,omitempty"`
+	Image          string `yaml:"image,omitempty"`
+	TimeoutMinutes *int   `yaml:"timeout_minutes,omitempty"`
+	ValidationLoop bool   `yaml:"validation_loop,omitempty"`
+}
+
+// LoadSpecFile reads and validates a spec file.
+func LoadSpecFile(path string) (*AgentSpec, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("reading spec file: %w", err)
+	}
+	return ParseSpec(data)
+}
+
+// ParseSpec decodes a spec document. Unknown keys are an error rather than a
+// silent no-op: a typo in a spec file would otherwise generate a different
+// agent than the author asked for, which is the failure mode this command
+// exists to remove.
+func ParseSpec(data []byte) (*AgentSpec, error) {
+	dec := yaml.NewDecoder(bytes.NewReader(data))
+	dec.KnownFields(true)
+
+	var spec AgentSpec
+	if err := dec.Decode(&spec); err != nil {
+		if errors.Is(err, io.EOF) {
+			return nil, fmt.Errorf("spec file is empty")
+		}
+		return nil, fmt.Errorf("parsing spec file: %w", err)
+	}
+	// A second document would be silently ignored otherwise. Only a real EOF
+	// means "there was nothing more": any other error is a malformed second
+	// document, which must be reported rather than treated as absence.
+	var extra AgentSpec
+	switch err := dec.Decode(&extra); {
+	case err == nil:
+		return nil, fmt.Errorf("spec file must contain exactly one YAML document")
+	case errors.Is(err, io.EOF):
+		// The expected case: one document, cleanly ended.
+	default:
+		return nil, fmt.Errorf("parsing spec file: %w", err)
+	}
+
+	if spec.Version != SpecVersion {
+		return nil, fmt.Errorf("spec version must be %q, got %q", SpecVersion, spec.Version)
+	}
+	if spec.Name == "" {
+		return nil, fmt.Errorf("spec field \"name\" is required")
+	}
+	if spec.On != "" && spec.Trigger != "" {
+		return nil, fmt.Errorf("spec fields \"on\" and \"trigger\" are mutually exclusive")
+	}
+	if spec.TimeoutMinutes != nil && *spec.TimeoutMinutes < 0 {
+		return nil, fmt.Errorf("spec field \"timeout_minutes\" must not be negative, got %d", *spec.TimeoutMinutes)
+	}
+	return &spec, nil
+}
diff --git a/internal/agentnew/spec_test.go b/internal/agentnew/spec_test.go
new file mode 100644
index 0000000000..39599e662d
--- /dev/null
+++ b/internal/agentnew/spec_test.go
@@ -0,0 +1,103 @@
+package agentnew
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParseSpec(t *testing.T) {
+	spec, err := ParseSpec([]byte(`
+version: "1"
+name: lint-docs
+role: triage
+description: Check docs changes for broken links
+on: command:/fs-lint-docs
+model: opus
+effort: high
+runtime: claude
+slug: my-org-lint-docs
+timeout_minutes: 20
+validation_loop: true
+`))
+	if err != nil {
+		t.Fatalf("ParseSpec: %v", err)
+	}
+	if spec.Name != "lint-docs" || spec.Role != "triage" {
+		t.Errorf("unexpected spec: %+v", spec)
+	}
+	if spec.TimeoutMinutes == nil || *spec.TimeoutMinutes != 20 || !spec.ValidationLoop {
+		t.Errorf("unexpected spec: %+v", spec)
+	}
+	if spec.Description != "Check docs changes for broken links" {
+		t.Errorf("description: %q", spec.Description)
+	}
+}
+
+func TestParseSpecRejects(t *testing.T) {
+	tests := []struct {
+		name, doc, wantErr string
+	}{
+		{"unknown key", "version: \"1\"\nname: a\nrol: triage\n", "field rol not found"},
+		{"missing version", "name: a\n", "version"},
+		{"wrong version", "version: \"2\"\nname: a\n", "version"},
+		{"missing name", "version: \"1\"\n", "name"},
+		{"on and trigger", "version: \"1\"\nname: a\non: label\ntrigger: 'true'\n", "mutually exclusive"},
+		{"negative timeout", "version: \"1\"\nname: a\ntimeout_minutes: -1\n", "negative"},
+		{"empty", "", "empty"},
+		{"two documents", "version: \"1\"\nname: a\n---\nversion: \"1\"\nname: b\n", "exactly one"},
+		{"not a mapping", "- a\n- b\n", "parsing spec file"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := ParseSpec([]byte(tc.doc))
+			if err == nil {
+				t.Fatalf("ParseSpec(%q) succeeded; want error", tc.doc)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Errorf("error %q should mention %q", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+func TestLoadSpecFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "spec.yaml")
+	if err := os.WriteFile(path, []byte("version: \"1\"\nname: lint-docs\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	spec, err := LoadSpecFile(path)
+	if err != nil {
+		t.Fatalf("LoadSpecFile: %v", err)
+	}
+	if spec.Name != "lint-docs" {
+		t.Errorf("name: %q", spec.Name)
+	}
+
+	if _, err := LoadSpecFile(filepath.Join(dir, "missing.yaml")); err == nil {
+		t.Error("LoadSpecFile on a missing path should fail")
+	}
+}
+
+// TestParseSpecDistinguishesZeroFromOmitted: `timeout_minutes: 0` is a real
+// choice, and reading the zero value as "omitted" would silently replace it
+// with the 15-minute default.
+func TestParseSpecDistinguishesZeroFromOmitted(t *testing.T) {
+	omitted, err := ParseSpec([]byte("version: \"1\"\nname: a\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if omitted.TimeoutMinutes != nil {
+		t.Errorf("an omitted timeout should be nil, got %v", *omitted.TimeoutMinutes)
+	}
+
+	zero, err := ParseSpec([]byte("version: \"1\"\nname: a\ntimeout_minutes: 0\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if zero.TimeoutMinutes == nil || *zero.TimeoutMinutes != 0 {
+		t.Errorf("an explicit 0 should survive, got %v", zero.TimeoutMinutes)
+	}
+}
diff --git a/internal/agentnew/templates/agent-body.md.tmpl b/internal/agentnew/templates/agent-body.md.tmpl
new file mode 100644
index 0000000000..9aba5b1011
--- /dev/null
+++ b/internal/agentnew/templates/agent-body.md.tmpl
@@ -0,0 +1,41 @@
+You are the __AGENT_NAME__ agent. <!-- FILL IN: one sentence on what this agent
+decides, in the imperative. Keep it to the single decision the result schema
+encodes. -->
+
+## Inputs
+
+- `ISSUE_URL` — the HTML URL of the work item this run was dispatched for.
+- The target repository is checked out at the sandbox working directory.
+
+<!-- FILL IN: any other environment variables your harness passes in
+`env.sandbox`. Every variable you name here must exist in the harness, or the
+agent will read an empty string at run time. -->
+
+## Steps
+
+1. Fetch the work item with `gh issue view "$ISSUE_URL" --json title,body,labels`.
+   If the command fails, write an error result (see Output contract) and stop.
+2. <!-- FILL IN: the analysis this agent performs. Be specific — name the
+   files, the thresholds, and the decision boundaries. A vague step here is the
+   single most common reason a custom agent produces unusable output. -->
+3. <!-- FILL IN: the decision. State explicitly what makes the result `ok`
+   versus `findings` versus `error`. -->
+
+## Output contract
+
+Write exactly one JSON object to `$FULLSEND_OUTPUT_DIR/agent-result.json`:
+
+```json
+{
+  "status": "findings",
+  "summary": "One line describing what you found",
+  "comment": "### Findings\n\n- ...\n"
+}
+```
+
+- `status` — one of `ok`, `findings`, `error`.
+- `summary` — one line, at most 200 characters. Used as the comment heading.
+- `comment` — Markdown body posted on the work item, at most 16384 characters.
+
+Do not push commits, open issues, apply labels, or call any mutating API. The
+post-script performs every side effect; your only output is this file.
diff --git a/internal/agentnew/templates/policies/base.yaml b/internal/agentnew/templates/policies/base.yaml
new file mode 100644
index 0000000000..a5816d1bfb
--- /dev/null
+++ b/internal/agentnew/templates/policies/base.yaml
@@ -0,0 +1,22 @@
+---
+version: 1
+
+# Base sandbox policy shared by all agents.
+#
+# Defines non-composable sandbox restrictions: filesystem access,
+# landlock, and process identity. Network access is provided
+# entirely by provider profiles via provider-backed policy
+# composition (ADR 0065).
+#
+# curl is deliberately excluded from all profile binary allowlists
+# to prevent raw HTTP access with the injected GH_TOKEN.
+
+filesystem_policy:
+  include_workdir: true
+  read_only: [/usr, /lib, /proc, /dev/urandom, /app, /etc, /var/log]
+  read_write: [/sandbox, /tmp, /dev/null]
+landlock:
+  compatibility: best_effort
+process:
+  run_as_user: sandbox
+  run_as_group: sandbox
diff --git a/internal/agentnew/templates/post.sh.tmpl b/internal/agentnew/templates/post.sh.tmpl
new file mode 100644
index 0000000000..6f37c752ed
--- /dev/null
+++ b/internal/agentnew/templates/post.sh.tmpl
@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# post-__AGENT_NAME__.sh — turn the __AGENT_NAME__ agent's JSON result into one comment.
+#
+# Generated by `fullsend agent new`. Safe to edit.
+#
+# Runs on the trusted runner after the sandbox exits. The working directory is
+# the RUN directory, and the agent's output lives one level down, in
+# iteration-<N>/output/agent-result.json — fullsend runs the agent once per
+# iteration and only the last one counts.
+#
+# Required env:
+#   ISSUE_URL — HTML URL of the work item (the harness maps GITHUB_ISSUE_URL to it)
+#   GH_TOKEN  — minted by fullsend from the harness `role:` field
+#
+# Optional env:
+#   FULLSEND_VALIDATED_ITERATION_DIR — set by fullsend when a validation_loop
+#     is configured and an iteration passed it. When present it names the
+#     iteration whose output was validated, which is not necessarily the last
+#     one, so it wins over the scan below.
+#
+# Treat the result file as untrusted: it is model output. Only the three
+# fields below are ever read, each is required to be a string, and the
+# comment body is piped on stdin rather than interpolated into a command.
+
+set -euo pipefail
+
+# ${#var} and ${var:0:n} count characters in a UTF-8 locale and BYTES under
+# C/POSIX. The result schema's maxLength counts Unicode code points, so
+# without this a valid multibyte summary is rejected as too long and
+# truncation can slice mid-character.
+export LC_ALL="${LC_ALL:-C.UTF-8}"
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+MARKER="<!-- fullsend:__AGENT_NAME__-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+# Locate the result. FULLSEND_VALIDATED_ITERATION_DIR is set by fullsend on
+# the runner, not by the sandbox or the agent, so it is trusted as given.
+RESULT_FILE=""
+if [[ -n "${FULLSEND_VALIDATED_ITERATION_DIR:-}" ]]; then
+  if [[ -f "${FULLSEND_VALIDATED_ITERATION_DIR}/agent-result.json" ]]; then
+    RESULT_FILE="${FULLSEND_VALIDATED_ITERATION_DIR}/agent-result.json"
+  else
+    echo "post-__AGENT_NAME__: FULLSEND_VALIDATED_ITERATION_DIR is set but has no agent-result.json" >&2
+    exit 1
+  fi
+else
+  # No validation loop configured: take the HIGHEST-numbered iteration that
+  # produced output. Compared numerically, not by glob order — the glob sorts
+  # lexicographically, which puts iteration-10 before iteration-9.
+  _best=-1
+  for _dir in iteration-*/output; do
+    [[ -f "${_dir}/agent-result.json" ]] || continue
+    _n="${_dir%/output}"
+    _n="${_n#iteration-}"
+    [[ "${_n}" =~ ^[0-9]+$ ]] || continue
+    if (( _n > _best )); then
+      _best="${_n}"
+      RESULT_FILE="${_dir}/agent-result.json"
+    fi
+  done
+fi
+
+if [[ -z "${RESULT_FILE}" || ! -f "${RESULT_FILE}" ]]; then
+  echo "post-__AGENT_NAME__: no agent-result.json found in any iteration-*/output directory" >&2
+  exit 1
+fi
+if ! jq -e 'type == "object"' "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-__AGENT_NAME__: ${RESULT_FILE} is not a JSON object" >&2
+  exit 1
+fi
+
+# Field allowlist: anything else in the file is ignored by construction.
+status=$(jq -r 'if (.status | type) == "string" then .status else empty end' "${RESULT_FILE}")
+summary=$(jq -r 'if (.summary | type) == "string" then .summary else empty end' "${RESULT_FILE}")
+comment=$(jq -r 'if (.comment | type) == "string" then .comment else empty end' "${RESULT_FILE}")
+
+case "${status}" in
+  ok|findings|error) ;;
+  *) echo "post-__AGENT_NAME__: status must be ok, findings or error (got '${status}')" >&2; exit 1 ;;
+esac
+[[ -n "${summary}" ]] || { echo "post-__AGENT_NAME__: summary is required" >&2; exit 1; }
+if [[ "${summary}" == *$'\n'* || "${summary}" == *$'\r'* ]]; then
+  echo "post-__AGENT_NAME__: summary must be a single line" >&2
+  exit 1
+fi
+[[ -n "${comment}" ]] || { echo "post-__AGENT_NAME__: comment is required" >&2; exit 1; }
+if (( ${#summary} > MAX_SUMMARY_CHARS )); then
+  echo "post-__AGENT_NAME__: summary exceeds ${MAX_SUMMARY_CHARS} characters" >&2
+  exit 1
+fi
+# Truncate to MAX_COMMENT_CHARS *including* the marker, so the result never
+# exceeds the cap the schema declares.
+TRUNCATION_MARKER=$'\n\n_(truncated)_'
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
+fi
+
+if [[ "${status}" == "ok" ]]; then
+  echo "post-__AGENT_NAME__: status=ok, nothing to post" >&2
+  exit 0
+fi
+
+# Derive the repo and number from the work item URL rather than trusting extra
+# environment. The pattern also rejects anything that is not a github.com URL.
+url_re='^https://github[.]com/([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)/(issues|pull)/([0-9]+)$'
+if [[ ! "${ISSUE_URL}" =~ ${url_re} ]]; then
+  echo "post-__AGENT_NAME__: ISSUE_URL is not a GitHub issue or pull request URL" >&2
+  exit 1
+fi
+REPO="${BASH_REMATCH[1]}"
+NUMBER="${BASH_REMATCH[3]}"
+
+if [[ "${__DRY_RUN_VAR__:-}" == "1" ]]; then
+  printf '**%s**\n\n%s\n' "${summary}" "${comment}"
+  echo "post-__AGENT_NAME__: dry run, not posting" >&2
+  exit 0
+fi
+
+# fullsend issues post-comment is the repo's sticky-comment primitive: it
+# finds this agent's previous comment by marker and edits it in place, so
+# re-runs do not flood the work item.
+printf '**%s**\n\n%s\n' "${summary}" "${comment}" \
+  | fullsend issues post-comment \
+      --tracker github \
+      --project "${REPO}" \
+      --number "${NUMBER}" \
+      --marker "${MARKER}" \
+      --result -
diff --git a/internal/agentnew/templates/scripts/validate-output-schema.sh b/internal/agentnew/templates/scripts/validate-output-schema.sh
new file mode 100755
index 0000000000..e074aaf15d
--- /dev/null
+++ b/internal/agentnew/templates/scripts/validate-output-schema.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# validate-output-schema.sh — Validate agent output against a JSON Schema.
+#
+# Generic script used by the harness validation_loop (ADR 0022).
+# Works for any agent — the schema path is configured in the harness.
+#
+# Required env vars:
+#   FULLSEND_OUTPUT_SCHEMA — path to the JSON Schema file
+#
+# Optional env vars:
+#   FULLSEND_OUTPUT_FILE  — filename to validate (default: agent-result.json)
+#
+# The script looks for the output file in the iteration output directory.
+# The working directory is the iteration dir (set by run.go).
+
+set -euo pipefail
+
+: "${FULLSEND_OUTPUT_SCHEMA:?FULLSEND_OUTPUT_SCHEMA must be set}"
+
+# Find the output JSON file in this iteration's output directory.
+OUTPUT_DIR="output"
+if [[ ! -d "${OUTPUT_DIR}" ]]; then
+  echo "FAIL: output directory not found"
+  exit 1
+fi
+
+_output_file="${FULLSEND_OUTPUT_FILE:-agent-result.json}"
+_output_file="$(basename "${_output_file}")"
+RESULT_FILE="${OUTPUT_DIR}/${_output_file}"
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "FAIL: ${RESULT_FILE} not found"
+  exit 1
+fi
+echo "Validating: ${RESULT_FILE} against ${FULLSEND_OUTPUT_SCHEMA}"
+
+# Validate JSON is parseable.
+if ! python3 -m json.tool "${RESULT_FILE}" > /dev/null 2>&1; then
+  echo "FAIL: ${RESULT_FILE} is not valid JSON"
+  exit 1
+fi
+
+# Validate against schema using Python's jsonschema.
+# jsonschema is required — fail hard if not installed.
+if ! python3 -c "import jsonschema" 2>/dev/null; then
+  echo "FAIL: python3 jsonschema package is not installed (required by ADR 0022)"
+  exit 1
+fi
+
+if ! python3 -c "
+import json, sys
+from jsonschema import validate, ValidationError
+
+with open(sys.argv[1]) as f:
+    instance = json.load(f)
+with open(sys.argv[2]) as f:
+    schema = json.load(f)
+try:
+    validate(instance=instance, schema=schema)
+    print('PASS: output validated against schema')
+except ValidationError as e:
+    print(f'FAIL: schema validation error: {e.message}')
+    if e.path:
+        print(f'  at: {\".\".join(str(p) for p in e.path)}')
+    if 'properties' in e.schema:
+        allowed = ', '.join(sorted(e.schema['properties'].keys()))
+        print(f'  allowed properties: {allowed}')
+    sys.exit(1)
+" "${RESULT_FILE}" "${FULLSEND_OUTPUT_SCHEMA}"; then
+  exit 1
+fi
diff --git a/internal/agentnew/testdata/golden/triage.txt b/internal/agentnew/testdata/golden/triage.txt
new file mode 100644
index 0000000000..0abf504bd4
--- /dev/null
+++ b/internal/agentnew/testdata/golden/triage.txt
@@ -0,0 +1,282 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob, Write
+model: opus
+---
+
+You are the lint-docs agent. <!-- FILL IN: one sentence on what this agent
+decides, in the imperative. Keep it to the single decision the result schema
+encodes. -->
+
+## Inputs
+
+- `ISSUE_URL` — the HTML URL of the work item this run was dispatched for.
+- The target repository is checked out at the sandbox working directory.
+
+<!-- FILL IN: any other environment variables your harness passes in
+`env.sandbox`. Every variable you name here must exist in the harness, or the
+agent will read an empty string at run time. -->
+
+## Steps
+
+1. Fetch the work item with `gh issue view "$ISSUE_URL" --json title,body,labels`.
+   If the command fails, write an error result (see Output contract) and stop.
+2. <!-- FILL IN: the analysis this agent performs. Be specific — name the
+   files, the thresholds, and the decision boundaries. A vague step here is the
+   single most common reason a custom agent produces unusable output. -->
+3. <!-- FILL IN: the decision. State explicitly what makes the result `ok`
+   versus `findings` versus `error`. -->
+
+## Output contract
+
+Write exactly one JSON object to `$FULLSEND_OUTPUT_DIR/agent-result.json`:
+
+```json
+{
+  "status": "findings",
+  "summary": "One line describing what you found",
+  "comment": "### Findings\n\n- ...\n"
+}
+```
+
+- `status` — one of `ok`, `findings`, `error`.
+- `summary` — one line, at most 200 characters. Used as the comment heading.
+- `comment` — Markdown body posted on the work item, at most 16384 characters.
+
+Do not push commits, open issues, apply labels, or call any mutating API. The
+post-script performs every side effect; your only output is this file.
+=== harness/lint-docs.yaml mode=644
+---
+# Generated by `fullsend agent new lint-docs`. Edit freely — nothing
+# regenerates this file.
+#
+# `image:` is the container image this agent runs inside, recorded as
+# an exact digest so every run uses the same one. Pass --image to
+# choose a different one.
+#
+# This agent handles GitHub only. To add GitLab or Jira, see
+# docs/guides/user/bring-your-own-agent.md.
+agent: agents/lint-docs.md
+description: Check docs changes for broken links
+role: triage
+slug: my-org-lint-docs
+image: ghcr.io/fullsend-ai/fullsend-sandbox@sha256:f8255971fec8a72a60adb20f501e55098f237e699dc829f0894647c0de2a19c2
+policy: policies/base.yaml
+providers:
+  - providers/vertex-ai.yaml
+  - providers/github-ro.yaml
+openshell:
+  profiles:
+    - profiles/fullsend-vertex-ai.yaml
+    - profiles/fullsend-github-ro.yaml
+host_files:
+  - src: ${GOOGLE_APPLICATION_CREDENTIALS}
+    dest: /tmp/.gcp-credentials.json
+  - src: ${GCP_OIDC_TOKEN_FILE}
+    dest: /sandbox/workspace/.gcp-oidc-token
+    optional: true
+model: opus
+effort: high
+post_script: scripts/post-lint-docs.sh
+env:
+  runner:
+    FULLSEND_FORGE: github
+    GH_TOKEN: ${GH_TOKEN}
+    ISSUE_URL: ${GITHUB_ISSUE_URL}
+  sandbox:
+    ANTHROPIC_VERTEX_PROJECT_ID: ${ANTHROPIC_VERTEX_PROJECT_ID}
+    CLAUDE_CODE_USE_VERTEX: "1"
+    CLOUD_ML_REGION: ${CLOUD_ML_REGION}
+    FULLSEND_FORGE: github
+    GH_TOKEN: ${GH_TOKEN}
+    GOOGLE_APPLICATION_CREDENTIALS: /tmp/.gcp-credentials.json
+    ISSUE_URL: ${GITHUB_ISSUE_URL}
+timeout_minutes: 15
+trigger: |
+  event.transition.kind == "comment_added"
+    && event.entity.kind == "work_item"
+    && has(event.transition.comment.command)
+    && event.transition.comment.command == "/fs-lint-docs"
+    && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
+=== policies/base.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== profiles/fullsend-github-ro.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== profiles/fullsend-vertex-ai.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== providers/github-ro.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== providers/vertex-ai.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== schemas/lint-docs-result.schema.json mode=644
+{
+  "$id": "https://fullsend.sh/schemas/lint-docs-result.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Structured output from the lint-docs agent, consumed by scripts/post-lint-docs.sh.",
+  "properties": {
+    "comment": {
+      "maxLength": 16384,
+      "minLength": 1,
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ok",
+        "findings",
+        "error"
+      ],
+      "type": "string"
+    },
+    "summary": {
+      "maxLength": 200,
+      "minLength": 1,
+      "pattern": "^[^\\r\\n]*$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "summary",
+    "comment"
+  ],
+  "title": "lint-docs Agent Result",
+  "type": "object"
+}
+=== scripts/post-lint-docs.sh mode=755
+#!/usr/bin/env bash
+# post-lint-docs.sh — turn the lint-docs agent's JSON result into one comment.
+#
+# Generated by `fullsend agent new`. Safe to edit.
+#
+# Runs on the trusted runner after the sandbox exits. The working directory is
+# the RUN directory, and the agent's output lives one level down, in
+# iteration-<N>/output/agent-result.json — fullsend runs the agent once per
+# iteration and only the last one counts.
+#
+# Required env:
+#   ISSUE_URL — HTML URL of the work item (the harness maps GITHUB_ISSUE_URL to it)
+#   GH_TOKEN  — minted by fullsend from the harness `role:` field
+#
+# Optional env:
+#   FULLSEND_VALIDATED_ITERATION_DIR — set by fullsend when a validation_loop
+#     is configured and an iteration passed it. When present it names the
+#     iteration whose output was validated, which is not necessarily the last
+#     one, so it wins over the scan below.
+#
+# Treat the result file as untrusted: it is model output. Only the three
+# fields below are ever read, each is required to be a string, and the
+# comment body is piped on stdin rather than interpolated into a command.
+
+set -euo pipefail
+
+# ${#var} and ${var:0:n} count characters in a UTF-8 locale and BYTES under
+# C/POSIX. The result schema's maxLength counts Unicode code points, so
+# without this a valid multibyte summary is rejected as too long and
+# truncation can slice mid-character.
+export LC_ALL="${LC_ALL:-C.UTF-8}"
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+# Locate the result. FULLSEND_VALIDATED_ITERATION_DIR is set by fullsend on
+# the runner, not by the sandbox or the agent, so it is trusted as given.
+RESULT_FILE=""
+if [[ -n "${FULLSEND_VALIDATED_ITERATION_DIR:-}" ]]; then
+  if [[ -f "${FULLSEND_VALIDATED_ITERATION_DIR}/agent-result.json" ]]; then
+    RESULT_FILE="${FULLSEND_VALIDATED_ITERATION_DIR}/agent-result.json"
+  else
+    echo "post-lint-docs: FULLSEND_VALIDATED_ITERATION_DIR is set but has no agent-result.json" >&2
+    exit 1
+  fi
+else
+  # No validation loop configured: take the HIGHEST-numbered iteration that
+  # produced output. Compared numerically, not by glob order — the glob sorts
+  # lexicographically, which puts iteration-10 before iteration-9.
+  _best=-1
+  for _dir in iteration-*/output; do
+    [[ -f "${_dir}/agent-result.json" ]] || continue
+    _n="${_dir%/output}"
+    _n="${_n#iteration-}"
+    [[ "${_n}" =~ ^[0-9]+$ ]] || continue
+    if (( _n > _best )); then
+      _best="${_n}"
+      RESULT_FILE="${_dir}/agent-result.json"
+    fi
+  done
+fi
+
+if [[ -z "${RESULT_FILE}" || ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: no agent-result.json found in any iteration-*/output directory" >&2
+  exit 1
+fi
+if ! jq -e 'type == "object"' "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not a JSON object" >&2
+  exit 1
+fi
+
+# Field allowlist: anything else in the file is ignored by construction.
+status=$(jq -r 'if (.status | type) == "string" then .status else empty end' "${RESULT_FILE}")
+summary=$(jq -r 'if (.summary | type) == "string" then .summary else empty end' "${RESULT_FILE}")
+comment=$(jq -r 'if (.comment | type) == "string" then .comment else empty end' "${RESULT_FILE}")
+
+case "${status}" in
+  ok|findings|error) ;;
+  *) echo "post-lint-docs: status must be ok, findings or error (got '${status}')" >&2; exit 1 ;;
+esac
+[[ -n "${summary}" ]] || { echo "post-lint-docs: summary is required" >&2; exit 1; }
+if [[ "${summary}" == *$'\n'* || "${summary}" == *$'\r'* ]]; then
+  echo "post-lint-docs: summary must be a single line" >&2
+  exit 1
+fi
+[[ -n "${comment}" ]] || { echo "post-lint-docs: comment is required" >&2; exit 1; }
+if (( ${#summary} > MAX_SUMMARY_CHARS )); then
+  echo "post-lint-docs: summary exceeds ${MAX_SUMMARY_CHARS} characters" >&2
+  exit 1
+fi
+# Truncate to MAX_COMMENT_CHARS *including* the marker, so the result never
+# exceeds the cap the schema declares.
+TRUNCATION_MARKER=$'\n\n_(truncated)_'
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
+fi
+
+if [[ "${status}" == "ok" ]]; then
+  echo "post-lint-docs: status=ok, nothing to post" >&2
+  exit 0
+fi
+
+# Derive the repo and number from the work item URL rather than trusting extra
+# environment. The pattern also rejects anything that is not a github.com URL.
+url_re='^https://github[.]com/([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)/(issues|pull)/([0-9]+)$'
+if [[ ! "${ISSUE_URL}" =~ ${url_re} ]]; then
+  echo "post-lint-docs: ISSUE_URL is not a GitHub issue or pull request URL" >&2
+  exit 1
+fi
+REPO="${BASH_REMATCH[1]}"
+NUMBER="${BASH_REMATCH[3]}"
+
+if [[ "${POST_LINT_DOCS_DRY_RUN:-}" == "1" ]]; then
+  printf '**%s**\n\n%s\n' "${summary}" "${comment}"
+  echo "post-lint-docs: dry run, not posting" >&2
+  exit 0
+fi
+
+# fullsend issues post-comment is the repo's sticky-comment primitive: it
+# finds this agent's previous comment by marker and edits it in place, so
+# re-runs do not flood the work item.
+printf '**%s**\n\n%s\n' "${summary}" "${comment}" \
+  | fullsend issues post-comment \
+      --tracker github \
+      --project "${REPO}" \
+      --number "${NUMBER}" \
+      --marker "${MARKER}" \
+      --result -
diff --git a/internal/agentnew/testdata/golden/validation-loop.txt b/internal/agentnew/testdata/golden/validation-loop.txt
new file mode 100644
index 0000000000..c17225dbc0
--- /dev/null
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -0,0 +1,292 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq,fullsend-check-output), Read, Grep, Glob, Write
+model: opus
+---
+
+You are the lint-docs agent. <!-- FILL IN: one sentence on what this agent
+decides, in the imperative. Keep it to the single decision the result schema
+encodes. -->
+
+## Inputs
+
+- `ISSUE_URL` — the HTML URL of the work item this run was dispatched for.
+- The target repository is checked out at the sandbox working directory.
+
+<!-- FILL IN: any other environment variables your harness passes in
+`env.sandbox`. Every variable you name here must exist in the harness, or the
+agent will read an empty string at run time. -->
+
+## Steps
+
+1. Fetch the work item with `gh issue view "$ISSUE_URL" --json title,body,labels`.
+   If the command fails, write an error result (see Output contract) and stop.
+2. <!-- FILL IN: the analysis this agent performs. Be specific — name the
+   files, the thresholds, and the decision boundaries. A vague step here is the
+   single most common reason a custom agent produces unusable output. -->
+3. <!-- FILL IN: the decision. State explicitly what makes the result `ok`
+   versus `findings` versus `error`. -->
+
+## Output contract
+
+Write exactly one JSON object to `$FULLSEND_OUTPUT_DIR/agent-result.json`:
+
+```json
+{
+  "status": "findings",
+  "summary": "One line describing what you found",
+  "comment": "### Findings\n\n- ...\n"
+}
+```
+
+- `status` — one of `ok`, `findings`, `error`.
+- `summary` — one line, at most 200 characters. Used as the comment heading.
+- `comment` — Markdown body posted on the work item, at most 16384 characters.
+
+Do not push commits, open issues, apply labels, or call any mutating API. The
+post-script performs every side effect; your only output is this file.
+
+Before you finish, run `fullsend-check-output "$FULLSEND_OUTPUT_DIR/agent-result.json"`
+to catch schema violations while you can still fix them.
+=== harness/lint-docs.yaml mode=644
+---
+# Generated by `fullsend agent new lint-docs`. Edit freely — nothing
+# regenerates this file.
+#
+# `image:` is the container image this agent runs inside, recorded as
+# an exact digest so every run uses the same one. Pass --image to
+# choose a different one.
+#
+# This agent handles GitHub only. To add GitLab or Jira, see
+# docs/guides/user/bring-your-own-agent.md.
+agent: agents/lint-docs.md
+description: Check docs changes for broken links
+role: triage
+slug: my-org-lint-docs
+image: ghcr.io/fullsend-ai/fullsend-sandbox@sha256:f8255971fec8a72a60adb20f501e55098f237e699dc829f0894647c0de2a19c2
+policy: policies/base.yaml
+providers:
+  - providers/vertex-ai.yaml
+  - providers/github-ro.yaml
+openshell:
+  profiles:
+    - profiles/fullsend-vertex-ai.yaml
+    - profiles/fullsend-github-ro.yaml
+host_files:
+  - src: ${GOOGLE_APPLICATION_CREDENTIALS}
+    dest: /tmp/.gcp-credentials.json
+  - src: ${GCP_OIDC_TOKEN_FILE}
+    dest: /sandbox/workspace/.gcp-oidc-token
+    optional: true
+model: opus
+effort: high
+post_script: scripts/post-lint-docs.sh
+validation_loop:
+  script: scripts/validate-output-schema.sh
+  schema: schemas/lint-docs-result.schema.json
+  max_iterations: 2
+  preflight_check: python3 -c "import jsonschema"
+env:
+  runner:
+    FULLSEND_FORGE: github
+    GH_TOKEN: ${GH_TOKEN}
+    ISSUE_URL: ${GITHUB_ISSUE_URL}
+  sandbox:
+    ANTHROPIC_VERTEX_PROJECT_ID: ${ANTHROPIC_VERTEX_PROJECT_ID}
+    CLAUDE_CODE_USE_VERTEX: "1"
+    CLOUD_ML_REGION: ${CLOUD_ML_REGION}
+    FULLSEND_FORGE: github
+    GH_TOKEN: ${GH_TOKEN}
+    GOOGLE_APPLICATION_CREDENTIALS: /tmp/.gcp-credentials.json
+    ISSUE_URL: ${GITHUB_ISSUE_URL}
+timeout_minutes: 15
+trigger: |
+  event.transition.kind == "comment_added"
+    && event.entity.kind == "work_item"
+    && has(event.transition.comment.command)
+    && event.transition.comment.command == "/fs-lint-docs"
+    && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
+=== policies/base.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== profiles/fullsend-github-ro.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== profiles/fullsend-vertex-ai.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== providers/github-ro.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== providers/vertex-ai.yaml mode=644 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
+=== schemas/lint-docs-result.schema.json mode=644
+{
+  "$id": "https://fullsend.sh/schemas/lint-docs-result.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Structured output from the lint-docs agent, consumed by scripts/post-lint-docs.sh.",
+  "properties": {
+    "comment": {
+      "maxLength": 16384,
+      "minLength": 1,
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ok",
+        "findings",
+        "error"
+      ],
+      "type": "string"
+    },
+    "summary": {
+      "maxLength": 200,
+      "minLength": 1,
+      "pattern": "^[^\\r\\n]*$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "summary",
+    "comment"
+  ],
+  "title": "lint-docs Agent Result",
+  "type": "object"
+}
+=== scripts/post-lint-docs.sh mode=755
+#!/usr/bin/env bash
+# post-lint-docs.sh — turn the lint-docs agent's JSON result into one comment.
+#
+# Generated by `fullsend agent new`. Safe to edit.
+#
+# Runs on the trusted runner after the sandbox exits. The working directory is
+# the RUN directory, and the agent's output lives one level down, in
+# iteration-<N>/output/agent-result.json — fullsend runs the agent once per
+# iteration and only the last one counts.
+#
+# Required env:
+#   ISSUE_URL — HTML URL of the work item (the harness maps GITHUB_ISSUE_URL to it)
+#   GH_TOKEN  — minted by fullsend from the harness `role:` field
+#
+# Optional env:
+#   FULLSEND_VALIDATED_ITERATION_DIR — set by fullsend when a validation_loop
+#     is configured and an iteration passed it. When present it names the
+#     iteration whose output was validated, which is not necessarily the last
+#     one, so it wins over the scan below.
+#
+# Treat the result file as untrusted: it is model output. Only the three
+# fields below are ever read, each is required to be a string, and the
+# comment body is piped on stdin rather than interpolated into a command.
+
+set -euo pipefail
+
+# ${#var} and ${var:0:n} count characters in a UTF-8 locale and BYTES under
+# C/POSIX. The result schema's maxLength counts Unicode code points, so
+# without this a valid multibyte summary is rejected as too long and
+# truncation can slice mid-character.
+export LC_ALL="${LC_ALL:-C.UTF-8}"
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+# Locate the result. FULLSEND_VALIDATED_ITERATION_DIR is set by fullsend on
+# the runner, not by the sandbox or the agent, so it is trusted as given.
+RESULT_FILE=""
+if [[ -n "${FULLSEND_VALIDATED_ITERATION_DIR:-}" ]]; then
+  if [[ -f "${FULLSEND_VALIDATED_ITERATION_DIR}/agent-result.json" ]]; then
+    RESULT_FILE="${FULLSEND_VALIDATED_ITERATION_DIR}/agent-result.json"
+  else
+    echo "post-lint-docs: FULLSEND_VALIDATED_ITERATION_DIR is set but has no agent-result.json" >&2
+    exit 1
+  fi
+else
+  # No validation loop configured: take the HIGHEST-numbered iteration that
+  # produced output. Compared numerically, not by glob order — the glob sorts
+  # lexicographically, which puts iteration-10 before iteration-9.
+  _best=-1
+  for _dir in iteration-*/output; do
+    [[ -f "${_dir}/agent-result.json" ]] || continue
+    _n="${_dir%/output}"
+    _n="${_n#iteration-}"
+    [[ "${_n}" =~ ^[0-9]+$ ]] || continue
+    if (( _n > _best )); then
+      _best="${_n}"
+      RESULT_FILE="${_dir}/agent-result.json"
+    fi
+  done
+fi
+
+if [[ -z "${RESULT_FILE}" || ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: no agent-result.json found in any iteration-*/output directory" >&2
+  exit 1
+fi
+if ! jq -e 'type == "object"' "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not a JSON object" >&2
+  exit 1
+fi
+
+# Field allowlist: anything else in the file is ignored by construction.
+status=$(jq -r 'if (.status | type) == "string" then .status else empty end' "${RESULT_FILE}")
+summary=$(jq -r 'if (.summary | type) == "string" then .summary else empty end' "${RESULT_FILE}")
+comment=$(jq -r 'if (.comment | type) == "string" then .comment else empty end' "${RESULT_FILE}")
+
+case "${status}" in
+  ok|findings|error) ;;
+  *) echo "post-lint-docs: status must be ok, findings or error (got '${status}')" >&2; exit 1 ;;
+esac
+[[ -n "${summary}" ]] || { echo "post-lint-docs: summary is required" >&2; exit 1; }
+if [[ "${summary}" == *$'\n'* || "${summary}" == *$'\r'* ]]; then
+  echo "post-lint-docs: summary must be a single line" >&2
+  exit 1
+fi
+[[ -n "${comment}" ]] || { echo "post-lint-docs: comment is required" >&2; exit 1; }
+if (( ${#summary} > MAX_SUMMARY_CHARS )); then
+  echo "post-lint-docs: summary exceeds ${MAX_SUMMARY_CHARS} characters" >&2
+  exit 1
+fi
+# Truncate to MAX_COMMENT_CHARS *including* the marker, so the result never
+# exceeds the cap the schema declares.
+TRUNCATION_MARKER=$'\n\n_(truncated)_'
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
+fi
+
+if [[ "${status}" == "ok" ]]; then
+  echo "post-lint-docs: status=ok, nothing to post" >&2
+  exit 0
+fi
+
+# Derive the repo and number from the work item URL rather than trusting extra
+# environment. The pattern also rejects anything that is not a github.com URL.
+url_re='^https://github[.]com/([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)/(issues|pull)/([0-9]+)$'
+if [[ ! "${ISSUE_URL}" =~ ${url_re} ]]; then
+  echo "post-lint-docs: ISSUE_URL is not a GitHub issue or pull request URL" >&2
+  exit 1
+fi
+REPO="${BASH_REMATCH[1]}"
+NUMBER="${BASH_REMATCH[3]}"
+
+if [[ "${POST_LINT_DOCS_DRY_RUN:-}" == "1" ]]; then
+  printf '**%s**\n\n%s\n' "${summary}" "${comment}"
+  echo "post-lint-docs: dry run, not posting" >&2
+  exit 0
+fi
+
+# fullsend issues post-comment is the repo's sticky-comment primitive: it
+# finds this agent's previous comment by marker and edits it in place, so
+# re-runs do not flood the work item.
+printf '**%s**\n\n%s\n' "${summary}" "${comment}" \
+  | fullsend issues post-comment \
+      --tracker github \
+      --project "${REPO}" \
+      --number "${NUMBER}" \
+      --marker "${MARKER}" \
+      --result -
+=== scripts/validate-output-schema.sh mode=755 (shared, written only when absent)
+<copied verbatim from the embedded scaffold>
diff --git a/internal/agentnew/trigger.go b/internal/agentnew/trigger.go
new file mode 100644
index 0000000000..995b4fa596
--- /dev/null
+++ b/internal/agentnew/trigger.go
@@ -0,0 +1,121 @@
+package agentnew
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Trigger presets. The expansions below are reproduced from
+// docs/guides/user/cel-triggers-reference.md rather than composed here: an
+// expression that compiles but touches an absent optional field raises a
+// missing-key error at dispatch time, and MatchHarnesses turns that into a
+// red ::error:: annotation on every matching event
+// (internal/harnessdispatch/enumerate.go:95-99). Emitting known-good text is
+// the whole point of generating the trigger instead of asking the user to
+// write one. TestTriggerPresetsArePinned asserts the exact strings.
+const (
+	// PresetCommand fires on a slash command. entity.kind pins it to issues
+	// and pull requests: a comment on a GitHub Discussion arrives with
+	// entity.kind "conversation", and without this clause the agent would
+	// fire there too and then fail in its post-script, which only accepts an
+	// issue or pull-request URL. The change_proposal clause uses has()
+	// rather than the reference doc's `!= null` because
+	// change_proposal is ABSENT from state on a non-PR comment (schema
+	// $defs.state requires only "labels"; see the jira-fs-triage-comment
+	// and discussion-fs-vouch-comment fixtures), so `!= null` raises a
+	// missing-key error on every issue comment. The guard refuses fork
+	// pull requests without excluding plain issues.
+	PresetCommand = "command"
+	// PresetLabel fires when a label is added.
+	PresetLabel = "label"
+	// PresetIssueOpened fires on new work items.
+	PresetIssueOpened = "issue-opened"
+	// PresetPROpened fires when a non-fork pull request is opened or updated.
+	PresetPROpened = "pr-opened"
+)
+
+// PresetNames lists the recognised --on presets in help order.
+func PresetNames() []string {
+	return []string{
+		PresetCommand + ":/<command>",
+		PresetLabel + ":<label>",
+		PresetIssueOpened,
+		PresetPROpened,
+	}
+}
+
+// ExpandTrigger turns an --on preset into its CEL expression. name supplies
+// the default command and label. The returned expression is not compiled
+// here; the caller runs harness.ValidateTriggerExpression on it before any
+// file is written.
+func ExpandTrigger(on, name string) (string, error) {
+	kind, arg, hasArg := strings.Cut(on, ":")
+	switch kind {
+	case PresetCommand:
+		command := "/fs-" + name
+		if hasArg && arg != "" {
+			command = arg
+			if !strings.HasPrefix(command, "/") {
+				command = "/" + command
+			}
+		}
+		if err := validCELStringLiteral(command); err != nil {
+			return "", fmt.Errorf("--on %s: %w", on, err)
+		}
+		return fmt.Sprintf(`event.transition.kind == "comment_added"
+  && event.entity.kind == "work_item"
+  && has(event.transition.comment.command)
+  && event.transition.comment.command == %q
+  && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
+`, command), nil
+
+	case PresetLabel:
+		label := name
+		if hasArg && arg != "" {
+			label = arg
+		}
+		if err := validCELStringLiteral(label); err != nil {
+			return "", fmt.Errorf("--on %s: %w", on, err)
+		}
+		return fmt.Sprintf(`event.transition.kind == "label_changed"
+  && event.transition.label.name == %q
+  && event.transition.label.action == "added"
+`, label), nil
+
+	case PresetIssueOpened:
+		if hasArg {
+			return "", fmt.Errorf("--on %s takes no argument", PresetIssueOpened)
+		}
+		return `event.entity.kind == "work_item"
+  && event.transition.kind == "opened"
+`, nil
+
+	case PresetPROpened:
+		if hasArg {
+			return "", fmt.Errorf("--on %s takes no argument", PresetPROpened)
+		}
+		return `event.entity.kind == "change_proposal"
+  && (event.transition.kind == "opened"
+      || event.transition.kind == "synchronized"
+      || event.transition.kind == "marked_ready")
+  && !event.state.change_proposal.is_fork
+`, nil
+	}
+
+	return "", fmt.Errorf("unknown --on preset %q\n\nvalid presets: %s\nfor anything else pass raw CEL with --trigger",
+		on, strings.Join(PresetNames(), ", "))
+}
+
+// validCELStringLiteral rejects values that would need escaping inside the
+// generated CEL string literal. %q would escape them correctly, but a
+// command or label containing a quote or newline is a mistake worth
+// reporting rather than encoding.
+func validCELStringLiteral(s string) error {
+	if s == "" {
+		return fmt.Errorf("value must not be empty")
+	}
+	if strings.ContainsAny(s, "\"'\\\n\r\t") {
+		return fmt.Errorf("value %q must not contain quotes, backslashes or whitespace control characters", s)
+	}
+	return nil
+}
diff --git a/internal/agentnew/trigger_fixtures_test.go b/internal/agentnew/trigger_fixtures_test.go
new file mode 100644
index 0000000000..13aca1eb2c
--- /dev/null
+++ b/internal/agentnew/trigger_fixtures_test.go
@@ -0,0 +1,239 @@
+package agentnew
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+// fixtureDir holds the normative NormalizedEvent v1 examples. Evaluating the
+// generated presets against these, rather than against hand-written maps,
+// means the test fails if the event shape the presets depend on ever moves.
+const fixtureDir = "../../docs/normative/normalized-event/v1/examples"
+
+func loadFixture(t *testing.T, name string) map[string]any {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(fixtureDir, name+".json"))
+	if err != nil {
+		t.Fatalf("reading fixture %s: %v", name, err)
+	}
+	var event map[string]any
+	if err := json.Unmarshal(data, &event); err != nil {
+		t.Fatalf("parsing fixture %s: %v", name, err)
+	}
+	return event
+}
+
+// forkVariant returns a fixture with state.change_proposal.is_fork flipped.
+// There is no fork pull-request COMMENT fixture in the corpus, so the fork
+// case is derived from the real non-fork one rather than hand-written.
+func forkVariant(t *testing.T, event map[string]any) map[string]any {
+	t.Helper()
+	data, err := json.Marshal(event)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var clone map[string]any
+	if err := json.Unmarshal(data, &clone); err != nil {
+		t.Fatal(err)
+	}
+	cp, ok := clone["state"].(map[string]any)["change_proposal"].(map[string]any)
+	if !ok {
+		t.Fatal("fixture has no state.change_proposal to flip")
+	}
+	cp["is_fork"] = true
+	return clone
+}
+
+// TestCommandPresetForkGuard is the security-critical test of this feature.
+// The command preset is the DEFAULT trigger, so every generated agent gets
+// it, including agents with role coder (contents:write, pull_requests:write).
+// It must fire for a maintainer on a non-fork PR and for an issue comment,
+// and must NOT fire for a comment on a fork pull request.
+func TestCommandPresetForkGuard(t *testing.T) {
+	prComment := loadFixture(t, "fs-fix-comment")            // PR comment, is_fork false
+	issueComment := loadFixture(t, "jira-fs-triage-comment") // issue comment, no change_proposal
+	forkComment := forkVariant(t, prComment)
+
+	tests := []struct {
+		name    string
+		command string
+		event   map[string]any
+		want    bool
+	}{
+		{"non-fork pull request comment fires", "/fs-fix", prComment, true},
+		{"issue comment fires (no change_proposal present)", "/fs-triage", issueComment, true},
+		{"fork pull request comment does NOT fire", "/fs-fix", forkComment, false},
+		{"different command does not fire", "/fs-other", prComment, false},
+		{"different command does not fire on issue", "/fs-other", issueComment, false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			expr, err := ExpandTrigger("command:"+tc.command, "irrelevant")
+			if err != nil {
+				t.Fatal(err)
+			}
+			got, err := harness.EvaluateTrigger(expr, tc.event)
+			// An error here is the failure this preset exists to avoid: a
+			// missing-key error becomes a red ::error:: annotation on every
+			// matching event, because MatchHarnesses logs and skips.
+			if err != nil {
+				t.Fatalf("trigger evaluation errored (this would be ::error:: spam at dispatch): %v", err)
+			}
+			if got != tc.want {
+				t.Errorf("EvaluateTrigger = %v, want %v\nexpr:\n%s", got, tc.want, expr)
+			}
+		})
+	}
+}
+
+// TestCommandPresetNeverErrorsOnAnyFixture: the whole point of the has()
+// guard over the reference doc's `!= null` is that it must not raise a
+// missing-key error on ANY event shape, including ones with no
+// change_proposal and no comment at all.
+func TestCommandPresetNeverErrorsOnAnyFixture(t *testing.T) {
+	entries, err := os.ReadDir(fixtureDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	expr, err := ExpandTrigger("command:/fs-fix", "irrelevant")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range entries {
+		if filepath.Ext(e.Name()) != ".json" {
+			continue
+		}
+		name := e.Name()[:len(e.Name())-len(".json")]
+		t.Run(name, func(t *testing.T) {
+			if _, err := harness.EvaluateTrigger(expr, loadFixture(t, name)); err != nil {
+				t.Errorf("preset errored on %s: %v", name, err)
+			}
+		})
+	}
+}
+
+// TestPROpenedPresetForkGuard: the pr-opened preset carries the reference
+// doc's fork guard verbatim, and change_proposal is always present on a
+// change_proposal event, so `!has()` is not needed there.
+func TestPROpenedPresetForkGuard(t *testing.T) {
+	expr, err := ExpandTrigger("pr-opened", "irrelevant")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		fixture string
+		want    bool
+	}{
+		{"pr-opened", true},
+		{"pr-opened-fork", false},
+		{"pr-synchronized", true},
+		{"issue-opened", false},
+	} {
+		t.Run(tc.fixture, func(t *testing.T) {
+			got, err := harness.EvaluateTrigger(expr, loadFixture(t, tc.fixture))
+			if err != nil {
+				t.Fatalf("evaluation errored: %v", err)
+			}
+			if got != tc.want {
+				t.Errorf("EvaluateTrigger(%s) = %v, want %v", tc.fixture, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestIssueOpenedPreset against the real fixture.
+func TestIssueOpenedPreset(t *testing.T) {
+	expr, err := ExpandTrigger("issue-opened", "irrelevant")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		fixture string
+		want    bool
+	}{
+		{"issue-opened", true},
+		{"pr-opened", false},
+	} {
+		got, err := harness.EvaluateTrigger(expr, loadFixture(t, tc.fixture))
+		if err != nil {
+			t.Fatalf("%s: %v", tc.fixture, err)
+		}
+		if got != tc.want {
+			t.Errorf("EvaluateTrigger(%s) = %v, want %v", tc.fixture, got, tc.want)
+		}
+	}
+}
+
+// TestLabelPreset against the real fixture.
+func TestLabelPreset(t *testing.T) {
+	expr, err := ExpandTrigger("label:ready-to-code", "irrelevant")
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := harness.EvaluateTrigger(expr, loadFixture(t, "ready-to-code-labeled"))
+	if err != nil {
+		t.Fatalf("evaluation errored: %v", err)
+	}
+	if !got {
+		t.Error("label preset did not match the ready-to-code-labeled fixture")
+	}
+}
+
+// TestCommandPresetMatchesTheReferenceDoc keeps the generator and the
+// documentation from drifting apart. The reference page tells users to write
+// this expression by hand; `agent new --on command:` emits it for them. If
+// either changes without the other, this fails.
+func TestCommandPresetMatchesTheReferenceDoc(t *testing.T) {
+	const docPath = "../../docs/guides/user/cel-triggers-reference.md"
+	data, err := os.ReadFile(docPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	const heading = "**Run on a slash command (issues and non-fork PRs):**"
+	idx := strings.Index(string(data), heading)
+	if idx < 0 {
+		t.Fatalf("could not find the slash-command section in %s", docPath)
+	}
+	block, ok := firstYAMLBlock(string(data)[idx:])
+	if !ok {
+		t.Fatalf("could not find a yaml block after %q", heading)
+	}
+
+	// The doc uses a folded scalar (trigger: >) and two-space continuation;
+	// compare the expression's significant tokens, not its layout.
+	docExpr := strings.TrimPrefix(strings.TrimSpace(block), "trigger: >")
+	preset, err := ExpandTrigger("command:/my-command", "irrelevant")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if normaliseCEL(docExpr) != normaliseCEL(preset) {
+		t.Errorf("the reference doc and the --on command: preset have drifted\n doc: %s\npreset: %s",
+			normaliseCEL(docExpr), normaliseCEL(preset))
+	}
+}
+
+func firstYAMLBlock(s string) (string, bool) {
+	start := strings.Index(s, "```yaml\n")
+	if start < 0 {
+		return "", false
+	}
+	rest := s[start+len("```yaml\n"):]
+	end := strings.Index(rest, "```")
+	if end < 0 {
+		return "", false
+	}
+	return rest[:end], true
+}
+
+// normaliseCEL collapses all whitespace so layout differences between a
+// folded YAML scalar and generated text do not matter.
+func normaliseCEL(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
diff --git a/internal/agentnew/trigger_test.go b/internal/agentnew/trigger_test.go
new file mode 100644
index 0000000000..f6077845a0
--- /dev/null
+++ b/internal/agentnew/trigger_test.go
@@ -0,0 +1,151 @@
+package agentnew
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+	"github.com/fullsend-ai/fullsend/internal/scaffold"
+)
+
+// TestTriggerPresetsArePinned asserts the exact text each preset emits.
+// String equality, not a compile check: an expression can compile and still
+// touch an absent optional field, which fails only at dispatch. That is the
+// failure mode this command exists to remove, so the text is pinned.
+func TestTriggerPresetsArePinned(t *testing.T) {
+	tests := []struct {
+		name string
+		on   string
+		want string
+	}{
+		{
+			name: "command default",
+			on:   "command",
+			want: `event.transition.kind == "comment_added"
+  && event.entity.kind == "work_item"
+  && has(event.transition.comment.command)
+  && event.transition.comment.command == "/fs-lint-docs"
+  && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
+`,
+		},
+		{
+			name: "command explicit",
+			on:   "command:/review-docs",
+			want: `event.transition.kind == "comment_added"
+  && event.entity.kind == "work_item"
+  && has(event.transition.comment.command)
+  && event.transition.comment.command == "/review-docs"
+  && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
+`,
+		},
+		{
+			name: "command without leading slash is normalised",
+			on:   "command:review-docs",
+			want: `event.transition.kind == "comment_added"
+  && event.entity.kind == "work_item"
+  && has(event.transition.comment.command)
+  && event.transition.comment.command == "/review-docs"
+  && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
+`,
+		},
+		{
+			name: "label default",
+			on:   "label",
+			want: `event.transition.kind == "label_changed"
+  && event.transition.label.name == "lint-docs"
+  && event.transition.label.action == "added"
+`,
+		},
+		{
+			name: "label explicit",
+			on:   "label:needs-docs",
+			want: `event.transition.kind == "label_changed"
+  && event.transition.label.name == "needs-docs"
+  && event.transition.label.action == "added"
+`,
+		},
+		{
+			name: "issue-opened",
+			on:   "issue-opened",
+			want: `event.entity.kind == "work_item"
+  && event.transition.kind == "opened"
+`,
+		},
+		{
+			name: "pr-opened",
+			on:   "pr-opened",
+			want: `event.entity.kind == "change_proposal"
+  && (event.transition.kind == "opened"
+      || event.transition.kind == "synchronized"
+      || event.transition.kind == "marked_ready")
+  && !event.state.change_proposal.is_fork
+`,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := ExpandTrigger(tc.on, "lint-docs")
+			if err != nil {
+				t.Fatalf("ExpandTrigger(%q): %v", tc.on, err)
+			}
+			if got != tc.want {
+				t.Errorf("expansion drifted\n got: %q\nwant: %q", got, tc.want)
+			}
+			// Every preset must also survive the same check the harness
+			// loader applies, including the bool-output-type assertion.
+			if err := harness.ValidateTriggerExpression(got); err != nil {
+				t.Errorf("preset does not compile as a harness trigger: %v", err)
+			}
+		})
+	}
+}
+
+func TestExpandTriggerRejects(t *testing.T) {
+	for _, tc := range []struct{ name, on string }{
+		{"unknown preset", "on-tuesday"},
+		{"empty", ""},
+		{"issue-opened with argument", "issue-opened:x"},
+		{"pr-opened with argument", "pr-opened:x"},
+		{"command with quote", `command:/a"b`},
+		{"label with backslash", `label:a\b`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := ExpandTrigger(tc.on, "lint-docs"); err == nil {
+				t.Fatalf("ExpandTrigger(%q) succeeded; want error", tc.on)
+			}
+		})
+	}
+}
+
+// TestUnknownPresetErrorListsAlternatives keeps the error actionable.
+func TestUnknownPresetErrorListsAlternatives(t *testing.T) {
+	_, err := ExpandTrigger("on-tuesday", "x")
+	if err == nil {
+		t.Fatal("want error")
+	}
+	for _, want := range []string{"command", "label", "issue-opened", "pr-opened", "--trigger"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error should mention %q, got: %v", want, err)
+		}
+	}
+}
+
+// TestRoleResourcesExistInScaffold proves every provider and profile path the
+// role table names is a file the CLI can actually produce. A path that names
+// nothing would pass harness validation and then fail at run time as "agent
+// crashes at 0s", because the embedded provider fallback covers only the
+// OpenAI provider.
+func TestRoleResourcesExistInScaffold(t *testing.T) {
+	for _, name := range RoleNames() {
+		role, err := LookupRole(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, p := range append(append([]string{}, role.Providers...), role.Profiles...) {
+			if _, err := scaffold.FullsendRepoFile(p); err != nil {
+				t.Errorf("role %q references %q, which is not in the embedded scaffold: %v", name, p, err)
+			}
+		}
+	}
+}
diff --git a/internal/cli/agent.go b/internal/cli/agent.go
index 328e9caafb..e0a4e00637 100644
--- a/internal/cli/agent.go
+++ b/internal/cli/agent.go
@@ -29,8 +29,9 @@ func newAgentCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "agent",
 		Short: "Manage agent registrations in config",
-		Long:  "Commands for adding, listing, updating, and removing agent registrations in fullsend config.",
+		Long:  "Commands for generating, adding, listing, updating, and removing agents in fullsend config.",
 	}
+	cmd.AddCommand(newAgentNewCmd())
 	cmd.AddCommand(newAgentAddCmd())
 	cmd.AddCommand(newAgentListCmd())
 	cmd.AddCommand(newAgentUpdateCmd())
diff --git a/internal/cli/agent_new.go b/internal/cli/agent_new.go
new file mode 100644
index 0000000000..332efb73e4
--- /dev/null
+++ b/internal/cli/agent_new.go
@@ -0,0 +1,369 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/fullsend-ai/fullsend/internal/agentnew"
+	"github.com/fullsend-ai/fullsend/internal/config"
+	"github.com/fullsend-ai/fullsend/internal/ui"
+)
+
+// agentNewFlags carries the `agent new` flag values plus whether each was
+// given, so a spec file (-f) and command-line flags can be merged with flags
+// winning — the same technique `agent set` uses.
+type agentNewFlags struct {
+	fullsendDir    string
+	specFile       string
+	role           string
+	description    string
+	on             string
+	trigger        string
+	model          string
+	effort         string
+	runtime        string
+	slug           string
+	image          string
+	timeoutMinutes int
+	validationLoop bool
+	noRegister     bool
+	force          bool
+	dryRun         bool
+
+	changed func(string) bool
+}
+
+func newAgentNewCmd() *cobra.Command {
+	var f agentNewFlags
+
+	cmd := &cobra.Command{
+		Use:   "new <name>",
+		Short: "Generate a complete custom agent",
+		Long: `Generate a complete, valid, runnable custom agent and register it.
+
+Writes the harness, agent definition, result schema and post-script, copies
+the sandbox policy, providers and profiles it needs when they are absent,
+validates the result with the same loader dispatch uses, and adds the agent
+to config.yaml.
+
+The agent is generated with a trigger, because an agent without one
+registers and validates but is silently never dispatched.
+
+Examples:
+  fullsend agent new lint-docs --fullsend-dir .fullsend \
+    --role triage --description "Check docs changes for broken links"
+
+  fullsend agent new lint-docs --fullsend-dir .fullsend --on label:needs-docs
+
+  fullsend agent new -f lint-docs.agent.yaml --fullsend-dir .fullsend
+
+` + agentnew.RoleHelp(),
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			f.changed = cmd.Flags().Changed
+			var name string
+			if len(args) == 1 {
+				name = args[0]
+			}
+			printer := ui.New(os.Stdout)
+			return runAgentNew(cmd.Context(), name, f, printer)
+		},
+	}
+
+	cmd.Flags().StringVar(&f.fullsendDir, "fullsend-dir", "", "path to the .fullsend configuration directory")
+	cmd.Flags().StringVarP(&f.specFile, "file", "f", "", "read the agent definition from a spec YAML file")
+	cmd.Flags().StringVar(&f.role, "role", agentnew.DefaultRole, "mint role the agent runs as (see the table below)")
+	cmd.Flags().StringVar(&f.description, "description", "", "one-line description of what the agent does")
+	cmd.Flags().StringVar(&f.on, "on", "", "trigger preset: "+strings.Join(agentnew.PresetNames(), ", ")+" (default command:/fs-<name>)")
+	cmd.Flags().StringVar(&f.trigger, "trigger", "", "raw CEL trigger expression; mutually exclusive with --on")
+	cmd.Flags().StringVar(&f.model, "model", agentnew.DefaultModel, "model for the agent")
+	cmd.Flags().StringVar(&f.effort, "effort", agentnew.DefaultEffort, "effort level (low, medium, high, xhigh, max)")
+	cmd.Flags().StringVar(&f.runtime, "runtime", "", "agent runtime recorded in config.yaml (claude, pi or codex)")
+	cmd.Flags().StringVar(&f.slug, "slug", "", "harness slug (default: <owner>-<name> from the origin remote)")
+	cmd.Flags().StringVar(&f.image, "image", "", "sandbox image (default: the fleet's pin for this role)")
+	cmd.Flags().IntVar(&f.timeoutMinutes, "timeout-minutes", agentnew.DefaultTimeoutMinutes, "agent timeout in minutes")
+	cmd.Flags().BoolVar(&f.validationLoop, "validation-loop", false,
+		"add a validation_loop that checks agent output against the schema (needs python3 with the jsonschema package on the runner)")
+	cmd.Flags().BoolVar(&f.noRegister, "no-register", false, "write the files but do not add the agent to config.yaml")
+	cmd.Flags().BoolVar(&f.force, "force", false, "overwrite generated files that already exist (never overwrites shared scaffold assets)")
+	cmd.Flags().BoolVar(&f.dryRun, "dry-run", false, "validate and report what would be written without writing anything")
+	_ = cmd.MarkFlagRequired("fullsend-dir")
+	return cmd
+}
+
+// resolveAgentNewOptions merges defaults, the spec file and command-line
+// flags into a validated Options. Flags win over spec keys.
+func resolveAgentNewOptions(name string, f agentNewFlags) (opts agentnew.Options, runtimeName string, slugWarning string, err error) {
+	opts = agentnew.Options{
+		Role:           f.role,
+		Model:          f.model,
+		Effort:         f.effort,
+		TimeoutMinutes: f.timeoutMinutes,
+		ValidationLoop: f.validationLoop,
+	}
+	runtimeName = f.runtime
+	on, trigger := f.on, f.trigger
+	slug, image, description := f.slug, f.image, f.description
+
+	if f.specFile != "" {
+		if name != "" {
+			return opts, "", "", fmt.Errorf("pass either a name or -f, not both")
+		}
+		spec, specErr := agentnew.LoadSpecFile(f.specFile)
+		if specErr != nil {
+			return opts, "", "", specErr
+		}
+		name = spec.Name
+		// Spec values apply only where the flag was not given.
+		if !f.changed("role") && spec.Role != "" {
+			opts.Role = spec.Role
+		}
+		if !f.changed("model") && spec.Model != "" {
+			opts.Model = spec.Model
+		}
+		if !f.changed("effort") && spec.Effort != "" {
+			opts.Effort = spec.Effort
+		}
+		// Pointer, not zero-check: `timeout_minutes: 0` is a real choice
+		// (no timeout) and must not be read as "field omitted".
+		if !f.changed("timeout-minutes") && spec.TimeoutMinutes != nil {
+			opts.TimeoutMinutes = *spec.TimeoutMinutes
+		}
+		if !f.changed("validation-loop") {
+			opts.ValidationLoop = spec.ValidationLoop
+		}
+		if !f.changed("runtime") {
+			runtimeName = spec.Runtime
+		}
+		if !f.changed("description") {
+			description = spec.Description
+		}
+		if !f.changed("slug") {
+			slug = spec.Slug
+		}
+		if !f.changed("image") {
+			image = spec.Image
+		}
+		if !f.changed("on") && !f.changed("trigger") {
+			on, trigger = spec.On, spec.Trigger
+		}
+	}
+
+	if name == "" {
+		return opts, "", "", fmt.Errorf("an agent name is required: `fullsend agent new <name>` or -f <spec.yaml>")
+	}
+	opts.Name = name
+
+	if on != "" && trigger != "" {
+		return opts, "", "", fmt.Errorf("--on and --trigger are mutually exclusive")
+	}
+	switch {
+	case trigger != "":
+		opts.Trigger = trigger
+	default:
+		if on == "" {
+			on = agentnew.DefaultOn
+		}
+		expanded, expandErr := agentnew.ExpandTrigger(on, name)
+		if expandErr != nil {
+			return opts, "", "", expandErr
+		}
+		opts.Trigger = expanded
+	}
+
+	if description == "" {
+		description = "Custom " + name + " agent."
+	}
+	opts.Description = description
+
+	if slug == "" {
+		// Absolute: GitConfigOwner cannot walk above "." from a relative
+		// path, so `--fullsend-dir sub/.fullsend` run from anywhere but the
+		// repository root would silently miss origin and fall back.
+		ownerDir := f.fullsendDir
+		if abs, absErr := filepath.Abs(ownerDir); absErr == nil {
+			ownerDir = abs
+		}
+		owner := agentnew.GitConfigOwner(ownerDir)
+		if owner == "" {
+			slugWarning = fmt.Sprintf("Could not read an owner from the origin remote; using slug %q. Pass --slug to set it.",
+				agentnew.DeriveSlug(name, ""))
+		}
+		slug = agentnew.DeriveSlug(name, owner)
+	}
+	opts.Slug = slug
+
+	if image == "" {
+		role, roleErr := agentnew.LookupRole(opts.Role)
+		if roleErr != nil {
+			return opts, "", "", roleErr
+		}
+		image = role.Image
+	}
+	opts.Image = image
+
+	if runtimeName != "" && !slices.Contains(userFacingRuntimes(), runtimeName) {
+		return opts, "", "", fmt.Errorf("runtime %q is not valid (allowed: %s)",
+			runtimeName, strings.Join(userFacingRuntimes(), ", "))
+	}
+
+	if validateErr := opts.Validate(); validateErr != nil {
+		return opts, "", "", validateErr
+	}
+	return opts, runtimeName, slugWarning, nil
+}
+
+func runAgentNew(ctx context.Context, name string, f agentNewFlags, printer *ui.Printer) error {
+	opts, runtimeName, slugWarning, err := resolveAgentNewOptions(name, f)
+	if err != nil {
+		return err
+	}
+	if slugWarning != "" {
+		printer.StepWarn(slugWarning)
+	}
+
+	// Reported first so a missing directory does not surface as a failure to
+	// read config.yaml from inside it.
+	if err := agentnew.ValidateFullsendDir(f.fullsendDir); err != nil {
+		return err
+	}
+	// Checked before Generate writes anything: registration happens last, so
+	// a name already in config.yaml would otherwise be reported only after
+	// the files had landed, leaving the directory changed by a failed run.
+	if !f.noRegister {
+		if err := ensureAgentNameFree(f.fullsendDir, opts.Name); err != nil {
+			return err
+		}
+	}
+
+	result, err := agentnew.Generate(opts, f.fullsendDir, f.force, f.dryRun)
+	if err != nil {
+		return err
+	}
+	for _, diag := range result.Diagnostics {
+		printer.StepWarn(diag.String())
+	}
+
+	if f.dryRun {
+		printer.StepInfo(fmt.Sprintf("Dry run: would create agent %q in %s", opts.Name, f.fullsendDir))
+		for _, w := range result.Written {
+			printer.Raw("  " + w + "\n")
+		}
+		for _, s := range result.SkippedShared {
+			printer.Raw("  " + s + "  (already present, would be left unchanged)\n")
+		}
+		for _, rf := range result.Rendered {
+			printer.Raw("\n--- " + rf.Path + " ---\n")
+			printer.Raw(string(rf.Data))
+		}
+		printer.StepInfo("Nothing was written and no agent was registered")
+		return nil
+	}
+
+	printer.StepDone(fmt.Sprintf("Created agent %q in %s", opts.Name, f.fullsendDir))
+	for _, w := range result.Written {
+		printer.Raw("  " + w + "\n")
+	}
+	for _, s := range result.SkippedShared {
+		printer.Raw("  " + s + "  (already present, left unchanged)\n")
+	}
+
+	if f.noRegister {
+		printer.StepInfo("Not registered (--no-register). Register it later with:")
+		printer.Raw(fmt.Sprintf("  fullsend agent add %s --fullsend-dir %s\n", result.HarnessPath, f.fullsendDir))
+	} else {
+		if err := runAgentAdd(ctx, result.HarnessPath, opts.Name, f.fullsendDir, nil, printer); err != nil {
+			return fmt.Errorf("agent files were written but registration failed: %w", err)
+		}
+		if runtimeName != "" {
+			if err := runAgentSet(f.fullsendDir, opts.Name, agentSetFlags{
+				runtime: runtimeName, runtimeSet: true,
+			}, printer); err != nil {
+				return fmt.Errorf("agent registered but setting the runtime failed: %w", err)
+			}
+		}
+	}
+
+	printNextSteps(opts, f, printer)
+	return nil
+}
+
+// printNextSteps tells the user what to edit, how to test locally, and how to
+// fire the agent in CI. The CI line is derived from the same trigger that
+// went into the harness, so the instruction and the CEL cannot disagree.
+func printNextSteps(opts agentnew.Options, f agentNewFlags, printer *ui.Printer) {
+	printer.Raw("\nNext:\n")
+	printer.Raw(fmt.Sprintf("  1. Fill in the marked sections of agents/%s.md — that file is the agent's prompt.\n", opts.Name))
+	printer.Raw(fmt.Sprintf("  2. Test locally:\n       fullsend run %s --fullsend-dir %s \\\n         --target-repo . --env-file .env.local\n",
+		opts.Name, f.fullsendDir))
+	printer.Raw("     .env.local needs GITHUB_ISSUE_URL, GH_TOKEN, ANTHROPIC_VERTEX_PROJECT_ID,\n")
+	printer.Raw("     CLOUD_ML_REGION, and GOOGLE_APPLICATION_CREDENTIALS pointing at a GCP\n")
+	printer.Raw("     credentials file — the harness copies that file into the sandbox, so the\n")
+	printer.Raw("     run stops before it starts without it. GH_TOKEN must be a real token: a\n")
+	printer.Raw("     connectivity check runs before the agent does. See\n")
+	printer.Raw("     docs/guides/user/running-agents-locally.md.\n")
+	if cmd := slashCommandFromTrigger(opts.Trigger); cmd != "" {
+		printer.Raw(fmt.Sprintf("  3. Commit %s, then comment `%s` on an issue or pull request to run it in CI.\n",
+			filepath.Clean(f.fullsendDir), cmd))
+	} else {
+		printer.Raw(fmt.Sprintf("  3. Commit %s, then trigger it with an event matching the harness `trigger:`.\n",
+			filepath.Clean(f.fullsendDir)))
+	}
+}
+
+// slashCommandFromTrigger recovers the slash command from a generated
+// trigger so the printed instruction always matches the emitted CEL.
+func slashCommandFromTrigger(trigger string) string {
+	const marker = "event.transition.comment.command == "
+	idx := strings.Index(trigger, marker)
+	if idx < 0 {
+		return ""
+	}
+	rest := trigger[idx+len(marker):]
+	if !strings.HasPrefix(rest, `"`) {
+		return ""
+	}
+	end := strings.Index(rest[1:], `"`)
+	if end < 0 {
+		return ""
+	}
+	return rest[1 : 1+end]
+}
+
+// ensureAgentNameFree reports whether an agent of this name is already
+// registered, without mutating anything. It mirrors the check runAgentAdd
+// makes, so the two cannot disagree about what counts as a collision.
+func ensureAgentNameFree(fullsendDir, name string) error {
+	absDir, err := filepath.Abs(fullsendDir)
+	if err != nil {
+		return fmt.Errorf("resolving fullsend dir: %w", err)
+	}
+	cfg, err := loadAgentConfig(filepath.Join(absDir, config.OverlayConfigFile))
+	if err != nil {
+		return err
+	}
+	if _, found := findAgentByName(cfg.AgentEntries(), name); found {
+		return fmt.Errorf("agent %q already exists in config; pick another name or run `fullsend agent remove %s` first", name, name)
+	}
+	return nil
+}
+
+// userFacingRuntimes is config.ValidRuntimes minus the dummy runtimes, which
+// exist only for behaviour tests. Offering them here would document a choice
+// that produces an agent doing no inference at all.
+func userFacingRuntimes() []string {
+	var out []string
+	for _, r := range config.ValidRuntimes() {
+		if strings.HasPrefix(r, "dummy") {
+			continue
+		}
+		out = append(out, r)
+	}
+	return out
+}
diff --git a/internal/cli/agent_new_test.go b/internal/cli/agent_new_test.go
new file mode 100644
index 0000000000..6cc70e3680
--- /dev/null
+++ b/internal/cli/agent_new_test.go
@@ -0,0 +1,330 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/fullsend-ai/fullsend/internal/agentnew"
+	"github.com/fullsend-ai/fullsend/internal/config"
+	"github.com/fullsend-ai/fullsend/internal/harness"
+	"github.com/fullsend-ai/fullsend/internal/ui"
+)
+
+// newFullsendDir creates a minimal per-repo .fullsend directory.
+func newFullsendDir(t *testing.T) string {
+	t.Helper()
+	dir := filepath.Join(t.TempDir(), ".fullsend")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "config.yaml"),
+		[]byte("version: \"1\"\nroles: [triage]\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+
+// defaultFlags mirrors what cobra would supply, including the flag defaults.
+func defaultFlags(dir string, changed ...string) agentNewFlags {
+	set := map[string]bool{}
+	for _, c := range changed {
+		set[c] = true
+	}
+	return agentNewFlags{
+		fullsendDir:    dir,
+		role:           agentnew.DefaultRole,
+		model:          agentnew.DefaultModel,
+		effort:         agentnew.DefaultEffort,
+		timeoutMinutes: agentnew.DefaultTimeoutMinutes,
+		changed:        func(name string) bool { return set[name] },
+	}
+}
+
+func runNew(t *testing.T, name string, f agentNewFlags) (string, error) {
+	t.Helper()
+	var buf bytes.Buffer
+	err := runAgentNew(context.Background(), name, f, ui.New(&buf))
+	return buf.String(), err
+}
+
+// TestAgentNewEndToEnd is the whole command against a real directory: files
+// land, the harness loads through the real loader, and the agent is
+// registered so dispatch can find it.
+func TestAgentNewEndToEnd(t *testing.T) {
+	dir := newFullsendDir(t)
+	out, err := runNew(t, "lint-docs", defaultFlags(dir))
+	if err != nil {
+		t.Fatalf("runAgentNew: %v\n%s", err, out)
+	}
+
+	for _, want := range []string{
+		"harness/lint-docs.yaml",
+		"agents/lint-docs.md",
+		"schemas/lint-docs-result.schema.json",
+		"scripts/post-lint-docs.sh",
+		"policies/base.yaml",
+		"providers/vertex-ai.yaml",
+		"profiles/fullsend-vertex-ai.yaml",
+	} {
+		if _, err := os.Stat(filepath.Join(dir, want)); err != nil {
+			t.Errorf("expected %s to be written: %v", want, err)
+		}
+	}
+
+	h, err := harness.Load(filepath.Join(dir, "harness", "lint-docs.yaml"))
+	if err != nil {
+		t.Fatalf("generated harness does not load: %v", err)
+	}
+	if _, err := harness.CheckGenerated(h, dir); err != nil {
+		t.Fatalf("generated tree does not validate: %v", err)
+	}
+
+	cfg, err := config.LoadConfig(dir, config.LoadOpts{MissingOK: false})
+	if err != nil {
+		t.Fatal(err)
+	}
+	agents, err := harness.RegisteredAgents(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var found bool
+	for _, a := range agents {
+		if a.Name == "lint-docs" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("agent was not registered; got %v", agents)
+	}
+
+	// The printed CI instruction must carry the same command the trigger
+	// encodes, or the user is told to type something that will not fire.
+	if !strings.Contains(out, "/fs-lint-docs") {
+		t.Errorf("next steps should name the slash command:\n%s", out)
+	}
+	if !strings.Contains(h.Trigger, `"/fs-lint-docs"`) {
+		t.Errorf("trigger should carry the same command: %q", h.Trigger)
+	}
+}
+
+// TestAgentNewPostScriptIsExecutable: the post-script is invoked directly by
+// the runner, so the execute bit is load-bearing.
+func TestAgentNewPostScriptIsExecutable(t *testing.T) {
+	dir := newFullsendDir(t)
+	if _, err := runNew(t, "lint-docs", defaultFlags(dir)); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(filepath.Join(dir, "scripts", "post-lint-docs.sh"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Mode().Perm()&0o111 == 0 {
+		t.Errorf("post-script is not executable: %v", info.Mode())
+	}
+}
+
+func TestAgentNewDryRunReportsWhatItWouldWrite(t *testing.T) {
+	dir := newFullsendDir(t)
+	f := defaultFlags(dir)
+	f.dryRun = true
+	out, err := runNew(t, "lint-docs", f)
+	if err != nil {
+		t.Fatalf("dry run failed: %v", err)
+	}
+	// That a dry run writes nothing is asserted in package agentnew
+	// (TestGenerateDryRunWritesNothing). What only this layer can check is
+	// that the command reports the plan rather than staying silent.
+	for _, want := range []string{
+		"Nothing was written",
+		"harness/lint-docs.yaml",
+		"agents/lint-docs.md",
+		"--- harness/lint-docs.yaml ---",
+		"role: triage",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("dry run output should contain %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestAgentNewNoRegister(t *testing.T) {
+	dir := newFullsendDir(t)
+	f := defaultFlags(dir)
+	f.noRegister = true
+	out, err := runNew(t, "lint-docs", f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "harness", "lint-docs.yaml")); err != nil {
+		t.Error("--no-register should still write the files")
+	}
+	cfg, err := config.LoadConfig(dir, config.LoadOpts{MissingOK: false})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cfg.AgentEntries()) != 0 {
+		t.Errorf("--no-register should not touch config.yaml, got %v", cfg.AgentEntries())
+	}
+	if !strings.Contains(out, "fullsend agent add") {
+		t.Errorf("--no-register should say how to register later:\n%s", out)
+	}
+}
+
+// TestAgentNewMissingConfig: runAgentAdd loads with MissingOK false, so a
+// directory with no config.yaml must fail with something actionable rather
+// than a bare stat error after the files have landed.
+func TestAgentNewMissingConfig(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), ".fullsend")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	_, err := runNew(t, "lint-docs", defaultFlags(dir))
+	if err == nil {
+		t.Fatal("a fullsend dir with no config.yaml should fail")
+	}
+}
+
+func TestAgentNewWithRuntime(t *testing.T) {
+	dir := newFullsendDir(t)
+	f := defaultFlags(dir, "runtime")
+	f.runtime = "pi"
+	if _, err := runNew(t, "lint-docs", f); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.LoadConfig(dir, config.LoadOpts{MissingOK: false})
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry, ok := config.AgentSettingsFor(cfg.AgentEntries(), "lint-docs")
+	if !ok {
+		t.Fatal("agent not registered")
+	}
+	if entry.Runtime != "pi" {
+		t.Errorf("runtime = %q, want pi", entry.Runtime)
+	}
+}
+
+func TestResolveAgentNewOptions(t *testing.T) {
+	dir := newFullsendDir(t)
+
+	t.Run("defaults", func(t *testing.T) {
+		opts, _, _, err := resolveAgentNewOptions("lint-docs", defaultFlags(dir))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if opts.Role != "triage" || opts.Model != "opus" || opts.Effort != "high" {
+			t.Errorf("unexpected defaults: %+v", opts)
+		}
+		if opts.Description != "Custom lint-docs agent." {
+			t.Errorf("description = %q", opts.Description)
+		}
+		if !strings.Contains(opts.Trigger, "/fs-lint-docs") {
+			t.Errorf("default trigger = %q", opts.Trigger)
+		}
+	})
+
+	t.Run("name and -f together are rejected", func(t *testing.T) {
+		f := defaultFlags(dir)
+		f.specFile = writeSpec(t, "version: \"1\"\nname: other\n")
+		if _, _, _, err := resolveAgentNewOptions("lint-docs", f); err == nil {
+			t.Fatal("want error")
+		}
+	})
+
+	t.Run("no name at all is rejected", func(t *testing.T) {
+		if _, _, _, err := resolveAgentNewOptions("", defaultFlags(dir)); err == nil {
+			t.Fatal("want error")
+		}
+	})
+
+	t.Run("--on and --trigger are mutually exclusive", func(t *testing.T) {
+		f := defaultFlags(dir, "on", "trigger")
+		f.on, f.trigger = "label:x", "true"
+		if _, _, _, err := resolveAgentNewOptions("lint-docs", f); err == nil {
+			t.Fatal("want error")
+		}
+	})
+
+	t.Run("spec file supplies values", func(t *testing.T) {
+		f := defaultFlags(dir)
+		f.specFile = writeSpec(t, `version: "1"
+name: from-spec
+role: review
+description: From the spec
+on: label:needs-review
+model: sonnet
+timeout_minutes: 30
+`)
+		opts, _, _, err := resolveAgentNewOptions("", f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if opts.Name != "from-spec" || opts.Role != "review" || opts.Model != "sonnet" {
+			t.Errorf("spec not applied: %+v", opts)
+		}
+		if opts.TimeoutMinutes != 30 || opts.Description != "From the spec" {
+			t.Errorf("spec not applied: %+v", opts)
+		}
+		if !strings.Contains(opts.Trigger, "needs-review") {
+			t.Errorf("spec trigger not applied: %q", opts.Trigger)
+		}
+	})
+
+	t.Run("flags override spec keys", func(t *testing.T) {
+		f := defaultFlags(dir, "role", "model")
+		f.role, f.model = "coder", "haiku"
+		f.specFile = writeSpec(t, "version: \"1\"\nname: from-spec\nrole: review\nmodel: sonnet\n")
+		opts, _, _, err := resolveAgentNewOptions("", f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if opts.Role != "coder" || opts.Model != "haiku" {
+			t.Errorf("flags should win over spec: %+v", opts)
+		}
+	})
+
+	t.Run("explicit slug suppresses the fallback warning", func(t *testing.T) {
+		f := defaultFlags(dir, "slug")
+		f.slug = "my-org-lint-docs"
+		opts, _, warning, err := resolveAgentNewOptions("lint-docs", f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if opts.Slug != "my-org-lint-docs" || warning != "" {
+			t.Errorf("slug = %q, warning = %q", opts.Slug, warning)
+		}
+	})
+}
+
+func TestSlashCommandFromTrigger(t *testing.T) {
+	expr, err := agentnew.ExpandTrigger("command:/fs-lint-docs", "lint-docs")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := slashCommandFromTrigger(expr); got != "/fs-lint-docs" {
+		t.Errorf("slashCommandFromTrigger = %q", got)
+	}
+	label, err := agentnew.ExpandTrigger("label:x", "lint-docs")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := slashCommandFromTrigger(label); got != "" {
+		t.Errorf("a label trigger has no slash command, got %q", got)
+	}
+	if got := slashCommandFromTrigger(""); got != "" {
+		t.Errorf("empty trigger, got %q", got)
+	}
+}
+
+func writeSpec(t *testing.T, body string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "spec.yaml")
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
diff --git a/internal/cli/agent_test.go b/internal/cli/agent_test.go
index 9241078973..7bbc4ca773 100644
--- a/internal/cli/agent_test.go
+++ b/internal/cli/agent_test.go
@@ -1308,13 +1308,15 @@ allowed_remote_resources:
 
 func TestNewAgentCmd_HasSubcommands(t *testing.T) {
 	cmd := newAgentCmd()
-	assert.Len(t, cmd.Commands(), 5)
+	assert.Len(t, cmd.Commands(), 6)
 	names := make([]string, len(cmd.Commands()))
 	for i, c := range cmd.Commands() {
 		names[i] = c.Name()
 	}
+	assert.Contains(t, names, "new")
 	assert.Contains(t, names, "add")
 	assert.Contains(t, names, "list")
+	assert.Contains(t, names, "set")
 	assert.Contains(t, names, "update")
 	assert.Contains(t, names, "remove")
 	assert.NotContains(t, names, "migrate-customizations", "should not exist — removed per ADR-0064")
diff --git a/internal/config/config.go b/internal/config/config.go
index 5781297a69..e2a8815320 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -149,6 +149,13 @@ const (
 	DefaultUpstreamRef = "main"
 	// DefaultGHRunner is the default GitHub Actions runner image for scaffold workflows.
 	DefaultGHRunner = "ubuntu-24.04"
+	// DefaultSandboxImage and DefaultCodeImage are the sandbox images
+	// `fullsend agent new` writes into a generated harness. They track the
+	// fleet's pins in fullsend-ai/agents (harness/triage.yaml and
+	// harness/code.yaml) and are repinned by hand on the same cadence as the
+	// fleet repin PRs. `agent new --image` overrides them.
+	DefaultSandboxImage = "ghcr.io/fullsend-ai/fullsend-sandbox@sha256:f8255971fec8a72a60adb20f501e55098f237e699dc829f0894647c0de2a19c2"
+	DefaultCodeImage    = "ghcr.io/fullsend-ai/fullsend-code@sha256:ea2a31f38ee80e2a9a898a898a289fe432aa882fa5a4046c3236ab8e2627d7e7"
 )
 
 // DispatchConfig configures how agent work is dispatched.
@@ -295,6 +302,14 @@ type orgConfig struct {
 // mintcore's canonical roles: mint-only dogfood roles (e.g. scribe) can be
 // registered with `fullsend mint add-role` before scaffold/workflow wiring
 // lands, and must not silently pass config validation.
+// ValidConfigAgentName reports whether name is acceptable as an agents:
+// entry name. Exported so a caller that generates an agent can apply the
+// same rule before writing anything, rather than discovering the mismatch
+// when registration fails after the files are already on disk.
+func ValidConfigAgentName(name string) bool {
+	return validConfigAgentName.MatchString(name)
+}
+
 func ValidRoles() []string {
 	return []string{"fullsend", "triage", "coder", "review", "fix", "retro", "prioritize", "e2e"}
 }
diff --git a/internal/harness/checkgenerated.go b/internal/harness/checkgenerated.go
new file mode 100644
index 0000000000..d4aff2e73f
--- /dev/null
+++ b/internal/harness/checkgenerated.go
@@ -0,0 +1,80 @@
+package harness
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// CheckGenerated validates a harness that was just constructed in memory and
+// written to disk, in the order a caller needs after its own Load.
+//
+// It exists for `fullsend agent new`, whose whole purpose is to surface at
+// generation time the errors that otherwise appear only at the first dispatch
+// after merge. It is deliberately NOT wired into `fullsend run` or
+// `fullsend lock`: those two interleave minting, runner-env validation and
+// ${VAR} expansion between the same steps, in different orders, and
+// collapsing them here would change their behaviour.
+//
+// Returned diagnostics are Lint()'s non-fatal warnings; the caller decides
+// how to present them. An error means the harness is not usable.
+//
+// Not checked here, on purpose: ValidateRunnerEnvWith. It requires every
+// ${VAR} in env.runner/env.sandbox to be set in the calling process, which is
+// true in CI and false on a developer's machine. Failing generation because
+// GITHUB_ISSUE_URL is unset would make the command unusable for its main
+// audience. The consequence is that an unset variable surfaces at
+// `fullsend run` time instead; the generated docs say so.
+func CheckGenerated(h *Harness, absDir string) ([]Diagnostic, error) {
+	diags := h.Lint()
+
+	if err := h.ResolveRelativeTo(absDir); err != nil {
+		return diags, fmt.Errorf("resolving paths: %w", err)
+	}
+	if err := h.ValidateFilesExist(); err != nil {
+		return diags, fmt.Errorf("validating files: %w", err)
+	}
+	if err := h.validateResourceFilesExist(); err != nil {
+		return diags, err
+	}
+	return diags, nil
+}
+
+// validateResourceFilesExist stats the provider and profile files the
+// harness names by path.
+//
+// ValidateFilesExist deliberately skips these — ResolveHarness reads them
+// later, during the run's resolve step, and reports its own error. But a
+// generator has no resolve step, so without this check the one failure it
+// most needs to catch is invisible: a harness naming providers/vertex-ai.yaml
+// with no such file validates cleanly here and then fails at run time as
+// "reading profile ...: no such file or directory", or worse, degrades to a
+// warning and a sandbox that cannot reach Vertex.
+func (h *Harness) validateResourceFilesExist() error {
+	check := func(field, p string) error {
+		if p == "" || IsURL(p) || !IsProviderPath(p) {
+			return nil
+		}
+		path := p
+		if !filepath.IsAbs(path) {
+			return nil // ResolveRelativeTo has already made these absolute
+		}
+		if _, err := os.Stat(path); err != nil {
+			return fmt.Errorf("%s: %w", field, err)
+		}
+		return nil
+	}
+	for i, p := range h.Providers {
+		if err := check(fmt.Sprintf("providers[%d]", i), p); err != nil {
+			return err
+		}
+	}
+	if h.OpenShell != nil {
+		for i, p := range h.OpenShell.Profiles {
+			if err := check(fmt.Sprintf("openshell.profiles[%d]", i), p); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
diff --git a/internal/harness/checkgenerated_test.go b/internal/harness/checkgenerated_test.go
new file mode 100644
index 0000000000..15f36aebc7
--- /dev/null
+++ b/internal/harness/checkgenerated_test.go
@@ -0,0 +1,174 @@
+package harness
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeGeneratedTree lays down a minimal but complete agent tree of the shape
+// `fullsend agent new` produces, so CheckGenerated can be exercised directly
+// rather than through the generator.
+func writeGeneratedTree(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	files := map[string]string{
+		"harness/demo.yaml": `agent: agents/demo.md
+role: triage
+policy: policies/base.yaml
+post_script: scripts/post-demo.sh
+providers:
+  - providers/vertex-ai.yaml
+openshell:
+  profiles:
+    - profiles/fullsend-vertex-ai.yaml
+trigger: |
+  event.entity.kind == "work_item"
+`,
+		"agents/demo.md":                   "---\nname: demo\n---\n\nbody\n",
+		"policies/base.yaml":               "version: 1\n",
+		"scripts/post-demo.sh":             "#!/usr/bin/env bash\ntrue\n",
+		"providers/vertex-ai.yaml":         "name: vertex-ai\ntype: fullsend-vertex-ai\n",
+		"profiles/fullsend-vertex-ai.yaml": "id: fullsend-vertex-ai\n",
+	}
+	for path, body := range files {
+		full := filepath.Join(dir, path)
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+func loadDemo(t *testing.T, dir string) *Harness {
+	t.Helper()
+	h, err := Load(filepath.Join(dir, "harness", "demo.yaml"))
+	if err != nil {
+		t.Fatalf("loading the test harness: %v", err)
+	}
+	return h
+}
+
+func TestCheckGeneratedHappyPath(t *testing.T) {
+	dir := writeGeneratedTree(t)
+	diags, err := CheckGenerated(loadDemo(t, dir), dir)
+	if err != nil {
+		t.Fatalf("a complete tree should validate: %v", err)
+	}
+	if len(diags) != 0 {
+		t.Errorf("unexpected diagnostics: %v", diags)
+	}
+}
+
+// TestCheckGeneratedMissingFiles covers both halves of the file checking:
+// ValidateFilesExist for the agent/policy/script, and the extra provider and
+// profile stat that ValidateFilesExist deliberately skips.
+func TestCheckGeneratedMissingFiles(t *testing.T) {
+	for _, victim := range []string{
+		"agents/demo.md",
+		"policies/base.yaml",
+		"scripts/post-demo.sh",
+		"providers/vertex-ai.yaml",
+		"profiles/fullsend-vertex-ai.yaml",
+	} {
+		t.Run(victim, func(t *testing.T) {
+			dir := writeGeneratedTree(t)
+			if err := os.Remove(filepath.Join(dir, victim)); err != nil {
+				t.Fatal(err)
+			}
+			_, err := CheckGenerated(loadDemo(t, dir), dir)
+			if err == nil {
+				t.Fatalf("removing %s was not detected", victim)
+			}
+			if !strings.Contains(err.Error(), filepath.Base(victim)) {
+				t.Errorf("error should name %q, got: %v", victim, err)
+			}
+		})
+	}
+}
+
+// TestCheckGeneratedReturnsLintDiagnostics: a deprecated shape is reported as
+// a non-fatal diagnostic, not an error, so the caller can warn and continue.
+func TestCheckGeneratedReturnsLintDiagnostics(t *testing.T) {
+	dir := writeGeneratedTree(t)
+	h := loadDemo(t, dir)
+	h.RunnerEnv = map[string]string{"LEGACY": "value"} // deprecated by ADR 0055
+
+	diags, err := CheckGenerated(h, dir)
+	if err != nil {
+		t.Fatalf("a deprecated shape must not be fatal: %v", err)
+	}
+	if len(diags) == 0 {
+		t.Fatal("expected a diagnostic for runner_env")
+	}
+	var found bool
+	for _, d := range diags {
+		if d.Field == "runner_env" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected a runner_env diagnostic, got %v", diags)
+	}
+}
+
+// TestCheckGeneratedRejectsEscapingPaths: ResolveRelativeTo must refuse a
+// path that climbs out of the fullsend directory.
+func TestCheckGeneratedRejectsEscapingPaths(t *testing.T) {
+	dir := writeGeneratedTree(t)
+	h := loadDemo(t, dir)
+	h.Policy = "../../etc/shadow"
+
+	if _, err := CheckGenerated(h, dir); err == nil {
+		t.Fatal("a path escaping the fullsend directory should be refused")
+	} else if !strings.Contains(err.Error(), "resolves outside") {
+		t.Errorf("unexpected error: %v", err)
+	}
+}
+
+// TestCheckGeneratedSkipsBareProviderNames: a bare name is resolved from the
+// binary's embedded definitions, not from disk, so it must not be stat-ed.
+func TestCheckGeneratedSkipsBareProviderNames(t *testing.T) {
+	dir := writeGeneratedTree(t)
+	h := loadDemo(t, dir)
+	h.Providers = []string{"vertex-ai"}
+	h.OpenShell = nil
+
+	if _, err := CheckGenerated(h, dir); err != nil {
+		t.Errorf("a bare provider name should not be stat-ed: %v", err)
+	}
+}
+
+func TestValidAgentBasename(t *testing.T) {
+	for _, name := range []string{"a", "lint-docs", "Lint_Docs9", "A-B_c-1"} {
+		if !ValidAgentBasename(name) {
+			t.Errorf("ValidAgentBasename(%q) = false, want true", name)
+		}
+	}
+	// The rejected set is the security-relevant half: the agent name reaches
+	// shell interpolation.
+	for _, name := range []string{
+		"", "a b", "a;rm -rf /", "a$(id)", "a`id`", "../escape", "a/b", "a|b", "a&b", "a\nb", "ä",
+	} {
+		if ValidAgentBasename(name) {
+			t.Errorf("ValidAgentBasename(%q) = true, want false", name)
+		}
+	}
+}
+
+func TestValidSlug(t *testing.T) {
+	for _, slug := range []string{"a", "0", "my-org-agent", "Org_1-x"} {
+		if !ValidSlug(slug) {
+			t.Errorf("ValidSlug(%q) = false, want true", slug)
+		}
+	}
+	for _, slug := range []string{"", "-leading", "_leading", "has space", "has/slash", "a.b"} {
+		if ValidSlug(slug) {
+			t.Errorf("ValidSlug(%q) = true, want false", slug)
+		}
+	}
+}
diff --git a/internal/harness/harness.go b/internal/harness/harness.go
index fd125e0284..92c7120da3 100644
--- a/internal/harness/harness.go
+++ b/internal/harness/harness.go
@@ -41,6 +41,20 @@ func ValidPluginBasename(name string) bool {
 	return validPluginName.MatchString(name)
 }
 
+// ValidAgentBasename reports whether name is a safe agent name — the same
+// check Validate applies to the agent: basename (minus .md). Exported so a
+// caller that constructs a harness, rather than loading one, can reject an
+// unsafe name before writing it anywhere: the name reaches shell
+// interpolation, so this is a security check, not a style check.
+func ValidAgentBasename(name string) bool {
+	return validAgentName.MatchString(name)
+}
+
+// ValidSlug reports whether slug matches the allowed harness slug pattern.
+func ValidSlug(slug string) bool {
+	return validSlugName.MatchString(slug)
+}
+
 // ChmodPluginDir makes all files under dir executable (0755). It resolves
 // symlinks first so it operates on the real directory tree. Plugins may
 // contain scripts or MCP server binaries that need the execute bit.