@agent-native/core 0.210.0-nightly-20261019153056 → 0.210.0

package/src/templates/factory/.agents/skills/review-prs/SKILL.md

@@ -3,8 +3,9 @@ name: review-prs
 description: >-
   Review recent BuilderIO/agent-native human pull requests, approve eligible
   internal PRs, and merge changes that are ready by Steve's bar. Use for
-  scheduled or manual PR sweeps; flag external non-bug work and unresolved major
-  product or UX decisions to Steve.
+  scheduled or manual PR sweeps; flag external work needing a major product
+  call or new framework API, and unresolved major product or UX decisions, to
+  Steve.
 user-invocable: true
 scope: dev
 metadata:
@@ -20,10 +21,12 @@ approve an external or unverified author.
 
 Approval and merge readiness are separate. A **Ready to merge by Steve's bar**
 result means merge the PR under the guarded merge procedure below. For a
-confirmed external author, only a clear bug fix enters evidence review and the
-possible merge flow; external authors are never eligible for an approval
-review. Surface other external work for Steve's explicit approval before a full
-review or merge; a scheduled or manual sweep is not that approval.
+confirmed external author, a clear bug fix or a bounded improvement that
+follows existing patterns enters evidence review and the possible merge flow;
+external authors are never eligible for an approval review. Surface external
+work that needs a major product call or a new framework API for Steve's explicit
+approval before a full review or merge; a scheduled or manual sweep is not that
+approval.
 
 ## Selection and evidence
 
@@ -53,6 +56,11 @@ author and draft state:
    summary to determine whether the PR already has a current, non-dismissed
    `APPROVED` review.
 
+ - Before the scope gate, check a confirmed nonmember's PR from a fork for
+   assignees. If any assignee is a verified current BuilderIO member, ignore
+   the PR completely, like a draft: that person owns it under `community-prs`.
+   Take no review, reply, or merge action, and leave it out of the recap.
+
  - Reuse that review as the code assessment only after verifying the reviewer
    is a different, current BuilderIO member and is eligible under the PR's
    author- and scope-specific rules, including any independent-review
@@ -99,17 +107,28 @@ the patch looks safe or the issue is obviously valid.
 
 ## External-contribution scope gate
 
+Builder devs decide bounded outside contributions; Steve keeps major product
+calls and new framework APIs.
+
 For an author the membership API confirms is not a current BuilderIO member,
-continue into the normal evidence sweep only for a clear bug fix: a change that
-corrects a specific reported or reproducible defect by restoring intended
-behavior. A feature, improvement, refactor, new or changed product behavior, or
-mixed bug-fix-and-enhancement scope is not a clear bug fix. If the title, issue,
-and initial diff do not establish a clear bug fix, treat it as non-bug work.
-
-For external non-bug work, stop before the full code review, approval or review
-action, merge-readiness disposition, author-facing draft, or merge. Report it to
-Steve as **Needs Steve's approval for scope**, with the PR link, author, stated
-scope, and why it is not a clear bug fix. Wait for Steve's explicit go-ahead on
+continue into the normal evidence sweep for a clear bug fix or a bounded
+improvement. A clear bug fix corrects a specific reported or reproducible
+defect by restoring intended behavior. A bounded improvement stays within one
+established workflow, app, or framework area and follows the patterns already
+there.
+
+External work needs Steve when it makes a major product call (as defined under
+Product and UX decisions) or adds a new framework API: a new public export,
+configuration option, action, plugin or hook contract, or CLI surface in a
+published package under `packages/`. A fix or bounded improvement to an existing
+API stays with devs when it keeps that API's contract. If the title, issue, and
+initial diff do not establish a clear bug fix or a bounded improvement, treat it
+as needing Steve.
+
+For external work that needs Steve, stop before the full code review, approval
+or review action, merge-readiness disposition, author-facing draft, or merge.
+Report it to Steve as **Needs Steve's approval for scope**, with the PR link,
+author, stated scope, and which call it needs. Wait for Steve's explicit go-ahead on
 that PR before continuing. Invoking or scheduling `review-prs`, approving a
 different PR, or prior approval of another external contribution does not
 authorize it. If membership is unknown, use the existing unknown-membership
