# ChecontAI Content Checker - User Guide (EN)

ChecontAI Content Checker adds **editorial signals** to WordPress posts: a rule-based "human-likelihood / AI-assist risk" score, explainable reasons, and a review workflow that can optionally display a **ChecontAI Content Checker** badge on the frontend.

This plugin does **not** claim to prove authorship. Use it as an editorial tool.

---

## 1) What the plugin does

On post updates (and on demand), ChecontAI Content Checker analyzes `post_content` and stores:
- **Editorial signal** (Total): a combined score
- **Signal**: structural/technical signals (repetition, anomalies, rhythm, similarity, etc.)
- **Style**: stylistic signals (typical phrases, connectors, "corporate" patterns, etc.)
- **Quality** (if enabled in build): readability / specificity / vagueness heuristics
- **Top reasons**: the strongest factors behind the current score
- **Evidence**: examples such as repeated phrases, overused connectors, similarity matches

You also get a **review workflow**:
- `Unreviewed`
- `Needs edits`
- `Reviewed`
- `Approved`

Only when a post is set to **Reviewed/Approved** (depending on your settings) can the frontend badge be shown.

---

## 2) Where you see the UI

### On the post edit screen
A **full-width panel below the editor** shows:
- Editorial signal (Total), Signal, Style
- Risk label (Low/Medium/High)
- Contribution breakdown bar (Structure/Style/Quality/Similarity)
- Top reasons
- Evidence UI (tabs + examples)
- Review status + reviewer note

### In the post list (All Posts)
Columns and filters (if enabled in your build):
- Risk: Low / Medium / High
- Review status
- Filter by risk and status
- Bulk actions (mark status / re-run analysis)

### ChecontAI Content Checker dashboard (Admin menu)
Reports page includes:
- Recent posts analyzed
- Counts by risk and status
- Quick links to filtered post listings
- CSV export of recent results

---

## 3) How scoring works

ChecontAI Content Checker computes an **editorial signal** (Total) by combining components:
- **Structure/Signal**: repetition, sentence/paragraph rhythm, mixed scripts, unicode anomalies, template patterns
- **Style**: typical "AI-assist / corporate" phrases, connector overuse
- **Quality**: vagueness vs specificity (facts per sentence, numbers), readability heuristics
- **Similarity**: approximate similarity to previously analyzed posts (via fingerprint)

Total is then mapped to a **risk label**:
- Low risk -> higher human-likelihood / low AI-assist risk
- Medium risk -> mixed / moderate
- High risk -> likely AI-assisted / high AI-assist risk

> Important: short posts are noisy. Use the "minimum characters" setting.

---

## 4) Evidence UI (why the score is high/low)

The "Why this editorial signal" section contains:
- **Repeated phrases / openings**: repeated n-grams and repeated sentence starters
- **Connectors**: overused transitional phrases (e.g., "overall", "in conclusion", "moreover")
- **Vagueness**: hedging/vague language ratio
- **Specificity**: numbers/facts density (heuristic)
- **Readability**: long sentences, long words ratio
- **Buzzwords**: "corporate"/marketing terms density
- **Similarity**: closest matching previously analyzed post(s)
- **Mixed script**: mixed alphabet words (Latin/Cyrillic inside same token)
- **AI-assist phrases**: common "AI-like" patterns (EN)

These are heuristics designed to be **explainable**.

---

## 5) Review workflow

### Set a status
Use "Review status" dropdown on the edit screen:
- `Needs edits` -> highlight content that should be improved
- `Reviewed` -> editorially checked; badge can be enabled
- `Approved` -> stronger approval status (optional)

### Reviewer note
Use the "Reviewer note" field for internal comments.

### Frontend badge behavior
You control:
- Whether badge is enabled globally
- Whether it appears only for Reviewed/Approved
- Where to show it (top/bottom) and how to insert it (shortcode/auto)

---

## 6) Shortcodes

- `[aidr_badge]`

---

## 7) Settings reference

Depending on your build, settings may include:
- Enable/disable analysis
- Threshold for risk labels
- Weights (Signal vs Style)
- Minimum characters to analyze
- Enable admin notices
- Debug logging (OFF by default)
- Frontend badge enable/mode/position

---

## 8) Data storage (what is written to the database)

ChecontAI Content Checker stores results in `post_meta`:
- A compact JSON result (scores + reasons + evidence)
- A content hash to avoid re-analyzing unchanged posts
- Review status + reviewer note + timestamps
- Optional fingerprint (similarity)

Options are stored in `wp_options` under the plugin option key(s).

---

## 9) Troubleshooting

### "Plugin could not be activated..."
- Ensure you have only one copy of the plugin installed.
- Check `wp-content/debug.log` for the exact fatal error line.

### Score does not update
- Edit content and click Update (hash caching may skip unchanged content).
- Make sure minimum character threshold is met.

### Missing evidence
- Evidence is stored only when analysis runs.
- Re-run analysis via bulk action or force recalculation (if available).

---

## 10) For developers (hooks)
Your build may expose hooks like:
- `aidr_after_analyze($post_id, $result)`
- `aidr_status_changed($post_id, $old, $new)`

(See source for exact hook names in your version.)