@ghostpaw/questlog 0.9.2 → 0.11.0

package/README.md

@@ -88,10 +88,14 @@ Lists show local due dates, overdue markers, and recorded outcomes. Plain JSON
 adds ISO UTC siblings for numeric timestamp fields ending in `At`.
 `done` stores `--outcome` with the finished quest; without it the command asks for one and exits 3.
 
-Plain commands print short text by default. Use `--json` for the full tool result
+Commands print text by default, including hooks, delivery views and each watch tick; `call` and direct tool commands return the raw tool result as JSON. Use `--json` for the full tool result
 and `--compact` for compact JSON. `--db path` works before or after the command.
 Each command accepts `--help`. Exit codes are 0 for success, 1 for invalid input
-or a tool error, 2 for usage errors, and 3 when clarification is needed.
+or a tool error, 2 for usage errors, and 3 when clarification is needed or `hook remove`/`hook test` addresses a missing target.
+Missing quests and deliveries exit 1. `hook label` names the database, not an individual target.
+
+`questlog skill --short` prints the compact cheat sheet; `questlog skill --list` lists guides.
+ISO date-times without a zone (for example `2026-10-29T09:00`) use the local time zone.
 
 The `call` command and the per-tool form still reach every tool and parameter:
 
@@ -124,6 +128,8 @@ ghostpaw-questlog skill > SKILL.md
 
 Each line downloads the latest release asset, checks it against the release’s SHA256SUMS and installs it on the PATH (~/.local/bin on Linux/macOS; the Windows script adds its folder to the user PATH).
 
+These lines never edit ~/.profile or other shell startup files: `export PATH` applies to the current shell only. To keep it in new shells, use the `~/.profile` line below.
+
 linux-x64:
 
 ```sh
@@ -148,17 +154,37 @@ darwin-x64:
 curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"
 ```
 
-windows-x64 (PowerShell):
+windows-x64 (PowerShell; persistently adds its folder to the user PATH):
 
 ```powershell
 irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex
 ```
 
+Pinned to a release:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target linux-x64 --version 0.11.0 && export PATH="$HOME/.local/bin:$PATH"
+```
+
+Also adding ~/.local/bin to ~/.profile (edits ~/.profile once; skipped if it already mentions ~/.local/bin; zsh login shells read ~/.zprofile instead, so use that file name there):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"
+```
+
+To skip the persistent Windows user PATH edit (the installer still installs and prints the folder to add):
+
+```powershell
+$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex
+```
+
 ```text
 $ ghostpaw-questlog --version
-questlog 0.9.2 (binary, linux-x64)
+questlog 0.11.0 (binary, linux-x64)
 ```
 
