archy/docs/1.8.12-RELEASE-PLAN.md

# Archipelago 1.8.12-alpha Release Plan

**Target date:** 2026-09-11
**Scope:** OTA, signed app registry, canonical Nostr source publication,
Companion 0.5.32 alpha, and an x86_64 installer ISO
**Candidate base:** `f5c0ba85` plus the release-preparation changes documented
here

## Release Outcome

This release is complete only when all of the following are true:

1. Existing nodes can install the signed OTA and retain AIUI, app data, app
   manifests, Nostr identities, Lightning state, and network configuration.
2. A fresh ISO installation boots, reports `1.8.12-alpha`, and serves the same
   dashboard/runtime payload as the OTA.
3. The signed app registry contains GitWorkshop, its embedded manifest, and the
   registry-owned Source promotion.
4. Archipelago's canonical repository is announced by
   `npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg` as the
   stable identifier `archy`, is cloneable through `nostr://`, and opens in
   GitWorkshop from the Source promotion.
5. Contributors can create an issue or proposal without gaining canonical
   merge, release-tag, catalog-signing, or OTA-signing authority.

Shipping GitWorkshop alone does not satisfy item 4. The client is the interface;
the signed NIP-34 announcement and reachable Git object servers are the source
publication.

## Audited Candidate State

### Ready

- The accumulated candidate is committed and the development node is healthy.
- GitWorkshop is healthy behind the authenticated same-origin app gate.
- The app works as a top-level Companion WebView and as a browser tab; the node
  signer remains consent-gated and identity-switchable.
- The Source icon, description, banner, Popular/All Apps placement, and
  maintainer npub are present in the development catalog.
- Payment receipts, Minibits claim persistence, update cancellation, app
  credential interstitials, Gitea limits, certificate guidance, and the pasta
  listener repair are included in the candidate.
- `ngit 2.6.3` and `git-remote-nostr 2.6.3` are installed on the node.
- The existing public Gitea source and Smart HTTP clone endpoints respond with
  HTTP 200.
- The release-root signer exists locally as a binary, while its mnemonic
  remains correctly offline.
- ISO dependencies (`xorriso`, `mksquashfs`, and QEMU) are installed.
- The corrected release gate passed on 2026-09-11: 1,091 frontend tests,
  production UI build, registry candidate/trust checks, Rust check, 114 focused
  backend tests plus orchestration, and live dashboard/AIUI/RPC probes. Android
  lint and the mobile Chromium signer-handoff regression also pass.
- The locally served Companion candidate is 28,157,847 bytes with SHA-256
  `30e0b6257f17bb5e072941ccce6fde04b6c8ae59a49b45169e1920aec1b108cf`.
- The owner accepted the risk of redistributing the pinned, unlicensed
  GitWorkshop revision on 2026-09-11. `NOTICE` and `UPSTREAM.md` disclose that
  decision without claiming an upstream license.

### Not Yet Complete

- This checkout is not logged into `ngit` and has no Nostr repository remote or
  cached kind `30617` announcement.
- The production signed catalog still contains 61 apps but not
  `archipelago-source` or `storefront`; a freshly generated candidate contains
  62 apps, 61 embedded manifests, GitWorkshop 0.4.0, and the Source promotion.
- The previous public Companion download was 0.5.28-debug. A 0.5.32-debug
  candidate has now been built with the same certificate and can update that
  alpha channel; the accepted 0.5.32-uat build remains a separate package.
- The shared debug certificate is intentionally public and its private key is
  reachable in an existing public Git branch. It provides upgrade continuity,
  not production authenticity. A future production Companion must use the
  `com.archipelago.app` package with a privately held release key.
- The pinned GitWorkshop revision has 4 high and 6 moderate production npm
  advisories. The final image is static nginx, reducing exposure to Node-server
  advisories, but browser dependencies remain reachable. Release requires an
  owner accept/fix decision.
- The repository is large: this checkout has about 5.4 GiB of packed objects,
  and the Gitea repository is about 5 GiB. Public GRASP replication must be
  allowed enough time and verified rather than assumed complete.
- The provided secrets audit reports known false positives in documentation,
  path-variable names, and deliberate test keys. Before Nostr publication,
  record that review and ensure local Git remote credentials are rotated; local
  `.git/config` credentials are not tracked and must never be copied into an
  announcement or release log.

## Required Owner Inputs

These secrets must be entered interactively and must not be sent in chat,
committed, placed in shell history, or stored on the node:

1. Access to the Nostr maintainer identity matching the npub above. Prefer an
   interactive NIP-46 connection through `ngit account connect`; do not pass an
   nsec on a command line.
2. The 24-word Archipelago release-master mnemonic for three signing actions:
   the OTA manifest, the app catalog, and the ISO checksum document.
3. A decision to accept the recorded GitWorkshop dependency advisories for
   1.8.12-alpha or pause for a dependency update.
4. A decision to publish 0.5.32 on the existing explicitly non-production
   `.debug` Companion channel, omit it, or pause for a secure production-app
   signing ceremony.

The shared Companion update certificate is not a production secret. It was
temporarily recovered from the public branch, verified against the distributed
0.5.28 APK, used to build the 0.5.32 alpha upgrade candidate, and removed from
the working tree. Neither it nor the UAT keystore belongs in the release commit.

## Execution Order

### Gate A — Freeze And Production Companion

1. Verify the shared Companion certificate against the existing public APK
   before building anything. This is complete for the alpha candidate.
2. Build the 0.5.32 shared-key alpha APK with v1, v2, and v3 signature schemes.
3. Verify package ID, version code/name, signing digest, and install-as-upgrade
   behavior on the owner's phone.
4. Stage the APK and its JSON version metadata in the dashboard payload.
5. Run formatting, frontend type checking/unit tests/build, Android lint/build,
   focused backend tests, manifest validation, registry-candidate validation,
   secret review, and live node smoke probes.
6. Deploy that exact build on this node and perform the short final UAT:
   GitWorkshop and IndeedHub first login, identity switching, Companion WebView,
   external tab, certificate install, payment receipt, update cancellation, and
   credential interstitial.

Stop on any failure. Do not sign or publish a workaround build.

### Gate B — Publish Archipelago Source Through Nostr

Run Nostr publication from a disposable clean clone so `ngit init` cannot
repoint or rewrite the release checkout's remotes.

1. Confirm the clean clone matches the final candidate and contains `LICENSE`,
   `CONTRIBUTING.md`, `SECURITY.md`, and `NOTICE`.
2. Connect `ngit` interactively to the canonical maintainer identity and verify
   `ngit account whoami` reports the expected npub.
3. Publish identifier `archy`, title `Archipelago`, the public project
   description/homepage, the existing Gitea HTTPS clone URL, and multiple
   current public GRASP services. Use at least `relay.ngit.dev` and
   `gitnostr.com`; add an Archipelago-operated GRASP service later without
   changing the repository coordinate.
4. Allow the complete repository push to finish. Do not treat a published
   announcement as proof that all Git objects arrived.
5. Verify the announcement author, identifier, relays, clone URLs, default
   branch, and release tags with `ngit repo`.
6. In a second empty directory, clone the printed `nostr://` URL and compare its
   `HEAD` tree to the candidate.
7. Open
   `/npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/archy`
   in the packaged GitWorkshop and confirm README/code browsing works.
8. Publish a test issue/proposal from a non-maintainer identity, review it from
   the maintainer identity, and confirm it cannot change canonical refs without
   maintainer authorization.
9. Confirm clone/browse still work with one GRASP server unavailable. A later
   infrastructure release must add an Archipelago-operated GRASP endpoint; the
   signed coordinate remains stable when servers change.

The Source promotion carries the deterministic npub/identifier deep-link. It
must not be published to the registry until steps 5–8 pass.

### Gate C — Prepare And Publish OTA 1.8.12-alpha

1. Convert the top `Unreleased` changelog section into
   `v1.8.12-alpha (2026-09-11)` and synchronize What's New.
2. Run `bash scripts/create-release.sh 1.8.12-alpha`. Enter the release mnemonic
   once when prompted and terminate input with Ctrl-D.
3. Verify the new release commit, annotated tag, staged backend/frontend
   artifacts, signed pending manifest, embedded AIUI, APK version, and clean
   tree.
4. Publish with
   `SKIP_ISO=1 scripts/publish-release-assets.sh 1.8.12-alpha gitea-vps2`.
   The script uploads and hashes artifacts before pushing the fleet-visible
   manifest. Never push `main` manually around this ordering.
5. Verify both local and public manifests, both asset hashes, public HTTPS
   download links, and update availability from this node.
6. Apply the OTA to this node first, reboot if requested, and rerun live smoke
   probes before allowing the catalog publication.

### Gate D — Publish The Signed App Registry

This follows the OTA canary because GitWorkshop's manifest builds from
`/opt/archipelago/docker/archipelago-source`, which older nodes do not have.

1. Generate `releases/app-catalog.json` from the final manifests.
2. Require 62 entries, 61 embedded manifests, `archipelago-source` 0.4.0,
   registry-owned storefront metadata, and the canonical Source deep-link.
3. Run strict metadata, manifest, and deployed-registry trust-floor checks.
4. Sign the exact catalog bytes using `bash scripts/sign-catalog.sh` and verify
   the pinned release-root DID.
5. Commit and push only the signed catalog after the OTA canary succeeds.
6. Confirm `/api/app-catalog` verifies the signature and a fresh node can see,
   install, launch, stop, start, and uninstall GitWorkshop.

### Gate E — Build, Test, Sign, And Attach The ISO

1. From clean `main` with the live signed 1.8.12 manifest and tag, run
   `bash scripts/build-iso-release.sh`. Do not use `--skip-gates` or `--no-qemu`
   for the publishable candidate.
2. Require the release harness, strict catalog check, full Rust test suite,
   version/artifact checks, ISO mount smoke test, and QEMU boot attempt.
3. Record the ISO filename, byte size, SHA-256, build commit, and whether QEMU
   was conclusive. If QEMU is inconclusive, boot the ISO on the target test
   machine before publication.
4. Sign the checksum document with
   `bash scripts/sign-iso-checksums.sh <iso>` and cryptographically verify it.
5. Attach the ISO, plain checksum, and signed checksum JSON by rerunning
   `scripts/publish-release-assets.sh 1.8.12-alpha gitea-vps2`.
6. Verify Gitea's stored sizes and public HTTPS links, then download/hash the
   public checksum documents. Flash/boot/install on real hardware before
   calling the ISO generally available.

## Rollback Rules

- OTA: the live manifest remains 1.8.11-alpha until all 1.8.12 artifacts have
  uploaded and verified. If canary application fails, do not publish the new
  catalog; restore the previous manifest/artifacts through the established
  rollback path.
- Registry: retain the previously signed catalog. Roll back by publishing a
  newly signed catalog that removes GitWorkshop or restores its prior entry;
  never edit signed JSON in place.
- Nostr source: repository state is authoritative only when signed by the
  configured maintainer. Add replacement servers before removing failed ones,
  then republish and run `ngit sync`.
- ISO: an ISO is not referenced by the OTA manifest. A failed ISO build/upload
  cannot block or corrupt an already verified OTA; do not advertise a partial
  attachment.
- Companion: retain 0.5.28 and the verified alpha signer until 0.5.32 installs
  as an upgrade. Never replace the public APK with the differently signed UAT
  build. Do not describe the public debug-key channel as production-secure.

## Final Release Record

Before announcing completion, record in the release notes:

- release/tag/commit and signed manifest DID;
- backend and frontend SHA-256 values;
- signed catalog commit, app count, and verification result;
- canonical `nostr://` URL, NIP-34 coordinate, GRASP/clone endpoints, and clone
  verification commit;
- Companion package/version/signing digest and APK SHA-256;
- ISO filename/size/SHA-256/signature and smoke/QEMU/real-hardware results;
- owner UAT acceptance and the explicit GitWorkshop no-license/dependency-risk
  decisions.