@agent-native/core 0.141.6 → 0.144.0

package/dist/shared/cache-control.d.ts

@@ -1,11 +1,11 @@
 export declare const DEFAULT_PUBLIC_CACHE_CONTROL = "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 export declare const DEFAULT_SSR_CACHE_CONTROL = "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 export declare const DEFAULT_SSR_CDN_CACHE_CONTROL = "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
-export declare const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL = "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
+export declare const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL = "public, durable, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 export declare const DEFAULT_SSR_CACHE_HEADERS: {
     readonly "cache-control": "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
     readonly "cdn-cache-control": "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
-    readonly "netlify-cdn-cache-control": "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
+    readonly "netlify-cdn-cache-control": "public, durable, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 };
 /**
  * Deployment-wide override for the SSR shell cache policy.
@@ -58,6 +58,30 @@ export declare function ssrCacheHeadersForPolicy(policy: SsrCachePolicy): SsrCac
  * response — copy it before mutating.
  */
 export declare function resolveSsrCacheHeaders(env?: Record<string, string | undefined>): Readonly<SsrCacheHeaders>;
+/**
+ * Provider-specific cache-KEY headers, emitted only on the provider that
+ * understands them.
+ *
+ * Netlify keys its durable cache on the FULL query string by default, so every
+ * `?fbclid=`, `?gclid=` and `?utm_source=` mints a separate entry. On a
+ * marketing URL that fan-out is unbounded: measured on www.agent-native.com,
+ * every ad or social click was a guaranteed cold render (~4.5s) that could
+ * never be reused. `netlify-vary` narrows the key to the params that actually
+ * change the response.
+ *
+ * `_routes` is react-router's partial-payload param and DOES change the body —
+ * `.data` is ~45KB while `.data?_routes=root` is ~108 bytes — so it must stay
+ * in the key. (Remix v2's `_data` is inert here; naming it instead collapses
+ * those two into one entry and serves the wrong payload.)
+ *
+ * This lives in core, gated by runtime, for two reasons. It was written once
+ * before — `DEFAULT_SSR_NETLIFY_VARY`, added 2026-07-11 in PR #2026 and deleted
+ * 2h09m later in PR #2031 — and then independently re-derived inside an app,
+ * where the next person cannot find it. And a header no other provider
+ * understands should not be on every response everywhere: on anything but
+ * Netlify this returns {}.
+ */
+export declare function resolveSsrCacheKeyHeaders(env?: Record<string, string | undefined>): Readonly<Record<string, string>>;
 export declare function isSsrCacheEnabled(env?: Record<string, string | undefined>): boolean;
 export declare const DEFAULT_SPECULATION_RULES_PATH = "/_agent-native/speculation-rules.json";
 export declare const DEFAULT_SPECULATION_RULES_HEADER = "\"/_agent-native/speculation-rules.json\"";

package/dist/shared/cache-control.js

@@ -1,7 +1,7 @@
 export const DEFAULT_PUBLIC_CACHE_CONTROL = "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 export const DEFAULT_SSR_CACHE_CONTROL = DEFAULT_PUBLIC_CACHE_CONTROL;
 export const DEFAULT_SSR_CDN_CACHE_CONTROL = DEFAULT_SSR_CACHE_CONTROL;
-export const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL = DEFAULT_PUBLIC_CACHE_CONTROL;
+export const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL = "public, durable, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 export const DEFAULT_SSR_CACHE_HEADERS = {
     "cache-control": DEFAULT_SSR_CACHE_CONTROL,
     "cdn-cache-control": DEFAULT_SSR_CDN_CACHE_CONTROL,
@@ -85,10 +85,12 @@ export function ssrCacheHeadersForPolicy(policy) {
     // the 7-day default SWR here would hand back the staleness they opted out of.
     const control = `public, max-age=${policy.seconds}, ` +
         `stale-while-revalidate=${policy.seconds}, stale-if-error=3600`;
+    const netlifyControl = `public, durable, max-age=${policy.seconds}, ` +
+        `stale-while-revalidate=${policy.seconds}, stale-if-error=3600`;
     return {
         "cache-control": control,
         "cdn-cache-control": control,
-        "netlify-cdn-cache-control": control,
+        "netlify-cdn-cache-control": netlifyControl,
     };
 }
 let memoizedRaw;
