Udpate AGENTS.md

AGENTS.md

···
 
 End of handoff. Implement auth login and repo list as described, keeping changes focused and testable.
 
+
+--------------------------------------------------------------------------------
+
+## 13) Tangled Core (../tangled-core) – Practical Notes
+
+This workspace often needs to peek at the Tangled monorepo to confirm XRPC endpoints and shapes. Here are concise tips and findings that informed this CLI implementation.
+
+### Where To Look
+
+- Lexicons (authoritative NSIDs and shapes): `../tangled-core/lexicons/**`
+  - Repo create: `../tangled-core/lexicons/repo/create.json` → `sh.tangled.repo.create`
+  - Repo record schema: `../tangled-core/lexicons/repo/repo.json` → `sh.tangled.repo`
+  - Misc repo queries (tree, log, tags, etc.) under `../tangled-core/lexicons/repo/`
+  - Note: there is no `sh.tangled.repo.list` lexicon in the core right now; listing is done via ATproto records.
+- Knotserver XRPC routes (what requires auth vs open): `../tangled-core/knotserver/xrpc/xrpc.go`
+  - Mutating repo ops (e.g., `sh.tangled.repo.create`) are behind ServiceAuth middleware.
+  - Read-only repo queries (tree, log, etc.) are open.
+- Create repo handler (server-side flow): `../tangled-core/knotserver/xrpc/create_repo.go`
+  - Validates ServiceAuth; expects rkey for the `sh.tangled.repo` record that already exists on the user's PDS.
+- ServiceAuth middleware (how Bearer is validated): `../tangled-core/xrpc/serviceauth/service_auth.go`
+  - Validates a ServiceAuth token with Audience = `did:web:<knot-or-service-host>`.
+- Appview client for ServiceAuth: `../tangled-core/appview/xrpcclient/xrpc.go` (method: `ServerGetServiceAuth`).
+
+### How To Search Quickly (rg examples)
+
+- Find a specific NSID across the repo:
+  - `rg -n "sh\.tangled\.repo\.create" ../tangled-core`
+- See which endpoints are routed and whether they’re behind ServiceAuth:
+  - `rg -n "chi\..*Get\(|chi\..*Post\(" ../tangled-core/knotserver/xrpc`
+  - Then open `xrpc.go` and respective handlers.
+- Discover ServiceAuth usage and audience DID:
+  - `rg -n "ServerGetServiceAuth|VerifyServiceAuth|serviceauth" ../tangled-core`
+- List lexicons by area:
+  - `ls ../tangled-core/lexicons/repo` or `rg -n "\bid\": \"sh\.tangled\..*\"" ../tangled-core/lexicons`
+
+### Repo Listing (client-side pattern)
+
+- There is no `sh.tangled.repo.list` in core. To list a user’s repos:
+  1) Resolve handle → DID if needed via PDS: `GET com.atproto.identity.resolveHandle`.
+  2) List records from the user’s PDS: `GET com.atproto.repo.listRecords` with `collection=sh.tangled.repo`.
+  3) Filter client-side (e.g., by `knot`). “Starred” filtering is not currently defined in core.
+
+### Repo Creation (two-step flow)
+
+- Step 1 (PDS): create the `sh.tangled.repo` record in the user’s repo:
+  - `POST com.atproto.repo.createRecord` with `{ repo: <did>, collection: "sh.tangled.repo", record: { name, knot, description?, createdAt } }`.
+  - Extract `rkey` from the returned `uri` (`at://<did>/<collection>/<rkey>`).
+- Step 2 (Tangled API base): call the server to initialize the bare repo on the knot:
+  - Obtain ServiceAuth: `GET com.atproto.server.getServiceAuth` from PDS with `aud=did:web:<tngl.sh or target-host>`.
+  - `POST sh.tangled.repo.create` on the Tangled API base with `{ rkey, defaultBranch?, source? }` and `Authorization: Bearer <serviceAuth>`.
+  - Server validates token via `xrpc/serviceauth`, confirms actor permissions, and creates the git repo.
+
+### Base URLs, DIDs, and Defaults
+
+- Tangled API base (server): default is `https://tngl.sh`. Do not use the marketing/landing site.
+- PDS base (auth + record ops): default `https://bsky.social` unless a different PDS was chosen on login.
+- ServiceAuth audience DID is `did:web:<host>` where `<host>` is the Tangled API base hostname.
+- CLI stores the PDS URL in the session to keep the CLI stateful.
+
+### Common Errors and Fixes
+
+- `InvalidToken` when listing repos: listing should use the PDS (`com.atproto.repo.listRecords`), not the Tangled API base.
+- 404 on `repo.create`: verify ServiceAuth audience matches the target host and that the rkey exists on the PDS.
+- Keychain issues on Linux: ensure a Secret Service (e.g., GNOME Keyring or KWallet) is running.
+
+### Implementation Pointers (CLI)
+
+- Auth
+  - `com.atproto.server.createSession` against the PDS, save `{accessJwt, refreshJwt, did, handle, pds}` in keyring.
+- List repos
+  - Use session.handle by default; resolve to DID, then `com.atproto.repo.listRecords` on PDS.
+- Create repo
+  - Build the PDS record first; then ServiceAuth → `sh.tangled.repo.create` on `tngl.sh`.
+
+### Testing Hints
+
+- Avoid live calls; use `mockito` to stub both PDS and Tangled API base endpoints.
+- Unit test decoding with minimal JSON envelopes: record lists, createRecord `uri`, and repo.create (empty body or simple ack).