v5.0.2-beta.15

.claude/logs/agent-2-planning-april-8-2026.md

@@ -0,0 +1,73 @@
+# Release Update Plan for April 8, 2026
+
+## Overview
+- Release Type: Minor (new REST endpoints + internal agent improvements)
+- Key Changes: 4 new V2 REST workspace endpoints; Stagehand agent enhancements; defaultValue for userContextFields
+- Breaking Changes: No
+
+## Areas Requiring Updates
+
+### 1. REST API Reference — New Workspace Endpoint Pages (HIGH PRIORITY)
+
+Four new MDX files must be created under the existing REST API workspace directory:
+
+- `api-reference/rest-apis/v2/workspace/create.mdx` — `POST /v2/workspace/create`
+- `api-reference/rest-apis/v2/workspace/get.mdx` — `POST /v2/workspace/get`
+- `api-reference/rest-apis/v2/workspace/email-status.mdx` — `POST /v2/workspace/email/status`
+- `api-reference/rest-apis/v2/workspace/send-login-link.mdx` — `POST /v2/workspace/email/send-login-link`
+
+Pattern to follow: `api-reference/rest-apis/v2/workspace/add-domain.mdx` (frontmatter `api:` field, Headers section with `x-velt-api-key` + `x-velt-auth-token`, Body Params section, Example Request/Response, `<ResponseExample>` block).
+
+Security notes to include on public endpoints:
+- IP-based rate limiting applied
+- Disposable email domain blocking applied
+
+**Do NOT add these to `api-methods.mdx`** — that file covers client SDK methods only.
+
+Priority: High
+
+### 2. Changelog Link Fix
+
+The release note at `release-notes/version-5/sdk-changelog.mdx` contains a placeholder link:
+
+```
+[Learn more →](<!-- TODO: confirm link target for this doc -->#TODO-confirm-doc-link)
+```
+
+Once the four endpoint pages are created, replace this with the correct path. Suggested link target: `/api-reference/rest-apis/v2/workspace/create` (or a workspace overview page if one is created).
+
+Priority: High — must be resolved after endpoint pages exist.
+
+### 3. Data Models — No Update Needed
+
+No new client-side types or interfaces introduced. Internal agent config changes (Firestore-driven aiConfig, deep merge for metadata) are backend-only and not exposed via the SDK.
+
+### 4. API Methods — No Update Needed
+
+No new SDK client methods or changed method signatures. Changes are REST endpoints and internal agent runtime behavior.
+
+### 5. UI Customization — No Update Needed
+
+No new components, primitives, or wireframes.
+
+### 6. Upgrade Guide — No Update Needed
+
+No breaking changes.
+
+## Implementation Sequence
+
+1. Create `api-reference/rest-apis/v2/workspace/create.mdx` following add-domain.mdx pattern.
+2. Create `api-reference/rest-apis/v2/workspace/get.mdx`.
+3. Create `api-reference/rest-apis/v2/workspace/email-status.mdx`.
+4. Create `api-reference/rest-apis/v2/workspace/send-login-link.mdx`.
+5. Fix the placeholder link in `release-notes/version-5/sdk-changelog.mdx` to point to the new create endpoint page.
+6. Verify the new pages appear in the docs nav (check mint.json or docs.json for REST API workspace section entries).
+
+## Quality Checklist
+- [ ] 4 new REST endpoint pages created under `api-reference/rest-apis/v2/workspace/`
+- [ ] Each page has correct `api:` frontmatter, Headers, Body, Example Request, Example Response, and `<ResponseExample>`
+- [ ] Public endpoint pages note IP-based rate limiting and disposable email blocking
+- [ ] Placeholder link in sdk-changelog.mdx resolved
+- [ ] Nav config updated if required for new pages
+- [ ] No changes made to `api-methods.mdx` or `data-models.mdx`
+- [ ] Log file written to `.claude/logs/agent-2-planning-april-8-2026.md`

.claude/logs/agent-7-qa-april-8-2026.md