@@ -109,6 +111,45 @@ export function resolveSsrCacheHeaders(env = typeof process === "undefined"
     memoizedHeaders = Object.freeze(ssrCacheHeadersForPolicy(parseSsrCacheSetting(raw)));
     return memoizedHeaders;
 }
+/**
+ * Provider-specific cache-KEY headers, emitted only on the provider that
+ * understands them.
+ *
+ * Netlify keys its durable cache on the FULL query string by default, so every
+ * `?fbclid=`, `?gclid=` and `?utm_source=` mints a separate entry. On a
+ * marketing URL that fan-out is unbounded: measured on www.agent-native.com,
+ * every ad or social click was a guaranteed cold render (~4.5s) that could
+ * never be reused. `netlify-vary` narrows the key to the params that actually
+ * change the response.
+ *
+ * `_routes` is react-router's partial-payload param and DOES change the body —
+ * `.data` is ~45KB while `.data?_routes=root` is ~108 bytes — so it must stay
+ * in the key. (Remix v2's `_data` is inert here; naming it instead collapses
+ * those two into one entry and serves the wrong payload.)
+ *
+ * This lives in core, gated by runtime, for two reasons. It was written once
+ * before — `DEFAULT_SSR_NETLIFY_VARY`, added 2026-07-11 in PR #2026 and deleted
+ * 2h09m later in PR #2031 — and then independently re-derived inside an app,
+ * where the next person cannot find it. And a header no other provider
+ * understands should not be on every response everywhere: on anything but
+ * Netlify this returns {}.
+ */
+export function resolveSsrCacheKeyHeaders(env = typeof process === "undefined"
+    ? {}
+    : process.env) {
+    // NETLIFY is the build-time marker; deployed functions expose SITE_ID at
+    // runtime. An explicit "false"/local override means we are not really hosted.
+    const explicitlyNotNetlify = env.NETLIFY_LOCAL === "true" || env.NETLIFY === "false";
+    const onNetlify = !explicitlyNotNetlify && (Boolean(env.NETLIFY) || Boolean(env.SITE_ID)); // guard:allow-env-credential -- Netlify's public runtime host marker, not a credential.
+    const none = Object.freeze({});
+    if (!onNetlify)
+        return none;
+    // This NARROWS the cache key rather than splitting it per user: it removes
+    // utm/fbclid/gclid so one entry serves everyone. The shapes the guard exists
+    // to stop are `private`, `no-store` and `Vary: Cookie`, none of which this is.
+    // guard:allow-ssr-shell-exception — narrows the shared key, never splits it
+    return Object.freeze({ "netlify-vary": "query=_routes|index" });
+}
 export function isSsrCacheEnabled(env = typeof process === "undefined"
     ? {}
     : process.env) {

package/dist/shared/index.d.ts

@@ -1,7 +1,7 @@
 export { agentChat, type AgentChatMessage, type AgentChatCallOptions, type AgentChatResponse, } from "./agent-chat.js";
 export { agentEnv, type EnvVar } from "./agent-env.js";
 export { extractOAuthStateAppId } from "./oauth-state.js";
-export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, encodeContinuation, normalizeAppPath, signInJourney, signInJourneyInlineScript, type SignInJourney, type SignInJourneyInput, } from "./sign-in-journey.js";
+export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, encodeContinuation, normalizeAppPath, signInJourney, signInJourneyInlineScript, type SignInJourney, type SignInJourneyInput, } from "./sign-in-journey.js";
 export { truncate } from "./truncate.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";

package/dist/shared/index.js

@@ -1,7 +1,7 @@
 export { agentChat, } from "./agent-chat.js";
 export { agentEnv } from "./agent-env.js";
 export { extractOAuthStateAppId } from "./oauth-state.js";
