# Atari Mutineer Sysops Guide

This guide covers installing, initializing, and operating an Atari Mutineer BBS
from an already-downloaded ATR disk image.

For file formats and current emulator settings, also see
[Data And File Formats](DATA_FORMATS.md), [Altirra 850 Modem](ALTIRRA_850_MODEM.md),
and [Troubleshooting](TROUBLESHOOTING.md).

## Install The ATR

Start with the Atari Mutineer ATR file you downloaded, for example:

```text
atari-mutineer-v<VERSION>.atr
```

Keep a clean copy of the downloaded ATR before first boot. The BBS writes live
user, message, file, and caller data to its disk, so your working copy becomes
your live board image.

### Altirra

1. Open Altirra.
2. Mount the Atari Mutineer ATR as drive `D1:`.
3. Boot the Atari with the disk mounted.
4. Let the auto-start sequence run.

If you are using a manual-start ATR, boot with the ATR mounted as `D1:` and
start it from SDX with:

```text
BASIC /I <<D1:STARUP
```

### Real Hardware

On real Atari hardware, use RespeQt, AspeQt, or another SIO disk utility to
mount the ATR as `D1:` or copy the ATR contents onto a physical floppy, hard
disk, or other Atari-compatible storage device.

For a direct SIO mount:

1. Attach your SIO2PC/SIO2USB interface.
2. Open RespeQt, AspeQt, or your preferred SIO utility.
3. Assign the Atari Mutineer ATR to drive `D1:`.
4. Boot the Atari from `D1:`.

For a physical floppy or hard-disk installation:

1. Use an Atari disk-copy utility or host-side ATR utility that can copy files
   from the ATR to the target disk.
2. Preserve the ATR's root files and directory structure.
3. Make sure the target boots the same DOS environment as the ATR.
4. Boot the Atari from the target as `D1:`.

Do not copy only the BASIC programs. The BBS also needs its DOS startup files,
MMS handler, configuration, menus, user database, message base, file base, and
door catalog files.

## Boot Flow

The auto-start ATR uses:

```text
AUTOEXEC.BAT -> RHND850.COM -> MMS.COM -> BASIC /I <<D1:AUTOGO
AUTOGO -> RUN "D1:>CORE>RUNBBS" -> APPMGR -> WFC
```

`WFC` waits for a carrier, prompts the caller to login or register, then
loads `CORE` through `APPMGR`.

The manual-start ATR loads `RHND850.COM` and `MMS.COM` only. Start the BBS with
the `STARUP` command file:

```text
BASIC /I <<D1:STARUP
```

## First User

The first registered user is user number `1` and access level `9`. Later
self-registered users are access level `1`.

Registration asks for:

- Full name.
- Handle.
- Email address.
- Password.
- Password confirmation.

Passwords are masked with `*` at the remote terminal.

## Access Levels And Time

`ACL.CFG` controls session and daily limits:

```text
# Level, sestime, daytime
0,0,0
1,30,90
2,45,120
3,60,180
4,90,300
5,120,300
6,300,600
7,300,600
8,300,600
9,999,999
```

Level `0` is banned. Level `9` is the sysop level. `WFC` uses the
RTIME8-compatible clock to apply daily/session limits.

Do not run complete initialization against a live board unless you have a
backup. It recreates live board data.

## Offline Initialization

Run `INIT` offline from the Atari console. It can recreate:

- `CONFIG` and `CALLERS.DAT`.
- `USERS.DAT`, `USERS.IDX`, and `NEXTUSER.DAT`.
- `ACL.CFG`.
- Default message base.
- Default file area.
- Default `DOORS.CFG`.

Use complete initialization only when you intend to reset the board data.

## Message Bases

Message bases use `MESG?.MET`, `MESG?.DAT`, and `MESG?.IDX`.

Caller commands are inside the message module:

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

Run `MSGMGR` offline for sysop maintenance:

- Create/update bases.
- Post/read/list messages.
- Delete/undelete messages.
- Verify indexes and pointers.
- Rebuild/compact active messages.

## File Areas

File areas use `FILE?.MET`, `FILE?.DAT`, and `FILE?.IDX`.

Caller commands are inside the file module:

- `B`, `F`, `A`, `N`: browse/list areas and files.
- `D`: download by file number or name.
- `U`: upload.
- `I`/`H`/`?`: file-area information.
- `X`: return to the main menu.

Run `FILEMGR` offline for sysop maintenance:

- Create/update areas.
- Add file records.
- Delete/undelete records.
- Verify physical file paths.
- Rebuild/compact active records.

## Doors

Door catalog rows live in `DOORS.CFG`:

```text
# #, Door Name, filename, path, level
1, Blackjack, BLKJACK, D3:>DOORS>BLKJACK>, 2
2, Dumjin, DUMJIN, D3:>DOORS>DUMJIN>, 2
3, Arena, ARENA, D3:>DOORS>ARENA>, 2
```

Door paths point to separately distributed door disks or directories. The main
BBS ATR does not need to include every door program. If a caller selects a door
whose disk/path is absent, the BBS reports `DOOR UNAVAILABLE.` and returns to
the door menu.

To install a separately distributed door package, mount or copy that door disk
to the drive/path expected by `DOORS.CFG`. For the example above, the Arena door
must be available at:

```text
D3:>DOORS>ARENA>
```

## Text Assets

Menus and static pages are included on the ATR. To customize them on a running
board, edit the live copies on your working disk image or installed Atari disk,
then back up that disk before making more changes.

Build-time text sources live in `source/textfiles/ascii/` and
`source/textfiles/atascii/`. Rebuilding an ATR stages those source files over
the packaged copies.

## Caller Command Surface

Main menu commands in `CORE`:

- `?`: display main menu.
- `B`: bulletin menu.
- `H`: help text.
- `W`: welcome text.
- `X`: toggle expert prompt mode.
- `M`: enter message area.
- `T`: display text file 1.
- `E`: leave feedback.
- `Y`: sysop yell/chat path.
- `G`: goodbye and hang up.
- `L`: toggle line-feed mode.
- `A`: toggle ASCII/ATASCII mode.
- `C`: caller list.
- `D`: door menu.
- `F`: file area.
- `I`: info text.

Message, file, and door subcommands are documented in
[Data And File Formats](DATA_FORMATS.md).

## Testing A Board

For an emulator-hosted board, connect to the modem/telnet port exposed by your
emulator. With a typical Altirra telnet setup, connect from the host with:

```sh
telnet 127.0.0.1 6507
```

Useful checks:

- Confirm `HIT <RETURN>` appears.
- Register or login.
- Confirm `Loading CORE ...` appears during module changes.
- Test `?`, `M`, `F`, `D`, `Y`, and `G`.
- Hang up and reconnect without restarting Altirra.

For automated host-side coverage, see [Testing And Evidence](TESTING_AND_EVIDENCE.md).

## Backups

Before resetting data or replacing an ATR, keep a copy of:

- User files.
- Caller history.
- Message base files.
- File area metadata.
- Door catalog.
- Customized text assets and config files.

A newly downloaded ATR contains baseline data files. Preserve live board data
separately before replacing the deployed image or reinstalling onto new media.