2 files changed, 85 insertions, 1 deletions

diff --git a/README.md b/README.md
index 3d172a2..074cde3 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ for code collaboration, nostr is used for:
 - state (ie. git refs)
 - proposals (PRs), issues and related discussion
 
-a git server is still required for data storage and syncing state. multiple git servers can be used for reduncancy and they can be seemlessly swapped out by maintainers just like nostr relays.
+a git server is still required for data storage and syncing state. multiple git servers can be used for reduncancy and they can be seemlessly swapped out by maintainers just like nostr relays. see [maintainer model](docs/architecture/maintainer-model.md) for details on how multi-maintainer repositories work.
 
 eg self-hosted, github, codeberg, etc.
 
diff --git a/docs/architecture/maintainer-model.md b/docs/architecture/maintainer-model.md
new file mode 100644
index 0000000..9aebea7
--- /dev/null
+++ b/docs/architecture/maintainer-model.md
@@ -0,0 +1,84 @@
+# Maintainer Model
+
+How ngit handles multi-maintainer repositories: coordinate discovery, maintainer sets, and the distinction between shared metadata and personal infrastructure.
+
+## Coordinate Discovery
+
+A **coordinate** is a `(kind, pubkey, identifier)` tuple that uniquely identifies a repository on nostr. The pubkey in the coordinate is the **trusted maintainer** (typically the original creator).
+
+ngit discovers the coordinate locally from (in priority order):
+
+1. `nostr://` git remotes
+2. `nostr.repo` git config
+3. `maintainers.yaml`
+
+No network access is required to find the coordinate. The coordinate may exist without a corresponding announcement event on relays.
+
+## Maintainer Set
+
+Each repository announcement (kind 30617) contains a `maintainers` tag listing public keys. These form a recursive set: if Alice lists Bob, and Bob lists Carol, then {Alice, Bob, Carol} are all in the maintainer set.
+
+Each maintainer independently decides who they list. Adding someone to your maintainers tag is an invitation to co-maintain.
+
+## Consuming vs Publishing
+
+The key architectural distinction is between **consuming** repository data (fetching, cloning, listing) and **publishing** it (`ngit init`).
+
+### Consuming: Union Across Maintainers
+
+When consuming repo data, `relays`, `clone` (git server URLs), and `blossoms` are **unioned** across all maintainers' announcement events. This means any maintainer can add a mirror git server or relay and all users benefit automatically.
+
+### Publishing: Personal Infrastructure, Shared Metadata
+
+When publishing via `ngit init`, fields are sourced differently depending on their type:
+
+#### Shared Metadata
+
+Sourced from the **latest event** (by `created_at`) across the maintainer set:
+
+- `name`
+- `description`
+- `web`
+- `hashtags`
+
+Rationale: these are shared identity. If any maintainer updates the project name, all subsequent re-announcements should pick it up.
+
+#### Infrastructure (Personal)
+
+Each maintainer has their own infrastructure preferences. When publishing, infrastructure comes from **my own announcement only**, not the union:
+
+- **Grasp servers** -- where my git+nostr data is hosted. Each grasp server derives:
+  - Clone URL: `https://{server}/{npub}/{identifier}.git`
+  - Relay URL: `wss://{server}`
+  - Blossom URL: `https://{server}`
+- **Additional relays, git servers, blossoms** -- beyond what grasp servers provide
+
+Grasp-format clone URLs belonging to other maintainers are kept as additional git servers (they're part of the union for consumers) but are not treated as my grasp servers.
+
+#### Maintainers
+
+Sourced from **my own announcement only**. Each maintainer independently decides who they list.
+
+If I don't have an existing announcement (first time co-maintaining), the default is `[me, trusted_maintainer]`.
+
+#### Earliest Unique Commit
+
+Cascade: my own event's value, then other maintainers' values, then the local root commit. A mismatch between maintainers may indicate a fork.
+
+#### Identifier
+
+From the existing coordinate. Cannot change without `--force` (changing it creates a new repository).
+
+## Init States
+
+When `ngit init` runs, there are 5 possible states based on what exists locally and on relays:
+
+| State | Condition | Behavior |
+|-------|-----------|----------|
+| **Fresh** | No coordinate found | Must provide name + server infrastructure |
+| **Coordinate Only** | Coordinate exists, no announcement on relays | Requires `--force` (could be a relay/network issue) |
+| **My Announcement** | Announcement exists, I'm the trusted maintainer | Re-publish/update, no force needed |
+| **Co-Maintainer** | Announcement exists, I'm listed as maintainer | Publish own announcement, no force needed |
+| **Not Listed** | Announcement exists, I'm not in maintainer set | Requires `--force` |
+
+See `src/bin/ngit/sub_commands/init.rs` (`InitState` enum) and `tests/ngit_init.rs` for the implementation and test coverage.