@hasna/skills 0.10.80 → 0.10.81

package/dist/lib/agent-discovery.d.ts

@@ -93,6 +93,17 @@ export interface ReviewedDiscoveryInputs {
 /** Project one native configuration's witnessed fields, exactly as discovery
  * binds them. Used for both the current file and a preserved reviewed preimage. */
 export declare function projectNativeDiscoveryFields(text: string, format: "json" | "toml" | "yaml", fields: readonly string[], path: string): string;
+/** Codex name reconcile only, after the caller verified that every enrolled
+ * plugin parent in `parents` kept its reviewed capability tuple (manifest apart
+ * from its version, app, MCP and remote receipt). A stale full-byte witness of a
+ * manifest, app or MCP declaration or skill document under one of those parents'
+ * version roots is replaced, in its own digest mode, by the same role's file in
+ * every current version root. Every other witness is kept unchanged, so any
+ * other change still refuses when the rebased binding is verified. */
+export declare function rebaseCodexEnrolledCacheWitnesses(binding: AgentDiscoveryBinding, cache: string, parents: readonly string[], strictlySkillsOnly: (parent: string) => boolean): {
+    binding: AgentDiscoveryBinding;
+    rebased: string[];
+};
 /** Called only after the owning planner validated discovery and capabilities.
  * New roots must already be body-free; absent roots need the prior typed proof. */
 export declare function captureRetiredCodexDiscovery(binding: AgentDiscoveryBinding, controls: CodexPluginSkillControl[], rules: unknown): AgentDiscoveryBinding;

package/dist/lib/agent-integration.d.ts

@@ -1,5 +1,6 @@
 import { type CodexAdmissionReceipt, type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
-import { type ReviewedCodexSkillDenial } from "./codex-plugin-skill-controls.js";
+import { connectCodexHookRpc } from "./codex-hook-rpc.js";
+import { type ReviewedCodexSkillDenial, type CodexPluginSkillControl } from "./codex-plugin-skill-controls.js";
 import { type CodexNativeHookEnvelope, type ProcessInspector, type NativePolicyHelperRunner } from "./codex-native-skill-policy.js";
 import { type CodexNativeSkillCatalog } from "./codex-native-skill-catalog.js";
 import type { NativeDiscoveryWitnessKind } from "./native-discovery-witness-change.js";
@@ -49,6 +50,7 @@ export interface AgentConfigChange {
     after: string;
 }
 export interface AgentIntegrationPlan {
+    codexReconcile?: CodexPluginReconcilePlanState;
     cacheWitnessUpgrade?: CodexSemanticCacheUpgrade;
     reviewArtifactSources?: Array<{
         path: string;
@@ -152,6 +154,7 @@ export declare function planAgentIntegration(options: {
     reviewedCacheAlias?: string;
     codexNativeCatalog?: CodexNativeSkillCatalog;
     codexSkillDenials?: ReviewedCodexSkillDenial[];
+    codexReconcile?: CodexPluginReconcileInput;
 }): AgentIntegrationPlan;
 export interface ClaudeManagedHookProjection {
     schema: "hasna.claude-managed-hook-projection.v1";
@@ -238,11 +241,126 @@ export interface ReviewArtifactMigration {
 }
 /** Explicit exact-proof migration. Never captures a new catalog or refreshes live inputs. */
 export declare function planReviewedArtifactMigration(options: ReviewArtifactMigration): AgentIntegrationPlan;
+/** Exact copies, names and deny rows one Codex name reconcile plans. */
+export interface CodexPluginReconcileInput {
+    copies: Array<{
+        path: string;
+        hash: string;
+    }>;
+    /** New qualified names added to the reviewed controls. */
+    names: string[];
+    /** Plugin parents whose documents the reconcile reviews: enrolled and newly enrolled. */
+    parents: string[];
+    /** Caller-verified native install receipts: of newly enrolled remote parents,
+     * and of enrolled remote parents whose stored controls lack one (healed). */
+    remoteIdentities: Record<string, string>;
+    /** Catalog-only skills outside the plugin cache: deny-only rows, no control. */
+    nameDenies: string[];
+    pathDenies: string[];
+    /** The saved review with stale enrolled-plugin cache witnesses re-captured. */
+    discovery?: AgentDiscoveryBinding;
+}
+export interface CodexPluginReconcileRequest {
+    home: string;
+    dataDir: string;
+    projectDir: string;
+    catalog: CodexNativeSkillCatalog;
+}
+export interface CodexPluginReconcilePlanState extends CodexPluginReconcileInput {
+    request: CodexPluginReconcileRequest;
+}
+export interface CodexPluginReconcileReport {
+    codexVersion: string;
+    /** Qualified names this reconcile adds to the reviewed controls and denies by name. */
+    enrolled: string[];
+    /** Qualified names already enrolled before this reconcile. */
+    alreadyEnrolled: number;
+    /** Catalog skills outside the plugin cache (Codex runtime plugins) denied by their stable qualified name. */
+    denied: string[];
+    /** Skills denied by exact path because no stable qualified name covers them, with the reason. */
+    pathDenied: Array<{
+        name: string;
+        path: string;
+        reason: "plugin-disabled" | "no-qualified-name";
+    }>;
+    /** Plugins explicitly disabled in [plugins]: no enrollment and no refusal. */
+    inactive: string[];
+    /** Every plugin this run classified as skills-only, citing the manifests read. */
+    classified: Array<{
+        pluginId: string;
+        capabilities: string[];
+        manifests: string[];
+    }>;
+    /** Reviewed cache witnesses re-captured after a skills-only version change. */
+    rebasedWitnesses: number;
+    /** Enrolled remote plugins whose controls stored without the install receipt gain the verified one. */
+    bound: string[];
+    /** Plugin-cache skill names left as they are: an existing path rule or an inactive plugin already makes them inert. */
+    skipped: number;
+    /** Native skills Codex loads after the reconcile; always exactly the bridge. */
+    allowed: string[];
+}
+/** A refusal: nothing was written and the guard keeps blocking with `code`. */
+export declare class CodexPluginReconcileRefusal extends Error {
+    readonly code: string;
+    readonly refusals: Array<{
+        pluginId: string;
+        reasons: string[];
+        manifests?: string[];
+    }>;
+    constructor(code: string, detail: string, refusals?: Array<{
+        pluginId: string;
+        reasons: string[];
+        manifests?: string[];
+    }>);
+}
+/** The reconcile writes only appended disable rows and the bounded policy fields
+ * that record them; anything else is a different review and refuses. */
+export declare function assertCodexReconcileScope(plan: AgentIntegrationPlan, scope: {
+    configPath: string;
+    policyPath: string;
+    prior: CodexPluginSkillControl[];
+    names: string[];
+    remoteIdentities?: Record<string, string>;
+    discovery: AgentDiscoveryBinding;
+}): void;
+/** Read-only plan for `skills hook codex-reconcile`. Enumerates the plugin-cache
+ * skills the strict guard refuses and the catalog skills Codex would load from
+ * its runtime cache; enrolls plugin-cache names whose capability tuple is
+ * unchanged (or a not yet enrolled skills-only plugin), denies runtime skills by
+ * qualified name (by exact path, reported, when Codex gives none), and refreshes
+ * the reviewed binding through planAgentIntegration. A null plan means nothing
+ * needs writing. Every refusal writes nothing. */
+export declare function planCodexPluginNameReconcile(request: CodexPluginReconcileRequest): {
+    plan: AgentIntegrationPlan | null;
+    report: CodexPluginReconcileReport;
+};
 export declare function applyAgentIntegration(plan: AgentIntegrationPlan, options?: CodexCorpusWriteOptions): {
     changed: string[];
     backups: string[];
     rootAliases?: AgentRootAlias[];
 } & CodexAdmissionReceipt;
+export interface CodexReconcileApplyOptions extends CodexCorpusWriteOptions {
+    /** The Codex home the owned app-server uses; omit for the default ~/.codex. */
+    codexHome?: string;
+    /** Test seam for the owned Codex app-server; production starts `codex app-server`. */
+    connect?: typeof connectCodexHookRpc;
+}
+export interface CodexReconcileApplyResult extends CodexAdmissionReceipt {
+    changed: string[];
+    backups: string[];
+    receipt?: string;
+    nativeConfigVersion?: string;
+    rootAliases?: AgentRootAlias[];
+}
+/** Apply a Codex name reconcile. The deny rows go through Codex's own writer
+ * (`config/batchWrite` with the user layer's `expectedVersion` and
+ * `reloadUserConfig`), so a concurrent Codex writer such as the desktop app
+ * makes the write refuse instead of being overwritten. The policy is written in
+ * the Skills transaction only after the config readback matches the plan.
+ * Either failure is compensated; the config is restored only through Codex's
+ * writer and only when nobody changed it since this run's write. */
+export declare function applyCodexPluginReconcile(plan: AgentIntegrationPlan, options?: CodexReconcileApplyOptions): Promise<CodexReconcileApplyResult>;
 export declare function archiveNativeSkills(inventory: NativeSkillEntry[], options: CodexCorpusWriteOptions & {
     dataDir?: string;
     includeUnmanaged?: boolean;

package/dist/lib/codex-native-skill-catalog.d.ts

@@ -12,6 +12,29 @@ export interface CodexNativeSkillCatalog {
     skills: CodexNativeSkill[];
     /** Added in 0.10.20; older reviewed skills/list receipts remain valid for listed skills. */
     plugins?: CodexInstalledPlugin[];
+    /** Remote install receipts read before the capture started any Codex process. */
+    remoteReceipts?: CodexRemoteReceiptSnapshot;
+}
+/** Schema of the remote install receipt snapshot embedded in a captured catalog. */
+export declare const CODEX_REMOTE_RECEIPT_SNAPSHOT_SCHEMA: "hasna.skills-codex-remote-receipts.v1";
+/** One plugin cache parent's native remote install receipt as it was on disk
+ * before Codex started. `remotePluginId` is null when the receipt is not a
+ * strictly valid schema-1 receipt; `sha256` is null when it is not a regular,
+ * unlinked file of at most 16 KiB. */
+export type CodexRemoteReceiptObservation = {
+    pluginId: string;
+    receipt: "absent";
+} | {
+    pluginId: string;
+    receipt: "present";
+    sha256: string | null;
+    remotePluginId: string | null;
+    mtimeMs: number;
+};
+export interface CodexRemoteReceiptSnapshot {
+    schema: typeof CODEX_REMOTE_RECEIPT_SNAPSHOT_SCHEMA;
+    cacheRoot: string;
+    plugins: CodexRemoteReceiptObservation[];
 }
 /** Safe installed-plugin identity needed when Codex hides a path-disabled skill. */
 export interface CodexInstalledPlugin {
@@ -28,6 +51,11 @@ export interface CodexInstalledPlugin {
     /** Declared local installation input, distinct from the loaded cache root. */
     sourcePath?: string;
 }
+/** The one remote rule for every receipt decision (install review, reconcile
+ * and the inactive rule): Codex reports a remote source, or reports any remote
+ * identity. A projected row can keep its remotePluginId while a missing or
+ * unrecognized source projects to no sourceType, so the id alone counts. */
+export declare function codexPluginIsRemote(plugin: Pick<CodexInstalledPlugin, "sourceType" | "remotePluginId"> | undefined): boolean;
 /** Codex 0.160 derives remote installed keys from these native scope realms.
  * A nonremote declaration in one of them cannot prove config-owned enablement:
  * remote reconciliation may replace enabled even while config stays disabled. */
@@ -42,6 +70,16 @@ export declare function projectCodexNativeSkillCatalog(response: unknown, cwd: s
 export declare function projectCodexInstalledPlugins(response: unknown): CodexInstalledPlugin[];
 /** Validate the bounded stored projection when it is consumed by a review. */
 export declare function projectCodexInstalledPluginEntries(value: unknown): CodexInstalledPlugin[];
+/** Read every plugin cache parent's native remote install receipt. Call it
+ * before any Codex process starts: starting the app-server rewrites each remote
+ * plugin's receipt to its own state, so a later read observes healed bytes and
+ * cannot show a receipt that was missing or stale. Never follows an alias. */
+export declare function captureCodexRemoteReceiptSnapshot(cache: string): CodexRemoteReceiptSnapshot;
+/** The plugin cache identity a snapshot is bound to: the real path of its
+ * deepest existing ancestor plus the rest, so an absent cache still compares. */
+export declare function canonicalCacheRoot(cache: string): string;
+/** Validate an embedded snapshot when a review consumes it; null when invalid. */
+export declare function projectCodexRemoteReceiptSnapshot(value: unknown): CodexRemoteReceiptSnapshot | null;
 /** Read one consumer's catalog through an owned, bounded native client. The RPC
  * transport owns request deadlines and child shutdown. Native discovery can
  * maintain its own caches; callers must constrain writes when requiring isolation. */

package/dist/lib/codex-plugin-capability-paths.d.ts

@@ -19,6 +19,14 @@ export declare const CODEX_PLUGIN_MANIFEST_DIRECTORIES: readonly string[];
  * codexPluginRootCapabilityEntry so a case-insensitive file system cannot alias
  * one. */
 export declare const CODEX_PLUGIN_ROOT_CAPABILITY_ENTRIES: readonly string[];
+/** The only Codex manifest keys that are identity and display metadata, the
+ * default skills root and the reviewed `.app.json` connector declaration. Any
+ * other key (hooks, commands, extensions, MCP servers, agents, unknown keys)
+ * is a capability or unreviewed. The vendor-refresh guard admits exactly these;
+ * the Codex name reconcile treats `apps` as the app capability. */
+export declare const CODEX_PLUGIN_MANIFEST_KNOWN_KEYS: readonly string[];
+/** The default skills root, which vendor manifests spell out. */
+export declare const CODEX_PLUGIN_DEFAULT_SKILLS_PATHS: readonly string[];
 /** Case-insensitive comparison form. Upper- then lower-casing also folds the
  * Kelvin sign, long s and dotless i onto their ASCII letters, so a name a
  * case-insensitive file system could open as a capability entry folds onto it. */

package/dist/lib/codex-plugin-reconcile.d.ts

@@ -0,0 +1,74 @@
+import { type CodexReconcileApplyOptions } from "./agent-integration.js";
+import { type CodexNativeSkillCatalog } from "./codex-native-skill-catalog.js";
+export declare const CODEX_RECONCILE_RESULT_SCHEMA: "hasna.skills-codex-reconcile.v1";
+export type CodexReconcileOutcome = "applied" | "unchanged" | "planned" | "refused" | "error";
+export interface CodexReconcileResult {
+    schema: typeof CODEX_RECONCILE_RESULT_SCHEMA;
+    mode: "preview" | "apply";
+    outcome: CodexReconcileOutcome;
+    /** Present exactly when the outcome is refused or error. */
+    code?: string;
+    message?: string;
+    codexVersion: string | null;
+    counts: {
+        enrolled: number;
+        alreadyEnrolled: number;
+        denied: number;
+        pathDenied: number;
+        skipped: number;
+        allowed: number;
+    };
+    /** Plugin-cache names added to the reviewed controls and denied by name. */
+    enrolled: string[];
+    /** Runtime-cache skills denied by their stable qualified name (no plugin control exists for them). */
+    denied: string[];
+    /** Skills denied by exact path, each with why no stable qualified name covers it. */
+    pathDenied: Array<{
+        name: string;
+        path: string;
+        reason: "plugin-disabled" | "no-qualified-name";
+    }>;
+    /** Inactive plugins (config disables them and Codex reports them disabled from a config-controlled source): neither enrolled nor refused. */
+    inactive: string[];
+    /** Plugins classified skills-only, each citing the manifest paths that were read. */
+    classified: Array<{
+        pluginId: string;
+        capabilities: string[];
+        manifests: string[];
+    }>;
+    /** Reviewed cache witnesses re-captured after a skills-only version change. */
+    rebasedWitnesses: number;
+    /** Enrolled remote plugins whose controls, stored without the install receipt, gain the verified one. */
+    bound: string[];
+    /** Native skills Codex loads afterwards; exactly the bridge, or the result is refused. */
+    allowed: string[];
+    /** Plugins whose capability kinds need a review, with the manifests read (refused only). */
+    refusals?: Array<{
+        pluginId: string;
+        reasons: string[];
+        manifests?: string[];
+    }>;
+    /** Files written (applied) or that apply would write (planned). */
+    changes: string[];
+    receipt?: string;
+    backups?: string[];
+}
+export declare function classifyCodexReconcileError(error: unknown): Pick<CodexReconcileResult, "outcome" | "code" | "message" | "refusals">;
+export interface CodexReconcileOptions {
+    apply: boolean;
+    home: string;
+    projectDir: string;
+    dataDir?: string;
+    codexCommand?: string;
+    codexHome?: string;
+    /** Test seam for the native catalog read; production uses the Codex app-server. */
+    captureCatalog?: (options: {
+        command: string;
+        home: string;
+        codexHome?: string;
+        cwd: string;
+    }) => Promise<CodexNativeSkillCatalog>;
+    /** Test seam for Codex's own config writer; production starts `codex app-server`. */
+    connect?: CodexReconcileApplyOptions["connect"];
+}
+export declare function runCodexPluginReconcile(options: CodexReconcileOptions): Promise<CodexReconcileResult>;

package/dist/lib/codex-plugin-skill-controls.d.ts

@@ -1,4 +1,4 @@
-import { type CodexNativeSkillCatalog } from "./codex-native-skill-catalog.js";
+import { type CodexInstalledPlugin, type CodexNativeSkillCatalog } from "./codex-native-skill-catalog.js";
 export interface CodexPluginSkillControl {
     name: string;
     pluginId: string;
@@ -35,6 +35,35 @@ type Read = (path: string) => string;
 /** The remote plugin identifier from the exact native install receipt Codex
  * writes beside a remote plugin's versions, or null when it is absent or invalid. */
 export declare function codexRemoteInstallReceipt(parent: string, read: Read): string | null;
+/** Named install refusals for a plugin Codex's catalog reports as remote. */
+export declare const CODEX_REMOTE_RECEIPT_MISSING = "CODEX_REMOTE_RECEIPT_MISSING";
+export declare const CODEX_REMOTE_RECEIPT_MISMATCH = "CODEX_REMOTE_RECEIPT_MISMATCH";
+export declare const CODEX_REMOTE_RECEIPT_SNAPSHOT_REQUIRED = "CODEX_REMOTE_RECEIPT_SNAPSHOT_REQUIRED";
+/** The remote identity the reconcile may bind for a plugin Codex reports as
+ * remote: the catalog's id when the receipt read before Codex started named it
+ * and the current receipt still does; null otherwise. A catalog without a
+ * valid pre-start reading for this cache refuses (SNAPSHOT_REQUIRED). */
+export declare function codexPreStartRemoteReceipt(catalog: CodexNativeSkillCatalog, cache: string, parent: string, plugin: {
+    id: string;
+    remotePluginId?: string;
+}, read: Read): string | null;
+/** Whether an enrolled parent's bound receipt was not there, with that id,
+ * before Codex started. Applies when a control binds a receipt and the parent
+ * exists (an absent parent is left to its own rules); a catalog without a
+ * valid pre-start reading for this cache then refuses (SNAPSHOT_REQUIRED). */
+export declare function codexPreStartReceiptChanged(catalog: CodexNativeSkillCatalog, cache: string, parentControls: CodexPluginSkillControl[]): boolean;
+/** What a reconcile does with an enrolled parent whose stored controls do not
+ * all carry its receipt (policies stored before every control recorded it).
+ * A plugin Codex reports as remote is healed: every control gets the catalog's
+ * id, on exactly the fresh-install proof (requireRemoteInstallReceipt: the
+ * pre-start reading and the current receipt both name it; MISSING or MISMATCH
+ * otherwise), and only when every bound control already agrees ("refuse").
+ * A plugin Codex does not report as remote refuses when only some controls are
+ * bound. null: nothing to heal (every control bound, none bound and not
+ * reported remote, or the parent is absent and left to its own rules). */
+export declare function codexStoredReceiptHeal(catalog: CodexNativeSkillCatalog, cache: string, parentControls: CodexPluginSkillControl[], plugin: CodexInstalledPlugin | undefined, read: Read): {
+    heal: string;
+} | "refuse" | null;
 /** Whether a vendor refresh's `.app.json` connector declaration is valid under
  * the same appControls validation rootControls applies (duplicate keys, the
  * single `apps` object, app names, `id`/`category`/`required` only, types and
@@ -85,5 +114,43 @@ export declare function reviewCodexPluginSkillControls(catalog: CodexNativeSkill
  * The caller verifies discovery/config witnesses before consuming this result. */
 export declare function isReviewedCodexPluginInactive(document: string, cache: string, controls: CodexInactivePluginControl[], pluginSettings: unknown, rules: unknown, read: Read): boolean;
 export declare function isReviewedCodexPluginSkillDisabled(document: string, cache: string, controls: CodexPluginSkillControl[], rules: unknown, read: Read): boolean;
+/** Refusal code for a plugin change that touches more than its skill names: a
+ * new or changed app, MCP, hooks, manifest or remote installation capability. */
+export declare const CODEX_PLUGIN_CAPABILITY_REVIEW_REQUIRED = "CODEX_PLUGIN_CAPABILITY_REVIEW_REQUIRED";
+export type CodexPluginCapabilityReason = "app" | "mcp" | "hooks" | "commands" | "agents" | "manifest" | "manifest-location" | "remote" | "unsupported";
+/** Why a plugin Skills has not enrolled needs a review before its skills can be
+ * enrolled automatically. Empty only when every version root holds nothing but
+ * a supported skills-only manifest and skills. A remote installation is not
+ * itself a capability; its receipt is checked separately. */
+export declare function unenrolledCodexPluginCapabilities(parent: string, read: Read): CodexPluginCapabilityReason[];
+/** The same classification with its evidence: every manifest path read. A
+ * skills-only result (no reasons) always names at least one manifest. */
+export declare function unenrolledCodexPluginEvidence(parent: string, read: Read): {
+    reasons: CodexPluginCapabilityReason[];
+    manifests: string[];
+};
+/** Capability evidence for a plugin root outside the plugin cache (a Codex
+ * runtime), where the version-directory contract does not apply. */
+export declare function codexPluginRootEvidence(root: string, read: Read): {
+    reasons: CodexPluginCapabilityReason[];
+    manifests: string[];
+};
+/** The strict scan for an enrolled plugin, run in addition to the reviewed-tuple
+ * check over every current version root: anything the reviewed tuple does not
+ * bind (a root plugin.json, hooks.json, commands/ or agents/, another manifest
+ * directory, a case variant, a nested declaration, a link) is a capability. */
+export declare function enrolledCodexPluginStrictChanges(parentControls: CodexPluginSkillControl[], read: Read): CodexPluginCapabilityReason[];
+/** Which capability of an enrolled plugin parent no longer matches its reviewed
+ * controls. Empty exactly when reviewedCodexPluginCapabilitiesUnchanged accepts it. */
+export declare function codexPluginCapabilityChanges(cache: string, parentControls: CodexPluginSkillControl[], read: Read, rules?: unknown): CodexPluginCapabilityReason[];
+/** Add newly enrolled qualified names to the reviewed control set. Never removes
+ * an existing control, and changes one only to bind `remoteIdentities[parent]`,
+ * the caller-verified native install receipt, onto an enrolled control stored
+ * without it (codexStoredReceiptHeal). A name under an enrolled plugin parent
+ * takes that parent's reviewed identity, and the native review must report the
+ * same capability tuple for it; it never drops a receipt the review verified.
+ * A name under a plugin Skills has not enrolled is admitted only for a
+ * skills-only plugin, and binds `remoteIdentities[parent]` when it is remote. */
+export declare function mergeReconciledCodexPluginControls(prior: CodexPluginSkillControl[], reviewed: CodexPluginSkillControl[], names: string[], remoteIdentities?: Record<string, string>): CodexPluginSkillControl[];
 export declare function disableReviewedCodexPluginNames(text: string, controls: CodexPluginSkillControl[]): string;
 export {};

package/dist/lib/remote-client.d.ts

@@ -11,6 +11,7 @@ import { type RemoteCreditCheckout, type RemoteCreditCheckoutOptions, type Remot
 import { type UpdateRemoteProfile, type UpdateRemoteWorkspace } from "./remote-profile.js";
 import { type RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
 import { type RemoteSkillsAccess } from "./remote-permissions.js";
+import { type SkillMetadataPatch, type SkillMetadataUpdatePlan } from "./skill-metadata-update.js";
 export type { RemoteQuoteUnavailableCode } from "./remote-quote-errors.js";
 /**
  * A server that predates this client's pin/tag/incremental-sync routes answered
@@ -123,6 +124,15 @@ export declare class RemoteSkillsClient {
     listSkills(): Promise<any[]>;
     getSkillMd(slug: string): Promise<string | null>;
     getSkill(slug: string): Promise<any | null>;
+    private metadataOrganization;
+    private readMetadataSnapshot;
+    /** Read-only preview. Save this complete private original before applying it. */
+    prepareSkillMetadataUpdate(slug: string, patch: SkillMetadataPatch): Promise<SkillMetadataUpdatePlan>;
+    /** One guarded PATCH; an uncertain response is reconciled by readback, never retried. */
+    applySkillMetadataUpdate(input: SkillMetadataUpdatePlan): Promise<{
+        status: "applied" | "reconciled" | "unchanged";
+        revisionId: string;
+    }>;
     /**
      * Raw GET for one skill, with the HTTP status surfaced. Used by the reconcile
      * re-check (registry-reconcile.ts) so it can distinguish "no such skill" (404) from

package/dist/lib/skill-metadata-update.d.ts

@@ -0,0 +1,46 @@
+import { type RevisionContent } from "./revision.js";
+export interface SkillMetadataPatch {
+    category?: string;
+    tags?: string[];
+}
+/** Private preservation snapshot: includes the original instruction body. */
+export interface SkillMetadataUpdatePlan {
+    schemaVersion: 1;
+    authority: string;
+    organizationId: string;
+    expectedRevisionId: string;
+    originalDocument: string;
+    before: RevisionContent;
+    patch: SkillMetadataPatch;
+}
+export declare class SkillMetadataUpdateError extends Error {
+    readonly code: "METADATA_AUTH_REQUIRED" | "INVALID_METADATA_PATCH" | "INVALID_METADATA_SNAPSHOT" | "INVALID_METADATA_PLAN" | "METADATA_REVISION_CONFLICT" | "METADATA_UPDATE_UNCONFIRMED";
+    constructor(code: "METADATA_AUTH_REQUIRED" | "INVALID_METADATA_PATCH" | "INVALID_METADATA_SNAPSHOT" | "INVALID_METADATA_PLAN" | "METADATA_REVISION_CONFLICT" | "METADATA_UPDATE_UNCONFIRMED");
+}
+/** Read category and tags once into a plain copy, then validate and return only that copy. */
+export declare function metadataPatch(value: unknown): SkillMetadataPatch;
+/** Normalize exactly the owning registry's revision fields, never arbitrary extras. */
+export declare function metadataSnapshot(value: unknown, etag: string | null): {
+    content: RevisionContent;
+    revisionId: string;
+};
+export declare function metadataPlan(value: unknown): SkillMetadataUpdatePlan;
+export declare function metadataPlanSummary(plan: SkillMetadataUpdatePlan): {
+    slug: string;
+    authority: string;
+    organizationId: string;
+    expectedRevisionId: string;
+    before: {
+        category: string;
+        tags: string[];
+    };
+    after: {
+        category: string;
+        tags: string[];
+    };
+    preserved: {
+        version: string | undefined;
+        bundleSha256: string | undefined;
+        instructionBody: string;
+    };
+};

package/dist/lib/skill-validation.d.ts

@@ -49,5 +49,7 @@ export interface SkillValidationProvenance {
     packageSkillSource?: string;
 }
 export declare function parseSkillFrontmatter(content: string): SkillFrontmatter | null;
-export declare function validateSkillDirectory(name: string, skillPath: string, registryMeta?: SkillMeta): SkillValidationResult;
+export declare function validateSkillDirectory(name: string, skillPath: string, registryMeta?: SkillMeta, options?: {
+    kind?: SkillKind;
+}): SkillValidationResult;
 export declare function validateRegistryConsistency(registry: SkillMeta[], skillsDir: string): RegistryConsistencyResult;

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.80";
+var version = "0.10.81";
 var package_default = {
   name: "@hasna/skills",
   version,

package/dist/sdk/index.d.ts

@@ -39,6 +39,7 @@ export * from "./spend.js";
 export * from "./offline.js";
 export * from "./execution/index.js";
 export { RemoteSkillsClient, createRemoteSkillsClient, RemoteRequestError, RemoteCreditCheckoutError, RemoteRouteUnsupportedError, RemoteCapabilityUnavailableError, RemoteQuoteUnavailableError, RemoteWorkspaceMemberError } from "../lib/remote-client.js";
+export { SkillMetadataUpdateError, metadataPlanSummary, type SkillMetadataPatch, type SkillMetadataUpdatePlan } from "../lib/skill-metadata-update.js";
 export { RemoteSkillsPermissionError, type RemoteSkillsAccess, type RemoteSkillsPermissions } from "../lib/remote-permissions.js";
 export * from "../lib/remote-recurring-contract.js";
 export { RecurringInputError, RemoteRecurringError, RemoteRecurringUnavailableError, RemoteRecurringReadError, RemoteRecurringUnconfirmedError } from "../lib/remote-recurring.js";