From 672d441e5be60633bd1cecf2518b1e5ac37d0836 Mon Sep 17 00:00:00 2001 From: baixiangcpp Date: Sun, 21 Jun 2026 10:22:08 -0700 Subject: [PATCH] [BF-032] Add growth dashboard runbook --- docs/growth/dashboard-runbook.md | 134 +++++++++++++++++++++++++++++++ docs/growth/seo-monitoring.md | 68 ++++++++++++++++ docs/privacy/analytics-policy.md | 90 +++++++++++++++++++++ 3 files changed, 292 insertions(+) create mode 100644 docs/growth/dashboard-runbook.md create mode 100644 docs/growth/seo-monitoring.md create mode 100644 docs/privacy/analytics-policy.md diff --git a/docs/growth/dashboard-runbook.md b/docs/growth/dashboard-runbook.md new file mode 100644 index 00000000..924e538c --- /dev/null +++ b/docs/growth/dashboard-runbook.md @@ -0,0 +1,134 @@ +# Growth Dashboard Runbook + +This runbook defines the operating dashboard for byteflow.tools after SEO, privacy, PWA, and tool-discovery changes ship. It is an internal operations document, not user-facing product copy. + +## Goals + +- Track whether users can find the right local-first tool and complete useful actions. +- Monitor indexing, crawl health, metadata quality, and page performance after releases. +- Keep analytics privacy-safe: aggregate signals only, no tool payloads, no user identifiers, and no undisclosed external requests. + +## Required Access + +The dashboard owner needs explicit access to these sources before using the checklist: + +- Google Search Console property for `https://byteflow.tools/`. +- Hosting/CDN dashboard for deployment, redirects, 404s, cache, and aggregate traffic. +- GitHub repository access for issues, PRs, release notes, and CI history. +- PageSpeed Insights or CrUX for aggregate Core Web Vitals. +- Privacy-safe analytics provider only if it is enabled by configuration and matches the allowlist in `docs/privacy/analytics-policy.md`. + +Do not use data exports from sources that require cookies, user-level tracking IDs, session replay, advertising profiles, fingerprinting, or raw request bodies. + +## North Star Metrics + +| Metric | Definition | Source | Notes | +| --- | --- | --- | --- | +| Monthly tool reach | Monthly aggregate count of tool page loads, measured only if a privacy-safe aggregate provider exists. | Privacy-safe analytics | Must not rely on cookies, user IDs, fingerprints, or session IDs. | +| Successful tool operations | Count of allowlisted `tool_action`, `copy_output`, and `download_output` events. | Privacy-safe analytics | Event params must stay coarse: tool ID, action type, locale, source page, and size bucket only. | +| Indexed useful pages | Valid indexed locale home, category, tool, workflow, and article pages. | Google Search Console | Track by route family and locale, not by user. | +| Search discovery quality | Clicks, impressions, CTR, and average position for tool and workflow query clusters. | Google Search Console | GSC query data is aggregate search demand, not internal search text. | + +## SEO Dashboard + +Track these weekly by route family: root, locale home, all tools, category hubs, tools, workflows, articles, compare pages, alternatives, fix pages, and static trust pages. + +| Metric | What To Watch | Action Threshold | +| --- | --- | --- | +| Indexed pages | Valid indexed URLs by route family and locale. | Any unexpected drop after a release. | +| Crawled currently not indexed | Pages Google crawled but did not index. | Rising count for tools, workflows, or localized pages. | +| Discovered currently not indexed | Pages found but not crawled. | Increasing count for sitemap-backed pages. | +| Duplicate without user-selected canonical | Canonical confusion. | Any core route hit. | +| Alternate page with proper canonical | Expected localized alternates. | Investigate if canonical points to the wrong locale. | +| 404 / soft 404 | Broken links, stale sitemap entries, or removed tools. | Any sitemap URL returning 404. | +| Redirect errors | Legacy route map or hosting redirect regressions. | Any redirect loop or wrong target. | +| Sitemap submitted / indexed | Sitemap acceptance and URL coverage. | Submitted count diverges from expected generated routes. | +| CTR by query cluster | Snippet/title intent match. | CTR drop greater than 20% week over week with stable position. | +| Average position | Ranking movement by cluster. | Position drop greater than 3 places for core tool clusters. | +| Core Web Vitals | LCP, INP, CLS by template. | Any route family leaving good status. | + +## Product Dashboard + +Use only allowlisted, aggregate events. Do not add raw input, output, query text, file information, or user identifiers. + +| Event | Allowed Dimensions | Purpose | +| --- | --- | --- | +| `tool_loaded` | tool ID, locale, source page | Understand tool discovery and route health. | +| `tool_action` | tool ID, action type, locale, input size bucket, source page | Count successful local tool actions without payloads. | +| `copy_output` | tool ID, action type, locale, source page | Measure completion of copy workflows. | +| `download_output` | tool ID, action type, locale, size bucket, source page | Measure export workflows without file names or content. | +| `search_performed` | locale, query length bucket, result count, source page | Track search usefulness without query text. | +| `related_tool_click` | source tool ID, related tool ID, locale, source page | Measure workflow navigation. | +| `pwa_installed` | locale, platform bucket, source page | Track successful installs. | + +If a desired event is not in the current analytics taxonomy, open a privacy review issue before adding it. + +## Weekly Checklist + +1. Open Google Search Console coverage and compare indexed, crawled-not-indexed, duplicate, and 404 counts with the previous week. +2. Confirm the submitted sitemap is accepted and the submitted URL count matches expected generated route families. +3. Review the top query clusters for each core category: JSON, JWT, Base64, hash, URL encoding, regex, Markdown, image tools, OpenAPI, and security headers. +4. Find pages with CTR drops greater than 20% while average position is stable; create content or metadata follow-up issues. +5. Review pages with impression growth but low CTR; check title, description, heading, and snippet intent. +6. Check legacy redirects and 404s; any sitemap URL returning 404 becomes a P1 routing issue. +7. Review Core Web Vitals by route family; create performance issues for route templates that leave good status. +8. Check privacy-safe product events for tool load to action completion by route family. +9. Confirm internal search metrics still avoid query text and only report length bucket, result count, locale, and source page. +10. Record findings in the weekly dashboard note with links to new issues. + +## Monthly Checklist + +1. Group GSC queries into clusters: direct tool names, local/privacy intent, alternatives, fix/how-to intent, and workflow intent. +2. Compare locale performance for `en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `de`, and `fr`; create i18n content issues where a locale underperforms with real impressions. +3. Review pages with high impressions and low action completion; check whether the tool surface matches the search intent. +4. Review content decay: pages losing impressions for three consecutive weeks should get a content refresh issue. +5. Review competitor and alternative-page queries only from aggregate GSC data; do not scrape or store user-level behavior. +6. Check release notes and CI failures for recurring SEO, PWA, sitemap, hreflang, or metadata regressions. +7. Reconfirm the analytics provider, if enabled, remains cookie-free and does not add user identifiers or new external requests. + +## Post-Release Monitoring + +Run this flow for every release that changes routes, sitemap, metadata, PWA, search, analytics, privacy copy, or tool templates: + +1. Confirm CI passed: lint, tests, validate, build, and required smoke tests. +2. Compare generated sitemap URL counts with the previous release. +3. Spot-check `/`, `/en`, `/zh-CN`, `/en/all-tools`, `/en/json-formatter`, `/en/jwt-decoder`, `/en/base64-encode-decode`, and `/en/trust-center`. +4. In GSC, inspect a sample of changed URLs after deployment. +5. Check hosting/CDN aggregate 404s and redirect errors after 24 hours. +6. Review privacy-safe event volume for sudden drops in tool load, tool action, copy, download, search click, and PWA install signals. +7. Create issues for regressions instead of making undocumented dashboard-only fixes. + +## Feedback Loop + +Every dashboard finding must become one of these outcomes: + +- No action: documented as expected behavior with evidence. +- New GitHub issue: include route family, locale, metric, date range, suspected cause, and acceptance criteria. +- Existing issue update: add dashboard evidence to the relevant BF or follow-up issue. +- Content refresh: identify the exact page, intent mismatch, and required localized copy scope. +- Privacy review: required before adding any event, provider, field, cookie, user identifier, or external request. + +## Issue Template For Findings + +```markdown +## Dashboard Finding +- Date range: +- Source: +- Route family: +- Locale(s): +- Metric: +- Current value: +- Previous value: +- Suspected cause: + +## Privacy Check +- [ ] Does not include tool input/output +- [ ] Does not include JWTs, tokens, secrets, log bodies, file names, file contents, image contents, hashes, or full URLs +- [ ] Does not require cookies, user IDs, session IDs, or fingerprinting + +## Proposed Action +- ... + +## Acceptance Criteria +- ... +``` diff --git a/docs/growth/seo-monitoring.md b/docs/growth/seo-monitoring.md new file mode 100644 index 00000000..37e52518 --- /dev/null +++ b/docs/growth/seo-monitoring.md @@ -0,0 +1,68 @@ +# SEO Monitoring Checklist + +This checklist turns Google Search Console and build-gate output into repeatable SEO operations. It must be used with the privacy limits in `docs/privacy/analytics-policy.md`. + +## Query Clusters + +Track aggregate GSC queries in these clusters: + +- Direct tool names: JSON formatter, JWT decoder, Base64 decode, URL encode, hash generator, regex tester. +- Local/privacy intent: local JSON formatter, browser JWT decoder, offline developer tools, privacy-first tools. +- Fix intent: JSON trailing comma, invalid Base64 length, URL malformed percent sequence. +- Workflow intent: API payload cleanup, security token review, log scrub before sharing, image social export. +- Comparison and alternative intent: jwt.io alternative, jsonlint alternative, Byteflow vs CyberChef. +- International intent: localized variants for the supported locales when GSC has enough aggregate data. + +Do not combine GSC query data with user-level analytics, cookies, session IDs, or internal search text. + +## URL Families + +Review SEO health by family, not by individual ad hoc URLs: + +| Family | Examples | Checks | +| --- | --- | --- | +| Root and locale home | `/`, `/en`, `/zh-CN` | x-default, localized title, category links, no thin root page. | +| Tool pages | `/en/json-formatter` | self canonical, all hreflang alternates, JSON-LD, unique metadata. | +| Category hubs | `/en/data-code-formats` | unique intro, linked tools, sitemap inclusion. | +| Workflow hubs | `/en/workflows/...` or equivalent route | How-to intent, related tools, localized metadata. | +| Content pages | how-to, fix, compare, alternatives | fair claims, unique title/description, Trust Center link. | +| Trust pages | privacy, about, install app, trust center | consistent privacy language and disclosed external requests. | + +## Weekly GSC Review + +1. Coverage: note valid, indexed, excluded, 404, soft 404, redirect error, duplicate, crawled-not-indexed, and discovered-not-indexed counts. +2. Sitemap: confirm submitted URL count and last read status. +3. Pages: sort by clicks lost week over week and flag drops not explained by seasonality or release changes. +4. Queries: group top queries into the clusters above and record changes in impressions, CTR, and average position. +5. Locales: compare the same route family across all supported locales where data is available. +6. Enhancements: check breadcrumbs, FAQ schema, software/app schema, and Core Web Vitals reports. +7. Actions: create issues for unexpected deltas with acceptance criteria and privacy-safe evidence only. + +## Monthly Content Review + +1. Prioritize pages with high impressions, low CTR, and stable or improving average position. +2. Refresh pages with declining impressions for three consecutive weeks. +3. Merge, redirect, or improve pages that remain crawled-not-indexed after two monthly reviews. +4. Review localized pages together; do not improve only English body copy while leaving other locales generic. +5. Check whether route metadata, headings, FAQ, examples, and related tools still match the page intent. + +## Technical SEO Regression Checks + +Run or verify these before using dashboard results to plan content changes: + +```bash +npm run check:canonical +npm run check:hreflang +npm run check:sitemap-lastmod +npm run check:metadata-localization +npm run check:jsonld-structured-data +npm run check:rendered-i18n-copy +``` + +If a technical gate fails, fix the technical issue before interpreting traffic changes as content performance. + +## Escalation + +- P1: sitemap URL returns 404, canonical points to the wrong locale, core route has `noindex`, or privacy/trust copy contradicts current behavior. +- P2: CTR drop greater than 20% for a stable-position core tool page, crawled-not-indexed increase for generated pages, or Core Web Vitals regression. +- P3: new query cluster opportunity, low-impression content refresh, or title/description experimentation. diff --git a/docs/privacy/analytics-policy.md b/docs/privacy/analytics-policy.md new file mode 100644 index 00000000..ddbab17e --- /dev/null +++ b/docs/privacy/analytics-policy.md @@ -0,0 +1,90 @@ +# Privacy-Safe Analytics Policy + +This policy defines what operational dashboards may collect and what they must never collect. It applies to product analytics, dashboard exports, GSC review notes, screenshots, and issue evidence. + +## Allowed Aggregate Signals + +Analytics may use only allowlisted aggregate events and coarse dimensions: + +- Event name. +- Tool ID or route family. +- Locale. +- Source page or template family. +- Action type from a fixed list. +- Result count. +- Size bucket, not exact content. +- Query length bucket, not query text. +- PWA install state or platform bucket. + +Any new field requires a privacy review issue before implementation. + +## Prohibited Data + +Never collect, store, export, paste into issues, or send to a provider: + +- Tool input. +- Tool output. +- JWTs, tokens, passwords, API keys, private keys, certificates with private material, or secrets. +- Payloads, request bodies, response bodies, logs, stack traces, HAR bodies, environment dumps, or configuration files. +- File names, file paths, file contents, image contents, document contents, or generated output containing original content. +- Raw internal search query text. +- Full URLs, URL query strings, fragments, or user-provided URLs. +- Hash values derived from user content. +- Email addresses, IP addresses, user IDs, account IDs, session IDs, cookies, device IDs, or fingerprints. +- Session replay, screen recordings, keystrokes, clipboard contents, or form field values. + +## Provider Requirements + +An analytics provider may be enabled only when it satisfies all requirements: + +- Cookie-free by default. +- No user-level identifier. +- No fingerprinting. +- No session replay. +- No advertising or retargeting use. +- No tool input/output capture. +- Configurable by environment variable or build-time setting. +- Disclosed in Privacy Policy and Trust Center before launch. +- Covered by tests or gates that prevent forbidden fields. + +If any requirement is uncertain, do not enable the provider. Mark the PR `needs-human-review`. + +## Search Data Rules + +There are two different search sources: + +- Google Search Console queries are aggregate external search demand and may be reviewed in dashboard summaries. +- Byteflow internal search and command palette queries must not collect query text. Only query length bucket, result count, locale, and source page are allowed. + +Never join GSC query data with user-level analytics or internal search behavior. + +## File And Tool Data Rules + +File and tool workflows may report only safe buckets: + +- Size bucket instead of exact size when needed. +- Tool ID instead of file name. +- Action type instead of raw command or payload. +- Success/failure count without error payloads. + +Do not log file names, MIME-derived personal names, file hashes, previews, extracted text, image pixels, or generated output. + +## Dashboard Export Rules + +Dashboard exports may contain aggregate rows only. Before sharing an export in an issue or PR: + +1. Remove any raw URL query string. +2. Remove any free-text query from internal search sources. +3. Remove user, session, cookie, IP, device, and account columns. +4. Remove file names and full referrers. +5. Keep only date range, route family, locale, metric name, aggregate value, and dashboard source. + +## Review Checklist + +- [ ] The metric is aggregate. +- [ ] The field is allowlisted. +- [ ] No raw input or output appears in the event, screenshot, log, or issue. +- [ ] No identifier can track a person or browser across time. +- [ ] The provider is disclosed. +- [ ] Privacy Policy and Trust Center remain consistent. +- [ ] Tests or gates cover the field before merge.