Skip to content
Brand analysis and audits

Brand analysis and audits

The services behind Brand Analysis: the one-line audit and its stages, the diagnosis, material attached to a new-site audit, content research, market research, Google Search Console, and fixes proposed to the customer’s own website repository. Package pulse.v1; the least role of each method is in its table. See Audit a domain.

Notes

  • One deadline. GenerateDiagnostic and a score-only RunAudit run under one end-to-end budget, PULSE_AUDIT_DEADLINE_SECONDS (170 seconds by default). Each phase gets a budget from what is left; a phase that does not finish is named on the result as not completed within the budget, and the diagnosis is returned as a partial result rather than discarded.
  • Judged output. Diagnostic.channel_prescriptions and brand_visibility hold only proposals the judging ladder kept; judgements lists every verdict.
  • Audit runs. RunAudit runs the stages detached from the call (bounded at 45 minutes), resumes from the first stage not done, reuses a run from the last 24 hours unless force is set, and attaches to a run already in flight. score_only runs just normalize and score on the URL as given; an identical score-only run within PULSE_AUDIT_CACHE_TTL (one hour by default) is reused unless force. Read the report with GetAuditRun (AuditRun.score_report).
  • Stages. stage is a stable identifier: show it as-is or map it to your own labels, but do not rely on the set of stages or their order. A stage that could not run because an earlier one did not finish is skipped, with an error that starts blocked:. queue_position is set while a stage waits for model capacity. The terminal event has an empty stage and the run’s final run_status. With TIDE_HEALTH_URL set, each stage reports to agent health as pulse-audit-<stage>.
  • Stored reads. The market research List* methods (ListDiscoveredChannels, ListTrendingPosts) read what earlier research and audits persisted; they search nothing and spend no model time. Guest spots that research finds are saved as partners (Leads → Partners), scored by topical relevance, never by an audience figure. The service keeps its older proto name.
  • Changing a site. ApplyAuditActions modes other than plan need PULSE_APPLY_ENABLED=true, PULSE_AUDIT_APPLY=true and an admin; every mode needs repo_path inside PULSE_APPLY_ROOT. SiteRepoService.ProposeSiteFix needs the same two switches and an admin, writes only to a new pulse/<run>-<finding> branch and opens a pull request. ConnectSiteRepo and DisconnectSiteRepo also check for an admin, although their table role is editor. See Website repository.
  • Search Console. StartSearchConsoleConnect returns Google’s consent address; Google returns to /oauth/search-console/callback. Without the Google OAuth client or an https PULSE_PUBLIC_BASE_URL the answer says what is not set up. See Google.

DiagnosticService

Multichannel business diagnostic — positioning, SWOT, competitor analysis.

pulse.v1.DiagnosticService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
CreateDiagnosticCreateDiagnosticRequest → DiagnosticeditorCreateDiagnostic creates a new diagnostic record from user-provided business info.
GetDiagnosticGetDiagnosticRequest → DiagnosticviewerGetDiagnostic fetches a single diagnostic by ID.
ListDiagnosticsListDiagnosticsRequest → ListDiagnosticsResponseviewerListDiagnostics returns paginated diagnostics for the current user/org.
GenerateDiagnosticGenerateDiagnosticRequest → stream StreamChunkeditorGenerateDiagnostic streams AI-generated diagnostic analysis in real-time.
UpdateDiagnosticUpdateDiagnosticRequest → DiagnosticeditorUpdateDiagnostic updates a diagnostic’s metadata or user notes.
ExportDiagnosticPDFExportDiagnosticPDFRequest → ExportDiagnosticPDFResponseviewerExportDiagnosticPDF generates a branded PDF export of the diagnostic.
ApplyAuditActionsApplyAuditActionsRequest → ApplyAuditActionsResponseeditorAuditURL was removed: a site score is AuditPipelineService.RunAudit with score_only set, and the report is AuditRun.score_report. ApplyAuditActions audits a URL and maps the auto-applyable fix-artifacts into a server-local repository (stack-aware, idempotent). mode escalates from “plan” (dry-run, default, no side effects) to “apply”/“commit”/“pr”. Copy/infra actions are returned as manual for human review, never applied.

Also uses StreamChunk, PaginationRequest, PaginationResponse, AssistantToolEvent, AssistantProposal, Channel.

// ContentSuggestion is one concrete content idea within a ChannelPrescription.
message ContentSuggestion {
  string title = 1;
  string description = 2;
  string cta = 3;
}

// ChannelPrescription is the AI's structured recommendation for a single
// channel — role in the overall strategy, priority, concrete content ideas,
// preferred CTA style, and the KPIs that matter for it.
message ChannelPrescription {
  Channel channel = 1;
  string role = 2;
  string priority = 3;
  repeated ContentSuggestion suggestions = 4;
  string cta_recommendation = 5;
  repeated string kpis = 6;
  // The judging ladder's verdict on this prescription (cmd/judgement_gate.go).
  // Only concur and unable-to-judge ever appear here: a dissented
  // prescription is withheld and lives only in Diagnostic.judgements.
  // Unset = judging was off (PULSE_JUDGEMENT=off) or it predates the gate.
  runink.ui.judgement.v1.Judgement judgement = 7;
}

// DocumentPrescription is the AI's structured recommendation for a single
// document format — its role, priority, and concrete ideas.
message DocumentPrescription {
  string format = 1;
  string role = 2;
  string priority = 3;
  repeated ContentSuggestion suggestions = 4;
}

// BrandVisibilityInsight is a Generative-Engine-Optimization finding: how to
// shape the brand's lexical/semantic presence so generative-AI metasearch
// engines (AI Overviews, Perplexity, ChatGPT, etc.) recognise, surface, and
// cite the company in context — a distinct insight stream from the
// audience-targeting prescriptions above.
message BrandVisibilityInsight {
  // entity_authority | semantic_topics | answer_framing | lexical_relevance |
  // structured_data | authority_sources
  string dimension = 1;
  string insight = 2;               // what the diagnosis found about current AI-search visibility
  repeated string target_terms = 3; // entities/phrases/queries to own for AI-search lexical relevance
  repeated string actions = 4;      // concrete actions to raise generative-AI discoverability
  string rationale = 5;             // why this shapes brand awareness in AI/metasearch engines
  // The judging ladder's verdict on this insight; see ChannelPrescription.judgement.
  runink.ui.judgement.v1.Judgement judgement = 6;
}

// AudienceSegment is one tier of a 360-degree audience map (e.g. decision
// makers, influencers, end users), with the areas/roles/technologies that
// define it.
message AudienceSegment {
  string level = 1;
  repeated string areas = 2;
  repeated string roles = 3;
  repeated string technologies = 4;
}

// CronogramTask is one task in the multichannel execution calendar.
message CronogramTask {
  int32 week = 1;
  Channel channel = 2;
  string task = 3;
  bool completed = 4;
}

// Diagnostic is a full multichannel business diagnostic report.
message Diagnostic {
  string id = 1;
  string user_id = 2;
  string business_name = 3;
  string industry = 4;
  string niche = 5;
  string target_audience = 6;
  string current_channels = 7;      // comma-separated active channels
  string competitors = 8;           // comma-separated competitor names
  string business_description = 9;  // user's free-form business description
  string website_url = 10;
  string positioning_analysis = 11;
  string swot_analysis = 12;
  string channel_recommendations = 13;
  string content_strategy = 14;
  string competitive_landscape = 15;
  string ai_opinion = 16;           // strategic opinion from the AI market-analyst
  string status = 17;               // "pending", "generating", "completed", "error"
  map<string, string> metadata = 18;
  google.protobuf.Timestamp created_at = 19;
  google.protobuf.Timestamp updated_at = 20;
  // Structured breakdown of channel_recommendations/content_strategy above,
  // parsed via a schema-constrained LLM call (see GenerateStructured in
  // cmd/model_server.go) instead of left as free text for the client to
  // guess at. Populated by GenerateDiagnostic; empty on a freshly-created,
  // not-yet-generated Diagnostic.
  repeated ChannelPrescription channel_prescriptions = 21;
  repeated AudienceSegment audience_segments = 22;
  repeated CronogramTask cronogram = 23;
  // URLs/titles of the real sources (site, LinkedIn, web search results)
  // the AI actually grounded this diagnostic in — see internal/metasearch.
  repeated string sources_used = 24;
  // Real, backend-verified actions taken during generation (e.g. "Scraped
  // live content from acme.com"), same convention as StreamChunk.agent_tasks
  // — streamed live during GenerateDiagnostic and persisted here so the
  // trace survives after generation finishes, not just visible mid-stream.
  repeated string agent_tasks = 25;
  // User's selected goals for the diagnostic
  repeated string goals = 26;
  repeated DocumentPrescription document_prescriptions = 27;
  // Generative-Engine-Optimization insights — how to shape brand awareness /
  // discoverability in AI metasearch engines via lexical relevance, split out
  // from the audience-targeting prescriptions above.
  repeated BrandVisibilityInsight brand_visibility = 28;
  // Every verdict the judging ladder reached on this diagnostic's proposals
  // (channel prescriptions + brand-visibility insights), accepted AND
  // rejected, with the ladder's own counts. A dissented proposal appears
  // ONLY here (accepted=false), never in the lists above. Kept in PULSE's own
  // store with the structured analysis. Unset = not judged.
  runink.ui.judgement.v1.JudgementSet judgements = 29;
}

message CreateDiagnosticRequest {
  string business_name = 1;
  string industry = 2;
  string niche = 3;
  string target_audience = 4;
  string current_channels = 5;
  string competitors = 6;
  string business_description = 7;
  string website_url = 8;
  repeated string goals = 9;
}

message GetDiagnosticRequest {
  string id = 1;
}

message ListDiagnosticsRequest {
  PaginationRequest pagination = 1;
}

message ListDiagnosticsResponse {
  repeated Diagnostic diagnostics = 1;
  PaginationResponse pagination = 2;
}

message GenerateDiagnosticRequest {
  string diagnostic_id = 1; // ID of the pre-created diagnostic to populate
}

message UpdateDiagnosticRequest {
  string id = 1;
  string business_name = 2;
  string industry = 3;
  string niche = 4;
  string target_audience = 5;
  string current_channels = 6;
  string competitors = 7;
  string business_description = 8;
  string website_url = 9;
  map<string, string> metadata = 10;
}

message ExportDiagnosticPDFRequest {
  string diagnostic_id = 1;
}

message ExportDiagnosticPDFResponse {
  bytes pdf_data = 1;
  string filename = 2;
  // The same PDF at a signed, expiring /media URL (the media vault), for a
  // native app: Android cannot save bytes where the person can open them, so
  // it hands this to the system browser, which downloads it. Empty when the
  // media vault is unavailable; the bytes are always set.
  string download_url = 3;
}

// ApplyAuditActionsRequest audits url and applies auto-fixable actions to the
// repo at repo_path. mode ∈ {plan,apply,commit,pr}; empty = plan (dry-run).
message ApplyAuditActionsRequest {
  string url = 1;
  string repo_path = 2;
  string profile = 3;
  string mode = 4;   // plan|apply|commit|pr
  string branch = 5; // default: seo/pulse-remediation
  string base = 6;   // default: main
}

// ApplyAuditActionsResponse reports the detected stack, the planned/applied file
// changes, the manual (copy/infra) actions left for review, and the git result.
message ApplyAuditActionsResponse {
  string stack = 1;
  double overall_score = 2;
  repeated PlannedChange changes = 3;
  repeated AuditAction manual = 4;
  ApplyGitResult git = 5;
  string pr_body = 6;
}

// PlannedChange is one file the agent would create/modify/skip.
message PlannedChange {
  string path = 1;
  string op = 2; // create|modify|skip
  string check_id = 3;
  string reason = 4;
}

// ApplyGitResult reports how far the git/PR step got, with manual instructions
// when credentials or gh are unavailable.
message ApplyGitResult {
  string branch = 1;
  bool committed = 2;
  bool pushed = 3;
  string pr_url = 4;
  string instructions = 5;
}

// AuditAction is a concrete remediation fix-artifact for a check: the actual
// content to apply (robots.txt, canonical tag, JSON-LD block, rewritten title,
// header config) plus where it goes and whether it's safe to auto-apply.
message AuditAction {
  string check_id = 1;
  string title = 2;
  string rationale = 3;
  string severity = 4;     // critical|high|medium|low
  string type = 5;         // file_create|head_insert|content_edit|header_config|manual
  string target_hint = 6;
  string artifact = 7;     // the concrete content/snippet to apply
  string confidence = 8;   // high|medium|low
  bool auto_apply = 9;
  double impact = 10;
}

AuditPipelineService

The one-phrase audit pipeline (“Audit example.com”): the user types a domain and every PULSE page is populated by inference — crawl, site score, trend slice, the diagnosis, the deterministic fan-out (campaign, approval drafts, follow-up cycle, schedule, creatives, course, persona, radar summary), then radar research and leads. Every stage is tracked (audit_runs / audit_stages), owner scoped, and reported honestly: a stage is done only when it wrote at least one row or recorded “0 found” from a source that actually answered. A run whose required stage failed ends partial or failed, never completed.

pulse.v1.AuditPipelineService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
RunAuditRunAuditRequest → stream AuditProgresseditorRunAudit starts (or attaches to, or resumes) the caller’s audit of a domain and streams stage progress until the run ends. A second call for the same (caller, domain) while a run is active attaches to it; a call after a failed/partial run resumes from the first stage that is not done; a call within 24h of a completed run returns that run unless force is set. A score_only call is its own run: it never attaches to or replays a full audit (nor a full audit to it); see RunAuditRequest.score_only.
GetAuditRunGetAuditRunRequest → AuditRunviewer
ListAuditRunsListAuditRunsRequest → ListAuditRunsResponseviewer
GetAuditAiVisibilityGetAuditAiVisibilityRequest → AuditAiVisibilityviewerGetAuditAiVisibility returns what a run’s genai_visibility stage measured, finding by finding, with the evidence for each.
GetAuditFindingsGetAuditFindingsRequest → AuditFindingsviewerGetAuditFindings returns what a run found for the business: leads with their contacts, possible competitors, where it wins and loses against each, niches worth exploring and partners with their contacts. Each kind says whether it was found, found nothing, or was not measured.
DeleteAuditRunsDeleteAuditRunsRequest → DeleteAuditRunsResponseeditorDeleteAuditRuns deletes some of the caller’s full audit runs, or every run of one domain but the newest (all_but_latest, with the domain typed back as confirm). Removed: each run, its stages, its findings, its AI-visibility rows and its content-gaps snapshot unless a campaign plan uses it. Kept: leads, campaigns, drafts, the diagnosis and the site-score history. A run still in flight is refused, never deleted.
GetAuditAudienceGetAuditAudienceRequest → AuditAudienceviewerGetAuditAudience returns who a run found the business sells to and what it sells (the research inputs it saved), each with where it came from.

Also uses AuditAction.

// AuditReport is the full audit result: the output contract of the scoring
// engine. overall_score is the weighted mean of composites; benchmark_mode is
// "relative" or "absolute"; skipped_data_sources lists adapters the user could
// configure to raise coverage.
message AuditReport {
  string url = 1;
  google.protobuf.Timestamp audited_at = 2;
  double overall_score = 3;
  repeated AuditComposite composites = 4;
  repeated string skipped_data_sources = 5;
  string benchmark_mode = 6;
  repeated AuditRecommendation recommendations = 7;
  repeated AuditAction actions = 8;
}

// AuditComposite is one of the four scored dimensions. coverage is the fraction
// (0-1) of the composite's weight that was actually scored — a 90 at 0.4
// coverage is very different from a 90 at 1.0.
message AuditComposite {
  string id = 1;
  string label = 2;
  double score = 3;
  double weight = 4;    // normalized 0-1
  double coverage = 5;  // 0-1
  repeated AuditSignal signals = 6;
}

// AuditSignal is a scored signal within a composite.
message AuditSignal {
  string id = 1;
  double score = 2;
  double weight = 3;    // normalized 0-1 within its composite
  double coverage = 4;  // 0-1
  repeated AuditCheck checks = 5;
}

// AuditCheck is a single check's outcome. status is "scored" | "skipped" |
// "error"; mode is "relative" | "absolute" for benchmark checks (else empty).
message AuditCheck {
  string id = 1;
  double score = 2;
  string status = 3;
  string raw_value = 4;
  string notes = 5;
  string mode = 6;
}

// AuditRecommendation is a lowest-scoring check surfaced by global weighted
// impact (check_weight × signal_weight × composite_weight), so the biggest
// wins bubble up.
message AuditRecommendation {
  string check_id = 1;
  double score = 2;
  double impact = 3;
  string notes = 4;
}

message RunAuditRequest {
  string domain = 1; // "example.com", "https://example.com/…" — normalised server-side
  bool force = 2;    // start a fresh run even when a completed one is < 24h old
  // What the person told the audit about the business. Any field set starts a
  // fresh run built on it; a niche, industry or business name lets the
  // research stages start without waiting for the model to infer one.
  AuditTuning tuning = 3;
  // score_only runs only normalize + score, on the URL exactly as given, as a
  // tracked run of its own (not listed by ListAuditRuns). It attaches only to
  // an identical score_only run in flight and is never replayed from a stored
  // run. A score computed by an earlier score_only call with the same inputs
  // within PULSE_AUDIT_CACHE_TTL is reused unless force is set.
  bool score_only = 4;
  // Weighting profile (e.g. "ai-focused"), empty = default. score_only only.
  string scoring_profile = 5;
  // 2-3 competitor URLs switch the benchmark-dependent checks to relative
  // mode. score_only only.
  repeated string competitor_urls = 6;
}

// The new-audit form's details. Every field is optional.
message AuditTuning {
  string business_name = 1;
  string industry = 2;
  string niche = 3;
  string target_audience = 4;
  string competitors = 5;          // free text: names or URLs, comma separated
  string business_description = 6; // "What do you sell?" plus any extra context
  repeated string goals = 7;
  string linkedin_url = 8;
  string instagram_handle = 9;
  // Material uploaded through AuditAttachmentService (photos, a short video,
  // product documents, voice notes) the audit compares the brand against.
  // Owner scoped: an id that is not the caller's is refused.
  repeated string attachment_ids = 10;
  // "Where are most of your customers?" — asked only when the site did not
  // state it; used as the region only when no check on the site measures one.
  string customer_region = 11;
}

// AuditProvenance says where a stage's output came from: "sourced" (read from
// the web), "inferred" (the model's reasoning over sourced input), or "mixed".
message AuditProvenance {
  string kind = 1;                 // sourced | inferred | mixed | none
  repeated string source_urls = 2; // bounded; the pages the stage actually read
  string basis = 3;                // one line: what the inference rests on
}

// AuditProgress is one event of a run. A stage event has stage set; the run's
// terminal event has stage == "" and run_status set to its final value.
message AuditProgress {
  string run_id = 1;
  string stage = 2;   // normalize, crawl, score, trends, diagnosis, fanout_*, niche, radar_*, leads
  string status = 3;  // pending | running | done | failed | skipped
  string detail = 4;
  map<string, int32> counts = 5;
  string error = 6;   // set whenever status is failed (and on a failed/partial terminal event)
  AuditProvenance provenance_summary = 7;
  int32 queue_position = 8; // >0 while this stage waits for the model lane
  string run_status = 9;    // running | completed | partial | failed
  string domain = 10;
  string diagnostic_id = 11;
  bool attached = 12;       // this stream joined a run another call started
  int32 attempt = 13;
}

message AuditStage {
  string stage = 1;
  string status = 2;
  int32 attempt = 3;
  map<string, int32> counts = 4;
  string error = 5;
  string detail = 6;
  google.protobuf.Timestamp started_at = 7;
  google.protobuf.Timestamp finished_at = 8;
  // Not applicable to this run (an optional stage skipped for a reason that
  // is not a failure, e.g. no material was attached): neither finished nor
  // unfinished, and not counted in "N of M parts".
  bool not_applicable = 9;
}

message AuditRun {
  string id = 1;
  string domain = 2;
  string diagnostic_id = 3;
  string status = 4; // running | completed | partial | failed
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp finished_at = 6;
  repeated AuditStage stages = 7;
  // The site score the run's score stage saved; unset when it saved none.
  AuditReport score_report = 8;
  bool score_only = 9;
}

message GetAuditRunRequest {
  string run_id = 1;
}

message ListAuditRunsRequest {
  int32 limit = 1;   // default 20, max 100
  string domain = 2; // optional filter
}

message ListAuditRunsResponse {
  repeated AuditRun runs = 1;
}

message GetAuditAiVisibilityRequest {
  string run_id = 1;
}

// One AI-access requirement read from the site itself.
message AiAccessCheck {
  string kind = 1;         // crawler | llms_txt | server_rendered | structured_data
  string item = 2;         // the crawler's name, or the file / page checked
  string state = 3;        // pass | fail | not_measured
  string evidence = 4;     // the line that decided it
  string evidence_url = 5;
  // The site-score check whose fix-artifact (in the score report's actions,
  // applied through ApplyAuditActions) fixes a failure; "" when none does.
  string fix_check_id = 6;
}

// One buyer question read on a search engine's own result page.
message AiAnswerCheck {
  string question = 1;
  string basis = 2;        // what the question was derived from
  string engine = 3;       // the engine whose page was read
  string serp_url = 4;     // that page
  // cited | not_cited | no_ai_answer | not_measured. not_measured is never
  // counted as not cited.
  string state = 5;
  string why = 6;          // set when not_measured
  repeated string sources = 7;          // the AI answer's cited links
  repeated string competitors_cited = 8; // cited hosts matching a named competitor
  repeated string other_cited = 9;       // every other cited host
  int32 organic_rank = 10;  // the brand's position among organic results; 0 = not among them
  int32 organic_count = 11; // organic results on the page as loaded; 0 = page not read
}

message AuditAiVisibility {
  string run_id = 1;
  string domain = 2;
  bool measured = 3;       // false: the stage stored nothing (absent, not empty)
  repeated AiAccessCheck access = 4;
  repeated AiAnswerCheck answers = 5;
  string engines_covered = 6;  // e.g. "DuckDuckGo"
  string not_covered = 7;      // what this measurement does not read
}

message GetAuditFindingsRequest {
  string run_id = 1; // "" = the caller's latest full audit
}

// FindingContact is what a page publishes about how to reach someone.
message FindingContact {
  string email = 1;
  string phone = 2;
  string website = 3;
  string linkedin = 4;
}

message AuditFinding {
  string kind = 1;        // lead | competitor | advantage | niche | partner
  string title = 2;       // the company, competitor, niche or partner
  string detail = 3;      // why, in plain words
  string source_url = 4;  // where it was found or measured
  string basis = 5;       // measured | named (by the owner) | judged (model proposal the plan gate kept)
  FindingContact contact = 6;
  repeated string wins = 7;   // advantage: checks this business meets and the competitor does not
  repeated string losses = 8; // advantage: checks the competitor meets and this business does not
  string lead_id = 9;         // lead: its row on the Leads page
  string judgement = 10;      // judged: the plan gate's verdict
  bool measured = 11;         // false = this item could not be measured (detail says why)
  string id = 12;             // the finding's own id (a partner's automation target id)
}

// AuditFindingKind is one kind's state for the run.
message AuditFindingKind {
  string kind = 1;
  string state = 2;  // found | none_found | not_measured
  string why = 3;    // none_found / not_measured: the stage's own reason
  string stage = 4;  // the stage that produced it
}

message AuditFindings {
  string run_id = 1;
  string domain = 2;
  repeated AuditFinding findings = 3;
  repeated AuditFindingKind kinds = 4;
}

message DeleteAuditRunsRequest {
  repeated string run_ids = 1;  // the caller's runs to delete
  // Delete every run of domain except its newest; confirm must equal the
  // domain as ListAuditRuns returns it (the typed confirmation).
  bool all_but_latest = 2;
  string domain = 3;
  string confirm = 4;
  // With all_but_latest: delete the newest run too.
  bool include_latest = 5;
  // START OVER (Settings › Account, Brand Analysis history): every run of the
  // caller (this account or agency client only) AND what the runs produced —
  // stages, findings, AI-visibility rows, site scores, insight snapshots
  // (content gaps, scenarios), every diagnosis, follow-up cycles with their
  // tasks and check-ins, market research (summaries, channels, trending posts,
  // imported partners), campaign proposals never accepted with their
  // campaigns, drafts never approved with their scheduled rows, creative
  // briefs and course outlines the audits made, and the leads they found.
  // confirm must equal domain, a domain the caller audited. Refused while any
  // of the caller's audits is running. Never deleted: anything published,
  // measured results (post_results), integrations, leads added by hand,
  // imported or won.
  bool start_over = 6;
  // Start over also deletes accepted campaigns (with their plans and roadmap).
  bool also_accepted_campaigns = 7;
  // No longer read: start over always deletes the leads audits found
  // (source "scraped" or linked from a finding) unless won (owner, 2026-10-30).
  bool also_audit_leads = 8;
  // Start over also deletes approved or scheduled items not sent yet.
  bool also_approved_unsent = 9;
  // Count what would go, delete nothing (the dialog's preview).
  bool dry_run = 10;
}

// What DeleteAuditRuns removed, row by row.
message DeleteAuditRunsResponse {
  repeated string deleted_run_ids = 1;
  int32 stages = 2;
  int32 findings = 3;
  int32 ai_visibility = 4;
  int32 snapshots = 5;
  // Runs still in flight: never deleted.
  repeated string refused_run_ids = 6;
  // Start over only (0 for a plain delete).
  int32 campaign_plans = 7;
  int32 campaigns = 8;
  int32 drafts = 9;          // content rows never approved
  int32 approved_unsent = 10; // approved or scheduled, not sent (only when asked)
  int32 scheduled_posts = 11; // pending scheduled posts removed with them
  int32 leads = 12;          // only when asked
  int32 roadmap_items = 13;
  int32 planner_tasks = 14;
  int32 diagnostics = 15;
  int32 competitor_channels = 16;
  // Published items kept (never deleted), for the dialog's summary.
  int32 kept_published = 17;
  bool dry_run = 18;
  // Start over refused: an audit is running (its run id).
  string refused_running = 19;
  int32 trending_posts = 20;   // trending posts the research saved for the runs' niches
  // Start over (owner, 2026-10-30: "clear everything the audits produced").
  int32 cycles = 21;            // follow-up cycles the audits made, with their tasks
  int32 check_ins = 22;         // the weekly check-ins of those cycles
  int32 creatives = 23;         // creative briefs the audits made
  int32 courses = 24;           // course outlines the audits made
  int32 market_summaries = 25;  // radar summaries
  int32 partners = 26;          // partners imported from the research (hand-added ones stay)
  int32 site_scores = 27;       // site scores the runs saved
  // What stays, for the dialog: leads added by hand, imported or won;
  // accepted campaigns (only when the person keeps them); connected accounts.
  int32 kept_leads = 28;
  int32 kept_campaigns = 29;
  int32 kept_integrations = 30;
}

message GetAuditAudienceRequest {
  string run_id = 1;
}

// One group of people the business sells to, as the run found them.
message AudiencePersona {
  string name = 1;
  string source = 2;   // tuning | owner | leads | audience
  string evidence = 3; // the line it was drawn from ("" when none was kept)
}

// One thing the business sells, in the site's own words when read there.
message AudienceOffering {
  string name = 1;
  string quote = 2;      // the site's words ("" when the owner typed it)
  string source = 3;     // site | tuning
  string source_url = 4; // the page read ("" for the owner's own words)
}

message AuditAudience {
  string run_id = 1;
  string domain = 2;
  // false: the run saved no audience (absent, not empty).
  bool measured = 3;
  repeated AudiencePersona personas = 4;
  repeated AudienceOffering offerings = 5;
  repeated string problems = 6; // the problems the research found for them
}

AuditAttachmentService

The material a person gives the new-site audit besides text: photos or a short video of the store or product, product documents (PDF, DOCX, TXT, MD) and voice notes. PULSE audits the brand AGAINST that material: does the site say what the documents and photos show, what is inconsistent, which benefits are not communicated.

UPLOAD IS CHUNKED OVER UNARY RPCS (Begin → Chunk… → Finish) because the web client speaks gRPC-Web, which has no client streaming. Every call is owner scoped: an upload or attachment of another user is NOT_FOUND. Bytes are sealed in PULSE’s appfs root the moment Finish accepts them; nothing is ever written to disk in plaintext. Pass the returned ids in AuditTuning.attachment_ids; an attachment used by a run lives as long as that run, one never used expires (expires_at).

pulse.v1.AuditAttachmentService, declared in attachments.proto.

MethodRequest → ResponseLeast roleNotes
GetAttachmentLimitsGetAttachmentLimitsRequest → AttachmentLimitsviewerWhat this instance accepts and can understand. Read it before showing the pickers: an instance without a vision tier still accepts photos but says up front that it cannot look at them.
BeginAttachmentUploadBeginAttachmentUploadRequest → BeginAttachmentUploadResponseeditorDeclares a file. Refused (INVALID_ARGUMENT, with a sentence the UI can show) when its type is not accepted or its declared size is over the cap.
UploadAttachmentChunkUploadAttachmentChunkRequest → UploadAttachmentChunkResponseeditorAppends one chunk at offset (must equal the bytes received so far; a retried chunk at an already-received offset is acknowledged, not duplicated). At most max_chunk_bytes per call.
FinishAttachmentUploadFinishAttachmentUploadRequest → AuditAttachmenteditorChecks the received bytes (size, sha256 when given, real file type, pages/duration caps), seals them and returns the attachment. Extraction then runs in the background: poll GetAttachment until status is not PROCESSING. Documents are usually READY on return.
GetAttachmentGetAttachmentRequest → AuditAttachmentviewer
ListAttachmentsListAttachmentsRequest → ListAttachmentsResponseviewer
DeleteAttachmentDeleteAttachmentRequest → DeleteAttachmentResponseeditorRemoves the sealed bytes and the extracted text. Idempotent.
enum AttachmentKind {
  ATTACHMENT_KIND_UNSPECIFIED = 0;
  ATTACHMENT_KIND_IMAGE = 1;    // jpeg, png, webp
  ATTACHMENT_KIND_VIDEO = 2;    // mp4, webm (short)
  ATTACHMENT_KIND_DOCUMENT = 3; // pdf, docx, txt, md
  ATTACHMENT_KIND_AUDIO = 4;    // a voice note: wav, webm/ogg opus, m4a, mp3
}

enum AttachmentStatus {
  ATTACHMENT_STATUS_UNSPECIFIED = 0;
  ATTACHMENT_STATUS_PROCESSING = 1; // sealed; extraction still running
  ATTACHMENT_STATUS_READY = 2;      // done; see analysis for what was obtained
  ATTACHMENT_STATUS_FAILED = 3;     // stored, but nothing could be read (see detail)
}

