docs(runs): Pi + Gentle Shell agent; runs and automations only with installed agents

[sre-helmcode]

What

Docs for the third run agent, Pi + Gentle Shell (pi_gentle), and the rule that runs and automations only accept an agent the workspace has installed. Shipped in helmcode/nan-cloud-api#345 (0.8.258); UI in helmcode/nan-cloud-ui#158; CLI in helmcode/nan-cli#47 (0.1.29).

EN and ES:

• runs.mdx: new Pick the agent / Elige el agente section right after the prerequisites: a table with the portal label, the --agent/agent value and what the workspace needs (Pi; Pi and gentle-shell; Hermes chosen or installed and switched on). It explains the installed-only rule: the portal lists only the workspace's agents, the CLI and the API get 409 agent_not_installed (param: "agent", CLI exit 4), and an automation keeps a removed agent but its runs are refused. It also points scripts at run_agents. The intro, the prerequisites, the Agent form row, the --agent pi|pi_gentle|hermes flag row (with the 0.1.29 requirement), a pi_gentle CLI example, and the API section (accepted agent values plus the exact 409 envelope) are updated.
• automations.mdx: the prerequisite and the Agent row (list filtered by workspace, the switch notice, (not installed), agent_not_installed).
• pr-gatekeeper.mdx: the prerequisite now reads "The agent installed in that workspace: Pi, Pi + Gentle Shell or Hermes", with a link to Pick the agent.
• workspaces.mdx: the run sentence names the three agents, and the gentle-shell paragraph links to Pick the agent.
• src/data/openapi.json: pi_gentle in every agent enum (CreateRunRequest, Run, RunEventDataStarted, Automation) with label descriptions. Adds Workspace.run_agents (enum, display order, the requirements) and puts it in both workspace examples. Adds an agent_not_installed example with param: "agent" to the 409 of POST /v1/runs and POST /v1/automations/{id}/runs. The Runs tag description is updated too.

Shapes come from cloud-api origin/main: runs.AgentName/AgentNotInstalled, software.RunAgentIDs/runAgentRequires, and workspace.Workspace.RunAgents.

Tests

• src/lib/openapiRuns.test.ts: the enum assertion is updated, plus a new block. It checks every agent enum is exactly pi, pi_gentle, hermes, that no schema still lists only pi/hermes, the label descriptions, run_agents placement, enum and examples, and the two 409 examples (exact envelope, validated against Error). The validator must accept all three agents and reject pi-gentle, gentle_shell and similar values.
• New src/tests/layouts/runAgentsDocs.test.ts covers EN and ES. It checks the agent table rows and order, where the section sits, the installed-only rule (409, agent, exit 4, run_agents), the form row, the flag row, 0.1.29 and the pi_gentle example. The 409 JSON in the guide must equal the reference example. It also checks the automations, PR gatekeeper and workspaces lines and that EN and ES match.
• Known-bad check: with the old content and spec, the new tests fail (33 failures).
• npm test: 81 files, 2084 tests pass. npm run build passes.

Deploy notes

No VERSION file (Cloudflare deploy on merge). --agent pi_gentle needs nan-cli 0.1.29, so merge after helmcode/nan-cli#47 is released. The portal labels match helmcode/nan-cloud-ui#158, so merge after that one too.

🤖 Generated with Claude Code