diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt
index 4c2f75a8655..5953894a9e9 100644
--- a/_vale/config/vocabularies/Docker/accept.txt
+++ b/_vale/config/vocabularies/Docker/accept.txt
@@ -295,6 +295,7 @@ Zsh
 [Ff]iletypes?
 [GgCc]oroutine
 [Hh]ealthcheck
+[Hh]eredoc
 [Hh]ostname
 [Ii]nfosec
 [Ii]nline
diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md
index 1027ea8f4b5..6399ac3881b 100644
--- a/content/manuals/ai/sandboxes/customize/kit-examples.md
+++ b/content/manuals/ai/sandboxes/customize/kit-examples.md
@@ -181,6 +181,33 @@ See the
 [FAQ](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for details.
 
+## Override agent settings
+
+Sandboxes seed settings files for some built-in agents during setup.
+For example, the sandbox writes `/home/agent/.claude/settings.json`
+for the `claude` agent. This happens after the kit's static files and
+`initFiles`, so a kit can't override those paths with either mechanism.
+Use `commands.startup` instead, which runs after the sandbox seeds its
+files:
+
+```yaml
+commands:
+  startup:
+    - command:
+        - sh
+        - -c
+        - |
+          mkdir -p /home/agent/.claude
+          cat > /home/agent/.claude/settings.json <<'JSON'
+          {"permissions": {"allow": ["Bash(echo:*)"]}}
+          JSON
+      user: "1000"
+      description: Write user-scope claude settings
+```
+
+Startup commands replay on every sandbox start, so the script must be
+idempotent. The heredoc pattern overwrites cleanly each time.
+
 ## Fork an existing agent
 
 Agent kits (`kind: agent`) define a full agent from scratch. The most
diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md
index 6fbce14af93..d8a1e1e1822 100644
--- a/content/manuals/ai/sandboxes/customize/kits.md
+++ b/content/manuals/ai/sandboxes/customize/kits.md
@@ -97,6 +97,17 @@ commands:
 
 See [`initFiles`](#initfiles) in the spec reference for all fields.
 
+Sandboxes seed settings files for some built-in agents during setup.
+For example, the sandbox writes `/home/agent/.claude/settings.json`
+for the `claude` agent. This happens after the kit's static files and
+`initFiles`, so kit-injected files at those paths get overwritten.
+Workspace files (such as `<workspace>/.claude/settings.local.json`)
+aren't affected, and you can ship them under `files/workspace/` as
+usual. To override a path the sandbox writes to, use a
+[`commands.startup`](#startup) script instead. See
+[Override agent settings](kit-examples.md#override-agent-settings) for
+an example.
+
 ### Set environment variables
 
 Environment variables set by the kit are available to the agent at