fix: recover generated state during init indexing (#7)

## Summary

This prepares the `v2.1.1` patch release and fixes the setup/indexing
failure mode seen after upgrading when existing generated
`.gather-step/storage` state is stale or incompatible.

The release also improves operator-facing recovery text so the CLI gives
sentence-cased, actionable guidance instead of exiting with only a
storage-open context.

## Root Cause

`gather-step init --index` invoked the normal index path without
auto-recovery. If generated graph/search/metadata state from an older
version was stale or schema-incompatible, setup could fail before
parsing repos and only surface the surrounding storage-open context.

## Key Decisions

- Treat `init --index` as a setup/rebuild flow and enable
generated-state auto-recovery there.
- Keep plain `gather-step index` conservative; operators still opt into
rebuilds with `--auto-recover`.
- Point unsupported graph schema state to `gather-step index
--auto-recover`.
- Use proper sentence casing for stable operator errors.
- Document Homebrew upgrades as `brew update` followed by `brew upgrade
thedoublejay/tap/gather-step`.

## Files Changed

| File | Change |
| --- | --- |
| `crates/gather-step-cli/src/commands/init.rs` | Enables auto-recovery
for setup-triggered indexing. |
| `crates/gather-step-cli/src/commands/index.rs` | Clarifies recovery
progress output. |
| `crates/gather-step-cli/src/errors.rs` | Adds proper-cased, actionable
recovery messages for generated-state failures. |
| `crates/gather-step-cli/tests/*` | Adds and updates recovery/message
regression coverage. |
| `Cargo.toml`, crate manifests, `Cargo.lock`, `website/package.json` |
Bumps package metadata to `2.1.1`. |
| `website/src/content/docs/changelog.md` | Marks `v2.1.1` as released.
|
| `website/src/content/docs/guides/installation.md` | Clarifies Homebrew
upgrade commands. |

## Verification

- [x] `cargo fmt --check`
- [x] `cargo check -p gather-step --all-targets`
- [x] `cargo test -p gather-step --test cli_wizard_full -- --nocapture`
- [x] `cargo test -p gather-step --test cli_commands
corrupt_graph_index_reports_auto_recover_and_auto_recover_rebuilds --
--exact --nocapture`
- [x] `cargo test -p gather-step --test cli_commands
unsupported_metadata_schema_reports_stable_rebuild_message -- --exact
--nocapture`
- [x] `cargo test -p gather-step --test cli_commands
stable_error_when_config_yaml_is_malformed -- --exact --nocapture`
- [x] `cargo nextest run --all-features`
- [x] `cargo clippy -p gather-step --all-targets --all-features -- -D
warnings`
- [x] `cargo run -q -p gather-step -- --version` prints `gather-step
2.1.1`
- [x] `cd website && bun run build`

## Rollout

After merge, tag `v2.1.1` and run the release workflow.

## Follow-ups

- None for this PR.

Author: thedoublejay

Cargo.lock

@@ -13,7 +13,7 @@ members = [
 ]
 
 [workspace.package]
-version = "2.1.0"
+version = "2.1.1"
 authors = ["JJ Adonis"]
 edition = "2024"
 rust-version = "1.94.1"
@@ -23,11 +23,11 @@ homepage = "https://github.com/thedoublejay/gather-step"
 description = "High-performance multi-repo codebase intelligence engine"
 
 [workspace.dependencies]
-gather-step-analysis = { path = "crates/gather-step-analysis", version = "2.1.0" }
-gather-step-core = { path = "crates/gather-step-core", version = "2.1.0" }
-gather-step-mcp = { path = "crates/gather-step-mcp", version = "2.1.0" }
-gather-step-parser = { path = "crates/gather-step-parser", version = "2.1.0" }
-gather-step-storage = { path = "crates/gather-step-storage", version = "2.1.0" }
+gather-step-analysis = { path = "crates/gather-step-analysis", version = "2.1.1" }
+gather-step-core = { path = "crates/gather-step-core", version = "2.1.1" }
+gather-step-mcp = { path = "crates/gather-step-mcp", version = "2.1.1" }
+gather-step-parser = { path = "crates/gather-step-parser", version = "2.1.1" }
+gather-step-storage = { path = "crates/gather-step-storage", version = "2.1.1" }
 
 tree-sitter = "=0.26.8"
 tree-sitter-typescript = "0.23.2"

Cargo.toml

@@ -30,7 +30,7 @@ harness = false
 
 [dependencies]
 gather-step-core.workspace = true
-gather-step = { path = "../gather-step-cli", version = "2.1.0" }
+gather-step = { path = "../gather-step-cli", version = "2.1.1" }
 gather-step-mcp.workspace = true
 gather-step-storage.workspace = true
 anyhow.workspace = true

crates/gather-step-bench/Cargo.toml

@@ -23,11 +23,11 @@ clap.workspace = true
 comfy-table.workspace = true
 console.workspace = true
 crossbeam-channel.workspace = true
-gather-step-analysis = { path = "../gather-step-analysis", version = "2.1.0" }
+gather-step-analysis = { path = "../gather-step-analysis", version = "2.1.1" }
 gather-step-core.workspace = true
-gather-step-git = { path = "../gather-step-git", version = "2.1.0" }
-gather-step-mcp = { path = "../gather-step-mcp", version = "2.1.0" }
-gather-step-output = { path = "../gather-step-output", version = "2.1.0" }
+gather-step-git = { path = "../gather-step-git", version = "2.1.1" }
+gather-step-mcp = { path = "../gather-step-mcp", version = "2.1.1" }
+gather-step-output = { path = "../gather-step-output", version = "2.1.1" }
 gather-step-parser.workspace = true
 gather-step-storage.workspace = true
 indicatif.workspace = true

crates/gather-step-cli/Cargo.toml

@@ -189,7 +189,7 @@ fn reset_and_reopen_indexer(
         )
     })?;
     output.line(format!(
-        "  {} Auto-recovered generated index state; rebuilding from source repos.",
+        "  {} Rebuilding generated index state from source repos.",
         style("→").cyan()
     ));
     RepoIndexer::open(storage_root, IndexingOptions::default())

