Metadata-Version: 2.4
Name: navig-debrief
Version: 0.1.0
Summary: Visual debrief of a work session: timeline, tool mix, mind map, files and UI mockups rendered to one navigable HTML report, with PNG exports.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,session,debrief,report,visualization,html,timeline,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Topic :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Requires-Dist: zstandard>=0.22.0

# navig-debrief

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> 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)

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

**With navig**

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

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig debrief build` | Build a visual debrief of a session (facts from the transcript, prose from story.json). |
| `navig debrief list` | List recent DSH sessions a debrief can be built from. |
| `navig debrief open` | Build (if needed) and open a session's debrief. |
| `navig debrief shot` | Capture PNGs for an existing (or freshly built) debrief. |

</details>

<!-- navig:plugin-card:end -->

**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.

```bash
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

| | this | image model |
|---|---|---|
| text in diagrams | exact, selectable | usually garbled |
| cost per image | 0 | per-image |
| editable | change one JSON field | regenerate |
| offline viewing | yes (HTML) | no |

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`](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`](navig_debrief/story.py)) — the small file an
   agent writes:

```json
{
  "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.
