Compare commits

...
Author SHA1 Message Date
poli0981 868e4e1d99 Merge branch 'main' of https://github.com/poli0981/frameledger into beta17/pr4-wiki
# Conflicts:
#	CHANGELOG.md
#	CLAUDE.md
2026-10-07 17:06:53 +07:00
poli0981andClaude Opus 5.5 8b879fcb4a docs(wiki): the developer half of the wiki, built from the repository and published at each release (beta.17 PR-4, D53)
The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D53):
the wiki's source lives in the repository and the Wiki tab is a copy, published when a release is made; the End-user
half is the user guide (PR-3, D54). The Wiki tab existed with one placeholder page.

- wiki/: Home (two doors), _Sidebar, and eleven short developer pages - Developers (where to start, where status lives),
  Architecture (a mermaid diagram, the processes, the two tiers, a frame's way to the screen), Repository map, Build and
  test (the gates in one table), Contributor rules (the nine rules in plain words, what will never be built, every
  pull request), Capture pipeline, Metrics (and the display rules), Data and IPC, App UI development (the WPF UI traps,
  this train's two included), Releasing, Developer glossary. Each links to its full document and states no status.
- tools/wiki-build.ps1: names each page (a guide page after its first heading; guide/README.md is User-guide,
  LIMITATIONS.md Limitations), rewrites links between pages to page names and every other repository link to GitHub at
  -Ref, drops each page's first heading, writes _Footer.md naming the ref. Refuses a link to a missing file, folder or
  section, two sources for one page, a page nothing leads to, a sidebar out of the guide's order, a backticked path in a
  wiki/ page that names nothing, and a version written into a wiki/ page. -SelfTest: nine cases, both directions.
- build.ps1: the wiki-check gate after notice-check (self-test, then -Check).
- .github/workflows/wiki.yml: on workflow_run of Release (success, started by a pushed v* tag - a rehearsal never
  publishes) and by hand (ref, publish). Checks out head_sha, links at the tag, uploads the pages, and publishes with
  gh auth setup-git + a clone of <repo>.wiki.git + push HEAD:master, only when something changed. contents: write, since
  the repository's default token is read-only. Separate from release.yml so a wiki failure is never a red release and
  can be re-run.
- Docs: README (the wiki, both halves), docs/README.md (the wiki; "D1...D46" corrected), CONTRIBUTING (where
  documentation lives), CLAUDE.md (wiki/ and wiki-build), 12_BUILD (gate 13d), 13_CI_CD (wiki.yml, five repo-local
  workflows, the owner's wiki-editing setting), CHANGELOG [Unreleased].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 16:40:31 +07:00
poli0981andClaude Opus 5.5 2374115337 docs(guide): the user guide looks things up too - the screens, every setting, troubleshooting, a glossary (beta.17 PR-3, D54)
The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D54):
the End-user part IS the user guide, one source - shown in the App under Help > User guide and, from PR-4, on the
wiki. Four pages join it after the FAQ, each written from the code it describes (labels, defaults, ranges and messages
read in SettingsPage.xaml, SettingsRegistry, Strings.resx and the view models):

- guide/07-screens.md - the badge and banners, every menu item, Dashboard, Games, a game's page, the session summary,
  Compare, Logs, the tray icon, keyboard and mouse.
- guide/08-settings.md - every setting the Settings page shows, in its order: what it does, its default, and which
  ones the agent reads.
- guide/09-troubleshooting.md - what you see, what it means, what to do: the agent, a game recorded but not measured
  (each "Why:"), N/A figures, "How it ended", updates, the database, the viewer, reporting a problem.
- guide/10-glossary.md - the words the App shows, A to Z.

guide/README.md lists them in the App's order (EmbeddedDocuments.GuidePages). The first run's "Your library" step named
"File > Import library... on the Games page"; File is the main window's menu and the Games page has no import button -
fixed in en/vi/ja (vi names the menu as shown, "Tep").

Tests (GuideDocumentsTests), each shown to bite on a deliberately broken page:
- EveryLinkToASectionNamesAHeadingOfItsPage - every section link, within a page, to another guide page, Limitations or
  a document, against the anchors the App's renderer gives the target (it replaces the one-anchor check);
- TheContentsListThePagesInTheAppsOrder;
- TheSettingsPageOfTheGuideNamesEverySetting - every Settings_*_Label the Settings page binds, in English;
- TheScreensPageOfTheGuideNamesEveryPageAndMenuItem - every Nav_* and Menu_* of the main window.
MarkdownRendererTests counts the guide's twelve pages.

Docs: CLAUDE.md and 08_UI ("eight short English pages" struck, the tests named; the consent dialog's button is "Keep
hooking off", not "Keep it off"), CHANGELOG [Unreleased].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 16:40:31 +07:00
23 changed files with 1058 additions and 6 deletions

No files matched your search

+100
View File
@@ -0,0 +1,100 @@
# The GitHub Wiki is a copy of the repository's own pages (D53/D54, the owner, 2026-10-07): wiki/ (Home, the sidebar,
# the developer pages) and guide/ (the user guide, which is the End-user part) with LIMITATIONS.md, assembled and checked
# by tools/wiki-build.ps1 - the check build.ps1 runs as `wiki-check`. A page edited on the Wiki tab is overwritten here;
# edit wiki/ or guide/ instead (docs/13_CI_CD.md §wiki.yml).
#
# Separate from release.yml on purpose. The release stays as it was and its dry run stays a pure rehearsal; a wiki that
# fails to publish is a red run of its own, re-run on its own, never a red release. A step after `gh release create`
# could never be re-run at all: the release would already exist.
#
# A release that release.yml creates with GITHUB_TOKEN fires no `release` event for other workflows. `workflow_run` does
# fire - the Release run itself was started by the owner's tag push - and it runs THIS file as it is on main, so the job
# checks out the commit the release was built from (head_sha) and links the repository's files at the tag (head_branch).
name: Wiki
on:
workflow_run:
workflows: [Release]
types: [completed]
workflow_dispatch:
inputs:
ref:
description: 'Branch, tag or commit to build the wiki from; repository files are linked at this ref'
required: true
default: main
type: string
publish:
description: 'Publish to the Wiki tab (off: build, check and upload the pages only)'
required: true
default: false
type: boolean
# The repository's default token is read-only; pushing to <repo>.wiki.git needs contents: write.
permissions:
contents: write
concurrency:
group: wiki
cancel-in-progress: false
jobs:
wiki:
# A rehearsal of release.yml (workflow_dispatch) never publishes the wiki: only a run started by a pushed v* tag
# that succeeded.
if: >-
github.event_name == 'workflow_dispatch' ||
(github.event.workflow_run.conclusion == 'success' &&
github.event.workflow_run.event == 'push' &&
startsWith(github.event.workflow_run.head_branch, 'v'))
runs-on: windows-latest
timeout-minutes: 10
env:
# Values reach the scripts through the environment only, never pasted into them.
WIKI_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_branch }}
WIKI_PUBLISH: ${{ github.event_name == 'workflow_run' || inputs.publish }}
steps:
- uses: actions/checkout@v7
with:
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_sha }}
persist-credentials: false
- name: Build and check the wiki
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
./tools/wiki-build.ps1 -Ref $env:WIKI_REF -Out out/wiki
if ($LASTEXITCODE -ne 0) { throw 'wiki-build failed' }
- name: Upload the pages
uses: actions/upload-artifact@v7
with:
name: wiki-${{ github.run_id }}
path: out/wiki/**
if-no-files-found: error
retention-days: 14
- name: Publish to the Wiki tab
if: env.WIKI_PUBLISH == 'true'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
run: |
$ErrorActionPreference = 'Stop'
gh auth setup-git
if ($LASTEXITCODE -ne 0) { throw 'gh auth setup-git failed' }
git clone --depth 1 "https://github.com/$env:GITHUB_REPOSITORY.wiki.git" wiki-repo
if ($LASTEXITCODE -ne 0) { throw 'cloning the wiki failed - it must have one page created on github.com first' }
Get-ChildItem wiki-repo -Force | Where-Object Name -ne '.git' | Remove-Item -Recurse -Force
Copy-Item out/wiki/* wiki-repo -Recurse
Set-Location wiki-repo
git add -A
git diff --cached --quiet
if ($LASTEXITCODE -eq 0) { Write-Host "The wiki already shows $env:WIKI_REF; nothing to publish."; exit 0 }
git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' commit -q -m "wiki: $env:WIKI_REF"
if ($LASTEXITCODE -ne 0) { throw 'commit failed' }
# The wiki repository's branch is master (git ls-remote, 2026-10-07).
git push origin HEAD:master
if ($LASTEXITCODE -ne 0) { throw 'push failed' }
Write-Host "Published the wiki at $env:WIKI_REF"
+5
View File
@@ -48,6 +48,11 @@ numeric core and does not move; the heading is the full version — corrected 20
button and shortcut), *Every setting* (what each one does and its default), *When something goes wrong* (what you see,
what it means, what to do) and *Words FrameLedger uses*. Tests now fail when a setting or a menu item is added without
its line in the guide, or a link names a section that does not exist.
- **A wiki.** The project's [wiki](https://github.com/poli0981/frameledger/wiki) has two halves: the user guide, the
same pages the app shows, and short pages for developers — the architecture, the repository, building and testing,
the rules every change keeps, capture, metrics, data, the app's UI and releasing — each linking to its full document.
It is published from the repository whenever a release is made (`wiki.yml`), so it always matches the newest
release, and `./build.ps1 check` fails on any link in it that leads nowhere (`13_CI_CD` §wiki.yml).
## [0.1.0-beta.16] - 2026-10-06
+5 -1
View File
@@ -138,7 +138,8 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# gen-ac-floor, hookinventory-check, license-check, license-gather
# (+ license-overrides/), notice-check, package-closure-check,
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
# versioninfo-check, vklayer-blastradius, fps-impact-runbook
# versioninfo-check, vklayer-blastradius, fps-impact-runbook,
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate)
# (six names added 2026-10-04)
# (PowerShell). This line used to name three, one of which
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
@@ -155,6 +156,9 @@ guide/ # the user guide (beta.12, D44): ~~eight~~ short
# App (Help > User guide); README.md is its contents. docs/ is for developers.
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
# and the guide is the wiki's End-user part)
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
# publishes them with guide/ and LIMITATIONS.md to the Wiki tab at a release;
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
docs/ legal/ legal/licenses/
```
+5
View File
@@ -27,6 +27,11 @@ That is the whole quality gate, and continuous integration runs the identical sc
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
Documentation lives in three places: `guide/` for players (shown in the app and on the wiki), `wiki/` for the wiki's own
pages, and `docs/` for developers. A change a player would notice updates `guide/`; a change to how the code is put
together updates `docs/` — and the `wiki/` page that summarises it, if that page now says something else.
`./build.ps1 check` builds the wiki and fails on a link that leads nowhere.
Never point a build of your own at the data FrameLedger records into (`%LOCALAPPDATA%\FrameLedger`): a newer build
migrates the database, and the released one cannot read it back. To look at real data, copy the folder and start
`FrameLedger.exe --data-dir <copy>` — a viewer that starts no Agent and changes nothing on the PC (`docs/12_BUILD.md`
+6 -2
View File
@@ -5,8 +5,10 @@
> No telemetry. No accounts. All data stays on your machine.
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
anti-cheat, and look after your data, a page each. What FrameLedger cannot do is on one page:
[Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User guide, Help ▸ Limitations).
anti-cheat, and look after your data, a page each, then every screen, every setting and what to do when something goes
wrong. What FrameLedger cannot do is on one page: [Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User
guide, Help ▸ Limitations), and on the project's [wiki](https://github.com/poli0981/frameledger/wiki) with the developer
pages.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-10-06.** The software is a beta; its latest
@@ -191,6 +193,8 @@ FrameLedger is GPL-3.0-only free software, and you are welcome to build it, chan
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reports: [`SECURITY.md`](SECURITY.md).
- **Fork or redistribute:** [`FORKING.md`](FORKING.md) — what the GPL asks of anyone who distributes builds, and the names
a fork must change so it does not share FrameLedger's update feed, install folder, data, pipe or Vulkan layer.
- **Find your way around:** the [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages are short, and each
links to the document it summarises ([`wiki/`](wiki/) is their source).
- **Read the design:** the developer documentation is in [`docs/`](docs/). Start with [`CLAUDE.md`](CLAUDE.md), then
[`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) — which constrains everything else — then
[`docs/01_ARCHITECTURE.md`](docs/01_ARCHITECTURE.md).
+9
View File
@@ -464,6 +464,15 @@ function Invoke-ProjectGates {
Invoke-Checked 'notice-check (self-test)' { & $noticeTool -SelfTest }
Invoke-Checked 'notice-check' { & $noticeTool -RepoRoot $repo }
# beta.17 (D53/D54): the GitHub Wiki is built from wiki/, guide/ and LIMITATIONS.md, and wiki.yml publishes it when a
# release is made. A link or a section that leads nowhere, a page nothing leads to, a sidebar out of the guide's
# order, a path that names nothing or a version written into a page is red here, not on the published wiki.
# Self-test first (nine cases, both directions), then the live assembly into a temporary folder.
Write-Step 'wiki-check'
$wikiTool = Join-Path $repo 'tools/wiki-build.ps1'
Invoke-Checked 'wiki-check (self-test)' { & $wikiTool -RepoRoot $repo -SelfTest }
Invoke-Checked 'wiki-check' { & $wikiTool -RepoRoot $repo -Check }
Write-Step 'changelog-check'
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
if (Test-Path $changelogTool) {
+1
View File
@@ -298,6 +298,7 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
13b. `tools/accuracy-check.ps1 -SelfTest`, then live — the accuracy block is ONE text (`legal/ACCURACY.md`) embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06)
13c. **`tools/notice-check.ps1 -SelfTest`, then live** (beta.12, owner decision D45, 2026-10-03) — every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`, tracked or new, minus `src/native/third_party/`) opens with `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (`NOTICE` carries them); the second line may name another holder and year in the same form (a contributor's own file).
Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a missing header, and `tools/resx-gen.ps1` generates the accessor with it
13d. **`tools/wiki-build.ps1 -SelfTest`, then `-Check`** (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from `wiki/`, `guide/` and `LIMITATIONS.md` into a temporary folder, as `wiki.yml` does at a release (`13_CI_CD` §wiki.yml), and fails on a link to a file, folder or section that does not exist, two sources for one page, a page that neither Home nor the sidebar leads to, a sidebar that lists the guide in another order than `guide/README.md`, a backticked repository path in a `wiki/` page that names nothing, and a version number written into a `wiki/` page (the footer says which release the wiki shows). Nine self-test cases, both directions
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one). The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
15. `tools/resx-audit.ps1` — ~~**skipped loudly; it does not exist, and no `.resx` file does either**~~ **built 2026-09-13 (P3 PR-2)**: `-SelfTest` first (11 fixture cases, both directions), then the live pass over every `Strings.resx` family under `src/` — key sets equal across en/vi/ja, `Safety_*` in `ja` marked for review or signed, `Strings.Designer.cs` current with `tools/resx-gen.ps1`. A tree with no family is red (`09_I18N` §Translation workflow)
+25 -1
View File
@@ -184,6 +184,29 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix. *(Added 2026-10-04: the PR-only removal step fails the job on any removal, a shrunk per-title list or an added trusted signer, whatever the body says — the justification is for the reviewer, and the job stays red.)*
- `permissions: contents: read`.
### `wiki.yml` — after a successful Release run, and by hand · **repo-local, built 2026-10-07 (beta.17, D53/D54)**
- **What:** the GitHub Wiki is a copy of the repository's own pages — `wiki/` (Home, the sidebar, the developer pages)
and `guide/` (the user guide: the End-user part, the same pages the App shows) with `LIMITATIONS.md`.
`tools/wiki-build.ps1` names each page (a guide page after its first heading, `guide/README.md` as *User-guide*,
`LIMITATIONS.md` as *Limitations*), rewrites links between pages to page names and every other repository link to
its address on GitHub **at the release's tag**, drops each page's first heading (the wiki prints the page name), and
writes a footer naming the tag. The same assembly is `build.ps1`'s `wiki-check` gate (`12_BUILD` §Local quality gate,
13d), so a dead link is red on the pull request, never on the published wiki.
- **When:** `workflow_run` on `Release`, completed — the job runs only when that run succeeded and was started by a
pushed `v*` tag, so a `workflow_dispatch` rehearsal of `release.yml` never publishes. It checks out the run's
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. By hand:
`gh workflow run wiki.yml -f ref=main -f publish=false` builds, checks and uploads the pages as an artifact; with
`publish=true` it publishes them.
- **Why not a step of `release.yml`:** the release stays as it was, its rehearsal stays a pure rehearsal, and a wiki
that fails to publish is a red run of its own that can be re-run — a step after `gh release create` could never be
re-run, the release already existing. A release created with `GITHUB_TOKEN` fires no `release` event for other
workflows; `workflow_run` fires because the Release run itself was started by a tag push.
- **Publishing:** `gh auth setup-git`, a clone of `<repo>.wiki.git`, everything but `.git` replaced, a commit as
`github-actions[bot]` only when something changed, `git push origin HEAD:master` (the wiki's branch is `master`). A
page edited on the Wiki tab is overwritten at the next release: edit `wiki/` or `guide/`.
- `permissions: contents: write` — the repository's default workflow token is read-only (read from the API,
2026-10-07), and pushing to the wiki repository needs write.
## Dependabot (`.github/dependabot.yml`)
```yaml
@@ -215,7 +238,7 @@ Central package management makes Dependabot PRs single-file diffs.
**In the tree — done:**
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph *(and `wiki.yml` since beta.17, repo-local too: five)*
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly)
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
@@ -227,4 +250,5 @@ Central package management makes Dependabot PRs single-file diffs.
- [ ] `Rules / validate` as a required check (§S23-2, after its skip-shim)
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
- [ ] Wiki editing restricted to collaborators (Settings ▸ General ▸ Features ▸ Wikis ▸ *Restrict editing to collaborators only*): otherwise anyone with a GitHub account can change a page until the next release overwrites it (§wiki.yml, beta.17)
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
+5 -2
View File
@@ -7,7 +7,8 @@ This folder is for people who build, change or review FrameLedger. **If you only
| You want to… | Read |
|---|---|
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (D1…D46) and the traps that each cost a cycle. It carries no status on purpose |
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (~~D1…D46~~ D1 onward — *corrected 2026-10-07: the range grows with every train*) and the traps that each cost a cycle. It carries no status on purpose |
| Find your way around first | The [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages (source: [`../wiki/`](../wiki/), beta.17) — a short page per part, each linking here |
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE) |
@@ -76,7 +77,9 @@ are safety items, and something listed there as unresolved should not be built t
## Beside this folder
- [`../guide/`](../guide/README.md) — the user guide (players, English).
- [`../guide/`](../guide/README.md) — the user guide (players, English); since beta.17 (D54) also the wiki's End-user part.
- [`../wiki/`](../wiki/Home.md) — the wiki's own pages: Home, the sidebar, the developer pages (D53). `wiki.yml`
publishes them with the guide to the Wiki tab when a release is made; `build.ps1`'s `wiki-check` holds every link.
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
texts, the trademark note.
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
+337
View File
@@ -0,0 +1,337 @@
# SPDX-License-Identifier: GPL-3.0-only
# Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
#Requires -Version 7.0
<#
.SYNOPSIS
Builds the GitHub Wiki from the repository - wiki/ (Home, the sidebar, the developer pages), guide/ (the user
guide, which is the wiki's End-user part) and LIMITATIONS.md - and refuses a wiki with a link that leads nowhere.
.DESCRIPTION
D53/D54 (the owner, 2026-10-07): the wiki's source lives in the repository and the Wiki tab is a copy of it, written
by .github/workflows/wiki.yml when a release is published. The user guide is the End-user part: one source, shown
in the App (Help > User guide) and on the wiki.
Assembling:
- wiki/*.md keeps its file name, which GitHub turns into the page's title (Build-and-test.md: "Build and test").
- A guide page becomes the page its first heading names (guide/README.md is User-guide, LIMITATIONS.md is
Limitations). Every page's first heading is dropped: the wiki prints the page's name above it.
- A link to one of those pages becomes the page's name; a link to any other file or folder of the repository
becomes its address on GitHub at -Ref, the release being published; anchors are kept.
- _Footer.md is written here, naming -Ref and where to edit.
Refused, each with a line, exit 1:
- a link to a file or folder that does not exist, or to a section no heading of its page produces;
- two sources that give one page name;
- a page that neither Home nor the sidebar leads to;
- a sidebar that lists the guide's pages in another order than guide/README.md does;
- a path in backticks in a wiki/ page that names nothing in the repository;
- a version number written in a wiki/ page (the footer is where the wiki says which release it shows).
-Check assembles into a temporary folder and only reports. -SelfTest proves every refusal, both ways, on copies.
#>
[CmdletBinding()]
param(
[string]$RepoRoot = (Split-Path $PSScriptRoot -Parent),
[string]$Out,
[string]$Ref = 'main',
[switch]$Check,
[switch]$SelfTest
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
$repoUrl = 'https://github.com/poli0981/frameledger'
$special = @{ 'guide/README.md' = 'User-guide'; 'LIMITATIONS.md' = 'Limitations' }
$pathPrefixes = @('src/', 'docs/', 'tools/', 'tests/', 'guide/', 'legal/', 'wiki/', 'rules/', '.github/')
$rootFiles = @('README.md', 'CLAUDE.md', 'CHANGELOG.md', 'LIMITATIONS.md', 'CONTRIBUTING.md', 'FORKING.md', 'SECURITY.md',
'CODE_OF_CONDUCT.md', 'NOTICE', 'LICENSE', 'VERSION', 'build.ps1', 'global.json', 'FrameLedger.slnx', 'Directory.Build.props')
if ($Ref -notmatch '^[A-Za-z0-9][A-Za-z0-9._/-]*$') { throw "-Ref '$Ref' is not a branch, tag or commit name" }
# The anchor GitHub gives a heading: lower-case, letters, digits, '-' and '_' kept, a space a '-', the rest dropped
# (MarkdownLinks.Slug in the App follows the same rule, so the guide's anchors work in both places).
function Get-Slug([string]$Heading) {
$sb = [System.Text.StringBuilder]::new()
foreach ($c in $Heading.Trim().ToLowerInvariant().ToCharArray()) {
if ([char]::IsLetterOrDigit($c) -or $c -eq '-' -or $c -eq '_') { [void]$sb.Append($c) }
elseif ($c -eq ' ') { [void]$sb.Append('-') }
}
return $sb.ToString()
}
# Lines outside fenced code blocks, each as @{ Index; Text }.
function Get-ProseLines([string[]]$Lines) {
$inFence = $false
for ($i = 0; $i -lt $Lines.Count; $i++) {
if ($Lines[$i] -match '^\s*(```|~~~)') { $inFence = -not $inFence; continue }
if (-not $inFence) { [pscustomobject]@{ Index = $i; Text = $Lines[$i] } }
}
}
function Get-Anchors([string]$Text) {
$anchors = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
foreach ($line in Get-ProseLines (($Text -replace "`r`n", "`n") -split "`n")) {
if ($line.Text -match '^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$') {
$heading = [regex]::Replace($Matches[1], '\[([^\]]*)\]\([^)]*\)', '$1') -replace '[`*]', ''
$slug = Get-Slug $heading
if ($slug.Length -eq 0) { continue }
$unique = $slug
for ($n = 1; $anchors.Contains($unique); $n++) { $unique = "$slug-$n" }
[void]$anchors.Add($unique)
}
}
return , $anchors
}
function Get-PageName([string]$Path, [string]$Text) {
if ($special.ContainsKey($Path)) { return $special[$Path] }
if ($Path.StartsWith('wiki/', [StringComparison]::Ordinal)) { return [IO.Path]::GetFileNameWithoutExtension($Path) }
$h1 = @(($Text -replace "`r`n", "`n") -split "`n" | Where-Object { $_ -match '^# \S' }) | Select-Object -First 1
if (-not $h1) { throw "$Path has no first heading to name its wiki page" }
return (($h1.Substring(2).Trim() -replace '[^A-Za-z0-9]+', '-').Trim('-'))
}
function Get-Sources([string]$SourceRoot) {
$sources = [System.Collections.Generic.List[object]]::new()
$add = {
param([string]$Path, [string]$File)
$text = [IO.File]::ReadAllText($File)
$sources.Add([pscustomobject]@{ Path = $Path; Text = $text; Name = (Get-PageName $Path $text); FromWiki = $Path.StartsWith('wiki/', [StringComparison]::Ordinal) })
}
foreach ($f in Get-ChildItem (Join-Path $SourceRoot 'wiki') -Filter *.md -File | Sort-Object Name) { & $add "wiki/$($f.Name)" $f.FullName }
foreach ($f in Get-ChildItem (Join-Path $SourceRoot 'guide') -Filter *.md -File | Sort-Object Name) { & $add "guide/$($f.Name)" $f.FullName }
& $add 'LIMITATIONS.md' (Join-Path $SourceRoot 'LIMITATIONS.md')
return , $sources
}
# A link's target as a path from the repository root, or $null when it climbs out of it.
function Resolve-RepoPath([string]$From, [string]$Link) {
$parts = [System.Collections.Generic.List[string]]::new()
$dir = [IO.Path]::GetDirectoryName($From) -replace '\\', '/'
if ($dir) { foreach ($s in $dir -split '/') { $parts.Add($s) } }
foreach ($seg in ($Link -split '/')) {
if ($seg -eq '' -or $seg -eq '.') { continue }
if ($seg -eq '..') {
if ($parts.Count -eq 0) { return $null }
$parts.RemoveAt($parts.Count - 1)
continue
}
$parts.Add($seg)
}
return ($parts -join '/')
}
# Every inline link of a page outside code: @{ Start; Length; Href }, in order.
function Get-Links([string]$Text) {
$lines = $Text -split "`n"
$offsets = [int[]]::new($lines.Count)
$at = 0
for ($i = 0; $i -lt $lines.Count; $i++) { $offsets[$i] = $at; $at += $lines[$i].Length + 1 }
foreach ($line in Get-ProseLines $lines) {
foreach ($m in [regex]::Matches($line.Text, '(?<!!)\]\((?<href>[^)\s]+)(?:\s+"[^"]*")?\)')) {
$g = $m.Groups['href']
[pscustomobject]@{ Start = $offsets[$line.Index] + $g.Index; Length = $g.Length; Href = $g.Value }
}
}
}
# Assembles the wiki in memory: @{ Pages = name -> text; Problems = string[] }.
function Invoke-Assembly([string]$SourceRoot, [string]$Root, [string]$GitRef) {
$problems = [System.Collections.Generic.List[string]]::new()
$sources = Get-Sources $SourceRoot
$byPath = @{}
$byName = @{}
foreach ($s in $sources) {
$byPath[$s.Path] = $s
if ($byName.ContainsKey($s.Name)) { $problems.Add("$($s.Path) and $($byName[$s.Name].Path) both make the page '$($s.Name)'") }
else { $byName[$s.Name] = $s }
}
foreach ($req in 'Home', '_Sidebar') {
if (-not $byName.ContainsKey($req)) { $problems.Add("wiki/$req.md is missing") }
}
$anchorCache = @{}
$anchorsOf = {
param([string]$Path, [string]$Text)
if (-not $anchorCache.ContainsKey($Path)) { $anchorCache[$Path] = Get-Anchors $Text }
return , $anchorCache[$Path]
}
$pages = [ordered]@{}
$edges = @{}
foreach ($s in $sources) {
$text = $s.Text -replace "`r`n", "`n"
$targets = [System.Collections.Generic.List[string]]::new()
$links = @(Get-Links $text)
$sb = [System.Text.StringBuilder]::new($text)
for ($k = $links.Count - 1; $k -ge 0; $k--) {
$link = $links[$k]
$href = $link.Href
if ($href -match '^(https?:|mailto:)') { continue }
$hash = $href.IndexOf('#')
$anchor = if ($hash -ge 0) { $href.Substring($hash + 1) } else { $null }
$pathPart = if ($hash -ge 0) { $href.Substring(0, $hash) } else { $href }
$new = $null
if ($pathPart -eq '') {
if (-not $anchor -or -not (& $anchorsOf $s.Path $s.Text).Contains($anchor.ToLowerInvariant())) { $problems.Add("$($s.Path): '$href' names no section of the page") }
continue
}
$isDir = $pathPart.EndsWith('/')
$target = Resolve-RepoPath $s.Path ([Uri]::UnescapeDataString($pathPart))
if ($null -eq $target -or $target -eq '') { $problems.Add("$($s.Path): '$href' leaves the repository"); continue }
if ($byPath.ContainsKey($target)) {
$page = $byPath[$target]
if ($anchor -and -not (& $anchorsOf $page.Path $page.Text).Contains($anchor.ToLowerInvariant())) { $problems.Add("$($s.Path): '$href' names no section of $target") }
$new = $page.Name + $(if ($anchor) { "#$anchor" } else { '' })
$targets.Add($page.Name)
}
else {
$full = Join-Path $Root ($target -replace '/', [IO.Path]::DirectorySeparatorChar)
$exists = if ($isDir) { Test-Path -LiteralPath $full -PathType Container } else { Test-Path -LiteralPath $full }
if (-not $exists) { $problems.Add("$($s.Path): '$href' leads to $target, which does not exist"); continue }
$folder = Test-Path -LiteralPath $full -PathType Container
if ($anchor -and ($folder -or -not $target.EndsWith('.md') -or -not (& $anchorsOf $target ([IO.File]::ReadAllText($full))).Contains($anchor.ToLowerInvariant()))) {
$problems.Add("$($s.Path): '$href' names no section of $target")
}
$kind = if ($folder) { 'tree' } else { 'blob' }
$new = "$repoUrl/$kind/$GitRef/$($target.TrimEnd('/'))" + $(if ($anchor) { "#$anchor" } else { '' })
}
[void]$sb.Remove($link.Start, $link.Length).Insert($link.Start, $new)
}
# The wiki prints the page's name as its title; the source's own first heading - kept for reading it in the
# repository and, for a guide page, in the App - would repeat it.
$converted = [regex]::Replace($sb.ToString(), '\A(?:<!--.*?-->\s*)*# [^\n]*\n(\s*\n)?', '', [Text.RegularExpressions.RegexOptions]::Singleline)
if ($s.FromWiki) { Test-WikiSource $s $Root $problems }
$pages[$s.Name] = $converted
$edges[$s.Name] = $targets
}
Test-Reachable $edges $byName $problems
Test-SidebarOrder $byPath $problems
$pages['_Footer'] = "This wiki is generated from the repository at [``$GitRef``]($repoUrl/tree/$GitRef). Edit " +
"[``wiki/``]($repoUrl/tree/main/wiki) or [``guide/``]($repoUrl/tree/main/guide) there: a change made here is " +
"overwritten when the next release is published.`n"
return [pscustomobject]@{ Pages = $pages; Problems = $problems.ToArray() }
}
# A wiki/ page names only paths that exist, and no version number.
function Test-WikiSource($Source, [string]$Root, $Problems) {
foreach ($line in Get-ProseLines (($Source.Text -replace "`r`n", "`n") -split "`n")) {
foreach ($m in [regex]::Matches($line.Text, '`([^`\s]+)`')) {
$candidate = $m.Groups[1].Value.TrimEnd('.', ',', ';', ':')
$isPath = ($pathPrefixes | Where-Object { $candidate.StartsWith($_, [StringComparison]::Ordinal) }) -or ($rootFiles -contains $candidate)
if (-not $isPath -or $candidate -match '[*<>{}|?]') { continue }
$full = Join-Path $Root ($candidate.TrimEnd('/') -replace '/', [IO.Path]::DirectorySeparatorChar)
if (-not (Test-Path -LiteralPath $full)) { $Problems.Add("$($Source.Path): ``$candidate`` names nothing in the repository") }
}
if ($line.Text -match '\b\d+\.\d+\.\d+-(?:beta|rc|alpha)\.\d+\b') {
$Problems.Add("$($Source.Path): '$($Matches[0])' - a wiki page names no version; the footer says which release it shows")
}
}
}
function Test-Reachable($Edges, $ByName, $Problems) {
$seen = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
$queue = [System.Collections.Generic.Queue[string]]::new()
foreach ($start in 'Home', '_Sidebar') { if ($ByName.ContainsKey($start) -and $seen.Add($start)) { $queue.Enqueue($start) } }
while ($queue.Count -gt 0) {
foreach ($next in $Edges[$queue.Dequeue()]) { if ($seen.Add($next)) { $queue.Enqueue($next) } }
}
foreach ($name in $ByName.Keys | Sort-Object) {
if (-not $seen.Contains($name)) { $Problems.Add("$($ByName[$name].Path): no link from Home or the sidebar leads to '$name'") }
}
}
# The sidebar lists the guide's pages in the order of the guide's own contents.
function Test-SidebarOrder($ByPath, $Problems) {
if (-not $ByPath.ContainsKey('wiki/_Sidebar.md') -or -not $ByPath.ContainsKey('guide/README.md')) { return }
$order = {
param($Source)
$paths = foreach ($l in Get-Links ($Source.Text -replace "`r`n", "`n")) {
$hash = $l.Href.IndexOf('#')
$p = Resolve-RepoPath $Source.Path ([Uri]::UnescapeDataString($(if ($hash -ge 0) { $l.Href.Substring(0, $hash) } else { $l.Href })))
if ($p -and $p.StartsWith('guide/', [StringComparison]::Ordinal) -and $p -ne 'guide/README.md') { $p }
}
return @($paths | Select-Object -Unique)
}
$contents = & $order $ByPath['guide/README.md']
$sidebar = & $order $ByPath['wiki/_Sidebar.md']
if (($contents -join '|') -ne ($sidebar -join '|')) {
$Problems.Add("wiki/_Sidebar.md lists the guide as [$($sidebar -join ', ')], guide/README.md as [$($contents -join ', ')]")
}
}
function Write-Wiki($Pages, [string]$Folder) {
New-Item -ItemType Directory -Path $Folder -Force | Out-Null
Get-ChildItem -LiteralPath $Folder -Force | Where-Object { $_.Name -ne '.git' } | Remove-Item -Recurse -Force
$utf8 = [System.Text.UTF8Encoding]::new($false)
foreach ($name in $Pages.Keys) {
[IO.File]::WriteAllText((Join-Path $Folder "$name.md"), ($Pages[$name] -replace "`r`n", "`n"), $utf8)
}
}
if ($SelfTest) {
$tmp = Join-Path ([IO.Path]::GetTempPath()) ('fl-wiki-' + [Guid]::NewGuid().ToString('N'))
New-Item -ItemType Directory -Path $tmp | Out-Null
try {
Copy-Item (Join-Path $RepoRoot 'wiki') (Join-Path $tmp 'wiki') -Recurse
Copy-Item (Join-Path $RepoRoot 'guide') (Join-Path $tmp 'guide') -Recurse
Copy-Item (Join-Path $RepoRoot 'LIMITATIONS.md') $tmp
$cases = 0
$expect = {
param([string]$What, [string]$Pattern)
$p = @((Invoke-Assembly $tmp $RepoRoot $Ref).Problems)
if ($Pattern -eq '') {
if ($p.Count -ne 0) { throw "self-test: $What should pass, got: $($p -join '; ')" }
}
elseif ($p.Count -ne 1 -or $p[0] -notmatch $Pattern) { throw "self-test: $What should fail once matching '$Pattern', got: $($p -join '; ')" }
$script:cases++
}
$mutate = {
param([string]$Rel, [scriptblock]$Change, [string]$What, [string]$Pattern)
$file = Join-Path $tmp $Rel
$existed = Test-Path $file
$orig = if ($existed) { [IO.File]::ReadAllText($file) } else { $null }
[IO.File]::WriteAllText($file, (& $Change $orig))
try { & $expect $What $Pattern }
finally { if ($existed) { [IO.File]::WriteAllText($file, $orig) } else { Remove-Item $file } }
}
& $expect 'the shipped sources' ''
& $mutate 'wiki/Home.md' { param($t) $t + "`n[gone](../docs/NO_SUCH_FILE.md)`n" } 'a link to a missing file' 'NO_SUCH_FILE.*does not exist'
& $mutate 'wiki/Home.md' { param($t) $t + "`n[gone](../guide/01-install.md#no-such-section)`n" } 'a link to a missing section' 'no-such-section.*names no section'
& $mutate 'wiki/Home.md' { param($t) $t + "`n[out](../../outside.md)`n" } 'a link out of the repository' 'leaves the repository'
& $mutate 'wiki/Limitations.md' { param($t) "Same name as LIMITATIONS.md.`n" } 'two sources for one page' "both make the page 'Limitations'"
& $mutate 'wiki/Orphan.md' { param($t) "Nothing links here.`n" } 'a page nothing leads to' "leads to 'Orphan'"
& $mutate 'wiki/_Sidebar.md' { param($t) ($t -replace '(?m)^- \[Questions and answers\]\(\.\./guide/06-faq\.md\)\r?\n', '') + "- [Questions and answers](../guide/06-faq.md)`n" } 'a sidebar out of the guide''s order' 'lists the guide as'
& $mutate 'wiki/Home.md' { param($t) $t + "`nSee ``src/FrameLedger.App/NoSuchFile.cs``.`n" } 'a backticked path that names nothing' 'NoSuchFile\.cs.*names nothing'
& $mutate 'wiki/Home.md' { param($t) $t + "`nSince 0.1.0-beta.99.`n" } 'a version number in a page' 'names no version'
Write-Host "wiki-build self-test OK - $cases cases, both directions"
}
finally {
Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue
}
exit 0
}
$result = Invoke-Assembly $RepoRoot $RepoRoot $Ref
if ($result.Problems.Count -ne 0) {
Write-Host 'WIKI CHECK FAILED:' -ForegroundColor Red
foreach ($p in $result.Problems) { Write-Host " $p" -ForegroundColor Red }
Write-Host ' The wiki is built from wiki/, guide/ and LIMITATIONS.md (docs/13_CI_CD.md, wiki.yml).' -ForegroundColor Red
exit 1
}
if ($Check) {
$tmp = Join-Path ([IO.Path]::GetTempPath()) ('fl-wiki-check-' + [Guid]::NewGuid().ToString('N'))
try { Write-Wiki $result.Pages $tmp } finally { Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue }
Write-Host "wiki-check OK - $($result.Pages.Count) pages, every link leads somewhere"
exit 0
}
if (-not $Out) { $Out = Join-Path $RepoRoot 'out/wiki' }
Write-Wiki $result.Pages $Out
Write-Host "wiki-build OK - $($result.Pages.Count) pages written to $Out at $Ref"
exit 0
+48
View File
@@ -0,0 +1,48 @@
# App UI development
The screens are specified, and described as built, in [`docs/08_UI.md`](../docs/08_UI.md); the rules for the UI library
are [`docs/16_WPFUI_SYNTAX.md`](../docs/16_WPFUI_SYNTAX.md). The App is `src/FrameLedger.App`: WPF on .NET 10 with
WPF UI 4.3.0 (pinned), CommunityToolkit.Mvvm, ScottPlot for charts and Markdig for documents.
## How it is put together
- A .NET Generic Host with dependency injection. Pages and their view models are transient — a page is made again on
every navigation, so state lives in the view models' services and the database, never in a page.
- Navigation goes only through WPF UI's `INavigationService`; a page implements `INavigableView<TViewModel>`.
- The App opens `ledger.db` itself to read; anything that acts on the PC — hooking, deleting sessions, pausing — is a
request to the agent over the pipe.
- `FrameLedger.exe --data-dir <copy>` is a viewer: no agent, no update, the controls that would change the PC disabled.
## Strings
Every user-visible string comes from `.resx`, in English, Vietnamese and Japanese (`src/FrameLedger.App/Strings.resx`
and its `.vi` and `.ja` siblings; the shared ones are in `src/FrameLedger.Shared`). `tools/resx-gen.ps1` writes the
accessor class, and `tools/resx-audit.ps1` fails the build when a key is missing in a language. The safety texts in
Japanese wait for a human reviewer, never a machine draft ([`docs/09_I18N.md`](../docs/09_I18N.md)).
## Colours and theme
Colours come only from WPF UI's theme brushes, by `DynamicResource` — never a hex value, never `StaticResource` for a
theme brush. Muted text uses the App's `SecondaryText` and `TertiaryText` styles (`src/FrameLedger.App/Styles/FrameLedger.xaml`).
The chart palettes are the one place a colour is written out, once per theme.
## The traps of WPF UI 4.3.0
Each of these cost a release; the full list, with the tests that hold each, is §Gotchas checklist of
[`docs/16_WPFUI_SYNTAX.md`](../docs/16_WPFUI_SYNTAX.md).
- `ui:TextBlock Appearance=` looks its brush up once: a theme switch leaves the text in the old theme's colour.
- A class handler on `Loaded` does not reach every element: WPF raises Loaded only where a subtree listens for it.
- Every page sets `ScrollViewer.CanContentScroll="False"`, or WPF UI wraps it in a scroller that eats the mouse wheel;
a scroller inside a dialog is a `ui:PassiveScrollViewer`.
- A scroll bar is hidden through its scroller's own `ScrollBarVisibility`, never a style on the bar.
- `ui:InfoBar` draws no content (the App's copy of its template does); `ui:Badge` palette appearances are not theme
colours; WPF UI's DataGrid parts have keyed styles only; its CheckBox is 120 px wide at least.
- No dialog closes on Esc by itself (`Services/DialogKeyboard` does it); ScottPlot zooms on every wheel unless told not to.
- Apply the theme before the first window loads; watch the system theme only once the window has a handle.
## Testing the UI
`tests/FrameLedger.App.Tests` renders every page, window and dialog under the real theme dictionaries on one STA thread
(`PagesLoadTests.OnStaAsync`): contrast in both themes, a theme switch while a surface is on screen, scroll bars with the
option on in a real window, keyboard and automation names. A rendered check is run red against the unfixed XAML first.
+55
View File
@@ -0,0 +1,55 @@
# Architecture
The full document is [`docs/01_ARCHITECTURE.md`](../docs/01_ARCHITECTURE.md); the IPC details are in
[`docs/07_IPC.md`](../docs/07_IPC.md).
```mermaid
flowchart LR
subgraph game["Game process (only games the user enabled)"]
G["Game"] -- "present and API calls" --> O["FrameLedger.Overlay.dll: hooks"]
end
O -- "fixed-size frame records" --> R[("shared-memory ring")]
R -- "drained every 100 ms" --> A["FrameLedger.Agent.exe"]
A -- "sessions, frames, sensors" --> DB[("ledger.db (SQLite)")]
DB --> UI["FrameLedger.exe (the App)"]
UI -- "named pipe: commands" --> A
A -- "named pipe: events" --> UI
```
## The processes
| What | Runs | Does |
|---|---|---|
| `FrameLedger.exe` — `src/FrameLedger.App` | as the user | The WPF app: library, sessions, charts, settings. Reads SQLite; talks to the agent over the pipe. |
| `FrameLedger.Agent.exe` — `src/FrameLedger.Agent` | as the user; as administrator only if the user opts in | Watches for tracked games, runs the anti-cheat guard, injects, drains the ring, reads sensors once a second, writes SQLite. Closing the App never stops it. |
| `FrameLedger.Overlay.dll` — `src/native/FrameLedger.Overlay` | inside the game | Hooks presentation (DXGI for Direct3D 11 and 12, and OpenGL) and the upscaler, frame-generation and ray-tracing calls, and writes one record per frame into the ring. A hook never blocks, allocates, logs or throws. It draws nothing on screen. |
| `FrameLedger.VkLayer.dll` — `src/native/FrameLedger.VkLayer` | inside a Vulkan game | An implicit Vulkan layer instead of hooks, active only in a game FrameLedger starts. |
| `FrameLedger.Guard.dll`, `FrameLedger.NvapiBridge.dll`, `FrameLedger.ProcessStats.dll` | inside the agent, never a game | The anti-cheat guard (required), NVIDIA's extra sensors (optional), and the game's own memory read from outside it (optional). An optional one missing makes its fields N/A. |
`src/FrameLedger.CaptureHost` is a developer tool and is never shipped.
## Two tiers
- **Tier 1 — measured.** The user switched hooking on for the game, and the guard found nothing: every frame is
recorded.
- **Tier 2 — recorded only.** No hooking: the session keeps its duration, the PC's sensors, the game's memory, its
display mode, and *why* it was not measured. Every frame figure is N/A, never an estimate.
There is no third rung: without the hook there is no frame measurement at all.
## How a frame gets to the screen
1. The agent's watcher sees a tracked game's executable start (by full path, once a second).
2. Hooking off, or not consented: the session is Tier 2.
3. The guard checks the game's process tree, the PC's drivers and services, its title lists and the game's install
folder. Any finding, or any doubt, refuses: Tier 2, with the reason.
4. On a pass, the guard injects the Overlay with the documented `LoadLibraryW`, under its real name.
5. The Overlay installs its hooks, creates the ring and publishes a handshake; the agent checks the layout version and
the build id before it reads anything.
6. The agent drains the ring every 100 ms and checks the game again every 30 seconds; a finding unhooks.
7. When the game exits, the agent finalizes the session and writes it to SQLite in one transaction; the App reads it.
## Where data lives
`%LOCALAPPDATA%\FrameLedger`: `ledger.db` (WAL mode), `logs\`, `crashdumps\`, and `tmp\` for a session in progress
(its `.partial` file). The App installs separately, in `%LOCALAPPDATA%\FrameLedger.App`.
+47
View File
@@ -0,0 +1,47 @@
# Build and test
The full documents are [`docs/12_BUILD.md`](../docs/12_BUILD.md) and [`docs/14_TESTING.md`](../docs/14_TESTING.md).
## What you need
- Windows 10 (22H2) or 11, 64-bit.
- Visual Studio with the C++ workload (MSVC v143 or later, a Windows SDK of 22621 or later) and CMake 3.28 or later.
- The .NET SDK that [`global.json`](../global.json) pins.
- PowerShell 7.
## The one gate
```powershell
./build.ps1 check
```
It is the whole gate, and CI runs the same script. In order:
| Step | What fails it |
|---|---|
| Native build and ctest | A C++ warning (`/W4 /WX`) or a native test. |
| clang-format, `dotnet format` | Code not formatted as committed. |
| Managed build and tests | A C# warning (warnings are errors), or a test — the integration tests included. |
| coverage-gate | Too little coverage of Domain and Application. |
| rules-validate | A detection-rules file that breaks its schema or weakens the anti-cheat blocklist. |
| versioninfo, chokepoint, hookinventory, package-closure | A binary without its version resources; an injection anywhere but the guard's own code, or an evasion primitive anywhere; a hook not in the inventory; a developer tool in the package. |
| license-check, accuracy-check, notice-check | A package without its licence, a copy of the accuracy statement that drifted, a source file without its licence header. |
| changelog-check, release-notes, resx-audit | The changelog or the release-notes extractor broken, or a string missing in English, Vietnamese or Japanese. |
| struct-mirror, test-artifacts, wiki-check, placeholder guard | The shared-memory mirror test not run, test leftovers, a wiki link that leads nowhere, a stray `{{…}}` in a shipped document. |
Other tasks: `./build.ps1 native`, `./build.ps1 managed`, `./build.ps1 format` (writes the formatting). A skipped gate is
reported, never hidden.
## Tests
- **Managed:** one project per layer under `tests/` (xUnit v3, FluentAssertions). The App's tests render every page,
window and dialog under the real theme dictionaries.
- **Native:** ctest suites for the guard, the ring, the layout, the Vulkan layer, the telemetry DLLs.
- **Integration:** the hook-harness is hooked for real, on WARP, so it runs on CI without a GPU.
- **A new test is shown red first** on the unfixed code: a check that has never failed has not been seen to work.
## Looking at the App with real data
`FrameLedger.exe --data-dir <a copy of a data folder>` opens the App as a viewer: no agent is started or contacted, and
nothing on the PC is changed. **Never run a development build against your own `%LOCALAPPDATA%\FrameLedger`**: a newer
build upgrades the database, and an older one cannot open it again.
+45
View File
@@ -0,0 +1,45 @@
# Capture pipeline
What the agent does from the moment a game starts. The full document is [`docs/04_CAPTURE.md`](../docs/04_CAPTURE.md);
the guard is [`docs/19_SAFETY_AND_ANTICHEAT.md`](../docs/19_SAFETY_AND_ANTICHEAT.md); the code is in
`src/FrameLedger.Application/Capture`, `src/FrameLedger.Application/Recording` and `src/FrameLedger.Application/Watch`.
## Watching
- Once a second, the watcher lists the running processes and matches each executable's **full path** against the
library entries that have recording on. A file name alone never starts a session — except the same file on a
changed drive letter, which the agent follows.
- A launcher's consent does not carry over to the game it starts: the game's own executable is the one that counts.
- One session per game at a time. At every start, the agent first rebuilds any session a crash interrupted.
## A session's life
`Idle → Detected → Guarded → Injecting → Capturing → Finalizing → Saved`, with three side roads:
- **Refused** — the guard found something, or hooking is off: the session continues as Tier 2, with the reason.
- **Unhooked for safety** — a finding at a 30-second re-scan: the hook goes dormant (it is never unloaded), measuring
stops, and the session keeps the frames measured so far and says it stopped early.
- **Interrupted** — the agent itself stopped: its `.partial` file is turned into a session at the next start.
A session shorter than the minimum length (30 seconds by default) is discarded.
## While capturing
- The ring is drained every 100 ms; it holds about 16 seconds of frames at 500 fps, so a stall of the agent loses
nothing, and a dropped record is a warning on the session, never silently accepted.
- Sensors are read on their own thread once a second, through three layers: Windows itself (DXGI and performance
counters, any GPU), LibreHardwareMonitor (any GPU), and NVAPI (NVIDIA cards). A missing layer makes its fields N/A.
- The game's own video memory and RAM are read from outside the game, in both tiers.
- Everything is written to the session's `.partial` file at each step and every 60 seconds.
## Ending
- The last drain, then one SQLite transaction writes the session, its segments, its frame and sensor series.
- How the game ended is classified: *normal*; *crashed* (an exception exit code, an application-error event in the
window, or the game's own crash reporter starting late); *unhooked for safety*; *degraded* (the hook faulted or lost
the game); *interrupted*.
- Two abnormal ends within 60 seconds of attaching switch hooking off for that game, and nothing switches it back on
automatically.
Why a session ended is the `SessionEndReason` type in `src/FrameLedger.Application/Capture` — the list grows, so read
the code rather than a copy of it.
+52
View File
@@ -0,0 +1,52 @@
# Contributor rules
The rules are stated in full, with their amendments, in [`CLAUDE.md`](../CLAUDE.md) §Non-negotiable rules; the safety
policy behind them is [`docs/19_SAFETY_AND_ANTICHEAT.md`](../docs/19_SAFETY_AND_ANTICHEAT.md). In plain words:
## The nine rules
1. **Hooking is opt-in, per game.** The user adds the game *and* switches hooking on for it, after a warning. There is
no "hook everything" mode and no automatic injection.
2. **The anti-cheat guard is a gate, not a warning.** It checks before every injection and every 30 seconds after. A
finding refuses, says why, and switches the game's hooking off. There is no override — apart from one narrow,
evidence-bound exception for anti-cheat that runs entirely in user mode, which the user grants per game and which
ends for good the first time it goes wrong. Do not add another form of override.
3. **No evasion.** Injection uses the documented `LoadLibraryW`; the component keeps its real name, exports and version
information. A performance tool must be *visible* to anti-cheat. A change that makes FrameLedger harder to detect is
refused on principle.
4. **Never read or write game memory** beyond the arguments of the calls we hooked and the objects we own.
5. **The hook must never crash the game.** Every hook body is guarded, allocates nothing, takes no lock, logs nothing
and lets no exception out; repeated faults switch the hook off.
6. **Never one inflated frame rate.** With frame generation measured, Native, Displayed and the factor are shown
together; without it, *Presented FPS* with a sentence saying whether generated frames could be in it
([Metrics](Metrics.md)).
7. **Ray tracing, path tracing and ray reconstruction are Yes, No or N/A.** Where it cannot be measured, the answer is
N/A — never a made-up Yes.
8. **No telemetry, no analytics, no silent network calls.** The rule permits three requests — the update check, a
detection-rules fetch and store metadata the user opts into. Only the update check, and its download, exists today,
and the user can switch it off.
9. **No obfuscation of our own binaries.** GPL v3; releases ship with SHA-256 checksums.
## What will never be built
Manual mapping or reflective loading; erasing PE headers; unlinking from the module list; hiding, renaming or
randomising the component, its exports or its object names; hiding threads or evading debuggers; packing; any bypass or
stealth mode, or instructions to defeat the guard; reading game state; a kernel driver of our own. A pull request that
proposes one is closed with a pointer to the safety document.
## Every pull request
The checklist is [`.github/pull_request_template.md`](../.github/pull_request_template.md):
- `./build.ps1 check` passes — no warning in C# or C++, every test green, formatting clean.
- A document a change makes wrong is corrected **in the same pull request**. A stale sentence is struck through and
dated where it stands, not quietly rewritten.
- Every new user-visible string exists in English, Vietnamese and Japanese (`.resx`).
- Every first-party source file opens with the two-line licence header that [`NOTICE`](../NOTICE) explains
(`tools/notice-check.ps1 -Fix` writes it).
- A change to `src/` adds a line to `CHANGELOG.md` `[Unreleased]`.
- A change to the hook layer states its measured overhead, lists any new hook in the inventory
([`docs/17_HOOK_ENGINE.md`](../docs/17_HOOK_ENGINE.md)) and answers the safety review questions in the template.
- A user-visible limit that moves updates [`LIMITATIONS.md`](../LIMITATIONS.md) in the same pull request.
How to contribute and how contributions are licensed: [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+45
View File
@@ -0,0 +1,45 @@
# Data and IPC
The full documents are [`docs/06_DATA_MODEL.md`](../docs/06_DATA_MODEL.md) and [`docs/07_IPC.md`](../docs/07_IPC.md).
## The database
One SQLite file, `%LOCALAPPDATA%\FrameLedger\ledger.db`, in WAL mode, used through Microsoft.Data.Sqlite and Dapper.
| Table | Holds |
|---|---|
| `games` | The library, with each game's hooking, consent and anti-cheat state. |
| `sessions` | One row per session: its tier, how it ended, its figures. |
| `session_segments` | Spans of a session at one resolution and upscaler. |
| `frame_blobs`, `sensor_blobs` | The per-frame and sensor series, compressed. |
| `hardware_snapshots` | The PC as it was, shared by the sessions recorded on it. |
| `session_annotations` | Tags, notes and the user's overrides. |
| `settings` | Key and value, as `SettingsRegistry` (`src/FrameLedger.Application/Settings`) defines them. |
| `legal_acceptance` | Which version of each document the user accepted, and when. |
| `schema_migrations` | The migrations applied. |
- **Who writes what:** the agent writes sessions, their series and snapshots, and a game's hooking state; the App
writes what the user edits — a game's details, annotations, settings, legal acceptance. Consent never goes through
the database: the App asks the agent over the pipe.
- **Migrations** are numbered SQL files embedded in `src/FrameLedger.Infrastructure/Persistence/Migrations`, applied in
order by whichever process opens the file first, under a lock. A database newer than the build is refused, which is
why an older version cannot open a database a newer one has touched.
## Shared memory — the game and the agent
- One mapping per game process, created by the component in the game and opened by the agent: a handshake, the
writer's state, a control block, the display state, then a ring of fixed-size frame records — one writer, one reader,
no locks.
- The layout is defined twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (normative) and
`src/FrameLedger.Shared/ShmLayout.cs`. `ShmLayoutMirrorTests` compares every field's offset against JSON the native
`fl-layout-dump` writes, in both directions, and the gate fails if that test did not run.
- Before reading anything, the agent compares the layout version, the record size and the build id, and refuses to
attach on a mismatch.
## The pipe — the App and the agent
- A named pipe, `\\.\pipe\FrameLedger.v2`, carrying length-prefixed JSON messages (source-generated System.Text.Json,
unknown fields ignored): commands from the App (switch hooking on, pause, delete sessions…) and events from the agent
(a session started, made progress, ended; a safety notice).
- **The pipe is not a trust boundary for safety:** no message can tell the agent that something is safe. The guard
decides on its own.
+32
View File
@@ -0,0 +1,32 @@
# Developer glossary
The words the code and the documents use. The player's glossary is [Words FrameLedger uses](../guide/10-glossary.md).
- **Agent** — `FrameLedger.Agent.exe`, the capture orchestrator; `--serve` is its normal mode, `--console` the
developer's.
- **Census** — the frame-generation runtimes found loaded in a game; it decides the qualifier beside Presented FPS.
- **Consent** — a user's per-game agreement to hooking, typed in the consent dialog, stamped with where it came from.
- **D-numbers** (D1, D2, …) — the owner's decisions, recorded in [`docs/HANDOFF.md`](../docs/HANDOFF.md).
- **Drain** — the agent reading the ring, every 100 ms.
- **FR-x / NFR-x** — requirement ids from [`docs/02_SPEC.md`](../docs/02_SPEC.md).
- **Guard** — the native anti-cheat check that runs before every injection and every 30 seconds after; one
implementation, in `src/native/FrameLedger.Injector`.
- **Handshake** — the first region of the shared memory: layout version, record size and build id, checked before
anything is read.
- **Hook harness** — `src/native/tools/hook-harness`, a dummy Direct3D 11, Direct3D 12, Vulkan and OpenGL program the
tests hook instead of a game.
- **Kill switch** — `hooking.kill_switch`, *Disable all hooking*: nothing is injected, whatever each game says.
- **Ledger** — `ledger.db`, the SQLite file.
- **Overlay** — `FrameLedger.Overlay.dll`, the component injected into a game. It draws nothing; the name is historical.
- **`.partial`** — a session in progress, written in checksummed chunks so a crash leaves a usable prefix.
- **Pre-scan** — the guard's check of a game when it is added, so the game's page can say what was found before it runs.
- **Ring** — the single-producer, single-consumer queue of fixed-size frame records in shared memory.
- **Safety unhook** — a finding during a session: the hook goes dormant and the session says so.
- **Steady state** — the frame-generation state a session spent most of its time in, shown with its share.
- **Tier 1 / Tier 2** — measured / recorded only. There is no third tier.
- **Trial** — the first two hooked sessions under a user-mode exception; one that goes badly ends the exception for
good.
- **User-mode exception** — the one narrow exception to the guard's refusal, for anti-cheat that runs entirely in user
mode ([`docs/19_SAFETY_AND_ANTICHEAT.md`](../docs/19_SAFETY_AND_ANTICHEAT.md)).
- **Viewer** — the App started with `--data-dir` over a copy: no agent, nothing changed on the PC.
- **WARP** — Windows' software renderer, which lets the hook harness run on CI without a GPU.
+42
View File
@@ -0,0 +1,42 @@
# Developers
FrameLedger is a C++ component loaded into the games a user chose, a C# capture agent beside it, and a WPF app, with one
SQLite file between them. These pages are short on purpose: each says what a part is and where its full document is.
The full set is [`docs/`](../docs/README.md), and the rules every AI-assisted change follows are in
[`CLAUDE.md`](../CLAUDE.md).
## Start here
1. [Contributor rules](Contributor-rules.md) — the rules every change keeps. Safety comes first, and some changes are
refused whatever they improve.
2. [Architecture](Architecture.md), then [Repository map](Repository-map.md).
3. [Build and test](Build-and-test.md) — `./build.ps1 check` is the whole gate, the same one CI runs.
Picking up work where it stopped: [`docs/HANDOFF.md`](../docs/HANDOFF.md) has the sequencing, the owner's decisions
and the traps that each cost a cycle.
## Where status lives
These pages never say what is done or what is next. Status is in four files, and nowhere else:
| Question | File |
|---|---|
| What is unresolved, and what does it block? | [`docs/20_OPEN_QUESTIONS.md`](../docs/20_OPEN_QUESTIONS.md) |
| What was measured, and on what machine? | [`docs/spike-notes.md`](../docs/spike-notes.md) |
| Which phase is where? | [`docs/15_ROADMAP.md`](../docs/15_ROADMAP.md) |
| What landed, in which release? | [`CHANGELOG.md`](../CHANGELOG.md) |
Check a status claim against the code before you plan on it: more than one document has said "built" of something that
was not, and the repository corrects such sentences where they stand — struck through and dated — rather than quietly.
## The other pages
- [Capture pipeline](Capture-pipeline.md) — what the agent does from the moment a game starts.
- [Metrics](Metrics.md) — what each number means, and the rules for showing it.
- [Data and IPC](Data-and-IPC.md) — the database, the shared memory and the pipe.
- [App UI development](App-UI-development.md) — the WPF app, and the traps of its UI library.
- [Releasing](Releasing.md) — from a merged change to an update on a user's PC.
- [Developer glossary](Developer-glossary.md) — the project's own words.
Contributing is described in [`CONTRIBUTING.md`](../CONTRIBUTING.md), redistributing in [`FORKING.md`](../FORKING.md),
and how to report a vulnerability in [`SECURITY.md`](../SECURITY.md).
+43
View File
@@ -0,0 +1,43 @@
# FrameLedger
**FrameLedger** records how your games run on this PC — frame rate and frame times, the settings a game really renders
with, ray tracing, temperatures, and the game's own memory — and keeps every session so you can compare them later.
Everything stays on your PC: no account, no telemetry. It is free software under the GNU GPL v3, for 64-bit Windows 10
(22H2) and Windows 11, and it is in beta.
Download it from the [Releases page](https://github.com/poli0981/frameledger/releases).
## Use FrameLedger
The [user guide](../guide/README.md) is the one FrameLedger shows under Help ▸ User guide.
1. [Install and first start](../guide/01-install.md)
2. [Record a game](../guide/02-record-a-game.md)
3. [Read your results](../guide/03-read-your-results.md)
4. [Anti-cheat and safety](../guide/04-anti-cheat-and-safety.md) — read it before you switch hooking on for any game
5. [Your data](../guide/05-your-data.md)
6. [Questions and answers](../guide/06-faq.md)
To look something up: [The screens](../guide/07-screens.md), [Every setting](../guide/08-settings.md),
[When something goes wrong](../guide/09-troubleshooting.md), [Words FrameLedger uses](../guide/10-glossary.md),
[The terms, in plain words](../guide/terms-in-plain-words.md), and [Limitations](../LIMITATIONS.md) — what FrameLedger
cannot do.
## Build or change FrameLedger
Start at [Developers](Developers.md). The developer pages are short; each says what a part is and links to its full
document in [`docs/`](../docs/README.md).
- [Architecture](Architecture.md) — the processes, and how a frame travels from the game to the screen.
- [Repository map](Repository-map.md) — what is where.
- [Build and test](Build-and-test.md) — the toolchain and the one gate.
- [Contributor rules](Contributor-rules.md) — the rules every change keeps, safety first.
- [Capture pipeline](Capture-pipeline.md), [Metrics](Metrics.md), [Data and IPC](Data-and-IPC.md),
[App UI development](App-UI-development.md), [Releasing](Releasing.md), [Developer glossary](Developer-glossary.md).
## More
- A bug or a question: the project's [issues](https://github.com/poli0981/frameledger/issues). A game whose anti-cheat
FrameLedger missed: the **Safety gap** form there.
- A vulnerability: [`SECURITY.md`](../SECURITY.md).
- The licence: [`LICENSE`](../LICENSE) (GPL v3) and [`NOTICE`](../NOTICE); the name: [`legal/TRADEMARKS.md`](../legal/TRADEMARKS.md).
+38
View File
@@ -0,0 +1,38 @@
# Metrics
How every number is computed is [`docs/03_METRICS.md`](../docs/03_METRICS.md) — the source of truth; the user's side is
[Read your results](../guide/03-read-your-results.md). The calculators are in `src/FrameLedger.Domain/Metrics`, and the
frame-generation ladder in `src/FrameLedger.Application/Recording`.
## The basics
- **Frame time** — present to present, timed with the performance counter at the moment the game presents, per swap
chain. A paused or interrupted stretch is a gap, and gaps are left out of every figure.
- **Average FPS** — frames divided by the time measured, never the mean of instantaneous rates.
- **1% low / 0.1% low** — 1000 divided by the 99th / 99.9th percentile of the game's own frame times. They need at least
1,000 / 10,000 frames; with fewer, N/A.
- **Stutter** — a frame longer than twice the median of the 19 frames centred on it.
## The rules for showing a number
- **N/A means not measured.** Never 0, and never an estimate (`docs/02_SPEC.md`, FR-4.9).
- **Frame generation is never folded into one number** (rule 6). Measured: `Native → Displayed (×N FG)`, for example
`62 → 118 FPS (×1.9 FG)`. Not measured: **Presented FPS**, with a chip saying whether a frame-generation runtime was
loaded — the word *Native* never stands alone. A session whose frame generation changed shows the state that lasted
longest, always with its share: `×1.9 FG · 75%`.
- **Ray tracing, path tracing, ray reconstruction** are Yes, No or N/A, each with where it came from (measured, the
user's override, the game's default). Ray tracing is *Yes* on acceleration-structure builds or `DispatchRays`; *No*
needs a capable device, the hook in place and no activity at all. Path tracing has no signature in the API, so it is
only ever suggested.
- **Tier 1 and Tier 2 are never averaged together.** A query and a chart split by tier; comparing across tiers asks the
user first.
## The game's memory and the sensors
- The game's video memory and RAM are read from outside the game, as Task Manager shows them, once a second, in both
tiers.
- The PC's sensors come from three layers (Windows, LibreHardwareMonitor, NVAPI); what a layer cannot read is N/A.
*GPU held back* exists on NVIDIA cards only. CPU temperature needs the agent elevated and PawnIO installed.
What is still unmeasured, or measured on one machine only, is in [`LIMITATIONS.md`](../LIMITATIONS.md) and
[`legal/ACCURACY.md`](../legal/ACCURACY.md).
+37
View File
@@ -0,0 +1,37 @@
# Releasing
The full documents are [`docs/13_CI_CD.md`](../docs/13_CI_CD.md) and [`docs/11_UPDATER.md`](../docs/11_UPDATER.md).
## The workflows
| Workflow | Runs on | Does |
|---|---|---|
| `.github/workflows/ci.yml` | pushes to `main`, pull requests | `./build.ps1 check`, and on a pull request the changelog check. |
| `.github/workflows/codeql.yml` | pushes and pull requests to `main`, weekly | CodeQL for C# and C++. |
| `.github/workflows/rules-publish.yml` | a change to the detection rules or their validator | Fails when an anti-cheat entry is removed. |
| `.github/workflows/release.yml` | a pushed `v*` tag; by hand, a rehearsal | Builds, gates and publishes a release. |
| `.github/workflows/wiki.yml` | a successful release; by hand | Builds this wiki from `wiki/` and `guide/` and publishes it to the Wiki tab. |
## Cutting a release
1. One pull request moves the `[Unreleased]` entries of [`CHANGELOG.md`](../CHANGELOG.md) under a `## [x.y.z]` or
`## [x.y.z-beta.N]` heading with an *Updating from* note, and updates the release lines in `README.md`, the accuracy
statement (`legal/ACCURACY.md` and its copies) and `LIMITATIONS.md`. `VERSION` changes only with the numeric core.
2. After it merges, a signed tag `vx.y.z` (or `vx.y.z-beta.N`) on the merge commit starts `release.yml`:
- it checks the tag against `VERSION` and that the changelog has the section;
- writes the release date into the legal documents;
- runs the whole gate;
- publishes the App and the agent (self-contained, ReadyToRun) and checks the published tree;
- packs them with Velopack, with a delta from the previous release;
- writes `SHA256SUMS.txt`;
- creates the GitHub release from the changelog section, marked pre-release for a beta.
3. The wiki follows: `wiki.yml` runs when the release run succeeds.
4. Check the published assets against `SHA256SUMS.txt`, and the update feed.
Releases are not code-signed, so every release says so and publishes its checksums.
## How users get it
Velopack reads GitHub Releases. Settings ▸ Updates ▸ Channel is *Automatic* by default: a pre-release looks for
pre-releases, a release for releases. A new version downloads in the background and installs only when FrameLedger
restarts — never while a game is being recorded.
+45
View File
@@ -0,0 +1,45 @@
# Repository map
The layout with its history is in [`CLAUDE.md`](../CLAUDE.md) §Solution layout.
## Managed code (`src/`, .NET 10, C#)
| Project | What it holds |
|---|---|
| `src/FrameLedger.Domain` | Entities and the metric calculators. References nothing. |
| `src/FrameLedger.Application` | Use cases and ports: the capture loop, the session recorder, settings, the safety decisions. |
| `src/FrameLedger.Infrastructure` | SQLite, the shared-memory reader, telemetry, the native interop, parsers. The **only** project that calls native code. |
| `src/FrameLedger.Shared` | The pipe's message contracts and the C# mirror of the shared-memory structs. |
| `src/FrameLedger.Agent` | The capture agent's host: the watcher, the pipe server, the recorder. |
| `src/FrameLedger.App` | The WPF app (WPF UI 4.3.0): pages, dialogs, charts, strings in English, Vietnamese and Japanese. |
| `src/FrameLedger.CaptureHost` | A developer tool, never shipped. |
Dependencies point inwards: App and Agent → Application → Domain; Infrastructure implements Application's ports.
## Native code (`src/native/`, C++20, MSVC)
| Folder | What it holds |
|---|---|
| `src/native/FrameLedger.Overlay` | The component loaded into a game: hooks, the ring writer. |
| `src/native/FrameLedger.Injector` | The anti-cheat guard and injection, built into `FrameLedger.Guard.dll` for the agent. |
| `src/native/FrameLedger.VkLayer` | The Vulkan implicit layer and its manifest. |
| `src/native/FrameLedger.Shm` | The shared-memory layout, header-only; `fl_shm.h` is normative. |
| `src/native/FrameLedger.NvapiBridge` | NVIDIA telemetry, loaded by the agent. |
| `src/native/FrameLedger.ProcessStats` | The game's own memory, read from the agent. |
| `src/native/tests` | The native test suites (ctest). |
| `src/native/tools` | `hook-harness` (a dummy Direct3D 11/12, Vulkan and OpenGL app to hook), the probes, `fl-layout-dump`. |
| `src/native/third_party` | Vendored vendor headers: NVAPI, Streamline, FidelityFX, Vulkan. |
## Everything else
| Path | What it holds |
|---|---|
| `tests/` | One test project per managed project, plus shared helpers and fixtures. |
| `tools/` | The PowerShell gates and generators `./build.ps1` runs — see [Build and test](Build-and-test.md). |
| `rules/detection-rules.json` | Engine, platform and capability signatures, and the anti-cheat blocklist. |
| `guide/` | The user guide — embedded in the App, and the End-user half of this wiki. |
| `wiki/` | This wiki's own pages, published to the Wiki tab when a release is made. |
| `docs/` | The developer documents; [`docs/README.md`](../docs/README.md) is their index. |
| `legal/` | The documents a user accepts, the accuracy statement, licences and notices. |
| `.github/workflows/` | CI, CodeQL, the rules gate, the release and the wiki. |
| `LIMITATIONS.md` | What the whole software cannot do, in a player's words; also in the App. |
+31
View File
@@ -0,0 +1,31 @@
**[Home](Home.md)**
**Use FrameLedger**
- [User guide](../guide/README.md)
- [Install and first start](../guide/01-install.md)
- [Record a game](../guide/02-record-a-game.md)
- [Read your results](../guide/03-read-your-results.md)
- [Anti-cheat and safety](../guide/04-anti-cheat-and-safety.md)
- [Your data](../guide/05-your-data.md)
- [Questions and answers](../guide/06-faq.md)
- [The screens](../guide/07-screens.md)
- [Every setting](../guide/08-settings.md)
- [When something goes wrong](../guide/09-troubleshooting.md)
- [Words FrameLedger uses](../guide/10-glossary.md)
- [The terms, in plain words](../guide/terms-in-plain-words.md)
- [Limitations](../LIMITATIONS.md)
**Build or change FrameLedger**
- [Developers](Developers.md)
- [Architecture](Architecture.md)
- [Repository map](Repository-map.md)
- [Build and test](Build-and-test.md)
- [Contributor rules](Contributor-rules.md)
- [Capture pipeline](Capture-pipeline.md)
- [Metrics](Metrics.md)
- [Data and IPC](Data-and-IPC.md)
- [App UI development](App-UI-development.md)
- [Releasing](Releasing.md)
- [Developer glossary](Developer-glossary.md)