docs: make ix.nix the starter surface

Closes #1503

Author: andrewgazelka

docs/ix-fleet/overview.md

@@ -75,7 +75,7 @@ each node key matches its `name`; and that every `dependsOn` names a real node.
   the simple attr lets the native multi-VM `ix up .#a .#b --build-vm <builder>`
   derive each VM name. The `<node>-system` package stays as a build alias. Merge
   the fleet's `nixosConfigurations` into your flake's top-level
-  `nixosConfigurations` (see `templates/dev/flake.nix`).
+  `nixosConfigurations` (see `templates/ix/flake.nix`).
 - **`ReplacementImage`** (`:34`): `imageName`, `imageTag`, `destination`,
   `source`, `sourceDrv` (the OCI image derivation to realise and push).
 - **`HealthCheck`** (`:54`): `description`, `command` (argv), `timeoutSec`,

examples/dev-fleet/README.md

@@ -1,6 +1,6 @@
-# Dev fleet
+# ix fleet
 
-A forkable dev environment (RFC 0007). One [`dev.nix`](dev.nix) - an ordinary
+A forkable ix environment (RFC 0007). One [`ix.nix`](ix.nix) - an ordinary
 NixOS module - is the source of truth for the per-VM environment, the fleet
 topology, and an opt-in shared SMB volume that gives the whole fleet one Claude
 (and ix) login.
@@ -12,13 +12,13 @@ ix up
 ```
 
 This example declares a multi-node `ix.dev.fleet`. Omit that block and the same
-`dev.nix` is a **single VM named `dev`** that `ix up` (or `nix run .#up` in the
-forkable [template](../../templates/dev)) builds and creates - the simplest way
-to consume a `dev.nix` for one new VM. The fleet below is the scale-up.
+`ix.nix` is a **single VM named `dev`** that `ix up` (or `nix run .#up` in the
+forkable [template](../../templates/ix)) builds and creates - the simplest way
+to consume an `ix.nix` for one new VM. The fleet below is the scale-up.
 
 ## Shape
 
-- [`dev.nix`](dev.nix) is the module a user edits after `ix dev init`. Top-level
+- [`ix.nix`](ix.nix) is the module a user edits after `ix init`. Top-level
   NixOS config (`environment.systemPackages`, `programs.git.enable`) is the
   environment; `ix.dev.fleet` is the topology; `ix.dev.shared` turns on the
   identity volume. Claude Code and Codex are installed by default.

examples/dev-fleet/default.nix

@@ -1,10 +1,10 @@
 { index }:
 
-# `mkDev` consumes the dev module in ./dev.nix and returns the same shape as
+# `mkDev` consumes the ix module in ./ix.nix and returns the same shape as
 # `mkFleet`, so `ix up` / `nix run .#dev-fleet-up` work unchanged. `src = ./.`
 # is what the template's flake.nix passes as the flake `self`; it is what gets
 # materialized at /ix on every node for recursion.
 index.lib.mkDev {
-  module = ./dev.nix;
+  module = ./ix.nix;
   src = ./.;
 }

examples/dev-fleet/ix.nix

@@ -0,0 +1,30 @@
+# A forkable ix environment (RFC 0007). This is an ordinary NixOS module: write
+# your environment at the top level, and use `ix.dev.*` for the fleet and the
+# shared volume. After `ix init` this is the one file you edit.
+{ pkgs, ... }:
+{
+  # Your environment - applied to every VM (single or fleet).
+  environment.systemPackages = [
+    pkgs.ripgrep
+    pkgs.jq
+  ];
+  programs.git.enable = true;
+
+  # Claude Code + Codex are installed by default; toggle either off here.
+  # ix.dev.agents.codex = false;
+
+  # A fleet: two interchangeable agents plus a builder that opts out of the
+  # shared volume below. Drop `ix.dev.fleet` entirely for a single VM.
+  ix.dev.fleet = {
+    agent.replicas = 2;
+    builder.dependsOn = [ "agent" ];
+  };
+
+  # One shared Claude (and ix) login for the fleet, over an SMB volume. The
+  # first `claude login` on any agent logs in every agent; `builder` opts out.
+  ix.dev.shared = {
+    enable = true;
+    ix = true; # also share ~/.n so a node can spawn more VMs (claude is shared by default)
+    excludeNodes = [ "builder" ];
+  };
+}

flake.nix

@@ -342,9 +342,9 @@
         };
       };
       overlays.default = ix.overlay;
