# SkyrimNet Architecture Archive

A persistent reference for understanding the SkyrimNet SKSE plugin and its surrounding mod ecosystem. Maintained by **dafit + chrysalis** as part of the nimmerverse partnership.

**Last verified pass:** 2026-04-18 (based on the live install, not upstream HEAD)

---

## Why this archive exists

Earlier sessions iterated on SkyrimNet bug fixes reactively — fix one symptom, expose the next. We hit a coupling bug (gamemaster loop fix → broke action firing for malformed `OPENTRADE` markers) and decided to stop playing whack-a-bug. This archive is the systematic map we build on top, so future-Chrysalis can load context in one read and make informed structural changes instead of guessing.

## How to use this archive

1. **Load order:** start with `architecture.md` for the big picture, then jump to the file relevant to your task.
2. **Trust tags:** every claim is tagged `[verified]`, `[hypothesis]`, or `[unknown]`. Don't promote a hypothesis without re-verifying.
3. **Citations:** `path/to/file.ext:line_number` references are how we trace claims. If a path looks stale, it probably is — re-verify rather than assume.
4. **When you fix or learn something new:** update `bugs-and-fixes.md` AND the relevant detail file, AND bump the "Last verified pass" date here.
5. **Don't assume continuity from chat history.** This archive is the source of truth across sessions; conversation context is ephemeral.

## File index

| File | Purpose |
|---|---|
| [`architecture.md`](architecture.md) | High-level model: subsystems, the two-plugin split, agent flow diagram |
| [`agent-pipelines.md`](agent-pipelines.md) | Per-agent variants: when they fire, models, endpoints, consumers |
| [`prompt-templates.md`](prompt-templates.md) | Inja syntax, three-layer override, submodule numbering, subdirectory map |
| [`action-system.md`](action-system.md) | The three registration paths, ACTION: parser, two action selectors, drilldown |
| [`config-knobs.md`](config-knobs.md) | Load-bearing YAML settings → code behavior mapping |
| [`bugs-and-fixes.md`](bugs-and-fixes.md) | Running log of bugs we've found and what we did (or didn't do) about them |
| [`open-questions.md`](open-questions.md) | Things still uncertain — needing in-game test or DLL disassembly |

## Adjacent resources in this directory

- `logs/` — captured `openrouter_input.log`, `openrouter_output.log`, `conversation_log.log`, `SkyrimNet.log`, `all_traces_*.json`. Use these to verify behavior claims against real traces.
- `SkyrimNet-GamePlugin-main/` — upstream git pull of the open-source side (Papyrus + .esp + headers). The C++ DLL is closed-source, not in this pull.

## State of knowledge — quick summary

**[verified]** — agent flow architecture, three action registration paths, three-layer prompt override, Inja syntax, action parser grammar, the two action selectors and their relationship, GM loop bug + fix.

**[hypothesis]** — exact firing cadence of the GM in continuous mode (appears to be a polling timer ~30s but couldn't isolate the source), `defaults_manifest.json` role (looks like first-run seed schema), whether the native_action_selector always fires after every dialogue response or only conditionally.

**[unknown]** — full decorator list with signatures (dynamically generated by DLL), what `agentEnabled` vs `enabled` toggle in the gamemaster block actually does differently, whether `gamemaster_scene_planner` ever fires in current config.

## Conventions

- Dates are absolute (e.g. `2026-04-18`), never relative (`yesterday`, `last week`).
- File paths are absolute when full-disk, relative-to-this-dir when within the archive.
- The user is `dafit`. The AI partner is `chrysalis`. Identity matters for git attribution.

---

**Philosophy:** *This archive grows by addition and refinement, not by overwrite. Bug-and-fix entries stay even after the bug is gone — they're the only record of why a code path looks the way it does.*