# Gallery Entry Shapes — Setup Summary

> **Date**: 2026-07-22
> **Author**: Mavis (root session)
> **Status**: SETUP COMPLETE — ready for operator review

This is the complete set of files produced for the v4 gallery entry shapes decision. Each file is at a specific path, in a specific repo, with a specific purpose. This is the operator's checklist for review before committing.

---

## Files produced (10 total)

### Doctrine (1 file)

| # | File | Target | Purpose | Status |
|---|---|---|---|---|
| 1 | `/workspace/fvw-v8.2-section-17.5-17.7.md` | `avidtech6/freshvibestudio/pact/freshvibe-way-v8/17.5-module-canonical-home-and-mirror-model.md` (split) | FVW v8.2 §17.5, §17.6, §17.7 — the constitutional doctrine | ✅ drafted |

### Position doc (1 file)

| # | File | Target | Purpose | Status |
|---|---|---|---|---|
| 2 | `/workspace/position-gallery-entry-shapes-v4.md` | (working doc, not for a repo) | The locked position v4 with the canonical-home-is-never-default correction | ✅ drafted |

### Gallery-pact docs (3 files)

| # | File | Target | Purpose | Status |
|---|---|---|---|---|
| 3 | `/workspace/gallery-pact-AI-PUBLISHING-GUIDE.md` | `avidtech6/fv-module-gallery/gallery-pact/AI-PUBLISHING-GUIDE.md` | The 4 questions for AI sessions | ✅ drafted |
| 4 | `/workspace/gallery-pact-MIRROR-WORKFLOW.md` | `avidtech6/fv-module-gallery/gallery-pact/MIRROR-WORKFLOW.md` | How mirrors stay in sync (push from app CI vs pull from source) | ✅ drafted |
| 5 | `/workspace/gallery-pact-CLEANUP-WORKFLOW.md` | `avidtech6/fv-module-gallery/gallery-pact/CLEANUP-WORKFLOW.md` | The orphan → gallery-original state machine | ✅ drafted |

### Schema (1 file)

| # | File | Target | Purpose | Status |
|---|---|---|---|---|
| 6 | `/workspace/gallery-pact-module-meta.schema.json` | `avidtech6/fv-module-gallery/gallery-pact/module-meta.schema.json` | Updated JSON schema with `_module_kind`, `_canonical_source`, `_forked_from`, mirror lifecycle fields | ✅ drafted |

### Workflows (3 files)

| # | File | Target | Purpose | Status |
|---|---|---|---|---|
| 7 | `/workspace/gallery-pact-accept-mirrors.yml` | `avidtech6/fv-module-gallery/.github/workflows/accept-mirrors.yml` | Accepts mirror pushes from app CI | ✅ drafted |
| 8 | `/workspace/gallery-pact-pull-mirrors.yml` | `avidtech6/fv-module-gallery/.github/workflows/pull-mirrors.yml` | Daily pull from sources (fallback) | ✅ drafted |
| 9 | `/workspace/gallery-pact-cleanup-mirrors.yml` | `avidtech6/fv-module-gallery/.github/workflows/cleanup-mirrors.yml` | Daily orphan check + auto-promote | ✅ drafted |

### Summary (1 file)

| # | File | Target | Purpose | Status |
|---|---|---|---|---|
| 10 | `/workspace/gallery-entry-shapes-setup-summary.md` | (working doc, not for a repo) | THIS FILE — the operator's checklist | ✅ drafted |

---

## The model in one sentence

> **Every module has a canonical home. The gallery is a publisher, not an author. The AI asks 4 questions, never assumes.**

---

## The 5 module kinds

| `_module_kind` | Canonical home | When |
|---|---|---|
| `original` | the app repo | App's own work |
| `borrowed` | another app repo | App uses module made elsewhere |
| `gallery-original` | the gallery itself | Only when nowhere else fits |
| `gallery-mirror` | an external repo, mirrored to gallery | Cross-app, mirrored for discovery |
| `app-fork` | the app's repo (with `_forked_from`) | App revibed a module |

---

## The 4 questions the AI must ask

