Decisions

Why is there one set of docs?

Because two drift. The repository and the website each had their own copy of most pages, and they disagreed on wording, names and which pages existed. With one file, a developer reads the same thing on GitHub and on www.local.link, and a change is one edit.

Why are a folder's pages in that folder?

So a pull request that changes a folder's code changes its pages in the same place, and a folder that leaves for a repository of its own takes its pages with it. OpenClaw's pages are in link-openclaw, Link Harness's in link-harness; the core keeps the pages that span them, such as Agents.

Why does a page's URL follow the tree?

Because a URL should say where a page is, the way the site does: /harnesses/openclaw/security reads as Harnesses, then OpenClaw, then Security. A file's path in its folder's docs/en/ is still its URL, so a folder holds its pages at their place in the tree (link-openclaw/docs/en/harnesses/openclaw/). A page that moves keeps its old address working: website.md's ## Moved lists it, and the old URL redirects for good.

Why is the site a tree?

Because a reader learns a few ideas at a time, and looks for a page by what it's about, not by which folder holds it. The home page has its ideas (your agent, any harness, any model, any machine, the waitlist), each a tab, and each tab opens a few more, and so on down. So website.md holds the tree, and a page outside it would leave the reader lost, so the build refuses one.

Why a tree beside the page, not rows of pills?

Rows of pills, one per level, worked for a few pages. At a hundred, five rows deep, they lost the hierarchy: a row didn't say what it was under. A tree shows every level at once, the page you're on dark and the sections above it in bold, the others folded with how many pages each holds. It's the whole site's, not one tab's, so it stays put as you go from Machines to Models, and you never lose the map. It also holds the page's own headings, under the page, so "On this page" is part of it rather than a column of its own. Until the screen is wide, it folds into one bar that says where you are. The tabs stay pills, and drop down their pages, so any page a level down is one click from anywhere.

The tree also helps a reader keep their place. A heading is marked with a #, so a place on the page never passes for a page, and a section of pages shows how many it holds, with an arrow that opens it. The heading you're reading is lit as you scroll. One you pick glides into view, and its whole section is lit for a moment where it lands. A tab's menu stays down while you click the tab, and for a moment after the pointer leaves.

Why at most ten under a heading?

A reader takes in about ten things at a glance; past that, a list is something to search. So no page has more than ten pages under it in the tree, and no heading more than ten headings under it: a longer list is grouped under headings one level deeper.

Why do a part's specs, Decisions and Security come last?

They describe the part beside them, so they sit with it, after a line: what it does first, then exactly what it reads, why it is so, and what it guarantees. A reader learning the part never has to step over them.

Why do links between folders go to www.local.link?

A relative path from one folder into another works only while both are in one repository. A link to the page on https://www.local.link works on GitHub, keeps working when a folder moves out, and the website turns it into a link within the site, in the reader's language.

Why does the release deploy the website?

So what the website says is what the latest release does, and never what a failed or unreleased change would.

Why is the website its own folder?

The website and the command line share nothing but the docs. In its own folder, each builds without the other's tools, and Vercel builds only the site.