Writing an article

Start to finish: starting one, editing it, publishing it, and the two things that rewrite more than you asked them to.

Where the work happens

/editorial. Open to any grant holder. The queues are at the top, over the branches you hold; the library is below them, browsable by category and searchable, every row opening straight in the editor.

Reading (/articles) has no editing controls at all. An educator reading between questions was one mis-tap from the editor. The most an article on Reading offers somebody who may edit it is Open in Editorial.

The editor's address is /editorial/articles/:id. Which mode the page is in is carried in the address, not in a flag: an article reached from the queue is being worked on, and the trail out of it leads back to the queue.

Starting one

Two doors, both moderator-only, both on /editorial:

Door	Does
By hand	POST /articles/ with a title and a slug. An empty article, opened for you.
AI draft	POST /articles/ai-draft with a topic and optional instructions.

The AI panel offers Draw on switches for the clinical library and PubMed — and only for the sources this site actually has, because a switch for a library nobody has configured is a switch that does nothing, and ticking it and waiting is the worst way to find that out. See Drafting with AI and Site policy.

Drafting is a background job. The panel polls it and drops you straight into the finished draft; if it fails, the reason is kept on the Jobs page for a day, because the panel's message dies with the panel.

The editor

The article

Title, slug, summary, and a markdown introduction that sits before the first section.

Renaming the slug is safe: every slug an article has ever had is remembered, so the old address still resolves.

Sections, one view at a time

Three tabs — Summary (short), Long, Clinical — with the number of sections in each on the tab. You edit one view at a time. All three live in one list because they are one article, but showing them together made it impossible to tell which version you were changing.

A new section	Gets a fresh 32-hex id and a slug, in the view you are looking at
Nesting	One level. The parent list offers only earlier top-level sections of the same view — a sub-section cannot belong to another view, and the server enforces it.
Removing one	Its children come up a level rather than going with it
An empty view	Is not offered to readers at all

References

Structured — title, author, pages — not free text, so the editorial queue can ask "what is published without sources" and get a truthful answer.

There are no citation markers in the prose. This list is the whole of the provenance.

Pages are typed as text and stored as numbers. Leaving the field shows what was actually stored, so a dropped entry is visible rather than a silent difference.

The three identifiers

At the top of the editor, each one a button that copies:

	Is
ID	What a cross-reference should carry — an id survives a rename
Slug	The readable address
[[12\|Bronchiolitis]]	The whole marker, ready to paste into another article

Saving

PATCH /articles/{id}. Every save:

1. Snapshots the article first into article_revisions — see Revisions and restoring.
2. Prunes any question link whose section no longer exists.
3. Checks every [[…]] in the body and returns what points at nothing.

Broken links are reported, not refused

If the save comes back with broken_links, the page names them:

N cross-references in this article point at nothing… Saved anyway — a link to an article that does not exist yet is a note to write it. It will start working the moment that article does.

The link checker is stricter and is the thing to run before a release.

Leaving without saving

Discard closes the editor. With unsaved changes in it, it asks first — in the same dialog every confirmation uses. There was no way out but Save and the browser's Back button, and the second one throws the sitting away without saying so.

Publishing

draft ──► in_review ──► published

Moderator only, on every step, even for an article a grant holder may rewrite entirely. Editing is editorial work; publishing is a decision about what the library contains.

Publishing stamps reviewed_at and reviewed_by, links cross-references, and reindexes the article for search. first_published_at is stamped once and never cleared — it is what decides whether deleting the article bins it or removes it outright.

Unpublish is the same button the other way.

AI refine — read this before pressing it

In the editor only, moderator only, and never on Reading: a model rewriting a published page underneath its readers is the draft's business.

It takes free-text instructions ("shorten the workup section") and queues the same task a fresh draft uses, with article_id set.

Refine rewrites the whole article

Not the section you named. The task replaces the title, slug, summary, introduction and every section from the model's reply. Your instructions steer it; they do not scope it.

Two things protect you: each section's variant and id are preserved, so cross-references pointing into the article do not break — and the article is snapshotted first, so there is a revision to go back to. That snapshot was added precisely because the one operation that rewrites an entire article left nothing to return to.

It never publishes. The article keeps whatever status it had.

Deleting

DELETE /articles/{id}, moderator only, from the queue or from the article. The outcome is one of two, and the page says which:

• Never published (first_published_at is null) — gone outright. Nobody ever saw it, so there is nothing to restore it for.
• Anything else — the bin, restorable from Editorial.

The other things on an article

Want	Go to
Attach or remove a figure	Figures and the bin
Generate a deck from it	Decks from an article
Claim a whole category for it	Topic claims
Give it another name for the linker	Aliases
Read what learners reported about it	Feedback
Put back an earlier version	Revisions and restoring