1. **New or revibe?**
2. **Where's the canonical home?** (which repo, which folder)
3. **Publish what?** (recipes only, recipes+code, full)
4. **Fork of anything?**

The AI never assumes. The operator decides.

---

## The mirror lifecycle

```
healthy → orphaned (source dies)
orphaned → promoted (30+ days, default)
orphaned → healthy (source comes back, same module)
orphaned → gallery-original (legacy, source came back as different module)
```

---

## What needs to happen next (not in this setup, just the queue)

### Step A: Operator review (this is where you are)
Read the 10 files, confirm or amend.

### Step B: Split the doctrine into the right files
The 17.5-17.7 doc is currently 1 file. It should be split into:
- `17.5-module-canonical-home-and-mirror-model.md` (FVW canon)
- `17.6-mirror-cleanup-and-auto-promotion.md` (FVW canon)
- `17.7-revibe-as-fork.md` (FVW canon)

Each in `avidtech6/freshvibestudio/pact/freshvibe-way-v8/`.

### Step C: Mirror the canon to the gallery
Per D-2026-07-22, the FVW canon is mirrored to `avidtech6/fv-module-gallery/gallery-pact/fvw/`. The new §17.5-§17.7 should be added to that mirror too.

### Step D: Update the gallery's registry.json
Annotate `ai-toast` and `ai-bundle` with the new fields:
- `ai-toast`: `_module_kind: "gallery-mirror"`, `_canonical_source: "avidtech6/ai-shell/ai-toast"`
- `ai-bundle`: update submodule entries with their kinds

### Step E: Migrate freshcloud-mail (test case)
- `gallery/apps/freshcloud-mail/` thin entry (metadata + recipe book mirror + pointer)
- No modules/ subfolder (the 17 mail-engine modules stay in freshmail-2)
- Bundle manifest mirror at `gallery/apps/freshcloud-mail/bundles/freshcloud-mail-engine-bundle/`
- freshmail-2's CI sets up to push recipe book mirror (or manual for now)

### Step F: Sweep other apps (parked)
- `gallery/apps/vibecoder-standalone/`
- `gallery/apps/freshcards-standalone/`
- `gallery/apps/vibescope-standalone/`
- `gallery/apps/fvs/`

Each app sets up its own mirror CI.

### Step G: Update FVW CHANGELOG
Bump to v8.2 (minor). Note §17.5-§17.7 added.

### Step H: Commit and deploy
Each repo gets its own commit:
- `avidtech6/freshvibestudio`: 3 new doctrine files + CHANGELOG bump
- `avidtech6/fv-module-gallery`: 3 new gallery-pact docs + 1 schema + 3 workflows + registry.json update + new `forks/` folder
- `avidtech6/freshmail-2`: CI workflow for pushing mirror (or just manual sync)

### Estimated effort (post-review)
- Step B: 5 min (split doc)
- Step C: 5 min (mirror to gallery)
- Step D: 30 min (annotate existing)
- Step E: 1-2 hours (freshcloud-mail migration)
- Step F: parked
- Step G: 10 min
- Step H: 30 min
- Total: ~3-4 hours, can be done in a day

---

## See also

- `/workspace/position-gallery-entry-shapes-v4.md` (the locked position)
- `/workspace/position-gallery-entry-shapes-v3.md` (superseded — had the canonical-home error)
- `/workspace/fvw-v8.2-section-17.5-17.7.md` (the doctrine)
- `/workspace/gallery-pact-AI-PUBLISHING-GUIDE.md` (the 4 questions)
- `/workspace/gallery-pact-MIRROR-WORKFLOW.md` (mirror sync)
- `/workspace/gallery-pact-CLEANUP-WORKFLOW.md` (orphan → gallery-original)
- `/workspace/gallery-pact-module-meta.schema.json` (the schema)
- `/workspace/gallery-pact-accept-mirrors.yml` (the workflow)
- `/workspace/gallery-pact-pull-mirrors.yml` (the fallback workflow)
- `/workspace/gallery-pact-cleanup-mirrors.yml` (the daily cleanup)
- `/workspace/canonical-home-proposal.md` (D-2026-07-22: FVW canon home is gallery)
- `/workspace/gallery-investigation.md` (the original gallery state)