@bigsteele/the-walkthrough

Reads your app the way a user meets it, works out every job a person comes there to do, grades the help you already have, and writes the help you do not.

npx @bigsteele/the-walkthrough

Writes the-walkthrough-<app>.md and .json into the repository. Exit code 0 when every job has a page, 2 when some do not, 1 when it refuses.

The number it leads with

Not a coverage percentage. Jobs people come here to do, against jobs that have a page.

| | Today | After | |---|---|---| | Jobs with a page that reads plainly | 3 of 17 | 17 of 17 | | Reading level of the help you have | grade 11.2 at worst | grade 6 or below | | Pages an agent can read as markdown | none | llms.txt plus a mirror per page |

It reads routes, not components

A help centre built from a list of components is a tour of the codebase. Only something with a URL counts as a screen here, because a URL is the only proof a person can actually get somewhere. Those screens are then grouped into jobs, because nobody wakes up wanting to visit /dashboard/keys; they want an API key.

Supported routers, in the two families they come in. Some put the route table in the folder names, and reading the tree reads the product: Next App Router, Next Pages, SvelteKit, Astro, including when the app is a package inside a monorepo. Others keep the routes in code, so the declarations are read instead: React Router (<Route> elements, the createBrowserRouter array, nested paths, index routes, and a path written as a named constant like path={ROUTES.billing}) and TanStack Router (createRoute with getParentRoute).

API routes are found and kept separate, because nobody lands on /api/webhooks/stripe and a walkthrough that said so would be fiction.

If it cannot read your app, it says so. A scan that finds no screens has failed, because every product has screens. It will not print "0 of 0 jobs" and let that read as a pass.

Two checks, because plain is not the same as visible

npx @bigsteele/the-walkthrough --check

The first is reading level. "Write it simply" is advice nobody can fail. A grade is a thing you can fail, so every page is measured with Flesch-Kincaid, the same score plain language regulators use, and the check exits non-zero above grade 6.

The second is whether the reader can see themselves. The grade cannot see this at all. "This page documents the credential management interface" is short-worded, short-sentenced, and tells a frightened person nothing about their own evening. It scores well and is invisible.

So the opening of every page is checked separately, on one question: can this reader immediately notice how their own situation is different? The opening has to contain the reader ("you"), a moment they recognise, and one concrete thing. If it does not, the page is marked UNSEEN and the tool names the swap that fixes it.

FAIL  grade  10.5   6 long   2 jargon  UNSEEN  help/curated-feeds.mdx
        split this (29 words): Updated every few hours from a curated set of...
        say "way for programs to talk" instead of "api"
        opening: "About the platform. Background on how the product works..."
        the symptom swap: Cut "platform". Say the thing your reader already feels.

| What is wrong with the opening | The swap it names | |---|---| | Uses an insider word | symptom swap | | The software is the subject | outcome swap | | The change is far away in time | time swap | | Pure abstraction, no moment | scene rewrite | | Asserts a size instead of showing a picture | number rewrite | | The reader never appears | person swap |

What this cannot do. The real test needs three fit buyers, cold, asked one question: "what would be different for you?" A machine cannot be a buyer. This is the pre-filter that catches the mechanical failures before a person has to look, and it says so rather than claiming a page has passed.

Scaffolds are a leash, not a template

A model asked to "write help docs for this app" invents buttons. So the scaffold arrives with the facts already in it, and the prose left blank:

<Step n="1" caption="TODO: what the reader does here, in under nine words">
  {/* EVIDENCE, from the scan. Delete this comment when the step is written.
     route: /signup
     file: src/app/signup/page.tsx
     buttons here: "Create my account"
  */}

Every label is lifted verbatim from your source. The writing rule is that nothing may be claimed that the scaffold does not already contain. An invented button is worse than a missing page: a missing page sends someone to support, an invented one sends them in circles.

--run opens Claude Code with the writing protocol and these scaffolds loaded.

The pictures, which a help page is half made of

