GitHub Copilot Instructions — Family Home Dashboard

These instructions are authoritative for the Family Home Dashboard repository. GitHub Copilot MUST follow them exactly when generating, editing, or refactoring code. If there is any ambiguity, prioritize architecture safety and correctness over features or convenience.

---

0. Absolute Rules (Non-Negotiable)

1. **The dashboard must NEVER boot into a blank UI.**

2. **ONE unified localStorage key only:** `family_dashboard_db_v1`.

3. **Modules are code. Windows are layout.**

4. **App.jsx is a window manager ONLY.**

5. **Drop-in modules must work without editing App.jsx or registries.**

---

1. Core Mental Model

This project is a **dashboard OS**, not a traditional single-page application (SPA).

---

2. Tech Stack (Do Not Change)

---

3. Storage Rules

All persistent data uses the unified key **`family_dashboard_db_v1`**.

**Example store API:**

```javascript

import { getModuleData, setModuleData } from '@/core/dashboardStore'

// Read module data

const data = getModuleData('todoList')

// Write module data

setModuleData('todoList', { tasks: [...] })

```

---

4. App.jsx Rules

`App.jsx` is the **window manager** and handles:

`App.jsx` must **never**:

---

5. Module Contract

Every module must export a `moduleDef` object with the following shape:

```javascript

export const moduleDef = {

id: 'uniqueModuleId', // string, unique identifier

title: 'Module Display Name', // string, shown in window header

Component: MyModuleComponent // React component

}

```

Modules are automatically discovered and registered by their `moduleDef` export.

---

6. Module Structure

Each module lives in its own directory under `src/modules/`:

```

src/modules/<moduleId>/

index.js // exports moduleDef

module.jsx // main React component

helpers.js // utility functions (optional)

```

**Example `index.js`:**

```javascript

import TodoModule from './module'

export const moduleDef = {

id: 'todoList',

title: 'To-Do List',

Component: TodoModule

}

```

---

7. Boot Safety

The dashboard must **never** render an empty screen.

**Example starter modules:**

---

8. Code Generation Guidelines

When generating or editing code:

1. **Always check for boot safety** — ensure at least one module is enabled

2. **Never hard-code module lists** — use the module registry or discovery pattern

3. **Never mutate localStorage directly** — use the centralized store API

4. **Keep modules self-contained** — avoid cross-module dependencies

5. **Preserve window layout state** — persist window positions and sizes in the unified store

---

9. Editing and Refactoring Rules

When modifying existing code:

---

10. Testing and Verification

Before committing changes:

1. Verify the dashboard boots with a visible UI (not blank)

2. Verify all data persists across page refreshes

3. Verify modules can be added/removed without editing App.jsx

4. Verify no direct `localStorage.getItem()` or `localStorage.setItem()` calls exist outside `dashboardStore.js`

---

FINAL RULE

**Modules are code.**

**Windows are layout.**

**The dashboard must never be empty.**