# Working on FreshVibe CMS (Mavis instructions)

If you're an AI looking at this file, READ THIS FIRST.

## What this repo is

This is the **source of truth** for `@freshvibe/cms` — the first-round
FreshVibe CMS that overlays FvRE-generated static dists. Every consuming
site (fvcms-web, fv-gallery-ui, etc) VENDORS a copy of this code into
their own `app-fragments/` directory.

## DO NOT edit vendored copies

When you see files with the marker:

```js
/* FV-CMS-VENDORED v0.4.0 — DO NOT EDIT IN PLACE. Source: github.com/avidtech6/freshvibe-cms. To update, run: fvcms-update */
```

**THOSE ARE VENDORED COPIES.** They live in another repo (fvcms-web,
fv-gallery-ui, etc). Edit them HERE, not there. Then the consuming site
picks up the change via `fvcms-update`.

## How the update system works

1. **Source of truth** — this repo (`avidtech6/freshvibe-cms`)
   - `FV-CMS-VERSION.txt` — single line, e.g. "0.4.0"
   - `FV-CMS-MANIFEST.json` — list of every file in the vendored bundle
   - `package.json` — npm metadata + vendored marker template
   - `scripts/fvcms-update.mjs` — CLI to pull latest into a target
   - `scripts/fvcms-version-check.mjs` — CLI to check if a target is current
   - `scripts/fvcms-stamp.mjs` — CLI to add the vendored marker to existing files

2. **Vendored copies** — `fvcms-web/app-fragments/...` etc
   - Same files, with the vendored marker stamped on every JS file
   - `FV-CMS-VERSION.txt` says which version they have
   - `FV-CMS-MANIFEST.json` says which files they have
   - On page load, `runtime/update-checker.js` hits GitHub and warns
     the operator if they're behind

3. **Release flow**:
   - Edit code here
   - Bump `FV-CMS-VERSION.txt` (and `package.json`)
   - `git tag v0.4.0 && git push --tags`
   - GitHub Actions (or manual) creates a release
   - Operators run `fvcms-update --target=../fvcms-web` on their site
   - Files overwrite in place, vendored marker refreshes

## What lives where

- `bootstrap.js` — entry point, exports `bootFreshvibeCms(opts)`
- `runtime/` — the engine (store, renderer, scopes, query)
- `modules/` — the 10 canonical modules (heading, cta, image, etc)
- `app-fragments/` — UI features (editor-inspector, outline, navigator, etc)
- `app-fragments/editor-inspector/controls/` — the 24 world-class controls
- `skins/` — Reign, BuddyX (sample skins)
- `schemas/` — content schemas if any
- `tests/` — 49/49 smoke tests
- `detectors/` — auto-detect modules in the dist
- `annotation.json` — the dist annotation file (consumed by bootstrap)

## Edit guidelines

1. **Read the WHOLE file** before editing. The 24 controls are similar
   but each has its own quirks.
2. **Match the existing style** — class names, export patterns, import
   paths, control function signatures all follow conventions in
   `app-fragments/editor-inspector/controls/`.
3. **Test before pushing** — `npm test` (49/49 should stay passing).
4. **One PR per concern** — don't mix a color picker fix with a typography
   refactor.
5. **Bump version on every PR that ships to vendors** — even patch bumps
   (`0.4.0` → `0.4.1`). The operator's update check is per-version.
6. **Update the manifest** — if you add/remove/rename a file, update
   `FV-CMS-MANIFEST.json` so `fvcms-update` knows what to ship.
7. **Stamp new files** — if you add a new control, the marker will be
   added by `fvcms-update` when it's vendored. But if you add a file
   that doesn't go through the vendor pipeline, stamp it manually.

## Common mistakes to avoid

- **Don't invent new control types** — if you need a new control,
  add it to `app-fragments/editor-inspector/controls/<name>/<name>.js`
  and update the spec in `CONTROLS-WORLD-CLASS-SPEC.md`.
- **Don't bypass the store** — every edit goes through the store and
  triggers the renderer. Don't directly mutate DOM or modules.
- **Don't hardcode paths** — use `import.meta.url` for relative paths
  so the code works in any site.
- **Don't add npm dependencies** — this is a vendored bundle, no
  build step, no node_modules at the consumer.

## How to know what to work on

- Operator reports a bug → find which module/control/runtime file
- Operator asks for a new feature → check the spec docs first
- Operator asks to update a site → run `fvcms-update`
- Operator asks what's deployed → run `fvcms-version-check`