docs: how article links, highlights and views are actually written

The syntax was known only to the code that parses it. This is the author's
side of it: `[[264|respiratory failure]]` and why the id form is the one that
cannot rot, `==key points==` and the three rules the parser follows,
`{{phrase|tip}}`, what each of the three views is for, how to link a question
or a whole topic, and what deleting does to a draft versus to something that
has been published.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TqXevQJhxFrM7jJg82cgZN

docs/README.md

@@ -13,6 +13,9 @@ Deep technical documentation for the PedsHub pediatric learning platform.
 | [Deployment](deployment.md) | Docker setup, environment variables, HTTPS, rebuilding, monitoring, troubleshooting, scaling |
 | [Adaptive sessions](adaptive-sessions.md) | What the Adaptive toggle selects, where the code is, and what it deliberately ignores |
 | [Study recommendations](study-recommendations.md) | How focus areas are ranked and what readiness means |
+| [Writing articles](writing-articles.md) | Cross-reference links, key-point highlights, teaching tips, the three views, linking questions, and what deleting does |
+| [Reranking](reranking.md) | Where the cross-encoder is applied and where it deliberately is not |
+| [Retrieval thresholds](retrieval-thresholds.md) | The numbers behind sourced / adjacent / open answers |
 
 ## Quick Links
 

docs/writing-articles.md

@@ -0,0 +1,112 @@
+# Writing an article
+
+Everything in an article body is Markdown, plus four pieces of syntax of our own.
+None of them need the editor: they are plain text, so they survive copy-paste,
+an AI draft, and a database import equally well.
+
+## Cross-references — `[[…]]`
+
+A link from one article to another. Two forms:
+
+| You write | It renders as | Use when |
+|---|---|---|
+| `[[264\|respiratory failure]]` | a link labelled *respiratory failure* | **always, by preference** |
+| `[[respiratory-failure]]` | a link labelled *respiratory-failure* | quick drafting |
+
+The first number is the article's **id**, and the id is the part that cannot
+change. A slug can be renamed — the old one keeps resolving, because every
+former slug is kept in `article_slugs` — but an id is permanent, so the id form
+is the one that cannot rot. The label after the bar is whatever reads naturally
+in the sentence: *"…severe viral `[[3|bronchiolitis]]`…"* reads as
+"…severe viral bronchiolitis…", with the two words linked.
+
+Where the id comes from: the article's URL. `/articles/264` is id 264. The
+editor's Linked-questions panel and the library listing both show it too.
+
+What happens at the far end: the link opens the article **in a side pane** next
+to what you are reading, rather than navigating away — following a reference
+does not lose your place. A marker pointing at an article that does not exist is
+reported on the editor as a broken link rather than rendering as dead text.
+
+Inside a **card or a list row** the same marker is flattened to its label
+instead of being rendered — a link inside something that is already a link would
+swallow the click.
+
+## Key points — `==…==`
+
+`Give ==IVIG within 10 days== of fever onset.` — the words between the double
+equals are highlighted in yellow, the way a highlighter is run over a textbook.
+
+Use it in the **high-yield view**, which is what it is for: a summary where
+nothing is emphasised is a shorter article, not a revision aid. A few phrases a
+section, never a whole paragraph.
+
+Rules the parser follows, so you can predict it:
+
+- A highlight may not run across a line break, so one stray `==` cannot swallow
+  the rest of a section.
+- `Sodium == 140` is a lab value, not an unclosed highlight: a lone marker stays
+  the characters you typed.
+- `====` is four equals signs, not an empty highlight.
+
+The Key button in the editor toolbar wraps the selection for you.
+
+## Teaching tips — `{{phrase|the tip}}`
+
+`{{stridor|Inspiratory stridor is extrathoracic until proven otherwise}}` — the
+phrase is underlined in the prose, and the sentence appears where the phrase is,
+on a click. It is a cross-reference minus the article: sometimes what a learner
+needs is one sentence, and writing a whole article to hang it on is how a
+sentence goes unwritten.
+
+The phrase may not contain a bar or a brace; the tip may not contain braces.
+
+## Maths
+
+`$…$` inline and `$$…$$` for a display block, rendered by KaTeX. Serum
+osmolality set as plain text is a different sentence from the one you wrote.
+
+## The three views
+
+Every section belongs to exactly one of them, chosen in the editor's view tabs.
+A view with no sections in it is not offered to the reader at all.
+
+| Variant | What it is for |
+|---|---|
+| **long** | The full article: pathophysiology, presentation, workup, management. The body of the work, and the default for anything written before views existed. |
+| **short** | The high-yield revision view. Tight lists of what a candidate must carry into an exam — not a summary of the long article's structure. This is where `==key points==` belong. |
+| **clinical** | What to do at the bedside, when the topic has one. Assessment, immediate management, escalation, disposition. Omit it entirely for a topic that is not acted on clinically. |
+
+An AI draft is asked for all three (see `ARTICLE_DRAFT_PROMPT`); it is told
+explicitly *not* to categorise the article or link it to questions, because both
+of those are judgements an educator makes.
+
+## Linking questions to an article
+
+From the article editor, under **Linked questions**:
+
+- **One at a time** — search by the stem, choose whether the link lands on the
+  whole article or on one section.
+- **A whole topic at once** — choose a category, and every question filed under
+  it (including its subtopics, unless you say otherwise) is linked in one action.
+  The button carries the number, so you can see that "Cardiology" means 43
+  questions before you press it. Up to 300 in one go.
+
+Either way these are ordinary link rows: removable one at a time, and a
+*snapshot* rather than a rule. Questions filed under that category tomorrow are
+**not** linked automatically — the alternative would silently attach new
+questions to an article nobody has looked at since.
+
+The same list is editable from each question's own editor, which is the same
+relationship seen from the other end.
+
+## Deleting
+
+- A draft that was **never published** is deleted outright. There is nothing to
+  restore, and a trash full of abandoned stubs is a second list to maintain.
+- Anything that **has been published**, even once, goes to the **trash** in
+  Editorial and can be restored exactly as it was. Somewhere there is a
+  learner's note against one of its sections, a question linked to it, and a
+  link somebody sent a colleague.
+
+The confirmation on the editor says which of the two you are about to do.