Guides: add Publish a public list link on TigerHub

docs/guides/README.md

@@ -3,12 +3,27 @@
 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.
+- **[Buy and encode TigerTag chips](./buy-and-encode-chips.md)** — start to
+  finish: which chips, which reader, encoding from phone or desktop, Twin Tag
+  pairs, and encoding in series.
+- **[Promote a chipless spool to a real chip](./promote-chipless-spool.md)** —
+  writing a TigerData / TigerData+ record onto a physical NTAG chip (desktop +
+  reader).
+- **[Publish a public list link on TigerHub](./publish-list-on-tigerhub.md)** —
+  share a read-only inventory or wishlist as a `/list/<token>` link; no app, no
+  account for the viewer.
+
+> **TODO:** more guides planned:
 >
-> - How to buy / encode TigerTag chips
-> - How to promote a chipless (digital) spool to a real chip
 > - How to migrate an existing spreadsheet inventory into your TigerSystem account
-> - How to publish a public list link on TigerHub
 
 ---
 

docs/guides/buy-and-encode-chips.md

@@ -0,0 +1,81 @@
+# Buy and encode TigerTag chips
+
+The fastest way to make a spool intelligent, start to finish: get the right
+chips, then write their identity. No account, no cloud, a few cents per spool.
+
+For the wrong purchases that only reveal themselves after delivery, read
+[buying pitfalls](./buying-pitfalls.md) first — this guide assumes you bought
+the right chips.
+
+## 1. Which chips to buy
+
+Any **NTAG213 / 215 / 216** (NFC Forum Type 2), **25 mm round sticker**
+recommended. NTAG213 is the minimum — the 144-byte payload is sized to fit it
+([the TigerTag chip](../concepts/tigertag-chip.md)). Buy from anywhere; nothing
+official is required.
+
+> **Note:** planning **two chips per spool**? That's how factory spools ship —
+> one on each side, so a reader always faces one. Write them as a pair (see
+> step 4).
+
+## 2. Which reader to use
+
+| You have | Use | Best for |
+|---|---|---|
+| An NFC phone | [Tiger NFC Connect](../products/tigertag-connect.md) | Getting started, occasional writes — the reader is already in your pocket |
+| A computer + a USB reader | Tiger Studio + ACR122U or [TigerPOD](../products/tigerpod.md) | Encoding in series, an inventory, a workshop |
+
+Everything below works **100 % offline**.
+
+## 3. Encode a chip from your phone
+
+1. Open Tiger NFC Connect and tap **Scan**.
+2. Present the chip to the phone's antenna (Android: upper back; iPhone: top
+   edge).
+   - A **blank** chip → the app offers to write a new TigerTag.
+   - A chip already holding **non-TigerTag** data → the app offers to
+     **convert** it. (If it errors instead, wipe it blank with a generic NFC
+     app, then re-scan — see [troubleshooting](./troubleshooting.md).)
+3. **Describe the filament** — material, brand, colour, aspect, diameter, and
+   the print settings: nozzle and bed temperature ranges, drying. The choices
+   come from the shared catalogue, so every compatible app reads the spool the
+   same way.
+4. Tap **Make** and hold the phone to the chip until it confirms.
+5. Stick the chip on the spool, and re-scan to check.
+
+> **Tip:** fill in the temperatures even if you know them by heart. The day a
+> reader-equipped machine reads the tag on its own, it needs them — and a
+> field you leave empty is a field nobody else will fill for a generic
+> filament.
+
+## 4. Encode two chips as a pair (Twin Tag)
+
+For the full experience, put a chip on each side of the spool and write them
+**together**, so they stay one spool for its whole life:
+
+- **On the phone** — use the **Dual Link** option at creation time.
+- **On the desktop** — write both with two readers, or repair an unlinked pair
+  in Tiger Studio with **Link to twin Spool**.
+
+Writing the two chips one after another with a single reader may link them
+temporarily, but the association is not guaranteed to survive a re-scan — write
+them as a pair.
+
+## 5. Encode in series (desktop)
+
+Beyond three or four spools, Tiger Studio + an ACR122U (or a
+[TigerPOD](../products/tigerpod.md)) is the practical route: prepare one
+filament sheet, duplicate it, and encode spools one after another. This is also
+where you burn a **chipless** [TigerData / TigerData+](../concepts/universal-filament-identity.md)
+record onto a physical chip — the mobile app doesn't do that yet.
+
+## What you can't do this way
+
+You cannot produce a **TigerTag+ Certified** (signed) chip: the signature is
+issued by certified manufacturers, and TigerTag holds the private key
+([TigerTag+](../products/tigertag-plus.md)). Encoding at home always produces a
+standard TigerTag — fully readable everywhere, just not signed.
+
+---
+
+**▲ [Documentation index](../../README.md)** · **Related:** [Buying pitfalls](./buying-pitfalls.md), [The TigerTag chip](../concepts/tigertag-chip.md), [Your first smart spool](../tutorials/first-smart-spool.md), [Troubleshooting](./troubleshooting.md)

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/promote-chipless-spool.md

