@agent-native/core 0.63.2 → 0.63.3

package/docs/content/workspace-connections.md

@@ -16,6 +16,13 @@ Workspace connections are the framework primitive for reusable integration metad
 - **credentialRef** — a pointer to a vault secret (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`). The connection says where the token lives; the vault holds the value.
 - **Readiness** — the combined status an app sees: `connected` (granted + credentials present), `needs_grant`, `needs_credentials`, `needs_attention`, or `not_configured`.
 
+```an-diagram title="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+{
+  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, status, scopes, config &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
+  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+}
+```
+
 ### Worked example: Slack
 
 Connect Slack once and grant it to Brain and Analytics:
@@ -51,6 +58,41 @@ await upsertWorkspaceConnectionGrant({
 });
 ```
 
+```an-schema title="The connection model" summary="A connection records safe provider metadata and credentialRefs (pointers, not secrets). Each grant unlocks one app — one connection, many grants."
+{
+  "entities": [
+    {
+      "id": "conn",
+      "name": "workspace_connections",
+      "note": "Named provider account. Never stores secret values.",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "stable provider id, e.g. slack" },
+        { "name": "label", "type": "string" },
+        { "name": "accountId", "type": "string", "nullable": true },
+        { "name": "accountLabel", "type": "string", "nullable": true },
+        { "name": "status", "type": "string", "note": "e.g. connected" },
+        { "name": "scopes", "type": "string[]", "nullable": true },
+        { "name": "config", "type": "json", "nullable": true, "note": "safe, non-secret config" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "Per-app permission to use a connection.",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g. brain, analytics" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "conn", "to": "grant", "kind": "1-n", "label": "grants apps" }
+  ]
+}
+```
+
 ### What apps call
 
 Before asking a user to paste a new key, check readiness first:
@@ -164,6 +206,13 @@ The credential vault answers: "Where is the secret stored, who can access it, an
 
 Workspace connection provider metadata answers: "Which provider is this, what can it do, what credential keys might it need, and which templates should offer it?"
 
+```an-diagram title="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">App action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">never returned to the agent or UI</small></div></div></div>",
+  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 Use both together:
 
 1. Dispatch (or another workspace setup flow) creates the underlying vault secret or OAuth credential reference.

package/docs/content/workspace-management.md

@@ -9,6 +9,13 @@ description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime
 
 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.
 
+```an-diagram title="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
+  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+}
+```
+
 ## Branching
 
 ### Feature Branches
@@ -38,6 +45,19 @@ Not everyone who needs to make changes is comfortable with git. [Builder.io](htt
 
 ## Code Ownership
 
+Code governance is configured by a handful of files at the repo root:
+
+```an-file-tree title="Governance config in the repo"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
+    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
+    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+  ]
+}
+```
+
 GitHub's CODEOWNERS file auto-assigns reviewers to PRs based on which files changed. Create `.github/CODEOWNERS` at the repo root:
 
 ```
@@ -96,6 +116,10 @@ Then add the [actions/labeler](https://github.com/actions/labeler) action — se
 
 Agent-native workspaces often have multiple AI agents working on the same branch simultaneously. This is by design — the agents share a branch and push independently.
 
+```an-callout
+{ "tone": "warning", "body": "**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken." }
+```
+
 When reviewing PRs in this environment:
 
 - **Don't revert changes you didn't make** unless they're clearly broken

package/docs/content/workspace.md

@@ -11,6 +11,13 @@ Every agent-native app ships with a **workspace**: the customization layer that
 
 The twist: **it's SQL rows, not filesystem files.** Each user gets their own workspace stored in the database. There's no dev-box to spin up, no container per user, no files to mount. A multi-tenant SaaS can give every user a fully-customizable agent for essentially free, because all of it is rows — personal memory, personal MCP servers, personal skills, personal sub-agents — and the shared codebase hosts all of them at once.
 
+```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}"
+}
+```
+
 | Claude Code / Codex              | Agent-native workspace                             |
 | -------------------------------- | -------------------------------------------------- |
 | Files on your local disk         | Rows in a shared SQL database                      |
@@ -44,6 +51,13 @@ The canonical paths that control how the agent uses each resource:
 
 These paths apply across all three scopes — workspace, organization/app, and personal. The later scope wins when the same path exists at multiple levels.
 
+```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}"
+}
+```
+
 ## Getting Started: a 1-minute walkthrough {#getting-started}
 
 Change how the agent behaves, in 60 seconds.
@@ -59,6 +73,10 @@ Change how the agent behaves, in 60 seconds.
 
 3. Save, switch to **Chat**, ask anything — the agent follows the new rule immediately.
 
+```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." }
+```
+
 **Next steps, when you want them:**
 
 - **Skills** (`+` → **Skill**) — focused how-to files invoked in chat with `/skill-name`.
@@ -163,6 +181,26 @@ The resource system also seeds a personal `LEARNINGS.md` for compatibility with
 
 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`.
 
+Every one of these surfaces — `AGENTS.md`, skills, memory, custom agents, MCP servers — is the same underlying resource shape: a `path` + `scope` + `content`, addressed and resolved the same way.
+
+```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 are Markdown resource files under the `skills/` path (preferably `skills/<name>/SKILL.md`) that give the agent on-demand domain knowledge, invoked in chat with `/skill-name`. Add them from the Workspace tab or, in Code mode, from `.agents/skills/`.
@@ -179,25 +217,18 @@ Use them when you want a focused delegate with its own name, description, model
 
 Custom agents use YAML frontmatter plus Markdown instructions:
 
-```markdown
----
-name: Design
-description: >-
-  Reviews layouts, interaction patterns, and product UX decisions.
-model: inherit
-tools: inherit
-delegate-default: false
----
-
-# Role
-
-You are a focused design agent.
-
-## Responsibilities
-
-- Review layouts and interaction flows
-- Suggest stronger visual direction
-- Be concise and opinionated
+```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." }
+  ]
+}
 ```
 
 Recommended conventions:

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

@@ -7,6 +7,13 @@ description: "How to write great agent instructions for an agent-native app or t
 
 The agent's behavior in an agent-native app is only as good as the instructions you give it. Three surfaces carry that guidance: `AGENTS.md` (the map), skills (the deep dives), and action/tool descriptions (how the agent picks the right tool). Write each one for fast retrieval, not for prose.
 
+```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}"
+}
+```
+
 ## Keep AGENTS.md small and skimmable {#small-agents-md}
 
 `AGENTS.md` is loaded as orientation. It should be the smallest thing that lets the agent act correctly, with everything deep pushed into skills. Aim for these sections and little else:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.63.2",
+  "version": "0.63.3",
   "type": "module",
   "engines": {
     "node": ">=22"