docs: make repo more agent-friendly

.cursor/rules/architecture.md

@@ -0,0 +1,29 @@
+# Architecture (always apply)
+
+Layer dependency direction — **never invert**:
+
+```text
+features/ → domain/ ← infrastructure/
+features/ → shared/providers/ → domain + infrastructure
+```
+
+## Banned imports
+
+| From | Must NOT import |
+|------|-----------------|
+| `lib/features/` | `package:kynos/infrastructure/` |
+| `lib/features/` | another feature's `providers/` |
+| `lib/domain/` | `package:flutter`, `flutter_riverpod`, `riverpod` |
+
+## Enforcement
+
+```bash
+bash scripts/check_architecture.sh
+```
+
+## When violating for DI
+
+Move bindings to `lib/shared/providers/` and re-export types if features need them.
+See `/wire-repository` skill.
+
+Reference: [AGENTS.md §5](../../AGENTS.md#5-dependency-rule-strictly-enforced)

.cursor/rules/kynos.md

@@ -1,9 +1,20 @@
 # KYNOS agent rules
 
+Read [docs/agents/README.md](../../docs/agents/README.md) for the full agent hub.
+
+## Always
+
 1. Read [CODEMAP.md](../../CODEMAP.md) before editing code.
 2. Follow [AGENTS.md](../../AGENTS.md) for architecture and PR workflow.
-3. Never import `infrastructure/` from `features/` — use `shared/providers/`.
-4. Never import one feature's `providers/` from another feature.
-5. Keep hand-written files under ~250 lines; split into `presentation/widgets/`.
-6. Run `dart run tool/generate_codemap.dart` after structural changes.
-7. PR titles must use Conventional Commits: `type` or `type(scope): subject` with a lowercase subject (e.g. `fix(ios): healthkit snackbar shows settings hint`). CI rejects non-conforming titles.
+3. Use Cursor skills in `.cursor/skills/` — `/onboard-agent`, `/add-feature`, `/validate-change`, `/open-pr`.
+4. Never import `infrastructure/` from `features/` — use `shared/providers/`.
+5. Never import one feature's `providers/` from another feature.
+6. Keep hand-written files under ~250 lines; split into `presentation/widgets/`.
+7. Run `dart run tool/generate_codemap.dart` after structural changes.
+8. PR titles: Conventional Commits with lowercase subject — CI enforces this.
+
+## Key files
+
+- `lib/app/router.dart` — routes (`Routes` constants)
+- `lib/shared/providers/` — DI composition root
+- `docs/agents/file-templates.md` — scaffolds for new files

.cursor/rules/pr-workflow.md

@@ -0,0 +1,25 @@
+# PR workflow (always apply)
+
+A task is **not complete** until the PR is merged or explicitly closed.
+
+## Before opening
+
+Run `/validate-change` — all checks must pass including `flutter build web`.
+
+## PR requirements
+
+- Target: `main`
+- Title: Conventional Commits — `type` or `type(scope): subject`, lowercase subject
+- Branch (agents): `cursor/<descriptive-name>-d1bd`
+- Fill [.github/pull_request_template.md](../../.github/pull_request_template.md)
+- Attach visual proof for UI changes
+
+## After opening — mandatory
+
+1. Monitor review comments (humans, CodeRabbit, CI)
+2. Fix, push, re-validate
+3. Reply on each comment thread
+4. 👍 every addressed comment
+5. Do not abandon the PR
+
+Reference: [AGENTS.md §4](../../AGENTS.md#4-pull-request--review-process)

.cursor/skills/add-feature/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: add-feature
+description: Add a new feature vertical slice to KYNOS. Use when creating a new screen, tab, page, or feature folder under lib/features/.
+---
+
+# Add Feature
+
+## When to Use
+
+- "Add a feature", "new screen", "new tab", "new page"
+- Creating `lib/features/<name>/`
+
+## Checklist (AGENTS.md §17)
+
+1. **Page** — `lib/features/<name>/presentation/pages/<name>_page.dart`
+2. **Provider** — `lib/features/<name>/providers/<name>_provider.dart` (`@riverpod`)
+3. **Use-case** — `lib/domain/usecases/<name>/`
+4. **Repository interface** — `lib/domain/repositories/` (if new data source)
+5. **Entity** — `lib/domain/entities/` with `@freezed` (if needed)
+6. **Infrastructure impl** — `lib/infrastructure/` (if new platform integration)
+7. **DI provider** — `lib/shared/providers/` binding infra → Riverpod
+8. **Route** — register in `lib/app/router.dart` (`Routes` constant)
+9. **Tests** — unit test for use-case, widget smoke test for page
+10. **Codemap** — `dart run tool/generate_codemap.dart`
+
+## Scaffold Templates
+
+See [docs/agents/file-templates.md](../../docs/agents/file-templates.md).
+
+## UI Rules
+
+- Import design system: `package:kynos/core/theme/theme.dart`
+- Use `KynosCard`, `MetricTile`, `Gap(tokens.Spacing.*)` — never raw numbers
+- Loading: shimmer (`KynosLoadingLine`, `MetricTile(value: null)`), not spinners in cards
+
+## Validation
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+dart run tool/generate_codemap.dart
+flutter analyze
+flutter test
+flutter build web
+```

.cursor/skills/ai-isolate/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ai-isolate
+description: Work on KYNOS on-device AI inference and the background isolate bridge. Use when editing Gemma, LiteRT-LM, coach chat streaming, or AI repository code.
+paths:
+  - "lib/infrastructure/ai/**"
+  - "lib/features/coach_chat/**"
+  - "lib/shared/providers/ai*.dart"
+---
+
+# AI Isolate
+
+## When to Use
+
+- Editing AI inference, Gemma model loading, or coach chat streaming
+- Touching `ai_isolate_bridge.dart` or `IsolateAiCoachRepository`
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `lib/infrastructure/ai/gemma/ai_isolate_bridge.dart` | Isolate message protocol |
+| `lib/infrastructure/ai/isolate_ai_coach_repository.dart` | Repository impl |
+| `lib/domain/repositories/ai_coach_repository.dart` | Domain contract |
+| `lib/shared/providers/ai_repository_providers.dart` | DI binding |
+| `lib/core/constants/app_constants.dart` | RAM budgets, thermal thresholds |
+
+## Rules (AGENTS.md §10)
+
+- **All LLM inference runs in a Background Isolate** — never on the UI thread
+- Features access AI only via `AiCoachRepository` through `shared/providers/`
+- Thermal / RAM checks before loading model
+- UI streaming via `Stream` — avoid full-page rebuilds on each token
+
+## RAM Probe
+
+Use `GemmaDeviceRamProbe` via `ai_repository_providers.dart` export — features must not import infrastructure directly.
+
+## Validation
+
+```bash
+flutter analyze
+flutter test test/infrastructure/ai/
+flutter build web
+```
+
+See [docs/architecture/ai_isolate_design.md](../../docs/architecture/ai_isolate_design.md).

.cursor/skills/audits/audit-ai-isolate/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: audit-ai-isolate
+description: Audit KYNOS AI isolate bridge for memory leaks, streaming efficiency, and thermal handling. Explicit invocation only — use /audit-ai-isolate.
+disable-model-invocation: true
+---
+
+# Audit AI Isolate
+
+**Reference:** [docs/workflow_prompts.md §4](../../docs/workflow_prompts.md) · AGENTS.md §10
+
+## Instructions
+
+1. Review `lib/infrastructure/ai/gemma/ai_isolate_bridge.dart` for leak paths
+2. Verify isolate killed and port closed on `CoachChatPage` dispose
+3. Confirm token streaming uses `Stream` — no full-page rebuilds per token
+4. Check thermal/RAM gating before model load (`AppConstants`)
+5. Test OOM handling on <6GB RAM devices
+
+## Key Files
+
+- `ai_isolate_bridge.dart`
+- `isolate_ai_coach_repository.dart`
+- `docs/architecture/ai_isolate_design.md`
+
+## Proof of Work
+
+- Video: smooth streaming while scrolling UI
+- Isolate RAM consumption log during inference

.cursor/skills/audits/audit-architecture/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: audit-architecture
+description: Audit KYNOS Clean Architecture layer imports and domain purity. Explicit invocation only — use /audit-architecture for recurring architecture integrity checks.
+disable-model-invocation: true
+---
+
+# Audit Architecture
+
+**Reference:** [docs/workflow_prompts.md §1](../../docs/workflow_prompts.md) · AGENTS.md §5
+
+## Instructions
+
+1. Run `bash scripts/check_architecture.sh`
+2. Grep `lib/features/` for `package:kynos/infrastructure/` imports
+3. Grep `lib/domain/` for `package:flutter`, `flutter_riverpod`, `riverpod`
+4. Grep `lib/features/` for cross-feature `providers/` imports
+5. Identify files >250 lines in CODEMAP hot files section
+6. Fix violations: extract to use-cases, move DI to `shared/providers/`
+
+## Proof of Work
+
+- `flutter analyze` — 0 issues
+- `bash scripts/check_architecture.sh` — passes
+- List of violations found and fixed (or confirm clean)

.cursor/skills/audits/audit-biomechanics/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: audit-biomechanics
+description: Audit KYNOS biomechanics regression model for numerical stability and cold-start handling. Explicit invocation only — use /audit-biomechanics.
+disable-model-invocation: true
+---
+
+# Audit Biomechanics
+
+**Reference:** [docs/workflow_prompts.md §8](../../docs/workflow_prompts.md)
+
+## Instructions
+
+1. Check multivariate regression for collinearity (cadence vs power)
+2. Verify β-coefficient persistence via Protocol Buffers (atomic save/load)
+3. Implement or verify confidence score for stride length prediction
+4. Handle cold start (1–2 data points) gracefully
+5. Ensure regression math is pure Dart (isolate-safe)
+
+## Proof of Work
+
+- Unit test: OLS prediction vs reference dataset
+- Screenshot: Nexus Lab showing β-coefficients and confidence

.cursor/skills/audits/audit-dart-modernization/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: audit-dart-modernization
+description: Audit KYNOS for modern Dart 3 patterns, lint upgrades, and build_runner optimization. Explicit invocation only — use /audit-dart-modernization.
+disable-model-invocation: true
+---
+
+# Audit Dart Modernization
+
+**Reference:** [docs/workflow_prompts.md §10](../../docs/workflow_prompts.md)
+
+## Instructions
+
+1. Review `analysis_options.yaml` — enable `strict-casts`, `unawaited_futures` if safe
+2. Replace legacy patterns with pattern matching on sealed `Failure` classes
+3. Use records where they simplify repository return types
+4. Optimize `build.yaml` to reduce `build_runner` scan scope
+5. Remove deprecated plugin/API usage
+
+## Proof of Work
+
+- `flutter analyze` clean with any new strict rules
+- Before/after snippet showing idiomatic Dart 3 refactor

.cursor/skills/audits/audit-documentation/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: audit-documentation
+description: Audit KYNOS documentation for drift against code and generate ADRs when needed. Explicit invocation only — use /audit-documentation.
+disable-model-invocation: true
+---
+
+# Audit Documentation
+
+**Reference:** [docs/workflow_prompts.md §9](../../docs/workflow_prompts.md)
+
+## Instructions
+
+1. Read `docs/architecture/*.md` and compare to actual `lib/` code
+2. Verify isolate protocol docs match `ai_isolate_bridge.dart`
+3. Check AGENTS.md §17, CODEMAP, and folder_structure.md for consistency
+4. Generate ADR (`docs/architecture/adr-XXX.md`) for significant decisions
+5. Audit DartDoc on public `domain/` APIs
+
+## Proof of Work
+
+- Report on doc/code drift items found and fixed
+- New or updated ADR if applicable
+- Run `dart run tool/generate_codemap.dart` if structure changed

.cursor/skills/audits/audit-health-data/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: audit-health-data
+description: Audit KYNOS health data aggregation, normalization, and empty-state UX. Explicit invocation only — use /audit-health-data.
+disable-model-invocation: true
+---
+
+# Audit Health Data
+
+**Reference:** [docs/workflow_prompts.md §7](../../docs/workflow_prompts.md)
+
+## Instructions
+
+1. Review `HealthKitRepository` sleep segment aggregation across midnight
+2. Verify HRV (SDNN) normalization for AI coach context
+3. Test permission-denied and zero-data empty states
+4. Confirm sealed `Failure` hierarchy for errors (AGENTS.md §9)
+5. Add unit tests for split sleep, DST edge cases
+
+## Proof of Work
+
+- Unit tests for complex data scenarios
+- Screenshot: dashboard empty state or permission UI

.cursor/skills/audits/audit-performance/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: audit-performance
+description: Audit KYNOS for 120Hz jank, unnecessary rebuilds, and GPU overdraw. Explicit invocation only — use /audit-performance.
+disable-model-invocation: true
+---
+
+# Audit Performance
+
+**Reference:** [docs/workflow_prompts.md §2](../../../../docs/workflow_prompts.md) · AGENTS.md §14
+
+## Instructions
+
+1. Analyze `DashboardPage`, `NexusLab`, lists for rebuild triggers
+2. Ensure `ref.select` for granular provider subscriptions (e.g. `hrvMs` not whole `HealthSummary`)
+3. Check `GlassCard` / `BackdropFilter` overdraw when multiple glass cards visible
+4. Add `const` constructors and `RepaintBoundary` where appropriate
+5. Verify `ListView.builder` for long lists
+
+## Targets
+
+- Frame budget: 8.3ms at 120Hz
+- No full-page rebuilds on streaming AI tokens
+
+## Proof of Work
+
+- Screen recording with Performance Overlay (bars below 8.3ms)
+- Optimization log: widgets converted to `const` or `ref.select`

.cursor/skills/audits/audit-privacy/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: audit-privacy
+description: Audit KYNOS for Zero-Knowledge privacy violations and biometric data leaks. Explicit invocation only — use /audit-privacy.
+disable-model-invocation: true
+---
+
+# Audit Privacy
+
+**Reference:** [docs/workflow_prompts.md §3](../../../../docs/workflow_prompts.md) · AGENTS.md §11
+
+## Instructions
+
+1. Scan for `print()`, `debugPrint()`, `logger` with health/biometric objects
+2. Grep sensitive field names in log statements: `hrvMs`, `rhrBpm`, `HealthSummary`, etc.
+3. Trace data path from `HealthKitRepository` to UI — no network interceptors capturing biometrics
+4. Verify `AppConstants.zeroKnowledgeMode == true`
+5. Confirm export flows are user-initiated only
+
+## Commands
+
+```bash
+# Single-line logger calls with sensitive payloads
+rg 'logger\.(d|i|w|e|f)\(.*(HealthSummary|hrvMs|rhrBpm)' lib/
+
+# Multi-line logger calls (e.g. named arguments split across lines)
+rg -U 'logger\.(d|i|w|e|f)\([\s\S]*?(HealthSummary|hrvMs|rhrBpm)' lib/
+
+rg 'print\(|debugPrint\(' lib/
+```
+
+## Proof of Work
+
+- Clean ripgrep report
+- `zeroKnowledgeMode` confirmed true