Add tunie/docs (full context + open-source roadmap); refresh README

docs/CONTEXT.md captures the entire reverse-engineering effort in one place:
KWP2000 protocol, AES-128 seed/key, the map format (dc decrypt -> flat-ROM
unpack -> directory -> fe table pointers), the fuel/ignition table map, the
validated SAI/O2 device flags, checksums, hardware, and a per-finding confidence
table.

docs/ROADMAP.md covers open-sourcing (legal/IP posture on proprietary maps and
the AES keys, repo hygiene, packaging/CI, community) and the technical path to
tuning the bike (first contact -> ROM dump -> calibration model -> write path ->
editor), with immediate next steps and a risk register.

Top-level README refreshed to describe the whole project (tool + viewer +
research) and point at docs/.

tunie/docs/ROADMAP.md

@@ -0,0 +1,130 @@
+# tunie — roadmap: open-sourcing + what's next
+
+Two tracks: **getting this into a shippable open-source project**, and the
+**technical work** still needed to actually tune the bike. Read
+[CONTEXT.md](CONTEXT.md) first for the full state.
+
+---
+
+## Track A — open-sourcing
+
+The code is original; the risk in publishing is the **third-party derived data**
+and the **flashing capability**. Handle these deliberately before a public repo.
+
+### A1. Legal / IP (do this first)
+- **No proprietary binaries in the repo.** Already enforced: `*.hex`, `*.dec.bin`,
+  `maps_cache/`, `table_map.json` are gitignored. Keep it that way — map files are
+  Triumph/TuneECU calibration data and must not be redistributed.
+- **APK-derived data** (`maps.json`, `mapdefs.json`, embedded `c.a`/`s.a`, the AES
+  keys, protocol constants) are facts extracted for **interoperability**. Frame the
+  project explicitly as independent interoperability research on hardware you own.
+  Add a clear NOTICE describing what's derived and why, and cite that it contains
+  no TuneECU source.
+- **The AES seed/key** enables writing to the ECU. Decide the posture: keep the
+  key/flashing material in a clearly-separated `research/` area with a warning, or
+  gate the write path behind an explicit build flag. Do not make bricking a
+  one-liner.
+- **License:** pick one (MIT/Apache-2.0 for the tool; note that embedded
+  extracted constants are facts, not licensed code). Add `LICENSE` and a top-level
+  legal/README section.
+
+### A2. Repo hygiene
+- Move `tunie/` out of the `samplez` grab-bag into its **own repo** for a real
+  project (keep samplez as the scratch mirror if you like).
+- Add: `CONTRIBUTING.md`, `SECURITY.md` (responsible-disclosure + "don't flash
+  blindly" warning), issue templates, a CHANGELOG.
+- Reproducible builds: pin deps, document `build_viewer.py` inputs (needs a
+  decompiled APK the repo can't ship — document how to produce it, don't include it).
+
+### A3. Packaging & CI
+- `pip install tunie` — the `pyproject.toml` is already there; add a wheel build.
+- CI: run `tests/verify_protocol.py` + the reference-map self-tests (`decode_map.py`,
+  `reconstruct_rom.py`, `table_map.py` — but those need map binaries, so gate them
+  behind a locally-provided fixtures dir / skip in public CI).
+- Lint/format (ruff/black), type-check (mypy) the `src/tunie` package.
+
+### A4. Docs & polish
+- A real top-level README with a quickstart, the safety stance, and a screenshot.
+- Host the viewer as a static page (it's a single self-contained file).
+- Turn `docs/CONTEXT.md` into a short "how the format works" explainer — it's
+  genuinely novel RE and good for the project's credibility.
+
+### A5. Community
+- The SuperH ECU community (npkern/FastECU/ScoobyRom authors, TunerPro forums,
+  triumphrat) is the natural audience. A working open Keihin decrypt + table map is
+  a real contribution. Coordinate rather than surprise — some of this overlaps
+  commercial XDF vendors.
+
+---
+
+## Track B — technical, to actually tune the bike
+
+Ordered by dependency. Phases 1–2 are safe reads; 3+ is the write path.
+
+### B1. First contact (READ) — the current blocker
+1. Identify the VAG KKL chip (`tunie ports`); install CH340 driver if needed.
+2. **Confirm the Triumph diagnostic-connector pinout** and build the adapter
+   (K-Line + switched 12V + ground). *This is the one real electrical risk.*
+3. `tunie info` — read ECU ID, current map, DTCs. Confirms which stock map is on
+   the bike (should be 20187/20191 for production silencers, mechanical odo).
+
+### B2. ROM dump (READ, deliberate)
+- Enable `0x35` RequestUpload (currently blocked in the read-only tool) to dump the
+  stock ROM as a recovery image. Do this before any write work.
+- Cross-check the dump against our decrypt/unpack: a stock dump should reconstruct
+  to the same flat ROM as the matching `.hex`, validating the whole pipeline on the
+  real bike's data.
+
+### B3. Finish the calibration model
+- **Absolute scaling** for fuel and ignition (units), via an XDF cross-check (~€70
+  OldSkull/Tuniverse) or more RE of `Nc`/`Lb`. Relative editing already works.
+- **AFR table** dimensions/axes (partly reversed; 128 = λ1.00 confirmed).
+- **Remaining device flags** (exhaust valve, air flap…) — needs the `x.a()` device
+  layout reverse (`x.t/x.s/x.q` for i27=72) or more single-mod reference maps.
+- Individual **SAI-vs-O2** isolation — only matters if hand-editing flags; the
+  owner's path (a complete AIRBOXBONNY-style map) sidesteps it.
+
+### B4. Write / flash path (the risky part — bench first)
+- Port the **flash kernel**: `fenugrec/npkern` explicitly lists SH7054 (untested) —
+  the strongest lead. `miikasyvanen/FastECU` shows a full end-to-end flow.
+- Finish **seed/key**: which of the 3 AES keys + the seed-block padding (one
+  captured pair from the bike/logging APK settles it).
+- **ECU flash checksum** at write time.
+- **Recovery**: `v-ladimir/audprog` (AUD debugger) for SH705x un-brick via the PCB
+  debug pins — mandatory backstop when developing a flasher.
+- Develop against a **spare/bench ECU**, on a stable supply, never the bike's only
+  ECU, and validate output against TuneECU before trusting our own writes.
+
+### B5. Editor completion
+- Full flat-ROM edit → re-pack → `dc`-encode → `.hex` for **arbitrary** table edits
+  (device flags already round-trip; generalize to any chunk + fix the edit
+  checksum).
+- In-viewer table editing with axes + a wideband/dyno-oriented diff workflow.
+
+### B6. The owner's actual goal
+2-1 exhaust + airbox removal + O2 + SAI delete:
+1. Base on `20188Map2009AIRBOXBONNY` (validated: flags off + airbox fueling done).
+2. Verify in the viewer (devices off, fuel tables sane vs stock).
+3. Flash it — via the tunie write path once it exists, or TuneECU meanwhile.
+4. Fine-tune midrange fuel for the 2-1 with a wideband (ideally a dyno).
+
+---
+
+## Immediate next steps (this week, if picking back up)
+
+1. **Cable + pinout** → run `tunie info` on the bike (unblocks everything).
+2. Pull `20188Map2009AIRBOXBONNY` into the viewer catalogue and diff it vs stock
+   20187 so the exact delete-tune changes are visible.
+3. Decide the open-source posture on the AES keys / write path (Track A1) before
+   any public repo.
+
+## Risk register
+
+| Risk | Status |
+|---|---|
+| Software bricking via the read tool | eliminated (write path not implemented) |
+| Electrical (wrong connector pin) | **live** — confirm pinout before plugging in |
+| Bad tune from flags-only edit | mitigated by guidance; use a complete map |
+| Flashing (comms drop / bad checksum) | future — needs bench ECU + recovery tooling |
+| Legal (redistributing proprietary maps) | mitigated — binaries gitignored |
+| One ECU, no spare | validate writes against TuneECU; get a spare before B4 |