app/docs/persimmons-shared-cutover.md

Persimmons shared-hosting cutover

https://persimmons.app is a second front door for the source-owned matcha/persimmons bytes already composed at https://xn--sj8h.teahub.xyz/%F0%9F%8D%8A/. It is not an application or a second Gitea. The browser uses the shared Gitea identity and storage at teahub.xyz; browser/API operations terminate at teahub-mcp through the bounded /tea/site/* bridge.

The retired persimmons-app and persimmons-gitea state is disposable. The repository contains no Fly manifests, provisioners, launch workflow, preflight workflow, or operator allowlist entry capable of recreating either app.

External cutover (independent operator plane)

Do not operate this change through Teahub itself. Start from an independently authenticated Fly/Cloudflare operator and record the current machine, image, volume, DNS, and certificate state before mutation.

1. Build the Gitea image from the exact current matcha/teahub main SHA. Update only the canonical teahub-gitea machine, preserving its machine ID, volume, services, IPs, and rollback image. This activates both gitea/teahub-nginx.conf and GITEA__session__SAME_SITE=none; do not use the UI-only refresh script for this config change.
2. On that same independent plane, run the composed Pages projector against the exact current matcha/greentea main SHA: ops/pages-project-greentea.sh <40-character-greentea-main-sha>. Confirm its recorded app_persimmons_source_sha equals the local matcha/persimmons.git refs/heads/main and that current/🍊/index.html, app.js, and store.js are nonempty.
3. Add persimmons.app to the teahub-gitea Fly certificate set. Replace the old dedicated-app DNS with DNS-only records pointing at the existing shared Teahub addresses: A 66.241.124.48 and AAAA 2a09:8280:1::19c:1dd0:0. Remove the retired 66.241.124.82 / 2a09:8280:1::1a0:f8e1:0 records. Wait for Fly to report the hostname certificate ready before treating the cutover as live.
4. Verify https://persimmons.app/, /app.js, and /store.js return 200 and nonempty bytes; compare their hashes with the files under the composed current/🍊 directory. Verify https://teahub.xyz/api/healthz and https://mcp.teahub.xyz/healthz remain 200 and one bounded Gitea write path still succeeds.
5. In a fresh browser, sign in through the Persimmons popup and confirm the Teahub session cookie is Secure; HttpOnly; SameSite=None. Confirm session, repository discovery, create/list/rotate/revoke/delete, extension connection, and Juice target https://teahub.xyz work. Confirm an unallowlisted origin receives no credentialed CORS header.
6. After the shared taste test passes, stop/delete the old persimmons-app and persimmons-gitea apps and their disposable volumes/IPs/certificates. Do not copy old dedicated users or vault state into Teahub.

Rollback changes only the shared Gitea machine back to the recorded image and restores the prior DNS records. Never replace or detach the Gitea data volume.