Sense 17: The House

Sense 17 · Folded in · Last touched 2026-08-20

Folded into Sense sense-42-the-landscape.

• last_verified: 2026-06-01

Synced from docs/design/sense_17_the_house.md in the engine repo — that’s the source; this page is a build-time mirror.

You don’t understand a home by reading the floor plan. You understand it by walking through the front door.

Status: proposed Author: the owner + Claude (inspire walkthrough, 2026-04-15/16; renamed 2026-05-14)

Renamed 2026-05-14. Originally “The Cathedral”, to match the 3D pipeline page’s first internal codename. As that page evolved into a warmer, more intimate guided walk-through — and the sidebar label became “Our House” — the older metaphor felt overwrought. The substance is unchanged: a guided, narrated walk-through of the tenant’s analytical pipeline. Only the framing word moved from “cathedral” (grand, formal) to “house” (lived-in, ours). Cross-tab navigation, which used to be lumped under this Sense in practice (BroadcastChannel("jinflow-cathedral")), is now Sense 34 “The Breeze”.

---

What pulled us in

The Pipeline page (/{tenant}/system/pipeline) is a 2D Cytoscape graph. It is correct, detailed, searchable, filterable — and overwhelming. Two hundred nodes. Three hundred edges. A tangle of rectangles connected by lines. The expert can trace lineage through it; the CFO cannot tell what it means.

The current 3D implementation (“Our House” — internally codenamed “Cathedral” when shipped 2026-04-12) translates the same tangle into Three.js with FPS controls. It is beautiful. But it inherits every problem of the 2D graph plus a new one: the user doesn’t know where to look or how to move. WASD + mouse-look is a game mechanic, not a communication tool. The house is a tech demo, not an experience.

The gap:

What exists	What’s needed
All nodes visible at once	Progressive reveal, layer by layer
FPS controls (WASD + mouse)	Guided camera on a scripted path
No text, no narration	Contextual panels explaining each layer
Raw node IDs on hover	Rich detail cards with findings, severity, links
Dark, fog, dust — atmospheric but intimidating	Inviting, celebratory — look at what we built together
Same view for every tenant	Adapts to the tenant’s actual data
Viewer is a pilot	Viewer is a passenger on a tour

The Principle

A home is not a warehouse.

A warehouse stores things and lets you find them if you already know what you’re looking for. A home welcomes you and walks you through a story. The layout tells you where things belong. The light tells you what’s alive. The framed pictures explain who lives here.

Our House should be a guided, narrated 3D walk-through of the tenant’s analytical pipeline. Not a debug tool. Not a graph explorer. A story about the data — where it comes from, what we did to it, what we found, and what it means.

The Tour

The camera moves on a scripted path — stops along a rail, one per major layer group. At each stop, the camera parks at a vantage point, the relevant nodes illuminate, and a narration panel explains what the user is seeing. The user clicks Next to advance, Back to revisit.

Stops (proposed)

#	Name	Layers visible	Narrative
0	Welcome	None (title card)	“Welcome to {tenant_display_name}. This is the story of your data.” Overview: how many models, signals, theses.
1	The Foundation	Gold	”Your data starts here — {N} Gold entities, the clean, validated facts.” Highlight the three Gold sub-groups: Clinical Volume, Master Data, Reference. Entity counts from the live KLS.
2	The Signals	Gold + Signal	”We asked {N} questions about your data.” Signals light up, connected to their Gold sources by edges. Findings count per signal. Color by severity or polarity.
3	The Perspectives	+ Perspective	”Perspectives aggregate signals into entity-level health views.” Show how perspectives sit above signals. Entity coverage stats.
4	The Theses	+ Thesis	”Theses are the business questions: ‘Are we losing money on unbilled materials?’” Show confirmed/plausible/not_observed distribution. Evidence chains glow.
5	The Verdicts	+ Verdict	”When a thesis is confirmed, a verdict explains why.” Root cause categories. Confidence. Recommendations.
6	Expert Knowledge	+ SMEbit + Dossier	”Not everything is in the data. {N} pieces of expert knowledge anchor the analysis.” Dossier narrative groupings.
7	The Full Picture	All layers	Camera pulls back to show the entire house. “This is your analytical pipeline. {total_models} models. {total_signals} signals. {confirmed}/{total_theses} theses confirmed.”

Between Stops

The camera glides between stops on a smooth curve (cubic Bezier or CatmullRom spline). During the glide, the new layer’s nodes fade in while the narration panel transitions. No instant teleportation — the motion itself tells the user they’re moving forward through the pipeline.

Controls

Control	Effect
Next (arrow / spacebar / click panel)	Advance to next stop
Back	Return to previous stop
Explore (toggle)	Leave the rail. Unlock FPS controls for free exploration from the current position. A “Back to Tour” button returns to the last stop.
Stop indicator	Dots at the bottom (like a slideshow) showing 0–7 position. Clickable for random access.

No WASD by default. No click-to-enter pointer lock. The tour starts automatically. Exploration is opt-in for advanced users.

Narration Panels

Each stop renders a panel anchored to the viewport (not the 3D scene). The panel contains:

