add architecture explainer to ngit skill

Explain the two-layer model: git state (refs) on Nostr relays,
git data (objects) on git servers, and how grasp servers combine
both. Covers decentralisation and ease of switching providers.

1 files changed, 11 insertions, 0 deletions

diff --git a/skills/ngit/SKILL.md b/skills/ngit/SKILL.md
index 5c4fc1c..9773bff 100644
--- a/skills/ngit/SKILL.md
+++ b/skills/ngit/SKILL.md
@@ -13,6 +13,17 @@ ngit makes `clone`, `fetch`, `push` work with `nostr://` URLs and adds a CLI for
 - Install: `curl -Ls https://ngit.dev/install.sh | bash` (installs `ngit` and `git-remote-nostr`)
 - Web UI: https://gitworkshop.dev
 
+## How it works
+
+Git has two distinct layers that ngit separates:
+
+- **Git state (refs)** — which commit each branch/tag points to — is published as signed events on Nostr relays. This is the source of truth for the repository.
+- **Git data (objects)** — the actual commits, trees, and blobs — is stored on ordinary git servers (any server that speaks the git protocol).
+
+When you `git fetch`, `git-remote-nostr` reads the current ref state from Nostr relays, then fetches the corresponding objects from the git server(s) listed in the repository announcement. Because the state lives on Nostr and the data can live anywhere, git servers are interchangeable — switching providers requires no coordination with contributors.
+
+**Grasp servers** are a convenience: they combine a Nostr relay and a git server into a single hosted service (e.g. `relay.ngit.dev`), so a single URL covers both layers. You can use separate relays and git servers if you prefer.
+
 ## Key rules
 
 - **Always use `--json`** on `ngit` commands when reading output — far easier to parse than human-readable text. `git` commands do not support `--json`.