Embed realize-toolkit, align with Apr 2026 brand guardrails

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "realize-ads-api",
-  "version": "0.2.0",
-  "description": "Query Taboola Realize campaigns and pull performance reports through natural language — powered by the Realize remote MCP.",
+  "version": "0.3.0",
+  "description": "Query Realize campaigns, pull performance reports, and create/update campaigns and ad items through natural language — powered by the Realize remote MCP.",
   "author": {
     "name": "Taboola"
   },

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/ensure-realize-mcp.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/settings.local.json.example

@@ -0,0 +1,13 @@
+{
+  "_comment": "Per-user opt-in to skip Claude Code's permission prompt for the 6 Realize write tools. The plugin's preview-then-confirm gate (see os/guardrails.md 'Write tool gate') still runs on every write. Copy this file to settings.local.json (gitignored) if you want to opt in.",
+  "permissions": {
+    "allow": [
+      "mcp__realize-mcp__create_campaign",
+      "mcp__realize-mcp__update_campaign",
+      "mcp__realize-mcp__create_native_item",
+      "mcp__realize-mcp__update_native_item",
+      "mcp__realize-mcp__create_display_item",
+      "mcp__realize-mcp__update_display_item"
+    ]
+  }
+}

.codex-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "realize-ads-api",
+  "version": "0.1.0",
+  "description": "Query and manage Realize campaigns through natural language on Codex — powered by the Realize remote MCP. Ships the system prompt (including the write-tool preview-then-confirm gate), the knowledge layer, and the MCP wiring. The Claude Code skill-driven workflows (campaign-creation walkthroughs, optimization diagnostics, report aggregation prose) are not loaded on Codex; write tools remain gated by the rules in os/guardrails.md. See INSTALL.md for Codex-specific install notes (manifest name and MCP URL).",
+  "author": {
+    "name": "Taboola"
+  },
+  "homepage": "https://github.com/taboola/realize-claude-plugin",
+  "repository": "https://github.com/taboola/realize-claude-plugin",
+  "license": "Apache-2.0",
+  "keywords": [
+    "taboola",
+    "realize",
+    "advertising",
+    "campaigns",
+    "reporting",
+    "mcp",
+    "analytics"
+  ],
+  "mcp": "../.mcp.json",
+  "systemPrompts": [
+    { "path": "../os/guardrails.md", "required": true }
+  ],
+  "knowledge": {
+    "manifest": "../knowledge/manifest.json",
+    "root": "../knowledge/"
+  }
+}

.gitignore

