prautoblogger/CONVENTIONS.md

# PRAutoBlogger — Conventions

This document codifies the naming patterns, coding conventions, and step-by-step guides for extending PRAutoBlogger. Update this file whenever a new pattern is introduced.

---

## Naming Conventions

### PHP Classes
- **Format:** `PRAutoBlogger_{PascalCase}` (e.g., `PRAutoBlogger_Content_Generator`)
- **File naming:** `class-{kebab-case}.php` (e.g., `class-content-generator.php`)
- **Interfaces:** `interface-{kebab-case}.php` with `PRAutoBlogger_{Name}_Interface` class name

### Hooks (Actions & Filters)
- **Prefix:** All hooks start with `prautoblogger_`
- **Actions:** `prautoblogger_{event}` (e.g., `prautoblogger_before_content_generation`)
- **Filters:** `prautoblogger_filter_{what}` (e.g., `prautoblogger_filter_article_idea_score`)
- **Hook callbacks registered in:** `class-prautoblogger.php` (central loader), never in the classes themselves

### Database
- **Table prefix:** `{$wpdb->prefix}prautoblogger_` (e.g., `wp_prautoblogger_source_data`)
- **Option prefix:** `prautoblogger_` (e.g., `prautoblogger_openrouter_api_key`)
- **Post meta prefix:** `_prautoblogger_` (underscore prefix hides from custom fields UI)
- **Transient prefix:** `prautoblogger_` (e.g., `prautoblogger_reddit_token`)

### Constants
- **Format:** `PRAUTOBLOGGER_{UPPER_SNAKE}` (e.g., `PRAUTOBLOGGER_MAX_RETRIES`)
- **Defined in:** `prautoblogger.php` (bootstrap file) for global constants

### Hook Callback Methods
- **Action callbacks:** Prefixed with `on_` (e.g., `on_daily_generation_triggered`)
- **Filter callbacks:** Prefixed with `filter_` (e.g., `filter_content_quality`)

---

## Error Handling & Logging

### Structured Logger
All logging uses `PRAutoBlogger_Logger` (singleton) instead of raw `error_log()`. The logger writes to the `prab_event_log` custom table and forwards errors/warnings to PHP's `error_log()` for server-level monitoring. The verbosity threshold is user-configurable via Settings → Publishing → Log Level.

**Never call `error_log()` directly.** Always use the Logger:

```php
$logger = PRAutoBlogger_Logger::instance();
$logger->error( 'API call failed: ' . $error_message, 'openrouter' );
$logger->warning( 'Budget nearing limit.', 'cost-tracker' );
$logger->info( 'Pipeline complete: 3 posts generated.', 'pipeline' );
$logger->debug( 'Token counts: prompt=1200, completion=800', 'openrouter' );
```

### Log levels (ascending verbosity)
| Level   | Numeric | Use for |
|---------|---------|---------|
| error   | 0       | Failures: API errors, parse failures, DB write failures |
| warning | 1       | Degraded behavior: budget approaching, missing providers, fallback pricing |
| info    | 2       | Key events: pipeline start/stop, articles generated, metrics collected |
| debug   | 3       | Verbose detail: token counts, timing, skipped posts, intermediate values |

### Context strings
The second argument to every log call is a short context tag identifying the origin:
`pipeline`, `scheduler`, `collector`, `analyzer`, `editor`, `openrouter`, `reddit`, `ga4`, `metrics`, `cost-tracker`, `encryption`.

### What gets shown to the user
- API key issues → admin notice (persistent until resolved)
- Budget exceeded → admin notice + email to site admin
- Generation failures → logged to `prab_generation_log` with `response_status = 'error'`
- Generation failures also shown in the admin dashboard widget
- All log entries visible in PRAutoBlogger → Activity Log (filterable by level)

