# App Development

Palace apps should be built with the assumption that AI butlers will be helping humans use them. Each app must include a `BUTLER.md` at its root (`apps/<appname>/BUTLER.md`) that tells butlers how to operate the app — data structure, schemas, sub-agent assignments, and file collision rules.

Code lives in `apps/<appname>/`. User data lives in `<palace>/palaceappsdata/<appname>/`. Apps are designed for multi-agent concurrency: separate files per concern, one writer per file, no cross-file references, app merges at read time.

## Creating a New Palace App

When told to make a new Palace app, do all of the following:

1. **Create app directory:** `apps/palace<appname>/` (lowercase, no hyphens)
2. **Create page:** `palacering/src/pages/<appname>/index.astro` — minimal hello world using Layout component, with back button to `/home`, app title, and "Hello, world." subtitle
3. **Register in apps.ts:** Add entry to `APPS` array in `palacering/src/lib/apps.ts` with id, label, href, gradient, and Phosphor icon SVG path via `ph()` helper
4. **Add to /home:** Add app link in the appropriate section of `palacering/src/pages/home.astro` (Lab section for new/experimental apps)

### Convention reference

- **Directory name:** `palace<appname>` (e.g., `palacepaint`, `palacemeditate`)
- **Page route:** `/<appname>/` (e.g., `/paint/`, `/meditate/`)
- **App id in apps.ts:** `<appname>` (e.g., `paint`, `meditate`)
- **Icons:** Always use [Phosphor Icons](https://phosphoricons.com/) SVG path data via the `ph()` helper in apps.ts. In home.astro, use the full SVG at 34x34 with viewBox 0 0 256 256.
- **Gradients:** Pick two muted tones that fit the app's character. Use `linear-gradient(135deg, #darker, #lighter)`.
- **Page structure:** Import Layout, wrap in `<div class="subpage">`, include `.page-header` with back button and title, `.page-sub` for subtitle.
- **Home sections:** Life, Office, Media, Pedia, Lab, Fund, Computer, Energy. New/experimental apps go in Lab.