@ghostpaw/questlog 0.9.1 → 0.10.1

package/skills/questlog/SKILL.md

@@ -1,18 +1,35 @@
 ---
 name: questlog
-description: "Manage local tasks, calendar commitments, and recurring work. Use when planning, executing, reviewing, or organizing work."
+description: "Use the release binary ghostpaw-questlog to manage local tasks, calendar commitments, and recurring work. Use when planning, executing, reviewing, or organizing work."
 license: "MIT"
-compatibility: "Node.js 24 or newer. MCP stdio or ghostpaw-questlog CLI."
+compatibility: "Release binary ghostpaw-questlog (no runtime needed); MCP stdio via ghostpaw-questlog mcp."
 ---
 
 # questlog
 
-No install? Use `npx -y @ghostpaw/questlog <command>`.
+## Install
+
+Linux/macOS:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh
+```
+
+Installs `~/.local/bin/ghostpaw-questlog` after checking SHA256SUMS.
+
+Windows x64 (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex
+```
+
+Run tools as `ghostpaw-questlog ...`; use `~/.local/bin/ghostpaw-questlog` if it is not on PATH.
+
 `questlog` and `ghostpaw-questlog` are the same binary.
 
 - `questlog search <words>` before `add` to avoid duplicates.
-- `questlog add --title "..." --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.
+- `ghostpaw-questlog add "..." --tag a,b --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 <id> --outcome "..."`
 - `questlog search <words>`
 - `questlog show <id>`
@@ -20,6 +37,7 @@ No install? Use `npx -y @ghostpaw/questlog <command>`.
 - Exit codes: 0 ok / 1 error / 2 usage / 3 needs input.
 - Database: `~/.ghostpaw/questlog.db`; override with `--db` or `GHOSTPAW_QUESTLOG_DB`.
 - Use one database per agent or project.
+- 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
 
@@ -29,10 +47,32 @@ Questlog manages local tasks, calendar commitments, and recurring work. Search b
 
 MCP: connect to ghostpaw-questlog, then call a tool by name with its JSON arguments.
 
-CLI: `ghostpaw-questlog call <tool> '<JSON object>'` or `ghostpaw-questlog <tool> --parameter value` (without a global install: `npx -y @ghostpaw/questlog <tool> ...`).
+CLI: `ghostpaw-questlog call <tool> '<JSON object>'` or `ghostpaw-questlog <tool> --parameter value`.
 
 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.
@@ -50,6 +90,10 @@ Read-only.
 | kinds | array | no | Optional entity kinds to search. |
 | mode | string | no | browse, identify_one. Whether to browse results normally or ask for clarification when several matches are found. |
 
+```sh
+ghostpaw-questlog call search_questlog '{"query":"release"}'
+```
+
 ### review_questlog
 
 Review one operational questlog surface such as available quests, open rumors, blocked work, or due repeatable anchors.
@@ -62,10 +106,18 @@ 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. |
+| filters.includeDeleted | boolean | no | Whether deleted quests should be included in quest views. |
+| filters.dayAt | integer | no | UTC timestamp within the day to review for scheduled-for-day. |
 | now | integer | no | Optional evaluation timestamp for time-sensitive views. |
 
+```sh
+ghostpaw-questlog call review_questlog '{"view":"deliveries"}'
+```
+
 ### inspect_questlog_item
 
 Inspect one specific questlog item in depth and return its richer structured detail and important related refs.
@@ -79,9 +131,15 @@ Read-only.
 | Parameter | Type | Required | Values / description |
 | --- | --- | --- | --- |
 | target | object | yes | The specific item to inspect. |
+| target.kind | string | yes | quest, questline, repeatable_quest, rumor. The kind of item to inspect. |
+| target.id | integer | yes | The numeric id of the item to inspect. |
 | detailLevel | string | no | compact, full. How much detail to return. |
 | now | integer | no | Optional evaluation timestamp for time-sensitive detail. |
 
+```sh
+ghostpaw-questlog call inspect_questlog_item '{"target":{"kind":"quest","id":1}}'
+```
+
 ### capture_rumor
 
 Capture uncertain incoming work as a rumor so it can be triaged later without prematurely turning it into committed execution.
@@ -98,6 +156,10 @@ Writes: writes_state.
 | details | string | no | Optional supporting context that explains why the rumor might matter. |
 | now | integer | no | Optional creation timestamp for the rumor. |
 
+```sh
+ghostpaw-questlog call capture_rumor '{"title":"Review release notes"}'
+```
+
 ### shape_work
 
 Create a quest (with timing, tags, and objective in one call), create a questline, settle a rumor into concrete work, or manage quest-questline membership. Use create_quest for clear commitments — include tags and timing directly to avoid follow-up calls.
@@ -114,7 +176,11 @@ Writes: writes_state.
 | questId | integer | no | Quest to attach or detach. |
 | questlineId | integer | no | Questline that should receive the quest. |
 | quest | object | no |  |
+| quest.title | string | yes | Title for the new quest. |
+| quest.objective | string | yes | Objective for the new quest. |
 | questline | object | no |  |
+| 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. |
@@ -123,6 +189,12 @@ Writes: writes_state.
 | title | string | no | New title for the update_rumor action. |
 | details | string | no | New or enriched context text for the update_rumor action. |
 
+```sh
+ghostpaw-questlog call shape_work '{"action":"attach_quest_to_questline","questId":1,"questlineId":1}'
+ghostpaw-questlog call shape_work '{"action":"create_quest","quest":{"title":"Review release notes","objective":"Check changes against the release"}}'
+ghostpaw-questlog call shape_work '{"action":"create_questline","questline":{"title":"Review release notes"}}'
+```
+
 ### plan_quest
 
 Refine a quest by revising its objective before actual start or by changing its temporal planning fields.
@@ -146,6 +218,11 @@ Writes: writes_state.
 | estimateSeconds | integer | no | Optional active-effort estimate in seconds. |
 | now | integer | no | Optional update timestamp. |
 
+```sh
+ghostpaw-questlog call plan_quest '{"action":"revise_objective","questId":1,"objective":"Check changes against the release"}'
+ghostpaw-questlog call plan_quest '{"action":"set_time","questId":1}'
+```
+
 ### run_quest
 
 Run quest lifecycle actions such as starting, logging effort, finishing, abandoning, or abandoning and spawning follow-up quests atomically.
@@ -168,6 +245,12 @@ Writes: writes_state.
 | 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. |
 
+```sh
+ghostpaw-questlog call run_quest '{"action":"start","questId":1}'
+ghostpaw-questlog call run_quest '{"action":"log_effort","questId":1,"effortSeconds":1}'
+ghostpaw-questlog call run_quest '{"action":"finish","questId":1,"outcome":"release"}'
+```
+
 ### organize_work
 
 Organize grouping and dependency structure by updating questlines or changing hard unlock prerequisites between concrete quests.
@@ -192,6 +275,12 @@ Writes: writes_state.
 | fromQuestIds | array | no | Full prerequisite quest id set. |
 | now | integer | no | Optional timestamp. |
 
+```sh
+ghostpaw-questlog call organize_work '{"action":"add_unlock","fromQuestId":1,"toQuestId":2}'
+ghostpaw-questlog call organize_work '{"action":"archive_questline","questlineId":1}'
+ghostpaw-questlog call organize_work '{"action":"remove_unlock","fromQuestId":1,"toQuestId":2}'
+```
+
 ### manage_repeatable
 
 Manage recurring work definitions by creating, updating, previewing, spawning, or archiving repeatable quests.
@@ -207,6 +296,10 @@ 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.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. |
+| repeatableQuest.anchorAt | integer | yes | Recurrence anchor timestamp. |
 | title | string | no | Optional new title for the update action. |
 | objective | string | no | Optional new objective for the update action. |
 | questlineId | integer | no | Optional new questline id. |
@@ -221,6 +314,12 @@ Writes: writes_state.
 | archivedAt | integer | no | Optional archive timestamp. |
 | now | integer | no | Evaluation or update timestamp. |
 
+```sh
+ghostpaw-questlog call manage_repeatable '{"action":"archive","repeatableQuestId":1}'
+ghostpaw-questlog call manage_repeatable '{"action":"create","repeatableQuest":{"title":"Review release notes","objective":"Check changes against the release","rrule":"FREQ=WEEKLY","anchorAt":1800000000000}}'
+ghostpaw-questlog call manage_repeatable '{"action":"preview_due"}'
+```
+
 ### tag_work
 
 Classify work by adding, removing, or replacing tags on quests and by replacing the future tag template set on repeatable quests.
@@ -235,9 +334,17 @@ Writes: writes_state.
 | --- | --- | --- | --- |
 | action | string | yes | add, remove, replace. Action to perform. |
 | target | object | yes |  |
+| 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. |
 | now | integer | no | Optional timestamp for the tag mutation. |
 
+```sh
+ghostpaw-questlog call tag_work '{"action":"add","target":{"id":1,"kind":"quest"},"tagNames":["release"]}'
+ghostpaw-questlog call tag_work '{"action":"remove","target":{"id":1,"kind":"quest"},"tagNames":["release"]}'
+ghostpaw-questlog call tag_work '{"action":"replace","target":{"id":1,"kind":"quest"},"tagNames":["release"]}'
+```
+
 ### reward_work
 
 Manage rewards by adding, updating, removing, or claiming quest rewards, or by replacing future reward templates on repeatable quests.
@@ -252,11 +359,22 @@ Writes: writes_state.
 | --- | --- | --- | --- |
 | action | string | yes | add, claim, remove, replace_repeatable_template, update. Action to perform. |
 | target | object | yes |  |
+| target.id | integer | yes | Target entity id. |
+| target.kind | string | yes | quest, reward, repeatable_quest. Target kind. |
 | reward | object | no |  |
+| 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. |
 | claimedAt | integer | no | Optional claim timestamp. |
 | now | integer | no | Optional timestamp for removal or template replacement. |
 
+```sh
+ghostpaw-questlog call reward_work '{"action":"add","target":{"id":1,"kind":"quest"},"reward":{"kind":"release","name":"release"}}'
+ghostpaw-questlog call reward_work '{"action":"claim","target":{"id":1,"kind":"quest"}}'
+ghostpaw-questlog call reward_work '{"action":"remove","target":{"id":1,"kind":"quest"}}'
+```
+
 ### retire_work
 
 Hide an item from normal active operation without rewriting history by soft-deleting a rumor, quest, questline, or repeatable quest.
@@ -271,35 +389,42 @@ Writes: writes_state.
 | --- | --- | --- | --- |
 | action | string | yes | hide. The retirement action to perform. |
 | target | object | yes | The target to hide. |
+| target.kind | string | yes | quest, questline, repeatable_quest, rumor. The kind of item to hide. |
+| target.id | integer | yes | The numeric id of the item to hide. |
 | deletedAt | integer | no | Optional timestamp to record when the item became hidden. |
 
+```sh
+ghostpaw-questlog call retire_work '{"action":"hide","target":{"kind":"quest","id":1}}'
+```
+
 ### Workflow guides
 
-- [archive-delete-and-prune](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.
-- [choose-work-shape](references/choose-work-shape.md): Choose the right structure for new work by separating uncertainty, one-shot execution, multi-step arcs, and recurring patterns.
-- [clarify-ambiguous-requests](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.
-- [close-work-and-claim-outcomes](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.
-- [create-concrete-quest](references/create-concrete-quest.md): Create real, bounded executable quests only when the objective is concrete enough to execute without interpretive guesswork.
-- [detect-slips-and-staleness](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.
-- [escalate-and-unblock](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.
-- [frame-initiative-questline](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.
-- [handle-exceptions-and-weird-cases](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.
-- [intake-triage](references/intake-triage.md): Triage new asks, ideas, and vague incoming work into the right next step without prematurely committing execution structure.
-- [maintain-clear-ownership](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.
-- [manage-approvals-and-promises](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.
-- [plan-successor-work](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.
-- [plan-time-correctly](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.
-- [prioritize-across-streams](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.
-- [protect-capacity-and-focus](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.
-- [recover-from-modeling-mistakes](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.
-- [report-status-and-manage-expectations](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.
-- [revise-or-reshape-commitment](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.
-- [run-operational-review](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.
-- [run-recurring-rhythms](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.
-- [search-and-retrieve-context](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.
-- [sequence-with-unlocks](references/sequence-with-unlocks.md): Model hard sequencing with unlocks between concrete quests so blocked and available work stay truthful and reviewable.
-- [settle-rumor-into-structure](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.
-- [tag-and-filter-portfolios](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` ([webhooks](references/webhooks.md)): Configure signed outbound event webhooks and verify deliveries.
+- `ghostpaw-questlog skill archive-delete-and-prune` ([archive-delete-and-prune](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](references/tag-and-filter-portfolios.md)): Use tags for cross-cutting classification and portfolio filtering without confusing tags for status, timing, or dependency modeling.
 
 ### Principles
 
