feat(cli): improve first-run activation

Author: LyleMi

README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Reforge</h1>
 
 <p align="center">
-  Evidence-backed structural analysis for codebases changing faster than they can be reviewed.
+  Find structural drift before it becomes the next refactor.
 </p>
 
 <p align="center">
@@ -15,156 +15,129 @@
   <a href="https://lylemi.github.io/Reforge/"><img alt="Documentation" src="https://img.shields.io/badge/docs-read-1556ad"></a>
 </p>
 
-Reforge is a local CLI that shows maintainers where a codebase is becoming
-harder to change. It finds duplicated implementations, oversized
-responsibilities, dependency tangles, and architecture drift across the whole
-repository—including patterns introduced gradually by coding agents.
+Reforge is a local CLI for repository-level code review. It finds duplicated
+implementations, oversized responsibilities, dependency tangles, and
+architecture drift—including patterns introduced gradually by coding agents.
 
-It does not assign an opaque health score or ask you to trust a generated
-summary. Every finding includes the source locations, measurements, and rule
-that produced it. Every report also records what Reforge could and could not
-analyze.
+Every finding identifies its rule and relevant source locations, with
+measurements or a value-flow witness when the rule produces them. Coverage
+records what Reforge could and could not analyze. Reforge does not upload source
+code, assign a health score, or claim that a finding is a bug.
 
 <p align="center">
-  <a href="https://lylemi.github.io/Reforge/playground/"><strong>See the agent-code Playground →</strong></a>
+  <a href="https://lylemi.github.io/Reforge/playground/"><strong>Try the agent-code Playground →</strong></a>
   &nbsp;·&nbsp;
-  <a href="https://lylemi.github.io/Reforge/sample/"><strong>Explore Reforge's self-analysis report →</strong></a>
+  <a href="https://lylemi.github.io/Reforge/sample/"><strong>Open an example report →</strong></a>
 </p>
 
-## See the evidence behind a finding
-
-This finding came from Reforge analyzing its own report application:
-
-```text
-Function readability: ReportView in web/report-app/src/reportApp.tsx
-
-  Rule:        reforge.codebase.complex_function
-  Location:    web/report-app/src/reportApp.tsx:33
-  Measurement: estimated complexity 15 (threshold 14)
-  Guidance:    Reduce the function to a clear sequence of named responsibilities.
-```
-
-The location makes the finding inspectable. The measurement explains why it
-was reported. The threshold can be tuned, and a legitimate exception can be
-suppressed with its reason preserved. Reforge makes the case for review; it
-does not pretend that a measurement can decide the refactor for you.
-
-## Get started
+## Quick start
 
 Install the latest release on Linux or macOS:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/LyleMi/Reforge/main/scripts/install.sh | sh
 ```
 
-On Windows PowerShell:
-
-```powershell
-$installer = Join-Path $env:TEMP "install-reforge.ps1"
-irm https://raw.githubusercontent.com/LyleMi/Reforge/main/scripts/install.ps1 -OutFile $installer
-& $installer
-```
-
-Rust users can alternatively build and install the command from crates.io:
+Or install only the CLI from crates.io:
 
 ```sh
 cargo install reforge-cli --locked
 ```
 
-The crates.io package installs the `reforge` binary only. Use the verified
-release installer above when you also want the bundled `reforge-analyze` Codex
-skill.
-
-Reforge runs Codebase analysis by default. Its rules begin as opt-in previews,
-so adopting Reforge does not immediately impose someone else's definition of
-maintainability. Initialize a configuration, then enable a small starter set:
+Then analyze a repository:
 
 ```sh
-reforge init
-```
-
-In the generated `reforge.toml`, start with:
-
-```toml
-[rules]
-enable = [
-  "reforge.codebase.large_file",
-  "reforge.codebase.long_function",
-  "reforge.codebase.dependency_cycle",
-  "reforge.codebase.similar_functions",
-]
+reforge analyze .
 ```
 
-Run the review in your repository or generate a standalone HTML report:
+With no configuration, the CLI runs Codebase analysis with four preview
+advisories: large files, long functions, dependency cycles, and similar
+functions. They are review prompts, not CI failures. Create a versioned starter
+configuration to tune or disable them:
 
 ```sh
-reforge analyze .
+reforge init
 reforge analyze . --output html --output-file reforge-report.html
 ```
 
-## Built for repository-level review
+Windows PowerShell and pinned-version installation are covered in the
+[installation guide](https://lylemi.github.io/Reforge/user-guide.html#install).
 
-| Need | What Reforge provides |
-| --- | --- |
-| Find change pressure beyond style errors | Project-wide signals for responsibilities, duplication, dependencies, and drift |
-| Verify why something was flagged | Source locations, measurements, thresholds, and rule provenance |
-| Trust an empty report appropriately | Coverage receipts and explicit analysis limitations |
-| Keep an accepted refactor from regressing | Reproducible baselines and CI gates for new or changed findings |
-| Keep source code private | Local analysis with no uploads or telemetry |
-
-Reforge complements compilers, linters, and security scanners. Its job is not
-to prove correctness or find vulnerabilities; it identifies structural
-pressure that deserves a maintainer's judgment before the next refactor.
-
-## What Codebase finds
+## What it finds
 
 | Area | Examples |
 | --- | --- |
-| **Responsibilities** | Large files, long or complex functions, deep nesting, broad public surfaces |
-| **Duplication** | Similar functions, repeated literals, repeated test setup, overlapping type shapes |
-| **Architecture drift** | Dependency cycles, generic buckets, parallel implementations, boundary bypasses |
-| **Repository consistency** | Naming drift, stale compatibility paths, TODO/FIXME clusters |
+| Responsibilities | Large files, long or complex functions, deep nesting, broad public surfaces |
+| Duplication | Similar functions, repeated literals, repeated test setup, overlapping type shapes |
+| Architecture drift | Dependency cycles, generic buckets, parallel implementations, boundary bypasses |
+| Repository consistency | Naming drift, stale compatibility paths, TODO/FIXME clusters |
+
+Codebase analysis supports Rust, JavaScript, TypeScript/TSX, Vue, Python, Go,
+Java, C#, Kotlin, PHP, Ruby, Bash, and PowerShell. Dependency rules also
+recognize C and C++.
 
-Each finding points to a concrete subject and includes the rule, source locations, and measurements that produced it. Coverage shows which languages and capabilities were actually observed. Reforge does not turn these signals into a health score, severity, or defect prediction—the decision stays with the reviewer.
+## What a finding contains
 
-Codebase supports Rust, JavaScript, TypeScript/TSX, Vue, Python, Go, Java, C#, Kotlin, PHP, Ruby, Bash, and PowerShell. Dependency rules also recognize C and C++.
+```text
+Implementation duplication: 3 related items
+
+  Rule:        reforge.codebase.shadowed_abstraction
+  Locations:   forms/legacy_email_validator.py:1
+               forms/signup_email_validator.py:1
+               shared/email_validator.py:1
+  Measurement: group size 3 (threshold 3)
+  Guidance:    Consolidate shared behavior or make separate variants explicit.
+```
 
-Analysis runs locally. Reforge does not upload source code or collect telemetry.
+The evidence makes a finding inspectable; it does not decide the refactor for
+you. An empty report is meaningful only for the languages, capabilities, and
+rules marked as observed in Coverage.
 
-## Use it in CI
+## Automate review
 
-Keep configuration in `reforge.toml`, review a JSON report as a baseline, then gate new or changed policy findings:
+Export JSON or SARIF for CI and code-scanning integrations:
 
 ```sh
-reforge analyze . --output json --output-file current.json \
-  --baseline reforge-baseline.json --gate new --reproducible
+reforge analyze . --output sarif --output-file reforge.sarif --reproducible
 ```
 
-Rules begin as opt-in previews. This keeps adoption deliberate: enable the signals that fit your codebase, review their evidence, and enforce only the policies your team has accepted.
+All current core rules are preview and advisory-only. The `--gate` options apply
+only to rules that later satisfy Reforge's calibration contract, become stable,
+and are explicitly enforced; preview findings do not fail CI.
+
+## Advanced Dataflow analysis
+
+Dataflow is opt-in and intended for exact value-path and declared-boundary
+inspection:
+
+```sh
+reforge analyze . --analysis dataflow --output json --reproducible
+reforge analyze . --analysis codebase --analysis dataflow --reproducible
+```
 
-## Learn more
+See the [Dataflow guide](docs/dataflow.md) for its configuration and coverage
+limits.
 
-- [Documentation](https://lylemi.github.io/Reforge/) — start here for installation, configuration, and report interpretation
-- [Codebase guide](docs/analyses.md) — understand what is analyzed and how to review findings
-- [Rule reference](docs/rule-cards.md) — see every available signal and its intended limits
-- [Configuration reference](docs/configuration.md) — tune scope, thresholds, policies, and suppressions
-- [Contributing](docs/contributing.md) — build and test Reforge locally
+## Documentation
 
-Reforge also includes an advanced, opt-in [Dataflow analysis](docs/dataflow.md) for exact value-path and boundary-policy inspection.
+- [User guide](https://lylemi.github.io/Reforge/user-guide.html)
+- [Codebase analysis](docs/analyses.md)
+- [Rule reference](docs/rule-cards.md)
+- [Configuration reference](docs/configuration.md)
+- [Contributing](docs/contributing.md)
 
 ## Development
 
-Reforge is a Rust 2024 workspace. Run the full validation suite with:
+Reforge is a Rust 2024 workspace. Run the complete validation gate with:
 
 ```sh
-cargo fmt --all -- --check
-cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
-cargo test --locked --workspace --all-targets --all-features
+scripts/check-ci.sh
 ```
 
-Run the complete Linux CI gate locally, or install it as a pre-push hook:
+Or run the core checks directly:
 
 ```sh
