lv24-seo 0.1.0__tar.gz

lv24_seo-0.1.0/.env.example

@@ -0,0 +1,50 @@
+# lv24-seo-optimizer — configuration template
+# Copy to `.env` (git-ignored) or export the variables in your shell.
+# Every value is optional: the default path needs no paid key at all.
+
+# ---------- Google Search Console ----------
+# Either an OAuth client (loopback flow) or a service-account JSON key that was added
+# to the property as Full/Owner. Prefer OAuth for a domain property you control.
+LV24_SEO_GSC_CLIENT_ID=
+LV24_SEO_GSC_CLIENT_SECRET=
+LV24_SEO_GSC_SERVICE_ACCOUNT_FILE=
+LV24_SEO_GSC_PROPERTY=sc-domain:example.com
+
+# ---------- Yandex Webmaster ----------
+# Scope: webmaster:hostinfo (+ webmaster:verify if you add hosts programmatically).
+LV24_SEO_YANDEX_WEBMASTER_TOKEN=
+LV24_SEO_YANDEX_HOST_ID=https:example.com:443
+
+# ---------- Yandex Metrika ----------
+# Scope: metrika:read
+LV24_SEO_YANDEX_METRIKA_TOKEN=
+LV24_SEO_YANDEX_METRIKA_COUNTER=
+
+# ---------- Bing Webmaster + IndexNow ----------
+LV24_SEO_BING_API_KEY=
+LV24_SEO_INDEXNOW_KEY=
+
+# ---------- Chrome UX Report / PageSpeed Insights ----------
+LV24_SEO_CRUX_API_KEY=
+LV24_SEO_PSI_API_KEY=
+
+# ---------- Optional paid adapters (BYO key; disabled by default) ----------
+LV24_SEO_DATAFORSEO_LOGIN=
+LV24_SEO_DATAFORSEO_PASSWORD=
+LV24_SEO_SERPAPI_KEY=
+
+# ---------- Delivery ----------
+LV24_SEO_SMTP_HOST=
+LV24_SEO_SMTP_PORT=587
+LV24_SEO_SMTP_USER=
+LV24_SEO_SMTP_PASSWORD=
+LV24_SEO_SMTP_FROM=seo@example.com
+LV24_SEO_MAIL_TO=owner@example.com
+LV24_SEO_TELEGRAM_BOT_TOKEN=
+LV24_SEO_TELEGRAM_CHAT_ID=
+
+# ---------- Storage / behaviour ----------
+LV24_SEO_DATA_DIR=./data
+LV24_SEO_LOG_LEVEL=INFO
+# Set to 1 only in CI/containers where keyring is unavailable.
+LV24_SEO_ALLOW_FILE_SECRETS=0

lv24_seo-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: Something in lv24-seo-optimizer does not work as documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please do not paste tokens, cookies or real query data.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `lv24-seo version --json`
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Surface
+      options: [CLI, MCP server, skill, report/email, crawl, provider API, install, docs]
+    validations:
+      required: true
+  - type: input
+    id: provider
+    attributes:
+      label: Provider (if relevant)
+      placeholder: gsc / yandex_webmaster / yandex_metrika / bing / crux / psi / crawl
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. lv24-seo ...
+        2. ...
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Redacted output
+      description: Run with `--verbose` and remove tokens, cookies and personal data.
+      render: text

lv24_seo-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature request
+description: Propose a provider, crawl rule, report or skill
+labels: ["enhancement"]
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What is it?
+      options: [free-tier provider, paid adapter (BYO key), crawl rule, report, MCP tool, CLI command, skill, docs]
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What SEO question cannot be answered today?
+    validations:
+      required: true
+  - type: textarea
+    id: data
+    attributes:
+      label: Data source
+      description: API/docs link, free quota, auth model, what it can and cannot return.
+    validations:
+      required: true
+  - type: checkboxes
+    id: rules
+    attributes:
+      label: Project rules
+      options:
+        - label: It works on a free tier (or is an optional adapter with a user-supplied key)
+          required: true
+        - label: It does not require scraping Google/Yandex SERPs
+          required: true
+        - label: I checked that no existing tool in the repo covers this
+          required: true

