Skip to content

Sources — Provenance of the documents

This file records where each Markdown file in this directory came from. The originals remain in their respective source repositories and are the canonical version there — this collection is a consolidation copy intended for a central public documentation site.

Snapshot

The files here mirror the source repositories at the following state as of 2026-04-30:

Source Workstation path Branch Commit
RaceLink_Host C:/Users/psima/Dev/RaceLink_Host wled-advanced-control ca3670c
RaceLink_Gateway C:/Users/psima/Dev/RaceLink_Gateway continous-rx-mode 25ba773
RaceLink_WLED C:/Users/psima/Dev/RaceLink_WLED auto-identify 91db41c
RaceLink_RH_Plugin C:/Users/psima/Dev/RaceLink_RH_Plugin adapt-host-changes fc0f36f
Plans folder (no repo) C:/Users/psima/.claude/plans/ working copy 2026-04-30

Note: the host snapshot was taken from a working tree with uncommitted changes (git status showed several modified files, notably under docs/). The content of these copies therefore reflects the working-copy state, not necessarily the HEAD commit ca3670c.

File-by-file directory

Top level

Consolidated path Origin Note
README.md new, written for this consolidation Top-level index and navigation
SOURCES.md new This provenance file
GLOSSARY.md new Single canonical glossary spanning all audiences
LICENSES.md new Reconciled per-component licence list
VERSIONING.md new Cross-component compatibility
CONTRIBUTING.md new PR rules, smoke tests
CHANGELOG.md new (initially empty) Release timeline
TROUBLESHOOTING.md new Operator-side index aggregating all sub-doc tips
HARVEST.md new Inventory of what was mined from plans/
AUDIT_RESPONSE.md new Map of audit findings → fixes applied
Consolidated path Source path Note
host/README.md RaceLink_Host/README.md Cleaned: fixed Windows-absolute path, trimmed duplicated system overview
host/ARCHITECTURE.md RaceLink_Host/ARCHITECTURE.md Cleaned: includes the content of docs/repo_split_map.md as a "Repo split history" subsection
host/docs/OPERATOR_GUIDE.md RaceLink_Host/docs/OPERATOR_GUIDE.md Cleaned: cross-links updated; cyclic-effect phase-lock note added (see HARVEST.md)
host/docs/DEVELOPER_GUIDE.md RaceLink_Host/docs/DEVELOPER_GUIDE.md Fixed the "three vs four gates" wording contradiction (audit C1); replaced workstation paths with upstream-WLED references
host/docs/PROTOCOL.md RaceLink_Host/docs/PROTOCOL.md Verbatim
host/docs/UI_CONVENTIONS.md RaceLink_Host/docs/UI_CONVENTIONS.md Verbatim
host/docs/standalone.md RaceLink_Host/docs/standalone.md Verbatim
host/docs/repo_split_map.md (folded into ARCHITECTURE.md) Original retained in the source repo
Consolidated path Source path Note
gateway/README.md RaceLink_Gateway/readme.md Cleaned: dropped duplicated system overview (now lives in root README)
gateway/OPERATOR.md new (gap G2) Operator setup that did not exist in the source
Consolidated path Source path Note
wled/README.md RaceLink_WLED/readme.md Cleaned: dropped duplicated system overview
wled/OPERATOR.md new (gap G3) Operator setup that did not exist in the source
wled/docs/effects-deterministic.md RaceLink_WLED/docs/effects-deterministic.md Verbatim
Consolidated path Source path Note
rh-plugin/README.md RaceLink_RH_Plugin/README.md Cleaned: trimmed duplicated system overview
rh-plugin/OPERATOR.md new (gap G4) Operator setup inside RotorHazard
rh-plugin/docs/release-playbook.md RaceLink_RH_Plugin/docs/release-playbook.md Verbatim
rh-plugin/docs/manifest-dependency-format.md RaceLink_RH_Plugin/docs/manifest-dependency-format.md Verbatim — see also ADR-0001 in maintainer/adr/

reference/ — cross-component reference

Consolidated path Origin Note
reference/SCENE_FORMAT.md new (gap G10) Distilled from host/docs/OPERATOR_GUIDE.md and the scene-manager-feature plan
reference/SSE_CHANNELS.md new (gap G12) Distilled from host/ARCHITECTURE.md § UI Scope Matrix
reference/WEB_API.md new (gap G11; stub) Source code not available in this consolidation; produced as a stub with a clear TODO

maintainer/

Consolidated path Origin Note
maintainer/adr/README.md new (gap G13) ADR index
maintainer/adr/0001-rh-plugin-manifest-dependency.md rephrased from rh-plugin/docs/manifest-dependency-format.md First ADR in canonical Context/Decision/Consequence format

What was deliberately NOT included

The following Markdown files exist in the source repositories but were not pulled in, because they are not RaceLink-specific documentation:

  • Third-party libraries under RaceLink_Gateway/.pio/libdeps/** (RadioLib, U8g2 — their README.md, CONTRIBUTING.md, SECURITY.md etc. belong to those upstream projects).
  • PyPI cache and build artefacts under RaceLink_RH_Plugin/.tmp/**, .venv/**, .tools/**, dist/** (Flask, Werkzeug, idna, offline staging copies of the plugin).
  • Pytest cache (.pytest_cache/README.md in several repos).
  • Claude session logs under ~/.claude/projects/c--Users-psima-Dev-RaceLink-*/*.jsonl — full conversation transcripts; not documentation, and not publicly relevant. Markdown memos under memory/ of individual projects (e.g. c--Users-psima-Dev-WLED-LoRa-WLED/memory/*.md) are similarly excluded — they are project-private notes to Claude, not project documentation.
  • The 16 plan files under plans/ in the source — they are an internal engineering ledger. Their public-relevant content has been mined into the appropriate documents in this consolidation; see HARVEST.md for the trace.

The exclusion can be reproduced with:

# Inside each source repo:
find . -name "*.md" -not -path "*/.pio/*" \
  -not -path "*/.venv/*" -not -path "*/.tmp/*" \
  -not -path "*/.tools/*" -not -path "*/dist/*" \
  -not -path "*/.pytest_cache/*"

Keeping this collection in sync

When a source document changes, the copy here goes stale. Update procedure:

  1. Identify the changed document in the relevant source repository.
  2. Copy the file from the source path to the consolidated path listed above (e.g. cp RaceLink_Host/docs/PROTOCOL.md RaceLink_Docs/docs/host/docs/PROTOCOL.md).
  3. Re-apply the audit-driven fixes documented in AUDIT_RESPONSE.md where they touch the updated file.
  4. Update the Snapshot block above (date, branch, commit).
  5. For structural changes (new file, removed file, renamed path) also update the file-by-file table here and the navigation in index.md.

Known limitations of the copies

  • Source-code cross-references do not resolve. Many of the original documents reference source files relatively (e.g. ../racelink/services/foo.py). This consolidation contains no source code — those links work only inside the source repository. For source-code references, see the matching source repository.
  • Cross-repo workstation paths do not resolve. For example, host/docs/DEVELOPER_GUIDE.md originally referenced ../../WLED LoRa/WLED/...; those paths are workstation-specific and not part of this set. Where they were essential, the references have been replaced with text references to the upstream WLED source layout (wled00/wled_server.cpp, etc.).
  • Markdown-to-Markdown links inside the same sub-project still work (e.g. host/docs/OPERATOR_GUIDE.mdhost/docs/PROTOCOL.md), because the original directory structure is preserved per-repo.
  • The source repository remains the source of truth. When a copy here and the source disagree, the source wins.