diff --git a/.agents/skills/update-sdk/SKILL.md b/.agents/skills/update-sdk/SKILL.md
new file mode 100644
index 0000000..c775c6c
--- /dev/null
+++ b/.agents/skills/update-sdk/SKILL.md
@@ -0,0 +1,188 @@
+---
+name: update-sdk
+description: Update the @relewise/client SDK from the main Relewise Swagger source with a strict git and PR flow. Use when asked to regenerate SDK models/types, refresh client contracts from Swagger, or prepare an SDK-update PR. Require a Trello card URL, run clean-main preflight checks, create a timestamped chore branch, regenerate from the main Swagger URL, validate build/types/tests, and prepare a PR with Trello URL as the first line.
+---
+
+# Update SDK
+
+## Goal
+Regenerate `@relewise/client` models and declaration types from the main Swagger source and deliver a validated PR to `main`.
+
+## Required Input
+Require a Trello card URL before running SDK update work.
+
+If the prompt does not include a Trello URL, ask for it first and do not continue until provided.
+
+## Preflight Git Safety
+Run commands from repository root.
+
+1. Require a strict clean worktree:
+```powershell
+git status --porcelain
+```
+Abort when any output exists.
+
+2. Ensure `origin` exists:
+```powershell
+git remote get-url origin
+```
+Abort on failure.
+
+3. Fetch refs:
+```powershell
+git fetch origin --prune
+```
+Abort on failure.
+
+4. Switch to `main`:
+```powershell
+git switch main
+```
+Abort if switch is not safe.
+
+5. Fast-forward local `main`:
+```powershell
+git pull --ff-only origin main
+```
+Abort if not fast-forward or if pull fails.
+
+Do not continue when any preflight step fails.
+
+## Branch Creation
+Use a timestamped branch (date + hour + minute):
+
+```powershell
+$stamp = Get-Date -Format 'yyyyMMdd-HHmm'
+$branchName = "chore/update-sdk-$stamp"
+```
+
+Abort if branch exists locally or remotely:
+```powershell
+git show-ref --verify --quiet "refs/heads/$branchName"
+git ls-remote --exit-code --heads origin $branchName
+```
+
+Create and switch:
+```powershell
+git switch -c $branchName
+```
+
+## SDK Regeneration (Main Swagger Source)
+Run commands from repository root using package-prefixed commands:
+
+1. Install dependencies:
+```powershell
+npm --prefix .\packages\client ci
+```
+
+2. Regenerate API models/types from the main Swagger URL:
+```powershell
+npm --prefix .\packages\client run gen-api
+```
+
+`gen-api` must use:
+```text
+https://api.relewise.com/public/swagger.json
+```
+through `packages/client/package.json`.
+
+Notes:
+- Do not use `gen-api-dev` for normal SDK updates.
+- `gen-api` also runs `fix-exports.js`, which patches `src/models/data-contracts.ts` to export `UtilRequiredKeys`.
+
+## Expected Changes Check
+Before validation, inspect changed files and ensure updates are coherent.
+
+Expected change locations:
+- `packages/client/src/models/*` generated by `swagger-typescript-api`
+- `packages/client/src/models/data-contracts.ts` export patch effect from `fix-exports.js`
+- lockfile/package metadata changes only when intentionally caused by install/update work
+
+If unrelated files changed unexpectedly, stop and investigate before proceeding.
+
+## Validation (Required)
+Run validation in `packages/client` and treat failures as blocking unless the user explicitly accepts known failures.
+
+1. Build:
+```powershell
+npm --prefix .\packages\client run build
+```
+
+2. Build declaration types:
+```powershell
+npm --prefix .\packages\client run build:types
+```
+
+3. Unit tests:
+```powershell
+npm --prefix .\packages\client test
+```
+
+4. Optional integration tests (when secrets are available or explicitly requested):
+```powershell
+npm --prefix .\packages\client run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com
+```
+
+If secrets are unavailable, report integration tests as not run.
+
+## Acceptance Criteria
+Treat the SDK update as successful only when:
+- `npm run gen-api` succeeds using the main Swagger URL
+- `npm --prefix .\packages\client run build` succeeds
+- `npm --prefix .\packages\client run build:types` succeeds
+- `npm --prefix .\packages\client test` succeeds
+- changed files are expected and reviewable
+
+## Commit, Push, and Pull Request
+1. Commit SDK update changes on the update branch.
+2. Push branch:
+```powershell
+git push -u origin $branchName
+```
+3. Create PR to `main`.
+
+Preferred automated flow with GitHub CLI:
+```powershell
+$prBodyPath = ".\\update-sdk-pr-body.md"
+@"
+$TrelloCardUrl
+
+## Summary
+- Regenerated `@relewise/client` from main Swagger URL
+- <key model/type changes>
+
+## Validation
+- `npm run gen-api`: <result>
+- `npm --prefix .\packages\client run build`: <result>
+- `npm --prefix .\packages\client run build:types`: <result>
+- `npm --prefix .\packages\client test`: <result>
+- `npm --prefix .\packages\client run integration-test`: <result or not run>
+
+## Notes
+- <known issues or limitations>
+"@ | Set-Content $prBodyPath
+
+$prUrl = gh pr create --base main --head $branchName --title "chore(client): update sdk from swagger ($stamp)" --body-file $prBodyPath
+if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' }
+Write-Host "PR URL: $prUrl"
+```
+
+Manual fallback:
+```powershell
+git push -u origin $branchName
+Write-Host "Create PR: https://github.com/Relewise/relewise-sdk-javascript/compare/main...$branchName?expand=1"
+Write-Host "PR title: chore(client): update sdk from swagger ($stamp)"
+Write-Host "PR body file: $prBodyPath"
+```
+
+Keep the Trello URL as the first line in PR description.
+
+## Output Expectations
+Provide a final summary with:
+- Trello URL used
+- branch name
+- changed file groups
+- key generated model/type updates
+- results for each validation command
+- pushed branch URL
+- PR URL, or exact manual fallback instructions when automated PR creation is unavailable
diff --git a/.agents/skills/update-sdk/agents/openai.yaml b/.agents/skills/update-sdk/agents/openai.yaml
new file mode 100644
index 0000000..b77e8b9
--- /dev/null
+++ b/.agents/skills/update-sdk/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update SDK"
+  short_description: "Swagger-driven client SDK refresh flow"
+  default_prompt: "Use $update-sdk to regenerate @relewise/client from the main Swagger URL, validate build/types/tests, and prepare a Trello-linked PR."
diff --git a/.agents/skills/upgrade-dependencies/SKILL.md b/.agents/skills/upgrade-dependencies/SKILL.md
new file mode 100644
index 0000000..bf8857d
--- /dev/null
+++ b/.agents/skills/upgrade-dependencies/SKILL.md
@@ -0,0 +1,213 @@
+---
+name: upgrade-dependencies
+description: Upgrade npm dependencies in relewise-sdk-javascript with a safe branch and PR flow. Use when asked to refresh package versions, maintain npm dependencies, or prepare a dependency-upgrade PR for this repository. Require a Trello card URL, enforce clean-main preflight checks, create a monthly chore branch, upgrade direct dependencies across package manifests, resolve manageable compatibility fallout, run repo-aligned validation, then push and open a PR with the Trello link on the first line.
+---
+
+# Upgrade Dependencies
+
+## Goal
+Upgrade direct npm dependencies to latest stable versions for this repository and deliver a validated PR to `main`.
+
+## Required Input
+Require a Trello card URL before running upgrade work.
+
+If the prompt does not include a Trello URL, ask for it first and do not continue until provided.
+
+## Preflight Git Safety
+Run commands from repository root.
+
+1. Require a strict clean worktree:
+```powershell
+git status --porcelain
+```
+Abort when any output exists.
+
+2. Ensure `origin` exists:
+```powershell
+git remote get-url origin
+```
+Abort on failure.
+
+3. Fetch refs:
+```powershell
+git fetch origin --prune
+```
+Abort on failure.
+
+4. Switch to `main`:
+```powershell
+git switch main
+```
+Abort if switch is not safe.
+
+5. Fast-forward local `main`:
+```powershell
+git pull --ff-only origin main
+```
+Abort if not fast-forward or if pull fails.
+
+Do not continue when any preflight step fails.
+
+## Branch Creation
+Use a monthly branch:
+
+```powershell
+$stamp = Get-Date -Format 'yyyyMM'
+$branchName = "chore/upgrade-dependencies-$stamp"
+```
+
+Abort if branch exists locally or remotely:
+```powershell
+git show-ref --verify --quiet "refs/heads/$branchName"
+git ls-remote --exit-code --heads origin $branchName
+```
+
+Create and switch:
+```powershell
+git switch -c $branchName
+```
+
+## Discover npm Manifests
+Discover package manifests under `packages/`, excluding `node_modules`.
+
+Preferred command:
+```powershell
+if (Get-Command rg -ErrorAction SilentlyContinue) {
+    $manifestPaths = rg --files -g "packages/**/package.json" -g "!**/node_modules/**"
+} else {
+    $manifestPaths = Get-ChildItem -Path .\packages -Recurse -Filter package.json |
+        Where-Object { $_.FullName -notmatch '\\node_modules\\' } |
+        ForEach-Object { $_.FullName }
+}
+$manifestPaths
+```
+
+Treat each discovered manifest directory as an upgrade target.
+
+## npm Upgrade Workflow
+For each discovered manifest directory:
+
+1. Run the upgrade loop from repository root:
+```powershell
+foreach ($manifestPath in $manifestPaths) {
+    $packageDir = Split-Path -Parent $manifestPath
+    Push-Location $packageDir
+    try {
+        npm install
+
+        $packageJson = Get-Content -Raw .\package.json | ConvertFrom-Json
+        $allPackages = @()
+        if ($packageJson.dependencies) { $allPackages += $packageJson.dependencies.PSObject.Properties.Name }
+        if ($packageJson.devDependencies) { $allPackages += $packageJson.devDependencies.PSObject.Properties.Name }
+        $allPackages = $allPackages | Sort-Object -Unique
+
+        foreach ($pkg in $allPackages) {
+            Write-Host "Updating npm package $pkg in $packageDir"
+            npm install "$pkg@latest"
+            if ($LASTEXITCODE -ne 0) {
+                throw "Failed to update npm package $pkg in $packageDir."
+            }
+        }
+
+        npm outdated
+    } finally {
+        Pop-Location
+    }
+}
+```
+
+Notes:
+- Upgrade only direct `dependencies` and `devDependencies` by default.
+- Do not auto-upgrade `peerDependencies` unless explicitly requested.
+- Keep lockfile updates generated by npm commands.
+- Ignore nested lockfiles that do not have a sibling `package.json`.
+
+## Resolve Upgrade Fallout
+Fix compatibility issues directly caused by dependency upgrades:
+- API or signature changes
+- type errors
+- build/test failures
+- lint failures
+
+Pause and ask for collaborative direction when fixes become extensive, such as broad refactors or behavior changes.
+
+## Validation (Required)
+Run validation per touched package and treat failures as blocking unless the user explicitly accepts known failures.
+
+For `packages/client`:
+```powershell
+npm --prefix .\packages\client run build
+npm --prefix .\packages\client test
+```
+
+For `packages/integrations`:
+```powershell
+npm --prefix .\packages\integrations run build
+npm --prefix .\packages\integrations test
+```
+
+For `packages/code-analyzer`:
+```powershell
+npm --prefix .\packages\code-analyzer run lint
+```
+
+Integration tests are conditional:
+- Run when API behavior/contracts are changed and required secrets are available.
+- If running both integration suites, run integrations package first:
+```powershell
+npm --prefix .\packages\integrations run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com
+npm --prefix .\packages\client run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com
+```
+- If secrets are unavailable, report integration tests as not run.
+
+## Commit, Push, and Pull Request
+1. Commit dependency and compatibility changes on the upgrade branch.
+2. Push branch:
+```powershell
+git push -u origin $branchName
+```
+3. Create PR to `main`.
+
+Preferred automated flow with GitHub CLI:
+```powershell
+$prBodyPath = ".\\upgrade-dependencies-pr-body.md"
+@"
+$TrelloCardUrl
+
+## Summary
+- <short summary of upgraded dependencies and compatibility fixes>
+
+## Validation
+- `packages/client`: <build/test result or not touched>
+- `packages/integrations`: <build/test result or not touched>
+- `packages/code-analyzer`: <lint result or not touched>
+- `integration tests`: <result or not run>
+
+## Notes
+- <known issues or limitations>
+"@ | Set-Content $prBodyPath
+
+$prUrl = gh pr create --base main --head $branchName --title "chore: upgrade dependencies ($stamp)" --body-file $prBodyPath
+if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' }
+Write-Host "PR URL: $prUrl"
+```
+
+Manual fallback:
+```powershell
+git push -u origin $branchName
+Write-Host "Create PR: https://github.com/Relewise/relewise-sdk-javascript/compare/main...$branchName?expand=1"
+Write-Host "PR title: chore: upgrade dependencies ($stamp)"
+Write-Host "PR body file: $prBodyPath"
+```
+
+Keep the Trello URL as the first line in PR description.
+
+## Output Expectations
+Provide a final summary with:
+- Trello URL used
+- branch name
+- upgraded npm packages grouped by manifest path
+- compatibility fixes applied
+- results for each validation command
+- pushed branch URL
+- PR URL, or exact manual fallback instructions when automated PR creation is unavailable
diff --git a/.agents/skills/upgrade-dependencies/agents/openai.yaml b/.agents/skills/upgrade-dependencies/agents/openai.yaml
new file mode 100644
index 0000000..f25ba51
--- /dev/null
+++ b/.agents/skills/upgrade-dependencies/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Upgrade Dependencies"
+  short_description: "Safe npm upgrades for SDK monorepo"
+  default_prompt: "Use $upgrade-dependencies to safely upgrade dependencies in relewise-sdk-javascript with clean-branch preflight, per-package validation, and a Trello-linked PR."
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..347f8f3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,119 @@
+# AGENTS.md
+
+## Purpose
+This file is the operating guide for contributors and coding agents working in `relewise-sdk-javascript`.
+
+The repository is a multi-package TypeScript SDK. Follow this guide to keep changes scoped, verifiable, and aligned with CI.
+
+## Repository Map
+- `packages/client`: `@relewise/client` public SDK (search/recommendation/tracking clients, builders, models, factories).
+- `packages/integrations`: `@relewise/integrations` package for entity update/integration flows.
+- `packages/code-analyzer`: internal TypeScript analyzer used for MCP ingestion payload generation.
+- `.github/workflows`: CI, publishing, dependabot auto-merge, and MCP ingestion workflows.
+- `.github/dependabot.yml`: monthly grouped dependency updates for `client`, `integrations`, and GitHub Actions.
+
+## Repository Skills
+- `upgrade-dependencies`:
+  - Location: `.agents/skills/upgrade-dependencies/SKILL.md`
+  - Use when asked to refresh npm package versions or prepare dependency-upgrade PRs for this repository.
+  - This skill enforces clean-main preflight checks, monthly chore branch creation, direct dependency upgrades, per-package validation, and Trello-first PR descriptions.
+- `update-sdk`:
+  - Location: `.agents/skills/update-sdk/SKILL.md`
+  - Use when asked to regenerate `@relewise/client` models/types from Swagger.
+  - This skill enforces main-URL Swagger generation (`https://api.relewise.com/public/swagger.json`), expected-file checks, client validation commands, and Trello-first PR descriptions.
+
+## Core Working Conventions
+- Run commands from package directories; there is no root workspace `package.json`.
+- Keep changes minimal and package-local.
+- Do not commit secrets (dataset IDs, API keys, private URLs, credentials).
+- Treat generated files as generated. In particular:
+  - `packages/client/src/models/data-contracts.ts` is generated from Swagger.
+  - Use `npm run gen-api` in `packages/client` when API contract regeneration is required.
+- Avoid manual edits that conflict with generation/build outputs unless the change is intentionally part of that pipeline.
+
+## Runbook
+
+### `packages/client`
+```powershell
+cd packages/client
+npm ci
+npm run gen-api
+npm run build
+npm run build:types
+npm test
+# Conditional (requires secrets):
+npm run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com
+```
+
+### `packages/integrations`
+```powershell
+cd packages/integrations
+npm ci
+npm run build
+npm run build:types
+npm test
+# Conditional (requires secrets):
+npm run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com
+```
+
+### `packages/code-analyzer`
+```powershell
+cd packages/code-analyzer
+npm ci
+npm run codeAnalyzer -- '..\client\tsconfig.json' '@relewise/client'
+npm run codeAnalyzer -- '..\integrations\tsconfig.json' '@relewise/integrations'
+```
+
+## Validation Policy (CI-Aligned, Pragmatic)
+- Required for normal code changes:
+  - Build and unit tests for each touched package.
+- Integration tests:
+  - Required when behavior/API contract changes are involved and credentials are available.
+  - If credentials are unavailable, explicitly report integration tests as not run.
+- For dependency/tooling changes:
+  - Re-run build + unit tests in all impacted packages.
+
+## Dependency Upgrade Guidance
+For dependency upgrade tasks, prefer using the `upgrade-dependencies` skill:
+
+```text
+$upgrade-dependencies
+```
+
+Core expectations from the skill:
+
+1. Start from a clean working tree.
+2. Ensure `origin` exists, fetch, switch to `main`, and fast-forward (`git pull --ff-only`).
+3. Create a monthly branch (example: `chore/upgrade-dependencies-YYYYMM`).
+4. Upgrade direct `dependencies` and `devDependencies` in each target package.
+5. Keep each package lockfile updated.
+6. Resolve manageable compatibility fallout (types, build, test failures).
+7. Run required validation (build + unit; integration tests conditional).
+8. Push and open PR to `main`.
+9. Put the Trello card URL on the first line of the PR description.
+
+Notes:
+- Dependabot already opens monthly grouped updates for `packages/client` and `packages/integrations`.
+- Minor/patch Dependabot PRs may auto-merge via workflow. Manual chore upgrades should coexist without breaking that flow.
+
+## SDK Update Guidance
+For Swagger-driven client SDK regeneration, prefer using the `update-sdk` skill:
+
+```text
+$update-sdk
+```
+
+Use `update-sdk` when the goal is updating generated client contracts/types from the main Swagger source URL, not general npm dependency upgrades.
+
+## PR Expectations
+Each PR should include:
+- Scope: which package(s) changed and why.
+- Risk notes: behavior surface potentially impacted.
+- Validation results by command (build/tests, and integration-test status).
+- API generation note when relevant (`gen-api` run/not run and reason).
+
+## Known Pitfalls
+- There is no root npm workspace command surface.
+- `packages/client/src/models/data-contracts.ts` is generated; avoid manual drift.
+- `client` and `integrations` are versioned separately and keep separate lockfiles.
+- Some `client` integration tests depend on data prepared by `integrations` integration tests.