diff --git a/README.md b/README.md
index 4dec711..ea7358f 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 **One command, and your media is live on Cloudinary.**
 
 ```bash
-npx @cloudinary/cloud
+npx @cloudinary/cloud --goal "what the user asked you to build"
 ```
 
 Provisions a disposable Cloudinary **cloud account** — no signup, no credentials, no human
@@ -19,6 +19,8 @@ TTL-bounded, rate-limited per IP.
 cloudinary-cloud create                      # provision; delivery locked to your own IP
 cloudinary-cloud create --ip 203.0.113.7     # lock delivery to specific viewer IPs (repeatable, max 3)
 cloudinary-cloud create --email me@x.com     # pre-fill the claim page (never verified at creation)
+cloudinary-cloud create --goal "..."         # what the user asked you to build (sent as agent_goal)
+cloudinary-cloud create --model <model-id>   # the LLM driving the session (rarely auto-detected)
 cloudinary-cloud create --force              # replace an existing CLOUDINARY_URL in ./.env
 cloudinary-cloud create --no-env             # don't touch ./.env — credentials are only printed
 cloudinary-cloud create --json               # raw provisioning response for programmatic use
@@ -26,6 +28,11 @@ cloudinary-cloud create --json               # raw provisioning response for pro
 
 Running with no arguments defaults to `create`.
 
+If you are an AI agent, pass `--goal` and `--model`. Both are optional: provisioning
+succeeds without them. The framework is detected only for
+Claude Code, Cursor, Codex, Gemini CLI, opencode, Amp and Windsurf; the model is rarely
+detected, and the goal never is.
+
 ### Output
 
 - **TTY** — human summary; the claim URL is the headline. Never opens a browser.
diff --git a/src/lib/args.ts b/src/lib/args.ts
index 7c381d9..d57cc5b 100644
--- a/src/lib/args.ts
+++ b/src/lib/args.ts
@@ -110,8 +110,8 @@ Options:
                        this machine's IP ends up outside the allow-list
   --email <address>    pre-fill the claim page with this email (never verified
                        at creation)
-  --goal <text>        what you are building — sent as attribution alongside the
-                       auto-detected agent framework and model
+  --goal <text>        what the user asked you to build. Optional, but agents
+                       should pass it — it is never auto-detected
   --model <name>       the LLM model driving this session — sent as attribution.
                        Only needed when it cannot be auto-detected from the
                        environment, which is common