mantra-kmp/docs/README.md

mantra docs

Notes on the parts of this app whose behaviour is not recoverable by reading the code alone — where the reasoning lives in a protocol, a failure mode that is silent, or a decision that looked arbitrary and was not.

document	covers
shared-key-ceremony.md	ChillDKG over NIP-17: the rounds, the approval gates, the chat transcript, participant ordering
shared-key-derivation.md	deriving further keys from the group's threshold key with FROST tweaks — why not BIP32, why no chain code, and the one rule that must not be broken
subgroups.md	a group making another group — the four ceremonies, what the parent's signature actually covers, and why the child's key is fresh rather than derived
subgroups-multiple-parents.md	adding a parent to a group that already exists — two signings and no ceremony, why the child's consent is the whole gate, and the certificate a group can truthfully sign about itself
subgroups-for-entities.md	giving a dialect, an artifact, a translation or a project a room of its own — why the link belongs on the birth certificate rather than in a column, and the screen a dialect needed before it could be asked
frost-batch-signing.md	signing several events in one ceremony — why one nonce can never cover two messages, and the phased schema, wire and UI work that follows from it
marmot-membership.md	how members join an MLS group, and the epoch race that makes a missing member look like a successful invite
member-chronicle.md	handing a member added after the work was done the group's signed record — why the events are not on the wire at all, and why the room's id is enough to verify them
marmot-direct-messages.md	a one-to-one message inside a group as a stock NIP-59 gift wrap — what its MIP-03 carve-out costs, why the sender cannot read their own, and the one query that would broadcast it
mls-skipped-keys.md	why a group event that arrives a moment late is dropped for good, which flows trigger it, the quartz fix, and the partial mitigation in this app
long-running-sync.md	the chat subscriptions that stay open instead of pulling once per screen — why the request queue could not simply hold one, and how the group filter follows the room list
dead-code.md	code in the sync and relay stack that nothing calls, why each piece is still there, and which of it is a bug rather than a leftover
nsec-sign-in.md	signing in with an existing nostr key — why an nsec can never have a wallet behind it, the ten call sites that make it small, and the sign-in machine that was already built and unreachable
npub-sign-in.md	signing in with only a public key — what a key that cannot sign can still see here, why that is a preview rather than a browser, and the four decisions the word settles
multiple-profiles.md	several profiles on one device — why a profile is a credential and a seed is a wallet attached to one, why a switch is a restart rather than a swap, the two entrances the app lacks, and the inbox a switch would silently lose
jvm-target.md	what desktop support cost, phased — why the native chain was already done, why an empty source set in our phoenix fork was the real blocker, and why DAO tests need none of it
ios-build.md	building for an iPhone, following the route the Curated fork walked — the five defects between here and a device, why the fork's "linux cinterop" fix is the one that makes a mac work, and the one annotation that unblocks native by changing every other target
npub-profile-preview.md	showing the person before a direct message is started from a pasted npub — why the preview is a screen keyed by public key, what "found" means when a row can be a placeholder, and the phase that makes the button honest about a key package that never comes
chapter-uploads.md	picking files off a device and having the group sign each one in as a chapter — why N files can never be one signing session, and the four things the single-chapter path gets away with
african-dialect-catalogue.md	filling a group's dialects from a bundled catalogue of the languages most spoken in Africa — why a dialect is a language in a country, why nothing in the schema makes one unique so duplication has to be stopped at proposal time, and the race two admins hit if the picker cannot see what is already being signed
project-feature.md	bringing the server schema's project and its two join models into a group that has no accounts and no server — a creator tag of its own and owners as a signed set of p tags, the role the parser has to be told about or every project lands ownerless, why a membership is its own signed event rather than a list, and the kind band that is already double-booked
material-design-conformance.md	what the M3 foundations actually require, measured against all 43 screens — the colour pairing that renders the app's own proposals invisible, and eight phases that put the decisions back in the theme
curated-to-mantra.md	pulling the Curated fork's thirty-nine commits back under Mantra's names — which lines of work to take, the three decisions, and a measured way to replay a twice-rebranded history without touching seven hundred files by hand
curated-to-mantra-profiles.md	the second pull: the fork's several-profiles line, ten commits and its first schema migration — which of it is a fix Mantra has today, who allocates a schema version number when two trees share one history, and the one conflict, which was Mantra's own
curated-to-mantra-preview.md	the third pull: the profile preview and the extended FAB, eleven commits — a brand token hidden in CamelCase, a commit half in a removed line taken as a partial pick, and the two conflicts the compiler found where git saw none

