# Mountainridge Leptos + Matterhorn Template – AI Coding Agent Instructions

**Purpose**  
This is the **single source of truth**.  
Every AI coding agent **must** follow these rules exactly.  
Any deviation breaks the template contract, Matterhorn codegen pipeline, Keycloak integration, Tauri desktop build, or
embedding mechanism.

## Core Overview

- Rust + **Leptos** (latest stable) **CSR-only** reactive web application
- Data layer: **Matterhorn entities** (JSON-schema driven)
- Styling: **Standalone TailwindCSS** + **DaisyUI** components (no `tailwind.config.js`)
- Corporate theme: **"mountainridge"** (locked in `styles.css`)
- Authentication: **Keycloak OAuth2**
- Desktop variant: enabled with feature flag **`desktop`** (uses Tauri)

## Agent Tool Usage (Mandatory)

All agents have the following **injected tools** and **must** use them exclusively:

- `mridge_craft_add_matterhorn_entity` – add new Matterhorn data entities
- `mridge_craft_build` – full build / serve / watch / desktop package (Cargo + Trunk + Tauri)
- Git commit & push
- Create issues for the craft

**Never** execute raw shell commands (`cargo`, `trunk`, `git`, `tauri`, etc.).  
All GitHub operations are fully wrapped — repo details are irrelevant.

## Project Structure & Immutable Rules

| Path                   | Purpose                                                                | Modification Rules                                                  |
|------------------------|------------------------------------------------------------------------|---------------------------------------------------------------------|
| `./assets/`            | Extra CSS, fonts, images, static assets                                | Add only                                                            |
| `./schemas/`           | JSON schemas for Matterhorn entities                                   | **Never edit manually** – use add-entity tool                       |
| `./src/codegen/`       | **Auto-generated only** (structs, API client, helpers)                 | **Never touch**                                                     |
| `./src/codegen/api.rs` | Generated type-safe Matterhorn client (list/read/create/update/delete) | Auto-regenerated                                                    |
| `./src/components/`    | All custom Leptos components                                           | Free (PascalCase.rs)                                                |
| `./src/main.rs`        | Router + Keycloak token loader + BaseLayout                            | **Only edit the router section**. Never remove auth/base wrappers   |
| `./src/styles.css`     | Global stylesheet + full "mountainridge" DaisyUI theme                 | Extend only – never overwrite theme block                           |
| `./index.html`         | HTML entry point (Trunk)                                               | **Immutable section** (see below) – only meta/title changes allowed |

## Immutable / Protected Elements (Never Change)

**`./index.html`** – these exact lines **must remain untouched** (required for Trunk, favicon, public URL, and config
injection):

```html

<link data-trunk rel="copy-dir" href="./assets" data-trunk-target-path="/assets"/>
<link rel="icon" href="./assets/mridge-craft-icon.webp" type="image/webp"/>
<base data-trunk-public-url/>
<script>
    window.__embeddedAppConfig = {};
    window.addEventListener('message', function (e) {
        if (e.data.type === 'APP_CONFIG') {
            window.__embeddedAppConfig = e.data;
        }
    }, {once: true});
</script>
```

**`./src/styles.css`** – never delete or replace the `"daisyui/theme"` block.

**`./src/main.rs`** – never remove `<AuthProvider>`, Keycloak init, or `<BaseLayout>`.

**`./src/codegen/`** – generated; never manual edits.

## Authentication – Keycloak OAuth2

`main.rs` contains the protected Keycloak token loader:

- **Web/iframe mode** (default): token injected via `postMessage` (uses `window.__embeddedAppConfig`)
- **Desktop mode** (`--features desktop`): full Keycloak login flow + Tauri

**Rule:** Never remove, refactor, or bypass any auth-related wrapper.

## Critical Rules for Coding Agents

1. **Data Dependencies**  
   Always use `mridge_craft_add_matterhorn_entity` for any new or modified Matterhorn model.

2. **Routing**  
   Add new routes **only** inside the existing `<Router>` block in `main.rs`.  
   Preserve all auth/protected-route wrappers.

3. **Styling**  
   Prefer DaisyUI classes everywhere.  
   Tailwind is standalone — no config file.  
   Never override the "mountainridge" theme.

4. **Data Fetching (CSR-only)**  
   All operations **must** use the generated `codegen::api::*` client.  
   No Leptos server functions.

5. **Building & Testing**  
   Every compile, dev server, release, or Tauri desktop build → use `mridge_craft_build`.

## Standard Agent Workflow

1. Need new data entity? → use 'mrdige_add-entity' skill
2. Create component(s) in `./src/components/`
3. Add route in `main.rs` (inside router, respect auth)
4. Commit/push via git tools or create issue if needed