# Specs Overview

This directory contains the repository's format and behavior specs for the RimWorld modpack tool.

These specs are intended to be read as a connected set, not as isolated documents. When code, tests, and docs change, they should stay aligned with the relevant spec files here.

## How To Use These Specs

- Treat the files in this directory as the source of truth for persisted project formats and pipeline behavior.
- Prefer the smallest implementation that matches the current wording.
- If a requested behavior conflicts with a spec, update the spec in the same change instead of letting code drift.
- Keep a clear separation between authored project files, generated outputs, and user-local tool configuration.

## Recommended Reading Order

Read the specs in this order:

1. [`modpack_folder_layout_spec.md`](D:\Projects\rimworld\rimpack\specs\modpack_folder_layout_spec.md)
2. [`pack_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\pack_toml_spec.md)
3. [`rimworld_modpack_list_format_spec.md`](D:\Projects\rimworld\rimpack\specs\rimworld_modpack_list_format_spec.md)
4. [`activation_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\activation_toml_spec.md)
5. [`ordering_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\ordering_toml_spec.md)
6. [`tool_config_spec.md`](D:\Projects\rimworld\rimpack\specs\tool_config_spec.md)

Why this order:

- Start with folder layout to understand project structure and authored vs generated boundaries.
- Read `pack.toml` next because it is the root manifest that points to the rest of the project.
- Read `.list` format next because it defines the primary authored mod intent.
- Read activation and ordering rules after `.list` files because they layer on top of authored entries rather than replacing them.
- Read tool config last because it is user-local machine configuration, not pack-authored project state.

## Spec Map

### Project structure

- [`modpack_folder_layout_spec.md`](D:\Projects\rimworld\rimpack\specs\modpack_folder_layout_spec.md)
  Defines the expected pack directory layout and the boundary between authored files and generated output.

- [`pack_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\pack_toml_spec.md)
  Defines the root manifest, including pack metadata, ordered mod-list files, and referenced rule/output paths.

### Authored pack inputs

- [`rimworld_modpack_list_format_spec.md`](D:\Projects\rimworld\rimpack\specs\rimworld_modpack_list_format_spec.md)
  Defines the text-first `.list` format, preservation rules, entry syntax, disabled entries, and unknown-line handling.

- [`activation_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\activation_toml_spec.md)
  Defines activation rules that decide whether resolved candidate entries are active for a given resolution run.

- [`ordering_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\ordering_toml_spec.md)
  Defines explicit ordering constraints that apply after resolution and after activation outcomes are known.

### User-local machine configuration

- [`tool_config_spec.md`](D:\Projects\rimworld\rimpack\specs\tool_config_spec.md)
  Defines machine-local configuration such as install paths. This is outside the modpack project and is not part of pack-authored state.

## Conceptual Pipeline

At a high level, the specs describe this flow:

1. Read `pack.toml`.
2. Load the authored `.list` files in `layout.mod_files` order.
3. Parse enabled and disabled authored entries while preserving file structure.
4. Resolve authored references to canonical mod identities.
5. Evaluate activation rules against resolved entries.
6. Apply ordering rules to the active resolved set.
7. Write generated outputs such as diagnostics or resolved load-order exports.
8. Build a machine-local launchable RimWorld view using symlinks.
9. Launch RimWorld from that symlinked view.

This is the intended mental model:

- `pack.toml` describes the project.
- `.list` files express authored mod intent.
- activation rules decide whether resolved entries participate.
- ordering rules constrain relative order.
- launching uses a machine-local symlinked runtime view rather than copying the game or rewriting the real install.

## Authoritative vs Non-Authoritative Specs

For pack project behavior, the primary authoritative specs are:

- [`modpack_folder_layout_spec.md`](D:\Projects\rimworld\rimpack\specs\modpack_folder_layout_spec.md)
- [`rimworld_modpack_list_format_spec.md`](D:\Projects\rimworld\rimpack\specs\rimworld_modpack_list_format_spec.md)
- [`pack_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\pack_toml_spec.md)
- [`ordering_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\ordering_toml_spec.md)
- [`activation_toml_spec.md`](D:\Projects\rimworld\rimpack\specs\activation_toml_spec.md)

[`tool_config_spec.md`](D:\Projects\rimworld\rimpack\specs\tool_config_spec.md) is also authoritative for user-local tool configuration, but it is not part of the modpack project format itself.

## Cross-Spec Rules

Keep these relationships in mind when implementing or reviewing behavior:

- `pack.toml` is the root manifest and should point to project-local files using relative paths.
- File order comes from `layout.mod_files`, not filesystem enumeration.
- `.list` files are preservation-sensitive authored text and should not be normalized wholesale.
- Activation rules and ordering rules are separate concepts and separate files.
- Tool config must not leak machine-local state into pack-authored project files.
- Runtime launch directories are machine-local per-pack state, not pack-authored project files.
- Per-pack save-data/config roots are machine-local state; only `ModsConfig.xml` is regenerated on
  each launch.

## Change Discipline

When making a change:

- update the relevant spec first or in the same change
- update tests with behavior changes
- keep generated output deterministic
- preserve authored text carefully where the spec requires it
- avoid introducing new persisted fields or format changes silently
