From 0937bebf325829fb1ad676306ccb26ac32ab03ec Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 11:44:20 -0400
Subject: [PATCH 01/17] feat(#6966): add role table, trigger presets and spec
 parsing for agent new
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Groundwork for `fullsend agent new`: the three pure, network-free pieces
the generator is built on.

The role table is hardcoded rather than derived from
mintcore.BuiltInRoles(). Derivation would re-admit `scribe`, which
config.ValidRoles() deliberately excludes as a mint-only dogfood role
that "must not silently pass config validation", and it would fail open
for any future canonical role with no provider pairing. Drift is caught
by a test asserting each role is in both BuiltInRoles() and ValidRoles()
and that its permissions equal mintcore.RolePermissionsFor(role) —
BuiltInRoles rather than HasRole, because HasRole also returns true for
standalone-mint custom roles registered at runtime.

Trigger presets are pinned by string equality, not just compiled. An
expression can compile and still touch an absent optional field, which
fails only at first dispatch — MatchHarnesses turns that into a red
::error:: annotation on every matching event. The `command` preset
guards fork pull requests with has() rather than the reference doc's
`!= null`: state.change_proposal is absent, not null, on a non-PR
comment, so `!= null` raises a missing-key error on every issue comment.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/roles.go        | 147 +++++++++++++++++++++++++++++
 internal/agentnew/roles_test.go   | 128 ++++++++++++++++++++++++++
 internal/agentnew/spec.go         |  77 ++++++++++++++++
 internal/agentnew/spec_test.go    |  82 +++++++++++++++++
 internal/agentnew/trigger.go      | 116 +++++++++++++++++++++++
 internal/agentnew/trigger_test.go | 148 ++++++++++++++++++++++++++++++
 internal/config/config.go         |   7 ++
 7 files changed, 705 insertions(+)
 create mode 100644 internal/agentnew/roles.go
 create mode 100644 internal/agentnew/roles_test.go
 create mode 100644 internal/agentnew/spec.go
 create mode 100644 internal/agentnew/spec_test.go
 create mode 100644 internal/agentnew/trigger.go
 create mode 100644 internal/agentnew/trigger_test.go

diff --git a/internal/agentnew/roles.go b/internal/agentnew/roles.go
new file mode 100644
index 0000000000..236feb5e51
--- /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, suffix, strings.Join(perms, ", "))
+	}
+	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..a880b63bd9
--- /dev/null
+++ b/internal/agentnew/spec.go
@@ -0,0 +1,77 @@
+package agentnew
+
+import (
+	"bytes"
+	"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 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.
+	var extra AgentSpec
+	if err := dec.Decode(&extra); err == nil {
+		return nil, fmt.Errorf("spec file must contain exactly one YAML document")
+	}
+
+	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 < 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..b91c56feaf
--- /dev/null
+++ b/internal/agentnew/spec_test.go
@@ -0,0 +1,82 @@
+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 != 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")
+	}
+}
diff --git a/internal/agentnew/trigger.go b/internal/agentnew/trigger.go
new file mode 100644
index 0000000000..8fa73455e0
--- /dev/null
+++ b/internal/agentnew/trigger.go
@@ -0,0 +1,116 @@
+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. 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"
+  && 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_test.go b/internal/agentnew/trigger_test.go
new file mode 100644
index 0000000000..27b2bb2d0b
--- /dev/null
+++ b/internal/agentnew/trigger_test.go
@@ -0,0 +1,148 @@
+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"
+  && 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"
+  && 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"
+  && 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/config/config.go b/internal/config/config.go
index 5781297a69..fa51161139 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.

From 6148b32f24ac7ccc86ced5275e7862d55de44ed2 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 11:48:18 -0400
Subject: [PATCH 02/17] feat(#6966): render a complete agent tree from
 validated options
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Render turns resolved options into the full file set: harness, agent
definition, result schema, post-script, and the shared scaffold assets a
generated agent depends on but does not own.

The harness is built as a harness.Harness value and marshalled, never
formatted as text, so the generator cannot emit a field the validator
does not know about. The agent definition's frontmatter is marshalled
for the same reason: a --description containing a colon or a leading ">"
would otherwise produce a broken document. The only user value that
reaches the generated shell script is the agent name, substituted after
it has passed harness.ValidAgentBasename.

Providers and profiles are referenced by path, not bare name. A bare
name with no definition on disk does not fail loudly — the embedded
fallback fills in only the OpenAI provider, so any other name degrades
to a warning and then a sandbox that cannot reach Vertex. The generator
therefore also writes policies/, providers/ and profiles/ when absent: a
per-repo install vendors none of them, CI's workspace layering skips
policies/ because the embedded scaffold has no such directory, and
profiles/ was never in LAYERED_DIRS at all.

ValidAgentBasename and ValidSlug are exported alongside the existing
ValidPluginBasename so a caller that constructs a harness, rather than
loading one, can reject an unsafe name before writing it anywhere.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/assets.go                   |  55 ++++
 internal/agentnew/options.go                  |  72 +++++
 internal/agentnew/options_test.go             |  85 ++++++
 internal/agentnew/render.go                   | 237 ++++++++++++++++
 internal/agentnew/render_test.go              | 268 ++++++++++++++++++
 .../agentnew/templates/agent-body.md.tmpl     |  44 +++
 .../agentnew/templates/policies/base.yaml     |  22 ++
 internal/agentnew/templates/post.sh.tmpl      |  85 ++++++
 .../scripts/validate-output-schema.sh         |  70 +++++
 internal/harness/harness.go                   |  14 +
 10 files changed, 952 insertions(+)
 create mode 100644 internal/agentnew/assets.go
 create mode 100644 internal/agentnew/options.go
 create mode 100644 internal/agentnew/options_test.go
 create mode 100644 internal/agentnew/render.go
 create mode 100644 internal/agentnew/render_test.go
 create mode 100644 internal/agentnew/templates/agent-body.md.tmpl
 create mode 100644 internal/agentnew/templates/policies/base.yaml
 create mode 100644 internal/agentnew/templates/post.sh.tmpl
 create mode 100755 internal/agentnew/templates/scripts/validate-output-schema.sh

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/options.go b/internal/agentnew/options.go
new file mode 100644
index 0000000000..6d4f3d9c61
--- /dev/null
+++ b/internal/agentnew/options.go
@@ -0,0 +1,72 @@
+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 {
+	if !harness.ValidAgentBasename(o.Name) {
+		return fmt.Errorf("agent name %q contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)", 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..8cfca00708
--- /dev/null
+++ b/internal/agentnew/options_test.go
@@ -0,0 +1,85 @@
+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 = "" }, "invalid characters"},
+		{"name with semicolon", func(o *Options) { o.Name = "a;rm -rf /" }, "invalid characters"},
+		{"name with slash", func(o *Options) { o.Name = "../escape" }, "invalid characters"},
+		{"name with space", func(o *Options) { o.Name = "lint docs" }, "invalid characters"},
+		{"name with dollar", func(o *Options) { o.Name = "a$(id)" }, "invalid characters"},
+		{"name with backtick", func(o *Options) { o.Name = "a`id`" }, "invalid characters"},
+		{"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/render.go b/internal/agentnew/render.go
new file mode 100644
index 0000000000..cc1194449f
--- /dev/null
+++ b/internal/agentnew/render.go
@@ -0,0 +1,237 @@
+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.ValidAgentName 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,
+		}
+	}
+	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. `image:` is the fleet's current pin; pass\n")
+	buf.WriteString("# --image to override it.\n#\n")
+	buf.WriteString("# This agent is GitHub-only. To add GitLab or Jira, see the overlays\n")
+	buf.WriteString("# section of 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,
+		// Exactly what the generated body uses, no more: tools must stay
+		// consistent with the body (fullsend-ai/agents#992).
+		Tools: "Bash(gh,jq), Read, Grep, Glob",
+		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)))
+	return buf.Bytes(), nil
+}
+
+func renderSchema(name string) ([]byte, error) {
+	// Built as an ordered document via json.RawMessage rather than a map so
+	// the property order is stable and readable; MarshalIndent on a map
+	// would sort keys and scatter the required list.
+	schema := map[string]any{
+		"$schema":              "https://json-schema.org/draft/2020-12/schema",
+		"$id":                  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"}},
+			"summary": map[string]any{"type": "string", "minLength": 1, "maxLength": 200},
+			"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
+}
+
+// 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.ValidAgentName, 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..14e6cdee03
--- /dev/null
+++ b/internal/agentnew/render_test.go
@@ -0,0 +1,268 @@
+package agentnew
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"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")
+	}
+	if doc["$id"] != "lint-docs-result.schema.json" {
+		t.Errorf("$id = %v", doc["$id"])
+	}
+}
+
+// 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
+}
diff --git a/internal/agentnew/templates/agent-body.md.tmpl b/internal/agentnew/templates/agent-body.md.tmpl
new file mode 100644
index 0000000000..e0a06b54dd
--- /dev/null
+++ b/internal/agentnew/templates/agent-body.md.tmpl
@@ -0,0 +1,44 @@
+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.
+
+Before you finish, run `fullsend-check-output "$FULLSEND_OUTPUT_DIR/agent-result.json"`
+to catch schema violations while you can still fix them.
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..849a22d02f
--- /dev/null
+++ b/internal/agentnew/templates/post.sh.tmpl
@@ -0,0 +1,85 @@
+#!/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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:__AGENT_NAME__-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-__AGENT_NAME__: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-__AGENT_NAME__: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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/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.

From 7a9f0318115b315a05f62ea88fed4b84e34affa4 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 11:50:11 -0400
Subject: [PATCH 03/17] feat(#6966): validate a generated agent tree before it
 is registered
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CheckGenerated runs the checks a freshly constructed harness needs:
Lint diagnostics, ResolveRelativeTo, ValidateFilesExist, and a stat of
every provider and profile named by path.

That fourth step is the point of the helper. ValidateFilesExist skips
providers and profiles deliberately — ResolveHarness reads them later,
during the run's resolve step, and reports its own error. A generator
has no resolve step, so without it the failure the generator most needs
to catch is invisible: a harness naming providers/vertex-ai.yaml with no
such file validates cleanly and then fails at run time, or degrades to a
warning and a sandbox that cannot reach Vertex.

CheckGenerated is deliberately not wired into run or lock. Those two
interleave minting, runner-env validation and ${VAR} expansion between
the same steps, in different orders — run expands paths so they resolve
before ValidateFilesExist stat-checks them, and lock never calls
ValidateFilesExist at all. Collapsing them would change behaviour on the
two hottest execution paths. ValidateRunnerEnvWith is likewise excluded,
and says so: it requires every ${VAR} to be set in the calling process,
which is true in CI and false on a developer's machine.

The trigger presets are now evaluated against the normative
NormalizedEvent v1 fixtures. The command preset is the default, so every
generated agent carries it, including role coder — it must fire for a
non-fork pull request comment and an issue comment, and must not fire
for a comment on a fork. A companion test evaluates it against all
thirteen fixtures and asserts it errors on none: that is the property
the reference doc's `!= null` does not have.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/checkgenerated_test.go   | 115 +++++++++++++
 internal/agentnew/trigger_fixtures_test.go | 185 +++++++++++++++++++++
 internal/harness/checkgenerated.go         |  80 +++++++++
 3 files changed, 380 insertions(+)
 create mode 100644 internal/agentnew/checkgenerated_test.go
 create mode 100644 internal/agentnew/trigger_fixtures_test.go
 create mode 100644 internal/harness/checkgenerated.go

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/trigger_fixtures_test.go b/internal/agentnew/trigger_fixtures_test.go
new file mode 100644
index 0000000000..1f6cec491a
--- /dev/null
+++ b/internal/agentnew/trigger_fixtures_test.go
@@ -0,0 +1,185 @@
+package agentnew
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"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")
+	}
+}
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
+}

