@hasna/skills 0.1.62 → 0.1.64

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

@@ -1,7 +1,9 @@
 /**
  * `skills sync` — the last mile: write skills from this machine's corpus
- * (~/.hasna/skills/installed/<name>/) into each coding agent's global skills directory,
- * per-tool adapted, so an agent auto-loads them.
+ * (the migrated owner-layout cache ~/.hasna/skills/skills/<name>/, or the
+ * legacy ~/.hasna/skills/installed/<name>/ when not migrated) into each coding
+ * agent's global skills directory, per-tool adapted, so an agent auto-loads
+ * them.
  *
  * This is the deliberate reversal of the old "pins, not installs" stub: agent skill
  * folders used to be left entirely unmanaged and every write path returned success:false.
@@ -18,6 +20,14 @@ import { renameSync } from "node:fs";
  */
 export type SyncAgent = "claude" | "codewith" | "codex" | "opencode" | "cursor";
 export declare const SYNC_AGENTS: readonly SyncAgent[];
+/**
+ * Environment variable naming an explicit canonical-corpus source for sync. The CLI
+ * `--source <path>` flag takes precedence; this is the ambient form, and it means the
+ * same thing: the npm package ships no corpus, so a machine that has not pulled from an
+ * instance (or that is not a checkout of the monorepo) must point sync at where the
+ * corpus actually is.
+ */
+export declare const SKILLS_SOURCE_ENV = "SKILLS_SOURCE";
 /**
  * Ownership marker written beside every SKILL.md this tool syncs. Its presence is how a
  * re-sync tells "a skill I wrote, safe to update" from "a skill the user hand-authored,
@@ -46,6 +56,18 @@ export declare function agentGlobalSkillsDir(agent: SyncAgent, homeDir?: string)
  * would corrupt meaning, and corpus/instruction skills are authored tool-neutral.
  */
 export declare function adaptSkillMdForAgent(skillMd: string, agent: string): string;
+/**
+ * The sentence every sync pointer stub carries in its body. It survives per-agent
+ * adaptation (adaptSkillMdForAgent only touches `user_invocable`), so it is the stable
+ * fingerprint for "this document is a pointer, not the skill's real content".
+ */
+export declare const POINTER_MARKER_PHRASE = "This is an executable skill from the @hasna/skills catalog";
+/**
+ * True when a SKILL.md is a sync pointer stub: frontmatter declares `kind: executable`
+ * AND the body carries the canonical pointer sentence. A full content document is never
+ * a stub even when it mentions the sentence, because it lacks the kind marker.
+ */
+export declare function isPointerSkillMd(markdown: string): boolean;
 /** A pointer SKILL.md for an executable skill: what it is and how to actually run it. */
 export declare function pointerSkillMd(name: string, description: string): string;
 export type SyncActionKind = "create" | "update" | "skip";
@@ -69,18 +91,49 @@ export interface SyncSkillsOptions {
     force?: boolean;
     /** Corpus root override. Tests only. */
     rootDir?: string;
+    /**
+     * Explicit canonical-corpus source: a directory of skill folders, or the monorepo
+     * package root (which contains `skills/`). Takes precedence over
+     * $SKILLS_SOURCE, which takes precedence over the installed corpus cache.
+     * Agent-workflow skills are NOT part of the public repo corpus anymore — they
+     * moved to the private per-station store (hasna-internal/fleet-resources) and
+     * reach sync through the installed cache — so a package root resolves to
+     * `skills/` only.
+     */
+    sourceDir?: string;
     /** Home directory override for agent skill dirs. Tests only. */
     homeDir?: string;
 }
 export interface SyncSkillsResult {
     actions: AgentSyncAction[];
 }