### What gets retried
- LLM API calls: exponential backoff, max 3 retries, then fail loudly
- Reddit API calls: exponential backoff, max 3 retries, then skip this collection cycle
- **Never retry silently.** Every retry is logged. Every final failure is surfaced.

### Error severity levels
1. **Fatal:** Plugin cannot function (missing API key, budget exhausted) → admin notice, stop all scheduled jobs
2. **Retriable:** Transient API failure → retry with backoff, log each attempt
3. **Skippable:** Single post generation failed → log, skip this post, continue with others

---

## How To: Add a New LLM Provider

1. Create `includes/providers/class-{name}-provider.php`
2. Implement `PRAutoBlogger_LLM_Provider_Interface` (see `interface-llm-provider.php`)
3. Required methods: `send_chat_completion()`, `get_available_models()`, `estimate_cost()`
4. Add provider option to the settings page in `admin/class-admin-page.php`
5. Register the provider in `class-prautoblogger.php` loader
6. Update ARCHITECTURE.md external API integrations table

### Interface contract:
```php
interface PRAutoBlogger_LLM_Provider_Interface {
    public function send_chat_completion(array $messages, string $model, array $options = []): array;
    public function get_available_models(): array;
    public function estimate_cost(string $model, int $prompt_tokens, int $completion_tokens): float;
    public function get_provider_name(): string;
}
```

---

## How To: Add a New Source Provider (Social Platform)

1. Create `includes/providers/class-{platform}-provider.php`
2. Implement `PRAutoBlogger_Source_Provider_Interface` (see `interface-source-provider.php`)
3. Required methods: `collect_data()`, `get_source_type()`, `validate_credentials()`
4. Add API credentials fields to the settings page in `admin/class-admin-page.php`
5. Register the provider in `class-prautoblogger.php` loader
6. Add the source type string to the `ab_source_data.source_type` allowed values
7. Update ARCHITECTURE.md file tree and external API integrations table

### Interface contract:
```php
interface PRAutoBlogger_Source_Provider_Interface {
    public function collect_data(array $config): array; // Returns PRAutoBlogger_Source_Data[]
    public function get_source_type(): string;           // e.g., 'reddit', 'tiktok'
    public function validate_credentials(): bool;
    public function get_rate_limit_status(): array;
}
```

---

## How To: Add a New Image Provider

1. Create `includes/providers/class-{name}-image-provider.php`
2. Implement `PRAutoBlogger_Image_Provider_Interface` (see `interface-image-provider.php`)
3. Required methods: `generate_image()`, `estimate_cost()`, `get_provider_name()`, `validate_credentials_detailed()`
4. Split helpers into companions if you'd exceed the 300-line cap. The Cloudflare provider splits into provider + pricing + validator — mirror that shape.
5. Add API credentials fields to `admin/class-settings-fields.php` under the `prautoblogger_images` section
6. Register the provider in `class-prautoblogger.php` loader once the image pipeline lands (commit 1b of the image workstream)
7. Update `ARCHITECTURE.md` file tree, external API integrations table, and the options table

### Interface contract:
```php
interface PRAutoBlogger_Image_Provider_Interface {
    public function generate_image( string $prompt, int $width, int $height, array $options = [] ): array; // {bytes, mime_type, width, height, model, seed, cost_usd, latency_ms}
    public function estimate_cost( int $width, int $height, array $options = [] ): float;
    public function get_provider_name(): string;                                   // e.g., 'cloudflare_workers_ai'
    public function validate_credentials_detailed(): array;                         // {status, message, debug?}
}
```

### Retry + cost rules (non-negotiable)
- 5xx / 429 / network errors: retry with exponential backoff up to `PRAUTOBLOGGER_MAX_RETRIES`, respect `Retry-After` when present.
- 4xx other than 429: fail loudly on the first response — never retry a deterministic bad request.
- Validation check must be non-destructive (no image generation).
- Every attempt logs via `PRAutoBlogger_Logger` with context `{provider-slug}-image`.

---

