Help & manual

How the Comrades Creative Suite works, what each control does, and how to get the best out of it.

What this is

The Comrades Creative Suite is your research-and-writing tool for the 2026 broadcast. It sits on top of an archive of cited segments drawn from books, Wikipedia entries, and interview material on the Comrades Marathon. You ask a question, the Librarian pulls the relevant source segments, and Claude either drafts a script (in T+W voice) or returns a structured factual or research answer, depending on which channel you pick.

The flow in one minute

1. Ask. Type a topic and any direction in the textbox. One sentence or one paragraph, your choice. Pick the channels you want output for. Click Write.
2. Write. Each picked channel produces its own draft. Drafts run in parallel.
3. Review & rewrite. Read the draft. Type feedback in the box below it. Click "rewrite with feedback" to regenerate, addressing your notes. The previous draft is shown to the model as context for the rewrite.
4. Citations. Open the panel at the bottom of the Write page to see the source segments the Librarian drew on for the piece.
5. New brief. Click ↻ new brief in the top bar to clear and start over.

The channels

Channel	What it produces	Length	Voice
Broadcast insert	VO script for the live TV broadcast	25–60 seconds (75–180 words)	T+W veteran storyteller
TikTok	VO script for short social	15–30 seconds (50–100 words)	T+W veteran, hooked at 2s
Instagram	Caption with hashtags	150–300 chars	T+W veteran, warm
LinkedIn	Reflective post	400–800 chars	T+W veteran, professional
Facebook	Community-tone post	250–500 chars	T+W veteran, conversational
X (Twitter)	Single punchy post	≤280 chars hard cap	T+W veteran, one hook
Facts (look-up)	Direct factual answer, lists, tables	No length cap	Library voice, no narrative
Research	Structured research piece with sections, sources, citations	As long as the topic needs	Editor-briefing-a-reporter

The four script channels share the same T+W writer stack. Facts and Research bypass it entirely and use their own simpler prompts.

Writing a good ask

The Ask textbox is one free-form input that captures both topic and direction. The Librarian uses every meaningful word in it to retrieve source segments, and the writer reads it as the brief.

Strong asks tend to:

• Name a specific subject. "Trimborn's cock crow" beats "a tradition".
• Hint at the angle. "…land on how strange and perfect it is" tells the writer where to take it.
• Say what you want, not what you don't. "Make the closing simple" beats "don't be flowery".
• Be plain. You're briefing a writer, not writing copy yourself. Plain English instructions land best.

Examples:

• Polly Shortts, and how the race gets decided there, not earlier.
• What it means to earn a green number.
• Vic Clapham's founding intent. The race as a memorial, not just a sporting event.
• Top 10 fastest up-run times.  (use Facts channel)
• How has the women's race changed since 1975?  (use Research channel)

Feedback & rewrite

Below every draft is a Feedback box. Anything you type there gets shown to the writer, alongside the previous draft, on the next regenerate. Use it to direct the rewrite:

• "Tighten the opening, drop the fifth line."
• "Land harder on the closing."
• "Pull back on specifics. Anonymise the runner."
• "Make the land line about the weight of years, not the hills."

The rewrite button label changes to ↻ rewrite with feedback when there's text in the box; otherwise it's a plain ↻ regenerate from scratch.

The fidelity audit

After every script draft (broadcast / TikTok / Instagram / LinkedIn / Facebook / X), a second Claude call audits the draft against the source facts and the canonical reference data. The result shows as a coloured strip below the draft:

• Green ✓ Audit clean — every concrete claim traces to a fact.
• Amber ⚠ Issues to review — one or more concerns the producer should check.
• Red ⚠ Fidelity problem — at least one clear fabrication.

The auditor flags these severity types:

• fabrication — a claim with no archival support.
• conflation — two facts fused into a third claim neither made.
• embellishment — added specific detail not in the facts.
• origin slip — turning a general statement into a specific-year origin.
• canonical mismatch — naming a person, hill, medal, or year-winner that contradicts the canonical reference.
• no land line — the piece reports but never reveals.
• flat close — closing line summarises or restates the opening.
• drift — the piece isn't about a single topic.
• non sequitur — a sentence that doesn't follow logically.

Facts and Research channels skip the audit. The audit checks for narrative violations that don't apply to look-up answers.

Source segments (citations)

Every Write page ends with a Source segments panel showing the passages the Librarian drew on. Click the header to expand. Each row shows the quoted source material, soul stars, and the source title + author + locator.

What you see there is what the writer saw. If the citations don't include something you expected, the topic likely didn't match strongly enough — try rephrasing the Ask with the exact name or term you want surfaced.

The writer's rules in short

• Persona. A Comrades veteran telling a story to listeners who haven't run it. Smug, never patronising. Reverent about the race, never precious.
• Race. Every piece is for the 2026 up-run. Durban to Pietermaritzburg. Big Five hills in up-run order: Cowies, Fields, Botha's, Inchanga, Polly Shortts.
• Structure. One topic, one move (NAME → OPEN → LAND is the default), one land line.
• Specificity. If the topic is a person, name them. If it's a tradition or concept, names and dates often crowd the piece. Hold back unless they earn their place.
• Voice. Short lines, fragments allowed. "We" and "you" welcome. Specific verbs over generic ones. Plain language carries the reverence.
• Hard rules. Never invent facts. No em-dashes. No "It's not X, it's Y" or any negation-reveal pattern. No "In a world where…", no clichés, no corporate words.
• Reference scripts for the voice are pinned in the system prompt: Green Number, Cock Crow, Shosholoza.

The archive

Currently cited segments across sources, including the Cameron-Dow combined history, Bob De La Motte's Runaway Comrade, eleven Wikipedia pages, and source material from interviews already segmented but not yet extracted.

Each segment carries: the claim, the supporting quote, the source + locator, the year (when present), and themes tagged at extraction time (history, geography, traditions, runner_stories).

Canonical truth

For year-winners, hills, and medal tiers, the writer and auditor are pinned to a canonical reference (1921–2025 winners, the Big Five hills in up-run order, current medal criteria). When you ask about a specific year or the Big Five, that reference takes precedence over anything in the archive that conflicts. Years 1941–45 (WWII) and 2020–21 (COVID) are flagged as race-not-held.

API key

Set your Anthropic API key via the 🔑 set api key button in the top-right. The key is stored in this browser's localStorage so you don't have to re-enter it; clear it manually on a shared machine. Every API call in the app goes directly from your browser to api.anthropic.com; the local server only serves the UI and the archive payload.

Local server

The suite runs at http://127.0.0.1:8765. Endpoints:

• / — this UI
• /api/health — facts count, sources count, export timestamp
• /api/facts — the full archive payload (used by the UI on load)
• /api/query?text=…&limit=… — server-side filter for ad-hoc retrieval

The server auto-syncs the database from the SMB share to a local copy, so SQLite locks behave correctly. If the SMB mount drops, a cron-driven script (~/bin/ensure-sf01-mount.sh) reconnects within a minute.

Troubleshooting

• "Set your API key" — click the 🔑 button top-right and paste your Anthropic key.
• Citations are empty — your Ask didn't match anything in the archive strongly enough. Try a more specific term (a runner's name, a year, a place).
• Audit failed — usually a network blip. Click ↻ re-audit on the draft.
• Facts list looks short — only segments with soul ≥ 2 and an anchored quote are surfaced. Soul-1 trivia and quote-less rows are filtered out.
• UI feels slow when typing — typing in the Ask box is debounced and retrieval only runs when you click Write. If it's still slow, refresh.

T+W Soul · Comrades Marathon Broadcast · 2026.