+/**
+ * Resolve where sync reads the canonical corpus from.
+ *
+ * The package ships no bundled corpus. Precedence is explicit-over-ambient:
+ *   1. `options.sourceDir`   - an explicit source: a corpus dir, or a package root
+ *                              containing `skills/`
+ *   2. `$SKILLS_SOURCE`      - the ambient spelling of the same thing
+ *   3. the installed cache   - `getPortableSkillsRoot()` (what `skills pull` writes),
+ *      resolved through `resolveCorpusRoot` so a migrated owner layout
+ *      (~/.hasna/skills/skills/) is read in preference to `installed/`. This cache is
+ *      also where private agent-workflow skills arrive from the per-station store
+ *      (hasna-internal/fleet-resources) and get synced into agent folders.
+ *
+ * A missing explicit source is an error, not a fallback to "nothing": the whole point
+ * of zero-corpus is that sync must not silently sync an empty corpus because the
+ * package directory changed shape.
+ */
+export declare function resolveSyncCorpus(options?: SyncSkillsOptions): {
+    roots: string[];
+    source: "source" | "corpus";
+};
 export declare function syncSkillsToAgents(options?: SyncSkillsOptions): SyncSkillsResult;
 export interface WriteManagedAgentSkillParams {
     skill: string;
     agent: SyncAgent;
     skillMd: string;
-    source?: "bundled" | "corpus";
+    source?: "source" | "corpus";
     resourceDir?: string;
     homeDir?: string;
     dryRun?: boolean;
@@ -90,9 +143,11 @@ export interface WriteManagedAgentSkillParams {
  * Write one skill into one agent's global folder, non-clobbering.
  *
  * A directory this tool has written before carries the marker file and is replaced with
- * an exact mirror. A directory with a SKILL.md but no marker is the user's own skill and
- * is skipped unless `force` explicitly adopts it. Any other pre-existing unmarked
- * directory is always left untouched. A fresh directory is created.
+ * an exact mirror — except that a managed home holding full content is never silently
+ * replaced with an executable pointer stub (that would be data loss; it is refused
+ * unless `force` is passed). A directory with a SKILL.md but no marker is the user's
+ * own skill and is skipped unless `force` explicitly adopts it. Any other pre-existing
+ * unmarked directory is always left untouched. A fresh directory is created.
  */
 export declare function writeManagedAgentSkill(params: WriteManagedAgentSkillParams): AgentSyncAction;
 export interface ManagedDirWriteResult {

package/dist/lib/auth-store.d.ts

@@ -1,3 +1,30 @@
+/**
+ * auth.json lives at the skills app root, beside config.json.
+ *
+ * Resolved through getDataDir() so that $HASNA_SKILLS_DIR relocates the
+ * credential file along with the rest of the app's state. It used to be an
+ * import-time constant composed from homedir(), so with the override set the
+ * CLI stored its API key at ~/.hasna/skills/auth.json while config, corpus,
+ * and database all moved — the same override-only-half-works split getDataDir()
+ * documents for its own history.
+ *
+ * The legacy ~/.skills/auth.json stays a $HOME concern, exactly like
+ * getDataDir()'s legacy merge (which is deliberately skipped for an overridden
+ * dir): it is still read as a fallback and removed by clearAuthConfig(), but
+ * never written when the override is set. Like getDataDir(), the home is read
+ * from the environment at call time — os.homedir() caches its answer after the
+ * first call, so a process that re-points $HOME would keep composing the old
+ * path.
+ */
+export declare function getAuthFilePath(): string;
+/**
+ * Write-free credential path resolution for read-only paths (e.g. `sync --dry-run`).
+ *
+ * getAuthFilePath() routes through getDataDir(), which WRITES (mkdirs the app dir,
+ * merges legacy ~/.skills content, copies the legacy config). A dry run must read
+ * the same credential file a real run would without performing any of that.
+ */
+export declare function getAuthFilePathReadOnly(): string;
 /**
  * Stored credentials for a Skills API instance.
  *
@@ -18,6 +45,16 @@ export declare function getAuthConfig(): AuthConfig | null;
 export declare function saveAuthConfig(config: AuthConfig): void;
 export declare function clearAuthConfig(): void;
 export declare function getApiKey(): string | null;
+/**
+ * Write-free credential read for read-only paths (e.g. `sync --dry-run`).
+ *
+ * getAuthConfig() resolves through getAuthFilePath() -> getDataDir(), which
+ * writes. Reads the same files (canonical auth.json, then the legacy ~/.skills
+ * fallback) without creating or migrating anything, and without touching the
+ * write path's module-level cache.
+ */
+export declare function getAuthConfigReadOnly(): AuthConfig | null;
+export declare function getApiKeyReadOnly(): string | null;
 export declare function normalizeSkillsApiOrigin(apiUrl: string): string;
 /**
  * Origin every credential-bearing request is sent to.

package/dist/lib/config.d.ts

@@ -58,12 +58,63 @@ export declare const DATA_DIR_ENV = "HASNA_SKILLS_DIR";
  * `custom` without colliding with anything.
  */
 export declare const INSTALLED_SKILLS_DIRNAME = "installed";
+/**
+ * Subfolder of the data directory holding the migrated corpus cache — the
+ * owner-layout replacement for installed/ after `skills storage migrate`
+ * (~/.hasna/skills/{skills,logs,outputs}).
+ *
+ * The marker file inside it (LAYOUT_MIGRATION_RECORD) is the authority: a
+ * skills/ directory someone created by hand is not the corpus and never will
+ * be treated as one (see isOwnerLayoutMigrated).
+ */
+export declare const SKILLS_CACHE_DIRNAME = "skills";
+/**
+ * Marker file inside the corpus cache proving the owner-layout migration ran;
+ * also its record (see migrateOwnerLayout in home-migration.ts).
+ */
+export declare const LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
+/**
+ * True once the owner layout has been migrated (the record is the authority).
+ *
+ * Lives here — rather than in home-migration.ts — because the canonical corpus
+ * resolver in portable-skills.ts must consult it too, and home-migration.ts
+ * depends on portable-skills.ts; this module sits below both.
+ */
+export declare function isOwnerLayoutMigrated(appDir: string): boolean;
 /**
  * Get the data directory for skills global config/data.
  * Default: ~/.hasna/skills/, overridable with $HASNA_SKILLS_DIR.
  * Auto-migrates from ~/.skills/ and ~/.skillsrc without deleting legacy data.
  */
 export declare function getDataDir(): string;
+/**
+ * Write-free data-dir resolution for read-only paths (e.g. `sync --dry-run`).
+ *
+ * getDataDir() itself writes: it mkdirs the app folder, merges legacy ~/.skills
+ * content and copies the legacy config file. A dry run must resolve the SAME
+ * directory a real run would use without performing any of that — mirror the path
+ * logic only, reading $HASNA_SKILLS_DIR and $HOME exactly the way getDataDir does.
+ */
+export declare function getDataDirReadOnly(): string;
+/**
+ * Get the config file path for a given scope, write-free (see getDataDirReadOnly).
+ */
+export declare function getConfigPathReadOnly(scope: ConfigScope): string;
+/**
+ * Load merged config (project-local overrides global) without the writes
+ * getDataDir() performs on the write path.
+ *
+ * The write path folds the legacy ~/.skillsrc into canonical config.json as part of
+ * getDataDir()'s migration — copied ONLY when canonical config.json is absent, and
+ * the legacy migration is skipped entirely when a data-directory override is active.
+ * This mirrors that FILE-LEVEL precedence, never field-level merging: canonical
+ * config.json, when present, is the whole global config; legacy ~/.skillsrc is read
+ * only in the exact situation the write path would copy it (no canonical file, no
+ * override). Field-level merging would inherit a stale legacy origin beneath a
+ * canonical config that omits apiUrl — and the client sends its stored credential to
+ * whatever origin resolves, so divergence from the write path is credential-bearing.
+ */
+export declare function loadConfigReadOnly(): SkillsConfig;
 /**
  * Get the config file path for a given scope
  */

package/dist/lib/home-adoption.d.ts

@@ -0,0 +1,91 @@
+import { type SyncAgent, type SyncMarker } from "./agent-sync.js";
+import type { PortableSkillOptions } from "./portable-skills.js";
+export declare const CONFLICTS_LEDGER_FILE = "conflicts.json";
+export declare const ROLLBACK_DIRNAME = "rollback";
+export interface HomeSkillEntry {
+    agent: SyncAgent;
+    skill: string;
+    /** The agent home skills directory (e.g. ~/.claude/skills). */
+    home: string;
+    /** The skill's own directory under the agent home. */
+    path: string;
+    hash: string;
+    /** SKILL.md mtime (ISO). */
+    mtime: string;
+}
+export interface HomeConflict extends HomeSkillEntry {
+    canonicalHash: string;
+}
+export interface UnknownHomeSkill extends HomeSkillEntry {
+}
+export interface AdoptionScan {
+    /** Unmarked home dirs whose SKILL.md hash matches the canonical corpus entry. */
+    adoptable: HomeSkillEntry[];
+    /** Unmarked home dirs whose content differs from canonical; never touched. */
+    conflicts: HomeConflict[];
+    /** Unmarked home dirs with no canonical corpus entry; reported and skipped. */
+    unknown: UnknownHomeSkill[];
+    /** Already-marked dirs, counted only. */
+    managed: number;
+}
+export interface AdoptionOptions extends PortableSkillOptions {
+    agents?: SyncAgent[];
+    /** Write markers and the conflicts ledger. Without it, scan only. */
+    apply?: boolean;
+}
+export interface AdoptionResult extends AdoptionScan {
+    applied: boolean;
+    /** Rollback record path, when markers were written. */
+    rollbackFile?: string;
+}
+export interface RollbackMarker {
+    agent: SyncAgent;
+    skill: string;
+    path: string;
+    hash: string;
+    marker: SyncMarker;
+}
+export interface RollbackRecord {
+    version: 1;
+    mode: "adopt" | "prune";
+    timestamp: string;
+    entries: RollbackMarker[];
+}
+export interface PruneCandidate extends RollbackMarker {
+    /** The agent home skills directory. */
+    home: string;
+}
+export interface PruneResult {
+    candidates: PruneCandidate[];
+    pruned: number;
+    dryRun: boolean;
+    rollbackFile?: string;
+}
+/**
+ * Canonical corpus index: skill name -> canonical SKILL.md hash. A skill is
+ * canonical when the corpus cache holds a directory with a SKILL.md.
+ */
+export declare function indexCanonicalCorpus(corpusRoot: string): Map<string, string>;
+/**
+ * Census of unmarked home skill dirs against the canonical corpus. Read-only.
+ */
+export declare function scanUnmarkedHomes(options?: AdoptionOptions): AdoptionScan;
+/**
+ * Write one rollback record listing every marker written (mode "adopt") or
+ * every directory removed (mode "prune"), so both operations are reversible
+ * from a single machine-readable file.
+ */
+export declare function writeRollbackRecord(mode: "adopt" | "prune", entries: RollbackMarker[], appDir?: string): string;
+/**
+ * Adopt unmarked home skills whose content exactly matches the canonical
+ * corpus. Without `apply` this is a pure scan; with `apply` it writes one
+ * marker per exact match, appends diverging dirs to the conflicts ledger, and
+ * records every written marker in a rollback file. Never deletes anything.
+ */
+export declare function adoptUnmarkedHomes(options?: AdoptionOptions): AdoptionResult;
+/**
+ * List (or, with `apply`, remove) marked home skill dirs that have no canonical
+ * corpus entry. Never touches an unmarked directory. Removals are recorded in
+ * the rollback store before they happen.
+ */
+export declare function pruneStrayHomes(options?: AdoptionOptions): PruneResult;

package/dist/lib/home-census.d.ts

@@ -0,0 +1,26 @@
+import { type SyncAgent } from "./agent-sync.js";
+import { type AdoptionOptions } from "./home-adoption.js";
+export type DriftKind = "missing-from-home" | "stray-in-home" | "diverged";
+export interface DriftEntry {
+    agent: SyncAgent;
+    skill: string;
+    kind: DriftKind;
+    path: string;
+    homeHash?: string;
+    canonicalHash?: string;
+    /** True when the home's SKILL.md is a sync pointer stub rather than real content. */
+    homeStub?: boolean;
+    /** True when the canonical corpus entry renders as a pointer stub (executable skill). */
+    canonicalStub?: boolean;
+}
+export interface DriftCensus {
+    entries: DriftEntry[];
+    /** Homes that exist and were checked. */
+    homesChecked: number;
+    /** Unmarked home skill dirs (adoption candidates, not drift). */
+    unmarked: number;
+    /** Marked home skill dirs. */
+    managed: number;
+    clean: boolean;
+}
+export declare function censusHomeDrift(options?: AdoptionOptions): DriftCensus;

package/dist/lib/home-migration.d.ts

@@ -0,0 +1,60 @@
+import { type PortableSkillOptions } from "./portable-skills.js";
+export { LAYOUT_MIGRATION_RECORD, SKILLS_CACHE_DIRNAME, isOwnerLayoutMigrated } from "./config.js";
+export declare const LOGS_DIRNAME = "logs";
+export declare const OUTPUTS_DIRNAME = "outputs";
+export declare const LEGACY_CUSTOM_DIRNAME = "custom";
+export interface LayoutMigrationRecord {
+    version: 1;
+    /** ISO timestamp of the migration. */
+    migratedAt: string;
+    /** The entries moved: "installed" for the old corpus dir, then each legacy flat dir name. */
+    moved: string[];
+    note: string;
+}
+export declare function layoutMigrationRecordPath(appDir: string): string;
+/**
+ * Resolve the corpus the sync/fan-out reads from.
+ *
+ * The precedence lives in ONE place, getPortableSkillsRoot():
+ *   1. options.rootDir — named outright, no suffix (unchanged contract)
+ *   2. migrated owner layout — <app folder>/skills when a migration record exists
+ *   3. the pre-migration corpus — installed/, with the legacy auto-copy migration
+ *
+ * The migration record is required: a skills/ directory someone created by hand
+ * is not the corpus and never will be treated as one.
+ *
+ * This wrapper exists so pull/agent-sync and any future caller can name the
+ * canonical resolver explicitly; delegating keeps a single implementation for
+ * list/search/info/push/sync alike (bug 170b0e9b was exactly the opposite — a
+ * second resolution that read installed/ while this one read skills/).
+ */
+export declare function resolveCorpusRoot(options?: PortableSkillOptions): string;
+export type LayoutMigrationStatus = "already-migrated" | "refused" | "migrated" | "nothing-to-do";
+export interface LayoutMigrationResult {
+    status: LayoutMigrationStatus;
+    /** Why a run refused; absent otherwise. */
+    reason?: string;
+    /** The source entries moved (or that a dry-run would move). */
+    moved: string[];
+    /** Directories created by the run. */
+    created: string[];
+    /** The record written, when a run actually migrated. */
+    record?: LayoutMigrationRecord;
+}
+export interface LayoutMigrationOptions {
+    dryRun?: boolean;
+    /** App-folder override for tests. */
+    homeDir?: string;
+}
+/**
+ * Migrate the owner layout, idempotently.
+ *
+ * - already-migrated: the record exists; nothing happens.
+ * - refused: skills/ exists with content and no record, or a legacy dir would
+ *   collide with an existing skills/<name>; nothing happens.
+ * - migrated: installed/ (when present) and every legacy flat dir moved into
+ *   skills/; logs/ and outputs/ created; the record written.
+ * - nothing-to-do: no installed/ and no legacy dirs; logs/ and outputs/ are
+ *   still created (lazily) unless the run is a dry-run.
+ */
+export declare function migrateOwnerLayout(options?: LayoutMigrationOptions): LayoutMigrationResult;

package/dist/lib/native-storage.d.ts

@@ -94,7 +94,7 @@ export declare function getStorageDatabaseEnv(env?: Record<string, string | unde
 export declare function getSkillsStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
 export declare function getStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
 export interface SkillsNativeStorageStatus {
-    package: "open-skills";
+    package: "skills";
     tables: readonly SkillsStorageTable[];
     env: {
         databaseUrl: string;

package/dist/lib/portable-skills-files.d.ts

@@ -1,5 +1,13 @@
 import type { SkillKind } from "./registry-types.js";
-import { type PortableSkillManifest } from "./portable-skills-types.js";
+import { type PortableSkillManifest, type PortableSkillProvenance, type PortableSkillRuntimeContract } from "./portable-skills-types.js";
+/**
+ * Default runtime contract (hasna.skill.v1). `bun` is the Hasna default
+ * runtime; the sandbox is read-only by default, execution is time-capped at
+ * 900s and does not assume network egress.
+ */
+export declare function defaultRuntimeContract(entrypoint?: string): PortableSkillRuntimeContract;
+/** Provenance defaults; content_hash is filled at write time over the bundle. */
+export declare function defaultProvenance(sourceCommit?: string): PortableSkillProvenance;
 export declare function normalizePortableSkillName(name: string): string;
 export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
 export declare function parseSkillKind(value: string | undefined): SkillKind | undefined;
@@ -11,6 +19,16 @@ export declare function createPortableManifest(name: string, options: {
     description: string;
 }): PortableSkillManifest;
 export declare function writePortableSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
+/**
+ * Write skill.json with the canonical content_hash computed over the current
+ * bundle. Preserves unknown keys already present in an existing skill.json
+ * (merge, never replace) and recomputes the hash whenever content changed.
+ *
+ * The manifest is written hashless FIRST so the canonical bundle covers
+ * skill.json itself; canonicalization strips content_hash, so adding the hash
+ * afterwards does not change the digest.
+ */
+export declare function writeSkillJsonWithHash(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function ensurePortableSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 /**
  * Instruction (prose) skills are consumed by agent renderers/MCP docs, not run
@@ -21,5 +39,7 @@ export declare function ensurePortableSkillFiles(skillPath: string, manifest: Po
 export declare function ensureInstructionSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
 export declare function copySkillDirectory(source: string, destination: string): void;
 export declare function renderSkillJson(manifest: PortableSkillManifest): string;
+/** The skill.json object for a manifest, with contract defaults applied. */
+export declare function renderSkillJsonObject(manifest: PortableSkillManifest): Record<string, unknown>;
 export declare function hasPackageDependencies(pkgPath: string): boolean;
 export declare function displayName(name: string): string;

package/dist/lib/portable-skills-types.d.ts

@@ -2,6 +2,50 @@ import type { SkillKind } from "./registry-types.js";
 export declare const PORTABLE_SKILL_STANDARD = "hasna.skill.v1";
 export declare const PORTABLE_SKILL_SCHEMA = "https://hasna.dev/schemas/skill.v1.json";
 export declare const PORTABLE_SKILL_DEFAULT_VERSION = "0.1.0";
+/** Allowed execution runtimes in the hasna.skill.v1 runtime contract. */
+export declare const SKILL_RUNTIMES: readonly ["bun", "node", "python3"];
+export type SkillRuntimeName = (typeof SKILL_RUNTIMES)[number];
+/** Allowed sandbox modes in the hasna.skill.v1 runtime contract. */
+export declare const SKILL_SANDBOX_MODES: readonly ["readonly-fs", "workspace-write", "full"];
+export type SkillSandboxMode = (typeof SKILL_SANDBOX_MODES)[number];
+/**
+ * Allowlisted system binaries a skill may declare. The allowlist lives here
+ * and in schemas/skill.schema.json; the parity test keeps them in agreement.
+ */
+export declare const SKILL_SYSTEM_DEPS_ALLOWLIST: readonly ["ffmpeg", "ffprobe", "imagemagick", "convert", "curl", "wget", "git", "gh", "jq", "python3", "pip3", "node", "bun", "npm", "rsync", "pdftotext", "tesseract", "7z", "unzip", "zip"];
+export type SkillSystemDep = (typeof SKILL_SYSTEM_DEPS_ALLOWLIST)[number];
+/**
+ * Runtime contract (hasna.skill.v1): how the skill executes and what it may
+ * touch. `env` carries secret REFERENCE names, never values.
+ */
+export interface PortableSkillRuntimeContract {
+    runtime: SkillRuntimeName;
+    /** Optional runtime version constraint, e.g. "22" or ">=3.12". */
+    version?: string;
+    /** Relative entrypoint; defaults to commands[0].entry. */
+    entrypoint?: string;
+    /** Max execution seconds, 1..900, default 900. */
+    timeout?: number;
+    /** Whether execution requires network egress, default false. */
+    needs_network?: boolean;
+    /** Secret reference names (uppercase identifiers), never values. */
+    env?: string[];
+    /** Filesystem access granted to execution, default readonly-fs. */
+    sandbox?: SkillSandboxMode;
+    /** Allowlisted system binaries required at execution time. */
+    system_deps?: SkillSystemDep[];
+    /** Glob patterns of artifacts the skill may produce. */
+    artifacts?: string[];
+}
+/** Provenance and integrity fields. content_hash is self-referencing. */
+export interface PortableSkillProvenance {
+    /** Git SHA of the source revision, or "unknown" for local scaffolds. */
+    source_commit?: string;
+    /** Canonical SHA-256 of the normalized bundle (see skill-hash.ts). */
+    content_hash?: string;
+    /** Pointer to changelog / release notes (relative path or URL). */
+    changelog?: string;
+}
 /**
  * Artifact class of a portable skill.
  * - `executable`: a runnable skill folder (package.json + bin + src entry).
@@ -35,6 +79,8 @@ export interface PortableSkillManifest {
     kind?: SkillKind;
     inputs: PortableSkillInput[];
     commands: PortableSkillCommand[];
+    runtime?: PortableSkillRuntimeContract;
+    provenance?: PortableSkillProvenance;
 }
 export interface PortableSkillSummary {
     name: string;

package/dist/lib/portable-skills.d.ts

@@ -7,11 +7,21 @@ export * from "./portable-skills-types.js";
 /**
  * Resolve the corpus: the directory holding one folder per installed skill.
  *
+ * THIS IS THE ONE CANONICAL CORPUS RESOLUTION. Every local discovery and
+ * publish path — list, search, info, push, pull, sync, registry — reads the
+ * corpus through this function (directly or via resolveCorpusRoot(), which
+ * delegates here), so a migrated owner layout is never bypassed by a path that
+ * still resolves installed/ (bug 170b0e9b: 'skills list --all' returned 87
+ * entries while the migrated corpus held 688).
+ *
  * Precedence is explicit-over-ambient, most specific first:
- *   1. `options.rootDir`  - the corpus, named outright (no `installed` suffix)
- *   2. `options.homeDir`  - <home>/.hasna/skills/installed
- *   3. `getDataDir()`     - <app folder>/installed, where the app folder is
- *                           $HASNA_SKILLS_DIR, else ~/.hasna/skills
+ *   1. `options.rootDir`      - the corpus, named outright (no suffix)
+ *   2. the migrated owner layout - <app folder>/skills/ when a migration record
+ *      exists there (the record is the authority; a skills/ directory someone
+ *      created by hand is not the corpus)
+ *   3. `getDataDir()`         - <app folder>/installed (pre-migration corpus,
+ *      with the legacy auto-copy migration), where the app folder is
+ *      $HASNA_SKILLS_DIR, else ~/.hasna/skills
  *
  * The app folder holds app data (config.json, skills.db, auth.json); the corpus
  * is a named subfolder of it, matching every sibling Hasna app. One variable
@@ -46,6 +56,24 @@ export interface CorpusSkillMeta {
     tags?: string[];
     version?: string;
     kind?: SkillKind;
+    /**
+     * The hosted registry's revision id for this skill (todos d061fcda), when the
+     * instance reported one. Carried onto the metadata-only pull path so the pull marker
+     * records which revision was installed there too.
+     */
+    revisionId?: string;
+    /**
+     * The row's SKILL.md, served in the published metadata so a client can recompute the
+     * content-addressed revision id and PROVE the declared revision identifies the content
+     * it received (todos d061fcda).
+     */
+    skillMd?: string;
+    /**
+     * The row's stored source (the payload's own `source` is always the client view
+     * "remote"). The canonical revision hash is computed over the stored value, so the
+     * client needs it to recompute the id.
+     */
+    publishedSource?: string;
 }
 export interface WriteCorpusSkillInput {
     name: string;
@@ -54,8 +82,9 @@ export interface WriteCorpusSkillInput {
     meta?: CorpusSkillMeta | null;
 }
 /**
- * Write a skill fetched from a Skills instance into the local corpus
- * (~/.hasna/skills/installed/<name>/), so loadRegistry() surfaces it to both the CLI
+ * Write a skill fetched from a Skills instance into the local corpus (the
+ * canonical root — installed/ before the layout migration, <app folder>/skills/
+ * after it), so loadRegistry() surfaces it to both the CLI
  * (`skills list --all`) and the MCP (`list_skills`) with no further step — the whole
  * point of the pull: the corpus is already a first-class registry source.
  *