@agent-native/core 0.85.7 → 0.86.0

package/corpus/templates/videos/.agents/skills/composition-management/SKILL.md

@@ -1,106 +0,0 @@
----
-name: composition-management
-description: How to create and register video compositions. Covers SQL-backed composition records, Remotion component generation, registry defaults, and the track system.
----
-
-# Composition Management
-
-Compositions are the core unit of the animation studio. There are two related storage surfaces:
-
-- **SQL composition records** in the `compositions` table, managed by actions such as `save-composition`, `update-composition`, `get-composition`, and `list-compositions`.
-- **Code-backed Remotion defaults** in `app/remotion/registry.ts` plus component files in `app/remotion/compositions/`. These are the shipped examples and default track definitions.
-
-Use the action surface for app data. Edit component and registry files only when creating or changing code-backed Remotion defaults.
-
-## SQL-Backed Compositions
-
-Create or update a composition record with `save-composition`:
-
-```bash
-pnpm action save-composition --id "my-comp" --title "My Composition" --type custom --data '{"tracks":[]}'
-```
-
-Use this when the user wants a saved composition entry, metadata changes, or JSON composition data. The action handles upsert behavior and sharing-aware access checks.
-
-## Registry Defaults
-
-`app/remotion/registry.ts` contains the default `CompositionEntry[]` shipped with the template. Each entry:
-
-```typescript
-type CompositionEntry = {
-  id: string; // URL slug: "logo-reveal" -> /c/logo-reveal
-  title: string;
-  description: string;
-  component: React.FC<any>;
-  durationInFrames: number;
-  fps: number;
-  width: number;
-  height: number;
-  defaultProps: Record<string, any>;
-  tracks: AnimationTrack[];
-};
-```
-
-`defaultProps` is shown in `PropsEditor` as editable fields. Do not include `tracks` in `defaultProps`; tracks are passed separately.
-
-## Adding a Code-Backed Composition
-
-For a new Remotion component:
-
-1. Create `app/remotion/compositions/MyComp.tsx`.
-2. Export it from `app/remotion/compositions/index.ts`.
-3. Add a `CompositionEntry` to `app/remotion/registry.ts`.
-4. Define `tracks` with meaningful IDs, labels, frame ranges, and `animatedProps`.
-5. Run `pnpm typecheck` and `pnpm action validate-compositions`.
-
-For boilerplate component generation, use:
-
-```bash
-pnpm action generate-animated-component --name MyComp --elements Button,Card
-```
-
-This generates component files. It does not replace the need to review tracks, registry metadata, and exported symbols.
-
-## Component Template
-
-```tsx
-import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
-import type { AnimationTrack } from "@/types";
-import { trackProgress, getPropValue, findTrack } from "../trackAnimation";
-
-const FALLBACK_TRACKS: AnimationTrack[] = [
-  {
-    id: "mc-intro",
-    label: "Intro",
-    startFrame: 0,
-    endFrame: 30,
-    easing: "spring",
-    animatedProps: [{ property: "opacity", from: "0", to: "1", unit: "" }],
-  },
-];
-
-export const MyComp: React.FC<{ tracks?: AnimationTrack[] }> = ({
-  tracks = FALLBACK_TRACKS,
-}) => {
-  const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
-
-  const introTrack = findTrack(tracks, "mc-intro", FALLBACK_TRACKS[0]);
-  const p = trackProgress(frame, fps, introTrack);
-  const opacity = getPropValue(p, introTrack, "opacity", 0, 1);
-
-  return (
-    <AbsoluteFill>
-      <div style={{ opacity }}>Content</div>
-    </AbsoluteFill>
-  );
-};
-```
-
-## Key Rules
-
-- Every animation must be registered as a track; avoid hardcoded frame checks.
-- Always declare `FALLBACK_TRACKS` in the component file.
-- Use `findTrack()`, `trackProgress()`, and `getPropValue()`.
-- Registry defaults are not runtime storage. User edits and overrides are SQL/localStorage backed depending on the workflow.
-- Use `save-composition` for SQL records; creation and updates share that action.

