fix: improve v2.4 setup and indexing flow (#11)

## Summary

- Reworked `gather-step init` so existing `gather-step.config.yaml`
files are respected, selected repos stay selected, and setup uses one
numbered checkbox-style repo picker.
- Added `gather-step watch N`, clearer indexing progress/logging, final
elapsed time plus index-size output, and a loader while AI Markdown
files are generated.
- Reduced noisy parser warnings for static JSON/YAML mapping files and
ambiguous sibling Python packages.
- Updated v2.4 version metadata, changelog, landing-page copy, setup
docs, CLI docs, and the CLI reference layout. Release-note drafts are
ignored.

## Context / Motivation

The setup flow was too easy to mistrust: rerunning `init` could fail on
an existing config or reintroduce repos the user had already removed,
indexing repeated repo discovery output, `watch N` was parsed as ignored
intent, and progress/log messages read like internal implementation
notes. The docs CLI reference page also had a sidebar/content overlap on
desktop.

## Key Decisions

- Treat existing config YAML as authoritative. Interactive init uses it
as the default repo selection and preserves selected repo metadata such
as custom `name`, `depth`, provider settings, and indexing rules.
- Keep the repo picker terminal-native instead of adding a TUI
dependency, so setup remains portable and script-friendly.
- Leave ambiguous sibling Python package imports unresolved instead of
choosing the first match, because an omitted edge is safer than a wrong
edge for planning context.
- Use `--force` as the explicit path for regenerating a fresh discovered
config.

## Files Changed

| Area | Files | Change |
| --- | --- | --- |
| Init/watch/generate CLI |
`crates/gather-step-cli/src/commands/init.rs`, `watch.rs`,
`generate.rs`, `mod.rs`, `tests/cli_init.rs` | Existing-config reuse,
repo picker, `watch N`, AI Markdown loader, review fixes, copy polish,
and regression coverage. |
| Indexing UX/logging | `crates/gather-step-cli/src/commands/index.rs` |
Shorter progress bar, current path display, start/finish logs, polished
finalization copy, elapsed time, and index size. |
| Parser warnings | `crates/gather-step-parser/src/tree_sitter.rs` |
Skip SWC for static mapping files and avoid warning/noisy first-match
Python package resolution. |
| Release metadata | `Cargo.toml`, crate manifests, `Cargo.lock`,
`website/package.json` | Bumped v2.4 metadata. |
| Docs/site | `website/src/**`, `.gitignore` | v2.4 changelog, landing
copy, setup/CLI docs, CLI reference layout constraints, and ignored
local release-note drafts. |

## Cross-Repo / Rollout Impact

None. This is local CLI/docs behavior in `thedoublejay/gather-step`.

Existing workspaces can keep their config. After upgrading, users should
rebuild generated state before relying on v2.4 output:

```bash
gather-step --workspace /path/to/workspace reindex
gather-step --workspace /path/to/workspace generate claude-md
gather-step --workspace /path/to/workspace generate agents-md
```

## Verification

- [x] `cargo fmt --all -- --check`
- [x] `cargo clippy -p gather-step -p gather-step-parser --all-targets
-- -D warnings`
- [x] `cargo test -p gather-step --lib`
- [x] `cargo test -p gather-step --test cli_init`
- [x] `cargo test -p gather-step
repo_config_merge_filters_allow_list_to_selected_repos --lib`
- [x] `cargo test -p gather-step
repo_config_name_match_keeps_discovered_path --lib`
- [x] `cargo test -p gather-step-parser --lib`
- [x] `cd website && bun run build`
- [x] `git diff --check`
- [x] Previewed `/reference/cli/` locally and captured a Playwright
screenshot at `1280x900` to confirm content no longer overlaps the
sidebar.

## Follow-ups

- Consider a separate generated-rules improvement pass using the
Braingent v3 cleanup plan: freshness metadata, context budgets, and
explicit retrieval/capture workflow pointers.

Author: thedoublejay

.gitignore

@@ -28,6 +28,9 @@ dist/
 # Local-only planning docs (superpowers plans, drafts, scratch)
 docs/superpowers/
 
+# Local release-note drafts
+release-notes/
+
 # Local-only Python private corpus benchmark inputs/results
 benchmark/python/private-corpus.local.yaml
 benchmark/python/private-results/

Cargo.lock

@@ -13,7 +13,7 @@ members = [
 ]
 
 [workspace.package]
-version = "2.3.0"
+version = "2.4.0"
 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.3.0" }
-gather-step-core = { path = "crates/gather-step-core", version = "2.3.0" }
-gather-step-mcp = { path = "crates/gather-step-mcp", version = "2.3.0" }
-gather-step-parser = { path = "crates/gather-step-parser", version = "2.3.0" }
-gather-step-storage = { path = "crates/gather-step-storage", version = "2.3.0" }
+gather-step-analysis = { path = "crates/gather-step-analysis", version = "2.4.0" }
+gather-step-core = { path = "crates/gather-step-core", version = "2.4.0" }
+gather-step-mcp = { path = "crates/gather-step-mcp", version = "2.4.0" }
+gather-step-parser = { path = "crates/gather-step-parser", version = "2.4.0" }
+gather-step-storage = { path = "crates/gather-step-storage", version = "2.4.0" }
 
 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.3.0" }
+gather-step = { path = "../gather-step-cli", version = "2.4.0" }
 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.3.0" }
+gather-step-analysis = { path = "../gather-step-analysis", version = "2.4.0" }
 gather-step-core.workspace = true
-gather-step-git = { path = "../gather-step-git", version = "2.3.0" }
-gather-step-mcp = { path = "../gather-step-mcp", version = "2.3.0" }
-gather-step-output = { path = "../gather-step-output", version = "2.3.0" }
+gather-step-git = { path = "../gather-step-git", version = "2.4.0" }
+gather-step-mcp = { path = "../gather-step-mcp", version = "2.4.0" }
+gather-step-output = { path = "../gather-step-output", version = "2.4.0" }
 gather-step-parser.workspace = true
 gather-step-storage.workspace = true
 indicatif.workspace = true

crates/gather-step-cli/Cargo.toml

@@ -12,6 +12,7 @@ use gather_step_output::{
     render_workspace_summary_claude,
 };
 use gather_step_storage::{GraphStoreDb, MetadataStore, MetadataStoreDb};
+use indicatif::{ProgressBar, ProgressStyle};
 use serde::Serialize;
 
 use crate::app::AppContext;
@@ -185,6 +186,7 @@ pub fn run_summary_pair(app: &AppContext) -> Result<()> {
     let output = app.output();
     let paths = app.workspace_paths();
     let metadata_path = paths.storage_root.join("metadata.sqlite");
+    let generation_bar = ai_generation_bar(app);
 
     if paths.graph_path.exists() && metadata_path.exists() {
         run_claude_md_rules(
@@ -196,11 +198,16 @@ pub fn run_summary_pair(app: &AppContext) -> Result<()> {
             },
         )?;
     } else {
-        output.line("warning: skipped .claude/rules/ generation because no workspace index exists");
+        output
+            .line("Warning: Skipped generating .claude/rules/ because no workspace index exists.");
         output.line(
-            "hint: run `gather-step index`, then `gather-step generate claude-md --target rules`",
+            "Hint: Run `gather-step index`, then `gather-step generate claude-md --target rules`.",
         );
     }
+    if let Some(bar) = &generation_bar {
+        bar.inc(1);
+        bar.set_message("Generating CLAUDE.gather.md...");
+    }
 
     run_claude_md_summary(
         app,
@@ -210,7 +217,33 @@ pub fn run_summary_pair(app: &AppContext) -> Result<()> {
             target: ClaudeMdTarget::Summary,
         },
     )?;
-    run_agents_md(app, GenerateAgentsMdArgs { output: None })
+    if let Some(bar) = &generation_bar {
+        bar.inc(1);
+        bar.set_message("Generating AGENTS.gather.md...");
+    }
+    run_agents_md(app, GenerateAgentsMdArgs { output: None })?;
+    if let Some(bar) = generation_bar {
+        bar.inc(1);
+        bar.finish_and_clear();
+    }
+    Ok(())
+}
+
+fn ai_generation_bar(app: &AppContext) -> Option<ProgressBar> {
+    app.progress_is_visible().then(|| {
+        let bar = app.multi_progress.add(ProgressBar::new(3));
+        bar.set_style(
+            ProgressStyle::with_template(
+                " {spinner:.cyan.bold} [{elapsed_precise}] [{bar:40.cyan/blue}] {pos}/{len}  {msg}",
+            )
+            .expect("AI context progress template is valid")
+            .progress_chars("█░░")
+            .tick_chars("⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ "),
+        );
+        bar.set_message("Generating AI context files...");
+        bar.enable_steady_tick(std::time::Duration::from_millis(80));
+        bar
+    })
 }
 
 fn run_codeowners(app: &AppContext, args: GenerateCodeownersArgs) -> Result<()> {