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):


<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

Data Dependencies
Always use mridge_craft_add_matterhorn_entity for any new or modified Matterhorn model.
Routing
Add new routes only inside the existing <Router> block in main.rs.
Preserve all auth/protected-route wrappers.
Styling
Prefer DaisyUI classes everywhere.
Tailwind is standalone — no config file.
Never override the "mountainridge" theme.
Data Fetching (CSR-only)
All operations must use the generated codegen::api::* client.
No Leptos server functions.
Building & Testing
Every compile, dev server, release, or Tauri desktop build → use mridge_craft_build.

Standard Agent Workflow

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

5.0 KiB Raw Blame History Unescape Escape