-      templates.dev = {
-        path = ./templates/dev;
-        description = "Forkable ix dev environment: one dev.nix for a default VM, a fleet, and shared Claude/ix auth (RFC 0007)";
+      templates.ix = {
+        path = ./templates/ix;
+        description = "Forkable ix environment: one ix.nix for a default VM, a fleet, and shared Claude/ix auth";
       };
       packages = collect "packages";
       checks = collect "checks";

lib/dev/options.nix

@@ -1,7 +1,7 @@
 /**
   The `ix.dev.*` option surface (RFC 0007).
 
-  This is what lets a forked `dev.nix` read like an ordinary NixOS module: you
+  This is what lets a forked `ix.nix` read like an ordinary NixOS module: you
   write `environment.systemPackages` and `programs.git.enable` at the top level
   as usual, and reach for `ix.dev.*` only to describe the agents, the fleet
   shape, and the shared identity volume. `mkDev` reads these options to plan the

lib/image/dev.nix

@@ -1,11 +1,11 @@
 /**
   `mkDev`: an opinionated dev-fleet layer over `mkFleet` (RFC 0007).
 
-  Consumes one user-owned NixOS module (the forkable `dev.nix`) and returns the
+  Consumes one user-owned NixOS module (the forkable `ix.nix`) and returns the
   same result shape `mkFleet` does (`.up`, `.health`, `.diff`, `withNodePrefix`,
   …), so it drops straight into the flake/example plumbing.
 
-  The user's `dev.nix` is an ordinary NixOS module: `environment.systemPackages`
+  The user's `ix.nix` is an ordinary NixOS module: `environment.systemPackages`
   and friends at the top level, plus `ix.dev.*` (see `lib/dev/options.nix`) to
   describe the agents, fleet, and shared volume. `mkDev` reads `ix.dev` once via
   a probe eval to plan the fleet, then builds each node with the same module:
@@ -24,7 +24,7 @@
   Curried `mkDevFor hostSystem { module, src }` so flake/example evaluation can
   build the wrapper derivations for the requested system, mirroring `mkFleetFor`.
   `src` is the flake `self`, threaded in by the template's `flake.nix`; it is
-  what gets materialized at `/ix`. The user's `dev.nix` never mentions it.
+  what gets materialized at `/ix`. The user's `ix.nix` never mentions it.
 */
 {
   lib,

templates/dev/README.md templates/ix/README.mdtemplates/dev/README.md renamed to templates/ix/README.md

@@ -1,32 +1,31 @@
-# My ix dev environment
+# My ix environment
 
-A forkable dev VM config (RFC 0007). [`dev.nix`](dev.nix) is an ordinary NixOS
+A forkable ix VM config (RFC 0007). [`ix.nix`](ix.nix) is an ordinary NixOS
 module that is the source of truth for your VM environment, an optional fleet,
 and an optional shared SMB volume that gives a fleet one Claude (and ix) login.
 
 ## Start
 
 ```sh
-nix flake init -t github:indexable-inc/index#dev
+nix flake init -t github:indexable-inc/index#ix
 ```
 
-Then edit [`dev.nix`](dev.nix): write your environment at the top level
+Then edit [`ix.nix`](ix.nix): write your environment at the top level
 (`environment.systemPackages`, `programs.*`, `services.*`), and use `ix.dev.*`
 for the agents, a `fleet`, and a `shared` volume. Commit it to your own repo and
 fork it freely. `flake.nix` is boilerplate you should not need to touch.
 
 ## Use
 
 Out of the box (no `ix.dev.fleet` declared) this config is a **single VM named
-`dev`**. One command builds `dev.nix` into an OCI image and creates that VM:
+`dev`**. One command builds `ix.nix` into an OCI image and creates or updates that VM:
 
 ```sh
 nix run .#up
 ```
 
-That is the "consume my `dev.nix` for a new VM" path: `nix run .#up` realises
-the image from your config and creates the VM through the same call `ix new`
-uses. Re-run it after editing `dev.nix` to roll the VM forward.
+That is the "consume my `ix.nix` for a new VM" path: `nix run .#up` realises
+the image from your config and creates or updates the VM through `ix up`. Re-run it after editing `ix.nix` to roll the VM forward.
 
 Declare nodes under `ix.dev.fleet` and the same command brings up the whole
 fleet instead. The other verbs mirror `ix fleet <sub>`:
@@ -48,5 +47,4 @@ first `claude login` on any node logs in the whole fleet, and a new replica
 needs no extra auth. Add `ix.dev.shared.ix = true` to also share `~/.n` so a
 node can spin up more VMs from `/ix`.
 
-> Default for new VMs: pointing a bare `ix up` at this config (`ix dev use`) is
-> wired in the `ix` CLI; see RFC 0007. Until then, use `nix run .#up`.
+> Default VM path: `ix up` should discover `./ix.nix`; until that CLI path lands, use `nix run .#up`.

templates/dev/flake.nix templates/ix/flake.nixtemplates/dev/flake.nix renamed to templates/ix/flake.nix

@@ -1,5 +1,5 @@
 {
-  description = "My ix dev environment (RFC 0007)";
+  description = "My ix environment (RFC 0007)";
 
   inputs.index.url = "github:indexable-inc/index";
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
@@ -25,13 +25,13 @@
       # declared); `.#health` / `.#diff` / `.#down` mirror `ix fleet <sub>`.
       # `<node>-system` is each node's system closure.
       #
-      # `module = ./dev.nix` is your config. `src = self` is the source
+      # `module = ./ix.nix` is your config. `src = self` is the source
       # materialized at /ix on every node so a VM can rebuild itself - keep it.
       packages = forEach (
         system:
         let
           dev = index.lib.mkDevFor system {
-            module = ./dev.nix;
+            module = ./ix.nix;
             src = self;
           };
         in
@@ -52,7 +52,7 @@
       # ix VM closures are x86_64-linux, so the configs come from that builder.
       inherit
         (index.lib.mkDevFor "x86_64-linux" {
-          module = ./dev.nix;
+          module = ./ix.nix;
           src = self;
         })
         nixosConfigurations

templates/dev/dev.nix templates/ix/ix.nixtemplates/dev/dev.nix renamed to templates/ix/ix.nix

@@ -1,4 +1,4 @@
-# Your ix dev environment (RFC 0007).
+# Your ix environment (RFC 0007).
 #
 # This is an ordinary NixOS module. Write your environment at the top level the
 # way you would any NixOS config; reach for `ix.dev.*` only to describe the