Enable graph engineering by default in installers; feature it in the README

README leads with the claim under the title — the world's first CLI with
built-in graph engineering — plus a dedicated section covering the /graph
command set, the closed loop it runs (plan → parallel worktree workers →
adversarial verify → 3-way merge-back → replan → optimize → terminal
whole-objective verification), the repo-following .kigi/graph.jsonl state,
copy-paste disable commands for macOS/Linux and Windows, and the tuning
knobs.

install.sh: the rc-file resolution and persist_line helper are hoisted out
of the not-on-PATH branch and generalized (guard + label), so PATH
persistence is unchanged while KIGI_GRAPH=1 is persisted unconditionally
and idempotently for zsh/bash/fish/POSIX profiles — an existing
KIGI_GRAPH line (e.g. a user's =0 opt-out) is left untouched on
reinstall. install.ps1 mirrors it with a User-scope environment variable,
also only when unset. No binary change — installers and README ship from
main, so this needs no rebuild or release.

README.md

@@ -2,6 +2,12 @@
 
 <h1>Kigi (<code>kigi</code>) 🌘</h1>
 
+<h3>🕸️ The world's first CLI with built-in <em>Graph Engineering</em></h3>
+
+<p><code>/graph</code> turns one objective into a dependency graph of
+autonomous, self-verifying agent loops — planned, parallelized,
+adversarially verified, and merged back, end to end.</p>
+
 **Kigi** is an unofficial Kimi Code CLI community build — a terminal-based
 AI coding agent re-targeted at the Kimi Code subscription API and the
 Moonshot open platform, built on the Apache-2.0 sources of
@@ -13,6 +19,7 @@ interactively, headlessly for scripting/CI, or embedded in editors via the
 Agent Client Protocol (ACP).
 
 [Installation](#installation) ·
+[Graph engineering](#graph-engineering) ·
 [Providers and API keys](#providers-and-api-keys) ·
 [Building from source](#building-from-source) ·
 [Coexistence with the official CLI](#coexistence-with-the-official-kimi-cli) ·
@@ -50,10 +57,54 @@ kigi             # start the TUI
 
 The installer verifies every download against the release's `SHA256SUMS`,
 installs into `~/.kigi/bin/kigi` (`%USERPROFILE%\.kigi\bin\kigi.exe` on
-Windows), and prints the PATH line to add. Later releases arrive through the
+Windows), persists the PATH line for you, and **enables graph engineering
+by default** (`KIGI_GRAPH=1`; see [Graph engineering](#graph-engineering)
+to disable). Later releases arrive through the
 built-in self-updater (`kigi update`, gated by `KIGI_AUTO_UPDATE`), which
 pulls from the same GitHub Releases feed.
 
+## Graph engineering
+
+Kigi is the first CLI to ship *graph engineering* as a first-class command:
+where a loop drives one agent, a graph is the programmable organization
+connecting many.
+
+```
+/graph <objective> [--budget <tokens>]   # decompose + run fully autonomously
+/graph status                            # node tree, budget, current work
+/graph show                              # box-drawing DAG view
+/graph pause | resume [--budget <n>]     # halt / continue (budget top-up)
+/graph clear                             # abandon the graph
+```
+
+One `/graph <objective>` runs the whole closed loop: a planner subagent
+decomposes the objective into a validated dependency DAG; independent
+nodes fan out as parallel workers in isolated git worktrees, each gated
+by an adversarial verifier and merged back three-way; out-of-scope
+discoveries (`DISCOVERED:`) replan the graph append-only; a topology
+optimizer prunes false dependencies at plan boundaries; and a terminal
+verification node re-checks the *whole* objective before the graph
+completes. State follows your repo in `.kigi/graph.jsonl`, so a fresh
+session — or a teammate — can `/graph resume` where you left off.
+
+The installer enables it by default. To disable:
+
+```sh
+# macOS / Linux
+echo 'export KIGI_GRAPH=0' >> ~/.zshrc   # or ~/.bashrc / ~/.bash_profile
+```
+
+```powershell
+# Windows PowerShell
+[Environment]::SetEnvironmentVariable('KIGI_GRAPH','0','User')
+```
+
+(One-off instead: `KIGI_GRAPH=0 kigi`.) Tuning knobs:
+`KIGI_GRAPH_CONCURRENCY` (parallel nodes, default 3),
+`KIGI_GRAPH_NODE_ROUNDS` (worker↔verifier rounds per node, default 3),
+`KIGI_GRAPH_REPLAN_CAP` (replan passes, default 3),
+`KIGI_GRAPH_OPTIMIZER=0` (disable the optimizer pass).
+
 ## Providers and API keys
 
 Kigi talks to a fixed three-platform registry:

install.ps1

@@ -148,6 +148,16 @@ try {
     } else {
         Write-Host "Run 'kigi' to get started."
     }
+
+    # Graph engineering ships enabled by default. Respect an explicit
+    # user choice: only set the variable when it is not already defined
+    # (so a persisted opt-out of "0" survives reinstalls).
+    $Graph = [Environment]::GetEnvironmentVariable("KIGI_GRAPH", "User")
+    if ($null -eq $Graph -or $Graph -eq "") {
+        [Environment]::SetEnvironmentVariable("KIGI_GRAPH", "1", "User")
+        Write-Host "Enabled graph engineering (KIGI_GRAPH=1)."
+        Write-Host "Disable: [Environment]::SetEnvironmentVariable('KIGI_GRAPH','0','User')"
+    }
 } finally {
     Remove-Item -Path $TmpDir -Recurse -Force -ErrorAction SilentlyContinue
 }

install.sh

@@ -186,50 +186,69 @@ mv -f "$TMP_LINK" "$BIN_DIR/kigi"
 
 printf '\nkigi v%s installed to %s\n' "$RESOLVED_VERSION" "$BIN_DIR/kigi"
 
+# Persist a line into an rc file. Idempotent via the grep guard; on write
+# failure the manual command is printed and the script fails loudly (the
+# binary itself is already installed).
+persist_line() {
+    rc="$1"
+    line="$2"
+    guard="$3"
+    what="$4"
+    if [ -f "$rc" ] && grep -qF "$guard" "$rc"; then
+        printf '\n%s is already configured in %s.\n' "$what" "$rc"
+        return 0
+    fi
+    printf '\n# Added by the kigi installer\n%s\n' "$line" >> "$rc" \
+        || err "could not write $rc — configure it manually: $line"
+    printf '\nAdded %s in %s.\n' "$what" "$rc"
+}
+
+# Resolve the login shell's rc file and env-line syntax once; PATH and
+# feature-flag persistence below both write to the same place.
+case "${SHELL:-}" in
+    */zsh)
+        RC_FILE="${ZDOTDIR:-$HOME}/.zshrc"
+        PATH_LINE="export PATH=\"$BIN_DIR:\$PATH\""
+        GRAPH_LINE="export KIGI_GRAPH=1"
+        ;;
+    */bash)
+        # macOS login shells read ~/.bash_profile; Linux reads ~/.bashrc.
+        if [ "$PLATFORM_OS" = "macos" ]; then
+            RC_FILE="$HOME/.bash_profile"
+        else
+            RC_FILE="$HOME/.bashrc"
+        fi
+        PATH_LINE="export PATH=\"$BIN_DIR:\$PATH\""
+        GRAPH_LINE="export KIGI_GRAPH=1"
+        ;;
+    */fish)
+        # fish_add_path in config.fish is fish's own idempotent way
+        # to persist a PATH entry.
+        FISH_CONF_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/fish"
+        mkdir -p "$FISH_CONF_DIR"
+        RC_FILE="$FISH_CONF_DIR/config.fish"
+        PATH_LINE="fish_add_path $BIN_DIR"
+        GRAPH_LINE="set -gx KIGI_GRAPH 1"
+        ;;
+    *)
+        RC_FILE="$HOME/.profile"
+        PATH_LINE="export PATH=\"$BIN_DIR:\$PATH\""
+        GRAPH_LINE="export KIGI_GRAPH=1"
+        ;;
+esac
+
 case ":$PATH:" in
     *":$BIN_DIR:"*)
         printf 'Run `kigi` to get started.\n'
         ;;
     *)