Every step points at a screenshot, and for a long time nothing created one. The instruction was "fill any screenshot the pages point at, or delete the <Screenshot> line", and everybody takes the second half. A walkthrough with no pictures is a list of instructions, which is the thing people were already not reading.

So --write also scaffolds the pictures, as HTML you edit:

help-visuals/<job>/step-01.html   a drawing of that screen
help-visuals/mockup.css           four colours, and it is yours after the first run
node help-visuals/capture.mjs     Chrome turns each one into the PNG the page wants

A drawing, not a capture, and that is on purpose. A real screenshot needs the app running, signed in, seeded, and sitting on exactly the screen the step describes. Step four of a billing flow needs a card on file, a subscription mid-cycle and a failed payment. Nobody sets that up eight times for one page, which is why the screenshots never get taken. A drawing needs a text editor. It is in version control, it renders the same on every machine, it never leaks a real customer's name, and it will pose for the empty state and the error state, which a live app will not do on request.

The app's own words are already in it. The button labels, the field labels and the address bar come out of your source. A model asked to mock up a billing screen invents a button called "Manage Subscription"; handed a drawing that already carries the real label, it cannot, because the job is editing rather than inventing. Same leash as the prose.

Nothing you have touched is overwritten, and that rule is stricter here than for the pages: an existing mockup is skipped outright rather than written beside it, because a step-01.new.html would be captured into the same PNG and quietly win.

node help-visuals/manifests.mjs content/help

writes a .manifest.json beside every finished page, for a narrator or a video pipeline to read instead of parsing MDX. It is DERIVED: the page is the source, edits to a manifest are lost on the next run, and a page still full of TODOs is skipped.

It checks what your docs say about money

Entitlement sentences are the highest-cost sentences in any help centre, because they are the ones a reader acts on with a credit card. A live product told customers a feature was "Pro and up" for three months after the code gave it to every plan, on the one page whose whole job was explaining that feature. Nobody lied. A policy changed and a sentence stayed behind.

So plan and role gates are read from the code, and every claim in the docs is checked against them. Each finding is phrased as a question, because the tool knows the two sides disagree, not which one is right.

It will not write a page you already have

Matching a free-form page title to a route cluster is a guess. Where a help centre exists and nothing in it obviously covers a job, the verdict is check, not write, and the pages nothing claimed are listed by name. Two pages that disagree is worse than one page that is out of date.

Nothing is ever overwritten. An improved version of an existing page is written beside it.

An llms.txt, and a markdown mirror

The MDX a docs framework renders is not what a model should read: it is full of components it has to guess at. So the same content ships twice.

| | | |---|---| | llms.txt | one index at the site root, so an agent learns what exists in one request | | llms-full.txt | every page inlined, in reading order |

Steps become numbered markdown, narration becomes prose, and a screenshot becomes its alt text, so a model reading your docs gets what a person gets.

Where it writes

Read from your setup rather than assumed: Fumadocs (content roots read out of source.config.ts), Docusaurus, Mintlify, Nextra, VitePress, MkDocs, Starlight, Docsify, or a plain markdown folder. Writing Fumadocs MDX into a Docusaurus site produces a build error, not a help centre.

Options

the-walkthrough [dir]        scan and report (writes nothing)
the-walkthrough --write      also scaffold the pages, the navigation, and llms.txt
the-walkthrough --run        open Claude Code with the writing protocol
the-walkthrough --check      fail on reading grade, or an opening the reader is not in
  --repo <dir>   --out <dir>   --root <dir>   --site <url>   --grade <n>
  --stdout       --yes

What it never does

No network, no database, no shell. It never opens an .env file. It never copies your source into its output: what it reports are paths, counts, and the labels your own interface already shows to users. If any output string matches a credential shape, nothing is written and the exit code is 1, because that means a secret is committed and that is the thing to fix first.

After the report

Send it in at bigsteele.com/scan and get a written read of the three pages to write first and what to put in them. Free, no call required, no pitch inside it. The live Scan Analysis call is $497, booked from the same page.

Big Steele · bigsteele.com