Explain any installed command from its man page; check AI suggestions against it

[Sym-jay]

This makes Clishe's knowledge come from the user's own machine instead of the network or a model's memory.

Explain anything that's installed, offline

explain used to know 43 commands. After those, it went to AI or gave up. Now the order is:

1. the offline dictionary (same as before),
2. the manual installed on this computer: man <command>, or <command> --help when there's no man page,
3. AI, only when there's no manual at all.

You: explain find . -type f -size +100M
Clishe (via your system's manual): find - search for files in a directory hierarchy
In 'find . -type f -size +100M':
  -type  File is of type c:
  -size  File uses less than, more than or exactly n units of space, rounding up.
Full details: man find

Short flags written together (-xzvf) are looked up one by one. Commands like find that use one dash for whole words (-size) are handled. Descriptions are cut to their first sentence. Dictionary entries now fill in flags they don't cover from the manual, instead of "try: man X".

AI suggestions are checked against the manual

Clishe (via local): I think you mean: find . -size +100M -bigger
  Big files.
  From the manual:
    find -size: File uses less than, more than or exactly n units of space, rounding up.
  ⚠ The manual doesn't mention: find -bigger. The AI may have made it up, so check before running.

Small local models usually go wrong by making up flags. This catches that, and the user learns from the real documentation.

Safety

--help runs a program, so it's never run for power, disk or deletion tools (reboot, dd, mkfs*, rm…). It's also skipped for anything the safety check flags, or any name that isn't a plain command name. Each call has a 2–4s timeout and gets no stdin.

Tests

• New tests/test_manual.py uses sample GNU man and --help text, so the tests don't depend on the CI machine's man pages.
• The brain test fixture stubs the manual for the same reason.
• New shell test for the suggestion display.
• 451 pytest tests pass locally. Shell tests: the new ones pass, and the rest match main on macOS bash 3.2; CI runs them all on Linux.
• Also checked by hand against the real macOS man pages for ls, tar, find, du, grep and chmod.

🤖 Generated with Claude Code