## Today — Forgejo private, public repos mirrored to `knot1.tangled.sh`

Forgejo holds canonical state. A small bridge translates Forgejo webhook events into AT Proto XRPC calls and signed git pushes against the hosted knot. Forgejo image untouched.

```mermaid
flowchart LR
    user(["author"]) -->|git push| forgejo

    subgraph private["my forge — private"]
        forgejo["Forgejo<br/>(authoritative)"]
        webhook[/"webhook config<br/>per repo or org"/]
        forgejo --- webhook
    end

    webhook -->|push / create / delete<br/>HMAC-signed| bridge

    subgraph bridgeBox["forgejo-knot-bridge — small Go service"]
        bridge["event handler<br/>user → DID mapping"]
        keystore[("signing keys<br/>per bridged DID")]
        statedb[("bridge.db<br/>repo→DID,<br/>last-mirrored ref")]
        bridge --- keystore
        bridge --- statedb
    end

    bridge -->|sh.tangled.repo.create<br/>Service-Auth JWT| knot
    bridge -->|git push --mirror<br/>Service-Auth Bearer| knot

    subgraph hosted["knot1.tangled.sh — hosted, third-party"]
        knot["knotserver"]
        appview["tangled.sh appview<br/>(consumes firehose)"]
        knot -.->|sh.tangled.knot.subscribeRepos<br/>ws firehose| appview
    end

    plc[("plc.directory")] -.->|DID document<br/>verifies signing key| knot
```

The bridge needs three things from the knot side: knot URL + DID, `server:member` role for the DIDs being published as, and signing keys for those DIDs. From Forgejo it needs a webhook subscription, public-repo read access, and a Forgejo-user → DID mapping.

---

## Tomorrow — Forgejo *is* the knot

Instead of bridging Forgejo *into* a separate knotserver, teach Forgejo to *be* a knot. Same Forgejo binary, same `codeberg.org` hostname, with a module that exposes the knot lexicon surface backed by Forgejo's existing repo storage.

```mermaid
flowchart LR
    subgraph today["Today (above)"]
        f1["Forgejo"] -->|webhook| b1["bridge<br/>(separate service)"]
        b1 -->|XRPC + git push| k1["knotserver<br/>(separate process)"]
    end

    subgraph proposed["Forgejo as a knot"]
        forgejo["Forgejo<br/>+ knot-frontend module<br/>(or external sidecar)"]
        users(["users<br/>(unchanged web/SSH/REST)"]) --> forgejo
        forgejo -.->|"/xrpc/sh.tangled.*<br/>/events firehose<br/>Service-Auth on writes"| world["AT Protocol clients<br/>(tangled.sh appview,<br/>knotmirror, ...)"]
    end

    today -.->|same protocol surface,<br/>different deployment| proposed
```

The mapping is mostly mechanical — `sh.tangled.repo.{create,delete,tree,log,branches,diff,...}` lands on Forgejo's existing repo APIs in XRPC envelopes; `sh.tangled.knot.listKeys` reuses Forgejo's user SSH keys; identity reconciles via a `did` field on Forgejo's user table.

No-trivial part is `sh.tangled.knot.subscribeRepos` — an atproto-style sequenced WebSocket subscription with `cursor` resume and `ConsumerTooSlow` semantics. Forgejo's existing internal event hooks (the same ones driving its ActivityPub outbound delivery) are the natural source; you translate ref-update events into the lexicon's wire format and replay from a `tangled_firehose_events` table on reconnect.