# Changelog

All notable changes to skillhook, newest first. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org). Describe changes under **Unreleased** as they land; `pnpm run release <patch|minor|major>` moves them under a new version, and the Release and Publish workflows tag it, publish it to npm and turn the section into the GitHub release notes.

## Unreleased

## 0.18.0 (2026-11-19)

- **Close a job that waits for a person** without answering it: `skillhook jobs close <id> [--reason TEXT] [--by NAME]`, `POST /jobs/<id>/close`, the MCP tool `close_job` and the cloud control command `job.close {id, reason?, by?}`. For a question that went stale or a finding that cleared by itself: nothing is delivered, no agent resumes, and the job records `closed: {at, by?, reason?}`, leaves `jobs list --waiting` and the waiting count, and reaches Skillhook Cloud in `job.updated` (`fields: ["closed"]`), so it leaves the inbox there too. Until now such a job waited until someone answered it. A job still running is answered or cancelled instead. The cloud must send `job.close` only to machines on 0.18.0 or later.
- The cloud snapshot (`SnapshotSchema`) keeps fields it does not know instead of refusing them, like every other record the cloud stores as JSON. A cloud built on 0.16.0 refused every sync from 0.17.0 machines for about two hours, because 0.17.0 added `managed` to the snapshot. From this version, a field that a later release adds no longer breaks a cloud that has not upgraded yet.

## 0.17.0 (2026-11-18)

