OSCortex: stock Flutter renders + fully interactive shell + app launch on bare metal

.agents/rules/oscortex-core.md

@@ -0,0 +1,35 @@
+---
+description: OSCortex core rules — target architecture, one path, no duplicate tooling, exclude landing/
+alwaysApply: true
+---
+
+# OSCortex
+
+Read **docs/arch.txt**, **docs/hardware.txt**, **docs/ci-cd.txt**, and project skills before structural work:
+
+- `.agents/skills/oscortex-architecture/SKILL.md`
+- `.agents/skills/oscortex-hardware/SKILL.md` (drivers, display, input, device classes)
+- `.agents/skills/oscortex-kernel-tests/SKILL.md` (driver unit + QEMU integration tests)
+- `.agents/skills/oscortex-ci-cd/SKILL.md` (branching, PRs, CI, release to main)
+- `.agents/skills/codebase-audit-cleanup/SKILL.md`
+- `.agents/skills/frontend-design/SKILL.md` (creative, premium frontend layouts and web interface designs)
+
+## Architecture
+
+- Kernel: hardware, compositor, focus, syscalls.
+- Flutter: shell, WM chrome, apps — **one process per app**, own engine instance.
+- PID 1: thin init/supervisor — not widgets, not all apps in one address space.
+- Apps: runtime install (`.osx`), not ISO reflash from `apps/*`.
+- Hardware: see **docs/hardware.txt** — syscalls only to userspace; one render path; drivers per device class.
+
+## Code rules
+
+- **One canonical path** — on pivot, delete old code/files; no dual boot or render stacks.
+- **Reuse** — extend existing modules; do not duplicate patch/embedder/syscall logic.
+- **Engine patches** — only `tools/flutter-engine/engine_patch.py`.
+- **Exclude** `landing/` unless the user explicitly asks.
+
+## Cleanup triggers
+
+Before large features or when the user mentions bloat/redundancy/pivot: run the codebase-audit-cleanup skill (Phase 1 scan → delete/consolidate → verify harness + build).
+

