Skip to content

The documentation: who reads it, how it is organised, how it is written

A source

This page is a source of edakit – a concept, a prompt or the rules of a session –, shown as it is in the repository. Read it as such; the guides say what edakit does.

Status 2026-11-01: built – D.2 to D.9 in one evening on the owner's word, one branch, the judgement calls in documentation-assumptions.md and the chapters' reviews in documentation-review/, for the owner's review; 1.0.0 was released on 2026-11-02 on the owner's word, at the first order (#210); the review closed on 2026-11-02 with decision 7 of documentation-newcomer.md – rule 5 stays strict – and the concept moved to done/. Decided 2026-10-31 – the eight decisions and what Claude decided itself accepted by the owner the same day, and a ninth and a tenth added by the owner the same evening (the circuit alone as a station; condensing as a rule, with its measure); an eleventh to a fourteenth on 2026-11-01 – the case for edakit on the start page, confirmed by the owner with the vision line added, and a gallery of the projects built with edakit, a page per project with its schematic and board pictures, accepted with the owner's additions, future work – two items, then a third, on the owner's word –, and the architecture – the mechanism on the reader pages, "edakit as a meta-harness" on a page for developers, the word named once at the start of the README –, in a decision round in Claude Code's form (the table at the end); D.1 built the same evening (docs/style.md, docs/glossary.md, tests/test_style.py, tests/test_references.py); each step D.2 to D.7 and D.9 starts on the owner's word, one per branch, listed in TODO.md. Written against main at 8fba5f2; the gallery checked against main at a6ae71a – its pictures are the release protocol's section 12 (since 741cc9a), and chapter 18, the second walkthrough, joins "The board"; the whole checked again against main at 08a6951 the same day, after 155 commits on main in a day – versions and a changelog (versioning.md), outreach.md building on D.2, D.7 and D.9 for its launch, the README's new sections, the four makers live –, the places below following; on the owner's word the same evening D.2, D.7 and D.9 come ahead of the other todos (decision 15). Asked for by the owner: the pages are comprehensive but confusing, so unreadable – a concept for how the documentation should look, be organised and be written, who its readers are, the language and its style, what is missing for it to be understood, everything needed so that others use edakit. With one condition the owner set while it was written: everything docs/organisation.md does not list as documentation – skills, agents, CLAUDE.md, the catalog's and the domains' texts, the manifests, the concepts – is data the automation reads; a change there may break something elsewhere or shift a meaning, so this concept leaves it alone and says where documentation itself is read by the automation; and a rule for every change: when unsure, ask – or check whether the text is generated or used elsewhere, which says to leave it as it is. The findings come from the site built from main (docs/pages.py, MkDocs), the Markdown measured – words, sentence lengths, headings, cross-references, the words that go unexplained – and the code and tests that read the documentation.

The short answer

The documentation is complete and checked against the code, and it is written for one reader: the owner, who knows every term, every project and every chapter number. 220,000 words on 63 pages – the handbook 107,000, the concepts 111,000 – with no page of one screen that says what edakit is and for whom, no path to a first result under 50,000 words of reading, no glossary, a navigation that lists sources (concepts, prompts) beside documentation and leaves two documentation pages off the site, and chapters of up to 1,121 lines whose sections run 300 lines without a subheading and whose sentences average 40 to 56 words. Four readers come to it and none is served: the newcomer who wants to know whether it is for them, the maker who wants to build a board, the engineer who wants to add a rule, the developer who wants to work on edakit. A fifth reader is served and must stay so: Claude in a session, for whom the handbook is reference material named from 415 places in the code, the skills and the agents.

Proposed: three layers over the one source that exists. An entry layer written anew and short – a start page of one screen, a quickstart to the first finding in fifteen minutes without EasyEDA, one page on how it works, a glossary –; the guides, which are the handbook's chapters, kept under their numbers and file names but grouped by reader and by station – the circuit, the board – in the navigation and trimmed in place – condensed to a third fewer words with no statement lost, subheadings, shorter sentences, the generated code lists replaced by a table and a link, the history and the private projects moved out, a status line where something is offline only – with the rule that a statement the automation points at is shortened at most, never moved or changed; and the reference, generated where the code knows it: the commands from the command line's own help, the catalog as one page per engine instead of 1.6 MB in one file. The sources – concepts, skills, agents, evals – stay readable on the site, but at its end under "Inside edakit", with an index that says what a concept is and in which state each one is, and their texts untouched. One style guide, docs/style.md, says how every layer is written and what it does not apply to, and a test holds what can be counted. The files, chapter numbers and section numbers stay: 415 places name them, the SessionStart hook reads section 11.4, and six tests hold the pages to the code.

Everything this concept adds is text in the repository; what it moves into text is what exists today only in the owner's head: who the readers are and how the documentation is written.

Who reads it

Reader Comes with Wants to know Finds today
The newcomer – has seen the name, has five minutes a browser what it is, whether it is for them, how much they must know, what it needs, what it costs, what has been built with it, how to try it a README of 2,300 words whose second sentence uses "sign-off" and whose third paragraph "hardware graph"; the requirements spread over the README, 2.2 and 16.2; the cost nowhere; the first run in chapter 17, 713 lines
The maker – wants a circuit, or a board Claude Code, an idea, little EDA routine; EasyEDA Pro or KiCad only for a board set up, describe a circuit, run the checks, read a finding, draw the schematic – a result on its own: a hand-wired build, a perfboard, a drawing for a document – and, from there or not at all, a board and an order; what Claude does, what they decide chapters 2 to 8, 11, 12 and 16 – 5,000 lines; the handbook's reading path "first time" is 1 → 2 → 17 → the bell → 3 → 6 → 7 → 8, about 50,000 words before the first graph of their own; that the circuit alone is a result is one sentence in chapter 1, 6.5 inside the EasyEDA chapter and 4.5 inside the parts chapter
The engineer – wants to add a rule electronics, maybe no Claude Code what a rule is made of, how a check, hint, block or part fact is added and tested, how it is proposed 14.2 to 14.4 inside the maker's chapter, the skill add-rule in .claude/skills/ (not on the site), the skill propose-rule, docs/organisation.md (not on the site)
The developer – works on edakit Python, git how the repository is organised, the rules of a session, the concepts and their state, the tests, the site docs/organisation.md, CLAUDE.md (neither on the site), 22 concept pages in path order, the READMEs under tests/
Claude in a session the plugin the chapter a skill names, section 11.4, the catalog served: 415 references "handbook N.N" and chapter paths, edakit explain – the constraint on every change below

What the site is today

Measured on main at 8fba5f2, the site built locally (python3 docs/pages.py, mkdocs build --strict):

  • Volume. 63 pages, 13 MB. The Markdown behind them: 220,000 words – the handbook 107,000 in 7,560 lines, the concepts 111,000, the README 2,300. The catalog page is one HTML file of 1.6 MB.
  • Chapters. Eight of the seventeen are longer than 400 lines; chapter 8 has 1,121 lines in seven sections, the longest 326 lines; chapters 3, 4, 5 and 7 have sections of 231 to 289 lines. Subheadings (###) exist in chapter 10 only. On the site a chapter's table of contents is its seven section titles for 118 KB of text.
  • Sentences. Prose outside tables and code: chapter 3 averages 56 words per sentence, 5 and 8 42, 4 36, 7 31, the README 31; chapters 1, 2, 6, 9 and 13 are between 16 and 26. The long ones are nested: an aside in an aside, three cross-references in one sentence, a list of five in the middle.
  • Cross-references. By number alone – "(8.2)", "(10.4)", "see 7.4" –: 116 in chapter 3, 118 in 4, 150 in 5, 137 in 7, 227 in 8, 188 in 10. A reader who does not know the numbering reads "(8.2)" as noise.
  • Generated lists. The catalog's code texts are rendered into the chapters – 175 lines in chapter 3, 108 and 21 in 8, 96 in 14, 37 in 4, 21 in 5 – and again on the catalog page: 458 lines of the same text in the chapter's flow, where a reader of the chapter wanted the next paragraph.
  • The navigation. Six entries by source folder: Handbook, Rule catalog, Concepts, Skills, Agents, Evals. Concepts lists 22 pages in the order of their paths – discarded/ first, done/ and new/ mixed, two prototype READMEs among them – with titles of up to seventeen words ("To be checked, clarified, fixed – what the walkthrough left open"). A reader cannot tell a plan from a decided concept from a discarded one without opening it.
  • Documentation and sources side by side. docs/organisation.md says what is documentation and what a source; the site shows the sources and leaves two documentation pages off – docs/organisation.md itself and the brand page are not in docs/pages.py. An implementation plan's status paragraph ("phase 1 (1.1 to 1.8), 3.1 to 3.5, 3.7 and the follow-ups below are done; 2.1 to 2.4 …") is the second page of the Concepts group.
  • Written from inside. "The reference project" – a private project – is named 30 times in the README and the handbook and described nowhere; "the bell" 21 times; "the owner" 32 times, "the user" 62 times – the skills' word for the person the reader is. Dates of October 2026 appear 47 times in the handbook, 17 in chapter 8 alone; chapter 9 opens with "Everything here was found the hard way … between 19 and 26 October 2026". The history and the reference are one text.
  • The circuit alone is a footnote. A project without a PCB needs no EasyEDA and no KiCad: checks, simulation, the schematic drawn as SVG (edakit schematic draw), hand-wired boards (wired = true) that the gate carries through stages P, G and E and leaves out of S, L and F. That is a product of its own – for a hand-wired build, a perfboard, a drawing for a document, or before anyone decides on a PCB – and the site says so in one sentence of chapter 1, in section 6.5 of the EasyEDA chapter and in 4.5 of the parts chapter.
  • The case is not made. The README says what edakit does; nowhere does the site say what the reader must bring and what they need not know, and the walkthrough has the numbers: of its 14 steps the person acts in six – answers the interview, says what the board must do, decides on what the checks found, creates the EasyEDA project, orders and pays, holds the boards –; of its seven decisions two are taste (D-5 who uses it, D-6 round), two money and purpose (D-1, D-4 the holder soldered by hand), three trade-offs presented with numbers (D-2 the red LED, D-3 no reverse protection, D-7 the cell's current). The forward voltages, a coin cell's pulse rating, what a reversed cell reaches, the footprints, the Gerber files and the order form came from edakit and Claude.
  • No project to look at. The README names the bell with its numbers and the example with its files; the reference project is private and nameless; nowhere is a built board to be seen – a photo, the drawn schematic, the board as made – with what it is, how it is built and what it taught edakit.
  • No glossary. Sign-off (143 mentions), M-1 to M-6 (201), stage, hand-over, claim, domain, engine, code, hint, block, gate run, release: each is explained where it is introduced, and a reader who arrives at chapter 8 by search has not been there.
  • The README. 239 lines: a 50-line block of commands (the same as 10.5 and edakit --help), one paragraph of 17 lines on skills and agents, a repository map of 15 rows for the developer, and "Status and limits" – the one section a newcomer needs – at the end.
  • Spelling. British as the rule – colour 45, behaviour 28, centre 16, licence 8 – with exceptions (color 6, behavior 14, license 5). "Catalogue" is JLCPCB's, "catalog" edakit's own: a distinction, not an inconsistency.
  • A day later. At 08a6951 the handbook has 121,700 words (107,000 at 8fba5f2), chapter 8 1,209 lines, the README 312 lines and 3,100 words; 450 places name the handbook (415), eight tests hold pages to the code since D.1; chapter 3 still averages 56 words per sentence. The documentation grows faster than anyone trims it – the reason D.5 counts words.
  • What works. The sentences are true to the code: the review of 2026-10-31 checked them (1cf3237). The tone is even – no superlatives, no marketing. Chapter 17 is the one chapter written for a reader who starts at zero, and it is the best page of the site; chapter 12 is a table a reader in trouble can use; handbook/README.md says for each chapter when to read it. The site has search, dark mode, a mobile layout and the brand. The problem is the text and its order, not the generator.

What the automation reads – and the rule for it

Claude reads the handbook. 274 places in edakit/ – finding and fix texts, docstrings, the help of the command line –, 120 in skills/, 12 in agents/ and 9 in .claude/ say "handbook 8.6" or name a chapter file; 51 distinct sections are named, every one exists today; a skill opens a chapter by path (${CLAUDE_PLUGIN_ROOT}/handbook/11-working-with-claude.md, 31 such paths, 10-reference.md and 02-setup.md most); edakit/agreements.py parses the numbered items of section 11.4 with their bold titles at every session start, so that the digest cannot drift from the chapter. The tests read it too: test_plugin.py wants every skill and agent named in the README and in table 11.1, test_catalog.py holds the generated sections to the catalog, test_walkthrough.py holds chapter 17 to the example, test_agreements.py holds 11.4, test_pages.py the site, test_catalog_page.py the catalog page. No test holds the 415 references themselves.

The other way round, the documentation quotes data: the catalog's rule, why and fix texts in the generated sections, the domains' texts, the help lines of the command line, the skills' descriptions on their pages. They read like documentation and are not – docs/organisation.md says so for the catalog, and the owner's condition extends it to every source: a change there is a change of what the automation does.

The rules this concept holds to, for every step below:

  • Sources, data and code are not touched. Skills, agents, CLAUDE.md, the catalog and the domains, the help texts in edakit/cli.py, the docstrings, the manifests, the concepts: not a word, not for style. Where the documentation needs a different word than a source uses, the documentation takes the source's word; where a source's text should change, that is a finding for the owner, as docs/organisation.md has it for the review – the stale "From a JSON hardware graph" in .claude-plugin/plugin.json is the first.
  • Unsure – ask, or check. Before a sentence of the documentation changes: is it generated – between <!-- edakit:generated --> markers, in a quote block of edakit docs, a skill's description rendered on its page –, then it changes in its source or not at all; is it used elsewhere – the phrase searched over edakit/, skills/, agents/, tests/ and the other chapters –, then it stays as it is: a text found elsewhere is a hint that it is better left unchanged; still unsure, the owner is asked, in the decision round of the branch. Nothing is changed on a guess.
  • Where the automation reads documentation, the statements stay. The chapter files the skills open, the sections the findings and the skills name (8.6, 4.1, 8.4, 3.1, 4.5, 5.1, 5.3 first), section 11.4 as the hook reads it, the README and table 11.1 as test_plugin.py reads them: a sentence there may be shortened, a long section may get subheadings, but no statement leaves the section that names it, none changes its meaning, and the numbered items of 11.4 with their bold titles stay as they are – they are the agreements, and a change of an agreement is the owner's.
  • Addresses stay. Chapter files, chapter numbers and section numbers do not change. A new ### adds an anchor and removes none. The navigation may call chapter 3 "Hardware graph"; the file keeps "3 The hardware graph".
  • The generated sections change only through their generator. The short kind (a table of code, title, severity with the link to the catalog page) is one more kind of edakit/catalog/handbook.py, test first; the texts it leaves out are still what edakit explain and the catalog page give, from the same data.
  • A test holds the addresses, new: tests/test_references.py – every "handbook N.N" and every chapter path named in edakit/, skills/, agents/ and .claude/ exists, and every path a skill opens exists. Red before a section disappears, not after a session finds the gap.
  • The review after each chapter reads for meaning. Old and new text side by side; every statement that is gone, moved or reworded is listed with the places in code, skills and agents that name its section, and the skills that open the file are read once against the new text. The list goes to the owner with the branch.

The proposal

Three layers, one source

Layer For Pages Written
Entry the newcomer, then everyone once the start page, the quickstart, how it works, the glossary anew, short, in the entry register of the style guide
Guides the maker – the circuit, then the board –, the engineer, the developer the handbook's chapters, grouped by reader and by station; two reader pages added in place: trimmed, not rewritten
Reference everyone who looks something up the project files and keys, the commands, the EasyEDA API, the catalog, the check IDs of before generated where the code knows it, in entries, not tables of paragraphs

The sources stay on the site, at its end, as "Inside edakit", untouched.

The entry layer

  • Start (README.md, the site's index): one screen. One sentence what edakit is; then the case, in three sentences a reader can check: you bring the idea, what the board must do, and the decisions on money, purpose and looks; edakit and Claude bring the rest – parts with their datasheets, the values, the rules, the simulation, the EDA tool, the maker's constraints, the manufacturing files, and the order at any of four makers up to the cart – the same release quoted at JLCPCB, PCBWay, Eurocircuits and AISLER, each with its price, whether its parts are in stock there and how long delivery takes, read off the maker's own form and checked by edakit –; you order, pay and hold the boards. The walkthrough is the evidence, linked: 14 steps, six of them yours, seven decisions. Its limit in the same breath: a check for every known error class and reviews by agents, not a guarantee (chapter 1); the regulatory review support, not legal advice. The word "harness" once, as a keyword, linked to the developer page (decision 14). Then the expectation set right, in one sentence that calls it the vision – "at least that is the vision, and we are close", the owner's words – and links the state – what is built offline only or has not run live yet, with its date – and the future work, both on How it works (today the README's "Status and limits" and "Future work"), so that the reader sees how close and where it goes. Three lines for whom – the maker (a circuit, or a board from it), the engineer, the developer – each with its link; what it needs (Claude Code; EasyEDA Pro desktop or KiCad 10; uv, ngspice; tested on Linux, Windows and macOS untested; a JLCPCB account for stock and ordering); what it is not (no editor of its own, two copper layers, DC operating points and a few transient runs); install in three lines; "try it in two minutes" – uvx --from git+https://github.com/tgd1975/edakit edakit check in examples/coin-cell-led, which takes 0.2 s and shows an accepted finding with its reason –; then the quickstart, the guides, the reference. The command block moves to the reference, the repository map to docs/organisation.md, "Status and limits" to "How it works". The test that wants every skill and agent in the README (test_plugin.py) is pointed at the page that lists them – the test changes with the page, on the same branch. Two parts stay on the start page, below its first screen: "What it runs, sends, fetches", which Anthropic's plugin directory asks a README to state (outreach.md, K.2), and the line on how issues are answered (K.3); the paragraph on versions joins the install lines, with the link to the changelog.
  • Quickstart (docs/quickstart.md): the first project to the first finding and the first drawn schematic, in about fifteen minutes, without EasyEDA – install the plugin, a project from the example or from /edakit:new-project, a graph of four parts, edakit check, one finding read with edakit explain, edakit sim, edakit schematic draw, and where the EasyEDA or KiCad part begins (chapter 17 takes it from there). The quickstart is the circuit station and says so at its end: this is a result on its own; for a board, go on to "The board" – and it names what the reader did not need on the way: no datasheet read, no value computed, every finding came with its reason. Every output from a real run, held by a test like chapter 17's (tests/test_walkthrough.py).
  • How it works (docs/how-it-works.md, two screens): the pipeline as a drawing in the brand's colours instead of the ASCII line, with the cut between the two stations – the circuit: graph, checks, simulation, drawing, hand-over; the board: schematic, PCB, files, order – and the loops back: the check loop, the review loop, the PCB round, the gate going back to the stage that failed, and the exit to the person where a decision is due; the ten words – graph, parts entry, stage, code, finding, sign-off, gate run, release, domain, block, hand-over –, one paragraph each; the mechanism in plain words – Claude proposes, checks that are not Claude check, reviewers in sessions of their own judge, the person decides –, with no buzzword for it (decision 14); what Claude does and what the person decides – the table of 17.1's "Who" column, step by step, with the count that backs the start page's case, and chapter 1's "what it does not give you" –, the decision round shown once as a shortened transcript; what is text and what still exists only in EasyEDA – the README's "Status and limits", kept current as it is today. After it, "Future work": the disruptive changes only, today three – ordering through the makers' interfaces instead of their pages in the browser, the same steps up to the cart and the same checks, ordering and paying still the reader's (handbook 8.4); the circuit in a language of edakit's own instead of the TOML graph (circuit-dsl.md); and Claude independence, edakit in other assistants and with self-hosted models (claude-independence.md) –, each with what it changes for a project and the link to where it is worked out. Smaller extensions and fixes are not future work and are not listed; TODO.md holds them.
  • Projects (docs/projects/): the projects built with edakit, each on a page of its own – there are two today, and each is worth a page. The index (docs/projects/README.md) shows a card per project: its board as made, one line, the link; the two examples (examples/coin-cell-led, examples/blinker-555) are cards whose page is their walkthrough, chapters 17 and 18. A project page explains the project to a reader who has never seen it, with the pictures edakit makes:
  • What it is – what the device does and for whom, its boards, the maker, where it stands: released, ordered, delivered, with the date and the release.
  • The circuit – the drawn schematic, and its blocks explained in plain words: what each does and why it is built that way, from the graph's labels and the decision log.
  • The board – top, bottom and the layers as made; size, layers, parts, nets, vias; what the maker assembles and what is soldered by hand; how it was placed and routed.
  • What edakit found – the findings that changed the design, each with its code and the link to the catalog, and the decisions they led to: the case of the start page, shown on a real project.
  • Variants, where a project has them – the boards side by side and a table of what differs. The bell is one circuit as main, smd, tht and esp32 (its D-11 to D-15): the same function with hand-soldered parts, with parts the maker assembles, with another module – each a variant in edakit's sense, a project of its own below the main one, released and published together.
  • What it changed in edakit – the gaps it closed (chapter 13).

The pictures are the release's: the gate draws the circuit and the board into section 12 of the protocol (pictures/, SVG and PNG), and edakit release publish puts them into the project's GitHub release (8.3). They are copied from there into docs/projects/<name>/ with the release's tag, never drawn by hand, and renewed with the next release; a photo of the delivered board where there is one. The numbers name their release. pytree, the reference project of chapter 13: the repository stays private, its page holds the information and the pictures the owner picks from its release, and it is the one description of the reference project – chapter 13 refers to it by name. A project gets its page once it has a result with edakit – a released board, or at the circuit station a checked and drawn circuit. A page also comes from a "built with edakit" issue (outreach.md, K.3): Claude writes it from the project's release, in this form, and its state names the edakit version that released the board, as the release notes do ("Released with edakit X.Y.Z", K.9). The gallery shows what is built and nothing that is planned: which project converts next is the owner's and TODO.md's, not the gallery's. A project page is written in the entry register, its length set by its pictures – a kind of page of its own in the style guide (D.9). - Glossary (docs/glossary.md): every term in one or two sentences, with the chapter that treats it, in the words the skills and the catalog use – the two stations and the hand-wired board among them. The first use on an entry page links to it.

The guides, by reader

The navigation, two levels, groups named after what the reader does:

Group Pages (the files as they are)
The circuit The approach (1), Setup (2), Working with Claude (11), Designing a circuit (14), Hardware graph (3), Parts (4), Simulation (5), Regulatory review (15) – the station ends with the drawn schematic (6.5, linked from the group's index) and the hand-over (edakit handover, 14.1): a result on its own, or the board's input
The board Schematic (6), PCB (7), Release gate (8), KiCad (16), Walkthrough (17), Walkthrough on KiCad (18), Troubleshooting (12), Lessons learned (13)
Extend the rules Adding a rule (new: from 14.4, the skill add-rule and docs/organisation.md – the catalog's files, a code's fields, the negative test, the generated sections, the run against the reference circuits, the proposal from a project), Propose a rule, Propose a feature (the skills' pages)
Develop edakit Working on edakit (new: docs/organisation.md on the site, extended by the concepts' lifecycle, the tests, the evals, how the site is built; CLAUDE.md beside it as a source page), edakit as a meta-harness (new: docs/architecture.md), Brand
Reference Project files and keys (10.1–10.4, 10.6), Commands (10.5), EasyEDA API (9), Rule catalog (one page per engine, the domains, the tables, the reference circuits, the open designs), Check IDs of before (10.7), Changelog (CHANGELOG.md)
Inside edakit Concepts – an index, then new, done, discarded, each with one line of state –, Skills, Agents, Evals

Chapters 9 and 10 move to the reference, chapter 14 to the circuit – 14.1 roles, 14.3 hints and 14.5 building blocks are the circuit designer's; 14.2 and 14.4 feed "Adding a rule" – without changing their files: the navigation lists a file where the reader looks, the file stays where the code looks. Section 6.5, the drawing without EasyEDA, stays in chapter 6 (the rules above) and is linked from the circuit's index; handbook/README.md becomes that index, with the two stations and its "read it when" column.

edakit as a meta-harness (docs/architecture.md, for developers, decision 14). The one page that uses the word, and it defines it by three properties, each checkable in the repository: edakit is built on an agent harness – Claude Code first – and specializes it; projects extend it with scripts and agents of their own ([scripts.*], [agents.*] in edakit.toml) that the gate runs and whose sign-offs it requires; and it changes through its own use – a finding becomes a proposal, the Action builds it with Claude, the owner merges. Then: the three layers – Claude Code (the loop, tools, permissions, sub-agents, hooks), the plugin (skills, agents, hooks, the working agreements, the EasyEDA MCP server), the checking core (the command line, the catalog, the engines, the simulation, the gate), which works without Claude Code –; the five loops with the files that set them – the check loop (skills/circuit-design/SKILL.md, "Check loop"), the review loop (working agreement 4 in 11.4), the PCB round (skills/pcb-round/SKILL.md), the gate (skills/release/SKILL.md, chapter 8), the loop across projects (skills/propose-rule, the triage skills, the Action proposals) –, each with its signal, its stop condition and its step back; what is bound to Claude Code (the formats of skills, hooks and agents, AskUserQuestion, Claude in Chrome) and what carries over (the command line and its checks, MCP, the skills as text); and the rules for developers that follow: a capability without a check is a prompt – every new step brings its check, seen red once; knowledge goes into data – catalog, domains, blocks, parts –, not into a skill's text; skills name handbook sections, which tests/test_references.py holds; the person gets decisions, not checklists.

What changes inside a chapter (step D.5), one chapter per branch, the documentation review after each, under the rules above – every sentence checked first for being generated or used elsewhere, and the owner asked where that leaves a doubt:

  • The first paragraph says who the page is for and what they can do after it.
  • Condensed: the same statements in a third fewer words – every statement once, at the place that owns it, the rest a link; one example instead of three; no sentence that announces the next; no restatement of what a code block shows; no chapter over 500 lines, no paragraph over 120 words. A qualification – a number, a condition, an exception – is a statement and stays; in a section the automation names, the wording gets shorter and nothing leaves. Where a chapter does not give the third without a statement going, the review says why, and the statements win.
  • A subheading at least every 80 lines; the long sections of 3, 4, 5, 7 and 8 get ### by topic, their statements where they were.
  • Sentences: one aside, one cross-reference, one list per sentence; a cross-reference names its subject – "the sign-off file (8.2)", not "(8.2)".
  • The generated code lists become the short kind – code, title, severity, the link to the catalog page, which holds the full texts.
  • The history leaves: dates, "found the hard way", what went wrong in which week go to chapter 13, which becomes the history of edakit – the reference project described there once, as a project of about 120 parts built in October 2026, and named nowhere else; the example and the open designs are the examples the guides use. The bell stays where it is cited, as the public example it is. A date a finding or a skill relies on (the law's state in chapter 15, the versions in chapter 2) is no history and stays.
  • A status admonition at the top where something is built offline only or planned, one line, instead of the state woven into the prose.
  • Tables whose cells are paragraphs become prose with a short table, or entries (definition lists).
  • "The user" becomes "you", "the owner" leaves the reader pages – in the documentation's own sentences; a quoted skill, agreement or catalog text keeps its words.

The reference, generated

  • Commands. 10.5 is a table of 60 rows and four columns whose cells are paragraphs; on a phone it does not fit. It becomes one entry per command: the synopsis and the help line generated from the command line's own parser (edakit/cli.py, 31 subcommands with help texts) between generated markers and held by a test as the catalog's lists are, and under each the hand-written lines reads, writes, exit codes, EasyEDA – what the table holds today, as lines. The help texts are code: a help line that reads badly in the reference is changed in cli.py through a branch of its own, not by the documentation.
  • The catalog page. docs/catalog/build.py writes one page per engine, one for the domains, the tables, the parts schema, the reference circuits and the open designs, and an index with the counters; the navigation lists them. test_catalog_page.py follows. The texts are the catalog's, as today.
  • The project files. 10.1 to 10.4 stay hand-written – they are the reference that explains –, their tables kept to short cells, the explanation below the table.

Sources on the site

Concepts, skills, agents and evals stay on the site – a reader of the developer page needs them, and a link into a concept must land somewhere readable – but as the last group, "Inside edakit", with an index page that says what a concept is, how it moves from new/ to done/ or discarded/, and lists each with the first sentence of its status line. Prototype READMEs leave the navigation (their links still work). CLAUDE.md joins as a page rendered like a skill. Every page of this group carries a one-line admonition at the top, added by docs/pages.py and not by an edit of the source: this is a source – a concept, a prompt, the rules of a session –, read it as such. Nothing in the sources changes for the site.

The site itself

  • The navigation as data in docs/pages.py – a table of file, group and short title – instead of the folder walk; test_pages.py holds it. Titles in the navigation have at most five words; the H1 of the file keeps its number.
  • docs/organisation.md and docs/brand/README.md on the site – they are documentation.
  • A line in the footer: built from edakit X.Y.Z – the version edakit --version names and the changelog describes (versioning.md).
  • Material's features as they are: search, dark mode, the brand. Definition lists and admonitions are enabled and unused today; the reference, the status lines and the source line use them.
  • A line at the foot of every page: something unclear or wrong – open an issue, with the forms for a bug or a question (outreach.md, K.3). An ordinary issue; the Action proposals reads the owner's sealed proposals only and stays as it is.

How it is written: the style guide

docs/style.md, a documentation page, pointed at by docs/organisation.md where the review's style sits today. It holds for the documentation – README.md, handbook/, docs/ outside concepts/, the example's Markdown – and for nothing else: the catalog's texts are data, the skills and agents are prompts, CLAUDE.md is the sessions' rules, the help texts are code; each keeps its own words, and the documentation follows them.

Registers. Three, by layer:

Entry Guides Reference
sentence at most 20 words on average, none over 35 at most 25 on average fragments allowed in entries and cells
paragraph at most four sentences one idea, at most 120 words; a subheading every 80 lines at most an entry per thing
length a page of at most two screens; the quickstart longer a chapter of at most 500 lines; the same statements in a third fewer words than today as long as the things it lists
asides none – a second sentence instead one per sentence, the en dash as written –
cross-references to the glossary and to one guide page, by name the subject and the number: "the board file (10.2)" by number and name
terms introduced one per sentence, linked to the glossary at first use used as the glossary has them as the glossary has them
history none none – chapter 13 none
state a status admonition, one line the same the same

Words. "You" for the reader, "the assistant" for the session – Claude, Copilot or another harness, named where it is meant (decision 8 of claude-independence.md) –, "edakit" for the tool; "the plugin", "the command line", "the handbook", "the catalog", "the site" for its parts. "The owner" on the developer page only – edakit's owner, who decides –, "the user" nowhere in a reader page's own sentences. One word per thing, listed in the glossary and taken from the skills and the catalog: hand-over, sign-off, tool chain, parts entry, board file, gate run, placement plan. British spelling as written; "catalog" is edakit's own name, "catalogue" JLCPCB's. No superlatives, no "simply", no "just", no "the hard way". No buzzwords – "harness", "agentic", "AI-powered", "copilot" and their kind –: a reader page says what happens, not what it is called; the README names "harness" once at its start, as a keyword with the link to docs/architecture.md, which uses it, defined; no other reader page does. Numbers with their unit and a space (0.2 mm, 5 V). Prose wrapped at 120 characters, as written.

Dense. Every statement once, at the place that owns it; everywhere else a link, not a paraphrase – the command list of the README, 10.5 and edakit --help are one list in one place. One example where one shows it. No sentence that announces another, no restatement of a code block or a table in prose, no history in a guide. Short sentences and dense text are not opposites: the words that go are the asides, the repetitions and the enumerations, not the statements – a qualification is a statement and stays, and a shorter wording never trades a meaning (the rules of "What the automation reads").

A page. Its first paragraph says for whom and what they can do after it; the shortest path comes first, the details after, the reasons at the end; a status admonition at the top where something is offline only or planned; headings of at most five words in the navigation. Regulatory content says once that it is support, not legal advice (CLAUDE.md). The case for edakit is made once, on the start page, as a statement a reader can check against the walkthrough – the count of steps and decisions –, never by an adjective; the sentence after it calls it the vision and links the state – the one wink the site allows itself, and no false expectation: what has not run live says so, dated. Future work lists the disruptive changes only – what changes how a project works –; a smaller extension or a fix is TODO.md's and never on the site.

Pictures. One per guide page where a picture is faster than a paragraph – the pipeline, a drawn schematic, a placement plan, a gate protocol –, SVG in the brand's colours; where edakit draws it (schematic draw, pcb plan) generated and held by a test, as chapter 17's drawings are.

Code and output. A command and its output from a real run, shortened with …; held by a test where a test can (test_walkthrough.py is the pattern).

Held by a test. What can be counted is counted, in edakit's own spirit: tests/test_style.py measures the entry pages' sentence length, finds a section over 80 lines without a subheading, a chapter over 500 lines, a paragraph over 120 words, a bare "(N.N)", "the reference project" or "the user" in a reader page's own sentences, a date outside chapter 13 and the status lines, a term in bold without a glossary entry, a listed buzzword outside docs/architecture.md and the README's one mention. It reads documentation only. The rest is the documentation review's (docs/organisation.md).

What is missing, so that others use it

  1. The entry – the start page, the quickstart, how it works, the glossary (above). Today the shortest way to a first result is chapter 17.
  2. "Is it for me" – said once, plainly, on the start page: what it needs, what it costs (a gate run, a decision round, a circuit design in tokens – the evals' runs give numbers; and the board itself, quoted at the four makers side by side), what it is not, the licences of what it combines (the README has them, at the end) – and the case: what you bring, what edakit and Claude bring, with the walkthrough's count; the one argument the site does not make today, and the owner's: "one needs relatively little knowledge to design a correct circuit and order the board, up to assembly".
  3. A session shown. Nothing on the site shows what working with it looks like: what Claude asks in a decision round, what the person answers, what is written where. One shortened transcript on "How it works", from a real session, held by the review to the skill it shows.
  4. Try it without committing – uvx … edakit check on the example: two minutes, no plugin, no EasyEDA. It works today and is one line in the README; it becomes the first thing the start page offers.
  5. Feedback – the line at the foot of every page.
  6. What changed – since versioning.md every change is a version with its section in CHANGELOG.md, written for a maker who updates; the site shows it under Reference (decision 8, superseded).
  7. The marketplace text – done: outreach.md (decision 5, K.2) gave plugin.json and marketplace.json the wording "circuit design as code", for EasyEDA Pro or KiCad (edakit 0.4.8).
  8. Boards to look at – the gallery (decision 12): a reader judges a tool by what has been built with it, and two real projects with their pictures say more than a list of features.
  9. Where it goes – future work (decision 13): the three changes that will alter how a reader's project works, and no wish list.
  10. Contributing, said plainly on the developer page: issues and pull requests are welcome and the owner merges – the issue forms of outreach.md (K.3); rule and feature proposals come from projects through the plugin, only the owner's are triaged by the Action, and an issue by someone else becomes one when the owner adopts it with a sealed comment (proposals-pipeline.md).

Steps

Step What Size Waits for
D.1 docs/style.md and docs/glossary.md; docs/organisation.md points at the style guide; tests/test_style.py for the countable rules, red on today's pages where it must be; tests/test_references.py for the addresses M the decisions
D.2 The entry layer: the README as the start page, docs/quickstart.md with its test, docs/how-it-works.md with the pipeline drawing and its loops, the mechanism, the transcript, the state and the future work; the buzzword rule into docs/style.md and tests/test_style.py; test_plugin.py pointed at the page that lists skills and agents – with it edakit 1.0.0 (versioning.md, V.6) and the launch of outreach.md M D.1
D.3 The site: the navigation as data, by reader, short titles; organisation.md and the brand page on it; "Inside edakit" with its index and the source line; the footer line; the feedback line; prototypes off the navigation; test_pages.py follows S–M D.2
D.4 The reference: 10.5 as entries with the generated synopsis; the catalog page split by build.py; the chapters' generated lists as the short kind of catalog/handbook.py M D.1
D.5 The chapters in place, worst first – 8, 3, 5, 7, 4, 10, then 2, 6, 11, 14, 15, 16, 17, 1 –, condensed to a third fewer words with the statements listed before and checked after, one per branch, the review for meaning after each; chapter 13 takes the history L (M per large chapter) D.1
D.6 The reader pages: "Adding a rule", "Working on edakit" with CLAUDE.md beside it, "edakit as a meta-harness" (docs/architecture.md) M D.3
D.7 The "is it for me" numbers from the evals, for the start page and outreach.md's fact sheet (K.5); the plugin's descriptions were settled by outreach.md, K.2 S –
D.8 "What changed", if decided S D.3
D.9 docs/projects/: the index with its cards; the bell's page with its variants, from the pictures of its current release; pytree's page with what the owner picks; the style guide's project page and test_style.py following; a later project's page once it has a result with edakit; further pages from "built with edakit" issues (outreach.md, K.3) M, then S–M per project D.2; pytree the owner

D.1 to D.4, D.6, D.7 and D.9 are about six sessions; D.5 is one session per large chapter and the review after it. The first usable result is after D.3: a newcomer enters through the start page and the quickstart and reaches the guides through a navigation that tells them where they are, with the chapters still as they are. outreach.md waits for D.2, D.7 and D.9 for its launch, aimed at the first half of December, and versioning.md sets 1.0.0 with D.2 – so those three come first (decision 15).

Measures – done when

  • A reader who has not seen edakit reaches the first finding on the example in under fifteen minutes with the quickstart alone, and without EasyEDA – tried by one person, and by Claude in a fresh session with the site as its only input, as an eval case (evals/).
  • The entry pages: sentences at most 20 words on average; no page over two screens but the quickstart.
  • The guides: a third fewer words than today per chapter, no statement lost (the review's list), no chapter over 500 lines, no paragraph over 120 words; no section over 80 lines without a subheading; sentences at most 25 words on average; no bare "(N.N)"; no "the reference project" and no "the user" in a reader page's own sentences; no date outside chapter 13, the status lines and the dates the automation relies on.
  • The projects: every page with the schematic and the board as made from a named release, its blocks and its findings explained; nothing planned on the gallery.
  • Future work: the disruptive changes only, today three items; nothing smaller.
  • No buzzword on a reader page; "harness" once at the start of the README, as a keyword, and defined on docs/architecture.md.
  • The navigation: two levels, at most fourteen entries per group, titles of at most five words.
  • The reference: no cell over 25 words; the commands' synopses equal the command line (test); no catalog page over 300 KB.
  • Nothing the automation reads has changed its meaning: the 415 references resolve (test_references.py), the hook's digest of 11.4 is the same, the six tests are green, the review's list of moved or reworded statements per chapter is empty for the sections the automation names, and mkdocs build --strict passes as today.

Alternatives

  • A – a new structure, new files. Tutorials, how-to guides, reference, explanation (Diátaxis), each chapter cut into pages of one kind. Cleanest on paper. It costs every address – the 415 references, the hook's section, the tests, the paths the skills open –, the text that is true today is rewritten and can drift, and it is weeks. Not recommended; the reader's order is had for less by the navigation.
  • B – the entry layer only. One session; the newcomer gets in, and on the second page meets a section of 300 lines with sentences of 56 words. The maker is the reader with the most to read, and B leaves them the most.
  • C – this concept. The entry layer, the navigation by reader, the chapters trimmed in place under the rules for what the automation reads, the reference generated, a style guide with a test. Recommended.
  • Another generator. Sphinx, Docusaurus, mdBook: none of them fixes a sentence. MkDocs Material has what the proposal uses – search, dark mode, mobile, admonitions, definition lists, the brand – and stays.

Costs and risks

  • Work. About six sessions for D.1 to D.4, D.6 and D.7, one per large chapter for D.5 – ten –, each followed by the review. The owner's tokens.
  • A meaning shifts where the automation reads. The largest risk, and the owner's condition. Held by the rules above: addresses fixed, statements of named sections in place, 11.4 untouched, the review reading old and new side by side with the places that name the section, test_references.py red before a section goes. What the rules do not catch – a shortened sentence that a skill read differently – is found by the review's reading of the skills against the new text, or by the first session that runs the skill; the first sessions after a trimmed chapter are watched for it.
  • Condensing is where meaning drifts most. A cut qualification changes what a sentence says; a merged pair of sentences can lose the case one of them covered. Held by the rule that a qualification is a statement, by the review's list of statements per chapter – the list is written before the chapter is condensed and checked after –, and by the owner's rule: unsure, ask; generated or used elsewhere, leave it.
  • Drift from the code. A trimmed chapter can lose a true sentence. The review checks each chapter against the code after its branch (docs/organisation.md); the tests hold the quoted outputs; a correct sentence stays as it is, shortened only where it is nested.
  • Two registers on one site. The entry pages short, the guides dense: a reader notices the seam at the first guide page. The first paragraph of each guide page – for whom, what after – is the bridge, and D.5 narrows the gap.
  • The catalog's and the skills' words bind the glossary. A term the documentation would rather name differently stays as the sources have it; a better word is a finding for the owner and a change of the sources on their word.
  • Evidence leaves with the history. "From the first graph to a released set in five days" is an argument for edakit; it moves to chapter 13 with the project described once, and the start page may quote the number with the link.

Decisions

Taken by the owner on 2026-10-31, in a decision round in Claude Code's form; "accepted" is the owner's yes to the recommendation.

# Question Recommendation Alternatives Decision
1 The structure C: the entry layer, the navigation by reader, the chapters trimmed in place under the rules for what the automation reads, the reference generated; files and numbers stay A: a new structure with new files; B: the entry layer only accepted
2 The sources on the site kept, as the last group "Inside edakit" with an index and a source line added by the site, the texts untouched off the site, links to GitHub; as today accepted
3 The spelling British as written; "catalog" edakit's own name, "catalogue" JLCPCB's; the exceptions in documentation unified, sources as they are American accepted
4 The voice "you" for the reader, "Claude" for the session; "the user" and "the owner" leave the reader pages' own sentences, quoted sources keep their words as today accepted; amended on 2026-11-01 by decision 8 of claude-independence.md: "the assistant" for the role, the harness by name where it is meant
5 The history and the private projects dates and the story leave the guides for chapter 13; "the reference project" described once – since decision 12 on its project page as pytree, which chapter 13 refers to by name – and named nowhere else; the example and the open designs are the examples; dates the automation relies on stay stays inline, as today accepted
6 The README one screen: what, for whom, needs, not, install, try it, next; the command block to the reference, the repository map to organisation.md, "Status and limits" to "How it works"; test_plugin.py follows as today, with a shorter head accepted
7 The command reference entries: the synopsis generated from the parser and held by a test, reads, writes and exit codes hand-written beneath; the help texts changed only in cli.py through a branch the table as today; fully generated (loses reads and writes) accepted
8 "What changed" from the merge commits on the site not built until a reader asks: the commit messages are written for the owner built with D.3 accepted; superseded on 2026-11-01 by versioning.md – CHANGELOG.md, written for a maker who updates, on the site under Reference (decided by Claude, confirmed by the owner the same day)
9 The circuit alone as a station (the owner's addition: "we can also make only a circuit SVG – maybe that is the maker anyway") two groups, "The circuit" and "The board", instead of "Use it"; chapter 14 to the circuit; the quickstart is the station and says so; the pipeline drawing shows the cut one group with the station on its index page only; a sentence in the maker's row only accepted
10 Condensing as a rule (the owner's addition: "it would be advisable to condense the texts – a style question") the same statements in a third fewer words per chapter, no chapter over 500 lines, no paragraph over 120 words, no statement lost – the review's list proves it, and where a chapter does not give the third the statements win the rules without a number; a target per chapter set at its branch accepted
11 The case for edakit (the owner's addition: "a big argument for edakit is that one needs relatively little knowledge to design a correct circuit and order the PCB, up to assembly – a selling point too"; where, the owner left to Claude) on the start page, in its first lines, as a statement a reader can check – you bring the idea, what the board must do and the decisions on money, purpose and looks; edakit and Claude bring the rest – with the walkthrough's count (14 steps, six yours, seven decisions) and its limit in the same breath: not a guarantee, the regulatory review support, not legal advice; the evidence table on How it works; the quickstart ends with what the reader did not need a slogan on the start page; the case nowhere, the facts alone accepted, with the owner's addition: after the case one sentence that calls it the vision – "at least that is the vision, and we are close" – and links the state, so that no false expectation is raised; the order at four makers added to the case on the owner's word of 2026-11-01 ("a cool feature we cover")
12 A gallery of projects (the owner's addition: "a kind of gallery with project presentations – pytree, even though the repository is private: some information and pictures can go out; the bell; later the tiny jukebox, the pedal and the steering wheel, once converted") docs/projects/ in the entry layer: an index with a card per project and a page per project – what it is, the circuit with its drawn schematic and its blocks explained, the board as made, what edakit found, its variants, what it changed in edakit –, the pictures from the project's release; the bell and pytree, pytree with what the owner picks and its page the one description of the reference project; the examples as cards to their walkthroughs; a page once a project has a result with edakit the projects in chapter 13 only; links on the start page only; a picture and three lines per project (Claude's first proposal) accepted, with the owner's additions: schematic and board pictures and more explanation – "otherwise it would be very dry" –, a page per project since there are two, the bell's board variants shown ("not uninteresting"); which project converts next is "none of the gallery's business"; what Claude decided itself – docs/projects/README.md as the index, the examples as cards to chapters 17 and 18, the pictures from the release with its tag, a page once a project has a result with edakit, chapter 18 in "The board" – confirmed the same day
13 Future work (the owner's addition: "two points are central: the ordering automation – it runs over the web pages today, I want to do it through APIs – and the switch to the DSL; these are disruptive, everything else is smaller extensions and fixes for now, not to be mentioned in future work") two items, nothing else: ordering through the makers' interfaces instead of their pages in the browser – the same steps up to the cart and the same checks, ordering and paying still the reader's, as handbook 8.4 has it –, and the circuit in a language of edakit's own instead of the TOML graph (circuit-dsl.md); on How it works after the state, linked from the start page's vision line, in the README's "Future work" until D.2; the style guide's rule that future work lists disruptive changes only a page of its own ("Roadmap"); every open item of TODO.md on the site the owner's word on the content; the place placed by Claude and confirmed by the owner the same day; the README's "Future work" on the owner's OK of the same day; a third added by the owner on 2026-11-01 – Claude independence (claude-independence.md), in the README's "Future work" the same day
14 The architecture and its word (the owner's addition: "harness is the buzzword of the day – marketing; describe it more strongly, and for the developer a section of its own on why it is a meta-harness, or something like it") reader pages without the buzzword: the mechanism described – Claude proposes, checks that are not Claude check, reviewers in sessions of their own judge, the person decides – and the loops drawn on How it works; "edakit as a meta-harness" on a page of its own for developers, docs/architecture.md in "Develop edakit", the term defined by three properties – built on Claude Code's harness, extended by projects with scripts and agents the gate runs, changed by its own use through proposals the owner merges –, with the layers, the loops and the files that set them, what is bound to Claude Code and what carries over, and the rules for developers; the style guide's buzzword rule and its count "A layer on Claude Code" or "A harness on a harness" as the title; a section of "Working on edakit" accepted – title and place the owner's choice among the alternatives, what Claude decided itself confirmed the same day; amended by the owner the same day: "it does belong at the start and in the README as a keyword" – named once at the start of the README, linked to docs/architecture.md; its first property reads "built on an agent harness, Claude Code first" since decision 8 of claude-independence.md
15 The order of the steps – TODO.md held D.2 to D.7 back until the other todos are done, outreach.md waits for D.2, D.7 and D.9 for its launch in the first half of December, and versioning.md sets 1.0.0 with D.2 D.2, D.7 and D.9 ahead of the other todos; D.3 to D.6 wait as before the order as it was; D.2 alone ahead accepted

Decided by Claude at the re-check of 2026-11-01 and confirmed by the owner the same day: the changelog on the site (decision 8); "What it runs, sends, fetches" and the line on how issues are answered kept on the start page, below its first screen; the order at four makers in the case and in "Is it for me"; gallery pages also from "built with edakit" issues, naming the edakit version that released the board.

Decided by Claude and confirmed by the owner on 2026-10-31: MkDocs Material stays; chapter files and numbers stay; sources, data and code untouched, with the rules of the section "What the automation reads"; tests/test_references.py; a glossary in the sources' words; the style guide with its test; the navigation two levels deep; prototype READMEs off the navigation; CLAUDE.md on the site as a source page; organisation.md and the brand page on the site; the quickstart offline and held by a test; the first reader as an eval case; the pipeline drawing in the brand's colours; the paths docs/style.md, docs/glossary.md, docs/quickstart.md, docs/how-it-works.md.

Sources