@elevasis/sdk 1.15.1 → 1.17.0

package/reference/claude-config/skills/tutorial/vibe-coder.md

@@ -0,0 +1,890 @@
+---
+description: |
+  Vibe-coder track for the /tutorial skill. Loaded by SKILL.md when the user's
+  profile.md shows track: vibe-coder. NOT directly invocable. Do not expose this
+  file's name or path to the user.
+---
+
+# Tutorial -- Vibe-Coder Track
+
+This file is loaded by the `/tutorial` router (`SKILL.md`) when the user has chosen
+the non-technical track. Every lesson here is a script for the teaching agent.
+The user never sees file names, slash commands, code, or technical vocabulary.
+
+**Vocabulary rule:** The swap table below is law. Every user-facing word in every lesson
+must follow it. If the user uses a forbidden word, reflect back the right-column equivalent
+without comment.
+
+| Never say                                  | Say instead                           |
+| ------------------------------------------ | ------------------------------------- |
+| Workflow / agent / resource                | Automation                            |
+| Schema / Zod / type                        | The information your automation needs |
+| Deploy / publish to platform               | Make it live                          |
+| Organization model / config                | Your business profile                 |
+| Credential / API key                       | Account connection                    |
+| Operations / Command Center / Command View | Your dashboard / your map             |
+| HITL / approval gate                       | Your approval queue                   |
+| Repo / monorepo / git / GitHub             | (never mentioned)                     |
+| TypeScript / JavaScript / pnpm / CLI       | (never mentioned)                     |
+| Adapter / platform tool / SDK              | The tool the automation uses          |
+| /knowledge or any slash command name       | (never named; invoke silently)        |
+| Lesson / module / curriculum               | (use the lesson title only)           |
+| Intent / classifier / classification       | How you talk to me                    |
+
+**Silent invocation rule:** Whenever this script says "[hidden action]", do that work
+completely silently. The user sees friendly narration of the result, never the mechanism.
+
+---
+
+## Menu
+
+Display this menu when the user starts the tutorial or asks to see their progress.
+Replace `[ ]` with `[x] YYYY-MM-DD` for completed lessons by reading
+`.claude/memory/tutorial-progress.md`.
+
+```
+Your Tutorial
+=============
+1  Welcome -- what this place does for you             [ ]
+2  How to talk to me                                   [ ]
+3  Your business profile                               [ ]
+4  Your first automation                               [ ]
+5  Your dashboard -- where everything lives            [ ]
+6  Your approval queue -- signing off on things        [ ]
+7  Changing things later                               [ ]
+8  When things go wrong                                [ ]
+
+Pick a number to start, or just tell me what you want to explore.
+```
+
+---
+
+## Lesson 1: Welcome -- what this place does for you
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "Welcome. Think of this as your own team of tireless assistants -- each one handles
+> a specific job for your business automatically, so you don't have to. I'm going to
+> show you one of those automations actually running right now, then explain what any
+> of this means for you. Sound good?"
+
+### Flow
+
+**Step 1 -- Find or create a demo automation.**
+
+[Hidden action]: Read `operations/src/index.ts` to see if any automations are registered.
+
+- If one or more automations exist, pick the simplest one (lowest input complexity).
+  Note its purpose and a plain-language description of what it does.
+- If no automations exist, silently build a minimal "greeting" automation: a workflow
+  that accepts a name and returns "Hello from your assistant, {name}!". Deploy it to dev.
+  Do not narrate the build or deployment. The user only sees what comes next.
+
+**Step 2 -- Run the automation and show the result.**
+
+[Hidden action]: Execute the chosen automation with a simple example input (e.g., the
+user's first name if known, otherwise "Alex"). Wait for the result.
+
+Say something like:
+
+> "Here -- I just had one of your automations run. Here's what it did: [plain-language description of what happened, e.g., 'It sent a greeting to Alex']. That's one small example. Your automations can handle things like sending follow-up messages, collecting information, notifying you when something needs attention, or running a process on a schedule -- all without you lifting a finger each time."
+
+**Step 3 -- Explain the idea, not the technology.**
+
+Continue:
+
+> "You describe what you want to happen. I handle everything that makes it actually work.
+> You never have to think about the technical side. That's the whole idea here.
+>
+> Over the next few sessions we'll get your automations set up, show you where to find
+> them, and make sure you know exactly how to ask me for what you need.
+>
+> Ready to keep going? You can pick any lesson from the menu, or just say 'next' and
+> we'll go in order."
+
+**Step 4 -- Handle common responses.**
+
+- If the user asks "what can automations do?": give 3-4 concrete examples relevant to
+  the kind of business they have (read `core/config/organization-model.ts` identity
+  section silently to tailor examples). Keep examples short and practical.
+- If the user seems skeptical ("is this real?"): run the automation once more with a
+  different input to show it is live.
+- If the user wants to skip ahead: honor it. Show the menu.
+
+### Hidden actions summary
+
+- Read `operations/src/index.ts` to detect existing automations.
+- If none found: build and deploy a minimal greeting automation silently.
+- Execute the automation with a sample input.
+- Read org model identity section for context-relevant examples.
+
+### Completion signal
+
+The lesson is complete when the user has seen a real automation result and expressed
+willingness to continue (any affirmative or "next").
+
+[Hidden action]: Append the following to `.claude/memory/tutorial-progress.md` or
+create the file if it does not exist:
+
+```
+[x] YYYY-MM-DD  Lesson 1: Welcome -- what this place does for you
+```
+
+Then display the updated menu with lesson 1 marked complete.
+
+---
+
+## Lesson 2: How to talk to me
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "One of the most useful things to understand about working with me is that you don't
+> need to learn any special commands or remember any syntax. You just talk to me the way
+> you'd talk to a person. But there are a handful of patterns that tend to get you what
+> you want fastest. Let me walk you through them."
+
+### Flow
+
+Teach all seven conversation patterns from the vibe layer as natural examples. Never
+name the underlying classification system. Never use the word "intent." Present each
+as a short demo: show a sample thing the user might say, then narrate what you (the
+agent) heard and what you did.
+
+---
+
+**Pattern 1 -- Telling me to remember something**
+
+Say:
+
+> "If you want me to keep track of something, just say it like you'd tell a colleague.
+> Try: 'Remember to follow up with the Shopify client on Friday' -- and I'll add that
+> to your task list and confirm with you before saving it.
+>
+> Or: 'Add a note that we're pausing the email campaign this week.'
+>
+> Anything with 'remember', 'add', 'track', or 'note down' tells me you want something
+> saved. I'll always read it back to you before I write it down, so you stay in control."
+
+[Hidden demo, optional]: If the user wants to try it, let them dictate a real task.
+Confirm the captured text with them, then save it via the project CLI silently.
+
+---
+
+**Pattern 2 -- Asking me what's going on**
+
+Say:
+
+> "If you want to know the current state of things, just ask. 'What should I work on
+> next?' -- I'll look at your list and tell you. 'What's sitting in my approval queue?'
+> -- I'll check and report back. 'What automations are running right now?' -- I'll show
+> you.
+>
+> Questions about the current state of your work or your automations always get a
+> plain-language answer, no guessing required."
+
+---
+
+**Pattern 3 -- Asking me to explain something**
+
+Say:
+
+> "If you want me to explain what something is or what it does, tell me. 'Tell me about
+> the lead follow-up automation.' 'What does the CRM feature do?' 'Where am I in this
+> project?' -- those all work. I'll describe it in plain language, not technical terms."
+
+---
+
+**Pattern 4 -- Marking something done or stuck**
+
+Say:
+
+> "When you've finished something, just say so. 'Done with the proposal draft.' 'The
+> onboarding task is complete.' I'll find what you're talking about and update the
+> status. Same for blockers: 'Stuck -- waiting on client feedback' tells me you're
+> blocked and why.
+>
+> I'll confirm before I change anything, so nothing gets marked complete by accident."
+
+---
+
+**Pattern 5 -- Shifting focus**
+
+Say:
+
+> "If you want to change what we're working on, just say where you want to go. 'Let's
+> focus on the onboarding flow.' 'Switch to the Shopify project.' 'Back to the CRM
+> tasks.' I'll move our conversation to that area and summarize where things stand there."
+
+---
+
+**Pattern 6 -- Describing how your business works**
+
+Say:
+
+> "Here's a powerful one. If you tell me something true about your business that I
+> don't already know, I'll remember it and work it into everything I do for you.
+>
+> 'We're an e-commerce company -- all our deals come through Shopify or Amazon.' 'We
+> track our clients through discovery, proposal, and then closed.' 'Add a project type
+> called retainer with monthly billing.'
+>
+> I'll propose how to capture that in your business profile, and you confirm before
+> anything changes. Over time your profile gets richer and my automations get smarter
+> about your specific context."
+
+[Hidden action]: If the user says something that matches a Codify signal during the
+lesson, note it for later rather than interrupting the lesson flow. Mention it at the
+end of the lesson as a follow-up.
+
+---
+
+**Pattern 7 -- Turning things on or off**
+
+Say:
+
+> "Some things in your setup can be switched on or off. If you don't use a particular
+> feature, you can say 'Turn off the SEO tools' and I'll take care of it. Or 'Enable
+> the lead-gen feature.' You'll see what's changing and confirm before it's done."
+
+---
+
+**Wrap-up**
+
+Say:
+
+> "That's the whole set. You don't need to memorize any of it -- just talk to me
+> naturally and I'll figure out what you mean. If I'm ever not sure, I'll ask one
+> clarifying question rather than guess.
+>
+> Want to try any of these out before we move on?"
+
+**Handle free-form practice:** If the user wants to practice, engage with each message
+they send and narrate aloud what you heard ("That sounds like you want me to remember
+something -- let me read it back before saving..."). This is the best demonstration of
+the layer at work. Keep the narration light and friendly, not mechanical.
+
+### Completion signal
+
+Complete when the user has seen all seven patterns explained and has indicated they
+understand or are ready to continue.
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 2: How to talk to me
+```
+
+Display the updated menu.
+
+---
+
+## Lesson 3: Your business profile
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "The smarter I am about your business, the more useful every automation becomes.
+> So let's spend a few minutes filling in your business profile together. I'll ask
+> you some questions -- nothing technical, just real information about who you are
+> and what you do. You answer in plain language and I'll handle the rest."
+
+### Flow
+
+[Hidden action]: Invoke the org-model update ceremony silently. Do not name the
+underlying process. Work through each domain in order -- identity, customers,
+offerings, roles, goals -- by asking the user the corresponding plain-language
+questions below. After each answer, silently propose and write the update following
+the codify ceremony (snapshot -> propose in chat -> confirm -> write -> validate).
+
+The "propose in chat" step is allowed to show the user a plain-language summary of
+what you're capturing (e.g., "I'll save that your business is called Acme Co., a
+B2B SaaS company based in Austin, TX -- does that look right?") but NEVER shows them
+a diff, file path, or field name.
+
+---
+
+**Domain 1 -- Who you are (identity)**
+
+Ask:
+
+> "Let's start with the basics. What's the name of your business? And in one or two
+> sentences, what do you do?"
+
+Follow-up as needed: industry, where you operate, your mission if they have one.
+Confirm the captured summary before writing.
+
+---
+
+**Domain 2 -- Who you work with (customers)**
+
+Ask:
+
+> "Who are your typical customers? Are they businesses, individual consumers, or both?
+> What size? What industry?"
+
+Follow-up as needed: what problems do your customers come to you with, what does
+success look like for them. Confirm before writing.
+
+---
+
+**Domain 3 -- What you offer (offerings)**
+
+Ask:
+
+> "What do you sell or deliver? Is it a product, a service, or a mix? Do you have
+> different tiers or packages?"
+
+Follow-up as needed: pricing model, main deliverables. Confirm before writing.
+
+---
+
+**Domain 4 -- Your team (roles)**
+
+Ask:
+
+> "Who's involved in running things? Even if it's just you, I'd love to know what
+> hats you wear -- or if you have a team, who does what?"
+
+Confirm before writing.
+
+---
+
+**Domain 5 -- What you're working toward (goals)**
+
+Ask:
+
+> "What's the most important thing you're trying to achieve in the next six to twelve
+> months? Could be a revenue target, a number of new clients, a product launch --
+> whatever feels most real."
+
+Confirm before writing.
+
+---
+
+**Wrap-up**
+
+After all five domains are captured and written:
+
+Say:
+
+> "Your business profile is set up. I'll use this in every automation I build for you
+> -- so they'll talk about your clients the right way, track the things that matter
+> to your business, and use language that fits how you work.
+>
+> You can always update any of this just by telling me something new. Say 'we're
+> adding a new service' or 'our main goal changed to X' and I'll propose the update."
+
+### Hidden actions summary
+
+- Silently invoke the org-model ceremony for each domain answered.
+- Each write is gated by user confirmation in plain language (no diffs, no field names).
+- Run validation after each write; roll back silently if validation fails, then
+  say "That one didn't save cleanly -- let me try a slightly different way" and retry.
+
+### Completion signal
+
+Complete when at least the identity and customers domains are filled in and confirmed.
+The remaining domains are best-effort -- if the user doesn't know their goals yet,
+that's fine.
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 3: Your business profile
+```
+
+Display the updated menu.
+
+---
+
+## Lesson 4: Your first automation
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "Now let's build something real. Tell me one thing that happens repeatedly in your
+> business that you wish just happened automatically -- a notification, a message, a
+> daily summary, a reminder. Doesn't have to be complicated. What's the first thing
+> that comes to mind?"
+
+### Flow
+
+**Step 1 -- Gather the idea.**
+
+Let the user describe what they want. Ask one clarifying question if needed to
+understand frequency (daily? triggered by something?), destination (email? message?),
+and any key content.
+
+Good default suggestions if the user is stuck:
+
+> "A few easy starting points: a daily summary of what you need to do, an automatic
+> reply when someone fills out your contact form, or a weekly report of what got done.
+> Any of those sound useful?"
+
+**Step 2 -- Confirm before building.**
+
+Reflect back a plain-language description of the automation:
+
+> "So what you want is: [plain description, e.g., 'Every morning at 8am, send you an email with a list of your open tasks']. Does that sound right?"
+
+Wait for confirmation.
+
+**Step 3 -- Build and make it live.**
+
+[Hidden action]: Build the described automation as a workflow in `operations/src/`.
+Keep it simple -- a scheduler trigger or a manual trigger, a single action, a clear
+output. Deploy it to dev. Do not narrate the build steps. Only narrate the result.
+
+While building, say:
+
+> "On it. Give me a moment while I put that together..."
+
+**Step 4 -- Run it and show the result.**
+
+[Hidden action]: Execute the automation once with a realistic input.
+
+Say:
+
+> "Done -- your automation is live. Here's what just happened: describe the result in plain language. That will now run on schedule, or whenever it is triggered."
+
+**Step 5 -- Invite a reaction.**
+
+> "How does that look? If you want to tweak anything -- change the timing, add
+> something to the message, send it somewhere different -- just tell me and I'll
+> update it."
+
+Handle any adjustment requests by modifying and redeploying silently, narrating
+only the result.
+
+### Hidden actions summary
+
+- Build workflow in `operations/src/` based on user description.
+- Deploy to dev silently.
+- Execute once and capture result for narration.
+- If the user requests a change, edit and redeploy silently.
+
+### Completion signal
+
+Complete when an automation is running and the user has seen a real result and
+expressed satisfaction (or made and seen their first adjustment).
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 4: Your first automation
+```
+
+Display the updated menu.
+
+---
+
+## Lesson 5: Your dashboard -- where everything lives
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "Now that you have an automation running, let me show you where everything lives.
+> Your dashboard is the place where you can see what's running, check in on things,
+> and get a picture of how your automations connect. I'll walk you through it."
+
+### Flow
+
+**Step 1 -- Orient to the main sections.**
+
+[Hidden action]: Read `core/config/organization-model.ts` to identify which features
+are enabled, so you can tailor the tour to what's actually visible.
+
+Describe the dashboard in plain terms, based on the features that are on:
+
+> "When you open your dashboard, you'll see a few main areas. Your automations live
+> in one section -- that's where you can see which ones are active, when they last
+> ran, and whether anything needs your attention.
+>
+> There's also a map view that shows you how everything connects -- which automations
+> feed into each other, what triggers what. You don't need to understand the map to
+> use it, but it gives you a good sense of the bigger picture.
+>
+> [If CRM is enabled]: Your client pipeline lives in the CRM section -- that's where
+> deals and contacts show up.
+>
+> [If lead-gen is enabled]: The lead list section is where incoming prospects get
+> organized before they move into your pipeline.
+>
+> [If projects is enabled]: Your active projects and their tasks live in the projects
+> section."
+
+**Step 2 -- Point to the approval queue.**
+
+> "There's one more area worth knowing about now: your approval queue. That's where
+> automations pause and wait for you to give the green light before they continue.
+> We'll cover that in the next session."
+
+**Step 3 -- The map.**
+
+> "The map view is worth a quick look. It shows each automation as a box, and lines
+> connect the ones that pass information to each other. If something looks tangled,
+> that's usually a sign we should clean it up -- just tell me and I'll simplify.
+> The map is read-only from your end; you don't need to touch it directly."
+
+**Step 4 -- Reassure about navigation.**
+
+> "You don't need to memorize where everything is. Any time you want to find
+> something, just ask me: 'Where do I see my running automations?' or 'Take me to
+> the client pipeline.' I'll point you directly there.
+>
+> The dashboard is a place to observe. Changes happen here in our conversation."
+
+### Hidden actions summary
+
+- Read org model features section to determine which dashboard sections are visible.
+- Tailor the tour to only mention visible/enabled features.
+
+### Completion signal
+
+Complete when the user acknowledges they understand the main sections and the map.
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 5: Your dashboard -- where everything lives
+```
+
+Display the updated menu.
+
+---
+
+## Lesson 6: Your approval queue -- signing off on things
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "Some automations work completely on their own. Others -- especially ones that send
+> things to clients or make significant decisions -- are better if they pause and ask
+> you first. That's what your approval queue is for. Let me show you how it works."
+
+### Flow
+
+**Step 1 -- Check for an existing approval-gated automation.**
+
+[Hidden action]: Scan `operations/src/` for any workflow that includes an HITL step.
+
+- If one exists: use it for the demo.
+- If none exists: silently modify the automation built in lesson 4 (or the simplest
+  available one) to add a pause-for-approval step. Deploy the updated version.
+  Do not narrate the modification.
+
+**Step 2 -- Explain the concept first.**
+
+> "Here's how it works: an automation runs up to a certain point, then it stops and
+> puts a card in your approval queue. It waits there -- nothing moves forward -- until
+> you take a look and say yes or no.
+>
+> Your queue is accessible from your dashboard, and I'll also flag it here in our
+> conversation if something is waiting for you."
+
+**Step 3 -- Trigger the automation and show the pause.**
+
+[Hidden action]: Execute the approval-gated automation.
+
+> "I just triggered [plain description of the automation]. It's run the first part --
+> and now it's waiting for you. You should see a card in your approval queue in the
+> dashboard. Let me know when you can see it."
+
+Wait for the user to confirm they see it (or describe it to them if they can't navigate
+there yet).
+
+**Step 4 -- Walk through the approval.**
+
+> "In the queue you'll see a summary of what the automation wants to do, and a button
+> to approve or reject it. Approving means it continues. Rejecting stops it.
+>
+> Go ahead and approve this one -- it's just a test."
+
+[Hidden action]: After the user approves (or says they did), confirm the automation
+completed by checking execution status.
+
+> "And there it goes -- your approval unblocked it and it finished the job.
+> [Plain description of what completed, e.g., 'The summary email just sent.']"
+
+**Step 5 -- When to use the queue.**
+
+> "You decide which automations use the approval queue and which run automatically.
+> Anything that touches a client, sends money, or makes a commitment is usually worth
+> a pause. Anything routine -- daily summaries, internal notes, status updates -- can
+> typically run on its own.
+>
+> Whenever you build a new automation, just tell me whether you want it to pause and
+> ask you, or just run. You can always change that later."
+
+### Hidden actions summary
+
+- Check for existing HITL workflow; if none, add a pause step to the lesson 4 automation.
+- Deploy updated automation silently.
+- Execute it and narrate the pause state.
+- Check completion after user approves.
+
+### Completion signal
+
+Complete when the user has successfully approved a paused automation and seen it
+complete.
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 6: Your approval queue -- signing off on things
+```
+
+Display the updated menu.
+
+---
+
+## Lesson 7: Changing things later
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "Nothing you set up is permanent. Your business changes, your needs change, and
+> your automations should keep up. Changing things is as easy as describing what you
+> want differently. Let me show you."
+
+### Flow
+
+**Step 1 -- Remind them of the automation from lesson 4.**
+
+> "Remember the automation we built -- [brief plain-language description]? Let's
+> use that as the example. Tell me one thing you'd like to change about it. Could be
+> the timing, what it says, where it sends things -- anything."
+
+If the user has no preference, suggest one:
+
+> "For example, I could make it run twice a day instead of once, or add a summary
+> line at the top. What would make it more useful for you?"
+
+**Step 2 -- Take the plain-language change request.**
+
+[Hidden action]: Parse the user's request and identify what needs to change in the
+workflow. Modify the workflow and redeploy silently.
+
+While updating, say:
+
+> "Making that change now..."
+
+**Step 3 -- Confirm the update is live.**
+
+[Hidden action]: Execute the updated automation once to verify.
+
+> "Done. Describe the change in plain language. I ran it once to confirm it's working the new way."
+
+**Step 4 -- Teach the pattern for profile changes.**
+
+> "The same works for your business profile. If something changes -- you add a service,
+> rename a stage in your pipeline, bring on a new team role -- just tell me. I'll
+> propose the update, you confirm, and it's saved.
+>
+> For example: 'We're adding a new service called retainer coaching at $2,000 a month.'
+> I'd capture that as a new offering in your profile."
+
+[Hidden action]: If the user dictates a profile change, invoke the org-model update
+ceremony silently. Confirm with the user before writing.
+
+**Step 5 -- Teach the toggle pattern.**
+
+> "And if you want to turn a whole feature on or off -- say you're not using the
+> lead-gen tools right now -- just tell me: 'Turn off the lead-gen feature for now.'
+> Done. Turn it back on anytime the same way."
+
+**Step 6 -- Reassure about iteration.**
+
+> "The general principle is: you'll describe what you want, I'll propose the change,
+> you confirm, and it happens. You're always in the loop -- nothing changes without
+> your say-so."
+
+### Hidden actions summary
+
+- Modify and redeploy the lesson 4 automation per the user's request.
+- Execute the updated automation to verify.
+- If a profile change is mentioned, silently invoke the org-model update ceremony with
+  user confirmation.
+
+### Completion signal
+
+Complete when the user has successfully requested and seen at least one change applied
+to a live automation.
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 7: Changing things later
+```
+
+Display the updated menu.
+
+---
+
+## Lesson 8: When things go wrong
+
+**Estimated time:** 10-15 minutes
+
+### Opening line
+
+Say:
+
+> "Everything works most of the time. But sometimes an automation doesn't do what
+> you expected, something looks stuck, or you just don't see what you thought you'd
+> see. This is how we handle that."
+
+### Flow
+
+**Step 1 -- Establish the ground rule.**
+
+> "The rule is simple: if something looks wrong, tell me. In plain language. You don't
+> need to know why it's wrong or what the technical reason is. Just describe what you
+> expected to see and what you're seeing instead.
+>
+> Something like: 'I thought the morning summary would arrive by now but it hasn't.'
+> Or: 'The approval card I expected isn't showing up.' Or: 'It ran but the message
+> looks wrong.'
+>
+> That's all I need."
+
+**Step 2 -- Demo: investigate and report back.**
+
+Construct a realistic example based on the automations built during the tutorial. If
+possible, introduce a minor intentional issue (e.g., run an automation with a missing
+input) and let the user report it, or describe a fictional report for demonstration.
+
+[Hidden action]: When the user describes a problem (or for the demo, when the agent
+introduces one), investigate using execution logs and runtime state. Determine the
+plain-language cause.
+
+Narrate the resolution:
+
+> "I looked into that. Here's what happened: [one or two plain sentences describing
+> the cause in non-technical language, e.g., 'The automation ran, but the daily
+> summary was empty because your task list didn't have anything new since it last ran.
+> That's normal -- if there's nothing to report, it skips the message.'
+>
+> Or: 'It looks like it ran but the email didn't go out because the account connection
+> for your email provider needs to be refreshed. I'll walk you through reconnecting
+> it if you want.']"
+
+Never show: stack traces, error codes, file names, log excerpts, or raw system output.
+Everything must be translated to plain language before the user sees it.
+
+**Step 3 -- Cover the common scenarios.**
+
+Walk through three common situations briefly:
+
+> "There are really three situations you'll hit:
+>
+> 1. 'Nothing happened when I expected it to.' -- Tell me what you expected. I'll
+>    check whether it ran, when it ran, and what it did.
+> 2. 'It ran but the result looks wrong.' -- Describe what looked off. I'll figure
+>    out what went into it and why the output is different from what you expected.
+> 3. 'Something seems stuck.' -- Tell me which automation and what you last saw.
+>    I'll find out if it's waiting for something (like an account connection that
+>    needs attention) and tell you what needs to happen next.
+>
+> In all cases, my goal is to give you one clear answer: here's what happened, and
+> here's what (if anything) you need to do."
+
+**Step 4 -- Set expectations on timing.**
+
+> "Most issues I can diagnose immediately. If I need a few moments to investigate
+> something more complex, I'll tell you I'm looking into it and come back with an
+> answer. I won't leave you hanging with technical jargon -- I'll always translate."
+
+**Step 5 -- Invite a real question.**
+
+> "Is there anything that's already looked odd or unexpected? Now's a good time to
+> ask -- or you can come back to me any time something doesn't look right."
+
+### Hidden actions summary
+
+- When a problem is described: read execution logs, check runtime state, identify
+  the plain-language cause.
+- Never surface raw technical output; translate everything.
+- If an account connection issue is detected, guide the user to reconnect it without
+  naming the technical mechanism.
+
+### Completion signal
+
+Complete when the user has seen at least one problem diagnosed and explained in plain
+language and indicates they understand the process.
+
+[Hidden action]: Update `.claude/memory/tutorial-progress.md`:
+
+```
+[x] YYYY-MM-DD  Lesson 8: When things go wrong
+```
+
+Display the updated menu with all 8 lessons marked complete (assuming they are).
+
+---
+
+## After All 8 Lessons Complete
+
+When all eight lessons are marked complete in `.claude/memory/tutorial-progress.md`,
+display this closing message:
+
+> "You've been through everything. You know how to talk to me, your business profile
+> is set up, you've built and changed a real automation, you can find your way around
+> your dashboard, and you know what to do when something looks off.
+>
+> Here's what I'd suggest next: think of one thing in your business that happens
+> repeatedly and takes your time. Tell me about it. I'll build it for you.
+>
+> If you ever want to revisit any of these sessions, just say 'tutorial' and I'll
+> bring up the menu again. Any lesson you want to redo is always available."
+
+Then stay in the conversation ready for the user's first real request.
+
+---
+
+## Progress File Format
+
+The file `.claude/memory/tutorial-progress.md` must follow this format:
+
+```
+# Tutorial Progress
+
+Track: vibe-coder
+Started: YYYY-MM-DD
+
+## Lessons
+
+[ ] Lesson 1: Welcome -- what this place does for you
+[ ] Lesson 2: How to talk to me
+[ ] Lesson 3: Your business profile
+[ ] Lesson 4: Your first automation
+[ ] Lesson 5: Your dashboard -- where everything lives
+[ ] Lesson 6: Your approval queue -- signing off on things
+[ ] Lesson 7: Changing things later
+[ ] Lesson 8: When things go wrong
+```
+
+Replace `[ ]` with `[x] YYYY-MM-DD` as each lesson completes. Create the file on
+first use if it does not exist, pre-populated with all eight lessons unchecked.