Onboarding — diegetic Bertranda walkthrough as Quest 001 beat 1

D-027: Onboarding — diegetic Bertranda walkthrough as Quest 001 beat 1

Round 4 pick 14 from the 2026-05-21 vision verification session. D-024 ratified the 6-region linear-saga structure; D-026 deferred per-class notification opt-in here; D-019 ratified 5 classes one-per-faction but left the in-game selection moment unspecified; D-022 §1 ratified the live-rewriting Map but the first-impression-of-Map moment was unauthored. D-027 closes onboarding-shape canon under one move: there is no meta-tutorial; onboarding IS Quest 001 beat 1, expanded to absorb the cold open (Bertranda hands Map → motto → 50-step register the hand → class registration).

D-level because the cold open absorbs ~7 distinct design surfaces — sign-in, attestation permission, Map widget first impression, motto delivery, class selection, notification opt-in, tab-unlock state machine — under one diegetic flow. Authoring those surfaces separately produces drift at the seams (ui-designer’s tutorial flow + narrative-designer’s quest authoring + tech-architect’s auth/permission gating diverging). D-027 locks the flow shape so the surfaces converge at one beat.

1. Onboarding IS Quest 001 beat 1 — no meta-tutorial

The current Quest 001 beat 1 (data/src/content/quests/quest-001-first-road.ts) — “Meet Bertranda Dot-Wells in the Head Scribe’s office. Receive the wooden Cech ring, the pocket map of the Plenny-Domek Mostkowy region, and one envelope sealed in brown wax” — is the canonical first-Walker experience. D-027 ratifies that beat 1 EXPANDS to absorb the cold open per §2; it does NOT add a separate “tutorial” flow outside the quest grammar.

No meta-tutorial: there is no skippable / hideable / outside-diegesis tutorial overlay. The Walker’s first action in the app is, canonically, accepting the Cech ring. Anything the player needs to learn is taught through Bertranda’s dialogue, the Map widget’s behaviour, and quest-beat progression. Coaching tooltips on tap targets are forbidden; affordance-by-design is the canon.

Beat-1-as-onboarding is editorial: the Quest 001 beat 1 content currently authored stays canonical. D-027 amends the ENVELOPE of beat 1 (the cold-open prefix per §2) and the beat-1-complete side effects (per §3 class selection, §5 streak day-1, §6 tab unlocks, §7 notification opt-in). Specific Bertranda dialogue expansion is narrative-designer W-level.

2. Cold-open beats (canonical cadence)

Order of operations, first launch to Quest 001 beat 1 complete:

#	Step	Anchor	Notes
0	Splash + locale auto-detect	D-011 (chrome ENG default; PL/EN locale follows OS unless overridden in Settings)	Player may pick locale in Settings post-onboarding; default is OS locale.
1	Sign-in (Firebase Auth: Google / Apple / Email)	D-008 §1, D-009 §1 (Apple Sign-In mandatory on iOS when other providers present)	Required before any step data persists; gating is platform-spec.
2	HealthKit / Health Connect permission prompt	D-007 §3 (attestation requires platform API access)	Must be granted before step 5 register. Refusal = onboarding cannot complete; Walker sees diegetic Bertranda framing (“the Cech cannot register a hand it cannot count”).
3	Bertranda hands the Map	D-012 (defining-image: the self-rewriting map)	The cosmic defining-image becomes the first physical artefact the Walker holds. Quest 001 beat 1 narrative authors the moment.
4	Two beats of `„Każdy krok piszemy do końca"`	D-013 (Cech motto, operative verb `piszemy`)	Motto delivered as two Bertranda half-sentences (per Bertranda’s canonical incomplete-sentence character beat — see Quest 001 beat 1: “Bertranda does not finish any of her sentences”).
5	”Register the hand” — 50 steps	D-007 §2 (per-day attestation), D-013 (editorial-commit grammar), D-022 §1 (Map as live gameplay surface)	50-step bar within the active app session. Map widget visibly responds during the bar — specific animation cadence (per-step vs per-bar-segment vs at-bar-completion) is ui-designer + mobile-developer W-level per D-022 §What-not-decide. Bar completion = first attested day per §5; streak clock starts.
6	Notification opt-in surface	D-026 §What-not-decide (closed here per §7)	Bertranda asks “which messages should the Cech register?”; player toggles 6 per-class options. OS-level notification permission prompt fires lazily on first-ON toggle.
7	Class selection surface	D-019 §1 + §3 (per §3)	Bertranda frames the moment as registering the Walker’s hand with the Cech via one of five practitioner stances.
8	Quest 001 beat 1 closes	D-024 §1 (Plenny saga first beat)	Receive Cech ring + envelope; beat 1 closes; Quest 001 continues with beat 2 (South Gate departure).

The 50-step bar (step 5) is the canonical onboarding gate. It is NOT a target the Walker can fail — they can be on a treadmill, walking around the house, or out the door. The bar’s purpose is the Map’s first redraw moment (D-022 §1 made literal) and the editorial-commit-grammar first impression (D-013 ratified at the surface).

Authentication / permission failure paths: if sign-in fails or HealthKit/HC permission is refused, Bertranda’s diegetic framing surfaces — “the Cech cannot register a hand it cannot count” — and the Walker is invited to retry. There is no “skip” affordance; without attestation, the game does not begin. This matches D-007 §3 anti-cheat posture.

3. Class selection — post-beat-1, diegetic registration

Quest 001 beat 1 closes with class selection (step 7 of §2). Bertranda’s dialogue (narrative-designer W-level) frames the moment as the Walker registering their hand with the Cech via one of five practitioner stances — D-019’s 5 classes, one per faction:

class.cartographer (Cech home faction; PL Kartograf, default if no choice / “stay with the Cech”). Per D-019 §2 + §Reasoning, the Cech class deliberately uses the Kartograf naming asymmetry (NOT Pisarz) — Pisarz Cechu is a faction rank inside the Cech, not the class itself. Re-litigating this would require superseding D-019.
class.pieczetarz (Akademia)
class.pielgrzym (Bractwo)
class.komiwojazer (Wolnokupiectwo)
class.tropiciel (Dziki Trakt)

The four non-Cech class files (pieczetarz / pielgrzym / komiwojazer / tropiciel) are mechanics-designer + narrative-designer W-level follow-up per D-019 open follow-ups (must ship same MR as glossary entries per D-017 wave 3+ pattern; pick one shape per Class.startingClusterId call). Until those four files ship, the class-selection surface in onboarding may render the four non-Cech options as preview-only with a “coming in next saga” diegetic affordance — narrative-designer + ui-designer joint W-level. The Cech default path is fully available from Phase 13.

Why post-beat-1: the Walker has now received the Cech ring + Map + envelope + walked 50 attested steps + heard the motto delivered in two half-sentences. They have physical, lore-anchored grounding in the Cech before being asked to commit to a metaphysical stance. Class selection is the first commit-able act of identity — D-013’s editorial register at the player-identity layer. Choosing class.cartographer (Cech) reads as “stay with the Cech”; choosing any other reads as “the Cech registered my hand, but my walking discipline is another faction’s.”

No “no-class” path: the Walker cannot exit onboarding without a class selection. Default is class.cartographer (Cech home class) — equivalent to the “registered Cech apprentice” identity. This is canon; class rebind via faction reputation (D-019 §4) happens LATER in the game, never at this beat.

Starting cluster: class selection at this beat anchors the Walker’s per-class entry cluster of the shared tree (D-019 §3). Until class is picked, no starting cluster is set; Tree tab cannot unlock (per §6 tab gate). Whether the storage shape is a schema field (Class.startingClusterId) or a JSDoc convention remains tech-architect W-level per D-019 §What-not-decide; D-027 ratifies that the selection moment SETS the value, not the storage shape.

4. The 50-step bar is real attestation, not tutorial

The 50 steps the Walker walks during step 5 of §2 are real HealthKit / Health Connect-attested steps. They count toward:

The day’s Energy budget (D-018 — 50 Energy if no streak bonus; first-day-of-streak math at §5).
The day’s step count for streak attestation (D-007 §2 — yes, this attested day satisfies the day-1 attestation invariant per §5).
The Map widget’s first visible response — the curvatures of the Plenny ↔ Domek Mostkowy first-quest region update per D-022 §1 (animation cadence per D-022 §What-not-decide W-level).

If the player legitimately walks 50 attested steps during onboarding, those steps are not “tutorial steps” — they are the first commits to the Spis (D-013 grammar). The mechanics layer treats them identically to any other 50 attested steps. This is the load-bearing design move: no separate tutorial data path = no drift between tutorial state and real state = no anti-cheat edge case at the tutorial / real boundary.

5. Streak day-1 starts at 50-step register

D-007 §2 ratified that streak decays on missed attested day. D-027 ratifies that the day Quest 001 beat 1 step 5 completes IS the Walker’s first attested day. The 7-day streak +20% milestone is reachable on the day onboarding + 6 subsequent attested days. The 30-day +50% milestone is reachable on the day onboarding + 29 subsequent attested days.

Edge case — late-night onboarding: if the Walker completes onboarding at 23:55 local time and then walks the next attested calendar day (00:00+), streak day-2 starts at midnight local. The 5-minute day-1 is fully canonical — it is still an attested day. This matches D-007 §2’s per-day attestation invariant strictly; no special-case “5-minute day doesn’t count” exists. Anti-cheat heuristics for distinguishing honest late-night onboarding from TZ-jump exploitation (a clock-rotation attacker compressing streaks across forged midnights) are tech-architect W-level per D-007 §3; D-027 ratifies the canonical case (honest 23:55 onboard = real day-1), not the adversarial surface.

Bertranda framing at streak day-1 close: if the Walker remains in-app at midnight local on day-1 and has opted into class 4 notifications per §7, a high-priority class 4 notification (per D-026 §1) MAY fire at the day-2 boundary celebrating the closed first day in Bertranda’s editorial voice (narrative-designer W-level for the specific copy). This is the first canonical notification the Walker receives — diegetic, observational, no nag.

6. Tab unlock sequence — progressive per beat

D-014 §1 mandates 5 tabs: Home / Tree / Factions / Quests / Craft. D-027 ratifies the unlock sequence:

Tab	Unlock trigger	Reasoning
Home (with Map widget)	Available from onboarding step 3 (Bertranda hands Map)	The Map IS the first artefact; Home is the surface that hosts it.
Tree	Quest 001 beat 5 complete (first tree point banked per D-016)	First tree point exists → Tree exists. Per-class `startingClusterId` is set at §3 class selection, so Tree opens to the Walker’s starting cluster.
Quests	Quest 002 enters the player’s quest log (post-Quest 001 completion, narrative-designer authors the trigger beat; trigger fires when Quest 002 becomes visible in the log, NOT when player taps to accept)	Quest log has more than one entry → Quest log is meaningful.
Factions	Quest 002 enters log (concurrent with Quests tab unlock) OR first faction-rep delta above zero on a non-Cech faction (whichever comes first)	Faction tracking is meaningful only when more than one faction’s rep exists. Cech rep is +3 from Quest 001 beat 1 by current authoring; Factions tab unlock requires meaningful comparison surface. (In current Quest 001 authoring, all rep deltas go to Cech — the first clause “Quest 002 enters log” is the operative trigger today; the second clause exists as a forward-compatibility hedge for future quest authoring that may grant non-Cech rep before Quest 002.)
Craft	Quest 003 OR first leak harvest above leakTier 0 (whichever comes first)	Crafting only matters when leak materials exist; before leak exposure (D-014 §3), Craft tab would be empty-state.

