@ghostpaw/questlog 0.6.2 → 0.8.0

package/README.md

@@ -1,12 +1,14 @@
+<a href="https://questlog.ghostpaw.dev/"><img src="https://raw.githubusercontent.com/GhostPawJS/questlog/main/.github/social-preview.png" alt="GhostPaw questlog: Your agent said it was done. Was it?" width="100%"></a>
+
 # @ghostpaw/questlog
 
-[![npm](https://img.shields.io/npm/v/@ghostpaw/questlog)](https://www.npmjs.com/package/@ghostpaw/questlog)
-[![node](https://img.shields.io/node/v/@ghostpaw/questlog)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/@ghostpaw/questlog)](LICENSE)
-[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![Live Demo](https://img.shields.io/badge/demo-live-06d6a0?style=flat&logo=github)](https://ghostpawjs.github.io/questlog)
-[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Fquestlog-06d6a0)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Fquestlog/versions/latest)
+[![npm](https://img.shields.io/npm/v/@ghostpaw/questlog?style=flat-square&labelColor=0a1119&color=62e6f2&label=npm)](https://www.npmjs.com/package/@ghostpaw/questlog) [![CI](https://img.shields.io/github/actions/workflow/status/GhostPawJS/questlog/ci.yml?branch=main&style=flat-square&labelColor=0a1119&label=CI)](https://github.com/GhostPawJS/questlog/actions/workflows/ci.yml) [![site](https://img.shields.io/badge/site-questlog.ghostpaw.dev-62e6f2?style=flat-square&labelColor=0a1119)](https://questlog.ghostpaw.dev/) [![runtime deps](https://img.shields.io/badge/runtime_deps-0-7af0b4?style=flat-square&labelColor=0a1119)](package.json) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Fquestlog-b39dff?style=flat-square&labelColor=0a1119)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Fquestlog/versions/latest) [![node](https://img.shields.io/badge/node-%E2%89%A524-93a5b9?style=flat-square&labelColor=0a1119)](https://nodejs.org) [![license](https://img.shields.io/npm/l/@ghostpaw/questlog?style=flat-square&labelColor=0a1119&color=93a5b9)](LICENSE)
+
+**Agent tasks as quests that finish only with a written outcome.**
+
+```bash
+npm install @ghostpaw/questlog
+```
 
 A unified task and calendar model for Node.js, built on SQLite.
 
@@ -63,13 +65,37 @@ initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
 
 ## CLI
 
+Install globally for the `ghostpaw-questlog` binary: `npm i -g @ghostpaw/questlog`.
+
 ```bash
-npx -y @ghostpaw/questlog tools
-npx -y @ghostpaw/questlog call capture_rumor '{"title":"Review release notes"}'
-npx -y @ghostpaw/questlog call search_questlog '{"query":"release notes"}'
+ghostpaw-questlog add --title "Review release notes" --tag release --due 2030-01-02
+ghostpaw-questlog list --limit 10
+ghostpaw-questlog search release notes --limit 5
+ghostpaw-questlog show 1
+ghostpaw-questlog done 1 --outcome "Reviewed changes"
+ghostpaw-questlog list --view quests.resolved --json
+```
+
+`add` accepts repeated `--tag` flags, `--objective` (defaults to the title),
+`--questline <id>`, and `--due` as an ISO date or milliseconds since epoch.
+`list` defaults to available quests; `list --help` lists all supported views.
+Its `--limit` caps text output; JSON preserves the full review tool result.
+`search --limit` caps matches in both formats. `show` inspects a quest id.
+`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
+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.
+
+The `call` command and the per-tool form still reach every tool and parameter:
+
+```bash
+ghostpaw-questlog tools
+ghostpaw-questlog call capture_rumor '{"title":"Review release notes"}'
+ghostpaw-questlog search_questlog --query "release notes"
 ```
 
-Install globally for the `ghostpaw-questlog` binary: `npm i -g @ghostpaw/questlog`.
 `ghostpaw-questlog mcp` starts the stdio server.
 
 ## Agent Skill
@@ -84,11 +110,79 @@ npx -y @ghostpaw/questlog skill > SKILL.md
 
 ## Install
 
-```bash
-npm install @ghostpaw/questlog
+The [npm package](https://www.npmjs.com/package/@ghostpaw/questlog) requires Node 24+:
+
+```sh
+npm install -g @ghostpaw/questlog
+npx -y @ghostpaw/questlog --help
 ```
 
-Requires **Node.js 24+** (uses the built-in `node:sqlite` module).
+As a library dependency: `npm install @ghostpaw/questlog`. It uses the built-in
+`node:sqlite` module, so there are no runtime dependencies.
+
+Standalone binaries are available from [GitHub Releases](https://github.com/GhostPawJS/questlog/releases)
+for linux-x64, linux-arm64, darwin-arm64, darwin-x64 and windows-x64.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh
+```
+
+```powershell
+irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex
+```
+
+Other release installers:
+
+```sh
+mise use -g github:GhostPawJS/questlog
+ubi --project GhostPawJS/questlog --exe ghostpaw-questlog --in ~/.local/bin
+eget GhostPawJS/questlog
+```
+
+For [aqua](https://aquaproj.github.io/docs/reference/registry-config/), define a
+`github_release` package in `aqua.yaml`:
+
+```yaml
+registries:
+  - name: questlog
+    type: local
+    path: questlog-registry.yaml
+packages:
+  - name: GhostPawJS/questlog@v0.8.0
+    registry: questlog
+```
+
+`questlog-registry.yaml`:
+
+```yaml
+packages:
+  - type: github_release
+    repo_owner: GhostPawJS
+    repo_name: questlog
+    asset: ghostpaw-questlog-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz
+    format: tar.gz
+    replacements: { amd64: x64 }
+    overrides:
+      - goos: windows
+        asset: ghostpaw-questlog-{{trimV .Version}}-windows-{{.Arch}}.zip
+        format: zip
+    files:
+      - name: ghostpaw-questlog
+```
+
+Install scripts verify SHA256SUMS. To verify a downloaded archive's
+[build attestation](https://cli.github.com/manual/gh_attestation_verify):
+
+```sh
+gh attestation verify <archive> -R GhostPawJS/questlog
+```
+
+Set `GHOSTPAW_VERIFY=attestation` for attestation verification in `install.sh`.
+Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser
+download on macOS, remove quarantine with
+`xattr -d com.apple.quarantine /path/to/ghostpaw-questlog`.
+Linux binaries require glibc 2.28+; use npx on Alpine.
+See the [binary build workflow](.github/workflows/release-binaries.yml).
 
 ## Quick Start
 
@@ -124,6 +218,16 @@ const dueSoon = read.listDueSoonQuests(db, 7 * 24 * 60 * 60 * 1000);
 const results = read.searchQuestlog(db, 'vendor');
 ```
 
+## Docs
+
+The live demo runs the library in your browser against an in-memory SQLite database. Each view below opens a different part of it:
+
+- [Dashboard](https://questlog.ghostpaw.dev/docs/): open, available, overdue and pending work
+- [Intake](https://questlog.ghostpaw.dev/docs/#/intake): capture rumors and triage them into quests
+- [Quests](https://questlog.ghostpaw.dev/docs/#/quests): start, block and finish quests with an outcome
+- [Planning](https://questlog.ghostpaw.dev/docs/#/planning): questlines and scheduling
+- [Search](https://questlog.ghostpaw.dev/docs/#/search): full-text search across the log
+
 ## The Model
 
 Seven concepts, strict separation of concerns: