@freecodecamp/universe-cli 0.4.0 → 0.5.0

package/README.md

@@ -2,12 +2,6 @@
 
 Static site deployment for the freeCodeCamp Universe platform.
 
-> v0.4 routes every deploy through the **artemis** proxy at
-> `uploads.freecode.camp`. Staff hold only a `platform.yaml` and a
-> GitHub identity — the proxy holds the R2 credentials. See
-> [Universe ADR-016](https://github.com/freeCodeCamp-Universe/Universe/blob/main/decisions/016-deploy-proxy.md)
-> for the full design.
-
 ## Install
 
 ### npm
@@ -23,29 +17,34 @@ universe <command>
 
 ### Binary
 
-Download the latest binary from [Releases](../../releases):
+<details>
+  <summary>
+    Download the latest binary from [Releases](../../releases):
+  </summary>
 
-```sh
-# macOS (Apple Silicon)
-gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-darwin-arm64"
-chmod +x universe-darwin-arm64
-sudo mv universe-darwin-arm64 /usr/local/bin/universe
-
-# macOS (Intel)
-gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-darwin-amd64"
-chmod +x universe-darwin-amd64
-sudo mv universe-darwin-amd64 /usr/local/bin/universe
-
-# Linux x64
-gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-linux-amd64"
-chmod +x universe-linux-amd64
-sudo mv universe-linux-amd64 /usr/local/bin/universe
-
-# Linux ARM64
-gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-linux-arm64"
-chmod +x universe-linux-arm64
-sudo mv universe-linux-arm64 /usr/local/bin/universe
-```
+  ```sh
+    # macOS (Apple Silicon)
+    gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-darwin-arm64"
+    chmod +x universe-darwin-arm64
+    sudo mv universe-darwin-arm64 /usr/local/bin/universe
+
+    # macOS (Intel)
+    gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-darwin-amd64"
+    chmod +x universe-darwin-amd64
+    sudo mv universe-darwin-amd64 /usr/local/bin/universe
+
+    # Linux x64
+    gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-linux-amd64"
+    chmod +x universe-linux-amd64
+    sudo mv universe-linux-amd64 /usr/local/bin/universe
+
+    # Linux ARM64
+    gh release download --repo freeCodeCamp-Universe/universe-cli --pattern "universe-linux-arm64"
+    chmod +x universe-linux-arm64
+    sudo mv universe-linux-arm64 /usr/local/bin/universe
+  ```
+
+</details>
 
 Verify:
 
@@ -60,7 +59,7 @@ Top-level (cross-cutting):
 ```sh
 universe login            # GitHub OAuth device flow → ~/.config/universe-cli/token
 universe logout           # delete stored token
-universe whoami           # echo current login + authorized sites
+universe whoami           # echo current login + authorized-sites count
 universe --version        # CLI version
 ```
 
@@ -73,6 +72,15 @@ universe static rollback --to <deployId>
 universe static ls [--site <site>]
 ```
 
+Static-app registry (namespaced under `sites`, staff-gated writes):
+
+```sh
+universe sites ls [--mine]                          # list registered sites; `--mine` filters to your authorized set
+universe sites register <slug> [--team=<name>...]   # create new entry (staff; defaults --team to staff)
+universe sites update <slug> --team=<name>...       # replace teams list (staff)
+universe sites rm <slug>                            # delete entry (staff; R2 deploy bytes untouched)
+```
+
 All commands support `--json` for CI integration.
 
 ## Identity (priority chain)
@@ -86,8 +94,10 @@ The CLI resolves a GitHub identity in this order — first match wins:
 5. Device-flow stored token at `~/.config/universe-cli/token`
 
 The proxy validates whatever it receives via GitHub `GET /user`, then
-authorizes against the `sites.yaml` map server-side. Run
-`universe whoami` to see which slot resolved.
+authorizes against the registry server-side (Valkey-backed; the
+`sites_yaml` backend was retired in artemis `f115198`). Run
+`universe whoami` to see which slot resolved; inspect the sites you
+can deploy to with `universe sites ls --mine`.
 
 ## Configuration (`platform.yaml`)
 
@@ -97,37 +107,57 @@ Every site has a `platform.yaml` at its repo root. Minimal valid file:
 site: my-site
 ```
 
-Full reference (every field, defaults, validation rules, v0.3 → v0.4
-migration): [`docs/platform-yaml.md`](docs/platform-yaml.md).
+Full schema reference (every field, defaults, validation rules):
+[`docs/platform-yaml.md`](docs/platform-yaml.md).
 
 No credential fields. The proxy holds the R2 admin key; the CLI never
 reads or writes one.
 
 ## Common flows
 
+Staff onboarding + deploy lifecycle:
+
 ```sh
 # 1. Authenticate (laptop, first time)
 universe login
 
-# 2. Deploy to preview
-universe static deploy
-
-# 3. Inspect identity + authorized sites
+# 2. Identity + how many sites you can deploy to
 universe whoami
 
-# 4. List recent deploys for the current site
+# 3. List your authorized sites (intersects registry with your GH teams)
+universe sites ls --mine
+
+# 4. From your site repo: deploy to preview (reads ./platform.yaml)
+universe static deploy
+
+# 5. Inspect recent deploys for the current site
 universe static ls
 
-# 5. Promote current preview to production
+# 6. Promote preview to production
 universe static promote
 
-# 6. Roll production back to a past deploy
+# 7. Roll production back to a past deploy
 universe static rollback --to 20260427-141522-abc1234
 ```
 
+Registry admin (staff team only — gated server-side by artemis's
+`REGISTRY_AUTHZ_TEAM`, default `staff`):
+
+```sh
+# Register a new site (defaults --team to staff)
+universe sites register hello-universe --team bots,staff
+
+# Add or replace the teams list on an existing site
+universe sites update hello-universe --team bots,staff,curriculum
+
+# Delete a site from the registry (R2 bytes age out via cleanup cron)
+universe sites rm hello-universe
+```
+
 CI (GitHub Actions) — set `permissions: id-token: write` and rely on
 slot 2 (GHA OIDC) of the identity chain, or pass `$GITHUB_TOKEN`
-explicitly.
+explicitly. Full operator walkthrough:
+[`docs/STAFF-GUIDE.md`](docs/STAFF-GUIDE.md).
 
 ## Environment overrides
 
@@ -142,17 +172,3 @@ The shipped binary embeds the `freeCodeCamp` GitHub OAuth App client id
 out of the box for staff. Fork operators and self-hosted mirror tenants
 set `UNIVERSE_GH_CLIENT_ID` to their own OAuth App's id — env value
 wins when set.
-
-## Development
-
-```sh
-pnpm install
-pnpm test          # vitest
-pnpm typecheck     # tsc --noEmit
-pnpm lint          # oxlint
-pnpm build         # tsup → dist/
-```
-
-## Releasing
-
-See [docs/RELEASING.md](docs/RELEASING.md).