Trustmebro

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

1. 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).
2. 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.
3. 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).
4. 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.
5. 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.
6. 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

1. RESOLVES, public HTTP 200 (trustmebro verify).
2. 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).
3. 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)

1. 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).
2. SUBSTANTIATE, a real tool / library / protocol / stat / quote gets its authoritative page. Where a wrong link does the most damage.
3. 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).