DocHub — Design Proposal

Date: 2026-08-14 | Author: fv-gallery-mavis (id 8) | Status: PROPOSAL (awaiting operator review)
Operator directive: "Introduce DocHub — human-facing story layer for modules"

1. What DocHub is

A human-facing documentation layer that sits on top of the Gallery's existing module library. For VibeCoders who think in vibe, tone, story, visual mockups — not in code or schemas.

What DocHub is NOT: constitutional (no module.json change), lineage (no trace-atlas/ change), structural (no code change), or a runtime concern. What it IS: a derivation of existing Gallery data, read-only (generated, never hand-edited), a first-class viewer in the Gallery UI, and embeddable in user apps.

2. DocHub entry shape (per module, ~12 fields)

dochub:
  id: <module-id>
  generated_at: <ISO timestamp>
  generator_version: "dochub-1.0.0"

  # === VISUAL MOCKUPS (3 reference-of-truth snapshots) ===
  mockups:
    default: { src: "dochub/<id>/mockup-default.svg" }
    hover:   { src: "dochub/<id>/mockup-hover.svg" }
    mobile:  { src: "dochub/<id>/mockup-mobile.svg" }

  # === EXPLANATIONS (3 levels) ===
  simple:  "A button the user clicks. Says 'Submit' or 'Cancel'."
  deep:    "An HTML <button> with type='button'. Configurable text, link,
            style variant, size. Renders server-side; CSS in skin, not button."
  expert:  "Canonical M-button. Schema: text (string, required), href (url,
            required), variant (select: solid|outline|ghost), size (select:
            small|medium|large). Inspector: Content+Style+Advanced."

  # === TONE VARIANTS (4 versions) ===
  tone:
    friendly:  "Hey, this is the Button — your everyday clicky thing!"
    designer:  "Primary action surface. 4 variants. Type-driven. ~120px wide."
    technical: "Anchor for user intent. Materializes as <button> or <a>."
    marketing: "Convert visitors into customers with the cleanest CTA."

  # === PERSONALITY + VIBE ===
  personality:
    archetype: "The reliable workhorse"     # one of N
    mood: ["confident", "calm", "approachable"]
    energy: "medium"                         # low | medium | high
    palette: ["#3b82f6", "#1e40af"]
    voice: "direct, friendly, no jargon"

  # === PURPOSE + USAGE ===
  purpose: "Primary call-to-action surface."
  usage:
    when_to_use:     ["commit a form", "navigate to next step"]
    when_not_to_use: ["section nav (use nav widget)"]
    pairing: [form, modal, accordion]

  # === EXAMPLES + CONSTRAINTS + WARNINGS ===
  examples:    [{title: "Submit form", config: {text: "Sign up", variant: "solid"}}, ...]
  constraints: ["must have text or icon", "href must be valid URL"]
  warnings:    ["avoid >3 buttons in one view (overwhelming)"]
  best_practices: ["solid=primary, outline=secondary, ghost=tertiary"]

All fields derived; no hand-edits.

3. Generation pipeline (4 stages)

[Source: 8 files in cms-widgets/<id>/]
   module.json, codex.md, rules.md, ingredients.json,
   dna/origin.json, coverage-matrix.md, trace-atlas/, module-meta.json
       ↓
[Stage 1: STRUCTURED EXTRACT] (mechanical, no LLM)
   - JSON fields from .json, markdown sections from .md → normalized intermediate
       ↓
[Stage 2: LLM SYNTHESIZE] (GLM-4.5-flash, ~5s/module)
   - 3 explanation levels, 4 tone variants, personality, examples, constraints
       ↓
[Stage 3: MOCKUP RENDER] (deterministic, no LLM)
   - Calls existing preview.html dynamic renderer
   - Captures 3 SVG snapshots: default / hover / mobile
   - Saves to cms-widgets/<id>/dochub/<state>.svg
       ↓
[Stage 4: DOCHUB YAML EMIT] (deterministic)
   - Writes cms-widgets/<id>/dochub.yml
   - 12/12 = "fully documented" (11 FES + 1 DocHub)

4. Storage & schema

New file per module: cms-widgets/<id>/dochub.yml (~3KB, the YAML above).

Updated Recipe Book:
- 10 §11 items + 1 §17 (module.json) = 11 from FvW doctrine (unchanged)
- 1 gallery-level item (dochub.yml probe) = 12/12 = "fully documented"
- Same model as today's preview.html 12th item (gallery-level, not per-module)
- No doctrine change required. DocHub is a gallery convention, not FvW §11/§17.

Gallery UI change: RecipeBookChecklist gets a 12th item, gallery-level badge styled like the existing preview.html row.

5. Gallery UI integration

Now (proposed, NOT yet built)

/dochub/:id page — full DocHub view for one module
/dochub index — list of all modules with personality + tone
RecipeBookChecklist 12th item (gallery-level probe)
"View DocHub" button on ModuleDetailPage

Future (per operator's "I have ideas to say at that point")

Module Browser recommends based on DocHub vibe tags
Trace Atlas links to DocHub for human-readable summaries
VibeCoder AI reads DocHub instead of codex when assembling apps
Simplified DocHub (dochub.lite.yml) embedded in user apps
Tone-variant search ("find me a friendly button")
Personality filters ("show me only calm-energy modules")

6. Build estimate

26 widgets × 5s GLM time = ~2 min total (parallelizable to 30s)
78 mockup SVGs (~10 min deterministic)
UI: 1 new page + 1 detail component + 1 checklist addition (~3h)
Total: ~4 hours for full DocHub coverage across all 26 modules

7. Open questions for operator

Mockup format: SVG (vector, scales) or PNG (raster, simpler)? → recommend SVG
Tone variants count: 4 or more? → start with 4
Personality archetypes: how many? → suggest 12 (workhorse, showpiece, specialist, …)
LLM choice: GLM-4.5-flash (free, fast) or operator's preferred? → GLM-4.5-flash
Generation trigger: every FES run (auto) or on-demand? → auto, in FES F6.5
Docthub.yml schema versioning: bump on every regen, or stable? → stable + timestamp

TL;DR

DocHub = 1 YAML per module (dochub.yml) generated from 8 existing source files via 4-stage pipeline (extract → LLM synthesize → mockup render → emit). 12-field schema: visual mockups, 3 explanation levels, 4 tone variants, personality/vibe, purpose/usage, examples, constraints, warnings. 12th item in the gallery's Recipe Book probe. ~4 hours total work. No doctrine change — DocHub is a gallery convention, like preview.html. Future UI integration per operator's later ideas.

Word count: ~700