diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 0f24eb3..c86074f 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -67,3 +67,4 @@ Two kinds of records live here. The boundary rule: | [0020](gdr/0020-nunito.md) | Nunito: the rounded face (amends 0019) | Accepted | | [0021](gdr/0021-the-wordmark.md) | The wordmark: bars beside "timbre", stroke 3; an underlined secondary (amends 0019, 0017) | Accepted | | [0022](gdr/0022-nunito-sans-for-text.md) | Nunito Sans for text; Nunito keeps the headlines (amends 0020) | Accepted | +| [0023](gdr/0023-the-library.md) | The Library: one store, five kinds, synced by iCloud, practised by voice | Accepted | diff --git a/docs/decisions/gdr/0023-the-library.md b/docs/decisions/gdr/0023-the-library.md new file mode 100644 index 0000000..2b9f163 --- /dev/null +++ b/docs/decisions/gdr/0023-the-library.md @@ -0,0 +1,24 @@ +# 0023 — The Library: one store, five kinds, synced by iCloud, practised by voice + +- **Status:** Accepted +- **Date:** 2026-10-14 +- **Builds on:** [GDR-0001](0001-local-only-free-no-account.md) (the claim), [GDR-0006](0006-app-never-phones-home.md) (the boundary), [GDR-0010](0010-optional-icloud-sync-of-the-personal-dictionary.md) (iCloud for the dictionary), [GDR-0011](0011-taught-corrections-before-the-model.md) and [GDR-0012](0012-command-mode.md) (what the Library replaces and feeds) +- **Decides:** the five questions in `docs/design/product-map.md` §8 + +## Context + +Hugo wants Timbre to make him better at four things: spelling, vocabulary, phrases, acronyms. The product map (2026-10-11) laid out how the product grows to do that — a Library, a phone, sync, practice — and ended with five decisions. They were walked through one at a time on 2026-10-14, each with its alternatives, and taken as follows. + +## Decisions + +1. **The Library syncs through iCloud, not an account.** CloudKit, private database, the user's own account; Apple's daemons move the data and the binary still makes zero requests. The store is built behind a sync interface so an account backend could be added later. An account becomes a decision on the day a non-Apple Library client is wanted, with its own record and its own change to `/network`. Until then, "Apple pure" is the product, not a tier. +2. **Timbre for iPhone is a companion.** The Library in your pocket: review, practise, word of the day, add a word you heard. It does not dictate into other apps — iOS cannot — and a keyboard extension is not planned. If one is ever wanted it is a record of its own. +3. **One Library, five kinds.** `word`, `acronym`, `phrase`, `spelling`, `correction`, replacing the three Settings lists. Every entry carries its meaning, an example, where it came from, industry tags, a strength that practice raises and time lowers, and its history. Vocabulary is the word entries; definitions are the acronym entries; corrections stay corrections. The three lists migrate on the Mac first, with nothing lost; Settings › Dictionary becomes Settings › Library with a kind filter. The polisher, explain and the correction table read the same store through the same interface, and the corpus proves the behaviour is unchanged. +4. **A platform-neutral package, TimbreCore, is created with the Library.** The Library, pure parsing, practice scoring and the sync interface live there; no AppKit. TimbreKit imports it and keeps the macOS pipeline; the iPhone app imports only TimbreCore. The rule for what goes where is an ADR written with the split. +5. **Practice uses the voice, and every drill ships with a guardrail and a corpus.** Spell it (say the word, spell it aloud; the recogniser checks the letters), Say it (use it in a sentence; the on-device model judges the meaning), Explain it (answer the card by voice), the word of the day (weakest entries first, then a bundled list for the profile's industry, as a local notification), and the private kind of gamification — strength, streaks, a weekly review, no leaderboard. Each drill's checks go on the Evals page next to the polisher's. Spell it ships first, because it needs no model judgment. + +## Consequences + +- Phases 1–4 of the product map are now the plan: the Library on the Mac with the `TimbreCore` split; iCloud sync proved on two Macs with `nettop` still empty; the iPhone companion; Spell it with its corpus. Each phase is its own pull request and its own measurement. +- Nothing here changes a claim: the headline keeps one asterisk and `/network` keeps one entry. +- A Library entry is the user's. The Mac app transmits none of it; iCloud carries it under the user's own account. diff --git a/docs/design/product-map.md b/docs/design/product-map.md index 5478fd4..ced578a 100644 --- a/docs/design/product-map.md +++ b/docs/design/product-map.md @@ -1,9 +1,9 @@ # Timbre, the whole product -*2026-10-11 · Status: proposed map, for the decisions below. Constraining -records: GDR-0001, GDR-0006, GDR-0010, GDR-0013. This document is where -the product is planned as one thing; each piece that lands still gets its -own record.* +*2026-10-11 · Status: the map; its five decisions were taken on 2026-10-14 +and are recorded in GDR-0023. Constraining records: GDR-0001, GDR-0006, +GDR-0010, GDR-0013. This document is where the product is planned as one +thing; each piece that lands still gets its own record.* Timbre started as a key you hold to talk. It is about to become the place where the words you use get better: spelling, vocabulary, phrases, @@ -119,10 +119,10 @@ That split is a record of its own (an ADR) before the first iOS line. | 5 | **Profile-aware explain** on the Mac. | A commands corpus case per industry. | | — | *Account and cross-platform.* | Decided when phase 3 has users asking. | -## 8. Decisions this map asks for +## 8. Decisions this map asked for — taken 2026-10-14 (GDR-0023) -1. **Sync by iCloud first, account later or never** (§4). -2. **The iPhone app is a companion** — the Library and practice — not a dictation app (§2). -3. **One Library, five kinds**, replacing the three Settings lists (§3). -4. **`TimbreCore`** split before the first iOS file (§6). -5. **Practice uses the voice** — drills are scored like commands, with a corpus (§5). +1. **Sync by iCloud first, account later or never** (§4). Taken: iCloud first; the store built behind a sync interface. +2. **The iPhone app is a companion** — the Library and practice — not a dictation app (§2). Taken: companion; no keyboard extension planned. +3. **One Library, five kinds**, replacing the three Settings lists (§3). Taken: five kinds, migrated on the Mac first. +4. **`TimbreCore`** split before the first iOS file (§6). Taken: created with the Library. +5. **Practice uses the voice** — drills are scored like commands, with a corpus (§5). Taken: Spell it first. diff --git a/web/src/lib/decisions/records.json b/web/src/lib/decisions/records.json index 1edda38..9a0907a 100644 --- a/web/src/lib/decisions/records.json +++ b/web/src/lib/decisions/records.json @@ -1,4 +1,39 @@ [ + { + "id": "GDR-0023", + "kind": "GDR", + "number": "0023", + "slug": "the-library", + "path": "docs/decisions/gdr/0023-the-library.md", + "title": "The Library: one store, five kinds, synced by iCloud, practised by voice", + "status": "Accepted", + "statusKind": "accepted", + "statusNote": null, + "supersededBy": null, + "supersedes": [], + "date": "2026-10-14", + "relations": [ + { + "label": "Builds on", + "summary": "GDR-0001 (the claim), GDR-0006 (the boundary), GDR-0010 (iCloud for the…", + "refs": [ + "GDR-0001", + "GDR-0006", + "GDR-0010", + "GDR-0011", + "GDR-0012" + ] + }, + { + "label": "Decides", + "summary": "the five questions in docs/design/product-map.md §8", + "refs": [] + } + ], + "excerpt": "Hugo wants Timbre to make him better at four things: spelling, vocabulary, phrases, acronyms. The product map (2026-10-11) laid out how the product grows to do that — a Library, a phone, sync, practice — and ended with five decisions. They were walked through one at a time on 2026-10-14, each with its alternatives, and taken as follows.", + "plain": "Accepted.\nContext.\nHugo wants Timbre to make him better at four things: spelling, vocabulary, phrases, acronyms. The product map (2026-10-11) laid out how the product grows to do that — a Library, a phone, sync, practice — and ended with five decisions. They were walked through one at a time on 2026-10-14, each with its alternatives, and taken as follows.\nDecisions.\n1. The Library syncs through iCloud, not an account. CloudKit, private database, the user's own account; Apple's daemons move the data and the binary still makes zero requests. The store is built behind a sync interface so an account backend could be added later. An account becomes a decision on the day a non-Apple Library client is wanted, with its own record and its own change to /network. Until then, \"Apple pure\" is the product, not a tier.\n2. Timbre for iPhone is a companion. The Library in your pocket: review, practise, word of the day, add a word you heard. It does not dictate into other apps — iOS cannot — and a keyboard extension is not planned. If one is ever wanted it is a record of its own.\n3. One Library, five kinds. word, acronym, phrase, spelling, correction, replacing the three Settings lists. Every entry carries its meaning, an example, where it came from, industry tags, a strength that practice raises and time lowers, and its history. Vocabulary is the word entries; definitions are the acronym entries; corrections stay corrections. The three lists migrate on the Mac first, with nothing lost; Settings › Dictionary becomes Settings › Library with a kind filter. The polisher, explain and the correction table read the same store through the same interface, and the corpus proves the behaviour is unchanged.\n4. A platform-neutral package, TimbreCore, is created with the Library. The Library, pure parsing, practice scoring and the sync interface live there; no AppKit. TimbreKit imports it and keeps the macOS pipeline; the iPhone app imports only TimbreCore. The rule for what goes where is an ADR written with the split.\n5. Practice uses the voice, and every drill ships with a guardrail and a corpus. Spell it (say the word, spell it aloud; the recogniser checks the letters), Say it (use it in a sentence; the on-device model judges the meaning), Explain it (answer the card by voice), the word of the day (weakest entries first, then a bundled list for the profile's industry, as a local notification), and the private kind of gamification — strength, streaks, a weekly review, no leaderboard. Each drill's checks go on the Evals page next to the polisher's. Spell it ships first, because it needs no model judgment.\nConsequences.\nPhases 1–4 of the product map are now the plan: the Library on the Mac with the TimbreCore split; iCloud sync proved on two Macs with nettop still empty; the iPhone companion; Spell it with its corpus. Each phase is its own pull request and its own measurement.\nNothing here changes a claim: the headline keeps one asterisk and /network keeps one entry.\nA Library entry is the user's. The Mac app transmits none of it; iCloud carries it under the user's own account.", + "html": "

