update reserach skill

2026-06-21 10:31:13 +00:00 · 2026-04-29 11:58:37 +03:00
parent f321268e1b
commit 5391d2c710
16 changed files with 1263 additions and 24 deletions
@@ -24,6 +24,7 @@ Phase details live in `phases/` — read the relevant file before executing each
 - **Save immediately**: write artifacts to disk after each phase
 - **Delegate execution**: all code changes go through the implement skill via task files
 - **Ask, don't assume**: when scope or priorities are unclear, STOP and ask the user
+- **Exact-fit recommendations**: do not recommend a replacement pattern, library, service, architecture, algorithm, or "modern approach" merely because it improves structure or solves a similar class of problem. It must fit confirmed product constraints, acceptance criteria, operating context, integration boundaries, and current code realities. Otherwise reject it, mark it experimental, or ask the user before adding it to the roadmap.

 ## Context Resolution

@@ -7,14 +7,17 @@
 ## 2a. Deep Research

 1. Analyze current implementation patterns
-2. Research modern approaches for similar systems
-3. Identify what could be done differently
-4. Suggest improvements based on state-of-the-art practices
+2. Extract the **Project Constraint Matrix** from `problem.md`, `restrictions.md`, `acceptance_criteria.md`, current architecture/docs, and actual code constraints. Include required inputs/outputs, operating context, lifecycle assumptions, integration boundaries, non-functional targets, and hard disqualifiers.
+3. Research modern approaches for similar systems
+4. For each alternative pattern/library/service/architecture/algorithm, research intrinsic implementation constraints: required inputs/outputs, runtime assumptions, supported deployment modes, resource needs, operational limits, licensing/security constraints, and known failure reports.
+5. Identify what could be done differently
+6. Suggest improvements only when they fit the Project Constraint Matrix. A cleaner or more modern approach that violates product constraints must be marked `Rejected` or `Experimental only`, not added as a roadmap recommendation.

 Write `RUN_DIR/analysis/research_findings.md`:
 - Current state analysis: patterns used, strengths, weaknesses
 - Alternative approaches per component: current vs alternative, pros/cons, migration effort
 - Prioritized recommendations: quick wins + strategic improvements
+- Constraint-fit table: recommendation, constraints checked, evidence, mismatches/disqualifiers, status (`Selected` / `Rejected` / `Experimental only` / `Needs user decision`)

 ## 2b. Solution Assessment & Hardening Tracks

@@ -22,6 +25,7 @@ Write `RUN_DIR/analysis/research_findings.md`:
 2. Identify weak points in codebase, map to specific code areas
 3. Perform gap analysis: acceptance criteria vs current state
 4. Prioritize changes by impact and effort
+5. Reject or escalate any proposed refactor that improves code structure while weakening required behavior, integration contracts, runtime constraints, safety/security posture, or acceptance criteria

 Present optional hardening tracks for user to include in the roadmap:

@@ -47,6 +51,9 @@ Write `RUN_DIR/analysis/refactoring_roadmap.md`:
 - Gap analysis: what's missing, what needs improvement
 - Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements)
 - Selected hardening tracks and their items
+- Applicability gate: each roadmap item must state constraint fit, mismatches, required evidence, and status (`Selected` / `Rejected` / `Experimental only` / `Needs user decision`)
+
+**BLOCKING applicability gate**: Before 2c and 2d, every recommendation in the roadmap must be `Selected`. Items marked `Rejected` are excluded. Items marked `Experimental only` or `Needs user decision` require a user decision before task creation.

 ## 2c. Create Epic

@@ -79,6 +86,9 @@ Convert the finalized `RUN_DIR/list-of-changes.md` into implementable task files
 **Self-verification**:
 - [ ] All acceptance criteria are addressed in gap analysis
 - [ ] Recommendations are grounded in actual code, not abstract
+- [ ] Every recommendation has been checked against the Project Constraint Matrix
+- [ ] No recommendation violates product restrictions, acceptance criteria, documented architecture decisions, or actual code integration boundaries
+- [ ] Rejected and experimental approaches are documented but not converted into implementation tasks without user approval
 - [ ] Roadmap phases are prioritized by impact
 - [ ] Epic created and all tasks linked to it
 - [ ] Every entry in list-of-changes.md has a corresponding task file in TASKS_DIR
@@ -23,6 +23,7 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
 - **Problem**: [what makes this problematic / untestable / coupled]
 - **Change**: [what to do — behavioral description, not implementation steps]
 - **Rationale**: [why this change is needed]
+- **Constraint Fit**: [which product constraints / acceptance criteria / integration boundaries this preserves; or "Rejected — violates ..."]
 - **Risk**: [low | medium | high]
 - **Dependencies**: [other change IDs this depends on, or "None"]

@@ -31,6 +32,7 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
 - **Problem**: [description]
 - **Change**: [description]
 - **Rationale**: [description]
+- **Constraint Fit**: [description]
 - **Risk**: [low | medium | high]
 - **Dependencies**: [C01, or "None"]
 ```
@@ -44,6 +46,8 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
 - **File(s)** must reference actual files verified to exist in the codebase
 - **Problem** describes the current state, not the desired state
 - **Change** describes what the system should do differently — behavioral, not prescriptive
+- **Constraint Fit** proves the change preserves confirmed product requirements, restrictions, acceptance criteria, architecture decisions, and integration contracts
+- Do not include changes whose only benefit is structural cleanliness if they weaken required behavior or violate constraints; record those as rejected in analysis instead
 - **Dependencies** reference other change IDs within this list; cross-run dependencies use tracker IDs
 - In guided mode, the input file entries are validated against actual code and enriched with file paths, risk, and dependencies before writing
 - In automatic mode, entries are derived from Phase 1 component analysis and Phase 2 research findings
@@ -30,6 +30,7 @@ Transform vague topics raised by users into high-quality, deliverable research r
 - **Internet-first investigation** — do not rely on training data for factual claims; search the web extensively for every sub-question, rephrase queries when results are thin, and keep searching until you have converging evidence from multiple independent sources
 - **Multi-perspective analysis** — examine every problem from at least 3 different viewpoints (e.g., end-user, implementer, business decision-maker, contrarian, domain expert, field practitioner); each perspective should generate its own search queries
 - **Question multiplication** — for each sub-question, generate multiple reformulated search queries (synonyms, related terms, negations, "what can go wrong" variants, practitioner-focused variants) to maximize coverage and uncover blind spots
+- **Exact-fit component selection** — never select a component, tool, library, service, architecture pattern, or algorithm merely because it solves a similar class of problem. It must be proven compatible with the project's explicit operating context, constraints, required inputs/outputs, non-functional requirements, lifecycle assumptions, and acceptance criteria. If fit is unproven or mismatched, mark it `Rejected`, `Experimental only`, or escalate for user decision before it can shape the solution.

 ## Context Resolution

@@ -34,6 +34,8 @@
 - [ ] Competitor analysis included: Existing solutions were researched
 - [ ] All components have comparison tables: Each component lists alternatives with tools, advantages, limitations, security, cost
 - [ ] Tools/libraries verified: Suggested tools actually exist and work as described
+- [ ] Component fit matrix completed: `06_component_fit_matrix.md` exists and every selected component/tool/pattern is marked `Selected`
+- [ ] No field-adjacent substitution: no selected candidate is chosen only because it solves a similar class of problem while failing the project's explicit constraints
 - [ ] Testing strategy covers AC: Tests map to acceptance criteria
 - [ ] Tech stack documented (if Phase 3 ran): `tech_stack.md` has evaluation tables, risk assessment, and learning requirements
 - [ ] Security analysis documented (if Phase 4 ran): `security_analysis.md` has threat model and per-component controls
@@ -45,6 +47,8 @@
 - [ ] New draft is self-contained: Written as if from scratch, no "updated" markers
 - [ ] Performance column included: Mode B comparison tables include performance characteristics
 - [ ] Previous draft issues addressed: Every finding in the table is resolved in the new draft
+- [ ] Existing component fit audited: every old and new component/tool/pattern was checked against `restrictions.md`, `acceptance_criteria.md`, and the Project Constraint Matrix
+- [ ] Rejected/experimental candidates are not lead recommendations unless the user explicitly accepted the risk

 ## Timeliness Check (High-Sensitivity Domain BLOCKING)

@@ -76,3 +80,14 @@ When the research topic has Critical or High sensitivity level:
 - [ ] Cited facts have corresponding statements in the original text (no over-interpretation)
 - [ ] Source publication/update dates annotated; technical docs include version numbers
 - [ ] Unverifiable information annotated `[limited source]` and not sole support for core conclusions
+
+## Exact-Fit Validation (BLOCKING)
+
+- [ ] Project Constraint Matrix extracted from problem context before component selection
+- [ ] Every selected component/tool/library/service/pattern/algorithm has evidence for required inputs/outputs and integration boundaries
+- [ ] Every selected candidate has evidence for the operating context and lifecycle assumptions it must support
+- [ ] Every selected candidate has evidence for non-functional targets that are binding for the project
+- [ ] Known unsupported scenarios and failure reports were searched for every selected candidate
+- [ ] Mismatches are recorded as disqualifiers, not softened into generic limitations
+- [ ] Any candidate with unproven fit is marked `Experimental only` or escalated for user decision
+- [ ] Any candidate with documented constraint conflict is marked `Rejected`
@@ -57,6 +57,7 @@ RESEARCH_DIR/
 ├── 03_comparison_framework.md     # Step 4 output: selected framework and populated data
 ├── 04_reasoning_chain.md          # Step 6 output: fact → conclusion reasoning
 ├── 05_validation_log.md           # Step 7 output: use-case validation results
+├── 06_component_fit_matrix.md     # Step 7.5 output: component exact-fit gate
 └── raw/                           # Raw source archive (optional)
    ├── source_1.md
    └── source_2.md
@@ -73,6 +74,7 @@ RESEARCH_DIR/
 | Step 4 | Selected comparison framework + initial population | `03_comparison_framework.md` |
 | Step 6 | Reasoning process for each dimension | `04_reasoning_chain.md` |
 | Step 7 | Validation scenarios + results + review checklist | `05_validation_log.md` |
+| Step 7.5 | Component exact-fit gate and selection status | `06_component_fit_matrix.md` |
 | Step 8 | Complete solution draft | `OUTPUT_DIR/solution_draft##.md` |

 ### Save Principles
@@ -95,6 +97,7 @@ RESEARCH_DIR/
 | `03_comparison_framework.md` | Selected framework and populated data | After Step 4 completion |
 | `04_reasoning_chain.md` | Fact → conclusion reasoning | After Step 6 completion |
 | `05_validation_log.md` | Use-case validation and review | After Step 7 completion |
+| `06_component_fit_matrix.md` | Exact-fit matrix for every proposed component/tool/pattern with status `Selected` / `Rejected` / `Experimental only` / `Needs user decision` | Before Step 8 deliverable formatting |
 | `OUTPUT_DIR/solution_draft##.md` | Complete solution draft | After Step 8 completion |
 | `OUTPUT_DIR/tech_stack.md` | Tech stack evaluation and decisions | After Phase 3 (optional) |
 | `OUTPUT_DIR/security_analysis.md` | Threat model and security controls | After Phase 4 (optional) |
@@ -73,16 +73,18 @@ Full 8-step research methodology. Produces the first solution draft.
 **Task** (drives the 8-step engine):
 1. Research existing/competitor solutions for similar problems — search broadly across industries and adjacent domains, not just the obvious competitors
 2. Research the problem thoroughly — all possible ways to solve it, split into components; search for how different fields approach analogous problems
-3. For each component, research all possible solutions and find the most efficient state-of-the-art approaches — use multiple query variants and perspectives from Step 1
-4. For each promising approach, search for real-world deployment experience: success stories, failure reports, lessons learned, and practitioner opinions
-5. Search for contrarian viewpoints — who argues against the common approaches and why? What failure modes exist?
-6. Verify that suggested tools/libraries actually exist and work as described — check official repos, latest releases, and community health (stars, recent commits, open issues)
-7. Include security considerations in each component analysis
-8. Provide rough cost estimates for proposed solutions
+3. Derive a **Project Constraint Matrix** before evaluating component options. Extract exact constraints from `problem.md`, `restrictions.md`, `acceptance_criteria.md`, input data notes, and the Phase 1 AC assessment. Include required inputs/outputs, operating context, runtime envelope, data availability, lifecycle boundaries, non-functional targets, integration boundaries, security constraints, and explicit out-of-scope decisions.
+4. For each component, research all possible solutions and find the most efficient state-of-the-art approaches — use multiple query variants and perspectives from Step 1
+5. For each promising approach, search for real-world deployment experience: success stories, failure reports, lessons learned, and practitioner opinions
+6. Search for contrarian viewpoints — who argues against the common approaches and why? What failure modes exist?
+7. Verify that suggested tools/libraries actually exist and work as described — check official repos, latest releases, and community health (stars, recent commits, open issues)
+8. For every candidate component/tool/library/service/pattern/algorithm, prove exact fit against the Project Constraint Matrix. A field-adjacent solution is not selectable unless its documented implementation assumptions match the project's constraints. Mismatches must be recorded as disqualifiers and the candidate marked `Rejected`, `Experimental only`, or `Needs user decision`.
+9. Include security considerations in each component analysis
+10. Provide rough cost estimates for proposed solutions

 Be concise in formulating. The fewer words, the better, but do not miss any important details.

