vanara 0.1.0 → 0.3.0

package/catalog/skills/readme-writing/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: readme-writing
+description: How to write a README that gets a project understood and running fast — lead with what/why, a 60-second quickstart, then usage, config, contributing, and license. Covers required sections, show-don't-tell examples, scannability, badges, and failure modes. Use when writing or auditing a project README.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# README Writing
+
+The README is the **front door** of a project. Most readers arrive with one of three jobs: *decide if
+this is worth their time*, *get it running*, or *find one specific answer*. A good README serves all
+three in the order they appear — orientation first, action second, depth on demand. This skill is the
+deep reference for writing one: the required sections, the writing moves that make it scannable, the
+runnable-example discipline, and the failure modes that quietly drive readers away. Heavy detail lives
+in `references/`; copy-paste material in `examples/`; a runnable linter in `scripts/`.
+
+## Mental model
+
+A README is read in **three passes**, and you write top-to-bottom to match them:
+
+| Pass | Reader's question | What answers it |
+|---|---|---|
+| Skim (10s) | "What is this and is it for me?" | Title + one-line description + badges |
+| Try (60s) | "Can I get it running?" | Install + minimal quickstart |
+| Use (later) | "How do I do X specifically?" | Usage, configuration, links to deeper docs |
+
+Optimize ruthlessly for the first 60 seconds. A reader who can't tell what the project does, or who
+hits a broken install command, leaves and does not come back. Everything else is recoverable; the first
+screen is not.
+
+## The required sections (in order)
+
+A complete README has these, roughly in this sequence. Not every project needs every one, but you must
+make a deliberate choice to omit, never an accidental one.
+
+1. **Title + one-line description** — what it is and who it's for, no preamble, no "Welcome to".
+2. **Badges** — build status, version, license, coverage. Signal of health, scanned in a glance.
+3. **Why / value** — the problem it solves, optionally a screenshot, GIF, or short result example.
+4. **Install** — the minimal commands to get the dependency in place, copy-pasteable and verified.
+5. **Quickstart / Usage** — the smallest end-to-end example that produces a visible result.
+6. **Configuration** — options, env vars, defaults — as a table, not prose.
+7. **Contributing** — how to set up a dev environment and the contribution flow (link to `CONTRIBUTING.md`).
+8. **License** — the SPDX name and a link to the `LICENSE` file.
+
+The full anatomy, with what to include and skip per project type (library vs CLI vs service vs
+framework), is in `references/anatomy.md`.
+
+## Lead with what and why
+
+The opening is the most-read and most-botched part. State the **what** in one line, then the **why**.
+Do not bury it under a logo, a table of contents, or a wall of badges.
+
+```markdown
+# Forge
+
+Forge builds and maintains AI agents and skills through a self-improving maker/checker loop —
+so your automation gets better on every run instead of rotting.
+
+[![build](https://img.shields.io/badge/build-passing-brightgreen)]()
+[![npm](https://img.shields.io/npm/v/forge)]()
+[![license](https://img.shields.io/badge/license-MIT-blue)]()
+```
+
+Within two sentences the reader knows the category (agent tooling), the mechanism (maker/checker loop),
+and the payoff (self-improving, no rot). Compare the anti-pattern: *"Welcome to Forge! Forge is a
+powerful, flexible, modern, enterprise-grade platform for..."* — three adjectives and zero information.
+See `references/writing-style.md` for the full list of filler phrases to cut.
+
+## The 60-second quickstart
+
+The quickstart is a promise: *paste these commands and see it work.* It must be **copy-pasteable**,
+**self-contained**, and **actually run** — test it in a clean checkout before shipping.
+
+```markdown
+## Quick start
+
+\`\`\`bash
+git clone https://github.com/acme/forge && cd forge
+npm install
+npx forge audit ./my-project    # prints a scorecard
+\`\`\`
+
+You should see a table of findings within a few seconds. Next, try `forge fix` to apply them.
+```
+
+Rules that make or break it:
+
+- **Show the expected output**, or at least describe it ("you should see a table"). A command with no
+  visible result leaves the reader unsure it worked.
+- **One happy path only.** Do not branch into "if you use yarn / pnpm / bun" in the quickstart — pick
+  one, link the rest. Optionality kills momentum.
+- **No undeclared prerequisites.** If it needs Node 20+, a running Postgres, or an API key, say so
+  *before* the commands, not in a stack trace the reader hits later.
+
+## Show, don't tell
+
+Prose describing behavior ages badly and is hard to trust. A **runnable example** is self-verifying —
+either it works or the reader sees it break. Prefer concrete examples over adjectives at every turn.
+
+```markdown
+## Usage
+
+\`\`\`js
+import { Forge } from 'forge';
+
+const forge = new Forge({ target: './my-project' });
+const report = await forge.audit();
+
+console.log(report.score);        // 87
+console.log(report.findings[0]);  // { rule: 'no-secrets', severity: 'high', file: '.env' }
+\`\`\`
+```
+
+The inline comments showing return values turn a snippet into documentation. This is why `examples/`
+ships a `good-readme-example.md` and a `README.template.md` you can adapt — see *Files in this package*.
+
+## Make it scannable
+
+Readers skim, they do not read. Structure for the eye:
+
+- **Headings every few paragraphs** so the table of contents (and the reader's scroll) has anchors.
+- **Tables for anything with structure** — config options, CLI flags, comparison matrices. A 5-row
+  table beats two paragraphs of "the `--depth` flag controls...".
+- **Code blocks for anything runnable**, always fenced with a language for syntax highlighting.
+- **Short paragraphs.** One idea each. Walls of text are scrolled past, not read.
+- **Link out for depth.** The README is a launchpad, not the manual. Link to `docs/`, the wiki, or a
+  hosted site rather than inlining a 200-line configuration reference.
+
+Audience calibration matters too: a library README assumes a developer who will read code; a CLI
+README assumes someone who wants commands; an end-user app README assumes neither. Details in
+`references/anatomy.md`.
+
+## Common pitfalls (failure modes)
+
+- **The broken quickstart.** Commands that don't run in a clean checkout — stale flags, missing
+  `install` step, undeclared env var. The single most damaging README bug. Test it cold.
+- **Burying the lede.** A logo, badge wall, or 30-line table of contents before the one-line
+  description. The reader scrolls looking for "what is this" and gives up.
+- **Adjective soup.** "Powerful, flexible, blazing-fast, enterprise-grade" — these are unfalsifiable
+  and information-free. Replace with a concrete capability or benchmark.
+- **Telling instead of showing.** Paragraphs describing the API instead of a code block using it.
+- **The novel.** Inlining the entire configuration reference, changelog, and architecture doc. The
+  README becomes unmaintainable and unscannable. Link out.
+- **Drift.** Examples that no longer match the current API because nobody re-ran them. Treat README
+  snippets as testable artifacts (see `scripts/lint-readme.mjs` and `references/maintenance.md`).
+- **No license.** A repo with no `LICENSE` is, legally, all-rights-reserved — nobody can safely use it.
+  Always state the license.
+
+## When NOT to write a heavy README / trade-offs
+
+A README is not the right home for everything, and more is not better:
+
+- **Deep, multi-page docs** belong in a `docs/` site (Docusaurus, mdBook, ReadTheDocs), not the README.
+  A README that scrolls for ten screens has failed at being a front door. Link instead.
+- **API reference** that's mechanically derivable (TypeDoc, rustdoc, Sphinx) should be generated, not
+  hand-written into the README where it will drift.
+- **Internal-only / throwaway repos** may need only a title and a one-line run command — don't gold-plate
+  a README nobody outside the team will read.
+- **Monorepos** often want a thin root README that routes to per-package READMEs, rather than one giant
+  document trying to cover every package.
+
+The trade-off is always **completeness vs. scannability**. When they conflict, scannability wins in the
+README and completeness moves to linked docs.
+
+## Files in this package
+
+- `references/anatomy.md` — full section-by-section anatomy + what to include per project type
+- `references/writing-style.md` — voice, filler phrases to cut, scannability techniques, badges
+- `references/maintenance.md` — keeping a README honest: testing snippets, drift, automation in CI
+- `examples/README.template.md` — a fill-in-the-blanks starter README with every required section
+- `examples/good-readme-example.md` — a complete, worked example README for a sample CLI tool
+- `scripts/lint-readme.mjs` — runnable Node check that a README has the required sections + a quickstart code block
+
+Pairs with the `documentation-structure` skill (for organizing the wider `docs/` tree the README links
+into) and the `technical-writer` agent (for tightening prose and voice). Also see the `changelog-writing`
+skill for the companion `CHANGELOG.md`.

package/catalog/skills/readme-writing/examples/README.template.md

@@ -0,0 +1,73 @@
+<!--
+  README TEMPLATE — fill in the blanks, delete the guidance comments and any
+  sections you don't need. Order is deliberate: what -> why -> run -> use -> details.
+  Run scripts/lint-readme.mjs against your filled-in copy to check required sections.
+-->
+
+# <Project Name>
+
+<!-- One sentence: what it is + who it's for + the payoff. No "Welcome to". -->
+<One-line description: the category and the value, in a single sentence.>
+
+<!-- One row of high-signal badges. Build, version, license, maybe coverage. -->
+[![build](https://img.shields.io/badge/build-passing-brightgreen)]()
+[![version](https://img.shields.io/badge/version-0.0.0-blue)]()
+[![license](https://img.shields.io/badge/license-MIT-blue)]()
+
+## Why
+
+<!-- The problem it solves and the result. Add a screenshot/GIF for visual tools,
+     or a tiny before/after snippet for libraries. -->
+<What problem does this solve, and what does using it get you?>
+
+## Install
+
+<!-- State prerequisites first, then the single primary install command. -->
+Requires <runtime + version>.
+
+```bash
+<install command>
+```
+
+## Quick start
+
+<!-- The smallest end-to-end example that produces a visible result.
+     Copy-pasteable. Show or describe the expected output. One happy path only. -->
+```bash
+<command 1>
+<command 2>
+```
+
+You should see <expected result> within <time>.
+
+## Usage
+
+<!-- Common tasks as runnable snippets. Show return values in comments.
+     Link out to generated reference docs instead of dumping the whole API. -->
+```js
+<minimal usage example with expected output in comments>
+```
+
+See [the full docs](<link>) for more.
+
+## Configuration
+
+<!-- A table beats prose for options. -->
+| Option | Env var | Default | Description |
+|---|---|---|---|
+| `<option>` | `<ENV_VAR>` | `<default>` | <what it does> |
+
+## Contributing
+
+<!-- Dev setup + link to the full flow. -->
+Contributions welcome. To set up locally:
+
+```bash
+<clone + install + test commands>
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full process.
+
+## License
+
+[<SPDX-ID>](./LICENSE) © <year> <holder>

package/catalog/skills/readme-writing/examples/good-readme-example.md

@@ -0,0 +1,95 @@
+<!--
+  WORKED EXAMPLE — a complete, realistic README for a small CLI tool ("tiderss",
+  a terminal RSS reader). Use it as a reference for tone, length, and structure.
+  Notice: what/why in the first three lines, a 60-second quickstart with expected
+  output, a config table, links out for depth, and a license. It passes lint-readme.mjs.
+-->
+
+# tiderss
+
+A fast terminal RSS reader that lives in your shell — subscribe, sync, and read feeds without leaving
+the keyboard.
+
+[![build](https://img.shields.io/badge/build-passing-brightgreen)]()
+[![npm](https://img.shields.io/badge/npm-v1.4.0-blue)]()
+[![license](https://img.shields.io/badge/license-MIT-blue)]()
+
+## Why
+
+Web feed readers are slow, ad-laden, and pull you into a browser tab you'll never close. `tiderss` keeps
+reading where the work already is: the terminal. It syncs in the background, caches offline, and renders
+articles as clean, readable text.
+
+![tiderss reading view](./docs/screenshot.png)
+
+## Install
+
+Requires Node 20+.
+
+```bash
+npm install -g tiderss
+```
+
+## Quick start
+
+```bash
+tiderss add https://blog.acme.dev/feed.xml   # subscribe to a feed
+tiderss sync                                  # fetch latest items
+tiderss read                                  # open the reader
+```
+
+After `sync` you'll see a count of new items (`12 new across 1 feed`), and `read` opens an interactive
+list. Use `j`/`k` to move, `Enter` to open, `q` to quit.
+
+## Usage
+
+List your subscriptions and unread counts:
+
+```bash
+tiderss list
+# acme-blog      12 unread
+# rust-weekly     3 unread
+```
+
+Mark everything read and export your subscriptions as OPML:
+
+```bash
+tiderss mark-all-read
+tiderss export > feeds.opml
+```
+
+For scripting, every command accepts `--json`:
+
+```bash
+tiderss list --json
+# [{ "feed": "acme-blog", "unread": 12 }, { "feed": "rust-weekly", "unread": 3 }]
+```
+
+See [the command reference](./docs/commands.md) for the full list.
+
+## Configuration
+
+Config lives at `~/.config/tiderss/config.toml`. All values are overridable by env var.
+
+| Option | Env var | Default | Description |
+|---|---|---|---|
+| `sync_interval` | `TIDERSS_SYNC_INTERVAL` | `30m` | Background sync cadence |
+| `cache_dir` | `TIDERSS_CACHE_DIR` | `~/.cache/tiderss` | Where article bodies are cached |
+| `theme` | `TIDERSS_THEME` | `auto` | `light`, `dark`, or `auto` |
+| `concurrency` | `TIDERSS_CONCURRENCY` | `8` | Parallel feed fetches |
+
+## Contributing
+
+Contributions are welcome. To set up a dev environment:
+
+```bash
+git clone https://github.com/acme/tiderss && cd tiderss
+npm install
+npm test
+```
+
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and open an issue before large changes.
+
+## License
+
+[MIT](./LICENSE) © 2026 Acme

package/catalog/skills/readme-writing/references/anatomy.md

@@ -0,0 +1,107 @@
+# README Anatomy — Section by Section
+
+A complete README is built from a known set of sections. Below is each one: its job, what to put in it,
+and what to leave out. Order matters — readers consume top to bottom and bail early, so the highest-value
+content goes first.
+
+## 1. Title and one-line description
+
+- **Job:** answer "what is this and is it for me?" in under ten seconds.
+- **Do:** the project name as an `# H1`, then a single sentence naming the category and the payoff.
+- **Don't:** "Welcome to", a logo before the name, or a tagline so abstract it could describe anything.
+
+```markdown
+# Forge
+
+A self-improving maker/checker loop for building and maintaining AI agents and skills.
+```
+
+## 2. Badges
+
+- **Job:** a health signal scanned in a glance — is it maintained, does it build, what license.
+- **Do:** build/CI status, package version, license, test coverage. Keep to one row.
+- **Don't:** twenty badges. A badge wall is noise and pushes the description below the fold.
+
+## 3. Why / value (and a visual)
+
+- **Job:** convince the skimmer this solves their problem.
+- **Do:** name the problem, then the result. For visual or interactive tools, a screenshot or GIF here
+  is worth a thousand words. For libraries, a tiny before/after code example.
+- **Don't:** a history of the project, your motivation, or a manifesto. Save it for `docs/`.
+
+## 4. Install
+
+- **Job:** get the dependency in place with zero ambiguity.
+- **Do:** the exact command(s) for the primary install path. State prerequisites (runtime version,
+  system deps) immediately above it.
+- **Don't:** five package managers and three OSes inline. Pick the primary, link the matrix.
+
+```markdown
+## Install
+
+Requires Node 20+.
+
+\`\`\`bash
+npm install forge
+\`\`\`
+```
+
+## 5. Quickstart / Usage
+
+- **Job:** prove it works and teach the happy path.
+- **Do:** the smallest end-to-end example that produces a visible result, with expected output shown.
+  Then a few common-task examples.
+- **Don't:** an exhaustive API dump. Link to generated reference docs for that.
+
+## 6. Configuration
+
+- **Job:** make options discoverable without reading source.
+- **Do:** a table of options, env vars, and defaults. Tables scan far better than prose here.
+
+```markdown
+| Option | Env var | Default | Description |
+|---|---|---|---|
+| `target` | `FORGE_TARGET` | `.` | Directory to audit |
+| `depth` | `FORGE_DEPTH` | `3` | Max recursion depth |
+```
+
+## 7. Contributing
+
+- **Job:** lower the barrier for the next contributor.
+- **Do:** dev setup commands, how to run tests, and a link to `CONTRIBUTING.md` for the full flow.
+- **Don't:** paste the entire code-of-conduct and PR checklist inline. Link them.
+
+## 8. License
+
+- **Job:** tell people whether they can legally use it. A repo with no license is all-rights-reserved.
+- **Do:** the SPDX identifier (e.g. `MIT`, `Apache-2.0`) and a link to the `LICENSE` file.
+
+```markdown
+## License
+
+[MIT](./LICENSE) © 2026 Acme
+```
+
+## Optional sections (use when relevant)
+
+| Section | Add when |
+|---|---|
+| Table of contents | The README is long enough to need in-page navigation (keep it collapsed) |
+| Features | The value isn't obvious from one line and benefits from a bulleted list |
+| Architecture | Contributors need a mental map; otherwise link to `docs/architecture.md` |
+| FAQ / Troubleshooting | There are recurring support questions worth pre-empting |
+| Roadmap | The project is early and you want to set expectations |
+| Acknowledgements / Credits | You're standing on others' work and want to credit it |
+
+## Tailoring by project type
+
+| Type | Lead with | Emphasize | De-emphasize |
+|---|---|---|---|
+| **Library** | a code snippet using it | install + import + usage | CLI, screenshots |
+| **CLI tool** | the primary command | flags table, examples | import-as-module API |
+| **Service / API** | what it serves + a curl example | run/deploy, config, endpoints | language-level API |
+| **Framework** | a "hello world" | concepts, links to a docs site | exhaustive reference inline |
+| **App / end-user** | a screenshot or GIF | how to install and run | code internals |
+
+The rule across all of them: **lead with the thing the reader most wants to do**, and move everything
+else to its right place — usually a linked doc.

package/catalog/skills/readme-writing/references/maintenance.md

@@ -0,0 +1,68 @@
+# Keeping a README Honest — Maintenance and Drift
+
+The most dangerous README is one that *used* to be correct. A broken quickstart or a snippet that no
+longer matches the API erodes trust faster than having no example at all. This reference is about keeping
+the README true over time.
+
+## Why READMEs drift
+
+- **Code changes, docs don't.** A flag is renamed, an import path moves, a default changes — the README
+  still shows the old form because nobody re-ran it.
+- **Copy-paste rot.** Examples copied from an old version or another project that never quite applied.
+- **Untested commands.** The quickstart was written from memory, not from a clean checkout, and a step
+  (usually `install`) is missing.
+
+## Treat snippets as testable artifacts
+
+The fix is to make examples *executable* rather than *aspirational*:
+
+- **Run the quickstart in CI** against a clean checkout. If `git clone && npm install && npx forge audit`
+  is the promise, run exactly that in a fresh container and fail the build if it errors.
+- **Extract and execute code blocks.** Tools like `mdsnippets`, `doctest`-style harnesses, or a small
+  script that pulls fenced blocks and runs them keep snippets in sync. Even a smoke test that the
+  documented command exits 0 catches the worst breakage.
+- **Lint structure in CI.** Use `scripts/lint-readme.mjs` (in this package) to assert the required
+  sections and a quickstart code block are present, so a refactor can't silently gut the README.
+
+## A pre-release checklist
+
+Before tagging a release, verify:
+
+- [ ] Quickstart runs end-to-end in a clean checkout (no missing prerequisite or step).
+- [ ] Every command's flags match the current CLI (`--help` agrees with the README).
+- [ ] Code snippets compile/run against the current version.
+- [ ] Version badge and any version-pinned install command point at the release.
+- [ ] Links resolve (no 404s to moved docs); relative links work on the repo host.
+- [ ] License section matches the actual `LICENSE` file.
+- [ ] Screenshots/GIFs still reflect the current UI.
+
+## Automating the check
+
+A minimal CI step that catches the structural failures:
+
+```yaml
+# .github/workflows/readme.yml
+name: readme
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node catalog/skills/readme-writing/scripts/lint-readme.mjs README.md
+```
+
+The linter exits non-zero when a required section or the quickstart block is missing, so a PR that
+deletes the install section fails review automatically.
+
+## Single-source where you can
+
+Drift is hardest to avoid when the same fact lives in two places. Reduce duplication:
+
+- **Generate** API reference from source (TypeDoc/rustdoc/Sphinx) rather than hand-copying signatures.
+- **Link** to `CHANGELOG.md` instead of summarizing release notes in the README.
+- **Pull** the version from the package manifest in CI rather than hardcoding it in prose.
+
+The less the README restates, the less there is to fall out of date.

package/catalog/skills/readme-writing/references/writing-style.md

@@ -0,0 +1,79 @@
+# README Writing Style — Voice, Scannability, Badges
+
+A README is a document people *skim under time pressure*. The writing has to survive that. This is the
+style reference: how to phrase things, what to cut, and how to format for the eye.
+
+## Voice
+
+- **Second person, present tense, active voice.** "Run `forge audit`" not "The audit can be run by the
+  user." Direct instructions are faster to act on.
+- **Concrete over abstract.** "Audits a project in under two seconds" beats "blazingly fast". If you
+  have a number, use it; if you don't, describe the capability, not its adjective.
+- **Confident but not salesy.** State what it does. You're documenting, not pitching.
+
+## Filler phrases to cut
+
+These add length and subtract information. Delete on sight:
+
+| Cut this | Why |
+|---|---|
+| "Welcome to..." | Wastes the most-read line on a greeting |
+| "powerful, flexible, robust, modern" | Unfalsifiable adjective soup — say *what* it does |
+| "simply", "just", "easy" | Condescending and often untrue for the reader |
+| "blazing-fast", "lightning-fast" | A benchmark number is credible; an adjective isn't |
+| "enterprise-grade", "production-ready" | Meaningless without evidence (tests, SLAs, users) |
+| "as you can see", "obviously", "of course" | If it's obvious, don't say it; if it's not, it's rude |
+| "in order to" | "to" is shorter and identical in meaning |
+
+## Scannability techniques
+
+- **Headings as signposts.** A reader scrolls and reads only headings until one matches their goal.
+  Make headings describe content (`## Configuration`), not be cute (`## The knobs`).
+- **Tables for structured data.** Anything that's "X has property Y with default Z" is a table, not a
+  paragraph. Options, flags, comparisons, env vars.
+- **Fenced code blocks with a language.** Always tag the fence (` ```bash `, ` ```js `) so syntax
+  highlighting kicks in and the reader can tell commands from output.
+- **Short paragraphs, one idea each.** Three sentences max. White space is a feature.
+- **Bold the load-bearing word** in a bullet so the eye catches it while scanning.
+- **Lists over comma-runs.** Three or more parallel items become a bulleted list.
+
+## Code block discipline
+
+- Show **expected output** alongside commands, as comments or a following block. A command with no
+  visible result is an unverifiable claim.
+- Keep examples **minimal and runnable** — no `...` placeholders in a block you're telling people to
+  paste. If you must elide, make it obvious and non-pasteable.
+- Use **realistic values**, not `foo`/`bar`, where a realistic value teaches something.
+
+## Badges, done right
+
+Badges are a glanceable health dashboard. The high-signal set:
+
+- **Build / CI status** — is the main branch green?
+- **Version** — npm/PyPI/crates.io published version.
+- **License** — at a glance, can I use it?
+- **Coverage** — optional, only if it's genuinely good and maintained.
+
+Keep them on one line, near the title. A wall of fifteen badges (downloads-this-week, Discord, Twitter,
+sponsors, code style, dependencies, ...) is noise that pushes your description below the fold. Shields.io
+generates consistent ones.
+
+## Links, not inlining
+
+The README is a launchpad. When a topic needs more than a screen, write a short summary and **link out**:
+
+- Deep configuration → `docs/configuration.md` or a hosted docs site
+- Full API → generated reference (TypeDoc, rustdoc, Sphinx)
+- Contribution details → `CONTRIBUTING.md`
+- Version history → `CHANGELOG.md`
+
+This keeps the README scannable and the deep content in a place where it can be versioned and generated
+without bloating the front door.
+
+## Accessibility and rendering
+
+- Give images **alt text** (`![alt](url)`) — screen readers and broken-image fallbacks rely on it.
+- Don't encode meaning in **color alone** (e.g. a red/green badge); the text label must carry it too.
+- Prefer **relative links** to in-repo files (`./LICENSE`) so they work on forks and mirrors.
+- Test the rendered Markdown on the host (GitHub/GitLab) — not every renderer supports the same
+  extensions (collapsible `<details>`, task lists, footnotes).