docs(sap): add Fisher UI Contract v1 + RJ addendum (ES/EN/PT)

.github/CODEOWNERS

@@ -1,6 +1,19 @@
-# Code Owners - iURi Pescadores
-# Este archivo define quién debe revisar cambios en partes específicas del código
+# Extra de acero: cualquier cambio sensible pide review explícito.
+# Orden importa: reglas más específicas abajo.
 
-# Guardião de comandos – só Cristian revisa
-/docs/CursorGuardianRules.json @cristianbarnes
-/backend/core/cursor_guardian.py @cristianbarnes
+# GitHub config
+.github/* @Cheewye
+.github/** @Cheewye
+
+# UI contracts (docs) – cambios deben pasar por el dueño
+docs/ui/** @Cheewye
+
+# Map / Dock / Forecast (frontend) – cambios requieren review del dueño
+frontend/src/components/maps/** @Cheewye
+frontend/src/pages/** @Cheewye
+frontend/src/lib/** @Cheewye
+frontend/src/config/** @Cheewye
+frontend/src/data/** @Cheewye
+
+# Fallback: todo lo demás (opcional, si no querés bloquear todo el repo, borrar estas dos líneas)
+* @Cheewye

.github/pull_request_template.md

@@ -1,52 +1,58 @@
-## 📋 PR Template - iURi Veracity Enforcement
-
-### 🎯 Scope (What)
-<!-- Describe exactly what this PR does. Be specific and verifiable. -->
-<!-- Use bullet points for clarity -->
-
-### 🚫 Non-goals (What NOT)
-<!-- What this PR explicitly does NOT do. Prevents scope creep. -->
-<!-- Use bullet points -->
-
-### 🔍 Verification Status
-
-#### CI_VERIFIED
-<!-- Link to GitHub Actions run that shows all CI checks passed -->
-**CI Run:** [Link to Actions Run](https://github.com/Cheewye/iuri-react-codex/actions/runs/XXX)
-**Status:** ✅ PASSED | ❌ FAILED
-**Evidence:** All checks green, no failing tests, lint clean
-
-#### PROD_VERIFIED
-<!-- Current production verification status -->
-**Latest Check:** [Link to PROD Verifier Run](https://github.com/Cheewye/iuri-react-codex/actions/runs/XXX)
-**Status:** ✅ PROD_VERIFIED | ❌ PROD_FAIL | ⚠️ REPO_ONLY
-**Evidence:** See job summary and artifacts `prod-evidence-{run_id}`
-
-### 🏷️ Labels Required
-<!-- Check all that apply -->
-- [ ] `veracity:prod-verified` - PROD_VERIFIED status confirmed
-- [ ] `veracity:ci-verified` - All CI checks passed
-- [ ] `veracity:repo-only` - Code changes only, no prod verification
-- [ ] `type:feature` - New feature
-- [ ] `type:fix` - Bug fix
-- [ ] `type:refactor` - Code improvement
-- [ ] `type:docs` - Documentation only
-
-### ⚠️ Breaking Changes
-<!-- List any breaking changes or migrations needed -->
-- [ ] No breaking changes
-- [ ] Breaking changes listed below:
-  <!-- Describe breaking changes and migration path -->
-
-### 📝 Testing
-<!-- How was this tested? -->
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] Manual testing performed
-- [ ] No tests needed (docs/config only)
-
----
-
-**⚡ VERACITY ENFORCEMENT**: This PR template is enforced by `tools/claim_lint.py` in CI. Claims like "fixed", "working", "verified" require PROD_VERIFIED: or CI_VERIFIED: tags to merge.
-
-**🔗 REQUIRED LINKS**: Both CI_VERIFIED and PROD_VERIFIED links must be provided and valid for merge.
+# Map/Dock/Forecast PR Gate (UI Contract v1 RJ)
+
+## Scope
+- [ ] This PR does **not** change backend / infra.
+- [ ] Changes are limited to the intended scope (map / dock / forecast) and do not introduce new hidden toggles or toasts.
+
+## Required: Appendix E + Appendix F
+**I confirm:**
+- [ ] ✅ passes **Appendix E (Checklist P0)**
+- [ ] ✅ keeps **Appendix F (Sources of Truth + Data on Hold)** intact
+- [ ] ✅ (If applicable) keeps **Appendix G (Dock collision-free)** intact
+
+> If any checkbox above is unchecked, this PR must not be merged.
+
+## What changed (2–6 bullets)
+-
+-
+-
+
+## UX verification (manual)
+Paste *what you actually checked* (no promises):
+
+### RJ targets
+- [ ] Guanabara: AIS default behavior verified
+- [ ] Barra São João: traffic-light is always visible (even if Barra toggle OFF)
+- [ ] Dock does not cover Leaflet Layers dropdown (top-right)
+- [ ] `layers=1` hides Dock (auto-hide) and Layers remains usable
+
+### Data integrity / “no silent failure”
+- [ ] No toasts for: hold / fetch error / slow / abort
+- [ ] Inline states present: `On hold`, `(fetch error)`, `slow`, `abort`
+- [ ] Fail-open verified (last good data stays visible on refresh failure)
+- [ ] “Copy debug” contains required fields (Appendix F4)
+
+## Evidence
+### Build
+Paste:
+- `npm -C frontend run build` summary line + `EXIT_CODE=0`
+
+### Conflict markers
+Paste:
+- `rg -n "^(<{7}|={7}|>{7})" frontend/src || true` (should be empty)
+
+### Version / Prod (if already deployed)
+Paste:
+- `curl -fsS https://iuriapp.com/version.json | head -c 200 && echo`
+
+### Debug JSON (Copy debug)
+Paste one Copy debug sample (sanitized if needed).
+
+## Risk & rollback
+- Risk level: [ ] Low [ ] Medium [ ] High
+- Rollback plan (1 sentence): revert PR / revert commit / toggle flag (if exists)
+
+## Reviewer checklist (fast)
+- [ ] UI Contract invariants still true (Dock, Layers, Data on Hold)
+- [ ] No new duplicated controls (Dock vs Preparation vs Forecast)
+- [ ] No regressions in RJ defaults

docs/ui/FISHER_UI_CONTRACT_v1.en.md

@@ -0,0 +1,175 @@
+# iURi Fisher UI Contract v1
+
+**Version:** 1 · **Language:** EN
+**Other versions:** [ES](./FISHER_UI_CONTRACT_v1.md) · [PT](./FISHER_UI_CONTRACT_v1.pt.md)
+
+---
+
+## Objective
+
+A showable, reliable map for fishers, with:
+
+- **navigation** (signals, zones, depth),
+- **safety** (bar/alerts),
+- **local context** (FMAP: landing/ice/etc.),
+- **departure decision** (forecast: wind/waves/tides/currents),
+
+with no silent failures and no hidden UI.
+
+---
+
+## 0) Definitions (so “buoys” are not mixed up)
+
+| Term | Definition |
+|------|------------|
+| **Signals (Seamarks)** | Nautical navigation signals (channels, marks, hazards). Typical source: OpenSeaMap tiles. |
+| **Buoys (PNBOIA)** | Buoys/stations (e.g. meteorological/oceanographic). They are not “nautical signals”. |
+| **FMAP Signals (seed)** | Local points/polygons (landing, ice, etc.) from FMAP, versioned as seed. |
+
+The UI must label them this way to avoid confusion.
+
+---
+
+## 1) UI surfaces (and responsibilities)
+
+### A) Live Map (`/map?start=realtime`)
+
+Live map, quick interaction. It does not explain much, it just operates.
+
+### B) “Layers” (Leaflet dropdown top-right)
+
+- **ONLY** Base Maps (map styles).
+- **Forbidden** to mix in operational layers (GPS, Buoys, AIS, etc.).
+
+### C) Fisher Dock (operational layers)
+
+- Single place for operational layers (toggles + status).
+- Does not hide in the header.
+- Does not cover the “Layers” dropdown.
+
+### D) Preparation
+
+“Before departure” setup: port, checklist, guided presets. Can turn defaults on/off (but live control stays in Dock).
+
+### E) Forecast
+
+Forecast screens (wind/waves/tides/currents) with clear states: **OK** / **Loading** / **Data on hold** / **Error**.
+
+### F) Smart Fishing
+
+Optional and clearly separate from “core safety”.
+
+---
+
+## 2) Fisher Dock v1
+
+### Layout/UX
+
+- Collapsible (preferred over draggable).
+- Supported snap positions: **Left** / **Right** / **Bottom**.
+- Default **Right** (vertically centered).
+- **Auto-hide** when `layers=1` (so it does not cover the layers/styles panel).
+- No toasts for errors: **everything inline** (minimal noise).
+
+### Toggles (7) — core
+
+1. **GPS** (My Location)
+2. **Signals** (Seamarks)
+3. **Zones**
+4. **Buoys** (PNBOIA)
+5. **Bar**
+6. **AIS** (default OFF, considered “advanced”)
+7. **FMAP** (Local signals)
+
+### Actions (not a toggle)
+
+- **Report:** action button (opens screen/flow). Does not count as a toggle.
+
+### Defaults (v1)
+
+| Layer | Default | Notes |
+|-------|---------|--------|
+| Signals (Seamarks) | ON | — |
+| Zones | ON | — |
+| FMAP | ON | No port: “near my location”; with port: “port resources” |
+| GPS | ON | — |
+| Buoys (PNBOIA) | ON | Always visible as “at hand” toggle |
+| AIS | OFF | — |
+| Bar | ON if applicable | If not applicable to area: OFF and/or “not available” |
+
+---
+
+## 3) “No silent failure” contract (mandatory)
+
+Every operational layer shows in the Dock:
+
+- **State:** OFF | LOADING | OK | ERROR | HOLD
+- If **ERROR:** short message + **Copy debug** button
+- If **OK:** relevant counters (e.g. Loaded/Visible, tilesRequested/Loaded/Error)
+
+### For Buoys (PNBOIA)
+
+- **Loaded** = N (full list)
+- **Visible** = M (by viewport)
+- **Go to buoys** button when Loaded > 0 and Visible = 0
+- **Fail-open:** if a good list was already loaded, it is not cleared by a later failure.
+
+### For Signals (Seamarks)
+
+- **Counters:** tilesRequested / tilesLoaded / tilesError
+- If tiles do not load: show **ERROR (tiles)** without breaking the map.
+
+### For FMAP
+
+- Show **one single row:** “FMAP Signals (seed)” + counts + **Go** / **Copy**
+- “Choclazo” details only with `debug=1`.
+
+---
+
+## 4) Copy debug (standard)
+
+**Copy debug** button per layer, with JSON including:
+
+- `version.gitCommit`
+- `href`
+- `layer`: status / error / loaded / visible
+- `timing`: loadingMs / slow / abortMs / abortReason (if applicable)
+- `map`: zoom + bounds
+- `stateHint` (if applicable)
+
+This is the “black box” so we do not depend on the console.
+
+---
+
+## 5) Preparation vs Dock (rule)
+
+- **Preparation** sets **defaults** (what is on when entering, based on port/conditions).
+- **Dock** controls **live** (actual toggle at the moment).
+- **Do not duplicate toggles** between both. In Preparation only “recommended preset” and **“Apply to Dock”** buttons.
+
+---
+
+## 6) MVP “showable” (Definition of Done v1)
+
+To say *“this can be shown to a fisher”*:
+
+- [ ] **GPS** works and is visible (marker + circle + tooltip).
+- [ ] **Signals (Seamarks)** ON by default and actually requests tiles.
+- [ ] **Zones** ON by default.
+- [ ] **FMAP** ON with something visible (near my location or port resources).
+- [ ] **Forecast** shows at least Tides in real form or “HOLD” clearly explained.
+- [ ] **No layer** fails silently: everything has state and Copy debug.
+
+---
+
+## 7) Change freeze (operational rule)
+
+From this contract onward:
+
+- **Do not move** a layer from its surface (Dock/Preparation/Forecast/Smart Fishing) without editing this doc.
+- **Do not mix** “Base maps” with “operational layers” again.
+- Every PR that touches the map must explicitly state: **“Contract impact: none / yes (section X)”**.
+
+---
+
+*Living document. Review on each map/Dock release.*