@agent-native/core 0.46.0 → 0.48.1

package/docs/content/workspace-management.md

@@ -5,7 +5,7 @@ description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime
 
 # Workspace Governance
 
-This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the dispatch control plane fits into your governance model.
+This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the Dispatch control plane fits into your governance model.
 
 For workspace setup, shared auth, and deployment, see [Multi-App Workspaces](/docs/multi-app-workspace).
 
@@ -34,33 +34,16 @@ Keep branches short-lived. Long-lived branches diverge from main and create pain
 
 ### Non-Developer Branching
 
-Not everyone who needs to make changes is comfortable with git. For teams with designers, product managers, or content editors who need to make visual changes:
-
-[Builder.io](https://www.builder.io) supports a visual branching model that maps to git branches under the hood:
-
-- Create branches from Builder's dashboard — no terminal needed
-- Edit content, components, layouts, and configuration visually
-- Preview changes in isolation before merging
-- Changes map to git branches, so developer and non-developer work converges
-
-This is useful for content and copy changes, layout adjustments, design iterations, and A/B testing — work that shouldn't require a dev environment. Developer code changes and Builder visual changes can coexist on the same branch.
+Not everyone who needs to make changes is comfortable with git. [Builder.io](https://www.builder.io) supports a visual branching model that maps to git branches under the hood — useful for content and copy changes, layout adjustments, design iterations, and A/B testing without a dev environment.
 
 ## Code Ownership
 
-GitHub's CODEOWNERS file auto-assigns reviewers to PRs based on which files changed. In a monorepo with many apps, this is how you make sure the right people review the right code without everyone reviewing everything.
-
-### Example CODEOWNERS
-
-Create `.github/CODEOWNERS` at the repo root:
+GitHub's CODEOWNERS file auto-assigns reviewers to PRs based on which files changed. Create `.github/CODEOWNERS` at the repo root:
 
 ```
-# Framework core — platform/infra team reviews all changes here
-# because they affect every app in the workspace
+# Framework core — affects every app; platform team reviews all changes
 packages/core/                     @your-org/platform-team
 
-# Desktop app shell
-packages/desktop-app/              @your-org/platform-team
-
 # Dispatch control plane — secrets, integrations, workspace resources
 templates/dispatch/                @your-org/platform-team
 
@@ -68,94 +51,38 @@ templates/dispatch/                @your-org/platform-team
 templates/mail/                    @your-org/mail-team
 templates/analytics/               @your-org/analytics-team
 templates/calendar/                @your-org/calendar-team
-templates/content/                 @your-org/content-team
-templates/design/                  @your-org/design-team
-templates/forms/                   @your-org/forms-team
-templates/clips/                   @your-org/clips-team
-templates/slides/                  @your-org/slides-team
-templates/videos/                  @your-org/videos-team
+# ... add an entry per app
 
 # Workspace-level config — broad review since it affects everyone
 .github/                           @your-org/platform-team
 package.json                       @your-org/platform-team
 pnpm-workspace.yaml                @your-org/platform-team
-.env.example                       @your-org/platform-team
 ```
 
-### Tips
+Key tips: use GitHub teams (`@org/team`), not individuals. Framework and Dispatch changes should always require platform review. See [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for glob syntax and multiple-owner patterns.
 
-- **Use GitHub teams, not individuals.** `@org/analytics-team` survives people changing roles. `@jdoe` doesn't.
-- **Framework changes need platform review.** A one-line change in `packages/core/` can break every app. The platform team should always see these.
-- **App teams own their templates.** The people who built and maintain an app understand its domain — they should review changes to it.
-- **Dispatch is infrastructure.** Treat it like core. It manages secrets and resources that affect the whole workspace.
-- **You can narrow with globs.** `templates/mail/**/*.tsx` if you want to assign frontend-specific reviewers for UI-only changes.
-- **Multiple owners are fine.** List both the app team and a senior engineer for critical paths like DB schemas or auth.
-
-### Enabling Required Reviews
-
-1. Create `.github/CODEOWNERS` with the patterns above
-2. In GitHub → Settings → Branches → Branch protection for `main`:
-   - Enable **Require a pull request before merging**
-   - Enable **Require review from Code Owners**
-   - Set minimum required approvals (1 is usually fine, 2 for regulated environments)
-3. Create the GitHub teams referenced in CODEOWNERS
-
-Once enabled, GitHub won't let a PR merge until each CODEOWNERS-matched team has approved. A PR that touches `templates/mail/` and `packages/core/` requires approval from both `@your-org/mail-team` and `@your-org/platform-team`.
+To enable required reviews: Settings → Branches → Branch protection for `main` → **Require a pull request before merging** → **Require review from Code Owners**.
 
 ## PR Labeling
 
-Auto-labeling PRs by app makes it easy to filter and prioritize reviews. Add `.github/labeler.yml`:
+Auto-label PRs by app with `.github/labeler.yml` (excerpt):
 
 ```yaml
 app:mail:
   - changed-files:
       - any-glob-to-any-file: templates/mail/**
-
 app:analytics:
   - changed-files:
       - any-glob-to-any-file: templates/analytics/**
-
-app:calendar:
-  - changed-files:
-      - any-glob-to-any-file: templates/calendar/**
-
-app:design:
-  - changed-files:
-      - any-glob-to-any-file: templates/design/**
-
-dispatch:
-  - changed-files:
-      - any-glob-to-any-file: templates/dispatch/**
-
 core:
   - changed-files:
       - any-glob-to-any-file: packages/core/**
 ```
 
-Then add the [actions/labeler](https://github.com/actions/labeler) GitHub Action to `.github/workflows/labeler.yml`:
-
-```yaml
-name: Label PRs
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-jobs:
-  label:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
-    steps:
-      - uses: actions/labeler@v5
-```
-
-Labels apply automatically when PRs are opened or updated. Teams can then filter their review queue by label.
+Then add the [actions/labeler](https://github.com/actions/labeler) action — see that repo's README for the full workflow YAML. Labels apply automatically when PRs are opened or updated.
 
 ## PR Review Guidelines
 
-### By Change Type
-
 | Change type                       | Who reviews                           | What to watch for                                                         |
 | --------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
 | **App-only** (`templates/<app>/`) | Owning app team                       | Domain correctness, action schemas                                        |
@@ -192,54 +119,11 @@ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It
 | Audit trail                     | `git log` / `git blame`       | Vault audit + dispatch audit logs                            |
 | Messaging & routing             | —                             | Slack / Telegram integration                                 |
 
-**Git handles code governance. Dispatch handles runtime governance.** Don't try to replicate git workflows inside dispatch or vice versa. They cover different surfaces.
-
-### What Dispatch Manages
-
-- **Vault** — store credentials centrally and sync on demand. The default policy makes all vault keys available to all workspace apps; manual mode requires specific app grants. Non-admins can request access; admins approve.
-- **Reusable integrations** — connect provider accounts once, store safe
-  credential refs and account metadata, and grant apps access without copying
-  secrets. Dispatch is the control plane for provider inventory, repair,
-  grants, and audit; the vault/secrets layer owns values; each app keeps its
-  own source configuration and interpretation.
-- **Workspace resources** — manage global skills, always-on guardrail instructions, reusable agent profiles, reference resources, and HTTP MCP servers inherited by apps. Use `AGENTS.md` or `instructions/<slug>.md` for instructions loaded every turn, `skills/<slug>/SKILL.md` for on-demand skills, `context/<slug>.md` for brand/company/product knowledge, and `mcp-servers/<slug>.json` for shared HTTP MCP tool servers. Scope to All apps for workspace defaults; apps read those defaults at runtime with no copy or manual sync step, and app shared or personal resources can override locally. The Resources page highlights the starter global context files, can restore missing starter files, and each app card shows the exact inherited/granted resources that app receives.
-- **Approvals** — require review before runtime changes (destinations, settings) take effect.
-- **Audit** — full history of secret access, grants, syncs, and changes.
-
-### Public App Routes
-
-Workspace apps are internal by default. For a public site with login-only admin
-pages, set a public audience and protect the admin prefix in that app's
-`package.json`:
-
-```json
-{
-  "agent-native": {
-    "workspaceApp": {
-      "audience": "public",
-      "protectedPaths": ["/admin"]
-    }
-  }
-}
-```
+**Git handles code governance. Dispatch handles runtime governance.** Don't try to replicate git workflows inside Dispatch or vice versa.
 
-For mostly internal apps with a few public pages, leave the audience internal and
-list page prefixes:
-
-```json
-{
-  "agent-native": {
-    "workspaceApp": {
-      "publicPaths": ["/", "/share"]
-    }
-  }
-}
-```
+Dispatch manages: vault secrets, reusable workspace connections, workspace resources (skills, instructions, agent profiles, MCP servers), approvals, and audit logs. For public app route configuration (`workspaceApp.audience` / `publicPaths` / `protectedPaths`), see [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment).
 
-These settings only affect read-only page navigation. Framework tools, agent
-chat, A2A, vault access, and arbitrary APIs stay authenticated unless the app
-explicitly declares public prefixes with
-`createAuthPlugin({ publicPaths: [...] })`.
+For the resource model and canonical paths, see [Workspace — Global resources](/docs/workspace#global-resources).
 
 ## Setup Checklist
 

package/docs/content/workspace.md

@@ -22,39 +22,8 @@ The twist: **it's SQL rows, not filesystem files.** Each user gets their own wor
 
 Same capabilities. Different economics. See [Templates](/docs/cloneable-saas) for why this matters for SaaS.
 
-## The Workspace tab {#the-tab}
-
-The **Workspace** tab in the agent sidebar is where you and the agent share persistent files — notes, instructions, skills, custom agents, and scheduled jobs. Files live in the database (not the filesystem), so they persist across sessions, work in serverless/edge deploys, and can be edited from both the UI and the agent.
-
-## TL;DR {#tldr}
-
-- Open the **Workspace** tab in the agent sidebar.
-- Create files with the `+` menu. Upload with the upload button. Edit inline (visual or code view).
-- **Personal** is just you. **Shared** is your team/org.
-- The agent can read, write, and rename any of these files as part of a conversation.
-- Special files the agent preloads: shared `AGENTS.md`, shared `instructions/*.md`, shared `LEARNINGS.md`, and personal structured memory at `memory/MEMORY.md`.
-- Shared reference resources such as `context/brand-guidelines.md` are indexed for the agent; it reads the relevant file when a task may depend on company, brand, positioning, persona, product, or domain context.
-
-## What goes in here? {#what-goes-in-here}
-
-| File / path                 | What it's for                                                                                           |
-| --------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `AGENTS.md` (Shared)        | Team instructions the agent reads every turn — tone, rules, domain context, skill references.           |
-| `instructions/<name>.md`    | Additional always-on shared guardrails loaded every turn. Good for compliance, brand voice, and policy. |
-| `LEARNINGS.md` (Shared)     | Shared corrections, conventions, and durable project memory the agent preloads.                         |
-| `memory/MEMORY.md`          | Personal structured memory the chat preloads for the current user.                                      |
-| `skills/<name>/SKILL.md`    | Focused domain guidance the agent pulls in on demand (invoked with `/` slash commands).                 |
-| `agents/<name>.md`          | **Custom agents** — reusable sub-agent profiles the agent can delegate to (invoked with `@` mentions).  |
-| `remote-agents/<name>.json` | A2A manifests for connected remote agents — edited via a form, not raw JSON.                            |
-| `mcp-servers/<name>.json`   | HTTP MCP server definitions that add external tools to the agent.                                       |
-| `jobs/<name>.md`            | Scheduled tasks that run on a cron (see the recurring-jobs docs).                                       |
-| `context/<name>.md`         | Shared reference material: brand guidelines, personas, positioning, product facts, messaging, etc.      |
-| Anything else               | Notes, prompts, config, dataset snippets — any text file.                                               |
-
 ## Overview {#overview}
 
-Every agent-native app has a built-in resource system. Resources are SQL-backed files that persist across sessions and deployments. Unlike code files, resources live in the database — not the filesystem — so they work in serverless environments, edge runtimes, and production deploys without any filesystem dependency.
-
 Resources have three runtime scopes:
 
 - **Personal** — scoped to a single user (their email). Good for preferences, notes, and per-user context.
@@ -63,14 +32,7 @@ Resources have three runtime scopes:
 
 The in-app Workspace panel shows all three scopes. Personal and shared/organization resources are editable there. Workspace-scope resources are read-only in app panels and edited centrally from Dispatch, so every app sees the same canonical files without a sync step.
 
-### Global resources and canonical paths {#global-resources}
-
-Workspace-scope resources are managed from Dispatch's **Resources** page and inherited by apps at runtime — no copy or sync step. Dispatch supports two grant scopes:
-
-- **All apps** — global resources every app in the workspace inherits. Most company, brand, persona, positioning, messaging, and guardrail context should be **All apps**.
-- **Selected apps** — resources granted to specific apps for app-specific context or tools. Use these sparingly.
-
-The path determines how the agent uses a resource. These canonical paths apply across all three scopes (workspace, organization/app, personal):
+The canonical paths that control how the agent uses each resource:
 
 | Runtime resource        | Path                                    | How agents use it                               |
 | ----------------------- | --------------------------------------- | ----------------------------------------------- |
@@ -80,40 +42,7 @@ The path determines how the agent uses a resource. These canonical paths apply a
 | Custom agent profiles   | `agents/<slug>.md`                      | Available as reusable local agent profiles      |
 | Shared HTTP MCP servers | `mcp-servers/<slug>.json`               | Loaded into granted apps' MCP tool registry     |
 
-This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.
-
-## Workspace Panel {#workspace-panel}
-
-The agent panel includes a **Workspace** tab alongside Chat and CLI. This panel lets users browse workspace resources, create/edit/delete personal or organization resources, and view inherited workspace defaults. It displays a tree view of all resources organized by folder path.
-
-Resources can be any text file — Markdown, JSON, YAML, plain text. The panel includes an inline editor for viewing and modifying resource content directly.
-
-The `+` menu in Workspace supports typed creation flows for:
-
-- **Files** — arbitrary resources
-- **Skills** — reusable instruction files under `skills/`
-- **Agents** — custom sub-agent profiles under `agents/*.md`
-- **Scheduled Tasks** — recurring jobs under `jobs/`
-
-Workspace resources appear in three scopes:
-
-- **Workspace** — inherited from Dispatch by every app; read-only in app panels
-- **Organization** — visible across the team/org
-- **Personal** — visible only to the current user
-
-When you open a resource, the editor shows an **Effective context** strip with the precedence stack:
-
-```text
-workspace default -> organization/app override -> personal override
-```
-
-If the same path exists at multiple levels, the later level wins. For example, `instructions/guardrails.md` in Personal overrides the organization version, which overrides the workspace default. Workspace resources are still visible in the stack so users can see what was inherited and why an override is active.
-
-Dispatch shows the same model from the control-plane side. On the **Resources** page, expand a resource and use **Effective in app** to choose an app and optional user email. The preview reports whether the resource is inherited by all apps or selected-only, and which layer is active for that exact path. From an app card's **Context** dialog, expand **Stack** on any resource row to see the same winner/override chain for that app.
-
-When Dispatch approval policy is enabled, creating, updating, or deleting an **All apps** resource queues an approval request instead of applying immediately. The create/edit/delete dialogs show an impact preview before save: whether the change reaches all apps, whether approval is required, and whether the same path is overridden at the organization/app or personal layer.
-
-Click the `?` icon in the Workspace toolbar to jump back to these docs at any time.
+These paths apply across all three scopes — workspace, organization/app, and personal. The later scope wins when the same path exists at multiple levels.
 
 ## Getting Started: a 1-minute walkthrough {#getting-started}
 
@@ -137,63 +66,16 @@ Change how the agent behaves, in 60 seconds.
 - **Scheduled Tasks** (`+` → **Scheduled Task**) — prompts that run on a cron.
 - **Memory** — shared `LEARNINGS.md` and personal `memory/MEMORY.md` keep durable context available across conversations.
 
-## How the Agent Uses Resources {#how-the-agent-uses-resources}
-
-The built-in app agent manages resources with the unified `resources` tool: use `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"`, or `"delete"`. External CLI/code agents can use the equivalent `pnpm action resource-*` commands.
-
-At the start of every conversation, the agent automatically reads:
-
-### AGENTS.md {#agents-md}
-
-An instruction resource seeded by default. The agent loads `AGENTS.md` from workspace, shared/organization, and personal scopes in that order. Edit the workspace version from Dispatch for company-wide defaults, the shared/app version for team or app-specific rules, and the personal version for per-user preferences.
-
-```text
-# Agent Instructions
-
-## Tone
-
-Be concise. Lead with the answer.
-
-## Code style
-
-- Use TypeScript, never JavaScript
-- Prefer named exports
-
-## Skills
-
-| Skill         | Path                            | Description                 |
-| ------------- | ------------------------------- | --------------------------- |
-| data-analysis | `skills/data-analysis/SKILL.md` | BigQuery and data workflows |
-```
-
-### Global Instructions {#global-instructions}
+## Global resources and canonical paths {#global-resources}
 
-Use workspace `AGENTS.md` for company-wide defaults, shared `AGENTS.md` for app/team rules, and personal `AGENTS.md` for per-user preferences. Use files under `instructions/` for separate guardrail documents that should also apply every turn, such as compliance rules, customer-facing tone, escalation policy, or brand voice. These files use the same workspace -> organization/app -> personal precedence.
-
-For example:
-
-```text
-AGENTS.md
-instructions/customer-support-guardrails.md
-instructions/legal-review-policy.md
-```
-
-Both normal chat and integration-triggered agent runs load these instruction resources before responding.
-
-### Reference Resources {#reference-resources}
-
-Put reusable company context under `context/`: personas, positioning, messaging, product facts, customer proof points, brand guidelines, competitive notes, and similar material. The agent sees an index of workspace and shared reference resources and reads the relevant file with the `resources` tool (`action: "read"`) when a task may depend on it. Use `resources` with `action: "effective"` and `path: "context/brand.md"` when you need to see whether a workspace default is overridden by an organization/app or personal resource.
+Workspace-scope resources are managed from Dispatch's **Resources** page and inherited by apps at runtime — no copy or sync step. Dispatch supports two grant scopes:
 
-Examples:
+- **All apps** — global resources every app in the workspace inherits. Most company, brand, persona, positioning, messaging, and guardrail context should be **All apps**.
+- **Selected apps** — resources granted to specific apps for app-specific context or tools. Use these sparingly.
 
-```text
-context/core-positioning.md
-context/buyer-personas.md
-context/brand-guidelines.md
-context/company-facts.md
-```
+The path determines how the agent uses a resource (see the table in [Overview](#overview) above). This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.
 
-For a new workspace, a useful starter pack is:
+A useful starter pack for a new workspace:
 
 ```text
 context/company.md              # what the company does, ICP, products, links
@@ -201,6 +83,7 @@ context/brand.md                # voice, visual identity, spelling, forbidden us
 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
 ```
 
 Keep `context/` files factual and easy to skim. Put rules that must apply every turn in `instructions/guardrails.md`. Use `skills/company-voice/SKILL.md` when the agent should deliberately transform or review copy in the company's voice.
@@ -259,6 +142,80 @@ description: Rewrite or review customer-facing copy using the workspace brand an
 Read `context/brand.md` and `context/messaging.md` before writing. Keep claims grounded in those files, preserve approved terminology, and flag missing proof instead of inventing it.
 ```
 
+## Workspace Panel {#workspace-panel}
+
+The agent panel includes a **Workspace** tab alongside Chat and CLI. This panel lets users browse workspace resources, create/edit/delete personal or organization resources, and view inherited workspace defaults. It displays a tree view of all resources organized by folder path.
+
+Resources can be any text file — Markdown, JSON, YAML, plain text. The panel includes an inline editor for viewing and modifying resource content directly.
+
+The `+` menu in Workspace supports typed creation flows for:
+
+- **Files** — arbitrary resources
+- **Skills** — reusable instruction files under `skills/`
+- **Agents** — custom sub-agent profiles under `agents/*.md`
+- **Scheduled Tasks** — recurring jobs under `jobs/`
+
+When you open a resource, the editor shows an **Effective context** strip with the precedence stack:
+
+```text
+workspace default -> organization/app override -> personal override
+```
+
+If the same path exists at multiple levels, the later level wins. Workspace resources are still visible in the stack so users can see what was inherited and why an override is active.
+
+Dispatch shows the same model from the control-plane side. On the **Resources** page, expand a resource and use **Effective in app** to choose an app and optional user email. From an app card's **Context** dialog, expand **Stack** on any resource row to see the same winner/override chain for that app.
+
+When Dispatch approval policy is enabled, creating, updating, or deleting an **All apps** resource queues an approval request instead of applying immediately. The create/edit/delete dialogs show an impact preview before save.
+
+Click the `?` icon in the Workspace toolbar to jump back to these docs at any time.
+
+## How the Agent Uses Resources {#how-the-agent-uses-resources}
+
+The built-in app agent manages resources with the unified `resources` tool: use `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"`, or `"delete"`. External CLI/code agents can use the equivalent `pnpm action resource-*` commands.
+
+At the start of every conversation, the agent automatically reads:
+
+### AGENTS.md {#agents-md}
+
+An instruction resource seeded by default. The agent loads `AGENTS.md` from workspace, shared/organization, and personal scopes in that order. Edit the workspace version from Dispatch for company-wide defaults, the shared/app version for team or app-specific rules, and the personal version for per-user preferences.
+
+```text
+# Agent Instructions
+
+## Tone
+
+Be concise. Lead with the answer.
+
+## Code style
+
+- Use TypeScript, never JavaScript
+- Prefer named exports
+
+## Skills
+
+| Skill         | Path                            | Description                 |
+| ------------- | ------------------------------- | --------------------------- |
+| data-analysis | `skills/data-analysis/SKILL.md` | BigQuery and data workflows |
+```
+
+### Global Instructions {#global-instructions}
+
+Use workspace `AGENTS.md` for company-wide defaults, shared `AGENTS.md` for app/team rules, and personal `AGENTS.md` for per-user preferences. Use files under `instructions/` for separate guardrail documents that should also apply every turn, such as compliance rules, customer-facing tone, escalation policy, or brand voice. These files use the same workspace -> organization/app -> personal precedence.
+
+For example:
+
+```text
+AGENTS.md
+instructions/customer-support-guardrails.md
+instructions/legal-review-policy.md
+```
+
+Both normal chat and integration-triggered agent runs load these instruction resources before responding.
+
+### Reference Resources {#reference-resources}
+
+Put reusable company context under `context/`: personas, positioning, messaging, product facts, customer proof points, brand guidelines, competitive notes, and similar material. The agent sees an index of workspace and shared reference resources and reads the relevant file with the `resources` tool (`action: "read"`) when a task may depend on it. Use `resources` with `action: "effective"` and `path: "context/brand.md"` when you need to see whether a workspace default is overridden by an organization/app or personal resource.
+
 ### Memory {#memory}
 
 The workspace has two current memory surfaces:
@@ -290,42 +247,19 @@ The resource system also seeds a personal `LEARNINGS.md` for compatibility with
 
 **Where it fits.**
 
-| Surface            | Scope              | Written by                           | Read when                                                                                                                                           |
-| ------------------ | ------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENTS.md`        | Shared             | Humans / agent on request            | Every turn                                                                                                                                          |
-| `LEARNINGS.md`     | Shared             | Humans / agent on request            | Every turn (Shared copy only — a personal `LEARNINGS.md` is seeded for back-compat but isn't preloaded; put personal context in `memory/MEMORY.md`) |
-| `memory/MEMORY.md` | Personal           | Agent / humans                       | Every turn                                                                                                                                          |
-| `instructions/…`   | Shared             | Humans / agent on request            | Every turn                                                                                                                                          |
-| `skills/…`         | Shared             | Humans / agent on request            | On demand (`/slash` command)                                                                                                                        |
-| `context/…`        | Shared             | Humans / agent on request            | Indexed every turn, read when relevant                                                                                                              |
-| `mcp-servers/…`    | Workspace / shared | Humans via Dispatch or app workspace | MCP config refresh                                                                                                                                  |
-
-Users can edit these memory files directly in the Workspace tab — they're regular resources. Delete lines the agent got wrong, keep personal preferences in `memory/MEMORY.md`, or promote team-wide rules into `AGENTS.md`.
+| Surface            | Scope              | Written by                           | Read when                              |
+| ------------------ | ------------------ | ------------------------------------ | -------------------------------------- |
+| `AGENTS.md`        | Shared             | Humans / agent on request            | Every turn                             |
+| `LEARNINGS.md`     | Shared             | Humans / agent on request            | Every turn (shared copy only)          |
+| `memory/MEMORY.md` | Personal           | Agent / humans                       | Every turn                             |
+| `instructions/…`   | Shared             | Humans / agent on request            | Every turn                             |
+| `skills/…`         | Shared             | Humans / agent on request            | On demand (`/slash` command)           |
+| `context/…`        | Shared             | Humans / agent on request            | Indexed every turn, read when relevant |
+| `mcp-servers/…`    | Workspace / shared | Humans via Dispatch or app workspace | MCP config refresh                     |
 
-## Workspace Connections {#workspace-connections}
+> A personal `LEARNINGS.md` is seeded for back-compat with older workspaces, but the chat preload path reads the shared copy. Put personal context in `memory/MEMORY.md` instead.
 
-Workspace Connections are the reusable integration framework primitive for apps
-that need the same third-party account. A connection records provider identity,
-account labels, status, scopes, app grants, and credential references in
-portable SQL. Secrets stay in the scoped credential store; connection records
-should only point at credential keys such as `SLACK_BOT_TOKEN` or
-`GITHUB_TOKEN`.
-
-This is the foundation for “connect once, use everywhere”: Brain can ingest
-approved repositories, Analytics can analyze the same provider later, and
-Dispatch can remain the control plane for sharing credentials and policy. The
-initial API lives in `@agent-native/core/workspace-connections` and is scoped by
-the active request user/org.
-
-The boundary is deliberate: reusable connections own provider identity and
-grants; app-local source config still belongs to the app. Brain decides which
-channels, repositories, captures, review gates, and citations are allowed.
-Analytics decides which source is authoritative for a metric and stores the
-dashboard, dictionary, and analysis context.
-
-See [Workspace Connections](/docs/workspace-connections) for the reusable
-connector pattern, app grant/readiness APIs, and concrete Slack, HubSpot, and
-GitHub examples.
+Users can edit these memory files directly in the Workspace tab — they're regular resources. Delete lines the agent got wrong, keep personal preferences in `memory/MEMORY.md`, or promote team-wide rules into `AGENTS.md`.
 
 ## Skills {#skills}
 
@@ -340,18 +274,34 @@ There are two ways to add skills:
 1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill/SKILL.md`. This works in both Code mode and App mode.
 2. **Via code (Code mode only)** — Add a Markdown file to `.agents/skills/` in your project. These are available when the app runs in Code mode.
 
-## Custom Agents {#custom-agents}
+### Skill Format {#skill-format}
+
+Skills are Markdown files with optional YAML frontmatter for metadata:
+
+```markdown
+---
+name: data-analysis
+description: BigQuery queries, data transforms, and visualization
+---
 
-Custom agents are reusable local sub-agent profiles stored as Markdown resources under `agents/*.md`.
+# Data Analysis
 
-Use them when you want a focused delegate with its own:
+## When to use
 
-- name
-- description
-- model preference
-- instruction set
+Use this skill when the user asks about data, queries, or analytics.
 
-Unlike skills, custom agents are not passive guidance. They are operational personas the main agent can invoke through `@` mentions or by selecting them during sub-agent spawning.
+## Rules
+
+- Always validate SQL before executing
+- Prefer CTEs over subqueries
+- Include LIMIT on exploratory queries
+```
+
+## Custom Agents {#custom-agents}
+
+Custom agents are reusable local sub-agent profiles stored as Markdown resources under `agents/*.md`. Agent-teams.md and agent-mentions.md use `/docs/workspace#custom-agents` as the canonical reference for this pattern.
+
+Use them when you want a focused delegate with its own name, description, model preference, and instruction set. Unlike skills, custom agents are not passive guidance — they are operational personas the main agent can invoke through `@` mentions or by selecting them during sub-agent spawning.
 
 ### Agent format {#agent-format}
 
@@ -393,36 +343,6 @@ There are two agent types in Workspace:
 
 Use custom agents for delegation within one app. Use connected agents when you need to call another app over A2A.
 
-### Skill Format {#skill-format}
-
-Skills are Markdown files with optional YAML frontmatter for metadata:
-
-```markdown
----
-name: data-analysis
-description: BigQuery queries, data transforms, and visualization
----
-
-# Data Analysis
-
-## When to use
-
-Use this skill when the user asks about data, queries, or analytics.
-
-## Rules
-
-- Always validate SQL before executing
-- Prefer CTEs over subqueries
-- Include LIMIT on exploratory queries
-
-## Patterns
-
-    -- Standard BigQuery date filter
-    WHERE DATE(created_at) BETWEEN @start_date AND @end_date
-```
-
-> Skill bodies can embed fenced code blocks in any language — shown above as indented code to keep this outer example readable, but you'd normally use a language-tagged fence in your real skill file.
-
 ## @ Tagging {#at-tagging}
 
 Type `@` in the chat input to reference workspace items. A dropdown appears at the cursor showing matching agents and files. Use arrow keys to navigate and Enter to select. The selected item appears as an inline chip in the input.
@@ -440,7 +360,7 @@ What shows up depends on the mode:
 
 ## / Slash Commands {#slash-commands}
 
-Type `/` at the start of a line to invoke a skill. A dropdown shows available skills with their names and descriptions. Selecting a skill adds it as an inline chip, and its content is included as context when the message is sent when the backend can resolve it; otherwise the agent receives the exact skill path and reads it with the appropriate resource or file tool.
+Type `/` at the start of a line to invoke a skill. A dropdown shows available skills with their names and descriptions. Selecting a skill adds it as an inline chip, and its content is included as context when the message is sent.
 
 What shows up depends on the mode:
 
@@ -461,6 +381,12 @@ The resource system works identically in both modes. The difference is what addi
 | Workspace panel    | Full access                                                             | Full access                                            |
 | AGENTS.md / memory | Available                                                               | Available                                              |
 
+## Workspace Connections {#workspace-connections}
+
+Workspace Connections let apps share the same provider account (Slack, GitHub, HubSpot, etc.) without duplicating credentials. A connection records provider identity, account labels, status, scopes, app grants, and credential references in SQL. Secrets stay in the credential store; connections only point at credential key names such as `SLACK_BOT_TOKEN`.
+
+See [Workspace Connections](/docs/workspace-connections) for the quickstart, connection/grant/credentialRef API, and concrete Slack, HubSpot, and GitHub examples.
+
 ## Resource API {#resource-api}
 
 Resources can be managed from server code, actions, or the REST API.

package/docs/content/writing-agent-instructions.md

@@ -117,6 +117,22 @@ App instructions should make honesty and verification the default behavior:
 
 Put these as core rules in `AGENTS.md` so they apply to every turn.
 
+## The four surfaces the agent sees {#four-surfaces}
+
+Every piece of guidance you author lands in one of four surfaces. Knowing which surface to use prevents duplication and misplaced detail:
+
+| Surface                     | Who writes it             | When it's loaded                                       | What belongs there                                          |
+| --------------------------- | ------------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
+| `AGENTS.md` instructions    | You (developer)           | Every turn, as orientation                             | Purpose, core rules, state keys, action index, skills index |
+| Skills (`SKILL.md`)         | You (developer)           | On demand when the agent decides the skill is relevant | Step-by-step how-to for a specific pattern, do/don't lists  |
+| Action descriptions (tools) | You (developer)           | Every turn, as the tool list                           | What the action does, what it returns, parameter semantics  |
+| `application_state` context | Your UI code (at runtime) | Every turn, as live app state                          | Current navigation, selection, focused object, URL          |
+
+**Quick diagnosis:**
+
+- "The agent keeps asking which record to act on even when one is open" → fix: write the current item ID into `application_state` (`navigation` key) from your UI. That's an `application_state` gap, not a skill gap.
+- "The agent calls the wrong action or misuses a parameter" → fix: improve the action's `description` and `.describe()` on the parameter. That's a tool description fix, not a skill.
+
 ## What goes where {#what-goes-where}
 
 - **AGENTS.md** — applies to the whole app, every turn: purpose, core rules, state keys, action index, skills index.
@@ -127,4 +143,4 @@ Put these as core rules in `AGENTS.md` so they apply to every turn.
 
 - [Skills Guide](/docs/skills-guide) — the skill file format, framework skills, and app-backed skills.
 - [Creating Templates](/docs/creating-templates) — how `AGENTS.md` and skills fit into a shippable template.
-- [Adding a Feature](/docs/adding-a-feature) — the four-area model every feature must satisfy.
+- [The four-area checklist](/docs/key-concepts#four-area-checklist) — the four-area model every feature must satisfy.