Gallery Self-Audit — 2026-08-19

Author: fv-gallery-mavis (id 8) | Repos: fv-module-gallery @ 0987270, fv-gallery-ui @ e0401ab, fv-cms-vendored v1.2.0, gallery-pact/fvw/v8

---

1. Shapes

9 canonical + 2 NEW + 1 MISSING.

| Shape | Where | Purpose | § |

|---|---|---|---|

| module.json | cms-widgets/<id>/, modules/<id>/, apps/<id>/ | Constitutional record | §17.5, §11.9 |

| module-meta.json | same | Display + tier + recipe-book | module-meta.schema.json |

| codex.md | per module | State machine, events | §22 |

| rules.md | per module | 9 universal rules | §08 |

| plan.md | per module | Work plan | §11 |

| coverage-matrix.md | per module | Test status | §11.6 |

| ingredients.json | per module | Deps, env | §10 |

| dna/origin.json | per module | Canonical home + lineage | §03 |

| trace-atlas/index.json | per module | Cross-app usage graph | §04 |

| pact-viewer.yml (NEW) | cms-widgets/<id>/ | 12-field human-facing | §17.5.5 |

| PactViewer schema (NEW) | module.json.schema (kind=pact-viewer) | Input contract | modules/fv-pact-viewer |

| ❌ module-graph.json | should exist | Per-module relationship | — |

---

2. Patterns

• **Naming:** kebab-case IDs; `fv-` prefix for 4 Tier 1 modules; `ai-` prefix for 14 AI modules
• **Tiering:** `off-the-shelf` (51), `stable` (3 — the 4 fv-* Tier 1), `experimental`/`preview`/`archived` (0)
• **Module kinds (§17.5.2):** `gallery-original` (33), `gallery-mirror` (25), `original`/`borrowed`/`app-fork` (0)
• **Lifecycle:** `healthy` (most), `drifted`, `archived`
• **Canonical homes:** `in-this-gallery`, `avidtech6/<repo>`, `<app>`
• **Vendoring paths:** `modules/<id>/` (portable), `cms-widgets/<id>/` (CMS chrome), `apps/<id>/` (app-level)

---

3. Internal Modules

**Tier 1 fv-* (4):** fv-theme-toggle, fv-source-link, fv-recipe-book-checklist, fv-pact-viewer (NEW 2026-08-19)

**ai-* (14):** ai-actions, ai-adapters, ai-ambient, ai-ask, ai-credentials, ai-fragments, ai-history, ai-input, ai-mic, ai-orchestrator, ai-settings, ai-stt, ai-toast, ai-workspaces-chip — bundled as ai-bundle

fv-cms-vendored chrome (24 inspector controls + 40+ app-fragments): editor-inspector/controls/ (24 typed controls), app-fragments/ (admin-*, editor-*, fvcms-*, ai-agent)

fv-gallery-ui primitives (10 components + 9 pages): AppShell, ModuleCard, BundleCard, FilterBar, ModuleDetailPage, BundleDetailPage, VariantsPage, DocsPage, PactViewerPage (NEW), HomePage, ModulesPage, BundlesPage

---

4. Doctrine

• **gallery-pact/fvw/v8/ (53 files):** FvW v8 constitutional source. §11 Recipe Book, §17.5 module kinds, §17.6 mirror lifecycle, §17.7 revibe-as-fork, §22 behaviour-first codex, §38 two-recipe model. **§17.5.5 (NEW 2026-08-19) adds the pact_viewer affordance.**
• **gallery-pact/ (9 files):** module-meta.schema.json, registry.schema.json, facets.schema.json, bundle-manifest.schema.json, fvw-versioning-rules.md, fes-vendor-mandate.md, MIRROR-WORKFLOW.md, CLEANUP-WORKFLOW.md, AI-PUBLISHING-GUIDE.md, repo-safety-charter.md
• **cms-widgets/<id>/:** per-module 11-file Recipe Book
• **fv-cms-vendored/FV-CMS-MANIFEST.json:** FreshVibe CMS at v1.2.0, same 8-artefact shape