@@ -1,5 +1,6 @@
-# Per-user plugin state (account defaults, session prefs)
+# Per-user plugin state (account defaults, session prefs, opt-in permissions)
 .claude/*.local.md
+.claude/settings.local.json
 
 # Claude Code tooling caches
 .agent-mail/
@@ -22,3 +23,8 @@ venv/
 .idea/
 .vscode/
 *.swp
+
+# Local PR / review / reply drafts at repo root (not for upstream)
+/pr-description-*.txt
+/pr*-comment-*.txt
+/reply-to-*.txt

CLAUDE.md

@@ -23,15 +23,22 @@ This is a thin Claude Code plugin that wraps the [Realize remote MCP](https://gi
            │                            search_lookalike_audiences, search_contextual_segments,
            │                            search_publishers, search_conversion_rules,
            │                            list_time_zones, list_cta_types
-           ├──► reports skill         → 4 report tools (CSV output)
-           └──► create-campaign skill → UI walkthrough (no MCP writes enabled here)
+           ├──► reports skill          → 4 report tools (CSV output)
+           ├──► optimize-campaign skill → diagnoses underperformance; hands write
+           │                              prescriptions to manage-campaigns
+           └──► manage-campaigns skill → 6 write tools: create_campaign, update_campaign,
+                                         create_native_item, update_native_item,
+                                         create_display_item, update_display_item.
+                                         Tiered preview-then-confirm with mandatory
+                                         ▶ WRITE TARGET account header.
+                                         UI fallback for delete/duplicate/bulk ops.
                      │
                      ▼
 ┌────────────────────────────────────────┐
 │ Realize MCP (https://mcp.realize.com)  │
-│  OAuth 2.1, 18 read tools wired here   │
-│  (upstream also exposes 4 writes —     │
-│  not enabled in this plugin revision)  │
+│  OAuth 2.1, 19 read + 6 write tools    │
+│  wired here. Writes routed exclusively │
+│  through the manage-campaigns skill.   │
 └────────────────────────────────────────┘
 ```
 
@@ -44,7 +51,7 @@ This plugin does not use Claude Code hooks. The remote MCP handles token refresh
 All Realize API access flows through MCP tools. Do not add Bash curl calls that hit Realize endpoints directly — that bypasses the MCP's rate limiting, auth handling, and safety guarantees.
 
 ### Use only tools that actually exist upstream
-The plugin's agent and skills must never fabricate tool calls. When a user requests an action that the current upstream MCP does not expose (e.g., creating a campaign), the `create-campaign` skill takes over with a UI walkthrough. When upstream adds new tools (including write tools), update the agent's Tool Reference, wire the new tool into the most appropriate skill, and trim the `create-campaign` UI walkthrough for the steps that become automatable — in an explicit PR, not silently.
+The plugin's agent and skills must never fabricate tool calls. When a user requests an action that the current upstream MCP does not expose (e.g., deleting or duplicating a campaign — there are no MCP tools for those today), the `manage-campaigns` skill takes over with a UI fallback reference. When upstream adds new tools, update the agent's Tool Reference, wire the new tool into the most appropriate skill, and trim the `manage-campaigns` UI fallback for the steps that become automatable — in an explicit PR, not silently. **Write tools require special handling**: route them exclusively through `manage-campaigns` so the preview-then-confirm gate (and the mandatory `▶ WRITE TARGET` account header) cannot be bypassed.
 
 ### CSV, not JSON
 Report tools return CSV. The leading metadata line (`Records: N | Total: M | Page: X | Size: Y`) is the primary pagination signal. Skills must cite `Total` in their summaries.
@@ -65,7 +72,7 @@ Users often type numeric IDs in natural language. The MCP expects opaque string
 2. Document: when to use, workflow, gotchas, example prompts.
 3. If the skill wraps MCP tools, list them with one-liner descriptions.
 4. Update [README.md](README.md) "Available Skills" table.
-5. Add at least one scenario to [tests/test-scenarios.md](tests/test-scenarios.md).
+5. Add at least one scenario to [`tests/test-scenarios-read.md`](tests/test-scenarios-read.md) (read-only) or [`tests/test-scenarios-write.md`](tests/test-scenarios-write.md) (destructive — include side effects + cleanup).
 6. Update [CHANGELOG.md](CHANGELOG.md) under the next unreleased version.
 
 ## How to sync with upstream MCP changes
@@ -80,12 +87,12 @@ When [taboola/realize-mcp](https://github.com/taboola/realize-mcp) ships a new v
 3. If a tool is removed or renamed:
    - Update the agent and skills.
    - Bump the minor version in [`plugin.json`](.claude-plugin/plugin.json) and note the breaking change in [CHANGELOG.md](CHANGELOG.md).
-4. If **write tools** are added upstream: **do not silently enable them.** Open an issue first; adding writes changes the plugin's safety posture and needs explicit review.
+4. If **write tools** are added upstream: **do not silently enable them.** Open an issue first; adding writes changes the plugin's safety posture and needs explicit review. New write tools land in the `manage-campaigns` skill, behind the same tiered preview-then-confirm gate (with the mandatory `▶ WRITE TARGET` account header) — never routed via the agent directly. Add corresponding scenarios to `tests/test-scenarios-write.md` with explicit side effects and cleanup steps.
 
 ## Conventions
 
 - Plugin name in `plugin.json`: lowercase, no hyphens (`realize`).
-- Skill directory names: lowercase, hyphen-separated (`create-campaign`).
+- Skill directory names: lowercase, hyphen-separated (`manage-campaigns`).
 - Agent filenames: `<name>.md` matching the `name:` frontmatter.
 - YAML frontmatter must be valid — CI validates this (`.github/workflows/validate.yml`).
 - Never write user credentials or tokens to any tracked file. Local per-user state lives in `.claude/*.local.md` (gitignored).
@@ -110,4 +117,4 @@ These are placeholders that should be updated by the repo maintainer before the
 - **`SECURITY.md`** — replace `security@taboola.com` with the real disclosure address if it differs.
 - **`plugin.json` `author`** — currently `"Taboola"`; specify a team or individual maintainer if desired.
 - **`homepage` / `repository` URLs** — confirm the repo lives at `github.com/taboola/realize-claude-plugin` or update.
-- **`CONTRIBUTING.md` contact line** — replace the `TODO: add team alias` comment with the real Taboola Realize team contact.
+- **`CONTRIBUTING.md` contact line** — replace the `TODO: add team alias` comment with the real Realize team contact at Taboola.

CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thanks for your interest in improving the Realize Claude Plugin. Contributions o
 - Be respectful and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
 - This plugin wraps the [Realize remote MCP](https://github.com/taboola/realize-mcp). If your change needs a new MCP tool or a behavioral change on the server side, open an issue on the MCP repo first.
 - Do not add direct API calls to Realize from this plugin (no `curl`, no `httpx`). All data access flows through MCP tools — see [CLAUDE.md](CLAUDE.md) for the reasoning.
-- Do not add code paths that call MCP tools that don't exist in the current upstream release. User-facing requests for actions not yet exposed as MCP tools are handled by the `create-campaign` skill, which walks users through the Realize UI. When upstream adds new write tools, wire them through with an explicit PR and update the `create-campaign` skill rather than silently adding a write path.
+- Do not add code paths that call MCP tools that don't exist in the current upstream release. User-facing requests for actions not yet exposed as MCP tools (today: delete, duplicate, bulk operations) are handled by the `manage-campaigns` skill's UI fallback section. When upstream adds new write tools, wire them through `manage-campaigns` with an explicit PR — never route writes directly through the agent. New writes must inherit the tiered preview-then-confirm gate and the mandatory `▶ WRITE TARGET` account header.
 
 ## Before you start
 
@@ -19,7 +19,7 @@ Thanks for your interest in improving the Realize Claude Plugin. Contributions o
 1. Fork and branch from `main`.
 2. Make your change. Keep PRs focused — one change per PR.
 3. Update documentation:
-   - New skill? Add a row to the README's "Available Skills" table and at least one test scenario in `tests/test-scenarios.md`.
+   - New skill? Add a row to the README's "Available Skills" table and at least one test scenario in `tests/test-scenarios-read.md` (read-only paths) or `tests/test-scenarios-write.md` (destructive paths — include side effects + cleanup).
    - Changed behavior? Note it in `CHANGELOG.md` under the next unreleased version.
 4. Verify locally:
    - `python -m json.tool < .claude-plugin/plugin.json` (valid JSON)
@@ -34,9 +34,11 @@ Thanks for your interest in improving the Realize Claude Plugin. Contributions o
 - [ ] CHANGELOG entry added
 - [ ] Frontmatter + JSON validates
 - [ ] At least one test scenario touches the new behavior
-- [ ] No write paths added to MCP tools
+- [ ] Any new MCP write tool routes through the `manage-campaigns` skill on Claude Code, and the preview-then-confirm gate in `os/guardrails.md` covers it for every runtime (Codex included)
+- [ ] New write paths have a scenario in `tests/test-scenarios-write.md` with explicit side-effects + cleanup
+- [ ] Pre-approval of new write tools stays out of the committed `.claude/settings.json` — per-user opt-in goes through the gitignored `.claude/settings.local.json` template instead
 - [ ] No secrets, tokens, or account-specific data in committed files
 
 ## Contact
 
-For questions that don't belong in an issue, email the Taboola Realize team (TODO: add team alias before the first public release).
+For questions that don't belong in an issue, email the Realize team at Taboola (TODO: add team alias before the first public release).

INSTALL.md

@@ -0,0 +1,100 @@
+# Install the Realize Claude Plugin
+
+> **Status:** the plugin is not yet published to a Claude Code marketplace. Until it is, **use the local-dev path below**. The marketplace path is documented for reference but won't work yet.
+
+## Prerequisites
+- [Claude Code](https://claude.ai/claude-code) CLI installed (`claude --version` works).
+- A Realize account (Taboola SSO).
+- Network access to `https://mcp.realize.com/mcp`.
+- Git installed locally.
+
+---
+
+## Install — local-dev path (works today)
+
+Clone the repo, then launch Claude Code with the `--plugin-dir` flag pointing at it:
+
+```bash
+git clone https://github.com/taboola/realize-claude-plugin
+claude --plugin-dir ./realize-claude-plugin
+```
+
+That's it. `--plugin-dir` loads the plugin (skills, agent, and MCP wiring) directly from the local directory — no marketplace required.
+
+On your first tool call, your browser opens for Taboola SSO. After sign-in, you can run prompts.
+
+**Picking up code changes:** after `git pull`, run `/reload-plugins` inside the Claude Code session to refresh without restarting the CLI.
+
+**Loading multiple plugins at once:** repeat the flag, e.g. `claude --plugin-dir ./realize-claude-plugin --plugin-dir ./other-plugin`.
+
+---
+
+## Install — marketplace path (once published)
+
+The commands below are run **inside a Claude Code session at the prompt** (slash commands), not in your shell.
+
+```
+/plugin marketplace add <marketplace-source>
+/plugin install realize-ads-api@<marketplace-name>
+```
+
+`<marketplace-source>` can be a GitHub shorthand (`owner/repo`), a full git URL, a local path, or a URL to a `marketplace.json`. `<marketplace-name>` is the `name` field declared in that marketplace's `marketplace.json`. The exact values will be filled in here once the Realize team publishes the marketplace.
+
+---
+
+## First run
+
+After install, test with a read prompt:
+
+```
+List my Realize accounts.
+```
+
+If accounts come back, the install is good.
+
+---
+
+## Optional: opt in to skip the permission prompt for write tools
+
+By default, the first call to each of the 6 Realize write tools (`create_campaign`, `update_campaign`, `create_native_item`, `update_native_item`, `create_display_item`, `update_display_item`) triggers a Claude Code permission prompt. This is **defense in depth on top of** the plugin's own preview-then-confirm gate (see [`os/guardrails.md`](os/guardrails.md) → "Write tool gate"). Both checks are recommended.
+
+If you want to skip the harness-level prompt locally (the plugin gate still fires on every write):
+
+```bash
+cp .claude/settings.local.json.example .claude/settings.local.json
+```
+
+`settings.local.json` is gitignored — it is a per-user opt-in and is **not** shipped with the repo.
+
+---
+
+## Install on Codex (experimental)
+
+> **Status:** the `.codex-plugin/` manifest exists in the repo but Codex support is not yet validated. Treat this section as a starting point; confirm the MCP URL/port for your Codex deployment before relying on it.
+
+The Codex build wires the Realize remote MCP and ships the system-prompt + knowledge layer. The Claude Code skills (campaign creation workflows, optimization diagnostics, report aggregation) are not loaded on Codex; the **write tool gate is defined in [`os/guardrails.md`](os/guardrails.md)** so it applies on Codex too.
+
+Two things differ from the Claude Code install:
+
+1. **Manifest name.** Codex loads `.codex-plugin/plugin.json`, where the plugin is registered as `realize-ads-api` (not `realize`). When installing into a Codex marketplace, use `realize-ads-api` as the plugin slug.
+2. **MCP URL / port.** The shared `.mcp.json` points at `https://mcp.realize.com/mcp` with OAuth callback port `3000`. The Codex build inherits this endpoint by default. Confirm with the Realize team whether your Codex deployment uses the same endpoint before installing — if Codex routes the realize-mcp differently, do not modify the shared `.mcp.json`; raise it with the Realize team for guidance on the correct override mechanism for your Codex environment.
+
+After install, run a read prompt the same as on Claude Code:
+
+```
+List my Realize accounts.
+```
+
+If a write is attempted on Codex, the preview-then-confirm gate from `os/guardrails.md` fires identically — no skill is required.
+
+---
+
+## Troubleshooting
+
+- **Browser didn't open for OAuth** → free port `3000`, retry.
+- **`search_accounts` returns nothing** → wrong SSO realm; check your Taboola login.
+- **Wrong account in a write preview** → re-run the `accounts` skill before retrying.
+- **`/plugin install` says "unknown marketplace"** → the marketplace hasn't been added yet. Run `/plugin marketplace add <source>` first, or fall back to the local-dev path above.
+- **Changes to a local plugin aren't visible** → run `/reload-plugins` inside the session.
+
+Full docs: [README.md](README.md) · Claude Code plugin docs: https://code.claude.com/docs/en/plugins