docs: explain the source-first workflow and compare with snippet checkers (#2)

[adrianbrowning]

Closes #2.

Summary

The READMEs now say that examples live in source or test files, your own lint and tests check them there, and mdcode update copies them into Markdown. The package README's "Why Use mdcode?" used to lead with the Markdown-first flow ("Write examples once in your README"), which is the confusion the issue describes.

 README.md
   intro
+    examples stay in source/test files; your checks run on them; update copies them in
+    mdcode doesn't type-check or lint fences; link to Kiira and the comparison
   Quick start
+    "It's an ordinary file, so your lint, type check and tests already cover it"
+    CI snippet: npm run lint && npm test, then mdcode update --check
 packages/mdcode/README.md
   Why Use mdcode?
-    The Solution: write in Markdown → extract → run → update
+    The Solution: write as code → point a block at it → lint/test → update / --check
-    Single Source of Truth: "Write examples once in your README"
+    One Copy to Maintain
+    Writing Examples in the Markdown   (extract/run flow kept, framed as the other direction)
+    mdcode and Snippet Checkers         (Kiira comparison, which snippets suit which tool)
 .bumpy/source-first-docs.md            (mdcode-ts: patch, since the package README ships to npm)

The comparison only describes what Kiira says it does: it extracts TS/JS fences from Markdown and MDX, type-checks them against the project, and reports errors on the fence line in the editor, the CLI and CI. It also points out that validate-snippets.mjs can run your own tsc on runnable=true blocks, so the docs don't claim mdcode can't check Markdown-authored code at all.

I dropped file=tests/examples/base-1.sh from the "Keep Examples Fresh" block I rewrote. That file has never existed, and mdcode update --check reports it as missing on main too. I left the other file=block-N blocks alone.

Evidence

The quick start and the new CI snippet, run against a temp project built from the README's src/greet.ts:

$ mdcode update --check README.md   -> 1   ✗ Out of sync: line 3: ts from src/greet.ts region=greet
$ mdcode update --apply README.md   -> 0   Updated 1 block(s) in README.md.
$ mdcode update --check README.md   -> 0   ✓ 1 block(s) in sync.

mdcode list still parses both READMEs (8 and 109 blocks). pnpm check passes, including docs.test.ts.

Merge Danger

Door: two-way

Blast Radius: docs

README text only. No CLI or library behaviour changes.

[github-actions]

The changes in this PR will be included in the next version bump.

Patch releases

• mdcode-ts 0.0.4 → 0.0.5

Bump files in this PR

• source-first-docs.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run