@@ -0,0 +1,21 @@
+## QA Summary for April 8, 2026 (Programmatic Workspace APIs)
+
+### Issues Found: 1
+
+1. **api-reference/rest-apis/v2/workspace/delete-domain.mdx** - Description was copy-pasted from add-domain.mdx: "Use this API to add new organizations and its metadata." This is a pre-existing bug in an existing file, not introduced by this release.
+   - Fix: Changed to "Use this API to remove domains from your organization's allowed domains list."
+
+### Observations (no fixes required)
+
+- **create.mdx, email-status.mdx, send-login-link.mdx** — No `# Headers` section. These are public/unauthenticated endpoints, consistent with their design (rate-limited by IP, not by API key). Omission is intentional.
+- **get.mdx** — Uses `x-velt-workspace-id` instead of `x-velt-api-key`. This is endpoint-specific and correct: retrieving a workspace uses the workspace ID + auth token rather than an API key.
+- **docs.json** — All 4 new pages correctly registered under the workspace nav group.
+- **sdk-changelog.mdx** — April 8, 2026 entry correctly links to `/api-reference/rest-apis/v2/workspace/create` and lists all 4 endpoints.
+- **ResponseExample blocks** — All 4 new pages include `<ResponseExample>` blocks matching the add-domain/delete-domain pattern.
+- **Section structure** — All 4 new pages follow: Endpoint → Headers (where applicable) → Body → Example Request → Example Response → ResponseExample. Consistent with existing workspace pages.
+
+### Summary
+- Files corrected: 1 (pre-existing bug, delete-domain.mdx)
+- Critical issues: 0
+- New page format issues: 0
+- Terminology issues: 0

.claude/logs/agent-7-qa-april-9-2026.md

@@ -0,0 +1,28 @@
+## QA Summary for April 9, 2026 Sub-Entry (v5.0.2-beta.15)
+### Release: Activity Intelligence Enrichment (backend only)
+
+### Issues Found: 0
+
+### Checks Performed
+
+1. **Separator placement** — `---` horizontal rule correctly separates April 8 block content from the April 9 sub-entry. No blank line missing.
+
+2. **Italic date line format** — `_April 9, 2026 — Activity Intelligence Enrichment (backend only, no client SDK changes)_` matches the established sub-entry format used in prior multi-day blocks.
+
+3. **Section order** — New Features → Improvements → Bug Fixes. Correct per pipeline rules.
+
+4. **Section labels** — All three bullet groups use `[**Access Control**]` or `[**Activity Logs**]`. No stray "Cloud Functions" product label. The phrase "Cloud Functions" in line 83 is used as a technical noun (GCP/Firebase deployment target for `embedjudgment` and `backfilljudgments`), not as a product section label. Correct usage.
+
+5. **No Breaking Changes section** — Confirmed absent. Backend-only changes are correctly surfaced only under New Features, Improvements, and Bug Fixes.
+
+6. **No client SDK terminology** — Entry correctly contains no `client.` API method references, no prop tables, no wireframe code, and no UI customization content.
+
+7. **Closing `</Update>` tag** — Present at line 95, correctly closing the v5.0.2-beta.15 block.
+
+8. **No data-models, api-methods, wireframe, primitives, or docs.json changes** — Confirmed. No cross-file consistency checks required.
+
+### Summary
+- Files corrected: 0
+- Critical issues: 0
+- Terminology alignments: 0
+- QA result: PASS — sub-entry is clean, no fixes required

.claude/logs/agent-7-qa-workspace-rest-apis.md