-export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, encodeContinuation, normalizeAppPath, signInJourney, signInJourneyInlineScript, } from "./sign-in-journey.js";
+export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, encodeContinuation, normalizeAppPath, signInJourney, signInJourneyInlineScript, } from "./sign-in-journey.js";
 export { truncate } from "./truncate.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";

package/dist/shared/password-policy.d.ts

@@ -0,0 +1,3 @@
+export declare const PASSWORD_MIN_LENGTH = 12;
+export declare const PASSWORD_MAX_LENGTH = 128;
+export declare const PASSWORD_MIN_LENGTH_MESSAGE = "Password must be at least 12 characters";

package/dist/shared/password-policy.js

@@ -0,0 +1,3 @@
+export const PASSWORD_MIN_LENGTH = 12;
+export const PASSWORD_MAX_LENGTH = 128;
+export const PASSWORD_MIN_LENGTH_MESSAGE = `Password must be at least ${PASSWORD_MIN_LENGTH} characters`;

package/dist/shared/sign-in-journey.d.ts

@@ -18,7 +18,7 @@
  *  - `signInJourney` returns `signInHref: null` — no token at all — when the
  *    browser is already at an auth entry path, so the one function permitted
  *    to mint continuations refuses to mint the dangerous value;
- *  - the sign-in URL is `<base>/_agent-native/sign-in?c=<opaque>`, so
+ *  - the sign-in URL is `<base>/sign-in?c=<opaque>`, so
  *    "capture the current location as the return" has no URL-shaped input to
  *    re-encode;
  *  - `c` does not look like a URL, so Better Auth's `callbackURL`, a proxy, or
@@ -42,7 +42,10 @@ export declare const SIGN_IN_CONTINUATION_PARAM = "c";
  * therefore will not be caught.
  */
 export declare const SIGN_IN_LEGACY_RETURN_PARAM = "return";
