Client Reporting

Originally published at thatdevpro.com. This framework reference is part of the 14-tier Engine Optimization stack from ThatDevPro, an SDVOSB-certified veteran-owned web + AI engineering studio. You are reading the dev.to mirror; the source-of-truth canonical version with embedded validation tools lives at the link above.

Reporting Cadence, Dashboard Design, KPI Selection, Narrative Reporting, Stakeholder Communication, and the Discipline of Showing Value Without Drowning in Data

A canonical operational reference for client reporting across SEO, AEO, AIO, and GEO engagements. Reporting is the visible artifact that determines retainer renewal. A well executed engagement with poor reporting feels less valuable than a mediocre engagement with excellent reporting. In 2026 the discipline doubled in complexity because reporting must address four visibility surfaces simultaneously where one used to suffice. This framework specifies report design, KPI selection, audience cuts, cadence, AI surface measurement, attribution coordination, the data pipeline, visualization standards, and the self hosted reporting stack on Bubbles. Dual purpose: installation manual and operational manual.

1. Document Purpose

1.1 What This Document Is

This is the canonical reference for the reporting layer of a four pillar SEO engagement. Reports are the visible artifact the client uses to decide whether the engagement continues. Every renewal conversation references the most recent report. Every churn can be traced back to a report that did not communicate value clearly enough to defend the budget against the next vendor pitch.

The discipline is selection plus narrative plus action. Selection: choose the small set of metrics that matters from the large set available. Narrative: connect the metrics to the business outcome the client cares about. Action: end every report with a recommendation the client can approve or reject. A report without selection is a data dump. A report without narrative is a chart deck. A report without action is a status update. None defend a retainer.

1.2 The 2026 Multi Surface Reporting Mandate

Reporting in 2026 must address four surfaces simultaneously. SEO classic organic ranking and click traffic. AEO answer engine optimization, featured snippets and voice. AIO AI Overview citation per framework-aioverviews.md. GEO broader generative engine citation per framework-aicitations.md.

Pre 2024 a single dashboard tracking organic sessions, conversions, and rankings was sufficient. Post citation decoupling that dashboard reports approximately 35 percent of the visibility surface honestly. The other 65 percent (AIO citation, AI Mode citation, GEO citation, brand mention without click, voice extraction overlap) is invisible to traffic centric reporting. The 2026 report covers SEO traffic alongside AI surface citation share alongside attribution path analysis alongside brand mention pace. The discipline of selection is what keeps the four layered deliverable from collapsing into a forty page PDF nobody reads.

1.3 Three Operating Modes

Mode A, Install Mode. Build the reporting infrastructure on a new engagement. Follow Sections 2 through 14 in order. Mode B, Audit Mode. Evaluate the existing reporting stack against the 14 section checklist. Identify gaps, prioritize remediation. Mode C, Hybrid Mode. Audit first, install for gaps.

1.4 Required Tools

• Google Search Console, see framework-gscanalysis.md
• Google Analytics 4, see framework-ga4.md
• Google Business Profile API where local applies
• Ahrefs or Semrush for backlink and ranking data
• Bing Webmaster Tools for Bing organic and Copilot signals
• AI citation monitor: Profound, Otterly, Athena HQ, BrightEdge AI Catalyst, or Semrush AI Toolkit
• Postgres on Bubbles for unified data warehouse
• Python with pandas, matplotlib, plotly for ETL and chart generation
• Pandoc for markdown to PDF rendering
• Self hosted Metabase or Grafana for dashboards
• Gmail SMTP and shared Nextcloud for delivery

1.5 Relationship to Neighboring Frameworks

This framework is the deliverable layer. The data layer upstream lives in framework-ga4.md, framework-gscanalysis.md, framework-attribution.md. The audit layer lives in framework-initialaudit.md, framework-ongoingaudit.md, framework-contentaudit.md. The AI surface layer lives in framework-aioverviews.md, framework-aicitations.md, framework-multiengine-tradeoffs.md. The onboarding layer lives in framework-clientonboarding.md, pricing in framework-pricing.md, tone in framework-brandvoice.md.

2. Client Variables Intake

# REPORTING FRAMEWORK CLIENT VARIABLES

# --- Business and Engagement Identity ---
business_name: ""
primary_domain: ""
engagement_type: ""                   # monthly_retainer, quarterly_engagement, project, one_time_audit
engagement_tier: ""                   # starter, core, growth, enterprise
engagement_start_date: ""
engagement_renewal_date: ""

# --- Report Cadence ---
weekly_report: false
monthly_report: false
quarterly_report: false
annual_report: false

# --- Audience ---
primary_audience: ""                  # founder, ceo, marketing_director, seo_manager, pr_manager, mixed
secondary_audiences: []
audience_technical_literacy: ""       # high, medium, low

# --- Format Preference ---
report_format: ""                     # pdf, html, slide_deck, dashboard_only, mixed
brand_colors_specified: []
brand_fonts_specified: []
client_logo_path: ""

# --- KPI Priority ---
primary_kpis: []                      # 3 to 5 max
secondary_kpis: []
north_star_metric: ""

# --- Comparison Baseline ---
baseline_period: ""                   # previous_month, previous_quarter, year_over_year, custom

# --- Distribution ---
delivery_channel: ""                  # email_pdf, shared_drive, nextcloud, slack, in_person, mixed
delivery_recipient_email: ""
delivery_cc_recipients: []
nextcloud_folder_path: ""

# --- Self Hosting State ---
reports_hosted_on_bubbles: true
report_archive_path: ""               # default /home/user/clients/[clientname]/reports/
postgres_database: ""
metabase_dashboard_url: ""

# --- AI Surface Reporting ---
ai_citation_monitor: ""               # profound, otterly, athena, brightedge, semrush, none
ai_overview_priority_queries: []
ai_engine_referral_tracked: false
brand_mention_pace_target_per_quarter: 0

# --- Attribution Layer ---
three_model_comparison_in_reports: false
brand_vs_nonbrand_split_in_reports: false
assisted_conversions_in_reports: false
mmm_in_reports: false

# --- Sign Off ---
report_review_required_before_send: true
review_assigned_to: ""
review_deadline_hours_before_send: 4

Reports cannot be configured until primary_audience is set, primary_kpis are agreed, and delivery_channel is established. Sites failing those dependencies route back to framework-clientonboarding.md first.

3. The Report Audience Matrix

3.1 The Audience Cut Doctrine

Every report has a primary audience. The primary audience determines the report cut. A single report serving four audiences serves none. The discipline: define the primary audience at engagement start, write the report to that audience, attach summaries or appendices for secondary audiences. Four audience archetypes recur. Each has different metrics they care about, different vocabulary they understand, different decisions they need to make. The same underlying data feeds all four reports. The cuts differ.

3.2 The Founder or CEO Cut

The founder or CEO cares about revenue and brand mention growth. The report opens with the revenue number from organic, the brand mention pace, and the strategic recommendation. Technical detail belongs in the appendix.

Vocabulary: revenue, growth, share, position, decision. Avoid: keywords, SERPs, schema, canonicals, robots.txt, hreflang. Length: 4 to 8 pages. Format: PDF for archive, slide deck for board presentations. Lead with the business outcome. Translate every technical signal into the business consequence.

3.3 The Marketing Director Cut

The marketing director cares about traffic and conversion velocity. The report opens with organic sessions, conversion rate, and the channel mix context. Technical detail is welcomed because the marketing director coordinates with paid, email, and social teams.

Vocabulary: sessions, conversions, channel, attribution, velocity, share, cohort. Spell out abbreviations on first use (E-E-A-T, SQRG, MMM). Length: 12 to 18 pages. Format: PDF with linked dashboard. The operational cut: what is working, what is not, what to adjust next month.

3.4 The SEO Manager Cut

The SEO manager cares about keyword position and technical health. The most technical cut.

Vocabulary: full technical vocabulary, frameworks referenced by name. Length: 18 to 24 pages. Format: PDF plus underlying data export. Show every signal moving, every issue surfacing, every recommendation specific.

3.5 The PR Manager Cut

The PR manager cares about branded mention and citation. Technical SEO detail is minimal. Brand visibility detail is comprehensive.

Vocabulary: mention, placement, reach, sentiment, share of voice, narrative. Length: 8 to 14 pages. Format: PDF with media tracking spreadsheet attached. The brand mention column from the assist conversion table from framework-attribution.md feeds the headline.

3.6 The Mixed Audience Resolution

Many engagements lack a single primary audience. The CEO and the marketing director read the same report. Design for the highest authority audience that will decide on renewal (usually the CEO or founder). Build the founder cut as primary, attach the marketing director cut as a section, attach the SEO manager cut as an appendix. The audience matrix lives at /home/user/clients/[clientname]/reports/audience-matrix.yaml, updated at every quarterly review.

4. KPI Selection Framework

4.1 The 22 Candidate Metrics

Across all four pillars and all four audiences, 22 distinct metrics recur as candidates for reporting. The 22 organized into five buckets:

Visibility (6). Organic impressions per query cohort. Average position for target keywords. AI Overview citation share. AI Mode citation share. ChatGPT, Claude, Perplexity, Copilot brand mention rate. GBP local pack appearance rate.

Traffic (5). Organic sessions. Organic users. Pages per session. Engaged sessions (10 seconds, 1 secondary view, or 90 percent scroll). AI engine referral sessions.

Engagement (4). Average session duration. Scroll depth distribution. Content complete read events. Newsletter or resource download events.

Conversion (4). Direct conversions from organic (last click). Data driven conversions. Assisted conversions. Conversion value or revenue.

Brand (3). Branded query volume in GSC. Unlinked brand mentions across the open web per quarter. Brand mention sentiment ratio.

22 metrics is the candidate pool. No engagement reports all 22. Selection is per engagement.

4.2 The Per Engagement KPI Subset

A typical engagement reports 5 to 9 KPIs total. More than 9 dilutes signal. Fewer than 5 leaves the report thin. The selection rule: every KPI must connect to a business outcome the audience cares about, and the KPI set must cover all four pillars where the engagement targets them.

A small business local service engagement reports 5 KPIs: local pack appearance rate on primary service queries, GBP profile views and call requests, phone clicks from organic search, organic conversion form submissions, and brand mention pace per quarter.

A B2B SaaS lead generation engagement reports 8 KPIs: organic sessions to product and pricing pages, demo request conversions from organic (data driven), assisted conversions from organic, AI Overview citation share on priority queries, ChatGPT brand mention rate, branded query volume from GSC, new referring domain count, and content complete read events on long form articles.

An e commerce engagement reports 7 KPIs: organic revenue (data driven attribution), organic transaction count and average order value, top product page rankings and AIO citation rate, Shopping tab visibility, branded vs non branded organic revenue split, cart abandonment rate from organic sessions, and brand mention pace per quarter.

The subset matches the business model. Local service prioritizes local pack and calls. SaaS prioritizes demo requests and AI surface citation. E commerce prioritizes revenue and product visibility.

4.3 The North Star Metric Doctrine

Every engagement has one north star metric. The single number that defines success. The number on the cover of every report. The number the renewal conversation references. Selection criteria: it must be the metric the audience cares about most, must be measurable consistently across the engagement lifecycle, must move in response to the work the engagement does, and must connect to revenue or revenue proxy.

The north star is set at engagement start. Changed only at quarterly review with explicit client signoff. Reports lead with the north star delta vs baseline before any other metric.

4.4 KPI Selection Process

