home-manager: Share Git and Jujutsu configuration

Move Git, Git LFS and `diff-so-fancy` into the common home module.
Enable Jujutsu with the same identity and add it to the devshell.

Document `jj` workflows and prefer them in Jujutsu workspaces.

AGENTS.md

@@ -187,6 +187,13 @@ in churn.
 
 ## Conventions
 
+- Prefer `jj` for status, diffs, history, commits, rebases and remote operations when it is
+  available and the checkout has a Jujutsu workspace. Use Git when `jj` is unavailable or the
+  checkout is Git-only, and for Git-specific tooling. The shared home config and devshell install
+  `jujutsu`; see [`docs/deployment.md#version-control`](docs/deployment.md#version-control) for
+  setup and the workflow. Inspect `jj status`, `jj diff` and `jj log` before editing; `jj`
+  snapshots working-copy changes automatically, so preserve existing user changes and use
+  explicit revisions when rewriting history or moving bookmarks.
 - Format with `nixpkgs-fmt` (`fmt`). 2-space indent, `inherit (...)` blocks at the top of `let` —
   prefer `inherit (lib) mkOption ...;` (and bare use) over qualifying inline as `lib.mkOption`.
   **Ask before running `fmt`** — some files aren't canonically formatted, so `fmt` can reindent a
@@ -212,11 +219,12 @@ in churn.
   command, option or upstream technical term such as QEMU's machine type.
 - Commit subjects follow `area/scope: Capitalized summary` (e.g. `nixos/home: ...`); keep logically
   distinct changes in separate commits. Aim for 50-character subjects and do not exceed 72
-  characters. Hard-wrap commit body lines at 72 characters; Git preserves an unwrapped `-m`
-  argument as one long line, so include literal line breaks or use a commit-message file. Before
-  reporting a commit, inspect `git show -s --format=%B HEAD` and amend it if any line exceeds 72
-  characters. A concise body describing the change and its rationale is welcome when the subject
-  alone does not provide enough context — keep it to the essentials rather than restating the diff.
+  characters. Hard-wrap commit body lines at 72 characters; `-m` preserves unwrapped text, so
+  include literal line breaks or use a commit-message file. Before reporting a commit, inspect
+  `jj log --no-graph -r <revision> -T description` (or `git show -s --format=%B HEAD` in a Git-only
+  checkout) and amend its description if any line exceeds 72 characters. A concise body describing
+  the change and its rationale is welcome when the subject alone does not provide enough context —
+  keep it to the essentials rather than restating the diff.
   `Co-Authored-By` is the only trailer used here; do **not** add a `Claude-Session` link (or any
   other session/tooling trailer).
 - **"Logically distinct" means unrelated** — two different applications, two boxes that have nothing

devshell/default.nix

@@ -32,5 +32,6 @@ in
       exec ${deploy-rs.deploy-rs}/bin/deploy --skip-checks "$@"
     '')
     home-manager
+    jujutsu
   ];
 }

docs/README.md

@@ -24,7 +24,7 @@ Not every box fits this pattern, but **colony** and **home** are organised this
   nixpkgs channels, shared module inventory.
 - [`networking.md`](networking.md) — network assignments, domains, site topologies, router HA,
   the AS211024 L2 mesh, BGP, WireGuard, Tailscale.
-- [`deployment.md`](deployment.md) — deploy-rs, devshell commands, secrets workflow, CI.
+- [`deployment.md`](deployment.md) — deploy-rs, devshell commands, `jj` workflow, secrets, CI.
 - [`nixpkgs-upgrade.md`](nixpkgs-upgrade.md) — guided procedure for the periodic upgrade of the four
   nixpkgs channels and home-manager (fork rebase, stable bumps, input review).
 - [`install-box.md`](install-box.md) — guided procedure for installing a new box, from the booted

docs/deployment.md

@@ -120,6 +120,43 @@ VM's unix sockets from `/run/vms/<vm>/` on `<host>` over SSH):
 | `vm-monitor <host> <vm>` | QEMU monitor socket in `minicom`. |
 | `vm-viewer <host> <vm>` | SPICE display in `virt-viewer` (not on Darwin). |
 
+## Version control
+
+The shared [Home Manager module](../home-manager/modules/common.nix) enables `programs.git`
+and `programs.jujutsu`, including Git LFS and `diff-so-fancy`, for graphical and non-graphical
+homes. Jujutsu uses the identity declared in `programs.git.settings.user`; Home Manager writes
+its `jj/config.toml`. The [devshell](../devshell/default.nix) also installs `jujutsu`, which
+provides `jj`. Prefer `jj` when it is available and the checkout has a Jujutsu workspace;
+use Git for Git-only checkouts and Git-specific tooling such as the installer-tag command
+and CI scripts.
+
+To use an existing Git checkout with both tools, run `jj git init --colocate` at its root.
+This creates local `.jj` metadata and keeps `.git` for Nix flake source discovery and existing
+Git tooling. Switch the home configuration to install the managed identity. When using only
+the devshell, configure your identity with `jj config set --user user.name '<name>'` and
+`jj config set --user user.email '<email>'` before creating commits.
+
+| Task | Command |
+|---|---|
+| Inspect the working copy and history | `jj status`, `jj diff`, `jj log` |
+| Describe the current change | `jj describe -m 'area/scope: Capitalized summary'` |
+| Start the next change | `jj new` |
+| Inspect a completed description | `jj log --no-graph -r <revision> -T description` |
+| Fetch remote history | `jj git fetch` |
+| Name a revision for publishing | `jj bookmark create <name> -r <revision>` |
+| Move an existing bookmark | `jj bookmark set <name> -r <revision>` |
+| Publish a bookmark | `jj git push --bookmark <name>` |
+
+`@` is the working-copy revision; after `jj new`, the completed change is normally `@-`.
+Working-copy edits are snapshotted automatically, without a staging step. Inspect existing
+changes before editing, keep unrelated work separate, and check the target revision before
+rewriting history or moving a bookmark. Follow the commit-message conventions in
+[`AGENTS.md`](../AGENTS.md#conventions).
+
+See the upstream [Jujutsu CLI reference](https://docs.jj-vcs.dev/latest/cli-reference/)
+for command options and [Git compatibility](https://docs.jj-vcs.dev/latest/git-compatibility/)
+for colocation details.
+
 ## Nix implementation
 
 Every context uses **Determinate Nix** as its `nix.package`, for its performance features

home-manager/modules/common.nix

@@ -67,6 +67,24 @@ in
         # never care about.
         home-manager.enable = true;
 
+        git = {
+          enable = true;
+          settings = {
+            user = {
+              email = "jackos1998@gmail.com";
+              name = "Jack O'Sullivan";
+            };
+            pull.rebase = true;
+          };
+          lfs.enable = true;
+        };
+        diff-so-fancy.enable = true;
+
+        jujutsu = {
+          enable = true;
+          settings.user = config.programs.git.settings.user;
+        };
+
         lsd = {
           enable = mkDefault true;
           enableFishIntegration = mkDefault true;

home-manager/modules/gui/default.nix

@@ -505,19 +505,6 @@ in
         };
 
         programs = {
-          git = {
-            enable = true;
-            settings = {
-              user = {
-                email = "jackos1998@gmail.com";
-                name = "Jack O'Sullivan";
-              };
-              pull.rebase = true;
-            };
-            lfs.enable = true;
-          };
-          diff-so-fancy.enable = true;
-
           waybar = import ./waybar.nix { inherit lib pkgs config font; };
           rofi = {
             enable = true;