-        # Persist BIN_DIR on PATH in the login shell's rc file, so the user
+        persist_line "$RC_FILE" "$PATH_LINE" "$BIN_DIR" "$BIN_DIR (PATH)"
-        # doesn't have to. Idempotent: skipped when the rc already mentions
-        # the bin dir. On write failure the manual command is printed and the
-        # script fails loudly (the binary itself is already installed).
-        persist_line() {
-            rc="$1"
-            line="$2"
-            if [ -f "$rc" ] && grep -qF "$BIN_DIR" "$rc"; then
-                printf '\n%s is already configured in %s.\n' "$BIN_DIR" "$rc"
-                return 0
-            fi
-            printf '\n# Added by the kigi installer\n%s\n' "$line" >> "$rc" \
-                || err "could not write $rc — add kigi to your PATH manually: $line"
-            printf '\nAdded %s to your PATH in %s.\n' "$BIN_DIR" "$rc"
-        }
-        EXPORT_LINE="export PATH=\"$BIN_DIR:\$PATH\""
-        case "${SHELL:-}" in
-            */zsh)
-                persist_line "${ZDOTDIR:-$HOME}/.zshrc" "$EXPORT_LINE"
-                ;;
-            */bash)
-                # macOS login shells read ~/.bash_profile; Linux reads ~/.bashrc.
-                if [ "$PLATFORM_OS" = "macos" ]; then
-                    persist_line "$HOME/.bash_profile" "$EXPORT_LINE"
-                else
-                    persist_line "$HOME/.bashrc" "$EXPORT_LINE"
-                fi
-                ;;
-            */fish)
-                # fish_add_path in config.fish is fish's own idempotent way
-                # to persist a PATH entry.
-                FISH_CONF_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/fish"
-                mkdir -p "$FISH_CONF_DIR"
-                persist_line "$FISH_CONF_DIR/config.fish" "fish_add_path $BIN_DIR"
-                ;;
-            *)
-                persist_line "$HOME/.profile" "$EXPORT_LINE"
-                ;;
-        esac
         printf 'Open a new terminal, then run `kigi` to get started.\n'
         ;;
 esac
+
+# Graph engineering ships enabled by default. The KIGI_GRAPH guard makes
+# this idempotent AND respects an explicit user opt-out (an existing
+# `export KIGI_GRAPH=0` line is left untouched). Disable any time with:
+#   echo 'export KIGI_GRAPH=0' >> <your shell rc>
+persist_line "$RC_FILE" "$GRAPH_LINE" "KIGI_GRAPH" "graph engineering (KIGI_GRAPH=1)"