-**Save action**: Write `OUTPUT_DIR/solution_draft##.md` using template: `templates/solution_draft_mode_a.md`
+**Save action**: Write `RESEARCH_DIR/06_component_fit_matrix.md` before the final draft, then write `OUTPUT_DIR/solution_draft##.md` using template: `templates/solution_draft_mode_a.md`

 ---

@@ -10,18 +10,25 @@ Full 8-step research methodology applied to assessing and improving an existing

 **Task** (drives the 8-step engine):
 1. Read the existing solution draft thoroughly
-2. Research in internet extensively — for each component/decision in the draft, search for:
+2. Derive or refresh the **Project Constraint Matrix** from all files in INPUT_DIR. Include required inputs/outputs, operating context, runtime envelope, data availability, lifecycle boundaries, non-functional targets, integration boundaries, security constraints, and explicit out-of-scope decisions.
+3. Audit every component/decision in the existing draft against the Project Constraint Matrix before researching alternatives:
+   - If a component's documented implementation assumptions match the project constraints, keep it eligible and record evidence.
+   - If fit is unproven, mark it `Experimental only` until evidence is found.
+   - If constraints conflict, mark it `Rejected` and search for alternatives.
+   - If rejecting it changes product behavior or risk materially, escalate for user decision.
+4. Research in internet extensively — for each component/decision in the draft, search for:
   - Known problems and limitations of the chosen approach
   - What practitioners say about using it in production
   - Better alternatives that may have emerged recently
   - Common failure modes and edge cases
   - How competitors/similar projects solve the same problem differently
-3. Search specifically for contrarian views: "why not [chosen approach]", "[chosen approach] criticism", "[chosen approach] failure"
-4. Identify security weak points and vulnerabilities — search for CVEs, security advisories, and known attack vectors for each technology in the draft
-5. Identify performance bottlenecks — search for benchmarks, load test results, and scalability reports
-6. For each identified weak point, search for multiple solution approaches and compare them
-7. Based on findings, form a new solution draft in the same format
+5. Search specifically for contrarian views: "why not [chosen approach]", "[chosen approach] criticism", "[chosen approach] failure"
+6. Identify security weak points and vulnerabilities — search for CVEs, security advisories, and known attack vectors for each technology in the draft
+7. Identify performance bottlenecks — search for benchmarks, load test results, and scalability reports
+8. For each identified weak point, search for multiple solution approaches and compare them
+9. For every revised candidate, prove exact fit against the Project Constraint Matrix. Do not select field-adjacent or "similar problem" options unless their intrinsic implementation constraints match the project.
+10. Based on findings, form a new solution draft in the same format

-**Save action**: Write `OUTPUT_DIR/solution_draft##.md` (incremented) using template: `templates/solution_draft_mode_b.md`
+**Save action**: Write `RESEARCH_DIR/06_component_fit_matrix.md` before the final draft, then write `OUTPUT_DIR/solution_draft##.md` (incremented) using template: `templates/solution_draft_mode_b.md`

 **Optional follow-up**: After Mode B completes, the user can request Phase 3 (Tech Stack Consolidation) or Phase 4 (Security Deep Dive) using the revised draft. These phases work identically to their Mode A descriptions in `steps/01_mode-a-initial-research.md`.
@@ -94,6 +94,9 @@ When decomposing questions, you must explicitly define the **boundaries of the r
 | **Geography** | Which region is being studied? | Chinese universities vs US universities vs global |
 | **Timeframe** | Which period is being studied? | Post-2020 vs full historical picture |
 | **Level** | Which level is being studied? | Undergraduate vs graduate vs vocational |
+| **Operating context** | What exact environment, lifecycle phase, and runtime conditions must the solution support? | In-flight embedded runtime vs offline post-processing; production web traffic vs admin batch job |
+| **Required interfaces** | What inputs, outputs, protocols, data shapes, and ownership boundaries are fixed? | One camera vs stereo rig; REST API vs message queue; local file boundary vs service API |
+| **Non-functional envelope** | What latency, throughput, storage, memory, availability, safety, security, cost, and maintainability targets are binding? | <400 ms p95, 8 GB RAM, 99.9% availability, reversible migrations |

 **Common mistake**: User asks about "university classroom issues" but sources include policies targeting "K-12 students" — mismatched target populations will invalidate the entire research.

@@ -116,6 +119,7 @@ Record the audit result in `00_question_decomposition.md` as a "Completeness Aud
   - Summary of relevant problem context from INPUT_DIR
   - Classified question type and rationale
   - **Research subject boundary definition** (population, geography, timeframe, level)
+   - **Project Constraint Matrix summary** (operating context, required interfaces, non-functional envelope, lifecycle assumptions, and hard disqualifiers extracted from input files)
   - List of decomposed sub-questions
   - **Chosen perspectives** (at least 3 from the Perspective Rotation table) with rationale
   - **Search query variants** for each sub-question (at least 3-5 per sub-question)
@@ -145,12 +149,23 @@ Do not stop at the first few results. The goal is to build a comprehensive evide
 - Consult at least **2 different source tiers** per sub-question (e.g., L1 official docs + L4 community discussion)
 - If initial searches yield fewer than 3 relevant sources for a sub-question, **broaden the search** with alternative terms, related domains, or analogous problems

+**Candidate implementation-limit searches (MANDATORY)**:
+For every component/tool/library/service/pattern/algorithm that may be selected or recommended, search for its intrinsic implementation constraints. Do not rely on product category labels, marketing summaries, or examples from a different operating context. Include query variants for:
+- Official supported inputs/outputs, protocols, data formats, and deployment modes
+- Required hardware/runtime/platform/version constraints
+- Timing, throughput, memory, storage, synchronization, and scaling assumptions
+- Lifecycle assumptions: offline vs online, batch vs real time, development vs production, single tenant vs multi tenant, local vs networked
+- Known unsupported scenarios, limitations, issue reports, production failures, and workarounds
+- Licensing, security, maintenance, and community-health constraints
+- Exact phrases from the project's restrictions and acceptance criteria combined with the candidate name
+
 **Search broadening strategies** (use when results are thin):
 - Try adjacent fields: if researching "drone indoor navigation", also search "robot indoor navigation", "warehouse AGV navigation"
 - Try different communities: academic papers, industry whitepapers, military/defense publications, hobbyist forums
 - Try different geographies: search in English + search for European/Asian approaches if relevant
 - Try historical evolution: "history of X", "evolution of X approaches", "X state of the art 2024 2025"
 - Try failure analysis: "X project failure", "X post-mortem", "X recall", "X incident report"
+- Try disqualifier probes: "X unsupported", "X limitations", "X requirements", "X with [project constraint]", "X without [required input]", "X real-time [target]", "X production failure"

 **Search saturation rule**: Continue searching until new queries stop producing substantially new information. If the last 3 searches only repeat previously found facts, the sub-question is saturated.

@@ -194,6 +209,7 @@ For each extracted fact, **immediately** append to `02_fact_cards.md`:
 - **Target Audience**: [which group this fact applies to, inherited from source or further refined]
 - **Confidence**: ✅/⚠️/❓
 - **Related Dimension**: [corresponding comparison dimension]
+- **Fit Impact**: [supports selection / disqualifies / makes experimental / needs user decision]
 ```

 **Target audience in fact statements**:
@@ -24,6 +24,15 @@ Write to `03_comparison_framework.md`:
 | ... | | | |
 ```

+**Required exact-fit dimensions for component/tool decisions**:
+When the output selects or recommends a component, tool, library, service, architecture pattern, or algorithm, the framework MUST include these dimensions unless explicitly not applicable:
+- Required inputs/outputs and ownership boundaries
+- Operating context and lifecycle fit
+- Non-functional envelope fit
+- Implementation assumptions and hard disqualifiers
+- Evidence quality and source tier
+- Selection status (`Selected`, `Rejected`, `Experimental only`, `Needs user decision`)
+
 ---

 ### Step 5: Reference Point Baseline Alignment
@@ -97,6 +106,8 @@ Validate conclusions against a typical scenario:
 - [ ] Are there any important dimensions missed?
 - [ ] Is there any over-extrapolation?
 - [ ] Are conclusions actionable/verifiable?
+- [ ] Does every selected component/tool/pattern match the Project Constraint Matrix?
+- [ ] Are mismatches marked as disqualifiers instead of hidden as generic "limitations"?

 **Save action**:
 Write to `05_validation_log.md`:
@@ -128,6 +139,31 @@ If using Y: [expected behavior]

 ---

+### Step 7.5: Component Applicability Gate (BLOCKING)
+
+Before finalizing the solution draft, build an exact-fit matrix for every component/tool/library/service/pattern/algorithm that is selected, recommended, rejected, or treated as a fallback.
+
+```markdown
+# Component Fit Matrix
+
+| Candidate | Intended Role | Project Constraints Checked | Evidence | Mismatches / Disqualifiers | Status | Decision Rationale |
+|-----------|---------------|-----------------------------|----------|----------------------------|--------|--------------------|
+| [name] | [role] | [constraints] | [Fact # / Source #] | [none / list] | Selected / Rejected / Experimental only / Needs user decision | [why] |
+```
+
+Rules:
+- `Selected` is allowed only when the candidate's documented implementation assumptions match the project's explicit constraints and acceptance criteria.
+- `Experimental only` is required when a candidate might work but lacks proof for the exact operating context.
+- `Rejected` is required when documented assumptions conflict with project constraints.
+- `Needs user decision` is required when a mismatch changes scope, cost, safety, product behavior, or acceptance criteria.
+- A candidate may not appear as the lead solution in Step 8 unless this gate marks it `Selected`.
+
+**Save action**: Write `06_component_fit_matrix.md`.
+
+**BLOCKING**: If any lead candidate is `Experimental only`, `Rejected`, or `Needs user decision`, do not silently proceed. Ask the user or choose a different selected candidate.
+
+---
+
 ### Step 8: Deliverable Formatting

 Make the output **readable, traceable, and actionable**.
@@ -14,8 +14,13 @@

 | Solution | Tools | Advantages | Limitations | Requirements | Security | Cost | Fit |
 |----------|-------|-----------|-------------|-------------|----------|------|-----|