- Every skill carries a **definition hash**: the SHA-256 of the files that define it (the SKILL.md directory, or a hook's block of `skillhook.yaml` and the SKILL.md it names), the same for the same files on every machine. `GET /skills`, `skillhook skills list --json` and the cloud snapshot carry it as `definition: {sha256, kind, bytes, files}`, `skills show` prints it, and `skill.changed` says `definition_sha256`. Skillhook Cloud keeps a copy of every skill keyed by it, so the dashboard shows and diffs skills from its own database: it asks for the text it lacks with the new read command `definitions.get` (up to twenty hashes), and `skill.get` answers with the whole definition. `cloud.upload_definitions: false` keeps the text on the machine (the hashes still travel).
- **Cloud-managed skills**: with `cloud.managed_skills: true` (and control mode, or `skills.sync` allowed) a machine serves the skills Skillhook Cloud assigns to it from `<home>/cloud-skills`, pulled on connect, at every snapshot interval and on the new control command `skills.sync`, and checked against the cloud right before each run (one conditional request: the definition the cloud holds at that moment is what runs; a changed admission rule fails the webhook job so the sender verifies again; an unreachable cloud runs the copy on disk and records `definition_fresh: false`, or fails the job with `cloud.require_fresh_definitions`). `skill.adopt` turns a skill of `<home>/skills` into a cloud-managed one once the cloud mirrored it. Every definition is checked (hashes, digest, a parsing SKILL.md, no dotfiles, `auth: none` only with a person's consent) before a file is written; a local skill or a linked repository's hook of the same name wins and is reported as shadowing. The job record and the run's `SKILLHOOK_DEFINITION` name the definition that ran; the event `skills.synced` reports every reconciliation. Off by default. See [docs/cloud.md](docs/cloud.md#cloud-managed-skills).
- `skillhook.yaml` can declare the skills the repository owns: a top-level `skills:` map from skill name to its SKILL.md directory (`issue-triage: .claude/skills/issue-triage`, or `{ path: … }`), and a hook refers to one as `skill: "@issue-triage"` instead of a path (a path still works). Every declared skill is checked on load, used by a hook or not, and reported as `@name` when it is missing, invalid or named otherwise; a hook that names an undeclared skill is an error listing what is declared. `skillhook projects` shows the declared skills with the hooks that use each, a hook's `source.skill` carries the declared name, and the `company` template and the starter file use the form. The list is the repository's inventory of skills, what it publishes to Skillhook Cloud.
- `skillhook projects init --template company` writes a whole operating loop into a repository instead of the one-hook starter: `<project>-task` (a GitHub issue labelled `agent` becomes a pull request), `<project>-incident` (a Sentry alert becomes a root-cause fix or a precise escalation), `<project>-daily` (a scheduled review that finishes unfinished agent work, reports and proposes next steps) and `<project>-health` (a shell probe every 15 minutes), with their skills in `.claude/skills/` and `company-rules.md`, the one file that says what agents decide alone and what needs a person. Agents open pull requests and never merge by default. Existing files are kept unless `--force`.
- A skill can carry its own MCP servers: `skillhook.claude.mcp_servers` (name → `{ command, args, env }` or `{ url, headers }`, Claude Code's own shape) are added to the run next to the job API with their tools allowed, and `claude.strict_mcp: true` gives the run only those servers instead of whatever the machine's Claude Code has configured. `${NAME}` in a server's strings is filled by Claude Code from the run's environment; skillhook forwards the names the servers refer to from `.env`, so a token is never in the skill file, the command line or a job file, and a credential header with the value pasted in is refused. `doctor` reports a referenced name that is not set. Claude runner only.
- `skillhook link` takes a remote: `skillhook link github:you/your-repo` (or an `https://`, `ssh://` or `file://` URL, or `git@host:you/your-repo.git`) clones the repository into `<home>/repos/<owner>/<repo>`, links it and adds it to `project_refresh`, so a server or container that nobody set up by hand serves a repository's hooks from the newest `origin/main`. `--into DIR` chooses the directory and `--no-refresh` leaves the checkout alone. Git authenticates with what the machine has (`gh auth setup-git`, a credential helper, an SSH key); skillhook holds no repository credential and refuses a URL that carries one. Only the command clones, never the server.
- A container image: `ghcr.io/meterapp/skillhook` is the server with Claude Code, Codex, `git` and `gh`, running as an unprivileged user with everything that must survive a restart on one volume (`/data`). The first start runs `skillhook init`, keeps a subscription token given as `CLAUDE_CODE_OAUTH_TOKEN` in `.env`, pairs with Skillhook Cloud when `SKILLHOOK_CLOUD_CODE` holds a code, and serves on every interface of the container. `docker/compose.yaml` runs it with Compose, and the Publish workflow pushes the image for each release. In the image `doctor` skips the service and Tailscale checks instead of warning about them. See [docs/docker.md](docs/docker.md).
- A webhook that arrives while the disk is full is no longer lost. The server wrote the job, remembered the delivery for de-duplication and only then queued the job, so when saving the de-dupe index failed with `ENOSPC` the request answered 500, the job stayed `queued` without ever running, and the sender's retry was answered as a duplicate of it. The job is now queued before its delivery is remembered, and a failure to save the index is logged as a warning instead of failing the request (the retry is still recognised in memory).
- A scheduled run that falls due while the disk is full is no longer lost. The scheduler remembered the slot for de-duplication before queueing its job, so when saving the de-dupe index failed with `ENOSPC` the tick failed, the job stayed `queued` without ever running, and every later tick skipped the slot as already fired. The job is now queued first, and a failure to save the index is logged as a warning (`could not save the delivery de-dupe index; the job is queued`).
- An automatic update no longer bricks the server when the new version rejects the current `skillhook.json`. Before restarting onto a newer version on disk, the server runs that version's `config show --json` against its home. If the new version rejects the config, the server logs `newer version installed but it rejects the current config; keeping this version running` with the error, keeps running, and checks again every minute, so fixing `skillhook.json` lets the restart go ahead. If the check cannot run (it times out, or node is missing), the server restarts as before. On 2026-11-12, 0.16.0 rejected `accounts.*.usage_login` keys that 0.15.2 had accepted. launchd then restarted the daemon 128 times, and it ran no jobs for 17 minutes.

## 0.16.0 (2026-11-10)

- A schedule can be paused without editing the file that declares it: `skillhook schedules pause <name> [--reason …] [--until 2h|<ISO>]` and `schedules resume <name>`, `POST /schedules/<name>/pause` and `/resume` (admin), and the cloud commands `schedule.pause` / `schedule.resume`. While paused nothing fires (the webhook still works); slots that pass are counted as skipped and never caught up. The pause lives in `jobs/.schedules.json`, so a repository pull or a restart keeps it, and `--until` ends it by itself. `schedules list`, `GET /health` and the cloud snapshot show `paused: {at, by, reason, until}`. This lets a repository's `skillhook.yaml` stay the source of truth for schedules while a person can still switch one off from Skillhook Cloud.
- The `service` health check now says how the server runs and whether systemd keeps it running after logout. Its details carry `run_mode` (`service`, `foreground` or `unknown`) and, on systemd, `linger` (`yes`, `no` or `unknown`, read-only from `loginctl`). A systemd service with lingering off is a `warn` with the `loginctl enable-linger` fix. Both reach Skillhook Cloud in the health report, so a machine that goes offline at logout or when its terminal closes can be told apart from one that was stopped on purpose. `service install` on Linux warns when lingering is off, and skips the tip when it is already on.
- A full disk no longer restarts the server. Recording a running job's pid or session id, and writing its stdout/stderr files, happened in child-process handlers outside any `try`, so `ENOSPC` reached the uncaught-exception handler: on 2026-11-11 one machine restarted 18 times in about two hours and every restart interrupted the jobs it was running. Those failures are now logged (`could not record job state`, `could not write job output`) and the job runs on.
- The published plugin mirror (`MeterApp/skillhook-plugins`, what Anthropic's plugin directory installs) no longer carries local MCP servers, a launcher script or a lockfile: the directory refuses those from organizations that are not Verified. It now has the skills and the hosted Skillhook Cloud server, which the host signs in to with the browser. This repository's own marketplace (`/plugin marketplace add MeterApp/skillhook`) keeps both local servers, and `skillhook mcp --print-config` adds the local one to any host.
- New `runners.claude.auth` (`auto`, `login`, `api_key`) chooses whether Claude Code runs and readiness checks use an API key or the subscription login, instead of whichever the environment happens to hold. `auto` (the default) behaves as before. `login` removes `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` and `CLAUDE_CODE_OAUTH_TOKEN` from Claude Code runs and probes, so readiness reflects the login in `CLAUDE_CONFIG_DIR` / `~/.claude`. `api_key` counts the runner as ready only with a key and keeps the key for skills with their own `claude.config_dir`. Named accounts keep their own credential either way. `skillhook health` reports by the same rule. Changing it is answered by a fresh readiness probe at once.
- The test suite no longer depends on the developer's shell: runner credentials (`ANTHROPIC_*`, `OPENAI_*`, `CODEX_*`, `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_OAUTH_TOKEN`) are cleared before every test file, so `pnpm test` passes inside a Claude Code session too.
- A Claude Code login whose token can no longer be refreshed is no longer reported as ready. `claude auth status` only reads the stored credentials and says "logged in" for such a token, so jobs passed the readiness check, failed with `401 OAuth access token has expired` and silently ran on their `fallback:` runner. Readiness (`skillhook runners`, `GET /runners`, the job pre-flight, account readiness) and the `claude` health rows now try the login through Claude Code's control protocol (no prompt) and report `expired: true` with `login expired: Claude Code could not use or refresh the stored token`.
- A `claude fallbacks` health check fails while jobs fall back from Claude Code because its login failed, and clears once Claude Code runs a job again. Skillhook Cloud raises a `health_failing` alert on it; a paired machine now sends a fresh health report at its next sync when a job falls back that way or a runner or account becomes usable or unusable, instead of waiting for `cloud.health_interval_seconds`.

## 0.15.2 (2026-11-05)

- The published plugin (Anthropic's plugin directory and `MeterApp/skillhook-plugins`) no longer starts its MCP servers with `npx` in Claude Code. It ships a `package.json` and a `package-lock.json` that pin this `@meterapp/skillhook` release and the runtime dependencies CI tested, with registry sources and integrity hashes; Claude Code installs them into the plugin when it installs or updates it, and `.mcp.json` starts `node server/skillhook.mjs mcp` (and `mcp --cloud`) on that copy. This answers the directory's `LAUNCHER_LOCK_MISSING` warnings. Codex and Cursor, which install no lockfile, keep the pinned `npx` launchers (`.mcp.npx.json` in the mirror), and so does this repository's own marketplace. The CLI itself is unchanged.

## 0.15.1 (2026-11-05)

- The Claude Code, Codex and Cursor plugin moved into its own folder, `plugins/skillhook/`, with its own README that states what the plugin runs and sends and how sign-in works. Anthropic's plugin directory reads every file in a plugin's folder and held the plugin (`MCP_FORWARDS_CREDENTIAL_ENV`) because the repository's docs, examples and tests show credentials being read; they are no longer part of the plugin. Install commands are unchanged (`/plugin marketplace add MeterApp/skillhook`, `/plugin install skillhook@meterapp-skillhook`, `npx skills add MeterApp/skillhook`). `pnpm run release --check` now also fails on any credential-read pattern, `.env` path or env-var wording in `plugins/skillhook/`, and on a `userConfig`, `env` block or header in its manifests. The plugin's skills describe secrets as saved with `skillhook secret set`. The CLI itself is unchanged.

## 0.15.0 (2026-11-04)

- Account pools spread their jobs instead of draining the first account until it hits a limit mid-session. `account_policy.strategy` now defaults to `balanced`. It picks the account running the fewest jobs, then the least used (in 25-point bands), then the one picked longest ago, so with no usage known it is a round robin. Set `ordered` to keep the first account as the primary and the others as backups. A new `account_policy.usage_avoid_percent` (default 90) moves an account with a 5-hour or weekly window at or above it behind every account with more left, whichever strategy is set. A window whose reset time has passed counts as empty again: in the pool's order and in the `usage_high` warning. Picks happen one at a time and reserve the account at once (`last_picked_at` in `jobs/.accounts.json`), so jobs that start together no longer all land on the same account.

## 0.14.7 (2026-11-03)

- `package.json` declares `mcpName` (`dev.skillhook/skillhook`) so the stdio MCP server (`skillhook mcp`) can be listed on the official MCP Registry.

## 0.14.6 (2026-10-29)

- Preserve an answered job while its session resume is queued or running. At the retention limit, creating a resume could prune its original before recording the resume link, fail the answer with “Unknown job”, and leave the resume unqueued.

## 0.14.5 (2026-10-29)

- Health checks ignore Claude configuration directories that a shell/Codex runner or a named account pool does not use, and skip the unnamed login and MCP servers when all enabled Claude skills use accounts or explicit profiles. Credential-free webhook warnings describe the configured IP allowlist instead of claiming any caller can trigger a localhost-only hook.
- Classify Codex's explicit "Selected model is at capacity" provider failure as a retryable rate limit even when unrelated MCP stderr mentions OAuth. Genuine primary authentication failures keep their authentication classification.

- A hung runner probe no longer stops the queue. On 2026-10-27 a macOS keychain dialog left every `claude auth status` the daemon started blocked for ten hours; Claude Code's binary ignores the SIGTERM `execFile` sends on timeout, so the probe never ended, the one shared readiness promise never settled and every Claude Code job waited on it. Probes are now killed with SIGKILL when they time out (`timedOut` is reported either way, and a probe whose output stays open is given up on after a grace period), the readiness cache gives up on a probe after the longest a check legitimately takes (`health.probe_timeout_seconds` plus the quick calls and a margin: 55 s by default) and lets the next caller probe afresh, and a login check that got no answer is "could not tell" rather than "not logged in": the queue runs the job on its runner anyway (`readiness check failed; running anyway`) instead of failing it or sending it to the `fallback:` runner.
- Version and login probes (`claude --version`, `claude auth status`, `codex login status`, the control-protocol login try) run with only PATH, the session basics and the runner's own variables (`ANTHROPIC_*`, `CLAUDE_*`, `OPENAI_*`, `CODEX_*`, proxies and certificates) rather than the whole job environment, so nothing else from `.env` shows up in `ps` for a mere version check.

## 0.14.4 (2026-10-28)

- Keep human-answer session resumes on their original Claude or Codex account, including legacy jobs matched to registered login directories. A missing or unavailable profile fails safely with the answer retained; session resumes never fail over to another account or runner. Fresh jobs keep the configured pool and fallback behavior.

- Links to Skillhook Cloud in the README, docs, `llms.txt`, the plugin's skills and manifest, and the CLI's output carry a `?ref=` slug (`readme`, `skillhook-docs`, `plugin`, `cli`), so the cloud can tell which of them brought a new account; the slugs are registered in Skillhook Cloud's `lib/attribution/sources.ts`. Base URLs (`--url`, `cloud.url`, API and MCP endpoints) are unchanged.

## 0.14.3 (2026-10-28)

- Bound runner and tool probes with a forced timeout so a CLI that ignores SIGTERM cannot hold queue slots indefinitely.

## 0.14.2 (2026-10-26)

- Use the Sentry-compatible `skillhook-daemon@<version>` release name. Scoped npm package names contain a slash, which Sentry discards from accepted events.

## 0.14.1 (2026-10-26)

- Opt-in Sentry reporting for unexpected daemon errors and fatal exceptions, with bounded delivery and private, static error context. `skillhook sentry status|test` checks the running daemon and sends an authenticated verification event; Sentry settings stay out of runner environments and remote credential controls.

## 0.14.0 (2026-10-25)

- Respect Codex turn completion after recovered reconnect errors, preserving terminal failures and raw diagnostics.
- Update Zod to the patched 4.6 line for GHSA-mrhx-c7xc-m3w5.

- Each account's own MCP servers, connectors and plugins: `skillhook accounts show <name> --mcp` lists them with whether each connected, needs authentication or failed (and why), with tool counts, from the account's own CLI and environment: Claude Code's `mcp_status` control request (claude.ai connectors and plugins' servers included) and Codex's `mcpServerStatus/list` merged with `codex mcp list --json`. `accounts --mcp` adds a `7/9` column, `accounts check --mcp` fails on a server that needs authentication or fails, `GET /accounts?mcp=1` and MCP `list_accounts {mcp: true}` return them, and the attention items `mcp_needs_auth`, `mcp_failed` and `mcp_missing` (servers the machine's own login has that the account lacks) carry the command that fixes each, run as the account. `skillhook health` (deep) has an `account <name> mcp <server>` row per server. Headers and environment values from the CLIs' answers are never kept.

- Several Claude Code and Codex logins on one machine: `skillhook accounts` ([docs/accounts.md](docs/accounts.md)). An account is a configuration directory of its own (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`, under `~/.skillhook/accounts/<name>`; a Codex account links the machine's Codex settings except `auth.json`), a long-lived `claude setup-token` token or an API key. `accounts add|login|logout|default|enable|disable|reset|discover|sync|exec|remove` manage them; `accounts`, `accounts show` and `accounts usage` show for each who it is logged in as, its plan, its usage windows (5h, weekly, per model, credits; read through the CLI's own control protocol and `codex app-server`, never with a token of skillhook's), its last use and its jobs of the last 24 hours, and what needs a person with the command that fixes it (logged out, login expired, usage limit, high usage, a failed login, a duplicate login). `accounts check [--notify]` exits 1 when one needs attention.
- `account:` in a skill or hook (and `defaults.accounts`) runs it as an account, or a pool of accounts: each job runs as the first usable one (`account_policy.strategy: ordered|balanced`), moves to the next when a run fails with a usage limit or a failed login before the agent did anything, and skips a limited account until its limit resets (from the CLI's own notice or message). A run gets only its account's credentials. Jobs record `account` (and each attempt's); `skillhook run --account`, `POST /skills/<name>/run {account}`, `jobs list --account`, `GET /jobs?account=`.
- `GET /accounts`, the MCP tool `list_accounts`, an `account <name>` row per account in `skillhook health`, and the events `account.changed` / `account.updated`. `serve` checks every account at start, reads usage every `account_policy.usage_poll_minutes` when set, and with `account_policy.notify: desktop` shows a notification when an account stops working or recovers. Readiness now tells an expired Claude Code login from none.
- Skillhook Cloud sees account health: a paired machine uploads `account.changed` / `account.updated` (checked once when the link connects) and answers the read command `accounts.get`, through an allow-list: name, runner, kind, status, attention codes, plan, usage windows and reset times, last failure; emails masked to `a…@example.com`, no directories or paths, `.env` values scrubbed ([docs/cloud.md](docs/cloud.md#accounts)).

## 0.13.1 (2026-10-22)

- Ready for Anthropic's plugin directory: the plugin's MCP servers start a pinned `npx -y @meterapp/skillhook@<version>` (the plugin's own release) instead of whatever is latest, and `pnpm run release` bumps and `--check` verifies that pin with `package.json` and the plugin manifests. The Claude Code manifest gains a listing icon, the skillhook.dev homepage and links to Skillhook Cloud's privacy policy and terms; the README gains the one-step `/plugin install skillhook --marketplace MeterApp/skillhook` and a plain account of what the plugin runs and sends. The contributor pointer moved from `CLAUDE.md` to `.claude/CLAUDE.md`.
- Upgrade the MCP server SDK to 2.3.1 to address the SDK request-isolation, validation-memory and bearer-token audience advisories.

## 0.13.0 (2026-10-17)

- The Skillhook feedback board from the terminal: `skillhook feedback list|show|mine|request|report|upvote|comment` and `skillhook review` / `skillhook reviews`, through the cloud's new catalogue tools (which `skillhook mcp --cloud` picks up by itself). `request` and `report` list similar items first (`--force` files anyway); `report --last` attaches the last request the cloud refused from this computer, `--job` / `--delivery` / `--request-id` what it is about, and every report carries the skillhook version and platform.

## 0.12.0 (2026-10-17)

- Skillhook Cloud's plans for agents and people in a terminal: `skillhook pricing [--json]` lists every plan's price, limits, features and checkout link without a key; `skillhook cloud billing [--portal]` shows the organisation's plan, renewal, usage against every limit and what the next plan adds (or Stripe's link to invoices and the card); `skillhook cloud upgrade --plan pro|business [--yearly] [--open]` gives a person the link that buys a plan, with a key (Stripe Checkout for the organisation) or without one (a link that signs them up first). Nothing is charged and no card details are taken. `skillhook mcp --cloud` offers `get_pricing` and `create_checkout_link` before anyone signed in, and requests to the cloud say which front end sent them (`x-skillhook-client`), so its links are attributed to `agent-cli` or `agent-mcp`.

## 0.11.0 (2026-10-17)

- Run each repository's hooks as a different Claude login: `claude.config_dir` on a skill or hook, or a top-level `claude:` block in `skillhook.yaml` for every hook of the file, sets `CLAUDE_CONFIG_DIR` for the run (and drops `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` unless listed in `env:`). Readiness and the `fallback:` decision probe that directory, `skillhook health` shows a `claude <dir>` row per directory with the logged-in account, and `resume_command` resumes with the same directory.

## 0.10.5 (2026-10-16)

- Bound graceful restart attempts without terminating active jobs: keep intake and cloud sync available, resume dispatch on timeout, and drain queued work safely for automatic upgrades. Preserve exact pending dispatch order across graceful exits, including jobs created within the same second.

## 0.10.4 (2026-10-16)

- Keep unanswered questions and unresolved `needs_human` jobs when retention prunes old jobs.
- Publish startup interruptions to lifecycle listeners and replay retained interruptions through the durable cloud outbox after restarts or delayed pairing.

- Keep transient hosted-ingress loopback failures unacknowledged for Cloud's existing bounded redelivery window; deduplicate by the trusted Cloud delivery ID when the sender provides none. Permanent authentication/configuration rejections stay terminal.

- Update the development-only `source-map-js` lockfile entry to 1.2.2 to address the indexed source-map denial-of-service advisory.

## 0.10.3 (2026-10-14)

- Bound decoded Cloud response bodies (4 MiB for machine sync, 64 MiB for other calls), cancel oversized or stalled streams, and normalize/redact body-read errors like connection errors. This hardens transport buffering; it does not establish the cause of the reported native HTTP/2 stall.

## 0.10.2 (2026-10-14)

- Preserve public configuration in cloud uploads through the local `cloud.public_env` declaration, fixing GitHub repository slugs redacted inside job links. Unknown values and credential variables stay private; cloud commands cannot change this policy.

- Reuse identical in-flight replay work in HTTP and cloud recovery; alternate eligible fresh/replay queue slots and serialize shared Git worktrees by default, with `serialize_cwd` overrides for coordinated parallel jobs or non-Git directories.

## 0.10.1 (2026-10-13)

- Fallback targets accept a runner, model and effort. Recognise Claude session/weekly limits and exhausted credits, ignore synthetic API error notices when checking whether fallback is safe, and never revisit a failed runner in the fallback chain.

## 0.10.0 (2026-10-09)

- `skillhook cloud login` signs in with the browser: it shows a code, opens the cloud's sign-in page, and the person
  approves it there (choosing the organisation, where they are an admin or owner, and the access: read, run or
  admin); the cloud makes a new organisation API key for this computer, named `skillhook CLI on <hostname>` under
  Settings → API keys, and hands it to the waiting CLI once. Nobody copies a key out of the dashboard and into a
  terminal any more. `--no-browser` only prints the link; the link and the code go to stderr, so `--json` still
  answers on stdout. `--key shc_…`, `--key -` (stdin) and `--key` alone (asked for at a terminal) keep a key made on
  the dashboard, as before; in CI, where nobody can approve, login says to use them. Needs a Skillhook Cloud with
  browser sign-in (`/api/auth/device/*`, live on https://skillhook.dev); an older one says to use `--key`.
- `skillhook_cloud_setup` of `skillhook mcp --cloud` does the same for an agent: without a working key it opens the
  sign-in page in the person's browser and returns the link and the code to show them, keeps the key once they
  approved and loads the cloud's tools; `wait_seconds` waits for the approval. The key never passes through the
  conversation, and the sign-in goes only to the cloud the key would.
- The messages that sent people to Settings → API keys to make a key first (no key, a refused key, a missing scope)
  say to run `skillhook cloud login` instead.

## 0.9.1 (2026-10-07)

- `skillhook init` names pairing with Skillhook Cloud (https://skillhook.dev) among its next steps, and the `cloud link`
  hint of `skillhook doctor` and `skillhook --help` carry the URL. The README, `docs/`, `llms.txt` and the plugin skills
  point at Skillhook Cloud where it is the hosted alternative: hosted webhook URLs for a machine that sleeps or has no
  public URL, every machine's deliveries and jobs on record with replay, the inbox, alerts, teams, the hosted MCP server
  at https://skillhook.dev/api/mcp, and the plans.

## 0.9.0 (2026-10-07)

- skillhook updates itself. At most once an hour any command (from a person, a script, an agent or an MCP host) starts
  a detached `skillhook update --refresh` when the cached answer is stale; with the new `auto_update` setting (default
  `true`) it installs a newer version with the package manager that installed skillhook: npm into the same global
  prefix, through the npm beside the running Node, or pnpm, bun, yarn or Volta. One install runs at a time
  (`<home>/update.lock`), its output goes to `<home>/logs/update.log`, and a version that failed is tried again after a
  day. No command waits for it and nothing is printed for scripts or agents; at a terminal skillhook says once that it
  updated itself, and mentions a newer version only when it will not install it (`auto_update: false`, a source
  checkout, an npx cache, a project's dependency, a global directory the user cannot write, a failed install).
  Before, the check ran only after interactive commands and installed nothing, so a skillhook only agents used never
  moved.
- `skillhook serve` checks hourly (was daily), starts the background install, and restarts itself onto a newer
  installed version once no job is queued or running when launchd or systemd runs it, whoever installed it (the
  background update, `update --install`, the cloud's `update.install` or npm). `skillhook serve` run by hand only logs
  that a restart would pick it up.
- `skillhook update --install` also brings the skillhook plugin up to date wherever it is installed: `claude plugin
  marketplace update` and `claude plugin update` in Claude Code, `codex plugin marketplace upgrade` in Codex.
  `--no-plugins` skips that.
- An npm upgrade now targets the global prefix this copy runs from (`npm install -g --prefix …`), so a machine with
  several Nodes (nvm, Homebrew) upgrades the copy that runs; `doctor`'s version hint says when the background update
  will install it, or why it did not.

## 0.8.0 (2026-10-07)

- Reports people can act on: a job says what it is about, how far it got, what came of it in one line
  and where to look, and offers choices for a person to pick from. Skillhook Cloud's inbox shows all of
  it, Markdown included.
  - **A title** for the job: `job_progress {title}` / `skillhook job progress --title "…"` (it stays
    until a later report changes it), or `title` in `job_set_outcome` and `response.json`. It becomes
    `job.title`, is in the `?wait=` response and `GET /jobs/<id>/progress`, and a resume job inherits it.
  - **A headline**, the result in one line (at most 280 characters), next to the summary:
    `job_set_outcome {headline}`, `skillhook job outcome --headline`, `headline` in `response.json`.
    It is the last progress message once the outcome is reported.
  - **Typed links**: a link is a URL, as before, or `{url, title, kind}` with `kind` one of `source`
    (what started the run), `pull_request`, `commit`, `issue`, `message`, `document`, `deploy`, `test`
    (how to check the result), `log`, `result` or `other`. On the command line,
    `--link "pull_request:[PR #7](https://…)"` (the kind and the title are optional) and `--links JSON`.
    A misspelled kind is refused instead of ending up inside the URL.
  - **Choices**: questions take `recommended` (the option the agent suggests) and `multiple` (a person
    may pick several; the answer lists them one per line and `answer.options` says which they were, and
    `job_ask_human` / `skillhook job ask` return them as `options`). A `needs_human` outcome can offer
    `options` (with `recommended` and `multiple`) too: a person picks one and the session resumes with it.
    `skillhook jobs answer <id> --option A --option B` and the MCP `answer_job {options}` answer with
    several picks.
  - The guardrails ask every run for a title, a headline and its links, and tell it about choices; the
    default `response.schema` of `response.mode: structured` has the new fields (links as objects).
    `skillhook jobs list|show` print titles, headlines, links and choices.
  - The cloud protocol names the link kinds (`LINK_KINDS`) and the limits of a report (`REPORT_LIMITS`);
    records stay loose, so nothing else about the protocol changes.

## 0.7.1 (2026-10-06)

- Skillhook Cloud's production deployment is the default cloud: `cloud.url` (and so `skillhook cloud
  connect`, `cloud login`, the fleet commands and `skillhook mcp --cloud`) defaults to
  `https://skillhook.dev` instead of the placeholder `https://cloud.skillhook.dev`, where no cloud ever
  answered. A plain `skillhook cloud login` on a machine that names no other cloud logs in there instead
  of refusing without `--url`, and an API key without a cloud of its own (set in the environment alone,
  or kept by 0.6) goes there too. `--url`, `SKILLHOOK_CLOUD_URL` and `cloud.url` still name another
  deployment, and a paired machine keeps the `cloud.url` written at pairing. A key kept at login still
  goes only to the cloud it was checked against, whatever `cloud.url` says later, only over HTTPS, only
  when it looks like an organisation key (`shc_…`) and never under `SKILLHOOK_NO_CLOUD=1`. Since the
  default is now a cloud like any other, a login without `--url` asks which cloud the key is for when
  the one kept here differs from this machine's, Skillhook Cloud's own included.
- Without an API key, the fleet commands, the instructions of `skillhook mcp --cloud` and its
  `skillhook_cloud_setup` tool say where to create one and the command to run, `skillhook cloud login`
  (with `--url` only for a cloud other than Skillhook Cloud's own), instead of
  `--url https://<your cloud>`.

## 0.7.0 (2026-10-02)

- Everything Skillhook Cloud's dashboard shows and does, from the terminal and for an agent, with an
  organisation API key. The cloud publishes its tools (`GET /api/v1/tools`: each with its JSON Schema
  and the scope it needs) and skillhook builds its commands and MCP tools from that list when it runs,
  so a tool the cloud adds works without a new skillhook.
  - `skillhook cloud overview`: what needs a person across the organisation (agents waiting for an
    answer, open alerts, failing health checks, failed jobs and rejected webhooks of the last 24 hours,
    the day's numbers, the next steps).
  - `skillhook cloud tools [tool]` lists the tools the key has (and which a wider key would add) or
    describes one; `skillhook cloud <tool> [args] [--param value]…` runs any of them by name:
    `answer_job`, `replay_job`, `run_skill`, `test_skill`, `save_skill`, `get_job_artifact`,
    `get_stats`, `list_alerts`, `enable_hosted_url`, `send_command`, … The words after the tool's name
    are read with its schema (before it, only skillhook's own options): required parameters as arguments
    in order, typed flags (switches, checked numbers, JSON as a literal, `@file` or `-`,
    `--param-file PATH` for long text, `--input` for the whole input). skillhook's own options (`--json`, `--help`,
    `--version`, `--dir`) mean the same wherever they stand and are never a parameter's value
    (`--answer=--help` sends that text), so `--help` never runs a tool. The answer prints as indented
    text, or as it came with `--json`. Text from the cloud, machines and senders reaches the terminal
    without control characters or bidirectional overrides, error messages included; with `--json` (of
    any command) they are `\u` escapes, the same JSON. A catalogue entry this version cannot read (a
    malformed schema included) is skipped; a newer catalogue shape asks for an update.
  - `skillhook cloud secret <machine> <skill|NAME> [--force]`: the machine generates a skill's secret
    (only a skill's: never its admin token or a runner's key) sealed to a key pair made for this one
    request; only this terminal can open it, the cloud only forwards the sealed value.
  - `skillhook mcp --cloud`, registered by the plugin as the `skillhook-cloud` MCP server: the same
    tools for the agent, the cloud's instructions, and `generate_secret`. Without a key it offers only
    `skillhook_cloud_setup`, which says what is missing and loads the tools once the person logged in;
    the agent never handles the key.
  - `skillhook cloud login [--url URL]` checks the key against the cloud named (else the one logged in to
    before, else the machine's; when those two differ it asks which) and keeps it with that cloud (`SKILLHOOK_CLOUD_API_URL` next to
    `SKILLHOOK_CLOUD_API_KEY` in `.env`): the key goes there and nowhere else, whatever `cloud.url` says
    later, and login never touches the machine's link. The same key set in the environment goes there too.
    A key kept by 0.6 goes to the machine's cloud until the next login. At a terminal login asks for the key
    without echoing it. `cloud status` and the MCP tool `cloud_status` say whether a key is kept and for
    which cloud.
  - The local MCP server refuses `cloud.*` settings in `update_config` and `SKILLHOOK_CLOUD_*` names in
    `set_secret` and `generate_secret`, so its configuration and secret tools do not move the link or the
    API key. An agent that can run commands on the machine still acts with the person's rights.
  - A new plugin skill, `skillhook-cloud`, teaches the agent to triage the organisation (failure kinds,
    rejected deliveries, failing checks), act on it safely and set up machines, skills, secrets and hosted
    URLs.
- With `cloud.upload_payloads` false, or an organisation that keeps no bodies, the cloud's `job.artifact` and
  `job.get` no longer send a job's `payload`, `event` or `prompt` (which quotes the payload): webhook bodies stay
  on the machine, as the docs promised. An agent's own output (its transcript, its result) can still quote what it
  read; `cloud.upload_artifacts: false` keeps transcripts home.
- A skill's `secret_env` can no longer name one of skillhook's own credentials (`SKILLHOOK_ADMIN_TOKEN`,
  `SKILLHOOK_CLOUD_*`): generating or setting the skill's secret would have overwritten it (a cloud link's
  token, where the API key goes). Such a skill is reported invalid. The machine also refuses the cloud's
  `secret.generate` and `secret.set` for these variables by whatever name they come (a skill's or the
  variable's), so the cloud cannot rotate the admin token either.
- `--help` and `-h` never run a command. Most commands used to ignore them and do their work, so
  `skillhook jobs prune --help` pruned jobs and `skillhook service install --help` installed the service
  (0.6.0 fixed only `skillhook cloud`). Now `skillhook <command> [subcommand …] --help`, or
  `skillhook help <command>`, prints that command's usage and exits 0 without touching anything;
  `--json` prints `{ "ok": true, "command": …, "usage": … }`. The check sits in front of every command,
  so a new one cannot forget it. `serve`, `doctor`, `health`, `runners`, `mcp` and `url` gained a usage
  text, and `skillhook job <subcommand> --help` prints the agent's job API or, for the rest, `jobs`.

## 0.6.0 (2026-09-29)

- `skillhook cloud report "<title>"`: a person on a paired machine reports a problem to the Skillhook
  team without leaving the terminal (`--body TEXT`, `--body -` or `--body-file PATH`, `--kind`,
  `--severity`, `--job`, `--delivery`, `--skill`, `--email`). One request, `POST /api/agent/issues`
  with the machine token, carrying the person's text and, unless `--no-diagnostics`, what the machine
  already knows: skillhook, Node, OS and architecture, `cloud.mode`, the link's state, whether each
  runner is ready and the health summary with the failing and warning checks. Every `.env` value is
  scrubbed from all of it, and payloads, logs, prompts and job output never go; `--dry-run` prints the
  exact JSON instead of sending it. It answers `Reported as #N: <url>` and whether a confirmation email
  went out. Each report carries a `report_id` (a UUID) on every attempt: network errors, timeouts and
  5xx are retried (three attempts), a 429 only after a short `retry_after_ms`, another 4xx never, and
  the cloud files a retried report once. The MCP tool `cloud_report_issue` sends the same report for
  an agent the person asked (`dry_run: true` returns it without sending). Refused on a machine that is
  not paired and under `SKILLHOOK_NO_CLOUD=1`.
- The protocol gains the report, additively (`PROTOCOL_VERSION` stays 1): `IssueReportRequestSchema`
  (with `report_id`, a client-generated idempotency key), `IssueReportResponseSchema`,
  `IssueDiagnosticsSchema`, `ISSUE_KINDS`, `ISSUE_SEVERITIES` and `LIMITS.max_issue_report_bytes`
  (64 KiB), documented in [docs/cloud-protocol.md](docs/cloud-protocol.md#issue-reports).
- The organisation's fleet from the CLI with an organisation API key: `skillhook cloud login --key
  shc_…|-` checks the key (`GET /api/v1/me`) and keeps it in `.env` as `SKILLHOOK_CLOUD_API_KEY`
  without ever printing it (the environment variable works too, for CI), `cloud logout` forgets it,
  and `cloud machines`, `cloud jobs [--machine M] [--skill S] [--status ST] [--outcome O] [--waiting]
  [--limit N] [--before C]` and `cloud job <id>` print tables, or the API's JSON with `--json`. The
  machine token is never used for them, so a paired machine cannot read the rest of its organisation.
  A refused key says to log in again, a missing scope names it. A key only goes to a cloud URL someone
  set (pairing, `cloud.url` or `SKILLHOOK_CLOUD_URL`), never to the built-in placeholder, and only if
  it looks like one (`shc_…`, one line).
- The cloud HTTP client reads the public API's RFC 9457 problem answers (`code`, `detail`,
  `request_id`) as well as the agent API's `error` / `message`, refuses a token that is not one line
  of printable characters before it becomes a header, and never lets a token into an error message.
- `skillhook cloud <subcommand> --help` prints the usage instead of running the subcommand.

## 0.5.0 (2026-09-28)

- The cloud link checks the runners as soon as it connects, so the dashboard shows whether `claude` and
  `codex` are installed and signed in before the first job runs (previously only after one).
- MCP tools `cloud_status` and `cloud_disconnect`. There is deliberately no `cloud_connect`: pairing hands
  the machine to an account, so the person runs `skillhook cloud connect --code …` themselves. The setup
  skill gains a Skillhook Cloud step that says so.
- The Skillhook Cloud link, opt-in. `skillhook cloud connect --code XXXX-XXXX [--control]` pairs the
  machine (the token goes to `.env` as `SKILLHOOK_CLOUD_TOKEN`, `cloud.*` to skillhook.json; observe
  mode unless `--control`), `cloud status` and `cloud disconnect` (which revokes the token) complete
  it. The running server then keeps one outbound HTTPS connection to `cloud.url`: it uploads
  deliveries, jobs, progress, schedule, config and health changes (headers redacted, command lines
  dropped, every string scrubbed of every `.env` value; bodies only with `cloud.upload_payloads` and
  at most 256 KiB), snapshots and periodic health reports; runs read commands (health, jobs,
  deliveries, stats, logs, skills) and, in `cloud.mode: control` or when allow-listed, the ones that
  act on the machine (run, test, replay and cancel jobs, answer a job waiting for a person, patch the
  configuration except the bind address, runner commands and the link itself, fire a schedule,
  install an update, restart a service-run server once the cloud has the answer, write or remove
  skills, generate a secret returned only sealed to the requester's key, and, allow-listed only, set a
  secret sealed to the machine's own key); streams a watched job's output (`job.output`) and uploads
  large artifacts in chunks; and replays webhooks that arrived at the machine's hosted
  URLs to the local server, where the signature is checked with the local secret (`via: "ingress"`
  and `ingress_id` on the delivery record). Events wait in `jobs/.cloud/` while the cloud is
  unreachable. `GET /health` (admin) reports the link as `cloud`, and doctor/health gain a
  `cloud link` check. Kill switches: `cloud.enabled: false`, `SKILLHOOK_NO_CLOUD=1`,
  `cloud disconnect`. The settings and the wire protocol, exported as `@meterapp/skillhook/protocol`
  for the cloud to validate against, are documented in [docs/cloud.md](docs/cloud.md) and
  [docs/cloud-protocol.md](docs/cloud-protocol.md). `SKILLHOOK_CLOUD_*` variables never reach a run's
  environment, even when a skill lists them.

## 0.4.0 (2026-09-28)

- An event bus inside `skillhook serve` (`src/events.ts`): the queue publishes `job.queued`,
  `job.started`, `job.updated`, `job.cancelled` and `job.finished`, the scheduler
  `schedule.registered`, `schedule.fired` and `schedule.skipped`, the registry `skill.changed` (a
  `SKILL.md` or `skillhook.yaml` that appeared, changed or disappeared, noticed on the next lookup or
  listing) and the server `server.started` / `server.stopping`. Every event carries a `seq`, a
  timestamp and the full record.
- Two streaming admin routes (server-sent events): `GET /events` (the whole bus, `?types=` to filter)
  and `GET /jobs/<id>/events` (one job: `status` snapshots, `stdout`/`stderr` as they are written,
  `end`). `GET /jobs/<id>/artifacts/<name>` returns one artifact file as-is (`?tail=<bytes>`).
  `skillhook jobs logs <id> -f` follows a running job through the server when one is running.
- Many senders waiting with `?wait=` on the same server no longer trigger Node's
  `MaxListenersExceededWarning`.
- A delivery log. Every request to `/hooks/<skill>` is now recorded in `jobs/.delivery-log/` with its
  outcome (`accepted`, `duplicate`, `in_flight`, `skipped`, `rejected`, `challenge`, `error`), the HTTP
  status and error code the sender got, the reason (the failing `when` condition, the auth error), the
  redacted headers, the client IP and the job it created or was folded into. Refused deliveries keep
  their body (`deliveries.store_bodies`, `deliveries.body_max_bytes`, 64 KiB) so what arrived can be
  inspected and, later, replayed; the newest `deliveries.max` (2000) records are kept. New:
  `skillhook deliveries list|show`, `GET /deliveries` and `GET /deliveries/<id>?include=body`, the MCP
  tools `list_deliveries` and `get_delivery`, `recent_deliveries` in `skillhook_status`, `deliveries`
  in `GET /health` (admin) and the `delivery.received` event.
- `GET /jobs`, `skillhook jobs list` and the MCP tool `list_jobs` page with `after` (`next_after` in
  the response) and filter by `trigger` and `since`; the route caps `limit` at 500 and answers
  `400 bad_request` for an unknown `status` or `trigger`. A malformed skill name in a hook URL is
  `404 unknown_skill` instead of `500`.
- Task outcomes. Every finished job now carries `outcome` (`completed`, `partial`, `needs_human`,
  `nothing_to_do`, `failed`, `unknown`) next to `status`: the agent reports it by writing
  `response.json` (`{outcome, summary, links, data}`) in the job directory (`SKILLHOOK_RESPONSE_PATH`,
  `{{response_path}}`; the guardrails say so), and the report is kept as `job.response`. A new
  `response:` field in the `skillhook:` block chooses how firmly it is asked for: `mode: file` asks for
  the file, `mode: structured` makes the runner answer with JSON (`claude -p --json-schema`,
  `codex exec --output-schema <job dir>/response.schema.json`; the answer is stored as `response.json`
  too), optionally against your own `schema`. A shell command that exits 0 is `completed`; a run that
  reports nothing is `unknown`; every non-succeeded status is `failed`. Surfaces: the `?wait=`
  response (`outcome`, `response`), `GET /jobs?outcome=`, `?include=response`, the `response`
  artifact, `skillhook jobs list --outcome` (new column) and `jobs show --response`, the MCP
  `list_jobs` filter and `skillhook_status`.
- Replay. `skillhook deliveries replay <id>` (`POST /deliveries/<id>/replay`, MCP `replay_delivery`)
  runs a recorded delivery again through the skill as it is now, and `skillhook jobs replay <id>`
  (`POST /jobs/<id>/replay`, MCP `replay_job`) does the same for any earlier job: a new job with
  `trigger: replay`, `source.method: REPLAY` and `replay_of: {delivery, job}`, the original payload,
  redacted headers (plus `x-skillhook-replay-of`), query string and sender IP. The signature is not
  checked again (a delivery that was rejected needs `--force` / `force`), `when` filters apply unless
  `--skip-filters`, nothing is de-duplicated, and `runner`/`model`/`effort` can be overridden. Through
  the running server when there is one, in the CLI process otherwise. The guardrails tell the agent it
  is replaying. `src/manual.ts` (manual runs) and `src/replay.ts` (the planner) are new leaf modules,
  re-exported from `src/ops.ts`.
- A job API for the running agent, and a human in the loop. Every Claude and Codex run now gets a
  per-run MCP server (`skillhook mcp --job`, injected with `claude --mcp-config` /
  `codex -c mcp_servers.skillhook_job.*`, nothing to configure) with `job_progress`, `job_ask_human`,
  `job_set_outcome`, `job_note` and `job_context`; the same is available as
  `skillhook job progress|ask|outcome|note|context` (`$SKILLHOOK_BIN`) for shell skills and agents
  that prefer a CLI. The guardrails explain both. Everything is files in the job directory
  (`progress.jsonl`, `progress.json`, `question.json`, `answer.json`), which the queue watches: they
  become the `progress`, `question` and `answer` fields of the job, the events `job.progress`,
  `job.waiting_human` and `job.answered`, `GET /jobs/<id>/progress` and the timeline in
  `skillhook jobs show`. `job_ask_human` waits for a person (`human_wait_seconds`, default 300; the
  job's timeout clock is paused meanwhile). A person answers with `skillhook jobs answer <id> "…"`,
  `POST /jobs/<id>/answer` or the MCP tool `answer_job`: live when the agent is still waiting,
  otherwise as a new job with `trigger: resume` that continues the session
  (`claude -p --resume <session>`, `codex exec resume <thread>`) with the answer in a
  `<human_answer>` block; the two jobs are linked by `resume_of` / `resolved_by`, and a run without a
  session runs the skill afresh (`runner_reason`). `skillhook jobs list --waiting`,
  `GET /jobs?waiting=1` and `list_jobs {waiting: true}` show what waits for a person (an open
  question, or outcome `needs_human`); a run that ends with its question unanswered counts as
  `needs_human`. New block fields `agent_api` (`mcp` | `cli` | `none`) and `human_wait_seconds`; new
  job variables `SKILLHOOK_BIN`, `SKILLHOOK_HOME`, `SKILLHOOK_HUMAN_WAIT_SECONDS`.
- Live configuration and remote control. The running server now holds one live `skillhook.json`:
  `skillhook config set` / `unset` tell it to re-read the file (`skillhook config reload`,
  `POST /config/reload`, `PATCH /config {set, unset}`, MCP `update_config`; a hand edit is noticed
  within five seconds), every key but `host` and `port` applies at once, and those two are reported
  as `pending_restart` (`GET /config`, MCP `get_config`). An invalid change is refused and nothing is
  written. `POST /control/restart` (MCP `restart_server`) stops a service-run server gracefully and
  lets launchd / systemd start it again; `GET /service`, `GET /logs` and `POST /update` (MCP
  `check_update`) expose the service status, its log and the update check to the admin API. New event
  `config.changed`. Internally `ConfigRef` patches the live config in place, the logger and the job
  store take new settings, the rate limiter reads its limit at use, and the queue can `drain`.
- Stats. `skillhook stats [--since 24h|7d|ISO] [--until ISO] [--skill S]`, `GET /stats` and the MCP tool
  `get_stats` sum up the job directories and the delivery log: jobs by status, outcome, trigger, runner
  and failure kind, success and completion rates, duration and queue-wait percentiles, cost and
  tokens (Claude and Codex usage added up), deliveries by outcome and HTTP status, and the same per
  skill.
- Runner readiness, failure kinds and fallback. Before a job spawns, skillhook checks that its runner is
  installed and logged in (or has an API key), with the job environment, cached for
  `health.readiness_cache_seconds` (60): `skillhook runners`, `GET /runners`, MCP `get_runners`, event
  `runners.changed`. A runner that is not ready fails the job at once (`failure.kind: auth`, no
  process started) unless the skill's new `fallback: { runners: [codex] }` (or `defaults.fallback` in
  `skillhook.json`) names a ready runner, which then takes over (`runner_requested`, `runner_reason`).
  Every `failed` or `timed_out` job now carries `failure: {kind, code, retryable, message}` (`auth`,
  `usage_limit`, `rate_limit`, `budget`, `max_turns`, `not_found`, `timeout`, `crash`, `unknown`),
  classified from what the CLI printed; `jobs list --failure`, `GET /jobs?failure=` and `list_jobs`
  filter by it. `fallback.on` may add `auth`, `usage_limit`, `rate_limit`, `crash`, and the new
  `retry: { attempts, on, backoff_seconds }` repeats a run on the same runner; both act only on a run
  that failed before the agent produced anything, and record the earlier runs in `attempts`.
- Deep health. `skillhook health` (`GET /health/checks`, MCP `get_health`) is the doctor plus what the
  agents actually depend on, grouped (`system`, `skillhook`, `runners`, `tools`, `skills`, `exposure`):
  `claude` / `codex` versions and logins, one check per MCP server Claude Code and Codex know
  (connected, needs authentication, failed to connect, with the CLI's reason), Claude's MCP config
  diagnostics and installed plugins, `codex doctor`, free disk space, and per skill the last run and
  any `env:` name that is not set. The probes run with the same environment as a job, so
  `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or an API key in `.env` apply to the diagnosis. The server keeps
  one report per flavour for `health.cache_seconds` (60; `health.probe_timeout_seconds`, 20, bounds
  `claude mcp list`), answers `GET /doctor` and `GET /health/checks` from it (`?refresh=1`,
  `?deep=0`, `?network=1`) and publishes `health.changed` when a check changes status. `doctor`
  gained `disk` and shows the CLI versions; every check now carries `group` and `data`.
- Ad-hoc runs. `skillhook run --file SKILL.md` (or `--stdin`), `POST /skills/test` and the MCP tool
  `test_skill` run a SKILL.md that is not installed: the document is validated, kept at
  `jobs/<id>/skill/<name>/SKILL.md` and run from there, as a job with `trigger: test`, `adhoc: true`,
  `skill_file` and `source.method: TEST`; nothing is added to `<home>/skills`. `--dry-run` works with
  `--file` too. Every job now records `skill_file` (the SKILL.md or skillhook.yaml it ran from), and
  `skillhook run --cwd` applies to real runs, not only to `--dry-run`.

## 0.3.0 (2026-09-23)

- Scheduled hooks. A `schedule:` key on any skill (`skillhook:` block) or hook (`skillhook.yaml`) runs it
  on a cron schedule from the running server, without a webhook: a five-field expression or an alias
  (`@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`), read in an IANA `timezone` (default UTC), with
  `catch_up` for slots missed while the server was stopped or the machine asleep (`latest` by default,
  `all` up to 24, or `none`), `overlap` for a slot that comes due while the previous run is still going
  (`skip` by default, or `queue`), and a static `payload`. `webhook: false` makes a scheduled hook
  schedule-only: `POST /hooks/<name>` answers `404 schedule_only` and no secret is required. A slot is
  identified by its wall-clock minute in the hook's zone and recorded in the delivery index, so a
  restart, a second tick or the repeated hour of a fall-back night never runs it twice; a minute that
  does not exist on a spring-forward night is skipped. A new schedule waits for its next slot.
- Scheduled jobs carry `trigger: schedule`, `source.method: SCHEDULE`, `delivery_id: schedule:<slot>`
  and the payload `{scheduled_for, schedule: {cron, timezone, slot, fired_at, caught_up, manual}, …}`;
  the guardrails say the run was started by a schedule and has no external sender. State lives in
  `jobs/.schedules.json`; the server logs `schedule registered`, `schedule fired` and
  `schedule slots skipped`.
- `skillhook schedules list | next <name> [--count N] | run <name> [--wait S]`, the MCP tool
  `list_schedules`, `schedules` in `GET /health` (admin), `webhook` and `schedule` (with `next_run_at`)
  in `GET /skills`, `skills show` and the `skills list` URL column (`(schedule <cron>)` for
  schedule-only hooks). `doctor` gains a `schedules` check and, on macOS, a `sleep` check that warns
  when a machine with schedules is allowed to sleep; `doctor` and `skills validate` no longer ask
  schedule-only hooks for a secret.
- `skillhook.yaml` and `SKILL.md` files that use `schedule` or `webhook` are rejected by older
  servers (unknown keys have always been errors), so upgrade every linked machine before merging one.
  Reference: `docs/schedules.md`.

## 0.2.0 (2026-09-17)

- Version-controlled hooks: a repository can declare its webhooks in a `skillhook.yaml` at its root.
  Each hook maps a webhook name to what runs: `run:` (a shell command, executed in the repository
  with the payload on stdin), `skill:` (a `SKILL.md` directory in the repository, served under the
  hook's name) or `prompt:` (inline instructions for the agent), plus any field of the `skillhook:`
  block (`auth`, `when`, `model`, `cwd`, `env`, …). Secrets are named, never stored, in the file.
- `skillhook link [dir]` registers a repository (the new `projects` key in `skillhook.json`),
  `skillhook unlink <dir>` removes it, `skillhook projects` lists linked repositories with their
  hooks and URLs, and `skillhook projects init [dir]` writes a starter file (a `git pull --ff-only`
  hook for merged GitHub pull requests) and links it. The server re-reads `projects`, every
  `skillhook.yaml` and every referenced `SKILL.md` on change, so `link` and `git pull` need no
  restart. Names in `~/.skillhook/skills` win over repositories; a name defined twice is reported by
  `skills list`, `skills validate`, `doctor` and the server log instead of being served.
- `skills list` gained a `source` column, `skills show` a `source:` line, `GET /skills` and the MCP
  skill tools a `source` field (`{type: "home"}` or `{type: "project", dir, file, kind}`), and
  `doctor` a `project <dir>` check per linked repository. New MCP tools: `list_projects`,
  `link_project` (with `init`), `unlink_project`.
- `schema/skillhook.yaml.schema.json` (generated by `npm run schema`) gives editors validation and
  completion for `skillhook.yaml`; the starter file references it on its first line.

## 0.1.1 (2026-09-16)

- The npm package is now `@meterapp/skillhook`; the command is still `skillhook`. Install with
  `npm install -g @meterapp/skillhook`. Coming from the unscoped `skillhook` 0.1.0 package, run
  `npm uninstall -g skillhook` first (npm refuses a second package that installs a `skillhook`
  command), then `skillhook service install` again if the service ran from that install. The old
  package's update check does not see the new name.
- The plugin's MCP server starts with `npx -y @meterapp/skillhook mcp`, and
  `skillhook mcp --print-config` prints the same `npx` fallback when skillhook is not installed.
- Releases: the Publish workflow takes the package name from `package.json`, and its verification
  waits until the new tarball downloads (then retries the install) instead of failing while the
  registry catches up. CI installs the tarball `npm pack` reports.

## 0.1.0 (2026-09-16)

Initial release.

- Webhook server (`/hooks/<skill>`) with per-skill auth: bearer, basic, HMAC, GitHub,
  Sentry, Linear, Standard Webhooks (Granola, Svix), Stripe, Slack; filters, de-duplication,
  rate limits, synchronous `?wait=` responses and an admin API.
- In-flight de-duplication: a delivery whose payload and query string match a job of the same
  skill that is still queued or running is answered with that job (`duplicate: true, in_flight: true`)
  instead of starting a second run. On by default (`jobs.dedupe_in_flight`); a skill opts out with
  `dedupe.in_flight: false`.
- Runners: Claude Code (`claude -p`, stream-json), Codex (`codex exec --json`), shell.
  Per-skill runner, model, effort, cwd, timeout and env allow-list.
- Agent Skills format (`SKILL.md` + `skillhook:` block) with a live-reloading registry.
- Jobs on disk with prompt, logs, result and a resume command for the agent session.
- CLI: init, doctor, serve, service (launchd/systemd), expose (Tailscale Funnel/Serve),
  skills, secret, run, send, jobs, config, url, mcp, update.
- Update notifications: `skillhook update [--install]`, a daily background check (cached in
  `update-check.json`) that mentions a newer version after commands, in `doctor` and in the
  server log. Opt out with `SKILLHOOK_NO_UPDATE_CHECK=1`, `CI`, or `"update_check": false`.
- MCP server exposing the whole workflow to Claude Code, Codex, Cursor and others.
- Bundled examples: hello, granola-meeting-actions, sentry-triage, github-issue-triage,
  remote-prompt.
- Release tooling: `npm run release`, a CI job that installs the packed tarball, and
  workflows that tag merged version bumps, publish to npm with provenance and verify the
  published package.
- Hardening from CodeQL: `Authorization` headers and `.env` lines are parsed without
  backtracking regexes, job-id characters come from `crypto.randomInt` instead of a biased
  modulo, and `config set` rejects `__proto__` / `constructor` / `prototype` keys.
