# Working on oscar-web (Mavis instructions)

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

## This site VENDORS @freshvibe/cms

The CMS overlay at `app-fragments/oscar-cms-panel/` is a **vendored
copy** of `avidtech6/freshvibe-cms`. The files are stamped with:

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

**DO NOT EDIT VENDORED FILES HERE.** Edit them in the freshvibe-cms
source repo, then run `fvcms-update` here to pull the new version.

## How to know which files are vendored

1. Check for the `FV-CMS-VENDORED` marker at the top of the file
2. Cross-reference `app-fragments/oscar-cms-panel/FV-CMS-MANIFEST.json`
3. If both confirm it's a CMS file → edit in freshvibe-cms, not here
4. If only one confirms → check `fvcms-version-check` to be sure

## What's local to oscar-web (editable here)

- `app-fragments/oscar-dev-btn/` — the { } dev button
- `app-fragments/oscar-dev-panel/` — the dev panel UI
- `app-fragments/oscar-fes-inspector/` — FES Inspector (a dev tool, not
  the CMS — this is separate from @freshvibe/cms)
- `app-fragments/oscar-trace/` — section/widget trace badges
- `app-fragments/oscar-panel-manager/` — dock-based panel system
- `app-fragments/oscar-module-editor/` — eael-post-carousel legacy editor
- `app-fragments/oscar-region-editor/` — region editor
- `app-fragments/oscar-watermark-hider/` — hides the Elementor watermark
- `cms/` — the Generic CMS Module (a separate record-based CMS, NOT
  the same as @freshvibe/cms — G has said this should be a copy of
  freshvibe-cms but it isn't yet)
- `dist/` — the rendered static site
- `scripts/render.cjs` — the Playwright renderer
- `recipes/` — FvRE recipe outputs
- `_redirects` — Cloudflare Pages redirects

## What NOT to edit here

Everything in `app-fragments/oscar-cms-panel/runtime/` is vendored.
Specifically:

- runtime/index.js, store.js, renderer.js, skin.js, etc
- runtime/panel-manager/* — vendored from freshvibe-cms
- runtime/styles.css
- app-fragments/editor-breadcrumb/, editor-context-menu/, etc
- app-fragments/editor-inspector/* (the v2 inspector and controls)

If you find a bug in any of these, the fix goes in freshvibe-cms.
Then run `fvcms-update --target=app-fragments/oscar-cms-panel` to pull
the fix here.

## Quick commands

```bash
# What version of FV-CMS do I have?
node /workspace/freshvibe-cms/scripts/fvcms-version-check.mjs --target=app-fragments/oscar-cms-panel

# Am I up to date with the latest on GitHub?
node /workspace/freshvibe-cms/scripts/fvcms-version-check.mjs --target=app-fragments/oscar-cms-panel

# Pull the latest version (dry run first!)
node /workspace/freshvibe-cms/scripts/fvcms-update.mjs --target=app-fragments/oscar-cms-panel --dry-run
node /workspace/freshvibe-cms/scripts/fvcms-update.mjs --target=app-fragments/oscar-cms-panel

# Stamp vendored markers on an existing copy
node /workspace/freshvibe-cms/scripts/fvcms-stamp.mjs --target=app-fragments/oscar-cms-panel
```

## When the operator says "the CMS" — which one?

1. **The CMS overlay** (modules, regions, skins) = @freshvibe/cms,
   vendored at `app-fragments/oscar-cms-panel/`. Edit source.
2. **The record-based admin** (CRUD for news/books/quizzes) = the
   `cms/` directory. This is a separate system. Edit locally.
3. **The FES Inspector** (edit Elementor widget data-settings) = the
   dev tool at `app-fragments/oscar-fes-inspector/`. Edit locally.
4. **The dist** (rendered HTML) = `dist/`. Regenerate via
   `npm run render`.

Don't conflate them. Each has its own purpose, its own tests, its own
deploy path.