searvex-seo 0.7.0 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     {
       "name": "searvex",
       "source": "./",
-      "description": "Deterministic technical SEO + GEO audits, competitor research and safe code fixes with rollback."
+      "description": "Technical SEO + GEO audits with a bilingual action-center report, repair prompts for coding agents and safe code fixes with rollback."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "searvex",
-  "version": "0.7.0",
-  "description": "Search intelligence & optimization engine: deterministic technical SEO + GEO audits with a sourced rule base, competitor research, and safe, verified code fixes with rollback.",
+  "version": "1.1.0",
+  "description": "Understand search, fix what matters: deterministic technical SEO + GEO audits with a sourced rule base, a bilingual (EN/TR) action-center report with root-cause groups and repair prompts, competitor research, and safe, verified code fixes with rollback.",
   "author": { "name": "Cihan Topaç", "url": "https://github.com/cihantopac" },
   "license": "Apache-2.0",
   "homepage": "https://github.com/cihantopac/searvex#readme",

package/CHANGELOG.md

@@ -5,6 +5,108 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-11-01
+
+A product-experience release: the analysis engine and its evidence are unchanged; how results are presented,
+selected and fixed is new. Release notes: [docs/release-notes-1.1.0.md](docs/release-notes-1.1.0.md).
+
+### Added
+- **Brand identity**: the approved Searvex logo (outlined SVG, theme-aware) in every HTML report header, an SVG
+  favicon in the reports, and the logo in the README. Source files in `docs/assets/brand/`.
+- **SEO action center** (`report.html`): Overview (health score, issue groups, affected URLs, condition by area,
+  top three priorities, limits of the run), Priorities, Issues, GEO, Search performance (only with connected
+  data), Changes (only with a previous run) and Evidence. One shell for website, repository, monitor and
+  ecosystem reports.
+- **English / Türkçe** interface with browser-language detection, and Turkish titles and fixes for all 90
+  rules. Evidence, URLs, code, file paths and rule ids are never translated.
+- **Light / Dark / System** theme next to the language switch; both are remembered in `localStorage` (safe
+  fallback when storage is blocked) and applied before first paint.
+- **Root-cause groups**: findings are split by URL template, source file or — when a rule hits most page types —
+  one shared layout, with page counts covering every affected URL. Every occurrence keeps a stable reference
+  (`ruleId#hash`).
+- **Remediation labels**: automatic (only when a dry-run plan produced a concrete patch), agent-assisted or
+  manual/operational.
+- **Issue selection and repair prompts**: select occurrences, groups or all visible issues, then generate an
+  editable prompt (Copy / Download Markdown, English or Turkish) for a coding agent. It contains the run id,
+  references, root-cause groups, evidence, fixes, verification steps and `optimize --only …` commands for the
+  automatic part. Secrets are redacted; crawled text is fenced as untrusted data. Website-only audits get a
+  remediation brief instead.
+- `searvex review <runId|latest> <ref|ruleId> <confirmed|rejected|fixed> [--note]`: records agent/human
+  verdicts in `reviews.json`, shown next to (never instead of) the scanner evidence.
+- `searvex open [runId|latest]` and `--open`: open the HTML report.
+- Automatic fixes for three more rules (12 in total): identical duplicate `<title>` and meta description in
+  static HTML (conflicting duplicates become a task), relative hreflang URLs in static HTML (with `--site-url`).
+- `run` writes `repository-report.html`; a website report produced with a repository knows that repository
+  (prompts target it; real patches count as automatic). `gsc report --audit` refreshes the audit's HTML with
+  the verified search data.
+- `scripts/screenshots.mjs` captures README screenshots from a real report.
+
+### Changed
+- Terminal summary: score, issue types and affected pages, three priorities, automatic fixes, limits and the
+  `file://` link of the report — instead of twelve finding lines.
+- Claude Code skills answer in 80–150 words with the report link and one next action; no phase-by-phase
+  narration, long tables or raw JSON in the chat.
+- README rewritten as a visual product page with real report screenshots.
+
+### Fixed
+- Optimizer, monorepos: `robots.no-sitemap` generated a second sitemap for an app that already had one, and
+  used the single `--site-url` for an app served on another host (found on a real monorepo copy, where the
+  patch passed verification but would have published login routes under the wrong host). It now plans only
+  for the app the finding is about and turns ambiguous multi-app cases into a reviewed task.
+
+## [1.0.0] - 2026-11-01
+
+First stable release. Every capability advertised as supported has been verified end to end; Bing Webmaster
+is the one integration shipped as experimental. Evidence: [docs/release-checklist.md](docs/release-checklist.md)
+and [docs/quality.md](docs/quality.md).
+
+### Security and data integrity
+- `monitor` no longer attaches search data of another website: `--import`, `--site-url`, `SEARVEX_GSC_SITE`
+  and `--baseline` are checked against the monitored site; an export without a pages table needs `--property`.
+- Search Console exports whose pages span several subdomains are scoped as domain properties (their totals
+  include every subdomain); an explicit `--property` that does not contain every exported page is refused.
+- `--render`: a hard per-page deadline stops pages whose scripts never yield or allocate without bound; a
+  stuck browser is replaced. Local host names with a trailing dot are blocked.
+- Optimizer: backups and the manifest are written before the first file (an interrupted apply is recoverable
+  with `rollback`, and new applies are refused until then); a failed verification never overwrites files
+  edited meanwhile; CRLF line endings and file modes are preserved.
+- Credentials: opt-in OS keychain store (`SEARVEX_CREDENTIAL_STORE=keychain`: macOS Keychain, Secret Service,
+  Windows DPAPI) using the OS's own tools with secrets on stdin; entries are isolated per config directory.
+  Automated scans confirm that no token, key or client secret reaches output or run files.
+
+### Added
+- `searvex bing auth|status|sites|logout` and `searvex crux auth|status|logout`: keys are entered without echo,
+  checked against the API and kept in the credential store instead of environment variables.
+- `gsc auth` opens the browser for consent (`--no-browser` to only print the URL).
+- `THIRD_PARTY_NOTICES.md` with the licence texts of all bundled runtime packages.
+
+### Changed
+- Search Console API reports show property totals from the daily series (anonymised queries included), equal
+  to the CSV export of the same period. Bing reports use the daily site series for totals and explain empty
+  data. `bing report` requires a verified site of the account.
+- "Fix first" names the likely root cause of dependent findings (e.g. a client-side language switch that
+  changes titles, canonicals and hreflang for renderers) and ranks it first.
+- 3-letter hreflang codes without an ISO 639-1 equivalent (`ast`, `ceb`) are reported at low severity with an
+  explanation instead of as high-severity mistakes; a finding's severity is its most severe occurrence.
+- Status commands (`gsc|bing|crux status`) exit 0 only when the integration is usable.
+
+### Fixed
+- Repository mode: test/fixture/benchmark/example folders, HTML fragments and server template folders are not
+  treated as the site (a repository without a website now scores n/a); static sites in workspace folders and
+  locale sub-folders are found; clean URLs; sitemap URLs without a file (unless another app routes them); all
+  Laravel route files; Blade/PHP expressions no longer hide attributes; admin views and tests skipped; error
+  pages modelled as 404/500; Next.js fill images and aspect-ratio utility classes are sized; personal sites
+  are not asked for Organization markup.
+- Website mode: pages linked only through internal redirects are not orphans; orphans are not reported on
+  crawls stopped at the page limit; cannibalisation candidates must share a language and exclude legal pages;
+  Turkish soft-404 wording is detected (Unicode-aware boundaries).
+
+### Verified
+- Live: Search Console API (authorization, refresh, properties, pagination, reports), Search Console CSV
+  (real Turkish and English exports), CrUX (values identical to the raw API), Bing Webmaster (mechanics; no
+  site data yet). Real-world rounds on 13 public sites and 9 repositories; benchmarks to 50,000 pages;
+  reproducible package; clean installs on Linux, macOS and Windows.
+
 ## [0.7.0] - 2026-10-30
 
 ### Added

package/NOTICE

@@ -11,6 +11,8 @@ The bundled distribution (dist/searvex.mjs) includes the following third-party s
 - robots-parser (MIT)        https://github.com/samclarke/robots-parser
 - @babel/parser (MIT)        https://github.com/babel/babel
 
+Full licence texts of every bundled package: THIRD_PARTY_NOTICES.md.
+
 Rule descriptions summarise and link to official documentation from Google Search Central, Bing
 Webmaster, Yandex, schema.org, W3C, web.dev, MDN and crawler operators. Those documents remain the
 property of their respective owners.

package/README.md

@@ -1,206 +1,209 @@
-# Searvex
-
-**Open-source search intelligence & optimization engine.** Searvex audits websites and code
-repositories for technical SEO and GEO/AEO (AI search) issues against a **sourced, versioned rule
-base**, researches competitors, and applies **safe, verified code fixes with one-command rollback**.
-It ships as a standalone CLI and as a Claude Code plugin.
-
-> Status: **v0.7.0 (early)**. The engine, rule base, CLI and plugin are tested (automated tests incl. Playwright rendering, CI on Linux/macOS/Windows,
-> real-site and real-repository validation — see [docs/quality.md](docs/quality.md)). Expect rough
-> edges; read [Limitations](#limitations) before relying on it.
-
-## Why Searvex
-
-| | Searvex | Typical crawlers (Screaming Frog, Sitebulb) | Prompt-only SEO skills |
-|---|---|---|---|
-| Deterministic, reproducible checks | ✅ code, not prompts | ✅ | ❌ |
-| Every finding cites an official source + check date | ✅ `searvex rules show <id>` | ❌ | ❌ |
-| Myth firewall (no keyword density, fixed title lengths, llms.txt-as-ranking-factor…) | ✅ | partly | ❌ |
-| Repository mode: findings with `file:line` for Next.js, Astro, Nuxt, Laravel, WordPress, static sites | ✅ | ❌ | partial |
-| Safe fixes: dry-run diff → apply → re-verify → rollback | ✅ | ❌ | ❌ |
-| GEO: AI crawler access by *purpose* (training vs search vs user fetch) | ✅ | partial | partial |
-| Honest measurement: each finding is `verified`, `heuristic` or `unmeasurable` | ✅ | ❌ | ❌ |
-| Local-first, no paid API required | ✅ | desktop app | ✅ |
-
-Competitor research and differentiation notes: [docs/research/competitors-2026-10.md](docs/research/competitors-2026-10.md).
-
-## What it does — and what it does not
-
-**Searvex does:**
-
-- Crawl public pages (robots.txt-compliant, rate-limited) or read a repository's source, and check them against
-  90 rules. 71 rules are `verified` against official documentation, 17 are `heuristic` and 2 are `unmeasurable`
-  signals that are reported as such.
-- Explain every finding with its official source, the date the source was checked, how to fix it and how to
-  verify the fix.
-- Compare runs over time (`monitor`), across related sites (`ecosystem`) and against competitors you name
-  (`research`).
-- Fix a small set of problems in code automatically (9 rule types: e.g. missing `lang`, viewport, robots.txt
-  sitemap line, invalid hreflang codes), always as a dry-run diff first, then apply → re-verify → rollback.
-- Read Search Console or Bing data when you connect them yourself, and keep measured data separate from
-  inference.
-
-**Searvex does not:**
-
-- Estimate traffic, rankings, search volume, keyword difficulty, backlinks or AI citations. Without a connected
-  data source these are reported as **not measured**.
-- Promise rankings or "SEO scores" that search engines use. The health score is a Searvex summary, not a search
-  engine metric.
-- Publish content, submit URLs, change live sites or send data to a Searvex server (there is none).
-- Offer a one-click Google login. Search Console access uses your own Google Cloud OAuth client, or a CSV
-  export you download yourself.
-- See login-protected pages, run Lighthouse lab tests, or execute JavaScript unless you opt into `--render`.
-- Rewrite your content. Judgement-based changes (titles, descriptions, alt text) are drafted by the agent for your
-  review, never applied silently.
-
-## Install
-
-Requires **Node.js ≥ 20.10** (Windows, macOS, Linux). The npm package is `searvex-seo`; the command it installs is `searvex`.
+<h1 align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/brand/primary-reversed.svg">
+  <img alt="Searvex" src="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/brand/primary-color.svg" width="320">
+</picture>
+</h1>
+
+<p align="center"><strong>Understand Search. Fix What Matters.</strong></p>
+
+<p align="center">
+Open-source SEO and AI-search auditor for websites and code repositories. It finds what is actually wrong,
+groups it by root cause, explains it with official sources and fixes the safe parts in your code — with
+verification and one-command rollback. CLI and Claude Code plugin.
+</p>
+
+<p align="center">
+<a href="https://www.npmjs.com/package/searvex-seo"><img alt="npm" src="https://img.shields.io/npm/v/searvex-seo?color=0e4f55&label=npm"></a>
+<a href="https://github.com/cihantopac/searvex/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/cihantopac/searvex/actions/workflows/ci.yml/badge.svg"></a>
+<a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-0e4f55"></a>
+<img alt="Node ≥ 20.10" src="https://img.shields.io/badge/node-%E2%89%A5%2020.10-0e4f55">
+</p>
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/dashboard-dark.webp">
+  <img alt="Searvex HTML report: health score, issue groups, affected URLs, condition by area and the three issues to fix first" src="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/dashboard-light.webp" width="900">
+</picture>
+<br><sub>Real report of a live site (ovokodo.com, 52 pages, 2026-11-01). English / Türkçe · light / dark / system.</sub>
+</p>
+
+## What Searvex does
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/workflow-dark.svg">
+  <img alt="Workflow: Audit, Understand, Prioritize, Fix, Verify, Monitor" src="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/workflow-light.svg" width="900">
+</picture>
+
+- **Audit** a live site (robots.txt-compliant crawl) or a repository (Next.js, Astro, Nuxt, Laravel, WordPress, static HTML).
+- **Understand** every finding: evidence, the official source it is based on and the date that source was checked.
+- **Prioritize** by root cause: one broken layout on 50 pages is one task, not 50.
+- **Fix** what can be fixed safely, in your code, after you approve a diff — or hand the rest to your coding agent with a ready-made repair prompt.
+- **Verify** by re-auditing; failed verification rolls back automatically.
+- **Monitor** what improved or regressed since the last run.
+
+## From findings to fixes
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**Select what to fix.** Issues are grouped by root cause — a URL template, a source file or a shared layout — and labelled by how they get fixed:
+
+- **Automatic** — a deterministic Searvex optimizer produced a verified patch.
+- **Agent-assisted** — needs source or content judgement.
+- **Manual** — deployment, server, Search Console or business decisions.
+
+</td>
+<td width="50%" valign="top">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/issues-dark.webp">
+  <img alt="Issues grouped by root cause with selection checkboxes" src="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/issues-light.webp">
+</picture>
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/prompt-dark.webp">
+  <img alt="Editable repair prompt with copy and Markdown download" src="https://raw.githubusercontent.com/cihantopac/searvex/main/docs/assets/prompt-light.webp">
+</picture>
+
+</td>
+<td width="50%" valign="top">
+
+**Generate a repair prompt** for Claude Code, Codex or any coding agent: target and run id, stable finding references, exact URLs or `file:line`, root-cause groups, evidence, the fix and how to verify it. The receiving agent is told to re-check the source, reject false positives, fix root causes once, get approval and re-audit.
+
+Secrets are redacted and crawled text is fenced as untrusted data. Without a repository the prompt becomes a remediation brief — the report never pretends it can edit your site.
+
+</td>
+</tr>
+</table>
+
+## Capabilities
+
+| | |
+|---|---|
+| **Technical SEO** | Crawlability, indexability, canonicals, redirects, hreflang, metadata, structured data (Google rich-result requirements), links, performance signals, security. |
+| **GEO / AI search** | AI crawler access by purpose (search vs. training vs. user fetch), snippet controls, entity consistency, content clarity. AI citations are reported as *not measured*. |
+| **Repository checks** | Findings with `file:line` for framework source code, not only rendered HTML. |
+| **Search Console & CrUX** | Optional, read-only: Search Console API (your own OAuth client) or CSV export, Chrome UX Report field data. Measured data is kept apart from inference. |
+| **Competitor research** | Topic and page-type coverage gaps against competitors you name — labelled as hypotheses, not demand. |
+| **Optimization** | 12 rule types fixed automatically (e.g. missing `lang`/viewport, canonicals, sitemap + robots.txt, identical duplicate `<title>`/description, hreflang codes and relative URLs): dry run → approval → apply → verify → rollback. |
+| **Monitoring** | Changes since the previous run in every report; `monitor` and `--fail-on high` for CI. |
+
+## Evidence, not claims
+
+Status: **v1.1.0** ([release notes](docs/release-notes-1.1.0.md), [changelog](CHANGELOG.md)).
+
+- **90 rules**, each with an official source and check date: **71 verified**, **17 heuristic**, **2 unmeasurable** (reported, never scored). `searvex rules show <id>`.
+- **Automated tests** across unit, integration, Playwright and end-to-end runs of the bundled CLI; CI on Linux, macOS and Windows with Node 20, 22 and 24 ([quality report](docs/quality.md)).
+- **Real-world validation** on 13 public sites and 9 repositories; **live** Search Console and CrUX checks returned values identical to the official exports and raw API.
+- **Real issues it found**, confirmed against live HTML: a 404 page listed in MDN's sitemap; two `<title>` elements on every page of an Inertia.js site; Turkish URLs that switch to English (and to "page not found") for an en-US browser.
+- **Safety:** read-only by default, SSRF protection, robots.txt always honoured, secret files never read, changes journaled with byte-for-byte rollback, reports rendered without `innerHTML` under a strict CSP.
+
+Searvex never promises rankings, indexing, traffic or AI citations. The health score is Searvex's own summary of its findings, not a search-engine metric.
+
+## Quick start
+
+Requires **Node.js ≥ 20.10**. The npm package is `searvex-seo`; the command is `searvex`.
 
 ```bash
 npm install -g searvex-seo
 ```
 
 ```bash
-searvex --help
+searvex audit https://example.com --open
 ```
 
-### Claude Code plugin
+```bash
+searvex audit ./my-site --site-url https://example.com
+```
 
-In Claude Code:
+```bash
+searvex optimize ./my-site --site-url https://example.com --lang en
+```
+
+Reports land in `.searvex/runs/<runId>/` (`report.html`, `.md`, `.json`, optional `.sarif`). `searvex open latest`
+opens the newest one. Full reference: [docs/cli.md](docs/cli.md).
+
+**Claude Code plugin** — no npm install needed:
 
 ```
 /plugin marketplace add cihantopac/searvex
 /plugin install searvex@searvex
 ```
 
-Then use **`/searvex <url> [path]`** — it runs the whole workflow in a fixed order (scope → competitors →
-audit → GEO → change since last run → research → repository audit → fix plan → approved fixes → content
-plan → monitoring) with approval checkpoints. Single steps are available as the namespaced skills `/searvex:audit`, `/searvex:research`,
-`/searvex:optimize`, `/searvex:geo`, `/searvex:monitor`. The plugin bundles the CLI
-(`dist/searvex.mjs`), so no `npm install` is needed.
+Then `/searvex <url> [path]` runs the whole workflow with approval checkpoints and answers with a short
+summary plus the report link. Single steps: `/searvex:audit`, `/searvex:geo`, `/searvex:research`,
+`/searvex:optimize`, `/searvex:monitor`.
 
-## Usage
+**Optional search data** (read-only, asked once per site):
 
 ```bash
-# Everything in order with one crawl: audit → GEO → change since last run → research → repo audit → fix plan (dry run)
-searvex run https://example.com ./my-site --competitor https://rival-a.com
-
-# Website mode: crawl (robots.txt-compliant, rate-limited) and audit
-searvex audit https://example.com --max-pages 300
-
-# Repository mode: detect the framework and analyse source files
-searvex audit ./my-next-app
-
-# Safe fixes for a repository: dry run first (default), then apply with verification
-searvex optimize ./my-site --site-url https://example.com --lang en
-searvex optimize ./my-site --site-url https://example.com --lang en --apply
-searvex rollback <changeId> ./my-site
-
-# GEO / AI-search readiness
-searvex geo https://example.com
-
-# Brand family / product ecosystem across related sites
-searvex ecosystem https://company.example https://product-a.example https://product-b.example
-
-# Competitor & content-gap research (competitors are passed explicitly)
-searvex research https://example.com --competitor https://rival-a.com --competitor https://rival-b.com
-
-# Regression monitoring against the previous run (optionally with Search Console data)
-searvex monitor https://example.com --fail-on high
-
-# Optional search performance data: Google / CSV / skip (asked once per site)
 searvex connect https://example.com
-searvex gsc import performance-export.zip --audit latest   # Search Console CSV export, no account access
-searvex gsc auth --client client_secret.json               # your own Google OAuth "Desktop app" client
-searvex gsc report sc-domain:example.com --audit latest
-SEARVEX_BING_API_KEY=… searvex bing report https://example.com/
-
-# Inspect the rule base and re-verify its official sources
-searvex rules check-sources
-searvex rules list
-searvex rules show canonical.in-body
-searvex rules validate
 ```
 
-Reports are written to `.searvex/runs/<runId>/` as Markdown, interactive HTML, JSON and SARIF
-(`--format md,html,json,sarif`). Use `--fail-on high` in CI to fail builds on serious issues.
-Full reference: [docs/cli.md](docs/cli.md).
-
-### Optional integrations (read-only, opt-in)
-
-| Variable | Enables |
-|---|---|
-| `SEARVEX_CRUX_API_KEY` | Real-user Core Web Vitals (Chrome UX Report API) |
-| `searvex gsc auth` (or `SEARVEX_GSC_TOKEN`) | Search Console query × page analysis, `monitor` performance |
-| `SEARVEX_BING_API_KEY` | Bing Webmaster Tools query × page analysis |
-| `searvex gsc import export.zip` | Search Console Performance CSV/ZIP exports (no account access; no query × page data) |
-| `npm i -D playwright` | `--render`: JavaScript rendering and raw-vs-rendered comparison |
-
-Without them, Searvex reports these metrics as **not measured** — it never estimates them.
-
-## What it checks
+```bash
+searvex gsc import performance-export.zip --audit latest
+```
 
-90 rules across crawlability, indexability, canonicalisation, international (hreflang), metadata,
-structured data (Google rich-result requirements), performance, security, links, content and GEO.
-Examples: robots.txt failures and AI crawler access, redirect chains and loops, noindex/sitemap
-conflicts, canonical conflicts (including canonicals pushed into `<body>` by invalid head markup),
-hreflang reciprocity and codes, soft 404s, client-side-only rendering, duplicate and near-duplicate
-content (template-aware), retired rich-result types (FAQ, HowTo), entity consistency, declared vs actual
-content language, untranslated headings on localized pages.
+```bash
+searvex crux auth
+```
 
-Each rule records the engines it applies to (Google, Bing, Yandex, AI systems), the official source
-URLs with check dates, how to fix and how to verify — see [docs/knowledge-base.md](docs/knowledge-base.md).
+Without them, clicks, impressions, positions and Core Web Vitals are shown as **not measured** — never estimated.
 
-## How it works
+<details>
+<summary><b>More commands</b></summary>
 
-```
-CLI / Claude Code skills
-        │
-        ├── Website mode: safe fetcher → crawler (robots, sitemaps, queue, checkpoints) → HTML5 extraction
-        ├── Repository mode: safe file walker → framework detection → source checks / static-site analysis
-        │
-        ├── Analyzers: technical · structured data · GEO · content · inventory   ← rule knowledge base
-        ├── Reports: Markdown · HTML · JSON · SARIF
-        └── Optimizer: deterministic fix planners → transaction (backup, verify, rollback)
+```bash
+searvex run https://example.com ./my-site --competitor https://rival.example   # whole workflow, one crawl
+searvex geo https://example.com                                                 # AI crawler access
+searvex research https://example.com --competitor https://rival.example        # coverage gaps
+searvex monitor https://example.com --fail-on high                              # regressions in CI
+searvex ecosystem https://company.example https://product.example              # related sites
+searvex review latest <ref> rejected --note "behind login"                     # record a verdict
+searvex rollback <changeId> ./my-site
+searvex gsc auth --client client_secret.json && searvex gsc report --audit latest
+searvex bing auth && searvex bing report https://example.com/                   # experimental
 ```
 
-The deterministic engine measures; the agent (Claude) explains, prioritises, researches competitors
-and drafts judgement-based changes (titles, descriptions, alt text) for the user's approval.
-Details: [docs/architecture.md](docs/architecture.md).
-
-## Security & privacy
-
-- Read-only by default. Nothing is published, submitted (e.g. IndexNow) or changed on live sites.
-- SSRF protection with connection-time DNS validation (anti-rebinding), per-redirect re-validation,
-  size and time limits; private networks require `--allow-private`.
-- robots.txt (RFC 9309) is always honoured, including for outbound link checks; per-host rate limiting,
-  `Crawl-delay`, `429/Retry-After` backoff. User agent: `SearvexBot`.
-- Repository access never follows symlinks, never reads secret files (`.env`, keys, credentials) and
-  refuses paths outside the repository.
-- Crawled content is treated as untrusted; HTML reports are rendered without `innerHTML` and with a CSP.
+| Integration | Status |
+|---|---|
+| Search Console CSV/ZIP import | supported (verified with real TR + EN exports) |
+| Search Console API (`gsc auth`) | supported (verified live) |
+| CrUX API (`crux auth`) | supported (verified live) |
+| JavaScript rendering (`--render`, Playwright) | supported |
+| Bing Webmaster API (`bing auth`) | experimental |
 
-See [docs/security.md](docs/security.md), [docs/privacy.md](docs/privacy.md) and [SECURITY.md](SECURITY.md).
+</details>
 
 ## Limitations
 
-- Website mode sees public pages only; no traffic, rankings or analytics without an integration.
-- Market data (search volumes, SERP features, backlinks) is not fetched — Searvex does not fabricate it.
-  The research skill discovers competitors via web search; volumes stay "unknown" unless you provide data.
-- AI citations cannot be observed directly; Bing Webmaster Tools AI Performance and Search Console are
-  the official sources.
-- Repository mode is static analysis: runtime-computed metadata (CMS, i18n, data fetching) is resolved
-  conservatively. Use website mode against a deployment for rendered output.
-- Analysis is in-memory: tested to 20,000 pages (~25 KB/page); very large sites need `--max-pages` or sections (`--include`).
+Website mode sees public pages only. Market data (search volumes, backlinks, SERP features) and AI citations are
+not fetched or estimated. Repository mode is static analysis: runtime-computed metadata is resolved
+conservatively. In repositories with several apps, sitemaps are left to a reviewed task because one site URL
+cannot tell which host serves which app. Full list: [docs/limitations.md](docs/limitations.md).
 
-Full list: [docs/limitations.md](docs/limitations.md).
+## Related tools
 
-## Contributing
+Complementary open-source tools by the same author — independent, not required:
+
+| | |
+|---|---|
+| [**Relivaro**](https://github.com/cihantopac/relivaro) | Software reliability, security and release readiness. |
+| [**Jourilo**](https://github.com/cihantopac/jourilo) | UX and conversion engineering in real browser journeys. |
+| [**Markilo**](https://github.com/cihantopac/markilo) | Brand identity and vector design for Claude Code. |
 
-Rules, framework adapters and fixtures are the most valuable contributions. Every rule needs an
-official source and a test fixture. See [CONTRIBUTING.md](CONTRIBUTING.md).
+## Contributing, security, license
 
-## License
+Rules, framework adapters and fixtures are the most valuable contributions — every rule needs an official source
+and a test fixture ([CONTRIBUTING.md](CONTRIBUTING.md)). Security: [SECURITY.md](SECURITY.md),
+[docs/security.md](docs/security.md), [docs/privacy.md](docs/privacy.md). Architecture:
+[docs/architecture.md](docs/architecture.md).
 
-[Apache-2.0](LICENSE). "Searvex" name availability notes: [docs/research/name-availability-2026-10.md](docs/research/name-availability-2026-10.md)
-(not legal trademark clearance).
+[Apache-2.0](LICENSE). Name availability notes: [docs/research/name-availability-2026-10.md](docs/research/name-availability-2026-10.md) (not legal trademark clearance).