@@ -118,6 +137,8 @@ solely because membership could not be verified. Keep the no-approval outcome,
 report the missing membership check, and assess merge readiness under the
 existing unknown-membership policy.
 
+Builder devs own outside PRs end to end with `community-prs`.
+
 ## Liamdebeasi approval policy
 
 For a PR authored by the exact GitHub login `liamdebeasi` and immutable user
@@ -296,9 +317,10 @@ merge scope and must remain completely untouched.
 For a PR that fails an approval gate, do not submit an approval. Flag the exact
 concern and the evidence needed to resolve it. External or unverified authors
 never receive an approval review, but their PRs can still be merged when they
-meet the readiness gate below. Confirmed external bug fixes must also pass the
-external-contribution scope gate; confirmed external non-bug work remains
-stopped at Steve's approval gate. For unknown membership, do not apply the
+meet the readiness gate below. Confirmed external PRs must also pass the
+external-contribution scope gate; external work that needs a major product call
+or a new framework API remains stopped at Steve's approval gate. For unknown
+membership, do not apply the
 external scope gate solely because verification failed; preserve the
 no-approval outcome, assess readiness under the existing unknown-membership
 policy, and name the missing check.
@@ -504,7 +526,8 @@ non-auto-approved external PR that needs an update or screenshot, include its
 draft reply in a separate section, or mark it waiting on the contributor with
 a link to Steve's outstanding request. For internal PRs, report the needed
 update or screenshot without drafting an author-facing reply. Do not add rows
-for bots, `steve8708`, or drafts; those are ignored completely.
+for bots, `steve8708`, drafts, or external PRs assigned to a BuilderIO member;
+those are ignored completely.
 
 Use this shape:
 
@@ -525,4 +548,4 @@ blocker when the PR is ready and the guarded admin merge is available.
 
 ## Related skills
 
-`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`
+`concurrent-agents`, `verifying-changes`, `ship`, `babysit-pr`, `community-prs`

package/src/templates/headless/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/src/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/docs/content/template-chat-first-edits.mdx

