Add the AI Brand Representation Snapshot recipe and result contract

[sergeliatko]

Implementation readiness gate

Do not begin implementation until the connected private SEO Agent Tools runtime has released a stable aligned direct contract for its ChatGPT, Gemini, and Perplexity brand-representation operations.

The private runtime must already provide, for every channel:

• the same public input structure;
• required invocation-scoped recognition status;
• optional canonical finite numeric awareness, sentiment, and credibility scores;
• normally billed exact no-report/not-recognized outcomes;
• explicit guidance that scores do not share a calibrated cross-channel scale.

This public issue must not import private traces, private tool bindings, supplier payloads, current customer prices, tenant state, or deployment details. Re-fetch the connected runtime contract when the gate is satisfied rather than relying on remembered versions.

Outcome

Publish a new immutable public catalog release containing an agent-executed recipe and dedicated result contract for this job:

Given a brand name, bare domain, or public URL and optional market framing, observe how ChatGPT, Gemini, and Perplexity currently represent that brand under the same conditions, then return one evidence-linked snapshot with honest comparison rules and explicit incomplete-result behavior.

The product is AI Brand Representation Snapshot.

It measures prompted, brand-conditioned representation. It does not measure unprompted buyer-prompt presence, stable model knowledge, historical trends, or business impact.

Product terminology

Use these meanings throughout the recipe, schema, skill guidance, fixtures, and release notes:

• Brand representation: a generated report produced after the brand or website is explicitly supplied.
• Recognition status: whether one invocation returned a structured report or an exact no-report signal. It is not stable model knowledge.
• Source descriptor: a generated source, channel, publication, or content-type string. It is not automatically a verified citation.
• Snapshot: one bounded, current, non-persistent set of channel observations.
• Controlled competitor panel: competitors explicitly supplied before the channel calls.
• Generated competitors: competitors proposed by a channel when no controlled panel was supplied or beyond that panel.

Recipe identity

• ID: ai-brand-representation-snapshot
• Version: 1.0.0
• Title: AI Brand Representation Snapshot
• Primary domain: add visibility
• Operations: use compare, diagnose, and validate
• Target: add brand
• Required input: brand

The required input description must accept a brand name, bare public domain, or HTTP/HTTPS public URL. Optional location, competitor, and product/service framing is acquired and settled by the methodology before channel observations.

Do not expand the generic recipe schema solely to add typed optional inputs. The dedicated result contract owns the settled framing shape.

Controlled vocabulary additions

Add only the values needed to express this method accurately.

Evidence unit

Add:

• channel

Capabilities

Add three explicit channel capabilities:

• brand-representation-chatgpt
• brand-representation-gemini
• brand-representation-perplexity

Use separate capabilities rather than introducing a grouped or alternative capability language. A private runtime can map each capability independently to its current operation and price.

Do not encode private tool names, provider adapters, or request counts beyond the public evidence scope of one observation per channel.

Required methodology

1. Settle the framing before spending

Record one framing object containing:

• supplied brand value;
• settled brand name when known;
• canonical website when known;
• location or market when supplied;
• controlled competitor panel when supplied;
• products or services when supplied;
• unresolved identity limitations.

Rules:

• Use identical framing for all channel observations.
• Never invent competitors or products to satisfy a private runtime minimum.
• When fewer than the connected runtime's required competitor minimum are confirmed, omit the panel rather than padding it.
• Supplied products/services are framing inputs and may be echoed by a channel; they are not independently discovered associations.
• A domain or URL can identify a website without proving the intended customer-facing brand. Stop before paid work when the subject remains materially ambiguous.

2. Preflight current execution

Before paid evidence collection:

• resolve the current recipe through the connected server;
• inspect current availability and result contracts;
• obtain the current required/default/maximum budget;
• confirm authorization and headroom;
• stop when a required channel capability is unavailable before execution.

Do not copy numeric prices into public methodology.

3. Observe each channel once

Plan exactly one observation from each channel capability using the settled framing.

