@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/skills/catalog.d.ts

@@ -64,7 +64,7 @@ export interface ResolvedSkill {
  */
 export declare function resolveSkills(db: KernelSchemaDb, input: Omit<EffectiveSkillsInput, "conversationId"> & {
     conversationId?: string;
-}): Promise<ResolvedSkill[]>;
+}, log?: Pick<Logger, "warn">): Promise<ResolvedSkill[]>;
 /** A pinned skill to read: an effective skill the agent version pins. */
 interface PinnedCandidate {
     id: string;
@@ -81,7 +81,8 @@ interface PinnedCandidate {
  */
 export declare function pinnedFailureText(e: ApiError): string;
 /**
- * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md`, verifies it against
+ * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md` (a platform version's
+ * `platform:<prefix>` from `deployment/<prefix>SKILL.md`), verifies it against
  * the manifest's size and sha256 and returns the parsed body, in order. Every failure throws
  * `storage.unavailable` (Decision 9: the run fails before any model request):
  * - a read error is retried once ({@link PINNED_READ_ATTEMPTS}), then is transient (the user

package/dist/skills/catalog.js

@@ -21,6 +21,7 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { CLAUDE_CODE_TOOL_MAP } from "../runtime/context/claude-tools.js";
 import { sameSnapshot, } from "../runtime/context/skills.js";
 import { StorageService } from "../storage/storage.service.js";
+import { selectedSkills, skillFileStore } from "./usable.js";
 /**
  * 技能目录快照（M5 T14，Ruling M17）：运行开始时解析「此刻对这个对话生效的技能」，与日志里最新一份快照不同才写
  * `skills_catalog`。模型看到的目录与 `Skill` 的名字解析只来自日志，不读实时的库。
@@ -73,43 +74,18 @@ function forModel(all, input, log) {
  * included and not truncated ({@link forModel} gives the model's part). Without
  * `conversationId` (a conversation not created yet) no trial draft applies.
  */
-export async function resolveSkills(db, input) {
-    const orgSkills = [...new Set(input.agent.skills?.orgSkills ?? [])];
-    const rows = await db
-        .selectFrom("skills")
-        .innerJoin("skill_versions", (j) => j
-        .onRef("skill_versions.skill_id", "=", "skills.id")
-        .onRef("skill_versions.version", "=", "skills.current_version"))
-        .leftJoin("catalog_items", "catalog_items.id", "skills.catalog_item_id")
-        .select([
-        "skills.id",
-        "skills.scope",
-        "skills.name",
-        "skills.current_version",
-        "skill_versions.manifest",
-        "skill_versions.object_prefix",
-        "skill_versions.source_format",
-        "catalog_items.name as item_name",
-    ])
-        .where("skills.org_id", "=", input.orgId)
-        .where("skills.deleted_at", "is", null)
-        .where((eb) => {
-        const agentOwn = eb.and([
-            eb("skills.scope", "=", "agent"),
-            eb("skills.agent_id", "=", input.agentId),
-        ]);
-        if (orgSkills.length === 0)
-            return agentOwn;
-        return eb.or([
-            agentOwn,
-            eb.and([eb("skills.scope", "=", "org"), eb("skills.id", "in", orgSkills)]),
-        ]);
-    })
-        .execute();
+export async function resolveSkills(db, input, log) {
+    // Phase 2 (Task 3): `orgSkills` ids may be org skills, org copies linked to a platform skill
+    // (served as its current version under the copy's id, ruling B2) or platform skill ids; only
+    // those usable in the org resolve (skills/usable.ts)
+    const rows = await selectedSkills(db, { orgId: input.orgId, agentId: input.agentId, orgSkills: input.agent.skills?.orgSkills ?? [] }, log);
+    // One skill per name: the agent's own, then an org skill or copy (an id the agent kept from
+    // before the platform component existed), then a platform skill id; ties by id
+    const rank = (r) => r.scope === "agent" ? 0 : r.platformSkillId === r.id ? 2 : 1;
     const byName = new Map();
     for (const r of rows) {
         const prev = byName.get(r.name);
-        if (!prev || (prev.scope === "org" && r.scope === "agent"))
+        if (!prev || rank(r) < rank(prev))
             byName.set(r.name, r);
     }
     const effective = new Map([...byName.values()].map((r) => [
@@ -118,12 +94,12 @@ export async function resolveSkills(db, input) {
             skill: {
                 id: r.id,
                 name: r.name,
-                description: r.manifest.description,
-                version: r.current_version,
-                source: r.object_prefix,
-                ...(r.item_name !== null && { plugin: r.item_name }),
+                description: r.description,
+                version: r.version,
+                source: r.source,
+                ...(r.plugin !== null && { plugin: r.plugin }),
             },
-            format: r.source_format,
+            format: r.format,
             manifest: r.manifest,
         },
     ]));
@@ -210,7 +186,8 @@ export function pinnedFailureText(e) {
     return "File storage is temporarily unavailable, so this agent's pinned skills cannot be read; send the message again later.";
 }
 /**
- * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md`, verifies it against
+ * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md` (a platform version's
+ * `platform:<prefix>` from `deployment/<prefix>SKILL.md`), verifies it against
  * the manifest's size and sha256 and returns the parsed body, in order. Every failure throws
  * `storage.unavailable` (Decision 9: the run fails before any model request):
  * - a read error is retried once ({@link PINNED_READ_ATTEMPTS}), then is transient (the user
@@ -224,9 +201,10 @@ export async function loadPinnedBodies(storage, orgId, pinned, opts = {}) {
     if (pinned.length === 0)
         return [];
     storage.assertAvailable();
-    const store = storage.kernel(orgId);
     const out = [];
     for (const p of pinned) {
+        // a platform version (`platform:<prefix>`) is read from deployment/ (ruling D2)
+        const { store, prefix } = skillFileStore(storage, orgId, p.source);
         const unreadable = (problem) => {
             opts.log?.error("pinned skill unreadable", {
                 orgId,
@@ -246,7 +224,7 @@ export async function loadPinnedBodies(storage, orgId, pinned, opts = {}) {
         for (let attempt = 1; bytes === null; attempt++) {
             let got;
             try {
-                got = await store.get(`${p.source}${SKILL_ENTRY_FILE}`, opts.signal && { signal: opts.signal });
+                got = await store.get(`${prefix}${SKILL_ENTRY_FILE}`, opts.signal && { signal: opts.signal });
                 if (got)
                     bytes = new Uint8Array(await new Response(got.body).arrayBuffer());
             }
@@ -390,7 +368,7 @@ let SkillsCatalogService = class SkillsCatalogService {
     async record(input, opts = {}) {
         const log = opts.log ?? this.log;
         for (let attempt = 1; attempt <= RECORD_ATTEMPTS; attempt++) {
-            const all = await resolveSkills(this.db.db, input);
+            const all = await resolveSkills(this.db.db, input, attempt === 1 ? log : undefined);
             // Warn about manual-only pins once, on the first attempt
             const first = pinnedCandidates(forModel(all, input), input.agent, input, all, attempt === 1 ? log : undefined);
             const pinned = fitPinned(await loadPinnedBodies(this.storage, input.orgId, first, { log }), log, input);

package/dist/skills/changes.controller.d.ts

@@ -12,6 +12,9 @@ declare const DecideBody: z.ZodObject<{
     }>;
     note: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+declare const NoticeParamsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
 /**
  * 共享 agent 的技能变更申请（`/api/v1/orgs/:orgId/skill-changes`，M5 T15，R4）。动作 `approvals.decide`
  * （访客起、仅限用户主体：agent / 服务令牌不能决定，R2）；能否决定由服务按该 agent **当前的负责人**判定，
@@ -47,10 +50,14 @@ export declare class AgentSkillsController {
 /**
  * 收件箱（`GET /api/v1/orgs/:orgId/inbox`，计划取舍 C6：按类型汇总）：当前用户待处理的工具审批与
  * 能决定的技能变更，新的在前、最多 100 项（`truncated` 表示还有更多）。仅限用户主体。
+ * Org admins also see the org's open notices and dismiss them with
+ * `POST /api/v1/orgs/:orgId/inbox/notices/:id/dismiss`.
  */
 export declare class InboxController {
     private readonly inbox;
     constructor(inbox: InboxService);
     list(principal: Principal, org: OrgContext): Promise<InboxView>;
+    /** An org admin dismisses an org notice (`skill_renamed`) -> 204. */
+    dismissNotice(principal: Principal, org: OrgContext, params: z.infer<typeof NoticeParamsSchema>): Promise<void>;
 }
 export {};

package/dist/skills/changes.controller.js

@@ -13,7 +13,7 @@ import { AgentsService } from "../agents/agents.service.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { InboxService } from "../inbox/inbox.service.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZBody } from "../infra/validation/zod-params.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { SkillChangesService, } from "./changes.service.js";
 import { SkillsService } from "./skills.service.js";
@@ -25,6 +25,9 @@ const DecideBody = z
     .strict();
 class SkillChangeDecideBody extends createZodDto(DecideBody, "SkillChangeDecideBody") {
 }
+const NoticeParamsSchema = z.object({ id: z.string().min(1).max(100) });
+class NoticeParams extends createZodDto(NoticeParamsSchema, "InboxNoticeParams") {
+}
 /**
  * 共享 agent 的技能变更申请（`/api/v1/orgs/:orgId/skill-changes`，M5 T15，R4）。动作 `approvals.decide`
  * （访客起、仅限用户主体：agent / 服务令牌不能决定，R2）；能否决定由服务按该 agent **当前的负责人**判定，
@@ -118,6 +121,8 @@ export { AgentSkillsController };
 /**
  * 收件箱（`GET /api/v1/orgs/:orgId/inbox`，计划取舍 C6：按类型汇总）：当前用户待处理的工具审批与
  * 能决定的技能变更，新的在前、最多 100 项（`truncated` 表示还有更多）。仅限用户主体。
+ * Org admins also see the org's open notices and dismiss them with
+ * `POST /api/v1/orgs/:orgId/inbox/notices/:id/dismiss`.
  */
 let InboxController = class InboxController {
     inbox;
@@ -128,6 +133,11 @@ let InboxController = class InboxController {
         const p = requireUser(principal);
         return this.inbox.list(org.orgId, p.account.id);
     }
+    /** An org admin dismisses an org notice (`skill_renamed`) -> 204. */
+    async dismissNotice(principal, org, params) {
+        const p = requireUser(principal);
+        await this.inbox.dismissNotice(org.orgId, p.account.id, params.id);
+    }
 };
 __decorate([
     Get(),
@@ -135,6 +145,14 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg())
 ], InboxController.prototype, "list", null);
+__decorate([
+    Post("notices/:id/dismiss"),
+    HttpCode(204),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(NoticeParams))
+], InboxController.prototype, "dismissNotice", null);
 InboxController = __decorate([
     Controller("api/v1/orgs/:orgId/inbox"),
     __param(0, Inject(InboxService))

package/dist/skills/invoke.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, skillDigest, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { AgentLookup } from "../agents/agent-lookup.js";
 import { ApiError } from "../errors.js";
@@ -18,6 +18,7 @@ import { StorageService } from "../storage/storage.service.js";
 import { BUILTIN } from "../tools/builtin-names.js";
 import { findSkillVersion, readSkillFile, SkillIntegrityError, } from "../tools/builtins/skill-load.js";
 import { invocationOf, resolveSkills } from "./catalog.js";
+import { skillFileStore } from "./usable.js";
 /** A leading `/<name>` or `/<plugin>:<name>`, then whitespace or the end (spec §3.2). */
 const SLASH_COMMAND_RE = /^\/([a-z0-9-]+(?::[a-z0-9-]+)?)(?:\s|$)/;
 /** `/name args` at the very start of a message, or null (`/etc/hosts`, ` /x`, `/Upper`). */
@@ -151,6 +152,7 @@ let SkillInvoker = class SkillInvoker {
         const input = {
             name: a.name,
             skillName: found.skill.name,
+            digest: skillDigest(found.manifest.files),
             version: found.skill.version,
             body,
             invocation: inv,
@@ -159,7 +161,7 @@ let SkillInvoker = class SkillInvoker {
         };
         // a SKILL.md whose body alone renders over the limit can never be invoked: say so, rather than
         // "shorten the arguments"
-        tooLarge(found.skill.name, () => renderSkillBody(body, inv, "", found.skill.name));
+        tooLarge(found.skill.name, () => renderSkillBody(body, inv, "", found.skill.name, input.digest));
         const args = a.args.trim();
         const record = {
             id: found.skill.id,
@@ -219,6 +221,7 @@ let SkillInvoker = class SkillInvoker {
         const task = (child) => renderSkillInvocation({
             name: skill.name,
             skillName: skill.name,
+            digest: skillDigest(found.manifest.files),
             version: skill.version,
             body,
             invocation: inv,
@@ -254,7 +257,9 @@ let SkillInvoker = class SkillInvoker {
         this.storage.assertAvailable();
         let bytes;
         try {
-            bytes = await readSkillFile(this.storage.kernel(orgId), `${r.skill.source}${SKILL_ENTRY_FILE}`, md);
+            // a platform version (`platform:<prefix>`) is read from deployment/ (ruling D2)
+            const { store, prefix } = skillFileStore(this.storage, orgId, r.skill.source);
+            bytes = await readSkillFile(store, `${prefix}${SKILL_ENTRY_FILE}`, md);
         }
         catch (e) {
             if (e instanceof SkillIntegrityError)

package/dist/skills/package.d.ts

@@ -1,4 +1,5 @@
 import { type SkillInvocation } from "@capybara-hq/plugin-sdk";
+import type { SkillManifest } from "../db/kernel-schema.js";
 /**
  * 技能包（zip）解包与校验。zip 一律当作恶意输入：
  *
@@ -45,7 +46,7 @@ export interface SkillPackage {
 export declare function storedInvocation(i: SkillInvocation): SkillInvocation | undefined;
 /**
  * Invalid zip or skill content (`problems` lists each one, in English). Independent of HTTP: a
- * skill upload maps it to `skill.invalid_package`, an enterprise catalog import to
+ * skill upload maps it to `skill.invalid_package`, a platform catalog import to
  * `catalog.invalid_manifest`.
  */
 export declare class SkillArchiveError extends Error {
@@ -85,3 +86,21 @@ export declare function checkSkillFiles(files: SkillPackageFile[], opts?: {
  * 不合法 → {@link SkillArchiveError}。
  */
 export declare function readZipFiles(bytes: Uint8Array, maxBytes: number): Promise<SkillPackageFile[]>;
+/**
+ * Checks skill files that are already unpacked (paths relative to the skill root), e.g. the ones
+ * built from text, with the rules of {@link readSkillPackage}. Invalid -> `skill.invalid_package`.
+ */
+export declare function checkBuiltSkillFiles(files: SkillPackageFile[]): SkillPackage;
+/** A validated skill package: its name, description, files and invocation. */
+export interface SkillPackageInput {
+    name: string;
+    description: string;
+    files: SkillPackageFile[];
+    /** Phase D: stored in the manifest when it is not the default. */
+    invocation?: SkillInvocation;
+}
+/**
+ * The stored manifest of a skill package (the invocation only when it is not the default); org
+ * skills and platform skills store the same shape.
+ */
+export declare function skillManifest(pkg: SkillPackageInput): SkillManifest;

package/dist/skills/package.js

@@ -48,7 +48,7 @@ export function storedInvocation(i) {
 const ignored = (path) => path.startsWith("__MACOSX/") || path === ".DS_Store" || path.endsWith("/.DS_Store");
 /**
  * Invalid zip or skill content (`problems` lists each one, in English). Independent of HTTP: a
- * skill upload maps it to `skill.invalid_package`, an enterprise catalog import to
+ * skill upload maps it to `skill.invalid_package`, a platform catalog import to
  * `catalog.invalid_manifest`.
  */
 export class SkillArchiveError extends Error {
@@ -225,3 +225,30 @@ export async function readZipFiles(bytes, maxBytes) {
     }
     return raw;
 }
+/**
+ * Checks skill files that are already unpacked (paths relative to the skill root), e.g. the ones
+ * built from text, with the rules of {@link readSkillPackage}. Invalid -> `skill.invalid_package`.
+ */
+export function checkBuiltSkillFiles(files) {
+    try {
+        return { ...checkSkillFiles(files), files };
+    }
+    catch (e) {
+        if (e instanceof SkillArchiveError)
+            throw invalid(e.problems);
+        throw e;
+    }
+}
+/**
+ * The stored manifest of a skill package (the invocation only when it is not the default); org
+ * skills and platform skills store the same shape.
+ */
+export function skillManifest(pkg) {
+    const invocation = pkg.invocation && storedInvocation(pkg.invocation);
+    return {
+        name: pkg.name,
+        description: pkg.description,
+        files: pkg.files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
+        ...(invocation !== undefined && { invocation }),
+    };
+}

package/dist/skills/skills.controller.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { OwnedItems, type OwnedSkillDeletePreview } from "../catalog/owned-items.js";
 import { type CreatedAttachment } from "../conversations/attachments.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
@@ -8,7 +9,17 @@ declare const UploadBody: z.ZodObject<{
     size: z.ZodNumber;
 }, z.core.$strict>;
 declare const CreateBody: z.ZodObject<{
-    uploadId: z.ZodString;
+    uploadId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    description: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    shareable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const IdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const ShareableBody: z.ZodObject<{
+    shareable: z.ZodBoolean;
 }, z.core.$strict>;
 /**
  * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
@@ -21,20 +32,44 @@ declare const CreateBody: z.ZodObject<{
  *      `POST /attachments/:id/finalize`, or skip it and let the next step finalize);
  *   3. `POST /` `{ uploadId }` unpacks and checks it, creating a skill or adding a version to the
  *      skill with the same name;
- *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3).
+ *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3; `GET /:id/delete-preview` says
+ *   what it does), `PUT /:id/shareable` sets 可共享 (plugin scope phase 3, ruling P3-6).
  * When the deployment setting `customSkills` is deny, registering an upload and creating both
  * return 403 `catalog.custom_disabled` (decided in the service, re-checked inside the org row lock
- * on create); installing skills from the enterprise catalog is unaffected.
+ * on create); installing skills from the platform catalog is unaffected.
  */
 export declare class SkillsController {
     private readonly skills;
-    constructor(skills: SkillsService);
+    /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
+    private readonly owned;
+    constructor(skills: SkillsService, 
+    /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
+    owned: OwnedItems);
     createUpload(principal: Principal, org: OrgContext, body: z.infer<typeof UploadBody>): Promise<CreatedAttachment>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<UploadedSkill>;
     list(principal: Principal, org: OrgContext): Promise<{
         skills: SkillSummary[];
     }>;
     get(principal: Principal, org: OrgContext, id: string): Promise<SkillDetail>;
+    /**
+     * Sets 可共享 on the org's own skill (`{ shareable }` -> 200 `{ id, shareable }`): only an org
+     * skill of the org's own (P3-6: an agent's skill or a copy of another owner's platform skill ->
+     * 409 `catalog.not_owned`); one it promoted writes its platform row too (ruling P3-2).
+     */
+    setShareable(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>, body: z.infer<typeof ShareableBody>): Promise<{
+        id: string;
+        shareable: boolean;
+    }>;
+    /**
+     * What deleting the skill does (pre-flight F19, P3-19; nothing written): `outcome`
+     * `transferred` when it was shared and another org uses it (`orgs`), else `removed`; `agents`
+     * the org's agents that lose it.
+     */
+    deletePreview(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>): Promise<OwnedSkillDeletePreview>;
+    /**
+     * Soft-deletes the skill; one the org shared that another org uses is transferred to the
+     * platform first (P3-19, platform notice `ownership_transferred`). 204.
+     */
     remove(principal: Principal, org: OrgContext, id: string): Promise<void>;
 }
 export {};

package/dist/skills/skills.controller.js

@@ -7,14 +7,16 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
-import { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { hasControlChars, isSkillName, MEDIA_NAME_MAX_CHARS, SKILL_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put } from "@nestjs/common";
 import { z } from "zod";
+import { OwnedItems } from "../catalog/owned-items.js";
 import { SKILL_PACKAGE_UPLOAD_MAX_BYTES, } from "../conversations/attachments.service.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZBody } from "../infra/validation/zod-params.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { SKILL_WRITE_MAX_BYTES } from "../tools/builtins/skill-write.js";
 import { SkillsService, } from "./skills.service.js";
 const UploadBody = z
     .object({
@@ -26,11 +28,31 @@ const UploadBody = z
     size: z.number().int().min(1).max(SKILL_PACKAGE_UPLOAD_MAX_BYTES),
 })
     .strict();
-const CreateBody = z.object({ uploadId: z.string().min(1).max(100) }).strict();
+const CreateBody = z
+    .object({
+    uploadId: z.string().min(1).max(100).optional(),
+    name: z
+        .string()
+        .refine(isSkillName, "name must be 1-64 lowercase letters, digits and single hyphens")
+        .optional(),
+    description: z.string().min(1).max(SKILL_LIMITS.descriptionMaxChars).optional(),
+    body: z.string().max(SKILL_WRITE_MAX_BYTES).optional(),
+    shareable: z.boolean().optional(),
+})
+    .strict()
+    .refine((v) => v.uploadId !== undefined
+    ? v.name === undefined && v.description === undefined && v.body === undefined
+    : v.name !== undefined && v.description !== undefined && v.body !== undefined, "send either { uploadId } or { name, description, body }");
 class SkillUploadBody extends createZodDto(UploadBody, "SkillUploadBody") {
 }
 class SkillCreateBody extends createZodDto(CreateBody, "SkillCreateBody") {
 }
+const IdParams = z.object({ id: z.string().min(1).max(100) });
+const ShareableBody = z.object({ shareable: z.boolean() }).strict();
+class SkillIdParams extends createZodDto(IdParams, "SkillIdParams") {
+}
+class SkillShareableBody extends createZodDto(ShareableBody, "SkillShareableBody") {
+}
 /**
  * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
  * - read: `skills.read` (member and up) — `GET /` list, `GET /:id` detail (versions and file
@@ -42,15 +64,20 @@ class SkillCreateBody extends createZodDto(CreateBody, "SkillCreateBody") {
  *      `POST /attachments/:id/finalize`, or skip it and let the next step finalize);
  *   3. `POST /` `{ uploadId }` unpacks and checks it, creating a skill or adding a version to the
  *      skill with the same name;
- *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3).
+ *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3; `GET /:id/delete-preview` says
+ *   what it does), `PUT /:id/shareable` sets 可共享 (plugin scope phase 3, ruling P3-6).
  * When the deployment setting `customSkills` is deny, registering an upload and creating both
  * return 403 `catalog.custom_disabled` (decided in the service, re-checked inside the org row lock
- * on create); installing skills from the enterprise catalog is unaffected.
+ * on create); installing skills from the platform catalog is unaffected.
  */
 let SkillsController = class SkillsController {
     skills;
-    constructor(skills) {
+    owned;
+    constructor(skills, 
+    /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
+    owned) {
         this.skills = skills;
+        this.owned = owned;
     }
     async createUpload(principal, org, body) {
         const p = requireUser(principal);
@@ -58,7 +85,17 @@ let SkillsController = class SkillsController {
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
-        return this.skills.upload(org.orgId, p.account.id, body.uploadId, patTokenId(p));
+        const tokenId = patTokenId(p);
+        if (body.uploadId !== undefined) {
+            return this.skills.upload(org.orgId, p.account.id, body.uploadId, tokenId, body.shareable);
+        }
+        return this.skills.createFromText(org.orgId, p.account.id, {
+            name: body.name,
+            description: body.description,
+            body: body.body,
+            ...(body.shareable !== undefined && { shareable: body.shareable }),
+            ...(tokenId !== undefined && { actorTokenId: tokenId }),
+        });
     }
     async list(principal, org) {
         requireUser(principal);
@@ -68,9 +105,34 @@ let SkillsController = class SkillsController {
         requireUser(principal);
         return this.skills.get(org.orgId, id);
     }
+    /**
+     * Sets 可共享 on the org's own skill (`{ shareable }` -> 200 `{ id, shareable }`): only an org
+     * skill of the org's own (P3-6: an agent's skill or a copy of another owner's platform skill ->
+     * 409 `catalog.not_owned`); one it promoted writes its platform row too (ruling P3-2).
+     */
+    async setShareable(principal, org, params, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        await this.owned.setShareable(org.orgId, p.account.id, { kind: "skill", id: params.id }, body.shareable, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+        return { id: params.id, shareable: body.shareable };
+    }
+    /**
+     * What deleting the skill does (pre-flight F19, P3-19; nothing written): `outcome`
+     * `transferred` when it was shared and another org uses it (`orgs`), else `removed`; `agents`
+     * the org's agents that lose it.
+     */
+    async deletePreview(principal, org, params) {
+        requireUser(principal);
+        return this.owned.previewSkillDelete(org.orgId, params.id);
+    }
+    /**
+     * Soft-deletes the skill; one the org shared that another org uses is transferred to the
+     * platform first (P3-19, platform notice `ownership_transferred`). 204.
+     */
     async remove(principal, org, id) {
         const p = requireUser(principal);
-        await this.skills.softDelete(org.orgId, id, p.account.id, patTokenId(p));
+        const tokenId = patTokenId(p);
+        await this.owned.deleteSkill(org.orgId, p.account.id, id, tokenId !== undefined ? { actorTokenId: tokenId } : {});
     }
 };
 __decorate([
@@ -100,6 +162,21 @@ __decorate([
     __param(1, CurrentOrg()),
     __param(2, Param("id"))
 ], SkillsController.prototype, "get", null);
+__decorate([
+    Put(":id/shareable"),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SkillIdParams)),
+    __param(3, ZBody(SkillShareableBody))
+], SkillsController.prototype, "setShareable", null);
+__decorate([
+    Get(":id/delete-preview"),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SkillIdParams))
+], SkillsController.prototype, "deletePreview", null);
 __decorate([
     Delete(":id"),
     HttpCode(204),
@@ -110,6 +187,7 @@ __decorate([
 ], SkillsController.prototype, "remove", null);
 SkillsController = __decorate([
     Controller("api/v1/orgs/:orgId/skills"),
-    __param(0, Inject(SkillsService))
+    __param(0, Inject(SkillsService)),
+    __param(1, Inject(OwnedItems))
 ], SkillsController);
 export { SkillsController };

package/dist/skills/skills.module.js

@@ -6,6 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Module } from "@nestjs/common";
 import { AgentLookupModule } from "../agents/agent-lookup.js";
+import { CatalogImportModule } from "../catalog/catalog-import.module.js";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
@@ -22,7 +23,15 @@ let SkillsModule = class SkillsModule {
 };
 SkillsModule = __decorate([
     Module({
-        imports: [StorageModule, OrgLockModule, EventLogModule, AttachmentsModule, AgentLookupModule],
+        imports: [
+            StorageModule,
+            OrgLockModule,
+            EventLogModule,
+            AttachmentsModule,
+            AgentLookupModule,
+            // the owner's new version of a skill it promoted goes to the platform row (ruling P3-4)
+            CatalogImportModule,
+        ],
         providers: [SkillsService, SkillChangesService, SkillsCatalogService, SkillInvoker],
         exports: [SkillsService, SkillChangesService, SkillsCatalogService, SkillInvoker],
     })