Merge public-prelaunch: open-source launch prep + FIPS unit-fallback coverage + companion safe-area fix

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/LICENSE-COMPLIANCE-AUDIT.md

@@ -0,0 +1,108 @@
+# License Compliance Audit — Open-Source Release
+
+Audit date: 2026-07-22. Scope: entire repo (core Rust workspace, neode-ui, apps/*, Android companion, image-recipe ISO, docker/, app-catalog, reticulum-daemon, demo/) plus the external FIPS source and registry-mirrored images.
+
+**Verdict:** the dependency graph is almost entirely permissive (MIT/Apache/BSD) and compatible with a free open-source release. But the repo is not releasable as-is: it has **no license of its own**, one **LGPL Rust dependency**, several **non-redistributable committed assets** (proprietary fonts, unknown-rights media), and **missing attribution machinery**. Everything below is ordered by severity.
+
+---
+
+## STATUS UPDATE — 2026-07-23
+
+**DONE:**
+- MIT adopted. Root `LICENSE` + `NOTICE` added; `license = "MIT"` in all 5 workspace crates (archy-fips-core already had it); `"license": "MIT"` (+ `"private": true`) in all 4 package.json files.
+- Deleted: `Courier_New/`, `Benton_Sans/`, `Redacted/` fonts; `wireguard.apk`; `atob.s9pk`; obsolete `test-install.sh` (all git-rm'd; also removed from `web/dist`).
+- Media provenance resolved: all demo music/photos/posters, UI sfx, backgrounds, and intro video are the author's original work — recorded in `demo/content/README.md` and `NOTICE`.
+- Meshtastic device artwork attributed (`mesh-devices/ATTRIBUTION.md` + NOTICE); icon attribution added (`assets/icon/ATTRIBUTION.md`: game-icons.net CC BY 3.0, pixelarticons MIT).
+- Reticulum decision: include + disclose (NOTICE states the Reticulum License restrictions and that it applies only to the optional daemon).
+- indeedhub: deferred — partnership in place; license the submodule before/at public release.
+- License inventories generated: `core/THIRD-PARTY-LICENSES.md` (649 crates) and `neode-ui/THIRD-PARTY-LICENSES.md` (runtime deps + fonts + vendored).
+
+**REMAINING (code changes, awaiting review — see sections below for detail):**
+1. Replace `zbase32` (LGPL-3.0+) with `z32` or original impl — §2.
+2. Swap `redis:7.4.8` → Valkey in `scripts/image-versions.sh` and deploys — §3.
+3. Delete dead StartOS-derived crates `core/{js-engine,container-init,models,helpers}` — §4.
+4. Attribution build integration: cargo-about in CI → ship full license texts in ISO; vite/rollup license plugin (or UI licenses page) for the web bundle; Android OSS-licenses screen — §5.
+5. Release-checklist items: per-release Debian source pointer (snapshot.debian.org), catalog `license`/`sourceUrl` fields, restrict ISO image bundling to the audited list — §6.
+6. Before repo goes public: purge deleted fonts/APKs from git history (`git filter-repo`), and verify game-icons author credit.
+
+---
+
+## 1. BLOCKER — the project has no license
+
+There is no `LICENSE`/`COPYING` file anywhere in the repo. No crate in `core/` declares a `license` field; none of the four `package.json` files do either (and the three `apps/*` packages aren't even `private: true`). Until fixed, the code is "all rights reserved" — publicly visible, but legally not open source and not usable by anyone.
+
+**Do:**
+- [ ] Choose a license. **Recommendation: MIT** — the Bitcoin-ecosystem norm (Bitcoin Core, LND are MIT), maximally compatible with everything found in the graph. (Alternatives: Apache-2.0 adds a patent grant; GPLv3 if copyleft is desired — nothing in the deps prevents any of these.)
+- [ ] Add `LICENSE` at repo root with the year and copyright holder.
+- [ ] Add `license = "MIT"` to all five workspace member `Cargo.toml`s (archipelago, container, openwrt, performance, security) and `Android/rust/archy-fips-core` (declares MIT but ships no license file — add one).
+- [ ] Add `"license": "MIT"` to `neode-ui/package.json` and `apps/{morphos-server,router,did-wallet}/package.json`.
+
+## 2. BLOCKER — copyleft dependency that must be replaced
+
+- [ ] **`zbase32 0.1.2` — LGPL-3.0+** — the only hard copyleft blocker in all 649 resolved Rust crates. Direct dep of `archipelago`, used in `core/archipelago/src/network/did_dht.rs` for did:dht z-base-32 encoding. LGPL statically linked into a Rust binary requires shipping relinkable objects/source — impractical. **Replace with the MIT `z32` crate** or a ~30-line original alphabet-substitution implementation.
+
+No GPL, AGPL, SSPL, or unlicensed crates exist anywhere else in the Rust graph. (`r-efi` and `self_cell` list LGPL/GPL only as options in OR-expressions — elect MIT/Apache, no action.)
+
+## 3. BLOCKER — committed files we may not redistribute
+
+Remove from git (and **purge from history** before the repo goes public — they're in past commits):
+
+- [ ] `neode-ui/public/assets/fonts/Courier_New/` — Monotype proprietary font, no license, **unused in CSS**. Delete.
+- [ ] `neode-ui/public/assets/fonts/Benton_Sans/BentonSans-Regular.otf` — commercial Font Bureau typeface, no license, unused. Delete.
+- [ ] `neode-ui/public/packages/wireguard.apk` (17 MB) — official WireGuard Android APK containing GPL-2.0 `libwg` components; redistribution triggers GPL source-offer. **Unreferenced since the FIPS migration** — delete.
+- [ ] `neode-ui/public/packages/atob.s9pk` (24 MB) — Start9 service package, unknown license, referenced only by a test script. Delete.
+- [ ] `demo/content/music/` (18 full tracks, ~150 MB) and `demo/peer-media/` (17 photos/book covers/film posters) — no recorded rights. If they're your own/AI-generated work, document that in a `demo/content/README`; otherwise remove.
+- [ ] `neode-ui/public/assets/video/video-intro.mp4`, `Kratter.MP3`, photographic `bg-*.jpg` backgrounds, UI/arcade sound effects in `assets/audio/` — same: document provenance (user-made per project convention) or replace. `welcome-noderunner.mp3` is ElevenLabs TTS — their commercial-use terms allow this on paid plans; note it.
+- [ ] **Registry: `redis:7.4.8`** (`scripts/image-versions.sh` `REDIS_IMAGE`) — Redis ≥ 7.4 is RSALv2/SSPLv1, **not open source**; re-hosting it on your registry is redistribution under a restricted license. **Switch to Valkey** (BSD-3, already mirrored) everywhere.
+
+## 4. VERIFY — unknown/third-party provenance
+
+- [ ] **`neode-ui/public/assets/img/mesh-devices/` (36 SVGs)** — almost certainly Meshtastic project device artwork (meshtastic/web is GPL-3.0). Confirm source; either replace with original art or comply with the upstream license + attribution.
+- [ ] **`neode-ui/public/assets/icon/`** — `barbarian.svg`, `batteries.svg` match game-icons.net (**CC BY 3.0 — visible attribution required**); pixel-style icons match pixelarticons (MIT). Confirm and add attribution, or replace.
+- [ ] `Redacted/redacted.regular.ttf` — upstream is SIL OFL 1.1 but no license file is shipped. Add `OFL.txt` or delete (unused).
+- [ ] **indeedhub** — submodule (private gitea) not checked out; no known license, yet `indeedhub{,-api,-ffmpeg}:1.0.0` images are distributed via registry/ISO. `indeedhub-ffmpeg` implies a bundled FFmpeg (LGPL/GPL → source-offer obligations). Must license the project and audit the ffmpeg build before public release.
+- [ ] `minmoto/fmcd` v0.8.0 and `ark-bitcoin/bark` (barkd) — binaries redistributed in your images; verify upstream licenses (bark claims Apache-2.0/MIT dual) and include their notices.
+- [ ] **Start9/StartOS heritage** — `core/{js-engine,container-init,models,helpers}` are StartOS-derived (embassy paths, s9pk handling). start-os is MIT → attribution required if kept. **Better: delete these four crates** — they are not workspace members, cannot compile (broken `../../patch-db` path dep), and carry an unpinned `yajrc = "*"` git dep on a moving branch. Deleting removes both the attribution question and dead code.
+- [ ] **Reticulum (RNS 1.3.5 + LXMF)** — verified: custom "Reticulum License" — MIT-style **plus field-of-use restrictions** (no systems designed to harm humans; no AI/ML training-dataset use). Redistribution is permitted, so shipping the PyInstaller `archy-reticulum-daemon` binary is fine **if** the license text is included with it — but the OS cannot claim to be 100 % OSI-open-source while bundling it. Options: include + disclose (recommended, matches "plan for decentralization" honesty), or make the daemon an optional download.
+
+## 5. REQUIRED — attribution / notice machinery (currently absent)
+
+Nearly every permissive license (MIT/BSD/ISC/Apache) requires reproducing copyright + license text **in distributed binaries** — and right now every distribution channel strips them:
+
+- [ ] **Rust binaries** (649 crates, ~85 % MIT/Apache dual): generate `THIRD-PARTY-LICENSES` with `cargo-about` (or `cargo-license`) in CI; ship it in the ISO at e.g. `/usr/share/doc/archipelago/`. Include **ring's three license files** (LICENSE, LICENSE-BoringSSL, LICENSE-other-bits) and note the system OpenSSL (Apache-2.0) linked via `ssh2`.
+- [ ] **Web bundle**: Vite/esbuild strips all `@license` comments from `web/dist`. Add `rollup-plugin-license`/`vite-plugin-license` to emit a third-party attribution file, or add an "Open-source licenses" page in the UI. Runtime deps needing notices: vue/vue-router/pinia/vue-i18n (MIT), d3 (ISC), leaflet (BSD-2), dompurify (elect Apache-2.0 of its MPL/Apache dual), fuse.js (Apache-2.0), qrcode/qr-scanner/qrloop/buffer/fast-json-patch (MIT).
+- [ ] **Android APK**: `packaging.excludes` strips `META-INF` license texts and there is no licenses screen. Add an OSS-licenses screen or bundled `licenses.txt` covering AndroidX/Compose/OkHttp/ZXing (Apache-2.0), **fips © 2026 Johnathan Corgan (MIT — the core of the VPN feature)**, tokio/tracing (MIT), subtle (BSD-3), tun (WTFPL — permissive, just list it), secp256k1 family (CC0). Generate the Rust side from the committed `Cargo.lock` with cargo-about.
+- [ ] **AIUI demo bundle** (`demo/aiui/` — committed minified build): bundles Mermaid, Cytoscape, KaTeX, D3, Lodash, Workbox (all MIT/BSD). Add a `THIRD-PARTY-LICENSES` file next to it (or rebuild with a license plugin).
+- [ ] Keep the intact MIT headers in the two vendored `qrcode.js` copies (docker/lnd-ui, docker/electrs-ui) — already compliant, don't minify them.
+- [ ] Fonts kept: Montserrat (OFL.txt present ✓), Open Sans (Apache LICENSE.txt present ✓) — keep license files adjacent to the font files in dist.
+
+## 6. REQUIRED — distribution-level obligations (ISO & registry)
+
+The ISO redistributes a full Debian (trixie) system plus ~29 container image tarballs; the private registry re-hosts upstream images. Re-hosting = redistribution, same obligations as bundling.
+
+- [ ] **GPL source offer for the ISO** — kernel, GRUB, busybox/live-boot, coreutils, nftables, cryptsetup, wireguard-tools, SYSLINUX `isohdpfx.bin`, etc. Easiest compliance: keep `/usr/share/doc/*/copyright` (the build already does ✓) **and** publish, per release, either a mirror of the exact Debian source packages (`apt-get source` snapshot / snapshot.debian.org pointer) or a written offer in the docs. Add this to the release checklist.
+- [ ] **AGPLv3 images redistributed** (mempool, Grafana, Vaultwarden, SearXNG, PhotoPrism, Nextcloud, Immich, CryptPad, MinIO): AGPL compliance = make corresponding source available. You ship a **modified** mempool-frontend (`docker/mempool-frontend` entrypoint patch) — the patch is in-repo, so compliance is met once the repo is public; state this in docs. For unmodified images, link upstream sources in the app catalog.
+- [ ] **GPLv2/GPLv3 images** (MariaDB, Jellyfin, AdGuard Home, strfry): unmodified redistribution → provide license text + upstream source links (a `license` + `sourceUrl` field per `app-catalog/catalog.json` entry solves this catalog-wide).
+- [ ] **Non-free firmware** (firmware-realtek/iwlwifi/misc/linux-nonfree, intel/amd microcode): redistributable but proprietary — disclose in docs ("includes non-free firmware for hardware support"), like Debian's own non-free-firmware ISOs do.
+- [ ] The ISO build's live-server image capture (`podman save` of whatever matches on the dev server) is a compliance hazard — bundle only from the audited image list.
+- [ ] FIPS daemon (jmcorgan/fips v0.4.1, MIT ✓) and nostr-rs-relay binary (MIT ✓): include their license texts in the notices bundle.
+
+## 7. Housekeeping (supports compliance)
+
+- [ ] Add lockfiles + pinned versions in `apps/*` (currently floating `^` ranges, violating the project's own pinning rule) — reproducibility is also what makes license audits stay true.
+- [ ] `Android` fips dep is pinned to a personal fork rev (`9qeklajc/fips-native@46494a74`) — mirror or vendor it so outside contributors can build.
+- [ ] Move `@types/dompurify` to devDeps; refresh stale `neode-ui/node_modules`.
+- [ ] Add a `NOTICE` file at root naming: fips (Johnathan Corgan, MIT), Start9 start-os (if any derived code remains), Kazuhiko Arase qrcode.js, font licenses, icon attributions.
+- [ ] Consider CI license gating: `cargo-deny` (Rust) + `license-checker` (npm) with an allowlist, so new copyleft deps are caught at PR time.
+
+---
+
+## Quick reference: what's already clean
+
+- All 649 Rust crates except `zbase32`: permissive or dual-licensed.
+- All 833 npm packages in neode-ui: no GPL/AGPL anywhere; only dev-tool LGPL (sharp's libvips, never distributed).
+- Android Gradle deps: 100 % Apache-2.0, all pinned, no Play Services/telemetry.
+- FIPS mesh: MIT (© 2026 Johnathan Corgan) — keep notice.
+- js-engine binds deno_core (MIT) as a crate, nothing vendored — moot if dead crates are deleted.
+- reticulum-daemon Python is original code; obligations attach only to the PyInstaller binary (see §4).
+- Bitcoin Core/Knots, LND, BTCPay, Electrs, Fedimint, core-lightning, Gitea, Home Assistant, Tailscale, Portainer, Uptime-Kuma, filebrowser, ollama, penpot: MIT/Apache/BSD/Zlib/MPL — link + notice is enough.

docs/OPEN-SOURCE-READINESS-PLAN.md

@@ -27,6 +27,75 @@ is GREEN and must stay green. Re-run after any orchestrator/lifecycle change (Ph
 especially). All cargo verification uses `--all-features` to match CI. Stage by explicit
 path, never `git add -A` (shared tree).
 
+## Current local pass status
+
+This branch is replayed on top of `origin/main` as `public-prelaunch`.
+
+Completed locally in this pass:
+
+- Redacted the two tracked Anthropic API key literals from
+  `scripts/setup-aiui-server.sh` and
+  `image-recipe/_archived/build-auto-installer-iso.sh`.
+- Removed `Android/app/debug.keystore` and `core/.env.production` from the
+  source tree; copies were preserved in
+  `~/Desktop/archipelago-sensitive-backup-2026-07-27/`.
+- Reworked `scripts/audit-secrets.sh` to scan tracked source more aggressively
+  and to catch non-example env files and credential file patterns.
+- Reworked `scripts/validate-app-manifest.sh` so the current `app:` manifest
+  schema can be audited without a Python `PyYAML` dependency.
+- Updated root/community docs, CI, PR template, app developer notes, and
+  container/deployment docs toward public contributor expectations.
+- Fixed native FIPS activation fallback: nodes that have the packaged
+  `fips.service` but not `archipelago-fips.service` now start the available
+  unit instead of repeatedly failing activation against a missing unit. This
+  now covers startup, supervisor self-heal, manual dashboard start/reconnect,
+  and post-onboarding activation. The UI now labels the action as `Start`
+  instead of making native FIPS look like an installable app.
+- Fixed the FIPS app-port relay design so it binds relays to the node's FIPS
+  ULA instead of wildcard `[::]`, avoiding collisions with Podman-published app
+  ports such as FileBrowser `8083` and Botfights `9100`.
+- Added `docs/nostr-git-source-hosting.md`, a NIP-34/ngit/GRASP source hosting
+  plan using a Bitcoin Core-style maintainer model: public review and easy
+  forks, with canonical merge rights held by a small signed maintainer set.
+
+Verified locally:
+
+- `./scripts/audit-secrets.sh` passes.
+- Full `apps/*/manifest.yml` repository audit passes with warnings only.
+- `bash -n` passes for the edited shell scripts.
+- Targeted FIPS dashboard vitest passes.
+- Targeted Rust tests for FIPS service unit detection and FIPS app relay
+  address selection pass.
+
+Verified on a Linux Archipelago verification node:
+
+- Native FIPS was restored by starting the already-installed packaged
+  `fips.service`; the daemon became active and joined the FIPS tree.
+- Correct local lifecycle API endpoint is HTTP, not HTTPS
+  (`ARCHY_HOST=127.0.0.1 ARCHY_SCHEME=http`).
+- Read-only lifecycle run progressed past login and confirmed required
+  containers, Bitcoin RPC, ElectrumX TCP, and manifest port-drift checks, but
+  did not complete cleanly: `botfights` and `filebrowser` remained in
+  `restarting` longer than the matrix window, and the LND `lncli getinfo`
+  probe hung. Do not run the destructive gate until those live-node issues are
+  understood.
+- After the node updated to `1.7.116-alpha`, `botfights`, `filebrowser`, and
+  `lnd` were active/running and ports `8083`/`9100` were held by Podman's
+  `rootlessport` as expected. The packaged `fips.service` remained installed
+  and enabled but inactive, so the native FIPS service fallback should still
+  ship before the public launch.
+
+Still required before public publish:
+
+- Rotate/revoke compromised credentials listed in Phase 0.
+- Finish Phase 1 password/node/token sanitization beyond the two API keys.
+- Publish from fresh history after the sanitized tree is final.
+- Run full Rust, frontend, Android, and lifecycle gate verification.
+- Resolve the live-node lifecycle blockers above, then rerun the read-only
+  suite followed by the destructive gate only on an approved verification node.
+- Decide the canonical Archipelago maintainer npub and merge-maintainer npub
+  list before publishing the Nostr Git source-hosting workflow.
+
 ---
 
 ## Phase 0 — Credential rotation (immediate, independent of the repo)

docs/app-manifest-spec.md

@@ -146,7 +146,7 @@ app:
     path: /health
   interfaces:
     main:
-      type: web
+      type: ui
       port: 8090
 ```
 

docs/developer-guide.md

@@ -74,9 +74,10 @@ archy/
 
 ### Prerequisites
 
-- **macOS** (development machine): Node.js 20+, npm
-- **Linux server** (`192.168.1.228`): Rust toolchain, Podman, Nginx, Debian 13
-- SSH key: `~/.ssh/archipelago-deploy`
+- Node.js 20+ and npm for frontend development.
+- Rust stable for backend development.
+- Linux with Podman, systemd, and Nginx for host integration work.
+- Debian 13 is the target runtime for release validation.
 
 ### Local Frontend Development
 
@@ -86,17 +87,18 @@ npm install
 npm start         # Vite dev server on :8100, mock backend on :5959
 ```
 
-The dev server at `http://localhost:8100` uses a mock backend. Login with `password123`.
+The dev server at `http://localhost:8100` uses a mock backend.
 
 ### Deploying Changes
 
-**Never build Rust on macOS.** The deploy script rsyncs source to the Linux server and builds there.
+Release and host-integration builds should run on Linux. The deploy script rsyncs
+source to a configured Linux target and builds there.
 
 ```bash
-# Deploy to live server (builds backend + frontend, restarts services)
+# Deploy to the configured primary target (builds backend + frontend, restarts services)
 ./scripts/deploy-to-target.sh --live
 
-# Deploy to both servers
+# Deploy to both configured targets
 ./scripts/deploy-to-target.sh --both
 ```
 
@@ -114,14 +116,16 @@ The deploy script:
 # Frontend tests
 cd neode-ui && npm test
 
-# Backend tests (on dev server via SSH)
-ssh -i ~/.ssh/archipelago-deploy archipelago@192.168.1.228 \
-  "cd ~/archy/core && cargo test --all-features"
+# Backend tests
+cd core && cargo test --all-features
 
 # Both
 ./scripts/run-tests.sh
 ```
 
+`scripts/run-tests.sh` can run backend tests on a Linux target when
+`ARCHIPELAGO_SSH_HOST` and `ARCHIPELAGO_SSH_KEY` are set.
+
 ## Adding a New RPC Endpoint
 
 ### 1. Create the Handler
@@ -200,7 +204,7 @@ async myAction(params: { name: string }): Promise<{ ok: boolean; result: string
 
 ```bash
 ./scripts/deploy-to-target.sh --live
-curl -X POST http://192.168.1.228/rpc/v1 \
+curl -X POST http://<node-host>/rpc/v1 \
   -H "Content-Type: application/json" \
   -b "archipelago_session=YOUR_SESSION" \
   -d '{"method":"mymodule.action","params":{"name":"test"}}'
@@ -309,5 +313,5 @@ mod tests {
 2. Make changes following the standards above
 3. Test locally: `cd neode-ui && npm test`
 4. Deploy to dev server: `./scripts/deploy-to-target.sh --live`
-5. Verify at `http://192.168.1.228`
+5. Verify on your configured development target
 6. Commit with conventional format: `feat: add my feature`

docs/nostr-git-source-hosting.md

@@ -0,0 +1,252 @@
+# Nostr Git Source Hosting Plan
+
+This plan describes how Archipelago can publish and accept contributions to its
+source code through `ngit`, NIP-34, and GRASP while keeping the developer
+experience inside Archipelago.
+
+## Goals
+
+- Publish Archipelago source from a sanitized, fresh-history repository.
+- Make the in-app registry the primary onboarding path for contributors.
+- Let contributors clone, branch, push PR branches, open PRs, and discuss issues
+  with a Nostr identity from their Archipelago node.
+- Follow the Bitcoin Core development model: broad public review and easy forks,
+  with canonical merge authority held by a small maintainer set.
+- Give contributors full read, fork, and proposal rights, but no direct merge
+  rights on the canonical repository.
+- Keep the official maintainer identity and merge authority separate from user
+  node identities.
+
+## Current Building Blocks
+
+Archipelago already has most of the primitives needed for this:
+
+- App manifests and the app registry already install developer tooling as
+  rootless Podman apps.
+- The `gitea` app provides a conventional fallback Git UI and package registry.
+- The app launcher already exposes a consent-gated NIP-07 bridge for launched
+  apps using `getPublicKey`, `signEvent`, NIP-04, and NIP-44 requests.
+- The backend exposes node and identity Nostr signing RPC methods.
+- FIPS gives nodes a stable mesh identity and private transport path, but repo
+  announcements and PRs should remain NIP-34 compatible on normal Nostr relays.
+- DWN protocol registration exists and can be used later for local contribution
+  metadata/cache, but should not be required for the first public workflow.
+
+## Protocol Basis
+
+Use existing Nostr Git conventions rather than inventing an Archipelago-only
+protocol:
+
+- NIP-34 repository announcement events identify repositories with kind `30617`.
+- NIP-34 repository state events publish branch/tag refs with kind `30618`.
+- NIP-34 patches, pull requests, PR updates, issues, and status events use kinds
+  `1617`, `1618`, `1619`, `1621`, and `1630`-`1633`.
+- `ngit` provides the `git-remote-nostr` helper for `nostr://` clone URLs and PR
+  branches.
+- GRASP servers provide Git Smart HTTP storage while Nostr events remain the
+  authority for repository identity, refs, PRs, issues, and maintainer state.
+
+Primary references:
+
+- https://nips.nostr.com/34
+- https://docs.rs/crate/ngit/latest/source/README.md
+- https://ngit.dev/grasp/
+
+## Recommended Architecture
+
+### Apps
+
+Create two first-party apps:
+
+- `ngit`: CLI/runtime package containing `ngit` and `git-remote-nostr`.
+- `archipelago-source`: web UI for cloning Archipelago source, viewing NIP-34
+  issues/PRs, opening branches, and submitting PR events.
+
+The `archipelago-source` app should depend on `ngit`. It can also recommend
+Gitea for users who want a conventional local web Git UI, but Gitea should not
+be the source of truth for public contribution permissions.
+
+### Contributor Onboarding
+
+When the user installs `archipelago-source` from the registry:
+
+1. Show a modal before first launch: "Contribute to Archipelago".
+2. Explain that the app will use their Archipelago Nostr identity to clone and
+   sign contribution events.
+3. Display the maintainer repository announcement, clone URL, maintainer npub,
+   and relay/GRASP endpoints.
+4. Ask for consent to:
+   - fetch repository metadata from configured relays,
+   - clone source through `nostr://`,
+   - create local branches,
+   - sign NIP-34 issue/PR/comment events,
+   - push PR branches to approved GRASP servers.
+5. Store approval per app origin, identity id, repository id, and relay set.
+
+This should build on the existing NIP-07 app-launcher bridge, but use a more
+specific permission scope than the generic sign-event approval.
+
+### Identity And Permissions
+
+Use four identity classes:
+
+- `archipelago-maintainer`: an offline or tightly controlled Nostr key that
+  signs the canonical kind `30617` repo announcement and status/merge events.
+- `archipelago-merge-maintainer`: one of the small set of maintainer npubs
+  allowed to advance canonical refs and publish valid merged/applied status.
+- `archipelago-build`: release automation key for signed release artifacts and
+  CI status events. It must not have merge authority.
+- `contributor`: user node or app-specific identity used for PRs, issues, and
+  comments.
+
+Contributor rights:
+
+- Clone the repository.
+- Open issues.
+- Push proposal branches using `pr/<npub>/<short-topic>` or `pr/<event-id>`.
+- Publish NIP-34 PR/update/comment events.
+- Rebase and update their own PR branch.
+- Run local validation and attach status evidence.
+
+Contributor restrictions:
+
+- Cannot update `refs/heads/main` or release branches in canonical state.
+- Cannot publish maintainer-valid merge/applied status.
+- Cannot alter the canonical repository announcement.
+- Cannot publish release catalog signatures.
+
+Maintainer rights:
+
+- Publish/update the canonical repo announcement.
+- Publish canonical `refs/heads/main` state.
+- Mark PRs merged/closed/draft via NIP-34 status events.
+- Sign release tags and catalog updates.
+
+Fork rights:
+
+- Any contributor can create their own NIP-34 kind `30617` repository
+  announcement for a fork.
+- Fork announcements should use the NIP-34 `u` tag to point back to the
+  canonical `archy` repository.
+- The source app should make forking a first-class path: "Fork on Nostr", clone
+  the fork locally, push branches to the contributor's GRASP list, and open PRs
+  back to canonical Archipelago when they want review.
+- Forks can have their own maintainer npubs, relays, policies, and release
+  cadence, but the app should clearly label them as forks unless signed by the
+  canonical maintainer set.
+
+The GRASP server policy should enforce this by accepting pushes to maintainer
+refs only when backed by signed maintainer state, while allowing contributor PR
+refs from their own npubs.
+
+## Repository Layout
+
+Canonical repo announcement:
+
+- repo id: `archy`
+- display name: `Archipelago`
+- clone URLs:
+  - `nostr://<maintainer-npub>/<relay-hint>/archy`
+  - `https://<grasp-host>/<maintainer-npub>/archy.git`
+- relays:
+  - Archipelago-operated relay
+  - at least two public Nostr relays that support the event load
+- GRASP servers:
+  - Archipelago-operated GRASP instance
+  - one public GRASP-compatible mirror
+
+Keep the existing HTTP Git remote as a mirror during launch. The docs can
+present `nostr://` as the preferred contribution path once the workflow is
+proven.
+
+## UI Requirements
+
+The source app should provide:
+
+- A first-run contribution modal with a real Archipelago source graphic, not a
+  generic text-only dialog.
+- Current clone status and local path.
+- Branch list, changed files, commit form, and push/open-PR flow.
+- PR inbox, issue list, maintainer status, and relay health.
+- Explicit identity indicator showing which npub will sign events.
+- A merge rights indicator that clearly says contributors can propose changes
+  but cannot merge them.
+- A fork flow that creates a user-owned NIP-34 repo announcement and remote,
+  then offers "Open PR to Archipelago" from any fork branch.
+- Maintainer badges based only on pinned canonical maintainer npubs, not relay
+  metadata or server-side account names.
+- Links to container docs, deployment docs, manifest spec, and open-source
+  readiness tasks.
+
+## Backend Work
+
+Add an RPC module for source contribution workflow:
+
+- `source.repo-info`: returns canonical announcement, clone URL, relay set,
+  maintainer npubs, and local clone state.
+- `source.ensure-ngit`: verifies the `ngit` app/runtime is installed.
+- `source.clone`: clones or updates the local source checkout.
+- `source.status`: returns branch, dirty files, ahead/behind, and PR state.
+- `source.commit`: creates a local commit from selected files.
+- `source.fork`: creates a contributor-owned NIP-34 fork announcement and local
+  remote.
+- `source.open-pr`: pushes a PR branch and publishes a kind `1618` event.
+- `source.update-pr`: updates the branch and publishes kind `1619`.
+- `source.issue`: publishes a kind `1621` event.
+
+Backend must shell out through a narrow command wrapper, never arbitrary user
+commands. The wrapper should set an isolated working tree under
+`/var/lib/archipelago/source/archy`, run as the Archipelago service user, and
+deny operations outside that path.
+
+## Security Model
+
+- Never expose maintainer private keys to an Archipelago node.
+- Prefer app-specific contributor identities over the node's default identity.
+- Require per-action consent for first PR push, issue creation, and signing any
+  event that tags the canonical repository.
+- Pin the canonical maintainer npub in the app manifest and backend config.
+- Keep the canonical merge-maintainer allow list signed by the
+  `archipelago-maintainer` key; never infer merge rights from GRASP server
+  accounts.
+- Verify the canonical kind `30617` event signature before displaying clone
+  instructions.
+- Treat GRASP servers as untrusted storage; verify Git refs against signed
+  Nostr state.
+- Do not use destructive git operations from the UI without an explicit modal.
+- Store local clones and generated patches outside app container writable roots
+  unless the user exports them.
+
+## MVP
+
+1. Package `ngit` as a first-party app.
+2. Stand up one Archipelago-operated GRASP server and one Nostr relay.
+3. Publish sanitized fresh-history `archy` through `ngit init`.
+4. Add a simple `archipelago-source` app that clones source and links out to the
+   preferred Nostr Git browser.
+5. Add app-launcher consent scopes for repository-specific NIP-34 signing.
+6. Allow issues and PR branch submission from contributor npubs.
+7. Add a one-click fork flow that publishes a contributor-owned fork
+   announcement referencing canonical Archipelago.
+8. Keep maintainer merge/status publication manual.
+
+## Later
+
+- Native PR review UI with file diffs and inline comments.
+- CI status events signed by the build identity.
+- FIPS-first source sync between trusted Archipelago nodes.
+- Private prerelease repositories using NIP-42 allow lists and/or protected
+  events if the ecosystem support is mature enough.
+- Multi-maintainer policy with threshold signatures or explicit maintainer-list
+  rotation events.
+
+## Open Questions
+
+- Which maintainer npub should become canonical for `archy`?
+- Should contributor identities be node-default or app-specific by default?
+- Which GRASP implementation should be deployed first: `ngit-grasp` or another
+  NIP-34/GRASP-compatible relay?
+- Should the source app include a full web Git UI in v1, or launch Gitea/ngit
+  browser links for review while keeping signing/submission native?
+- What exact license and contribution certificate should contributors accept
+  before submitting PR events?