@agent-native/core 0.15.13 → 0.16.0

package/docs/content/workspace.md

@@ -32,33 +32,39 @@ The **Workspace** tab in the agent sidebar is where you and the agent share pers
 - 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 `LEARNINGS.md`, and personal structured memory at `memory/MEMORY.md`.
+- 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.          |
-| `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>.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.                           |
-| `jobs/<name>.md`            | Scheduled tasks that run on a cron (see the recurring-jobs docs).                                      |
-| Anything else               | Notes, prompts, config, dataset snippets — any text file.                                              |
+| 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.                            |
+| `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 two scopes:
+Resources have three runtime scopes:
 
 - **Personal** — scoped to a single user (their email). Good for preferences, notes, and per-user context.
-- **Shared** — visible to all users. Good for team instructions, skills, and shared config.
+- **Shared / organization** — visible to all users in the app or organization. Good for app/team instructions, skills, and shared config.
+- **Workspace** — inherited global defaults managed from Dispatch Resources. Good for company facts, positioning, brand guidelines, global guardrails, and workspace-wide skills. Apps read these at runtime; they are not copied into each app.
+
+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.
 
 ## Workspace Panel {#workspace-panel}
 
-The agent panel includes a **Workspace** tab alongside Chat and CLI. This panel lets users browse, create, edit, and delete workspace resources. It displays a tree view of all resources organized by folder path.
+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.
 
@@ -69,10 +75,23 @@ The `+` menu in Workspace supports typed creation flows for:
 - **Agents** — custom sub-agent profiles under `agents/*.md`
 - **Scheduled Tasks** — recurring jobs under `jobs/`
 
-Workspace resources come in two scopes:
+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
-- **Shared** — visible across the team/org
+
+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.
 
@@ -100,15 +119,15 @@ Change how the agent behaves, in 60 seconds.
 
 ## How the Agent Uses Resources {#how-the-agent-uses-resources}
 
-The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-write`, and `resource-delete`. These are available in both dev and production modes.
+The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-effective`, `resource-write`, and `resource-delete`. These are available in both dev and production modes.
 
 At the start of every conversation, the agent automatically reads:
 
 ### AGENTS.md {#agents-md}
 
-A shared resource seeded by default. It contains custom instructions, preferences, and skill references. Edit this to change how the agent behaves for all users — tone, rules, domain context, and which skills to use.
+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.
 
-```markdown
+```text
 # Agent Instructions
 
 ## Tone
@@ -122,9 +141,102 @@ Be concise. Lead with the answer.
 
 ## Skills
 
-| Skill         | Path                      | Description                 |
-| ------------- | ------------------------- | --------------------------- |
-| data-analysis | `skills/data-analysis.md` | BigQuery and data workflows |
+| 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 `resource-read` when a task may depend on it. Use `resource-effective --path "context/brand.md"` when you need to see whether a workspace default is overridden by an organization/app or personal resource.
+
+Examples:
+
+```text
+context/core-positioning.md
+context/buyer-personas.md
+context/brand-guidelines.md
+context/company-facts.md
+```
+
+For a new workspace, a useful starter pack is:
+
+```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
+```
+
+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.
+
+To override a global default for one app or team, create a shared/organization resource in that app with the same path. To override it for one person, create a personal resource with the same path. Do not copy the workspace file into every app; the runtime resolves the stack on read:
+
+```text
+workspace context/brand.md
+-> shared/app context/brand.md
+-> personal context/brand.md
+```
+
+Example contents:
+
+```text
+<!-- context/company.md -->
+
+# Company
+
+- Company: Example Co
+- Product: Agent-native workspace for internal teams
+- ICP: Operations, support, and GTM teams managing many small tools
+- Canonical links: https://example.com, https://docs.example.com
+
+<!-- context/brand.md -->
+
+# Brand
+
+- Voice: direct, warm, concrete
+- Use: "workspace", "agent", "team"
+- Avoid: unsupported superlatives and vague AI claims
+
+<!-- context/messaging.md -->
+
+# Messaging
+
+- Positioning: one control plane for every app agent
+- Value props: shared context, shared credentials, cross-app delegation
+- Proof points: fewer duplicated Slack bots, one vault, one policy surface
+
+<!-- instructions/guardrails.md -->
+
+# Guardrails
+
+- Do not invent customer names, metrics, or legal claims.
+- Ask for approval before changing shared instructions or All-app resources.
+- Escalate security, billing, and data-loss concerns to an admin.
+
+<!-- skills/company-voice/SKILL.md -->
+
+---
+name: company-voice
+description: Rewrite or review customer-facing copy using the workspace brand and messaging resources.
+---
+
+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.
 ```
 
 ### Memory {#memory}
