add pcb docs for readmes (#569)

dioderobot · hexdae · web-flow · commit 0bfe0fd59ed4 · 2026-02-26T12:38:30.000-05:00
* add docs pages

* add ch

* use links instead of docs

* explain how to access the docs

* less verbose docs

* refresh

* refresh

---------

Co-authored-by: d-asnaghi &lt;30296575+hexdae@users.noreply.github.com&gt;
diff --git a/.agents/skills/pcb/SKILL.md b/.agents/skills/pcb/SKILL.md
@@ -106,6 +106,8 @@ pcb doc spec               # Full language specification
 pcb doc spec --list        # List all spec sections
 pcb doc spec/<section>     # Read specific section (e.g., spec/io, spec/module)
 pcb doc packages           # Dependency management docs
+pcb doc docs_bringup       # Guide on writing bringup docs in markdown 
+pcb doc docs_changelog     # Guide on writing a changelog after every change
 ```
 
 Package docs (stdlib, registry packages):
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,7 @@ and this project adheres to Semantic Versioning (https://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Added `pcb doc` guides for bringup, changelog, and readme conventions.
 - Added MCP tool `resolve_datasheet` to produce cached `datasheet.md` + `images/` from `datasheet_url`, `pdf_path`, or `kicad_sym_path`.
 - Added LSP request `pcb/resolveDatasheet`, sharing the same resolve flow as the MCP tool.
 
diff --git a/docs/docs.json b/docs/docs.json
@@ -40,6 +40,10 @@
       {
         "group": "Documentation",
         "pages": ["pages/spec", "pages/packages", "pages/testing"]
+      },
+      {
+        "group": "Guides",
+        "pages": ["pages/docs_bringup", "pages/docs_changelog", "pages/docs_readme"]
       }
     ]
   },
diff --git a/docs/pages/docs_bringup.mdx b/docs/pages/docs_bringup.mdx
@@ -0,0 +1,140 @@
+---
+title: Bringup
+description: Conventions for writing board bringup and rework documentation that renders in the Diode Glass bringup tab.
+---
+
+# Bringup Documentation
+
+Write a `README.md` per board version documenting reworks, firmware flashing, and test procedures. Diode Glass parses these and renders them in the **bringup** tab.
+
+## File Location
+
+```
+src/boards/<BOARD_NAME>/
+  bringup/
+    v1.0/
+      README.md
+      images/
+        estop-rework.png
+    v2.0/
+      README.md
+```
+
+One `README.md` per version folder. Images go in `images/` alongside the README.
+
+### Version Matching
+
+- **Exact**: release `v2.0` → folder `v2.0/`
+- **Prefix**: release `v2.0.4` → folder `v2.0/` (covers all v2.0.x)
+- **No cross-minor**: release `v2.1.0` does NOT match `v2.0/`
+
+New folder per minor version. Patch versions share a folder unless they have unique rework. Docs are fetched from `main`, not the release artifact.
+
+## Document Structure
+
+```markdown
+# <Board> <Version> Bringup
+
+Overview text.
+
+## Reworks
+
+### 1. Title of first rework
+
+...
+
+### 2. Title of second rework
+
+...
+
+## Firmware
+
+Free-form markdown.
+
+## Testing
+
+Free-form markdown.
+```
+
+`## Reworks` is parsed into structured data. All other `##` sections render as collapsible markdown.
+
+## Rework Items
+
+Each rework is a `### N. Title` heading followed by free-form prose. Describe the problem, fix, and board location naturally. Mention status in the text or heading (e.g., "fixed in v1.1") rather than a structured field.
+
+### Linking to Components
+
+Use markdown links with the `pcb://` scheme: `[R1](pcb://R1)`, `[C5](pcb://C5)`, `[U3](pcb://U3)`. The parser links these to the PCB viewer for click-to-highlight.
+
+### Images
+
+Place in `./images/`, reference with `![description](./images/photo.png)`.
+
+## Complete Example
+
+```markdown
+# DM0001 v1.0 Bringup
+
+Board version v1.0 requires 3 reworks before bringup.
+Items 1–2 are fixed in v1.1. Item 3 requires a physical fix on each board.
+
+## Reworks
+
+### 1. Short ESTOP debounce resistor (fixed in v1.1)
+
+The 47k ESTOP debounce resistor [R_ESTOP_DEBOUNCE](pcb://R_ESTOP_DEBOUNCE) creates a voltage
+divider with the ESTOP LED, pulling the signal to ~1.5V (below the AND gate
+VIH threshold of 2.0V). Short across [R_ESTOP_DEBOUNCE](pcb://R_ESTOP_DEBOUNCE) (47k 0402) with
+a solder blob or wire. Located near the ESTOP connector between ESTOP_RAW
+and ESTOP nets.
+
+![ESTOP Rework](./images/estop-rework.png)
+
+### 2. Replace decoupling capacitors (fixed in v1.1)
+
+[C5](pcb://C5) and [C6](pcb://C6) have insufficient 10uF decoupling for [U1](pcb://U1) LDO.
+Replace both with 22uF/16V X5R (GRM188R61C226ME15). Bottom side, adjacent
+to [U1](pcb://U1).
+
+### 3. CAN termination resistor
+
+[R12](pcb://R12) footprint is unpopulated. Add 120 ohm 0402 resistor for CAN bus
+termination.
+
+## Firmware
+
+### Prerequisites
+
+- J-Link programmer
+- Firmware v1.0.2: `dm0001-v1.0.2.bin`
+
+### Flash Procedure
+
+1. Connect J-Link to SWD header [J5](pcb://J5)
+2. Power board via 12V supply
+3. Run: `JFlash -openprj dm0001.jflash -open dm0001-v1.0.2.bin -auto -exit`
+4. Verify: LED [D1](pcb://D1) should blink at 1Hz after flash
+
+## Testing
+
+### Power Rail Verification
+
+| Rail | Test Point | Expected | Tolerance |
+|------|-----------|----------|-----------|
+| 3.3V | [TP1](pcb://TP1) | 3.30V | ±50mV |
+| 1.8V | [TP2](pcb://TP2) | 1.80V | ±30mV |
+| 5.0V | [TP3](pcb://TP3) | 5.00V | ±100mV |
+
+### CAN Bus Test
+
+1. Connect CAN analyzer to [J2](pcb://J2)
+2. Send test frame: ID=0x100, DLC=8, data=0xFF
+3. Board should echo back on ID=0x101 within 10ms
+
+### ESTOP Functional Test
+
+1. Short ESTOP connector pins 1-2
+2. Verify ESTOP_OUT test point reads 3.3V (after rework #1)
+3. Open ESTOP connector
+4. Verify ESTOP_OUT reads 0V
+```
diff --git a/docs/pages/docs_changelog.mdx b/docs/pages/docs_changelog.mdx
@@ -0,0 +1,121 @@
+---
+title: Changelog
+description: Conventions for writing package changelogs that are parsed by tooling and shown to users on upgrade.
+---
+
+# Changelog
+
+Every board/package gets a `CHANGELOG.md` at its root (`pcb new` creates one). Parsed by `pcb publish` for release notes and by the build system for CLI display, so format matters.
+
+## Format
+
+Follow [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/):
+
+```markdown
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+
+- New features.
+
+### Changed
+
+- Changes to existing behavior.
+
+### Fixed
+
+- Bug fixes.
+
+### Removed
+
+- Removed features.
+```
+
+## Rules
+
+- **`[Unreleased]` first.** Add entries here as you work. `pcb publish` moves them into a versioned section with today's date.
+- **One entry per user-visible change.** Internal refactors with no behavior change don't need entries.
+- **Four categories only.** `Added`, `Changed`, `Fixed`, `Removed`. Omit empty ones.
+- **Newest version first.** Reverse chronological order.
+- **Write for the upgrader.** Lead with *what* changed, not *why*. Note if action is needed.
+
+## Writing Entries
+
+Each entry is `- ` followed by a concise description. Use backticks for identifiers.
+
+Good:
+```markdown
+- `Component()` now infers missing `footprint` from symbol `Footprint` property.
+- Fix `layout.sync` false positives caused by `.kicad_pro` newline drift.
+```
+
+Avoid:
+```markdown
+- Updated code.
+- Fixed bug.
+- Refactored internals (no user-visible change).
+```
+
+## Versioning
+
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html):
+
+- **Patch** (0.3.1 → 0.3.2): Metadata only — docs, property typos, manufacturer aliases. No connectivity or behavior changes.
+- **Minor** (0.3.x → 0.4.0): New non-breaking functionality — optional pins, new config options, additional footprint variants.
+- **Major** (0.x → 1.0): Breaking changes requiring design updates — changed pin definitions, restructured interfaces, removed features.
+
+Pre-1.0: `pcb publish` bumps minor (0.3.2 → 0.4.0) since minor versions are treated as potentially breaking.
+
+## Tooling
+
+1. **`pcb publish`** — reads `[Unreleased]` as the release body for the annotated git tag.
+2. **Build-time extraction** — CLI parses changelog at compile time for `pcb doc --changelog`. Expects `## [...]` version headers and `### Category` subsections.
+
+Both parsers are strict: use exactly `## [X.Y.Z] - YYYY-MM-DD` for versions and `## [Unreleased]` for the working section.
+
+## Complete Example
+
+```markdown
+# Changelog
+
+All notable changes to this board will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- CAN bus termination option via `config()` parameter.
+
+## [0.2.0] - 2026-02-15
+
+### Changed
+
+- Replace LDO `U1` with TPS54331 buck converter for improved thermal performance.
+- Increase decoupling capacitors `C5`, `C6` from 10uF to 22uF.
+
+### Fixed
+
+- ESTOP debounce resistor value corrected from 47k to 10k.
+
+### Removed
+
+- Removed unused test points `TP4`, `TP5`.
+
+## [0.1.0] - 2026-01-10
+
+### Added
+
+- Initial board design with STM32F4 MCU, CAN bus, and ESTOP circuit.
+- Power supply: 12V input, 3.3V and 1.8V rails.
+- SWD debug header on `J5`.
+```
diff --git a/docs/pages/docs_readme.mdx b/docs/pages/docs_readme.mdx

Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,10 @@`
`40`	`40`	`{`
`41`	`41`	`"group": "Documentation",`
`42`	`42`	`"pages": ["pages/spec", "pages/packages", "pages/testing"]`
	`43`	`+ },`
	`44`	`+ {`
	`45`	`+ "group": "Guides",`
	`46`	`+ "pages": ["pages/docs_bringup", "pages/docs_changelog", "pages/docs_readme"]`
`43`	`47`	`}`
`44`	`48`	`]`
`45`	`49`	`},`