From f8e6c993ba02e6413eab0f865c37ab4403c825dc Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:22:25 -0400
Subject: [PATCH 04/17] feat(#6966): add `fullsend agent new`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Generates a complete, valid, runnable custom agent from a name and a
role, registers it, and validates the result with the same loader
dispatch uses — so the errors that used to appear at the first dispatch
after merge appear at generation time instead.

Ordering is the substance of the command. The name is checked against
the shell-safety pattern before anything touches disk; the trigger is
expanded and compiled before any file is written; everything is rendered
and validated in a scratch directory first, so a harness that would fail
validation never leaves a half-written .fullsend behind. Where a shared
asset already exists in the target, the target's copy is what gets
validated, since a hand-edited policies/base.yaml is common and its
content matters.

--force overwrites the four files an agent owns but never a shared
scaffold asset, and never papers over a config name collision.

A trigger is mandatory. ListTriggeredHarnesses skips a trigger-less
harness with a bare `continue` and no annotation, so such an agent
registers, validates, appears in `agent list`, and is then silently
never dispatched — the single failure this command is best placed to
prevent. The printed CI instruction is derived from the same trigger
that went into the harness, so the two cannot disagree.

The existing subcommand-count assertion is updated for the sixth
subcommand and gains positive assertions for `new` and `set`.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/generate.go           | 221 +++++++++++++
 internal/agentnew/generate_slug_test.go |  83 +++++
 internal/agentnew/roles.go              |   4 +-
 internal/cli/agent.go                   |   3 +-
 internal/cli/agent_new.go               | 296 ++++++++++++++++++
 internal/cli/agent_new_test.go          | 395 ++++++++++++++++++++++++
 internal/cli/agent_test.go              |   4 +-
 7 files changed, 1002 insertions(+), 4 deletions(-)
 create mode 100644 internal/agentnew/generate.go
 create mode 100644 internal/agentnew/generate_slug_test.go
 create mode 100644 internal/cli/agent_new.go
 create mode 100644 internal/cli/agent_new_test.go

diff --git a/internal/agentnew/generate.go b/internal/agentnew/generate.go
new file mode 100644
index 0000000000..eb1c9da7e2
--- /dev/null
+++ b/internal/agentnew/generate.go
@@ -0,0 +1,221 @@
+package agentnew
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/fullsend-ai/fullsend/internal/harness"
+)
+
+// 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.
+	Written []string
+	// 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 info, statErr := os.Stat(absDir); statErr != nil || !info.IsDir() {
+		return nil, fmt.Errorf("fullsend dir %s does not exist; run `fullsend github setup` first", fullsendDir)
+	}
+
+	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.
+	var collisions []string
+	writable := make([]File, 0, len(files))
+	result := &Result{HarnessPath: filepath.Join("harness", opts.Name+".yaml")}
+	for _, f := range files {
+		_, statErr := os.Stat(filepath.Join(absDir, f.Path))
+		exists := statErr == nil
+		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
+	}
+	if dryRun {
+		return result, nil
+	}
+
+	for _, f := range writable {
+		path := filepath.Join(absDir, f.Path)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			return nil, fmt.Errorf("creating %s: %w", filepath.Dir(f.Path), err)
+		}
+		// Written directly rather than renamed in from the temp tree: a
+		// rename across filesystems fails, and the bytes are already here.
+		if err := os.WriteFile(path, f.Data, os.FileMode(f.Mode)); err != nil {
+			return nil, fmt.Errorf("writing %s: %w", f.Path, err)
+		}
+		result.Written = append(result.Written, f.Path)
+	}
+	return result, 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 {
+			if existing, readErr := os.ReadFile(filepath.Join(absDir, f.Path)); readErr == nil {
+				data = existing
+			}
+		}
+		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 reads .git/config for the origin remote and extracts the
+// owner. It understands the two URL forms git writes.
+func GitConfigOwner(dir string) string {
+	for depth := 0; depth < 20; depth++ {
+		data, err := os.ReadFile(filepath.Join(dir, ".git", "config"))
+		if err == nil {
+			return ownerFromGitConfig(string(data))
+		}
+		if !errors.Is(err, os.ErrNotExist) {
+			return ""
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			return ""
+		}
+		dir = parent
+	}
+	return ""
+}
+
+func ownerFromGitConfig(cfg string) string {
+	inOrigin := false
+	for _, line := range strings.Split(cfg, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "[remote ") {
+			inOrigin = strings.Contains(trimmed, `"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..71a90d06b7
--- /dev/null
+++ b/internal/agentnew/generate_slug_test.go
@@ -0,0 +1,83 @@
+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)
+	}
+}
diff --git a/internal/agentnew/roles.go b/internal/agentnew/roles.go
index 236feb5e51..461672b81b 100644
--- a/internal/agentnew/roles.go
+++ b/internal/agentnew/roles.go
@@ -136,9 +136,9 @@ func RoleHelp() string {
 		sort.Strings(perms)
 		suffix := ""
 		if name == DefaultRole {
-			suffix = " (default)"
+			suffix = "  (default)"
 		}
-		fmt.Fprintf(&b, "  %-11s%s %s\n", name, suffix, strings.Join(perms, ", "))
+		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")
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..0688ffc58b
--- /dev/null
+++ b/internal/cli/agent_new.go
@@ -0,0 +1,296 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/fullsend-ai/fullsend/internal/agentnew"
+	"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
+		}
+		if !f.changed("timeout-minutes") && spec.TimeoutMinutes != 0 {
+			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 == "" {
+		owner := agentnew.GitConfigOwner(f.fullsendDir)
+		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 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)
+	}
+
+	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 _, f := range result.Written {
+			printer.Raw("  " + f + "\n")
+		}
+		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, ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION\n")
+	printer.Raw("     and GH_TOKEN. See 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]
+}
diff --git a/internal/cli/agent_new_test.go b/internal/cli/agent_new_test.go
new file mode 100644
index 0000000000..fee9c93048
--- /dev/null
+++ b/internal/cli/agent_new_test.go
@@ -0,0 +1,395 @@
+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 TestAgentNewDryRunWritesNothing(t *testing.T) {
+	dir := newFullsendDir(t)
+	before := treeSnapshot(t, dir)
+
+	f := defaultFlags(dir)
+	f.dryRun = true
+	out, err := runNew(t, "lint-docs", f)
+	if err != nil {
+		t.Fatalf("dry run failed: %v", err)
+	}
+	if !strings.Contains(out, "Nothing was written") {
+		t.Errorf("dry run should say nothing was written:\n%s", out)
+	}
+	if after := treeSnapshot(t, dir); after != before {
+		t.Errorf("dry run modified the directory\nbefore: %s\nafter:  %s", before, after)
+	}
+}
+
+// TestAgentNewRejectsCollisions and --force semantics: --force may overwrite
+// the files this agent owns, but never a shared scaffold asset.
+func TestAgentNewForceNeverOverwritesSharedAssets(t *testing.T) {
+	dir := newFullsendDir(t)
+	if _, err := runNew(t, "lint-docs", defaultFlags(dir)); err != nil {
+		t.Fatal(err)
+	}
+
+	sentinel := []byte("# hand-edited, must survive\n")
+	policyPath := filepath.Join(dir, "policies", "base.yaml")
+	if err := os.WriteFile(policyPath, 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)
+	}
+
+	// Without --force the collision is refused and nothing changes.
+	if _, err := runNew(t, "lint-docs", defaultFlags(dir)); err == nil {
+		t.Fatal("a second run without --force should fail")
+	}
+	if got, _ := os.ReadFile(harnessPath); string(got) != "clobbered\n" {
+		t.Error("a refused run must not modify anything")
+	}
+
+	f := defaultFlags(dir)
+	f.force = true
+	f.noRegister = true // already registered; --force must not paper over that
+	if _, err := runNew(t, "lint-docs", f); err != nil {
+		t.Fatalf("--force run failed: %v", err)
+	}
+	if got, _ := os.ReadFile(harnessPath); string(got) == "clobbered\n" {
+		t.Error("--force should have rewritten the harness")
+	}
+	if got, _ := os.ReadFile(policyPath); string(got) != string(sentinel) {
+		t.Errorf("--force must never overwrite a shared asset; policy is now %q", got)
+	}
+}
+
+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 TestAgentNewMissingDir(t *testing.T) {
+	_, err := runNew(t, "lint-docs", defaultFlags(filepath.Join(t.TempDir(), "nope")))
+	if err == nil {
+		t.Fatal("a missing fullsend dir should fail")
+	}
+	if !strings.Contains(err.Error(), "github setup") {
+		t.Errorf("error should point at github setup, got: %v", err)
+	}
+}
+
+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
+}
+
+// treeSnapshot renders a directory's file list and contents for comparison.
+func treeSnapshot(t *testing.T, dir string) string {
+	t.Helper()
+	var b strings.Builder
+	err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() {
+			return err
+		}
+		data, readErr := os.ReadFile(path)
+		if readErr != nil {
+			return readErr
+		}
+		b.WriteString(path + ":" + string(data) + "\n")
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b.String()
+}
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")

From 8ede72d95827fa7284f9af945884e1b533fc7d21 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:30:03 -0400
Subject: [PATCH 05/17] docs(#6966): document `agent new` and fix the
 slash-command trigger
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every command shown was run against a real temporary --fullsend-dir and
the output pasted is the output it produced.

The CEL reference's slash-command pattern is corrected to use
!has(state.change_proposal) rather than `!= null`. change_proposal is
ABSENT on a comment posted to a plain issue, not present-and-null — the
NormalizedEvent schema requires only `labels` under `state` — so
comparing it against null raises a missing-key error, and dispatch
reports that as `trigger eval failed` on every issue comment in the
repository. The corrected block is byte-identical to what
`agent new --on command:` emits, and a test asserts the two stay that
way.

The Bring Your Own Agent guide claimed twice that `github setup` creates
policies/, providers/ and profiles/. It creates none of them, and that
sentence is what walks authors into #6834; it now says so and points at
the generator.

ADR 0102 records the decision. It is a new ADR, not a superseding one:
#4839's July "prefer guides over a CLI" call was taken in Slack and
never written up.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 docs/ADRs/0058-agent-registration.md          |   8 +
 ...102-generate-custom-agents-from-the-cli.md | 130 +++++++++
 docs/cli/agent.md                             | 275 +++++++++++++++++-
 docs/guides/dev/cli-internals.md              |  11 +-
 docs/guides/getting-started/operations.md     |   1 +
 docs/guides/user/bring-your-own-agent.md      |  38 ++-
 docs/guides/user/building-custom-agents.md    |   8 +-
 docs/guides/user/cel-triggers-reference.md    |  18 +-
 docs/guides/user/customizing-agents.md        |   2 +
 docs/guides/user/customizing-with-skills.md   |   2 +
 internal/agentnew/generate.go                 |  13 +-
 internal/agentnew/golden_test.go              | 135 +++++++++
 internal/agentnew/testdata/golden/coder.txt   | 231 +++++++++++++++
 .../testdata/golden/label-trigger.txt         | 230 +++++++++++++++
 .../agentnew/testdata/golden/prioritize.txt   | 231 +++++++++++++++
 internal/agentnew/testdata/golden/retro.txt   | 237 +++++++++++++++
 internal/agentnew/testdata/golden/review.txt  | 231 +++++++++++++++
 internal/agentnew/testdata/golden/triage.txt  | 231 +++++++++++++++
 .../testdata/golden/validation-loop.txt       | 237 +++++++++++++++
 internal/agentnew/trigger_fixtures_test.go    |  54 ++++
 internal/cli/agent_new.go                     |  11 +-
 internal/cli/agent_new_test.go                |  12 +
 22 files changed, 2331 insertions(+), 15 deletions(-)
 create mode 100644 docs/ADRs/0102-generate-custom-agents-from-the-cli.md
 create mode 100644 internal/agentnew/golden_test.go
 create mode 100644 internal/agentnew/testdata/golden/coder.txt
 create mode 100644 internal/agentnew/testdata/golden/label-trigger.txt
 create mode 100644 internal/agentnew/testdata/golden/prioritize.txt
 create mode 100644 internal/agentnew/testdata/golden/retro.txt
 create mode 100644 internal/agentnew/testdata/golden/review.txt
 create mode 100644 internal/agentnew/testdata/golden/triage.txt
 create mode 100644 internal/agentnew/testdata/golden/validation-loop.txt

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..44fa457e83
--- /dev/null
+++ b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
@@ -0,0 +1,130 @@
+---
+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, with `--template-dir` as an override.
+
+## 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.
+
+The cost is a second place where harness shape is encoded. That is 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.
+
+Two limits are deliberate and documented. `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`. And 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.
+
+The generator does not replace `fullsend lock` or `fullsend run` validation and
+is not wired into them: those 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/cli/agent.md b/docs/cli/agent.md
index 63a2b05822..8cc262531f 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,285 @@ 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. This is the
+fastest path from nothing to a working agent — you edit prose, not 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"
+
+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`. A per-repo
+install does not vendor them, which is why `agent new` writes them.
+
+### 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` | | Raw CEL trigger expression; 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>` | Harness slug; `<owner>` comes from the `origin` remote |
+| `--image` | per-role pin | Sandbox image |
+| `--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 the **mint** role, not the agent's name. It selects which GitHub App
+identity and permissions the mint issues. 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 at the
+first dispatch. To use a role the hosted mint does not serve, you need your own
+mint — see [Custom Agent Identity](../guides/user/custom-agent-identity.md).
+
+### Triggers
+
+Every generated agent gets a `trigger:`. An agent without one registers and
+validates but is **silently never dispatched**, so `agent new` refuses to write
+one. `--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 emitted expressions are exactly the ones in
+[CEL Triggers Reference](../guides/user/cel-triggers-reference.md#common-trigger-patterns);
+a test asserts the two stay identical. For anything else, pass `--trigger` with
+raw CEL — it is compiled before any file is written.
+
+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. To actually run the agent, fill in the marked sections
+of `agents/<name>.md`, then follow
+[Running agents locally](../guides/user/running-agents-locally.md) — a real run
+needs GCP credentials, a sandbox image, and an `--env-file` supplying
+`GITHUB_ISSUE_URL`, `ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION` and
+`GH_TOKEN`. Set `POST_<NAME>_DRY_RUN=1` (for example
+`POST_LINT_DOCS_DRY_RUN=1`) so the generated post-script prints its comment
+instead of posting it.
+
+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..b2de57e7de 100644
--- a/docs/guides/user/bring-your-own-agent.md
+++ b/docs/guides/user/bring-your-own-agent.md
@@ -14,6 +14,38 @@ This guide uses the [fullsend-ai/agents](https://github.com/fullsend-ai/agents)
 
 ## Overview
 
+### Step 0: generate the skeleton
+
+Start here. [`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 below. Fill in the marked sections of
+`agents/lint-docs.md`, then go to [Testing locally](#testing-locally). The rest
+of this guide explains what was generated and how to change it — read it when
+you need to go beyond the defaults, or when you are writing a harness by hand.
+
+### 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 +56,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 +100,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 +391,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..8d94270799 100644
--- a/docs/guides/user/cel-triggers-reference.md
+++ b/docs/guides/user/cel-triggers-reference.md
@@ -98,17 +98,27 @@ 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"
     && 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.
+
+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/generate.go b/internal/agentnew/generate.go
index eb1c9da7e2..0b32e133c0 100644
--- a/internal/agentnew/generate.go
+++ b/internal/agentnew/generate.go
@@ -14,8 +14,11 @@ import (
 // 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.
+	// 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
@@ -72,6 +75,13 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 	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
 	}
@@ -86,7 +96,6 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 		if err := os.WriteFile(path, f.Data, os.FileMode(f.Mode)); err != nil {
 			return nil, fmt.Errorf("writing %s: %w", f.Path, err)
 		}
-		result.Written = append(result.Written, f.Path)
 	}
 	return result, nil
 }
diff --git a/internal/agentnew/golden_test.go b/internal/agentnew/golden_test.go
new file mode 100644
index 0000000000..4b346fd892
--- /dev/null
+++ b/internal/agentnew/golden_test.go
@@ -0,0 +1,135 @@
+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) {
+	cases := []struct {
+		name string
+		opts func() Options
+	}{
+		{"triage", func() Options { return testOptions("lint-docs", "triage") }},
+		{"coder", func() Options { return testOptions("lint-docs", "coder") }},
+		{"retro", func() Options { return testOptions("lint-docs", "retro") }},
+		{"review", func() Options { return testOptions("lint-docs", "review") }},
+		{"prioritize", func() Options { return testOptions("lint-docs", "prioritize") }},
+		{"validation-loop", func() Options {
+			o := testOptions("lint-docs", "triage")
+			o.ValidationLoop = true
+			return o
+		}},
+		{"label-trigger", func() Options {
+			o := testOptions("lint-docs", "triage")
+			trigger, err := ExpandTrigger("label:needs-docs", "lint-docs")
+			if err != nil {
+				panic(err)
+			}
+			o.Trigger = trigger
+			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/testdata/golden/coder.txt b/internal/agentnew/testdata/golden/coder.txt
new file mode 100644
index 0000000000..c3aa8dc9a9
--- /dev/null
+++ b/internal/agentnew/testdata/golden/coder.txt
@@ -0,0 +1,231 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of docs/guides/user/bring-your-own-agent.md.
+agent: agents/lint-docs.md
+description: Check docs changes for broken links
+role: coder
+slug: my-org-lint-docs
+image: ghcr.io/fullsend-ai/fullsend-code@sha256:ea2a31f38ee80e2a9a898a898a289fe432aa882fa5a4046c3236ab8e2627d7e7
+policy: policies/base.yaml
+providers:
+  - providers/vertex-ai.yaml
+  - providers/github.yaml
+openshell:
+  profiles:
+    - profiles/fullsend-vertex-ai.yaml
+    - profiles/fullsend-github.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"
+    && 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.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.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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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/label-trigger.txt b/internal/agentnew/testdata/golden/label-trigger.txt
new file mode 100644
index 0000000000..c4af76f187
--- /dev/null
+++ b/internal/agentnew/testdata/golden/label-trigger.txt
@@ -0,0 +1,230 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of 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 == "label_changed"
+    && event.transition.label.name == "needs-docs"
+    && event.transition.label.action == "added"
+=== 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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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/prioritize.txt b/internal/agentnew/testdata/golden/prioritize.txt
new file mode 100644
index 0000000000..1159c49ffe
--- /dev/null
+++ b/internal/agentnew/testdata/golden/prioritize.txt
@@ -0,0 +1,231 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of docs/guides/user/bring-your-own-agent.md.
+agent: agents/lint-docs.md
+description: Check docs changes for broken links
+role: prioritize
+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"
+    && 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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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/retro.txt b/internal/agentnew/testdata/golden/retro.txt
new file mode 100644
index 0000000000..25f2df6986
--- /dev/null
+++ b/internal/agentnew/testdata/golden/retro.txt
@@ -0,0 +1,237 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of docs/guides/user/bring-your-own-agent.md.
+agent: agents/lint-docs.md
+description: Check docs changes for broken links
+role: retro
+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
+  - providers/github-artifacts.yaml
+openshell:
+  profiles:
+    - profiles/fullsend-vertex-ai.yaml
+    - profiles/fullsend-github-ro.yaml
+    - profiles/fullsend-github-artifacts.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"
+    && 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-artifacts.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-artifacts.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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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/review.txt b/internal/agentnew/testdata/golden/review.txt
new file mode 100644
index 0000000000..25f91dc1d0
--- /dev/null
+++ b/internal/agentnew/testdata/golden/review.txt
@@ -0,0 +1,231 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of docs/guides/user/bring-your-own-agent.md.
+agent: agents/lint-docs.md
+description: Check docs changes for broken links
+role: review
+slug: my-org-lint-docs
+image: ghcr.io/fullsend-ai/fullsend-code@sha256:ea2a31f38ee80e2a9a898a898a289fe432aa882fa5a4046c3236ab8e2627d7e7
+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"
+    && 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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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/triage.txt b/internal/agentnew/testdata/golden/triage.txt
new file mode 100644
index 0000000000..cd35eafd15
--- /dev/null
+++ b/internal/agentnew/testdata/golden/triage.txt
@@ -0,0 +1,231 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of 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"
+    && 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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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..d35960b836
--- /dev/null
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -0,0 +1,237 @@
+=== agents/lint-docs.md mode=644
+---
+name: lint-docs
+description: Check docs changes for broken links
+tools: Bash(gh,jq), Read, Grep, Glob
+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 fleet's current pin; pass
+# --image to override it.
+#
+# This agent is GitHub-only. To add GitLab or Jira, see the overlays
+# section of 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
+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"
+    && 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": "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,
+      "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's iteration directory, so the agent output is ./output/agent-result.json.
+#
+# 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
+#
+# 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
+
+: "${ISSUE_URL:?ISSUE_URL must be set}"
+: "${GH_TOKEN:?GH_TOKEN must be set}"
+
+RESULT_FILE="output/agent-result.json"
+MARKER="<!-- fullsend:lint-docs-agent -->"
+MAX_SUMMARY_CHARS=200
+MAX_COMMENT_CHARS=16384
+
+if [[ ! -f "${RESULT_FILE}" ]]; then
+  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+  exit 1
+fi
+if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
+  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
+[[ -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
+if (( ${#comment} > MAX_COMMENT_CHARS )); then
+  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+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_fixtures_test.go b/internal/agentnew/trigger_fixtures_test.go
index 1f6cec491a..13aca1eb2c 100644
--- a/internal/agentnew/trigger_fixtures_test.go
+++ b/internal/agentnew/trigger_fixtures_test.go
@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/fullsend-ai/fullsend/internal/harness"
@@ -183,3 +184,56 @@ func TestLabelPreset(t *testing.T) {
 		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/cli/agent_new.go b/internal/cli/agent_new.go
index 0688ffc58b..5e662b6950 100644
--- a/internal/cli/agent_new.go
+++ b/internal/cli/agent_new.go
@@ -222,8 +222,15 @@ func runAgentNew(ctx context.Context, name string, f agentNewFlags, printer *ui.
 
 	if f.dryRun {
 		printer.StepInfo(fmt.Sprintf("Dry run: would create agent %q in %s", opts.Name, f.fullsendDir))
-		for _, f := range result.Written {
-			printer.Raw("  " + f + "\n")
+		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
diff --git a/internal/cli/agent_new_test.go b/internal/cli/agent_new_test.go
index fee9c93048..e2cf3cd880 100644
--- a/internal/cli/agent_new_test.go
+++ b/internal/cli/agent_new_test.go
@@ -140,6 +140,18 @@ func TestAgentNewDryRunWritesNothing(t *testing.T) {
 	if !strings.Contains(out, "Nothing was written") {
 		t.Errorf("dry run should say nothing was written:\n%s", out)
 	}
+	// A dry run that reports nothing is useless: it must list what would be
+	// created and show the rendered bodies.
+	for _, want := range []string{
+		"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)
+		}
+	}
 	if after := treeSnapshot(t, dir); after != before {
 		t.Errorf("dry run modified the directory\nbefore: %s\nafter:  %s", before, after)
 	}

From 55260f47c5262cda6be44ff8f49e183a9825e3a1 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:35:11 -0400
Subject: [PATCH 06/17] fix(#6966): derive the slug when generating inside a
 git worktree

In a linked worktree, .git is a FILE containing "gitdir: <path>" rather
than a directory, and the repository config lives in the main
repository's common directory. The owner lookup read dir/.git/config
directly, so inside a worktree it found nothing and every generated
agent silently fell back to the "fullsend-<name>" slug.

Worktrees are the normal way to work in this project, so that was the
common path rather than an edge case. readGitConfig now follows the
gitdir pointer and the commondir file; a malformed pointer still
degrades to the fallback rather than failing.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/generate.go           | 60 +++++++++++++++++++++----
 internal/agentnew/generate_slug_test.go | 50 +++++++++++++++++++++
 2 files changed, 102 insertions(+), 8 deletions(-)

diff --git a/internal/agentnew/generate.go b/internal/agentnew/generate.go
index 0b32e133c0..2c6f25c9a5 100644
--- a/internal/agentnew/generate.go
+++ b/internal/agentnew/generate.go
@@ -157,16 +157,13 @@ func DeriveSlug(name string, owner string) string {
 // repository, or "" when it cannot be determined.
 type RepoOwner func(dir string) string
 
-// GitConfigOwner reads .git/config for the origin remote and extracts the
-// owner. It understands the two URL forms git writes.
+// GitConfigOwner walks up from dir looking for a repository, and returns the
+// owner segment of its origin remote. 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++ {
-		data, err := os.ReadFile(filepath.Join(dir, ".git", "config"))
-		if err == nil {
-			return ownerFromGitConfig(string(data))
-		}
-		if !errors.Is(err, os.ErrNotExist) {
-			return ""
+		if cfg, ok := readGitConfig(dir); ok {
+			return ownerFromGitConfig(cfg)
 		}
 		parent := filepath.Dir(dir)
 		if parent == dir {
@@ -177,6 +174,53 @@ func GitConfigOwner(dir string) string {
 	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 {
+		if !errors.Is(err, os.ErrNotExist) {
+			return "", false
+		}
+		return "", false
+	}
+	return string(data), true
+}
+
 func ownerFromGitConfig(cfg string) string {
 	inOrigin := false
 	for _, line := range strings.Split(cfg, "\n") {
diff --git a/internal/agentnew/generate_slug_test.go b/internal/agentnew/generate_slug_test.go
index 71a90d06b7..55d5adf426 100644
--- a/internal/agentnew/generate_slug_test.go
+++ b/internal/agentnew/generate_slug_test.go
@@ -81,3 +81,53 @@ func TestDeriveSlug(t *testing.T) {
 		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)
+	}
+}

From 9706bb60814520252fe8ecbcc3668b8d6170f648 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:47:58 -0400
Subject: [PATCH 07/17] fix(#6966): close the write-path and validation gaps
 from review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six correctness findings, all on paths that could leave a repository
changed by a failed run or accept input that should be refused.

A name already registered in config.yaml was only detected during
registration, which happens after every file has been written — so a
duplicate name left the directory modified by a run that then failed.
The check now happens before anything is written, and the fullsend-dir
check happens before that, so a missing directory is still reported as
"run github setup first" rather than as a failure to read config.yaml
from inside it.

Destinations are now resolved with Lstat rather than Stat, and every
directory between the fullsend dir and each destination is checked. A
repository shipping a `.fullsend/harness` symlink, or a dangling symlink
at a destination, could otherwise redirect a generated file outside the
fullsend directory entirely. Anything that is not a regular file is
refused rather than overwritten.

A failure part-way through the write loop now removes the files that run
created, rather than leaving a partial agent: some files present, the
harness perhaps missing, nothing registered.

An existing shared asset that cannot be read — a directory in its place,
or bad permissions — now fails naming the path. It previously fell back
to validating the embedded copy, which is not the file the agent would
have run against.

--runtime is validated while options are resolved rather than during
registration, and only a real io.EOF ends a spec document: any other
error from the second decode is a malformed second document and is now
reported instead of being read as absence.

The opt-in validation_loop gains a preflight_check. The validation
script hard-fails when python3 or jsonschema is missing, and it does so
only after the agent has run; preflight_check is evaluated before
sandbox creation, so the same missing dependency costs nothing.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/generate.go | 89 +++++++++++++++++++++++++++++++++--
 internal/agentnew/render.go   |  6 +++
 internal/agentnew/spec.go     | 14 ++++--
 internal/cli/agent_new.go     | 39 +++++++++++++++
 4 files changed, 140 insertions(+), 8 deletions(-)

diff --git a/internal/agentnew/generate.go b/internal/agentnew/generate.go
index 2c6f25c9a5..a4c81aab68 100644
--- a/internal/agentnew/generate.go
+++ b/internal/agentnew/generate.go
@@ -11,6 +11,21 @@ import (
 	"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)
+	}
+	info, err := os.Stat(absDir)
+	if err != nil || !info.IsDir() {
+		return fmt.Errorf("fullsend dir %s does not exist; run `fullsend github setup` first", 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 {
@@ -39,8 +54,8 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 	if err != nil {
 		return nil, fmt.Errorf("resolving fullsend dir: %w", err)
 	}
-	if info, statErr := os.Stat(absDir); statErr != nil || !info.IsDir() {
-		return nil, fmt.Errorf("fullsend dir %s does not exist; run `fullsend github setup` first", fullsendDir)
+	if err := ValidateFullsendDir(fullsendDir); err != nil {
+		return nil, err
 	}
 
 	files, err := Render(opts)
@@ -51,12 +66,23 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 	// 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 {
-		_, statErr := os.Stat(filepath.Join(absDir, f.Path))
+		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)
@@ -86,20 +112,61 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 		return result, nil
 	}
 
+	// Files created by this call, for rollback. A failure part-way through
+	// would otherwise leave a partial agent behind: some files present, the
+	// harness perhaps missing, and nothing registered.
+	var created []string
+	rollback := func() {
+		for i := len(created) - 1; i >= 0; i-- {
+			_ = os.Remove(created[i])
+		}
+	}
+
 	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)
 		}
 		// Written directly rather than renamed in from the temp tree: a
 		// rename across filesystems fails, and the bytes are already here.
-		if err := os.WriteFile(path, f.Data, os.FileMode(f.Mode)); err != nil {
+		if err := writeFile(path, f.Data, os.FileMode(f.Mode)); err != nil {
+			rollback()
 			return nil, fmt.Errorf("writing %s: %w", f.Path, err)
 		}
+		created = append(created, path)
 	}
 	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.
 //
@@ -117,8 +184,20 @@ func validateInTempTree(absDir string, opts Options, files []File, result *Resul
 	for _, f := range files {
 		data := f.Data
 		if f.Shared {
-			if existing, readErr := os.ReadFile(filepath.Join(absDir, f.Path)); readErr == nil {
+			// 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)
diff --git a/internal/agentnew/render.go b/internal/agentnew/render.go
index cc1194449f..a10999e818 100644
--- a/internal/agentnew/render.go
+++ b/internal/agentnew/render.go
@@ -131,6 +131,12 @@ func buildHarness(opts Options, role Role) (*harness.Harness, error) {
 			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
diff --git a/internal/agentnew/spec.go b/internal/agentnew/spec.go
index a880b63bd9..7dcfc5dd3b 100644
--- a/internal/agentnew/spec.go
+++ b/internal/agentnew/spec.go
@@ -2,6 +2,7 @@ package agentnew
 
 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -50,15 +51,22 @@ func ParseSpec(data []byte) (*AgentSpec, error) {
 
 	var spec AgentSpec
 	if err := dec.Decode(&spec); err != nil {
-		if err == io.EOF {
+		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.
+	// 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
-	if err := dec.Decode(&extra); err == nil {
+	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 {
diff --git a/internal/cli/agent_new.go b/internal/cli/agent_new.go
index 5e662b6950..4004927890 100644
--- a/internal/cli/agent_new.go
+++ b/internal/cli/agent_new.go
@@ -5,11 +5,13 @@ import (
 	"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"
 )
 
@@ -197,6 +199,11 @@ func resolveAgentNewOptions(name string, f agentNewFlags) (opts agentnew.Options
 	}
 	opts.Image = image
 
+	if runtimeName != "" && !slices.Contains(config.ValidRuntimes(), runtimeName) {
+		return opts, "", "", fmt.Errorf("runtime %q is not valid (allowed: %s)",
+			runtimeName, strings.Join(config.ValidRuntimes(), ", "))
+	}
+
 	if validateErr := opts.Validate(); validateErr != nil {
 		return opts, "", "", validateErr
 	}
@@ -212,6 +219,20 @@ func runAgentNew(ctx context.Context, name string, f agentNewFlags, printer *ui.
 		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
@@ -301,3 +322,21 @@ func slashCommandFromTrigger(trigger string) string {
 	}
 	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
+}

From c0416542adb66349eb4410478ccae91ac8dc453e Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:48:00 -0400
Subject: [PATCH 08/17] test(#6966): cover the generator from its own packages

codecov/patch failed at 72.23%. The cause was mine: internal/harness's
CheckGenerated and the exported name validators were exercised only from
internal/agentnew's tests, and Codecov credits a file from tests in its
own package. My local measurement had used -coverpkg, which does credit
cross-package calls, so it reported 88% for a patch CI scored at 72%.

CheckGenerated now has direct tests in package harness: the happy path,
each missing-file branch including the provider and profile stat that
ValidateFilesExist deliberately skips, a lint diagnostic returned
non-fatally, a path escaping the fullsend directory, and a bare provider
name correctly not stat-ed. ValidAgentBasename and ValidSlug get table
tests; the rejected half of ValidAgentBasename is the security-relevant
one, since the agent name reaches shell interpolation.

The generator's write paths are covered in their own package too:
force-overwrite versus shared-asset preservation, collision refusal,
dry-run, the injected-failure rollback, both symlink refusals, and the
unreadable shared asset.

Measured without -coverpkg, as CI measures: 87.9%.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/generate_write_test.go      | 212 ++++++++++++++++++
 .../testdata/golden/validation-loop.txt       |   1 +
 internal/harness/checkgenerated_test.go       | 174 ++++++++++++++
 3 files changed, 387 insertions(+)
 create mode 100644 internal/agentnew/generate_write_test.go
 create mode 100644 internal/harness/checkgenerated_test.go

diff --git a/internal/agentnew/generate_write_test.go b/internal/agentnew/generate_write_test.go
new file mode 100644
index 0000000000..3587da07e6
--- /dev/null
+++ b/internal/agentnew/generate_write_test.go
@@ -0,0 +1,212 @@
+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")
+	}
+}
diff --git a/internal/agentnew/testdata/golden/validation-loop.txt b/internal/agentnew/testdata/golden/validation-loop.txt
index d35960b836..ef64236277 100644
--- a/internal/agentnew/testdata/golden/validation-loop.txt
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -84,6 +84,7 @@ 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
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)
+		}
+	}
+}

From 3dafa133194b92dbb3492a7cc391aa92174bd571 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:48:01 -0400
Subject: [PATCH 09/17] docs(#6966): record the decision in architecture.md and
 tidy the ADR

Adds the ADR 0102 entry to the agent-registration Decided list in
architecture.md, which the repo's convention expects for a new ADR, and
converts the ADR's Consequences section to bullets per the template.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 ...102-generate-custom-agents-from-the-cli.md | 47 +++++++++----------
 docs/architecture.md                          |  1 +
 2 files changed, 23 insertions(+), 25 deletions(-)

diff --git a/docs/ADRs/0102-generate-custom-agents-from-the-cli.md b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
index 44fa457e83..b2d4c7d11d 100644
--- a/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
+++ b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
@@ -103,28 +103,25 @@ ships scaffold content, with `--template-dir` as an override.
 
 ## 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.
-
-The cost is a second place where harness shape is encoded. That is 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.
-
-Two limits are deliberate and documented. `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`. And 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.
-
-The generator does not replace `fullsend lock` or `fullsend run` validation and
-is not wired into them: those interleave minting, runner-env validation and
-`${VAR}` expansion between the same steps in different orders, so sharing one
-helper would change their behaviour.
+- 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:**
 

From d64d6d844e6a63af5812be056fb1da677232e6b9 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 12:49:47 -0400
Subject: [PATCH 10/17] docs(#6966): order the BYO prerequisites ahead of step
 0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 0 opened with a runnable command while the prerequisites it needs —
the CLI on PATH, a scaffolded repository, inference and the GitHub Apps —
were two sections further down. It now points at them first, and the
overview leads with the numbered sequence rather than prose so step 0
reads as part of the flow instead of an aside.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 docs/guides/user/bring-your-own-agent.md | 32 ++++++++++++++++++------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/docs/guides/user/bring-your-own-agent.md b/docs/guides/user/bring-your-own-agent.md
index b2de57e7de..cc9577344f 100644
--- a/docs/guides/user/bring-your-own-agent.md
+++ b/docs/guides/user/bring-your-own-agent.md
@@ -14,11 +14,30 @@ 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` — harness, agent
+   definition, schema, post-script, trigger and registration. See below.
+1. **Fill in the agent definition** — the prompt is the only part the
+   generator cannot write for you.
+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 and how to change it.
+Read it when you need to go beyond the defaults, or when you are writing a
+harness by hand — the [four steps by hand](#the-four-steps-by-hand) below are
+the long form.
+
 ### Step 0: generate the skeleton
 
-Start here. [`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:
+First complete [Before you begin](#before-you-begin) — `agent new` needs the
+fullsend CLI on your PATH and a scaffolded repository, and running the agent
+afterwards needs the inference and GitHub App prerequisites listed there.
+
+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 \
@@ -39,10 +58,9 @@ fullsend agent new lint-docs --fullsend-dir .fullsend \
   ✓ Added agent "lint-docs"
 ```
 
-That covers steps 1, 2 and 4 below. Fill in the marked sections of
-`agents/lint-docs.md`, then go to [Testing locally](#testing-locally). The rest
-of this guide explains what was generated and how to change it — read it when
-you need to go beyond the defaults, or when you are writing a harness by hand.
+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
 

From 68ecfc7ca8890c378d35282db10c5e9b8b189389 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Thu, 3 Sep 2026 13:29:16 -0400
Subject: [PATCH 11/17] fix(#6966): keep a truncated comment inside the
 declared cap

The generated post-script cut the comment at MAX_COMMENT_CHARS and then
appended the truncation marker, so a truncated comment came out longer
than the 16384-character limit the generated result schema declares.

It now reserves the marker's length before cutting. Verified against the
generated script: a 17,000-character comment produces exactly 16384.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/render_test.go              | 23 +++++++++++++++++++
 internal/agentnew/templates/post.sh.tmpl      |  7 +++++-
 internal/agentnew/testdata/golden/coder.txt   |  7 +++++-
 .../testdata/golden/label-trigger.txt         |  7 +++++-
 .../agentnew/testdata/golden/prioritize.txt   |  7 +++++-
 internal/agentnew/testdata/golden/retro.txt   |  7 +++++-
 internal/agentnew/testdata/golden/review.txt  |  7 +++++-
 internal/agentnew/testdata/golden/triage.txt  |  7 +++++-
 .../testdata/golden/validation-loop.txt       |  7 +++++-
 9 files changed, 71 insertions(+), 8 deletions(-)

diff --git a/internal/agentnew/render_test.go b/internal/agentnew/render_test.go
index 14e6cdee03..095781803b 100644
--- a/internal/agentnew/render_test.go
+++ b/internal/agentnew/render_test.go
@@ -266,3 +266,26 @@ func hasPath(files []File, path string) bool {
 	}
 	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)
+		}
+	}
+}
diff --git a/internal/agentnew/templates/post.sh.tmpl b/internal/agentnew/templates/post.sh.tmpl
index 849a22d02f..41ed474a08 100644
--- a/internal/agentnew/templates/post.sh.tmpl
+++ b/internal/agentnew/templates/post.sh.tmpl
@@ -48,8 +48,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/coder.txt b/internal/agentnew/testdata/golden/coder.txt
index c3aa8dc9a9..01142a27c0 100644
--- a/internal/agentnew/testdata/golden/coder.txt
+++ b/internal/agentnew/testdata/golden/coder.txt
@@ -194,8 +194,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/label-trigger.txt b/internal/agentnew/testdata/golden/label-trigger.txt
index c4af76f187..5dcab0b266 100644
--- a/internal/agentnew/testdata/golden/label-trigger.txt
+++ b/internal/agentnew/testdata/golden/label-trigger.txt
@@ -193,8 +193,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/prioritize.txt b/internal/agentnew/testdata/golden/prioritize.txt
index 1159c49ffe..9de954471e 100644
--- a/internal/agentnew/testdata/golden/prioritize.txt
+++ b/internal/agentnew/testdata/golden/prioritize.txt
@@ -194,8 +194,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/retro.txt b/internal/agentnew/testdata/golden/retro.txt
index 25f2df6986..17e1c222cf 100644
--- a/internal/agentnew/testdata/golden/retro.txt
+++ b/internal/agentnew/testdata/golden/retro.txt
@@ -200,8 +200,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/review.txt b/internal/agentnew/testdata/golden/review.txt
index 25f91dc1d0..ead2080aed 100644
--- a/internal/agentnew/testdata/golden/review.txt
+++ b/internal/agentnew/testdata/golden/review.txt
@@ -194,8 +194,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/triage.txt b/internal/agentnew/testdata/golden/triage.txt
index cd35eafd15..593d9d2315 100644
--- a/internal/agentnew/testdata/golden/triage.txt
+++ b/internal/agentnew/testdata/golden/triage.txt
@@ -194,8 +194,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then
diff --git a/internal/agentnew/testdata/golden/validation-loop.txt b/internal/agentnew/testdata/golden/validation-loop.txt
index ef64236277..81b6e62a68 100644
--- a/internal/agentnew/testdata/golden/validation-loop.txt
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -199,8 +199,13 @@ 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
-  comment="${comment:0:${MAX_COMMENT_CHARS}}"$'\n\n_(truncated)_'
+  keep=$(( MAX_COMMENT_CHARS - ${#TRUNCATION_MARKER} ))
+  if (( keep < 0 )); then keep=0; fi
+  comment="${comment:0:${keep}}${TRUNCATION_MARKER}"
 fi
 
 if [[ "${status}" == "ok" ]]; then

From 70458b982eae34a0bb9d176f4d1dc11dd83dab88 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Fri, 4 Sep 2026 11:03:25 -0400
Subject: [PATCH 12/17] test(#6966): trim golden trees to two and drop
 duplicated CLI tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Seven golden trees for a five-role table was mostly repetition: the roles
differ only in table data — image, providers, profiles — which
TestRoleTableMatchesMint and its siblings already assert directly, and
more precisely than a byte diff does.

Kept triage as the default and validation-loop as the second. Not retro
or coder, despite those having the larger diffs: their differences are
data, while validation-loop is the only variant that exercises an actual
conditional in the generator — `if opts.ValidationLoop` in both
buildHarness and sharedAssets, which is also the only path that writes a
conditional shared asset.

Two branches the dropped trees did cover are now asserted directly
rather than incidentally: that each role's image and provider set reach
the generated harness, including that both image constants are reachable
so neither becomes dead configuration; and that each --on preset
survives marshalling into the harness. Those are checks a table test
cannot make, which is why they are worth keeping when the trees go.

On the CLI side, TestAgentNewForceNeverOverwritesSharedAssets and
TestAgentNewMissingDir duplicated package-level tests in internal/agentnew
outright, and the dry-run test's "wrote nothing" half did too; it now
asserts only what this layer can see, that the command reports its plan.
treeSnapshot lost its last caller and is removed.

Net 1,200 lines lighter. Patch coverage 87.4%, measured with plain
`go test -cover` per package as CI measures it.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/golden_test.go              |  19 +-
 internal/agentnew/render_test.go              |  69 +++++
 internal/agentnew/testdata/golden/coder.txt   | 236 -----------------
 .../testdata/golden/label-trigger.txt         | 235 -----------------
 .../agentnew/testdata/golden/prioritize.txt   | 236 -----------------
 internal/agentnew/testdata/golden/retro.txt   | 242 ------------------
 internal/agentnew/testdata/golden/review.txt  | 236 -----------------
 internal/cli/agent_new_test.go                |  87 +------
 8 files changed, 80 insertions(+), 1280 deletions(-)
 delete mode 100644 internal/agentnew/testdata/golden/coder.txt
 delete mode 100644 internal/agentnew/testdata/golden/label-trigger.txt
 delete mode 100644 internal/agentnew/testdata/golden/prioritize.txt
 delete mode 100644 internal/agentnew/testdata/golden/retro.txt
 delete mode 100644 internal/agentnew/testdata/golden/review.txt

diff --git a/internal/agentnew/golden_test.go b/internal/agentnew/golden_test.go
index 4b346fd892..7429855291 100644
--- a/internal/agentnew/golden_test.go
+++ b/internal/agentnew/golden_test.go
@@ -20,29 +20,22 @@ var update = flag.Bool("update", false, "rewrite the golden files in testdata/go
 //
 // 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") }},
-		{"coder", func() Options { return testOptions("lint-docs", "coder") }},
-		{"retro", func() Options { return testOptions("lint-docs", "retro") }},
-		{"review", func() Options { return testOptions("lint-docs", "review") }},
-		{"prioritize", func() Options { return testOptions("lint-docs", "prioritize") }},
 		{"validation-loop", func() Options {
 			o := testOptions("lint-docs", "triage")
 			o.ValidationLoop = true
 			return o
 		}},
-		{"label-trigger", func() Options {
-			o := testOptions("lint-docs", "triage")
-			trigger, err := ExpandTrigger("label:needs-docs", "lint-docs")
-			if err != nil {
-				panic(err)
-			}
-			o.Trigger = trigger
-			return o
-		}},
 	}
 
 	for _, tc := range cases {
diff --git a/internal/agentnew/render_test.go b/internal/agentnew/render_test.go
index 095781803b..42bcbf0c74 100644
--- a/internal/agentnew/render_test.go
+++ b/internal/agentnew/render_test.go
@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 
@@ -289,3 +290,71 @@ func TestPostScriptTruncatesWithinTheCap(t *testing.T) {
 		}
 	}
 }
+
+// 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/testdata/golden/coder.txt b/internal/agentnew/testdata/golden/coder.txt
deleted file mode 100644
index 01142a27c0..0000000000
--- a/internal/agentnew/testdata/golden/coder.txt
+++ /dev/null
@@ -1,236 +0,0 @@
-=== agents/lint-docs.md mode=644
----
-name: lint-docs
-description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
-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 fleet's current pin; pass
-# --image to override it.
-#
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of docs/guides/user/bring-your-own-agent.md.
-agent: agents/lint-docs.md
-description: Check docs changes for broken links
-role: coder
-slug: my-org-lint-docs
-image: ghcr.io/fullsend-ai/fullsend-code@sha256:ea2a31f38ee80e2a9a898a898a289fe432aa882fa5a4046c3236ab8e2627d7e7
-policy: policies/base.yaml
-providers:
-  - providers/vertex-ai.yaml
-  - providers/github.yaml
-openshell:
-  profiles:
-    - profiles/fullsend-vertex-ai.yaml
-    - profiles/fullsend-github.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"
-    && 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.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.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": "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,
-      "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's iteration directory, so the agent output is ./output/agent-result.json.
-#
-# 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
-#
-# 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
-
-: "${ISSUE_URL:?ISSUE_URL must be set}"
-: "${GH_TOKEN:?GH_TOKEN must be set}"
-
-RESULT_FILE="output/agent-result.json"
-MARKER="<!-- fullsend:lint-docs-agent -->"
-MAX_SUMMARY_CHARS=200
-MAX_COMMENT_CHARS=16384
-
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
-  exit 1
-fi
-if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
-[[ -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/label-trigger.txt b/internal/agentnew/testdata/golden/label-trigger.txt
deleted file mode 100644
index 5dcab0b266..0000000000
--- a/internal/agentnew/testdata/golden/label-trigger.txt
+++ /dev/null
@@ -1,235 +0,0 @@
-=== agents/lint-docs.md mode=644
----
-name: lint-docs
-description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
-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 fleet's current pin; pass
-# --image to override it.
-#
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of 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 == "label_changed"
-    && event.transition.label.name == "needs-docs"
-    && event.transition.label.action == "added"
-=== 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": "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,
-      "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's iteration directory, so the agent output is ./output/agent-result.json.
-#
-# 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
-#
-# 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
-
-: "${ISSUE_URL:?ISSUE_URL must be set}"
-: "${GH_TOKEN:?GH_TOKEN must be set}"
-
-RESULT_FILE="output/agent-result.json"
-MARKER="<!-- fullsend:lint-docs-agent -->"
-MAX_SUMMARY_CHARS=200
-MAX_COMMENT_CHARS=16384
-
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
-  exit 1
-fi
-if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
-[[ -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/prioritize.txt b/internal/agentnew/testdata/golden/prioritize.txt
deleted file mode 100644
index 9de954471e..0000000000
--- a/internal/agentnew/testdata/golden/prioritize.txt
+++ /dev/null
@@ -1,236 +0,0 @@
-=== agents/lint-docs.md mode=644
----
-name: lint-docs
-description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
-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 fleet's current pin; pass
-# --image to override it.
-#
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of docs/guides/user/bring-your-own-agent.md.
-agent: agents/lint-docs.md
-description: Check docs changes for broken links
-role: prioritize
-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"
-    && 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": "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,
-      "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's iteration directory, so the agent output is ./output/agent-result.json.
-#
-# 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
-#
-# 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
-
-: "${ISSUE_URL:?ISSUE_URL must be set}"
-: "${GH_TOKEN:?GH_TOKEN must be set}"
-
-RESULT_FILE="output/agent-result.json"
-MARKER="<!-- fullsend:lint-docs-agent -->"
-MAX_SUMMARY_CHARS=200
-MAX_COMMENT_CHARS=16384
-
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
-  exit 1
-fi
-if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
-[[ -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/retro.txt b/internal/agentnew/testdata/golden/retro.txt
deleted file mode 100644
index 17e1c222cf..0000000000
--- a/internal/agentnew/testdata/golden/retro.txt
+++ /dev/null
@@ -1,242 +0,0 @@
-=== agents/lint-docs.md mode=644
----
-name: lint-docs
-description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
-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 fleet's current pin; pass
-# --image to override it.
-#
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of docs/guides/user/bring-your-own-agent.md.
-agent: agents/lint-docs.md
-description: Check docs changes for broken links
-role: retro
-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
-  - providers/github-artifacts.yaml
-openshell:
-  profiles:
-    - profiles/fullsend-vertex-ai.yaml
-    - profiles/fullsend-github-ro.yaml
-    - profiles/fullsend-github-artifacts.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"
-    && 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-artifacts.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-artifacts.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": "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,
-      "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's iteration directory, so the agent output is ./output/agent-result.json.
-#
-# 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
-#
-# 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
-
-: "${ISSUE_URL:?ISSUE_URL must be set}"
-: "${GH_TOKEN:?GH_TOKEN must be set}"
-
-RESULT_FILE="output/agent-result.json"
-MARKER="<!-- fullsend:lint-docs-agent -->"
-MAX_SUMMARY_CHARS=200
-MAX_COMMENT_CHARS=16384
-
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
-  exit 1
-fi
-if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
-[[ -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/review.txt b/internal/agentnew/testdata/golden/review.txt
deleted file mode 100644
index ead2080aed..0000000000
--- a/internal/agentnew/testdata/golden/review.txt
+++ /dev/null
@@ -1,236 +0,0 @@
-=== agents/lint-docs.md mode=644
----
-name: lint-docs
-description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
-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 fleet's current pin; pass
-# --image to override it.
-#
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of docs/guides/user/bring-your-own-agent.md.
-agent: agents/lint-docs.md
-description: Check docs changes for broken links
-role: review
-slug: my-org-lint-docs
-image: ghcr.io/fullsend-ai/fullsend-code@sha256:ea2a31f38ee80e2a9a898a898a289fe432aa882fa5a4046c3236ab8e2627d7e7
-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"
-    && 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": "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,
-      "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's iteration directory, so the agent output is ./output/agent-result.json.
-#
-# 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
-#
-# 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
-
-: "${ISSUE_URL:?ISSUE_URL must be set}"
-: "${GH_TOKEN:?GH_TOKEN must be set}"
-
-RESULT_FILE="output/agent-result.json"
-MARKER="<!-- fullsend:lint-docs-agent -->"
-MAX_SUMMARY_CHARS=200
-MAX_COMMENT_CHARS=16384
-
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
-  exit 1
-fi
-if ! jq -e . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&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; }
-[[ -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/cli/agent_new_test.go b/internal/cli/agent_new_test.go
index e2cf3cd880..6cc70e3680 100644
--- a/internal/cli/agent_new_test.go
+++ b/internal/cli/agent_new_test.go
@@ -127,22 +127,19 @@ func TestAgentNewPostScriptIsExecutable(t *testing.T) {
 	}
 }
 
-func TestAgentNewDryRunWritesNothing(t *testing.T) {
+func TestAgentNewDryRunReportsWhatItWouldWrite(t *testing.T) {
 	dir := newFullsendDir(t)
-	before := treeSnapshot(t, dir)
-
 	f := defaultFlags(dir)
 	f.dryRun = true
 	out, err := runNew(t, "lint-docs", f)
 	if err != nil {
 		t.Fatalf("dry run failed: %v", err)
 	}
-	if !strings.Contains(out, "Nothing was written") {
-		t.Errorf("dry run should say nothing was written:\n%s", out)
-	}
-	// A dry run that reports nothing is useless: it must list what would be
-	// created and show the rendered bodies.
+	// 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 ---",
@@ -152,49 +149,6 @@ func TestAgentNewDryRunWritesNothing(t *testing.T) {
 			t.Errorf("dry run output should contain %q:\n%s", want, out)
 		}
 	}
-	if after := treeSnapshot(t, dir); after != before {
-		t.Errorf("dry run modified the directory\nbefore: %s\nafter:  %s", before, after)
-	}
-}
-
-// TestAgentNewRejectsCollisions and --force semantics: --force may overwrite
-// the files this agent owns, but never a shared scaffold asset.
-func TestAgentNewForceNeverOverwritesSharedAssets(t *testing.T) {
-	dir := newFullsendDir(t)
-	if _, err := runNew(t, "lint-docs", defaultFlags(dir)); err != nil {
-		t.Fatal(err)
-	}
-
-	sentinel := []byte("# hand-edited, must survive\n")
-	policyPath := filepath.Join(dir, "policies", "base.yaml")
-	if err := os.WriteFile(policyPath, 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)
-	}
-
-	// Without --force the collision is refused and nothing changes.
-	if _, err := runNew(t, "lint-docs", defaultFlags(dir)); err == nil {
-		t.Fatal("a second run without --force should fail")
-	}
-	if got, _ := os.ReadFile(harnessPath); string(got) != "clobbered\n" {
-		t.Error("a refused run must not modify anything")
-	}
-
-	f := defaultFlags(dir)
-	f.force = true
-	f.noRegister = true // already registered; --force must not paper over that
-	if _, err := runNew(t, "lint-docs", f); err != nil {
-		t.Fatalf("--force run failed: %v", err)
-	}
-	if got, _ := os.ReadFile(harnessPath); string(got) == "clobbered\n" {
-		t.Error("--force should have rewritten the harness")
-	}
-	if got, _ := os.ReadFile(policyPath); string(got) != string(sentinel) {
-		t.Errorf("--force must never overwrite a shared asset; policy is now %q", got)
-	}
 }
 
 func TestAgentNewNoRegister(t *testing.T) {
@@ -234,16 +188,6 @@ func TestAgentNewMissingConfig(t *testing.T) {
 	}
 }
 
-func TestAgentNewMissingDir(t *testing.T) {
-	_, err := runNew(t, "lint-docs", defaultFlags(filepath.Join(t.TempDir(), "nope")))
-	if err == nil {
-		t.Fatal("a missing fullsend dir should fail")
-	}
-	if !strings.Contains(err.Error(), "github setup") {
-		t.Errorf("error should point at github setup, got: %v", err)
-	}
-}
-
 func TestAgentNewWithRuntime(t *testing.T) {
 	dir := newFullsendDir(t)
 	f := defaultFlags(dir, "runtime")
@@ -384,24 +328,3 @@ func writeSpec(t *testing.T, body string) string {
 	}
 	return path
 }
-
-// treeSnapshot renders a directory's file list and contents for comparison.
-func treeSnapshot(t *testing.T, dir string) string {
-	t.Helper()
-	var b strings.Builder
-	err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
-		if err != nil || info.IsDir() {
-			return err
-		}
-		data, readErr := os.ReadFile(path)
-		if readErr != nil {
-			return readErr
-		}
-		b.WriteString(path + ":" + string(data) + "\n")
-		return nil
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	return b.String()
-}

From c3e2c306cdc8a4e7548dd987b66c02ca707a29eb Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Fri, 4 Sep 2026 11:10:20 -0400
Subject: [PATCH 13/17] docs(#6966): say what things are instead of naming them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A reader who has not used fullsend cannot follow the new pages. Three
reviewer questions on the sibling PR were all the same defect — a term
of art used as if it were plain English — so this fixes the class rather
than the instances.

`mint` was used four times in docs/cli/agent.md before anything said
what it is; it now gets a sentence saying agents hold no long-lived
credentials and ask a service for a short-lived token, which is what
makes the role table matter. `--slug` said "harness slug", which tells a
reader nothing they did not already have; it now says what the value is
for. "A per-repo install does not vendor them" is now "`fullsend github
setup` does not copy these into your repository". "You edit prose, not
plumbing" is now the actual claim: every file is written for you except
the instructions the agent follows. Triggers are described before the
presets table rather than assumed.

The Bring Your Own Agent step 0 listed harness, agent definition,
schema, post-script, trigger and registration — six terms, none defined
until later in the page, in the first thing a reader sees. It now says
what those files do.

The generated harness header called the image "the fleet's current pin".
Every generated agent carries that comment, so the jargon shipped to
users; it now explains that the digest pins the image so every run uses
the same one. Goldens regenerated.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 docs/cli/agent.md                             | 50 ++++++++++++-------
 docs/guides/user/bring-your-own-agent.md      | 22 ++++----
 internal/agentnew/render.go                   | 10 ++--
 internal/agentnew/testdata/golden/triage.txt  | 11 ++--
 .../testdata/golden/validation-loop.txt       | 11 ++--
 5 files changed, 63 insertions(+), 41 deletions(-)

diff --git a/docs/cli/agent.md b/docs/cli/agent.md
index 8cc262531f..68df305a7d 100644
--- a/docs/cli/agent.md
+++ b/docs/cli/agent.md
@@ -21,8 +21,9 @@ Manage agents in fullsend config. Generate a new agent, add, list, set (runtime,
 
 ## `agent new`
 
-Generate a complete, valid, runnable custom agent and register it. This is the
-fastest path from nothing to a working agent — you edit prose, not plumbing.
+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 \
@@ -89,8 +90,9 @@ it ships with marked sections to fill in. Everything else is complete.
 | `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`. A per-repo
-install does not vendor them, which is why `agent new` writes them.
+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
 
@@ -101,12 +103,12 @@ install does not vendor them, which is why `agent new` writes them.
 | `--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` | | Raw CEL trigger expression; mutually exclusive with `--on` |
+| `--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>` | Harness slug; `<owner>` comes from the `origin` remote |
-| `--image` | per-role pin | Sandbox image |
+| `--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` |
@@ -115,8 +117,14 @@ install does not vendor them, which is why `agent new` writes them.
 
 ### Roles
 
-`--role` is the **mint** role, not the agent's name. It selects which GitHub App
-identity and permissions the mint issues. The hosted mint serves these:
+`--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 |
 |----------|-------------|-----------|
@@ -127,15 +135,18 @@ identity and permissions the mint issues. The hosted mint serves these:
 | `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 at the
-first dispatch. To use a role the hosted mint does not serve, you need your own
-mint — see [Custom Agent Identity](../guides/user/custom-agent-identity.md).
+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
 
-Every generated agent gets a `trigger:`. An agent without one registers and
-validates but is **silently never dispatched**, so `agent new` refuses to write
-one. `--on` takes a preset:
+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 |
 |--------|-----------|
@@ -144,10 +155,11 @@ one. `--on` takes a preset:
 | `issue-opened` | A new issue is opened |
 | `pr-opened` | A non-fork pull request is opened, updated, or marked ready |
 
-The emitted expressions are exactly the ones in
-[CEL Triggers Reference](../guides/user/cel-triggers-reference.md#common-trigger-patterns);
-a test asserts the two stay identical. For anything else, pass `--trigger` with
-raw CEL — it is compiled before any file is written.
+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.
diff --git a/docs/guides/user/bring-your-own-agent.md b/docs/guides/user/bring-your-own-agent.md
index cc9577344f..2b957ac99a 100644
--- a/docs/guides/user/bring-your-own-agent.md
+++ b/docs/guides/user/bring-your-own-agent.md
@@ -17,23 +17,25 @@ This guide uses the [fullsend-ai/agents](https://github.com/fullsend-ai/agents)
 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` — harness, agent
-   definition, schema, post-script, trigger and registration. See below.
-1. **Fill in the agent definition** — the prompt is the only part the
-   generator cannot write for you.
+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 and how to change it.
-Read it when you need to go beyond the defaults, or when you are writing a
-harness by hand — the [four steps by hand](#the-four-steps-by-hand) below are
-the long form.
+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 scaffolded repository, and running the agent
-afterwards needs the inference and GitHub App prerequisites listed there.
+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
diff --git a/internal/agentnew/render.go b/internal/agentnew/render.go
index a10999e818..4e96c809aa 100644
--- a/internal/agentnew/render.go
+++ b/internal/agentnew/render.go
@@ -145,10 +145,12 @@ func buildHarness(opts Options, role Role) (*harness.Harness, error) {
 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. `image:` is the fleet's current pin; pass\n")
-	buf.WriteString("# --image to override it.\n#\n")
-	buf.WriteString("# This agent is GitHub-only. To add GitLab or Jira, see the overlays\n")
-	buf.WriteString("# section of docs/guides/user/bring-your-own-agent.md.\n")
+	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)
diff --git a/internal/agentnew/testdata/golden/triage.txt b/internal/agentnew/testdata/golden/triage.txt
index 593d9d2315..b3f4f6f2ae 100644
--- a/internal/agentnew/testdata/golden/triage.txt
+++ b/internal/agentnew/testdata/golden/triage.txt
@@ -53,11 +53,14 @@ 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 fleet's current pin; pass
-# --image to override it.
+# regenerates this file.
 #
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of docs/guides/user/bring-your-own-agent.md.
+# `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
diff --git a/internal/agentnew/testdata/golden/validation-loop.txt b/internal/agentnew/testdata/golden/validation-loop.txt
index 81b6e62a68..da42e51044 100644
--- a/internal/agentnew/testdata/golden/validation-loop.txt
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -53,11 +53,14 @@ 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 fleet's current pin; pass
-# --image to override it.
+# regenerates this file.
 #
-# This agent is GitHub-only. To add GitLab or Jira, see the overlays
-# section of docs/guides/user/bring-your-own-agent.md.
+# `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

From 0bbdf3d172d641f88998f253c61e4fa9212eb2a6 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Fri, 4 Sep 2026 11:36:36 -0400
Subject: [PATCH 14/17] fix(#6966): the generated post-script never found its
 own input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four reviewers ran over this branch; three independently found the same
thing, and it is the failure this whole command exists to prevent.

`postCmd.Dir = runDir` (internal/cli/run.go:1645) — the post-script runs
from the RUN directory, and the agent's output is one level down, in
iteration-<N>/output/. The template hardcoded `output/agent-result.json`,
a path that never exists, so every agent this command generated would
have failed its first real run. The fleet's own post-script gets this
right, and I had quoted its pattern in the research for this change.

The tests could not have caught it. They matched substrings, and
`output/` appears in both the right and the wrong form; the shell test
built `<tmp>/output/` and ran from there, encoding the same wrong
assumption, so seventeen green assertions were confirming the bug. The
post-script is now executed by a Go test against the real layout —
iteration directories, the validated-iteration override, and the
no-output case — which is the only shape of test that distinguishes
them.

Selecting the last iteration by glob order was also wrong past nine:
iteration-10 sorts before iteration-9. It is compared numerically now.

Also from this round, each verified before fixing:

- A symlinked `.fullsend` root wrote straight through it. The earlier
  symlink guard only walked segments BENEATH the root, and
  ValidateFullsendDir used Stat, which follows. Reproduced by writing
  three files outside the tree, then fixed with Lstat.
- Rollback deleted `--force`-overwritten files instead of restoring
  them, so an interrupted regeneration destroyed a working agent rather
  than leaving it alone. Originals are now kept and restored.
- os.WriteFile leaves an existing file's mode alone, so a re-generated
  post-script could keep a non-executable bit. Chmod is now explicit.
- `_lead` passed generation and then failed registration, leaving ten
  files behind: harness and config disagreed on the first character.
  config.ValidConfigAgentName is exported and both rules now apply.
- The command trigger fired on GitHub Discussions, which the docs say it
  does not. Verified against the normative fixture — entity.kind is
  "conversation" — and the doc's own pattern had the work_item guard I
  had dropped. Restored in the preset and the reference together.
- The body told every agent to run fullsend-check-output, which exits
  non-zero unless FULLSEND_OUTPUT_SCHEMA is set — and the runner only
  sets it when a validation loop is configured, which is off by default.
  The instruction is now rendered only when it will work, and the tools
  list matches what the body actually invokes rather than claiming to.
- ${#var} counts bytes under a C locale while the schema's maxLength
  counts code points, so a valid multibyte summary was rejected and
  truncation could slice mid-character. The script pins LC_ALL.
- `jq -e .` called a bare `null` document invalid JSON and let a
  top-level array reach a raw jq error; it now checks for an object.
  A model-supplied summary containing a newline broke the heading it is
  interpolated into, and is refused.
- ownerFromGitConfig kept its section state across headers, so an origin
  with no url could return a submodule's owner.
- The slug lookup was handed a relative path it could not walk above.
- ADR 0102 documented `--template-dir`, which does not exist.
- --runtime offered the dummy runtimes, which do no inference.
- `timeout_minutes: 0` was indistinguishable from omitted.
- A comment described an implementation the code does not use, two named
  a function that does not exist, and a dead branch returned the same
  value twice.

Patch coverage 87.8%, plain `go test -cover` per package.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 ...102-generate-custom-agents-from-the-cli.md |   2 +-
 docs/guides/user/cel-triggers-reference.md    |   5 +
 internal/agentnew/generate.go                 |  78 +++++++++--
 internal/agentnew/generate_write_test.go      |  92 ++++++++++++
 internal/agentnew/options.go                  |   9 +-
 internal/agentnew/options_test.go             |  14 +-
 internal/agentnew/postscript_exec_test.go     | 132 ++++++++++++++++++
 internal/agentnew/render.go                   |  49 +++++--
 internal/agentnew/render_test.go              |   7 +-
 internal/agentnew/spec.go                     |   6 +-
 internal/agentnew/spec_test.go                |  23 ++-
 .../agentnew/templates/agent-body.md.tmpl     |   3 -
 internal/agentnew/templates/post.sh.tmpl      |  56 +++++++-
 internal/agentnew/testdata/golden/triage.txt  |  64 +++++++--
 .../testdata/golden/validation-loop.txt       |  61 ++++++--
 internal/agentnew/trigger.go                  |   9 +-
 internal/agentnew/trigger_test.go             |   3 +
 internal/cli/agent_new.go                     |  33 ++++-
 internal/config/config.go                     |   8 ++
 19 files changed, 580 insertions(+), 74 deletions(-)
 create mode 100644 internal/agentnew/postscript_exec_test.go

diff --git a/docs/ADRs/0102-generate-custom-agents-from-the-cli.md b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
index b2d4c7d11d..be4b6d13ba 100644
--- a/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
+++ b/docs/ADRs/0102-generate-custom-agents-from-the-cli.md
@@ -99,7 +99,7 @@ convenience:
    `.fullsend` behind.
 
 Templates are embedded with `go:embed`, matching how the repository already
-ships scaffold content, with `--template-dir` as an override.
+ships scaffold content.
 
 ## Consequences
 
diff --git a/docs/guides/user/cel-triggers-reference.md b/docs/guides/user/cel-triggers-reference.md
index 8d94270799..68916bdc4e 100644
--- a/docs/guides/user/cel-triggers-reference.md
+++ b/docs/guides/user/cel-triggers-reference.md
@@ -102,6 +102,7 @@ trigger: >
 ```yaml
 trigger: >
   event.transition.kind == "comment_added"
+    && event.entity.kind == "work_item"
     && has(event.transition.comment.command)
     && event.transition.comment.command == "/my-command"
     && (!has(event.state.change_proposal) || !event.state.change_proposal.is_fork)
@@ -110,6 +111,10 @@ trigger: >
 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)
diff --git a/internal/agentnew/generate.go b/internal/agentnew/generate.go
index a4c81aab68..6890fecc57 100644
--- a/internal/agentnew/generate.go
+++ b/internal/agentnew/generate.go
@@ -19,10 +19,21 @@ func ValidateFullsendDir(fullsendDir string) error {
 	if err != nil {
 		return fmt.Errorf("resolving fullsend dir: %w", err)
 	}
-	info, err := os.Stat(absDir)
-	if err != nil || !info.IsDir() {
+	// 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
 }
 
@@ -112,13 +123,27 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 		return result, nil
 	}
 
-	// Files created by this call, for rollback. A failure part-way through
-	// would otherwise leave a partial agent behind: some files present, the
-	// harness perhaps missing, and nothing registered.
-	var created []string
+	// 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(created) - 1; i >= 0; i-- {
-			_ = os.Remove(created[i])
+		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)
 		}
 	}
 
@@ -128,13 +153,33 @@ func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, er
 			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)
 		}
-		created = append(created, path)
+		// 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
 }
@@ -237,7 +282,9 @@ func DeriveSlug(name string, owner string) string {
 type RepoOwner func(dir string) string
 
 // GitConfigOwner walks up from dir looking for a repository, and returns the
-// owner segment of its origin remote. Returns "" when there is no repository,
+// 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++ {
@@ -292,9 +339,6 @@ func readGitConfig(dir string) (string, bool) {
 
 	data, err := os.ReadFile(filepath.Join(gitDir, "config"))
 	if err != nil {
-		if !errors.Is(err, os.ErrNotExist) {
-			return "", false
-		}
 		return "", false
 	}
 	return string(data), true
@@ -304,8 +348,12 @@ func ownerFromGitConfig(cfg string) string {
 	inOrigin := false
 	for _, line := range strings.Split(cfg, "\n") {
 		trimmed := strings.TrimSpace(line)
-		if strings.HasPrefix(trimmed, "[remote ") {
-			inOrigin = strings.Contains(trimmed, `"origin"`)
+		// 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") {
diff --git a/internal/agentnew/generate_write_test.go b/internal/agentnew/generate_write_test.go
index 3587da07e6..154bd96740 100644
--- a/internal/agentnew/generate_write_test.go
+++ b/internal/agentnew/generate_write_test.go
@@ -210,3 +210,95 @@ func TestGenerateRejectsMissingDir(t *testing.T) {
 		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/options.go b/internal/agentnew/options.go
index 6d4f3d9c61..852190bb5c 100644
--- a/internal/agentnew/options.go
+++ b/internal/agentnew/options.go
@@ -40,8 +40,13 @@ type Options struct {
 // 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 {
-	if !harness.ValidAgentBasename(o.Name) {
-		return fmt.Errorf("agent name %q contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)", o.Name)
+	// 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
diff --git a/internal/agentnew/options_test.go b/internal/agentnew/options_test.go
index 8cfca00708..561443c78c 100644
--- a/internal/agentnew/options_test.go
+++ b/internal/agentnew/options_test.go
@@ -19,12 +19,14 @@ func TestOptionsValidateRejects(t *testing.T) {
 		mutate  func(*Options)
 		wantErr string
 	}{
-		{"empty name", func(o *Options) { o.Name = "" }, "invalid characters"},
-		{"name with semicolon", func(o *Options) { o.Name = "a;rm -rf /" }, "invalid characters"},
-		{"name with slash", func(o *Options) { o.Name = "../escape" }, "invalid characters"},
-		{"name with space", func(o *Options) { o.Name = "lint docs" }, "invalid characters"},
-		{"name with dollar", func(o *Options) { o.Name = "a$(id)" }, "invalid characters"},
-		{"name with backtick", func(o *Options) { o.Name = "a`id`" }, "invalid characters"},
+		{"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"},
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
index 4e96c809aa..68331a9ae4 100644
--- a/internal/agentnew/render.go
+++ b/internal/agentnew/render.go
@@ -23,7 +23,7 @@ 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.ValidAgentName by the time Render is called.
+// passed harness.ValidAgentBasename by the time Render is called.
 const (
 	agentNamePlaceholder = "__AGENT_NAME__"
 	dryRunPlaceholder    = "__DRY_RUN_VAR__"
@@ -186,9 +186,12 @@ func renderAgentDefinition(opts Options) ([]byte, error) {
 	if err := enc.Encode(agentFrontmatter{
 		Name:        opts.Name,
 		Description: opts.Description,
-		// Exactly what the generated body uses, no more: tools must stay
-		// consistent with the body (fullsend-ai/agents#992).
-		Tools: "Bash(gh,jq), Read, Grep, Glob",
+		// 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)
@@ -198,16 +201,31 @@ func renderAgentDefinition(opts Options) ([]byte, error) {
 	}
 	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) {
-	// Built as an ordered document via json.RawMessage rather than a map so
-	// the property order is stable and readable; MarshalIndent on a map
-	// would sort keys and scatter the required list.
+	// 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",
-		"$id":                  name + "-result.schema.json",
+		"$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",
@@ -236,9 +254,20 @@ func renderPostScript(name string) ([]byte, error) {
 	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.ValidAgentName, so the result is always a
+// 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
index 42bcbf0c74..387ff4c21d 100644
--- a/internal/agentnew/render_test.go
+++ b/internal/agentnew/render_test.go
@@ -174,9 +174,14 @@ func TestSchemaIsValidJSON(t *testing.T) {
 	if doc["additionalProperties"] != false {
 		t.Error("schema must set additionalProperties: false")
 	}
-	if doc["$id"] != "lint-docs-result.schema.json" {
+	// 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
diff --git a/internal/agentnew/spec.go b/internal/agentnew/spec.go
index 7dcfc5dd3b..09412f713c 100644
--- a/internal/agentnew/spec.go
+++ b/internal/agentnew/spec.go
@@ -28,7 +28,7 @@ type AgentSpec struct {
 	Runtime        string `yaml:"runtime,omitempty"`
 	Slug           string `yaml:"slug,omitempty"`
 	Image          string `yaml:"image,omitempty"`
-	TimeoutMinutes int    `yaml:"timeout_minutes,omitempty"`
+	TimeoutMinutes *int   `yaml:"timeout_minutes,omitempty"`
 	ValidationLoop bool   `yaml:"validation_loop,omitempty"`
 }
 
@@ -78,8 +78,8 @@ func ParseSpec(data []byte) (*AgentSpec, error) {
 	if spec.On != "" && spec.Trigger != "" {
 		return nil, fmt.Errorf("spec fields \"on\" and \"trigger\" are mutually exclusive")
 	}
-	if spec.TimeoutMinutes < 0 {
-		return nil, fmt.Errorf("spec field \"timeout_minutes\" must not be negative, got %d", spec.TimeoutMinutes)
+	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
index b91c56feaf..39599e662d 100644
--- a/internal/agentnew/spec_test.go
+++ b/internal/agentnew/spec_test.go
@@ -27,7 +27,7 @@ validation_loop: true
 	if spec.Name != "lint-docs" || spec.Role != "triage" {
 		t.Errorf("unexpected spec: %+v", spec)
 	}
-	if spec.TimeoutMinutes != 20 || !spec.ValidationLoop {
+	if spec.TimeoutMinutes == nil || *spec.TimeoutMinutes != 20 || !spec.ValidationLoop {
 		t.Errorf("unexpected spec: %+v", spec)
 	}
 	if spec.Description != "Check docs changes for broken links" {
@@ -80,3 +80,24 @@ func TestLoadSpecFile(t *testing.T) {
 		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
index e0a06b54dd..9aba5b1011 100644
--- a/internal/agentnew/templates/agent-body.md.tmpl
+++ b/internal/agentnew/templates/agent-body.md.tmpl
@@ -39,6 +39,3 @@ Write exactly one JSON object to `$FULLSEND_OUTPUT_DIR/agent-result.json`:
 
 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.
diff --git a/internal/agentnew/templates/post.sh.tmpl b/internal/agentnew/templates/post.sh.tmpl
index 41ed474a08..6f37c752ed 100644
--- a/internal/agentnew/templates/post.sh.tmpl
+++ b/internal/agentnew/templates/post.sh.tmpl
@@ -4,32 +4,72 @@
 # Generated by `fullsend agent new`. Safe to edit.
 #
 # Runs on the trusted runner after the sandbox exits. The working directory is
-# the run's iteration directory, so the agent output is ./output/agent-result.json.
+# 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}"
 
-RESULT_FILE="output/agent-result.json"
 MARKER="<!-- fullsend:__AGENT_NAME__-agent -->"
 MAX_SUMMARY_CHARS=200
 MAX_COMMENT_CHARS=16384
 
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-__AGENT_NAME__: ${RESULT_FILE} not found" >&2
+# 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 . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-__AGENT_NAME__: ${RESULT_FILE} is not valid JSON" >&2
+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
 
@@ -43,6 +83,10 @@ case "${status}" in
   *) 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
diff --git a/internal/agentnew/testdata/golden/triage.txt b/internal/agentnew/testdata/golden/triage.txt
index b3f4f6f2ae..31e5f78e05 100644
--- a/internal/agentnew/testdata/golden/triage.txt
+++ b/internal/agentnew/testdata/golden/triage.txt
@@ -2,7 +2,7 @@
 ---
 name: lint-docs
 description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
+tools: Bash(gh,jq), Read, Grep, Glob, Write
 model: opus
 ---
 
@@ -47,9 +47,6 @@ Write exactly one JSON object to `$FULLSEND_OUTPUT_DIR/agent-result.json`:
 
 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
@@ -99,6 +96,7 @@ env:
 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)
@@ -114,7 +112,7 @@ trigger: |
 <copied verbatim from the embedded scaffold>
 === schemas/lint-docs-result.schema.json mode=644
 {
-  "$id": "lint-docs-result.schema.json",
+  "$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.",
@@ -153,32 +151,72 @@ trigger: |
 # Generated by `fullsend agent new`. Safe to edit.
 #
 # Runs on the trusted runner after the sandbox exits. The working directory is
-# the run's iteration directory, so the agent output is ./output/agent-result.json.
+# 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}"
 
-RESULT_FILE="output/agent-result.json"
 MARKER="<!-- fullsend:lint-docs-agent -->"
 MAX_SUMMARY_CHARS=200
 MAX_COMMENT_CHARS=16384
 
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+# 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 . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&2
+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
 
@@ -192,6 +230,10 @@ case "${status}" in
   *) 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
diff --git a/internal/agentnew/testdata/golden/validation-loop.txt b/internal/agentnew/testdata/golden/validation-loop.txt
index da42e51044..76bcc5eabf 100644
--- a/internal/agentnew/testdata/golden/validation-loop.txt
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -2,7 +2,7 @@
 ---
 name: lint-docs
 description: Check docs changes for broken links
-tools: Bash(gh,jq), Read, Grep, Glob
+tools: Bash(gh,jq,fullsend-check-output), Read, Grep, Glob, Write
 model: opus
 ---
 
@@ -104,6 +104,7 @@ env:
 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)
@@ -119,7 +120,7 @@ trigger: |
 <copied verbatim from the embedded scaffold>
 === schemas/lint-docs-result.schema.json mode=644
 {
-  "$id": "lint-docs-result.schema.json",
+  "$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.",
@@ -158,32 +159,72 @@ trigger: |
 # Generated by `fullsend agent new`. Safe to edit.
 #
 # Runs on the trusted runner after the sandbox exits. The working directory is
-# the run's iteration directory, so the agent output is ./output/agent-result.json.
+# 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}"
 
-RESULT_FILE="output/agent-result.json"
 MARKER="<!-- fullsend:lint-docs-agent -->"
 MAX_SUMMARY_CHARS=200
 MAX_COMMENT_CHARS=16384
 
-if [[ ! -f "${RESULT_FILE}" ]]; then
-  echo "post-lint-docs: ${RESULT_FILE} not found" >&2
+# 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 . "${RESULT_FILE}" >/dev/null 2>&1; then
-  echo "post-lint-docs: ${RESULT_FILE} is not valid JSON" >&2
+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
 
@@ -197,6 +238,10 @@ case "${status}" in
   *) 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
diff --git a/internal/agentnew/trigger.go b/internal/agentnew/trigger.go
index 8fa73455e0..995b4fa596 100644
--- a/internal/agentnew/trigger.go
+++ b/internal/agentnew/trigger.go
@@ -14,8 +14,12 @@ import (
 // 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. The change_proposal clause
-	// uses has() rather than the reference doc's `!= null` because
+	// 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
@@ -59,6 +63,7 @@ func ExpandTrigger(on, name string) (string, error) {
 			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)
diff --git a/internal/agentnew/trigger_test.go b/internal/agentnew/trigger_test.go
index 27b2bb2d0b..f6077845a0 100644
--- a/internal/agentnew/trigger_test.go
+++ b/internal/agentnew/trigger_test.go
@@ -22,6 +22,7 @@ func TestTriggerPresetsArePinned(t *testing.T) {
 			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)
@@ -31,6 +32,7 @@ func TestTriggerPresetsArePinned(t *testing.T) {
 			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)
@@ -40,6 +42,7 @@ func TestTriggerPresetsArePinned(t *testing.T) {
 			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)
diff --git a/internal/cli/agent_new.go b/internal/cli/agent_new.go
index 4004927890..dc93a0fce4 100644
--- a/internal/cli/agent_new.go
+++ b/internal/cli/agent_new.go
@@ -130,8 +130,10 @@ func resolveAgentNewOptions(name string, f agentNewFlags) (opts agentnew.Options
 		if !f.changed("effort") && spec.Effort != "" {
 			opts.Effort = spec.Effort
 		}
-		if !f.changed("timeout-minutes") && spec.TimeoutMinutes != 0 {
-			opts.TimeoutMinutes = spec.TimeoutMinutes
+		// 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
@@ -181,7 +183,14 @@ func resolveAgentNewOptions(name string, f agentNewFlags) (opts agentnew.Options
 	opts.Description = description
 
 	if slug == "" {
-		owner := agentnew.GitConfigOwner(f.fullsendDir)
+		// 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, ""))
@@ -199,9 +208,9 @@ func resolveAgentNewOptions(name string, f agentNewFlags) (opts agentnew.Options
 	}
 	opts.Image = image
 
-	if runtimeName != "" && !slices.Contains(config.ValidRuntimes(), runtimeName) {
+	if runtimeName != "" && !slices.Contains(userFacingRuntimes(), runtimeName) {
 		return opts, "", "", fmt.Errorf("runtime %q is not valid (allowed: %s)",
-			runtimeName, strings.Join(config.ValidRuntimes(), ", "))
+			runtimeName, strings.Join(userFacingRuntimes(), ", "))
 	}
 
 	if validateErr := opts.Validate(); validateErr != nil {
@@ -340,3 +349,17 @@ func ensureAgentNameFree(fullsendDir, name string) error {
 	}
 	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/config/config.go b/internal/config/config.go
index fa51161139..e2a8815320 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -302,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"}
 }

From 2216d5434c66267e6f023577849b6f51b8af7999 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Fri, 4 Sep 2026 11:47:59 -0400
Subject: [PATCH 15/17] fix(#6966): generated schema forbids a multi-line
 summary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The generated prompt says the summary is one line and the generated
post-script refuses one that is not, but the generated schema only
constrained type and length. So a multi-line summary passed the
validation loop, no retry was triggered, and the run died in the
post-script with nothing posted — the three files that are supposed to
describe one contract described two.

Found reviewing the reference agent in fullsend-ai/agents#1167, which is
generated from this template.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 internal/agentnew/render.go                           | 11 +++++++++--
 internal/agentnew/testdata/golden/triage.txt          |  1 +
 internal/agentnew/testdata/golden/validation-loop.txt |  1 +
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/internal/agentnew/render.go b/internal/agentnew/render.go
index 68331a9ae4..03fb3bd4db 100644
--- a/internal/agentnew/render.go
+++ b/internal/agentnew/render.go
@@ -232,8 +232,15 @@ func renderSchema(name string) ([]byte, error) {
 		"additionalProperties": false,
 		"required":             []string{"status", "summary", "comment"},
 		"properties": map[string]any{
-			"status":  map[string]any{"type": "string", "enum": []string{"ok", "findings", "error"}},
-			"summary": map[string]any{"type": "string", "minLength": 1, "maxLength": 200},
+			"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},
 		},
 	}
diff --git a/internal/agentnew/testdata/golden/triage.txt b/internal/agentnew/testdata/golden/triage.txt
index 31e5f78e05..0abf504bd4 100644
--- a/internal/agentnew/testdata/golden/triage.txt
+++ b/internal/agentnew/testdata/golden/triage.txt
@@ -133,6 +133,7 @@ trigger: |
     "summary": {
       "maxLength": 200,
       "minLength": 1,
+      "pattern": "^[^\\r\\n]*$",
       "type": "string"
     }
   },
diff --git a/internal/agentnew/testdata/golden/validation-loop.txt b/internal/agentnew/testdata/golden/validation-loop.txt
index 76bcc5eabf..c17225dbc0 100644
--- a/internal/agentnew/testdata/golden/validation-loop.txt
+++ b/internal/agentnew/testdata/golden/validation-loop.txt
@@ -141,6 +141,7 @@ trigger: |
     "summary": {
       "maxLength": 200,
       "minLength": 1,
+      "pattern": "^[^\\r\\n]*$",
       "type": "string"
     }
   },

From 366e64a8c6305c355f41a147ef9fd5f924773917 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Fri, 4 Sep 2026 11:57:18 -0400
Subject: [PATCH 16/17] docs(#6966): show a real local run of a generated agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The result-path bug this branch fixed could only ever surface at run
time, and nothing in the PR had actually run a generated agent. So I ran
one: `--runtime dummy` exercises the real sandbox and the real
post-script with a scripted result in place of the model, which proves
the whole pipeline without spending inference or touching a forge.

It works — agent exit code 0, and the post-script finds
iteration-1/output/agent-result.json and renders the comment. That
output is now in the docs as what success looks like, because it is the
one command whose failure this branch exists to prevent.

Running it also found a gap in the command's own next-steps text. The
generated harness copies GOOGLE_APPLICATION_CREDENTIALS into the
sandbox, so a run stops at validation without it — even under the dummy
runtime, which does no inference — and the printed list did not mention
it. GH_TOKEN also has to be a real token, because a connectivity check
runs before the agent does; a placeholder fails with `Bad credentials`.
Both are now in the printed next steps and in the troubleshooting prose,
alongside the `--forge github` requirement.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 docs/cli/agent.md         | 62 ++++++++++++++++++++++++++++++++++-----
 internal/cli/agent_new.go |  8 +++--
 2 files changed, 60 insertions(+), 10 deletions(-)

diff --git a/docs/cli/agent.md b/docs/cli/agent.md
index 68df305a7d..1d70c8f579 100644
--- a/docs/cli/agent.md
+++ b/docs/cli/agent.md
@@ -274,14 +274,60 @@ to delete or keep.
 
 ### Running it
 
-Generation is step one. To actually run the agent, fill in the marked sections
-of `agents/<name>.md`, then follow
-[Running agents locally](../guides/user/running-agents-locally.md) — a real run
-needs GCP credentials, a sandbox image, and an `--env-file` supplying
-`GITHUB_ISSUE_URL`, `ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION` and
-`GH_TOKEN`. Set `POST_<NAME>_DRY_RUN=1` (for example
-`POST_LINT_DOCS_DRY_RUN=1`) so the generated post-script prints its comment
-instead of posting 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)
+```
+
+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
diff --git a/internal/cli/agent_new.go b/internal/cli/agent_new.go
index dc93a0fce4..332efb73e4 100644
--- a/internal/cli/agent_new.go
+++ b/internal/cli/agent_new.go
@@ -302,8 +302,12 @@ func printNextSteps(opts agentnew.Options, f agentNewFlags, printer *ui.Printer)
 	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, ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION\n")
-	printer.Raw("     and GH_TOKEN. See docs/guides/user/running-agents-locally.md.\n")
+	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))

From c73568c4d5f9ac170058c47c54b68b36270930b5 Mon Sep 17 00:00:00 2001
From: Wayne Sun <gsun@redhat.com>
Date: Fri, 4 Sep 2026 12:37:56 -0400
Subject: [PATCH 17/17] docs(#6966): add the claude-runtime run beside the
 dummy one

The dummy run proves the plumbing; it cannot prove that a real model can
follow the generated prompt with the tools and network profile the
harness grants. This run does: the reference agent against a real pull
request, exit 0, schema validation passed, post-script printing rather
than posting.

Getting there took isolating an unrelated failure, which is worth
recording because the symptom is misleading. A local `--runtime claude`
run died with `Could not refresh access token: policy_denied`, which
reads as a credentials problem. It was not: the composed sandbox policy
contained no Vertex network policy at all, because this host's
registered `vertex-ai` provider had drifted to zero credential keys. The
provider file and the profile were both byte-correct. Deleting the
provider and letting the run re-ensure it produced a healthy
registration and the run worked.

Assisted-by: Claude
Signed-off-by: Wayne Sun <gsun@redhat.com>
---
 docs/cli/agent.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/cli/agent.md b/docs/cli/agent.md
index 1d70c8f579..47c6049d88 100644
--- a/docs/cli/agent.md
+++ b/docs/cli/agent.md
@@ -313,6 +313,28 @@ 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