// What PULSE could actually get out of the file. Three of these are honest
// "could not" states, never a guess: an image with no vision tier is
// IMAGE_UNDERSTANDING_UNAVAILABLE, not a text model's description of a
// filename.
enum AttachmentAnalysis {
  ATTACHMENT_ANALYSIS_UNSPECIFIED = 0;
  ATTACHMENT_ANALYSIS_PENDING = 1;
  ATTACHMENT_ANALYSIS_TEXT_EXTRACTED = 2;   // document text read
  ATTACHMENT_ANALYSIS_NO_TEXT_FOUND = 3;    // read fine, but no text in it (e.g. a scanned PDF)
  ATTACHMENT_ANALYSIS_IMAGE_DESCRIBED = 4;  // the vision tier described it (video: its frames)
  ATTACHMENT_ANALYSIS_IMAGE_UNDERSTANDING_UNAVAILABLE = 5; // no vision tier on this instance, or it did not answer
  ATTACHMENT_ANALYSIS_FRAMES_NOT_ANALYSED = 6;  // video stored; frames could not be sampled
  ATTACHMENT_ANALYSIS_TRANSCRIBED = 7;      // voice note transcribed (Voxtral)
  ATTACHMENT_ANALYSIS_TRANSCRIPTION_UNAVAILABLE = 8; // no voice tier, or it did not answer
  ATTACHMENT_ANALYSIS_FAILED = 9;           // the file could not be parsed
}

message GetAttachmentLimitsRequest {}

message AttachmentTypeLimit {
  AttachmentKind kind = 1;
  repeated string content_types = 2; // accepted MIME types
  repeated string extensions = 3;    // accepted extensions, lower case, no dot
  int64 max_bytes = 4;
  int32 max_duration_seconds = 5;    // video/audio; 0 = not applicable
  int32 max_pages = 6;               // documents; 0 = not applicable
}

message AttachmentLimits {
  repeated AttachmentTypeLimit types = 1;
  int32 max_attachments_per_audit = 2;
  int32 max_chunk_bytes = 3;
  // Whether the instance can look inside the material, decided from its
  // configuration (a vision tier, a voice tier, a frame sampler). False is
  // shown to the person before they upload.
  bool image_understanding_available = 4;
  bool transcription_available = 5;
  bool video_frames_available = 6;
  int32 unused_retention_hours = 7; // an attachment no run used is removed after this
}

message BeginAttachmentUploadRequest {
  string filename = 1;     // shown back and cited in findings; path parts are dropped
  string content_type = 2; // as the picker reports it; the bytes are checked at Finish
  int64 size_bytes = 3;    // declared total size; Finish refuses a different count
}

message BeginAttachmentUploadResponse {
  string upload_id = 1;
  AttachmentKind kind = 2;
  int32 max_chunk_bytes = 3;
  google.protobuf.Timestamp expires_at = 4; // an unfinished upload is dropped after this
}

message UploadAttachmentChunkRequest {
  string upload_id = 1;
  int64 offset = 2;
  bytes data = 3;
}

message UploadAttachmentChunkResponse {
  int64 received_bytes = 1;
}

message FinishAttachmentUploadRequest {
  string upload_id = 1;
  string sha256_hex = 2; // optional; checked when set
}

message AuditAttachment {
  string id = 1;
  string filename = 2;
  string content_type = 3; // as detected from the bytes
  AttachmentKind kind = 4;
  int64 size_bytes = 5;
  AttachmentStatus status = 6;
  AttachmentAnalysis analysis = 7;
  string detail = 8;          // one sentence for the person: what was read, or why not
  string summary = 9;         // first part of what was extracted/described (bounded)
  int32 extracted_chars = 10; // size of the full extracted text the audit can use
  int32 page_count = 11;      // documents; 0 = unknown
  int32 duration_seconds = 12; // video/audio; 0 = unknown
  int32 frames_analysed = 13; // video
  string audit_run_id = 14;   // the run that used it; "" = not used yet
  google.protobuf.Timestamp created_at = 15;
  google.protobuf.Timestamp expires_at = 16; // unset once a run uses it
  // What the audit run (audit_run_id) found comparing the site with this
  // material, each judged by the plan gate. Empty until that run's diagnosis.
  repeated AttachmentFinding findings = 17;
}

// One brand-vs-material finding drawn from an attachment.
message AttachmentFinding {
  string type = 1;      // gap | inconsistency | uncommunicated_benefit | confirmed
  string finding = 2;   // one sentence
  string action = 3;    // what to change on the site or in marketing
  string judgement = 4; // the plan gate's verdict text; "" = not judged (PULSE_JUDGEMENT=off)
}

message GetAttachmentRequest {
  string attachment_id = 1;
}

message ListAttachmentsRequest {
  string audit_run_id = 1; // optional: only those a run used
}

message ListAttachmentsResponse {
  repeated AuditAttachment attachments = 1;
}

message DeleteAttachmentRequest {
  string attachment_id = 1;
}

message DeleteAttachmentResponse {
  bool deleted = 1; // false when there was nothing to delete
}

SitePreviewService

What the new-audit wizard can show the person before they type anything: the site’s own name and description, and the social profiles it links to. One page read, no model call, no write. Everything returned is what the page itself says, so the wizard can ask “is this right?” instead of showing empty fields.

pulse.v1.SitePreviewService, declared in site_preview.proto.

MethodRequest → ResponseLeast roleNotes
PreviewSitePreviewSiteRequest → SitePreviewviewer
message PreviewSiteRequest {
  string url = 1; // "bakery.com" or a full URL; normalised server-side
}

// A social profile the page links to.
message SiteProfile {
  string network = 1; // instagram | facebook | linkedin | tiktok | youtube | x | pinterest
  string url = 2;
  string handle = 3;  // "@name" when the link names one; "" otherwise
}

message SitePreview {
  string url = 1;    // the page that was read
  // False: the page could not be read (why says so). Not an empty site.
  bool read = 2;
  string why = 3;
  string name = 4;        // og:site_name, else <title>; "" when the page has neither
  string description = 5; // meta description, else og:description; "" when absent
  repeated SiteProfile profiles = 6;
  // Where the business's customers are, as the page itself states it
  // (cmd/region.go); "" = not measured. region_source names the check.
  string region = 7;
  string region_source = 8;
}

ContentResearchService

ContentResearchService — the audit’s deep content research (release 5). From what an audit MEASURED (the site’s own text and what it sells, the niche, trending posts, competitor channels, trend searches, leads and the people the business sells to), PULSE fans out scenarios: one person × one problem they have × one angle × the channel formats it suits, each with 3-5 post ideas, the findings that back it and a research pass through PULSE’s own crawler. Every scenario is one content-skill run on PULSE’s own inference (OpenBias, Go checks, plan gate); a withheld one is listed with the reason. Nothing here publishes.

pulse.v1.ContentResearchService, declared in content_scenarios.proto.

MethodRequest → ResponseLeast roleNotes
ListContentScenariosListContentScenariosRequest → ListContentScenariosResponseviewerListContentScenarios returns the scenarios of a run ("" = the caller’s latest run that has them), best first, withheld ones last. No model call.
GetResearchTuningGetResearchTuningRequest → ResearchTuningviewerGetResearchTuning returns what the caller saved, and what the latest audit found to seed it with (people it sells to, what it sells).
SaveResearchTuningSaveResearchTuningRequest → ResearchTuningeditorSaveResearchTuning stores the caller’s tuning (per account; an agency client is its own account). The next audit and every re-tune use it.
RetuneContentScenariosRetuneContentScenariosRequest → RetuneContentScenariosResponseeditorRetuneContentScenarios re-runs the scenarios of a finished run with the saved tuning, detached; ListContentScenarios shows the result.
// One post idea of a scenario.
message ScenarioItem {
  string hook = 1;    // the first line people see
  string format = 2;  // instagram_feed | instagram_carousel | instagram_reel | instagram_story | youtube_long | youtube_shorts
  string cta = 3;     // what the post asks people to do, in plain words
  string why = 4;     // why it matters to this person
  string channel = 5; // instagram | youtube
}

// One finding a scenario is drawn from.
message ScenarioEvidence {
  string ref = 1;        // "E3"
  string kind = 2;       // site | offering | niche | trend | trending_post | competitor_channel | lead | persona | gap
  string text = 3;
  string source_url = 4; // "" when the finding has no page of its own
}

// One scenario. Contract with the campaign plan generator (Agent D): it reads
// the kept scenarios (withheld = false) and their items when present.
message ContentScenario {
  string id = 1;
  string audit_run_id = 2;
  string persona = 3;   // who it is for (from the tuning, the audit's leads or its audience)
  string pain = 4;      // the problem or job that person has
  string angle = 5;     // educate | proof | behind_the_scenes | offer | event
  string offering = 6;  // what the business sells that it serves (stated on the site or by the owner)
  repeated string channel_formats = 7;
  repeated string evidence_refs = 8; // refs into evidence
  double score = 9;     // 0-100: evidence strength and fit; ranks the list
  bool withheld = 10;
  string withheld_reason = 11;
  repeated ScenarioItem items = 12;
  repeated ScenarioEvidence evidence = 13;
  // How the score was reached, in plain words ("3 findings, 2 measured; …").
  string score_basis = 14;
  // The plan gate's verdict: concur | unable | off ("" when withheld before it).
  string verdict = 15;
  // persona_source: tuning | leads | audience. offering_source: tuning | site.
  string persona_source = 16;
  string offering_source = 17;
  // What PULSE's own web research found for it ("" = none ran or none found).
  string research_note = 18;
  // The Go checks' summary ("scenario-items 100/pass").
  repeated string checks = 19;
}

// One day of the Instagram week (daily posting across several scenarios):
// no topic twice in a row, at most one offer post in any four.
message RotationSlot {
  int32 day = 1;          // 1..7
  string scenario_id = 2;
  int32 item_index = 3;   // into that scenario's items
  string format = 4;
  string angle = 5;
  string topic = 6;       // the scenario's pain, for the rotation rule
  bool promo = 7;         // angle == offer
}

message ListContentScenariosRequest {
  string audit_run_id = 1; // "" = the latest run with scenarios
}

message ListContentScenariosResponse {
  string audit_run_id = 1;
  string domain = 2;
  // The run's content_scenarios stage: pending | running | done | failed |
  // skipped ("" = no run), and its detail or error.
  string stage_status = 3;
  string stage_detail = 4;
  repeated ContentScenario scenarios = 5;
  // Derived from the measured inputs; run inside the time budget; not run
  // because the budget could not pay for them (they are listed withheld).
  int32 derived = 6;
  int32 dispatched = 7;
  int32 capped = 8;
  string depth = 9;  // quick | deep
  repeated RotationSlot instagram_rotation = 10;
  string generated_at = 11; // RFC 3339; "" = none yet
  // The tuning the scenarios were built with.
  ResearchTuning tuning = 12;
  // Why there is no Instagram week ("" = there is one).
  string rotation_note = 13;
  // The hash-chain head over every scenario's outcome (runi/chain).
  string trace_head = 14;
}

// What the person tunes the research with. Lists are plain words; an empty
// list or a 0 count means "not set", never "none".
message ResearchTuning {
  string goal = 1;
  repeated string personas = 2;   // who they sell to
  repeated string offerings = 3;  // what they sell
  repeated string channels = 4;   // instagram | youtube
  int32 posts_per_week = 5;       // 0 = not set
  int32 stories_per_day = 6;      // 0 = not set
  repeated string focus_topics = 7;
  repeated string avoid_topics = 8;
  string language = 9;
  string region = 10;
  string depth = 11;              // quick | deep ("" = quick)
  string updated_at = 12;         // "" = never saved
  bool saved = 13;                // false: nothing saved yet (the seeds below still apply)
  // What the latest audit found, offered as chips: never saved by itself.
  repeated string seeded_personas = 14;
  repeated string seeded_offerings = 15;
  // The expertise Leads › Freelance searches with. Empty = PULSE infers it
  // from the audit (seeded_expertise); saved = exactly these terms.
  repeated string expertise = 16;
  // What the latest audit inferred, offered as chips: never saved by itself.
  repeated string seeded_expertise = 17;
}

message GetResearchTuningRequest {}

message SaveResearchTuningRequest {
  ResearchTuning tuning = 1;
}

message RetuneContentScenariosRequest {
  string audit_run_id = 1; // "" = the latest run
}

message RetuneContentScenariosResponse {
  string audit_run_id = 1;
  string status = 2; // started | running (already re-tuning)
  string detail = 3;
}

InsightsService

Prescriptive content intelligence — the analysis behind the Content Gaps, Content Strategy, and Strategy Roadmap surfaces. Each RPC is synthesized by the platform’s OWN sovereign model (no external AI), grounded in the user’s diagnosis + published content + live market signals, and returned as structured rows the limbic screens render directly (plus a summary and a single headline score).

pulse.v1.InsightsService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
AnalyzeContentGapsAnalyzeContentGapsRequest → ContentGapsResponseeditorAnalyzeContentGaps finds topics/formats the user under-serves vs. demand.
GenerateContentStrategyGenerateContentStrategyRequest → ContentStrategyResponseeditorGenerateContentStrategy proposes content pillars, cadence, and themes.
GenerateStrategyRoadmapGenerateStrategyRoadmapRequest → StrategyRoadmapResponseeditorGenerateStrategyRoadmap lays out a phased go-to-market roadmap.
GetAuditContentGapsGetAuditContentGapsRequest → AuditContentGapsviewerGetAuditContentGaps returns the content gaps computed after the caller’s latest audit, and that step’s progress. No model call.
ListOwnInsightsListOwnInsightsRequest → ListOwnInsightsResponseviewerListOwnInsights lists what the caller ran by hand (AnalyzeContentGaps, GenerateContentStrategy), newest first, as stored. No model call.

Also uses DateRange, Channel.

message GetAuditContentGapsRequest {}

message ListOwnInsightsRequest {}

// One result the user ran by hand; exactly one of gaps / strategy is set.
message OwnInsight {
  string id = 1;
  string kind = 2; // content_gaps | content_strategy
  google.protobuf.Timestamp created_at = 3;
  ContentGapsResponse gaps = 4;
  ContentStrategyResponse strategy = 5;
}

message ListOwnInsightsResponse {
  repeated OwnInsight insights = 1;
}

message AuditContentGaps {
  // Unset when no audit has computed gaps yet.
  ContentGapsResponse gaps = 1;
  // The latest audit run ("" = the caller never ran one) and its domain.
  string audit_run_id = 2;
  string domain = 3;
  // That run's content_gaps stage: pending | running | done | failed |
  // skipped ("" = no run), and its detail or error.
  string stage_status = 4;
  string stage_detail = 5;
  // The run whose gaps are shown, when it is an earlier one than audit_run_id.
  string gaps_audit_run_id = 6;
  // The campaign PULSE proposed from these gaps ("" = none).
  string campaign_id = 7;
  // Gaps that serve nothing the business sells (offering_match = no_match):
  // kept out of gaps, offered as "doesn't match what you sell".
  repeated ContentGap unmatched_gaps = 8;
}

message AnalyzeContentGapsRequest {
  string focus_area = 1;    // optional theme to concentrate the analysis on
  DateRange date_range = 2; // window of published content to assess
  // A competitor to compare with: its site (example.com) or a social handle
  // (@name). A site is read; a handle is named only. "" = none.
  string competitor = 3;
}

message ContentGap {
  string topic = 1;
  string format = 2;         // e.g. "article", "video", "infographic"
  double demand_score = 3;   // 0-100 — how much the audience wants this
  double coverage_score = 4; // 0-100 — how well the user currently covers it
  double opportunity = 5;    // 0-100 — prescriptive priority (demand vs coverage)
  string rationale = 6;
  // The judging ladder's verdict on this gap (cmd/judgement_gate.go): concur or
  // unable-to-judge only — a dissented gap is withheld and appears only in
  // ContentGapsResponse.judgements. Unset = judging off (PULSE_JUDGEMENT=off).
  runink.ui.judgement.v1.Judgement judgement = 7;
  // The audit findings this gap was drawn from. Empty = it cites none (the
  // analysis was not run on an audit, or the model cited nothing that exists).
  repeated GapEvidence evidence = 8;
  // What the business sells that this gap serves, as the site or the owner
  // states it ("" = none matched).
  string offering = 9;
  // matches | no_match | not_checked (no offerings were known).
  string offering_match = 10;
}

// One audit finding a gap cites. The three scores of a gap are the model's
// estimates; evidence is what the audit measured.
message GapEvidence {
  string ref = 1;        // "E3"
  string kind = 2;       // site_score | check | discover | retention | trend | ai_visibility
  string text = 3;
  string source_url = 4; // "" when the finding has no page of its own
}

message ContentGapsResponse {
  repeated ContentGap gaps = 1;
  double coverage_index = 2; // headline: overall content coverage 0-100
  string summary = 3;
  google.protobuf.Timestamp generated_at = 4;
  // Every verdict of this run, accepted AND rejected, with the ladder's counts.
  runink.ui.judgement.v1.JudgementSet judgements = 5;
  // What the check was asked (a manual check; "" = not asked).
  string focus_area = 6;
  string competitor = 7;
  // How the competitor was used: "read" (its site's text was read) |
  // "handle" (named only: a handle has no page PULSE reads) | "unreadable"
  // (its site could not be read; competitor_reason says why) | "" (none).
  string competitor_read = 8;
  string competitor_reason = 9;
  // How many of the latest audit's measured findings the check was given
  // (0 = no audit to cite).
  int32 audit_evidence_count = 10;
}

message GenerateContentStrategyRequest {
  string objective = 1;         // e.g. "Thought Leadership", "Lead Gen"
  repeated Channel channels = 2;
  string audience = 3;
}

message ContentPillar {
  string name = 1;
  string description = 2;
  repeated string example_topics = 3;
  double weight = 4; // recommended share of the content mix 0-100
  // The judging ladder's verdict on this pillar; see ContentGap.judgement.
  runink.ui.judgement.v1.Judgement judgement = 5;
}

message ContentStrategyResponse {
  repeated ContentPillar pillars = 1;
  string cadence = 2;          // e.g. "3 posts/week, 1 long-form/month"
  double alignment_score = 3;  // headline: strategy-fit 0-100
  string summary = 4;
  google.protobuf.Timestamp generated_at = 5;
  // Every verdict of this run, accepted AND rejected, with the ladder's counts.
  runink.ui.judgement.v1.JudgementSet judgements = 6;
}

message GenerateStrategyRoadmapRequest {
  string objective = 1;
  int32 horizon_weeks = 2; // planning horizon (defaults sensibly when 0)
}

message RoadmapPhase {
  string name = 1;                // e.g. "Foundation", "Momentum", "Scale"
  string timeframe = 2;           // e.g. "Weeks 1-4"
  repeated string initiatives = 3;
  double momentum = 4;            // projected momentum 0-100
  string outcome = 5;
  // The judging ladder's verdict on this phase; see ContentGap.judgement.
  runink.ui.judgement.v1.Judgement judgement = 6;
}

message StrategyRoadmapResponse {
  repeated RoadmapPhase phases = 1;
  double readiness_score = 2; // headline 0-100
  string summary = 3;
  google.protobuf.Timestamp generated_at = 4;
  // Every verdict of this run, accepted AND rejected, with the ladder's counts.
  runink.ui.judgement.v1.JudgementSet judgements = 5;
}

RadarService

Market research — trending topics, hashtag analysis, profile discovery.

pulse.v1.RadarService, declared in pulse.proto.

MethodRequest → ResponseLeast roleNotes
StartResearchStartResearchRequest → stream StreamChunkeditorStartResearch streams live market research findings for a given topic/niche.
ListRadarResultsListRadarResultsRequest → ListRadarResultsResponseviewerListRadarResults returns the user’s stored radar results, most recent first — materialized from a diagnosis and produced by StartResearch.
SuggestProfilesSuggestProfilesRequest → SuggestProfilesResponseeditorSuggestProfiles suggests influencer/competitor profiles to follow.
UseRadarFeedbackUseRadarFeedbackRequest → google.protobuf.EmptyeditorUseRadarFeedback records user feedback on radar suggestions for refinement.
GetTrendingPostsGetTrendingPostsRequest → GetTrendingPostsResponseeditorGetTrendingPosts returns real scraped social posts for a niche — a visual feed (image + source + relevance) rather than a text summary.
SubmitPostFeedbackSubmitPostFeedbackRequest → google.protobuf.EmptyeditorSubmitPostFeedback records a like/dislike on a single trending post, distinct from UseRadarFeedback (which is profile-level) — this feedback is folded into the grounding context of future GetTrendingPosts calls.
DiscoverCompetitorChannelsDiscoverCompetitorChannelsRequest → DiscoverCompetitorChannelsResponseeditorDiscoverCompetitorChannels finds competitors’ YouTube & Instagram channels for a niche/competitor list via real web search + structured extraction.
DiscoverGuestOpportunitiesDiscoverGuestOpportunitiesRequest → DiscoverGuestOpportunitiesResponseeditorDiscoverGuestOpportunities finds YouTube channels and podcasts the user could guest on (interview/collab formats) within a niche.
DraftPartnershipOutreachDraftPartnershipOutreachRequest → stream StreamChunkeditorDraftPartnershipOutreach streams a first-contact message proposing a two-sided value exchange (e.g. a guest-episode swap) for a discovered channel/podcast, and stages it for the user’s approval (draft-only).
ListPartnershipOutreachListPartnershipOutreachRequest → ListPartnershipOutreachResponseviewerListPartnershipOutreach returns the outreach messages already drafted/staged.
ListDiscoveredChannelsListDiscoveredChannelsRequest → ListDiscoveredChannelsResponseviewerListDiscoveredChannels returns the competitor channels and guest opportunities already discovered and persisted for the caller — by an audit’s background research pass or an earlier Discover* call — most relevant first. Read-only: it runs no search and no model call, so the Radar page can open on what the audit found instead of re-searching.
ListTrendingPostsListTrendingPostsRequest → ListTrendingPostsResponseviewerListTrendingPosts returns the trending posts already found and persisted for the caller, newest first. Read-only (no search, no model call).

Also uses StreamChunk, Channel, AssistantToolEvent, AssistantProposal.

message StartResearchRequest {
  string topic = 1;
  string niche = 2;
  repeated Channel channels = 3;
  string target_audience = 4;
  string region = 5;            // e.g. "BR", "US", "LATAM"
  string language = 6;          // e.g. "pt-BR", "en-US"
  // Extra sources the user attached to ground this research beyond the default
  // web search — web-search seeds, website/YouTube URLs, or pasted text. The
  // radar agent folds these into the prompt as user-provided grounding.
  repeated ExtraSource extra_sources = 7;
}

// Where an ExtraSource came from — mirrors the "add sources" composer in the UI.
enum ExtraSourceKind {
  EXTRA_SOURCE_KIND_UNSPECIFIED = 0;
  EXTRA_SOURCE_KIND_WEB = 1;         // a web-search seed (query grounded live)
  EXTRA_SOURCE_KIND_WEBSITE = 2;     // a website or YouTube URL to scrape
  EXTRA_SOURCE_KIND_PASTED_TEXT = 3; // free-form text pasted by the user
}

// One user-attached source that grounds market research. `url` is set for
// website/YouTube sources (scraped server-side); `content` carries inline text
// for pasted-text sources; `label` is a human title shown as a chip in the UI.
message ExtraSource {
  ExtraSourceKind kind = 1;
  string label = 2;     // display title (page title, "Pasted text", the query…)
  string url = 3;       // for website/YouTube sources
  string content = 4;   // inline text for pasted-text sources
}

message ListRadarResultsRequest {}

message ListRadarResultsResponse {
  repeated RadarResults results = 1;
}

message RadarResults {
  string id = 1;
  string topic = 2;
  repeated TrendingTopic trends = 3;
  repeated HashtagCluster hashtag_clusters = 4;
  repeated ProfileSuggestion suggested_profiles = 5;
  string market_summary = 6;
  string competitive_intel = 7;
  google.protobuf.Timestamp generated_at = 8;
}

message TrendingTopic {
  string title = 1;
  string description = 2;
  double relevance_score = 3; // 0.0-1.0
  string source = 4;          // platform or data source
  repeated Channel channels = 5;
}

message HashtagCluster {
  string primary_hashtag = 1;
  repeated string related_hashtags = 2;
  int64 estimated_reach = 3;
  double engagement_rate = 4;
  Channel channel = 5;
}

message ProfileSuggestion {
  string username = 1;
  string display_name = 2;
  string bio = 3;
  string profile_url = 4;
  Channel channel = 5;
  int64 follower_count = 6;   // as stated in the search results; 0 = unknown (never estimated)
  double relevance_score = 7;
  string category = 8; // "influencer", "competitor", "partner"
}

message SuggestProfilesRequest {
  string niche = 1;
  repeated Channel channels = 2;
  string region = 3;
  int32 max_results = 4;
}

message SuggestProfilesResponse {
  repeated ProfileSuggestion profiles = 1;
}

message UseRadarFeedbackRequest {
  string research_id = 1;
  string profile_username = 2;
  string feedback_type = 3; // "useful", "not_relevant", "save", "block"
  string notes = 4;
}

// RadarPost is one real scraped social/web post surfaced by GetTrendingPosts
// — a visual feed item (image + source + a 0-100 relevance/hot score) that
// the user can react to, as opposed to a text-only TrendingTopic summary.
message RadarPost {
  string id = 1;
  string source_url = 2;
  string image_url = 3;
  string caption = 4;
  string author_handle = 5;
  Channel channel = 6;
  int32 hot_score = 7;    // 0-100, the model's estimate; -1 = not scored
  string feedback = 8;    // "", "like", "dislike"
  google.protobuf.Timestamp created_at = 9;
  string niche = 10; // the niche the search ran for
}

message GetTrendingPostsRequest {
  string niche = 1;
  repeated Channel channels = 2;
  int32 max_results = 3;
}

message GetTrendingPostsResponse {
  repeated RadarPost posts = 1;
}

message SubmitPostFeedbackRequest {
  string post_id = 1;
  string feedback = 2; // "like" or "dislike"
}

// DiscoveredChannel is a competitor's social channel or a guest opportunity
// (YouTube channel / podcast) surfaced by Radar discovery.
message DiscoveredChannel {
  string id = 1;
  string name = 2;              // channel / show / person name
  string handle = 3;            // @handle or host name
  Channel channel = 4;          // YOUTUBE, INSTAGRAM, PODCAST, ...
  string url = 5;               // channel / show URL
  string description = 6;       // what the channel is about
  int64 audience_size = 7;      // subscribers/followers/listeners as stated in the search results; 0 = unknown (never estimated)
  string category = 8;          // "competitor" or "guest_opportunity"
  double relevance_score = 9;   // 0.0-1.0 fit for the niche
  string contact_hint = 10;     // booking/contact link or email if found, else ""
  google.protobuf.Timestamp created_at = 11;
  // source_url is the channel URL ONLY when that URL appeared verbatim in the
  // web-search results the discovery was grounded on; "" when the model
  // produced a URL the search never returned (unverified — never imported as
  // an influencer, and shown as unverified).
  string source_url = 12;
  google.protobuf.Timestamp discovered_at = 13; // when it was found and persisted
  string niche = 14;                            // the niche it was found for
  // true = relevance_score could not be read (the model wrote no number):
  // the fit is ABSENT and shown as "not rated", never as 0.
  bool relevance_unrated = 15;
}

message DiscoverCompetitorChannelsRequest {
  string niche = 1;
  repeated string competitors = 2; // explicit names; if empty, derived from niche/diagnosis
  string region = 3;
  int32 max_results = 4;
}

message DiscoverCompetitorChannelsResponse {
  repeated DiscoveredChannel channels = 1;
}

message DiscoverGuestOpportunitiesRequest {
  string niche = 1;
  string topic = 2;                // what the user wants to be a guest about
  repeated Channel channels = 3;   // restrict to e.g. YOUTUBE, PODCAST; empty = both
  string region = 4;
  int32 max_results = 5;
}

message DiscoverGuestOpportunitiesResponse {
  repeated DiscoveredChannel channels = 1;
}

// PartnershipOutreach is a staged first-contact message for a discovered
// channel/podcast, proposing a two-sided value exchange. Draft-only until the
// user reviews and sends it (no auto-send).
message PartnershipOutreach {
  string id = 1;
  string channel_id = 2;        // DiscoveredChannel.id it targets (may be "")
  string target_name = 3;
  string target_url = 4;
  Channel channel = 5;
  string subject = 6;
  string body = 7;
  string value_for_them = 8;    // why the host benefits
  string value_for_us = 9;      // why we benefit
  string status = 10;           // "draft"
  google.protobuf.Timestamp created_at = 11;
}

message DraftPartnershipOutreachRequest {
  string channel_id = 1;        // discovered channel to target (optional)
  string target_name = 2;       // required if channel_id empty
  string target_url = 3;
  Channel channel = 4;
  string category = 5;          // "competitor" | "guest_opportunity"
  string angle = 6;             // optional extra context / offer angle
}

message ListPartnershipOutreachRequest {
  int32 max_results = 1;
}

message ListPartnershipOutreachResponse {
  repeated PartnershipOutreach outreach = 1;
}

message ListDiscoveredChannelsRequest {
  string category = 1;    // "competitor" | "guest_opportunity"; "" = both
  int32 max_results = 2;  // <= 0 = server default (50)
}

message ListDiscoveredChannelsResponse {
  repeated DiscoveredChannel channels = 1;
}

message ListTrendingPostsRequest {
  string niche = 1;       // "" = every niche the caller has researched
  int32 max_results = 2;  // <= 0 = server default (20)
}

message ListTrendingPostsResponse {
  repeated RadarPost posts = 1;
}

SearchConsoleService

Google Search Console, read-only (scope webmasters.readonly): connect with Google (the same OAuth client as YouTube, PKCE), pick the property, and read the Search Analytics of the last 28 days against the 28 before, once a day. What it reads is measured search demand: clicks, impressions, CTR and average position per query and per page. Not connected = not measured.

pulse.v1.SearchConsoleService, declared in search_console.proto.

MethodRequest → ResponseLeast roleNotes
StartSearchConsoleConnectStartSearchConsoleConnectRequest → StartSearchConsoleConnectResponseeditorStartSearchConsoleConnect returns Google’s consent URL; Google redirects to /oauth/search-console/callback, which seals the tokens and lists the properties. configured=false (with message) when this server has no Google client or no public address.
GetSearchConsoleGetSearchConsoleRequest → SearchConsoleStatusviewerGetSearchConsole: the connection, its properties and its last read.
SetSearchConsolePropertySetSearchConsolePropertyRequest → SearchConsoleStatuseditorSetSearchConsoleProperty chooses the property PULSE reads.
SyncSearchConsoleSyncSearchConsoleRequest → SearchConsoleStatuseditorSyncSearchConsole reads now (the daily read does the same; a read that already has today’s data makes no call).
GetSearchVisibilityGetSearchVisibilityRequest → SearchVisibilityviewerGetSearchVisibility: what was read, for Brand Analysis. A read; no call to Google.
message StartSearchConsoleConnectRequest {
  bool reconnect = 1;
}

message StartSearchConsoleConnectResponse {
  bool configured = 1;
  string authorize_url = 2;
  string redirect_uri = 3; // the callback the Google OAuth client must allow
  string message = 4;      // why sign-in is not available, when configured=false
}

