# 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.