Update CLAUDE.md for v0.4: branching convention, renderer features, known limitations

- Branching: main=release, development=default dev branch, no per-conversation branches
- Add v0.4 renderer features section (callouts, TOC, theme, icons, PWA, fetch-deps)
- Note topbar nav is broken — always use sidebar
- Update version markers to v0.4 throughout
- Add note that tag pushes must be done locally (cloud env blocks them)

https://claude.ai/code/session_01UP8Wo2CKPNhvvTkzX48CWF

CLAUDE.md

@@ -8,8 +8,12 @@ Every merge into `main` is a release. Before committing any change to `mdcms.py`
 
 ## Branching convention
 
-- **Code changes** (`mdcms.py`, `pyproject.toml`, `app/`, `.github/`) — use branch `mdcms_claude` (create from `main` if it doesn't exist), PR to `main`.
-- **Documentation only** (`CLAUDE.md`, `docs/`) — push directly to `main`.
+- **`main`** is the release branch. Every merge to `main` is a release. Never commit work-in-progress directly to `main`.
+- **`development`** is the default branch for all development, including all Claude-driven work. Create it from `main` if it doesn't exist. Do not create a new branch per conversation.
+- **Phased branches** (`claude/<feature>`) are allowed when a large feature needs staged review, but the final merge target is always `main` via `development`.
+- **Documentation only** (`CLAUDE.md`, `docs/`) — may be pushed directly to `main`.
+
+In practice: check out `development`, do the work, push to `development`, PR `development` → `main` when ready to release.
 
 ## What this project is
 
@@ -26,8 +30,8 @@ The `app/` folder is the deployable artifact and the starter template downloaded
 mdcms.py                        ← CLI tool
 pyproject.toml                  ← packaging (entry point, dependencies)
 app/
-  index.html                    ← renderer + v0.3 version marker
-  config.yml                    ← starter config + v0.3 version marker
+  index.html                    ← renderer + v0.4 version marker
+  config.yml                    ← starter config + v0.4 version marker
   nav.yml                       ← generated
   search.json                   ← generated
   pages/
@@ -97,8 +101,9 @@ Single-module Python script. Logical layers in order:
 
 Every mdcms site has a version marker on the first line of two files:
 
-- `config.yml` line 1: `# mdcms v0.3 | DO NOT REMOVE THIS COMMENT`
-- `index.html` line 1: `<!-- mdcms v0.3 | DO NOT REMOVE THIS COMMENT -->`
+- `config.yml` line 1: `# mdcms v0.4 | DO NOT REMOVE THIS COMMENT`
+- `index.html` line 1: `<!-- mdcms v0.4 | DO NOT REMOVE THIS COMMENT -->`
+- `theme.yml` line 1: `# mdcms v0.4 | DO NOT REMOVE THIS COMMENT`
 
 `register` and `build` both read the marker from `config.yml` to detect and validate the site. Sites with no marker are not recognised as mdcms sites. Sites below `MIN_SUPPORTED_VERSION` are rejected.
 
@@ -193,12 +198,37 @@ All artifacts are attached to the GitHub release using `gh release create`. The
 2. Update `version` in `pyproject.toml`
 3. Update site format markers in `app/config.yml` and `app/index.html` only if the site format changed
 
-Then: `git tag v0.3.1 && git push origin v0.3.1`
+Then: `git tag v0.4.1 && git push origin v0.4.1`
+
+**Note:** Git tag pushes must be done from a local machine — the cloud environment cannot push tags (HTTP 403). Use `gh release create <tag>` locally after pushing the tag.
 
 ## Known limitations
 
 - Most `posts-*` tag variants are broken. Only `posts-datetime-chronological-byyearmonth` and `posts-datetime-reversechronological` reliably work.
 - Section headings in the nav are non-clickable (sections-sitemap is not yet implemented).
+- **`navigation: topbar` is broken.** Always use `navigation: sidebar` in `config.yml` for any test sites or starter templates.
+
+## v0.4 renderer features (index.html)
+
+Features added in v0.4, all rendered client-side in `app/index.html`:
+
+### Callout tags
+Fenced `mdcms` blocks with `callout-info`, `callout-warning`, `callout-success`, `callout-error`. Each has a coloured left border, low-opacity tinted background, optional icon + title row, and full markdown body. The JS sets `--callout-primary` and `--callout-bg` CSS variables on the container; the CSS must reference these (not hardcoded colours). Config-defined messages: `message: <key>` resolves title and body from the `callouts:` block in `config.yml`.
+
+### Table of contents tag
+Fenced `mdcms` block with `toc`. Renders a section-grouped list of all visible, non-draft pages in the active category, excluding the TOC page itself. Groups by nav section.
+
+### Theme system (`theme.yml`)
+Presentational config separate from `config.yml`. Controls accent colour, dark/light mode palette, fonts, and layout. `index.html` loads it at runtime.
+
+### Icon system
+All UI icons served as local SVGs from `app/assets/icons/`. No Google Fonts or external icon font. Icon names are normalised (lowercase, spaces → hyphens).
+
+### PWA
+`manifest.json` and `service-worker.js` generated by `mdcms build` when `pwa: yes`. Cache-first SW precaches all pages, posts, and assets. Offline message from `config.yml` (`offline-message` key) stored in `localStorage` and shown when a page can't be fetched. Requires a `favicon.png` in `assets/images/` for the install icon (192×192 recommended).
+
+### `fetch-deps` offline mode
+`mdcms fetch-deps` downloads all CDN JS/CSS to `assets/required/vendors/` and Bunny Fonts to `assets/fonts/`, then patches `index.html` CDN URLs to local paths. After this, the site makes no external network requests.
 
 ## Key implementation details