---
name: website-analytics-bootstrap
description: Set up a website's first SEO analytics loop end-to-end: persistent SerpBear rank tracking, Google Search Console, seeded keywords, read-only technical audits, and Telegram alerts on a local host or NAS.
license: MIT
allowed-tools: Bash, Read, Write, Edit
compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires network access, a reachable deployment host, and owner-provided Search Console and alert credentials.
metadata:
  targets: [_source-only]
  author: Oleg Koval
  tags:
    - seo
    - analytics
    - google-search-console
    - serpbear
    - nas
    - telegram
    - monitoring
---

> 🤖 *Auto-generated by **weekly-pattern-learner** · reusable first-run website analytics onboarding workflow derived from a validated local/NAS setup pattern*

# website-analytics-bootstrap

Build a repeatable, observable SEO analytics loop for a website without making unapproved content or code changes.

## Outcome

At completion, the operator has:

- persistent rank tracking for the target domain and a small, evidence-based keyword seed set;
- Google Search Console connected to the correct property and verified with a real API query;
- daily rank/Search Console refreshes;
- a read-only technical audit for key pages, `robots.txt`, and `sitemap.xml`;
- Telegram alerts for failures and a weekly health summary;
- saved reports, raw HTTP responses, logs, schedules, credentials locations, and a concise handoff.

This skill automates observation and reporting. Website edits, SEO copy changes, indexing submissions, and deployments remain approval-gated.

## First-run questions

Ask at most three questions only when the answer cannot be discovered safely:

1. What is the canonical website URL and which host/NAS should run the service?
2. Which Google Search Console property should be used: Domain or URL-prefix?
3. Should alerts use an existing Telegram bot/chat, or should the owner create one?

Never ask the user to paste private keys, bot tokens, passwords, or app passwords into chat. Accept them through the target UI, a secure secret store, or a protected host file.

## Workflow

### 1. Inspect before changing anything

- Read project-local agent instructions and inspect `.claude/scripts/` before making HTTP tooling.
- Check the current repository, remote, dirty worktree, deployment files, and existing analytics/monitoring integrations.
- Resolve the host using read-only checks. Prefer the reachable VPN/Tailscale address when the LAN address is unavailable.
- Check Docker/Container Manager, Node, Python/uv, systemd, and the host's supported scheduler.
- Preserve unrelated worktree changes. Do not reset, delete, or overwrite broad directories.
- Check whether an existing skill already covers post-connection GSC indexing analysis; use `search-console-indexing-audit` for that later phase instead of duplicating it.

### 2. Choose the deployment path

Prefer a persistent container when Docker is healthy. If Docker is unavailable or broken, use the supported native runtime as a deliberate fallback:

- pin the application version used for the setup;
- store application source separately from persistent data;
- set a non-default port and an explicit application URL;
- run under a least-privilege service user;
- keep secrets in a protected environment file, never in source, shell history, logs, or reports;
- build and run the production application before configuring automation.

Before applying any persistent setup, credential or permission changes, enabling the scheduler, or performing Telegram delivery or test actions, require explicit owner confirmation for that specific action. If confirmation is absent, default to a no-op and do not perform the action. Record the confirmation outcome alongside the actual path, runtime, port, service user, and rollback/restart command.

### 3. Configure SerpBear

- Create or verify the admin account without printing the password.
- Configure a supported scraper/proxy such as SerpApi through the UI or protected settings.
- Set daily scraping with a conservative strategy and retry behavior appropriate to API quotas.
- Add the canonical domain exactly once.
- Seed 8–12 phrases from visible services, locations, and positioning. Start with a mix of branded, service, and location queries; do not invent volume or ranking claims.
- Verify at least one real rank result and record the initial baseline.

Keyword seed examples should be generated from the target site's actual language, for example `{service} photographer`, `{service} {city}`, and the brand name. Expand the list only after Search Console supplies real queries or the owner confirms the market.

### 4. Connect Google Search Console

Use a Google Cloud service account created for this integration:

1. Create a JSON key in the service account's **Keys** tab. Keyless authentication is preferred when supported; otherwise document owner-approved rotation schedule, replacement procedure in SerpBear, and immediate disable/delete revocation steps for compromised or retired JSON keys.
2. Enable the Google Search Console API in that same Cloud project.
3. Add the service account's `client_email` as a **Restricted** user (with read-only access) on the exact Search Console property, retaining the existing `webmasters.readonly` scope and query-validation steps.
4. Enter `client_email` and the JSON `private_key` into SerpBear through its protected settings UI.
5. Match the property type precisely:
   - Domain property → `sc-domain:example.com`.
   - URL-prefix property → configure the exact URL, including protocol and trailing slash when required.
6. Trigger a real query and inspect the response. A saved credential flag is not proof of connectivity.

Diagnose in this order:

- `403 accessNotConfigured` → enable the Search Console API;
- `403 Forbidden` → verify the property type and service-account user on that exact property;
- key/decoder errors → verify the full PEM value and newline handling;
- empty rows with a successful request → report “connected, no data yet,” not a failure.

### 5. Add the read-only technical audit

Use a reusable project-local script or the target runtime's equivalent for repeated HTTP checks. Save every raw response and reproduction metadata before analysis. At minimum check:

- `/`, `/work` or the primary portfolio route;
- the main service/booking route;
- `/about` and `/contact`;
- `/robots.txt`;
- `/sitemap.xml`.

For HTML pages, inspect status, title, meta description, canonical, and accidental `noindex`. For robots and sitemap, inspect status, content type, parseability, and sitemap URL count. Do not infer indexation from a 200 response; use Search Console for index status.

Before saving artifacts, sanitize HTTP response headers and body fields by removing session-bearing Set-Cookie values and personal data. Restrict artifact file permissions to owner-read-write only and enforce bounded retention with automatic deletion of artifacts older than the documented retention period. Write a JSON report with timestamp, checked URLs, status, latency, issue list, sitemap count, and artifact paths using only sanitized data. Logs must be structured and must not contain credentials or full secret-bearing request data.

### 6. Schedule and alert

Prefer a persistent systemd service/timer. If the host cannot install a system unit, use the host's supported scheduler or stop and ask for an operator-approved scheduler change; do not silently assume a user crontab exists.

Recommended behavior:

- daily audit;
- immediate Telegram notification only when an actionable issue appears;
- one weekly healthy/degraded summary;
- forced test notification during setup;
- bounded report/artifact retention so daily raw responses cannot fill the NAS.

Reuse an existing Telegram bot only when it is explicitly in the same owner scope. Keep bot token and chat ID in a protected environment file and redact them from all output.

### 7. Verify every gate

Before claiming completion, verify all of the following:

- the web service responds with HTTP 200 on its configured port;
- the target domain and initial keywords are visible in SerpBear;
- at least one rank query succeeds;
- Search Console API query succeeds or returns a clearly documented no-data result;
- the audit runs successfully and writes a report plus raw artifacts;
- the scheduler is enabled and its next run is visible;
- a forced Telegram test succeeds;
- a simulated or observed failure produces a bounded, actionable notification;
- logs contain no passwords, private keys, bot tokens, or raw credential payloads;
- the final report identifies what is automatic, what remains approval-gated, and where to find logs/reports.

## Failure boundaries

Stop and ask for direction when:

- the target host or property cannot be identified without guessing;
- credentials are missing and cannot be entered through a secure UI or host file;
- the desired alert destination is ambiguous;
- enabling a scheduler requires a destructive or broad privilege change;
- the requested automation would edit or publish site content without approval.

Do not claim “connected” because settings were saved. Do not claim “indexed” because a page returned 200. Do not claim SEO improvement before a baseline and a later comparison exist.

## Handoff format

Return a compact handoff containing:

- target domain and deployment URL/port;
- SerpBear version and scraper mode;
- keyword count and initial baseline;
- Search Console property type and verification result;
- audit scope and latest issue count;
- Telegram schedule and test result;
- report/log/artifact locations;
- any manual action still required;
- explicit statement that no site content or code was changed unless approved.