+Scripts that compare versions should use `--version --short` or `--version --json`.
+
 Standalone binaries are available from [GitHub Releases](https://github.com/GhostPawJS/questlog/releases).
 
 A session with the 0.9.1 linux-x64 binary against a fresh database:
@@ -498,3 +524,117 @@ If this package helps your project, consider sponsoring its maintenance:
 ---
 
 **[Anonyfox](https://anonyfox.com) • [MIT License](LICENSE)**
+
+## Webhooks
+
+Configure opt-in outbound wakes with the release binary. No server or scheduler is started.
+With no targets, tick makes no network calls. Targets and retry state live in the database.
+
+```sh
+questlog hook add https://example.org/wake --min-gap 60
+questlog hook add https://example.org/team --tag work --events quest.due,quest.overdue --secret-stdin
+questlog hook label work
+questlog hook list
+questlog tick --dry-run
+questlog tick
+questlog watch --interval 60
+questlog hook test 1
+questlog review deliveries
+questlog show 12
+questlog hook remove 1
+```
+
+Save the signing secret printed once by `hook add` (including its `--json` result).
+`--secret-stdin` reads a supplied secret from standard input; there is no secret flag.
+Secrets and custom header values are stored in the database. On POSIX, new database files
+and their WAL/SHM siblings use mode 0600, and directories created for them use 0700.
+Existing database permissions are preserved; Windows uses its existing access controls.
+
+Add repeatable custom headers with `--header "Authorization: Bearer value"` or
+`--header-stdin` (one `Name: value` line per header, keeping values out of shell history).
+For example: `questlog hook add https://example.org/wake --header "X-Key: value"`.
+Headers accompany every delivery and test. Header names are shown with values replaced by
+`***`; values are never included in list, show, test, tick, watch, or tool output.
+Names must be HTTP tokens; `host`, `content-length`, `content-type`, and `x-questlog-*`
+are reserved (case insensitive). To change headers, remove the hook and add it again.
+Use separate invocations for `--header-stdin` and `--secret-stdin`.
+URL userinfo is rejected; use a custom header or query key instead.
+`questlog show d_…` prints delivery status, attempts, HTTP status, next attempt,
+redacted target URL, and event ids; add `--json` for JSON.
+
+List output redacts URL userinfo and query strings. Removal deletes the target and its deliveries.
+A target covers the database unless `--tag` restricts it to quests with that tag;
+rumors have no tags and reach database targets only. `--events` defaults to all five events.
+The label defaults to the database filename without directory or extension (`questlog` for memory).
+Only use labels suitable for disclosure to the receiver.
+
+For cron:
+
+```cron
+* * * * * questlog tick
+```
+
+Cron's PATH may need `$HOME/.local/bin/questlog tick --db /path/to/quests.db`.
+`watch` repeats tick (default 60 seconds, minimum 5), finishing its current tick on SIGINT/SIGTERM.
+Tick exits 0 after running even when deliveries need retrying. Dry runs roll back all changes,
+including repeatable materialization, and make no network calls.
+
+Events are detected from the model at tick time:
+
+- `quest.due`: an unresolved, undeleted quest reaches its effective due time (own `due_at`, otherwise its undeleted questline's due time).
+- `quest.overdue`: that effective deadline is strictly earlier than now and the quest remains unresolved.
+- `quest.unblocked`: an unresolved quest is available, all active prerequisites have succeeded or been deleted, and at least one prerequisite succeeded after its unlock was installed. Occurrence time is the latest active prerequisite success or not-before time, whichever is later.
+- `repeatable.spawned`: a concrete repeatable instance was created; occurrence time is its creation time. Tick first materializes due anchors through the existing spawn operation.
+- `rumor.captured`: an undeleted rumor was created; occurrence time is its creation time, even if subsequently settled or dismissed.
+
+Each type, entity and occurrence timestamp has a persistent unique event key. Repeated ticks
+and restarts do not create another occurrence. Changes removed before any tick cannot be
+reconstructed. Occurrences earlier than target creation are excluded, preventing backlog floods.
+Tags are evaluated when assigning an event. Already assigned events retain their batch membership.
+
+One POST batch per target per tick contains only identifiers, types, timestamps, and the DB label:
+
+```json
+{"type":"questlog.events","db":"work","deliveryId":"d_…","sentAt":"2026-10-28T10:00:00.000Z","events":[{"id":"e_…","type":"quest.due","questId":12,"occurredAt":"2026-10-28T09:59:00.000Z"}]}
+```
+
+Headers are `content-type: application/json`, `user-agent: questlog/<version>`,
+`x-questlog-delivery: <deliveryId>`, `x-questlog-timestamp: <unix seconds>`, and
+`x-questlog-signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + rawBody)>`.
+No titles, objectives, details, or tag text are sent. `hook test` sends a logged `hook.test`
+event immediately, ignoring the min gap. Add and test are CLI-only in the tool facade;
+`manage_hooks` supports list, remove, tick (with `dry_run`), and deliveries.
+
+2xx delivers the batch. Requests time out after 5 seconds. Other responses, timeouts, and
+network errors retry after 30 seconds, 1 minute, 2 minutes, 4 minutes, and so on, capped
+at 1 hour, plus less than 1 second jitter. The target's min gap also applies to retries.
+Eight unsuccessful attempts mark a delivery failed. Retries retain the delivery id and events.
+Pending batches wait behind retries. Only the last 500 delivered entries per target are kept;
+pending and failed entries are retained. Transactions and two-minute leases prevent overlapping
+ticks from claiming the same delivery. A crash after receipt but before recording success can
+cause another request: receivers must dedupe by delivery id.
+
+### Verifying a delivery
+
+Compute HMAC-SHA256 over `timestamp + "." + rawBody` with the secret and compare in constant
+time. Reject timestamps older than 5 minutes (and timestamps too far in the future), then
+dedupe on `x-questlog-delivery`. Use durable deduplication storage in a production receiver.
+This 15-line Node example uses an in-memory set:
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+const secret = process.env.WEBHOOK_SECRET, seen = new Set();
+createServer(async (req, res) => {
+  const chunks = []; for await (const chunk of req) chunks.push(chunk);
+  const rawBody = Buffer.concat(chunks), h = req.headers;
+  const timestamp = h['x-questlog-timestamp'], id = h['x-questlog-delivery'];
+  const age = Date.now() / 1000 - Number(timestamp);
+  const expected = createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest();
+  const signature = String(h['x-questlog-signature'] || '');
+  const actual = Buffer.from(signature.slice(7), 'hex');
+  if (!id || !/^\d+$/.test(timestamp) || age > 300 || age < -300 || !/^sha256=[a-f0-9]{64}$/.test(signature) || actual.length !== expected.length || !timingSafeEqual(actual, expected)) { res.writeHead(401).end(); return; }
+  if (!seen.has(id)) { seen.add(id); console.log(JSON.parse(rawBody)); }
+  res.writeHead(204).end();
+}).listen(8080, '127.0.0.1');
+```

package/SKILL.md

@@ -28,15 +28,20 @@ Run tools as `ghostpaw-questlog ...`; use `~/.local/bin/ghostpaw-questlog` if it
 `questlog` and `ghostpaw-questlog` are the same binary.
 
 - `questlog search <words>` before `add` to avoid duplicates.
-- `ghostpaw-questlog add "..." --tag a,b --due tomorrow`
-- `questlog list [--view <view>]`: questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors.
-- `questlog done <id> --outcome "..."`
-- `questlog search <words>`
-- `questlog show <id>`
+- `ghostpaw-questlog add "Write the report" --tag work --due tomorrow`
+- `questlog list [--view <view>]`: deliveries, questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors.
+- `questlog done 12 --outcome "Report sent"`
+- `questlog search "release"`
+- `questlog show 12`
+- `questlog list --view quests.available`
 - Use `--json` on any plain command.
-- Exit codes: 0 ok / 1 error / 2 usage / 3 needs input.
+- Exit codes: 0 ok / 1 error / 2 usage / 3 needs input or hook target not found.
 - Database: `~/.ghostpaw/questlog.db`; override with `--db` or `GHOSTPAW_QUESTLOG_DB`.
-- Use one database per agent or project.
+- Use one database per project.
+- `questlog --version` prints the installed version.
+- `questlog skill --short` prints this compact cheat sheet.
+- `questlog skill --list` lists guides; `questlog skill webhooks` reads one.
+- Webhooks: `questlog hook add <url>`, `questlog tick --dry-run`, `questlog watch`. Read `questlog skill webhooks` for events, signing, verification, and cron setup.
 
 ## Appendix: MCP and tool calls
 
@@ -50,6 +55,28 @@ CLI: `ghostpaw-questlog call <tool> '<JSON object>'` or `ghostpaw-questlog <tool
 
 Inspect schemas with `ghostpaw-questlog describe <tool>`. Use `--db <path>` to select a database.
 
+### manage_hooks
+
+List or remove outbound webhook targets, run a tick, or inspect pending and failed deliveries.
+
+Use when: Use to operate configured outbound webhooks. Add and test targets with the CLI.
+
+Not for: Use quest tools to change work itself.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | list, remove, tick, deliveries. Operation. |
+| id | integer | no | Target id. |
+| dry_run | boolean | no | Preview only. |
+
+```sh
+ghostpaw-questlog call manage_hooks '{"action":"list"}'
+ghostpaw-questlog call manage_hooks '{"action":"remove","id":1}'
+ghostpaw-questlog call manage_hooks '{"action":"tick"}'
+```
+
 ### search_questlog
 
 Search quests and rumors by text when you need to find an existing item before inspecting or changing it.
@@ -83,7 +110,7 @@ Read-only.
 
 | Parameter | Type | Required | Values / description |
 | --- | --- | --- | --- |
-| view | string | yes | questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors. Which operational review surface to return. |
+| view | string | yes | deliveries, questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors. Which operational review surface to return. |
 | filters | object | no | Optional filters for supported review surfaces. |
 | filters.questlineId | integer | no | Optional questline id used by quest views. |
 | filters.tagNames | array | no | Optional tag names used by quest views. |
@@ -92,7 +119,7 @@ Read-only.
 | now | integer | no | Optional evaluation timestamp for time-sensitive views. |
 
 ```sh
-ghostpaw-questlog call review_questlog '{"view":"questlines"}'
+ghostpaw-questlog call review_questlog '{"view":"deliveries"}'
 ```
 
 ### inspect_questlog_item
@@ -152,16 +179,39 @@ Writes: writes_state.
 | action | string | yes | attach_quest_to_questline, create_quest, create_questline, detach_quest_from_questline, dismiss_rumor, reopen_rumor, settle_rumor, update_rumor. Action to perform. |
 | questId | integer | no | Quest to attach or detach. |
 | questlineId | integer | no | Questline that should receive the quest. |
-| quest | object | no |  |
+| quest | object | no | Object: title (required), objective (required), questlineId, tags, rewards, dueAt, notBeforeAt, scheduledStartAt, scheduledEndAt, allDay, estimateSeconds |
 | quest.title | string | yes | Title for the new quest. |
 | quest.objective | string | yes | Objective for the new quest. |
-| questline | object | no |  |
+| quest.questlineId | integer | no | Optional questline to place the quest in. |
+| quest.tags | array | no | Optional tags to apply at creation. |
+| quest.rewards | array | no | Optional rewards to attach at creation. |
+| quest.rewards[].kind | string | yes | Reward kind. |
+| quest.rewards[].name | string | yes | Reward name. |
+| quest.dueAt | integer | no | Optional latest acceptable completion timestamp. |
+| quest.notBeforeAt | integer | no | Optional earliest actionable timestamp. |
+| quest.scheduledStartAt | integer | no | Optional planned schedule window start. |
+| quest.scheduledEndAt | integer | no | Optional planned schedule window end. |
+| quest.allDay | boolean | no | Whether the scheduled window is all-day. |
+| quest.estimateSeconds | integer | no | Optional active-effort estimate in seconds. |
+| questline | object | no | Object: title (required), description |
 | questline.title | string | yes | Questline title. |
 | questline.description | string | no | Optional questline description. |
 | rumorId | integer | no | Rumor to settle, dismiss, or reopen. |
 | dismissedAt | integer | no | Optional dismissal timestamp. |
 | settledAt | integer | no | Optional settlement timestamp. |
 | quests | array | no | Quests to create during rumor settlement. Include timing and tags directly. |
+| quests[].title | string | yes | Title for a created quest. |
+| quests[].objective | string | yes | Objective for a created quest. |
+| quests[].tags | array | no | Optional tags to apply at creation. |
+| quests[].rewards | array | no | Optional rewards to attach at creation. |
+| quests[].rewards[].kind | string | yes | Reward kind. |
+| quests[].rewards[].name | string | yes | Reward name. |
+| quests[].dueAt | integer | no | Optional latest acceptable completion timestamp. |
+| quests[].notBeforeAt | integer | no | Optional earliest actionable timestamp. |
+| quests[].scheduledStartAt | integer | no | Optional planned schedule window start. |
+| quests[].scheduledEndAt | integer | no | Optional planned schedule window end. |
+| quests[].allDay | boolean | no | Whether the scheduled window is all-day. |
+| quests[].estimateSeconds | integer | no | Optional active-effort estimate in seconds. |
 | now | integer | no | Optional timestamp for membership, reopen, or rumor update. |
 | title | string | no | New title for the update_rumor action. |
 | details | string | no | New or enriched context text for the update_rumor action. |
@@ -221,6 +271,8 @@ Writes: writes_state.
 | outcome | string | no | Terminal outcome text. Required for finish, abandon, and abandon_and_spawn_followups. |
 | resolvedAt | integer | no | Optional resolved timestamp for finish or abandon actions. |
 | followups | array | no | Follow-up quests to create atomically. Required for abandon_and_spawn_followups. |
+| followups[].title | string | yes | Title for a follow-up quest. |
+| followups[].objective | string | yes | Objective for a follow-up quest. |
 
 ```sh
 ghostpaw-questlog call run_quest '{"action":"start","questId":1}'
@@ -272,7 +324,7 @@ Writes: writes_state.
 | --- | --- | --- | --- |
 | action | string | yes | archive, create, preview_due, spawn_due, update. Action to perform. |
 | repeatableQuestId | integer | no | Repeatable quest to archive or update. |
-| repeatableQuest | object | no |  |
+| repeatableQuest | object | no | Object: title (required), objective (required), rrule (required), anchorAt (required) |
 | repeatableQuest.title | string | yes | Title for the new repeatable quest. |
 | repeatableQuest.objective | string | yes | Objective for the new repeatable quest. |
 | repeatableQuest.rrule | string | yes | RRULE describing recurrence. |
@@ -310,7 +362,7 @@ Writes: writes_state.
 | Parameter | Type | Required | Values / description |
 | --- | --- | --- | --- |
 | action | string | yes | add, remove, replace. Action to perform. |
-| target | object | yes |  |
+| target | object | yes | Object: id (required), kind (required) |
 | target.id | integer | yes | Target entity id. |
 | target.kind | string | yes | quest, repeatable_quest. Target kind. |
 | tagNames | array | yes | Tag names to add, remove, or replace. |
@@ -335,14 +387,16 @@ Writes: writes_state.
 | Parameter | Type | Required | Values / description |
 | --- | --- | --- | --- |
 | action | string | yes | add, claim, remove, replace_repeatable_template, update. Action to perform. |
-| target | object | yes |  |
+| target | object | yes | Object: id (required), kind (required) |
 | target.id | integer | yes | Target entity id. |
 | target.kind | string | yes | quest, reward, repeatable_quest. Target kind. |
-| reward | object | no |  |
+| reward | object | no | Object: kind (required), name (required), now |
 | reward.kind | string | yes | Reward kind. |
 | reward.name | string | yes | Reward name. |
 | reward.now | integer | no | Optional update timestamp for the update action. |
 | rewards | array | no | Full future reward template set. Required for replace_repeatable_template. |
+| rewards[].kind | string | yes | Reward kind. |
+| rewards[].name | string | yes | Reward name. |
 | claimedAt | integer | no | Optional claim timestamp. |
 | now | integer | no | Optional timestamp for removal or template replacement. |
 
@@ -376,31 +430,32 @@ ghostpaw-questlog call retire_work '{"action":"hide","target":{"kind":"quest","i
 
 ### Workflow guides
 
-- `ghostpaw-questlog skill archive-delete-and-prune` ([archive-delete-and-prune](skills/questlog/references/archive-delete-and-prune.md)): Choose the right retirement action for each kind of work so history stays honest and hiding does not get confused with archival or terminal execution truth.
-- `ghostpaw-questlog skill choose-work-shape` ([choose-work-shape](skills/questlog/references/choose-work-shape.md)): Choose the right structure for new work by separating uncertainty, one-shot execution, multi-step arcs, and recurring patterns.
-- `ghostpaw-questlog skill clarify-ambiguous-requests` ([clarify-ambiguous-requests](skills/questlog/references/clarify-ambiguous-requests.md)): Treat ambiguity as a real state, capture uncertainty honestly, and only commit work structure once the next executable shape is clear.
-- `ghostpaw-questlog skill close-work-and-claim-outcomes` ([close-work-and-claim-outcomes](skills/questlog/references/close-work-and-claim-outcomes.md)): Close work with the correct terminal lifecycle action, then handle any concrete reward claim as a separate explicit step.
-- `ghostpaw-questlog skill create-concrete-quest` ([create-concrete-quest](skills/questlog/references/create-concrete-quest.md)): Create real, bounded executable quests only when the objective is concrete enough to execute without interpretive guesswork.
-- `ghostpaw-questlog skill detect-slips-and-staleness` ([detect-slips-and-staleness](skills/questlog/references/detect-slips-and-staleness.md)): Detect work that is slipping or going stale by reading overdue, deferred, in-progress, and related operational views before choosing one recovery move.
-- `ghostpaw-questlog skill escalate-and-unblock` ([escalate-and-unblock](skills/questlog/references/escalate-and-unblock.md)): Diagnose blockers honestly, then remove or realign hard gates when the model is wrong instead of treating every delay as generic escalation theater.
-- `ghostpaw-questlog skill frame-initiative-questline` ([frame-initiative-questline](skills/questlog/references/frame-initiative-questline.md)): Use questlines for shared initiative context, then attach concrete quests and maintain the structure without confusing one quest with one arc.
-- `ghostpaw-questlog skill handle-exceptions-and-weird-cases` ([handle-exceptions-and-weird-cases](skills/questlog/references/handle-exceptions-and-weird-cases.md)): Handle weird cases by diagnosing the actual tool outcome, routing into clarification or recovery when needed, and refusing to fake a clean normal-state story.
-- `ghostpaw-questlog skill intake-triage` ([intake-triage](skills/questlog/references/intake-triage.md)): Triage new asks, ideas, and vague incoming work into the right next step without prematurely committing execution structure.
-- `ghostpaw-questlog skill maintain-clear-ownership` ([maintain-clear-ownership](skills/questlog/references/maintain-clear-ownership.md)): Keep ownership explicit through quest content and classification because Questlog does not provide a separate assignee field or ownership tool.
-- `ghostpaw-questlog skill manage-approvals-and-promises` ([manage-approvals-and-promises](skills/questlog/references/manage-approvals-and-promises.md)): Treat approvals and commitments as modeled work with timing and dependencies instead of burying them as vague narrative promises.
-- `ghostpaw-questlog skill plan-successor-work` ([plan-successor-work](skills/questlog/references/plan-successor-work.md)): Create explicit successor work after closure by spawning follow-ups or shaping new work, while keeping uncertain next steps in intake instead of faking certainty.
-- `ghostpaw-questlog skill plan-time-correctly` ([plan-time-correctly](skills/questlog/references/plan-time-correctly.md)): Use quest planning fields honestly so availability, due pressure, and schedule intent stay meaningful instead of getting collapsed into one generic date.
-- `ghostpaw-questlog skill prioritize-across-streams` ([prioritize-across-streams](skills/questlog/references/prioritize-across-streams.md)): Prioritize across competing work streams by reading real candidate sets, distinguishing available from blocked work, and then reflecting the choice in planning.
-- `ghostpaw-questlog skill protect-capacity-and-focus` ([protect-capacity-and-focus](skills/questlog/references/protect-capacity-and-focus.md)): Protect capacity and focus by reading the real in-progress and scheduled-now load, then using planning to rebalance instead of silently overcommitting.
-- `ghostpaw-questlog skill recover-from-modeling-mistakes` ([recover-from-modeling-mistakes](skills/questlog/references/recover-from-modeling-mistakes.md)): Recover from modeling mistakes by diagnosing the exact current state first, then applying the smallest honest corrective tool instead of rewriting history blindly.
-- `ghostpaw-questlog skill report-status-and-manage-expectations` ([report-status-and-manage-expectations](skills/questlog/references/report-status-and-manage-expectations.md)): Build status reporting from the real questlog state, separating available, blocked, in-progress, slipping, and resolved work without relying on memory.
-- `ghostpaw-questlog skill revise-or-reshape-commitment` ([revise-or-reshape-commitment](skills/questlog/references/revise-or-reshape-commitment.md)): Revise a quest objective before execution starts, but reshape commitments honestly with lifecycle tools once real execution history exists.
-- `ghostpaw-questlog skill run-operational-review` ([run-operational-review](skills/questlog/references/run-operational-review.md)): Drive daily or weekly operational review from structured list views, then move from diagnosis into actual planning or execution changes.
-- `ghostpaw-questlog skill run-recurring-rhythms` ([run-recurring-rhythms](skills/questlog/references/run-recurring-rhythms.md)): Model recurring work as repeatable definitions that spawn fresh concrete quests over time instead of living forever as one immortal task.
-- `ghostpaw-questlog skill search-and-retrieve-context` ([search-and-retrieve-context](skills/questlog/references/search-and-retrieve-context.md)): Find relevant questlog context quickly, then switch from discovery to exact inspection without confusing free-text search with structured review surfaces.
-- `ghostpaw-questlog skill sequence-with-unlocks` ([sequence-with-unlocks](skills/questlog/references/sequence-with-unlocks.md)): Model hard sequencing with unlocks between concrete quests so blocked and available work stay truthful and reviewable.
-- `ghostpaw-questlog skill settle-rumor-into-structure` ([settle-rumor-into-structure](skills/questlog/references/settle-rumor-into-structure.md)): Turn a ready rumor into committed quest or questline structure without losing provenance or pretending vague intake is settled.
-- `ghostpaw-questlog skill tag-and-filter-portfolios` ([tag-and-filter-portfolios](skills/questlog/references/tag-and-filter-portfolios.md)): Use tags for cross-cutting classification and portfolio filtering without confusing tags for status, timing, or dependency modeling.
+- `ghostpaw-questlog skill webhooks`: Configure signed outbound event webhooks and verify deliveries.
+- `ghostpaw-questlog skill archive-delete-and-prune`: Choose the right retirement action for each kind of work so history stays honest and hiding does not get confused with archival or terminal execution truth.
+- `ghostpaw-questlog skill choose-work-shape`: Choose the right structure for new work by separating uncertainty, one-shot execution, multi-step arcs, and recurring patterns.
+- `ghostpaw-questlog skill clarify-ambiguous-requests`: Treat ambiguity as a real state, capture uncertainty honestly, and only commit work structure once the next executable shape is clear.
+- `ghostpaw-questlog skill close-work-and-claim-outcomes`: Close work with the correct terminal lifecycle action, then handle any concrete reward claim as a separate explicit step.
+- `ghostpaw-questlog skill create-concrete-quest`: Create real, bounded executable quests only when the objective is concrete enough to execute without interpretive guesswork.
+- `ghostpaw-questlog skill detect-slips-and-staleness`: Detect work that is slipping or going stale by reading overdue, deferred, in-progress, and related operational views before choosing one recovery move.
+- `ghostpaw-questlog skill escalate-and-unblock`: Diagnose blockers honestly, then remove or realign hard gates when the model is wrong instead of treating every delay as generic escalation theater.
+- `ghostpaw-questlog skill frame-initiative-questline`: Use questlines for shared initiative context, then attach concrete quests and maintain the structure without confusing one quest with one arc.
+- `ghostpaw-questlog skill handle-exceptions-and-weird-cases`: Handle weird cases by diagnosing the actual tool outcome, routing into clarification or recovery when needed, and refusing to fake a clean normal-state story.
+- `ghostpaw-questlog skill intake-triage`: Triage new asks, ideas, and vague incoming work into the right next step without prematurely committing execution structure.
+- `ghostpaw-questlog skill maintain-clear-ownership`: Keep ownership explicit through quest content and classification because Questlog does not provide a separate assignee field or ownership tool.
+- `ghostpaw-questlog skill manage-approvals-and-promises`: Treat approvals and commitments as modeled work with timing and dependencies instead of burying them as vague narrative promises.
+- `ghostpaw-questlog skill plan-successor-work`: Create explicit successor work after closure by spawning follow-ups or shaping new work, while keeping uncertain next steps in intake instead of faking certainty.
+- `ghostpaw-questlog skill plan-time-correctly`: Use quest planning fields honestly so availability, due pressure, and schedule intent stay meaningful instead of getting collapsed into one generic date.
+- `ghostpaw-questlog skill prioritize-across-streams`: Prioritize across competing work streams by reading real candidate sets, distinguishing available from blocked work, and then reflecting the choice in planning.
+- `ghostpaw-questlog skill protect-capacity-and-focus`: Protect capacity and focus by reading the real in-progress and scheduled-now load, then using planning to rebalance instead of silently overcommitting.
+- `ghostpaw-questlog skill recover-from-modeling-mistakes`: Recover from modeling mistakes by diagnosing the exact current state first, then applying the smallest honest corrective tool instead of rewriting history blindly.
+- `ghostpaw-questlog skill report-status-and-manage-expectations`: Build status reporting from the real questlog state, separating available, blocked, in-progress, slipping, and resolved work without relying on memory.
+- `ghostpaw-questlog skill revise-or-reshape-commitment`: Revise a quest objective before execution starts, but reshape commitments honestly with lifecycle tools once real execution history exists.
+- `ghostpaw-questlog skill run-operational-review`: Drive daily or weekly operational review from structured list views, then move from diagnosis into actual planning or execution changes.
+- `ghostpaw-questlog skill run-recurring-rhythms`: Model recurring work as repeatable definitions that spawn fresh concrete quests over time instead of living forever as one immortal task.
+- `ghostpaw-questlog skill search-and-retrieve-context`: Find relevant questlog context quickly, then switch from discovery to exact inspection without confusing free-text search with structured review surfaces.
+- `ghostpaw-questlog skill sequence-with-unlocks`: Model hard sequencing with unlocks between concrete quests so blocked and available work stay truthful and reviewable.
+- `ghostpaw-questlog skill settle-rumor-into-structure`: Turn a ready rumor into committed quest or questline structure without losing provenance or pretending vague intake is settled.
+- `ghostpaw-questlog skill tag-and-filter-portfolios`: Use tags for cross-cutting classification and portfolio filtering without confusing tags for status, timing, or dependency modeling.
 
 ### Principles
 

package/dist/chunk-7KTRNXTU.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// src/surfaces/schema_rows.ts
+function schemaRows(schema, prefix = "") {
+  const properties = { ...schema.properties };
+  const required = new Set(schema.required);
+  for (const branch of schema.oneOf ?? []) {
+    Object.assign(properties, branch.properties);
+    for (const key of branch.required ?? []) required.add(key);
+  }
+  return Object.entries(properties).flatMap(([key, property]) => {
+    const nested = property.items ?? property;
+    const children = nested.properties ?? Object.assign({}, ...(nested.oneOf ?? []).map((b) => b.properties));
+    const description = property.description || (Object.keys(children).length ? `Object: ${Object.keys(children).map((name) => `${name}${nested.required?.includes(name) ? " (required)" : ""}`).join(", ")}` : property.type === "array" ? `Array of ${property.items?.type ?? "values"}` : `Value for ${key}`);
+    return [
+      `${prefix}${key} | ${property.type ?? "oneOf"} | ${required.has(key) ? "yes" : "no"} | ${(property.enum ? `${property.enum.join(", ")}. ` : "") + description.replaceAll("|", "\\|").replaceAll("\n", " ")}`,
+      ...schemaRows(nested, `${prefix}${key}${property.items ? "[]" : ""}.`)
+    ];
+  });
+}
+
+export { schemaRows };

package/dist/chunk-D6EGZCT7.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// src/hooks/list_deliveries.ts
+function listDeliveries(db, options = {}) {
+  return db.prepare(
+    `SELECT * FROM hook_deliveries ${options.includeDelivered ? "" : "WHERE status <> 'delivered'"} ORDER BY target_id, next_attempt_at, id`
+  ).all().map(
+    (row) => ({
+      id: String(row.id),
+      targetId: Number(row.target_id),
+      events: JSON.parse(String(row.events)),
+      status: row.status,
+      attempts: Number(row.attempts),
+      lastAttemptAt: row.last_attempt_at == null ? null : Number(row.last_attempt_at),
+      httpStatus: row.http_status == null ? null : Number(row.http_status),
+      errorClass: row.error_class == null ? null : String(row.error_class),
+      nextAttemptAt: Number(row.next_attempt_at)
+    })
+  ).filter(
+    (d) => options.questId === void 0 || d.events.some((e) => e.questId === options.questId)
+  );
+}
+
+export { listDeliveries };

package/dist/chunk-GVD6A3RR.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+
+var CliUsageError = class extends Error {
+  exitCode = 2;
+};
+var keyOf = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+function parseCliArgs(argv, spec) {
+  const values = {};
+  const positions = [];
+  const flags = spec.flags ?? [];
+  const convert = (raw, arg) => {
+    let value = raw;
+    if (raw.startsWith("@")) {
+      try {
+        value = readFileSync(raw.slice(1), "utf8");
+      } catch {
+        throw new CliUsageError(`Cannot read value file: ${raw.slice(1)}`);
+      }
+    }
+    let result = value;
+    if (arg.type === "number" || arg.type === "integer") {
+      result = Number(value);
+      if (!value.trim() || !Number.isFinite(result) || arg.type === "integer" && !Number.isInteger(result))
+        throw new CliUsageError(`Expected ${arg.type} for ${arg.name}: ${value}`);
+    } else if (arg.type === "boolean") {
+      if (!["true", "false"].includes(value))
+        throw new CliUsageError(`Expected boolean for ${arg.name}`);
+      result = value === "true";
+    } else if (arg.type === "json") {
+      try {
+        result = JSON.parse(value);
+      } catch {
+        throw new CliUsageError(`Invalid JSON for ${arg.name}`);
+      }
+    }
+    if (arg.enum && !arg.enum.includes(result))
+      throw new CliUsageError(`${arg.name} must be one of: ${arg.enum.join(", ")}`);
+    return result;
+  };
+  let ended = false;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!ended && token === "--") {
+      ended = true;
+      continue;
+    }
+    if (ended || token === "-" || !token.startsWith("-")) {
+      positions.push(token);
+      continue;
+    }
+    const [flag, inline] = token.split(/=(.*)/s);
+    const negative = flag?.startsWith("--no-");
+    const name = flag?.replace(/^--?/, "").replace(/^no-/, "");
+    const arg = flags.find(
+      (entry) => entry.name === name || keyOf(entry.name) === name || entry.short === name
+    );
+    if (!arg) {
+      const prefix = (name ?? "").slice(0, 3);
+      const suggestion = prefix ? flags.find((entry) => entry.name.startsWith(prefix)) : void 0;
+      throw new CliUsageError(
+        `Unknown flag: ${flag}${suggestion ? `; did you mean --${suggestion.name}?` : ""}`
+      );
+    }
+    if (negative && arg.type !== "boolean")
+      throw new CliUsageError(`--no-${arg.name} requires a boolean flag`);
+    let raw = inline;
+    if (arg.type === "boolean" && raw === void 0) raw = negative ? "false" : "true";
+    if (raw === void 0) {
+      const next = argv[i + 1];
+      if (next === void 0 || /^--[a-z]/i.test(next))
+        throw new CliUsageError(`Missing value: --${arg.name}`);
+      raw = next;
+      i++;
+    }
+    const key = keyOf(arg.name);
+    if (arg.type === "array") {
+      const item = convert(raw, { ...arg, type: arg.itemType ?? "string" });
+      values[key] = [...values[key] ?? [], item];
+    } else values[key] = convert(raw, arg);
+  }
+  let index = 0;
+  for (const arg of spec.positionals ?? []) {
+    if (index >= positions.length) continue;
+    values[keyOf(arg.name)] = arg.variadic ? positions.slice(index).map((value) => convert(value, { ...arg, type: arg.itemType ?? arg.type })) : convert(positions[index], arg);
+    index = arg.variadic ? positions.length : index + 1;
+  }
+  if (index < positions.length)
+    throw new CliUsageError(`Unexpected positional: ${positions[index]}`);
+  for (const arg of [...flags, ...spec.positionals ?? []]) {
+    if (arg.required && values[keyOf(arg.name)] === void 0)
+      throw new CliUsageError(`Missing required argument: ${arg.name}`);
+  }
+  return values;
+}
+function renderCliHelp(spec) {
+  const describe = (arg) => `${arg.type}${arg.enum ? ` (${arg.enum.join("|")})` : ""}${arg.required ? " required" : ""}  ${arg.description ?? ""}`;
+  return `Usage: ${spec.command} ${(spec.positionals ?? []).map((arg) => `<${arg.name}${arg.variadic ? "..." : ""}>`).join(" ")} [flags]
+${spec.description ?? ""}
+
+Positionals:
+${(spec.positionals ?? []).map((arg) => `  ${arg.name}  ${describe(arg)}`).join("\n")}
+Flags:
+${(spec.flags ?? []).map((arg) => `  --${arg.name}${arg.short ? `, -${arg.short}` : ""}  ${describe(arg)}`).join("\n")}
+`;
+}
+
+export { CliUsageError, parseCliArgs, renderCliHelp };

package/dist/{chunk-6KTQK3ZE.js → chunk-I2AMIXGP.js}

@@ -724,8 +724,16 @@ Failure handling:
 - Do not filter by tags and assume that is the same as a schedule or dependency review.`
 });
 
+// src/skills/webhooks.ts
+var webhooksSkill = defineQuestlogSkill({
+  name: "webhooks",
+  description: "Configure signed outbound event webhooks and verify deliveries.",
+  content: '# Webhooks\n\nUse `questlog` to configure opt-in outbound automation. No server or scheduler is added.\nNo targets means no network calls. `manage_hooks` supports list, remove, tick with\n`dry_run`, and deliveries; add/test are CLI-only. `review_questlog` view `deliveries`\nand `questlog show <id>` expose pending/failed deliveries.\n\n```sh\nquestlog hook add https://example.org/wake --min-gap 60\nquestlog hook add https://example.org/team --tag work --events quest.due,quest.overdue --secret-stdin\nquestlog hook label work\nquestlog hook list\nquestlog tick --dry-run\nquestlog tick\nquestlog watch --interval 60\nquestlog hook test 1\nquestlog review deliveries\nquestlog show 12\nquestlog hook remove 1\n```\n\n`hook add` prints its random 32-byte signing secret once, also as `secret` in `--json`.\nSave it securely. `--secret-stdin` supplies one via stdin; there is no secret flag.\nSecrets and custom header values are stored in the DB. New POSIX DB/WAL/SHM files use 0600 and created directories use 0700; existing DB modes are preserved. Windows uses existing access controls.\nUse repeatable `--header "Name: value"` or `--header-stdin` (one line per header, avoiding shell history). Headers are sent on every delivery and test; output shows names with `***` values. HTTP token names are required; host, content-length, content-type, and x-questlog-* are reserved. Change headers by removing and adding the hook again. Use --header-stdin and --secret-stdin separately. URL userinfo is rejected; use a custom header or query key.\n`questlog show d_\u2026` displays delivery status, attempts, HTTP status, next attempt, redacted target URL and event ids. Text is the default; --json prints JSON. Missing hook remove/test targets exit 3; missing quests/deliveries exit 1. hook label names the database.\nList output redacts userinfo/query strings. Removal deletes the target and deliveries.\nDefault scope is the database; `--tag` matches quest tags, never rumors.\n`--events` defaults to all types. The DB label defaults to the filename without its\npath/extension (`questlog` in memory); set it to a name suitable for disclosure.\n\n```cron\n* * * * * questlog tick\n```\n\nCron\'s PATH may need `$HOME/.local/bin/questlog tick --db /path/to/quests.db`.\nWatch defaults to 60 seconds (minimum 5); SIGINT/SIGTERM finishes the current tick.\nTick exits 0 even when deliveries need retries. Dry-run records nothing and sends nothing.\n\nEvents are detected from the model at tick time:\n\n- `quest.due`: an unresolved, undeleted quest reaches its effective due time (own `due_at`, otherwise its undeleted questline\'s due time).\n- `quest.overdue`: that effective deadline is strictly earlier than now and the quest remains unresolved.\n- `quest.unblocked`: an unresolved quest is available, all active prerequisites have succeeded or been deleted, and at least one prerequisite succeeded after its unlock was installed. Occurrence time is the latest active prerequisite success or not-before time, whichever is later.\n- `repeatable.spawned`: a concrete repeatable instance was created; occurrence time is its creation time. Tick first materializes due anchors through the existing spawn operation.\n- `rumor.captured`: an undeleted rumor was created; occurrence time is its creation time, even if subsequently settled or dismissed.\n\nPersistent event keys contain type, entity ids, and occurrence time. Restarts and repeated\nticks do not repeat occurrences. Removed transitions between ticks cannot be reconstructed.\nOnly occurrences at/after target creation are assigned; tags are evaluated at assignment.\nTick materializes due repeatables using the existing spawn path, including during preview\nwith rollback. Batches contain only ids, event types, timestamps, and the DB label:\n\n```json\n{"type":"questlog.events","db":"work","deliveryId":"d_\u2026","sentAt":"2026-10-28T10:00:00.000Z","events":[{"id":"e_\u2026","type":"quest.due","questId":12,"occurredAt":"2026-10-28T09:59:00.000Z"}]}\n```\n\nHeaders are `content-type: application/json`, `user-agent: questlog/<version>`,\n`x-questlog-delivery: <deliveryId>`, `x-questlog-timestamp: <unix seconds>`, and\n`x-questlog-signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + rawBody)>`.\nNo titles, objectives, details, or tag text are sent. `hook test` sends a logged `hook.test`\nevent immediately, ignoring the min gap. Add and test are CLI-only in the tool facade;\n`manage_hooks` supports list, remove, tick (with `dry_run`), and deliveries.\n\n2xx delivers. Timeout is 5 seconds. Failures retry after 30 s, 1 m, 2 m, 4 m, doubling\nto 1 h plus <1 s jitter, subject to the target\'s min gap. Eight failures mark failed.\nRetries keep the delivery id/events; new events queue behind them. Keep the last 500\ndelivered log entries per target and all pending/failed entries. Transactional claims\nlease work for two minutes. A crash after receipt may retry: dedupe at the receiver.\n\n### Verifying a delivery\n\nCompute HMAC-SHA256 over `timestamp + "." + rawBody` with the secret and compare in constant\ntime. Reject timestamps older than 5 minutes (and timestamps too far in the future), then\ndedupe on `x-questlog-delivery`. Use durable deduplication storage in a production receiver.\nThis 15-line Node example uses an in-memory set:\n\n```js\nimport { createHmac, timingSafeEqual } from \'node:crypto\';\nimport { createServer } from \'node:http\';\nconst secret = process.env.WEBHOOK_SECRET, seen = new Set();\ncreateServer(async (req, res) => {\n  const chunks = []; for await (const chunk of req) chunks.push(chunk);\n  const rawBody = Buffer.concat(chunks), h = req.headers;\n  const timestamp = h[\'x-questlog-timestamp\'], id = h[\'x-questlog-delivery\'];\n  const age = Date.now() / 1000 - Number(timestamp);\n  const expected = createHmac(\'sha256\', secret).update(timestamp + \'.\').update(rawBody).digest();\n  const signature = String(h[\'x-questlog-signature\'] || \'\');\n  const actual = Buffer.from(signature.slice(7), \'hex\');\n  if (!id || !/^\\d+$/.test(timestamp) || age > 300 || age < -300 || !/^sha256=[a-f0-9]{64}$/.test(signature) || actual.length !== expected.length || !timingSafeEqual(actual, expected)) { res.writeHead(401).end(); return; }\n  if (!seen.has(id)) { seen.add(id); console.log(JSON.parse(rawBody)); }\n  res.writeHead(204).end();\n}).listen(8080, \'127.0.0.1\');\n```\n'
+});
+
 // src/skills/skill_registry.ts
 var questlogSkills = [
+  webhooksSkill,
   archiveDeleteAndPruneSkill,
   chooseWorkShapeSkill,
   clarifyAmbiguousRequestsSkill,