Governance¶

Governance is the narrator permissions table — Uprawnienia — one row per Narrator, keyed by Margonem ID and stored in private state (never the lore repository). Each row records what a Narrator is allowed to run: ranga, magia, polityka, walki_pvp, and the like. This page covers reading the table and upserting one row. The write example targets Anward, the Narrator of the fixture session.

Reads need governance.read, writes need governance.write; the admin token carries both. Every example runs against a live daemon — see how the reference is tested.

Routes¶

Cap is the required capability (— = public, no token); Write (✓) marks routes that pass the write gate; a — in Cmdlet is reached directly, no wrapper. Paths are relative to /v1/api; the cross-cutting contract — middleware, envelopes, status codes — is on the API reference index.

The {nick} path segment also accepts the Margonem id; a successful edit fires the AfterGovernanceChange hook (governance:changed on the event stream). The Uprawnienia model: Permissions.

Read the permissions table¶

GET /v1/api/governance/permissions returns the { count, items } envelope — every Uprawnienia row. Narrow to one Narrator with ?id= (Margonem ID or nick). A freshly imported repository has no rows yet.

GET /v1/api/governance/permissions
Authorization: Bearer <token>

await fetch("https://evocation.nerthus.pl/v1/api/governance/permissions", {
  headers: { "Authorization": `Bearer ${token}` },
}).then((r) => r.json());

Response 200:

{ "count": 0, "items": [] }

Preview a permission edit without writing¶

PATCH /v1/api/governance/permissions/{nick} upserts the matched row (by Margonem ID or nick) and stamps zmieniono. With ?dryRun=true it returns 200 { wouldUpdate, fields } and persists nothing — proven by the follow-up ?id=Anward read still finding no row.

PATCH /v1/api/governance/permissions/Anward?dryRun=true
Content-Type: application/json
Authorization: Bearer <token>

{ "ranga": "Narrator", "magia": "do 3/5" }

await fetch("https://evocation.nerthus.pl/v1/api/governance/permissions/Anward?dryRun=true", {
  method: "PATCH",
  headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
  body: JSON.stringify({ ranga: "Narrator", magia: "do 3/5" }),
});

Response 200:

{ "wouldUpdate": "Anward", "fields": { "ranga": "Narrator", "magia": "do 3/5" } }