[sre-helmcode]

What

A new Secrets docs page (/docs/secrets, /es/docs/secrets), nested under Automations in the sidebar (frontmatter parent: automations, right after PR gatekeeper). Until now, member secrets were only explained inside /docs/automations, /docs/nan-cli and the BYOK sections.

The page covers:

• What a secret is and where it lives: encrypted with a key that belongs to the member's account alone, write-only, only a hint of the last 4 characters (…a1b2, values of 20+ characters), no hash.
• The two kinds: Secret (generic) and Provider key (provider_key: Anthropic, OpenAI, Google Gemini, OpenAI-compatible), with the base URL rules and the "never put a token in the base URL" warning.
• Create, replace, edit and delete from the portal (Settings > Secrets), the CLI (nan secrets ls/show/set/edit/rm, values only via --value-file / --value-stdin) and the API (/v1/secrets: routes and scopes, accepted and refused credentials, idempotency, rate limit, the error envelope, the secret object).
• Using secrets in automations: assignment by name with an env var and an exposure (agent vs actions), reserved names, the read/write GITHUB_TOKEN pattern, BYOK provider keys.
• Safety: masking as nan-run does it ([masked], encodings, 8+ character prefix fragments, and its limits), what an agent can do with an agent-exposed secret, why write scopes are dangerous (GitHub write tokens, secrets:write, automations:write, nan auth login never inside a workspace), rotation, replace and delete (409 secret_in_use, 409 secrets_too_large, secret_missing), Last changed from.
• Limits and a troubleshooting table of every error a member can see.

Automations, runs (BYOK), nan-cli, webhooks, PR gatekeeper and the intro keep short versions and link the new page. The API reference's Secrets tag and Secret schema now link /docs/secrets.

Also fixes runs: masked values show as [masked] (nan-run mask.Marker), not ***.

Infrastructure is not disclosed: the page says "encrypted with a key that belongs to your account alone" and never names the secret store (the docs tests forbid it).

Sources of truth

cloud-api origin/main 95414e4 (internal/secrets, handlers/account_secrets.go, runs/protocol/byok.go and v2.go, nanrun/mask), devops AGENT-AUTOMATIONS-PHASE2.md §3, AGENT-AUTOMATIONS-PHASE3-BYOK.md §2, AGENT-AUTOMATIONS-PHASE3-WRITE-API.md §2 and §4, cloud-ui fd930a3 (SecretsSection.tsx, SecretAssignments.tsx, lib/inference.ts, lib/updated-by.ts), nan-cli 0.1.33 (cmd/secrets.go).

Tests

• New src/tests/layouts/secretsDocs.test.ts: nesting and order, /api/docs rendering, every link and anchor resolves in the same locale (API anchors against the openapi tags), portal labels, facts pinned to the sources (limits, codes, providers, base URL rules, reserved env names, masking, routes and scopes cross-checked with openapi.json, the secret object keys), every error in the troubleshooting table, EN/ES parity, no em-dashes, no internals, nothing private, the other guides link it.
• Sidebar render test: Secrets is the second sub-item of Automations, active and trail states. Prev/next and breadcrumb tests updated for the second child.
• Existing tests updated for the new order slot (Webhooks moves from 22 to 23), the shortened automations sections, the [masked] fix and the API reference link.
• npm test: 2383 passed. npm run build: OK.

Deploy notes

None: docs only, no env vars, no VERSION file in this repo.

🤖 Generated with Claude Code