4. Project files

Goal: Know which files you edit, which maand generates, and where the hello job lives in the tree.

Prerequisites: Chapter 3 — The model.

Bucket layout

./                          # bucket root — run all `maand` commands here
├── maand.conf              # SSH user, key, optional env selector
├── data/maand.db           # catalog (output of build — do not edit by hand)
├── workspace/              # source of truth you edit (git)
│   ├── workers.json
│   └── jobs/hello/
│       ├── manifest.json
│       └── Makefile
├── secrets/                # SSH private key, CA, KV encryption key
├── tmp/                    # deploy staging (ephemeral)
└── logs/                   # maand command logs

Rule: if it is under workspace/, you change it and run maand build. Worker runtime dirs (data/, logs/ on the worker) are created by your Makefile, not checked into workspace.

What you edit vs what maand owns

Path	You edit?	Purpose
`workspace/`	Yes (git)	Workers, jobs, optional `disabled.json`
`maand.conf`	Yes	SSH settings, cert TTL, environment selector
`secrets/`	Carefully	Keys — usually not in git
`data/maand.db`	No	SQLite catalog from build
`tmp/`, `logs/`	No	Staging and command logs

`maand.conf` essentials

ssh_user = "agent"
ssh_key = "worker.key"
use_sudo = true

Full options: Reference: configuration.

Build vs deploy (two phases)

Build validates and records intent — no SSH to workers (except hook scripts on the CLI host).
Deploy reads the catalog and pushes to workers.

This lets you catch placement and resource errors before touching production hosts.

Optional workspace files (later)

File	Purpose
`workspace/disabled.json`	Drain nodes or jobs without deleting definitions
`workspace/bucket.conf`	Shared port pool
`workspace/bucket.jobs.conf`	Per-job CPU/memory reservations

You do not need these for the hello tutorial.

What you learned

workspace/ is what you commit; maand.db is generated by build
maand.conf and secrets/ configure SSH from the CLI host
Build is local; deploy reaches workers

Chapter 5 — Build: run build deliberately and read the catalog.