[Bug] --output flag example in README/SKILL.md doesn't work — dir paths get treated as filenames

[jcrabapple]

Bug/UX: --output is documented as accepting a directory but actually requires a file path

Both the README and SKILL.md examples show --output being passed a directory:

README:

python ~/.hermes/skills/hermes-project-oracle/scripts/oracle_scan.py \
  --path /path/to/your/project \
  --output .oracle/

SKILL.md (Phase 1):

python <skill_dir>/scripts/oracle_scan.py --path <projet> --output .oracle/

But the actual behavior treats --output as a literal file path. Passing a directory-style value silently writes a file with that name:

$ python oracle_scan.py --path . --output /tmp/oracle-test/
[INFO] Report written: /tmp/oracle-test (193354 bytes)
# creates a FILE named "/tmp/oracle-test", not a directory

$ ls -la /tmp/oracle-test
-rw-r--r--  1 jason jason 193354 Jun 22 20:46 /tmp/oracle-test
$ file /tmp/oracle-test
/tmp/oracle-test: JSON data

The CLI even help text confirms this:

$ python oracle_scan.py --help
--output / -o  Fichier JSON de sortie (défaut: .oracle/scan-report.json)

("Fichier JSON de sortie" = "Output JSON file".)

Why this is bad

1. The example in the README doesn't work — first-time users hit this immediately.
2. Silent failure: no error, just a misnamed file with .oracle/ style content sitting next to your real .oracle/ if you happen to have one.
3. The default value is .oracle/scan-report.json which implies "put a file at this path", but the example --output .oracle/ (no filename) doesn't follow that pattern.

Suggested fix

Pick one of these and make it consistent:

Option A — auto-derive filename from directory (matches the README example, friendliest UX):

out = Path(args.output)
if out.is_dir() or str(args.output).endswith(('/', os.sep)):
    out.mkdir(parents=True, exist_ok=True)
    out = out / "scan-report.json"

Option B — be explicit in docs and CLI:

• Update README and SKILL.md to use --output .oracle/scan-report.json everywhere.
• Update the CLI help epilog.

Option C — add --output-dir as a sibling flag:

--output       FILE  Output file path (default: .oracle/scan-report.json)
--output-dir   DIR   Output directory; filename auto-derived as scan-report.json

I'd vote for Option A because it preserves the existing documented examples, but Option B is fine too if you don't want the auto-magic. Either way, the docs and behavior need to match.