feat(ai): online mode — local per-file Bob diagrams, matched by start line

[Yoshitd]

Online (AI Assisted) mode — local per-file Bob diagrams

A developer runs Bob on one file; ZDoc gets back one Mermaid flowchart per
function and attaches each to its symbol by the function's starting line.
Deliberately small — no daemon, no snippet assembly, no Bob extension.

What's here

• ai/annotate.{h,c} — the online-mode step. zdoc_ai_annotate(path, mod, bob_cli)
  takes an already-parsed Module (online mode does not parse), runs Bob
  once (Bob reads the file itself), then splits Bob's reply on the
  ## line <N> headers and stores each flowchart into the Symbol whose
  starting line is N — filling Symbol.diagram. Starting line is the match key.
  Cross-platform: fork+exec on POSIX, CreateProcess on Windows (prompt
  passed as a single argument, so its backticks/quotes never touch a shell).
• ai/zdoc_ai.c — a thin standalone tool. Parses ONE file only to obtain a
  module to hand to zdoc_ai_annotate, then prints each stored diagram.

  make -C ai zdoc_ai
  ./ai/zdoc_ai path/to/File.(c|java|plx) [--bob <bob-binary>]

• Prompt hardened against hallucination: read the file first; diagram only
  code actually in the body; never invent steps/branches/calls; use only names
  from the source; fall back to A[No executable logic] / A[Source unavailable]
  instead of guessing; self-check every node against the code.

How to test

# Real Bob (on PATH + authenticated; run so Bob can open the file):
make -C ai zdoc_ai
./ai/zdoc_ai docs/student_grades.plx

# No-credit dry run (fake bob echoes a flowchart per listed line):
mkdir -p /tmp/fakebobdir
cat > /tmp/fakebobdir/bob <<'SH'
#!/bin/sh
printf '%s\n' "$4" | grep -oE 'line [0-9]+:' | sed -E 's/line ([0-9]+):/\1/' | while read n; do
  printf '## line %s: fn\n```mermaid\nflowchart TD\n    A[Entry %s]-->B[Return]\n```\n\n' "$n" "$n"
done
SH
chmod +x /tmp/fakebobdir/bob
./ai/zdoc_ai docs/student_grades.plx --bob /tmp/fakebobdir/bob   # -> stored 7 of 7 diagrams

Verified: docs/student_grades.plx → 7/7 diagrams stored into the right
Symbol.diagram by line (181 INITIALIZE_SYSTEM, 224 ADD_STUDENT, …); C and
Java parse paths work too.

---

Connecting online mode to the CLI/daemon (not in this PR)

Online mode is exactly zdoc_ai_annotate(path, mod, bob_cli). Because it takes
an already-parsed module and does not parse, wiring it in is small:

1. Build: link ai/annotate.c into the daemon/CLI and #include "ai/annotate.h".
2. Call it after the parse stage, per parsed module, when --mode ai:

   /* daemon already has the file path and the parsed Module *mod */
   if (opt.mode == ZD_MODE_AI)
       zdoc_ai_annotate(path, mod, opt.bob_cli);   /* fills mod->symbols[i].diagram */

   The daemon already holds both the path and the parsed Module, so nothing is
   parsed twice.
3. Render as usual — the renderers already consume Symbol.diagram.

Follow-ups for that integration (out of scope here):

• Concurrency + timeout: one Bob call per file, network-bound — run the
  per-file calls on the daemon's existing worker pool with a bound, and add a
  per-call timeout.
• Config pass-through: zdoc_ai_annotate takes only the Bob binary today;
  thread bob_args through if needed.
• MD renderer: html_renderer already emits Symbol.diagram; the
  md_renderer does not yet — add a fenced ```mermaid block.
• Pre-existing main build bugs unrelated to this PR, worth fixing before
  daemon integration: zdoc/Makefile references the renamed
  parser/plx_parser/helpers.c, and html_render.c re-declares xmalloc
static against the non-static decl in parser_shared.h.

🤖 Generated with Claude Code