D-056 — FreshCards = 4th sovereign workspace AND substrate

Status: accepted (originally 2026-06-18, re-recorded in docHub 2026-06-23) Originally decided: 2026-06-18 (per pact/decisions/2026-06-18-vanilla-chrome-swap.md) Re-recorded by: Helper Mavis (session 412100071272671)

Context

Prior to 2026-06-18, FreshCards was a feature inside the FVS Studio app, with its own card-aware peek panel and card-scoped AI. The "vanilla chrome swap" refactor moved FVS chrome to vanilla TypeScript (no Mantine) and redefined FreshCards' relationship to the rest of the system.

The decision: FreshCards is not just a feature. It is:

1. The 4th sovereign workspace (alongside VibeCoder, VibeScope, Origin)
2. A reusable substrate (Card, SubNav, SubChips, SupportActs, InnerCard primitives) used across Studio

This dual identity is what makes the studio/modules/freshcards/ module shape possible — it has both workspace-mount code AND substrate-export code in the same package.

Decision

FreshCards has two co-equal identities:

• Sovereign workspace — full chip row, own layout, can be mounted as the active workspace in FVS Studio
• Substrate — provides Card primitives, geometry, regions, lifecycle, semantic roles for use by other parts of the system

The canonical FreshCards code lives at studio/modules/freshcards/ and is tier: platform-supreme (per module.json).

Consequences

• ✅ FreshCards has its own workspace-id in the sovereign-workspaces list
• ✅ Other parts of FVS Studio can import { Card, InnerCard, ... } from '@fvs/freshcards'
• ✅ The substrate contract is in studio/modules/freshcards/module.json and any FVS code that knows how to read a substrate module can introspect it
• ⚠️ Changes to FreshCards affect BOTH its workspace identity AND its substrate role. Breaking changes to the substrate ripple to every consumer
• ⚠️ The two identities can drift in priority. Sovereign workspace wants features; substrate wants stability. D-056 says substrate wins for non-trivial changes (per the platform-supreme tier)

Pact cross-references

Pact ref — vanilla-chrome-swap-001 (pact/decisions/2026-06-18-vanilla-chrome-swap.md)

"FreshCards is BOTH a sovereign workspace AND a substrate"

Relation to this decision: the original decision record. D-056 is the docHub re-recording; the canonical decision lives in the pact file.

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

type: workspace-substrate, tier: platform-supreme, constitutional_basis: [pact/platform/cards/cards.md, ...]

Relation to this decision: the substrate contract enforces the dual identity. The type field is "workspace-substrate" (not just "workspace"), and the tier_meta.platform_supreme: true makes the substrate priority explicit.

Related decisions

• D-060 — docHub substrate mirrors FreshCards shape (the pattern D-056 established extends to docHub)
• D-061 — FreshCards canonical location is studio/modules/freshcards/, not a standalone repo