Yusupov's House - User contributions [en-gb]

Dozenal Primer Inscription

2026-09-24T18:03:42Z

Mvuijlst: TWELVE: the simplex form C01-M03-T02-C04 is attested once, in the numeral list (clause 15); the sums write twelve as one dozen

[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref>

The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

== Overview ==
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" />

The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.

== Glyph inventory and distribution ==

A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription (45 clauses, 838 sign tokens, 28 sign types); positions are counted within words, with the clause-final divider P01 treated as bound to the preceding word. Code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:center;"
|-
! scope="col" | Code
! scope="col" | Glyph
! scope="col" | Name
! scope="col" | Freq
! scope="col" | Init
! scope="col" | Med
! scope="col" | Final
|-
| A01
| [[File:A01.svg|24px|alt=A01|link=]]
| style="text-align:left;" | TRI-OPEN
| 15 || 11 || 4 || –
|-
| A02
| [[File:A02.svg|24px|alt=A02|link=]]
| style="text-align:left;" | TRI-BAR
| 29 || 29 || – || –
|-
| A03
| [[File:A03.svg|24px|alt=A03|link=]]
| style="text-align:left;" | TRI-DOT
| 6 || – || 6 || –
|-
| A05
| [[File:A05.svg|24px|alt=A05|link=]]
| style="text-align:left;" | TRI-CLOSED-BAR
| 4 || – || 4 || –
|-
| B01
| [[File:B01.svg|24px|alt=B01|link=]]
| style="text-align:left;" | BOX
| 17 || 6 || 8 || 3
|-
| B02
| [[File:B02.svg|24px|alt=B02|link=]]
| style="text-align:left;" | BOX-DOT
| 8 || 6 || 2 || –
|-
| B04
| [[File:B04.svg|24px|alt=B04|link=]]
| style="text-align:left;" | BOX-DIAG-SW-NE
| 36 || – || 15 || 21
|-
| B05
| [[File:B05.svg|24px|alt=B05|link=]]
| style="text-align:left;" | BOX-DOT-DIAG-SW-NE
| 3 || – || 3 || –
|-
| C01
| [[File:C01.svg|24px|alt=C01|link=]]
| style="text-align:left;" | CORNER-NW
| 109 || 50 || 29 || 30
|-
| C02
| [[File:C02.svg|24px|alt=C02|link=]]
| style="text-align:left;" | CORNER-SE
| 39 || 39 || – || –
|-
| C03
| [[File:C03.svg|24px|alt=C03|link=]]
| style="text-align:left;" | CORNER-SE-DOT
| 43 || 1 || 42 || –
|-
| C04
| [[File:C04.svg|24px|alt=C04|link=]]
| style="text-align:left;" | CORNER-NW-DIAG
| 3 || 2 || 1 || –
|-
| C05
| [[File:C05.svg|24px|alt=C05|link=]]
| style="text-align:left;" | CORNER-SE-DIAG
| 32 || 32 || – || –
|-
| C06
| [[File:C06.svg|24px|alt=C06|link=]]
| style="text-align:left;" | CORNER-NW-DIAG-DOT
| 4 || – || 4 || –
|-
| H01
| [[File:H01.svg|24px|alt=H01|link=]]
| style="text-align:left;" | DOUBLE-POST-CONNECTED
| 20 || – || 20 || –
|-
| H02
| [[File:H02.svg|24px|alt=H02|link=]]
| style="text-align:left;" | POST-DOUBLE-BAR
| 40 || – || 38 || 2
|-
| H03
| [[File:H03.svg|24px|alt=H03|link=]]
| style="text-align:left;" | DOUBLE-POST-BAR
| 30 || – || 30 || –
|-
| L01
| [[File:L01.svg|24px|alt=L01|link=]]
| style="text-align:left;" | LINE-VERT
| 45 || – || 12 || 33
|-
| L02
| [[File:L02.svg|24px|alt=L02|link=]]
| style="text-align:left;" | LINE-HOR
| 34 || – || 26 || 8
|-
| M01
| [[File:M01.svg|24px|alt=M01|link=]]
| style="text-align:left;" | COMB-2-N
| 18 || 4 || 13 || 1
|-
| M02
| [[File:M02.svg|24px|alt=M02|link=]]
| style="text-align:left;" | COMB-2-W
| 67 || – || 67 || –
|-
| M03
| [[File:M03.svg|24px|alt=M03|link=]]
| style="text-align:left;" | COMB-3-E
| 62 || – || 60 || 2
|-
| P01
| [[File:P01.svg|24px|alt=P01|link=]]
| style="text-align:left;" | SLASH
| 45 || – || – || 45
|-
| S02
| [[File:S02.svg|24px|alt=S02|link=]]
| style="text-align:left;" | MEANDER-2-HOLLOW
| 12 || – || 6 || 6
|-
| S03
| [[File:S03.svg|24px|alt=S03|link=]]
| style="text-align:left;" | MEANDER-3
| 48 || – || 45 || 3
|-
| T01
| [[File:T01.svg|24px|alt=T01|link=]]
| style="text-align:left;" | TEE-UP
| 11 || – || 9 || 2
|-
| T02
| [[File:T02.svg|24px|alt=T02|link=]]
| style="text-align:left;" | TEE-LEFT
| 9 || – || 6 || 3
|-
| T03
| [[File:T03.svg|24px|alt=T03|link=]]
| style="text-align:left;" | UPSIDE-DOWN-TEE
| 49 || – || 28 || 21

|}

== Proposed numeric forms and functional sequences ==

Codes follow Kristiansen’s signary. Values are glosses for exposition only.<ref name="Rubergskier2024" />. Coding scheme per Kristiansen.<ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:left;"
|-
! scope="col" | Function (gloss)
! scope="col" | Codes (Kristiansen)
! scope="col" | Glyph sequence (icons)
! scope="col" | Notes
|-
| ZERO
| <code>B02-M03-L01-B05-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:B05.svg|20px|alt=B05|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| ONE
| <code>C01-S03-C03-T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| TWO
| <code>C02-M02-H01-M01-T01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T01.svg|20px|alt=T01|link=]]
|
|-
| THREE
| <code>B01-M02-L02-A03-H02</code>
| [[File:B01.svg|20px|alt=B01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L02.svg|20px|alt=L02|link=]][[File:A03.svg|20px|alt=A03|link=]][[File:H02.svg|20px|alt=H02|link=]]
|
|-
| FOUR
| <code>C05-M03-S02-C06-T02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S02.svg|20px|alt=S02|link=]][[File:C06.svg|20px|alt=C06|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| FIVE
| <code>C01-M03-T02</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| SIX
| <code>C05-B04-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:B04.svg|20px|alt=B04|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| SEVEN
| <code>M01-L01-A01-T03</code>
| [[File:M01.svg|20px|alt=M01|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:A01.svg|20px|alt=A01|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| EIGHT
| <code>B02-M03-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| NINE
| <code>C05-M02-H02-A05-S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:A05.svg|20px|alt=A05|link=]][[File:S02.svg|20px|alt=S02|link=]]
|
|-
| TEN
| <code>C05-M01-L02-M02-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:L02.svg|20px|alt=L02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| ELEVEN
| <code>A01-H01-B01</code>
| [[File:A01.svg|20px|alt=A01|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:B01.svg|20px|alt=B01|link=]]
|
|-
| TWELVE (one dozen)
| <code>C01-S03-C03-T03-C01-M02-H02-B04</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]][[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Transparently ONE followed by the ×12 derivational bundle; the sums always write twelve this way. Target of the complement sums 11+1, 10+2 and 6+6. <ref name="Rubergskier2024" />
|-
| TWELVE (simplex)
| <code>C01-M03-T02-C04</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:C04.svg|20px|alt=C04|link=]]
| Attested once, as the last item of the numeral list in the second line (clauses 3–15), which gives ZERO to ELEVEN as one-word clauses and then this form; read as twelve from its position. The sums never use it, and Rubergskier's analysis does not discuss the list. Glossed TWELVE in the dictionary published with Üksküla's Zagi materials. <ref name="Ukskula2024">Inrik Üksküla, “The Clan of Zagi: Numeric Calculus or Genealogical Primer? A Structural Analysis of the Kristiansen Cuneiform Corpus,” preprint (2024), with downloadable analysis materials.</ref>
|-
| '''EQUALS / clause spine'''
| <code>C02–M03–H03–C01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:H03.svg|20px|alt=H03|link=]][[File:C01.svg|20px|alt=C01|link=]]
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" />
|-
| '''PLUS (binary addition)'''
| <code>A02–L01</code>
| [[File:A02.svg|20px|alt=A02|link=]][[File:L01.svg|20px|alt=L01|link=]]
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" />
|-
| '''MINUS (subtraction)'''
| <code>C05–M02–S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:S02.svg|20px|alt=S02|link=]]
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" />
|-
| '''ONE (simplex unit)'''
| <code>C01–S03–C03–T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" />
|-
| '''PUNCTUATION (bound period)'''
| <code>P01</code> (final only)
| [[File:P01.svg|20px|alt=P01|link=]]
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" />
|-
| '''×12 derivation (“dozen”)'''
| –C01–M02–H02–B04 (right edge)
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" />
|}

== Scholarly discussion ==
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" />

== Nomenclature ==
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).

== Relation to the Scapula Glyph Inscription ==
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" />

== See also ==
* [[Duodecimal]]
* [[Numeral system]]
* [[Mathematical notation]]
* [[Undeciphered writing systems]]
* [[Epigraphy]]
* [[Paleography]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Klema]]

Nordland Itinerary

2026-09-24T11:02:22Z

Mvuijlst: Name Klema: origin in Nordland Itinerary line 58 (Weidner 1939 addendum), located by Roelandt in 2024; Hittite-type misnomer

[[File:Weidner 1938 Abb 1.jpg|thumb|Weidner's Abb. 1: a caravan descending from a rocky mountain edge into a wide, snow-covered steppe (pen drawing, 1938).]]
The '''Nordland Itinerary''' (German ''Reisebericht ins Nordland'') is the conventional name for a Sumerian travel account preserved on an Old Babylonian school tablet and published in 1938 by H. Weidner as “Ein neusumerischer Reisebericht ins Nordland” in the ''Mitteilungen der Deutschen Orient-Gesellschaft zu Leipzig''.<ref name="Weidner1938">H. Weidner, “Ein neusumerischer Reisebericht ins Nordland,” ''Mitteilungen der Deutschen Orient-Gesellschaft zu Leipzig'' 27 (April 1938).</ref> It records the stages of a royal expedition that left northern Mesopotamia, crossed the Zagros and the Iranian plateau, reached the southern shore of the Caspian and continued through the steppe corridor towards the Urals, and it is the only cuneiform text that describes snow, a frozen river and the northern lights.

Weidner assigned the composition to the Ur III period, around 2100 BC, and treated the surviving tablet as a later copy made for teaching. His 1938 article published some thirty lines from the third and fourth columns. The remaining lines of the fourth column, with the colophon, appeared a year later in a short addendum that was long overlooked;<ref name="Weidner1939">H. Weidner, “Nachtrag zum neusumerischen Reisebericht ins Nordland,” ''Mitteilungen der Deutschen Orient-Gesellschaft zu Leipzig'' 29 (1939).</ref> they contain the only foreign language name recorded by a Mesopotamian source north of the Caspian, ''ki-li-ma'', from which the modern term [[Kristiansen coding system|Klema]] is taken.

== The tablet ==
The text survives on a medium-sized four-column tablet of light brown clay. Palaeographically the hand is Old Babylonian. A colophon on the lower edge of the reverse, partly preserved, gives the total number of travelling days. In 1938 Weidner read the surviving figure as a little over six months; the addendum, which gives the line in full, shows the numeral broken at its left edge, and “[1]6 months and 12 days” is now the accepted reading, which suits a journey whose snowfall comes in the seventh month.<ref name="Weidner1938" /><ref name="Weidner1939" />

Weidner argued that the composition itself is older than its copy on three grounds: the text is written consistently in Sumerian rather than in Akkadian with Sumerian glosses; its vocabulary and style match the elevated idiom of the Neo-Sumerian royal hymns; and particular theological turns, above all the presentation of Enki as a river god who has “his dwelling” in the frozen river, stand closest to texts of the time of Šulgi. He therefore placed its composition at an Ur III court, in Ur itself or in Nippur, and its copying in the Old Babylonian school, where it served as an exercise or reading text.

The itinerary belongs to a small class of Mesopotamian texts that record day-marches and stages of travel, of which the best known real example is the Old Babylonian itinerary published by Goetze in 1953.<ref name="Goetze1953">A. Goetze, “An Old Babylonian Itinerary,” ''Journal of Cuneiform Studies'' 7 (1953): 51–72.</ref> Weidner's text differs from that class in one respect: at the decisive transitions of the journey the scribe abandons the bare listing of stages for short passages in a poetic register, in which the strangeness of the northern lands is put into words.

== Contents ==
The published text begins where the expedition leaves the mountains. The badly damaged lines before it mention, in Akkadian, toponyms of the north-eastern frontier of the Sumerian world: Subartu, Lullubu and perhaps Elam, together with “narrow ways in the mountains” (''sila tur-tur kur-ra''). Weidner read this as a crossing from the Upper Mesopotamian lowland over a pass north of Arbela into the Zagros.

Three Sumerian passages were published in 1938.

;Steppe and wagon peoples (lines 16–25)
:The travellers reach “very great rivers” whose “foreign tongues we did not know”, meet “men with boats and pack animals” who “set many wagons in motion”, negotiate with the caravan, and receive “weapons and strong hands”, which Weidner took to mean an armed escort through unsafe country. The land has no city; its people “do not eat grain bread, they eat only pig and fat cattle.”
;Cold, snow and the frozen river (lines 26–35)
:“In the seventh month white things moved from the sky, like chaff of the great threshing floor they fell to earth, the land became white, our great river became white.” Men and donkeys put their weight on the ice and carry “the water things over the water”. The foreigners say the river “is no longer there”; the scribe answers that this is “the house-river of Enki”, the place where the river god has set his dwelling.
;Forest, furs and sky lights (lines 36–45)
:“Trees upon trees are in the foreign lands; in three days one cannot count them to an end.” The people of the forest eat “the necks of thick-haired beasts” and bring heavy furs and fine hides “for the neck of the king”. In the sky “birds” move, “fast as eyes that are set, like shining gold and lapis lazuli”; the locals say “there our gods are set”, and the scribe replies that “it is Inanna who lays her hand to rest there.”

The addendum of 1939 added the rest of the fourth column.

;The head of the lands (lines 46–52)
:The expedition reaches “the head of the lands”, where “a great river touches the heart of the foreign lands” and there is “no city, no cultivated place”. A stone is set up for the king, beer and fine oil are poured, and “the name of the king of the land” is set down at the head of the lands.
;The furthest people and their tongue (lines 53–60)
:The people there “dwell in houses of hide”, “know no donkey, know no wagon”, and have “great-horned oxen” that “draw a sledge over the whiteness”. Their tongue “is apart from the tongues of the other lands” and has to be turned “through a third interpreter”. Line 58 then records the name: ''eme-bi ki-li-ma-še3 mu-un-sa4-e-ne'', “their tongue they call ''ki-li-ma''” (𒆠𒇷𒈠). The interpreter glosses it (line 59) as ''eme ti-la'', “the living tongue”. The scribe closes the exchange in his usual manner (line 60): “it is a tongue that Nisaba does not know”, Nisaba being the goddess of writing; that is, an unwritten one.
;Gifts, the tusk and the return (lines 61–67)
:The people give “heavy hides, horns of the great-horned ox, and the tusk of the elephant of that land”; “the elephant of that land no one saw”. The foreigners say the tusk “comes out of the earth”; the scribe answers that “it is the bull of Enki that lies in the earth”. In the ninth month the expedition turns back towards Ur, leaves the frozen river on foot, and carries “the hides and the tusk for the neck of the king”. The column ends there; the return route is not described.

== Weidner's commentary ==
Weidner's commentary follows the route stage by stage. The “rivers of very many woods” of line 16 he located in the upper Diyala or Sirwan system; the wagon peoples in the contact zone between mountain and plateau, where river transport, caravan traffic and an early wagon culture met; and the frozen river north of the Elburz, either the lower Safid Rud or, further north, a tributary of the Caspian in the Transcaspian lowland, while admitting that the material does not allow identification. The forest zone with its fur-bearing animals and its “sky lights”, which he took to be the aurora, he placed in the belt of woodland stretching from the Caspian basin towards the Urals, where the Eurasian steppe corridor opens.

Two smaller observations have been widely quoted. Line 20, ''anše-kur-ra-ĝu10 ma-da-an-du11'', “they spoke to my mountain donkey in their land”, he read as a joke of the scribe's: the whole Sumerian caravan personified as “donkey people” with whom the local wagon-drivers must first negotiate. And the repeated pattern in which the foreigners explain a phenomenon and the scribe reinterprets it through his own gods, the frozen river as Enki's house, the lights as Inanna's hand, he singled out as the characteristic method by which a Mesopotamian scholar absorbed the foreign into his own world. The addendum shows the pattern continuing to the end of the text: the unwritten tongue becomes one “Nisaba does not know”, and ivory dug from the ground becomes “the bull of Enki that lies in the earth”.

On the tusk Weidner was brief: ''zu2 am-si'' is the ordinary Sumerian word for ivory, and the scribe has a word for the material but none for the animal. He compared the reports of fossil ivory gathered from river banks and thawing ground in northern Siberia, without drawing further conclusions.<ref name="Weidner1939" />

In his closing remarks Weidner drew the wider conclusion that the connection from northern Mesopotamia over the Zagros, the Iranian plateau and the Caspian rim to the north Eurasian forest and steppe region was, at least occasionally, a real and not merely an imagined one.

== The name ''ki-li-ma'' ==
Line 58 is the only place in the text where a foreign word is written out rather than described. The three signs 𒆠𒇷𒈠 can be read ''ki-li-ma'' or ''ke4-le-ma''. Sumerian orthography cannot write two consonants at the beginning of a word, and foreign names with initial clusters are regularly broken up with a vowel in cuneiform, so a form with a cluster, ''klema'' or ''klima'', is at least as likely as the four-syllable one. What the scribe was told the word meant is given in the next line, “the living tongue”.

Weidner treated the name as a curiosity. It acquired a second life in 2024, when [[Marie Roelandt]], who had located the addendum, named her blog after it, and writers on the [[Kristiansen coding system|Kristiansen corpus]] followed, using “Klema” for the sign system and the language presumed to lie behind it on the strength of geography alone: the itinerary places a language so called in the forest zone north of the Caspian around 2100 BC, and the [[Yedoma Ledger]], the only physical object proposed as a carrier of the corpus, comes from the north Eurasian permafrost. The blog ''[[Klema Field Notes]]'' carries the name in its title. No published study has argued that the people the expedition met were the people who wrote the corpus, and the tablets themselves say the tongue was unwritten.

The name is therefore a misnomer of a familiar kind. Hittite is named after the land of Hatti and its biblical inhabitants, while the speakers of the language called it ''nešili'', after the city of Neša; the label stuck because it was the first one available, and philology has lived with it. “Klema” names a language by the word a Sumerian scribe heard from a forest people who may or may not have been its speakers, and applies it to a script that no Sumerian ever saw. Its users accept this. Roelandt has written that it may be “the wrong name for the wrong script”, and that it is nevertheless “a better name than ‘the Kristiansen corpus’”.

== Publication and reception ==
The 1938 article appeared in April and was illustrated with a single pen drawing of a caravan descending into a snowy steppe. It gives the tablet's physical description but not its museum number or present whereabouts, and no photograph or hand copy of the tablet was included. The addendum of 1939, a few pages in a late issue of the same series, supplied the transliteration and translation of the remaining lines and the colophon, again without a copy or photograph. Published on the eve of the war in a small print run, it was not cited for decades, and the remainder of the text was widely believed to be unedited until [[Marie Roelandt]] located a copy in early 2024 while searching the older literature for Mesopotamian contacts with the north Eurasian forest zone. She took the name in line 58 for her blog, and the corpus literature took the word from there.<ref name="Weidner1939" />

The itinerary is cited in discussion of the [[Kristiansen coding system|Kristiansen corpus]] for two reasons. It is the earliest text placing a literate Mesopotamian expedition in the north Eurasian forest zone, the broad region from which the [[Yedoma Ledger]] was later recovered, and it carries the name that the corpus has come to bear. Nothing in either publication mentions inscribed bone or ivory or any encounter with a script; the one statement about writing in the text is the scribe's own, that the tongue he heard was unwritten. No direct connection between the itinerary and the corpus has been proposed in print.

== See also ==
* [[Yedoma Ledger]]
* [[Kristiansen coding system]]
* [[Klema Field Notes]]
* [[Dur-Untash Expedition]]

== References ==
<references />

[[Category:Klema]]
[[Category:Epigraphy]]
[[Category:Parafictional Mesopotamian archaeology]]

Marie Roelandt

2026-09-24T11:02:21Z

Mvuijlst: Name Klema: origin in Nordland Itinerary line 58 (Weidner 1939 addendum), located by Roelandt in 2024; Hittite-type misnomer

'''Marie Roelandt''' (born 1967) is a Belgian independent researcher, the author of the blog ''[[Klema Field Notes]]'' (klema.tsuk.org), and the person who introduced the name '''Klema''' for the [[Kristiansen coding system|Kristiansen corpus]]. She lives in Antwerp. She trained as a librarian and worked for many years in archival document management, developing alongside this a longstanding amateur interest in historical linguistics, genealogy, and cryptography. She has no formal academic affiliation and describes herself on her blog as "a librarian who reads too many preprints."

Roelandt began following the [[Kristiansen corpus]] literature after encountering [[Ginevra Rubergskier|Rubergskier]]'s 2024 paper through a popular-science digest. Her distinctive contribution has been to bring genealogical intuitions, developed through decades of family history research, to bear on [[Inrik Üksküla|Üksküla]]'s structural analysis of the [[Zagi Tablets]].

== Work ==
In "The Zagi Family" (''[[Klema Field Notes]]'', 18 March 2024), Roelandt argued that the sign Üksküla had labelled UNIT should be read as the concrete kin term CHILD rather than an abstract quantity. She demonstrated that this substitution transforms Üksküla's structural templates into natural genealogical statements: "X has N children" and "child N is Y." She identified parental coupling as the function of the AND_PLUS connector and read Document 4 of the Zagi corpus as a straightforward four-child family record.

In a follow-up post, "Who's who in the Zagi family?" (''[[Klema Field Notes]]'', 12 April 2024), Roelandt constructed a working transliteration of the corpus. This was explicitly not a phonetic proposal but a readability aid, assigning arbitrary Latin letters to sign types in rough frequency order. Using it, she reconstructed a multi-generational family tree spanning at least three generations, identified two gendered variants of both CHILD and PARENT alongside a gender-neutral form of each, and identified a possessive particle. She noted two probable scribal slips in Document 3 in which the copy appears to have misattributed a grandchild relationship as a child relationship, and she stopped short of proposing readings for the opening and closing sentences of the corpus, which she described as "tempting but beyond what the internal evidence can support."

Roelandt is also the source of the name Klema. In February 2024, before her first post, she went through the older Assyriological literature looking for any Mesopotamian text that placed a literate party in the north Eurasian forest zone, the region the [[Yedoma Ledger]] had come out of, and found Weidner's 1938 article on the [[Nordland Itinerary]] together with his short 1939 addendum, which had not been cited since the war. The addendum contains the line in which the people at “the head of the lands” name their own tongue, ''ki-li-ma'', “the living tongue”. She took the word for her blog and mentioned its source only on the About page, where she calls it “the wrong name for the wrong script” and “a better name than ‘the Kristiansen corpus’”. The word passed from the blog into informal use in the field. She has said that she expected to be corrected and was surprised to be followed.

Roelandt's CHILD reading has been informally cited by several researchers as a significant clarification of Üksküla's Hypothesis B, though it has not yet appeared in peer-reviewed literature. She has said she has no plans to submit for publication, preferring the blog format for its speed and its tolerance of openly provisional conclusions.

== See also ==
* [[Klema Field Notes]]
* [[Zagi Tablets]]
* [[Inrik Üksküla]]
* [[Ginevra Rubergskier]]

[[Category:Researchers]][[Category:Bloggers]][[Category:Kristiansen corpus]]

Klema Field Notes

2026-09-24T11:02:20Z

Mvuijlst: Name Klema: origin in Nordland Itinerary line 58 (Weidner 1939 addendum), located by Roelandt in 2024; Hittite-type misnomer

'''''Klema Field Notes''''' is an independent research blog maintained by [[Marie Roelandt]] and hosted at [https://klema.tsuk.org/ klema.tsuk.org]. It publishes informal but closely argued analyses of material in the [[Kristiansen coding system]], with a particular focus on the [[Zagi Tablets]].

== Name ==
The blog is named after ''ki-li-ma'', the word that line 58 of the [[Nordland Itinerary]] gives as the name the people at “the head of the lands” used for their own tongue. The line belongs to the part of the text that H. Weidner published in a short addendum of 1939, which was overlooked for decades; Roelandt located a copy in early 2024, while searching the older Assyriological literature for any Mesopotamian contact with the north Eurasian forest zone, and adopted the word before her first post. She recorded the source only on the blog's About page, where she also concedes that it may be “the wrong name for the wrong script” and calls it “a better name than ‘the Kristiansen corpus’”. From the blog the word passed into general use for the [[Kristiansen coding system|corpus]] and the language presumed behind it.

== Notable posts ==
* "The Zagi Family" (18 March 2024): Roelandt argues that the sign UNIT in the Zagi corpus should be read as the kin term CHILD rather than as an abstract quantity, and demonstrates that this substitution produces natural genealogical statements of the form "X has N children" and "child N is Y." She identifies two structural templates—X DEF_PIVOT N CHILD and CHILD N EQ_PIVOT Y—and reads the AND_PLUS connector as a parental coupling marker.

* "Who's who in the Zagi family?" (12 April 2024): Building on the previous post, Roelandt assigns working transliterations to all sign types (explicitly not proposed as phonetic values) and uses these to reconstruct a multi-generational family tree from Documents 1–4. She identifies two families named CHILD-GENDERA and CHILD-GENDERB, two parental role terms distinguished by a suffix, and a gender-neutral parental term. She notes two probable scribal slips in Document 3 and stops short of proposing readings for the opening and closing lines of the corpus.

== Relation to academic literature ==
''Klema Field Notes'' explicitly engages with and cites [[Inrik Üksküla]]'s preprint and [[Ginevra Rubergskier]]'s [[Language Codes|''Language Codes'']] paper. Roelandt's CHILD reading may be seen as a development of Üksküla's Hypothesis B. The name Klema, which the corpus literature now uses informally, is likewise hers; see [[#Name|above]].

== See also ==
* [[Marie Roelandt]]
* [[Zagi Tablets]]
* [[Inrik Üksküla]]

[[Category:Kristiansen corpus]]
[[Category:Blogs]][[Category:Epigraphy]]

Kristiansen coding system

2026-09-24T11:02:19Z

Mvuijlst: Name Klema: origin in Nordland Itinerary line 58 (Weidner 1939 addendum), located by Roelandt in 2024; Hittite-type misnomer

The '''Kristiansen coding system''' is the alphanumeric notation used in the scholarly literature to transcribe the geometric signs of the [[Scapula Glyph Inscription]] and the other texts that share its sign repertory, collectively referred to as the '''Kristiansen corpus''' and, since 2024, also as '''Klema''', a name borrowed from the [[Nordland Itinerary]] (see [[#Name|Name]] below). Each sign receives a family letter and a two-digit index (for example C01, B04, P01). The system was introduced by [[Jan-Tage Kristiansen]] in a 2023 correspondence note and has since been adopted without modification by every subsequent study.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

The codes are deliberately neutral. They record what a sign looks like and how it is built, not what it might mean or sound like. No phonetic values have been proposed in the literature, and the mnemonic names attached to the codes (BOX-DOT, TEE-LEFT, and so on) are descriptive labels only.

== Principles ==
Kristiansen's note set out three rules that later work has kept:
* '''One code per sign.''' Every distinct grapheme in the inventory receives one code; no code is assigned to a sequence.
* '''Family letter plus index.''' The letter names one of eight visually coherent families, identified by shared construction (a corner, a closed box, a triangle, and so on). The index numbers the members of a family in the order they appear on the scapula. A ninth letter, P, is reserved for the single divider sign.
* '''Rotation and diacritics are features, not new families.''' Signs that differ only by rotation or by an added dot, bar or diagonal tick stay within their family and are distinguished by index. Kristiansen's original signary carried a rotation column; later work by [[Camille Voudrin]] and colleagues treated rotation as a non-contrastive convenience and canonicalised signs rotation-agnostically, with no effect on the inventory.

== Transcription conventions ==
* Signs within a word are joined by hyphens: <code>C01-M03-S01-C02</code>. Words are separated by spaces.
* The divider '''P01''' is transcribed as a sign in its own right. In the [[Dozenal Primer Inscription]] and the [[Zagi Tablets]] it occurs only at clause ends and is written bound to the last word of the clause (<code>…-T03-P01</code>).
* Sentences in the longer corpora are numbered by document and position, for example <code>F3_44</code> for the forty-fourth sentence in Document 3 of the Zagi Tablets. This numbering originates with [[Inrik Üksküla]]'s preprint and is used by [[Marie Roelandt]].
* Uncertain or damaged signs are written <code>??</code> in place of a code.

== The signary ==
The unified signary contains 31 signs in eight families plus the divider, 32 codes in all. Every one of them is attested once on the scapula (KS-01), which presents the families as an ordered sweep and so fixes the index order.<ref name="Kristiansen2023h" /> Rotation and feature descriptions follow Kristiansen's catalogue.

{| class="wikitable" style="font-size:95%;"
! scope="col" | Code !! scope="col" | Glyph !! scope="col" | Mnemonic !! scope="col" | Rotation !! scope="col" | Distinguishing features
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Corner family (C), 7 signs
|-
| C01 || [[File:C01.svg|24px|alt=C01|link=]] || CORNER-NW || rot0 || shape=right-angle, open=NE, marks=none
|-
| C02 || [[File:C02.svg|24px|alt=C02|link=]] || CORNER-SE || rot180 || shape=right-angle, open=SE, marks=none
|-
| C03 || [[File:C03.svg|24px|alt=C03|link=]] || CORNER-SE-DOT || rot180 || shape=right-angle, open=SE, dot=centerline
|-
| C04 || [[File:C04.svg|24px|alt=C04|link=]] || CORNER-NW-DIAG || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE
|-
| C05 || [[File:C05.svg|24px|alt=C05|link=]] || CORNER-SE-DIAG || rot180 || shape=right-angle, open=SE, tick=diagonal, axis=NW-SE
|-
| C06 || [[File:C06.svg|24px|alt=C06|link=]] || CORNER-NW-DIAG-DOT || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE, dot=centerline
|-
| C07 || [[File:C07.svg|24px|alt=C07|link=]] || CORNER-SE-DIAG-DOT || rot180 || shape=right-angle, open=SE, notch=orthogonal, depth=short, dot=centerline
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Box family (B), 5 signs
|-
| B01 || [[File:B01.svg|24px|alt=B01|link=]] || BOX || rot0 || outline=square, interior=clear
|-
| B02 || [[File:B02.svg|24px|alt=B02|link=]] || BOX-DOT || rot0 || outline=square, dot=center
|-
| B03 || [[File:B03.svg|24px|alt=B03|link=]] || BOX-TICK || rot0 || outline=square, notch=orthogonal, wall=top, depth=short
|-
| B04 || [[File:B04.svg|24px|alt=B04|link=]] || BOX-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE
|-
| B05 || [[File:B05.svg|24px|alt=B05|link=]] || BOX-DOT-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE, dot=corner_NE
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Triangle family (A), 5 signs
|-
| A01 || [[File:A01.svg|24px|alt=A01|link=]] || TRI-OPEN || rot0 || closure=open, apex=up
|-
| A02 || [[File:A02.svg|24px|alt=A02|link=]] || TRI-BAR || rot180 || closure=open, apex=down, bar=1, position=mid
|-
| A03 || [[File:A03.svg|24px|alt=A03|link=]] || TRI-DOT || rot180 || closure=open, apex=down, bar=1, position=mid, dot=center
|-
| A04 || [[File:A04.svg|24px|alt=A04|link=]] || TRI-VEE || rot180 || closure=open, apex=down, vee=1, orientation=apex-base
|-
| A05 || [[File:A05.svg|24px|alt=A05|link=]] || TRI-CLOSED-BAR || rot0 || closure=closed, apex=up, bar=1, position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Line family (L), 2 signs
|-
| L01 || [[File:L01.svg|24px|alt=L01|link=]] || LINE-VERT || rot0 || orientation=vertical, length=cell
|-
| L02 || [[File:L02.svg|24px|alt=L02|link=]] || LINE-HOR || rot90 || orientation=horizontal, length=cell
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Tee family (T), 3 signs
|-
| T01 || [[File:T01.svg|24px|alt=T01|link=]] || TEE-UP || rot0 || stem=vertical, bar=top
|-
| T02 || [[File:T02.svg|24px|alt=T02|link=]] || TEE-LEFT || rot90 || stem=horizontal, bar=left
|-
| T03 || [[File:T03.svg|24px|alt=T03|link=]] || UPSIDE-DOWN-TEE || rot180 || stem=vertical, bar=bottom
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Comb family (M), 3 signs
|-
| M01 || [[File:M01.svg|24px|alt=M01|link=]] || COMB-2-N || rot0 || tines=2, stem=vertical, tines_side=left/top
|-
| M02 || [[File:M02.svg|24px|alt=M02|link=]] || COMB-2-W || rot0 || tines=2, stem=vertical, tines_side=left
|-
| M03 || [[File:M03.svg|24px|alt=M03|link=]] || COMB-3-E || rot0 || tines=3, stem=vertical, tines_side=right
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Meander family (S), 3 signs
|-
| S01 || [[File:S01.svg|24px|alt=S01|link=]] || MEANDER-2 || rot0 || elements=2, hollow=false
|-
| S02 || [[File:S02.svg|24px|alt=S02|link=]] || MEANDER-2-HOLLOW || rot0 || elements=2, hollow=true
|-
| S03 || [[File:S03.svg|24px|alt=S03|link=]] || MEANDER-3 || rot0 || elements=3, hollow=false
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Barred-post family (H), 3 signs
|-
| H01 || [[File:H01.svg|24px|alt=H01|link=]] || DOUBLE-POST-CONNECTED || rot0 || posts=2, parallel, connector=base, bars=0
|-
| H02 || [[File:H02.svg|24px|alt=H02|link=]] || POST-DOUBLE-BAR || rot0 || posts=1, bars=2, bar_style=cross, bar_positions=mid, upper
|-
| H03 || [[File:H03.svg|24px|alt=H03|link=]] || DOUBLE-POST-BAR || rot0 || posts=2, parallel, bars=1, bridging=true, bar_position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Punct family (P), 1 sign
|-
| P01 || [[File:P01.svg|24px|alt=P01|link=]] || SLASH || rot30 || punct=slash, function=separator
|}

== Distributional classes ==
Working only from sign distributions in three longer inscriptions, Voudrin, Marchand and Leclerc (2024) found that the inventory partitions almost deterministically into two classes with the behaviour expected of consonants and vowels. The consonant-like class comprises the Corner, Box, Triangle and Comb families; the vowel-like class comprises the Tee, Line, Meander and Barred-post families. No family was split between the two classes.<ref name="Voudrin2024">Camille Voudrin, Solène Marchand, and Hadrien Leclerc, “A distributional test of vowel–consonant structure in an undeciphered signary suggests robust class separation,” ''[[Language Codes]]'' 7 (2024): 1281–1294.</ref> The authors stress that this is a structural result and not a decipherment.

== The corpus ==
Texts transcribed in the system, in order of publication:
* '''[[Scapula Glyph Inscription]]''' (KS-01), 2023. Four ruled lines on a scapula-shaped object; the abecedary-like presentation from which the signary was compiled.
* '''A longer companion inscription''', 2023. Six lines and 146 tokens supplied as a transcription, analysed statistically in Kristiansen's longer working paper.
* '''[[Dozenal Primer Inscription]]''', 2024. Forty-five clauses read by [[Ginevra Rubergskier]] as a primer for base-12 arithmetic.
* '''Three extended inscriptions''', 2024. The material analysed by Voudrin and colleagues for vowel–consonant structure; published as vector tracings in their paper.
* '''[[Zagi Tablets]]''', 2024. One hundred and four sentences on four clay tablets, headed in Akkadian ''imri Zagi-ak'', analysed by [[Inrik Üksküla]] and, on the blog ''[[Klema Field Notes]]'', by [[Marie Roelandt]].

Whether these texts share a single origin is not established. They share a sign inventory, the divider, and the same broad clause architecture; the Zagi Tablets add a cuneiform rendering and an Akkadian heading that the others lack.

No physical object has been securely tied to any of them. The [[Yedoma Ledger]], a mammoth-ivory plaque with ruled incised registers recovered from Siberian permafrost in 2021, has been proposed informally as the carrier of the longer companion inscription, on grounds of chronology and register geometry rather than of any published sign comparison; neither its excavator nor Kristiansen has endorsed the identification.

== Reception ==
The system's chief virtue is that it commits its users to nothing. Rubergskier's arithmetic reading, Voudrin's phonological partition and Roelandt's genealogical reading all operate on the same codes and can be compared token for token, which would be impossible had each study adopted its own transliteration. Roelandt's working transliteration into Latin letters is explicitly a readability aid layered on top of the codes, not a replacement for them.

Critics note that the neutrality is also a limitation: the codes freeze Kristiansen's initial segmentation of the signs, and any sign he merged or split in 2023 is merged or split in every later study. Kristiansen himself has issued only minor corrections since, describing his role as “keeping the inventory honest.”

== Name ==
“Kristiansen corpus” and “Kristiansen coding system” are descriptive conveniences, like “Dozenal Primer Inscription” and “Zagi Tablets”; none is a claim about what the writers called anything. The word '''Klema''' entered the field in 2024 from outside it. Line 58 of the [[Nordland Itinerary]], in the part of that text edited in Weidner's overlooked 1939 addendum, records what the people at “the head of the lands” called their tongue: ''ki-li-ma'', glossed by the scribe's interpreter as “the living tongue”. [[Marie Roelandt]], who had located the addendum, named her blog ''[[Klema Field Notes]]'' after it in March 2024, and the word spread from the blog into informal usage for the sign system and the language presumed to lie behind it, on the strength of geography alone: the itinerary places a language so called in the forest zone north of the Caspian around 2100 BC, and the [[Yedoma Ledger]] comes from the north Eurasian permafrost.

Users of the name generally acknowledge that it is a misnomer of the Hittite type. Nothing connects the people the Sumerian expedition met with the people who wrote the corpus, the itinerary itself says the tongue it heard was unwritten, and the cuneiform spelling breaks up a word that may have begun with a consonant cluster. Kristiansen has declined to use it, on the ground that a name is a hypothesis. Rubergskier and Üksküla use it in correspondence and not in print. It has nevertheless become the ordinary short name, and this encyclopedia follows that usage where no more precise term is needed.

== See also ==
* [[Jan-Tage Kristiansen]]
* [[Scapula Glyph Inscription]]
* [[Dozenal Primer Inscription]]
* [[Zagi Tablets]]
* [[Language Codes]]
* [[Klema Field Notes]]
* [[Nordland Itinerary]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Writing systems]]
[[Category:Epigraphy]]

Nordland Itinerary

2026-09-24T10:57:49Z

Mvuijlst: Add Weidner's 1939 addendum: lines 46-67 and colophon, the name ki-li-ma (Klema), Hittite-type misnomer section

[[File:Weidner 1938 Abb 1.jpg|thumb|Weidner's Abb. 1: a caravan descending from a rocky mountain edge into a wide, snow-covered steppe (pen drawing, 1938).]]
The '''Nordland Itinerary''' (German ''Reisebericht ins Nordland'') is the conventional name for a Sumerian travel account preserved on an Old Babylonian school tablet and published in 1938 by H. Weidner as “Ein neusumerischer Reisebericht ins Nordland” in the ''Mitteilungen der Deutschen Orient-Gesellschaft zu Leipzig''.<ref name="Weidner1938">H. Weidner, “Ein neusumerischer Reisebericht ins Nordland,” ''Mitteilungen der Deutschen Orient-Gesellschaft zu Leipzig'' 27 (April 1938).</ref> It records the stages of a royal expedition that left northern Mesopotamia, crossed the Zagros and the Iranian plateau, reached the southern shore of the Caspian and continued through the steppe corridor towards the Urals, and it is the only cuneiform text that describes snow, a frozen river and the northern lights.

Weidner assigned the composition to the Ur III period, around 2100 BC, and treated the surviving tablet as a later copy made for teaching. His 1938 article published some thirty lines from the third and fourth columns. The remaining lines of the fourth column, with the colophon, appeared a year later in a short addendum that was long overlooked;<ref name="Weidner1939">H. Weidner, “Nachtrag zum neusumerischen Reisebericht ins Nordland,” ''Mitteilungen der Deutschen Orient-Gesellschaft zu Leipzig'' 29 (1939).</ref> they contain the only foreign language name recorded by a Mesopotamian source north of the Caspian, ''ki-li-ma'', from which the modern term [[Kristiansen coding system|Klema]] is taken.

== The tablet ==
The text survives on a medium-sized four-column tablet of light brown clay. Palaeographically the hand is Old Babylonian. A colophon on the lower edge of the reverse, partly preserved, gives the total number of travelling days. In 1938 Weidner read the surviving figure as a little over six months; the addendum, which gives the line in full, shows the numeral broken at its left edge, and “[1]6 months and 12 days” is now the accepted reading, which suits a journey whose snowfall comes in the seventh month.<ref name="Weidner1938" /><ref name="Weidner1939" />

Weidner argued that the composition itself is older than its copy on three grounds: the text is written consistently in Sumerian rather than in Akkadian with Sumerian glosses; its vocabulary and style match the elevated idiom of the Neo-Sumerian royal hymns; and particular theological turns, above all the presentation of Enki as a river god who has “his dwelling” in the frozen river, stand closest to texts of the time of Šulgi. He therefore placed its composition at an Ur III court, in Ur itself or in Nippur, and its copying in the Old Babylonian school, where it served as an exercise or reading text.

The itinerary belongs to a small class of Mesopotamian texts that record day-marches and stages of travel, of which the best known real example is the Old Babylonian itinerary published by Goetze in 1953.<ref name="Goetze1953">A. Goetze, “An Old Babylonian Itinerary,” ''Journal of Cuneiform Studies'' 7 (1953): 51–72.</ref> Weidner's text differs from that class in one respect: at the decisive transitions of the journey the scribe abandons the bare listing of stages for short passages in a poetic register, in which the strangeness of the northern lands is put into words.

== Contents ==
The published text begins where the expedition leaves the mountains. The badly damaged lines before it mention, in Akkadian, toponyms of the north-eastern frontier of the Sumerian world: Subartu, Lullubu and perhaps Elam, together with “narrow ways in the mountains” (''sila tur-tur kur-ra''). Weidner read this as a crossing from the Upper Mesopotamian lowland over a pass north of Arbela into the Zagros.

Three Sumerian passages were published in 1938.

;Steppe and wagon peoples (lines 16–25)
:The travellers reach “very great rivers” whose “foreign tongues we did not know”, meet “men with boats and pack animals” who “set many wagons in motion”, negotiate with the caravan, and receive “weapons and strong hands”, which Weidner took to mean an armed escort through unsafe country. The land has no city; its people “do not eat grain bread, they eat only pig and fat cattle.”
;Cold, snow and the frozen river (lines 26–35)
:“In the seventh month white things moved from the sky, like chaff of the great threshing floor they fell to earth, the land became white, our great river became white.” Men and donkeys put their weight on the ice and carry “the water things over the water”. The foreigners say the river “is no longer there”; the scribe answers that this is “the house-river of Enki”, the place where the river god has set his dwelling.
;Forest, furs and sky lights (lines 36–45)
:“Trees upon trees are in the foreign lands; in three days one cannot count them to an end.” The people of the forest eat “the necks of thick-haired beasts” and bring heavy furs and fine hides “for the neck of the king”. In the sky “birds” move, “fast as eyes that are set, like shining gold and lapis lazuli”; the locals say “there our gods are set”, and the scribe replies that “it is Inanna who lays her hand to rest there.”

The addendum of 1939 added the rest of the fourth column.

;The head of the lands (lines 46–52)
:The expedition reaches “the head of the lands”, where “a great river touches the heart of the foreign lands” and there is “no city, no cultivated place”. A stone is set up for the king, beer and fine oil are poured, and “the name of the king of the land” is set down at the head of the lands.
;The furthest people and their tongue (lines 53–60)
:The people there “dwell in houses of hide”, “know no donkey, know no wagon”, and have “great-horned oxen” that “draw a sledge over the whiteness”. Their tongue “is apart from the tongues of the other lands” and has to be turned “through a third interpreter”. Line 58 then records the name: ''eme-bi ki-li-ma-še3 mu-un-sa4-e-ne'', “their tongue they call ''ki-li-ma''” (𒆠𒇷𒈠). The interpreter glosses it (line 59) as ''eme ti-la'', “the living tongue”. The scribe closes the exchange in his usual manner (line 60): “it is a tongue that Nisaba does not know”, Nisaba being the goddess of writing; that is, an unwritten one.
;Gifts, the tusk and the return (lines 61–67)
:The people give “heavy hides, horns of the great-horned ox, and the tusk of the elephant of that land”; “the elephant of that land no one saw”. The foreigners say the tusk “comes out of the earth”; the scribe answers that “it is the bull of Enki that lies in the earth”. In the ninth month the expedition turns back towards Ur, leaves the frozen river on foot, and carries “the hides and the tusk for the neck of the king”. The column ends there; the return route is not described.

== Weidner's commentary ==
Weidner's commentary follows the route stage by stage. The “rivers of very many woods” of line 16 he located in the upper Diyala or Sirwan system; the wagon peoples in the contact zone between mountain and plateau, where river transport, caravan traffic and an early wagon culture met; and the frozen river north of the Elburz, either the lower Safid Rud or, further north, a tributary of the Caspian in the Transcaspian lowland, while admitting that the material does not allow identification. The forest zone with its fur-bearing animals and its “sky lights”, which he took to be the aurora, he placed in the belt of woodland stretching from the Caspian basin towards the Urals, where the Eurasian steppe corridor opens.

Two smaller observations have been widely quoted. Line 20, ''anše-kur-ra-ĝu10 ma-da-an-du11'', “they spoke to my mountain donkey in their land”, he read as a joke of the scribe's: the whole Sumerian caravan personified as “donkey people” with whom the local wagon-drivers must first negotiate. And the repeated pattern in which the foreigners explain a phenomenon and the scribe reinterprets it through his own gods, the frozen river as Enki's house, the lights as Inanna's hand, he singled out as the characteristic method by which a Mesopotamian scholar absorbed the foreign into his own world. The addendum shows the pattern continuing to the end of the text: the unwritten tongue becomes one “Nisaba does not know”, and ivory dug from the ground becomes “the bull of Enki that lies in the earth”.

On the tusk Weidner was brief: ''zu2 am-si'' is the ordinary Sumerian word for ivory, and the scribe has a word for the material but none for the animal. He compared the reports of fossil ivory gathered from river banks and thawing ground in northern Siberia, without drawing further conclusions.<ref name="Weidner1939" />

In his closing remarks Weidner drew the wider conclusion that the connection from northern Mesopotamia over the Zagros, the Iranian plateau and the Caspian rim to the north Eurasian forest and steppe region was, at least occasionally, a real and not merely an imagined one.

== The name ''ki-li-ma'' ==
Line 58 is the only place in the text where a foreign word is written out rather than described. The three signs 𒆠𒇷𒈠 can be read ''ki-li-ma'' or ''ke4-le-ma''. Sumerian orthography cannot write two consonants at the beginning of a word, and foreign names with initial clusters are regularly broken up with a vowel in cuneiform, so a form with a cluster, ''klema'' or ''klima'', is at least as likely as the four-syllable one. What the scribe was told the word meant is given in the next line, “the living tongue”.

Weidner treated the name as a curiosity. It acquired a second life in the 2020s, when writers on the [[Kristiansen coding system|Kristiansen corpus]] began to use “Klema” for the sign system and the language presumed to lie behind it, on the strength of geography alone: the itinerary places a language so called in the forest zone north of the Caspian around 2100 BC, and the [[Yedoma Ledger]], the only physical object proposed as a carrier of the corpus, comes from the north Eurasian permafrost. The blog ''[[Klema Field Notes]]'' carries the name in its title. No published study has argued that the people the expedition met were the people who wrote the corpus, and the tablets themselves say the tongue was unwritten.

The name is therefore a misnomer of a familiar kind. Hittite is named after the land of Hatti and its biblical inhabitants, while the speakers of the language called it ''nešili'', after the city of Neša; the label stuck because it was the first one available, and philology has lived with it. “Klema” names a language by the word a Sumerian scribe heard from a forest people who may or may not have been its speakers, and applies it to a script that no Sumerian ever saw. Its users accept this. Roelandt has written that it may be “the wrong name for the wrong script”, and that it is nevertheless “a better name than ‘the Kristiansen corpus’”.

== Publication and reception ==
The 1938 article appeared in April and was illustrated with a single pen drawing of a caravan descending into a snowy steppe. It gives the tablet's physical description but not its museum number or present whereabouts, and no photograph or hand copy of the tablet was included. The addendum of 1939, a few pages in a late issue of the same series, supplied the transliteration and translation of the remaining lines and the colophon, again without a copy or photograph. Published on the eve of the war in a small print run, it was not cited for decades, and the remainder of the text was widely believed to be unedited until the addendum was identified in 2026.<ref name="Weidner1939" />

The itinerary is cited in discussion of the [[Kristiansen coding system|Kristiansen corpus]] for two reasons. It is the earliest text placing a literate Mesopotamian expedition in the north Eurasian forest zone, the broad region from which the [[Yedoma Ledger]] was later recovered, and it carries the name that the corpus has come to bear. Nothing in either publication mentions inscribed bone or ivory or any encounter with a script; the one statement about writing in the text is the scribe's own, that the tongue he heard was unwritten. No direct connection between the itinerary and the corpus has been proposed in print.

== See also ==
* [[Yedoma Ledger]]
* [[Kristiansen coding system]]
* [[Klema Field Notes]]
* [[Dur-Untash Expedition]]

== References ==
<references />

[[Category:Klema]]
[[Category:Epigraphy]]
[[Category:Parafictional Mesopotamian archaeology]]

File:Weidner 1938 Abb 1.jpg

2026-09-22T11:07:19Z

Mvuijlst: Abb. 1 of Weidner 1938: caravan descending into a snowy steppe (from the zog repo, downscaled)

Abb. 1 of Weidner 1938: caravan descending into a snowy steppe (from the zog repo, downscaled)

Kristiansen coding system

2026-09-22T11:06:57Z

Mvuijlst: See also: Nordland Itinerary

The '''Kristiansen coding system''' is the alphanumeric notation used in the scholarly literature to transcribe the geometric signs of the [[Scapula Glyph Inscription]] and the other texts that share its sign repertory, collectively referred to as the '''Kristiansen corpus'''. Each sign receives a family letter and a two-digit index (for example C01, B04, P01). The system was introduced by [[Jan-Tage Kristiansen]] in a 2023 correspondence note and has since been adopted without modification by every subsequent study.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

The codes are deliberately neutral. They record what a sign looks like and how it is built, not what it might mean or sound like. No phonetic values have been proposed in the literature, and the mnemonic names attached to the codes (BOX-DOT, TEE-LEFT, and so on) are descriptive labels only.

== Principles ==
Kristiansen's note set out three rules that later work has kept:
* '''One code per sign.''' Every distinct grapheme in the inventory receives one code; no code is assigned to a sequence.
* '''Family letter plus index.''' The letter names one of eight visually coherent families, identified by shared construction (a corner, a closed box, a triangle, and so on). The index numbers the members of a family in the order they appear on the scapula. A ninth letter, P, is reserved for the single divider sign.
* '''Rotation and diacritics are features, not new families.''' Signs that differ only by rotation or by an added dot, bar or diagonal tick stay within their family and are distinguished by index. Kristiansen's original signary carried a rotation column; later work by [[Camille Voudrin]] and colleagues treated rotation as a non-contrastive convenience and canonicalised signs rotation-agnostically, with no effect on the inventory.

== Transcription conventions ==
* Signs within a word are joined by hyphens: <code>C01-M03-S01-C02</code>. Words are separated by spaces.
* The divider '''P01''' is transcribed as a sign in its own right. In the [[Dozenal Primer Inscription]] and the [[Zagi Tablets]] it occurs only at clause ends and is written bound to the last word of the clause (<code>…-T03-P01</code>).
* Sentences in the longer corpora are numbered by document and position, for example <code>F3_44</code> for the forty-fourth sentence in Document 3 of the Zagi Tablets. This numbering originates with [[Inrik Üksküla]]'s preprint and is used by [[Marie Roelandt]].
* Uncertain or damaged signs are written <code>??</code> in place of a code.

== The signary ==
The unified signary contains 31 signs in eight families plus the divider, 32 codes in all. Every one of them is attested once on the scapula (KS-01), which presents the families as an ordered sweep and so fixes the index order.<ref name="Kristiansen2023h" /> Rotation and feature descriptions follow Kristiansen's catalogue.

{| class="wikitable" style="font-size:95%;"
! scope="col" | Code !! scope="col" | Glyph !! scope="col" | Mnemonic !! scope="col" | Rotation !! scope="col" | Distinguishing features
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Corner family (C), 7 signs
|-
| C01 || [[File:C01.svg|24px|alt=C01|link=]] || CORNER-NW || rot0 || shape=right-angle, open=NE, marks=none
|-
| C02 || [[File:C02.svg|24px|alt=C02|link=]] || CORNER-SE || rot180 || shape=right-angle, open=SE, marks=none
|-
| C03 || [[File:C03.svg|24px|alt=C03|link=]] || CORNER-SE-DOT || rot180 || shape=right-angle, open=SE, dot=centerline
|-
| C04 || [[File:C04.svg|24px|alt=C04|link=]] || CORNER-NW-DIAG || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE
|-
| C05 || [[File:C05.svg|24px|alt=C05|link=]] || CORNER-SE-DIAG || rot180 || shape=right-angle, open=SE, tick=diagonal, axis=NW-SE
|-
| C06 || [[File:C06.svg|24px|alt=C06|link=]] || CORNER-NW-DIAG-DOT || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE, dot=centerline
|-
| C07 || [[File:C07.svg|24px|alt=C07|link=]] || CORNER-SE-DIAG-DOT || rot180 || shape=right-angle, open=SE, notch=orthogonal, depth=short, dot=centerline
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Box family (B), 5 signs
|-
| B01 || [[File:B01.svg|24px|alt=B01|link=]] || BOX || rot0 || outline=square, interior=clear
|-
| B02 || [[File:B02.svg|24px|alt=B02|link=]] || BOX-DOT || rot0 || outline=square, dot=center
|-
| B03 || [[File:B03.svg|24px|alt=B03|link=]] || BOX-TICK || rot0 || outline=square, notch=orthogonal, wall=top, depth=short
|-
| B04 || [[File:B04.svg|24px|alt=B04|link=]] || BOX-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE
|-
| B05 || [[File:B05.svg|24px|alt=B05|link=]] || BOX-DOT-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE, dot=corner_NE
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Triangle family (A), 5 signs
|-
| A01 || [[File:A01.svg|24px|alt=A01|link=]] || TRI-OPEN || rot0 || closure=open, apex=up
|-
| A02 || [[File:A02.svg|24px|alt=A02|link=]] || TRI-BAR || rot180 || closure=open, apex=down, bar=1, position=mid
|-
| A03 || [[File:A03.svg|24px|alt=A03|link=]] || TRI-DOT || rot180 || closure=open, apex=down, bar=1, position=mid, dot=center
|-
| A04 || [[File:A04.svg|24px|alt=A04|link=]] || TRI-VEE || rot180 || closure=open, apex=down, vee=1, orientation=apex-base
|-
| A05 || [[File:A05.svg|24px|alt=A05|link=]] || TRI-CLOSED-BAR || rot0 || closure=closed, apex=up, bar=1, position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Line family (L), 2 signs
|-
| L01 || [[File:L01.svg|24px|alt=L01|link=]] || LINE-VERT || rot0 || orientation=vertical, length=cell
|-
| L02 || [[File:L02.svg|24px|alt=L02|link=]] || LINE-HOR || rot90 || orientation=horizontal, length=cell
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Tee family (T), 3 signs
|-
| T01 || [[File:T01.svg|24px|alt=T01|link=]] || TEE-UP || rot0 || stem=vertical, bar=top
|-
| T02 || [[File:T02.svg|24px|alt=T02|link=]] || TEE-LEFT || rot90 || stem=horizontal, bar=left
|-
| T03 || [[File:T03.svg|24px|alt=T03|link=]] || UPSIDE-DOWN-TEE || rot180 || stem=vertical, bar=bottom
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Comb family (M), 3 signs
|-
| M01 || [[File:M01.svg|24px|alt=M01|link=]] || COMB-2-N || rot0 || tines=2, stem=vertical, tines_side=left/top
|-
| M02 || [[File:M02.svg|24px|alt=M02|link=]] || COMB-2-W || rot0 || tines=2, stem=vertical, tines_side=left
|-
| M03 || [[File:M03.svg|24px|alt=M03|link=]] || COMB-3-E || rot0 || tines=3, stem=vertical, tines_side=right
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Meander family (S), 3 signs
|-
| S01 || [[File:S01.svg|24px|alt=S01|link=]] || MEANDER-2 || rot0 || elements=2, hollow=false
|-
| S02 || [[File:S02.svg|24px|alt=S02|link=]] || MEANDER-2-HOLLOW || rot0 || elements=2, hollow=true
|-
| S03 || [[File:S03.svg|24px|alt=S03|link=]] || MEANDER-3 || rot0 || elements=3, hollow=false
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Barred-post family (H), 3 signs
|-
| H01 || [[File:H01.svg|24px|alt=H01|link=]] || DOUBLE-POST-CONNECTED || rot0 || posts=2, parallel, connector=base, bars=0
|-
| H02 || [[File:H02.svg|24px|alt=H02|link=]] || POST-DOUBLE-BAR || rot0 || posts=1, bars=2, bar_style=cross, bar_positions=mid, upper
|-
| H03 || [[File:H03.svg|24px|alt=H03|link=]] || DOUBLE-POST-BAR || rot0 || posts=2, parallel, bars=1, bridging=true, bar_position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Punct family (P), 1 sign
|-
| P01 || [[File:P01.svg|24px|alt=P01|link=]] || SLASH || rot30 || punct=slash, function=separator
|}

== Distributional classes ==
Working only from sign distributions in three longer inscriptions, Voudrin, Marchand and Leclerc (2024) found that the inventory partitions almost deterministically into two classes with the behaviour expected of consonants and vowels. The consonant-like class comprises the Corner, Box, Triangle and Comb families; the vowel-like class comprises the Tee, Line, Meander and Barred-post families. No family was split between the two classes.<ref name="Voudrin2024">Camille Voudrin, Solène Marchand, and Hadrien Leclerc, “A distributional test of vowel–consonant structure in an undeciphered signary suggests robust class separation,” ''[[Language Codes]]'' 7 (2024): 1281–1294.</ref> The authors stress that this is a structural result and not a decipherment.

== The corpus ==
Texts transcribed in the system, in order of publication:
* '''[[Scapula Glyph Inscription]]''' (KS-01), 2023. Four ruled lines on a scapula-shaped object; the abecedary-like presentation from which the signary was compiled.
* '''A longer companion inscription''', 2023. Six lines and 146 tokens supplied as a transcription, analysed statistically in Kristiansen's longer working paper.
* '''[[Dozenal Primer Inscription]]''', 2024. Forty-five clauses read by [[Ginevra Rubergskier]] as a primer for base-12 arithmetic.
* '''Three extended inscriptions''', 2024. The material analysed by Voudrin and colleagues for vowel–consonant structure; published as vector tracings in their paper.
* '''[[Zagi Tablets]]''', 2024. One hundred and four sentences on four clay tablets, headed in Akkadian ''imri Zagi-ak'', analysed by [[Inrik Üksküla]] and, on the blog ''[[Klema Field Notes]]'', by [[Marie Roelandt]].

Whether these texts share a single origin is not established. They share a sign inventory, the divider, and the same broad clause architecture; the Zagi Tablets add a cuneiform rendering and an Akkadian heading that the others lack.

No physical object has been securely tied to any of them. The [[Yedoma Ledger]], a mammoth-ivory plaque with ruled incised registers recovered from Siberian permafrost in 2021, has been proposed informally as the carrier of the longer companion inscription, on grounds of chronology and register geometry rather than of any published sign comparison; neither its excavator nor Kristiansen has endorsed the identification.

== Reception ==
The system's chief virtue is that it commits its users to nothing. Rubergskier's arithmetic reading, Voudrin's phonological partition and Roelandt's genealogical reading all operate on the same codes and can be compared token for token, which would be impossible had each study adopted its own transliteration. Roelandt's working transliteration into Latin letters is explicitly a readability aid layered on top of the codes, not a replacement for them.

Critics note that the neutrality is also a limitation: the codes freeze Kristiansen's initial segmentation of the signs, and any sign he merged or split in 2023 is merged or split in every later study. Kristiansen himself has issued only minor corrections since, describing his role as “keeping the inventory honest.”

== See also ==
* [[Jan-Tage Kristiansen]]
* [[Scapula Glyph Inscription]]
* [[Dozenal Primer Inscription]]
* [[Zagi Tablets]]
* [[Language Codes]]
* [[Klema Field Notes]]
* [[Nordland Itinerary]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Writing systems]]
[[Category:Epigraphy]]

Yedoma Ledger

2026-09-22T11:06:56Z

Mvuijlst: See also: Nordland Itinerary

{{Infobox
| name = Yedoma Ledger
| image = Yenoma Ledger.jpg
| caption = Plaque with incised geometric registers
| 1 Material = [[Ivory|Mammoth ivory]] (''[[Woolly mammoth|Mammuthus primigenius]]'')
| 2 Writing = Geometric incisions
| 3 Created = Substrate plausibly Last Interglacial (~125 ka); age of carving undetermined
| 4 Discovered_place = Lower [[Indigirka River|Indigirka]] basin, northeast [[Siberia]] (Russia)
| 5 Discovered_date = Late August (year per preliminary report)
| 6 Present_location = Regional heritage authority
| 7 Dimensions = ~216 × 54 × 39 mm; ~486 g
}}

The '''Yedoma Ledger''' is a worked plaque of mammoth ivory reportedly recovered from [[permafrost]] in the lower Indigirka region of northeast Siberia. The object was discovered and handled in the field by a small team led by [[J. Levi Schültke]] during a rapid-impact survey of thaw gullies commissioned to document erosion threats to organic artefacts; Schültke’s group was engaged for its prior experience with cold-chain recovery and identification of proboscidean ivory.<ref name="Schueltke2021">J. Levi Schültke, ''A Mammoth-Ivory Plaque with Geometric Incisions from Northeast Siberia: Discovery, Context, and Materials Analysis'' (preliminary field and materials report, Seminar für Archäologie der Periglazialzonen, 2021).</ref> Its carved surface shows parallel bands of straight and oblique incisions, including chevrons and cross-hatching. The preliminary report describes controlled cold-chain recovery and non-destructive documentation but does not advance a cultural attribution or secure the age of the carving itself.<ref name="Schueltke2021" />

== Discovery and context ==
According to the report, the plaque was noticed by the team in a thaw gully within ice-rich loess ([[Yedoma]]) and recovered with surrounding sediment using bagged blocks and refrigerated transport overseen by the regional heritage authority.<ref name="Schueltke2021" /> Yedoma sequences in Siberia are known to preserve Late Pleistocene faunal remains and organic materials that can be reworked by [[thermokarst]] processes, complicating archaeological context.<ref name="Schirrmeister2022">Lutz Schirrmeister, “Yedoma Permafrost Landscapes as Past Archives and Future Change Hotspots,” ''Frontiers in Earth Science'' 10 (2022): 929873, [https://doi.org/10.3389/feart.2022.929873](https://doi.org/10.3389/feart.2022.929873).</ref>

== Description ==
The object follows the natural camber of tusk ivory and presents a prepared, flatter face with multiple incised registers bounded by guide lines. Identification as mammoth ivory is supported by observation of [[Schreger lines]], a standard criterion in proboscidean ivory analysis.<ref name="CITES2020">“Identification Guide for Ivory and Ivory Substitutes,” CITES (2020), [https://cites.org/sites/default/files/ID_Manuals/Identification_Guide_for_Ivory_and_Ivory_Substitutes_ENGLISH.pdf](https://cites.org/sites/default/files/ID_Manuals/Identification_Guide_for_Ivory_and_Ivory_Substitutes_ENGLISH.pdf).</ref>

== Dating ==
Screening methods reported include FTIR for collagen/mineral preservation, [[amino acid racemization]] (AAR) on a detached lamella, and [[optically stimulated luminescence]] (OSL) on associated sediment. These results are consistent with an ancient Pleistocene substrate but do not directly date the carving. Open-system behavior in bones and dentine limits the reliability of some radiometric approaches; targeted dating of incision surfaces has not yet been published.<ref name="Schueltke2021" /><ref name="Penkman2022">K. Penkman, “Dating the Paleolithic: trapped charge and amino acid geochronology,” ''Evolutionary Anthropology'' 31, no. 5 (2022): 203–222, [https://doi.org/10.1002/evan.21958](https://doi.org/10.1002/evan.21958).</ref><ref name="Lian2006">O. B. Lian, “Dating the Quaternary: progress in luminescence dating,” ''Quaternary Science Reviews'' 25, nos. 19–20 (2006): 2449–2468, [https://doi.org/10.1016/j.quascirev.2005.11.013](https://doi.org/10.1016/j.quascirev.2005.11.013).</ref>

== Interpretation ==
Published descriptions remain neutral and descriptive; no consensus interpretation (notation, decoration, or other function) has been advanced. Pending secure dating and replication studies, the Yedoma Ledger is cited as a candidate example of worked ivory from permafrost context rather than as evidence for a particular symbolic system.<ref name="Schueltke2021" />

== Possible relation to the Kristiansen corpus ==
Since 2024 the Ledger has been discussed, so far only informally, as a candidate physical carrier for material in the [[Kristiansen coding system]]. The suggestion rests on three observations rather than on any direct comparison of signs.

First, chronology. Schültke's preliminary report, which circulated in 2021, describes the incised face as a series of registers bounded by guide lines but publishes only one photograph and no tracing. [[Jan-Tage Kristiansen]]'s 2023 correspondence note and his longer working paper were based on drawings and a transcription received by anonymous email in the two years that followed, with no indication of the object drawn.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

Second, geometry. The scapula inscription (KS-01) is a short abecedary and cannot be the Ledger, whose registers run the full 216 mm of the prepared face. Kristiansen's ''longer companion inscription'', however, was supplied as a transcription only: six lines, 146 tokens, medium unstated. At the roughly one-centimetre sign pitch reported for the scapula, a 216 mm register holds about twenty signs, which is in keeping with a six-line text averaging some twenty-four tokens a line. The stroke repertoire described by Schültke, straight and oblique cuts with chevrons and cross-hatching, is consistent with the Triangle, Barred-post and Comb families of the signary, though it is equally consistent with a great deal of Upper Palaeolithic ornament.

Third, the absence of any other candidate. The Ledger is the only object publicly documented from a controlled recovery whose incisions are organised in ruled registers of the kind the Kristiansen corpus presupposes.

None of this amounts to an identification. Schültke has not commented on the Kristiansen literature, and his report predates it. Kristiansen, asked whether the anonymous transcription could derive from the Ledger, replied that he had “no basis for saying so and no basis for denying it,” and that the question would be settled by a full-resolution tracing of the Ledger's registers, which the regional heritage authority has not released.<ref name="Kristiansen2023h" /> Until such a tracing exists the Ledger remains, in the words of its own preliminary report, a candidate example of worked ivory from permafrost context, and the Kristiansen corpus remains a set of drawings without an object.

== Significance ==
The find highlights both the potential and the difficulties of researching artefacts emerging from rapidly changing permafrost landscapes. It has been noted in discussions of best practice for recovery, minimal-intervention conservation (e.g. reversible consolidants), and multi-modal imaging such as [[reflectance transformation imaging]] in Arctic and sub-Arctic contexts.<ref name="Schueltke2021" /><ref name="HE2016">Historic England, ''Multi-Light Imaging for Heritage Applications (incl. H-RTI)'' (2016), [https://historicengland.org.uk/images-books/publications/multi-light-imaging-heritage-applications/](https://historicengland.org.uk/images-books/publications/multi-light-imaging-heritage-applications/).</ref>

== See also ==

* [[Kristiansen coding system]]
* [[Scapula Glyph Inscription]]
* [[Nordland Itinerary]]
* [[Yedoma]]
* [[Woolly mammoth]]
* [[Pleistocene archaeology]]
* [[Reflectance transformation imaging]]

== References ==
{{reflist}}

[[Category:Klema]]

Nordland Itinerary

2026-09-22T11:06:55Z

Mvuijlst: Create article on Weidner's 1938 Neo-Sumerian itinerary into the north

Kristiansen coding system

2026-09-22T11:03:34Z

Mvuijlst: Corpus section: note the Yedoma Ledger as the only proposed physical carrier

The '''Kristiansen coding system''' is the alphanumeric notation used in the scholarly literature to transcribe the geometric signs of the [[Scapula Glyph Inscription]] and the other texts that share its sign repertory, collectively referred to as the '''Kristiansen corpus'''. Each sign receives a family letter and a two-digit index (for example C01, B04, P01). The system was introduced by [[Jan-Tage Kristiansen]] in a 2023 correspondence note and has since been adopted without modification by every subsequent study.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

The codes are deliberately neutral. They record what a sign looks like and how it is built, not what it might mean or sound like. No phonetic values have been proposed in the literature, and the mnemonic names attached to the codes (BOX-DOT, TEE-LEFT, and so on) are descriptive labels only.

== Principles ==
Kristiansen's note set out three rules that later work has kept:
* '''One code per sign.''' Every distinct grapheme in the inventory receives one code; no code is assigned to a sequence.
* '''Family letter plus index.''' The letter names one of eight visually coherent families, identified by shared construction (a corner, a closed box, a triangle, and so on). The index numbers the members of a family in the order they appear on the scapula. A ninth letter, P, is reserved for the single divider sign.
* '''Rotation and diacritics are features, not new families.''' Signs that differ only by rotation or by an added dot, bar or diagonal tick stay within their family and are distinguished by index. Kristiansen's original signary carried a rotation column; later work by [[Camille Voudrin]] and colleagues treated rotation as a non-contrastive convenience and canonicalised signs rotation-agnostically, with no effect on the inventory.

== Transcription conventions ==
* Signs within a word are joined by hyphens: <code>C01-M03-S01-C02</code>. Words are separated by spaces.
* The divider '''P01''' is transcribed as a sign in its own right. In the [[Dozenal Primer Inscription]] and the [[Zagi Tablets]] it occurs only at clause ends and is written bound to the last word of the clause (<code>…-T03-P01</code>).
* Sentences in the longer corpora are numbered by document and position, for example <code>F3_44</code> for the forty-fourth sentence in Document 3 of the Zagi Tablets. This numbering originates with [[Inrik Üksküla]]'s preprint and is used by [[Marie Roelandt]].
* Uncertain or damaged signs are written <code>??</code> in place of a code.

== The signary ==
The unified signary contains 31 signs in eight families plus the divider, 32 codes in all. Every one of them is attested once on the scapula (KS-01), which presents the families as an ordered sweep and so fixes the index order.<ref name="Kristiansen2023h" /> Rotation and feature descriptions follow Kristiansen's catalogue.

{| class="wikitable" style="font-size:95%;"
! scope="col" | Code !! scope="col" | Glyph !! scope="col" | Mnemonic !! scope="col" | Rotation !! scope="col" | Distinguishing features
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Corner family (C), 7 signs
|-
| C01 || [[File:C01.svg|24px|alt=C01|link=]] || CORNER-NW || rot0 || shape=right-angle, open=NE, marks=none
|-
| C02 || [[File:C02.svg|24px|alt=C02|link=]] || CORNER-SE || rot180 || shape=right-angle, open=SE, marks=none
|-
| C03 || [[File:C03.svg|24px|alt=C03|link=]] || CORNER-SE-DOT || rot180 || shape=right-angle, open=SE, dot=centerline
|-
| C04 || [[File:C04.svg|24px|alt=C04|link=]] || CORNER-NW-DIAG || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE
|-
| C05 || [[File:C05.svg|24px|alt=C05|link=]] || CORNER-SE-DIAG || rot180 || shape=right-angle, open=SE, tick=diagonal, axis=NW-SE
|-
| C06 || [[File:C06.svg|24px|alt=C06|link=]] || CORNER-NW-DIAG-DOT || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE, dot=centerline
|-
| C07 || [[File:C07.svg|24px|alt=C07|link=]] || CORNER-SE-DIAG-DOT || rot180 || shape=right-angle, open=SE, notch=orthogonal, depth=short, dot=centerline
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Box family (B), 5 signs
|-
| B01 || [[File:B01.svg|24px|alt=B01|link=]] || BOX || rot0 || outline=square, interior=clear
|-
| B02 || [[File:B02.svg|24px|alt=B02|link=]] || BOX-DOT || rot0 || outline=square, dot=center
|-
| B03 || [[File:B03.svg|24px|alt=B03|link=]] || BOX-TICK || rot0 || outline=square, notch=orthogonal, wall=top, depth=short
|-
| B04 || [[File:B04.svg|24px|alt=B04|link=]] || BOX-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE
|-
| B05 || [[File:B05.svg|24px|alt=B05|link=]] || BOX-DOT-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE, dot=corner_NE
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Triangle family (A), 5 signs
|-
| A01 || [[File:A01.svg|24px|alt=A01|link=]] || TRI-OPEN || rot0 || closure=open, apex=up
|-
| A02 || [[File:A02.svg|24px|alt=A02|link=]] || TRI-BAR || rot180 || closure=open, apex=down, bar=1, position=mid
|-
| A03 || [[File:A03.svg|24px|alt=A03|link=]] || TRI-DOT || rot180 || closure=open, apex=down, bar=1, position=mid, dot=center
|-
| A04 || [[File:A04.svg|24px|alt=A04|link=]] || TRI-VEE || rot180 || closure=open, apex=down, vee=1, orientation=apex-base
|-
| A05 || [[File:A05.svg|24px|alt=A05|link=]] || TRI-CLOSED-BAR || rot0 || closure=closed, apex=up, bar=1, position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Line family (L), 2 signs
|-
| L01 || [[File:L01.svg|24px|alt=L01|link=]] || LINE-VERT || rot0 || orientation=vertical, length=cell
|-
| L02 || [[File:L02.svg|24px|alt=L02|link=]] || LINE-HOR || rot90 || orientation=horizontal, length=cell
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Tee family (T), 3 signs
|-
| T01 || [[File:T01.svg|24px|alt=T01|link=]] || TEE-UP || rot0 || stem=vertical, bar=top
|-
| T02 || [[File:T02.svg|24px|alt=T02|link=]] || TEE-LEFT || rot90 || stem=horizontal, bar=left
|-
| T03 || [[File:T03.svg|24px|alt=T03|link=]] || UPSIDE-DOWN-TEE || rot180 || stem=vertical, bar=bottom
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Comb family (M), 3 signs
|-
| M01 || [[File:M01.svg|24px|alt=M01|link=]] || COMB-2-N || rot0 || tines=2, stem=vertical, tines_side=left/top
|-
| M02 || [[File:M02.svg|24px|alt=M02|link=]] || COMB-2-W || rot0 || tines=2, stem=vertical, tines_side=left
|-
| M03 || [[File:M03.svg|24px|alt=M03|link=]] || COMB-3-E || rot0 || tines=3, stem=vertical, tines_side=right
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Meander family (S), 3 signs
|-
| S01 || [[File:S01.svg|24px|alt=S01|link=]] || MEANDER-2 || rot0 || elements=2, hollow=false
|-
| S02 || [[File:S02.svg|24px|alt=S02|link=]] || MEANDER-2-HOLLOW || rot0 || elements=2, hollow=true
|-
| S03 || [[File:S03.svg|24px|alt=S03|link=]] || MEANDER-3 || rot0 || elements=3, hollow=false
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Barred-post family (H), 3 signs
|-
| H01 || [[File:H01.svg|24px|alt=H01|link=]] || DOUBLE-POST-CONNECTED || rot0 || posts=2, parallel, connector=base, bars=0
|-
| H02 || [[File:H02.svg|24px|alt=H02|link=]] || POST-DOUBLE-BAR || rot0 || posts=1, bars=2, bar_style=cross, bar_positions=mid, upper
|-
| H03 || [[File:H03.svg|24px|alt=H03|link=]] || DOUBLE-POST-BAR || rot0 || posts=2, parallel, bars=1, bridging=true, bar_position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Punct family (P), 1 sign
|-
| P01 || [[File:P01.svg|24px|alt=P01|link=]] || SLASH || rot30 || punct=slash, function=separator
|}

== Distributional classes ==
Working only from sign distributions in three longer inscriptions, Voudrin, Marchand and Leclerc (2024) found that the inventory partitions almost deterministically into two classes with the behaviour expected of consonants and vowels. The consonant-like class comprises the Corner, Box, Triangle and Comb families; the vowel-like class comprises the Tee, Line, Meander and Barred-post families. No family was split between the two classes.<ref name="Voudrin2024">Camille Voudrin, Solène Marchand, and Hadrien Leclerc, “A distributional test of vowel–consonant structure in an undeciphered signary suggests robust class separation,” ''[[Language Codes]]'' 7 (2024): 1281–1294.</ref> The authors stress that this is a structural result and not a decipherment.

== The corpus ==
Texts transcribed in the system, in order of publication:
* '''[[Scapula Glyph Inscription]]''' (KS-01), 2023. Four ruled lines on a scapula-shaped object; the abecedary-like presentation from which the signary was compiled.
* '''A longer companion inscription''', 2023. Six lines and 146 tokens supplied as a transcription, analysed statistically in Kristiansen's longer working paper.
* '''[[Dozenal Primer Inscription]]''', 2024. Forty-five clauses read by [[Ginevra Rubergskier]] as a primer for base-12 arithmetic.
* '''Three extended inscriptions''', 2024. The material analysed by Voudrin and colleagues for vowel–consonant structure; published as vector tracings in their paper.
* '''[[Zagi Tablets]]''', 2024. One hundred and four sentences on four clay tablets, headed in Akkadian ''imri Zagi-ak'', analysed by [[Inrik Üksküla]] and, on the blog ''[[Klema Field Notes]]'', by [[Marie Roelandt]].

Whether these texts share a single origin is not established. They share a sign inventory, the divider, and the same broad clause architecture; the Zagi Tablets add a cuneiform rendering and an Akkadian heading that the others lack.

No physical object has been securely tied to any of them. The [[Yedoma Ledger]], a mammoth-ivory plaque with ruled incised registers recovered from Siberian permafrost in 2021, has been proposed informally as the carrier of the longer companion inscription, on grounds of chronology and register geometry rather than of any published sign comparison; neither its excavator nor Kristiansen has endorsed the identification.

== Reception ==
The system's chief virtue is that it commits its users to nothing. Rubergskier's arithmetic reading, Voudrin's phonological partition and Roelandt's genealogical reading all operate on the same codes and can be compared token for token, which would be impossible had each study adopted its own transliteration. Roelandt's working transliteration into Latin letters is explicitly a readability aid layered on top of the codes, not a replacement for them.

Critics note that the neutrality is also a limitation: the codes freeze Kristiansen's initial segmentation of the signs, and any sign he merged or split in 2023 is merged or split in every later study. Kristiansen himself has issued only minor corrections since, describing his role as “keeping the inventory honest.”

== See also ==
* [[Jan-Tage Kristiansen]]
* [[Scapula Glyph Inscription]]
* [[Dozenal Primer Inscription]]
* [[Zagi Tablets]]
* [[Language Codes]]
* [[Klema Field Notes]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Writing systems]]
[[Category:Epigraphy]]

Yedoma Ledger

2026-09-22T11:03:33Z

Mvuijlst: Add section on the possible relation to the Kristiansen corpus; link the coding-system hub

{{Infobox
| name = Yedoma Ledger
| image = Yenoma Ledger.jpg
| caption = Plaque with incised geometric registers
| 1 Material = [[Ivory|Mammoth ivory]] (''[[Woolly mammoth|Mammuthus primigenius]]'')
| 2 Writing = Geometric incisions
| 3 Created = Substrate plausibly Last Interglacial (~125 ka); age of carving undetermined
| 4 Discovered_place = Lower [[Indigirka River|Indigirka]] basin, northeast [[Siberia]] (Russia)
| 5 Discovered_date = Late August (year per preliminary report)
| 6 Present_location = Regional heritage authority
| 7 Dimensions = ~216 × 54 × 39 mm; ~486 g
}}

The '''Yedoma Ledger''' is a worked plaque of mammoth ivory reportedly recovered from [[permafrost]] in the lower Indigirka region of northeast Siberia. The object was discovered and handled in the field by a small team led by [[J. Levi Schültke]] during a rapid-impact survey of thaw gullies commissioned to document erosion threats to organic artefacts; Schültke’s group was engaged for its prior experience with cold-chain recovery and identification of proboscidean ivory.<ref name="Schueltke2021">J. Levi Schültke, ''A Mammoth-Ivory Plaque with Geometric Incisions from Northeast Siberia: Discovery, Context, and Materials Analysis'' (preliminary field and materials report, Seminar für Archäologie der Periglazialzonen, 2021).</ref> Its carved surface shows parallel bands of straight and oblique incisions, including chevrons and cross-hatching. The preliminary report describes controlled cold-chain recovery and non-destructive documentation but does not advance a cultural attribution or secure the age of the carving itself.<ref name="Schueltke2021" />

== Discovery and context ==
According to the report, the plaque was noticed by the team in a thaw gully within ice-rich loess ([[Yedoma]]) and recovered with surrounding sediment using bagged blocks and refrigerated transport overseen by the regional heritage authority.<ref name="Schueltke2021" /> Yedoma sequences in Siberia are known to preserve Late Pleistocene faunal remains and organic materials that can be reworked by [[thermokarst]] processes, complicating archaeological context.<ref name="Schirrmeister2022">Lutz Schirrmeister, “Yedoma Permafrost Landscapes as Past Archives and Future Change Hotspots,” ''Frontiers in Earth Science'' 10 (2022): 929873, [https://doi.org/10.3389/feart.2022.929873](https://doi.org/10.3389/feart.2022.929873).</ref>

== Description ==
The object follows the natural camber of tusk ivory and presents a prepared, flatter face with multiple incised registers bounded by guide lines. Identification as mammoth ivory is supported by observation of [[Schreger lines]], a standard criterion in proboscidean ivory analysis.<ref name="CITES2020">“Identification Guide for Ivory and Ivory Substitutes,” CITES (2020), [https://cites.org/sites/default/files/ID_Manuals/Identification_Guide_for_Ivory_and_Ivory_Substitutes_ENGLISH.pdf](https://cites.org/sites/default/files/ID_Manuals/Identification_Guide_for_Ivory_and_Ivory_Substitutes_ENGLISH.pdf).</ref>

== Dating ==
Screening methods reported include FTIR for collagen/mineral preservation, [[amino acid racemization]] (AAR) on a detached lamella, and [[optically stimulated luminescence]] (OSL) on associated sediment. These results are consistent with an ancient Pleistocene substrate but do not directly date the carving. Open-system behavior in bones and dentine limits the reliability of some radiometric approaches; targeted dating of incision surfaces has not yet been published.<ref name="Schueltke2021" /><ref name="Penkman2022">K. Penkman, “Dating the Paleolithic: trapped charge and amino acid geochronology,” ''Evolutionary Anthropology'' 31, no. 5 (2022): 203–222, [https://doi.org/10.1002/evan.21958](https://doi.org/10.1002/evan.21958).</ref><ref name="Lian2006">O. B. Lian, “Dating the Quaternary: progress in luminescence dating,” ''Quaternary Science Reviews'' 25, nos. 19–20 (2006): 2449–2468, [https://doi.org/10.1016/j.quascirev.2005.11.013](https://doi.org/10.1016/j.quascirev.2005.11.013).</ref>

== Interpretation ==
Published descriptions remain neutral and descriptive; no consensus interpretation (notation, decoration, or other function) has been advanced. Pending secure dating and replication studies, the Yedoma Ledger is cited as a candidate example of worked ivory from permafrost context rather than as evidence for a particular symbolic system.<ref name="Schueltke2021" />

== Possible relation to the Kristiansen corpus ==
Since 2024 the Ledger has been discussed, so far only informally, as a candidate physical carrier for material in the [[Kristiansen coding system]]. The suggestion rests on three observations rather than on any direct comparison of signs.

First, chronology. Schültke's preliminary report, which circulated in 2021, describes the incised face as a series of registers bounded by guide lines but publishes only one photograph and no tracing. [[Jan-Tage Kristiansen]]'s 2023 correspondence note and his longer working paper were based on drawings and a transcription received by anonymous email in the two years that followed, with no indication of the object drawn.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

Second, geometry. The scapula inscription (KS-01) is a short abecedary and cannot be the Ledger, whose registers run the full 216 mm of the prepared face. Kristiansen's ''longer companion inscription'', however, was supplied as a transcription only: six lines, 146 tokens, medium unstated. At the roughly one-centimetre sign pitch reported for the scapula, a 216 mm register holds about twenty signs, which is in keeping with a six-line text averaging some twenty-four tokens a line. The stroke repertoire described by Schültke, straight and oblique cuts with chevrons and cross-hatching, is consistent with the Triangle, Barred-post and Comb families of the signary, though it is equally consistent with a great deal of Upper Palaeolithic ornament.

Third, the absence of any other candidate. The Ledger is the only object publicly documented from a controlled recovery whose incisions are organised in ruled registers of the kind the Kristiansen corpus presupposes.

None of this amounts to an identification. Schültke has not commented on the Kristiansen literature, and his report predates it. Kristiansen, asked whether the anonymous transcription could derive from the Ledger, replied that he had “no basis for saying so and no basis for denying it,” and that the question would be settled by a full-resolution tracing of the Ledger's registers, which the regional heritage authority has not released.<ref name="Kristiansen2023h" /> Until such a tracing exists the Ledger remains, in the words of its own preliminary report, a candidate example of worked ivory from permafrost context, and the Kristiansen corpus remains a set of drawings without an object.

== Significance ==
The find highlights both the potential and the difficulties of researching artefacts emerging from rapidly changing permafrost landscapes. It has been noted in discussions of best practice for recovery, minimal-intervention conservation (e.g. reversible consolidants), and multi-modal imaging such as [[reflectance transformation imaging]] in Arctic and sub-Arctic contexts.<ref name="Schueltke2021" /><ref name="HE2016">Historic England, ''Multi-Light Imaging for Heritage Applications (incl. H-RTI)'' (2016), [https://historicengland.org.uk/images-books/publications/multi-light-imaging-heritage-applications/](https://historicengland.org.uk/images-books/publications/multi-light-imaging-heritage-applications/).</ref>

== See also ==

* [[Kristiansen coding system]]
* [[Scapula Glyph Inscription]]
* [[Yedoma]]
* [[Woolly mammoth]]
* [[Pleistocene archaeology]]
* [[Reflectance transformation imaging]]

== References ==
{{reflist}}

[[Category:Klema]]

File:Dozenal successor schema.png

2026-09-22T11:00:05Z

Mvuijlst: Mvuijlst uploaded a new version of File:Dozenal successor schema.png

The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.

Kristiansen corpus

2026-09-22T10:29:54Z

Mvuijlst: Redirect to the hub article Kristiansen coding system

#REDIRECT [[Kristiansen coding system]]

Kristiansen coding system

2026-09-22T10:29:51Z

Mvuijlst: Create hub article: principles, conventions, full signary, distributional classes, corpus, reception

The '''Kristiansen coding system''' is the alphanumeric notation used in the scholarly literature to transcribe the geometric signs of the [[Scapula Glyph Inscription]] and the other texts that share its sign repertory, collectively referred to as the '''Kristiansen corpus'''. Each sign receives a family letter and a two-digit index (for example C01, B04, P01). The system was introduced by [[Jan-Tage Kristiansen]] in a 2023 correspondence note and has since been adopted without modification by every subsequent study.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

The codes are deliberately neutral. They record what a sign looks like and how it is built, not what it might mean or sound like. No phonetic values have been proposed in the literature, and the mnemonic names attached to the codes (BOX-DOT, TEE-LEFT, and so on) are descriptive labels only.

== Principles ==
Kristiansen's note set out three rules that later work has kept:
* '''One code per sign.''' Every distinct grapheme in the inventory receives one code; no code is assigned to a sequence.
* '''Family letter plus index.''' The letter names one of eight visually coherent families, identified by shared construction (a corner, a closed box, a triangle, and so on). The index numbers the members of a family in the order they appear on the scapula. A ninth letter, P, is reserved for the single divider sign.
* '''Rotation and diacritics are features, not new families.''' Signs that differ only by rotation or by an added dot, bar or diagonal tick stay within their family and are distinguished by index. Kristiansen's original signary carried a rotation column; later work by [[Camille Voudrin]] and colleagues treated rotation as a non-contrastive convenience and canonicalised signs rotation-agnostically, with no effect on the inventory.

== Transcription conventions ==
* Signs within a word are joined by hyphens: <code>C01-M03-S01-C02</code>. Words are separated by spaces.
* The divider '''P01''' is transcribed as a sign in its own right. In the [[Dozenal Primer Inscription]] and the [[Zagi Tablets]] it occurs only at clause ends and is written bound to the last word of the clause (<code>…-T03-P01</code>).
* Sentences in the longer corpora are numbered by document and position, for example <code>F3_44</code> for the forty-fourth sentence in Document 3 of the Zagi Tablets. This numbering originates with [[Inrik Üksküla]]'s preprint and is used by [[Marie Roelandt]].
* Uncertain or damaged signs are written <code>??</code> in place of a code.

== The signary ==
The unified signary contains 31 signs in eight families plus the divider, 32 codes in all. Every one of them is attested once on the scapula (KS-01), which presents the families as an ordered sweep and so fixes the index order.<ref name="Kristiansen2023h" /> Rotation and feature descriptions follow Kristiansen's catalogue.

{| class="wikitable" style="font-size:95%;"
! scope="col" | Code !! scope="col" | Glyph !! scope="col" | Mnemonic !! scope="col" | Rotation !! scope="col" | Distinguishing features
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Corner family (C), 7 signs
|-
| C01 || [[File:C01.svg|24px|alt=C01|link=]] || CORNER-NW || rot0 || shape=right-angle, open=NE, marks=none
|-
| C02 || [[File:C02.svg|24px|alt=C02|link=]] || CORNER-SE || rot180 || shape=right-angle, open=SE, marks=none
|-
| C03 || [[File:C03.svg|24px|alt=C03|link=]] || CORNER-SE-DOT || rot180 || shape=right-angle, open=SE, dot=centerline
|-
| C04 || [[File:C04.svg|24px|alt=C04|link=]] || CORNER-NW-DIAG || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE
|-
| C05 || [[File:C05.svg|24px|alt=C05|link=]] || CORNER-SE-DIAG || rot180 || shape=right-angle, open=SE, tick=diagonal, axis=NW-SE
|-
| C06 || [[File:C06.svg|24px|alt=C06|link=]] || CORNER-NW-DIAG-DOT || rot0 || shape=right-angle, open=NE, tick=diagonal, axis=NW-SE, dot=centerline
|-
| C07 || [[File:C07.svg|24px|alt=C07|link=]] || CORNER-SE-DIAG-DOT || rot180 || shape=right-angle, open=SE, notch=orthogonal, depth=short, dot=centerline
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Box family (B), 5 signs
|-
| B01 || [[File:B01.svg|24px|alt=B01|link=]] || BOX || rot0 || outline=square, interior=clear
|-
| B02 || [[File:B02.svg|24px|alt=B02|link=]] || BOX-DOT || rot0 || outline=square, dot=center
|-
| B03 || [[File:B03.svg|24px|alt=B03|link=]] || BOX-TICK || rot0 || outline=square, notch=orthogonal, wall=top, depth=short
|-
| B04 || [[File:B04.svg|24px|alt=B04|link=]] || BOX-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE
|-
| B05 || [[File:B05.svg|24px|alt=B05|link=]] || BOX-DOT-DIAG-SW-NE || rot0 || outline=square, tick=diagonal, entry=SW-NE, dot=corner_NE
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Triangle family (A), 5 signs
|-
| A01 || [[File:A01.svg|24px|alt=A01|link=]] || TRI-OPEN || rot0 || closure=open, apex=up
|-
| A02 || [[File:A02.svg|24px|alt=A02|link=]] || TRI-BAR || rot180 || closure=open, apex=down, bar=1, position=mid
|-
| A03 || [[File:A03.svg|24px|alt=A03|link=]] || TRI-DOT || rot180 || closure=open, apex=down, bar=1, position=mid, dot=center
|-
| A04 || [[File:A04.svg|24px|alt=A04|link=]] || TRI-VEE || rot180 || closure=open, apex=down, vee=1, orientation=apex-base
|-
| A05 || [[File:A05.svg|24px|alt=A05|link=]] || TRI-CLOSED-BAR || rot0 || closure=closed, apex=up, bar=1, position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Line family (L), 2 signs
|-
| L01 || [[File:L01.svg|24px|alt=L01|link=]] || LINE-VERT || rot0 || orientation=vertical, length=cell
|-
| L02 || [[File:L02.svg|24px|alt=L02|link=]] || LINE-HOR || rot90 || orientation=horizontal, length=cell
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Tee family (T), 3 signs
|-
| T01 || [[File:T01.svg|24px|alt=T01|link=]] || TEE-UP || rot0 || stem=vertical, bar=top
|-
| T02 || [[File:T02.svg|24px|alt=T02|link=]] || TEE-LEFT || rot90 || stem=horizontal, bar=left
|-
| T03 || [[File:T03.svg|24px|alt=T03|link=]] || UPSIDE-DOWN-TEE || rot180 || stem=vertical, bar=bottom
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Comb family (M), 3 signs
|-
| M01 || [[File:M01.svg|24px|alt=M01|link=]] || COMB-2-N || rot0 || tines=2, stem=vertical, tines_side=left/top
|-
| M02 || [[File:M02.svg|24px|alt=M02|link=]] || COMB-2-W || rot0 || tines=2, stem=vertical, tines_side=left
|-
| M03 || [[File:M03.svg|24px|alt=M03|link=]] || COMB-3-E || rot0 || tines=3, stem=vertical, tines_side=right
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Meander family (S), 3 signs
|-
| S01 || [[File:S01.svg|24px|alt=S01|link=]] || MEANDER-2 || rot0 || elements=2, hollow=false
|-
| S02 || [[File:S02.svg|24px|alt=S02|link=]] || MEANDER-2-HOLLOW || rot0 || elements=2, hollow=true
|-
| S03 || [[File:S03.svg|24px|alt=S03|link=]] || MEANDER-3 || rot0 || elements=3, hollow=false
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Barred-post family (H), 3 signs
|-
| H01 || [[File:H01.svg|24px|alt=H01|link=]] || DOUBLE-POST-CONNECTED || rot0 || posts=2, parallel, connector=base, bars=0
|-
| H02 || [[File:H02.svg|24px|alt=H02|link=]] || POST-DOUBLE-BAR || rot0 || posts=1, bars=2, bar_style=cross, bar_positions=mid, upper
|-
| H03 || [[File:H03.svg|24px|alt=H03|link=]] || DOUBLE-POST-BAR || rot0 || posts=2, parallel, bars=1, bridging=true, bar_position=mid
|-
! colspan="5" style="text-align:left; background:#f2f2f2;" | Punct family (P), 1 sign
|-
| P01 || [[File:P01.svg|24px|alt=P01|link=]] || SLASH || rot30 || punct=slash, function=separator
|}

== Distributional classes ==
Working only from sign distributions in three longer inscriptions, Voudrin, Marchand and Leclerc (2024) found that the inventory partitions almost deterministically into two classes with the behaviour expected of consonants and vowels. The consonant-like class comprises the Corner, Box, Triangle and Comb families; the vowel-like class comprises the Tee, Line, Meander and Barred-post families. No family was split between the two classes.<ref name="Voudrin2024">Camille Voudrin, Solène Marchand, and Hadrien Leclerc, “A distributional test of vowel–consonant structure in an undeciphered signary suggests robust class separation,” ''[[Language Codes]]'' 7 (2024): 1281–1294.</ref> The authors stress that this is a structural result and not a decipherment.

== The corpus ==
Texts transcribed in the system, in order of publication:
* '''[[Scapula Glyph Inscription]]''' (KS-01), 2023. Four ruled lines on a scapula-shaped object; the abecedary-like presentation from which the signary was compiled.
* '''A longer companion inscription''', 2023. Six lines and 146 tokens supplied as a transcription, analysed statistically in Kristiansen's longer working paper.
* '''[[Dozenal Primer Inscription]]''', 2024. Forty-five clauses read by [[Ginevra Rubergskier]] as a primer for base-12 arithmetic.
* '''Three extended inscriptions''', 2024. The material analysed by Voudrin and colleagues for vowel–consonant structure; published as vector tracings in their paper.
* '''[[Zagi Tablets]]''', 2024. One hundred and four sentences on four clay tablets, headed in Akkadian ''imri Zagi-ak'', analysed by [[Inrik Üksküla]] and, on the blog ''[[Klema Field Notes]]'', by [[Marie Roelandt]].

Whether these texts share a single origin is not established. They share a sign inventory, the divider, and the same broad clause architecture; the Zagi Tablets add a cuneiform rendering and an Akkadian heading that the others lack.

== Reception ==
The system's chief virtue is that it commits its users to nothing. Rubergskier's arithmetic reading, Voudrin's phonological partition and Roelandt's genealogical reading all operate on the same codes and can be compared token for token, which would be impossible had each study adopted its own transliteration. Roelandt's working transliteration into Latin letters is explicitly a readability aid layered on top of the codes, not a replacement for them.

Critics note that the neutrality is also a limitation: the codes freeze Kristiansen's initial segmentation of the signs, and any sign he merged or split in 2023 is merged or split in every later study. Kristiansen himself has issued only minor corrections since, describing his role as “keeping the inventory honest.”

== See also ==
* [[Jan-Tage Kristiansen]]
* [[Scapula Glyph Inscription]]
* [[Dozenal Primer Inscription]]
* [[Zagi Tablets]]
* [[Language Codes]]
* [[Klema Field Notes]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Writing systems]]
[[Category:Epigraphy]]

Dozenal Primer Inscription

2026-09-22T10:27:17Z

Mvuijlst: Regenerate glyph frequency table from current transcription (45 clauses, 838 tokens, 28 types; adds B05 and L02)

[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref>

The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

== Overview ==
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" />

The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.

== Glyph inventory and distribution ==

A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription (45 clauses, 838 sign tokens, 28 sign types); positions are counted within words, with the clause-final divider P01 treated as bound to the preceding word. Code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:center;"
|-
! scope="col" | Code
! scope="col" | Glyph
! scope="col" | Name
! scope="col" | Freq
! scope="col" | Init
! scope="col" | Med
! scope="col" | Final
|-
| A01
| [[File:A01.svg|24px|alt=A01|link=]]
| style="text-align:left;" | TRI-OPEN
| 15 || 11 || 4 || –
|-
| A02
| [[File:A02.svg|24px|alt=A02|link=]]
| style="text-align:left;" | TRI-BAR
| 29 || 29 || – || –
|-
| A03
| [[File:A03.svg|24px|alt=A03|link=]]
| style="text-align:left;" | TRI-DOT
| 6 || – || 6 || –
|-
| A05
| [[File:A05.svg|24px|alt=A05|link=]]
| style="text-align:left;" | TRI-CLOSED-BAR
| 4 || – || 4 || –
|-
| B01
| [[File:B01.svg|24px|alt=B01|link=]]
| style="text-align:left;" | BOX
| 17 || 6 || 8 || 3
|-
| B02
| [[File:B02.svg|24px|alt=B02|link=]]
| style="text-align:left;" | BOX-DOT
| 8 || 6 || 2 || –
|-
| B04
| [[File:B04.svg|24px|alt=B04|link=]]
| style="text-align:left;" | BOX-DIAG-SW-NE
| 36 || – || 15 || 21
|-
| B05
| [[File:B05.svg|24px|alt=B05|link=]]
| style="text-align:left;" | BOX-DOT-DIAG-SW-NE
| 3 || – || 3 || –
|-
| C01
| [[File:C01.svg|24px|alt=C01|link=]]
| style="text-align:left;" | CORNER-NW
| 109 || 50 || 29 || 30
|-
| C02
| [[File:C02.svg|24px|alt=C02|link=]]
| style="text-align:left;" | CORNER-SE
| 39 || 39 || – || –
|-
| C03
| [[File:C03.svg|24px|alt=C03|link=]]
| style="text-align:left;" | CORNER-SE-DOT
| 43 || 1 || 42 || –
|-
| C04
| [[File:C04.svg|24px|alt=C04|link=]]
| style="text-align:left;" | CORNER-NW-DIAG
| 3 || 2 || 1 || –
|-
| C05
| [[File:C05.svg|24px|alt=C05|link=]]
| style="text-align:left;" | CORNER-SE-DIAG
| 32 || 32 || – || –
|-
| C06
| [[File:C06.svg|24px|alt=C06|link=]]
| style="text-align:left;" | CORNER-NW-DIAG-DOT
| 4 || – || 4 || –
|-
| H01
| [[File:H01.svg|24px|alt=H01|link=]]
| style="text-align:left;" | DOUBLE-POST-CONNECTED
| 20 || – || 20 || –
|-
| H02
| [[File:H02.svg|24px|alt=H02|link=]]
| style="text-align:left;" | POST-DOUBLE-BAR
| 40 || – || 38 || 2
|-
| H03
| [[File:H03.svg|24px|alt=H03|link=]]
| style="text-align:left;" | DOUBLE-POST-BAR
| 30 || – || 30 || –
|-
| L01
| [[File:L01.svg|24px|alt=L01|link=]]
| style="text-align:left;" | LINE-VERT
| 45 || – || 12 || 33
|-
| L02
| [[File:L02.svg|24px|alt=L02|link=]]
| style="text-align:left;" | LINE-HOR
| 34 || – || 26 || 8
|-
| M01
| [[File:M01.svg|24px|alt=M01|link=]]
| style="text-align:left;" | COMB-2-N
| 18 || 4 || 13 || 1
|-
| M02
| [[File:M02.svg|24px|alt=M02|link=]]
| style="text-align:left;" | COMB-2-W
| 67 || – || 67 || –
|-
| M03
| [[File:M03.svg|24px|alt=M03|link=]]
| style="text-align:left;" | COMB-3-E
| 62 || – || 60 || 2
|-
| P01
| [[File:P01.svg|24px|alt=P01|link=]]
| style="text-align:left;" | SLASH
| 45 || – || – || 45
|-
| S02
| [[File:S02.svg|24px|alt=S02|link=]]
| style="text-align:left;" | MEANDER-2-HOLLOW
| 12 || – || 6 || 6
|-
| S03
| [[File:S03.svg|24px|alt=S03|link=]]
| style="text-align:left;" | MEANDER-3
| 48 || – || 45 || 3
|-
| T01
| [[File:T01.svg|24px|alt=T01|link=]]
| style="text-align:left;" | TEE-UP
| 11 || – || 9 || 2
|-
| T02
| [[File:T02.svg|24px|alt=T02|link=]]
| style="text-align:left;" | TEE-LEFT
| 9 || – || 6 || 3
|-
| T03
| [[File:T03.svg|24px|alt=T03|link=]]
| style="text-align:left;" | UPSIDE-DOWN-TEE
| 49 || – || 28 || 21

|}

== Proposed numeric forms and functional sequences ==

Codes follow Kristiansen’s signary. Values are glosses for exposition only.<ref name="Rubergskier2024" />. Coding scheme per Kristiansen.<ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:left;"
|-
! scope="col" | Function (gloss)
! scope="col" | Codes (Kristiansen)
! scope="col" | Glyph sequence (icons)
! scope="col" | Notes
|-
| ZERO
| <code>B02-M03-L01-B05-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:B05.svg|20px|alt=B05|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| ONE
| <code>C01-S03-C03-T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| TWO
| <code>C02-M02-H01-M01-T01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T01.svg|20px|alt=T01|link=]]
|
|-
| THREE
| <code>B01-M02-L02-A03-H02</code>
| [[File:B01.svg|20px|alt=B01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L02.svg|20px|alt=L02|link=]][[File:A03.svg|20px|alt=A03|link=]][[File:H02.svg|20px|alt=H02|link=]]
|
|-
| FOUR
| <code>C05-M03-S02-C06-T02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S02.svg|20px|alt=S02|link=]][[File:C06.svg|20px|alt=C06|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| FIVE
| <code>C01-M03-T02</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| SIX
| <code>C05-B04-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:B04.svg|20px|alt=B04|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| SEVEN
| <code>M01-L01-A01-T03</code>
| [[File:M01.svg|20px|alt=M01|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:A01.svg|20px|alt=A01|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| EIGHT
| <code>B02-M03-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| NINE
| <code>C05-M02-H02-A05-S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:A05.svg|20px|alt=A05|link=]][[File:S02.svg|20px|alt=S02|link=]]
|
|-
| TEN
| <code>C05-M01-L02-M02-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:L02.svg|20px|alt=L02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| ELEVEN
| <code>A01-H01-B01</code>
| [[File:A01.svg|20px|alt=A01|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:B01.svg|20px|alt=B01|link=]]
|
|-
| TWELVE (one dozen)
| <code>C01-S03-C03-T03-C01-M02-H02-B04</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]][[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Transparently ONE followed by the ×12 derivational bundle; no simplex sign sequence for twelve is attested in the inscription. Target of the complement sums 11+1, 10+2 and 6+6. <ref name="Rubergskier2024" />
|-
| '''EQUALS / clause spine'''
| <code>C02–M03–H03–C01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:H03.svg|20px|alt=H03|link=]][[File:C01.svg|20px|alt=C01|link=]]
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" />
|-
| '''PLUS (binary addition)'''
| <code>A02–L01</code>
| [[File:A02.svg|20px|alt=A02|link=]][[File:L01.svg|20px|alt=L01|link=]]
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" />
|-
| '''MINUS (subtraction)'''
| <code>C05–M02–S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:S02.svg|20px|alt=S02|link=]]
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" />
|-
| '''ONE (simplex unit)'''
| <code>C01–S03–C03–T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" />
|-
| '''PUNCTUATION (bound period)'''
| <code>P01</code> (final only)
| [[File:P01.svg|20px|alt=P01|link=]]
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" />
|-
| '''×12 derivation (“dozen”)'''
| –C01–M02–H02–B04 (right edge)
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" />
|}

== Scholarly discussion ==
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" />

== Nomenclature ==
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).

== Relation to the Scapula Glyph Inscription ==
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" />

== See also ==
* [[Duodecimal]]
* [[Numeral system]]
* [[Mathematical notation]]
* [[Undeciphered writing systems]]
* [[Epigraphy]]
* [[Paleography]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Klema]]

Dozenal Primer Inscription

2026-09-22T10:25:07Z

Mvuijlst: THREE and TEN: plain e is L02, not T02

[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref>

The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

== Overview ==
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" />

The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.

== Glyph inventory and distribution ==

A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:center;"
|-
! scope="col" | Code
! scope="col" | Glyph
! scope="col" | Name
! scope="col" | Freq
! scope="col" | Init
! scope="col" | Med
! scope="col" | Final
|-
| A01
| [[File:A01.svg|24px|alt=A01|link=]]
| style="text-align:left;" | TRI-OPEN
| 5 || 2 || 3 || –
|-
| A02
| [[File:A02.svg|24px|alt=A02|link=]]
| style="text-align:left;" | TRI-BAR
| 17 || 17 || – || –
|-
| A03
| [[File:A03.svg|24px|alt=A03|link=]]
| style="text-align:left;" | TRI-DOT
| 4 || – || 4 || –
|-
| A05
| [[File:A05.svg|24px|alt=A05|link=]]
| style="text-align:left;" | TRI-CLOSED-BAR
| 3 || – || 3 || –
|-
| B01
| [[File:B01.svg|24px|alt=B01|link=]]
| style="text-align:left;" | BOX
| 6 || 4 || 2 || –
|-
| B02
| [[File:B02.svg|24px|alt=B02|link=]]
| style="text-align:left;" | BOX-DOT
| 5 || 5 || – || –
|-
| B04
| [[File:B04.svg|24px|alt=B04|link=]]
| style="text-align:left;" | BOX-DIAG-SW-NE
| 5 || – || 3 || 2
|-
| C01
| [[File:C01.svg|24px|alt=C01|link=]]
| style="text-align:left;" | CORNER-NW
| 28 || 14 || – || 14
|-
| C02
| [[File:C02.svg|24px|alt=C02|link=]]
| style="text-align:left;" | CORNER-SE
| 27 || 27 || – || –
|-
| C03
| [[File:C03.svg|24px|alt=C03|link=]]
| style="text-align:left;" | CORNER-SE-DOT
| 6 || 1 || 5 || –
|-
| C04
| [[File:C04.svg|24px|alt=C04|link=]]
| style="text-align:left;" | CORNER-NW-DIAG
| 3 || – || 3 || –
|-
| C05
| [[File:C05.svg|24px|alt=C05|link=]]
| style="text-align:left;" | CORNER-SE-DIAG
| 16 || 16 || – || –
|-
| C06
| [[File:C06.svg|24px|alt=C06|link=]]
| style="text-align:left;" | CORNER-NW-DIAG-DOT
| 7 || – || 7 || –
|-
| H01
| [[File:H01.svg|24px|alt=H01|link=]]
| style="text-align:left;" | DOUBLE-POST-CONNECTED
| 15 || – || 15 || –
|-
| H02
| [[File:H02.svg|24px|alt=H02|link=]]
| style="text-align:left;" | POST-DOUBLE-BAR
| 8 || – || 6 || 2
|-
| H03
| [[File:H03.svg|24px|alt=H03|link=]]
| style="text-align:left;" | DOUBLE-POST-BAR
| 14 || – || 14 || –
|-
| L01
| [[File:L01.svg|24px|alt=L01|link=]]
| style="text-align:left;" | LINE-VERT
| 24 || – || 8 || 16
|-
| M01
| [[File:M01.svg|24px|alt=M01|link=]]
| style="text-align:left;" | COMB-2-N
| 20 || 3 || 16 || 1
|-
| M02
| [[File:M02.svg|24px|alt=M02|link=]]
| style="text-align:left;" | COMB-2-W
| 52 || – || 52 || –
|-
| M03
| [[File:M03.svg|24px|alt=M03|link=]]
| style="text-align:left;" | COMB-3-E
| 40 || – || 40 || –
|-
| P01
| [[File:P01.svg|24px|alt=P01|link=]]
| style="text-align:left;" | SLASH
| 25 || – || – || 25
|-
| S02
| [[File:S02.svg|24px|alt=S02|link=]]
| style="text-align:left;" | MEANDER-2-HOLLOW
| 9 || – || 3 || 6
|-
| S03
| [[File:S03.svg|24px|alt=S03|link=]]
| style="text-align:left;" | MEANDER-3
| 39 || – || 37 || 2
|-
| T01
| [[File:T01.svg|24px|alt=T01|link=]]
| style="text-align:left;" | TEE-UP
| 7 || – || 4 || 3
|-
| T02
| [[File:T02.svg|24px|alt=T02|link=]]
| style="text-align:left;" | TEE-LEFT
| 30 || – || 23 || 7
|-
| T03
| [[File:T03.svg|24px|alt=T03|link=]]
| style="text-align:left;" | UPSIDE-DOWN-TEE
| 38 || – || 19 || 19

|}

== Proposed numeric forms and functional sequences ==

Codes follow Kristiansen’s signary. Values are glosses for exposition only.<ref name="Rubergskier2024" />. Coding scheme per Kristiansen.<ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:left;"
|-
! scope="col" | Function (gloss)
! scope="col" | Codes (Kristiansen)
! scope="col" | Glyph sequence (icons)
! scope="col" | Notes
|-
| ZERO
| <code>B02-M03-L01-B05-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:B05.svg|20px|alt=B05|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| ONE
| <code>C01-S03-C03-T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| TWO
| <code>C02-M02-H01-M01-T01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T01.svg|20px|alt=T01|link=]]
|
|-
| THREE
| <code>B01-M02-L02-A03-H02</code>
| [[File:B01.svg|20px|alt=B01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L02.svg|20px|alt=L02|link=]][[File:A03.svg|20px|alt=A03|link=]][[File:H02.svg|20px|alt=H02|link=]]
|
|-
| FOUR
| <code>C05-M03-S02-C06-T02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S02.svg|20px|alt=S02|link=]][[File:C06.svg|20px|alt=C06|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| FIVE
| <code>C01-M03-T02</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| SIX
| <code>C05-B04-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:B04.svg|20px|alt=B04|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| SEVEN
| <code>M01-L01-A01-T03</code>
| [[File:M01.svg|20px|alt=M01|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:A01.svg|20px|alt=A01|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| EIGHT
| <code>B02-M03-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| NINE
| <code>C05-M02-H02-A05-S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:A05.svg|20px|alt=A05|link=]][[File:S02.svg|20px|alt=S02|link=]]
|
|-
| TEN
| <code>C05-M01-L02-M02-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:L02.svg|20px|alt=L02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| ELEVEN
| <code>A01-H01-B01</code>
| [[File:A01.svg|20px|alt=A01|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:B01.svg|20px|alt=B01|link=]]
|
|-
| TWELVE (one dozen)
| <code>C01-S03-C03-T03-C01-M02-H02-B04</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]][[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Transparently ONE followed by the ×12 derivational bundle; no simplex sign sequence for twelve is attested in the inscription. Target of the complement sums 11+1, 10+2 and 6+6. <ref name="Rubergskier2024" />
|-
| '''EQUALS / clause spine'''
| <code>C02–M03–H03–C01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:H03.svg|20px|alt=H03|link=]][[File:C01.svg|20px|alt=C01|link=]]
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" />
|-
| '''PLUS (binary addition)'''
| <code>A02–L01</code>
| [[File:A02.svg|20px|alt=A02|link=]][[File:L01.svg|20px|alt=L01|link=]]
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" />
|-
| '''MINUS (subtraction)'''
| <code>C05–M02–S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:S02.svg|20px|alt=S02|link=]]
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" />
|-
| '''ONE (simplex unit)'''
| <code>C01–S03–C03–T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" />
|-
| '''PUNCTUATION (bound period)'''
| <code>P01</code> (final only)
| [[File:P01.svg|20px|alt=P01|link=]]
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" />
|-
| '''×12 derivation (“dozen”)'''
| –C01–M02–H02–B04 (right edge)
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" />
|}

== Scholarly discussion ==
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" />

== Nomenclature ==
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).

== Relation to the Scapula Glyph Inscription ==
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" />

== See also ==
* [[Duodecimal]]
* [[Numeral system]]
* [[Mathematical notation]]
* [[Undeciphered writing systems]]
* [[Epigraphy]]
* [[Paleography]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Klema]]

Dozenal Primer Inscription

2026-09-22T10:23:35Z

Mvuijlst: TWELVE row: show attested kodaklef (ONE + x12 bundle) instead of bare suffix

[[File:Dozenal successor schema.png|thumb|The four examples render the successor chain 1→2, 2→3, 3→4, 4→5, demonstrating that adding the simplex unit “ONE” advances X to its next value while preserving clause structure. Codes follow Kristiansen’s signary; glyph labels (“ONE”, “TWO”, …) are semantic glosses for expository clarity and do not assume phonetic values.]]
The '''Dozenal Primer Inscription''' is the working name for a long geometric-glyph text proposed to encode a compact [[Duodecimal|dozenal]] (base-12) arithmetic register. The inscription is transcribed with a neutral code of sign classes (for example A01, B04, C03 and a slash-like divider P01) that mirrors the notation first used to document the shorter [[Scapula Glyph Inscription]] (KS-01). In 2024, a study argued from distributional evidence—rather than from phonetic values or a bilingual—that the text exhibits an equation-like clause structure with bound punctuation, a stereotyped medial “equals” spine, operator clusters, and a productive ×12 derivational suffix. On that account, the inscription functions as a brief primer for base-12 arithmetic, extending to compounds traditionally glossed as ''dozen'' (12×), ''gross'' (12²) and a tentative ''greatgross'' (12³).<ref name="Rubergskier2024">Ginevra Rubergskier, “A dozenal primer hidden in plain sight: decoding arithmetic from a corpus of tagged tokens,” ''Language Codes'' 6 (2024): 820–824.</ref>

The sign code used to publish the Dozenal Primer Inscription derives from earlier internal documentation of KS-01, which described short ruled lines, rectilinear glyphs built from a limited set of straight strokes, and visually coherent families (corners, boxes, triangles, barred posts) separated by a consistent slash divider. That memorandum cautioned that widely circulated images likely trace back to a single original drawing, and it advocated raking-light or RTI imaging before firm claims about medium, date or technique.<ref name="Kristiansen2023h">Jan-Tage Kristiansen, “Twin renderings, single template: a ruled signary on a putative cervid scapula,” correspondence note, ''language'' 27 (October 2023): 1073–1074.</ref>

== Overview ==
The Dozenal Primer Inscription is published only as a transcription in the Kristiansen coding scheme and as line drawings; no phonetic values or language affiliation are claimed in the 2024 analysis. Instead, the argument proceeds by methods common in [[Corpus linguistics]] and quantitative [[Epigraphy]]: (1) positional bias over initial/medial/final slots; (2) bigram inventories and pointwise mutual information to find unusually tight collocations; and (3) tests for morphological productivity at the right edge of clauses. In this model, the slash P01 behaves as bound punctuation confined to clause ends; an invariant 4-sign sequence occupies the medial spine and functions like an equals sign; a compact cluster acts as a binary addition operator; and a fixed four-sign bundle at the right edge derives “×12” forms. Complement constructions such as “11+1,” “10+2,” and “6+6” converge on the same dozen-marked targets, diagnosing 12 as the privileged base. A small number of clauses are read as scaling the same patterns to 12² and, by extension, to 12³.<ref name="Rubergskier2024" />

The approach is intentionally agnostic about [[Language identification]] and about whether the glyphs are ultimately [[Logogram|logographic]], [[Syllabary|syllabic]] or something else. The claim is structural: that a small and rigid clause template—bound final punctuation, a fixed medial spine, operator clusters with narrow distribution, and a selective right-edge derivation—fits a didactic number register more parsimoniously than it fits a segmental writing system without additional evidence.<ref name="Rubergskier2024" /> Proponents note that such “equation-like” formatting is well attested in practice texts and primers across historical [[Numeral system]]s, whereas critics point out that non-linguistic genres (lists, catalogues, tallies) can sometimes mimic grammatical structure.

== Glyph inventory and distribution ==

A compact distribution over the transcribed sign set (Kristiansen codes) is given below. Counts refer to the Dozenal Primer Inscription as published in line drawings/transcription; code labels are descriptive only and do not imply phonetic values.<ref name="Rubergskier2024" /><ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:center;"
|-
! scope="col" | Code
! scope="col" | Glyph
! scope="col" | Name
! scope="col" | Freq
! scope="col" | Init
! scope="col" | Med
! scope="col" | Final
|-
| A01
| [[File:A01.svg|24px|alt=A01|link=]]
| style="text-align:left;" | TRI-OPEN
| 5 || 2 || 3 || –
|-
| A02
| [[File:A02.svg|24px|alt=A02|link=]]
| style="text-align:left;" | TRI-BAR
| 17 || 17 || – || –
|-
| A03
| [[File:A03.svg|24px|alt=A03|link=]]
| style="text-align:left;" | TRI-DOT
| 4 || – || 4 || –
|-
| A05
| [[File:A05.svg|24px|alt=A05|link=]]
| style="text-align:left;" | TRI-CLOSED-BAR
| 3 || – || 3 || –
|-
| B01
| [[File:B01.svg|24px|alt=B01|link=]]
| style="text-align:left;" | BOX
| 6 || 4 || 2 || –
|-
| B02
| [[File:B02.svg|24px|alt=B02|link=]]
| style="text-align:left;" | BOX-DOT
| 5 || 5 || – || –
|-
| B04
| [[File:B04.svg|24px|alt=B04|link=]]
| style="text-align:left;" | BOX-DIAG-SW-NE
| 5 || – || 3 || 2
|-
| C01
| [[File:C01.svg|24px|alt=C01|link=]]
| style="text-align:left;" | CORNER-NW
| 28 || 14 || – || 14
|-
| C02
| [[File:C02.svg|24px|alt=C02|link=]]
| style="text-align:left;" | CORNER-SE
| 27 || 27 || – || –
|-
| C03
| [[File:C03.svg|24px|alt=C03|link=]]
| style="text-align:left;" | CORNER-SE-DOT
| 6 || 1 || 5 || –
|-
| C04
| [[File:C04.svg|24px|alt=C04|link=]]
| style="text-align:left;" | CORNER-NW-DIAG
| 3 || – || 3 || –
|-
| C05
| [[File:C05.svg|24px|alt=C05|link=]]
| style="text-align:left;" | CORNER-SE-DIAG
| 16 || 16 || – || –
|-
| C06
| [[File:C06.svg|24px|alt=C06|link=]]
| style="text-align:left;" | CORNER-NW-DIAG-DOT
| 7 || – || 7 || –
|-
| H01
| [[File:H01.svg|24px|alt=H01|link=]]
| style="text-align:left;" | DOUBLE-POST-CONNECTED
| 15 || – || 15 || –
|-
| H02
| [[File:H02.svg|24px|alt=H02|link=]]
| style="text-align:left;" | POST-DOUBLE-BAR
| 8 || – || 6 || 2
|-
| H03
| [[File:H03.svg|24px|alt=H03|link=]]
| style="text-align:left;" | DOUBLE-POST-BAR
| 14 || – || 14 || –
|-
| L01
| [[File:L01.svg|24px|alt=L01|link=]]
| style="text-align:left;" | LINE-VERT
| 24 || – || 8 || 16
|-
| M01
| [[File:M01.svg|24px|alt=M01|link=]]
| style="text-align:left;" | COMB-2-N
| 20 || 3 || 16 || 1
|-
| M02
| [[File:M02.svg|24px|alt=M02|link=]]
| style="text-align:left;" | COMB-2-W
| 52 || – || 52 || –
|-
| M03
| [[File:M03.svg|24px|alt=M03|link=]]
| style="text-align:left;" | COMB-3-E
| 40 || – || 40 || –
|-
| P01
| [[File:P01.svg|24px|alt=P01|link=]]
| style="text-align:left;" | SLASH
| 25 || – || – || 25
|-
| S02
| [[File:S02.svg|24px|alt=S02|link=]]
| style="text-align:left;" | MEANDER-2-HOLLOW
| 9 || – || 3 || 6
|-
| S03
| [[File:S03.svg|24px|alt=S03|link=]]
| style="text-align:left;" | MEANDER-3
| 39 || – || 37 || 2
|-
| T01
| [[File:T01.svg|24px|alt=T01|link=]]
| style="text-align:left;" | TEE-UP
| 7 || – || 4 || 3
|-
| T02
| [[File:T02.svg|24px|alt=T02|link=]]
| style="text-align:left;" | TEE-LEFT
| 30 || – || 23 || 7
|-
| T03
| [[File:T03.svg|24px|alt=T03|link=]]
| style="text-align:left;" | UPSIDE-DOWN-TEE
| 38 || – || 19 || 19

|}

== Proposed numeric forms and functional sequences ==

Codes follow Kristiansen’s signary. Values are glosses for exposition only.<ref name="Rubergskier2024" />. Coding scheme per Kristiansen.<ref name="Kristiansen2023h" />

{| class="wikitable plainlist" style="text-align:left;"
|-
! scope="col" | Function (gloss)
! scope="col" | Codes (Kristiansen)
! scope="col" | Glyph sequence (icons)
! scope="col" | Notes
|-
| ZERO
| <code>B02-M03-L01-B05-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:B05.svg|20px|alt=B05|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| ONE
| <code>C01-S03-C03-T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| TWO
| <code>C02-M02-H01-M01-T01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T01.svg|20px|alt=T01|link=]]
|
|-
| THREE
| <code>B01-M02-T02-A03-H02</code>
| [[File:B01.svg|20px|alt=B01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:A03.svg|20px|alt=A03|link=]][[File:H02.svg|20px|alt=H02|link=]]
|
|-
| FOUR
| <code>C05-M03-S02-C06-T02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S02.svg|20px|alt=S02|link=]][[File:C06.svg|20px|alt=C06|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| FIVE
| <code>C01-M03-T02</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:T02.svg|20px|alt=T02|link=]]
|
|-
| SIX
| <code>C05-B04-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:B04.svg|20px|alt=B04|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| SEVEN
| <code>M01-L01-A01-T03</code>
| [[File:M01.svg|20px|alt=M01|link=]][[File:L01.svg|20px|alt=L01|link=]][[File:A01.svg|20px|alt=A01|link=]][[File:T03.svg|20px|alt=T03|link=]]
|
|-
| EIGHT
| <code>B02-M03-S03</code>
| [[File:B02.svg|20px|alt=B02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:S03.svg|20px|alt=S03|link=]]
|
|-
| NINE
| <code>C05-M02-H02-A05-S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:A05.svg|20px|alt=A05|link=]][[File:S02.svg|20px|alt=S02|link=]]
|
|-
| TEN
| <code>C05-M01-T02-M02-L01</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M01.svg|20px|alt=M01|link=]][[File:T02.svg|20px|alt=T02|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:L01.svg|20px|alt=L01|link=]]
|
|-
| ELEVEN
| <code>A01-H01-B01</code>
| [[File:A01.svg|20px|alt=A01|link=]][[File:H01.svg|20px|alt=H01|link=]][[File:B01.svg|20px|alt=B01|link=]]
|
|-
| TWELVE (one dozen)
| <code>C01-S03-C03-T03-C01-M02-H02-B04</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]][[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Transparently ONE followed by the ×12 derivational bundle; no simplex sign sequence for twelve is attested in the inscription. Target of the complement sums 11+1, 10+2 and 6+6. <ref name="Rubergskier2024" />
|-
| '''EQUALS / clause spine'''
| <code>C02–M03–H03–C01</code>
| [[File:C02.svg|20px|alt=C02|link=]][[File:M03.svg|20px|alt=M03|link=]][[File:H03.svg|20px|alt=H03|link=]][[File:C01.svg|20px|alt=C01|link=]]
| Invariant medial sequence dividing left expression from result; reported as present in every equation clause. <ref name="Rubergskier2024" />
|-
| '''PLUS (binary addition)'''
| <code>A02–L01</code>
| [[File:A02.svg|20px|alt=A02|link=]][[File:L01.svg|20px|alt=L01|link=]]
| High-PMI operator cluster used in successor and complement constructions. <ref name="Rubergskier2024" />
|-
| '''MINUS (subtraction)'''
| <code>C05–M02–S02</code>
| [[File:C05.svg|20px|alt=C05|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:S02.svg|20px|alt=S02|link=]]
| Distinct collocational profile mirroring the syntax of the addition lines. <ref name="Rubergskier2024" />
|-
| '''ONE (simplex unit)'''
| <code>C01–S03–C03–T03</code>
| [[File:C01.svg|20px|alt=C01|link=]][[File:S03.svg|20px|alt=S03|link=]][[File:C03.svg|20px|alt=C03|link=]][[File:T03.svg|20px|alt=T03|link=]]
| Recurrent bundle functioning as the unit “one”; used to advance the successor chain. <ref name="Rubergskier2024" />
|-
| '''PUNCTUATION (bound period)'''
| <code>P01</code> (final only)
| [[File:P01.svg|20px|alt=P01|link=]]
| Clause-final slash behaving as bound punctuation; not attested internally. <ref name="Rubergskier2024" />
|-
| '''×12 derivation (“dozen”)'''
| –C01–M02–H02–B04 (right edge)
| [[File:C01.svg|20px|alt=C01|link=]][[File:M02.svg|20px|alt=M02|link=]][[File:H02.svg|20px|alt=H02|link=]][[File:B04.svg|20px|alt=B04|link=]]
| Contiguous right-edge 4-gram treated as a derivational suffix forming multiples of twelve; composes with stems. <ref name="Rubergskier2024" />
|}

== Scholarly discussion ==
Because the archaeological context of the longer inscription has not been publicly detailed, reception has been cautious. Supporters of the dozenal reading emphasise the conjunction of multiple independent diagnostics (final-only punctuation, a medial spine with near-zero variance, a selective right-edge four-gram, and complementary sums converging on the same target), arguing that chance alignment across all four is unlikely. Skeptics reply that without provenance, additional exemplars, or phonetic control, an arithmetic interpretation remains provisional and vulnerable to genre effects. Both sides agree on clear tests that could confirm or weaken the proposal: finding the slash P01 in non-final position; observing the putative ×12 four-gram away from clause edges; or documenting clauses that disrupt the medial spine while still behaving “arithmetically.”<ref name="Rubergskier2024" />

== Nomenclature ==
“Dozenal Primer Inscription” is a descriptive convenience used in secondary discussion and is not a claim about ancient self-designation. Alternative labels in circulation include “Dozenal arithmetic inscription,” “Twelve-base arithmetic inscription,” and “Kristiansen-coded arithmetic inscription.” For clarity and disambiguation within encyclopedic contexts, the present title foregrounds the proposed function (primer) and base (dozenal).

== Relation to the Scapula Glyph Inscription ==
The [[Scapula Glyph Inscription]] (KS-01) is much shorter but provided the stable sign labels and visual classes used in the transcription of the Dozenal Primer Inscription. KS-01 shows bipartite lines and a group-final slash divider consistent with the clause architecture proposed for the longer text, although by itself the scapula piece is too brief to display a full base-12 progression. Early notes on KS-01 also highlighted the need for direct examination and higher-quality imaging before drawing conclusions about material or chronology.<ref name="Kristiansen2023h" />

== See also ==
* [[Duodecimal]]
* [[Numeral system]]
* [[Mathematical notation]]
* [[Undeciphered writing systems]]
* [[Epigraphy]]
* [[Paleography]]

== References ==
<references />

[[Category:Kristiansen corpus]]
[[Category:Klema]]

Yedoma Ledger

2026-09-22T10:19:19Z

Mvuijlst: Yenoma -> Yedoma in name, lead and interpretation

Jan-Tage Kristiansen

2026-09-22T10:16:41Z

Mvuijlst: Eight families plus divider; add 2023 working paper and ELTTT affiliation

'''Jan-Tage Kristiansen''' (born 1971) is a Norwegian-Estonian philologist and independent researcher based in Tallinn. He trained as a linguist at the University of Bergen, where his MA thesis examined positional constraints in runic epigraphy, before completing a doctorate at the University of Tartu in 2001 on graphemic variability in undeciphered scripts of the eastern Baltic region.

Kristiansen worked for several years as a cataloguer at the Estonian History Museum before leaving institutional employment to pursue independent research. He is a corresponding member of ELTTT-Selskabet, a small learned society in Aarhus, under whose affiliation his longer work has appeared. He has described his working method as "palaeographic accountancy": systematic inventory of graphemic features before any interpretive commitment.

== Work ==
Kristiansen's correspondence note "Twin renderings, single template: a ruled signary on a putative cervid scapula" (''language'' 27, October 2023: 1073–1074) introduced the alphanumeric coding system now used throughout the scholarly literature on the [[Scapula Glyph Inscription]] and related texts. The note described a short, four-line inscription on a scapula-shaped object, identified eight visually coherent sign families (Corner, Box, Triangle, Line, Tee, Comb, Meander and Barred-post, labelled A, B, C, H, L, M, S and T), reserved a ninth code, P, for the slash divider, and provided a full positional frequency table. Kristiansen declined to propose a cultural attribution, noting that circulating images of the object appeared to derive from a single original drawing and that higher-resolution imaging was desirable before drawing further conclusions.

The coding system he established, in which each sign receives a family letter and index number (C01, B04, P01, and so on), was subsequently adopted without modification by [[Ginevra Rubergskier]], [[Camille Voudrin]], [[Inrik Üksküla]], and others, giving the note an influence disproportionate to its two-page length.

Later in 2023 Kristiansen circulated a longer working paper, "A geometric signary on a scapula and a longer companion inscription: inventory, layout, and statistical structure", under the ELTTT-Selskabet affiliation. It compiles the unified signary across the eight families, describes the scapula as a single ordered sweep through those families with slash separators, and reports positional biases, high-PMI collocations and bigram and trigram entropies below frequency-preserving shuffles in a six-line, 146-token companion inscription. The paper makes no claim of linguistic content and states that, given the anonymous digital-only provenance, a hoax or modern didactic pastiche cannot be excluded.

Kristiansen has continued to maintain the signary as a stable reference document, issuing minor corrections to the preliminary frequency table following the appearance of higher-quality tracings in 2024. He has not published an interpretive article of his own, describing his role as "keeping the inventory honest."

== Other interests ==
Outside the Kristiansen corpus, Kristiansen has published short notes on pre-Christian Baltic carved artefacts and on quantitative approaches to grapheme classification. He maintains a low profile and rarely attends conferences in person.

== See also ==
* [[Scapula Glyph Inscription]]
* [[Dozenal Primer Inscription]]
* [[Zagi Tablets]]
* [[Ginevra Rubergskier]]

[[Category:Researchers]][[Category:Epigraphy]][[Category:Kristiansen corpus]]

Inrik Üksküla

2026-05-06T13:37:51Z

Mvuijlst:

'''Inrik Üksküla''' (born 1979) is an Estonian linguist and semiotician, currently unaffiliated. He studied theoretical linguistics and logic at the University of Tartu, where he subsequently taught for several years before leaving academic employment in 2018. He has described his departure as voluntary, citing a preference for "work that doesn't require committee approval." He has since published independently, maintaining a particular interest in formal models of small, restricted corpora.

Üksküla's approach is characterised by a willingness to develop competing hypotheses in parallel rather than committing prematurely to a single reading. He has credited the Tartu tradition of semiotics associated with Juri Lotman as an influence on his view that a corpus should be allowed to generate its own interpretive possibilities before external frameworks are applied.

==Work==
Üksküla's preprint "The Clan of Zagi: Numeric Calculus or Genealogical Primer? A Structural Analysis of the Kristiansen Cuneiform Corpus" (2024) analysed 104 short, highly formulaic sentences in the [[Zagi Tablets]]—a corpus of clay tablets inscribed in the [[Kristiansen coding system]] and headed in Akkadian as ''imri Zagi-ak'' ("the clan of Zagi"). The study identified a small set of structural pivots and a paradigm of four ordinal or cardinal markers, and developed two interpretive hypotheses: a numeric calculus reading, in which the corpus functions as a didactic arithmetic system, and a genealogical primer reading, in which the same structures encode a kinship model for the named clan. Üksküla evaluated both against the corpus and concluded that the available evidence did not decisively favour either, proposing a hybrid in which formal numeric notation is used to model the internal structure of a specific kin-group.

The Akkadian heading ''imri Zagi-ak'' attracted particular attention as the first named attribution in the broader [[Kristiansen corpus]]. Üksküla noted that the name Zagi does not appear in any known Akkadian administrative context and may be a transliteration of a name from an unrelated language.

[[Ginevra Rubergskier|Rubergskier]] has observed that the AND_PLUS element in the Zagi corpus shares its collocational profile with the addition operator she identified in the [[Dozenal Primer Inscription]], a correspondence Üksküla discusses briefly in his preprint. [[Marie Roelandt]] subsequently developed Üksküla's genealogical hypothesis further in two posts on her blog [[Klema Field Notes]], arguing that the UNIT sign should be read as the kin term CHILD.

==See also==
* [[Zagi Tablets]]
* [[Scapula Glyph Inscription]]
* [[Jan-Tage Kristiansen]]
* [[Marie Roelandt]]

[[Category:Researchers]][[Category:Epigraphy]][[Category:Kristiansen corpus]]

A Cabinet of Brief Curiosities

2026-04-23T15:24:51Z

Mvuijlst:

{{Infobox
| 01_name = A Cabinet of Brief Curiosities
| 02_url = https://acbc.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated short-fiction application
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = MIT
}}

'''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated three-sentence short stories in the style of [[H. P. Lovecraft]]. Each story is composed by a large language model from a structured set of randomised "knobs" and optional user-supplied seed words, and is paired with a black-and-white illustration produced by a generative image model and styled to resemble a 19th-century engraved book plate. The site's rotating tagline — drawn every thirty minutes from a pool of forty-five variants — frames the act of generation in deliberately archaic terms; the canonical opening reads "Dredge slivers of impossible worlds from the black gulfs of imagination and press them into trembling mortal words."

== Technology stack ==

The application is built on Flask 3.0 with [[SQLite]] as its database, accessed through [[SQLAlchemy]].<ref name="requirements">requirements.txt in the project repository </ref> Authentication is handled by Flask-Login and cross-site request forgery protection by Flask-WTF. It is deployed on an Ubuntu VPS behind [[Nginx]] with [[Gunicorn]] running over a Unix socket under a dedicated <code>django</code> system user, supervised by systemd. Additional dependencies include the [[OpenAI]] Python client for both text and image generation, [[Pillow (imaging library)|Pillow]] for image post-processing, [[python-dotenv]] for environment configuration, and [[httpx]] as the underlying HTTP transport. The front end is rendered from Jinja templates using a small Bootstrap-derived stylesheet (<code>static/style.css</code>) and is registered as an installable progressive web app via <code>static/manifest.json</code> and a service worker (<code>static/sw.js</code>).

== Data model ==

The database contains two tables.

=== User ===

<code>User</code> stores a single bootstrapped administrator account with an e-mail address, a Werkzeug password hash, and a creation timestamp. Sign-ups are disabled at the route level: the <code>/signup</code> endpoint flashes a notice and redirects to login. The administrator is created on application start from the <code>ADMIN_EMAIL</code> and <code>ADMIN_PASSWORD</code> environment variables if no matching row exists.

=== Story ===

<code>Story</code> stores the generated short fiction:

* ''id'' (primary key), an optional ''user_id'' foreign key (null for guest submissions), the three-sentence ''story_text'', the optional ''mood'', ''nouns'' and ''verbs'' seeds supplied by the requester, an optional ''image_path'' (relative to the static folder, e.g. <code>images/story_42.png</code>), the originating ''ip_address'' (indexed), an indexed ''created_at'' timestamp, and a JSON-encoded ''knobs_json'' column that records the parameter set the model was given.

The schema is created on first run by SQLAlchemy. A small startup routine inspects the live table and issues an <code>ALTER TABLE</code> if a newer column (such as <code>knobs_json</code>) is missing, providing a lightweight migration path without an external migration framework. The same routine sets <code>PRAGMA journal_mode=WAL</code> on the SQLite database to allow concurrent reads while a background image-generation thread writes.

== Story generation pipeline ==

Story generation is initiated by a POST to <code>/generate</code> and proceeds through several deterministic-and-random stages before the OpenAI call.

=== Seeds and knobs ===

A request may carry up to three optional free-text fields — ''noun'', ''verb'', and ''mood'' — which are passed to the model as "seeds" and validated for presence in the output. Around the seeds, the application constructs a compact JSON ''knobs'' object that nudges the model along several axes:

{| class="wikitable"
|-
! Dimension !! Pool size !! Examples
|-
| Perspective || 4 || first, second, third, omniscient
|-
| Structure || 8 || Discovery → Investigation → Revelation; Object → Rumor → Catastrophe; Signal → Interpretation → Realization; …
|-
| Time || 8 (forced ''ambiguous'') || Victorian era, distant past, mythic period, interwar, near-future of obsolete technology
|-
| Location || 50 || lighthouse, salt marsh, foundry, signal box, scriptorium, observatory, shipbreaker's yard, …
|-
| Situation || 32 || during a storm, at low tide, during a blackout, on the eve of demolition, while the clock refuses to strike, …
|-
| Lexical palette || 53 || nautical, horological, astronomical, archival, cartographic, mycological, glaciological, heraldic, …
|-
| Style constraint || 5 || include exactly one short line of dialogue; include a question; avoid the words "shadow" and "dim"; …
|-
| Sentence pattern || 3 || short → long → medium; medium → short → long; long → medium → short
|-
| Theme (only when no seeds) || 18 || forbidden knowledge, cosmic entities, inherited curses, mathematical theorems, astronomical observations, …
|}

The knobs object always carries the seeds and at most two additional non-seed dimensions. Three of the knobs — ''perspective'', ''structure'', and ''time'' — are selected ''deterministically'' from a SHA-256 hash of a salt composed of the current 30-minute time bucket, the requester's IP address, and the seed words; this guarantees that the same client requesting the same seeds inside the same half-hour window draws the same priority knobs. The previous story's knobs for that IP are read from the <code>knobs_json</code> column (falling back to the JSONL choices log for older rows) and avoided where possible. ''Time'' is hard-pinned to <code>ambiguous</code> to suppress dated or era-specific references in the output. Lexicon and constraint values are sampled with the regular pseudo-random generator. Once all priority knobs are forced into the object, any non-priority extras are dropped at random until at most two non-seed knobs remain.

=== System rules ===

The system prompt is composed entirely of positive instructions: it asks for exactly three sentences in a grave Lovecraftian register, with no titles, lists, numbering, or blank lines, and embeds two short hand-written exemplar stories so the model can imitate length, cadence, and concreteness rather than reason in the negative. The application then validates the response against a separate banned-word list rather than naming forbidden terms in the prompt itself, in order to avoid the well-documented tendency of language models to reproduce items they are explicitly told to avoid.

=== Model selection ===

The default text model is GPT-4o (configurable via <code>OPENAI_MODEL</code>) with a configurable fallback (<code>OPENAI_FALLBACK_MODEL</code>, also GPT-4o by default). A helper function inspects the installed OpenAI SDK at request time: if the configured model is in the <code>gpt-5</code> family but the SDK does not expose the Responses API, the call silently falls back to a chat-compatible model. When the Responses API is available it is preferred for all models, with the system rules supplied via the explicit <code>instructions</code> field. For <code>gpt-5</code> family models the call additionally injects a <code>reasoning</code> object (defaulting to ''effort: low'' but configurable via <code>OPENAI_REASONING_EFFORT</code>), drops the <code>temperature</code> and <code>top_p</code> parameters (which those models reject), and grants a higher <code>max_output_tokens</code> budget (1600 by default, raised to 2400 on retry) to absorb reasoning-token consumption. For non-reasoning models, ''temperature'' is sampled uniformly from a narrow [0.78, 0.92] interval and ''top_p'' is fixed at 0.9, deliberately tighter than typical creative-writing defaults to keep tone consistent. Where the Responses API is unavailable, the call degrades to Chat Completions.

=== Validation and retry ===

After the call returns, the output is validated by a checker that enforces:

* Exactly three non-empty lines.
* No line beginning with any of a list of banned opening prefixes ("In the", "Beneath", "Under the", "Within the", and so on).
* Absence of a curated list of overused or out-of-register words and phrases ("eldritch", "cyclopean", "loathsome", any inflection of ''tentacle'', and similar).
* Absence of anachronisms unsuited to the desired ambiguous-historical tone (kilometres, kilograms, GPS coordinates, e-mail addresses, four-digit years, references to Wi-Fi).
* A per-sentence word count in the [8, 60] range.
* One terminal punctuation mark per line.

If the request supplied seeds, a second pass verifies that the noun appears in the text — with allowance for irregular plurals — and that the verb appears in any common inflection.

A separate near-duplicate check computes a 64-bit SimHash of the candidate text and rejects it if the Hamming distance to any of the most recent fifty stored stories is below a small threshold, so the corpus does not collapse into thematic loops.

When validation fails, a single targeted retry is issued with a corrective prompt that quotes the failing lines back at the model verbatim, names the specific failures, lowers the temperature slightly, and reuses the same knobs JSON. The retry result is accepted if it passes, or if it fails with strictly fewer issues than the original. If the model call itself fails — including the specific case where a <code>gpt-5</code> response is marked ''incomplete'' due to <code>max_output_tokens</code> — the pipeline retries once with a higher token budget, then attempts the configured fallback model, and finally falls back to a fixed three-sentence placeholder. All failures surface to the user as Flask flash messages with appropriate severity.

=== Persistence and logging ===

The validated story text is written to a new <code>Story</code> row together with the seeds, the originating IP, and the JSON-encoded knobs object. Image generation is then dispatched in a background daemon thread so the HTTP response returns immediately. Two structured logs are appended in JSON-Lines format under the Flask instance folder:

* <code>instance/choices.log.jsonl</code> records, per story, the seeds, the knobs JSON, the selected temperature and top_p, the model actually used, the configured model, and the validation outcome (including reasons and whether a retry was attempted).
* <code>instance/image.log.jsonl</code> records each image generation attempt with status (''success'', ''retry'', ''failed'', ''skipped''), error text, attempt count, image size, image model, and post-processing diagnostics such as the standard deviation of the output's luminance.

Both logs are rotated to a single ''<file>.1'' backup once they exceed a configurable byte threshold (default 2 MiB) so that long-running instances cannot fill the disk.

== Image generation ==

Each story is paired with a square 1024×1024 illustration generated through the OpenAI image API.

=== Style library ===

The application maintains a curated library of fifteen monochrome illustration styles, each anchored to one or more named historical artists or movements — for example wood engravings in the manner of Gustave Doré or Thomas Bewick, pen-and-ink in the manner of Aubrey Beardsley or Edward Gorey, drypoint in the manner of Käthe Kollwitz, aquatint in the manner of Goya's ''Caprichos'', a Victorian scientific plate after Ernst Haeckel, relief woodcut after Lynd Ward, silhouette cuts after Lotte Reiniger, and symbolist pen-and-ink after Alfred Kubin. Anchoring each entry to a real reference reliably moves the model closer to the desired register. The style for a given story is selected by hashing its primary key, so adjacent stories on the home grid do not visually collide and a regenerated image for the same story can vary by perturbing the salt. A legacy global counter file at <code>instance/image_style_cycle.txt</code> is retained for callers without a story id.

=== Prompt construction ===

To keep the image prompt concrete enough for a diffusion model to act on, the three-sentence story is first reduced to a one- or two-sentence visual scene description by a cheap secondary call to a smaller model (<code>OPENAI_SCENE_MODEL</code>, default <code>gpt-4o-mini</code>); the helper names a single subject, a single setting, one source of light, and one telling object, and discards mood words and metaphor. The final image prompt is then assembled from a hard full-bleed directive, the selected style sentence, the scene description, and an avoid clause that explicitly forbids colour, painterly shading, photorealism, captions, watermarks, signatures, and any kind of border, frame, or decorative edge.

=== Image API and retries ===

The configured image model defaults to <code>gpt-image-1</code>; common typos such as <code>gpt-image-1.5</code> are normalised back to <code>gpt-image-1</code> at start-up. The generation size is configurable through <code>OPENAI_IMAGE_GEN_SIZE</code> (default 1024×1024) and the post-processed final size is fixed at 1024×1024. Each generation tolerates up to three attempts (configurable via <code>IMAGE_RETRIES</code>) with exponential backoff starting at 1.5 seconds and capped at 10 seconds. If all attempts fail — or if a returned image is blank or near-uniform — a small inline SVG placeholder is written to disk and recorded as the story's image path so the front end always has something to display. A few legacy stories carry a one-pixel GIF placeholder of the same purpose; the application detects either by the presence of the substring <code>_placeholder.</code> in the path.

=== Post-processing ===

Successfully returned PNG bytes are passed through a Pillow-based post-processor that:

* Estimates the background colour from the four corner patches.
* Computes a difference image against a uniform background of that colour, raises its contrast, and finds the bounding box of meaningful content.
* Crops away any uniform border of more than ten pixels on any side, padded by two pixels to avoid clipping ink.
* Resizes the result back to the final size using Lanczos resampling and re-encodes as optimised PNG.
* Computes the standard deviation of the resulting image's luminance; if the value falls below a small threshold, the image is treated as blank and the generation attempt is failed so a retry can be issued.

If Pillow is unavailable or any step fails, the original bytes are written through unchanged.

== Public interface ==

=== Home ===

The home page (<code>/</code>) renders the generation form together with a gallery of the five most recent stories that successfully produced an image. For unauthenticated visitors, the form is hidden and replaced by a rotating notice (one of twenty-two phrasings, selected from a SHA-256 hash of the visitor's IP and a six-hour bucket) when the visitor has already generated a story in the last 24 hours or when the site-wide guest cap has been reached. A footer-level statistics block displays the number of guest stories in the last 24 hours, the number of stories created by signed-in users in the same window, the all-time total, and the time elapsed since the most recent story.

=== Story detail ===

Each story is reachable at <code>/story/<id></code> and is publicly viewable regardless of authorship. The page presents the three sentences alongside the illustration; for the administrator, controls are exposed to regenerate the image (<code>/regenerate-image/<id></code>) or delete the story (<code>/story/<id>/delete</code>). A polling endpoint at <code>/api/story/<id>/status</code> returns a JSON document indicating whether a real image has yet been written, the URL of the image (or placeholder), and a flag distinguishing the two; the front-end script polls with exponential backoff capped at eight seconds, gives up after a hard timeout, and writes status updates into an <code>aria-live</code> region for screen-reader accessibility. The story page also overrides the base template's [[Open Graph protocol|Open Graph]] block to advertise per-story metadata, including the generated illustration, when the page is shared on social media.

=== Archive ===

The archive (<code>/archive</code>) is a paginated chronological listing of all stories, nine per page, with previous/next navigation. There is no per-user filter — all stories are visible. The archive page sets <code><meta name="robots" content="noindex,follow"></code> to keep the long tail out of search-engine indexes while leaving individual story pages indexable.

=== Health endpoint ===

<code>/healthz</code> returns a small JSON document and an HTTP 200 when the application is fully configured and able to query the database, or HTTP 503 when the OpenAI API key is not set or the database round-trip fails. It is intended for use by uptime monitors and load balancers.

=== Authentication ===

<code>/login</code> accepts only the e-mail address configured in <code>ADMIN_EMAIL</code> and verifies the password against the stored Werkzeug hash. <code>/logout</code> ends the session. <code>/signup</code> is intentionally disabled. All form-bearing pages carry a CSRF token rendered from the Flask-WTF helper, and an expired token is recovered with a flash message and a redirect rather than an HTTP error.

=== Tagline rotation ===

The base template injects a "current tagline" string into every response. The selection is deterministic on the current 30-minute interval since the Unix epoch: the interval timestamp is used as a seed for the standard library random module, which then picks one of forty-five variant phrasings. All visitors served within the same half-hour see the same tagline; the tagline rotates without any database state.

== Rate limiting ==

Rate limiting is enforced for unauthenticated visitors only:

* '''Per-IP daily limit''': any IP that has produced a story within the last 24 hours is blocked from generating another (one story per visitor per day).
* '''Site-wide guest cap''': the total number of guest-authored stories in the last 24 hours must not exceed <code>GUEST_DAILY_CAP</code> (default 24). When the cap is reached, the form is hidden for all guests until older stories age out.

Both limits are evaluated at form render time (to hide the form) and at form submission time (to short-circuit the POST with a flashed warning and a redirect). Authenticated users have no rate limits and no per-IP enforcement.

The originating IP for limit accounting and for the <code>Story.ip_address</code> column is read from the <code>X-Forwarded-For</code> request header only when the immediate peer is in a configurable trusted-proxy allow-list (<code>TRUSTED_PROXIES</code>, default loopback); otherwise the application uses <code>request.remote_addr</code>. This prevents trivial spoofing of the originating address when the application is exposed without a reverse proxy in front of it.

== Deployment ==

The production deployment is an Ubuntu VPS running a systemd unit (<code>acbc.service</code>) that launches Gunicorn with three workers, bound to a Unix domain socket under the project directory. Nginx terminates HTTPS (provisioned by [[Let's Encrypt]] via Certbot), serves the <code>static/</code> directory directly with a one-year immutable cache header, and proxies all other requests to the Gunicorn socket. The service runs as the <code>django</code> system user out of <code>/home/django/acbc</code>. The application reads its configuration from environment variables loaded via python-dotenv.

== Security and authorisation ==

* All POST endpoints require a CSRF token issued by Flask-WTF.
* Sign-ups are disabled; only the bootstrapped administrator account can authenticate.
* Login attempts for any e-mail other than <code>ADMIN_EMAIL</code> are rejected without a database query.
* The image-deletion helper refuses to remove any path that does not begin with <code>images/</code> or that, after canonicalisation, falls outside the configured upload folder, providing protection against path-traversal in stored data.
* Story deletion requires either the administrator session or ownership of the row; image regeneration requires the administrator session.
* The story-status JSON endpoint returns no user-identifying information beyond the public fields rendered on the story page.
* The originating-IP determination only honours <code>X-Forwarded-For</code> from trusted proxies.

== See also ==

* [[OpenAI]]
* [[Flask (web framework)]]
* [[H. P. Lovecraft]]
* [[Computational creativity]]
* [[Generative artificial intelligence]]

== References ==
{{reflist}}

A Cabinet of Brief Curiosities

2026-04-23T15:23:51Z

Mvuijlst:

{{Infobox
| 01_name = A Cabinet of Brief Curiosities
| 02_url = https://acbc.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated short-fiction application
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = MIT
}}

'''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated three-sentence short stories in the style of [[H. P. Lovecraft]]. Each story is composed by a large language model from a structured set of randomised "knobs" and optional user-supplied seed words, and is paired with a black-and-white illustration produced by a generative image model and styled to resemble a 19th-century engraved book plate. The site's rotating tagline — drawn every thirty minutes from a pool of forty-five variants — frames the act of generation in deliberately archaic terms; the canonical opening reads "Dredge slivers of impossible worlds from the black gulfs of imagination and press them into trembling mortal words."

== Technology stack ==

The application is built on Flask 3.0 with [[SQLite]] as its database, accessed through [[SQLAlchemy]] (Flask-SQLAlchemy 3.1).<ref name="requirements">requirements.txt in the project repository pins Flask 3.0.3, Flask-Login 0.6.3, Flask-SQLAlchemy 3.1.1, Flask-WTF ≥1.2, python-dotenv 1.0.1, openai ≥1.50, httpx 0.27.2, and Pillow ≥10.</ref> Authentication is handled by Flask-Login and cross-site request forgery protection by Flask-WTF. It is deployed on an Ubuntu VPS behind [[Nginx]] with [[Gunicorn]] running over a Unix socket under a dedicated <code>django</code> system user, supervised by systemd. Additional dependencies include the [[OpenAI]] Python client for both text and image generation, [[Pillow (imaging library)|Pillow]] for image post-processing, [[python-dotenv]] for environment configuration, and [[httpx]] as the underlying HTTP transport. The front end is rendered from Jinja templates using a small Bootstrap-derived stylesheet (<code>static/style.css</code>) and is registered as an installable progressive web app via <code>static/manifest.json</code> and a service worker (<code>static/sw.js</code>).

== Data model ==

The database contains two tables.

=== User ===

<code>User</code> stores a single bootstrapped administrator account with an e-mail address, a Werkzeug password hash, and a creation timestamp. Sign-ups are disabled at the route level: the <code>/signup</code> endpoint flashes a notice and redirects to login. The administrator is created on application start from the <code>ADMIN_EMAIL</code> and <code>ADMIN_PASSWORD</code> environment variables if no matching row exists.

=== Story ===

<code>Story</code> stores the generated short fiction:

* ''id'' (primary key), an optional ''user_id'' foreign key (null for guest submissions), the three-sentence ''story_text'', the optional ''mood'', ''nouns'' and ''verbs'' seeds supplied by the requester, an optional ''image_path'' (relative to the static folder, e.g. <code>images/story_42.png</code>), the originating ''ip_address'' (indexed), an indexed ''created_at'' timestamp, and a JSON-encoded ''knobs_json'' column that records the parameter set the model was given.

The schema is created on first run by SQLAlchemy. A small startup routine inspects the live table and issues an <code>ALTER TABLE</code> if a newer column (such as <code>knobs_json</code>) is missing, providing a lightweight migration path without an external migration framework. The same routine sets <code>PRAGMA journal_mode=WAL</code> on the SQLite database to allow concurrent reads while a background image-generation thread writes.

== Story generation pipeline ==

Story generation is initiated by a POST to <code>/generate</code> and proceeds through several deterministic-and-random stages before the OpenAI call.

=== Seeds and knobs ===

A request may carry up to three optional free-text fields — ''noun'', ''verb'', and ''mood'' — which are passed to the model as "seeds" and validated for presence in the output. Around the seeds, the application constructs a compact JSON ''knobs'' object that nudges the model along several axes:

{| class="wikitable"
|-
! Dimension !! Pool size !! Examples
|-
| Perspective || 4 || first, second, third, omniscient
|-
| Structure || 8 || Discovery → Investigation → Revelation; Object → Rumor → Catastrophe; Signal → Interpretation → Realization; …
|-
| Time || 8 (forced ''ambiguous'') || Victorian era, distant past, mythic period, interwar, near-future of obsolete technology
|-
| Location || 50 || lighthouse, salt marsh, foundry, signal box, scriptorium, observatory, shipbreaker's yard, …
|-
| Situation || 32 || during a storm, at low tide, during a blackout, on the eve of demolition, while the clock refuses to strike, …
|-
| Lexical palette || 53 || nautical, horological, astronomical, archival, cartographic, mycological, glaciological, heraldic, …
|-
| Style constraint || 5 || include exactly one short line of dialogue; include a question; avoid the words "shadow" and "dim"; …
|-
| Sentence pattern || 3 || short → long → medium; medium → short → long; long → medium → short
|-
| Theme (only when no seeds) || 18 || forbidden knowledge, cosmic entities, inherited curses, mathematical theorems, astronomical observations, …
|}

The knobs object always carries the seeds and at most two additional non-seed dimensions. Three of the knobs — ''perspective'', ''structure'', and ''time'' — are selected ''deterministically'' from a SHA-256 hash of a salt composed of the current 30-minute time bucket, the requester's IP address, and the seed words; this guarantees that the same client requesting the same seeds inside the same half-hour window draws the same priority knobs. The previous story's knobs for that IP are read from the <code>knobs_json</code> column (falling back to the JSONL choices log for older rows) and avoided where possible. ''Time'' is hard-pinned to <code>ambiguous</code> to suppress dated or era-specific references in the output. Lexicon and constraint values are sampled with the regular pseudo-random generator. Once all priority knobs are forced into the object, any non-priority extras are dropped at random until at most two non-seed knobs remain.

=== System rules ===

The system prompt is composed entirely of positive instructions: it asks for exactly three sentences in a grave Lovecraftian register, with no titles, lists, numbering, or blank lines, and embeds two short hand-written exemplar stories so the model can imitate length, cadence, and concreteness rather than reason in the negative. The application then validates the response against a separate banned-word list rather than naming forbidden terms in the prompt itself, in order to avoid the well-documented tendency of language models to reproduce items they are explicitly told to avoid.

=== Model selection ===

The default text model is GPT-4o (configurable via <code>OPENAI_MODEL</code>) with a configurable fallback (<code>OPENAI_FALLBACK_MODEL</code>, also GPT-4o by default). A helper function inspects the installed OpenAI SDK at request time: if the configured model is in the <code>gpt-5</code> family but the SDK does not expose the Responses API, the call silently falls back to a chat-compatible model. When the Responses API is available it is preferred for all models, with the system rules supplied via the explicit <code>instructions</code> field. For <code>gpt-5</code> family models the call additionally injects a <code>reasoning</code> object (defaulting to ''effort: low'' but configurable via <code>OPENAI_REASONING_EFFORT</code>), drops the <code>temperature</code> and <code>top_p</code> parameters (which those models reject), and grants a higher <code>max_output_tokens</code> budget (1600 by default, raised to 2400 on retry) to absorb reasoning-token consumption. For non-reasoning models, ''temperature'' is sampled uniformly from a narrow [0.78, 0.92] interval and ''top_p'' is fixed at 0.9, deliberately tighter than typical creative-writing defaults to keep tone consistent. Where the Responses API is unavailable, the call degrades to Chat Completions.

=== Validation and retry ===

After the call returns, the output is validated by a checker that enforces:

* Exactly three non-empty lines.
* No line beginning with any of a list of banned opening prefixes ("In the", "Beneath", "Under the", "Within the", and so on).
* Absence of a curated list of overused or out-of-register words and phrases ("eldritch", "cyclopean", "loathsome", any inflection of ''tentacle'', and similar).
* Absence of anachronisms unsuited to the desired ambiguous-historical tone (kilometres, kilograms, GPS coordinates, e-mail addresses, four-digit years, references to Wi-Fi).
* A per-sentence word count in the [8, 60] range.
* One terminal punctuation mark per line.

If the request supplied seeds, a second pass verifies that the noun appears in the text — with allowance for irregular plurals — and that the verb appears in any common inflection.

A separate near-duplicate check computes a 64-bit SimHash of the candidate text and rejects it if the Hamming distance to any of the most recent fifty stored stories is below a small threshold, so the corpus does not collapse into thematic loops.

When validation fails, a single targeted retry is issued with a corrective prompt that quotes the failing lines back at the model verbatim, names the specific failures, lowers the temperature slightly, and reuses the same knobs JSON. The retry result is accepted if it passes, or if it fails with strictly fewer issues than the original. If the model call itself fails — including the specific case where a <code>gpt-5</code> response is marked ''incomplete'' due to <code>max_output_tokens</code> — the pipeline retries once with a higher token budget, then attempts the configured fallback model, and finally falls back to a fixed three-sentence placeholder. All failures surface to the user as Flask flash messages with appropriate severity.

=== Persistence and logging ===

The validated story text is written to a new <code>Story</code> row together with the seeds, the originating IP, and the JSON-encoded knobs object. Image generation is then dispatched in a background daemon thread so the HTTP response returns immediately. Two structured logs are appended in JSON-Lines format under the Flask instance folder:

* <code>instance/choices.log.jsonl</code> records, per story, the seeds, the knobs JSON, the selected temperature and top_p, the model actually used, the configured model, and the validation outcome (including reasons and whether a retry was attempted).
* <code>instance/image.log.jsonl</code> records each image generation attempt with status (''success'', ''retry'', ''failed'', ''skipped''), error text, attempt count, image size, image model, and post-processing diagnostics such as the standard deviation of the output's luminance.

Both logs are rotated to a single ''<file>.1'' backup once they exceed a configurable byte threshold (default 2 MiB) so that long-running instances cannot fill the disk.

== Image generation ==

Each story is paired with a square 1024×1024 illustration generated through the OpenAI image API.

=== Style library ===

The application maintains a curated library of fifteen monochrome illustration styles, each anchored to one or more named historical artists or movements — for example wood engravings in the manner of Gustave Doré or Thomas Bewick, pen-and-ink in the manner of Aubrey Beardsley or Edward Gorey, drypoint in the manner of Käthe Kollwitz, aquatint in the manner of Goya's ''Caprichos'', a Victorian scientific plate after Ernst Haeckel, relief woodcut after Lynd Ward, silhouette cuts after Lotte Reiniger, and symbolist pen-and-ink after Alfred Kubin. Anchoring each entry to a real reference reliably moves the model closer to the desired register. The style for a given story is selected by hashing its primary key, so adjacent stories on the home grid do not visually collide and a regenerated image for the same story can vary by perturbing the salt. A legacy global counter file at <code>instance/image_style_cycle.txt</code> is retained for callers without a story id.

=== Prompt construction ===

To keep the image prompt concrete enough for a diffusion model to act on, the three-sentence story is first reduced to a one- or two-sentence visual scene description by a cheap secondary call to a smaller model (<code>OPENAI_SCENE_MODEL</code>, default <code>gpt-4o-mini</code>); the helper names a single subject, a single setting, one source of light, and one telling object, and discards mood words and metaphor. The final image prompt is then assembled from a hard full-bleed directive, the selected style sentence, the scene description, and an avoid clause that explicitly forbids colour, painterly shading, photorealism, captions, watermarks, signatures, and any kind of border, frame, or decorative edge.

=== Image API and retries ===

The configured image model defaults to <code>gpt-image-1</code>; common typos such as <code>gpt-image-1.5</code> are normalised back to <code>gpt-image-1</code> at start-up. The generation size is configurable through <code>OPENAI_IMAGE_GEN_SIZE</code> (default 1024×1024) and the post-processed final size is fixed at 1024×1024. Each generation tolerates up to three attempts (configurable via <code>IMAGE_RETRIES</code>) with exponential backoff starting at 1.5 seconds and capped at 10 seconds. If all attempts fail — or if a returned image is blank or near-uniform — a small inline SVG placeholder is written to disk and recorded as the story's image path so the front end always has something to display. A few legacy stories carry a one-pixel GIF placeholder of the same purpose; the application detects either by the presence of the substring <code>_placeholder.</code> in the path.

=== Post-processing ===

Successfully returned PNG bytes are passed through a Pillow-based post-processor that:

* Estimates the background colour from the four corner patches.
* Computes a difference image against a uniform background of that colour, raises its contrast, and finds the bounding box of meaningful content.
* Crops away any uniform border of more than ten pixels on any side, padded by two pixels to avoid clipping ink.
* Resizes the result back to the final size using Lanczos resampling and re-encodes as optimised PNG.
* Computes the standard deviation of the resulting image's luminance; if the value falls below a small threshold, the image is treated as blank and the generation attempt is failed so a retry can be issued.

If Pillow is unavailable or any step fails, the original bytes are written through unchanged.

== Public interface ==

=== Home ===

The home page (<code>/</code>) renders the generation form together with a gallery of the five most recent stories that successfully produced an image. For unauthenticated visitors, the form is hidden and replaced by a rotating notice (one of twenty-two phrasings, selected from a SHA-256 hash of the visitor's IP and a six-hour bucket) when the visitor has already generated a story in the last 24 hours or when the site-wide guest cap has been reached. A footer-level statistics block displays the number of guest stories in the last 24 hours, the number of stories created by signed-in users in the same window, the all-time total, and the time elapsed since the most recent story.

=== Story detail ===

Each story is reachable at <code>/story/<id></code> and is publicly viewable regardless of authorship. The page presents the three sentences alongside the illustration; for the administrator, controls are exposed to regenerate the image (<code>/regenerate-image/<id></code>) or delete the story (<code>/story/<id>/delete</code>). A polling endpoint at <code>/api/story/<id>/status</code> returns a JSON document indicating whether a real image has yet been written, the URL of the image (or placeholder), and a flag distinguishing the two; the front-end script polls with exponential backoff capped at eight seconds, gives up after a hard timeout, and writes status updates into an <code>aria-live</code> region for screen-reader accessibility. The story page also overrides the base template's [[Open Graph protocol|Open Graph]] block to advertise per-story metadata, including the generated illustration, when the page is shared on social media.

=== Archive ===

The archive (<code>/archive</code>) is a paginated chronological listing of all stories, nine per page, with previous/next navigation. There is no per-user filter — all stories are visible. The archive page sets <code><meta name="robots" content="noindex,follow"></code> to keep the long tail out of search-engine indexes while leaving individual story pages indexable.

=== Health endpoint ===

<code>/healthz</code> returns a small JSON document and an HTTP 200 when the application is fully configured and able to query the database, or HTTP 503 when the OpenAI API key is not set or the database round-trip fails. It is intended for use by uptime monitors and load balancers.

=== Authentication ===

<code>/login</code> accepts only the e-mail address configured in <code>ADMIN_EMAIL</code> and verifies the password against the stored Werkzeug hash. <code>/logout</code> ends the session. <code>/signup</code> is intentionally disabled. All form-bearing pages carry a CSRF token rendered from the Flask-WTF helper, and an expired token is recovered with a flash message and a redirect rather than an HTTP error.

=== Tagline rotation ===

The base template injects a "current tagline" string into every response. The selection is deterministic on the current 30-minute interval since the Unix epoch: the interval timestamp is used as a seed for the standard library random module, which then picks one of forty-five variant phrasings. All visitors served within the same half-hour see the same tagline; the tagline rotates without any database state.

== Rate limiting ==

Rate limiting is enforced for unauthenticated visitors only:

* '''Per-IP daily limit''': any IP that has produced a story within the last 24 hours is blocked from generating another (one story per visitor per day).
* '''Site-wide guest cap''': the total number of guest-authored stories in the last 24 hours must not exceed <code>GUEST_DAILY_CAP</code> (default 24). When the cap is reached, the form is hidden for all guests until older stories age out.

Both limits are evaluated at form render time (to hide the form) and at form submission time (to short-circuit the POST with a flashed warning and a redirect). Authenticated users have no rate limits and no per-IP enforcement.

The originating IP for limit accounting and for the <code>Story.ip_address</code> column is read from the <code>X-Forwarded-For</code> request header only when the immediate peer is in a configurable trusted-proxy allow-list (<code>TRUSTED_PROXIES</code>, default loopback); otherwise the application uses <code>request.remote_addr</code>. This prevents trivial spoofing of the originating address when the application is exposed without a reverse proxy in front of it.

== Deployment ==

The production deployment is an Ubuntu VPS running a systemd unit (<code>acbc.service</code>) that launches Gunicorn with three workers, bound to a Unix domain socket under the project directory. Nginx terminates HTTPS (provisioned by [[Let's Encrypt]] via Certbot), serves the <code>static/</code> directory directly with a one-year immutable cache header, and proxies all other requests to the Gunicorn socket. The service runs as the <code>django</code> system user out of <code>/home/django/acbc</code>. The application reads its configuration from environment variables loaded via python-dotenv.

== Security and authorisation ==

* All POST endpoints require a CSRF token issued by Flask-WTF.
* Sign-ups are disabled; only the bootstrapped administrator account can authenticate.
* Login attempts for any e-mail other than <code>ADMIN_EMAIL</code> are rejected without a database query.
* The image-deletion helper refuses to remove any path that does not begin with <code>images/</code> or that, after canonicalisation, falls outside the configured upload folder, providing protection against path-traversal in stored data.
* Story deletion requires either the administrator session or ownership of the row; image regeneration requires the administrator session.
* The story-status JSON endpoint returns no user-identifying information beyond the public fields rendered on the story page.
* The originating-IP determination only honours <code>X-Forwarded-For</code> from trusted proxies.

== See also ==

* [[OpenAI]]
* [[Flask (web framework)]]
* [[H. P. Lovecraft]]
* [[Computational creativity]]
* [[Generative artificial intelligence]]

== References ==
{{reflist}}

A Cabinet of Brief Curiosities

2026-04-23T14:50:46Z

Mvuijlst: Created page with "{{Infobox | 01_name = A Cabinet of Brief Curiosities | 02_url = https://acbc.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2025 | 05_genre = AI-generated short-fiction application | 06_language = Python | 07_framework = Flask 3.0 | 08_license = MIT }} '''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated thre..."

{{Infobox
| 01_name = A Cabinet of Brief Curiosities
| 02_url = https://acbc.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated short-fiction application
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = MIT
}}

'''A Cabinet of Brief Curiosities''' (abbreviated '''acbc''') is a web application hosted at <code>acbc.yusupov.cloud</code> that generates illustrated three-sentence short stories in the style of [[H. P. Lovecraft]]. Each story is composed by a large language model from a structured set of randomised "knobs" and optional user-supplied seed words, and is paired with a black-and-white illustration designed to resemble a 19th-century engraved book plate. The site's rotating tagline — drawn every thirty minutes from a pool of forty-five variants — frames the act of generation in deliberately archaic terms; the canonical opening reads "Dredge slivers of impossible worlds from the black gulfs of imagination and press them into trembling mortal words."

== Technology stack ==

The application is built on Flask 3.0 with [[SQLite]] as its database, accessed through [[SQLAlchemy]] (Flask-SQLAlchemy 3.1).<ref name="requirements">requirements.txt in the project repository pins Flask 3.0.3, Flask-Login 0.6.3, Flask-SQLAlchemy 3.1.1, python-dotenv 1.0.1, openai ≥1.50, httpx 0.27.2, and Pillow ≥10.</ref> Authentication is handled by Flask-Login. It is deployed on an Ubuntu VPS behind [[Nginx]] with [[Gunicorn]] running over a Unix socket under a dedicated <code>django</code> system user, supervised by systemd. Additional dependencies include the [[OpenAI]] Python client for both text and image generation, [[Pillow (imaging library)|Pillow]] for image post-processing, [[python-dotenv]] for environment configuration, and [[httpx]] as the underlying HTTP transport. The front end is rendered from Jinja templates using a small Bootstrap-derived stylesheet (<code>static/style.css</code>) and is registered as an installable progressive web app via <code>static/manifest.json</code> and a service worker (<code>static/sw.js</code>).

== Data model ==

The database contains two tables.

=== User ===

<code>User</code> stores a single bootstrapped administrator account with an e-mail address, a Werkzeug password hash, and a creation timestamp. Sign-ups are disabled at the route level: the <code>/signup</code> endpoint flashes a notice and redirects to login. The administrator is created on application start from the <code>ADMIN_EMAIL</code> and <code>ADMIN_PASSWORD</code> environment variables if no matching row exists.

=== Story ===

<code>Story</code> stores the generated short fiction:

* ''id'' (primary key), an optional ''user_id'' foreign key (null for guest submissions), the three-sentence ''story_text'', the optional ''mood'', ''nouns'' and ''verbs'' seeds supplied by the requester, an optional ''image_path'' (relative to the static folder, e.g. <code>images/story_42.png</code>), the originating ''ip_address'' (indexed), and an indexed ''created_at'' timestamp.

== Story generation pipeline ==

Story generation is initiated by a POST to <code>/generate</code> and proceeds through several deterministic-and-random stages before the OpenAI call.

=== Seeds and knobs ===

A request may carry up to three optional free-text fields — ''noun'', ''verb'', and ''mood'' — which are passed to the model as "seeds" and validated for presence in the output. Around the seeds, the application constructs a compact JSON ''knobs'' object that nudges the model along several axes:

{| class="wikitable"
|-
! Dimension !! Pool size !! Examples
|-
| Perspective || 4 || first, second, third, omniscient
|-
| Structure || 8 || Discovery → Investigation → Revelation; Object → Rumor → Catastrophe; Signal → Interpretation → Realization; …
|-
| Time || 8 (forced ''ambiguous'') || Victorian era, distant past, mythic period, interwar, near-future of obsolete technology
|-
| Location || 50 || lighthouse, salt marsh, foundry, signal box, scriptorium, observatory, shipbreaker's yard, …
|-
| Situation || 32 || during a storm, at low tide, during a blackout, on the eve of demolition, while the clock refuses to strike, …
|-
| Lexical palette || 53 || nautical, horological, astronomical, archival, cartographic, mycological, glaciological, heraldic, …
|-
| Style constraint || 5 || include exactly one short line of dialogue; include a question; avoid the words "shadow" and "dim"; …
|-
| Sentence pattern || 3 || short → long → medium; medium → short → long; long → medium → short
|-
| Theme (only when no seeds) || 18 || forbidden knowledge, cosmic entities, inherited curses, mathematical theorems, astronomical observations, …
|}

The knobs object always carries the seeds and at most three additional dimensions. Three of the knobs — ''perspective'', ''structure'', and ''time'' — are selected ''deterministically'' from a SHA-256 hash of a salt composed of the current 30-minute time bucket, the requester's IP address, and the seed words; this guarantees that the same client requesting the same seeds inside the same half-hour window draws the same priority knobs. The previous story's knobs for that IP are read from the choices log and avoided where possible. ''Time'' is hard-pinned to <code>ambiguous</code> to suppress dated or era-specific references in the output. Lexicon and constraint values are sampled with the regular pseudo-random generator. Once all priority knobs are forced into the object, any non-priority extras are dropped at random until at most three non-seed knobs remain.

=== System rules ===

The system prompt instructs the model to produce a coherent short story of exactly three sentences in the style of H. P. Lovecraft, with no titles, lists, numbering, or blank lines. The tone must be grave, ominous, and unsettling, and never humorous. The model is forbidden to use the words "eldritch", "cyclopean", or "loathsome", and is forbidden to begin any line with one of six banned openings — "In the", "Beneath", "Under the", "Within the", "In the dim", and "In the shadow". Whimsical seeds are to be adapted with synonyms that preserve tone.

=== Model selection ===

The default text model is GPT-4o (configurable via <code>OPENAI_MODEL</code>) with a configurable fallback (<code>OPENAI_FALLBACK_MODEL</code>, also GPT-4o by default). A helper function inspects the installed OpenAI SDK at request time: if the configured model is in the <code>gpt-5</code> family but the SDK does not expose the Responses API, the call silently falls back to a chat-compatible model. When the Responses API is available it is preferred for all models, with the system rules supplied via the explicit <code>instructions</code> field. For <code>gpt-5</code> family models the call additionally injects a <code>reasoning</code> object (defaulting to ''effort: low'' but configurable via <code>OPENAI_REASONING_EFFORT</code>), drops the <code>temperature</code> and <code>top_p</code> parameters (which those models reject), and grants a higher <code>max_output_tokens</code> budget (1600 by default, raised to 2400 on retry) to absorb reasoning-token consumption. For non-reasoning models, ''temperature'' is sampled uniformly from [0.88, 1.05] and ''top_p'' is fixed at 0.92. Where the Responses API is unavailable, the call degrades to Chat Completions.

=== Validation and retry ===

After the call returns, the output is validated by a lightweight checker that enforces:

* Exactly three non-empty lines.
* No line beginning with any of the banned opening prefixes.
* Absence of the banned words.
* One terminal punctuation mark per line (no missing terminator, no more than two strong delimiters).

If the request supplied seeds, a second pass verifies that the noun appears in the text and that the verb (or a simple inflection thereof) appears as a whole word.

When validation fails, a single targeted retry is issued with a corrective prompt that names the specific failures, lowers the temperature slightly, and reuses the same knobs JSON. The retry result is accepted if it passes, or if it fails with strictly fewer issues than the original. If the model call itself fails — including the specific case where a <code>gpt-5</code> response is marked ''incomplete'' due to <code>max_output_tokens</code> — the pipeline retries once with a higher token budget, then attempts the configured fallback model, and finally falls back to a fixed three-sentence placeholder ("The moon borrowed a suitcase from a bewildered pigeon. …"). All failures surface to the user as Flask flash messages with appropriate severity.

=== Persistence and logging ===

The validated story text is written to a new <code>Story</code> row together with the seeds and originating IP. Image generation is then dispatched in a background daemon thread so the HTTP response returns immediately. Two structured logs are appended in JSON-Lines format under the Flask instance folder:

* <code>instance/choices.log.jsonl</code> records, per story, the seeds, the knobs JSON, the selected temperature and top_p, the model actually used, the configured model, and the validation outcome (including reasons and whether a retry was attempted).
* <code>instance/image.log.jsonl</code> records each image generation attempt with status (''success'', ''retry'', ''failed'', ''skipped''), error text, attempt count, image size, and image model.

== Image generation ==

Each story is paired with a square 1024×1024 illustration generated through the OpenAI image API.

=== Style cycling ===

The application maintains a counter file at <code>instance/image_style_cycle.txt</code> that walks deterministically through a library of fifteen monochrome engraving styles, including Victorian wood engraving, antique grimoire pen-and-ink, penny-dreadful frontispiece, steel engraving, copperplate etching, drypoint, mezzotint, aquatint-grained etching, scratchboard, Victorian scientific plate, woodcut, scanned 1860s book plate, fin-de-siècle symbolism, and Victorian reportage sketch. A threading lock guards the read-modify-write of the counter so that concurrent generations do not collide on the same style. If the counter file is missing or unreadable, a random style is chosen instead.

=== Prompt construction ===

The image prompt is assembled from four blocks:

# A composition directive specifying a square 1:1 aspect ratio, full-bleed framing with no borders or margins, and a centred subject.
# The selected style sentence from the cycling library.
# A "scanned 1860s book plate" line that asks for slight ink unevenness and faint paper texture.
# The story text itself, truncated to 900 characters with an ellipsis if longer.
# A trailing "Avoid:" clause that explicitly forbids colour, grayscale wash, painterly shading, photorealism, 3D rendering, borders, frames, mats, vignettes, modern comic or anime style, halftone dots, captions, readable text, watermarks, and signatures.

=== Image API and retries ===

The configured image model defaults to <code>gpt-image-1</code>; common typos such as <code>gpt-image-1.5</code> are normalised back to <code>gpt-image-1</code> at start-up. The output size is fixed at 1024×1024. Each generation tolerates up to three attempts (configurable via <code>IMAGE_RETRIES</code>) with exponential backoff starting at 1.5 seconds and capped at 10 seconds. If all attempts fail, a tiny placeholder GIF is written to disk under the name <code>story_<id>_placeholder.gif</code> and recorded as the story's image path so the front end always has something to display.

=== Post-processing ===

Successfully returned PNG bytes are passed through a Pillow-based post-processor that:

* Estimates the background colour from the four corner patches.
* Computes a difference image against a uniform background of that colour, raises its contrast, and finds the bounding box of meaningful content.
* Crops away any uniform border of more than ten pixels on any side, padded by two pixels to avoid clipping ink.
* Resizes the result back to 1024×1024 using Lanczos resampling and re-encodes as optimised PNG.

If Pillow is unavailable or any step fails, the original bytes are written through unchanged.

== Public interface ==

=== Home ===

The home page (<code>/</code>) renders the generation form together with a gallery of the five most recent stories that successfully produced an image. For unauthenticated visitors, the form is hidden and replaced by a rotating notice (one of twenty-two phrasings, selected from a SHA-256 hash of the visitor's IP and a six-hour bucket) when the visitor has already generated a story in the last 24 hours or when the site-wide guest cap has been reached. A footer-level statistics block displays the number of guest stories in the last 24 hours, the number of stories created by signed-in users in the same window, the all-time total, and the time elapsed since the most recent story.

=== Story detail ===

Each story is reachable at <code>/story/<id></code> and is publicly viewable regardless of authorship. The page presents the three sentences alongside the illustration; for the administrator, controls are exposed to regenerate the image (<code>/regenerate-image/<id></code>) or delete the story (<code>/story/<id>/delete</code>). A polling endpoint at <code>/api/story/<id>/status</code> returns a JSON document indicating whether a real image has yet been written, the URL of the image (or placeholder), and a flag distinguishing the two; the front end uses this to swap a placeholder GIF for the final image once background generation completes.

=== Archive ===

The archive (<code>/archive</code>) is a paginated chronological listing of all stories, nine per page, with previous/next navigation. There is no per-user filter — all stories are visible.

=== Authentication ===

<code>/login</code> accepts only the e-mail address configured in <code>ADMIN_EMAIL</code> and verifies the password against the stored Werkzeug hash. <code>/logout</code> ends the session. <code>/signup</code> is intentionally disabled.

=== Tagline rotation ===

The base template injects a "current tagline" string into every response. The selection is deterministic on the current 30-minute interval since the Unix epoch: the interval timestamp is used as a seed for the standard library random module, which then picks one of forty-five variant phrasings. All visitors served within the same half-hour see the same tagline; the tagline rotates without any database state.

== Rate limiting ==

Rate limiting is enforced for unauthenticated visitors only:

* '''Per-IP daily limit''': any IP that has produced a story within the last 24 hours is blocked from generating another (one story per visitor per day).
* '''Site-wide guest cap''': the total number of guest-authored stories in the last 24 hours must not exceed <code>GUEST_DAILY_CAP</code> (default 24). When the cap is reached, the form is hidden for all guests until older stories age out.

Both limits are evaluated at form render time (to hide the form) and at form submission time (to short-circuit the POST with a flashed warning and a redirect). Authenticated users have no rate limits and no per-IP enforcement.

The originating IP for limit accounting and for the <code>Story.ip_address</code> column is read from <code>X-Forwarded-For</code> when the request carries it (taking the first comma-separated value), and from <code>request.remote_addr</code> otherwise.

The application reads its configuration from environment variables loaded via python-dotenv:

== Deployment ==

The production deployment is an Ubuntu VPS running a systemd unit (<code>acbc.service</code>) that launches Gunicorn with three workers, bound to a Unix domain socket under the project directory. Nginx terminates HTTPS (provisioned by [[Let's Encrypt]] via Certbot), serves the <code>static/</code> directory directly with a one-year immutable cache header, and proxies all other requests to the Gunicorn socket. The service runs as the <code>django</code> system user out of <code>/home/django/acbc</code>.

== Security and authorisation ==

* Sign-ups are disabled; only the bootstrapped administrator account can authenticate.
* Login attempts for any e-mail other than <code>ADMIN_EMAIL</code> are rejected without a database query.
* The image-deletion helper refuses to remove any path that does not begin with <code>images/</code> or that, after canonicalisation, falls outside the configured upload folder, providing protection against path-traversal in stored data.
* Story deletion requires either the administrator session or ownership of the row; image regeneration requires the administrator session.
* The story-status JSON endpoint returns no user-identifying information beyond the public fields rendered on the story page.

== See also ==

* [[OpenAI]]
* [[Flask (web framework)]]
* [[H. P. Lovecraft]]
* [[Computational creativity]]
* [[Generative artificial intelligence]]

== References ==
{{reflist}}

Yusupov.cloud

2026-04-23T14:42:57Z

Mvuijlst: /* Subdomains and projects */

{{Infobox
| name = yusupov.cloud
| 1 url = https://yusupov.cloud
| 2 type = Personal web sites
| 3 owner = [[Michel Vuijlsteke]]
| 4 launched = 2025
| 5 current_status = Online
}}

'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref>

== Overview ==
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref>

== Subdomains and projects ==
Publicly visible projects include:

* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''[[A Cabinet of Brief Curiosities]]'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref>
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref>
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref>
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''[[Digest]]'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref>
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref>
* [https://nomos.yusupov.cloud nomos.yusupov.cloud] — ''[[Nomos]]'', a daily-generating archive of fictional Flemish administrative legislation, where real Vlaamse Codex documents are semantically shifted by GPT-5 into structurally faithful but entirely invented decrees, orders, and circulars. (Built with Wagtail 7/Django 6 per operator.)
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref>
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)

Operator-reported (not publicly discoverable at time of writing):

* skills.yusupov.cloud — a skills matrix application. (Per operator.)
* resources.yusupov.cloud — a simple resource planning calendar. (Per operator.)

== Technology ==
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" />

== Relation to the BBS ==
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref>

== See also ==
* [[Yusupov's House]] (1990s BBS)
* [[Michel Vuijlsteke]]

== References ==
{{Reflist}}

[[Category:Personal websites]]
[[Category:Belgian websites]]
[[Category:2025 establishments in Belgium]]

Nomos

2026-04-20T15:42:17Z

Mvuijlst:

{{Infobox
| 01_name = Nomos
| 02_url = https://nomos.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2026
| 05_genre = AI-generated legal document archive
| 06_language = Python
| 07_framework = [[Django]] / [[Wagtail]]
| 08_license = Proprietary
}}

'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."

== Technology stack ==

The application is built on Django with Wagtail as its content management framework and [[SQLite]] as its development database. Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch. The planned production deployment targets a Hetzner VPS behind [[Nginx]] with [[Gunicorn]] and [[PostgreSQL]].

== Data model ==

The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:

* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.
* ''publication_date'' (<code>DateField</code>) — set to the generation date.
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.
* ''revision_notes'' (<code>TextField</code>) — an LLM-generated summary of the subtle details introduced during the revision stage (see below); empty if the revision was rejected or produced no changes.

Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.

== Generation pipeline ==

Generation is driven by the <code>generate_decree</code> management command, which invokes a multi-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.

=== Stage 1: Structural sourcing ===

The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:

{| class="wikitable"
|-
! Codex type !! Mapped instrument
|-
| Decreet || DECREET
|-
| Besluit van de Vlaamse Regering || BESLUIT
|-
| Ministerieel besluit || BESLUIT
|-
| Omzendbrief || OMZENDBRIEF
|}

Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.

=== Topic inspiration ===

Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. To avoid reusing the same inspiration across runs, the scraper selects a random publication date from the past 90 days rather than always fetching the current edition. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.

=== Stage 2: Technical mutation ===

The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (the model is configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.

=== Stage 3: Administrative drafting ===

The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:

* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.
* If the source has no chapter divisions, the output must not introduce them.
* The total length must be comparable to the source.
* Content must be entirely original — only the form is emulated.

The output is requested as clean HTML using <code><h2></code>, <code><h3></code>, <code><p></code>, <code><ol></code>, and <code><li></code> elements, without a top-level heading (which is rendered separately on the page).

=== Stage 3b: Subtle revision ===

After drafting, the full text is sent to an additional API call that introduces ''defamiliarisation through precision'': the model is instructed to locate 3 to 5 passages dealing with execution, control, materials, or conditions, and to make a single local detail in each slightly more specific or procedural than necessary — for example, adding an unexpectedly precise measurement, a format requirement, or a procedural substep. The changes must be strictly additive; no text may be removed or truncated. Two programmatic guards run before the revision is accepted: an identity check rejects revisions that return the text unchanged, and a length check rejects revisions where the word count drops below 95% of the original (indicating deleted content). If a revision fails either guard, it is retried once. A separate validation call (the ''revision scrub'') then checks whether the revision shifted the main subject, introduced too many or contextually inappropriate details, or deleted content. If the revision is rejected or produced no changes, the unrevised text is used.

=== Stage 4: Juridical scrub ===

The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.

=== Stage 5: Generation notes ===

After successful validation, an API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon. If the subtle revision was accepted, a second call compares the pre- and post-revision texts word by word and produces a bullet-point list of the specific passages that were changed, stored as ''revision_notes''.

=== Text sanitisation ===

All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where some language models occasionally emit ASCII control characters in place of Unicode punctuation.

=== Persistence ===

The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.

== Anti-sameness system ==

To prevent the archive from becoming repetitive, the system employs two mechanisms:

* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.

== Public interface ==

=== Index page ===

The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').

=== Document detail page ===

Each decree page displays:

* A breadcrumb navigation link back to the index page.
* The full title as a top-level heading.
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).
* The full decree body rendered as rich text.

=== Visual design ===

The interface is very loosely inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.

== Administration ==

The application uses the standard Wagtail admin interface. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, generation notes, and revision notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.

The Django admin is available for lower-level database access.

== Logging ==

Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.

== Management commands ==

{| class="wikitable"
|-
! Command !! Purpose
|-
| <code>generate_decree</code> || Run the full generation pipeline: fetch seed, tilt title, draft decree, apply subtle revision, validate, generate notes, and publish as a Wagtail page
|-
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present
|}

== Deployment ==

The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.

== See also ==

* [[OpenAI]]
* [[Django (web framework)]]
* [[Wagtail (CMS)]]
* [[Vlaamse Codex]]
* [[Computational creativity]]
* [[Procedural generation]]

== References ==
{{reflist}}

Nomos

2026-04-20T15:41:00Z

Mvuijlst: /* Technology stack */

{{Infobox
| 01_name = Nomos
| 02_url = https://nomos.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2026
| 05_genre = AI-generated legal document archive
| 06_language = Python
| 07_framework = [[Django]] 6.0 / [[Wagtail]] 7.3
| 08_license = Proprietary
}}

'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."

== Technology stack ==

The application is built on Django 6.0.4 with Wagtail 7.3.1 as its content management framework and [[SQLite]] as its development database.<ref name="requirements">requirements.txt lists Django 6.0.4, wagtail 7.3.1, openai 2.32.0, requests 2.33.1, python-dotenv 1.2.2, beautifulsoup4 4.14.3, and Pillow 12.2.0.</ref> Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.8 loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch.

== Data model ==

The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:

* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.
* ''publication_date'' (<code>DateField</code>) — set to the generation date.
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.
* ''revision_notes'' (<code>TextField</code>) — an LLM-generated summary of the subtle details introduced during the revision stage (see below); empty if the revision was rejected or produced no changes.

Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.

== Generation pipeline ==

Generation is driven by the <code>generate_decree</code> management command, which invokes a multi-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.

=== Stage 1: Structural sourcing ===

The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:

{| class="wikitable"
|-
! Codex type !! Mapped instrument
|-
| Decreet || DECREET
|-
| Besluit van de Vlaamse Regering || BESLUIT
|-
| Ministerieel besluit || BESLUIT
|-
| Omzendbrief || OMZENDBRIEF
|}

Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.

=== Topic inspiration ===

Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. To avoid reusing the same inspiration across runs, the scraper selects a random publication date from the past 90 days rather than always fetching the current edition. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.

=== Stage 2: Technical mutation ===

The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (default model: GPT-5, configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<ref name="temperature">GPT-5 does not support custom temperature values. All API calls use the model's default temperature (1).</ref>

=== Stage 3: Administrative drafting ===

The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:

* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.
* If the source has no chapter divisions, the output must not introduce them.
* The total length must be comparable to the source.
* Content must be entirely original — only the form is emulated.

The output is requested as clean HTML using <code><h2></code>, <code><h3></code>, <code><p></code>, <code><ol></code>, and <code><li></code> elements, without a top-level heading (which is rendered separately on the page).

=== Stage 3b: Subtle revision ===

After drafting, the full text is sent to an additional API call that introduces ''defamiliarisation through precision'': the model is instructed to locate 3 to 5 passages dealing with execution, control, materials, or conditions, and to make a single local detail in each slightly more specific or procedural than necessary — for example, adding an unexpectedly precise measurement, a format requirement, or a procedural substep. The changes must be strictly additive; no text may be removed or truncated. Two programmatic guards run before the revision is accepted: an identity check rejects revisions that return the text unchanged, and a length check rejects revisions where the word count drops below 95% of the original (indicating deleted content). If a revision fails either guard, it is retried once. A separate validation call (the ''revision scrub'') then checks whether the revision shifted the main subject, introduced too many or contextually inappropriate details, or deleted content. If the revision is rejected or produced no changes, the unrevised text is used.

=== Stage 4: Juridical scrub ===

The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.

=== Stage 5: Generation notes ===

After successful validation, an API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon. If the subtle revision was accepted, a second call compares the pre- and post-revision texts word by word and produces a bullet-point list of the specific passages that were changed, stored as ''revision_notes''.

=== Text sanitisation ===

All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where GPT-5 occasionally emits ASCII control characters in place of Unicode punctuation.

=== Persistence ===

The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.

== Anti-sameness system ==

To prevent the archive from becoming repetitive, the system employs two mechanisms:

* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.

== Public interface ==

=== Index page ===

The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').

=== Document detail page ===

Each decree page displays:

* A breadcrumb navigation link back to the index page.
* The full title as a top-level heading.
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).
* The full decree body rendered as rich text.

=== Visual design ===

The interface is very loosely inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.

== Administration ==

The application uses the standard Wagtail admin interface. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, generation notes, and revision notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.

The Django admin is available for lower-level database access.

== Logging ==

Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.

== Management commands ==

{| class="wikitable"
|-
! Command !! Purpose
|-
| <code>generate_decree</code> || Run the full generation pipeline: fetch seed, tilt title, draft decree, apply subtle revision, validate, generate notes, and publish as a Wagtail page
|-
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present
|}

== Deployment ==

The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.

== See also ==

* [[OpenAI]]
* [[Django (web framework)]]
* [[Wagtail (CMS)]]
* [[Vlaamse Codex]]
* [[Computational creativity]]
* [[Procedural generation]]

== References ==
{{reflist}}

Nomos

2026-04-20T15:40:05Z

Mvuijlst:

{{Infobox
| 01_name = Nomos
| 02_url = https://nomos.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2026
| 05_genre = AI-generated legal document archive
| 06_language = Python
| 07_framework = [[Django]] 6.0 / [[Wagtail]] 7.3
| 08_license = Proprietary
}}

'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."

== Technology stack ==

The application is built on Django 6.0.4 with Wagtail 7.3.1 as its content management framework and [[SQLite]] as its development database.<ref name="requirements">requirements.txt lists Django 6.0.4, wagtail 7.3.1, openai 2.32.0, requests 2.33.1, python-dotenv 1.2.2, beautifulsoup4 4.14.3, and Pillow 12.2.0.</ref> Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.8 loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch. The planned production deployment targets a Hetzner VPS behind [[Nginx]] with [[Gunicorn]] and [[PostgreSQL]].

== Data model ==

The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:

* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.
* ''publication_date'' (<code>DateField</code>) — set to the generation date.
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.
* ''revision_notes'' (<code>TextField</code>) — an LLM-generated summary of the subtle details introduced during the revision stage (see below); empty if the revision was rejected or produced no changes.

Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.

== Generation pipeline ==

Generation is driven by the <code>generate_decree</code> management command, which invokes a multi-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.

=== Stage 1: Structural sourcing ===

The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:

{| class="wikitable"
|-
! Codex type !! Mapped instrument
|-
| Decreet || DECREET
|-
| Besluit van de Vlaamse Regering || BESLUIT
|-
| Ministerieel besluit || BESLUIT
|-
| Omzendbrief || OMZENDBRIEF
|}

Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.

=== Topic inspiration ===

Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. To avoid reusing the same inspiration across runs, the scraper selects a random publication date from the past 90 days rather than always fetching the current edition. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.

=== Stage 2: Technical mutation ===

The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (default model: GPT-5, configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<ref name="temperature">GPT-5 does not support custom temperature values. All API calls use the model's default temperature (1).</ref>

=== Stage 3: Administrative drafting ===

The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:

* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.
* If the source has no chapter divisions, the output must not introduce them.
* The total length must be comparable to the source.
* Content must be entirely original — only the form is emulated.

The output is requested as clean HTML using <code><h2></code>, <code><h3></code>, <code><p></code>, <code><ol></code>, and <code><li></code> elements, without a top-level heading (which is rendered separately on the page).

=== Stage 3b: Subtle revision ===

After drafting, the full text is sent to an additional API call that introduces ''defamiliarisation through precision'': the model is instructed to locate 3 to 5 passages dealing with execution, control, materials, or conditions, and to make a single local detail in each slightly more specific or procedural than necessary — for example, adding an unexpectedly precise measurement, a format requirement, or a procedural substep. The changes must be strictly additive; no text may be removed or truncated. Two programmatic guards run before the revision is accepted: an identity check rejects revisions that return the text unchanged, and a length check rejects revisions where the word count drops below 95% of the original (indicating deleted content). If a revision fails either guard, it is retried once. A separate validation call (the ''revision scrub'') then checks whether the revision shifted the main subject, introduced too many or contextually inappropriate details, or deleted content. If the revision is rejected or produced no changes, the unrevised text is used.

=== Stage 4: Juridical scrub ===

The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.

=== Stage 5: Generation notes ===

After successful validation, an API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon. If the subtle revision was accepted, a second call compares the pre- and post-revision texts word by word and produces a bullet-point list of the specific passages that were changed, stored as ''revision_notes''.

=== Text sanitisation ===

All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where GPT-5 occasionally emits ASCII control characters in place of Unicode punctuation.

=== Persistence ===

The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.

== Anti-sameness system ==

To prevent the archive from becoming repetitive, the system employs two mechanisms:

* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.

== Public interface ==

=== Index page ===

The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').

=== Document detail page ===

Each decree page displays:

* A breadcrumb navigation link back to the index page.
* The full title as a top-level heading.
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).
* The full decree body rendered as rich text.

=== Visual design ===

The interface is very loosely inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.

== Administration ==

The application uses the standard Wagtail admin interface. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, generation notes, and revision notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.

The Django admin is available for lower-level database access.

== Logging ==

Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.

== Management commands ==

{| class="wikitable"
|-
! Command !! Purpose
|-
| <code>generate_decree</code> || Run the full generation pipeline: fetch seed, tilt title, draft decree, apply subtle revision, validate, generate notes, and publish as a Wagtail page
|-
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present
|}

== Deployment ==

The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.

== See also ==

* [[OpenAI]]
* [[Django (web framework)]]
* [[Wagtail (CMS)]]
* [[Vlaamse Codex]]
* [[Computational creativity]]
* [[Procedural generation]]

== References ==
{{reflist}}

Nomos

2026-04-19T23:18:18Z

Mvuijlst: Created page with "{{Infobox | 01_name = Nomos | 02_url = https://nomos.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2026 | 05_genre = AI-generated legal document archive | 06_language = Python | 07_framework = Django 6.0 / Wagtail 7.3 | 08_license = Proprietary }} '''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each..."

{{Infobox
| 01_name = Nomos
| 02_url = https://nomos.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2026
| 05_genre = AI-generated legal document archive
| 06_language = Python
| 07_framework = [[Django]] 6.0 / [[Wagtail]] 7.3
| 08_license = Proprietary
}}

'''Nomos''' is a web application hosted at <code>nomos.yusupov.cloud</code> that generates and publishes AI-created Flemish administrative legislation. Each day, the system fetches a real document from the Vlaamse Codex open-data API, performs a semantic shift on its subject matter using a large language model, and produces a structurally faithful but entirely fictional legal text — a decree, ministerial order, or circular — that reads as if it were published in the ''Belgisch Staatsblad''. The generated documents are stored in a [[Wagtail (CMS)|Wagtail]] content management system and presented through a GOV.UK-inspired Dutch-language public interface. The name ''Nomos'' derives from the [[Ancient Greek|Greek]] word νόμος, meaning "law."

== Technology stack ==

The application is built on Django 6.0.4 with Wagtail 7.3.1 as its content management framework and [[SQLite]] as its development database.<ref name="requirements">requirements.txt lists Django 6.0.4, wagtail 7.3.1, openai 2.32.0, requests 2.33.1, python-dotenv 1.2.2, beautifulsoup4 4.14.3, and Pillow 12.2.0.</ref> Additional dependencies include the [[OpenAI]] Python client for language-model calls, [[Requests (software)|Requests]] for HTTP communication with the Vlaamse Codex API, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping title inspiration from the Belgisch Staatsblad, [[Pillow (imaging library)|Pillow]] as a Wagtail dependency, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.8 loaded from the jsDelivr CDN with subresource integrity hashes. All user interface text is in Dutch. The planned production deployment targets a Hetzner VPS behind [[Nginx]] with [[Gunicorn]] and [[PostgreSQL]].

== Data model ==

The data model uses Wagtail's page tree. A singleton <code>DecreeIndexPage</code> (limited to <code>max_count = 1</code>) serves as the parent of all generated documents. Each document is a <code>DecreePage</code> with the following fields:

* ''instrument'' — one of four types: Decreet, Besluit, Omzendbrief, or Reglement.
* ''full_title'' (<code>TextField</code>) — the complete title, unlimited in length. The standard Wagtail ''title'' field (255-character limit) holds a truncated copy for internal use.
* ''body'' (<code>RichTextField</code>) — the full HTML text of the generated legislation.
* ''publication_date'' (<code>DateField</code>) — set to the generation date.
* ''status'' — either ''Geldig'' (valid) or ''Gearchiveerd'' (archived); defaults to Geldig.
* ''seed_id'' (<code>IntegerField</code>, unique, nullable) — the numeric ID of the source document in the Vlaamse Codex, used for deduplication to ensure no seed is used twice.
* ''seed_reference'' (<code>URLField</code>) — direct API link to the source document.
* ''seed_document'' (<code>TextField</code>) — human-readable label recording the type and title of the source document.
* ''generation_notes'' (<code>TextField</code>) — an LLM-generated human-readable summary describing how the generated document differs from its source.

Full-text search is indexed on ''full_title'' and ''body'' via Wagtail's database search backend.

== Generation pipeline ==

Generation is driven by the <code>generate_decree</code> management command, which invokes a five-stage pipeline implemented in <code>nomos/services/generator.py</code>. The pipeline retries up to three times if validation fails.

=== Stage 1: Structural sourcing ===

The <code>pick_random_seed()</code> function in <code>nomos/services/codex.py</code> fetches up to 200 recent documents from the Vlaamse Codex open-data API (<code>codex.opendata.api.vlaanderen.be</code>). Candidates are filtered to four allowed document types:

{| class="wikitable"
|-
! Codex type !! Mapped instrument
|-
| Decreet || DECREET
|-
| Besluit van de Vlaamse Regering || BESLUIT
|-
| Ministerieel besluit || BESLUIT
|-
| Omzendbrief || OMZENDBRIEF
|}

Documents whose <code>seed_id</code> already exists in the database are excluded. The remaining candidates are grouped by type, and a weighted random selection favours types that have been used less frequently in the preceding seven days. For each recently used instrument, the selection weight is reduced by two per occurrence (minimum weight of 1). Once a seed is selected, the system fetches its full detail and chapter/section structure from the API.

=== Topic inspiration ===

Before generating, the pipeline scrapes the ''Belgisch Staatsblad'' website (<code>ejustice.just.fgov.be</code>) for a random document title to use as thematic inspiration. Federal and national references in the scraped title are replaced with Flemish equivalents using a table of 17 substitution pairs — for example, "Federale Overheidsdienst" becomes "Vlaamse overheidsdienst," "Koninklijk besluit" becomes "Besluit van de Vlaamse Regering," and "België" becomes "Vlaanderen." If the scrape fails, generation proceeds without a topic hint.

=== Stage 2: Technical mutation ===

The seed document's title (''opschrift'') is sent to the OpenAI Chat Completions API (default model: GPT-5, configurable via the <code>OPENAI_MODEL</code> environment variable). The system prompt instructs the model to behave as an expert in Flemish legislation and to perform a semantic shift: replace the core subject with a plausible but fictional technical equivalent while preserving the exact grammatical structure and bureaucratic tone. If a topic hint was obtained from the Belgisch Staatsblad, it is included as thematic guidance.<ref name="temperature">GPT-5 does not support custom temperature values. All API calls use the model's default temperature (1).</ref>

=== Stage 3: Administrative drafting ===

The tilted title, the seed document's full text (up to 4,000 characters), and its structural outline are sent to a second API call. The system prompt instructs the model to act as a legislative jurist of the Flemish government and to rewrite the source document about the new subject. Strict structural parity rules are enforced:

* The output must contain the exact same number of chapters (''hoofdstukken''), sections (''afdelingen''), and articles (''artikelen'') as the source.
* If the source has no chapter divisions, the output must not introduce them.
* The total length must be comparable to the source.
* Content must be entirely original — only the form is emulated.

The output is requested as clean HTML using <code><h2></code>, <code><h3></code>, <code><p></code>, <code><ol></code>, and <code><li></code> elements, without a top-level heading (which is rendered separately on the page).

=== Stage 4: Juridical scrub ===

The generated HTML is submitted to a validation call in which the model acts as a quality controller. It checks for the presence of narrative, poetic, or metaphorical language; references to fiction, imagination, or art; and humor or irony. Documents that do not read as authentic administrative texts are rejected with a reason. If all three attempts fail validation, the pipeline raises an error.

=== Stage 5: Generation notes ===

After successful validation, a final API call generates a human-readable summary of the transformation. The model is instructed to act as an archivist and to describe in one or two plain-language sentences how the new document's subject differs from the original, without technical jargon.

=== Text sanitisation ===

All generated text is passed through a sanitisation function that strips Unicode control characters (C0/C1 range, excluding newlines and tabs), applies NFC normalisation, removes empty list items and orphaned list wrappers from the HTML, and cleans whitespace artifacts. This addresses a known issue where GPT-5 occasionally emits ASCII control characters in place of Unicode punctuation.

=== Persistence ===

The <code>save_decree()</code> function in <code>nomos/services/storage.py</code> creates a <code>DecreePage</code> as a child of the <code>DecreeIndexPage</code>. The slug is derived from the title (truncated to 200 characters) and made unique by appending a numeric suffix if necessary. The page is published immediately via Wagtail's <code>save_revision().publish()</code> mechanism. The publication date is set to the current date and the status defaults to ''Geldig''.

== Anti-sameness system ==

To prevent the archive from becoming repetitive, the system employs two mechanisms:

* '''Seed deduplication''': the <code>seed_id</code> field (unique integer) ensures that no Vlaamse Codex document is used as a source more than once. Before selecting a seed, the pipeline queries all existing <code>seed_id</code> values and excludes them from the candidate pool.
* '''Type-weighted selection''': the <code>_get_recent_type_counts()</code> function counts how many times each instrument type has appeared in the last seven days. Types with higher recent counts receive proportionally lower selection weights, encouraging the system to alternate between decrees, orders, and circulars.

== Public interface ==

=== Index page ===

The index page lists all published <code>DecreePage</code> children ordered by publication date (newest first). A search bar and an instrument type dropdown filter are provided. Search uses Wagtail's database search backend, querying the ''full_title'' and ''body'' fields. The type filter applies an exact match on the ''instrument'' field. Each list entry displays the full title, publication date, instrument type label, and a colour-coded status tag (green for ''Geldig'', grey for ''Gearchiveerd'').

=== Document detail page ===

Each decree page displays:

* A breadcrumb navigation link back to the index page.
* The full title as a top-level heading.
* A GOV.UK-style summary list with key/value rows for document type, publication date, and status (rendered as a tag badge).
* The full decree body rendered as rich text.

=== Visual design ===

The interface is inspired by the [[GOV.UK Design System]]. The base template features a dark masthead with a yellow (<code>#ffe615</code>) accent border, the site name "Nomos" as a navigation link, and a dark/light mode toggle button. The toggle uses CSS custom properties for theming and persists the user's preference in <code>localStorage</code>. In dark mode, the masthead shifts to <code>#1a1a1a</code>, links become lighter, and status tag colours are adjusted for contrast. A responsive layout collapses the summary list key/value pairs into a single column below 576px.

== Administration ==

The application uses the standard Wagtail admin interface at <code>/admin/</code>. <code>DecreePage</code> content panels expose the instrument type, full title, body, publication date, and status. A separate "Generatie-informatie" settings panel groups the seed ID, seed reference URL, seed document description, and generation notes — metadata that is recorded automatically during generation and is accessible to editors but not displayed on the public site.

The Django admin is available at <code>/django-admin/</code> for lower-level database access.

== Logging ==

Application logging is configured with two handlers: console output and a rotating file log (<code>nomos.log</code> in the project root). The <code>nomos</code> logger is set to <code>INFO</code> level and records each pipeline stage (seed selection, title tilting, drafting, validation, publication) with document identifiers and truncated titles.

== Management commands ==

{| class="wikitable"
|-
! Command !! Purpose
|-
| <code>generate_decree</code> || Run the full five-stage pipeline: fetch seed, tilt title, draft decree, validate, generate notes, and publish as a Wagtail page
|-
| <code>setup_index_page</code> || Create the <code>DecreeIndexPage</code> as the site root (idempotent); removes the default Wagtail welcome page if present
|}

== Deployment ==

The planned production deployment targets <code>nomos.yusupov.cloud</code> on a Hetzner VPS running [[Nginx]] as a reverse proxy, [[Gunicorn]] as the WSGI application server, and [[PostgreSQL]] as the production database (replacing SQLite). TLS is to be provided by [[Let's Encrypt]] via Certbot. Daily generation is to be scheduled via cron calling <code>python manage.py generate_decree</code>.

== See also ==

* [[OpenAI]]
* [[Django (web framework)]]
* [[Wagtail (CMS)]]
* [[Vlaamse Codex]]
* [[Computational creativity]]
* [[Procedural generation]]

== References ==
{{reflist}}

Yusupov.cloud

2026-04-19T23:18:06Z

Mvuijlst: /* Subdomains and projects */

{{Infobox
| name = yusupov.cloud
| 1 url = https://yusupov.cloud
| 2 type = Personal web sites
| 3 owner = [[Michel Vuijlsteke]]
| 4 launched = 2025
| 5 current_status = Online
}}

'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref>

== Overview ==
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref>

== Subdomains and projects ==
Publicly visible projects include:

* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref>
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref>
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref>
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''[[Digest]]'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref>
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref>
* [https://nomos.yusupov.cloud nomos.yusupov.cloud] — ''[[Nomos]]'', a daily-generating archive of fictional Flemish administrative legislation, where real Vlaamse Codex documents are semantically shifted by GPT-5 into structurally faithful but entirely invented decrees, orders, and circulars. (Built with Wagtail 7/Django 6 per operator.)
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref>
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)

Operator-reported (not publicly discoverable at time of writing):

* skills.yusupov.cloud — a skills matrix application. (Per operator.)
* resources.yusupov.cloud — a simple resource planning calendar. (Per operator.)

== Technology ==
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" />

== Relation to the BBS ==
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref>

== See also ==
* [[Yusupov's House]] (1990s BBS)
* [[Michel Vuijlsteke]]

== References ==
{{Reflist}}

[[Category:Personal websites]]
[[Category:Belgian websites]]
[[Category:2025 establishments in Belgium]]

Michel Vuijlsteke

2026-04-19T21:15:40Z

Mvuijlst: /* Volunteering */

{{Infobox
| name = Michel Vuijlsteke
| image = Michel Vuijlsteke, Gentse Feesten 2025.jpg
| 01 Born = 27 August 1970, Ghent, Belgium
| 03 Occupation = User experience architect; writer; former BBS/Internet early adopter
| 04 Active = 1970–present
| 05 Employer(s) = Ghent University, [[Albania for King Zog Committee]]
| 06 Website = [https://blog.zog.org/ blog.zog.org]
}}

'''Michel Vuijlsteke''' (born 27 August 1970) is a Belgian user experience architect, writer and former Internet early adopter.

== Biography ==
Vuijlsteke was born in Ghent and studied law, but did not pursue a legal career.<ref name="cv">Michel Vuijlsteke, ''CV Michel Vuijlsteke'', 2025.</ref> In 1992 he participated in the pilot program of the [[Central European University]] in Prague, an experience he later summarized as leaving “mainly culinary impressions.”<ref name="cv" /> In 2016 he obtained a cooking diploma at the [[Spermalie Hotel School]] in Ghent, formalising a long-standing interest in food.<ref name="cv" />

He lives in Ghent, is married and has four children; two cats also feature prominently in the household logistics.<ref name="cv" />

== Career ==
Vuijlsteke co-founded [[Netpoint]] in 1995, one of the early Internet companies in Belgium, which built websites for a variety of clients.<ref name="cv" /> After Netpoint’s acquisition by [[Unit4Agresso]] and subsequent renaming to ''Amercom België'' in 2000, he served as managing director.<ref name="cv" />

He later worked at the [[College of Europe]] and joined [[Namahn]] (2006–2010), contributing to projects in information architecture for clients including SD Worx, Belgacom and KBC.<ref name="cv" /> From 2010 to 2018 he was product owner of [[Adhese]], an online advertising platform operating in the European ad-tech niche.<ref name="cv" />

Between 2018 and 2022 he returned to [[Namahn]], mainly working on user experience architecture at [[EUROCONTROL]], where he contributed to applications used in European airspace management.<ref name="cv" /><ref name="linkedin">"Michel Vuijlsteke – LinkedIn profile". Available at: https://www.linkedin.com/in/mvuijlst/</ref>

Vuijlsteke is currently employed at [[Ghent University]], where he heads the team responsible for user experience and interface development across university-wide web platforms. His role combines coordination of front-end development with UX design leadership.<ref name="cv" />

== Volunteering ==
* At [[cirQ]] he contributed to productions such as ''Datakamp'' (2017), ''Batacratie'' (2018), ''Batastunt'' (2019) and ''cirQ TV'' during the COVID lockdown. He returned to cirQ in 2025 for ''Bataknar 2.0''<ref name="cv" />
* At [[Companie Cordial]] (then ''Refu Interim'') he built a volunteer-management application and is a member of the Board<ref name="cv" />
* For [[Gentblogt]] he wrote articles and took photos for many years, later serving as chair of the non-profit.<ref name="cv" />
* For [[Doorway Productions]] he worked as a screenwriter and script doctor.<ref name="cv" />

== Online presence ==
Since 2002 Vuijlsteke writes at least daily posts on blog.zog.org, mixing technology, personal notes and commentary, which he once called “a diary that got out of hand.”<ref name="about">"Over mezelf", Zog.org. Available at: https://blog.zog.org/about</ref> Beyond the blog, he operates personal and experimental websites across multiple domains, among others: [[yusupov.cloud]], [https://moosedept.org moosedept.org], [[otlet.cloud]], [https://blaffeture.net blaffeture.net], [https://tsuk.org tsuk.org], [https://genea.cloud genea.cloud], and [https://vuijlsteke.net vuijlsteke.net].

== Association with the Moose Dept. ==
In addition to his professional and personal writing, Vuijlsteke has been informally connected with the [[Moose Dept.]], a subdivision of the [[Albania for King Zog Committee]]. Since at least 1989 he has occasionally signed correspondence as “Grand Mufti, Moose Dept.,” a title referenced in later interviews.<ref>Barker, W., interview with M. Vuijlsteke, 1998, privately circulated typescript.</ref><ref>Anonymous interview with M. Vuijlsteke, 2007, recorded in the AKZ Oral Archive, Ghent.</ref>

The relationship between these playful titles and his broader digital projects has been the subject of some scholarly commentary.<ref>Duquesne, M., ''Domestic Esoterica: Everyday Surfaces of Secret Societies'' (''Proceedings of Contemporary Folklore'', vol. 7, 2018), pp. 52–67.</ref>

== Languages ==
Vuijlsteke speaks Dutch and French as mother tongues, English fluently, and has working knowledge of German, Italian and Spanish.<ref name="cv" />

== References ==
<references />

Digest

2026-04-19T20:28:35Z

Mvuijlst:

{{Infobox
| 01_name = Digest
| 02_url = https://digest.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated recipe application
| 06_language = Python
| 07_framework = [[Django]] 5.2
| 08_license = Proprietary
}}

'''Digest''' is a web application hosted at <code>digest.yusupov.cloud</code> that generates and publishes AI-created recipes inspired by current news articles. Each day, the system fetches articles from the ''New York Times'' RSS feed, selects two at random, and uses them as creative prompts for a large language model to invent a realistic, seasonally appropriate recipe. A companion image-generation pipeline produces editorial-quality food photography for each recipe using a composition diversity system that enforces visual variety across generations. The site's tagline is "Daily recipes inspired by the news."

== Technology stack ==

The application is built on Django 5.2 with [[SQLite]] as its database.<ref name="requirements">requirements.txt in the project repository lists Django ≥5.2, Pillow ≥10, openai ≥1.40, python-dotenv ≥1.0, gunicorn ≥21, requests ≥2.31, beautifulsoup4 ≥4.12, and markdown ≥3.5.</ref> It is deployed behind [[Nginx]] with [[Gunicorn]] on an Ubuntu server running two synchronous workers on port 8001. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing and optimisation, the [[OpenAI]] Python client for language-model and image-generation calls, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping recipe inspiration from external sites, [[Markdown (markup language)|python-markdown]] for rendering recipe inspiration text, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.3 with Bootstrap Icons, and typography is set in Roboto (body), Roboto Serif (headings), and Roboto Slab (accents), loaded from Google Fonts.

== Data model ==

=== Recipe ===

The central model is <code>Recipe</code>, which stores:

* ''name'', ''slug'' (auto-generated), ''intro'' (short paragraph), ''inspiration'' (120–200-word Markdown text linking to the source articles), and ''visual_description'' (a single sentence describing the plated dish for use as an image-generation prompt).
* ''hero_image'' (uploaded to <code>recipes/hero/</code>), ''base_servings'' (default 4), ''prep_time_minutes'', ''cook_time_minutes'', ''is_featured'' (boolean), and automatic ''created_at'' / ''updated_at'' timestamps.
* A many-to-many relationship to <code>RecipeType</code> (one of ten canonical types: Main, Salad, One-pan, Starter, Cold dish, Soup, Side dish, Dessert, Breakfast, or Snack).

=== Structured ingredients ===

Ingredients are organised into optional titled groups (e.g. "Dough", "Sauce") via <code>IngredientGroup</code>. Each <code>Ingredient</code> within a group has:

* A foreign key to <code>IngredientName</code> (a canonical master list of deduplicated ingredient names, each with a slug and an optional foreign key to <code>IngredientCategory</code>).
* A ''quantity'' (decimal), a foreign key to <code>Unit</code> (with ''name_singular'' and ''name_plural'', e.g. "cup"/"cups", "clove"/"cloves", "g"/"g"), an optional ''note'' (e.g. "finely diced", "zested then juiced"), and an ''order'' field.
²
<code>IngredientCategory</code> supports arbitrary hierarchy via a self-referencing parent foreign key, enabling structures such as Fruit → Citrus → Lemon.

=== Instructions ===

Recipe steps are stored as <code>Direction</code> rows, optionally grouped into titled <code>InstructionGroup</code> sections. Both models carry an ''order'' field for sequencing.

=== Image prompt history ===

Every AI image generation attempt is recorded in <code>RecipeImagePrompt</code>, which stores the full prompt text, the visual description, five composition dimension values (camera angle, framing, setting, lighting style, mood), a ''was_centered'' boolean, and a creation timestamp. This history is queried by the composition diversity system to enforce variety across successive hero images.

== Recipe generation pipeline ==

Recipe generation is driven by Django management commands and a service layer in <code>recipes/services/</code>.

=== Inspiration sourcing ===

Two management commands gather external inspiration:

* <code>fetch_nyt_inspiration</code> downloads the current ''New York Times'' front page image (saved to <code>static/img/nyt/</code>) and fetches articles from the NYT homepage RSS feed. It also manages a weighted variation-rotation state file (<code>data/nyt_variation_state.json</code>) that tracks which recipe types, cooking techniques, proteins, bases, and connection styles have been used recently.
* <code>fetch_recipe_inspiration</code> scrapes the ''NYT Cooking'' and ''Dagelijkse Kost'' (VRT) websites for reference recipes, extracting titles, descriptions, and ingredient lists from embedded JSON-LD <code>Recipe</code> markup. Results are written to <code>data/inspiration.json</code>.

A PowerShell script (<code>scripts/schedule_inspiration_refresh.ps1</code>) automates the inspiration refresh on a three-day cycle via Windows Task Scheduler.

=== Variation rotation ===

To prevent repetitive output, the system maintains weighted "draw bags" for five dimensions of recipe variety:

{| class="wikitable"
|-
! Dimension !! Pool size !! Examples
|-
| Recipe type || 10 || Main (weight 7), One-pan (3), Soup (3), Salad (2), …
|-
| Technique || 13 || pan-searing (3), roasting (3), stir-frying (2), sous vide (2), …
|-
| Protein || 9 || chicken (3), beef (3), fish (2), shellfish (2), mushrooms (2), …
|-
| Base || 8 || rice (3), pasta (3), potatoes (3), flatbread (2), noodles (2), …
|-
| Connection style || 10 || geographical (10), seasonal (4), historical (3), narrative (3), …
|}

Each dimension uses a weighted bag: items are added with multiplicity proportional to their weight, and one is drawn per run without replacement. When the bag empties it is refilled. Immediate repeats of the same pick are avoided when alternatives exist. State is persisted to JSON between runs.

=== Prompt construction ===

The <code>gen_recipe_from_nyt</code> command orchestrates the full pipeline:

# Two articles are selected from the RSS feed, filtered against a usage log (<code>data/inspiration_usage.json</code>) to avoid reuse.
# Variation picks are drawn for recipe type, technique, protein, base, and connection style.
# A structured prompt is assembled, instructing the model to act as a professional recipe developer, invent one realistic recipe that a home cook in Belgium can make using seasonally appropriate ingredients, stay within 75 minutes total time, and use the drawn picks. The prompt includes both article summaries and one extra recipe reference from the inspiration pool (with a 2:1 preference for VRT over NYT sources).
# An ingredient diversity constraint is injected: the system queries the last seven recipes' ingredients and flags any non-staple ingredient that appears in three or more of them. Flagged ingredients are added to the prompt as a hard exclusion list ("MUST NOT be used in this recipe"). A curated set of approximately 40 pantry staples — salt, oil, butter, garlic, onion, flour, water, lemon, parsley, and similar basics — is exempt from this check. The constraint is self-correcting: once a previously overused ingredient drops below the threshold it is automatically unblocked.
# The prompt is appended with strict JSON schema instructions specifying the output format: name, intro, inspiration, visual description, servings, times, typed ingredient groups with quantities and units, titled instruction groups, and a recipe type from the canonical list.

=== Text generation ===

The <code>OpenAIRecipeGenerator</code> service class sends the prompt to the OpenAI Responses API. The default model is GPT-5, configurable via environment variable. The system prompt instructs the model to behave as a seasoned chef with Michelin-starred and home-cooking experience, and enforces detailed culinary realism rules: precise quantities ("325g not 300g"), specified heat levels and sensory cues, timing ranges, prep details in ingredient notes, assertive seasoning with salt quantities, and instructions that read like a tested recipe.<ref name="system-prompt">The system prompt in <code>recipes/services/openai_recipes.py</code> specifies: "You are a seasoned chef and food editor with 20 years of Michelin-starred and home-cooking experience."</ref>

The API call requests JSON object output format. If the model or SDK does not support the <code>text</code> format parameter, the call falls back to unformatted output. Similarly, if the model does not support the <code>temperature</code> parameter (as is the case with GPT-5), the call automatically retries without it.

=== Validation ===

After generation, the recipe JSON is passed through a self-critique step: a second, cheaper API call instructs the model to review the recipe for culinary realism — checking that quantities make sense for the serving count, that cook times are realistic for the described technique, that no ingredients mentioned in the instructions are missing from the ingredient list, and that prep notes match the steps. The model returns a corrected JSON object or the original if no issues are found. If the critique call fails, the original is used unchanged.

=== Inspiration rewriting ===

After generation, the pipeline inspects the <code>inspiration</code> field. If it is shorter than 120 words, contains the forbidden words "article" or "news," or lacks Markdown anchor links to both source articles, a rewrite call asks the model to produce a 120–200-word vivid text weaving concrete ideas from both sources, ending with properly formatted attribution links.

=== Persistence ===

The <code>save_recipe_from_data</code> function maps the generated JSON to Django models within a single transaction:

* Creates the <code>Recipe</code> row with all scalar fields.
* Resolves recipe types against the canonical allowed list (by slug); creates missing <code>RecipeType</code> rows only for canonical names.
* Creates <code>IngredientGroup</code>, <code>Ingredient</code>, <code>IngredientName</code> (get-or-create by slug), and <code>Unit</code> (get-or-create by singular name) rows.
* Normalises instruction groups: merges untitled single-step groups into one, handles multiple JSON shapes (list of strings, list of dicts with <code>step</code> or <code>text</code> keys, plain text blobs), and filters artifacts shorter than three characters.
* Triggers hero image generation (non-fatal by default; controlled by the <code>OPENAI_IMAGE_REQUIRED</code> setting).

=== Text sanitisation ===

All generated text fields are passed through a sanitisation function before database persistence. This addresses a known issue where certain language models (notably GPT-5) emit ASCII control characters in place of Unicode punctuation — for example, <code>U+0019</code> followed by a digit where an en-dash should appear, or <code>U+0019</code> followed by <code>s</code> where a right single quotation mark is intended. The sanitisation function applies pattern-based corrections for these control character sequences, normalises Unicode dashes and quotation marks to their ASCII equivalents, and strips any remaining C0 control characters. The function is applied to the recipe name, intro, inspiration, visual description, all ingredient names and notes, and all instruction steps and group titles.

== Hero image generation ==

Image generation is a three-layer system: a low-level OpenAI client, a composition diversity engine, and a high-level orchestrator.

=== Image API client ===

<code>OpenAIImageGenerator</code> calls the OpenAI image generation endpoint (model <code>gpt-image-1.5</code> by default, configurable via <code>OPENAI_IMAGE_MODEL</code>) and returns raw PNG bytes decoded from the base64 API response. The default output size is 1536×1024 (landscape), matching typical food photography framing.<ref name="image-size">The default size is set in <code>recipes/services/openai_images.py</code> and can be overridden via the <code>OPENAI_IMAGE_SIZE</code> setting.</ref>

=== Composition diversity ===

The <code>FoodPhotoPromptGenerator</code> enforces visual variety across successive hero images by selecting compositions from the Cartesian product of five dimensions:

{| class="wikitable"
|-
! Dimension !! Count !! Examples
|-
| Camera angle || 8 || overhead flat lay, 45° oblique, eye-level, low side, macro detail, handheld documentary, three-quarter view, tilted dutch angle
|-
| Framing || 11 || wide with negative space, tight crop, off-center, partial out-of-frame, action/utensil-in-motion, ingredient close-up, shallow depth-of-field, symmetrical centered, diagonal composition, …
|-
| Setting || 11 || white studio, stainless pro kitchen, home counter, picnic/outdoor, dark restaurant table, marble surface, wooden cutting board, concrete backdrop, vintage tile, slate serving board, …
|-
| Lighting || 12 || hard sun, soft window, dramatic low-key, warm tungsten, backlit steam, golden hour, bounce fill, rim lighting, diffused overhead, candlelight, …
|-
| Mood || 12 || modern editorial, rustic farmhouse, minimalist, street-food, celebratory, cozy homestyle, vibrant colorful, moody atmospheric, fresh healthy, indulgent decadent, …
|}

This yields approximately 13,000 possible combinations. The selection algorithm:

# Generates all combinations and shuffles them using a cryptographically secure random source (<code>secrets.SystemRandom</code>).
# Filters candidates against: angle+setting pairs used in the last 30 days (banned), recent compositions within the history window (must differ in at least 3 of 5 dimensions), and a centering constraint (no centered composition if the previous image was centered).
# Falls back to progressively relaxed criteria if no perfect match exists.

=== Prompt construction ===

The selected composition is assembled into a detailed image prompt that specifies:

* The dish name and a one-sentence visual description.
* A style directive requesting "high-end editorial food photography for a cookbook or food magazine," with natural imperfections — "slight char marks, a drip of sauce, steam rising, herbs slightly wilted from heat."
* The five composition dimensions.
* Food styling details: realistic portion sizes, contextual props (linen napkin, scattered herbs, olive oil drizzle), visible textures (crispy skin, glossy glaze, charred edges), and a natural, non-oversaturated colour palette.
* Hard constraints: photorealistic only (no illustrations), no text or watermarks, no human faces or hands, and avoidance of rustic wood unless specified.

=== Persistence and attachment ===

Each generation creates a <code>RecipeImagePrompt</code> record storing all composition metadata. The generated PNG is attached to the recipe's <code>hero_image</code> field via Django's file storage. On-demand regeneration is available through the upload-image view, which also accepts manual image uploads (validated for JPEG, PNG, or WebP content type, maximum 20 MB, downscaled to 2048px and converted to JPEG at 85% quality).

== Public interface ==

=== Home page ===

The home page displays a featured recipe (hero image with title, intro, and call-to-action) and a grid of the seven most recent recipes as cards with 1:1 hero images. The layout is responsive: seven columns on desktop, three on tablet, two on mobile.

=== Recipe detail ===

Each recipe page (<code>/r/<slug>/</code>) features:

* A hero section with the image (left, 1:1 aspect ratio, rounded shadow) and title, intro, recipe type badges (linked to type pages), and time estimates (prep, cook, total) with ingredient count.
* A sticky sidebar with the ingredient list, organised by groups, with a servings control (−/+ buttons and direct input). Ingredient quantities are scaled client-side using the formula <code>scaled_qty = base_qty × (servings / base_servings)</code>, with unit pluralisation logic handling irregular forms (cup/cups, clove/cloves).
* Numbered instructions below, optionally grouped by titled sections.
* For authenticated users: edit, delete, and regenerate-image controls, plus a collapsible display of the raw image generation prompt.

The page emits [[Schema.org]] <code>Recipe</code> JSON-LD markup (name, image, prep/cook times in ISO 8601 duration format, yield, ingredient list, and <code>HowToStep</code> instructions), Open Graph meta tags, and a canonical URL.

=== Browsing ===

The site provides several browsing views, all with file-based caching:

* ''Meals'' (<code>/types/</code>): lists recipe types with the latest example recipe for each, linking to paginated type detail pages (12 recipes per page).
* ''Ingredients'' (<code>/ingredients/</code>): a master ingredient index with recipe usage counts, linking to paginated ingredient detail pages (12 recipes per page).
* ''Categories'' (<code>/categories/</code>): a hierarchical ingredient category tree with subcategories and ingredient counts, linking to paginated category detail pages (24 items per page).
* ''Calendar'' (<code>/year/</code>): a year-view calendar displaying all twelve months in a responsive grid. Days on which at least one recipe was published (across all years) are rendered as hyperlinks to a day detail page (<code>/year/MM/DD/</code>), which lists all recipes for that month-and-day combination regardless of year, using the same card layout and pagination as the type detail pages.
* ''About'' (<code>/about/</code>): a static information page.

=== Theme ===

The site supports light and dark colour themes, toggled via a moon/sun icon button in the navigation bar and persisted in <code>localStorage</code>. Dark mode uses a <code>#121212</code> background, <code>#e6e6e6</code> text, and yellow (<code>rgb(255, 193, 7)</code>) accent links, with high-contrast card and list-group styling.

== Administration ==

The Django admin interface is customised with:

* <code>RecipeAdmin</code>: list display with name, servings, times, creation date, and featured flag; search across name, intro, and inspiration; inline editing of instruction groups and directions; horizontal filter for recipe types.
* <code>IngredientNameAdmin</code>: list with category and recipe count; bulk actions for assigning or removing categories, and for merging duplicate ingredient names (which transfers all ingredient references to the merge target).
* <code>IngredientCategoryAdmin</code>: hierarchical display with direct and recursive ingredient counts; inline subcategory editing; a custom overview view showing category statistics; and an action for moving ingredients between subcategories.

Custom admin templates provide forms for category assignment (<code>assign_category.html</code>), category overview (<code>category_overview.html</code>), ingredient merging (<code>merge_ingredients.html</code>), and ingredient moving (<code>move_ingredients.html</code>).

== SEO and caching ==

Four sitemap classes are registered at <code>/sitemap.xml</code>:

{| class="wikitable"
|-
! Sitemap !! Items !! Priority !! Frequency
|-
| Recipes || All recipes || 0.9 || daily
|-
| Recipe types || All types || 0.6 || weekly
|-
| Ingredients || All ingredient names || 0.5 || weekly
|-
| Static pages || home, about, types index, ingredients index || 0.4 || weekly
|}

A <code>robots.txt</code> view allows all crawlers and includes the sitemap URL. Django's file-based cache is used throughout, with cache timeouts ranging from 5 minutes (recipe detail for anonymous users) to 1 hour (ingredient and category indexes). Cache is invalidated wholesale via <code>post_save</code>, <code>post_delete</code>, and <code>m2m_changed</code> signals on the <code>Recipe</code> model.

== Deployment ==

The application is deployed on an Ubuntu VPS behind Nginx, which serves static files and media directly and proxies application requests to Gunicorn on port 8001. The Gunicorn configuration specifies two synchronous workers, a 180-second request timeout (to accommodate long-running OpenAI image generation calls), and request-count-based worker recycling (1000 requests with ±100 jitter). Nginx is configured with <code>proxy_read_timeout 300s</code> for the same reason. TLS is provided by [[Let's Encrypt]] via Certbot.

== Middleware ==

A custom <code>ClacksOverheadMiddleware</code> adds the <code>X-Clacks-Overhead: GNU Terry Pratchett</code> header to all responses, as a tribute to [[Terry Pratchett]].

== Management commands ==

{| class="wikitable"
|-
! Command !! Purpose
|-
| <code>gen_recipe</code> || Generate a single recipe from a free-text topic
|-
| <code>gen_recipe_from_file</code> || Create a recipe from a JSON file matching the output schema
|-
| <code>gen_recipe_from_nyt</code> || Full pipeline: fetch NYT articles, build prompt with variation rotation, generate recipe, optionally save to database
|-
| <code>fix_garbled_text</code> || One-time cleanup of control-character artifacts in existing recipes
|-
| <code>fetch_nyt_inspiration</code> || Download NYT front page and fetch RSS articles; manage variation state
|-
| <code>fetch_recipe_inspiration</code> || Scrape NYT Cooking and Dagelijkse Kost for reference recipes
|-
| <code>create_ingredient_categories</code> || Seed the hierarchical ingredient category tree
|-
| <code>auto_categorize_ingredients</code> || Pattern-matching assignment of categories to uncategorised ingredients
|-
| <code>find_duplicate_ingredients</code> || Detect and merge duplicate ingredient names
|-
| <code>normalize_instructions</code> || Post-migration cleanup for instruction group schema
|-
| <code>seed_recipes</code> || Populate the database with sample recipes
|}

== See also ==

* [[OpenAI]]
* [[Django (web framework)]]
* [[Artificial intelligence art]]
* [[Computational creativity]]

== References ==
{{reflist}}

Digest

2026-04-13T21:25:12Z

Mvuijlst: Created page with "{{Infobox | 01_name = Digest | 02_url = https://digest.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2025 | 05_genre = AI-generated recipe application | 06_language = Python | 07_framework = Django 5.2 | 08_license = Proprietary }} '''Digest''' is a web application hosted at <code>digest.yusupov.cloud</code> that generates and publishes AI-created recipes inspired by current news articles. Each day, the s..."

{{Infobox
| 01_name = Digest
| 02_url = https://digest.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated recipe application
| 06_language = Python
| 07_framework = [[Django]] 5.2
| 08_license = Proprietary
}}

'''Digest''' is a web application hosted at <code>digest.yusupov.cloud</code> that generates and publishes AI-created recipes inspired by current news articles. Each day, the system fetches articles from the ''New York Times'' RSS feed, selects two at random, and uses them as creative prompts for a large language model to invent a realistic, seasonally appropriate recipe. A companion image-generation pipeline produces editorial-quality food photography for each recipe using a composition diversity system that enforces visual variety across generations. The site's tagline is "Daily recipes inspired by the news."

== Technology stack ==

The application is built on Django 5.2 with [[SQLite]] as its database.<ref name="requirements">requirements.txt in the project repository lists Django ≥5.2, Pillow ≥10, openai ≥1.40, python-dotenv ≥1.0, gunicorn ≥21, requests ≥2.31, beautifulsoup4 ≥4.12, and markdown ≥3.5.</ref> It is deployed behind [[Nginx]] with [[Gunicorn]] on an Ubuntu server running two synchronous workers on port 8001. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing and optimisation, the [[OpenAI]] Python client for language-model and image-generation calls, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for scraping recipe inspiration from external sites, [[Markdown (markup language)|python-markdown]] for rendering recipe inspiration text, and [[python-dotenv]] for environment configuration. The front end uses [[Bootstrap]] 5.3.3 with Bootstrap Icons, and typography is set in Roboto (body), Roboto Serif (headings), and Roboto Slab (accents), loaded from Google Fonts.

== Data model ==

=== Recipe ===

The central model is <code>Recipe</code>, which stores:

* ''name'', ''slug'' (auto-generated), ''intro'' (short paragraph), ''inspiration'' (120–200-word Markdown text linking to the source articles), and ''visual_description'' (a single sentence describing the plated dish for use as an image-generation prompt).
* ''hero_image'' (uploaded to <code>recipes/hero/</code>), ''base_servings'' (default 4), ''prep_time_minutes'', ''cook_time_minutes'', ''is_featured'' (boolean), and automatic ''created_at'' / ''updated_at'' timestamps.
* A many-to-many relationship to <code>RecipeType</code> (one of ten canonical types: Main, Salad, One-pan, Starter, Cold dish, Soup, Side dish, Dessert, Breakfast, or Snack).

=== Structured ingredients ===

Ingredients are organised into optional titled groups (e.g. "Dough", "Sauce") via <code>IngredientGroup</code>. Each <code>Ingredient</code> within a group has:

* A foreign key to <code>IngredientName</code> (a canonical master list of deduplicated ingredient names, each with a slug and an optional foreign key to <code>IngredientCategory</code>).
* A ''quantity'' (decimal), a foreign key to <code>Unit</code> (with ''name_singular'' and ''name_plural'', e.g. "cup"/"cups", "clove"/"cloves", "g"/"g"), an optional ''note'' (e.g. "finely diced", "zested then juiced"), and an ''order'' field.
²
<code>IngredientCategory</code> supports arbitrary hierarchy via a self-referencing parent foreign key, enabling structures such as Fruit → Citrus → Lemon.

=== Instructions ===

Recipe steps are stored as <code>Direction</code> rows, optionally grouped into titled <code>InstructionGroup</code> sections. Both models carry an ''order'' field for sequencing.

=== Image prompt history ===

Every AI image generation attempt is recorded in <code>RecipeImagePrompt</code>, which stores the full prompt text, the visual description, five composition dimension values (camera angle, framing, setting, lighting style, mood), a ''was_centered'' boolean, and a creation timestamp. This history is queried by the composition diversity system to enforce variety across successive hero images.

== Recipe generation pipeline ==

Recipe generation is driven by Django management commands and a service layer in <code>recipes/services/</code>.

=== Inspiration sourcing ===

Two management commands gather external inspiration:

* <code>fetch_nyt_inspiration</code> downloads the current ''New York Times'' front page image (saved to <code>static/img/nyt/</code>) and fetches articles from the NYT homepage RSS feed. It also manages a weighted variation-rotation state file (<code>data/nyt_variation_state.json</code>) that tracks which recipe types, cooking techniques, proteins, bases, and connection styles have been used recently.
* <code>fetch_recipe_inspiration</code> scrapes the ''NYT Cooking'' and ''Dagelijkse Kost'' (VRT) websites for reference recipes, extracting titles, descriptions, and ingredient lists from embedded JSON-LD <code>Recipe</code> markup. Results are written to <code>data/inspiration.json</code>.

A PowerShell script (<code>scripts/schedule_inspiration_refresh.ps1</code>) automates the inspiration refresh on a three-day cycle via Windows Task Scheduler.

=== Variation rotation ===

To prevent repetitive output, the system maintains weighted "draw bags" for five dimensions of recipe variety:

{| class="wikitable"
|-
! Dimension !! Pool size !! Examples
|-
| Recipe type || 10 || Main (weight 7), One-pan (3), Soup (3), Salad (2), …
|-
| Technique || 13 || pan-searing (3), roasting (3), stir-frying (2), sous vide (2), …
|-
| Protein || 9 || chicken (3), beef (3), fish (2), shellfish (2), mushrooms (2), …
|-
| Base || 8 || rice (3), pasta (3), potatoes (3), flatbread (2), noodles (2), …
|-
| Connection style || 10 || geographical (10), seasonal (4), historical (3), narrative (3), …
|}

Each dimension uses a weighted bag: items are added with multiplicity proportional to their weight, and one is drawn per run without replacement. When the bag empties it is refilled. Immediate repeats of the same pick are avoided when alternatives exist. State is persisted to JSON between runs.

=== Prompt construction ===

The <code>gen_recipe_from_nyt</code> command orchestrates the full pipeline:

# Two articles are selected from the RSS feed, filtered against a usage log (<code>data/inspiration_usage.json</code>) to avoid reuse.
# Variation picks are drawn for recipe type, technique, protein, base, and connection style.
# A structured prompt is assembled, instructing the model to act as a professional recipe developer, invent one realistic recipe that a home cook in Belgium can make using seasonally appropriate ingredients, stay within 75 minutes total time, and use the drawn picks. The prompt includes both article summaries and one extra recipe reference from the inspiration pool (with a 2:1 preference for VRT over NYT sources).
# The prompt is appended with strict JSON schema instructions specifying the output format: name, intro, inspiration, visual description, servings, times, typed ingredient groups with quantities and units, titled instruction groups, and a recipe type from the canonical list.

=== Text generation ===

The <code>OpenAIRecipeGenerator</code> service class sends the prompt to the OpenAI Responses API. The default model is GPT-5, configurable via environment variable. The system prompt instructs the model to behave as a seasoned chef with Michelin-starred and home-cooking experience, and enforces detailed culinary realism rules: precise quantities ("325g not 300g"), specified heat levels and sensory cues, timing ranges, prep details in ingredient notes, assertive seasoning with salt quantities, and instructions that read like a tested recipe.<ref name="system-prompt">The system prompt in <code>recipes/services/openai_recipes.py</code> specifies: "You are a seasoned chef and food editor with 20 years of Michelin-starred and home-cooking experience."</ref>

The API call requests JSON object output format. If the model or SDK does not support the <code>text</code> format parameter, the call falls back to unformatted output. Similarly, if the model does not support the <code>temperature</code> parameter (as is the case with GPT-5), the call automatically retries without it.

=== Validation ===

After generation, the recipe JSON is passed through a self-critique step: a second, cheaper API call instructs the model to review the recipe for culinary realism — checking that quantities make sense for the serving count, that cook times are realistic for the described technique, that no ingredients mentioned in the instructions are missing from the ingredient list, and that prep notes match the steps. The model returns a corrected JSON object or the original if no issues are found. If the critique call fails, the original is used unchanged.

=== Inspiration rewriting ===

After generation, the pipeline inspects the <code>inspiration</code> field. If it is shorter than 120 words, contains the forbidden words "article" or "news," or lacks Markdown anchor links to both source articles, a rewrite call asks the model to produce a 120–200-word vivid text weaving concrete ideas from both sources, ending with properly formatted attribution links.

=== Persistence ===

The <code>save_recipe_from_data</code> function maps the generated JSON to Django models within a single transaction:

* Creates the <code>Recipe</code> row with all scalar fields.
* Resolves recipe types against the canonical allowed list (by slug); creates missing <code>RecipeType</code> rows only for canonical names.
* Creates <code>IngredientGroup</code>, <code>Ingredient</code>, <code>IngredientName</code> (get-or-create by slug), and <code>Unit</code> (get-or-create by singular name) rows.
* Normalises instruction groups: merges untitled single-step groups into one, handles multiple JSON shapes (list of strings, list of dicts with <code>step</code> or <code>text</code> keys, plain text blobs), and filters artifacts shorter than three characters.
* Triggers hero image generation (non-fatal by default; controlled by the <code>OPENAI_IMAGE_REQUIRED</code> setting).

== Hero image generation ==

Image generation is a three-layer system: a low-level OpenAI client, a composition diversity engine, and a high-level orchestrator.

=== Image API client ===

<code>OpenAIImageGenerator</code> calls the OpenAI image generation endpoint (model <code>gpt-image-1.5</code> by default, configurable via <code>OPENAI_IMAGE_MODEL</code>) and returns raw PNG bytes decoded from the base64 API response. The default output size is 1536×1024 (landscape), matching typical food photography framing.<ref name="image-size">The default size is set in <code>recipes/services/openai_images.py</code> and can be overridden via the <code>OPENAI_IMAGE_SIZE</code> setting.</ref>

=== Composition diversity ===

The <code>FoodPhotoPromptGenerator</code> enforces visual variety across successive hero images by selecting compositions from the Cartesian product of five dimensions:

{| class="wikitable"
|-
! Dimension !! Count !! Examples
|-
| Camera angle || 8 || overhead flat lay, 45° oblique, eye-level, low side, macro detail, handheld documentary, three-quarter view, tilted dutch angle
|-
| Framing || 11 || wide with negative space, tight crop, off-center, partial out-of-frame, action/utensil-in-motion, ingredient close-up, shallow depth-of-field, symmetrical centered, diagonal composition, …
|-
| Setting || 11 || white studio, stainless pro kitchen, home counter, picnic/outdoor, dark restaurant table, marble surface, wooden cutting board, concrete backdrop, vintage tile, slate serving board, …
|-
| Lighting || 12 || hard sun, soft window, dramatic low-key, warm tungsten, backlit steam, golden hour, bounce fill, rim lighting, diffused overhead, candlelight, …
|-
| Mood || 12 || modern editorial, rustic farmhouse, minimalist, street-food, celebratory, cozy homestyle, vibrant colorful, moody atmospheric, fresh healthy, indulgent decadent, …
|}

This yields approximately 13,000 possible combinations. The selection algorithm:

# Generates all combinations and shuffles them using a cryptographically secure random source (<code>secrets.SystemRandom</code>).
# Filters candidates against: angle+setting pairs used in the last 30 days (banned), recent compositions within the history window (must differ in at least 3 of 5 dimensions), and a centering constraint (no centered composition if the previous image was centered).
# Falls back to progressively relaxed criteria if no perfect match exists.

=== Prompt construction ===

The selected composition is assembled into a detailed image prompt that specifies:

* The dish name and a one-sentence visual description.
* A style directive requesting "high-end editorial food photography for a cookbook or food magazine," with natural imperfections — "slight char marks, a drip of sauce, steam rising, herbs slightly wilted from heat."
* The five composition dimensions.
* Food styling details: realistic portion sizes, contextual props (linen napkin, scattered herbs, olive oil drizzle), visible textures (crispy skin, glossy glaze, charred edges), and a natural, non-oversaturated colour palette.
* Hard constraints: photorealistic only (no illustrations), no text or watermarks, no human faces or hands, and avoidance of rustic wood unless specified.

=== Persistence and attachment ===

Each generation creates a <code>RecipeImagePrompt</code> record storing all composition metadata. The generated PNG is attached to the recipe's <code>hero_image</code> field via Django's file storage. On-demand regeneration is available through the upload-image view, which also accepts manual image uploads (validated for JPEG, PNG, or WebP content type, maximum 20 MB, downscaled to 2048px and converted to JPEG at 85% quality).

== Public interface ==

=== Home page ===

The home page displays a featured recipe (hero image with title, intro, and call-to-action) and a grid of the seven most recent recipes as cards with 1:1 hero images. The layout is responsive: seven columns on desktop, three on tablet, two on mobile.

=== Recipe detail ===

Each recipe page (<code>/r/<slug>/</code>) features:

* A hero section with the image (left, 1:1 aspect ratio, rounded shadow) and title, intro, recipe type badges (linked to type pages), and time estimates (prep, cook, total) with ingredient count.
* A sticky sidebar with the ingredient list, organised by groups, with a servings control (−/+ buttons and direct input). Ingredient quantities are scaled client-side using the formula <code>scaled_qty = base_qty × (servings / base_servings)</code>, with unit pluralisation logic handling irregular forms (cup/cups, clove/cloves).
* Numbered instructions below, optionally grouped by titled sections.
* For authenticated users: edit, delete, and regenerate-image controls, plus a collapsible display of the raw image generation prompt.

The page emits [[Schema.org]] <code>Recipe</code> JSON-LD markup (name, image, prep/cook times in ISO 8601 duration format, yield, ingredient list, and <code>HowToStep</code> instructions), Open Graph meta tags, and a canonical URL.

=== Browsing ===

The site provides several browsing views, all with file-based caching:

* ''Meals'' (<code>/types/</code>): lists recipe types with the latest example recipe for each, linking to paginated type detail pages (12 recipes per page).
* ''Ingredients'' (<code>/ingredients/</code>): a master ingredient index with recipe usage counts, linking to paginated ingredient detail pages (12 recipes per page).
* ''Categories'' (<code>/categories/</code>): a hierarchical ingredient category tree with subcategories and ingredient counts, linking to paginated category detail pages (24 items per page).
* ''About'' (<code>/about/</code>): a static information page.

=== Theme ===

The site supports light and dark colour themes, toggled via a moon/sun icon button in the navigation bar and persisted in <code>localStorage</code>. Dark mode uses a <code>#121212</code> background, <code>#e6e6e6</code> text, and yellow (<code>rgb(255, 193, 7)</code>) accent links, with high-contrast card and list-group styling.

== Administration ==

The Django admin interface is customised with:

* <code>RecipeAdmin</code>: list display with name, servings, times, creation date, and featured flag; search across name, intro, and inspiration; inline editing of instruction groups and directions; horizontal filter for recipe types.
* <code>IngredientNameAdmin</code>: list with category and recipe count; bulk actions for assigning or removing categories, and for merging duplicate ingredient names (which transfers all ingredient references to the merge target).
* <code>IngredientCategoryAdmin</code>: hierarchical display with direct and recursive ingredient counts; inline subcategory editing; a custom overview view showing category statistics; and an action for moving ingredients between subcategories.

Custom admin templates provide forms for category assignment (<code>assign_category.html</code>), category overview (<code>category_overview.html</code>), ingredient merging (<code>merge_ingredients.html</code>), and ingredient moving (<code>move_ingredients.html</code>).

== SEO and caching ==

Four sitemap classes are registered at <code>/sitemap.xml</code>:

{| class="wikitable"
|-
! Sitemap !! Items !! Priority !! Frequency
|-
| Recipes || All recipes || 0.9 || daily
|-
| Recipe types || All types || 0.6 || weekly
|-
| Ingredients || All ingredient names || 0.5 || weekly
|-
| Static pages || home, about, types index, ingredients index || 0.4 || weekly
|}

A <code>robots.txt</code> view allows all crawlers and includes the sitemap URL. Django's file-based cache is used throughout, with cache timeouts ranging from 5 minutes (recipe detail for anonymous users) to 1 hour (ingredient and category indexes). Cache is invalidated wholesale via <code>post_save</code>, <code>post_delete</code>, and <code>m2m_changed</code> signals on the <code>Recipe</code> model.

== Deployment ==

The application is deployed on an Ubuntu VPS behind Nginx, which serves static files and media directly and proxies application requests to Gunicorn on port 8001. The Gunicorn configuration specifies two synchronous workers, a 180-second request timeout (to accommodate long-running OpenAI image generation calls), and request-count-based worker recycling (1000 requests with ±100 jitter). Nginx is configured with <code>proxy_read_timeout 300s</code> for the same reason. TLS is provided by [[Let's Encrypt]] via Certbot.

== Middleware ==

A custom <code>ClacksOverheadMiddleware</code> adds the <code>X-Clacks-Overhead: GNU Terry Pratchett</code> header to all responses, as a tribute to [[Terry Pratchett]].

== Management commands ==

{| class="wikitable"
|-
! Command !! Purpose
|-
| <code>gen_recipe</code> || Generate a single recipe from a free-text topic
|-
| <code>gen_recipe_from_file</code> || Create a recipe from a JSON file matching the output schema
|-
| <code>gen_recipe_from_nyt</code> || Full pipeline: fetch NYT articles, build prompt with variation rotation, generate recipe, optionally save to database
|-
| <code>fetch_nyt_inspiration</code> || Download NYT front page and fetch RSS articles; manage variation state
|-
| <code>fetch_recipe_inspiration</code> || Scrape NYT Cooking and Dagelijkse Kost for reference recipes
|-
| <code>create_ingredient_categories</code> || Seed the hierarchical ingredient category tree
|-
| <code>auto_categorize_ingredients</code> || Pattern-matching assignment of categories to uncategorised ingredients
|-
| <code>find_duplicate_ingredients</code> || Detect and merge duplicate ingredient names
|-
| <code>normalize_instructions</code> || Post-migration cleanup for instruction group schema
|-
| <code>seed_recipes</code> || Populate the database with sample recipes
|}

== See also ==

* [[OpenAI]]
* [[Django (web framework)]]
* [[Artificial intelligence art]]
* [[Computational creativity]]

== References ==
{{reflist}}

Yusupov.cloud

2026-04-13T21:25:00Z

Mvuijlst:

{{Infobox
| name = yusupov.cloud
| 1 url = https://yusupov.cloud
| 2 type = Personal web sites
| 3 owner = [[Michel Vuijlsteke]]
| 4 launched = 2025
| 5 current_status = Online
}}

'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref>

== Overview ==
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref>

== Subdomains and projects ==
Publicly visible projects include:

* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref>
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref>
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref>
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''[[Digest]]'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref>
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref>
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref>
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)

Operator-reported (not publicly discoverable at time of writing):

* skills.yusupov.cloud — a skills matrix application. (Per operator.)
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)

== Technology ==
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" />

== Relation to the BBS ==
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref>

== See also ==
* [[Yusupov's House]] (1990s BBS)
* [[Michel Vuijlsteke]]

== References ==
{{Reflist}}

[[Category:Personal websites]]
[[Category:Belgian websites]]
[[Category:2025 establishments in Belgium]]

Quidlibet

2026-04-13T13:50:01Z

Mvuijlst:

{{Infobox
| 01_name = Quidlibet
| 02_url = https://quidlibet.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated fictional book library
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = Proprietary
}}

'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title and optionally an author and genre for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.

== Technology stack ==

The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.

== Data model ==

=== Books ===

Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.

=== Authors ===

Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.

=== Genres ===

The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.

=== Reviews ===

Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.

=== Supporting models ===

A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.

== Book generation pipeline ==

Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1.5</code>.

=== Title and metadata ===

When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.

=== Author reuse and continuity ===

Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.

When the model must invent a new author, the prompt includes a dynamically generated blocklist of first and last names that already appear two or more times in the database, preventing the library from accumulating clusters of identically named authors. The blocklist is rebuilt from the live database on every generation run.

=== Synopses and formatting ===

Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.

=== Review generation and rating profiles ===

Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).

The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.

After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.

=== Cover generation ===

Cover images are generated via OpenAI's <code>gpt-image-1.5</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.

=== Author-photo generation ===

After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1.5</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.

=== Error handling and transaction safety ===

If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code><img></code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.

== Daily batch generation ==

A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.

=== Goodreads title inspiration ===

Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].

=== Anti-sameness system ===

To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:

# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.

A parallel system applies to author names. The prompt includes a dynamically built blocklist of first and last names that already appear two or more times across the library's author table, and requires that no two authors within a single batch share a first name. The local fallback generator (used when the OpenAI API is unavailable) enforces the same within-batch uniqueness constraint on first names.

The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.

=== Hourly processing ===

A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.

== Cron security ==

Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.

== Public interface ==

=== Home page ===

The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.

=== Book pages ===

Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.

=== Author pages ===

The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).

=== Archive ===

The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.

=== Genres ===

The genres page lists all active genres alphabetically with book counts.

=== Theme ===

The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.

== Progressive web application ==

The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.

== See also ==

* [[Procedural generation]]
* [[Flask (web framework)]]
* [[OpenAI]]

== References ==
{{reflist}}

Quidlibet

2026-04-13T13:49:12Z

Mvuijlst:

{{Infobox
| 01_name = Quidlibet
| 02_url = https://quidlibet.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated fictional book library
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = Proprietary
}}

'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title — and optionally an author and genre — for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.

== Technology stack ==

The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.

== Data model ==

=== Books ===

Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.

=== Authors ===

Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.

=== Genres ===

The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.

=== Reviews ===

Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.

=== Supporting models ===

A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.

== Book generation pipeline ==

Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1.5</code>.

=== Title and metadata ===

When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.

=== Author reuse and continuity ===

Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.

When the model must invent a new author, the prompt includes a dynamically generated blocklist of first and last names that already appear two or more times in the database, preventing the library from accumulating clusters of identically named authors. The blocklist is rebuilt from the live database on every generation run.

=== Synopses and formatting ===

Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.

=== Review generation and rating profiles ===

Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).

The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.

After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.

=== Cover generation ===

Cover images are generated via OpenAI's <code>gpt-image-1.5</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.

=== Author-photo generation ===

After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1.5</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.

=== Error handling and transaction safety ===

If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code><img></code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.

== Daily batch generation ==

A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.

=== Goodreads title inspiration ===

Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].

=== Anti-sameness system ===

To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:

# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.

A parallel system applies to author names. The prompt includes a dynamically built blocklist of first and last names that already appear two or more times across the library's author table, and requires that no two authors within a single batch share a first name. The local fallback generator (used when the OpenAI API is unavailable) enforces the same within-batch uniqueness constraint on first names.

The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.

=== Hourly processing ===

A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.

== Cron security ==

Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.

== Public interface ==

=== Home page ===

The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.

=== Book pages ===

Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.

=== Author pages ===

The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).

=== Archive ===

The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.

=== Genres ===

The genres page lists all active genres alphabetically with book counts.

=== Theme ===

The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.

== Progressive web application ==

The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.

== See also ==

* [[Procedural generation]]
* [[Flask (web framework)]]
* [[OpenAI]]

== References ==
{{reflist}}

Quidlibet

2026-04-13T13:24:04Z

Mvuijlst:

{{Infobox
| 01_name = Quidlibet
| 02_url = https://quidlibet.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated fictional book library
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = Proprietary
}}

'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title and optionally an author and genre for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.

== Technology stack ==

The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.

== Data model ==

=== Books ===

Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.

=== Authors ===

Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.

=== Genres ===

The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.

=== Reviews ===

Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.

=== Supporting models ===

A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.

== Book generation pipeline ==

Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1</code>.

=== Title and metadata ===

When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.

=== Author reuse and continuity ===

Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.

=== Synopses and formatting ===

Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.

=== Review generation and rating profiles ===

Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).

The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.

After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.

=== Cover generation ===

Cover images are generated via OpenAI's <code>gpt-image-1</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.

=== Author-photo generation ===

After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.

=== Error handling and transaction safety ===

If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code><img></code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.

== Daily batch generation ==

A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.

=== Goodreads title inspiration ===

Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].

=== Anti-sameness system ===

To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:

# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.

The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.

=== Hourly processing ===

A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.

== Cron security ==

Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.

== Public interface ==

=== Home page ===

The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.

=== Book pages ===

Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.

=== Author pages ===

The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).

=== Archive ===

The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.

=== Genres ===

The genres page lists all active genres alphabetically with book counts.

=== Theme ===

The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.

== Progressive web application ==

The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.

== See also ==

* [[Procedural generation]]
* [[Flask (web framework)]]
* [[OpenAI]]

== References ==
{{reflist}}

Quidlibet

2026-04-13T13:15:04Z

Mvuijlst: Created page with "{{Infobox | 01_name = Quidlibet | 02_url = https://quidlibet.yusupov.cloud | 03_developer = Michel Vuijlsteke | 04_released = 2025 | 05_genre = AI-generated fictional book library | 06_language = Python | 07_framework = Flask 3.0 | 08_license = Proprietary }} '''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional..."

{{Infobox
| 01_name = Quidlibet
| 02_url = https://quidlibet.yusupov.cloud
| 03_developer = Michel Vuijlsteke
| 04_released = 2025
| 05_genre = AI-generated fictional book library
| 06_language = Python
| 07_framework = [[Flask]] 3.0
| 08_license = Proprietary
}}

'''Quidlibet''' (Latin for "anything whatsoever") is a web application hosted at <code>quidlibet.yusupov.cloud</code> that generates and catalogues entirely fictional books. Each book is a complete literary artefact: a plausible title, a named author with a biographical sketch and portrait, a Markdown-formatted synopsis, an AI-generated cover in genre-appropriate style, a publication date and page count, and between four and eight reader reviews with individually calibrated star ratings. The site presents itself as a browsable library catalogue under the heading "Possible Books," inviting visitors to enter a title — and optionally an author and genre — for "a book that you'd like to read but that doesn't actually exist." In addition to on-demand generation, an automated pipeline publishes up to twelve new books per day on a cron schedule.

== Technology stack ==

The application is built on Flask 3.0 with Flask-SQLAlchemy as its ORM and Flask-Login for authentication.<ref name="requirements">requirements.txt in the project repository lists Flask 3.0.3, Flask-SQLAlchemy 3.1.1, Flask-Login 0.6.3, and Flask-Caching 2.3.0.</ref> It uses [[SQLite]] as its database and is deployed behind [[Nginx]] on a Linux VPS. Additional dependencies include [[Pillow (imaging library)|Pillow]] for image processing, the Python <code>markdown</code> library for rich-text rendering, [[Beautiful Soup (HTML parser)|Beautiful Soup]] for web scraping, <code>python-dotenv</code> for configuration, and the [[OpenAI]] Python client for all language-model and image-generation calls. The front end uses Bootstrap 5.3 with a custom CSS layer, Google Fonts (Roboto Serif, Roboto Slab, Roboto), and Bootstrap Icons. The site is installable as a [[progressive web application]] via a Web App Manifest and a minimal service worker.

== Data model ==

=== Books ===

Each book record carries a ''title'', a foreign key to an ''Author'', a foreign key to a ''Genre'' (with a legacy genre-name string for backward compatibility), a Markdown ''synopsis'', a ''num_pages'' integer, an ISO 8601 ''publication_date'', a ''cover_image'' path, an ''avg_rating'' and ''rating_count'' (derived from reviews), and the ''ip_address'' and timestamp of the generation request. Books are addressed by URL slug in the form <code>/book/{id}-{title-slug}</code>, where the leading integer guarantees uniqueness and the slug provides readability.

=== Authors ===

Authors are stored with a ''name'' in "Lastname, Firstname" format (rendered as "Firstname Lastname" in the interface via a Jinja display-name filter), a Markdown-formatted ''bio'', and an optional ''author_image'' path. Author names are matched case-insensitively using Python's <code>SequenceMatcher</code> with a similarity threshold, so that minor variations do not create duplicate records.

=== Genres ===

The ''Genre'' model supports hierarchical categorisation via a self-referential ''parent_id'' foreign key. Each genre has a ''name'', an optional ''description'', a hex ''color'' code for UI tags, an ''icon'' class, a ''display_order'', and an ''is_active'' flag.

=== Reviews ===

Each review belongs to a book and carries a ''reviewer_name'', a ''review_date'' (in-universe), Markdown ''review_text'', and a ''stars'' rating between one and five. Reviews are cascade-deleted when their parent book is removed.

=== Supporting models ===

A ''GenerationJob'' tracks the asynchronous lifecycle of each generation request (pending → processing → completed or failed), with a ''progress_message'' field polled by the front end. A ''GenerationLog'' provides an audit trail of every generation attempt — successful or otherwise — including the model used, the API surface called, and any error message. A ''GenerationQueueItem'' implements a database-backed seed queue as an alternative to the file-based daily queue.

== Book generation pipeline ==

Book generation is performed in the main Flask application via a multi-step pipeline of OpenAI API calls. The default text model is GPT-5; the image model is <code>gpt-image-1</code>.

=== Title and metadata ===

When a visitor submits a title (and optionally an author and genre), the application creates a ''GenerationJob'' and redirects to a status page that polls for progress. On the status page, while the visitor waits, a rotating display of faux-library-science progress messages — "Reticulating splines…," "Reconciling author names against authority files…," "De-duplicating near-identical editions and printings…," "Calibrating star ratings to review sentiment…" — plays at random intervals for entertainment. Behind the scenes, the pipeline sends a structured prompt to the text model asking it to return a JSON object with the book's synopsis, page count, publication date, author name (invented if not supplied), and an author biography. The prompt instructs the model to write the synopsis in Markdown with bold and italic formatting, to keep it under two paragraphs of 120 words each, and to anchor it with concrete names, places, and objects rather than vague abstractions.

=== Author reuse and continuity ===

Before generating a new author, the pipeline queries the database for existing authors whose names are at least 80% similar (by sequence-matching across four name-format permutations). If a match is found — which happens for roughly a quarter of all generated books — the pipeline reuses the existing author record. It supplies the model with a context dossier listing the author's existing books, genres, and publication dates, and instructs it to revise the biography so that it naturally covers the author's expanded body of work. A hard constraint requires that any new publication date differ from the author's existing dates by at least six months. Biographies are post-processed by a helper that detects and corrects any instance of the "Lastname, Firstname" storage format that may have leaked into the prose.

=== Synopses and formatting ===

Author biographies are written in Markdown: the author's name is '''bold''' on first mention and for notable awards, book titles are ''italicised'', and paragraphs are separated by blank lines. Synopses follow similar conventions. All Markdown content is rendered through a Jinja filter backed by the Python <code>markdown</code> library (with extensions for line breaks, fenced code, and tables). On grid pages where biographies appear as truncated previews, the Markdown is first rendered to HTML, then stripped of tags, so that formatting tokens do not leak into the plaintext snippet.

=== Review generation and rating profiles ===

Reviews are generated in a separate API call. Before prompting, the pipeline constructs a deterministic ''rating profile'' by seeding a random number generator with the SHA-256 hash of the book's title, synopsis, and publication date. This seed selects one of four rating clusters — low (18% probability, mean 2.2–3.0), mid (34%, mean 3.2–3.9), high (26%, mean 4.0–4.6), or polarised (22%, mean 3.0–3.8 with high spread) — and derives a target mean, standard deviation, skew direction, and a rant count (zero to two extended reviews of either one–two or five stars).

The model is asked to produce four to eight reviews, each assigned a distinct ''stylistic palette'' from a rotating set of eight: crisp capsule (one or two punchy sentences), craft critique (prose, structure, pacing), character study (interiority, dialogue, motives), worldbuilding lens (setting, atmosphere, rules), theme tracer (motifs and subtext), comparative take (comparisons to two non-celebrity authors), sceptic's ledger (bullet-point pros and cons), and librarian angle (audience notes). Each review also rotates through a primary focus — characters, plot, prose, world, themes, or audience — so that no two reviews in a set read the same way. Review dates must fall between the book's publication date and the present day. The prompt bans stock phrases ("page-turner," "unputdownable") and requires diverse, plausible reviewer names.

After creation, the pipeline calculates the book's average rating and review count directly from the database and stores them on the book record.

=== Cover generation ===

Cover images are generated via OpenAI's <code>gpt-image-1</code> model at 1024 × 1536 pixels (2:3 portrait aspect). The prompt is tailored to the book's genre through a weighted style-selection system: cookbooks receive an eightfold bias toward photographic covers; graphic novels toward vector/graphic styles; science fiction, fantasy, and horror toward illustration; biography and history toward photography; and romance toward an even mix. The prompt specifies the exact title and author name as cover typography and bans watermarks. Generated images are decoded from base64, converted to optimised progressive JPEG via Pillow (quality 92), and saved as <code>book_{id}.jpg</code>. The pipeline allows two attempts; if both fail, the entire book-generation transaction is rolled back so that no coverless book can enter the database.

=== Author-photo generation ===

After a successful cover, the pipeline checks whether the author already has a portrait. If not, it sends a prompt to <code>gpt-image-1</code> for a photorealistic head-and-shoulders portrait at 1024 × 1024 pixels. The result is centre-cropped to a 512 × 512 square JPEG and saved as <code>author_{id}.jpg</code>. Unlike cover generation, photo generation is non-blocking: failures are logged but do not abort the job. In the interface, authors without photos receive a CSS-generated avatar showing their initials.

=== Error handling and transaction safety ===

If any exception occurs during book creation, review insertion, or image generation, the pipeline issues an immediate <code>db.session.rollback()</code> to discard all uncommitted data. The ''GenerationJob'' and ''GenerationLog'' records — committed in an earlier transaction — survive, so the failure is auditable. The job is marked as failed with a descriptive error message. In templates, all cover <code><img></code> tags include an <code>onerror</code> handler that replaces a broken image with a CSS gradient placeholder bearing the book's title, as a defence against stale database references to missing files.

== Daily batch generation ==

A standalone script, <code>fast_generator.py</code>, generates twelve book seeds (title, author, genre) in a single GPT-5 API call lasting roughly twelve seconds. The batch pipeline incorporates several layers of anti-repetition machinery.

=== Goodreads title inspiration ===

Before prompting, the script scrapes two to three randomly chosen genre pages on [[Goodreads]] (from a pool of eight: historical fiction, history, fantasy, science fiction, romance, cookbooks, general fiction, and horror). It extracts book titles from <code>div.bookBox img[alt]</code> elements, cleans them of series numbers, author suffixes, and emoji, and presents a sample as "inspiration titles — for tone and flavour only, not to be reproduced." If Goodreads is unreachable, the script falls back to a curated JSON file of titles harvested from the [[Internet Archive]] and [[Open Library]].

=== Anti-sameness system ===

To prevent the model from gravitating toward a narrow band of title shapes, the script enforces structural diversity through five mechanisms:

# '''Title-class rotation.''' Ten structural classes — concrete object, place or institution, named person, event or incident, documentary phrase, odd juxtaposition, fragment or question, subtitle-led, idiomatic phrase, and one-word punch — are allocated evenly across the batch so that each slot has a designated shape.
# '''Avoidance guidance.''' The script analyses a rolling memory of up to 2,000 previously generated titles (persisted in a JSON file) plus all titles already in the database. It identifies the twenty most overused content words, the most common title frames (e.g., "The Last ___," "Beyond the ___"), the most frequent opening words, and the most frequent closing nouns, and encodes these as explicit "do not use" directives in the prompt.
# '''Batch validator.''' After generation, each title in the batch is scored for repetitiveness: collisions on first word, end noun, or structural frame within the batch incur penalties of 0.5–1.5 points; matches against historical overuse patterns add further penalties; and two-word titles composed entirely of generic mood words score a 2.0 penalty. Titles exceeding a cumulative penalty of 3.0 are rejected and regenerated.
# '''Title memory.''' Accepted titles are appended to the rolling memory file (capped at 2,000 entries, oldest dropped first) and checked against the database to prevent exact duplicates.
# '''Database deduplication.''' Each final title is compared case-insensitively to every existing book in the database; duplicates are silently skipped.

The output is written to <code>daily_books.json</code>, a flat array of title/author/genre objects with generation timestamps.

=== Hourly processing ===

A companion script, <code>simple_hourly_processor.py</code>, runs once per hour via cron. It selects one book from the daily JSON file — indexed by a hash of the current date and hour — and triggers its full generation (metadata, reviews, cover, author photo) by calling the application's <code>/cron/hourly_book_full</code> endpoint. If all twelve daily seeds have already been processed, the hour is skipped. In production, a typical crontab runs the batch generator daily at midnight and the hourly processor every other hour, yielding up to twelve new books per day.

== Cron security ==

Cron endpoints are protected by a localhost check: the request's client IP must be <code>127.0.0.1</code>, <code>::1</code>, or <code>localhost</code>. For deployments where the cron job calls the public URL rather than the loopback address, two overrides are available: an <code>X-API-Key</code> header (or <code>api_key</code> query parameter) checked against an environment variable, or a global <code>DISABLE_CRON_LOCALHOST_CHECK</code> flag.

== Public interface ==

=== Home page ===

The home page displays a hero section with the title "Possible Books," a rotating tagline (changed every thirty minutes, seeded by the current UTC half-hour), and a generation form with an autocomplete datalist of existing authors. Below the form, a grid of the twelve most recent books (with cover images or gradient fallbacks) appears alongside the twenty-five most recent reviews, sorted by review date.

=== Book pages ===

Each book page shows the cover image (or fallback), title, author byline linked to the author's page, genre tag, page count, publication date, and average star rating. The synopsis and author biography are rendered from Markdown. Below, reviews are listed with reviewer name, star display (filled and hollow star characters), review date, and Markdown-formatted review text. Administrators see additional controls: edit book, regenerate cover, delete book, regenerate reviews, and recalculate rating.

=== Author pages ===

The author page displays the portrait (or a CSS initials placeholder), the full Markdown biography, and a grid of the author's books. The authors index lists all authors sorted alphabetically by surname, with a plaintext preview of each biography (Markdown rendered, tags stripped, truncated to 100 characters).

=== Archive ===

The archive page presents a paginated, filterable grid of all books. A sidebar offers filters by publication-year range (dynamically bucketed), minimum average rating (one to five stars), and genre (checkboxes, grouped by popularity). Filters are applied via form auto-submission on change; an explicit "clear filters" link resets the view.

=== Genres ===

The genres page lists all active genres alphabetically with book counts.

=== Theme ===

The site defaults to a dark colour scheme (<code>#111315</code> background, <code>#e6e6e6</code> text) and supports a light mode toggled via a moon-icon button in the masthead, persisted in <code>localStorage</code>. The toggle respects the operating system's <code>prefers-color-scheme</code> setting as a default. Typography uses Roboto Serif for display headings and Roboto for body text and UI elements.

== Progressive web application ==

The site ships a Web App Manifest declaring standalone display mode, dark background and theme colours, and maskable icons at 192 and 512 pixels. A service worker registers at the root scope but operates in passthrough mode — all fetch events are returned unmodified — to satisfy PWA installability requirements without risking stale cached pages in a database-backed application that publishes new content hourly.

== See also ==

* [[Procedural generation]]
* [[Flask (web framework)]]
* [[OpenAI]]

== References ==
{{reflist}}

Yusupov.cloud

2026-04-13T13:05:02Z

Mvuijlst: /* Subdomains and projects */

{{Infobox
| name = yusupov.cloud
| 1 url = https://yusupov.cloud
| 2 type = Personal web sites
| 3 owner = [[Michel Vuijlsteke]]
| 4 launched = 2025
| 5 current_status = Online
}}

'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref>

== Overview ==
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref>

== Subdomains and projects ==
Publicly visible projects include:

* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref>
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref>
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref>
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref>
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref>
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''[[Quidlibet]]'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref>
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)

Operator-reported (not publicly discoverable at time of writing):

* skills.yusupov.cloud — a skills matrix application. (Per operator.)
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)

== Technology ==
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" />

== Relation to the BBS ==
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref>

== See also ==
* [[Yusupov's House]] (1990s BBS)
* [[Michel Vuijlsteke]]

== References ==
{{Reflist}}

[[Category:Personal websites]]
[[Category:Belgian websites]]
[[Category:2025 establishments in Belgium]]

Yusupov.cloud

2026-04-13T09:30:34Z

Mvuijlst: /* Subdomains and projects */

{{Infobox
| name = yusupov.cloud
| 1 url = https://yusupov.cloud
| 2 type = Personal web sites
| 3 owner = [[Michel Vuijlsteke]]
| 4 launched = 2025
| 5 current_status = Online
}}

'''yusupov.cloud''' is a personal domain and virtual private server operated by Belgian technologist [[Michel Vuijlsteke]]. It hosts multiple small web applications on subdomains and at the apex domain. One of these is a MediaWiki installation titled “Yusupov’s House.” The setup is presented as a web-era continuation of the do-it-yourself ethos of Vuijlsteke’s 1990s BBS of the same name.<ref name="wiki-home">“Yusupov’s House,” ''yusupov.cloud'' (wiki), accessed 10 October 2025, https://yusupov.cloud/</ref>

== Overview ==
Among the projects on the domain is a MediaWiki (at the apex, ''yusupov.cloud'') running MediaWiki 1.44.0 with PHP 8.3.6 (FPM) and SQLite, using the Vector skin and core extensions for citations and template scripting.<ref name="version">‘‘Special:Version’’ page, ''yusupov.cloud'', accessed 10 October 2025, https://yusupov.cloud/wiki/Special:Version</ref>

== Subdomains and projects ==
Publicly visible projects include:

* [https://acbc.yusupov.cloud acbc.yusupov.cloud] — ''A Cabinet of Brief Curiosities'', generating tiny three-sentence surreal/horror micro-stories with an hourly cadence and an archive. (Built with Flask per operator.)<ref name="acbc-home">A Cabinet of Brief Curiosities (home), ''acbc.yusupov.cloud'', accessed 10 October 2025, https://acbc.yusupov.cloud/</ref>
* [https://agenda.yusupov.cloud agenda.yusupov.cloud] — ''A Life in Planners'', a structured journal chronicling the final years of the operator’s mother, with calendar, food, medications, measurements, and statistics views (multilingual UI).<ref name="agenda">“A life in planners,” ''agenda.yusupov.cloud'', accessed 10 October 2025, https://agenda.yusupov.cloud/</ref>
* [https://cloud.yusupov.cloud cloud.yusupov.cloud] — a series of static html creative coding experiments, simulations, and games including: timebeat, fire and snake simulations, biomass metaballs, cs3, ''Cross'' crossword puzzle game, image dithering tool, books, ''Elite Galaxy Explorer'', ZX Spectrum loading screen simulator, Carcassonne, 3D boids flocking algorithm, physarum slime mold simulation, temps temperature visualization, ''The Chronicle of Hamurabi'' ancient Sumeria resource management game, and gatekeeper.<ref name="cloud-home">"cloud," ''cloud.yusupov.cloud'', accessed 12 April 2026, https://cloud.yusupov.cloud/</ref>
* [https://digest.yusupov.cloud digest.yusupov.cloud] — ''Digest'', daily seasonal AI-assisted recipes inspired by current events, browsable by meal type and ingredients.<ref name="digest-home">“Digest — Daily recipes inspired by the news,” ''digest.yusupov.cloud'', accessed 10 October 2025, https://digest.yusupov.cloud/</ref>
* [https://echoes.yusupov.cloud echoes.yusupov.cloud] — ''[[Echoes of What Wasn't]]'', an AI-generated alternate-history newspaper presenting richly detailed articles about historical events as if they had unfolded differently. A pipeline scrapes real events from multilingual Wikipedia, uses OpenAI to craft a divergent narrative with period-appropriate prose and DALL-E imagery, and publishes via a REST API. Features article browsing by month, a "Where/When" interactive map-and-timeline view using Leaflet, and a picture desk. (Built with Wagtail 7/Django 5 per operator.)<ref name="echoes-home">"Echoes — Dispatches from Histories That Never Were," ''echoes.yusupov.cloud'', accessed 12 April 2026, https://echoes.yusupov.cloud/</ref>
* [https://quidlibet.yusupov.cloud quidlibet.yusupov.cloud] — ''Quidlibet'', an app that generates fictional books complete with synopsis, author bio, and faux reviews; includes genre and author archives. (Built with Flask per operator.)<ref name="quidlibet-home">“Quidlibet — Book Generator,” ''quidlibet.yusupov.cloud'', accessed 10 October 2025, https://quidlibet.yusupov.cloud/</ref>
* [https://tyov-web.yusupov.cloud tyov-web.yusupov.cloud] — a web implementation of the solo RPG ''[[Thousand Year Old Vampire]]'', with Django 5 backend and Vue 3 frontend. (Per operator.)

Operator-reported (not publicly discoverable at time of writing):

* skills.yusupov.cloud — a skills matrix application. (Per operator.)
* resources.yusupov.cloud — a simple resource plannign calendar. (Per operator.)

== Technology ==
The wiki stack is documented on ''Special:Version''. Individual apps are described by the operator as Flask (''acbc'', ''quidlibet'') and Django 5 + Vue 3 (''tyov-web'').<ref name="version" />

== Relation to the BBS ==
The project name references Vuijlsteke’s single-line BBS (FidoNet 2:291/1925) active between 1990 and 1995. While the VPS is not a BBS, its single-admin, self-maintained hosting reprises the early DIY approach.<ref name="wiki-home" /><ref name="nodehist">“Nodelist history search: History of node 2:291/1925,” NodeHist, accessed 10 October 2025, https://nodehist.fidonet.org.ua/?address=2%3A291%2F1925</ref>

== See also ==
* [[Yusupov's House]] (1990s BBS)
* [[Michel Vuijlsteke]]

== References ==
{{Reflist}}

[[Category:Personal websites]]
[[Category:Belgian websites]]
[[Category:2025 establishments in Belgium]]

File:Tyov-story.jpg

2026-04-12T11:46:41Z

Mvuijlst:

File:Tyov-prompt.jpg

2026-04-12T11:45:53Z

Mvuijlst:

File:Tyov-home.jpg

2026-04-12T11:45:22Z

Mvuijlst:

Thousand Year Old Vampire

2026-04-12T11:45:01Z

Mvuijlst:

{{Infobox
| 01_name = Thousand Year Old Vampire - Web Helper
| 02_developer = Michel Vuijlsteke
| 03_programming language = Python, TypeScript
| 04_operating system = Cross-platform (Web)
| 05_genre = Solo RPG digital companion
| 06_license = Custom
| 07_website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.

[[File:tyov-home.jpg|thumb|center|900px|The TYOV-Web home page, where players can browse existing chronicles, continue unfinished character creation, or begin a new vampire.]]

== Premise ==

In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.

TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''

== How Play Works ==

The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.

[[File:tyov-prompt.jpg|thumb|right|500px|A prompt page during play. The current prompt, experience form, memories, characters, and skills are visible at the same time, emphasizing both story writing and memory pressure.]]

That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.

The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.

Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue.

== An Example Unlife: Karmis ==

The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.

[[File:tyov-story.jpg|thumb|right|500px|The story overview view presents a character's life as a readable timeline, combining narrative entries with a compact summary of memories, experiences, characters, skills, resources, and marks.]]

He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.

The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.

From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.

The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.

One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.

By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.

In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.

His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.

== Why the Application Works ==

What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.

The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.

The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.

== The Frontend as Chronicle ==

The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.

That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.

State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.

== The Backend as Memory Keeper ==

Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.

The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.

Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.

== Audit Trail ==

One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.

This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.

== Development and Deployment ==

TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.

Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.

== Reception Within the Project ==

As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]

Thousand Year Old Vampire

2026-04-12T11:34:54Z

Mvuijlst: /* How Play Works */

{{Infobox
| 01_name = Thousand Year Old Vampire - Web Helper
| 02_developer = Michel Vuijlsteke
| 03_programming language = Python, TypeScript
| 04_operating system = Cross-platform (Web)
| 05_genre = Solo RPG digital companion
| 06_license = Custom
| 07_website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.

== Premise ==

In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.

TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''

== How Play Works ==

The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.

That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.

The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.

Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue.

== An Example Unlife: Karmis ==

The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.

He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.

The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.

From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.

The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.

One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.

By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.

In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.

His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.

== Why the Application Works ==

What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.

The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.

The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.

== The Frontend as Chronicle ==

The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.

That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.

State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.

== The Backend as Memory Keeper ==

Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.

The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.

Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.

== Audit Trail ==

One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.

This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.

== Development and Deployment ==

TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.

Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.

== Reception Within the Project ==

As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]

Thousand Year Old Vampire

2026-04-12T11:34:07Z

Mvuijlst:

{{Infobox
| 01_name = Thousand Year Old Vampire - Web Helper
| 02_developer = Michel Vuijlsteke
| 03_programming language = Python, TypeScript
| 04_operating system = Cross-platform (Web)
| 05_genre = Solo RPG digital companion
| 06_license = Custom
| 07_website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.

== Premise ==

In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.

TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''

== How Play Works ==

The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.

That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.

The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.

Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue. TYOV-Web exposes these rules clearly during play, but the rules never overwhelm the fiction. They exist to sharpen it.

== An Example Unlife: Karmis ==

The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.

He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.

The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.

From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.

The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.

One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.

By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.

In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.

His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.

== Why the Application Works ==

What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.

The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.

The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.

== The Frontend as Chronicle ==

The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.

That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.

State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.

== The Backend as Memory Keeper ==

Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.

The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.

Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.

== Audit Trail ==

One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.

This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.

== Development and Deployment ==

TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.

Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.

== Reception Within the Project ==

As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]

Thousand Year Old Vampire

2026-04-12T11:33:32Z

Mvuijlst:

{{Infobox software
| name = Thousand Year Old Vampire - Web Helper
| developer = Michel Vuijlsteke
| programming language = Python, TypeScript
| operating system = Cross-platform (Web)
| genre = Solo RPG digital companion
| license = Custom
| website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire - Web Helper''' ('''TYOV-Web''') is a browser-based adaptation of the solo role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. Rather than presenting the game as a digital board game or a rules spreadsheet, it treats a campaign as a long, accumulating chronicle: a vampire begins with a handful of memories, gains new experiences, loses old ones, and leaves behind a life story made of fragments, scars, names, and vanished centuries. The application is built as a '''Django''' backend serving a '''Vue''' single-page frontend, but its real achievement is literary rather than merely technical: it turns bookkeeping-heavy solo play into something that feels legible, mournful, and continuous.

== Premise ==

In ''Thousand Year Old Vampire'', the player does not manage hit points, armies, or territory. Instead, the player manages '''memory'''. A vampire may survive for centuries, but cannot perfectly retain those centuries. New experiences force older ones aside. Friends die. Languages decay. Identities are traded, abandoned, or forgotten. The drama comes from watching the self narrow and distort over time.

TYOV-Web preserves that central idea. A player creates a vampire from mortal beginnings, plays through prompts generated by dice rolls, writes narrative responses to those prompts, and organises the resulting fragments into memories. Over time the character collects skills, resources, marks, and known companions, but those are unstable possessions. The most important question is never simply ''what happened?'' It is ''what can still be remembered?''

== How Play Works ==

The application follows the structure of the tabletop game closely, but presents it as a guided story engine. Character creation unfolds in six stages: mortal life, mortal relationships, skills, resources, a defining early experience, and finally the turning into vampirism. Once play begins, each turn revolves around a prompt. The player reads the current prompt, writes at least one experience in response, manages any consequences on the character sheet, then rolls a ten-sided die and a six-sided die to discover the next destination in the prompt list.

That movement is what gives the game its broken historical rhythm. A positive result on D10 minus D6 pushes the vampire forward; a negative result drags the story backward into earlier themes or alternative branches. Prompts are also divided into variations, so revisiting a number does not necessarily mean revisiting the same moment in the same way.

The memory system gives the application its emotional pressure. A character can normally hold only '''five active memories''', and each memory can contain no more than '''three experiences'''. When that limit is reached, the player must decide what to lose. Some memories can be moved into a '''diary''', which acts as an external repository, but diaries themselves are only resources, and resources can be lost. The result is a game about narrative curation: the player is constantly deciding which version of the vampire's past deserves to remain visible.

Special prompts can alter that rhythm. Some disable experience-writing for a turn. Others allow the vampire's name to change, permit the editing of old experiences, reduce or increase permanent memory capacity, or end the chronicle entirely with an epilogue. TYOV-Web exposes these rules clearly during play, but the rules never overwhelm the fiction. They exist to sharpen it.

== An Example Unlife: Karmis ==

The most compelling way to understand the application is through one of its stored characters. One campaign in the database follows '''Karmis''', formerly '''Ekurzu''' and before that '''Naram''', across roughly three and a half thousand years.

He begins in Bronze Age Mari as a temple scribe: precise, observant, and deeply embedded in the religious and political machinery of the city. His mortal life is defined by clay tablets, whispered intelligence, and courtly danger. He falls in love with Hessa, is shaped by the mentorship of the high priest Ibbi-Zamri, and is eventually turned by the ancient vampire Ashurban the Veiled. In one of the campaign's defining cruelties, Ibbi-Zamri becomes the first person Karmis kills after the turning.

The early centuries of his unlife are marked by exile and shame. He flees with Ennatum, struggles to master the hunger, tries to imagine restraint as redemption, and fails. One of the campaign's most effective lines comes from this period: he builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually he devours Ennatum during a sandstorm and carries that loss into the long middle stretch of the story.

From there the campaign moves through one civilisation after another. Karmis passes through Akhenaten's Egypt, the imperial roads of the Achaemenids, the scholarly world of Alexandria, Roman frontiers, monastic Europe, Mediterranean trade routes, and the violence of the early modern Atlantic world. His roles change less than the world around him does. He remains a scribe, witness, forger, archivist, and careful observer of institutions that never last as long as he does.

The campaign also shows how the game's systems create character rather than merely recording it. Karmis gains skills such as ''Silent Cartography'', the ability to trace unseen paths of influence, and ''Ash-Tongue'', a talent for insinuation and social survival. But he loses others as time damages his identity. He once knew how to decipher ancient texts; later he no longer can. He once believed he could control the beast within; later even that confidence disappears. The mechanics translate immortality into erosion.

One of the campaign's richest relationships is with '''Thooni''', a scholar who recognises the name ''Ekurzu'' not as legend but as continuity. After her mortal death, the relationship persists in altered form: a spectral Thooni begins appearing in the margins of Karmis's diary, leaving fragments in languages he can no longer read. TYOV-Web handles this elegantly because its model of a character is not limited to a living cast list. People can be present, absent, lost, remembered, or transformed into symbols the protagonist can no longer fully interpret.

By the late Roman and early medieval portions of the chronicle, the cost of the memory rules becomes brutal. Karmis loses so many memories that even the event of his own turning is no longer available to him. He relies on diaries and external records to stabilise himself, yet those too are vulnerable. A carved chamber called ''The Walls of Forgetting'' and a later monastery diary both disappear. The application does not treat this as simple inventory loss; it feels instead like a second death for pieces of the self.

In the final act, Karmis witnesses the Atlantic slave trade and begins keeping a ledger of names drawn from shipping manifests and punishment records. A later response captures the moral exhaustion of the character with unusual sharpness: he no longer imagines himself purified by restraint, only redirected by purpose. He feeds on slavers and calls it justice, yet recognises that the blood tastes the same. This is the kind of line the application is built to preserve: not just event logs, but accumulations of ethical fatigue.

His last great companion is '''Mirelde of Bracha''', who becomes mirror, partner, and eventually historian. By the time the epilogue arrives, the story is no longer told in Karmis's own voice. Mirelde writes the closing judgment on him: not as a monster laid to rest, but as "just a man who remembered too much, for too long, and chose, in the end, peace." That shift in narrator is exactly the sort of late-game turn TYOV-Web makes easy to sustain, because it keeps the campaign legible even after the protagonist himself has become unreliable.

== Why the Application Works ==

What makes TYOV-Web effective is not that it digitises every rule, though it largely does. Its strength is that it understands which parts of the original game are dramatically important and places those at the centre of the interface.

The main play screen is organised around the prompt, the character sheet, and the memory display. The prompt is always the immediate literary provocation. The memory display constantly reminds the player of pressure and loss: active memories, diary memories, and forgotten memories sit in visible relation to one another. Skills, resources, marks, and known characters are editable in place, which means the character sheet grows and collapses alongside the fiction instead of feeling like a separate administrative surface.

The result is a frontend that behaves less like a dashboard and more like a writing desk. Players move between the prompt text, the experience form, and the fragments of the vampire's surviving life. Even when the application is doing something purely mechanical, such as validating whether the player may continue, the effect is narrative: it is asking whether the current moment of the story has been fully accounted for.

== The Frontend as Chronicle ==

The client side of TYOV-Web is a '''Vue 3''' single-page application written in '''TypeScript'''. In practical terms, this means the entire experience unfolds without page reloads; in literary terms, it allows the game to feel continuous. The player logs in, sees a home screen of active and archived characters, enters a creation wizard for new vampires, and then spends most of the campaign inside a single evolving game view.

That view is supported by a set of focused screens: a login page, a home dashboard, the six-step character creation flow, the main game interface, an ending screen for completed chronicles, an archive view, and a story view that presents the campaign as a timeline. Around those are a collection of smaller windows and dialogs for editing characters, skills, resources, memories, and experiences. These are important not because there are many of them, but because they preserve the sense that a campaign is always open to revision, annotation, and reinterpretation.

State is held in Pinia stores for authentication, gameplay, character creation, and theme. That is an implementation detail, but in this case it serves a visible purpose: it keeps the player's character, current prompt, pending changes, and validation state coherent at all times. The interface never feels as if it has forgotten where the player is in the life of the vampire.

== The Backend as Memory Keeper ==

Behind the interface is a '''Django 5''' application with a REST API built on '''Django REST Framework'''. The backend models the campaign in the same terms the game itself cares about: '''Character''', '''Memory''', '''Experience''', '''Skill''', '''Resource''', '''Mark''', '''GameCharacter''', '''Prompt''', and '''PendingChange'''. This is not especially glamorous architecture, but it is disciplined. The data model is close to the language of play, which makes the whole system easier to reason about.

The most interesting design choice is the use of '''pending changes'''. TYOV-Web does not immediately finalise every action the player takes. Instead, new experiences and character-sheet adjustments can accumulate as provisional edits until the player chooses to continue the story. Only then are they committed atomically. This makes the system feel less like a CRUD application and more like a drafting process. A turn can be assembled, reconsidered, and only then sealed into the chronicle.

Authentication is handled by JWT tokens, and character data is scoped to the authenticated user. The backend exposes endpoints for the game state itself, dice rolling, story continuation, and CRUD operations on memories, experiences, skills, resources, marks, and known characters. In the article, however, the important point is not the shape of the URLs. It is that the backend has been designed to support a narrative workflow rather than a generic records system.

== Audit Trail ==

One of the application's strongest features is its audit trail. Each time the player advances to a new prompt, TYOV-Web captures a complete snapshot of the game state: prompt transition, dice roll, character sheet, memories, and the set of changes applied on that turn. In effect, the application keeps both the ''current'' vampire and the ''history of how that vampire became current''.

This matters for more than debugging. In a game built around forgetting, a turn-by-turn archive becomes part of the theme. The player may choose to lose a memory inside the fiction, but the application still preserves the fact that the loss occurred. The vampire forgets; the chronicle does not.

== Development and Deployment ==

TYOV-Web is developed as a two-part web project: Django on the server side, Vue on the client side. In local development the repository can be started with a PowerShell bootstrap script, which creates the Python environment, installs dependencies, runs migrations, and launches both servers. In production, the frontend is built with Vite and the backend is configured through the usual Django environment settings, including a production mode selected with <code>DJANGO_ENV=production</code>.

Testing exists on both sides of the stack. The backend is covered with '''pytest''' and '''pytest-django'''; the frontend uses '''Playwright''' for end-to-end coverage of the creation flow and core game loop. Those details are reassuring, but secondary. The more meaningful point is that the project has been built as an actual maintained application rather than a one-off prototype.

== Reception Within the Project ==

As a fan-made implementation, TYOV-Web is best understood as an act of interpretation. It does not try to replace the tabletop experience with spectacle. Instead it asks what a web application can do well for this particular game: preserve long-form writing, reduce clerical overhead, make memory pressure visible, and retain the full history of a life that the protagonist can no longer fully remember. In that sense it is not merely a helper app. It is a machine for turning play into biography.

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]

Thousand Year Old Vampire

2026-04-12T11:26:18Z

Mvuijlst: /* A Life in Summary */

{{Infobox
| 01_name = Thousand Year Old Vampire – Web Helper
| 02_logo =
| 03_developer = Michel Vuijlsteke
| 04_programming language = Python (Django 5), TypeScript (Vue 3)
| 05_operating system = Cross-platform (Web)
| 06_genre = Solo RPG Digital Companion
| 07_license = custom
| 08_website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.

== Overview ==

''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.

TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.

== Game Rules ==

=== Core Concept ===

The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.

=== Character Creation ===

Character creation follows a guided six-step wizard:

{| class="wikitable"
|-
! Step !! Description
|-
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence
|-
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)
|-
| 3. Skills || Choose 2–3 starting skills representing mortal expertise
|-
| 4. Resources || Select initial possessions and locations
|-
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together
|-
| 6. The Turning || Narrate how and why the character was turned into a vampire
|}

=== Memory System ===

The memory system is the heart of the game:

* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).
* Each memory can contain up to '''3 experiences''' (individual narrative entries).
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.
* If the diary resource is lost, all memories stored in it are also lost.
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).

=== Dice Rolling and Prompt Navigation ===

Each turn the player rolls two dice:

* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).
* A '''positive''' result moves forward that many prompts.
* A '''negative''' result moves backward.
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.

Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.

=== Turn Structure ===

Each game turn follows this sequence:

# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.

=== Character Attributes ===

{| class="wikitable"
|-
! Attribute !! Description
|-
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).
|-
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.
|-
| '''Marks''' || Physical or psychological scars that accumulate over time.
|-
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).
|}

=== Special Prompt Rules ===

Certain prompts carry special mechanics encoded as rules:

{| class="wikitable"
|-
! Rule !! Effect
|-
| <code>no_experience</code> || Experience creation is disabled for this turn
|-
| <code>allow_name_change</code> || The player may change the vampire's name
|-
| <code>memory_modification</code> || The player may edit the text of existing experiences
|-
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1
|-
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1
|-
| <code>game_over</code> || The game ends; the player writes an epilogue
|}

=== Game Ending ===

The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.

== Architecture ==

=== Technology Stack ===

{| class="wikitable"
|-
! Layer !! Technology !! Version
|-
| Backend framework || Django || 5.0.6
|-
| REST API || Django REST Framework || 3.15.1
|-
| Authentication || Simple JWT (custom) || 5.3.0
|-
| CORS || django-cors-headers || 4.3.1
|-
| Image handling || Pillow || 11.3.0
|-
| Production server || Gunicorn || 21.2.0
|-
| Frontend framework || Vue.js || 3.5
|-
| State management || Pinia || 3.0
|-
| Routing || Vue Router || 4.5
|-
| HTTP client || Axios || 1.10
|-
| CSS framework || Bootstrap || 5.3
|-
| Build tool || Vite || 7.0
|-
| Language || TypeScript || 5.8
|-
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8
|-
| Testing (frontend) || Playwright || 1.53
|}

=== High-Level Diagram ===

<pre>
┌─────────────────────────────────────────────────┐
│ Vue 3 SPA (TypeScript) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│ │ Views │ │Components│ │ Pinia Stores ││
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││
│ │ │ │ │ │ characterCreation ││
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│
│ └─────────────┴────────────────┘ │
│ │ Axios │
│ ▼ │
├─────────────────────────────────────────────────┤
│ Django REST API │
│ /api/auth/login /api/auth/verify │
│ /api/characters/ (CRUD + game_state, │
│ roll_dice, continue_story, audit_trail) │
│ /api/characters/<id>/memories/ │
│ /api/characters/<id>/experiences/ │
│ /api/characters/<id>/skills/ │
│ /api/characters/<id>/resources/ │
│ /api/characters/<id>/marks/ │
│ /api/characters/<id>/characters/ │
│ /api/characters/<id>/pending-changes/ │
│ /api/prompts/ │
├─────────────────────────────────────────────────┤
│ Django ORM / SQLite │
│ Character · Memory · Experience · Skill │
│ Resource · Mark · GameCharacter · Prompt │
│ PendingChange · GameStateSnapshot │
└─────────────────────────────────────────────────┘
</pre>

== Backend ==

=== Django Apps ===

The project is organised into three Django apps plus a settings module:

{| class="wikitable"
|-
! App !! Purpose
|-
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot
|-
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware
|-
| <code>authentication</code> || JWT-based login and token verification endpoints
|-
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration
|}

=== Data Models ===

==== Character ====

The central model, owned by a Django <code>User</code> via a ForeignKey:

{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>name</code> || CharField(200) || Current name of the vampire
|-
| <code>description</code> || TextField || Background/appearance description
|-
| <code>image</code> || ImageField || Optional character portrait
|-
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")
|-
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll
|-
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order
|-
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions
|-
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases
|-
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard
|-
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished
|-
| <code>creation_data</code> || JSONField || Temporary storage during creation
|-
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)
|-
| <code>is_completed</code> || BooleanField || Whether the story has ended
|-
| <code>completed_at</code> || DateTimeField || Timestamp of story completion
|}

==== Memory ====

A memory belongs to a Character and holds up to 3 Experiences:

* <code>title</code> – descriptive name (unique per character)
* <code>in_diary</code> – whether the memory is stored in the diary
* <code>is_lost</code> – whether the memory has been forgotten

==== Experience ====

An individual narrative entry within a Memory:

* <code>title</code> – optional short description
* <code>content</code> – the narrative text
* <code>prompt_id</code> – which prompt generated this experience
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")

==== Skill ====

* <code>name</code>, <code>description</code>
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code>

==== Resource ====

* <code>name</code>, <code>description</code>
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code>
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)
* <code>is_lost</code>

==== Mark ====

* <code>name</code>, <code>description</code>
* <code>is_lost</code>

==== GameCharacter ====

* <code>name</code>, <code>description</code>
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code>
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral
* <code>is_lost</code>

==== Prompt ====

* <code>prompt_id</code> – e.g. "17a", "32b"
* <code>number</code>, <code>variation</code> – parsed components for sorting
* <code>content</code> – the scenario text
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)

==== PendingChange ====

Temporary storage for changes before they are atomically committed on "Continue":

* <code>change_type</code> – experience, memory, skill, resource, mark, or character
* <code>change_data</code> – JSON payload of the change

==== GameStateSnapshot (Audit Trail) ====

Automatically created each turn to record the complete game state:

* <code>turn_number</code> – sequential, starting from 1
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition
* <code>dice_roll</code> – raw dice data
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.
* <code>changes_applied</code> – JSON array of pending changes that were committed
* <code>created_at</code> – timestamp

=== API Endpoints ===

All endpoints require JWT authentication (except login).

==== Authentication ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token
|-
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info
|}

Login is rate-limited to 5 requests per minute per IP.

==== Characters ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || <code>/api/characters/</code> || List all characters for the authenticated user
|-
| POST || <code>/api/characters/</code> || Create a new character
|-
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)
|-
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields
|-
| DELETE || <code>/api/characters/{id}/</code> || Delete a character
|-
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info
|-
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result
|-
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt
|-
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history
|-
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns
|}

==== Nested Character Resources ====

For each character, full CRUD is available on:

* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)
* <code>/api/characters/{id}/experiences/</code>
* <code>/api/characters/{id}/skills/</code>
* <code>/api/characters/{id}/resources/</code>
* <code>/api/characters/{id}/marks/</code>
* <code>/api/characters/{id}/characters/</code> (known NPCs)
* <code>/api/characters/{id}/pending-changes/</code>

==== Prompts ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || <code>/api/prompts/</code> || List all game prompts
|-
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID
|}

=== Permissions and Security ===

* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.
* CORS headers are configured via <code>django-cors-headers</code>.

== Frontend ==

=== Views (Pages) ===

{| class="wikitable"
|-
! View !! Route !! Description
|-
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home
|-
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid
|-
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard
|-
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display
|-
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue
|-
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters
|-
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue
|}

All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.

=== Key Components ===

{| class="wikitable"
|-
! Component !! Purpose
|-
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results
|-
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection
|-
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions
|-
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls
|-
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete
|-
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks
|-
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters
|-
| '''ExperienceEditWindow''' || Window for editing existing experience text
|-
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it
|-
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions
|-
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied
|}

=== State Management (Pinia) ===

Four Pinia stores manage application state:

{| class="wikitable"
|-
! Store !! Responsibility
|-
| '''auth''' || JWT token, user object, login/logout, token expiry handling
|-
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation
|-
| '''characterCreation''' || Multi-step wizard data, initial character creation
|-
| '''theme''' || Dark/light mode toggle with localStorage persistence
|}

=== API Service Layer ===

* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.

=== Composables ===

Vue composables encapsulate reusable business logic:

* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes

== Audit Trail ==

The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.

Each '''GameStateSnapshot''' records:

* The turn number (sequential from 1)
* The prompt transition (e.g. 36a → 34a)
* The dice roll
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters
* All pending changes that were committed

The audit trail is accessible via:

* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code>
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes

== Deployment ==

=== Local Development ===

<pre>
.\startup.ps1
</pre>

This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).

=== Production ===

* Set <code>DJANGO_ENV=production</code>
* Build the frontend: <code>cd frontend && npm run build</code>
* Serve with Gunicorn behind a reverse proxy
* Static files are collected into the <code>static/</code> directory
* The production frontend points to <code>https://tyov.yusupov.cloud</code>

== Example: A Finished Character ==

The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.

=== Karmiš (formerly Ekurzu / Naram) ===

'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.

'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.

'''Final prompt:''' 73a

'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)

==== Epilogue ====

<blockquote>
He has not died. Let me say that plainly. There will be no grave. He is alive, but quietly, deliberately, and utterly outside your reach.

When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and finally his historian.

But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]

Just a man who remembered too much, for too long. And chose, in the end, peace.

— ''Mirelde''
</blockquote>

==== A Life in Summary ====

Karmiš's story spans roughly three and a half thousand years. It begins in Bronze Age Mesopotamia, where the mortal scribe Naram serves in the temple of Ishtar at Mari. He writes omens, navigatesg palace intrigue, and fals in love with a woman named Hessa who moves through the court "like smoke." His mentor, the High Priest Ibbi-Zamri, is the first person he kills after being turned by the ancient vampire Ashurban the Veiled.

The early centuries are defined by guilt and exile. Fleeing with his mortal companion Ennatum, the newly-made vampire (now calling himself Ekurzu) struggles to control his hunger. He builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually the hunger wins: he devours Ennatum during a sandstorm and spends the following decades alone.

The middle game carries the character through the great civilisations of antiquity: Amarna under Akhenaten, the Achaemenid Royal Road, the libraries of Alexandria—always in the role of scribe, forger, or quiet observer. He accumulates skills like ''Silent Cartography'' ("I trace the unseen paths between people, places, and power") and ''Ash-Tongue'' ("I speak in soot and suggestion, in the cracks between laws"), but loses others as the centuries erode his identity: the ability to ''Decipher Ancient Texts'' and even ''I Control the Beast'' both slip away.

A pivotal relationship develops with the scholar Thoöni, who recognises the name ''Ekurzu'' not as myth but as continuity. Later, after Thoöni's mortal death, her spectral echo begins appearing in the margins of his diary, scratching fragments in languages he can no longer read.

By the late Roman period Karmiš has lost so many memories that he can barely hold a conversation. The game's memory mechanics enforce this viscerally: eight of his sixteen memories were permanently forgotten, including ''The Turning'' itself; the vampire no longer remembers how he was made. He compensates by keeping diaries, but even those are lost: ''The Walls of Forgetting'' (memory carvings in five scripts beneath a shrine near Carchemish) and ''The Monastery Diary'' both vanish, taking their stored memories with them.

The final act takes place in early modern Europe. Karmiš witnesses the Atlantic slave trade first-hand and begins compiling ''The Margins of Manifest'', a cipher-folio of names taken from shipping manifests and punishment ledgers. His response to prompt 66a captures the shift:

<blockquote>
''It is no longer a question of restraint. That was a younger version of me, one who believed self-control made me different from the others. Now I am different in purpose, not method. I feed from slavers and call it justice, but the blood tastes the same.''
</blockquote>

His companion in the final centuries is Mirelde of Bracha. She is an immortal who becomes his mirror, partner, and ultimately his historian. Together they rediscover a clay tablet bearing his original name in a Venetian bookseller's back room (prompt 68a, 1704 CE), and in a ruined estate outside Smyrna Mirelde finds the remains of a life Karmiš can no longer remember.

At the story's end Karmiš retains only five active memories, three diary memories, two marks (''The Unblinking Eye'', a scar that burns in the presence of lies and ''The Gesture Forbidden'', an involuntary court gesture mistaken for mockery), and three possessions: his diary ''Kept Against Forgetting'', the clay tablet bearing his name, and the slave-trade folio. Of the eleven characters he encountered, only four remain: Ashurban (his distant maker), Mirelde (his companion), Thoöni's ghost, and a nameless figure known only as ''The One Who Does Not Answer''. Over 34 prompts he accumulated 37 experiences, gained and lost a memory slot each, and burned through three separate diaries.

The character's story is narrated in the epilogue not by Karmiš himself but by Mirelde, who insists: "He has not died. [...] Just a man who remembered too much, for too long. And chose, in the end, ''peace''."

== Testing ==

=== Backend ===

Tests are run with '''pytest''' and '''pytest-django''':

<pre>
pytest
</pre>

Test files include:
* <code>vampire/test_models.py</code> – model unit tests
* <code>tyov_api/test_api.py</code> – API endpoint integration tests
* <code>tyov_api/test_models.py</code> – API model tests
* <code>authentication/test_views.py</code> – authentication tests

=== Frontend ===

End-to-end tests use '''Playwright''':

<pre>
cd frontend
npx playwright test
</pre>

Test specs include:
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard
* <code>e2e/tyov-game.spec.ts</code> – game loop testing
* <code>e2e/vue.spec.ts</code> – general Vue component tests

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]

Thousand Year Old Vampire

2026-04-12T11:22:40Z

Mvuijlst: /* Epilogue */

{{Infobox
| 01_name = Thousand Year Old Vampire – Web Helper
| 02_logo =
| 03_developer = Michel Vuijlsteke
| 04_programming language = Python (Django 5), TypeScript (Vue 3)
| 05_operating system = Cross-platform (Web)
| 06_genre = Solo RPG Digital Companion
| 07_license = custom
| 08_website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.

== Overview ==

''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.

TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.

== Game Rules ==

=== Core Concept ===

The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.

=== Character Creation ===

Character creation follows a guided six-step wizard:

{| class="wikitable"
|-
! Step !! Description
|-
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence
|-
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)
|-
| 3. Skills || Choose 2–3 starting skills representing mortal expertise
|-
| 4. Resources || Select initial possessions and locations
|-
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together
|-
| 6. The Turning || Narrate how and why the character was turned into a vampire
|}

=== Memory System ===

The memory system is the heart of the game:

* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).
* Each memory can contain up to '''3 experiences''' (individual narrative entries).
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.
* If the diary resource is lost, all memories stored in it are also lost.
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).

=== Dice Rolling and Prompt Navigation ===

Each turn the player rolls two dice:

* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).
* A '''positive''' result moves forward that many prompts.
* A '''negative''' result moves backward.
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.

Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.

=== Turn Structure ===

Each game turn follows this sequence:

# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.

=== Character Attributes ===

{| class="wikitable"
|-
! Attribute !! Description
|-
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).
|-
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.
|-
| '''Marks''' || Physical or psychological scars that accumulate over time.
|-
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).
|}

=== Special Prompt Rules ===

Certain prompts carry special mechanics encoded as rules:

{| class="wikitable"
|-
! Rule !! Effect
|-
| <code>no_experience</code> || Experience creation is disabled for this turn
|-
| <code>allow_name_change</code> || The player may change the vampire's name
|-
| <code>memory_modification</code> || The player may edit the text of existing experiences
|-
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1
|-
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1
|-
| <code>game_over</code> || The game ends; the player writes an epilogue
|}

=== Game Ending ===

The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.

== Architecture ==

=== Technology Stack ===

{| class="wikitable"
|-
! Layer !! Technology !! Version
|-
| Backend framework || Django || 5.0.6
|-
| REST API || Django REST Framework || 3.15.1
|-
| Authentication || Simple JWT (custom) || 5.3.0
|-
| CORS || django-cors-headers || 4.3.1
|-
| Image handling || Pillow || 11.3.0
|-
| Production server || Gunicorn || 21.2.0
|-
| Frontend framework || Vue.js || 3.5
|-
| State management || Pinia || 3.0
|-
| Routing || Vue Router || 4.5
|-
| HTTP client || Axios || 1.10
|-
| CSS framework || Bootstrap || 5.3
|-
| Build tool || Vite || 7.0
|-
| Language || TypeScript || 5.8
|-
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8
|-
| Testing (frontend) || Playwright || 1.53
|}

=== High-Level Diagram ===

<pre>
┌─────────────────────────────────────────────────┐
│ Vue 3 SPA (TypeScript) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│ │ Views │ │Components│ │ Pinia Stores ││
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││
│ │ │ │ │ │ characterCreation ││
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│
│ └─────────────┴────────────────┘ │
│ │ Axios │
│ ▼ │
├─────────────────────────────────────────────────┤
│ Django REST API │
│ /api/auth/login /api/auth/verify │
│ /api/characters/ (CRUD + game_state, │
│ roll_dice, continue_story, audit_trail) │
│ /api/characters/<id>/memories/ │
│ /api/characters/<id>/experiences/ │
│ /api/characters/<id>/skills/ │
│ /api/characters/<id>/resources/ │
│ /api/characters/<id>/marks/ │
│ /api/characters/<id>/characters/ │
│ /api/characters/<id>/pending-changes/ │
│ /api/prompts/ │
├─────────────────────────────────────────────────┤
│ Django ORM / SQLite │
│ Character · Memory · Experience · Skill │
│ Resource · Mark · GameCharacter · Prompt │
│ PendingChange · GameStateSnapshot │
└─────────────────────────────────────────────────┘
</pre>

== Backend ==

=== Django Apps ===

The project is organised into three Django apps plus a settings module:

{| class="wikitable"
|-
! App !! Purpose
|-
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot
|-
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware
|-
| <code>authentication</code> || JWT-based login and token verification endpoints
|-
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration
|}

=== Data Models ===

==== Character ====

The central model, owned by a Django <code>User</code> via a ForeignKey:

{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>name</code> || CharField(200) || Current name of the vampire
|-
| <code>description</code> || TextField || Background/appearance description
|-
| <code>image</code> || ImageField || Optional character portrait
|-
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")
|-
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll
|-
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order
|-
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions
|-
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases
|-
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard
|-
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished
|-
| <code>creation_data</code> || JSONField || Temporary storage during creation
|-
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)
|-
| <code>is_completed</code> || BooleanField || Whether the story has ended
|-
| <code>completed_at</code> || DateTimeField || Timestamp of story completion
|}

==== Memory ====

A memory belongs to a Character and holds up to 3 Experiences:

* <code>title</code> – descriptive name (unique per character)
* <code>in_diary</code> – whether the memory is stored in the diary
* <code>is_lost</code> – whether the memory has been forgotten

==== Experience ====

An individual narrative entry within a Memory:

* <code>title</code> – optional short description
* <code>content</code> – the narrative text
* <code>prompt_id</code> – which prompt generated this experience
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")

==== Skill ====

* <code>name</code>, <code>description</code>
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code>

==== Resource ====

* <code>name</code>, <code>description</code>
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code>
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)
* <code>is_lost</code>

==== Mark ====

* <code>name</code>, <code>description</code>
* <code>is_lost</code>

==== GameCharacter ====

* <code>name</code>, <code>description</code>
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code>
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral
* <code>is_lost</code>

==== Prompt ====

* <code>prompt_id</code> – e.g. "17a", "32b"
* <code>number</code>, <code>variation</code> – parsed components for sorting
* <code>content</code> – the scenario text
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)

==== PendingChange ====

Temporary storage for changes before they are atomically committed on "Continue":

* <code>change_type</code> – experience, memory, skill, resource, mark, or character
* <code>change_data</code> – JSON payload of the change

==== GameStateSnapshot (Audit Trail) ====

Automatically created each turn to record the complete game state:

* <code>turn_number</code> – sequential, starting from 1
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition
* <code>dice_roll</code> – raw dice data
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.
* <code>changes_applied</code> – JSON array of pending changes that were committed
* <code>created_at</code> – timestamp

=== API Endpoints ===

All endpoints require JWT authentication (except login).

==== Authentication ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token
|-
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info
|}

Login is rate-limited to 5 requests per minute per IP.

==== Characters ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || <code>/api/characters/</code> || List all characters for the authenticated user
|-
| POST || <code>/api/characters/</code> || Create a new character
|-
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)
|-
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields
|-
| DELETE || <code>/api/characters/{id}/</code> || Delete a character
|-
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info
|-
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result
|-
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt
|-
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history
|-
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns
|}

==== Nested Character Resources ====

For each character, full CRUD is available on:

* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)
* <code>/api/characters/{id}/experiences/</code>
* <code>/api/characters/{id}/skills/</code>
* <code>/api/characters/{id}/resources/</code>
* <code>/api/characters/{id}/marks/</code>
* <code>/api/characters/{id}/characters/</code> (known NPCs)
* <code>/api/characters/{id}/pending-changes/</code>

==== Prompts ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || <code>/api/prompts/</code> || List all game prompts
|-
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID
|}

=== Permissions and Security ===

* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.
* CORS headers are configured via <code>django-cors-headers</code>.

== Frontend ==

=== Views (Pages) ===

{| class="wikitable"
|-
! View !! Route !! Description
|-
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home
|-
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid
|-
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard
|-
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display
|-
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue
|-
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters
|-
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue
|}

All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.

=== Key Components ===

{| class="wikitable"
|-
! Component !! Purpose
|-
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results
|-
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection
|-
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions
|-
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls
|-
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete
|-
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks
|-
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters
|-
| '''ExperienceEditWindow''' || Window for editing existing experience text
|-
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it
|-
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions
|-
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied
|}

=== State Management (Pinia) ===

Four Pinia stores manage application state:

{| class="wikitable"
|-
! Store !! Responsibility
|-
| '''auth''' || JWT token, user object, login/logout, token expiry handling
|-
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation
|-
| '''characterCreation''' || Multi-step wizard data, initial character creation
|-
| '''theme''' || Dark/light mode toggle with localStorage persistence
|}

=== API Service Layer ===

* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.

=== Composables ===

Vue composables encapsulate reusable business logic:

* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes

== Audit Trail ==

The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.

Each '''GameStateSnapshot''' records:

* The turn number (sequential from 1)
* The prompt transition (e.g. 36a → 34a)
* The dice roll
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters
* All pending changes that were committed

The audit trail is accessible via:

* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code>
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes

== Deployment ==

=== Local Development ===

<pre>
.\startup.ps1
</pre>

This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).

=== Production ===

* Set <code>DJANGO_ENV=production</code>
* Build the frontend: <code>cd frontend && npm run build</code>
* Serve with Gunicorn behind a reverse proxy
* Static files are collected into the <code>static/</code> directory
* The production frontend points to <code>https://tyov.yusupov.cloud</code>

== Example: A Finished Character ==

The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.

=== Karmiš (formerly Ekurzu / Naram) ===

'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.

'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.

'''Final prompt:''' 73a

'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)

==== Epilogue ====

<blockquote>
He has not died. Let me say that plainly. There will be no grave. He is alive, but quietly, deliberately, and utterly outside your reach.

When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and finally his historian.

But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]

Just a man who remembered too much, for too long. And chose, in the end, peace.

— ''Mirelde''
</blockquote>

==== A Life in Summary ====

Karmiš's story spans roughly three and a half thousand years. It begins in Bronze Age Mesopotamia, where the mortal scribe Naram serves in the temple of Ishtar at Mari—writing omens, navigating palace intrigue, and falling in love with a woman named Hessa who moves through the court "like smoke." His mentor, the High Priest Ibbi-Zamri, is the first person he kills after being turned by the ancient vampire Ashurban the Veiled.

The early centuries are defined by guilt and exile. Fleeing with his mortal companion Ennatum, the newly-made vampire—now calling himself Ekurzu—struggles to control his hunger. He builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually the hunger wins: he devours Ennatum during a sandstorm and spends the following decades alone.

The middle game carries the character through the great civilisations of antiquity—Amarna under Akhenaten, the Achaemenid Royal Road, the libraries of Alexandria—always in the role of scribe, forger, or quiet observer. He accumulates skills like ''Silent Cartography'' ("I trace the unseen paths between people, places, and power") and ''Ash-Tongue'' ("I speak in soot and suggestion, in the cracks between laws"), but loses others as the centuries erode his identity: the ability to ''Decipher Ancient Texts'' and even ''I Control the Beast'' both slip away.

A pivotal relationship develops with the scholar Thoöni, who recognises the name ''Ekurzu'' not as myth but as continuity. Later—after Thoöni's mortal death—her spectral echo begins appearing in the margins of his diary, scratching fragments in languages he can no longer read.

By the late Roman period Karmiš has lost so many memories that he can barely hold a conversation. The game's memory mechanics enforce this viscerally: eight of his sixteen memories were permanently forgotten, including ''The Turning'' itself—the vampire no longer remembers how he was made. He compensates by keeping diaries, but even those are lost: ''The Walls of Forgetting'' (memory carvings in five scripts beneath a shrine near Carchemish) and ''The Monastery Diary'' both vanish, taking their stored memories with them.

The final act takes place in early modern Europe. Karmiš witnesses the Atlantic slave trade first-hand and begins compiling ''The Margins of Manifest''—a cipher-folio of names taken from shipping manifests and punishment ledgers. His response to prompt 66a captures the shift:

<blockquote>
''It is no longer a question of restraint. That was a younger version of me—one who believed self-control made me different from the others. Now I am different in purpose, not method. I feed from slavers and call it justice, but the blood tastes the same.''
</blockquote>

His companion in the final centuries is Mirelde of Bracha—an immortal who becomes his mirror, partner, and ultimately his historian. Together they rediscover a clay tablet bearing his original name in a Venetian bookseller's back room (prompt 68a, 1704 CE), and in a ruined estate outside Smyrna Mirelde finds the remains of a life Karmiš can no longer remember.

At the story's end Karmiš retains only five active memories, three diary memories, two marks (''The Unblinking Eye''—a scar that burns in the presence of lies—and ''The Gesture Forbidden''—an involuntary court gesture mistaken for mockery), and three possessions: his diary ''Kept Against Forgetting'', the clay tablet bearing his name, and the slave-trade folio. Of the eleven characters he encountered, only four remain: Ashurban (his distant maker), Mirelde (his companion), Thoöni's ghost, and a nameless figure known only as ''The One Who Does Not Answer''. Over 34 prompts he accumulated 37 experiences, gained and lost a memory slot each, and burned through three separate diaries.

The character's story is narrated in the epilogue not by Karmiš himself but by Mirelde, who insists: "He has not died. [...] Just a man who remembered too much, for too long. And chose, in the end, ''peace''."

== Testing ==

=== Backend ===

Tests are run with '''pytest''' and '''pytest-django''':

<pre>
pytest
</pre>

Test files include:
* <code>vampire/test_models.py</code> – model unit tests
* <code>tyov_api/test_api.py</code> – API endpoint integration tests
* <code>tyov_api/test_models.py</code> – API model tests
* <code>authentication/test_views.py</code> – authentication tests

=== Frontend ===

End-to-end tests use '''Playwright''':

<pre>
cd frontend
npx playwright test
</pre>

Test specs include:
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard
* <code>e2e/tyov-game.spec.ts</code> – game loop testing
* <code>e2e/vue.spec.ts</code> – general Vue component tests

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]

Thousand Year Old Vampire

2026-04-12T11:21:35Z

Mvuijlst:

{{Infobox
| 01_name = Thousand Year Old Vampire – Web Helper
| 02_logo =
| 03_developer = Michel Vuijlsteke
| 04_programming language = Python (Django 5), TypeScript (Vue 3)
| 05_operating system = Cross-platform (Web)
| 06_genre = Solo RPG Digital Companion
| 07_license = custom
| 08_website = <code>https://tyov.yusupov.cloud</code>
}}

'''Thousand Year Old Vampire – Web Helper''' ('''TYOV-Web''') is a modern web-based implementation of the solo tabletop role-playing game ''Thousand Year Old Vampire'' by Tim Hutchings. The application digitises the game's complex mechanics of memory, experience, and character development, allowing players to create and guide a vampire character across centuries of unlife through an interactive browser interface. The backend is built with '''Django 5''' and '''Django REST Framework'''; the frontend is a '''Vue 3''' single-page application.

== Overview ==

''Thousand Year Old Vampire'' is a solo storytelling RPG in which a player creates a vampire character and guides it through an increasingly fragmented existence spanning hundreds or thousands of years. The central tension lies in the vampire's deteriorating memory: as an immortal being it accumulates experiences, but its ancient mind can only retain a limited number of memories at any time. Players must constantly choose what to remember and what to forget.

TYOV-Web fully implements the game's rules—character creation, dice-driven prompt navigation, memory management, diary storage, skills, resources, marks, known characters, and game-ending conditions—in a reactive web interface with persistent server-side storage and a complete audit trail.

== Game Rules ==

=== Core Concept ===

The player creates a vampire and progresses through numbered '''prompts''' (story scenarios). Each prompt asks the player to narrate what happens to the vampire during a particular era. The game is non-linear: dice rolls determine which prompt to visit next, and most prompts have multiple '''variations''' (A, B, C) to prevent repetition.

=== Character Creation ===

Character creation follows a guided six-step wizard:

{| class="wikitable"
|-
! Step !! Description
|-
| 1. Mortal Life || Establish the vampire's name, background, and mortal existence
|-
| 2. Mortal Characters || Define 2–4 NPCs from the vampire's human life (friends, mentors, rivals, lovers)
|-
| 3. Skills || Choose 2–3 starting skills representing mortal expertise
|-
| 4. Resources || Select initial possessions and locations
|-
| 5. Combination Experience || Write a pivotal mortal-life experience that ties characters, skills, and resources together
|-
| 6. The Turning || Narrate how and why the character was turned into a vampire
|}

=== Memory System ===

The memory system is the heart of the game:

* A character may hold a maximum of '''5 active memories''' (adjustable by prompt rules and permanent effects).
* Each memory can contain up to '''3 experiences''' (individual narrative entries).
* When the limit is exceeded, the player must '''forget''' (permanently lose) a memory, or '''move''' one to a '''diary''' (if the character possesses one).
* A '''diary''' is a special resource that stores up to '''4 additional memories''' outside the active limit.
* If the diary resource is lost, all memories stored in it are also lost.
* Some prompts grant or remove permanent memory slots (<code>memory_slot_gain</code>, <code>memory_slot_loss</code>).

=== Dice Rolling and Prompt Navigation ===

Each turn the player rolls two dice:

* '''D10''' (1–10) minus '''D6''' (1–6) = result (range: −5 to +9).
* A '''positive''' result moves forward that many prompts.
* A '''negative''' result moves backward.
* A result of '''zero''' stays at the current prompt number but selects the next unused variation.

Variations are visited in order A → B → C. If all variations of a prompt have been used, the system finds the next available variation in prompt order.

=== Turn Structure ===

Each game turn follows this sequence:

# '''Prompt Presentation''' – The current prompt text and any special rules are displayed.
# '''Dice Roll''' – The player rolls D10 − D6 to determine the next prompt.
# '''Experience Creation''' – The player writes at least one narrative experience for the current prompt.
# '''Character Updates''' – Skills, resources, marks, and known characters may be added, edited, checked, or removed.
# '''Memory Management''' – The player resolves any memory overflow (forget or move to diary).
# '''Validation''' – The system verifies all rules are satisfied (at least one experience added, memory limits respected, etc.).
# '''Continue''' – All pending changes are atomically committed and the game advances to the next prompt.

=== Character Attributes ===

{| class="wikitable"
|-
! Attribute !! Description
|-
| '''Skills''' || Learned abilities; can be ''normal'' (latent), ''checked'' (used/active), or ''lost'' (permanently removed).
|-
| '''Resources''' || Possessions or locations; typed as ''portable'' or ''stationary''. One resource may be flagged as a ''diary''.
|-
| '''Marks''' || Physical or psychological scars that accumulate over time.
|-
| '''Known Characters''' || NPCs the vampire has encountered; typed as ''mortal'' or ''immortal''; may be lost (dead, vanished, etc.).
|}

=== Special Prompt Rules ===

Certain prompts carry special mechanics encoded as rules:

{| class="wikitable"
|-
! Rule !! Effect
|-
| <code>no_experience</code> || Experience creation is disabled for this turn
|-
| <code>allow_name_change</code> || The player may change the vampire's name
|-
| <code>memory_modification</code> || The player may edit the text of existing experiences
|-
| <code>memory_slot_loss</code> || Permanent reduction of memory capacity by 1
|-
| <code>memory_slot_gain</code> || Permanent increase of memory capacity by 1
|-
| <code>game_over</code> || The game ends; the player writes an epilogue
|}

=== Game Ending ===

The game ends when the player reaches a prompt with the <code>game_over</code> rule (or under other conditions defined by the original game). The player writes an '''epilogue'''—a final reflection on the vampire's story—and the character is archived. A statistics summary shows prompt count, memories, experiences, skills, resources, marks, and characters accumulated during the playthrough.

== Architecture ==

=== Technology Stack ===

{| class="wikitable"
|-
! Layer !! Technology !! Version
|-
| Backend framework || Django || 5.0.6
|-
| REST API || Django REST Framework || 3.15.1
|-
| Authentication || Simple JWT (custom) || 5.3.0
|-
| CORS || django-cors-headers || 4.3.1
|-
| Image handling || Pillow || 11.3.0
|-
| Production server || Gunicorn || 21.2.0
|-
| Frontend framework || Vue.js || 3.5
|-
| State management || Pinia || 3.0
|-
| Routing || Vue Router || 4.5
|-
| HTTP client || Axios || 1.10
|-
| CSS framework || Bootstrap || 5.3
|-
| Build tool || Vite || 7.0
|-
| Language || TypeScript || 5.8
|-
| Testing (backend) || pytest + pytest-django || 8.0 / 4.8
|-
| Testing (frontend) || Playwright || 1.53
|}

=== High-Level Diagram ===

<pre>
┌─────────────────────────────────────────────────┐
│ Vue 3 SPA (TypeScript) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│ │ Views │ │Components│ │ Pinia Stores ││
│ │ (7 pages)│ │ (14+) │ │ auth/game/theme/ ││
│ │ │ │ │ │ characterCreation ││
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘│
│ └─────────────┴────────────────┘ │
│ │ Axios │
│ ▼ │
├─────────────────────────────────────────────────┤
│ Django REST API │
│ /api/auth/login /api/auth/verify │
│ /api/characters/ (CRUD + game_state, │
│ roll_dice, continue_story, audit_trail) │
│ /api/characters/<id>/memories/ │
│ /api/characters/<id>/experiences/ │
│ /api/characters/<id>/skills/ │
│ /api/characters/<id>/resources/ │
│ /api/characters/<id>/marks/ │
│ /api/characters/<id>/characters/ │
│ /api/characters/<id>/pending-changes/ │
│ /api/prompts/ │
├─────────────────────────────────────────────────┤
│ Django ORM / SQLite │
│ Character · Memory · Experience · Skill │
│ Resource · Mark · GameCharacter · Prompt │
│ PendingChange · GameStateSnapshot │
└─────────────────────────────────────────────────┘
</pre>

== Backend ==

=== Django Apps ===

The project is organised into three Django apps plus a settings module:

{| class="wikitable"
|-
! App !! Purpose
|-
| <code>vampire</code> || Core domain models: Character, Memory, Experience, Skill, Resource, Mark, GameCharacter, Prompt, PendingChange, GameStateSnapshot
|-
| <code>tyov_api</code> || REST API layer: serialisers, viewsets, URL routing, permissions, middleware
|-
| <code>authentication</code> || JWT-based login and token verification endpoints
|-
| <code>tyov_backend</code> || Django project settings, URL root, WSGI/ASGI configuration
|}

=== Data Models ===

==== Character ====

The central model, owned by a Django <code>User</code> via a ForeignKey:

{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>name</code> || CharField(200) || Current name of the vampire
|-
| <code>description</code> || TextField || Background/appearance description
|-
| <code>image</code> || ImageField || Optional character portrait
|-
| <code>current_prompt</code> || CharField(10) || ID of the current prompt (e.g. "17a")
|-
| <code>last_dice_roll</code> || JSONField || Stores D10, D6, and result of the last roll
|-
| <code>visited_prompts</code> || JSONField(list) || List of all prompt IDs visited in order
|-
| <code>memory_slots_lost</code> || IntegerField || Permanent memory slot reductions
|-
| <code>memory_slots_gained</code> || IntegerField || Permanent memory slot increases
|-
| <code>creation_step</code> || IntegerField(1–6) || Tracks progress through the creation wizard
|-
| <code>is_creation_complete</code> || BooleanField || True when all six creation steps are finished
|-
| <code>creation_data</code> || JSONField || Temporary storage during creation
|-
| <code>epilogue</code> || TextField || Player's final reflection (set at game end)
|-
| <code>is_completed</code> || BooleanField || Whether the story has ended
|-
| <code>completed_at</code> || DateTimeField || Timestamp of story completion
|}

==== Memory ====

A memory belongs to a Character and holds up to 3 Experiences:

* <code>title</code> – descriptive name (unique per character)
* <code>in_diary</code> – whether the memory is stored in the diary
* <code>is_lost</code> – whether the memory has been forgotten

==== Experience ====

An individual narrative entry within a Memory:

* <code>title</code> – optional short description
* <code>content</code> – the narrative text
* <code>prompt_id</code> – which prompt generated this experience
* <code>date_info</code> – temporal context (e.g. "Winter, 431 CE")

==== Skill ====

* <code>name</code>, <code>description</code>
* <code>status</code> – one of <code>normal</code>, <code>checked</code>, or <code>lost</code>

==== Resource ====

* <code>name</code>, <code>description</code>
* <code>resource_type</code> – <code>portable</code> or <code>stationary</code>
* <code>is_diary</code> – flags the special diary resource (constrained to one active diary per character)
* <code>is_lost</code>

==== Mark ====

* <code>name</code>, <code>description</code>
* <code>is_lost</code>

==== GameCharacter ====

* <code>name</code>, <code>description</code>
* <code>character_type</code> – <code>mortal</code> or <code>immortal</code>
* <code>relationship</code> – e.g. friend, rival, mentor, love, enemy, neutral
* <code>is_lost</code>

==== Prompt ====

* <code>prompt_id</code> – e.g. "17a", "32b"
* <code>number</code>, <code>variation</code> – parsed components for sorting
* <code>content</code> – the scenario text
* <code>rules</code> – special mechanics as comma-separated tokens (e.g. <code>no_experience, allow_name_change</code>)

==== PendingChange ====

Temporary storage for changes before they are atomically committed on "Continue":

* <code>change_type</code> – experience, memory, skill, resource, mark, or character
* <code>change_data</code> – JSON payload of the change

==== GameStateSnapshot (Audit Trail) ====

Automatically created each turn to record the complete game state:

* <code>turn_number</code> – sequential, starting from 1
* <code>prompt_id</code> / <code>next_prompt_id</code> – transition
* <code>dice_roll</code> – raw dice data
* <code>game_state</code> – full JSON snapshot of all memories, skills, resources, etc.
* <code>changes_applied</code> – JSON array of pending changes that were committed
* <code>created_at</code> – timestamp

=== API Endpoints ===

All endpoints require JWT authentication (except login).

==== Authentication ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| POST || <code>/api/auth/login/</code> || Authenticate with username/password; returns JWT token
|-
| POST || <code>/api/auth/verify/</code> || Verify current token and return user info
|}

Login is rate-limited to 5 requests per minute per IP.

==== Characters ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || <code>/api/characters/</code> || List all characters for the authenticated user
|-
| POST || <code>/api/characters/</code> || Create a new character
|-
| GET || <code>/api/characters/{id}/</code> || Retrieve full character detail (prefetched relations)
|-
| PUT/PATCH || <code>/api/characters/{id}/</code> || Update character fields
|-
| DELETE || <code>/api/characters/{id}/</code> || Delete a character
|-
| GET || <code>/api/characters/{id}/game_state/</code> || Complete game state including prompt, validation, dice info
|-
| POST || <code>/api/characters/{id}/roll_dice/</code> || Roll D10 − D6 and store the result
|-
| POST || <code>/api/characters/{id}/continue_story/</code> || Validate, commit pending changes, advance to next prompt
|-
| GET || <code>/api/characters/{id}/audit_trail/</code> || View turn-by-turn audit history
|-
| GET || <code>/api/characters/{id}/game-state-changes/</code> || Timeline of state changes between turns
|}

==== Nested Character Resources ====

For each character, full CRUD is available on:

* <code>/api/characters/{id}/memories/</code> (plus <code>move_to_diary</code> and <code>restore_lost_memory</code> actions)
* <code>/api/characters/{id}/experiences/</code>
* <code>/api/characters/{id}/skills/</code>
* <code>/api/characters/{id}/resources/</code>
* <code>/api/characters/{id}/marks/</code>
* <code>/api/characters/{id}/characters/</code> (known NPCs)
* <code>/api/characters/{id}/pending-changes/</code>

==== Prompts ====

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || <code>/api/prompts/</code> || List all game prompts
|-
| GET || <code>/api/prompts/{prompt_id}/</code> || Retrieve a single prompt by ID
|}

=== Permissions and Security ===

* All character data is scoped to the authenticated user via <code>IsCharacterOwner</code> permission.
* JWT tokens are sent as <code>Authorization: Bearer {token}</code> headers.
* The login endpoint is throttled (5/minute) to prevent brute-force attacks.
* All pending changes are processed inside a database '''transaction''' to guarantee atomicity.
* CORS headers are configured via <code>django-cors-headers</code>.

== Frontend ==

=== Views (Pages) ===

{| class="wikitable"
|-
! View !! Route !! Description
|-
| '''LoginView''' || <code>/login</code> || Authentication form; redirects authenticated users to home
|-
| '''HomeView''' || <code>/</code> || Dashboard showing all active characters in a card grid
|-
| '''CharacterCreationView''' || <code>/character-creation/:id</code> || Six-step creation wizard
|-
| '''GameView''' || <code>/game/:characterId</code> || Main game loop: prompt display, experience form, dice rolling, entity management, memory display
|-
| '''GameEndedView''' || <code>/game/:characterId/ended</code> || End-of-story screen with statistics and epilogue
|-
| '''RecordsView''' || <code>/records</code> || Archive of current and completed characters
|-
| '''StoryView''' || <code>/story/:characterId</code> || Narrative timeline with experience history, character stats sidebar, and epilogue
|}

All routes except <code>/login</code> require authentication. The router guard redirects unauthenticated users.

=== Key Components ===

{| class="wikitable"
|-
! Component !! Purpose
|-
| '''PromptSection''' || Displays the current prompt text, special rules, and dice roll results
|-
| '''ExperienceForm''' || Form for writing new experiences with title, date, content, and memory selection
|-
| '''MemoriesDisplay''' || Shows active, diary, and lost memories with experience counts; includes move-to-diary, delete, and restore actions
|-
| '''GameDataSection''' || Reusable list for skills, resources, or marks with add/edit/delete controls
|-
| '''CharactersSection''' || Grid of known NPCs with type badges and edit/delete
|-
| '''EntityCreationWindow''' || Draggable modal for creating/editing skills, resources, marks
|-
| '''CharacterCreationWindow''' || Draggable modal for creating/editing NPC characters
|-
| '''ExperienceEditWindow''' || Window for editing existing experience text
|-
| '''DiaryCreationModal''' || Modal for creating a diary resource and moving a memory into it
|-
| '''ConfirmationDialog''' || Generic confirmation dialog for destructive actions
|-
| '''ValidationWarning''' || Displays validation errors when game rules are not satisfied
|}

=== State Management (Pinia) ===

Four Pinia stores manage application state:

{| class="wikitable"
|-
! Store !! Responsibility
|-
| '''auth''' || JWT token, user object, login/logout, token expiry handling
|-
| '''game''' || Characters list, current character, game state, all CRUD actions for entities, dice rolling, story continuation
|-
| '''characterCreation''' || Multi-step wizard data, initial character creation
|-
| '''theme''' || Dark/light mode toggle with localStorage persistence
|}

=== API Service Layer ===

* '''<code>api.ts</code>''' – Axios instance with base URL auto-detection (development vs. production), request interceptor for JWT headers, response interceptor for 401/token-expiry handling.
* '''<code>gameService.ts</code>''' – All API call methods: authentication, character CRUD, dice rolling, story continuation, memory/experience/skill/resource/mark/character management.
* '''<code>entityService.ts</code>''' – Generic <code>EntityService</code> class instantiated for skills, resources, marks, and characters for DRY CRUD operations.

=== Composables ===

Vue composables encapsulate reusable business logic:

* '''<code>useGameData()</code>''' – Computed properties derived from the game store (current character, memories, skills, resources, etc.)
* '''<code>useExperienceForm()</code>''' – Form state, validation, memory selection, and reset logic
* '''<code>useEntityManagement()</code>''' – Generic CRUD operations with optional confirmation dialogs
* '''<code>useSkillManagement()</code>''', '''<code>useResourceManagement()</code>''', '''<code>useMarkManagement()</code>''', '''<code>useMemoryManagement()</code>''' – Specialised wrappers
* '''<code>useConfirmationDialog()</code>''' – Promise-based modal confirmation
* '''<code>useMemoryDisplay()</code>''' – Display logic for memories including pending-change awareness
* '''<code>useExperienceDisplay()</code>''' – Markdown rendering for experience content
* '''<code>usePendingChangesDisplay()</code>''' – Badge rendering for undo-able pending changes

== Audit Trail ==

The application includes an automatic audit trail that captures the complete game state every time the player advances to a new prompt.

Each '''GameStateSnapshot''' records:

* The turn number (sequential from 1)
* The prompt transition (e.g. 36a → 34a)
* The dice roll
* A complete JSON snapshot of all memories, skills, resources, marks, and known characters
* All pending changes that were committed

The audit trail is accessible via:

* '''API''': <code>GET /api/characters/{id}/audit_trail/</code> with optional <code>?turn=N</code> and <code>?limit=N</code> parameters
* '''Management command''': <code>python manage.py view_audit_trail {id} [--summary] [--turn N] [--export file.json]</code>
* '''Timeline API''': <code>GET /api/characters/{id}/game-state-changes/</code> for a structured timeline of all state changes

== Deployment ==

=== Local Development ===

<pre>
.\startup.ps1
</pre>

This script creates a virtual environment, installs dependencies, runs migrations, and starts both the Django backend (<code>http://localhost:8000</code>) and the Vue dev server (<code>http://localhost:5173</code>).

=== Production ===

* Set <code>DJANGO_ENV=production</code>
* Build the frontend: <code>cd frontend && npm run build</code>
* Serve with Gunicorn behind a reverse proxy
* Static files are collected into the <code>static/</code> directory
* The production frontend points to <code>https://tyov.yusupov.cloud</code>

== Example: A Finished Character ==

The following is an example of a character from an actual playthrough stored in the application database. It demonstrates how the game's mechanics play out over an extended narrative.

=== Karmiš (formerly Ekurzu / Naram) ===

'''Description:''' Naram was a temple scribe in the ancient city of Mari: meticulous, observant, and deeply entangled in the political and spiritual life of the city. His life was shaped by clay tablets, omens, and whispered secrets carried through palace corridors and temple courtyards. Behind his calm demeanor lies a mind constantly at work—recording, interpreting, and surviving.

'''Prompts visited:''' 34 prompts across variations, including: 1a, 4a, 11a–c, 12a, 17a, 20a, 24a, 25a, 32a–b, 34a–36a, 37a–41c, 43a–c, 47a, 52a, 57a, 64a, 66a, 68a, 71a, 73a.

'''Final prompt:''' 73a

'''Memory slots lost:''' 1 · '''Memory slots gained:''' 1 (net effect: standard 5-memory limit)

==== Epilogue ====

<blockquote>
He has not died. Let me say that plainly. There will be no grave, no crumbling tomb, no name worn smooth by time. He is alive—quietly, deliberately, and utterly outside your reach.

This book is not a memorial. It is a reckoning.

When I first met him, I did not understand what he was. He wore his years like dust on old vellum—thin, barely visible, but ever present. [...] Over time, I became his mirror, then his partner, and—finally—his historian.

But someone has to begin the telling. Someone has to place the first stone. So this book begins in a house of quiet gardens and low ceilings, where he writes in the mornings and feeds only when he must. [...]

Just a man who remembered too much, for too long. And chose, in the end, ''peace''.

— ''Mirelde''
</blockquote>

==== A Life in Summary ====

Karmiš's story spans roughly three and a half thousand years. It begins in Bronze Age Mesopotamia, where the mortal scribe Naram serves in the temple of Ishtar at Mari—writing omens, navigating palace intrigue, and falling in love with a woman named Hessa who moves through the court "like smoke." His mentor, the High Priest Ibbi-Zamri, is the first person he kills after being turned by the ancient vampire Ashurban the Veiled.

The early centuries are defined by guilt and exile. Fleeing with his mortal companion Ennatum, the newly-made vampire—now calling himself Ekurzu—struggles to control his hunger. He builds walls and plays flutes in the wilderness, but it is "never penance, only a cage with softer bars." Eventually the hunger wins: he devours Ennatum during a sandstorm and spends the following decades alone.

The middle game carries the character through the great civilisations of antiquity—Amarna under Akhenaten, the Achaemenid Royal Road, the libraries of Alexandria—always in the role of scribe, forger, or quiet observer. He accumulates skills like ''Silent Cartography'' ("I trace the unseen paths between people, places, and power") and ''Ash-Tongue'' ("I speak in soot and suggestion, in the cracks between laws"), but loses others as the centuries erode his identity: the ability to ''Decipher Ancient Texts'' and even ''I Control the Beast'' both slip away.

A pivotal relationship develops with the scholar Thoöni, who recognises the name ''Ekurzu'' not as myth but as continuity. Later—after Thoöni's mortal death—her spectral echo begins appearing in the margins of his diary, scratching fragments in languages he can no longer read.

By the late Roman period Karmiš has lost so many memories that he can barely hold a conversation. The game's memory mechanics enforce this viscerally: eight of his sixteen memories were permanently forgotten, including ''The Turning'' itself—the vampire no longer remembers how he was made. He compensates by keeping diaries, but even those are lost: ''The Walls of Forgetting'' (memory carvings in five scripts beneath a shrine near Carchemish) and ''The Monastery Diary'' both vanish, taking their stored memories with them.

The final act takes place in early modern Europe. Karmiš witnesses the Atlantic slave trade first-hand and begins compiling ''The Margins of Manifest''—a cipher-folio of names taken from shipping manifests and punishment ledgers. His response to prompt 66a captures the shift:

<blockquote>
''It is no longer a question of restraint. That was a younger version of me—one who believed self-control made me different from the others. Now I am different in purpose, not method. I feed from slavers and call it justice, but the blood tastes the same.''
</blockquote>

His companion in the final centuries is Mirelde of Bracha—an immortal who becomes his mirror, partner, and ultimately his historian. Together they rediscover a clay tablet bearing his original name in a Venetian bookseller's back room (prompt 68a, 1704 CE), and in a ruined estate outside Smyrna Mirelde finds the remains of a life Karmiš can no longer remember.

At the story's end Karmiš retains only five active memories, three diary memories, two marks (''The Unblinking Eye''—a scar that burns in the presence of lies—and ''The Gesture Forbidden''—an involuntary court gesture mistaken for mockery), and three possessions: his diary ''Kept Against Forgetting'', the clay tablet bearing his name, and the slave-trade folio. Of the eleven characters he encountered, only four remain: Ashurban (his distant maker), Mirelde (his companion), Thoöni's ghost, and a nameless figure known only as ''The One Who Does Not Answer''. Over 34 prompts he accumulated 37 experiences, gained and lost a memory slot each, and burned through three separate diaries.

The character's story is narrated in the epilogue not by Karmiš himself but by Mirelde, who insists: "He has not died. [...] Just a man who remembered too much, for too long. And chose, in the end, ''peace''."

== Testing ==

=== Backend ===

Tests are run with '''pytest''' and '''pytest-django''':

<pre>
pytest
</pre>

Test files include:
* <code>vampire/test_models.py</code> – model unit tests
* <code>tyov_api/test_api.py</code> – API endpoint integration tests
* <code>tyov_api/test_models.py</code> – API model tests
* <code>authentication/test_views.py</code> – authentication tests

=== Frontend ===

End-to-end tests use '''Playwright''':

<pre>
cd frontend
npx playwright test
</pre>

Test specs include:
* <code>e2e/character-creation-workflow.spec.ts</code> – character creation wizard
* <code>e2e/tyov-game.spec.ts</code> – game loop testing
* <code>e2e/vue.spec.ts</code> – general Vue component tests

== See Also ==

* ''Thousand Year Old Vampire'' by Tim Hutchings – the original tabletop game
* [[Django (web framework)]]
* [[Vue.js]]
* [[Single-page application]]

== References ==

{{Reflist}}

[[Category:Web applications]]
[[Category:Role-playing video games]]
[[Category:Django (web framework) applications]]
[[Category:Vue.js applications]]
[[Category:Solo role-playing games]]