human-hindsight 1.8.0 → 1.8.2

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)
@@ -44,6 +44,18 @@ No data move or re-distillation is required. Data-directory precedence is:
 a fresh installation. If both directories exist, the new one wins; use
 `--home` to choose explicitly. Directories are never merged automatically.
 
+In 1.8.2, existing preferences remain visible as **candidates**. Open the
+Preferences tab, check the evidence and scope, then **Accept**, **Edit**, or
+**Dismiss** each candidate. **Accepted instructions** builds a block from
+accepted global rules, with an optional project selection. Task-only choices
+stay out of standing instruction files. Reviews are saved in your library and
+survive browser restarts.
+
+Re-running `distill` refreshes results whose source content, prompt version,
+runner/model selection, or grouping mode changed. Older checkpoints are refreshed
+once because they have no input fingerprints. Hand-edited prompts are preserved;
+`--force` explicitly allows replacing them.
+
 Updating the old npm package installs the small compatibility wrapper, so
 `npx cc-hindsight@latest gui` also works. Both global commands can coexist:
 the main package owns `human-hindsight`, and the wrapper owns `cc-hindsight`.
@@ -106,7 +118,7 @@ Use `--no-follow-up` for one command at a time; pipes, dry runs, and scripted
 You can also start directly with distillation:
 
 ```bash
-npx human-hindsight distill    # offers to export first, then digest → cluster →
+npx human-hindsight@latest distill    # offers to export first, then digest → cluster →
                             # author (asks before any runner call), then shows
                             # offers the finished library in your browser
 ```
@@ -114,24 +126,25 @@ npx human-hindsight distill    # offers to export first, then digest → cluster
 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         # accepted global rules → CLAUDE.md
+npx human-hindsight@latest preferences --project my-app # include this project's accepted rules
+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
@@ -142,17 +155,58 @@ 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 titles and text, filter by domain, sort, and copy prompts with one click.
+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 preference candidates. Newly distilled candidates
+show exact human quotations, message references, and global/project/task scope;
+older observations are labeled for review. Candidates can come from failed or
+unfinished sessions too. You can bookmark either view and use your browser's
+Back and Forward buttons. **View all candidates** shows observations;
+**Accepted instructions** provides the reviewed block for `CLAUDE.md` or
+`AGENTS.md`. Changed source evidence returns a candidate to review.
+
+The terminal `preferences` command also exports accepted rules by default.
+Use `--include-unreviewed` explicitly to inspect draft observations in scripts.
+This flag does not accept them or change their review status.
+
+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 your accepted rules in a 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**. Every output rule links to its input preferences.
+Coverage, scope, explicit conditions, and direct contradictions are checked;
+invalid output gets one semantic correction attempt. Failed, empty, incomplete,
+or declined results leave the last saved result intact. Saved results are
+flagged when the selected inputs or their review status change. Legacy saved
+results remain readable and need regeneration before copying as reviewed
+instructions.
+
 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
@@ -162,8 +216,11 @@ The GUI uses Node's built-in HTTP server and bundled HTML/CSS/JavaScript:
 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.
+It listens only on `127.0.0.1` and stops with Ctrl+C. Browsing stays read-only.
+The single write action saves an explicit preference review to
+`library/preferences.review.json`; it requires the current browser session's
+token, matching origin, and a current candidate revision. The GUI never invokes
+an agent, edits source history, or writes an instruction file for you.
 
 ### Multiple backends (Claude Code + Codex + Kiro + OpenCode)
 
@@ -201,14 +258,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,
@@ -217,7 +274,13 @@ source defaults to `AGENTS.md`. The Codex runner uses `codex exec` with a JSON
 schema, a read-only sandbox, and ephemeral sessions; generated distill sessions
 do not become new source history. Claude supports current `structured_output`
 results as well as legacy `result` objects/strings and verbose event arrays.
-It disables session persistence when the installed CLI advertises the flag.
+The Claude runner requires current isolation controls, including `--safe-mode`.
+It runs from a private directory, disables tools, hooks, skills, and ambient
+MCP configuration, supplies a dedicated system instruction, and disables session
+persistence. Unsupported CLIs fail before any model call with an upgrade hint
+or the option to choose another runner. Updating Human Hindsight does not update
+Claude Code. Organization-managed policy remains authoritative; these controls
+do not override administrator policy or constitute an operating-system sandbox.
 
 ### OpenCode 1 and 2
 
@@ -258,10 +321,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
@@ -323,7 +386,7 @@ product:
   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
+- **Consent-gated LLM use.** `distill` states its estimated 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
   invoking anything (exit code 2).
@@ -402,10 +465,11 @@ chosen local agent CLI to its configured provider, using its authentication.
 
 **What does distill cost?**
 Whatever your chosen agent CLI costs you: it runs on your existing subscription or
-API credits. The consent prompt states the exact invocation count up front
+API credits. The consent prompt estimates the invocation count up front
 (one call per session digested, one to cluster, one per task authored), and
 `--dry-run` prints the same plan without running anything. Checkpoints mean an
-interrupted run isn't wasted money. Sessions too large for the input budget
+interrupted run can reuse completed work. Retries and windowed grouping may add
+calls. Sessions too large for the input budget
 (default 400k chars, `--input-budget`) are **refused before anything is
 spent**. Re-run with `--truncate=extreme` to cut them (recorded in
 provenance) or narrow the scope. Digest and author calls run 3 at a time by

package/dist/THIRD_PARTY_NOTICES.txt

@@ -1,140 +1,6 @@
 Human Hindsight includes the following open-source libraries.
 
 
-========================================================================
-@clack/prompts@1.7.0 — MIT
-
-MIT License
-
-MIT License Copyright (c) 2025-Present [Bombshell contributors](https://bomb.sh/team)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
-========================================================================
-@clack/core@1.4.3 — MIT
-
-MIT License
-
-MIT License Copyright (c) 2025-Present [Bombshell contributors](https://bomb.sh/team)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
-========================================================================
-fast-wrap-ansi@0.2.2 — MIT
-
-MIT License
-
-Copyright (c) 2025 James Garbutt
-
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-
-========================================================================
-fast-string-width@3.0.2 — MIT
-
-The MIT License (MIT)
-
-Copyright (c) 2024-present Fabio Spampinato
-
-Permission is hereby granted, free of charge, to any person obtaining a
-copy of this software and associated documentation files (the "Software"),
-to deal in the Software without restriction, including without limitation
-the rights to use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
-
-
-========================================================================
-fast-string-truncated-width@3.0.3 — MIT
-
-The MIT License (MIT)
-
-Copyright (c) 2024-present Fabio Spampinato
-
-Permission is hereby granted, free of charge, to any person obtaining a
-copy of this software and associated documentation files (the "Software"),
-to deal in the Software without restriction, including without limitation
-the rights to use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
-
-
-========================================================================
-sisteransi@1.0.5 — MIT
-
-MIT License
-
-Copyright (c) 2018 Terkel Gjervig Nielsen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-
 ========================================================================
 citty@0.2.2 — MIT