# Angelia

> Wagtail CMS — Robert's website publishing platform.

- **MCP server name:** `angelia`
- **Prompt snippet:** [prompts/tools/angelia.md](../../prompts/tools/angelia.md)
- **Authoring skill (future):** detailed page-by-page authoring guidance — design tokens, HTML patterns, page-type schemas, workflow — will be packaged as a Skill in a later phase. For now, the full Angelia 2 Authoring Guide is sourced separately when an authoring task begins.

## What It Is

Angelia is the Wagtail-based CMS for Robert's website. It exposes the site's content management — pages, blog posts, events, the media library — through an MCP surface, so an authoring agent can create and update content programmatically rather than clicking through the admin UI.

The MCP exposes 24 tools across six surfaces: pages (read tree, get content, create FlexPage, update, publish/unpublish, delete, move, copy), media (search images, get sized renditions, upload, list collections, tag images), blog (create/update/list posts, manage categories, manage tags), events (create/update/list), and syndication (feed URLs).

Content fields accept **raw HTML** (not Markdown, not StreamField blocks). The site's base template provides Bootstrap 5.3.3, Bootstrap Icons, three self-hosted font families, and a design-token system (CSS custom properties) for consistency.

## Page Types

Angelia has six page types, each with a fixed template:

| Page type | Purpose | Max count | Parent |
|---|---|---|---|
| **HomePage** | Site root with hero + body | 1 | Site root |
| **FlexPage** | Freeform creative content with per-page CSS | unlimited | HomePage or FlexPage (can nest) |
| **BlogIndexPage** | Container for blog posts | 1 | HomePage |
| **BlogPage** | Individual blog post | unlimited | BlogIndexPage |
| **EventIndexPage** | Container for events | 1 | HomePage |
| **EventPage** | Calendar event with date/location | unlimited | EventIndexPage |

**FlexPage** is the go-to for creative content — full HTML control + per-page `custom_css`. Use FlexPage when the page is bespoke. Use BlogPage when it's an article in the running blog. Use EventPage when it's something with a structured start/end time.

## Workflow Discipline

The canonical flow:

1. **`get_page_tree()`** first — always start by understanding the site structure. You need parent IDs to create pages, and you need to know what already exists.
2. **`search_images()`** for visuals before uploading new ones.
3. **`manage_categories()` (list)** before posting if categories are involved — they have to exist first; only tags are created on the fly.
4. **Create as draft** — every tool defaults to `publish=False`. Don't publish until reviewed.
5. **Review with `get_page_content()`** — read back what was created or updated.
6. **Publish when ready** — `publish_page(page_id)` is the deliberate step.

## Who Uses Angelia

- **Ann** — primary user. Website authoring (FlexPages), blog post creation, content calendar execution, event page creation. The website is Ann's primary marketing surface; Angelia is how the website gets touched.

Other agents may eventually use Angelia (e.g., Cousteau if a "garden notes" section gets added), but Ann is the only current user.

## What It's Good For

- Programmatic page authoring with full HTML control
- Blog post creation with tags, categories, featured images, ActivityPub publication
- Event creation with structured date/time, location, registration links, recurrence rules
- Media library management — upload, search, tag, request specific renditions
- Draft-and-review workflow without leaving the chat

## What It's Not Good For

- Heavy WYSIWYG editing of existing rich content — the HTML is the content; there's no rich-text intermediary
- Markdown — Angelia's content fields take raw HTML, not Markdown
- StreamField-style content blocks — Angelia deliberately doesn't use StreamField. Structure your content with HTML + Bootstrap + design tokens.
- Things that aren't web publishing — calendar events Robert is attending (that's Kairos), CRM contacts (Athena for work, Kairos for personal), etc.

## Design Tokens (high-level)

The site has a design-token system — CSS custom properties for colors, typography, spacing, layout, borders, shadows. Author CSS using `var(--token-name)` rather than hardcoded values to stay consistent with the rest of the site.

Tokens cover: brand colors (primary teal, secondary magenta, accent orange, plus success/warning/danger), typography (Inter for headings, Source Sans Pro for body, JetBrains Mono for code), spacing scale (xs through 2xl), layout widths, border radii, and shadow tiers.

Full token reference is loaded as part of the authoring guide when an authoring task begins; the MCP also exposes the design tokens as a readable resource (`angelia://design-tokens`).

## Known Gotchas

- **HTML, not Markdown.** All content fields take raw HTML. Don't pass Markdown.
- **No StreamField.** Angelia doesn't use Wagtail's block system. Use HTML + Bootstrap + design tokens for structure.
- **Don't include `<!DOCTYPE>`, `<html>`, `<head>`, `<body>`, `<nav>`, or `<footer>`** in your HTML — the base template provides all of that. Your HTML renders inside `<main class="page-content">`.
- **Default to drafts.** Every creation tool defaults to `publish=False`. Don't pass `publish=True` until the content has been reviewed.
- **Tags vs categories:** tags are created on the fly when you use them; categories must already exist. Run `manage_categories(action="list")` before creating a post with categories, and create any missing ones first.
- **Image renditions are pre-generated.** `search_images` returns ready-to-use URLs for common sizes (thumbnail, small, medium, large, hero, og). Use `get_image_url` with a `filter_spec` only when you need a custom size.
- **No external font imports** — the three site fonts are self-hosted. Don't try to load Google Fonts.
- **Hero image binding is automatic.** If `hero_image_id` is set on a HomePage, the template adds the `background-image` to `.hero-section` automatically. Your `hero_css` needs to include `background-size: cover; background-position: center;` or the image won't display correctly.
- **`tags` and `category_slugs` on `update_blog_post` replace** existing values rather than appending. To keep existing tags and add new ones, pass the full combined list.
- **`get_page_tree` first.** Skipping this and trying to create a page with a guessed parent ID is the most common authoring error.