Skip to content

Adopt a lore repository

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: none, retired with Core.

Adoption turns an existing Nerthus lore repository (repozytorium-fabularne) into one the tool manages. It happens once in a repository's life, before anybody records a session against it. Until it has run, the daemon refuses every write.

One script runs the whole thing: it imports your files, fetches the session logs, derives the map doors, builds the Lokacje/ folder, and checks the maps. When it finishes you have a managed repository: the hand-written Polish files exactly as they were, plus the generated files the tool reads and writes from then on.

The script never touches Git. Reviewing the result and committing it is a human decision, and it is the last step on this page.

Adoption is a hosting task, but it needs no programming - the steps below are copy-paste, and everything after them happens in the operator tab. The mechanism behind it, and why re-running is safe, is the adoption model.

What you need before you start

  • PowerShell 7.2 or newer. Check it with $PSVersionTable.PSVersion.
  • A local clone of repozytorium-fabularne - the working tree with Postaci/, Wątki/, Świat gry/, and Organizacje/. The repository lives at https://gitlab.com/margonem/nerthus/narratorzy/repozytorium-fabularne and is closed - only contributors can open it. Clone it with the GitLab account that carries your membership, into ~/nerthus/repozytorium-fabularne - that is the path this page uses.
  • Git. The repository is a Git working tree, and you commit the generated files at the end.
  • Gracze.md - the roster file. It is needed only the first time a repository is adopted. A clone whose nerthus.contributors.md already carries the ## Osoby section does not need it anymore.

Each command below talks to a small background service that starts itself when needed. You never manage it by hand. One service serves one repository, so if another shell already started it, your shell finds it and reuses it.

1. Install the module

Clone the module repository and import the manifest by path:

git clone https://gitlab.com/margonem/nerthus/it/nerthus.core.git ~/nerthus/Nerthus.Core
Import-Module ~/nerthus/Nerthus.Core/Nerthus.Core.psd1

After the import, the Verb-Nerthus* cmdlets are available in that shell.

The daemon those cmdlets start loads a compiled C# assembly that a fresh clone does not carry, so a device without a matching .NET SDK fails here with a timeout rather than with the missing file. Run the daemon locally in Docker is the way past that: the image carries the assembly, and the import runs against the container instead.

2. Preview the setup

Dry-run the setup first:

~/nerthus/Nerthus.Core/vm/Initialize-NerthusLoreRepo.ps1 -Repo ~/nerthus/repozytorium-fabularne -WhatIf

-WhatIf renders what the setup would write, without writing anything. On a repository the tool has never seen the preview covers the import alone, and says so - the later stages need a repository that is already set up. Review the preview before the real run.

3. Run the setup

~/nerthus/Nerthus.Core/vm/Initialize-NerthusLoreRepo.ps1 -Repo ~/nerthus/repozytorium-fabularne

Setting up a repository is this one command. It prints one line per stage as it goes:

  1. Import. Reads Gracze.md, Postaci/, Organizacje/, Świat gry/, and Wątki/, and writes nerthus.entities.md at the repository root - the index of Gracze, Postacie, NPC, Grupy, Lokacje, and Margonem maps. It moves the free narrator notes out of the roster into the character files under Postaci/Gracze/, in each file's **Dodatkowe informacje:** section, recovers the record of which sessions were already awarded PU so nothing is paid out a second time, and writes the Lokacje/ folder - one subfolder per known place, each with a generated Sesje.md listing the sessions that happened there. See record a session for how to read that folder.
  2. Session logs. Downloads every game transcript linked from the sessions' Logi metadata into nerthus.logs/. That archive belongs in repozytorium-transkryptow — see Splitting out the transcript archive — and lands at the lore repository root only on a host that has not been given one. Once a transcript is archived, every future clone reads it offline, even after the original hosting disappears. A link that fails to download is recorded and retried later on its own. Over a cold archive of a few thousand transcripts this stage takes many minutes. More in session logs.
  3. Map doors. Reads the archived transcripts and derives the @drzwi (door) connections between places. Each derived door is written on both sides, on the Mapa and the Lokacja block alike, and marked (auto). Doors are covered in doors between places.
  4. The Lokacje/ folder. Reports how the sessions were filed by place, and rebuilds any generated Sesje.md that is missing.
  5. Maps. Sweeps every Mapa entity's map image and retires outdated versions. Maps and the location tree are covered in locations.

Until the setup has run, the tool refuses every change to the repository. Running it is the remedy, and writing opens the moment the import finishes.

Two stages need the network - the session logs and the maps. Skip either one on a run that should stay local:

