Document and apply tokenwar scan recommendations

[ousamabenyounes]

Summary

• remove the old Mermaid complementarity diagram from the README while keeping the main stack image
• document tokenwar scan usage, supported clients, local log roots, env overrides, and decision labels
• add tokenwar scan --apply, a guarded activation flow for direct ENABLE recommendations
• keep the apply path intentionally narrow: it can enable installed-but-disabled caveman, claude-mem, and ponytail; it does not install new tools, edit RTK hooks, remove pxpipe, or choose third-party code-context tools
• add the observed local scan interpretation to the tool map and update the README check section from four rules to the current five-rule model

Test verification (RED -> GREEN)

RED with the new --apply tests before implementation:

not ok 2 scan apply asks before enabling applicable recommendations
not ok 3 scan apply does nothing when declined
not ok 4 scan apply yes flag enables without prompting

GREEN on this branch:

$ docker run --rm -v "$PWD:/repo" -w /repo node:20-bookworm bash -lc 'apt-get update >/dev/null && apt-get install -y --no-install-recommends bats shellcheck >/dev/null && shellcheck -S warning scripts/*.sh scripts/lib/*.sh && chmod +x scripts/*.sh && bats tests/check.bats tests/scan.bats tests/dispatcher.bats'
1..16
ok 1 R1 PASS
ok 2 R1 WARN
ok 3 R1 FAIL
ok 4 R2 PASS
ok 5 R3 always PASS
ok 6 Verdict COMPLEMENTARY when all PASS
ok 7 scan recommends shell, context, memory, and code tools from local logs
ok 8 scan apply asks before enabling applicable recommendations
ok 9 scan apply does nothing when declined
ok 10 scan apply yes flag enables without prompting
ok 11 scan apply refuses json mode
ok 12 scan json mode emits clients and recommendations
ok 13 dispatcher routes scan subcommand
ok 14 help lists the commands
ok 15 unknown command exits 2 with usage
ok 16 check subcommand runs the checker

Additional validation:

$ bash -n scripts/scan.sh
$ git diff --check
$ rg -n '[éèàçù]|GARDER|ACTIVER|TESTER|OPTIONNEL|Complementarity diagram|```mermaid|flowchart' README.md docs/tokenwar-tools.md scripts/scan.sh tests/scan.bats
# no matches
$ ORA_PROVIDER=codex bash scripts/tokenwar.sh scan --client codex --json | node -e '...'
scan json ok: 1 client(s), 7 recommendation(s)
$ TOKENWAR_SCAN_CONFIRM=no TOKENWAR_SCAN_MAX_FILES=50 TOKENWAR_SCAN_MAX_BYTES_PER_FILE=65536 ORA_PROVIDER=codex bash scripts/tokenwar.sh scan --client codex --apply
Apply recommended TokenWar changes?
  - enable caveman (14.2K estimated opportunity; 595 prose/review/summary signals)
Apply? [y/N] no
Apply skipped.