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 (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:

Provision per-project Incus containers that bind-mount the user's git/hg repos (cmd_new)
Backup ~/repos/ to NFS via rsync (cmd_sync)
Manage the Incus profiles that share host-side resources (configs, agents, bind-mountable runtimes) into containers
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.

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:

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:

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:

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

[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`)

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)

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`

Resolve user dir + vendor dir.
Enumerate *.yml in each. Build a name → source map; user wins on collision (note as "user (shadows vendor)" in source column).
For each, query incus profile show --project repoman <name> to determine installed.
For installed entries, render the file and compute drift = (rendered != incus_show_output).
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`)

Resolve name to a file path via shadow lookup.
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.
Call incus.profile_create_or_edit("repoman", name, rendered_yaml).
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>`

Resolve and render the file.
Fetch incus profile show --project repoman <name> stdout. If not installed, print "not installed; would install " and the rendered content.
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>`

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.
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).
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>`

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:

incus_project — ensure repoman project exists (unchanged).
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)

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.
incus.profile_get(name) wrapper. Small, used by profile diff/list/show.
profile.reef module skeleton + pure helpers (vendor_dir, user_dir, render). Unit tests.
profile.lookup and profile.list_all (filesystem-effectful). Smoke test by inspection.
profile.install, profile.remove, profile.show. Smoke-tested via subcommand wiring in step 8.
profile.diff. Smoke-tested via subcommand wiring.
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).
Wire cmd_profile dispatch in cli.reef covering all 5 verbs. Update print_usage. Add pre-launch validation in cmd_new.
Makefile: install profiles into /usr/local/share/repoman/profiles/.
Author the three vendor profile YAML files in profiles/.
README + VISION updates: profile library section, migration guide for users coming from v0.3, document the new subcommands.
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.