docs(#6099): document code/fix image and policy sync guidance

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

@@ -170,3 +170,12 @@ automatically by `fullsend run`.
 - Provider and profile definitions are currently resolved from local
   directories only. Portability for URL-referenced base harnesses
   requires harness-level declaration and URL-based resolution ([#2672](https://github.com/fullsend-ai/fullsend/issues/2672)).
+
+## Notes
+
+- The Context quote above reflects the `policies/fix.yaml` header when
+  this ADR was written. Upstream revised that comment in
+  [fullsend-ai/agents#766](https://github.com/fullsend-ai/agents/pull/766)
+  to describe overlapping sandbox needs with the code agent while
+  allowing intentional divergence; see also
+  [fullsend-ai/agents#532](https://github.com/fullsend-ai/agents/issues/532).

docs/agents/code.md

@@ -46,6 +46,58 @@ on issues (not PRs). The code agent is also triggered automatically when the
 See [Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
 [Configuring with Skills](../guides/user/customizing-with-skills.md).
 
+### Image and network policy synchronization
+
+By default, the code and [fix agent](fix.md) use the same upstream container
+image and overlapping sandbox policies (`policies/code.yaml` and
+`policies/fix.yaml` in [fullsend-ai/agents](https://github.com/fullsend-ai/agents)).
+They are separate harnesses, though — you can override each independently when
+their needs diverge. For example, you might keep Jira endpoints out of the code
+agent's policy while allowing them on the fix agent when reviewers ask you to
+verify something against a ticket during PR feedback.
+
+> **Warning:** If you customize image, `policy:`, or `providers:` on only one
+> agent by mistake, the other may fail with no obvious reason (for example, a
+> package manager or registry endpoint allowed in code but not fix).
+
+**Recommended configuration**
+
+If you want both agents to share one behavior set — one place to edit image,
+policy, providers, and runner scripts — put the same overrides in both harness
+files in your repo's `.fullsend/` directory:
+
+```yaml
+# .fullsend/harness/code.yaml  (register as source: harness/code.yaml in config.yaml)
+base: https://raw.githubusercontent.com/fullsend-ai/agents/<tag>/harness/code.yaml#sha256=…
+image: ghcr.io/your-org/your-fullsend-image@sha256:…
+policy: policies/base.yaml
+providers:
+  - vertex-ai
+  - github
+  - package-registries
+
+# .fullsend/harness/fix.yaml  (register as source: harness/fix.yaml in config.yaml)
+base: https://raw.githubusercontent.com/fullsend-ai/agents/<tag>/harness/fix.yaml#sha256=…
+image: ghcr.io/your-org/your-fullsend-image@sha256:…
+policy: policies/base.yaml   # same file — edit once, both agents use it
+providers:
+  - vertex-ai
+  - github
+  - package-registries
+```
+
+Keep the shared policy at `.fullsend/policies/base.yaml`. The policy file
+defines non-network sandbox restrictions only — filesystem access, landlock, and
+process identity. Network access is controlled through `providers:` profiles
+listed in the harness (see
+[ADR 0065](../ADRs/0065-provider-backed-policy-composition.md)) — when
+unifying configuration, keep the `providers:` list the same on both harnesses
+too. The same pattern applies to `pre_script` and `post_script` when you want a
+single place to maintain runner-side behavior.
+
+See [Customizing Agents](../guides/user/customizing-agents.md) for harness
+composition.
+
 ### Variables
 
 None.

docs/agents/fix.md

@@ -146,6 +146,58 @@ Remove the label or use `/fs-fix` to re-engage.
 See [Configuring with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
 [Configuring with Skills](../guides/user/customizing-with-skills.md).
 
+### Image and network policy synchronization
+
+By default, the fix and [code agent](code.md) use the same upstream container
+image and overlapping sandbox policies (`policies/code.yaml` and
+`policies/fix.yaml` in [fullsend-ai/agents](https://github.com/fullsend-ai/agents)).
+They are separate harnesses, though — you can override each independently when
+their needs diverge. For example, you might keep Jira endpoints out of the code
+agent's policy while allowing them on the fix agent when reviewers ask you to
+verify something against a ticket during PR feedback.
+
+> **Warning:** If you customize image, `policy:`, or `providers:` on only one
+> agent by mistake, the other may fail with no obvious reason (for example, a
+> package manager or registry endpoint allowed in code but not fix).
+
+**Recommended configuration**
+
+If you want both agents to share one behavior set — one place to edit image,
+policy, providers, and runner scripts — put the same overrides in both harness
+files in your repo's `.fullsend/` directory:
+
+```yaml
+# .fullsend/harness/code.yaml  (register as source: harness/code.yaml in config.yaml)
+base: https://raw.githubusercontent.com/fullsend-ai/agents/<tag>/harness/code.yaml#sha256=…
+image: ghcr.io/your-org/your-fullsend-image@sha256:…
+policy: policies/base.yaml
+providers:
+  - vertex-ai
+  - github
+  - package-registries
+
+# .fullsend/harness/fix.yaml  (register as source: harness/fix.yaml in config.yaml)
+base: https://raw.githubusercontent.com/fullsend-ai/agents/<tag>/harness/fix.yaml#sha256=…
+image: ghcr.io/your-org/your-fullsend-image@sha256:…
+policy: policies/base.yaml   # same file — edit once, both agents use it
+providers:
+  - vertex-ai
+  - github
+  - package-registries
+```
+
+Keep the shared policy at `.fullsend/policies/base.yaml`. The policy file
+defines non-network sandbox restrictions only — filesystem access, landlock, and
+process identity. Network access is controlled through `providers:` profiles
+listed in the harness (see
+[ADR 0065](../ADRs/0065-provider-backed-policy-composition.md)) — when
+unifying configuration, keep the `providers:` list the same on both harnesses
+too. The same pattern applies to `pre_script` and `post_script` when you want a
+single place to maintain runner-side behavior.
+
+See [Customizing Agents](../guides/user/customizing-agents.md) for harness
+composition.
+
 ### Variables
 
 None.