Statewave Guide — Day 0 + Day 1 · Social copy

Week 1 of the series (KW 40). Blog texts: day-0-the-beginning.md, day-1-the-dom-is-not-the-product.md.
All times UTC. Blog first, then everything that links to it.

Day 0 is live since 28 Sep: https://www.statewave.ai/blog/statewave-guide-day-0 — the URL is already filled in below. Note the www.
[BLOG-1] = https://www.statewave.ai/blog/statewave-guide-day-1 — replace after Day 1 is published, and open the page before posting anything that links to it.

Accounts: X runs on @StatewaveAI (decided 18 Sep, Kai-Uwe), so the threads are in the
we voice. LinkedIn runs as a feed post directly on Saber's personal profile in the first
person, reshared by the company page (decided 18 Sep, Kai-Uwe). The blog text stays in
Saber's first person. No separate announcement the week before: Day 0 is the announcement.

Day 0 — X thread, @StatewaveAI (Mon 28 Sep, 21:00 UTC)

1/
The code is ahead of this story.

For a few weeks we've been building Statewave Guide in public: in-app help that works from the source code alone. 16 build days, all on GitHub.

Starting today we're writing up the why. One or two days a week.

Day 0 🧵

2/
What we wanted sounded simple: a help chat that knows how the product works.

You ask "Where do I change this?" and instead of five paragraphs it takes you there. Highlights the control. Walks you through. Remembers next week that you already learned it.

3/
There are great chat frameworks, product-tour libraries, doc generators, RAG systems.

We couldn't find the thing we wanted:

source code → product understanding → memory → guidance inside the real app

4/
One requirement came fast: no second copy of the app in Confluence just so the assistant understands the first one.

Routes, forms, endpoints, schemas, permissions, tests, translations, Git history.

The knowledge is already in the code. We just don't call it documentation.

5/
So we're building our own guidance engine, with Statewave underneath for memory.

Day 0's question:

Can source code become reliable product knowledge without anyone maintaining a knowledge base beside it?

6/
Day 0 in full: https://www.statewave.ai/blog/statewave-guide-day-0

If you want the ending now, it's in the repo: github.com/smaramwbc/statewave-guide

Day 1 on Wednesday.

Image for post 1: guide-day0-og-1200x630.png.

Day 0 — LinkedIn, Saber's profile (Mon 28 Sep, 21:00 UTC)

Post:

For a few weeks I've been building something in public without telling the story behind it.

The code is on GitHub. 16 build days. What isn't there is the why.

Starting today I'm writing it up, one or two days a week.

Day 0 started with something that sounded simple: a help chat that actually knows how the product works.

Not a bubble that links you to a 200-page documentation site.

Something that answers "Where do I change this?" by taking you there. It highlights the right control, walks you through the task, and remembers next week that you already learned it.

I looked around. Great chat frameworks, product-tour libraries, doc generators, RAG systems. Lots of good pieces. Not the thing I wanted.

One requirement became clear fast: I don't want developers maintaining a second version of their application in Confluence just so an assistant can understand the first one.

A modern codebase already holds an enormous amount of product knowledge. Routes, forms, permissions, tests, translations, Git history.

We just don't call it documentation.

So the first question was:

Can source code become reliable product knowledge, without anyone maintaining a knowledge base beside it?

The next posts are about everything we got wrong on the way to an answer.

Image: why-statewave-guide-exists.png, cropped to the "decisions" block (the full graphic is too tall for the feed; brief §5).

First comment (right after publishing):

Day 0 in full: https://www.statewave.ai/blog/statewave-guide-day-0
The repository, including where it ended up: https://github.com/smaramwbc/statewave-guide

Company page reshare (Tue 29 Sep, 05:00 UTC), text above the reshare:

A new build log starts today: how Statewave Guide learned to explain an app from its source code alone, one build day at a time.

No hashtags in the body. If the team wants them: at most #buildinpublic #opensource at the very end.

Day 1 — X thread, @StatewaveAI (Wed 30 Sep, 21:00 UTC)

1/
Statewave Guide — Day 1: The DOM is not the product.

Day 0 ended with 141 files, 257 tests green and a first closed loop:
source → graph → running UI → navigate → highlight

"Nice. This is going surprisingly well."

That lasted about five minutes. 🧵

2/
Adversarial review. All green. And still:

– a path with ( gave an empty graph
– a render loop heading past 300 renders
– a selector injection edge case toward input[type="password"]
– constructor, inherited from Object.prototype, gone from the graph

257 tests. Still broken.

3/
The bugs weren't the interesting part. What they forced was.

The DOM can say "there's a button here". That's scenery.

The product is:
clients.create → openCreateClient() → NewClientDialog → submitClient() → clientService.create() → POST /api/clients

4/
So: the DOM is runtime evidence. It is not the product model.

The model comes from the source. The running UI links back through stable ids like data-guide="clients.create".

No hoping the third button in the fourth div survives Friday's redesign.

5/
And the rule we suspect survives the whole project: unknown is better than wrong.

Provable edge: stored, with file, symbol and line.
"The names look similar, it probably opens a dialog": nothing stored.

Send users to the wrong screen twice and nobody trusts it again.

6/
Day 1 in full: [BLOG-1]
This day in the repo: github.com/smaramwbc/statewave-guide/pull/1

Next question: can we follow one real user action from a button to the backend without guessing?

Image for post 1: Day 1 OG (still to be made; brief task 9).
No LinkedIn for Day 1: Wednesday posts run on X, blog and dev only (concept, decision D4).

dev.to + Hashnode (23:00 UTC on the same night)

Series name on both platforms: Statewave Guide — Build Log. Create it with Day 0, so the table of contents and prev/next work from the first post.

Check after saving: canonical URL in the post settings points to statewave.ai, and the post shows up in the series.
Relative links (/blog/...) in the body must become absolute (https://statewave.ai/blog/...) on both platforms.

X micro-beats for the week after (KW 41, Day 2 week)

Only quote days that are already published. Night slot 21:00–22:30 UTC, Tue or Thu, or Sunday.

Tue 6 Oct

257 tests. All green.

Then adversarial review found a React render loop heading past 300 renders, and constructor quietly vanishing from our graph because it's inherited from Object.prototype.

Green tests only prove what the tests asked.

Thu 8 Oct

A browser DOM tells you "there's a button here".

That's not product knowledge. It's scenery.

Product knowledge is: this button → this handler → this dialog → this form → this service → POST /api/clients.

With the file and line for every arrow.

Pre-flight checklist (both nights)

• [ ] Journey Index /blog/statewave-guide live (footer and index links depend on it)
• [ ] Blog post live and opened before any link is posted
• [ ] Scheduler set to UTC, time read back in the tool
• [ ] LinkedIn link in the first comment, not in the post
• [ ] Canonical checked on dev.to and Hashnode
• [ ] No star, upvote or share request anywhere
• [ ] Night watch named for 21:00 UTC; first light from 06:00 UTC