@agent-native/core 0.4.5 → 0.6.1

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

@@ -0,0 +1,167 @@
+---
+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 (files), Rule 2 (delegate), Rule 3 (scripts), Rule 4 (SSE), Rule 5 (self-modify), or "utility."
+3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
+4. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
+5. **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/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,90 @@
+---
+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 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 the database, 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,
+});
+```
+
+## 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
+
+## 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.
+
+## Related Skills
+
+- **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 to the database

package/dist/templates/default/.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: frontend-design
+description: >-
+  Create distinctive, production-grade frontend interfaces with high design
+  quality. Use when building web components, pages, artifacts, posters, or
+  applications (websites, landing pages, dashboards, React components,
+  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
+  creative, polished UI that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+## Anti-Patterns to Avoid
+
+NEVER use generic AI-generated aesthetics like:
+- Overused font families (Inter, Roboto, Arial, system fonts)
+- Clichéd color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and component patterns
+- Cookie-cutter design that lacks context-specific character
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+## Implementation Notes
+
+**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+In the agent-native framework context:
+- Agent-native apps use React 18, Vite, TailwindCSS, and shadcn/ui
+- Custom styles go in component CSS or Tailwind classes — never inline styles
+- For complex visual effects, use a `<style>` tag in the component or a dedicated CSS file
+- Fonts can be loaded from Google Fonts via `@import` in a CSS file or `<link>` in `index.html`
+- Animation libraries: prefer CSS transitions and keyframes; use Framer Motion for complex sequences
+- All new UI components should be placed in `app/components/`
+
+## Related Skills
+
+- **self-modifying-code** — The agent can edit source code to apply design changes
+- **storing-data** — Design configuration can be stored in the settings table for agent-editable theming

package/dist/templates/default/.agents/skills/real-time-collab/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: real-time-collab
+description: >-
+  How to enable multi-user collaborative editing with Yjs CRDT, TipTap
+  Collaboration extension, live cursors, and agent-driven edits.
+---
+
+# Real-Time Collaboration
+
+The framework provides a Yjs-based collaborative editing system in `@agent-native/core/collab`. Multiple users can edit the same document simultaneously with live cursor positions, and the AI agent can make surgical edits that appear in real-time.
+
+## Architecture
+
+```
+User A (TipTap + Collaboration ext)  ←→  Y.XmlFragment  ←→  Server (_collab_docs table)
+User B (TipTap + Collaboration ext)  ←→  Y.XmlFragment  ←→       ↑
+Agent (edit-document action)         ←→  search-replace endpoint ─┘
+```
+
+- **Yjs Y.Doc** stores the document as a `Y.XmlFragment` (ProseMirror node tree)
+- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment via `ySyncPlugin`
+- **CollaborationCaret extension** renders remote users' cursors with names and colors
+- **Polling** (every 2s) syncs Y.Doc updates and awareness state between clients and server
+- **SQL `_collab_docs` table** persists Yjs state (base64-encoded binary)
+
+## Enabling Collaboration in a Template
+
+### 1. Install dependencies
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap --filter your-template
+```
+
+### 2. Add Vite optimizeDeps
+
+In `vite.config.ts`:
+```ts
+export default defineConfig({
+  plugins: [reactRouter()],
+  optimizeDeps: {
+    include: [
+      "yjs",
+      "y-protocols/awareness",
+      "@tiptap/extension-collaboration",
+      "@tiptap/extension-collaboration-caret",
+      "@tiptap/y-tiptap",
+    ],
+  },
+});
+```
+
+This prevents Vite from re-bundling TipTap in incompatible ways during dev.
+
+### 3. Add the collab server plugin
+
+Create `server/plugins/collab.ts`:
+```ts
+import { createCollabPlugin } from "@agent-native/core/server";
+export default createCollabPlugin({
+  table: "your_table",
+  contentColumn: "content",
+  idColumn: "id",
+  autoSeed: false, // Client-side seeding on first load
+});
+```
+
+This mounts routes under `/_agent-native/collab/`:
+- `GET /:docId/state` — fetch Y.Doc state
+- `POST /:docId/update` — apply client update
+- `POST /:docId/text` — apply full text (diff-based)
+- `POST /:docId/search-replace` — surgical text find/replace in Y.XmlFragment
+- `POST /:docId/awareness` — sync cursor/presence state
+
+### 4. Use the `useCollaborativeDoc` hook
+
+```ts
+import { useCollaborativeDoc, generateTabId } from "@agent-native/core/client";
+
+const TAB_ID = generateTabId();
+
+const { ydoc, awareness, isLoading, activeUsers } = useCollaborativeDoc({
+  docId: documentId,
+  requestSource: TAB_ID,
+  user: { name: "Steve", email: "steve@example.com", color: "#60a5fa" },
+});
+```
+
+The hook:
+- Creates a stable `Y.Doc` per docId (never changes identity)
+- Fetches server state and applies it
+- Sends local updates to server
+- Polls for remote updates (every 2s)
+- Tracks active users via awareness
+
+### 5. Add Collaboration extension to TipTap
+
+```ts
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+import { Awareness } from "y-protocols/awareness";
+
+// Create awareness locally (must use same y-protocols as the caret extension)
+const awareness = new Awareness(ydoc);
+awareness.setLocalStateField("user", { name, color });
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ history: false }), // Disable history — Yjs handles undo
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider: { awareness },
+      user: { name, color },
+    }),
+    // ... other extensions
+  ],
+  content: initialContent, // Seeds Y.XmlFragment on first load
+});
+```
+
+**Important:** Disable `history` in StarterKit when using Collaboration — Yjs handles undo/redo.
+
+### 6. Seed the Y.XmlFragment
+
+The Collaboration extension does NOT auto-seed from the `content` prop. You must seed manually:
+
+```ts
+useEffect(() => {
+  if (!editor || !ydoc || !content) return;
+  const fragment = ydoc.getXmlFragment("default");
+  if (fragment.length === 0) {
+    editor.commands.setContent(parseContent(content));
+  }
+}, [editor, ydoc, content]);
+```
+
+**Critical:** Guard against saving empty content back to SQL when the editor is in collab mode but hasn't been seeded yet:
+
+```ts
+onUpdate: ({ editor }) => {
+  const md = editor.storage.markdown.getMarkdown();
+  if (!md.trim() && ydoc) return; // Don't save empty during seeding
+  onChange(md);
+}
+```
+
+## Agent Edits via `edit-document`
+
+The `edit-document` action uses search-and-replace:
+```bash
+pnpm action edit-document --id <docId> --find "old text" --replace "new text"
+```
+
+When collab state exists, the action calls the server's `search-replace` endpoint which:
+1. Walks the Y.XmlFragment tree
+2. Finds the text in Y.XmlText nodes
+3. Applies minimal delete/insert operations
+4. Emits a Yjs update via the poll system
+5. Client receives the update → ySyncPlugin applies a targeted ProseMirror transaction → cursor preserved
+
+**Important:** Actions run in a separate process, so they must use the HTTP endpoint (not the collab module directly) to emit updates to the server's poll system.
+
+## Key Modules
+
+| Module | Path | Purpose |
+|--------|------|---------|
+| `@agent-native/core/collab` | `packages/core/src/collab/` | Server-side Yjs management |
+| `useCollaborativeDoc` | `packages/core/src/collab/client.ts` | Client hook |
+| `createCollabPlugin` | `packages/core/src/server/collab-plugin.ts` | Route mounting |
+| `searchAndReplace` | `packages/core/src/collab/ydoc-manager.ts` | Y.XmlFragment text mutation |
+
+## Common Pitfalls
+
+1. **TipTap version mismatch** — All `@tiptap/*` packages must be the same version. The Collaboration extension requires `editor.utils` which was added in v3.22.2.
+
+2. **Empty editor on first load** — The Collaboration extension uses Y.XmlFragment as the source of truth. If the fragment is empty, the editor shows empty. Seed manually (see above).
+
+3. **Data loss from empty saves** — The `onUpdate` handler fires when the editor initializes with an empty Y.XmlFragment. If this empty content is saved to SQL, it overwrites the real content. Always guard against saving empty content in collab mode.
+
+4. **Stale content on document switch** — Use `key={documentId}` on the editor component to force a full remount when switching documents. This ensures the Y.Doc, seeding, and editor state are all fresh.
+
+5. **Separate process for actions** — Actions run via `pnpm action` in a new Node.js process. The in-memory EventEmitter in the action process doesn't reach the dev server's poll system. Use HTTP endpoints for collab operations from actions.
+
+6. **Vite dep optimization** — Adding Yjs-related packages to a template changes Vite's dependency bundling, which can break TipTap's React integration. Always add them to `optimizeDeps.include`.

