superbee 0.4.4-pre.10 → 0.4.4-pre.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.4-pre.10",
+  "version": "0.4.4-pre.12",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [

package/references/hosted-checkout.md

@@ -92,6 +92,33 @@ must already be a member of the workspace (invited from the Members page first).
 bundle id in their own terminal. If it refuses with `needs_person_at_terminal`, show the person
 the host's statement and give them the command; do not try to work around it.
 
+## Requesting GitHub workload access
+
+A GitHub Actions job can use `superbee workload exec` with a bounded version1 JSON intent, an
+explicit HTTPS workspace origin and workspace slug, followed by its command after `--`.
+Run its `--help` for exact syntax. The intent contains a display name, supported events, exact
+bundle read/write capabilities and optional fixed sites. It contains no repository IDs, workflow
+refs, environment, credentials or app UUID. Each requested site must have its matching Read bundle
+capability. A protected main-only GitHub environment and `id-token: write` are required by the host.
+This works for custom research or documentation workflows without `release.config.json`.
+
+The existing exchange verifies the job's GitHub identity and resolves exactly approved access.
+Pending approval is `FORBIDDEN` (exit 2) with `details.reason: workload_approval_pending`, an opaque
+request id, expiry and `review_url`. No child starts and no Superbee bearer is returned. A workspace
+administrator reviews the permissions at that URL and approves or denies them; an agent must not
+approve its own request. Run the workflow again after approval. There is no polling, implicit grant,
+UUID fallback or copied app-ID variable. Denied or expired requests remain terminal.
+
+On success only the child receives the short-lived bearer, resolved gateway host, and
+`SUPERBEE_WORKLOAD_APP_ID` from the validated response, replacing any inherited app ID. The latter
+is temporary identity metadata for a native principal check, never a grant; nothing is written to
+`GITHUB_ENV`, a file or a persistent GitHub variable. Its GitHub OIDC minting variables are removed. The command is spawned directly with its argument boundaries,
+not through a shell, and its exit status is preserved. Tokens are masked in GitHub Actions logs;
+do not print or upload the child's environment. A changed capability declaration needs its own
+approval and cannot silently inherit broader access. The host must serve this request mode before
+using it; merged client source alone does not establish deployment, registration or production
+qualification. Existing explicit app-ID clients and the registration fallback below remain supported.
+
 ## Registering a site's CI: `workload register`
 
 A site whose content lives in hosted Superbee reads it in CI as a registered workload app. In the
@@ -370,6 +397,15 @@ superbee sync --resolve keep --doc index.md     # the next sync sends yours over
 
 ## Ordinary files (SVGs, images, `data/*.json`)
 
+`pull --doc-key <key> --out <path> --from-host --dir <checkout>` reads one blob's bytes and stored
+content type directly from the bound host, using its version and content type together as the
+read pin. It checks the checkout's signed-in person and workspace and verifies the returned bytes.
+A changed pin, denied access or unsupported host refuses without falling back to local bytes.
+It does not sync, send edits or refresh the working copy; only the requested output is written.
+Use `--out -` for raw stdout with the receipt on stderr. Ordinary `pull` still reads the local
+working copy, including unsent edits; its content type is inferred from the filename. The explicit
+host option is for blobs only and cannot be combined with `--remote`.
+
 Files other than `.md` documents are ordinary files. Sync sends and refreshes only **tracked**
 ones. Treat an edit to a tracked file as a publish: the next `superbee sync` sends it to the hosted
 bundle for everyone.