@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/workspace.md

@@ -0,0 +1,323 @@
+---
+title: "Espacio de trabajo"
+description: "Claude: personalización a nivel de código por usuario (skills, memoria, instrucciones, agentes personalizados, trabajos programados, servidores MCP) respaldados por SQL, no por un sistema de archivos."
+---
+
+# Espacio de trabajo
+
+> **¿Qué documento de espacio de trabajo?** Esta página cubre la **capa de personalización**: qué es un espacio de trabajo. Para conocer la forma de implementación (un monorepo, muchas aplicaciones), consulte [Multi-App Workspaces](/docs/multi-app-workspace); para conocer la gobernanza (quién revisa, aprueba y es propietario de qué), consulte [Workspace Governance](/docs/workspace-management).
+
+Cada aplicación nativa del agente viene con un **espacio de trabajo**: la capa de personalización que hace suyo al agente. Contiene instrucciones de equipo (`AGENTS.md`), aprendizajes compartidos (`LEARNINGS.md`), memoria estructurada personal (`memory/MEMORY.md`), skills que el agente utiliza según demanda, subagentes personalizados, trabajos programados y servidores MCP conectados: todo lo que esperarías de una configuración de código Claude/Codex.
+
+El giro: **son filas SQL, no archivos del sistema de archivos.** Cada usuario obtiene su propio espacio de trabajo almacenado en la base de datos. No hay una caja de desarrollo que activar, ni un contenedor por usuario, ni archivos que montar. Un SaaS multiinquilino puede brindar a cada usuario un agente totalmente personalizable de forma esencialmente gratuita, porque todo son filas (memoria personal, servidores MCP personales, skills personal, subagentes personales) y el código base compartido los aloja todos a la vez.
+
+```an-diagram title="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
+{
+  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL database</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
+  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+}
+```
+
+| Código Claude / Codex                           | Espacio de trabajo nativo del agente                                    |
+| ----------------------------------------------- | ----------------------------------------------------------------------- |
+| Archivos en su disco local                      | Filas en una base de datos SQL compartida                               |
+| Una base de código por desarrollador            | Una base de código, muchos usuarios                                     |
+| Necesita una caja de desarrollo o un contenedor | Se ejecuta en cualquier host perimetral/sin servidor                    |
+| Personalización en `~/.claude/`                 | Personalización por usuario, ámbito `u:<email>:…`                       |
+| `CLAUDE.md` / skills por proyecto               | `AGENTS.md` por aplicación + recursos de memoria del espacio de trabajo |
+| Configuración MCP en un archivo JSON            | Configuración MCP en JSON _o_ la configuración UI, según el alcance     |
+
+Las mismas capacidades. Economía diferente. Consulte [Templates](/docs/cloneable-saas) para saber por qué esto es importante para SaaS.
+
+## Descripción general {#overview}
+
+Los recursos tienen tres alcances de ejecución:
+
+- **Personal**: dirigido a un único usuario (su correo electrónico). Bueno para preferencias, notas y contexto por usuario.
+- **Compartido/organización**: visible para todos los usuarios de la aplicación u organización. Bueno para instrucciones de aplicación/equipo, skills y configuración compartida.
+- **Espacio de trabajo**: valores predeterminados globales heredados administrados desde Dispatch Resources. Bueno para datos de la empresa, posicionamiento, pautas de marca, barreras de seguridad globales, skills en todo el espacio de trabajo y servidores MCP compartidos. Las aplicaciones los leen en tiempo de ejecución; no se copian en cada aplicación.
+
+El panel Área de trabajo de la aplicación muestra los tres ámbitos. Los recursos personales y compartidos/de la organización se pueden editar allí. Los recursos del ámbito del espacio de trabajo son de solo lectura en los paneles de aplicaciones y se editan de forma centralizada desde Dispatch, por lo que cada aplicación ve los mismos archivos canónicos sin un paso de sincronización.
+
+Las rutas canónicas que controlan cómo el agente usa cada recurso:
+
+| Recurso de tiempo de ejecución     | Ruta                                   | Cómo lo usan los agentes                                                  |
+| ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| Instrucciones sobre barandillas    | `AGENTS.md` o `instructions/<slug>.md` | Se carga cada turno en cada aplicación que lo recibe                      |
+| skills global                      | `skills/<slug>/SKILL.md`               | Listado como espacio de trabajo skills y lectura bajo demanda             |
+| Recursos de marca/empresa          | `context/<slug>.md`                    | Indexado en cada turno, leído cuando sea relevante                        |
+| Perfiles de agentes personalizados | `agents/<slug>.md`                     | Disponibles como perfiles de agentes locales reutilizables                |
+| Servidores compartidos HTTP MCP    | `mcp-servers/<slug>.json`              | Cargado en el registro de herramientas MCP de las aplicaciones concedidas |
+
+Estas rutas se aplican en los tres ámbitos: espacio de trabajo, organización/aplicación y personal. El ámbito posterior gana cuando existe la misma ruta en múltiples niveles.
+
+```an-diagram title="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
+{
+  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organization / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
+  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+}
+```
+
+## Primeros pasos: un tutorial de 1 minuto {#getting-started}
+
+Cambia el comportamiento del agente en 60 segundos.
+
+1. Abra la pestaña **Espacio de trabajo** → **Compartido** → `AGENTS.md` (créelo con `+` → **Archivo** si falta).
+2. Agregue una regla, por ejemplo:
+
+   ```rebaja
+   ## Tono
+
+   Sea conciso. Comienza con la respuesta.
+   ```
+
+3. Guarde, cambie a **Chat**, pregunte cualquier cosa: el agente sigue la nueva regla inmediatamente.
+
+```an-callout
+{ "tone": "info", "body": "No restart, no redeploy. `AGENTS.md` is read at the start of every turn, so an edit you save now changes the agent's behavior on the very next message." }
+```
+
+**Próximos pasos, cuando los desees:**
+
+- **Skills** (`+` → **Habilidad**): archivos instructivos enfocados invocados en el chat con `/skill-name`.
+- **Agentes** (`+` → **Agente**): personas de subagente reutilizables invocadas con `@agent-name`.
+- **Tareas programadas** (`+` → **Tarea programada**): mensajes que se ejecutan en un cron. Consulte [Recurring Jobs](/docs/recurring-jobs) para conocer los horarios y los factores desencadenantes.
+- **Memoria**: el `LEARNINGS.md` compartido y el `memory/MEMORY.md` personal mantienen un contexto duradero disponible en todas las conversaciones.
+
+## Recursos globales y rutas canónicas {#global-resources}
+
+Los recursos del ámbito del espacio de trabajo se administran desde la página **Recursos** de Dispatch y las aplicaciones los heredan en tiempo de ejecución, sin necesidad de copiar ni sincronizar. Dispatch admite dos ámbitos de subvención:
+
+- **Todas las aplicaciones**: recursos globales que hereda cada aplicación del espacio de trabajo. La mayor parte del contexto de empresa, marca, personalidad, posicionamiento, mensajes y barandillas deben ser **Todas las aplicaciones**.
+- **Aplicaciones seleccionadas**: recursos otorgados a aplicaciones específicas para contextos o herramientas específicos de la aplicación. Úselos con moderación.
+
+La ruta determina cómo el agente usa un recurso (consulte la tabla en [Overview](#overview) arriba). Este es el hogar adecuado para personas principales, posicionamiento, mensajes, datos de la empresa, pautas de marca, políticas de soporte, herramientas skills compartidas o HTTP MCP compartidas de las que muchas aplicaciones deberían beneficiarse.
+
+Un paquete inicial útil para un nuevo espacio de trabajo:
+
+```text
+context/company.md              # what the company does, ICP, products, links
+context/brand.md                # voice, visual identity, spelling, forbidden usage
+context/messaging.md            # positioning, value props, proof points, objections
+instructions/guardrails.md      # compliance, escalation, and approval rules
+skills/company-voice/SKILL.md   # on-demand guidance for customer-facing writing
+agents/<slug>.md                # reusable custom agent profiles
+```
+
+Mantenga los archivos `context/` actualizados y fáciles de leer. Pon reglas que deben aplicarse en cada turno en `instructions/guardrails.md`. Utilice `skills/company-voice/SKILL.md` cuando el agente deba transformar o revisar deliberadamente una copia en la voz de la empresa.
+
+Para anular un valor predeterminado global para una aplicación o equipo, cree un recurso compartido/organizativo en esa aplicación con la misma ruta. Para anularlo para una persona, cree un recurso personal con la misma ruta. No copie el archivo del espacio de trabajo en cada aplicación; el tiempo de ejecución resuelve la pila al leer:
+
+```text
+workspace context/brand.md
+-> shared/app context/brand.md
+-> personal context/brand.md
+```
+
+Mantenga los archivos `context/` breves y objetivos: algunos puntos que el agente puede leer:
+
+```text
+<!-- context/brand.md -->
+
+# Brand
+
+- Voice: direct, warm, concrete
+- Use: "workspace", "agent", "team"
+- Avoid: unsupported superlatives and vague AI claims
+```
+
+## Panel de espacio de trabajo {#workspace-panel}
+
+El panel del agente incluye una pestaña **Espacio de trabajo** junto a Chat y CLI. Muestra un árbol organizado en carpetas de todos los recursos, un editor en línea para cualquier archivo de texto (Markdown, JSON, YAML, texto sin formato) y los flujos de creación escritos del menú `+` (Archivos, Skills, Agentes, Tareas programadas). Los usuarios pueden explorar los valores predeterminados del espacio de trabajo heredado y crear, editar o eliminar recursos personales o de la organización.
+
+Cuando abre un recurso, el editor muestra una franja de **Contexto efectivo** con la pila `workspace default -> organization/app override -> personal override`, para que pueda ver qué se heredó y por qué está activa una anulación. Dispatch muestra el mismo modelo desde el lado del plano de control: en la página **Recursos**, use **Efectivo en la aplicación** o expanda **Apilar** en una fila de recursos en el cuadro de diálogo **Contexto** de una tarjeta de aplicación.
+
+Cuando la política de aprobación de envío está habilitada, la creación, actualización o eliminación de un recurso **Todas las aplicaciones** pone en cola una solicitud de aprobación en lugar de aplicarla inmediatamente. Los cuadros de diálogo de creación/edición/eliminación muestran una vista previa del impacto antes de guardar.
+
+Haga clic en el icono `?` en la barra de herramientas del espacio de trabajo para volver a estos documentos en cualquier momento.
+
+## Cómo utiliza el agente los recursos {#how-the-agent-uses-resources}
+
+El agente de aplicación integrado administra los recursos con la herramienta unificada `resources`: use `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"` o `"delete"`. Los agentes de código/CLI externos pueden utilizar los comandos `pnpm action resource-*` equivalentes.
+
+Al inicio de cada conversación, el agente lee automáticamente:
+
+### AGENTS.md e instrucciones {#agents-md}
+
+`AGENTS.md` es un recurso de instrucción que se genera de forma predeterminada y se carga en cada turno desde ámbitos de espacio de trabajo, compartido/organización y personal en ese orden: espacio de trabajo para valores predeterminados de toda la empresa, compartido/aplicación para reglas de equipo, personal para preferencias por usuario. Los archivos bajo `instructions/` son documentos de seguridad separados que también se aplican en cada turno (reglas de cumplimiento, política de escalamiento, voz de marca) y siguen la misma precedencia. Tanto el chat normal como las ejecuciones activadas por integración los cargan antes de responder.
+
+```text
+AGENTS.md
+instructions/customer-support-guardrails.md
+instructions/legal-review-policy.md
+```
+
+### Recursos de referencia {#reference-resources}
+
+El contexto empresarial reutilizable se encuentra bajo `context/` (personas, posicionamiento, datos del producto, pautas de marca, notas competitivas). El agente ve un índice de estos y lee el archivo correspondiente con la herramienta `resources` (`action: "read"`) cuando una tarea puede depender de ello; use `action: "effective"` para ver si se anula el valor predeterminado del espacio de trabajo para una aplicación o usuario.
+
+### Memoria {#memory}
+
+El espacio de trabajo tiene dos superficies de memoria actuales:
+
+- `LEARNINGS.md` en alcance **compartido** para convenciones, correcciones y conocimiento duradero del equipo en todo el proyecto.
+- `memory/MEMORY.md` en el ámbito **Personal** para la memoria estructurada sobre el usuario actual.
+
+El sistema de recursos también genera un `LEARNINGS.md` personal para compatibilidad con espacios de trabajo más antiguos, pero la ruta de precarga del chat es compartida `LEARNINGS.md` más `memory/MEMORY.md` personal.
+
+**Qué se guarda.** Cuando corrige al agente ("use siempre X en lugar de Y"), comparte una preferencia ("Prefiero respuestas concisas") o revela el contexto ("mi equipo llama a esto 'la capa de despacho'"), el agente captura ese aprendizaje para no repetir el error ni volver a preguntar. Los aprendizajes de todo el proyecto se comparten en `LEARNINGS.md`; La memoria específica del usuario se encuentra bajo `memory/`. La habilidad `capture-learnings` explica cuándo y cómo.
+
+**Donde cabe.**
+
+| Superficie         | Alcance                       | Escrito por                                                        | Leer cuando                                        |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------ | -------------------------------------------------- |
+| `AGENTS.md`        | Compartido                    | Humanos/agente bajo petición                                       | Cada turno                                         |
+| `LEARNINGS.md`     | Compartido                    | Humanos/agente bajo petición                                       | Cada turno (solo copia compartida)                 |
+| `memory/MEMORY.md` | Personales                    | Agente / humanos                                                   | Cada turno                                         |
+| `instructions/…`   | Compartido                    | Humanos/agente bajo petición                                       | Cada turno                                         |
+| `skills/…`         | Compartido                    | Humanos/agente bajo petición                                       | Bajo demanda (comando `/slash`)                    |
+| `context/…`        | Compartido                    | Humanos/agente bajo petición                                       | Indexado en cada turno, leído cuando sea relevante |
+| `mcp-servers/…`    | Espacio de trabajo/compartido | Humanos a través de Dispatch o espacio de trabajo de la aplicación | Actualización de configuración MCP                 |
+
+Los usuarios pueden editar estos archivos de memoria directamente en la pestaña Espacio de trabajo; son recursos regulares. Elimine líneas en las que el agente se equivocó, mantenga las preferencias personales en `memory/MEMORY.md` o promueva reglas para todo el equipo en `AGENTS.md`.
+
+Cada una de estas superficies (`AGENTS.md`, skills, memoria, agentes personalizados, servidores MCP) tiene la misma forma de recurso subyacente: un `path` + `scope` + `content`, direccionado y resuelto de la misma manera.
+
+```an-schema title="The workspace resource model" summary="One resource shape backs every workspace file. The runtime keys it by path and scope and resolves the effective value on read."
+{
+  "entities": [
+    {
+      "id": "resource",
+      "name": "workspace resource",
+      "note": "A single file in a user's workspace — instructions, skill, memory, agent, MCP config, or job.",
+      "fields": [
+        { "name": "path", "type": "string", "note": "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md" },
+        { "name": "scope", "type": "workspace | shared | personal", "note": "Which level this row lives at" },
+        { "name": "owner", "type": "string", "nullable": true, "note": "u:<email> for personal scope" },
+        { "name": "content", "type": "text", "note": "Markdown / JSON / YAML body" }
+      ]
+    }
+  ]
+}
+```
+
+## Skills {#skills}
+
+Skills son archivos de recursos Markdown en la ruta `skills/` (preferiblemente `skills/<name>/SKILL.md`) que brindan al agente conocimiento del dominio bajo demanda, invocados en el chat con `/skill-name`. Agréguelos desde la pestaña Espacio de trabajo o, en modo Código, desde `.agents/skills/`.
+
+Consulte [Skills Guide](/docs/skills-guide): la fuente única de formato, alcance, descubrimiento y creación de habilidades.
+
+## Agentes personalizados {#custom-agents}
+
+Los agentes personalizados son perfiles de subagente local reutilizables almacenados como recursos Markdown en `agents/*.md`. Este es el hogar canónico del formato de agente personalizado.
+
+Úselos cuando desee un delegado enfocado con su propio nombre, descripción, preferencia de modelo y conjunto de instrucciones. A diferencia de skills, los agentes personalizados no son una guía pasiva: son personajes operativos que el agente principal puede invocar a través de menciones de `@` o seleccionándolos durante la generación de subagentes.
+
+### Formato de agente {#agent-format}
+
+Los agentes personalizados utilizan el frontmatter YAML más las instrucciones Markdown:
+
+```an-annotated-code title="A custom agent profile"
+{
+  "filename": "agents/design.md",
+  "language": "markdown",
+  "code": "---\nname: Design\ndescription: >-\n  Reviews layouts, interaction patterns, and product UX decisions.\nmodel: inherit\ntools: inherit\ndelegate-default: false\n---\n\n# Role\n\nYou are a focused design agent.\n\n## Responsibilities\n\n- Review layouts and interaction flows\n- Suggest stronger visual direction\n- Be concise and opinionated",
+  "annotations": [
+    { "lines": "2", "label": "@mention handle", "note": "`name` is what appears in the `@`-dropdown and what the main agent delegates to." },
+    { "lines": "3-4", "label": "When to delegate", "note": "The `description` is what the orchestrator reads to decide this profile fits a task." },
+    { "lines": "5", "label": "Model", "note": "`inherit` reuses the main agent's model. Override only when the profile clearly needs a different one." },
+    { "lines": "6", "note": "`tools: inherit` for now — the field is reserved for future per-agent tool policies." }
+  ]
+}
+```
+
+Convenciones recomendadas:
+
+- Almacenar agentes personalizados en `agents/<slug>.md`
+- Utilice `model: inherit` a menos que el perfil necesite claramente un modelo diferente
+- Conserve `tools: inherit` por ahora; el campo está reservado para futuras políticas de herramientas
+
+### Agentes remotos versus agentes personalizados {#remote-vs-custom-agents}
+
+Hay dos tipos de agentes en Workspace:
+
+- **Agentes personalizados**: perfiles locales en `agents/*.md`, ejecutados dentro de la aplicación/tiempo de ejecución actual
+- **Agentes conectados**: pares remotos de A2A descritos por manifiestos en `remote-agents/*.json` (los manifiestos antiguos de `agents/*.json` aún se reconocen)
+
+Utilice agentes personalizados para delegar dentro de una aplicación. Utilice agentes conectados cuando necesite llamar a otra aplicación a través de A2A.
+
+## @ Etiquetado {#at-tagging}
+
+Escriba `@` en la entrada del chat para hacer referencia a los elementos del espacio de trabajo. Aparece un menú desplegable en el cursor que muestra los agentes y archivos coincidentes. Utilice las teclas de flecha para navegar y Enter para seleccionar. El elemento seleccionado aparece como un chip en línea en la entrada.
+
+Cuando envía un mensaje, **archivos/recursos** se pasan como referencias que el agente puede leer, los **agentes personalizados** se ejecutan localmente con sus instrucciones de perfil y los **agentes conectados** se llaman a través de A2A.
+
+## /Comandos de barra diagonal {#slash-commands}
+
+Escriba `/` al comienzo de una línea para invocar una habilidad. Un menú desplegable muestra los skills disponibles con sus nombres y descripciones; seleccionar uno agrega un chip en línea e incluye su contenido como contexto cuando se envía el mensaje. Si no hay ningún skills configurado, el menú desplegable enlaza a estos documentos.
+
+## Código versus modo de aplicación {#dev-vs-prod}
+
+El sistema de recursos funciona de manera idéntica en ambos modos. Lo que difiere son las fuentes adicionales disponibles para el etiquetado `@` y los comandos `/`:
+
+| Característica               | Modo de código                                                                                          | Modo de aplicación                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| @ etiquetado                 | Archivos de código base + recursos del espacio de trabajo + agentes personalizados + agentes conectados | Recursos del espacio de trabajo + agentes personalizados + agentes conectados |
+| /comandos de barra diagonal  | .agents/skills/ + recurso skills                                                                        | Recurso skills únicamente                                                     |
+| Acceso al archivo del agente | Sistema de archivos + recursos                                                                          | Solo recursos                                                                 |
+| Panel de espacio de trabajo  | Acceso completo                                                                                         | Acceso completo                                                               |
+| AGENTS.md/memoria            | Disponible                                                                                              | Disponible                                                                    |
+
+## Conexiones del espacio de trabajo {#workspace-connections}
+
+Workspace Connections permite que las aplicaciones compartan la misma cuenta de proveedor (Slack, GitHub, HubSpot, etc.) sin duplicar credenciales. Una conexión registra la identidad del proveedor, las etiquetas de cuenta, el estado, los ámbitos, las concesiones de aplicaciones y las referencias de credenciales en SQL. Los secretos permanecen en el almacén de credenciales; las conexiones solo apuntan a nombres de claves de credenciales como `SLACK_BOT_TOKEN`.
+
+Consulte [Workspace Connections](/docs/workspace-connections) para obtener información sobre inicio rápido, conexión/concesión/credencialRef API y ejemplos concretos de Slack, HubSpot y GitHub.
+
+---
+
+# Referencia
+
+## Recurso API {#resource-api}
+
+Los recursos se pueden administrar desde el código del servidor, actions o REST API.
+
+### Servidor API {#server-api}
+
+Puntos finales REST montados automáticamente:
+
+| Método   | Punto final                                   | Descripción                                            |
+| -------- | --------------------------------------------- | ------------------------------------------------------ |
+| `GET`    | `/_agent-native/resources?scope=all`          | Listar recursos                                        |
+| `GET`    | `/_agent-native/resources?scope=workspace`    | Enumerar los recursos del espacio de trabajo heredados |
+| `GET`    | `/_agent-native/resources/tree?scope=all`     | Obtener árbol de carpetas                              |
+| `GET`    | `/_agent-native/resources/effective?path=...` | Mostrar la pila de herencia efectiva                   |
+| `POST`   | `/_agent-native/resources`                    | Crear un recurso                                       |
+| `GET`    | `/_agent-native/resources/:id`                | Obtener recurso con contenido                          |
+| `PUT`    | `/_agent-native/resources/:id`                | Actualizar un recurso                                  |
+| `DELETE` | `/_agent-native/resources/:id`                | Eliminar un recurso                                    |
+| `POST`   | `/_agent-native/resources/upload`             | Subir un archivo como recurso                          |
+
+### Acción API {#script-api}
+
+El agente utiliza estos actions integrados. También puedes llamarlos desde tu propio actions:
+
+```bash
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill/SKILL.md"
+
+# Read inherited workspace context managed by Dispatch
+pnpm action resource-read --scope workspace --path "context/brand.md"
+
+# Show workspace -> organization/app -> personal precedence for a path
+pnpm action resource-effective --path "context/brand.md"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+```

package/docs/content/locales/es-ES/writing-agent-instructions.md

@@ -0,0 +1,173 @@
+---
+title: "Instrucciones del agente de escritura y Skills"
+description: "Cómo escribir excelentes instrucciones de agente para una aplicación o plantilla nativa de agente: AGENTS.md, skills y descripciones de herramientas."
+---
+
+# Instrucciones del agente de escritura y Skills
+
+El comportamiento del agente en una aplicación nativa del agente es tan bueno como las instrucciones que usted le dé. Tres superficies contienen esa guía: `AGENTS.md` (el mapa), skills (las inmersiones profundas) y descripciones de acciones/herramientas (cómo el agente elige la herramienta adecuada). Escribe cada uno para recuperarlo rápidamente, no para escribirlo en prosa.
+
+```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
+{
+  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</small></div></div>",
+  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+## Mantenga AGENTS.md pequeño y fácil de leer {#small-agents-md}
+
+`AGENTS.md` se carga como orientación. Debería ser lo más pequeño que permita al agente actuar correctamente, con todo profundamente metido en skills. Apunta a estas secciones y poco más:
+
+- **Línea de propósito**: una oración sobre qué es la aplicación y el flujo de trabajo principal.
+- **Reglas básicas**: el puñado de invariantes que siempre deben cumplirse (los datos en SQL, las operaciones pasan por actions, la IA pasa por el chat del agente, los cambios de esquema son aditivos). Viñetas cortas e imperativas.
+- **Teclas de estado de la aplicación**: las teclas `navigation`/selección/enfoque que el agente lee para saber qué está mirando el usuario y su forma.
+- **Tabla de acciones**: una tabla compacta del nombre de la acción según su propósito.
+- **Índice Skills**: una lista de los skills que existen y cuándo leer cada uno.
+
+Si una sección crece más allá de una pantalla, pertenece a una habilidad. `AGENTS.md` responde "¿qué es esta aplicación y qué puedo hacer?", no "cómo hago exactamente lo difícil".
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## AGENTS.md de fuente única {#single-source}
+
+Conserve un archivo de instrucciones canónico: `AGENTS.md`. Si un cliente espera `CLAUDE.md`, conviértalo en un enlace simbólico a `AGENTS.md` en lugar de una segunda copia. Dos archivos mantenidos manualmente se desvían y el agente termina con reglas contradictorias. Una fuente de verdad, vinculada donde sea necesario.
+
+## El frontmatter SKILL.md debe decir qué AND y cuándo {#skill-frontmatter}
+
+El `description` es lo único que ve el agente cuando decide si leer una habilidad. Debe responder dos preguntas: qué cubre la habilidad y cuándo activarla. Una descripción que solo describa el tema no se activará.
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- Liderar con la capacidad, luego agregar una cláusula explícita **"Usar cuando..."**.
+- Sé un poco agresivo: activar demasiado es mejor que una habilidad que nunca se carga.
+- Mantenlo en menos de ~40 palabras; se carga en contexto en cada conversación.
+
+## Divulgación progresiva {#progressive-disclosure}
+
+Escriba el `SKILL.md` como la capa sencilla que debe conocer: la regla, cómo hacerlo, la lista de lo que se debe/no se debe hacer y sugerencias. Inserte ejemplos largos, referencias de campos exhaustivas, peculiaridades de API y tablas de casos extremos en archivos `references/` que el agente lee solo cuando los necesita.
+
+```text
+.agents/skills/project-imports/
+├── SKILL.md            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+Esto mantiene pequeña la superficie siempre cargada y permite escalar la profundidad sin un contexto abultado. Consulte [Skills Guide](/docs/skills-guide) para conocer el formato completo de las habilidades.
+
+## Escribir tablas orientadas a acciones {#action-tables}
+
+El agente escanea las tablas más rápido que la prosa. Prefiera una tabla de nombres y propósitos a párrafos que describan cada operación. Lo mismo se aplica a las claves de estado, los tipos de campos y cualquier conjunto enumerable. Las tablas se pueden leer, diferenciar y es fácil mantener sincronizadas cuando agregas una acción.
+
+## Escribir descripciones claras de las herramientas {#tool-descriptions}
+
+Las descripciones de acciones son descripciones de herramientas: impulsan la selección de herramientas. Haz de cada una una oración precisa y de un solo propósito:
+
+- Diga qué hace y qué devuelve, no cómo se implementa.
+- Describe cada parámetro en su `.describe()` para que el agente lo complete correctamente.
+- Una responsabilidad por acción. Si una descripción necesita "y también...", divídala.
+- Marque actions (`readOnly: true` o `http: { method: "GET" }`) como de solo lectura para que el agente sepa que es seguro llamar libremente.
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## Skills frente a actions {#skills-vs-actions}
+
+Skills y actions son complementarios. Una habilidad es una guía que el agente lee; un
+la acción es el código que el agente puede ejecutar.
+
+| Necesidad                                                                                        | Usar                                    |
+| ------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| El agente debe seguir un flujo de trabajo, una política, una lista de verificación o una rúbrica | **Habilidad**                           |
+| El agente necesita ejemplos, material de referencia o reglas específicas del dominio             | **Habilidad**                           |
+| El agente necesita leer o escribir datos de la aplicación                                        | **Acción**                              |
+| El agente necesita llamar a un API externo o realizar una aprobación                             | **Acción**                              |
+| El agente llama a la operación correcta pero de forma incorrecta                                 | Mejorar la **habilidad**                |
+| El agente no puede invocar la operación de manera confiable                                      | Mejorar la **acción**                   |
+| El agente elige la herramienta equivocada                                                        | Mejorar la **descripción de la acción** |
+
+La mayoría de las funciones reales utilizan ambas: la habilidad explica cómo abordar la tarea y
+la acción proporciona la operación escrita. Por ejemplo, una habilidad `invoice-review`
+puede explicar la política de revisión y las reglas de escalamiento, mientras que `list-invoices`,
+`flag-invoice` y `approve-invoice` actions realizan las lecturas y escrituras reales.
+
+## Hornear en antifabricación y verificar antes de terminar {#anti-fabrication}
+
+Las instrucciones de la aplicación deben hacer que la honestidad y la verificación sean el comportamiento predeterminado:
+
+- **Nunca invente.** Si no se encuentran datos o una acción falla, dígalo y recupérelo; no invente resultados ni afirme haber sido exitoso. Lea el valor real a través de una acción o consulta antes de informarla.
+- **Verifique antes de declarar realizado.** Después de un cambio, confírmelo con una lectura posterior (vuelva a consultar la fila, vuelva a leer la pantalla a través de `view-screen`) en lugar de asumir que la escritura funcionó.
+- **Recupera, no te rindas.** En caso de un error recuperable (una consulta fallida, una recuperación transitoria), vuelve a intentar o corrige la entrada en lugar de abandonar la tarea. Mantenga esto separado de la regla contra la fabricación: no combine "no inventar cosas" con "deténgase en el primer error".
+
+Póngalas como reglas básicas en `AGENTS.md` para que se apliquen en todos los turnos.
+
+## Las cuatro superficies que ve el agente {#four-surfaces}
+
+Cada pieza de orientación que usted crea aterriza en una de las cuatro superficies. Saber qué superficie utilizar evita duplicaciones y detalles fuera de lugar:
+
+| Superficie                               | Quién lo escribe                      | Cuando está cargado                                             | Qué pertenece allí                                                                             |
+| ---------------------------------------- | ------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Instrucciones `AGENTS.md`                | Tú (desarrollador)                    | Cada giro, como orientación                                     | Propósito, reglas básicas, claves de estado, índice de acción, índice skills                   |
+| Skills (`SKILL.md`)                      | Tú (desarrollador)                    | A pedido, cuando el agente decide que la habilidad es relevante | Instrucciones paso a paso para un patrón específico, listas de lo que se debe/no se debe hacer |
+| Descripciones de acciones (herramientas) | Tú (desarrollador)                    | Cada turno, según la lista de herramientas                      | Qué hace la acción, qué devuelve, semántica de los parámetros                                  |
+| Contexto `application_state`             | Su código UI (en tiempo de ejecución) | Cada turno, como estado de la aplicación en vivo                | Navegación actual, selección, objeto enfocado, URL                                             |
+
+**Diagnóstico rápido:**
+
+- "El agente sigue preguntando en qué registro actuar incluso cuando hay uno abierto" → solución: escriba el ID del elemento actual en `application_state` (clave `navigation`) desde su UI. Esa es una brecha `application_state`, no una brecha de habilidades.
+- "El agente realiza una acción incorrecta o hace un mal uso de un parámetro" → solución: mejora `description` y `.describe()` de la acción en el parámetro. Esa es una corrección de descripción de herramienta, no una habilidad.
+
+## Qué va a dónde {#what-goes-where}
+
+- **AGENTS.md**: se aplica a toda la aplicación, en cada paso: propósito, reglas básicas, claves de estado, índice de acción, índice skills.
+- **Skills**: instrucciones reutilizables para un patrón específico, cargadas bajo demanda. Se aplica a todos los que trabajan en la aplicación.
+- **Memoria (`memory/MEMORY.md`)**: preferencias y correcciones por usuario, no orientación escrita.
+
+## ¿Qué sigue? {#whats-next}
+
+- [Skills Guide](/docs/skills-guide): el formato de archivo de habilidades, el marco skills y el skills respaldado por la aplicación.
+- [Creating Templates](/docs/creating-templates): cómo encajan `AGENTS.md` y skills en una plantilla que se puede enviar.
+- [The four-area checklist](/docs/key-concepts#four-area-checklist): el modelo de cuatro áreas que toda característica debe satisfacer.