docs: post-pilot polish — de-lint, doc-truth, replay demo, architecture diagram, pilot field report (#35)

* docs: de-lint, fix doc-truth gaps, add badges + CHANGELOG + vuln reporting

Post-pilot repo polish (Phase A of the presentation-hardening pass):

- .gitignore: also ignore .idea/, *.swp, scratch/ so editor/scratch litter
  can't be committed.
- Remove the two dead linear.app hyperlinks (docs/agent-monitoring.md,
  sensorwatch-monitor/SKILL.md); keep the LEO-### ids as plain-text provenance.
- README: add PyPI-version, Python-versions, crates.io, and MIT-license badges;
  drop the stale "once published" crates hedge (crates.io is live).
- ROADMAP: add `report` to the Rust CLI status row.
- SECURITY.md: add a "Reporting a Vulnerability" section (private GitHub
  security advisories) — README/CONTRIBUTING routed reporters here but there
  was no reporting path.
- CHANGELOG.md: new (Keep a Changelog), from the v0.1.0/v0.1.1/v0.2.0 tag
  history plus an Unreleased section for the post-0.2.0 C++/Rust/CLI/skills work.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: no-hardware replay demo, architecture diagram, pilot field report

Post-pilot showcase assets (Phase B of the presentation-hardening pass):

- examples/demo/: a committed 4-sample +12V fixture, a commented threshold
  rule, and a walkthrough README. `watch --replay` fires a critical event with
  zero hardware on any OS (exit 10); `--follow` records the full fire -> clear
  lifecycle. make_demo_gif.py runs those exact commands, captures their real
  stdout and exit codes, and renders the committed demo.gif from them, so the
  recording can't drift from the CLI.
- Mermaid five-layer architecture diagram in README and docs/agent-monitoring.md
  (validated), replacing the text-only layer table as the visual hook.
- docs/pilot-field-report.md: a sanitized write-up of the week-long, agent-run
  pilot — the quiet 8-day soak, two fault drills (a synthetic escalation-ladder
  run and a real OCCT thermal event delivered over three channels), and the
  three defects adversarial testing surfaced. Host/network/account specifics
  scrubbed.
- README: a "Try it in 60 seconds -- no hardware" quickstart with the demo GIF.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: address PR review on the demo GIF generator

Round 1 feedback (Copilot) on examples/demo/make_demo_gif.py:

- load_font: the fallback returned ImageFont.load_default() (not a FreeTypeFont),
  so the return annotation was wrong. Use load_default(size), which returns a
  sized FreeTypeFont on modern Pillow — the annotation is now accurate and the
  fallback still honors the requested size.
- The exit note hard-coded "a rule fired" regardless of the real exit code. Gate
  it on rc1 == 10 (the "rule fired" contract) so a demo command that exits any
  other way can't render as a passing one.

No visual change to the committed demo.gif (the real run exits 10 and Cascadia
Mono is present, so neither path is exercised on the recording host).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: address round-1 rollup reviews (codex / claude / kimi)

Doc-truth and robustness fixes from the three rollup reviews:

- Pilot field report ran as an INTERACTIVE session, not the headless per-wake
  supervisor. Corrected the "fresh invocation / zero context growth" claims to
  describe the real runtime (bounded per-wake reads + on-disk state + periodic
  compaction), and framed headless invocation as the Phase-2 graduation the
  discipline enables. (codex #1, claude #1)
- ROADMAP: flipped the Phase 1 pilot from "now underway" to complete (dates,
  both drills), linked the field report, and now tracks the three pilot defects
  as Phase 2/C follow-ups so the report's "see roadmap" is true. Softened the
  escalation-ladder claim: the tier-3 issue rung is a drafted-artifact
  placeholder, not a wired action. Diagrams say "issue-draft" to match.
  (codex #1/#2, claude #1)
- README Requirements: split into replay-demo (Rust >= 1.82 + C compiler),
  Python-package, and live-monitor prerequisites, and noted HWiNFO's free-tier
  12-hour Shared Memory limit for always-on use. Added a Windows PowerShell
  command variant to the quickstart. (codex #3, claude #2, kimi #4/#5)
- README: added the shipped `report` subcommand to the sensorwatch-cli
  enumeration. (codex #5)
- make_demo_gif.py: fail closed — validate rc1==10, rc2==0, and fired/cleared
  event states before rendering, so a broken demo can't overwrite demo.gif with
  a passing recording; and search Linux/macOS font dirs so regeneration off
  Windows uses a real monospace font. (codex #4, claude #6/#7, kimi #3)
- CI: added a replay-demo smoke test to the rust job (Ubuntu + Windows) — the
  one-shot exits 10 with a fired event, --follow emits fired+cleared — so the
  "60-second demo" can't silently rot. (kimi #2)
- Dropped stale publication hedges in rust/Cargo.toml and CONTRIBUTING.md (both
  registries have shipped). (claude #3)
- examples/demo/README: reset logs/ before the --follow example so its sample
  output actually shows seq 1. (claude #8)
- CHANGELOG: clarified that post-0.2.0 Rust/CLI/skill work is recorded under
  Unreleased until the next Python tag. (kimi #6)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: consolidate the LEO-411 monitor worked example from PR #33

Pulls the reviewed, non-overlapping substance of PR #33 into this PR so the
post-pilot docs land as one unit (and #33 can close):

- examples/monitor-setup/ — a copy-from starting point for the always-on agent
  monitor on the free ntfy path: an annotated config.toml exercising all five
  rule kinds, an ntfy-only notify.toml (with commented Pushover/SMTP add-ons,
  all placeholder values), and a PILOT_TEST_PLAN.md acceptance checklist.
  Complements examples/demo/ (try-a-fire) with a real-setup example, and is
  where the HWiNFO free-tier note also lives.
- README: a pointer to the worked example from the monitor-skill section,
  merged into the same paragraph as the new architecture diagram.
- skills/sensorwatch-monitor/SKILL.md: three correctness clarifications —
  drain the spool on bootstrap (watch never replays it on re-arm),
  open_incident.py's --classification requirement, and the ack_event.py
  pending-path constraint plus its update-deduped incident partner.

Verified: config.toml parses through `watch` (valid rule set), all relative
links and anchors in the pulled files resolve, and notify.toml carries only
placeholder secrets (topic sensorwatch-CHANGEME, example.com addresses).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: address round-2 review (codex 2×P1 + P2s, kimi nits)

Tier-3 contract alignment (codex #1 / claude #1) — the authoritative skill
surfaces still directed a real Linear issue while ROADMAP/report/diagrams say
"issue-draft placeholder", so an agent could attempt an unsupported action.
Reworded to the issue-draft/outbox placeholder (real tracker/webhook = Phase C):
SKILL.md tier table, the tier-3 guidance paragraph, and the security summary;
templates/bootstrap.md; scripts/escalation_gate.py's tier ladder; and notify.py's
docstring.

Monitor worked example runnable from a clean state (codex #2) — examples/
monitor-setup/README.md §3 now initializes the state directory with init_state.py
(ack_event.py needs cursor.json) and starts the layer-1 `sensorwatch log`
alongside the one-shot watcher (live watch samples HWiNFO directly and writes no
sensors_*.jsonl, so report/baseline had no history). Fixed config.toml's
"watch reads the log stream" comment. PILOT_TEST_PLAN §6 notes the logger must be
running for the 24h baseline. Verified end to end: init_state.py creates the
state tree, and the plan's fixture fires psu-12v-sag (exit 10) against the
example config.

POSIX/PowerShell (codex #3) — documented that the worked-example and test-plan
commands are POSIX shell (Git Bash/WSL) and added a PowerShell variant to the
demo README's --follow section.

ROADMAP opener (codex #4) — the real notification transport shipped in LEO-339;
only the unattended runtime remains in progress.

Nits — CI demo smoke test now also asserts the --follow exit code (kimi #3);
make_demo_gif.py drops the now-unreachable caption branch (kimi #1) and broadens
load_font's return annotation (kimi #2).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: address round-3 review — honest tier-3 contract, single-cwd worked example

Round 3 (codex 2×P1, both independently confirmed by claude; kimi approve
w/ suggestions; 2 Copilot nits):

Tier-3 contract, honest this time (codex P1 #1) — round 2 overcorrected: the
skill claimed tier 3 "emits an issue-draft to outbox/", but notify.py in the
canonical routed mode never writes outbox (fallback only when notify.toml is
absent). Reworded to what the tooling does today: tier 3 delivers the same
routed notification as tier 2; no distinct issue action is wired (Phase C);
an agent may force a durable draft with --adapter outbox (verified at runtime:
writes the draft file AND records delivery, so it arms the cooldown and counts
toward the daily cap — documented). Applied to SKILL.md (table, guidance,
security summary), templates/bootstrap.md, escalation_gate.py, and the ROADMAP
ladder bullet.

Worked example: one working directory (codex P1 #2, claude confirm) — every
command in examples/monitor-setup/README.md and PILOT_TEST_PLAN.md now runs
from examples/monitor-setup/: helper scripts as ../../skills/..., a working-
directory-and-binary note in both files, and the bare-`sensorwatch` trap
called out with the path-qualified Rust binary (kimi #1). Verified end to end
from that cwd: config validate (exit 0) → init_state → replay fire (exit 10,
spool written) → open → summary pending=1 → re-open update-deduped → ack
(cursor 0→1, file to spool/acked/).

Nits — fixture/for_samples cross-references in config.toml and the test plan
(kimi #3); never-commit-a-real-topic warning in notify.toml (kimi #4);
make_demo_gif.py falls back to argless load_default() on Pillow < 10.1
(Copilot); rust/Cargo.toml comment says "both library crates", CLI repo-only
(Copilot).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

* docs: address round-4 review — Python prerequisite + ladder-label truth

codex P1 — a user with HWiNFO + the Rust CLI hits exit 127 at the very first
monitor-state command because Python was never listed as an agent-monitor
prerequisite. Added Python 3.12+ (with the python/python3/py launcher note)
to examples/monitor-setup/README.md prerequisites, the sensorwatch-monitor
SKILL.md prerequisites (list renumbered), and the root README's live-monitor
requirements bucket.

codex P2 / kimi's remaining inconsistency — the Mermaid ladder label and the
ROADMAP ladder enumeration still read "issue-draft", over-promising a distinct
tier-3 artifact the routed path doesn't produce. Both diagram copies (kept
byte-identical) now read "issue (Phase C)" and the ROADMAP enumerates the rung
as a placeholder pointing at the explanation below it.

kimi polish — the root README Install section now notes that the PyPI
package's `sensorwatch` console script is the Python logger, not the Rust CLI
with snapshot/watch/report, and to path-qualify the Rust binary when both are
on PATH.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxKabmaTX8ZY8PJBkrKxmi

---------

Co-authored-by: lcj-claude-coder <lcj.claude.coder@pm.me>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>