# Data And File Formats

This page documents files used by the packaged ATR and live board. Source of
truth: `tools/package_mutineer_atr.py`, `tools/build_mms_apps.py`,
`source/text/*.bas`, and `source/config/MMSAPPS.CFG`.

## ATR Directory Layout

Normal Mutineer ATR:

- Root: `AUTOEXEC.BAT`, `AUTOGO`, `RHND850.COM`, `MMS.COM`, `README`.
- `D1:>CORE>`: tokenized BASIC modules and offline tools.
- `D1:>DATA>`: runtime databases and config.
- `D1:>ASCII>`: ASCII menus/static files.
- `D1:>ATASCII>`: ATASCII menus/static files.
- `D1:>MAIL>`: default message base files.

## Configuration Files

`D1:>DATA>CONFIG` is line-oriented text:

```text
CSECT
CBYTE
CALLNO
MSECT
MBYTE
MSGS
HMSG
```

`WFC`, `CORE`, and `SYSOP` read it to track caller history pointers and message
counts. The packaged default is `657, 48, 0, 559, 21, 1, 1`.

`D1:>DATA>MSGBASE.CFG` stores the message-base root path. The packaged default
is:

```text
D1:>MAIL>
```

`D1:>DATA>ACL.CFG` is comma-separated:

```text
level,session_minutes,daily_minutes
```

Level `0` is banned. Level `9` is sysop. `WFC` applies session and daily limits
from this file during login/registration.

## Users

Files:

- `D1:>DATA>USERS.DAT`: fixed-width user records.
- `D1:>DATA>USERS.IDX`: fixed-width handle index records.
- `D1:>DATA>NEXTUSER.DAT`: next user number as text.

`USERS.DAT` records are 128 bytes:

- status byte;
- user number high/low;
- handle, 16 bytes;
- full name, 24 bytes;
- email, 40 bytes;
- password, 12 bytes;
- access level;
- flags;
- call count high/low;
- daily date, 8 bytes;
- daily used minutes high/low;
- reserved tail bytes.

`USERS.IDX` records contain normalized handle text, user number high/low,
status, and a reserved byte. Registration creates the first user as access
level `9`; later self-registered users are level `1`.

## Caller History

`D1:>DATA>CALLERS.DAT` is a text file. The packaged file starts with `*`.
`WFC` recalibrates the append pointer on startup and appends caller identity,
date, and time. `CORE` reads it for the caller-list command.

## Application Registry

Editable source: `source/config/MMSAPPS.CFG`.
Packed runtime: `D1:>DATA>MMSAPPS.DAT`.
Packager script: `tools/build_mms_apps.py`.

Source rows:

```text
handle,key,return,type,flags,access,route,term,name,path
```

Validation rules:

- up to 32 records;
- handle range `1..254`, unique;
- stable key unique, hexadecimal in the source file;
- return key must be `0000` or match another app key;
- access must be `0..9`;
- path must fit 24 bytes and match supported SDX path syntax;
- name must fit 8 bytes.

Packed format:

- header signature `MAPR`;
- version `1`;
- record size `48`;
- record count and generation byte;
- 16-bit checksum over record body;
- 48-byte records with handle/type/flags/access, key, return key, path, name,
  route, term, and reserved bytes.

## Message Bases

Default files:

- `D1:>MAIL>MESGA.MET`
- `D1:>MAIL>MESGA.DAT`
- `D1:>MAIL>MESGA.IDX`

`MESG?.MET` stores:

- version;
- base ID;
- base name;
- short name;
- required access level;
- data file path;
- index file path;
- next message number;
- active message count.

Message records include status, message number, from, to, subject, kill
password, date, time, line count, and body lines. Index records are 16 bytes and
point to message data records. `MSGMGR` creates, verifies, deletes, undeletes,
and compacts message bases.

Caller commands in `MESGAREA`:

- `Q`: quick scan.
- `S`: summary.
- `R`: read.
- `E`: enter.
- `K`: kill.
- `A` or `L`: select/list bases.
- `X`: return to main menu.

## File Areas

Default files:

- `D1:>DATA>FILEA.MET`
- `D1:>DATA>FILEA.DAT`
- `D1:>DATA>FILEA.IDX`

`FILE?.MET` stores:

- version;
- area ID;
- area name;
- view level;
- download level;
- upload level;
- data file path;
- index file path;
- upload path;
- next file number;
- active file count.

File records include status, file number, filename, description, type, location,
uploader, upload date, file size, and download count. Index records are 16 bytes
and point to file data records. `FILEMGR` creates, verifies, deletes, undeletes,
and compacts file areas.

Caller commands in `FILEBASE`:

- `B`, `F`, `A`, `N`: browse/list configured areas and files.
- `D`: download by number or name.
- `U`: upload into an area.
- `I`, `H`, `?`: file-area information.
- `L`: reports no marked files.
- `C`: clears marked files.
- `M`, `S`, `P`: currently inactive.

## Door Catalog

Live file: `D1:>DATA>DOORS.CFG`.

Rows are comma-separated:

```text
id, door name, filename, path, access level
```

The path must end in `>`. `DOORS` appends `filename` to `path` and runs the
result. Missing door programs return `DOOR UNAVAILABLE.` and leave the caller in
the door menu.

## Text Assets

Editable sources:

- `source/textfiles/ascii/`
- `source/textfiles/atascii/`

Packaged directories:

- `D1:>ASCII>`
- `D1:>ATASCII>`

Menus/static files include `MAINMNU`, `FILESMNU`, `MESGMNU`, `DOORMNU`,
`BULLMNU`, `BULL1`, `BULL2`, `BULL4`, `INFO`, `OBBS`, and `WELC`. The packager
also writes generated branded text files `HELP`, `NEWU`, and `FUNC`, and stages
`TEXTF` article files.