Knitter's Library — User Manual

A short guide to the parts of the app that aren't immediately obvious from the buttons. Written for you and anyone else who wants to use the app without losing data. Last updated 2026-05-20 (build 1488).

What you need to know in one minute

1. ALWAYS use it as an installed app. NEVER as just a browser tab. This is non-negotiable. Install it on every device you want to use it on, before you do anything else. Browser-only access will eventually lose your data — guaranteed on iOS, likely on Mac/Windows. The installed-app path keeps your library safe.
   • iPhone / iPad: Share button → "Add to Home Screen".
   • Mac (Safari 17 / Sonoma+): File menu → "Add to Dock".
   • Mac / Windows Chrome or Edge: install icon in the address bar (or 3-dot menu → "Install app").
   • Android Chrome / Edge / Brave: 3-dot menu → "Install app" or "Add to Home Screen".
2. Export a .klib backup once a week (Settings → Export Data) and AirDrop or email it to yourself. This is the only recovery method that works with no internet and no paired device.
3. Write down your 12 recovery words (Settings → Show recovery phrase) and store them somewhere safe — not on the same device.
4. Never delete the home-screen icon as a "fresh start" or "force refresh". iOS treats that as a full data wipe — your library on that device is gone instantly. If you really need to start fresh, use Settings → Disconnect Sync first.

1. How to start

If you're setting up Knitter's Library for the first time, the smoothest order is to enter what you OWN before you enter what you're MAKING:

1. Enter your tools first. Add all your needles, hooks, cables and other accessories to your inventory. Once they're in, every project can pick them from a list instead of you typing them again each time.
2. Then enter your yarns. Add your whole stash to the yarn library — brand, colour, weight, how many skeins, the price if you know it.
3. Then add your projects. Now each project can pull yarn and tools straight from the libraries you just built, and the app can do the useful math for you — how much yarn a project used, what it cost, which needles are currently busy.

Keep it up as you go: whenever you buy new yarn or a new accessory, add it to your inventory right away. The app is at its most useful when your inventory mirrors what you actually own.

2. Multi-device sync

You can use the same library on as many of your own devices as you want (phone, tablet, laptop). Every change made on one device appears on the others within seconds. Photos take a bit longer (5-30 seconds depending on size and connectivity). Both devices need to be online for changes to flow.

How it works under the hood

Every device that joins your sync room holds the same encryption key. Edits are sealed on the sender, sent through a relay server (which only sees ciphertext), and unsealed on the receiver. Neither I nor the relay nor any third party can read your data — only your own devices have the key.

Adding a second device

Two ways. Pick whichever is more convenient.

Way 1 — Scan a QR (fastest, no typing)

The direction matters: the new (empty) device shows the code, the existing device scans it.

1. On the new device: Open Knitter's Library → Settings → SYNC, and tap "Show QR (another device scans it)". A QR code appears.
2. On the existing device: Open Knitter's Library → Settings → SYNC, and tap "Scan QR from another device". Point the camera at the new device's QR. The existing device sends its encryption key to the new device, sealed so the relay can't read it.
3. Wait ~5 seconds. The new device flips to "connected" and your library appears.

Way 2 — Type the 12-word phrase

1. On the existing device: Settings → SYNC → "Show my recovery phrase" (you may need to confirm with your device passcode). Write down the 12 words in order.
2. Make sure the existing device is online and the sync indicator is settled before you start typing on the new device. Edits made while offline sit in a local queue on that device until it reaches wifi — they aren't on the relay yet, so the new device can't pull them. Open the existing device, wait a few seconds for the sync icon to go quiet, then continue.
3. On the new device: Settings → SYNC → "Pair using 12 words". Type all 12 words separated by spaces.
4. Wait ~30 seconds for the library to download.

What syncs both directions

