@agent-native/core 0.14.8 → 0.15.1

package/dist/templates/workspace-core/.agents/skills/create-skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: create-skill
+description: >-
+  How to create new skills for an agent-native app. Use when adding a new
+  skill, documenting a pattern the agent should follow, or creating reusable
+  guidance for the agent.
+---
+
+# Create a Skill
+
+## When to Use
+
+Create a new skill when:
+
+- There's a pattern the agent should follow repeatedly
+- A workflow needs step-by-step guidance
+- You want to scaffold files from a template
+
+Don't create a skill when:
+
+- The guidance already exists in another skill (extend it instead)
+- You're documenting something the agent already knows (e.g., how to write TypeScript)
+- The guidance is a one-off — put it in `AGENTS.md` or `learnings.md` instead
+
+## 5-Question Interview
+
+Before writing the skill, answer these:
+
+1. **What should this skill enable?** — The core purpose in one sentence.
+2. **Which agent-native rule does it serve?** — Rule 1 (data in SQL), Rule 2 (delegate to agent), Rule 3 (scripts), Rule 4 (polling sync), Rule 5 (self-modify), Rule 6 (app-state in SQL), or "utility."
+3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
+4. **Does it involve context awareness?** — Does the agent need to know what the user is looking at to use this skill? If yes, the skill should reference the `navigation` app-state key and the `view-screen` script pattern. See the **context-awareness** skill.
+5. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
+6. **Does it need supporting files?** — References (read-only context) or none. Keep it minimal.
+
+## Skill Types and Templates
+
+### Pattern (architectural rule)
+
+For documenting how things should be done:
+
+```markdown
+---
+name: my-pattern
+description: >-
+  [Under 40 words. When should this trigger?]
+---
+
+# [Pattern Name]
+
+## Rule
+
+[One sentence: what must be true]
+
+## Why
+
+[Why this rule exists]
+
+## How
+
+[How to follow it, with code examples]
+
+## Don't
+
+[Common violations]
+
+## Related Skills
+
+[Which skills compose with this one]
+```
+
+### Workflow (step-by-step)
+
+For multi-step implementation tasks:
+
+```markdown
+---
+name: my-workflow
+description: >-
+  [Under 40 words. When should this trigger?]
+---
+
+# [Workflow Name]
+
+## Prerequisites
+
+[What must be in place first]
+
+## Steps
+
+[Numbered steps with code examples]
+
+## Verification
+
+[How to confirm it worked]
+
+## Troubleshooting
+
+[Common issues and fixes]
+
+## Related Skills
+```
+
+### Generator (scaffolding)
+
+For creating files from templates:
+
+```markdown
+---
+name: my-generator
+description: >-
+  [Under 40 words. When should this trigger?]
+---
+
+# [Generator Name]
+
+## Usage
+
+[How to invoke — what args/inputs are needed]
+
+## What Gets Created
+
+[List of files and their purpose]
+
+## Template
+
+[The template content with placeholders]
+
+## After Generation
+
+[What to do next — wire up SSE, add routes, etc.]
+
+## Related Skills
+```
+
+## Naming Conventions
+
+- Hyphen-case only: `[a-z0-9-]`, max 64 characters
+- Pattern skills: descriptive names (`storing-data`, `delegate-to-agent`)
+- Workflow/generator skills: verb-noun (`create-script`, `capture-learnings`)
+
+## Tips
+
+- **Keep descriptions under 40 words** — They're loaded into context on every conversation.
+- **Keep SKILL.md under 500 lines** — Move detailed content to `references/` files.
+- **Use standard markdown headings** — No XML tags or custom formats.
+
+## Anti-Patterns
+
+- **Inline LLM calls** — Skills must not call LLMs directly (violates Rule 2)
+- **Database patterns** — Skills must not introduce databases (violates Rule 1)
+- **Ignoring db sync** — If a skill creates data, mention wiring up `useDbSync`
+- **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
+- **Pure documentation** — Skills should guide action, not just explain concepts
+
+## File Structure
+
+```
+.agents/skills/my-skill/
+├── SKILL.md              # Main skill (required)
+└── references/           # Optional supporting context
+    └── detailed-guide.md
+```
+
+## Related Skills
+
+- **capture-learnings** — When a learning graduates to reusable guidance, create a skill
+- **self-modifying-code** — The agent can create new skills (Tier 2 modification)

package/dist/templates/workspace-core/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: delegate-to-agent
+description: >-
+  How to delegate all AI work to the agent chat. Use when delegating AI work
+  from UI or scripts to the agent, when a user asks for agent behavior or
+  LLM-powered features, when tempted to add inline LLM calls, or when sending
+  messages to the agent from application code.
+---
+
+# Delegate All AI to the Agent
+
+## Rule
+
+The UI and server never call an LLM directly. All AI work is delegated to the agent through the chat bridge.
+
+## Why
+
+The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
+
+## How
+
+**From the UI (client):**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+
+sendToAgentChat({
+  message: "Generate a summary of this document",
+  context: documentContent, // optional hidden context (not shown in chat UI)
+  submit: true, // auto-submit to the agent
+});
+```
+
+**From scripts (Node):**
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+agentChat.submit("Process the uploaded images and create thumbnails");
+```
+
+**From the UI, detecting when agent is done:**
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core";
+
+function MyComponent() {
+  const isGenerating = useAgentChatGenerating();
+  // Show loading state while agent is working
+}
+```
+
+## `submit` vs Prefill
+
+The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
+
+| `submit` value | Behavior                                | Use when                                                                            |
+| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
+| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
+
+```ts
+// Auto-submit: routine operation
+sendToAgentChat({ message: "Update the project summary", submit: true });
+
+// Prefill: let user review before sending
+sendToAgentChat({
+  message: "Delete all projects older than 30 days",
+  submit: false,
+});
+```
+
+## Capture user input first when generating from a prompt
+
+Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+
+**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+
+```tsx
+<Button
+  onClick={() =>
+    sendToAgentChat({ message: "make a design", submit: true })
+  }
+>
+  New Design
+</Button>
+```
+
+**Good** — Popover anchored to the button captures the prompt, then submits it:
+
+```tsx
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>New Design</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-96">
+    <Textarea
+      autoFocus
+      value={prompt}
+      onChange={(e) => setPrompt(e.target.value)}
+      placeholder="What do you want to design?"
+    />
+    <Button
+      onClick={() => {
+        sendToAgentChat({ message: prompt, submit: true });
+        setOpen(false);
+        setPrompt("");
+      }}
+    >
+      Create
+    </Button>
+  </PopoverContent>
+</Popover>
+```
+
+**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
+
+**Auto-submit without input is fine when intent is unambiguous:**
+
+- "Try to fix" on a tool error — submits the error details with a clear fix instruction
+- "Retry the last operation" after a transient failure
+- Single-purpose buttons where there is nothing meaningful for the user to add
+
+If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+
+## Don't
+
+- Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
+- Don't `import OpenAI from "openai"` in client or server code
+- Don't make direct API calls to any LLM provider
+- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
+- Don't build "AI features" that bypass the agent chat
+- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+
+## Exception
+
+Scripts may call external APIs (image generation, search, etc.) — but the AI reasoning and orchestration still goes through the agent. A script is a tool the agent uses, not a replacement for the agent.
+
+## When to Use A2A Instead
+
+`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// Call a different agent — not the local agent chat
+const stats = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+```
+
+See the **a2a-protocol** skill for the full pattern.
+
+## Related Skills
+
+- **a2a-protocol** — When the work goes to a different agent, not the local one
+- **scripts** — The agent invokes scripts via `pnpm action <name>` to perform complex operations
+- **self-modifying-code** — The agent operates through the chat bridge to make code changes
+- **storing-data** — The agent writes results to the database after processing requests
+- **real-time-sync** — The UI updates automatically when the agent writes data

package/dist/templates/workspace-core/.agents/skills/extension-points/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: extension-points
+description: >-
+  How extensions render as widgets inside other apps via named UI slots — the
+  framework's VS-Code-style extension system. Use when a user asks to add a
+  custom widget to an app surface (e.g. "add a sticky-note widget to my mail
+  contact sidebar"), when wiring an ExtensionSlot in a template, or when
+  marking an extension as installable into a slot.
+---
+
+# Extension Points
+
+> **Terminology note.** "Extensions" in this doc are the framework's
+> sandboxed Alpine.js mini-app primitive (see the `extensions` skill).
+> They are NOT LLM "tools" (function calls). The slot-system tables are
+> still physically named `tool_slots` and `tool_slot_installs` for
+> back-compat — see the table at the bottom of this doc and the
+> "Database & API names" section in the `extensions` skill.
+
+## Mental model
+
+**Slots** are named React-shaped holes in apps. **Extensions** are widgets
+that opt into filling those holes. The framework matches them up by string
+ID.
+
+Three primitives:
+
+| Primitive            | What it is                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| **Slot**             | `<ExtensionSlot id="..." context={...} />` dropped into an app's JSX                            |
+| **Slot target**      | A row saying "extension X can render in slot Y" — `tool_slots` table (Drizzle: `extensionSlots`) |
+| **Slot install**     | A row saying "user U wants extension X in slot Y" — `tool_slot_installs` (Drizzle: `extensionSlotInstalls`) |
+
+When `<ExtensionSlot>` renders, it queries the user's installs and mounts
+one `<EmbeddedTool>` (a small auto-sized iframe) per install, pushing the
+slot's context into each via postMessage. (The component is still exported
+as `EmbeddedTool` for back-compat.)
+
+## Slot ID convention
+
+`<app>.<area>.<position>` — three dot-separated lowercase-kebab segments.
+
+- `mail.contact-sidebar.bottom`
+- `mail.thread-toolbar.actions`
+- `clips.right-panel.tabs`
+- `calendar.event-detail.bottom`
+
+Stable strings. Renaming a slot is a data migration — same as renaming a
+route.
+
+## How to author an extension that fills a slot
+
+1. **Create the extension** with `create-extension`. The HTML can read
+   `window.slotContext` to get the host's context (the contact email,
+   recording id, etc.) and subscribe to changes via
+   `window.onSlotContext(fn)`.
+
+   ```html
+   <div
+     x-data="{ contact: null }"
+     x-init="contact = window.slotContext; window.onSlotContext(c => contact = c)"
+   >
+     <template x-if="contact">
+       <div class="rounded-lg border p-4 m-4">
+         <p class="text-sm">
+           Notes for <span x-text="contact.contactEmail"></span>
+         </p>
+       </div>
+     </template>
+   </div>
+   ```
+
+2. **Declare the slot target** with `add-extension-slot-target`:
+
+   ```
+   add-extension-slot-target { extensionId: "<id>", slotId: "mail.contact-sidebar.bottom" }
+   ```
+
+3. **Install it** for the current user with `install-extension`:
+
+   ```
+   install-extension { extensionId: "<id>", slotId: "mail.contact-sidebar.bottom" }
+   ```
+
+The slot will pick up the install on its next render (≤2s via polling sync,
+immediate after the action's UI invalidation).
+
+## How to declare a slot in your app
+
+Drop `<ExtensionSlot>` wherever you want to allow extensions:
+
+```tsx
+import { ExtensionSlot } from "@agent-native/core/client/extensions";
+
+// inside your component
+<ExtensionSlot
+  id="mail.contact-sidebar.bottom"
+  context={{ contactEmail: contact.email, contactName: contact.name }}
+  showEmptyAffordance
+/>;
+```
+
+> The legacy import path `@agent-native/core/client/tools` continues to
+> re-export the same component for back-compat with existing templates.
+
+Props:
+
+- `id` — slot identifier. Must match what extensions target.
+- `context` — object pushed to each embedded extension as `slotContext`. Re-pushed
+  whenever this prop changes.
+- `showEmptyAffordance` — when true, shows a "+ Add widget" button in the
+  empty state. Default: false (slot renders nothing when empty).
+- `className` / `toolClassName` — optional styling hooks. (The `toolClassName`
+  prop name is kept for back-compat; it styles the embedded extension's
+  iframe wrapper.)
+
+The host doesn't register slots in advance — `<ExtensionSlot>` is the
+declaration. If an extension targets a slot ID that no app has placed, it
+just won't render anywhere (the install record is harmless).
+
+## Context contract
+
+Each slot publishes whatever shape it wants via the `context` prop. There's
+no schema enforcement in v1 — extensions should null-check fields and fail
+gracefully if a field they expect is missing.
+
+Document the context shape next to your `<ExtensionSlot>` so extension
+authors know what to read. Convention: include the document in the slot
+ID's prefix section so the agent can find it (`mail.contact-sidebar.*`
+slots all publish `{ contactEmail, contactName }`).
+
+## Agent actions
+
+| Action                       | What it does                                                            |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `add-extension-slot-target`  | Mark an extension as installable into a slot (extension author opts in) |
+| `install-extension`          | Install an extension into a slot for the current user                   |
+| `uninstall-extension`        | Remove an extension from a slot for the current user                    |
+| `list-extensions-for-slot`   | List installable extensions for a given slot ID                         |
+| `list-extension-slots`       | List slot targets an extension declares                                 |
+
+Typical flow when a user asks "add a CRM widget below my contacts":
+
+1. `list-extensions-for-slot { slotId: "mail.contact-sidebar.bottom" }` —
+   see what's already installable
+2. If a fitting extension exists: `install-extension`
+3. Otherwise: `create-extension` → `add-extension-slot-target` →
+   `install-extension`
+
+## Lifecycle
+
+**Mount** — host calls the slot installs API, renders an `<iframe>` per
+install. The iframe URL includes `?slot=<slotId>` so the runtime knows it's
+embedded (enables auto-resize, suppresses anything that only makes sense
+full-page).
+
+**Context push** — host posts `agent-native-slot-context` immediately on
+iframe load, and again on every prop change. The extension reads the
+current value synchronously via `window.slotContext` and subscribes via
+`window.onSlotContext(fn)` for live updates.
+
+**Auto-resize** — when in slot mode, the iframe runtime measures its
+content height and posts `agent-native-tool-resize` (postMessage type kept
+for back-compat) to the host. The `<EmbeddedTool>` sets the iframe height
+accordingly. Use `ResizeObserver` to follow content changes.
+
+**Extension API** — embedded extensions have the full helper set:
+`appAction`, `appFetch`, `dbQuery`, `dbExec`, `extensionFetch`,
+`extensionData` (with `toolFetch` / `toolData` legacy aliases). Same auth
+context as full-page extensions.
+
+**Unmount** — uninstall deletes the install row. Polling sync invalidates
+the `slot-installs` query and the host re-renders without the iframe.
+
+## Permissions
+
+- Installing requires viewer access to the extension. A user can only
+  install extensions they have access to.
+- Declaring slot targets requires editor access to the extension.
+- Slot installs are per-user — installing a widget only affects the
+  installing user's view. There's no org-wide "default install" in v1.
+- Slots themselves are ungated. Any app code can drop an `<ExtensionSlot>`
+  in any user's view; the slot's contents come from that user's installs.
+
+## What this is NOT
+
+- **Not a way to render arbitrary React in slots.** Slots only render
+  Alpine.js iframe extensions. Same security/auth/sandbox as
+  `/extensions/:id`.
+- **Not cross-extension messaging.** Two extensions in the same slot can't
+  read each other's `extensionData`. Use actions or app SQL if widgets need
+  to coordinate.
+- **Not a slot manifest.** Slot targets live in the `tool_slots` table
+  (Drizzle export `extensionSlots`), not in the extension's HTML content.
+  The agent can re-target an extension without rewriting it.
+- **Not for arbitrary code modification.** If a user wants to change how
+  the app itself behaves (not add a sandboxed widget), use the
+  `self-modifying-code` skill instead.
+
+## Cross-references
+
+- `extensions` skill — authoring Alpine.js mini-apps (the substrate for widgets)
+- `sharing` skill — how access flows from extension sharing to slot installs
+- `context-awareness` skill — how extensions read what the user is looking at
+- `actions` skill — how `install-extension` etc. are auto-mounted