Overview

Core concepts

Red Pen is one idea wearing five coats. A note is the same object whether you left it in WordPress, an Express app, a static page, a Blender scene, or Ableton. That shared model is exactly what lets the Hub roll every project into one board. This page is the vocabulary; the surface pages show how each platform realizes it.

The three principles

Everything in Red Pen follows from the four commitments on the Home page. Restated here because they decide how every field below behaves:

• Dev-only. Red Pen is for the people building the site, never its visitors. Each surface is gated: a WordPress capability check, an NODE_ENV check plus a real remote-address check in Express, a localhost guard you add on the static drop-in, Live's Developer Mode in Ableton, and Blender's own add-on install. The one to watch is the static drop-in: it is just a script, so the guard is yours to write.
• Local-first. Notes live in your site's database, a file in your repo, or your browser. There is no service behind Red Pen to report to, and no switch anyone else can flip. The only time a note leaves your machine is when you deliberately push it (for example, to your own local Hub).
• Free and open. Every concept on this page is free on every surface that implements it, and the Hub that aggregates them is free too, however many projects you connect. Implements it is doing real work in that sentence: the surfaces are at different maturity levels, and the Surface matrix says which has what. Where it shows a gap, the feature is unbuilt rather than paywalled. If Red Pen saves you time, you can back the next release; support is optional and never gates a feature.

The note model

A note is the core object. Every surface stores it differently (a WordPress post, a line in .redpen/notes.jsonl, a localStorage entry, a JSON sidecar beside the .blend, or an external notes.json for Live) but the shape is the contract. These are the fields:

Surfaces may carry a few extra platform-only fields (WordPress, for instance, stores a structured context key and template metadata), but the fields above are the portable core that the Hub normalizes against.

Note types

Every note has a type. There are four built-in types; the stored value is the enum key, and the label shown in the UI may differ (and may be localized):

Custom note types are part of the free core: you can define your own types, each with an optional colour flag, and they merge into every type dropdown and render their colour on the note. They ship on WordPress (site-wide, defined as Label|#hexcolor lines in Display settings, stored with a ct_ key prefix) and on the static drop-in (per browser, label and colour, defined in Settings). The Hub renders a custom type's own label and colour when a surface sends them, and humanizes the slug when it does not. Express, Blender and Ableton have the four built-ins only. See the Surface matrix for the current grid and the Roadmap for what is next.

Priorities

A note carries one of three priorities: low, normal (the default, sometimes surfaced as "medium"), and high. Priority drives sorting and at-a-glance triage. High priority is rendered in the brand red (#D32F2F) across the surfaces and on the Hub board, so the things that matter stand out without you reading a word.

Severities

Severity is a second, optional axis that answers a different question than priority. Priority is about scheduling: when should this be done. Severity is about impact: how bad is it if it stays. The two are orthogonal: a low-priority, high-severity crash is a real thing (it will hurt badly, but not today), and so is a high-priority, low-severity typo on the launch page. Severity is unset by default and shown only when you deliberately choose one, so it never adds noise to notes that do not need it. There are five keys:

Only WordPress authors severity today (set in the note form, dev-only). The Hub board and the CSV export display it, and the other surfaces can adopt it later. The field is part of the shared model regardless of which surface writes it.

Status and workflow

Notes move through a small, explicit workflow rather than just existing as sticky notes:

Resolving a note clears it from the working view; reopening brings it back. The overlay's panel is organized into Open / (In Progress) / Resolved tabs with live counts so you always know what is left. Resolve also offers an undo in case you closed the wrong one.

A resolve now also records when it happened (a resolvedAt timestamp, cleared again on reopen) and, on surfaces that have identity, who did it (resolvedBy; WordPress stores the user's display name). The Hub board surfaces both as its Created and Resolved columns, so you can see and sort by when each note opened and closed.

Context and scoping

Every note belongs to a context, which is how a surface answers "what notes are on this page / this thing?":

• Web (Express and static): the page path, location.pathname. The panel shows the notes for the page you are on; the repository shows them all.
• WordPress: a structured context key, for example post:ID, term:tax:ID, pt_archive:slug, plus home, search, and 404, so a note attaches to the right piece of content even across permalink changes.
• Ableton: the anchored object or time, meaning a clip, track, scene, or beat range.

Anchors and pinning

A note can be pinned to a specific spot, or left at the context level (anchor: null). Pinning is what turns "the button near the header" into a note that points at the exact button.

On the web surfaces, an anchor is { sel, x, y }: a CSS-selector path to the element (it prefers an #id, otherwise builds an nth-of-type chain), plus a relative position x / y from 0 to 1 within the element's box. To create one you click Pin, then click the element. A numbered red marker then renders over that element and repositions as the page scrolls or resizes; Locate on a note scrolls to and briefly flashes its element.

In Ableton, an anchor is platform-specific: a beat range from an arrangement selection, or the identity of a clip, track, or scene. Locating there is deliberately weaker than on the web: Live 12's Extensions API exposes no way to select a clip, scroll the view, or switch between Session and Arrangement, so the button is called Flash and it blinks the clip's colour rather than jumping to it. For time anchors, Red Pen writes a native Live locator named RP: ... onto the timeline, and that visible locator IS the locate feature. See the Ableton surface page for what that writes into your Set.

Threaded replies

Each note can carry a flat, single-level thread of replies, shaped [{ author?, body, createdAt }]. You add a reply from the overlay, and the thread shows on the note and in the repository. It is enough to capture a back-and-forth ("is this still happening?" / "fixed in the last deploy") without turning Red Pen into a full discussion tool.

Replies ship on WordPress, Express, the static drop-in and Ableton. The Blender add-on does not have them yet, and the Hub shows a reply count without a thread view or a way to post.

Screenshots

A note can carry an optional region capture: drag a box around any area of the page and the snip is attached to the note (captured with html2canvas, stored as a small WebP or data URL). The capture shows on the note and in the repository, and is served gated like everything else (a capability check plus nonce on WordPress).

Assignee and agent

Two related fields record who a note is for, and they are how Red Pen distinguishes manual work from automated work:

• Assignee: a person. On WordPress this is a real WordPress user; elsewhere it is a free-text handle.
• Agent: an AI coding agent (a slug such as claude or codex), set when you delegate a note to an agent instead of a person. An optional codeScope points the agent at a file or symbol. Agent notes are kept out of the human views and live in an "agents" queue.

An agent consumes its queue locally, with no keys and nothing leaving the machine, in one of two ways: a filtered query (for example GET /notes?agent=claude) or an auto-maintained agent-<slug>.json brief file it reads off disk. In practice "check for red pens" means: pull the open notes (optionally one agent's), fix them, and mark each resolved.

Export and import

No export is behind a payment anywhere, and none is planned to be. Export is not uniform either, and three of the six have no one-click export at all. The state today:

The commitment underneath is narrower than "always portable": your notes are never in a format only we can read, and never behind a payment. Every store above is plain text or a standard WordPress post type on your own disk. Where a one-click export is missing, that is unbuilt work. See the Surface matrix for the grid and the Roadmap for the plan to bring Markdown export down from the Hub to every surface.

How the surfaces relate

Because all five surfaces speak the same note model, a companion piece can aggregate them: the Red Pen Hub reads each surface's store through a small adapter, normalizes every note to the fields above, and shows them on one board, tagging each with its project and surface. The Hub is also where the model's two-way side lives today: you can resolve or reopen a note from the board and it writes back to the real source. Everything the Hub does rests on this shared vocabulary.

From here, head to the page for the surface you are using:

• WordPress plugin, the flagship and most complete surface.
• Express middleware, one line into any Node app.
• Static drop-in, one script tag onto any website.
• Ableton Live, notes while you produce (feature-complete, awaiting SDK release).
• Blender add-on, a bug tracker for your scene in the viewport sidebar.
• Red Pen Hub, all your projects on one board.