## How To: Tune the Image Composer (v0.17.0+)

The deterministic composer (ARCHITECTURE.md #21) renders branded variants between
provider bytes and sideload. Three rules when touching it:

1. **Geometry lives in code, not settings.** All sizes/colors/opacities come from
   `PRAutoBlogger_Image_Composer_Layout::defaults()` and can be overridden via the
   `prautoblogger_image_compose_layout` filter:
   ```php
   add_filter( 'prautoblogger_image_compose_layout', function ( array $layout ): array {
       $layout['featured']['mark_opacity'] = 0.40;
       return $layout;
   } );
   ```
   Promote a value to a settings field only on explicit CEO request.
2. **Keep renderer classes WP-free.** `Image_Composer_Imagick`, `Image_Composer_Canvas`,
   and `Image_Composer_Layout` must not call WordPress functions — they are exercised by
   a standalone render harness (and the determinism test) without a WP bootstrap. Only
   the orchestrator (`Image_Composer`) and the GD rung (`Image_Composer_Editor`) may
   touch WP APIs.
3. **Never fatal a publish.** Any new render path needs a try/catch that degrades to
   pass-through and logs at most one WARNING per run (`warn_once()`). Capability checks
   go through the cached probe (`prautoblogger_image_compose_capability` option +
   same-named override filter) — never re-probe per image.

Adding a new variant role: extend `Layout::defaults()` + the renderer, whitelist the
role in `Image_Composer::configured_variants()` and in
`Image_Attacher::ROLE_POST_META` (new `_prautoblogger_{role}_image_id` post meta keeps
the uninstall prefix-sweep effective), then cover it in the unit ladder tests.

---

## How To: Add a New Admin Setting

1. Define the option key in the settings array in `admin/class-admin-page.php` → `get_settings_fields()` method
2. Format: add an entry to the appropriate section array:
   ```php
   [
       'id'          => 'prautoblogger_new_setting',
       'label'       => __('Setting Label', 'prautoblogger'),
       'type'        => 'text', // text, number, select, textarea, checkbox, password
       'default'     => '',
       'description' => __('Help text shown below the field.', 'prautoblogger'),
       'sanitize'    => 'sanitize_text_field', // sanitization callback
   ]
   ```
3. The settings page renderer handles registration, rendering, and sanitization automatically from this array.
4. Access the setting anywhere with: `get_option('prautoblogger_new_setting', $default)`
5. For encrypted settings (API keys): use `PRAutoBlogger_Encryption::encrypt()` / `decrypt()`

---

## How To: Add a New Pipeline Stage

Writing stages are methods on `Content_Generator` that delegate to its `execute_stage()`
helper (Opik span + LLM dispatch + cost log + run-stage state in one place).

1. Add the stage method to `class-content-generator.php` and call
   `$this->execute_stage( $stage, $span_name, $user_prompt, $request, $model, $options )`
2. Wire it into `generate_multi_step()` (or the relevant mode path)
3. Add the stage to `PRAutoBlogger_Stage_Display_Map` (label, default agent role, prompt key)
   and — if it has registry-managed copy — a prompt key in the defaults classes
4. Cost logging and per-run stage state (idempotent resume, output snapshot) come free from
   `execute_stage()`; the per-run cost governor guards the call inside the provider
5. If a stage fails after retries, the entire pipeline fails (no partial publishes); the
   stage row is failed by the worker's catch-all and the run is swept by Run_Reaper

---

## How To: Add a New Frontend Component

Frontend components use `wp.element` (WordPress-bundled React) — no JSX, no build step.

1. Create the PHP class in `includes/frontend/class-{name}.php`:
   - Register a shortcode via `add_shortcode()` in an `on_register_shortcode()` method
   - Register a REST endpoint if the component needs async data (in `on_register_rest_route()`)
   - Enqueue JS (`wp-element` dependency) and CSS via `wp_enqueue_script/style()`
   - Pass config to JS via `wp_localize_script()`

2. Create JS in `assets/js/{name}.js`:
   - Use `wp.element.createElement` (aliased as `el`) for rendering
   - Import hooks: `var useState = wp.element.useState;`
   - Read config from `window.{localizedObjectName}`
   - Handle all states: loading, loaded, empty, error
   - Mount into the shortcode's `<div id="...">` mount point

3. Create CSS in `assets/css/{name}.css`:
   - Use Peptide Starter theme CSS custom properties with fallbacks: `var(--color-text-primary, #f9fafb)`
   - Prefix all classes with `prab-` to avoid collisions
   - Include responsive breakpoints, focus-visible states, and loading skeletons

4. Wire hooks in `class-prautoblogger.php`:
   - Instantiate the PHP class in `register_frontend_hooks()`
   - Register shortcode on `init`, REST routes on `rest_api_init`

5. Add `'frontend/'` to the autoloader's `$directories` array (already done for the first component)

6. Update ARCHITECTURE.md file tree and add a data flow section

### REST endpoint conventions:
- Namespace: `prautoblogger/v1`
- Permission callback: use a filter hook for extensibility (e.g., `prautoblogger_rest_{name}_public`)
- Sanitize all params with `sanitize_callback` in arg registration
- Return only the fields the frontend needs — no unnecessary data
- Set `Cache-Control` header for cacheable responses

---

## Code Quality Rules

1. **`declare(strict_types=1);`** in every PHP file
2. **Type declarations** on all method parameters, return types, and class properties
3. **No file exceeds 300 lines.** Split when approaching this limit
4. **Every class has a 3-question preamble docblock:** What / Who triggers / Dependencies
5. **Every public method has a docblock** with `@param`, `@return`, and side effects
6. **`@see` references** at the top of files that participate in multi-class flows
7. **All strings translatable** via `__()` / `_e()` with `prautoblogger` text domain
8. **No magic methods** without explicit justification documented in code
9. **No `echo` of raw data** — always escape with `esc_html()`, `esc_attr()`, etc.
10. **Nonce on every form/AJAX** — `wp_nonce_field()` / `check_ajax_referer()`


## How To: Add an OpenRouter model picker field (v0.11.0+)

Use the `model_select` field type to let admins choose OpenRouter models with a searchable dropdown, capability filtering, and estimated cost preview based on usage history.

### 1. Declare the field in `class-settings-fields.php`

```php
[
    'id'          => 'my_plugin_model',
    'label'       => __( 'My Model Setting', 'my-plugin' ),
    'type'        => 'model_select',
    'section'     => 'my_plugin_settings',
    'default'     => 'anthropic/claude-3.5-haiku',
    'capability'  => 'text→text',  // see ARCHITECTURE.md §18 for all capability strings
    'description' => __( 'Choose a model...', 'my-plugin' ),
    'badge'       => __( 'Quality', 'my-plugin' ),
],
```

### 2. Map the setting to pipeline stages (for cost preview)

If you want cost preview to work, add your setting ID and stage list to the `get_stages_for_setting()` method in `includes/admin/fields/class-open-router-model-field.php`:

```php
private static function get_stages_for_setting( string $field_id ): array {
    $map = [
        'prautoblogger_analysis_model'     => [ 'analysis' ],
        'prautoblogger_writing_model'      => [ 'outline', 'draft', 'polish' ],
        'prautoblogger_editor_model'       => [ 'review' ],
        'my_new_model_setting'             => [ 'my_stage' ],  // ADD HERE
    ];
    return $map[ $field_id ] ?? [];
}
```

The cost preview queries `get_avg_tokens_for_stages()` on the Cost Tracker to show estimated cost per generation based on the last 30 days of usage.

### 3. That's it

The field renderer, AJAX refresh, model picker JS, and capability filtering are already wired. The admin will see a "Refresh Model List" button on the AI Models tab (or whichever tab contains the picker field).

### Capability strings (locked in v0.11.0)

- `text→text` — text input, text output (default for analysis/writing/editor)
- `text+image→text` — vision models
- `text+audio→text` — audio input models
- `text→image` — image generation
- `text→audio` — voice synthesis
- `text→video` — video generation
- `text→embedding` — embeddings

Phase 3 will add provider selection; v0.11.0 is OpenRouter-only.

## How To: Change a Pipeline Prompt (v0.18.0+)

Prompt copy is **versioned data**, not code. The bodies live in
`wp_prautoblogger_prompts` (one ACTIVE version per key); the hardcoded texts in
`class-prompt-defaults.php` / `class-prompt-defaults-editorial.php` are the canonical v1 seed
AND the fallback when the table is unavailable — never edit a stored version in place.

1. **Never `UPDATE` a body.** Create a new version and activate it:
   ```php
   $v = PRAutoBlogger_Prompt_Registry_Writer::create_version(
       'content.polish', $new_body, $model, $params, 'your-name', true
   );
   ```
2. **Keys** are dot-namespaced: `content.system`, `content.single_pass`, `content.outline`,
   `content.draft`, `content.polish`, `analysis.system`, `analysis.user`, `editor.system`,
   `editor.review`, `research.system`, `image.rewriter_system`, `image.style_template`.
   The two `image.*` keys are the image-composer seam — coordinate on the convo thread
   before touching them.
3. **Tokens** use the `{{ name }}` syntax (exactly one space each side — same convention as
   the Style Template's `{{ topic_summary }}`). Token VALUES are computed by code
   (`Content_Prompts`, `Analysis_Prompts`, `Chief_Editor`); a new prompt version may reorder
   or drop tokens but must not invent new ones without adding the value at the call site.
4. **Pinning.** A run pins the active version of every key at start
   (`runs.pinned_prompts_json`, written by `Cost_Tracker::set_run_id()`); every
   generation_log row is stamped with the pinned `prompt_version`. Activating a new version
   affects the NEXT run, never a run in flight.
5. **Call sites** render via `PRAutoBlogger_Prompt_Registry::render( $key, $tokens )` and
   must keep working when the table is absent (the registry falls back to the defaults
   automatically — do not add your own fallback).
6. If you add a key: define the body in the appropriate defaults class, add it to `defs()`,
   map its stage in `Stage_Display_Map`, and it will seed on the next migration pass.

## Git Workflow — PR-Gated, Soft-Enforced

This repo is private on GitHub's free plan, which does not support branch protection or rulesets. The review gate is enforced at the agent layer, not server-side. Every agent and human contributor follows these rules; the `.github/workflows/main-push-audit.yml` tripwire opens an audit issue on any direct push to `main` that did not come from a merged PR.

### Rules

1. **Never push to `main` directly.** Every change lands via a pull request that the maintainer merges. No self-merging. No force-pushing to `main`.

2. **Branch naming**: `claude/<scope>-<YYYYMMDD>` for agent-authored work, `fix/<scope>` or `feat/<scope>` for human-authored. The scope is a 1–3 word kebab-case description.

3. **Commit trailer**: every commit authored by an agent must end with an `Agent-Session:` trailer so commits can be correlated back to the conversation that produced them, even though all commits share the `peptiderepo` bot identity.

   ```
   feat: add per-request cost tracking

   Agent-Session: cowork-2026-04-14-cost-audit
   ```

4. **PR description template**: every PR description covers
   - **What changed** (one paragraph)
   - **Why** (motivation or incident link)
   - **Risk flags** (schema changes, API contract changes, cost impact, compatibility)
   - **Test plan** (what was run locally, what to smoke-test after merge)

5. **Emergency push exception**: if a situation genuinely requires pushing to `main` without a PR (site down, CI broken, one-line hotfix), surface it in the chat before doing it. Every emergency push gets a follow-up PR that commits the same changes through the normal flow so git stays the source of truth. The tripwire will open an audit issue — close it with a comment explaining why.

### Opening a PR from an agent session

The `gh` CLI is not installed in the Cowork sandbox. Use `curl` with the PAT from the workspace `.env.credentials`:

```bash
GH_TOKEN=$(grep "^GITHUB_PAT=" "$WORKSPACE/.env.credentials" | cut -d= -f2)

git push -u origin HEAD

curl -s -X POST -H "Authorization: token $GH_TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.github.com/repos/peptiderepo/<repo>/pulls" \
  -d "$(jq -cn --arg title "<title>" --arg head "<branch>" --arg body "<body>" \
      '{title:$title, head:$head, base:"main", body:$body}')"
```

### When this changes

If the peptiderepo GitHub account is ever upgraded to Pro (or the repo goes public), replace this soft-enforcement section with a note pointing to the real branch protection rules in repo settings.
## Instrumenting a New LLM Call Site for Opik (v0.12.0+)

When you add a new LLM call (via `$llm->send_chat_completion()`), follow this pattern to capture it in Opik:

### 1. Get the trace context

At the start of your method, grab the per-request singleton:

```php
$ctx = PRAutoBlogger_Opik_Trace_Context::current();
```

### 2. Start the span

Before the LLM call, declare a span with metadata:

```php
$span_id = $ctx->start_span(
	array(
		'name'     => 'my_llm_operation',  // kebab-case, descriptive
		'type'     => 'llm',
		'model'    => $model,               // e.g. 'gpt-4', from get_option()
		'provider' => 'openrouter',         // or the actual provider name
		'input'    => array( 'key' => 'value' ), // optional metadata (no full prompts!)
	)
);
```

### 3. Make the LLM call (unchanged)

```php
$response = $this->llm->send_chat_completion(
	array(
		array( 'role' => 'system', 'content' => $system_prompt ),
		array( 'role' => 'user', 'content' => $user_prompt ),
	),
	$model,
	array( 'temperature' => 0.7, 'max_tokens' => 4000 )
);
```

### 4. End the span with output

After the response, record the outcome:

```php
$ctx->end_span(
	$span_id,
	array(
		'output' => array( 'response_length' => strlen( $response['content'] ?? '' ) ),
		'usage'  => array(
			'prompt_tokens'     => $response['prompt_tokens'],
			'completion_tokens' => $response['completion_tokens'],
			'total_tokens'      => $response['prompt_tokens'] + $response['completion_tokens'],
		),
	)
);
```

### Key rules

- **Never log full prompts.** Use prompt hashes or version tags in `input`. Full text blows payload size and leaks content policy.
- **Check the feature flag at call-site level?** No. The singleton is always available; Opik_Dispatcher checks the flag before dispatch.
- **Async dispatch?** Yes. Spans are queued; dispatch happens via `prautoblogger_opik_dispatch` cron (no blocking).
- **Cost logging?** Unchanged. Your `cost_tracker->log_api_call()` remains separate from Opik; Opik is observability-only.

### Example: minimal instrumentation

```php
public function my_operation( $input ) {
	$model = get_option( 'my_model', 'default-model' );
	$ctx = PRAutoBlogger_Opik_Trace_Context::current();

	$span_id = $ctx->start_span(
		array(
			'name'     => 'my_operation',
			'type'     => 'llm',
			'model'    => $model,
			'provider' => 'openrouter',
		)
	);

	$response = $this->llm->send_chat_completion( /* ... */ );

	$ctx->end_span(
		$span_id,
		array(
			'usage' => array(
				'prompt_tokens'     => $response['prompt_tokens'],
				'completion_tokens' => $response['completion_tokens'],
				'total_tokens'      => $response['prompt_tokens'] + $response['completion_tokens'],
			),
		)
	);

	return $response['content'];
}
```

That's it. No config, no feature-flag checks, no try/catch needed.