Six steps per engagement, applied during onboarding and reviewed quarterly. Identify the business outcome that justifies the engagement budget. Identify the audience archetype consuming reports. Select 1 north star metric from the candidate pool. Select 4 to 8 supporting KPIs covering the four pillars where the engagement targets them. Establish baselines for each KPI over a trailing 90 day window. Document the selection in /home/user/clients/[clientname]/reports/kpi-selection.yaml with explicit client signoff.

The selection is reviewed quarterly. Metrics that consistently fail to move are either replaced or escalated to client conversation. Metrics the client has stopped caring about are retired.

4.5 The Forbidden Vanity Metrics

Three metrics that recur in agency reports and almost never connect to business outcomes. Total impressions. Climbing impressions without click or conversion growth signals nothing. Often climbs even as click traffic declines because AI Overview impressions inflate the number without sending clicks. Total backlinks. A site can accumulate thousands of backlinks from spam directories with no impact. Refer instead to new referring domain count from authoritative sources via framework-linkbuilding.md. Total ranking keywords without filtering. A site ranks for thousands of keywords by accident. The relevant subset is target keywords mapped to revenue intent. Any report leading with one of these three has a selection problem.

5. Weekly Report Template

5.1 When Weekly Reports Apply

Weekly reports apply to enterprise tier retainers, active campaign engagements during launch periods, and project engagements while work is in flight. Most retainers do not need weekly. The report must be short enough to read in 5 minutes, focused enough to drive a decision per week, and consistent enough to compare week over week. The cap: 4 pages.

5.2 The Four Page Format

Page 1: Cover. Client name, week ending date, north star metric vs baseline (last week, last month, year over year), one sentence executive summary.

Page 2: Visibility Delta. Organic sessions week over week chart, AI Overview citation count for priority queries, top three movers up and down by query.

Page 3: Conversion Delta. Conversion count and value week over week, conversion rate, assisted conversion change.

Page 4: Action List. Three to five specific actions for the upcoming week. Each has an owner (agency or client), a deadline, and a success criterion.

Total length 4 pages. Rendered as PDF via Pandoc. Delivered Tuesday by 5pm via Gmail or shared Nextcloud folder.

5.3 Pandoc Rendering

The weekly report markdown lives at /home/user/clients/[clientname]/reports/weekly/YYYY-MM-DD-weekly.md. Charts generated by Python and embedded as PNG references. Pandoc renders to PDF via pandoc weekly.md -o weekly.pdf --pdf-engine=xelatex --template=/home/user/clients/templates/weekly-template.latex. The xelatex engine supports custom fonts. The template carries client brand colors and logo. Output PDF lands in the weekly folder, with a symlink to latest.pdf for the Nextcloud share.

5.4 The 30 Minute Generation Budget

A weekly report must be generated in 30 minutes including review. The data pipeline pre aggregates the metrics overnight Monday. The Python notebook generates charts Tuesday morning. The markdown is assembled with a template fill script. The PDF rendering and Gmail send is a single command. If generation takes more than 30 minutes, the pipeline needs investment. The agency time should be the strategic thinking, not data wrangling.

5.5 The Weekly Report Markdown Template

The weekly markdown follows a fixed skeleton at /home/user/clients/templates/weekly-template.md: title with client name and week ending date, prepared by line, north star metric with delta vs last week, one sentence executive summary, visibility delta bullets, conversion delta bullets, and a numbered action list of 3 to 5 items with owner, deadline, and success criterion per action.

6. Monthly Report Template

6.1 The Monthly Report as the Backbone

The monthly report is the backbone deliverable of most retainer engagements. The cadence is sustainable, the depth supports strategic reasoning, and the renewal conversation references the most recent monthly more than any other artifact. The cap: 12 pages of narrative plus appendix. Rendered as PDF via Pandoc. Delivered the first Wednesday of the month by noon.

6.2 The Twelve Page Format

Twelve pages of narrative plus appendix with detailed data tables. The appendix is for reference, not for reading.

6.3 The Two Hour Generation Budget

A monthly report takes approximately two hours of agency time including review. The data pipeline aggregates overnight on the last day of the month. Charts generate Wednesday morning. The narrative is written by the agency lead, not auto generated. The KPI scoreboard auto populates from the Postgres warehouse. The narrative is the work that cannot be automated: selection of which signal matters, framing of why a metric moved, recommendation of what to do next. The 2 hours buys that judgment.

6.4 The Monthly Markdown Template Skeleton

The monthly report follows the standard markdown skeleton at /home/user/clients/templates/monthly-template.md with sections matching the twelve page table above. Each section opens with a narrative paragraph leading the page (Section 12 voice rules) followed by the supporting chart and specific data points. The three model comparison table from framework-attribution.md appears in Conversion Contribution. The AI surface metrics from Section 8 appear in AI Surface Trend. The KPI scoreboard pulls from the warehouse via the Section 14 stack.

6.5 Month Over Month vs Year Over Year Framing

Always include both comparisons. Month over month captures short term movement. Year over year captures structural change and removes seasonality. A traffic decline of 8 percent MoM with a 23 percent YoY increase is a healthy site in a seasonal low. The same 8 percent decline with flat YoY is structural concern. The dual frame is non negotiable.

7. Quarterly Executive Review

7.1 The Quarterly as the Strategic Deliverable

The quarterly report is the strategic deliverable. The monthly is operational, the quarterly is strategic. The audience is typically the founder, CEO, or senior leadership team. The format is deeper, the analysis longer, the recommendations larger in scope. The cap: 24 pages. Rendered as PDF plus optional slide deck for board presentation. Delivered the third Wednesday of the month following quarter end.

7.2 The Twenty Four Page Format

The 24 page structure: page 1 cover and executive summary, pages 2 to 3 business impact summary, pages 4 to 5 organic share of voice, pages 6 to 7 AI citation share of voice, pages 8 to 10 multi touch attribution analysis, pages 11 to 13 content portfolio analysis, pages 14 to 15 link portfolio analysis, pages 16 to 17 technical debt status, pages 18 to 19 competitive intelligence, pages 20 to 21 strategic recommendations, page 22 budget allocation analysis, page 23 90 day roadmap, page 24 KPI scoreboard quarter over quarter and year over year. Strategic narrative plus appendix.

