# System Layout

Canonical home-first layout for `ballbox-first`.

## Goals

- one obvious home for each category
- optimize for agent predictability, not personal browsing
- keep canonical control/docs in `~`
- use `/mnt/rpi` only for explicitly special storage, not as the default agent plane

## Canonical roots

- control plane: `/home/sebas/pi-config`
- durable memory service: `/home/sebas/agents-database`
- runtime plane: `/home/sebas/runtime`
- work tree: `/home/sebas/work`
- user-visible outputs: `/home/sebas/outputs`
- historical material: `/home/sebas/archive`
- informal notes: `/home/sebas/notes`

## Runtime layout

```text
/home/sebas/runtime/
  pi-jobs/
  pi-loop-runs/
  agent-logs/
  logs/
  venvs/
  tmp/
```

Rules:

- `pi-job-*` runtime lives under `/home/sebas/runtime/pi-jobs`
- `pi-loop` run artifacts live under `/home/sebas/runtime/pi-loop-runs`
- growing service/app logs for agent-owned tooling live under `/home/sebas/runtime/agent-logs`
- generic local service/operator logs should prefer `/home/sebas/runtime/logs`
- durable Python environments used by local tooling should prefer `/home/sebas/runtime/venvs`
- scratch runtime state should prefer `/home/sebas/runtime/tmp`

## Work layout

```text
/home/sebas/work/
  projects/
  tools/
  admin/
  scratch/
```

Rules:

- long-lived repos and app projects go under `projects/`
- local utility code or harnesses go under `tools/`
- machine/admin helper scripts go under `admin/`
- ad hoc code snippets or one-off work files go under `scratch/`

## Outputs and archive

- user-consumed artifacts go under `/home/sebas/outputs`
- backups, handoffs, and retired trees go under `/home/sebas/archive`
- informal notes go under `/home/sebas/notes`

## Work and media

- media canon is in `~/media` and `~/Music`
- `~/media/library` is the durable media library
- `~/media/incomplete`, `~/media/downloads`, and `~/media/watch` are staging/watch-plane folders, not the canonical library
- `~/downloads` is the shared/download-served tree; current public example is `/home/sebas/downloads/mp3-share/`
- `~/Downloads` is the desktop/user inbox for manually opened or received files
- avoid duplicate category roots between `/home/sebas` and `/mnt/rpi`

## `/mnt/rpi`

`/mnt/rpi` is auxiliary storage.

Use it only when it has an explicit role such as:
- large datasets/media already tied to that volume
- cold storage or archives
- hardware-specific payloads
- other intentionally non-canonical machine storage

Do not treat `/mnt/rpi` as the default home for agent runtime or config.

## Invariants

- each category gets one canonical root
- docs must point to canonical paths only
- stale duplicate roots should be removed, not kept for compatibility
- service-owned virtualenvs should prefer `/home/sebas/runtime/venvs`