Onboarding

What happens the first time you sign up, and how to replay any of it later.

The 5-step tour

After your first sign-in, a small modal walks you through five steps. Each step is one screen with a short body and a Next button. Esc dismisses the modal. Clicking the backdrop does not dismiss — that's intentional. The only ways out are Next-through-all-five or the explicit Skip button.

1. Welcome. Quick recap of what Vibstr is: items derive from plans, the AI sidebar knows the context, your team discusses in Slack, the manual paths work without any AI. No promises about what you'll do next — just framing.
2. Pick a template. Web app (5 categories, 13 areas, 4 workflow labels) or Empty (nothing — you'll set it up yourself). Picking Web app populates the project so you can file your first item immediately without spending 10 minutes configuring categories.
3. Connect Claude Code. One master snippet. Copy → paste into Claude Code → tell Claude: Add this to my CLAUDE.md. After that, Claude drives the loop on every build prompt — plans first, derives items, commits with closes #NN, runs the build-report curl. You don't have to remember any of it. (Not using Claude Code? The same snippet works as documentation for any AI agent that reads a CLAUDE.md / AGENTS.md at session start. Or use generic git hooks for the auto-report curl without an AI agent.)
4. Link your GitHub repo. Single text input — owner/repo (e.g. custardsquare/vibelog). Saves to vibelog_projects.github_repo. Used by the super-function for closes #NN auto-close + by the build-doc capture mechanism (SPEC §26) to pull .md files out of each commit's diff. Continue with valid input saves; Continue empty + Skip both advance without writing. Inline regex validation surfaces a red error below the input if the format's wrong. You can change this any time in Settings → INTEGRATIONS → GitHub repo. (Pre-1.20.10 this step was "File your first item" — retired because the capture-strip-prefill flow had an opaque area-validation bug AND zero meaningful onboarding value vs the repo-link step.)
5. Done. Confirmation screen with a "Replay this tour anytime from Settings" footer. Click Close.

State persists in two columns on vibelog_profiles:

• onboarded_at — set to now() when the user clicks Done on step 5.
• onboarding_step — which step they're currently on (0 if not started, 5 if completed).

Both columns ship at the schema level and are read by loadApp() on every page load to decide whether to show the modal.

Connect Claude Code — one master snippet

The Connect Claude Code pane (Settings → PROJECT → Connect Claude Code) is a 2-minute setup. It shows:

• Status banner. "Connected" when at least one build with commit_hash has landed OR a plan with derived items exists. "Idle" otherwise. The pill at the top of the pane mirrors this.
• Intro paragraph + "after that:" bullets. Plain English: copy the snippet, paste into Claude Code, tell Claude to add it to your CLAUDE.md. After that, every build prompt drives the loop automatically.
• Master snippet code-block preview. Mono, scrollable. Your project's API key is already embedded — no placeholder substitution.
• One primary button: Copy CLAUDE.md snippet — sets up the full automation loop. Click → snippet is on your clipboard with an actionable toast that tells you exactly what to do next.
• Expandable "What happens next?" disclosure (collapsed by default). For curious minds: the 5-step plan → derive → build → commit → report breakdown. Skip it if you just want the loop running.
• Deep dive link. Points at /how-we-ship/claude-code/ for the long version.
• API key card. Reveal / Copy / Regenerate. The key is project-scoped. Auto-regenerating invalidates any CLAUDE.md snippet that's still pointing at the old key — be deliberate; re-copy the snippet from the pane after rotating.

The Configured pill flips green once the loop has produced output (a build with a commit hash, or a plan with derived items).

The master snippet bundles three things into one paste: workflow instructions for Claude (plan first, derive items, build, commit with closes #NN, run the curl), the per-project tailored Vibstr Plan Prompt for canonical-format plans, and the build-report curl recipe. Claude reads it once at session start and runs the loop from there.

Trial-day-N nudges

Three nudges fire client-side from loadApp() based on the user's trial_started_at column:

• Day 1. "Welcome to Vibstr — here's a 30-second tour." Soft prompt. Appears in the Inbox tab.
• Day 7. "You're halfway through the trial. Here's what most users do at this point." Lists the three high-value paths: file 10+ items, connect a real GitHub repo, try the AI sidebar on an item.
• Day 12. "Trial ends in 2 days. Two ways to keep AI features: BYO Anthropic key (you pay Anthropic, we never mark up), or upgrade to Pro at $2.99/seat/month. Manual features stay free either way."

Each nudge has a sparkle glyph and a type-specific CTA. Dismissible. Suppressed for:

• BYO key users (they're not on a clock).
• Platform admins (chris doesn't need a trial nudge for his own product).
• Paid tier (Pro $2.99/seat/month).
• Expired trial (the soft gate modal is the right surface at that point).

Activity log captures each nudge view as user_trial_nudge_shown so we can measure conversion impact in the Platform Analytics card.

Auto vs Manual paths

Both supported, both first-class. Vibstr never assumes you use Claude Code or any specific AI tool.

Auto path:

• Post-commit hook runs a curl after every git push.
• Hook sends version + commit hash + commit message body to the project's ingest URL.
• Auto-ingest parses closes #NN references and deterministically closes those items.
• AI semantic matching runs on the REMAINING items (against your claude_output if you ran one). Burns one daily AI call.
• Build appears in the Build tab with the items grouped under it.

Manual path:

• Click Ship items on the Build tab.
• Multi-select items via the picker (Cmd-click or shift-click ranges).
• Optionally generate a deterministic markdown changelog.
• Click Ship → items close into a new build with match_source: 'manual_ship' on the activity log.
• No AI cost. No commit message required. Useful when you're shipping work that didn't go through git, or when you want to batch-close a sprint without rewriting commit history.

Both paths fully supported forever. The manual path is in the SPEC §20 contract — every AI-using feature in Vibstr ships with a deterministic fallback.

Replay the tour anytime

Settings → ACCOUNT → Onboarding has a "Re-take tour" button. Click it and the 5-step modal opens at step 1. Your onboarding_step resets to 0; clicking through to Done on step 5 re-stamps onboarded_at.

Useful when:

• You want to show a teammate what the first-run is like before they sign up.
• Your project's setup has drifted from the Web app template and you want to see what a fresh template looks like.
• You're debugging a tour-flow issue.

What's NOT in the onboarding flow (intentional non-goals)

• No video. Text + the live UI is the tour. We're not in the video-production business.
• No animated walkthrough overlay. No "click here next" arrows pointing at parts of the UI. The 5 steps are self-contained modals; users find the actual UI surface themselves.
• No skip-onboarding-permanently button. The Skip button dismisses the modal for this session. It'll come back on the next sign-in if onboarded_at is still null. The fix is to finish the tour or click Re-take + skip-to-done, not to add another toggle.
• No localised copy. English only for the foreseeable future. We'd rather ship the product than translate it 12 ways before we have 1000 users.

Related pages

• Pricing — what changes at trial end.
• Claude Code — the auto-path long version.
• Git hooks — bash, PowerShell, GitHub Actions variants of the post-commit script.
• The AI sidebar — what the a keystroke gets you.
• Plans — the canonical format the Vibstr Plan Prompt produces.

← Back to the docs index · Open Vibstr