Surfaces

WordPress plugin v0.20.0

The flagship surface and the most complete implementation of Red Pen. A logged-in Dev Mode overlay on the site front end, plus a full notes repository in wp-admin - all from a single self-contained plugin file.

At a glance Editors and admins flip on Dev Mode and drop typed notes, pinned to elements, anywhere on the front end. Every note collects on the post's edit screen and in one shared repository. Free, no license keys, no premium tier, no third-party services. Dev credit: Lincoln Tracy / Tracy Digital Media.

What it is

Reviewing a WordPress site usually means a messy spreadsheet, a thread of "the about page has a typo", or comments scattered across email. Red Pen puts the note where you found the problem - on the page itself - and collects every note in one place your whole team can see. It is good for editorial review, client hand-offs, content audits, QA passes, and shared to-do lists.

The plugin has two halves that share one data store:

The front-end overlay - a floating button (bottom right) shown only to logged-in users who can edit posts. This is where you leave, pin, and reply to notes while looking at the live page.
The repository - an admin screen under Tools in wp-admin listing every note across the whole site, with filters and one-click status changes. There is also a per-post meta box on each edit screen showing that page's notes.

Install and activate

Copy the wp-red-pen folder to wp-content/plugins/ (or upload the zip via Plugins -> Add New -> Upload).
Activate it. There is no build step and no settings you must configure to start - it is a single self-contained wp-red-pen.php with inline CSS and JS.
Click Red Pen: Off in the admin bar to turn Dev Mode on for your account.
Open any post or page on the front end and use the floating button.
Review everything under the Red Pen repository in wp-admin (under Tools).

Local fleets Red Pen is a default-workflow plugin on local development installs. A deploy-to-installs.sh script scans the local web root and deploys/activates the current build across every WordPress install at once, so the whole fleet stays on the same version.

Dev Mode

Red Pen is invisible until a logged-in user with the edit_posts capability (editors and admins) turns on Dev Mode from the admin-bar toggle. Dev Mode is per user - flipping it on affects only your account, so a client and a developer logged into the same site can have it on or off independently.

The admin-bar item reads Red Pen: On / Red Pen: Off and carries an open-note count badge, mirrored on the floating button, so you always see how many notes are still open.
Logged-out visitors never receive the Red Pen assets at all - the capability check happens before any CSS or JS is enqueued. There is no way for an end user to see or trigger the overlay.
A global "Where Red Pen appears" setting controls which views show the button - singular posts and pages, archives, taxonomy pages, the home/front page, search, and 404. It defaults to everywhere.

Leaving a note

With Dev Mode on, the floating button opens the note panel. From there you can:

Type a note with a type - note, suggested edit, bug/problem, or question - plus a priority of Low, Normal, or High. Custom note types with their own colour flag are supported too.
Set a severity (optional) - under More, next to Priority, tag the note's impact as Blocker, Critical, Major, Minor, or Trivial. Severity is the impact axis where priority is the scheduling one (see Severities); it is left unset by default, dev-only (client reviewers never see it), and shows on the note, in the CSV export, and on the Hub board.
Pin to an element - the "Pin to element" picker lets you click any element on the page to anchor the note to it. Anchored notes appear as numbered markers on the page; clicking a marker opens its note, and the note can jump you back to the element.
Snip a screenshot - click Screenshot, drag a box around the area, and the region is captured client-side (via vendored html2canvas) and stored as a small WebP in uploads/wp-red-pen/, attached to the note.
Set the reporting level - target This page (the exact post or archive you are on) or This template (the view type, so the note covers every page rendered the same way). A page shows its own notes plus the template notes that apply to it.

Every note also records auto-context - the browser, OS, and viewport it was created in - so a layout bug carries the environment it happened in.

Editing a note

Any note can be edited after it is added - change the text, type, priority, or assignee; swap, remove, or add a screenshot; and re-pin, move, or clear the attached element. The front-end panel has full editing.

Statuses, priorities, and replies

Red Pen models a real triage flow, not just sticky notes.

Three-state workflow - every note is Open, In progress, or Resolved. Resolve and reopen are one click; In progress sits between the two for work that is underway.
Priority - Low, Normal, or High, surfaced as a column and a filter in the repository.
Threaded replies - reply to any note from the panel to build a discussion under it. Replies are stored as child notes of the parent.

Assignee and agent

WordPress is the surface where assignment is fully implemented today. A note carries two distinct, complementary fields:

Assignee - a WordPress user the note is assigned to (a real person). The repository adds an Assigned column and an "Assigned to me" filter. This is the manual-work lane.
Agent - an AI agent slug (for example a coding agent's handle). An empty agent means a human note; a set agent marks the note as automated work, and the REST API can return just the notes targeted at a given agent. This is the automated-work lane.

Why two fields Keeping a human assignee separate from an agent slug lets a board distinguish manual from automated tasks at a glance. This model is the reference the other surfaces and the Hub will adopt as assignment rolls out to them.

The repository

The shared repository admin page lists every note across the site. You can filter by Open / In progress / Resolved / All, by priority, and by assignee ("Assigned to me"), and resolve or reopen any note with one click. A CSV export dumps the current view (honouring the active filters) for handing off or archiving - generated locally, with no external service. Each post's edit screen also carries a meta box listing that page's notes inline.

Client review links v0.13.0, free

The reason this surface exists for client work: you can let a non-technical client leave pinned notes on a site without a WordPress login. From the "Client review links" panel (under Tools, alongside the Hub settings) you generate a labelled, shareable link. Send it privately to your client; they open it, click the red button, and leave typed notes and replies pinned to the page - the same overlay you use, in a restricted "reviewer mode". This is free core, never gated.

What a reviewer can and cannot do

Reviewer mode is a deliberately narrow door. A link holder can open the overlay, pin notes to elements, leave typed notes (type and priority), reply, and see the open notes already on the page. A link holder cannot resolve, reopen, edit, delete, or assign notes, cannot open the admin repository, cannot view screenshots, and never sees the user list, the agent options, or any other reviewer link. The boundary is enforced on the server, not just hidden in the interface.

Managing links

Generate with a label (the client or project name) and an optional expiry (never, 7, 30, or 90 days). The full URL is shown once at creation - copy it then, because only a hash is stored and it cannot be displayed again.
Revoke any link instantly from the active-links table. A revoked link stops working on the next request.
Triage reviewer feedback in the repository: reviewer notes carry a red "Client" badge and the reviewer's name, and a Source filter (All / Client reviews / Dev notes) narrows the list so you can review or bulk-action client feedback on its own.

Share it privately A review link is a bearer link - anyone who has it can leave notes, so share it with your client directly rather than posting it publicly. Abuse is bounded by a per-visitor rate limit and the instant revoke, and an optional expiry adds a second backstop. Because it is a link, the token appears in the URL, so it can show up in that browser's history.

Client report v0.21.0

The deliverable you hand a client. From the Client report panel (under Tools, alongside the review links) you generate a clean, printable summary of the site's notes - Generate report (all) for everything including resolved items, or Open items only. It opens in a new tab; use the browser's Print / Save as PDF to send it. This is the "here is what you asked for, here is what is done" document, drawn straight from the notes you have been triaging.

The report groups notes by status (Open, In Progress, Resolved) with summary counts, and shows each note's type, its severity when set, the page it is on, its screenshot, and the dates it was added and resolved. It is deliberately client-facing: the agent queue and internal-only fields (assignee, agent, code scope, browser context) are left out.

Plain (free) vs branded (PRO)

The plain report is free - export is never gated. The branded layer is PRO: set a custom report title, your logo, an accent colour, and hide the "Generated with Red Pen" credit, so the report goes out as your own deliverable rather than the tool's. You set these in the same panel; they apply only when PRO is unlocked, and the free report always stays plain.

Unlocking PRO uses an offline-signed license key you paste into the Client report panel. It is verified locally against a public key embedded in the plugin - no phone-home, no expiry, and no kill switch, so it works forever. A valid key shows a "Licensed to ..." confirmation; the free report needs no key. (For self-use, a WPRP_PRO constant or the wprp_is_pro filter also unlock it.) This is the first PRO feature on the flagship, and the same key unlocks the Hub.

REST API

The front-end button talks to a small REST API under the wprp/v1 namespace. The same routes are what the Red Pen Hub uses for two-way write-back. Every route is gated by an edit_posts capability check. The front-end button authenticates with the standard wp_rest nonce; a server-to-server client (such as the Hub) authenticates with a WordPress Application Password over HTTP Basic auth.

Method + route	Purpose
`GET /wp-json/wprp/v1/notes`	List notes for a view. Accepts `target`, `status`, context `keys`, or an `agent` slug to fetch an agent's queue. Also accepts `scope=all` so the Hub can pull every note on the site, not just site-wide (`target=0`) ones. Notes carry an ISO `createdAt` and, once resolved, `resolvedAt` + `resolvedBy`.
`POST /wp-json/wprp/v1/notes`	Create a note (body, type, priority, target, anchor, screenshot, agent, and more).
`POST /wp-json/wprp/v1/notes/{id}`	Edit an existing note - text, type, priority, assignee, anchor (re-pin / clear), screenshot, and context.
`POST /wp-json/wprp/v1/notes/{id}/status`	Set the status (`open`, `progress`, or `resolved`). The Hub's Resolve / Reopen calls this route.
`POST /wp-json/wprp/v1/notes/{id}/replies`	Add a threaded reply to a note.

Connect to Hub

To see this site's notes alongside every other project, connect it to the Red Pen Hub. Under the plugin's Display settings, fill in "Connect to Red Pen Hub" with the Hub URL and the shared connect token. The plugin then pushes its notes to the Hub whenever a note changes - the site sends to the Hub, so no Application Password or inbound access is needed.

What the push sends. A push includes every top-level note on the site - all pages and posts, not just site-wide ones - each with its full data: type, priority, severity, anchor, the ISO created and resolved timestamps, the resolver, and the assignee (v0.20.1). So the board shows the same detail no matter how the site is connected.

There is a second way to connect: instead of the site pushing, the Hub can pull from the site using a WordPress Application Password (see the REST /notes route above). A pull uses the ?scope=all parameter added in v0.19.0 to get the whole note set - before it, a pull saw only site-wide (target=0) notes and page/post-attached ones went missing. Pull connections are also how the Hub writes a resolve back into the WordPress database over REST.

Known gotcha The Hub URL must include the scheme - write http://localhost:3900, not localhost:3900. A schemeless URL is silently rejected by WordPress sanitisation, which saves the token but blanks the URL, so the push quietly no-ops. Recent versions auto-prepend http://, but include it to be safe.

Architecture and data

The plugin keeps everything in standard WordPress structures - no custom tables:

Storage - a private wprp_note custom post type. The note body is the post content; author and date are native; status is a custom post status (wprp_open / wprp_progress / wprp_resolved).
Replies are child wprp_note posts (the parent is the note id). Priority, assignee, agent, context, and the element anchor are all post meta.
Targeting context - each note stores a context key (for example post:12, pt_archive:composer, term:genre:5, tpl:single-track, search, 404), a human label, and a level (page or template). The front end fetches by the current view's page and template keys.
Clean uninstall - deleting the plugin removes every note and preference it created, and nothing else.

Troubleshooting

No floating button. Confirm you are logged in as an editor or admin and Dev Mode is On in the admin bar. Logged-out users never get the assets. Check the "Where Red Pen appears" setting covers the view you are on.
Notes not reaching the Hub. Verify the Hub URL includes http:// and the connect token matches the Hub's token exactly. A bad token returns a 401; a missing scheme blanks the URL.
A screenshot did not save. Screenshots are stored under uploads/wp-red-pen/; confirm the uploads directory is writable.

Previous← Core concepts NextExpress middleware →