-export declare const SIGN_IN_ENTRY_PATH = "/_agent-native/sign-in";
+/** The clean, user-facing sign-in entry point emitted by current clients. */
+export declare const SIGN_IN_ENTRY_PATH = "/sign-in";
+/** The old framework entry point, retained for generated apps and bookmarks. */
+export declare const SIGN_IN_LEGACY_ENTRY_PATH = "/_agent-native/sign-in";
 /** Max length of an encoded continuation token, in characters. */
 export declare const SIGN_IN_CONTINUATION_MAX_LENGTH = 512;
 export interface SignInJourney {

package/dist/shared/sign-in-journey.js

@@ -18,7 +18,7 @@
  *  - `signInJourney` returns `signInHref: null` — no token at all — when the
  *    browser is already at an auth entry path, so the one function permitted
  *    to mint continuations refuses to mint the dangerous value;
- *  - the sign-in URL is `<base>/_agent-native/sign-in?c=<opaque>`, so
+ *  - the sign-in URL is `<base>/sign-in?c=<opaque>`, so
  *    "capture the current location as the return" has no URL-shaped input to
  *    re-encode;
  *  - `c` does not look like a URL, so Better Auth's `callbackURL`, a proxy, or
@@ -42,7 +42,10 @@ export const SIGN_IN_CONTINUATION_PARAM = "c";
  * therefore will not be caught.
  */
 export const SIGN_IN_LEGACY_RETURN_PARAM = "return";
-export const SIGN_IN_ENTRY_PATH = "/_agent-native/sign-in";
+/** The clean, user-facing sign-in entry point emitted by current clients. */
+export const SIGN_IN_ENTRY_PATH = "/sign-in";
+/** The old framework entry point, retained for generated apps and bookmarks. */
+export const SIGN_IN_LEGACY_ENTRY_PATH = "/_agent-native/sign-in";
 /** Max length of an encoded continuation token, in characters. */
 export const SIGN_IN_CONTINUATION_MAX_LENGTH = 512;
 /**
@@ -56,7 +59,8 @@ export const SIGN_IN_CONTINUATION_MAX_LENGTH = 512;
 function createSignInJourneyRuntime(basePath) {
     var PARAM = "c";
     var LEGACY_PARAM = "return";
-    var ENTRY_PATH = "/_agent-native/sign-in";
+    var ENTRY_PATH = "/sign-in";
+    var LEGACY_ENTRY_PATH = "/_agent-native/sign-in";
     var MAX_TOKEN = 512;
     var SENTINEL = "http://an.invalid";
     function normalizeBasePath(raw) {
@@ -79,7 +83,9 @@ function createSignInJourneyRuntime(basePath) {
         // including one this process was not configured with (a workspace host
         // serving a sibling app's URL).
         if (pathname === ENTRY_PATH ||
-            pathname.slice(-ENTRY_PATH.length) === ENTRY_PATH) {
+            pathname.slice(-ENTRY_PATH.length) === ENTRY_PATH ||
+            pathname === LEGACY_ENTRY_PATH ||
+            pathname.slice(-LEGACY_ENTRY_PATH.length) === LEGACY_ENTRY_PATH) {
             return true;
         }
         var rest = pathname;

package/dist/sharing/actions/set-resource-visibility.js

@@ -52,10 +52,22 @@ export default defineAction({
             }
         }
         const beforeExtensionTargets = await getExtensionShareChangeTargets(args.resourceType, args.resourceId);
-        await db
-            .update(reg.resourceTable)
-            .set(update)
-            .where(eq(reg.resourceTable.id, args.resourceId));
+        if (reg.persistVisibilityChange) {
+            await reg.persistVisibilityChange({
+                resource: access.resource,
+                resourceId: args.resourceId,
+                visibility: args.visibility,
+                update,
+                userEmail: rawAccess.userEmail,
+                orgId: currentOrgId,
+            });
+        }
+        else {
+            await db
+                .update(reg.resourceTable)
+                .set(update)
+                .where(eq(reg.resourceTable.id, args.resourceId));
+        }
         invalidateCollabAccessCache(args.resourceType, args.resourceId);
         await notifyExtensionShareChanged(args.resourceType, args.resourceId, beforeExtensionTargets);
         return { ok: true, visibility: args.visibility };

package/dist/sharing/registry.d.ts

@@ -110,6 +110,20 @@ export interface ShareableResourceRegistration {
      * the right DB instance (schema is template-specific).
      */
     getDb: () => any;
+    /**
+     * Optional resource-owned persistence hook for visibility changes. Use this
+     * when changing visibility must share a transaction with another invariant,
+     * such as reserving a human-readable name before the row becomes visible.
+     * The generic action falls back to a direct update when this is omitted.
+     */
+    persistVisibilityChange?: (args: {
+        resource: any;
+        resourceId: string;
+        visibility: "private" | "org" | "public";
+        update: Record<string, unknown>;
+        userEmail?: string;
+        orgId?: string;
+    }) => void | Promise<void>;
     /**
      * When `false`, `visibility: "public"` is rejected by `set-resource-visibility`,
      * and `accessFilter` / `resolveAccess` treat any stored public row as private

package/dist/styles/agent-native.css

@@ -128,6 +128,12 @@
   width: var(--agent-layout-left-drawer-expanded-width, 14rem);
 }
 
+.agent-layout-left-drawer[data-collapsed="false"] > * {
+  width: var(--agent-layout-left-drawer-expanded-width, 14rem);
+  min-width: var(--agent-layout-left-drawer-expanded-width, 14rem);
+  max-width: var(--agent-layout-left-drawer-expanded-width, 14rem);
+}
+
 .agent-layout-left-drawer .bg-sidebar {
   background: var(--agent-native-lower-surface) !important;
 }

package/dist/templates/chat/.agents/skills/turn-into-app/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: turn-into-app
+description: >-
+  Turn a proven thread, skill, or workflow into a runnable Agent-Native app
+  with simple buttons, visible agent steps, preview, and deployment handoff.
+  Use when a user invokes `/turn-into-app` or asks to make a workflow into an
+  app.
+user-invocable: true
+scope: both
+metadata:
+  internal: true
+---
+
+# Turn Into App
+
+## Default behavior
+
+This is an end-to-end build skill, not a request for an app proposal.
+
+- With no argument, use the current thread as the source. This is the normal
+  invocation at the end of a successful workflow.
+- With a named skill or local workflow, read that source and package it
+  immediately, even at the beginning of a thread. For example,
+  `/turn-into-app /some-skill` means “turn `/some-skill` into an app.”
+- With an attachment or path, read the supplied artifact as the source.
+- Do not ask the user to restate context that is already in the thread.
+- When invoked from an Agent-Native app, keep the current thread as the source
+  and use the available workspace/coding-agent handoff when the current runtime
+  cannot edit files. Do not claim the app exists without an actual path and
+  verification result.
+
+## Source support
+
+Supported source paths today are the current Codex thread, a named skill, or a
+local workflow/transcript supplied as a path or attachment. An exported
+ChatGPT or Claude transcript can use the same local-file path today.
+
+ChatGPT shared-conversation import and Claude web conversation/project import
+are **coming soon**. Do not claim private web access, invent an importer, add
+fake OAuth, or scrape a logged-in page without an explicit supported adapter.
+If a user gives one of those URLs before an adapter exists, ask for an export or
+transcript instead and treat it as imported source material.
+
+Deliver a fresh app in a new directory, implement the repeatable workflow with
+buttons and agent handoffs, start its dev server, verify the main path, and
+continue through build/deployment handoff. Do not stop at a plan.
+
+## Source selection guard
+
+The generated app must implement the concrete workflow found in the source. It
+must not become a generic “what app do you want to make?” intake form.
+
+- In a delegated or forked task, read the actual referenced source thread and
+  the latest explicit workflow direction in the current task. If they disagree,
+  the latest concrete workflow direction wins.
+- Do not treat a thread that merely discusses building this skill as the product
+  source unless the user explicitly asks to appify that meta-workflow.
+- If the source contains several workflows, choose the latest successful,
+  repeatable job that motivated the request and name it in the handoff. If no
+  concrete job can be identified, stop and report what is missing instead of
+  inventing an app-builder UI.
+
+## UI contract for generated apps
+
+Generated apps must follow the shared Agent-Native surface model:
+
+- Keep the domain workflow on a named route (`/workflow`, `/automations`,
+  `/block`, or the source's equivalent). Preserve the scaffold's full-page
+  chat route instead of replacing it with a domain form while leaving the
+  layout configured as a chat page.
+- Use the right `AgentSidebar` for contextual AI. Every button-triggered
+  `sendToAgentChat` handoff should open or focus that sidebar and keep the user
+  on the current domain page.
+- Use a sans-first SaaS hierarchy for the app shell. Choose a named visual
+  direction in `DESIGN.md` before styling: product mode, audience, palette
+  family, type treatment, composition, shape language, and anti-references.
+  One restrained editorial cue is welcome, but warm beige plus terracotta is
+  not the default and serif type belongs in content previews or a deliberate
+  brand moment rather than the whole tool.
+- Preserve existing brand tokens. For a new unbranded app, choose a
+  product-fitting palette family and compare sibling apps before reusing their
+  accent. Keep shared semantic tokens and Agent-Native behavior consistent
+  while varying the visual world, density, composition, and shape language.
+- Give the AgentSidebar a subtle surface or divider boundary so it is visually
+  distinct from the domain page without becoming a heavy panel wall.
+- Every AI-labeled button must actually call `sendToAgentChat` with bounded
+  context and `openSidebar: true`. Keep `submit: true` for direct execution and
+  `submit: false` only when the user should edit the staged prompt first. Label
+  deterministic local actions as local, preview, or analyze instead of AI.
+- Standalone apps that render `AgentSidebar` must keep one assistant-ui runtime
+  context. Pin the versions compatible with the installed core/toolkit peer
+  graph, and add Vite dedupe/aliases when linked or transitive packages resolve
+  duplicate assistant-ui modules. Verify a fresh AI handoff has no
+  `AssistantUiStaleIndexErrorBoundary` or stale-index console error.
+- Make the left navigation describe domain destinations. Chat is a separate
+  destination, not the label for every app page.
+- Start with one primary action and one compact state. Put setup choices,
+  advanced inputs, diagnostics, and long explanations behind progressive
+  disclosure or later workflow steps.
+- Never use sparkle, wand, magic, robot, or similar decorative AI icons. Use a
+  message or neutral action icon, or no icon when the button label is enough.
+- Before handoff, inspect the first viewport for text density, repeated cards,
+  unrelated forms, and generic helper copy. Remove what the user does not need
+  until the next decision.
+- Run a `distill`, `typeset`, `colorize`, `layout`, `polish`, and `audit` pass
+  as useful named reviews. Make one intervention at a time and commit the
+  chosen direction rather than averaging several options into generic SaaS.
+- For before/after or original/generated review, stack the source first and the
+  result second by default. Reserve side-by-side layouts for short content that
+  remains comfortable to scan at the target width.
+
+## 1. Extract the workflow
+
+Read the full available source before coding. Reduce it to a short working
+brief:
+
+- the user and repeatable job;
+- inputs and outputs;
+- the 1-3 judgment-heavy agent moments;
+- the buttons, review points, and retry states a user needs;
+- data, permissions, integrations, and failure boundaries.
+
+Preserve useful judgment from the source, but do not turn a one-off answer,
+private data, or an unverified result into a product contract. If the source is
+not available or does not contain a repeatable job, say what is missing rather
+than claiming the app is complete.
+
+## 2. Create a fresh app
+
+Choose a short slug from the workflow and create a new directory. Never
+overwrite an existing app. If the user supplied a directory, use it; otherwise
+use `apps/<slug>` inside an existing Agent-Native workspace, or a new sibling
+directory when working outside one.
+
+For a new UI-bearing standalone app, use the current Agent-Native scaffold and
+then read the generated `AGENTS.md`:
+
+```bash
+npx @agent-native/core@latest create <app-directory> --template chat
+cd <app-directory>
+pnpm install
+```
+
+When working inside an existing Agent-Native workspace, create the app from
+the workspace root instead:
+
+```bash
+pnpm exec agent-native add-app <slug> --template=chat
+```
+
+Do not use `create` for an existing workspace; it scaffolds a new standalone
+workspace rather than adding an app to the current one.
+
+Use a first-party template only when it materially fits the workflow. Keep the
+new app independent from the source thread's working tree unless the user
+explicitly asks to extend an existing app.
+
+Read the generated `DESIGN.md` before building the first screen and fill in the
+visual direction as part of the app brief. Do not copy the previous app's
+palette just because its tokens are nearby.
+
+## 3. Turn the workflow into buttons and agent work
+
+Implement the smallest useful surface around the extracted brief. The app
+should make the repeated path obvious without hiding the agent's judgment:
+
+- Give each important repeated moment a clear button, such as “Analyze,”
+  “Suggest options,” “Draft,” “Review,” or “Publish.” Use the source's actual
+  vocabulary when it is clear.
+- Put deterministic reads, writes, approvals, and publishing in `actions/`
+  with `defineAction`. The UI and agent must call the same action surface.
+- Use application state for the current screen, selected item, and focused
+  object so the agent can see where the user is.
+- Use `sendToAgentChat({ message, context, submit: true })` for intentional
+  button-triggered agent work. Use `submit: false` when the user should review
+  or edit the proposed prompt first.
+- Pass IDs, URLs, and bounded summaries in context. Do not paste large provider
+  dumps into prompts, call an LLM directly from the browser, or invent fake
+  progress.
+- Make agent results visible, editable, retryable, and attributable. Keep
+  irreversible actions behind an explicit review or confirmation point.
+
+Use the existing shadcn/ui primitives, Tabler icons, shared composer, and
+optimistic action patterns. Do not add a parallel CRUD API route for an action.
+
+## 4. Keep onboarding shared
+
+Use the framework's existing setup experience. The app should offer the normal
+“Connect Builder” and “Add your own keys” paths for AI setup. Do not create a
+second credential form or hardcode a provider key.
+
+In local-development instructions, add a brief note that a developer can set
+an environment variable such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` before
+starting the app; after restart, the setup prompt is no longer shown when the
+key is available. Keep real secrets out of source, examples, and generated
+content.
+
+Turn-into-app apps should commit an `agent-native.json` app configuration so a
+plain `pnpm dev` has the right first-run behavior without extra flags:
+
+```json
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "connect",
+      "production": "connect-and-integrations"
+    }
+  }
+}
+```
+
+`connect` keeps the Connect Builder / Add your own keys choice visible and
+skips only the generic “This app is an agent.” integrations catalog. The
+production value includes that catalog for a hosted app. Do not replace this
+with a local credential form or remove the shared onboarding. In development,
+the shared Connect Builder card also explains the deployment-level
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` fallback and links to the full
+environment-variable guide.
+
+When the onboarding default needs code rather than a static mode map, add an
+optional `agent-native.config.ts` with the same returned shape:
+
+```ts
+import { defineAgentNativeConfig } from "@agent-native/core/config";
+
+export default defineAgentNativeConfig(({ isDev }) => ({
+  version: 1,
+  onboarding: {
+    firstRun: isDev ? "connect" : "connect-and-integrations",
+  },
+}));
+```
+
+The Vite preset loads this file automatically on supported Node versions. The
+JSON file remains the portable, inspectable fallback. See the [Agent-Native
+app configuration guide](/docs/agent-native-config) for precedence, supported
+modes, and the boundary between committed config and deployment secrets.
+
+For an account-free local preview, create the ignored local `.env` file with
+`AUTH_DISABLED=1` before starting the dev server. This is only for loopback
+development; never commit or deploy this setting. AI/provider connections still
+use the normal onboarding flow or the documented environment-variable keys.
+
+## 5. Run it immediately
+
+From the new app directory:
+
+```bash
+pnpm dev
+```
+
+For a fresh local test app, use the ignored `.env` with `AUTH_DISABLED=1` so the
+domain UI opens without an account; the committed app config makes shared
+onboarding visible. Keep the process running so the user can try the app. Read
+the actual server output and report the real local URL. If the app needs installation or a setup step,
+complete it when possible and distinguish “not configured” from an unavailable
+credential store.
+
+## 6. Verify, build, and deploy
+
+Exercise the actual happy path, not only the source files:
+
+1. Load the reported URL and confirm the main route renders.
+2. Confirm the shared onboarding state or a configured local key.
+3. Click the primary workflow button and confirm the intended agent handoff.
+   Also click every other AI-labeled button and confirm it opens the same
+   contextual sidebar with the expected prompt or staged context.
+4. Confirm the result, action persistence, application state, and sync path.
+5. Check the dev output for browser/runtime errors, and capture input, result,
+   and agent-sidebar states so the complete flow is reviewable.
+
+Then run the supported build. For a standalone app, use the generated app's
+documented build and hosting path. For an app inside a workspace, use the
+workspace deploy command, for example:
+
+```bash
+npx @agent-native/core@latest build
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+Use `vercel` or another supported preset when that is the configured target.
+Attempt deployment when the user requested it or the project already has the
+required provider configuration. If external authentication, a production
+secret, or a hosting decision is missing, finish local verification and report
+the exact remaining handoff without claiming a live deployment.
+
+Label evidence separately: locally running, locally verified, build-ready,
+deployed, and live-verified are different states.
+
+## Handoff
+
+End with the new app directory, local URL, visual direction, what the buttons do,
+account-free local-preview status, verification performed, deployment URL if it is real,
+and one precise pending step when something could not be completed. Keep the
+handoff short enough to use in a demo or recording.

package/dist/templates/chat/.agents/skills/turn-into-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Turn Into App"
+  short_description: "Turn a thread or skill into a runnable app"
+  default_prompt: "Scan the current thread, turn the workflow into a new Agent-Native app with clear buttons, run it locally, verify it, and complete the deployment handoff."