[docs-scanner] Contradictory information about startup commands gating agent entrypoint

[docker-agent]

Files:

• content/manuals/ai/sandboxes/customize/kit-reference.md
• content/manuals/ai/sandboxes/customize/kit-examples.md

Issue

Two files in the same directory give contradictory information about whether setup.startup commands gate the agent's entrypoint.

In kit-reference.md, the startup section states:

Startup commands are non-interactive. They run before the agent attaches, with no terminal connected, so they can't prompt the user (for example, an interactive aws login will hang or fail). They also don't gate the agent's entrypoint: the agent launches once startup commands have been dispatched, regardless of background. A value of false waits within the startup dispatcher before it runs the next command; it doesn't delay the agent entrypoint.

But in kit-examples.md, the "Customize agent settings" section warns:

Agent settings mechanisms differ. If an agent doesn't support an additional config file, launch option, or environment variable for the setting, kits can't replace the sandbox-managed user settings before the agent launches. setup.startup doesn't gate the agent entrypoint, so don't use it for settings the agent must read during initialization.

The first quote explains the behavior in detail. The second quote repeats the same fact but in a warning context that suggests this is a limitation readers need to work around. However, both are saying the same thing - startup commands don't block the agent from starting.

The confusion is compounded because the background: false description in kit-reference.md says:

Block later startup commands until this command finishes. Set to true to let later commands run without waiting.

This makes it sound like background: false creates blocking behavior, but then the text immediately clarifies that this blocking only affects other startup commands, not the agent entrypoint. A reader could easily misunderstand this sequence.

Why this matters

A reader trying to understand when their startup commands will complete relative to agent launch will get conflicting signals. The detailed explanation in kit-reference.md is correct, but the way background: false is described ("Block later startup commands") followed by the clarification creates unnecessary confusion. The warning in kit-examples.md repeats the same fact without adding new information, making readers wonder if they missed something.

Suggested fix

1. In kit-reference.md, rewrite the background field description to lead with what it does, not what it blocks:

   Current:

   Block later startup commands until this command finishes. Set to true to let later commands run without waiting.

   Suggested:

   Run this command in the background. When false (default), the startup dispatcher waits for this command to finish before running the next startup command. When true, the dispatcher continues immediately. Neither setting delays the agent entrypoint.

2. In kit-examples.md, remove the redundant warning sentence since the limitation is already explained in the reference. Keep only the actionable guidance:

   Current:

   Agent settings mechanisms differ. If an agent doesn't support an additional config file, launch option, or environment variable for the setting, kits can't replace the sandbox-managed user settings before the agent launches. setup.startup doesn't gate the agent entrypoint, so don't use it for settings the agent must read during initialization.

   Suggested:

   Agent settings mechanisms differ. If an agent doesn't support an additional config file, launch option, or environment variable for the setting, kits can't replace the sandbox-managed user settings before the agent launches.

---

Found by nightly documentation quality scanner