Start with the ceremony if you are new to this area; the Marmot notes all assume it. Read the skipped-keys note before debugging any "the other device never got it" report — it is silent, and it looks like every other kind of delivery failure. The sync note stands alone, and the dead-code inventory reads as a follow-up to it. The batch-signing note is a phased plan that has been built: read it after the derivation note, whose one rule is the same one it is built around. The member chronicle note is a phased plan that has not been built, and reads as the membership note's unanswered half: what a member who joins late can be given, and the one thing they cannot. The jvm-target note is unrelated to all of them: it is a build and packaging story. The subgroups note is a phased plan that has been built; it assumes both shared-key notes and reads as the ceremony's second half — what a group does once it has a key, and what it can say about a group that does not yet. The multiple-parents note is a phased plan that has been built, and reads only after it: it takes the one assumption that note never had to state — that a lineage is settled at founding — and finds that dropping it costs less than founding a subgroup does, because no ceremony is involved. The Material Design note is a phased plan that has not been built, and is the only one about what the app looks like rather than what it does; read the jvm-target note first if you want to know why its adaptive-layout phase exists. The curated-to-mantra note is a phased plan that has been built, save for its last phase, which is a decision: it is about the repository rather than the app, and reads alone, except that its first decision leans on the derivation note's one rule. Two of the lines it pulled -- the group's nostr identity and the curated lists -- were taken out again the same day, and its record says what went and what stayed. The nsec and npub sign-in notes arrived with it and record what they built. The profiles pull note is the same exercise a second time, planned with its dry run already done and built the same day; read it after the first, because it assumes the method and the three decisions and only says what changed — chiefly that the tree is no longer a superset, and what the check for an exact pull becomes when it is not. The preview pull note is the third and shortest; read it for the two kinds of resolution the first two never needed. The nsec sign-in note is a phased plan that has been built; it inherits the key-storage decision from the jvm-target note and drives the navigation state machine NavigationViewModel.processLocalAccount implements, so read it with the code open, and read its table of where the build chose differently first. The npub sign-in note is a phased plan that has been built, and reads as that plan's out-of-scope note answered: it takes the Identity type and the sign-in machine as given and asks what an identity with no secret is for, before it asks how to build one; read its table of where the build chose differently first. The multiple-profiles note is a phased plan that has been built, and reads as the third of the sign-in notes: it asks what happens when the device holds two identities, and its first phase changes one rule the other two share — a seed's key becomes a credential like any other — so read it with StoredIdentity.merge, SovereignWalletViewModel.switchToIdentity and the startup screen open, and read its table of where the build chose differently first. The npub profile preview note is a phased plan that has been built, and is the smallest of the plans: it changes the entrance to the direct-message flow and nothing past it, so read it with StartDirectMessageToNpubOrNip05Dialog and ChatRoomMessagingViewModel.initiateNewChat open, its four decisions before its four phases, and its table of where the build chose differently first. The chapter uploads note is a phased plan that has been built, and is the only one that starts from another codebase: it mirrors the mantra.press web app's multi-file upload under this app's rule that the group, not the uploader, is the author. Read the batch-signing note first — its three limits are the whole shape of this one — and read its four-defects section even if the feature is never built, because each of those is wrong in the single-chapter path today. Its two splitter phases are separable from the rest and worth reading on their own: what a chunk is, measured against the parser the web app translates with rather than assumed. The African dialect catalogue note is a phased plan that has been built. It is the smallest of the nip30303 plans and the only one whose hard part is an identity rule rather than a ceremony: a dialect's id is a content hash including createdAt, there is no unique index, and the rows are quorum-signed, so two proposals of the same dialect are two rows and neither is wrong by any rule the schema knows. Read its two framing sections before its phases -- they are what every phase is built to keep -- and read the batch-signing note first if the all-or-nothing rule is not already familiar. Its last phase is a fix the feature makes necessary rather than part of it, which is worth knowing before reading the diff.

The projects note is a phased plan that has been built as far as its seventh phase, and is the only one whose starting point is outside this repository: the platform's server schema, mantra-db-models, has had the three models for years. It reads as the translation domain's unanswered question — the app can say what a chapter is and who translated it, and cannot say what any of it is for — so read it after the nip30303 conventions are familiar, its decisions before its phases, and its scope fork before either, because that one changes the shape of the rest, and its table of where the build chose differently first.