# ═══════════════════════════════════════════════════════════════════════
# .rammerules — Ramme App Agent Enforcement Manifest
# Distributed via: @ramme-io/create-app
# Full ruleset: https://github.com/ramme-io/ramme-monorepo/.rammerules
# ═══════════════════════════════════════════════════════════════════════
#
# These rules are LAWS, not suggestions. Every agent (AI or human)
# operating in this project is bound by them.
# ═══════════════════════════════════════════════════════════════════════


# ═══════════════════════════════════════════════════════════════════════
# LAW 14: THE 5-PART APPSHELL CHASSIS CONTRACT
# Ratified: May 2026 | Scope: ALL route components in this app
# ═══════════════════════════════════════════════════════════════════════
#
# THE LAW:
#   Every Ramme application screen MUST be assembled using the canonical
#   AppShell chassis from @ramme-io/ui. No custom layout wrappers, no
#   flexbox root divs that attempt to replicate chassis geometry.
#
# THE 5 STRUCTURAL SLOTS (frozen, non-negotiable):
#
#   ┌─────────────────────────────────────────┐
#   │  2. headerSlot  (h-header, sticky top)  │
#   │─────────────────────────────────────────│
#   │  3. toolbarSlot (h-toolbar, breadcrumb) │
#   ├──────────┬──────────────────────────────┤
#   │          │                              │
#   │ 1. side  │   4. children (canvas)       │
#   │   barSlot│       flex-1, overflow-y-auto│
#   │          │                              │
#   ├──────────┴──────────────────────────────┤
#   │  5. statusbarSlot (h-statusbar, bottom) │
#   └─────────────────────────────────────────┘
#
#   AppShell usage:
#     <AppShell
#       layoutPreset="dashboard"   ← 'dashboard' | 'explorer' | 'focus'
#       sidebarSlot={...}
#       headerSlot={...}
#       toolbarSlot={...}
#       statusbarSlot={...}
#     >
#       {/* canvas content */}
#     </AppShell>
#
# LAYOUT PRESETS:
#   dashboard → sidebar + header + toolbar + canvas + statusbar (default)
#   explorer  → same as dashboard but canvas is edge-to-edge (p-0)
#   focus     → header/sidebar/toolbar/statusbar all hidden; canvas only
#
# ENFORCEMENT:
#   - AppShell MUST be the first rendered element of any route component.
#   - Slot components MUST be defined OUTSIDE the route component —
#     no inline JSX creation inside slot props.
#   - NEVER apply h-screen or h-dvh inside any slot — AppShell already
#     owns the full viewport via its root className.
#   - NEVER place DetailDrawer or Modal inside AppShell children —
#     they use `fixed` positioning and must be siblings at the root level.
#
# REFERENCE IMPLEMENTATION (included in this project):
#   src/features/dashboard/MainDashboard.tsx
#   — Canonical dashboard layout with all 5 slots wired and annotated.
#   — Study this file before building any new route or layout.


# ───────────────────────────────────────────────────────────────────────
# LAW 15: ISOMORPHIC SKU NAMING SCHEMA
# Ratified: May 2026 | Scope: ALL components, hooks, data primitives
# ───────────────────────────────────────────────────────────────────────
#
# THE FORMAT:
#   @[Layer]/[Category]/[SemanticName]
#
# LAYERS (from @ramme-io/ui wizardManifest):
#   @atom      → Primitive UI elements (Button, Input, Badge, Icon)
#   @chassis   → Structural layout (AppShell, Sidebar, Header, Toolbar)
#   @molecule  → Pre-assembled composites (DataCard, DetailDrawer, StatCard)
#   @hook      → React hooks (useDevice, useSignalStore, useManifest)
#   @util      → Pure functions (cn, formatters, parsers)
#   @data      → Mock + seeded data primitives
#
# CATEGORY EXAMPLES:
#   @atom/primitive/*       → ui/ primitive components
#   @chassis/layout/*       → layout/ (AppShell, Sidebar)
#   @molecule/data/*        → data-display/ components
#   @molecule/form/*        → forms/ components
#   @molecule/nav/*         → navigation/ components
#   @molecule/iot/*         → iot/ blocks (DeviceCard, TelemetryLog)
#   @molecule/ai/*          → ai/ blocks (Suggestion, ChatFAB)
#   @molecule/feedback/*    → feedback/ (Alert, Toast, EmptyState)
#   @hook/lib/*             → hooks/ utilities
#   @data/mock/*            → data/ mock primitives
#
# USAGE IN CODE:
#   Every component file MUST carry its SKU in a JSDoc or comment header:
#     /**
#      * @sku @chassis/layout/main-dashboard
#      * @description Reference implementation of the 5-part chassis.
#      */
#
#   Inline annotations for key usage points:
#     {/* @sku @molecule/data/data-card */}
#     <DataCard title="Node Temp" ...>...</DataCard>
#
# MACHINE READABLE:
#   The SKU is the lookup key in @ramme-io/ui wizardManifest and AUTO_REGISTRY.
#   AI agents resolve components via: resolvePreview({ sku: '...' })
# ═══════════════════════════════════════════════════════════════════════
