A readme is the written explanation that travels with your work: a plain-language description of what a workflow does, or what a single step does, kept right alongside the thing it describes. It's how the next person, or you in six months, understands a workflow without reading every line of code.
Part of the workflow
A readme isn't metadata stored off to the side; it's a file that lives inside the workflow, right next to the steps and their code. That means it's versioned along with everything else, travels with the workflow when it's cloned or synced through git, and changes as part of the same edits that change behavior. The intent is that the explanation and the implementation stay together, so the docs move whenever the workflow does.
Two levels of readme
Readmes exist at two levels, and they answer different questions.
A workflow readme describes the workflow as a whole: what it's for, how it's triggered, and the shape of what flows through it. It shows up on the workflow's Readme tab, so it's the natural first stop for anyone trying to understand the automation at a glance.
A step readme describes one step. It's the first thing you see when you open a step, explaining what that piece does, what it talks to, and the shape of its input and output. Where the workflow readme gives the overview, step readmes fill in the detail piece by piece.
Together they let someone read top-down: start with the workflow readme for the big picture, then dip into a step's readme when they need to know exactly how that part works.
Written in markdown
Readmes are written in markdown and rendered as formatted text, so they can be genuinely readable rather than a wall of plain text. Headings, lists, tables, and code samples all work, and a diagram can be dropped in when a picture of the flow makes the logic clearer than words would.
The point is clarity: format in service of explaining, not decoration.
Links that navigate
A readme can link to the workflow's own files, and those links become in-app navigation. A mention of a particular step's script, written as a normal markdown link, turns into something a reader can click to jump straight there.
That keeps a readme connected to the thing it describes: instead of saying "look in the Filter step," it can send the reader there directly. It's part of what makes a readme a map of the workflow rather than a separate document that drifts out of date.
You don't have to start from scratch
When a workflow has no readme yet, Tines 3B says so and offers to write one for you. Because Tines 3B can read the whole workflow, it can produce a first draft that describes what's actually there, giving you something to refine rather than a blank page. From there, the best readmes are kept current: updated when a workflow's purpose or structure changes, and left alone for pure tidying that doesn't change what the workflow does.