~/nerthus/Nerthus.Core/vm/Initialize-NerthusLoreRepo.ps1 -Repo ~/nerthus/repozytorium-fabularne -SkipLogs -SkipMapCheckup

If a transcript host is down, the setup says so and carries on with the remaining stages - those logs are retried on a later run.

Where the roster notes land

The notes move by whose notes they are:

  • A note written about a character goes into that character's own file.
  • A player's own note goes into the file of that player's active character. If the player has no active character, it goes to the first of their characters whose file resolves.

A note naming a character the tool cannot resolve does not stop the run. It stays in Gracze.md for you to place by hand.

Gracze.md itself is a frozen archive. The setup reads it once and never writes to it - the notes are read out of it and written into the character files, and the roster file is left exactly as it is.

The same rule holds everywhere else: the setup never rewrites a hand-authored Polish source file. It reads your files and emits its own.

A second run is safe

Re-running the setup on an unchanged repository produces the same result - the same index, the same Sesje.md files, the same bytes. A note already sitting in a character file is not appended twice, and a session already paid out is never paid out again. Re-running costs you nothing but the time.

After the first run, the ## Osoby section of nerthus.contributors.md and the ## Postacie Graczy section of the index are yours to hand-edit, and a later run carries them over untouched - see people and roles and player characters.

4. Check the result

Get-NerthusStatus

status        : ok
mode          : ReadWrite
uptimeSeconds : 42.7
requestCount  : 1
entities      : 3513
pid           : 48213

mode : ReadWrite confirms the setup completed and writing is open. entities is how many blocks the index now carries. Now query the data:

Find-NerthusEntity -Name 'Thuzal' | Select-Object Name, Type, Status, FilePath

Name   Type    Status  FilePath
----   ----    ------  --------
Thuzal Lokacja Aktywny /Świat gry/Thuzal.md

The tool understands Polish declension, so an inflected name written in session prose still finds its entity:

Resolve-NerthusName -Name 'Erastera'      # → Eraster
Resolve-NerthusName -Name 'Tussalem'      # → Lord Tussal
Resolve-NerthusName -Name 'Ithanie'       # → Ithan

You do not have to write canonical names in your prose for the tool to follow it. Name matching and the @alias tag are covered in add and edit entities.

Look up a Gracz and the Postacie they own:

Get-NerthusPlayer -Name 'Eraster' | Select-Object Name, Type, Status, MargonemId
Get-NerthusPlayerCharacter -Player 'Eraster' | Format-Table Name, Status, PuSuma

Name          Status     PuSuma
----          ------     ------
Eraster       Aktywny    127.90
Losso Minewit Nieaktywny 42.1
Felkissian    Nieaktywny 52.95
Klusp         Nieaktywny 65.40

Each character carries its own PU total. That is the shape you will see everywhere - see grant PU.

5. Commit the setup

The setup runs no Git command, so everything it wrote is sitting in your working tree. Review the diff, then commit:

cd ~/nerthus/repozytorium-fabularne
git add nerthus.entities.md Lokacje/ Postaci/ .nerthus/
# nerthus.logs/ only if this host has no separate transcript archive — see the runbook below.
git rm Gracze.md
git commit -m "Adopt repo into Nerthus.Core"

What each path carries:

  • nerthus.entities.md - the generated index.
  • nerthus.logs/ - the archived transcripts, if they landed here rather than in the transcript repository.
  • Lokacje/ - the sessions filed by place.
  • Postaci/ - the roster notes now living in the character files.
  • .nerthus/ - the tool's own settings. Its private working files are gitignored automatically, so only the shareable parts are staged.

git rm Gracze.md retires the roster file. Everything it carried now lives in the index and the character files, and Git history keeps the archive. The tool never deletes Gracze.md itself - this commit is your decision as the operator.

6. Stop the background service (optional)

Stop-Nerthus

Stopping is optional. The next Verb-Nerthus* cmdlet starts a fresh one on its own. Pass -StopDaemon to the setup script to have it stop the service for you when it finishes.

Running one stage on its own

The script runs the five stages in order because each one needs what the stage before it wrote. Once a repository is set up you can also run a single stage, which is what you want when only one thing changed:

cd ~/nerthus/repozytorium-fabularne
Initialize-NerthusRepo                       # re-import after hand-editing the Polish files
Invoke-NerthusSessionLogFetch                # fetch newly linked transcripts
Invoke-NerthusReindex                        # re-derive the map doors
Invoke-NerthusSessionRegistryRegenerate      # rebuild the Lokacje/ folder
Invoke-NerthusMapCheckup                     # retire outdated map images

Each one takes -WhatIf and previews without writing, exactly as the whole script does.

Next in this tab:

What the operators do with the result: