v4.26 — Help Site Design Overhaul

The guide stopped explaining the app in prose and started showing it — live, on every page.

Summary

Before this milestone, help.objectuve.com read like a generic docs site: an article index up top, static screenshots buried in prose below. Its primary reader — someone brand-new, mid-onboarding, trying to understand a feature they just saw in the app — had to translate words back into a mental picture of a screen they hadn't found yet.

Josh's design handoff ("Objectuve help site redesign.zip," delivered 2026-07-31) proposed direction 1b, "the live simulator," as the fix: stop indexing articles and start demonstrating the app. Home becomes a phone-frame simulator driven by six mechanic rows — Check in, Build a streak, Earn XP and ranks, Talk to your Coach, Track a goal, Cheer an ally — each one swapping the phone screenshot, an annotated pin, and a caption column together. Every article page gains a sticky right rail whose middle card is a real app screen that swaps as the reader scrolls past each section, or clicks a heading in the table of contents. The handoff called this rail "the signature move," and it's the piece that makes an article read less like documentation and more like a guided screen recording.

Eight phases shipped it in two days, one PR per phase straight to master — guide_site deploys on its own path-filtered push, so each phase went live to real users independently, with no integration branch to hide behind. The 19 existing markdown content pages kept every word of their prose; only the shell, the templates, and page frontmatter changed. The milestone's most consequential single addition was new, not restyled: a grace-day streak simulator that lets a reader tap through 14 days and watch the app's actual forgiveness rule play out, targeting the single most-misunderstood mechanic in the product.

Goal

