docs: fix --bot-cookies url required field and Puppeteer context.cookies() usage

Author: MSTU0

CLI_FLAGS.md

@@ -202,15 +202,15 @@ Accepts cookie data as either inline JSON or from a file.
 
 **Inline JSON:**
 ```bash
---bot-cookies='[{"name":"session","value":"abc123","domain":".example.com"}]'
+--bot-cookies='[{"url":"https://example.com","name":"session","value":"abc123","domain":".example.com"}]'
 ```
 
 **From JSON file:**
 ```bash
 --bot-cookies="@/path/to/cookies.json"
 ```
 
-The file should contain a JSON array of cookie objects with name, value, and domain fields. Guide: [Cookie Management](https://botbrowser.io/docs/identity/cookie-management/)
+Each cookie object must include a `url` field. Cookies without `url` are silently skipped. Guide: [Cookie Management](https://botbrowser.io/docs/identity/cookie-management/)
 
 <a id="--bot-bookmarks"></a>
 ### `--bot-bookmarks`
@@ -512,7 +512,7 @@ chromium-browser \
   --bot-profile="/absolute/path/to/profile.enc" \
   --bot-config-browser-brand="chrome" \  # ENT Tier2 feature
   --bot-config-window="profile" \
-  --bot-cookies='[{"name":"sessionid","value":"abc123","domain":".example.com"}]' \
+  --bot-cookies='[{"url":"https://example.com","name":"sessionid","value":"abc123","domain":".example.com"}]' \
   --bot-bookmarks='[{"title":"Work Site","url":"https://work.example.com","type":"url"}]' \
   --user-data-dir="/tmp/instance1" &
 

botbrowser-control/src/renderer/js/app.js

@@ -1381,7 +1381,7 @@
         <div class="form-section-title">${I.cookie} Cookies & Bookmarks</div>
         <div class="form-group full">
           <label class="form-label">Cookies ${badge('PRO')}</label>
-          <textarea class="form-textarea" id="f-cookies" rows="4" placeholder='[{"name":"session","value":"abc","domain":".example.com"}] or @/path/to/cookies.json'>${esc(d.cookies||'')}</textarea>
+          <textarea class="form-textarea" id="f-cookies" rows="4" placeholder='[{"url":"https://example.com","name":"session","value":"abc","domain":".example.com"}] or @/path/to/cookies.json'>${esc(d.cookies||'')}</textarea>
         </div>
         <div class="form-group full">
           <label class="form-label">Bookmarks</label>

docs/guides/getting-started/CLI_RECIPES.md

@@ -297,7 +297,7 @@ chromium-browser \
 ```bash
 chromium-browser \
   --bot-profile="/path/to/profile.enc" \
-  --bot-cookies='[{"name":"session","value":"abc123","domain":".example.com"}]' \
+  --bot-cookies='[{"url":"https://example.com","name":"session","value":"abc123","domain":".example.com"}]' \
   --user-data-dir="$(mktemp -d)"
 ```
 

docs/guides/getting-started/PROFILE_MANAGEMENT.md

@@ -204,7 +204,7 @@ Use one profile with different session settings to create distinct user sessions
 chromium-browser \
   --bot-profile="/path/to/profile.enc" \
   --proxy-server=socks5://user:pass@us-proxy.example.com:1080 \
-  --bot-cookies='[{"name":"session","value":"us-user","domain":".example.com"}]' \
+  --bot-cookies='[{"url":"https://example.com","name":"session","value":"us-user","domain":".example.com"}]' \
   --user-data-dir="$(mktemp -d)" &
 
 # Session 2: German user
@@ -213,7 +213,7 @@ chromium-browser \
   --proxy-server=socks5://user:pass@de-proxy.example.com:1080 \
   --bot-config-timezone=Europe/Berlin \
   --bot-config-locale=de-DE \
-  --bot-cookies='[{"name":"session","value":"de-user","domain":".example.com"}]' \
+  --bot-cookies='[{"url":"https://example.com","name":"session","value":"de-user","domain":".example.com"}]' \
   --user-data-dir="$(mktemp -d)" &
 ```
 

docs/guides/identity/COOKIE_MANAGEMENT.md

@@ -33,7 +33,7 @@ You can provide cookies as inline JSON directly in the flag value, or load them
 ```bash
 chromium-browser \
   --bot-profile="/path/to/profile.enc" \
-  --bot-cookies='[{"name":"session_id","value":"abc123","domain":".example.com"}]'
+  --bot-cookies='[{"url":"https://example.com","name":"session_id","value":"abc123","domain":".example.com"}]'
 ```
 
 ### From a file
@@ -56,36 +56,38 @@ The file should contain a JSON array of cookie objects.
 
 2. **Cookie injection.** Cookies are injected into the browser's cookie store before any page navigation occurs. This means the first HTTP request already includes the injected cookies.
 
-3. **Domain matching.** Each cookie must include a `domain` field. The browser only sends cookies to matching domains, following standard cookie rules.
+3. **Domain matching.** Each cookie must include a `url` field. The browser uses it to set the cookie origin and only sends cookies to matching domains, following standard cookie rules.
 
 ### Cookie Format
 
 Each cookie object supports these fields:
 
 | Field | Required | Description |
 |-------|----------|-------------|
+| `url` | Yes | Full URL used to set the cookie (e.g., `https://example.com`). Required for the cookie to be accepted. |
 | `name` | Yes | Cookie name. |
 | `value` | Yes | Cookie value. |
-| `domain` | Yes | Domain the cookie belongs to. Prefix with `.` for subdomains (e.g., `.example.com`). |
+| `domain` | No | Domain the cookie belongs to. Prefix with `.` for subdomains (e.g., `.example.com`). |
 | `path` | No | Cookie path. Defaults to `/`. |
-| `secure` | No | Whether the cookie requires HTTPS. Defaults to `false`. |
+| `secure` | No | Whether the cookie requires HTTPS. Defaults to `true`. |
 | `httpOnly` | No | Whether the cookie is HTTP-only (not accessible via JavaScript). Defaults to `false`. |
-| `sameSite` | No | SameSite attribute: `Strict`, `Lax`, or `None`. |
-| `expires` | No | Expiration time as a Unix timestamp (seconds since epoch). |
+| `sameSite` | No | SameSite attribute: `strict`, `lax`, or `none`. |
+| `expirationDate` | No | Expiration time as a Unix timestamp (seconds since epoch). |
 
 ---
 
 <a id="common-scenarios"></a>
 
 ## Common Scenarios
 
-### Pre-authenticated session
+### Pre-authenticated session (Playwright)
 
 ```javascript
 import { chromium } from "playwright-core";
 
 const cookies = JSON.stringify([
   {
+    url: "https://example.com",
     name: "session_id",
     value: "abc123def456",
     domain: ".example.com",
@@ -94,6 +96,7 @@ const cookies = JSON.stringify([
     httpOnly: true,
   },
   {
+    url: "https://example.com",
     name: "user_prefs",
     value: "theme=dark",
     domain: ".example.com",
@@ -115,16 +118,55 @@ await page.goto("https://example.com/dashboard"); // Loads as authenticated user
 await browser.close();
 ```
 
+### Pre-authenticated session (Puppeteer)
+
+With Puppeteer, use `browser.defaultBrowserContext()` to access the context that `--bot-cookies` injects into. `context.cookies()` returns all cookies for the context without a URL argument.
+
+```javascript
+import puppeteer from "puppeteer-core";
+
+const cookies = JSON.stringify([
+  {
+    url: "https://example.com",
+    name: "session_id",
+    value: "abc123def456",
+    domain: ".example.com",
+    path: "/",
+    secure: true,
+    httpOnly: true,
+  },
+]);
+
+const browser = await puppeteer.launch({
+  executablePath: process.env.BOTBROWSER_EXEC_PATH,
+  headless: true,
+  args: [
+    "--bot-profile=/path/to/profile.enc",
+    `--bot-cookies=${cookies}`,
+  ],
+});
+
+const context = browser.defaultBrowserContext();
+const page = await context.newPage();
+await page.goto("https://example.com/dashboard");
+
+const injectedCookies = await context.cookies();
+console.log(injectedCookies);
+
+await browser.close();
+```
+
 ### Cookie consent pre-set
 
 ```javascript
 const consentCookies = JSON.stringify([
   {
+    url: "https://example.com",
     name: "cookie_consent",
     value: "accepted",
     domain: ".example.com",
     path: "/",
-    expires: Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60,
+    expirationDate: Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60,
   },
 ]);
 
@@ -145,6 +187,7 @@ Create a `cookies.json` file:
 ```json
 [
   {
+    "url": "https://example.com",
     "name": "session_id",
     "value": "abc123",
     "domain": ".example.com",
@@ -153,6 +196,7 @@ Create a `cookies.json` file:
     "httpOnly": true
   },
   {
+    "url": "https://example.com",
     "name": "locale",
     "value": "en-US",
     "domain": ".example.com",
@@ -175,7 +219,7 @@ When building the `--bot-cookies` flag in JavaScript, do not wrap the JSON value
 
 ```javascript
 // Correct
-const cookies = [{ name: "sid", value: "abc", domain: ".example.com" }];
+const cookies = [{ url: "https://example.com", name: "sid", value: "abc", domain: ".example.com" }];
 args.push("--bot-cookies=" + JSON.stringify(cookies));
 
 // Wrong - extra quotes become part of the value
@@ -190,6 +234,8 @@ args.push(`--bot-cookies='${JSON.stringify(cookies)}'`);
 
 | Problem | Solution |
 |---------|----------|
+| Cookies not injected (silently skipped) | Each cookie object must include a `url` field (e.g., `"url": "https://example.com"`). Without it, the cookie is silently dropped. |
+| Puppeteer: `context.cookies()` returns empty | Use `browser.defaultBrowserContext()`. Cookies from `--bot-cookies` are injected into the default context only, not into contexts created with `browser.createBrowserContext()`. |
 | Cookies not sent with requests | Verify the `domain` field matches the target site. Use `.example.com` (with leading dot) to include subdomains. |
 | "Invalid JSON" error | Check that the cookie value is a valid JSON array. Use a JSON validator if needed. |
 | File not found | When using `@/path/to/file.json`, ensure the path is absolute. |

docs/guides/identity/HISTORY_SEEDING.md

@@ -111,7 +111,7 @@ const browser = await chromium.launch({
     "--proxy-server=socks5://user:pass@proxy.example.com:1080",
     "--bot-inject-random-history",
     `--bot-cookies=${JSON.stringify([
-      { name: "consent", value: "accepted", domain: ".example.com" },
+      { url: "https://example.com", name: "consent", value: "accepted", domain: ".example.com" },
     ])}`,
     `--bot-bookmarks=${JSON.stringify([
       { title: "Google", type: "url", url: "https://www.google.com" },