crates/gather-step-cli/src/commands/index.rs

@@ -95,7 +95,7 @@ async fn run_non_interactive(app: &AppContext, args: InitArgs) -> Result<()> {
     let output = app.output();
 
     if args.index && !args.no_index {
-        index::run(app, index::IndexArgs::default()).await?;
+        index::run(app, init_index_args()).await?;
     }
     if args.generate_ai_files && !args.no_generate_ai_files {
         generate::run_summary_pair(app)?;
@@ -167,7 +167,7 @@ async fn run_wizard(app: &AppContext, args: InitArgs) -> Result<()> {
     write_default_config_with_repos(app, &args, repos)?;
 
     if do_index {
-        index::run(app, index::IndexArgs::default()).await?;
+        index::run(app, init_index_args()).await?;
     }
     if do_ai {
         generate::run_summary_pair(app)?;
@@ -186,6 +186,13 @@ async fn run_wizard(app: &AppContext, args: InitArgs) -> Result<()> {
     Ok(())
 }
 
+fn init_index_args() -> index::IndexArgs {
+    index::IndexArgs {
+        auto_recover: true,
+        ..index::IndexArgs::default()
+    }
+}
+
 fn write_default_config(app: &AppContext, args: &InitArgs) -> Result<()> {
     let repos = discover_git_repos(&app.workspace_path)?;
     write_default_config_with_repos(app, args, repos)

crates/gather-step-cli/src/commands/init.rs

@@ -4,7 +4,7 @@ use anyhow::Error;
 use gather_step_core::ConfigError;
 use gather_step_storage::{GraphStoreError, MetadataStoreError, SearchStoreError};
 
-const UNSUPPORTED_SCHEMA_MESSAGE: &str = "your local index uses an unsupported schema; run `gather-step clean && gather-step index` to rebuild";
+const UNSUPPORTED_SCHEMA_MESSAGE: &str = "Generated index state uses an unsupported schema. Run `gather-step index --auto-recover` to rebuild from source repos.";
 
 #[must_use]
 pub fn format_operator_error(error: &Error) -> String {
@@ -27,36 +27,39 @@ pub fn format_operator_error(error: &Error) -> String {
             match graph_error {
                 GraphStoreError::StorageHeld { .. }
                 | GraphStoreError::StorageHeldByDaemon { .. } => {
-                    return "another gather-step process is using this workspace; stop `gather-step watch` or `gather-step serve --watch`, then retry".to_owned();
+                    return "Another gather-step process is using this workspace. Stop `gather-step watch` or `gather-step serve --watch`, then retry.".to_owned();
                 }
                 GraphStoreError::Corrupt { .. } => {
-                    return "your index is corrupt or incomplete; run `gather-step index --auto-recover` to rebuild generated state, or run `gather-step clean && gather-step index`".to_owned();
+                    return "Your index is corrupt or incomplete. Run `gather-step index --auto-recover` to rebuild generated state, or run `gather-step clean && gather-step index`.".to_owned();
+                }
+                GraphStoreError::SchemaVersionMismatch { .. } => {
+                    return UNSUPPORTED_SCHEMA_MESSAGE.to_owned();
                 }
                 _ => {}
             }
         }
     }
 
     if contains_ascii_case_insensitive(&full, "workspace is not a git repository") {
-        return "workspace is not a git repository. Next step: run from a git checkout or omit `--release-gate` for an unsealed run".to_owned();
+        return "Workspace is not a git repository. Next step: run from a git checkout or omit `--release-gate` for an unsealed run.".to_owned();
     }
     if contains_ascii_case_insensitive(&full, ".gather-step")
         && contains_ascii_case_insensitive(&full, "permission denied")
     {
-        return "cannot write `.gather-step` generated state. Next step: fix permissions on `.gather-step` or pass writable `--storage`/`--registry` paths".to_owned();
+        return "Cannot write `.gather-step` generated state. Next step: fix permissions on `.gather-step` or pass writable `--storage`/`--registry` paths.".to_owned();
     }
     if contains_ascii_case_insensitive(&full, "database already open")
         || contains_ascii_case_insensitive(&full, "already locked by another gather-step process")
         || contains_ascii_case_insensitive(&full, "locked by gather-step pid")
     {
-        return "another gather-step process is using this workspace; stop `gather-step watch` or `gather-step serve --watch`, then retry".to_owned();
+        return "Another gather-step process is using this workspace. Stop `gather-step watch` or `gather-step serve --watch`, then retry.".to_owned();
     }
     if contains_ascii_case_insensitive(&full, "db corrupted")
         || contains_ascii_case_insensitive(&full, "corrupt")
         || contains_ascii_case_insensitive(&full, "repair aborted")
         || contains_ascii_case_insensitive(&full, "manual upgrade required")
     {
-        return "your index is corrupt or incomplete; run `gather-step index --auto-recover` to rebuild generated state, or run `gather-step clean && gather-step index`".to_owned();
+        return "Your index is corrupt or incomplete. Run `gather-step index --auto-recover` to rebuild generated state, or run `gather-step clean && gather-step index`.".to_owned();
     }
 
     one_line(error.to_string())
@@ -66,27 +69,29 @@ fn format_config_error(error: &ConfigError) -> String {
     match error {
         ConfigError::Read { path, source } if source.kind() == ErrorKind::NotFound => {
             format!(
-                "config not found: {path}. Next step: run `gather-step init` or pass `--config <path>`"
+                "Config not found: {path}. Next step: run `gather-step init` or pass `--config <path>`."
             )
         }
         ConfigError::Read { path, source } if source.kind() == ErrorKind::PermissionDenied => {
             format!(
-                "cannot read config: {path}. Next step: fix file permissions or pass `--config <path>`"
+                "Cannot read config: {path}. Next step: fix file permissions or pass `--config <path>`."
             )
         }
         ConfigError::Read { path, .. } => {
-            format!("cannot read config: {path}. Next step: fix the path or pass `--config <path>`")
+            format!(
+                "Cannot read config: {path}. Next step: fix the path or pass `--config <path>`."
+            )
         }
         ConfigError::Parse { path, .. } => {
-            format!("config YAML is malformed: {path}. Next step: fix the YAML syntax and rerun")
+            format!("Config YAML is malformed: {path}. Next step: fix the YAML syntax and rerun.")
         }
         ConfigError::Validation { reason, .. } if reason.contains("path does not exist") => {
             format!(
-                "configured repo path does not exist: {reason}. Next step: create the repo directory or fix the repo path in the config"
+                "Configured repo path does not exist: {reason}. Next step: create the repo directory or fix the repo path in the config."
             )
         }
         ConfigError::Validation { reason, .. } => {
-            format!("config is invalid: {reason}. Next step: fix the config and rerun")
+            format!("Config is invalid: {reason}. Next step: fix the config and rerun.")
         }
     }
 }
@@ -118,3 +123,24 @@ fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
         .windows(needle.len())
         .any(|window| window.eq_ignore_ascii_case(needle.as_bytes()))
 }
+
+#[cfg(test)]
+mod tests {
+    use gather_step_storage::GraphStoreError;
+
+    use super::format_operator_error;
+
+    #[test]
+    fn graph_schema_mismatch_reports_auto_recover() {
+        let error = anyhow::Error::new(GraphStoreError::SchemaVersionMismatch {
+            stored: 0,
+            expected: 1,
+        })
+        .context("opening storage at /tmp/workspace/.gather-step/storage");
+
+        let message = format_operator_error(&error);
+
+        assert!(message.contains("unsupported schema"));
+        assert!(message.contains("gather-step index --auto-recover"));
+    }
+}

crates/gather-step-cli/src/errors.rs

@@ -486,7 +486,7 @@ fn stable_error_when_config_is_missing() {
 
     let output = run_fail(temp.path(), &["index", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("config not found:"));
+    assert!(stderr.contains("Config not found:"));
     assert!(stderr.contains("Next step: run `gather-step init`"));
 }
 
@@ -497,7 +497,7 @@ fn stable_error_when_config_yaml_is_malformed() {
 
     let output = run_fail(temp.path(), &["index", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("config YAML is malformed:"));
+    assert!(stderr.contains("Config YAML is malformed:"));
     assert!(stderr.contains("Next step: fix the YAML syntax and rerun"));
 }
 
@@ -516,7 +516,7 @@ repos:
 
     let output = run_fail(temp.path(), &["index", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("configured repo path does not exist:"));
+    assert!(stderr.contains("Configured repo path does not exist:"));
     assert!(stderr.contains("repo `backend_standard` path does not exist"));
 }
 
@@ -526,7 +526,7 @@ fn release_gate_rejects_non_git_workspace_with_stable_error() {
 
     let output = run_fail(temp.path(), &["index", "--release-gate", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("workspace is not a git repository"));
+    assert!(stderr.contains("Workspace is not a git repository"));
     assert!(stderr.contains("omit `--release-gate`"));
 }
 
@@ -542,7 +542,7 @@ fn corrupt_graph_index_reports_auto_recover_and_auto_recover_rebuilds() {
 
     let output = run_fail(temp.path(), &["index", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("index is corrupt or incomplete"));
+    assert!(stderr.contains("Your index is corrupt or incomplete"));
     assert!(stderr.contains("gather-step index --auto-recover"));
 
     let recovered = run_ok(temp.path(), &["index", "--auto-recover", "--json"]);
@@ -566,7 +566,7 @@ fn unsupported_metadata_schema_reports_stable_rebuild_message() {
     let output = run_fail(temp.path(), &["index", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
     assert!(stderr.contains("unsupported schema"));
-    assert!(stderr.contains("gather-step clean && gather-step index"));
+    assert!(stderr.contains("gather-step index --auto-recover"));
 
     let recovered = run_ok(temp.path(), &["index", "--auto-recover", "--json"]);
     let recovered_json = stdout_json(&recovered);
@@ -584,8 +584,8 @@ fn concurrent_graph_open_reports_stable_process_error() {
         .expect("graph should open and hold the redb lock");
     let output = run_fail(temp.path(), &["status", "--json"]);
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("another gather-step process is using this workspace"));
-    assert!(stderr.contains("stop `gather-step watch`"));
+    assert!(stderr.contains("Another gather-step process is using this workspace"));
+    assert!(stderr.contains("Stop `gather-step watch`"));
 }
 
 #[test]
@@ -605,7 +605,7 @@ fn generated_state_permission_denied_reports_stable_error() {
     let output = run_fail(temp.path(), &["index", "--json"]);
     let _ = fs::set_permissions(&generated_root, fs::Permissions::from_mode(0o700));
     let stderr = String::from_utf8_lossy(&output.stderr);
-    assert!(stderr.contains("cannot write `.gather-step` generated state"));
+    assert!(stderr.contains("Cannot write `.gather-step` generated state"));
     assert!(stderr.contains("fix permissions on `.gather-step`"));
 }