package/corpus/templates/videos/.agents/skills/create-skill/SKILL.md

@@ -1,221 +0,0 @@
----
-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.
-scope: dev
-metadata:
-  internal: true
----
-
-# Create a Skill
-
-## When to Use
-
-Create a new skill when:
-
-- There's a pattern the agent should follow repeatedly.
-- A multi-step workflow needs reliable, 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).
-- It's a one-off — put it in `AGENTS.md` (for everyone) or `memory/MEMORY.md`
-  (personal, per-user). See **capture-learnings**.
-
-## Interview
-
-Before writing the skill, answer these:
-
-1. **What should this skill enable?** — The core purpose in one sentence.
-2. **Which of the four areas does it serve?** — UI, actions, skills/instructions,
-   or application state (see the **adding-a-feature** skill). Most skills are
-   about how to touch one or more of these correctly.
-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? If so, reference the `navigation` application-state key and
-   the `view-screen` action pattern. See the **context-awareness** skill.
-5. **What type of skill?** — Pattern, Workflow, or Generator (see below).
-6. **Does it need supporting files?** — References (read-only context) or none.
-   Keep it minimal; push depth into `references/`.
-
-## Skill Types and Templates
-
-### Pattern (architectural rule)
-
-For documenting how things should be done:
-
-```markdown
----
-name: my-pattern
-description: >-
-  [Under 40 words. What it covers AND when it should 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. What it covers AND when it should 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. What it covers AND when it should 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 sync, add routes, register the action, 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-skill`, `capture-learnings`).
-- The directory name must match the `name` in frontmatter.
-
-## Skill Scope (runtime vs dev)
-
-An optional `scope` frontmatter field controls which agent loads the skill:
-
-- `both` (default when omitted) — loaded by connected repo agents and the
-  in-app runtime agent. Use for any skill both audiences should follow.
-- `runtime` — loaded only by the in-app runtime agent.
-- `dev` — meant for the human's coding agent (e.g. Claude Code) only. **Excluded
-  from the runtime agent everywhere**: not in the system-prompt skills block and
-  not in `docs-search` results.
-
-Use `scope: dev` for internal-only skills that should guide connected repo
-agents such as Codex or Claude Code, but should not affect the deployed
-production agent. Do not use `metadata.internal` for runtime visibility; that
-field is catalog/package metadata and is intentionally not treated as
-production exclusion.
-
-```markdown
----
-name: release-checklist
-description: >-
-  Steps for cutting a release. Use when preparing or publishing a new version.
-scope: dev
----
-```
-
-Leave `scope` off for normal skills — the default (`both`) keeps them loading at
-runtime, so this is fully backward compatible. To make a dev-only skill visible
-to your coding agent but hidden from the runtime agent, mark it `scope: dev` and
-optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
-`.claude/skills/` independently of the runtime's `.agents/skills/`).
-
-## Tips
-
-- **Keep descriptions under 40 words** — they load into context on every
-  conversation. State what the skill does AND when to trigger it.
-- **Keep SKILL.md lean (under ~500 lines)** — move detailed content to
-  `references/` files (progressive disclosure).
-- **Use standard markdown headings** — no XML tags or custom formats.
-
-## Anti-Patterns
-
-- **Inline LLM calls** — skills must not call LLMs directly. All AI work goes
-  through the agent chat (see **delegate-to-agent**).
-- **Introducing databases** — data lives in SQL via Drizzle (see **storing-data**).
-- **Ignoring sync** — if a skill creates data, mention wiring `useDbSync` /
-  `useActionQuery` so the UI updates (see **real-time-sync**).
-- **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
-
-- **adding-a-feature** — The four-area model every skill ultimately serves.
-- **writing-agent-instructions** — How to write AGENTS.md and skills well for
-  apps and templates you ship to others.
-- **capture-learnings** — When a learning graduates to reusable guidance, create
-  a skill; one-offs go to `AGENTS.md` or `memory/MEMORY.md`.
-- **self-modifying-code** — The agent can create new skills (Tier 2 modification).

package/corpus/templates/videos/.agents/skills/delegate-to-agent/SKILL.md