.agents/skills/codebase-audit-cleanup/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: codebase-audit-cleanup
+description: >
+  Audit and clean OSCortex for redundancy, AI slop, dead pivots, and missing reusability.
+  Trigger on: cleanup, audit, duplicate code, technical debt, refactor, bloat, pivot,
+  remove old code, one path, code reusability, or before large features. Excludes landing/.
+---
+
+# Codebase Audit & Cleanup (OSCortex)
+
+Systematically find duplicate logic, orphaned scripts, dual code paths, and boot/render junk — then delete or consolidate. **An OS cannot carry parallel implementations.**
+
+**Also read:** [oscortex-architecture](../oscortex-architecture/SKILL.md) · [oscortex-hardware](../oscortex-hardware/SKILL.md) · [docs/arch.txt](../../../docs/arch.txt) · [docs/hardware.txt](../../../docs/hardware.txt)
+
+**Exclude from all scans and edits:** `landing/`
+
+---
+
+## Core philosophy
+
+AI generates code in isolation. On OSCortex this becomes:
+
+- **Duplicate patch scripts** — `scratch/patch_*.py` next to `engine_patch.py`
+- **Pivoted apps** — `main_minimal.dart`, `.bak`, alternate shells
+- **Dual boot/render paths** — kernel demos + Flutter; FB_BYPASS hacks; moving test boxes
+- **God files** — single modules doing entire syscall domains
+- **Orphan harnesses** — one-off debug scripts never wired to CI
+
+**Rule:** One canonical way per concern. On pivot, **delete the old way** — do not comment it out “for reference.”
+
+---
+
+## OSCortex canonical locations (do not duplicate)
+
+| Concern | Canonical location |
+|---------|---------------------|
+| Engine patches | `tools/flutter-engine/engine_patch.py` |
+| Patch verification | `harness/verify_engine_patches.py` |
+| ISO build | `scripts/build-iso.sh` |
+| Embedder | `tools/flutter-embedder/` |
+| Architecture | `docs/arch.txt` |
+| Hardware / drivers | `docs/hardware.txt` |
+| Driver init | `kernel/src/drivers/platform.rs` |
+| Driver unit tests | `tests/kernel/` · `kernel/src/drivers/common/` |
+| Driver QEMU integration | `tests/integration/qemu_drivers.sh` |
+| PCI / port I/O | `kernel/src/arch/pci.rs`, `kernel/src/arch/port_io.rs` |
+| Syscall ABI | `kernel/src/embedder/abi.rs` |
+| Native drivers | `kernel/src/drivers/` |
+| Compositor / display | `kernel/src/compositor/` |
+| CDP WASM drivers | `kernel/src/cortex/driver_gen.rs` |
+| CPU porting | `kernel/src/arch/` |
+| System shell app | `apps/oscortex_app/` |
+
+If you find logic elsewhere that belongs here → **move or merge**, then **delete** the duplicate.
+
+---
+
+## Phase 1: Automated scan (OSCortex)
+
+Run from repo root. Adapt extensions for Rust/Dart/Python/sh.
+
+```bash
+# 1A — largest files (god-file candidates)
+find . -type f \( -name "*.rs" -o -name "*.dart" -o -name "*.py" -o -name "*.sh" \) \
+  ! -path "./.git/*" ! -path "./target/*" ! -path "./build/*" ! -path "./landing/*" \
+  | xargs wc -l 2>/dev/null | sort -rn | head -35
+
+# 1B — debt markers
+grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|WORKAROUND" \
+  --include="*.rs" --include="*.dart" --include="*.py" --include="*.sh" . \
+  | grep -v "./.git" | grep -v "./landing"
+
+# 1C — duplicate / orphan tooling
+find scratch -type f 2>/dev/null
+find . -name "*.bak" -o -name "*_minimal.*" -o -name "*.bak_*" 2>/dev/null | grep -v landing
+
+# 1D — references to deleted or legacy paths
+grep -rn "scratch/\|userspace/init\|main_minimal\|STRICT_ENGINE_MODE\|early_banner\|early_probe\|test.red\|test_red" \
+  --include="*.rs" --include="*.dart" --include="*.py" --include="*.sh" . \
+  | grep -v "./.git" | grep -v "./landing"
+
+# 1E — Rust unused / warnings
+cd kernel && cargo check 2>&1 | grep -E "warning:|unused"
+
+# 1F — duplicate engine patch entry points
+grep -rn "va_to_file\|0x196e300\|patch_engine" --include="*.py" . | grep -v engine_patch.py
+```
+
+---
+
+## Phase 2: Manual checklist (score 0–3)
+
+### Single path
+- [ ] Only one boot userspace stack documented in `docs/arch.txt`?
+- [ ] Only one render path (Flutter → compositor) per `docs/hardware.txt`?
+- [ ] No duplicate driver or MMIO paths in embedder/userspace?
+- [ ] Only one engine patch script?
+- [ ] No kernel boot splash/demo surfaces before Flutter presents?
+- [ ] No second Dart entry (`main_minimal`, `.bak`) for the same app?
+
+### Reusability
+- [ ] New syscall logic in focused modules under `kernel/src/syscall/`, not a new god file?
+- [ ] Shared ELF/AOT parsing not copied embedder ↔ kernel?
+- [ ] Build scripts call canonical tools, not inline duplicate patch bytes?
+
+### Pivot hygiene
+- [ ] Old approach files **deleted**, not deprecated in place?
+- [ ] Docs updated when architecture changes (`docs/arch.txt`)?
+
+---
+
+## Phase 3: Audit report template
+
+```markdown
+# Codebase Audit Report — OSCortex — [Date]
+
+## Summary
+- Files scanned: X
+- Critical / High / Medium counts
+
+## Critical (fix before features)
+| Issue | Location | Action | Effort |
+
+## Deleted this pass
+| Path | Reason |
+
+## Consolidated this pass
+| From | To |
+
+## Remaining (prioritized)
+...
+```
+
+---
+
+## Phase 4: Harness
+
+Before/after refactors:
+
+```bash
+python3 harness/verify_engine_patches.py
+cd kernel && cargo build --release
+bash scripts/build-iso.sh   # when boot/render touched
+```
+
+One module per change. Re-run harness after each.
+
+---
+
+## Phase 5: Cleanup order
+
+1. **Dead files** — scratch orphans, `.bak`, pivoted duplicates, stale HANDOFF docs
+2. **Boot/render junk** — kernel demos, fallback surfaces, verbose embedder logs
+3. **Consolidate tooling** — patches, blob hash, verify scripts
+4. **Split god modules** — syscall domains, compositor vs WM
+5. **Architecture alignment** — remove paths that violate process isolation model
+
+---
+
+## Prompt template for AI cleanup tasks
+
+```
+AUDIT FINDING: [specific finding]
+
+CANONICAL TARGET: [path or pattern from table above]
+
+TASK:
+- Consolidate or delete redundant code
+- Do not leave dual paths
+- Update docs/arch.txt if behavior/arch changed
+- Exclude landing/
+
+VERIFY:
+python3 harness/verify_engine_patches.py
+cargo build --release (if kernel touched)
+```
+
+---
+
+## Reference
+
+- Smell catalog and generic scan commands: [references/smell-catalog.md](references/smell-catalog.md)
+- Language scan commands: [references/scan-commands.md](references/scan-commands.md)

