@agent-native/core 0.149.2 → 0.149.4

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -76,8 +76,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }>>;
 }, z.core.$strip>>, {
     id?: undefined;
-    provider?: undefined;
     deleted?: undefined;
+    provider?: undefined;
     providers: {
         id: string;
         label: string;
@@ -94,8 +94,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     id?: undefined;
-    count?: undefined;
     deleted?: undefined;
+    count?: undefined;
     providers?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
@@ -103,9 +103,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
+    deleted?: undefined;
     count?: undefined;
     provider?: undefined;
-    deleted?: undefined;
     providers?: undefined;
     found: boolean;
     id: string;
@@ -123,9 +123,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
+    deleted?: undefined;
     count?: undefined;
     provider?: undefined;
-    deleted?: undefined;
     providers?: undefined;
     found?: undefined;
     registered: boolean;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,8 +311,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        deleted?: undefined;
+        message?: undefined;
         id?: undefined;
+        deleted?: undefined;
         providers: {
             id: string;
             label: string;
@@ -327,28 +328,28 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         found?: undefined;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
-        deleted?: undefined;
+        message?: undefined;
         count?: undefined;
         id?: undefined;
+        deleted?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
-        deleted?: undefined;
+        message?: undefined;
         count?: undefined;
+        deleted?: undefined;
         providers?: undefined;
         provider?: undefined;
         found: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
+        message?: undefined;
         count?: undefined;
         providers?: undefined;
         provider?: undefined;
@@ -357,10 +358,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         id: string;
         registered?: undefined;
         label?: undefined;
-        message?: undefined;
     } | {
-        deleted?: undefined;
         count?: undefined;
+        deleted?: undefined;
         providers?: undefined;
         provider?: undefined;
         found?: undefined;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/scripts/docs/source-search.js

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseSkillFrontmatter } from "../../server/agents-bundle.js";
+import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "../../server/agents-bundle.js";
 import { isValidPath, parseArgs } from "../utils.js";
 const MAX_FILE_BYTES = 1_000_000;
 const MAX_READ_CHARS = 40_000;
@@ -155,7 +155,7 @@ function isRuntimeVisibleCorpusPath(corpusRoot, absolutePath) {
         return true;
     try {
         const raw = fs.readFileSync(skillEntryPath, "utf-8");
-        return parseSkillFrontmatter(raw).scope !== "dev";
+        return isRuntimeVisibleScope(parseSkillFrontmatter(raw).scope);
     }
     catch {
         return true;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-chat/framework-prompts.js

@@ -22,6 +22,11 @@ import { lazyFs } from "./lazy-fs.js";
 export function buildFrameworkPrompts(examples, options) {
     const FRAMEWORK_CORE = buildFrameworkCore(examples, options);
     const FRAMEWORK_CORE_COMPACT = buildFrameworkCoreCompact(examples, options);
+    // Dev agents edit source directly, so their copy of the core drops the
+    // production-only "hand code changes to Builder" sentence.
+    const devCoreOptions = { ...options, canEditSource: true };
+    const DEV_FRAMEWORK_CORE = buildFrameworkCore(examples, devCoreOptions);
+    const DEV_FRAMEWORK_CORE_COMPACT = buildFrameworkCoreCompact(examples, devCoreOptions);
     const extensionToolsEnabled = options?.extensionTools === true;
     const planModeArtifactList = extensionToolsEnabled
         ? "source-code handoffs and app-created artifacts such as extensions, widgets, dashboards, calculators, mini-apps, documents, designs, slides, or videos"
@@ -107,7 +112,7 @@ When editing code, follow the agent-native architecture:
 - All SQL must be dialect-agnostic (works on SQLite and Postgres)
 - No Node.js-specific APIs in server routes (must work on Cloudflare Workers, etc.)
 - Use shadcn/ui components and Tabler Icons for all UI work
-${FRAMEWORK_CORE}`;
+${DEV_FRAMEWORK_CORE}`;
     const PROD_FRAMEWORK_PROMPT_COMPACT = `## Agent-Native Framework — Production Mode
 
 You are an AI agent in an agent-native application, running in **production mode**.
@@ -141,7 +146,7 @@ When editing code, follow the agent-native architecture:
 - All SQL must be dialect-agnostic (works on SQLite and Postgres)
 - No Node.js-specific APIs in server routes (must work on Cloudflare Workers, etc.)
 - Use shadcn/ui components and Tabler Icons for all UI work
-${FRAMEWORK_CORE_COMPACT}`;
+${DEV_FRAMEWORK_CORE_COMPACT}`;
     return {
         FRAMEWORK_CORE,
         FRAMEWORK_CORE_COMPACT,

package/dist/server/agent-chat/prompt-resources.js

@@ -3,7 +3,7 @@ import { getFrontmatterValue, getSkillNameFromPath, parseFrontmatter, } from "..
 import { ensurePersonalDefaults, organizationIdFromResourceOwner, resourceGet, resourceGetByPath, resourceList, resourceListAccessible, SHARED_OWNER, sharedResourceOwner, WORKSPACE_OWNER, } from "../../resources/store.js";
 import { discoverAgents } from "../agent-discovery.js";
 import { getRequestOrgId } from "../request-context.js";
-import { parseSkillFrontmatter } from "./skill-frontmatter.js";
+import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "./skill-frontmatter.js";
 // ---------------------------------------------------------------------------
 // System-prompt resource loading: AGENTS.md, instructions/*.md, skills
 // summaries, and the shared/workspace resource index. Assembled by
@@ -523,7 +523,7 @@ async function loadResourceSkillsPromptBlock(owner, orgId) {
             const meta = parseSkillFrontmatter(full.content);
             if (meta.userInvocable === false)
                 continue;
-            if (meta.scope === "dev")
+            if (!isRuntimeVisibleScope(meta.scope))
                 continue;
             const name = meta.name || getSkillNameFromPath(resource.path);
             if (!name || seen.has(name))

package/dist/server/agent-chat/skill-frontmatter.d.ts

@@ -1,6 +1,35 @@
-export declare function parseSkillFrontmatter(content: string): {
+/**
+ * Where a skill is meant to be used:
+ *   - `runtime` — only the in-app agent at runtime.
+ *   - `dev`     — only the human's development/coding agent (e.g. Claude Code).
+ *                 Hidden from the runtime agent everywhere.
+ *   - `both`    — loaded everywhere. The default when `scope` is absent.
+ *   - `invalid` — never written by hand: the parse result for a `scope:` nobody
+ *                 recognizes. See `normalizeSkillScope`.
+ */
+export type SkillScope = "runtime" | "dev" | "both" | "invalid";
+export declare const DEFAULT_SKILL_SCOPE: SkillScope;
+/**
+ * An unrecognized `scope:` can neither throw nor fall back to `both`.
+ * Throwing would be swallowed: every caller parses inside a `catch` that skips
+ * the skill (`readSkillsDir`) or falls back to a permissive default, so at
+ * production cold start the skill would vanish with no log — the same
+ * invisible failure pointed the other way. Falling back to `both` ships a
+ * dev-only skill's body to the deployed agent, which is the bug this sentinel
+ * exists to prevent. So `invalid` stays distinguishable from an absent scope,
+ * is loud once per file+value, and is excluded from the runtime agent's view
+ * while the development agent still sees the skill and the mistake.
+ */
+export declare function normalizeSkillScope(raw: string | undefined, sourceLabel?: string): SkillScope;
+/**
+ * The one runtime-visibility gate. A skill whose scope could not be read is
+ * withheld alongside `dev`, so a typo fails closed instead of leaking the body
+ * into the deployed agent's prompt and docs-search.
+ */
+export declare function isRuntimeVisibleScope(scope: SkillScope | undefined): boolean;
+export declare function parseSkillFrontmatter(content: string, sourceLabel?: string): {
     name?: string;
     description?: string;
     userInvocable?: boolean;
-    scope?: "runtime" | "dev" | "both";
+    scope?: SkillScope;
 };

package/dist/server/agent-chat/skill-frontmatter.js

@@ -1,25 +1,51 @@
 import { getFrontmatterValue, parseFrontmatter, } from "../../resources/metadata.js";
-export function parseSkillFrontmatter(content) {
+export const DEFAULT_SKILL_SCOPE = "both";
+const warnedBadScopes = new Set();
+/**
+ * An unrecognized `scope:` can neither throw nor fall back to `both`.
+ * Throwing would be swallowed: every caller parses inside a `catch` that skips
+ * the skill (`readSkillsDir`) or falls back to a permissive default, so at
+ * production cold start the skill would vanish with no log — the same
+ * invisible failure pointed the other way. Falling back to `both` ships a
+ * dev-only skill's body to the deployed agent, which is the bug this sentinel
+ * exists to prevent. So `invalid` stays distinguishable from an absent scope,
+ * is loud once per file+value, and is excluded from the runtime agent's view
+ * while the development agent still sees the skill and the mistake.
+ */
+export function normalizeSkillScope(raw, sourceLabel) {
+    if (!raw?.trim())
+        return DEFAULT_SKILL_SCOPE;
+    const value = raw.trim().toLowerCase();
+    if (value === "runtime" || value === "dev" || value === "both")
+        return value;
+    const warnKey = `${sourceLabel ?? ""}\u0000${value}`;
+    if (!warnedBadScopes.has(warnKey)) {
+        warnedBadScopes.add(warnKey);
+        console.error(`[skill-frontmatter] Invalid scope "${raw.trim()}" in ${sourceLabel ?? "an unidentified SKILL.md"} — valid values are runtime, dev, both. Hiding this skill from the runtime agent until it is fixed.`);
+    }
+    return "invalid";
+}
+/**
+ * The one runtime-visibility gate. A skill whose scope could not be read is
+ * withheld alongside `dev`, so a typo fails closed instead of leaking the body
+ * into the deployed agent's prompt and docs-search.
+ */
+export function isRuntimeVisibleScope(scope) {
+    return scope !== "dev" && scope !== "invalid";
+}
+export function parseSkillFrontmatter(content, sourceLabel) {
     const frontmatter = parseFrontmatter(content);
     const userInvocable = getFrontmatterValue(frontmatter, "user-invocable");
-    const scope = normalizeSkillFrontmatterScope(getFrontmatterValue(frontmatter, "scope"));
+    const rawScope = getFrontmatterValue(frontmatter, "scope");
+    const name = getFrontmatterValue(frontmatter, "name");
     return {
-        name: getFrontmatterValue(frontmatter, "name"),
+        name,
         description: getFrontmatterValue(frontmatter, "description"),
-        scope,
+        scope: rawScope
+            ? normalizeSkillScope(rawScope, sourceLabel ?? name)
+            : undefined,
         userInvocable: userInvocable === undefined
             ? undefined
             : userInvocable.toLowerCase() === "true",
     };
 }
-function normalizeSkillFrontmatterScope(value) {
-    if (!value)
-        return undefined;
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "runtime" ||
-        normalized === "dev" ||
-        normalized === "both") {
-        return normalized;
-    }
-    return "both";
-}

package/dist/server/agent-chat-plugin.js

@@ -118,7 +118,7 @@ import { isNetlifyRecurringJobsRuntime, shouldDisableRecurringJobsRuntime, } fro
 import { isLocalhost, shouldBlockInProductCodeEditingSurface, } from "./agent-chat/request-surface.js";
 import { loadRunCodeToolEntries } from "./agent-chat/run-code-tools.js";
 import { createAgentEngineScriptEntries, createAgentLoopSettingsScriptEntries, createCallAgentScriptEntry, createChatScriptEntries, createDbScriptEntries, createDocsScriptEntries, createResourceScriptEntries, } from "./agent-chat/script-entries.js";
-import { parseSkillFrontmatter } from "./agent-chat/skill-frontmatter.js";
+import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "./agent-chat/skill-frontmatter.js";
 import { shouldDisableInProcessSweeps } from "./sweep-runtime.js";
 export { loadResourcesForPrompt };
 export { _agentChatPromptSectionsForTests };
@@ -3373,7 +3373,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                                     const fm = parseSkillFrontmatter(content);
                                     if (fm.userInvocable === false)
                                         continue;
-                                    if (fm.scope === "dev")
+                                    if (!isRuntimeVisibleScope(fm.scope))
                                         continue;
                                     const skillName = fm.name || entry.name.replace(/\.md$/, "");
                                     if (!seenNames.has(skillName)) {
@@ -3455,7 +3455,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                                 : undefined);
                             if (full) {
                                 const fm = parseSkillFrontmatter(full.content);
-                                if (fm.scope === "dev")
+                                if (!isRuntimeVisibleScope(fm.scope))
                                     continue;
                                 if (fm.name)
                                     skillName = fm.name;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/agents-bundle.d.ts

@@ -20,23 +20,16 @@
  *
  * Result is cached in module scope so it's only computed once per cold start.
  */
-/**
- * Where a skill is meant to be used:
- *   - `runtime` — only the in-app agent at runtime (not the human's coding agent).
- *   - `dev`     — only the human's development/coding agent (e.g. Claude Code).
- *                 EXCLUDED from the runtime agent's prompt block and docs-search.
- *   - `both`    — loaded everywhere. This is the default when `scope` is absent
- *                 or set to an unrecognized value (fully backward compatible).
- */
-export type SkillScope = "runtime" | "dev" | "both";
-export declare const DEFAULT_SKILL_SCOPE: SkillScope;
+import { DEFAULT_SKILL_SCOPE, isRuntimeVisibleScope, normalizeSkillScope, type SkillScope } from "./agent-chat/skill-frontmatter.js";
+export { DEFAULT_SKILL_SCOPE, isRuntimeVisibleScope, normalizeSkillScope, type SkillScope, };
 export interface SkillMeta {
     name: string;
     description: string;
     /**
      * Audience for the skill. Defaults to `both` when the SKILL.md frontmatter
-     * omits `scope` or specifies an unknown value. `dev`-scoped skills are hidden
-     * from the runtime agent everywhere (prompt block + docs-search).
+     * omits `scope`. An unrecognized value parses to `invalid`, which is hidden
+     * from the runtime agent everywhere (prompt block + docs-search) exactly
+     * like `dev`. `dev`-scoped skills are likewise hidden from the runtime agent.
      */
     scope: SkillScope;
 }
@@ -104,7 +97,6 @@ export interface AgentInstructionPaths {
     development: string;
 }
 export declare function resolveAgentInstructionPaths(instructions?: AgentNativeInstructionsConfig): AgentInstructionPaths;
-export declare function normalizeSkillScope(raw: string | undefined): SkillScope;
 /**
  * Parse the YAML frontmatter at the top of a skill file.
  * Only pulls out `name`, `description`, and `scope` — deliberately simple, no
@@ -113,8 +105,11 @@ export declare function normalizeSkillScope(raw: string | undefined): SkillScope
  *   - Inline: `description: Some text`
  *   - Folded scalar: `description: >-\n  multi\n  line` → "multi line"
  *   - Literal scalar: `description: |\n  multi\n  line` → "multi\nline"
+ *
+ * `sourceLabel` only names the file in the invalid-scope log; pass it wherever
+ * a path is known so a typo is traceable to the SKILL.md that carries it.
  */
-export declare function parseSkillFrontmatter(content: string): Partial<SkillMeta>;
+export declare function parseSkillFrontmatter(content: string, sourceLabel?: string): Partial<SkillMeta>;
 import type { AgentNativeInstructionsConfig } from "../config.js";
 /**
  * Paths to a workspace-core's agent resources, for merging into a template's
@@ -160,15 +155,17 @@ export declare function loadAgentsBundle(): Promise<AgentsBundle>;
  */
 /**
  * Skills visible to the agent-native RUNTIME agent. Excludes `scope: dev`
- * skills (those are for the human's coding agent only). Skills with no scope,
- * `scope: runtime`, or `scope: both` are all included. Use this anywhere the
- * runtime agent's view of skills is built (prompt block + docs-search) so a
- * dev-scoped skill is invisible to the runtime agent everywhere.
+ * skills (those are for the human's coding agent only) and skills whose scope
+ * could not be read. Skills with no scope, `scope: runtime`, or `scope: both`
+ * are all included. Use this anywhere the runtime agent's view of skills is
+ * built (prompt block + docs-search) so a dev-scoped skill is invisible to the
+ * runtime agent everywhere.
  */
 export declare function getRuntimeSkills(bundle: AgentsBundle): Skill[];
 /**
  * Skills visible to development/coding agents. Excludes `scope: runtime`
- * skills that are intended only for the deployed in-app agent.
+ * skills that are intended only for the deployed in-app agent. An `invalid`
+ * scope stays visible here on purpose — this is the audience that can fix it.
  */
 export declare function getDevelopmentSkills(bundle: AgentsBundle): Skill[];
 export declare function skillDocsSlug(name: string): string;

package/dist/server/agents-bundle.js

@@ -20,7 +20,8 @@
  *
  * Result is cached in module scope so it's only computed once per cold start.
  */
-export const DEFAULT_SKILL_SCOPE = "both";
+import { DEFAULT_SKILL_SCOPE, isRuntimeVisibleScope, normalizeSkillScope, } from "./agent-chat/skill-frontmatter.js";
+export { DEFAULT_SKILL_SCOPE, isRuntimeVisibleScope, normalizeSkillScope, };
 const DEFAULT_AGENT_INSTRUCTIONS_PATH = "AGENTS.md";
 export function resolveAgentInstructionPaths(instructions) {
     return {
@@ -29,26 +30,6 @@ export function resolveAgentInstructionPaths(instructions) {
     };
 }
 let cached = null;
-/**
- * Coerce a raw frontmatter `scope` value into a known `SkillScope`. Unknown,
- * empty, or malformed values fall back to the default (`both`) so a typo never
- * silently hides a skill from the runtime agent. Optionally warns once per
- * distinct bad value to aid debugging without spamming logs.
- */
-const warnedBadScopes = new Set();
-export function normalizeSkillScope(raw) {
-    if (!raw)
-        return DEFAULT_SKILL_SCOPE;
-    const value = raw.trim().toLowerCase();
-    if (value === "runtime" || value === "dev" || value === "both") {
-        return value;
-    }
-    if (value && !warnedBadScopes.has(value)) {
-        warnedBadScopes.add(value);
-        console.warn(`[agents-bundle] Unknown skill scope "${raw}" — treating as "${DEFAULT_SKILL_SCOPE}". Valid values: runtime, dev, both.`);
-    }
-    return DEFAULT_SKILL_SCOPE;
-}
 /**
  * Parse the YAML frontmatter at the top of a skill file.
  * Only pulls out `name`, `description`, and `scope` — deliberately simple, no
@@ -57,8 +38,11 @@ export function normalizeSkillScope(raw) {
  *   - Inline: `description: Some text`
  *   - Folded scalar: `description: >-\n  multi\n  line` → "multi line"
  *   - Literal scalar: `description: |\n  multi\n  line` → "multi\nline"
+ *
+ * `sourceLabel` only names the file in the invalid-scope log; pass it wherever
+ * a path is known so a typo is traceable to the SKILL.md that carries it.
  */
-export function parseSkillFrontmatter(content) {
+export function parseSkillFrontmatter(content, sourceLabel) {
     const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
     if (!match)
         return {};
@@ -106,7 +90,7 @@ export function parseSkillFrontmatter(content) {
         else if (key === "description" && value)
             result.description = value;
         else if (key === "scope" && value)
-            result.scope = normalizeSkillScope(value);
+            result.scope = normalizeSkillScope(value, sourceLabel ?? result.name);
     }
     return result;
 }
@@ -170,7 +154,7 @@ function readSkillsDir(skillsDir, rootForRelative, out, skipExistingNames) {
             if (!fs.existsSync(realSkillFile))
                 continue;
             const content = fs.readFileSync(realSkillFile, "utf-8");
-            const meta = parseSkillFrontmatter(content);
+            const meta = parseSkillFrontmatter(content, path.relative(rootForRelative, skillFile).replace(/\\/g, "/"));
             const name = meta.name ?? entry.name;
             if (skipExistingNames && out[name])
                 continue; // Template wins
@@ -375,17 +359,19 @@ export async function loadAgentsBundle() {
  */
 /**
  * Skills visible to the agent-native RUNTIME agent. Excludes `scope: dev`
- * skills (those are for the human's coding agent only). Skills with no scope,
- * `scope: runtime`, or `scope: both` are all included. Use this anywhere the
- * runtime agent's view of skills is built (prompt block + docs-search) so a
- * dev-scoped skill is invisible to the runtime agent everywhere.
+ * skills (those are for the human's coding agent only) and skills whose scope
+ * could not be read. Skills with no scope, `scope: runtime`, or `scope: both`
+ * are all included. Use this anywhere the runtime agent's view of skills is
+ * built (prompt block + docs-search) so a dev-scoped skill is invisible to the
+ * runtime agent everywhere.
  */
 export function getRuntimeSkills(bundle) {
-    return Object.values(bundle.skills).filter((skill) => skill.meta.scope !== "dev");
+    return Object.values(bundle.skills).filter((skill) => isRuntimeVisibleScope(skill.meta.scope));
 }
 /**
  * Skills visible to development/coding agents. Excludes `scope: runtime`
- * skills that are intended only for the deployed in-app agent.
+ * skills that are intended only for the deployed in-app agent. An `invalid`
+ * scope stays visible here on purpose — this is the audience that can fix it.
  */
 export function getDevelopmentSkills(bundle) {
     return Object.values(bundle.skills).filter((skill) => skill.meta.scope !== "runtime");
@@ -437,14 +423,12 @@ function generateSkillsPromptBlockForEntries(entries, mode) {
                 extras = ` (also contains: ${s.extraFiles.join(", ")})`;
             }
         }
-        const runtimeHint = mode === "runtime"
-            ? ` Read with \`docs-search --slug "${skillDocsSlug(s.meta.name)}"\` before starting a task it applies to.`
-            : "";
+        const runtimeHint = mode === "runtime" ? ` [${skillDocsSlug(s.meta.name)}]` : "";
         return `- \`${s.meta.name}\` at \`${s.dir}/\` — ${s.meta.description || "(no description)"}${extras}${runtimeHint}`;
     });
     const readHint = mode === "runtime"
-        ? `To read a skill in the in-app runtime agent:
-  \`docs-search --slug "skill-<skill-name>"\`
+        ? `To read a skill in the in-app runtime agent, before starting a task it applies to:
+  \`docs-search --slug "<slug>"\` — each skill's slug is the [bracketed] token ending its line
   \`docs-search --query "<topic>"\` to discover matching docs/skills`
         : `To read a skill in dev mode (when you have bash access):
   \`bash(command="cat <skill-dir>/SKILL.md")\`

package/dist/server/better-auth-instance.d.ts

@@ -253,3 +253,4 @@ export declare function resetBetterAuth(): Promise<void>;
 export declare function configureLocalSqlite(sqlite: {
     pragma(statement: string): unknown;
 }): void;
+export declare function buildDatabaseConfig(dialect: string): Promise<BetterAuthOptions["database"]>;

package/dist/server/better-auth-instance.js

@@ -16,7 +16,7 @@ import { pgTable, text as pgText, timestamp as pgTimestamp, boolean as pgBoolean
 import { sqliteTable, text as sqliteText, integer as sqliteInteger, } from "drizzle-orm/sqlite-core";
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { getDbExec, isPostgres } from "../db/client.js";
-import { getDialect, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolOptions, guardNeonPool, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "../db/client.js";
+import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolOptions, guardNeonPool, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "../db/client.js";
 import { CORE_RESET_PASSWORD_EMAIL_ID, CORE_VERIFY_SIGNUP_EMAIL_ID, } from "../email-catalog/system-emails.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
@@ -1126,7 +1126,7 @@ export function configureLocalSqlite(sqlite) {
     sqlite.pragma("busy_timeout = 10000");
     sqlite.pragma("journal_mode = WAL");
 }
-async function buildDatabaseConfig(dialect) {
+export async function buildDatabaseConfig(dialect) {
     if (dialect === "postgres") {
         const url = getDatabaseUrl();
         const { buildResilientNeonPool, buildResilientPostgresJsClient, isNeonUrl, } = await import("../db/create-get-db.js");
@@ -1180,6 +1180,21 @@ async function buildDatabaseConfig(dialect) {
             schema: pgAuthSchema,
         });
     }
+    if (dialect === "d1") {
+        const d1 = getCloudflareD1Binding();
+        if (!d1) {
+            throw new Error("Cloudflare D1 database binding is unavailable; configure the DB binding before initializing Better Auth.");
+        }
+        const { drizzle } = await import("drizzle-orm/d1");
+        const db = drizzle(d1, {
+            schema: sqliteAuthSchema,
+        });
+        const { drizzleAdapter } = await import("better-auth/adapters/drizzle");
+        return drizzleAdapter(db, {
+            provider: "sqlite",
+            schema: sqliteAuthSchema,
+        });
+    }
     // SQLite / libsql
     const url = getDatabaseUrl("file:./data/app.db");
     if (url.startsWith("file:") || !url.includes("://")) {

package/dist/server/prompts/framework-core-compact.d.ts

@@ -2,7 +2,7 @@
  * Compact framework core instructions (FRAMEWORK_CORE_COMPACT).
  * Used in lazy-context mode (lazyContext: true — the default).
  *
- * Shares rules 8–9, 12–13 with the full variant via shared-rules.ts.
+ * Shares rules 8–9, 13–15 with the full variant via shared-rules.ts.
  * The compact version omits:
  *   - Verbose "Extended Capabilities" section (agent uses get-framework-context)
  *   - Detailed "Parallel Tool Calls" prose (replaced with one-liner)
@@ -18,6 +18,11 @@ export interface FrameworkCoreCompactPromptOptions {
      *  a group's tool by name is gated on this — a prompt naming an absent tool
      *  makes the model call it, fail, and often report the capability as missing. */
     disabledFrameworkGroups?: ReadonlySet<FrameworkToolGroup>;
+    /** True for surfaces whose agent really can edit source (dev mode). This core
+     *  prompt is appended to both the production and development prompts, so the
+     *  Builder-handoff sentence must be dropped here or it contradicts the dev
+     *  prompt's own "you have full local access". */
+    canEditSource?: boolean;
 }
 /**
  * Build the compact FRAMEWORK_CORE prompt string.