@agent-native/core 0.182.0 → 0.182.1-nightly-20260916202735

package/dist/deploy/build.js

@@ -1967,7 +1967,7 @@ function patchReactRouterServerManifestSource(source, serverBuildFile, clientMan
         const replacement = JSON.stringify(mergeReactRouterServerManifest(serverManifest, clientManifest));
         return (source.slice(0, valueStart) + replacement + source.slice(assignmentEnd));
     }
-    const assignments = /\b[A-Za-z_$][\w$]*\s*=\s*(\{\s*(?:entry|["']entry["'])\s*:)/g;
+    const assignments = /(?:\b[A-Za-z_][\w$]*|\$[\w$]*)\s*=\s*(\{\s*(?:entry|["']entry["'])\s*:)/g;
     for (const match of source.matchAll(assignments)) {
         const valueStart = match.index + match[0].lastIndexOf("{");
         const valueEnd = findJavaScriptObjectEnd(source, valueStart);

package/dist/file-upload/actions/upload-image.d.ts

@@ -17,11 +17,11 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
-    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
+    error?: undefined;
 }>;
 export default _default;

package/dist/notifications/routes.d.ts

@@ -28,6 +28,6 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    id?: undefined;
+    error?: undefined;
+    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
+    id?: undefined;
+} | {
     error?: undefined;
     ok?: undefined;
-} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
-    ok?: undefined;
 } | {
-    id?: undefined;
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
+    id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
-    id?: undefined;
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
+    id?: undefined;
     ok: boolean;
-    error?: undefined;
 }>>;

package/dist/org/handlers.d.ts

@@ -52,9 +52,9 @@ export declare const setWorkspaceAppDefaultVisibilityHandler: import("h3").Event
 }>>;
 /** POST /_agent-native/org — create a new organization */
 export declare const createOrgHandler: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    name?: undefined;
     success: boolean;
     id?: undefined;
-    name?: undefined;
     role?: undefined;
 } | {
     success?: undefined;

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

@@ -311,7 +311,6 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        message?: undefined;
         id?: undefined;
         provider?: undefined;
         deleted?: undefined;
@@ -328,8 +327,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         count: number;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         id?: undefined;
         deleted?: undefined;
         providers?: undefined;
@@ -338,8 +337,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         provider?: undefined;
         deleted?: undefined;
         providers?: undefined;
@@ -348,8 +347,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         id: string;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         provider?: undefined;
         found?: undefined;
         providers?: undefined;
@@ -358,6 +357,7 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         id: string;
         registered?: undefined;
         label?: undefined;
+        message?: undefined;
     } | {
         provider?: undefined;
         deleted?: 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<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/collab-plugin.d.ts

@@ -12,6 +12,7 @@
  * });
  * ```
  */
+import { type DbExec } from "../db/client.js";
 type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 export type CollabResourceIdResolver = (docId: string) => string | null | Promise<string | null>;
 export type CollabAccess = {
@@ -39,10 +40,16 @@ export interface CollabPluginOptions {
     contentColumn?: string;
     /** Column name for the document ID. Default: "id" */
     idColumn?: string;
-    /** Whether to auto-seed existing documents on startup. Default: true */
+    /** Whether to lazily seed a source row on its first collab request. Default: true */
     autoSeed?: boolean;
     /** Map a source-table id to the id used by the collab document store. */
     resolveCollabDocumentId?: (sourceId: string) => string;
+    /**
+     * Map a collab document id back to the source-table id for lazy seeding.
+     * Without this, the legacy forward resolver is supported with a first-load
+     * compatibility scan because arbitrary functions are not invertible.
+     */
+    resolveSourceIdFromCollabDocumentId?: (docId: string) => string;
     /**
      * Callback invoked after a collab update to sync the content column.
      * If not provided, the plugin auto-syncs using table/contentColumn/idColumn.
@@ -79,9 +86,15 @@ export interface CollabPluginOptions {
     maxPayloadBytes?: number;
 }
 export declare function normalizeCollabAccess(options: Pick<CollabPluginOptions, "access" | "resourceType" | "resolveResourceId">): NormalizedCollabAccess;
+/**
+ * Coalesce concurrent first loads for one document. The optional lock lets a
+ * database-backed caller extend that guarantee across server instances.
+ */
+export declare function createCollabSourceSeeder(options: {
+    hasState: (docId: string) => Promise<boolean>;
+    loadSource: (docId: string) => Promise<string | null>;
+    seed: (docId: string, source: string, client?: DbExec) => Promise<void>;
+    withLock?: (docId: string, run: (client?: DbExec) => Promise<void>) => Promise<void>;
+}): (docId: string) => Promise<void>;
 export declare function createCollabPlugin(options?: CollabPluginOptions): NitroPluginDef;
-export declare function selectUnseededCollabRows(rows: ReadonlyArray<Record<string, unknown>>, idColumn: string, existingDocIds: ReadonlySet<string>, resolveCollabDocumentId?: (sourceId: string) => string): Array<{
-    row: Record<string, unknown>;
-    docId: string;
-}>;
 export {};

package/dist/server/collab-plugin.js

@@ -16,10 +16,10 @@ import { defineEventHandler, getMethod, setResponseStatus, } from "h3";
 import { postAwareness, getActiveUsers } from "../collab/awareness.js";
 import { getCollabEmitter } from "../collab/emitter.js";
 import { getCollabState, postCollabUpdate, postCollabText, postCollabSearchReplace, } from "../collab/routes.js";
-import { listCollabDocIds } from "../collab/storage.js";
+import { hasCollabState } from "../collab/storage.js";
 import { postCollabJson, getCollabJson, postCollabPatch, } from "../collab/struct-routes.js";
 import { seedFromText, seedFromJson } from "../collab/ydoc-manager.js";
-import { getDbExec } from "../db/client.js";
+import { getDbExec, withDbExec } from "../db/client.js";
 import { getOrgContext } from "../org/context.js";
 import { resolveAccess, assertAccess } from "../sharing/access.js";
 import { getSession } from "./auth.js";
@@ -79,10 +79,60 @@ function warnForImplicitAllAuthenticatedAccess(table) {
         'Use access: { mode: "resource", resourceType: "..." } for access-scoped delivery, ' +
         'or access: { mode: "all-authenticated" } to explicitly acknowledge deployment-wide delivery.');
 }
+/**
+ * Coalesce concurrent first loads for one document. The optional lock lets a
+ * database-backed caller extend that guarantee across server instances.
+ */
+export function createCollabSourceSeeder(options) {
+    const inFlight = new Map();
+    return async (docId) => {
+        const existing = inFlight.get(docId);
+        if (existing)
+            return existing;
+        const seed = async (client) => {
+            if (await options.hasState(docId))
+                return;
+            const source = await options.loadSource(docId);
+            if (source === null)
+                return;
+            if (client) {
+                await options.seed(docId, source, client);
+            }
+            else {
+                await options.seed(docId, source);
+            }
+        };
+        const pending = (async () => {
+            // Keep the normal seeded-document path out of a transaction. The second
+            // check inside the lock closes the cross-instance race for cold docs.
+            if (await options.hasState(docId))
+                return;
+            if (options.withLock) {
+                await options.withLock(docId, seed);
+            }
+            else {
+                await seed();
+            }
+        })();
+        inFlight.set(docId, pending);
+        try {
+            await pending;
+        }
+        finally {
+            if (inFlight.get(docId) === pending)
+                inFlight.delete(docId);
+        }
+    };
+}
 export function createCollabPlugin(options = {}) {
     const normalizedAccess = normalizeCollabAccess(options);
     const { table = "documents", contentColumn = "content", idColumn = "id", autoSeed = true, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, } = options;
-    const resolveCollabDocumentId = options.resolveCollabDocumentId ?? ((sourceId) => sourceId);
+    const resolveSourceIdFromCollabDocumentId = options.resolveSourceIdFromCollabDocumentId ?? ((docId) => docId);
+    const isJson = options.contentType === "json";
+    const seedColumn = isJson
+        ? options.jsonColumn || contentColumn
+        : contentColumn;
+    const legacyResolveCollabDocumentId = options.resolveCollabDocumentId;
     const resourceType = normalizedAccess.mode === "resource"
         ? normalizedAccess.resourceType
         : undefined;
@@ -93,6 +143,115 @@ export function createCollabPlugin(options = {}) {
         !normalizedAccess.explicit) {
         warnForImplicitAllAuthenticatedAccess(table);
     }
+    const ensureDocumentSeeded = autoSeed
+        ? createCollabSourceSeeder({
+            hasState: hasCollabState,
+            loadSource: async (docId) => {
+                const readSource = (row, sourceId) => {
+                    const source = row[seedColumn];
+                    if (typeof source !== "string") {
+                        throw new Error(`[collab] ${table}.${seedColumn} for ${sourceId} is unreadable`);
+                    }
+                    return source;
+                };
+                if (legacyResolveCollabDocumentId &&
+                    !options.resolveSourceIdFromCollabDocumentId) {
+                    // An arbitrary forward resolver cannot be inverted. Preserve
+                    // existing consumers with a request-lazy compatibility scan; new
+                    // configs should provide the reverse resolver to use the indexed
+                    // source-id lookup.
+                    const { rows } = await getDbExec().execute({
+                        sql: `SELECT ${idColumn}, ${seedColumn} FROM ${table}`,
+                    });
+                    for (const row of rows) {
+                        const rawSourceId = row[idColumn];
+                        if (rawSourceId === null ||
+                            rawSourceId === undefined ||
+                            (typeof rawSourceId !== "string" &&
+                                typeof rawSourceId !== "number" &&
+                                typeof rawSourceId !== "bigint")) {
+                            throw new Error(`[collab] ${table}.${idColumn} for a legacy lazy seed is unreadable`);
+                        }
+                        const sourceId = String(rawSourceId);
+                        if (!sourceId) {
+                            throw new Error(`[collab] ${table}.${idColumn} for a legacy lazy seed is unreadable`);
+                        }
+                        if (legacyResolveCollabDocumentId(sourceId) !== docId)
+                            continue;
+                        return readSource(row, sourceId);
+                    }
+                    return null;
+                }
+                const sourceId = resolveSourceIdFromCollabDocumentId(docId);
+                const { rows } = await getDbExec().execute({
+                    sql: `SELECT ${seedColumn} FROM ${table} WHERE ${idColumn} = ?`,
+                    args: [sourceId],
+                });
+                if (rows.length === 0)
+                    return null;
+                return readSource(rows[0], sourceId);
+            },
+            seed: async (docId, source, client) => {
+                if (!isJson) {
+                    if (client) {
+                        await seedFromText(docId, source, "content", client);
+                    }
+                    else {
+                        await seedFromText(docId, source);
+                    }
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(source);
+                }
+                catch (error) {
+                    throw new Error(`[collab] ${table}.${seedColumn} for ${docId} contains invalid JSON`, { cause: error });
+                }
+                const type = Array.isArray(parsed) ? "array" : "map";
+                if (client) {
+                    await seedFromJson(docId, parsed, "data", type, client);
+                }
+                else {
+                    await seedFromJson(docId, parsed, "data", type);
+                }
+            },
+            withLock: async (docId, run) => {
+                const client = getDbExec();
+                if (typeof client.transaction !== "function")
+                    return run();
+                for (let attempt = 0; attempt < 20; attempt += 1) {
+                    const acquired = await client.transaction(async (tx) => {
+                        const { rows } = await tx.execute({
+                            sql: "SELECT pg_try_advisory_xact_lock(hashtextextended(?, 0)) AS acquired",
+                            args: [`${table}:${docId}`],
+                            timeoutMs: 1_000,
+                        });
+                        const result = rows[0]?.acquired;
+                        const acquired = result === true || result === "t"
+                            ? true
+                            : result === false || result === "f"
+                                ? false
+                                : null;
+                        if (acquired === null) {
+                            throw new Error(`[collab] advisory lock result for ${docId} is unreadable`);
+                        }
+                        if (!acquired)
+                            return false;
+                        await withDbExec(tx, () => run(tx));
+                        return true;
+                    });
+                    if (acquired)
+                        return;
+                    // Do not leave every cold instance blocked on a database session
+                    // while the first seed runs. This bounded retry keeps the wait in
+                    // application memory and fails loudly if a seed cannot finish.
+                    await new Promise((resolve) => setTimeout(resolve, Math.min(200, 25 * (attempt + 1))));
+                }
+                throw new Error(`[collab] timed out waiting to seed ${docId}; retry the request`);
+            },
+        })
+        : async () => { };
     return async (nitroApp) => {
         await awaitBootstrap(nitroApp);
         const P = FRAMEWORK_ROUTE_PREFIX;
@@ -278,6 +437,14 @@ export function createCollabPlugin(options = {}) {
                         event.context._collabMaxPayloadBytes = maxPayloadBytes;
                     }
                 }
+                const needsSeed = (action === "state" && method === "GET") ||
+                    (action === "update" && method === "POST") ||
+                    (action === "text" && method === "POST") ||
+                    (action === "search-replace" && method === "POST") ||
+                    (action === "json" && (method === "GET" || method === "POST")) ||
+                    (action === "patch" && method === "POST");
+                if (needsSeed)
+                    await ensureDocumentSeeded(docId);
                 if (action === "state" && method === "GET")
                     return getCollabState(event);
                 if (action === "update" && method === "POST")
@@ -300,65 +467,8 @@ export function createCollabPlugin(options = {}) {
                 return { error: "Not found" };
             });
         }));
-        // Auto-seed existing documents into collab state
-        if (autoSeed) {
-            const isJson = options.contentType === "json";
-            const seedColumn = isJson
-                ? options.jsonColumn || contentColumn
-                : contentColumn;
-            // Run in background so it doesn't block startup
-            setTimeout(async () => {
-                try {
-                    // Read existing ids once, then apply the plugin's document-id
-                    // mapping before filtering. A source-table SQL predicate can use
-                    // the wrong id for integrations such as Analytics' dash-* docs.
-                    const existingDocIds = await listCollabDocIds();
-                    const client = getDbExec();
-                    const { rows } = await client.execute(`SELECT ${idColumn}, ${seedColumn} FROM ${table}`);
-                    for (const { row, docId } of selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId)) {
-                        let seeded = false;
-                        if (isJson) {
-                            const raw = row[seedColumn] ?? "{}";
-                            try {
-                                const parsed = JSON.parse(raw);
-                                const inferredType = Array.isArray(parsed)
-                                    ? "array"
-                                    : "map";
-                                await seedFromJson(docId, parsed, "data", inferredType);
-                                seeded = true;
-                            }
-                            catch {
-                                // Invalid JSON — skip
-                            }
-                        }
-                        else {
-                            const content = row[seedColumn] ?? "";
-                            await seedFromText(docId, content);
-                            seeded = true;
-                        }
-                        if (seeded)
-                            existingDocIds.add(docId);
-                    }
-                }
-                catch {
-                    // Table may not exist yet on first boot — that's fine
-                }
-            }, 1000);
-        }
+        // Source rows are seeded lazily by the request path above. A cold-start
+        // scan here stampedes serverless instances and does work for documents no
+        // caller will ever open.
     };
 }
-export function selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId = (sourceId) => sourceId) {
-    const seenDocIds = new Set(existingDocIds);
-    const unseeded = [];
-    for (const row of rows) {
-        const sourceId = String(row[idColumn] ?? "");
-        if (!sourceId)
-            continue;
-        const docId = resolveCollabDocumentId(sourceId);
-        if (seenDocIds.has(docId))
-            continue;
-        seenDocIds.add(docId);
-        unseeded.push({ row, docId });
-    }
-    return unseeded;
-}

package/dist/templates/chat/.agents/skills/shadcn-ui/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: shadcn-ui
 description: >-
-  The shadcn CLI, component composition, theming, and registry workflow. Use
-  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
-  or when changing a theme or registry. Do not load it for ordinary edits to a
-  file that happens to import a shadcn component.
+  Project-aware shadcn/ui components, registry MCP, theming, and design-system
+  lint feedback. Use when adding or changing React/Tailwind UI, a primitive,
+  theme, registry, or component contract in an Agent-Native app.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
 local-changes: >-
@@ -16,11 +15,18 @@ metadata:
 
 # shadcn/ui
 
-This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
+This skill keeps shadcn/ui work project-aware. Components are source files in the
+app, so always inspect the local project before adding, importing, or rewriting
+them. When `@shadcn/lint` is configured, treat its feedback as implementation
+guidance, not cosmetic noise. The framework repository runs it through the root
+Oxlint configuration; generated workspaces carry this skill and the MCP
+workflow, but do not automatically inherit that repository-only lint setup.
 
 ## First Steps
 
-1. Work from the app root that owns `components.json`.
+1. Work from the app root that owns `components.json`. In this monorepo, that is
+   the selected app/template directory (usually under `templates/`), not the
+   repository root.
 2. In an Agent-Native app, inspect `app/design-system.ts` and
    `ToolkitProvider` before choosing a primitive. A registered company design
    system takes precedence over the default shadcn adapter.
@@ -29,6 +35,59 @@ This skill keeps shadcn/ui work project-aware. Components are source files in th
 5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
 6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
 
+## MCP Registry Workflow
+
+Each first-party app keeps the official shadcn MCP configuration in `.mcp.json`
+next to its `components.json`. Start the agent from that app root so the MCP
+server resolves the correct aliases, local UI directory, and Tailwind theme.
+Do not add a single repository-root server: the root is a workspace, not a
+shadcn project, and would make installs target the wrong project.
+
+- Use the shadcn MCP to search, inspect, and install registry items when it is
+  connected. Prefer the app's configured registries over copied source.
+- Use `pnpm dlx shadcn@latest info --json` for project context; the MCP has no
+  equivalent project-info tool.
+- If the MCP is unavailable, use the equivalent `pnpm dlx shadcn@latest`
+  command from the same app root and continue following this skill.
+- Keep registry URLs and aliases in that app's `components.json`. Never put
+  registry credentials in MCP config or checked-in source.
+
+## Design-System Lint Feedback
+
+In the framework repository, `pnpm lint` runs Oxlint with `@shadcn/lint` for the
+scoped template UI paths. Run it after UI changes and fix every `shadcn/*`
+finding before handing off. Template packages use the workspace lint
+configuration; do not create a second local lint configuration just for one
+app.
+
+Before claiming that shadcn lint ran in another workspace, inspect its root
+`package.json` and `.oxlintrc.json`. The generic generated workspace currently
+exposes `pnpm lint` as formatting-only and does not ship `@shadcn/lint` or the
+framework repository's Oxlint config. In that scaffold, use this skill plus the
+connected shadcn MCP (or the CLI fallback) for design-system guidance, and do
+not report `shadcn/*` checks as having run. If the workspace owner adopts the
+linter, add the dependency, scoped config, and lint script together.
+
+The Plan template is intentionally excluded from this rollout. Its files remain
+under `templates/plan/**`, but the root Oxlint ignore list keeps them out of the
+shadcn checks until that template has a separate lint baseline.
+
+- `no-restyle`: use the component's `variant`, `size`, and semantic props; put
+  layout on a parent and add a component variant only when the design system
+  genuinely needs a new treatment.
+- `no-raw-colors`: use the theme tokens in the app's `global.css`, not raw
+  Tailwind palette classes or hard-coded color attributes.
+- `no-arbitrary-values`: use the theme scale or a declared token instead of
+  one-off bracket values.
+- `no-inline-styles`: use classes or CSS custom properties for dynamic layout;
+  keep intentional editor/export exceptions scoped to their owning subsystem.
+- `no-unknown-classes` and `require-static-classes`: use classes Tailwind can
+  generate and keep class strings statically discoverable.
+
+The local primitive source is the contract boundary. Product code should consume
+its props and variants; update `packages/toolkit/src/ui/` or an app's
+`components/ui/` only when the design-system contract itself changes.
+
 ## Agent-Native Adapter Rule
 
 Pages, routes, and domain components import controls through the app's local UI

package/dist/templates/chat/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["shadcn@latest", "mcp"]
+    }
+  }
+}

package/dist/templates/default/.agents/skills/shadcn-ui/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: shadcn-ui
 description: >-
-  The shadcn CLI, component composition, theming, and registry workflow. Use
-  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
-  or when changing a theme or registry. Do not load it for ordinary edits to a
-  file that happens to import a shadcn component.
+  Project-aware shadcn/ui components, registry MCP, theming, and design-system
+  lint feedback. Use when adding or changing React/Tailwind UI, a primitive,
+  theme, registry, or component contract in an Agent-Native app.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
 local-changes: >-
@@ -16,11 +15,18 @@ metadata:
 
 # shadcn/ui
 
-This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
+This skill keeps shadcn/ui work project-aware. Components are source files in the
+app, so always inspect the local project before adding, importing, or rewriting
+them. When `@shadcn/lint` is configured, treat its feedback as implementation
+guidance, not cosmetic noise. The framework repository runs it through the root
+Oxlint configuration; generated workspaces carry this skill and the MCP
+workflow, but do not automatically inherit that repository-only lint setup.
 
 ## First Steps
 
-1. Work from the app root that owns `components.json`.
+1. Work from the app root that owns `components.json`. In this monorepo, that is
+   the selected app/template directory (usually under `templates/`), not the
+   repository root.
 2. In an Agent-Native app, inspect `app/design-system.ts` and
    `ToolkitProvider` before choosing a primitive. A registered company design
    system takes precedence over the default shadcn adapter.
@@ -29,6 +35,59 @@ This skill keeps shadcn/ui work project-aware. Components are source files in th
 5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
 6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
 
+## MCP Registry Workflow
+
+Each first-party app keeps the official shadcn MCP configuration in `.mcp.json`
+next to its `components.json`. Start the agent from that app root so the MCP
+server resolves the correct aliases, local UI directory, and Tailwind theme.
+Do not add a single repository-root server: the root is a workspace, not a
+shadcn project, and would make installs target the wrong project.
+
+- Use the shadcn MCP to search, inspect, and install registry items when it is
+  connected. Prefer the app's configured registries over copied source.
+- Use `pnpm dlx shadcn@latest info --json` for project context; the MCP has no
+  equivalent project-info tool.
+- If the MCP is unavailable, use the equivalent `pnpm dlx shadcn@latest`
+  command from the same app root and continue following this skill.
+- Keep registry URLs and aliases in that app's `components.json`. Never put
+  registry credentials in MCP config or checked-in source.
+
+## Design-System Lint Feedback
+
+In the framework repository, `pnpm lint` runs Oxlint with `@shadcn/lint` for the
+scoped template UI paths. Run it after UI changes and fix every `shadcn/*`
+finding before handing off. Template packages use the workspace lint
+configuration; do not create a second local lint configuration just for one
+app.
+
+Before claiming that shadcn lint ran in another workspace, inspect its root
+`package.json` and `.oxlintrc.json`. The generic generated workspace currently
+exposes `pnpm lint` as formatting-only and does not ship `@shadcn/lint` or the
+framework repository's Oxlint config. In that scaffold, use this skill plus the
+connected shadcn MCP (or the CLI fallback) for design-system guidance, and do
+not report `shadcn/*` checks as having run. If the workspace owner adopts the
+linter, add the dependency, scoped config, and lint script together.
+
+The Plan template is intentionally excluded from this rollout. Its files remain
+under `templates/plan/**`, but the root Oxlint ignore list keeps them out of the
+shadcn checks until that template has a separate lint baseline.
+
+- `no-restyle`: use the component's `variant`, `size`, and semantic props; put
+  layout on a parent and add a component variant only when the design system
+  genuinely needs a new treatment.
+- `no-raw-colors`: use the theme tokens in the app's `global.css`, not raw
+  Tailwind palette classes or hard-coded color attributes.
+- `no-arbitrary-values`: use the theme scale or a declared token instead of
+  one-off bracket values.
+- `no-inline-styles`: use classes or CSS custom properties for dynamic layout;
+  keep intentional editor/export exceptions scoped to their owning subsystem.
+- `no-unknown-classes` and `require-static-classes`: use classes Tailwind can
+  generate and keep class strings statically discoverable.
+
+The local primitive source is the contract boundary. Product code should consume
+its props and variants; update `packages/toolkit/src/ui/` or an app's
+`components/ui/` only when the design-system contract itself changes.
+
 ## Agent-Native Adapter Rule
 
 Pages, routes, and domain components import controls through the app's local UI

package/dist/templates/default/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["shadcn@latest", "mcp"]
+    }
+  }
+}