@@ -158,18 +270,38 @@ 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                   |
-| `memory/MEMORY.md` | Personal | Agent / humans            | Every turn                   |
-| `skills/…`         | Shared   | Humans / agent on request | On demand (`/slash` command) |
+| Surface            | Scope    | Written by                | Read when                              |
+| ------------------ | -------- | ------------------------- | -------------------------------------- |
+| `AGENTS.md`        | Shared   | Humans / agent on request | Every turn                             |
+| `LEARNINGS.md`     | Shared   | Humans / agent on request | Every turn                             |
+| `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 |
 
 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`.
 
+## Workspace Connections {#workspace-connections}
+
+Workspace Connections are the reusable integration metadata layer for apps that
+need the same third-party account. A connection records the provider, account
+label, status, scopes, allowed app slugs, 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.
+
+See [Workspace Connections](/docs/workspace-connections) for the reusable
+connector pattern, app grant/readiness APIs, and concrete Slack, HubSpot, and
+GitHub examples.
+
 ## Skills {#skills}
 
-Skills are Markdown resource files that give the agent deep domain knowledge for specific tasks. They live under the `skills/` path prefix in resources (e.g. `skills/data-analysis.md`, `skills/code-review.md`).
+Skills are Markdown resource files that give the agent deep domain knowledge for specific tasks. They live under the `skills/` path prefix in resources, preferably as `skills/<name>/SKILL.md` (e.g. `skills/data-analysis/SKILL.md`, `skills/code-review/SKILL.md`). Flat `skills/<name>.md` files still work for compatibility.
 
 When the agent encounters a task that matches a skill, it reads the skill file and follows its guidance. Skills referenced in `AGENTS.md` are discovered automatically.
 
@@ -177,7 +309,7 @@ When the agent encounters a task that matches a skill, it reads the skill file a
 
 There are two ways to add skills:
 
-1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill.md`. This works in both dev and production.
+1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill/SKILL.md`. This works in both dev and production.
 2. **Via code (dev only)** — Add a Markdown file to `.agents/skills/` in your project. These are available when the app runs in dev mode.
 
 ## Custom Agents {#custom-agents}
@@ -309,15 +441,17 @@ Resources can be managed from server code, actions, or the REST API.
 
 REST endpoints mounted automatically:
 
-| Method   | Endpoint                                  | Description               |
-| -------- | ----------------------------------------- | ------------------------- |
-| `GET`    | `/_agent-native/resources?scope=all`      | List resources            |
-| `GET`    | `/_agent-native/resources/tree?scope=all` | Get folder tree           |
-| `POST`   | `/_agent-native/resources`                | Create a resource         |
-| `GET`    | `/_agent-native/resources/:id`            | Get resource with content |
-| `PUT`    | `/_agent-native/resources/:id`            | Update a resource         |
-| `DELETE` | `/_agent-native/resources/:id`            | Delete a resource         |
-| `POST`   | `/_agent-native/resources/upload`         | Upload a file as resource |
+| Method   | Endpoint                                      | Description                          |
+| -------- | --------------------------------------------- | ------------------------------------ |
+| `GET`    | `/_agent-native/resources?scope=all`          | List resources                       |
+| `GET`    | `/_agent-native/resources?scope=workspace`    | List inherited workspace resources   |
+| `GET`    | `/_agent-native/resources/tree?scope=all`     | Get folder tree                      |
+| `GET`    | `/_agent-native/resources/effective?path=...` | Show the effective inheritance stack |
+| `POST`   | `/_agent-native/resources`                    | Create a resource                    |
+| `GET`    | `/_agent-native/resources/:id`                | Get resource with content            |
+| `PUT`    | `/_agent-native/resources/:id`                | Update a resource                    |
+| `DELETE` | `/_agent-native/resources/:id`                | Delete a resource                    |
+| `POST`   | `/_agent-native/resources/upload`             | Upload a file as resource            |
 
 ### Action API {#script-api}
 
@@ -328,7 +462,13 @@ The agent uses these built-in actions. You can also call them from your own acti
 pnpm action resource-list --scope all
 
 # Read a resource
-pnpm action resource-read --path "skills/my-skill.md"
+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..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.15.13",
+  "version": "0.16.0",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -76,6 +76,9 @@
     "./mcp-client": "./dist/mcp-client/index.js",
     "./tracking": "./dist/tracking/index.js",
     "./usage": "./dist/usage/store.js",
+    "./connections": "./dist/connections/index.js",
+    "./code-agents": "./dist/code-agents/index.js",
+    "./workspace-connections": "./dist/workspace-connections/index.js",
     "./notifications": "./dist/notifications/index.js",
     "./client/notifications": "./dist/client/notifications/index.js",
     "./progress": "./dist/progress/index.js",
