navig-debrief

Visual debrief of a work session: timeline, tool mix, mind map, files and UI mockups rendered to one navigable HTML report, with PNG exports.

Works on its own — its own CLI, no navig required · v0.1.0 · not on PyPI yet (install from source below)

On its own (no navig needed)

pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-debrief"
navig-debrief --help   # no navig needed

With navig

pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-debrief"
navig debrief --help

A finished work session, turned into something you can look at. One command reads the session transcript and writes a navigable HTML report — timeline, tool mix, files touched, commands, a map, an optional mind map and UI mockups — then screenshots itself with the Edge/Chrome you already have.

navig debrief build last --open          # newest session in this workspace
navig debrief build 6d7697de --shots     # by id, with PNGs
navig debrief list                       # what can be debriefed
navig debrief shot last --section files  # re-shoot one section

Standalone too: pip install -e . then navig-debrief build last --open.

Why HTML and a local browser, not an image model

The report is a program, not a picture: sidebar navigation, Ctrl K search, deep links (#files), 1–9 section jumps, j/k, shot mode (?shot=1&only=files), and "copy as markdown" on every section so an agent can read what you see.

The two layers

1. Facts (navig_debrief/facts.py) — deterministic. Reads ~/.dsh/sessions/<workspace>/<session-id>/session.v4.jsonl.zstd (concatenated zstd frames; zstandard reads across frames). Every number in the report comes from a record the host wrote: tool/call, tool/result, turn/start, deliverables/presented. No model calls, no guesses.
2. Story (navig_debrief/story.py) — the small file an agent writes:

{
  "title": "Windows audit — what to switch off",
  "summary": ["321 services scanned", "73 fixes selected"],
  "sections": [
    {"id": "map", "kind": "mermaid", "title": "How the audit fits",
     "diagram": "flowchart LR\n  a --> b"},
    {"id": "mind", "kind": "markmap", "title": "System map",
     "markdown": "# Services\n## Running"},
    {"id": "ui", "kind": "mockups", "title": "The report",
     "frames": [{"label": "report.html", "html": "<div>…</div>"}]}
  ]
}

Kinds: mermaid, markmap, mockups, gallery, callout, notes. after places a section behind an existing anchor (overview, timeline, roles, tools, files, commands, deliverables, todos). Section ids are stable, so links and screenshots survive a re-render.

Output

~/.navig/debrief/<session-id>/
  index.html        the report (single file, CDN for mermaid/markmap)
  manifest.json     session + stats + section ids + shot paths
  shots/report.png  full page
  shots/<id>.png    one per section

Override the root with NAVIG_DEBRIEF_DIR. --story adds curated sections; --no-shots skips the browser entirely.

How the screenshots work

debrief.js keeps writing <title>H:<scrollHeight></title> in shot mode; the driver runs headless Chromium twice — once with --dump-dom to read the exact height, once with --window-size=W,H --screenshot=…. No Playwright, no CDP client, no Node. Width defaults to 1280 CSS px; --dpr 2 for retina.

Inside navig

Installed as a plugin (pip install "navig[debrief]"), it contributes:

• navig debrief … — the same Typer app,
• a free debrief module (per-space toggle gates verb, tile and tool),
• Debrief tile in NAVIG OS / Dock — GET /api/deck/debrief lists built reports, POST /api/deck/debrief/build builds one, GET /api/deck/debrief/{id} returns a manifest. All routes are local-only and gated on the module,
• the debrief_build agent tool (toolset debrief), so the agent can debrief a session without shelling out,
• a session-debrief skill, so "debrief this session" (or "recap") routes to the tool instead of the model hand-writing another HTML file.

Honest limits

• Facts are only as rich as the transcript: a session recorded elsewhere (or a different session.v* schema) renders less. --session accepts a file path.
• Mermaid and markmap load from jsDelivr; offline the page still shows every fact/table, just not the two diagram types.
• Classifying a pwsh run as inspect/change is a regex heuristic — the legend says so in the report.
• Very tall pages are clamped at 16 000 px per shot; use --section for detail.
• The deck routes are local-only by design: a manifest carries absolute paths.