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.mdin 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.
The idea, in one line
Section titled “The idea, in one line”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.
What pulled us in
Section titled “What pulled us in”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.
The shape
Section titled “The shape”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.
tour_id: tour_delta_first_visittitle: { en: "Start here", de: "Beginnen Sie hier", ... }intro: { en: "The fleet is already telling you something…", ... }audience: visitor # optional variants: cto | field_team | reviewerstops: - 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] # …touses the bare tenant-relative grammar (Sense 13.1) so a tour is portable across tenants where the routes line up.why/noticeare 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.
The render surface
Section titled “The render surface”Two candidate renders; the second is the real one.
- A declared page (cheap first slice). The tour bakes into a registry like
any page; a
/tourroute lists the stops as a readable path with links. This is the docs-showcase experience, in-product. Ships on existing page machinery. - 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
whybeside the real page, apply itsselection, 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).
Why declared, not authored
Section titled “Why declared, not authored”- 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.
The three homes (this completes the set)
Section titled “The three homes (this completes the set)”A tour now lives in three complementary forms, each with a purpose:
| Form | Purpose | Status |
|---|---|---|
| HTML presentation | the designed leave-behind you hand over | authored per-demo (artifact) |
| Docs showcase | the durable, searchable reference | shipped (showcase-delta) |
| Declared in-product tour | onboarding the platform offers itself | this Sense |
Non-goals
Section titled “Non-goals”- 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.
Phases
Section titled “Phases”- Declare + bake +
/tourrender —tour/*.yaml, atourcheck/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/tourin nav + a first-visit landing prompt (the “Probably both” of open question 3);created_atbackfill on the tour YAML; atourcompileunit test. - The guided overlay — the docent rail that navigates + narrates in place, URL-stable per stop.
selectionstops — 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).- Audience variants —
for the CTOvsfor the field teamvsfor 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.
Open questions
Section titled “Open questions”- 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.
- 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.
- 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.
- One tour per tenant, or many (a firmware tour, a watershed tour)? Many, by
the same logic as many dossiers — but a designated
first_visittour is the default the landing offers.
Numerical neighbors: ← Sense 63 — The Satellites: connected windows