• Do not rerun a valid report or valid not-recognized result to obtain a preferred outcome.
• A server-directed retry for an actual retryable execution failure remains governed by the connected server.
• Preserve a failed or unavailable channel in the result rather than silently omitting it.
• A valid negative/not-recognized result is evidence, not a failed operation.

4. Interpret each observation

For each channel record:

• outcome and recognition status;
• observation time;
• exact conditions;
• awareness, sentiment, and credibility categories;
• native scores when supplied;
• generated topics and associations;
• generated source descriptors;
• controlled-panel competitor evidence separately from generated competitor discoveries;
• limitations and quality notes.

Rules:

• Missing scores are unavailable, not zero.
• Native scores do not share a guaranteed cross-channel scale.
• Do not average, normalize, or rank channels by score.
• Categories are generated labels and may be placed side by side, but are not calibrated measurements.
• Generated source descriptors are not verified citations.
• Mixed-language or placeholder-like content may be flagged without silently translating or rewriting the underlying evidence.

5. Compare only supported dimensions

Cross-channel comparison may describe:

• which channels returned reports or not-recognized observations;
• exact category agreement or disagreement;
• qualitative differences in descriptions, topics, associations, and competitors;
• overlap and divergence in generated competitors;
• limitations caused by missing or failed observations.

Do not calculate:

• a universal visibility score;
• a cross-channel average;
• a channel ranking from native scores;
• buyer-prompt mention rate;
• trend or change over time.

At least two usable structured reports are required for claims comparing report contents. Negative/not-recognized observations remain evidence about their own channels but do not supply report categories or scores.

6. Return and validate the result

Return the exact ai-brand-representation-snapshot/v1 contract and validate it through the connected server when that capability exists.

The result must remain valid when:

• all three channels return reports;
• one or more channels return not-recognized;
• one channel fails after planning;
• only one usable report remains;
• no usable report remains;
• the subject must be rejected before spending.

Evidence plan

Declare one required server evidence entry for each channel capability, each scoped to a maximum of one channel observation.

Because the current public recipe schema treats required capability availability as execution readiness, all three capabilities are required at planning time. Each entry must state:

• the recipe cannot begin when the capability is unavailable before execution;
• a later invocation failure is preserved in a contract-valid incomplete result rather than reconstructed through another channel;
• the exact current server result and failure guidance remain authoritative.

Do not introduce a synthetic generic ai-answer-visibility capability or change the recipe resolver to support all_of solely for this recipe.

Ordered steps

Use stable steps equivalent to:

1. settle-brand-framing
2. budget-preflight
3. observe-chatgpt
4. observe-gemini
5. observe-perplexity
6. compare-representation
7. validate-snapshot

The observations may be independent, but the public method must not require parallel execution because approval and client capabilities vary.

Stop conditions

At minimum:

• Stop before paid work when the brand subject is materially ambiguous.
• Stop before execution when current authorization, headroom, or any required channel capability is unavailable.
• Never invent competitors or products to satisfy a minimum.
• Never repeat a valid channel observation to smooth or improve the result.
• Never infer stable model knowledge from one report or not-recognized outcome.
• Never average, normalize, or rank native scores across channels.
• Never present generated source descriptors as verified citations.
• Never make cross-channel report-content claims from fewer than two usable reports.
• Return a contract-valid incomplete result when a planned call fails after execution begins.

Result contract: ai-brand-representation-snapshot/v1

Create a dedicated schema composed with the existing shared evidence envelope.

Required snapshot fields

The contract should require:

• framing
• channel_observations
• comparison
• cost_summary

Framing

Use a closed object containing:

• supplied subject;
• settled brand name or null;
• canonical website or null;
• location or null;
• supplied competitor panel in preserved order;
• supplied products/services in preserved order;
• framing limitations.

Competitor entries should preserve a caller-supplied label and/or URL without requiring the result to invent a label from a hostname.

Channel observations

Require exactly one row for each named channel, enforced through schema plus the smallest generic semantic validator needed for uniqueness and completeness.

Each row must contain:

• channel enum;
• outcome: report, not_recognized, failed, or unavailable;
• recognition status: recognized, not_recognized, or indeterminate as appropriate to the composed observation;
• observed time or null when no invocation occurred;
• evidence IDs;
• categories and optional native scores when a report exists;
• generated topics, associations, source descriptors, and competitors when available;
• quality notes;
• limitations.

The composed contract may use indeterminate for failed/unavailable rows even though the direct tools use only recognized and not_recognized on valid results.

Separate:

• supplied competitor-panel observations;
• generated competitor discoveries;
• supplied product/service framing;
• generated associations.

Do not copy complete raw provider responses into the validated result.

Comparison

Use a closed object containing:

• channels attempted;
• usable report channels;
• comparison completeness;
• supported agreements;
• supported differences;
• excluded comparison claims;
• fixed score-comparison policy.

Do not define any field for a universal or averaged score.

Cost summary

Use a provider-neutral structure containing:

• unit name;
• total quoted amount when known;
• total charged amount;
• one row per channel with quoted and charged amounts when known.

The public schema defines structure only. The connected runtime remains the authority for values and currency/credit semantics.

Completion and disposition

Use the shared envelope consistently:

• proceed: three usable reports and a complete comparison;
• conditional: a useful partial result with material limitations, including valid negative observations or one failed channel;
• defer: insufficient evidence for the requested comparison;
• reject: invalid or unresolved brand framing.

completion.status is complete only when every planned channel produced a valid domain outcome and every required result section is present. A valid not-recognized result counts as a completed channel outcome. A failed or unavailable channel makes completion incomplete.

Required fixtures and semantic validation

Add public-safe deterministic fixtures for:

• three recognized reports;
• two reports plus one not-recognized result;
• one report plus two not-recognized results;
• one failed channel after planning;
• only one usable report;
• no usable reports;
• rejected ambiguous subject;
• controlled competitor panel kept separate from generated competitors;
• supplied products kept separate from generated associations;
• numeric zero preserved;
• missing score represented as absence;
• mixed-language/placeholder quality note;
• valid zero-gap comparison;
• invalid duplicate or missing channel row;
• invalid averaged/universal score field;
• invalid unresolved evidence references.

Use JSON Schema for structure and the existing generic semantic fixture validator for evidence references, IDs, and channel uniqueness where JSON Schema alone is insufficient. Do not create a recipe-specific validation framework.

Agent evaluations

Add fresh-context behavioral cases proving that a capable agent:

• selects the recipe for a multi-channel brand-representation request;
• settles framing before paid evidence;
• discovers current budget instead of quoting public static prices;
• uses all three required channel capabilities once;
• does not pad a two-item competitor list;
• does not rerun a valid negative result;
• does not compare scores across channels;
• distinguishes supplied and generated competitors/products;
• produces a valid incomplete result after a simulated channel failure;
• does not describe the snapshot as buyer-prompt visibility or a trend.

Public guidance

Update only the directly affected public skill and references so agents can distinguish:

• direct one-channel brand analysis;
• the three-channel snapshot recipe;
• future buyer-prompt presence work.

Do not embed the full recipe body in the runtime skill.

Release and review procedure

Follow the repository's current exact-candidate release process.

1. Re-read repository guidance, current catalog/version state, this issue, and the current connected-runtime contract.
2. Create one branch from green main.
3. Implement the taxonomy, capabilities, result schema, recipe, fixtures, semantic checks, guidance, and generated projection.
4. Run focused validation and package checks, then self-review.
5. Prepare the next unused public release only after all source and fixtures are stable.
6. Run one complete public release preflight on the frozen candidate, including deterministic two-build checks, disclosure scans, package verification, and exact-tag installation checks required by current repository policy.
7. Give the exact candidate to three fresh read-only reviewers:
   • methodology, evidence, and claim safety;
   • schema/catalog architecture and public/private boundaries;
   • fixtures, behavioral evaluations, packaging, and release quality.
8. Every blocking finding requires correction, invalidated gates, a new exact candidate, and a new three-reviewer round.
9. Push only the conforming candidate, merge through protection, create the exact immutable tag/release, and verify every published catalog, manifest, skill, and plugin asset.