@@ -307,3 +432,7 @@ Writes: writes_state.
 - Read before you prescribe.
 - Protect history when reality changes.
 - Close the last mile, not just the main work.
+
+## Without the binary
+
+Use `npx -y @ghostpaw/questlog ...` in npm-based environments (Node 24+). Harnesses that embed it in code can import `@ghostpaw/questlog` as a library.

package/skills/questlog/references/webhooks.md

@@ -0,0 +1,91 @@
+# Webhooks
+
+Use `questlog` to configure opt-in outbound automation. No server or scheduler is added.
+No targets means no network calls. `manage_hooks` supports list, remove, tick with
+`dry_run`, and deliveries; add/test are CLI-only. `review_questlog` view `deliveries`
+and `questlog show <id>` expose pending/failed deliveries.
+
+```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
+```
+
+`hook add` prints its random 32-byte signing secret once, also as `secret` in `--json`.
+Save it securely. `--secret-stdin` supplies one via stdin; there is no secret flag.
+List output redacts userinfo/query strings. Removal deletes the target and deliveries.
+Default scope is the database; `--tag` matches quest tags, never rumors.
+`--events` defaults to all types. The DB label defaults to the filename without its
+path/extension (`questlog` in memory); set it to a name suitable for disclosure.
+
+```cron
+* * * * * questlog tick
+```
+
+Cron's PATH may need `$HOME/.local/bin/questlog tick --db /path/to/quests.db`.
+Watch defaults to 60 seconds (minimum 5); SIGINT/SIGTERM finishes the current tick.
+Tick exits 0 even when deliveries need retries. Dry-run records nothing and sends nothing.
+
+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.
+
+Persistent event keys contain type, entity ids, and occurrence time. Restarts and repeated
+ticks do not repeat occurrences. Removed transitions between ticks cannot be reconstructed.
+Only occurrences at/after target creation are assigned; tags are evaluated at assignment.
+Tick materializes due repeatables using the existing spawn path, including during preview
+with rollback. Batches contain only ids, event 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. Timeout is 5 seconds. Failures retry after 30 s, 1 m, 2 m, 4 m, doubling
+to 1 h plus <1 s jitter, subject to the target's min gap. Eight failures mark failed.
+Retries keep the delivery id/events; new events queue behind them. Keep the last 500
+delivered log entries per target and all pending/failed entries. Transactional claims
+lease work for two minutes. A crash after receipt may retry: dedupe at the receiver.
+
+### 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/dist/chunk-KRQDV4KF.js

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-function resolveQuestlogDbPath(options = {}) {
-  return options.flag ?? ((options.env ?? process.env).GHOSTPAW_QUESTLOG_DB || join(homedir(), ".ghostpaw", "questlog.db"));
-}
-
-// src/version.ts
-var questlogVersion = "0.9.1";
-
-// src/surfaces/surface_types.ts
-function isErrorResult(result) {
-  return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
-}
-
-// src/surfaces/validate_input.ts
-function validateInput(schema, input, path = "$") {
-  const errors = [];
-  const matchesType = (type) => {
-    switch (type) {
-      case "object":
-        return typeof input === "object" && input !== null && !Array.isArray(input);
-      case "array":
-        return Array.isArray(input);
-      case "integer":
-        return typeof input === "number" && Number.isInteger(input);
-      case "number":
-        return typeof input === "number" && Number.isFinite(input);
-      case "null":
-        return input === null;
-      default:
-        return typeof input === type;
-    }
-  };
-  if (schema.type && !(Array.isArray(schema.type) ? schema.type : [schema.type]).some(matchesType)) {
-    return [`${path}: expected ${String(schema.type)}`];
-  }
-  if (schema.enum && !schema.enum.some((value) => JSON.stringify(value) === JSON.stringify(input)))
-    errors.push(`${path}: expected one of ${JSON.stringify(schema.enum)}`);
-  if (schema.oneOf && !schema.oneOf.some((branch) => validateInput(branch, input, path).length === 0))
-    errors.push(`${path}: must match at least one schema branch`);
-  if (typeof input === "object" && input !== null && !Array.isArray(input)) {
-    const record = input;
-    for (const name of schema.required ?? [])
-      if (!Object.hasOwn(record, name)) errors.push(`${path}.${name}: required`);
-    for (const [name, property] of Object.entries(schema.properties ?? {}))
-      if (Object.hasOwn(record, name))
-        errors.push(...validateInput(property, record[name], `${path}.${name}`));
-  }
-  if (Array.isArray(input) && schema.items)
-    input.forEach((value, index) => {
-      errors.push(...validateInput(schema.items, value, `${path}[${index}]`));
-    });
-  return errors;
-}
-
-export { isErrorResult, questlogVersion, resolveQuestlogDbPath, validateInput };

package/dist/open_questlog_db-SH3DAU4C.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export { openQuestlogDb } from './chunk-3B6FMHZU.js';