@hasna/skills 0.1.62 → 0.1.64

package/docs/skill-standard.md

@@ -17,9 +17,34 @@ Portable skills live in one folder each:
 `skills port <path>` and `skills add <path>` copy an existing skill folder into
 this layout and add missing standard files.
 
+## The manifest split
+
+Two metadata surfaces exist, with one rule: **portable metadata lives in
+`skill.json`; consumer frontmatter stays minimal.**
+
+- `skill.json` is the machine-readable manifest and the **source of truth**
+  for everything the fleet needs to know about a skill: identity, version,
+  runtime contract, provenance. It is the `hasna.skill.v1` contract defined
+  in `schemas/skill.schema.json` (published at
+  `https://hasna.dev/schemas/skill.v1.json`).
+- `SKILL.md` is the agent-facing document. Its frontmatter carries only
+  `name` and `description` (plus `user_invocable: true` where a Claude
+  consumer renderer needs it). Everything else — `kind`, `version`,
+  `source`, `category`, `tags`, `displayName` — lives in `skill.json`.
+  See `docs/authoring-rule-amendment.md` for the proposed fleet rule text.
+
+```yaml
+---
+name: my-skill
+description: What this skill does and when to use it.
+---
+```
+
 ## Skill Kinds
 
-A skill declares its artifact class with the `kind` frontmatter field:
+A skill declares its artifact class with the `kind` field in `skill.json`
+(`kind` may also appear in `SKILL.md` frontmatter for compatibility with
+existing Codewith conventions):
 
 - `kind: executable` (default when omitted) — a runnable skill folder with
   `package.json`, a non-empty `bin`, and `src/index.ts`. `skills run` executes it.
@@ -33,45 +58,65 @@ A skill declares its artifact class with the `kind` frontmatter field:
 Missing `kind` defaults to `executable` so the bundled corpus is unaffected.
 Migrated operational (prose) skills should set `kind: instruction` explicitly.
 
-Minimum `SKILL.md` frontmatter for an instruction skill:
-
-```yaml
----
-name: project
-description: Open or resume an existing Hasna repo project using the projects CLI.
-kind: instruction
-version: 0.1.0
-source: private
----
-```
-
 ## Naming
 
 Skill names are lowercase slugs: letters, numbers, dots, underscores, and
 hyphens. The folder name, `SKILL.md` frontmatter `name`, `skill.json` `name`,
-and `package.json` `name` should match.
-
-## Manifest
-
-Every portable skill needs a manifest. `skill.json` is the machine-readable
-manifest. `SKILL.md` frontmatter stays compatible with existing Codewith
-`SKILL.md` conventions and can be used by agents for skill discovery.
-
-Minimum `SKILL.md` frontmatter:
-
-```yaml
----
-name: my-skill
-description: What this skill does and when to use it.
-version: 0.1.0
-source: custom
-category: Development Tools
-tags:
-  - custom
----
-```
-
-Minimum `skill.json`:
+and `package.json` `name` must match.
+
+## The `hasna.skill.v1` manifest
+
+Every portable skill needs a `skill.json` manifest conforming to
+`hasna.skill.v1` (schema: `schemas/skill.schema.json`). The templates always
+emit a complete valid manifest; `skills validate` rejects one that is
+incomplete, invalid, or whose `content_hash` does not match the bundle.
+
+### Required fields
+
+| field | type | meaning |
+|---|---|---|
+| `standard` | string | `"hasna.skill.v1"` |
+| `name` | string | Lowercase slug; matches the folder name |
+| `description` | string | What this skill does and when to use it |
+| `version` | string | Semver (e.g. `0.1.0`). Any content change requires a version bump |
+| `runtime` | object | The runtime contract below |
+| `provenance` | object | Source and integrity fields; `content_hash` is required |
+
+### Optional fields (legacy-compatible)
+
+| field | type | meaning |
+|---|---|---|
+| `$schema` | string | `https://hasna.dev/schemas/skill.v1.json` |
+| `displayName` | string | Human-facing name |
+| `category` | string | Marketplace / registry category |
+| `tags` | string[] | Searchable tags |
+| `kind` | `"executable" \| "instruction"` | Artifact class |
+| `inputs` | object[] | Declared inputs (`name`, `type`, optional `required`, `description`) |
+| `commands` | object[] | Runnable commands (`name`, `entry`/`command`, optional `args`, `description`) |
+
+### The runtime contract
+
+| field | type | default | meaning |
+|---|---|---|---|
+| `runtime` | `"bun" \| "node" \| "python3"` | *(required)* | Execution runtime. `bun` is the Hasna default |
+| `version` | string | — | Optional runtime version constraint (e.g. `"22"`, `">=3.12"`) |
+| `entrypoint` | string | `commands[0].entry` | Relative path to the runnable entrypoint |
+| `timeout` | integer | `900` | Max execution seconds, **capped at 900** |
+| `needs_network` | boolean | `false` | Whether execution requires network egress |
+| `env` | string[] | `[]` | **Secret REFERENCE names only, never values** — uppercase identifiers such as `OPENAI_API_KEY` |
+| `sandbox` | `"readonly-fs" \| "workspace-write" \| "full"` | `"readonly-fs"` | Filesystem access granted to execution |
+| `system_deps` | string[] | `[]` | Allowlisted system binaries (see schema for the list) |
+| `artifacts` | string[] | `[]` | Glob patterns of artifacts the skill may produce (e.g. `"out/**"`) |
+
+### The provenance fields
+
+| field | type | meaning |
+|---|---|---|
+| `source_commit` | string | Git SHA of the source revision, or `"unknown"` for locally scaffolded skills |
+| `content_hash` | string | **Self-referencing** canonical SHA-256 of the normalized bundle (see below). Required on every manifest |
+| `changelog` | string | Pointer to changelog / release notes (relative path or URL) |
+
+### Example
 
 ```json
 {
@@ -80,6 +125,9 @@ Minimum `skill.json`:
   "name": "my-skill",
   "description": "What this skill does and when to use it.",
   "version": "0.1.0",
+  "displayName": "My Skill",
+  "category": "Development Tools",
+  "tags": ["custom"],
   "inputs": [
     {
       "name": "args",
@@ -95,13 +143,61 @@ Minimum `skill.json`:
       "description": "Run my-skill.",
       "args": ["...args"]
     }
-  ]
+  ],
+  "runtime": {
+    "runtime": "bun",
+    "entrypoint": "src/index.ts",
+    "timeout": 900,
+    "needs_network": false,
+    "env": [],
+    "sandbox": "readonly-fs",
+    "system_deps": [],
+    "artifacts": []
+  },
+  "provenance": {
+    "source_commit": "unknown",
+    "content_hash": "<64 lowercase hex chars>",
+    "changelog": "CHANGELOG.md"
+  }
 }
 ```
 
 If `skill.json` is absent, the CLI can infer a portable manifest from
 `SKILL.md` frontmatter plus `package.json` `bin`, but scaffolded and ported
-skills should keep `skill.json` checked in.
+skills always keep a complete `skill.json` checked in. A manifest present
+without a valid `content_hash` is rejected by `skills validate`.
+
+## Canonical content hashing
+
+`content_hash` is a **self-referencing** SHA-256 over the normalized skill
+bundle:
+
+1. **Coverage** — every file at the skill root (`SKILL.md`, `skill.json`,
+   `AGENTS.md`, `package.json`, `tsconfig.json`) plus every file under
+   `src/`, `scripts/`, `assets/`, and `references/`, recursively.
+2. **Exclusions** — `node_modules`, `.git`, `dist`, `build`, `.turbo`,
+   dot-entries, and symlinks never enter the hash.
+3. **Normalization** — line endings are normalized to LF; for `skill.json`
+   the manifest is **blank-canonicalized**: parsed, its own `content_hash`
+   field (top-level or under `provenance`) removed, and re-serialized with
+   sorted keys. Key order, CRLF, and the hash's own presence therefore never
+   change the digest.
+4. **Determinism** — files are hashed in sorted relative-path order (posix
+   separators), each entry length-prefixed, so the digest is identical on
+   every platform for the same logical content.
+5. **Verification** — `skills validate` recomputes the hash and rejects any
+   manifest whose declared `content_hash` does not match, with the computed
+   value in the error message.
+
+### Versioning rule
+
+**A content change requires a version bump; the same version with different
+content is rejected.** Enforcement is structural: any content change alters
+the canonical bundle, so the declared `content_hash` no longer matches and
+`skills validate` fails (`contract.content_hash_mismatch`). Re-hashing
+without a version bump is still a rejection signal for the registry/server
+later, which pins by version + hash — same semver + different hash is
+unpublishable.
 
 ## Agent Handoff
 