7.3 Business Impact Summary

The business impact summary opens the quarterly. The format: north star metric this quarter, last quarter, same quarter last year, customer acquisition cost from organic, revenue contribution from organic, marketing budget allocation efficiency.

A typical paragraph: "In Q1 2026 organic search delivered 2,341 conversions valued at 487,300 dollars in attributed revenue under data driven attribution. Year over year the quarter is up 38 percent in revenue contribution while overall site traffic grew 12 percent, reflecting improved conversion rate on the buyer guide and product page templates published in Q4 2025. Customer acquisition cost from organic is 24 dollars per conversion against 184 dollars from paid search, making organic the most efficient channel in the mix." Specific numbers, named templates, specific comparison.

7.4 Organic Share of Voice

Share of voice is the percent of priority query impressions captured by the client site vs the top 3 to 5 competitors. Calculated from GSC impressions and Ahrefs or Semrush competitor data. Reported as a 12 month trend. A client gaining share of voice from 18 percent to 27 percent over a year is taking 9 percentage points of attention from competitors. That is the budget defense narrative.

7.5 AI Citation Share of Voice

The new in 2026 metric. AI citation share of voice is the percent of priority query AI surface citations earned by the client site vs the named competitors across Google AI Overview, AI Mode, ChatGPT, Claude, Perplexity, Copilot. Calculation: weekly manual sampling per framework-aioverviews.md Section 10.3, aggregated per engine, ratio of client citations to total citations across competitor set. Reported as 13 week rolling average to account for the 70 percent regeneration volatility. A client cited in AI Overview on 38 percent of priority queries across a quarter is winning the AI surface against competitors cited on 12 percent.

7.6 Multi Touch Attribution Analysis

The quarterly is where multi touch attribution gets full treatment per framework-attribution.md Section 8. Three model comparison plus conversion path analysis plus assisted conversion ratio. The deeper dive surfaces path length distribution, channel role per path position, channel removal effect (Markov chain via BigQuery), and the "AI to organic to conversion" path frequency.

7.7 Content Portfolio Analysis

Content portfolio analysis groups every page on the site by template and topical cluster, then reports per cluster: total pages, average organic traffic per page, conversion rate, AI Overview citation rate, refresh status, Information Gain score. The cuts surface which clusters earn the budget and which are dead weight. See framework-contentaudit.md for the full methodology.

7.8 Strategic Recommendations and the 90 Day Roadmap

The quarterly closes with strategic recommendations and a 90 day forward roadmap. Recommendations are concrete enough to approve or reject. A typical recommendation: "Reallocate 25 percent of monthly content budget from new article production to refresh of the 47 priority pages identified as AI Overview cited in 2025 but uncited in 2026 Q1. Expected impact: restore citation on at least 30 of the 47 pages within 90 days, recovering approximately 8 percent of the AI surface impression baseline. Investment: equivalent to producing 4 new articles per month. Tradeoff: 4 fewer new articles published this quarter." Specific, quantified, with tradeoff acknowledged. The founder can approve or counter propose against the same level of specificity.

8. AI Surface Reporting

8.1 The New in 2026 Reporting Layer

AI surface reporting did not exist as a reporting category in most agency stacks before 2025. By 2026 it is required for any engagement targeting visibility on Google AI Overviews, AI Mode, ChatGPT, Claude, Perplexity, Bing Copilot, or Meta AI. The signals upstream live in framework-aioverviews.md and framework-aicitations.md. The reporting layer aggregates the signals for the client.

8.2 The Six Engine Citation Metrics

Six metrics across the AI surface. Tracked weekly via manual sampling plus third party tool data where available.

AI Overview citation count and share. Count of priority queries where the client site appears as a cited source in Google AI Overview, divided by total priority queries sampled. Tracked across 13 week rolling window because of 70 percent regeneration volatility per framework-aioverviews.md Section 9.1. Headline metric for AIO pillar.

Perplexity citation count and share. Perplexity displays citations more prominently than other engines so visibility is easier to verify. Tracked weekly.

ChatGPT and SearchGPT brand mention rate. Percent of priority queries where the client brand is mentioned in the response. ChatGPT cites less consistently than Google or Perplexity so brand mention rate matters more than citation count.

Gemini brand mention rate. Same engine family as Google AI Overview but the consumer interface and response shape differ.

Claude brand mention rate. Claude favors analytical and balanced perspective content.

Copilot brand mention rate. Microsoft Copilot (formerly Bing Chat). Copilot favors institutional sources.

8.3 The AI Citation Share of Voice Metric

The headline aggregate metric for the AI surface. AI citation share of voice combines the six engine metrics into a single weighted percentage. Default weighting: Google AI Overview 40 percent (largest user base via Google search), Google AI Mode 15 percent (75 million daily users as of January 2026), ChatGPT and SearchGPT 20 percent (largest standalone AI search platform), Perplexity 10 percent (AI search native users, high citation rate), Microsoft Copilot 10 percent (Bing share, enterprise Microsoft 365), Claude 5 percent (professional and developer audience). Weighting adjusts per client business model. A B2B SaaS targeting developer audience increases Claude weight. An enterprise vendor increases Copilot weight. The metric is reported as a single percentage in the quarterly. A client at 24 percent is competitive. 47 percent is dominant. 4 percent is invisible on the AI surface regardless of classic SEO position.

8.4 The Manual Sampling Protocol

Third party tools are improving rapidly but no tool yet provides comprehensive coverage across all six engines with reliable accuracy. Manual sampling is the ground truth. Protocol per framework-aioverviews.md Section 10.3: weekly top 10 priority queries sampled in incognito browser with target market location set, each query run in all six engines, citation state recorded with screenshots in /home/user/clients/[clientname]/ai-sampling/YYYY-WW/. Monthly: next 50 priority queries. Quarterly: long tail. The sampling takes approximately 90 minutes per week per client. The result feeds the citation share metric directly.

