docs: dedicated Secrets page, nested under Automations

src/content/docs-es/apps.md

@@ -1,7 +1,7 @@
 ---
 title: Apps
 description: Despliega tus apps desde GitHub a NaN Cloud en minutos.
-order: 24
+order: 25
 group: Guías
 ---
 

src/content/docs-es/automations.mdx

@@ -86,25 +86,13 @@ Cada automatización tiene cuatro pestañas: **Settings**, **Triggers**, **Runs*
 
 ## Secretos
 
-Los secretos son los tokens y claves que usan tus automatizaciones: un token de GitHub, una API key de algún servicio tuyo. Los guardas en tus ajustes y los asignas a las automatizaciones que los necesitan.
+Los secretos son los tokens y claves que usan tus automatizaciones: un token de GitHub, una API key de algún servicio tuyo. Los guardas en tus ajustes y los asignas a las automatizaciones que los necesitan. Todo sobre ellos (los dos tipos, el portal, la CLI y la API, el enmascarado, la rotación y los errores que puedes ver) está en [Secretos](/es/docs/secrets).
 
 ### Añade un secreto
 
-Abre tus ajustes en el portal, **Secrets**, debajo de **Tokens**, y pulsa **Add secret**. En **Kind**, **Secret** es para los tokens y claves que reciben tus automatizaciones; **Provider key** es para tu propia clave con un proveedor de IA, que se usa como inferencia de runs y automatizaciones: consulta [Usa tu propia clave de proveedor](#usa-tu-propia-clave-de-proveedor-byok).
+Abre tus ajustes en el portal, **Secrets**, debajo de **Tokens**, y pulsa **Add secret**. Dale un **Name**, normalmente el nombre de la variable que ven tus automatizaciones (por ejemplo `GITHUB_TOKEN`), y pega el **Value**, hasta 16 KiB. En **Kind**, **Secret** es para los tokens que reciben tus automatizaciones, y **Provider key** para tu propia clave con un proveedor de IA: consulta [Usa tu propia clave de proveedor](#usa-tu-propia-clave-de-proveedor-byok).
 
-- **Name**: el nombre de la variable que ven tus automatizaciones, en mayúsculas, dígitos y `_`, empezando por una letra. Por ejemplo `GITHUB_TOKEN`. Hasta 64 caracteres.
-- **Value**: se guarda tal cual lo pegas, hasta 16 KiB. Los saltos de línea dentro del valor están bien (una clave PEM, por ejemplo), pero no al principio ni al final.
-- **Description**, opcional.
-
-Los secretos son de **solo escritura**: una vez guardados, nadie puede volver a leer el valor, ni siquiera tú. La lista muestra el nombre, los 4 últimos caracteres cuando el valor es lo bastante largo, la descripción y qué automatizaciones usan cada uno. Puedes:
-
-- **Replace value**: el valor nuevo lo usan todos los runs que arranquen a partir de ese momento, incluidos los que ya están en cola. El anterior no se puede recuperar.
-- Cambiar su **Description**.
-- **Delete**. El borrado se rechaza mientras una automatización lo use, como uno de sus secretos o como su provider key: quítalo antes de esas automatizaciones.
-
-Puedes guardar hasta 100 secretos. Mejor tokens de vida corta, limitados a lo que necesita la automatización.
-
-Cada secreto muestra desde dónde se cambió por última vez (**Last changed from**: **Browser**, **CLI** o **API token**), así que un cambio que no hiciste tú salta a la vista. Desde la CLI: `nan secrets set`, `nan secrets edit` y `nan secrets rm`, en [Gestiónalas desde la CLI o la API](#gestiónalas-desde-la-cli-o-la-api).
+Los secretos son de **solo escritura**: una vez guardados, nadie puede volver a leer el valor, ni siquiera tú. Puedes usar **Replace value**, cambiar la descripción o borrar uno que no use ninguna automatización. Puedes guardar hasta 100 secretos, y cada uno muestra desde dónde se cambió por última vez (**Last changed from**). Consulta [Gestiona los secretos en el portal](/es/docs/secrets#gestiona-los-secretos-en-el-portal).
 
 ### Asigna secretos a una automatización
 
@@ -123,7 +111,7 @@ El mismo nombre de variable puede aparecer una vez por opción. La configuració
 
 Una automatización admite hasta 20 secretos, y todos los secretos que recibe un run pueden sumar como mucho 48 KiB. Los secretos solo llegan a los runs de las automatizaciones a las que los asignas: un run que lanzas con `nan run` o desde la pestaña **Runs** de un workspace no recibe ninguno.
 
-En los logs, resultados y propuestas de los runs, todos los valores de los secretos aparecen enmascarados. Un run solo arranca si todos los secretos que necesita están disponibles; si no, falla con `secrets_unavailable` y nada se ejecuta sin ellos.
+En los logs, resultados y propuestas de los runs, todos los valores de los secretos aparecen enmascarados: consulta [Enmascarado en logs y eventos](/es/docs/secrets#enmascarado-en-logs-y-eventos). Un run solo arranca si todos los secretos que necesita están disponibles; si no, falla con `secrets_unavailable` y nada se ejecuta sin ellos.
 
 <Callout title="Qué puede hacer el agente con un secreto" variant="warning">
 Un agente que recibe un secreto puede leerlo, y podría mandarlo a algún sitio si algo le convence de hacerlo. El enmascarado protege nuestros logs, no la red del agente. Dale al agente solo tokens de lectura, deja los tokens de escritura como **Actions only** y limita cada token al repositorio para el que es.
@@ -402,13 +390,7 @@ nan secrets edit GITHUB_WRITE_TOKEN --description "expires in December"
 nan secrets rm GITHUB_READ_TOKEN
 ```
 
-- **El valor nunca va en la línea de comandos**, donde se quedaría en el historial de tu shell y otros programas podrían verlo: `--value-file PATH` lo lee de un archivo y `--value-stdin` de una tubería. `--value-stdin` se niega a leer de la terminal, así que nunca se teclea un valor a la vista.
-- Se quita un salto de línea al final (los archivos suelen acabar en uno). Aparte de eso, el valor no puede empezar ni terminar con un salto de línea.
-- `set` crea el secreto o **reemplaza el valor** del que tenga ese nombre. El tipo, el proveedor y el nombre quedan fijos al crearlo.
-- `edit` cambia la descripción, o la URL base de una clave de proveedor compatible con OpenAI.
-- `rm` pregunta antes de borrar (si respondes que no, sale con código 1); `--yes` se salta la pregunta en scripts. Se rechaza mientras una automatización use el secreto, y la CLI te dice cuáles.
-- Con un token, nombrar un secreto que ya existe necesita `secrets:read` para buscar el nombre; un token solo con `secrets:write` puede crear un secreto nuevo.
-- `--json` imprime los metadatos en JSON.
+El valor se lee de un archivo (`--value-file PATH`) o de una tubería (`--value-stdin`), nunca de la línea de comandos, y nada lo vuelve a imprimir. `set` crea un secreto o reemplaza su valor, `edit` cambia su descripción o su URL base, y `rm` lo borra cuando ninguna automatización lo usa. Todas las opciones, las credenciales que acepta cada comando y la API están en [Gestiona los secretos desde la CLI](/es/docs/secrets#gestiona-los-secretos-desde-la-cli).
 
 ### Automatizaciones desde la CLI
 
@@ -478,7 +460,7 @@ jq -n --rawfile v token.txt '{name: "GITHUB_WRITE_TOKEN", value: ($v | rtrimstr(
 - Crear un trigger devuelve la URL del webhook y el secreto de firma una sola vez, con `Cache-Control: no-store`; rotarlo, igual. Crear un trigger no es idempotente: si se pierde la respuesta, lista los triggers y rota o borra el que no llegaste a ver.
 - Demasiados cambios reciben `429 rate_limited`: consulta [Límites](#límites).
 
-Todas las rutas, cuerpos y errores están en [Referencia de la API → Secrets](/es/docs/api#tag/secrets) y [Referencia de la API → Automations](/es/docs/api#tag/automations).
+Las rutas de secretos se explican en [Gestiona los secretos desde la API](/es/docs/secrets#gestiona-los-secretos-desde-la-api). Todas las rutas, cuerpos y errores están en [Referencia de la API → Secrets](/es/docs/api#tag/secrets) y [Referencia de la API → Automations](/es/docs/api#tag/automations).
 
 ## Tokens para automatizaciones
 

src/content/docs-es/examples.md

@@ -1,7 +1,7 @@
 ---
 title: Ejemplos
 description: Fragmentos de código para conectarte a la API de NaN con Python, Node.js, curl y más.
-order: 23
+order: 24
 group: Guías
 ---
 

src/content/docs-es/intro.md

@@ -35,5 +35,6 @@ Los límites van por API key — un tope de peticiones por minuto y un máximo d
 - [Automatizaciones](/es/docs/automations): guarda una tarea de agente y lánzala desde un webhook, una programación o tus scripts, con las aprobaciones que elijas.
 - [Webhooks y programaciones](/es/docs/webhooks): conecta GitHub, Stripe o tus propios sistemas, o ejecútala con una programación.
 - [PR gatekeeper](/es/docs/pr-gatekeeper): una guía paso a paso, con capturas, de una automatización que comprueba cada pull request y deja un comentario con el veredicto.
+- [Secretos](/es/docs/secrets): guarda los tokens y claves que usan tus automatizaciones, y tus propias claves de proveedor, cifrados y de solo escritura, desde el portal, la CLI o la API.
 - [Ejemplos](/es/docs/examples): fragmentos en Python, Node.js y curl.
 - Soporte: reporta incidencias en `#support` de Discord.

src/content/docs-es/nan-cli.mdx

@@ -196,7 +196,7 @@ nan automations disable "PR review"
 nan automations triggers add "PR review" -f webhook.yaml  # imprime la URL y el secreto una vez
 ```
 
-El valor de un secreto se lee de un archivo o de una tubería, nunca de la línea de comandos, y nada lo vuelve a imprimir. Mientras tu cuenta no tenga la API de escritura, estos comandos te lo dicen y te mandan al portal. Aprobar propuestas siempre se hace en el portal, con sesión iniciada en tu navegador.
+El valor de un secreto se lee de un archivo o de una tubería, nunca de la línea de comandos, y nada lo vuelve a imprimir. Todas las opciones de `nan secrets`, cómo rotar un secreto y los errores que puedes ver están en [Secretos](/es/docs/secrets#gestiona-los-secretos-desde-la-cli). Mientras tu cuenta no tenga la API de escritura, estos comandos te lo dicen y te mandan al portal. Aprobar propuestas siempre se hace en el portal, con sesión iniciada en tu navegador.
 
 Estos comandos usan primero tu sesión de `nan auth login` (gana a `NAN_TOKEN`; `--token-file` gana a las dos), o un token de plataforma con los scopes que necesitan: `secrets:read` y `secrets:write` para secretos, `automations:write` (y `automations:read` para usar nombres) para automatizaciones; consulta [Tokens para automatizaciones](/es/docs/automations#tokens-para-automatizaciones). Inicia sesión en tu propia máquina, nunca dentro de un workspace: los agentes de ahí podrían leer la sesión y cambiar tus secretos. Todos los comandos, los archivos YAML y los avisos están en [Gestiónalas desde la CLI o la API](/es/docs/automations#gestiónalas-desde-la-cli-o-la-api).
 

src/content/docs-es/pr-gatekeeper.mdx

@@ -106,7 +106,7 @@ La automatización tiene que hacer dos cosas en GitHub: clonar el repositorio, s
 
 Un repositorio público no necesita el token de lectura.
 
-Guarda los dos en el portal, con esos nombres: tus ajustes, **Secrets**, **Add secret**. Un secreto es de solo escritura: una vez guardado, nadie puede volver a leerlo, ni siquiera tú. Consulta [Añade un secreto](/es/docs/automations#añade-un-secreto).
+Guarda los dos en el portal, con esos nombres: tus ajustes, **Secrets**, **Add secret**. Un secreto es de solo escritura: una vez guardado, nadie puede volver a leerlo, ni siquiera tú. Consulta [Secretos](/es/docs/secrets) para ver cómo se guardan, se enmascaran y se rotan.
 
 <Callout title="Por qué dos tokens" variant="warning">
 El agente ejecuta el código de la pull request, tests incluidos, y puede leer todos los secretos que recibe. Un test podría intentar mandar ese token a otra parte. Mantén el token que puede escribir fuera del alcance del agente: dale el de solo lectura y deja que NaN publique el comentario con el otro. Nuestra configuración de las capturas usa un único token para las dos filas; dos tokens es la opción más segura.

src/content/docs-es/runs.mdx

@@ -149,9 +149,9 @@ Cada run trabaja en su propio proceso dentro del workspace, con su parte de CPU
 
 Los runs con la inferencia de NaN usan la clave de inferencia del workspace, la misma que usan sus agentes cuando trabajas con ellos a mano. Sus peticiones cuentan para el uso de tu plan como cualquier otra. Los runs con [tu propia clave de proveedor](#usa-tu-propia-clave-de-proveedor-byok) usan tu clave en su lugar, y nunca reciben la del workspace.
 
-Los secretos del archivo de entorno de tu workspace, como esa clave de inferencia o un token de bot de Telegram, aparecen como `***` en los logs y resultados de los runs, así que un log no los filtra.
+Los secretos del archivo de entorno de tu workspace, como esa clave de inferencia o un token de bot de Telegram, aparecen como `[masked]` en los logs y resultados de los runs, así que un log no los filtra. Consulta [Enmascarado en logs y eventos](/es/docs/secrets#enmascarado-en-logs-y-eventos).
 
-Los secretos que guardas en tus ajustes no se les dan a estos runs: solo llegan a los runs de las [automatizaciones](/es/docs/automations#secretos) a las que los asignas.
+Los secretos que guardas en tus ajustes no se les dan a estos runs: solo llegan a los runs de las [automatizaciones](/es/docs/automations#secretos) a las que los asignas. Consulta [Secretos](/es/docs/secrets).
 
 ## Usa tu propia clave de proveedor (BYOK)
 
@@ -179,24 +179,15 @@ Abre tus ajustes en el portal, **Secrets**, y pulsa **Add secret**. Rellena (el
 - **Name**: cómo la nombran los runs y las automatizaciones, por ejemplo `ANTHROPIC_KEY`. Mayúsculas, dígitos y `_`, empezando por una letra.
 - **Kind**: **Provider key**.
 - **Provider**: **Anthropic**, **OpenAI**, **Google Gemini** u **OpenAI-compatible**. No se puede cambiar después: para cambiar de proveedor, añade otra clave.
-- **Base URL**, solo para **OpenAI-compatible**: la raíz del endpoint, que suele acabar en `/v1`, por ejemplo `https://api.together.xyz/v1`. Mira las reglas más abajo.
+- **Base URL**, solo para **OpenAI-compatible**: la raíz del endpoint, que suele acabar en `/v1`, por ejemplo `https://api.together.xyz/v1`. Mira las [reglas de la URL base](/es/docs/secrets#reglas-de-la-url-base).
 - **Value**: la clave, una sola línea sin espacios, de 8 a 4096 caracteres.
 - **Description (optional)**.
 
 Como todo secreto, una provider key es de **solo escritura**: nadie puede volver a leerla, ni siquiera tú. La lista la muestra como **Provider key · Anthropic** (o su proveedor) normalmente con sus 4 últimos caracteres y, en una clave OpenAI-compatible, su URL base, que puedes cambiar con **Base URL**. **Replace value** cambia la clave para todos los runs que arranquen a partir de ese momento. `nan secrets ls` la muestra con **KIND** `provider_key`, su **PROVIDER** y su **BASE URL**.
 
-Si tu cuenta tiene la API de escritura, también puedes guardarla desde la CLI, leyendo la clave de un archivo o de una tubería: `nan secrets set ANTHROPIC_KEY --value-file key.txt --kind provider_key --provider anthropic`. Consulta [Secretos desde la CLI](/es/docs/automations#secretos-desde-la-cli).
+Si tu cuenta tiene la API de escritura, también puedes guardarla desde la CLI, leyendo la clave de un archivo o de una tubería: `nan secrets set ANTHROPIC_KEY --value-file key.txt --kind provider_key --provider anthropic`. Consulta [Gestiona los secretos desde la CLI](/es/docs/secrets#gestiona-los-secretos-desde-la-cli).
 
-**Reglas de la URL base.** NaN comprueba la URL base al guardarla y nunca se conecta a ella: solo lo hace el agente de tu workspace.
-
-- Solo `https`, hasta 512 caracteres. Un puerto vale (`https://llm.example.com:8443/v1`).
-- Un nombre de host público (con al menos un punto) o una dirección IP pública. Se rechazan `localhost`, las direcciones privadas y de enlace local, y los nombres que acaban en `.local`, `.internal`, `.lan`, `.home.arpa` o `.svc`.
-- No valen los hosts de NaN (`nan.builders`, `helmcode.com` y sus subdominios): para los modelos de NaN, elige **NaN** como inferencia.
-- Sin `usuario:contraseña@`, sin parámetros (`?...`) y sin fragmento (`#...`).
-
-<Callout title="No pongas nunca un token en la URL base" variant="warning">
-La clave va en **Value**, donde se guarda cifrada y enmascarada. La URL base no es un secreto: el portal, `nan secrets ls` y la API la muestran tal cual. Una URL con un token dentro se rechaza si lleva `usuario:contraseña@` o parámetros, pero cualquier otra forma de esconder un token en ella quedaría a la vista de quien lea tus ajustes.
-</Callout>
+**Reglas de la URL base.** NaN comprueba la URL base al guardarla y nunca se conecta a ella: solo lo hace el agente de tu workspace. Tiene que ser una dirección `https` pública, que no sea uno de los hosts de NaN, sin `usuario:contraseña@`, parámetros ni fragmento: la lista completa está en [Reglas de la URL base](/es/docs/secrets#reglas-de-la-url-base). **No pongas nunca un token en la URL base**: no es un secreto, y el portal, `nan secrets ls` y la API la muestran en claro.
 
 ### Elígela para un run
 
@@ -240,7 +231,7 @@ Tu proveedor factura todos los tokens de estos runs, en tu cuenta con él. NaN n
 
 ### Seguridad
 
-- Tu clave se guarda como cualquier [secreto](/es/docs/automations#secretos): cifrada, de solo escritura y enmascarada en logs, resultados y propuestas.
+- Tu clave se guarda como cualquier [secreto](/es/docs/secrets): cifrada, de solo escritura y [enmascarada](/es/docs/secrets#enmascarado-en-logs-y-eventos) en logs, resultados y propuestas.
 - Solo llega al agente del run, dentro de tu propio workspace, como variable de entorno: nunca en la línea de comandos, en un archivo ni en los logs de NaN. El run no recibe la clave de inferencia de NaN de tu workspace.
 - **NaN nunca llama a tu URL base ni a tu proveedor.** Lo hace el agente de tu workspace, por la red de tu workspace.
 - El run lee los ajustes de tu agente para conservar tus skills y preferencias, pero usa su propia copia de la configuración, con solo el proveedor de tu clave: tus archivos de configuración no cambian.