@@ -0,0 +1,26 @@
+## QA Summary — Workspace REST APIs Complete Reference
+
+### Issues Found: 1
+
+1. **api-reference/rest-apis/v2/workspace/add-domain.mdx** — Stale description carried from a different endpoint: "Use this API to add new organizations and its metadata." (organizations wording, wrong context).
+   - Fix: Updated to "Use this API to add one or more domains to the allowed domains list for a workspace."
+
+### Checks Performed (No Issues)
+
+- **All 20 pages present in docs.json** — Navigation entries verified at lines 574–593, all 20 workspace paths accounted for, correct order.
+- **`api:` frontmatter URLs** — All 20 pages verified. URLs match the `# Endpoint` section inline. No mismatches.
+- **`<ResponseExample>` blocks** — All 20 pages have a `<ResponseExample>` block containing the success response. No pages missing this block.
+- **Error response format** — All pages use `{ "error": { "status": "...", "message": "..." } }` shape consistently. No deviation.
+- **Auth header split** — Three tiers are correctly applied across all pages:
+  - Workspace-level auth (`x-velt-workspace-id` + `x-velt-auth-token`): `apikey-create`, `apikeys-get`, `apikey-update`, `authtokens-get`, `authtoken-reset`, `get`
+  - API-key-level auth (`x-velt-api-key` + `x-velt-auth-token`): `add-domain`, `delete-domain`, `domains-get`, `domains-request`, `requested-domains-get`, `additional-url-request`, `emailconfig-get`, `emailconfig-update`, `webhookconfig-get`, `webhookconfig-update`, `apikeymetadata-get`
+  - No auth (public endpoints): `create`, `send-login-link`, `email-status`
+- **Body pattern consistency** — Endpoints with no body use `This endpoint does not require a request body.` + `{}` example consistently. Endpoints with body use `#### Params` + `<ParamField body="data">` wrapper consistently.
+- **`requested-domains-get.mdx` URL** — `api: "POST https://api.velt.dev/v2/workspace/requested/domains/get"` uses `/requested/domains/get` path (not `/domains/requested/get`). Noted as potentially non-standard path structure but consistent with the endpoint's purpose and not contradicted by any other pattern in the workspace group.
+
+### Summary
+- Files corrected: 1
+- Critical issues: 0
+- Terminology/description fixes: 1 (stale description in pre-existing file)
+- New pages (Agent-6 created): clean — no issues
+- QA result: PASS with 1 minor fix applied

api-reference/rest-apis/v2/workspace/add-domain.mdx

@@ -3,7 +3,11 @@ title: "Add Domains"
 api: "POST https://api.velt.dev/v2/workspace/domains/add"
 ---
 
-Use this API to add new organizations and its metadata.
+Use this API to add one or more domains to the allowed domains list for a workspace.
+
+<Info>
+This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint.
+</Info>
 
 # Endpoint
 
@@ -26,7 +30,7 @@ Use this API to add new organizations and its metadata.
 <ParamField body="data" type="object" required>
   <Expandable title="properties">
     <ParamField body="domains" type="string[]" required>
-      Array of domains
+      Array of domains to add. Max 100 entries. You can send full URLs (e.g., `"https://www.example.com"`) or bare domains (e.g., `"example.com"`). The API normalizes all entries by stripping the protocol and `www` prefix — the stored and returned value will be the bare domain (e.g., `"example.com"`). Wildcard subdomains are supported (e.g., `"*.firebase.com"`).
     </ParamField>
   </Expandable>
 </ParamField>

api-reference/rest-apis/v2/workspace/apikey-create.mdx

