diff --git a/.cursor/rules/coding-rules.mdc b/.cursor/rules/coding-rules.mdc new file mode 100644 index 00000000..e1dae72f --- /dev/null +++ b/.cursor/rules/coding-rules.mdc @@ -0,0 +1,271 @@ +# Archipelago Development Rules + +## CRITICAL: Project Structure & Location + +### NEVER Reference External Directories +- ❌ **NEVER** reference `/Users/tx1138/Code/Archipelago/` in code, scripts, or documentation +- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or `$PROJECT_ROOT` +- ✅ The workspace at `/Users/tx1138/Archipelago` is the ONLY project location +- ✅ All files must be created in the workspace, never in external directories + +### File Creation Rules +- ✅ Create files directly in the workspace using relative paths +- ❌ Never assume files exist elsewhere - check first, create if missing +- ✅ When copying from external sources, copy TO workspace, then update references + +## Design System & Styling + +### Tailwind CSS Rules +- ✅ **ALWAYS** create global utility classes in `neode-ui/src/style.css` or a dedicated `tailwind.css` +- ❌ **NEVER** use inline Tailwind classes directly in components +- ✅ Create semantic class names: `.glass-card`, `.glass-button`, `.nav-tab-active` +- ✅ Use CSS variables for design tokens: `--color-primary`, `--spacing-base` + +### Design Standards (From Memory) +- **Font**: Avenir Next font family (preferred) +- **Padding**: 4px grid system, 16px default padding +- **Containers**: iOS-style glassmorphism + - Background: `rgba(255,255,255,0.15)` + - Backdrop blur: `20px` + - Subtle white borders +- **Backgrounds**: Persistent background images (not dark themes) +- **Animations**: Smooth 2s splash screens with logo draw/glitch animations + +### Example Global Classes +```css +.glass-card { + background: rgba(255, 255, 255, 0.15); + backdrop-filter: blur(20px); + -webkit-backdrop-filter: blur(20px); + border: 1px solid rgba(255, 255, 255, 0.2); + border-radius: 16px; + padding: 16px; /* 4px grid */ +} + +.glass-button { + background: rgba(255, 255, 255, 0.1); + backdrop-filter: blur(10px); + border: 1px solid rgba(255, 255, 255, 0.15); + transition: all 0.2s ease; +} + +.glass-button:hover { + background: rgba(255, 255, 255, 0.2); +} +``` + +## StartOS Independence + +### Zero StartOS Dependencies +- ❌ **NEVER** import or reference StartOS-specific code +- ❌ **NEVER** copy StartOS patterns without refactoring +- ✅ **ALWAYS** create Archipelago-native implementations +- ✅ Use our own container orchestration (`core/container/`) +- ✅ Use our own security modules (`core/security/`) +- ✅ Use our own performance modules (`core/performance/`) + +### Backend Architecture +- ✅ Use `archipelago-container` crate, not StartOS container code +- ✅ Use our RPC endpoints in `core/startos/src/container/` +- ⚠️ **TEMPORARY**: Using StartOS backend (`startbox`) as base - this is temporary +- ✅ **GOAL**: Build our own Archipelago backend binary that uses ONLY our modules +- ✅ Mark all StartOS-derived code with `// TODO: Refactor to Archipelago-native` +- ✅ For development: Use mock backend for UI work, avoid StartOS backend when possible +- ✅ All new features must use our modules (`archipelago-container`, `archipelago-security`, etc.) + +## Container & App Development + +### App Manifest Rules +- ✅ **ALWAYS** create manifests in `apps/{app-id}/manifest.yml` +- ✅ Follow the manifest specification in `docs/app-manifest-spec.md` +- ✅ Use semantic versioning: `MAJOR.MINOR.PATCH` +- ✅ Include security policies, resource limits, health checks + +### Container Orchestration +- ✅ Use `archipelago_container::PodmanClient` for all container operations +- ✅ Use `archipelago_container::AppManifest` for manifest parsing +- ✅ Use `archipelago_container::DependencyResolver` for dependency management +- ❌ Never use Docker directly - always use Podman via our client + +### Security First +- ✅ **ALWAYS** set `readonly_root: true` unless explicitly needed +- ✅ **ALWAYS** drop all capabilities, add only required ones +- ✅ **ALWAYS** use isolated networks unless host network is required +- ✅ **ALWAYS** verify container images with Cosign signatures +- ✅ Use AppArmor profiles from `core/security/` + +## Frontend Development + +### Vue.js Component Rules +- ✅ Use Composition API (`