# VIBE HOWTO — Work Fast Without Re-reading the Tree

Purpose
- Ship features incrementally, with minimal context reload.
- Use grep-friendly region markers, a single API index, and clear responsibilities per module.
- Keep safety and error conventions explicit and consistent.

Key Ideas
- Contracts live in [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
- Every module starts with REGION blocks that act like a 10-second summary.
- Architectural decisions go in ADRs under [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md).
- Examples live at [config/zosstorage.example.yaml](../config/zosstorage.example.yaml).

Quickstart
- Build:
  - cargo build
- Inspect CLI:
  - cargo run -- --help
- Run with config and debug logs:
  - cargo run -- --config ./config/zosstorage.example.yaml --log-level debug
- Default config file location (initramfs/user space):
  - /etc/zosstorage/config.yaml (copy from [config/zosstorage.example.yaml](../config/zosstorage.example.yaml))

What the REGION markers mean
- REGION: API — one-liners for public items; grep target
- REGION: RESPONSIBILITIES — scope and non-goals
- REGION: EXTENSION_POINTS — how to extend without rewriting modules
- REGION: SAFETY — invariants; when to abort; idempotency rules
- REGION: ERROR_MAPPING — exact mapping to Error variants
- REGION: TODO — the next concrete steps to implement

Where to start (by responsibility)
- Entrypoint/binary:
  - [src/main.rs](../src/main.rs)
- CLI parsing:
  - [src/cli/args.rs](../src/cli/args.rs)
- Logging initialization:
  - [src/logging/mod.rs](../src/logging/mod.rs)
- Config load/merge/validate:
  - [src/config/loader.rs](../src/config/loader.rs)
  - [src/types.rs](../src/types.rs)
- Device discovery:
  - [src/device/discovery.rs](../src/device/discovery.rs)
- Partitioning planning/apply:
  - [src/partition/plan.rs](../src/partition/plan.rs)
- Filesystem planning/create:
  - [src/fs/plan.rs](../src/fs/plan.rs)
- Mount planning/apply + fstab:
  - [src/mount/ops.rs](../src/mount/ops.rs)
- Reporting JSON:
  - [src/report/state.rs](../src/report/state.rs)
- Orchestration:
  - [src/orchestrator/run.rs](../src/orchestrator/run.rs)
- Idempotency/emptiness probes:
  - [src/idempotency/mod.rs](../src/idempotency/mod.rs)
- External tools and shell-out:
  - [src/util/mod.rs](../src/util/mod.rs)

Daily workflow (feature implementation)
1) Find the module
   - Open the file and read the REGION header block for a 10-second overview.
   - If you don’t know where to look, grep by region:
     - grep -R "REGION: TODO" src/
     - grep -R "REGION: API" src/

2) Implement only the declared APIs first
   - Keep signatures stable (as in [docs/API-SKELETONS.md](docs/API-SKELETONS.md)).
   - Replace todo!() bodies one by one.
   - Add safety and error notes under REGION: SAFETY and REGION: ERROR_MAPPING.

3) Keep docs in sync
   - If you change a signature, update [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
   - If behavior or invariants change, update [docs/SPECS.md](docs/SPECS.md).
   - If it’s an architectural choice, add or edit an ADR under [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md).

4) Validate and build
   - cargo build
   - Use [config/zosstorage.example.yaml](../config/zosstorage.example.yaml) to drive configs.
   - For VM testing guidance see [PROMPT.md](../PROMPT.md) Testing & Validation.

Error policy (quick rules)
- Map external tool failures to Error::Tool with status and stderr (see [src/errors.rs](../src/errors.rs)).
- Validation failures should be Error::Validation with clear messages.
- Config IO/parse issues are Error::Config; reporting IO errors are Error::Report.
- Use Error::Other(anyhow) sparingly (last-resort wrapping).

Safety and idempotency rules
- Never change a disk that isn’t empty when require_empty_disks=true.
- Partitioning must guarantee GPT, 1 MiB alignment, reserved GPT names, and no preexisting signatures.
- Filesystems must use reserved labels: ZOSBOOT (ESP) and ZOSDATA (all data filesystems).
- Orchestrator must do nothing on already-provisioned systems and exit success.

Suggested first implementation tasks
- Utilities (unblocks everything else)
  - Implement which_tool, run_cmd, run_cmd_capture, udev_settle in [src/util/mod.rs](../src/util/mod.rs)
- Kernel cmdline data: URL support
  - Add base64 YAML support to config loading in [src/config/loader.rs](../src/config/loader.rs)
- Logging init
  - Implement tracing setup in [src/logging/mod.rs](../src/logging/mod.rs), idempotent setup, optional file target

VM test matrix (virtio /dev/vd?)
- 1 disk (/dev/vda):
  - single → btrfs on data, label ZOSDATA
- 2 disks (/dev/vda, /dev/vdb):
  - dual_independent → btrfs per disk (two ZOSDATA)
  - bcachefs cache/backing → /dev/vda cache (SSD-like), /dev/vdb backing (HDD-like), label ZOSDATA
  - btrfs_raid1 → mirrored btrfs across both, label ZOSDATA
- 3 disks (/dev/vda, /dev/vdb, /dev/vdc):
  - bcachefs → cache on /dev/vda; backing on /dev/vdb and /dev/vdc with two replicas; label ZOSDATA

Continuity checklist (resume after a break)
- Open the target module and read the REGION block.
- grep -R "REGION: TODO" src/ to find pending items.
- Verify the function signatures in [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
- Check recent ADRs under [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md).
- Skim [docs/SPECS.md](docs/SPECS.md) for behavior notes and in-progress sections.

Commit discipline
- Small commits per module/functionality.
- Keep REGION markers accurate (especially API and TODO).
- When changing behavior, update docs and/or ADRs in the same PR.

Reference index
- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Schema: [docs/SCHEMA.md](docs/SCHEMA.md)
- API Index: [docs/API-SKELETONS.md](docs/API-SKELETONS.md)
- Specs: [docs/SPECS.md](docs/SPECS.md)
- Dev Workflow (detailed): [docs/DEV_WORKFLOW.md](docs/DEV_WORKFLOW.md)
- ADR: [docs/adr/0001-modular-workflow.md](docs/adr/0001-modular-workflow.md)
- Example config: [config/zosstorage.example.yaml](../config/zosstorage.example.yaml)