@anyforge/control 0.8.0 → 0.9.0

package/README.md

@@ -312,3 +312,53 @@ check the company's BYOK provider key and the agent's endpoint. If the displayed
 company or user is wrong, reconnect with `anyforge init` rather than editing an ID.
 The server route and its Firestore indexes must be deployed before a newly built
 CLI can use this diagnostic command; a 404 is not an authentication verdict.
+
+
+### Code Studio
+
+Studio commands require `@anyforge/control` **0.9.0 or later** and a deployed
+Studio API. Install with `npm install -g @anyforge/control@^0.9.0` after its npm
+release; a repository build or application deployment does not update an
+installed CLI. Run `anyforge --version` to check the installed version.
+
+Use a dedicated Studio key from Settings → API keys. Standard `write` and legacy
+keys do not authorize Studio execution or publication. Owners and operators, plus editors explicitly enabled by their company owner, can
+use these commands; service accounts cannot own interactive Studio sessions.
+
+```sh
+anyforge studio list --json
+anyforge studio usage SESSION --json
+anyforge studio create --repo acme/app --branch feature/fix --context "Fix the form" --json
+anyforge studio continue SESSION --file src/form.ts --context "Review this local reference"
+anyforge studio open SESSION
+anyforge studio run SESSION --context "Implement and test the fix" --input '{"maxTotalTokens":40000}'
+anyforge studio events RUN --cursor 12 --json
+anyforge studio answer RUN --context "Use option A" --input '{"questionId":"QUESTION"}'
+anyforge studio cancel RUN
+anyforge studio changes SESSION
+anyforge studio commit SESSION --input '{"message":"Fix form","expectedRevision":"REVISION"}'
+anyforge studio push SESSION --input '{"expectedHeadSha":"SHA"}'
+```
+
+`create` and `continue` prepare context without running code. `--file` sends only
+that file (20 KB maximum), labels its local branch/commit and uncommitted state,
+and does not copy local edits into the remote checkout. `--initiative ID` assigns
+a new session to an existing initiative; omission starts direct work. Keep the
+returned session/run IDs and event cursor to reconnect. Reuse an explicit
+`idempotencyKey` in `--input` when retrying a create or run request.
+
+`studio usage SESSION` reads the owned session's recorded billing subtotal,
+limited to the newest 200 rows, grouped by actual model, product, run and leg.
+It preserves the API's `truncated`, `coverage` and `pending` fields. Historical
+coverage may be incomplete; missing attribution is unavailable cost, not zero.
+Provider cost and platform fee remain separate fields. This read never starts a
+run or calculates prices locally.
+
+Read access requires `studio:read`; preparation requires `studio:write`; runs and
+local Git operations require `studio:execute`; pushing and PR lifecycle actions
+require `studio:publish`. External runs use audited local coding, reads and reviews. Hosted shell, browser,
+connectors, Oracle, crew dispatch, workflows and approvals require browser Studio
+with its separate role and confirmation gates; publish scope does not unlock them. Opted-in editors can edit, review, commit and publish
+with their own GitHub identity, but cannot dispatch crews or approve work.
+Review changes before committing, prefer draft PRs, and confirm ready/merge in browser Studio only
+for a specific PR and exact head after checks and review pass.