prautoblogger/CONTEXT.md

# PRAutoBlogger — Domain Glossary

Per DoD v1.2.0 §7, this file defines domain terms introduced by structural changes.
Update when a PR introduces new terms not covered here.

For full design rationale see `ARCHITECTURE.md` (§21–§25) and `CONVENTIONS.md`.

---

## Pipeline Settings (introduced v0.23.0)

| Term | Definition |
|------|-----------|
| **step** | One LLM-powered stage in the article-generation pipeline (Research, Analysis, Writer, Editorial, Image). Non-LLM stages (Scoring, Publish) are not surfaced here. |
| **step rail** | The vertical navigation column in the Pipeline Settings page; one button per step. |
| **step panel** | The right-hand content area in the Pipeline Settings page that shows model, params, and prompts for the selected step. |
| **pipeline-ui** | The author tag written to the prompts table when an operator edits a prompt via the Pipeline Settings page (e.g. `pipeline-ui:rhys`). |
| **system instruction** | The system prompt for an LLM step — sets role, constraints, and style for the model. Stored in the prompt registry under a key like `research.system`. |
| **agent prompt** | A user-turn prompt for an LLM step — contains the task the model must perform. Stored under keys like `content.single_pass`, `content.draft`. |
| **system_key** | The registry key string for a step's system instruction (e.g. `research.system`). Defined in `PRAutoBlogger_Pipeline_Settings_Step_Map`. |
| **agent_key** | A registry key string for one of a step's agent/user prompts. A step may have zero or more agent keys. |
| **prompt key** | Generic term covering both system_key and agent_key — a dotted string like `content.single_pass` that uniquely identifies a prompt in the registry. |
| **prompt slug** | URL/form-safe encoding of a prompt key: dots replaced with hyphens (e.g. `content-single_pass`). Used as HTML field values and `?prompt_key=` query params. |
| **reset-to-default** | A Pipeline Settings action that creates a new prompt version with the canonical seed body (`PRAutoBlogger_Prompt_Registry::default_body()`), effectively restoring factory settings for that key. |
| **step map** | `PRAutoBlogger_Pipeline_Settings_Step_Map` — the single source of truth for step metadata, model option keys, and prompt key allowlists. |
| **save handler** | `PRAutoBlogger_Pipeline_Settings_Save_Handler` — stateless class that verifies nonce/cap, validates against allowlists, and persists model or prompt changes. |

## Prompt Registry Terms (introduced v0.16.0–v0.18.0)

| Term | Definition |
|------|-----------|
| **prompt version** | An immutable row in `wp_prautoblogger_prompts`. Once written, the body never changes; a new edit creates a new version row. |
| **active version** | The single version per prompt key flagged `is_active = 1`. Older versions are retained for history/rollback. |
| **seed** | Version 1 of a prompt key, written by the activator migration (`seed_v1()`). Author tag: `seed`. |

---

## Core Domain Terms (introduced v0.22.1)

**run**
A single end-to-end article generation cycle: orchestrate → generate idea(s) →
finalize. Represented as a row in `wp_prautoblogger_runs` (status, cost ceiling,
timestamps). One run may produce multiple articles if the daily idea-count > 1.

**run\_stages** (`wp_prautoblogger_run_stages`)
Sub-steps within a run (research, analysis, generation, publish). Each stage has
its own status and can be replayed independently via `Rerun_Executor`. Generation
checkpoint runs populate stages as Article_Worker progresses.

**checkpoint**
The persistence boundary between pipeline ticks. After each tick the idea queue
and run state are written to `wp_options` so a process kill cannot lose work. The
next tick reads the queue option and continues. See §25 of ARCHITECTURE.md.

**idea queue** (`prautoblogger_article_queue` option)
Serialized array of `Article_Idea` objects written by `on_orchestrate_tick()` and
consumed one-at-a-time by successive `on_generate_tick()` calls. Deleted on
finalize or cleanup.

**Generation\_Lock** (`wp_prautoblogger_generation_lock` or `wp_options`)
DB mutex that prevents two concurrent runs. Acquired at the start of
`on_orchestrate_tick()`, released by `Helpers::finalize()` or on error/halt.

---

## Execution Modes (introduced v0.22.1)

### Async (wp-cron driven)

Default path for the Board "New Article" button and the plain
`wp prautoblogger generate` WP-CLI command.

1. `kick_off()` schedules `prautoblogger_gen_orchestrate` and calls `fire_cron_now()`.
2. `on_orchestrate_tick()` runs in a background PHP process, schedules
   `prautoblogger_gen_tick`, and calls `fire_cron_now()` to spawn the next process.
3. Each `on_generate_tick()` spawns the next until the queue drains.

Limitation: Hostinger kills background PHP processes at ~10 min. Orchestrate tick
(LLM-free) and individual generate ticks (one LLM call each) are both well within
this limit; the checkpoint design is the mitigation.

### Sync (VPS-driven / `--sync`)

Used by the Coolify KVM8 VPS systemd timer via `infra/vps/orchestrate-generation.sh`
in `peptide-e2e`. Introduced v0.22.1.

1. `run_sync()` sets `Generation_Checkpoint_Runner::$sync_mode = true`.
2. Calls `on_orchestrate_tick()` **in-process** (no background spawn).
3. Loops calling `on_generate_tick()` directly until queue empty or terminal state.
4. `$sync_mode = true` suppresses all `wp_schedule_single_event` +
   `fire_cron_now` calls inside both tick methods, preventing a competing
   background cron chain from forming in parallel.

