docs: remove archived planning documents

docs/01-docs-index.md

@@ -18,15 +18,6 @@ Read in this order if you want to understand and run the current project:
 
 - [11-overview-demo-video-transcript.md](11-overview-demo-video-transcript.md)
 
-## Planning / Historical Design Notes
-
-These files are useful context, but they are not the source of truth for current runtime commands:
-
-- [90-archive-implementation-plan.md](90-archive-implementation-plan.md)
-- [91-archive-coach-analysis-implementation-plan.md](91-archive-coach-analysis-implementation-plan.md)
-- [92-archive-coach-model-data-plan.md](92-archive-coach-model-data-plan.md)
-- [99-archive-pozify-project-documentation.md](99-archive-pozify-project-documentation.md)
-
 ## Notes
 
 - Current coach-summary cloud runtime default: `Qwen/Qwen3-14B`

docs/90-archive-implementation-plan.md

@@ -1,128 +0,0 @@
-# Pozify Implementation Plan
-
-Status: historical implementation plan.
-
-Use [../README.md](../README.md) and [01-docs-index.md](01-docs-index.md) for the current runtime
-workflow and operational commands.
-
-This plan breaks Pozify into implementation workstreams that can be developed independently while preserving the current JSON data contracts.
-
-## Phase 1: Foundation And Contracts
-
-Goal: make the mocked pipeline production-shaped before replacing mock logic.
-
-Deliverables:
-
-- Stable JSON contracts in `src/pozify/contracts.py`.
-- Artifact persistence under `runs/<run_id>/`.
-- Contract validation and unit tests.
-- Clear step boundaries for replacing mock implementations.
-- Seed knowledge card structure.
-
-## Phase 2: Video Intake And Quality Gate
-
-Goal: accept user videos, extract reliable metadata, and reject videos that cannot be analyzed safely.
-
-Deliverables:
-
-- OpenCV-backed video metadata extraction.
-- Duration, FPS, brightness, blur, and basic frame-count checks.
-- Pose-quality-aware analysis gate.
-- User-facing quality warnings.
-- Capture guidance for failed videos.
-
-## Phase 3: Pose Extraction And Cleaning
-
-Goal: convert videos into a clean 17-point 3D pose sequence.
-
-Deliverables:
-
-- MediaPipe Pose Landmarker integration.
-- Per-frame landmark persistence.
-- Pose quality scoring.
-- Smoothing and interpolation.
-- Coordinate normalization.
-
-## Phase 4: Exercise Router
-
-Goal: classify the video as squat, push-up, shoulder press, or unknown.
-
-Deliverables:
-
-- Pose feature extraction for 30-frame windows.
-- Baseline classifier.
-- Fine-tuned small temporal classifier.
-- Confidence-weighted aggregation.
-- Manual fallback when confidence is low.
-
-## Phase 5: Rep Segmentation
-
-Goal: split each exercise into clean reps using transparent state machines.
-
-Deliverables:
-
-- Squat rep counter.
-- Push-up rep counter.
-- Shoulder press rep counter.
-- Partial-rep handling.
-- Rep boundary visualization/debug output.
-
-## Phase 6: Rep Analysis And Variation Detection
-
-Goal: compute meaningful metrics per rep and separate valid variations from issues.
-
-Deliverables:
-
-- Common rep metrics.
-- Exercise-specific metrics.
-- Variation detection rules.
-- Aggregate trends such as fatigue and decreasing ROM.
-
-## Phase 7: Frame-Level Issue Markers
-
-Goal: identify exact issue intervals and attach evidence to each issue.
-
-Deliverables:
-
-- Rule-based frame-level issue scores.
-- Consecutive-frame thresholding.
-- Issue interval grouping.
-- Optional temporal issue classifier.
-- Evidence payloads for each marker.
-
-## Phase 8: Annotated Video And UI
-
-Goal: make the evidence visible and easy to inspect.
-
-Deliverables:
-
-- Skeleton overlay renderer.
-- Red/amber highlights during issue intervals.
-- Rep counter overlay.
-- Issue thumbnails.
-- Gradio report layout with summary, metrics, reps, issues, and JSON evidence tabs.
-
-## Phase 9: Grounded Coach Summary
-
-Goal: generate concise coaching feedback from structured evidence, not model memory.
-
-Deliverables:
-
-- Exercise, variation, issue, goal, and safety knowledge cards.
-- Deterministic retrieval.
-- SLM prompt contract.
-- Summary verifier.
-- Conservative fallback summary.
-
-## Phase 10: Dataset, Training, Evaluation, And Demo
-
-Goal: create a defensible small-model story and a reliable hackathon demo.
-
-Deliverables:
-
-- Dataset ingestion scripts.
-- Custom data collection guide.
-- Training pipeline for the exercise router.
-- Evaluation metrics.
-- Demo videos.
-- README and deployment instructions.

docs/91-archive-coach-analysis-implementation-plan.md

@@ -1,183 +0,0 @@
-# Pozify Coach Analysis Expansion Plan
-
-Status: historical implementation plan for the coach-analysis branch work.
-
-Use [../README.md](../README.md) and [01-docs-index.md](01-docs-index.md) for the current runtime
-workflow and operational commands.
-
-## Objective
-
-Extend Pozify's grounded coach-summary pipeline with a dataset-ready knowledge layer so the app can incorporate richer exercise expertise without turning the product into a generic chatbot.
-
-The target outcome is:
-
-- Keep summary generation grounded in structured artifacts.
-- Expand exercise knowledge through deterministic retrieval.
-- Preserve verifier safety rules and current UI/report interfaces.
-- Create a clean path for later ingesting open datasets such as `hasaneyldrm/exercises-dataset`.
-
-## Why This Fits The Current Codebase
-
-Pozify already has the right runtime shape:
-
-- `src/pozify/pipeline.py` orchestrates the end-to-end flow.
-- `src/pozify/knowledge_cards.py` provides deterministic card retrieval.
-- `src/pozify/slm/prompting.py` injects knowledge cards into the SLM prompt.
-- `src/pozify/steps/verifier.py` rejects unsafe or ungrounded output.
-
-That means the highest-leverage change is not a chat finetune. It is a stronger knowledge-source layer that can feed better grounded cards into the existing summary step.
-
-## Recommended Data Strategy
-
-### Primary data source
-
-Use `hasaneyldrm/exercises-dataset` as the main source for exercise-grounding expansion because it maps naturally to Pozify's current `knowledge_cards` architecture:
-
-- exercise names
-- target muscles
-- equipment
-- execution cues
-- standardized instructions
-
-### Secondary sources
-
-Use conversational datasets such as:
-
-- `onurSakar/GYM-Exercise`
-- `HazSylvia/Fitness_Unformatted`
-- `chibbss/fitness-chat-prompt-completion-dataset`
-
-only later, and only for:
-
-- coach voice calibration
-- response phrasing
-- optional supervised examples for tone
-
-These should not be the primary source for grounded issue reasoning.
-
-## Implementation Steps
-
-### Step 1. Plan and branch setup
-
-Deliverables:
-
-- This plan document.
-- New branch `ht/coach-analysis`.
-
-Commit:
-
-- `docs: add coach-analysis implementation plan`
-
-### Step 2. Add dataset-ready card pack loading
-
-Goal:
-
-Allow Pozify to load extra knowledge cards from local JSON packs while keeping built-in cards as safe defaults.
-
-Deliverables:
-
-- A local card-pack loader in `src/pozify/knowledge_cards.py` or adjacent module.
-- Deterministic merge rules:
-  - built-in cards always exist
-  - external packs may add new cards
-  - external packs may enrich known labels without breaking retrieval order
-- Environment-based configuration for optional pack paths.
-
-Why:
-
-This lets us transform open datasets into card packs offline and plug them into the existing summary pipeline without changing the model contract.
-
-Commit:
-
-- `feat: load external coach knowledge card packs`
-
-### Step 3. Add a sample coach-analysis pack
-
-Goal:
-
-Ship one real example pack that demonstrates how open dataset knowledge will be represented inside Pozify.
-
-Deliverables:
-
-- A checked-in JSON pack under `data/knowledge_cards/`.
-- Enriched entries for existing exercises such as:
-  - squat
-  - push-up
-  - shoulder press
-- Additional factual fields expressed through current card schema:
-  - execution cues
-  - equipment context
-  - target-muscle context
-
-Commit:
-
-- `feat: add sample external coach knowledge pack`
-
-### Step 4. Surface card provenance in artifacts
-
-Goal:
-
-Make it observable when coach summaries used built-in cards versus dataset-backed cards.
-
-Deliverables:
-
-- Final report artifact metadata indicating:
-  - whether external packs were loaded
-  - which pack files were used
-  - how many retrieved cards came from external packs
-
-Commit:
-
-- `feat: expose coach knowledge provenance in artifacts`
-
-### Step 5. Add tests for deterministic retrieval and pack loading
-
-Goal:
-
-Protect the summary pipeline from nondeterministic knowledge changes.
-
-Deliverables:
-
-- Unit tests for:
-  - valid external pack parsing
-  - deterministic merge behavior
-  - duplicate-card override rules
-  - retrieval by label with external packs enabled
-  - pipeline artifact provenance
-
-Commit:
-
-- `test: cover external coach knowledge retrieval`
-
-### Step 6. Validate end-to-end behavior
-
-Goal:
-
-Confirm the current app still runs and contract tests still pass.
-
-Deliverables:
-
-- Passing targeted tests:
-  - `tests.test_coach_summary`
-  - `tests.test_pipeline_contracts`
-- No regressions in current UI/report flow.
-
-Commit:
-
-- `test: validate coach-analysis pipeline integration`
-
-## Follow-On Work After This Branch
-
-These items are intentionally out of scope for the first implementation pass but become straightforward after the card-pack layer exists:
-
-1. Build a dataset transformer that converts `hasaneyldrm/exercises-dataset` rows into Pozify card packs.
-2. Add a small curated evaluation set of artifact-to-summary pairs.
-3. Fine-tune a small instruct model on Pozify-native JSON-to-summary examples.
-4. Optionally add a separate chat/Q&A mode using the conversational datasets.
-
-## Success Criteria
-
-- Pozify still generates grounded summaries from structured artifacts.
-- The app can ingest richer exercise knowledge through deterministic local packs.
-- Retrieval remains explainable and testable.
-- Verifier and fallback behavior remain unchanged in safety-sensitive cases.