@@ -0,0 +1,49 @@
+# Promote a chipless spool to a real chip
+
+You can manage a whole inventory with **no chips at all** — as
+[TigerData or TigerData+](../concepts/universal-filament-identity.md) records,
+the identity living purely in your account. When you're ready, "promoting" a
+record means writing it onto a physical NTAG chip so the spool carries its own
+identity, offline.
+
+## What you need
+
+- The chipless spool in your inventory (a **TigerData** or **TigerData+**
+  record).
+- A blank **NTAG213 / 215 / 216** chip.
+- **[Tiger Studio](../products/tiger-studio.md) + a USB reader** — an ACR122U
+  or a [TigerPOD](../products/tigerpod.md).
+
+> **Warning:** this one step is **desktop-only**. Tiger NFC Connect can write a
+> tag you describe on the spot, but it cannot burn an existing chipless
+> **record** onto a chip yet — that path runs through Tiger Studio and a reader.
+
+## Steps
+
+1. In Tiger Studio, open the chipless spool from your inventory.
+2. Place the blank chip on the reader.
+3. Write the record to the chip. The record keeps its catalogue identity — a
+   promoted TigerData+ stays identified.
+4. Re-scan to confirm, and stick the chip on the spool.
+
+The moment the data lands on the chip, the record becomes a **TigerTag**: a
+physical UID is now associated with the identity. A promoted **TigerData+**
+becomes a **TigerTag+** (still identified, still not signed — see
+[TigerTag+](../products/tigertag-plus.md)).
+
+## Two chips? Promote them as a pair
+
+If the spool will carry two chips, write both in the same operation so they
+stay one spool — with two readers, or by repairing the pair afterwards with
+**Link to twin Spool**. See
+[Buy and encode chips](./buy-and-encode-chips.md#4-encode-two-chips-as-a-pair-twin-tag).
+
+## The reverse is always possible
+
+Chips are never write-locked. A promoted spool can be re-encoded, wiped, or
+returned to a plain chipless record at any time — the identity is yours to move
+between digital and physical.
+
+---
+
+**▲ [Documentation index](../../README.md)** · **Related:** [Universal filament identity](../concepts/universal-filament-identity.md), [Buy and encode chips](./buy-and-encode-chips.md), [TigerPOD](../products/tigerpod.md), [Tiger Studio](../products/tiger-studio.md)

docs/guides/publish-list-on-tigerhub.md

@@ -0,0 +1,67 @@
+# Publish a public list link on TigerHub
+
+Share a read-only view of an inventory or a wishlist as a plain web link.
+Whoever opens it needs **no app and no account** — just a browser.
+
+## What it is
+
+A public list link looks like:
+
+```
+https://tigersystem.io/list/<token>
+```
+
+It's a read-only snapshot served by [TigerHub](../products/tigerhub.md), the
+ecosystem's web home. The `<token>` is what makes the link work — anyone who
+has it can view the list, so treat it like a shared password (see revoking,
+below).
+
+## Publish a list
+
+The link is generated from the apps, not from the website — TigerHub only
+displays what [Tiger Studio](../products/tiger-studio.md) or
+[Tiger NFC Connect](../products/tigertag-connect.md) publish:
+
+1. In Tiger Studio or Tiger NFC Connect, open the inventory or wishlist you
+   want to share.
+2. Generate a **share link** for it.
+3. Copy the `https://tigersystem.io/list/<token>` link and send it to anyone.
+
+The viewer opens it in any browser and sees the list read-only — they cannot
+edit it, and nothing about your account is exposed beyond what the list shows.
+
+## Revoke a link
+
+A share link stays valid until you revoke it. Revoke it from the same place you
+generated it (Tiger Studio / Connect) once you no longer want the list public —
+after that, the old `/list/<token>` URL stops resolving.
+
+> **Tip:** revoking then re-publishing produces a **new** token. If you shared
+> the old link widely and want to cut access, revoking is the way — the old URL
+> goes dead immediately.
+
+## Public link vs sharing with a friend
+
+Two different mechanisms, same source data:
+
+| | Public list link | Friend |
+|---|---|---|
+| Who can see it | anyone with the URL | a specific person you added |
+| They need an account | no | yes (a TigerSystem account) |
+| How | generate a `/list/<token>` link | exchange **friend codes / invitations** |
+| Good for | a Reddit post, a forum, a quick show-and-tell | an ongoing, mutual view between two makers |
+
+Friend codes and invitations are managed from the apps and from your account on
+the web (`/account`).
+
+## What's behind it
+
+The published data comes from your TigerSystem account (a single shared Firebase
+database that every app reads and writes); TigerHub is only the web surface that
+renders the public view. Your account data is never public — only the specific
+list you chose to publish. See
+[Inventory & cloud sync](../concepts/inventory-and-cloud-sync.md).
+
+---
+
+**▲ [Documentation index](../../README.md)** · **Related:** [TigerHub](../products/tigerhub.md), [Inventory & cloud sync](../concepts/inventory-and-cloud-sync.md), [Tiger Studio](../products/tiger-studio.md)