Unlock UX: each tab unlock fires a Bertranda or quest-side narrative beat (narrative-designer W-level for specific lines). NO unmotivated UI reveal — the player learns the tab exists through the quest, then sees it appear. The 5-tab endpoint shape from D-014 §1 is preserved; locked tabs are NOT rendered (not “greyed out”) to preserve the staged-reveal feel. Intermediate-state tab-bar layouts (1 tab, 2 tabs, 4 tabs) are new shapes that D-014 §1 did not author — layout treatment (centred / left-aligned / stretched) for the intermediate states is ui-designer W-level downstream of D-027.

Tester / debug builds: mobile-developer W-level may add a debug-only “unlock all tabs” affordance for testing; not player-facing, not canon.

7. Per-class notification opt-in — diegetic Bertranda framing

D-026 §What-not-decide deferred the notification opt-in moment here. D-027 closes it:

Install default: all 6 notification channels (per D-026 §1) are OFF. OS-level notification permission is ungranted. Walker receives ZERO notifications until opt-in.
Opt-in moment: step 6 of §2 (post-50-step register, pre-class-selection). Bertranda’s dialogue surfaces a “which messages should the Cech register?” prompt. Per-class toggles surface as the in-character question. OS-level notification permission prompt fires lazily — only when the Walker turns ON the first toggle (no permission ask until the Walker indicates intent).
Default toggles in the opt-in prompt: all 6 OFF by default. Bertranda explains each class’s purpose in her two-half-sentence cadence; the Walker toggles in the diegetic surface.
No-notifications skip path: the Walker can decline all 6. Per D-021 §3 + D-026 reconciliation, the game functions fully without any notifications. Bertranda’s response to all-decline is brief and warm — no guilt, no manipulation, no “are you sure” re-prompt.
OS denial after in-game ON: if the Walker turns ON an in-game toggle and then DENIES the OS permission prompt, the in-game toggle reverts to OFF silently. Bertranda does not re-prompt and does not flag the denial — no guilt, no “are you sure”. The Walker may re-attempt later via Settings, which re-triggers the OS prompt (subject to platform-specific re-prompt rules — on iOS the prompt may not fire a second time once denied; in that case Settings surfaces a deep-link to OS-level notification settings).
Subsequent control: all 6 channels remain toggle-able from Settings post-onboarding. Walker can opt out of any class at any time. OS-level notification permission survives once granted; re-opting in to a channel does not re-prompt OS permission.

This is the canonical narrative cover for the OS-level notification permission prompt. Without D-027’s diegetic framing, the OS prompt fires as a cold “WalkRPG wants to send you notifications” — disconnected from the experience. With D-027, Bertranda asks the question, the Walker answers, and the OS prompt is the technical instrumentation of that answer.

Rejected alternatives

