Embed realize-toolkit, align with Apr 2026 brand guardrails

[amitl-levi]

Summary

• Embeds the realize-toolkit knowledge layer into the plugin:
  os/guardrails.md (consolidated system-prompt), knowledge/ (10 topic MDs +
  manifest.json), scripts/brand-check.sh (linter).
• Applies the Apr 2026 PMM brand guardrails across all plugin content.
• Aligns operational thresholds with the toolkit (toolkit treated as
  authoritative source).
• Consolidates the os/ layer from 4 files (guardrails, tone,
  orchestration, routing) into 1 (guardrails) — Claude Code skill-routing
  handles intent matching natively.
• Removes redundancy: duplicate attribution rules folded into the global
  guardrails layer, and backlog.md removed (content lives in
  docs/realize-best-practices-gap.md Part 3).

Why

• Brand: PMM published an updated brand-guardrails doc (Apr 2026) with
  feature renames and tightened banned positioning. Plugin now follows it.
• Knowledge alignment: plugin had thresholds taken from public Taboola
  help articles that contradicted the internal realize-toolkit best practices.
  The toolkit is now the authoritative source.
• Architecture: skills already handle intent routing natively, so a
  separate routing.md was redundant. Single source of truth =
  os/guardrails.md.

Key changes

Area	Before	After
Feature naming	Realize Pixel; Marketplace Audiences; Realize 1P
Taboola Pixel; Taboola First Party Audiences
UI naming	Realize console	Realize UI
Brand naming	"Taboola Realize"	"Realize" alone
Click threshold (item-level diagnosis)	500–1000 clicks per item	**100+
clicks per item**
Spend threshold (CPA/CVR diagnosis)	$50/day flat	**daily spend ≥ 8× CPA
goal**
Learning phase	7–10 days (mixed elsewhere)	**7–10 days, consistent
everywhere**
Ads per campaign	3–10	4–6 (never more than 10)
Creative variations	5–10 per URL	**3 distinct titles + 3 unique images
per campaign**
Fixed Bid budget	5× CPA daily / 150× monthly	per client requirements
(manual)

Test plan

• bash scripts/brand-check.sh passes (0 FAIL, 1 known false-positive
  WARN)
• Open the plugin in Claude Code; verify the realize-analyst agent reads
  os/guardrails.md at session start
• Ask "Which bid strategy for a new conversion campaign?" — should consult
  knowledge/bidding.md
• Ask "CPA is 3× goal" — should activate optimize-campaign skill with
  the new toolkit-aligned thresholds
• Verify Taboola Realize, Realize console, Marketplace Audiences no
  longer appear in any output

Notes for review

• backlog.md deleted — content (with more detail, including UI paths) is in
  docs/realize-best-practices-gap.md Part 3.
• Three pre-existing TODO: markers remain in CLAUDE.md, CONTRIBUTING.md,
  SECURITY.md — not introduced by this PR.
• scripts/brand-check.sh allows item_id as a public MCP parameter (it
  remains banned as a schema column in the realize-toolkit's separate linter
  copy).
• 26 files changed (13 new, 13 modified), +2467 / -63 lines.

Amit comment:

Update (Jun 16 2026 — commit a0d6176)

Addresses all 13 review threads from @chrishall-taboola + bonus work for block-list wiring and guardrails v4 alignment.

MCP write-surface API fixes

skills/manage-campaigns/references/mcp-write-surface.md

• Readback tool names → list_campaigns / list_items / get_item
• spending_limit_model="DAILY" → "NONE" + daily_cap + daily_ad_delivery_model="STRICT"
• conversion_rules shape → {"rules":[{"id":<int>}]}
• target_roas removed; roasGoal documented as update-only / DCO-only / not MCP-wired
• publisher_bid_modifier shape → {"values":[{"target":<name>,"cpc_modification":<multiplier>}]}
• cpc_cap narrowed to MAX_CONVERSIONS only