@@ -99,7 +102,7 @@
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest --run src",
-    "prepack": "cp ../../README.md ./README.md",
+    "prepack": "npm run build && cp ../../README.md ./README.md",
     "prepublishOnly": "npm run build",
     "release": "npm version patch && npm publish --access public"
   },
@@ -292,7 +295,9 @@
     "express": "^5.2.1",
     "firebase-admin": "^13.0.0",
     "node-pty": "^1.1.0",
+    "playwright": "^1.60.0",
     "react": "^19.2.5",
+    "react-dom": "19.2.5",
     "react-router": "^7.13.1",
     "tailwindcss": "catalog:",
     "typescript": "^6.0.3",

package/src/templates/default/AGENTS.md

@@ -25,10 +25,10 @@ Use `getSession(event)` server-side and `useSession()` client-side.
 
 Resources are SQL-backed persistent files for notes, learnings, and context.
 
-**At the start of every conversation, read these resources (both personal and shared scopes):**
+**At the start of every conversation, read these resources (workspace, shared, and personal scopes as relevant):**
 
-1. **`AGENTS.md`** -- user-specific context. Read both `--scope personal` and `--scope shared`.
-2. **`LEARNINGS.md`** -- user preferences, corrections, and patterns. Read both scopes.
+1. **`AGENTS.md`** -- inherited workspace defaults, app/team instructions, and user-specific context.
+2. **`LEARNINGS.md`** -- user preferences, corrections, and patterns. Read personal and shared scopes.
 
 **Update `LEARNINGS.md` when you learn something important.**
 

package/src/templates/workspace-core/AGENTS.md

@@ -27,6 +27,13 @@ agent should know.
   notes, scripts, task plans, or intermediate outputs, but should promote them
   to normal workspace visibility only when the user explicitly asks to keep or
   manage the file.
+- Runtime-editable global resources can be managed from Dispatch Resources.
+  Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
+  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
+  personas/positioning/messaging/company facts/brand guidelines, and
+  `agents/<slug>.md` for custom agent profiles. Scope them to All apps when
+  every workspace app should inherit them. All-app resources are inherited at
+  runtime; do not copy or sync them into individual apps.
 
 ## Adding Apps
 

package/src/templates/workspace-root/AGENTS.md

@@ -24,6 +24,13 @@ coding agents can discover the same workspace-wide guidance from the root.
   manage the file.
 - Durable instructions, skills, jobs, memories, custom agents, and files the
   user explicitly asked to save belong in normal workspace visibility.
+- Runtime-editable global resources are managed from Dispatch Resources. Use
+  `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
+  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
+  personas/positioning/messaging/company facts/brand guidelines, and
+  `agents/<slug>.md` for custom agent profiles.
+- Set Dispatch resources to All apps when every workspace app should inherit
+  them. Use selected-app grants only for resources that should not be global.
 
 ## Workspace Scope
 

package/src/templates/workspace-root/README.md

@@ -36,6 +36,28 @@ the shared package (`@{{APP_NAME}}/shared`).
 The workspace root also links `.agents/skills` to the shared package so coding
 agents launched from the root can discover the same workspace-wide skills.
 
+Runtime-editable global resources live in Dispatch, not in `packages/shared`.
+Use Dispatch **Resources** for company context and guardrails that admins should
+change without a code deploy:
+
+- `AGENTS.md` or `instructions/<slug>.md` for instructions every app agent loads
+- `skills/<slug>/SKILL.md` for workspace skills
+- `context/<slug>.md` for personas, positioning, messaging, company facts, and brand guidelines
+- `agents/<slug>.md` for reusable custom agent profiles
+
+Set those resources to **All apps** when every workspace app should receive
+them; use selected-app grants for app-specific packs.
+
+Starter global resources:
+
+```text
+context/company.md              # company overview, ICP, products, canonical links
+context/brand.md                # brand voice, visual identity, spelling, terms to avoid
+context/messaging.md            # positioning, value props, proof points, objections
+instructions/guardrails.md      # compliance, escalation, and approval rules
+skills/company-voice/SKILL.md   # copywriting/review guidance for customer-facing work
+```
+
 ## Getting started
 
 ```bash
@@ -55,6 +77,9 @@ localhost or dev ports because the active gateway origin owns the port.
 Dispatch vault keys are workspace-wide by default: every saved vault key is
 available to every workspace app and can be synced from Dispatch. Switch the
 Vault page to manual access only when you need explicit per-app key grants.
+Dispatch resources are inherited rather than synced: All-app resources live
+once at workspace scope and every app agent reads them at runtime. Use selected
+resource grants only for genuinely app-specific context.
 
 ## Workspace org identity