• Title — layer group name (e.g., “The Signals”)
• Body — 2–3 sentences of tenant-specific narrative. Uses live data: finding counts, severity distribution, confirmed thesis count, entity coverage, etc. Tri-lingual (EN/DE/FR) via the same i() mechanism.
• Stats bar — compact KPIs relevant to this stop (e.g., at Stop 2: “39 signals · 1,247 findings · 812 high-severity”)
• Detail drill — clicking a glowing node during a stop opens a detail card (display name, type, finding count, severity, money at risk, link to JinDesk page). The card overlays the panel, not the scene.

Atmosphere

The current dark-fog-dust atmosphere reads as ominous. The house should feel inviting — the user is being shown something impressive that was built for them, not warned about a threat.

Proposed:

• Background: deep navy gradient, not black. Subtle animated gradient shift (slow hue rotation, barely perceptible).
• Lighting: warm directional from above (sun through a skylight), soft ambient fill. Nodes cast soft glows, not hard shadows.
• Particles: golden dust motes drifting slowly. Celebratory, not industrial.
• Node appearance: soft spheres with warm emissive glow per-layer color. Active nodes (with findings) pulse gently. Inactive nodes are translucent — present but not demanding attention.
• Edges: thin, curved, subtly animated (a slow pulse traveling along the curve from source to target). Not all visible at once — only edges connected to visible layers appear.
• Signposts: layer labels emerge from the scene as the camera approaches, not as fixed HUD elements. Feels like discovering something, not reading a dashboard.
• Sound (optional, off by default): ambient tone that shifts with each stop. Not music — a presence. Toggle with a speaker icon.

Data Contract

The tour needs more data than the raw graph JSON. A tour manifest extends the graph data with per-stop narratives and stats:

{
  "graph": { "elements": [...] },
  "tour": {
    "tenant_display_name": "Inspire",
    "stops": [
      {
        "id": "welcome",
        "title": { "en": "Welcome", "de": "Willkommen", "fr": "Bienvenue" },
        "body": { "en": "Welcome to Inspire. This is the story of your data." },
        "stats": { "total_models": 94, "total_edges": 747 },
        "layers_visible": [],
        "camera": { "position": [0, 60, 200], "lookAt": [0, 0, 0] }
      },
      {
        "id": "foundation",
        "title": { "en": "The Foundation" },
        "body": { "en": "Your data starts here — 22 Gold entities..." },
        "stats": { "entity_count": 22 },
        "layers_visible": ["gold"],
        "camera": { "position": [-20, 30, 80], "lookAt": [0, 0, -40] }
      }
    ]
  }
}

Generated during jin make by generate_pipeline_graph.py, stored as a fourth artifact (graph_tour_json) alongside graph_json, graph_html, and graph_3d_html. The tour narratives are templated — {N} placeholders filled from the stats at generation time. Tri-lingual strings come from i18n keys in the generator.

Relationship to Other Features

• Pipeline page (2D): stays as-is — the expert’s tool for lineage tracing and source inspection. Our House links to it (“Open in Pipeline”) for drill-down.
• About page: shows provenance and build stats. Our House’s “Full Picture” stop (Stop 7) echoes those numbers but in a spatial, experiential way.
• Reports (PDF): the tour could eventually be captured as a series of screenshots for a “visual pipeline report”. Deferred.

Implementation Phases

Phase 1 — The Rail (scripted camera + narration)

Replace FPS controls with a stop-based tour. Hard-coded 8 stops. Hard-coded camera positions. Plain HTML overlay panels with static text. No detail cards yet. Reuse the existing Three.js scene and node geometry.

Deliverable: clicking “3D” in the sidebar takes you on a guided walk-through that ends in 60 seconds. No WASD knowledge required.

Phase 2 — Live Data + Detail

Wire the narration text to live KLS stats (finding counts, thesis verdicts, entity coverage). Add detail cards on node click. Generate the tour manifest during jin make.

Deliverable: each stop’s narrative is tenant-specific. Clicking a glowing node shows its findings and links to JinDesk page.

Phase 3 — Atmosphere + Polish

Gradient background, warm lighting, golden particles, edge animations, signpost reveal. Camera glide curves. Explore-mode toggle. Optional ambient sound. Responsive (works on iPad).

Deliverable: Our House feels like a product, not a prototype.

How this manifests in jinflow

Folded into a later sense. Status: folded in. See the status note at the top of this page (or the absorbing sense in the sidebar) for where the concept now lives.

---

Open Questions

1. Stop count: 8 stops is a full tour (~60s). Should there be a “short tour” (3 stops: Gold → Signals → Full Picture) for impatient users?
2. Entry point: sidebar → 3D. Should the About page also link to it? (“Take the tour”)
3. Auto-play vs click-to-advance: should the tour auto-advance on a timer (like a slideshow), or wait for user interaction?
4. Mobile: FPS controls don’t work on touch. The guided tour does (it’s just Next/Back). Should mobile be a first-class target?
5. Offline / PDF: can the tour be “played” as a sequence of pre-rendered frames in a PDF report? Worth designing for?
6. Sound: ambient sound in a data tool — delightful or annoying? Off by default is safe, but should it be offered at all?
7. Naming: “Pipeline Cathedral” was a fun internal name. Is it the product name? Resolved 2026-05-14: renamed to “Our House” in the sidebar; this Sense doc renamed to “The House”.

---

Numerical neighbors: ← Sense 16: P2P2P — Peer-to-Peer-to-People · Sense 18: The Ledger — Computational Provenance as Narrative →