Skip to content

Set up the repository

This page walks you through preparing the Nerthus lore repository (repozytorium-fabularne, the GitLab repo behind nerthus.pl) for the tool. You run a one-time import, look at what it produced, fetch the session logs, derive the map doors, check the maps, and commit the result. When you finish you have a managed repository: your hand-written Polish files exactly as you wrote them, plus one generated file at the root - nerthus.entities.md, the unified index the tool reads and writes from then on.

This is the one page that names commands. Everywhere else you write Markdown by hand.

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 index already carries the ## Gracze roster 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 <nerthus-powershell-repo-url> ~/nerthus/Nerthus.Core
Import-Module ~/nerthus/Nerthus.Core/Nerthus.Core.psd1

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

2. Preview the import

Go into the lore repository and dry-run the import first:

cd ~/nerthus/repozytorium-fabularne
Initialize-NerthusRepo -WhatIf

-WhatIf renders the index the import would write, without writing anything. Review the preview before the real run.

3. Run the import

Initialize-NerthusRepo

Setting up a repository is this one command. The single pass:

  • reads Gracze.md, Postaci/, Organizacje/, Świat gry/, and Wątki/,
  • writes one generated file at the repository root - nerthus.entities.md, the unified index of Gracze, Postacie, NPC, Grupy, Lokacje, and Margonem maps,
  • moves the free narrator notes out of the roster and 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.

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

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 import 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 import never rewrites a hand-authored Polish source file. It reads your files and emits its own.

A second run is safe

Re-running the import on an unchanged repository produces the same result - the same index, 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 ## Gracze and ## Postacie Graczy sections of the index are yours to hand-edit, and a later import carries them over untouched - see players and 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 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. Fetch the session logs

Invoke-NerthusSessionLogFetch

This downloads every game transcript linked from the sessions' Logi metadata into nerthus.logs/, a committed archive at the repository root. Once a transcript is archived, every future clone reads it offline, even after the original hosting disappears. A link that fails to download is retried on the next fetch. More in session logs.

6. Derive the map doors

Invoke-NerthusReindex

The reindex 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 locations. Run this after the log fetch: without the archived transcripts there is nothing to derive doors from.

7. Check the maps

Invoke-NerthusMapCheckup

The checkup sweeps every Mapa entity's map image and retires outdated versions. Maps and the location tree are covered in locations.

8. Commit the setup

Review the diff, then commit:

git add nerthus.entities.md nerthus.logs/ Postaci/ .nerthus/
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.
  • 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.

9. Stop the background service (optional)

Stop-Nerthus

Stopping is optional. The next Verb-Nerthus* cmdlet starts a fresh one on its own.