# Fv Module Gallery — Status

**Repo:** `avidtech6/fv-module-gallery` (PRIVATE)
**Last updated:** 2026-07-23 (v8.3.0 era)

## What this is

A private module gallery for the FreshVibe ecosystem. Two top-level concepts:

- **`modules/`** — flat, top-level, reusable. Each module is independent, forkable, versioned separately.
- **`bundles/`** — just lists of modules. A bundle is a module tagged `"bundle"` with a manifest. It contains NO module code.

Per **FVW v8.3 §17.5.7**, the default layout is **top-level submodules** (each `ai-*` sits at `modules/<m>/`, the bundle is a meta-entity at `bundles/<b>/`).

## What goes in here

- Modules (chrome + engine) used by Oscar, FreshCards, VibeCoder, VibeScope
- Bundles (groups of modules that ship together)
- App-pointers (thin entries for apps that consume the modules)
- Gallery-pact (schemas + FVW doctrine + conventions for the gallery itself)

## What does NOT go in here

- **CMS** — separate repo (`avidtech6/freshvibe-cms` or similar). It's an app, not a module. It can CONSUME gallery modules but doesn't live here.
- **FVRE** — separate repo (`avidtech6/fv-re` or similar). It's a CLI refactor tool, not a module, not a bundle.
- **Raw application code** — apps live in their own repos (`avidtech6/oscar-platform`, `avidtech6/vibecoder-standalone`, etc.). The gallery mirrors their modules.

## Doctrine: FVW v8.3.0 (canonical home IS the gallery)

Per **D-2026-07-22** ("FVW canonical home is gallery"), the FreshVibe Way doctrine is now canonical at `gallery-pact/fvw/freshvibe-way-v8/`. This is the inverse of the 2026-07-17 position.

- **Canonical**: `avidtech6/fv-module-gallery/gallery-pact/fvw/freshvibe-way-v8/`
- **Mirror**: `avidtech6/freshvibestudio/pact/freshvibe-way-v8/` (auto-synced via the FVW-SYNC-PROTOCOL)
- **Version**: 8.3.0 (2026-07-23)
- **Supersedes**: v8.2.0 (2026-07-22), v8.0 (2026-07-21), v7 (deprecated), v6 (frozen)

The 3 new sections in v8.3.0:
- **§17.5.7 — Bundle Layout: Top-Level vs Bundle-Local** (the "12 ai-modules rule")
- (plus the v8.2 sections: §17.5 canonical home + module kinds, §17.6 mirror cleanup, §17.7 revibe-as-fork)

## Current state (2026-07-23)

### Modules: 25 in `modules/`

| Category | Count | Modules |
|---|---|---|
| **ai-bundle (14 modules)** | 14 | ai-actions, ai-ask, ai-orchestrator, ai-adapters, ai-settings, ai-credentials, ai-fragments, ai-ambient, ai-mic, ai-input, ai-toast, ai-history, ai-stt, ai-workspaces-chip |
| **fvw-aligned (11 modules)** | 11 | anchor-system, card-constellation, cms, freshcards, lock, menu, mobile-unified-panel, navigation, refresh, settings, vibechat-signals |
| **Total** | **25** | All `_module_kind: gallery-mirror` (canonical in their respective app repos) |

**Canonical homes for the 14 ai-bundle submodules**: All 14 are canonical in `avidtech6/oscar-platform/app/src/modules/<m>/`. The 4 shell modules (ai-toast, ai-mic, ai-stt, ai-workspaces-chip) were originally in `avidtech6/ai-shell/src/`, moved to Oscar 2026-07-23 per operator directive ("ai shell repo needs deleting these shell modules need to belong to Oscar"). The ai-shell repo can be safely deleted.

### Bundles: 1 in `bundles/`

| Bundle | Version | Status | Submodules |
|---|---|---|---|
| `ai-bundle` | 2.2.1 | COMPLETE | 14 (9 public, 5 private) |

Bundle layout: **top-level submodules** (per FVW v8.3 §17.5.7). The bundle's `bundle-manifest.json` lists the 14 submodules by bare ID (`"id": "ai-ask"`, not `"id": "ai-bundle/ai-ask"`). Each submodule has its own canonical home.

### Apps: 4 in `apps/`

| App | Type | Status |
|---|---|---|
| `freshcards-standalone` | app-pointer | thin entry, modules partial |
| `freshvibestudio` | app-pointer | thin entry, fvs-aligned |
| `vibecoder-standalone` | app-pointer | thin entry, modules partial |
| `vibescope-standalone` | app-pointer | thin entry |

### Gallery-pact: 8 doctrine files + 2 schemas

| File | Status |
|---|---|
| `AI-PUBLISHING-GUIDE.md` | DONE — the 4 questions for AI sessions |
| `MIRROR-WORKFLOW.md` | DONE — how mirrors are published |
| `CLEANUP-WORKFLOW.md` | DONE — orphan → gallery-original promotion |
| `fvw/freshvibe-way-v8/` | DONE — FVW v8.3.0 canonical home |
| `module-meta.schema.json` | DONE — JSON schema for module metadata |
| `bundle-manifest.schema.json` | DONE — JSON schema for bundle manifests |
| `facets.schema.json` | DONE — facet definitions |
| `fvw-versioning-rules.md` | DONE — version bump rules |

### Operational infra: 3 GitHub Actions + 5 Python scripts

