`graphify watch` rejects --debounce, the flag its own module help documents

[Azeem1985]

The gap

watch() takes a debounce argument (graphify/watch.py, default 3.0) and the module's own
help advertises it:

$ python -m graphify.watch --help
  --debounce DEBOUNCE   Seconds to wait after last change before updating (default: 3)

But the shipped sub-command never parses it — graphify/cli.py's watch branch accepts only
--semantic, --backend, --fallback-backend, and rejects everything else:

$ graphify watch /path --debounce 60
error: unknown watch option: --debounce        # exit 2

So the knob is documented and unreachable through the command people actually run, and
graphify --help does not list it either.

Why the default is not always right (measured)

On a vault watched by graphify watch --semantic, three files written 6 seconds apart
produced two batches → two AST rebuilds → two graph.json writes → two downstream view
renders. The second batch is unavoidable at debounce=3: the rebuild itself takes ~46 s, and
every event landing during it becomes a fresh batch the moment the loop is free.

With the same burst and --debounce 60: one batch, one rebuild, one render. On this box a
render rewrites 31k view files, so a needless second batch is not free.

Suggested fix

Parse --debounce N / --debounce=N in the watch branch, reject a non-number and a negative
with exit 2, and pass nothing when the flag is absent so the watcher's own default keeps
living in one place. One line in graphify --help next to --semantic.

Implemented and tested in our fork (8 tests: both spellings, zero, absent-means-default, combined
with --semantic/--backend, both rejection paths, and the still-rejected unknown option) —
happy to open a PR against v8.

[akshitj11]

Working on this in fix/3061-watch-debounce.

[Azeem1985]

Thanks @akshitj11 — reviewed and ran #3085: all 9 tests in tests/test_cli_watch.py pass on the PR head on the box where the issue was measured, and the parsing covers the full matrix from the report (both spellings, 0 allowed, absent → no kwarg so watch()'s default stays the single source of truth, non-numeric / negative / missing value → exit 2, help line present).

One correction to my own report: the error: unknown watch option: --debounce (exit 2) I quoted came from a patched build on my side. Stock v8 is quieter and worse — the watch branch reads only sys.argv[2] as the path, so graphify watch /path --debounce 60 silently ignores the flag, and graphify watch --debounce 60 /path dies with path not found: --debounce. #3085 fixes both orderings and makes stray options loud, which is better than either old behavior.

No duplicate PR from me — I'll drop the fork-side patch once this lands.

[akshitj11]

Thanks for the review and the stock v8 clarification. Glad the test matrix matches what you measured. I will keep an eye on the PR for maintainer feedback.

[Azeem1985]

Sounds good — I'll leave this issue open to track #3085 and close it once that lands. Thanks again for the quick turnaround.