trustmebro
Insert verified links into a post (markdown or html) so a reader can read and verify it: explain jargon, back up external claims, and (rarely) show code. You hand the reader the source to check a claim; you do NOT ask them to take your word, and trustmebro does NOT decide if the claim is true. trustmebro ADDS citations; it is NOT a fact-check of the document.
The agent makes every judgment call; a small helper (trustmebro) does the mechanics. The helper only checks a link is LIVE; whether it is RIGHT is on you.
Quickstart
- Read the post and do a deliberate jargon sweep: every concept, tool, protocol, or algorithm a technical generalist (literate, not a specialist in this domain) would not know is an EXPLAIN candidate; external claims are SUBSTANTIATE candidates. The bias is split by type: be thorough on EXPLAIN, defaulting to OVER-linking (a link is low-risk and one keystroke for the human to remove; a reader stuck on an unlinked term is the real cost), and conservative on SUBSTANTIATE (a wrong backing link does damage). When you're unsure whether that reader knows a term, LINK it. And sweep the post's own central + domain nouns and newer coinages too, the term the whole piece is about, the security/protocol/format words (e.g. 'ai agent', a 'secret' meaning a credential, a protocol name), not just the obvious acronyms, those central terms are the ones most often missed. You do not pre-ration; the human prunes. Never manufacture a link, no honest source means don't (flag it instead). Don't leave the post's central term unlinked while citing a secondary one, unless it has no honest target, then flag it (under-linking the center beats laundering it).
- Resolve each: web-search the source, open it, confirm it means the term / backs the claim in this post's sense. A live-but-wrong link is the worst output.
- Flag, don't fabricate. Can't back a claim, or it looks false? Don't invent a link:
trustmebro flag <post> <reason> (put the dead url IN the reason).
- Insert each with
trustmebro insert <file> <phrase> <url>, it verifies the url, wraps the first occurrence of the phrase (errors if the phrase isn't found, the missed-add safety net; notes if it occurs several times), in the doc's format (markdown, or HTML <a href>; tell the user if you adapt). To target a specific later occurrence, pass a longer unique phrase. Never rewrite prose.
- Gate:
trustmebro prove <post> <base> (only link markup changed) and trustmebro lint <post> (no url-as-text half-fix). Both must pass. Pass the base ref, since a bare prove after committing self-passes.
- Hand off with the list + an open invite, always, every run. When you finish, give the user a tight list of what you linked (term -> source) and name what you deliberately skipped and why (a term inside a code span can't be linked; a claim you flagged). Then, in ONE message so they never have to think to ask for more, invite the next pass: "here's what i linked, review the preview and tell me if you want any removed, others added, a more aggressive sweep, or if you have a specific list of terms. anything else you wanted done?" This is the point: reduce the back-and-forth, you offer the next step, they don't have to prompt for it. (For pre-existing links you didn't touch, just count them with
trustmebro links and offer a rot-check on a yes.)
The reader you assume
A technical generalist: literate, but NOT a specialist in this post's domain. Link a term only if that reader would not know it. This one tiebreaker kills both "some novice might not know X" and "an expert knows X".
The bar for every link
- RESOLVES, public HTTP 200 (
trustmebro verify).
- RIGHT, the page genuinely means the term / backs the claim in this post's sense.
trustmebro verify cannot check this; open it and read. Watch multi-sense terms (the _(computing) page, not the physics one), and prefer the canonical page over a stale-but-live one (follow the redirect).
- HELPS, more than no link. Don't link a word the reader knows, and don't re-link the same term twice. But EXPLAIN is per-concept, not rationed: every distinct unknown term earns its one link, even several in a section. The thing to avoid is repetition and linking the obvious, not coverage.
What to link (value-ranked)
- EXPLAIN (highest), every concept/tool/protocol/algorithm the reader would not know (
ast, raft, io_uring, knowledge graph, connected component) gets an authoritative explainer. Sweep for these and don't ration them: an explainer is unambiguous (low risk) and one keystroke to delete, so erring toward including a real unknown term serves the reader. It defines the word; it does NOT vouch the surrounding claim (see the laundering trap).
- SUBSTANTIATE, a real tool / library / protocol / stat / quote gets its authoritative page. Where a wrong link does the most damage.
- SHOW code (rare, gated on clarity not authorship), when seeing the code illuminates a claim, a sha-pinned permalink. Public + verified. Skip proof-only code links.
The laundering trap
An explainer link makes the surrounding sentence read as backed. So if a claim is dubious, unverifiable, or about a thing that may not exist, do NOT sprinkle explainer links around it, you would lend borrowed credibility. Decision test: is the sentence's CORE claim independently true? If no, refuse even a perfect term-explainer and flag it instead. (E.g. "vortex uses a count-min sketch": the term is real, but if "vortex" is unverifiable, linking it makes the whole sentence read as backed, refuse.)
Flag, don't fabricate
Can't back a claim (a tool not made, a concept not invented, an unsourced stat)? Don't invent a link, surface it and record it: trustmebro flag <post> <reason> appends to .tmb-flags.md at the repo root. Put the dead url in the reason: trustmebro check downgrades a verify failure whose url is flagged to "flagged, known" (not a gate failure), so a correctly-flagged pre-existing dead link still PASSes.
What trustmebro is NOT
Link-hygiene + targeted explanation, NOT a whole-document fact-check. It only inspects what it links; untouched claims ride straight through. A trustmebro-passed post is NOT a verified-true post.
Dead vs gated (when verifying)
A non-200 is not automatically dead. Some hosts (crates.io, npm, registries) 403 an anonymous check but load in a browser (bot-gated). Confirm via a non-gated source (a registry's json/index), or trustmebro verify --crosscheck (probes the host root), before calling a link dead. A link YOU add must verify clean. A PRE-EXISTING author link that fails is FLAGGED, never auto-stripped; prefer fixing it to its canonical (often live nearby in the same doc), and fix every occurrence (href + visible text).
Code mode (the rare code link)
Know or infer the repo, read a .tmb map if present (name = owner/repo), or ask. trustmebro preflight <repo-dir> reports slug / HEAD / pushed / visibility. Private repo, do not cite it. trustmebro permalink <repo-dir> <path> <start> [end] [--ref origin/<branch>] builds a sha-pinned, range-validated link.
Setup
The trustmebro script is next to this file. Put it on PATH (ln -s "$PWD/trustmebro" ~/.local/bin/trustmebro) or call it by path. Invoke it as trustmebro or the short alias tmb, the two are identical. Needs node (>=18, for built-in fetch) and git (gh optional). No bash/perl/curl, runs on macOS, Linux, and Windows. Two roots: trustmebro operates on the post's git repo (where prove / flag / check work). Clone the helper outside that repo (or gitignore it), so it does not get committed into the post's tree.
Helper reference
trustmebro verify <url> | trustmebro verify - resolves? HTTP code + dead-vs-gated hint + redirect landing (batch: parallel, JSONL). --crosscheck probes the host root.
trustmebro links <file> every link url (md + html href + ref-defs + autolinks + bare), images excluded. --relative also lists relative targets.
trustmebro insert <file> <phrase> <url> safe add: verify url + wrap the FIRST literal match (md or html). errors on 0 (missed add); notes on multiples. no every-occurrence mode.
trustmebro prove <file> [ref] assert ONLY link markup changed vs ref (default HEAD); fails on any prose/text/whitespace edit.
trustmebro lint <file> catch the half-fix (visible text is a url that differs from its href). --fix syncs it.
trustmebro flag <post> <reason> record a dead link / dubious claim (WITH its url) to .tmb-flags.md.
trustmebro check <post> [base] OPTIONAL full audit: verify all links + prove + lint. Offer it, never auto-run, never a gate on adding links.
trustmebro sweep <repo-dir> <base> prove + lint over every changed .md , backstop after a batch run.
trustmebro preflight / permalink (code mode) repo state / sha-pinned permalink.
trustmebro version
Add --json for structured output (links / verify / lint / check). To cite or flag a phrase that IS a flag token, end options with --: trustmebro insert post.md -- --fix <url>.
Environment. TMB_JOBS sets batch parallelism for verify / check / sweep (default 16, the one knob with no flag). TMB_JSON / TMB_XCHECK / TMB_FIX / TMB_REL mirror --json / --crosscheck / --fix / --relative.
Works on markdown OR html, a post, doc, readme, or article (.md / .html). insert writes a [markdown](link) for a .md file and an <a href> for a .html file (it keys off the extension; tell the user if you adapt). Code regions trustmebro skips = fenced ```/~~~ blocks, inline `code`, html comments, and html <pre> / <code> blocks , NOT Markdown's 4-space-indented code blocks. Put code you don't want trustmebro to read/touch in a fenced (or <pre>) block. Other parser limits (optional-audit only; eyeball foreign docs): deeply-nested-paren urls, multi-line html anchors, html-entity hrefs, reference-style ([text][ref]) link bodies (insert/lint protect inline + html links, not ref-style).
1---2name: trustmebro3description: Insert verified links into a markdown or html post so a reader can READ and VERIFY it (hand them the source to check a claim, don't ask them to take your word; not a proof of truth). Three kinds: EXPLAIN a term a non-specialist would not know, SUBSTANTIATE a claim about an external thing, or (rarely) SHOW code via a sha-pinned permalink. Every link must resolve AND actually mean the thing in context (a live-but-wrong link is the worst output). NOT a fact-check of the document. Triggers: "cite this post", "add citations", "explain the jargon", "back up the claims", "make this post easier to follow". Sweeps jargon aggressively for a technical-generalist reader, auto-inserts verified links, then lists what it linked and invites you to add / remove / go more aggressive in one pass. Review the diff.4---56# trustmebro78Insert **verified** links into a post (markdown or html) so a reader can **read and verify** it: explain jargon, back up external claims, and (rarely) show code. You hand the reader the source to check a claim; you do NOT ask them to take your word, and trustmebro does NOT decide if the claim is true. **trustmebro ADDS citations; it is NOT a fact-check of the document.**910The agent makes every judgment call; a small helper (`trustmebro`) does the mechanics. **The helper only checks a link is LIVE; whether it is RIGHT is on you.**1112## Quickstart13141. **Read** the post and do a deliberate **jargon sweep**: every concept, tool, protocol, or algorithm a *technical generalist* (literate, not a specialist in this domain) would not know is an EXPLAIN candidate; external claims are SUBSTANTIATE candidates. The bias is split by type: be **thorough on EXPLAIN, defaulting to OVER-linking** (a link is low-risk and one keystroke for the human to remove; a reader stuck on an unlinked term is the real cost), and **conservative on SUBSTANTIATE** (a wrong backing link does damage). **When you're unsure whether that reader knows a term, LINK it.** And sweep the post's own *central + domain* nouns and newer coinages too, the term the whole piece is about, the security/protocol/format words (e.g. 'ai agent', a 'secret' meaning a credential, a protocol name), not just the obvious acronyms, those central terms are the ones most often missed. You do not pre-ration; the human prunes. Never manufacture a link, no honest source means don't (flag it instead). Don't leave the post's *central* term unlinked while citing a secondary one, unless it has no honest target, then flag it (under-linking the center beats laundering it).152. **Resolve** each: web-search the source, **open it**, confirm it means the term / backs the claim *in this post's sense*. A live-but-wrong link is the worst output.163. **Flag, don't fabricate.** Can't back a claim, or it looks false? Don't invent a link: `trustmebro flag <post> <reason>` (put the dead url IN the reason).174. **Insert** each with `trustmebro insert <file> <phrase> <url>`, it verifies the url, wraps the **first** occurrence of the phrase (errors if the phrase isn't found, the missed-add safety net; notes if it occurs several times), in the doc's format (markdown, or HTML `<a href>`; tell the user if you adapt). To target a specific later occurrence, pass a longer unique phrase. Never rewrite prose.185. **Gate:** `trustmebro prove <post> <base>` (only link markup changed) and `trustmebro lint <post>` (no url-as-text half-fix). Both must pass. Pass the base ref, since a bare prove after committing self-passes.196. **Hand off with the list + an open invite, always, every run.** When you finish, give the user a tight list of what you linked (term -> source) and name what you deliberately skipped and why (a term inside a code span can't be linked; a claim you flagged). Then, in ONE message so they never have to think to ask for more, invite the next pass: *"here's what i linked, review the preview and tell me if you want any removed, others added, a more aggressive sweep, or if you have a specific list of terms. anything else you wanted done?"* This is the point: reduce the back-and-forth, you offer the next step, they don't have to prompt for it. (For pre-existing links you didn't touch, just count them with `trustmebro links` and offer a rot-check on a yes.)2021## The reader you assume2223A **technical generalist**: literate, but NOT a specialist in this post's domain. Link a term only if *that* reader would not know it. This one tiebreaker kills both "some novice might not know X" and "an expert knows X".2425## The bar for every link26271. **RESOLVES**, public HTTP 200 (`trustmebro verify`).282. **RIGHT**, the page genuinely means the term / backs the claim in this post's sense. `trustmebro verify` cannot check this; open it and read. Watch multi-sense terms (the `_(computing)` page, not the physics one), and prefer the canonical page over a stale-but-live one (follow the redirect).293. **HELPS**, more than no link. Don't link a word the reader knows, and don't re-link the same term twice. But EXPLAIN is **per-concept, not rationed**: every *distinct* unknown term earns its one link, even several in a section. The thing to avoid is repetition and linking the obvious, not coverage.3031## What to link (value-ranked)32331. **EXPLAIN** (highest), every concept/tool/protocol/algorithm the reader would not know (`ast`, `raft`, `io_uring`, `knowledge graph`, `connected component`) gets an authoritative explainer. Sweep for these and don't ration them: an explainer is unambiguous (low risk) and one keystroke to delete, so erring toward including a real unknown term serves the reader. It defines the word; it does NOT vouch the surrounding claim (see the laundering trap).342. **SUBSTANTIATE**, a real tool / library / protocol / stat / quote gets its authoritative page. Where a wrong link does the most damage.353. **SHOW code** (rare, gated on clarity not authorship), when seeing the code illuminates a claim, a sha-pinned permalink. Public + verified. Skip proof-only code links.3637## The laundering trap3839An explainer link makes the surrounding sentence *read as backed*. So if a claim is dubious, unverifiable, or about a thing that may not exist, do NOT sprinkle explainer links around it, you would lend borrowed credibility. **Decision test: is the sentence's CORE claim independently true?** If no, refuse even a perfect term-explainer and flag it instead. (E.g. "vortex uses a count-min sketch": the term is real, but if "vortex" is unverifiable, linking it makes the whole sentence read as backed, refuse.)4041## Flag, don't fabricate4243Can't back a claim (a tool not made, a concept not invented, an unsourced stat)? Don't invent a link, surface it and record it: `trustmebro flag <post> <reason>` appends to `.tmb-flags.md` at the repo root. **Put the dead url in the reason:** `trustmebro check` downgrades a verify failure whose url is flagged to "flagged, known" (not a gate failure), so a correctly-flagged pre-existing dead link still PASSes.4445## What trustmebro is NOT4647Link-hygiene + targeted explanation, NOT a whole-document fact-check. It only inspects what it links; untouched claims ride straight through. **A trustmebro-passed post is NOT a verified-true post.**4849## Dead vs gated (when verifying)5051A non-200 is not automatically dead. Some hosts (crates.io, npm, registries) 403 an anonymous check but load in a browser (bot-gated). Confirm via a non-gated source (a registry's json/index), or `trustmebro verify --crosscheck` (probes the host root), before calling a link dead. A link YOU add must verify clean. A PRE-EXISTING author link that fails is FLAGGED, never auto-stripped; prefer fixing it to its canonical (often live nearby in the same doc), and fix every occurrence (href + visible text).5253## Code mode (the rare code link)5455Know or infer the repo, read a `.tmb` map if present (`name = owner/repo`), or ask. `trustmebro preflight <repo-dir>` reports slug / HEAD / pushed / visibility. Private repo, do not cite it. `trustmebro permalink <repo-dir> <path> <start> [end] [--ref origin/<branch>]` builds a sha-pinned, range-validated link.5657## Setup5859The `trustmebro` script is next to this file. Put it on PATH (`ln -s "$PWD/trustmebro" ~/.local/bin/trustmebro`) or call it by path. Invoke it as `trustmebro` or the short alias `tmb`, the two are identical. Needs `node` (>=18, for built-in `fetch`) and `git` (`gh` optional). No bash/perl/curl, runs on macOS, Linux, and Windows. Two roots: trustmebro operates on **the post's** git repo (where prove / flag / check work). Clone the helper **outside** that repo (or gitignore it), so it does not get committed into the post's tree.6061## Helper reference6263```64trustmebro verify <url> | trustmebro verify - resolves? HTTP code + dead-vs-gated hint + redirect landing (batch: parallel, JSONL). --crosscheck probes the host root.65trustmebro links <file> every link url (md + html href + ref-defs + autolinks + bare), images excluded. --relative also lists relative targets.66trustmebro insert <file> <phrase> <url> safe add: verify url + wrap the FIRST literal match (md or html). errors on 0 (missed add); notes on multiples. no every-occurrence mode.67trustmebro prove <file> [ref] assert ONLY link markup changed vs ref (default HEAD); fails on any prose/text/whitespace edit.68trustmebro lint <file> catch the half-fix (visible text is a url that differs from its href). --fix syncs it.69trustmebro flag <post> <reason> record a dead link / dubious claim (WITH its url) to .tmb-flags.md.70trustmebro check <post> [base] OPTIONAL full audit: verify all links + prove + lint. Offer it, never auto-run, never a gate on adding links.71trustmebro sweep <repo-dir> <base> prove + lint over every changed .md , backstop after a batch run.72trustmebro preflight / permalink (code mode) repo state / sha-pinned permalink.73trustmebro version74```7576Add `--json` for structured output (links / verify / lint / check). To cite or flag a phrase that IS a flag token, end options with `--`: `trustmebro insert post.md -- --fix <url>`.7778**Environment.** `TMB_JOBS` sets batch parallelism for verify / check / sweep (default 16, the one knob with no flag). `TMB_JSON` / `TMB_XCHECK` / `TMB_FIX` / `TMB_REL` mirror `--json` / `--crosscheck` / `--fix` / `--relative`.7980**Works on markdown OR html**, a post, doc, readme, or article (`.md` / `.html`). insert writes a `[markdown](link)` for a `.md` file and an `<a href>` for a `.html` file (it keys off the extension; tell the user if you adapt). **Code regions** trustmebro skips = fenced ` ``` `/`~~~` blocks, inline `` `code` ``, html comments, and html `<pre>` / `<code>` blocks , NOT Markdown's 4-space-indented code blocks. Put code you don't want trustmebro to read/touch in a fenced (or `<pre>`) block. Other parser limits (optional-audit only; eyeball foreign docs): deeply-nested-paren urls, multi-line html anchors, html-entity hrefs, reference-style (`[text][ref]`) link bodies (insert/lint protect inline + html links, not ref-style).
royashbrook