docs/92-archive-coach-model-data-plan.md

@@ -1,660 +0,0 @@
-# Pozify Coach Model Data Plan
-
-Status: planning and architecture note.
-
-This file is useful for model and dataset strategy, but it is not the source of truth for the
-current run/deploy commands. Use [../README.md](../README.md) and
-[30-coach-modal-training.md](30-coach-modal-training.md) for the current workflow.
-
-## Objective
-
-Define a practical data and modeling plan for improving Pozify's coach summary and coach-style guidance using open datasets and the current codebase.
-
-This document answers:
-
-- Which public datasets are actually useful for Pozify's current problem.
-- Whether to use RAG, SFT, or both.
-- How those choices fit the current pipeline, artifacts, verifier, and UI.
-- A concrete implementation roadmap that does not break the current app architecture.
-
-## Current Codebase Fit
-
-Pozify today is not a generic fitness chatbot. It is a structured video-analysis pipeline that ends with a grounded coach summary:
-
-- `video_qc` -> `pose_landmarker` -> `exercise_classifier` -> `rep_analysis` -> `variation` -> `issue_markers` -> `coach_summary` -> `verifier`
-- The coach summary step already consumes structured evidence and retrieved knowledge cards.
-- The verifier already rejects summaries that invent issues, overcorrect valid variations, or make unsafe claims.
-
-Relevant modules:
-
-- `src/pozify/pipeline.py`
-- `src/pozify/steps/coach_summary.py`
-- `src/pozify/slm/prompting.py`
-- `src/pozify/knowledge_cards.py`
-- `src/pozify/steps/verifier.py`
-
-That means any dataset strategy must be evaluated against the real task:
-
-> Generate safe, grounded, structured coaching language from Pose/Rep/Variation/Issue JSON artifacts.
-
-This is **not** the same task as:
-
-- answering open-ended fitness questions,
-- free-form nutrition coaching,
-- broad lifestyle coaching,
-- or generic health chat.
-
-## Recommendation Summary
-
-### Best near-term strategy
-
-Use a **hybrid approach**:
-
-1. **Expand knowledge retrieval first** using a curated exercise knowledge base.
-2. **Keep coach summary grounded on structured Pozify artifacts.**
-3. **Use lightweight SFT only after you have a Pozify-native training set** built from your own analysis artifacts and target summaries.
-
-### What not to do first
-
-Do **not** directly fine-tune the current coach-summary model on broad fitness chat datasets and expect it to improve the grounded summary step.
-
-That would likely:
-
-- make the model more conversational,
-- but also make it more likely to hallucinate,
-- talk beyond the provided JSON,
-- and fight against the verifier.
-
-### Strong recommendation
-
-For the current codebase, the best order is:
-
-1. **RAG / retrieval upgrade**
-2. **Pozify-native supervised dataset creation**
-3. **LoRA / SFT on the Pozify-native task**
-4. **Optional separate chatbot mode** trained on public chat/Q&A datasets
-
-## Dataset-by-Dataset Assessment
-
-### 1. `onurSakar/GYM-Exercise`
-
-Source notes:
-
-- Hugging Face dataset page shows `1.66k` rows and a single text field formatted in Llama-style instruction format.
-- The visible examples include fitness Q&A, but also broader wellness topics such as environmental stressors, work-life balance, mental clarity, and social well-being.
-
-Fit for Pozify:
-
-- Good for **general fitness coach tone**.
-- Weak fit for **grounded rep-by-rep coach summary generation**.
-- Weak fit for **variation-vs-issue reasoning** tied to structured pose artifacts.
-
-Risks:
-
-- Topic drift beyond movement coaching.
-- May encourage generic answer patterns instead of artifact-conditioned reasoning.
-- Could increase verifier failures because the model may mention things outside `issue_markers.json`.
-
-Best use in Pozify:
-
-- Use only as **auxiliary style data**.
-- Filter to movement-technique and workout-guidance samples.
-- Do not use raw as the main SFT dataset for `coach_summary`.
-
-Verdict:
-
-- **Useful later**
-- **Not the primary dataset for the current summary pipeline**
-
-### 2. `HazSylvia/Fitness_Unformatted`
-
-Source notes:
-
-- Hugging Face page shows `928` rows.
-- Fields appear as `Human` and `Assistant`.
-- Examples are cleaner fitness Q&A than the dataset above and closer to gym onboarding and workout guidance.
-
-Fit for Pozify:
-
-- Better than `onurSakar/GYM-Exercise` for conversational coach tone.
-- Still not tightly aligned with Pozify's structured JSON-to-summary task.
-
-Risks:
-
-- Still mostly free-form Q&A, not evidence-grounded explanation.
-- Lacks explicit inputs like `rep_analysis`, `variation`, `issue_markers`.
-
-Best use in Pozify:
-
-- Use as **secondary SFT data for tone/voice**.
-- Convert to JSONL and filter for exercise technique, beginner coaching, and workout-planning responses.
-- Consider this dataset for a future `Ask Pozify` chat mode.
-
-Verdict:
-
-- **Good for coach voice**
-- **Not enough by itself for the current pipeline**
-
-### 3. `chibbss/fitness-chat-prompt-completion-dataset`
-
-Source notes:
-
-- Hugging Face page shows `245` rows.
-- Has `instruction` and `output` fields.
-- Content appears to focus on healthy habits, routines, stress, sleep, and lifestyle guidance.
-
-Fit for Pozify:
-
-- Good format for instruction tuning.
-- Too small and too broad to be the main fine-tuning source for the current task.
-
-Risks:
-
-- Small size.
-- Lifestyle-heavy answers may not improve form-review summaries.
-- Could push the model toward broad wellness advice instead of evidence-based movement coaching.
-
-Best use in Pozify:
-
-- Optional augmentation for tone.
-- Better suited to a future “habit coach” or “ask a coach” feature than to movement-summary generation.
-
-Verdict:
-
-- **Supplementary only**
-
-### 4. `hasaneyldrm/exercises-dataset`
-
-Based on your description, this is the most strategically valuable dataset for Pozify right now.
-
-Fit for Pozify:
-
-- High fit for retrieval and knowledge expansion.
-- It maps well to Pozify's current `knowledge_cards` architecture.
-- It improves factual consistency for exercise descriptions, target muscles, equipment, and execution cues.
-
-Why it fits the codebase:
-
-- Pozify already retrieves deterministic cards in `src/pozify/knowledge_cards.py`.
-- The prompt builder already injects knowledge cards into the model input.
-- The current gap is not “more chat data”; the gap is “richer, broader, more standardized exercise knowledge.”
-
-Best use in Pozify:
-
-- Use this as the basis for a **local knowledge base** first.
-- Convert exercise rows into:
-  - exercise cards,
-  - variation cards,
-  - equipment-aware cues,
-  - and optional goal-specific cue overlays.
-- Later, optionally index it in FAISS/Chroma for semantic retrieval in a separate chat flow.
-
-Verdict:
-
-- **Best immediate dataset to integrate**
-
-### 5. `strova-ai/fitness-tracker-dataset`
-
-Source notes:
-
-- Hugging Face page describes it as a synthetic wearable/activity dataset.
-- It contains tabular metrics such as age, gender, height, weight, steps, heart rate, calories, distance, and activity.
-- The page also shows dataset-viewer schema issues, which suggests ingestion may need cleanup.
-
-Fit for Pozify:
-
-- Useful for personalization experiments.
-- Weak fit for current video-form summary generation.
-
-Why it does not fit immediately:
-
-- Pozify's current app does not reason from wearable timeseries.
-- The current `UserProfile` contract is small and categorical.
-- There is no current component that transforms tabular physiology into grounded motion advice.
-
-Best use in Pozify:
-
-- Optional later-stage personalization module.
-- Useful for future “today's activity context” or “session recommendation” features.
-- Not a priority for the current coach summary pipeline.
-
-Verdict:
-
-- **Future personalization dataset, not Phase 1**
-
-## What This Means For Pozify
-
-### The current task is not generic chat SFT
-
-Pozify's core output is:
-
-- bounded by `exercise_classification.json`
-- bounded by `rep_analysis.json`
-- bounded by `variation.json`
-- bounded by `issue_markers.json`
-- conditioned by knowledge cards
-- checked by a verifier
-
-So the most valuable training examples are not public generic fitness Q&A.
-
-The most valuable examples look like this:
-
-```json
-{
-  "analysis_json": {
-    "user_profile": {},
-    "exercise_classification": {},
-    "rep_analysis": {},
-    "variation": {},
-    "issue_markers": {}
-  },
-  "retrieved_knowledge_cards": [],
-  "ideal_coach_summary": {
-    "summary": "",
-    "what_you_did": [],
-    "what_looked_good": [],
-    "what_changed_across_reps": [],
-    "valid_variation_vs_issue": [],
-    "top_fixes": [],
-    "next_session_plan": [],
-    "confidence_notes": []
-  }
-}
-```
-
-This is already much closer to the current runtime prompt contract than any public chat dataset you listed.
-
-## Recommended Strategy
-
-## Option A: Retrieval-first upgrade
-
-### Why this is the best first move
-
-It fits the current architecture with the least risk.
-
-It improves:
-
-- factual exercise guidance,
-- coaching cue coverage,
-- equipment-specific instructions,
-- and future exercise expansion,
-
-without retraining the model first.
-
-### How to use `hasaneyldrm/exercises-dataset`
-
-Convert exercise rows into a normalized internal artifact such as:
-
-```json
-{
-  "card_id": "exercise:barbell_bench_press",
-  "card_type": "exercise",
-  "labels": ["barbell_bench_press", "bench_press"],
-  "title": "Barbell Bench Press",
-  "summary": "Compound upper-body press.",
-  "target_muscles": ["chest"],
-  "secondary_muscles": ["triceps", "front_delts"],
-  "equipment": ["barbell", "bench"],
-  "instructions": [
-    "Set the shoulder blades before unracking.",
-    "Lower with control to a repeatable touch point.",
-    "Press while keeping wrists stacked."
-  ]
-}
-```
-
-### Implementation in current codebase
-
-1. Add a data ingestion script under `scripts/`:
-   - `scripts/build_exercise_knowledge_base.py`
-2. Store normalized cards under:
-   - `data/knowledge/exercises.json`
-3. Update `src/pozify/knowledge_cards.py` to:
-   - load built-in cards,
-   - merge external exercise cards,
-   - keep deterministic retrieval for current exercise/variation/issue labels.
-4. Keep the current coach-summary flow intact.
-
-### Benefits
-
-- Immediate product improvement.
-- No retraining required.
-- Low safety risk.
-- Reuses the current prompt architecture.
-
-## Option B: Pozify-native SFT for coach summary
-
-### Why this is the right SFT target
-
-If you do SFT, train on the task Pozify actually runs:
-
-- structured evidence in
-- structured grounded summary out
-
-### Recommended data source for SFT
-
-Build your own dataset from:
-
-- current artifact pipeline outputs in `runs/`
-- synthetic or hand-authored expert summaries
-- optional edits by the team
-
-Then optionally augment with:
-
-- filtered examples from `HazSylvia/Fitness_Unformatted`
-- filtered examples from `onurSakar/GYM-Exercise`
-- filtered examples from `chibbss/fitness-chat-prompt-completion-dataset`
-
-But use public datasets only for:
-
-- tone,
-- phrasing,
-- concise coaching style,
-- and generic structure.
-
-Do not use them to replace the grounded target format.
-
-### SFT training objective
-
-Input:
-
-- current prompt evidence object
-- retrieved cards
-
-Output:
-
-- the exact `CoachSummary` JSON contract
-
-### Recommended model
-
-Use the current runtime-aligned model family first:
-
-- `Qwen/Qwen3-14B`
-
-Because the app already uses this model family successfully through Hugging Face Inference.
-
-### Recommended training tools
-
-- TRL if you want closer Hugging Face-native control
-- Unsloth if you want fast LoRA iteration on a smaller GPU budget
-- Axolotl if you want a cleaner config-driven fine-tuning pipeline
-
-### Best fine-tuning style
-
-- LoRA / QLoRA
-- JSON-only target format
-- deterministic eval checks against verifier outcomes
-
-### Why not train directly on public chat sets first
-
-Because the task mismatch is too large:
-
-- public chat sets teach “fitness assistant”
-- Pozify needs “artifact-grounded explanation generator”
-
-## Option C: Separate chat / Ask-a-Coach feature
-
-This is where the public datasets are actually strongest.
-
-### Best datasets for that feature
-
-- `HazSylvia/Fitness_Unformatted`
-- `onurSakar/GYM-Exercise`
-- `chibbss/fitness-chat-prompt-completion-dataset`
-
-### Suitable user stories
-
-- “I am new to the gym, where do I start?”
-- “Can you give me a 3-day weekly plan?”
-- “What should I eat after a workout?”
-- “How do I stay consistent?”
-
-### Why keep this separate from coach summary
-
-Because:
-
-- the current summary step must stay grounded
-- broad wellness chat should not weaken form-review safety
-- the verifier logic is built for artifact-based outputs, not broad coaching conversations
-
-### Suggested architecture
-
-- Keep `coach_summary` as today, evidence-first.
-- Add a future `ask_coach` endpoint and UI tab.
-- Back that feature with:
-  - a filtered fitness Q&A dataset,
-  - optional RAG over exercise knowledge,
-  - and a different safety policy.
-
-## Recommended Final Architecture
-
-### Phase 1
-
-- Retrieval-only upgrade from exercise knowledge base
-- No SFT required
-
-### Phase 2
-
-- Build Pozify-native summary dataset
-- Fine-tune a LoRA adapter for structured summary generation
-
-### Phase 3
-
-- Add optional `Ask Pozify` chat mode
-- Use public Q&A datasets there
-
-### Phase 4
-
-- Add personalization features using wearable/tabular data
-- Use `strova-ai/fitness-tracker-dataset` only if product scope expands into recommendations
-
-## Concrete Implementation Plan
-
-## Step 1: Add external exercise knowledge ingestion
-
-Goal:
-
-- turn exercise reference data into Pozify-ready knowledge cards
-
-Work:
-
-1. Create `data/knowledge/` directory.
-2. Add `scripts/build_exercise_knowledge_base.py`.
-3. Normalize raw exercise dataset fields into a local JSON schema.
-4. Add tests for normalization and card loading.
-5. Update `src/pozify/knowledge_cards.py` to load external cards.
-
-Deliverables:
-
-- `data/knowledge/exercises.json`
-- updated knowledge card loader
-- tests
-
-## Step 2: Expand current retrieval interface
-
-Goal:
-
-- use richer exercise and equipment context without changing app UX
-
-Work:
-
-1. Keep deterministic retrieval for current labels.
-2. Add equipment-aware retrieval using `UserProfile.equipment`.
-3. Add goal-aware retrieval overlays.
-4. Add per-exercise cue prioritization for the summary prompt.
-
-Deliverables:
-
-- richer `retrieve_cards(...)`
-- no changes needed in the UI contract
-
-## Step 3: Create a Pozify-native SFT dataset builder
-
-Goal:
-
-- create training examples from the actual runtime task
-
-Work:
-
-1. Add `scripts/build_coach_summary_sft_dataset.py`.
-2. Read from:
-   - `runs/*/exercise_classification.json`
-   - `runs/*/rep_analysis.json`
-   - `runs/*/variation.json`
-   - `runs/*/issue_markers.json`
-   - retrieved knowledge cards
-3. Export JSONL rows like:
-
-```json
-{
-  "messages": [
-    {"role": "system", "content": "..."},
-    {"role": "user", "content": "...structured evidence..."},
-    {"role": "assistant", "content": "{...coach summary json...}"}
-  ]
-}
-```
-
-4. Start with hand-authored gold summaries for 100-300 samples.
-5. Add validation scripts that reject malformed outputs.
-
-Deliverables:
-
-- `data/sft/coach_summary_train.jsonl`
-- `data/sft/coach_summary_eval.jsonl`
-
-## Step 4: Use public datasets only as auxiliary style data
-
-Goal:
-
-- improve coach tone without damaging grounded reasoning
-
-Work:
-
-1. Add `scripts/prepare_public_fitness_chat_data.py`.
-2. Ingest:
-   - `onurSakar/GYM-Exercise`
-   - `HazSylvia/Fitness_Unformatted`
-   - `chibbss/fitness-chat-prompt-completion-dataset`
-3. Filter out:
-   - broad medical claims
-   - unrelated wellness topics
-   - environment/toxin/social-life content
-4. Convert only the most relevant rows into a secondary style corpus.
-5. Use this corpus with lower sampling weight than Pozify-native data.
-
-Deliverables:
-
-- `data/sft/public_fitness_style.jsonl`
-
-## Step 5: Fine-tune with LoRA
-
-Goal:
-
-- make the model better at emitting Pozify's exact summary contract
-
-Work:
-
-1. Choose one training stack:
-   - TRL
-   - Unsloth
-   - Axolotl
-2. Fine-tune `Qwen/Qwen3-14B`.
-3. Use:
-   - low temperature at inference
-   - JSON-only targets
-   - training/eval split with verifier-based metrics
-4. Track:
-   - JSON validity rate
-   - verifier pass rate
-   - unsupported-issue mention rate
-   - variation-overcorrection rate
-
-Deliverables:
-
-- LoRA adapter
-- eval report
-- deployment notes
-
-## Step 6: Add pluggable model loading for local or Hub adapters
-
-Goal:
-
-- swap between base model and fine-tuned adapter cleanly
-
-Work:
-
-1. Extend `src/pozify/slm/providers.py`.
-2. Add env-driven model selection:
-   - base model
-   - fine-tuned adapter
-   - fallback model
-3. Surface model metadata in `final_report.artifacts`.
-
-Deliverables:
-
-- deployable adapter path
-- clear model/version tracking in UI and artifacts
-
-## Step 7: Optional future RAG for free-form chat
-
-Goal:
-
-- add a broader coach chat feature without weakening grounded summaries
-
-Work:
-
-1. Add `src/pozify/chat/` module.
-2. Index exercise knowledge into:
-   - FAISS first, or
-   - ChromaDB if persistence/filtering is preferred
-3. Use RAG only for:
-   - exercise explanations
-   - equipment substitutions
-   - general programming suggestions
-4. Keep this separate from `coach_summary`.
-
-Deliverables:
-
-- `Ask Pozify` feature
-- isolated inference path
-
-## Decision Table
-
-| Dataset | Best use in Pozify | Use now? | Notes |
-|---|---|---:|---|
-| `onurSakar/GYM-Exercise` | auxiliary style SFT | No | useful tone, but too broad for summary task |
-| `HazSylvia/Fitness_Unformatted` | auxiliary style SFT / future chat | Later | cleaner coach Q&A, still task-mismatched |
-| `chibbss/fitness-chat-prompt-completion-dataset` | auxiliary style SFT / future chat | Later | small, useful for tone only |
-| `hasaneyldrm/exercises-dataset` | retrieval knowledge base | Yes | best immediate fit for current architecture |
-| `strova-ai/fitness-tracker-dataset` | future personalization | No | not aligned with current app contracts |
-
-## Final Recommendation
-
-If the goal is to improve the current Pozify product, do this:
-
-1. **Integrate `hasaneyldrm/exercises-dataset` as structured knowledge cards first.**
-2. **Build a Pozify-native coach-summary SFT dataset from real artifacts.**
-3. **Fine-tune Qwen with LoRA on the Pozify-native task.**
-4. **Use public fitness chat datasets only as secondary style data.**
-5. **Use RAG later for a separate chat feature, not to replace the current grounded summary path.**
-
-This path gives the best balance of:
-
-- safety,
-- architecture fit,
-- product usefulness,
-- and implementation risk.
-
-## Sources
-
-- Hugging Face dataset page for `onurSakar/GYM-Exercise`: https://huggingface.co/datasets/onurSakar/GYM-Exercise
-- Hugging Face dataset page for `HazSylvia/Fitness_Unformatted`: https://huggingface.co/datasets/HazSylvia/Fitness_Unformatted
-- Hugging Face dataset page for `chibbss/fitness-chat-prompt-completion-dataset`: https://huggingface.co/datasets/chibbss/fitness-chat-prompt-completion-dataset
-- Hugging Face dataset page for `strova-ai/fitness-tracker-dataset`: https://huggingface.co/datasets/strova-ai/fitness-tracker-dataset
-- Pozify runtime code:
-  - `src/pozify/pipeline.py`
-  - `src/pozify/steps/coach_summary.py`
-  - `src/pozify/slm/prompting.py`
-  - `src/pozify/knowledge_cards.py`
-  - `src/pozify/steps/verifier.py`

