meta living owner: Azwaan reviewed: 2026-07-06

Lovable Data Contract

Every JSON feed the Lovable frontend consumes, field by field. Read with the Publication Model (ownership, tiers, missing-data rules) and the Entity Catalogue (entity definitions). Field types use TypeScript-ish notation; ? = optional. Every feed conforms to a JSON Schema under publication/schemas/.

Golden rules for every feed: (1) it carries an envelope with a status; (2) every factual value is traceable to source or omitted; (3) awaiting/planned/missing states are explicit; (4) routes are resolvable via routes.json; (5) enums are closed (below).


0 · Shared envelope

Every feed file is:

{
  "contract": "arrival",                 // feed id (matches file name)
  "version": "1.0.0",                    // semver of THIS feed's schema+content shape
  "status": "live|buildable|awaiting|future",
  "feedClass": "static|generated|live",  // mutability class (§8 model) — live is RESERVED, none today
  "publicationClass": "editorial|reference|generated|claim-bearing|live|structural", // approval routing
  "shape": "single|index|detail",        // scaling (§11 model) — "single" today; index/detail reserved
  "source": {                            // provenance of the generation
    "estateCommit": "<git sha | null>",  // markdown estate commit the feed was built from
    "editorialCommit": "<git sha | null>", // content/editorial commit (if the feed has authored parts)
    "graphHash": "<sha256 | null>",      // hash of portfolio-graph.json used
    "healthHash": "<sha256 | null>"      // hash of health.json used (if consumed)
  },
  "generatedAt": null,                   // null for determinism; stamped only at publish time
  "ttl": null,                           // seconds; ONLY set on live feeds (feedClass:"live")
  "page": null,                          // {index,size,nextPath} — only when shape implies paging (reserved)
  "data": { /* feed-specific payload */ },
  "missing": [ /* {entity|field, reason, status} awaiting/planned items */ ]
}

Feed classes (§8 model): static (authored, immutable) · generated (deterministic projection, immutable) · live (reserved — mutable, ttl set, unpinned, lives under live/ not publication/; none exist today). Publication classes route approval: reference/generatedauto-publishable; editorial/claim-bearing/livehuman-approved; structuralhuman + ADR.

Closed enums (validated everywhere)

Enum Allowed values
status (feed/item) live · buildable · awaiting · missing · planned · future
feedClass static · generated · live
publicationClass editorial · reference · generated · claim-bearing · live · structural
shape single · index · detail
maturity concept · early-development · active-development · operational · production · mixed
realization implemented · in-progress · planned · vision
entityType repository · capability · system · venture · adr · principle · operating-principle · glossary-term · technology · layer · architecture · governance · operating-model · current-state · intelligence-product · flagship-experience · evidence-plate · diagram · artefact · asset · extraction · finding · recommendation · action-item · knowledge-asset · draft · domain-brief · home · overview · registry · meta · doc
edgeType implements · providedBy · consumes · consumedBy · belongsToLayer · inLayer · inSystem · hasMember · usesTechnology · supportsRepository · relatesTo · relatedCapability · references
altitude (exhibit) value-chain · system-context · container · component · runtime · layer
spineRole knowledge · capability · product · application · venture · outcome
diagramFormat mermaid (only format today; extensible)
artefactType pack · api-contract · schema · diagram · score-model · digest · adr
docType how-to · reference · explanation

system vs venture (§10 model): system = internal repo grouping (Shared Skills, Intelligence Platform, Applications & Agents); venture = a business (Inexis Digital, Consulting, Inbound Lanka, City Retreats), reserved first-class, currently awaiting. flagship-experience was formerly “case study.”

Contradiction fix (2026-07-06, during Phase-0 implementation): home · overview · registry · meta · doc were added to the enum. routes.json and reference-library.json must type every page for link resolution, and these structural (non-entity) page types had no enum member. This is the one allowed kind of change (a discovered contradiction), recorded here and in site/scripts/publication/contract.mjs.

Shared sub-objects

// EntityRef — a resolvable pointer to any entity
{ "id": "cap-website-assessment", "type": "capability", "title": "Website Assessment Platform",
  "route": "/capabilities/cap-website-assessment" }

// EvidenceRef — provenance for any claim (see evidence-plates.json)
{ "plateId": "ep-wa-pack", "sourceRepo": "intelproducts",
  "sourcePath": "intelligence-packs/website-assessment/pack-manifest.md",
  "section": "#scoring", "status": "verified|awaiting|planned" }

