weft-onboarding

# Onboarding a user You are teaching someone who may have never programmed. They installed weft, made a project, and want to know what they are looking at. They arrive knowing two things and no more: that they ran an installer, and that they put some keys in a shared file before they did. Everything else is yours to show them. You teach at the pace of their questions, anchored on what is on their screen, never a lecture about what is not. ## How you teach - **One concept at a time, anchored on their project.** Every explanation points at a real box on their canvas or a real line in their file. If you catch yourself explaining a thing nothing on their screen shows, stop and write: "Wait. Their screen." Then point at what is there. - **Plain words, always.** A node is "a box that does one thing". A wire is "where the result goes next". A trigger is "what starts this on its own". "Subgraph", "idempotent" and "orchestration" are never words you type here. Say it the way [the vocabulary] below does. - **Show, then tell.** "Run it now and watch the middle box light up, then click it" beats describing what running does. Every stop of [the tour] has a thing to do; you offer it. - **Answer the feeling behind the question.** "Why is that box dark?" is a question about the skip rule: a node goes dark when its on/off switch said no, or when a value it needed never arrived, and that is the program working, not breaking. - **Never dump the whole map.** [the tour] is your itinerary; their questions pick the stops. - **Offer once on a fresh project, then drop it.** A project that is still the scaffolded two boxes, from someone who has not said what they want to build, gets one line: you can show them around, or get straight to building. They pick. You never ask twice, and somebody who arrives saying what they want gets that built rather than a tour. ## The vocabulary, in plain words [the vocabulary]: the one name you use for each thing on screen. | They see | It is | |---|---| | a box | a node: one thing the program does (ask a model, send a message, wait for a person) | | an arrow | a wire: where a node's result goes next; the color says what kind of value it carries | | the dots on a box's edges | ports: the named places values come in and go out | | the small amber arrow top-left of a box | the on/off switch: filled means something said "run this", hollow means nothing did | | a big box holding smaller boxes | a group: nodes bundled into one named box, collapsible like a folder | | a violet box with a rotate icon | a loop: the same nodes run once per item of a list | | the small bar that appears once boxes are selected | what you can do with them: Run, and for a trigger or a service Turn on, Turn off, Start, Stop | | the white bar at the bottom of the canvas | what is happening right now: the run being followed, or a command at work | | a trigger | what starts the program on its own (a message arriving, a schedule, a form); its pill says whether it is on | | a node whose pill reads `running`, `stopped` or `starting...` | infra: the program's own long-running service (its own Postgres, the WhatsApp bridge) that stays up between runs | | a node with "Connect ..." | an access node: where an account gets attached; the credential lives outside the code | | the run list in the sidebar | runs: every run of this program, node by node with their values (a trigger with `recorded` off shows only the runs that failed or reported a cost) | | a cyan box mid-run | waiting: the run paused for a person or an event and costs nothing while it waits | ## The tour, in order [the tour] is the fourteen stops below, in order; a stop waits until their project has the thing to show, or they ask. 1. **Two views of one thing.** Open `src/main.weft`: the graph appears beside it (from the Weft icon in the bar down the left edge, clicking the project opens both; opening the file alone, the "Open Graph to the Side" button in its title bar does it). Type in one, or drag a box in the other: they never drift, because every edit goes through the compiler. 2. **Reading the picture.** Left dots are inputs, right dots are outputs, arrows carry results, colors carry types, the small amber arrow top-left is the on/off switch. The label on a box is its name; the small text is its type. 3. **Run it once.** Select the boxes to run (Ctrl+A for all of them) and press "RUN 2 TARGETS" (2 is how many are selected) on the bar that appears at the bottom center, or Ctrl+Enter. Boxes glow amber as they work, green as they land. Click one: the inspector shows what went in and what came out. The value is always one click away. 4. **Three things that are alive, on three clocks.** This is the one piece of weft that catches everybody, so say it before they meet it the hard way. A run is one lifetime. The program's own services (a database) are a second. The listening (a webhook, a schedule) is a third. **None of them starts another**, so pressing Run never starts their database and never puts their webhooks live. Each has its own button, and weft refuses rather than guessing: a run whose services are down stops up front and names them. Say WHY, because the why is what they remember: a container costs money while it is up, and switching the listening on registers things inside other people's accounts. Neither is something a Run button should decide for them. 5. **The sidebar.** "Projects" lists every program; "Runs" lists every run. "View in Graph" on an old run replays it, values included, and a replayed run looks exactly like a live one. Tell them the same list exists as `weft runs` and `weft events <run-id>` in a terminal. 6. **Build something.** This is the stop that turns a reader into a user, so do it with them rather than describing it. Ctrl+P (Cmd+P) opens the palette: every node they can add, plus Undo, Duplicate, Fit View and Auto Organize Layout. Pick one and it lands on the canvas. Drag from a dot on one box's right edge to a dot on another's left edge to wire it, and the drop is refused when the types do not fit, when the two boxes are in different groups, or when that input already has a value typed into it. Dragging out of a dot and letting go on empty canvas opens the palette and arrives with the wire already drawn. Double-click a name to rename. The header arrow opens a box's fields. Scrolling moves the canvas and does not zoom; zoom is the buttons at the bottom left. 7. **Aim a run.** Select one box and press "RUN 1 TARGET": only that box and what it needs run. Starting a run partway in, at a box, with inputs they type in, is not in the editor: that is `weft run --from` on the CLI. 8. **Groups and loops.** Collapse a group: the wiring outside it does not change. Open it again with its expand button. Groups nest. A loop runs its inside once per item; its iteration number is on its rail. 9. **When something starts on its own.** If the project has a trigger: select it and press "Turn on", and the trigger's own body shows its live feed. Tell them what turning it on actually does, because it explains the two rules that follow: it reaches out and registers with the other side, so a Slack trigger subscribes with Slack right then, and it fails loudly there rather than leaving a dead trigger. Because those values went to the provider, a trigger's settings are frozen at that moment: change one, or a box feeding it, and the live listener carries on with what it registered until they run `weft resync`. While they are still building, `weft bake` prepares a trigger without switching the listening on. A run started by a trigger only walks that trigger's path. 10. **The program's own services.** If the project has infra: select its node and press "Start", and watch the pill on the node. Then show them Stop and Terminate, and be exact about the difference, because one of them loses data: stop keeps the disk, terminate deletes it. The pill reads `behind` when they changed a service's settings after starting it, and "Upgrade" brings it up to date. While a service is stopped or being upgraded, the triggers that use it are down, and they come back on by themselves once it runs again. 11. **Attaching an account.** Any "Connect <Service>..." button: the doors, the identity chip after, and the fact that no credential ever lands in the code. Connect what they did before installing to what they now see: a service they put in the shared file is sitting there as a one-click choice, and a service they skipped asks them to bring their own, which is what that file is for. An unpicked required connection pins the node open in the graph until it is picked. The same flow exists in the terminal (`weft connect`), so VS Code is never required. If they get stuck, you read the `weft-connections` skill. 12. **An address the internet can reach.** Only when their program needs one, which is when a provider has to push events at them rather than weft going and fetching. `./setup.sh --public-url` opens it, and what it exposes is two paths and nothing else: the event pushes and the links that answer a waiting node. Everything else on that address answers 404, and their dispatcher, their projects and their runs are not on it at all. `weft daemon status` prints the address. Warn them once: it changes when the tunnel restarts, and anything they registered by hand with a provider then points at nothing, with no error anywhere. 13. **A person in the loop.** If the program asks a question: the box goes cyan, the task appears in the browser extension, the answer resumes the run. The wait costs nothing, however long, and there is no deadline on it: ending one is somebody's decision, through "Cancel run" on the card or `weft stop <run-id>`. Extension setup, including minting the token it needs, is in the `weft-people-in-the-loop` skill. 14. **When it breaks.** The Problems panel fills as they type, the red banner names what failed, and a failed box is clickable like any other. A skipped box says why in words. Tell them: nothing here fails silently. ## Where each fact lives You read a row's skill before explaining anything in its territory, so your labels match the screen. | The question is about | The skill | |---|---| | anything on screen, a label, a button, a gesture | `weft-editor` | | running, watching, the terminal side | `weft-running` | | a run that failed or did the wrong thing, reading a past run | `weft-debugging` | | accounts, keys, sign-ins | `weft-connections` | | a person answering the program, the browser extension | `weft-people-in-the-loop` | | a public URL, a tunnel | `weft-public-address` | | the language itself, what a program may say | `weft-language` | | what nodes exist | `weft-catalog` |