a semantic text format
SemText is a semantic text format: a single HTML file that a language model reads and writes the way it writes Markdown today. The difference is what the text can say. A fact, a step, a caveat, an incorrect statement, a term and its definition are each written as what they are — a tag and a few attributes — so the structure is in the text itself, not inferred from it.
Read it as-is. A model, a diff, a terminal, or an editor shows readable text in document order, with every qualifier spelled out next to the thing it qualifies. Nothing has to run first.
Open it in a browser and the same markup becomes working web components: flashcards flip, quizzes score, tabs switch, code copies, terms preview, and a reader bar tracks the outline. All of it works from a double-clicked file in any current browser, and none of it changes the text the model wrote.
<sem-note variant="warning">
Refresh tokens rotate per use —
each exchange retires the last one.
</sem-note>
<sem-facts view-as="flashcards">
<sem-fact id="f-jwt" kind="concept">
<statement>JWTs rotate per session</statement>
<conclusion>Short-lived access tokens;
the refresh grant issues a new pair.</conclusion>
<incorrect-statement>Store the token in
localStorage for durability.</incorrect-statement>
</sem-fact>
</sem-facts>The idea, in one control
These four facts are authored once, as <sem-fact> elements holding a <statement>, a <conclusion> and a <incorrect-statement>. view-as on the <sem-facts> element selects how they render — switching it rewrites nothing, and the records a machine reads are the same in every view. One file, three readers:
semtext.html — the in-browser render: double-click the file and it runs.semtext tui — the same file in an interactive terminal for people: navigate sections, flip flashcards, run quizzes.semtext --render — plain text for agents: collapsed sections expand on demand, embeds load, and the file arrives as its own summary.$ cat demo/messages/code.txtcode view — the pager over the deck file: bat demo/example-deck.sem.html Up/Down line · PgUp/PgDn page · / find · n/N next/prev · q quit (placeholder — this shell types and runs the script once the shell bundle lands)$ cat demo/messages/tui.txttui view — the interactive terminal over the notes file: semtext tui demo/auth-notes.sem.html arrow keys or click: sections, flashcards, quiz · Esc exits (placeholder — this shell types and runs the script once the shell bundle lands)$ cat demo/messages/cli.txtcli view — plain text out, one command per reader: render-card demos/render-demo.card semtext --render demo/auth-notes.sem.html render-card demos/render-subsection.card render-card demos/render-toc.card (placeholder — this shell types and runs the script once the shell bundle lands)The browser pane renders demo/example-deck.sem.html itself — the same file double-clicking opens. The shell panes type their first commands once the shell bundle lands. More sample documents sit in the showcase menu below.
Reading
The recall elements above are one use of the vocabulary. Most documents are read, not drilled, so it also carries what a long document needs: a glossary whose terms preview on hover, references with backlinks, a dated chronology, listings with provenance, notes that can float in the margin, content addressed to a named audience, and links that reach into closed disclosures. The examples below are the real content; the live affordances — hover previews, sorting, the reader bar — run on the showcase.
A sem-properties block with view-as="glossary". Each property carries an id; a term in prose is a plain anchor to it. With scripts off, the link simply jumps to the definition; the reading bundle adds a preview on hover or focus.
sem-chronology is CSS only: a list of sem-event items in chronological order, each with a when and an optional status. Extraction gives each event a positional ordinal.
Jan 2026 · done
Format spec v0 and the Tier-0 schemas.
Mar 2026 · done
Fallback tier, extraction contract, scripts-stripped artifact.
Sep 2026 · current
Reading experience: foundations, then the prose elements on this page.
2026 Q4
Theme pipeline and the reader chrome.
A sem-audiences block declares the profiles a document knows; any element may carry audience. Nothing is removed — content for a profile is hidden until a reader claims it, and extraction never consults visibility, so a filtered document still extracts whole.
sem-code carries what a listing cannot: a filename, a language and a set of marked lines. The listing is written directly inside the element — it becomes a <pre><code> when the reading bundle runs — stays byte-identical, and extraction reports it verbatim.
<p>Rotate per use<a href="#r-rfc">[1]</a>.</p>
<sem-references id="refs" kind="bibliography" role="list">
<sem-reference id="r-rfc" role="listitem"
href="https://www.rfc-editor.org/rfc/rfc6749" cite="RFC 6749">The OAuth 2.0 Authorization Framework, §10.4.</sem-reference>
</sem-references>
sem-reader is the bar pinned to the top of the showcase page: one per document, a direct child of the root wrapper, mints nothing. Its outline is generated from the headings, h2 on down. Focus, type size, face and colour scheme are attributes on <html> that the vocabulary CSS keys on, remembered in localStorage when the browser allows it.
sem-source lets a reader flip a section between the rendered result and the markup that produced it. sem-md holds Markdown as its text and renders it in the browser — tables above all. sem-table wraps an authored <table> and adds sort and filter; there is no JSON payload — the markup is the data. All three run live on the showcase.
sem-references numbers its entries with a CSS counter in every tier. Citations in prose are plain anchors; the reading bundle adds a preview on each, a backlink per citation, and an external link where an entry has an href.
Quick start
A SemText document is an HTML file. The vocabulary is custom elements with plain attributes — <sem-facts view-as="flashcards">, <sem-step status="done"> — so any editor, template language or generator that emits HTML can write one, and the browser parses it with or without a script.
Save it, double-click it. That is the whole workflow. Written the older way — <div class="sem-note" data-variant="warning"> — it renders and extracts the same; that spelling is the compatibility alias, documented once in the spec's Appendix A. The cdn.semtext.dev links are the planned origin; today the same files ship in the spec repo.
semtext.css — and, if you want a theme, semtext-theme-<name>.css — next to your document, and set data-sem-theme on <html> to that theme's name.semtext.js. Link it, or paste it inline for a document you intend to send as a single file.sem-* elements where interactivity or machine-readability pays. Ordinary HTML stays ordinary HTML.Want your own look? The theme file format is documented in the theme conventions section of the spec .
Surface
One script and one stylesheet, plus an optional theme file. Everything a document needs rides in the single semtext.js — the components, the reading chrome and the Markdown renderer — so there is no build step and nothing else to link.
Twenty-one element types mint records: sem-agent, sem-note, sem-facts and sem-fact, sem-details and sem-detail, sem-procedure and sem-step, sem-properties and sem-property, sem-views and sem-view, sem-reveal, sem-progress, sem-chronology and sem-event, sem-code, sem-references and sem-reference, sem-table and sem-md. sem-reader is chrome and mints nothing.
Browse all of them — purpose, options, and the authored markup — in the tag reference.
A sem-agent block is document-level metadata aimed at a model, carried by the same file a person is reading. It is inert to a browser and it is a record to an extractor.
Scope
SemText ends at the document: no build step, no service, no install. The limits below are the design, not the gaps.
Integrations
The reading and extraction core is free and static. Integrations connect a document to live systems — tickets and knowledge-base answers cited inline, quizzes and courses readers work through, mockups and UML rendered in place. Each is wired to its real logic as it is built, and none change how a document reads.
An account key enables ticket embedding — live tickets from your tracker, cited inline like any other datum.
TRK-241 · open
Streak reset wipes a completed quiz score
assigned @dana · tagged semtext · cited inline from your tracker
Point a document at your knowledge base, so facts and procedures draw on live KB entries.
KB-118 · account keys · v3
What does an account key unlock?
Embedding — tickets, quizzes and course progress render inside your documents; the reading core stays open.
source: The Robot Knows · entry cited on the fact
Courses load as SemText and track each reader's quiz progress; sign-in is prompted when tracking starts.
course · Working with SemText
progress tracked per reader · sign-in prompted on start
Private exams and quizzes from The Robot Learns embed in your pages, beside a public catalogue of embedded quizzes.
quiz · public catalogue
Which attribute selects an alternate rendering?
scores in place · private exams use the same embed
Mockups and UML renders from Draftamo-hosted projects, or from local Draftamo XML.
checkout-flow.uml · rendered by Draftamo
Submit an issue from the page itself — The Robot Plans files it in Jira, ClickUp, or GitHub.
SEM-312 · Integration carousel keyboard focus ring
Reported from this page — reporter, page section and build attached automatically.
filed via embedded form → The Robot Plans (GitHub)
1 / 6 — Ticket embedding
Extend
Org-specific components, and a submission tool where you talk an element into existence: the agent drafts the vocabulary entry, builds the Lit component, and wires the submission flow.