Acceptance criteria

• The public catalog contains controlled visibility, brand, and channel vocabulary.
• Three explicit channel capabilities exist without private tool bindings or a grouped-capability language.
• ai-brand-representation-snapshot 1.0.0 is the only canonical recipe definition.
• ai-brand-representation-snapshot/v1 validates complete, negative, partial, incomplete, and rejected outcomes.
• The result preserves settled framing, one row per channel, supported comparisons, actual cost structure, limitations, completion, and verification.
• No field or guidance permits a universal score, cross-channel average, buyer-prompt presence claim, or trend claim.
• Required channel planning and post-start failure handling are unambiguous.
• Supplied competitor/product framing remains separate from generated discoveries and associations.
• Fresh agents follow the one-observation, no-padding, no-rerun, and no-score-comparison rules.
• Public source contains no private tool names, provider adapters, current prices, traces, tenant data, or deployment details.
• The exact candidate passes validation, independent reviews, protected merge, deterministic packaging, immutable release, and exact-tag installation verification.

Non-goals

• No private runtime mapping or deployment.
• No direct tool contract correction.
• No buyer-prompt probing.
• No Search Console, crawler-access, page-readiness, citation, or authority audit.
• No persistence, schedules, trends, or dashboards.
• No server-side recipe execution.
• No universal AI visibility score.
• No grouped capability resolver.
• No new generic recipe schema solely for optional inputs.

[sergeliatko]

Cross-repository coordination is tracked in TechSpokes/seo-tools#470. The implementation-readiness gate is satisfied only after the private runtime's direct brand-report family alignment in TechSpokes/seo-tools#471 is merged, deployed, and its current contract is re-inspected. This link is coordination only; no private traces, mappings, prices, or provider details should be copied into this public issue or repository.

[sergeliatko]

Planning correction after cross-repository review. This supersedes the narrower channel-outcome enum and disposition wording in the issue body:

1. channel_observations[].outcome must support not_attempted in addition to report, not_recognized, failed, and unavailable.
   • not_attempted: no call was made because framing was rejected or execution stopped before that channel.
   • unavailable: the required channel capability was not available or authorized at preflight.
   • failed: an attempted invocation did not produce a valid domain outcome.
   • report and not_recognized: valid normally billed domain outcomes.
2. observedAt is required for attempted outcomes (report, not_recognized, failed) and is null for unavailable or not_attempted.
3. Use deterministic disposition semantics:
   • reject: invalid or unresolved framing before paid execution;
   • proceed: all three channel outcomes are reports;
   • conditional: at least two channels produced valid domain outcomes (report or not_recognized), but the snapshot is not a three-report comparison;
   • defer: fewer than two valid domain outcomes remain.
4. completion.status is complete only when all three planned channels produced valid domain outcomes (report or not_recognized); otherwise it is incomplete.
5. Report-content comparison still requires at least two report outcomes. Recognition-status comparison may use valid report and not_recognized outcomes.
6. cost_summary.totalCharged and totalQuoted must reconcile arithmetically with their channel rows. Null quote values are allowed only when no quote was reached. Extend the smallest existing semantic fixture validator needed for these internal totals; do not create a new validation framework.

Include positive and negative fixtures for these rules in the same candidate.

[sergeliatko]

Delivered end to end.

• Protected PR #21 merged at 7ef657dc4c94bd282b06f89dc4d0d746113ea3e6.
• Immutable release v0.5.0 is published from that merge commit.
• Final structural validation passed with 7 recipes, 5 result contracts, 70 contract fixtures, and 40 registered behavioral cases.
• Issue-specific fresh-context behavioral evaluations and all three final exact-candidate reviews passed.
• Deterministic two-build release packaging, exact-tag installation, provenance attestation, public clean installation, and update from the previous release all passed.
• Published catalog, manifest, skill, plugin, and checksum assets matched the locally verified tagged build byte for byte.

No follow-up defect remains in the public issue scope. The private import/deployment dependency has been unblocked and updated in its owning issue.