Context

\n

Hugo wants Timbre to make him better at four things: spelling, vocabulary, phrases, acronyms. The product map (2026-10-11) laid out how the product grows to do that — a Library, a phone, sync, practice — and ended with five decisions. They were walked through one at a time on 2026-10-14, each with its alternatives, and taken as follows.

\n

Decisions

\n
    \n
  1. The Library syncs through iCloud, not an account. CloudKit, private database, the user's own account; Apple's daemons move the data and the binary still makes zero requests. The store is built behind a sync interface so an account backend could be added later. An account becomes a decision on the day a non-Apple Library client is wanted, with its own record and its own change to /network. Until then, "Apple pure" is the product, not a tier.
    2. \n
  2. Timbre for iPhone is a companion. The Library in your pocket: review, practise, word of the day, add a word you heard. It does not dictate into other apps — iOS cannot — and a keyboard extension is not planned. If one is ever wanted it is a record of its own.
    3. \n
  3. One Library, five kinds. word, acronym, phrase, spelling, correction, replacing the three Settings lists. Every entry carries its meaning, an example, where it came from, industry tags, a strength that practice raises and time lowers, and its history. Vocabulary is the word entries; definitions are the acronym entries; corrections stay corrections. The three lists migrate on the Mac first, with nothing lost; Settings › Dictionary becomes Settings › Library with a kind filter. The polisher, explain and the correction table read the same store through the same interface, and the corpus proves the behaviour is unchanged.
    4. \n
  4. A platform-neutral package, TimbreCore, is created with the Library. The Library, pure parsing, practice scoring and the sync interface live there; no AppKit. TimbreKit imports it and keeps the macOS pipeline; the iPhone app imports only TimbreCore. The rule for what goes where is an ADR written with the split.
    5. \n
  5. Practice uses the voice, and every drill ships with a guardrail and a corpus. Spell it (say the word, spell it aloud; the recogniser checks the letters), Say it (use it in a sentence; the on-device model judges the meaning), Explain it (answer the card by voice), the word of the day (weakest entries first, then a bundled list for the profile's industry, as a local notification), and the private kind of gamification — strength, streaks, a weekly review, no leaderboard. Each drill's checks go on the Evals page next to the polisher's. Spell it ships first, because it needs no model judgment.
    6. \n
\n

Consequences

\n\n" + }, { "id": "GDR-0022", "kind": "GDR", diff --git a/web/src/lib/design/design.json b/web/src/lib/design/design.json index ee9b42e..af90aef 100644 --- a/web/src/lib/design/design.json +++ b/web/src/lib/design/design.json @@ -10,7 +10,7 @@ "slug": "product-map", "path": "docs/design/product-map.md", "title": "Timbre, the whole product", - "status": "2026-10-11 · Status: proposed map, for the decisions below. Constraining records: GDR-0001, GDR-0006, GDR-0010, GDR-0013. This document is where the product is planned as one thing; each piece that lands still gets its own record.", - "html": "

2026-10-11 · Status: proposed map, for the decisions below. Constraining\nrecords: GDR-0001, GDR-0006, GDR-0010, GDR-0013. This document is where\nthe product is planned as one thing; each piece that lands still gets its\nown record.

\n

Timbre started as a key you hold to talk. It is about to become the place\nwhere the words you use get better: spelling, vocabulary, phrases,\nacronyms. This map lays out every piece, which surface owns it, where its\ndata lives, and what crosses the one boundary the product is built on —\nso nothing is built twice and nothing falls between two surfaces.

\n

1. Three pillars

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PillarWhat it isToday
SpeakDictate, fix/shorten/plain/explain, read aloud, say a to-do. Everything on-device, nothing leaves the Mac.Shipped (0.3.x, 0.4.0 forming)
LearnThe Library — words, acronyms, phrases, spellings you are collecting — plus a profile that makes "explain" right for your industry, a word of the day, and practice that uses your own voice.Vocabulary, corrections and definitions exist as three Settings lists. Nothing else yet.
RunBackstage: releases, decisions, plans, evals, launch, architecture, brand. The business, in one place.Shipped
\n

Speak is the wedge and stays the wedge: dictation that never leaves your\nMac. Learn is the reason to open the app when you are not dictating, and\nthe reason to want it on your phone. Run is ours.

\n

2. Surfaces

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SurfaceOwnsDoes not do
Mac appEverything in Speak. The Library's capture side: a word you taught, a correction, a definition, a word you had explained — each lands in the Library. The Mac is where words are met.Nothing cloud-side. Zero network requests (GDR-0001/0013).
iPhone app (planned)The Library in your pocket: review, practise, word of the day, add a word you heard. The phone is where words are kept.No dictation into other apps (iOS cannot), no commands. It is a companion, not a port.
WebsiteThe claim, the download, the network list.Accounts, sync, anything personal.
BackstageRunning the product.Anything a user sees.
Cross-platform client (open)A Library on Android or the web, if ever.Only exists if there is an account to sign into — see §4.
\n

3. The Library

\n

One store replaces three lists. Every entry has a kind, and the kinds\nare exactly the four things Hugo wants to get better at, plus the one the\napp already keeps:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KindExampleWhere it comes fromWhat uses it
wordephemeral — short-livedexplain on a word; added by hand; word of the daythe polisher's vocabulary; practice
acronymADR — Architecture Decision Recorddefine in Settings; explain's answer, keptexplain answers from it first (GDR-0012)
phrasea canary in the coal mine — an early warningexplain on a selection; added by handpractice; the polisher leaves it intact
spellingdefinately → definitelyfix corrected it; the spell checker fallbackpractice ("spell it"); a correction if it keeps happening
correctiontimber kit → TimbreKittaught in Settings; one day from your own editsCorrectionTable, before the model (GDR-0011)
\n

An entry carries: the term, its meaning, an example sentence, where it\ncame from (which app, dictated or typed, on which day), tags including the\nindustry it belongs to, a strength that practice raises and time lowers\n(the spaced-repetition number), and its history. Nothing in an entry is\never transmitted by the Mac app; the entry is the user's.

\n

Profile. Industry (one or more), role, first language. Used in two\nplaces: explain's prompt ("the reader works in healthcare, so PA means\nphysician assistant before it means personal assistant"), and the word of\nthe day's choice of lists. Lives in the Library, syncs with it.

\n

4. The one boundary, and the sync decision

\n

The Mac binary makes no network requests. That is the claim on the\nheadline, falsifiable with a network monitor, and the entire competitive\nwedge (GDR-0001, GDR-0006, GDR-0013). The Library wants to be on the phone.\nThere are two ways to get it there, and they are not equal:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
A. iCloudB. A Timbre account
HowCloudKit, private database, the user's own iCloud. Apple's daemons do the syncing; the binary still makes zero requests. GDR-0010 already accepted this shape for the dictionary.Supabase (already running Backstage's auth), the apps call it.
ReachesMac and iPhone (and iPad, Watch).Anything with a browser.
NeedsThe iCloud capability on the App ID (done), a CloudKit container, an entitlement. No server, no cost, no account to create.Sign-up, sessions, a schema with row-level security, a privacy policy, GDPR handling, uptime.
Costs the claimNothing. /network stays at one entry.The headline needs a second asterisk: the app phones home when you sign in. Amends GDR-0013; /network gains entries.
When it is rightNow.When a non-Apple client is real and wanted — not before.
\n

Recommendation: A first, and design the Library's store so that B is a\nsecond backend behind the same interface, not a rewrite. "Apple pure" is\nnot a lite tier; it is the product. B becomes a decision the day there is\nan Android or web Library to sign into, and it gets its own record then.

\n

5. Learning, using what Timbre already does

\n

Practice should use Timbre's own abilities rather than becoming a flash-card\napp with a microphone bolted on:

\n\n

6. No gaps, no duplication

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CapabilityOwnerStoreSync
Dictation, commands, read aloud, to-dosMac app——
Capturing a Library entry from useMac appLibrary (local)iCloud
Browsing, editing the LibraryMac Settings → Library; iPhoneLibraryiCloud
ProfileiPhone and Mac, same screenLibraryiCloud
Practice, word of the dayiPhone first; Mac menu laterLibrary (strength, history)iCloud
Usage countMac appUserDefaultsnever (GDR: this Mac only)
Dictation capture for tuningMac appjsonl on disknever (GDR-0004)
Releases, decisions, plans, evals, launch, architecture, brandBackstagethe repoCI
\n

Shared logic lives in one place: the Library's model, parsing and practice\nscoring move into a platform-neutral TimbreCore package that the Mac app\nand the iPhone app both import; TimbreKit keeps the macOS-only pipeline.\nThat split is a record of its own (an ADR) before the first iOS line.

\n

7. Phases

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PhaseDeliversProof
00.4.0: icon, disk image, to-dos, plain, live typing. Launch.Public.
1The Library on Mac. One store with kinds; Settings › Dictionary becomes Library; explain, fix and define write to it; export to a file.Every existing list migrates; nothing lost.
2TimbreCore + iCloud sync. The split, the CloudKit container, sync on two Macs.Teach on one Mac, see it on the other, nettop still empty.
3Timbre for iPhone. The Library, profile, word of the day, Spell it.On the phone a minute after teaching on the Mac.
4Practice that listens. Say it, Explain it, strength and streaks.A drill corpus the harness can score.
5Profile-aware explain on the Mac.A commands corpus case per industry.
—Account and cross-platform.Decided when phase 3 has users asking.
\n

8. Decisions this map asks for

\n
    \n
  1. Sync by iCloud first, account later or never (§4).
    2. \n
  2. The iPhone app is a companion — the Library and practice — not a dictation app (§2).
    3. \n
  3. One Library, five kinds, replacing the three Settings lists (§3).
    4. \n
  4. TimbreCore split before the first iOS file (§6).
    5. \n
  5. Practice uses the voice — drills are scored like commands, with a corpus (§5).
    6. \n
\n" + "status": "2026-10-11 · Status: the map; its five decisions were taken on 2026-10-14 and are recorded in GDR-0023. Constraining records: GDR-0001, GDR-0006, GDR-0010, GDR-0013. This document is where the product is planned as one thing; each piece that lands still gets its own record.", + "html": "

2026-10-11 · Status: the map; its five decisions were taken on 2026-10-14\nand are recorded in GDR-0023. Constraining records: GDR-0001, GDR-0006,\nGDR-0010, GDR-0013. This document is where the product is planned as one\nthing; each piece that lands still gets its own record.

\n

Timbre started as a key you hold to talk. It is about to become the place\nwhere the words you use get better: spelling, vocabulary, phrases,\nacronyms. This map lays out every piece, which surface owns it, where its\ndata lives, and what crosses the one boundary the product is built on —\nso nothing is built twice and nothing falls between two surfaces.

\n

1. Three pillars

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PillarWhat it isToday
SpeakDictate, fix/shorten/plain/explain, read aloud, say a to-do. Everything on-device, nothing leaves the Mac.Shipped (0.3.x, 0.4.0 forming)
LearnThe Library — words, acronyms, phrases, spellings you are collecting — plus a profile that makes "explain" right for your industry, a word of the day, and practice that uses your own voice.Vocabulary, corrections and definitions exist as three Settings lists. Nothing else yet.
RunBackstage: releases, decisions, plans, evals, launch, architecture, brand. The business, in one place.Shipped
\n

Speak is the wedge and stays the wedge: dictation that never leaves your\nMac. Learn is the reason to open the app when you are not dictating, and\nthe reason to want it on your phone. Run is ours.

\n

2. Surfaces

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SurfaceOwnsDoes not do
Mac appEverything in Speak. The Library's capture side: a word you taught, a correction, a definition, a word you had explained — each lands in the Library. The Mac is where words are met.Nothing cloud-side. Zero network requests (GDR-0001/0013).
iPhone app (planned)The Library in your pocket: review, practise, word of the day, add a word you heard. The phone is where words are kept.No dictation into other apps (iOS cannot), no commands. It is a companion, not a port.
WebsiteThe claim, the download, the network list.Accounts, sync, anything personal.
BackstageRunning the product.Anything a user sees.
Cross-platform client (open)A Library on Android or the web, if ever.Only exists if there is an account to sign into — see §4.
\n

3. The Library

\n

One store replaces three lists. Every entry has a kind, and the kinds\nare exactly the four things Hugo wants to get better at, plus the one the\napp already keeps:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KindExampleWhere it comes fromWhat uses it
wordephemeral — short-livedexplain on a word; added by hand; word of the daythe polisher's vocabulary; practice
acronymADR — Architecture Decision Recorddefine in Settings; explain's answer, keptexplain answers from it first (GDR-0012)
phrasea canary in the coal mine — an early warningexplain on a selection; added by handpractice; the polisher leaves it intact
spellingdefinately → definitelyfix corrected it; the spell checker fallbackpractice ("spell it"); a correction if it keeps happening
correctiontimber kit → TimbreKittaught in Settings; one day from your own editsCorrectionTable, before the model (GDR-0011)
\n

An entry carries: the term, its meaning, an example sentence, where it\ncame from (which app, dictated or typed, on which day), tags including the\nindustry it belongs to, a strength that practice raises and time lowers\n(the spaced-repetition number), and its history. Nothing in an entry is\never transmitted by the Mac app; the entry is the user's.

\n

Profile. Industry (one or more), role, first language. Used in two\nplaces: explain's prompt ("the reader works in healthcare, so PA means\nphysician assistant before it means personal assistant"), and the word of\nthe day's choice of lists. Lives in the Library, syncs with it.

\n

4. The one boundary, and the sync decision

\n

The Mac binary makes no network requests. That is the claim on the\nheadline, falsifiable with a network monitor, and the entire competitive\nwedge (GDR-0001, GDR-0006, GDR-0013). The Library wants to be on the phone.\nThere are two ways to get it there, and they are not equal:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
A. iCloudB. A Timbre account
HowCloudKit, private database, the user's own iCloud. Apple's daemons do the syncing; the binary still makes zero requests. GDR-0010 already accepted this shape for the dictionary.Supabase (already running Backstage's auth), the apps call it.
ReachesMac and iPhone (and iPad, Watch).Anything with a browser.
NeedsThe iCloud capability on the App ID (done), a CloudKit container, an entitlement. No server, no cost, no account to create.Sign-up, sessions, a schema with row-level security, a privacy policy, GDPR handling, uptime.
Costs the claimNothing. /network stays at one entry.The headline needs a second asterisk: the app phones home when you sign in. Amends GDR-0013; /network gains entries.
When it is rightNow.When a non-Apple client is real and wanted — not before.
\n

Recommendation: A first, and design the Library's store so that B is a\nsecond backend behind the same interface, not a rewrite. "Apple pure" is\nnot a lite tier; it is the product. B becomes a decision the day there is\nan Android or web Library to sign into, and it gets its own record then.

\n

5. Learning, using what Timbre already does

\n

Practice should use Timbre's own abilities rather than becoming a flash-card\napp with a microphone bolted on:

\n\n

6. No gaps, no duplication

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CapabilityOwnerStoreSync
Dictation, commands, read aloud, to-dosMac app——
Capturing a Library entry from useMac appLibrary (local)iCloud
Browsing, editing the LibraryMac Settings → Library; iPhoneLibraryiCloud
ProfileiPhone and Mac, same screenLibraryiCloud
Practice, word of the dayiPhone first; Mac menu laterLibrary (strength, history)iCloud
Usage countMac appUserDefaultsnever (GDR: this Mac only)
Dictation capture for tuningMac appjsonl on disknever (GDR-0004)
Releases, decisions, plans, evals, launch, architecture, brandBackstagethe repoCI
\n

Shared logic lives in one place: the Library's model, parsing and practice\nscoring move into a platform-neutral TimbreCore package that the Mac app\nand the iPhone app both import; TimbreKit keeps the macOS-only pipeline.\nThat split is a record of its own (an ADR) before the first iOS line.

\n

7. Phases

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PhaseDeliversProof
00.4.0: icon, disk image, to-dos, plain, live typing. Launch.Public.
1The Library on Mac. One store with kinds; Settings › Dictionary becomes Library; explain, fix and define write to it; export to a file.Every existing list migrates; nothing lost.
2TimbreCore + iCloud sync. The split, the CloudKit container, sync on two Macs.Teach on one Mac, see it on the other, nettop still empty.
3Timbre for iPhone. The Library, profile, word of the day, Spell it.On the phone a minute after teaching on the Mac.
4Practice that listens. Say it, Explain it, strength and streaks.A drill corpus the harness can score.
5Profile-aware explain on the Mac.A commands corpus case per industry.
—Account and cross-platform.Decided when phase 3 has users asking.
\n

8. Decisions this map asked for — taken 2026-10-14 (GDR-0023)

\n
    \n
  1. Sync by iCloud first, account later or never (§4). Taken: iCloud first; the store built behind a sync interface.
    2. \n
  2. The iPhone app is a companion — the Library and practice — not a dictation app (§2). Taken: companion; no keyboard extension planned.
    3. \n
  3. One Library, five kinds, replacing the three Settings lists (§3). Taken: five kinds, migrated on the Mac first.
    4. \n
  4. TimbreCore split before the first iOS file (§6). Taken: created with the Library.
    5. \n
  5. Practice uses the voice — drills are scored like commands, with a corpus (§5). Taken: Spell it first.
    6. \n
\n" } ]