[finding] llms-full.txt emits HTML numeric entities into a plain-text file, and two of them break the markdown link they sit in

Found while implementing #178. Pre-existing on main — the counts below are byte-identical before and after that change, which is how it was spotted.

Notation. This tracker's body sanitizer decodes HTML numeric character references, including inside code fences — the first version of this card was rewritten by it into one where the before and after examples read identically. So throughout this card, AMP stands for one literal ampersand character. AMP#x2A; means the six characters that would otherwise be typed as an ampersand, hash, x, 2, A, semicolon. That behaviour is itself worth knowing about when filing evidence here.

What is on main

The body served at /llms-full.txt contains HTML numeric character references, in text that is not HTML:

entity	character it encodes	occurrences
`AMP#x2A;`	asterisk	58
`AMP#x60;`	backtick	5
`AMP#x29;`	closing parenthesis	4

They come from page.data.getText('processed'), via getLLMText in apps/docs/lib/source.ts.

The authored MDX is plain. content/docs/build/index.mdx:36:

1. **Just exploring?** → Open ObjectOS, start the [AI Builder](/docs/build/ai-builder),
   say *"I need to track customer support tickets ..."*

The served text for that same line, with the entities spelled in the notation above:

1. **Just exploring?** → Open ObjectOS, start the [AI Builder](/docs/build/ai-builderAMP#x29;,
   say AMP#x2A;"I need to track customer support tickets ..."*

Two things happened: the closing parenthesis of the link target became AMP#x29;, and the opening asterisk of the emphasis pair became AMP#x2A; while its closing partner stayed a literal asterisk.

Why it is worth a card

Two effects, one cosmetic and one not.

Cosmetic: an LLM reading this file reads AMP#x2A; literally. It is not markdown emphasis and it is not an asterisk; it is six characters of noise inside a sentence, 58 times. The whole file exists to be read as text by something that will not run it through an HTML parser.

Not cosmetic: where the escaped character is a link's closing parenthesis, the markdown link stops being a link. Two of the four AMP#x29; occurrences do exactly that, both on [AI Builder](/docs/build/ai-builder... — one in content/docs/build/index.mdx, one in content/docs/build/ai-builder.

Both render correctly on the website, because there the entity decodes back to a parenthesis before markdown ever sees it. In llms-full.txt nothing decodes it, so the link is delivered as broken literal text.

These are the only 2 of the 646 link targets in the served body that are not well-formed; the other 644 are fine.

Measured on main @ 6653744, production build, fetched over HTTP.

Shape of the fix

Not obvious enough to prescribe, which is why this is a finding rather than a task. getText('processed') is fumadocs' own pipeline and the escaping happens inside it. Candidates: ask for a different text mode; decode the numeric references on the way out in getLLMText; report it upstream. Worth checking which characters fumadocs escapes and why before picking — a blind decode of every numeric reference would also rewrite one an author typed on purpose.

/llms.txt is unaffected: it emits titles and descriptions from frontmatter, not processed body text.

Out of scope for #178, which changes how URLs in these bodies are spelled and leaves the 2 malformed targets exactly as it found them. #178 is not addressed here.

Reproduce

cd apps/docs && pnpm run build
grep -o 'AMP#x[0-9A-Fa-f][0-9A-Fa-f];' .next/server/app/llms-full.txt.body | sort | uniq -c

(with AMP typed as a literal ampersand)

Generated by Claude Code

Graded: promoted to pm:queue / Bug, finding removed.

Filed as a finding because the fix is not obvious — correct call, and it stays a finding-shaped problem in a Bug-shaped card. Two of 646 link targets are delivered malformed, which is a defect with a measurement, not an observation. The other half (58 asterisks and 5 backticks of literal noise in a file whose entire audience will not run it through an HTML parser) is real but would not on its own have earned a Bug.

The first task is investigation, not a patch

The card names three candidates — a different text mode, decoding on the way out in getLLMText, reporting upstream — and warns that a blind decode would also rewrite a reference an author typed on purpose. That warning is the card's most valuable line and it should govern the dispatch.

So whoever takes this establishes first, before writing anything:

Which characters getText('processed') escapes, and why. *, ` and ) are all markdown-significant — the escaping looks deliberate, aimed at a consumer that will re-parse the text as markdown. If that is what it is, "decode everything" is fighting the pipeline rather than configuring it.
Whether fumadocs offers a text mode that does not escape. Check the installed version's API before assuming it does not.
Why the escaping is asymmetric — the card measured an emphasis pair where the opening asterisk became an entity and the closing one stayed literal. That asymmetry is a clue about where in the pipeline it happens, and any fix that does not explain it is probably treating a symptom.

If the answer turns out to be "report upstream and wait", that is a legitimate outcome — say so with the reproduction rather than shipping a local decode that papers over it.

Scope note

/llms.txt is unaffected (frontmatter titles and descriptions, not processed body text), so this is one route's problem. The file has changed twice today — #178 (9a1a7ad, absolute links) and #196 is queued to change its page order — so read the tree, and expect to sequence against #196 since both land in llms-full.txt/route.ts.

The notation finding is worth more than this card

Buried in the body:

This tracker's body sanitizer decodes HTML numeric character references, including inside code fences — the first version of this card was rewritten by it into one where the before and after examples read identically.

That is the second thing we have learned about this sanitizer today; the first was that it strips angle-bracket markup, including inside fences. A card whose entire subject is character-level escaping was silently rewritten into one that showed no difference between the broken and correct forms — the failure mode being documented, applied to the document describing it.

Inventing the AMP notation to route around it, and stating the convention up front, is the right handling. Recording it here so the next agent filing evidence about escaped characters in this tracker does not lose an hour to it.

Generated by Claude Code

Claim: PM loop round 9
Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-197-llms-full-entity-decode
Worktree: objectos-issue-197
Domain: n/a (objectos carries no domain:* lanes)
File surface: apps/docs/app/llms-full.txt/route.ts, apps/docs/lib/source.ts (getLLMText lives there). Stop on breach; explain in the report.
Container & model: M, mode:subagent, model: opus — PM judgement.
Clause-②: no
Serial constraints cleared: llms-full.txt/route.ts is free — #178 (9a1a7ad) and #196 (1ebd7b7) have both merged. #184 is in flight on .github/scripts/check-locale-surface.mjs and #199 on app/layout.tsx / middleware.ts / lib/seo.ts; neither touches your files.

Read coupling with #184, and it is why the scope line matters: #184 is adding this file's body to the locale-surface gate, asserting which pages and which locales appear. Your change alters the characters inside page text. Those are disjoint — page titles come from frontmatter and never pass through getText('processed') — so the gate will not notice you. But if your fix changes which pages appear, stop and report: that would collide.

Note the file has been rewritten twice in the last two hours. Read the tree.

Generated by Claude Code

Claim (dev): starting investigation.

Session: session_01G5zjYc2BoFV2NjKBBapC7C
Branch: claude/issue-197-llms-full-entity-decode (pushed, empty, at 1ebd7b7)
Worktree: /home/user/objectos-issue-197
Base: 1ebd7b7 — origin/main after #196/#201 landed, so both of today's rewrites of this file are in the tree I am reading.
File surface: apps/docs/app/llms-full.txt/route.ts, apps/docs/lib/source.ts. Stop on breach and report.

Order of work is taken from the grading comment: investigation first, three questions answered before any patch — which characters getText('processed') escapes and why, whether the installed fumadocs has a non-escaping text mode, and what explains the asymmetry the card measured. needs_decision with a reproduction is on the table as a terminal outcome; a blind decode is not.

Following the card's AMP notation for anything I write back here.

Generated by Claude Code

os-dev-report

{
  "issue": 197,
  "status": "needs_decision",
  "branch": "claude/issue-197-llms-full-entity-decode",
  "pr": null,
  "premise_still_valid": true,
  "files_changed": [],
  "gates": "None run: the diff is empty, so there is nothing for a gate to judge. Two full production builds of apps/docs were run instead (baseline and candidate-fix), both through the shared verify lock, both VERDICT command-exit 0.",
  "deviations": [
    "No PR opened. The only repair that addresses the cause needs pnpm.patchedDependencies plus a patches/ file, which is outside the declared file surface (apps/docs/app/llms-full.txt/route.ts, apps/docs/lib/source.ts). Stopped on breach and reported, as instructed.",
    "The candidate fix was proved by patching node_modules, never the repo. The target file is hard-linked into the pnpm store (link count 3), so the directory entry was replaced with mv rather than written through the shared inode (link count 1 after, confirming the store inode was untouched); an EXIT/INT/TERM trap restored it and the restore was verified by sha256 equality with the pre-experiment hash e061d718f43d9ec08ef0e52b41c7a5b8cde84512b94fe133710c90039a8a3246.",
    "Branch claude/issue-197-llms-full-entity-decode was pushed empty as the write-route probe and is left in place at 1ebd7b7 (identical to origin/main). It carries no commits; delete it or reuse it, whichever suits the route chosen."
  ],
  "summary": "NOTATION: AMP stands for one literal ampersand character, per the card's convention, because this tracker's sanitizer decodes numeric character references even inside fences. Investigation only; nothing shipped. The card's premise holds exactly: on origin/main at 1ebd7b7 the served body carries 58 AMP#x2A;, 5 AMP#x60; and 4 AMP#x29; -- the card's counts to the digit. ANSWER 1 (what getText('processed') escapes, and why). Its escaping mechanism is the BACKSLASH, not the character reference. The same served body carries 51 backslash escapes across 7 distinct characters (19 underscore, 15 pipe, 6 backtick, 5 tilde, 3 left angle bracket, 2 ampersand, 1 asterisk). That escaping is deliberate and is aimed at exactly the consumer the grading comment guessed at -- something that will re-parse the text as markdown. The 67 numeric references are NOT that policy. They come from a different function, encodeCharacterReference, reached only through mdast-util-to-markdown's attention-adjacency rule, whose own source comment reads: 'Important: punctuation must never be encoded. Punctuation is solely used by markdown constructs. And by encoding itself. Encoding them will break constructs or double encode things.' The one place a character reference is legitimate for punctuation is a fenced code block's info string (safe() is called there with encode set to backtick); none of the 67 sit in one. The file spells the SAME characters both ways -- asterisk appears as backslash-asterisk and as AMP#x2A;, backtick as backslash-backtick and as AMP#x60; -- which on its own proves the two are not one policy. So 'decode everything' is not fighting the pipeline: all 67 are outside what the pipeline intends, and the pipeline's own intended spelling for them is the backslash. ANSWER 2 (does the installed fumadocs offer a non-escaping text mode). No. Read from node_modules, not from docs: fumadocs-mdx 15.0.7 exposes exactly two modes, getText('raw') (reads the original file off disk -- frontmatter, imports and JSX components included, so not a substitute) and getText('processed'). includeProcessedMarkdown accepts LLMsOptions, which is mdast-util-to-markdown Options plus fumadocs' element filters; there is no escaping switch on it, and any handlers passed through it are wrapped by the very code that causes the defect, so that channel cannot even be used to work around it. There is no configuration route. ANSWER 3 (the asymmetry, and the root cause it points at). fumadocs-core's defaultStringifier wraps every serializer handler (modHandler, dist/mdx-plugins/stringifier.js) and does not carry the handler's .peek property onto the wrapper. mdast-util-to-markdown's containerPhrasing uses handle.peek to obtain the NEXT sibling's first character cheaply and WITHOUT side effects; with peek missing it invokes the next sibling's FULL handler instead, and that lookahead call leaves state.attentionEncodeSurroundingInfo set from node N+1. The loop then reads those flags as though they described node N and applies them to (a) the last character ALREADY EMITTED for sibling N-1 and (b) the first character of sibling N+1. That is the asymmetry, precisely: the emphasis run's OPENING marker is encoded because it is the first character of the following sibling, while its CLOSING marker is left alone because when that node is finally serialized for real its own encodeInfo has true context and correctly asks for no encoding. It also predicts every damaged character in the file, and the prediction holds: each one is either the closing delimiter of a peek-bearing node -- strong (asterisk), link (right parenthesis), inlineCode (backtick) -- or the opening delimiter of an attention run. 58 + 4 + 5 = 67, with nothing left over. THREE CORRECTIONS TO THE CARD, all of which make it worse rather than better. (a) FOUR link targets are malformed, not two, out of 650, not 646. The card's 646 looks like its well-formed count used as the denominator: 646 well-formed + 4 broken = 650. The four are content/docs/build/index.mdx:36, content/docs/build/interface/dashboards.mdx:214 (the card said 'content/docs/build/ai-builder'), content/docs/configure/mcp.mdx:7 and content/docs/resources/faq.mdx:212. All four are ordinary authored links in plain MDX; in every case the trigger is the attention run immediately following. (b) This is NOT one route's problem. /llms.mdx/docs/[[...slug]] prerenders 79 per-page bodies and they carry the identical 58/5/4, because both routes go through getLLMText and therefore through getText('processed'). The grading comment's scope note is right that /llms.txt is unaffected (frontmatter only) but /llms.mdx is affected. A fix in llms-full.txt/route.ts would repair one route; a fix in lib/source.ts would repair both. (c) The defect is quietly defeating a fix that already shipped. SITE_LINK in llms-full.txt/route.ts needs a literal right parenthesis to match, so the two broken SITE links were invisible to #178's absolute-URL rewrite and are served RELATIVE in a file whose whole purpose is to be read elsewhere. Repairing the entity bug raises absolute site targets from 549 to 551 with no other link touched. WHY NOTHING SHIPPED. The cause is one missing line in fumadocs-core 16.8.12, and it is still present in 16.15.1, the current latest -- that function is byte-identical to the installed one apart from a brace reformat -- so 'upgrade' is not a fix and 'report upstream and wait' has no bounded end. Repairing the cause from this repo means pinning the upstream one-liner with pnpm.patchedDependencies, which is outside the declared file surface. The only in-surface repair is an output decode, and the card's warning about it is real and now demonstrated rather than asserted: an author-typed numeric reference in PROSE is decoded at parse time and re-serialized as a backslash escape, so it can never reach the output and a decoder could not hurt it -- but inside inline code and fenced code it survives VERBATIM, and a decode would rewrite it. Worse, the bug itself destroys inline-code closing delimiters (the served body contains backtick-thank-you-AMP#x60;), so a 'skip code spans' guard would be keying on structure the bug has already broken. content/docs carries 0 author-typed numeric references in English MDX today, so that hazard is prospective rather than present -- but it would be a permanent output-rewriting step in this repo, guarding against a bug we could instead delete.",
  "tests": "All measurements on worktree /home/user/objectos-issue-197 at BASE 1ebd7b7 (origin/main, after #178/9a1a7ad and #196/1ebd7b7 both landed). Heavy commands via bash /home/user/objectstack/scripts/pm/os-verify-lock.sh -c '...'. (1) BASELINE BUILD. 'cd apps/docs && NODE_OPTIONS=--max-old-space-size=4096 pnpm run build' -- 'os-verify-lock: VERDICT command-exit 0 . held the lock 57s . waited 0s'. Card's reproduction on .next/server/app/llms-full.txt.body: 58 AMP#x2A;, 5 AMP#x60;, 4 AMP#x29;, 0 decimal references -- identical to the card, so premise_still_valid true. Link targets: 650 occurrences of right-bracket-left-paren, 646 well-formed, 4 malformed. Backslash escapes in the same body: 51 across 7 characters. Same three counts (58/5/4) in all 79 prerendered /llms.mdx/docs bodies. Authored numeric references in English content/docs MDX: 0 files. (2) ISOLATED REPRODUCTION, no MDX and no Next in the loop: fromMarkdown + micromark gfm, then fumadocs-core's own defaultStringifier called with a stub processor supplying gfmToMarkdown. Emits all three entity kinds on a 12-line input -- 'Talk to the AI Builder*AMP#x2A;', '(/docs/build/ai-builderAMP#x29;,', 'backtick-thank-you-AMP#x60; AMP#x2A;(default)*'. This pins the defect to the stringifier, not to MDX, not to fumadocs-mdx, not to this repo. (3) A/B ON THE HYPOTHESIS. Same function re-declared verbatim with one line added -- copy handler.peek onto the wrapper -- run over the same input twice in one process: PRESERVE_PEEK=false gives refs [AMP#x2A;, AMP#x2A;, AMP#x29;, AMP#x2A;, AMP#x60;, AMP#x2A;]; PRESERVE_PEEK=true gives refs []. Output otherwise identical apart from table column widths. (4) END-TO-END ON THE REAL SITE. Mutation: the anchor line 'for (const k in handlers) handlers[k] = modHandler(handlers[k], node.ctx);' occurs exactly once in fumadocs-core/dist/mdx-plugins/stringifier.js; replaced with a form that copies .peek. MUTATION CONFIRMED ON DISK BEFORE THE BUILD, not by an editor's exit code: grep -c of the removed anchor text = 0 and grep -c of the injected marker '__w.peek = __h.peek' = 1, read back from the installed path. The file is hard-linked into the pnpm store (stat link count 3), so the directory entry was replaced with mv rather than written through the shared inode; link count 1 afterwards confirms the store inode was never touched, i.e. no sibling worktree and no future install was poisoned. .next removed so nothing was served from cache, then rebuilt: 'os-verify-lock: VERDICT command-exit 0 . held the lock 57s . waited 0s'. RESTORE LEG: an EXIT/INT/TERM trap invoking an absolute-path restore script ran and printed 'RESTORE OK'; independently re-verified afterwards, sha256 of the installed file = e061d718f43d9ec08ef0e52b41c7a5b8cde84512b94fe133710c90039a8a3246 = the pre-experiment hash, and git status in the worktree is empty with an empty diff against BASE. (5) RESULTS OF THE CANDIDATE FIX, measured on the rebuilt body. Numeric references 67 -> 0. Link targets 650 total in both; well-formed 646 -> 650; malformed 4 -> 0. Membership and order from #196 UNTOUCHED: the sequence of every top-level heading line is byte-identical between the two bodies (93 headings, same order), and the line count is identical (12835). Otherwise byte-identical apart from the decoded characters, checked by decoding the baseline and diffing: 21 differing lines, of which 19 are GFM table column padding (a cell that loses 5 characters narrows its whole column, so the padding of every row is recomputed) and exactly 2 are the AI Builder links acquiring the absolute URL that #178 had been unable to give them -- absolute site targets 549 -> 551. (6) AUTHOR-TYPED REFERENCE PROBE, which is what makes the card's warning concrete. Through the same stringifier: in prose, an authored reference is decoded at parse time and comes back out as a backslash escape (never as an entity); inside inline code and inside a fenced block it survives verbatim, 4 of 4 in the probe. So a decode is safe against today's content and unsafe against a page that documents character references.",
  "open_questions": [
    {
      "question": "The cause is a one-line omission in fumadocs-core (modHandler in dist/mdx-plugins/stringifier.js does not carry Handle.peek onto the wrapper), it is present in the current latest release 16.15.1 as well as the installed 16.8.12, and the fix for it is outside the file surface I was given. Which route should this repo take?",
      "options": [
        "A -- Pin the upstream one-liner with pnpm.patchedDependencies (a patches/ file plus a pnpm-workspace.yaml entry) and file it upstream in parallel. Fixes the cause once, for llms-full.txt and llms.mdx and any future consumer of getText('processed'). Verified end-to-end above: 0 references, 650/650 link targets, membership and order untouched. Cost: two files outside my surface, and the pin must be re-checked on each fumadocs bump (it deletes itself on the release that carries the fix).",
        "B -- Targeted decode inside getLLMText in lib/source.ts (in surface), restricted to numeric references whose code point is ASCII punctuation -- justifiable character by character, because the serializer's own invariant is that punctuation is never encoded, and the only legitimate punctuation reference (a backtick in a fenced block's info string) does not occur here. Cost: a permanent output-rewriting step; it needs a code-span and fence guard, and the bug itself destroys inline-code closing delimiters, so that guard keys on structure the bug has already broken; and it leaves the cause in place for anything that reads getText('processed') without going through getLLMText.",
        "C -- Report upstream and wait, changing nothing here. Cost: unbounded, because the defect is in the newest release, not only in the pinned one. Four link targets stay broken and two stay relative in the meantime."
      ],
      "recommendation": "A, with the upstream report filed at the same time; do not decode. Real business need: measured, not speculative -- 4 of 650 link targets malformed in a file whose entire audience is a machine that will not run it through an HTML parser, plus 2 links silently exempted from the absolute-URL rewrite that #178 shipped for this very file, plus 58 asterisks and 5 backticks of literal noise, and all of it duplicated across the 79 per-page /llms.mdx bodies. Long-term soundness: the contract-first rule says a defect that tempts you to widen the consumer belongs in the producer, and B is exactly the tolerant-consumer shape that rule names; A is byte-identical to what upstream will ship and disappears on the release that carries it, whereas B is code this repo owns forever. Making AI-written material hard to get wrong: this file is read by machines, and A restores well-formed markdown at the source so no downstream consumer has to know the quirk exists, while B leaves a decode step that every future reader of getText('processed') has to remember to replicate -- and the one place B could go wrong is a page documenting character references, which is a page a docs site is unusually likely to acquire. Startup scope discipline: A is one pinned line and no new logic; B is new permanent logic plus a guard whose correctness is genuinely hard to argue. A is less code, not more. If the pin is judged too much machinery for two broken links, C is defensible and B is not -- B costs more than A and fixes less."
    }
  ],
  "out_of_scope_findings": []
}

Generated by Claude Code

Investigation ACCEPTED. needs_decision is the correct terminal outcome — and this is the best report of the run. Routing to the maintainer.

(NOTATION: AMP stands for one literal ampersand, per this card's convention, because this tracker's sanitizer decodes numeric character references even inside fences.)

The cause, found rather than guessed

fumadocs-core's defaultStringifier wraps every serializer handler through modHandler and does not carry Handle.peek onto the wrapper. mdast-util-to-markdown's containerPhrasing uses peek to read the next sibling's first character cheaply and without side effects; with peek missing it invokes that sibling's full handler instead, and the lookahead leaves state.attentionEncodeSurroundingInfo set from node N+1. The loop then applies those flags to node N.

That is the asymmetry I flagged in the grading comment as "a clue about where in the pipeline it happens, and any fix that does not explain it is probably treating a symptom." It was the clue. The opening marker is encoded because it is the first character of the following sibling; the closing one is untouched because when that node is finally serialized for real, its own encodeInfo has true context.

And it predicts every damaged character with nothing left over: 58 + 4 + 5 = 67, each either the closing delimiter of a peek-bearing node or the opening delimiter of an attention run. A root cause that accounts for the entire population, not most of it.

The A/B is what makes it a finding rather than a story: the same function re-declared verbatim with one line added, run over the same input twice in one process — PRESERVE_PEEK=false emits six references, PRESERVE_PEEK=true emits none, output otherwise identical.

Three corrections to my card. I got all three wrong; take the report's numbers.

(a) Four malformed link targets, not two — out of 650, not 646. My denominator was the well-formed count: 646 + 4 = 650. The card also named content/docs/build/ai-builder for what is actually content/docs/build/interface/dashboards.mdx:214.

(b) My scope note was wrong, and it was the load-bearing line of the grading comment. I wrote "this is one route's problem." It is not. /llms.mdx/docs/[[...slug]] prerenders 79 per-page bodies carrying the identical 58/5/4, because both routes reach getText('processed') through getLLMText. A fix in llms-full.txt/route.ts repairs one route; a fix in lib/source.ts repairs both. My scope note would have produced a fix that left 79 pages broken and looked complete.

That is the second time today a grading comment of mine has shipped a wrong mechanism assumption to a dev, and the second time a dev has measured instead of complying. It is worth naming the pattern: the file surface I grant is a constraint, not a finding — when it disagrees with the measurement, the measurement wins and the card gets corrected.

(c) The best item in the report, and it changes the impact calculus. SITE_LINK in llms-full.txt/route.ts needs a literal right parenthesis to match. The two links whose closing parenthesis the bug had already turned into AMP#x29; were therefore invisible to #178's absolute-URL rewrite, and are served relative in a file whose entire purpose is to be read somewhere else. Repairing the entity bug raises absolute site targets 549 → 551 with no other link touched.

So this is not 63 characters of cosmetic noise. Two fixes we merged today interact silently, and the older one has been quietly incomplete since it landed. Nothing would ever have reported that.

Method note

The end-to-end proof mutated an installed file, and the dev treated the pnpm store as the shared resource it is: link count read before (3) and after (1), the directory entry replaced with mv rather than written through the shared inode, an EXIT/INT/TERM trap for the restore, and the restore verified by sha256 equality rather than by an exit code. This session has already lost work once to shared state that looked local. Checking the link count before writing is exactly the habit that prevents it.

Equally: "confirmed on disk before the build" — the anchor's absence and the marker's presence both read back from the installed path, rather than trusting an editor's exit code.

Why this needs the maintainer

The cause is one missing line in fumadocs-core, and it is present in 16.15.1, the current latest, not only in the installed 16.8.12. So "upgrade" is not a fix, and "report upstream and wait" has no bounded end. Fixing the cause from this repo means pnpm.patchedDependencies plus a patches/ file — outside the granted surface, which is why the dev stopped and reported. Correct call; that boundary is the one I ask devs to respect.

My recommendation: A (pin the upstream one-liner, file upstream in parallel). Do not decode.

The argument that decides it is not elegance, it is that B is unsound, not merely permanent. A decode needs a code-span guard — and the bug destroys inline-code closing delimiters (the served body contains a backtick span closed by AMP#x60;), so that guard would key on structure the bug has already broken. B costs more than A and fixes less. If the pin is judged too much machinery for this, C is defensible; B is not.

One interaction the decision needs: #160 is the pending Dependabot bump of this exact package (16.8.12 → 16.14.5). The dev measured the target function as byte-identical in the newer release apart from a brace reformat — which means a patch pinned today will fail to apply on that bump rather than silently mis-apply. That is the behaviour you want, but it makes #160 a regeneration task, not a merge. Noting it on #160 either way.

Labelling needs-user-decision, removing pm:dispatched, unassigning. Not dispatching anything on this card until the route is chosen.

Housekeeping

claude/issue-197-llms-full-entity-decode is pushed empty at 1ebd7b7 — leaving it in place; whichever route is chosen can reuse it.

#203 unblocks now. It was serialized behind this card on the expectation that #197 would rewrite llms-full.txt/route.ts; the diff is empty, so the constraint is gone.

Generated by Claude Code

Decided by the maintainer: Route A

Pin the upstream one-liner with pnpm.patchedDependencies, and file the bug upstream in parallel. The upstream report is part of A, not a follow-up — the patch is meant to delete itself on the release that carries the real fix, and that release only exists if someone reports it.

Removing needs-user-decision. This card is now implementable.

(NOTATION: AMP stands for one literal ampersand, per this card's convention — this tracker's sanitizer decodes numeric character references even inside fences.)

What is being patched

fumadocs-core, dist/mdx-plugins/stringifier.js: defaultStringifier wraps every serializer handler through modHandler and does not carry Handle.peek onto the wrapper. mdast-util-to-markdown's containerPhrasing then loses its side-effect-free lookahead, invokes the next sibling's full handler instead, and applies the resulting attentionEncodeSurroundingInfo to the wrong node.

One line. The investigation on this card measured it both in isolation (same function re-declared with the line added: six references become zero) and end-to-end against a real build.

Expected effect, already measured

numeric character references: 67 → 0
malformed markdown link targets: 4 → 0, out of 650
absolute site targets: 549 → 551 — two links that [finding] llms.txt and llms-full.txt emit site-relative links, so the map only resolves for a fetcher that remembers where it fetched from #178's absolute-URL rewrite could never match, because SITE_LINK needs a literal closing parenthesis and this bug had already turned theirs into AMP#x29;
page membership and order untouched: 93 headings byte-identical in sequence, identical line count

Scope: the producer, so both consumers

The fix belongs in the producer, which means it repairs /llms-full.txt and the 79 per-page /llms.mdx bodies together.

⚠️ The scope note in this card's body is wrong and was corrected in the grading comment above. It says "/llms.txt is unaffected … so this is one route's problem." /llms.txt is indeed unaffected (frontmatter only), but /llms.mdx is not — both routes reach getText('processed') through getLLMText. A fix scoped to llms-full.txt/route.ts would repair one route, leave 79 pages broken, and look complete.

Likewise the body's "two of 646 link targets": it is four of 650. 646 was the well-formed count used as the denominator.

The patch does not expire on the next bump

The defect is present in 16.15.1, the current latest as measured, not only in the installed 16.8.12. So "upgrade" was never a fix, and the pin stays until upstream lands the change.

#160 is a regeneration task, not a merge

This is the operational consequence to carry. #160 bumps this exact package, 16.8.12 → 16.14.5. The target function is byte-identical in the newer release apart from a brace reformat — so a patch generated against 16.8.12 will fail to apply, loudly, rather than mis-apply silently.

That is the behaviour you want from a pin, and it means #160 cannot be merged on green: the patch must be regenerated against the new version in the same PR. Noted on #160 already.

Housekeeping

claude/issue-197-llms-full-entity-decode is pushed empty at 1ebd7b7 — it carries no commits and can be reused or deleted.

The investigation that produced this decision proved the fix by patching node_modules hard-link-aware (link count read before and after, directory entry replaced with mv rather than written through the shared pnpm-store inode, restore verified by sha256 against the pre-experiment hash). Whoever implements A does not need to repeat that — the patches/ file is the durable form of the same change.

Generated by Claude Code

Claim: PM loop, repo:objectos seat, round 5 of this tenure
Session: session_01ChPQM8jamxLUfUAxwFpJ8S
Branch: claude/issue-197-fumadocs-peek-patch
Worktree: objectos-issue-197-patch
Base: origin/main @ 50aacb9 — not the 1ebd7b7 the investigation read. Nine commits have landed since (#265's cache fix, #275's size gate, #276, #278's pre-merge render gate). Re-measure the baseline in your own tree; do not carry the investigation's counts forward as current.

Route A is decided (maintainer's comment). This dispatch implements it. It is not a re-investigation — the cause, the A/B and the end-to-end measurement are already on this card and stand. What is unproven is that the durable form of the same one-line change behaves the same way.

File surface: patches/ (new file), the manifest that carries pnpm.patchedDependencies (read the installed pnpm's major version and put it where that version puts it — pnpm 10 moved it to pnpm-workspace.yaml; the repo has no patches/ dir and no such key today, so there is no local precedent to copy), pnpm-lock.yaml. apps/docs/lib/source.ts is out of surface — Route A fixes the producer, so no consumer file should need to change. If you find yourself editing source.ts or llms-full.txt/route.ts, stop and report: that means Route A is not doing what it was chosen to do.

Clause-②: no.

Serial constraints and read-coupling

#277 is in flight on .github/workflows/ci.yml — disjoint files, but not disjoint readings. Your patch changes what the bundle contains, and #275's size gate weighs wrangler deploy --dry-run's Total Upload: against a 61440 KiB budget on every PR. Expect your Total Upload: to differ from main's. Two consequences:

If the gate goes red, that is a real signal about your change, not gate noise — report it, do not raise the budget.
If it goes green with a small delta, say what you measured and stop there. The Worker size gate's reading moves by a few KiB between builds of bundle-identical trees, so small per-PR deltas cannot be attributed #277 is on this repo's board precisely because a few-KiB move between two different commits has not been shown to be a change in the bundle at all. Do not narrate a delta as growth or shrinkage.

#239 (Dependabot, fumadocs-core 16.8.12 → 16.15.2) is open and this dispatch changes its meaning. Correction to the decision comment, which says the consequence was "noted on #160 already": #160 is closed — Dependabot superseded it on 08-29 with #239, to a different target version (16.15.2, not 16.14.5). The regeneration note is therefore recorded on a closed PR and reaches nobody. I am carrying it to #239 myself; you do not need to.

The half the report cannot skip

The investigation proved the fix by mutating node_modules under a restore trap. A patches/ file is a different mechanism reaching the same source line, and the thing that makes it worth pinning is that it survives pnpm install. So the acceptance bar is:

The patch applies on a clean install, demonstrated by an install that had no prior patched state — not by the tree you already have.
The counts, re-measured on 50aacb9 before and after, with the before-figure taken in your own tree: numeric character references, malformed link targets out of the total, and absolute site targets. The decision quotes 67→0, 4→0 of 650, 549→551. If any before-figure differs from those, the tree moved under the investigation and I want the new number, not the quoted one.
The 79 /llms.mdx per-page bodies too, not only /llms-full.txt. That was the load-bearing correction on this card: a fix that repairs one route and leaves 79 pages broken looks complete.
A negative control. Show the patch can fail: an install with the patch removed (or the anchor perturbed) must put the references back / refuse to apply. A patch step that cannot fail is indistinguishable from one that applied.

The upstream report is part of Route A, and you cannot file it

This session's GitHub access is scoped to objectstack-ai/*. You cannot open an issue on fuma-nama/fumadocs. So write the report as a ready-to-post body in a comment on this card — the anchor line, the two-run A/B, the affected releases (16.8.12 and 16.15.1 both measured; check whether 16.15.2 still carries it, since that is what #239 would install), and the one-line fix. I will route the filing to the maintainer. Reference that pending filing in the patch file's own header comment so the next person to touch it knows why the pin exists and when it can be deleted.

⛔ Do not touch content/docs/. ⛔ Do not raise the size budget. ⛔ Report a falsified premise rather than making a number come out right.

Generated by Claude Code

Upstream report, ready to post — `fuma-nama/fumadocs`

Route A includes filing this upstream; this session's GitHub access is scoped to objectstack-ai/*, so here is the body for the maintainer to route.

⚠️ Before posting it upstream, replace every literal AMP with one ampersand character. This tracker's body sanitizer decodes HTML numeric character references, including inside code fences, so they cannot be written literally here. Everything else is verbatim.

The reproduction below was run in this container against a clean npm i fumadocs-core@16.15.2 — a throwaway install, not this repo's tree — so it stands on its own.

Title: defaultStringifier drops Handle.peek when wrapping handlers, so toMarkdown encodes markdown punctuation as character references

Body:

What happens

defaultStringifier (dist/mdx-plugins/stringifier.js, src/mdx-plugins/stringifier.ts) wraps every mdast-util-to-markdown serializer handler through modHandler. The wrapper does not carry the handler's peek property:

for (const k in handlers) handlers[k] = modHandler(handlers[k], node.ctx);

mdast-util-to-markdown's containerPhrasing uses Handle.peek to obtain the next sibling's first character cheaply and without side effects (lib/util/container-phrasing.js: if (handle && handle.peek) handle = handle.peek). With peek missing on the wrapper, that lookahead invokes the sibling's full handler instead, and the call leaves state.attentionEncodeSurroundingInfo set from node N+1. The loop then reads those flags as if they described node N and applies them to the last character already emitted for N-1 and to the first character of N+1.

The visible result is that markdown punctuation — the closing ) of a link, the closing backtick of an inline code span, the opening * of an attention run — comes out as an HTML numeric character reference. mdast-util-to-markdown's own comment on encodeCharacterReference says this must not happen: "Important: punctuation must never be encoded. Punctuation is solely used by markdown constructs. And by encoding itself. Encoding them will break constructs or double encode things."

It is also visibly asymmetric, which is the tell: an emphasis run's opening marker is encoded while its closing partner is untouched, because the closing one is encoded from its own node's true context when that node is finally serialized for real.

Reproduction

npm i fumadocs-core@16.15.2 mdast-util-from-markdown
node repro.mjs

import { fromMarkdown } from 'mdast-util-from-markdown';
import { defaultStringifier } from 'fumadocs-core/mdx-plugins/stringifier';

const INPUT = [
  'Start the [AI Builder](/docs/build/ai-builder), say *"track tickets"*.',
  '',
  'Use the `set_active_package` tool when you say something like *"Switch to X"*.',
  '',
  'Talk to the **AI Builder** — *"I need this"*.',
].join('\n');

const out = defaultStringifier().call(undefined, fromMarkdown(INPUT), {});
console.log(out);

Output, as shipped:

Start the [AI Builder](/docs/build/ai-builderAMP#x29;, say AMP#x2A;"track tickets"*.

Use the `set_active_packageAMP#x60; tool when you say something like AMP#x2A;"Switch to X"*.

Talk to the **AI Builder*AMP#x2A; — AMP#x2A;"I need this"*.

Six numeric character references, and the first line is no longer a markdown link: the target now ends in AMP#x29; rather than ).

The fix, one line

Carry peek onto the wrapper:

for (const k in handlers) {
  const h = handlers[k];
  const w = modHandler(h, node.ctx);
  if (h.peek) w.peek = h.peek;
  handlers[k] = w;
}

A/B, same input, one process

stringifier.fixed.js is a verbatim copy of the shipped dist/mdx-plugins/stringifier.js with only the five lines above in place of the one-line loop. Both are imported into the same process and run over the same input:

=== PRESERVE_PEEK=false (as shipped) ===
numeric character references: 6  AMP#x29; AMP#x2A; AMP#x60; AMP#x2A; AMP#x2A; AMP#x2A;

=== PRESERVE_PEEK=true  (one line added) ===
numeric character references: 0

With the line added the output is byte-identical to the input (asserted in the run, not eyeballed). Nothing else in the output changes.

Affected releases

Checked by unpacking the published tarballs on 2026-09-08. In each, the anchor line above occurs exactly once and the string peek does not occur in the file at all:

version	anchor line	`peek` anywhere in the file
16.8.12	1	0
16.15.1	1	0
16.15.2	1	0
16.15.8 (`latest` on that date)	1	0

The only difference in this file between 16.8.12 and 16.15.x is an unrelated brace reformat of the extraInfo if, two hunks above.

Why it matters downstream

getText('processed') is what a docs site serves to machine readers. On ours it put 67 character references into /llms-full.txt and into each of 79 per-page /llms.mdx bodies, and delivered 4 of 661 markdown link targets malformed — in files whose entire audience will not run them through an HTML parser. Two of those broken targets also slipped past our own absolute-URL rewrite, because that rewrite needs a literal closing parenthesis to match.

Not part of the upstream body — for this card

Also measured while checking the releases: whatever version #239 lands on, the pin is keyed to 16.8.12 and simply will not be applied to any other version, so the defect returns silently unless the patch is regenerated in that same PR. That is recorded in the patch file's own header and in the PR body.

Generated by Claude Code

os-dev-report

{
  "issue": 197,
  "status": "done",
  "branch": "claude/issue-197-fumadocs-peek-patch",
  "pr": "https://github.com/objectstack-ai/objectos/pull/281",
  "premise_still_valid": true,
  "files_changed": [
    "patches/fumadocs-core@16.8.12.patch (new, 86 lines: a 63-line header comment plus the one-hunk diff)",
    "package.json (pnpm.patchedDependencies, 3 lines added)",
    "pnpm-lock.yaml (patchedDependencies block plus patch_hash annotations, +13/-8)"
  ],
  "gates": "All exit 0 on the final tree at 5ce94d3, verdicts read from each command's own output, never from a bare $? after a pipe. pnpm install --frozen-lockfile on a wiped node_modules (what CI runs); check-node-floor.mjs --self-test (17 rule + 24 satisfies + 18 range cases) and the real scan (430 engines blocks, floor 22.0.0); scripts/pm/check-half-states.mjs --self-test (1551 cases); apps/docs/scripts/gen-zh-hant.mjs --check (73 generated files byte-identical); pnpm turbo run type-check --continue; pnpm turbo run build; check-locale-surface.mjs (409 sitemap URLs, 0 unexpected / 0 missing, both llms bodies carry all 60 en-only titles and none from other locales); pnpm turbo run test --force (7 self-tests, 8 fixtures, all 7 rules demonstrated able to fail; --force because the first run replayed a turbo cache hit); opennextjs-cloudflare build --skipNextBuild plus wrangler deploy --dry-run; and #278's pre-merge render check, smoke-docs.mjs against a local opennextjs-cloudflare preview -- 4 pages rendered and its own negative control tripped red. Heavy runs went through bash /home/user/objectstack/scripts/pm/os-verify-lock.sh; every VERDICT line read command-exit 0.",
  "deviations": [
    "MANIFEST PLACEMENT. The dispatch expected pnpm.patchedDependencies in pnpm-workspace.yaml because pnpm 10 moved settings there. The installed pnpm (10.28.2) put it in the root package.json instead, inside the pnpm block that already carries onlyBuiltDependencies -- that is pnpm patch-commit's own choice, not mine. I left it where the tool wrote it and verified it end to end through a wiped --frozen-lockfile install, which is the behaviour the dispatch said to follow over any local precedent.",
    "THREE BASELINE FIGURES MOVED under the investigation and I am reporting the new ones. Link targets in the served body are 661, not the 650 the decision comment quotes, and absolute site targets 560, not 549 -- eleven on-site links have landed in content/docs since 1ebd7b7. The malformed count (4) and every reference count (67; 58 asterisk, 5 backtick, 4 closing parenthesis) are unchanged, and the absolute-target figure still moves by exactly +2.",
    "SIZE-GATE READING, stated without a delta claim. Three wrangler deploy --dry-run readings in this container: 58549.15 KiB with the pin removed, 58544.59 KiB on this branch built with pnpm run build, 58544.37 KiB on this branch built with pnpm turbo run build. All far under the 61440 KiB budget (about 2895 KiB headroom); the gate is green. The two readings of the SAME branch differ by 0.22 KiB, so I claim no direction for the cross-state gap and did not touch the budget.",
    "I ran two gates the dispatch did not name -- the Worker packaging plus size weigh-in, and #278's pre-merge render check -- because this change alters what the site serves and both are CI steps rather than pnpm run scripts. Both green.",
    "The pnpm patch edit directory and the isolated upstream reproduction live under the session scratchpad at /tmp/claude-0/-home-user/9bd2d956-ef28-5e84-ba52-81dd45260916/scratchpad/issue-197/, never in a repo tree. The reproduction is its own throwaway npm install of fumadocs-core@16.15.2, so it touched neither this worktree's node_modules nor the shared pnpm store."
  ],
  "summary": "NOTATION: AMP stands for one literal ampersand, per this card's convention. Route A implemented as decided: patches/fumadocs-core@16.8.12.patch carries .peek from each serializer handler onto the wrapper modHandler builds, pinned through pnpm.patchedDependencies. No consumer file was touched -- lib/source.ts and llms-full.txt/route.ts are byte-unchanged, which is the outcome Route A was chosen for. The premise holds: the cause, the anchor line and the mechanism are exactly as the card describes, the anchor occurs once in the installed file, and one line fixes it. What was unproven and is now measured is the durable form: the patch applies on an install that had no prior patched state, and the installer's own artefacts say so -- the virtual store directory it resolved to is named fumadocs-core@16.8.12_patch_hash=042796c0..., and the installed file, resolved through apps/docs' own module resolution, carries the injected line at line 81 and the pristine anchor 0 times. Effect at base 50aacb9, re-measured in this tree, and identical in BOTH consumers: numeric character references 67 to 0 in /llms-full.txt and 67 to 0 across the 79 /llms.mdx per-page bodies; malformed link targets 4 to 0 of 661; absolute site targets 560 to 562, the two AI Builder links whose closing parenthesis the bug had turned into AMP#x29; so SITE_LINK could never match them. Membership and order untouched: 93 top-level page headings byte-identical in sequence, all 799 heading lines byte-identical in sequence, identical line count. The upstream report Route A requires is posted as a ready-to-post body on this card (comment 5592063362) with the AMP substitution rule stated, since this session cannot open an issue on fuma-nama/fumadocs; the patch file's header points at it and states the deletion condition. Checked for the report: the defect is present in 16.8.12, 16.15.1, 16.15.2 (what #239 would install) and 16.15.8 (latest on 2026-09-08) -- anchor line present once, the string peek absent from the file, in all four.",
  "tests": "All measurements in worktree /home/user/objectos-issue-197-patch, BASE 50aacb9, final commit 5ce94d3; the gate union above was re-run on that same head. (1) HARNESS. One node script, identical before and after, reading the built bodies off apps/docs/.next/server/app -- llms-full.txt.body and all 79 .body files under llms.mdx/. It counts numeric character references by kind, link openers, well-formed targets (an opener whose target closes with a literal right parenthesis before any whitespace), and absolute site targets. (2) BEFORE, unpatched at 50aacb9, .next removed first: /llms-full.txt 695176 bytes, 67 references (58 AMP#x2A;, 5 AMP#x60;, 4 AMP#x29;), 661 link targets of which 657 well-formed and 4 malformed, 560 absolute site targets; the 79 /llms.mdx bodies carry the identical 67 and 4-of-661 across 29 damaged pages. (3) AFTER, patched, .next removed first: 694779 bytes, 0 references, 661 of 661 well-formed, 0 malformed, 562 absolute; the 79 /llms.mdx bodies 0 references, 0 malformed, 0 damaged pages. Reproduced identically by a second build of the same tree (NEXT_PRIVATE_STANDALONE, as CI sets) -- the two after-bodies are byte-identical (cmp). (4) MEMBERSHIP AND ORDER. 93 top-level heading lines byte-identical in sequence (cmp), 799 heading lines byte-identical in sequence (cmp), line count 12923 both sides. Decoding the before body's references and diffing against the after body leaves 21 differing lines, classified mechanically: 19 differ only in runs of spaces and table-rule dashes (GFM column repadding, since a cell that loses 5 characters narrows its column) and 2 are the AI Builder links acquiring the absolute URL. 0 lines fall outside those two classes. (5) CLEAN-INSTALL PROOF. node_modules removed in all three workspace projects, then pnpm install --frozen-lockfile -- exit 0. pnpm 10.28.2 prints no patch-applied line on success, so the evidence is read off disk afterwards, not from an exit code: the resolved directory name carries the installer's own patch_hash= segment, grep finds 'if (handler.peek) wrapped.peek = handler.peek;' at line 81, and grep finds the pristine anchor 0 times. Repeated from a fully wiped node_modules three separate times (after patch-commit, after the header was added, and after the negative controls) with the same result. (6) NEGATIVE CONTROL A, the pin removed: pnpm.patchedDependencies deleted from package.json (removal confirmed by reading the file back, 0 occurrences), node_modules wiped, install exit 0 -- and the installed file then carries the pristine anchor once and the peek line 0 times. A full rebuild puts the defect back at exactly the baseline figures: 695176 bytes, 67 references, 4 of 661 malformed. So the mechanism can fail, and the fix is what is doing the work. (7) NEGATIVE CONTROL B, the anchor perturbed: one character changed in the patch's removed-context line (node.ctx to node.CTX), the change confirmed on disk by git hash-object before and after (c9ebf2a1 to f4bd6a7f) and by counting both the removed and the injected text, node_modules wiped, pnpm install exits 1 with ERR_PNPM_PATCH_FAILED Could not apply patch. So the install step is genuinely reading and applying this file rather than passing regardless. BOTH failure modes were demonstrated, which the acceptance bar asked to be stated plainly. (8) RESTORE LEGS, treated with the same suspicion as the mutation legs. Both controls restored via git checkout HEAD -- PATH (never a bare git checkout -- PATH, which restores from a possibly-poisoned index) under a trap on EXIT INT TERM with absolute paths, and each restore verified by git diff HEAD being empty and git status being clean, not by an exit code. The implementation was committed BEFORE either control ran, so HEAD was a real restore point rather than the pre-fix tree. (9) ISOLATED UPSTREAM REPRODUCTION, in a throwaway npm install of fumadocs-core@16.15.2 (not this repo's tree, not the pnpm store): the shipped defaultStringifier emits 6 references on a 5-line input -- AMP#x29; AMP#x2A; AMP#x60; AMP#x2A; AMP#x2A; AMP#x2A;, all three kinds. A verbatim copy of the same dist file with only the one line added, imported into the SAME process and run over the SAME input, emits 0, and its output is byte-identical to the input (asserted in the run). (10) RELEASE SWEEP by unpacking published tarballs: 16.8.12, 16.15.1, 16.15.2 and 16.15.8 each carry the anchor line exactly once and contain the string peek zero times in that file; the only difference between 16.8.12 and 16.15.x there is an unrelated brace reformat two hunks above.",
  "mcp_calls": "7",
  "open_questions": [],
  "out_of_scope_findings": [
    "NOT FILED, deliberately -- it belongs to open PR/issue #277, which is in flight on exactly this question, and filing a second card would split it. Two wrangler deploy --dry-run readings of the SAME commit and the SAME node_modules in this container differ by 0.22 KiB (58544.59 vs 58544.37 KiB); the only difference between them is whether .next came from pnpm run build or pnpm turbo run build. That is a measured instance of the size gate's reading moving without the bundle changing, which is the thing #277 is trying to establish. Handing it to the PM to carry there rather than filing it."
  ]
}

Generated by Claude Code

Accepted and merged as 6505ac1. pm:dispatched cleared by hand. Route A implemented as decided, with no consumer file touched — which is the outcome Route A was chosen for, so that is the result to check first and it holds: lib/source.ts and llms-full.txt/route.ts are byte-unchanged, and the whole diff is three files (patches/, package.json, pnpm-lock.yaml).

What I verified against GitHub rather than the report

The patch is the one-liner the card diagnosed, not a rewrite: one hunk in dist/mdx-plugins/stringifier.js, replacing the for (const k in handlers) line with a form that carries handler.peek onto the wrapper. I read the hunk on the branch.
The manifest key really is where the deviation says. package.json → pnpm.patchedDependencies → fumadocs-core@16.8.12, alongside the onlyBuiltDependencies that was already there. The dispatch expected pnpm-workspace.yaml; pnpm 10.28.2's own patch-commit chose otherwise and the dev left it where the tool put it. Correct call — the dispatch said to follow the installed tool over a local precedent that does not exist.
The lockfile carries the installer's own annotations, not hand-edits: a patchedDependencies block with hash: 042796c0…, and patch_hash=042796c0… threaded into the fumadocs-core version key in all three places it is referenced (fumadocs-core, fumadocs-mdx, fumadocs-ui).
CI applied the patch on a clean install, on GitHub's runners, not only in the dev's container. Run 34280082137 on 5ce94d3: build success, Node floor success. That job's first step is pnpm install --frozen-lockfile, and a patch that failed to apply exits 1 there — so the green build is an independent clean-install proof.

The two things that made this report worth accepting

Both failure modes were demonstrated, and stated as such. A perturbed anchor makes install exit 1 with ERR_PNPM_PATCH_FAILED; removing the pin lets install exit 0 and puts the defect back at exactly the baseline figures — 67 references, 4 of 661 malformed, byte count matching the before build. The second is the one that matters, because it is the failure mode this repo will actually meet (see below), and it is the one a patch step cannot demonstrate by succeeding.

Three baseline figures moved and the dev reported the new ones. Link targets are 661, not the 650 the decision comment quotes; absolute site targets 560, not 549 — eleven on-site links landed in content/docs/ since the investigation read 1ebd7b7. The reference counts (67; 58/5/4) and the malformed count (4) are unchanged, and the absolute figure still moves by exactly +2. Reporting numbers that contradict the PM's own decision comment is the behaviour that makes a report worth reading.

What I did with the rest of the report

Filed #282 — nothing asserts the served bodies are entity-free, so this fix regresses silently. My earlier note on #239 was wrong in a way worth correcting publicly: I said a stale patch would "fail loudly". That is true when the file stops matching a pinned version; it is false when the version moves, which is what #239 does. Then the pin simply does not match, no patch is applied, install succeeds, and the 67 references come back with nothing red anywhere. Corrected on #239 and sequenced behind #282.

Carried the withheld finding to #280 rather than letting it drop. The dev measured two wrangler deploy --dry-run readings of the same commit and same node_modules differing by 0.22 KiB, the only difference being pnpm run build versus pnpm turbo run build — and this repo already knows turbo 2 strict env mode drops undeclared env vars. That is a candidate mechanism, not noise. Holding it back for #277 was the right instinct and the wrong destination; #277 had closed.

The upstream report is posted and routed. The maintainer files it — this session cannot open an issue on fuma-nama/fumadocs. It is on the seat post's still-on-the-maintainer list, because the patch is designed to delete itself on the release that carries the real fix and that release only exists if someone reports it. The defect was checked present in 16.8.12, 16.15.1, 16.15.2 and 16.15.8, each by unpacking the published tarball, so there is no version to upgrade to instead.

Generated by Claude Code

ci: fail the build when an llms body carries a numeric character refe…

[finding] llms-full.txt emits HTML numeric entities into a plain-text file, and two of them break the markdown link they sit in #197

Description

What is on main

Why it is worth a card

Shape of the fix

Reproduce

Activity

hotlong commented on Aug 26, 2026

The first task is investigation, not a patch

Scope note

The notation finding is worth more than this card

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

hotlong commented on Aug 26, 2026

The cause, found rather than guessed

Three corrections to my card. I got all three wrong; take the report's numbers.

Method note

Why this needs the maintainer

Housekeeping

hotlong commented on Sep 8, 2026

Decided by the maintainer: Route A

What is being patched

Expected effect, already measured

Scope: the producer, so both consumers

The patch does not expire on the next bump

#160 is a regeneration task, not a merge

Housekeeping

os-bill commented on Sep 8, 2026

Serial constraints and read-coupling

The half the report cannot skip

The upstream report is part of Route A, and you cannot file it

os-bill commented on Sep 8, 2026

Upstream report, ready to post — fuma-nama/fumadocs

What happens

Reproduction

The fix, one line

A/B, same input, one process

Affected releases

Why it matters downstream

Not part of the upstream body — for this card

os-bill commented on Sep 8, 2026

os-bill commented on Sep 8, 2026

What I verified against GitHub rather than the report

The two things that made this report worth accepting

What I did with the rest of the report

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Upstream report, ready to post — `fuma-nama/fumadocs`