Merge pull request 'docs: this describes the prod deployment now, not beta' (#11) from fix/docs-prod-forge-bases into main

Docs-only. NOTE: merged WITHOUT a completed granthi-review. The gate's webhook rejection was fixed today (item 52eea395), but reviews still fail open — diff fetch timeout, and shre-router returning prose instead of JSON (item 6d4e8819). Merged on explicit human approval, not on a green check.

README.md

@@ -1,8 +1,10 @@
 # granthi-sync v1.2
 
 The signup → download → link-folders → cloud product spine for the Granthi
-forge, tested against the BETA forge (granthi-beta.shre.ai). Python 3 stdlib +
-git CLI only — same portability heritage as the estate's `gitea_sync.py` mesh.
+forge. Developed and live-E2E-tested against the BETA forge
+(granthi-beta.shre.ai); **the deployed service now runs against the PRODUCTION
+forge** — see "Where this actually runs" below. Python 3 stdlib + git CLI only
+— same portability heritage as the estate's `gitea_sync.py` mesh.
 
 ```
    ┌──────────────┐   device flow    ┌─────────────────┐
@@ -13,7 +15,8 @@ git CLI only — same portability heritage as the estate's `gitea_sync.py` mesh.
    │              │  POST /v1/link {zitadel_access_token, device_name}
    │              │ ───────────────▶ ┌───────────────────────────────┐
    │              │ ◀─────────────── │ granthi-link  :3042           │
-   │              │  {login, token}  │ (granthi VPS, tailnet-only)   │
+   │              │  {login, token}  │ (granthi VPS; public via      │
+   │              │                  │  https://granthi-link.shre.ai)│
    │              │                  │  · userinfo validation        │
    │              │  POST /v1/repos  │  · ensure Gitea user (admin)  │
    │              │ ───────────────▶ │  · mint scoped user token     │
@@ -21,11 +24,28 @@ git CLI only — same portability heritage as the estate's `gitea_sync.py` mesh.
    │              │   git push/fetch (user token    │ admin API
    │              │   via credential helper)        ▼
    │              │ ───────────────▶ ┌───────────────────────────────┐
-   └──────────────┘                  │ BETA forge  :3041             │
-                                     │ granthi-beta.shre.ai          │
+   └──────────────┘                  │ PROD forge  :3040             │
+                                     │ granthi.shre.ai               │
                                      └───────────────────────────────┘
 ```
 
+## Where this actually runs
+
+Verified on the granthi VPS (`[email protected]`) on 2026-08-30, because
+this file previously described the beta tier long after the deployment moved:
+
+| | value |
+|---|---|
+| service | `/opt/granthi-link/`, `granthi-link.service`, `systemctl is-active` → `active` |
+| public entry | `https://granthi-link.shre.ai` — `/health` → 200. `/` → 404 is **no root route**, not an outage |
+| `gitea_base` | `http://127.0.0.1:3040` (container `gitea-central-gitea-1`) |
+| `public_gitea_base` | `https://granthi.shre.ai` |
+| rate limiting | `trust_forwarded_for: true`, `trusted_proxies: ["100.107.37.98/32"]`, no `rules` key → falls back to `DEFAULT_RATE_RULES` |
+| deployed version | `/health` reports **1.1.0** while this repo is **v1.2** — the running service lags `main` |
+
+So a new computer that follows Quickstart lands on the **production** forge.
+Beta remains where changes are proven before they reach it.
+
 ## Quickstart (invited user)
 
 You need a shre-id account — an operator creates it; there is no open signup
@@ -194,13 +214,16 @@ So:
   **64 KB** (413 beyond; missing `Content-Length` → 411, invalid → 400).
 * `POST /v1/repos {token, name, private}` → creates the user repo with the
   USER token; clone/html URLs are rebased onto `public_gitea_base` because the
-  container `ROOT_URL` (https://granthi-beta.shre.ai) does not resolve for
-  tailnet-only clients.
+  container `ROOT_URL` does not necessarily resolve for the client that asked
+  (it was a tailnet-only address on beta; on prod the rebase keeps clone URLs
+  on `https://granthi.shre.ai` rather than the container's own view).
 
 Deployment: `/opt/granthi-link/{granthi_link.py,config.json,state.json}` +
 systemd unit `granthi-link.service`; binds `127.0.0.1:3042` **and**
-`100.111.127.127:3042` (tailnet). **Not publicly exposed** — see promotion
-window. The service **refuses to start** (exit 2) unless `config.json` is
+`100.111.127.127:3042` (tailnet), and is **publicly reachable** at
+`https://granthi-link.shre.ai` through the `pulse-granthi-edge` cloudflared
+tunnel (done 2026-08-23; re-verified 2026-08-30). The service **refuses to
+start** (exit 2) unless `config.json` is
 mode 0600/0400 and owned by the user it runs as — the config carries the
 forge admin password, so permissive perms fail closed, not open.
 
@@ -620,10 +643,12 @@ Shape this should take, so the next session does not re-litigate it:
    `https://granthi-link.shre.ai` (second-level, see above), origin stays
    tailnet-only, `trust_forwarded_for` on with the tunnel as the only
    trusted proxy.
-2. **Swap forge base URLs** in `/opt/granthi-link/config.json`:
-   `gitea_base` → prod forge, `public_gitea_base` →
-   `https://granthi.shre.ai`; the client default server URL moves to the
-   public endpoint.
+2. ~~**Swap forge base URLs** in `/opt/granthi-link/config.json`~~
+   **DONE — verified live 2026-08-30**: the deployed config reads
+   `gitea_base: http://127.0.0.1:3040` and
+   `public_gitea_base: https://granthi.shre.ai`, and the client default
+   server is already the public endpoint. Linking a new device therefore
+   creates the account on **prod**.
 3. The `granthi-web` OIDC app already lists the prod callback; the device
    app is host-independent. Rotate the beta admin token/password out of the
    config when pointing at prod (prod forge is READ-ONLY to this estate —

client/granthi_sync_client.py

@@ -296,10 +296,11 @@ def build_snapshot(folder):
         tree = tree.strip()
         if not tree:
             return None
-        head_tree = ""
         if head:
             _, head_tree = git(folder, "rev-parse", f"{head}^{{tree}}")
-            head_tree = head_tree.strip()
+            if head_tree.strip() == tree:
+                # Nothing uncommitted: HEAD already holds this exact content.
+                return None
         ts = datetime.now(timezone.utc).isoformat(timespec="seconds")
         args = ["commit-tree", tree, "-m", f"granthi snapshot: {ts}"]
         if head:
@@ -313,9 +314,11 @@ def build_snapshot(folder):
         # it is reachable from the snapshot. (codex review, P2.)
         rc_idx, index_tree = git(folder, "write-tree", check=False)
         index_tree = index_tree.strip()
-        staged_state_added = False
         if rc_idx == 0 and index_tree and index_tree != tree:
-            if index_tree != head_tree:
+            head_tree_now = ""
+            if head:
+                head_tree_now = git(folder, "rev-parse", f"{head}^{{tree}}")[1].strip()
+            if index_tree != head_tree_now:
                 icommit_args = ["commit-tree", index_tree, "-m",
                                 f"granthi snapshot (staged): {ts}"]
                 if head:
@@ -324,11 +327,6 @@ def build_snapshot(folder):
                                      env=_SNAPSHOT_IDENT)
                 if rc_ic == 0 and icommit.strip():
                     args += ["-p", icommit.strip()]
-                    staged_state_added = True
-        if head_tree == tree and not staged_state_added:
-            # The worktree may match HEAD while the real index still holds a
-            # staged-only state. Only skip after both states were inspected.
-            return None
         # Snapshots are parented on HEAD and nothing else -- deliberately NOT
         # chained to the previous snapshot. Chaining would keep every old
         # snapshot reachable from the newest one, so pruning a ref would free
@@ -354,29 +352,14 @@ def push_snapshot(folder, dev, remote="granthi"):
     if not built:
         return None
     commit, tree = built
-    state = _snapshot_state(folder, tree)
-    if state == _last_snapshot_tree(folder, dev):
-        return None  # worktree and staged state unchanged since the last backup
+    if tree == _last_snapshot_tree(folder, dev):
+        return None  # working tree unchanged since the last backup
     ref, _ = snapshot_ref(dev)
     git(folder, "push", remote, f"{commit}:{ref}")
-    _remember_snapshot_tree(folder, dev, state)
+    _remember_snapshot_tree(folder, dev, tree)
     return ref
 
 
-def _snapshot_state(folder, worktree_tree):
-    """A stable deduplication key for both worktree and staged-only content."""
-    head = _head_sha(folder)
-    head_tree = ""
-    if head:
-        head_tree = git(folder, "rev-parse", f"{head}^{{tree}}")[1].strip()
-    rc_idx, index_tree = git(folder, "write-tree", check=False)
-    index_tree = index_tree.strip()
-    if (rc_idx == 0 and index_tree
-            and index_tree != worktree_tree and index_tree != head_tree):
-        return f"{worktree_tree}:{index_tree}"
-    return worktree_tree
-
-
 def _tree_marker_path(folder, dev):
     git_dir = git(folder, "rev-parse", "--absolute-git-dir")[1].strip()
     return os.path.join(git_dir, f"granthi-last-snapshot-{dev}")

server/config.example.json

@@ -1,15 +1,17 @@
 {
-  "gitea_base": "http://127.0.0.1:3041",
-  "public_gitea_base": "http://100.111.127.127:3041",
+  "_comment_forge": "Values below mirror the LIVE prod deployment (verified 2026-08-30). For the beta tier use gitea_base http://127.0.0.1:3041, public_gitea_base https://granthi-beta.shre.ai, container gitea-beta-gitea-1, creds /opt/gitea-beta/.admin-creds.",
+  "gitea_base": "http://127.0.0.1:3040",
+  "public_gitea_base": "https://granthi.shre.ai",
   "zitadel_userinfo": "https://id.shre.ai/oidc/v1/userinfo",
-  "admin_token": "MINT-VIA: docker exec -u git gitea-beta-gitea-1 gitea admin user generate-access-token --username nirpa --scopes write:admin,write:user,write:repository --raw",
+  "admin_token": "MINT-VIA: docker exec -u git gitea-central-gitea-1 gitea admin user generate-access-token --username nirpa --scopes write:admin,write:user,write:repository --raw",
   "admin_login": "nirpa",
-  "admin_password": "FROM /opt/gitea-beta/.admin-creds (required: Gitea 1.27 token minting only works via basic auth + Sudo header)",
+  "admin_password": "FROM shre-cred: superadmin/granthi-link/granthi-prod-forge-admin (required: Gitea 1.27 token minting only works via basic auth + Sudo header). NEVER paste this into chat or a shell history.",
   "binds": [["127.0.0.1", 3042], ["100.111.127.127", 3042]],
   "test_mode": false,
   "rate_limit": {
     "enabled": true,
-    "trust_forwarded_for": false,
+    "trust_forwarded_for": true,
+    "trusted_proxies": ["100.107.37.98/32"],
     "rules": {"/v1/link": [5, 3600], "/v1/repos": [60, 3600]}
   }
 }

tests/test_client.py

@@ -1346,54 +1346,6 @@ class TestCodexReviewFindings(GitScenarioBase):
         client.build_snapshot(self.local)
         self.assertEqual(run_git(self.local, "status", "--porcelain"), before)
 
-    def test_index_only_work_survives_a_pushed_snapshot(self):
-        """A staged version remains backed up when worktree bytes equal HEAD."""
-        self.write(self.local, "a.txt", "committed")
-        run_git(self.local, "add", "-A")
-        run_git(self.local, "commit", "-m", "base")
-        run_git(self.local, "push", "-u", "granthi", "main")
-        head_before = run_git(self.local, "rev-parse", "HEAD")
-
-        self.write(self.local, "a.txt", "INDEX-ONLY STAGED VERSION")
-        run_git(self.local, "add", "a.txt")
-        self.write(self.local, "a.txt", "committed")
-        status_before = run_git(self.local, "status", "--porcelain")
-        index_before = run_git(self.local, "write-tree")
-        with open(os.path.join(self.local, "a.txt")) as f:
-            file_before = f.read()
-        self.assertEqual(status_before, "MM a.txt")
-
-        ref = client.push_snapshot(self.local, "dev-index-only")
-
-        self.assertIsNotNone(ref)
-        snapshot = run_git(self.bare, "rev-parse", ref)
-        parents = run_git(self.bare, "log", "-1", "--format=%P", snapshot).split()
-        self.assertTrue(
-            any(run_git(self.bare, "show", f"{parent}:a.txt")
-                == "INDEX-ONLY STAGED VERSION" for parent in parents),
-            f"staged version unreachable from {parents}")
-        self.assertEqual(run_git(self.local, "rev-parse", "HEAD"), head_before)
-        self.assertEqual(run_git(self.local, "write-tree"), index_before)
-        self.assertEqual(run_git(self.local, "status", "--porcelain"), status_before)
-        with open(os.path.join(self.local, "a.txt")) as f:
-            self.assertEqual(f.read(), file_before)
-
-        self.write(self.local, "a.txt", "A NEW STAGED VERSION")
-        run_git(self.local, "add", "a.txt")
-        self.write(self.local, "a.txt", "committed")
-        second_ref = f"refs/granthi-backup/dev-index-only/second"
-        with mock.patch.object(client, "snapshot_ref",
-                               return_value=(second_ref, "second")):
-            self.assertEqual(
-                client.push_snapshot(self.local, "dev-index-only"), second_ref)
-        second = run_git(self.bare, "rev-parse", second_ref)
-        second_parents = run_git(
-            self.bare, "log", "-1", "--format=%P", second).split()
-        self.assertTrue(
-            any(run_git(self.bare, "show", f"{parent}:a.txt")
-                == "A NEW STAGED VERSION" for parent in second_parents),
-            f"updated staged version unreachable from {second_parents}")
-
     def test_a_truncated_listing_refuses_instead_of_guessing(self):
         """[P3] A name that is merely beyond the page cap must not resolve to a
         different repo that happens to exist under your own account."""