human-hindsight 1.7.0 → 1.8.1

package/README.md

@@ -13,7 +13,7 @@
 </p>
 
 ```bash
-npx human-hindsight
+npx human-hindsight@latest
 ```
 
 Human Hindsight mines your coding-agent session history (Claude Code, Codex, Kiro, OpenCode)
@@ -87,35 +87,51 @@ The second prompt was knowable at t=0. You just hadn't written it yet.
 
 ## Quickstart
 
-One command builds the whole library and shows it to you when it's done:
+Start the guided terminal workflow:
 
 ```bash
-npx human-hindsight distill    # offers to export first, then digest → cluster →
+npx human-hindsight@latest
+```
+
+After scanning, the CLI suggests **export** and asks whether to run it.
+Type `y` to continue. Export offers **distill**, and a successful distillation
+offers the browser library. Your library directory, source, project filter,
+runner, and model stay selected through the handoffs.
+
+Distillation still shows its model-call plan and asks for spending consent.
+Follow-up offers default to No and appear only in an interactive terminal.
+Use `--no-follow-up` for one command at a time; pipes, dry runs, and scripted
+`--yes` invocations never start these follow-up commands automatically.
+
+You can also start directly with distillation:
+
+```bash
+npx human-hindsight@latest distill    # offers to export first, then digest → cluster →
                             # author (asks before any runner call), then shows
-                            # you the finished library
+                            # offers the finished library in your browser
 ```
 
 Prefer to drive each stage yourself? The pipeline is just three verbs:
 
 ```bash
-npx human-hindsight            # 1. scan: inventory your projects (read-only)
-npx human-hindsight export     # 2. export: human-only markdown per session
-npx human-hindsight distill    # 3. distill: digest → cluster → author (asks first)
+npx human-hindsight@latest            # 1. scan: inventory your projects (read-only)
+npx human-hindsight@latest export     # 2. export: human-only markdown per session
+npx human-hindsight@latest distill    # 3. distill: digest → cluster → author (asks first)
 ```
 
 Then browse and curate the results:
 
 ```bash
-npx human-hindsight list                # your library (✎ edited / ▲▼ rating badges)
-npx human-hindsight gui                 # browse, search, and copy in your browser
-npx human-hindsight show <slug>         # read a oneshot
-npx human-hindsight copy <slug>         # → clipboard, paste into a fresh session
-npx human-hindsight edit <slug>         # open in $EDITOR; your edits are protected
-npx human-hindsight rate <slug> up      # record a verdict (up|down)
-npx human-hindsight prune               # remove orphaned entries (asks first)
-npx human-hindsight preferences         # → CLAUDE.md block
-npx human-hindsight status              # pipeline funnel + orphan/skip flags
-npx human-hindsight retention           # optional: preview longer local retention
+npx human-hindsight@latest list                # your library (✎ edited / ▲▼ rating badges)
+npx human-hindsight@latest gui                 # browse, search, and copy in your browser
+npx human-hindsight@latest show <slug>         # read a oneshot
+npx human-hindsight@latest copy <slug>         # → clipboard, paste into a fresh session
+npx human-hindsight@latest edit <slug>         # open in $EDITOR; your edits are protected
+npx human-hindsight@latest rate <slug> up      # record a verdict (up|down)
+npx human-hindsight@latest prune               # remove orphaned entries (asks first)
+npx human-hindsight@latest preferences         # → CLAUDE.md block
+npx human-hindsight@latest status              # pipeline funnel + orphan/skip flags
+npx human-hindsight@latest retention           # optional: preview longer local retention
 ```
 
 Requires Node 22.13+ on Node 22, or Node 23.4+ on newer releases, on macOS or Linux (Windows is untested and currently
@@ -126,20 +142,55 @@ with a consent prompt (or your explicit `--yes`).
 ### A small local library viewer
 
 ```bash
-npx human-hindsight gui                    # start locally and open your browser
-npx human-hindsight gui --no-open          # print the address without opening it
-npx human-hindsight gui --port 3210        # choose a port (default: any available port)
-npx human-hindsight gui --home /path/to/library-home
+npx human-hindsight@latest gui                    # start locally and open your browser
+npx human-hindsight@latest gui --no-open          # print the address without opening it
+npx human-hindsight@latest gui --port 3210        # choose a port (default: any available port)
+npx human-hindsight@latest gui --home /path/to/library-home
 ```
 
-Search prompt titles and text, filter by domain, sort, and copy the prompt
-body with one click. The viewer shows your existing library, including local
-edits, ratings, and session counts. Use **Refresh** after changing files.
-Light and dark appearance follow your system setting, and the layout works
-on narrow screens. Press `/` to focus search.
+Switch between **Prompts** and **Preferences** to search, filter by domain,
+sort, and copy items with one click. Preferences are deduplicated across tasks
+and can be sorted by frequency, recency, or text. Search also matches their
+evidence and source prompt titles.
+Domain filters start with broad categories and reveal optional subdomains,
+up to five levels deep. Selecting a parent includes all its descendants.
+Existing flat labels are grouped locally without changing the library or
+making a model call; newly distilled sessions use hierarchical domain paths.
+**Preview** renders Markdown headings, lists, tables, links, blockquotes, task
+lists, and code blocks. **Markdown** shows the original source. Copy always
+uses that original Markdown, including when the preview is selected.
+
+Each prompt links to its observed preferences; each preference shows its
+evidence and links back to the source prompts. You can bookmark either view
+and use your browser's Back and Forward buttons. **View all preferences**
+opens a combined Markdown block ready to copy into `CLAUDE.md` or `AGENTS.md`.
+
+The tips bar starts with an open-source and privacy reminder, then rotates
+through quick tips with copyable `npx human-hindsight@latest` commands.
+Pause it, hide it, or restore it with **Show tips**. Hidden tips stay hidden
+when you reload the same local address.
+
+Export and distill show an open-source/privacy reminder near the start.
+Interactive terminals get a colorful elapsed-time progress indicator during
+scanning, export, and model work; redirected output stays free of animation.
+
+Consolidation is optional: `npx human-hindsight@latest preferences --consolidate`
+uses one call through your own coding harness and its configured provider,
+with consent and the subscription/credit cost explained first. Successful
+results are saved, with their Markdown and input metadata, in
+`<home>/library/preferences.consolidated.json`. Refresh the GUI to open
+**Saved consolidation**. It flags results whose observed preferences have
+changed. Failed or declined calls leave the last saved result intact.
+
+The viewer uses a minimal black-and-white palette and system monospace fonts.
+Light and dark appearance follow your system setting. Local edits, ratings,
+and session counts remain visible. Use **Refresh** after changing files and
+press `/` to focus search.
 
 The GUI uses Node's built-in HTTP server and bundled HTML/CSS/JavaScript:
-no additional dependencies, frontend framework, database, or external assets.
+no frontend framework, database, font download, or external assets.
+Markdown parsing and sanitization ship inside the bundle. Raw HTML stays
+inert and remote images are represented by their alt text, without fetching them.
 It listens only on `127.0.0.1`, serves a read-only library API, and stops with
 Ctrl+C. The GUI doesn't invoke an agent or modify your library.
 
@@ -179,14 +230,14 @@ then falls back in the order Claude → Codex → Kiro → OpenCode. Models are
 with `--model`; without it, the chosen CLI uses its configured default.
 
 ```bash
-npx human-hindsight export --source codex
-npx human-hindsight distill --source codex --runner codex
-npx human-hindsight distill --source claude --runner codex
-npx human-hindsight preferences --target codex  # AGENTS.md; alias of --target agents
-npx human-hindsight export --source opencode
-npx human-hindsight distill --source opencode --runner opencode
-npx human-hindsight distill --source claude --runner opencode --model provider/model
-npx human-hindsight preferences --target opencode  # AGENTS.md
+npx human-hindsight@latest export --source codex
+npx human-hindsight@latest distill --source codex --runner codex
+npx human-hindsight@latest distill --source claude --runner codex
+npx human-hindsight@latest preferences --target codex  # AGENTS.md; alias of --target agents
+npx human-hindsight@latest export --source opencode
+npx human-hindsight@latest distill --source opencode --runner opencode
+npx human-hindsight@latest distill --source claude --runner opencode --model provider/model
+npx human-hindsight@latest preferences --target opencode  # AGENTS.md
 ```
 
 `preferences --target claude|codex|kiro|opencode|agents` emits a `CLAUDE.md` block,
@@ -236,10 +287,10 @@ OpenCode preferences can go into the project's `AGENTS.md`, or the global
 ### Optional: keep more local history
 
 ```bash
-npx human-hindsight retention                    # read-only preview
-npx human-hindsight retention --apply            # preview, then confirm
-npx human-hindsight retention --apply --yes      # explicit opt-in for scripting
-npx human-hindsight retention --source codex --apply
+npx human-hindsight@latest retention                    # read-only preview
+npx human-hindsight@latest retention --apply            # preview, then confirm
+npx human-hindsight@latest retention --apply --yes      # explicit opt-in for scripting
+npx human-hindsight@latest retention --source codex --apply
 ```
 
 The default reviews existing tool directories. An explicit `--source` can
@@ -294,17 +345,13 @@ product:
   (`~/.human-hindsight`). No hosted service, accounts, or telemetry. The only network
   traffic is through your chosen agent CLI during consented distillation or
   preference consolidation.
-- **Five runtime dependencies.** [`citty`](https://github.com/unjs/citty)
-  (zero-dependency CLI framework), [`zod`](https://zod.dev) (schema
-  validation), and [`@clack/prompts`](https://github.com/bombshell-dev/clack)
-  (progress spinners), plus [`smol-toml`](https://github.com/squirrelchat/smol-toml)
-  for safely preserving Codex configuration values during optional retention
-  edits, and [`jsonc-parser`](https://github.com/microsoft/node-jsonc-parser)
-  for reading OpenCode provider configuration without executing it. SQLite
-  comes from Node itself; no database addon or native compilation is required. All five are
-  exact-pinned, and the entire transitive tree ships locked via
-  `npm-shrinkwrap.json`. The whole data path is small enough to audit in one
-  sitting.
+- **One self-contained npm package.** JavaScript libraries are bundled into
+  the CLI; the published package has no npm dependencies or installation
+  scripts. SQLite comes from Node. Starting the app does not install compilers,
+  platform bindings, or build tools. The development dependency tree is pinned
+  in the repository's `package-lock.json`, which is not published. Bundled
+  libraries include citty, Zod, Clack, smol-toml, jsonc-parser, Marked, and
+  DOMPurify; their license texts ship in `dist/THIRD_PARTY_NOTICES.txt`.
 - **Consent-gated LLM use.** `distill` states the exact invocation count and
   waits for `[y/N]` before anything runs on your subscription/credits.
   `--dry-run` shows the full plan for free. If you decline, it exits without