8.5 The Third Party Tool Layer

Third party tools complement manual sampling but do not replace it. The 2026 options: Profound (all six engines, brand visibility focus, $800+ monthly), Otterly (five engines, citation tracking, gaps on Copilot), Athena HQ (four engines, evolving), BrightEdge AI Catalyst (all six, enterprise tier, $3000+ monthly), Semrush AI Toolkit (three engines, integrated with Semrush stack). Enterprise engagements use BrightEdge or Profound. Mid market uses Otterly or Athena. Solo and small business engagements rely on manual sampling alone.

8.6 The Pipeline Attribution View

For long sales cycle engagements the AI surface contribution shows up in pipeline attribution rather than immediate conversion per framework-attribution.md Section 10.6. The quarterly report ties AI surface citation share to pipeline created in CRM, closing the loop from AI Overview citation to closed revenue. With the loop closed, the quarterly can report "AI Overview citation contributed to closed deals totaling 187,400 dollars in Q1 2026" rather than only "AI Overview citation count rose 23 percent." The former defends the budget. The latter describes activity.

9. Attribution Reporting

9.1 Cross Reference Authority

Attribution reporting in monthly and quarterly deliverables follows the full architecture in framework-attribution.md. This section specifies the subset that appears in client facing reports.

9.2 The Three Model Comparison

Every monthly report includes a three model comparison table per framework-attribution.md Section 5.9 with rows for organic non brand, organic brand, direct, paid search non brand, paid search brand, email, paid social, organic social, AI engine referral, and referral, and columns for last click, data driven, assisted, and touched paths. Three model comparison is non negotiable. Last click alone systematically under reports SEO. Data driven alone is a black box. Assisted conversions alone misses the closing channel signal. The three together produce honest reporting.

9.3 GA4 Last Click vs Data Driven Framing

The reporting frame: "Under last click, organic search delivered 47 conversions this month. Under data driven attribution, organic search delivered 89 conversions because the model credits organic for assisting paths where another channel closed. Both numbers are correct. The 47 reflects which channel was last in the path. The 89 reflects which channel contributed to the path. We recommend the data driven number for budget conversation because it captures the full contribution organic made." That framing surfaces the difference in plain language. The client understands the gap.

9.4 Multi Touch Path Analysis

The path analysis surfaces patterns the three model table cannot. Common 2026 patterns: organic to direct to conversion (buyer reads content, returns directly, converts), organic to paid to conversion (buyer reads content, sees retargeting, converts via paid), AI Overview to organic to conversion (buyer sees AIO citation, clicks through, converts), paid to organic to conversion (paid generates awareness, organic harvests), brand search only (demand harvesting only, upstream invisible). The quarterly report includes path frequency for the top 5 patterns. A client where 40 percent of conversions follow the "AI Overview to organic to conversion" pattern is winning the AI surface citation work even if last click reports flat organic numbers.

9.5 The AI to Organic to Conversion Path

The flagship path of 2026. A buyer reads a citation in an AI Overview, recognizes the brand, returns via direct or brand search weeks later, converts. The AI Overview citation that started the chain is invisible to standard attribution. The brand search session that closed the path absorbs the credit. The path is identified through the patterns in framework-attribution.md Section 10.3: brand search volume lag against AI Overview impression delta, onsite attribution survey on the thank you page, GSC AIO impression baseline correlated with conversion lift on cited pages. The reporting frame: "AI Overview citation count rose 38 percent in Q1 2026. Brand search volume rose 23 percent in Q2 2026, consistent with the 60 to 180 day brand recall lag the framework expects."

9.6 The Brand vs Non Brand Split

Every report separates brand from non brand organic per framework-attribution.md Section 9. Brand search converts at 5 to 20 times the rate of non brand search. Bundling them inflates organic conversion rate with demand harvesting that reflects the relationship upstream work built, not the closing organic session. The reporting frame: "Combined organic converted at 1.41 percent this month. Non brand organic converted at 0.56 percent. Brand organic converted at 7.36 percent. Non brand reflects cold acquisition from new search demand. Brand reflects demand harvesting on relationships content and PR work built upstream."

10. Data Source Coordination

10.1 The Eight Source Stack

Every engagement reporting layer pulls from up to eight data sources: Google Search Console (impressions, clicks, position, queries), Google Analytics 4 (sessions, conversions, engagement, attribution), Google Business Profile API where local applies (views, calls, directions), Ahrefs (backlinks, ranking history, competitor data), Semrush as Ahrefs alternative (keyword position, share of voice), Bing Webmaster Tools (Bing organic, Copilot signals), AI citation monitor (Profound, Otterly, etc. for cross engine citation), and server logs from nginx on Bubbles (bot crawl frequency). Most engagements use 5 to 7. Enterprise engagements use all 8. Solo and small business engagements use the first 4 plus manual sampling for AI surface.

10.2 The ETL Pipeline on Bubbles

The unified Postgres warehouse on Bubbles aggregates all sources nightly. Architecture: source APIs (GSC, GA4, Ahrefs, Semrush, Bing, AI monitor) flow through Python ETL scripts (cron 02:00 daily) into Postgres on Bubbles, then to Metabase dashboards and Pandoc reports. The Python ETL scripts live at /home/user/etl/. Each source has a dedicated script that pulls the last 30 days of data, normalizes to the warehouse schema, and upserts into the corresponding Postgres table. Failures send a notification to the agency Gmail. The Postgres schema normalizes dimensions across sources with a unified long format that makes cross source aggregation feasible.

10.3 The Unified Postgres Schema

