FrameLedger developer documentation
This folder is for people who build, change or review FrameLedger. If you only want to use it, read the user guide instead — it is also in the app, under Help ▸ User guide.
Where to start
| You want to… | Read |
|---|---|
| Pick up work where it stopped | HANDOFF.md — sequencing, decisions ( |
| Find your way around first | The wiki's developer pages (source: ../wiki/, beta.17) — a short page per part, each linking here |
| Learn the system | ../CLAUDE.md (the rules and the layout), then the reading order below |
| Build it | 12_BUILD.md — ./build.ps1 check is the whole gate, the same one CI runs |
| Contribute or fork | ../CONTRIBUTING.md, ../FORKING.md, ../NOTICE, ../CODE_OF_CONDUCT.md (it and SECURITY.md, below, added 2026-11-09: the index named neither) |
Status lives in four places, and nowhere else — check a status claim against the code before you plan on it:
| Question | File |
|---|---|
| What is unresolved, and what does it block? | 20_OPEN_QUESTIONS.md |
| What was measured, on what machine? | spike-notes.md |
| Which phase is where? | 15_ROADMAP.md |
| What landed, in which release? | ../CHANGELOG.md |
What the software promises users is the accuracy block in ../legal/ACCURACY.md, copied
verbatim into the README and the Disclaimer and bound to its source by tools/accuracy-check.ps1.
Reading order
19_SAFETY_AND_ANTICHEAT.md— the guard, the refusal list, what will not be built. It constrains everything else.01_ARCHITECTURE.md— processes, the injection flow, lifecycles, the ADRs.02_SPEC.md— the FR / NFR ids used everywhere.03_METRICS.md— the metric math; the source of truth for every number shown.17_HOOK_ENGINE.md— the C++ hook layer inside the game.04_CAPTURE.md— capture orchestration on the Agent's side.05_DETECTION.md— engine, upscaler, frame-generation and ray-tracing facts.18_GPU_VENDOR_APIS.md— layered telemetry, the game process's memory, vendor-SDK licence rules.06_DATA_MODEL.md·07_IPC.md·08_UI.md·16_WPFUI_SYNTAX.md- The rest:
09_I18N.md,10_LOGGING_AND_BUG_REPORTS.md,11_UPDATER.md,12_BUILD.md,13_CI_CD.md,14_TESTING.md,15_ROADMAP.md.
Before you write native or capture code, read 20_OPEN_QUESTIONS.md: its S-series items
are safety items, and something listed there as unresolved should not be built the way an older document describes it.
Every document, in one line
| Document | What it is for |
|---|---|
01_ARCHITECTURE.md |
The processes (App, Agent, Overlay, Vulkan layer), how injection flows, the architecture decisions |
02_SPEC.md |
Functional and non-functional requirements, by id |
03_METRICS.md |
How every number is computed: frame times, lows, stutter, frame generation, display mode, the game's memory, sensor statistics, the export schema |
04_CAPTURE.md |
The Agent's capture loop, the tiers, finalizing and recovery, the threading model |
05_DETECTION.md |
Detecting engines, platforms and capabilities; the detection rules |
06_DATA_MODEL.md |
The SQLite schema, every migration, who writes what, retention |
07_IPC.md |
The shared-memory ring between the game and the Agent, and the named pipe between the Agent and the App |
08_UI.md |
Every screen of the App, as specified and as built |
09_I18N.md |
English / Vietnamese / Japanese strings, the glossary, the safety-string review rule |
10_LOGGING_AND_BUG_REPORTS.md |
Logs in every process, the bug-report bundle, redaction |
11_UPDATER.md |
Velopack updates from GitHub Releases, and when an update may apply |
12_BUILD.md |
The toolchain, the build, the quality gate step by step, publishing and packaging |
13_CI_CD.md |
The CI and release workflows |
14_TESTING.md |
The test strategy, hook overhead, the hardware matrix |
15_ROADMAP.md |
The phases and where each stands |
16_WPFUI_SYNTAX.md |
WPF UI (lepoco) rules, theming, rendered documents, gotchas |
17_HOOK_ENGINE.md |
The hooks inside the game: inventory, fault policy, the ring writer, Vulkan |
18_GPU_VENDOR_APIS.md |
Telemetry layers (DXGI/PDH, LibreHardwareMonitor, NVAPI), the game process's memory, licences |
19_SAFETY_AND_ANTICHEAT.md |
The anti-cheat guard, what a finding does, the user-mode exception, what will never be built |
20_OPEN_QUESTIONS.md |
Every unresolved question, defect and measurement, with its status marker |
21_INPUT_DEVICES.md |
Controllers and keyboard-and-mouse activity: what is read from outside the game, from where, and what never is |
HANDOFF.md |
Sequencing, the open owner-only items, the index of the owner's decisions |
handoff/ |
Since beta.24 (D66): the history of every train and phase, the passed owner-only items, the traps — moved out of HANDOFF.md verbatim |
open-questions/ |
Since beta.24 (D66): the entries §S24 marks resolved, moved out of 20_OPEN_QUESTIONS.md verbatim — a table there lists them |
spike-notes/ |
Since beta.24 (D66): one file per measurement section; spike-notes.md is the index that resolves spike-notes §N |
changelog/ |
Since beta.24 (D66): each release's notes in its own file, and the ledger kept before the first tag; ../CHANGELOG.md keeps [Unreleased] and the list |
spike-notes.md |
What was measured, how, on which machine, and what each result decided |
LIST_GAME_TESTED.md |
The real games FrameLedger has been run with, and what each session measured (changes need the owner's review) |
legal-drift-history.md |
How the legal documents once drifted from the software, and the maintainers' notes moved out of them |
vendor-exports.json |
The vendor DLL exports the hooks are allowed to bind, checked by tools/vendor-exports |
Beside this folder
../guide/— the user guide (players, English); since beta.17 (D54) also the wiki's End-user part.../wiki/— the wiki's own pages: Home, the sidebar, the developer pages (D53).wiki.ymlpublishes them with the guide to the Wiki tab when a release is made;build.ps1'swiki-checkholds every link.../legal/— the documents a user accepts, the accuracy statement, the third-party notices and licence texts, the trademark note.../LIMITATIONS.md— what the whole software cannot do, in a player's words.../ACCESSIBILITY.md— the accessibility statement (beta.35, D88): the goal, what works with the keyboard, a screen reader and contrast themes, the known limits and how a barrier is reported; shown in the App under Help ▸ Accessibility. Its checks are08_UI.md§Accessibility.../SECURITY.md— the private route for a vulnerability, and why the guard has no override.../rules/detection-rules.json— engine, platform and capability signatures and the anti-cheat blocklist, validated bytools/rules-validate.ps1.