@hasna/skills 0.1.71 → 0.2.0

package/dist/server/app.d.ts

@@ -1,8 +1,11 @@
 import { type GovernanceStore } from "../sdk/governance-store.js";
+import { ArtifactStorage } from "./artifact-storage.js";
 import { type SkillsServerConfig } from "./config.js";
 import { type MemorySkillsStore } from "./store.js";
 import { type SkillsProductStore } from "./types.js";
 export interface SkillsServerOptions {
+    /** Overrides the artifact storage (tests inject an in-memory S3 stand-in). */
+    artifactStorage?: ArtifactStorage;
     config?: Partial<SkillsServerConfig>;
     store?: SkillsProductStore;
     /** Lifecycle ledger and ceiling reads for governance surfaces (cancellation). Defaults to the store's database. */

package/dist/server/artifact-storage.d.ts

@@ -1,3 +1,4 @@
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 import { type OwnedBytes } from "../lib/skill-bundle.js";
 import type { BlobStorageKind, ServerArtifact, ServerRunRecord, ServerSkillBundle } from "./types.js";
 export interface ArtifactBody {
@@ -5,10 +6,18 @@ export interface ArtifactBody {
     bodyText: string;
     contentType: string;
 }
+/** The slice of the AWS client the storage uses; injectable so tests can stand in an in-memory bucket. */
+export interface S3ClientLike {
+    send(command: PutObjectCommand | GetObjectCommand | DeleteObjectCommand): Promise<{
+        Body?: unknown;
+    }>;
+}
 export interface ArtifactStorageOptions {
     bucket?: string;
     prefix?: string;
     region?: string;
+    /** Overrides the real S3 client (tests). Ignored when no bucket is configured. */
+    client?: S3ClientLike;
 }
 export declare class ArtifactStorage {
     private bucket?;
@@ -98,5 +107,23 @@ export declare class ArtifactStorage {
      */
     moveToQuarantine(artifact: ServerArtifact): Promise<string | null>;
     private keyFor;
+    /**
+     * Version-addressed copy of a published bundle plus its manifest (hasna/apps#1630):
+     *   <prefix>/skills/<org>/<slug>/<version>/bundle.tar.gz
+     *   <prefix>/skills/<org>/<slug>/<version>/manifest.json
+     * The content-addressed object under bundles/ stays the read path (dedupe); these keys
+     * are the durable, browsable history and are never deleted by orphan collection.
+     * Returns the placement recorded on the version row; in db mode nothing is written.
+     */
+    putVersionObjects(orgId: string, slug: string, version: string, bytes: OwnedBytes, manifest: Record<string, unknown>, contentType?: string): Promise<{
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+    }>;
+    /** Where putVersionObjects WOULD place a version, without writing: recorded on the row before the objects exist. */
+    versionPlacement(orgId: string, slug: string, version: string): {
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+    };
+    versionKeyFor(orgId: string, slug: string, version: string, file: string): string;
     private bundleKeyFor;
 }

package/dist/server/config.d.ts

@@ -3,6 +3,8 @@ export interface SkillsServerConfig {
     port: number;
     databaseUrl?: string;
     bootstrapApiKey?: string;
+    /** Publish the bundled corpus as versioned skills on boot (default on; set HASNA_SKILLS_SEED_BUNDLED_CORPUS=0 to skip). */
+    seedBundledCorpus: boolean;
     artifactBucket?: string;
     artifactPrefix: string;
     inlineWorker: boolean;

package/dist/server/rows.d.ts

@@ -1,4 +1,4 @@
-import type { ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord } from "./types.js";
+import type { ServerSkillVersion, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord } from "./types.js";
 export declare function nowIso(): string;
 /**
  * Coerce a caller-supplied row limit to a non-negative integer.
@@ -22,3 +22,4 @@ export declare function rowToSkillBundle(row: Record<string, unknown>): ServerSk
 export declare function parseJsonObject(value: unknown): Record<string, unknown>;
 export declare function parseJsonArray(value: unknown): string[];
 export declare function dateString(value: unknown): string;
+export declare function rowToSkillVersion(row: Record<string, unknown>): ServerSkillVersion;

package/dist/server/seed-bundled.d.ts

@@ -0,0 +1,20 @@
+import type { ArtifactStorage } from "./artifact-storage.js";
+import type { ApiPrincipal, SkillsProductStore } from "./types.js";
+export interface SeedBundledCorpusOptions {
+    store: SkillsProductStore;
+    artifactStorage: ArtifactStorage;
+    principal: ApiPrincipal;
+    /** Version recorded for every seeded skill. Defaults to the package version. */
+    version?: string;
+    log?: (line: string) => void;
+}
+export interface SeedBundledCorpusResult {
+    version: string;
+    seeded: string[];
+    skipped: string[];
+    failed: Array<{
+        slug: string;
+        error: string;
+    }>;
+}
+export declare function seedBundledCorpus(options: SeedBundledCorpusOptions): Promise<SeedBundledCorpusResult>;

package/dist/server/skills-api.d.ts

@@ -2,7 +2,7 @@ import { type OwnedBytes } from "../lib/skill-bundle.js";
 import type { SkillMeta } from "../lib/registry-types.js";
 import type { ArtifactStorage } from "./artifact-storage.js";
 import type { SkillsServerConfig } from "./config.js";
-import { type ApiPrincipal, type PublishSkillInput, type ServerPin, type ServerSkillRecord, type SkillsProductStore } from "./types.js";
+import { type ApiPrincipal, type PublishSkillInput, type ServerPin, type ServerSkillRecord, type ServerSkillVersion, type SkillsProductStore } from "./types.js";
 /** Wire shape of a pin: the client-facing facts, without the storage columns. */
 export declare function pinPayload(pin: ServerPin): Record<string, unknown>;
 /**
@@ -167,4 +167,21 @@ export declare function readPublishedBundle(store: SkillsProductStore, artifactS
 }>;
 export declare function assertPublishableSlug(slug: string): void;
 export declare function assertSha256(value: string): void;
+/**
+ * Versions surface (hasna/apps#1630).
+ *
+ * GET /api/v1/skills/:slug/versions           -> { slug, current, versions: [...] }
+ * GET /api/v1/skills/:slug/versions/:version  -> one version's manifest
+ * GET /api/v1/skills/:slug/versions/:version/bundle -> the exact bytes of that version
+ *
+ * The registry row is the "current" pointer; a version's bytes come from the
+ * content-addressed bundle store so db-mode instances serve history exactly like S3 ones.
+ */
+export declare function skillVersionPayload(version: ServerSkillVersion, currentSha?: string): Record<string, unknown>;
+export declare function listSkillVersionsPayload(store: SkillsProductStore, principal: ApiPrincipal, slug: string): Promise<Record<string, unknown>>;
+export declare function readSkillVersion(store: SkillsProductStore, principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion>;
+export declare function readSkillVersionBundle(store: SkillsProductStore, artifactStorage: ArtifactStorage, principal: ApiPrincipal, slug: string, version: string): Promise<{
+    version: ServerSkillVersion;
+    bytes: OwnedBytes;
+}>;
 export {};

package/dist/server/sqlite-store.d.ts

@@ -13,7 +13,7 @@
  * requirement; changing Postgres behaviour is not this module's job.
  */
 import { Database } from "bun:sqlite";
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillVersion, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 export interface SqliteStoreOptions {
     /** Apply pending migrations on open. Default true - it is what makes zero-config work. */
     migrate?: boolean;
@@ -102,6 +102,8 @@ export declare class SqliteSkillsStore implements SkillsProductStore {
     deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
     purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
     unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
     listPins(principal: ApiPrincipal): Promise<ServerPin[]>;

package/dist/server/store.d.ts

@@ -1,4 +1,4 @@
-import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
+import type { ApiPrincipal, ClaimRunInput, CreateRunInput, PublishSkillInput, RunTransitionPatch, ServerArtifact, ServerPin, ServerRunLog, ServerRunRecord, ServerSkillBundle, ServerSkillRecord, ServerSkillVersion, SkillsProductStore, StoreBackendInfo, UpdateSkillPatch } from "./types.js";
 import { type SqliteStoreOptions } from "./sqlite-store.js";
 export declare function createArtifactId(): string;
 export interface StoreOptions {
@@ -31,6 +31,7 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     private idempotency;
     private skills;
     private bundles;
+    private versions;
     private pins;
     constructor(apiKeys?: Array<{
         token: string;
@@ -67,6 +68,8 @@ export declare class MemorySkillsStore implements SkillsProductStore {
     listArtifacts(principal: ApiPrincipal, runId: string): Promise<ServerArtifact[]>;
     getArtifact(principal: ApiPrincipal, runId: string, id: string): Promise<ServerArtifact | null>;
     publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
     updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch, expectedRevisionId?: string): Promise<ServerSkillRecord | null>;
@@ -158,6 +161,8 @@ export declare class PostgresSkillsStore implements SkillsProductStore {
     deleteSkill(principal: ApiPrincipal, slug: string, tombstoneWindowMs: number): Promise<ServerSkillRecord | null>;
     purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
     unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
     listPins(principal: ApiPrincipal): Promise<ServerPin[]>;

package/dist/server/types.d.ts

@@ -31,6 +31,18 @@ export declare class SkillRevisionConflictError extends Error {
     readonly currentRevisionId: string | null;
     constructor(slug: string, expectedRevisionId: string | null | undefined, currentRevisionId: string | null);
 }
+/**
+ * A publish was refused because (org, slug, version) already exists with a DIFFERENT bundle
+ * digest. Versions are immutable (hasna/apps#1630): the same digest is idempotent, a new
+ * digest needs a new version. Carries the stored digest so the client can say which.
+ */
+export declare class SkillVersionExistsError extends Error {
+    readonly slug: string;
+    readonly version: string;
+    readonly existingSha256: string;
+    readonly attemptedSha256: string;
+    constructor(slug: string, version: string, existingSha256: string, attemptedSha256: string);
+}
 export interface ApiPrincipal {
     apiKeyId: string;
     orgId: string;
@@ -182,6 +194,24 @@ export interface ServerSkillBundle {
     bytes?: OwnedBytes;
     createdAt: string;
 }
+/**
+ * One immutable published version of a skill (hasna/apps#1630). The registry row is the
+ * mutable "current" pointer; these rows are the history: each (org, slug, version) exactly once,
+ * pointing at a content-addressed bundle that orphan collection must keep alive.
+ */
+export interface ServerSkillVersion {
+    orgId: string;
+    slug: string;
+    version: string;
+    bundleSha256: string;
+    bundleByteSize: number;
+    storageKind: BlobStorageKind;
+    storageKey?: string;
+    /** Files (path -> sha256), byte counts and provenance the publisher sent; never secret. */
+    manifest: Record<string, unknown>;
+    publishedByUserId?: string;
+    createdAt: string;
+}
 export interface PublishSkillInput {
     principal: ApiPrincipal;
     slug: string;
@@ -195,6 +225,16 @@ export interface PublishSkillInput {
     skillMd?: string;
     /** Omitted for a metadata-only publish or update. */
     bundle?: Omit<ServerSkillBundle, "orgId" | "createdAt">;
+    /**
+     * Publisher-supplied version manifest (file digests, provenance). Stored verbatim on the
+     * version row when `version` is set; ignored otherwise.
+     */
+    versionManifest?: Record<string, unknown>;
+    /** Version-addressed object key the API wrote (S3 mode); recorded on the version row. */
+    versionStorage?: {
+        storageKind: BlobStorageKind;
+        storageKey?: string;
+    };
     /**
      * Optimistic-concurrency guard (todos d061fcda): the revision_id (ETag) the writer
      * read. A publish against an existing, LIVE row requires the guard to name that row's
@@ -320,6 +360,9 @@ export interface SkillsProductStore {
      */
     purgeExpiredTombstones(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
     getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+    /** Every published version of a slug, newest first (hasna/apps#1630). */
+    listSkillVersions(principal: ApiPrincipal, slug: string): Promise<ServerSkillVersion[]>;
+    getSkillVersion(principal: ApiPrincipal, slug: string, version: string): Promise<ServerSkillVersion | null>;
     pinSkill(principal: ApiPrincipal, slug: string, metadata?: Record<string, unknown>): Promise<ServerPin>;
     /** False when this principal has no pin by that slug. */
     unpinSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;

package/dist/storage.js

@@ -49,19 +49,18 @@ var __require = import.meta.require;
 // src/lib/native-storage.ts
 import { createHash, createHmac } from "crypto";
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync3,
   readdirSync as readdirSync2,
   statSync as statSync2,
   writeFileSync as writeFileSync3
 } from "fs";
-import { dirname as dirname2, join as join3, normalize, relative, sep } from "path";
+import { dirname as dirname2, join as join4, normalize, relative, sep } from "path";
 
 // src/lib/config.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "fs";
-import { join, dirname } from "path";
-import { homedir } from "os";
+import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "fs";
+import { join as join2, dirname } from "path";
 
 // src/lib/retired-settings.ts
 var RETIRED_ENV_SUFFIXES = ["_STORAGE_MODE", "_DEPLOYMENT_MODE", "_CLOUD_MODE"];
@@ -109,6 +108,124 @@ function assertNoRetiredConfigKeys(config, source) {
   }
 }
 
+// src/lib/app-home.ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { homedir as pathsResolverHomedir } from "os";
+import { join as pathsResolverJoin } from "path";
+var PATHS_RESOLVER_KIND_ENV = {
+  config: "HASNA_CONFIG_HOME",
+  data: "HASNA_DATA_HOME",
+  state: "HASNA_STATE_HOME",
+  cache: "HASNA_CACHE_HOME"
+};
+var PATHS_RESOLVER_APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function pathsResolverAssertApp(app) {
+  if (typeof app !== "string" || app.length === 0) {
+    throw new TypeError("paths: app must be a non-empty string");
+  }
+  if (!PATHS_RESOLVER_APP_SLUG_RE.test(app)) {
+    throw new TypeError(`paths: invalid app slug "${app}" \u2014 expected lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)`);
+  }
+}
+function pathsResolverAssertKind(kind) {
+  if (!Object.keys(PATHS_RESOLVER_KIND_ENV).includes(kind)) {
+    throw new TypeError(`paths: invalid path kind "${kind}" \u2014 expected one of ${Object.keys(PATHS_RESOLVER_KIND_ENV).join(", ")}`);
+  }
+}
+function pathsResolverBaseDir(kind, options) {
+  pathsResolverAssertKind(kind);
+  const env = options.env ?? process.env;
+  const override = env[PATHS_RESOLVER_KIND_ENV[kind]];
+  if (typeof override === "string" && override.length > 0)
+    return override;
+  const home = options.home ?? pathsResolverHomedir();
+  const platform = options.platform ?? process.platform;
+  if (platform === "darwin") {
+    switch (kind) {
+      case "config":
+      case "data":
+        return pathsResolverJoin(home, "Library", "Application Support", "Hasna");
+      case "cache":
+        return pathsResolverJoin(home, "Library", "Caches", "Hasna");
+      case "state":
+        return pathsResolverJoin(home, "Library", "Logs", "Hasna");
+    }
+  }
+  switch (kind) {
+    case "config":
+      return pathsResolverJoin(home, ".config", "hasna");
+    case "data":
+      return pathsResolverJoin(home, ".local", "share", "hasna");
+    case "state":
+      return pathsResolverJoin(home, ".local", "state", "hasna");
+    case "cache":
+      return pathsResolverJoin(home, ".cache", "hasna");
+  }
+}
+function pathsResolverResolve(kind, options) {
+  pathsResolverAssertApp(options.app);
+  const appSegment = options.internal === true ? pathsResolverJoin("internal", options.app) : options.app;
+  return pathsResolverJoin(pathsResolverBaseDir(kind, options), appSegment);
+}
+function dataDir(options) {
+  return pathsResolverResolve("data", options);
+}
+var DATA_DIR_ENV = "HASNA_SKILLS_DIR";
+var HASNA_SKILLS_HOME_ENV = "HASNA_SKILLS_HOME";
+var SKILLS_HOME_ENV = "SKILLS_HOME";
+var DEFAULT_SQLITE_FILENAME = "server.db";
+var GLOBAL_CONFIG_FILENAME = "config.json";
+function effectiveHome() {
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir() || "/tmp";
+}
+function legacyDataRoot() {
+  return join(effectiveHome(), ".hasna", "skills");
+}
+function resolverDataRoot(home = effectiveHome(), env) {
+  return dataDir({ app: "skills", home, env });
+}
+function adoptResolverDataRoot(resolved, env = process.env) {
+  const dataOverride = env.HASNA_DATA_HOME;
+  if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
+    return true;
+  return existsSync(join(resolved, DEFAULT_SQLITE_FILENAME)) || existsSync(join(resolved, GLOBAL_CONFIG_FILENAME));
+}
+function exactDataRoot() {
+  for (const key of [DATA_DIR_ENV, HASNA_SKILLS_HOME_ENV, SKILLS_HOME_ENV]) {
+    const dir = process.env[key]?.trim();
+    if (dir)
+      return resolve(dir);
+  }
+  return;
+}
+function hasExactOverride(env = process.env) {
+  return Boolean(env[DATA_DIR_ENV]?.trim()) || Boolean(env[HASNA_SKILLS_HOME_ENV]?.trim()) || Boolean(env[SKILLS_HOME_ENV]?.trim());
+}
+function hasOperatorOverride(env = process.env) {
+  return hasExactOverride(env) || Boolean(env.HASNA_DATA_HOME?.trim());
+}
+function getDataRoot() {
+  const exact = exactDataRoot();
+  if (exact)
+    return exact;
+  const resolved = resolverDataRoot();
+  return adoptResolverDataRoot(resolved) ? resolve(resolved) : resolve(legacyDataRoot());
+}
+function skillsDataRootForHome(home) {
+  const isOwnHome = resolve(home) === resolve(effectiveHome()) || resolve(home) === resolve(homedir());
+  if (isOwnHome) {
+    const exact = exactDataRoot();
+    if (exact)
+      return exact;
+    const resolved2 = resolverDataRoot(home);
+    return adoptResolverDataRoot(resolved2) ? resolve(resolved2) : resolve(join(home, ".hasna", "skills"));
+  }
+  const resolved = resolverDataRoot(home, {});
+  return adoptResolverDataRoot(resolved, {}) ? resolve(resolved) : resolve(join(home, ".hasna", "skills"));
+}
+
 // src/lib/config.ts
 var ENUM_KEYS = {
   defaultAgent: ["claude", "codex", "gemini", "pi", "opencode", "all"],
@@ -123,19 +240,19 @@ function allowedValues(key) {
   return ENUM_KEYS[key];
 }
 function mergeDirectoryContents(sourceDir, targetDir) {
-  if (!existsSync(sourceDir))
+  if (!existsSync2(sourceDir))
     return;
   mkdirSync(targetDir, { recursive: true });
   for (const entry of readdirSync(sourceDir)) {
-    const sourcePath = join(sourceDir, entry);
-    const targetPath = join(targetDir, entry);
+    const sourcePath = join2(sourceDir, entry);
+    const targetPath = join2(targetDir, entry);
     try {
       const sourceStat = statSync(sourcePath);
       if (sourceStat.isDirectory()) {
         mergeDirectoryContents(sourcePath, targetPath);
         continue;
       }
-      if (!existsSync(targetPath))
+      if (!existsSync2(targetPath))
         copyFileSync(sourcePath, targetPath);
     } catch {}
   }
@@ -160,44 +277,40 @@ function normalizeConfigValue(key, value) {
     return value.trim() ? value : undefined;
   return;
 }
-var DATA_DIR_ENV = "HASNA_SKILLS_DIR";
 var INSTALLED_SKILLS_DIRNAME = "installed";
 var SKILLS_CACHE_DIRNAME = "skills";
 var LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
 function isOwnerLayoutMigrated(appDir) {
-  return existsSync(join(appDir, SKILLS_CACHE_DIRNAME, LAYOUT_MIGRATION_RECORD));
+  return existsSync2(join2(appDir, SKILLS_CACHE_DIRNAME, LAYOUT_MIGRATION_RECORD));
 }
 function getDataDir() {
-  const override = process.env[DATA_DIR_ENV];
-  if (override) {
-    try {
-      mkdirSync(override, { recursive: true });
-    } catch {}
-    return override;
-  }
-  const home = process.env["HOME"] || process.env["USERPROFILE"] || homedir();
-  const newDir = join(home, ".hasna", "skills");
-  const oldDir = join(home, ".skills");
-  const oldConfigFile = join(home, ".skillsrc");
-  mkdirSync(newDir, { recursive: true });
+  const root = getDataRoot();
   try {
-    mergeDirectoryContents(oldDir, newDir);
+    mkdirSync(root, { recursive: true });
   } catch {}
-  if (existsSync(oldConfigFile) && !existsSync(join(newDir, "config.json"))) {
+  if (hasOperatorOverride())
+    return root;
+  const home = effectiveHome();
+  const oldDir = join2(home, ".skills");
+  const oldConfigFile = join2(home, ".skillsrc");
+  try {
+    mergeDirectoryContents(oldDir, root);
+  } catch {}
+  if (existsSync2(oldConfigFile) && !existsSync2(join2(root, "config.json"))) {
     try {
-      copyFileSync(oldConfigFile, join(newDir, "config.json"));
+      copyFileSync(oldConfigFile, join2(root, "config.json"));
     } catch {}
   }
-  return newDir;
+  return root;
 }
 function getConfigPath(scope) {
   if (scope === "global") {
-    return join(getDataDir(), "config.json");
+    return join2(getDataDir(), "config.json");
   }
-  return join(process.cwd(), "skills.config.json");
+  return join2(process.cwd(), "skills.config.json");
 }
 function readConfigFile(path) {
-  if (!existsSync(path))
+  if (!existsSync2(path))
     return {};
   let parsed;
   try {
@@ -233,7 +346,7 @@ function saveConfig(key, value, scope = "project") {
   }
   const filePath = getConfigPath(scope);
   let existing = {};
-  if (existsSync(filePath)) {
+  if (existsSync2(filePath)) {
     try {
       existing = JSON.parse(readFileSync(filePath, "utf-8"));
       if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
@@ -244,7 +357,7 @@ function saveConfig(key, value, scope = "project") {
     }
   } else {
     const dir = dirname(filePath);
-    if (!existsSync(dir)) {
+    if (!existsSync2(dir)) {
       mkdirSync(dir, { recursive: true });
     }
   }
@@ -258,7 +371,7 @@ function unsetConfig(key, scope = "project") {
     throw new Error(`Unknown config key: ${key}. Valid keys: ${validKeys().join(", ")}`);
   }
   const filePath = getConfigPath(scope);
-  if (!existsSync(filePath))
+  if (!existsSync2(filePath))
     return false;
   let existing;
   try {
@@ -278,8 +391,8 @@ function unsetConfig(key, scope = "project") {
 }
 
 // src/lib/project-state.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
 
 // src/lib/utils.ts
 function normalizeSkillName(name) {
@@ -301,14 +414,14 @@ var SKILLS_PROJECT_DIR = ".skills";
 var PROJECT_CONFIG_FILE = "project.json";
 var DEFAULT_EXPORT_DIR = ".skills/exports";
 function getProjectStateDir(targetDir = process.cwd()) {
-  return join2(targetDir, SKILLS_PROJECT_DIR);
+  return join3(targetDir, SKILLS_PROJECT_DIR);
 }
 function getProjectConfigPath(targetDir = process.cwd()) {
-  return join2(getProjectStateDir(targetDir), PROJECT_CONFIG_FILE);
+  return join3(getProjectStateDir(targetDir), PROJECT_CONFIG_FILE);
 }
 function loadProjectConfig(targetDir = process.cwd()) {
   const path = getProjectConfigPath(targetDir);
-  if (!existsSync2(path))
+  if (!existsSync3(path))
     return null;
   try {
     return normalizeProjectConfig(JSON.parse(readFileSync2(path, "utf-8")));
@@ -561,7 +674,7 @@ function getSkillsNativeStorageStatus(options = {}) {
     local: {
       dataDir: getDataDir(),
       projectStateDir: getProjectStateDir(targetDir),
-      feedbackDbPath: join3(getDataDir(), "skills.db")
+      feedbackDbPath: join4(getDataDir(), "skills.db")
     },
     remote: {
       databaseConfigured: Boolean(config.databaseUrl),
@@ -584,7 +697,7 @@ function getStorageStatus(options = {}) {
 function exportSkillsLocalSnapshot(targetDir = process.cwd(), options = {}) {
   const projectStateDir = getProjectStateDir(targetDir);
   const files = [];
-  if (existsSync3(projectStateDir)) {
+  if (existsSync4(projectStateDir)) {
     for (const filePath of walkFiles(projectStateDir)) {
       const bytes = readFileSync3(filePath);
       const relativePath = toPosix(relative(targetDir, filePath));
@@ -611,7 +724,7 @@ function importSkillsLocalSnapshot(snapshot, targetDir = process.cwd(), options
       continue;
     }
     const absolutePath = resolveSnapshotPath(targetDir, file.path);
-    if (existsSync3(absolutePath) && !options.overwrite) {
+    if (existsSync4(absolutePath) && !options.overwrite) {
       skipped += 1;
       continue;
     }
@@ -918,7 +1031,7 @@ function parsePositiveInteger(value) {
 function walkFiles(dir) {
   const files = [];
   for (const entry of readdirSync2(dir)) {
-    const full = join3(dir, entry);
+    const full = join4(dir, entry);
     const stats = statSync2(full);
     if (stats.isDirectory())
       files.push(...walkFiles(full));
@@ -935,7 +1048,7 @@ function resolveSnapshotPath(targetDir, snapshotPath) {
   if (!toPosix(normalizedPath).startsWith(".skills/")) {
     throw new Error(`Snapshot path must stay inside .skills: ${snapshotPath}`);
   }
-  return join3(targetDir, normalizedPath);
+  return join4(targetDir, normalizedPath);
 }
 function normalizeS3Prefix(prefix) {
   return (prefix ?? "").trim().replace(/^\/+|\/+$/g, "");

package/migrations/postgres/0006_skill_versions.sql

@@ -0,0 +1,30 @@
+-- Immutable skill versions (hasna/apps#1630).
+--
+-- skills_registry keeps ONE row per (org, slug): the current revision. Every re-publish
+-- replaced it and purged the previous bundle, so there was no history. This table records
+-- each published name@version once: the content-addressed bundle it points at, the file
+-- manifest and provenance the client sent, and where the version-addressed copy lives.
+--
+-- Rows are never updated. A publish of an existing (org, slug, version) with a different
+-- bundle digest is refused (409 SKILL_VERSION_EXISTS); the same digest is idempotent.
+-- bundle_sha256 references skills_bundles(org_id, sha256) softly, like skills_registry
+-- does; orphan collection must consult this table so a version's bundle outlives the
+-- registry row that first published it.
+CREATE TABLE IF NOT EXISTS skills_versions (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  slug text NOT NULL,
+  version text NOT NULL,
+  bundle_sha256 text NOT NULL,
+  bundle_byte_size integer NOT NULL,
+  -- 'db' when the bytes live in skills_bundles.body_blob, 's3' when a version-addressed
+  -- object (<prefix>/skills/<org>/<slug>/<version>/bundle.tar.gz) was written.
+  storage_kind text NOT NULL DEFAULT 'db',
+  storage_key text,
+  manifest_json jsonb NOT NULL DEFAULT '{}'::jsonb,
+  published_by_user_id text REFERENCES users(id) ON DELETE SET NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (org_id, slug, version)
+);
+
+CREATE INDEX IF NOT EXISTS skills_versions_org_slug_created_idx ON skills_versions (org_id, slug, created_at DESC);
+CREATE INDEX IF NOT EXISTS skills_versions_bundle_idx ON skills_versions (org_id, bundle_sha256);

package/migrations/sqlite/0006_skill_versions.sql

@@ -0,0 +1,17 @@
+-- Immutable skill versions (hasna/apps#1630). SQLite twin of migrations/postgres/0006.
+CREATE TABLE IF NOT EXISTS skills_versions (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  slug text NOT NULL,
+  version text NOT NULL,
+  bundle_sha256 text NOT NULL,
+  bundle_byte_size integer NOT NULL,
+  storage_kind text NOT NULL DEFAULT 'db',
+  storage_key text,
+  manifest_json text NOT NULL DEFAULT '{}',
+  published_by_user_id text REFERENCES users(id) ON DELETE SET NULL,
+  created_at text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (org_id, slug, version)
+);
+
+CREATE INDEX IF NOT EXISTS skills_versions_org_slug_created_idx ON skills_versions (org_id, slug, created_at DESC);
+CREATE INDEX IF NOT EXISTS skills_versions_bundle_idx ON skills_versions (org_id, bundle_sha256);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.71",
+  "version": "0.2.0",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -80,7 +80,7 @@
   "author": "Hasna",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "1.3.14",
     "@types/node": "25.2.3",
     "@types/react": "^18.2.0",
     "bun-types": "1.3.14",