• All yarns (name, brand, color, photo, weight, fiber, reviews, …)
• All projects (status, notes, pattern, dates, photos, yarn list, …)
• All techniques (description, photos, steps, tips)
• All inspirations (photos, palettes, tags, links, notes)
• All accessories (needles, hooks, cables, tools)
• Tombstones — when you delete something on one device, it disappears on the other.

If you edit the same field on two devices at the same time (rare in practice), the latest write wins. The other write is overwritten, not merged.

What if a device is offline?

Your edits queue locally. The next time that device gets wifi/cellular, all queued edits push to the others in the order you made them. Nothing is lost while offline; you just won't see the OTHER devices' changes until you're back online.

When sync goes wrong

Most issues self-heal if you keep both devices unlocked and the app foregrounded for ~5 minutes. The most common scenario is a few photos fail to arrive on first pair — they retry in the background, and as long as the source device is awake and connected they eventually all arrive.

If something is still missing after that, email a screenshot or the name of the missing item to knitters.library@gmail.com and we'll trace it from the logs.

3. Data safety: three rules

The app is local-first — your library lives in your phone's storage, not on a server. That's a feature (privacy, offline, fast) but it means YOU are responsible for not losing it. Three rules for that:

Rule 1 — ALWAYS install it as an app. NEVER use it as a browser tab.

This is the most important rule in the manual. It's stated emphatically on purpose: there is no scenario in which using the app via just a browser tab is the right choice for a user who actually cares about their library.

On iPhone / iPad / Android phone, browser-only access will lose your data. iOS Safari evicts site data after 7 idle days, under storage pressure, on "Clear History", and on private-browsing exit. Android Chrome is more lenient but still cleanable. Adding to the home screen elevates the app to "persistent storage" — iOS / Android treat it like a real installed app and skip those eviction rules.

On Mac / Windows desktop, the storage in modern browsers is more durable by default — your data probably survives most browser-cleanup events. But "probably" isn't good enough for your library. Installing as a Dock app (macOS Safari / Sonoma+: File → Add to Dock) or a desktop app (Chrome / Edge: install icon in the address bar) makes storage truly persistent and gives you a real launcher icon.

The universal rule: install on every device, on every platform, before the first time you add real data. If you've already started using the app in a browser, install it as soon as you can — your existing data will carry over to the installed app on the same device.

Rule 2 — Export .klib backups regularly

Settings → Export Data → "Download .klib". This file contains your entire library — every yarn, every project, every photo, every technique, every inspiration. It's the only recovery method that works without any internet AND without any paired device.

Suggest: export once a week. AirDrop or email it to yourself so it lives in two places (your device and your email/cloud).

To restore: Settings → Import Data → pick a .klib file. The library loads in a few seconds. Photos load progressively after.

Rule 3 — Don't delete the home-screen icon

iOS treats deleting the home-screen icon as deleting the app's data. Everything on that device is wiped instantly. If you delete the icon without first exporting AND/OR saving the recovery phrase, you've lost that device's library.

You can still recover the data IF:

• At least one other paired device still has it. Re-install on the deleted device, type your 12 recovery words, and the library syncs from the peer.
• You have a .klib export. Re-install, import the .klib.

But never assume both are true. If you have only one device, only one recovery method, and you tap the icon's "Remove App" → "Delete App", your library is gone.

If you really need to start fresh on a device, use Settings → Disconnect Sync first. That's the safe path.

Two recovery routes — both work

Having both is belt-and-braces. The ideal: a .klib export from this month + the 12 words written down somewhere safe. Then no matter what happens to your devices, you can recover.

4. Features and gotchas

Yarn library