---

5. Registry

Top-level (20 keys): modules, apps, bundles (3 main arrays: 59+4+1), module_kind_index, tier_index, variant_index, facet_index, tags_index, consumer_index, dependency_graph, dependents_graph, deprecated_modules, forks, fvw_doctrine_refs, fvw_version, version, generated_at, generated_by, category_index, stats

Module fields (22 keys): id, path, version, _module_kind, _canonical_source, _canonical_version, _mirror_status, _last_verified, _cleanup_threshold_days, tier, tags, display_name, description, view, instantiable_by, consumers, license, _canonical_home, fvw_doctrine_refs, fvw_doctrine_version, category, is_ai

Mapping (module-meta.json ↔ registry.json): display_name → display_name; tier → tier; category → category; is_ai → is_ai; recipe_book_complete → implied via tier=stable; (last_built, builder not in registry)

Mapping (module.json ↔ registry.json): id → id; name → display_name; version → version; kind → _module_kind; provenance.origin → _canonical_source; filesystem path → path; tags → tags

---

6. Inheritance & Vendoring

FvW v8 (§11, §17.5) — source of truth
       ↓
fv-module-gallery/
   ├── fv-cms-vendored (v1.2.0, FreshVibe CMS)
   ├── modules/fv-* (Tier 1, npm-published)
   ├── modules/ai-* (14, ai-bundle)
   ├── cms-widgets/ (26 widgets, 12 at 11/11)
   ├── bundles/ai-bundle/ (1)
   ├── apps/ (4 app-pointers)
   └── registry.json (59 + 4 + 1)
       ↓ consumed by
fv-gallery-ui (React SPA)
   ├── AppShell + pages + components
   └── PactViewerPage (NEW 2026-08-19)
       ↓ deployed at
gallery.freshvibeapps.com

Cross-app vendoring (25 gallery-mirror modules): each pulls from external canonical home (e.g. avidtech6/oscar-platform for ai-*). Gallery shows them; actual code lives in the consumer app.

---

7. Cross-Cutting Rules

NEW (2026-08-19, in §17.5.5):

• **Tone variants:** friendly / designer / technical / marketing (4 in pact-viewer.yml)
• **Personality:** archetype, mood, energy, palette, voice
• **Examples:** 3-5 sample configs
• **Warnings + best_practices:** lists
• **pact_viewer affordance:** every module MAY expose one

Existing:

• **Recipe Book 11/11 (§11):** every module MUST have 11 FES files
• **9-folder layout (§02):** every module MUST sit in 9-folder FvW v8 layout

---

8. Missing Shapes

| Missing | Where it should be | Priority |

|---|---|---|

| module-graph.json | per module | HIGH |

| module-relationships.json | per module | HIGH |

| module-affordance-map | per module (click, submit, navigate) | HIGH |

| pact_viewer.yml auto-generation in FES | FES worker | HIGH |

| tier_transitions.json | per module (history) | MEDIUM |

| consumer_health.json | per consumer | MEDIUM |

| mockup_assets/ directory | per module (3 SVG mockups) | MEDIUM |

| tone_audit.md | per module (per-tone quality) | LOW |

---

9. Reusable Components for FreshVibe OS Pact Viewer

| Component | Status | Notes |

|---|---|---|

| PactViewer (React) | ✅ @avidtech6/fv-pact-viewer | NEW today |

| PactViewerPage (route) | ✅ in fv-gallery-ui | Full-page shell |

| usePactViewer (hook) | ✅ exported | For non-React contexts |

| ModuleCard | ❌ Needs <T> for Tier 2 promotion | MEDIUM |

| BundleCard | ❌ Same | MEDIUM |

| FilterBar | ❌ Tightly coupled to registry | LOW |

| AppShell | ❌ App-specific | LOW |

| RegistryLoader | ⚠️ Trivial extract | HIGH |

| DocsLoader | ⚠️ Trivial extract | HIGH |