| Component | Status |
|---|---|
| `.github/workflows/accept-mirrors.yml` | DONE — auto-accept mirror PRs |
| `.github/workflows/pull-mirrors.yml` | DONE — periodic pull from sources |
| `.github/workflows/cleanup-mirrors.yml` | DONE — promote orphans after 30+ days |
| `scripts/validate-mirror-push.py` | DONE — pre-push validation |
| `scripts/pull-mirrors.py` | DONE — pull from sources |
| `scripts/cleanup-mirrors.py` | DONE — orphan promotion |
| `scripts/update-registry.py` | DONE — regenerate registry |
| `scripts/report-promotions.py` | DONE — report orphaned mirrors |
| `scripts/README.md` | DONE — script docs |

## 5 module kinds (per FVW v8.3 §17.5.2)

| `_module_kind` | Canonical home | Used for |
|---|---|---|
| `original` | this app's repo | App's own work |
| `borrowed` | another app's repo | App uses module from elsewhere |
| `gallery-original` | the gallery itself | Gallery IS the long-term home |
| `gallery-mirror` | an external repo (mirrored) | Cross-app, mirrored for discovery |
| `app-fork` | the app's repo (`_forked_from` set) | App revibed a module |

**In this gallery today**: 25 entries are `gallery-mirror` (canonical in their respective app repos). 4 are `app-pointer` (apps, not modules). 1 bundle is `gallery-mirror` (canonical in Oscar).

## Mirror lifecycle (per FVW v8.3 §17.6)

```
healthy → orphaned (source dies)
       → promoted (30+ days, source gone, becomes gallery-original)
       → reattached (source comes back, mirror resumes)
```

Current state: **25/25 healthy, 0 orphaned, 0 promoted**.

## What happened (2026-07-22 → 2026-07-23)

The 2026-07-17 STATUS.md was the original plan. Since then:

| Date | Event | What |
|---|---|---|
| 2026-07-22 | D-2026-07-22 | FVW v8.2 published, FVW canonical home = gallery (the inversion) |
| 2026-07-22 | First mirror | 12 ai-bundle modules mirrored from Oscar to gallery (commit `294edc2`) |
| 2026-07-22 | Revert | 21 freshmail modules removed (commit `30428c5`) — operator said "no freshmail" |
| 2026-07-22 | v8.1 → v8.2 | Added §17.5, §17.6, §17.7 to FVW |
| 2026-07-23 | v8.2 → v8.3 | Added §17.5.7 (Bundle Layout) + bundle refactor: 12 submodules to top level |
| 2026-07-23 | ai-shell → Oscar | 4 shell modules moved from ai-shell to Oscar (commits `1ce46c5`, `0887777`, `fa8fdf8`) |
| 2026-07-23 | ai-stt + ai-workspaces-chip added | 2 modules from ai-shell mirrored + moved to Oscar (commits `d3876d8`, `64e4820`, `41d7740`) |
| 2026-07-23 | Bundle v2.2.1 | All 14 submodules now `_module_kind: original` in Oscar's manifest, `gallery-mirror` in gallery's (commits `fa8fdf8`, `0185061`) |

## Pending work

- **(Parked, operator-approved)** Mirror FreshVibe Way v6 and v7 to gallery (see `/workspace/PARKED-mirror-freshvibe-way-v6-and-v7-to-gallery.md`)
- **(Parked, per operator)** FreshCloud Mail work — operator excluded freshmail from current scope
- **(Optional)** Re-deploy gallery static site to VPS so the live gallery reflects the 25 modules (live site is stale, last deployed 2026-07-17 with only ai-toast)
- **(Optional)** Delete `avidtech6/ai-shell` repo now that the 4 shell modules are in Oscar

## Decisions (chronological)

- **D-2026-07-17-01**: CMS lives in its own repo, not in this gallery.
- **D-2026-07-17-02**: FVRE lives in its own repo, not in this gallery.
- **D-2026-07-17-04**: Repo name is `fv-module-gallery` (not `freshvibe-monorepo`).
- **D-2026-07-17-05**: Modules are flat — `modules/<id>/`, never nested inside bundles.
- **D-2026-07-17-06**: Bundles are just lists — `bundles/<id>/` contains only `module.json` + `bundle-manifest.json` + `bundle-features.md` + `recipe-book/`. No module code.
- **D-2026-07-22-01**: FVW v8 canonical home is the gallery, not freshvibestudio. Mirror in freshvibestudio auto-syncs from gallery.
- **D-2026-07-22-02**: Reuse rule: mirror FVW-aligned modules from Oscar's `app/src/modules/<m>/` (initially excluded ai-shell).
- **D-2026-07-22-03**: Gallery is never canonical by default for new modules — AI asks 4 questions, operator decides.
- **D-2026-07-22-04**: FreshCloud Mail work is parked. Do not mirror freshmail modules to gallery.
- **D-2026-07-23-01**: FVW v8.3 §17.5.7 — bundle submodules go at top level (Layout A is the FVW default).
- **D-2026-07-23-02**: All 4 shell modules (ai-toast, ai-mic, ai-stt, ai-workspaces-chip) belong to Oscar. The ai-shell repo can be deleted.
- **D-2026-07-23-03**: Reuse rule extended — shell modules can be sourced from ai-shell, but the canonical home is Oscar (after the 2026-07-23 move).