Meta-tutorial outside diegesis (skippable overlay tutorial). Rejected — collapses Pillar 1 / Pillar 2 framing at first contact; D-008 §4 hardcore-adult does not tolerate patronizing tutorial overlays. The diegetic teaching IS the design.
Class selection at character creation pre-Bertranda. Rejected — Walker has zero lore exposure at character creation; the class names alone (kartograf / pieczetarz / etc.) require some understanding of D-013 + D-019 to read as anything more than RPG-class-noun. Post-beat-1 placement gives 50 attested steps + Bertranda’s two motto beats + Map first-redraw as grounding.
Class selection post-Plenny-saga (after Quest 015). Rejected — D-019 §3 ratified per-class starting cluster as the differentiation lever. Without class at start, startingClusterId cannot be set, and the tree-allocation experience for the first 14 quests would be either un-rooted or arbitrary. D-019’s implication that startingClusterId MUST be set before Tree opens is load-bearing.
No-class path / “Walker undecided”. Rejected — D-019 §1 enumerates 5 classes; “undecided” is not a 6th class. Default class.cartographer (Cech) IS the no-active-pick affordance.
Streak day-1 starts on calendar day AFTER onboarding. Rejected — contradicts D-013’s editorial-commit grammar (first 50 attested steps ARE commits); contradicts D-007 §2’s per-day attestation invariant (any day with attested walking counts); imports a “warm-up not real” pattern that creates an anti-cheat edge case at the tutorial / real boundary (mockable as “what counts as a real day”).
All tabs visible from launch with empty-state copy. Rejected — heavier first impression, dilutes the diegetic reveal moment for each tab. Empty-state copy is a mobile-game pattern WalkRPG is positioned against.
Two unlocks only (Home from start, all others after Quest 001). Rejected — bulk reveal feels arbitrary; loses per-tab teaching moment that narrative-designer authors as part of the saga. Per-beat staged reveal matches the saga’s first-region pacing.
Notification critical-3 default-on (streak / event / social). Rejected — contradicts D-008 §4 sparse-by-default; even time-sensitive social/event/streak classes stay off until the Walker explicitly opts in. Diegetic opt-in is the hardcore-adult pattern.
All notifications opt-out with no diegetic moment. Rejected — discovery cost is real; testers and early players will not find the settings page for weeks. Bertranda framing is the cheapest discovery affordance + the most respectful (in-character, two-half-sentence explanation, then the Walker decides).
Map widget hidden until first Walker step. Rejected — D-012’s defining-image moment (Bertranda hands the Map) requires the Map widget to be visible BEFORE the 50-step bar; the widget animating in real-time during step 5 IS the first-impression payoff.

What D-027 does NOT decide (delegated)

Specific Bertranda dialogue lines for the cold open, opt-in moment, and class-selection beat — narrative-designer W-level. Two-half-sentence cadence per Bertranda’s canonical incomplete-sentence character beat; bilingual per LocalizedString.
Map widget animation curve / timing / visual treatment during the 50-step register — ui-designer W-level + mobile-developer joint. D-022 §1 ratified the behaviour; visual specifics are downstream.
Per-class notification opt-in UX surface (toggle widget shape, label copy, OS prompt timing) — ui-designer + narrative-designer joint W-level.
Class selection UX surface (5-option picker shape, hover/preview semantics, class-description card) — ui-designer + narrative-designer joint W-level.
Tab-unlock animation / reveal moment visual treatment — ui-designer W-level.
Tab unlock state machine implementation (which event triggers what state transition in mobile state store) — mobile-developer W-level per Phase 13.
Onboarding skip pattern for debug builds — mobile-developer W-level; debug-only, not player-facing.
Re-onboarding flow after account deletion + recreate — tech-architect + mobile-developer joint W-level. Default posture: re-onboarding is full; no partial restore from prior account.
Returning-player onboarding (player who completed onboarding on Android then re-installs or installs on iOS) — tech-architect W-level on cross-platform identity restore shape. Canon UX expectation: returning players see condensed onboarding (Bertranda recognizes them, skips Map handover beat, runs 50-step bar as “re-register the hand”, restores class + tab unlocks + notification opt-in state). This is a canonical first-impression promise, not a “default-or-implement-as-time-permits” — the implementation shape is W-level, the UX expectation is canon.
First Walker-name input (player-set display name vs Cech ring number identity) — ui-designer + narrative-designer joint W-level. D-026 forward-referenced “no avatar”; D-027 stays silent on whether display name is player-set.
Accessibility-specific onboarding (wheelchair propulsion attestation prompt, treadmill / cycle mode setup) — forward-referenced to D-029 candidate. D-027 forward-states that onboarding IS the surface where D-029’s accessibility setup happens; D-029 ratifies the specifics.

Forward-references