Three core tables. daily_metrics carries client_id, source, metric_name, metric_value, metric_date, three dimension columns, and ingested_at, with composite primary key across client, source, metric, date, and dimensions. ai_citation_samples carries client_id, query, engine, sampled_at, cited boolean, brand_mentioned boolean, cited_url, and notes. monthly_kpi_scoreboard carries client_id, report_month, kpi_name, current/baseline/target values, and status. Long format accommodates new metrics without schema changes. The Python ETL writes one row per metric per day per dimension combination. Metabase queries against the warehouse for dashboards. Pandoc reports query against the warehouse via Python at generation time.

10.4 Daily Refresh Cadence

The pipeline refreshes daily at 02:00 Central. The freshness contract: by 06:00 every morning, the warehouse contains data through end of day previous day for all sources. Weekly reports generated Tuesday morning have data through Sunday. Monthly reports generated first Wednesday have data through end of previous month. Cron entries on Bubbles run run-all-sources.sh at 02:00 and freshness-check.sh at 06:00. Missing source triggers an email alert. The agency lead reviews before 08:00.

10.5 The API Rate Limit Discipline

GSC, GA4, Ahrefs, Semrush all rate limit. Scripts respect quotas (GSC 1200 per day per property, GA4 Data API 50,000 tokens per day, Ahrefs throttled to 1 request per second, Bing Webmaster 1000 per day per site), implement exponential backoff on 429 responses, retry failed fetches next morning. The pipeline is idempotent: re running for the same date does not double count.

10.6 The Server Log Layer

The nginx access log on Bubbles contains the ground truth for bot crawl activity per client site at /var/log/nginx/[domain].access.log. A nightly bash script iterates over the AI bot user agents (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot, Applebot, bingbot), greps yesterday's date and the bot string, emits CSV rows of domain,bot,date,count to /home/user/etl/bot-frequency.csv. The CSV upserts into the warehouse daily. The bot frequency trend feeds the technical health section of monthly reports. Sudden drops in Googlebot or Google-Extended frequency surface as alerts.

11. Visualization Standards

11.1 The Five Chart Types

Every chart in every report falls into one of five types. Line chart for trends. Time on x axis, metric on y. Use for sessions over 12 months, citation count over 13 weeks. Default chart type. Bar chart for comparison. Categorical x axis, metric y. Use for top 10 pages, top 10 queries, conversion by channel. Stacked bar for composition over time. Time x, value y, stacked components per category. Use for channel mix evolution, brand vs non brand split, AI citation breakdown by engine. Sparkline for at a glance KPI cards. Tiny line chart embedded in KPI scoreboards. Heatmap for geographic or temporal density. Two dimensional grid with color intensity. Use for local pack ranking heat map, hour of day conversion concentration. Five types used consistently. Nothing else.

11.2 The No Pie Chart Rule

Pie charts are forbidden. Pie charts encode value as angle which the human eye cannot read accurately. A bar chart with the same data is always more readable. If a report includes a pie chart, the agency lead reviews the visualization choice and almost always replaces it with a bar chart or stacked bar.

11.3 The Always Rolling 12 Month Baseline

Every trend chart uses a rolling 12 month baseline by default. 12 months removes seasonality, accommodates year over year comparison, and shows enough context to spot structural change. Exceptions: weekly reports use 13 week trends (one quarter rolling). Quarterly reports use 8 quarter trends (two year rolling) for the strategic deliverable.

11.4 Color Coding for Client Brand

Each client engagement has a defined color palette at /home/user/clients/[clientname]/reports/brand-palette.yaml carrying primary, secondary, and accent hex values plus neutral dark and light plus comparison gray plus status green, red, and amber. The primary brand color appears in the headline metric. Secondary colors appear in supporting series. Comparison series (competitor data, baseline, target) appear in muted neutrals. Python matplotlib or plotly chart generation reads the palette and applies consistently. The result: every chart in every report for the client uses the same colors, signaling continuity.

11.5 Chart Annotation Discipline

Every chart in a report carries a title, axis labels, date range, comparison period, and a one sentence caption explaining what the chart shows. Example caption: "Organic non brand sessions over the trailing 12 months. April 2026 is up 23 percent year over year, driven by the buyer guide cluster published in Q4 2025." The caption converts a chart from a visualization into a story element.

11.6 The Matplotlib and Plotly Choice

Charts in reports are generated by Python. Matplotlib for static PDF report charts (high resolution PNG, embedded in Pandoc markdown via image reference). Plotly for interactive dashboard charts (HTML or JSON for Metabase). Both libraries read the same data from Postgres via pandas. The chart generation code lives at /home/user/etl/charts/.

11.7 The Accessibility Baseline

Charts must be readable by colorblind users. The palette excludes red green only distinctions. Comparison series use shape or pattern variation in addition to color. Text labels appear on data points where space permits. Charts that fail the colorblind safe check get regenerated with adjusted palette.

12. Narrative Voice and Tone

12.1 The Report Is a Recommendation Document

The report is not a data dump. It is a recommendation document with data supporting. Every page leads with a claim. Subsequent sentences support the claim with data. A page that opens with a chart and lets the reader interpret has abandoned the narrative responsibility. The agency interprets the data. Without the interpretation the agency offers no value beyond what a dashboard already provides.

12.2 The First Sentence Claim Pattern

Every page in every report opens with a one sentence claim. The claim is the takeaway the page supports.

Strong opening claims: "Organic traffic grew 23 percent year over year, driven by the buyer guide cluster published in Q4 2025." "AI Overview citation share rose from 12 percent to 38 percent across priority queries, putting the site ahead of the next named competitor." "The conversion path data shows organic search assists 4.2 conversions for every conversion it closes, surfacing the upstream role of the engagement." "Technical health is stable with the exception of a Core Web Vitals regression on the product detail template requiring response by end of week."

Weak claims to avoid: "This month we did a lot of work on the site." "Here is the traffic chart." "Performance was solid this month." If the opening sentence is not specific enough to draft a competitor's headline against, rewrite.