The VPS SSH session is held open; the process is not subject to Hostinger's
background-kill constraint.

---

## Table Shorthand

Throughout the codebase `wp_prautoblogger_*` tables are referenced by their
`$wpdb->` property names (e.g. `$wpdb->prab_runs`, `$wpdb->prab_run_stages`).
Full table names are defined in `class-activator.php`.

---

*See also: `ARCHITECTURE.md` §25 (checkpoint design), `CONVENTIONS.md` (coding rules).*

---

## Pipeline Settings M2 (v0.24.0)

| Term | Definition |
|------|-----------|
| **step context** | A routing key (`global\|research\|analysis\|writer\|editorial`) that identifies which group of option fields is being edited in the `save_step_settings` handler. Validated against the `PRAutoBlogger_Pipeline_Settings_Option_Fields::contexts()` allowlist before any write. Distinct from "step" (the display unit in the step rail) — `global` is a context with no corresponding step button. |
| **Global Content Context** | The editable form block rendered above the step rail in the Pipeline Settings page (v0.24.0). Surfaces `prautoblogger_niche_description` and any future cross-step fields. Uses `step_context=global` in its save form. Not associated with an LLM step. |
| **option field** | A `wp_option`-backed field surfaced in a step panel or the Global Content Context block. Defined in `PRAutoBlogger_Pipeline_Settings_Option_Fields_Data`. Distinct from a "prompt panel" (which edits the prompt registry). Types: `textarea`, `select`, `number`, `toggle`, `checkboxes`. |
| **step option** | Synonym for option field when it appears inside a step panel (i.e., not in the Global Content Context). |
| **`step_context`** | The POST key that routes `save_step_settings` to the correct field set. Expected values: `global`, `research`, `analysis`, `writer`, `editorial`. Validated with `sanitize_key()` before use. |
| **`pipeline_action=save_step_settings`** | POST contract key introduced in M2. Triggers `PRAutoBlogger_Pipeline_Settings_Save_Handler::handle_step_settings_save()`. Parallel to the existing `save_model`, `save_prompt`, and `reset_prompt` action values. |
| **relocated-tabs concept** | The Settings tabs `prautoblogger_models`, `prautoblogger_content`, and `prautoblogger_sources` were retired in M2; their 17 option fields moved to per-step panels in the Pipeline page. The `wp_option` keys are unchanged — only the admin UI surface that edits them moved. See `CONVENTIONS.md §Retired Settings Tabs`. |

---

## Pipeline Settings M3 (v0.25.0)

| Term | Definition |
|------|-----------|
| **assembled instructions** | The fully-rendered text the LLM actually received for a given prompt key — all `{{ token }}` placeholders substituted with live data. Surfaced in the Template/Preview toggle on the Pipeline Settings page. Preferred source: last successful `generation_log.request_json` row for the stage; fallback: sample render with `[token_name]` placeholders. |
| **Template mode** | The default view of a prompt panel: shows the editable textarea with raw template text (including `{{ token }}` placeholders). Editing here writes a new version to the prompt registry. |
| **Preview mode** | Read-only view of a prompt panel: shows the assembled instructions the LLM received in the last run (or a sample render if no run exists). No save path in PHP or JS. |
| **Template-vs-Preview guardrail** | The Template and Preview panes are mutually exclusive. Preview has no save path server-side (no write handler) or client-side (JS sends no save POST when in preview mode). Prevents accidental edits to the rendered output. |
| **version diff** | An LCS-based line-level diff between two prompt versions (or a version and the factory default). Rendered server-side as `{type, text}` lines (added/removed/context/omitted); the JS applies colours without parsing unified-diff format. Context window: 3 lines before/after each changed block. |

---

## Pipeline Settings M4 (v0.26.0)

| Term | Definition |
|------|-----------|
| **Generation History** | The `prautoblogger-gen-history` admin page: paginated list of all pipeline runs, newest first. Entry point to the per-step I/O drill-down. |
| **run row** | A single entry in the Generation History list. Corresponds to one `prautoblogger_runs` ledger row. Shows title (from linked post), date, status chip, models used, cost, duration. |
| **Stage I/O** | The inline drill-down panel for a run: shows every generation_log stage's full INPUT (system + user message content from `request_json`) and OUTPUT (model response from `run_stages.meta_json.output`). Loaded via AJAX on first toggle; cached client-side for subsequent toggles. |
| **input_system** | The `system`-role message content extracted from `generation_log.request_json`. The prompt template the LLM received. May be null for image/non-chat stages. |
| **input_user** | The last `user`-role message content from `request_json`. The rendered, token-filled instruction the LLM received. |
| **output** | The LLM's raw response text from `run_stages.meta_json.output`. Null when the stage is log-only (image_a, image_b, llm_research, image_prompt_rewrite — no run_stages row). |
| **output_pruned** | True when `run_stages.meta_json` exists but has no `output` key — indicating the output was pruned by the `prautoblogger_request_json_retention_days` setting. The UI shows an explicit message instead of a blank field. |
| **log-only stage** | A generation_log stage with no corresponding run_stages row. Image stages (image_a, image_b, image_prompt_rewrite) and llm_research fall here. Their output is null (not pruned) in the drill-down. |