Guides: add Troubleshooting (symptom → cause)

docs/guides/README.md

@@ -3,7 +3,16 @@
 Task-oriented how-to guides (shorter and more targeted than
 [tutorials](../tutorials/README.md)).
 
-> **TODO:** this section is scaffolding. Planned topics:
+## Available
+
+- **[Buying pitfalls](./buying-pitfalls.md)** — the handful of wrong purchases
+  that only reveal themselves after delivery: chips, readers, PN532 modules,
+  the TigerScale screen, screws, filament for printed parts.
+- **[Troubleshooting: symptom → cause](./troubleshooting.md)** — chip reading,
+  writing and verification problems, most frequent first, collected from real
+  cases.
+
+> **TODO:** more guides planned:
 >
 > - How to buy / encode TigerTag chips
 > - How to promote a chipless (digital) spool to a real chip

docs/guides/buying-pitfalls.md

@@ -0,0 +1,88 @@
+# Buying pitfalls
+
+Everything in the ecosystem runs on cheap, widely available parts — that's the
+point. The flip side: marketplace listings all look alike, and the wrong
+variant only reveals itself **after delivery**. Every pitfall below cost a
+real builder time or money; most were reported on the
+[Discord](https://discord.gg/3Qv5TSqnJH).
+
+Read this **before** placing an order, not after.
+
+## Blank NFC chips
+
+| Buy | Avoid | Why |
+|---|---|---|
+| **NTAG213 / 215 / 216**, 25 mm round sticker recommended | Listings that only say "NFC 13.56 MHz" | That label also covers incompatible chips. Insist on the exact NTAG reference. |
+| | **MIFARE Classic 1K** tags | Same frequency, different standard — it's what several printer vendors use for their own locked tags ([compatibility](../compatibility/README.md)). A blank one cannot hold a TigerTag. |
+| | UID-changeable **"magic" chips** | The [TigerTag+](../products/tigertag-plus.md) trust model is anchored on the factory-locked UID. A spoofable UID defeats it — and a seller pushing "magic" chips for spool tagging is a red flag in itself. |
+| | Pre-locked promotional tags | Some promotional NFC stickers ship **write-locked** and can never be encoded. |
+
+> **Note:** NTAG213 is the minimum — the 144-byte payload is sized to fit it.
+> Official branded chips ship as NTAG215 so the chip can be reused as a plain
+> NDEF object at end of life ([the TigerTag chip](../concepts/tigertag-chip.md)).
+
+Sticking a chip **on a metal surface**? A standard sticker goes dead on metal —
+you need an *on-metal* (ferrite-backed) tag, which costs more. For a plastic or
+cardboard spool, the standard sticker is fine.
+
+## USB desktop readers (ACR122U class)
+
+The ACR122U is the reference desktop reader — two of them power a
+[TigerPOD](../products/tigerpod.md). The reader itself is a safe buy; how you
+plug it is the trap:
+
+> **Warning:** on an **unpowered USB hub**, an ACR122U reads fine but **fails
+> writes intermittently** — the most confusing failure mode there is, reported
+> repeatedly by builders. Plug it directly into the computer, or use a powered
+> hub.
+
+## PN532 modules (TigerScale builds)
+
+> **Warning:** *"Sealed USB-C-only PN532 dongles will not work with this
+> board"* — the
+> [Tiger-Scale-V3 README](https://github.com/TigerTag-Project/Tiger-Scale-V3)'s
+> own words. You need bare **PN532 V3 modules with accessible header pins**.
+> The sealed dongles look like the convenient option; they are the single most
+> common wrong purchase of the build.
+
+Two more things to check on the listing photos:
+
+- The common red PN532 boards carry **two DIP switches** selecting the bus
+  (I²C / SPI / HSU). Wrongly set, the module is simply invisible — set them to
+  match the transport you flash.
+- You need **two** modules for a TigerScale.
+
+## The TigerScale touchscreen: 3.5 vs 3.5B
+
+Both Waveshare variants are supported — they differ only in controllers:
+
+| | ESP32-S3-Touch-LCD-**3.5** | ESP32-S3-Touch-LCD-**3.5B** |
+|---|---|---|
+| Display controller | ST7796 (SPI) | AXS15231B (QSPI) |
+| Touch controller | FT6336 (separate chip, I²C) | AXS15231B (integrated, I²C) |
+| MCU / PSRAM / resolution | identical | identical |
+
+The **3.5B** was the original development target and is the nicer
+architecture — but it is chronically **out of stock**. The plain **3.5**
+performs just as well in practice (team-confirmed after user testing, on the
+Discord). **Buy whichever you can find**; you select the variant at flash
+time.
+
+## Screws: order them with the electronics
+
+The TigerScale build needs 2× M5×30 + 2× M4×30 (load cell), 4× M2×6
+(display) and M3 self-tapping screws (housing). In non-metric countries these
+are genuinely hard to find in local hardware stores — a builder on the
+Discord ended up assembling a separate parts order after discovering this
+mid-build. One online order **together with the electronics** avoids the
+wait.
+
+## Filament for the printed parts
+
+Do **not** print any part that sits between a reader and a chip in
+carbon-fiber-filled filament (PLA-CF, PETG-CF): the conductive fibers disturb
+the NFC field. Plain PLA or PETG works fine.
+
+---
+
+**▲ [Documentation index](../../README.md)** · **Related:** [The TigerTag chip](../concepts/tigertag-chip.md), [TigerScale](../products/tigerscale.md), [TigerPOD](../products/tigerpod.md), [FAQ](../faq/README.md)

docs/guides/troubleshooting.md

@@ -0,0 +1,88 @@
+# Troubleshooting: symptom → cause
+
+Chip reading, writing and verification problems, ordered from most to least
+frequent. Start at your symptom, work down the checks in order — most of them
+were collected from real cases on the
+[Discord](https://discord.gg/3Qv5TSqnJH).
+
+For printer-link problems (a machine not appearing in Tiger Studio, a slot not
+updating), see the per-vendor pages in [compatibility](../compatibility/README.md);
+for purchases that fail by design, see [buying pitfalls](./buying-pitfalls.md).
+
+## The chip is not detected at all
+
+| Check | Detail |
+|---|---|
+| Is NFC on? | Android: Settings → Connections → NFC. iPhone: always on, nothing to enable. |
+| Right antenna spot? | Android phones usually have the antenna in the **upper back**; iPhones read from the **top edge**. Sweep the phone slowly over the chip rather than holding one spot. |
+| Case in the way? | A thick case, a magnetic mount plate or a metal ring blocks the field. Take the case off for the read. |
+| Chip on metal? | A standard sticker goes dead on a metal surface — that needs an on-metal tag ([buying pitfalls](./buying-pitfalls.md)). |
+| Chip damaged? | A fold, tear or puncture cuts the antenna trace. That chip is permanently dead — encode a fresh one. |
+| Two chips in the field? | Two chips presented to one reader at the same time collide and neither reads. Separate them. (The two chips of a single spool sit on **opposite sides** precisely so a reader only ever sees one — [why two chips](../concepts/tigertag-chip.md).) |
+
+## The chip reads as blank / "Init"
+
+Not a fault: the chip is new. It carries the TigerTag Init marker and no data
+yet. Encode it — [your first smart spool](../tutorials/first-smart-spool.md).
+
+## The chip reads, but the data is wrong
+
+The chip was encoded with the wrong values, or it came off another spool.
+Chips are **never write-locked**: just re-encode it with the right data
+([the TigerTag chip](../concepts/tigertag-chip.md)).
+
+## The phone reads fine, but the printer does nothing
+
+The chip is fine — what's missing is printer-side support. No printer reads
+TigerTag chips by itself out of the box today (the one exception is the
+Snapmaker U1 running the community firmware — see
+[Snapmaker](../compatibility/snapmaker.md)); the filament data reaches the
+six integrated brands **through Tiger Studio**. Check where your machine
+stands in the [compatibility matrix](../compatibility/README.md).
+
+## TigerTag+ Certified verification fails
+
+| Cause | What to do |
+|---|---|
+| Stale reference data | Verification resolves against the shared reference database. Update the app / let it sync, then re-scan. |
+| Data was rewritten after signing | **Expected behaviour.** Rewriting the signed area invalidates the signature; the chip stays fully readable — it is simply no longer certified ([TigerTag+](../products/tigertag-plus.md)). |
+| Data was copied onto another chip | **By design.** The chip's factory-locked UID is part of what's signed — a clone can never verify. |
+
+Only the first row is fixable; the other two are the trust model doing its
+job.
+
+## The write fails on a chip that already holds other data
+
+A blank chip writes first try; a chip that already carries **non-TigerTag
+data** sometimes doesn't — reported on the Discord since August 2025.
+
+The app is designed to detect a non-TigerTag chip and offer to **convert** it.
+If you get an error instead:
+
+1. wipe the chip back to blank with a generic NFC app (the community
+   workaround is "NFC Tools", iOS/Android),
+2. re-scan — it now behaves like a factory-blank chip and the write goes
+   through.
+
+## A write fails midway
+
+- **Hold still.** Moving the phone or the chip during a write can interrupt it
+  and leave the chip in an inconsistent state — reported by builders, and
+  recoverable: a full re-encode brings the chip back.
+- **ACR122U writing intermittently?** Check how it's powered —
+  [buying pitfalls](./buying-pitfalls.md#usb-desktop-readers-acr122u-class).
+
+## Still stuck?
+
+Ask in **#help-and-support** on the [Discord](https://discord.gg/3Qv5TSqnJH),
+with the five things that make an answer possible:
+
+1. chip model (NTAG213/215/216, or unknown),
+2. reader — phone model, ACR122U, TigerPOD, TigerScale,
+3. app and version,
+4. what you did, in order,
+5. what the app showed, word for word (or a screenshot).
+
+---
+
+**▲ [Documentation index](../../README.md)** · **Related:** [Buying pitfalls](./buying-pitfalls.md), [The TigerTag chip](../concepts/tigertag-chip.md), [Compatibility](../compatibility/README.md), [FAQ](../faq/README.md)