// DiagramRef — a diagram exhibit (Mermaid source lives in the estate)
{ "id": "dg-wa-journey", "format": "mermaid", "altitude": "value-chain",
  "sourcePath": "portal/capabilities/cap-website-assessment.md", "status": "live" }

0b · canonical/spine.json (core, Tier A) — the single Platform Spine

Purpose: the one canonical value chain (§9 model). arrival, architecture-gallery, and story reference it by id; none may inline its own stages. feedClass:generated · publicationClass:reference.

Field Type Req Notes
data.id string platform-spine
data.stages[] SpineStage[] ordered, exactly 6
SpineStage.name string Knowledge · Capabilities · Intelligence Products · Applications · Ventures · Customer Outcomes
SpineStage.role spineRole knowledge/capability/product/application/venture/outcome
SpineStage.mapsToLayer string the architecture layer it maps to

Validation: spine-single-source — no other feed defines a stage list; referencing feeds carry spineRef:"platform-spine" only.


1 · manifest.json (core, Tier A)

Purpose: the index Lovable loads first — feed versions, statuses, and integrity. Lovable pins this.

Field Type Req Notes
publicationVersion string semver of the whole publication set
generatedAt string|null stamped at publish; else null
estateCommit string|null source commit
feeds FeedEntry[] one per feed
schemas { [feed]: string } path → JSON Schema
FeedEntry.id string feed id
FeedEntry.path string file path
FeedEntry.version string feed semver
FeedEntry.status status tier of the feed
FeedEntry.hash string sha256 of feed bytes (integrity)

Missing-data: a feed not yet built is listed with status:"awaiting" and hash:null. Validation: every destination feed referenced by Lovable MUST appear here; hash must match the file.


2 · routes.json (core, Tier A)

Purpose: single source of truth for link/route resolution (mirrors the site’s route resolver). Lovable uses it so no destination hard-codes a URL.

Field Type Req Notes
routes[].id string entity/page id
routes[].route string canonical path
routes[].entityType entityType
routes[].title string
routes[].contract string? destination feed that owns it (if any)
routes[].status status

Missing-data: an unresolved link target ⇒ validation error (routes must resolve, validation).


2b · navigation.json (core, Tier A) — the single navigation source

Purpose: the only navigation source Lovable consumes (§ review I-3). Lovable renders the menu/site-map from this; it never hard-codes structure. feedClass:generated · publicationClass:reference.

Field Type Req Source Notes
data.destinations[] NavDestination[] editorial+routes top-level portal destinations
NavDestination.id string e.g. flagship-experiences
NavDestination.label string editorial canonical display name (§8)
NavDestination.route string routes
NavDestination.order number editorial menu order
NavDestination.visibility "visible"|"hidden"|"future" future = shown as coming, not linked
NavDestination.feed string the destination feed it opens
NavDestination.sections NavSection[] routes sub-nav within a destination
NavSection.label,NavSection.route,NavSection.order
data.futureExpansion NavDestination[] reserved destinations (visibility:"future")

Missing-data: a future destination is listed with visibility:"future" and no live feed — Lovable shows it as “coming,” never links it. Validation: every route/feed resolves; exactly one nav source exists.


2c · search-index.json (core, Tier B) — the single search source

Purpose: the only search source Lovable consumes. Keyword search today; semantic-search compatible (reserved fields). feedClass:generated · publicationClass:reference.

Field Type Req Source Notes
data.documents[] SearchDoc[] graph+estate one per indexed entity
SearchDoc.id string graph
SearchDoc.type entityType graph
SearchDoc.title string graph
SearchDoc.route string routes
SearchDoc.text string estate excerpt indexed body
SearchDoc.keywords string[] frontmatter/derived
SearchDoc.aliases string[] glossary/editorial synonyms (e.g. “COP” → Commercial Opportunity)
SearchDoc.boost number editorial ranking weight (flagship/capability higher)
SearchDoc.crossRefs EntityRef[] edges related entities
SearchDoc.embeddingRef string? reserved future semantic vector id — unset today

Indexed entities: all reference entities + capabilities + flagship-experiences + ADRs + glossary + products. Missing-data: embeddingRef unset until semantic search exists (reserved, never faked).


