# Learnin' Man

Learnin' Man is a family-friendly browser game for exploring basic machine-learning ideas through invention. Players make a 2D contraption, connect its sensors and motors through a graphical multilayer perceptron, build a level, and watch a background PPO trainer discover a controller.

This is the portable CC0 source release. It runs entirely on the local machine, needs no account or cloud service, and does not require a GPU.

## Run it

Requirements:

- Docker Engine 24+ or Docker Desktop
- Docker Compose v2 (`docker compose`)
- Internet access for the first image build
- A current browser

From the extracted directory:

```console
docker compose up --build -d
docker compose ps
```

Open [http://localhost:8080](http://localhost:8080). The service is ready when `docker compose ps` reports `healthy`. A command-line health check is also available:

```console
curl http://localhost:8080/api/health
```

Windows PowerShell can use:

```powershell
Invoke-RestMethod http://localhost:8080/api/health
```

Stop the service without removing saved work:

```console
docker compose down
```

Do **not** add `--volumes` unless you intentionally want to delete every profile, workbench, saved Learnin' Man, World, run, and checkpoint.

## First steps in the game

1. Create a profile. Each profile owns one automatically preserved workbench draft.
2. Use **Body** to build a contraption and place sensors.
3. Use **Brain** to add dense layers or hand-wire custom neurons.
4. Use **World** and **Rewards** to make the challenge.
5. Explicitly save the Learnin' Man and World into their versioned libraries.
6. Start training, then watch Latest or saved Champion checkpoints in the Training Viewer.

Workshop draft preservation does not create library versions. Only the visible Save actions do that.

## Safety and privacy

The default Compose configuration binds only to `127.0.0.1`. Learnin' Man deliberately has profiles but **no authentication or authorization**. Do not expose it to the public internet.

To use it from other devices on a trusted household LAN, copy `.env.example` to `.env`, set `LEARNIN_MAN_BIND=0.0.0.0`, and set `LEARNIN_MAN_ORIGIN` to the URL those devices will use. Anyone who can reach that URL can view and change all family content.

Application state and rolling logs live in Docker named volumes, outside this source directory and outside the application image.

## Verify the source

Run the privacy and packaging audit:

```console
python scripts/release_audit.py
```

Build the test stage, which runs the complete Python and JavaScript suites inside the supported container environment:

```console
docker build --target test -t learnin-man:test .
```

## Documentation

- [START-HERE.md](START-HERE.md): exact handoff procedure for another technical agent
- [docs/PRODUCT-REFERENCE.md](docs/PRODUCT-REFERENCE.md): player concepts, workshops, components, sensors, motors, rewards, and training behavior
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): service boundaries, simulation sharing, persistence, versioning, and training design
- [docs/OPERATIONS.md](docs/OPERATIONS.md): configuration, storage, backups, restore, upgrades, logs, and reverse proxies
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md): symptom-oriented diagnostics
- [SECURITY.md](SECURITY.md): the trusted-household security model

## License

Project-authored material is dedicated under CC0 1.0 Universal. Third-party dependencies retain their own licenses; see [LICENSE-SCOPE.md](LICENSE-SCOPE.md) and [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).