docs - leafscale/repoman

root / docs
docs Plain Text 10610 lines 382.5 KB
# RFE: public `isatty(fd: int): bool` binding

**Filer:** repoman v0.1.1 implementation
**Reef version:** 0.5.18
**Date:** 2026-05-03
**Severity:** Low — blocks one polish item; clean workaround possible by importing whole tty module if its internal C conflicts are fixed

---

## Summary

Common need: detect whether a given file descriptor (typically `STDOUT`/`STDERR`) is a terminal, to switch between interactive and non-interactive output modes. Today there is no user-callable API for this:

- `ui.backend.tty` declares `extern "C" fn reef_tty_is_tty(fd: int): int` privately and uses it internally (`if reef_tty_is_tty(STDOUT_FD) == 0`), but does not export a wrapper.
- `sys.fd` exports `STDIN()`, `STDOUT()`, `STDERR()` and various read/write/dup primitives, but no `isatty`.
- `sys.platform.libc` does not bind `isatty(3)`.

Workarounds either fail at link time (`extern "C"` declaration in user code links against an undefined symbol) or fail at compile time (importing `ui.backend.tty` pulls in conflicting `extern int write(int fd, char* buf, int count);` that clashes with the runtime's own `write` declaration).

## Use case

repoman v0.1.1 task A2 (TTY detection for rsync progress): when stdout is a terminal, repoman wants to pass `--info=stats2,progress2` to rsync (live progress); otherwise `--info=stats2` (cron-friendly). Currently hardcoded `is_tty: bool = false` for cron compatibility; missing the live-progress UX in interactive use.

This is a generic CLI need — any tool that wants to render progress bars, ANSI colors, or interactive prompts needs to detect TTY context.

## Proposed API

Either of:

```reef
// In sys.fd:
fn isatty(fd: int): bool

// Or in ui.backend.tty (publicly exported):
fn is_tty(fd: int): bool
```

Trivial wrapper:
```reef
fn isatty(fd: int): bool
    return reef_tty_is_tty(fd) == 1
end isatty
```

`sys.fd` feels more correct since `isatty(3)` is a POSIX file-descriptor primitive, but `ui.backend.tty` is also reasonable since the implementation already lives there. Either works.

## Side issue

If `ui.backend.tty` becomes the home, the existing `extern int write(int fd, char* buf, int count);` declaration inside that module needs to be removed or replaced — it conflicts with the runtime's own `write` declaration, which makes importing `ui.backend.tty` from a user program fail to compile (`error: conflicting types for 'write'`). If the goal is for user code to be able to import `ui.backend.tty` cleanly, that needs fixing regardless.

## Repoman impact

A2 in our v0.1.1 polish list is parked until this lands. Trivial to wire in once the API exists (one-line replacement in `cli.cmd_sync`).

---

*Filed by the repoman v0.1.1 build flow.*
# Response: repoman v0.1 Feedback

**Source feedback:** `bugs/reef-feedback.md`
**Reef version evaluated:** 0.5.9
**Response date:** 2026-04-28
**Status:** All 8 items accepted — implementation plan in `bugs/reef-feedback-implementation-plan.md`

---

## Summary

Thank you for the thorough, well-prioritized feedback. Each item is a real friction point and the proposed API shapes are largely on the mark. We accepted all 8 items; no rejections.

Two corrections worth flagging up front:
- **Item 6 is partially out of date.** `assert_true`, `assert_false`, `assert_not_eq_int`, `assert_not_eq_bool`, and `assert_not_eq_string` already exist on `TestRunner` in v0.5.9. Genuinely missing: `assert_contains` and Result-aware assertions (`assert_ok_*` / `assert_err_*`). We'll add those.
- **Item 4 sketch references `str.substring_from` — that function does not exist.** The correct call in v0.5.9 is `str.substring(s, start, len)`. The implementation will use the real function; just flagging in case repoman has the workaround coded against a placeholder name.

The rest is accurate as filed.

---

## Item-by-item disposition

### 1. TOML/JSON encoders missing — **HIGH** — accepted

Going with the **builder API** (your option b), not the flat `toml_serialize(keys, values, count)`. Reason: the parser's parallel-array representation cannot losslessly round-trip `[[project]]` table-arrays — table-array indices are encoded into key names as a parser-internal detail, not a public contract. A flat serialize would be ambiguous on round-trip.

The builder will be a plain `struct` (not an Active Object — no message-passing overhead needed for single-threaded doc building), modeled on `text.stringbuilder`. JSON gets a parallel `JsonBuilder` with the same surface plus `begin/end_object` / `begin/end_array` for JSON's mandatory structural nesting.

YAML and INI extensions are out of scope for this batch — repoman doesn't need them, and YAML's nested-table indentation is non-trivial.

**Scope:** medium (2-3 days). Sprint 4.

### 2. `io.file` missing rename and fsync — **HIGH** — accepted

Both will be added to `io.file`. `rename` becomes a thin Reef wrapper delegating to the existing `runtime.reef_fs_rename` (same C function `fs.ops.rename` already calls — keeping `fs.ops.rename` in place because the modules have different audiences; doc cross-references on both will resolve the discoverability concern).

`fsync` requires a small C runtime addition (`reef_fs_fsync(path)` in `reef_fs.c`) plus the FFI bridge plus the user-facing wrapper. Path-based, not handle-based — `io.file` has no handle type today and adding one would be a much larger redesign. The path-based fsync does an extra `open`/`close`, but for the atomic-write recipe that's nanoseconds; the actual disk flush dominates.

**Scope:** small. Sprint 2.

### 3. No generic `Result[T, E]` — **MEDIUM** — accepted

Will create `core/result_generic.reef` mirroring `core/option_generic.reef` exactly. Five functions: `is_ok[T,E]`, `is_err[T,E]`, `unwrap_ok[T,E]`, `unwrap_err[T,E]`, `unwrap_or[T,E]`. The existing `core.result` (type-specific monomorphizations) stays untouched for one release; deprecation notice and stdlib internal migration follow in a later release.

**One thing to validate first:** that two-parameter generic enums (`enum Ok(T); Err(E)`) compile cleanly. `option_generic.reef` proves single-param works; we'll smoke-test the two-param case before writing function bodies. If we hit a compiler limit, fallback is `Result[T]` with `E` fixed to `string` — still satisfies the use case you described.

The syntax reference's "Future stdlib" note about generic Result will be updated to "Available in `core.result_generic`" once shipped.

**Scope:** small. Sprint 3.

### 4. `io.path.expand_home` missing — **MEDIUM** — accepted

Pure-Reef addition to `io.path`. Behavior: `~` → `$HOME`, `~/foo` → `$HOME/foo`, anything else → passthrough. If `HOME` is unset, returns the path unchanged (substituting empty would silently corrupt `~/foo` to `/foo`).

`expand_user("~user/...")` is **deferred** to a separate item — it requires a new C runtime helper (`getpwnam` resolution) and adds a `getpwnam_r` thread-safety footnote. Your feedback rated it as a "maybe" and we'd rather ship `expand_home` quickly than couple them. The current `expand_home` returns unchanged on `~user` form so adding `expand_user` later won't break anything.

**Scope:** small. Sprint 1.

### 5. `sys.flag` no subcommand dispatch — **MEDIUM** — accepted in two phases

**Phase 1 (Sprint 2):** `flag_parser_from(args: [string]): FlagParser` — caller slices argv and feeds it in. `parse()` reads from the override array when set, otherwise calls `sys.args` as today. Backward-compatible.

**Phase 2 (Sprint 4):** Full `subcommand_parser` API matching cobra/clap conventions. Has open design questions worth resolving with you before implementation:
- Should subcommand flags be defined before `dispatch` (each subcommand pre-registered with its own parser) or after (cobra-style, parser handed back from dispatch)?
- How do global flags (e.g., `--verbose` before the subcommand token) coexist with per-subcommand flags?
- Does `dispatch` intercept `--help` and route to subcommand-specific usage, or is that the caller's job?

We'll spec Phase 2 against repoman's actual subcommand structure once you reach that part of the build. Phase 1 unblocks you immediately.

**Scope:** Phase 1 small (~1 day), Phase 2 medium (2-3 days after design pass).

### 6. `test.framework` thin assertions — **MEDIUM** — accepted (with correction)

**Already in v0.5.9** (you may have been reading older docs):
- `assert_true(condition, message)` — line 130
- `assert_false(condition, message)` — line 135
- `assert_not_eq_int/bool/string` — lines 178-201

**Genuinely missing, will add (Sprint 1):**
- `assert_contains_string(haystack, needle, message)` — substring; uses existing `str.contains`
- `assert_ok_int/str/bool` — pass when `Result*_Ok(_)`, fail with diagnostic showing the wrapped error
- `assert_err_int/str/bool` — pass when `Result*_Err(_)`

Skipping `ResultFloat` variants for now (rare in error paths; add on demand). Skipping array-membership `assert_contains` until generic Result lands — a typed-array version per element type would be 4-5 procs and isn't worth it before generics. The string substring form covers your actual use case.

A `test_framework.reef` test file (which currently doesn't exist) will be created alongside.

**Scope:** small. Sprint 1.

### 7. TOML parser quirks — **LOW** — accepted in two phases

**Phase 1 (Sprint 1) — silent truncation:** new `toml_parse_status(input, keys, values, max_capacity): int` returning `-1` when input remains unconsumed AND the cap was hit. Existing `toml_parse` and `toml_parse_sized` are untouched (zero breakage). Module docstring will be updated to recommend `toml_parse_status` for production callers.

`json_parse` has the **identical silent-truncation flaw** at a 512-entry cap — we'll mirror the fix as `json_parse_status` in the same release, given the symmetry.

**Phase 2 (Sprint 3) — `TomlDoc` struct:** new ergonomic API replacing the parallel-array threading. Adds `TomlDoc` struct + `toml_parse_doc()` + 4 wrapper getters (`toml_get_doc`, `toml_get_int_doc`, `toml_get_bool_doc`, `toml_has_key_doc`). Coexists with old API for ≥1 release.

**Scope:** Phase 1 small, Phase 2 small-medium.

### 8. `join_path` naming — **LOW** — accepted (bundled)

Adding `fn join(a, b)` as the canonical export, leaving `join_path` as a silent synonym. No deprecation ceremony — Reef has no precedent for one in the stdlib (verified by grep through CHANGELOG; all prior changes were additions or fixes, never renames). A docstring line on `join_path` notes that `join` is preferred.

This is the only `<verb>_path` redundancy in `io.path` — `dirname`/`basename`/`extension` etc. don't repeat the module name. No coordinated naming pass needed elsewhere.

**Scope:** ~15 minutes. Bundled with item 4 in Sprint 1.

---

## Sprint plan summary

Detailed plan in `bugs/reef-feedback-implementation-plan.md`. Top-line sequencing:

| Sprint | Items | Est. effort | Outcome |
|---|---|---|---|
| 1 | 4, 6, 7a, 8 (+JSON mirror) | ~1.5 days | Quick wins; unblocks ~half the friction points |
| 2 | 2, 5a | ~2 days | Runtime additions; subcommand-friendly parser |
| 3 | 3, 7b | ~1.5 days | Generic Result + ergonomic TomlDoc |
| 4 | 1, 5b | ~5 days | Encoders + full subcommand API |

**Defer indefinitely:** `expand_user` (item 4 follow-on, requires runtime work and only a "maybe" in the feedback).

---

## What you can do today

While we land Sprint 1, you can unblock these items in repoman with minimal hand-rolled glue:

- **`expand_home`** — your sketched workaround works; just substitute `str.substring(p, 2, str.length(p) - 2)` for the non-existent `substring_from`.
- **`assert_contains`** — `runner.assert_eq_bool(str.contains(haystack, needle), true, message)` works as a stopgap.
- **Atomic write** — without `fsync`, the write→rename sequence still gives crash-consistency in the common case (just not power-loss durability). Acceptable for v0.1.
- **TOML truncation detection** — call `toml_parse_sized(input, keys, values, max_entries)` with your own cap and assert the returned count is less than the cap — if equal, you may be truncated.
- **Subcommand dispatch** — hand-roll using `sys.args.get_args()` to extract argv[1] as the subcommand, then call `flag_parser()` with a different program name per subcommand. Migrate to `flag_parser_from(slice)` once Sprint 2 ships.

---

## Test plan summary

Each sprint will add tests; the matrix below shows what coverage lands per item:

| Item | Test file | Cases |
|---|---|---|
| 4 | `tests/integration/test_path_expand_home.reef` | bare `~`, `~/foo`, `/abs`, `relative`, empty, `~~double`, `HOME` unset |
| 8 | (same as above) | `path.join(a, b)` produces same result as `path.join_path(a, b)` |
| 6 | `reef-stdlib/test/test_framework.reef` (new) | pass + fail paths for every new assertion, verify diagnostic format |
| 7a | `reef-stdlib/encoding/toml_test.reef` (new) | exact-cap parse returns count (not `-1`), over-cap returns `-1`, under-cap returns count |
| 2 | extends `examples/test_file_io.reef` | rename existence check, atomic-write recipe (write→fsync→rename) |
| 5a | new `tests/integration/test_flag_subcommand.reef` | flat parse unchanged, sliced parse, `tool sub --flag` end-to-end |
| 3 | new `tests/result_generic_test.reef` | `Result[int,string]`, `Result[Point,string]` (struct payload — exercises BUG-034 territory) |
| 7b | extends `toml_test.reef` | `TomlDoc` round-trip, `truncated` flag |
| 1 | new `tests/encoding_toml_writer_test.reef`, `encoding_json_writer_test.reef` | round-trip parse→serialize→parse for all supported types incl. `[[project]]` |
| 5b | extends `test_flag_subcommand.reef` | full `tool sub --flag` end-to-end via `subcommand_parser` |

---

## Open questions for repoman team

1. **Subcommand structure (item 5b):** what does repoman's actual subcommand layout look like? Knowing whether you need global flags before the subcommand token, and whether subcommands can have sub-subcommands (`tool group sub --flag`), shapes the Phase 2 design.
2. **Result error type (item 3):** if generic `Result[T, E]` two-param form hits a compiler limit, are you okay with `Result[T]` where `E = string`? Your feedback example used `string` errors throughout, so this should be a no-op.
3. **Encoder priority (item 1):** TOML or JSON first? You're using both per the feedback, but if one unblocks more of repoman's surface, we'll lead with that.

---

*Reef team — Chris Tusal*
# reef-lang Feedback — Surfaced While Planning repoman v0.1

**Source:** Spec'ing `repoman` (a real Linux CLI tool: Incus container management + rsync/NFS backup) against reef-lang 0.5.9 stdlib. Items below are gaps and quirks discovered while mapping the spec onto actual stdlib APIs. None are blockers — repoman v0.1 will work around them — but each is a friction point a future user will hit when writing a real production reef program.

---

## 1. Encoders missing for structured formats — **highest impact**

Every config-driven program eventually needs to **write** its config, not just read it. Today:

| Module | Reads | Writes |
|---|---|---|
| `encoding.toml` | yes (`toml_parse`, `toml_get*`, `toml_array_*`) | **no** |
| `encoding.json` | yes (`json_parse`, `json_get*`) | **no** |
| `encoding.yaml` | yes | only line-at-a-time `yaml_encode_string/int/bool` — no nested tables, no lists |
| `encoding.ini` | yes (line helpers) | **no** |
| `encoding.csv` | TBD | TBD |

**What repoman needs:** a `toml_serialize(...)` (or equivalent for one of the structured formats) that handles strings, ints, bools, string arrays, tables, and table-arrays (`[[project]]`).

**Suggested API shape** (TOML; same idea for JSON):
```
fn toml_serialize(keys: [string], values: [string], count: int): string
// or a higher-level builder:
type TomlBuilder
fn toml_builder(): TomlBuilder
proc toml_set_string(b: TomlBuilder, key: string, val: string)
proc toml_set_int(b: TomlBuilder, key: string, val: int)
proc toml_set_bool(b: TomlBuilder, key: string, val: bool)
proc toml_set_string_array(b: TomlBuilder, key: string, vals: [string])
proc toml_array_append_table(b: TomlBuilder, name: string)  // for [[project]]
fn toml_render(b: TomlBuilder): string
```

Parser/serializer asymmetry is the single biggest gap stdlib has for "write a real config-driven program."

## 2. `io.file` is missing rename and fsync

`io.file` exposes `readFile`, `writeFile`, `appendFile`, `deleteFile`, `fileExists`, `fileSize`, plus binary versions. **Missing:**
- `rename(old, new)` — `fs.ops.rename` exists, so this is just a discoverability issue (people will look in `io.file` first).
- `fsync(path)` — there is **no** way to force a file's contents to disk before a rename. Important for the standard atomic-write recipe (write tmp → fsync → rename). Today repoman has to skip the fsync and accept a brief power-loss inconsistency window.

**Suggested:** add `fn fsync(path: string): bool` (or expose a file-handle-based API, then add `flush_to_disk(handle)`).

## 3. No generic `Result[T, E]`

`core.result` only exports concrete `ResultInt`, `ResultStr`, `ResultBool`, `ResultFloat`. For functions that return structs (e.g., `load_registry() : Result<Registry, string>`), every caller has to define a local enum:
```reef
type RegistryLoad = enum
    Ok(Registry)
    Err(string)
end RegistryLoad
```

`core.option_generic` already provides `Option[T]` — the same pattern would be a clean fit for `Result[T, E]`. The existing concrete `ResultInt`/`ResultStr`/etc. could be deprecated aliases or stay as ergonomic shortcuts.

**Suggested:** add `core.result_generic` with `Result[T, E]`, `is_ok[T,E]`, `is_err[T,E]`, `unwrap_ok[T,E]`, `unwrap_err[T,E]`.

## 4. `io.path` is missing `expand_home`

`~/foo` expansion is one of the most frequent path operations in any user-facing CLI. Today `io.path` has `join_path`, `dirname`, `basename`, `extension`, `normalize`, `is_absolute` — but no `expand_home` or `expand_user`. Every caller writes (corrected from v1: `str.substring_from` does not exist publicly; the real call is `str.substring(s, start, len)`):
```reef
fn expand_home(p: string): string
    if str.starts_with(p, "~/")
        let len = str.length(p)
        return path.join_path(env.get_env_or("HOME", ""), str.substring(p, 2, len - 2))
    end if
    return p
end expand_home
```

**Suggested:** `fn expand_home(path: string): string` (and maybe `expand_user(path)` for `~user/...`) in `io.path`.

## 5. `sys.flag` doesn't support subcommand dispatch

`sys.flag` is a V-style **flat** flag parser. It calls `sys.args` directly inside `parse()` — there's no way to feed it a subcommand-sliced argv. The common CLI shape `tool <subcommand> [subcommand-flags]` (git, kubectl, incus, podman, repoman) requires a hand-rolled outer parser to extract the subcommand, then either a hand-rolled per-subcommand parser or a way to give `sys.flag` a sub-slice of argv.

**Suggested:** either
- (a) `flag_parser_from(args: [string]): FlagParser` so callers can pass a sliced argv, or
- (b) a `subcommand_parser` API at the same level as `flag_parser` that handles the dispatch.

Even a doc note ("for subcommand tools, hand-roll using `sys.args.get(i)`") would help — today the example in `sys/flag.reef` makes it look like the answer.

## 6. `test.framework` thin assertion surface

`TestRunner` (an active object — nice) already has `assert_eq_int/bool/string/float`, and **as of v0.5.9 also has** `assert_true`, `assert_false`, and `assert_not_eq_int/bool/string` (filer error in v1 of this report — caught reading only the first 100 lines of a 235-line file). **Genuinely missing:**
- `assert_contains(haystack, needle, message)` for substring/array membership.
- `assert_ok_*` / `assert_err_*` for Result types (uses pattern-match plus a diagnostic that surfaces the wrapped error/value on failure).

## 7. TOML parser quirks

- **Hard 1024-entry cap** in `toml_alloc_keys()`. Adequate for repoman (~127 projects max), but the cap is invisible — `toml_parse` returns the entry count it processed; if the file had more, callers don't know. Suggest a return value indicating "truncated" (or accept a max-entries arg and error if exceeded — the `_sized` variants already do the latter, so making them the recommended path would help).
- **Parallel-array repr** (`[string] keys`, `[string] values`, `int count`) forces every caller to thread three values around. A small `TomlDoc` struct (or `[Pair]` array) would be friendlier — the runtime cost is the same but the API surface is much smaller.

## 8. Naming nit

`io.path.join_path(a, b)` — the `_path` suffix is redundant since the function is in `io.path`. Most languages call this `path.join`. Minor, but discoverability matters when learning a new stdlib.

---

## Summary table (ordered by impact on real-world reef programs)

| # | Item | Severity | Type |
|---|---|---|---|
| 1 | TOML/JSON encoders missing | **High** | Feature gap |
| 2 | `io.file` no rename/fsync | High | Feature gap |
| 3 | No generic `Result[T,E]` | Medium | API design |
| 4 | `io.path.expand_home` missing | Medium | Feature gap |
| 5 | `sys.flag` no subcommand support | Medium | API design |
| 6 | `test.framework` thin assertions | Medium | Feature gap |
| 7 | TOML parser caps & repr | Low | API design |
| 8 | `join_path` naming | Low | Naming |

repoman v0.1 works around all of these and ships. But every one of them costs the project some hand-rolled glue code that *should* be in stdlib.
# repoman v0.1 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship a reef-lang implementation of `repoman new <name>` and `repoman sync [name]` with feature parity to the bash prototype at `~/.local/bin/repoman`, plus the v0.1-only differentiator: containers live under an Incus `project` namespace.

**Architecture:** Six modules under `src/`, no nesting: `main` (entry), `cli` (subcommand dispatch + flag parsing), `config` (TOML-backed registry + per-project overrides), `incus` (subprocess wrappers around the `incus` CLI), `sync` (NFS mount check + rsync invocation), `paths` (path helpers — pluralized to avoid colliding with stdlib's `io.path`). Pure logic lives in `config.merge_with_defaults`, `sync.build_rsync_args`, `incus.validate_name`, `paths.expand_home` — these get full unit-test coverage. Effectful wrappers (subprocess, file I/O, NFS check) are kept narrow and smoke-tested manually.

**Tech Stack:** reef-lang 0.5.10 (compiles to C → native binary), `encoding.toml` (TomlBuilder + TomlDoc), `core.result_generic` (`Result[T, string]` for errors), `sys.process.process_spawn` (argv-list subprocess — never the shell variant), `sys.flag.flag_parser_from` (sliced argv per subcommand), `test.framework.TestRunner` (active object with `assert_eq_*`, `assert_contains_string`).

---

## Reference: spec and source

- Design spec: `docs/superpowers/specs/2026-04-29-repoman-v0.1-design.md` (rev 3, locked)
- Bash prototype: `~/.local/bin/repoman` (behavioral source of truth for `new`/`sync`)
- Reef stdlib reference: `~/reef-lang-0.5.10-source/reef-stdlib/`
  - `test/framework.reef` — TestRunner API (note: `new framework.TestRunner()`, not `new TestRunner()`)
  - `encoding/toml.reef` — `toml_builder()`, `toml_set_*`, `toml_array_append_table`, `toml_render`, `toml_parse_doc`, `TomlDoc`
  - `io/path.reef` — `expand_home`, `join`, `dirname`, `basename`
  - `io/file.reef` — `readFile`, `writeFile`, `fileExists`, `rename`, `fsync`, `deleteFile`
  - `io/dir.reef` — `dir_exists`, `is_directory`, `create_dir_all`
  - `sys/flag.reef` — `flag_parser_from(args)`, `bool_flag`, `string_flag`, `parse`, `positional_args`
  - `sys/process.reef` — `process_spawn(prog, [args])`, `process_wait(pid)`, `process_exit_code()`
  - `sys/args.reef` — `count()`, `get(i)`, `program()`
  - `sys/env.reef` — `get_env(name)`, `get_env_or(name, default)`
  - `core/result_generic.reef` — `Result[T, E]`, construction `@Result[T, E].Ok(v)` / `@Result[T, E].Err(e)`, queries `is_ok(r)`, `is_err(r)`, `unwrap_ok(r)`, `unwrap_err(r)`
  - `core/str.reef` — `length`, `equals`, `contains`, `starts_with`, `ends_with`, `substring`, `split`, `join`

## File structure

```
~/repos/repoman/
├── reef.toml              # package manifest
├── Makefile               # install/uninstall wrapper for distro packagers
├── README.md              # quickstart + test loop + smoke recipe
├── VISION.md              # (already exists) design intent
├── .hgignore              # (already exists) build/, *.o, etc.
├── docs/                  # (already exists) specs + reef feedback
├── src/
│   ├── main.reef          # proc main() → cli.dispatch + exit
│   ├── cli.reef           # outer dispatch on argv[1]; per-subcommand parsers
│   ├── config.reef        # types + parse + serialize + load_or_init + atomic save
│   ├── incus.reef         # subprocess wrappers + validate_name (pure)
│   ├── sync.reef          # ensure_nfs_mounted + build_rsync_args (pure) + run
│   └── path.reef          # expand_home, join, exists, is_dir wrappers
└── tests/
    ├── test_path.reef
    ├── test_incus_validate.reef
    ├── test_config_parse.reef
    ├── test_config_serialize.reef
    ├── test_config_roundtrip.reef
    ├── test_config_merge.reef
    ├── test_sync_args.reef
    ├── test_config_io.reef         # uses temp dir
    └── test_config_save.reef       # uses temp dir
```

Module boundary rules:
- Each module file declares `module <name>` matching its filename.
- `main.reef` has no `module` declaration; it's the entry point.
- Tests are standalone reef programs (each has its own `proc main()`); they import production modules from `src/` (resolved automatically when run from project root).
- All `module <name>` blocks must end with `end module`.

---

## Task 1: Scaffold project

**Files:**
- Create: `reef.toml`, `src/main.reef`, `tests/.keep`
- Modify: `.hgignore` (add reef build artifacts)

- [ ] **Step 1: Initialize reef project in existing repo**

The repoman directory already exists with `VISION.md` and `docs/`. Run `reefc init` to add a `reef.toml` without disturbing existing files:

```bash
cd ~/repos/repoman
reefc init
```

Expected stdout: `Initialized Reef project in current directory` and `Created reef.toml`.

- [ ] **Step 2: Replace generated reef.toml with the repoman manifest**

The default `reef.toml` from `reefc init` is generic. Overwrite with this exact content:

```toml
[package]
name = "repoman"
version = "0.1.0"
author = "Chris Tusa <chris.tusa@leafscale.com>"
description = "Per-project Incus containers + opinionated NFS/ZFS backup"
license = "MIT"
url = ""

[build]
entry = "src/main.reef"
output = "repoman"
output_dir = "build"
source_dirs = ["src"]

[docs]
output = "docs/api"
include_private = false
```

Note: `tests/` is intentionally NOT in `source_dirs` — tests are standalone programs run via `reefc run tests/test_*.reef`, not bundled into the production binary.

- [ ] **Step 3: Create src/ and tests/ directories with placeholder main**

```bash
mkdir -p src tests
```

Create `src/main.reef` with this exact content (it will be replaced in Task 19, but we want a buildable skeleton now):

```reef
proc main()
    println("repoman 0.1.0 — not yet implemented")
end main
```

Create `tests/.keep` (empty file) so the directory is committed:

```bash
touch tests/.keep
```

- [ ] **Step 4: Update .hgignore for reef build artifacts**

Append to `.hgignore`:

```
build/
*.c
*.o
*.so
*.exe
docs/api/
```

(The `docs/api/` line covers reef's generated API docs.)

- [ ] **Step 5: Build and verify the skeleton runs**

Run from `~/repos/repoman/`:

```bash
reefc build
./build/repoman
```

Expected output: `repoman 0.1.0 — not yet implemented`. Build directory should appear at `~/repos/repoman/build/` and contain `repoman`.

- [ ] **Step 6: Commit**

```bash
hg add reef.toml src/main.reef tests/.keep
hg commit -m "scaffold: reef project skeleton + manifest"
```

---

## Task 2: paths module (`expand_home`, `join`, `exists`, `is_dir`)

> **Naming note:** the local module is named `paths` (plural), not `path`. Bare `path` collides with the stdlib's `io.path` and reef resolves to the stdlib module first, producing C-codegen errors at link time. Pluralizing avoids the collision; `paths.X` reads naturally at call sites.

**Files:**
- Create: `src/paths.reef`
- Test: `tests/test_paths.reef`

The `path` module is a thin facade over `io.path` and `io.dir`, named to keep call sites short. `expand_home` and `join` are direct re-exports of stdlib; `exists` and `is_dir` wrap `io.dir`. We test the re-exports too — they're trivial but anchor the test framework + module-import chain end-to-end before we write more.

- [ ] **Step 1: Write the failing test**

Create `tests/test_paths.reef`:

```reef
import paths
import test.framework
import sys.env

proc main()
    let runner = new framework.TestRunner()

    // expand_home
    env.set_env("HOME", "/home/test")
    runner.assert_eq_string(paths.expand_home("~/foo"), "/home/test/foo", "~/foo expands")
    runner.assert_eq_string(paths.expand_home("~"), "/home/test", "bare ~ expands")
    runner.assert_eq_string(paths.expand_home("/abs/path"), "/abs/path", "abs path passthrough")
    runner.assert_eq_string(paths.expand_home("relative"), "relative", "relative passthrough")
    runner.assert_eq_string(paths.expand_home(""), "", "empty passthrough")

    // join
    runner.assert_eq_string(paths.join("/a", "b"), "/a/b", "join basic")
    runner.assert_eq_string(paths.join("/a/", "b"), "/a/b", "join trailing slash")
    runner.assert_eq_string(paths.join("/a", "/b"), "/a/b", "join leading slash")

    // exists / is_dir against a known dir
    runner.assert_eq_bool(paths.exists("/tmp"), true, "/tmp exists")
    runner.assert_eq_bool(paths.is_dir("/tmp"), true, "/tmp is dir")
    runner.assert_eq_bool(paths.exists("/this-does-not-exist-zzz"), false, "missing path → false")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_paths.reef
```

Expected: compile error (module `path` not found).

- [ ] **Step 3: Write minimal implementation**

Create `src/paths.reef`:

```reef
module paths

import io.path as iopath
import io.dir as iodir
import io.file as iofile

export
    fn expand_home(p: string): string
    fn join(a: string, b: string): string
    fn exists(p: string): bool
    fn is_dir(p: string): bool
end export

fn expand_home(p: string): string
    return iopaths.expand_home(p)
end expand_home

fn join(a: string, b: string): string
    return iopaths.join(a, b)
end join

fn exists(p: string): bool
    if iofile.fileExists(p)
        return true
    end if
    return iodir.dir_exists(p)
end exists

fn is_dir(p: string): bool
    return iodir.is_directory(p)
end is_dir

end module
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_paths.reef
```

Expected: `Tests passed: 9`, `Tests failed: 0`, `All tests passed!`.

- [ ] **Step 5: Commit**

```bash
hg add src/paths.reef tests/test_paths.reef
hg commit -m "path: expand_home/join/exists/is_dir wrappers + tests"
```

---

## Task 3: incus.validate_name

**Files:**
- Create: `src/incus.reef`
- Test: `tests/test_incus_validate.reef`

`validate_name` is the pure half of the `incus` module. Container names follow Incus rules: lowercase alphanumeric + hyphens, must not start with a hyphen, ≤63 chars, must be non-empty. We populate the rest of the module (subprocess wrappers) in Task 13.

- [ ] **Step 1: Write the failing test**

Create `tests/test_incus_validate.reef`:

```reef
import incus
import test.framework

proc main()
    let runner = new framework.TestRunner()

    runner.assert_eq_bool(incus.validate_name("foo"), true, "simple name")
    runner.assert_eq_bool(incus.validate_name("foo-bar"), true, "hyphenated")
    runner.assert_eq_bool(incus.validate_name("foo123"), true, "trailing digits")
    runner.assert_eq_bool(incus.validate_name("a"), true, "single char")

    runner.assert_eq_bool(incus.validate_name(""), false, "empty rejected")
    runner.assert_eq_bool(incus.validate_name("-foo"), false, "leading hyphen rejected")
    runner.assert_eq_bool(incus.validate_name("foo_bar"), false, "underscore rejected")
    runner.assert_eq_bool(incus.validate_name("foo.bar"), false, "dot rejected")
    runner.assert_eq_bool(incus.validate_name("Foo"), false, "uppercase rejected")
    runner.assert_eq_bool(incus.validate_name("foo bar"), false, "space rejected")

    // 63-char boundary (exactly 63 = ok, 64 = reject)
    let s63 = "abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabc"
    let s64 = "abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcd"
    runner.assert_eq_int(str.length(s63), 63, "s63 setup check")
    runner.assert_eq_int(str.length(s64), 64, "s64 setup check")
    runner.assert_eq_bool(incus.validate_name(s63), true, "63 chars accepted")
    runner.assert_eq_bool(incus.validate_name(s64), false, "64 chars rejected")

    runner.report()
end main
```

Note: this test imports `core.str` implicitly via `str.length` — add `import core.str` at the top:

```reef
import incus
import test.framework
import core.str
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_incus_validate.reef
```

Expected: compile error (module `incus` not found).

- [ ] **Step 3: Write minimal implementation**

Create `src/incus.reef`:

```reef
module incus

import core.str

export
    fn validate_name(name: string): bool
end export

fn is_lower_alnum_or_hyphen(c: char): bool
    if c >= 'a' and c <= 'z'
        return true
    end if
    if c >= '0' and c <= '9'
        return true
    end if
    if c == '-'
        return true
    end if
    return false
end is_lower_alnum_or_hyphen

fn validate_name(name: string): bool
    let n: int = str.length(name)
    if n == 0
        return false
    end if
    if n > 63
        return false
    end if
    if name[0] == '-'
        return false
    end if
    mut i: int = 0
    while i < n
        if not is_lower_alnum_or_hyphen(name[i])
            return false
        end if
        i = i + 1
    end while
    return true
end validate_name

end module
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_incus_validate.reef
```

Expected: all 14 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add src/incus.reef tests/test_incus_validate.reef
hg commit -m "incus: validate_name + boundary tests"
```

---

## Task 4: config types

**Files:**
- Create: `src/config.reef` (skeleton with type definitions only)

This task lays down the data types that subsequent tasks will populate. No functions yet — just the structs. We don't write a test for type definitions; the next task's test will exercise them.

- [ ] **Step 1: Create the config module skeleton**

Create `src/config.reef`:

```reef
module config

import core.str
import core.result_generic as rg
import encoding.toml as toml
import io.file as iofile
import io.dir as iodir
import io.path as iopath
import paths

export
    type Defaults
    type Project
    type Override
    type Mount
    type Registry
    type EffectiveConfig
end export

type Defaults = struct
    repos_root: string
    backup_root: string
    incus_project: string
    default_image: string
    profiles: [string]
end Defaults

type Project = struct
    name: string
    repo: string
    image: string
    profiles: [string]
    created: string
    last_sync: string
    backup: bool
end Project

type Mount = struct
    source: string
    path: string
end Mount

type Override = struct
    image: string
    profiles: [string]
    has_profiles: bool
    mounts: [Mount]
    env_keys: [string]
    env_values: [string]
end Override

type Registry = struct
    schema: int
    defaults: Defaults
    projects: [Project]
end Registry

type EffectiveConfig = struct
    name: string
    repo: string
    repo_path: string
    image: string
    profiles: [string]
    mounts: [Mount]
    env_keys: [string]
    env_values: [string]
end EffectiveConfig

end module
```

Notes on the Override shape:
- `has_profiles` distinguishes "user authored an empty profiles list" from "user didn't author profiles" (the merge in Task 8 needs this to decide whether override replaces defaults).
- `env_keys` / `env_values` are parallel arrays. Reef doesn't have a native dict; this matches how TomlDoc surfaces parsed key-value entries.

- [ ] **Step 2: Verify it compiles**

```bash
reefc --check src/config.reef
```

Expected: no errors. (`--check` is reefc's type-check-only mode, useful for module-level smoke checks before there's a `proc main()`.)

If `--check` doesn't accept module files standalone, a quick alternative: run `reefc build` and confirm it still produces `build/repoman`. The new module is unused but should compile cleanly.

- [ ] **Step 3: Commit**

```bash
hg add src/config.reef
hg commit -m "config: type skeleton (Registry/Defaults/Project/Override/EffectiveConfig)"
```

---

## Task 5: config.parse_registry

**Files:**
- Modify: `src/config.reef` (add `parse_registry` function + helpers)
- Create: `tests/test_config_parse.reef`

Parses a TOML string into a `Registry`. Uses the new `TomlDoc` API from 0.5.10 — much cleaner than threading `(keys, values, count)`. Returns `Result[Registry, string]`.

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_parse.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

proc main()
    let runner = new framework.TestRunner()

    let toml_input: string = "[repoman]\nschema = 1\n\n[defaults]\nrepos_root = \"/home/u/repos\"\nbackup_root = \"/nfs/repos\"\nincus_project = \"repoman\"\ndefault_image = \"images:ubuntu/26.04/cloud\"\nprofiles = [\"default\", \"claude-share\"]\n\n[[project]]\nname = \"isurus\"\nrepo = \"isurus-project\"\nimage = \"images:ubuntu/26.04/cloud\"\nprofiles = [\"default\"]\ncreated = \"2026-04-28T15:00:00Z\"\nlast_sync = \"\"\nbackup = true\n"

    let r = config.parse_registry(toml_input)
    runner.assert_eq_bool(rg.is_ok(r), true, "parse succeeds")
    if rg.is_ok(r)
        let reg = rg.unwrap_ok(r)
        runner.assert_eq_int(reg.schema, 1, "schema = 1")
        runner.assert_eq_string(reg.defaults.repos_root, "/home/u/repos", "repos_root")
        runner.assert_eq_string(reg.defaults.backup_root, "/nfs/repos", "backup_root")
        runner.assert_eq_string(reg.defaults.incus_project, "repoman", "incus_project")
        runner.assert_eq_string(reg.defaults.default_image, "images:ubuntu/26.04/cloud", "default_image")
        runner.assert_eq_int(reg.defaults.profiles.length(), 2, "defaults.profiles count")
        runner.assert_eq_string(reg.defaults.profiles[0], "default", "defaults.profiles[0]")
        runner.assert_eq_string(reg.defaults.profiles[1], "claude-share", "defaults.profiles[1]")
        runner.assert_eq_int(reg.projects.length(), 1, "1 project")
        let p = reg.projects[0]
        runner.assert_eq_string(p.name, "isurus", "project.name")
        runner.assert_eq_string(p.repo, "isurus-project", "project.repo")
        runner.assert_eq_string(p.image, "images:ubuntu/26.04/cloud", "project.image")
        runner.assert_eq_int(p.profiles.length(), 1, "project.profiles count")
        runner.assert_eq_string(p.profiles[0], "default", "project.profiles[0]")
        runner.assert_eq_string(p.last_sync, "", "project.last_sync")
        runner.assert_eq_bool(p.backup, true, "project.backup")
    end if

    // schema rejection
    let bad_schema: string = "[repoman]\nschema = 99\n[defaults]\nrepos_root = \"/r\"\nbackup_root = \"/b\"\nincus_project = \"x\"\ndefault_image = \"y\"\nprofiles = []\n"
    let r2 = config.parse_registry(bad_schema)
    runner.assert_eq_bool(rg.is_err(r2), true, "schema 99 rejected")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_parse.reef
```

Expected: compile error (`parse_registry` not defined in `config`).

- [ ] **Step 3: Add parse_registry + helpers to src/config.reef**

In `src/config.reef`, add to the `export` block:

```reef
    fn parse_registry(toml_text: string): rg.Result[Registry, string]
```

Add these functions before `end module`:

```reef
// Parse a comma-separated TOML inline array of strings: `["a", "b"]`.
// Tolerates whitespace and missing brackets; returns empty if input is empty.
fn parse_string_array(raw: string): [string]
    let n: int = str.length(raw)
    if n == 0
        return new [string](0)
    end if
    // Strip leading [ and trailing ]
    mut start: int = 0
    mut end_idx: int = n
    if n > 0 and raw[0] == '['
        start = 1
    end if
    if end_idx > start and raw[end_idx - 1] == ']'
        end_idx = end_idx - 1
    end if
    let inner: string = str.substring(raw, start, end_idx - start)

    // Split on commas, then trim quotes and whitespace from each element.
    let inner_len: int = str.length(inner)
    if inner_len == 0
        return new [string](0)
    end if

    // Reef doesn't have a dynamic split-and-collect; use str.split with a max.
    mut parts: [string] = new [string](64)
    let count: int = str.split(inner, ',', parts, 64)

    mut result: [string] = new [string](count)
    mut i: int = 0
    while i < count
        let p: string = str.trim_ws(parts[i])
        // Strip surrounding double quotes if present
        let pl: int = str.length(p)
        if pl >= 2 and p[0] == '"' and p[pl - 1] == '"'
            result[i] = str.substring(p, 1, pl - 2)
        else
            result[i] = p
        end if
        i = i + 1
    end while
    return result
end parse_string_array

fn parse_registry(toml_text: string): rg.Result[Registry, string]
    let doc: toml.TomlDoc = toml.toml_parse_doc(toml_text)
    if doc.truncated
        return @rg.Result[Registry, string].Err("registry too large (>1024 entries)")
    end if

    let schema: int = toml.toml_get_int_doc(doc, "repoman.schema")
    if schema != 1
        return @rg.Result[Registry, string].Err("unsupported schema (expected 1)")
    end if

    let defaults: Defaults = Defaults {
        repos_root:    toml.toml_get_doc(doc, "defaults.repos_root"),
        backup_root:   toml.toml_get_doc(doc, "defaults.backup_root"),
        incus_project: toml.toml_get_doc(doc, "defaults.incus_project"),
        default_image: toml.toml_get_doc(doc, "defaults.default_image"),
        profiles:      parse_string_array(toml.toml_get_doc(doc, "defaults.profiles"))
    }

    let project_count: int = toml.toml_array_count(doc.keys, doc.count, "project")
    mut projects: [Project] = new [Project](project_count)
    mut i: int = 0
    while i < project_count
        let p: Project = Project {
            name:      toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "name"),
            repo:      toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "repo"),
            image:     toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "image"),
            profiles:  parse_string_array(toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "profiles")),
            created:   toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "created"),
            last_sync: toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "last_sync"),
            backup:    toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "backup") != "false"
        }
        projects[i] = p
        i = i + 1
    end while

    let reg: Registry = Registry {
        schema:   schema,
        defaults: defaults,
        projects: projects
    }
    return @rg.Result[Registry, string].Ok(reg)
end parse_registry
```

Note on the `backup` boolean parse: `toml_get_bool` exists, but the table-array helper `toml_array_get` returns a string. We default-true unless the literal string is `"false"`. Tighter handling can come later.

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_parse.reef
```

Expected: 19 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_parse.reef
hg commit -m "config: parse_registry via TomlDoc + tests"
```

---

## Task 6: config.serialize_registry

**Files:**
- Modify: `src/config.reef` (add `serialize_registry`)
- Create: `tests/test_config_serialize.reef`

Renders a `Registry` to a TOML string using `TomlBuilder`. The output must round-trip cleanly through `parse_registry` (we test that explicitly in Task 7).

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_serialize.reef`:

```reef
import config
import test.framework

proc main()
    let runner = new framework.TestRunner()

    let defaults: config.Defaults = config.Defaults {
        repos_root:    "/home/u/repos",
        backup_root:   "/nfs/repos",
        incus_project: "repoman",
        default_image: "images:ubuntu/26.04/cloud",
        profiles:      ["default", "claude-share"]
    }
    mut projects: [config.Project] = new [config.Project](1)
    projects[0] = config.Project {
        name:      "isurus",
        repo:      "isurus-project",
        image:     "images:ubuntu/26.04/cloud",
        profiles:  ["default"],
        created:   "2026-04-28T15:00:00Z",
        last_sync: "",
        backup:    true
    }
    let reg: config.Registry = config.Registry {
        schema:   1,
        defaults: defaults,
        projects: projects
    }

    let out: string = config.serialize_registry(reg)
    runner.assert_contains_string(out, "[repoman]", "has [repoman] header")
    runner.assert_contains_string(out, "schema = 1", "has schema field")
    runner.assert_contains_string(out, "[defaults]", "has [defaults] header")
    runner.assert_contains_string(out, "repos_root = \"/home/u/repos\"", "has repos_root field")
    runner.assert_contains_string(out, "[[project]]", "has [[project]] header")
    runner.assert_contains_string(out, "name = \"isurus\"", "has project.name")
    runner.assert_contains_string(out, "backup = true", "has backup = true")
    runner.assert_contains_string(out, "profiles = [\"default\", \"claude-share\"]", "defaults.profiles array")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_serialize.reef
```

Expected: compile error (`serialize_registry` undefined).

- [ ] **Step 3: Add serialize_registry to src/config.reef**

Add to the export block:

```reef
    fn serialize_registry(reg: Registry): string
```

Add the implementation before `end module`:

```reef
fn serialize_registry(reg: Registry): string
    let b: toml.TomlBuilder = toml.toml_builder()

    toml.toml_begin_table(b, "repoman")
    toml.toml_set_int(b, "schema", reg.schema)

    toml.toml_begin_table(b, "defaults")
    toml.toml_set_string(b, "repos_root", reg.defaults.repos_root)
    toml.toml_set_string(b, "backup_root", reg.defaults.backup_root)
    toml.toml_set_string(b, "incus_project", reg.defaults.incus_project)
    toml.toml_set_string(b, "default_image", reg.defaults.default_image)
    toml.toml_set_string_array(b, "profiles", reg.defaults.profiles)

    let pn: int = reg.projects.length()
    mut i: int = 0
    while i < pn
        let p: Project = reg.projects[i]
        toml.toml_array_append_table(b, "project")
        toml.toml_set_string(b, "name", p.name)
        toml.toml_set_string(b, "repo", p.repo)
        toml.toml_set_string(b, "image", p.image)
        toml.toml_set_string_array(b, "profiles", p.profiles)
        toml.toml_set_string(b, "created", p.created)
        toml.toml_set_string(b, "last_sync", p.last_sync)
        toml.toml_set_bool(b, "backup", p.backup)
        i = i + 1
    end while

    return toml.toml_render(b)
end serialize_registry
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_serialize.reef
```

Expected: 8 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_serialize.reef
hg commit -m "config: serialize_registry via TomlBuilder + tests"
```

---

## Task 7: config round-trip test

**Files:**
- Create: `tests/test_config_roundtrip.reef`

Confirms that `parse(serialize(reg)) == reg`. This is the canonical test for any encoder pair — without it the two halves can drift.

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_roundtrip.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

proc main()
    let runner = new framework.TestRunner()

    let defaults: config.Defaults = config.Defaults {
        repos_root:    "/home/u/repos",
        backup_root:   "/nfs/repos",
        incus_project: "repoman",
        default_image: "images:ubuntu/26.04/cloud",
        profiles:      ["default", "claude-share"]
    }
    mut projects: [config.Project] = new [config.Project](2)
    projects[0] = config.Project {
        name:      "isurus",
        repo:      "isurus-project",
        image:     "images:ubuntu/26.04/cloud",
        profiles:  ["default"],
        created:   "2026-04-28T15:00:00Z",
        last_sync: "",
        backup:    true
    }
    projects[1] = config.Project {
        name:      "tools",
        repo:      "tools",
        image:     "images:debian/12/cloud",
        profiles:  ["default", "claude-share"],
        created:   "2026-04-29T10:00:00Z",
        last_sync: "2026-04-29T11:00:00Z",
        backup:    false
    }
    let reg: config.Registry = config.Registry {
        schema: 1, defaults: defaults, projects: projects
    }

    let serialized: string = config.serialize_registry(reg)
    let parsed_r = config.parse_registry(serialized)
    runner.assert_eq_bool(rg.is_ok(parsed_r), true, "round-trip parse succeeds")

    if rg.is_ok(parsed_r)
        let reg2 = rg.unwrap_ok(parsed_r)
        runner.assert_eq_int(reg2.schema, 1, "schema preserved")
        runner.assert_eq_string(reg2.defaults.repos_root, reg.defaults.repos_root, "defaults.repos_root preserved")
        runner.assert_eq_int(reg2.defaults.profiles.length(), 2, "defaults.profiles len preserved")
        runner.assert_eq_int(reg2.projects.length(), 2, "project count preserved")
        runner.assert_eq_string(reg2.projects[0].name, "isurus", "project[0].name")
        runner.assert_eq_string(reg2.projects[1].name, "tools", "project[1].name")
        runner.assert_eq_bool(reg2.projects[0].backup, true, "project[0].backup")
        runner.assert_eq_bool(reg2.projects[1].backup, false, "project[1].backup")
        runner.assert_eq_string(reg2.projects[1].last_sync, "2026-04-29T11:00:00Z", "last_sync preserved")
    end if

    runner.report()
end main
```

- [ ] **Step 2: Run test**

```bash
reefc run tests/test_config_roundtrip.reef
```

Expected: 9 assertions pass. If any fail, the parse and serialize sides have drifted — fix whichever is wrong.

- [ ] **Step 3: Commit**

```bash
hg add tests/test_config_roundtrip.reef
hg commit -m "config: round-trip test (serialize → parse equals original)"
```

---

## Task 8: config.parse_override

**Files:**
- Modify: `src/config.reef` (add `parse_override`)
- Create: `tests/test_config_override.reef`

Parses a per-project override TOML (`[container]`, `[[mount]]`, `[env]` sections). Returns `Result[Override, string]`. Override files are read-only — repoman never writes them — so we only need parse, not serialize.

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_override.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

proc main()
    let runner = new framework.TestRunner()

    let toml_input: string = "[container]\nimage = \"images:debian/12/cloud\"\nprofiles = [\"default\", \"claude-share\", \"node-dev\"]\n\n[[mount]]\nsource = \"~/.npm\"\npath = \"/home/ctusa/.npm\"\n\n[[mount]]\nsource = \"~/.cache/yarn\"\npath = \"/home/ctusa/.cache/yarn\"\n\n[env]\nNODE_ENV = \"development\"\nDEBUG = \"1\"\n"

    let r = config.parse_override(toml_input)
    runner.assert_eq_bool(rg.is_ok(r), true, "override parse succeeds")
    if rg.is_ok(r)
        let ov = rg.unwrap_ok(r)
        runner.assert_eq_string(ov.image, "images:debian/12/cloud", "override.image")
        runner.assert_eq_bool(ov.has_profiles, true, "has_profiles set")
        runner.assert_eq_int(ov.profiles.length(), 3, "profiles count")
        runner.assert_eq_string(ov.profiles[2], "node-dev", "profiles[2]")
        runner.assert_eq_int(ov.mounts.length(), 2, "mount count")
        runner.assert_eq_string(ov.mounts[0].source, "~/.npm", "mount[0].source")
        runner.assert_eq_string(ov.mounts[0].path, "/home/ctusa/.npm", "mount[0].path")
        runner.assert_eq_int(ov.env_keys.length(), 2, "env count")
        // env keys are not order-guaranteed by TOML; check both possibilities
        let k0: string = ov.env_keys[0]
        runner.assert_eq_bool(k0 == "NODE_ENV" or k0 == "DEBUG", true, "env_keys[0] is one of expected")
    end if

    // empty override
    let r2 = config.parse_override("")
    runner.assert_eq_bool(rg.is_ok(r2), true, "empty override is valid")
    if rg.is_ok(r2)
        let ov2 = rg.unwrap_ok(r2)
        runner.assert_eq_string(ov2.image, "", "empty override.image")
        runner.assert_eq_bool(ov2.has_profiles, false, "no profiles")
        runner.assert_eq_int(ov2.mounts.length(), 0, "no mounts")
        runner.assert_eq_int(ov2.env_keys.length(), 0, "no env")
    end if

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_override.reef
```

Expected: compile error (`parse_override` undefined).

- [ ] **Step 3: Add parse_override to src/config.reef**

Add to the export block:

```reef
    fn parse_override(toml_text: string): rg.Result[Override, string]
```

Implementation (place before `end module`):

```reef
fn parse_override(toml_text: string): rg.Result[Override, string]
    let doc: toml.TomlDoc = toml.toml_parse_doc(toml_text)
    if doc.truncated
        return @rg.Result[Override, string].Err("override too large")
    end if

    let image: string = toml.toml_get_doc(doc, "container.image")
    let profiles_raw: string = toml.toml_get_doc(doc, "container.profiles")
    let has_profiles: bool = toml.toml_has_key_doc(doc, "container.profiles")
    let profiles: [string] = parse_string_array(profiles_raw)

    let mount_count: int = toml.toml_array_count(doc.keys, doc.count, "mount")
    mut mounts: [Mount] = new [Mount](mount_count)
    mut i: int = 0
    while i < mount_count
        mounts[i] = Mount {
            source: toml.toml_array_get(doc.keys, doc.values, doc.count, "mount", i, "source"),
            path:   toml.toml_array_get(doc.keys, doc.values, doc.count, "mount", i, "path")
        }
        i = i + 1
    end while

    // Walk doc.keys for entries starting with "env."
    mut env_keys_buf: [string] = new [string](128)
    mut env_vals_buf: [string] = new [string](128)
    mut env_count: int = 0
    mut k: int = 0
    while k < doc.count
        let key: string = doc.keys[k]
        if str.starts_with(key, "env.")
            if env_count < 128
                env_keys_buf[env_count] = str.substring(key, 4, str.length(key) - 4)
                env_vals_buf[env_count] = doc.values[k]
                env_count = env_count + 1
            end if
        end if
        k = k + 1
    end while

    mut env_keys: [string] = new [string](env_count)
    mut env_vals: [string] = new [string](env_count)
    mut j: int = 0
    while j < env_count
        env_keys[j] = env_keys_buf[j]
        env_vals[j] = env_vals_buf[j]
        j = j + 1
    end while

    let ov: Override = Override {
        image:        image,
        profiles:     profiles,
        has_profiles: has_profiles,
        mounts:       mounts,
        env_keys:     env_keys,
        env_values:   env_vals
    }
    return @rg.Result[Override, string].Ok(ov)
end parse_override
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_override.reef
```

Expected: all assertions pass (12 in this test).

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_override.reef
hg commit -m "config: parse_override (container/mount/env) + tests"
```

---

## Task 9: config.merge_with_defaults

**Files:**
- Modify: `src/config.reef` (add `merge_with_defaults`)
- Create: `tests/test_config_merge.reef`

Pure function: takes a name, repo dirname, optional `--image` flag, optional Override, and Defaults. Returns an `EffectiveConfig`. Implements the merge table from spec §3.3:

| Field | Priority |
|---|---|
| `image` | flag → override.image → defaults.default_image |
| `profiles` | override.profiles (replace, when has_profiles) → defaults.profiles |
| `mounts` | always [auto repo bind] ++ override.mounts |
| `env` | override.env entries (or empty) |

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_merge.reef`:

```reef
import config
import test.framework

fn make_defaults(): config.Defaults
    return config.Defaults {
        repos_root:    "/home/u/repos",
        backup_root:   "/nfs/repos",
        incus_project: "repoman",
        default_image: "images:ubuntu/26.04/cloud",
        profiles:      ["default", "claude-share"]
    }
end make_defaults

fn empty_override(): config.Override
    return config.Override {
        image:        "",
        profiles:     new [string](0),
        has_profiles: false,
        mounts:       new [config.Mount](0),
        env_keys:     new [string](0),
        env_values:   new [string](0)
    }
end empty_override

proc main()
    let runner = new framework.TestRunner()
    let d = make_defaults()

    // 1. flag wins over override and defaults
    mut ov1: config.Override = empty_override()
    ov1.image = "images:debian/12/cloud"
    let e1 = config.merge_with_defaults("isurus", "isurus-project", "images:custom/x", ov1, d)
    runner.assert_eq_string(e1.image, "images:custom/x", "flag wins")
    runner.assert_eq_string(e1.repo_path, "/home/u/repos/isurus-project", "repo_path computed")

    // 2. override.image wins over defaults when no flag
    let e2 = config.merge_with_defaults("isurus", "isurus-project", "", ov1, d)
    runner.assert_eq_string(e2.image, "images:debian/12/cloud", "override.image wins")

    // 3. defaults when no flag, no override.image
    let e3 = config.merge_with_defaults("isurus", "isurus-project", "", empty_override(), d)
    runner.assert_eq_string(e3.image, "images:ubuntu/26.04/cloud", "defaults.image wins")

    // 4. profiles: override replaces defaults when has_profiles
    mut ov2: config.Override = empty_override()
    ov2.profiles = ["default", "claude-share", "node-dev"]
    ov2.has_profiles = true
    let e4 = config.merge_with_defaults("isurus", "isurus-project", "", ov2, d)
    runner.assert_eq_int(e4.profiles.length(), 3, "override profiles count")
    runner.assert_eq_string(e4.profiles[2], "node-dev", "override profiles[2]")

    // 5. profiles fall back to defaults
    let e5 = config.merge_with_defaults("isurus", "isurus-project", "", empty_override(), d)
    runner.assert_eq_int(e5.profiles.length(), 2, "defaults profiles count")

    // 6. mounts: auto bind always present, override appended
    mut m1: [config.Mount] = new [config.Mount](1)
    m1[0] = config.Mount { source: "~/.npm", path: "/home/u/.npm" }
    mut ov3: config.Override = empty_override()
    ov3.mounts = m1
    let e6 = config.merge_with_defaults("isurus", "isurus-project", "", ov3, d)
    runner.assert_eq_int(e6.mounts.length(), 2, "auto bind + 1 override mount")
    runner.assert_eq_string(e6.mounts[0].source, "/home/u/repos/isurus-project", "auto bind source")
    runner.assert_eq_string(e6.mounts[0].path, "/home/u/repos/isurus-project", "auto bind dest")
    runner.assert_eq_string(e6.mounts[1].source, "~/.npm", "override mount preserved")

    // 7. env: passed through
    mut keys: [string] = ["NODE_ENV"]
    mut vals: [string] = ["development"]
    mut ov4: config.Override = empty_override()
    ov4.env_keys = keys
    ov4.env_values = vals
    let e7 = config.merge_with_defaults("isurus", "isurus-project", "", ov4, d)
    runner.assert_eq_int(e7.env_keys.length(), 1, "env_keys count")
    runner.assert_eq_string(e7.env_keys[0], "NODE_ENV", "env_keys[0]")
    runner.assert_eq_string(e7.env_values[0], "development", "env_values[0]")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_merge.reef
```

Expected: compile error (`merge_with_defaults` undefined).

- [ ] **Step 3: Add merge_with_defaults to src/config.reef**

Add to export block:

```reef
    fn merge_with_defaults(name: string, repo: string, image_flag: string, ov: Override, d: Defaults): EffectiveConfig
```

Implementation:

```reef
fn merge_with_defaults(name: string, repo: string, image_flag: string, ov: Override, d: Defaults): EffectiveConfig
    let repos_root_expanded: string = paths.expand_home(d.repos_root)
    let repo_path: string = paths.join(repos_root_expanded, repo)

    // Image priority: flag → override → defaults
    mut image: string = d.default_image
    if str.length(ov.image) > 0
        image = ov.image
    end if
    if str.length(image_flag) > 0
        image = image_flag
    end if

    // Profiles: override replaces defaults when has_profiles, else defaults
    mut profiles: [string] = d.profiles
    if ov.has_profiles
        profiles = ov.profiles
    end if

    // Mounts: [auto repo bind] ++ override.mounts
    let ov_mount_count: int = ov.mounts.length()
    mut mounts: [Mount] = new [Mount](1 + ov_mount_count)
    mounts[0] = Mount { source: repo_path, path: repo_path }
    mut i: int = 0
    while i < ov_mount_count
        // Expand ~ in mount source for host paths
        let m: Mount = ov.mounts[i]
        mounts[i + 1] = Mount {
            source: paths.expand_home(m.source),
            path:   m.path
        }
        i = i + 1
    end while

    return EffectiveConfig {
        name:       name,
        repo:       repo,
        repo_path:  repo_path,
        image:      image,
        profiles:   profiles,
        mounts:     mounts,
        env_keys:   ov.env_keys,
        env_values: ov.env_values
    }
end merge_with_defaults
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_merge.reef
```

Expected: 14 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_merge.reef
hg commit -m "config: merge_with_defaults + tests"
```

---

## Task 10: config.add_project + config.update_last_sync

**Files:**
- Modify: `src/config.reef` (add the two registry mutators)
- Modify: `tests/test_config_merge.reef` (add cases) — actually new file for clarity:
- Create: `tests/test_config_mutate.reef`

Two pure functions that build a new `Registry` from an existing one. They never write to disk — that's `save`'s job (Task 12).

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_mutate.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

fn empty_defaults(): config.Defaults
    return config.Defaults {
        repos_root: "/r", backup_root: "/b", incus_project: "p",
        default_image: "img", profiles: new [string](0)
    }
end empty_defaults

proc main()
    let runner = new framework.TestRunner()

    let reg0: config.Registry = config.Registry {
        schema: 1, defaults: empty_defaults(), projects: new [config.Project](0)
    }

    let p1: config.Project = config.Project {
        name: "isurus", repo: "isurus", image: "img",
        profiles: new [string](0), created: "t", last_sync: "", backup: true
    }
    let r1 = config.add_project(reg0, p1)
    runner.assert_eq_bool(rg.is_ok(r1), true, "add new project ok")
    if rg.is_ok(r1)
        let reg1 = rg.unwrap_ok(r1)
        runner.assert_eq_int(reg1.projects.length(), 1, "1 project after add")
        runner.assert_eq_string(reg1.projects[0].name, "isurus", "project added")

        // duplicate add fails
        let r2 = config.add_project(reg1, p1)
        runner.assert_eq_bool(rg.is_err(r2), true, "duplicate name rejected")

        // update_last_sync
        let r3 = config.update_last_sync(reg1, "isurus", "2026-04-29T12:00:00Z")
        runner.assert_eq_bool(rg.is_ok(r3), true, "update existing ok")
        if rg.is_ok(r3)
            let reg3 = rg.unwrap_ok(r3)
            runner.assert_eq_string(reg3.projects[0].last_sync, "2026-04-29T12:00:00Z", "last_sync updated")
        end if

        // update unknown name fails
        let r4 = config.update_last_sync(reg1, "nope", "t")
        runner.assert_eq_bool(rg.is_err(r4), true, "unknown name rejected")
    end if

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_mutate.reef
```

Expected: compile error.

- [ ] **Step 3: Add functions to src/config.reef**

Export:

```reef
    fn add_project(reg: Registry, p: Project): rg.Result[Registry, string]
    fn update_last_sync(reg: Registry, name: string, ts: string): rg.Result[Registry, string]
```

Implementations:

```reef
fn add_project(reg: Registry, p: Project): rg.Result[Registry, string]
    let n: int = reg.projects.length()
    mut i: int = 0
    while i < n
        if reg.projects[i].name == p.name
            return @rg.Result[Registry, string].Err("project already exists: " + p.name)
        end if
        i = i + 1
    end while

    mut new_projects: [Project] = new [Project](n + 1)
    mut k: int = 0
    while k < n
        new_projects[k] = reg.projects[k]
        k = k + 1
    end while
    new_projects[n] = p

    return @rg.Result[Registry, string].Ok(Registry {
        schema:   reg.schema,
        defaults: reg.defaults,
        projects: new_projects
    })
end add_project

fn update_last_sync(reg: Registry, name: string, ts: string): rg.Result[Registry, string]
    let n: int = reg.projects.length()
    mut found: int = -1
    mut i: int = 0
    while i < n
        if reg.projects[i].name == name
            found = i
        end if
        i = i + 1
    end while

    if found < 0
        return @rg.Result[Registry, string].Err("project not in registry: " + name)
    end if

    mut new_projects: [Project] = new [Project](n)
    mut k: int = 0
    while k < n
        if k == found
            let old: Project = reg.projects[k]
            new_projects[k] = Project {
                name: old.name, repo: old.repo, image: old.image,
                profiles: old.profiles, created: old.created,
                last_sync: ts, backup: old.backup
            }
        else
            new_projects[k] = reg.projects[k]
        end if
        k = k + 1
    end while

    return @rg.Result[Registry, string].Ok(Registry {
        schema:   reg.schema,
        defaults: reg.defaults,
        projects: new_projects
    })
end update_last_sync
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_mutate.reef
```

Expected: 7 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_mutate.reef
hg commit -m "config: add_project + update_last_sync + tests"
```

---

## Task 11: config.load_or_init (file I/O)

**Files:**
- Modify: `src/config.reef` (add `load_or_init`, `default_registry_for`, `registry_path`)
- Create: `tests/test_config_io.reef` (uses temp dir under `/tmp`)

`load_or_init(home_dir)` is the main entry point: returns the registry, creating an initial one if none exists. We use `home_dir` as a parameter (not implicit `$HOME`) so the test can drive it.

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_io.reef`:

```reef
import config
import test.framework
import core.result_generic as rg
import io.dir as iodir
import io.file as iofile
import sys.process as proc

proc main()
    let runner = new framework.TestRunner()

    // Set up a fresh temp dir as fake $HOME
    let pid_str: string = "12345"  // process id stand-in for uniqueness; reuse same dir is fine
    let tmp: string = "/tmp/repoman-test-load-init"
    // Wipe and recreate
    let _: int = proc.process_wait(proc.process_spawn("rm", ["-rf", tmp]))
    let _: bool = iodir.create_dir_all(tmp)

    // First call: no .config/repoman/repoman.toml exists → init writes default
    let r1 = config.load_or_init(tmp)
    runner.assert_eq_bool(rg.is_ok(r1), true, "load_or_init creates default")
    if rg.is_ok(r1)
        let reg = rg.unwrap_ok(r1)
        runner.assert_eq_int(reg.schema, 1, "default schema = 1")
        runner.assert_eq_int(reg.projects.length(), 0, "default has no projects")
        runner.assert_eq_string(reg.defaults.incus_project, "repoman", "default incus_project")
    end if

    // The file should now exist on disk.
    let cfg_path: string = tmp + "/.config/repoman/repoman.toml"
    runner.assert_eq_bool(iofile.fileExists(cfg_path), true, "registry file written")

    // Second call: should load the existing file.
    let r2 = config.load_or_init(tmp)
    runner.assert_eq_bool(rg.is_ok(r2), true, "second load reads existing")

    // Cleanup
    let _: int = proc.process_wait(proc.process_spawn("rm", ["-rf", tmp]))

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_io.reef
```

Expected: compile error.

- [ ] **Step 3: Add load_or_init + helpers to src/config.reef**

Export:

```reef
    fn registry_path(home_dir: string): string
    fn default_registry(home_dir: string): Registry
    fn load_or_init(home_dir: string): rg.Result[Registry, string]
```

Implementation:

```reef
fn registry_path(home_dir: string): string
    let cfg_dir: string = paths.join(home_dir, ".config/repoman")
    return paths.join(cfg_dir, "repoman.toml")
end registry_path

fn default_registry(home_dir: string): Registry
    let repos_root: string = paths.join(home_dir, "repos")
    return Registry {
        schema: 1,
        defaults: Defaults {
            repos_root:    repos_root,
            backup_root:   "/nfs/repos",
            incus_project: "repoman",
            default_image: "images:ubuntu/26.04/cloud",
            profiles:      ["default", "claude-share"]
        },
        projects: new [Project](0)
    }
end default_registry

fn load_or_init(home_dir: string): rg.Result[Registry, string]
    let cfg_path: string = registry_path(home_dir)
    let cfg_dir: string = iopath.dirname(cfg_path)

    // Ensure ~/.config/repoman/ exists
    if not iodir.dir_exists(cfg_dir)
        if not iodir.create_dir_all(cfg_dir)
            return @rg.Result[Registry, string].Err("cannot create config dir: " + cfg_dir)
        end if
    end if

    if iofile.fileExists(cfg_path)
        let contents: string = iofile.readFile(cfg_path)
        return parse_registry(contents)
    end if

    // Init: write default registry.
    let reg: Registry = default_registry(home_dir)
    let saved_r = save(reg, cfg_path)
    if rg.is_err(saved_r)
        return @rg.Result[Registry, string].Err(rg.unwrap_err(saved_r))
    end if
    return @rg.Result[Registry, string].Ok(reg)
end load_or_init
```

Note: this references `save` which is the next task. Stub it out for now so this file compiles:

```reef
fn save(reg: Registry, cfg_path: string): rg.Result[bool, string]
    let _: bool = iofile.writeFile(cfg_path, serialize_registry(reg))
    return @rg.Result[bool, string].Ok(true)
end save
```

The stub will be replaced in Task 12 with the proper atomic write.

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_io.reef
```

Expected: 5 assertions pass; `/tmp/repoman-test-load-init` is cleaned up at the end.

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_io.reef
hg commit -m "config: load_or_init with stub save (init flow + tests)"
```

---

## Task 12: config.save (atomic write with fsync + rename)

**Files:**
- Modify: `src/config.reef` (replace stub `save` with atomic version)
- Create: `tests/test_config_save.reef`

Atomic write recipe per spec §3.4: write to `<path>.tmp`, fsync the tmp, rename over the target. If any step fails, return Err with the failing step.

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_save.reef`:

```reef
import config
import test.framework
import core.result_generic as rg
import io.dir as iodir
import io.file as iofile
import sys.process as proc

proc main()
    let runner = new framework.TestRunner()

    let tmp: string = "/tmp/repoman-test-save"
    let _: int = proc.process_wait(proc.process_spawn("rm", ["-rf", tmp]))
    let _: bool = iodir.create_dir_all(tmp)
    let cfg_path: string = tmp + "/repoman.toml"

    let reg: config.Registry = config.default_registry("/home/u")
    let r1 = config.save(reg, cfg_path)
    runner.assert_eq_bool(rg.is_ok(r1), true, "save returns Ok")
    runner.assert_eq_bool(iofile.fileExists(cfg_path), true, "target file exists")
    runner.assert_eq_bool(iofile.fileExists(cfg_path + ".tmp"), false, "tmp removed after rename")

    // Round-trip: read what we wrote
    let contents: string = iofile.readFile(cfg_path)
    let r2 = config.parse_registry(contents)
    runner.assert_eq_bool(rg.is_ok(r2), true, "saved file parses")
    if rg.is_ok(r2)
        let reg2 = rg.unwrap_ok(r2)
        runner.assert_eq_int(reg2.schema, 1, "schema preserved on disk")
    end if

    let _: int = proc.process_wait(proc.process_spawn("rm", ["-rf", tmp]))
    runner.report()
end main
```

- [ ] **Step 2: Run test to verify the stub passes one assertion but isn't atomic-safe**

The stub `save` from Task 11 will pass the basic assertions (it does write the file), but doesn't go through `.tmp` and doesn't fsync. We're going to replace it.

```bash
reefc run tests/test_config_save.reef
```

Expected: passes (the stub is correct enough for these assertions; we replace it for crash safety, not behavior).

- [ ] **Step 3: Replace the stub save with the atomic version**

In `src/config.reef`, find the stub `save` from Task 11 and replace it with:

```reef
// Atomic write: writeFile(.tmp) → fsync(.tmp) → rename(.tmp, target).
// If any step fails, returns Err naming the failing step.
fn save(reg: Registry, cfg_path: string): rg.Result[bool, string]
    let serialized: string = serialize_registry(reg)
    let tmp_path: string = cfg_path + ".tmp"

    if not iofile.writeFile(tmp_path, serialized)
        return @rg.Result[bool, string].Err("write failed: " + tmp_path)
    end if

    if not iofile.fsync(tmp_path)
        // Best effort: clean up tmp
        let _: bool = iofile.deleteFile(tmp_path)
        return @rg.Result[bool, string].Err("fsync failed: " + tmp_path)
    end if

    if not iofile.rename(tmp_path, cfg_path)
        let _: bool = iofile.deleteFile(tmp_path)
        return @rg.Result[bool, string].Err("rename failed: " + tmp_path + " → " + cfg_path)
    end if

    return @rg.Result[bool, string].Ok(true)
end save
```

Add `save` to the export block:

```reef
    fn save(reg: Registry, cfg_path: string): rg.Result[bool, string]
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_config_save.reef
```

Expected: 5 assertions pass; the `.tmp` file is gone after rename.

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_save.reef
hg commit -m "config: atomic save (writeFile→fsync→rename)"
```

---

## Task 13: incus subprocess wrappers

**Files:**
- Modify: `src/incus.reef`

Subprocess wrappers around the `incus` CLI. These are NOT unit-tested — they need a live Incus daemon; the smoke recipe in Task 21 covers them. We do test that the argv-list construction is correct by inspection — read the bash prototype lines 105-115 for the canonical incantations.

Wrappers needed:
- `project_ensure(project: string)` — `incus project list --format csv -c name | grep -qx <p>`, else `incus project create <p>`
- `container_exists(project: string, name: string)` — `incus list --project <p> --format csv -c n | grep -qx <name>`
- `launch(project, name, image, profiles)` — `incus launch --project <p> [--profile P]+ <image> <name>`
- `device_add_disk(project, name, dev, source, dst)` — `incus config device add --project <p> <name> <dev> disk source=<src> path=<dst>`
- `set_env(project, name, key, val)` — `incus config set --project <p> <name> environment.<key>=<val>`
- `restart(project, name)` — `incus restart --project <p> <name>`

Each wrapper calls `process_spawn(prog, argv)` then `process_wait(pid)` and returns `Result[bool, string]` (Ok(true) on exit 0, Err with stderr-summary on non-zero). Stderr passes through to the user's terminal — we don't capture and reformat.

- [ ] **Step 1: Add wrappers to src/incus.reef**

Add to `src/incus.reef`:

```reef
import sys.process as p
import core.result_generic as rg
```

Add to the export block:

```reef
    fn project_ensure(project: string): rg.Result[bool, string]
    fn container_exists(project: string, name: string): rg.Result[bool, string]
    fn launch(project: string, name: string, image: string, profiles: [string]): rg.Result[bool, string]
    fn device_add_disk(project: string, name: string, dev: string, src: string, dst: string): rg.Result[bool, string]
    fn set_env_var(project: string, name: string, key: string, val: string): rg.Result[bool, string]
    fn restart(project: string, name: string): rg.Result[bool, string]
```

Implementations (place before `end module`):

```reef
// Run `incus <args>`. Returns Ok(true) on exit 0, Err with a brief diagnostic
// on non-zero. Stderr inherits the parent terminal — incus's own message
// reaches the user without us reformatting.
fn run_incus(args: [string]): rg.Result[bool, string]
    let pid: int = p.process_spawn("incus", args)
    if pid < 0
        return @rg.Result[bool, string].Err("failed to spawn 'incus' (is it installed?)")
    end if
    let exit: int = p.process_wait(pid)
    if exit == 0
        return @rg.Result[bool, string].Ok(true)
    end if
    return @rg.Result[bool, string].Err("incus exited with code " + int_to_str_simple(exit))
end run_incus

fn int_to_str_simple(n: int): string
    if n == 0
        return "0"
    end if
    mut value: int = n
    mut neg: bool = false
    if value < 0
        neg = true
        value = -value
    end if
    mut digits: string = ""
    while value > 0
        let d: int = value % 10
        let dc: char = '0'
        unsafe
            dc = d + 48
        end unsafe
        let one: string = ""
        let appended: string = append_char_local(one, dc)
        digits = appended + digits
        value = value / 10
    end while
    if neg
        return "-" + digits
    end if
    return digits
end int_to_str_simple

fn append_char_local(s: string, c: char): string
    let n: int = str.length(s)
    mut out: string = ""
    mut i: int = 0
    while i < n
        out = out + char_to_string(s[i])
        i = i + 1
    end while
    return out + char_to_string(c)
end append_char_local

fn char_to_string(c: char): string
    let buf: string = ""
    // Quick char-to-string via concatenation: rely on str.concat handling chars
    // (Reef strings are buffer-backed; if str.concat fails we'd need an FFI).
    mut tmp: string = " "
    tmp[0] = c
    return tmp
end char_to_string

// project_ensure: list, create if missing.
fn project_ensure(project: string): rg.Result[bool, string]
    // `incus project show <name>` exits 0 if it exists, non-0 otherwise.
    let pid: int = p.process_spawn("incus", ["project", "show", project])
    let exit: int = p.process_wait(pid)
    if exit == 0
        return @rg.Result[bool, string].Ok(true)
    end if
    // Create
    return run_incus(["project", "create", project])
end project_ensure

fn container_exists(project: string, name: string): rg.Result[bool, string]
    // `incus info --project <p> <name>` exits 0 if it exists.
    let pid: int = p.process_spawn("incus", ["info", "--project", project, name])
    let exit: int = p.process_wait(pid)
    if exit == 0
        return @rg.Result[bool, string].Ok(true)
    end if
    return @rg.Result[bool, string].Ok(false)
end container_exists

fn launch(project: string, name: string, image: string, profiles: [string]): rg.Result[bool, string]
    let pn: int = profiles.length()
    // Compute argv length: ["launch", "--project", project, ...profile args (2*pn), image, name]
    mut args: [string] = new [string](3 + 2 * pn + 2)
    args[0] = "launch"
    args[1] = "--project"
    args[2] = project
    mut i: int = 0
    while i < pn
        args[3 + i * 2] = "--profile"
        args[3 + i * 2 + 1] = profiles[i]
        i = i + 1
    end while
    args[3 + 2 * pn] = image
    args[3 + 2 * pn + 1] = name
    return run_incus(args)
end launch

fn device_add_disk(project: string, name: string, dev: string, src: string, dst: string): rg.Result[bool, string]
    return run_incus([
        "config", "device", "add",
        "--project", project,
        name,
        dev,
        "disk",
        "source=" + src,
        "path=" + dst
    ])
end device_add_disk

fn set_env_var(project: string, name: string, key: string, val: string): rg.Result[bool, string]
    return run_incus([
        "config", "set",
        "--project", project,
        name,
        "environment." + key + "=" + val
    ])
end set_env_var

fn restart(project: string, name: string): rg.Result[bool, string]
    return run_incus(["restart", "--project", project, name])
end restart
```

Note on the int-to-string and char-to-string helpers: reef-stdlib does have these (`encoding.toml` has `int_to_str`; `core.str` has helpers) but they aren't all exported uniformly. To minimize surprise, the helpers above are local and self-contained. If a clean stdlib import works, prefer it — but verify with `reefc --check` before relying on it.

- [ ] **Step 2: Compile-check the module**

```bash
reefc build
```

Expected: builds cleanly. (No tests for this module — they require a live Incus.)

- [ ] **Step 3: Commit**

```bash
hg commit -m "incus: subprocess wrappers (project_ensure/launch/device_add/set_env/restart)"
```

---

## Task 14: sync.build_rsync_args (pure)

**Files:**
- Create: `src/sync.reef`
- Create: `tests/test_sync_args.reef`

Pure function that builds the rsync argv from `(src, dst, dry_run, no_delete, is_tty, excluded_repos)`. The standard exclude list is hardcoded to match the bash prototype line by line. `excluded_repos` is the per-project `backup = false` skip list, applied only in whole-tree mode.

- [ ] **Step 1: Write the failing test**

Create `tests/test_sync_args.reef`:

```reef
import sync
import test.framework

proc main()
    let runner = new framework.TestRunner()

    // Basic: no flags
    let a1: [string] = sync.build_rsync_args("/src/", "/dst/", false, false, false, new [string](0))
    runner.assert_eq_bool(contains_str(a1, "-aHAX"), true, "has -aHAX")
    runner.assert_eq_bool(contains_str(a1, "--info=stats2"), true, "has --info=stats2")
    runner.assert_eq_bool(contains_str(a1, "--delete"), true, "delete on by default")
    runner.assert_eq_bool(contains_str(a1, "--exclude=node_modules/"), true, "node_modules excluded")
    runner.assert_eq_bool(contains_str(a1, "--exclude=.cache/"), true, ".cache excluded")
    runner.assert_eq_bool(last_two(a1, "/src/", "/dst/"), true, "src and dst end positional")

    // Dry run: --dry-run + --itemize-changes + --info=stats2 (NOT progress2)
    let a2: [string] = sync.build_rsync_args("/src/", "/dst/", true, false, true, new [string](0))
    runner.assert_eq_bool(contains_str(a2, "--dry-run"), true, "dry-run flag")
    runner.assert_eq_bool(contains_str(a2, "--itemize-changes"), true, "itemize-changes flag")
    runner.assert_eq_bool(contains_str(a2, "--info=stats2"), true, "info stats2")
    runner.assert_eq_bool(contains_str(a2, "--info=stats2,progress2"), false, "no progress in dry-run")

    // No delete
    let a3: [string] = sync.build_rsync_args("/src/", "/dst/", false, true, false, new [string](0))
    runner.assert_eq_bool(contains_str(a3, "--delete"), false, "no --delete with no_delete")

    // TTY interactive: stats2,progress2
    let a4: [string] = sync.build_rsync_args("/src/", "/dst/", false, false, true, new [string](0))
    runner.assert_eq_bool(contains_str(a4, "--info=stats2,progress2"), true, "tty progress")

    // Excluded repos in whole-tree mode
    let a5: [string] = sync.build_rsync_args("/src/", "/dst/", false, false, false, ["repo-A", "repo-B"])
    runner.assert_eq_bool(contains_str(a5, "--exclude=repo-A/"), true, "excluded repo A")
    runner.assert_eq_bool(contains_str(a5, "--exclude=repo-B/"), true, "excluded repo B")

    runner.report()
end main

fn contains_str(arr: [string], target: string): bool
    let n: int = arr.length()
    mut i: int = 0
    while i < n
        if arr[i] == target
            return true
        end if
        i = i + 1
    end while
    return false
end contains_str

fn last_two(arr: [string], a: string, b: string): bool
    let n: int = arr.length()
    if n < 2
        return false
    end if
    return arr[n - 2] == a and arr[n - 1] == b
end last_two
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_sync_args.reef
```

Expected: compile error (`sync` module not found).

- [ ] **Step 3: Create src/sync.reef**

```reef
module sync

import core.str
import core.result_generic as rg
import sys.process as p

export
    fn build_rsync_args(src: string, dst: string, dry_run: bool, no_delete: bool, is_tty: bool, excluded_repos: [string]): [string]
end export

// Hardcoded excludes matching bash prototype line 26-41.
fn standard_excludes(): [string]
    return [
        "node_modules/",
        "target/",
        "build/",
        "dist/",
        ".next/",
        "__pycache__/",
        "*.pyc",
        ".venv/",
        "venv/",
        ".cache/",
        ".tox/",
        ".pytest_cache/",
        ".mypy_cache/",
        ".ruff_cache/"
    ]
end standard_excludes

fn build_rsync_args(src: string, dst: string, dry_run: bool, no_delete: bool, is_tty: bool, excluded_repos: [string]): [string]
    let std: [string] = standard_excludes()
    let std_n: int = std.length()
    let ex_n: int = excluded_repos.length()

    // Estimate capacity: 1 (-aHAX) + up to 3 info flags + 1 (--delete) + std_n excludes + ex_n excludes + 2 positionals
    let cap: int = 1 + 3 + 1 + std_n + ex_n + 2
    mut buf: [string] = new [string](cap)
    mut k: int = 0

    buf[k] = "-aHAX"
    k = k + 1

    if dry_run
        buf[k] = "--dry-run"
        k = k + 1
        buf[k] = "--itemize-changes"
        k = k + 1
        buf[k] = "--info=stats2"
        k = k + 1
    elif is_tty
        buf[k] = "--info=stats2,progress2"
        k = k + 1
    else
        buf[k] = "--info=stats2"
        k = k + 1
    end if

    if not no_delete
        buf[k] = "--delete"
        k = k + 1
    end if

    mut i: int = 0
    while i < std_n
        buf[k] = "--exclude=" + std[i]
        k = k + 1
        i = i + 1
    end while

    mut j: int = 0
    while j < ex_n
        buf[k] = "--exclude=" + excluded_repos[j] + "/"
        k = k + 1
        j = j + 1
    end while

    buf[k] = src
    k = k + 1
    buf[k] = dst
    k = k + 1

    // Trim to actual size
    mut out: [string] = new [string](k)
    mut m: int = 0
    while m < k
        out[m] = buf[m]
        m = m + 1
    end while
    return out
end build_rsync_args

end module
```

- [ ] **Step 4: Run test to verify it passes**

```bash
reefc run tests/test_sync_args.reef
```

Expected: 13 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add src/sync.reef tests/test_sync_args.reef
hg commit -m "sync: build_rsync_args (pure) + tests covering every branch"
```

---

## Task 15: sync.ensure_nfs_mounted (subprocess)

**Files:**
- Modify: `src/sync.reef` (add `ensure_nfs_mounted`)

Three-step check from bash prototype lines 60-71:
1. `stat <backup_root>` (triggers autofs)
2. `mountpoint -q <backup_root>` (confirms it's a mount)
3. `findmnt -t nfs4 <backup_root>` (confirms NFSv4)

Each fails fast with a different message. No unit test — needs a real NFS mount; smoke test will exercise it.

- [ ] **Step 1: Add ensure_nfs_mounted to src/sync.reef**

Add to export block:

```reef
    fn ensure_nfs_mounted(backup_root: string): rg.Result[bool, string]
```

Implementation:

```reef
fn ensure_nfs_mounted(backup_root: string): rg.Result[bool, string]
    // Step 1: stat triggers autofs
    let pid1: int = p.process_spawn("stat", [backup_root])
    if pid1 < 0
        return @rg.Result[bool, string].Err("cannot spawn stat")
    end if
    if p.process_wait(pid1) != 0
        return @rg.Result[bool, string].Err("cannot stat " + backup_root + " — autofs misconfigured or server unreachable")
    end if

    // Step 2: mountpoint
    let pid2: int = p.process_spawn("mountpoint", ["-q", backup_root])
    if pid2 < 0
        return @rg.Result[bool, string].Err("cannot spawn mountpoint")
    end if
    if p.process_wait(pid2) != 0
        return @rg.Result[bool, string].Err(backup_root + " exists but is not a mount — NFS server unreachable?")
    end if

    // Step 3: findmnt -t nfs4
    let pid3: int = p.process_spawn("findmnt", ["-t", "nfs4", backup_root])
    if pid3 < 0
        return @rg.Result[bool, string].Err("cannot spawn findmnt")
    end if
    if p.process_wait(pid3) != 0
        return @rg.Result[bool, string].Err(backup_root + " is mounted but not as nfs4 — check /etc/auto.nfs")
    end if

    return @rg.Result[bool, string].Ok(true)
end ensure_nfs_mounted
```

- [ ] **Step 2: Compile-check**

```bash
reefc build
```

Expected: builds cleanly.

- [ ] **Step 3: Commit**

```bash
hg commit -m "sync: ensure_nfs_mounted (stat → mountpoint → findmnt)"
```

---

## Task 16: sync.run

**Files:**
- Modify: `src/sync.reef` (add `run`)

Spawns rsync with the args from `build_rsync_args` and returns its exit code. Inherits parent stdio so the user sees rsync's progress live.

- [ ] **Step 1: Add run to src/sync.reef**

Add to export block:

```reef
    fn run(args: [string]): int
```

Implementation:

```reef
// Spawn rsync with the given argv. Inherits parent stdio (no capture).
// Returns rsync's exit code, or -1 if spawn failed.
fn run(args: [string]): int
    let pid: int = p.process_spawn("rsync", args)
    if pid < 0
        return -1
    end if
    return p.process_wait(pid)
end run
```

- [ ] **Step 2: Compile-check**

```bash
reefc build
```

Expected: builds cleanly.

- [ ] **Step 3: Commit**

```bash
hg commit -m "sync: run (spawn rsync, inherit stdio, return exit code)"
```

---

## Task 17: cli.cmd_new (orchestration)

**Files:**
- Create: `src/cli.reef` (with `cmd_new` function and supporting flag-parsing)

`cmd_new` walks through every step of spec §4.1: validate name, load registry, reject duplicates, resolve repo path, parse override, merge, ensure project, ensure no container conflict, launch, attach mounts, set env, restart, write registry, print ready hint. No unit test — orchestration is smoke-tested.

- [ ] **Step 1: Create src/cli.reef with cmd_new**

```reef
module cli

import core.str
import core.result_generic as rg
import io.console as console
import io.file as iofile
import sys.flag as flag
import sys.env as env
import sys.args as args
import config
import incus
import sync
import paths

export
    fn cmd_new(argv: [string]): int
    fn cmd_sync(argv: [string]): int
    fn dispatch(argv: [string]): int
end export

// argv passed in is the slice past argv[1] (i.e., excludes program + subcommand).
fn cmd_new(argv: [string]): int
    let parser: flag.FlagParser = flag.flag_parser_from(argv)
    flag.application(parser, "repoman new")
    flag.description(parser, "Create a new container + repo bind")
    let _ = flag.string_flag(parser, "repo", '\0', "", "repo dirname (defaults to <name>)")
    let _ = flag.string_flag(parser, "image", '\0', "", "container image (overrides default)")

    if not flag.parse(parser)
        console.printErr("repoman: error: " + flag.error(parser) + "\n")
        return 2
    end if

    let positionals: [string] = flag.positional_args(parser)
    if positionals.length() != 1
        console.printErr("repoman: error: 'new' takes exactly one positional argument: <name>\n")
        return 2
    end if

    let name: string = positionals[0]
    let repo_flag: string = flag.get_string(parser, "repo")
    let image_flag: string = flag.get_string(parser, "image")

    if not incus.validate_name(name)
        console.printErr("repoman: error: invalid container name: " + name + "\n")
        console.printErr("hint: lowercase alphanumeric + hyphens, ≤63 chars, no leading hyphen\n")
        return 1
    end if

    let home: string = env.get_env_or("HOME", "")
    if str.length(home) == 0
        console.printErr("repoman: error: HOME is not set\n")
        return 3
    end if

    let cfg_path: string = config.registry_path(home)
    let reg_r = config.load_or_init(home)
    if rg.is_err(reg_r)
        console.printErr("repoman: error: " + rg.unwrap_err(reg_r) + "\n")
        return 3
    end if
    let reg: config.Registry = rg.unwrap_ok(reg_r)

    // Reject duplicate name
    let pn: int = reg.projects.length()
    mut i: int = 0
    while i < pn
        if reg.projects[i].name == name
            console.printErr("repoman: error: project '" + name + "' already in registry\n")
            console.printErr("hint: incus delete --project " + reg.defaults.incus_project + " " + name + " ; then remove from " + cfg_path + "\n")
            return 4
        end if
        i = i + 1
    end while

    // Resolve repo path
    mut repo: string = repo_flag
    if str.length(repo) == 0
        repo = name
    end if
    let repos_root: string = paths.expand_home(reg.defaults.repos_root)
    let repo_path: string = paths.join(repos_root, repo)
    if not paths.is_dir(repo_path)
        console.printErr("repoman: error: no repo at " + repo_path + "\n")
        return 3
    end if

    // Read override (optional)
    let override_path: string = paths.join(home, ".config/repoman/repos.d/" + name + ".toml")
    mut override: config.Override = config.Override {
        image: "", profiles: new [string](0), has_profiles: false,
        mounts: new [config.Mount](0),
        env_keys: new [string](0), env_values: new [string](0)
    }
    if iofile.fileExists(override_path)
        let ov_r = config.parse_override(iofile.readFile(override_path))
        if rg.is_err(ov_r)
            console.printErr("repoman: error: bad override " + override_path + ": " + rg.unwrap_err(ov_r) + "\n")
            return 3
        end if
        override = rg.unwrap_ok(ov_r)
    end if

    let eff: config.EffectiveConfig = config.merge_with_defaults(name, repo, image_flag, override, reg.defaults)

    // Ensure incus project
    console.printErr("==> incus project ensure " + reg.defaults.incus_project + "\n")
    let pe = incus.project_ensure(reg.defaults.incus_project)
    if rg.is_err(pe)
        console.printErr("repoman: error: " + rg.unwrap_err(pe) + "\n")
        return 1
    end if

    // Reject if container exists already
    let ce = incus.container_exists(reg.defaults.incus_project, name)
    if rg.is_err(ce)
        console.printErr("repoman: error: " + rg.unwrap_err(ce) + "\n")
        return 1
    end if
    if rg.unwrap_ok(ce)
        console.printErr("repoman: error: container '" + name + "' already exists in project '" + reg.defaults.incus_project + "'\n")
        console.printErr("hint: incus delete --project " + reg.defaults.incus_project + " " + name + "\n")
        return 4
    end if

    // Launch
    console.printErr("==> incus launch " + eff.image + " " + name + "\n")
    let lr = incus.launch(reg.defaults.incus_project, name, eff.image, eff.profiles)
    if rg.is_err(lr)
        console.printErr("repoman: error: " + rg.unwrap_err(lr) + "\n")
        return 1
    end if

    // Mounts: device names "repo" for the auto bind, "mount-1", "mount-2", ...
    let mn: int = eff.mounts.length()
    mut k: int = 0
    while k < mn
        let m: config.Mount = eff.mounts[k]
        let dev_name: string = "repo"
        if k > 0
            dev_name = "mount-" + int_to_str_simple(k)
        end if
        console.printErr("==> incus device add " + name + " " + dev_name + " " + m.source + ":" + m.path + "\n")
        let dr = incus.device_add_disk(reg.defaults.incus_project, name, dev_name, m.source, m.path)
        if rg.is_err(dr)
            console.printErr("repoman: error: " + rg.unwrap_err(dr) + "\n")
            console.printErr("hint: incus delete --project " + reg.defaults.incus_project + " " + name + "\n")
            return 1
        end if
        k = k + 1
    end while

    // Env
    let en: int = eff.env_keys.length()
    mut e: int = 0
    while e < en
        let er = incus.set_env_var(reg.defaults.incus_project, name, eff.env_keys[e], eff.env_values[e])
        if rg.is_err(er)
            console.printErr("repoman: error: " + rg.unwrap_err(er) + "\n")
            return 1
        end if
        e = e + 1
    end while

    // Restart so binds + env take effect
    console.printErr("==> incus restart " + name + "\n")
    let rr = incus.restart(reg.defaults.incus_project, name)
    if rg.is_err(rr)
        console.printErr("repoman: error: " + rg.unwrap_err(rr) + "\n")
        return 1
    end if

    // Build new project entry and write registry
    let new_p: config.Project = config.Project {
        name:      name,
        repo:      repo,
        image:     eff.image,
        profiles:  eff.profiles,
        created:   "",            // v0.1: leave timestamp blank (no time stdlib used yet)
        last_sync: "",
        backup:    true
    }
    let reg2_r = config.add_project(reg, new_p)
    if rg.is_err(reg2_r)
        console.printErr("repoman: error: " + rg.unwrap_err(reg2_r) + "\n")
        return 1
    end if
    let saved = config.save(rg.unwrap_ok(reg2_r), cfg_path)
    if rg.is_err(saved)
        console.printErr("repoman: error: " + rg.unwrap_err(saved) + "\n")
        return 1
    end if

    // Ready hint — use $UID and $HOME for shell expansion (correct on any host)
    console.printErr("==> ready\n")
    console.printErr("\n")
    console.printErr("  shell in:   incus exec --project " + reg.defaults.incus_project + " --user $UID --cwd " + repo_path + " --env HOME=$HOME " + name + " -- bash -l\n")
    console.printErr("  run claude: incus exec --project " + reg.defaults.incus_project + " " + name + " -- claude\n")
    return 0
end cmd_new

// Local int-to-str helper (decimal, non-negative integers expected)
fn int_to_str_simple(n: int): string
    if n == 0
        return "0"
    end if
    mut value: int = n
    mut digits: string = ""
    while value > 0
        let d: int = value % 10
        let dc: char = '0'
        unsafe
            dc = d + 48
        end unsafe
        let one_buf: string = " "
        one_buf[0] = dc
        digits = one_buf + digits
        value = value / 10
    end while
    return digits
end int_to_str_simple

end module
```

- [ ] **Step 2: Compile-check**

```bash
reefc build
```

Expected: builds cleanly.

- [ ] **Step 3: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: cmd_new orchestration (validate→load→merge→incus→save)"
```

---

## Task 18: cli.cmd_sync (orchestration)

**Files:**
- Modify: `src/cli.reef` (add `cmd_sync`)

`cmd_sync` walks spec §4.2: parse flags, load registry, ensure NFS mount, resolve target (single project vs whole tree), build args, run rsync, on success update last_sync. Exit code is rsync's, with pre-rsync errors using 1-4.

- [ ] **Step 1: Add cmd_sync to src/cli.reef**

Add the implementation (anywhere before `end module`):

```reef
fn cmd_sync(argv: [string]): int
    let parser: flag.FlagParser = flag.flag_parser_from(argv)
    flag.application(parser, "repoman sync")
    flag.description(parser, "rsync local repos → NFS backup")
    let _ = flag.bool_flag(parser, "no-delete", '\0', false, "additive only — no deletions on the destination")
    let _ = flag.bool_flag(parser, "dry-run", '\0', false, "preview changes without writing")

    if not flag.parse(parser)
        console.printErr("repoman: error: " + flag.error(parser) + "\n")
        return 2
    end if

    let positionals: [string] = flag.positional_args(parser)
    if positionals.length() > 1
        console.printErr("repoman: error: 'sync' takes at most one positional argument: [name]\n")
        return 2
    end if

    let no_delete: bool = flag.get_bool(parser, "no-delete")
    let dry_run: bool = flag.get_bool(parser, "dry-run")

    let home: string = env.get_env_or("HOME", "")
    if str.length(home) == 0
        console.printErr("repoman: error: HOME is not set\n")
        return 3
    end if

    let reg_r = config.load_or_init(home)
    if rg.is_err(reg_r)
        console.printErr("repoman: error: " + rg.unwrap_err(reg_r) + "\n")
        return 3
    end if
    let reg: config.Registry = rg.unwrap_ok(reg_r)
    let cfg_path: string = config.registry_path(home)

    let backup_root: string = paths.expand_home(reg.defaults.backup_root)
    let repos_root:  string = paths.expand_home(reg.defaults.repos_root)

    // ensure_nfs_mounted
    let mr = sync.ensure_nfs_mounted(backup_root)
    if rg.is_err(mr)
        console.printErr("repoman: error: " + rg.unwrap_err(mr) + "\n")
        return 3
    end if

    // Resolve target
    mut src: string = ""
    mut dst: string = ""
    mut excluded: [string] = new [string](0)
    mut single_target: string = ""

    if positionals.length() == 1
        let name: string = positionals[0]
        // Find in registry
        let pn: int = reg.projects.length()
        mut found: int = -1
        mut i: int = 0
        while i < pn
            if reg.projects[i].name == name
                found = i
            end if
            i = i + 1
        end while
        if found < 0
            console.printErr("repoman: error: '" + name + "' not in registry\n")
            console.printErr("hint: repoman new " + name + "\n")
            return 1
        end if
        let proj: config.Project = reg.projects[found]
        if not proj.backup
            console.printErr("repoman: error: '" + name + "' has backup = false; refusing single-target sync\n")
            return 1
        end if
        src = paths.join(repos_root, proj.repo) + "/"
        dst = paths.join(backup_root, proj.repo) + "/"
        single_target = name
    else
        // whole tree
        src = repos_root + "/"
        dst = backup_root + "/"
        // Build excludes for backup=false projects
        let pn: int = reg.projects.length()
        mut buf: [string] = new [string](pn)
        mut count: int = 0
        mut i: int = 0
        while i < pn
            if not reg.projects[i].backup
                buf[count] = reg.projects[i].repo
                count = count + 1
            end if
            i = i + 1
        end while
        mut tight: [string] = new [string](count)
        mut j: int = 0
        while j < count
            tight[j] = buf[j]
            j = j + 1
        end while
        excluded = tight
    end if

    // Build args + log + run
    let is_tty: bool = false  // v0.1: assume non-TTY (cron-friendly defaults).
                              // TTY detection via ui.backend.tty.is_tty(STDOUT_FD) is a v0.2 niceness.
    let rsync_args: [string] = sync.build_rsync_args(src, dst, dry_run, no_delete, is_tty, excluded)

    mut tags: string = ""
    if dry_run
        tags = tags + "(dry-run) "
    end if
    if no_delete
        tags = tags + "(additive) "
    end if
    console.printErr("==> rsync " + tags + src + " → " + dst + "\n")

    let exit: int = sync.run_rsync(rsync_args)
    if exit < 0
        console.printErr("repoman: error: failed to spawn rsync\n")
        return 1
    end if
    if exit != 0
        return exit
    end if

    // Success: update last_sync. Skip in dry-run mode (nothing changed).
    if not dry_run
        let now: string = ""  // v0.1: timestamp blank; time stdlib integration is a follow-on
        if str.length(single_target) > 0
            let upd = config.update_last_sync(reg, single_target, now)
            if rg.is_ok(upd)
                let _ = config.save(rg.unwrap_ok(upd), cfg_path)
            end if
        else
            mut cur: config.Registry = reg
            let pn: int = cur.projects.length()
            mut i: int = 0
            while i < pn
                if cur.projects[i].backup
                    let upd = config.update_last_sync(cur, cur.projects[i].name, now)
                    if rg.is_ok(upd)
                        cur = rg.unwrap_ok(upd)
                    end if
                end if
                i = i + 1
            end while
            let _ = config.save(cur, cfg_path)
        end if
    end if

    return 0
end cmd_sync
```

- [ ] **Step 2: Compile-check**

```bash
reefc build
```

Expected: builds cleanly.

- [ ] **Step 3: Commit**

```bash
hg commit -m "cli: cmd_sync orchestration (NFS check → rsync → last_sync update)"
```

---

## Task 19: cli.dispatch (outer router)

**Files:**
- Modify: `src/cli.reef` (add `dispatch`, `usage`)

Outer dispatch on `argv[1]` per spec §5. Handles `new`, `sync`, `--version`/`-V`, `--help`/`-h`/`help`, no args.

- [ ] **Step 1: Add dispatch + usage to src/cli.reef**

Add to the top of the implementations (before `cmd_new`):

```reef
fn version_string(): string
    return "repoman 0.1.0"
end version_string

proc print_usage()
    console.printErr("Usage: repoman <subcommand> [args]\n")
    console.printErr("\n")
    console.printErr("Subcommands\n")
    console.printErr("  new <name> [--repo <dirname>] [--image <image>]\n")
    console.printErr("      Launch a container in the 'repoman' Incus project; bind ~/repos/<dirname>.\n")
    console.printErr("\n")
    console.printErr("  sync [name] [--no-delete] [--dry-run]\n")
    console.printErr("      Mirror local repos to NFS backup (rsync --delete by default).\n")
    console.printErr("\n")
    console.printErr("  --version | -V\n")
    console.printErr("  --help    | -h | help\n")
end print_usage
```

Add `dispatch` (place after `cmd_sync`):

```reef
fn dispatch(argv: [string]): int
    // argv is the full process argv: [program, subcommand, ...]
    let n: int = argv.length()
    if n < 2
        print_usage()
        return 0
    end if

    let sub: string = argv[1]

    if sub == "--version" or sub == "-V"
        console.printErr(version_string() + "\n")
        return 0
    end if
    if sub == "--help" or sub == "-h" or sub == "help"
        print_usage()
        return 0
    end if

    // Slice argv[2..] for the subcommand parser
    mut rest: [string] = new [string](n - 2)
    mut i: int = 0
    while i < n - 2
        rest[i] = argv[i + 2]
        i = i + 1
    end while

    if sub == "new"
        return cmd_new(rest)
    end if
    if sub == "sync"
        return cmd_sync(rest)
    end if

    console.printErr("repoman: error: unknown subcommand: " + sub + "\n")
    console.printErr("hint: try 'repoman --help'\n")
    return 2
end dispatch
```

- [ ] **Step 2: Compile-check**

```bash
reefc build
```

Expected: builds cleanly.

- [ ] **Step 3: Commit**

```bash
hg commit -m "cli: dispatch + usage (subcommand routing, --version, --help)"
```

---

## Task 20: main.reef entry point

**Files:**
- Modify: `src/main.reef`

Tiny entry that collects argv, calls `cli.dispatch`, exits with the returned code.

- [ ] **Step 1: Replace src/main.reef**

Overwrite `src/main.reef` with:

```reef
import cli
import sys.args as args
import sys.process as p

proc main()
    let n: int = args.count()
    mut argv: [string] = new [string](n)
    mut i: int = 0
    while i < n
        argv[i] = args.get(i)
        i = i + 1
    end while
    let code: int = cli.dispatch(argv)
    p.exit_now(code)
end main
```

- [ ] **Step 2: Build and smoke-test the help output**

```bash
reefc build
./build/repoman --version
./build/repoman --help
./build/repoman
./build/repoman bogus-subcommand
```

Expected:
- `--version` → `repoman 0.1.0`, exit 0.
- `--help` → usage, exit 0.
- no args → usage, exit 0.
- bogus → error message, exit 2.

(Run `echo $?` after each to check exit codes.)

- [ ] **Step 3: Commit**

```bash
hg commit -m "main: argv collection + dispatch"
```

---

## Task 21: README + Makefile

**Files:**
- Create: `README.md`
- Create: `Makefile`

README documents quickstart, build, test loop, smoke recipe, install. Makefile provides `make`/`make install`/`make uninstall`/`make clean`/`make test` for distro packagers — `reefc` does the actual building.

- [ ] **Step 1: Create README.md**

```markdown
# repoman

Per-project Incus containers + opinionated NFS/ZFS backup. v0.1.

## Build

```bash
reefc build
```

Produces `./build/repoman`.

## Test

```bash
for t in tests/test_*.reef; do
    echo "== $t =="
    reefc run "$t" || exit 1
done
```

## Install

System-wide via Makefile (uses `reefc build` under the hood):

```bash
make
sudo make install        # installs to /usr/local/bin/repoman
```

## Quickstart

```bash
# First run creates ~/.config/repoman/repoman.toml with sane defaults.
repoman --help
repoman new isurus --repo isurus-project
repoman sync --dry-run
```

## Smoke test (requires Incus + NFS)

```bash
# In an existing repo dir under ~/repos:
repoman new test-foo
repoman sync test-foo --dry-run
incus delete --project repoman test-foo
```

## Configuration

Central registry: `~/.config/repoman/repoman.toml` (managed; do not edit while repoman is running).

Per-project overrides: `~/.config/repoman/repos.d/<container-name>.toml` (user-authored). Example:

```toml
[container]
image    = "images:debian/12/cloud"
profiles = ["default", "claude-share", "node-dev"]

[[mount]]
source = "~/.npm"
path   = "/home/ctusa/.npm"

[env]
NODE_ENV = "development"
```

## Recommended Incus profile: `claude-share`

For the agent-friendly setup repoman is built around, create a shared profile that exposes the user's Claude state:

```bash
# (one-time)
incus profile create claude-share
incus profile edit claude-share  # add your bind-mounts for ~/.claude, etc.
```

repoman uses profiles `default` and `claude-share` by default; override per-project in `repos.d/<name>.toml`.
```

- [ ] **Step 2: Create Makefile**

```makefile
PREFIX ?= /usr/local
BINDIR  = $(PREFIX)/bin
DESTDIR ?=

.PHONY: all build test clean install uninstall

all: build

build:
	reefc build

test:
	@for t in tests/test_*.reef; do \
		echo "== $$t =="; \
		reefc run "$$t" || exit 1; \
	done

clean:
	reefc clean

install: build
	install -d $(DESTDIR)$(BINDIR)
	install -m 0755 build/repoman $(DESTDIR)$(BINDIR)/repoman

uninstall:
	rm -f $(DESTDIR)$(BINDIR)/repoman
```

- [ ] **Step 3: Verify make targets work**

```bash
make clean
make build
ls build/repoman
make test
```

Expected: `make build` produces the binary, `make test` runs every `tests/test_*.reef` and reports pass.

- [ ] **Step 4: Commit**

```bash
hg add README.md Makefile
hg commit -m "docs: README + Makefile (quickstart, install, test loop)"
```

---

## Task 22: End-to-end smoke test

**Files:** none — operational verification

Run the smoke recipe from README against a real Incus + NFS environment. This is the v0.1 acceptance gate.

- [ ] **Step 1: Pre-flight**

Confirm:
- `incus version` works, daemon is running
- `/nfs/repos` is autofs-mounted (autofs config covers it)
- A dir exists under `~/repos/<some-name>` for the smoke (e.g., `mkdir ~/repos/repoman-smoke; cd ~/repos/repoman-smoke; hg init`)

- [ ] **Step 2: First-run init**

```bash
rm -rf ~/.config/repoman   # clean slate; you may want to back up first if you've been using it
./build/repoman --help
ls ~/.config/repoman/repoman.toml   # should NOT exist yet (help doesn't init)
./build/repoman sync --dry-run      # this triggers init
cat ~/.config/repoman/repoman.toml  # should show schema=1, no projects
```

Expected: registry created on first command that touches it.

- [ ] **Step 3: `new` flow**

```bash
./build/repoman new repoman-smoke
```

Expected:
- Stderr shows `==> incus project ensure repoman`, `==> incus launch ...`, `==> incus device add ... repo ...`, `==> incus restart ...`, `==> ready`.
- `incus list --project repoman` shows `repoman-smoke` running.
- `~/.config/repoman/repoman.toml` now has a `[[project]]` entry for `repoman-smoke`.
- The shell-in hint is printed.

- [ ] **Step 4: Verify the bind mount**

```bash
incus exec --project repoman repoman-smoke -- ls /home/ctusa/repos/repoman-smoke
```

Expected: contents of the host repo are visible inside the container.

- [ ] **Step 5: `sync` dry-run**

```bash
./build/repoman sync repoman-smoke --dry-run
```

Expected: rsync prints itemize-changes lines (mostly `cd+++++++++` for new dirs), exits 0, the registry's `last_sync` for `repoman-smoke` is NOT updated (because dry-run).

- [ ] **Step 6: `sync` real run**

```bash
./build/repoman sync repoman-smoke
```

Expected: rsync runs, exits 0, registry's `last_sync` for `repoman-smoke` is updated to a non-empty value (or stays empty if you haven't wired the timestamp yet — that's a v0.2 task per spec).

- [ ] **Step 7: Cleanup**

```bash
incus delete --project repoman --force repoman-smoke
# Manually remove the entry from ~/.config/repoman/repoman.toml (no `repoman remove` in v0.1)
```

- [ ] **Step 8: Tag the release**

```bash
hg tag -m "v0.1.0 ships" v0.1.0
```

If the smoke test surfaced bugs, fix them before tagging — open follow-up commits as needed.

---

## Self-review checklist (run after writing all tasks)

After completing the plan, verify:

1. **Spec coverage:**
   - §1 scope: `new`, `sync`, registry, override, project namespace ✓ (Tasks 17, 18, 11, 8, 17)
   - §2 architecture: 6 modules ✓ (Tasks 2, 3, 4-12, 13, 14-16, 17-19)
   - §3 data shapes: registry, override, merge, atomic write, validation ✓ (Tasks 4-9, 11, 12)
   - §4 flows: `new`, `sync` ✓ (Tasks 17, 18)
   - §5 CLI: subcommands, exit codes, error UX ✓ (Tasks 17-19)
   - §6 testing: pure-logic units, smoke recipe ✓ (Tasks 2, 3, 5-12, 14, 22)
   - §7 build/install: reef.toml, Makefile, README ✓ (Tasks 1, 21)

2. **Type consistency:** function names and signatures match between definitions and call sites — `parse_registry`, `serialize_registry`, `parse_override`, `merge_with_defaults`, `add_project`, `update_last_sync`, `load_or_init`, `save`, `registry_path`, `default_registry`. The `incus.*` and `sync.*` symbol shapes are consistent across `cli.reef`'s call sites and the module exports.

3. **Placeholder scan:** no TODO, no "implement later", no "similar to Task N". Code blocks are concrete.

---

## Known v0.1 simplifications (intentional, not gaps)

These are tracked for v0.2, deliberately omitted from the plan:
- **Timestamps blank.** `created` and `last_sync` are written as `""`. A `time.now_iso8601()` integration is straightforward but the time stdlib hasn't been audited yet; a dedicated follow-up task can add it without breaking the schema.
- **TTY detection always false.** `cmd_sync` hardcodes `is_tty = false`, giving cron-friendly `--info=stats2`. To get progress bars in interactive use, wire `ui.backend.tty.is_tty(STDOUT_FD)`. Trivial to add.
- **No rollback on partial `new` failure.** Per spec §4.1: if launch succeeds but a downstream step fails, the user sees the error and the manual cleanup hint. v0.2 candidate: `--rollback-on-error`.
- **No CI.** Per spec §6.5. Test loop runs locally via `make test`.
# repoman v0.3 — Setup wizard + LLM stack Implementation Plan

## Scope reduction (2026-05-08)

The `--hermes`/`--no-hermes`/`--purge-hermes` flag-based provisioning was **removed
during smoke testing** and does not ship in v0.3. Smoke testing exposed fundamental
problems with the bind-mount-the-host-runtime architecture: hermes' Python venv pins
to a uv-vendored host-only path, and uid-mapping for file binds does not generalize.
v0.4 will revisit via pre-built incus images.

v0.3 ships: setup wizard, llm-share profile (ollama wiring), schema-2 migration,
hermes module helpers as a library for v0.4.

---

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship `repoman setup` (idempotent host-bootstrap wizard) plus per-container hermes data-dir provisioning (`repoman new --hermes`, `repoman remove --purge-hermes`), with a repoman-managed `llm-share` Incus profile that wires containers to the host's ollama daemon over LAN.

**Architecture:** Two new modules under `src/`: `setup.reef` (the wizard — environment detection → stage planner → applier) and `hermes.reef` (per-container data-dir lifecycle: pure helpers for path resolution and seed-list classification, effectful `seed_data_dir` / `purge_data_dir`). Targeted edits to `config.reef` (schema bump 1→2 with migration; new `LlmDefaults` substruct; new `hermes` field on `Project`), `incus.reef` (capture-mode `profile_exists`, stdin-based `profile_create_or_edit`, options-aware `device_add_disk_opts`), and `cli.reef` (`cmd_setup` dispatch; `--hermes`/`--no-hermes` on `new`; `--purge-hermes` on `remove`; `hermes: yes/no` on `list`/`status`). The wizard composes `incus.*` and `hermes.*` — it adds no new abstractions over them.

**Tech Stack:** reef-lang 0.5.20 (no new stdlib requirements vs v0.2; targets every API documented since 0.5.10), `encoding.toml` (TomlBuilder + TomlDoc), `core.result_generic`, `sys.process.process_spawn` (argv-list — never shell), `sys.flag.flag_parser_from`, `io.console` (interactive prompts), `io.file`/`io.dir` (seed copy + dir creation), `test.framework.TestRunner`.

---

## Reference: spec and source

- Design spec: `docs/superpowers/specs/2026-05-06-repoman-v0.3-llm-and-setup.md` (this plan implements it)
- v0.1 plan (style/depth reference): `docs/superpowers/plans/2026-04-29-repoman-v0.1.md`
- Hermes Docker docs (cited in spec §4.1): `https://hermes-agent.nousresearch.com/docs/user-guide/docker`
- Existing modules whose patterns to mirror:
  - `src/config.reef` — parse/serialize/migrate idiom; `with_projects`/`add_project` invariant pattern
  - `src/incus.reef` — `process_run_capture` for stdout-capturing wrappers; `run_incus` for fire-and-forget
  - `src/cli.reef` — `cmd_*` shape: parse → validate → load registry → effects → save → exit code
  - `tests/test_config_*.reef` — temp-dir + fixture-driven tests; `framework.TestRunner` API

## File structure

```
~/repos/repoman/
├── reef.toml                              # bump version to 0.3.0
├── README.md                              # add: setup, --hermes, --purge-hermes
├── VISION.md                              # check off setup, document llm-share
├── src/
│   ├── cli.reef                           # +cmd_setup, --hermes/--no-hermes, --purge-hermes
│   ├── config.reef                        # +LlmDefaults, +Project.hermes, schema 1→2 migration
│   ├── hermes.reef                        # NEW — data-dir lifecycle
│   ├── incus.reef                         # +profile_exists, +profile_create_or_edit, +device_add_disk_opts
│   ├── log.reef                           # (unchanged)
│   ├── main.reef                          # (unchanged)
│   ├── paths.reef                         # (unchanged)
│   ├── setup.reef                         # NEW — host bootstrap wizard
│   └── sync.reef                          # (unchanged)
└── tests/
    ├── test_config_llm_parse.reef         # NEW — parse llm block + hermes field
    ├── test_config_llm_serialize.reef     # NEW — serialize llm block + hermes field
    ├── test_config_migrate_v1.reef        # NEW — schema 1 → 2 migration
    ├── test_hermes_paths.reef             # NEW — state_dir_for, default_seed_list
    ├── test_hermes_classify.reef          # NEW — classify_seed_entry partition logic
    ├── test_setup_template.reef           # NEW — render_llm_share_template golden
    ├── test_setup_planner.reef            # NEW — plan_stages from a fixture environment
    └── test_*.reef                        # existing v0.1/v0.2 tests untouched
```

Module-boundary rules from v0.1 still apply:
- Each module file declares `module <name>` matching its filename, ends with `end module`.
- `main.reef` has no module declaration.
- Tests are standalone reef programs; each has its own `proc main()`.
- `make test` runs every `tests/test_*.reef` and stops on first failure.

---

## Task 1: Add `LlmDefaults` type + extend `Defaults` struct

**Files:**
- Modify: `src/config.reef:32-39` (Defaults struct), add new type after it.

`Defaults` gains an `llm: LlmDefaults` field. `LlmDefaults` carries the four fields from spec §6.1: `enabled`, `hermes_default`, `ollama_url`, `hermes_seed`.

- [ ] **Step 1: Read the current Defaults declaration**

```bash
sed -n '32,40p' src/config.reef
```

Expected: a struct with `repos_root`, `backup_root`, `logdir`, `incus_project`, `default_image`, `profiles`.

- [ ] **Step 2: Add `LlmDefaults` type and extend `Defaults`**

In `src/config.reef`, modify the `export` block (lines 11-30) to add the new type to the export list (insert after `type Defaults`):

```reef
    type LlmDefaults
```

Then add the new type definition immediately above the existing `type Defaults = struct` block (around line 32):

```reef
type LlmDefaults = struct
    enabled:        bool
    hermes_default: bool
    ollama_url:     string
    hermes_seed:    [string]
end LlmDefaults
```

And extend the existing `Defaults` struct to add the field as the last entry, before `end Defaults`:

```reef
type Defaults = struct
    repos_root: string
    backup_root: string
    logdir: string
    incus_project: string
    default_image: string
    profiles: [string]
    llm: LlmDefaults
end Defaults
```

- [ ] **Step 3: Build to verify the types compile**

```bash
make build
```

Expected: clean build, no errors. Existing tests will fail to compile in next steps because the `Defaults` literal sites need updating — that's expected and addressed in Task 2.

- [ ] **Step 4: Update existing `Defaults` construction sites**

Three sites today construct a `Defaults` literal: `parse_registry` (line ~153), `default_registry` (line ~434), and any test that builds one. Pin the `llm` field on each to a default-disabled value so this task doesn't break the build.

In `parse_registry` (around line 153), update the literal to add the field at the end (just before the closing `}`):

```reef
        llm: LlmDefaults {
            enabled:        false,
            hermes_default: false,
            ollama_url:     "",
            hermes_seed:    new [string](0)
        }
```

In `default_registry` (around line 434), do the same:

```reef
        llm: LlmDefaults {
            enabled:        false,
            hermes_default: false,
            ollama_url:     "",
            hermes_seed:    new [string](0)
        }
```

- [ ] **Step 5: Build and run all existing tests**

```bash
make build && make test
```

Expected: clean build; every existing test passes (we haven't changed parse/serialize semantics yet — the new field defaults out).

- [ ] **Step 6: Commit**

```bash
hg add src/config.reef
hg commit -m "config: add LlmDefaults substruct on Defaults (schema unchanged)"
```

---

## Task 2: Add `hermes` field to `Project` struct

**Files:**
- Modify: `src/config.reef:41-49` (Project struct)

- [ ] **Step 1: Extend Project struct**

In `src/config.reef`, modify the `Project` struct:

```reef
type Project = struct
    name: string
    repo: string
    image: string
    profiles: [string]
    created: string
    last_sync: string
    backup: bool
    hermes: bool
end Project
```

- [ ] **Step 2: Update existing `Project` construction sites**

Find every `Project {` literal and add `hermes: false` as the last field. Sites today:
- `parse_registry` (around line 167)
- `update_last_sync` (around line 367) — preserves `old.hermes`
- `cmd_new` in cli.reef (around line 200)
- Tests (e.g., `tests/test_config_serialize.reef`, `tests/test_config_mutate.reef`)

For `parse_registry`, add at the end of the literal:

```reef
            hermes:    toml.toml_array_get(doc.keys, doc.values, doc.count, "project", i, "hermes") == "true"
```

For `update_last_sync` (line ~367), preserve old.hermes:

```reef
            new_projects[k] = Project {
                name: old.name, repo: old.repo, image: old.image,
                profiles: old.profiles, created: old.created,
                last_sync: ts, backup: old.backup,
                hermes: old.hermes
            }
```

For `cli.cmd_new` (line ~200), add:

```reef
        hermes:    false
```

For tests: open each test file that builds a `Project` literal and add `hermes: false` to the last position. Run `grep -rln 'Project {' tests/` to find them.

- [ ] **Step 3: Build and run all tests**

```bash
make build && make test
```

Expected: clean build, all existing tests pass.

- [ ] **Step 4: Commit**

```bash
hg add src/config.reef src/cli.reef tests/
hg commit -m "config: add Project.hermes flag (defaults false; schema unchanged)"
```

---

## Task 3: Schema-2 acceptance in `parse_registry` (no migration yet)

The existing parser rejects anything but `schema = 1`. We change it to accept `1` or `2`, populate `LlmDefaults` from `[defaults].llm` *only when present*, and otherwise leave it default-disabled.

**Files:**
- Modify: `src/config.reef:127-186` (parse_registry)
- Test: `tests/test_config_llm_parse.reef`

- [ ] **Step 1: Write the failing test for schema 2 + llm block**

Create `tests/test_config_llm_parse.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

proc main()
    let runner = new framework.TestRunner()

    // Schema 2 with [defaults.llm] populated
    let toml: string =
        "[repoman]\n" ++
        "schema = 2\n" ++
        "output = \"quiet\"\n\n" ++
        "[defaults]\n" ++
        "repos_root = \"~/repos\"\n" ++
        "backup_root = \"/nfs/repos\"\n" ++
        "logdir = \"~/.local/state/repoman\"\n" ++
        "incus_project = \"repoman\"\n" ++
        "default_image = \"images:ubuntu/26.04/cloud\"\n" ++
        "profiles = [\"default\", \"claude-share\", \"llm-share\"]\n\n" ++
        "[defaults.llm]\n" ++
        "enabled = true\n" ++
        "hermes_default = false\n" ++
        "ollama_url = \"http://192.168.168.42:11434\"\n" ++
        "hermes_seed = [\".env\", \"config.yaml\", \"skills/\"]\n\n" ++
        "[[project]]\n" ++
        "name = \"isurus\"\n" ++
        "repo = \"isurus\"\n" ++
        "image = \"images:ubuntu/26.04/cloud\"\n" ++
        "profiles = [\"default\", \"claude-share\", \"llm-share\"]\n" ++
        "created = \"2026-05-06T00:00:00Z\"\n" ++
        "last_sync = \"\"\n" ++
        "backup = true\n" ++
        "hermes = true\n"

    let r = config.parse_registry(toml)
    runner.assert_eq_bool(rg.is_ok(r), true, "schema 2 parses ok")
    if rg.is_ok(r)
        let reg = rg.unwrap_ok(r)
        runner.assert_eq_int(reg.schema, 2, "schema = 2")
        runner.assert_eq_bool(reg.defaults.llm.enabled, true, "llm.enabled = true")
        runner.assert_eq_bool(reg.defaults.llm.hermes_default, false, "llm.hermes_default = false")
        runner.assert_eq_string(reg.defaults.llm.ollama_url, "http://192.168.168.42:11434", "llm.ollama_url")
        runner.assert_eq_int(reg.defaults.llm.hermes_seed.length(), 3, "llm.hermes_seed has 3 entries")
        runner.assert_eq_int(reg.projects.length(), 1, "one project")
        runner.assert_eq_bool(reg.projects[0].hermes, true, "project.hermes = true")
    end if

    // Schema 2 with [defaults.llm] missing — should default to disabled
    let toml_no_llm: string =
        "[repoman]\n" ++
        "schema = 2\n" ++
        "output = \"quiet\"\n\n" ++
        "[defaults]\n" ++
        "repos_root = \"~/repos\"\n" ++
        "backup_root = \"/nfs/repos\"\n" ++
        "logdir = \"~/.local/state/repoman\"\n" ++
        "incus_project = \"repoman\"\n" ++
        "default_image = \"images:ubuntu/26.04/cloud\"\n" ++
        "profiles = [\"default\", \"claude-share\"]\n"

    let r2 = config.parse_registry(toml_no_llm)
    runner.assert_eq_bool(rg.is_ok(r2), true, "schema 2 without llm block parses ok")
    if rg.is_ok(r2)
        let reg2 = rg.unwrap_ok(r2)
        runner.assert_eq_bool(reg2.defaults.llm.enabled, false, "llm.enabled defaults false")
        runner.assert_eq_int(reg2.defaults.llm.hermes_seed.length(), 0, "llm.hermes_seed empty")
    end if

    // Schema 99 still rejected
    let toml_bad: string = "[repoman]\nschema = 99\n"
    let r3 = config.parse_registry(toml_bad)
    runner.assert_eq_bool(rg.is_err(r3), true, "schema 99 rejected")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_llm_parse.reef
```

Expected: failure — current parser rejects schema 2.

- [ ] **Step 3: Modify parse_registry to accept schema 1 or 2**

In `src/config.reef`, find the schema check (line ~134):

```reef
    if schema != 1
        return @Result[Registry, string].Err("unsupported schema (expected 1)")
    end if
```

Replace with:

```reef
    if schema != 1 and schema != 2
        return @Result[Registry, string].Err("unsupported schema (expected 1 or 2)")
    end if
```

- [ ] **Step 4: Read `[defaults.llm.*]` after the existing `defaults` literal**

Immediately after the `Defaults` literal is constructed (line ~160, before the project loop), replace:

```reef
    let defaults: Defaults = Defaults {
        repos_root:    toml.toml_get_doc(doc, "defaults.repos_root"),
        ...
        profiles:      parse_string_array(toml.toml_get_doc(doc, "defaults.profiles"))
    }
```

With:

```reef
    let llm: LlmDefaults = LlmDefaults {
        enabled:        toml.toml_get_doc(doc, "defaults.llm.enabled") == "true",
        hermes_default: toml.toml_get_doc(doc, "defaults.llm.hermes_default") == "true",
        ollama_url:     toml.toml_get_doc(doc, "defaults.llm.ollama_url"),
        hermes_seed:    parse_string_array(toml.toml_get_doc(doc, "defaults.llm.hermes_seed"))
    }

    let defaults: Defaults = Defaults {
        repos_root:    toml.toml_get_doc(doc, "defaults.repos_root"),
        backup_root:   toml.toml_get_doc(doc, "defaults.backup_root"),
        logdir:        logdir,
        incus_project: toml.toml_get_doc(doc, "defaults.incus_project"),
        default_image: toml.toml_get_doc(doc, "defaults.default_image"),
        profiles:      parse_string_array(toml.toml_get_doc(doc, "defaults.profiles")),
        llm:           llm
    }
```

(Replace the placeholder default `LlmDefaults` from Task 1's edit with this real read.)

- [ ] **Step 5: Run the new test to verify it passes**

```bash
reefc run tests/test_config_llm_parse.reef
```

Expected: all 9 assertions pass.

- [ ] **Step 6: Run all tests to verify no regression**

```bash
make test
```

Expected: every test passes (existing v0.1/v0.2 tests use `schema = 1`, which is still accepted; new test exercises schema = 2).

- [ ] **Step 7: Commit**

```bash
hg add src/config.reef tests/test_config_llm_parse.reef
hg commit -m "config: parse_registry accepts schema 2 + [defaults.llm] block"
```

---

## Task 4: Schema-2 emission in `serialize_registry`

The serializer always writes the current Registry shape. After this task, every save writes `schema = 2` with the `[defaults.llm]` block and per-project `hermes` field.

**Files:**
- Modify: `src/config.reef:188-219` (serialize_registry)
- Test: `tests/test_config_llm_serialize.reef`

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_llm_serialize.reef`:

```reef
import config
import test.framework
import core.result_generic as rg
import core.str

proc main()
    let runner = new framework.TestRunner()

    let llm = config.LlmDefaults {
        enabled:        true,
        hermes_default: false,
        ollama_url:     "http://192.168.168.42:11434",
        hermes_seed:    [".env", "config.yaml", "skills/"]
    }
    let defaults = config.Defaults {
        repos_root:    "~/repos",
        backup_root:   "/nfs/repos",
        logdir:        "~/.local/state/repoman",
        incus_project: "repoman",
        default_image: "images:ubuntu/26.04/cloud",
        profiles:      ["default", "claude-share", "llm-share"],
        llm:           llm
    }
    let p = config.Project {
        name:      "isurus",
        repo:      "isurus",
        image:     "images:ubuntu/26.04/cloud",
        profiles:  ["default", "claude-share", "llm-share"],
        created:   "2026-05-06T00:00:00Z",
        last_sync: "",
        backup:    true,
        hermes:    true
    }
    let reg = config.Registry {
        schema:   2,
        output:   "quiet",
        defaults: defaults,
        projects: [p]
    }

    let s = config.serialize_registry(reg)

    runner.assert_contains_string(s, "schema = 2",                  "writes schema = 2")
    runner.assert_contains_string(s, "[defaults.llm]",              "writes [defaults.llm] table header")
    runner.assert_contains_string(s, "enabled = true",              "writes llm.enabled")
    runner.assert_contains_string(s, "hermes_default = false",      "writes llm.hermes_default")
    runner.assert_contains_string(s, "ollama_url = \"http://192.168.168.42:11434\"", "writes llm.ollama_url")
    runner.assert_contains_string(s, "hermes_seed = [",             "writes llm.hermes_seed array")
    runner.assert_contains_string(s, "\".env\"",                    "hermes_seed contains .env")
    runner.assert_contains_string(s, "hermes = true",               "writes project.hermes")

    // Round-trip check
    let r2 = config.parse_registry(s)
    runner.assert_eq_bool(rg.is_ok(r2), true, "round-trip parses")
    if rg.is_ok(r2)
        let reg2 = rg.unwrap_ok(r2)
        runner.assert_eq_int(reg2.schema, 2, "round-trip schema")
        runner.assert_eq_bool(reg2.defaults.llm.enabled, true, "round-trip llm.enabled")
        runner.assert_eq_int(reg2.defaults.llm.hermes_seed.length(), 3, "round-trip hermes_seed length")
        runner.assert_eq_bool(reg2.projects[0].hermes, true, "round-trip project.hermes")
    end if

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_llm_serialize.reef
```

Expected: assertion failures — serializer doesn't yet emit the new fields.

- [ ] **Step 3: Extend serialize_registry**

In `src/config.reef`, find the `serialize_registry` function (line ~188). After the `toml_set_string_array(b, "profiles", reg.defaults.profiles)` line (~201), add the LLM table:

```reef
    toml.toml_begin_table(b, "defaults.llm")
    toml.toml_set_bool(b, "enabled", reg.defaults.llm.enabled)
    toml.toml_set_bool(b, "hermes_default", reg.defaults.llm.hermes_default)
    toml.toml_set_string(b, "ollama_url", reg.defaults.llm.ollama_url)
    toml.toml_set_string_array(b, "hermes_seed", reg.defaults.llm.hermes_seed)
```

Inside the per-project loop (line ~205-216), after the existing `toml_set_bool(b, "backup", p.backup)` line, add:

```reef
        toml.toml_set_bool(b, "hermes", p.hermes)
```

- [ ] **Step 4: Run the new test to verify it passes**

```bash
reefc run tests/test_config_llm_serialize.reef
```

Expected: all 13 assertions pass.

- [ ] **Step 5: Run all tests to verify the existing round-trip test still passes**

```bash
make test
```

Note: `tests/test_config_roundtrip.reef` likely now sees `schema = 2` in the output even when it constructed `schema = 1` input. If it asserts `schema = 1` post-round-trip, update its expectation to `schema = 2` (this is intentional: the serializer always writes the current shape). Inspect with `cat tests/test_config_roundtrip.reef`.

- [ ] **Step 6: Commit**

```bash
hg add src/config.reef tests/test_config_llm_serialize.reef
hg commit -m "config: serialize_registry writes schema 2 with [defaults.llm] + project.hermes"
```

---

## Task 5: Schema 1 → 2 migration in `load_or_init`

When `repoman` reads a `schema = 1` registry from disk, populate the new fields with safe defaults and treat the in-memory Registry as `schema = 2`. The next save (for any reason) writes `schema = 2`. Lossless and idempotent.

**Files:**
- Modify: `src/config.reef:446-469` (load_or_init), `src/config.reef:127-186` (parse_registry — set in-memory schema to 2 even if input is 1)
- Test: `tests/test_config_migrate_v1.reef`

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_migrate_v1.reef`:

```reef
import config
import test.framework
import core.result_generic as rg
import io.dir as iodir
import io.file as iofile
import sys.process as pr

proc main()
    let runner = new framework.TestRunner()

    let tmp: string = "/tmp/repoman-test-migrate-v1"
    let _w: int = pr.process_wait(pr.process_spawn("rm", ["-rf", tmp]))
    let _c: bool = iodir.create_dir_all(tmp)
    let _c2: bool = iodir.create_dir_all(tmp ++ "/.config/repoman")

    // Write a v1 registry on disk
    let v1: string =
        "[repoman]\n" ++
        "schema = 1\n" ++
        "output = \"quiet\"\n\n" ++
        "[defaults]\n" ++
        "repos_root = \"~/repos\"\n" ++
        "backup_root = \"/nfs/repos\"\n" ++
        "logdir = \"~/.local/state/repoman\"\n" ++
        "incus_project = \"repoman\"\n" ++
        "default_image = \"images:ubuntu/26.04/cloud\"\n" ++
        "profiles = [\"default\", \"claude-share\"]\n\n" ++
        "[[project]]\n" ++
        "name = \"isurus\"\n" ++
        "repo = \"isurus\"\n" ++
        "image = \"images:ubuntu/26.04/cloud\"\n" ++
        "profiles = [\"default\", \"claude-share\"]\n" ++
        "created = \"2026-04-28T15:00:00Z\"\n" ++
        "last_sync = \"\"\n" ++
        "backup = true\n"

    let _w2: bool = iofile.writeFile(tmp ++ "/.config/repoman/repoman.toml", v1)

    // load_or_init reads v1 and migrates
    let r = config.load_or_init(tmp)
    runner.assert_eq_bool(rg.is_ok(r), true, "v1 registry loads")
    if rg.is_ok(r)
        let reg = rg.unwrap_ok(r)
        runner.assert_eq_int(reg.schema, 2, "in-memory schema bumped to 2")
        runner.assert_eq_bool(reg.defaults.llm.enabled, false, "migrated llm.enabled = false")
        runner.assert_eq_int(reg.defaults.llm.hermes_seed.length(), 0, "migrated hermes_seed empty")
        runner.assert_eq_int(reg.projects.length(), 1, "project preserved")
        runner.assert_eq_bool(reg.projects[0].hermes, false, "migrated project.hermes = false")
        runner.assert_eq_string(reg.projects[0].name, "isurus", "project name preserved")
    end if

    // Cleanup
    let _w3: int = pr.process_wait(pr.process_spawn("rm", ["-rf", tmp]))

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_config_migrate_v1.reef
```

Expected: assertion failure — `reg.schema` will be 1, not 2.

- [ ] **Step 3: Force in-memory schema to 2 in parse_registry**

In `src/config.reef`, find the final Registry literal at the end of `parse_registry` (line ~179):

```reef
    let reg: Registry = Registry {
        schema:   schema,
        output:   output,
        defaults: defaults,
        projects: projects
    }
```

Change `schema:   schema,` to `schema:   2,` — every successfully parsed registry is exposed as schema 2 in memory regardless of disk format. Migration is implicit: parse fills new fields with safe defaults (the array/string/bool gets default-empty values when the keys aren't present), and the in-memory schema reflects what we'll write next.

- [ ] **Step 4: Run the migration test to verify it passes**

```bash
reefc run tests/test_config_migrate_v1.reef
```

Expected: all 6 assertions pass.

- [ ] **Step 5: Run all tests**

```bash
make test
```

Expected: every test passes. Any v0.1/v0.2 test that asserted `reg.schema == 1` after a parse needs its assertion updated to `2` — find and update with `grep -rn 'schema, 1' tests/` if the existing tests fail.

- [ ] **Step 6: Commit**

```bash
hg add src/config.reef tests/test_config_migrate_v1.reef
hg commit -m "config: implicit v1 → v2 migration on load (in-memory schema always 2)"
```

---

## Task 6: Update `default_registry` to schema 2

Fresh installs should write schema 2 from the start.

**Files:**
- Modify: `src/config.reef:428-444` (default_registry)
- Test: existing `tests/test_config_io.reef` will need its `schema, 1` assertion updated to `schema, 2`.

- [ ] **Step 1: Update default_registry**

In `src/config.reef`, find:

```reef
    return Registry {
        schema: 1,
        ...
    }
```

Change to:

```reef
    return Registry {
        schema: 2,
        ...
    }
```

- [ ] **Step 2: Update affected tests**

Run `grep -rn 'schema, 1' tests/` and update each match to `schema, 2`. Likely candidates: `tests/test_config_io.reef`, `tests/test_config_serialize.reef`. Each should change:

```reef
runner.assert_eq_int(reg.schema, 1, "default schema = 1")
```

to:

```reef
runner.assert_eq_int(reg.schema, 2, "default schema = 2")
```

- [ ] **Step 3: Run all tests**

```bash
make test
```

Expected: all tests pass.

- [ ] **Step 4: Commit**

```bash
hg add src/config.reef tests/
hg commit -m "config: default_registry writes schema 2"
```

---

## Task 7: `incus.profile_exists` (capture-mode wrapper)

**Files:**
- Modify: `src/incus.reef` (export block + new function)

- [ ] **Step 1: Add to the export block**

In `src/incus.reef`, extend the `export` block (lines 9-20) to add:

```reef
    fn profile_exists(project: string, name: string): rg.Result[bool, string]
```

- [ ] **Step 2: Implement profile_exists**

After the existing `delete_container` function (line ~272), add:

```reef
// Returns Ok(true) if the named profile exists in the given project,
// Ok(false) otherwise. Errors only on subprocess failure.
fn profile_exists(project: string, name: string): rg.Result[bool, string]
    let pid: int = process_run_silent("incus", [
        "profile", "show", "--project", project, name
    ])
    if pid < 0
        return @Result[bool, string].Err("failed to spawn 'incus profile show'")
    end if
    let exit: int = p.process_wait(pid)
    if exit == 0
        return @Result[bool, string].Ok(true)
    end if
    return @Result[bool, string].Ok(false)
end profile_exists
```

- [ ] **Step 3: Build to verify it compiles**

```bash
make build
```

Expected: clean build. (No unit test for this — it's a subprocess wrapper, smoke-tested via `cmd_setup`.)

- [ ] **Step 4: Commit**

```bash
hg add src/incus.reef
hg commit -m "incus: add profile_exists (capture-mode probe)"
```

---

## Task 8: `incus.profile_create_or_edit` (apply YAML via stdin)

`incus profile create <name>` makes an empty profile; `incus profile edit <name> < file.yaml` applies a YAML body. Idempotent flow: try create (ignore failure if exists), then edit. Edit takes YAML on stdin.

**Files:**
- Modify: `src/incus.reef`

- [ ] **Step 1: Add to export block**

```reef
    fn profile_create_or_edit(project: string, name: string, yaml: string): rg.Result[bool, string]
```

- [ ] **Step 2: Add a stdin-feeding helper near `process_run_capture`**

After `process_run_capture` (line ~96), add:

```reef
// Spawn `program args` with the given string written to the child's stdin.
// stdout/stderr inherit the parent terminal. Returns exit code.
// On any setup failure (fork, pipe, exec), returns non-zero.
fn process_run_with_stdin(program: string, args: [string], input: string): int
    let pipe_fds: [int] = fd.fd_pipe()
    if pipe_fds.length() != 2
        return -1
    end if
    let read_fd: int = pipe_fds[0]
    let write_fd: int = pipe_fds[1]

    let pid: int = p.process_fork()
    if pid < 0
        let _r: int = fd.fd_close(read_fd)
        let _w: int = fd.fd_close(write_fd)
        return -1
    end if
    if pid == 0
        // Child: dup read end of pipe over stdin, close both ends, exec.
        let _i: int = fd.fd_dup2(read_fd, fd.STDIN())
        let _c1: int = fd.fd_close(read_fd)
        let _c2: int = fd.fd_close(write_fd)
        let _x: int = p.process_run_exec(program, args)
        p.exit_now(127)
    end if

    // Parent: close read end, write input, close write, wait.
    let _cr: int = fd.fd_close(read_fd)
    let _wn: int = fd.fd_write(write_fd, input)
    let _cw: int = fd.fd_close(write_fd)
    return p.process_wait(pid)
end process_run_with_stdin
```

(If `fd.STDIN()` and `fd.fd_write` aren't already imported / exported by `sys.fd`, this requires a quick reef-stdlib check; both *are* expected to exist alongside `STDOUT()`/`STDERR()`/`fd_dup2`.)

- [ ] **Step 3: Implement profile_create_or_edit**

After `delete_container`:

```reef
// Idempotent: ensure the profile exists with the given YAML body.
// Step 1: try `incus profile create` (no-op error if exists).
// Step 2: `incus profile edit` reads stdin and replaces the profile body.
fn profile_create_or_edit(project: string, name: string, yaml: string): rg.Result[bool, string]
    // Step 1: create (silent on failure — profile may already exist)
    let create_pid: int = process_run_silent("incus", [
        "profile", "create", "--project", project, name
    ])
    let _ce: int = p.process_wait(create_pid)

    // Step 2: edit with YAML on stdin
    let edit_exit: int = process_run_with_stdin("incus", [
        "profile", "edit", "--project", project, name
    ], yaml)
    if edit_exit == 0
        return @Result[bool, string].Ok(true)
    end if
    return @Result[bool, string].Err("incus profile edit exited with code " ++ convert.to_string(edit_exit))
end profile_create_or_edit
```

- [ ] **Step 4: Build**

```bash
make build
```

Expected: clean build. If `fd.STDIN()` or `fd.fd_write` are missing, surface as an open question and hand-roll the equivalent from already-exported primitives.

- [ ] **Step 5: Commit**

```bash
hg add src/incus.reef
hg commit -m "incus: add profile_create_or_edit (stdin-feed YAML to incus profile edit)"
```

---

## Task 9: `incus.device_add_disk_opts` — extended disk-device add

The existing `device_add_disk(project, name, dev, src, dst)` doesn't support `shift=true` or `readonly=true`, both of which are required by the `llm-share` profile. Add a new function that takes an opts list (each `"key=value"` string is appended to the argv as a separate arg).

**Files:**
- Modify: `src/incus.reef`

- [ ] **Step 1: Add to export block**

```reef
    fn device_add_disk_opts(project: string, name: string, dev: string, src: string, dst: string, opts: [string]): rg.Result[bool, string]
```

- [ ] **Step 2: Implement device_add_disk_opts**

After the existing `device_add_disk` (line ~245), add:

```reef
// Like device_add_disk but with extra options like ["shift=true",
// "readonly=true"] appended to the incus argv.
fn device_add_disk_opts(project: string, name: string, dev: string, src: string, dst: string, opts: [string]): rg.Result[bool, string]
    let on: int = opts.length()
    mut args: [string] = new [string](7 + on)
    args[0] = "config"
    args[1] = "device"
    args[2] = "add"
    args[3] = "--project"
    args[4] = project
    args[5] = name
    args[6] = dev
    // (note: no "disk" type arg here — appended after as the 8th, with src/dst/opts)
    return device_add_disk_opts_inner(project, name, dev, src, dst, opts)
end device_add_disk_opts

fn device_add_disk_opts_inner(project: string, name: string, dev: string, src: string, dst: string, opts: [string]): rg.Result[bool, string]
    let on: int = opts.length()
    // Final argv: ["config", "device", "add", "--project", P, NAME, DEV, "disk",
    //             "source=...", "path=...", opts...]
    mut args: [string] = new [string](10 + on)
    args[0] = "config"
    args[1] = "device"
    args[2] = "add"
    args[3] = "--project"
    args[4] = project
    args[5] = name
    args[6] = dev
    args[7] = "disk"
    args[8] = "source=" ++ src
    args[9] = "path=" ++ dst
    mut i: int = 0
    while i < on
        args[10 + i] = opts[i]
        i = i + 1
    end while
    return run_incus(args)
end device_add_disk_opts_inner
```

(Two functions because reef doesn't allow shadowing — the inner does the work, the outer is the public surface.)

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/incus.reef
hg commit -m "incus: add device_add_disk_opts for shift/readonly disk devices"
```

---

## Task 10: `hermes` module skeleton + pure helpers

**Files:**
- Create: `src/hermes.reef`
- Test: `tests/test_hermes_paths.reef`

- [ ] **Step 1: Write the failing test**

Create `tests/test_hermes_paths.reef`:

```reef
import hermes
import test.framework

proc main()
    let runner = new framework.TestRunner()

    runner.assert_eq_string(
        hermes.state_dir_for("/home/ctusa", "isurus"),
        "/home/ctusa/.local/share/repoman/hermes/isurus",
        "state_dir_for layout"
    )

    let seed = hermes.default_seed_list()
    runner.assert_eq_int(seed.length(), 8, "default seed list size = 8")
    runner.assert_eq_string(seed[0], ".env",          "first entry .env")
    runner.assert_eq_string(seed[1], "config.yaml",   "second config.yaml")
    runner.assert_eq_string(seed[2], "SOUL.md",       "third SOUL.md")
    runner.assert_eq_string(seed[3], "skills/",       "fourth skills/")
    runner.assert_eq_string(seed[4], "hooks/",        "fifth hooks/")
    runner.assert_eq_string(seed[5], "hermes-agent/", "sixth hermes-agent/")
    runner.assert_eq_string(seed[6], "node/",         "seventh node/")
    runner.assert_eq_string(seed[7], "bin/",          "eighth bin/")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

```bash
reefc run tests/test_hermes_paths.reef
```

Expected: compile error — module `hermes` not found.

- [ ] **Step 3: Create the hermes module skeleton**

Create `src/hermes.reef`:

```reef
module hermes

import core.str
import paths

export
    fn state_dir_for(home_dir: string, container_name: string): string
    fn default_seed_list(): [string]
    fn classify_seed_entry(name: string): int
end export

// Layout under ~/.local/share/repoman/hermes/<container-name>/
fn state_dir_for(home_dir: string, container_name: string): string
    let base: string = paths.join(home_dir, ".local/share/repoman/hermes")
    return paths.join(base, container_name)
end state_dir_for

// Default selective-seed list: what to copy/symlink from the host's
// ~/.hermes/ into a per-container data dir. Per-instance state
// (sessions/, memories/, state.db, etc.) is *not* in this list.
fn default_seed_list(): [string]
    return [
        ".env",
        "config.yaml",
        "SOUL.md",
        "skills/",
        "hooks/",
        "hermes-agent/",
        "node/",
        "bin/"
    ]
end default_seed_list

// Constants exposed to the applier so it knows whether to copy or symlink
// each seed entry.
export
    fn SEED_KIND_COPY(): int
    fn SEED_KIND_SYMLINK(): int
end export

fn SEED_KIND_COPY(): int
    return 1
end SEED_KIND_COPY

fn SEED_KIND_SYMLINK(): int
    return 2
end SEED_KIND_SYMLINK

// Classify a seed entry: runtime dirs (hermes-agent/, node/, bin/) are
// symlinks; everything else is a copy. Trailing-slash convention from
// default_seed_list() is honored.
fn classify_seed_entry(name: string): int
    if name == "hermes-agent/" or name == "node/" or name == "bin/"
        return SEED_KIND_SYMLINK()
    end if
    return SEED_KIND_COPY()
end classify_seed_entry

end module
```

- [ ] **Step 4: Run the test**

```bash
reefc run tests/test_hermes_paths.reef
```

Expected: all 9 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add src/hermes.reef tests/test_hermes_paths.reef
hg commit -m "hermes: module skeleton — state_dir_for, default_seed_list, classify_seed_entry"
```

---

## Task 11: `hermes.classify_seed_entry` test

Already implemented in Task 10; this task adds the dedicated unit test for the partition logic.

**Files:**
- Test: `tests/test_hermes_classify.reef`

- [ ] **Step 1: Write the test**

Create `tests/test_hermes_classify.reef`:

```reef
import hermes
import test.framework

proc main()
    let runner = new framework.TestRunner()

    let copy = hermes.SEED_KIND_COPY()
    let link = hermes.SEED_KIND_SYMLINK()

    // Runtime directories → symlink
    runner.assert_eq_int(hermes.classify_seed_entry("hermes-agent/"), link, "hermes-agent/ symlink")
    runner.assert_eq_int(hermes.classify_seed_entry("node/"),         link, "node/ symlink")
    runner.assert_eq_int(hermes.classify_seed_entry("bin/"),          link, "bin/ symlink")

    // Credentials/config/customizations → copy
    runner.assert_eq_int(hermes.classify_seed_entry(".env"),          copy, ".env copy")
    runner.assert_eq_int(hermes.classify_seed_entry("config.yaml"),   copy, "config.yaml copy")
    runner.assert_eq_int(hermes.classify_seed_entry("SOUL.md"),       copy, "SOUL.md copy")
    runner.assert_eq_int(hermes.classify_seed_entry("skills/"),       copy, "skills/ copy (user data, not runtime)")
    runner.assert_eq_int(hermes.classify_seed_entry("hooks/"),        copy, "hooks/ copy")

    // Unknown entries → conservative default (copy)
    runner.assert_eq_int(hermes.classify_seed_entry("custom_thing"),  copy, "unknown defaults to copy")

    runner.report()
end main
```

- [ ] **Step 2: Run the test**

```bash
reefc run tests/test_hermes_classify.reef
```

Expected: all 9 assertions pass.

- [ ] **Step 3: Commit**

```bash
hg add tests/test_hermes_classify.reef
hg commit -m "hermes: classify_seed_entry — explicit copy/symlink partition test"
```

---

## Task 12: `hermes.seed_data_dir` (effectful copy + symlink)

Given a source dir (e.g., `/home/ctusa/.hermes`), a destination dir (e.g., `/home/ctusa/.local/share/repoman/hermes/isurus`), and a seed list, create the destination if missing, then for each entry: if `classify_seed_entry` is COPY, recursively copy; if SYMLINK, create a symlink pointing back to the source path.

**Files:**
- Modify: `src/hermes.reef`

- [ ] **Step 1: Add to export block**

```reef
    fn seed_data_dir(source: string, dest: string, seed: [string]): rg.Result[bool, string]
```

(Re-add after the SEED_KIND_* exports.)

- [ ] **Step 2: Add imports needed**

At the top of `src/hermes.reef`, add:

```reef
import core.result_generic as rg
import core.convert as convert
import io.dir as iodir
import sys.process as p
```

- [ ] **Step 3: Implement seed_data_dir**

Just before `end module`, add:

```reef
// Strip a trailing slash from a string ("hermes-agent/" → "hermes-agent").
// Used to normalize seed-list entries before paths.join.
fn strip_trailing_slash(s: string): string
    let n: int = str.length(s)
    if n > 0 and s[n - 1] == '/'
        return str.substring(s, 0, n - 1)
    end if
    return s
end strip_trailing_slash

// Recursively copy `src` to `dst`. We don't have a built-in recursive copy
// in the reef stdlib, so we shell out to `cp -a`. argv-list spawn — never
// shell — so user-supplied paths can't escape.
fn cp_recursive(src: string, dst: string): bool
    let pid: int = p.process_spawn("cp", ["-a", src, dst])
    if pid < 0
        return false
    end if
    return p.process_wait(pid) == 0
end cp_recursive

// Create a symlink at `link` pointing to `target` (absolute path).
fn make_symlink(target: string, link: string): bool
    let pid: int = p.process_spawn("ln", ["-sfn", target, link])
    if pid < 0
        return false
    end if
    return p.process_wait(pid) == 0
end make_symlink

// Selectively seed `source` into `dest` per the seed list.
// Idempotent for COPY entries (cp -a overwrites); idempotent for
// SYMLINK entries (ln -sfn replaces existing links).
// Returns Err on the first failure with a message naming the offending entry.
fn seed_data_dir(source: string, dest: string, seed: [string]): rg.Result[bool, string]
    if not iodir.dir_exists(source)
        return @Result[bool, string].Err("hermes source dir not found: " ++ source)
    end if
    if not iodir.create_dir_all(dest)
        return @Result[bool, string].Err("cannot create dest dir: " ++ dest)
    end if

    let n: int = seed.length()
    mut i: int = 0
    while i < n
        let entry: string = seed[i]
        let normalized: string = strip_trailing_slash(entry)
        let src_path: string = paths.join(source, normalized)
        let dst_path: string = paths.join(dest, normalized)
        let kind: int = classify_seed_entry(entry)

        if kind == SEED_KIND_COPY()
            if not cp_recursive(src_path, dst_path)
                return @Result[bool, string].Err("copy failed: " ++ entry)
            end if
        else
            if not make_symlink(src_path, dst_path)
                return @Result[bool, string].Err("symlink failed: " ++ entry)
            end if
        end if
        i = i + 1
    end while
    return @Result[bool, string].Ok(true)
end seed_data_dir
```

- [ ] **Step 4: Build to verify it compiles**

```bash
make build
```

Expected: clean build.

- [ ] **Step 5: Smoke-test seed_data_dir**

This function is effectful (touches the filesystem and forks `cp`/`ln`), so we exercise it via a manual smoke run rather than a unit test. Create `/tmp/hermes-smoke.sh`:

```bash
#!/bin/bash
set -e
SRC=/tmp/hermes-smoke-src
DST=/tmp/hermes-smoke-dst
rm -rf $SRC $DST
mkdir -p $SRC/skills $SRC/hooks $SRC/hermes-agent
echo 'KEY=secret' > $SRC/.env
echo 'model: foo' > $SRC/config.yaml
echo 'agent runtime' > $SRC/hermes-agent/index.js
echo 'a skill' > $SRC/skills/skill1.md

# Use a tiny reef wrapper to call hermes.seed_data_dir; or hand-trace by
# running the equivalent ops:
mkdir -p $DST
cp -a $SRC/.env $DST/.env
cp -a $SRC/config.yaml $DST/config.yaml
cp -a $SRC/skills $DST/skills
cp -a $SRC/hooks $DST/hooks 2>/dev/null || true
ln -sfn $SRC/hermes-agent $DST/hermes-agent
ln -sfn $SRC/node $DST/node 2>/dev/null || true  # may not exist
ln -sfn $SRC/bin $DST/bin 2>/dev/null || true

ls -la $DST
[[ -L $DST/hermes-agent ]] && echo "OK: hermes-agent is a symlink"
[[ -f $DST/.env ]] && echo "OK: .env is a regular file"
echo "smoke OK"
```

```bash
bash /tmp/hermes-smoke.sh
```

Expected: shows `OK: hermes-agent is a symlink`, `OK: .env is a regular file`. Confirms the model.

- [ ] **Step 6: Commit**

```bash
hg add src/hermes.reef
hg commit -m "hermes: seed_data_dir — selective copy + symlink from host ~/.hermes"
```

---

## Task 13: `hermes.purge_data_dir`

**Files:**
- Modify: `src/hermes.reef`

- [ ] **Step 1: Add to export block**

```reef
    fn purge_data_dir(dest: string): rg.Result[bool, string]
```

- [ ] **Step 2: Implement**

```reef
// Recursively delete the per-container hermes data dir. Loud; only called
// from `repoman remove --purge-hermes`.
fn purge_data_dir(dest: string): rg.Result[bool, string]
    if not iodir.dir_exists(dest)
        return @Result[bool, string].Ok(true)  // nothing to do
    end if
    let pid: int = p.process_spawn("rm", ["-rf", dest])
    if pid < 0
        return @Result[bool, string].Err("failed to spawn rm")
    end if
    let exit: int = p.process_wait(pid)
    if exit == 0
        return @Result[bool, string].Ok(true)
    end if
    return @Result[bool, string].Err("rm -rf exited " ++ convert.to_string(exit))
end purge_data_dir
```

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/hermes.reef
hg commit -m "hermes: purge_data_dir for --purge-hermes flow"
```

---

## Task 14: `setup` module skeleton + `Environment` struct

**Files:**
- Create: `src/setup.reef`

- [ ] **Step 1: Create the module skeleton**

```reef
module setup

import core.str
import core.result_generic as rg
import core.convert as convert
import io.console as console
import io.file as iofile
import io.dir as iodir
import sys.env
import sys.process as p
import sys.fd as fd
import paths
import incus
import hermes
import config

export
    type Environment
    fn detect_environment(home_dir: string): Environment
    fn detect_host_lan_ip(): string
    fn render_llm_share_template(host_lan_ip: string, user: string): string
    type Stage
    fn plan_stages(env: Environment, with_llm: bool): [Stage]
    fn cmd_setup(argv: [string]): int
end export

// Snapshot of the host state that `setup` cares about.
type Environment = struct
    home_dir:             string
    user:                 string
    host_lan_ip:          string         // empty if br0 not found
    incus_reachable:      bool
    repoman_project_present: bool
    claude_share_present: bool
    ollama_binary:        string         // path; empty if not installed
    ollama_lan_ok:        bool           // listening on LAN, not just loopback
    hermes_binary:        string         // path; empty if not installed
    hermes_data_present:  bool           // ~/.hermes exists
end Environment

// Stage is a planned action with a description for the user.
type Stage = struct
    id:          string                  // "incus_project", "llm_share_profile", etc.
    description: string                  // user-facing
    is_change:   bool                    // false → no-op, just inform
end Stage

// (function bodies follow in subsequent tasks)

fn detect_environment(home_dir: string): Environment
    return Environment {
        home_dir:             home_dir,
        user:                 "",
        host_lan_ip:          "",
        incus_reachable:      false,
        repoman_project_present: false,
        claude_share_present: false,
        ollama_binary:        "",
        ollama_lan_ok:        false,
        hermes_binary:        "",
        hermes_data_present:  false
    }
end detect_environment

fn detect_host_lan_ip(): string
    return ""
end detect_host_lan_ip

fn render_llm_share_template(host_lan_ip: string, user: string): string
    return ""
end render_llm_share_template

fn plan_stages(env: Environment, with_llm: bool): [Stage]
    return new [Stage](0)
end plan_stages

fn cmd_setup(argv: [string]): int
    return 0
end cmd_setup

end module
```

- [ ] **Step 2: Build to verify the skeleton compiles**

```bash
make build
```

Expected: clean build. (Functions are stubs; later tasks fill them.)

- [ ] **Step 3: Commit**

```bash
hg add src/setup.reef
hg commit -m "setup: module skeleton — Environment, Stage, stubbed entry points"
```

---

## Task 15: `setup.detect_host_lan_ip` (parse `ip -4 addr show br0`)

Run `ip -4 addr show br0`, parse the first `inet X.Y.Z.W/N` line, return `X.Y.Z.W`. Empty string if anything fails.

**Files:**
- Modify: `src/setup.reef`

- [ ] **Step 1: Replace the stub with a real implementation**

In `src/setup.reef`, replace the body of `detect_host_lan_ip`:

```reef
fn detect_host_lan_ip(): string
    let cap = incus.process_run_capture("ip", ["-4", "addr", "show", "br0"])
    if cap.exit_code != 0
        return ""
    end if
    // Look for the first occurrence of "inet " and grab the IPv4 token after it
    // until the next slash. `cap.stdout` is small, hand-roll the scan.
    let s: string = cap.stdout
    let n: int = str.length(s)
    let needle: string = "inet "
    let needle_len: int = 5
    mut i: int = 0
    while i + needle_len <= n
        if str.substring(s, i, needle_len) == needle
            let start: int = i + needle_len
            mut end_idx: int = start
            while end_idx < n and s[end_idx] != '/' and s[end_idx] != ' '
                end_idx = end_idx + 1
            end while
            return str.substring(s, start, end_idx - start)
        end if
        i = i + 1
    end while
    return ""
end detect_host_lan_ip
```

(Note: `incus.process_run_capture` is currently private to that module. To call it from `setup`, either export it from `incus` (preferred — small, no leakage of intent) or replicate the capture helper here. **Choose: export** — change `src/incus.reef` to add `process_run_capture` to its `export` block, with the existing `CaptureResult` type also exported.)

- [ ] **Step 2: Export from incus**

In `src/incus.reef`, modify the `export` block to add:

```reef
    type CaptureResult
    fn process_run_capture(program: string, args: [string]): CaptureResult
```

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Smoke-test detect_host_lan_ip**

There's no clean unit test for this (depends on the host's network), so smoke-test from a tiny throwaway program.

```bash
cat > /tmp/test_lanip.reef <<'EOF'
import setup
import io.console as console
proc main()
    let ip = setup.detect_host_lan_ip()
    console.print("br0 IP: [" ++ ip ++ "]\n")
end main
EOF
reefc run /tmp/test_lanip.reef
```

Expected: prints something like `br0 IP: [192.168.168.42]`. If your host has no `br0`, prints `br0 IP: []` — note this for the spec's open question O-4.

- [ ] **Step 5: Commit**

```bash
hg add src/setup.reef src/incus.reef
hg commit -m "setup: detect_host_lan_ip via ip -4 addr show br0; export incus.process_run_capture"
```

---

## Task 16: `setup.render_llm_share_template`

Pure function: substitute `{HOST_LAN_IP}` and `{USER}` in the embedded template. Test with a golden string.

**Files:**
- Modify: `src/setup.reef`
- Test: `tests/test_setup_template.reef`

- [ ] **Step 1: Write the failing test**

Create `tests/test_setup_template.reef`:

```reef
import setup
import test.framework

proc main()
    let runner = new framework.TestRunner()

    let yaml = setup.render_llm_share_template("192.168.168.42", "ctusa")

    runner.assert_contains_string(yaml, "name: llm-share",                "name line")
    runner.assert_contains_string(yaml, "OLLAMA_HOST",                    "ollama env key")
    runner.assert_contains_string(yaml, "http://192.168.168.42:11434",    "lan ip substitution")
    runner.assert_contains_string(yaml, "/usr/local/bin/ollama",          "ollama bin path")
    runner.assert_contains_string(yaml, "/home/ctusa/.ollama",            "user path substitution")
    runner.assert_contains_string(yaml, "shift: \"true\"",                "shift opt set")
    runner.assert_contains_string(yaml, "readonly: \"true\"",             "readonly opt on bin")

    // No placeholders should remain
    runner.assert_eq_bool(false, setup.template_contains_placeholder(yaml), "no {HOST_LAN_IP} or {USER} left")

    runner.report()
end main
```

- [ ] **Step 2: Run to verify it fails**

```bash
reefc run tests/test_setup_template.reef
```

Expected: fails — function returns empty string.

- [ ] **Step 3: Implement**

In `src/setup.reef`, add a constant template + replace the stub body. Add to the export block:

```reef
    fn template_contains_placeholder(s: string): bool
```

Then replace `render_llm_share_template` and add the helper:

```reef
fn render_llm_share_template(host_lan_ip: string, user: string): string
    let template: string =
        "name: llm-share\n" ++
        "description: |\n" ++
        "  Local LLM client tools (ollama client + hermes runtime) and host-daemon wiring.\n" ++
        "  Created by repoman setup; do not hand-edit (changes will be overwritten).\n" ++
        "config:\n" ++
        "  environment.OLLAMA_HOST: \"http://{HOST_LAN_IP}:11434\"\n" ++
        "devices:\n" ++
        "  ollama-bin:\n" ++
        "    type: disk\n" ++
        "    source: /usr/local/bin/ollama\n" ++
        "    path: /usr/local/bin/ollama\n" ++
        "    readonly: \"true\"\n" ++
        "  ollama-state:\n" ++
        "    type: disk\n" ++
        "    source: /home/{USER}/.ollama\n" ++
        "    path: /home/{USER}/.ollama\n" ++
        "    shift: \"true\"\n"
    let s1: string = str.replace(template, "{HOST_LAN_IP}", host_lan_ip)
    let s2: string = str.replace(s1,       "{USER}",        user)
    return s2
end render_llm_share_template

fn template_contains_placeholder(s: string): bool
    return str.contains(s, "{HOST_LAN_IP}") or str.contains(s, "{USER}")
end template_contains_placeholder
```

(`core.str.replace(s, old, new)` is the global-replace function in the reef stdlib — verified at `~/reef-lang-0.5.20-source/reef-stdlib/core/str.reef:65`.)

- [ ] **Step 4: Run the test to verify it passes**

```bash
reefc run tests/test_setup_template.reef
```

Expected: all 8 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add src/setup.reef tests/test_setup_template.reef
hg commit -m "setup: render_llm_share_template with {HOST_LAN_IP}/{USER} substitution"
```

---

## Task 17: `setup.detect_environment` (full env probe)

Populate every field of `Environment`: HOME, USER, br0 IP, incus reachability, project/profile presence, ollama/hermes binaries, ollama LAN listening status.

**Files:**
- Modify: `src/setup.reef`

- [ ] **Step 1: Replace the stub**

```reef
// Probe whether a binary is in PATH by running `command -v <name>`.
// Returns the path on success, empty string on failure.
fn which_binary(name: string): string
    let cap = incus.process_run_capture("sh", ["-c", "command -v " ++ name])
    if cap.exit_code != 0
        return ""
    end if
    return str.trim_ws(cap.stdout)
end which_binary

// Returns true if anything is listening on the given TCP host:port.
// Uses /bin/sh + getent + bash's TCP redirection? Simpler: try
// `curl -sS -o /dev/null --connect-timeout 1 http://<ip>:11434`
// and check the exit. curl is in claude-share's image baseline.
fn ollama_listening_at(host: string): bool
    let url: string = "http://" ++ host ++ ":11434"
    let pid: int = p.process_spawn("curl", [
        "-sS", "-o", "/dev/null", "--connect-timeout", "1", url
    ])
    if pid < 0
        return false
    end if
    return p.process_wait(pid) == 0
end ollama_listening_at

fn detect_environment(home_dir: string): Environment
    let user: string = env.get_env_or("USER", "")
    let lan_ip: string = detect_host_lan_ip()

    // incus reachable?
    let incus_pid: int = incus.process_run_silent("incus", ["version"])
    let incus_ok: bool = p.process_wait(incus_pid) == 0

    // repoman project + claude-share profile (only if incus is up)
    mut project_ok: bool = false
    mut claude_share_ok: bool = false
    if incus_ok
        let pe = incus.project_ensure_check_only("repoman")  // helper added below if needed
        project_ok = rg.is_ok(pe) and rg.unwrap_ok(pe)
        let cs = incus.profile_exists("default", "claude-share")
        claude_share_ok = rg.is_ok(cs) and rg.unwrap_ok(cs)
    end if

    let ollama_path: string = which_binary("ollama")
    let hermes_path: string = which_binary("hermes")
    let hermes_data_dir: string = paths.join(home_dir, ".hermes")
    let hermes_data_ok: bool = iodir.dir_exists(hermes_data_dir)

    mut ollama_lan_ok: bool = false
    if str.length(lan_ip) > 0
        ollama_lan_ok = ollama_listening_at(lan_ip)
    end if

    return Environment {
        home_dir:             home_dir,
        user:                 user,
        host_lan_ip:          lan_ip,
        incus_reachable:      incus_ok,
        repoman_project_present: project_ok,
        claude_share_present: claude_share_ok,
        ollama_binary:        ollama_path,
        ollama_lan_ok:        ollama_lan_ok,
        hermes_binary:        hermes_path,
        hermes_data_present:  hermes_data_ok
    }
end detect_environment
```

(`incus.project_ensure_check_only` doesn't yet exist — that's what the helper-or-existing-function comment is about. Take the existing `project_ensure(project, verbose)` and split out a check-only path: rename or add a sibling `fn project_present(project): rg.Result[bool, string]` that runs `incus project show` silently and reports existence without creating. **Add this small helper** in `src/incus.reef` and export it; keep `project_ensure` for the create path.)

- [ ] **Step 2: Add `incus.project_present`**

In `src/incus.reef`, after `project_ensure`, add:

```reef
fn project_present(project: string): rg.Result[bool, string]
    let pid: int = process_run_silent("incus", ["project", "show", project])
    if pid < 0
        return @Result[bool, string].Err("failed to spawn 'incus project show'")
    end if
    let exit: int = p.process_wait(pid)
    if exit == 0
        return @Result[bool, string].Ok(true)
    end if
    return @Result[bool, string].Ok(false)
end project_present
```

And export it. Update the `detect_environment` body to call `incus.project_present("repoman")` instead of the placeholder `project_ensure_check_only`.

Also export `incus.process_run_silent` for use in `setup` (same pattern as `process_run_capture`):

```reef
    fn process_run_silent(program: string, args: [string]): int
```

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Smoke-test detect_environment**

```bash
cat > /tmp/test_detect.reef <<'EOF'
import setup
import sys.env
import io.console as console
proc main()
    let h = env.get_env_or("HOME", "")
    let e = setup.detect_environment(h)
    console.print("home: " ++ e.home_dir ++ "\n")
    console.print("user: " ++ e.user ++ "\n")
    console.print("br0 IP: [" ++ e.host_lan_ip ++ "]\n")
    console.print("incus reachable: " ++ (if e.incus_reachable then "yes" else "no") ++ "\n")
    console.print("repoman project: " ++ (if e.repoman_project_present then "yes" else "no") ++ "\n")
    console.print("claude-share: " ++ (if e.claude_share_present then "yes" else "no") ++ "\n")
    console.print("ollama: [" ++ e.ollama_binary ++ "] lan_ok=" ++ (if e.ollama_lan_ok then "y" else "n") ++ "\n")
    console.print("hermes: [" ++ e.hermes_binary ++ "] data=" ++ (if e.hermes_data_present then "y" else "n") ++ "\n")
end main
EOF
reefc run /tmp/test_detect.reef
```

Expected: each field printed with a sensible value matching the host's actual state.

- [ ] **Step 5: Commit**

```bash
hg add src/setup.reef src/incus.reef
hg commit -m "setup: detect_environment + incus.project_present + exported probes"
```

---

## Task 18: `setup.plan_stages` (pure)

Given an `Environment` and `with_llm: bool`, return the ordered list of stages with their `is_change`/no-op status.

**Files:**
- Modify: `src/setup.reef`
- Test: `tests/test_setup_planner.reef`

- [ ] **Step 1: Write the failing test**

Create `tests/test_setup_planner.reef`:

```reef
import setup
import test.framework

proc main()
    let runner = new framework.TestRunner()

    // Fully fresh host: nothing exists, with_llm = true
    let fresh = setup.Environment {
        home_dir: "/home/ctusa", user: "ctusa",
        host_lan_ip: "192.168.168.42",
        incus_reachable: true,
        repoman_project_present: false, claude_share_present: false,
        ollama_binary: "/usr/local/bin/ollama", ollama_lan_ok: true,
        hermes_binary: "/home/ctusa/.local/bin/hermes", hermes_data_present: true
    }
    let stages_fresh = setup.plan_stages(fresh, true)

    // Expect 4 actionable stages: incus_project, claude_share_check, llm_share_profile, registry_defaults
    runner.assert_eq_int(stages_fresh.length(), 4, "fresh + with_llm = 4 stages")
    runner.assert_eq_string(stages_fresh[0].id, "incus_project", "stage 0 = incus_project")
    runner.assert_eq_bool(stages_fresh[0].is_change, true, "incus_project will change")
    runner.assert_eq_string(stages_fresh[2].id, "llm_share_profile", "stage 2 = llm_share_profile")

    // Already set up host, no LLM: just verify
    let setup_done = setup.Environment {
        home_dir: "/home/ctusa", user: "ctusa",
        host_lan_ip: "192.168.168.42",
        incus_reachable: true,
        repoman_project_present: true, claude_share_present: true,
        ollama_binary: "", ollama_lan_ok: false,
        hermes_binary: "", hermes_data_present: false
    }
    let stages_done = setup.plan_stages(setup_done, false)
    runner.assert_eq_int(stages_done.length(), 3, "done host + no_llm = 3 stages (no llm_share)")
    let any_change: bool = stages_done[0].is_change or stages_done[1].is_change or stages_done[2].is_change
    runner.assert_eq_bool(any_change, false, "all stages no-op when host is set up")

    // Want LLM but no LAN IP detected → llm_share stage flagged is_change=false with explanatory description
    let no_br0 = setup.Environment {
        home_dir: "/home/ctusa", user: "ctusa",
        host_lan_ip: "",
        incus_reachable: true,
        repoman_project_present: true, claude_share_present: true,
        ollama_binary: "/usr/local/bin/ollama", ollama_lan_ok: false,
        hermes_binary: "/home/ctusa/.local/bin/hermes", hermes_data_present: true
    }
    let stages_no_br0 = setup.plan_stages(no_br0, true)
    runner.assert_eq_int(stages_no_br0.length(), 4, "with_llm but no br0 still plans 4 stages")
    // The llm_share stage is index 2; it should NOT mark itself is_change=true without an IP
    runner.assert_eq_bool(stages_no_br0[2].is_change, false, "llm_share is_change=false with no br0 IP")

    runner.report()
end main
```

- [ ] **Step 2: Run to verify it fails**

```bash
reefc run tests/test_setup_planner.reef
```

Expected: assertion failures.

- [ ] **Step 3: Implement plan_stages**

```reef
fn plan_stages(env: Environment, with_llm: bool): [Stage]
    mut count: int = 3                      // incus_project, claude_share_check, registry_defaults
    if with_llm
        count = 4                            // + llm_share_profile (between claude_share and registry)
    end if

    mut stages: [Stage] = new [Stage](count)

    stages[0] = Stage {
        id:          "incus_project",
        description: "ensure Incus project 'repoman' exists",
        is_change:   not env.repoman_project_present
    }
    stages[1] = Stage {
        id:          "claude_share_check",
        description: "verify 'claude-share' profile exists in default project",
        is_change:   false                  // we never modify claude-share; failure→exit
    }
    if with_llm
        let llm_change: bool = (str.length(env.host_lan_ip) > 0) and env.ollama_lan_ok
        stages[2] = Stage {
            id:          "llm_share_profile",
            description: "create/refresh 'llm-share' profile in repoman project",
            is_change:   llm_change
        }
        stages[3] = Stage {
            id:          "registry_defaults",
            description: "write registry defaults (schema 2, llm.enabled, profiles list)",
            is_change:   true
        }
    else
        stages[2] = Stage {
            id:          "registry_defaults",
            description: "write registry defaults (schema 2, llm.enabled=false)",
            is_change:   true
        }
    end if

    return stages
end plan_stages
```

- [ ] **Step 4: Run the test to verify it passes**

```bash
reefc run tests/test_setup_planner.reef
```

Expected: all 8 assertions pass.

- [ ] **Step 5: Commit**

```bash
hg add src/setup.reef tests/test_setup_planner.reef
hg commit -m "setup: plan_stages — pure stage planner with idempotency awareness"
```

---

## Task 19: `setup.apply_stage` (per-stage applier)

Wire the planned stages to actual effects.

**Files:**
- Modify: `src/setup.reef`

- [ ] **Step 1: Add to export block**

```reef
    fn apply_stage(stage: Stage, env: Environment, reg: config.Registry): rg.Result[config.Registry, string]
```

- [ ] **Step 2: Implement**

Add at the bottom of the module before `end module`:

```reef
fn apply_stage(stage: Stage, env: Environment, reg: config.Registry): rg.Result[config.Registry, string]
    if stage.id == "incus_project"
        if env.repoman_project_present
            return @Result[config.Registry, string].Ok(reg)  // no-op
        end if
        let r = incus.project_ensure("repoman", false)
        if rg.is_err(r)
            return @Result[config.Registry, string].Err(rg.unwrap_err(r))
        end if
        return @Result[config.Registry, string].Ok(reg)
    end if

    if stage.id == "claude_share_check"
        if env.claude_share_present
            return @Result[config.Registry, string].Ok(reg)
        end if
        return @Result[config.Registry, string].Err(
            "claude-share profile not found.\n" ++
            "Create it with:\n" ++
            "  incus profile create claude-share\n" ++
            "  incus profile edit claude-share  # add your bind-mounts (~/.claude, ~/.local/bin, ...)"
        )
    end if

    if stage.id == "llm_share_profile"
        if str.length(env.host_lan_ip) == 0
            return @Result[config.Registry, string].Err(
                "no br0 IP detected — cannot wire llm-share without a stable LAN address.\n" ++
                "Set up br0 first, then re-run 'repoman setup --with-llm'."
            )
        end if
        if not env.ollama_lan_ok
            return @Result[config.Registry, string].Err(
                "ollama daemon not reachable on " ++ env.host_lan_ip ++ ":11434.\n" ++
                "Add OLLAMA_HOST=" ++ env.host_lan_ip ++ ":11434 to your systemd unit and restart ollama."
            )
        end if
        let yaml: string = render_llm_share_template(env.host_lan_ip, env.user)
        let r = incus.profile_create_or_edit("repoman", "llm-share", yaml)
        if rg.is_err(r)
            return @Result[config.Registry, string].Err(rg.unwrap_err(r))
        end if
        return @Result[config.Registry, string].Ok(reg)
    end if

    if stage.id == "registry_defaults"
        // Compute desired LlmDefaults
        let want_enabled: bool = (str.length(env.host_lan_ip) > 0) and env.ollama_lan_ok and (str.length(env.hermes_binary) > 0)
        let new_llm = config.LlmDefaults {
            enabled:        want_enabled,
            hermes_default: false,
            ollama_url:     "http://" ++ env.host_lan_ip ++ ":11434",
            hermes_seed:    hermes.default_seed_list()
        }
        // Compute desired profiles list
        mut new_profiles: [string] = ["default", "claude-share"]
        if want_enabled
            new_profiles = ["default", "claude-share", "llm-share"]
        end if
        let new_defaults = config.Defaults {
            repos_root:    reg.defaults.repos_root,
            backup_root:   reg.defaults.backup_root,
            logdir:        reg.defaults.logdir,
            incus_project: reg.defaults.incus_project,
            default_image: reg.defaults.default_image,
            profiles:      new_profiles,
            llm:           new_llm
        }
        let new_reg = config.Registry {
            schema:   2,
            output:   reg.output,
            defaults: new_defaults,
            projects: reg.projects
        }
        return @Result[config.Registry, string].Ok(new_reg)
    end if

    return @Result[config.Registry, string].Err("unknown stage id: " ++ stage.id)
end apply_stage
```

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/setup.reef
hg commit -m "setup: apply_stage — per-stage applier composing incus + config writes"
```

---

## Task 20: `cli.cmd_setup` wiring

**Files:**
- Modify: `src/cli.reef`

- [ ] **Step 1: Add cmd_setup to the export block**

In `src/cli.reef`'s export block, add:

```reef
    fn cmd_setup(argv: [string]): int
```

- [ ] **Step 2: Add the import**

Near the top of `cli.reef`, add:

```reef
import setup
```

- [ ] **Step 3: Implement cmd_setup**

After `cmd_shell` (line ~752) and before `version_string`, add:

```reef
fn cmd_setup(argv: [string]): int
    let parser: flag.FlagParser = flag.flag_parser_from(argv)
    flag.application(parser, "repoman setup")
    flag.description(parser, "First-time host bootstrap: incus project, profiles, registry")
    let _f1 = flag.bool_flag(parser, "non-interactive", '\0', false, "accept all defaults without prompting")
    let _f2 = flag.bool_flag(parser, "with-llm",        '\0', false, "include the LLM stack (llm-share profile, ollama wiring)")
    let _f3 = flag.bool_flag(parser, "without-llm",     '\0', false, "skip the LLM stack")

    if not flag.parse(parser)
        console.printErr("repoman: error: " ++ flag.error(parser))
        return 2
    end if

    let non_interactive: bool = flag.get_bool(parser, "non-interactive")
    let with_llm_flag: bool = flag.get_bool(parser, "with-llm")
    let without_llm_flag: bool = flag.get_bool(parser, "without-llm")
    if with_llm_flag and without_llm_flag
        console.printErr("repoman: error: --with-llm and --without-llm are mutually exclusive")
        return 2
    end if

    let home: string = env.get_env_or("HOME", "")
    if str.length(home) == 0
        console.printErr("repoman: error: HOME is not set")
        return 3
    end if

    let env_snap = setup.detect_environment(home)
    if not env_snap.incus_reachable
        console.printErr("repoman: error: 'incus' is not installed or not on PATH")
        return 3
    end if

    // Decide LLM inclusion
    mut with_llm: bool = false
    if with_llm_flag
        with_llm = true
    else if without_llm_flag
        with_llm = false
    else if non_interactive
        with_llm = false                // safe default in non-interactive mode
    else
        // Interactive prompt
        console.print("Include local LLM stack (ollama + hermes wiring)? [y/N] ")
        let answer: string = console.readLine()
        let trimmed: string = str.trim_ws(answer)
        with_llm = trimmed == "y" or trimmed == "Y" or trimmed == "yes"
    end if

    // Plan & display
    let stages = setup.plan_stages(env_snap, with_llm)
    console.print("\nrepoman setup plan:\n")
    let n: int = stages.length()
    mut i: int = 0
    while i < n
        let st = stages[i]
        let marker: string = if st.is_change then " * " else "   "
        console.print(marker ++ "[" ++ st.id ++ "] " ++ st.description ++ "\n")
        i = i + 1
    end while
    console.print("\n* = will change; otherwise no-op\n\n")

    if not non_interactive
        console.print("proceed? [Y/n] ")
        let answer: string = console.readLine()
        let trimmed: string = str.trim_ws(answer)
        if trimmed == "n" or trimmed == "N" or trimmed == "no"
            console.print("aborted\n")
            return 4
        end if
    end if

    // Load registry (or init)
    let reg_r = config.load_or_init(home)
    if rg.is_err(reg_r)
        console.printErr("repoman: error: " ++ rg.unwrap_err(reg_r))
        return 3
    end if
    mut reg: config.Registry = rg.unwrap_ok(reg_r)

    // Apply stages
    mut k: int = 0
    while k < n
        let st = stages[k]
        console.print("==> [" ++ st.id ++ "] " ++ st.description ++ "\n")
        let r = setup.apply_stage(st, env_snap, reg)
        if rg.is_err(r)
            console.printErr("repoman: error: " ++ rg.unwrap_err(r))
            return 1
        end if
        reg = rg.unwrap_ok(r)
        k = k + 1
    end while

    // Persist registry
    let cfg_path: string = config.registry_path(home)
    let saved = config.save(reg, cfg_path)
    if rg.is_err(saved)
        console.printErr("repoman: error: " ++ rg.unwrap_err(saved))
        return 1
    end if

    console.print("\nsetup complete.\n")
    console.print("\n  next: repoman new <name>")
    if reg.defaults.llm.enabled
        console.print("        repoman new <name> --hermes")
    end if
    console.print("        repoman list\n")
    return 0
end cmd_setup
```

- [ ] **Step 4: Wire into the dispatcher**

Find the dispatch function (around `dispatch` near the end of `cli.reef`) and add a `setup` arm. It looks like:

```reef
fn dispatch(argv: [string]): int
    ...
    if cmd == "new"
        return cmd_new(rest)
    end if
    ...
```

Add (alphabetically — between `remove` and `shell`, or wherever fits):

```reef
    if cmd == "setup"
        return cmd_setup(rest)
    end if
```

Also update the help text in the same function to add `setup` to the list of commands.

- [ ] **Step 5: Build and smoke-test**

```bash
make build
./build/repoman setup --without-llm --non-interactive
```

Expected: prints the plan, applies each stage, says "setup complete".

- [ ] **Step 6: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: cmd_setup — interactive host bootstrap with --with-llm/--without-llm"
```

---

## Task 21: `cmd_new --hermes / --no-hermes`

**Files:**
- Modify: `src/cli.reef:30-226` (cmd_new)

- [ ] **Step 1: Add the flags**

In `cmd_new`, after the existing flag definitions (line ~37), add:

```reef
    let _f3 = flag.bool_flag(parser, "hermes",     '\0', false, "provision a per-container hermes data dir (overrides default)")
    let _f4 = flag.bool_flag(parser, "no-hermes",  '\0', false, "skip per-container hermes data dir (overrides default)")
```

- [ ] **Step 2: Resolve `want_hermes`**

After loading the registry (around line ~72) and resolving `verbose`, add:

```reef
    let cli_hermes: bool = flag.get_bool(parser, "hermes")
    let cli_no_hermes: bool = flag.get_bool(parser, "no-hermes")
    if cli_hermes and cli_no_hermes
        console.printErr("repoman: error: --hermes and --no-hermes are mutually exclusive")
        return 2
    end if
    let override_hermes: bool = override_has_hermes_field(override)  // helper added below
    mut want_hermes: bool = reg.defaults.llm.hermes_default
    if cli_hermes
        want_hermes = true
    else if cli_no_hermes
        want_hermes = false
    else if override_hermes
        want_hermes = override_hermes_value(override)
    end if
    if want_hermes and not reg.defaults.llm.enabled
        console.printErr("repoman: error: --hermes requires LLM stack enabled. Run 'repoman setup --with-llm' first.")
        return 3
    end if
```

(Note: this assumes `Override` carries an optional `hermes` field; that's deferred — for v0.3 the override-file `[hermes].enabled` is *not* yet read by `parse_override`. To keep this task self-contained, **simplify**: drop the override branch:

```reef
    let cli_hermes: bool = flag.get_bool(parser, "hermes")
    let cli_no_hermes: bool = flag.get_bool(parser, "no-hermes")
    if cli_hermes and cli_no_hermes
        console.printErr("repoman: error: --hermes and --no-hermes are mutually exclusive")
        return 2
    end if
    mut want_hermes: bool = reg.defaults.llm.hermes_default
    if cli_hermes
        want_hermes = true
    else if cli_no_hermes
        want_hermes = false
    end if
    if want_hermes and not reg.defaults.llm.enabled
        console.printErr("repoman: error: --hermes requires LLM stack enabled. Run 'repoman setup --with-llm' first.")
        return 3
    end if
```

The override-file integration is a v0.4 task. Update the spec's §6.2 "open question" annotation accordingly when committing.)

- [ ] **Step 3: After the existing container restart, seed the hermes dir**

After the `incus.restart` call (around line ~196), before the registry write, add:

```reef
    // Seed per-container hermes data dir + add disk device (opt-in)
    if want_hermes
        let dest: string = hermes.state_dir_for(home, name)
        if iodir.dir_exists(dest)
            log.write("repoman: error: hermes data dir already exists at " ++ dest)
            log.write("hint: repoman remove --purge-hermes " ++ name ++ "  (then retry)")
            return 4
        end if
        let source: string = paths.join(home, ".hermes")
        log.write("==> hermes seed " ++ source ++ " → " ++ dest)
        let sr = hermes.seed_data_dir(source, dest, reg.defaults.llm.hermes_seed)
        if rg.is_err(sr)
            log.write("repoman: error: " ++ rg.unwrap_err(sr))
            return 1
        end if
        let in_path: string = "/home/" ++ env.get_env_or("USER", "") ++ "/.hermes"
        log.write("==> incus device add " ++ name ++ " hermes-state " ++ dest ++ " → " ++ in_path)
        let dr = incus.device_add_disk_opts(reg.defaults.incus_project, name, "hermes-state", dest, in_path, ["shift=true"])
        if rg.is_err(dr)
            log.write("repoman: error: " ++ rg.unwrap_err(dr))
            log.write("hint: repoman remove --purge-hermes " ++ name)
            return 1
        end if
        // Restart again so the new device is mounted
        let rr2 = incus.restart(reg.defaults.incus_project, name)
        if rg.is_err(rr2)
            log.write("repoman: error: " ++ rg.unwrap_err(rr2))
            return 1
        end if
    end if
```

- [ ] **Step 4: Update the new Project literal**

The `new_p` literal (line ~200) needs `hermes: want_hermes`:

```reef
    let new_p: config.Project = config.Project {
        name:      name,
        repo:      repo,
        image:     eff.image,
        profiles:  eff.profiles,
        created:   now,
        last_sync: "",
        backup:    true,
        hermes:    want_hermes
    }
```

- [ ] **Step 5: Add the imports needed by cmd_new**

At the top of `cli.reef`, ensure these imports exist:

```reef
import hermes
import io.dir as iodir
```

(`paths` is already imported; `incus` already; `iofile` already.)

- [ ] **Step 6: Build and smoke**

```bash
make build
```

Expected: clean build. (Smoke test deferred to Task 25.)

- [ ] **Step 7: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: cmd_new --hermes/--no-hermes — seed data dir + add disk device"
```

---

## Task 22: `cmd_remove --purge-hermes`

**Files:**
- Modify: `src/cli.reef:577-669` (cmd_remove)

- [ ] **Step 1: Add the flag**

In `cmd_remove`, alongside the existing flag definitions, add:

```reef
    let _fph = flag.bool_flag(parser, "purge-hermes", '\0', false, "also delete the per-container hermes data dir")
```

- [ ] **Step 2: After successful container delete + registry write, optionally purge the data dir**

Find the block where `cmd_remove` writes the registry after successful container removal. Immediately after the `config.save` returns Ok, add:

```reef
    let purge: bool = flag.get_bool(parser, "purge-hermes")
    if purge
        let dest: string = hermes.state_dir_for(home, name)
        log.write("==> purge hermes data dir: " ++ dest)
        let pr = hermes.purge_data_dir(dest)
        if rg.is_err(pr)
            log.write("repoman: warning: " ++ rg.unwrap_err(pr))
            // Don't fail the overall remove on purge failure — container is gone.
        end if
    end if
```

(If `cmd_remove` doesn't currently expose `home`/`name` at the right scope, hoist them — they are loaded earlier in the function.)

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: cmd_remove --purge-hermes — also delete per-container data dir"
```

---

## Task 23: `cmd_list` and `cmd_status` show hermes flag

**Files:**
- Modify: `src/cli.reef:400-575` (cmd_list, cmd_status_one, cmd_status_all)

- [ ] **Step 1: cmd_list output column**

Find the loop in `cmd_list` that prints each project (around line 440). It currently prints something like:

```
NAME           REPO                 IMAGE                                 PROFILES
isurus         isurus               images:ubuntu/26.04/cloud             default,claude-share
```

Add a `HERMES` column. The exact format depends on the existing print pattern — match it. For example, if rows are produced by `console.print(p.name + "\t" + p.repo + "\t" + ...)`, add `+ "\t" + (if p.hermes then "yes" else "no")`. Read the function to see the exact pattern, then mirror it.

- [ ] **Step 2: cmd_status_one — show hermes line**

In `cmd_status_one`, add a line after the existing project info:

```reef
    console.print("hermes: " ++ (if p.hermes then "yes" else "no") ++ "\n")
    if p.hermes
        let dest: string = hermes.state_dir_for(home, name)
        console.print("  data dir: " ++ dest ++ "\n")
    end if
```

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: list/status show hermes column + data dir"
```

---

## Task 24: README + VISION updates + reef.toml version bump

**Files:**
- Modify: `reef.toml`, `README.md`, `VISION.md`

- [ ] **Step 1: Bump version**

In `reef.toml`, change:

```toml
version = "0.1.0"
```

to:

```toml
version = "0.3.0"
```

- [ ] **Step 2: README — add setup + LLM section**

In `README.md`, add a new section after the existing usage examples:

```markdown
## Setup wizard

First-time host bootstrap (idempotent — safe to re-run):

    repoman setup                     # interactive
    repoman setup --non-interactive   # accept defaults
    repoman setup --with-llm          # include local LLM stack (ollama + hermes)

The wizard creates the Incus project `repoman`, verifies your `claude-share` profile
exists, and (with `--with-llm`) creates an `llm-share` profile that wires containers
to your host's ollama daemon over LAN.

## Local LLM stack

`repoman setup --with-llm` provisions:

- An Incus profile `llm-share` that bind-mounts `/usr/local/bin/ollama` (read-only)
  and `~/.ollama/`, and sets `OLLAMA_HOST=http://<host-lan-ip>:11434` in the
  container environment.
- Registry default `[defaults].llm.enabled = true`.

Per-project hermes data directories (opt-in):

    repoman new myapp --hermes

This selectively seeds your host's `~/.hermes/` (credentials, config, skills, hooks,
runtime symlinks) into `~/.local/share/repoman/hermes/myapp/` and bind-mounts that
into the container as `~/.hermes`. Per-container sessions, memories, and SQLite state
stay isolated — never share a hermes data dir between two running instances.

To delete the data dir alongside the container:

    repoman remove myapp --purge-hermes
```

- [ ] **Step 3: VISION updates**

In `VISION.md`, find the line in the subcommand table for `repoman setup` and update its description:

```markdown
| `repoman setup` | First-time host setup. Creates Incus project `repoman`, ensures profiles exist (`claude-share` user-managed, `llm-share` repoman-managed), validates LAN ollama reachability if --with-llm. Idempotent. **Shipped in v0.3.** |
```

- [ ] **Step 4: Commit**

```bash
hg add reef.toml README.md VISION.md
hg commit -m "docs: v0.3 — README sections for setup + LLM stack; bump version"
```

---

## Task 25: End-to-end smoke test

Verify a complete `setup` → `new --hermes` → `shell into container and run hermes` → `remove --purge-hermes` cycle on the actual host. This is the manual gate before tagging v0.3.0.

**Files:**
- (none — manual verification)

- [ ] **Step 1: Build**

```bash
make build && sudo make install
```

Expected: `repoman --version` reports `0.3.0`.

- [ ] **Step 2: Setup wizard (with LLM)**

```bash
repoman setup --with-llm --non-interactive
```

Expected: prints the plan; applies stages; reports `setup complete`. Verify:

```bash
incus profile list --project repoman
# llm-share should be listed
incus profile show --project repoman llm-share | grep OLLAMA_HOST
# should show OLLAMA_HOST: "http://<your-lan-ip>:11434"
cat ~/.config/repoman/repoman.toml | grep -E 'schema|llm'
# schema = 2; [defaults.llm] block with enabled = true
```

- [ ] **Step 3: Create a hermes-enabled container**

```bash
mkdir -p ~/repos/smoke-test
echo "smoke" > ~/repos/smoke-test/README.md
repoman new smoke-test --hermes
```

Expected: container launched, hermes data dir seeded, device added, container restarted, registry updated.

```bash
ls ~/.local/share/repoman/hermes/smoke-test/
# should show .env, config.yaml, skills/, hooks/, hermes-agent (symlink), node (symlink), bin (symlink), SOUL.md
incus exec --project repoman smoke-test -- ls -la /home/$USER/.hermes
# inside the container, the same layout should appear
```

- [ ] **Step 4: Validate symlinks across the bind boundary (spec O-3)**

```bash
incus exec --project repoman smoke-test -- readlink /home/$USER/.hermes/hermes-agent
incus exec --project repoman smoke-test -- ls /home/$USER/.hermes/hermes-agent/
```

Expected: readlink shows the host path; the listing succeeds. **If the listing fails (broken symlink across mount namespace), this validates spec open question O-3 in the negative — escalate to a follow-up task: change `classify_seed_entry` to return `SEED_KIND_COPY()` for the runtime dirs and accept the upgrade-coordination cost.**

- [ ] **Step 5: Run hermes from inside the container**

```bash
repoman shell smoke-test
# inside the container:
hermes --version       # should print hermes version, identical to host
ollama list             # should hit the host daemon and list models
exit
```

Expected: both commands succeed. If `hermes` fails because some library/path is unresolved, surface the exact error — likely a sub-fix for the symlink set or an additional bind-mount needed in the `claude-share` profile (e.g., `~/.local/lib/python*/site-packages/`).

- [ ] **Step 6: Cleanup with --purge-hermes**

```bash
repoman remove smoke-test --purge-hermes
ls ~/.local/share/repoman/hermes/smoke-test/ 2>&1
# should report "No such file or directory"
```

- [ ] **Step 7: Tag v0.3.0**

```bash
hg tag v0.3.0
hg commit -m "v0.3.0 ships (setup wizard + llm-share profile + per-container hermes seeding)"
```

(Or, if your project tags via release notes only: skip the formal tag and ensure the commit message above is the release marker.)

---

## Self-review

**Spec coverage check** (against `2026-05-06-repoman-v0.3-llm-and-setup.md`):

- §0 New vs v0.2 — covered by the entire plan.
- §1 In-scope items — `repoman setup`: T14–T20. `llm-share`: T8, T15–T20. `--hermes`/`--no-hermes`: T21. `--purge-hermes`: T22. Selective seeding: T10–T12. Host LAN-IP detection: T15. `[defaults].llm` block: T1, T3, T4, T5, T6.
- §2 New modules — `setup.reef`: T14–T19. `hermes.reef`: T10–T13.
- §2 Edits to `cli.reef`/`config.reef`/`incus.reef` — T7–T9 (incus), T1–T6 (config), T20–T23 (cli).
- §3 `llm-share` profile — T16 (template), T19 (apply), T20 (cmd_setup wiring).
- §4 Per-container hermes data dirs — T10 (paths), T11 (classify), T12 (seed), T13 (purge), T21 (cmd_new wiring), T22 (cmd_remove wiring).
- §6.1 Schema bump — T1 (LlmDefaults), T2 (Project.hermes), T3 (parse), T4 (serialize), T5 (migration), T6 (default_registry).
- §6.2 Per-project override addition — *deferred, noted in T21 commit message and recorded as v0.4 work.*
- §6.3 Profile YAML template — T16.
- §7 Testing — pure tests at T1–T6, T10, T11, T16, T18; smoke at T15, T17, T25.
- §10 Build sequence — followed step-for-step (T1–T6 = §10.1, T7–T9 = §10.2, T10–T13 = §10.3, T14–T19 = §10.4, T20 = §10.5, T21 = §10.6, T22 = §10.7, T23 = §10.8, T24 = §10.9, T25 = §10.10).

**Spec gaps closed during planning:**
- The §6.2 override-file `[hermes].enabled` field is acknowledged in T21 as deferred to v0.4, with an explicit guard in `cmd_new` that prevents `--hermes` when LLM stack disabled.
- The exported-status of `incus.process_run_capture` and `process_run_silent` was a hidden dependency surfaced in T15 and T17 — handled by exporting them.

**Type-consistency check:** `LlmDefaults.hermes_seed: [string]` consistently across T1, T3, T4, T19. `Project.hermes: bool` across T2, T4, T21. `Stage.id: string` across T18, T19, T20. `seed_data_dir(source, dest, seed: [string])` signature matches T12 def and T21 call site.

**No-placeholder check:** every step contains either runnable shell, complete reef code, or a directive to read/find/grep a known location. Reviewed once; clean.

---

## Deferred (v0.4 candidates)

- `parse_override` reading `[hermes].enabled` from `repos.d/<name>.toml` (spec §6.2; gated in T21 by hard error).
- `repoman setup` authoring/editing `claude-share` (spec §1 explicit out-of-scope; spec O-5).
- `--purge` umbrella unifying `--purge-hermes` and future per-tool purges (spec O-1).
- `HERMES_HOME` env-based redirection if hermes supports it (spec O-2).
- Adopting an existing `~/.hermes` install as one of the per-container dirs.
- Multi-host registry awareness (spec O-6).
# repoman v0.4 — Profile library + scope trim Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Introduce the `profile` subcommand family backed by a vendor/user profile library, trim the v0.3 LLM-stack-specific surface from `setup`, and migrate the registry to schema 3.

**Architecture:** New `src/profile.reef` module owns profile lifecycle (lookup → render → install/remove/diff/show) with vendor profiles at `/usr/local/share/repoman/profiles/` and user shadows at `~/.config/repoman/profiles.d/`. Schema-3 `[host].lan_ip` field replaces `[defaults].llm.ollama_url`; the `[defaults].llm` block is removed entirely. `setup` shrinks from 4 stages to 2 (incus_project + registry_defaults); `cmd_new` gains pre-launch profile validation.

**Tech Stack:** reef-lang 0.5.20 (no new stdlib requirements), `encoding.toml`, `core.result_generic`, `sys.process.process_spawn` / `process_run`, `io.dir.list_dir` (new caller for an existing API), `test.framework.TestRunner`.

---

## Reference: spec and source

- Design spec: `docs/superpowers/specs/2026-05-08-repoman-v0.4-profile-library.md` (locked)
- v0.3 plan (style/depth reference): `docs/superpowers/plans/2026-05-06-repoman-v0.3-llm-and-setup.md`
- Existing modules to mirror:
  - `src/setup.reef` — for module skeleton style + Environment/Stage struct pattern
  - `src/incus.reef` — for `process_run_capture`/`process_run_silent` patterns
  - `src/config.reef` — for parse/serialize/migrate idiom (T1–T6 of v0.3 plan are direct precedent for schema migrations)
- Reef stdlib API references already verified for v0.4:
  - `core.str.replace(s, old, new)` — global replace
  - `io.dir.list_dir(path: string, entries: [string], max: int): int` — populates buffer, returns count
  - `io.dir.dir_exists`, `io.dir.create_dir_all` — already in use
  - `io.file.fileExists`, `io.file.readFile`, `io.file.writeFile` — already in use
  - `core.str.starts_with`, `str.ends_with`, `str.substring`, `str.length`, `str.contains` — all already used
  - `sys.env.get_env_or` — already in use

## File structure

```
~/repos/repoman/
├── reef.toml                              # bump version 0.3.0 → 0.4.0
├── README.md                              # add ## Profile library + ## Migrating from v0.3 sections
├── VISION.md                              # update setup row (no --with-llm); add profile management row
├── Makefile                               # install profiles/*.yml to /usr/local/share/repoman/profiles/
├── profiles/                              # NEW vendor library directory
│   ├── claude-share.yml
│   ├── llm-share.yml
│   └── dotfiles.yml
├── src/
│   ├── cli.reef                           # +cmd_profile dispatch, +pre-launch validation, -setup --with-llm flags
│   ├── config.reef                        # +Host substruct, -LlmDefaults, schema 2→3 migration
│   ├── hermes.reef                        # (unchanged) library-only, kept from v0.3
│   ├── incus.reef                         # +profile_get (capture stdout)
│   ├── log.reef                           # (unchanged)
│   ├── main.reef                          # (unchanged)
│   ├── paths.reef                         # (unchanged)
│   ├── profile.reef                       # NEW
│   ├── setup.reef                         # trim Environment, drop llm helpers, shrink plan/apply
│   └── sync.reef                          # (unchanged)
└── tests/
    ├── test_config_schema_v3.reef         # NEW — schema 3 acceptance + serialize round-trip
    ├── test_config_migrate.reef           # NEW — v1→v3 and v2-with-llm→v3 migration
    ├── test_profile_paths.reef            # NEW — vendor_dir, user_dir
    ├── test_profile_render.reef           # NEW — ${VAR} substitution
    └── test_*.reef                        # existing tests; some updated, some deleted
```

Module-boundary rules (carried from v0.1):
- Each module file declares `module <name>` matching its filename, ends with `end module`.
- `main.reef` has no module declaration.
- Tests are standalone reef programs each with their own `proc main()`.
- `make test` runs every `tests/test_*.reef`, stops on first failure.

---

## Task 1: `Host` substruct + drop `LlmDefaults`

**Files:**
- Modify: `src/config.reef` (export block, type definitions, Defaults literal sites)

`Defaults` loses its `llm: LlmDefaults` field. Registry gains a `host: Host` field. `LlmDefaults` type is removed.

- [ ] **Step 1: Read the current Defaults / Registry / LlmDefaults declarations**

```bash
sed -n '11,80p' src/config.reef
```

Expected: `LlmDefaults` type definition and `llm: LlmDefaults` field in `Defaults`.

- [ ] **Step 2: Add Host type and Registry.host field; drop LlmDefaults type and Defaults.llm field**

In `src/config.reef`'s export block, **remove** the line `type LlmDefaults` and **add** `type Host`:

```reef
export
    type Defaults
    type Host
    type Project
    type Override
    type Mount
    type Registry
    type EffectiveConfig
    ...
end export
```

Add a new type definition above `Defaults`:

```reef
type Host = struct
    lan_ip: string
end Host
```

Remove the entire `type LlmDefaults = struct ... end LlmDefaults` block.

In `Defaults`, remove the `llm: LlmDefaults` field. The struct goes back to its v0.2 shape:

```reef
type Defaults = struct
    repos_root: string
    backup_root: string
    logdir: string
    incus_project: string
    default_image: string
    profiles: [string]
end Defaults
```

In `Registry`, add a `host: Host` field as the second field (after `schema`, before `output`):

```reef
type Registry = struct
    schema: int
    host: Host
    output: string
    defaults: Defaults
    projects: [Project]
end Registry
```

- [ ] **Step 3: Update existing Defaults/Registry construction sites — remove `llm: LlmDefaults {...}` blocks, add `host: Host {...}`**

Sites today (per v0.3 + revert state):
- `parse_registry` (around line 153): `Defaults { ..., llm: LlmDefaults {...} }`. Drop the `llm:` line.
- `default_registry` (around line 434): same.
- Any test that builds a `Defaults` literal: `tests/test_config_serialize.reef`, `tests/test_config_roundtrip.reef`, `tests/test_config_merge.reef`, `tests/test_config_mutate.reef` — drop `llm:` field.

Then add `host: Host { lan_ip: "" }` to every `Registry` literal:
- `parse_registry` (the final return literal)
- `default_registry`
- Tests that build a `Registry` literal directly

For `parse_registry`'s final literal, change:

```reef
    let reg: Registry = Registry {
        schema:   2,
        output:   output,
        defaults: defaults,
        projects: projects
    }
```

to:

```reef
    let host: Host = Host {
        lan_ip: ""    // populated below for schema 2 migration; left empty otherwise
    }
    let reg: Registry = Registry {
        schema:   2,
        host:     host,
        output:   output,
        defaults: defaults,
        projects: projects
    }
```

(The `host.lan_ip` value will be properly populated by the schema-2 migration logic in T2; this task just adds the field with a default of empty string.)

For `default_registry`:

```reef
    return Registry {
        schema:   2,
        host:     Host { lan_ip: "" },
        output:   "quiet",
        defaults: Defaults { ... },     // no llm field
        projects: new [Project](0)
    }
```

(Schema constant stays at 2 in this task; T5 bumps to 3.)

- [ ] **Step 4: Run existing tests; expect compile failures in test files that reference LlmDefaults or `defaults.llm`**

```bash
make test
```

Expected: compile errors on tests that use `LlmDefaults` or `reg.defaults.llm`. These tests are about to be deleted (T7) but for now patch them minimally to compile:
- `tests/test_config_serialize.reef`, `test_config_roundtrip.reef`, `test_config_merge.reef`, `test_config_mutate.reef` — drop `llm:` field from `Defaults` literals; add `host: Host { lan_ip: "" }` to `Registry` literals.

Run `grep -rln 'LlmDefaults\|defaults.llm' src/ tests/` to find every site.

- [ ] **Step 5: Build clean and re-run tests**

```bash
make build && make test
```

Expected: clean build. Some tests may still fail because parse/serialize haven't been updated yet (T2/T3); that's fine for now. The build must compile.

- [ ] **Step 6: Commit**

```bash
hg add src/config.reef tests/
hg commit -m "config: add Host substruct on Registry, drop LlmDefaults (schema unchanged)"
```

---

## Task 2: `parse_registry` reads `[host].lan_ip` and migrates from schema 2's `[defaults.llm.ollama_url]`

**Files:**
- Modify: `src/config.reef` (parse_registry function)

- [ ] **Step 1: Add a private helper `extract_lan_ip_from_url`**

Inside `src/config.reef`, before `parse_registry`, add:

```reef
// Extract the host portion of an `http://<host>:<port>` URL string.
// Returns "" if the input doesn't match that shape.
fn extract_lan_ip_from_url(url: string): string
    let n: int = str.length(url)
    if n == 0
        return ""
    end if
    let prefix: string = "http://"
    let prefix_len: int = 7
    if not str.starts_with(url, prefix)
        return ""
    end if
    // Find ':' after the prefix
    mut i: int = prefix_len
    while i < n and url[i] != ':'
        i = i + 1
    end while
    if i <= prefix_len
        return ""
    end if
    return str.substring(url, prefix_len, i - prefix_len)
end extract_lan_ip_from_url
```

- [ ] **Step 2: Modify `parse_registry` to read `[host].lan_ip` (schema 3) or extract from `[defaults.llm.ollama_url]` (schema 2 migration)**

In `parse_registry`, find the schema check (currently `if schema != 1 and schema != 2`). Update to accept schema 3:

```reef
    if schema != 1 and schema != 2 and schema != 3
        return @Result[Registry, string].Err("unsupported schema (expected 1, 2, or 3)")
    end if
```

Right before the final `Registry { ... }` literal (where Task 1 added `host: host`), populate the `host` value:

```reef
    // [host].lan_ip — schema 3 reads it directly; schema 2 migration extracts from
    // the now-removed [defaults.llm.ollama_url]; schema 1 has no such value (empty).
    mut lan_ip: string = toml.toml_get_doc(doc, "host.lan_ip")
    if str.length(lan_ip) == 0
        // Fall back: schema 2 migration via [defaults.llm.ollama_url]
        let old_url: string = toml.toml_get_doc(doc, "defaults.llm.ollama_url")
        if str.length(old_url) > 0
            lan_ip = extract_lan_ip_from_url(old_url)
        end if
    end if

    let host: Host = Host {
        lan_ip: lan_ip
    }
```

Replace Task 1's placeholder `let host: Host = Host { lan_ip: "" }` with this block.

- [ ] **Step 3: Build to verify**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/config.reef
hg commit -m "config: parse_registry accepts schema 3 + migrates lan_ip from schema 2 ollama_url"
```

---

## Task 3: `serialize_registry` writes `[host]` block; never writes `[defaults.llm]`

**Files:**
- Modify: `src/config.reef` (serialize_registry function)

The serializer is currently writing `[defaults.llm]` (per v0.3 T4). Remove that, add `[host]`.

- [ ] **Step 1: Read the current serialize_registry**

```bash
grep -n 'fn serialize_registry\|toml.toml_begin_table\|defaults.llm' src/config.reef
```

Identify the `toml_begin_table(b, "defaults.llm")` block and the surrounding section.

- [ ] **Step 2: Remove `[defaults.llm]` writes; add `[host]` write**

In `serialize_registry`, after `toml_set_string(b, "output", reg.output)` (the `[repoman]` block) and BEFORE `toml_begin_table(b, "defaults")`, insert the `[host]` block:

```reef
    toml.toml_begin_table(b, "host")
    toml.toml_set_string(b, "lan_ip", reg.host.lan_ip)
```

In the `[defaults]` section, **remove** the entire `[defaults.llm]` block:

```reef
    // DELETE these lines:
    toml.toml_begin_table(b, "defaults.llm")
    toml.toml_set_bool(b, "enabled", reg.defaults.llm.enabled)
    toml.toml_set_bool(b, "hermes_default", reg.defaults.llm.hermes_default)
    toml.toml_set_string(b, "ollama_url", reg.defaults.llm.ollama_url)
    toml.toml_set_string_array(b, "hermes_seed", reg.defaults.llm.hermes_seed)
```

The `[defaults]` body retains all other field writes (repos_root, backup_root, logdir, incus_project, default_image, profiles).

- [ ] **Step 3: Build to verify**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/config.reef
hg commit -m "config: serialize_registry emits [host] block, drops [defaults.llm]"
```

---

## Task 4: Force in-memory schema to 3 in `parse_registry`

**Files:**
- Modify: `src/config.reef` (parse_registry's final Registry literal)

Same pattern as v0.3's T5: any registry, regardless of disk format, becomes schema 3 in memory.

- [ ] **Step 1: Update parse_registry's final literal**

In `parse_registry`, find the final Registry literal (currently `schema: 2,`):

```reef
    let reg: Registry = Registry {
        schema:   2,
        host:     host,
        output:   output,
        defaults: defaults,
        projects: projects
    }
```

Change `schema: 2,` to `schema: 3,`.

- [ ] **Step 2: Update existing test assertions about post-parse schema**

`grep -rn 'reg.schema, 2\|.schema, 2\|reg2.schema, 2' tests/` to find tests asserting schema=2 after parse. Update to `3`.

Likely sites: `tests/test_config_parse.reef`, `tests/test_config_roundtrip.reef`, `tests/test_config_save.reef`, `tests/test_config_migrate_v1.reef`. Also possibly `test_config_io.reef` for the parse-not-init path.

For each, change assertions like:

```reef
runner.assert_eq_int(reg.schema, 2, "schema after parse = 2")
```

to:

```reef
runner.assert_eq_int(reg.schema, 3, "schema after parse = 3 (migrated)")
```

Don't change tests that build a `Registry` literal directly with `schema: 2` and serialize without parsing (those are testing serializer fidelity at the input schema, and still pass).

- [ ] **Step 3: Run all tests**

```bash
make test
```

Expected: all suites pass. Some tests will need additional updates due to `LlmDefaults` removal (already done in T1's step 4). If any still fail, they'll likely be in `test_config_llm_parse.reef` or `test_config_llm_serialize.reef` — both will be deleted in T7. For now, comment out their failing assertions or skip the test.

- [ ] **Step 4: Commit**

```bash
hg add src/config.reef tests/
hg commit -m "config: in-memory schema always 3 after parse (v1/v2 migrate implicitly)"
```

---

## Task 5: `default_registry` returns schema 3

**Files:**
- Modify: `src/config.reef` (default_registry function)
- Tests: `tests/test_config_io.reef` (init-path schema assertion)

- [ ] **Step 1: Update default_registry**

In `src/config.reef`, find:

```reef
fn default_registry(home_dir: string): Registry
    ...
    return Registry {
        schema: 2,
        host:     Host { lan_ip: "" },
        ...
    }
end default_registry
```

Change `schema: 2,` to `schema: 3,`.

- [ ] **Step 2: Update test_config_io.reef's init-path assertion**

`grep -n 'schema' tests/test_config_io.reef`. The init path (where `load_or_init` is called against an empty temp dir) currently asserts `reg.schema == 2`. Change to `3`.

- [ ] **Step 3: Run tests**

```bash
make test
```

Expected: all green (modulo the to-be-deleted tests).

- [ ] **Step 4: Commit**

```bash
hg add src/config.reef tests/test_config_io.reef
hg commit -m "config: default_registry writes schema 3"
```

---

## Task 6: Schema 3 acceptance test + migration test

**Files:**
- Test: `tests/test_config_schema_v3.reef` (new)
- Test: `tests/test_config_migrate.reef` (new)

- [ ] **Step 1: Write test_config_schema_v3.reef — schema 3 round-trip**

Create `tests/test_config_schema_v3.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

proc main()
    let runner = new framework.TestRunner()

    // Build a schema-3 registry, serialize, parse round-trip
    let reg = config.Registry {
        schema:   3,
        host:     config.Host { lan_ip: "192.168.168.124" },
        output:   "quiet",
        defaults: config.Defaults {
            repos_root:    "~/repos",
            backup_root:   "/nfs/repos",
            logdir:        "~/.local/state/repoman",
            incus_project: "repoman",
            default_image: "images:ubuntu/26.04/cloud",
            profiles:      ["default"]
        },
        projects: new [config.Project](0)
    }

    let s = config.serialize_registry(reg)
    runner.assert_contains_string(s, "schema = 3", "writes schema = 3")
    runner.assert_contains_string(s, "[host]", "writes [host] block")
    runner.assert_contains_string(s, "lan_ip = \"192.168.168.124\"", "writes lan_ip")
    let neg = str.contains(s, "[defaults.llm]")
    runner.assert_eq_bool(neg, false, "does NOT write [defaults.llm]")

    let r2 = config.parse_registry(s)
    runner.assert_eq_bool(rg.is_ok(r2), true, "round-trip parses ok")
    if rg.is_ok(r2)
        let reg2 = rg.unwrap_ok(r2)
        runner.assert_eq_int(reg2.schema, 3, "round-trip schema = 3")
        runner.assert_eq_string(reg2.host.lan_ip, "192.168.168.124", "round-trip host.lan_ip")
    end if

    runner.report()
end main
```

(Note: `import core.str` for `str.contains` if needed — check `tests/test_config_llm_serialize.reef` for the import pattern.)

- [ ] **Step 2: Write test_config_migrate.reef — v1→v3 and v2→v3 migration**

Create `tests/test_config_migrate.reef`:

```reef
import config
import test.framework
import core.result_generic as rg

proc main()
    let runner = new framework.TestRunner()

    // v1 (no llm block, no host block) → v3 with empty lan_ip
    let v1: string = "[repoman]\nschema = 1\noutput = \"quiet\"\n\n[defaults]\nrepos_root = \"~/repos\"\nbackup_root = \"/nfs/repos\"\nlogdir = \"~/.local/state/repoman\"\nincus_project = \"repoman\"\ndefault_image = \"images:ubuntu/26.04/cloud\"\nprofiles = [\"default\", \"claude-share\"]\n"
    let r1 = config.parse_registry(v1)
    runner.assert_eq_bool(rg.is_ok(r1), true, "v1 parses ok")
    if rg.is_ok(r1)
        let reg = rg.unwrap_ok(r1)
        runner.assert_eq_int(reg.schema, 3, "v1 schema migrates to 3")
        runner.assert_eq_string(reg.host.lan_ip, "", "v1 has no lan_ip")
    end if

    // v2 with [defaults.llm.ollama_url] → v3 with extracted lan_ip
    let v2: string = "[repoman]\nschema = 2\noutput = \"quiet\"\n\n[defaults]\nrepos_root = \"~/repos\"\nbackup_root = \"/nfs/repos\"\nlogdir = \"~/.local/state/repoman\"\nincus_project = \"repoman\"\ndefault_image = \"images:ubuntu/26.04/cloud\"\nprofiles = [\"default\"]\n\n[defaults.llm]\nenabled = true\nhermes_default = false\nollama_url = \"http://192.168.168.124:11434\"\nhermes_seed = []\n"
    let r2 = config.parse_registry(v2)
    runner.assert_eq_bool(rg.is_ok(r2), true, "v2 parses ok")
    if rg.is_ok(r2)
        let reg = rg.unwrap_ok(r2)
        runner.assert_eq_int(reg.schema, 3, "v2 schema migrates to 3")
        runner.assert_eq_string(reg.host.lan_ip, "192.168.168.124", "v2 lan_ip extracted from ollama_url")
    end if

    // v2 without [defaults.llm.ollama_url] (LLM was disabled) → v3 with empty lan_ip
    let v2_no_llm: string = "[repoman]\nschema = 2\noutput = \"quiet\"\n\n[defaults]\nrepos_root = \"~/repos\"\nbackup_root = \"/nfs/repos\"\nlogdir = \"~/.local/state/repoman\"\nincus_project = \"repoman\"\ndefault_image = \"images:ubuntu/26.04/cloud\"\nprofiles = [\"default\"]\n"
    let r3 = config.parse_registry(v2_no_llm)
    runner.assert_eq_bool(rg.is_ok(r3), true, "v2 without llm block parses ok")
    if rg.is_ok(r3)
        let reg = rg.unwrap_ok(r3)
        runner.assert_eq_string(reg.host.lan_ip, "", "v2 without ollama_url has empty lan_ip")
    end if

    // v3 native (with [host].lan_ip) round-trip
    let v3: string = "[repoman]\nschema = 3\noutput = \"quiet\"\n\n[host]\nlan_ip = \"10.0.0.5\"\n\n[defaults]\nrepos_root = \"~/repos\"\nbackup_root = \"/nfs/repos\"\nlogdir = \"~/.local/state/repoman\"\nincus_project = \"repoman\"\ndefault_image = \"images:ubuntu/26.04/cloud\"\nprofiles = [\"default\"]\n"
    let r4 = config.parse_registry(v3)
    runner.assert_eq_bool(rg.is_ok(r4), true, "v3 parses ok")
    if rg.is_ok(r4)
        let reg = rg.unwrap_ok(r4)
        runner.assert_eq_string(reg.host.lan_ip, "10.0.0.5", "v3 native lan_ip read directly")
    end if

    runner.report()
end main
```

- [ ] **Step 3: Run the new tests**

```bash
reefc run tests/test_config_schema_v3.reef
reefc run tests/test_config_migrate.reef
```

Expected: all assertions pass.

- [ ] **Step 4: Run full test suite for regression check**

```bash
make test
```

Expected: all green (modulo the to-be-deleted tests in T7).

- [ ] **Step 5: Commit**

```bash
hg add tests/test_config_schema_v3.reef tests/test_config_migrate.reef
hg commit -m "config: tests for schema 3 round-trip and v1/v2 migration"
```

---

## Task 7: Delete v0.3-only LLM-block tests

**Files:**
- Delete: `tests/test_config_llm_parse.reef`
- Delete: `tests/test_config_llm_serialize.reef`
- Delete: `tests/test_config_migrate_v1.reef`

After T6's new tests, these v0.3-era tests are superseded:
- `test_config_llm_parse.reef` — tested parsing of `[defaults.llm]` block which no longer exists
- `test_config_llm_serialize.reef` — tested serializing the same
- `test_config_migrate_v1.reef` — tested v1→v2 migration; T6's `test_config_migrate.reef` covers v1→v3 and v2→v3

- [ ] **Step 1: Delete the three test files**

```bash
hg rm tests/test_config_llm_parse.reef
hg rm tests/test_config_llm_serialize.reef
hg rm tests/test_config_migrate_v1.reef
```

- [ ] **Step 2: Run all tests to confirm clean state**

```bash
make test
```

Expected: clean. The remaining test count is lower than v0.3.

- [ ] **Step 3: Commit**

```bash
hg commit -m "tests: drop v0.3 [defaults.llm] tests; superseded by schema_v3 + migrate tests"
```

---

## Task 8: `incus.profile_get` — capture-mode wrapper for `incus profile show`

**Files:**
- Modify: `src/incus.reef` (export block + new function)

- [ ] **Step 1: Add to export block**

In `src/incus.reef`'s export block, add:

```reef
    fn profile_get(project: string, name: string): rg.Result[string, string]
```

- [ ] **Step 2: Implement profile_get**

After the existing `profile_create_or_edit` function, add:

```reef
// Returns the YAML body of the named profile (the same output as
// `incus profile show <project> <name>`). Errors if the profile doesn't
// exist or the subprocess fails.
fn profile_get(project: string, name: string): rg.Result[string, string]
    let cap: CaptureResult = process_run_capture("incus", [
        "profile", "show", "--project", project, name
    ])
    if cap.exit_code != 0
        return @Result[string, string].Err("incus profile show exited " + convert.to_string(cap.exit_code))
    end if
    return @Result[string, string].Ok(cap.stdout)
end profile_get
```

- [ ] **Step 3: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 4: Commit**

```bash
hg add src/incus.reef
hg commit -m "incus: add profile_get (capture incus profile show stdout)"
```

---

## Task 9: `profile.reef` skeleton + types

**Files:**
- Create: `src/profile.reef`

- [ ] **Step 1: Create the module skeleton**

Create `src/profile.reef`:

```reef
module profile

import core.str
import core.result_generic as rg
import core.convert as convert
import io.file as iofile
import io.dir as iodir
import sys.env
import paths
import incus

export
    type ProfileEntry
    type HostFacts
    fn vendor_dir(): string
    fn user_dir(home_dir: string): string
    fn render(yaml: string, host: HostFacts): string
    fn lookup(name: string, home_dir: string): rg.Result[string, string]
    fn list_all(home_dir: string): [ProfileEntry]
    fn install(name: string, home_dir: string, host: HostFacts): rg.Result[bool, string]
    fn remove_profile(name: string): rg.Result[bool, string]
    fn show(name: string, home_dir: string, host: HostFacts): rg.Result[string, string]
    fn diff(name: string, home_dir: string, host: HostFacts): rg.Result[string, string]
end export

// One entry from the profile library, populated by list_all.
type ProfileEntry = struct
    name:      string         // e.g., "claude-share"
    source:    string         // "user", "vendor", or "user (shadows vendor)"
    file_path: string         // resolved file path
    installed: bool           // present in incus state
end ProfileEntry

// Substitution context for templated profile YAML.
type HostFacts = struct
    lan_ip: string
    user:   string
    home:   string
end HostFacts

// (function bodies follow in subsequent tasks)

fn vendor_dir(): string
    return ""
end vendor_dir

fn user_dir(home_dir: string): string
    return ""
end user_dir

fn render(yaml: string, host: HostFacts): string
    return yaml
end render

fn lookup(name: string, home_dir: string): rg.Result[string, string]
    return @Result[string, string].Err("not implemented")
end lookup

fn list_all(home_dir: string): [ProfileEntry]
    return new [ProfileEntry](0)
end list_all

fn install(name: string, home_dir: string, host: HostFacts): rg.Result[bool, string]
    return @Result[bool, string].Err("not implemented")
end install

fn remove_profile(name: string): rg.Result[bool, string]
    return @Result[bool, string].Err("not implemented")
end remove_profile

fn show(name: string, home_dir: string, host: HostFacts): rg.Result[string, string]
    return @Result[string, string].Err("not implemented")
end show

fn diff(name: string, home_dir: string, host: HostFacts): rg.Result[string, string]
    return @Result[string, string].Err("not implemented")
end diff

end module
```

(Note: function name is `remove_profile` not `remove` — `remove` would conflict with the existing reef stdlib. Caller in `cli.reef` uses `profile.remove_profile`.)

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build (stubs compile).

- [ ] **Step 3: Commit**

```bash
hg add src/profile.reef
hg commit -m "profile: module skeleton with types and stubbed entry points"
```

---

## Task 10: `profile.vendor_dir`, `profile.user_dir`, `profile.render` + tests

**Files:**
- Modify: `src/profile.reef`
- Test: `tests/test_profile_paths.reef`
- Test: `tests/test_profile_render.reef`

- [ ] **Step 1: Write failing test for vendor_dir / user_dir**

Create `tests/test_profile_paths.reef`:

```reef
import profile
import test.framework

proc main()
    let runner = new framework.TestRunner()

    runner.assert_eq_string(
        profile.vendor_dir(),
        "/usr/local/share/repoman/profiles",
        "vendor_dir is the install layout"
    )
    runner.assert_eq_string(
        profile.user_dir("/home/ctusa"),
        "/home/ctusa/.config/repoman/profiles.d",
        "user_dir under XDG config"
    )
    runner.assert_eq_string(
        profile.user_dir(""),
        "/.config/repoman/profiles.d",
        "user_dir with empty home (still composes path)"
    )

    runner.report()
end main
```

- [ ] **Step 2: Run test, see failure**

```bash
reefc run tests/test_profile_paths.reef
```

Expected: 3 assertion failures (stub returns "").

- [ ] **Step 3: Implement vendor_dir + user_dir**

In `src/profile.reef`, replace the stubs:

```reef
fn vendor_dir(): string
    return "/usr/local/share/repoman/profiles"
end vendor_dir

fn user_dir(home_dir: string): string
    return paths.join(home_dir, ".config/repoman/profiles.d")
end user_dir
```

- [ ] **Step 4: Run test, expect pass**

```bash
reefc run tests/test_profile_paths.reef
```

Expected: 3/3 pass.

- [ ] **Step 5: Write failing test for render**

Create `tests/test_profile_render.reef`:

```reef
import profile
import test.framework

proc main()
    let runner = new framework.TestRunner()

    let host = profile.HostFacts {
        lan_ip: "192.168.168.124",
        user:   "ctusa",
        home:   "/home/ctusa"
    }

    // All three substitutions
    let yaml: string = "config:\n  environment.OLLAMA_HOST: \"http://${HOST_LAN_IP}:11434\"\ndevices:\n  state:\n    source: ${HOME}/.ollama\n    user: ${USER}\n"
    let out = profile.render(yaml, host)
    runner.assert_contains_string(out, "http://192.168.168.124:11434", "${HOST_LAN_IP} substituted")
    runner.assert_contains_string(out, "/home/ctusa/.ollama", "${HOME} substituted")
    runner.assert_contains_string(out, "user: ctusa", "${USER} substituted")
    runner.assert_eq_bool(false, str.contains(out, "${HOST_LAN_IP}"), "no leftover ${HOST_LAN_IP}")
    runner.assert_eq_bool(false, str.contains(out, "${USER}"), "no leftover ${USER}")
    runner.assert_eq_bool(false, str.contains(out, "${HOME}"), "no leftover ${HOME}")

    // No substitutions present — input is returned unchanged
    let plain: string = "name: foo\nconfig: {}\n"
    runner.assert_eq_string(profile.render(plain, host), plain, "no-substitution input passes through")

    // Empty input
    runner.assert_eq_string(profile.render("", host), "", "empty input")

    runner.report()
end main
```

(Add `import core.str` at the top — `str.contains` requires it.)

- [ ] **Step 6: Run, see failure**

```bash
reefc run tests/test_profile_render.reef
```

Expected: assertion failures (stub returns input unchanged, but the substitution-required assertions fail).

- [ ] **Step 7: Implement render**

Replace the stub:

```reef
fn render(yaml: string, host: HostFacts): string
    let s1: string = str.replace(yaml, "${HOST_LAN_IP}", host.lan_ip)
    let s2: string = str.replace(s1,   "${USER}",        host.user)
    let s3: string = str.replace(s2,   "${HOME}",        host.home)
    return s3
end render
```

- [ ] **Step 8: Run tests**

```bash
reefc run tests/test_profile_render.reef
make test
```

Expected: render test 9/9, full suite green.

- [ ] **Step 9: Commit**

```bash
hg add src/profile.reef tests/test_profile_paths.reef tests/test_profile_render.reef
hg commit -m "profile: vendor_dir, user_dir, render — pure helpers + tests"
```

---

## Task 11: `profile.lookup` — search user dir then vendor dir

**Files:**
- Modify: `src/profile.reef` (replace lookup stub)

- [ ] **Step 1: Implement lookup**

Replace the stub `fn lookup(...)`:

```reef
// Search user dir first, then vendor dir. Returns the path to the YAML file.
// User shadows vendor: a file in user dir wins.
fn lookup(name: string, home_dir: string): rg.Result[string, string]
    let user_path: string = paths.join(user_dir(home_dir), name + ".yml")
    if iofile.fileExists(user_path)
        return @Result[string, string].Ok(user_path)
    end if
    let vendor_path: string = paths.join(vendor_dir(), name + ".yml")
    if iofile.fileExists(vendor_path)
        return @Result[string, string].Ok(vendor_path)
    end if
    return @Result[string, string].Err("profile not found: " + name + " (looked in " + user_path + " and " + vendor_path + ")")
end lookup
```

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 3: Smoke-test by inspection**

Create a temp dir + file:

```bash
mkdir -p /tmp/repoman-lookup-test/.config/repoman/profiles.d
echo 'name: test' > /tmp/repoman-lookup-test/.config/repoman/profiles.d/test.yml
cat > /tmp/test_lookup.reef <<'EOF'
import profile
import core.result_generic as rg
import io.console as console

proc main()
    let r = profile.lookup("test", "/tmp/repoman-lookup-test")
    if rg.is_ok(r)
        console.print("found: " + rg.unwrap_ok(r) + "\n")
    else
        console.print("err: " + rg.unwrap_err(r) + "\n")
    end if
EOF
reefc run /tmp/test_lookup.reef
```

Expected: `found: /tmp/repoman-lookup-test/.config/repoman/profiles.d/test.yml`.

(If `console.print` doesn't compile, use `println` instead — same pattern as the v0.3 setup smoke test.)

- [ ] **Step 4: Commit**

```bash
hg add src/profile.reef
hg commit -m "profile: lookup — user-shadows-vendor file resolution"
```

---

## Task 12: `profile.list_all` — enumerate both dirs with shadow + install status

**Files:**
- Modify: `src/profile.reef` (replace list_all stub)

- [ ] **Step 1: Implement list_all**

Replace the stub. The function enumerates user dir + vendor dir, builds a name → ProfileEntry map (user shadows vendor), and queries incus for install status.

```reef
fn list_all(home_dir: string): [ProfileEntry]
    // Buffers for filename lists. Cap at 256 per dir; profile libraries
    // are not expected to be enormous.
    let max_files: int = 256
    mut user_buf: [string] = new [string](max_files)
    mut vendor_buf: [string] = new [string](max_files)

    let u_dir: string = user_dir(home_dir)
    mut user_count: int = 0
    if iodir.dir_exists(u_dir)
        user_count = iodir.list_dir(u_dir, user_buf, max_files)
    end if

    let v_dir: string = vendor_dir()
    mut vendor_count: int = 0
    if iodir.dir_exists(v_dir)
        vendor_count = iodir.list_dir(v_dir, vendor_buf, max_files)
    end if

    // Pre-allocate result buffer at worst-case size.
    let cap: int = user_count + vendor_count
    mut entries_buf: [ProfileEntry] = new [ProfileEntry](cap)
    mut e_count: int = 0

    // Pass 1: add all user-dir *.yml files
    mut i: int = 0
    while i < user_count
        let fname: string = user_buf[i]
        if str.ends_with(fname, ".yml")
            let name: string = str.substring(fname, 0, str.length(fname) - 4)
            let path: string = paths.join(u_dir, fname)
            let installed_r = incus.profile_exists("default", name)
            mut installed: bool = false
            if rg.is_ok(installed_r)
                installed = rg.unwrap_ok(installed_r)
            end if
            entries_buf[e_count] = ProfileEntry {
                name:      name,
                source:    "user",
                file_path: path,
                installed: installed
            }
            e_count = e_count + 1
        end if
        i = i + 1
    end while

    // Pass 2: add vendor-dir *.yml files NOT already present (so user wins)
    mut j: int = 0
    while j < vendor_count
        let fname: string = vendor_buf[j]
        if str.ends_with(fname, ".yml")
            let name: string = str.substring(fname, 0, str.length(fname) - 4)
            // Check if name already in entries_buf
            mut shadowed: bool = false
            mut k: int = 0
            while k < e_count
                if entries_buf[k].name == name
                    shadowed = true
                    // Update the existing user entry's source label to indicate shadow
                    entries_buf[k] = ProfileEntry {
                        name:      entries_buf[k].name,
                        source:    "user (shadows vendor)",
                        file_path: entries_buf[k].file_path,
                        installed: entries_buf[k].installed
                    }
                end if
                k = k + 1
            end while
            if not shadowed
                let path: string = paths.join(v_dir, fname)
                let installed_r = incus.profile_exists("default", name)
                mut installed: bool = false
                if rg.is_ok(installed_r)
                    installed = rg.unwrap_ok(installed_r)
                end if
                entries_buf[e_count] = ProfileEntry {
                    name:      name,
                    source:    "vendor",
                    file_path: path,
                    installed: installed
                }
                e_count = e_count + 1
            end if
        end if
        j = j + 1
    end while

    // Compact to actual size
    mut entries: [ProfileEntry] = new [ProfileEntry](e_count)
    mut m: int = 0
    while m < e_count
        entries[m] = entries_buf[m]
        m = m + 1
    end while
    return entries
end list_all
```

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 3: Commit**

```bash
hg add src/profile.reef
hg commit -m "profile: list_all — enumerate user + vendor dirs with shadow handling"
```

---

## Task 13: `profile.install` — render + apply via incus.profile_create_or_edit

**Files:**
- Modify: `src/profile.reef` (replace install stub)

- [ ] **Step 1: Implement install**

Replace the stub:

```reef
fn install(name: string, home_dir: string, host: HostFacts): rg.Result[bool, string]
    // Resolve the file (user or vendor)
    let path_r = lookup(name, home_dir)
    if rg.is_err(path_r)
        return @Result[bool, string].Err(rg.unwrap_err(path_r))
    end if
    let path: string = rg.unwrap_ok(path_r)

    // Read the file
    let yaml: string = iofile.readFile(path)
    if str.length(yaml) == 0
        return @Result[bool, string].Err("empty or unreadable profile file: " + path)
    end if

    // Render — but if HOST_LAN_IP is needed and host.lan_ip is empty, fail with a hint
    if str.contains(yaml, "${HOST_LAN_IP}") and str.length(host.lan_ip) == 0
        return @Result[bool, string].Err("profile " + name + " requires ${HOST_LAN_IP} but [host].lan_ip is empty in registry. Run 'repoman setup' to detect and store the host LAN IP.")
    end if
    let rendered: string = render(yaml, host)

    // Apply via incus
    return incus.profile_create_or_edit("default", name, rendered)
end install
```

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 3: Commit**

```bash
hg add src/profile.reef
hg commit -m "profile: install — resolve, render, apply via incus profile_create_or_edit"
```

---

## Task 14: `profile.remove_profile` and `profile.show`

**Files:**
- Modify: `src/profile.reef`

- [ ] **Step 1: Implement remove_profile and show**

Replace the stubs:

```reef
fn remove_profile(name: string): rg.Result[bool, string]
    let pid: int = process_run_silent_via_incus(name)  // helper below
    // Note: we use incus.run_incus directly for clarity here.
    return incus_delete_profile(name)
end remove_profile
```

Actually, simpler: avoid the indirection. Replace with a direct call:

```reef
fn remove_profile(name: string): rg.Result[bool, string]
    return incus_run_remove(name)
end remove_profile
```

Hmm, neither is cleanest. Use the existing incus public surface or extend it.

Let me reconsider — `src/incus.reef` already has `delete_container`. Add a sibling `delete_profile`:

(This step requires a small addition in `src/incus.reef`. Take this detour now.)

In `src/incus.reef`, add to the export block:

```reef
    fn delete_profile(project: string, name: string): rg.Result[bool, string]
```

And add the function near `delete_container`:

```reef
fn delete_profile(project: string, name: string): rg.Result[bool, string]
    return run_incus(["profile", "delete", "--project", project, name])
end delete_profile
```

Now back to `src/profile.reef`:

```reef
fn remove_profile(name: string): rg.Result[bool, string]
    return incus.delete_profile("default", name)
end remove_profile

fn show(name: string, home_dir: string, host: HostFacts): rg.Result[string, string]
    let path_r = lookup(name, home_dir)
    if rg.is_err(path_r)
        return @Result[string, string].Err(rg.unwrap_err(path_r))
    end if
    let path: string = rg.unwrap_ok(path_r)
    let yaml: string = iofile.readFile(path)
    let rendered: string = render(yaml, host)
    return @Result[string, string].Ok(rendered)
end show
```

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 3: Commit**

```bash
hg add src/profile.reef src/incus.reef
hg commit -m "profile+incus: remove_profile, show; add incus.delete_profile wrapper"
```

---

## Task 15: `profile.diff` — render file vs incus state

**Files:**
- Modify: `src/profile.reef`

- [ ] **Step 1: Implement diff**

Replace the stub:

```reef
// Compute and return a string describing differences between the rendered
// file and the live incus profile state. v0.4 uses a simple line-by-line
// presentation: "  same line" / "- removed line" / "+ added line". A more
// sophisticated unified diff is out of scope; the use case is "show me
// what's drifted" not "produce a patch."
fn diff(name: string, home_dir: string, host: HostFacts): rg.Result[string, string]
    // Render the file
    let path_r = lookup(name, home_dir)
    if rg.is_err(path_r)
        return @Result[string, string].Err(rg.unwrap_err(path_r))
    end if
    let path: string = rg.unwrap_ok(path_r)
    let yaml: string = iofile.readFile(path)
    let rendered: string = render(yaml, host)

    // Fetch incus state
    let incus_r = incus.profile_get("default", name)
    if rg.is_err(incus_r)
        // Profile not installed — diff shows the rendered file as "would install"
        let msg: string = "profile " + name + " is not installed. Rendered would-be content:\n\n" + rendered
        return @Result[string, string].Ok(msg)
    end if
    let live: string = rg.unwrap_ok(incus_r)

    if rendered == live
        return @Result[string, string].Ok("(no drift)")
    end if

    // Simple line-mark diff: file lines marked '-', incus lines marked '+'.
    // This is not a unified diff; it's a side-by-side hint.
    let header: string = "--- profile file (rendered): " + path + "\n+++ incus state\n"
    let body: string = "-- file --\n" + rendered + "\n-- incus --\n" + live
    return @Result[string, string].Ok(header + body)
end diff
```

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 3: Commit**

```bash
hg add src/profile.reef
hg commit -m "profile: diff — show rendered file vs live incus state"
```

---

## Task 16: Trim `setup.reef` part 1 — Environment struct, detect_environment, drop helpers

**Files:**
- Modify: `src/setup.reef`
- Delete: `tests/test_setup_template.reef`

- [ ] **Step 1: Trim Environment struct**

In `src/setup.reef`, change:

```reef
type Environment = struct
    home_dir:             string
    user:                 string
    host_lan_ip:          string
    incus_reachable:      bool
    repoman_project_present: bool
    claude_share_present: bool
    ollama_binary:        string
    ollama_lan_ok:        bool
    hermes_binary:        string
    hermes_data_present:  bool
end Environment
```

to:

```reef
type Environment = struct
    home_dir:                 string
    user:                     string
    host_lan_ip:              string
    incus_reachable:          bool
    repoman_project_present:  bool
end Environment
```

- [ ] **Step 2: Trim detect_environment**

Replace the body to only populate the 5 fields:

```reef
fn detect_environment(home_dir: string): Environment
    let user: string = env.get_env_or("USER", "")
    let lan_ip: string = detect_host_lan_ip()

    // incus reachable?
    let incus_pid: int = incus.process_run_silent("incus", ["version"])
    mut incus_ok: bool = false
    if incus_pid >= 0
        incus_ok = p.process_wait(incus_pid) == 0
    end if

    // repoman project (only if incus is up)
    mut project_ok: bool = false
    if incus_ok
        let pe = incus.project_present("repoman")
        if rg.is_ok(pe)
            project_ok = rg.unwrap_ok(pe)
        end if
    end if

    return Environment {
        home_dir:                 home_dir,
        user:                     user,
        host_lan_ip:              lan_ip,
        incus_reachable:          incus_ok,
        repoman_project_present:  project_ok
    }
end detect_environment
```

- [ ] **Step 3: Remove helper functions which_binary, ollama_listening_at**

Both helpers are no longer used. Delete them entirely from `src/setup.reef`.

- [ ] **Step 4: Remove render_llm_share_template and template_contains_placeholder**

Delete both functions and remove them from the export block.

- [ ] **Step 5: Delete the test that exercised the now-removed render**

```bash
hg rm tests/test_setup_template.reef
```

- [ ] **Step 6: Build and test**

```bash
make build
make test
```

Expected: clean build. The setup_planner test will likely still pass (its 3 fixtures construct minimal Environments). If any test references the removed Environment fields, fix the test.

- [ ] **Step 7: Commit**

```bash
hg add src/setup.reef tests/
hg commit -m "setup: trim Environment to 5 fields; drop render_llm_share_template + which_binary + ollama_listening_at"
```

---

## Task 17: Trim `setup.reef` part 2 — plan_stages, apply_stage, planner test

**Files:**
- Modify: `src/setup.reef`
- Test: `tests/test_setup_planner.reef` (update)

- [ ] **Step 1: Update test_setup_planner.reef to expect 2 stages**

The test currently asserts 3-or-4 stages. Replace with 2 stages always:

```reef
import setup
import test.framework

proc main()
    let runner = new framework.TestRunner()

    // Fresh host
    let fresh = setup.Environment {
        home_dir: "/home/ctusa", user: "ctusa",
        host_lan_ip: "192.168.168.42",
        incus_reachable: true,
        repoman_project_present: false
    }
    let stages = setup.plan_stages(fresh)
    runner.assert_eq_int(stages.length(), 2, "always 2 stages: incus_project + registry_defaults")
    runner.assert_eq_string(stages[0].id, "incus_project", "stage 0 = incus_project")
    runner.assert_eq_bool(stages[0].is_change, true, "incus_project will change on fresh host")
    runner.assert_eq_string(stages[1].id, "registry_defaults", "stage 1 = registry_defaults")
    runner.assert_eq_bool(stages[1].is_change, true, "registry_defaults always writes")

    // Already-set-up host
    let done = setup.Environment {
        home_dir: "/home/ctusa", user: "ctusa",
        host_lan_ip: "192.168.168.42",
        incus_reachable: true,
        repoman_project_present: true
    }
    let s2 = setup.plan_stages(done)
    runner.assert_eq_int(s2.length(), 2, "still 2 stages")
    runner.assert_eq_bool(s2[0].is_change, false, "incus_project no-op when present")

    runner.report()
end main
```

- [ ] **Step 2: Update plan_stages signature and body**

`plan_stages` no longer takes `with_llm` (the flag is gone). Trim:

```reef
fn plan_stages(env: Environment): [Stage]
    mut stages: [Stage] = new [Stage](2)
    stages[0] = Stage {
        id:          "incus_project",
        description: "ensure Incus project 'repoman' exists",
        is_change:   not env.repoman_project_present
    }
    stages[1] = Stage {
        id:          "registry_defaults",
        description: "write registry defaults (schema 3, [host].lan_ip)",
        is_change:   true
    }
    return stages
end plan_stages
```

Update the export-block declaration to match:

```reef
    fn plan_stages(env: Environment): [Stage]
```

- [ ] **Step 3: Trim apply_stage to handle only incus_project and registry_defaults**

In `src/setup.reef`, replace `apply_stage`'s body:

```reef
fn apply_stage(stage: Stage, env: Environment, reg: config.Registry): rg.Result[config.Registry, string]
    if stage.id == "incus_project"
        if env.repoman_project_present
            return @Result[config.Registry, string].Ok(reg)
        end if
        let r = incus.project_ensure("repoman", false)
        if rg.is_err(r)
            return @Result[config.Registry, string].Err(rg.unwrap_err(r))
        end if
        return @Result[config.Registry, string].Ok(reg)
    end if

    if stage.id == "registry_defaults"
        // Update [host].lan_ip from detected env
        let new_host = config.Host {
            lan_ip: env.host_lan_ip
        }
        let new_reg = config.Registry {
            schema:   3,
            host:     new_host,
            output:   reg.output,
            defaults: reg.defaults,
            projects: reg.projects
        }
        return @Result[config.Registry, string].Ok(new_reg)
    end if

    return @Result[config.Registry, string].Err("unknown stage id: " + stage.id)
end apply_stage
```

The previous llm_share_profile and claude_share_check stages are gone.

- [ ] **Step 4: Build and test**

```bash
make build
make test
```

Expected: clean. test_setup_planner now passes its updated assertions.

- [ ] **Step 5: Commit**

```bash
hg add src/setup.reef tests/test_setup_planner.reef
hg commit -m "setup: plan_stages always emits 2 stages; apply_stage handles only incus_project + registry_defaults"
```

---

## Task 18: Trim `setup.reef` part 3 — cmd_setup flags and prompt

**Files:**
- Modify: `src/setup.reef` (cmd_setup function)

- [ ] **Step 1: Drop --with-llm and --without-llm flags from cmd_setup**

In `src/setup.reef`, find `cmd_setup`. Remove these lines:

```reef
    let _f2 = flag.bool_flag(parser, "with-llm",        '\0', false, "include the LLM stack ...")
    let _f3 = flag.bool_flag(parser, "without-llm",     '\0', false, "skip the LLM stack")
```

And remove the LLM-decision block:

```reef
    let with_llm_flag: bool = flag.get_bool(parser, "with-llm")
    let without_llm_flag: bool = flag.get_bool(parser, "without-llm")
    if with_llm_flag and without_llm_flag
        ...
    end if
    mut with_llm: bool = false
    if with_llm_flag
        ...
    end if
    ...prompt for LLM...
```

- [ ] **Step 2: Update calls to plan_stages and the success message**

Wherever cmd_setup currently calls `plan_stages(env_snap, with_llm)`, change to `plan_stages(env_snap)` (no second arg).

Remove the conditional success-hint about `--hermes`:

```reef
    // DELETE this block:
    if reg.defaults.llm.enabled
        println("        repoman new <name> --hermes")
    end if
```

(Note: `reg.defaults.llm` doesn't exist anymore; this would be a compile error after T1 anyway.)

The final success message becomes:

```reef
    println("")
    println("setup complete.")
    println("")
    println("  next: repoman profile install --all   (install vendor profile library)")
    println("        repoman new <name>")
    println("        repoman list")
```

- [ ] **Step 3: Update cmd_setup's flag.description and the print_usage entry in cli.reef**

In `src/setup.reef` cmd_setup, update:

```reef
    flag.description(parser, "First-time host bootstrap: incus project, registry, host LAN IP detection")
```

(`cli.reef` print_usage update is in T20.)

- [ ] **Step 4: Build and test**

```bash
make build
make test
```

Expected: clean.

- [ ] **Step 5: Commit**

```bash
hg add src/setup.reef
hg commit -m "setup: cmd_setup drops --with-llm/--without-llm flags; success hint points to profile install"
```

---

## Task 19: `cmd_new` pre-launch profile validation

**Files:**
- Modify: `src/cli.reef` (cmd_new)

- [ ] **Step 1: Insert validation block before `incus.launch`**

In `cmd_new`, find the line:

```reef
    log.write("==> incus launch " + eff.image + " " + name)
    let lr = incus.launch(reg.defaults.incus_project, name, eff.image, eff.profiles)
```

Immediately before `log.write("==> incus launch ...")`, add:

```reef
    // Pre-launch profile validation: every name in eff.profiles must either be
    // the magic incus 'default' profile, or installed in the 'default' project.
    // (Repoman-managed profiles all live in 'default' per the v0.4 architecture.)
    let pn2: int = eff.profiles.length()
    mut pi: int = 0
    while pi < pn2
        let pname: string = eff.profiles[pi]
        if pname != "default"
            let exists_r = incus.profile_exists("default", pname)
            if rg.is_ok(exists_r) and not rg.unwrap_ok(exists_r)
                log.write("repoman: error: container references profile '" + pname + "' but it's not installed in incus.")
                log.write("hint: repoman profile install " + pname)
                log.write("hint: repoman profile install --all   (to install the vendor library)")
                return 4
            end if
        end if
        pi = pi + 1
    end while
```

- [ ] **Step 2: Build**

```bash
make build
```

Expected: clean build.

- [ ] **Step 3: Test by inspection**

Set up a fixture: registry with `[defaults].profiles = ["default", "missing-profile"]`. Run `repoman new test`. Expect exit 4 with the hint.

(Manual smoke; no unit test for cmd_new because it's effectful.)

- [ ] **Step 4: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: cmd_new pre-launch validation — error early if profile not installed"
```

---

## Task 20: `cli.cmd_profile` dispatch for 5 verbs

**Files:**
- Modify: `src/cli.reef`

- [ ] **Step 1: Add cmd_profile to imports and exports**

In `src/cli.reef`, add to imports near the top:

```reef
import profile
```

Add `cmd_profile` to the export block:

```reef
    fn cmd_profile(argv: [string]): int
```

- [ ] **Step 2: Implement cmd_profile (dispatches on verb)**

After `cmd_setup`, add `cmd_profile`. Each verb is its own helper:

```reef
fn cmd_profile(argv: [string]): int
    if argv.length() == 0
        console.printErr("repoman: error: 'profile' requires a subcommand: list | install | diff | remove | show")
        return 2
    end if
    let verb: string = argv[0]
    // Slice argv[1..] for the verb's own parser
    let n: int = argv.length()
    mut rest: [string] = new [string](n - 1)
    mut i: int = 0
    while i < n - 1
        rest[i] = argv[i + 1]
        i = i + 1
    end while

    if verb == "list"
        return cmd_profile_list(rest)
    end if
    if verb == "install"
        return cmd_profile_install(rest)
    end if
    if verb == "diff"
        return cmd_profile_diff(rest)
    end if
    if verb == "remove"
        return cmd_profile_remove(rest)
    end if
    if verb == "show"
        return cmd_profile_show(rest)
    end if
    console.printErr("repoman: error: unknown profile subcommand: " + verb)
    return 2
end cmd_profile

fn build_host_facts(): profile.HostFacts
    let home: string = env.get_env_or("HOME", "")
    let user: string = env.get_env_or("USER", "")
    let reg_r = config.load_or_init(home)
    mut lan_ip: string = ""
    if rg.is_ok(reg_r)
        lan_ip = rg.unwrap_ok(reg_r).host.lan_ip
    end if
    return profile.HostFacts {
        lan_ip: lan_ip,
        user:   user,
        home:   home
    }
end build_host_facts

fn cmd_profile_list(argv: [string]): int
    let home: string = env.get_env_or("HOME", "")
    let entries = profile.list_all(home)
    println("NAME              SOURCE                  INSTALLED")
    let n: int = entries.length()
    mut i: int = 0
    while i < n
        let e = entries[i]
        mut inst: string = "no"
        if e.installed
            inst = "yes"
        end if
        println(e.name + "    " + e.source + "    " + inst)
        i = i + 1
    end while
    return 0
end cmd_profile_list

fn cmd_profile_install(argv: [string]): int
    let host = build_host_facts()
    let home: string = host.home
    if argv.length() == 0
        console.printErr("repoman: error: 'profile install' requires <name> or --all")
        return 2
    end if
    if argv[0] == "--all"
        let entries = profile.list_all(home)
        let n: int = entries.length()
        mut i: int = 0
        mut errs: int = 0
        while i < n
            let e = entries[i]
            println("==> install " + e.name + " (source: " + e.source + ")")
            let r = profile.install(e.name, home, host)
            if rg.is_err(r)
                console.printErr("  error: " + rg.unwrap_err(r))
                errs = errs + 1
            end if
            i = i + 1
        end while
        if errs > 0
            return 1
        end if
        return 0
    end if
    let name: string = argv[0]
    let r = profile.install(name, home, host)
    if rg.is_err(r)
        console.printErr("repoman: error: " + rg.unwrap_err(r))
        return 1
    end if
    println("==> installed " + name)
    return 0
end cmd_profile_install

fn cmd_profile_diff(argv: [string]): int
    if argv.length() == 0
        console.printErr("repoman: error: 'profile diff' requires <name>")
        return 2
    end if
    let host = build_host_facts()
    let r = profile.diff(argv[0], host.home, host)
    if rg.is_err(r)
        console.printErr("repoman: error: " + rg.unwrap_err(r))
        return 3
    end if
    println(rg.unwrap_ok(r))
    return 0
end cmd_profile_diff

fn cmd_profile_remove(argv: [string]): int
    if argv.length() == 0
        console.printErr("repoman: error: 'profile remove' requires <name>")
        return 2
    end if
    let r = profile.remove_profile(argv[0])
    if rg.is_err(r)
        console.printErr("repoman: error: " + rg.unwrap_err(r))
        return 1
    end if
    println("==> removed " + argv[0] + " from incus")
    return 0
end cmd_profile_remove

fn cmd_profile_show(argv: [string]): int
    if argv.length() == 0
        console.printErr("repoman: error: 'profile show' requires <name>")
        return 2
    end if
    let host = build_host_facts()
    let r = profile.show(argv[0], host.home, host)
    if rg.is_err(r)
        console.printErr("repoman: error: " + rg.unwrap_err(r))
        return 3
    end if
    println(rg.unwrap_ok(r))
    return 0
end cmd_profile_show
```

- [ ] **Step 3: Wire into the dispatcher**

Find the `dispatch` function. Add a `profile` arm in alphabetical position (between `new` and `remove`, or wherever fits):

```reef
    if cmd == "profile"
        return cmd_profile(rest)
    end if
```

- [ ] **Step 4: Update print_usage**

Add `profile` to the help text:

```reef
    console.printErr("  profile {list|install|diff|remove|show} [<name>] [--all]")
    console.printErr("      Manage Incus profiles from the repoman library.")
    console.printErr("")
```

Place it after `new`'s entry, before `remove`'s entry (alphabetical).

Also update setup's help text to drop the `--with-llm` mention:

```reef
    console.printErr("  setup [--non-interactive]")
    console.printErr("      First-time host bootstrap: incus project + registry.")
```

- [ ] **Step 5: Build and verify**

```bash
make build
./build/repoman --help
./build/repoman profile
```

Expected: `--help` shows the `profile` line; `profile` (no verb) prints the error message.

- [ ] **Step 6: Commit**

```bash
hg add src/cli.reef
hg commit -m "cli: cmd_profile dispatch for list/install/diff/remove/show; update print_usage"
```

---

## Task 21: Author the three vendor profile YAML files

**Files:**
- Create: `profiles/claude-share.yml`
- Create: `profiles/llm-share.yml`
- Create: `profiles/dotfiles.yml`

- [ ] **Step 1: Create profiles directory and the three YAML files**

```bash
mkdir -p profiles
```

Create `profiles/claude-share.yml`:

```yaml
name: claude-share
description: Share host's Claude CLI state (auth, history, plugins) into containers.
config: {}
devices:
  claude-state:
    type: disk
    source: ${HOME}/.claude
    path: ${HOME}/.claude
    shift: "true"
  claude-bin:
    type: disk
    source: ${HOME}/.local/bin/claude
    path: /usr/local/bin/claude
    readonly: "true"
    shift: "true"
```

Create `profiles/llm-share.yml`:

```yaml
name: llm-share
description: Wire containers to the host ollama daemon over LAN.
config:
  environment.OLLAMA_HOST: "http://${HOST_LAN_IP}:11434"
devices:
  ollama-bin:
    type: disk
    source: /usr/local/bin/ollama
    path: /usr/local/bin/ollama
    readonly: "true"
  ollama-state:
    type: disk
    source: ${HOME}/.ollama
    path: ${HOME}/.ollama
    shift: "true"
```

Create `profiles/dotfiles.yml`:

```yaml
name: dotfiles
description: Bind common host dotfiles (.gitconfig, .hgrc) into containers.
config: {}
devices:
  gitconfig:
    type: disk
    source: ${HOME}/.gitconfig
    path: ${HOME}/.gitconfig
    readonly: "true"
    shift: "true"
  hgrc:
    type: disk
    source: ${HOME}/.hgrc
    path: ${HOME}/.hgrc
    readonly: "true"
    shift: "true"
```

- [ ] **Step 2: Commit**

```bash
hg add profiles/claude-share.yml profiles/llm-share.yml profiles/dotfiles.yml
hg commit -m "profiles: vendor library — claude-share, llm-share, dotfiles"
```

---

## Task 22: `Makefile` — install profiles to `/usr/local/share/repoman/profiles/`

**Files:**
- Modify: `Makefile`

- [ ] **Step 1: Update install/uninstall targets**

Replace the existing `install:` and `uninstall:` targets:

```makefile
PREFIX ?= /usr/local
BINDIR  = $(PREFIX)/bin
SHAREDIR = $(PREFIX)/share/repoman
PROFILES_DIR = $(SHAREDIR)/profiles
DESTDIR ?=

.PHONY: all build test clean install uninstall

all: build

build:
	reefc build

test:
	@for t in tests/test_*.reef; do \
		echo "== $$t =="; \
		reefc run "$$t" || exit 1; \
	done

clean:
	reefc clean

install: build
	install -d $(DESTDIR)$(BINDIR)
	install -m 0755 build/repoman $(DESTDIR)$(BINDIR)/repoman
	install -d $(DESTDIR)$(PROFILES_DIR)
	install -m 0644 profiles/*.yml $(DESTDIR)$(PROFILES_DIR)/

uninstall:
	rm -f $(DESTDIR)$(BINDIR)/repoman
	rm -rf $(DESTDIR)$(PROFILES_DIR)
```

- [ ] **Step 2: Test the install path locally**

```bash
sudo make install
ls /usr/local/share/repoman/profiles/
```

Expected: `claude-share.yml`, `dotfiles.yml`, `llm-share.yml`.

- [ ] **Step 3: Commit**

```bash
hg add Makefile
hg commit -m "Makefile: install profiles/*.yml to /usr/local/share/repoman/profiles/"
```

---

## Task 23: README + VISION + reef.toml + version_string updates

**Files:**
- Modify: `reef.toml`
- Modify: `src/cli.reef` (version_string)
- Modify: `README.md`
- Modify: `VISION.md`

- [ ] **Step 1: Bump version**

In `reef.toml`, change `version = "0.3.0"` to `version = "0.4.0"`.

In `src/cli.reef`, find `version_string()` and change `"repoman 0.3.0"` to `"repoman 0.4.0"`.

- [ ] **Step 2: README — add profile library section, drop --with-llm**

In `README.md`, find the `## Setup wizard` and `## Local LLM stack` sections from v0.3. Replace them with:

```markdown
## Setup wizard

First-time host bootstrap (idempotent — safe to re-run):

    repoman setup                     # interactive
    repoman setup --non-interactive   # accept defaults

The wizard creates the Incus project `repoman`, detects your host LAN IP (used by
profiles that wire containers to host services), and writes the initial registry.

After setup, install the vendor profile library:

    repoman profile install --all

## Profile library

repoman ships a vendor profile library at `/usr/local/share/repoman/profiles/`.
v0.4 includes three profiles:

- **`claude-share`** — bind `~/.claude` and `~/.local/bin/claude` into containers
  so they share the host's Claude CLI auth, history, and plugins.
- **`llm-share`** — bind `/usr/local/bin/ollama` and `~/.ollama` into containers,
  set `OLLAMA_HOST=http://<host-lan-ip>:11434` so containers reach the host's
  ollama daemon over LAN.
- **`dotfiles`** — bind `~/.gitconfig` and `~/.hgrc` (extend with your own).

Manage profiles via `repoman profile`:

    repoman profile list
    repoman profile install <name>
    repoman profile install --all
    repoman profile diff <name>            # show drift between file and incus state
    repoman profile show <name>            # print rendered YAML
    repoman profile remove <name>          # remove from incus (file untouched)

### Customizing profiles

To override a vendor profile, copy it to your user dir and edit:

    cp /usr/local/share/repoman/profiles/dotfiles.yml ~/.config/repoman/profiles.d/
    $EDITOR ~/.config/repoman/profiles.d/dotfiles.yml
    repoman profile install dotfiles       # applies the user version (shadows vendor)

User profiles in `~/.config/repoman/profiles.d/` always win over vendor profiles
of the same name. `repoman profile list` shows the active source for each.

## Migrating from v0.3

If you ran `repoman setup --with-llm` on v0.3, your registry is at schema 2 and
includes a `[defaults.llm]` block. v0.4 reads that block on first load, extracts
the ollama_url's host portion into `[host].lan_ip`, and writes the registry as
schema 3 on the next save. No action required — the migration is automatic and
lossless for the one fact that's still useful.

The `--hermes` / `--no-hermes` / `--purge-hermes` flags are gone. Hermes (and
similar agents that need per-container installs) is now the user's responsibility:
shell into the container with `repoman shell <name>` and run the install yourself.
v0.5+ may revisit this if real demand surfaces.
```

- [ ] **Step 3: VISION.md — update setup row, add profile management**

In `VISION.md`, find the subcommand table. Update the `repoman setup` row description and add a `repoman profile` row:

```markdown
| `repoman setup` | First-time host setup. Creates Incus project `repoman`, detects host LAN IP, writes initial registry. Idempotent. **Shipped in v0.3, trimmed in v0.4 (no longer touches profiles or LLM stack).** |
| `repoman profile {list, install, diff, remove, show}` | Manage Incus profiles from the vendor library at `/usr/local/share/repoman/profiles/` and the user override dir at `~/.config/repoman/profiles.d/`. **Shipped in v0.4.** |
```

- [ ] **Step 4: Build and test**

```bash
make build
./build/repoman --version    # repoman 0.4.0
./build/repoman --help       # shows setup (no --with-llm), profile, etc.
make test
```

Expected: clean.

- [ ] **Step 5: Commit**

```bash
hg add reef.toml src/cli.reef README.md VISION.md
hg commit -m "docs: v0.4 — profile library section, migration guide; bump version"
```

---

## Task 24: End-to-end smoke test

Manual gate before tagging v0.4.0.

**Files:** (no code changes — manual verification)

- [ ] **Step 1: Install and verify version**

```bash
cd ~/repos/repoman
sudo make install
repoman --version              # repoman 0.4.0
ls /usr/local/share/repoman/profiles/   # three YAML files
```

- [ ] **Step 2: Run setup**

```bash
repoman setup --non-interactive
cat ~/.config/repoman/repoman.toml | grep -E 'schema|host|lan_ip'
```

Expected: `schema = 3`, `[host]` block, `lan_ip = "<your br0 IP>"`.

- [ ] **Step 3: Install vendor profile library**

```bash
repoman profile install --all
incus profile list --project default | grep -E 'claude-share|llm-share|dotfiles'
```

Expected: all three profiles present in incus.

- [ ] **Step 4: Verify rendered profiles**

```bash
incus profile show --project default llm-share | grep OLLAMA_HOST
# expect: environment.OLLAMA_HOST: http://<your-lan-ip>:11434

incus profile show --project default claude-share | grep '/home/'
# expect: /home/<your-user>/.claude paths
```

- [ ] **Step 5: Test profile diff and show**

```bash
repoman profile show claude-share | head -20
repoman profile diff claude-share
# expect "(no drift)" since we just installed it
```

- [ ] **Step 6: Test pre-launch validation**

Edit `~/.config/repoman/repoman.toml` to add `"missing-profile"` to `[defaults].profiles`. Then:

```bash
mkdir -p ~/repos/smoke-test
echo "smoke" > ~/repos/smoke-test/README.md
repoman new smoke-test
```

Expected: error with hint `repoman profile install missing-profile`. Container is NOT launched.

Revert the registry change.

- [ ] **Step 7: Successful container creation with profiles**

```bash
# Edit registry to use ["default", "claude-share", "llm-share", "dotfiles"] in [defaults].profiles
# OR write an override at ~/.config/repoman/repos.d/smoke-test.toml
repoman new smoke-test
repoman shell smoke-test
# Inside container:
ls -la ~/.claude        # bind-mounted from host
ls -la ~/.gitconfig     # readable
ollama list             # talks to host daemon
exit
```

Expected: all three profiles working.

- [ ] **Step 8: Test user-shadow customization**

```bash
mkdir -p ~/.config/repoman/profiles.d
cp /usr/local/share/repoman/profiles/dotfiles.yml ~/.config/repoman/profiles.d/
# Edit to add a custom bind, e.g., ~/.zshrc
repoman profile install dotfiles
repoman profile list | grep dotfiles
# expect: source = "user (shadows vendor)"
```

- [ ] **Step 9: Cleanup and tag**

```bash
repoman remove smoke-test --yes
rm -rf ~/repos/smoke-test
hg tag v0.4.0
hg log -r tip --template "{node|short} {desc|firstline}\n"
```

If everything in steps 1-8 worked, **v0.4.0 ships.**

---

## Self-review

### Spec coverage check

- §1 In-scope items:
  - Profile library layout (vendor + user) → T9, T10, T11, T12
  - `repoman profile {list, install, diff, remove, show}` → T13, T14, T15, T20
  - Templated YAML with `${VAR}` → T10
  - `[host].lan_ip` field → T1, T2, T17
  - Schema 2 → 3 migration → T2, T4, T5, T6
  - Three vendor profiles → T21
  - Pre-launch validation → T19
- §1 Trims:
  - `--with-llm` / `--without-llm` flags removed → T18
  - ollama LAN-listening check removed → T16
  - `[defaults].llm` block removed → T1, T3
  - String template embedded in setup.reef removed → T16
  - apply_stage llm_share_profile and registry_defaults trim → T17
- §2 Architecture:
  - `src/profile.reef` new module → T9–T15
  - `setup.reef` edits → T16, T17, T18
  - `cli.reef` edits → T19, T20
  - `config.reef` edits → T1, T2, T3, T4, T5
  - `incus.reef` `profile_get` and `delete_profile` → T8, T14
- §3 Data shapes — all covered (Schema 3, profile YAMLs, ProfileEntry, HostFacts)
- §4 Subcommand flows — all covered
- §5 Testing — pure tests in T6, T10; smoke in T24
- §7 Decisions — locked into spec, not implementation tasks

### Placeholder scan

No "TBD"/"TODO" in the plan. Each step has either runnable shell or complete reef code.

### Type-consistency check

- `Host` struct: `lan_ip: string` consistently across T1, T2, T6, T17.
- `Registry` field order: `schema, host, output, defaults, projects` — used consistently in T1, T6, T17.
- `ProfileEntry` fields: name, source, file_path, installed — consistent T9, T12, T20.
- `HostFacts` fields: lan_ip, user, home — consistent T9, T10, T13, T14, T15, T20.
- `profile.remove_profile` (NOT `profile.remove`) — consistent T9, T14, T20.
- `incus.delete_profile` (new in T14) used in T14.
- `incus.profile_get` (new in T8) used in T15.
- `plan_stages(env)` (no `with_llm` arg after T17) — used in T17, T18.
- `apply_stage(stage, env, reg)` signature — unchanged, used in T17.

### Task ordering / dependency check

T1–T7 (config schema): linear sequence; each builds on the prior. ✓
T8 (incus.profile_get): independent; can land anywhere before T15. ✓
T9–T15 (profile module): T9 stub first, T10 paths/render, T11 lookup uses paths, T12 list_all uses lookup, T13 install uses lookup+render, T14 remove (small) + show (uses lookup+render), T15 diff (uses everything). ✓
T16–T18 (setup trim): each builds on the prior — T16 first (struct + helpers), T17 next (planner), T18 last (CLI integration). ✓
T19 (cmd_new validation): independent; needs T8 indirectly via incus.profile_exists which already exists. ✓
T20 (cmd_profile dispatch): depends on profile module (T9–T15) being complete. ✓
T21 (vendor YAMLs): independent file authoring. ✓
T22 (Makefile): depends on T21 (files must exist). ✓
T23 (docs + version): can land anywhere; placed near end as polish. ✓
T24 (smoke): final gate. ✓

No circular deps.

---

## Deferred (v0.5+ candidates)

- `repoman profile diff --vendor` (shadow-vs-vendor diff): noted in spec §7 as resolved decision; implementation deferred.
- `optional: true` on bind-mount sources for dotfiles (so missing files don't break launch): blocked on incus version support; reassess at v0.5.
- Smarter unified diff in `profile diff` instead of side-by-side: low value for v0.4 use cases.
- Setup wizard configuring ollama (installer + systemd override): explicitly rejected as out of mission scope.
- Pre-built incus images (`repoman image {build, refresh, list, prune}`): rejected as maintenance overhead.
- Per-project `[install]` block in override files: rejected — shell scripts in user repos serve this need.
# repoman rename — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a `repoman rename <old> <new>` subcommand that renames a project across every layer that encodes its name — incus container, `repo` bind device, host repo dir, registry entry, and (opt-in) Claude history slug — idempotently.

**Architecture:** A pure registry mutation (`config.rename_project`) mirrors the existing `update_last_sync` helper and is unit-tested via TDD. Four thin `run_incus` wrappers add the incus verbs the command needs. `cli.cmd_rename` orchestrates the layers using the existing `cmd_remove` skeleton (load → resolve → guard → confirm → log → mutate → save), inspecting each layer's state and changing only what's still on the old name.

**Tech Stack:** Reef 0.7.5 (reefc on PATH), incus CLI, Mercurial (`hg`). Build: `reefc build`. Test: `reefc run tests/<file>.reef` and `make test`.

## Global Constraints

- Reef **0.7.5** stdlib: fallible stdlib ops return `result.Result`/`option.Option`. Repoman keeps its own `rg.Result[T, string]` convention (`import core.result as rg`) and converts stdlib `error.Error` → string at boundaries via `error.error_message(e)`.
- Result construction is `@Result[T, string].Ok(...)` / `.Err(...)` (bare `Result`, resolves to `core.result`).
- Reef syntax: `fn name(...): T ... end name`; `proc name(...) ... end name`; `mut`/`let`; `while ... end while`; `if ... end if`; string concat with `+`; array alloc `new [T](n)`; `.length()`; index `a[i]`.
- Every new source file starts with the header from `SRCHEADER.txt` (fill `Project: repoman`, `Filename:`, `Description:`).
- Incus project for all containers: `reg.defaults.incus_project` (value `repoman`).
- Author for commits: `Chris Tusa <chris.tusa@leafscale.com>`. VCS is **Mercurial** — commit with `hg commit -u "<author>" -m "<msg>" <files>`. Never `git`.
- `container_state(project, name)` returns `"RUNNING"`, `"STOPPED"`, the raw state string, or `"MISSING"` when the container does not exist.

---

## File Structure

- **`src/config.reef`** — add `rename_project` (registry mutation) + export. Owns registry logic.
- **`src/incus.reef`** — add `stop`, `start`, `rename_container`, `device_set` wrappers + exports. Owns incus CLI shelling.
- **`src/cli.reef`** — add `cmd_rename`, wire into `dispatch` + `print_usage` + the `export` block. Owns subcommand orchestration + user I/O.
- **`tests/test_config_rename.reef`** — new. Unit tests for `rename_project`.
- **`README.md`** — document the `rename` subcommand.

---

## Task 1: `config.rename_project` registry mutation (TDD)

**Files:**
- Create: `tests/test_config_rename.reef`
- Modify: `src/config.reef` (add to `export` block near line 44; add fn after `remove_project`, ~line 490)

**Interfaces:**
- Consumes: `config.Registry`, `config.Project`, `config.Defaults`, `config.Host`, `config.with_projects` (existing).
- Produces: `fn rename_project(reg: Registry, old: string, new_name: string): rg.Result[Registry, string]` — renames the project named `old` to `new_name`; sets `repo = new_name` **iff** the old `repo == old` (coupled dirname), else leaves `repo` unchanged; `Err` if `old` absent or `new_name` already used by a different project. NOTE: `new` is a reserved keyword in Reef (array allocation), so the parameter is `new_name`.

- [ ] **Step 1: Write the failing test**

Create `tests/test_config_rename.reef` (header from `SRCHEADER.txt`, Description: `Tests: rename_project registry mutation`):

```reef
import config
import test.framework
import core.result as rg

fn empty_defaults(): config.Defaults
    return config.Defaults {
        repos_root: "/r", backup_root: "/b", logdir: "/l", incus_project: "p",
        default_image: "img", profiles: new [string](0)
    }
end empty_defaults

fn mk_project(name: string, repo: string): config.Project
    return config.Project {
        name: name, repo: repo, image: "img",
        profiles: new [string](0), created: "t", last_sync: "", backup: true
    }
end mk_project

proc main()
    let runner = new framework.TestRunner()

    // Two projects: a coupled one (name==repo) and a decoupled one (name!=repo).
    mut projs: [config.Project] = new [config.Project](2)
    projs[0] = mk_project("driftohm", "driftohm")
    projs[1] = mk_project("portal", "leafscale-infrastructure/portal.leafscale.com")
    let reg0: config.Registry = config.Registry {
        schema: 3, host: config.Host { lan_ip: "" }, output: "quiet",
        defaults: empty_defaults(), projects: projs
    }

    // Coupled rename: both name and repo move.
    let r1 = config.rename_project(reg0, "driftohm", "mist")
    runner.assert_eq_bool(rg.is_ok(r1), true, "coupled rename ok")
    if rg.is_ok(r1)
        let reg1 = rg.unwrap_ok(r1)
        runner.assert_eq_string(reg1.projects[0].name, "mist", "coupled: name moved")
        runner.assert_eq_string(reg1.projects[0].repo, "mist", "coupled: repo moved in lockstep")
        runner.assert_eq_string(reg1.output, "quiet", "output preserved through rename_project")
    end if

    // Decoupled rename: only name moves, repo (nested path) preserved.
    let r2 = config.rename_project(reg0, "portal", "gateway")
    runner.assert_eq_bool(rg.is_ok(r2), true, "decoupled rename ok")
    if rg.is_ok(r2)
        let reg2 = rg.unwrap_ok(r2)
        runner.assert_eq_string(reg2.projects[1].name, "gateway", "decoupled: name moved")
        runner.assert_eq_string(reg2.projects[1].repo, "leafscale-infrastructure/portal.leafscale.com", "decoupled: repo dirname preserved")
    end if

    // Collision: rename onto an existing project name fails.
    let r3 = config.rename_project(reg0, "driftohm", "portal")
    runner.assert_eq_bool(rg.is_err(r3), true, "rename onto existing name rejected")

    // Unknown source name fails.
    let r4 = config.rename_project(reg0, "ghost", "whatever")
    runner.assert_eq_bool(rg.is_err(r4), true, "unknown source name rejected")

    runner.report()
end main
```

- [ ] **Step 2: Run test to verify it fails**

Run: `reefc run tests/test_config_rename.reef`
Expected: FAIL — compile/type error `rename_project` is not a member of `config` (function not defined yet).

- [ ] **Step 3: Add the export declaration**

In `src/config.reef`, inside the `export` block, add after the `remove_project` line (~line 44):

```reef
    fn rename_project(reg: Registry, old: string, new_name: string): rg.Result[Registry, string]
```

- [ ] **Step 4: Implement `rename_project`**

In `src/config.reef`, add after `remove_project` (~line 490, before `end module`):

```reef
// Rename the project named `old` to `new`. The repo dirname moves in lockstep
// only when it was coupled to the old name (repo == old); a deliberately
// decoupled dirname (e.g. a nested monorepo path) is preserved. Errors if `old`
// is absent or `new` is already used by a different project.
fn rename_project(reg: Registry, old: string, new_name: string): rg.Result[Registry, string]
    let n: int = reg.projects.length()
    mut found: int = -1
    mut i: int = 0
    while i < n
        if reg.projects[i].name == old
            found = i
        end if
        i = i + 1
    end while

    if found < 0
        return @Result[Registry, string].Err("project not in registry: " + old)
    end if

    mut j: int = 0
    while j < n
        if j != found and reg.projects[j].name == new_name
            return @Result[Registry, string].Err("project already exists: " + new_name)
        end if
        j = j + 1
    end while

    mut new_projects: [Project] = new [Project](n)
    mut k: int = 0
    while k < n
        if k == found
            let old_p: Project = reg.projects[k]
            mut new_repo: string = old_p.repo
            if old_p.repo == old
                new_repo = new_name
            end if
            new_projects[k] = Project {
                name: new_name, repo: new_repo, image: old_p.image,
                profiles: old_p.profiles, created: old_p.created,
                last_sync: old_p.last_sync, backup: old_p.backup
            }
        else
            new_projects[k] = reg.projects[k]
        end if
        k = k + 1
    end while

    return @Result[Registry, string].Ok(with_projects(reg, new_projects))
end rename_project
```

- [ ] **Step 5: Run test to verify it passes**

Run: `reefc run tests/test_config_rename.reef`
Expected: PASS — `All tests passed!`, Tests failed: 0.

- [ ] **Step 6: Commit**

```bash
hg commit -u "Chris Tusa <chris.tusa@leafscale.com>" \
  -m "config: add rename_project registry mutation" \
  src/config.reef tests/test_config_rename.reef
```

---

## Task 2: incus verb wrappers (`stop`, `start`, `rename_container`, `device_set`)

**Files:**
- Modify: `src/incus.reef` (add to `export` block ~line 45; add fns near `restart` ~line 364)

**Interfaces:**
- Consumes: `run_incus(args: [string]): rg.Result[bool, string]` (existing).
- Produces:
  - `fn stop(project: string, name: string): rg.Result[bool, string]`
  - `fn start(project: string, name: string): rg.Result[bool, string]`
  - `fn rename_container(project: string, old: string, new_name: string): rg.Result[bool, string]`
  - `fn device_set(project: string, name: string, dev: string, keyvals: [string]): rg.Result[bool, string]`

- [ ] **Step 1: Add the export declarations**

In `src/incus.reef`, inside the `export` block (before `end export`, ~line 45), add:

```reef
    fn stop(project: string, name: string): rg.Result[bool, string]
    fn start(project: string, name: string): rg.Result[bool, string]
    fn rename_container(project: string, old: string, new_name: string): rg.Result[bool, string]
    fn device_set(project: string, name: string, dev: string, keyvals: [string]): rg.Result[bool, string]
```

- [ ] **Step 2: Implement the wrappers**

In `src/incus.reef`, add immediately after `restart` (~line 364):

```reef
fn stop(project: string, name: string): rg.Result[bool, string]
    return run_incus(["stop", "--project", project, name])
end stop

fn start(project: string, name: string): rg.Result[bool, string]
    return run_incus(["start", "--project", project, name])
end start

fn rename_container(project: string, old: string, new_name: string): rg.Result[bool, string]
    return run_incus(["rename", "--project", project, old, new_name])
end rename_container

// incus config device set <container> <device> <key>=<val> ...
fn device_set(project: string, name: string, dev: string, keyvals: [string]): rg.Result[bool, string]
    let kn: int = keyvals.length()
    mut args: [string] = new [string](7 + kn)
    args[0] = "config"
    args[1] = "device"
    args[2] = "set"
    args[3] = "--project"
    args[4] = project
    args[5] = name
    args[6] = dev
    mut i: int = 0
    while i < kn
        args[7 + i] = keyvals[i]
        i = i + 1
    end while
    return run_incus(args)
end device_set
```

- [ ] **Step 3: Build to verify it compiles**

Run: `reefc build`
Expected: `Build complete: build/repoman` (stdlib exhaustiveness warnings are pre-existing and fine).

- [ ] **Step 4: Commit**

```bash
hg commit -u "Chris Tusa <chris.tusa@leafscale.com>" \
  -m "incus: add stop/start/rename_container/device_set wrappers" \
  src/incus.reef
```

---

## Task 3: `cmd_rename` orchestration + dispatch/usage wiring

**Files:**
- Modify: `src/cli.reef` (add to `export` block ~line 48; add `cmd_rename` before `dispatch` ~line 1000; add `rename` branch in `dispatch` ~line 1049; add usage line in `print_usage` ~line 995)

**Interfaces:**
- Consumes: `config.load_or_init`, `config.registry_path`, `config.rename_project`, `config.save`, `config.Registry`, `config.Project` (existing + Task 1); `incus.validate_name`, `incus.container_state`, `incus.stop`, `incus.start`, `incus.rename_container`, `incus.device_set` (existing + Task 2); `paths.expand_home`, `paths.join`, `paths.is_dir`; `iofile.rename`; `error.error_message`; `log.open_log`, `log.write`; `flag.*`; `console.*`; `str.replace`.
- Produces: `fn cmd_rename(argv: [string]): int` wired into `dispatch` on subcommand `"rename"`.

- [ ] **Step 1: Add the export declaration**

In `src/cli.reef`, inside the `export` block, add after the `cmd_remove` line (~line 46):

```reef
    fn cmd_rename(argv: [string]): int
```

- [ ] **Step 2: Implement `cmd_rename`**

In `src/cli.reef`, add before `fn dispatch` (~line 1000):

```reef
// Build the Claude history slug directory for a repo path: the absolute
// container-internal cwd with '/' replaced by '-' (e.g. /home/u/repos/x ->
// -home-u-repos-x), under ~/.claude/projects/.
fn claude_slug_dir(home: string, repo_path: string): string
    let slug: string = str.replace(repo_path, "/", "-")
    return paths.join(home, ".claude/projects/" + slug)
end claude_slug_dir

fn cmd_rename(argv: [string]): int
    let parser: flag.FlagParser = flag.flag_parser_from(argv)
    flag.application(parser, "repoman rename")
    flag.description(parser, "Rename a project across container, registry, and repo dir")
    let _y  = flag.bool_flag(parser, "yes", 'y', false, "skip confirmation prompt")
    let _mh = flag.bool_flag(parser, "migrate-claude-history", '\0', false, "also move the Claude history slug dir")
    if not flag.parse(parser)
        console.printErr("repoman: error: " + flag.error(parser))
        return 2
    end if

    let positionals: [string] = flag.positional_args(parser)
    if positionals.length() != 2
        console.printErr("repoman: error: 'rename' takes exactly two arguments: <old> <new>")
        return 2
    end if
    let old: string = positionals[0]
    let new_name: string = positionals[1]
    let do_history: bool = flag.get_bool(parser, "migrate-claude-history")

    if old == new_name
        console.printErr("repoman: error: <old> and <new> are the same: " + old)
        return 2
    end if
    if not incus.validate_name(new_name)
        console.printErr("repoman: error: invalid new name: " + new_name)
        console.printErr("hint: lowercase alphanumeric + hyphens, <=63 chars, no leading hyphen")
        return 1
    end if

    let home: string = env.get_env_or("HOME", "")
    if str.length(home) == 0
        console.printErr("repoman: error: HOME is not set")
        return 3
    end if

    let cfg_path: string = config.registry_path(home)
    let reg_r = config.load_or_init(home)
    if rg.is_err(reg_r)
        console.printErr("repoman: error: " + rg.unwrap_err(reg_r))
        return 3
    end if
    let reg: config.Registry = rg.unwrap_ok(reg_r)

    // Resolve the target project. Idempotent: accept either the old name
    // (normal) or the new name (registry layer already renamed on a re-run).
    let pn: int = reg.projects.length()
    mut old_idx: int = -1
    mut new_idx: int = -1
    mut i: int = 0
    while i < pn
        if reg.projects[i].name == old
            old_idx = i
        end if
        if reg.projects[i].name == new_name
            new_idx = i
        end if
        i = i + 1
    end while
    if old_idx < 0 and new_idx < 0
        console.printErr("repoman: error: no such project: " + old)
        return 1
    end if
    if old_idx >= 0 and new_idx >= 0
        console.printErr("repoman: error: both '" + old + "' and '" + new_name + "' exist in the registry; refusing to merge")
        return 1
    end if
    mut base_idx: int = old_idx
    if base_idx < 0
        base_idx = new_idx
    end if
    let proj: config.Project = reg.projects[base_idx]

    // The directory tier applies only when the repo dirname was coupled to the
    // name (repo == old, or == new_name on a resumed run). A decoupled dirname
    // is left alone.
    let coupled: bool = proj.repo == old or proj.repo == new_name
    let repos_root: string = paths.expand_home(reg.defaults.repos_root)
    let old_dir: string = paths.join(repos_root, old)
    let new_dir: string = paths.join(repos_root, new_name)
    let inc_project: string = reg.defaults.incus_project

    // Confirmation (case-aware).
    let auto_confirmed: bool = flag.get_bool(parser, "yes")
    if not auto_confirmed
        println("repoman rename " + old + " " + new_name)
        println("  will move:")
        println("    - incus container   " + old + " -> " + new_name)
        println("    - registry entry    " + old + " -> " + new_name)
        if coupled
            println("    - repo directory    " + old_dir + " -> " + new_dir)
            if do_history
                println("    - claude history    (slug for " + new_dir + ")")
            end if
            println("  your source is moved intact, never deleted.")
        else
            println("  repo directory unchanged (" + paths.join(repos_root, proj.repo) + ")")
            println("  -- this project's dir name is decoupled from its container name.")
        end if
        let proceed: bool = console.confirm_default_no("continue?")
        if not proceed
            println("aborted")
            return 4
        end if
    end if

    let _ol: bool = log.open_log(reg.defaults.logdir, new_name, "rename")

    // Inspect container run-state for both names.
    mut state_old: string = "MISSING"
    let so_r = incus.container_state(inc_project, old)
    if rg.is_ok(so_r)
        state_old = rg.unwrap_ok(so_r)
    end if
    mut state_new: string = "MISSING"
    let sn_r = incus.container_state(inc_project, new_name)
    if rg.is_ok(sn_r)
        state_new = rg.unwrap_ok(sn_r)
    end if
    if state_old != "MISSING" and state_new != "MISSING"
        log.write("repoman: error: containers '" + old + "' and '" + new_name + "' both exist; refusing to merge")
        return 1
    end if
    let was_running: bool = state_old == "RUNNING" or state_new == "RUNNING"

    // Step: stop the container (whichever name it currently has) if running.
    if state_old == "RUNNING"
        log.write("==> incus stop " + old)
        let r = incus.stop(inc_project, old)
        if rg.is_err(r)
            log.write("repoman: error: " + rg.unwrap_err(r))
            return 1
        end if
    elif state_new == "RUNNING"
        log.write("==> incus stop " + new_name)
        let r = incus.stop(inc_project, new_name)
        if rg.is_err(r)
            log.write("repoman: error: " + rg.unwrap_err(r))
            return 1
        end if
    end if

    // Step: host repo dir (coupled only).
    if coupled
        if paths.is_dir(old_dir) and not paths.is_dir(new_dir)
            log.write("==> mv " + old_dir + " -> " + new_dir)
            let mv_r = iofile.rename(old_dir, new_dir)
            if rg.is_err(mv_r)
                log.write("repoman: error: cannot move repo dir: " + error.error_message(rg.unwrap_err(mv_r)))
                log.write("hint: move it manually then re-run 'repoman rename " + old + " " + new_name + "'")
                return 1
            end if
        elif paths.is_dir(new_dir)
            log.write("==> repo dir already at " + new_dir + " (skipping)")
        else
            log.write("repoman: error: repo directory not found: " + old_dir)
            return 1
        end if
    end if

    // Step: rename the container.
    if state_old != "MISSING"
        log.write("==> incus rename " + old + " -> " + new_name)
        let rn_r = incus.rename_container(inc_project, old, new_name)
        if rg.is_err(rn_r)
            log.write("repoman: error: " + rg.unwrap_err(rn_r))
            return 1
        end if
    elif state_new != "MISSING"
        log.write("==> container already named " + new_name + " (skipping rename)")
    else
        log.write("==> no incus container for '" + old + "' (skipping rename)")
    end if

    // Step: repoint the repo device (coupled only), on the now-new container.
    if coupled and (state_old != "MISSING" or state_new != "MISSING")
        log.write("==> incus config device set " + new_name + " repo source/path -> " + new_dir)
        let ds_r = incus.device_set(inc_project, new_name, "repo", ["source=" + new_dir, "path=" + new_dir])
        if rg.is_err(ds_r)
            log.write("repoman: error: " + rg.unwrap_err(ds_r))
            return 1
        end if
    end if

    // Step: registry (skip if already renamed on a resumed run).
    if old_idx >= 0
        let reg2_r = config.rename_project(reg, old, new_name)
        if rg.is_err(reg2_r)
            log.write("repoman: error: " + rg.unwrap_err(reg2_r))
            return 1
        end if
        let saved = config.save(rg.unwrap_ok(reg2_r), cfg_path)
        if rg.is_err(saved)
            log.write("repoman: error: " + rg.unwrap_err(saved))
            return 1
        end if
    end if

    // Step: Claude history slug (coupled + opt-in).
    if coupled and do_history
        let old_slug: string = claude_slug_dir(home, old_dir)
        let new_slug: string = claude_slug_dir(home, new_dir)
        if paths.is_dir(old_slug) and not paths.is_dir(new_slug)
            log.write("==> mv claude history " + old_slug + " -> " + new_slug)
            let hs_r = iofile.rename(old_slug, new_slug)
            if rg.is_err(hs_r)
                log.write("repoman: warning: could not move claude history: " + error.error_message(rg.unwrap_err(hs_r)))
            end if
        elif paths.is_dir(new_slug)
            log.write("==> claude history already at new slug (skipping)")
        else
            log.write("==> no claude history dir for old name (skipping)")
        end if
    end if

    // Step: restart if it was running before.
    if was_running
        log.write("==> incus start " + new_name)
        let st_r = incus.start(inc_project, new_name)
        if rg.is_err(st_r)
            log.write("repoman: error: " + rg.unwrap_err(st_r))
            return 1
        end if
    end if

    log.write("==> renamed '" + old + "' -> '" + new_name + "'")
    return 0
end cmd_rename
```

- [ ] **Step 3: Wire into `dispatch`**

In `src/cli.reef` `fn dispatch`, add after the `remove` branch (~line 1040):

```reef
    if sub == "rename"
        return cmd_rename(rest)
    end if
```

- [ ] **Step 4: Add the usage line**

In `src/cli.reef` `proc print_usage`, add after the `remove` block (~line 994, before the `shell` block):

```reef
    console.printErr("")
    console.printErr("  rename <old> <new> [--yes | -y] [--migrate-claude-history]")
    console.printErr("      Rename a project: incus container, registry, and (coupled) repo dir. Idempotent.")
```

- [ ] **Step 5: Build to verify it compiles**

Run: `reefc build`
Expected: `Build complete: build/repoman`.

- [ ] **Step 6: Verify help + arg validation (no incus needed)**

Run: `./build/repoman --help 2>&1 | grep rename`
Expected: the `rename <old> <new> ...` usage line prints.

Run: `./build/repoman rename onlyone 2>&1`
Expected: `repoman: error: 'rename' takes exactly two arguments: <old> <new>` and exit 2.

Run: `./build/repoman rename a 'bad/name' 2>&1`
Expected: `repoman: error: invalid new name: bad/name` and exit 1.

- [ ] **Step 7: Full unit-test suite still green**

Run: `make test`
Expected: exit 0; every suite reports `Tests failed: 0`; the claude-launcher shell test passes.

- [ ] **Step 8: Manual integration recipe (documented; run against a scratch project)**

On a host with incus, using a throwaway project:
1. `./build/repoman new scratchone` — creates container + `~/repos/scratchone`.
2. `./build/repoman rename scratchone scratchtwo` — confirm at the prompt.
   - Assert: `incus list --project repoman` shows `scratchtwo`, not `scratchone`.
   - Assert: `incus config device show scratchtwo --project repoman` → `repo` device `source`/`path` = `~/repos/scratchtwo`.
   - Assert: `~/repos/scratchtwo` exists, `~/repos/scratchone` gone.
   - Assert: `./build/repoman list` shows `scratchtwo`/`scratchtwo`.
   - Assert: container run-state matches its pre-rename state.
3. Re-run `./build/repoman rename scratchone scratchtwo --yes` — asserts idempotency: succeeds as a no-op (registry has `scratchtwo`, dir already moved), no errors.
4. Clean up: `./build/repoman remove scratchtwo --yes`.

- [ ] **Step 9: Commit**

```bash
hg commit -u "Chris Tusa <chris.tusa@leafscale.com>" \
  -m "cli: add 'repoman rename' subcommand" \
  src/cli.reef
```

---

## Task 4: Document the `rename` subcommand in README

**Files:**
- Modify: `README.md` (subcommand list / usage section)

**Interfaces:**
- Consumes: nothing (docs).
- Produces: user-facing docs for `rename`.

- [ ] **Step 1: Add the rename row to README's subcommand table**

`README.md` documents subcommands as a markdown table (`## Subcommands`, header `| Subcommand | Description |`, ~line 76). Insert a new row immediately after the `remove` row (line 85), matching the table format:

```markdown
| `rename <old> <new> [--yes | -y] [--migrate-claude-history]` | Rename a project across its incus container, registry entry, and — when the repo dirname is coupled to the name — the host repo directory and `repo` bind device. Idempotent (safe to re-run after a partial rename). `--migrate-claude-history` also moves the repo's Claude history directory. A project whose `repo` dirname is deliberately decoupled from its name has only its identity renamed; the repo directory is left untouched. |
```

- [ ] **Step 2: Commit**

```bash
hg commit -u "Chris Tusa <chris.tusa@leafscale.com>" \
  -m "docs: document 'repoman rename' in README" \
  README.md
```

---

## Notes for the implementer

- **No incus/filesystem mock layer exists** in repoman; existing suites (`test_config_*`, `test_paths`, `test_hermes_*`) are pure-logic. Task 1 is the only fully-automated test surface. Tasks 2–3 are build-verified plus the Task 3 Step 8 manual recipe — this matches the project's established test reality; do not invent a mock harness.
- **Version bump is out of scope for this plan.** After merge, the release is cut separately via `./scripts/bump-version.sh --patch` (repoman's lockstep bumper), taking **0.7.0 → 0.7.1** — a patch bump, not a minor. Not part of feature work.
- If `iofile.rename` returns `EXDEV` (cross-filesystem) on the host-dir move, that surfaces as the `Err` in Task 3 Step 2's dir block, which already tells the user to move the dir manually and re-run — idempotency finishes the rest.
# repoman v0.1 — Design Spec

**Status:** v0.1 design, locked
**Date:** 2026-04-29
**Implementation language:** reef-lang 0.5.10
**Origin:** [VISION.md](../../../VISION.md) (intent) + bash prototype at `~/.local/bin/repoman` (behavioral spec for `new`/`sync`)
**Outcome:** the contract for the first reef build of repoman.

---

## Reef version target

This spec targets **reef 0.5.10**, which shipped the stdlib additions requested in [`docs/reef-feedback.md`](../../reef-feedback.md) (response in [`docs/reef-feedback-response.md`](../../reef-feedback-response.md)). All four feedback sprints landed in a single 0.5.10 release on 2026-04-29:

- `io.path.expand_home`, `io.path.join` (canonical synonym for `join_path`).
- `test.framework.assert_contains_string`, `assert_ok_int/_str/_bool`, `assert_err_int/_str/_bool`.
- `encoding.toml.toml_parse_status`, `encoding.json.json_parse_status` (truncation-aware parse).
- `io.file.rename`, `io.file.fsync` (atomic-write primitives; parent-directory fsync still pending).
- `sys.flag.flag_parser_from(args)` for sliced argv (subcommand dispatch).
- `core.result_generic` — `Result[T, E]` with `is_ok`, `is_err`, `unwrap_ok`, `unwrap_err`, `unwrap_or`. Construction uses explicit type args: `@Result[int, string].Ok(42)`. Cross-module use unblocked by BUG-037 fix in the same release.
- `encoding.toml.TomlDoc` + `toml_parse_doc` (struct-bundled parse output, replacing parallel-array threading).
- `encoding.toml.TomlBuilder` and `encoding.json.JsonBuilder` (streaming serializers — closes the reader-without-writer asymmetry).

**Deferred to 0.5.11** (does not affect repoman v0.1):
- Cobra-style declarative `subcommand_parser` API. Phase 1 (`flag_parser_from`) is sufficient for repoman's subcommand dispatch — we hand-roll the outer dispatch on `argv[1]`, then feed each subcommand a sliced argv.
- `expand_user("~user/...")`. Current `expand_home` passes `~user/...` through unchanged.

§2 (architecture's CLI parser hedge) and §3.4 (atomic-write fsync hedge) were originally written against 0.5.9 workarounds. They have been retargeted to the 0.5.10 APIs in rev 3.

---

## 1. Scope

v0.1 is "match-then-surpass": ship feature-parity with the bash prototype's two subcommands plus the one v0.1-only differentiator that's cheap to add now and expensive to retrofit (the Incus `project` namespace). Everything else from VISION (the remaining subcommands, REST integration, interactive wizard, JSON output mode) is deferred.

**In scope:**
- `repoman new <name> [--repo <dirname>] [--image <img>]`
- `repoman sync [name] [--no-delete] [--dry-run]`
- `repoman --version` / `repoman --help` / `repoman` (no args → full help)
- Central registry at `~/.config/repoman/repoman.toml`
- Per-project overrides at `~/.config/repoman/repos.d/<name>.toml`
- Incus `project repoman` as the namespace for every container repoman creates

**Out of scope (deferred to v0.2 or later):**
- Subcommands: `setup`, `list`, `shell`, `remove`, `status`, `update`, `config`, `adopt`
- Incus REST-over-unix-socket integration (v0.1 shells out to the `incus` CLI)
- Interactive wizard / line-prompt mode for missing args
- Auto-rollback when a `new` step fails midway
- JSON output mode for automation
- CI / public-forge release artifacts (prebuilt binaries)
- Migration from the bash prototype's containers (which live in Incus's `default` project)
- `repoman` config-by-env-var compatibility (`LOCAL_REPOS`/`NFS_REPOS`)
- Incus profile management (e.g., `repoman profile new dotfiles` interactive create/edit). v0.1 expects users to author profiles directly via `incus profile create/edit` and reference them in `[defaults].profiles`. README documents the recommended `dotfiles` profile pattern (bind-mount `~/.hgrc`/`~/.gitconfig`/etc.) for shared host config.
- `[defaults].seed_files` (copy-at-create semantics). Bind-mount via Incus profile is sufficient for the v0.1 dotfiles use case; revisit if a real copy-on-create need surfaces.

---

## 2. Architecture

Six modules under `src/`, no nesting:

| File | Module | Responsibility | Pure? |
|---|---|---|---|
| `src/main.reef` | (entry) | `proc main()` → `cli.dispatch(sys.args.argv())` and exit. | — |
| `src/cli.reef` | `cli` | Subcommand routing, flag parsing, usage/version output. Returns exit codes. Hand-rolls outer dispatch on `argv[1]`, then feeds each subcommand a sliced argv via `sys.flag.flag_parser_from(args)`. Migrates to the declarative `subcommand_parser` API in 0.5.11+. | mostly |
| `src/config.reef` | `config` | Registry types (`Defaults`, `Project`, `Registry`), per-project override (`Override`), `EffectiveConfig`. Load-or-init from disk (atomic write); merge defaults+override. | yes |
| `src/incus.reef` | `incus` | Thin wrappers over the `incus` CLI via `process_spawn(prog, argv)` — `project_ensure`, `container_exists`, `launch`, `bind_repo`, `set_env`, `restart`. Plus pure `validate_name`. | wrappers thin; `validate_name` pure |
| `src/sync.reef` | `sync` | `ensure_nfs_mounted` (stat → mountpoint → findmnt -t nfs4 chain), pure `build_rsync_args(opts)`, effectful `run(opts)` that spawns rsync and inherits stdio. | arg builder pure |
| `src/path.reef` | `path` | `expand_home`, `join`, `exists`, `is_dir`. Thin wrappers over `io.path` / `io.dir`. | yes |

**Boundaries.** Pure logic (TOML schemas, name validation, rsync arg construction, path expansion, defaults merging) is unit-tested. Effectful wrappers (subprocess invocation, NFS mount checks, file write) are kept narrow so they can be smoke-tested via integration but don't need fakes. `core.result_generic` (`Result[T, string]`) carries errors out of every fallible function; `main` translates `Result.Err` into a stderr message + non-zero exit code. Construction syntax is `@Result[T, string].Ok(value)` / `@Result[T, string].Err(msg)` per 0.5.10 generics.

**Subprocess discipline.** Every external invocation goes through `sys.process.process_spawn(program, argv)` — never `process_spawn_shell`. This is non-negotiable: user-derived names (container, repo, paths) must not pass through a shell's word-splitting or globbing.

**Dependency graph.** `main → cli → {config, incus, sync, path}`. `incus` and `sync` are independent of each other. `config` depends only on `encoding.toml`, `io.file`, `path`. No cycles.

**Concurrency.** v0.1 is fully sequential. No Active Objects, no parallel sync. VISION's parallel-sync-across-N-projects idea is a v0.2 candidate.

---

## 3. Data shapes

### 3.1 Central registry — `~/.config/repoman/repoman.toml`

```toml
[repoman]
schema = 1

[defaults]
repos_root     = "~/repos"
backup_root    = "/nfs/repos"
incus_project  = "repoman"
default_image  = "images:ubuntu/26.04/cloud"
profiles       = ["default", "claude-share"]

[[project]]
name        = "isurus"
repo        = "isurus-project"
image       = "images:ubuntu/26.04/cloud"
profiles    = ["default", "claude-share"]
created     = "2026-04-28T15:00:00Z"
last_sync   = ""           # "" = never synced
backup      = true         # false → sync skips
```

**Fields:**
- `[repoman].schema` — registry schema version. v0.1 writes `1`. Loader rejects any other value with a clear error and a hint to upgrade repoman.
- `[defaults].repos_root` / `backup_root` — `~` expanded by `path.expand_home` at load time.
- `[[project]].repo` — repo dirname relative to `repos_root`. Defaults to `name` if unspecified.
- `[[project]].image` and `[[project]].profiles` — **effective** (post-merge) values used at container-create time, snapshotted for the registry. If override `repos.d/<name>.toml` had `[container].profiles`, those (not defaults) get stored here. Stored explicitly so v0.2 `list`/`status` doesn't need to query Incus to display them.
- `[[project]].created` / `last_sync` — ISO 8601 UTC strings. `""` for never.
- `[[project]].backup` — opt-out flag. Default `true`.

### 3.2 Per-project override — `~/.config/repoman/repos.d/<name>.toml`

User-authored before `repoman new`. Optional. Read by `new` only.

```toml
[container]
image    = "images:debian/12/cloud"
profiles = ["default", "claude-share", "node-dev"]

[[mount]]
source = "~/.npm"          # host path, ~ expanded
path   = "/home/ctusa/.npm" # container path

[env]
NODE_ENV = "development"
```

Filename keys off the **container name** (`<name>`), not the repo dirname. So `repoman new isurus --repo isurus-project` reads `repos.d/isurus.toml`.

### 3.3 Merge semantics (`new` only)

Effective config priority:

| Field | Priority |
|---|---|
| `image` | `--image` flag → `override.container.image` → `defaults.default_image` |
| `profiles` | `override.container.profiles` (replace, not merge) → `defaults.profiles` |
| `mounts` | `[auto repo bind]` ++ `override.[[mount]]` (additive; the auto repo bind is always present) |
| `env` | `override.[env]` (key-by-key; empty if absent) |

Replace semantics for `profiles` is deliberate: VISION's example shows the override containing the full profiles list (including the defaults), and predictable replace beats subtle additive surprises.

### 3.4 Atomic write

Central registry is rewritten atomically on every change:
1. `io.file.writeFile("repoman.toml.tmp", contents)` in the same directory as the target.
2. `io.file.fsync("repoman.toml.tmp")` to push contents to disk before the rename.
3. `io.file.rename("repoman.toml.tmp", "repoman.toml")`.

Parent-directory fsync is not yet exposed (per the 0.5.10 changelog), so a power-loss window for the rename itself remains. Acceptable for a homelab dev tool; revisit when the runtime adds it.

TOML serialization is via `encoding.toml.TomlBuilder` from 0.5.10 — explicit `toml_set_string` / `toml_set_string_array` / `toml_array_append_table` for `[[project]]` entries, then `toml_render` to a string.

The override file is never written by repoman in v0.1. User authors it.

### 3.5 Validation on registry load

- `[repoman].schema == 1` — error otherwise.
- All `[[project]].name` values pass `incus.validate_name`.
- No duplicate `name` across `[[project]]` entries.
- `repos_root` and `backup_root` resolve to non-empty strings after `~` expansion.

Failure → `Result.Err` with a clear message including the offending field. Exit code 3 (environment).

---

## 4. Subcommand flows

### 4.1 `repoman new <name> [--repo <dirname>] [--image <img>]`

1. Parse args. `name` required; bad usage → exit 2.
2. `incus.validate_name(name)` — pure check (alnum + hyphen, ≤63, no leading hyphen). Fail → exit 1.
3. `config.load_or_init()` — read or create the registry with default `[repoman]`/`[defaults]`.
4. Reject if `name` already exists in `[[project]]` → exit 4 with hint.
5. Resolve repo path: `<defaults.repos_root>/<repo>`. Error if directory doesn't exist (matches bash) → exit 3.
6. Read `~/.config/repoman/repos.d/<name>.toml` if present; parse into `Override`.
7. Compute `EffectiveConfig` per the merge table in §3.3.
8. `incus.project_ensure(defaults.incus_project)` — list, create if missing. Idempotent.
9. `incus.container_exists(project, name)` — error if already present → exit 4 with `incus delete --project <p> <name>` hint.
10. `incus launch --project <p> --profile P1 --profile P2 ... <image> <name>` (one `process_spawn`).
11. For each effective mount (always: the auto repo bind at `<repo_path>:<repo_path>`; then any override mounts), `incus config device add --project <p> <name> <devname> disk source=<src> path=<dst>`. Device names: `repo` for the auto bind, `mount-N` (N=1..) for overrides.
12. For each `[env]` entry, `incus config set --project <p> <name> environment.KEY=VALUE`.
13. `incus restart --project <p> <name>` so binds and env take effect.
14. Append a `[[project]]` entry with all snapshot fields; `config.save(reg)` atomically.
15. Print "ready" + a correct shell-in hint using `getuid()` and `$HOME` (not hardcoded `1000`/`/home/ctusa` like bash).

**Rollback policy.** v0.1 does **not** auto-destroy on partial-failure. If launch succeeds but a downstream step fails (device-add, env-set, restart, registry write), surface the error and the exact `incus delete --project <p> <name>` command for manual cleanup. v0.2 candidate: `--rollback-on-error`.

### 4.2 `repoman sync [name] [--no-delete] [--dry-run]`

1. Parse args.
2. `config.load_or_init()`.
3. `sync.ensure_nfs_mounted(defaults.backup_root)` — three calls: `stat <backup_root>` (triggers autofs), `mountpoint -q <backup_root>`, `findmnt -t nfs4 <backup_root>`. Each via `process_spawn`. Any failure → exit 3 with a clear message identifying which step failed.
4. Resolve sync target:
   - **With `name`:** find in registry. Missing → exit 1 with hint. `backup = false` → exit 1 (user explicitly asked, refusing is more honest than silent skip). `src = <repos_root>/<repo>/`, `dst = <backup_root>/<repo>/`.
   - **Without `name`:** `src = <repos_root>/`, `dst = <backup_root>/`. Build excludes from the standard list (see §4.3) plus `<repo>/` for every project where `backup = false`.
5. Pure `sync.build_rsync_args(opts)` produces argv. See §4.3 for the full set.
6. Print one-line tag to stderr: `==> rsync (dry-run) (additive) <src> → <dst>` (tags conditional on flags).
7. `process_spawn("rsync", argv)`. Inherit parent stdout/stderr — user sees rsync's progress live; we don't capture or reformat.
8. If rsync exit 0: update `last_sync` to current ISO 8601 UTC and `config.save(reg)` atomically. "Affected" = the named project (single-project mode), or every project where `backup != false` (whole-tree mode).
9. Exit code = rsync's exit code (passthrough). 0 = success; 23 = partial transfer; 24 = vanished files; etc.

### 4.3 rsync invocation

Base flags: `-aHAX`.

Adaptive info flags:
- Dry-run: `--dry-run --itemize-changes --info=stats2`
- Interactive (TTY on stdout): `--info=stats2,progress2`
- Otherwise (cron / piped): `--info=stats2`

Delete: `--delete` unless `--no-delete`.

Excludes (hardcoded for v0.1 — matches bash prototype):
```
node_modules/
target/
build/
dist/
.next/
__pycache__/
*.pyc
.venv/
venv/
.cache/
.tox/
.pytest_cache/
.mypy_cache/
.ruff_cache/
```

Whole-tree mode appends `--exclude=<repo>/` for every project where `backup = false`.

**`backup = false` semantics:**
- Whole-tree sync: that repo is excluded by rsync; not synced; its `last_sync` is not touched.
- Single-project sync: errors. The user explicitly named it.

---

## 5. CLI surface and error UX

### 5.1 Subcommands

```
repoman new <name> [--repo <dirname>] [--image <img>]
repoman sync [name] [--no-delete] [--dry-run]
repoman --version | -V
repoman --help    | -h | help
repoman                         # no args → print full help
```

### 5.2 Output discipline

- All informational chatter (`==> incus launch ...`, `==> rsync (dry-run) ...`) goes to **stderr**.
- **stdout is reserved** for future machine-readable output. v0.1 produces no stdout (matches bash prototype, keeps cron logs clean).
- Errors prefixed `repoman: error: <message>` to stderr. Append a `hint:` line where a clear next step exists.

### 5.3 Exit codes

| Code | Meaning |
|---|---|
| `0` | success |
| `1` | generic / unhandled error |
| `2` | bad usage (unknown subcommand, missing required arg, bad flag) |
| `3` | environment problem (NFS unreachable, repo dir missing, registry corrupt) |
| `4` | state conflict (container already exists, name already in registry) |
| (rsync codes) | for `sync`: rsync's own exit code passes through when rsync itself fails. Pre-rsync errors use 1–4. |

The rsync passthrough is deliberate: cron consumers can distinguish "couldn't even start" (3/4) from "rsync hit a problem" (rsync's own codes).

### 5.4 Error UX matrix

| Class | Example | Code | What the user sees |
|---|---|---|---|
| Bad usage | `repoman new` | 2 | error msg + short usage hint |
| Validation | invalid container name | 1 | error msg + offending value |
| State conflict | name already in registry | 4 | error msg + cleanup hint |
| Environment | NFS not mounted | 3 | "backup_root /nfs/repos is not mounted (autofs/server unreachable)" |
| Subprocess (incus) | `incus launch` failed | 1 | our error msg + incus's stderr passed through |
| Subprocess (rsync) | rsync mid-transfer error | rsync's | rsync's own stderr (we don't capture) |

### 5.5 No interactive mode in v0.1

Missing required args produce a usage error, not a prompt. Wizard mode is v0.2.

---

## 6. Testing strategy

### 6.1 Unit-tested (pure logic) — full coverage expected

| Module | What's tested |
|---|---|
| `path` | `expand_home` (`~/`, `~`, no-op cases), `join` (trailing-slash handling) |
| `incus` | `validate_name` — valid, leading-hyphen, too-long, dot/underscore, empty, exactly-63-char boundary |
| `config` | TOML round-trip (parse → serialize → reparse equals original); schema rejection (unknown `schema`); `load_or_init` against a temp `XDG_CONFIG_HOME`; `merge_with_defaults` for image/profiles/mounts/env priority cases; `add_project` rejects duplicates; `update_last_sync` on known/unknown name |
| `sync` | `build_rsync_args` covers every branch: dry-run on/off, delete on/off, TTY/non-TTY info flags, `backup=false` exclude generation, single-project vs whole-tree, every standard exclude present |

### 6.2 Smoke-tested (effectful) — manual, not automated

- `incus.project_ensure`, `launch`, `bind_repo`, `restart` — need a real Incus daemon.
- `sync.ensure_nfs_mounted`, `sync.run` — need a real NFS mount and rsync.

Smoke test recipe (in README):
```bash
# In an existing repo dir under ~/repos:
repoman new test-foo
repoman sync test-foo --dry-run
incus delete --project repoman test-foo
```

Three commands, ~30 seconds, catches integration regressions before each release tag.

### 6.3 Test runner

Reef idiom: `reefc run tests/test_<module>.reef` per file, each a standalone program using `test.framework`'s `TestRunner`. Documented loop in README:
```bash
for t in tests/test_*.reef; do
    echo "== $t =="
    reefc run "$t" || exit 1
done
```

### 6.4 Not tested in v0.1

- `main.reef` — 5-line dispatcher, exercised by every invocation in dev.
- CLI flag-parsing fine grain — exercised by manual usage during dogfooding; revisit in v0.2.
- Exact rsync exit-code passthrough — trusts rsync.

### 6.5 No CI in v0.1

Public-forge + CI is post-v0.1 work. Bar for v0.1: the test loop runs cleanly locally.

---

## 7. Build, install, distribution

### 7.1 `reef.toml` manifest

```toml
[package]
name        = "repoman"
version     = "0.1.0"
author      = "Chris Tusa <chris.tusa@leafscale.com>"
description = "Per-project Incus containers + opinionated NFS/ZFS backup"
license     = "MIT"           # placeholder — open product question
url         = ""              # forge TBD

[build]
entry        = "src/main.reef"
output       = "repoman"
output_dir   = "build"
source_dirs  = ["src"]

[docs]
output           = "docs/api"
include_private  = false
```

### 7.2 Repo layout

```
~/repos/repoman/
├── reef.toml
├── Makefile             # 10-line install/uninstall wrapper for packagers
├── README.md            # quickstart + test loop + smoke-test recipe + recommended `dotfiles` Incus profile pattern
├── VISION.md            # design intent (stays at root)
├── .hgignore            # build/, *.o, etc.
├── docs/
│   ├── superpowers/specs/2026-04-29-repoman-v0.1-design.md  # this file
│   └── api/             # generated by `reefc doc`
├── src/
│   ├── main.reef
│   ├── cli.reef
│   ├── config.reef
│   ├── incus.reef
│   ├── sync.reef
│   └── path.reef
├── tests/
│   ├── test_path.reef
│   ├── test_config.reef
│   ├── test_incus.reef
│   └── test_sync.reef
└── build/               # generated; hg-ignored
```

### 7.3 Build / clean / docs

Reef-native:
- `reefc build` → `build/repoman`
- `reefc clean`
- `reefc doc` → `docs/api/`

### 7.4 Tests

Documented shell loop in README (§6.3); no wrapper.

### 7.5 Install

10-line `Makefile`, install/uninstall only (packagers expect `DESTDIR`/`PREFIX`):

```make
PREFIX ?= /usr/local
DESTDIR ?=

build/repoman:
	reefc build

install: build/repoman
	install -d $(DESTDIR)$(PREFIX)/bin
	install -m 755 build/repoman $(DESTDIR)$(PREFIX)/bin/repoman

uninstall:
	rm -f $(DESTDIR)$(PREFIX)/bin/repoman

.PHONY: install uninstall
```

`make install PREFIX=$HOME/.local` and `sudo make install` both work; `DESTDIR` honored for fakeroot staging.

### 7.6 Single-binary distribution

Reef compiles to C → native. `build/repoman` statically links `libreef_runtime.a`. v0.1 doesn't use TLS (no REST yet) → `libreef_tls.a` not pulled in. Runtime deps: libc + the external `incus`, `rsync`, `findmnt`, `mountpoint`, `stat` binaries.

### 7.7 Release artifacts (post-v0.1)

Source tarball minimum; prebuilt binaries per platform once forge is chosen. Out of scope for v0.1.

### 7.8 v0.1 verification checklist

1. `reefc build` succeeds clean.
2. The test loop passes for every file in `tests/`.
3. `make install PREFIX=$HOME/.local` (or `sudo make install`) puts `repoman` on PATH.
4. Smoke test: `repoman new test-foo` (against an existing test repo) → `repoman sync test-foo --dry-run` → manual `incus delete --project repoman test-foo`. All exit 0.
5. `repoman --version` prints `0.1.0`.

---

## 8. Open product questions (do not block v0.1 dev)

1. **License.** MIT placeholder in `reef.toml`. Final choice (MIT vs Apache-2.0) before public release.
2. **Forge.** GitHub / Codeberg / self-hosted — affects release artifact pipeline.
3. **Env-var compatibility.** Bash prototype reads `LOCAL_REPOS` / `NFS_REPOS`. Reef v0.1 does not — TOML registry is canonical. Decide before the bash version is retired whether to honor `REPOMAN_REPOS_ROOT` / `REPOMAN_BACKUP_ROOT` as overrides.
4. **Logging / observability.** v0.1 = stderr only. JSON-lines mode is a v0.2 candidate.

---

## 9. Implementation pinned at scaffold-time (not now)

These are decisions deliberately deferred to the moment the code lands, because a 10-minute look at the actual reef API resolves them better than abstract debate:

1. **CLI parser.** Hand-roll an `argv[1]` switch in `cli.reef`, then call `sys.flag.flag_parser_from(argv[2..])` per subcommand. The surface to the rest of the code is `cli.dispatch(argv: [string]): int`. Migrate to `subcommand_parser` when 0.5.11 ships it.
2. **`incus config show` output parsing.** Anywhere v0.1 needs to query Incus state (e.g., `container_exists`), prefer `incus list --format csv` or `--format json` over text scraping. Lock the format choice when implementing each call.

---

## 10. References

- [VISION.md](../../../VISION.md) — design intent, audience, differentiators, open product questions.
- `~/.local/bin/repoman` — bash prototype (behavioral spec for `new` ≈ `create` and `sync`).
- `~/reef-lang-0.5.10-source/docs/language/reference/031_PROJECT_STRUCTURE.md` — reef project conventions (`reefc init`, `reef.toml`, module-to-file mapping).
- `~/reef-lang-0.5.10-source/reef-stdlib/sys/process.reef` — `process_spawn` / `process_exec` / wait/kill API used throughout.
- `~/reef-lang-0.5.10-source/reef-stdlib/encoding/toml.reef` — TOML codec for the registry.
# repoman v0.3 — Setup wizard + LLM stack integration

## Scope reduction (2026-05-08)

The `--hermes`/`--no-hermes`/`--purge-hermes` flag-based provisioning described in
this spec was **removed during smoke testing** and will not ship in v0.3.

Root cause: the bind-mount-the-host-runtime architecture does not survive Python venv
portability constraints. Hermes' venv pins to a uv-vendored host-only path; bind-
mounting it into a container where that path doesn't exist fails at import time. Uid
mapping for the bind also does not generalize cleanly. Copying the venv breaks shebang
paths.

v0.4 will revisit per-container hermes provisioning via pre-built incus images that
embed a self-contained hermes install rather than sharing the host runtime.

**v0.3 still ships:** `repoman setup` wizard, `llm-share` profile (ollama client
wiring), schema-2 migration, and the `hermes` module helpers as a library for v0.4.

---

**Status:** v0.3 design, under review
**Date:** 2026-05-06
**Implementation language:** reef-lang 0.5.20 (no new stdlib requirements vs v0.2)
**Origin:** [VISION.md §4 (`repoman setup`)](../../../VISION.md), [v0.1 spec](2026-04-29-repoman-v0.1-design.md), conversation 2026-05-06 with hermes Docker docs at `https://hermes-agent.nousresearch.com/docs/user-guide/docker`
**Outcome:** the contract for v0.3 — the first version of repoman that productizes the host-side bootstrap and bundles local-LLM tooling.

---

## 0. What's new vs v0.2

v0.2 shipped `new`/`sync`/`list`/`status`/`remove`/`shell`. It assumes the host is already prepared (Incus project exists, `claude-share` profile authored, ZFS/NFS available). v0.3 closes that gap by introducing the host-bootstrap subcommand and adds first-class support for local LLM tooling (ollama + hermes) since that's the most common reason a fresh host needs more than just `claude-share`.

Two threads, one release:

1. **`repoman setup`** — idempotent host bootstrap. Replaces the README's manual incus-project-create / profile-edit walkthrough with a guided wizard.
2. **LLM stack integration** — `llm-share` profile, ollama client wiring, per-container hermes data dirs with selective seeding.

The two are coupled because the wizard is the natural place to *offer* LLM-stack setup as an option, and the per-container hermes seeding adds new behavior to `repoman new`.

---

## 1. Scope

**In scope:**
- `repoman setup` — interactive + flag-driven (`--non-interactive`, `--with-llm`, `--without-llm`).
- `llm-share` Incus profile, repoman-managed (created/refreshed by `setup`).
- `repoman new --hermes` — opt-in flag that provisions a per-container hermes data dir.
- `repoman new --no-hermes` (and `--llm/--no-llm` umbrella) for explicit opt-out when defaults change.
- Selective hermes seeding from host's `~/.hermes/` into `~/.local/share/repoman/hermes/<name>/`.
- `repoman remove --purge-hermes` — delete the per-container hermes data dir (default: leave it for safety).
- Host LAN-IP detection for `OLLAMA_HOST` (read once at `setup`, written into profile).
- `[defaults].llm = { enabled, hermes_default, ollama_url, hermes_seed }` block in `repoman.toml`.

**Out of scope (deferred to v0.4 or later):**
- Adopting an existing host hermes install whose `~/.hermes` should *be* one of the project dirs (no migration tool yet — user can `mv` manually).
- Re-keying / rotating `.env` API keys across N seeded containers.
- Bind-mounting `/opt/ollama/imports` into containers for in-container `ollama create`. Will be added if real demand surfaces; for v0.3, model imports stay a host operation.
- `claude-share` lifecycle. v0.3 *checks* its existence in `setup` and tells the user how to create it if missing, but does not author or edit it. (Same boundary as v0.2.)
- Hermes server-side gateway (port 8642) exposure to the LAN as a shared service. The hermes docs explicitly reject the daemon model; we don't fight it.
- YAML rewriting of seeded `config.yaml`. v0.3 issues a warning if `localhost:11434` is detected in the seed source and asks the user to fix once on the host; we do not parse YAML.

---

## 2. Architecture additions

Two new modules, plus targeted edits to `cli.reef`, `config.reef`, `incus.reef`:

| File | Module | Responsibility | Pure? |
|---|---|---|---|
| `src/setup.reef` | `setup` | The wizard: detect state (incus project, profiles, ollama, hermes binary, host LAN IP), print summary, prompt yes/no per stage, apply changes. Composes `incus.*` and `hermes.*`. | wrappers thin |
| `src/hermes.reef` | `hermes` | Per-container data-dir management: `seed_data_dir(name, source, dest, seed_list)`, `purge_data_dir(dest)`. Pure helpers `default_seed_list()` (returns the allow-list), `state_dir_for(name)` (resolves `~/.local/share/repoman/hermes/<name>/`). | helpers pure; copy effectful |

Edits:

- `cli.reef` — add `cmd_setup` dispatch, extend `cmd_new` to honor `--hermes` / `--no-hermes`, extend `cmd_remove` to honor `--purge-hermes`.
- `config.reef` — add `[defaults].llm` substructure, schema bump to `2`, migration path for `schema = 1` registries.
- `incus.reef` — add `profile_exists(name, project)`, `profile_create_or_edit(name, project, yaml)`, `container_add_disk_device(name, device, source, path, opts)`. The disk-device add is needed because `hermes-state` is a *per-container* device, not a profile-level one.

**Dependency graph addition:** `cli → setup → {incus, hermes, config, path}`. `hermes → {path, io.file, io.dir}`. No cycles.

**Non-goal: a new abstraction over Incus profiles.** `setup` constructs `llm-share` from a string-template embedded in the binary — we don't build a profile-modeling layer in reef just yet.

---

## 3. The `llm-share` profile

Created and maintained by `repoman setup`, in the `repoman` Incus project:

```yaml
name: llm-share
description: |
  Local LLM client tools (ollama client + hermes runtime) and host-daemon wiring.
  Created by repoman setup; do not hand-edit (changes will be overwritten).
config:
  environment.OLLAMA_HOST: "http://<HOST_LAN_IP>:11434"
devices:
  ollama-bin:
    type: disk
    source: /usr/local/bin/ollama
    path: /usr/local/bin/ollama
    readonly: "true"
  ollama-state:
    type: disk
    source: /home/<USER>/.ollama
    path: /home/<USER>/.ollama
    shift: "true"
```

`<HOST_LAN_IP>` is the address bound to `br0` on the host, resolved at `setup` time by parsing `ip -4 addr show br0`. `<USER>` is the invoking user. Both are baked into the YAML at write time — `repoman setup` is the single source of truth.

**Notably absent:** any hermes bind-mount. Hermes data is per-container (see §4).

**Refresh policy.** Re-running `repoman setup` rewrites `llm-share` from template if and only if the on-disk content differs. `setup` tells the user what it changed and why.

---

## 4. Per-container hermes data dirs

Host hermes' `~/.hermes/` is left untouched. For each container that opts into hermes, repoman provisions:

- A host directory at `~/.local/share/repoman/hermes/<container-name>/`, owned by the invoking user.
- Selective seed from `~/.hermes/` into that directory (see §4.2).
- An Incus disk device on the container itself (not a profile) bind-mounting that host dir to `/home/<USER>/.hermes` inside.

The hermes binary at `~/.local/bin/hermes` is reachable inside the container via the existing `claude-share` profile's bind on `~/.local/bin/`. (We **verify** this assumption in §6.1; if `claude-share` doesn't share `~/.local/bin`, the wizard tells the user to add it.)

### 4.1 Why per-container, not shared

Per the [hermes Docker guide](https://hermes-agent.nousresearch.com/docs/user-guide/docker):

> Never run two Hermes gateway containers against the same data directory simultaneously — session files and memory stores are not designed for concurrent write access.

`state.db` is SQLite + WAL. Sharing the data dir between host and N containers risks corruption. Per-container dirs eliminate the risk entirely and align with the hermes team's recommended pattern (one data dir per profile/container).

### 4.2 Seed list

Default `[defaults].llm.hermes_seed`:

```toml
hermes_seed = [
  ".env",                 # API keys
  "config.yaml",          # model defaults, daemon URL
  "SOUL.md",              # persona
  "skills/",              # user-authored skills (recursive)
  "hooks/",               # user hooks (recursive)
  "hermes-agent/",        # vendored runtime — symlink (see §4.3)
  "node/",                # vendored node — symlink
  "bin/",                 # extra binaries — symlink
]
```

**Not seeded** (per-instance state, must be fresh): `sessions/`, `memories/`, `logs/`, `state.db`, `state.db-shm`, `state.db-wal`, `audio_cache/`, `image_cache/`, `sandboxes/`, `cron/`, `pairing/`, `models_dev_cache.json`, `ollama_cloud_models_cache.json`, `context_length_cache.yaml`, `.skills_prompt_snapshot.json`, `.update_check`, `.hermes_history`, `auth.lock`.

The seed list is in `[defaults].llm.hermes_seed` so users can adjust it without rebuilding.

### 4.3 Symlink vs copy for runtime dirs

`hermes-agent/`, `node/`, `bin/` are *runtime*, not user data. By default we **symlink** them from the host's `~/.hermes/` (so a `hermes` upgrade on the host applies to every container with no rebuild), and **copy** the credential/config files. A future `--hermes-isolate-runtime` flag can flip everything to copy for users who want hermes versions to diverge per container.

Symlinks must point at the host path *as visible from inside the container* — i.e., the symlink target must already be reachable through some other bind. Since `~/` is bind-mounted in or mappable, this works as long as the user paths align. **Open question O-3 (§9)** owns the cross-mount-namespace symlink correctness check.

### 4.4 Storage location: why `~/.local/share/repoman/hermes/<name>/`

Considered: `~/.hermes-<name>/` (parallel to `~/.hermes`).

Chose `~/.local/share/repoman/hermes/<name>/` because:
- All repoman-owned per-project state ends up under one tree (`~/.local/share/repoman/`), which matters for backups and for users who want to know "what does repoman own?"
- `~/.hermes-*` pollutes `$HOME` and risks collision with hypothetical future hermes profile features.
- XDG Base Directory convention.

---

## 5. Subcommand flows

### 5.1 `repoman setup [--non-interactive] [--with-llm | --without-llm]`

Stages, run sequentially. Each stage prints what it found, what it'd change, and (interactive mode) waits for `[Y/n]`. `--non-interactive` accepts every default; `--with-llm`/`--without-llm` non-interactively pin the LLM stage.

1. **Detect environment.** incus reachable, current user, host LAN IP via `br0`, ollama binary, hermes binary, `~/.hermes/` presence, ZFS/NFS roots from registry defaults.
2. **Incus project `repoman`.** Create if missing. (No-op if v0.1 already created it.)
3. **`claude-share` profile.** Verify it exists in the `repoman` project and bind-mounts `~/.local/bin/`. If missing or doesn't bind that path, print the recommended `incus profile edit` snippet and exit non-zero with a clear message — we do not author `claude-share`.
4. **LLM stack (gated on `--with-llm` or interactive yes).**
   1. Verify ollama daemon is reachable on `<host-lan-ip>:11434`. If only on loopback, print the systemd-override snippet to make it LAN-listen and exit non-zero.
   2. Write/refresh the `llm-share` profile in the `repoman` project from template (§3).
   3. Verify hermes binary at `~/.local/bin/hermes` and host data dir at `~/.hermes/`. If absent, print install pointer (link to hermes user guide) and skip per-container hermes seeding default.
5. **Registry defaults.** Write `[defaults].profiles = ["default", "claude-share", "llm-share"]` if user said yes to LLM stack; write `[defaults].llm.{enabled = true, hermes_default = false, ollama_url, hermes_seed = [...]}` block. Schema bumps to `2`.
6. **Summary.** Print `setup complete` summary with three follow-on hints: `repoman new <name>`, `repoman new <name> --hermes`, `repoman list`.

Exit codes: `0` success, `2` bad usage, `3` environment (incus unreachable, ollama not LAN-bound, br0 missing), `4` user said no to a required stage in non-interactive mode.

**Idempotency:** every stage is rerunnable. Re-running `setup` after a hermes upgrade refreshes the `llm-share` profile if its content changed and is otherwise a no-op.

### 5.2 `repoman new <name> [...] [--hermes | --no-hermes]`

Existing v0.2 flow plus:

- After the container launch, **if** `--hermes` (explicit) or `[defaults].llm.hermes_default = true` and not `--no-hermes`:
  1. Compute `dest = ~/.local/share/repoman/hermes/<name>/`.
  2. Refuse if `dest` already exists and is non-empty (exit 4 with hint to `repoman remove --purge-hermes <name>` first).
  3. Run the seed (§4.2): copy the credential/config files, symlink the runtime dirs.
  4. `incus.container_add_disk_device(<name>, "hermes-state", source=dest, path=/home/<USER>/.hermes, shift=true)`.
  5. Restart the container so the device takes effect.
- The registry's `[[project]]` entry gains a `hermes = true|false` field so `list`/`status` can show it.

If the LLM stack wasn't enabled at `setup` time, `--hermes` errors out with a hint to `repoman setup --with-llm`.

### 5.3 `repoman remove <name> [--purge-hermes]`

Existing v0.2 flow plus:

- Container removal proceeds as today.
- If the project had `hermes = true`, the per-container data dir is **left in place by default**. The user's reauthorized `.env` and skills survive the container teardown.
- `--purge-hermes` (or `--purge` umbrella, see open question O-1) deletes `~/.local/share/repoman/hermes/<name>/`. Logged loudly because this destroys session/memory state.

### 5.4 `repoman status <name>` / `repoman list`

Show `hermes: yes/no` per project. No new flags.

---

## 6. Data shapes

### 6.1 Registry schema bump (1 → 2)

```toml
[repoman]
schema = 2

[defaults]
repos_root     = "~/repos"
backup_root    = "/nfs/repos"
incus_project  = "repoman"
default_image  = "images:ubuntu/26.04/cloud"
profiles       = ["default", "claude-share", "llm-share"]   # llm-share added if user opted in

[defaults.llm]
enabled        = true
hermes_default = false                                       # false → opt-in via --hermes
ollama_url     = "http://192.168.168.42:11434"               # LAN IP captured at setup
hermes_seed    = [
  ".env", "config.yaml", "SOUL.md",
  "skills/", "hooks/",
  "hermes-agent/", "node/", "bin/",
]

[[project]]
name        = "isurus"
repo        = "isurus-project"
image       = "images:ubuntu/26.04/cloud"
profiles    = ["default", "claude-share", "llm-share"]
created     = "2026-04-28T15:00:00Z"
last_sync   = ""
backup      = true
hermes      = true                                           # NEW; defaults false
```

**Migration from schema 1:** `config.load_or_init` recognizes `schema = 1`, prints a one-line note, populates `[defaults].llm` with `enabled = false` (i.e., user must opt in via `setup`), sets `hermes = false` on every existing `[[project]]`, writes back as `schema = 2`. Idempotent. No data loss.

### 6.2 Per-project override addition

Override files (`~/.config/repoman/repos.d/<name>.toml`) gain an optional field:

```toml
[hermes]
enabled = true   # equivalent to passing --hermes; flag wins if both specified
```

Unknown to v0.2; harmless to v0.2 since override parser ignores unknown sections.

### 6.3 Profile YAML template

Embedded as a `string` constant in `setup.reef`:

```reef
let LLM_SHARE_TEMPLATE: string =
  "name: llm-share\n" ++
  "description: |\n" ++
  "  Local LLM client tools (ollama client + hermes runtime) and host-daemon wiring.\n" ++
  "  Created by repoman setup; do not hand-edit (changes will be overwritten).\n" ++
  "config:\n" ++
  "  environment.OLLAMA_HOST: \"http://{HOST_LAN_IP}:11434\"\n" ++
  "devices:\n" ++
  "  ollama-bin:\n" ++
  "    type: disk\n" ++
  "    source: /usr/local/bin/ollama\n" ++
  "    path: /usr/local/bin/ollama\n" ++
  "    readonly: \"true\"\n" ++
  "  ollama-state:\n" ++
  "    type: disk\n" ++
  "    source: /home/{USER}/.ollama\n" ++
  "    path: /home/{USER}/.ollama\n" ++
  "    shift: \"true\"\n"
```

Substitutions are literal `{HOST_LAN_IP}` / `{USER}` replacement — no template engine. Validated with a roundtrip test (substitution → YAML parse via the bundled toolchain → assert structure).

---

## 7. Testing

Mirrors the v0.1 boundary: pure logic gets unit tests; effectful wrappers get smoke-tested via integration. Specifically:

**Pure tests** (run on every build):
- `hermes.default_seed_list()` returns the documented allow-list.
- `hermes.state_dir_for("foo")` resolves to `<expand_home("~")>/.local/share/repoman/hermes/foo/`.
- Profile template substitution: given known `HOST_LAN_IP`/`USER`, the rendered YAML matches a golden string.
- Schema migration: load `schema = 1` toml, get back `schema = 2` toml with expected defaults populated and existing `[[project]]` entries unchanged except for `hermes = false`.
- Seed-list partition: given the documented hermes dir contents (test fixture), the seeded vs not-seeded sets match §4.2.
- `setup` stage planner: given a fixture environment description (profile present, ollama on LAN, hermes installed), the planner returns the expected list of "would change" actions and "no-op" actions.

**Smoke tests** (require an Incus host, gated on `REPOMAN_SMOKE=1`):
- `repoman setup --non-interactive --with-llm` on a fresh-ish host produces a working baseline.
- `repoman new foo --hermes` then `incus exec foo -- ls /home/$USER/.hermes` shows the seeded layout, and `incus exec foo -- hermes --version` runs.
- `repoman remove foo` leaves the data dir; `repoman remove foo --purge-hermes` removes it.
- Symlink correctness: from inside the container, `readlink ~/.hermes/hermes-agent` resolves to a real path (no broken link).

---

## 8. Risks / mitigations

| Risk | Mitigation |
|---|---|
| Symlinks for runtime dirs break across mount namespaces. | Smoke test 4 above. If broken, fall back to copy for runtime dirs and surface as O-3. |
| Host LAN IP changes (DHCP renewal). | `setup --refresh` re-detects and rewrites `llm-share`. Documented as the recovery step in `repoman status` when ollama health-check fails. |
| Hermes upgrades change the on-disk layout (`hermes-agent/` schema, etc.). | Symlinking the runtime dirs means upgrades flow through automatically. Seed list is config (`[defaults].llm.hermes_seed`) so users can adjust without recompiling. |
| `.env` shared across N containers means a leaked container key is the user's main key. | Same trust model as `claude-share`. Documented in README. Future v0.4 work on rotation is explicitly out of scope here. |
| User has hermes installed in a non-default location (not `~/.hermes/`). | `setup` reads `HERMES_HOME`-equivalent if set; otherwise hardcoded default. Open question O-2. |
| `setup` partial-fails midway (e.g., wrote `llm-share` but couldn't restart a container). | Each stage is independently idempotent. `setup` is safe to rerun. No transactional rollback in v0.3 — same posture as v0.1's container-create. |

---

## 9. Open questions

- **O-1: `--purge-hermes` vs `--purge`.** Should `repoman remove` have a single `--purge` flag that removes both the hermes data dir and any future per-container repoman state, or stay tool-specific (`--purge-hermes`, `--purge-claude`, …)? Defaulting to `--purge-hermes` for v0.3.
- **O-2: Hermes home env var.** Does the hermes CLI honor a `HERMES_HOME` (or similar) env var to redirect from `~/.hermes/`? If yes, the per-container path could be set via env rather than bind-mount-overlay. Needs probe.
- **O-3: Symlink correctness across the bind boundary.** Validate empirically that `~/.local/share/repoman/hermes/<name>/hermes-agent → /home/<USER>/.hermes/hermes-agent` resolves correctly inside the container when only the per-container dir is bind-mounted. If not, fall back to copy and document.
- **O-4: `claude-share` baseline check.** v0.3 currently *checks* that `claude-share` bind-mounts `~/.local/bin/`. If that's a fragile assumption (the user may name their profile differently), should `setup` accept a `--claude-share-profile=<name>` override?
- **O-5: Authoring `claude-share` itself.** Out of scope for v0.3 (§1), but eventually repoman should manage `claude-share` the same way it manages `llm-share`. v0.4 candidate.
- **O-6: Multi-host repoman.** If a user runs repoman on two hosts and their LAN IPs differ, the registry's `ollama_url` is host-specific. v0.3 treats `repoman.toml` as host-local; document.

---

## 10. Build sequence

Suggested order so each step produces a working binary:

1. **Schema bump.** `config.reef` adds `[defaults].llm` parsing + schema 1→2 migration. Tests pass; v0.2 behavior unchanged.
2. **`incus.profile_*` and `container_add_disk_device` wrappers.** Pure plumbing; no caller yet.
3. **`hermes.reef` module.** `default_seed_list`, `state_dir_for`, `seed_data_dir`, `purge_data_dir`. Unit-tested.
4. **`setup.reef` module.** Detection + planner + applier. The interactive prompt scaffolding is `io.console`-based; matches the wizard pattern named in VISION.
5. **`cli.cmd_setup`** — wire it up.
6. **`cmd_new` extensions** — `--hermes`/`--no-hermes`, registry write of `hermes` field, post-launch seed + device-add + restart.
7. **`cmd_remove` extensions** — `--purge-hermes`.
8. **`list`/`status` display** — show `hermes: yes/no`.
9. **README + VISION updates** — document `setup`, document `--hermes`, link to hermes Docker docs as the source for the per-container-data-dir decision.
10. **Smoke run on a fresh host** — fold findings back as bug fixes, then tag v0.3.0.
# repoman v0.4 — Profile library + scope trim

**Status:** v0.4 design, under review
**Date:** 2026-05-08
**Implementation language:** reef-lang 0.5.20 (no new stdlib requirements vs v0.3)
**Origin:** brainstorm 2026-05-08 — re-anchoring on repoman's actual mission after v0.3 LLM-stack work overshot scope. Builds on [v0.3 spec](2026-05-06-repoman-v0.3-llm-and-setup.md) (which was scope-reduced before shipping; see addendum at top of that file).
**Outcome:** the contract for v0.4 — repoman becomes a profile-library-driven container provisioner, with the v0.3 LLM-specific surface either generalized into the profile system or removed.

---

## 0. Mission re-anchor

Repoman's mission is narrowly:
1. Provision per-project Incus containers that bind-mount the user's git/hg repos (`cmd_new`)
2. Backup `~/repos/` to NFS via rsync (`cmd_sync`)
3. Manage the Incus profiles that share host-side resources (configs, agents, bind-mountable runtimes) into containers
4. Quality-of-life subcommands over the above (`list`, `status`, `remove`, `shell`, `setup`)

**What repoman is NOT:** a host-configuration tool. It does not install or configure host services (ollama, hermes runtime, kernel modules). It does not build or maintain container images. It does not run arbitrary install scripts on the user's behalf.

**Where v0.3 drifted:** `setup --with-llm` checks whether the host's ollama daemon listens on the LAN IP and tells the user how to configure it if not. This was halfway across the host-config line. v0.4 pulls back to the line.

**The unifying insight from this brainstorm:** `claude-share` (user-managed since v0.1) and `llm-share` (repoman-managed since v0.3) are the same kind of thing — incus profiles that bind something host-side into containers. The split was incidental, not principled. v0.4 unifies them under a single profile library.

---

## 1. Scope

**In scope (additions):**
- Profile library layout: vendor profiles at `/usr/local/share/repoman/profiles/`, user profiles at `~/.config/repoman/profiles.d/`, user shadows vendor.
- `repoman profile` subcommand family: `list`, `install`, `diff`, `remove`, `show`.
- Templated YAML profile files. Substitution syntax: `${VAR}` (shell-style). Variables: `${HOST_LAN_IP}`, `${USER}`, `${HOME}`.
- `[host].lan_ip` field in the registry, populated by `repoman setup`'s detection.
- Registry schema 2 → schema 3 migration (drops `[defaults].llm` entirely, extracts `lan_ip` from the old `ollama_url` if present).
- Three vendor profiles ship in v0.4: `claude-share.yml`, `llm-share.yml`, `dotfiles.yml`.
- Pre-launch validation in `repoman new`: error early with actionable hint if a referenced profile isn't installed in incus.

**In scope (trims/removals):**
- `repoman setup --with-llm` and `--without-llm` flags — removed. Setup no longer touches profiles.
- `setup`'s ollama LAN-listening check — removed. Reading host LAN IP from `ip -4 addr show br0` stays (read-only host introspection, not configuration).
- `[defaults].llm` registry block (enabled, hermes_default, ollama_url, hermes_seed) — removed entirely.
- The string-template-embedded-in-binary approach for `llm-share` in `setup.reef` — removed. `llm-share` becomes a vendor profile YAML file.
- `setup`'s `apply_stage` for `llm_share_profile` and `registry_defaults` — those stages move to `repoman profile install` and registry init respectively.

**Out of scope (deferred or rejected):**
- Image management (`repoman image build/refresh/etc.`) — rejected during brainstorm. Maintenance burden too high for a homelab tool with low container churn. v0.5+ may revisit if real demand surfaces.
- `[install]` block in override files — rejected during brainstorm. Per-project install commands are shell-script territory; not repoman's job.
- Configuring host ollama (installer, systemd override, model pulls) — rejected as scope creep across the host-config boundary.
- Remote profile registries / fetching profiles over HTTP — out of scope. Library is local files only.
- Profile dependencies (`profile A includes profile B`) — YAGNI. Each profile is independent.
- Profile YAML schema validation — trust incus. v0.4 just substitutes templates; incus rejects malformed YAML at apply time with clear errors.
- Per-host portability automation — registry is per-host (lives in `~/.config/repoman/`); document that fact rather than automate it.

---

## 2. Architecture

### 2.1 New module: `src/profile.reef`

Single new module covering the profile library. Composes `incus`, `path`, `config`, and stdlib I/O.

| Responsibility | Pure? |
|---|---|
| `vendor_dir(): string` — `/usr/local/share/repoman/profiles` | yes |
| `user_dir(home: string): string` — `<home>/.config/repoman/profiles.d` | yes |
| `lookup(name: string, home: string): Result[string, string]` — search user dir then vendor dir, return path to YAML file or Err if not found | side-effecting (filesystem reads) |
| `list_all(home: string): [ProfileEntry]` — enumerate both dirs, return list with source (user/vendor) tags | side-effecting |
| `render(yaml: string, host: HostFacts): string` — substitute `${HOST_LAN_IP}`, `${USER}`, `${HOME}` | yes |
| `install(name: string, home: string, host: HostFacts): Result[bool, string]` — lookup → render → `incus.profile_create_or_edit` | side-effecting |
| `diff(name: string, home: string, host: HostFacts): Result[string, string]` — render the file, fetch the live incus profile, return unified diff | side-effecting |
| `remove(name: string): Result[bool, string]` — `incus profile delete` (no-op if not installed) | side-effecting |
| `show(name: string, home: string, host: HostFacts): Result[string, string]` — return rendered YAML for inspection | side-effecting |

Pure helpers (`render`, `vendor_dir`, `user_dir`) get unit tests. Effectful wrappers are smoke-tested via `cmd_*`.

### 2.2 Edits to existing modules

- `src/setup.reef`: drop `render_llm_share_template`, `template_contains_placeholder`, the `apply_stage` cases for `llm_share_profile` and `registry_defaults`, and the `--with-llm`/`--without-llm` flag plumbing in `cmd_setup`. Setup becomes: detect environment → print plan → ensure incus project → write registry with `[host].lan_ip` populated. The wizard still has `--non-interactive`. Two stages remain (down from up to four): `incus_project`, `registry_defaults`.
- `src/cli.reef`: add `cmd_profile` dispatch covering 5 subcommands. Add pre-launch validation in `cmd_new`: before `incus.launch`, iterate `eff.profiles` and call `incus.profile_exists("default", name)` for each — error early with `hint: repoman profile install <name>` if any are missing. Update `print_usage()` help text.
- `src/config.reef`: add `Host` substruct (`lan_ip: string`) and `Registry.host: Host` field. Drop `LlmDefaults` and `Defaults.llm`. Bump schema constant to 3. Add migration: if loading schema 2, extract `[defaults.llm.ollama_url]`, parse the host portion of the URL into `[host].lan_ip`, drop the rest.
- `src/incus.reef`: add `profile_get(name): Result[string, string]` (`incus profile show <name>` capturing stdout) — needed for `profile diff`.
- `src/main.reef`: dispatch already routes through `cli.dispatch`; no changes.

### 2.3 Build/install changes

`Makefile`:
- New target dependency: `install` copies `profiles/*.yml` into `/usr/local/share/repoman/profiles/`.
- New target: `uninstall` removes them.

```makefile
PROFILES_DIR = $(DESTDIR)$(PREFIX)/share/repoman/profiles

install: build
    install -d $(DESTDIR)$(BINDIR)
    install -m 0755 build/repoman $(DESTDIR)$(BINDIR)/repoman
    install -d $(PROFILES_DIR)
    install -m 0644 profiles/*.yml $(PROFILES_DIR)/

uninstall:
    rm -f $(DESTDIR)$(BINDIR)/repoman
    rm -rf $(PROFILES_DIR)
```

### 2.4 Repository layout addition

```
~/repos/repoman/
├── profiles/
│   ├── claude-share.yml      # bind ${HOME}/.claude
│   ├── llm-share.yml         # bind /usr/local/bin/ollama, ${HOME}/.ollama; OLLAMA_HOST env
│   └── dotfiles.yml          # bind ${HOME}/.gitconfig, ${HOME}/.hgrc
├── src/
│   ├── profile.reef          # NEW
│   ├── ...
└── ...
```

`profiles/` is a tracked directory in the source repo (versioned alongside code). The files are templates; substitutions happen at install time.

---

## 3. Data shapes

### 3.1 Vendor profile templates (v0.4 starter library)

**`profiles/claude-share.yml`:**
```yaml
name: claude-share
description: Share host's Claude CLI state (auth, history, plugins) into containers.
config: {}
devices:
  claude-state:
    type: disk
    source: ${HOME}/.claude
    path: ${HOME}/.claude
    shift: "true"
  claude-bin:
    type: disk
    source: ${HOME}/.local/bin/claude
    path: /usr/local/bin/claude
    readonly: "true"
    shift: "true"
```

(Note: `claude-bin` assumes claude is installed via npm/pipx into `~/.local/bin/`. Users with system-installed claude shadow this profile.)

**`profiles/llm-share.yml`:**
```yaml
name: llm-share
description: Wire containers to the host ollama daemon over LAN.
config:
  environment.OLLAMA_HOST: "http://${HOST_LAN_IP}:11434"
devices:
  ollama-bin:
    type: disk
    source: /usr/local/bin/ollama
    path: /usr/local/bin/ollama
    readonly: "true"
  ollama-state:
    type: disk
    source: ${HOME}/.ollama
    path: ${HOME}/.ollama
    shift: "true"
```

**`profiles/dotfiles.yml`:**
```yaml
name: dotfiles
description: Bind common host dotfiles (.gitconfig, .hgrc) into containers.
config: {}
devices:
  gitconfig:
    type: disk
    source: ${HOME}/.gitconfig
    path: ${HOME}/.gitconfig
    readonly: "true"
    shift: "true"
  hgrc:
    type: disk
    source: ${HOME}/.hgrc
    path: ${HOME}/.hgrc
    readonly: "true"
    shift: "true"
```

Users add their own dotfiles by shadowing — copy `dotfiles.yml` into `~/.config/repoman/profiles.d/` and add `.zshrc`, `.tmux.conf`, etc.

### 3.2 Registry schema 3

```toml
[repoman]
schema = 3
output = "quiet"

[host]
lan_ip = "192.168.168.124"           # populated by `repoman setup` from `ip -4 addr show br0`

[defaults]
repos_root     = "~/repos"
backup_root    = "/nfs/repos"
logdir         = "~/.local/state/repoman"
incus_project  = "repoman"
default_image  = "images:ubuntu/26.04/cloud"
profiles       = ["default"]                    # safe default; users add others by editing or via override files

# [defaults.llm] block removed (was in schema 2).

[[project]]
name        = "isurus"
repo        = "isurus-project"
image       = "images:ubuntu/26.04/cloud"
profiles    = ["default", "claude-share", "llm-share"]
created     = "2026-04-28T15:00:00Z"
last_sync   = ""
backup      = true
```

### 3.3 Schema 2 → 3 migration

Implicit (no migration function — same pattern as v0.3's 1→2):
- `parse_registry` accepts schemas 1, 2, or 3.
- When loading schema 2: read `[defaults.llm.ollama_url]` (e.g., `"http://192.168.168.124:11434"`), strip `http://` prefix and `:11434` suffix, store remainder in `[host].lan_ip`. If parse fails or the field is missing, leave `lan_ip` empty (will be re-detected on next `setup` run).
- When loading schema 1: same behavior as schema 2 except `[host].lan_ip = ""` (no llm block to extract from).
- Final `Registry` literal in `parse_registry` always returns `schema: 3`.
- `default_registry` returns `schema: 3` with `[host].lan_ip = ""` (populated by `setup`).
- `serialize_registry` writes schema 3 with `[host]` block; never writes `[defaults.llm]`.

### 3.4 ProfileEntry struct (for `list_all`)

```reef
type ProfileEntry = struct
    name:        string       // e.g., "claude-share"
    source:      string       // "user" or "vendor"
    file_path:   string       // resolved path
    installed:   bool         // present in incus state
    drift:       bool         // installed-and-rendered-file-differs (computed lazily; false if not installed)
end ProfileEntry
```

### 3.5 HostFacts (substitution context)

```reef
type HostFacts = struct
    lan_ip: string
    user:   string
    home:   string
end HostFacts
```

Constructed at command entry (read from registry + env), passed to `profile.render`/`install`/etc.

---

## 4. Subcommand flows

### 4.1 `repoman profile list`

1. Resolve user dir + vendor dir.
2. Enumerate `*.yml` in each. Build a name → source map; user wins on collision (note as "user (shadows vendor)" in source column).
3. For each, query `incus profile show --project repoman <name>` to determine `installed`.
4. For installed entries, render the file and compute `drift = (rendered != incus_show_output)`.
5. Print a table:

```
NAME            SOURCE                 INSTALLED   DRIFT
claude-share    vendor                 yes         no
llm-share       user (shadows vendor)  yes         yes
dotfiles        vendor                 no          n/a
my-experiment   user                   no          n/a
```

Exit 0 always (informational).

### 4.2 `repoman profile install <name>` (or `--all`)

1. Resolve `name` to a file path via shadow lookup.
2. Read file → render with `HostFacts` (registry `[host].lan_ip`, env `USER`, env `HOME`). If `${HOST_LAN_IP}` is in the file but registry has empty `lan_ip`, fail with hint to run `repoman setup`.
3. Call `incus.profile_create_or_edit("repoman", name, rendered_yaml)`.
4. Print `==> installed <name> (source: user|vendor)`.

`--all`: enumerate the union of user and vendor profile names; install each (user shadows resolve correctly).

Exit 0 success, 1 install failure, 3 missing host facts.

### 4.3 `repoman profile diff <name>`

1. Resolve and render the file.
2. Fetch `incus profile show --project repoman <name>` stdout. If not installed, print "not installed; would install <name>" and the rendered content.
3. Compute and print a unified diff between rendered file and live incus state. Exit 0 if no diff, 1 if diff exists, 3 on resolution failure.

(Useful for "what will `profile install` change?" before running it.)

### 4.4 `repoman profile remove <name>`

1. `incus profile delete --project default <name>`. If it doesn't exist in incus, that's an error from incus — surface it to the user with exit 1 and a hint that they may not need to remove it.
2. Does NOT delete the file from `~/.config/repoman/profiles.d/<name>.yml`. User's files are user's. Print: `==> removed <name> from incus (file at <path> untouched)`.
3. If any project in the registry references the just-removed profile in its `profiles` list, print a warning naming the projects that will fail to relaunch — but exit 0; the removal succeeded.

### 4.5 `repoman profile show <name>`

1. Resolve and render. Print to stdout. Exit 0.

Useful for debugging templating, piping into other tools, or sanity-checking before install.

### 4.6 `repoman setup` (revised — much smaller)

Stages reduce from four to two:

1. **`incus_project`** — ensure `repoman` project exists (unchanged).
2. **`registry_defaults`** — write registry with `schema = 3`, `[host].lan_ip` populated from `detect_host_lan_ip()`, default `[defaults].profiles = ["default", "claude-share"]`.

The `claude_share_check` and `llm_share_profile` stages from v0.3 are gone. Profile installation is now `repoman profile install --all`.

Flags: `--non-interactive` only. No `--with-llm`/`--without-llm`.

Help text:

```
setup [--non-interactive]
    First-time host bootstrap: ensures Incus project 'repoman' exists,
    detects host LAN IP, writes initial registry. Run `repoman profile
    install --all` afterwards to install the vendor profile library.
```

### 4.7 `repoman new` (small addition: pre-launch profile validation)

Just before `incus.launch`, iterate `eff.profiles`. For each name except the magic incus default `"default"`, call `incus.profile_exists("default", name)`. (All repoman-managed profiles install into the incus `default` project — see §6 below — and our `features.profiles=false` setting on the `repoman` project means containers in it inherit profiles from `default`.) If any check returns false:

```
repoman: error: container references profile 'foo' but it's not installed in incus.
hint: repoman profile install foo
hint: repoman profile install --all   (to install the vendor library)
```

Exit 4 (resource-conflict class).

---

## 5. Testing

Mirrors the v0.3 testing posture: pure logic gets unit tests; effectful wrappers are smoke-tested.

**Pure tests** (run on every build):
- `profile.render` — given a YAML string with `${HOST_LAN_IP}`, `${USER}`, `${HOME}` and a `HostFacts`, returns the substituted output. Test cases: all three present, only some present, none present (no-op), unknown variable left as literal.
- `profile.vendor_dir` and `profile.user_dir` — given a `home`, return the documented paths.
- Schema 2 → 3 migration: load a fixture toml with `[defaults.llm.ollama_url]` set, verify `[host].lan_ip` is populated correctly; load one with the field missing, verify empty string; load schema 1, verify both work.
- Registry schema-3 round-trip serialize → parse.

**Smoke tests** (require an Incus host, gated on `REPOMAN_SMOKE=1`):
- `repoman profile install claude-share` against a fresh host produces a working profile.
- `repoman profile diff` correctly identifies drift between an edited file and the installed profile.
- `repoman profile remove` removes from incus but leaves the file.
- `repoman new <name>` against a registry with `profiles = [..., "missing-profile"]` errors early with the expected hint, before any incus mutation.
- Schema 2 registry on disk loads cleanly and re-saves as schema 3, with `[host].lan_ip` extracted from the old `ollama_url`.

---

## 6. Risks / mitigations

| Risk | Mitigation |
|---|---|
| Existing users have hand-authored `claude-share` profiles in incus that differ from the vendor `claude-share.yml`. `repoman profile install claude-share` would overwrite. | Document migration: before `install`, run `repoman profile diff claude-share` to see what would change; user can `cp /usr/local/share/repoman/profiles/claude-share.yml ~/.config/repoman/profiles.d/`, edit to match their hand-authored version, then `install` (user file wins). README has a "migrating to v0.4" section. |
| Vendor `dotfiles.yml` binds `~/.gitconfig` but a user doesn't have one. Container fails to launch. | Minimal initial set (.gitconfig, .hgrc) reduces this surface. README documents shadowing as the way to tailor. Future v0.5 could explore `optional: true` semantics if incus supports it. |
| `${HOST_LAN_IP}` can't be substituted if registry's `[host].lan_ip` is empty (e.g., `setup` couldn't detect br0). | `profile install` errors with a clear "run `repoman setup` first" hint. Detection happens in `setup`; it's the documented path. |
| User edits vendor profile file directly at `/usr/local/share/repoman/profiles/<name>.yml`. Next `make install` overwrites. | Document: vendor dir is owned by the package; user changes go in `~/.config/repoman/profiles.d/`. |
| `repoman profile install --all` order dependencies (e.g., what if profile A references profile B?). | YAGNI for v0.4 — no dependencies model. `--all` installs in alphabetical order; user re-installs if needed. Document. |
| `incus profile show` output format differs from what we render — diff always shows noise. | The render → install → show roundtrip should be stable for the limited template surface we use. If incus rewrites/normalizes the YAML, `diff` will show normalization noise; we accept this for v0.4 and document. v0.5 could add a smarter diff. |

---

## 7. Decisions and open questions

### Resolved decisions (locked into spec)

- **All repoman-managed profiles install in the incus `default` project.** v0.1/v0.2 already placed `claude-share` there; v0.3's `llm-share` was inconsistent (placed in `repoman` project). v0.4 unifies: every vendor and user profile installed via `repoman profile install` lands in `default`. The `repoman` project's `features.profiles=false` setting means containers in it inherit profiles from `default`, so this works without any per-profile project metadata. Users who want a different project can `incus profile copy` manually after install.
- **`repoman profile remove` does not touch the registry.** It only deletes from incus; if `[defaults].profiles` or any project's `profiles` list still names the removed profile, those references fail at next `new` (caught by pre-launch validation). `remove` prints a warning if removal would orphan a reference, but doesn't auto-edit the registry.
- **`profile diff` supports `--vendor` for shadow-vs-vendor comparison.** Default is rendered-file-vs-incus (most useful day-to-day). `--vendor` shows the user shadow vs the vendor file (useful when upgrading repoman). If the named profile isn't shadowed (no user file), `--vendor` errors with a clear hint.
- **Initial `[defaults].profiles = ["default"]`.** Just the magic incus `default` profile. Users add others (claude-share, llm-share, etc.) explicitly — via override files in `repos.d/` or by editing `repoman.toml` — after they've run `profile install` for whatever they want.

### Open questions

- **O-1: Per-host portability of `[host].lan_ip`.** A user moving `repoman.toml` between hosts would carry the old IP. Out of scope to automate — registry is per-host. Document.
- **O-2: Vendor `dotfiles.yml` failure mode.** If a user lacks `~/.gitconfig` or `~/.hgrc` on the host, the bind fails at container start. The minimal initial set reduces but doesn't eliminate this risk. Investigate whether incus supports `optional: true` on disk devices (newer incus versions may); if yes, add to the vendor profile. If no, document and let users shadow.
- **O-3: `incus profile show` output format stability.** If incus normalizes/reorders YAML on write, `profile diff` shows formatting noise rather than semantic drift. Acceptable for v0.4; revisit if it's painful in practice.
- **O-4: What if vendor library grows in v0.5+?** Users who shadowed an existing profile keep their shadow (good). Users who didn't get the new ones automatically (good). Risk: vendor adds a name that collides with a user's custom. Shadowing handles this — user wins. Documented in §6's risks.

---

## 8. Build sequence (suggested order)

1. Schema 3 plumbing in `config.reef`: add `[host]` substruct, drop `[defaults].llm`, schema 2→3 migration, schema constant bump in `default_registry`. Round-trip + migration tests.
2. `incus.profile_get(name)` wrapper. Small, used by `profile diff`/`list`/`show`.
3. `profile.reef` module skeleton + pure helpers (`vendor_dir`, `user_dir`, `render`). Unit tests.
4. `profile.lookup` and `profile.list_all` (filesystem-effectful). Smoke test by inspection.
5. `profile.install`, `profile.remove`, `profile.show`. Smoke-tested via subcommand wiring in step 8.
6. `profile.diff`. Smoke-tested via subcommand wiring.
7. Trim `setup.reef`: remove llm-stage, remove flag plumbing for `--with-llm`/`--without-llm`, remove `render_llm_share_template` + `template_contains_placeholder`. Update `apply_stage` to handle only `incus_project` and `registry_defaults` (with `[host].lan_ip` writing).
8. Wire `cmd_profile` dispatch in `cli.reef` covering all 5 verbs. Update `print_usage`. Add pre-launch validation in `cmd_new`.
9. `Makefile`: install profiles into `/usr/local/share/repoman/profiles/`.
10. Author the three vendor profile YAML files in `profiles/`.
11. README + VISION updates: profile library section, migration guide for users coming from v0.3, document the new subcommands.
12. Smoke run on a fresh host: `setup` → `profile install --all` → `new myproj` (with profiles) → `shell` → verify everything works → `profile remove` → `profile diff` to verify drift detection. Tag v0.4.0.
# repoman CI + binary release — design

**Date:** 2026-06-02
**Status:** Approved (design), pending implementation
**Author:** Chris Tusa <chris.tusa@leafscale.com>

## Goal

Build, test, and release repoman binaries automatically via **Isurus CI**, using
the prebuilt **reef-lang toolchain container** as the build environment. On every
push/PR: build + test. On a version tag: also package a binary bundle and publish
it as an Isurus release asset.

## Context

- repoman is a reef *application* (compiles to a single `build/repoman` binary via
  `reefc`), not the reef compiler. It also ships `profiles/*.yml` and
  `recipes/{docker,claude}/*` that `make install` lays under
  `/usr/local/share/repoman`.
- Isurus CI config is `.isurus-ci.yml` at the repo root, hg-native (`hg push`
  triggers; `hg tag vX && hg push` → tag event). Steps run in `docker:` images;
  `container-registry:` authenticates private pulls; a top-level `release:` block
  attaches `assets:` globs to the release on tag using a `releases:write` token.
- The build image `registry.sharkos.one/reef/reef-builder:latest` already contains
  a **pre-installed reef compiler** (`reefc` on PATH, runtime + clang/lld baked in;
  `reefc doctor` passes). No `opam env` setup is needed — that is only for building
  the compiler from OCaml source, which repoman does not do.
- Reference pipelines: `~/repos/reef-lang/.isurus-ci.yml` (canonical Isurus
  example) and `~/repos/zygaena-project/coral/.woodpecker.yml` (a reef app release,
  pre-Isurus). This design follows reef-lang's structure.

## Decisions

- **Release contents:** binary bundle only (no source tarball).
- **Installer:** a standalone `install.sh` inside the bundle — end users need no
  reefc and no Makefile to install.
- **Arch:** `linux-amd64` only (the reef-builder image and repoman's Incus-host
  target are x86-64). arm64 deferred.
- **Build image tag:** `:latest` (floats with the toolchain, matching reef-lang),
  not a pinned `:0.6.5`.
- **Triggers:** build + test on `[push, pull_request, tag]`; package + release on
  `[tag]` only. Single `when:` filter map, no top-level `branch:` gate (a branch
  gate is incompatible with PR CI — per reef-lang's CLAUDE.md note).
- **Version source of truth:** the `version` field in `reef.toml` (currently
  `0.6.0`). Packaging derives the version from it; the release fires off `$CI_TAG`.

## Components

### 1. `.isurus-ci.yml` (repo root, new)

```yaml
container-registry:
  - url: registry.sharkos.one
    secret: SHARKOS_REGISTRY_CREDS

when:
  event: [push, pull_request, tag]

steps:
  - name: build
    docker: { image: registry.sharkos.one/reef/reef-builder:latest }
    commands:
      - reefc doctor
      - make all
      - ./build/repoman --version
    timeout: 30m

  - name: test
    docker: { image: registry.sharkos.one/reef/reef-builder:latest }
    commands:
      - make test
    timeout: 30m

  - name: package
    docker: { image: registry.sharkos.one/reef/reef-builder:latest }
    when: { event: [tag] }
    commands:
      - ./scripts/package-binary.sh
      - ls -la dist/
    timeout: 30m

release:
  tag: "$CI_TAG"
  title: "repoman $CI_TAG"
  assets:
    - dist/*.tar.gz
    - dist/*.sha256
  secret: ISURUS_RELEASE_TOKEN
  when:
    event: [tag]
```

Notes:
- `make all` lives only in `build`. Steps share the cloned workspace and run
  sequentially (pipeline halts on first failure), so `package` only runs after
  `build`/`test` pass. Each target is also self-sufficient: `make test` compiles
  and runs the test files directly via `reefc run` (no dependency on
  `build/repoman`), and `package-binary.sh` calls `make install`, whose phony
  `build` prerequisite rebuilds the binary. No repeated `make all`.
- `reefc doctor` in `build` gives an early, legible failure if the toolchain image
  is broken.

### 2. `scripts/package-binary.sh` (new, executable)

Produces `dist/repoman-<version>-linux-amd64.tar.gz` and a matching `.sha256`.

Behavior:
1. Derive `VERSION` from `reef.toml` (`grep '^version' | sed`), allow override via
   `$1`.
2. `NAME=repoman-${VERSION}-linux-amd64`, `DIST=${REPOMAN_DIST:-dist}`.
3. Stage the real install tree by reusing the Makefile:
   `make install DESTDIR="$STAGE/$NAME" PREFIX=/usr/local`
   → `$STAGE/$NAME/usr/local/{bin/repoman, share/repoman/...}`.
4. Add `README.md`, `LICENSE`, and a generated `install.sh` (see §3) to
   `$STAGE/$NAME/`.
5. `tar -czf "$DIST/$NAME.tar.gz" -C "$STAGE" "$NAME"`.
6. `sha256sum "$DIST/$NAME.tar.gz" > "$DIST/$NAME.tar.gz.sha256"`.
7. `set -eu`; clean up `$STAGE` on exit.

Rationale for reusing `make install`: the tarball's tree stays byte-identical to a
real install, so there is one definition of the install layout (DRY) — when a new
recipe/profile is added, the bundle picks it up automatically.

### 3. Bundled `install.sh` (inside the tarball)

Relocatable installer; needs no reefc, no make. Run from the unpacked bundle dir:

```sh
#!/bin/sh
set -eu
PREFIX="${PREFIX:-/usr/local}"
here="$(cd "$(dirname "$0")" && pwd)"
# Copy the staged usr/local tree into PREFIX.
cp -a "$here/usr/local/." "$PREFIX/"
echo "repoman installed under $PREFIX"
"$PREFIX/bin/repoman" --version
```

- Honors `PREFIX` (default `/usr/local`); preserves perms (`cp -a`) so the
  launcher recipe stays `0755`.
- Mirrors what `make install` does, minus the build dependency.

### 4. `.hgignore` (edit)

Add `dist/` so packaging output is not accidentally committed.

## Data flow

```
hg push (branch)            -> build + test
hg push (PR)                -> build + test
hg tag vX.Y.Z && hg push    -> build + test + package -> dist/*.tar.gz(+.sha256)
                                                       -> release: attach assets to vX.Y.Z
```

## Prerequisites (operator-side, outside this repo)

Two CI secrets must exist for the repoman repo (or its org) in Isurus
**CI/CD > Secrets**:
- `SHARKOS_REGISTRY_CREDS` — Harbor robot creds JSON
  `{"username":"robot$ci","password":"<token>"}` to pull the builder image.
- `ISURUS_RELEASE_TOKEN` — token with `releases:write` scope.

reef-lang already uses both names; if they are org-scoped, repoman inherits them.

## Testing / verification

- **Local dry runs (no CI needed):**
  - `make all && make test` inside the builder image (or locally) stays green.
  - `./scripts/package-binary.sh` produces a tarball; unpack to a temp dir, run its
    `install.sh` with `PREFIX=$(mktemp -d)`, and confirm `bin/repoman --version`
    prints the bundle version and the claude launcher lands at `0755`.
- **CI smoke:** push a branch → build+test pipeline goes green. Then a throwaway
  tag (or the next real release tag) exercises package + release end to end.

## Out of scope

- Source tarball, multi-arch (arm64), signing/notarization, publishing to any
  index beyond Isurus releases, and container-image publishing for repoman itself.

## Files touched

| File | Change |
|------|--------|
| `.isurus-ci.yml` | new — pipeline + release block |
| `scripts/package-binary.sh` | new, `0755` — binary bundle + sha256 |
| `.hgignore` | add `dist/` |
| `Makefile` | (if needed) confirm `install` works with `DESTDIR`/`PREFIX` — already verified |
| `README.md` | brief "Releases / CI" note (optional) |
# repoman rename — design

**Date:** 2026-07-15
**Status:** Approved (design), pending implementation
**Author:** Chris Tusa <chris.tusa@leafscale.com>

## Goal

Add a `repoman rename <old> <new>` subcommand that renames a project as a single
operation across every layer that encodes its name: the incus container, the
`repo` bind-mount device, the host repo directory, the registry entry, and
(opt-in) the Claude conversation-history slug. The command is **idempotent and
resumable** so it also repairs a project whose layers have drifted out of sync.

## Context / motivation

This feature comes directly from a real incident. A project's codename `brainbox`
was renamed to the product name `driftohm`. The user renamed the host repo
directory (`~/repos/brainbox → ~/repos/driftohm`) and the Claude history slug
themselves, but the incus container and the repoman registry were left on the old
name. The result:

- `repoman shell brainbox` still dropped into the repo — but only because the
  container was *running* and its bind mount was pinned to the (renamed) inode. A
  restart would have broken the mount entirely, since the device `source` still
  pointed at the now-missing `~/repos/brainbox`.
- Claude history appeared "missing": in-container Claude runs with cwd
  `/home/ctusa/repos/brainbox` (the `repo` device `path`), so it looked for the
  slug `-home-ctusa-repos-brainbox`, which had been renamed to
  `-home-ctusa-repos-driftohm`. Nothing was lost — just unreachable from the old
  cwd.

The manual fix (stop → `incus rename` → repoint device → edit registry → start)
is exactly what this command should automate.

### How names couple today

- **Registry** (`~/.config/repoman/repoman.toml`): each `[[project]]` has a
  `name` (project + container identity) and a `repo` (host dirname under
  `repos_root`). `cmd_new` defaults `repo = name` but `--repo` can decouple them.
- **incus container**: named `name`, in project `reg.defaults.incus_project`
  (`repoman`).
- **`repo` disk device**: created by `cmd_new` as device index 0, named `"repo"`,
  with `source = path = <repos_root>/<repo>` (host path and container-internal
  path are identical). Additional override mounts are `mount-1`, `mount-2`, …
  and are unrelated to the rename.
- **Claude history**: keyed by the in-container cwd, which is the `repo` device
  `path` = `<repos_root>/<repo>`. Slug = that path with `/` → `-`
  (e.g. `-home-ctusa-repos-driftohm`). History lives on the host under
  `~/.claude/projects/<slug>/` (bind-mounted into the container via the
  `claude-state` device).

## CLI surface

```
repoman rename <old> <new> [--yes] [--migrate-claude-history]
```

- Exactly two positional arguments: current name, new name.
- `--yes` — skip the confirmation prompt (mirrors `cmd_remove`).
- `--migrate-claude-history` — also move
  `~/.claude/projects/-…-<old>` → `-…-<new>`. Opt-in, because it reaches into
  Claude's internal on-disk layout, which repoman does not otherwise depend on.
- Registered in `dispatch` and the help text.

## What moves — the `name` vs `repo` rule

repoman's model permits `repo != name`. Rename therefore splits into two tiers:

- **Identity layer — always moved:** registry `name`, incus container name.
- **Directory layer — moved only when `proj.repo == <old>`** (the coupled common
  case, including the incident): registry `repo` field, host dir
  `<repos_root>/<old> → <repos_root>/<new>`, the `repo` device `source`+`path`,
  and (with `--migrate-claude-history`) the Claude slug.

When `proj.repo != <old>` the user deliberately decoupled the dirname, so rename
touches only the identity layer and leaves the repo dir, device, and history
alone. This is inferred from the data — no extra flag. In that case the device
`path`/`source` and the Claude slug are derived from `repo` (unchanged), so
history stays valid automatically.

**Decoupling is load-bearing, not a wart.** It is the only way to give a nested
or awkwardly-named repo path a valid, short container identity — a container
cannot be named e.g. `leafscale-infrastructure/portal.leafscale.com` (slashes,
length, charset all fail `incus.validate_name`), so the `portal` project maps
that nested path to the short name `portal`. Enforcing `repo == name` was
considered and rejected: it would break this active pattern. The predictability
concern it raises is addressed by the case-aware confirmation prompt below, which
makes the two-tier behavior self-explaining at the moment it matters.

### Confirmation prompt (case-aware)

The prompt states exactly which layers move and, in the decoupled case, why the
repo dir is left alone and names it explicitly:

```
# coupled (proj.repo == <old>):
repoman rename driftohm mist
  will move:
    - incus container   driftohm → mist
    - registry entry    driftohm → mist
    - repo directory    ~/repos/driftohm → ~/repos/mist
  your source is moved intact, never deleted.
  continue? [y/N]

# decoupled (proj.repo != <old>):
repoman rename portal gateway
  will move:
    - incus container   portal → gateway
    - registry entry    portal → gateway
  repo directory unchanged (~/repos/leafscale-infrastructure/portal.leafscale.com)
  — this project's dir name is decoupled from its container name.
  continue? [y/N]
```

With `--migrate-claude-history` a `- claude history  <old-slug> → <new-slug>`
line is added in the coupled case (and omitted, with the dir, in the decoupled
case).

## Algorithm (idempotent, resumable)

Inspect every layer first, then change only what is still on the old name. The
order is chosen so a mid-sequence failure leaves a re-runnable state, and so the
container is stopped before any operation that requires it.

1. **Resolve state** of each layer:
   - registry: is there an entry for `<old>`? for `<new>`? (and the matched
     project's `repo` value)
   - container: does `<old>` exist? does `<new>` exist? current run-state?
     (A `container_state` *probe failure* — incus unreachable — aborts here
     with `Err` before any mutation; only a confirmed-empty `"MISSING"` is
     treated as genuine absence.)
   - host dir: does `<repos_root>/<old>` exist? does `<repos_root>/<new>` exist?
   - (if flag) does the `<old>` slug dir exist? the `<new>` slug dir?
2. **Guard rails** (refuse rather than guess):
   - Nothing on either name anywhere → `Err "no such project: <old>"`.
   - `<new>` fails `incus.validate_name` → `Err`.
   - `<old>` and `<new>` both exist as **distinct live** things (e.g. two
     different containers, or two registry entries) → `Err` — rename must not
     merge or clobber. (The benign "already partly renamed" states — same
     project, some layers ahead — are allowed and resumed.)
3. **Confirm** unless `--yes`: print the case-aware plan (see *Confirmation
   prompt* above) — the exact layers that will move, old → new, and in the
   decoupled case the named repo dir that will be left untouched and why. Use
   `console.confirm_default_no`.
4. Open the per-invocation log (after confirmation), verb `"rename"`.
5. **Stop** the container before renaming it — only the **old-named** container,
   and only when it exists and is running (`incus rename` requires it stopped).
   The new-named container is never stopped: if it is already running, a prior
   run completed fully (start is the last step), so a no-op re-run does not bounce
   a healthy container; a container needing device repair was left stopped by the
   failed run.
6. **Host dir** (directory tier only): if `<repos_root>/<old>` exists and
   `<repos_root>/<new>` does not → rename it. If `<new>` already exists and
   `<old>` is gone → skip (already done). If **both** exist → `Err` (never
   overwrite). If **neither** exists → `Err "repo directory not found"` (the
   source is gone; do not repoint the device at a missing path).
7. **Container**: if still named `<old>` → `incus rename <old> <new>`. If already
   `<new>` → skip. If **neither** container exists (e.g. deleted out of band) →
   skip with a logged note and continue; rename still repairs the registry.
8. **Repo device** (directory tier only): `incus config device set` the `repo`
   device `source` and `path` to `<repos_root>/<new>`, targeting the container by
   its **current** name (already `<new>` after step 7). Idempotent — safe even if
   already correct.
9. **Registry**: `config.rename_project(reg, old, new)` then atomic `config.save`.
   If the registry already holds `<new>` and not `<old>` → skip.
10. **Claude slug** (only with `--migrate-claude-history`, directory tier): same
    exists/skip rules as the host dir, but best-effort — a failed move or a
    both-exist collision is a **warning**, not a hard error (history migration
    is opt-in and never blocks the rename).
11. **Ensure the container ends running**: re-read its current state and
    `incus start` it if it exists and is not already running. (This supersedes
    the original "restart iff it was running before" — a deterministic
    end-running state is resume-safe: an interrupted-then-resumed run always
    brings the container back up, and repoman containers are meant to be up.)

### Failure handling

- Every step logs its action (`==> …`) to the per-invocation log, mirroring
  `cmd_new`/`cmd_remove`.
- On failure mid-sequence, report which layers completed and which remain, and
  instruct the user to **re-run the identical command** — idempotency resumes it.
- Never overwrite an existing target directory: step 6 (host dir) hard-errors on
  a both-exist collision; step 10 (opt-in Claude slug) warns and leaves both in
  place rather than blocking.
- The most fragile external step is `incus rename` (requires the container
  stopped); step 5 guarantees that precondition.

## New / changed code

### `src/config.reef`
- `fn rename_project(reg: Registry, old: string, new: string): rg.Result[Registry, string]`
  — mirrors `update_last_sync`: locate the project by `old`; error if not found;
  error if a different entry already uses `new`; produce a copied `Project` with
  `name = new` and `repo = new` **iff** the old `repo == old` (else `repo`
  unchanged); rebuild via `with_projects`.

### `src/incus.reef`
Four thin `run_incus` wrappers (today only `restart` / `delete_container` /
`device_add_disk[_opts]` exist):
- `fn stop(project, name): rg.Result[bool, string]` → `["stop", "--project", P, name]`
- `fn start(project, name): rg.Result[bool, string]` → `["start", "--project", P, name]`
- `fn rename_container(project, old, new): rg.Result[bool, string]`
  → `["rename", "--project", P, old, new]`
- `fn device_set(project, name, dev: string, keyvals: [string]): rg.Result[bool, string]`
  → `["config", "device", "set", "--project", P, name, dev, keyvals…]`

Run-state is read via the existing `container_state` / `container_exists`
helpers rather than a new probe.

### `src/cli.reef`
- `fn cmd_rename(argv: [string]): int` following the `cmd_remove` skeleton
  (load registry → find `<old>` → guard rails → confirm → log → per-layer
  mutate → save), implementing the algorithm above.
- Wire `rename` into `dispatch` and the help/usage text.

### Host filesystem moves
- Host dir and slug renames use `iofile.rename` (a same-filesystem `rename(2)`;
  both paths live under `$HOME`). Consistent with the codebase's existing
  `iofile.rename` use in `config.save`. No shelling out to `mv`.

## Testing

### Unit — `tests/test_config_rename.reef` (mirrors `test_config_mutate.reef`)
- Happy path, `name == repo`: both `name` and `repo` become `new`.
- `name != repo`: only `name` changes; `repo` untouched.
- Collision: `new` already used by another project → `Err`.
- Not found: `old` absent → `Err`.

### Integration (manual — documented recipe)
repoman has no incus/filesystem mock layer (existing suites are pure-logic:
config, paths, hermes-classify), so the incus + dir + slug steps are validated by
a documented manual recipe:
1. `repoman new tmpname` (or reuse a scratch project), note its container + dir.
2. `repoman rename tmpname tmpname2` → assert container renamed, `repo` device
   `source`/`path` repointed, `~/repos/tmpname2` present, registry updated,
   container back to its prior run-state.
3. Re-run `repoman rename tmpname tmpname2` → asserts idempotency (no-op success,
   no errors).
4. With `--migrate-claude-history`, assert the slug dir moved.

## Out of scope (YAGNI)

- No renaming of incus **projects** (`reg.defaults.incus_project`) — only the
  per-project container/identity.
- No renaming of override mounts (`mount-1`, …) or arbitrary devices — only the
  `repo` device.
- No cross-filesystem host moves — `rename(2)` within `$HOME` is assumed; a
  cross-device `EXDEV` surfaces as an `Err` telling the user to move the dir
  manually, then re-run (idempotency handles the rest).
- No history-slug migration by default — it is opt-in behind
  `--migrate-claude-history`.