// A Search Console property the connected Google account can read.
message SearchConsoleProperty {
  string site_url = 1;          // "sc-domain:example.com" or "https://www.example.com/"
  string permission_level = 2;  // siteOwner | siteFullUser | siteRestrictedUser
  bool matches_audited_domain = 3;
}

message GetSearchConsoleRequest {}

message SetSearchConsolePropertyRequest {
  string site_url = 1;
}

message SyncSearchConsoleRequest {}

message SearchConsoleStatus {
  // not_connected | pick_property | connected | reconnect
  string state = 1;
  string integration_id = 2;
  string account_name = 3;
  string site_url = 4; // the chosen property; "" when none
  repeated SearchConsoleProperty properties = 5;
  string audited_domain = 6; // the domain of the latest site audit; "" when none
  string properties_note = 7; // why the property list is empty, when it is
  string watermark = 8;       // last day read (YYYY-MM-DD); "" = never read
  google.protobuf.Timestamp last_read_at = 9;
  string last_error = 10;
  string last_error_kind = 11; // auth | permission | quota | unreadable; "" when the last read worked
}

message GetSearchVisibilityRequest {
  int32 limit = 1; // rows per list; 0 = 10
}

// One query or page, last 28 days, with the 28 before when it had any.
message SearchRow {
  string key = 1; // the query, or the page URL
  int64 clicks = 2;
  int64 impressions = 3;
  double ctr = 4;      // 0..1
  double position = 5; // average position, 1 = top
  bool has_prior = 6;
  int64 prior_clicks = 7;
  int64 prior_impressions = 8;
  double prior_position = 9;
}

message SearchVisibility {
  // False: nothing was read (why says so: not connected, no property, not
  // read yet, or the last read failed). Never shown as zero.
  bool measured = 1;
  string why = 2;
  string site_url = 3;
  string current_start = 4; // YYYY-MM-DD
  string current_end = 5;
  string prior_start = 6;
  string prior_end = 7;
  // Totals over the days read in each window; has_totals false when the days
  // were not read.
  bool has_totals = 8;
  int64 clicks = 9;
  int64 impressions = 10;
  bool has_prior_totals = 11;
  int64 prior_clicks = 12;
  int64 prior_impressions = 13;
  repeated SearchRow top_queries = 14;   // most clicks first
  repeated SearchRow losing_pages = 15;  // most clicks lost first
  repeated SearchRow near_page_one = 16; // average position 4 to 15, most impressions first
  google.protobuf.Timestamp read_at = 17;
}

GoogleBusinessService

Google Business Profile (GBP), per account: connect with Google (the same OAuth client as YouTube and Search Console, PKCE, scope business.manage), choose the locations PULSE manages, and read their reviews and basic performance. Replies to reviews are DRAFTED by PULSE’s own inference into an approval queue; only a person’s approval posts one, and a negative review is never answered without the person saying they read it. GBP posts (update, offer, event) are content on CHANNEL_GOOGLE_BUSINESS: they go through the approval queue and the publisher like every other channel (PULSE_APPLY_ENABLED and PULSE_PUBLISH_GBP; replies also PULSE_PUBLISH_GBP_REPLIES). Not connected = not measured, never a zero.

pulse.v1.GoogleBusinessService, declared in gbp.proto.

MethodRequest → ResponseLeast roleNotes
StartGBPConnectStartGBPConnectRequest → StartGBPConnectResponseeditorStartGBPConnect returns Google’s consent URL; Google redirects to /oauth/google-business/callback, which seals the tokens and lists the locations. configured=false (with message) when this server has no Google client or no https public address.
GetGBPGetGBPRequest → GBPStatusviewerGetGBP: the connection, its locations and the last read.
SetGBPLocationsSetGBPLocationsRequest → GBPStatuseditorSetGBPLocations chooses the locations PULSE manages (reads, drafts replies for, and can post to).
SyncGBPSyncGBPRequest → GBPStatuseditorSyncGBP reads now (the scheduled read does the same).
ListGBPReviewsListGBPReviewsRequest → GBPReviewsviewerListGBPReviews: what was read, for the Reviews page. No call to Google.
ApproveGBPReplyApproveGBPReplyRequest → GBPRevieweditorApproveGBPReply posts the reply (as drafted, or the person’s edit) through every publish gate. A negative review needs acknowledge_negative=true.
DismissGBPReplyDismissGBPReplyRequest → GBPRevieweditorDismissGBPReply drops the draft: nothing is posted.
CreateGBPPostCreateGBPPostRequest → CreateGBPPostResponseeditorCreateGBPPost saves a GBP post as content waiting for approval on CHANNEL_GOOGLE_BUSINESS. Approving it in the approval queue publishes it.
ProposeReviewRequestProposeReviewRequestRequest → ProposeReviewRequestResponseeditorProposeReviewRequest drafts a review-request email for a won lead in the outreach system (the same proposal PULSE makes when a deal is marked won). It waits for approval like every outreach email.
message StartGBPConnectRequest {
  bool reconnect = 1;
}

message StartGBPConnectResponse {
  bool configured = 1;
  string authorize_url = 2;
  string redirect_uri = 3; // the callback the Google OAuth client must allow
  string message = 4;      // why sign-in is not available, when configured=false
}

// A Business Profile location the connected Google account manages.
message GBPLocation {
  string name = 1;          // "locations/123"
  string account = 2;       // "accounts/456"
  string title = 3;
  string address = 4;
  string place_id = 5;      // "" when Google gave none (no review link then)
  string maps_uri = 6;
  string review_uri = 7;    // the link that opens "write a review"; "" when unknown
  bool managed = 8;         // PULSE reads it and drafts for it
}

message GetGBPRequest {}

message SetGBPLocationsRequest {
  repeated string names = 1; // the managed locations; empty = none
}

message SyncGBPRequest {}

message GBPStatus {
  // not_connected | pick_locations | connected | reconnect
  string state = 1;
  string integration_id = 2;
  string account_name = 3;
  repeated GBPLocation locations = 4;
  string locations_note = 5; // why the list is empty, when it is
  google.protobuf.Timestamp last_read_at = 6;
  string last_error = 7;
  string last_error_kind = 8; // auth | permission | quota | unreadable; "" when the last read worked
}

message ListGBPReviewsRequest {
  string location_name = 1; // "" = every managed location
}

message GBPReview {
  string id = 1;              // PULSE's id
  string location_name = 2;
  string location_title = 3;
  string reviewer = 4;        // "" for an anonymous reviewer
  int32 rating = 5;           // 1..5; 0 = Google gave no star rating
  string text = 6;            // "" = a rating with no text
  google.protobuf.Timestamp created_at = 7;
  bool has_reply = 8;         // the business has replied on Google
  string reply_text = 9;
  // none | not_drafted | waiting | sent | withheld | failed | dismissed
  string draft_status = 10;
  string draft_reply = 11;
  string draft_reason = 12;   // why not drafted, withheld or failed
  bool negative = 13;         // 1-2 stars, or 3 stars with a complaint: never answered without the person
}

// Basic performance of the managed locations, last 28 complete days. Each
// figure counts only when its *_reported flag is true (Google reported it).
message GBPInsights {
  bool measured = 1;
  string why = 2;             // when not measured
  string start = 3;           // YYYY-MM-DD
  string end = 4;
  bool impressions_reported = 5;
  int64 impressions = 6;      // Search + Maps, desktop + mobile
  bool calls_reported = 7;
  int64 calls = 8;
  bool website_clicks_reported = 9;
  int64 website_clicks = 10;
  bool direction_requests_reported = 11;
  int64 direction_requests = 12;
}

message GBPReviews {
  // False: nothing was read (why says so). Never shown as zero.
  bool measured = 1;
  string why = 2;
  bool has_rating = 3;        // Google reported an average rating
  double average_rating = 4;  // weighted over the managed locations
  int64 total_reviews = 5;    // as Google counts them
  int32 unanswered = 6;       // of the stored reviews
  int32 waiting_approval = 7; // drafts waiting for a person
  repeated GBPReview reviews = 8; // newest first
  GBPInsights insights = 9;
  google.protobuf.Timestamp read_at = 10;
}

message ApproveGBPReplyRequest {
  string review_id = 1;
  string text = 2;                 // "" = as drafted
  bool acknowledge_negative = 3;   // required for a negative review
}

message DismissGBPReplyRequest {
  string review_id = 1;
}

message CreateGBPPostRequest {
  string location_name = 1;
  string topic_type = 2;     // update | offer | event
  string summary = 3;        // the post's text (Google allows 1500 characters)
  string event_title = 4;    // event and offer
  string start_date = 5;     // YYYY-MM-DD, event and offer
  string end_date = 6;       // YYYY-MM-DD, event and offer
  string coupon_code = 7;    // offer, optional
  string redeem_url = 8;     // offer, optional
  string terms = 9;          // offer, optional
  string action_type = 10;   // "" | LEARN_MORE | BOOK | ORDER | SHOP | SIGN_UP | CALL
  string action_url = 11;    // required for every action but CALL
  string campaign_id = 12;   // optional
}

message CreateGBPPostResponse {
  string content_id = 1;
}

message ProposeReviewRequestRequest {
  string lead_id = 1;
}

message ProposeReviewRequestResponse {
  string sequence_id = 1;
  string message = 2;
}

BrandSignalsService

SERVICE: BrandSignalsService (owner, 2026-11-16)

Brand awareness (how visible and mentioned the brand is), Reputation (reviews and public comment) and Customer approvals (how customers approve of the brand and its offers). All three are computed by the platform’s ONE market-signals engine (org-runink/crawler signals), shared with FACE: public search through the shared crawler (robots obeyed), PULSE’s own model behind the untrusted-data fence, cited cards only. PULSE stores each week’s measures, compares the latest week with the account’s OWN earlier weeks (no fixed threshold; confidence n/(n+1)), and turns a shift into a campaign PROPOSAL a person accepts or dismisses in Campaigns. Nothing is published or sent. Reviews are themes, never people.

pulse.v1.BrandSignalsService, declared in brand_signals.proto.

MethodRequest → ResponseLeast roleNotes
GetBrandSignalsGetBrandSignalsRequest → BrandSignalsviewerWhat is stored for one area: the last reading, the measures’ weeks and the ideas. No search and no model.
ReadBrandSignalsReadBrandSignalsRequest → BrandSignalseditorRead one area now (search + model); the week’s measures are stored.
ProposeBrandCampaignProposeBrandCampaignRequest → ProposeBrandCampaignResponseeditorTurn one idea into a campaign PROPOSAL (Campaigns: accept or dismiss).
enum BrandArea {
  BRAND_AREA_UNSPECIFIED = 0;
  BRAND_AREA_AWARENESS = 1;
  BRAND_AREA_REPUTATION = 2;
  BRAND_AREA_APPROVAL = 3;
}