• A "yarn" with multiple colorways shows up as a grouped card. Tap to expand and see each colorway.
• The "Review yarn" field is shared across all colorways of the same (name, brand) — editing the review on Nepal-Red updates Nepal-Blue too. Per-colorway "Notes" stays per-row.
• Sort modes: alphabet / color / brand / weight. Color/brand/weight segments show grouped cards; tap a card to drill in.
• Color buckets are picked manually from an 11-option palette (white, yellow, orange, red, pink, violet, green, blue, brown, black, multicolor).
• If a yarn has a grams-per-skein value, leftover amounts are shown to the exact gram (e.g. "20g" instead of "0.8 skein"). Without that value the app falls back to ¼ / ½ / ¾ fractions.
• When you add a grams-per-skein value to a yarn that already had a partial-skein leftover recorded, the app asks once whether to keep or clear that partial — because a "¼ skein" suddenly becomes real grams in the stock math, and it wants you to confirm the number is right.

Projects

• A project's status moves through Future → In progress → Finished. The big button at the bottom of the project always offers the natural next step: a Future or Hibernating project shows "Mark as in progress"; an in-progress project shows "Mark as Finished"; a finished project shows "Reopen Project".
• Marking a project finished subtracts the yarn it used from your stash (it asks you to confirm, and lists what will be subtracted). Reopening the project puts that yarn back.
• Right after you mark a project finished, the app asks "Add finish photos now?" — say yes to add up to 3 photos of the finished piece straight away, or skip and add them later from the project card.
• Finish photos live in a small gallery on the finished project. Tap "Edit photos" to add, delete, or pick which photo is the project's main (hero) photo — tap the star on a photo to promote it; the old hero photo drops into the gallery so nothing is lost.
• Cost: if the yarns a finished project used have a price recorded, the project view shows a Cost section at the bottom — per-yarn cost and a total, worked out from the grams used.
• "Date of finish" is frozen at the moment you tap "Mark as Finished". Subsequent edits don't change it.
• Manual Start date and Finish date fields override the auto values — set them when you started a project before installing the app or finished one before tapping "Mark as Finished".

Accessories & needles

• Add needles, hooks, cables and tools to your inventory. Needles can be added one at a time or as a whole set (the "+ Add needle set" option ticks every size in a set at once).
• The inventory shows whether each needle is Available or In use — a needle counts as "in use" when an active project's needle list references the same kind + size (+ tip length for interchangeable tips). Finished projects release their needles.
• When you add yarn to a project you can pick it straight from your yarn library; same for needles from your accessories. Both pickers are sorted (yarns A→Z, needles smallest→biggest) so they're easy to scan.

Techniques

• Each technique can have a photo. Tap the photo to view it full-screen.
• Notes support rich text (bold/italic/underline/strikethrough/lists/ colors).

Inspirations (moodboard)

• Add photos of patterns / yarn combos you want to try later.
• Notes support rich text — same toolbar as techniques and projects.
• "Color palette" lets you set 1+ swatch colors for a card.
• Projects shared with you by other Knitters also land here — see chapter 5.

5. Sharing cards with other Knitters

You can share a single project, a single yarn, or a single technique with another Knitter's Library user.

Open the project (or yarn, or technique) you want to share and tap Share. The app creates a short link. Send that link to the other person however you like — message, email, anything.

When they open the link in their own Knitter's Library, the shared card is imported into their Inspiration library as a read-only reference. It is a look, not a merge: it never changes their own yarn, needles, accessories, or techniques. They can browse it for ideas, and that's it.

Sharing is one-way and one-time: the link is a snapshot taken the moment you created it. If you change the project afterwards, send a fresh link.

6. Contact us

Found a bug, something confusing, or have a feature idea? Email us at knitters.library@gmail.com. Screenshots are the most helpful thing you can send for visual bugs.

For sync issues specifically: say WHICH device(s) it happened on and roughly WHEN. Every sync event from every device is logged, so a screenshot or a timestamp lets us pinpoint exactly what went wrong.

7. When in doubt

• Export a .klib first.
• THEN try the thing you're worried about.

That's the universal "I have an undo button" approach. The export takes ~5 seconds, the import takes ~10 seconds. Spend that time before any operation that feels risky.