-scripts/check-ci.sh
-scripts/install-git-hooks.sh
+cargo fmt --all -- --check
+cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
+cargo test --locked --workspace --all-targets --all-features
 ```

crates/reforge-output/src/human.rs

@@ -102,8 +102,31 @@ fn write_human_coverage(
             }
         }
     }
+    write_human_rules(writer, coverage)?;
+    Ok(())
+}
+
+fn write_human_rules(
+    writer: &mut impl Write,
+    coverage: &reforge_schema::AnalysisCoverage,
+) -> Result<()> {
     for (rule, execution) in &coverage.rules {
-        write_human_rule(writer, rule, execution)?;
+        if execution.enabled_source != reforge_schema::RuleActivation::Disabled {
+            write_human_rule(writer, rule, execution)?;
+        }
+    }
+    let disabled = coverage
+        .rules
+        .values()
+        .filter(|execution| {
+            execution.enabled_source == reforge_schema::RuleActivation::Disabled
+        })
+        .count();
+    if disabled > 0 {
+        writeln!(
+            writer,
+            "    {disabled} disabled rule(s) omitted; JSON and YAML retain full coverage"
+        )?;
     }
     Ok(())
 }

crates/reforge-output/src/tests.rs

@@ -151,3 +151,42 @@ fn human_output_includes_language_capability_receipts() {
     assert!(output.contains("capability direct_calls: Partial"));
     assert!(output.contains("unresolved_direct_call (1): one call could not be resolved"));
 }
+
+#[test]
+fn human_output_summarizes_disabled_rules_without_losing_machine_coverage() {
+    let mut report = report_with_issue();
+    report.coverage.get_mut("codebase").unwrap().rules = BTreeMap::from([
+        (
+            "reforge.codebase.large_file".into(),
+            reforge_schema::RuleExecution {
+                maturity: "preview".into(),
+                enabled_source: reforge_schema::RuleActivation::Enable,
+                status: CoverageStatus::Observed,
+                observations: Vec::new(),
+                limitations: Vec::new(),
+            },
+        ),
+        (
+            "reforge.codebase.long_function".into(),
+            reforge_schema::RuleExecution {
+                maturity: "preview".into(),
+                enabled_source: reforge_schema::RuleActivation::Disabled,
+                status: CoverageStatus::Observed,
+                observations: Vec::new(),
+                limitations: Vec::new(),
+            },
+        ),
+    ]);
+    report.provenance = default_provenance(&report.coverage, &report.issues);
+
+    let mut output = Vec::new();
+    write_report(&mut output, &report, OutputFormat::Human).unwrap();
+    let output = String::from_utf8(output).unwrap();
+
+    assert!(output.contains("rule reforge.codebase.large_file"));
+    assert!(!output.contains("rule reforge.codebase.long_function"));
+    assert!(output.contains("1 disabled rule(s) omitted"));
+
+    let json = serde_json::to_value(&report).unwrap();
+    assert!(json["coverage"]["codebase"]["rules"]["reforge.codebase.long_function"].is_object());
+}

docs/configuration.md

@@ -16,7 +16,12 @@ exclude-tests = false
 ignore-paths = []
 
 [rules]
-enable = []
+enable = [
+  "reforge.codebase.large_file",
+  "reforge.codebase.long_function",
+  "reforge.codebase.dependency_cycle",
+  "reforge.codebase.similar_functions",
+]
 disable = []
 enforce = []
 
@@ -46,8 +51,9 @@ min-modules = 3
 Rule arrays require complete IDs. Duplicate, conflicting, and unknown IDs are
 errors. `enforce` implies enable and accepts only stable rules. Experimental
 rules remain internal observations; preview rules are off unless enabled and
-can only produce advisory Issues. Only explicitly enforced stable rules produce
-policy Issues or participate in a gate.
+can only produce advisory Issues. The CLI starter configuration enables four
+preview rules explicitly. Only enforced stable rules produce policy Issues or
+participate in a gate.
 
 Each Dataflow policy is single-language and names exact sink declarations:
 

docs/rule-cards.md

@@ -11,6 +11,9 @@ All rules below are currently `preview`, `default_enabled = false`,
 `validation_basis = fixture`, semantic version `1.0.0`, and ineligible for
 enforcement. A language can become stable only through the audited calibration
 protocol in `calibration/README.md`; other languages remain preview.
+The CLI's starter configuration explicitly enables four of these rules as
+advisories; this does not change their manifest maturity or default-enabled
+state.
 
 | Rule | Claim / inspection question | Capability | Positive and negative fixtures | Legitimate exceptions |
 | --- | --- | --- | --- | --- |

docs/user-guide.md

@@ -37,6 +37,12 @@ Run the default Codebase analysis:
 reforge analyze . --reproducible
 ```
 
+Without a configuration file, the CLI enables a small starter set of preview
+advisories for large files, long functions, dependency cycles, and similar
+functions. They produce review prompts but cannot fail a policy gate. Run
+`reforge init` to write the same starter selection to `reforge.toml`, then tune
+or disable it for the repository.
+
 Dataflow is explicit. Run it alone or combine both core analyses over one workspace index:
 
 ```sh
@@ -70,7 +76,9 @@ reforge analyze . --output json --output-file current.json \
   --baseline reforge-baseline.json --gate new --reproducible
 ```
 
-`--gate all` fails on every current policy Issue. Rules are preview/off by default; enable and enforce the selected rule IDs in versioned `reforge.toml`.
+`--gate all` fails on every current policy Issue. Most rules remain preview/off;
+enable selected preview rules as advisories in versioned `reforge.toml`. Only
+stable rules can be enforced as policy.
 
 ## Configuration and rules