Aller au contenu

Sense 64 — The Docent: the tour as a declaration

Ce contenu n’est pas encore disponible dans votre langue.

Sense 64 · In bloom · Last touched 2026-08-20

  • last_verified: 2026-07-27

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

Status: Phase 1 SHIPPED 2026-07-22 (declare + check + compile + bake + /tour render). Phases 2–4 proposed. Named “The Docent” as a placeholder (Mig’s to keep or rename, as with the Reservoir). Emerged 2026-07-19 from building Delta Basin’s hand-over presentation and realizing the tour was trivially declarable.

Phase 1 realization: a tour is a Dossier whose members are routes, so it reuses that machinery — tour/*.yaml (new tour AFS artifact type), tourcheck.py + tourcompile.py emitting tour_registry + tour_stops beside the Dossier registry (models/smebits/, smebit tag, zero dbt_project changes), wired into make after BitBundle compile. JinDesk /[tenant]/tour route renders the first-visit tour as a readable guided path (title + intro + ordered stop cards, each a four-locale why + tenant-relative link + optional notice). Delta’s tour_delta_first_visit (6 stops) is the first. The guided overlay that navigates JinDesk for you is Phase 2.

Kin: Sense 13 The Canvas (form follows data — any perspective is a declaration); the showcase tutorials (Delta); the Selection bus / Sense 63 The Satellites.

The Sense: a guided tour is not something you write about a tenant — it is something the tenant declares, and the platform renders. A museum has docents: authored guides who lead a visitor stop by stop and explain what they’re looking at. Every jinflow tenant can have one, written in YAML, in four languages, offered inside JinDesk itself.

Onboarding becomes metadata: tour/*.yaml in the AFS declares an ordered path through the tenant — each stop a destination plus a why — and JinDesk walks a first-time visitor along it, narrating in place.

We built a deep hand-over presentation for Delta Basin — an HTML page and a docs showcase, both good, both authored by hand about the tenant. Then the realization: the presentation is nothing but an ordered list of stops. Stop 2 is “the diamond — open the firmware thesis, here’s why it matters.” Stop 4 is “Observations — here’s the differentiator.” Each is a destination, a title, and a paragraph. That is a declarable structure. And declaring it is more jinflow than writing it, because the tour of a tenant is domain knowledge — it belongs in the AFS beside the signals and theses, authored by whoever built the tenant, not hand-coded by whoever happened to make the demo.

The same move Sense 13 made for analytical perspectives (“a YAML declaration, not a Svelte file”), applied to the first five minutes a visitor spends.

A tour is a Dossier whose members are routes instead of Subject Matter. The machinery is ~80% already built — note/dossier baking, tenant-relative link rewriting, four-locale authoring.

afs/tour/tour_delta_first_visit.yaml
tour_id: tour_delta_first_visit
title: { en: "Start here", de: "Beginnen Sie hier", ... }
intro: { en: "The fleet is already telling you something…", ... }
audience: visitor # optional variants: cto | field_team | reviewer
stops:
- title: { en: "The overview — the fleet at a glance", ... }
to: / # a route, tenant-relative (Sense-13.1 grammar)
why: { en: "Four tiles, and none is just a number…", ... }
notice: { en: "Click the red finding sliver.", ... } # optional highlight
- title: { en: "The diamond — from what to why", ... }
to: /theses/thesis_firmware_field_discipline
why: { en: "It asks a plain question and names the cause…", ... }
- title: { en: "Observations — hunches weighed against data", ... }
to: /observations
why: { en: "The part no dashboard has…", ... }
selection: # optional — the docent scopes as it explains
anchor: Sensor
ids: [S001, S039, S055]
# …
  • to uses the bare tenant-relative grammar (Sense 13.1) so a tour is portable across tenants where the routes line up.
  • why / notice are the docent’s voice — prose, four-locale, the thing a first-timer needs to know at that stop.
  • selection (the lovely part) lets a stop carry a Selection onto the bus, so the docent doesn’t only navigate — it scopes the view as it speaks (“these three sensors are the field-visit shortlist”). This is where the Docent meets The Satellites: a tour is a scripted sequence of Selection + navigation events.

Two candidate renders; the second is the real one.

  1. A declared page (cheap first slice). The tour bakes into a registry like any page; a /tour route lists the stops as a readable path with links. This is the docs-showcase experience, in-product. Ships on existing page machinery.
  2. The guided overlay (the Docent proper). A “Start here” affordance on the tenant landing opens a slim rail that navigates JinDesk for you — go to the stop, surface its why beside the real page, apply its selection, and offer “next.” The visitor sees the actual product, guided, not a slideshow of it. Chrome stays minimal; the rail is dismissible; the URL stays shareable at every stop (so a visitor can leave the tour and keep exploring from exactly where they stood).
  • Per-tenant, by the author who knows. Delta declares Delta’s tour; Inspire and Val d’Oria theirs. The engine renders whatever’s declared — it holds no tenant-specific tour code.
  • Four languages, one source, like every other artifact.
  • Versioned, git-tracked, provenance-bearing — the tour travels in the KLS’s self-describing AFS archive, so a published showcase carries its own guide.
  • Adding a stop is a YAML edit + make. The demo script stops being a thing someone re-writes each release and becomes a thing that rebuilds with the tenant.

A tour now lives in three complementary forms, each with a purpose:

FormPurposeStatus
HTML presentationthe designed leave-behind you hand overauthored per-demo (artifact)
Docs showcasethe durable, searchable referenceshipped (showcase-delta)
Declared in-product touronboarding the platform offers itselfthis Sense
  • Not a replacement for the docs showcases (reference) or the hand-designed leave-behind (marketing). It is the third, most-integrated form.
  • Not a general slideshow/presentation builder — a tour points at real routes in this tenant, nothing free-floating.
  • Not analytics or product-tour telemetry (who-completed-what). A later concern if ever.
  1. Declare + bake + /tour render — tour/*.yaml, a tourcheck / tourcompile, a registry, and a readable stop-list page. Delta authors the first tour (lift it straight from the presentation). SHIPPED 2026-07-22. Open follow-ups: surface /tour in nav + a first-visit landing prompt (the “Probably both” of open question 3); created_at backfill on the tour YAML; a tourcompile unit test.
  2. The guided overlay — the docent rail that navigates + narrates in place, URL-stable per stop.
  3. selection stops — the docent scopes the view as it explains (bus integration, Sense 63 kinship). Spec: Selection Stops (Docent as bus source not sink; data path already 80% baked; three decisions pending Miss EDA).
  4. Audience variants — for the CTO vs for the field team vs for a reviewer, the same stops re-weighted; a visitor picks their lens.

The Warrant (orthogonal capability, any phase) — a tour that knows whether it is still true. A stop carries a checkable expect claim; jin make verifies it against the live KLS and flags a stop whose story the data has left behind, so a showcase cannot silently rot. Spec: The Warrant.

  1. Render as a declared page (reuse Sense 13 V3) or a bespoke overlay from the start? Slice 1 favors the page; the overlay is the destination.
  2. Can a stop target a specific artifact (a finding, an observation) as cleanly as a route? The tenant-relative grammar already addresses most; deep artifact anchors may want the anchor shape Observations use.
  3. Should the tour be discoverable in nav (a declared page auto-surfaces) and as a first-visit prompt? Probably both, gated so returning visitors aren’t nagged.
  4. One tour per tenant, or many (a firmware tour, a watershed tour)? Many, by the same logic as many dossiers — but a designated first_visit tour is the default the landing offers.

Numerical neighbors: ← Sense 63 — The Satellites: connected windows

jazzisnow jinflow is a jazzisnow product
v0.65.0 · built 2026-11-13 10:20 UTC