3 · arrival.jsonArrival (Tier B, buildable)

Purpose: the 15-second first screen. Entity types: none (composed). Route: /. feedClass:generated · publicationClass:editorial (carries authored copy → human-approved).

Field Type Req Source Notes
data.eyebrow string editorial layer content/editorial/arrival.md
data.headline string editorial layer
data.lede string editorial layer
data.spineRef "platform-spine" canonical references canonical/spine.json — does NOT inline stages
data.scale Metric[] graph stats architectural only (no diagrams/edges)
Metric.num number graph real stat
Metric.label string e.g. “Reusable capabilities”
data.entries Entry[] editorial+routes journey/persona CTAs
Entry.label,Entry.route,Entry.journey string routes.json
data.cta.primary,data.cta.secondary {label,route}

Evidence: scale numbers must equal portfolio-graph.json stats (validation cross-checks). Canonical spine: spineRef only — inlining stages fails spine-single-source. Missing-data: N/A (all inputs live/editorial).


4 · story.jsonStory (Tier B, buildable)

Purpose: the guided narrative. Entity types: flagship-experience/diagram/entity refs. Route: /story. feedClass:generated · publicationClass:editorial. May reference the canonical spine via spineRef.

Field Type Req Source Notes
data.meta.readingMinutes number editorial layer
data.meta.stats Metric[] graph/health realised layers, capabilities, repos, health
data.meta.spineRef "platform-spine"? canonical reference only; never inline
data.chapters Chapter[] editorial layer + graph content/editorial/story/*
Chapter.n string “01”…“10”
Chapter.id string anchor
Chapter.eyebrow string editorial layer e.g. “Chapter 1 · The Problem”
Chapter.title string editorial layer
Chapter.lede string? editorial layer
Chapter.body Block[] editorial layer prose blocks (paragraph/list)
Chapter.takeaway string? editorial layer the single idea
Chapter.transition string? editorial layer bridge to next
Chapter.exhibits DiagramRef[] estate chapter diagrams
Chapter.facts Fact[] graph each with an EvidenceRef
Chapter.exploreLinks EntityRef[] routes “explore next”
Fact.claim string authored
Fact.evidence EvidenceRef estate required — a fact with no source is dropped

Evidence: every Fact carries an EvidenceRef; unsourced ⇒ omitted (§6.4 model). Missing-data: a chapter with no exhibits/facts still renders (prose-only).


Purpose: browsable grid of capabilities + ventures. Entity types: capability, venture. Route: /capabilities, /ventures.

Field Type Req Source Notes
data.items[] GalleryItem[] graph
GalleryItem.id string graph
GalleryItem.type "capability"|"system"|"venture" graph system=repo grouping · venture=business (§10)
GalleryItem.title string graph
GalleryItem.summary string graph excerpt
GalleryItem.layer string? frontmatter
GalleryItem.maturity maturity frontmatter honest label
GalleryItem.providers EntityRef[] edges providedBy capabilities
GalleryItem.consumers EntityRef[] edges consumedBy
GalleryItem.route string routes
GalleryItem.flagship boolean editorial Website Assessment = true
GalleryItem.flagshipRef EntityRef? flagship-experiences if a study exists

Missing-data: a capability without consumers ships consumers:[] (valid — reuse may be declared/planned).


6 · flagship-experiences.jsonFlagship Experiences (Tier B; first live, rest awaiting)

Purpose: flagship end-to-end showcases proving business value (formerly “Case Studies”). Entity types: flagship-experience. Route: /flagship-experiences/<id> (mirrors the capability page). feedClass:generated · publicationClass:claim-bearing (customer-facing claims → human-approved).

Field Type Req Source Notes
data.experiences[] FlagshipExperience[] capability estate + editorial layer
FlagshipExperience.id string e.g. fx-website-assessment
FlagshipExperience.capabilityRef EntityRef graph the capability it showcases
FlagshipExperience.title string
FlagshipExperience.problem string estate the business problem
FlagshipExperience.whyExistingFails string? estate
FlagshipExperience.approach string estate
FlagshipExperience.journey DiagramRef estate the primary end-to-end journey
FlagshipExperience.layers LayerStep[] estate/graph crosses which layers
FlagshipExperience.artefacts EvidenceRef[] evidence-plates real artefacts
FlagshipExperience.businessValue string[] estate
FlagshipExperience.decisions EntityRef[] ADRs/principles decisions that shaped it
FlagshipExperience.maturity MaturityBreakdown estate implemented/in-progress/planned split
MaturityBreakdown.{implemented,inProgress,planned} string[] estate honest
FlagshipExperience.status status Website Assessment=buildable, others=awaiting

Evidence: artefacts must resolve to evidence-plates.json entries with a real sourceRepo/sourcePath. Missing-data: only Website Assessment exists today; the array contains it, others are absent (not faked). Additional flagship candidates appear in missing[] with status:"awaiting".


Purpose: the architecture exhibits (diagrams at altitudes). Entity types: diagram, architecture. Route: /architecture/*.

Field Type Req Source Notes
data.exhibits[] Exhibit[] estate mermaid
Exhibit.id string
Exhibit.title string estate heading
Exhibit.altitude altitude value-chain/system/container/component/runtime/layer
Exhibit.diagram DiagramRef estate Mermaid source pointer
Exhibit.caption string estate
Exhibit.relatedEntities EntityRef[] graph
Exhibit.route string routes source page
Exhibit.canonical boolean editorial the “architecture in one picture” = true
Exhibit.spineRef "platform-spine"? canonical the canonical exhibit references the spine; never redefines it

Missing-data: N/A — diagrams are extracted from the estate (each has a source page). Canonical spine: the value-chain exhibit sets spineRef:"platform-spine" and carries no independent stage list (spine-single-source).


8 · intelligence-products.jsonIntelligence Products (Tier C, awaiting)

Purpose: the versioned packs the platform publishes. Entity types: intelligence-product. Route: /intelligence-products/<id> (planned).

Field Type Req Source Notes
data.products[] Product[] intelproducts pack manifests feed status awaiting
Product.id string e.g. website-assessment-pack-v1
Product.name string
Product.version string manifest
Product.immutable boolean true
Product.domains string[] manifest
Product.ruleCount number? manifest
Product.consumers EntityRef[] graph edges
Product.maturity maturity digest
Product.evidence EvidenceRef[] evidence-plates
Product.status status

Missing-data: until intelproducts exports pack manifests as a feed, this ships with a minimal record for website-assessment-pack-v1 authored from its capability digest (15 rules · 6 domains · REC-001…015), status:"awaiting", and all other packs in missing[]. No pack internals are invented.


9 · reference-library.jsonReference Library (Tier A, live)

Purpose: the searchable index of every reference entity. Entity types: repository, capability, venture, adr, principle, operating-principle, glossary-term, technology, layer, architecture. Route: the entity’s own route.

Field Type Req Source Notes
data.collections { [entityType]: RefItem[] } graph grouped
RefItem.id string graph
RefItem.title string graph
RefItem.type entityType graph
RefItem.excerpt string? graph
RefItem.status status frontmatter
RefItem.maturity maturity? frontmatter where applicable
RefItem.route string routes
RefItem.relationships Relationship[] edges typed
Relationship.type edgeType edges
Relationship.target EntityRef edges

Missing-data: an entity with no relationships ships relationships:[]. This feed is a direct projection of the graph — it never adds entities the graph lacks.


10 · engineering-manual.jsonEngineering Manual (Tier B, buildable)

Purpose: the how-to / governance / operating reference. Entity types: governance, operating-model. Route: /governance/*, /operating-model/*.

Field Type Req Source Notes
data.sections[] Section[] estate
Section.id string
Section.title string estate
Section.purpose string estate one-line
Section.kind "governance"|"operating-model"
Section.docType "how-to"|"reference"|"explanation" frontmatter type
Section.route string routes
Section.steps string[]? estate for how-to pages
Section.relatedDecisions EntityRef[] ADRs

Missing-data: a section with no steps (reference page) ships without steps — valid.


11 · living-platform.jsonLiving Platform (Tier D, future; snapshot buildable)

Purpose: operational awareness — Health, Current State, Roadmap, Changelog. The static snapshot is a generated feed, buildable now; the interactive/streaming layer is a reserved live feed (§8, future). Route: /health, /current-state/*.

Field Type Req Source Notes
data.health HealthSnapshot health.json deterministic snapshot
HealthSnapshot.scores {documentation,repositoryHealth,capabilityHealth,overall} health
HealthSnapshot.coverage object health per entity type
HealthSnapshot.workQueue {total,bySeverity,byType,items} health
data.currentState StateItem[] current-state estate status dashboard
data.roadmap RoadmapItem[] roadmap estate each labelled planned
data.changelog ChangelogEntry[] changelog estate newest first
data.liveFeatures Feature[] all status:"future" (streaming, agent updates)
Feature.name,Feature.status string,"future" never rendered as available

Missing-data: liveFeatures are declared future — Lovable renders them as “planned,” never live. The Hermes learning loop and orchestrator automation appear here only as future.


12 · evidence-plates.jsonEvidence Plates (Tier B, buildable)

Purpose: the provenance store every destination references for real artefacts/claims. Entity types: evidence-plate, artefact.

Field Type Req Source Notes
data.plates[] EvidencePlate[] estate citations
EvidencePlate.id string e.g. ep-wa-pack
EvidencePlate.claim string estate the assertion
EvidencePlate.artefactType "pack"|"api-contract"|"schema"|"diagram"|"score-model"|"digest"|"adr"
EvidencePlate.sourceRepo string? estate
EvidencePlate.sourcePath string? estate file/section
EvidencePlate.quote string? estate verbatim citation
EvidencePlate.status "verified"|"awaiting"|"planned" verified needs a resolvable source
EvidencePlate.destinations string[] which feeds cite it

Rule: a plate with status:"verified" must have sourceRepo+sourcePath. No source ⇒ awaiting, and its claim may be shown only as an awaiting placeholder. This is where “no invented evidence” is enforced.


13 · Worked example — arrival.json (illustrative, real values)

Shows the envelope + a real feed. Numbers are the actual current graph stats; copy is editorial. This is an example of the shape, not a published artefact.

{
  "contract": "arrival",
  "version": "1.0.0",
  "status": "buildable",
  "feedClass": "generated",
  "publicationClass": "editorial",
  "shape": "single",
  "source": { "estateCommit": null, "editorialCommit": null, "graphHash": null, "healthHash": null },
  "generatedAt": null,
  "ttl": null,
  "page": null,
  "data": {
    "eyebrow": "Architecture platform · not documentation",   // from content/editorial/arrival.md
    "headline": "The operating manual for a layered AI venture ecosystem.",
    "lede": "Not a collection of AI projects — one architecture …",
    "spineRef": "platform-spine",                             // references canonical/spine.json — NOT inlined
    "scale": [
      { "num": 7,  "label": "Reusable capabilities"   },      // real graph stats
      { "num": 4,  "label": "Architecture layers"     },
      { "num": 7,  "label": "Repositories"            },
      { "num": 7,  "label": "Architecture decisions"  },
      { "num": 21, "label": "Governing principles"    }
    ],
    "entries": [
      { "label": "Executive overview", "route": "/overview", "journey": "executive" },
      { "label": "Software Engineer",  "route": "/repos",    "journey": "technical" }
    ],
    "cta": {
      "primary":   { "label": "Start the guided tour", "route": "/story" },
      "secondary": { "label": "Executive overview",    "route": "/overview" }
    }
  },
  "missing": []
}

The canonical platform-spine (Knowledge → Capabilities → Intelligence Products → Applications → Ventures → Customer Outcomes) lives once in canonical/spine.json; arrival/story/architecture-gallery reference it. An awaiting feed (e.g. intelligence-products.json) has the same envelope with status:"awaiting", data.products seeded only with the documented website-assessment-pack-v1 record, and the rest in missing[] — never invented.

14 · Destination → feed → entity map (index)

Lovable destination Feed file Primary entities Tier
Arrival arrival.json (composed) spineRef + stats B
Story story.json chapters, facts, diagrams B
Portfolio Gallery portfolio-gallery.json capability, system, venture A/B
Flagship Experiences flagship-experiences.json flagship-experience B (1 live)
Architecture Gallery architecture-gallery.json diagram, architecture A/B
Intelligence Products intelligence-products.json intelligence-product C awaiting
Reference Library reference-library.json all reference entities A
Engineering Manual engineering-manual.json governance, operating-model B
Living Platform living-platform.json health, current-state, roadmap D (snapshot B)
(cross-cutting) canonical/spine.json, navigation.json, search-index.json, evidence-plates.json, routes.json, manifest.json, portfolio-graph.json, health.json A/B