@@ -1,263 +0,0 @@
----
-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.
-scope: dev
-metadata:
-  internal: true
----
-
-# Delegate All AI to the Agent
-
-## Rule
-
-The UI never calls an LLM directly. Product workflows are delegated to the
-agent through the chat bridge so users can see, steer, and audit the work.
-Server-side one-shot model calls are an explicit escape hatch for narrow text
-transforms only; use `completeText()` from `@agent-native/core/server` when the
-work intentionally does not need tools, chat history, or run state.
-
-## 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/client";
-
-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 the UI, in the background:**
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client";
-
-sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-This is still a full agent run: tools, actions, thread state, and run tracking
-all remain active. It simply does not focus or open the sidebar.
-
-**From scripts (Node):**
-
-```ts
-import { agentChat } from "@agent-native/core";
-
-agentChat.submit("Process the uploaded images and create thumbnails");
-```
-
-**For narrow server-side text transforms:**
-
-```ts
-import { completeText } from "@agent-native/core/server";
-
-const result = await completeText({
-  systemPrompt: "Return exactly one sentiment label.",
-  input: messageBody,
-  maxOutputTokens: 12,
-  temperature: 0,
-});
-```
-
-Wrap user-facing uses in actions so the UI and agent share the same operation.
-Do not call provider SDKs directly.
-
-**From the UI, detecting when agent is done:**
-
-```ts
-import { useAgentChatGenerating } from "@agent-native/core/client";
-
-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.
-
-## Delegating to a Sub-Agent (Agent Teams)
-
-`sendToAgentChat()` delegates from app code _to_ the agent. The other axis of
-delegation is the agent handing work _to a sub-agent_ through the Agent Teams
-run-manager. The main chat stays the orchestrator: it spawns sub-agents, then
-reads and integrates their results.
-
-### When to spawn a sub-agent vs do it yourself
-
-- **Do it yourself** when the work is small, on the critical path, or tightly
-  coupled to what you're already doing. Sub-agent overhead and coordination risk
-  outweigh the benefit.
-- **Spawn a sub-agent** for a self-contained unit of work that can run
-  independently — a disjoint investigation, an isolated implementation slice, a
-  long-running search — especially when it frees the main thread to keep
-  orchestrating.
-
-### Briefing contract
-
-Every sub-agent brief must specify four things, or the sub-agent will guess:
-
-- **Objective** — the one concrete outcome it owns, in a sentence.
-- **Context** — the facts it needs (paths, prior findings, constraints) so it
-  doesn't re-derive them.
-- **Output** — the exact shape you want back (a summary, a file edited, a list
-  of paths, a yes/no with rationale).
-- **Boundaries** — what it must NOT touch (files, branches, side effects) and
-  when to stop and report rather than push forward.
-
-### Fan-out discipline
-
-- **Default to a single sub-agent.** Most delegation is one focused task.
-- **Spawn multiple only for genuinely independent units** that don't share state
-  or files. Never parallelize coupled work — if B needs A's output, run them in
-  sequence.
-- **Cap parallel fan-out at ~3.** More sub-agents means more synthesis cost and
-  more chance of conflicting edits to the same area.
-
-### Synthesis discipline
-
-- **Read every result** before concluding — don't act on the first one back.
-- **Reconcile conflicts** between sub-agent findings explicitly; decide which is
-  right rather than averaging or ignoring.
-- **Integrate into one answer.** The main thread produces the single coherent
-  result; it never just forwards raw sub-agent transcripts to the user.
-
-Background sub-agents must use the core run-manager / Agent Teams infrastructure
-rather than ad-hoc LLM calls.
-
-## 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)
-- Don't use `completeText()` for workflows that need tools, database writes,
-  auditability, user steering, or multi-step reasoning. Use the agent chat
-  instead, optionally with `background: true`.
-
-## 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.
-
-`completeText()` is allowed for small server-side transforms such as
-classification, extraction, rewriting a short string, or normalizing messy
-provider text. It deliberately runs with `tools: []` and does not create chat
-thread state.
-
-## 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
-- **actions** — The agent invokes actions 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