.agents/skills/codebase-audit-cleanup/references/scan-commands.md

@@ -0,0 +1,54 @@
+# Scan Commands — OSCortex
+
+Run from repo root. Always exclude `./landing/` and `./.git/`.
+
+## Universal
+
+```bash
+find . -type f \( -name "*.rs" -o -name "*.dart" -o -name "*.py" -o -name "*.sh" \) \
+  ! -path "./.git/*" ! -path "./target/*" ! -path "./build/*" ! -path "./landing/*" \
+  | xargs wc -l 2>/dev/null | sort -rn | head -40
+
+grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|WORKAROUND" \
+  --include="*.rs" --include="*.dart" --include="*.py" --include="*.sh" . \
+  | grep -v "./.git" | grep -v "./landing"
+```
+
+## Rust (kernel / embedder)
+
+```bash
+cd kernel && cargo check 2>&1 | grep -E "warning:|unused"
+cd kernel && cargo clippy -- -W dead_code 2>&1 | head -40
+grep -rn "todo!\(\)\|unimplemented!\(\)" kernel/ tools/flutter-embedder/
+```
+
+## Dart / Flutter
+
+```bash
+find apps -name "*.dart" ! -path "*/landing/*"
+grep -rn "print(" apps/ --include="*.dart"
+```
+
+## Python (engine tooling)
+
+```bash
+grep -rn "def va_to_file\|PATCHES\[" tools/ --include="*.py"
+python3 harness/verify_engine_patches.py
+```
+
+## Quick audit script
+
+```bash
+bash -c '
+echo "=== OSCortex Quick Audit ==="
+echo "--- Top files ---"
+find . -type f \( -name "*.rs" -o -name "*.dart" -o -name "*.py" \) \
+  ! -path "./.git/*" ! -path "./target/*" ! -path "./landing/*" \
+  | xargs wc -l 2>/dev/null | sort -rn | head -15
+echo "--- scratch ---"
+ls scratch 2>/dev/null || echo "(none)"
+echo "--- debt markers ---"
+grep -rn "TODO\|FIXME\|HACK" --include="*.rs" --include="*.dart" . \
+  | grep -v "./.git" | grep -v "./landing" | wc -l
+'
+```

.agents/skills/codebase-audit-cleanup/references/smell-catalog.md

@@ -0,0 +1,20 @@
+# AI-Generated Code Smell Catalog (OSCortex)
+
+Use during Phase 2 manual audit.
+
+## OSCortex-specific smells
+
+| Smell | Example | Fix |
+|-------|---------|-----|
+| Scratch sprawl | `scratch/patch_engine.py` | Merge into `engine_patch.py`, delete scratch |
+| Pivot shadow | `main_minimal.dart`, `userspace/init/` | Delete; one shell entry |
+| Boot demo layer | kernel grid/banner/moving box before Flutter | Delete; compositor waits for real surface |
+| Same-PID app launch | `app_launch` → isolate in shell PID | Target: spawn app host process (see arch.txt) |
+| ISO app catalog | `apps/*` loop baking user apps into image | Shell only in ISO; runtime `app_install` |
+| Diagnostic permanence | `[embedder]` spam, `present_callback` p0 logs | Remove after fix verified once |
+
+## Generic smells (still apply)
+
+See conversation skill source for: Utility Sprawl, Copy-Paste Validation, Parallel Interfaces, Magic Strings, God Utility File, Dead Feature Shadows, Error Handling Chaos.
+
+**Severity:** Copy-paste tooling and dual boot paths are **Critical** on an OS — they cause wrong-runtime behavior, not just style issues.

.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.