M0 docs — lock three-tier resolve + upstream-contribution posture

The design calls for rustypipe primary, yt-dlp fallback, and rip-to-temp as the
last-resort path when streams die mid-play. README expanded to spell
out all three tiers + adds the 'fight YouTube alongside the FOSS
ecosystem' framing. MILESTONES M1 rewritten to cover all three tiers.

New file docs/upstream.md tracks every PR we file against rustypipe /
NPE / yt-dlp with honest outcomes. Opens empty; fills as M1+ surface
real bugs to fix.

MILESTONES.md

@@ -7,11 +7,13 @@
 - [x] GPL-3.0 license headers
 - [ ] the build container produces a static aarch64 sidecar binary
 
-## M1 — sidecar resolve
+## M1 — sidecar resolve (three-tier)
 
 - [ ] reads `{"op":"resolve","id":"<yt-id>"}` from stdin
-- [ ] calls rustypipe → returns `{"streams":[…],"title":"…","duration_s":N}`
-- [ ] handles age-restricted + region-restricted as typed errors, not panics
+- [ ] **Tier 1:** rustypipe → `{"streams":[…],"title":"…","duration_s":N,"source":"rustypipe"}`
+- [ ] **Tier 2:** on Tier-1 failure, shell out to `yt-dlp -j <url>` → same JSON shape with `"source":"yt-dlp"`
+- [ ] **Tier 3:** new op `{"op":"rip","id":"<yt-id>","dest":"/storage/.kodi/temp/torttube/<id>.<ext>"}` invoked by addon on Tier-1+2 stream failures or 403-mid-play; yt-dlp downloads file, sidecar returns local path
+- [ ] typed errors for age-restricted / region-restricted / private (not panics)
 - [ ] sig decoding verified against a known-good video
 - [ ] DASH manifest URL or per-itag direct stream URL — whichever inputstream.adaptive prefers
 
@@ -49,10 +51,16 @@
 - [ ] `addon.zip` ships with platform detect via `xbmc.getCondVisibility('system.platform.linux.raspberrypi')`
 - [ ] one-shot install path documented for LibreELEC `/storage/.kodi/`
 
-## Upstream PR targets (parallel, opportunistic)
+## Upstream PR work (parallel lane — every bug evaluated for "fix it upstream?")
 
-Pick one as we hit it organically — don't gate milestones on these.
+This isn't a separate milestone, it's a posture. Every sidecar bug we
+diagnose: ask "is this rustypipe / NPE / yt-dlp's bug?" — if yes, fix lands
+upstream too. Log every filed PR in [docs/upstream.md](docs/upstream.md).
 
-- NPE #1357 (JDoc) — smallest, just to land a credible PR
+Opening shortlist:
+
+- rustypipe PR #77 — review + help land
+- NPE #1357 (JDoc) — smallest credible PR, opens the relationship
 - NPE #1444 (typed errors) — clean signal/contract change
-- rustypipe — file issues + PRs on codeberg as we hit gaps
+- NPE #1360 (refactor link handlers, "help wanted")
+- rustypipe ↔ NPE port — anything one project has that the other lacks