message GetBrandSignalsRequest {
  BrandArea area = 1;
}

message ReadBrandSignalsRequest {
  BrandArea area = 1;
}

message ProposeBrandCampaignRequest {
  BrandArea area = 1;
  string idea_id = 2;
}

message ProposeBrandCampaignResponse {
  string campaign_id = 1;
  // Set when nothing new was proposed, and why.
  string note = 2;
}

message BrandSignalEvidence {
  string excerpt = 1;
  string source_url = 2;
  string source_label = 3;
}

message BrandSignalCard {
  string kind = 1;
  // positive | negative | mixed | neutral
  string tone = 2;
  string title = 3;
  string summary = 4;
  string suggestion = 5;
  // low | medium | high, and why.
  string confidence = 6;
  string confidence_reason = 7;
  repeated BrandSignalEvidence evidence = 8;
}

message BrandSignalSource {
  string label = 1;
  string url = 2;
  // read | not_readable | not_configured | failed
  string state = 3;
  string note = 4;
}

// One week's value of a measure.
message BrandMeasureWeek {
  string week = 1; // YYYY-MM-DD, a Monday
  double value = 2;
  int32 basis = 3;
}

// One measure: its latest value, what it rests on, and its own history.
message BrandMeasure {
  // visibility | mentions | rating | positive_share | approval
  string name = 1;
  double value = 2;
  // What the value rests on (pages, reviews, cited pieces); 0 = not measured.
  int32 basis = 3;
  // Why it was not measured, when basis is 0.
  string note = 4;
  // Oldest first; weeks with basis 0 are left out.
  repeated BrandMeasureWeek weeks = 5;
}

// A campaign idea from a measure's shift in its latest week against the
// account's own earlier weeks.
message BrandCampaignIdea {
  string idea_id = 1;
  string measure = 2;
  // up | down
  string direction = 3;
  string week = 4;
  double this_week = 5;
  double earlier_mean = 6;
  double earlier_min = 7;
  double earlier_max = 8;
  int32 earlier_weeks = 9;
  // n / (n + 1) for n earlier weeks.
  double confidence = 10;
  string confidence_reason = 11;
  // The English rationale the proposal records.
  string rationale = 12;
  // Oldest first; the last is this week.
  repeated BrandMeasureWeek evidence = 13;
  // The campaign proposed from it ("" = not proposed).
  string campaign_id = 14;
}

message BrandSignals {
  BrandArea area = 1;
  // no_brand (no check-up names the brand) | not_read | read
  string state = 2;
  string brand_name = 3;
  // Why there are no cards, when there are none.
  string note = 4;
  google.protobuf.Timestamp read_at = 5;
  repeated BrandSignalCard cards = 6;
  repeated BrandSignalSource sources = 7;
  repeated BrandMeasure measures = 8;
  repeated BrandCampaignIdea ideas = 9;
  // Why there are no ideas (e.g. no earlier week yet).
  string ideas_note = 10;
  // Reputation and approvals: whether reviews PULSE holds were included.
  bool reviews_included = 11;
}

SiteChatService

The account owner’s side of the WEBSITE CHAT: the PULSE assistant in a public website-visitor mode (cmd/site_chat*.go). The visitor side is plain HTTP under /site-chat/ (a static widget plus JSON), authenticated by the site key these RPCs make, pinned to the listed origins. A visitor sees only the account’s public facts (offerings, approved FAQ content, pages of its own site); never leads, plans, metrics, other chats or internal tools.

pulse.v1.SiteChatService, declared in site_chat.proto.

MethodRequest → ResponseLeast roleNotes
GetSiteChatGetSiteChatRequest → SiteChatSettingsviewer
UpdateSiteChatUpdateSiteChatRequest → SiteChatSettingseditorSaves on/off, origins, greeting and language. Turning it on the first time makes the site key.
RotateSiteChatKeyRotateSiteChatKeyRequest → SiteChatSettingseditorA new site key; the old one stops working at once.
RevokeSiteChatKeyRevokeSiteChatKeyRequest → SiteChatSettingseditorNo key at all: the widget stops answering and the chat is off.
ListSiteChatHandoffsListSiteChatHandoffsRequest → ListSiteChatHandoffsResponseviewer“Ask a person” requests from visitors, newest first.
ResolveSiteChatHandoffResolveSiteChatHandoffRequest → SiteChatHandoffeditor
message GetSiteChatRequest {}

message SiteChatSettings {
  bool enabled = 1;
  // The public site key the snippet carries. Not a secret (it is in the
  // page), but only ever lets a visitor chat with this account's public facts
  // from the listed origins. "" = none (revoked or never made).
  string site_key = 2;
  repeated string allowed_origins = 3;
  string greeting = 4;
  string language = 5; // en | es | fr | pt: the widget's language
  // The HTML to paste just before the closing body tag; "" without a key
  // or a public URL.
  string embed_snippet = 6;
  // The widget script's URL (PULSE_PUBLIC_BASE_URL + /site-chat/widget.js).
  string widget_url = 7;
  // False: this server has no rate limits, daily cap or public URL set, so
  // the widget answers nothing; why lists what is missing.
  bool server_ready = 8;
  string server_not_ready_why = 9;
  // How long a visitor's chat is kept, in hours (PULSE_SITE_CHAT_RETENTION_HOURS).
  int32 retention_hours = 10;
  // Visitor messages accepted today (UTC) against the daily cap.
  int32 messages_today = 11;
  int32 daily_cap = 12;
  google.protobuf.Timestamp key_created_at = 13;
}

message UpdateSiteChatRequest {
  bool enabled = 1;
  repeated string allowed_origins = 2;
  string greeting = 3;
  string language = 4;
}

message RotateSiteChatKeyRequest {}

message RevokeSiteChatKeyRequest {}

message SiteChatTurn {
  string role = 1; // user (the visitor) | assistant
  string text = 2;
  google.protobuf.Timestamp at = 3;
}

message SiteChatHandoff {
  string id = 1;
  string status = 2; // open | resolved
  string message = 3; // what the visitor asked a person
  // Given only with the visitor's consent; "" otherwise.
  string name = 4;
  string email = 5;
  string page = 6; // host + path the visitor was on
  google.protobuf.Timestamp created_at = 7;
  google.protobuf.Timestamp resolved_at = 8;
  // The visitor's chat while it is kept (see retention_hours); empty after.
  repeated SiteChatTurn transcript = 9;
  string lead_id = 10; // the lead made from it, when the visitor consented
}

message ListSiteChatHandoffsRequest {
  bool open_only = 1;
}

message ListSiteChatHandoffsResponse {
  repeated SiteChatHandoff handoffs = 1;
}

message ResolveSiteChatHandoffRequest {
  string id = 1;
}

SiteRepoService

The person’s own website repository on GitHub (Settings → Integrations → Website repository) and the site fixes PULSE proposes there as pull requests. Proposals go through the GitHub REST API only. PULSE never pushes to the base branch and never merges: a pull request is a proposal. Proposing needs PULSE_APPLY_ENABLED + PULSE_AUDIT_APPLY and an admin.

pulse.v1.SiteRepoService, declared in site_repo.proto.

MethodRequest → ResponseLeast roleNotes
GetSiteRepoGetSiteRepoRequest → SiteRepoviewerThe stored connection and its last checked status. Dials nothing.
ConnectSiteRepoConnectSiteRepoRequest → SiteRepoeditorStores the repository (token sealed) and checks access. Admin only.
CheckSiteRepoCheckSiteRepoRequest → SiteRepoeditorChecks access again and stores the answer.
DisconnectSiteRepoDisconnectSiteRepoRequest → google.protobuf.EmptyeditorForgets the repository and its token. Admin only.
ProposeSiteFixProposeSiteFixRequest → SiteProposaleditorProposes one audit fix as one branch and one pull request.
ListSiteProposalsListSiteProposalsRequest → ListSiteProposalsResponseviewerThe proposals of a run as last read.
RefreshSiteProposalsListSiteProposalsRequest → ListSiteProposalsResponseeditorReads each proposal’s pull request state back from GitHub.
enum SiteRepoStatus {
  SITE_REPO_STATUS_UNSPECIFIED = 0;
  SITE_REPO_STATUS_NOT_CONNECTED = 1;
  SITE_REPO_STATUS_CONNECTED = 2;
  SITE_REPO_STATUS_MISSING_PERMISSION = 3;
  SITE_REPO_STATUS_UNREACHABLE = 4;
  SITE_REPO_STATUS_TOKEN_REJECTED = 5;
  SITE_REPO_STATUS_BRANCH_NOT_FOUND = 6;
}

message SiteRepo {
  string owner = 1;
  string repo = 2;
  string base_branch = 3;
  SiteRepoStatus status = 4;
  string status_detail = 5;               // why, in plain words; "" when connected
  google.protobuf.Timestamp checked_at = 6; // unset = never checked
  bool has_token = 7;
}

message GetSiteRepoRequest {}

message ConnectSiteRepoRequest {
  string owner = 1;
  string repo = 2;
  string base_branch = 3; // "" = main
  // A fine-grained personal access token limited to this repository with
  // Contents and Pull requests read and write. "" keeps the stored token.
  string token = 4;
}

message CheckSiteRepoRequest {}

message DisconnectSiteRepoRequest {}

message ProposeSiteFixRequest {
  string run_id = 1;   // the audit run whose site score found the issue
  string check_id = 2; // the finding (AuditAction.check_id)
}

message SiteProposalFile {
  string path = 1;
  string op = 2; // create | modify
  string reason = 3;
}

message SiteProposal {
  string id = 1;
  string run_id = 2;
  string check_id = 3;
  // open | merged | closed (read from GitHub); not_needed (the fix is already
  // in the repository or cannot be placed; detail says which); withheld (the
  // plan gate dissented; detail says why).
  string state = 4;
  string detail = 5;
  string branch = 6;
  int32 pr_number = 7;
  string pr_url = 8;
  string stack = 9;
  repeated SiteProposalFile files = 10;
  google.protobuf.Timestamp created_at = 11;
  google.protobuf.Timestamp state_checked_at = 12;
  // The plan gate's verdict: concur | unable | off.
  string gate = 13;
}

message ListSiteProposalsRequest {
  string run_id = 1;
}

message ListSiteProposalsResponse {
  repeated SiteProposal proposals = 1;
}