D-060 — docHub substrate mirrors FreshCards `module.json` shape

Status: accepted Date: 2026-06-23 Decided by: Helper Mavis (session 412100071272671), based on direct API inspection of studio/modules/freshcards/module.json

Context

Helper was about to invent a custom substrate contract for docHub when the operator asked: "Does it use the FreshCards module? Does it follow the FreshVibe Way?" A direct API check of FVS Studio revealed the actual FreshCards module.json schema in production. Inventing a new contract would have created fragmentation, not compatibility.

The FreshCards substrate (studio/modules/freshcards/module.json) is tier: platform-supreme, type: workspace-substrate, with a 5-file constitutional basis, 7 submodules, depends/used_by lineage, and a revibe lifecycle field. docHub should reuse this shape.

Decision

docHub's module.json will:

Reuse the FreshCards shape — module_id, version, type, description, path, tags, tier, tier_meta, submodules, depends, used_by, revibe, lineage.
Extend with two fields:

type: "doc-substrate" (vs FreshCards' "workspace-substrate") — distinguishes a doc substrate from a card substrate.
faces: { dev: {...}, user: {...} } — the two-face split (dev for AI/operator, user for end-users of FVS apps). Each face has its own path and auth policy.

Cite FreshCards in tier_meta.constitutional_basis — append studio/modules/freshcards/module.json to the constitutional basis list, making the extension relationship explicit and traceable.
Add tier_meta.extends: "studio/modules/freshcards/module.json" — formal "extends" relationship.

Consequences

✅ docHub is FVS-substrate-compatible from line 1. Any FVS code that knows how to consume FreshCards can consume docHub with a type check.
✅ Future FVS substrates (if any) follow the same shape with their own type discriminator.
⚠️ The two-face split (dev / user) is docHub-specific. Other substrates should not adopt it unless they have the same audience split.
⚠️ docHub's tier: platform-supreme means it's not copyable. The licence is avidtech6-proprietary. This constrains downstream use.

Pact cross-references

Pact ref — freshcards-substrate-001 (studio/modules/freshcards/module.json)

type: workspace-substrate, tier: platform-supreme, constitutional_basis: [pact/platform/cards/cards.md, pact/freshvibe-way-v7/23-two-view-substrate.md, pact/blueprint/workspace/workspace-model.md, pact/platform/workspaces/workspace-registry.md]

Relation to this decision: docHub's module.json is a structural extension of this. Every field in FreshCards' module.json has a counterpart (or an extension) in docHub's.

Pact ref — fvw-v7-23-two-view-substrate (pact/freshvibe-way-v7/23-two-view-substrate.md)

Two-view substrate pattern: a single substrate can be both a sovereign workspace AND a reusable module pattern.

Relation to this decision: docHub follows the same dual-usage pattern — sovereign workspace + FVS-embeddable substrate. The two faces (dev / user) are a docHub-specific refinement of the two-view concept.

Related decisions