# MONIKA Agent Operations Guide

This guide replaces the ad-hoc tmp scripts with a single documented workflow for
running and maintaining MONIKA. It captures the canonical entry points and the
cleanup tooling that now lives in `attic_sweep.tmp.py`.

## Repository Layout (Active Paths)

- `salience_os_seed/runtime/` – core runtime, MCP bridge, orchestrator, driver.
- `salience_os_seed/proto_lm/` – Proto language model implementations and
  checkpoint management.
- `start_mcp_server.py` – CLI entry point when launching MONIKA as an MCP
  server.
- `start.standard.py` – Synthetic baseline training harness.
- `attic/` – Archived legacy scripts, manifests, and experimental checkpoints
  preserved for reference.
- `attic_sweep.tmp.py` – Single script responsible for archiving future
  temporary helpers.

## Launching the MCP Server

Start the server from the repository root. Optional `--state` and `--checkpoint`
arguments allow loading conversation state or a specific ProtoLM checkpoint.

```bash
python start_mcp_server.py [--state storage/conversation_state.json] \
    [--checkpoint storage/proto_lm/checkpoint.pt]
```

Internally this invokes `salience_os_seed.runtime.mcp_server.main`, which:

1. Parses CLI arguments.
2. Builds a `ConversationConfig` (injecting `checkpoint_path` when provided).
3. Creates a `ConversationSession` with its runtime driver.
4. Serves the MCP protocol over stdio.

### MCP Client Configuration Example

```json
{
  "mcpServers": {
    "monika": {
      "command": "python",
      "args": ["C:/MONIKA/start_mcp_server.py"]
    }
  }
}
```

## Training the Proto Language Model

Use `start.standard.py` to stream the synthetic baseline corpus into the ProtoLM.
This script ensures directories exist and defers to
`salience_os_seed.training.run_corpus` with tuned defaults.

```bash
python start.standard.py
```

Key defaults:

- Corpus: `data/local_benchmarks/synthetic_baseline_corpus.txt`
- Checkpoint output: `storage/proto_lm/synthetic_baseline.pt`
- Resumable training with shuffle buffer and patience controls.

For bespoke experiments, prefer extending the training package rather than
reinventing one-off scripts.

## Managing Checkpoints

The runtime expects the active checkpoint at `storage/proto_lm/checkpoint.pt`.
Additional historical checkpoints live in `attic/storage/`. Use the
`salience_os_seed.proto_lm.checkpoints` utilities or the training harness to
rotate checkpoints.

## Cleanup Procedure

If temporary helpers accumulate again, run the approved sweeper:

```bash
python attic_sweep.tmp.py
```

The script moves:

- Any `*.tmp.py` files (excluding itself).
- Legacy maintenance scripts listed in its `LEGACY_FILES` constant.
- Non-canonical checkpoints enumerated in `EXTRA_CHECKPOINTS`.

Artifacts retain their relative paths under `attic/` so investigations remain
possible without cluttering the working tree.

## Testing

Pytest coverage resides in `tests/`, including smoke tests for the runtime and
ProtoLM. Run them before publishing changes:

```bash
pytest
```

## Operational Checklist

1. Train or update the ProtoLM (`start.standard.py` or dedicated trainer).
2. Launch MCP server (`start_mcp_server.py`).
3. Connect via MCP-compatible client.
4. Archive experimental scripts with `attic_sweep.tmp.py` when needed.
5. Run `pytest` to ensure core invariants remain intact.

Following this playbook keeps MONIKA’s intent intact while avoiding proliferation
of undocumented maintenance scripts.