12.3 Avoid Jargon and Spell Out Abbreviations

Reports addressed to non technical audiences avoid jargon by default. The audience determines the language. Abbreviations are spelled out on first use: E-E-A-T is "experience, expertise, authoritativeness, trustworthiness (E-E-A-T)" first, then E-E-A-T thereafter. SQRG is "Search Quality Rater Guidelines (SQRG)" first. MMM is "marketing mix modeling (MMM)" first. DDA is "data driven attribution (DDA)" first. The SEO manager cut can skip spell out for vocabulary the manager uses daily.

12.4 Specificity Beats Generality

Strong narrative writing uses specific numbers, named pages, named queries, named events. Weak writing uses generalities. "Traffic increased significantly" becomes "Organic traffic increased 23 percent (from 18,400 to 22,600 monthly sessions)." "Rankings improved on many keywords" becomes "Rankings improved on 47 target keywords, including primary money queries 'enrolled agent bentonville' and 'quarterly estimated taxes 2026'." "Schema implementation helped" becomes "Schema implementation on the 23 priority pages added Article author and reviewer credit, completing the YMYL requirement and lifting AI Overview citation count from 6 to 14." The specific version is longer. Length is acceptable. The specific version is more credible.

12.5 Honesty in Reporting Negative News

Reports include negative news honestly. Trust is built on consistent honest reporting through good and bad periods. Hiding bad news destroys trust when the client discovers independently. The pattern: lead with the issue and do not bury it, take accountability where appropriate, explain the root cause analysis, outline the remediation plan, set expectation for recovery timeline.

Example: "Organic conversions declined 12 percent this month. Root cause: the checkout flow regression introduced in the May 3 deployment routed a subset of users to a broken cart page. The issue was identified May 8 via the GA4 alert and resolved May 9. Recovery expected by end of May. Going forward we have added a checkout completion synthetic monitor (one transaction per hour, alerting on 2 consecutive failures) to catch this pattern within 2 hours rather than 5 days." The framing acknowledges, explains, remediates, and prevents recurrence. The client trusts the agency more after reading that paragraph than after a report that omitted the regression.

12.6 Brevity Over Padding

Concise writing beats padded writing. Each sentence carries meaning. One topic per paragraph, 60 to 120 word paragraphs typically, bullet lists for parallel items and prose for flowing analysis, no throat clearing, no restating the obvious. Cross reference framework-brandvoice.md for the agency voice that should appear in every report.

13. Reporting Cadence Calendar

13.1 The Three Standard Cadences

Three cadences cover the vast majority of engagements. Each has a fixed delivery day. Weekly: Tuesday by 5pm Central. Applies to enterprise tier, active campaign engagements, project engagements in flight. The 5pm Tuesday slot lets the agency review Monday's data on Tuesday morning, generate and review by Tuesday afternoon, send by 5pm. Monthly: First Wednesday of the month by noon Central. Applies to all retainer tiers above starter. The first Wednesday gives the agency three business days after month end to aggregate data and write the narrative. Quarterly: Third Wednesday of the month following quarter end by noon Central. Applies to all retainer tiers. The third Wednesday gives the agency three weeks after quarter end for the deeper analysis.

13.2 The Annual Cadence

The annual report applies to retainer engagements that have crossed 12 months. The annual is a deeper version of the quarterly with year over year structural analysis, lessons learned synthesis, strategic plan for the next year, and pricing or scope review. The annual delivers third Wednesday of January for engagements aligned to calendar year. For engagements aligned to fiscal year, the annual delivers third Wednesday of the month following fiscal year end.

13.3 The Auto Reminder System

Cadence enforcement depends on automation. Manual tracking of deadlines fails. The Bubbles cron system handles reminders via /etc/cron.d/reporting-reminders: weekly reminder at 09:00 every Tuesday, monthly reminder at 09:00 the first Monday of the month, quarterly reminder at 09:00 the third Monday of January, April, July, and October. The reminders email the agency lead with the client list, due dates, and template links. The reminders fire 2 to 3 business days before delivery deadline, giving time for narrative writing and review.

13.4 The Delivered On Time 100 Percent KPI

The agency's own KPI: every report delivered on time, every cadence, every client. Tracked monthly. Missed deliveries trigger root cause analysis. Repeated misses trigger workflow review. The 100 percent KPI matters because client perception of agency reliability shapes renewal. A retainer with one late report per year is not in trouble. Three late reports in a quarter puts renewal at risk. The cadence calendar is a contract with the client.

13.5 The Acceleration Allowance

Some clients prefer accelerated cadence during campaign launches, product releases, or competitive shifts. The framework allows acceleration without changing the standard cadence: standard weekly stays weekly with an additional mid week update during launch periods, standard monthly stays monthly with an additional 2 week update during major refresh cycles, standard quarterly stays quarterly with an additional strategic review when a major algorithm update lands. Pricing for acceleration follows framework-pricing.md tier structure.

13.6 Renewal Conversation Timing

The renewal conversation references the most recent quarterly report. Renewal discussions happen approximately 30 days before contract end. The quarterly preceding renewal must include explicit renewal material: trajectory of the engagement, recommended scope for the next term, pricing if changing, strategic priorities. The renewal quarterly is the most carefully written report of the engagement. The agency lead writes the narrative personally. It is the artifact the client uses to decide.

14. Bubbles Hosted Reporting Stack

14.1 The Self Hosting Posture

The reporting stack is fully self hosted on the Bubbles Debian server at public IP 169.155.162.118. No third party CDN, no third party proxy, no edge intermediary. Data sovereignty for client reporting, no third party SaaS dependency, full control over uptime and data residency. When a client asks where their reporting data lives, the answer is "on a server we control in our office, not on a third party platform."

14.2 The Infrastructure Layer

