pysage-tools 0.1.0__tar.gz

pysage_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clement Julia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pysage_tools-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: pysage-tools
+Version: 0.1.0
+Summary: Python tools for the data formats of the SAGE engine (Battle for Middle-earth): ini game data, binary maps, replays, and UI movies.
+Author-email: Clement Julia <clement.julia13@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ClementJ18/pySAGE
+Project-URL: Repository, https://github.com/ClementJ18/pySAGE
+Project-URL: Issues, https://github.com/ClementJ18/pySAGE/issues
+Keywords: sage,bfme,ini,parser,linter,map,replay,modding
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: reversebox>=0.84; sys_platform == "win32"
+Provides-Extra: ui
+Requires-Dist: PyQt6>=6.6; extra == "ui"
+Requires-Dist: pybig>=0.6; extra == "ui"
+Requires-Dist: pillow>=10; extra == "ui"
+Provides-Extra: lint-ui
+Requires-Dist: PyQt6>=6.6; extra == "lint-ui"
+Provides-Extra: wiki
+Requires-Dist: mwclient>=0.11; extra == "wiki"
+Requires-Dist: mwparserfromhell>=0.7; extra == "wiki"
+Requires-Dist: PyQt6>=6.6; extra == "wiki"
+Requires-Dist: pybig>=0.6; extra == "wiki"
+Requires-Dist: keyring>=24; extra == "wiki"
+Provides-Extra: edain-ui
+Requires-Dist: PyQt6>=6.6; extra == "edain-ui"
+Provides-Extra: apt
+Requires-Dist: pybig>=0.6; extra == "apt"
+Dynamic: license-file
+
+# pySAGE
+
+A collection of Python tools for reading, editing, linting and visualising the data
+formats of the **SAGE engine** - the engine behind *Command & Conquer: Generals* and
+*The Battle for Middle-earth*. It grew out of an ini parser and now spans ini game data,
+binary maps, replays, and UI, with a domain overlay for the Edain mod.
+
+Everything installs as one package with optional extras (see [Install](#install)). Each
+subproject has its own README with the details; this page is the map.
+
+## Projects
+
+### Ini game data
+
+| Project | What it is |
+| --- | --- |
+| [`sage_ini`](sage_ini/README.md) | The foundation: a typed, comment-preserving `.ini` parser, a whole-game loader, the cross-reference graph, and a lossless AST. Everything else builds on it. |
+| [`sage_lint`](sage_lint/README.md) | Formatter and linter over `sage_ini` - canonical reprint plus judgment rules (dangling references, out-of-range values, duplicates, unused definitions) and meta-analysis. |
+
+### Binary formats
+
+| Project | What it is |
+| --- | --- |
+| [`sage_map`](sage_map/README.md) | Reader/writer for BFME `.map` files, plus a game-aware overlay that resolves script arguments and object references and lints maps. |
+| [`sage_replay`](sage_replay/README.md) | Reader for SAGE replay files (Generals `.rep`, BFME / BFME2 / RotWK) - the recorded order stream, decoded into build orders, APM and command timing. |
+| [`sage_apt`](sage_apt/README.md) | Converter, viewer and editor for `.apt` UI movies (the Flash-derived format behind BFME's menus and HUD). **Work in progress**, not yet fully functional. |
+
+### Domain overlays & apps
+
+| Project | What it is |
+| --- | --- |
+| [`sage_mods.edain`](sage_mods/edain/README.md) | Edain-mod overlay: builds a faction ownership graph (spellbook → base → structures → units/heroes/upgrades) and renders, diffs or serves it. |
+| [`sage_wiki`](sage_wiki/README.md) | Desktop tool that updates Edain wiki infoboxes from parsed game data through the MediaWiki API. |
+| [`sage_ui`](sage_ui/README.md) | PyQt6 desktop browser for SAGE game data: load sources, search an object, see its resolved stats. |
+
+### Shared
+
+| Project | What it is |
+| --- | --- |
+| [`sage_utils`](sage_utils/README.md) | Helpers shared by more than one front end: the Qt-free data layer (sources, textures, views, the faction-graph types) and the shared Qt chrome. |
+
+## Install
+
+Requires Python ≥ 3.12. The project is **pySAGE**; on PyPI it is published as **`pysage-tools`**.
+
+> **Note:** the bare `pysage` name on PyPI is an unrelated, abandoned messaging library last
+> released in 2011, and `py-sage` is likewise taken by another project. `pip install pysage` will
+> *not* get you this project - install `pysage-tools`.
+
+```sh
+pip install pysage-tools             # core library + linter
+pip install "pysage-tools[ui]"       # + the PyQt6 desktop apps (sage-ui)
+pip install "pysage-tools[wiki]"     # + the wiki updater
+pip install "pysage-tools[edain-ui]" # + the Edain Linter desktop app
+pip install "pysage-tools[apt]"      # + reading .const/.apt out of .big archives
+```
+
+From a clone, for development, swap the name for an editable install of the checkout:
+
+```sh
+pip install -e ".[ui]"
+```
+
+The extras (`ui`, `lint-ui`, `wiki`, `edain-ui`, `apt`) pull in the optional dependencies each
+peripheral tool needs. The ini, map and replay layers are stdlib-only and always ship, so no
+extra is needed to parse, lint or diff a map. The one non-optional dependency is `reversebox` on
+Windows, the native RefPack compressor that makes saving large maps fast (its DLL is Windows-only,
+so other platforms use the byte-identical pure-Python compressor).
+
+Console scripts are installed for the CLI tools: `sage-ini`, `sage-lint`, `sage-edain`,
+`sage-replay`, `sage-apt` (and the GUI scripts `sage-ui`, `sage-wiki`, `sage-lint-ui`,
+`sage-edain-lint` - the Edain Linter, which combines the ini and map checks in one window).
+
+## Tests
+
+```sh
+pytest            # fast, data-free core suite
+pytest --full     # + corpus acceptance gates and peripheral-package suites
+```
+
+## Contributing
+
+Contributions are welcome - bug reports, fixes, new checks and rules, format coverage, and
+documentation all help. See **[CONTRIBUTING.md](CONTRIBUTING.md)** to get set up and
+**[CONVENTIONS.md](CONVENTIONS.md)** for the coding rules. AI-assisted contributions are
+welcome too, with one expectation: you have read, understood, and can stand behind every
+line you submit.

pysage_tools-0.1.0/README.md

@@ -0,0 +1,87 @@
+# pySAGE
+
+A collection of Python tools for reading, editing, linting and visualising the data
+formats of the **SAGE engine** - the engine behind *Command & Conquer: Generals* and
+*The Battle for Middle-earth*. It grew out of an ini parser and now spans ini game data,
+binary maps, replays, and UI, with a domain overlay for the Edain mod.
+
+Everything installs as one package with optional extras (see [Install](#install)). Each
+subproject has its own README with the details; this page is the map.
+
+## Projects
+
+### Ini game data
+
+| Project | What it is |
+| --- | --- |
+| [`sage_ini`](sage_ini/README.md) | The foundation: a typed, comment-preserving `.ini` parser, a whole-game loader, the cross-reference graph, and a lossless AST. Everything else builds on it. |
+| [`sage_lint`](sage_lint/README.md) | Formatter and linter over `sage_ini` - canonical reprint plus judgment rules (dangling references, out-of-range values, duplicates, unused definitions) and meta-analysis. |
+
+### Binary formats
+
+| Project | What it is |
+| --- | --- |
+| [`sage_map`](sage_map/README.md) | Reader/writer for BFME `.map` files, plus a game-aware overlay that resolves script arguments and object references and lints maps. |
+| [`sage_replay`](sage_replay/README.md) | Reader for SAGE replay files (Generals `.rep`, BFME / BFME2 / RotWK) - the recorded order stream, decoded into build orders, APM and command timing. |
+| [`sage_apt`](sage_apt/README.md) | Converter, viewer and editor for `.apt` UI movies (the Flash-derived format behind BFME's menus and HUD). **Work in progress**, not yet fully functional. |
+
+### Domain overlays & apps
+
+| Project | What it is |
+| --- | --- |
+| [`sage_mods.edain`](sage_mods/edain/README.md) | Edain-mod overlay: builds a faction ownership graph (spellbook → base → structures → units/heroes/upgrades) and renders, diffs or serves it. |
+| [`sage_wiki`](sage_wiki/README.md) | Desktop tool that updates Edain wiki infoboxes from parsed game data through the MediaWiki API. |
+| [`sage_ui`](sage_ui/README.md) | PyQt6 desktop browser for SAGE game data: load sources, search an object, see its resolved stats. |
+
+### Shared
+
+| Project | What it is |
+| --- | --- |
+| [`sage_utils`](sage_utils/README.md) | Helpers shared by more than one front end: the Qt-free data layer (sources, textures, views, the faction-graph types) and the shared Qt chrome. |
+
+## Install
+
+Requires Python ≥ 3.12. The project is **pySAGE**; on PyPI it is published as **`pysage-tools`**.
+
+> **Note:** the bare `pysage` name on PyPI is an unrelated, abandoned messaging library last
+> released in 2011, and `py-sage` is likewise taken by another project. `pip install pysage` will
+> *not* get you this project - install `pysage-tools`.
+
+```sh
+pip install pysage-tools             # core library + linter
+pip install "pysage-tools[ui]"       # + the PyQt6 desktop apps (sage-ui)
+pip install "pysage-tools[wiki]"     # + the wiki updater
+pip install "pysage-tools[edain-ui]" # + the Edain Linter desktop app
+pip install "pysage-tools[apt]"      # + reading .const/.apt out of .big archives
+```
+
+From a clone, for development, swap the name for an editable install of the checkout:
+
+```sh
+pip install -e ".[ui]"
+```
+
+The extras (`ui`, `lint-ui`, `wiki`, `edain-ui`, `apt`) pull in the optional dependencies each
+peripheral tool needs. The ini, map and replay layers are stdlib-only and always ship, so no
+extra is needed to parse, lint or diff a map. The one non-optional dependency is `reversebox` on
+Windows, the native RefPack compressor that makes saving large maps fast (its DLL is Windows-only,
+so other platforms use the byte-identical pure-Python compressor).
+
+Console scripts are installed for the CLI tools: `sage-ini`, `sage-lint`, `sage-edain`,
+`sage-replay`, `sage-apt` (and the GUI scripts `sage-ui`, `sage-wiki`, `sage-lint-ui`,
+`sage-edain-lint` - the Edain Linter, which combines the ini and map checks in one window).
+
+## Tests
+
+```sh
+pytest            # fast, data-free core suite
+pytest --full     # + corpus acceptance gates and peripheral-package suites
+```
+
+## Contributing
+
+Contributions are welcome - bug reports, fixes, new checks and rules, format coverage, and
+documentation all help. See **[CONTRIBUTING.md](CONTRIBUTING.md)** to get set up and
+**[CONVENTIONS.md](CONVENTIONS.md)** for the coding rules. AI-assisted contributions are
+welcome too, with one expectation: you have read, understood, and can stand behind every
+line you submit.

pysage_tools-0.1.0/pyproject.toml

@@ -0,0 +1,184 @@
+[build-system]
+requires = ["setuptools>=77"]  # >=77 for the PEP 639 SPDX `license` field below
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pysage-tools"
+version = "0.1.0"
+description = "Python tools for the data formats of the SAGE engine (Battle for Middle-earth): ini game data, binary maps, replays, and UI movies."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Clement Julia", email = "clement.julia13@gmail.com" },
+]
+keywords = ["sage", "bfme", "ini", "parser", "linter", "map", "replay", "modding"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    # Native RefPack compressor for map saving (`sage_utils.refpack`). reversebox ships a
+    # Windows-only DLL, so the marker installs it exactly where it can load; every other
+    # platform resolves to no dependencies at all and uses the pure-Python compressor.
+    "reversebox>=0.84; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/ClementJ18/pySAGE"
+Repository = "https://github.com/ClementJ18/pySAGE"
+Issues = "https://github.com/ClementJ18/pySAGE/issues"
+
+[project.scripts]
+sage-lint = "sage_lint.cli:main"
+sage-ini = "sage_ini.__main__:main"
+sage-edain = "sage_mods.edain.__main__:main"
+sage-replay = "sage_replay.__main__:main"
+sage-apt = "sage_apt.__main__:main"
+sage-save = "sage_save.__main__:main"
+sage-map = "sage_map.__main__:main"
+
+# Desktop apps; each needs its extra installed (ui / wiki / lint-ui / edain-ui).
+[project.gui-scripts]
+sage-ui = "sage_ui.app:main"
+sage-wiki = "sage_wiki.launcher:main"  # guards the [wiki] extra; app.py imports Qt at module scope
+sage-lint-ui = "sage_lint.plugins.ui.app:main"
+sage-edain-lint = "sage_mods.edain.map_checks.ui.app:main"
+
+[project.optional-dependencies]
+ui = [
+    "PyQt6>=6.6",
+    "pybig>=0.6",
+    "pillow>=10",
+]
+
+lint-ui = [
+    "PyQt6>=6.6",
+]
+
+wiki = [
+    "mwclient>=0.11", 
+    "mwparserfromhell>=0.7", 
+    "PyQt6>=6.6", 
+    "pybig>=0.6",
+    "keyring>=24",
+]
+
+edain-ui = [
+    "PyQt6>=6.6",
+]
+
+apt = [
+    "pybig>=0.6",  # reading a .const (or .apt) out of a .big archive; the core stays stdlib-only
+]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "mypy",
+    "pyinstaller>=6",  # builds the desktop .exe bundles (the *.spec files); not a runtime dep
+]
+
+[tool.setuptools.packages.find]
+include = ["sage_apt*", "sage_ini*", "sage_lint*", "sage_map*", "sage_replay*", "sage_save*", "sage_utils*", "sage_wiki*", "sage_ui*", "sage_mods*"]
+
+[tool.setuptools.package-data]
+# Anything a package opens at runtime must be listed here, or it is absent from the wheel. The
+# loaders degrade silently (a missing asset returns None), so an omission surfaces as a feature
+# quietly not working rather than an error; tests/test_packaging.py asserts every runtime asset
+# below is shipped.
+sage_apt = ["assets/*.html", "py.typed"]
+sage_ini = ["py.typed", "skill_assets/**/*"]
+sage_map = ["py.typed"]
+sage_save = ["py.typed"]
+sage_replay = ["py.typed"]
+sage_ui = ["*.ico"]
+sage_wiki = ["*.ico"]
+sage_utils = ["assets/*.png"]  # portrait background + overlays; sage_utils/textures.py
+"sage_lint.plugins.ui" = ["*.ico"]
+sage_mods = ["py.typed"]  # PEP 561 marker belongs on the top-level package, not sage_mods.edain
+"sage_mods.edain" = [
+    "ui/*",
+    "skill_assets/**/*",
+    "map_checks/ui/*.ico",
+    "icons/*.webp",  # faction emblems; the public ICONS_DIR / FACTION_ICONS in edain/replay.py
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = [
+    "full: part of the full suite (corpus gates + peripheral packages); run with --full",
+]
+
+[tool.ruff]
+target-version = "py312"  # matches requires-python, so pyupgrade cannot suggest 3.13-only syntax
+line-length = 100
+extend-exclude = [
+    "data", # game-data corpus
+]
+
+[tool.ruff.lint]
+select = [
+    "E",       # pycodestyle errors (E722: no bare `except:`)
+    "W",       # pycodestyle warnings
+    "F",       # pyflakes
+    "I",       # isort - deterministic import order
+    "B",       # bugbear (B009/B010: no getattr/setattr with constant attribute names)
+    "UP",      # pyupgrade
+    "BLE",     # blind-except: no `except Exception:` swallowing
+    "PLC0415", # all imports at module top level; no function-local imports
+]
+
+[tool.ruff.lint.per-file-ignores]
+"sage_ini/model/behaviors.py" = ["F821"]
+"sage_ini/model/nuggets.py" = ["F821"]
+"sage_ini/model/data_blocks.py" = ["F821"]
+# The embedded single-page HTML/CSS/JS template carries lines longer than the Python limit.
+"sage_apt/viewer.py" = ["E501"]
+"sage_replay/aggregate.py" = ["E501"]
+
+[tool.ruff.format]
+
+[tool.mypy]
+python_version = "3.12"  # matches requires-python: catch 3.13-only API use on the lowest floor
+files = ["sage_apt", "sage_ini", "sage_map", "sage_mods", "sage_replay", "sage_save", "sage_utils"]
+disable_error_code = ["annotation-unchecked"]
+
+[[tool.mypy.overrides]]
+module = ["reversebox.*", "PyQt6.*", "pyBIG.*", "PIL.*"]
+ignore_missing_imports = true
+
+# The Qt half of sage_utils (and the texture/source layer built on optional deps) is outside
+# the type-checked set: it needs the [ui] extras installed and predates annotations. The
+# Qt-free helpers (config, views, skill, cli) are checked like the core packages.
+[[tool.mypy.overrides]]
+module = [
+    "sage_utils.widgets",
+    "sage_utils.styles",
+    "sage_utils.textures",
+    "sage_utils.sources",
+    "sage_utils.findings",
+]
+ignore_errors = true
+
+# Same for the Qt half of the Edain Linter window; its Qt-free runner stays checked.
+[[tool.mypy.overrides]]
+module = ["sage_mods.edain.map_checks.ui.window", "sage_mods.edain.map_checks.ui.app"]
+ignore_errors = true
+
+# sage_lint is a tool package, not in the type-checked `files` set. sage_mods.edain.map_checks imports
+# its shared map-lint runner (add_map_lint_arguments / run_map_lint), which pulls sage_lint into
+# reach: follow the import so sage_mods.edain still sees real types, but don't gate on sage_lint's own
+# (pre-existing) errors here - it is checked on its own terms, not through this overlay.
+[[tool.mypy.overrides]]
+module = ["sage_lint.*"]
+follow_imports = "silent"

pysage_tools-0.1.0/pysage_tools.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: pysage-tools
+Version: 0.1.0
+Summary: Python tools for the data formats of the SAGE engine (Battle for Middle-earth): ini game data, binary maps, replays, and UI movies.
+Author-email: Clement Julia <clement.julia13@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ClementJ18/pySAGE
+Project-URL: Repository, https://github.com/ClementJ18/pySAGE
+Project-URL: Issues, https://github.com/ClementJ18/pySAGE/issues
+Keywords: sage,bfme,ini,parser,linter,map,replay,modding
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: reversebox>=0.84; sys_platform == "win32"
+Provides-Extra: ui
+Requires-Dist: PyQt6>=6.6; extra == "ui"
+Requires-Dist: pybig>=0.6; extra == "ui"
+Requires-Dist: pillow>=10; extra == "ui"
+Provides-Extra: lint-ui
+Requires-Dist: PyQt6>=6.6; extra == "lint-ui"
+Provides-Extra: wiki
+Requires-Dist: mwclient>=0.11; extra == "wiki"
+Requires-Dist: mwparserfromhell>=0.7; extra == "wiki"
+Requires-Dist: PyQt6>=6.6; extra == "wiki"
+Requires-Dist: pybig>=0.6; extra == "wiki"
+Requires-Dist: keyring>=24; extra == "wiki"
+Provides-Extra: edain-ui
+Requires-Dist: PyQt6>=6.6; extra == "edain-ui"
+Provides-Extra: apt
+Requires-Dist: pybig>=0.6; extra == "apt"
+Dynamic: license-file
+
+# pySAGE
+
+A collection of Python tools for reading, editing, linting and visualising the data
+formats of the **SAGE engine** - the engine behind *Command & Conquer: Generals* and
+*The Battle for Middle-earth*. It grew out of an ini parser and now spans ini game data,
+binary maps, replays, and UI, with a domain overlay for the Edain mod.
+
+Everything installs as one package with optional extras (see [Install](#install)). Each
+subproject has its own README with the details; this page is the map.
+
+## Projects
+
+### Ini game data
+
+| Project | What it is |
+| --- | --- |
+| [`sage_ini`](sage_ini/README.md) | The foundation: a typed, comment-preserving `.ini` parser, a whole-game loader, the cross-reference graph, and a lossless AST. Everything else builds on it. |
+| [`sage_lint`](sage_lint/README.md) | Formatter and linter over `sage_ini` - canonical reprint plus judgment rules (dangling references, out-of-range values, duplicates, unused definitions) and meta-analysis. |
+
+### Binary formats
+
+| Project | What it is |
+| --- | --- |
+| [`sage_map`](sage_map/README.md) | Reader/writer for BFME `.map` files, plus a game-aware overlay that resolves script arguments and object references and lints maps. |
+| [`sage_replay`](sage_replay/README.md) | Reader for SAGE replay files (Generals `.rep`, BFME / BFME2 / RotWK) - the recorded order stream, decoded into build orders, APM and command timing. |
+| [`sage_apt`](sage_apt/README.md) | Converter, viewer and editor for `.apt` UI movies (the Flash-derived format behind BFME's menus and HUD). **Work in progress**, not yet fully functional. |
+
+### Domain overlays & apps
+
+| Project | What it is |
+| --- | --- |
+| [`sage_mods.edain`](sage_mods/edain/README.md) | Edain-mod overlay: builds a faction ownership graph (spellbook → base → structures → units/heroes/upgrades) and renders, diffs or serves it. |
+| [`sage_wiki`](sage_wiki/README.md) | Desktop tool that updates Edain wiki infoboxes from parsed game data through the MediaWiki API. |
+| [`sage_ui`](sage_ui/README.md) | PyQt6 desktop browser for SAGE game data: load sources, search an object, see its resolved stats. |
+
+### Shared
+
+| Project | What it is |
+| --- | --- |
+| [`sage_utils`](sage_utils/README.md) | Helpers shared by more than one front end: the Qt-free data layer (sources, textures, views, the faction-graph types) and the shared Qt chrome. |
+
+## Install
+
+Requires Python ≥ 3.12. The project is **pySAGE**; on PyPI it is published as **`pysage-tools`**.
+
+> **Note:** the bare `pysage` name on PyPI is an unrelated, abandoned messaging library last
+> released in 2011, and `py-sage` is likewise taken by another project. `pip install pysage` will
+> *not* get you this project - install `pysage-tools`.
+
+```sh
+pip install pysage-tools             # core library + linter
+pip install "pysage-tools[ui]"       # + the PyQt6 desktop apps (sage-ui)
+pip install "pysage-tools[wiki]"     # + the wiki updater
+pip install "pysage-tools[edain-ui]" # + the Edain Linter desktop app
+pip install "pysage-tools[apt]"      # + reading .const/.apt out of .big archives
+```
+
+From a clone, for development, swap the name for an editable install of the checkout:
+
+```sh
+pip install -e ".[ui]"
+```
+
+The extras (`ui`, `lint-ui`, `wiki`, `edain-ui`, `apt`) pull in the optional dependencies each
+peripheral tool needs. The ini, map and replay layers are stdlib-only and always ship, so no
+extra is needed to parse, lint or diff a map. The one non-optional dependency is `reversebox` on
+Windows, the native RefPack compressor that makes saving large maps fast (its DLL is Windows-only,
+so other platforms use the byte-identical pure-Python compressor).
+
+Console scripts are installed for the CLI tools: `sage-ini`, `sage-lint`, `sage-edain`,
+`sage-replay`, `sage-apt` (and the GUI scripts `sage-ui`, `sage-wiki`, `sage-lint-ui`,
+`sage-edain-lint` - the Edain Linter, which combines the ini and map checks in one window).
+
+## Tests
+
+```sh
+pytest            # fast, data-free core suite
+pytest --full     # + corpus acceptance gates and peripheral-package suites
+```
+
+## Contributing
+
+Contributions are welcome - bug reports, fixes, new checks and rules, format coverage, and
+documentation all help. See **[CONTRIBUTING.md](CONTRIBUTING.md)** to get set up and
+**[CONVENTIONS.md](CONVENTIONS.md)** for the coding rules. AI-assisted contributions are
+welcome too, with one expectation: you have read, understood, and can stand behind every
+line you submit.