@@ -136,6 +232,11 @@ Validation checks:
 
 - folder and name safety;
 - `SKILL.md` frontmatter compatibility (including a valid `kind`);
+- the `hasna.skill.v1` contract: `standard`, `name`, `description`, `version`
+  (semver), the runtime contract (runtime, timeout cap, sandbox, env reference
+  names, system-deps allowlist), and provenance;
+- the canonical `content_hash`: present, well-formed, and matching the bundle
+  (`contract.content_hash_mismatch` on drift);
 - `skill.json` standard, version, inputs, and commands (relaxed for
   `kind: instruction`, which needs neither `commands`, `inputs`, nor `AGENTS.md`);
 - `AGENTS.md` presence (executable skills only);
@@ -143,6 +244,8 @@ Validation checks:
   optional for `kind: instruction`);
 - no reserved files such as `.env` or symlinks.
 
+An invalid manifest exits non-zero with the exact field errors.
+
 ## Porting Existing Skills
 
 ```bash
@@ -153,4 +256,73 @@ skills add ./old-skill --name new-name
 Porting copies the folder into `~/.hasna/skills/<name>/`, skips generated and
 dependency directories such as `node_modules`, `dist`, and `.git`, then adds or
 normalizes `skill.json`, `AGENTS.md`, `package.json`, `tsconfig.json`, and an
-entrypoint when they are missing.
+entrypoint when they are missing. Missing contract fields (runtime defaults,
+provenance) are filled and the `content_hash` is recomputed over the ported
+bundle; unknown keys in an existing `skill.json` are preserved.
+
+## Machine Layout
+
+The skills app folder (`~/.hasna/skills/`, relocatable with
+`$HASNA_SKILLS_DIR`) hosts the owner layout:
+
+```text
+~/.hasna/skills/
+├── skills/     canonical corpus cache — the sync source
+├── logs/       run/sync logs (created lazily)
+├── outputs/    run outputs (created lazily)
+├── custom/     experiments, retained as-is
+├── config.json
+└── skills.db
+```
+
+`skills/` replaces the older `installed/` corpus home, and legacy flat skill
+dirs that predate `installed/` migrate into it. Both moves are opt-in and
+idempotent:
+
+```bash
+skills storage migrate            # installed/ + legacy dirs -> skills/, creates logs/ + outputs/
+skills storage migrate --dry-run  # show what would move, write nothing
+```
+
+Migration refuses to run against a non-empty `skills/` that carries no
+migration record (`skills/.layout-migration.json`), and never touches
+`custom/`. After a successful migration `skills sync` reads the corpus from
+the new cache automatically.
+
+### Unmarked-home adoption
+
+Agent homes are full of skill directories the CLI never wrote (the ad-hoc
+sed/scp/rsync era). Those carry no `.hasna-skills.json` marker and sync leaves
+them alone by design. Adoption is the migration mode for that population:
+
+```bash
+skills sync --adopt             # dry-run: hash unmarked home skills vs the corpus
+skills sync --adopt --apply     # write markers for exact matches; ledger the rest
+```
+
+Each unmarked home skill's `SKILL.md` is hashed (line endings normalized,
+`user_invocable` stripped) and compared against the canonical corpus cache:
+
+- exact match -> a marker is written and the dir is adopted;
+- content differs -> recorded in `~/.hasna/skills/conflicts.json` (home, skill,
+  hash, canonical hash, mtime) and skipped — an unmarked dir is never
+  overwritten;
+- no canonical entry -> reported as unknown and skipped.
+
+Every written marker is listed in a rollback record under
+`~/.hasna/skills/rollback/`. Nothing is ever deleted by adoption.
+
+### Home drift census
+
+```bash
+skills sync --check             # exits non-zero while drift exists
+```
+
+Compares each existing agent home against the canonical corpus and lists
+`missing-from-home`, `stray-in-home` (marked dir, no canonical entry), and
+`diverged` (marked dir whose hash differs). Unmarked dirs are adoption
+candidates, not drift. `skills diff <name>` and `skills outdated` use the same
+home-vs-canonical comparison; the pinned-skill version comparison remains as a
+subset. `skills sync --prune [--apply]` removes only marked-and-stray dirs,
+recording each removal in the rollback store before it happens.
+

package/migrations/postgres/0003_run_outputs_governance.sql

@@ -0,0 +1,83 @@
+-- Run outputs governance: privacy, retention, cancellation fencing, spend.
+--
+-- Postgres dialect of 0003_run_outputs_governance. Read the SQLite file for why
+-- the migration is additive; the rationale is not repeated here, only the
+-- dialect differences are:
+--   * timestamptz -> text holding a UTC ISO-8601 instant (expires_at, reconciled_at).
+--   * text JSON   -> jsonb (metadata_json).
+--
+-- SQLite has no row-level security; tenant isolation there rests on the
+-- org-scoped predicates in the store and the service-layer negative tests. This
+-- dialect additionally arms PostgreSQL RLS on the two tenant tables, so a
+-- statement that never set the tenant context sees zero rows (fail closed):
+--
+--   CREATE POLICY ... USING (
+--     org_id = current_setting('app.skills_org_id', true)
+--     OR current_setting('app.skills_claim_context', true) = 'worker'
+--   )
+--
+-- The first clause is the principal path: the store runs every tenant-facing
+-- read under SET LOCAL app.skills_org_id = <org>, and an unset setting matches
+-- nothing. The second clause is the worker path, stated as the deliberate
+-- exception it is: skills-worker claims and finalises runs for every org on the
+-- instance (claimNextRun is not org-scoped by design), so it writes under an
+-- explicit claim context rather than a tenant context. Both clauses must be
+-- present for the shipped server to work at all, and neither weakens the tenant
+-- fence: a caller with no context and no claim role reads no tenant rows.
+
+ALTER TABLE skills_runs ADD COLUMN lease_generation integer NOT NULL DEFAULT 0;
+
+ALTER TABLE skills_artifacts ADD COLUMN visibility text NOT NULL DEFAULT 'private';
+ALTER TABLE skills_artifacts ADD COLUMN expires_at timestamptz;
+
+CREATE TABLE IF NOT EXISTS skills_lifecycle_receipts (
+  id text PRIMARY KEY,
+  kind text NOT NULL,
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES skills_runs(id) ON DELETE CASCADE,
+  artifact_id text,
+  requested_by text NOT NULL,
+  metadata_json jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CHECK (kind IN ('delete','quarantine','cancel'))
+);
+
+CREATE INDEX IF NOT EXISTS skills_lifecycle_receipts_org_run_idx
+  ON skills_lifecycle_receipts (org_id, run_id);
+
+CREATE TABLE IF NOT EXISTS skills_credit_reservations (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES skills_runs(id) ON DELETE CASCADE,
+  estimated_cents integer NOT NULL,
+  actual_cents integer,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  reconciled_at timestamptz,
+  CHECK (status IN ('reserved','charged','released'))
+);
+
+CREATE INDEX IF NOT EXISTS skills_credit_reservations_org_run_idx
+  ON skills_credit_reservations (org_id, run_id);
+
+ALTER TABLE skills_runs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE skills_artifacts ENABLE ROW LEVEL SECURITY;
+
+-- FORCE closes the owner exemption: Postgres exempts a table's owner from RLS,
+-- and this instance runs migrations and the server as one role, so without
+-- FORCE the fence would not bind the app path. With FORCE the store's
+-- tenant/worker contexts apply to that role like any other.
+ALTER TABLE skills_runs FORCE ROW LEVEL SECURITY;
+ALTER TABLE skills_artifacts FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY skills_runs_tenant_isolation ON skills_runs
+  USING (
+    org_id = current_setting('app.skills_org_id', true)
+    OR current_setting('app.skills_claim_context', true) = 'worker'
+  );
+
+CREATE POLICY skills_artifacts_tenant_isolation ON skills_artifacts
+  USING (
+    org_id = current_setting('app.skills_org_id', true)
+    OR current_setting('app.skills_claim_context', true) = 'worker'
+  );

package/migrations/postgres/0004_hosted_pins.sql

@@ -0,0 +1,28 @@
+-- Hosted pins: the cloud becomes a source of truth for what the user selected.
+--
+-- Today a pin lives only in local project state (.skills/project.json); an
+-- instance has no pins surface, so nothing a user selected is ever visible to
+-- the server, to a second machine, or to another operator of the same org.
+-- This table is that surface.
+--
+-- Row identity is (org_id, principal, slug): one org, one API key, one slug -
+-- a pin is a fact about a specific principal's selection. `principal` stores
+-- the api_keys.id of the API key that pinned (ApiPrincipal.apiKeyId), so two
+-- API keys in the same org each have their own pin set, and two organizations
+-- can pin the same slug without colliding. The task's UNIQUE(org,principal,slug)
+-- is expressed as the composite primary key, which implies the same uniqueness
+-- and is the row's natural identity - there is no separate id to mint.
+--
+-- Pins are metadata-only: slug plus a free-form metadata object. Nothing here
+-- references skills_registry, so a pin may name a skill the org has not
+-- published (a bundled skill, or one that will exist later) without a
+-- foreign-key constraint choosing which of those futures is allowed.
+
+CREATE TABLE IF NOT EXISTS skills_pins (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  principal text NOT NULL,
+  slug text NOT NULL,
+  pinned_at timestamptz NOT NULL DEFAULT now(),
+  metadata_json jsonb NOT NULL DEFAULT '{}'::jsonb,
+  PRIMARY KEY (org_id, principal, slug)
+);

package/migrations/postgres/0005_revision_tombstone_registry.sql

@@ -0,0 +1,37 @@
+-- Revision identity, optimistic concurrency, and the tombstone contract for the hosted
+-- registry (todos d061fcda, plan 8022d27f).
+--
+-- Three behaviours this migration makes possible, all in one table because they are
+-- three properties of the same row:
+--
+--   1. IMMUTABLE REVISION IDENTITY. revision_id is a sha-256 over the row's published
+--      content (computed in TypeScript, src/lib/revision.ts) and revision_number is a
+--      monotonic per-slug write counter. Together they let a client prove WHICH revision
+--      it installed and let the server refuse a stale overwrite.
+--
+--   2. OPTIMISTIC CONCURRENCY. publish/update require an If-Match carrying the current
+--      revision_id; a mismatch (or a missing guard against an existing row) returns 409
+--      instead of silently overwriting a newer revision. The guard is enforced in the
+--      store's SQL (WHERE ... revision_id = <expected> on the upsert), never in
+--      read-then-write JS, so two concurrent writers cannot both pass a stale check.
+--
+--   3. TOMBSTONES. delete no longer drops the row: it stamps tombstoned_at +
+--      tombstone_purge_after (delete time + the configured window). Reads within the
+--      window answer 410 with the tombstone marker so a client's pull can reconcile
+--      (remove the local copy); after the window a read or list purges the row and its
+--      bundle. Re-publish over a tombstoned slug revives it as a fresh revision.
+--
+-- The columns are added by ALTER rather than by the 0002 drop-and-recreate pattern:
+-- the registry can hold tenant rows now (publishing shipped in the 0002 change), so a
+-- rebuild would be data loss. Rows that predate this migration get revision_id '' and
+-- revision_number 0; the store backfills a content sha for them on first open, because
+-- an empty revision id would make If-Match vacuous for legacy rows (every stale client
+-- would "match" the same empty string and two concurrent writers could both land).
+--
+-- Hand-written parallel of migrations/sqlite/0005_revision_tombstone_registry.sql; the
+-- dialect differences are the same documented set as 0001-0003 (timestamptz -> text).
+
+ALTER TABLE skills_registry ADD COLUMN revision_id text NOT NULL DEFAULT '';
+ALTER TABLE skills_registry ADD COLUMN revision_number integer NOT NULL DEFAULT 0;
+ALTER TABLE skills_registry ADD COLUMN tombstoned_at timestamptz;
+ALTER TABLE skills_registry ADD COLUMN tombstone_purge_after timestamptz;

package/migrations/postgres/0005_tag_projection.sql

@@ -0,0 +1,36 @@
+-- The hosted tag surface (T7) queries tag membership from this relational
+-- projection of skills_registry.tags_json, in both dialects with one identical
+-- shape. SQLite cannot index json_each() over the JSON column, and Postgres
+-- rows written by the current path hold the array text inside a jsonb scalar
+-- (bun's driver binds a JS string against a ::jsonb cast as a JSON string), so
+-- neither dialect can serve an indexed array-expansion query directly. The
+-- projection turns tag membership into a plain indexed lookup: the PRIMARY KEY
+-- serves (org_id, slug) maintenance and the org_tag index serves (org_id, tag)
+-- filters. The write paths keep it in step; the backfill below covers rows
+-- that predate it.
+-- No composite FK to skills_registry: the schema-parity parser cannot
+-- represent a multi-column FK identically in both dialects, and every write
+-- path here maintains the projection explicitly (publish/update replace its
+-- rows, the tombstone purge removes them with the row), so the constraint
+-- would be redundancy.
+CREATE TABLE skills_tags (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  slug text NOT NULL,
+  tag text NOT NULL,
+  PRIMARY KEY (org_id, slug, tag)
+);
+
+CREATE INDEX skills_tags_org_tag_idx ON skills_tags (org_id, tag);
+
+-- Backfill every existing row's tags. tags_json may be a real array or,
+-- because of the jsonb-scalar write path, the array text inside a jsonb
+-- string; both shapes are expanded here.
+INSERT INTO skills_tags (org_id, slug, tag)
+SELECT DISTINCT r.org_id, r.slug, t.tag
+FROM skills_registry r
+CROSS JOIN LATERAL jsonb_array_elements_text(
+  CASE WHEN jsonb_typeof(r.tags_json) = 'array' THEN r.tags_json
+       WHEN jsonb_typeof(r.tags_json) = 'string' THEN (r.tags_json #>> '{}')::jsonb
+       ELSE '[]'::jsonb END
+) AS t(tag)
+WHERE t.tag <> '';

package/migrations/sqlite/0003_run_outputs_governance.sql

@@ -0,0 +1,58 @@
+-- Run outputs governance: privacy, retention, cancellation fencing, spend.
+--
+-- Three columns and two tables, all additive. skills_runs/skills_artifacts hold
+-- tenant rows today, so this migration must not drop or rebuild them - the 0002
+-- drop-and-recreate pattern was safe only while the tables had never had a writer.
+--
+--   * skills_artifacts.visibility     - outputs are PRIVATE by default.
+--   * skills_artifacts.expires_at     - finite retention: set at write time from
+--                                       the configured TTL, swept by the expiry
+--                                       service, never open-ended.
+--   * skills_runs.lease_generation    - the cancellation fence. Each claim bumps
+--                                       it; a worker that keeps writing with a
+--                                       stale generation is rejected. Cancel bumps
+--                                       it too, fencing the worker it interrupts.
+--
+-- skills_lifecycle_receipts is the immutable, append-only record of every
+-- deletion, quarantine, and cancellation. There is no UPDATE or DELETE path in
+-- the store for this table - a receipt is a fact that happened, not state to
+-- correct.
+--
+-- skills_credit_reservations is the spend ledger: a reservation is made before
+-- dispatch, reconciled once at terminal state (charged with the actual cost, or
+-- released when the run used nothing).
+
+ALTER TABLE skills_runs ADD COLUMN lease_generation integer NOT NULL DEFAULT 0;
+
+ALTER TABLE skills_artifacts ADD COLUMN visibility text NOT NULL DEFAULT 'private';
+ALTER TABLE skills_artifacts ADD COLUMN expires_at text;
+
+CREATE TABLE IF NOT EXISTS skills_lifecycle_receipts (
+  id text PRIMARY KEY,
+  kind text NOT NULL,
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES skills_runs(id) ON DELETE CASCADE,
+  artifact_id text,
+  requested_by text NOT NULL,
+  metadata_json text NOT NULL DEFAULT '{}',
+  created_at text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  CHECK (kind IN ('delete','quarantine','cancel'))
+);
+
+CREATE INDEX IF NOT EXISTS skills_lifecycle_receipts_org_run_idx
+  ON skills_lifecycle_receipts (org_id, run_id);
+
+CREATE TABLE IF NOT EXISTS skills_credit_reservations (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES skills_runs(id) ON DELETE CASCADE,
+  estimated_cents integer NOT NULL,
+  actual_cents integer,
+  status text NOT NULL,
+  created_at text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  reconciled_at text,
+  CHECK (status IN ('reserved','charged','released'))
+);
+
+CREATE INDEX IF NOT EXISTS skills_credit_reservations_org_run_idx
+  ON skills_credit_reservations (org_id, run_id);

package/migrations/sqlite/0004_hosted_pins.sql

@@ -0,0 +1,21 @@
+-- Hosted pins: the cloud becomes a source of truth for what the user selected.
+--
+-- SQLite dialect of 0004_hosted_pins. Read the Postgres file for the why; the
+-- only differences here are the documented dialect mapping:
+--   * timestamptz -> text holding a UTC ISO-8601 instant (pinned_at).
+--   * jsonb       -> text holding JSON (metadata_json).
+--
+-- No RLS: the tenant fence on this table is the org-scoped predicate in the
+-- store, exactly as it is for skills_registry and skills_bundles. RLS was
+-- armed in 0003 only for the run-output tables, where a worker path writes
+-- outside a tenant context; pins are written and read only by the API under
+-- the requesting principal's org, so there is no context-less writer to fence.
+
+CREATE TABLE IF NOT EXISTS skills_pins (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  principal text NOT NULL,
+  slug text NOT NULL,
+  pinned_at text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  metadata_json text NOT NULL DEFAULT '{}',
+  PRIMARY KEY (org_id, principal, slug)
+);

package/migrations/sqlite/0005_revision_tombstone_registry.sql

@@ -0,0 +1,18 @@
+-- SQLite dialect of 0005_revision_tombstone_registry.
+--
+-- Hand-written parallel of migrations/postgres/0005_revision_tombstone_registry.sql. Read
+-- that file for why the registry gains revision_id/revision_number (immutable revision
+-- identity), the optimistic-concurrency guard, and the tombstone contract; the rationale
+-- is not repeated here, only the dialect differences are.
+--
+-- Deliberate, shape-preserving dialect differences (same set as 0001):
+--   * timestamptz -> text holding a UTC ISO-8601 instant.
+--
+-- SQLite requires a non-null literal DEFAULT for a NOT NULL ADD COLUMN; the '' default is
+-- the legacy-row marker the store's backfill (src/lib/revision.ts) replaces with a
+-- content sha on first open, exactly as on Postgres.
+
+ALTER TABLE skills_registry ADD COLUMN revision_id text NOT NULL DEFAULT '';
+ALTER TABLE skills_registry ADD COLUMN revision_number integer NOT NULL DEFAULT 0;
+ALTER TABLE skills_registry ADD COLUMN tombstoned_at text;
+ALTER TABLE skills_registry ADD COLUMN tombstone_purge_after text;

package/migrations/sqlite/0005_tag_projection.sql

@@ -0,0 +1,25 @@
+-- The hosted tag surface (T7) queries tag membership from this relational
+-- projection of skills_registry.tags_json, in both dialects with one identical
+-- shape. SQLite cannot index json_each() over the JSON column, so the tag
+-- lookup becomes an indexed read here: the PRIMARY KEY serves (org_id, slug)
+-- maintenance and the org_tag index serves (org_id, tag) filters. The write
+-- paths keep it in step; the backfill below covers rows that predate it.
+-- No composite FK to skills_registry: the schema-parity parser cannot
+-- represent a multi-column FK identically in both dialects, and every write
+-- path here maintains the projection explicitly (publish/update replace its
+-- rows, the tombstone purge removes them with the row), so the constraint
+-- would be redundancy.
+CREATE TABLE skills_tags (
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  slug text NOT NULL,
+  tag text NOT NULL,
+  PRIMARY KEY (org_id, slug, tag)
+);
+
+CREATE INDEX skills_tags_org_tag_idx ON skills_tags (org_id, tag);
+
+-- Backfill every existing row's tags from the stored JSON array.
+INSERT INTO skills_tags (org_id, slug, tag)
+SELECT DISTINCT r.org_id, r.slug, je.value
+FROM skills_registry r, json_each(r.tags_json) AS je
+WHERE je.value <> '';