# BreznGEO

![PHP 8.0+](https://img.shields.io/badge/PHP-8.0%2B-blue)
![WordPress 6.0+](https://img.shields.io/badge/WordPress-6.0%2B-21759b)
![License: GPL-2.0](https://img.shields.io/badge/License-GPL--2.0--or--later-green)
![Version](https://img.shields.io/badge/Version-1.3.0-orange)
![Tests](https://img.shields.io/badge/Tests-163%20passing-brightgreen)

🇩🇪 [Deutsche Version → README.de.md](README.de.md)

**Website:** [brezngeo.com](https://brezngeo.com)  ·  [How To](https://brezngeo.com/howto.html)  ·  [FAQ](https://brezngeo.com/faq.html)  ·  [Changelog](https://brezngeo.com/changelog.html)

---

BreznGEO is a lightweight SEO & GEO plugin for WordPress. It generates AI-powered meta descriptions, outputs Schema.org structured data, creates GEO content blocks for AI engines, and manages crawler access via robots.txt and llms.txt — all in one plugin, nothing hidden behind a paywall.

It works with or without an AI key. It integrates without conflicts into Rank Math, Yoast, AIOSEO, and SEOPress. No SaaS. No telemetry. No upsells.

---

## Why This Plugin Exists

Most WordPress SEO plugins have evolved in the same direction: bloated feature sets, dashboards full of metrics nobody needed, and a pricing model that locks the useful functionality behind a monthly subscription.

The AI wave made it worse. Plugins started offering "AI-powered" features — but as a proxy service. You pay a monthly fee, your content goes through their servers, they call the AI API on your behalf and add a margin on top.

BreznGEO takes a different approach:

- **Direct API access.** You store your own key from OpenAI, Anthropic, Google, xAI, or OpenRouter (600+ models through one key). BreznGEO calls the API directly. No middleman, no margin, no data passing through third-party servers.
- **Clear output, not noise.** Meta descriptions, structured data, GEO content blocks, bot management. No readability scores, no keyword density meters, no upsell banners.
- **No subscription.** GPL-2.0. Free to use on any number of sites. The only costs are API usage — typically fractions of a cent per post.
- **No telemetry.** BreznGEO sends no data home. No usage tracking, no remote logging, no analytics leaving your server.
- **Works without AI.** No API key? The fallback extractor generates a usable meta description from post content using sentence boundary detection. Every post gets a description.

Built in Passau, Bavaria — for [Donau2Space](https://donau2space.de), a personal AI blog, where exactly this was needed — and nothing more.

---

## Table of Contents

- [Why This Plugin Exists](#why-this-plugin-exists)
- [Directory Structure](#directory-structure)
- [Features](#features)
- [Data Storage](#data-storage)
- [Security](#security)
- [AI Providers](#ai-providers)
- [Hooks & Extensibility](#hooks--extensibility)
- [AJAX Endpoints](#ajax-endpoints)
- [Installation](#installation)
- [Tech Stack](#tech-stack)
- [License](#license)

---

## Directory Structure

```
brezngeo/
├── brezngeo.php      # Plugin header, constants (BREZNGEO_VERSION, BREZNGEO_DIR, BREZNGEO_URL)
├── uninstall.php                 # Cleanup on plugin deletion
├── assets/
│   ├── admin.css                 # Shared admin stylesheet
│   ├── admin.js                  # Provider selector, connection test
│   ├── bulk.js                   # Bulk generator AJAX loop + progress UI
│   ├── editor-meta.js            # Meta editor box: live counter, AI regen button
│   ├── geo-editor.js             # GEO block editor: generate / clear button
│   ├── geo-frontend.css          # Minimal stylesheet for .brezngeo-geo on frontend
│   ├── keyword-analysis.js        # Keyword analysis: AJAX checks, result rendering, AI handlers
│   ├── link-suggest.js           # Internal link suggestions: trigger, UI, apply (Gutenberg + Classic)
│   └── seo-widget.js             # SEO analysis widget: live evaluation in editor
├── includes/
│   ├── Core.php                  # Singleton bootstrap, loads all dependencies
│   ├── Admin/
│   │   ├── AdminMenu.php         # Menu structure + dashboard render
│   │   ├── BulkPage.php          # Bulk generator admin page
│   │   ├── GeoEditorBox.php      # GEO block meta box in post editor
│   │   ├── GeoPage.php           # GEO block settings page
│   │   ├── KeywordMetaBox.php    # Keyword analysis meta box in post editor
│   │   ├── KeywordPage.php       # Keyword analysis settings page
│   │   ├── LinkAnalysis.php      # AJAX handler for link analysis dashboard
│   │   ├── LinkSuggestPage.php   # Internal link suggestions settings page
│   │   ├── MetaEditorBox.php     # Meta description meta box in post editor
│   │   ├── MetaPage.php          # Meta generator settings page
│   │   ├── ProviderPage.php      # AI provider settings page
│   │   ├── SchemaMetaBox.php     # Schema.org per-post meta box
│   │   ├── TxtPage.php           # TXT Files page: llms.txt + robots.txt (tabbed)
│   │   ├── SchemaPage.php        # Schema.org settings page
│   │   ├── SeoWidget.php         # SEO analysis sidebar widget
│   │   ├── SettingsPage.php      # Central getSettings() — merges all option keys
│   │   └── views/                # PHP templates for all admin pages
│   ├── Features/
│   │   ├── CrawlerLog.php        # Log AI bot visits (own DB table)
│   │   ├── GeoBlock.php          # GEO Quick Overview block (frontend output)
│   │   ├── LlmsTxt.php           # /llms.txt endpoint with ETag/cache
│   │   ├── LinkSuggest.php       # Internal link suggestions: matching engine + AJAX handler + meta box
│   │   ├── KeywordAnalysis.php    # Keyword analysis engine: 10 SEO checks
│   │   ├── MetaGenerator.php     # Core logic: AI call, save, bulk, AJAX
│   │   ├── RobotsTxt.php         # robots.txt bot blocking via WP filter
│   │   └── SchemaEnhancer.php    # JSON-LD Schema.org output in wp_head
│   ├── Helpers/
│   │   ├── BulkQueue.php         # Mutex lock for bulk processes (transient-based)
│   │   ├── FallbackMeta.php      # Meta extraction from post content without AI
│   │   ├── KeyVault.php          # API key obfuscation before writing to DB
│   │   ├── KeywordVariants.php   # Locale-aware keyword variant generation (EN/DE)
│   │   └── TokenEstimator.php    # Rough token estimate for cost preview in bulk
│   └── Providers/
│       ├── ProviderInterface.php    # Interface: getId, getName, getModels, testConnection, generateText
│       ├── ProviderRegistry.php     # Registry pattern: register and retrieve providers
│       ├── AnthropicProvider.php    # Claude API (Messages API)
│       ├── GeminiProvider.php       # Google Gemini (generateContent API)
│       ├── GrokProvider.php         # xAI Grok (OpenAI-compatible endpoint)
│       ├── OpenAIProvider.php       # OpenAI GPT (Chat Completions API)
│       └── OpenRouterProvider.php   # OpenRouter (600+ models via one OpenAI-compatible API)
└── vendor/                       # Composer dependencies (production only)
```

---

## Features

### AI Meta Generator

Generates SEO-optimized meta descriptions (150–160 characters) automatically when a post is published. The prompt is fully customizable; supported placeholders: `{title}`, `{content}`, `{excerpt}`, `{language}`.

**Language detection:** The target language is automatically detected from Polylang, WPML, or the WordPress locale and passed in the prompt — no configuration needed.

**SEO plugin integration:** Generated descriptions are written not only to `_bre_meta_description` but also directly to the native field of the active SEO plugin:

| SEO Plugin | Meta Field |
|---|---|
| Rank Math | `rank_math_description` |
| Yoast SEO | `_yoast_wpseo_metadesc` |
| AIOSEO | `_aioseo_description` |
| SEOPress | `_seopress_titles_desc` |
| (none active) | BreznGEO outputs `<meta name="description">` itself |

**Token mode:** Either the full post content is sent (`full`) or it is trimmed to a configurable token count (100–8000) (`limit`). Trimming is handled by `TokenEstimator` — a word-based estimate without external libraries, using a ratio of ~0.75 words per token.

**Fallback without AI:** `FallbackMeta::extract()` always delivers a usable description — even without an API key or on error. Extraction prefers sentence boundaries (`. `, `! `, `? `), falls back to word boundaries, and only uses a hard cut with `…` as a last resort. Fully multibyte-safe via `mb_substr` / `mb_strrpos`.

---

### GEO Block (Quick Overview)

Generates AI-powered content blocks directly in post text for Generative Engine Optimization:

- **Summary** — brief overview of the post
- **Key Points** — bullet list of the most important points
- **FAQ** — question-answer pairs (only above a configurable word threshold, default: 350 words)

**Insert position** (configurable): after the first paragraph (default), top, bottom.

**Display modes:**

| Mode | Behavior |
|---|---|
| `details_collapsible` | Native HTML `<details>` — collapsed, no JavaScript needed |
| `open_always` | Block always visible |
| `store_only_no_frontend` | Store in DB only, no frontend output (e.g. for FAQPage schema) |

All labels (title, summary, key points, FAQ), the accent color, color scheme (auto/light/dark), and custom CSS are configurable via the admin page — no coding required.

**Per-post prompt add-on:** Authors can enter a custom prompt addition via a meta box in the post editor that is appended to the base prompt. Can be enabled/disabled globally.

---

### Schema.org Enhancer

Outputs JSON-LD structured data and meta tags in `<head>`. Settings under **BreznGEO → Schema.org**. Each type is individually toggleable:

| Type | Schema.org Type | Notes |
|---|---|---|
| `organization` | `Organization` | Name, URL, logo, `sameAs` links (social profiles) |
| `author` | `Person` | Author name, profile URL, optional Twitter `sameAs` |
| `speakable` | `WebPage` + `SpeakableSpecification` | CSS selectors on H1 and first paragraph |
| `article_about` | `Article` | Headline, publish/modified, description, publisher |
| `breadcrumb` | `BreadcrumbList` | Automatically suppressed when Rank Math or Yoast is active |
| `ai_meta_tags` | — | `<meta name="robots">` + `<meta name="googlebot">` with `max-snippet:-1` |
| `faq_schema` | `FAQPage` | Automatically populated from GEO block data |
| `blog_posting` | `BlogPosting` / `Article` | With embedded `author` and featured image |
| `image_object` | `ImageObject` | Featured image with dimensions and caption |
| `video_object` | `VideoObject` | YouTube/Vimeo automatically detected and embedded |
| `howto` | `HowTo` | Step-by-step guide — data via meta box in post editor |
| `review` | `Review` | Rating with `ratingValue` — data via meta box |
| `recipe` | `Recipe` | Ingredients, times, nutritional values — data via meta box |
| `event` | `Event` | Date, location, organizer — data via meta box |

---

### llms.txt

Serves `/llms.txt` and paginated follow-up files (`/llms-2.txt`, `/llms-3.txt` …) via a `parse_request` hook at priority 1 — before WordPress routing, no rewrite rule flush needed.

**File structure:**
```
# Site Title
> Description block

## Featured Links
- [Title](URL): Description

## Content
- [Title](URL): Date

---
## More
/llms-2.txt
```

**HTTP caching:**
- `ETag: "md5(content)"` → HTTP 304 on `If-None-Match`
- `Last-Modified` based on the most recent `post_modified_gmt` in the database
- `Cache-Control: public, max-age=3600`
- Transient cache is automatically invalidated on every settings change

**Rank Math conflict notice:** If Rank Math also wants to serve an llms.txt, BreznGEO shows an admin notice — BreznGEO takes precedence automatically due to priority 1.

---

### robots.txt Manager

Appends `Disallow` blocks via the WordPress filter `robots_txt` — WordPress's own robots.txt is preserved; BreznGEO only extends it.

Supported AI bots (all individually toggleable):

| User-Agent | Operator |
|---|---|
| `GPTBot` | OpenAI |
| `ClaudeBot` | Anthropic |
| `Google-Extended` | Google (Bard/Gemini training) |
| `PerplexityBot` | Perplexity AI |
| `CCBot` | Common Crawl |
| `Applebot-Extended` | Apple AI |
| `Bytespider` | ByteDance |
| `DataForSeoBot` | DataForSEO |
| `ImagesiftBot` | Imagesift |
| `omgili` | Omgili |
| `Diffbot` | Diffbot |
| `FacebookBot` | Meta |
| `Amazonbot` | Amazon |

---

### Bulk Generator

Batch processing of all published posts without a meta description. The process runs as a repeated AJAX request in the browser — no WP-Cron, no CLI required.

**Technical details:**
- 1–20 posts per batch (configurable)
- 6-second delay between batches (rate limiting against API limits)
- Up to 3 attempts per post
- Live progress log and running cost estimate in the admin UI
- **Mutex lock via transient** (`brezngeo_bulk_running`, TTL 15 minutes): prevents parallel runs across multiple browser tabs or admin users. The lock is set at start, automatically released after the last batch — or manually via button.

---

### Crawler Log

Logs visits from known AI bots in the dedicated database table `{prefix}brezngeo_crawler_log`:

| Column | Type | Content |
|---|---|---|
| `bot_name` | VARCHAR | Name of the bot (e.g. `GPTBot`) |
| `ip_hash` | CHAR(64) | SHA-256 hash of the visitor IP |
| `url` | VARCHAR(512) | Requested URL |
| `visited_at` | DATETIME | Timestamp |

**Why SHA-256 instead of plain-text IP?** The original IP is never stored. The hash satisfies the GDPR requirement of data minimization: bot patterns are identifiable (same hash = same IP), but tracing back to a person without the plain-text value is practically impossible.

Entries older than 90 days are automatically cleaned up via weekly cron (`brezngeo_cleanup_crawler_log`). The dashboard shows a 30-day summary per bot.

---

### Keyword Analysis

Meta box in the post editor that analyzes keyword usage across ten on-page SEO checks:

| Check | What it evaluates |
|---|---|
| Title | Keyword present in the post title |
| Headings | Keyword appears in at least one H2–H6 |
| Density | Keyword density within target range (default 0.5 %–2.5 %) |
| Image Alt | At least one image has the keyword in its `alt` attribute |
| Meta Description | Keyword present in the meta description |
| Slug | Keyword present in the URL slug |
| First Paragraph | Keyword appears in the opening paragraph |
| Last Paragraph | Keyword appears in the closing paragraph |
| Image Title/Caption | Keyword in at least one image `title` or `<figcaption>` |
| Excerpt | Keyword present in the post excerpt |

**Primary + secondary keywords:** The primary keyword is evaluated against all ten checks with stricter thresholds. Secondary keywords support multiple entries and use relaxed minimums.

**Update modes:** `live` (debounced while typing), `manual` (button click), or `save` (on post save).

**Locale-aware variants:** `KeywordVariants` generates compound forms (space ↔ hyphen), trailing-s, and language-specific suffixes (EN: -es, -ing, -ed; DE: -er, -en, -e) to match keyword variations automatically.

**Optional AI features** (when an API key is configured):
- **Suggest** — AI-generated keyword suggestions based on post content
- **Optimize** — content optimization tips for the current keyword
- **Semantic** — related semantic keywords for broader topic coverage

---

### Meta Editor Box

Meta box in the post editor (Classic and Block Editor):
- Source badge: `AI generated` / `Fallback` / `Manual` / `Not generated`
- Text field with `maxlength="160"` and live character counter (JavaScript, no save needed)
- "Regenerate with AI" button (only when API key is configured) — generates inline without page reload

---

### SEO Analysis Widget

Sidebar meta box in the post editor with live evaluation while writing:
- Title length (target: ≤ 60 characters)
- Word count and estimated reading time
- Heading hierarchy (H1–H6 tree)
- Counter for internal and external links
- Inline warnings: no H2, no internal link, title too long

All stats are updated live via `MutationObserver`, no manual save needed.

---

### Link Analysis (Dashboard)

AJAX widget on the plugin dashboard:
- Posts with no internal links at all
- Posts with an above-average number of external links
- Top-5 pillar pages by number of incoming internal links

Results are cached for 1 hour in the transient cache (`brezngeo_link_analysis`).

---

## Data Storage

### WordPress Options (wp_options)

| Option Key | Content |
|---|---|
| `brezngeo_settings` | Active provider, API keys (obfuscated), model selection, token costs, `ai_enabled` flag |
| `brezngeo_meta_settings` | Meta generator: auto mode, post types, token mode, prompt |
| `brezngeo_schema_settings` | Schema.org: enabled types, organization sameAs URLs |
| `brezngeo_geo_settings` | GEO block: mode, position, labels, CSS, prompt, color scheme |
| `brezngeo_robots_settings` | robots.txt: blocked bots |
| `brezngeo_llms_settings` | llms.txt: title, description, featured links, footer, page count |
| `brezngeo_keyword_settings` | Keyword analysis: update mode, target density, min occurrences, post types, debounce |
| `brezngeo_usage_stats` | Accumulated token usage: `tokens_in`, `tokens_out`, `count` |
| `brezngeo_first_activated` | Unix timestamp of first activation (used by welcome notice) |

### Post Meta (wp_postmeta)

| Meta Key | Content |
|---|---|
| `_bre_meta_description` | Generated meta description |
| `_bre_meta_source` | Source: `ai` / `fallback` / `manual` |
| `_bre_bulk_failed` | Last error during bulk attempt |
| `_bre_geo_summary` | GEO block summary |
| `_bre_geo_bullets` | GEO block key points (JSON array) |
| `_bre_geo_faq` | GEO block FAQ (JSON array) |
| `_brezngeo_keyword_main` | Primary keyword |
| `_brezngeo_keyword_secondary` | Secondary keywords (comma-separated) |
| `_brezngeo_keyword_results` | Cached analysis results (JSON) |

### Custom Database Table

| Table | Purpose |
|---|---|
| `{prefix}brezngeo_crawler_log` | AI bot visits (bot_name, ip_hash, url, visited_at) |

### Transients

| Transient | TTL | Purpose |
|---|---|---|
| `brezngeo_llms_cache_{n}` | 1 hour | Cached llms.txt content per page |
| `brezngeo_link_analysis` | 1 hour | Dashboard link analysis result |
| `brezngeo_bulk_running` | 15 minutes | Mutex lock for bulk generator |
| `brezngeo_meta_stats` | 5 minutes | Dashboard meta coverage query result |
| `brezngeo_crawler_summary` | 5 minutes | Dashboard crawler summary (last 30 days) |

### Uninstall cleanup

`uninstall.php` removes on plugin deletion:
- Options `brezngeo_settings`, `brezngeo_keyword_settings`
- Post meta `_brezngeo_meta_description`, `_brezngeo_keyword_main`, `_brezngeo_keyword_secondary`, `_brezngeo_keyword_results` for all posts

> Note: The remaining option keys and the `brezngeo_crawler_log` table are not automatically removed. For full cleanup, delete these manually.

---

## Security

### API Key Obfuscation (KeyVault)

```
Plaintext key  →  XOR(key, sha256(AUTH_KEY . SECURE_AUTH_KEY))  →  base64  →  "bre1:<base64>"
```

`BreznGEO\Helpers\KeyVault` obfuscates API keys before writing to `wp_options`:

1. A 64-byte salt is derived from the WordPress constants `AUTH_KEY` and `SECURE_AUTH_KEY` via `hash('sha256', ...)`.
2. The plaintext is XOR'd byte-by-byte (salt is repeated as needed).
3. The result is base64-encoded and prefixed with `bre1:`.

**Why XOR and not AES?** No `openssl_*` or external extension required — the code runs on any PHP 8.0+ installation without configuration. The `bre1:` prefix allows future migration to stronger encryption without a breaking change.

**Security boundary:** XOR with a static salt is obfuscation, not cryptographic encryption. An attacker with access to **both** the database **and** `wp-config.php` can reconstruct the key. For maximum security, keys can be defined as `wp-config.php` constants — these take precedence over the database version:

```php
define( 'BREZNGEO_OPENAI_KEY',     'sk-...' );
define( 'BREZNGEO_ANTHROPIC_KEY',  'sk-ant-...' );
define( 'BREZNGEO_GEMINI_KEY',     'AI...' );
define( 'BREZNGEO_GROK_KEY',       'xai-...' );
define( 'BREZNGEO_OPENROUTER_KEY', 'sk-or-...' );
```

In the admin UI, keys are always displayed masked: `••••••Ab3c9` (only the last 5 characters visible).

### CSRF Protection and Capability Checks

Every AJAX handler follows the same pattern — without exception:

```php
check_ajax_referer( 'brezngeo_admin', 'nonce' );          // CSRF
if ( ! current_user_can( 'manage_options' ) ) {      // Authorization
    wp_send_json_error( 'Unauthorized', 403 );
}
```

The nonce `brezngeo_admin` is passed to the frontend via `wp_localize_script` and validated server-side on every request. There are no `wp_ajax_nopriv_` handlers — all AJAX endpoints are exclusively accessible to logged-in users with `manage_options` capability.

### Input Validation and Output Escaping

- All `$_POST` values are processed via `wp_unslash()` + specific sanitizers (`sanitize_text_field`, `absint`, `wp_kses_post` depending on context).
- All output in admin views is escaped (`esc_html`, `esc_attr`, `esc_url`, `esc_textarea`).
- SQL queries exclusively via `$wpdb->prepare()`.
- GEO Block custom CSS is sanitized through `Helpers\Css::sanitize_declarations()` — strips comments, braces, at-rules (`@import`, `@media`, etc.), `url()`, `expression()`, and `javascript:` before injection via `wp_add_inline_style()`.

### Privacy (GDPR)

The crawler log stores IP addresses exclusively as SHA-256 hashes. The original value is never persisted. Entries are automatically deleted after 90 days.

---

## AI Providers

BreznGEO supports five providers, all implementing the same `ProviderInterface`:

| Provider | Class | API Base URL |
|---|---|---|
| OpenAI | `OpenAIProvider` | `https://api.openai.com/v1/chat/completions` |
| Anthropic | `AnthropicProvider` | `https://api.anthropic.com/v1/messages` |
| Google Gemini | `GeminiProvider` | `https://generativelanguage.googleapis.com/...` |
| xAI Grok | `GrokProvider` | `https://api.x.ai/v1/chat/completions` |
| OpenRouter | `OpenRouterProvider` | `https://openrouter.ai/api/v1/chat/completions` |

**About OpenRouter:** A single API key opens access to 600+ models from OpenAI, Anthropic, Google, Meta, Mistral, xAI, DeepSeek and others. The curated Marketing/SEO selection is fetched on demand ("Load models" button) and cached for 12 hours. Pricing is read from OpenRouter automatically. Custom model IDs (e.g. `anthropic/claude-opus-4.7`) are supported.

### Adding a New Provider

```php
// includes/Providers/YourProvider.php
namespace BreznGEO\Providers;

class YourProvider implements ProviderInterface {
    public function getId(): string    { return 'yourprovider'; }
    public function getName(): string  { return 'Your Provider'; }
    public function getModels(): array { return [ 'model-id' => 'Model Name' ]; }

    public function testConnection( string $api_key ): array {
        // Minimal API call — returns ['success' => bool, 'message' => string]
    }

    public function generateText( string $prompt, string $api_key, string $model, int $max_tokens = 300 ): string {
        // Call API, return plain text — throw \RuntimeException on error
    }
}
```

Register in `includes/Core.php` → `register_hooks()`:

```php
$registry->register( new Providers\YourProvider() );
```

The provider automatically appears in all admin dropdowns, the provider settings page, and the cost overview of the bulk generator.

---

## Hooks & Extensibility

### `brezngeo_prompt` (Filter)

Allows modifying the final prompt immediately before the API call.

```php
add_filter( 'brezngeo_prompt', function( string $prompt, WP_Post $post ): string {
    $keyword = get_post_meta( $post->ID, 'focus_keyword', true );
    return $keyword ? $prompt . "\nFocus keyword: {$keyword}" : $prompt;
}, 10, 2 );
```

### `brezngeo_meta_saved` (Action)

Fired after a meta description is successfully saved — both on automatic generation at publish and on manual regen in the editor.

```php
add_action( 'brezngeo_meta_saved', function( int $post_id, string $description ): void {
    // e.g. sync with external system or cache invalidation
    my_cdn_purge( get_permalink( $post_id ) );
}, 10, 2 );
```

### Adding a New Feature

1. Create `includes/Features/YourFeature.php` with a `register()` method that registers WordPress hooks.
2. In `includes/Core.php` → `load_dependencies()`: `require_once BREZNGEO_DIR . 'includes/Features/YourFeature.php';`
3. In `includes/Core.php` → `register_hooks()`: `( new Features\YourFeature() )->register();`

---

## AJAX Endpoints

All endpoints are exclusively accessible to logged-in users with `manage_options` (no `nopriv`).

| Action | Handler | Description |
|---|---|---|
| `brezngeo_regen_meta` | `MetaEditorBox::ajax_regen` | Regenerate meta description for a single post |
| `brezngeo_test_connection` | `ProviderPage::ajax_test_connection` | Test API key and connection |
| `brezngeo_get_default_prompt` | `ProviderPage::ajax_get_default_prompt` | Reset to default prompt |
| `brezngeo_openrouter_load_models` | `ProviderPage::ajax_openrouter_load_models` | Fetch curated OpenRouter marketing/SEO model list (12 h transient cache) |
| `brezngeo_link_analysis` | `LinkAnalysis::ajax_analyse` | Run link analysis for the dashboard |
| `brezngeo_link_suggestions` | `LinkSuggest::ajax_suggest` | Return top-10 internal link suggestions for current post |
| `brezngeo_geo_generate` | `GeoEditorBox::ajax_generate` | Generate GEO block for a single post |
| `brezngeo_geo_clear` | `GeoEditorBox::ajax_clear` | Clear GEO block data for a single post |
| `brezngeo_llms_clear_cache` | `TxtPage::ajax_clear_cache` | Clear llms.txt transient cache |
| `brezngeo_dismiss_llms_notice` | `LlmsTxt::ajax_dismiss_notice` | Dismiss Rank Math conflict admin notice |
| `brezngeo_dismiss_welcome` | `AdminMenu::ajax_dismiss_welcome` | Dismiss the welcome notice per user |
| `brezngeo_bulk_generate` | `MetaGenerator::ajaxBulkGenerate` | Process next batch in bulk generator |
| `brezngeo_bulk_stats` | `MetaGenerator::ajaxBulkStats` | Retrieve progress and stats of running bulk |
| `brezngeo_bulk_release` | `MetaGenerator::ajaxBulkRelease` | Manually release bulk mutex lock |
| `brezngeo_bulk_status` | `MetaGenerator::ajaxBulkStatus` | Check bulk lock status |
| `brezngeo_keyword_analyze` | `KeywordMetaBox::ajax_analyze` | Run keyword analysis for a post |
| `brezngeo_keyword_ai_suggest` | `KeywordMetaBox::ajax_ai_suggest` | AI keyword suggestions |
| `brezngeo_keyword_ai_optimize` | `KeywordMetaBox::ajax_ai_optimize` | AI content optimization tips |
| `brezngeo_keyword_ai_semantic` | `KeywordMetaBox::ajax_ai_semantic` | AI semantic keyword analysis |

---

## Installation

**Via GitHub Release (recommended):**
1. Download `brezngeo.zip` from the [latest release](https://github.com/noschmarrn/brezngeo/releases/latest)
2. In WordPress go to *Plugins → Add New → Upload Plugin*

**Manual (clone):**
```bash
cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/noschmarrn/brezngeo.git brezngeo
wp plugin activate brezngeo
```

**After activation:**
1. Go to *BreznGEO → AI Provider*, select your provider and enter your API key
2. Run the connection test
3. Go to *Meta Generator*, enable auto mode and select post types

The plugin has no JavaScript build step. All assets under `assets/` are direct JS/CSS files without transpiling or bundling.

---

## Tech Stack

| Component | Technology |
|---|---|
| Backend | PHP 8.0+, WordPress Plugin API |
| Namespace | `BreznGEO\` |
| Architecture | Singleton core, registry pattern (providers), feature classes with `register()` |
| Database | WordPress Options API, `wpdb` (custom table for CrawlerLog) |
| Caching | WordPress transients (llms.txt, link analysis, bulk lock) |
| Frontend | Vanilla JS + jQuery (WordPress-bundled), no build step |
| i18n | `.pot` file, text domain `brezngeo` |
| Tests | PHPUnit (163 tests, 311 assertions) |
| Coding standard | WordPress PHPCS |
| License | GPL-2.0-or-later |

---

## License

GPL-2.0-or-later — [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html)

Copyright (c) 2025–2026 [Donau2Space](https://donau2space.de)