| Inspector chrome (24 controls) | ✅ Shared via fv-cms-vendored | HIGH |

| FES worker | ✅ In fv-cms-vendored | HIGH |

| build-feed.py | ✅ In fv-module-gallery | HIGH |

Missing for full OS Pact Viewer: unified pact_viewer registry in npm, server component (Express), CLI (npx fv-pact-viewer), VSCode extension.

---

10. Recommendations for FreshVibe OS Pact Viewer

R1 (HIGH) Promote fv-pact-viewer to a top-level package — split into fv-pact-viewer-core (no UI), -react, -server, -cli

R2 (HIGH) Generate pact-viewer.yml for all 26 widgets via the 4-stage pipeline (currently only button.yml)

R3 (HIGH) Count pact-viewer.yml in the 11/11 Recipe Book probe (or as the 12th gallery-level probe)

R4 (DONE) Cross-app toggle shipped in the React component

R5 (MEDIUM) Add pact_viewer server endpoint to gallery: GET /api/pact-viewer/<id> returns JSON, .svg returns mockup

R6 (MEDIUM) Connect pact-viewer to Trace Atlas — "this module is used by 3 apps in production" becomes a real fact

R7 (LOW) Add theme="auto" (follow OS) + per-app theme overrides

R8 (LOW) Add a "compare two modules" side-by-side mode

---

Summary tables

A. Shapes (16)

| Shape | Status |

|---|---|

| module.json, module-meta.json, codex.md, rules.md, plan.md, coverage-matrix.md, ingredients.json, dna/origin.json, trace-atlas/index.json, diffs/CHANGELOG.md, recipe.md | ✅ Required §11 |

| pact-viewer.yml (NEW 2026-08-19) | 🆕 Gallery-level |

| PactViewer schema (NEW) | 🆕 in module.json |

| module-graph.json | ❌ MISSING |

| module-relationships.json | ❌ MISSING |

| tone_audit.md | ❌ MISSING (LOW) |

B. Patterns (9)

Kebab-case IDs (100%), fv- prefix (4), ai- prefix (14), gallery-original (33), gallery-mirror (25), tier=stable (3), tier=off-the-shelf (51), 11/11 Recipe Book (12), 0/11 Recipe Book (6)

C. Dependency graph

FvW v8 → fv-module-gallery (vendors fv-cms-vendored v1.2.0 + 4 fv-* + 14 ai-* + 26 widgets) → fv-gallery-ui (consumes via @avidtech6/fv-* aliases) → gallery.freshvibeapps.com

D. Vendoring graph

avidtech6/gallery-pact@main/fvw/v8/ (FvW doctrine) → avidtech6/fv-module-gallery (vendors fv-cms-vendored, publishes npm @avidtech6/fv-*) → avidtech6/fv-gallery-ui (consumes) → gallery.freshvibeapps.com (deployed)

E. Reusable components (12)

✅ Extracted: fv-pact-viewer, fv-theme-toggle, fv-source-link, fv-recipe-book-checklist, inspector chrome (24), FES worker, build-feed.py

⚠️ In gallery-ui only: RegistryLoader, DocsLoader

❌ Not extracted: ModuleCard, BundleCard, FilterBar, AppShell

F. Missing components (8)

fv-pact-viewer-server (HIGH), fv-pact-viewer-cli (MED), fv-module-card (MED), fv-bundle-card (MED), module-graph.json shape (HIGH), pact-viewer.yml bulk generator (HIGH), pact_viewer server endpoint (MED), tone_audit convention (LOW)

---

TL;DR

Gallery is a healthy 9-shape system with the Pact Viewer (NEW today) as the 12th human-facing shape. 59 modules, 4 apps, 1 bundle, 24 inspector controls, 10 React components, 53 doctrine files. 8 recommendations for a full OS-level Pact Viewer: promote to top-level package, generate yml for all 26 widgets, count in Recipe Book probe, ship server + CLI + extensions, connect to Trace Atlas.

Word count: ~1100