lv24_seo-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Problem
+
+<!-- What SEO question or failure does this change address? -->
+
+## Solution
+
+<!-- What changed, and why this way. -->
+
+## Provider limits touched
+
+<!-- GSC / Yandex / Bing quotas, truncation, data lag. Write "none" if not applicable. -->
+
+## Verification
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run pytest -q
+```
+
+## Checklist
+
+- [ ] No paid dependency added to the default path
+- [ ] `limitations[]` / truncation honest
+- [ ] Write path gated (`--allow-write`, idempotency key)
+- [ ] Docs updated in the same change
+- [ ] Works on Windows
+- [ ] No secrets, tokens or real query data in tests/fixtures

lv24_seo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    paths-ignore: ["docs/**", "**/*.md", "LICENSE"]
+  pull_request:
+    paths-ignore: ["docs/**", "**/*.md", "LICENSE"]
+  workflow_dispatch:
+
+# Zero-spend policy: public repo + standard ubuntu runners only, no matrix explosion,
+# no larger runners, no artifacts beyond 7 days, concurrency cancels stale runs.
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --extra dev
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Ruff format
+        run: uv run ruff format --check .
+      - name: Mypy
+        run: uv run mypy src
+      - name: Gitleaks
+        run: |
+          curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.24.3/gitleaks_8.24.3_linux_x64.tar.gz \
+            | tar -xz -C /usr/local/bin gitleaks
+          gitleaks detect --source . --redact --verbose --exit-code 2 --log-opts="--all"
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: uv sync --extra dev
+      - name: Tests (offline only)
+        run: uv run pytest -q -m "not live and not network"
+
+  schemas:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --extra dev
+      - name: Regenerate tool schemas
+        run: uv run python -m lv24_seo.mcp.registry > /tmp/tools.json
+      - name: Fail on drift
+        run: diff -u schemas/tools.json /tmp/tools.json
+
+  npm:
+    # The npm package is a thin launcher; this job only proves it is syntactically valid and
+    # packages the intended files. Publishing happens in release.yml on a v* tag.
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    defaults:
+      run:
+        working-directory: packages/npm
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7.1.0
+        with:
+          node-version: "22"
+      - name: Syntax check
+        run: node --check bin/lv24-seo.js
+      - name: Package contents
+        run: npm pack --dry-run
+
+

lv24_seo-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,212 @@
+name: release
+
+# Build and publish lv24-seo when a v* tag is pushed.
+#
+# Triggers:
+#   * push of a v* tag  -> build + publish to PyPI;
+#   * workflow_dispatch -> build-only dry run unless the selected ref is a v* tag.
+# There is deliberately no pull_request trigger, so releases never run for PRs.
+#
+# Zero-spend policy (same as ci.yml):
+#   * public repository + standard ubuntu-latest runners only = $0;
+#   * no matrix, no larger runners, no paid services;
+#   * two short jobs, artifacts kept for 7 days;
+#   * PyPI uses OIDC Trusted Publishing, so no long-lived API token secret exists.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  # Never cancel a run that may be halfway through a PyPI upload.
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v10.3.3
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Check tag, pyproject, __version__ and server.json agree
+        # A release must never publish a tag that disagrees with the package metadata.
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          python3 - "${GITHUB_REF_NAME#v}" <<'PY'
+          import json
+          import pathlib
+          import re
+          import sys
+          import tomllib
+
+          tag = sys.argv[1]
+          pyproject = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          server = json.loads(pathlib.Path("server.json").read_text(encoding="utf-8"))
+          npm = json.loads(pathlib.Path("packages/npm/package.json").read_text(encoding="utf-8"))
+          init_source = pathlib.Path("src/lv24_seo/__init__.py").read_text(encoding="utf-8")
+          init_version = re.search(r'^__version__\s*=\s*"([^"]+)"', init_source, re.MULTILINE)
+          versions = {
+              "tag": tag,
+              "pyproject.toml": pyproject["project"]["version"],
+              "src/lv24_seo/__init__.py": init_version.group(1) if init_version else "missing",
+              "server.json": server["version"],
+              "server.json packages[0]": server["packages"][0]["version"],
+              "packages/npm/package.json": npm["version"],
+          }
+          if len(set(versions.values())) != 1:
+              print("::error::version mismatch: " + ", ".join(f"{key}={value}" for key, value in versions.items()))
+              raise SystemExit(1)
+          print(f"versions aligned at {tag}")
+          PY
+
+      - name: Build sdist and wheel
+        # hatchling is the build backend declared in pyproject.toml.
+        # uv.lock must be committed: CI and the local release checks use it for
+        # reproducible installs, so the tagged commit has a tested dependency set.
+        run: uv build
+
+      - name: List distributions
+        run: ls -lh dist/
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    # A manual dispatch is a build-only dry run unless it targets a v* tag.
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lv24-seo
+    permissions:
+      # Job-level permissions replace the workflow-level block.
+      # OIDC only: no PyPI password or API token is stored in this repository.
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        # One-time setup on PyPI: project lv24-seo -> Publishing -> add a trusted
+        # publisher with owner LevapVeeskela, repository lv24-seo-optimizer,
+        # workflow release.yml and environment pypi. Without it this step fails.
+        # PyPI files are immutable: a version can never be uploaded twice.
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  publish-npm:
+    name: publish @lv24/seo to npm
+    needs: build
+    # A manual dispatch is a build-only dry run unless it targets a v* tag.
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # npm provenance attests the tarball to this workflow run via OIDC.
+      id-token: write
+    defaults:
+      run:
+        working-directory: packages/npm
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Detect the npm token
+        # `secrets` cannot be used in `if:` expressions, so the gate is a step output.
+        # Without NPM_TOKEN the job skips instead of failing the whole release.
+        id: gate
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -n "$NPM_TOKEN" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::NPM_TOKEN is not set — skipping the npm publish."
+          fi
+
+      - name: Install Node
+        if: steps.gate.outputs.enabled == 'true'
+        uses: actions/setup-node@v7.1.0
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+
+      - name: Check the npm version matches the tag
+        if: steps.gate.outputs.enabled == 'true'
+        run: |
+          node -e '
+            const pkg = require("./package.json");
+            const tag = process.env.GITHUB_REF_NAME.replace(/^v/, "");
+            if (pkg.version !== tag) {
+              console.error(`npm version ${pkg.version} != tag ${tag}`);
+              process.exit(1);
+            }
+            console.log(`npm version aligned at ${tag}`);
+          '
+
+      - name: Publish with provenance
+        if: steps.gate.outputs.enabled == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public --provenance
+
+  # ---------------------------------------------------------------------------
+  # Optional and disabled: GHCR image for Docker/VPS users (WP10.3).
+  # Public container packages are free to store and pull, but building and
+  # pushing still consumes Actions minutes, and this repository has no
+  # Dockerfile yet. Enable only after the first PyPI release is green, then
+  # change `needs` to publish-pypi if the image must follow a successful upload.
+  #
+  # publish-ghcr:
+  #   name: publish container to GHCR
+  #   needs: build
+  #   if: startsWith(github.ref, 'refs/tags/v')
+  #   runs-on: ubuntu-latest
+  #   timeout-minutes: 20
+  #   permissions:
+  #     contents: read
+  #     packages: write
+  #   steps:
+  #     - uses: actions/checkout@v7
+  #       with:
+  #         persist-credentials: false
+  #     - uses: docker/login-action@v3
+  #       with:
+  #         registry: ghcr.io
+  #         username: ${{ github.actor }}
+  #         password: ${{ secrets.GITHUB_TOKEN }}
+  #     - uses: docker/build-push-action@v6
+  #       with:
+  #         context: .
+  #         push: true
+  #         tags: ghcr.io/levapveeskela/lv24-seo:${{ github.ref_name }}

lv24_seo-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.uv/
+
+# Local data (never commit crawled data, tokens or reports)
+data/
+.env
+.env.*
+!.env.example
+*.sqlite
+*.sqlite3
+*.db
+*.sqlite3-wal
+*.sqlite3-shm
+reports/*.html
+reports/*.json
+!reports/.gitkeep
+logs/
+*.log
+
+# Editors / OS
+.idea/
+.vscode/*
+!.vscode/extensions.json
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Node (npm launcher package)
+node_modules/
+packages/npm/package-lock.json

lv24_seo-0.1.0/.gitleaks.toml

@@ -0,0 +1,16 @@
+# Gitleaks configuration.
+# The default rule set is kept; we only allowlist the documentation template whose values are
+# intentionally empty placeholders (a key *name* without a secret still matches generic-api-key).
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Template files contain empty placeholders only; env var NAMES are not secrets"
+paths = [
+  '''^\.env\.example$''',
+  '''^tests/''',
+]
+regexes = [
+  '''LV24_SEO_[A-Z0-9_]+''',
+]

lv24_seo-0.1.0/AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md — contract for AI agents working in this repo
+
+This file is the canonical instruction set for any coding agent (Claude Code, OpenCode, Codex,
+Cursor, Gemini, Aider). `CLAUDE.md` is a pointer to this file — never let the two diverge.
+
+## 1. What this project is
+
+`lv24-seo-optimizer` is a Python package that ships four surfaces over one core:
+
+| Surface | Entry point | Contract |
+|---|---|---|
+| CLI | `src/lv24_seo/cli/` | every command supports `--json`, returns `{ok,data,meta,warnings}`, stable exit codes |
+| MCP server | `src/lv24_seo/mcp/` | 8–12 stable tools, read-only by default, `structuredContent` + text fallback |
+| Skills | `skills/*/SKILL.md` | canonical skill + thin mirrors (`.claude/skills`, `.opencode/skills`) |
+| Automation | `src/lv24_seo/automation/` | cron / systemd / Task Scheduler generators, email + Telegram delivery |
+
+Single source of truth for tool metadata: `src/lv24_seo/mcp/registry.py`. CLI help, MCP schemas,
+`schemas/tools.json` and the docs tables are **generated** from it. Never hand-edit generated files.
+
+## 2. Hard rules
+
+1. **Zero spend.** Default path must work on free tiers only. Do not add a dependency that requires a
+   paid account, a card on file, or a paid CI runner. Optional paid adapters are allowed only behind
+   an explicit provider key and must degrade gracefully.
+2. **Read-only by default.** Any destructive or quota-consuming action (sitemap submit, recrawl
+   request, IndexNow submit) requires `--allow-write` (CLI) / `destructiveHint` + confirm token (MCP),
+   plus an idempotency key.
+3. **Honesty over completeness.** Every bounded response must carry `truncated`, `total`, `data_age`
+   and `limitations[]`. Never let an agent claim full coverage when a provider capped the data.
+4. **No secrets in the repo, logs, fixtures or tests.** Tokens live in the OS keychain, `0600` files
+   outside the repo, or `LV24_SEO_*` env vars. Tests use synthetic fixtures only.
+5. **No scraping of SERPs.** Rank tracking uses provider APIs (GSC, Yandex Webmaster), never HTML
+   scraping of Google/Yandex result pages.
+6. **No vendor resale.** If a paid provider is integrated, the user supplies their own key and the
+   data stays local.
+7. **Windows, macOS and Linux must all work.** No POSIX-only paths in user-facing commands; shell
+   snippets in docs come in both bash and PowerShell where relevant.
+8. **Deterministic output.** Report and CLI output is stable enough to diff between runs (sorted keys,
+   ISO-8601 UTC timestamps, no random ids in visible output).
+
+## 3. Repo layout
+
+```
+src/lv24_seo/
+  core/        config, errors, envelopes, rate limiting, http, time
+  providers/   gsc, yandex_webmaster, yandex_metrika, bing, crux, psi, ga4 (optional)
+  crawl/       fetcher, parsers, rules, link graph, log ingest
+  store/       sqlite schema + repositories
+  report/      builders, renderers (html/text/md), delivery
+  mcp/         server, registry (SoT), resources, prompts
+  cli/         Typer commands
+  automation/  scheduler generators, GitHub Actions recipes
+schemas/       generated JSON schemas (tools.json)
+skills/        canonical SKILL.md files
+docs/          architecture, limits, guides, plans, research
+tests/         unit, contract (recorded fixtures), e2e (network-gated)
+```
+
+## 4. How to work
+
+```bash
+uv sync                    # install dev env
+uv run ruff check .        # lint
+uv run ruff format --check .
+uv run mypy src            # types
+uv run pytest -q           # offline tests only
+uv run pytest -q -m live   # requires tokens; never in CI
+uv run lv24-seo doctor     # environment self-check
+```
+
+Before claiming done:
+
+- `ruff check` + `ruff format --check` + `mypy` + `pytest -q` are green.
+- Generated artifacts are regenerated, not edited: `uv run python -m lv24_seo.mcp.registry --write`.
+- Docs updated in the same change (command help, tool table, `docs/*`).
+- No new required dependency without a note in the PR body explaining why and its license.
+- Do not weaken `limitations[]`, truncation reporting or write-gating to make a test pass.
+
+## 5. Change review protocol
+
+- Small, focused commits. Subject format: `[SEO](<area>) - <what changed>`, e.g.
+  `[SEO](providers) - add yandex recrawl quota guard`.
+- One area per commit: `cli`, `mcp`, `providers`, `crawl`, `report`, `store`, `docs`, `infra`, `tests`.
+- PR body: problem, solution, verification commands, and a note about provider limits touched.
+- Never commit generated fixtures containing real customer data or personal queries.
+
+## 6. Where decisions live
+
+- Product and architecture decisions: `docs/decisions/ADR-*.md` (append a new ADR, do not rewrite old ones).
+- Execution plan and wave status: `docs/plans/2026-11-10-implementation-plan.md`.
+- Provider capability matrix: `docs/data-sources.md` — update it in the same PR that touches a provider.

lv24_seo-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+### Added — engine (waves W0–W7)
+
+- **Core**: config (`seo.toml` + `LV24_SEO_*` env), secret store (keychain → env → `0600` file),
+  HTTP client with IPv4 pinning/retry/`Retry-After`, token-bucket rate limiter, redacting JSON logging,
+  time/period helpers, typed error codes + response envelope.
+- **Providers**: Google Search Console (search analytics with pagination, URL inspection, sites,
+  sitemaps), Yandex Webmaster (hosts, summary, indexing history, search-urls events, diagnostics,
+  popular queries, recrawl quota), Yandex Metrika (counters, goals, stat/v1), Bing Webmaster +
+  IndexNow, Chrome UX Report, PageSpeed Insights. Every result carries `truncated`, `total`,
+  `data_age_days`, `limitations[]`.
+- **Crawler**: robots.txt (RFC 9309), manual redirects, sitemap reader (index, gzip, 50k/50MB caps),
+  stdlib HTML extraction (title/meta/canonical/hreflang/JSON-LD/links/images/word count), internal
+  link graph, render-parity hook, and **30 rules** (indexability, content, structured data, i18n,
+  mixed content, sitemap membership).
+- **Storage**: SQLite (WAL) with 9 tables, repositories, snapshot hashing, delivery ledger.
+- **Analysis**: period deltas with thresholds, striking-distance/CTR-gap/decay opportunities, indexing
+  triage buckets with next actions, GSC↔Yandex↔Metrika fusion with explicit caveats, nginx JSON log
+  stats (bots, crawl waste, p95).
+- **Reports**: weekly/indexing/opportunities builders, text/Markdown/HTML renderers (email-safe,
+  escaped), SMTP + Telegram delivery with content hashing and idempotent sends, change-gated sends.
+- **CLI**: `version`, `doctor`, `init`, `config show`, `auth status|set|login|logout`, `properties`,
+  `gsc query`, `yandex queries|indexing`, `crawl`, `report weekly`, `schedule print|install`,
+  `install --client`, `export tools` — every command supports `--json` and stable exit codes.
+- **MCP**: 10 registry-driven tools (8 read + 2 gated write), resources `seo://config`,
+  `seo://report/latest`, `seo://docs/tools`, prompts `weekly_seo_review` / `indexing_triage` /
+  `content_opportunities`; stdio by default, stateless HTTP optional.
+- **Automation**: cron / systemd user units / Windows Task Scheduler generators with `--print` and
+  idempotent install; GitHub Actions and VPS cron recipes.
+
+### Added — docs and repository
+
+- Apache-2.0 license, agent contract (`AGENTS.md`), `llms.txt`, CI, issue/PR templates, gitleaks.
+- `lv24_seo.mcp.registry` — canonical tool registry (10 tools) and generated `schemas/tools.json`.
+- Docs: architecture, data sources and quotas, MCP surface, CLI, config, scheduling, skills,
+  3 ADRs, quickstart, GitHub Actions and VPS guides.
+- Research: 2026 landscape (Google/Yandex APIs, existing SEO MCP servers, paid tooling, audit signals).
+- Skills: `seo-weekly`, `seo-indexing-triage`, `seo-technical-audit`.
+
+### Known gaps
+
+- GSC service-account auth is documented but not wired (OAuth bearer token only).
+- Write operations exist in adapters but have no CLI/MCP confirm-token flow yet.
+- No live end-to-end run against a real property; PyPI/MCP-registry publishing pending.
+
+### Notes
+
+- Pre-release: interfaces may change until `v0.1.0`.

lv24_seo-0.1.0/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md
+
+The canonical agent contract for this repository is [`AGENTS.md`](AGENTS.md).
+Read it before changing anything; this file intentionally contains no separate rules.