The Bubbles server runs Debian 12 amd64 with 16GB RAM, nginx for reverse proxy, Postgres 15 for the warehouse, Python 3.11 for ETL and chart generation, Pandoc 3.1 with xelatex for PDF rendering, Metabase 0.50 for dashboards (or Grafana 10), Gmail SMTP for email, and Nextcloud 28 for shared folders. The services bind to localhost. nginx reverse proxies HTTPS traffic to the appropriate service. TLS certificates from Let's Encrypt via certbot, renewed by cron.

14.3 The Data Pipeline Layer

The data pipeline lives at /home/user/etl/ with directories for sources/ (per source pull scripts), transforms/ (normalize, deduplicate, aggregate), load/ (postgres loader and schema), charts/ (chart generators per type), reports/ (weekly, monthly, quarterly generators), delivery/ (gmail and nextcloud), and logs/. The orchestration entry point is run-all-sources.sh. The pipeline runs nightly at 02:00 Central via cron. Each source script is independent and idempotent. Failure in one source does not block others. Logs accumulate with daily rotation.

14.4 The Report Generation Layer

Report generation is a Python and Pandoc pipeline. The bash entry point at /home/user/etl/reports/generate-monthly.sh takes CLIENT_ID and REPORT_MONTH, runs monthly_generate.py to produce matplotlib charts, runs fill_template.py to merge data into the markdown skeleton, then calls pandoc --pdf-engine=xelatex --template=monthly-template.latex to render the PDF. A symlink updates latest.pdf for the Nextcloud share. The script runs in approximately 90 seconds per client. The agency lead reviews the markdown before triggering PDF rendering.

14.5 The Delivery Layer

Two delivery channels per client. Gmail SMTP delivery. Python script using google-auth-oauthlib and the Gmail API. Attaches the PDF, sends to the recipient list, BCCs the agency archive address. Email body includes the executive summary paragraph plus a link to the Metabase dashboard. Nextcloud shared folder delivery. Python script uploads to a shared folder per client. The client has read access via a link sent at engagement start. The folder structure mirrors /home/user/clients/[clientname]/reports/. Both channels run after agency lead approval.

14.6 The Metabase Dashboard Layer

Metabase runs on Bubbles at localhost:3000, reverse proxied by nginx. Per client dashboards live in dedicated collections permissioned so clients see only their own data. Structure: page 1 executive summary with north star and KPI scoreboard, page 2 traffic with rolling 12 month sessions and channel mix, page 3 conversions with three model comparison and brand vs non brand split, page 4 search performance with GSC top queries and position distribution, page 5 AI surface with citation count per engine and brand mention rate, page 6 local where applicable, page 7 links. The dashboard refreshes nightly from Postgres. Clients with the dashboard URL can check anytime. The dashboard answers "what is the data right now." The report answers "what does the data mean and what should we do."

14.7 The Grafana Alternative

Some clients prefer Grafana over Metabase. Grafana excels at time series, threshold alerting, and devops integration. Metabase excels at business KPI dashboards and SQL exploration. The framework supports either. The Postgres warehouse is the shared layer.

14.8 The Backup and Archive Layer

Reports archive on Bubbles in /home/user/clients/[clientname]/reports/ with per cadence directories containing dated subfolders for markdown source, PDF output, chart PNGs, plus latest.pdf symlinks for the Nextcloud share. The archive is included in the daily Bubbles backup. The external 4.5TB drive at /mnt/storage receives a weekly backup of /home/user/clients/. Off site backup goes to encrypted Backblaze B2 for any client requiring data residency redundancy. The archive is searchable. The agency lead can pull up any historical report instantly, supporting renewal conversations where the client wants to compare current performance against the engagement start state.

14.9 The Self Hosted Posture

The hosting stack uses no third party CDN or proxy of any kind. The reasoning: data sovereignty so client reporting data never transits a third party platform, cost since third party CDN adds monthly fees, simplicity since fewer moving parts means fewer failure modes, vendor independence since a third party outage does not affect client reporting delivery. The tradeoff: Bubbles is the single point of failure. Mitigation: external storage backup at /mnt/storage, Backblaze B2 off site backup, and a cold standby pattern where the framework can be redeployed to a new Debian server within 4 hours. The 4 hour recovery time is acceptable for weekly to quarterly cadence reporting.

14.10 The Audit Rubric for the Stack

Score 13. World class stack: 12 or higher with R12 and R13 mandatory.

End of Framework Document

Document version: 2.0
Last updated: 2026-05-14
Maintained by: ThatDeveloperGuy

Client reporting is the visible artifact that determines retainer renewal. The framework specifies the architecture that delivers weekly, monthly, and quarterly reports across four pillars of visibility (SEO, AEO, AIO, GEO), tailored to four audience archetypes, backed by a self hosted data pipeline on Bubbles, free of third party CDN or proxy dependency. The discipline is selection plus narrative plus action. Apply after framework-clientonboarding.md and framework-pricing.md.

Companions

• framework-attribution.md, SEO attribution modeling and conversion path
• framework-ga4.md, GA4 platform install and event basics
• framework-gscanalysis.md, GSC analysis and organic query data
• framework-initialaudit.md, initial engagement audit
• framework-ongoingaudit.md, ongoing audit cadence
• framework-contentaudit.md, content portfolio audit
• framework-clientonboarding.md, engagement start and reporting setup
• framework-aicitations.md, broader AI citation across engines
• framework-aioverviews.md, Google AI Overview citation
• framework-multiengine-tradeoffs.md, cross engine tradeoff matrix
• framework-linkbuilding.md, link portfolio strategy
• framework-brandvoice.md, agency narrative tone and voice
• framework-pricing.md, tier pricing and reporting cadence alignment

From the ThatDevPro Engine Optimization framework library. Studio: ThatDevPro (SDVOSB veteran-owned web + AI engineering). Sister property: ThatDeveloperGuy. Source: https://www.thatdevpro.com/insights/framework-reporting/.