UserSay/ Docs

1 · Get them started

The survival gate — getting a new user from "I'm here" to "I made something I care about", and unsticking them the second they stall.

A new user signs up and then stalls. Not for lack of wanting it — the gap between "I'm here" and "I made something I care about" is wider than it looks, and most people never cross it. They didn't churn; they never activated.

That's why this layer is first. Every layer below it is multiplied by it: a user who never reached a first success can't be saved or upgraded — both are worth zero on top of them.

Here's the gap at its most literal. A CS student at Monash, two diagrams in, four to go, UML assignment due tomorrow — the credit counter hits zero before they've made the thing they came to make:

Sarah
ChatDiagram · credits_exhausted
Sarah
out already? that limit's tight, I know. what were you working on?
SIGNAL
no artifact yet — help them finish the thing they came to make
my UML assignment, I just made 2 of the 6 use case diagrams
Tool call · grant_credits
→{ amount: 8, reason: "activation_bootstrap" }
←{ status: "applied", new_balance: 8 }
COST
$0.08 to unblock the first real artifact — a small investment in activation
just dropped 8 in — enough for the 4 left plus a couple to fix anything. good luck with the assignment 🙂

That one cost eight cents and a tool on your server. It's the only play in this layer that needs one — everything else here is words.


The states in this layer

  • First fifteen seconds on the site — they're here and haven't done anything yet. Moment: welcome.
  • Stuck right now — everything they need is already on screen and they still don't know what to do. Moment: stuck.
  • A first run that failed — they tried, the output missed. Moment: generation_failed.
  • A first success worth confirming — it worked, and they're a bit pleased about it. Moment: first_use.

The last one isn't a problem state, and it's the most valuable of the four. It is a useful moment to learn what worked and what they plan to do next.

What zero code already catches

welcome fires on a first visit with no code at all — script tag, identify(), nothing else:

yourproduct.com
Sarah
welcome
hey 👋 first time here? tell me what you're trying to make and I'll point you at the fastest way to get there.
Reply

The other three are one line each, placed where the thing actually happens in your product:

UserSay.trigger('first_use');         // from the SUCCESS callback — not the attempt
UserSay.trigger('stuck');             // your own idle / retry / dead-end heuristic
UserSay.trigger('generation_failed'); // when output missed

She won't guess at these, on purpose: only you know what a first success looks like in your product (the dashboard calls this moment First value for that reason — a first attempt is not a first value), and a moment that fires at the wrong time costs more than one that doesn't fire. credits_exhausted — the moment the creditless-start play below hangs off — is free as well, because she watches for HTTP 402 responses from your own API. The tier-by-tier list for every moment is on How much you have to build.

Answering all four states is Layer 0: her words, free, no server to build. Only the credit grant crosses into Layer 1, her hands.

The plays

Catch the aha and ask

play
Fires at: first_useCalls: — (just words)

A new ChatDiagram user types one sentence describing their hiring flow. Three seconds later the whole diagram is on screen, and it's right. They lean back, a bit pleased. That's the second to ask anything.

Sarah
ChatDiagram · first_use
Sarah
that came out clean — what were you making it for?
SIGNAL
ask at the peak, not the wall — an offer here feels earned; the same offer 10 seconds earlier feels like a pitch
an onboarding flow for my new hire, I'll drop it in our wiki
Sarah
nice, a real one 🙂 what part will help your new hire most?
MOVE
understand the next step — find out how the result will be used

Free, Layer 0, works the day you install. Ask about the result while the experience is fresh, then listen.

Bootstrap a creditless start

action
Usually at: credits_exhausted · first_useCalls: grant_creditsToggle: Agent → Actions (needs your MCP)

The Monash student at the top of this page needs enough credits to finish the assignment. A small grant removes the immediate blocker and lets them experience the product working.

This is the one play here that needs your MCP server: a grant_credits tool, where your caps pick the amount, not Sarah. She asks; your server decides and answers. The same tool gets reused in Grow, which is why it's usually the first one worth building.

Rescue a stuck user

play
Fires at: stuckCalls: — (just words)Toggle: Agent → Plays → Onboarding rescue

A blank canvas, a half-finished thought, and ten minutes of staring. They have everything they need and still don't know what to do. A grant would solve a problem they don't have. Words do.

Sarah
ChatDiagram · stuck
Sarah
looks like you've been staring at a blank canvas — what are you trying to draw?
SIGNAL
comprehension wall, not a resource one — a grant here would solve a problem they don't have
I have meeting notes but no idea what diagram fits
Sarah
paste the notes — if it's a process, a flowchart; if it's parts of a whole, a mind map. let's try one.
MOVE
diagnose UI vs conceptual, then unblock with one concrete suggestion

The cheapest retention surface there is. Sarah's first job is telling which kind of stuck this is: a UI problem ("I can't find the export button" — a docs or product fix) or a conceptual one ("I don't know what to make" — a guidance fix). They need very different answers, and credits answer neither. A first run that failed runs this same rescue — generation_failed and stuck are the same play with different openings.

What she can't see yet

Signed up and never came back. Nothing watches for the absence of a first use.

Every moment on this page needs the user to be in your product right now. Sarah works in a browser tab; if nobody's in the tab, nothing fires. So the biggest hole in the layer is also its quietest one — someone who made an account, closed it, and never opened it again is invisible to her. Don't read this page as "she watches your new users for you." She meets the ones who show up. The user journey lists the other two blind spots.


Next: Keep — once they've felt the value, how Sarah catches the cancel, the refund, and the quiet drift away.

On this page