chore: initial template commit

2026-05-06 09:21:40 +00:00
commit fcd4eb39f4
16 changed files with 946 additions and 0 deletions
@@ -0,0 +1,104 @@
+# 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