diff --git a/.agents/rules/oscortex-core.md b/.agents/rules/oscortex-core.md new file mode 100644 index 0000000..0697544 --- /dev/null +++ b/.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). + diff --git a/.agents/skills/codebase-audit-cleanup/SKILL.md b/.agents/skills/codebase-audit-cleanup/SKILL.md new file mode 100644 index 0000000..21b3a15 --- /dev/null +++ b/.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) diff --git a/.agents/skills/codebase-audit-cleanup/references/scan-commands.md b/.agents/skills/codebase-audit-cleanup/references/scan-commands.md new file mode 100644 index 0000000..1520591 --- /dev/null +++ b/.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 +' +``` diff --git a/.agents/skills/codebase-audit-cleanup/references/smell-catalog.md b/.agents/skills/codebase-audit-cleanup/references/smell-catalog.md new file mode 100644 index 0000000..c495e6a --- /dev/null +++ b/.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. diff --git a/.agents/skills/frontend-design/SKILL.md b/.agents/skills/frontend-design/SKILL.md new file mode 100644 index 0000000..7c15181 --- /dev/null +++ b/.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. diff --git a/.agents/skills/oscortex-a2ui-compliance/SKILL.md b/.agents/skills/oscortex-a2ui-compliance/SKILL.md new file mode 100644 index 0000000..df9c40c --- /dev/null +++ b/.agents/skills/oscortex-a2ui-compliance/SKILL.md @@ -0,0 +1,119 @@ +--- +name: oscortex-a2ui-compliance +description: > + Enforce A2UI protocol compliance for all OSCortex UI components. + Trigger when: adding a new Osc* widget, creating a new interactive component, + modifying the oscortex_ui package, or any question about A2UI support. + Ensures every new component has an A2UI renderer mapping and is exported correctly. +--- + +# OSCortex A2UI Compliance + +## Purpose + +Every interactive or container component in the `oscortex_ui` package **MUST** have +a corresponding A2UI renderer mapping so that AI agents can compose UI declaratively. + +## Rules + +### 1. No Material UI in Interactive Components + +OSCortex is its own OS — **never** use these Material widgets for interactive/container components: + +| ❌ FORBIDDEN Material Widget | ✅ Use Instead | +|------------------------------|----------------| +| `Checkbox` | `OscCheckbox` | +| `Slider` | `OscSlider` | +| `showDatePicker()` | `OscDatePicker` | +| `Dialog` / `AlertDialog` | `OscModal` | +| `TabBar` / `TabBarView` | `OscTabs` | +| `DropdownButton` | `OscPopupMenu` | +| `Switch` | Build `OscSwitch` | +| `Radio` | Build `OscRadio` | +| `SnackBar` / `ScaffoldMessenger` | `OscBanner` | +| `BottomSheet` | Build `OscSheet` | +| `AppBar` | `OscToolbar` | +| `NavigationRail` | `OscAppRail` | +| `FloatingActionButton` | `OscButton` | +| `Chip` / `InputChip` / `FilterChip` | `OscChip` / `OscTag` | + +**Passthrough OK** — these carry no design language and may be used directly: +- `Row`, `Column`, `Flex`, `Stack`, `Wrap` +- `ListView`, `GridView`, `SingleChildScrollView` +- `Text`, `RichText`, `Image.network`, `Image.asset` +- `Icon` (with `A2UIIcons` mapping) +- `Container`, `SizedBox`, `Padding`, `Center`, `Align` +- `GestureDetector`, `MouseRegion`, `AnimatedContainer` +- `ClipRRect`, `BackdropFilter`, `Opacity` + +### 2. New Component Checklist + +When adding a new `Osc*` widget to the package, you **MUST** complete ALL of these: + +- [ ] **Create the widget** in `packages/oscortex_ui/lib/src/widgets/osc_.dart` +- [ ] **Add `@OscPreview` annotations** with at least 2 preview functions +- [ ] **Export in barrel** — add to `lib/oscortex_ui.dart` +- [ ] **Map in A2UI renderer** — add a case in `a2ui_renderer.dart` `_renderComponent()` +- [ ] **Add A2UI component type** — add enum value in `a2ui_types.dart` if new +- [ ] **Add parser support** — handle in `a2ui_parser.dart` `_parseType()` and `_parseProps()` +- [ ] **Run `flutter analyze`** on `packages/oscortex_ui` — must be 0 issues + +### 3. A2UI Renderer Architecture + +``` +packages/oscortex_ui/lib/src/ +├── a2ui/ +│ ├── a2ui.dart ← barrel export +│ ├── a2ui_types.dart ← Component, BoundValue, Action, Surface +│ ├── a2ui_parser.dart ← JSON → A2UISurface (v0.8 + v0.9) +│ ├── a2ui_data_store.dart ← Reactive path-based data binding +│ ├── a2ui_icons.dart ← Icon name → Material IconData +│ ├── a2ui_renderer.dart ← Component → Osc* widget mapping +│ └── a2ui_surface.dart ← Top-level JSON → UI widget +└── widgets/ + ├── osc_button.dart ← A2UI Button + ├── osc_checkbox.dart ← A2UI CheckBox + ├── osc_slider.dart ← A2UI Slider + ├── osc_date_picker.dart ← A2UI DateTimeInput + ├── osc_modal.dart ← A2UI Modal + ├── osc_tabs.dart ← A2UI Tabs + ├── osc_text_field.dart ← A2UI TextField + ├── osc_card.dart ← A2UI Card + ├── osc_chip.dart ← A2UI MultipleChoice/ChoicePicker + └── ... ← All other Osc* widgets +``` + +### 4. Current A2UI Component Support + +| A2UI Component | Osc* Widget | Status | +|--------------------|------------------|--------| +| Row | Row (passthrough) | ✅ | +| Column | Column (passthrough) | ✅ | +| List | ListView (passthrough) | ✅ | +| Text | Text + OscTypography | ✅ | +| Image | Image.network (passthrough) | ✅ | +| Icon | A2UIIcons → Icon | ✅ | +| Divider | Container (passthrough) | ✅ | +| Button | OscButton / OscOutlineButton | ✅ | +| TextField | OscTextField | ✅ | +| CheckBox | OscCheckbox | ✅ | +| Slider | OscSlider | ✅ | +| DateTimeInput | OscDatePicker | ✅ | +| MultipleChoice | OscChip | ✅ | +| Card | OscCard | ✅ | +| Modal | OscModal | ✅ | +| Tabs | OscTabs | ✅ | + +### 5. Testing + +After any changes: + +```bash +cd packages/oscortex_ui && flutter analyze +cd apps/oscortex_app && flutter analyze +cd apps/oscortex_files && flutter analyze +cd apps/oscortex_canvas && flutter analyze +cd apps/oscortex_web_link && flutter analyze +``` + +All must report **0 issues**. diff --git a/.agents/skills/oscortex-architecture/SKILL.md b/.agents/skills/oscortex-architecture/SKILL.md new file mode 100644 index 0000000..c184f61 --- /dev/null +++ b/.agents/skills/oscortex-architecture/SKILL.md @@ -0,0 +1,102 @@ +--- +name: oscortex-architecture +description: > + Canonical OSCortex OS architecture — kernel vs Flutter userspace, process isolation, + shell vs apps, runtime install model. Use when designing features, refactoring boot/app + launch, writing docs, or any question about how OSCortex should work (not legacy hacks). +--- + +# OSCortex Architecture + +**Read first:** [docs/arch.txt](../../../docs/arch.txt) · [docs/hardware.txt](../../../docs/hardware.txt) + +**Out of scope:** `landing/` — never modify unless explicitly requested. + +--- + +## One-sentence model + +**Kernel owns hardware and policy. Flutter owns everything above the kernel — window management, shell, and applications — with one hard rule: each runnable unit that can crash is its own process.** + +--- + +## Layers + +``` +USER APPS (Flutter) — one process per app, own engine instance, own surface(s) +SYSTEM SHELL / WM (Flutter) — one system process; launcher, desktop, chrome, gen UI +INIT / SUPERVISOR — PID 1; boot, spawn/stop/restart, reap zombies; NOT the widget tree +KERNEL — scheduler, memory, IPC, drivers, compositor, focus, syscalls +``` + +--- + +## Non-negotiable rules + +1. **Process isolation** — user apps never share an address space with the shell or each other. +2. **Failure containment** — one app crash must not take down shell, init, or other apps. +3. **One render path** — every pixel via Flutter engine → surface → kernel compositor. No parallel shells or demo/fallback render paths left in tree. +4. **Runtime install** — apps ship as built AOT bundles (`.osx`); installed on a running OS via syscalls. **Not** “add to `apps/`, rebuild ISO, reflash.” +5. **System apps** — shell and core system UI are uninstallable; still **separate processes**, not merged into PID 1. +6. **Pivot = delete** — when architecture or approach changes, remove the old path entirely. No dual boot stacks, no “legacy for now.” + +--- + +## App lifecycle (product) + +| Step | Where | +|------|--------| +| Dev build | Flutter project → AOT artifact (pack tool → `.osx`) | +| Install | `app_install` syscall → persistent storage | +| Launch | spawn **new app host process** (embedder + engine + that app's AOT) | +| Uninstall | `app_uninstall` (reject for system apps) | +| List | `app_list` / platform channel for shell store UI | + +--- + +## Kernel vs Flutter boundary + +| Kernel | Flutter userspace | +|--------|-------------------| +| Compositor, surface table, z-order | Widgets, layout, window chrome (Dart) | +| Focus, hit-testing, input routing | Pointer/key handling inside engine | +| `surface_create` / `present` / flip | `present_callback` → pixels | +| Process spawn, mmap, capabilities | App logic, platform channels | +| Drivers, compositor blit, input HW | Never maps MMIO / PCI from userspace | + +**Hardware detail:** [docs/hardware.txt](../../../docs/hardware.txt) · skill `oscortex-hardware` + +--- + +## Hardware (summary) + +- **One render path:** Flutter → `gpu_submit_strided` → compositor → framebuffer (CPU blit today). +- **`gpu_submit` ≠ GPU vendor driver** — pixel copy into surfaces; real GPU is a future compositor backend. +- **Each device class** (audio, touchpad, storage, …) needs its own kernel driver; APIs are shared via syscalls. +- **Multi-arch:** port CPU in `kernel/src/arch/`; drivers per platform; CDP WASM portable across ISAs. + +--- + +## Canonical paths + +| Path | Role | +|------|------| +| `kernel/` | Kernel — compositor, WM events, syscalls, process model | +| `tools/flutter-embedder/` | Flutter host binary (`oscortex-host`) | +| `tools/flutter-engine/engine_patch.py` | **Only** engine patch entry point | +| `apps/oscortex_app/` | System shell source (not an app manager holding all apps) | +| `scripts/build-iso.sh` | ISO build — ships kernel, init, engine, shell; not user app catalog | +| `docs/arch.txt` | Canonical architecture document | +| `docs/hardware.txt` | Drivers, display, device classes, CDP | +| `.agents/skills/oscortex-hardware/SKILL.md` | Agent guide for driver/hardware work | +| `.agents/skills/oscortex-ci-cd/SKILL.md` | Branching, PRs, CI, release to main | + +--- + +## When implementing + +- Align new code with **target architecture** in `docs/arch.txt`, not temporary bring-up shortcuts. +- Do not add isolate-in-PID-1 launches for user apps. +- Do not add kernel boot demos, grid splashes, synthetic cursors, or compositor placeholders. +- Extend existing modules; do not duplicate embedder/patch/syscall logic in new files. + diff --git a/.agents/skills/oscortex-ci-cd/SKILL.md b/.agents/skills/oscortex-ci-cd/SKILL.md new file mode 100644 index 0000000..8ab3c20 --- /dev/null +++ b/.agents/skills/oscortex-ci-cd/SKILL.md @@ -0,0 +1,234 @@ +--- +name: oscortex-ci-cd +description: > + OSCortex Git branching, CI gates, PR compliance, and production release flow. + Use when committing, pushing, opening PRs, merging to develop/main, releasing + ISOs, setting up GitHub Actions, or any question about which branch to work on. +--- + +# OSCortex CI/CD & Branching + +**Read first:** [docs/ci-cd.txt](../../../docs/ci-cd.txt) · [.github/pull_request_template.md](../../../.github/pull_request_template.md) + +**Related skills:** [oscortex-architecture](../oscortex-architecture/SKILL.md) · [oscortex-kernel-tests](../oscortex-kernel-tests/SKILL.md) + +**Repo:** `DotCorr/oscortex` · default branch: **`develop`** · production: **`main`** + +--- + +## One-sentence model + +**All code starts on `feature/*`; merges to `develop` only after green CI + human PR review (light gate); ships to `main` only after a separate release PR + stricter human review (heavy gate) — then auto `vX.Y.Z` + ISO.** + +--- + +## Three-tier promotion (memorize) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ TIER 1 — WORK feature/* fix/* │ +│ Where agents & devs edit code. Push freely to remote feat/*. │ +└───────────────────────────────┬─────────────────────────────────┘ + │ PR → develop + │ ✅ CI green (required) + │ ✅ Human clicks Merge (light review) + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ TIER 2 — INTEGRATE develop (default branch) │ +│ Integration / next release. NEVER push directly. │ +│ Lighter protection: CI + PR + any write-access reviewer. │ +└───────────────────────────────┬─────────────────────────────────┘ + │ Release PR → main (explicit only) + │ ✅ CI green (required) + │ ✅ CODEOWNERS + human release review (strict) + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ TIER 3 — PRODUCTION main │ +│ Shipped code only. NEVER push directly. NEVER agent-merge. │ +│ Merge triggers release.yml → vX.Y.Z + oscortex ISO. │ +└─────────────────────────────────────────────────────────────────┘ +``` + +| Tier | Branch | Who edits | How code arrives | Merge who | Gate weight | +|------|--------|-----------|------------------|-----------|-------------| +| 1 | `feature/*`, `fix/*` | Agents + devs | `git push origin feat/...` | — | None (open) | +| 2 | `develop` | Nobody direct | PR from `feature/*` | **Human** on GitHub | **Light** — CI + 1 review | +| 3 | `main` | Nobody direct | Release PR from `develop` | **Human** on GitHub | **Strict** — CI + CODEOWNERS review | + +**Agents never merge PRs and never push to `develop` or `main`** unless the user explicitly asks for a specific merge/push command. + +--- + +## Tier 1 — Feature branch workflow (default for all work) + +### Start + +```bash +git fetch origin +git checkout develop && git pull origin develop # sync integration base +git checkout -b feat/short-description # ALWAYS branch for new work +``` + +Work and commit on `feat/*` (or locally on `develop`, then publish — see below). + +### Publish (never `git push origin develop`) + +```bash +git push -u origin feat/short-description +gh pr create --base develop --head feat/short-description \ + --title "..." --body "..." # fill PR template checklist +``` + +Direct push to `develop` **always fails** (`GH006: Protected branch update failed`). That is correct. + +### Before asking human to merge + +Run locally (same as required CI): + +```bash +bash tests/run_all.sh +cd apps/oscortex_app && flutter analyze && flutter test +gh pr checks # both required jobs must pass +``` + +Then **stop**. Tell the user: PR is ready for their manual merge into `develop`. + +--- + +## Tier 2 — develop (light gate) + +**Purpose:** Integration branch — always green, holds the next release. + +**Protection (light):** +- PR required — no direct pushes +- Required CI: `Kernel build + unit tests`, `Flutter shell analyze + test` +- 1 approving review (any reviewer with write access) +- CODEOWNERS **not** required on develop PRs (faster iteration) +- Linear history, branch must be up to date + +**Human merge only:** After CI is green and reviewer approves, a **person** merges on GitHub. Agents do not click Merge. + +**After merge:** delete or abandon the feature branch; pull `develop` locally: + +```bash +git checkout develop && git pull origin develop +``` + +--- + +## Tier 3 — main / production (strict gate) + +**Purpose:** Exactly what has shipped. Every merge auto-releases. + +**Protection (strict):** +- PR required — release PRs only (`develop` → `main`) +- Same required CI checks must pass on the release PR +- **CODEOWNERS review required** (`.github/CODEOWNERS`) +- 1+ approving review — treat as a release sign-off, not a rubber stamp +- Linear history, no force-push + +**Human merge only:** Only when the user explicitly requests a production release: + +```bash +gh pr create --base main --head develop \ + --title "Release: v0.0.x" --body "Release notes..." +# Human reviews + merges → release.yml → vX.Y.Z + oscortex-vX.Y.Z.iso +``` + +Agents **must not** open or merge release PRs unless the user explicitly asks. + +**On merge to `main`:** `release.yml` patch-bumps tag, builds `cargo xtask iso`, publishes GitHub Release. + +--- + +## CI checks (both tiers 2 and 3) + +**Workflow:** `.github/workflows/ci.yml` + +| Job | Required for merge? | Local command | +|-----|---------------------|---------------| +| Kernel build + unit tests | ✅ | `bash tests/run_all.sh` | +| Flutter shell analyze + test | ✅ | `cd apps/oscortex_app && flutter analyze && flutter test` | +| rustfmt + clippy (advisory) | ⚠️ reports only | `cargo fmt --all --check` | + +--- + +## Agent rules (non-negotiable) + +1. **Always work on `feature/*`** (branch off `develop`) for new changes. +2. **Never `git push origin develop`** or **`git push origin main`**. +3. **Never merge PRs** — prepare PR, verify CI, hand off to human. +4. **Never open `develop` → `main` release PR** unless user explicitly requests production ship. +5. **Commit only when user asks** (repo rule); when they do, publish via `feat/*` + PR to `develop`. +6. Fill [.github/pull_request_template.md](../../../.github/pull_request_template.md) on every PR. + +--- + +## PR compliance checklist + +- One canonical path — delete old code on pivot +- Hardware in kernel only; Flutter via syscalls +- Reuse existing modules; `engine_patch.py` only for engine patches +- No `landing/` changes +- Verification: `tests/run_all.sh`, analyze/test as applicable + +--- + +## Hotfix (production emergency) + +``` +fix/* ← branch from main + │ PR → main (strict gate + human merge → immediate release) + ▼ +back-merge into develop (PR, so fix is not lost) +``` + +--- + +## Common mistakes + +| Mistake | Why it fails | Correct action | +|---------|--------------|----------------| +| `git push origin develop` | Protected branch | `git push origin feat/...` + PR | +| Agent merges PR | Policy — human gate | Notify user PR is ready | +| Work on `main` | Production only | `git checkout develop` → `feat/*` | +| Skip CI before merge | Branch protection blocks | Fix failures, re-push feat branch | +| Release without user ask | Prod is deliberate | Wait for explicit release request | + +--- + +## Key paths + +| Path | Role | +|------|------| +| `docs/ci-cd.txt` | Canonical CI/CD doc | +| `.github/workflows/ci.yml` | Integration gate (develop + main PRs) | +| `.github/workflows/release.yml` | Production release + ISO (main only) | +| `scripts/setup-github.sh` | Branch protection (light develop / strict main) | +| `tests/run_all.sh` | Local + CI test entry | +| `tools/xtask/src/main.rs` | `cargo xtask iso` (released ISO) | + +--- + +## Quick commands + +```bash +# Start work (always feature branch) +git fetch origin && git checkout develop && git pull origin develop +git checkout -b feat/my-change + +# Publish +git push -u origin feat/my-change +gh pr create --base develop --head feat/my-change + +# Verify before human merge +bash tests/run_all.sh +cd apps/oscortex_app && flutter analyze && flutter test +gh pr checks + +# After human merged your PR — sync local develop +git checkout develop && git pull origin develop + +# Production (human + explicit request only) +gh pr create --base main --head develop --title "Release: ..." +``` diff --git a/.agents/skills/oscortex-hardware/SKILL.md b/.agents/skills/oscortex-hardware/SKILL.md new file mode 100644 index 0000000..df9a09b --- /dev/null +++ b/.agents/skills/oscortex-hardware/SKILL.md @@ -0,0 +1,120 @@ +--- +name: oscortex-hardware +description: > + OSCortex hardware and driver model — display/GPU path, device classes, syscalls, + multi-arch rules, CDP WASM drivers. Use when adding or changing drivers, input, + audio, storage, net, compositor backends, or any question about hardware support + vs CPU porting. +--- + +# OSCortex Hardware & Drivers + +**Read first:** [docs/hardware.txt](../../../docs/hardware.txt) +**Product context:** [docs/arch.txt](../../../docs/arch.txt) · [oscortex-architecture](../oscortex-architecture/SKILL.md) + +**Out of scope:** `landing/` + +--- + +## One-sentence model + +**Hardware stays below stable syscalls; Flutter never touches devices; each device class needs its own driver, but the userspace API is shared.** + +--- + +## Display / GPU (most common confusion) + +- **No traditional GPU driver required** for shell first paint. +- Path: Flutter CPU raster → `present_callback` → `gpu_submit_strided` → compositor CPU blit → framebuffer. +- **`gpu_submit` = pixel copy to surface**, not Mesa/NVIDIA programming. +- Future real GPU = optional compositor backend under **same** surface syscalls. + +--- + +## Layers + +``` +Flutter → syscalls (abi.rs) → compositor/WM/policy → drivers/ → arch/ +``` + +--- + +## What transfers vs what does not + +| Transfers everywhere | Per device / per class | +|---------------------|-------------------------| +| Surface + WM syscalls | NVMe, audio, touchpad drivers | +| Flutter render contract | PCI ID-specific quirks | +| CDP WASM on all CPUs | Probe + init for each bus | +| compositor logic | Machine QEMU profile | + +--- + +## Adding hardware (short checklist) + +1. Driver in `kernel/src/drivers/` (native) or CDP WASM via `driver_gen.rs`. +2. MMIO/PCI only through `kernel/src/arch/` (`pci`, `port_io`, `mmio`, `cpu`). +3. Expose via **syscalls** or WM events — not userspace MMIO. +4. Update status in `docs/hardware.txt`. +5. Flutter via platform channel or existing WM — no parallel render path. +6. **Run tests** — `tests/run_all.sh` (see oscortex-kernel-tests skill). + +--- + +## Testing (2026-05-27) + +| Layer | Command | Covers | +|-------|---------|--------| +| Unit | `tests/run_all.sh` | vring, PCI BAR, xHCI caps, NVMe doorbells, net frames, manifest | +| Integration | `tests/run_all.sh --qemu` | virtio-blk/net, NVMe, PS/2 serial markers | + +Skill: `../oscortex-kernel-tests/SKILL.md` + +--- + +## Canonical paths + +| Path | Role | +|------|------| +| `docs/hardware.txt` | Canonical hardware document + compliance table | +| `kernel/src/arch/pci.rs` | PCI facade (all driver probing) | +| `kernel/src/arch/port_io.rs` | Legacy I/O port facade | +| `kernel/src/arch/mmio.rs` | MMIO load/store facade | +| `kernel/src/drivers/platform.rs` | Single driver init entry from main | +| `kernel/src/drivers/registry.rs` | Native + WASM driver registry | +| `kernel/src/embedder/abi.rs` | Stable syscall numbers | +| `kernel/src/drivers/` | Native drivers | +| `kernel/src/compositor/` | Surfaces, gpu_submit, vsync | +| `kernel/src/wm/` | Input routing, focus | +| `kernel/src/cortex/driver_gen.rs` | CDP WASM protocol (runtime AI drivers) | +| `kernel/src/arch/` | CPU porting | + +## Compliance (2026-05-27) + +| Rule | Status | +|------|--------| +| Syscalls-only userspace | ✅ | +| PCI/port/MMIO via `arch/` | ✅ | +| `drivers/platform.rs` init | ✅ | +| Native drivers in registry at boot | ✅ | +| Compositor canonical render | ✅ (`fb_map` no longer bypasses) | +| CDP WASM runtime load/heal | ✅ sandbox + quarantine; AI gen TBD | +| All device classes on all CPUs | x86 full profile; other arches skip PCI cleanly | + +--- + +## Non-negotiable rules + +1. **One render path** — compositor + Flutter only (see architecture skill). +2. **No userspace drivers** — no MMIO in embedder or apps. +3. **Pivot = delete** — no duplicate driver or syscall paths. +4. **Do not block shell bring-up** on GPU vendor stacks or unimplemented device classes. + +--- + +## When implementing + +- Extend existing driver modules; do not fork parallel ioctl/syscall domains. +- Align with `docs/hardware.txt` device table — mark ✅ / ⏳ when done. +- Shell paint issues are often **scheduler/compositor**, not missing GPU — verify before adding drivers. + diff --git a/.agents/skills/oscortex-kernel-tests/SKILL.md b/.agents/skills/oscortex-kernel-tests/SKILL.md new file mode 100644 index 0000000..520415c --- /dev/null +++ b/.agents/skills/oscortex-kernel-tests/SKILL.md @@ -0,0 +1,89 @@ +--- +name: oscortex-kernel-tests +description: > + OSCortex kernel driver tests — unit tests in tests/kernel/, QEMU integration in + tests/integration/, run via tests/run_all.sh or cargo xtask test. Use when adding + or changing kernel drivers, arch shims, platform init, or docs/hardware compliance. +--- + +# OSCortex Kernel Tests + +**Read first:** [tests/README.md](../../../tests/README.md) · [docs/hardware.txt](../../../docs/hardware.txt) + +**Related skills:** [oscortex-hardware](../oscortex-hardware/SKILL.md) · [oscortex-architecture](../oscortex-architecture/SKILL.md) · [oscortex-ci-cd](../oscortex-ci-cd/SKILL.md) · [codebase-audit-cleanup](../codebase-audit-cleanup/SKILL.md) + +--- + +## Run commands + +```bash +# Fast — host unit tests only (any machine) +tests/run_all.sh +cargo xtask test + +# Full — unit + QEMU driver smoke (x86_64, builds ISO) +tests/run_all.sh --qemu +cargo xtask test-qemu +``` + +--- + +## Layout + +| Path | Purpose | +|------|---------| +| `tests/kernel/` | Host `cargo test` — pure logic from `kernel/src/drivers/common/` | +| `tests/integration/qemu_drivers.sh` | Boot ISO, grep serial for driver ready markers | +| `tests/run_all.sh` | Unified runner | +| `kernel/src/drivers/common/` | **Testable pure helpers** — keep driver math here | + +--- + +## When you change kernel drivers + +1. **Pure logic** (BAR decode, vring layout, frame lengths, xHCI CAP parse) → put in `drivers/common/`, add/update unit test in `tests/kernel/unit/`. +2. **New native driver** → register in `drivers/platform.rs`, list in `docs/hardware.txt`, extend `tests/kernel/unit/driver_manifest.rs` if needed. +3. **QEMU-visible init** → ensure serial log line exists; add marker to `tests/integration/qemu_drivers.sh` if bring-up critical. +4. Run `tests/run_all.sh` before finishing driver work. + +--- + +## Unit test pattern + +Tests **include** kernel sources directly (no full no_std host build): + +```rust +#[path = "../../../kernel/src/drivers/common/vring.rs"] +mod vring; +``` + +Do **not** duplicate layout math in the test crate — change `drivers/common/` and tests follow. + +--- + +## Integration markers (current) + +Expected in QEMU serial output: + +- `[virtio-blk] ready` +- `[virtio-net] ready` + `[virtio-net] self-test TX completion OK` +- `[NVMe]` +- `[Input] PS/2 enabled` +- `[USB-HID] WM route OK` (HID parse → WM self-test; runs on every x86 boot) +- `[USB] XHCI ready` or `[USB] N XHCI controller(s) mapped and reset` +- `[USB] XHCI runtime started` (command/event rings programmed; enumeration polled on vsync) +- `[smoltcp] TCP/IP stack initialised` +- `[net] DHCP self-test OK` **or** `timeout (static IP fallback OK)` +- `[net] TCP self-test connect OK` **or** `connect skipped` + +Also run on every CI/local check: + +- `tests/integration/kernel_build.sh` — `x86_64-unknown-none` cross-build on host (works on Apple Silicon Macs) + +## Not covered (yet) + +- Live USB keyboard reports (`[USB-HID] live key` from `-device usb-kbd`) — xHCI runtime rings up but full EP0/HID enumeration still WIP +- Flutter paint / scheduler / cond-wait (separate agent) +- Physical bare-metal hardware (QEMU profile only; bare-metal policy covered by unit tests) + +Document gaps in `docs/hardware.txt` — do not claim test coverage that does not exist. diff --git a/.agents/skills/oscortex-ui-design/SKILL.md b/.agents/skills/oscortex-ui-design/SKILL.md new file mode 100644 index 0000000..7c91eeb --- /dev/null +++ b/.agents/skills/oscortex-ui-design/SKILL.md @@ -0,0 +1,113 @@ +--- +name: oscortex-ui-design +description: Design systems guidelines, layout rules, and components code-base for OSCortex landing page and interfaces, derived from lightfield.app style. +--- + +# OSCortex Design System Guideline (Lightfield Light Theme Style) + +This document establishes the UI design language for the OSCortex landing page and interface modules. Every component must strictly align with these parameters to maintain visual continuity. + +--- + +## 1. Design Tokens & Styling Variables + +### Theme Colors (Light Mode) +* **Primary Background (Base):** `#f5f5f5` (Creamy off-white background) +* **Secondary Background:** `#fafafa` +* **Surface Card / secondary:** `rgba(0, 0, 0, 0.02)` (Very low opacity black overlay) +* **Surface Card / primary:** `rgba(0, 0, 0, 0.04)` +* **Hairline Border:** `rgba(0, 0, 0, 0.08)` (Ultra-thin borders) +* **Strong Border:** `rgba(0, 0, 0, 0.15)` +* **Text Primary:** `#0d0d0d` (High-contrast near-black text) +* **Text Muted:** `rgba(0, 0, 0, 0.65)` (Standard gray text) +* **Text Dim:** `rgba(0, 0, 0, 0.4)` (Light gray for tags/meta) +* **Accent Color:** `#7c3aed` (Violet) / `#10b981` (Emerald green for active state) +* **Buttons:** + * **Primary:** solid black background with white text (`bg-black text-white hover:bg-neutral-800`) + * **Secondary:** transparent background, light black border (`border-black/[0.08] text-black hover:bg-black/[0.02]`) + +### Typography Hierarchy +* **Title font:** `Instrument Serif`, Georgia, serif (Normal/medium weight, tight tracking `-0.03em`) +* **Body font:** `Inter`, system-ui (Regular weight) +* **Monospace font:** `JetBrains Mono` (For telemetry, code snippets, tags) +* **Font Scales:** + * `.text-d4`: `32px` (leading `1.15em`, tracking `-0.035em`) + * `.text-h1`: `28px` (leading `1.2em`, tracking `-0.03em`) + * `.text-h2`: `24px` (leading `1.25em`, tracking `-0.02em`) + * `.text-h3`: `21px` (leading `1.25em`, tracking `-0.015em`) + * `.text-h4`: `19px` (leading `1.3em`, tracking `-0.01em`) + * `.text-base`: `15px` + * `.text-sm`: `13px` + * `.text-xs`: `12px` + * `.text-xxs`: `11px` + * `.monocaps-xxs`: `9px` (letter-spacing `1px`) + * `.monocaps-xs`: `10px` (letter-spacing `1px`) + +--- + +## 2. Structural Patterns + +### Floating Capsule Navbar +* Navbar must render as a floating pill capsule centered at the top of the viewport. +* It must have a blur backdrop (`backdrop-blur-[17px]`), rounded corners (`rounded-[10px]`), and a hairline border. +* Example Tailwind class layout: + ```html +