D-028 candidate (Cosmetics, pick 15): Walker outfit / Mapa theme selection at onboarding. D-027 stays silent — cosmetics canon authors the moment if/when D-028 ratifies. Default: no cosmetic selection during onboarding; all unlocks via progression per D-028 candidate.
D-029 candidate (Accessibility, pick 16): wheelchair propulsion / treadmill / cycle attestation prompts during step 2 (HealthKit / Health Connect permission). D-027 ratifies that onboarding IS the surface; D-029 ratifies which movement modes are offered.
First Walker-name D-decision (if raised at all): currently no D-decision authors the question; D-027 lists it as W-level. If a future product question elevates it (e.g. social features need player-set names), a D-decision joins the chain.

Reasoning

The cold open is the highest-stakes design surface in the product. Every Walker passes through it exactly once. A drift here — meta-tutorial, cold class-pick, opaque OS notification prompt, generic tab reveal — has irreversible product cost (first impressions, App Store reviews, retention). D-027 closes the surface as a single diegetic event with eight absorbed sub-surfaces (sign-in, attestation permission, Map first-impression, motto, 50-step register, notification opt-in, class selection, tab unlock).

Quest 001 beat 1 is the canonical anchor — pre-existing, narrative-designer-authored, lore-correct (D-013 Bertranda + D-012 Map + D-006 Cech). D-027 ratifies the EXPANSION of beat 1, not the construction of a new tutorial layer. This is the cheapest design move that closes the surface: the canonical first-beat absorbs everything; no parallel tutorial flow exists to drift.

The class-selection-post-beat-1 timing (§3) is the load-bearing call: cold class pick at character creation would be the standard RPG pattern but contradicts D-013 + D-019 framing where class IS metaphysical stance. The Walker needs Bertranda + Map + 50 steps + motto exposure before the metaphysical-stance question becomes legible. Post-beat-1 placement is the minimum lore-grounding necessary.

The streak-day-1-at-register timing (§5) closes the “what counts as a real day” mock-step anti-cheat vector. If 50 attested onboarding steps DIDN’T count, a mock-step attacker could exploit the tutorial / real boundary. They DO count = no boundary = no exploit. Editorial-commit grammar (D-013) is the right intuition; the anti-cheat consequence is the load-bearing reason.

The progressive tab unlock (§6) extends D-014 §1’s 5-tab navigation with a staged reveal sequence that matches the saga’s pacing. D-014 §1 ratified WHAT tabs; D-027 ratifies WHEN they appear. The two surfaces compose cleanly.

The notification opt-in moment (§7) closes [[D-026]]‘s deferred surface with the maximally diegetic option. Hardcore-adult sparse defaults + Bertranda in-character framing + lazy OS-permission-grant = the hardcore-adult-positioning surface stays consistent at the OS layer.

Source: pick 14 from ops/memory/vision-qa-2026-05-21.md. Triage by game-director (2026-05-21 Round 4 estimate). Pre-ratification recon per [[feedback-decide-triage-recon]] confirmed: “onboarding” appears once in data/src/content/_glossary.ts as a transcreationNote descriptor for cluster.first-steps (semantically separate); “tutorial” has zero presence in data/src/content/; “bertranda” surfaces only in canonical NPC card npc.three-dots-clerk (Bertranda Dot-Wells EN / Bertranda Kropka-Wieliska PL, canonical per 2026-05-18 bootstrap glossary), her title Naczelna Pisarka locked at D-013 §Open-questions point 2 — no collision risk. Four CEO call-out picks at ratification: class selection post-beat-1 (recommended), streak day-1 at 50-step register (recommended), progressive tab unlock (recommended), all-6-opt-out with diegetic Bertranda opt-in (recommended). All four recommended-win. system-reviewer initial verdict BLOCK at 2026-05-21 on canon-collision (class.pisarz invented vs D-019 §2 locked class.cartographer); resolved inline by global handle replace + Cech-naming-asymmetry framing per D-019 §Reasoning. Remaining 8 nits applied inline pre-commit (review file: ops/reviews/D-027-onboarding-canon.md).