DOCUMENTATION_INDEX.md

PyKotor Documentation Index

Complete guide to PyKotor documentation, organized by topic and audience.

Knowledgebase navigation (agents & contributors)

Start here for implementation and debugging:

1. STRATEGY.md — product intent, metrics, active tracks
2. AGENTS.md — KB map, canonical pytest command, tool gotchas
3. docs/plans/ — active execution plans
4. docs/solutions/ — validated learnings (YAML frontmatter)
5. wiki/ — public format and RE specifications
6. docs/ — implementation deep dives (e.g. TSLPatchData index)

Quick Navigation

Getting Started

• README.md — Project overview, installation, quick start
• CONTRIBUTING.md — How to contribute (includes scoped pytest)
• AGENTS.md — Agent runbook and test commands

Design & Architecture

• FIGMA_INTEGRATION_SUMMARY.md — Figma integration overview
• FIGMA_DIAGRAMS.md — Architectural diagrams
• Design System Rules — UI design system
• Code Connect Examples — Figma-to-code mappings

Development

• CONTRIBUTING.md — Contribution guidelines
• CONVENTIONS.md — Code conventions
• POWERSHELL.md — PowerShell setup for Windows

Reference Documentation

• PyKotor Library Docs — Core library API documentation
• Project Wiki — Community documentation
• File Format Documentation — In-tree game file format specifications

Validated learnings (solutions)

Topic	Doc
BWM / walkmesh authority	docs/solutions/documentation/authoritative-bwm-wiki-from-re-and-pipelines.md
Save/load engine parity	docs/solutions/logic-errors/kotor-save-load-1-1-python-from-re.md
TSLPatcher parity harness	docs/solutions/testing/tslpatcher-parity-harness-mvp.md

Tool-Specific Documentation

• HolocronToolset — GUI editor suite
• HoloPatcher — Mod installer
• KotorDiff — Diff tool
• BatchPatcher — Batch processing
• HoloPazaak — Pazaak game

---

By Audience

For New Developers

1. Read README.md for project overview
2. Follow CONTRIBUTING.md for environment and test commands
3. Use AGENTS.md for scoped pytest and Linux gotchas
4. Check FIGMA_DIAGRAMS.md for architecture context

For Contributors

1. Read CONTRIBUTING.md first
2. Follow CONVENTIONS.md for code style
3. Reference AGENTS.md for CI-aligned test commands
4. Check docs/solutions/ before changing documented areas

For AI Assistants

1. Read AGENTS.md KB map and pytest block
2. Consult STRATEGY.md for metric-linked paths
3. Check docs/solutions/ for prefer/defer/avoid in documented domains
4. Follow Design System Rules for Holocron UI work

---

Quick Reference

Essential test command

QT_QPA_PLATFORM=offscreen uv run pytest --import-mode=importlib -m "not gui and not slow" --timeout=120 \
  --ignore=Libraries/PyKotor/tests/resource/formats/test_mdl_ascii.py \
  --ignore=Libraries/PyKotor/tests/test_utility/test_registry_strict_typing.py \
  --ignore=Libraries/PyKotor/tests/test_utility/test_file_dialog_components.py \
  Libraries/PyKotor/tests

Parity harness smoke:

QT_QPA_PLATFORM=offscreen uv run pytest --import-mode=importlib -m "not gui and not slow" --timeout=120 \
  Libraries/PyKotor/tests/tslpatcher/parity/test_parity_harness.py -v

Essential file locations

PyKotor/
├── STRATEGY.md             # Product metrics and tracks
├── AGENTS.md               # Agent KB map + pytest
├── Libraries/PyKotor/      # Core library + tests
├── Tools/                  # Holocron, HoloPatcher, KotorDiff, …
├── docs/plans/             # Execution plans
├── docs/solutions/         # Validated learnings
├── wiki/                   # Format specs
└── pyproject.toml          # Workspace config

---

Removed / relocated paths

These paths are not maintained at the locations previously listed here:

• docs/SETUP.md — use CONTRIBUTING.md and README.md
• docs/QUICK_START.md — use docs/INDEX.md (TSLPatchData) and AGENTS.md

---

Last Updated: 2026-05-23