The guide today "feels like a generic docs site" (the handoff's own framing). Its primary reader is a brand-new user mid-onboarding, not someone hunting a reference fact. Direction 1b — "the live simulator" — is the chosen answer: Home stops being an article index and becomes a live demonstration of the app; every article page gains a sticky right rail whose middle card is a real app screen that swaps as you scroll and on click.

Scope — What Shipped

• New home (GuideHome.vue rewrite) — hero band, the 0.92fr/1.08fr live simulator panel (six keyboard-operable mechanic rows, 266px phone frame, annotated pin, copy column), a search band, and an "All 19 pages" index derived from guideSidebar.ts rather than hand-listed
• New article template — 3-column grid (TOC / prose / rail), sticky "In the app" preview rail with IntersectionObserver-driven swap on scroll and on TOC click, falling back cleanly to the page's hero figure on any page without authored preview: frontmatter
• New --guide-* token layer (guide.css) mapping the handoff's literal hex onto brand.css and design_system/css/tokens.css, wired into VitePress's own --vp-c-* variables rather than overriding them; 72px sticky nav, restyled footer, full dark-mode parity
• New grace-day streak simulator (GuideStreakSimulator.vue) — 14 tappable days + 4 stat tiles, deterministic and client-only, its rule independently verified against User#current_streak's actual grace-budget math across all 16,384 possible 14-day patterns
• Restyled demo components — check-in ring, walkthrough player, coach-tone demo, rank-stacker — presentation-only, existing aria-pressed/aria-live contracts preserved
• Restyled search overlay + 404, and a new /whats-new page sourced from ionic_frontend/CHANGELOG.md in user-facing language, closing a standing nav TODO that had pointed at a marketing URL
• Mobile-specific surfaces — 390px article view, a section bar replacing the desktop rail, a cropped-window preview instead of a nested phone frame, and a bottom tab bar (Learn / Search / Topics / Ask)
• ~25 preview: frontmatter entries across 11 of the 19 content pages — screenshot, pin coordinate, and caption per section, authored against Phase 1's contract and Josh-approved as one batch (not every section warranted one; a forced preview was treated as worse than the honest fallback)
• Real PostHog analytics in guide_site for the first time — a single guide_feedback event (page path + yes/no, no PII, DNT-respected) replacing the "Did this answer your question?" control's previously-inert click handler
• A Josh-approved per-CTA deep-link mapping — "Ask Coach" → https://app.objectuve.com/coach, live on 4 independent surfaces (tab bar, article rail, search overlay, layout)

Phases

Phase	Name	Status	Plans	Highlights
1	UI-SPEC + token mapping	Shipped	1	Desi mapped the handoff's hex onto --guide-*; found 5 real defects (2 contrast failures, a horizontal-scroll bug) during a missing-evidence review bounce
2	Tokens + shell	Shipped	1	--guide-* wired into --vp-c-*; sticky nav shipped deliberately without "What's new" to respect the dead-link build gate
3	Home — the live simulator	Shipped	1	The milestone's headline change; pin nested + centre-anchored correctly on the first implementation attempt
4	Article template + preview rail	Shipped	1	The cleanest phase — approved on first review pass, no fix round
5	Demos + grace-day simulator	Shipped	1	3 fix rounds; the new component's independently-specced rule caught 2 real defects in the source handoff's own pseudocode
6	Search overlay + 404 + /whats-new	Shipped	1	Caught a zero-results state that announced to nobody — axe-clean and still broken, found only by a human read
7	Mobile	Shipped	2	Corrected the mobile pin-placement formula and a safe-area-inset-bottom fallback that silently no-op'd on most devices
8	Content, captions & analytics	Shipped	1	Render-verified every authored pin against its source crop, catching 7 of 26 mis-placed entries a number-only check would have missed

Key Decisions

• Direction 1b only, not 1a — the handoff's alternate "launch path" direction was reference material for comparison and was never implemented.
• Desi first, every new component — Phase 1 mapped every literal hex onto the token layer before any CSS shipped. Phase 5 later demonstrated the cost of skipping this for a genuinely new component (a missed UI-scope flag led to a parallel spec arriving after implementation); Phase 7 applied the lesson and dispatched Desi ahead of the build, catching two more contract defects before they could ship.
• Verify pins against the rendered crop, not the authored number — the same symptom (a pin pointing at the wrong control) recurred under three unrelated causes (geometry, derivation, authoring) across three phases. A number-only check would have passed all of them; render-verification caught all of them.
• The server is the source of truth for the grace-day and XP rules, not the prototype — verified once at kickoff against user.rb:35-36 and gamification/subscribers.rb:57, and re-verified exhaustively by Phase 5's verify-rule.mjs script.
• A forced preview is worse than the fallback — not every article section got a preview: entry; pages without a section worth showing correctly shipped with none, landing at ~25 entries across 11 pages against an original ~50–60/19 projection.
• One PR per phase, straight to master, no integration branch — guide_site deploys on a path-filtered push, so every phase had to leave the live site in a fully working state, light and dark, on its own.

Requirements Coverage

8 / 8 phase acceptance checklists satisfied (quoted from v4.26-help-site-overhaul-MILESTONE-AUDIT.md). This milestone has no standalone REQUIREMENTS.md — coverage is derived from the UI-SPEC's own §8 per-phase acceptance checklist, the binding contract for all 8 phases.

Category	Count	Status
Phase acceptance checklists	8	All satisfied
Josh's locked decisions (CTA mapping, nav label, gradient-fill rule, Topics tab, etc.)	9	All implemented and verified

Outcomes

A new visitor to help.objectuve.com now lands on a page that shows the app working before asking them to read anything, and every article they open keeps a real screen of the app visible beside the prose the whole time they're reading. The grace-day streak simulator gives a concrete, tappable answer to the product's most support-ticket-generating question ("did I just lose my streak?"). The guide has real usage analytics for the first time, and its "What's new" nav item finally points at a real, user-facing changelog instead of a placeholder marketing link.

Tech Debt

• (Phase 3, tracked as OBJ-2017) Pre-existing dark-mode color-contrast gap on .guide-word-sub and nav links — reproduces on the untouched pre-milestone /, not introduced by this work. backlog, non-blocking.
• (Phase 6) A nested-interactive axe violation inside VitePress's own VPLocalSearchBox vendor markup, reproducing at desktop too. Caps future search work short of forking VitePress; needs its own ticket.
• (Phase 8) A manual click-through to confirm the guide_feedback PostHog event fires end-to-end — headless automation couldn't observe it directly across two review passes, though static review read correct both times.
• (Phase 8, process) A fix commit went unpushed to origin in both of Phase 8's review rounds, with the PR head briefly lagging what the fix report described. Riley caught it both times before merge; carried forward as a process habit to watch, not a shipped defect.
• (This close) The ROADMAP's self-reported delivery count ("26 preview entries across 12 pages") doesn't exactly match this audit's direct count (25 entries across 11 pages) — see the milestone audit's verification section. Non-blocking; the underlying "well under the original ~50–60 projection, by design" story is unaffected.

Related Artifacts

• Roadmap: v4.26-help-site-overhaul-ROADMAP.md
• Milestone Audit: v4.26-help-site-overhaul-MILESTONE-AUDIT.md
• Design contract (UI-SPEC): docs/ui-specs/v4.26-help-site-overhaul.md
• Coordination anchor: OBJ-1932
• Merge PRs: #1914 · #1920 · #1921 · #1922 · #1924 · #1925 · #1941 · #1947 · #1952

Related Commits

• c97ec394a — Phase 1: UI-SPEC + token mapping (#1914)
• 5204ffaae — Phase 2: tokens + shell (#1920)
• efb8e0c10 — Phase 3: home — the live simulator (#1921)
• 26bf3308f — Phase 4: article template + preview rail (#1922)
• 46fd967fe — Phase 5: demos + grace-day simulator (#1924)
• ca623e8db — Phase 6: search overlay + 404 + /whats-new (#1925)
• bb95e1d24 — Phase 7 session A: mobile shell + article (#1941)
• edb23e5d3 — Phase 7 session B: mobile derived surfaces (#1947)
• 9f4b06447 — Phase 8: content, captions & analytics — final phase (#1952)
• 7c4bf42d8 — docs(planning): tick v4.26 Phase 8 shipped — milestone complete (cherry-picked from agent/orion/96cc2f0f's 77b760ecc onto this close branch)

Last updated: 2026-08-01