SKILL ↔ knowledge contradictions

• TARGET_CPA min: 5×/150× → 10× CPA/day
• SMART (Enhanced CPC) split out with 5×/150× min
• cpc bid-lever: SMART + FIXED (was FIXED only)
• Bundling threshold: per-day, strategy-specific
• Canonical bid-lever matrix in bidding.md: dropped Target ROAS row, fixed cpc_cap row, added editing-note guard

Codex + permissions safety

• Write-gate ported into os/guardrails.md (covers Codex without skills)
• .claude/settings.json write-tool allowlist removed; per-user opt-in template at .claude/settings.local.json.example
• INSTALL.md adds Codex install section + opt-in permissions doc
• CONTRIBUTING.md checklist rewritten to match enabled writes

Manifest + Campaign Groups + closed-gap restructure

• manifest.json creative entry trimmed (phantom Wilson / 1P/3P tags removed)
• Pointer added in creative.md to targeting.md for the Display item shape
• Campaign Groups: MCP-status callout (UI-only today)
• docs/realize-best-practices-gap.md: closed-gap rows moved out of "Future ability" tables

Block-list wiring (from Chris's Jun 15 upstream work)

Publisher block-list edits routed through update_campaign(publisher_targeting=...):

• agent triage updated (was UI-only)
• new manage-campaigns recipe: search_publishers → get_campaign → merge → top-N guard → preview → write → verify
• new W4b test scenario with full-replace gotcha + cleanup
• gap-doc closed-gap notes + CHANGELOG entry

Guardrails v4 brand spec alignment

• Backstage added to Banned brand variations
• Banned company-vs-platform framing section removed
• Internal codename → external name mapping section removed; runtime echo guard added
• Banned competitor terminology → Banned industry terms

Verification: scripts/brand-check.sh passes (0 FAIL, 5 WARN — all pre-existing false-positives). 19 files changed, 342 insertions, 108 deletions.

[chrishall-taboola]

mcp-write-surface.md:195-198 — nonexistent readback tools. Table lists get_all_campaigns, get_campaign_items, get_campaign_item — none exist in the MCP. Correct names: list_campaigns, list_items, get_item.

[chrishall-taboola]

mcp-write-surface.md:210 — invalid spending_limit_model="DAILY". Enum is NONE|MONTHLY|ENTIRE (API + MCP). For a daily budget use spending_limit_model="NONE" + daily_cap= + daily_ad_delivery_model="STRICT".

[chrishall-taboola]

mcp-write-surface.md:214,240 — wrong conversion_rules shape. Sends [{"rule_id":""}]; API/MCP expect {"rules":[{"id":}]} (key id, nested under rules, integer not string).

[chrishall-taboola]

mcp-write-surface.md:239 (block 232-243) — target_roas at create is impossible. Field name is wrong (API = roasGoal) and ROAS can't be set on create_campaign for any account; it's update-only, DCO-accounts-only, and MCP doesn't wire it at all. Remove the field/example. (Plugin fix now; separate upstream MCP issue if ROAS support is ever wanted.)

[chrishall-taboola]

mcp-write-surface.md:252-254 — wrong publisher_bid_modifier shape. Sends [{"publisher_id":,"modifier_pct":+20}]; API/MCP expect {"values":[{"target":"<publisher_name>","cpc_modification":1.25}]} (publisher name not id; multiplier not percent).

[chrishall-taboola]

CONTRIBUTING.md:37 — checklist - [ ] No write paths added to MCP tools contradicts the now-enabled writes. Reword to the real policy.

[chrishall-taboola]

Codex build (.codex-plugin/plugin.json) ships the full .mcp.json — including the 6 write tools — but none of the skills, so its claim that writes are "not available on Codex" is false and writes run without the manage-campaigns preview-confirm gate. Either port the write-gate into os/guardrails.md (or scope Codex to read-only) and document/test it, or drop the manifest until Codex is a real target.

Note the realize-mcp runs on different port for codex - so mcp install instructions should change if codex is supported. Also conflicts with name of repo.,

[chrishall-taboola]

Fix contradictions between skill and knowledgebase:

• skills/manage-campaigns/SKILL.md:156 — TARGET_CPA daily budget minimum contradicts the knowledge base. SKILL says TARGET_CPA = 5× CPA/day + 150× CPA/month;
  knowledge/bidding.md:18-19,123 and knowledge/budget.md say Target CPA = 10× CPA/day (same as Maximize Conversions). The 5×/150× figure is Enhanced CPC's minimum,
  mis-assigned to this row. Fix: set TARGET_CPA to 10× CPA/day ($50 min if CPA < $5) to match knowledge/bidding.md.
• skills/manage-campaigns/SKILL.md:158 — SMART (Enhanced CPC) shown as having no minimum, contradicts the knowledge base. SKILL groups SMART, MAX_VALUE as "don't block on a
  hard minimum." But os/guardrails.md:126 maps SMART → Enhanced CPC, and knowledge/bidding.md:124 + knowledge/budget.md give Enhanced CPC a published 5× CPA/day + 150×
  CPA/month minimum. Fix: split SMART out and give it the 5× daily / 150× monthly minimum; leave MAX_VALUE as client-defined.
• skills/manage-campaigns/SKILL.md:153 — cpc bid-lever gate excludes Enhanced CPC, contradicts the knowledge base. SKILL gates the cpc scalar bid to bid_strategy=FIXED
  only; knowledge/bidding.md:62-66 (and optimization-flow.md:224) put campaign-level CPC bids under both Enhanced CPC (SMART) and Fixed Bid (FIXED). Fix: allow cpc on SMART
  and FIXED.

[chrishall-taboola]

Committed permissions.allow pre-approves all 6 raw write tools → no permission prompt. The preview-then-confirm gate is otherwise just SKILL.md prose; this allowlist
deletes the one harness-level check, and ships it to every clone.

• Fix: move to settings.local.json (per-user opt-in), or drop pre-approval and let the prompt fire. Echoes the write-posture point from earlier — this is its concrete
  config root.

[chrishall-taboola]

knowledge/manifest.json creative entry — phantom content ✓ confirmed

Manifest advertises tags + description for creative.md that don't exist in the file. Verified grep counts in creative.md: Wilson=0, validity tier=0, 3P=0, 1P=0,
create_display_item=0, ad_tag=0, asset_url=0. Description promises "Wilson score lower bound" + "1P-hosted + 3P JS-tag paths via MCP" — none present.

• Fix: either trim the manifest to match creative.md, or add the missing Display-recipe + Wilson-ranking content.

See creative.md for the full Display recipe." No Display recipe in creative.md (no 3P/1P/ad_tag/asset_url). The real Display item shape lives in targeting.md:206-209.

• Fix: repoint to the correct file, or add the recipe to creative.md

[chrishall-taboola]

knowledge/campaign-structure.md:64 vs 66 — inconsistent bundling thresholds. CONFIRMED (low).

Both lines answer the same question — "when is budget too small to split platforms, so bundle instead?" — but with different, unreconciled units:

• Line 64: bundle all platforms when "budget is so small that splitting would kill algo learning (under ~$5K total)."
• Line 66: bundle when budget/campaign falls below learning threshold (< $1k/day for MAX_CONVERSIONS, < $500/day for FIXED).

The problem: one is a total figure, the other per-day + strategy-specific, with no relationship stated. They can disagree — e.g., a $3k/day campaign over a 1-day flight is
$3K total (< $5K → "bundle" by line 64) but $3k/day (> $1k/day → "split" by line 66). A reader can't tell which test governs.

• Severity: low — guidance prose, not a hard gate; both point the same direction in the common case.
• Fix: pick one basis (per-day is more actionable and matches the bid-strategy framing), or explicitly relate the $5K-total figure to the per-day thresholds (e.g., "≈ the
  per-day minimum × typical flight length").

[chrishall-taboola]

skills/manage-campaigns/SKILL.md:52 says cpc_cap "valid on all strategies (… MAX_CONVERSIONS / TARGET_CPA / MAX_VALUE)." API + MCP both say MAX_CONVERSIONS only (CpcCapTransformer.java:39; registry.py:500). Sending cpc_cap on TARGET_CPA/MAX_VALUE → API 400. Note: knowledge/bidding.md is silent on this, so the SKILL is the lone offender. Fix: "valid only on MAX_CONVERSIONS.

[chrishall-taboola]

Campaign Groups are heavily mentioned in plugin - but does not yet have MCP support. Maybe remove it until we have MCP support?

[amitl-levi]

@chrishall-taboola — all 13 review items addressed in commit a0d6176. Walking through them in your order:

1. mcp-write-surface.md:195-198 — nonexistent readback tools

Renamed in the "Readback (after writes)" table: now list_campaigns, list_items, get_item. Cross-checked against the runtime MCP tool list.

2. mcp-write-surface.md:210 — invalid spending_limit_model="DAILY"

Both MaxConv and Target CPA payload examples now use spending_limit_model="NONE" + daily_cap + daily_ad_delivery_model="STRICT". Scalar-field table + the update_campaign intent table also updated to the NONE | MONTHLY | ENTIRE enum.

3. mcp-write-surface.md:214,240 — wrong conversion_rules shape

Both examples now send conversion_rules={"rules":[{"id":<int>}]}. Scalar-field row rewritten with explicit nesting / key / type notes.

4. mcp-write-surface.md:239 — target_roas at create is impossible

"Maximize Value with target ROAS" example removed; replaced with a plain Max Value example + a note: roasGoal is update-only, DCO accounts only, and not currently exposed by the MCP. Same note propagated to the scalar table (roasGoal row labeled NOT writable via MCP), knowledge/bidding.md, and optimize-campaign/references/optimization-flow.md. The canonical bid-lever matrix in bidding.md had its Target ROAS row dropped entirely.

5. mcp-write-surface.md:252-254 — wrong publisher_bid_modifier shape

Now {"values":[{"target":"<publisher_name>","cpc_modification":1.20}, ...]} with inline comments calling out "multiplier, not delta" and "publisher name, not ID". Scalar-field row also rewritten.

6. CONTRIBUTING.md:37 — "No write paths added" line

Replaced with three checklist items reflecting the real policy: any new write tool routes through manage-campaigns, the write-gate in os/guardrails.md covers every runtime, and pre-approval stays out of committed settings.json (per-user opt-in via the gitignored settings.local.json template).

7. Codex build — full .mcp.json without the gate; install instructions

Ported the write-gate into os/guardrails.md so Codex inherits it without needing skills. New Write tool gate section lists the 6 write tools, mandates the ▶ WRITE TARGET header, defines explicit Yes/No/Edit confirm, refuses confirmation-skip framings, requires scope-fan-out confirmation, and routes UI-only actions at the Realize UI. Self-check at the bottom of the file updated. .codex-plugin/plugin.json description updated. INSTALL.md got a new "Install on Codex (experimental)" section flagging the manifest-name conflict (realize-ads-api vs realize) and the MCP URL/port caveat.

One open question: I couldn't verify the Codex MCP endpoint from the public README (source moved to a private repo on Jun 9). INSTALL.md currently says to confirm the URL/port with the Realize team. If you can paste the actual Codex endpoint, I'll plug it in as a small follow-up.

8. SKILL ↔ knowledgebase contradictions (3 sub-items)

In skills/manage-campaigns/SKILL.md:

• TARGET_CPA min: 5×/150× → 10× CPA/day ($50 min if CPA < $5). Matches knowledge/bidding.md + knowledge/budget.md.
• SMART (Enhanced CPC): split out into its own row with 5× CPA/day + 150× monthly. MAX_VALUE left as "per client requirements."
• cpc bid-lever: now allowed on SMART or FIXED (was FIXED only).

While there, also reconciled the canonical Bid Levers matrix in knowledge/bidding.md itself (the one referenced as canonical by mcp-write-surface.md §4 and optimize-campaign/references/optimization-flow.md §6) — dropped the false Target ROAS row, fixed the cpc_cap row to MAX_CONVERSIONS only, added an editing-note callout pointing future editors at the downstream copies to keep them in sync.

9. Committed permissions.allow pre-approval

6 write tools removed from committed .claude/settings.json (block deleted). Added .claude/settings.local.json.example as a per-user opt-in template; settings.local.json now gitignored. INSTALL.md documents the opt-in path under "Optional: opt in to skip the permission prompt for write tools."

10. manifest.json creative entry — phantom content

Hybrid fix per your suggestion:

• knowledge/manifest.json creative entry: dropped phantom tags (Wilson, validity tier, 3P JS tag, 1P-hosted display, create_display_item, ad_tag, asset_url); description rewritten to match what creative.md actually covers.
• knowledge/creative.md: added a one-line pointer at the top to knowledge/targeting.md for the Display item MCP payload shape (3P ad_tag vs 1P asset_url + dimensions).
• Cross-reference tables in mcp-write-surface.md §8 and optimization-flow.md §12 also rewritten — they used to make the same false claim about creative.md. Now they point at the actual locations (targeting.md for the payload shape, optimization-flow.md §3 for Wilson-score ranking).

11. campaign-structure.md:64 vs :66 — inconsistent bundling thresholds

Picked the per-day, strategy-specific basis per your recommendation. The "~$5K total" figure is gone from L64; L66 (now slightly reworded) is the single rule: < $1k/day for MAX_CONVERSIONS / TARGET_CPA, < $500/day for FIXED.

12. SKILL.md:52 — cpc_cap valid on all strategies

Now reads "valid only on bid_strategy=MAX_CONVERSIONS" (sending on TARGET_CPA / MAX_VALUE / SMART / FIXED returns API 400). Same correction propagated to the scalar field table in mcp-write-surface.md, the bid-lever matrix in the same file, the refuse-and-reframe rules, the failure-mode table, and the canonical matrix in bidding.md. Thanks for the CpcCapTransformer.java:39 and registry.py:500 citations — those were the source of truth.

13. Campaign Groups — no MCP support

Kept the conceptual content (still useful for users planning their structure in the UI) but added an explicit MCP-status callout at the top of the Campaign Groups section in knowledge/campaign-structure.md:

MCP support status: Campaign Group assignment is not exposed via the Realize MCP today. create_campaign and update_campaign accept no campaign_group_id parameter. Group creation and campaign-to-group assignment are UI-only actions — when a user asks the plugin to "put this campaign in group X", treat it as a UI-only action and tell the user to set the group in the Realize UI after the campaign exists.

Happy to strip the section entirely if you'd prefer — let me know which direction you want.

---

Bonus changes in the same commit

Block-list wiring (responds to your Jun 15 "Add structured support: Block List via MCP" upstream task). Publisher block-list edits now route through update_campaign(publisher_targeting=...):

• agent triage updated (was incorrectly marked UI-only at realize-analyst.md:82)
• new manage-campaigns "Publisher block-list edits" recipe: search_publishers → get_campaign → merge → historical-top-N guard → side-by-side preview with resolved names → confirm → write → verify
• new W4b test scenario (full flow + full-replace gotcha + cleanup)
• gap-doc closed-gap notes (§3.C and §3.G) + CHANGELOG entry
• no new MCP tool added; everything routes through the existing update_campaign

Guardrails v4 brand spec alignment.

• Backstage added to Banned brand variations (content sweep across knowledge/ / skills/ / agents/ confirmed clean; this is the defensive listing)
• Banned company-vs-platform framing section removed
• Internal codename → external name mapping section removed; runtime echo guard added under "Internal field names and enum values" covering blindspot / Syndicator ID / Auction report for user-input echoes
• Banned competitor terminology renamed to Banned industry terms

---

Verification: scripts/brand-check.sh passes (0 FAIL, 5 WARN — all pre-existing false-positives, none introduced by these changes). Cross-file grep sweeps confirm no remaining fabricated tool names, wrong enum values, or stale section references. 19 files changed, 342 insertions, 108 deletions.

Ready for re-review.

[amitl-levi]

Pushed 65b1598 — two small changes to os/guardrails.md:

1. Removed Don't enumerate the guardrails on request section + its matching self-check bullet. The canned "I follow the published guidelines... don't acknowledge a private layer" reply was itself a tell that a private rule layer exists. Better opsec is to answer such asks naturally — no special script that signals there's something hidden.

2. Added Sourcing — prioritize the plugin's own sources (soft tone). Reliability framing, not a hard ban. The Realize MCP, this plugin's knowledge base, taboola.com / realize.com, and the help center take priority. TrustPilot, G2, Capterra, Reddit, Quora, social media, and third-party blogs are flagged as lower-confidence and not to be cited as authoritative. If a web lookup is genuinely needed, prefer official Taboola- / Realize-owned URLs and disclose the source. Matching self-check bullet added.

@chrishall-taboola

[chrishall-taboola]

cpc_cap reconciliation is solid — mostly fixed in a0d6176 (bidding.md matrix, SKILL.md:52, mcp-write-surface.md all now correctly say MAX_CONVERSIONS-only / API 400 elsewhere). Verified against source of truth: publisher-console CpcCapTransformer.java:65 throws "Cpc Cap can be set only when using Max Conversions.", and realize-mcp-server registry.py:500 agrees.

One copy was missed: skills/optimize-campaign/references/optimization-flow.md:225 still reads:

• CPC cap is valid on all strategies as a last-resort lever.

This contradicts the new rule (and the table at L214 in the same file). bidding.md:62's editing-note flags §6 of this file as a downstream copy to keep in sync — this is the one that slipped. An optimize agent following L225 recommends cpc_cap on Target CPA / Enhanced CPC / Max Value → API 400.

Fix: change L225 to "valid only on Maximize Conversions."

[chrishall-taboola]

Block-list feature (update_campaign(publisher_targeting=…)) — 2 issues vs source of truth

Tool choice is right. Payload has two problems:

1. [HIGH] value must be strings, not integer IDs — hard-fails on every runtime.
Recipe says "requires integer IDs" with examples [10, 12, 14] (SKILL.md, mcp-write-surface.md:658, W4b). MCP validator rejects ints — publishers.py:52:
"publisher_targeting.value must be a list of strings". Schema is items: {type: string}; feed the strings from search_publishers verbatim. Drop "integer IDs" + the
numeric examples.

2. [HIGH] Codex path missing the merge rule.
publisher_targeting is full-replace (registry.py:68–71). Merge-before-write lives only in the skills; os/guardrails.md's gate (Codex loads this, no skills) says
"capture current state" but never "merge." On Codex "block ESPN" silently wipes existing blocks. Hoist the merge rule into os/guardrails.md.

[chrishall-taboola]

skills/discovery/SKILL.md:75 mis-types IDs vs the API contract

The line says:

audience_id, segment_id, rule_id, and publisher id are opaque values returned by the API. Do not coerce to int …

Checked against APICampaign.java (backstage-api-model) and the MCP schemas — 3 of the 4 are integers, not opaque strings:

Field	API POJO	MCP schema
audience IDs	MultiTargeting<Long> (:125)	integer (registry.py:320)
segment IDs	MultiTargeting<Long> (:126)	integer (registry.py:345)
lookalike rule_id	long	integer (registry.py:376)
publisher targeting	Targeting<String> (:70)	string ✓

So an agent obeying this line quotes audience/segment/lookalike IDs as strings → MCP integer-schema rejects → silent fail across three targeting types. Only publisher is a
string (and there the block-list recipe says the opposite — "integer IDs" — see the block-list comment).

Fix (plugin, not MCP — the MCP matches the POJOs): correct :75 to — account/campaign/item/publisher IDs are opaque strings; audience / segment / lookalike rule_id /
conversion-rule id are integers. Pre-existing (file not in this PR), but adjacent to the conversion_rules change here.

[chrishall-taboola]

Display ad_tag docs: dangling allowlist pointer + wrong error-recovery advice

Checked against DisplayAdTagValidator (publisher-console) + MCP error path.

1. Dangling pointer. Six refs (realize-analyst.md:187, SKILL.md:32/334/351, mcp-write-surface.md:107/319) say "see knowledge/creative.md for the validator
allowlist / strip rules." creative.md has none of that (0 matches, even pre-PR). Also no enumerable "allowlist" exists — validation is a per-vendor ordered
List<TagConfig>, server-side.

2. Recovery advice keys off the wrong error. SKILL.md:351 / mcp-write-surface.md:319:

If 400 Unsupported tag, the 3P tag failed the allowlist — strip any HTML wrapper and retry.

The validator throws two distinct 400s, and the MCP proxies the message body back to the agent (errors.py: 4xx body returned for self-correction), so the agent matches on
the text:

• "Unsupported tag" (UNSUPPORTED_TAG, L56) → vendor not configured (tagsConfig == null). Stripping a wrapper won't fix it.
• "Invalid html tag structure" (INVALID_STRUCTURE, L52) → malformed/wrapped markup. This is the strip-the-wrapper case.

So the advice fires on the wrong condition.

Fix (plugin; MCP is fine): drop the "see creative.md for the allowlist" promise; document the two real failure modes — unsupported vendor vs malformed structure.
Pre-existing, but the PR gutted creative.md further. (Minor: confirm APIBadRequestException("Unsupported tag") serializes into the JSON message field the agent matches
— standard mapping, not traced.)

[chrishall-taboola]

"Pace Ahead" recommended as an action, but it's a gated field not exposed via MCP

bidding.md (228, 365) and budget.md (56, 113, 122, 170) recommend the Pace Ahead feature to accelerate spend, as if it's actionable. The MCP exposes no field for it (0
matches in realize-mcp-server).

Checked the API: Pace Ahead is real but gated — APICampaign.budgetAdditionalParameters.paceAheadFactor, validated against per-account publisher config
(PaceAheadFactorValidatorImpl(PublisherConfigProvider)), with a FilterOutBudgetAdditionalParameters mixin and a BALANCED-only state dependency. So the MCP omission is
deliberate, not an oversight.

This is the same posture as roasGoal (gated → DCO-only, FilterOutRoasGoal, not in MCP), which this PR correctly flagged UI-only. Pace Ahead was missed → an
optimize-campaign agent prescribes "use Pace Ahead" → routes to manage-campaigns → no field → attempt-and-discover-halfway.

Fix: add a "Pace Ahead is UI-only — gated field, not exposed via the MCP; set it in the Realize UI" callout next to these recs, matching the roasGoal treatment. (Dropping
ACCELERATED from daily_ad_delivery_model is correct — deprecated in MCP, and Pace Ahead is a separate field, not that enum value.)

[amitl-levi]

Thanks Chris — all 5 addressed across 4e580de and adc66c8 (self-review on the first commit caught a bug in the Codex merge rule, fixed in the second).

1. publisher_targeting payload (HIGH) — strings not integers, across SKILL.md, mcp-write-surface.md, and the W4b test scenario. MCP validator rejects integers; we now feed the publisher ID strings from search_publishers verbatim.

2. Codex merge gap (HIGH) — hoisted the full-replace merge rule into os/guardrails.md step 2 of the Confirmation flow. Self-review on 4e580de caught three invented field names (audience_targeting / _excluded / contextual_segments); adc66c8 corrects them to the real schema from mcp-write-surface.md:67-69 — audiences_targeting, contextual_segments_targeting, lookalike_audience_targeting — extends to all 11 full-replace targeting blocks, and adds the item-update arrays verification_pixel / viewability_tag.

3. cpc_cap reconciliation — optimization-flow.md:225 now correctly Maximize-Conversions-only with API-400 note, matching the L214 matrix.

4. Discovery ID typing — discovery/SKILL.md:75 distinguishes opaque strings (account / campaign / item / publisher) from integers (audience_id, segment_id, lookalike rule_id, conversion-rule id), matching the API POJOs and MCP schemas.

5. Display ad_tag — dropped the dangling creative.md allowlist pointers (3 refs); split the 400 error-recovery into Unsupported tag (vendor not configured — route to AM, do not retry) vs Invalid html tag structure (strip the wrapper and retry).

Also: Pace Ahead UI-only callout added at all 6 refs across bidding.md and budget.md, mirroring the existing roasGoal pattern.
@chrishall-taboola

[amitl-levi]

Two related runtime tone rules added to os/guardrails.md
and propagated through the knowledge layer. Anchor for both:
brand-voice review feeding into product, June 2026.

• Publisher and site framing — measurable performance, not
  name. Publisher / site recommendations describe measurable
  performance ("0 conversions over 14 days", "CPA exceeds 3×
  campaign average") + action — never the publisher's character
  or reputation in the abstract. Ties back to existing frozen
  brand phrases (Embedded publisher integrations, Code on
  page integrations) so the rule reads as brand-voice
  extension rather than a banned-word list. Removes the one
  upstream priming anchor in knowledge/site-management.md
  ("blocking bad sites" → "excluding sites that underperform
  on the campaign's KPI"). Adds defense-in-depth FAIL regexes
  to scripts/brand-check.sh.
• Reader framing — the operator, not a relay through
  them. The reader is the campaign operator (self-serve
  advertiser, agency running on behalf of a brand, or in-house
  media buyer) — never a Taboola Account Manager relaying
  instructions to "the client". Possessive "your client" /
  "my client" stay in voice for the agency case.
  Knowledge-layer reader-voice sweep across 9 files (~30
  phrasings + 3 section retitles, all rewrites stay in
  advertiser-direct second person or neutral instructional
  voice — no net-new content). Adds AM-relay FAIL regexes to
  scripts/brand-check.sh, tight enough that "your Account
  Manager", "client-side merge", and possessive "your
  client" stay valid.

Section retitles:

• knowledge/brand-safety.md "When an Advertiser
  Complains" → "Responding to a Brand-Safety Complaint"
• knowledge/tracking.md "When the Advertiser Refuses Pixel
  or S2S" → "When Pixel or S2S Isn't an Option"; inline
  "How to communicate this to clients" → "What to plan for"
• knowledge/environments.md "Sponsored Content ↔ Display
  Upsell" → "Sponsored Content ↔ Display Expansion" (4
  table-row rewrites)

Silent self-check bullets added to os/guardrails.md for
both rules.

[amitl-levi]

Pushed one more fix— surgical README edit (one line in, one line out, no other files touched).

Replaces the single descriptive sentence about the realize-analyst agent with a directive paragraph that (a) leads with "Start with a skill, not the MCP" in bold, (b) names what the skills carry that raw MCP calls bypass — account resolution, CSV conventions, optimization playbook, write-preview gate — and (c) pins the most common install-time miss: "performance review" or "insights" asks being answered as ad-hoc analysis instead of being routed to optimize-campaign.

Context: caught from a real install transcript where Claude went straight to the MCP tools and only invoked the skill after being explicitly asked "did you use the skill set?"