@@ -0,0 +1,161 @@
+---
+title: "Create API Key"
+api: "POST https://api.velt.dev/v2/workspace/apikey/create"
+---
+
+Use this API to create a new API key for a workspace.
+
+<Info>
+This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers.
+</Info>
+
+# Endpoint
+
+`POST https://api.velt.dev/v2/workspace/apikey/create`
+
+# Headers
+
+<ParamField header="x-velt-workspace-id" type="string" required>
+  Your Workspace ID.
+</ParamField>
+
+<ParamField header="x-velt-auth-token" type="string" required>
+  Your [Auth Token](/security/auth-tokens).
+</ParamField>
+
+# Body
+
+#### Params
+
+<ParamField body="data" type="object" required>
+  <Expandable title="properties">
+    <ParamField body="ownerEmail" type="string" required>
+      Email address of the API key owner.
+    </ParamField>
+    <ParamField body="type" type="string" required>
+      API key type. Accepted values: `"testing"` or `"production"`. Production keys require `planInfo` or `customPlanInfo`.
+    </ParamField>
+    <ParamField body="createAuthToken" type="boolean">
+      Whether to create an auth token along with the API key. Recommended: `true`.
+    </ParamField>
+    <ParamField body="apiKeyName" type="string">
+      Display name for the API key.
+    </ParamField>
+    <ParamField body="planInfo" type="object">
+      Plan information object associated with this API key. Required for `"production"` type unless `customPlanInfo` is `true`.
+      <Expandable title="properties">
+        <ParamField body="type" type="string">
+          Plan type identifier (e.g., `"sdk test"`, `"production"`).
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    <ParamField body="customPlanInfo" type="boolean">
+      Whether to use custom plan info instead of standard `planInfo`.
+    </ParamField>
+    <ParamField body="customPlanInfoData" type="object">
+      Freeform custom plan info data payload. Required when `customPlanInfo` is `true`. You can pass any key-value pairs needed for your custom plan configuration.
+    </ParamField>
+    <ParamField body="allowedDomains" type="string[]">
+      List of domains allowed to use this API key.
+    </ParamField>
+    <ParamField body="addLocalHostToAllowedDomains" type="boolean">
+      Whether to automatically add localhost to allowed domains.
+    </ParamField>
+    <ParamField body="useEmailService" type="boolean">
+      Whether to enable the email service for this API key.
+    </ParamField>
+    <ParamField body="useWebhookService" type="boolean">
+      Whether to enable the webhook service for this API key.
+    </ParamField>
+    <ParamField body="emailServiceConfig" type="object">
+      Configuration object for the email service. See [Update Email Config](/api-reference/rest-apis/v2/workspace/emailconfig-update) for the full schema.
+      <Expandable title="properties">
+        <ParamField body="type" type="string">
+          Email service provider type. Accepted values: `"default"` or `"sendgrid"`.
+        </ParamField>
+        <ParamField body="apiKey" type="string">
+          API key for the email service provider (e.g., your SendGrid API key).
+        </ParamField>
+        <ParamField body="fromEmail" type="string">
+          Sender email address.
+        </ParamField>
+        <ParamField body="fromCompany" type="string">
+          Sender company name.
+        </ParamField>
+        <ParamField body="commentTemplateId" type="string">
+          SendGrid template ID for comment notification emails.
+        </ParamField>
+        <ParamField body="tagTemplateId" type="string">
+          SendGrid template ID for tag/mention notification emails.
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    <ParamField body="webhookServiceConfig" type="object">
+      Configuration object for the webhook service. See [Update Webhook Config](/api-reference/rest-apis/v2/workspace/webhookconfig-update) for the full schema.
+      <Expandable title="properties">
+        <ParamField body="authToken" type="string">
+          Auth token sent with each webhook request for verification.
+        </ParamField>
+        <ParamField body="rawNotificationUrl" type="string">
+          URL to receive raw (unprocessed) webhook notifications.
+        </ParamField>
+        <ParamField body="processedNotificationUrl" type="string">
+          URL to receive processed webhook notifications.
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+# Example Request
+
+```JSON
+{
+  "data": {
+    "ownerEmail": "owner@example.com",
+    "type": "testing",
+    "createAuthToken": true
+  }
+}
+```
+
+# Example Response
+
+#### Success Response
+
+```JSON
+{
+  "result": {
+    "status": "success",
+    "message": "API key created successfully.",
+    "data": {
+      "apiKey": "your_new_api_key"
+    }
+  }
+}
+```
+
+#### Failure Response
+
+```JSON
+{
+  "error": {
+    "status": "INVALID_ARGUMENT",
+    "message": "ownerEmail is required."
+  }
+}
+```
+
+<ResponseExample>
+```js
+{
+  "result": {
+    "status": "success",
+    "message": "API key created successfully.",
+    "data": {
+      "apiKey": "your_new_api_key"
+    }
+  }
+}
+```
+</ResponseExample>