| 1 | --- |
| 2 | title: Digg NUX must match printing-press-library install paths and agent subprocess PATH |
| 3 | date: 2026-06-17 |
| 4 | category: docs/solutions/integration-issues |
| 5 | module: lib/setup_wizard |
| 6 | problem_type: integration_issue |
| 7 | component: development_workflow |
| 8 | severity: medium |
| 9 | symptoms: |
| 10 | - Digg source silently off after first-run setup reports success on Hermes or OpenClaw |
| 11 | - Users who already installed pp-digg via printing-press-library still see Digg missing from --diagnose available_sources |
| 12 | - Setup wizard probed ~/go/bin while the catalog installer writes to ~/.local/bin (printing-press-library 0.1.16+) |
| 13 | - OpenClaw setup --openclaw path skipped Digg install entirely |
| 14 | root_cause: config_error |
| 15 | resolution_type: code_fix |
| 16 | related_components: |
| 17 | - lib/pipeline |
| 18 | - lib/digg |
| 19 | - CONFIGURATION.md |
| 20 | tags: |
| 21 | - digg |
| 22 | - setup-wizard |
| 23 | - printing-press-library |
| 24 | - agent-path |
| 25 | - hermes |
| 26 | - openclaw |
| 27 | - nux |
| 28 | - optional-cli-sources |
| 29 | --- |
| 30 | |
| 31 | # Digg NUX must match printing-press-library install paths and agent subprocess PATH |
| 32 | |
| 33 | ## Problem |
| 34 | |
| 35 | First-run setup auto-install for `digg-pp-cli` could report success while the engine still omitted Digg, especially on Hermes and OpenClaw where the agent subprocess PATH often excludes `$HOME/.local/bin`. The initial PR also used the deprecated `@mvanhorn/printing-press` package and probed legacy `~/go/bin` fallbacks instead of the current Printing Press default install dir. |
| 36 | |
| 37 | ## Symptoms |
| 38 | |
| 39 | - `--diagnose` `available_sources` lacks `digg` even though pp-digg or setup "installed" the CLI. |
| 40 | - Hermes/OpenClaw users with a prior `npx @mvanhorn/printing-press-library install digg --cli-only` run hit false failures or false "now active" messages depending on probe logic. |
| 41 | - OpenClaw `setup --openclaw` never attempted Digg install (desktop NUX only). |
| 42 | |
| 43 | ## What Didn't Work |
| 44 | |
| 45 | - **Treating "binary exists somewhere" as installed** — `pipeline.available_sources()` and `digg._is_available()` gate on `shutil.which("digg-pp-cli")` only. Probing `~/go/bin` without PATH visibility produced false positives. |
| 46 | - **Assuming Hermes vs OpenClaw use different binary locations** — both harnesses use the same printing-press-library default (`$HOME/.local/bin`); only the focused pp-digg *skill* wiring differs. |
| 47 | - **Using `@mvanhorn/printing-press`** — superseded by `@mvanhorn/printing-press-library`; install defaults moved from `$GOPATH/bin` to `$HOME/.local/bin` in npm 0.1.16. |
| 48 | |
| 49 | ## Solution |
| 50 | |
| 51 | Align setup wizard with the catalog installer and the engine PATH gate: |
| 52 | |
| 53 | 1. **Pin installer:** `npx -y @mvanhorn/printing-press-library@0.1.16 install digg --cli-only` (`--cli-only` only — last30days embeds Digg as an engine source, not pp-digg skill). |
| 54 | 2. **Split outcomes:** `already_installed` / `installed` only when `shutil.which` resolves; `installed_off_path` when the binary exists under known dirs (`~/.local/bin`, legacy `~/go/bin`, Windows PrintingPress bin) but is not PATH-visible; surface `digg_path` and PATH-restart guidance in status text. |
| 55 | 3. **OpenClaw parity:** `run_openclaw_setup()` runs the same `_install_digg_cli()` and returns `digg_cli`, `digg_action`, optional `digg_path`. |
| 56 | 4. **Docs:** CONFIGURATION.md, SKILL.md Step 0, HERMES_SETUP.md, AGENTS.md rule for CLI-gated sources. |
| 57 | |
| 58 | Key helper shape in `setup_wizard.py`: |
| 59 | |
| 60 | ```python |
| 61 | def _digg_on_path() -> Optional[str]: |
| 62 | return shutil.which(DIGG_CLI_BIN) # engine gate |
| 63 | |
| 64 | def _digg_off_path_binary() -> Optional[str]: |
| 65 | for candidate in _digg_bin_candidate_paths(): # ~/.local/bin first |
| 66 | if candidate.is_file() and os.access(candidate, os.X_OK): |
| 67 | return str(candidate) |
| 68 | return None |
| 69 | ``` |
| 70 | |
| 71 | ## Why This Works |
| 72 | |
| 73 | The engine never reads "is pp-digg skill installed?" — every research run shells out to `digg-pp-cli` by name on PATH. Printing Press already installs to a managed user bin dir and warns when that dir is off PATH; last30days setup must mirror that contract instead of inventing a separate success definition. Detecting off-PATH binaries lets setup reuse prior pp-digg installs without lying about activation. |
| 74 | |
| 75 | ## Prevention |
| 76 | |
| 77 | - When adding NUX auto-install for a CLI-gated source, match the upstream installer's default bin dir and pin the npm semver. |
| 78 | - Success messaging must use the same probe as `available_sources()` (`shutil.which`), with a separate off-PATH outcome when the binary exists on disk. |
| 79 | - Cover Hermes/OpenClaw in tests with redirected `HOME` and mocked PATH; add OpenClaw JSON fields when server setup should mirror desktop NUX. |
| 80 | - Search `docs/solutions/` for `digg`, `setup-wizard`, and `agent-path` before changing optional-source onboarding. |
| 81 |