docs/99-archive-pozify-project-documentation.md

@@ -1,1211 +0,0 @@
-# Pozify Project Documentation
-
-Status: large historical product/design document.
-
-Some sections may lag behind the current runtime implementation. For the current project entrypoint,
-commands, and model workflow, use [../README.md](../README.md) and [01-docs-index.md](01-docs-index.md).
-
-## 1. Product Overview
-
-**Pozify** is a Gradio web app that lets a user upload or record a short workout video, then returns a rep-by-rep movement report built from pose landmarks, movement metrics, frame-level issue markers, and goal-aware coaching feedback.
-
-One-line pitch:
-
-> Pozify turns a short workout video into a rep-by-rep movement report: what you did, where your form changed, why it matters for your goal, and what to practice next.
-
-Pozify is not positioned as a generic fitness chatbot. It is a **video evidence review cockpit**: the user sees the exercise detected, rep count, issue timestamps, movement metrics, confidence notes, and a practical next-session plan.
-
-Pozify is also not a medical or clinical product. It should not diagnose injuries, claim to prevent injuries, or replace a qualified trainer, clinician, or physical therapist.
-
-## 2. MVP Scope
-
-The MVP supports three exercises:
-
-- Squat.
-- Push-up.
-- Shoulder press.
-
-Depth strategy:
-
-- Classify all three supported exercises.
-- Provide deeper analysis for squat and push-up first.
-- Provide shoulder press counting and one or two core issue checks in the MVP.
-- Clearly display confidence and feature depth in the UI.
-
-### In Scope
-
-- Gradio web app.
-- Upload or record short workout videos.
-- User profile and training intent form.
-- Video quality check.
-- 17-point 3D pose extraction.
-- Pose cleaning and normalization.
-- Exercise classifier for `squat`, `push_up`, `shoulder_press`, and `unknown`.
-- Exercise-specific rep counter.
-- Per-rep movement metrics.
-- Basic variation detection.
-- Frame-level issue markers.
-- Annotated video renderer.
-- Grounded coach summary from a small language model.
-- Verifier for coach summary quality and safety.
-- JSON evidence/debug output.
-- Optional downloadable JSON/PDF report.
-
-### Out Of Scope
-
-- Medical diagnosis.
-- Injury claims.
-- Lab-grade biomechanics claims.
-- Support for every gym exercise.
-- Real-time live coaching.
-- Multi-person workout analysis.
-- Replacing a professional coach or clinician.
-
-## 3. Target User And Problem
-
-Target users:
-
-- Beginner or casual gym-goers.
-- People training at home.
-- Users who already record workout videos but do not know how to evaluate them.
-- Users who need specific, timestamped feedback instead of generic advice.
-
-Core user problem:
-
-- The user has a video but does not know which reps changed or failed.
-- Online form advice is often generic and not tied to visible evidence.
-- Valid exercise variations can be mistaken for errors.
-- Beginners need concise cues and a concrete next action.
-
-## 4. System Architecture
-
-Main pipeline:
-
-```text
-user profile + input video
--> video QC
--> 17-point 3D pose landmarker
--> pose cleaning and normalization
--> exercise classifier
--> exercise-specific rep counter
--> per-rep analysis
--> variation detection
--> frame-level issue markers
--> annotated video renderer
--> grounded coach summary
--> verifier
--> final report and UI
-```
-
-End-to-end flow:
-
-```mermaid
-flowchart TD
-    A["User uploads or records workout video"] --> B["Video QC"]
-    U["User profile and training intent"] --> G["Grounded coach summary"]
-    B --> C["17-point 3D Pose Landmarker"]
-    C --> D["Pose cleaning and normalization"]
-    D --> E["Exercise classifier"]
-    E --> F{"Exercise type"}
-    F -->|Squat| S1["Squat rep counter"]
-    F -->|Push-up| P1["Push-up rep counter"]
-    F -->|Shoulder press| O1["Shoulder press rep counter"]
-    S1 --> S2["Squat per-rep analysis"]
-    P1 --> P2["Push-up per-rep analysis"]
-    O1 --> O2["Shoulder press per-rep analysis"]
-    S2 --> H["Frame-level issue markers"]
-    P2 --> H
-    O2 --> H
-    H --> R["Annotated video renderer"]
-    H --> G
-    K["Exercise knowledge cards"] --> G
-    G --> V["Summary verifier"]
-    V --> Z["Final report and UI"]
-    R --> Z
-```
-
-Data contract flow:
-
-```mermaid
-flowchart LR
-    A["input.mp4"] --> B["video_manifest.json"]
-    B --> C["pose_sequence.json"]
-    C --> D["exercise_classification.json"]
-    D --> E["reps.json"]
-    E --> F["rep_analysis.json"]
-    F --> G["variation.json"]
-    G --> H["issue_markers.json"]
-    H --> I["coach_summary.json"]
-    H --> J["annotated_video.mp4"]
-    I --> K["final_report.json"]
-    J --> K
-```
-
-Design principles:
-
-- Each step reads and writes structured data.
-- Each model can be replaced independently.
-- Every coach summary claim should be traceable to metrics, issue markers, user profile, or knowledge cards.
-- Low-confidence input should produce warnings or rejection instead of hallucinated feedback.
-
-## 5. Data Contracts
-
-The Python contracts are defined in `src/pozify/contracts.py`.
-
-### `UserProfile`
-
-Captures user intent and context.
-
-Fields:
-
-- `goal`: `strength`, `hypertrophy`, `endurance`, `mobility`, or `beginner_practice`.
-- `experience_level`: `beginner` or `intermediate`.
-- `intended_exercise`: `auto`, `squat`, `push_up`, or `shoulder_press`.
-- `intended_variation`: optional variation label.
-- `known_limitations`: discomfort or limitation flags.
-- `equipment`: `bodyweight`, `dumbbell`, `barbell`, or `unknown`.
-
-Example:
-
-```json
-{
-  "goal": "hypertrophy",
-  "experience_level": "beginner",
-  "intended_exercise": "push_up",
-  "intended_variation": "wide_grip_push_up",
-  "known_limitations": ["wrist_discomfort"],
-  "equipment": "bodyweight"
-}
-```
-
-### `VideoManifest`
-
-Stores video metadata and quality warnings.
-
-Example:
-
-```json
-{
-  "video_path": "input.mp4",
-  "fps": 30.0,
-  "duration_sec": 24.8,
-  "total_frames": 744,
-  "sampled_frames": 372,
-  "quality_warnings": ["side_view_detected"],
-  "analysis_allowed": true
-}
-```
-
-### `PoseSequence`
-
-Stores pose frames after extraction and cleaning.
-
-Each frame includes:
-
-- `frame_index`
-- `timestamp_sec`
-- `landmarks`
-- `world_landmarks`
-- `pose_quality`
-
-Example:
-
-```json
-{
-  "frame_index": 120,
-  "timestamp_sec": 4.0,
-  "landmarks": {
-    "left_shoulder": { "x": 0.43, "y": 0.32, "z": -0.03, "visibility": 0.99 }
-  },
-  "world_landmarks": {},
-  "pose_quality": {
-    "mean_visibility": 0.93,
-    "critical_landmarks_visible": true
-  }
-}
-```
-
-### `ExerciseClassification`
-
-Routes the video to the correct analyzer.
-
-Example:
-
-```json
-{
-  "exercise": "push_up",
-  "confidence": 0.92,
-  "window_predictions": [
-    { "start_sec": 0.0, "end_sec": 1.0, "label": "push_up", "confidence": 0.91 }
-  ],
-  "fallback_required": false
-}
-```
-
-### `Reps`
-
-Stores rep boundaries.
-
-Example:
-
-```json
-{
-  "exercise": "push_up",
-  "reps": [
-    {
-      "rep_id": 1,
-      "start_frame": 60,
-      "mid_frame": 91,
-      "end_frame": 125,
-      "start_sec": 2.0,
-      "mid_sec": 3.03,
-      "end_sec": 4.17
-    }
-  ],
-  "partial_reps": []
-}
-```
-
-### `RepAnalysis`
-
-Stores per-rep metrics and aggregate metrics.
-
-Example:
-
-```json
-{
-  "rep_id": 4,
-  "duration_sec": 1.8,
-  "range_of_motion_score": 0.74,
-  "stability_score": 0.66,
-  "symmetry_score": 0.82,
-  "metrics": {
-    "min_elbow_angle_deg": 91,
-    "body_line_score": 0.62,
-    "hip_sag_score": 0.78,
-    "hand_width_ratio": 1.42
-  },
-  "variation_hints": ["wide_grip_push_up"]
-}
-```
-
-### `Variation`
-
-Separates valid exercise variation from true issues.
-
-Example:
-
-```json
-{
-  "exercise": "push_up",
-  "detected_variation": "wide_grip_push_up",
-  "variation_confidence": 0.84,
-  "not_issues": ["wide_hand_placement"]
-}
-```
-
-### `IssueMarkers`
-
-Stores issue intervals and evidence.
-
-Example:
-
-```json
-{
-  "issues": [
-    {
-      "rep_id": 4,
-      "issue": "hip_sag",
-      "severity": 0.78,
-      "start_frame": 210,
-      "end_frame": 248,
-      "start_sec": 7.0,
-      "end_sec": 8.27,
-      "affected_joints": ["left_hip", "right_hip", "shoulders", "ankles"],
-      "evidence": {
-        "body_line_score": 0.52,
-        "threshold": 0.65
-      }
-    }
-  ]
-}
-```
-
-### `CoachSummary`
-
-Stores grounded user-facing feedback.
-
-Fields:
-
-- `summary`
-- `what_went_well`
-- `main_findings`
-- `variation_explanation`
-- `top_fixes`
-- `next_session_plan`
-- `confidence_notes`
-
-### `Verification`
-
-Stores summary verification results.
-
-Fields:
-
-- `passed`
-- `checks`
-- `notes`
-
-## 6. Step-By-Step Implementation Plan
-
-### Step 0: User Profile And Training Intent
-
-Goal:
-
-- Collect context so coaching is not one-size-fits-all.
-- Help distinguish valid variations from issues.
-- Adapt feedback to the user's goal and experience level.
-
-Model:
-
-- No model required.
-
-Current implementation:
-
-- Gradio form values are converted into a `UserProfile` contract.
-
-Future implementation:
-
-- Add stricter validation for unsupported exercise/variation combinations.
-- Add presets for beginner, hypertrophy, strength, endurance, and mobility use cases.
-
-### Step 1: Video Intake And Quality Check
-
-Goal:
-
-- Accept the video.
-- Normalize metadata.
-- Decide whether analysis is allowed.
-
-Model:
-
-- No dedicated model required.
-
-Future algorithm:
-
-1. Decode video with OpenCV.
-2. Limit duration to 10-60 seconds.
-3. Resize to 480p or 720p.
-4. Sample at 15-30 FPS.
-5. Check brightness.
-6. Check blur with variance of Laplacian.
-7. Check frame count and FPS.
-8. Check pose-valid ratio after pose detection.
-9. Check full-body visibility.
-10. Warn or reject if there are multiple people in frame.
-
-Current implementation:
-
-- Returns mocked video metadata and warnings.
-
-### Step 2: 17-Point 3D Pose Landmarker
-
-Goal:
-
-- Convert video frames into full-body pose landmarks.
-
-Recommended model:
-
-- MediaPipe Pose Landmarker.
-
-Reasons:
-
-- Works on decoded video frames.
-- Outputs COCO-17 body landmarks.
-- Provides image coordinates for rendering and world coordinates for 3D exercise metrics.
-- Practical for a Gradio Space.
-
-Fine-tuning:
-
-- Do not fine-tune the pose detector for the MVP.
-- Use it as a stable feature extractor.
-
-Current implementation:
-
-- Generates mocked landmark frames.
-
-Future implementation:
-
-- Run MediaPipe on sampled frames.
-- Store all 17 COCO body landmarks.
-- Store visibility, pose quality, and 3D world coordinates per frame.
-
-### Step 3: Pose Cleaning And Normalization
-
-Goal:
-
-- Make landmark sequences stable enough for classification and metrics.
-
-Future algorithm:
-
-- Drop low-confidence frames.
-- Interpolate short missing spans.
-- Smooth landmarks with Savitzky-Golay, exponential smoothing, or OneEuro filter.
-- Normalize coordinates by hip center and torso length.
-- Optionally normalize camera rotation for front/side views.
-
-Current implementation:
-
-- Marks the mocked sequence as normalized and smoothed.
-
-### Step 4: Exercise Classifier
-
-Goal:
-
-- Classify video as `squat`, `push_up`, `shoulder_press`, or `unknown`.
-
-Recommended model:
-
-- BiLSTM, TCN, tiny 1D CNN, or GRU over pose-feature windows.
-
-Fast baseline:
-
-- XGBoost or LightGBM over engineered sequence features.
-
-Fine-tuning:
-
-- This is the first recommended fine-tune.
-- It is easier to evaluate and explain than a freeform language-model fine-tune.
-
-Input features:
-
-- Normalized landmarks.
-- Joint angles: knee, hip, elbow, shoulder.
-- Relative distances:
-  - hand width / shoulder width.
-  - stance width / hip width.
-  - wrist-to-shoulder.
-  - hip-to-knee.
-- Motion deltas:
-  - wrist velocity.
-  - hip velocity.
-  - knee velocity.
-  - joint angle deltas.
-
-Current implementation:
-
-- Uses the intended exercise if provided.
-- Defaults to mocked `push_up` when `auto` is selected.
-
-### Step 5: Rep Counting
-
-Goal:
-
-- Split the movement into individual reps.
-- Return `start`, `mid`, and `end` frames and timestamps.
-
-Model:
-
-- No ML needed for MVP.
-- Use deterministic signal processing and exercise-specific state machines.
-
-Squat:
-
-- Signal: knee angle and hip vertical position.
-- Rep: top -> bottom -> top.
-
-Push-up:
-
-- Signal: elbow angle, shoulder/chest vertical motion, and body line.
-- Rep: top -> bottom -> top.
-
-Shoulder press:
-
-- Signal: wrist height and elbow angle.
-- Rep: bottom -> top -> bottom.
-
-Current implementation:
-
-- Returns five mocked reps.
-
-### Step 6: Per-Rep Analysis
-
-Goal:
-
-- Produce a rich feature pack for each rep.
-- Avoid reducing form review to a generic good/bad label.
-
-Common metrics:
-
-- Rep duration.
-- Eccentric duration.
-- Concentric duration.
-- Pause at top/bottom.
-- Tempo consistency.
-- Range of motion score.
-- Left/right symmetry score.
-- Stability score.
-- Smoothness/jerk score.
-- Landmark confidence.
-- Fatigue trend across reps.
-
-Squat metrics:
-
-- Min/max knee angle.
-- Min/max hip angle.
-- Hip depth relative to knee.
-- Torso lean.
-- Knee valgus/varus.
-- Stance width.
-- Hip shift.
-- Bottom stability.
-
-Push-up metrics:
-
-- Min/max elbow angle.
-- Body line score.
-- Hip sag or pike score.
-- Chest depth proxy.
-- Hand width ratio.
-- Elbow flare.
-- Neck/head alignment.
-- Lockout quality.
-
-Shoulder press metrics:
-
-- Min/max elbow angle.
-- Wrist path verticality.
-- Lockout quality.
-- Left/right wrist height asymmetry.
-- Back arch proxy.
-- Overhead stability.
-
-Current implementation:
-
-- Returns exercise-aware mocked metrics.
-
-### Step 7: Variation Detection
-
-Goal:
-
-- Separate valid variation from true issue.
-
-Examples:
-
-- Wide-grip push-up is not automatically an error.
-- Knee push-up can be a regression, not a failure.
-- Partial squat may be acceptable depending on intent.
-
-Model:
-
-- Rule-based first.
-- Optional classifier later.
-
-Current implementation:
-
-- Returns a mocked variation, or the user's intended variation if provided.
-
-### Step 8: Frame-Level Issue Markers
-
-Goal:
-
-- Identify exact frames/timestamps where issues occur.
-- Attach issues to reps.
-- Provide evidence for annotated video and coach summary.
-
-Model:
-
-- Hybrid:
-  - Rule-based issue scores for transparency.
-  - Optional fine-tuned temporal classifier for robustness.
-
-Initial issue labels:
-
-- `shallow_depth`
-- `knee_valgus`
-- `excessive_torso_lean`
-- `hip_shift`
-- `hip_sag`
-- `incomplete_depth`
-- `incomplete_lockout`
-- `uneven_tempo`
-- `unstable_bottom`
-- `asymmetry`
-
-Current implementation:
-
-- Creates mocked issue intervals when stability drops below a threshold.
-
-### Step 9: Annotated Video Renderer
-
-Goal:
-
-- Turn movement analysis into a visual review.
-
-Future renderer:
-
-- Draw skeleton on every frame.
-- Draw normal skeleton in green or blue.
-- Draw active issue joints/segments in red or orange.
-- Overlay rep count.
-- Overlay current phase.
-- Overlay issue label during issue intervals.
-- Add confidence warnings when needed.
-- Export `annotated_video.mp4`.
-
-Current implementation:
-
-- Writes `annotated_video_placeholder.json`.
-- Returns the original video path.
-
-### Step 10: Grounded Coach Summary
-
-Goal:
-
-- Convert structured evidence into concise PT-style feedback.
-- Avoid model hallucinations.
-- Separate valid variations from actual issues.
-
-Recommended SLM:
-
-- Qwen2.5-3B-Instruct for multilingual and structured output.
-- SmolLM2-1.7B-Instruct for a smaller model story.
-- MiniCPM4-0.5B if the team wants an aggressive tiny-model angle.
-
-The SLM should receive:
-
-- User profile.
-- Exercise classification.
-- Variation detection.
-- Rep analysis.
-- Issue markers.
-- Retrieved exercise knowledge cards.
-
-The SLM should not:
-
-- Detect issues directly from video.
-- Invent metrics.
-- Diagnose injury.
-- Claim injury prevention.
-- Treat valid variation as an error.
-
-Current implementation:
-
-- Returns a mocked summary based on structured artifacts.
-
-### Step 11: Verifier
-
-Goal:
-
-- Check the coach summary before displaying it.
-
-Verifier checks:
-
-- Does the summary mention only issues present in JSON?
-- Does it separate variation from issue?
-- Does it adapt to user goal and experience?
-- Does it avoid medical diagnosis?
-- Does it include confidence notes when needed?
-
-Current implementation:
-
-- Runs a lightweight mocked rule verifier.
-
-## 7. Model Plan
-
-### Pose Detector
-
-Recommended model:
-
-- MediaPipe Pose Landmarker.
-
-Role:
-
-- Extract 17 COCO body landmarks per valid frame, with 3D world coordinates when available.
-
-Fine-tuning:
-
-- No fine-tuning for MVP.
-
-### Exercise Router
-
-Recommended model:
-
-- BiLSTM, TCN, tiny 1D CNN, or GRU over pose windows.
-
-Role:
-
-- Route to the correct exercise-specific analyzer.
-
-Fine-tuning:
-
-- Yes. This is the highest-priority fine-tune.
-
-### Rep Counter
-
-Model:
-
-- No ML for MVP.
-
-Role:
-
-- Segment reps using deterministic state machines.
-
-### Per-Rep Analyzer
-
-Model:
-
-- Rule-based metrics and biomechanical feature engineering.
-
-Role:
-
-- Produce evidence for issue markers and coach summary.
-
-### Issue Classifier
-
-Recommended model:
-
-- Tiny 1D CNN, TCN, GRU, XGBoost, or LightGBM.
-
-Role:
-
-- Predict issue probabilities per rep or frame interval.
-
-Fine-tuning:
-
-- Optional after rule-based markers work.
-
-### Small Language Model
-
-Recommended models:
-
-- Qwen2.5-3B-Instruct.
-- SmolLM2-1.7B-Instruct.
-- MiniCPM4-0.5B.
-
-Role:
-
-- Explain structured findings in clear language.
-- Generate top fixes and next-session plan.
-
-Fine-tuning:
-
-- Optional LoRA/SFT for tone, format, and grounded reasoning.
-- Do not use the SLM fine-tune as the primary source of fitness knowledge.
-
-## 8. Dataset Plan
-
-### Exercise Router Dataset
-
-Primary:
-
-- `RickyRiccio/Real_Time_Exercise_Recognition_Dataset`
-
-Useful labels:
-
-- Squat.
-- Push-up.
-- Shoulder press.
-- Barbell bicep curl as a possible negative class.
-
-Custom additions:
-
-- Unknown/setup clips.
-- Standing idle.
-- Walking into or out of frame.
-- Stretching.
-- Bad camera angles.
-- Partial reps.
-- Team/friend videos to improve robustness.
-
-### Issue Classifier Dataset
-
-Public or academic options:
-
-- Fitness-AQA:
-  - BackSquat, OverheadPress, and BarbellRow.
-  - Posture-error annotations.
-  - Requires access approval and attention to non-commercial terms.
-- FLEX:
-  - 20 fitness actions.
-  - Multiview video.
-  - 3D pose.
-  - Error types and feedback.
-  - Requires terms review.
-
-Practical hackathon dataset:
-
-- Record 50-100 clips.
-- Label per rep:
-  - good.
-  - shallow depth.
-  - hip sag.
-  - incomplete lockout.
-  - torso lean.
-  - unstable bottom.
-  - knee valgus.
-  - asymmetry.
-
-Labeling strategy:
-
-1. Generate pseudo-labels from rules.
-2. Manually correct a small validation set.
-3. Train a tiny classifier.
-4. Compare classifier output with rule baseline.
-
-### Coach Summary SFT Dataset
-
-Goal:
-
-- Fine-tune style and structure, not factual knowledge.
-
-Training format:
-
-```json
-{
-  "analysis_json": {},
-  "user_profile": {},
-  "retrieved_knowledge_cards": [],
-  "ideal_coach_summary": ""
-}
-```
-
-Target size:
-
-- 100-300 examples.
-
-Sources:
-
-- Synthetic rep analysis JSON.
-- Curated exercise cards.
-- Team-written ideal summaries.
-- Ambiguous cases:
-  - wide-grip push-up.
-  - knee push-up.
-  - partial squat.
-  - shoulder press back arch.
-  - low-confidence camera angle.
-
-## 9. Knowledge Cards
-
-Knowledge cards keep the SLM grounded.
-
-Card types:
-
-- Exercise card.
-- Variation card.
-- Issue card.
-- Goal card.
-- Safety card.
-
-Each card should contain:
-
-- Exercise or variation label.
-- Primary muscles.
-- Secondary muscles.
-- Valid form notes.
-- Common issues.
-- Related metrics.
-- Not-always-errors.
-- Coaching cues.
-- Regressions.
-- Progressions.
-- Safety notes.
-- Claims the assistant must not make.
-
-Example:
-
-```json
-{
-  "exercise": "push_up",
-  "variation": "wide_grip_push_up",
-  "primary_muscles": ["chest"],
-  "secondary_muscles": ["triceps", "front_delts", "core"],
-  "valid_form_notes": [
-    "Hands wider than shoulder width",
-    "More chest emphasis than close-grip push-up",
-    "Some elbow flare is expected"
-  ],
-  "common_issues": ["hip_sag", "incomplete_depth"],
-  "not_always_errors": ["wide_hand_placement", "moderate_elbow_flare"],
-  "coaching_cues": [
-    "Brace before descent",
-    "Keep shoulders and hips moving together"
-  ]
-}
-```
-
-Retrieval:
-
-- MVP: deterministic lookup by labels.
-- Later: small embedding model if card count grows.
-
-## 10. Output And UI Strategy
-
-Final user-facing output:
-
-1. Annotated video with skeleton and issue markers.
-2. Exercise type and confidence.
-3. Detected variation.
-4. Rep count.
-5. Overall form score.
-6. Movement metrics.
-7. Per-rep breakdown.
-8. Issue timeline with timestamps.
-9. PT-style explanation.
-10. Next-session fix plan.
-11. JSON/PDF report if available.
-
-### Scan Summary
-
-Show immediately:
-
-- Detected exercise.
-- Detected variation.
-- Completed reps.
-- Overall form score.
-- Main issue.
-- Biggest win.
-- Confidence.
-
-Example:
-
-```text
-Exercise: Push-up
-Variation: Wide-grip
-Reps: 8
-Overall Form: 74/100
-Main Limiter: Hip sag after rep 5
-Confidence: 87%
-```
-
-### Annotated Video
-
-Primary visual:
-
-- Video player with skeleton overlay.
-- Red affected joints only during issue intervals.
-- Rep counter.
-- Timeline markers.
-- Click-to-jump issue cards.
-
-### Movement Metrics
-
-Each metric should include:
-
-- Value.
-- Target or expected band.
-- Status: good, caution, needs work.
-- Short explanation.
-
-### Rep Breakdown
-
-Each rep should include:
-
-- Worst-frame thumbnail.
-- ROM score.
-- Stability score.
-- Symmetry score.
-- Tempo.
-- Issues.
-- Confidence.
-
-### Fix Plan
-
-The report should end with practical next actions, not only a summary.
-
-Example:
-
-```text
-Next session:
-1. Slow negative push-up - 2 sets x 5 reps
-   Focus: keep shoulders, hips, and ankles moving as one line.
-
-2. High plank hold - 2 x 20s
-   Focus: brace before each rep.
-
-3. Stop set when hip sag appears
-   Your form starts breaking down after rep 5 today.
-```
-
-### Debug Evidence
-
-For hackathon credibility, expose:
-
-- JSON debug tab.
-- Classifier confidence.
-- Landmark quality.
-- Issue thresholds.
-- Window predictions.
-- Export report.
-
-## 11. Safety And Risk Guardrails
-
-### Risk: The App Feels Generic
-
-Mitigation:
-
-- Do not position Pozify as a chatbot.
-- Make frame-level markers the hero.
-- Show classifier confidence, rep segmentation, issue intervals, and metrics.
-
-### Risk: Bad Video Quality Breaks Analysis
-
-Mitigation:
-
-- Add capture guidance.
-- Add a video quality gate.
-- Refuse low-quality analysis.
-- Show confidence and camera warnings.
-
-### Risk: Three Exercises Become Too Shallow
-
-Mitigation:
-
-- Classify all three.
-- Analyze squat and push-up deeply first.
-- Keep shoulder press simpler in the MVP.
-
-### Risk: Coach Summary Is Wrong
-
-Mitigation:
-
-- Feed structured JSON, knowledge cards, and user profile.
-- Add a verifier step.
-- Keep variation labels separate from issue labels.
-
-### Risk: Fitness Safety Claims
-
-Mitigation:
-
-- Use "practice feedback" language.
-- Avoid diagnosis and injury-prevention claims.
-- Mention uncertainty when confidence is low.
-- If discomfort is reported, give conservative advice.
-
-Recommended language:
-
-- "This is practice feedback based on visible movement."
-- "If this causes pain or discomfort, stop and ask a qualified professional."
-
-Avoid:
-
-- "This prevents injury."
-- "You have a knee problem."
-- "This is a medical assessment."
-
-## 12. Build Phases
-
-### Phase 1: Core Pipeline
-
-Deliver:
-
-- Gradio UI.
-- Video upload.
-- OpenCV decode.
-- Basic video QC.
-- MediaPipe pose extraction.
-- Pose JSON.
-- Basic annotated video export.
-
-### Phase 2: Exercise And Reps
-
-Deliver:
-
-- Exercise classifier.
-- Rep counters for three exercises.
-- Confidence and manual fallback.
-- Rep boundary visualization.
-
-### Phase 3: Analysis And Markers
-
-Deliver:
-
-- Per-rep metrics.
-- Variation detection.
-- Frame-level issue markers.
-- Issue timeline.
-- Rep review table.
-
-### Phase 4: Coach Summary
-
-Deliver:
-
-- Knowledge cards.
-- Deterministic retrieval.
-- SLM summary.
-- Fixed JSON output format.
-- Verifier.
-- Conservative fallback summary.
-
-### Phase 5: Polish
-
-Deliver:
-
-- Better Gradio layout.
-- Before/after demo.
-- Export report.
-- JSON debug tab.
-- Optional progress comparison view.
-
-## 13. Hackathon Demo Script
-
-Use two videos:
-
-1. Good-form example.
-2. Bad-form example, such as push-up hip sag after rep 5 or shallow squat depth.
-
-Demo flow:
-
-1. Upload video.
-2. App detects `push_up`.
-3. App detects `wide_grip_push_up`.
-4. App counts 8 reps.
-5. Timeline shows issues in reps 6-8.
-6. User clicks marker and the video jumps to the issue frame.
-7. Metrics show body line score dropping after rep 5.
-8. Coach summary explains:
-   - Wide grip is not the issue.
-   - Hip sag is the actual breakdown.
-   - The likely cause is fatigue or bracing loss.
-   - The next session should include 2-3 corrective drills.
-
-Demo one-liner:
-
-> Pozify turns workout video into visible movement evidence: exact reps, exact issue frames, grounded metrics, and the next practice plan.
-
-## 14. Success Metrics
-
-Product metrics:
-
-- User understands what to fix in under one minute.
-- Output includes concrete timestamps.
-- User can see which reps were stronger or weaker.
-- User receives a next-session plan.
-
-Technical metrics:
-
-- Exercise classifier works across three exercises plus unknown.
-- Rep count is close on 10-60 second videos.
-- Issue markers avoid one-frame noise.
-- Coach summary does not mention issues outside the JSON.
-- Low-quality video is warned or rejected.
-
-Hackathon metrics:
-
-- Clear visual demo.
-- Defensible small-model or fine-tuned-model story.
-- Dataset/model story on Hugging Face.
-- JSON evidence/debug output to show the app is not a black box.
-
-## 15. References
-
-- Build Small Hackathon: https://huggingface.co/build-small-hackathon
-- MediaPipe Pose Landmarker: https://developers.google.com/edge/mediapipe/solutions/vision/pose_landmarker/python
-- RickyRiccio/Real_Time_Exercise_Recognition_Dataset: https://huggingface.co/datasets/RickyRiccio/Real_Time_Exercise_Recognition_Dataset
-- Fitness AI Trainer With Automatic Exercise Recognition and Counting: https://github.com/RiccardoRiccio/Fitness-AI-Trainer-With-Automatic-Exercise-Recognition-and-Counting
-- Fitness-AQA: https://github.com/ParitoshParmar/Fitness-AQA
-- FLEX Dataset: https://haoyin116.github.io/FLEX_Dataset/
-- Qwen2.5-3B-Instruct: https://huggingface.co/Qwen/Qwen2.5-3B-Instruct
-- SmolLM2-1.7B-Instruct: https://huggingface.co/HuggingFaceTB/SmolLM2-1.7B-Instruct
-- Ochy: https://www.ochy.io/
-- Ochy Runners: https://www.ochy.io/runners