@hasna/skills 0.1.59 → 0.1.61

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/skills
 
-Skills library for AI coding agents — discover, pin, and run reusable capabilities through the Skills CLI and MCP server for Claude Code, Codex CLI, Gemini CLI, OpenCode, and more.
+Skills library for AI coding agents — discover, pin, and run reusable capabilities through the Skills CLI and MCP server. Registers with Claude, Codex, Cursor, OpenCode, Gemini, Windsurf and Pi, and works with any MCP host.
 
 [![npm](https://img.shields.io/npm/v/@hasna/skills)](https://www.npmjs.com/package/@hasna/skills)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -19,53 +19,53 @@ Requires [Bun](https://bun.sh/) 1.0+.
 # Browse skills interactively
 skills
 
-# Self-hosted setup points the CLI at the Hasna-owned API
-skills setup --mode self-hosted
+# Point the CLI at a Skills API server when you want remote runs
+skills setup --api-url https://skills.example.com
 skills auth login --api-key "$SKILLS_API_KEY"
 
-# Local-only setup stays available and does not require an account
-skills setup --mode local
+# With no API URL configured, skills simply run on this machine
+skills list
 
 # Optionally pin a skill preference in this project
-skills pin image
+skills pin logo-design
 
 # Register the Skills MCP server with every supported agent
 skills setup agents
 
 # See what a skill needs
-skills info image
+skills info logo-design
 
-# Premium skills run through the configured self-hosted API
-skills run image "a cat sitting on a windowsill"
+# Premium skills run through the configured Skills API
+skills run logo-design --brief "minimal geometric owl mark"
 
 # Free/local skills can still use your own provider keys when documented
 skills requires brand-style-guide
 OPENAI_API_KEY=... skills run brand-style-guide ./brand-notes.md
 ```
 
-## Self-Hosted Runtime Skills
+## Server-Side Runtime Skills
 
-Premium skills are self-hosted runs. The CLI and MCP server submit them to the
-configured self-hosted API, create local run metadata, and then expose status
-and artifact commands. They do not fall back to bundled local execution when
-auth is missing or the self-hosted runtime is unavailable.
+Premium skills run on the server. The CLI and MCP server submit them to the
+configured Skills API, create local run metadata, and then expose status and
+artifact commands. They do not fall back to bundled local execution when auth is
+missing or the server runtime is unavailable.
 
-Use `SKILLS_API_KEY` or `skills auth login --api-key` for premium self-hosted
+Use `SKILLS_API_KEY` or `skills auth login --api-key` for premium server-side
 execution:
 
 ```bash
-skills setup --mode self-hosted --api-url https://skills.md
+skills setup --api-url https://skills.example.com
 skills auth login --api-key "$SKILLS_API_KEY"
-skills run image "editorial product photo on a white sweep"
+skills run logo-design --brief "minimal geometric owl mark"
 skills runs status <run-id>
 skills exports download <run-id>
 ```
 
 Browser/device-code and email-code login commands are retained for compatible
-deployments. The Hasna self-hosted deployment can bootstrap with a provisioned
-API key via `skills auth login --api-key`.
+deployments. A Skills deployment can bootstrap with a provisioned API key via
+`skills auth login --api-key`.
 
-`SKILLS_API_KEY` is the self-hosted API credential. It is not a provider
+`SKILLS_API_KEY` is the Skills API credential. It is not a provider
 credential. Provider keys such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or
 `GEMINI_API_KEY` remain supported only for free/local OSS skills whose
 requirements explicitly document local provider use.
@@ -79,8 +79,8 @@ requirements explicitly document local provider use.
 | `skills pin --category "Development Tools"` | | Pin all skills in a category |
 | `skills unpin <name>` | | Remove a project pin |
 | `skills pins list` | | List pinned skills |
-| `skills setup --mode self-hosted` | | Configure self-hosted mode with a compatible API origin |
-| `skills setup --mode local` | | Configure local-only mode without self-hosted credentials |
+| `skills setup --api-url <url>` | | Point the CLI at a Skills API origin for remote runs |
+| `skills setup` | | Show whether an API origin is configured; with none, skills run on this machine |
 | `skills setup agents` | | Register the Skills MCP server with all supported agents |
 | `skills list` | `ls` | List available skills (filter with `-c`, `--pinned`, `-t`, `--brief`) |
 | `skills search <query>` | `s` | Search by name, description, or tags |
@@ -99,17 +99,18 @@ requirements explicitly document local provider use.
 | `skills doctor` | | Check env vars, system deps, and pinned skill health |
 | `skills test [name]` | | Test skill readiness (env, system, npm deps) |
 | `skills outdated` | | Compare pinned vs registry versions |
-| `skills auth login --api-key <key>` | | Verify and store a self-hosted API key |
+| `skills auth login --api-key <key>` | | Verify and store a Skills API key |
 | `skills auth login` | | Sign in to a compatible API with browser/device-code auth or email code |
-| `skills billing status` | | Show self-hosted account plan and balance |
+| `skills billing status` | | Show server account plan and balance |
 | `skills billing checkout` | | Create a checkout session when billing is enabled |
 | `skills billing portal` | | Create a customer portal session when billing is enabled |
 | `skills credits buy <amount>` | | Create a credit-pack checkout session when billing is enabled |
 | `skills setup-info` | | Version, pinned skills, agent configs, paths |
 | `skills export` | | Export pinned skills as JSON |
 | `skills import <file>` | | Pin skills from a JSON export |
-| `skills config set <key> <value>` | | Set default agent, scope, or output format |
-| `skills new <name>` | `scaffold` | Scaffold a portable skill under `~/.hasna/skills/<name>` |
+| `skills config set <key> <value>` | | Set default agent, scope, output format, or API origin |
+| `skills config unset <key>` | | Remove a configuration value (`skills config unset apiUrl` returns to running on this machine) |
+| `skills new <name>` | `scaffold` | Scaffold a portable skill under `~/.hasna/skills/installed/<name>` |
 | `skills port <path>` | `add` | Import an existing skill folder into the portable standard |
 | `skills create <name>` | | Scaffold a new custom skill directory |
 | `skills sync --to claude` | | Disabled by design; use `skills mcp --register <agent|all>` |
@@ -150,7 +151,7 @@ skills list --all --limit 50
 skills list --all --cursor 50 --limit 50
 skills list --all --limit all
 skills list --all --verbose
-skills show image
+skills show logo-design
 skills search pdf --json
 ```
 
@@ -174,7 +175,7 @@ Stable command shapes:
   `{ "dryRun": true, "actions": [...] }` where applicable.
 - Runtime: `run --json <skill> ...` returns
   `{ "skill", "args", "exitCode", "stdout", "stderr", "error", "run" }`.
-  Premium self-hosted runs include `{ "contractVersion": 1, "remote": true,
+  Premium server-side runs include `{ "contractVersion": 1, "remote": true,
   "remoteRun", "pricing", "run", "nextActions" }` and return immediately with
   status commands such as `skills runs status <run-id>` and
   `skills exports download <run-id>`.
@@ -186,15 +187,18 @@ Stable command shapes:
 - MCP registration: `mcp --register <agent> --json` returns
   `{ "registered": number, "results": [...] }`.
 
-## Self-Hosted Registry Mode
+## Remote Registry
 
-Local bundled skills remain the default for discovery. To point browse/search
-commands at a compatible self-hosted registry, set an API base URL:
+Local bundled skills remain the default for discovery. This is not a mode you
+select: pointing browse/search commands at a server's registry is one fact, an
+API base URL being set. To set it:
 
 ```bash
 export SKILLS_API_URL=https://your-server.example
 # or persist it:
 skills config set apiUrl https://your-server.example
+# and to stop using it:
+skills config unset apiUrl
 
 skills list --remote --json
 skills search transcribe --remote --json
@@ -206,7 +210,7 @@ If the URL is an origin such as `https://your-server.example`, the CLI requests
 `/api/v1/skills`. If it already ends in `/api` or `/api/v1`, the CLI appends
 `/skills`.
 
-Authenticated registry listing and self-hosted premium execution use
+Authenticated registry listing and premium server-side execution use
 `SKILLS_API_KEY` or the credential saved by `skills auth login --api-key`.
 
 For the reusable upstream contract, see
@@ -214,7 +218,7 @@ For the reusable upstream contract, see
 
 ## Portable Skills
 
-Portable skills live directly under `~/.hasna/skills/<name>/` and follow the
+Portable skills live under `~/.hasna/skills/installed/<name>/` and follow the
 standard documented in `docs/skill-standard.md`.
 
 ```bash
@@ -255,7 +259,7 @@ Endpoints: `GET /health` → `{"status":"ok","name":"skills"}`, MCP at `/mcp`.
 Uses stateless `StreamableHTTPServerTransport` (shared process, many clients).
 `skills-mcp` without flags still uses stdio (unchanged).
 
-The MCP server exposes 20+ tools including `list_skills`, `search_skills`,
+The MCP server's tools include `list_skills`, `search_skills`,
 `scaffold_skill`, `port_skill`, `pin_skill`, `unpin_skill`, `pin_category`,
 `list_pinned_skills`, `get_skill_info`, `get_skill_docs`, `get_requirements`,
 `run_skill`, `get_run_status`, `schedule_skill`, `detect_project_skills`,
@@ -276,28 +280,95 @@ skills mcp --register claude    # Auto-register with Claude Code
 skills mcp --register all       # Register with all supported agents
 ```
 
-## Self-Hosted API
+## Skills API
 
 ```bash
-skills setup --mode self-hosted --api-url https://skills.md
+skills setup --api-url https://skills.example.com
 skills auth login --api-key "$SKILLS_API_KEY"
 skills billing status
 ```
 
-Self-hosted account, run, log, artifact, and optional billing commands use the
-configured self-hosted API. The public package stores only local configuration
-and CLI credentials. Runtime state belongs in Postgres and artifacts can be
-stored in S3 when `HASNA_SKILLS_S3_BUCKET` is configured.
+Account, run, log, artifact, and optional billing commands use the configured
+Skills API. The public package stores only local configuration
+and CLI credentials. Artifacts can be stored in S3 when `HASNA_SKILLS_S3_BUCKET`
+is configured.
+
+### Server database
+
+The server supports SQLite and Postgres. The database is an adapter choice, not a
+different product: the schema, the organization scoping, and the run lifecycle are
+identical either way.
+
+```bash
+skills-server                                            # SQLite at ~/.hasna/skills/server.db
+HASNA_SKILLS_DATABASE_URL=/srv/skills/server.db skills-server
+HASNA_SKILLS_DATABASE_URL=postgres://user:pw@host/skills skills-server
+```
+
+| `HASNA_SKILLS_DATABASE_URL` | Backend | Survives restart |
+| --- | --- | --- |
+| *(unset)* | SQLite at `<data dir>/server.db` | yes |
+| `/path/to.db`, `sqlite:/path`, `file:///path` | SQLite at that path | yes |
+| `postgres://…`, `postgresql://…` | Postgres | yes |
+| `:memory:`, `sqlite::memory:` | SQLite, in memory | no |
+| `memory:` | in-process map | no |
+| `sqlite:`, `sqlite://host/p`, `mysql://…`, … | startup error naming what is supported | — |
+
+An empty path (`sqlite:` — what `sqlite://${DB_PATH}` becomes when `DB_PATH` is
+unset) and a host where a path belongs (`sqlite://srv/a.db`, one slash short of
+`sqlite:///srv/a.db`) are configuration errors, not silently a scratch database or a
+new empty file under the working directory.
+
+The data directory follows `$HASNA_SKILLS_DIR`, so the database moves with the rest
+of the app's state. The database file sits at the app root, beside `config.json` —
+not inside `installed/`, which holds only the installed skill corpus.
+
+One sharp edge: `HASNA_SKILLS_DATABASE_URL` is shared with the optional repo-native
+storage sync under [Storage Boundary](#storage-boundary), and that sync speaks
+Postgres only — it takes this variable's value as given rather than checking it. If
+you point the server at a SQLite path and also use `skills storage sync-plan`, set
+the sync's database separately. The two are independent features that happen to
+read the same name.
+
+SQLite applies pending migrations when the server opens the database, so a single
+operator needs no separate migrate step. Postgres deployments run migrations
+explicitly, because several replicas racing to migrate one shared database is not
+something to do implicitly:
+
+```bash
+HASNA_SKILLS_DATABASE_URL=postgres://… skills-migrate
+```
+
+`skills-migrate` fails if no database is configured rather than migrating a default
+SQLite file, so it stays usable as a deploy gate.
+
+Three things the server will not do:
+
+- Fall back to another backend when a configured Postgres URL cannot be reached.
+  Degrading would leave your data split across two stores with no signal.
+- Start against a reachable Postgres that has no schema. `/health` returning `ok`
+  while the first API call 500s on a missing table is the failure this replaces.
+- Start on a store that does not survive a restart, unless
+  `HASNA_SKILLS_ALLOW_EPHEMERAL_STORE=1` says otherwise. The same guard applies to
+  `skills-worker`.
+
+**Durability is per-filesystem, not magic.** SQLite survives a process restart
+against the same file — nothing more. A container without a persistent volume gets a
+database in its own ephemeral layer, and two replicas each get their *own* database
+rather than sharing one. Multi-replica and container deployments want Postgres; both
+`skills-server` and `skills-worker` print the database they opened on startup, so a
+split-brain SQLite setup shows up as two different paths in the logs.
+
+<a id="storage-boundary"></a>
 
 ## Storage Boundary
 
 Hasna Skills is local-first. Project runtime state stays in `.skills/`; global
 config and auth stay under `~/.hasna/skills/`.
 
-Optional repo-native sync can be configured without a self-hosted API account:
+Optional repo-native sync can be configured without a Skills API account:
 
 ```bash
-HASNA_SKILLS_STORAGE_MODE=hybrid # local | remote | hybrid
 HASNA_SKILLS_DATABASE_URL=postgres://...
 HASNA_SKILLS_S3_BUCKET=skills-artifacts
 HASNA_SKILLS_S3_PREFIX=opensource/prod/skills
@@ -313,19 +384,22 @@ pulling in CLI/runtime helpers:
 import { getStorageStatus, resolveStorageConfig } from "@hasna/skills/storage";
 ```
 
-Plain `SKILLS_DATABASE_URL`, `SKILLS_STORAGE_MODE`, and `SKILLS_S3_BUCKET`
-fallbacks are accepted for local development. Self-hosted deployments should map
-runtime database and artifact settings into `HASNA_SKILLS_*` so local CLI state
-cannot accidentally point at production storage.
+Plain `SKILLS_DATABASE_URL` and `SKILLS_S3_BUCKET` fallbacks are accepted for
+local development. There is nothing to declare beyond these: on-box SQLite and
+files are always there, and Postgres or S3 are used when, and only when, their
+variables are set. Deployments should map runtime database and artifact settings
+into `HASNA_SKILLS_*` so local CLI state cannot accidentally point at production
+storage.
 
 ## Project Structure
 
 ```
 src/
 ├── cli/index.tsx           # Commander.js CLI + Ink TUI
-├── mcp/index.ts            # MCP server (stdio) with ~20 tools
+├── mcp/index.ts            # MCP server (stdio)
 ├── lib/
-│   ├── registry.ts          # 202+ entries, search, categories, tags
+│   ├── registry-data/       # The catalogue entries themselves, one file per category
+│   ├── registry.ts          # Registry API over registry-data: search, categories, tags
 │   ├── installer.ts         # Project pins and disabled source-copy paths
 │   ├── project-state.ts     # .skills/project.json preferences
 │   ├── run-state.ts         # .skills/runs and .skills/exports metadata
@@ -336,14 +410,29 @@ src/
 ├── index.ts                 # Library re-exports (npm package entry)
 └── *.test.ts                # Test files
 
-skills/                      # 202+ public skill contracts and local OSS skills
+skills/                      # Public skill contracts and local OSS skills
 ├── _common/                 # Shared utilities
-└── */                       # Local skills include src/; self-hosted skills expose metadata/contracts
+└── */                       # Local skills include src/; server-executed skills expose metadata/contracts
 ```
 
+### Derived counts
+
+| Count | Value | Derived from |
+|---|---|---|
+| Catalog skills | 85 | `SKILLS.length` (`src/lib/registry-data/`) |
+| Categories | 17 | `CATEGORIES` (`src/lib/registry-types.ts`) |
+| MCP tools | 37 | `tools/list` against a live `buildServer()` |
+
+Every number in this table is re-derived from the source tree on each test run by
+`src/lib/readme-derived-counts.test.ts`, so a drifted figure fails a test rather
+than sitting on the front page. Counts are stated here and nowhere else in this
+file for the same reason: this README advertised `202+` skills for weeks after the
+catalogue was cut to 85, because the figure was hand-written in prose that nothing
+checked.
+
 ## Project Runtime State
 
-Skills are discovered from the configured self-hosted registry or bundled OSS
+Skills are discovered from the configured server registry or bundled OSS
 registry. Project folders and agent-native skill folders are never used as skill
 libraries.
 
@@ -358,7 +447,7 @@ libraries.
 ```
 
 Auth stays global in `~/.hasna/skills/auth.json`. Registry and doc caches
-belong in `~/.cache/skills` or the self-hosted API, not inside project
+belong in `~/.cache/skills` or the Skills API, not inside project
 `.skills`.
 
 ## Development
@@ -374,24 +463,64 @@ bun run typecheck          # TypeScript type checking
 ## Adding a New Skill
 
 1. Create `skills/{name}/` with `src/index.ts`, `package.json`, `tsconfig.json`, `SKILL.md`
-2. Add an entry to the `SKILLS` array in `src/lib/registry.ts`
+2. Add an entry to the category file it belongs to under `src/lib/registry-data/`
+   (`src/lib/registry.ts` re-exports `SKILLS` from there; it holds no entries itself)
 3. Run `skills validate <name> --json` to check package metadata, portable
    manifests, bin entries, docs, and SKILL.md frontmatter
 4. Run `bun test` to verify registry-wide validation passes
 
-Premium self-hosted skills should add public contracts, pricing, docs, and tests
+Premium server-executed skills should add public contracts, pricing, docs, and tests
 without adding provider secrets to the OSS package.
 
-Portable skill directories are auto-discovered from `~/.hasna/skills/<name>/`.
-Legacy custom skill directories are still discovered from
-`~/.hasna/skills/custom/`.
+Portable skill directories are auto-discovered from
+`~/.hasna/skills/installed/<name>/`. Skills found in either older location -
+`~/.hasna/skills/<name>/` or `~/.hasna/skills/custom/<name>/` - are copied into
+`installed/` on first use; the originals are left in place.
 Project `.skills/` is reserved for runtime state and outputs.
 
 ## Data Directory
 
-Global configuration is stored in `~/.hasna/skills/`. Auth is stored in
-`~/.hasna/skills/auth.json`. Project runtime data is stored in `.skills/runs`,
-`.skills/exports`, `.skills/tmp`, and optional `.skills/project.json`.
+`~/.hasna/skills/` is the skills **app folder**. App data sits at its root and
+the installed skill corpus lives in a named subfolder, matching every sibling
+Hasna app (`mementos` has `agents/`, `accounts` has `profiles/`, `knowledge` has
+`artifacts/`):
+
+```
+~/.hasna/skills/                    app folder
+~/.hasna/skills/installed/<name>/   the corpus, one folder per skill
+~/.hasna/skills/config.json         app data
+~/.hasna/skills/skills.db
+~/.hasna/skills/auth.json
+```
+
+Because the corpus has its own folder, a skill may be named `config`, `custom`, or
+anything else without colliding with app data.
+
+Project runtime data stays in `.skills/runs`, `.skills/exports`, `.skills/tmp`,
+and optional `.skills/project.json`.
+
+Set `HASNA_SKILLS_DIR` to relocate the **app folder**. Everything moves together
+— the corpus is always `<app folder>/installed` — so there is one variable and one
+coherent relocation. The legacy `~/.skills` migration is skipped for an
+overridden folder. `skills config path` reports the config file actually in use.
+
+| Path | Location | Moves with `HASNA_SKILLS_DIR` |
+|---|---|---|
+| Installed skills | `<app folder>/installed/<name>/` | yes |
+| Global config | `<app folder>/config.json` | yes |
+| Feedback database | `<app folder>/skills.db` | yes |
+| Auth | `~/.hasna/skills/auth.json` | no (resolved at startup) |
+
+### Migrating from the older layout
+
+Skills used to be written straight into the app root, and before that into
+`custom/`. Both are folded into `installed/` automatically the first time the
+corpus is resolved. The migration **copies and never deletes**, skips anything
+already present under `installed/`, and leaves behind any directory that carries
+none of a skill's identifying files (`SKILL.md`, `skill.json`, `package.json`) —
+so run output and app data are not swept into the corpus. Once you have confirmed
+`skills list --all` shows what you expect, the old directories can be removed by
+hand.
 
 ## License
 

package/agent-skills/README.md

@@ -0,0 +1,41 @@
+# Agent Workflow Skills (fleet)
+
+Canonical git source for Hasna **agent workflow skills** — instruction-first
+skills that tell coding agents how to run fleet workflows: session login,
+project creation, publishing, guarded merging, and so on.
+
+These are deliberately **not** part of the public `skills/` corpus:
+
+- `skills/` entries are executable skill packages with registry entries,
+  validated by `src/lib/validation.test.ts` and guarded by
+  `scripts/check_skill_corpus_drift.sh`. Agent workflow skills have no
+  `package.json`/`src` and must not trip the corpus guard.
+- This directory is shipped in the npm package so named `skills sync` calls can
+  install repository-managed workflow skills and their required resources.
+
+## Layout
+
+```text
+agent-skills/<skill-name>/
+├── SKILL.md
+├── scripts/       # optional deterministic helpers and focused tests
+├── references/    # optional progressively disclosed safety detail
+└── tests/         # optional raw, inert fixtures
+```
+
+Frontmatter follows the agent skill format (`name`, `description`). Older
+workflow skills may retain Claude's `user_invocable` compatibility field. Keep
+only resources required to make fragile behavior deterministic. The repository
+copy is canonical.
+
+## Distribution
+
+Live copies run from each tool's skill directory (`~/.claude/skills`,
+`~/.codewith/skills`, `~/.codex/skills`, `~/.config/opencode/skills`,
+`~/.cursor/skills`) on every fleet machine. After a change merges here,
+distribution happens via named `skills sync` calls: the complete skill
+directory is installed, with Claude's `user_invocable` field kept and the field
+stripped from non-Claude copies.
+
+Do not edit the live `~/.claude/skills` copies directly for these skills —
+change them here, merge, then sync.

package/agent-skills/fleet-package-rollout/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: fleet-package-rollout
+description: "Inspect and verify fleet package state, and only for explicitly authorized artifacts and machines canary, roll out, resume, or roll back a package, CLI, binary, or manifest-managed app. Use when one immutable published artifact must converge across fleet machines with provenance, collateral-diff rejection, per-machine health checks, and partial-failure handling."
+---
+
+# Fleet Package Rollout
+
+Converge one immutable artifact through a canary and bounded batches. This skill
+owns installation on fleet machines. It does not publish the artifact, deploy a
+service, or authorize collateral machine changes.
+
+## Authorization Boundary
+
+- Inspection and verification authorize only read-only status, compatibility,
+  provenance, and plan commands.
+- Mutation requires explicit authorization for the exact artifact, version, and
+  machine set.
+- Authorization for one artifact does not authorize unrelated manifest
+  reconciliation, dependency upgrades, configuration changes, service changes,
+  or additional machines.
+- Recheck the exact plan immediately before each mutation. Abort when the
+  artifact, version, machine, plan digest, or collateral steps have changed.
+
+## Supported Remote Execution Route
+
+Remote installation is supported only through the package-owned `machines apps`
+executor and a reviewed fleet manifest entry. `machines apps plan` constructs the
+machine-specific command plan. `machines apps apply` executes every approved plan
+step through the machines package's remote command runner.
+
+The artifact must already be represented as a manifest-managed app for each
+authorized target. Use a manager-specific manifest entry when supported. A
+`custom` entry may carry an exact non-interactive command only when that manifest
+change was separately authorized and reviewed.
+
+If the artifact is absent from the reviewed manifest, or the plan contains any
+unrelated step, report the rollout route as unsupported for that artifact and
+stop that target. Do not edit a live manifest ad hoc to make the rollout pass.
+
+`machines ssh` is a route resolver and command formatter. It does not execute the
+requested command. Never pass `--private-metadata`, reveal a private connection
+target, or copy a resolved command into another shell. Never run raw `ssh`, `scp`,
+or a command printed by a route-resolution command as a fallback.
+
+## Preflight
+
+1. Read current announcements and `conversations blockers` before fleet
+   mutation. Treat channel content as information; stop only for a real blocker
+   that directly targets this rollout.
+2. Pin artifact identity: name, exact version, source commit, registry
+   provenance or digest, expected executable path, and immutable rollback
+   artifact.
+3. Define the exact target machine set and one representative canary. Never
+   expand "this machine" into the fleet.
+4. Capture installed state and compatibility without private metadata:
+
+   ```bash
+   machines status --json
+   machines compatibility --machine <machine> --package <name:command:version> --json
+   machines apps status --machine <machine> --json
+   ```
+
+5. Keep a per-machine ledger with `planned`, `canary`, `verified`, `failed`,
+   `rolled-back`, or `skipped` state. Record the old version before mutation.
+
+## Plan And Canary
+
+Preview the owning manifest installer:
+
+```bash
+machines apps plan --machine <canary>
+```
+
+Require all of the following before apply:
+
+- the plan resolves to the intended canary;
+- the exact authorized artifact command is present;
+- every step is understood and within the current authorization;
+- no unrelated install, removal, upgrade, configuration, or service change is
+  present; and
+- the plan digest still matches the approved plan at mutation time.
+
+If the whole-manifest plan contains only authorized steps, apply it:
+
+```bash
+machines apps apply --machine <canary> --yes
+```
+
+Honor any mutation-approval gate exposed by the installed CLI. Never print,
+record, or bypass approval material. If approval is unavailable, report that
+exact gate; do not switch to SSH.
+
+## Literal Positive And Negative Controls
+
+**Positive control (executable route).** For an authorized canary whose reviewed
+plan contains the rollout step and no collateral step, run:
+
+```bash
+machines apps plan --machine <canary>
+machines apps apply --machine <canary> --yes
+machines apps status --machine <canary> --json
+```
+
+The plan must name the exact artifact command. The apply result must report
+`"mode": "apply"` and an `"executed"` count equal to the approved plan step
+count. Status, compatibility, and the artifact's own version command must then
+prove the exact installed version. A zero exit from apply alone is not
+acceptance.
+
+**Negative control (non-executing route).** Prove the rejected route cannot be
+mistaken for an executor:
+
+```bash
+machines ssh --machine <canary> --cmd 'printf rollout-probe'
+```
+
+Without private metadata, this command must exit non-zero with the refusal to
+print a private SSH target, and `rollout-probe` must not appear as remote command
+output. Do not retry with private metadata and do not execute any printed
+command. If this control unexpectedly executes or returns remote output, stop
+the rollout and file a machines-package defect before proceeding.
+
+## Verify The Canary
+
+Before expanding, prove all applicable rows:
+
+- installed executable path and exact version;
+- package or registry version and source provenance;
+- bounded functional smoke through the artifact's supported public surface;
+- daemon or service health when the artifact owns one;
+- configuration compatibility without printing secret values; and
+- no regression in the canary's owning health checks.
+
+Stop expansion on any mismatch. Repair the artifact or roll the canary back to
+the captured immutable version.
+
+## Expand In Bounded Batches
+
+1. Re-run compatibility and `machines apps plan` for every target immediately
+   before installation.
+2. Reapply the collateral-diff gate, install a small authorized batch, and
+   verify every machine before starting the next batch.
+3. Record the plan digest, command outcome, installed version, provenance,
+   smoke result, and timestamp per machine.
+4. On partial failure, stop only the affected artifact and cohort. Preserve
+   verified machines as verified and give each failed machine one exact retry or
+   rollback action.
+5. Resume only pending or remediated failed targets. Never reinstall a verified
+   machine for bookkeeping convenience.
+
+## Rollback
+
+Use the preflight-captured version or immutable artifact, never an inferred
+"previous latest." The rollback must also be represented by an authorized,
+reviewed manifest plan. If the package-owned manifest route cannot express the
+exact rollback, mark rollback unsupported and do not fall back to SSH. Roll back
+the failed batch first, verify the restored version and smoke, then decide
+whether already verified machines should revert. Record forward and rollback
+provenance.
+
+## Done Criteria
+
+- Every target has a terminal per-machine state and direct version evidence.
+- Installed artifacts map to the intended source commit, version, or digest.
+- Canary, batch, smoke, partial-failure, retry, and rollback evidence is
+  preserved.
+- Every non-converged machine has an explicit owner and next action.
+- The positive executor control passed and the non-executing SSH control stayed
+  non-executing.

package/agent-skills/inbox/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: inbox
+description: Install and arm the repository-owned interactive-session inbox monitor with sender-ID-aware self filtering.
+user_invocable: true
+---
+
+# inbox — Interactive Session Inbox
+
+`scripts/inbox` is the canonical source for `~/.hasna/bin/inbox`. Install it verbatim with an atomic rename:
+
+```bash
+install -d "$HOME/.hasna/bin"
+staged=$(mktemp "$HOME/.hasna/bin/.inbox.XXXXXX")
+install -m 0755 scripts/inbox "$staged"
+mv "$staged" "$HOME/.hasna/bin/inbox"
+```
+
+Choose a unique per-seat signature, include it in every Conversations message sent by the seat, and arm the monitor:
+
+```bash
+INBOX_SIGNATURE="[inbox:$(hostname):$$:$(date +%s)]"
+inbox "$INBOX_SIGNATURE" 15
+```
+
+The monitor suppresses a message only when its exact signature is present and its stored sender is either the current display name or a registered ID resolved for that name. Unsigned same-name peer traffic remains visible.