Skip to content

docs: document ripgrep and ImageMagick as external tools; add both to Doctor - #1660

Open
elhoim wants to merge 1 commit into
danielmiessler:mainfrom
elhoim:docs/document-ripgrep-imagemagick
Open

docs: document ripgrep and ImageMagick as external tools; add both to Doctor#1660
elhoim wants to merge 1 commit into
danielmiessler:mainfrom
elhoim:docs/document-ripgrep-imagemagick

Conversation

@elhoim

@elhoim elhoim commented Jul 26, 2026

Copy link
Copy Markdown

GETTING-STARTED.md is the page that lists the external tools doctrine uses, and it opens with a promise: "None are required — every one degrades honestly when absent." Two tools that shipped code shells out to were missing from it, and from Doctor's registry.

ripgrep

ContextSearch/Tools/ContextSearch.ts spawns rg directly, as do the work sweep and UpdateModels.ts's drift scan. LifeOS indexes through the filesystem instead of a vector store, so this is load-bearing rather than a style preference — the architecture doc says as much ("fast search such as with Ripgrep can give us everything people usually want from a RAG system").

Worth separating: the built-in Grep tool is independently ripgrep-backed and unaffected. This is only about the tools that spawn rg themselves.

ImageMagick

Interceptor's blank-frame guard and Art's composition steps both spawn magick.

Capture.sh already handles absence well — it returns the screenshot but prints BLANK-FRAME GUARD SKIPPED (imagemagick-absent) — do not treat it as pixel-verified without looking, with an install hint. That is exactly the honest degradation the page promises. The gap was that nothing told you beforehand, so the first signal was a warning mid-verification.

Changes

  • Both added to Doctor's capability registry, so they surface as ✅/❌ with a fix command like every other tool, and can be declined.
  • Both documented in GETTING-STARTED.md in the same shape as the existing entries, with the ImageMagick note recording what actually happens when it is absent.

Verified

Doctor.ts run with both binaries present → both report ✅ live. The same which() logic run against a PATH with rg and magick stripped → both report broken and surface their fix command. Doctor's existing capabilities are unchanged in both runs.

GETTING-STARTED.md exists to list the external tools doctrine uses and
promises that each 'degrades honestly when absent'. Two tools shipped code
shells out to were missing from it:

- ripgrep — ContextSearch spawns `rg` directly, as do the work sweep and
  UpdateModels' drift scan. LifeOS indexes via the filesystem rather than a
  vector store, so this is load-bearing, not a preference. (The built-in
  Grep tool is separately ripgrep-backed and unaffected.)
- ImageMagick — Interceptor's blank-frame guard and Art's composition both
  spawn `magick`.

Neither appeared in GETTING-STARTED.md or in Doctor's capability registry,
so a host without them got no signal until something failed at use time.

Adds both as Doctor capabilities so they surface as ✅/❌ with a fix
command like every other tool, and documents them in GETTING-STARTED.md
with the same shape as the existing entries.

The ImageMagick note records what actually happens when it is absent:
Capture.sh still returns a screenshot but prints BLANK-FRAME GUARD
SKIPPED, and that capture must not be cited as pixel-verified.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant