Objectuve Docs

Appearance

v4.21 — First-Class User Guide + Marketing Refresh ​

Objectuve now has a real, public, interactive user guide at help.objectuve.com — and the marketing landing page finally shows the shipped Teams features.

Summary ​

Before this milestone, Objectuve had no public user guide at all. The only "how to use the app" content was a single 704-line markdown page, trapped behind the staff-only internal docs site (docs.objectuve.com, Clerk @objectuve.com / password gate). Nothing about it was reachable by an actual user.

v4.21 replaced that with guide_site/ — a wholly new, standalone VitePress site with its own Firebase Hosting target (enkidu-guide, mapped to help.objectuve.com), no auth chrome, and a public information architecture spanning 18 feature pages. Phase 1 stood up the shell and carved the existing content out of the internal docs tree. Phase 2 rewrote every page into comprehensive, task-oriented, brand-voice content — device-framed screenshots, numbered steps, Coach callouts, reference tables — verified against the rails_api gamification source. Phase 3 made the guide genuinely interactive: a reusable step-through walkthrough player embedded across six feature areas, plus three stateful demos (a tappable check-in ring, a Coach persona/tone matrix, an XP-to-rank meter). Phase 4 closed out the milestone by extending the shared screenshot-capture pipeline to cover the Teams routes, regenerating every app screenshot off the shipped v4.19 Teams UI, and replacing the guide's placeholder Teams page with a full walkthrough verified against the live components.

All four phases shipped the same day (2026-07-28), but the milestone's own tracking file and this narrative page didn't get written until now, six days later (2026-08-04), after Orion's OBJ-2150 milestone-ledger reconciliation found the gap. This page corrects two inaccuracies the milestone's own records carried in the interim, rather than repeating them: Phase 3's PR (#1845) squash-merged into the milestone's integration branch, not master — its cited commit 63ab4349f is confirmed not a master ancestor. Phase 3's actual content (the five interactive Vue components) reached master through a different commit, 0f3d0253e, which is Phase 4's own PR (#1850) — that PR's diff carried the full accumulated Phase 3 + Phase 4 changes to master in one squash-merge, the same "final phase merges everything" shape v4.17-design-system-facelift used. Separately, the milestone's -ROADMAP.md file sat with Phase 4 marked unchecked and gated on OBJ-1827 for several days after Phase 4 had actually shipped and CHANGELOG.md already documented it — that ROADMAP file was corrected 2026-08-04 as part of the same reconciliation (OBJ-2150, PR #2104). Both are now closed; see Tech Debt below. Every phase's content has been confirmed live on master as of this writing — the gap was in the paperwork, not the delivery.

Goal ​

Turn the "user guide" from a single 704-line markdown page (docs/product/user-guide.md) — today trapped inside the staff-only internal docs site (docs.objectuve.com, Clerk @objectuve.com / password gate), unreachable by any real user — into a first-class, public, interactive content surface that end users of Objectuve can actually find and read, and refresh the marketing landing app screenshots so both surfaces reflect the current app (including the newly-wired v4.19 Teams features).

Scope — What Shipped ​

  • New standalone public site — guide_site/ (own VitePress config, theme, .github/workflows/guide.yml), deployed to a new, additive Firebase Hosting target (enkidu-guide) mapped to help.objectuve.com. The internal, staff-gated docs.objectuve.com and its AuthGate were left untouched.
  • 18 rewritten guide pages covering account/onboarding, dashboard & goals, habits & streaks, the Coach, achievements/XP, communities, and Teams — each using a shared content system (GuideFigure device-framed screenshots, GuideCards reference tables).
  • 5 interactive Vue SFCs — GuideWalkthrough/GuideStep (a reusable, WAI-ARIA-Tabs-pattern step-through player, keyboard + touch accessible) instantiated across 6 feature areas, plus GuideCheckinDemo, GuideCoachToneDemo, and GuideRankMeter — three small stateful demos, all SSR-safe and gated on prefers-reduced-motion. Confirmed present on master at guide_site/.vitepress/theme/.
  • Extended screenshot pipeline — scripts/capture-screenshots.mjs now captures the Teams routes (team home, leaderboard, sub-communities, collective goal) and writes into three targets in one pass: docs/assets/, marketing_landing/images/screenshots/, and guide_site/public/assets/.
  • A full guide_site/teams.md rewrite (112 lines), replacing the Phase 2 placeholder, covering team home, collective goals, the leaderboard, sub-communities, members & invites, and starting/joining a team — verified against the shipped Teams V1 components.
  • SEO hardening (OBJ-1853) — canonical <link>, robots.txt, and a sitemap on guide_site/, preventing the .web.app origin and custom domain from being indexed as duplicate content.
  • Operational surface — guide_site/ joins the repo's independently-deployed surface lanes (see Independent surface lanes), with its own path-filtered master-push deploy workflow (guide.yml).

Phases ​

PhaseNameStatusPlansHighlights
1Publish & restructure the guide (foundation)Shipped — PR #1841 → master @ 335a2344c1New standalone guide_site/ site, own Firebase target, 18-page IA carved from docs/product/user-guide.md; internal docs AuthGate untouched
2Content overhaulShipped — PR #1844 → master @ e4ce0c3a51All 18 pages rewritten in brand voice; XP/rank/streak content verified against rails_api source
3InteractivityShipped — PR #1845 → integration branch @ 63ab4349f (not master); content reached master via PR #1850's accumulated squash-merge15 interactive SFCs across 6 feature areas — reusable walkthrough player + 3 stateful demos
4Asset refresh + marketing screenshotsShipped — PR #1850 → master @ 0f3d0253e (also carried Phase 3's content to master)1Teams-route capture gap closed, all screenshots regenerated off shipped v4.19 UI, full teams.md rewrite

Key Decisions ​

  • Public guide built as a wholly new site, not carved inside docs_site/ — Codi stood up guide_site/ as its own standalone VitePress project (own config, theme, CI workflow, Firebase target) rather than reusing the internal docs tree with pages excluded, keeping the public surface's build/deploy/auth posture fully independent of the staff-gated site from day one.
  • help.objectuve.com, confirmed by Josh — decoupled from docs.objectuve.com, which stays staff-only for internal engineering/product documentation.
  • Real Teams content, gated on the real UI shipping — Phase 4 hard-gated on OBJ-1827 (v4.19 Teams UI) actually merging, not just being scheduled, and Phase 3 deliberately shipped no interactive walkthrough for Teams so nothing would document UI that hadn't shipped yet. Teams got a static, screenshot-driven page in Phase 4 instead, captured against the real shipped components (TeamHomeView.vue, TeamLeaderboardView.vue, TeamSettingsView.vue, CreateTeamView.vue, JoinTeamView.vue).
  • deploy-sites.sh turned out to be unnecessary — both guide_site/ and marketing_landing/ already auto-deploy on path-filtered master pushes; the manual deploy script referenced in the ROADMAP's Phase 4 task package was never actually invoked.
  • A milestone's phases don't all have to land through the milestone's own cited PR — Phase 3's PR (#1845) landed on the integration branch, and its content only reached master because Phase 4's PR (#1850) squash-merged the full accumulated diff. This is the same shape v4.17-design-system-facelift used deliberately; here it happened without anyone updating the ROADMAP to say so, which is why this page and the milestone audit exist six days later than they should have (see Tech Debt).

Requirements Coverage ​

9 / 9 requirements satisfied (per the Milestone Audit; this milestone has no standalone REQUIREMENTS.md — coverage is derived from the ROADMAP's own task checklist).

CategoryCountStatus
Phase 1 (GUIDE-UISPEC-1, GUIDE-1, GUIDE-DOCS-1)3All satisfied
Phase 2 (CONTENT-UISPEC-1, CONTENT-1)2All satisfied
Phase 3 (INTERACT-UISPEC-1, INTERACT-1)2All satisfied (content confirmed on master; landing commit corrected — see Related Commits)
Phase 4 (ASSET-1, ASSET-DOCS-1)2All satisfied

Full detail: v4.21-user-guide-first-class-MILESTONE-AUDIT.md.

Outcomes ​

Anyone can now visit https://help.objectuve.com without signing in and read a comprehensive, brand-voice guide to every major feature — account setup, the dashboard, goals, habits and streaks, the Coach, achievements and XP, communities, and Teams. Several pages let a reader try the interaction before they see it in the app: tap the check-in ring and watch the streak tick up, drag the Coach tone slider and see a live sample line change, or slide an XP amount and watch the rank meter recompute. The Teams page shows real, shipped UI — team home, the leaderboard, sub-communities — captured directly from the live v4.19 release, not placeholders. The internal, staff-gated docs site at docs.objectuve.com is completely unaffected — its AuthGate was never touched.

Tech Debt ​

  • (Documentation accuracy, closed by this page + OBJ-2150.) For several days post-ship, the milestone's own -ROADMAP.md file and CHANGELOG.md disagreed about whether Phase 4 had shipped, and the ROADMAP's Phase 3 entry cited a commit (63ab4349f) that is not actually a master ancestor without noting that gap. Corrected 2026-08-04 (OBJ-2150, PR #2104) and compiled into the audit and this page. See the Milestone Audit's Tech Debt #1 for the full correction.
  • (Phase 4) collective-goal.png shows a 0/1000 (0%) progress card and team-leaderboard.png shows a generic "Admin Account" entry — both real captures off the seeded demo Team, just not visually compelling for a marketing surface. A reseed + recapture is a tracked fast-follow, not a regression.
  • (Phase 4, pre-existing) .github/workflows/visual-regression.yml installs puppeteer but the capture script uses Playwright — a tooling mismatch surfaced, not caused, by this milestone.
  • (Phase 4, pre-existing) goal_details_desktop.png (docs-only) stayed stale — a desktop-width goal-card click doesn't fire even with the corrected selector. Unrelated to Teams; needs its own small investigation.
  • 335a2344c — [Codi] Phase 1: stand up public user-guide surface on its own Firebase target (GUIDE-1, OBJ-1846) (#1841)
  • e4ce0c3a5 — [Dori] Phase 2: comprehensive content pass across guide_site (CONTENT-1) (#1844)
  • 0f3d0253e — [Codi] Phase 4: Teams-route screenshot capture + regenerated app screenshots (ASSET-1, OBJ-1849) (#1850) — also the actual master-landing commit for Phase 3's 5 interactive SFCs, since PR #1845's own squash-merge (63ab4349f) only reached the milestone's integration branch, never master
  • 1e58acbaf — [Dori] docs(planning): reconcile ROADMAP.md/STATE.md/PROJECT.md to verified ship state (OBJ-2150 Tasks 3+3b+4+5) (#2104) — corrected this milestone's -ROADMAP.md Status header and Definition-of-Done

Last updated: 2026-08-04

Loading…