@@ -1,158 +0,0 @@
----
-title: "Chat: Your First Feature"
-description: "The files that render Chat's starter screens, what their real props do, and a full walkthrough of adding a feature end to end."
----
-
-# Your First Feature
-
-This page is for developers extending the [Chat template](/docs/template-chat). It covers the files that render the starter screens, then walks through everything the agent typically touches when you ask for a real feature.
-
-## First code to inspect {#first-code}
-
-- `actions/hello.ts` is the starter behavior the agent can call. Replace it or
-  add actions beside it.
-- `app/components/chat/ChatRouteContent.tsx` renders the full-page chat surface
-  at `/chat/<threadId>`. Adjust the empty state, composer, or message slots here.
-- `app/components/home/HomePage.tsx` is the editable Get started landing page at
-  `/home`. `/chat` starts a new chat.
-- `AGENTS.md` tells the built-in agent how to work inside this app.
-
-<FileTree
-  id="doc-block-chat3"
-  title="Chat template layout"
-  entries={[
-    {
-      path: "actions/hello.ts",
-      note: "the one example action; replace or add actions beside it",
-    },
-    {
-      path: "actions/view-screen.ts",
-      note: "standard context action the agent calls first",
-    },
-    {
-      path: "actions/navigate.ts",
-      note: "standard navigation action",
-    },
-    {
-      path: "app/routes/home.tsx",
-      note: "/home: the Get started landing page; /chat: starts a new chat",
-    },
-    {
-      path: "app/routes/chat._index.tsx",
-      note: "/chat: starts a new chat and hands off to /chat/:threadId",
-    },
-    {
-      path: "app/routes/chat.$threadId.tsx",
-      note: "/chat/:threadId: renders ChatRouteContent for that thread",
-    },
-    {
-      path: "app/components/chat/ChatRouteContent.tsx",
-      note: "the full-page chat surface; edit the empty state, composer, and message slots",
-    },
-    {
-      path: "app/components/home/HomePage.tsx",
-      note: "the editable Get started home page",
-    },
-    {
-      path: "app/lib/chat-paths.ts",
-      note: "Chat path helpers",
-    },
-    {
-      path: "AGENTS.md",
-      note: "chat-first guidance the built-in agent reads",
-    },
-  ]}
-/>
-
-The chat surface is assembled from AgentKit pieces: a transport, a thread root, and the chat view. Its copy comes from i18n keys rather than literal strings:
-
-<AnnotatedCode
-  id="doc-block-chat4"
-  title="app/components/chat/ChatRouteContent.tsx (trimmed)"
-  filename="app/components/chat/ChatRouteContent.tsx"
-  language="tsx"
-  code={
-    'import { createAgentNativeAgentKitTransport } from "@agent-native/core/client/agentkit-chat/transport";\nimport { useT } from "@agent-native/core/client/i18n";\nimport { AgentKitChat } from "@agent-native/toolkit/app/agentkit/react/components";\nimport { CoreAgentKitRoot } from "@agent-native/toolkit/app/chat/agentkit-chat/index";\nimport { useState } from "react";\nimport { useNavigate, useParams } from "react-router";\n\nimport { chatThreadPath } from "@/lib/chat-paths";\nimport { TAB_ID } from "@/lib/tab-id";\n\nexport default function ChatRouteContent() {\n  const { threadId } = useParams();\n  const navigate = useNavigate();\n  const t = useT();\n  const [transport] = useState(() =>\n    createAgentNativeAgentKitTransport({\n      browserTabId: TAB_ID,\n      surface: "app",\n      adapter: { textFormat: "markdown" },\n    }),\n  );\n  if (!threadId) return null;\n\n  return (\n    <CoreAgentKitRoot\n      transport={transport}\n      threadId={threadId}\n      labels={{ composerPlaceholder: t("chat.composerPlaceholder") }}\n      slots={{ emptyState: ChatEmptyState }}\n      onThreadForked={(thread) => navigate(chatThreadPath(thread.id))}\n    >\n      <AgentKitChat\n        emptyComposerPlacement="center"\n        composerProps={{ requireAgentEngine: true, voiceEnabled: true }}\n      />\n    </CoreAgentKitRoot>\n  );\n}\n\nfunction ChatEmptyState() {\n  const t = useT();\n  return (\n    <div className="agentkit-chat-empty-copy">\n      <h1>{t("chat.heroTitle")}</h1>\n    </div>\n  );\n}'
-  }
-  annotations={[
-    {
-      lines: "15-21",
-      label: "Transport",
-      note: "`createAgentNativeAgentKitTransport` connects the chat view to the app's agent runtime. `TAB_ID` (`app/lib/tab-id.ts`, a random id generated once per browser tab) lets the runtime tell open tabs of the same app apart, so a run started in one tab isn't mistaken for one in another.",
-    },
-    {
-      lines: "25-30",
-      label: "Thread root",
-      note: "`CoreAgentKitRoot` loads the thread named in `/chat/:threadId` (`chat.$threadId.tsx`). Visiting `/chat` creates a new thread id and hands off here. When a thread is forked, `chatThreadPath` moves the URL to the new thread.",
-    },
-    {
-      lines: "29",
-      label: "Slots",
-      note: "Slots replace parts of the chat view. The real file also passes `message`, `runFailure`, `connectionRequest`, and `footer` slots for recovery messages, MCP connection cards, and the agent footer.",
-    },
-    {
-      lines: "32-35",
-      label: "Centered composer",
-      note: '`emptyComposerPlacement="center"` centers the composer until the thread has a message. `requireAgentEngine` shows the Connect AI card until a model is connected.',
-    },
-    {
-      lines: "40-47",
-      label: "Empty state",
-      note: "The heading above the centered composer. Its copy is `chat.heroTitle` in `app/i18n/en-US.ts`: edit the catalog to change the pitch, or add elements here.",
-    },
-  ]}
-/>
-
-## First edits {#first-edits}
-
-Most first features follow the same shape: a table, one or two actions, a route, a nav entry, and an `AGENTS.md` update. Ask the agent:
-
-> Add a data model for `notes`. A note has an id, title, body, and owner. Render a notes page at `/notes`, add create/list actions, and keep chat able to create notes.
-
-Chat ships with no `server/db/schema.ts` at all (see [What ships](/docs/template-chat#what-ships)), so the first change is a new file, following the same `table`/`text`/`ownableColumns` shape every other template uses:
-
-<Diff
-  id="doc-block-chat5"
-  title="A new notes table"
-  filename="server/db/schema.ts"
-  language="ts"
-  before={""}
-  after={
-    'import {\n  table,\n  text,\n  ownableColumns,\n} from "@agent-native/core/db/schema";\n\nexport const notes = table("notes", {\n  id: text("id").primaryKey(),\n  title: text("title").notNull(),\n  body: text("body").notNull(),\n  createdAt: text("created_at").notNull(),\n  updatedAt: text("updated_at").notNull(),\n  ...ownableColumns(),\n});'
-  }
-  annotations={[
-    {
-      lines: "1-5",
-      label: "Shared schema helpers",
-      note: "`table`/`text`/`ownableColumns` come from `@agent-native/core/db/schema`, the PostgreSQL schema helpers every template uses.",
-    },
-    {
-      lines: "13",
-      label: "ownableColumns",
-      note: "`...ownableColumns()` adds the owner/org columns the framework's `accessFilter`/`resolveAccess` helpers expect, so notes slot into the standard per-user/per-org sharing model with no extra plumbing.",
-    },
-  ]}
-/>
-
-The rest of the feature follows from there:
-
-- `actions/create-note.ts` — a `defineAction` with a Zod schema (`title`, `body`), shaped like `actions/hello.ts`.
-- `actions/list-notes.ts` — a read-only action (`readOnly: true`, like `actions/view-screen.ts`) that queries the new table through `accessFilter`.
-- `app/routes/notes.tsx` — a new route; the app uses file-system routing (`flatRoutes()` in `app/routes.ts`), so adding the file is enough to mount `/notes`.
-- A link in `app/components/layout/Sidebar.tsx`, added before `ChatThreadsSection` and pointing at `/notes`.
-- An `AGENTS.md` addition telling the agent notes exist and which actions manage them.
-
-A new action is callable by chat as soon as it exists — every `defineAction` is a tool by default unless it sets `agentTool: false`. It won't necessarily be in the model's very first request, though: `server/plugins/agent-chat.ts` sets `INITIAL_TOOL_NAMES = ["view-screen", "navigate", "hello", "provider-api-request"]`, which controls only which tool schemas are sent on the first turn. Everything else, including a brand-new `create-note`, stays reachable through `tool-search` and loads on demand — add a name to that list only if you want it in the model's default toolset from message one.
-
-## Use your own agent backend {#own-agent-backend}
-
-The template uses the built-in app-agent loop by default. To connect a custom backend, swap the chat runtime behind the agent chat plugin instead of rewriting the UI. The Chat route should stay a thin renderer around the shared chat surface; the backend choice belongs in the server plugin/runtime adapter.
-
-Use this when your model orchestration already lives elsewhere, but you still want an app with auth, threads, actions, UI state, and deployable pages.
-
-## What's next
-
-- [**Chat**](/docs/template-chat) — what ships by default and when to pick it
-- [**Chat: Developer Guide**](/docs/template-chat-developers) — quick start, actions, core tables, auth, and the admin pages
-- [**Actions**](/docs/actions-overview) — the action system chat and UI both call
-- [**Native Chat UI**](/docs/native-chat-ui) — chat surface primitives and runtime options