@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/ai/skills.ts

@@ -1,3 +1,7 @@
+import { aiProjects } from "./projects";
+import { AuthenticatedPrincipalSchema } from "../contracts/shared";
+import { createHash } from "node:crypto";
+import { accessRevision } from "../server/services/access-revision";
 import { type SQL, type SQLQuery, sql } from "bun";
 import type { AccessSubject } from "../server";
 import {
@@ -9,6 +13,7 @@ import {
   type Principal,
 } from "../server/services/access";
 import { toPgUuidArray } from "../services/postgres";
+import { aiSkillSearchSql, withAiSkillSearch } from "./skill-search";
 import { mountAiSkillFilePath } from "./file-mount";
 import { AI_SHORT_ID_PATTERN, withAiShortIdForDb } from "./short-id";
 import {
@@ -21,6 +26,7 @@ import {
   validateAiSkillName,
   validateAiSkillReferences,
 } from "./skill-format";
+import { getBuiltinAiSkillTemplates } from "./skill-seeds";
 import type { AiSkillFileToolContent, AiSkillFileToolStat } from "./types";
 
 export type AiSkillPermission = Exclude<PermissionLevel, "none">;
@@ -55,7 +61,22 @@ export type AiSkillAccess = {
   createdAt: string;
 };
 
+export type AiSkillTemplate = {
+  key: string;
+  version: number;
+  name: string;
+  description: string;
+  instructions: string;
+  extraFrontmatter?: AiSkillExtraFrontmatter;
+  references?: readonly AiSkillReferenceInput[];
+};
+
 export type AiSkillAdminListItem = {
+  revision: number;
+  templateId: string | null;
+  templateVersion: number | null;
+  currentTemplateVersion: number | null;
+  templateStatus: "current" | "modified" | "update_available" | null;
   id: string;
   shortId: string;
   name: string;
@@ -86,6 +107,9 @@ type SkillRow = {
   id: string;
   short_id: string;
   managed_key: string | null;
+  template_id: string | null;
+  template_version: number | null;
+  template_hash: string | null;
   name: string;
   description: string;
   instructions: string;
@@ -106,13 +130,14 @@ type SkillAccessRow = {
   display_name: string | null;
 };
 
-type SkillSummaryRow = SkillRow & {
+type SkillSummaryRow = Pick<SkillRow, "id" | "short_id" | "name" | "description" | "revision" | "created_at" | "updated_at"> & {
   permission: AiSkillPermission;
   reference_count: number;
   enabled: boolean;
 };
 
 type AdminSkillRow = SkillRow & {
+  content_references: AiSkillReference[] | string;
   reference_count: number;
   access_count: number;
   admin_count: number;
@@ -162,7 +187,7 @@ const principalForSubject = (subject: AccessSubject): Principal =>
     : { type: "service_account", serviceAccountId: subject.serviceAccountId };
 
 const accessMatch = (subject: AccessSubject | null): SQLQuery =>
-  buildAccessPrincipalCondition({
+  subject === null ? sql`FALSE` : buildAccessPrincipalCondition({
     subject,
     columns: {
       userId: sql`access.user_id`,
@@ -181,17 +206,22 @@ const getRowByShortId = async (shortId: string, db: SQL = sql): Promise<SkillRow
 const getRowByName = async (name: string, db: SQL = sql): Promise<SkillRow | null> =>
   (await db<SkillRow[]>`SELECT * FROM ai.skills WHERE name = ${name}`)[0] ?? null;
 
+// Project links grant read only. Their creator's later permissions are irrelevant.
+const effectivePermission = (skillId: SQLQuery, subject: AccessSubject | null) => sql`
+  SELECT permission FROM (
+    SELECT access.permission FROM ai.skill_access link JOIN auth.access access ON access.id=link.access_id
+      WHERE link.skill_id=${skillId} AND ${accessMatch(subject)}
+    UNION ALL
+    SELECT 'read'::auth.permission_level FROM ai.project_skills link
+      JOIN ai.project_access project_access ON project_access.project_id=link.project_id
+      JOIN auth.access access ON access.id=project_access.access_id
+      WHERE link.skill_id=${skillId} AND access.permission <> 'none' AND ${accessMatch(subject)}
+  ) grants ORDER BY CASE permission WHEN 'admin' THEN 3 WHEN 'write' THEN 2 WHEN 'read' THEN 1 ELSE 0 END DESC LIMIT 1
+`;
+
 const permissionFor = async (skillId: string, subject: AccessSubject | null, db: SQL = sql): Promise<AiSkillPermission | "none"> => {
-  const match = accessMatch(subject);
-  const rows = await db<{ permission: AiSkillPermission }[]>`
-    SELECT access.permission
-    FROM ai.skill_access skill_access
-    JOIN auth.access access ON access.id = skill_access.access_id
-    WHERE skill_access.skill_id = ${skillId}::uuid AND ${match}
-    ORDER BY CASE access.permission WHEN 'admin' THEN 3 WHEN 'write' THEN 2 WHEN 'read' THEN 1 ELSE 0 END DESC
-    LIMIT 1
-  `;
-  return rows[0]?.permission ?? "none";
+  const [row] = await db<{ permission: AiSkillPermission | null }[]>`SELECT (${effectivePermission(sql`${skillId}::uuid`, subject)}) AS permission`;
+  return row?.permission ?? "none";
 };
 
 const enabledFor = async (skillId: string, subject: AccessSubject | null, db: SQL = sql): Promise<boolean> => {
@@ -280,6 +310,7 @@ const createSkillAccess = async (
   input: { principal: Principal; permission: AiSkillPermission },
   db: SQL,
 ): Promise<AiSkillAccess> => {
+  AuthenticatedPrincipalSchema.parse(input.principal);
   const created = await createAccess(input, db);
   if (!created.ok) throw new Error(created.error.message);
   let shortId = "";
@@ -300,6 +331,11 @@ const createSkillAccess = async (
   return entry;
 };
 
+const checkAccessRevision = async (skillId: string, expected: string | undefined, db: SQL) => {
+  if (expected !== undefined && accessRevision(await listSkillAccess(skillId, db)) !== expected)
+    throw new AiSkillRevisionConflictError();
+};
+
 const updateSkillAccess = async (skillId: string, accessId: string, permission: AiSkillPermission, db: SQL): Promise<boolean> => {
   const [bound] = await db<{ id: string; permission: AiSkillPermission }[]>`
     SELECT access.id, access.permission
@@ -361,26 +397,92 @@ const validatedFields = (input: {
   }
 };
 
-const sameReferences = (left: readonly AiSkillReference[], right: readonly AiSkillReference[]): boolean =>
-  left.length === right.length &&
-  left.every((reference, index) => reference.path === right[index]?.path && reference.content === right[index]?.content);
+// JSON object key order and reference insertion order are not content changes.
+const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+
+const contentHash = (fields: ReturnType<typeof validatedFields>): string =>
+  createHash("sha256")
+    .update(
+      canonicalJson({
+        ...fields,
+        references: [...fields.references].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+      }),
+    )
+    .digest("hex");
+
+const rowContentHash = async (row: SkillRow, db: SQL = sql): Promise<string> =>
+  contentHash({
+    name: row.name,
+    description: row.description,
+    instructions: row.instructions,
+    extraFrontmatter: jsonObject(row.extra_frontmatter),
+    references: await listReferences(row.id, db),
+  });
+
+const validateTemplate = (input: AiSkillTemplate) => {
+  if (!input.key.trim() || !Number.isSafeInteger(input.version) || input.version < 1 || input.version > 2147483647)
+    throw new AiSkillInputError("A template needs a stable ID and a positive integer version.");
+  const fields = validatedFields(input);
+  return { fields, hash: contentHash(fields) };
+};
+
+const replaceTemplate = async (row: SkillRow, template: AiSkillTemplate, db: SQL): Promise<void> => {
+  const { fields, hash } = validateTemplate(template);
+  await db`UPDATE ai.skills SET name = ${fields.name}, description = ${fields.description},
+    instructions = ${fields.instructions}, extra_frontmatter = (${JSON.stringify(fields.extraFrontmatter)}::text)::jsonb,
+    template_id = ${template.key}, template_version = ${template.version}, template_hash = ${hash},
+    revision = revision + 1, updated_at = now() WHERE id = ${row.id}::uuid`;
+  await db`DELETE FROM ai.skill_references WHERE skill_id = ${row.id}::uuid`;
+  for (const ref of fields.references)
+    await db`INSERT INTO ai.skill_references (skill_id, path, content)
+    VALUES (${row.id}::uuid, ${ref.path}, ${ref.content})`;
+};
 
 const skillSearchPattern = (search?: string): string | null => {
   const value = search?.trim().toLowerCase();
   return value ? `%${value.replace(/[\\%_]/g, (char) => `\\${char}`)}%` : null;
 };
 
-const toAdminSkill = (row: AdminSkillRow): AiSkillAdminListItem => ({
-  id: row.id,
-  shortId: row.short_id,
-  name: row.name,
-  description: row.description,
-  referenceCount: Number(row.reference_count),
-  accessCount: Number(row.access_count),
-  adminCount: Number(row.admin_count),
-  createdAt: iso(row.created_at),
-  updatedAt: iso(row.updated_at),
-});
+const toAdminSkill = (row: AdminSkillRow): AiSkillAdminListItem => {
+  const template = getBuiltinAiSkillTemplates().find((entry) => entry.key === row.template_id);
+  return {
+    revision: Number(row.revision),
+    templateId: row.template_id,
+    templateVersion: row.template_version,
+    currentTemplateVersion: template?.version ?? null,
+    templateStatus: !row.template_id
+      ? null
+      : template && template.version > Number(row.template_version)
+        ? "update_available"
+        : contentHash({
+              name: row.name,
+              description: row.description,
+              instructions: row.instructions,
+              extraFrontmatter: jsonObject(row.extra_frontmatter),
+              references: snapshotFiles(row.content_references),
+            }) === row.template_hash
+          ? "current"
+          : "modified",
+    id: row.id,
+    shortId: row.short_id,
+    name: row.name,
+    description: row.description,
+    referenceCount: Number(row.reference_count),
+    accessCount: Number(row.access_count),
+    adminCount: Number(row.admin_count),
+    createdAt: iso(row.created_at),
+    updatedAt: iso(row.updated_at),
+  };
+};
 
 const skillSnapshotFiles = (skill: AiSkill): { path: string; content: string }[] => [
   {
@@ -390,90 +492,104 @@ const skillSnapshotFiles = (skill: AiSkill): { path: string; content: string }[]
   ...skill.references.map((reference) => ({ path: `${skill.name}/${reference.path}`, content: reference.content })),
 ];
 
-export const aiSkills = {
-  async seedOnce(input: {
-    key: string;
-    name: string;
-    description: string;
-    instructions: string;
-    extraFrontmatter?: AiSkillExtraFrontmatter;
-    references?: readonly AiSkillReferenceInput[];
-  }): Promise<void> {
-    const key = input.key.trim();
-    if (!key) throw new AiSkillInputError("Skill seed key is required.");
-    const fields = validatedFields(input);
-    await sql.begin(async (tx) => {
-      const [claimed] = await tx<{ key: string }[]>`
-        INSERT INTO ai.skill_seeds (key) VALUES (${key})
-        ON CONFLICT (key) DO NOTHING
-        RETURNING key
-      `;
-      if (!claimed) return;
+type SkillListOptions = { query?: string; enabledOnly?: boolean; limit?: number };
+async function listSkillSummaries(subject: AccessSubject | null, options: SkillListOptions & {
+  project?: { id: string; linked: boolean }; manageOnly?: boolean; offset?: number;
+} = {}): Promise<AiSkillSummary[]> {
+  const userId = subject?.type === "user" ? subject.userId : null;
+  const query = (options.query ?? "").trim().slice(0, 200);
+  const limit = Math.max(1, Math.min(201, options.limit ?? 200));
+  const rows = await withAiSkillSearch(query, async (bm25) => {
+    const search = aiSkillSearchSql(query, bm25);
+    return sql<SkillSummaryRow[]>`
+    SELECT skill.id, skill.short_id, skill.name, skill.description, skill.revision, skill.created_at, skill.updated_at,
+           access.permission,
+           count(DISTINCT reference.path)::int AS reference_count,
+           (disabled.user_id IS NULL) AS enabled
+    FROM ai.skills skill
+    JOIN LATERAL (${effectivePermission(sql`skill.id`, subject)}) access ON true
+    LEFT JOIN ai.skill_references reference ON reference.skill_id = skill.id
+    LEFT JOIN ai.skill_user_disabled disabled
+      ON disabled.skill_id = skill.id AND disabled.user_id = ${userId}::uuid
+    WHERE access.permission <> 'none'
+      AND (${!options.manageOnly} OR access.permission='admin')
+      AND ${options.project ? sql`EXISTS(SELECT 1 FROM ai.project_skills link WHERE link.skill_id=skill.id AND link.project_id=${options.project.id}::uuid) = ${options.project.linked}` : sql`true`}
+      AND (${!options.enabledOnly} OR disabled.user_id IS NULL) AND ${search.matches}
+    GROUP BY skill.id, disabled.user_id, access.permission
+    ORDER BY ${search.rank} DESC, ${search.textRank} DESC, skill.name, skill.id
+    LIMIT ${limit} OFFSET ${options.offset ?? 0}
+  `;
+  });
+  return rows.map((row) => ({
+    id: row.id,
+    shortId: row.short_id,
+    name: row.name,
+    description: row.description,
+    permission: row.permission,
+    revision: Number(row.revision),
+    referenceCount: Number(row.reference_count),
+    enabled: row.enabled,
+    createdAt: iso(row.created_at),
+    updatedAt: iso(row.updated_at),
+  }));
+}
 
-      let [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE managed_key = ${key} FOR UPDATE`;
-      if (!row) {
-        const [conflict] = await tx<{ id: string }[]>`SELECT id FROM ai.skills WHERE name = ${fields.name}`;
-        if (conflict) return;
-        const rows = await withAiShortIdForDb(
-          tx,
-          "idx_ai_skills_short_id",
-          (attempt, shortId) => attempt<SkillRow[]>`
-            INSERT INTO ai.skills (short_id, name, description, instructions, extra_frontmatter)
-            VALUES (
-              ${shortId}, ${fields.name}, ${fields.description}, ${fields.instructions},
-              (${JSON.stringify(fields.extraFrontmatter)}::text)::jsonb
-            )
-            RETURNING *
-          `,
-        );
-        row = rows[0]!;
-      } else {
-        const references = await listReferences(row.id, tx);
-        const changed =
-          row.name !== fields.name ||
-          row.description !== fields.description ||
-          row.instructions !== fields.instructions ||
-          JSON.stringify(jsonObject(row.extra_frontmatter)) !== JSON.stringify(fields.extraFrontmatter) ||
-          !sameReferences(references, fields.references);
-        if (changed) {
-          [row] = await tx<SkillRow[]>`
-            UPDATE ai.skills
-            SET name = ${fields.name}, description = ${fields.description}, instructions = ${fields.instructions},
-                extra_frontmatter = (${JSON.stringify(fields.extraFrontmatter)}::text)::jsonb,
-                managed_key = NULL, revision = revision + 1, updated_at = now()
-            WHERE id = ${row.id}::uuid
-            RETURNING *
-          `;
-        } else {
-          [row] = await tx<SkillRow[]>`
-            UPDATE ai.skills SET managed_key = NULL WHERE id = ${row.id}::uuid RETURNING *
-          `;
-        }
-      }
+async function linkedSkillProjects(skillId: string, subject: AccessSubject | null) {
+  const links = await sql<{projectId:string}[]>`SELECT project_id AS "projectId" FROM ai.project_skills WHERE skill_id=${skillId}::uuid ORDER BY project_id`;
+  const result: Array<{ projectId: string; shortId: string | null; name: string | null }> = [];
+  for (const link of links) {
+    const project = await aiProjects.get(link.projectId, subject);
+    result.push({ ...link, shortId: project?.shortId ?? null, name: project?.name ?? null });
+  }
+  return result;
+}
 
-      const currentReferences = await listReferences(row!.id, tx);
-      if (!sameReferences(currentReferences, fields.references)) {
-        await tx`DELETE FROM ai.skill_references WHERE skill_id = ${row!.id}::uuid`;
-        for (const reference of fields.references) {
-          await tx`
-            INSERT INTO ai.skill_references (skill_id, path, content)
-            VALUES (${row!.id}::uuid, ${reference.path}, ${reference.content})
-          `;
+export const aiSkills = {
+  async seedOnce(template: AiSkillTemplate): Promise<void> {
+    const { fields, hash } = validateTemplate(template);
+    await sql.begin(async (tx) => {
+      const [claimed] = await tx`INSERT INTO ai.skill_seeds (key, catalog_version)
+        VALUES (${template.key}, ${template.version}) ON CONFLICT (key) DO NOTHING RETURNING key`;
+      // Seed lock always precedes the Skill lock, including administrator adoption/reset.
+      const [seed] = await tx<{ skill_id: string | null; catalog_version: number }[]>`
+        SELECT skill_id, catalog_version FROM ai.skill_seeds WHERE key = ${template.key} FOR UPDATE`;
+      if (!seed || seed.catalog_version > template.version) return;
+      await tx`UPDATE ai.skill_seeds SET catalog_version = ${template.version} WHERE key = ${template.key}`;
+      if (seed.skill_id) {
+        const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id = ${seed.skill_id}::uuid FOR UPDATE`;
+        if (!row || row.template_id !== template.key || Number(row.template_version) >= template.version) return;
+        if ((await rowContentHash(row, tx)) !== row.template_hash) return;
+        // A user may have claimed the new name. Keep the existing Skill rather than fail startup.
+        const [collision] = await tx`SELECT id FROM ai.skills WHERE name = ${fields.name} AND id <> ${row.id}::uuid`;
+        if (!collision) {
+          try {
+            await tx.savepoint((attempt) => replaceTemplate(row, template, attempt));
+          } catch (error) {
+            // A concurrent normal create may claim the name after our read.
+            if (!(typeof error === "object" && error !== null && "constraint" in error && error.constraint === "idx_ai_skills_name"))
+              throw error;
+          }
         }
+        return;
       }
-
-      const [grant] = await tx<{ id: string; permission: AiSkillPermission }[]>`
-        SELECT access.id, access.permission
-        FROM ai.skill_access skill_access
-        JOIN auth.access access ON access.id = skill_access.access_id
-        WHERE skill_access.skill_id = ${row!.id}::uuid AND access.authenticated_only = true
-        LIMIT 1
-      `;
-      if (!grant) {
-        await createSkillAccess(row!.id, { principal: { type: "authenticated" }, permission: "read" }, tx);
-      } else if (grant.permission !== "read") {
-        await tx`UPDATE auth.access SET permission = 'read' WHERE id = ${grant.id}::uuid`;
-      }
+      // Old seed markers and name collisions never authorize adoption or replacement.
+      if (!claimed) return;
+      const [collision] = await tx`SELECT id FROM ai.skills WHERE name = ${fields.name}`;
+      if (collision) return;
+      const [row] = await withAiShortIdForDb(
+        tx,
+        "idx_ai_skills_short_id",
+        (attempt, shortId) => attempt<SkillRow[]>`
+        INSERT INTO ai.skills (short_id, name, description, instructions, extra_frontmatter, template_id, template_version, template_hash)
+        VALUES (${shortId}, ${fields.name}, ${fields.description}, ${fields.instructions},
+          (${JSON.stringify(fields.extraFrontmatter)}::text)::jsonb, ${template.key}, ${template.version}, ${hash}) ON CONFLICT (name) DO NOTHING RETURNING *`,
+      );
+      if (!row) return;
+      for (const ref of fields.references)
+        await tx`INSERT INTO ai.skill_references (skill_id, path, content)
+        VALUES (${row!.id}::uuid, ${ref.path}, ${ref.content})`;
+      await tx`UPDATE ai.skill_seeds SET skill_id = ${row!.id}::uuid WHERE key = ${template.key}`;
+      await createSkillAccess(row!.id, { principal: { type: "authenticated" }, permission: "read" }, tx);
     });
   },
 
@@ -510,39 +626,38 @@ export const aiSkills = {
     });
   },
 
-  async list(subject: AccessSubject | null): Promise<AiSkillSummary[]> {
-    const match = accessMatch(subject);
-    const userId = subject?.type === "user" ? subject.userId : null;
-    const rows = await sql<SkillSummaryRow[]>`
-      SELECT skill.*,
-             (array_agg(access.permission ORDER BY
-               CASE access.permission WHEN 'admin' THEN 3 WHEN 'write' THEN 2 WHEN 'read' THEN 1 ELSE 0 END DESC
-             ))[1] AS permission,
-             count(DISTINCT reference.path)::int AS reference_count,
-             (disabled.user_id IS NULL) AS enabled
-      FROM ai.skills skill
-      JOIN ai.skill_access skill_access ON skill_access.skill_id = skill.id
-      JOIN auth.access access ON access.id = skill_access.access_id
-      LEFT JOIN ai.skill_references reference ON reference.skill_id = skill.id
-      LEFT JOIN ai.skill_user_disabled disabled
-        ON disabled.skill_id = skill.id AND disabled.user_id = ${userId}::uuid
-      WHERE access.permission <> 'none' AND ${match}
-      GROUP BY skill.id, disabled.user_id
-      ORDER BY skill.name, skill.id
-      LIMIT 200
-    `;
-    return rows.map((row) => ({
-      id: row.id,
-      shortId: row.short_id,
-      name: row.name,
-      description: row.description,
-      permission: row.permission,
-      revision: Number(row.revision),
-      referenceCount: Number(row.reference_count),
-      enabled: row.enabled,
-      createdAt: iso(row.created_at),
-      updatedAt: iso(row.updated_at),
-    }));
+  async list(subject: AccessSubject | null, options: SkillListOptions = {}): Promise<AiSkillSummary[]> {
+    return listSkillSummaries(subject, options);
+  },
+
+  async projectSkills(projectId: string, subject: AccessSubject | null, options: { query?: string; page?: number; available?: boolean } = {}) {
+    if (!(await aiProjects.get(projectId, subject, options.available ? "admin" : "read"))) return null;
+    const page = Math.max(1, Math.min(100000, Math.trunc(options.page ?? 1)));
+    const skills = await listSkillSummaries(subject, { query: options.query, limit: 31, offset: (page-1)*30,
+      project: { id: projectId, linked: !options.available }, manageOnly: options.available });
+    return { items: skills.slice(0,30), hasNext: skills.length>30, page };
+  },
+
+  async linkProject(skillId: string, projectId: string, linked: boolean, subject: AccessSubject | null): Promise<boolean> {
+    if (!(await aiProjects.get(projectId, subject, "admin"))) return false;
+    return sql.begin(async tx => {
+      const [row] = await tx`SELECT id FROM ai.skills WHERE id=${skillId}::uuid FOR UPDATE`;
+      if (!row || !hasPermission(await permissionFor(skillId, subject, tx), "admin")) return false;
+      if (linked) await tx`INSERT INTO ai.project_skills(project_id,skill_id) VALUES(${projectId}::uuid,${skillId}::uuid) ON CONFLICT DO NOTHING`;
+      else await tx`DELETE FROM ai.project_skills WHERE project_id=${projectId}::uuid AND skill_id=${skillId}::uuid`;
+      return true;
+    });
+  },
+
+  async linkedProjects(skillId: string, subject: AccessSubject | null) {
+    if (!(await this.get(skillId, subject, "admin"))) return null;
+    return linkedSkillProjects(skillId, subject);
+  },
+
+  async search(subject: AccessSubject | null, query: string, limit = 30): Promise<{ skills: AiSkillSummary[]; more: boolean }> {
+    const size = Math.max(1, Math.min(200, limit));
+    const skills = await aiSkills.list(subject, { query, enabledOnly: true, limit: size + 1 });
+    return { skills: skills.slice(0, size), more: skills.length > size };
   },
 
   async get(skillId: string, subject: AccessSubject | null, required: AiSkillPermission = "read"): Promise<AiSkill | null> {
@@ -607,39 +722,89 @@ export const aiSkills = {
   },
 
   async listAccess(skillId: string, subject: AccessSubject | null): Promise<AiSkillAccess[] | null> {
-    if (!(await requireSkill(await getRow(skillId), subject, "admin"))) return null;
-    return listSkillAccess(skillId);
+    return sql.begin(async tx => {
+      const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id=${skillId}::uuid FOR UPDATE`;
+      if (!row || !hasPermission(await permissionFor(row.id, subject, tx), "admin")) return null;
+      return listSkillAccess(skillId, tx);
+    });
   },
 
   async grantAccess(
     skillId: string,
     subject: AccessSubject | null,
     input: { principal: Principal; permission: AiSkillPermission },
+    expectedAccessRevision?: string,
   ): Promise<AiSkillAccess | null> {
     return sql.begin(async (tx) => {
       const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id = ${skillId}::uuid FOR UPDATE`;
       if (!row || !hasPermission(await permissionFor(row.id, subject, tx), "admin")) return null;
+      await checkAccessRevision(skillId, expectedAccessRevision, tx);
       return createSkillAccess(skillId, input, tx);
     });
   },
 
-  async updateAccess(skillId: string, accessId: string, subject: AccessSubject | null, permission: AiSkillPermission): Promise<boolean> {
+  async updateAccess(skillId: string, accessId: string, subject: AccessSubject | null, permission: AiSkillPermission, expectedAccessRevision?: string): Promise<boolean> {
     return sql.begin(async (tx) => {
       const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id = ${skillId}::uuid FOR UPDATE`;
-      return row && hasPermission(await permissionFor(row.id, subject, tx), "admin")
-        ? updateSkillAccess(skillId, accessId, permission, tx)
-        : false;
+      if (!row || !hasPermission(await permissionFor(row.id, subject, tx), "admin")) return false;
+      await checkAccessRevision(skillId, expectedAccessRevision, tx);
+      return updateSkillAccess(skillId, accessId, permission, tx);
     });
   },
 
-  async revokeAccess(skillId: string, accessId: string, subject: AccessSubject | null): Promise<boolean> {
+  async revokeAccess(skillId: string, accessId: string, subject: AccessSubject | null, expectedAccessRevision?: string): Promise<boolean> {
     return sql.begin(async (tx) => {
       const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id = ${skillId}::uuid FOR UPDATE`;
-      return row && hasPermission(await permissionFor(row.id, subject, tx), "admin") ? revokeSkillAccess(skillId, accessId, tx) : false;
+      if (!row || !hasPermission(await permissionFor(row.id, subject, tx), "admin")) return false;
+      await checkAccessRevision(skillId, expectedAccessRevision, tx);
+      return revokeSkillAccess(skillId, accessId, tx);
     });
   },
 
   admin: {
+    linkedProjects: linkedSkillProjects,
+    // Platform-owned recovery API: callers must enforce platform-admin authorization.
+    async applyTemplate(
+      skillId: string,
+      input: {
+        templateId: string;
+        templateVersion: number;
+        expectedRevision: number;
+        mode: "associate" | "reset";
+      },
+    ): Promise<boolean> {
+      const template = getBuiltinAiSkillTemplates().find((entry) => entry.key === input.templateId);
+      if (!template) throw new AiSkillInputError("Unknown Skill template.");
+      if (template.version !== input.templateVersion) throw new AiSkillRevisionConflictError();
+      const { hash } = validateTemplate(template);
+      return sql.begin(async (tx) => {
+        await tx`INSERT INTO ai.skill_seeds (key, catalog_version) VALUES (${template.key}, ${template.version})
+          ON CONFLICT (key) DO NOTHING`;
+        const [seed] = await tx<{ skill_id: string | null; catalog_version: number }[]>`
+          SELECT skill_id, catalog_version FROM ai.skill_seeds WHERE key = ${template.key} FOR UPDATE`;
+        const [row] = await tx<SkillRow[]>`SELECT * FROM ai.skills WHERE id = ${skillId}::uuid FOR UPDATE`;
+        if (!row) return false;
+        if (
+          Number(row.revision) !== input.expectedRevision ||
+          seed!.catalog_version > template.version ||
+          Number(row.template_version) > template.version
+        )
+          throw new AiSkillRevisionConflictError();
+        if (seed!.skill_id && seed!.skill_id !== row.id)
+          throw new AiSkillInputError("This template is already linked, possibly to a deleted Skill.");
+        if (input.mode === "associate") {
+          if (row.template_id) throw new AiSkillInputError("This Skill already has a template.");
+          await tx`UPDATE ai.skills SET template_id = ${template.key}, template_version = ${template.version},
+            template_hash = ${hash}, managed_key = NULL, revision = revision + 1, updated_at = now() WHERE id = ${row.id}::uuid`;
+        } else {
+          if (row.template_id !== template.key) throw new AiSkillInputError("Associate this Skill with its template first.");
+          await replaceTemplate(row, template, tx);
+        }
+        await tx`UPDATE ai.skill_seeds SET skill_id = ${row.id}::uuid, catalog_version = ${template.version} WHERE key = ${template.key}`;
+        return true;
+      });
+    },
+
     async list(params: {
       search?: string;
       page?: number;
@@ -659,6 +824,8 @@ export const aiSkills = {
       `;
       const rows = await sql<AdminSkillRow[]>`
         SELECT skill.*,
+               (SELECT COALESCE(jsonb_agg(jsonb_build_object('path', content.path, 'content', content.content)), '[]'::jsonb)
+                FROM ai.skill_references content WHERE content.skill_id = skill.id) AS content_references,
                count(DISTINCT reference.path)::int AS reference_count,
                count(DISTINCT skill_access.access_id)::int AS access_count,
                count(DISTINCT skill_access.access_id) FILTER (WHERE access.permission = 'admin')::int AS admin_count
@@ -704,6 +871,8 @@ export const aiSkills = {
     async getByShortId(shortId: string): Promise<AiSkillAdminListItem | null> {
       const rows = await sql<AdminSkillRow[]>`
         SELECT skill.*,
+               (SELECT COALESCE(jsonb_agg(jsonb_build_object('path', content.path, 'content', content.content)), '[]'::jsonb)
+                FROM ai.skill_references content WHERE content.skill_id = skill.id) AS content_references,
                count(DISTINCT reference.path)::int AS reference_count,
                count(DISTINCT skill_access.access_id)::int AS access_count,
                count(DISTINCT skill_access.access_id) FILTER (WHERE access.permission = 'admin')::int AS admin_count
@@ -885,17 +1054,15 @@ export const aiSkills = {
   },
 
   async listTurnFiles(turnId: string, subject: AccessSubject | null): Promise<AiSkillFileToolStat[]> {
-    const match = accessMatch(subject);
     const userId = subject?.type === "user" ? subject.userId : null;
     const rows = await sql<SnapshotRow[]>`
       SELECT DISTINCT snapshot.skill_name, snapshot.description, snapshot.revision, snapshot.instructions,
              snapshot.files, snapshot.loaded_at
       FROM ai.turn_skill_snapshots snapshot
-      JOIN ai.skill_access skill_access ON skill_access.skill_id = snapshot.skill_id
-      JOIN auth.access access ON access.id = skill_access.access_id
+      JOIN LATERAL (${effectivePermission(sql`snapshot.skill_id`, subject)}) access ON true
       LEFT JOIN ai.skill_user_disabled disabled
         ON disabled.skill_id = snapshot.skill_id AND disabled.user_id = ${userId}::uuid
-      WHERE snapshot.turn_id = ${turnId}::uuid AND access.permission <> 'none' AND ${match}
+      WHERE snapshot.turn_id = ${turnId}::uuid AND access.permission <> 'none'
         AND disabled.user_id IS NULL
       ORDER BY snapshot.skill_name
     `;
@@ -914,21 +1081,23 @@ export const aiSkills = {
     const stat = files.find((file) => file.path === path);
     if (!stat) return null;
     const [skillName] = path.split("/", 1);
-    const match = accessMatch(subject);
     const userId = subject?.type === "user" ? subject.userId : null;
     const [row] = await sql<SnapshotRow[]>`
       SELECT DISTINCT snapshot.skill_name, snapshot.description, snapshot.revision, snapshot.instructions,
              snapshot.files, snapshot.loaded_at
       FROM ai.turn_skill_snapshots snapshot
-      JOIN ai.skill_access skill_access ON skill_access.skill_id = snapshot.skill_id
-      JOIN auth.access access ON access.id = skill_access.access_id
+      JOIN LATERAL (${effectivePermission(sql`snapshot.skill_id`, subject)}) access ON true
       LEFT JOIN ai.skill_user_disabled disabled
         ON disabled.skill_id = snapshot.skill_id AND disabled.user_id = ${userId}::uuid
       WHERE snapshot.turn_id = ${turnId}::uuid AND snapshot.skill_name = ${skillName}
-        AND access.permission <> 'none' AND ${match} AND disabled.user_id IS NULL
+        AND access.permission <> 'none' AND disabled.user_id IS NULL
       LIMIT 1
     `;
     const file = row ? snapshotFiles(row.files).find((entry) => entry.path === path) : null;
     return file ? { ...stat, bytes: new TextEncoder().encode(file.content) } : null;
   },
 };
+
+export const seedCloudAiSkills = async (): Promise<void> => {
+  for (const seed of getBuiltinAiSkillTemplates()) await aiSkills.seedOnce(seed);
+};