package/dist/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: real-time-sync
+description: >-
+  How to keep the UI in sync with agent changes via polling. Use when wiring
+  query invalidation for new data models, debugging UI not updating, or
+  understanding jitter prevention.
+---
+
+# Real-Time Sync (Polling)
+
+## Rule
+
+The UI stays in sync with agent/script changes through database polling. When the agent writes to the database, the UI detects the change and updates automatically — no manual refresh needed.
+
+## Why
+
+The agent modifies data in SQL, but the UI runs in the browser. Polling bridges this gap: every database write increments a version counter, the `useDbSync()` hook polls for version changes, and React Query invalidates the relevant caches. This is what makes database writes feel real-time.
+
+## How It Works
+
+1. **Server** increments a version counter on every database write. The `/_agent-native/poll` endpoint returns the current version and any events since the last poll.
+
+2. **Client** polls for changes and invalidates React Query caches:
+
+   ```ts
+   import { useDbSync } from "@agent-native/core";
+   useDbSync({ queryClient, queryKeys: ["items", "settings"] });
+   ```
+
+3. When the agent writes to the database, the version increments, polling detects it, and React Query refetches the affected queries.
+
+## Don't
+
+- Don't create manual polling loops — `useDbSync()` handles it (polls every 2 seconds by default)
+- Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+
+## Query Key Mapping
+
+By default, `useDbSync` invalidates all listed query keys on every change. For apps with multiple data models, this causes unnecessary refetches. Use event-based filtering via the `onEvent` callback:
+
+```ts
+useDbSync({
+  queryClient,
+  queryKeys: [], // don't auto-invalidate everything
+  onEvent: (data) => {
+    if (data.source === "settings") {
+      queryClient.invalidateQueries({ queryKey: ["settings"] });
+    } else if (data.source === "app-state") {
+      queryClient.invalidateQueries({ queryKey: ["navigate-command"] });
+    } else {
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+    }
+  },
+});
+```
+
+To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
+
+```ts
+useQuery({
+  queryKey: ["items"],
+  queryFn: fetchItems,
+  staleTime: 2000, // don't refetch within 2 seconds
+});
+```
+
+## Troubleshooting
+
+| Symptom                            | Check                                                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Are the `queryKeys` matching your `useQuery` keys?       |
+| Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
+| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries and use event-based filtering.                        |
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`, `deleteAppState`), the write is automatically tagged with `requestSource: "agent"`. This prevents the UI from overwriting active user edits when it receives the change event.
+
+### How it works
+
+1. **Agent writes** are tagged: the script helpers in `@agent-native/core/application-state` pass `{ requestSource: "agent" }` to the store.
+2. **UI writes** are tagged: templates send a per-tab ID via the `X-Request-Source` header on PUT/DELETE requests to application-state endpoints.
+3. **Polling filters**: `useDbSync()` accepts an `ignoreSource` option. The UI passes its own tab ID so it ignores events from its own writes — but still picks up events from agents, other tabs, and scripts.
+
+### Template setup
+
+```ts
+// app/lib/tab-id.ts
+export const TAB_ID = `tab-${Math.random().toString(36).slice(2, 8)}`;
+
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID,
+});
+```
+
+The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Source` header when writing navigation state, so the tab that wrote the state does not refetch it.
+
+### Why this matters
+
+Without jitter prevention, a cycle occurs: the UI writes state, polling detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
+
+## Related Skills
+
+- **storing-data** — Application-state and settings are the data stores that sync via polling
+- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
+- **scripts** — Script outputs written to the database trigger poll events
+- **self-modifying-code** — Agent code edits trigger poll events; rapid edits can cause event storms