-| [Option 1] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [cost] | [fit assessment] |
-| [Option 2] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [cost] | [fit assessment] |
+| [Option 1] | [lib/platform] | [pros] | [cons] | [intrinsic requirements] | [security] | [cost] | [Selected / Rejected / Experimental only / Needs user decision — cite exact-fit evidence and disqualifiers] |
+| [Option 2] | [lib/platform] | [pros] | [cons] | [intrinsic requirements] | [security] | [cost] | [Selected / Rejected / Experimental only / Needs user decision — cite exact-fit evidence and disqualifiers] |
+
+**Exact-fit evidence**:
+- Project constraints checked: [inputs/outputs, operating context, lifecycle, NFRs, acceptance criteria]
+- Evidence: [Fact # / Source #]
+- Disqualifiers: [none or list]

 [Repeat per component]

@@ -17,8 +17,13 @@

 | Solution | Tools | Advantages | Limitations | Requirements | Security | Performance | Fit |
 |----------|-------|-----------|-------------|-------------|----------|------------|-----|
-| [Option 1] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [perf] | [fit assessment] |
-| [Option 2] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [perf] | [fit assessment] |
+| [Option 1] | [lib/platform] | [pros] | [cons] | [intrinsic requirements] | [security] | [perf] | [Selected / Rejected / Experimental only / Needs user decision — cite exact-fit evidence and disqualifiers] |
+| [Option 2] | [lib/platform] | [pros] | [cons] | [intrinsic requirements] | [security] | [perf] | [Selected / Rejected / Experimental only / Needs user decision — cite exact-fit evidence and disqualifiers] |
+
+**Exact-fit evidence**:
+- Project constraints checked: [inputs/outputs, operating context, lifecycle, NFRs, acceptance criteria]
+- Evidence: [Fact # / Source #]
+- Disqualifiers: [none or list]

 [Repeat per component]

@@ -0,0 +1,308 @@
+# GPS-Denied Onboard System - Architecture
+
+## Architecture Vision
+
+The GPS-Denied stack is an onboard companion-computer software system for a fixed-wing UAV. It runs on a Jetson Orin Nano Super beside an ArduPilot flight controller and produces GPS-equivalent WGS84 position fixes when the real GPS is denied, jammed, or spoofed. The runtime shape is a ROS 2 Humble pipeline: camera frames, FC IMU/attitude/altitude telemetry, and a pre-loaded satellite tile cache flow through a cheap nadir motion bridge, conditional visual place recognition, cross-view matching for anchors/corrections, covariance calibration, MAVLink output, in-flight tile generation, and slim companion-side flight recording. The system owns only the onboard stack, the Jetson UI pre-flight workflow, the local tile-cache read/write behavior, and the provisioning workflow; upstream satellite sourcing and trusted basemap promotion remain owned by the Azaion Suite Satellite Service.
+
+Components and intent-level responsibilities:
+
+| Component | Responsibility |
+|-----------|----------------|
+| C-1 Satellite Tile Cache & Descriptor Index | Maintain the local MBTiles tile cache, descriptor indexes, freshness metadata, sidecar metadata, and read/write access for runtime localization and tile generation. |
+| C-1b Ortho-Tile Generator | Orthorectify eligible nav-cam frames into basemap-aligned z=19 tiles using camera calibration, pose, and per-sector DEM data. |
+| C-2 Visual Place Recognition | Retrieve candidate basemap chunks only on re-localization triggers using DINOv2 SALAD/BoQ or fallback descriptors over a FAISS index. |
+| C-3 Cross-View Matching & PnP | Match nav-cam frames to satellite basemap candidates, estimate absolute pose, and produce covariance for the output stage. |
+| C-4 Nadir Motion Bridge | Provide cheap per-frame/near-frame relative motion from nav-frame overlap, homography/optical flow, FC IMU, attitude, altitude, and DEM constraints between satellite-anchored fixes. |
+| C-5 Companion-Side Output Stage | Calibrate covariance, apply a Mahalanobis outlier gate, assign source labels, and emit GPS-equivalent fixes without doing state propagation. |
+| C-6 MAVLink Integration & Source Promotion | Manage MAVLink telemetry, signed GPS_INPUT injection, sysid separation, and spoofing-promotion behavior. |
+| C-7 Failsafe, Health & Re-Localization | Detect loss of confidence, raise re-localization workflows, report health, and keep FC failsafe behavior explicit. |
+| C-8 Object Localization | Compute coordinates for AI-camera detections from current GPS-Denied pose, gimbal angle, zoom, and altitude. |
+| C-9 Software Platform & Process Topology | Package and orchestrate the ROS 2 / MAVROS / rclpy / CUDA-TensorRT node graph on JetPack 6. |
+| C-10 Companion-Side FDR | Store only companion-unique forensic signals, tile-generation metadata, failure thumbnails, and Jetson health under a rolling retention cap. |
+| C-11 Confidence Score | Define and validate the `(sigma_xy, source_label)` contract carried by every emitted fix. |
+| C-12 Provisioning Tool | Provide `provision-fc.py`, guided camera calibration, FC parameter pinning, MAVLink2 signing bootstrap, smoke tests, and signed airframe-manifest generation. |
+
+Architectural principles and non-negotiables:
+
+- Q1) Tile-cache + sidecar schema authority = THIS build (sole owner).
+- Q2) Operator-hint MAVLink mechanism is OOS for v1; QGC is the only GCS; no custom Azaion GCS service exists.
+- Q3) Tile-cache folder is the boundary contract with the Suite Satellite Service. Pre-flight: operator uses Jetson UI (deployed on Jetson, with internet) to draw route + sector; flights API requests tiles from Suite Satellite Service; tiles land in `/var/azaion/tile-cache/` (path owned by `../satellite-service/`). Companion reads + writes during/post flight. Throughput-sensitive on initial pre-load (~700 MB at z=19).
+- Q4) Three-scope configuration model: Global = bundled in companion deployment image. Per-airframe = signed manifest produced by Provisioning Tool (NEW Component 12) at client setup. Per-mission = YAML written by Jetson UI alongside the tile fetch (operational area polygon, sector classes, mission ID).
+- Q5) Suite Satellite Service contract authorship lives in `../satellite-service/`. This build references, does not own. Includes tile-cache folder layout + file allocation.
+- Q6 / F2b) SLIM companion FDR - companion-side-unique signals only: per-frame source-label decisions + gate values (matcher inliers, VPR top-K scores, sigma_xy pre/post calibration, Mahalanobis distance), tile-generation events with sidecar metadata, failure thumbnails (<=0.1 Hz), Jetson health (CPU/GPU/temp/throttle, 1 Hz delta-encoded). Format: FlatBuffers + zstd at segment close. Retention: rolling 3 flights, oldest auto-removed. Storage cap: ~2 GB total (~500 MB/flight). FC dataflash remains authoritative for IMU, GPS_INPUT receipts, EKF3 state, MAVLink tlog - companion does NOT duplicate.
+- F3b) Storage tile zoom locked to z=19 (60 cm/px), 5x scale ratio vs nav cam. Documented fall-back to z=20 if matcher bench-off shows AC-2.2 (cross-domain MRE <2.5 px) failure.
+- FC connection (per F1 elaboration): Provisioning Tool `provision-fc.py` one-button workflow - detect FC, pin SERIAL2_BAUD/PROTOCOL, pin GPS1_TYPE=14 + EK3_SRC1_*, bootstrap MAVLink2 signing key, smoke-test (RAW_IMU rate + GPS_INPUT round-trip). Manual residuals: physical wiring (labeled harness), checkerboard intrinsics cal (guided by Jetson UI), FC compass/accelerometer cal (standard QGC procedure).
+
+Open architecture research item:
+
+- Cross-view matcher accuracy at z=19 (5x scale ratio) on Orin Nano Super must validate AC-2.2 cross-domain MRE <2.5 px before the z=19 lock is treated as final for deployment. z=20 remains the documented fallback if bench-off fails.
+
+## 1. System Context
+
+**Problem being solved**: the UAV must continue estimating the GPS coordinates of navigation-camera frame centers, and AI-camera object centers, when true GPS is denied or spoofed. It has an initial GPS handoff, a downward fixed nav camera, FC IMU/attitude telemetry, and pre-loaded satellite imagery, but must operate in real time on a constrained Jetson platform for long fixed-wing missions.
+
+**System boundaries**:
+
+- Inside this build: Jetson UI, companion runtime nodes, local tile cache schema and sidecars, VPR/matcher/VO/output/FDR nodes, provisioning tool, FC parameter bootstrap, and post-flight tile upload client behavior.
+- Outside this build: satellite imagery procurement, trusted-basemap promotion, Suite Service ingest/voting implementation, QGroundControl itself, ArduPilot firmware internals, AI detection model internals, and GCS-side custom application development.
+
+**External systems**:
+
+| System | Integration Type | Direction | Purpose |
+|--------|------------------|-----------|---------|
+| ArduPilot FC | MAVLink2 over serial/USB | Both | Source of IMU/attitude/GPS-health telemetry; sink for signed GPS_INPUT position fixes. |
+| QGroundControl | MAVLink via FC telemetry | Outbound primarily | Operator situational awareness through 1-2 Hz summary and STATUSTEXT events. |
+| Azaion Suite Satellite Service | HTTPS/API + tile-cache folder contract | Both, pre/post flight only | Supplies pre-flight tiles and receives candidate onboard tiles after landing. |
+| AI detection systems | Local process/topic API | Inbound request, outbound coordinates | Request AI-camera object geolocation using GPS-Denied pose. |
+| Public/field test corpora | Offline files | Inbound to tests/bench-off | Provide validation data for matcher, VO, and robustness acceptance criteria. |
+
+## 2. Technology Stack
+
+| Layer | Technology | Version / Constraint | Rationale |
+|-------|------------|----------------------|-----------|
+| OS / BSP | JetPack 6 on Ubuntu 22.04 | Jetson Orin Nano Super, 25 W mode | Matches hardware target and CUDA/TensorRT availability. |
+| Robotics middleware | ROS 2 Humble | Locked v1 orchestration choice | Provides node contracts, bags, topic introspection, diagnostics, and MAVROS integration without assuming cuVSLAM applicability. |
+| Runtime languages | C++ and Python | C++ for Isaac/MAVROS nodes; Python 3.11/3.12 for rclpy nodes | Reuses existing ROS ecosystem while keeping model and orchestration logic simple. |
+| Nadir motion bridge | Custom/bench-selected fixed-wing nadir VO: homography/optical flow + FC IMU/attitude/altitude + DEM constraints | Single fixed nadir camera, fixed-wing flight | Matches the actual sensor topology. Isaac ROS cuVSLAM is not selected for v1 because official docs center on stereo/multi-camera VIO and do not prove support for one monocular nadir camera in this flight envelope. |
+| Matching / retrieval | TensorRT, SP+LG/GIM-LG, LiteSAM fallback, FAISS | FP16 default, INT8 when validated | Keeps inline matching under latency budget while preserving a rare re-loc fallback. |
+| Tile storage | MBTiles SQLite + WAL | z=19 storage, sidecar schema owned here | One persistent local cache with transactional writes and predictable file footprint. |
+| Data serialization | FlatBuffers + zstd | Segment compression at close | Low-overhead FDR format with bounded storage. |
+| MAVLink | MAVROS, pymavlink, MAVSDK | `GPS_INPUT` via pymavlink sysid=11; telemetry via MAVSDK sysid=10 | MAVSDK lacks native GPS_INPUT; sysid separation avoids router daemon. |
+| Orthorectification | Orthority with fallback to OpenCV + DEM | SRTM-30 m DEM | Uses a maintained projection library, with a measured fallback if F-T14 fails. |
+| Database | None for app state; SQLite inside MBTiles | Local file only | No server database belongs on the aircraft runtime path. |
+| CI/CD | Containerized build and hardware bench gates | Later deployment artifacts | Must build TRT engines at install time and run SITL/bench-off gates before flight release. |
+
+**Key constraints from `restrictions.md` and Phase 2a decisions**:
+
+- Runtime hardware is Jetson Orin Nano Super with 8 GB shared memory and 25 W thermal envelope.
+- Flights last up to 8 hours, at about 60 km/h, over up to 400 km2 operational areas.
+- Satellite imagery is pre-loaded only; in-flight network access to the Service is not part of the runtime path.
+- QGroundControl is the only supported GCS in v1.
+- ArduPilot is the only v1 autopilot target; PX4 is out of scope.
+- The confirmed architecture supersedes stale z=20/full-FDR source wording with z=19 storage and slim companion FDR.
+
+## 3. Deployment Model
+
+**Environments**:
+
+| Environment | Purpose | Representative Runtime |
+|-------------|---------|------------------------|
+| Development | Local component development, unit tests, fixture generation | Dev machine plus containerized ROS 2 nodes where possible. |
+| Bench / SITL | MAVLink loop, cold start, source switching, and signing tests | Jetson or Jetson-equivalent container + ArduPilot SITL. |
+| HIL / Field Test | Thermal, camera, FC, and real hardware validation | Actual Jetson, FC, cameras, NVMe, and harness. |
+| Production Flight | Operational aircraft runtime | Signed companion image, signed airframe manifest, mission YAML, local tile cache. |
+
+**Infrastructure**:
+
+- Onboard deployment is a companion image installed on the Jetson with ROS 2 packages, Python nodes, TensorRT engines, CUDA assets, calibration files, and provisioning tooling.
+- No cloud service is required in flight. The Suite Satellite Service is contacted before flight for tile fetch and after flight for candidate upload.
+- The local persistent storage layout separates the service-owned tile-cache boundary from FDR segments, logs, mission YAML, and airframe manifests.
+
+**Environment-specific configuration**:
+
+| Config Scope | Development / Bench | Production Flight |
+|--------------|---------------------|-------------------|
+| Global | Repository defaults and dev image values | Bundled in signed companion deployment image. |
+| Per-airframe | Test manifest | Signed manifest from Provisioning Tool containing FC params, sysids, signing fingerprint, and camera intrinsics. |
+| Per-mission | Fixture YAML | Mission YAML written by Jetson UI with operational polygon, sector classes, and mission ID. |
+| Secrets | Dev-only keys, never shared | MAVLink2 signing key provisioned to FC; no hardcoded keys in image. |
+| Logging | Console + bags + local logs | Slim FDR + selected ROS 2 bags where explicitly enabled for tests. |
+
+## 4. Data Model Overview
+
+| Entity | Description | Owned By Component |
+|--------|-------------|--------------------|
+| Airframe Manifest | Signed per-airframe record of FC parameter pins, sysids, signing key fingerprint, and camera calibration references. | C-12 |
+| Mission YAML | Per-mission operational polygon, sector classification, mission ID, and cache-fetch metadata. | Jetson UI / C-12 |
+| Tile Cache | Persistent MBTiles store and sidecar schema under `/var/azaion/tile-cache/`. | C-1 |
+| Tile Sidecar | Metadata for tiles: capture date, trust level, parent pose sigma, terrain class, source, and freshness state. | C-1 / C-1b |
+| VPR Chunk | Ground-footprint retrieval unit derived from storage tiles, multi-scale in active-conflict sectors. | C-2 |
+| Pose Hypothesis | Relative or absolute pose plus covariance from VO or matcher. | C-3 / C-4 |
+| Position Estimate | WGS84 fix, covariance, source label, gate values, and timestamp emitted toward FC. | C-5 / C-11 |
+| Tile Generation Event | Eligibility, quality, dedup, write decision, and sidecar metadata for an onboard tile. | C-1b / C-10 |
+| FDR Segment | FlatBuffers segment compressed with zstd at close, stored under rolling retention. | C-10 |
+| Object Geolocation Request | AI-camera detection plus gimbal/zoom/altitude inputs and resulting object coordinate. | C-8 |
+
+**Key relationships**:
+
+- One airframe has one active signed airframe manifest and many missions.
+- One mission has one mission YAML, one operational area, many sectors, many VPR chunks, and a bounded local tile cache subset.
+- One position estimate may be satellite-anchored, VO-extrapolated, or dead-reckoned; only valid estimates are emitted as `GPS_INPUT`.
+- One onboard-generated tile is tied to a parent position estimate and may later be uploaded as a candidate to the Suite Satellite Service.
+- One FDR segment contains many position estimate decisions, gate values, tile-generation events, health samples, and failure thumbnails.
+
+**Data flow summary**:
+
+- Suite Satellite Service -> Jetson UI -> Tile Cache: pre-flight tile fetch and descriptor/index preparation.
+- Nav Cam + FC IMU/attitude/altitude -> Nadir Motion Bridge -> Output Stage -> ArduPilot FC: cheap per-frame or near-frame motion propagation between satellite anchors.
+- Tile Cache -> VPR/Matcher -> Output Stage: initial anchors, periodic drift correction, re-localization, and confidence reset. Satellite matching is not the every-frame path.
+- Nav Cam + Position Estimate + DEM -> Ortho-Tile Generator -> Tile Cache -> Suite Service: in-flight tile write and post-flight candidate upload.
+- Companion Nodes -> FDR: companion-unique forensic record only.
+
+## 5. Integration Points
+
+### Internal Communication
+
+| From | To | Protocol / Format | Pattern | Notes |
+|------|----|-------------------|---------|-------|
+| Nav camera ingest | Nadir motion bridge, matcher, tile generator | ROS 2 image topics | Stream | Raw frames are processed in memory and not retained. |
+| MAVROS | Nadir motion bridge, output stage, object localization | ROS 2 topics | Stream | Provides FC IMU, attitude, altitude, EKF/GPS health. |
+| Tile cache | VPR, matcher, tile generator | SQLite/MBTiles + sidecar API | Local file access | WAL and transaction batching required. |
+| VPR | Matcher | Candidate chunk shortlist | Request/response | Invoked conditionally, not on every frame. |
+| Matcher/PnP | Output stage | Pose hypothesis + covariance | Event | Input to Mahalanobis gate and covariance calibration. |
+| Output stage | MAVLink injector | GPS_INPUT payload | Command | v1 emits GPS_INPUT only. |
+| Runtime nodes | FDR writer | FlatBuffers records | Append | Records companion-side-unique signals. |
+| AI detection systems | Object localization | Local API/topic | Request/response | Uses current position and AI camera pose inputs. |
+
+### External Integrations
+
+| External System | Protocol | Auth | Rate / Limits | Failure Mode |
+|-----------------|----------|------|---------------|--------------|
+| ArduPilot FC | MAVLink2 | Mandatory signing on flight link | Per-frame GPS_INPUT, health telemetry | If output stops >3 s, FC falls back to IMU-only dead reckoning. |
+| QGroundControl | MAVLink via FC | FC/GCS link controls | 1-2 Hz downsampled summary | Operator sees degraded status; no custom GCS service exists. |
+| Suite Satellite Service | HTTPS/API + folder contract | Suite auth outside this build | Pre-flight/post-flight only | Flight can proceed only with sufficient local cache; no in-flight fetch. |
+| Field/bench corpora | Files/datasets | Dataset-specific | Offline tests only | Deferred-corpus rows remain blocked until data is acquired. |
+
+## 6. Non-Functional Requirements
+
+| Requirement | Target | Measurement | Priority |
+|-------------|--------|-------------|----------|
+| Frame-center accuracy | >=80% within 50 m; >=50% within 20 m in normal segments | Replay against ground truth | High |
+| Cross-domain registration | MRE <2.5 px | Matcher bench-off and replay tests | High |
+| VO drift | <100 m VO-only or <50 m with IMU between anchors | AerialVL / field replay | High |
+| End-to-end latency | <400 ms p95 camera-to-FC output | Jetson 25 W benchmark | High |
+| Memory | <8 GB shared LPDDR5 | Runtime telemetry under load | High |
+| Cold start TTFF | <30 s p95 | 50x boot bench | High |
+| Spoofing promotion | <3 s p95 | SITL spoofing scenario | High |
+| False-position safety | P(error >500 m) <0.1%; P(error >1 km) <0.01% per flight | Monte Carlo replay | High |
+| Tile poisoning safety | P(tile error >30 m) <1%; >100 m <0.1% per flight | Multi-flight Monte Carlo | High |
+| Thermal envelope | 25 W sustained for 8 h at +50 C, no throttling | Hot-soak HIL | High |
+| FDR retention | Rolling 3 flights; ~2 GB total cap | 8-hour synthetic load | Medium |
+| Tile cache footprint | About 700 MB for 400 km2 at z=19 plus index/DEM overhead | Cache-generation run | Medium |
+
+## 7. Security Architecture
+
+**Authentication and trust boundaries**:
+
+- MAVLink2 signing is mandatory for flight links between the companion and FC.
+- The airframe manifest is signed and produced during provisioning; runtime refuses to silently invent missing FC/signing/camera parameters.
+- Suite Service auth is used only during pre-flight tile fetch and post-flight candidate upload.
+
+**Authorization**:
+
+- The Jetson UI exposes provisioning and mission setup functions only in the ground/pre-flight context.
+- Runtime flight nodes do not accept arbitrary GCS commands; v1 operator hints are out of scope except standard QGC status/telemetry visibility.
+
+**Data protection**:
+
+- At rest: no raw nav-cam or AI-camera frames are retained in normal operation. FDR contains bounded forensic metadata and failure thumbnails only.
+- In transit: MAVLink2 signing protects the companion-FC link; Suite Service calls must use TLS.
+- Secrets: no MAVLink signing key or Suite credential is hardcoded in source or image defaults.
+
+**Audit logging**:
+
+- FDR records source-label decisions, gate values, tile-generation events, signing/provisioning status, promotion/demotion events, and Jetson health.
+- FC dataflash remains authoritative for IMU, received GPS_INPUT, EKF3 state, and MAVLink tlog.
+
+## 8. Key Architectural Decisions
+
+### ADR-001: ROS 2 Humble Runtime, Without cuVSLAM as v1 VO Lead
+
+**Context**: the runtime needs ROS 2 integration for camera ingest, FC telemetry, node observability, and MAVLink plumbing. However, the aircraft has one fixed nadir monocular nav camera. Isaac ROS Visual SLAM / cuVSLAM is not documented as a proven fit for this exact sensor topology and fixed-wing altitude/speed envelope; its official material centers on stereo/multi-camera visual-inertial SLAM.
+
+**Decision**: use ROS 2 Humble on JetPack 6 as the v1 runtime platform, but do not select cuVSLAM as the v1 visual-odometry lead. C-4 is a nadir-specific motion bridge using frame overlap/homography/optical flow plus FC IMU/attitude/altitude and DEM constraints. cuVSLAM is `Rejected for v1` unless future bench evidence proves reliable operation with one monocular nadir camera under the actual fixed-wing flight envelope.
+
+**Alternatives considered**:
+
+1. Isaac ROS cuVSLAM as the VO lead - rejected for v1 because exact-fit support is unproven for one monocular nadir camera at the required flight conditions.
+2. Single Python asyncio orchestrator - rejected because FC telemetry, camera ingest, diagnostics, and replay tooling benefit from ROS 2 contracts.
+3. Mixed ad hoc subprocess topology - rejected because observability, topic contracts, and failure recovery would be weaker.
+
+**Consequences**: accepts DDS overhead and larger image footprint in exchange for robotics tooling, but keeps the motion-estimation algorithm matched to the actual aircraft sensor geometry. C-4 must be validated with a bench-off against the project acceptance criteria before implementation lock.
+
+### ADR-002: GPS_INPUT Only in v1
+
+**Context**: parallel GPS_INPUT and ODOMETRY for overlapping axes risks EKF3 double-fusion behavior.
+
+**Decision**: v1 emits signed GPS_INPUT only; ODOMETRY remains disabled until a v1.1 SITL gate proves clean source switching.
+
+**Alternatives considered**:
+
+1. Emit GPS_INPUT and ODOMETRY together - rejected because of documented EKF3 instability risks.
+2. ODOMETRY-primary v1 - rejected because the product framing and ArduPilot parameter path are currently GPS-substitute oriented.
+
+**Consequences**: covariance fidelity is limited to GPS_INPUT fields, so companion-side calibration and gate correctness become more important.
+
+### ADR-003: No Companion-Side State-Propagating Filter in v1
+
+**Context**: a companion EKF feeding FC EKF3 duplicates fusion responsibilities.
+
+**Decision**: C-5 calibrates covariance, gates outliers, labels source, and emits fixes; ArduPilot EKF3 remains the only state-propagating filter.
+
+**Alternatives considered**:
+
+1. Companion EKF - rejected because it creates double-fusion and ownership ambiguity.
+2. Companion ESKF - reserved for v1.x only if evidence requires it.
+
+**Consequences**: VO and matcher components must expose honest covariance; F-T18 and AC-NEW-4 become critical safety gates.
+
+### ADR-004: z=19 Tile Storage with z=20 Fallback
+
+**Context**: Phase 2a.0 locked z=19 to reduce cache preload from about 2.8 GB to about 700 MB for 400 km2, accepting a 5x scale ratio to the nav camera.
+
+**Decision**: store the runtime basemap as z=19 MBTiles and validate cross-domain accuracy empirically before deployment lock.
+
+**Alternatives considered**:
+
+1. z=20 storage - safer matcher scale ratio but heavier preload; retained as fallback if z=19 fails AC-2.2.
+2. z=18 storage - rejected because scale ratio is too high for reliable matching.
+
+**Consequences**: the matcher bench-off must explicitly test z=19 cross-view MRE <2.5 px on Orin Nano Super.
+
+### ADR-005: Tile-Cache Folder Boundary with Suite Satellite Service
+
+**Context**: the Suite Satellite Service owns upstream imagery sourcing and trusted-basemap promotion, while this build owns onboard runtime use.
+
+**Decision**: this build owns tile-cache schema and sidecars locally, but treats the folder layout/file allocation contract as authored by `../satellite-service/`.
+
+**Alternatives considered**:
+
+1. Direct commercial-provider integration onboard - rejected as out of scope and unavailable in flight.
+2. This build owning Service ingest/voting - rejected because it belongs to the sibling Satellite Service.
+
+**Consequences**: Plan Step 3 must produce clear interface tasks and avoid implementing Service internals in this repo.
+
+### ADR-006: Slim Companion-Side FDR
+
+**Context**: older AC wording asked the companion to retain IMU, GPS_INPUT receipts, MAVLink tlog, and larger per-flight payloads that the FC already records.
+
+**Decision**: the companion FDR stores companion-side-unique signals only, compressed as FlatBuffers + zstd, rolling 3 flights under about 2 GB total.
+
+**Alternatives considered**:
+
+1. Full duplicate FDR on companion - rejected because FC dataflash is authoritative and duplicate storage increases write load and retention risk.
+2. No companion FDR - rejected because gate values and failure thumbnails are needed for false-position and tile-poisoning analysis.
+
+**Consequences**: AC-NEW-3 and related test docs need a coordinated wording update in a later Plan/Decompose cleanup.
+
+### ADR-007: Provisioning Tool as a First-Class Component
+
+**Context**: FC parameter pinning, signing setup, camera calibration, and manifest creation are too safety-critical to leave as manual tribal knowledge.
+
+**Decision**: add C-12 Provisioning Tool to v1 deliverables.
+
+**Alternatives considered**:
+
+1. Manual runbook only - rejected because repeatability and auditability are insufficient.
+2. Fold provisioning into runtime nodes - rejected because provisioning is a ground-time workflow with different privileges and failure modes.
+
+**Consequences**: component decomposition must include provisioning tasks, manifest validation, FC smoke tests, and Jetson UI guided calibration steps.
+
+## 9. Known Source Deltas to Resolve Later
+
+These deltas are intentionally not side-edited during Phase 2a. They should be handled as a coordinated cleanup after architecture confirmation or during Plan Step 3 / Decompose:
+
+- `_docs/00_problem/restrictions.md` still states z=20 and about 2.8 GB cache; update to z=19 and about 700 MB if this architecture is confirmed.
+- `_docs/00_problem/acceptance_criteria.md` AC-NEW-3 still describes a large duplicate FDR; rewrite to the slim companion-side FDR contract.
+- `_docs/00_problem/acceptance_criteria.md` AC-2.2 should explicitly call out the z=19 5x scale-ratio validation and z=20 fallback.
+- `_docs/01_solution/solution.md` needs Component 1, Component 10, and new Component 12 updates to match this architecture.
@@ -0,0 +1,151 @@
+# Glossary
+
+> **Status**: confirmed-by-user
+> **Date**: 2026-04-27
+> **Scope**: project-specific terminology only. Generic software / network / OS terms (REST, JSON, TCP, container, etc.) are intentionally excluded.
+> **Source convention**: `(source: <file> [§<section>])` — points back to the input where the term originates. `(decision: 2026-04-27)` marks terms whose meaning was locked during the Phase 2a.0 review.
+
+---
+
+## A
+
+- **Absolute pose** — position + orientation derived from a cross-view match against the satellite basemap (Component 3 + PnP). Synonym: *visual fix*, *satellite-anchored fix*, *anchor fix*. Distinguished from *relative pose*. (source: solution.md §Component 3)
+- **Active-conflict sector** — operational sub-area where building destruction or major scene change is expected; drives stricter freshness budget (<6 months) and larger VPR top-K. (source: AC-8.2, AC-NEW-6)
+- **AGL** — Above Ground Level (altitude reference). UAV mission profile is ≤1 km AGL. (source: restrictions.md §UAV & Flight)
+- **AI camera** — operator-controllable mission camera with gimbal + zoom; output consumed by onboard AI detection systems. Distinct from the nav cam. Pose available to this build: gimbal angle + zoom only (not airframe bank/pitch). (source: restrictions.md §Cameras, AC-7.1)
+- **Airframe manifest** — per-airframe signed configuration document produced by the Provisioning Tool (Component 12) at client setup. Contains FC firmware version, MAVLink2 signing-key fingerprint, sysid assignments (10/11), camera intrinsics, FC parameter pinning. (decision: 2026-04-27)
+- **Anchor fix** — see *absolute pose*.
+- **ArduPilot** — autopilot firmware. The only autopilot target in v1 scope. Configured with `GPS1_TYPE=14` for MAVLink GPS injection. PX4 is out of v1 scope. (source: restrictions.md §Sensors & Integration; AC-4.3)
+- **Azaion Suite** — the broader product family this build is one component of. Sibling components include Satellite Service, AI detection, semantic detection. (source: AC-8.1; decision: 2026-04-27)
+- **Azaion Suite Satellite Service** — sibling Suite component responsible for upstream satellite imagery sourcing and onboard-tile ingest with 2-flight voting. Out of scope for this build except at the **tile-cache folder boundary**. Contract authorship lives in `../satellite-service/`. (source: AC-8.1; decision: 2026-04-27)
+
+## B
+
+- **Basemap** — the satellite reference imagery surface against which UAV nav-cam frames are matched. Stored as MBTiles z=19 in the local tile cache. (source: AC-NEW-7, solution.md §Tile generation; decision: 2026-04-27)
+- **Bench-off** — comparative empirical measurement on Orin Nano Super @ 25 W against the dataset suite (AerialVL / UAV-VisLoc / AerialExtreMatch / 2chADCNN season set / TartanAir V2 / internal Mavic / first internal fixed-wing flight). Used to lock matcher / VO / VPR / z-level decisions. (source: solution.md §Component 3, §Component 4)
+
+## C
+
+- **Candidate pool** — Service-side staging area for onboard-generated tiles awaiting 2-flight voting promotion. Companion writes here post-flight; Service ingest reads. (source: solution.md §Tile generation; AC-NEW-7)
+- **Companion computer** — the Jetson Orin Nano Super running this build alongside the FC. Not the FC itself, not the GCS. (source: restrictions.md §Onboard Hardware)
+- **Companion-side FDR** — slim flight log on the companion NVMe holding ONLY signals the FC dataflash does not capture (per-stage gate values, source-label decisions, tile-generation events, failure thumbnails, Jetson health). 3-flight rolling retention, ~500 MB/flight compressed. Distinct from the FC dataflash. (decision: 2026-04-27, supersedes AC-NEW-3 v1.0)
+- **Confidence score** — `(σ_xy, source_label)` pair carried on every emitted fix. Cross-cutting (Component 11). (source: AC-1.4)
+- **Cross-view matching** — matching a UAV nav-cam frame against a satellite basemap chunk to obtain an absolute pose. Cross-domain (aerial photo ↔ ortho satellite tile) — distinguished from frame-to-frame VO matching. (source: solution.md §Component 3)
+- **cuVSLAM** — NVIDIA's CUDA-accelerated monocular+IMU VO/SLAM engine. v1 visual odometry (Component 4). Apache-2.0, drop-in via `isaac_ros_visual_slam` ROS 2 wrapper. (source: solution.md §Component 4; M-22, M-23)
+
+## D
+
+- **Dead reckoning** — IMU-only position propagation when no visual fix is available. Source-label `dead_reckoned`. Performed FC-side by EKF3, never companion-side in v1. (source: AC-1.4, AC-5.2; M-26)
+- **DEM** — Digital Elevation Model. SRTM-30 m DEM is loaded per-sector and consumed by Component 1b (Orthority) for orthorectification. (source: solution.md §Component 1b)
+- **DDS** — middleware transport layer used by ROS 2 Humble. ~2–5 % CPU overhead accepted in exchange for `isaac_ros_visual_slam` + MAVROS integration. (source: solution.md §Component 9)
+
+## E
+
+- **EKF3** — ArduPilot's 24-state classical extended Kalman filter, runs at 400 Hz on the FC. The ONLY state-propagating filter in the v1 system. Consumes our `GPS_INPUT` plus its own IMU/baro/compass. (source: solution.md §Component 5; M-26)
+- **ESKF** — Error-State Kalman Filter; tangent-space covariance on SO(3). Reserved for a hypothetical v1.x companion-side filter only — NOT used in v1. (source: solution.md §Component 5; S69)
+
+## F
+
+- **Failsafe** — autopilot fallback to IMU-only dead reckoning when this build fails to emit a fix for >3 s. (source: AC-5.2; restrictions.md §Failsafe)
+- **FC** — Flight Controller; the ArduPilot board on the airframe. (source: restrictions.md §Sensors & Integration)
+- **FC dataflash** — ArduPilot's microSD-resident binary log on the FC itself. Authoritative for IMU traces, received `GPS_INPUT` frames, EKF3 internal state, MAVLink raw tlog. Companion-side FDR does NOT duplicate these. (decision: 2026-04-27)
+- **Failure thumbnail** — low-rate (≤0.1 Hz) downsampled JPEG of nav-cam frames that failed tile generation. Forensic-only, retained on companion FDR for AC-NEW-7 audit. Other frames are NOT retained (no raw-frame storage policy). (source: AC-8.5, AC-NEW-3 revised)
+- **FDR** — Flight Data Recorder. In this build refers to the *companion-side* FDR (slim, companion-side-unique signals only). Not to be confused with the FC dataflash. See *Companion-side FDR*. (source: AC-NEW-3 revised; decision: 2026-04-27)
+- **Fixed-wing** — UAV airframe type (winged, not multirotor). The only airframe class in scope. (source: restrictions.md §UAV & Flight)
+- **Frame center** — geographic center of a navigation-camera frame projected onto the ground. Primary AC-1.1 / AC-1.2 accuracy target. Synonym: *photo center* (problem.md uses "photo", AC uses "frame"). (source: problem.md, AC-1.1)
+- **Freshness budget** — maximum allowable age of a satellite tile: <6 months for active-conflict sectors, <12 months for stable rear sectors. Tiles past budget are rejected or down-confidence-weighted. (source: AC-8.2, AC-NEW-6)
+
+## G
+
+- **GCS** — Ground Control Station. In this build, **only QGroundControl** is supported. Mission Planner is not in scope. There is no Azaion-custom GCS service. (source: AC-6.1, restrictions.md §Sensors; decision: 2026-04-27)
+- **GPS_INPUT** — MAVLink message ID used to inject the GPS-equivalent fix into ArduPilot. Carries `h_acc`, `v_acc`, `vel_acc` covariance. The single MAVLink output channel from this build to the FC in v1. (source: AC-4.3)
+- **GPS-denial** — operational condition where real GPS is jammed, spoofed, or otherwise unavailable. The trigger condition for this build's promotion to FC primary GPS source. (source: problem.md, AC-NEW-2)
+- **GPS-Denied system / GPS-Denied stack** — this build itself; the onboard companion-computer software stack. Synonyms: *the build*, *companion-side software*. (source: AC-8.1)
+- **GSD** — Ground Sample Distance, in cm/px on the ground. Nav cam at 1 km AGL ≈ 12 cm/px. Basemap at z=19 ≈ 60 cm/px. Scale ratio (basemap GSD / nav-cam GSD) is the matcher's binding constraint. (source: restrictions.md §Cameras, AC-8.1; decision: 2026-04-27)
+
+## I
+
+- **Isaac ROS** — NVIDIA's robotics middleware extensions on ROS 2 Humble. Provides `isaac_ros_visual_slam` for cuVSLAM integration. v1 orchestration platform alongside MAVROS. (source: solution.md §Component 9; Q6 → A)
+
+## J
+
+- **Jetson Orin Nano Super** — the onboard processing platform. 67 TOPS sparse INT8, 8 GB shared LPDDR5 (CPU+GPU share the same pool), 25 W TDP. Runs JetPack 6 / Ubuntu 22.04. (source: restrictions.md §Onboard Hardware)
+- **Jetson UI** — pre-flight web UI deployed on the Jetson companion, accessed by the operator via wired connection during pre-flight. Used for: drawing route + operational sector, triggering tile fetch from the Suite Satellite Service, running Provisioning Tool steps, walking through camera intrinsics calibration. Requires pre-flight internet. (decision: 2026-04-27)
+
+## L
+
+- **LiteSAM** — purpose-built satellite↔aerial AVL matcher (S58, MDPI Oct 2025). Used in this build in three NON-inline roles: (a) re-localization fallback (cold start, σ_xy > 50 m, sharp turn after VO loss); (b) offline validation oracle; (c) distillation teacher for a future inline student model. NOT inline due to ~1.5–2 s/pair latency on Orin Nano Super. (source: solution.md §Component 3; M-24)
+
+## M
+
+- **Mahalanobis gate** — outlier rejection mechanism in Component 5. Drops fix candidates whose innovation w.r.t. the cuVSLAM relative-pose prior exceeds a threshold derived from AC-NEW-4. NOT a state-propagating filter — pure gate. (source: solution.md §Component 5; M-26)
+- **MAVLink2 signing** — per-link cryptographic signing on every companion ↔ FC link. **Mandatory in v1**. Per-airframe signing key written to FC FRAM via `MAV_CMD_SETUP_SIGNING` during Provisioning Tool bootstrap. USB connections bypass signing — bench-only. (source: solution.md §Component 6; R10)
+- **MAVROS** — ROS 2 ↔ MAVLink bridge node. Owned by Component 9. Subscribes to FC `RAW_IMU` / `SCALED_IMU` / `ATTITUDE`; publishes our `GPS_INPUT`. (source: solution.md §Component 9)
+- **MAVSDK** — high-level MAVLink library. Used in this build for general telemetry (sysid=10) only. Does NOT inject `GPS_INPUT` (no native API; that goes through pymavlink). (source: AC-4.3, restrictions.md §Sensors)
+- **MBTiles** — SQLite-backed tile-storage container format. **One file** for the whole tile cache (not thousands of filesystem entries). Used by Component 1 for the persistent tile cache; opened with WAL + connection pool + transaction batching. (source: solution.md §Component 1)
+- **Mission YAML** — per-mission configuration written by Jetson UI alongside the tile fetch. Contains operational area polygon, sector classes (active-conflict / stable rear), mission ID. One of three configuration scopes. (decision: 2026-04-27)
+
+## N
+
+- **Nadir** — straight-down direction from the airframe. Nav cam is fixed nadir-pointing. (source: restrictions.md §Cameras)
+- **Nav cam / Navigation camera** — fixed downward-pointing 20 MP APS-C camera (ADTi 20MP 20L V1). Consumed by this build for position estimation. NOT operator-controllable, NOT gimbaled. Distinct from the AI camera. (source: restrictions.md §Cameras)
+
+## O
+
+- **ODOMETRY** — alternate MAVLink ExtNav channel (richer covariance, native yaw error, quality field). **Intentionally disabled in v1** (Option A in M-30) due to ArduPilot EKF3 double-fusion bugs (#30076 / #32506). Re-enables in v1.1 once F-T9 SITL confirms PR #30080-class clean source-switching. (source: AC-4.3 v1 scope clause)
+- **Operational area** — the pre-cached union of sector + transit corridor for a mission. Up to ~400 km² total. Cache is persistent across flights. (source: restrictions.md §UAV & Flight)
+- **Operator** — the UAV pilot operating the mission. Responsible for: pre-flight tile fetch via Jetson UI, monitoring via QGC during flight, optional re-localization hints via QGC. Single human role; no co-operator distinction in v1. (source: restrictions.md, AC-6.2)
+- **Orthority** — Python library used by Component 1b for per-frame orthorectification. Frame-camera model + GeoTIFF DEM. Pip-installable, MIT-class license. Documented fall-back: `cv2.warpPerspective + bilinear DEM` if F-T14 latency budget (≤50 ms/frame) is exceeded. (source: solution.md §Component 1b; M-27)
+- **Orthorectification / Ortho** — projecting a nav-cam frame onto the basemap projection (EPSG:3857 z=19) using the camera model + per-sector DEM. Output is a basemap-aligned tile. (source: solution.md §Component 1b)
+
+## P
+
+- **PnP** — Perspective-n-Point, the geometric step that turns matched 2D-3D correspondences (cross-view matcher output) into an absolute pose + covariance. (source: solution.md §Component 3)
+- **Provisioning Tool** — Jetson-side `provision-fc.py` workflow that runs once at client setup. Does FC parameter pinning (`GPS1_TYPE=14`, `EK3_SRC1_*`, `SERIAL2_*`), MAVLink2 signing-key bootstrap, and a smoke-test (`RAW_IMU` rate + `GPS_INPUT` round-trip). Produces the per-airframe signed manifest. Component 12. (decision: 2026-04-27)
+- **pymavlink** — low-level MAVLink Python library. Used in this build EXCLUSIVELY for `GPS_INPUT` injection (sysid=11). MAVSDK has no native `GPS_INPUT` API. (source: AC-4.3, M-6)
+
+## Q
+
+- **QGC / QGroundControl** — the supported GCS software. Operator-side application running on a laptop or tablet, communicating with the FC via MAVLink. Receives a 1–2 Hz downsampled telemetry summary from the companion through the FC. NOT running on the companion. (source: AC-6.1, restrictions.md §Sensors; decision: 2026-04-27)
+
+## R
+
+- **Re-localization (re-loc)** — the act of recovering an absolute pose after VO/cuVSLAM tracking loss. Triggers: cold start (AC-NEW-1), sharp turn (AC-3.2), disconnected segment (AC-3.3), σ_xy > 50 m, VO failure for ≥2 frames. VPR + LiteSAM are the re-loc workhorses; SP+LG inline matcher is invoked after VPR narrows the candidate set. (source: AC-3.3, AC-8.6, solution.md §Component 3)
+- **Relative pose** — frame-to-frame pose increment produced by cuVSLAM. Distinguished from *absolute pose* (matcher + PnP). (source: solution.md §Component 4)
+- **ROS 2 Humble** — middleware platform on JetPack 6 / Ubuntu 22.04. v1 orchestration target (Q6 → A, locked 2026-04-26). Replaces the draft01 "single Python asyncio process". (source: solution.md §Component 9; M-29)
+
+## S
+
+- **Sector** — operational sub-area within the operational area. Two sub-types matter: *active-conflict* (stricter freshness, K=20 VPR top-K) and *stable rear* (relaxed freshness, K=5). Plus a separate terrain classification (`flat` / `moderate` / `rugged`) used by Component 1b. (source: AC-8.2, AC-NEW-6, solution.md §Component 1b)
+- **σ_xy / sigma_xy** — 2D position uncertainty: the 95% covariance ellipse semi-major axis in meters. Carried on every emitted fix; gates Component 1b tile-generation eligibility (≤5 m hard, ≤3 m for full-quality writes). (source: AC-1.4, AC-NEW-7)
+- **SITL** — Software-In-The-Loop ArduPilot simulator. Used by F-T9 to validate the full MAVLink loop (GPS_INPUT injection, source switching, MAVLink2 signing). (source: solution.md §F-T9)
+- **Source label** — categorical tag on every emitted fix: `satellite_anchored` (matcher+PnP succeeded), `vo_extrapolated` (cuVSLAM continuation from last anchor), `dead_reckoned` (no recent visual fix). Drives FC's confidence treatment. (source: AC-1.4)
+- **Spoofing-promotion** — the system action of promoting our estimate to FC primary GPS source when real GPS is detected as spoofed/lost. Latency target <3 s (AC-NEW-2). Driven by Component 7 watching `GPS_RAW_INT`, `EKF_STATUS_REPORT`, `SYS_STATUS`. (source: AC-NEW-2)
+- **Stable rear sector** — operational sub-area where major scene change is not expected. Relaxed freshness budget (<12 months); smaller VPR top-K (K=5). Opposite of active-conflict sector. (source: AC-8.2)
+- **Suite Service ingest** — server-side process at the Suite Satellite Service that consumes onboard-uploaded tiles via the candidate pool and applies 2-flight voting before promoting them to trusted basemap. Out of scope for this build (lives in `../satellite-service/`). (source: AC-NEW-7)
+- **sysid (system ID)** — MAVLink endpoint identifier. Companion uses two: **10** (MAVSDK telemetry) and **11** (pymavlink GPS_INPUT). FC uses its native `SYSID_THISMAV`. Routing handled by ArduPilot's native MAVLink routing — no `mavlink-router` daemon. (source: solution.md §Component 6; M-31)
+
+## T
+
+- **TartanAir V2** — synthetic dataset (Q4 → A, locked) used as early-stage matcher and VO baseline before real flight data is available. (source: solution.md, Q4)
+- **TensorRT (TRT)** — NVIDIA's GPU inference compiler. All heavy NN inference in this build runs as TRT engines (FP16 default; INT8 where validated). Engines built at install time, not at first run, to meet AC-NEW-1 cold-start budget. (source: solution.md §Component 9, AC-NEW-1)
+- **Tile** — slippy-XYZ z=19, 512×512 px, ~60 cm/px GSD. The unit of basemap **storage** in the tile cache. Decoupled from the VPR chunk (the unit of retrieval). Carries sidecar metadata: `parent_pose_sigma_xy`, `terrain_class`, `trust_level`, `capture_date`. (decision: 2026-04-27, supersedes z=20 in restrictions.md / solution.md)
+- **Tile cache** — the persistent MBTiles store on the companion NVMe at `/var/azaion/tile-cache/` (path TBD with Suite Service contract). Read+write during flight. ~700 MB for a 400 km² operational area at z=19. Persistent across flights — not redownloaded. (source: restrictions.md §Satellite Imagery; decision: 2026-04-27)
+- **Tile-cache folder** — the **boundary contract** between this build and the Suite Satellite Service. Pre-flight: tiles arrive in this folder via the Service's fetch flow (out-of-scope mechanism). In-flight: this build reads + writes to this folder. Post-flight: this build's uploader pushes new tiles from this folder to the Service candidate pool. The folder layout / file naming is owned by `../satellite-service/`. (decision: 2026-04-27)
+- **Trust level** — sidecar metadata on each onboard-generated tile: `candidate` (default; σ_xy ≤ 5 m), `soft` (σ_xy ∈ (3, 5] m), or trusted-basemap (post Service-side 2-flight voting). Determines whether downstream flights match against it. (source: AC-NEW-7)
+- **TTFF** — Time-to-First-Fix on cold start. Budget: <30 s from companion-computer boot to first valid `GPS_INPUT` (AC-NEW-1). Drives TRT engine pre-build, FAISS index pre-load, mmap-warm tile cache. (source: AC-NEW-1)
+
+## V
+
+- **Visual fix** — see *absolute pose*.
+- **VO** — Visual Odometry. Frame-to-frame relative pose. In v1 supplied by cuVSLAM in monocular+IMU mode. Distinguished from cross-view matching against the satellite basemap. (source: solution.md §Component 4)
+- **VPR** — Visual Place Recognition. Global descriptor retrieval (DINOv2 SALAD/BoQ; AnyLoc fallback) over a FAISS IVF index of per-chunk descriptors. Narrows the basemap to a top-K candidate-chunk shortlist on re-localization triggers. **Conditionally invoked**, not per-frame. (source: solution.md §Component 2; AC-8.6)
+- **VPR chunk** — ground-footprint-sized (~600–800 m at 1 km AGL, 40–50 % overlap) retrieval unit derived from the z=19 storage tile cache. **Decoupled from the storage tile** — must NOT be conflated. Multi-scale: fine-scale (z=19-derived) + coarse (z=17/z=18 effective scale) for change-robust retrieval in active-conflict sectors. (source: AC-8.6, restrictions.md §Satellite Imagery)
+
+## W
+
+- **WGS84** — coordinate system used for all output GPS coordinates. Matches `GPS_INPUT` spec. (source: AC-6.3)
+
+## Z
+
+- **z=19 / Storage tile zoom** — slippy-XYZ zoom level 19, ~60 cm/px GSD, 512×512 tiles. The pinned basemap storage zoom for v1. Scale ratio to nav cam at 1 km AGL is **5×** (above the 4× safety threshold quoted in solution.md draft03 §Component 1) — accepted as v1 default with documented fall-back to z=20 if matcher bench-off shows AC-2.2 (MRE <2.5 px cross-domain) failure. ~700 MB cache for a 400 km² operational area. (decision: 2026-04-27, supersedes restrictions.md §Satellite Imagery z=20 clause)
@@ -0,0 +1,659 @@
+# GPS-Denied Onboard System - System Flows
+
+## Flow Inventory
+
+| # | Flow Name | Trigger | Primary Components | Criticality |
+|---|-----------|---------|--------------------|-------------|
+| F1 | Airframe Provisioning & FC Bootstrap | Client setup or airframe maintenance | C-12, C-6, FC, Jetson UI | High |
+| F2 | Pre-Flight Mission Setup & Tile Fetch | Operator prepares mission on Jetson UI | Jetson UI, C-1, C-2, Suite Satellite Service | High |
+| F3 | In-Flight VO-First Localization | Nav-cam frame arrives | C-4, C-2, C-3, C-5, C-6, C-10, C-11 | High |
+| F4 | Re-Localization Recovery | Cold start, VO loss, sharp turn, disconnected segment, or sigma_xy > 50 m | C-2, C-3, C-5, C-7 | High |
+| F5 | In-Flight Tile Generation & Local Write | Eligible satellite-anchored frame | C-1b, C-1, C-10 | Medium |
+| F6 | Post-Flight Candidate Tile Upload | Aircraft lands and network is available | C-1, Suite Satellite Service | Medium |
+| F7 | Cold Start, Spoofing Promotion & Failsafe | Boot, GPS-denial signal, or output gap | C-6, C-7, FC, QGC | High |
+| F8 | AI-Camera Object Localization | AI detection system requests object coordinates | C-8, C-5, MAVROS/FC telemetry | Medium |
+
+## Flow Dependencies
+
+| Flow | Depends On | Shares Data With |
+|------|------------|------------------|
+| F1 | Physical wiring and FC access | F2 and F3 via signed airframe manifest and FC parameter pins |
+| F2 | F1 for manifest and signing; Suite Service connectivity | F3/F4/F5 via tile cache, mission YAML, VPR index |
+| F3 | F2 for sufficient local cache; F1 for FC integration | F4 via re-loc triggers; F5 via satellite-anchored pose; F7 via output health |
+| F4 | F2 cache and descriptors; F3 trigger context | F3 via recovered anchor fix; F7 via failure state |
+| F5 | F3 satellite-anchored pose and tile cache | F6 via candidate tiles; C-10 via tile-generation events |
+| F6 | F5 candidate tiles and post-flight network | Future F2 through Suite Service trusted-basemap refresh |
+| F7 | F1 signing and FC params; F3 output health | F3 via source mode; QGC via status messages |
+| F8 | F3 current pose and FC altitude/attitude | FDR via object-localization audit records |
+
+---
+
+## Flow F1: Airframe Provisioning & FC Bootstrap
+
+### Description
+
+At client setup, the operator or field engineer uses the Jetson UI and Provisioning Tool to make one airframe safe and repeatable for GPS-Denied operation. The output is a signed airframe manifest and a verified FC link.
+
+### Preconditions
+
+- Jetson, FC, nav camera, and harness are physically installed.
+- FC is reachable over the intended companion link.
+- The operator can perform manual physical wiring checks and standard QGC compass/accelerometer calibration.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Operator
+    participant JetsonUI as Jetson UI
+    participant Provisioner as C-12 Provisioning Tool
+    participant FC as ArduPilot FC
+    participant Manifest as Airframe Manifest
+
+    Operator->>JetsonUI: Start airframe provisioning
+    JetsonUI->>Provisioner: Launch provision-fc.py
+    Provisioner->>FC: Detect FC and read firmware/sysid
+    FC-->>Provisioner: FC identity and current parameters
+    Provisioner->>FC: Pin SERIAL2_BAUD/SERIAL2_PROTOCOL
+    Provisioner->>FC: Pin GPS1_TYPE=14 and EK3_SRC1_*
+    Provisioner->>FC: Bootstrap MAVLink2 signing key
+    Provisioner->>FC: Smoke-test RAW_IMU rate and GPS_INPUT round-trip
+    Provisioner->>JetsonUI: Request checkerboard intrinsics calibration
+    Operator->>JetsonUI: Complete guided calibration
+    Provisioner->>Manifest: Write signed airframe manifest
+    JetsonUI-->>Operator: Provisioning complete
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    start([Start provisioning]) --> detectFc[Detect FC]
+    detectFc --> fcReachable{FC reachable?}
+    fcReachable -->|No| stopRepair[Stop for wiring/link repair]
+    fcReachable -->|Yes| pinParams[Pin serial, GPS_INPUT, EK3 params]
+    pinParams --> signing[Install MAVLink2 signing key]
+    signing --> smoke[RAW_IMU + GPS_INPUT smoke test]
+    smoke --> smokeOk{Smoke test passes?}
+    smokeOk -->|No| stopDebug[Stop with failed check]
+    smokeOk -->|Yes| calibrate[Guided nav-cam intrinsics calibration]
+    calibrate --> manifest[Write signed airframe manifest]
+    manifest --> done([Airframe ready])
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | FC | Provisioning Tool | Firmware, sysid, current params | MAVLink |
+| 2 | Provisioning Tool | FC | Serial/GPS/EKF params, signing key | MAVLink commands |
+| 3 | Jetson UI | Provisioning Tool | Camera calibration observations | Guided calibration payload |
+| 4 | Provisioning Tool | Runtime | Airframe manifest | Signed file |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| FC not detected | FC link check | No heartbeat | Stop and repair wiring/link settings. |
+| Signing bootstrap fails | Signing setup | FC rejects command or verification | Stop; do not run flight stack unsigned. |
+| GPS_INPUT round-trip fails | Smoke test | FC does not receive/accept test frame | Stop and debug params/sysids/signing. |
+| Intrinsics calibration incomplete | Jetson UI | Missing calibration artifact | Keep airframe unprovisioned. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Provisioning duration | Human-paced | Safety and correctness matter more than speed. |
+| Smoke-test result | Deterministic pass/fail | Must run before production flight. |
+
+---
+
+## Flow F2: Pre-Flight Mission Setup & Tile Fetch
+
+### Description
+
+Before takeoff, the operator connects to the Jetson UI, defines the route and sector, requests tiles from the Suite Satellite Service, and writes mission YAML next to the local tile cache. This is the only time the aircraft needs Service connectivity for the upcoming mission.
+
+### Preconditions
+
+- Airframe provisioning is complete.
+- Jetson has pre-flight internet.
+- Suite Satellite Service is reachable and authorized.
+- The operator knows the intended operational area and sector classes.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Operator
+    participant JetsonUI as Jetson UI
+    participant Service as Suite Satellite Service
+    participant Cache as C-1 Tile Cache
+    participant VPR as C-2 VPR Index
+
+    Operator->>JetsonUI: Draw route, sector, and transit corridor
+    JetsonUI->>JetsonUI: Classify sectors and write mission YAML draft
+    JetsonUI->>Service: Request z=19 tiles for operational area
+    Service-->>JetsonUI: Tile package and metadata
+    JetsonUI->>Cache: Store MBTiles and sidecar metadata
+    Cache->>VPR: Build/update chunk descriptors and FAISS index
+    VPR-->>JetsonUI: Index ready
+    JetsonUI-->>Operator: Mission cache ready for flight
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    start([Operator opens Jetson UI]) --> draw[Draw route + sector]
+    draw --> classify[Set active-conflict/stable sector classes]
+    classify --> fetch[Request tiles from Suite Service]
+    fetch --> enoughTiles{Tiles meet coverage, freshness, resolution?}
+    enoughTiles -->|No| block[Block flight cache-ready status]
+    enoughTiles -->|Yes| store[Store z=19 MBTiles + sidecars]
+    store --> index[Build VPR chunks and descriptors]
+    index --> yaml[Write mission YAML]
+    yaml --> ready([Mission ready])
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | Operator | Jetson UI | Route, sector polygon, mission ID | UI form |
+| 2 | Jetson UI | Suite Service | Tile fetch request | HTTPS/API |
+| 3 | Suite Service | Tile Cache | Tiles and metadata | MBTiles/package contract |
+| 4 | Tile Cache | VPR Index | Chunks and descriptors | Local files / FAISS index |
+| 5 | Jetson UI | Runtime | Mission configuration | YAML |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| Service unavailable | Tile fetch | Request fails | Retry pre-flight; do not assume in-flight fetch. |
+| Tile freshness invalid | Cache validation | Capture date violates sector budget | Reject or mark down-confidence per AC-NEW-6. |
+| Cache incomplete | Coverage validation | Operational area gap | Block mission-ready status until resolved. |
+| Descriptor build fails | VPR index | Index missing or corrupt | Rebuild; block flight if unresolved. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Initial preload size | About 700 MB for 400 km2 at z=19 | Throughput-sensitive but pre-flight only. |
+| Runtime dependency | Zero Service calls in flight | All needed data must be local before takeoff. |
+
+---
+
+## Flow F3: In-Flight VO-First Localization
+
+### Description
+
+For each nav-camera frame, the runtime uses the cheap C-4 motion bridge to propagate pose from the last satellite anchor. Satellite retrieval and matching are not run on every frame; they are invoked on anchor cadence, covariance growth, VO-health triggers, sharp turns, cold start, or disconnected-segment recovery.
+
+### Preconditions
+
+- Mission YAML and tile cache are loaded.
+- Airframe manifest is valid.
+- Camera stream and FC telemetry are live.
+- TensorRT engines and descriptor indexes are warmed.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Cam as Nav Camera
+    participant FC as ArduPilot FC
+    participant VO as C-4 Nadir Motion Bridge
+    participant VPR as C-2 VPR
+    participant Matcher as C-3 Matcher/PnP
+    participant Output as C-5/C-11 Output Stage
+    participant Mav as C-6 MAVLink Injector
+    participant FDR as C-10 FDR
+
+    Cam->>VO: Frame
+    FC-->>VO: IMU, attitude, altitude
+    VO-->>Output: Relative motion + covariance
+    Output->>Output: Check anchor age, sigma_xy, drift budget, VO health
+    alt Anchor cadence or re-localization trigger
+        Output->>VPR: Request candidate chunks
+        VPR-->>Matcher: Top-K chunks
+        Cam->>Matcher: Current frame
+        Matcher-->>Output: Absolute pose + covariance + inliers
+    end
+    Output->>Output: Mahalanobis gate and covariance calibration
+    Output->>Mav: GPS_INPUT payload
+    Mav->>FC: Signed GPS_INPUT
+    Output->>FDR: Source label, gates, covariance, decision
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    frame([Frame arrives]) --> vo[Update nadir motion bridge]
+    vo --> trigger{Anchor cadence or re-loc trigger?}
+    trigger -->|No| extrapolate[Produce vo_extrapolated candidate]
+    trigger -->|Yes| retrieve[VPR top-K candidate chunks]
+    retrieve --> match[Cross-view match + PnP]
+    match --> gate[Mahalanobis gate]
+    extrapolate --> gate
+    gate --> valid{Valid confidence?}
+    valid -->|Yes| emit[Emit signed GPS_INPUT]
+    valid -->|No| dead[Mark dead_reckoned/no fix]
+    emit --> record[FDR decision record]
+    dead --> record
+    record --> next([Next frame])
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | Nav camera | Motion bridge / matcher | Current frame | ROS 2 image |
+| 2 | FC | Motion bridge / output | IMU, attitude, altitude, GPS health | MAVLink -> ROS 2 |
+| 3 | Tile cache | VPR / matcher | Candidate chunks and descriptors | Local cache/index |
+| 4 | Matcher / VO | Output stage | Pose hypotheses and covariance | ROS 2 messages |
+| 5 | Output stage | FC | WGS84 fix and accuracy | MAVLink GPS_INPUT |
+| 6 | Output stage | FDR | Decisions and gates | FlatBuffers record |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| Frame dropped under load | Camera/runtime | Queue overflow or skip policy | Drop up to allowed budget; keep latest-frame processing. |
+| VO unhealthy | Motion bridge | Low overlap, blur, weak features, inconsistent IMU/attitude, or covariance growth | Trigger F4 re-localization. |
+| Matcher outlier | Output gate | Mahalanobis distance exceeds threshold | Reject, do not down-weight into a false anchor. |
+| GPS_INPUT rejected | FC | Missing acceptance/round-trip evidence | Raise health alert and F7 failsafe path. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Camera-to-FC output | <400 ms p95 | Steady-state path is VO-first; satellite matching is cadence/triggered correction, not every-frame work. |
+| Frame rate | 3 fps input; up to about 10% drops allowed under load | Output must not batch. |
+| Memory | <8 GB shared | Includes TensorRT engines and ROS 2 overhead. |
+
+---
+
+## Flow F4: Re-Localization Recovery
+
+### Description
+
+When the system lacks a trustworthy recent anchor, it expands retrieval and matching to recover an absolute pose. This path handles cold start, sharp turns, disconnected segments, sigma_xy growth, and VO failure.
+
+### Preconditions
+
+- Tile cache and VPR index cover the current operational area.
+- The runtime has an initial or predicted position from FC/VO/dead reckoning.
+- LiteSAM and inline matcher engines are installed and warmed according to deployment mode.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Output as C-5 Output Stage
+    participant VPR as C-2 VPR
+    participant Matcher as C-3 Inline Matcher
+    participant LiteSAM as LiteSAM Fallback
+    participant FDR as C-10 FDR
+
+    Output->>VPR: Re-loc request with predicted position and sector class
+    VPR-->>Output: Top-K chunks based on sector and sigma_xy
+    Output->>Matcher: Try SP+LG/GIM-LG over candidates
+    alt Inline match succeeds
+        Matcher-->>Output: Absolute pose + covariance
+    else Inline match fails and fallback allowed
+        Output->>LiteSAM: Rare fallback match request
+        LiteSAM-->>Output: Absolute pose candidate
+    end
+    Output->>Output: Gate against VO/dead-reckoned prior
+    Output->>FDR: Re-loc attempt and result
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    trigger([Re-loc trigger]) --> chooseK[Choose K by sector and sigma_xy]
+    chooseK --> vpr[VPR retrieval]
+    vpr --> inline[Run inline matcher over candidates]
+    inline --> inlineOk{Good inliers and MRE?}
+    inlineOk -->|Yes| pnp[PnP absolute pose]
+    inlineOk -->|No| fallbackAllowed{LiteSAM fallback allowed?}
+    fallbackAllowed -->|Yes| litesam[Run LiteSAM rare fallback]
+    fallbackAllowed -->|No| noFix[No anchor this frame]
+    litesam --> pnp
+    pnp --> gate[Mahalanobis gate]
+    gate --> recovered{Gate passes?}
+    recovered -->|Yes| anchor[Emit satellite_anchored fix]
+    recovered -->|No| noFix
+    noFix --> escalate[Continue VO/dead reckoning and update failure counters]
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | Output stage | VPR | Predicted position, sector type, sigma_xy | Re-loc request |
+| 2 | VPR | Matcher | Candidate chunks | Chunk list |
+| 3 | Matcher/LiteSAM | Output stage | Correspondences, pose, covariance | Pose candidate |
+| 4 | Output stage | FDR | Attempt metadata | FlatBuffers record |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| No candidate chunk | VPR | Empty result | Expand window to K=50; if still empty, no anchor. |
+| Stale tile match | Matcher/output | Tile freshness metadata invalid | Reject or downgrade; never emit `satellite_anchored` from stale tile. |
+| LiteSAM too slow | Fallback | Exceeds rare-path budget | Record timeout; continue dead reckoning/failsafe logic. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Inline re-loc pair latency | <=200 ms per candidate path target | Bench-off decides exact settings. |
+| LiteSAM fallback | <=2 s rare-path budget | Not part of steady-state p95. |
+| Cold-start TTFF | <30 s p95 | F7 includes full boot budget. |
+
+---
+
+## Flow F5: In-Flight Tile Generation & Local Write
+
+### Description
+
+When a frame has a high-confidence satellite-anchored pose, the system may orthorectify it into the z=19 basemap projection and write a candidate tile into the local cache with sidecar metadata.
+
+### Preconditions
+
+- Current source label is `satellite_anchored`.
+- Parent pose sigma_xy <=5 m for hard write eligibility.
+- Terrain class is flat or moderate, not rugged.
+- DEM and camera intrinsics are available.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Output as C-5 Output Stage
+    participant Ortho as C-1b Ortho Generator
+    participant Cache as C-1 Tile Cache
+    participant FDR as C-10 FDR
+
+    Output->>Ortho: Eligible frame + pose + covariance
+    Ortho->>Ortho: Orthorectify with Orthority + DEM
+    Ortho->>Ortho: Score quality and deduplicate
+    Ortho->>Cache: Transactional candidate/soft tile write
+    Cache-->>Ortho: Write result
+    Ortho->>FDR: Tile-generation event and sidecar metadata
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    candidate([Frame candidate]) --> eligible{source=satellite_anchored and sigma<=5m?}
+    eligible -->|No| skip[Skip tile generation]
+    eligible -->|Yes| terrain{Terrain allowed?}
+    terrain -->|No| skip
+    terrain -->|Yes| ortho[Orthorectify with DEM + camera model]
+    ortho --> quality{Quality and dedup pass?}
+    quality -->|No| thumb[Record failure thumbnail <=0.1 Hz]
+    quality -->|Yes| write[Write MBTiles transaction + sidecar]
+    write --> record[FDR tile-generation event]
+    thumb --> record
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | Output stage | Ortho generator | Frame, pose, covariance, source label | ROS 2/local message |
+| 2 | Tile cache | Ortho generator | Existing tile metadata | SQLite/sidecar |
+| 3 | Ortho generator | Tile cache | Candidate/soft tile and metadata | MBTiles transaction |
+| 4 | Ortho generator | FDR | Quality, write decision, failure thumbnail reference | FlatBuffers record |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| Orthority latency too high | F-T14/runtime metric | >50 ms/frame budget | Switch implementation to OpenCV + bilinear DEM fallback after validation. |
+| Pose covariance too high | Eligibility | sigma_xy >5 m | Skip write; do not poison cache. |
+| Service tile overwrite risk | Dedup/write | Existing trusted tile within freshness budget | Do not overwrite service-source tile. |
+| Cache write failure | SQLite/MBTiles | Transaction fails | Log event; keep localization running. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Orthorectification latency | <=50 ms/frame budget | Measured on Orin Nano Super. |
+| Misaligned tile probability | >30 m <1%; >100 m <0.1% per flight | AC-NEW-7 Monte Carlo gate. |
+
+---
+
+## Flow F6: Post-Flight Candidate Tile Upload
+
+### Description
+
+After landing, candidate tiles generated during flight are uploaded from the local cache boundary to the Suite Satellite Service candidate pool. The Service owns voting and trusted-basemap promotion.
+
+### Preconditions
+
+- Aircraft has landed and post-flight network is available.
+- Candidate tiles and sidecars are present.
+- Suite Service credentials are available in the approved ground context.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Operator
+    participant Uploader as Post-Flight Uploader
+    participant Cache as C-1 Tile Cache
+    participant Service as Suite Satellite Service
+    participant FDR as C-10 FDR
+
+    Operator->>Uploader: Start post-flight sync
+    Uploader->>Cache: Enumerate candidate/soft tiles
+    Cache-->>Uploader: Tile payloads and sidecars
+    Uploader->>Service: Upload candidate pool batch
+    Service-->>Uploader: Accepted/rejected result
+    Uploader->>FDR: Record upload summary
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    start([Post-flight sync]) --> enumerate[Enumerate candidate tiles]
+    enumerate --> any{Any candidates?}
+    any -->|No| done([Nothing to upload])
+    any -->|Yes| upload[Upload batch to Suite Service candidate pool]
+    upload --> accepted{Accepted?}
+    accepted -->|Yes| mark[Mark uploaded locally]
+    accepted -->|No| retry[Keep pending with failure reason]
+    mark --> done
+    retry --> done
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | Tile cache | Uploader | Candidate tiles and sidecars | Local files/SQLite |
+| 2 | Uploader | Suite Service | Candidate upload batch | Service API contract |
+| 3 | Suite Service | Uploader | Accepted/rejected records | API response |
+| 4 | Uploader | FDR/log | Upload summary | FlatBuffers/log record |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| Network unavailable | Upload | Connection failure | Keep candidates pending; retry on next post-flight sync. |
+| Service rejects tile | Service ingest | Rejection response | Record reason; do not mark uploaded. |
+| Contract mismatch | Upload payload | Schema/API error | Block upload and raise integration issue with `../satellite-service/`. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Upload timing | Post-flight, not flight-critical | Can retry without affecting flight safety. |
+| Promotion | Service-owned | This build never marks tiles trusted. |
+
+---
+
+## Flow F7: Cold Start, Spoofing Promotion & Failsafe
+
+### Description
+
+This flow covers safety state changes around boot, GPS denial/spoofing, promotion to primary GPS substitute, and output failure. It keeps FC behavior explicit and makes QGC telemetry a status surface, not a control-plane dependency.
+
+### Preconditions
+
+- FC is configured by F1.
+- Runtime has access to FC GPS/EKF health telemetry.
+- Mission cache is loaded for cold-start matching.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Runtime as GPS-Denied Runtime
+    participant FC as ArduPilot FC
+    participant Reloc as F4 Re-Localization
+    participant QGC as QGroundControl
+    participant FDR as C-10 FDR
+
+    Runtime->>FC: Connect with signed MAVLink
+    FC-->>Runtime: Last EKF position + GPS/EKF health
+    Runtime->>Reloc: Cold-start first fix
+    Reloc-->>Runtime: Valid anchor or no-fix
+    alt GPS denial/spoofing detected
+        FC-->>Runtime: GPS health degraded
+        Runtime->>FC: Promote signed GPS_INPUT within <3 s
+        Runtime->>QGC: STATUSTEXT promotion status via FC
+    end
+    alt No output >3 s
+        FC->>FC: Fall back to IMU-only dead reckoning
+        Runtime->>QGC: Degraded/failsafe status via FC
+    end
+    Runtime->>FDR: Boot, promotion, failsafe events
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    boot([Runtime boot]) --> connect[Signed MAVLink connect]
+    connect --> init[Read last FC EKF position]
+    init --> firstFix[Run cold-start re-localization]
+    firstFix --> ttff{First fix <30s?}
+    ttff -->|Yes| normal[Normal GPS_INPUT output]
+    ttff -->|No| degraded[Degraded status and continued re-loc]
+    normal --> gpsHealth{FC reports GPS denial/spoofing?}
+    gpsHealth -->|Yes| promote[Promote our GPS_INPUT primary within <3s]
+    gpsHealth -->|No| monitor[Monitor output age]
+    promote --> monitor
+    degraded --> monitor
+    monitor --> gap{No position >3s?}
+    gap -->|Yes| failsafe[FC IMU-only dead reckoning + log]
+    gap -->|No| normal
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | FC | Runtime | EKF position, GPS health, status | MAVLink |
+| 2 | Runtime | FC | Signed GPS_INPUT | MAVLink |
+| 3 | Runtime | QGC | Status summary / STATUSTEXT via FC | MAVLink |
+| 4 | Runtime | FDR | Boot, promotion, failsafe events | FlatBuffers record |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| Cold-start no fix | First re-loc | TTFF budget exceeded | Continue re-loc, report degraded, FC continues own fallback behavior. |
+| Spoofing not promoted | Health monitor | Promotion >3 s | Fails AC-NEW-2; record and investigate. |
+| Output gap | Runtime output | >3 s without fix | FC falls back to IMU-only dead reckoning. |
+| Signing failure | MAVLink link | FC rejects frames | Do not bypass signing in flight; report unsafe state. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Cold-start first fix | <30 s p95 | From companion boot to first valid GPS_INPUT. |
+| Spoofing promotion | <3 s p95 | From FC GPS-denial signal. |
+| Failsafe output gap | >3 s | FC fallback threshold. |
+
+---
+
+## Flow F8: AI-Camera Object Localization
+
+### Description
+
+Other onboard AI systems can request the coordinates of an object detected by the AI camera. The system projects the object using current GPS-Denied position, altitude, AI-camera gimbal angle, zoom, and level-flight assumptions.
+
+### Preconditions
+
+- Current GPS-Denied position estimate is available with confidence.
+- AI-camera gimbal angle and zoom are available.
+- Flight altitude is available.
+- Request is scoped to level flight accuracy unless the caller accepts the published maneuvering error bound.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Detection System
+    participant Obj as C-8 Object Localization
+    participant Pose as C-5 Current Pose
+    participant FC as FC Telemetry
+    participant FDR as C-10 FDR
+
+    AI->>Obj: Object pixel/box + camera metadata
+    Obj->>Pose: Request current GPS-Denied pose
+    Pose-->>Obj: WGS84 position + sigma_xy + source label
+    FC-->>Obj: Altitude and attitude
+    Obj->>Obj: Project object ray to ground plane
+    Obj-->>AI: Object WGS84 coordinate + error bound
+    Obj->>FDR: Object localization audit record
+```
+
+### Flowchart
+
+```mermaid
+flowchart TD
+    request([AI object request]) --> pose[Read current GPS-Denied pose]
+    pose --> poseOk{Pose acceptable?}
+    poseOk -->|No| reject[Return unavailable with reason]
+    poseOk -->|Yes| inputs[Read gimbal angle, zoom, altitude]
+    inputs --> level{Bank/pitch <5 deg?}
+    level -->|Yes| project[Project object to ground plane]
+    level -->|No| bound[Compute maneuvering error bound]
+    bound --> project
+    project --> result[Return WGS84 + confidence/error bound]
+```
+
+### Data Flow
+
+| Step | From | To | Data | Format |
+|------|------|----|------|--------|
+| 1 | AI system | Object localization | Object detection and camera metadata | Local API/topic |
+| 2 | Output stage | Object localization | Current pose and confidence | Runtime state/topic |
+| 3 | FC | Object localization | Altitude and attitude | MAVLink/ROS 2 |
+| 4 | Object localization | AI system | Object WGS84 and error bound | Response DTO/message |
+
+### Error Scenarios
+
+| Error | Where | Detection | Recovery |
+|-------|-------|-----------|----------|
+| Pose unavailable | C-5 current state | No current estimate or high sigma_xy | Return unavailable; do not invent coordinates. |
+| Maneuvering flight | FC attitude | bank/pitch >=5 degrees | Publish bounded error, lower confidence. |
+| Missing gimbal/zoom | AI-camera metadata | Required field absent | Reject request with explicit missing input. |
+
+### Performance Expectations
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Response latency | Near-real-time local call | Not on FC safety-critical path. |
+| Accuracy | Consistent with frame-center accuracy in level flight | AC-7.1/AC-7.2 scoped behavior. |
@@ -6,9 +6,25 @@ step: 3
 name: Plan
 status: in_progress
 sub_step:
-  phase: 5
-  name: plan-step-1-complete
-  detail: "Plan Step 1 (test-spec sub-skill) COMPLETE. Phase 1 (input-data analysis) DONE earlier; Phase 2 (test scenarios, 8 artifacts) DONE; Phase 3 HARD GATE PASSED (100% spec-level coverage, 0 truly-missing items, 0 removed tests, defer-don't-remove per Phase 1 D4); Hardware Assessment DONE — `## Test Execution` section appended to environment.md classifying project as hardware-dependent and recording the Mode-C (both: Docker for T1/T2/T3 + bench-local for T4 + field for T5) per-tier split decision; Phase 4 (runner-scripts) SKIPPED per skill rule (planning context — script creation deferred to Decompose as tasks). Plan Step 1 user-level BLOCKING gate (test coverage confirmation) was satisfied by the Phase 2 → Phase 3 confirmation earlier in this session. Next: Plan Step 2 (Solution Analysis), opening with BLOCKING Phase 2a.0 (Glossary + Architecture Vision)."
+  phase: 7
+  name: phase-2a-architecture
+  detail: |
+    Phase 2a.0 COMPLETE — _docs/02_document/glossary.md written and confirmed by
+    user (2026-04-27). User picked option A on the condensed-view review.
+
+    Phase 2a architecture docs written:
+      - _docs/02_document/architecture.md
+      - _docs/02_document/system-flows.md
+
+    BLOCKING GATE: awaiting user confirmation of the Phase 2a architecture
+    summary. On A, advance sub_step to:
+      phase: 8
+      name: phase-2b-data-model
+      detail: "Phase 2a confirmed; proceed to data_model.md."
+
+    If the user requests edits, update the two Phase 2a files and re-present the
+    architecture summary before advancing. Do not re-ask the already-locked
+    Q1-Q6 / F1 / F2 / F3 decisions unless the user explicitly reopens them.
 retry_count: 0
 cycle: 1
 tracker: jira