smart-commit-copilot-cli 0.1.3 → 0.1.5

package/docs/configuration.md

@@ -1,6 +1,43 @@
 # Configuration Guide
 
-This document explains how `smart-commit CLI` resolves configuration and which settings matter most in practice.
+This guide explains not only what each `smart-commit CLI` setting does, but also how to choose a good value for it.
+
+If you are new to the project, read [`getting-started.md`](./getting-started.md) first. Then use this page when you start asking:
+
+- which fields are actually required
+- which defaults are safe
+- which settings you should change first
+- which settings are easy to misconfigure
+
+## Start Here
+
+For most first-time users, the real minimum is:
+
+- `connection.baseUrl`
+- `connection.apiKey`
+- `connection.model`
+- `git.autoCommit`
+- `git.autoPush`
+
+Use this as your safe starting point:
+
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    },
+    "git": {
+      "autoCommit": false,
+      "autoPush": false
+    }
+  }
+}
+```
+
+This gives you a review-first workflow with no commit or push side effects.
 
 ## Recommended Format
 
@@ -18,15 +55,15 @@ Use the canonical JSON format:
 }
 ```
 
-Legacy `smartCommit.*` keys are still accepted for migration, but they are compatibility input only.
+Legacy `smartCommit.*` keys are still accepted for migration, but they should be treated as compatibility input only.
 
-## Precedence
+## How Configuration Is Resolved
 
-Merged from high to low:
+The CLI merges config from high to low precedence:
 
 1. CLI arguments
 2. environment variables
-3. `smartCommitCli`
+3. `smartCommitCli` in a JSON config file
 4. legacy `smartCommit.*`
 5. built-in defaults
 
@@ -40,6 +77,8 @@ Final result:
 
 - `git.autoPush = true` from CLI
 
+This means the command line always wins, which is useful for temporarily overriding a shared config file.
+
 ## `env:VAR_NAME` References
 
 String values that begin with `env:` are resolved from the current process environment after merge and before validation.
@@ -62,86 +101,268 @@ Required shell setup:
 export SMART_COMMIT_API_KEY="your-api-key"
 ```
 
-## High-Value Settings
+This pattern is recommended for secrets because:
 
-These are the fields most users usually need first.
+- the same config file can work across machines
+- secrets stay out of committed config files
+- `config resolve` will still show the final merged config with secret redaction
 
-### Connection
+## The Most Important Warning
 
-- `connection.baseUrl`
-- `connection.apiKey`
-- `connection.model`
-- `connection.requestTimeoutMs`
-- `connection.extraHeaders`
+The built-in defaults are not always the safest rollout defaults.
 
-### Review
+In particular, the built-in config defaults are:
 
-- `review.threshold`
-- `review.language`
-- `review.maxDiffChars`
-- `review.skill.id`
-- `review.skill.path`
-- `review.skill.promptTuning`
+- `git.autoStageWhenNothingStaged = true`
+- `git.autoCommit = true`
+- `git.autoPush = true`
 
-Numeric review scores are the final gating signal:
+These may be fine for a mature automated workflow, but they are too aggressive for first rollout.
 
-- `score <= review.threshold` blocks
-- `score > review.threshold` passes
-- if a review returns `score = null`, the model decision is used
+For first use, explicitly set:
 
-### Commit Message
+```json
+{
+  "smartCommitCli": {
+    "git": {
+      "autoCommit": false,
+      "autoPush": false
+    }
+  }
+}
+```
 
-- `commitMessage.input`
-- `commitMessage.language`
-- `commitMessage.autoGenerate`
-- `commitMessage.hybridGenerate`
-- `commitMessage.validation.protocol`
-- `commitMessage.validation.pattern`
-- `commitMessage.validation.extractTicketIdFromBranch`
-- `commitMessage.validation.requireTicketIdInMessage`
-- `commitMessage.skill.id`
-- `commitMessage.skill.path`
-- `commitMessage.skill.promptTuning`
+## Safe Team Rollout Example
 
-### Git
+Recommended early team setup:
 
-- `git.autoStageWhenNothingStaged`
-- `git.autoCommit`
-- `git.autoPush`
-- `git.pushTimeoutMs`
+```json
+{
+  "smartCommitCli": {
+    "connection": {
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "env:SMART_COMMIT_API_KEY",
+      "model": "gpt-5"
+    },
+    "review": {
+      "threshold": 6,
+      "language": "zh"
+    },
+    "git": {
+      "autoStageWhenNothingStaged": true,
+      "autoCommit": false,
+      "autoPush": false
+    },
+    "passHistory": {
+      "enabled": true,
+      "dirPath": ".smart-commit-cli",
+      "maxEntries": 3000
+    },
+    "output": {
+      "format": "json",
+      "logLevel": "info"
+    }
+  }
+}
+```
+
+This is a practical team default because it:
+
+- keeps the rollout safe
+- stores successful run history
+- stays friendly to hooks and automation
+
+## Field-By-Field Decision Guide
+
+This section is the main reference for how to choose values.
+
+### `connection.*`
+
+These settings tell the CLI how to reach your AI endpoint. `bridge` requires all three of `baseUrl`, `apiKey`, and `model`.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `connection.baseUrl` | empty string | `https://api.openai.com/v1` or your internal OpenAI-compatible gateway | Change it when you use a proxy, gateway, or non-default compatible endpoint | Leaving it empty and expecting `bridge` to work |
+| `connection.apiKey` | empty string | `env:SMART_COMMIT_API_KEY` | Change it only if you intentionally inject secrets another way | Putting raw secrets into committed config files |
+| `connection.model` | empty string | A model name that your chosen `baseUrl` actually serves | Change it when you switch cost, quality, or provider capabilities | Using a model name unsupported by your gateway |
+| `connection.requestTimeoutMs` | `1000000` | Leave default first | Change it only if your provider is too slow or your requests time out unexpectedly | Setting it below `5000`, which fails validation |
+| `connection.extraHeaders` | `{}` | Leave empty first | Add values only if your proxy or API gateway requires custom headers | Adding provider-specific headers that your endpoint does not expect |
+
+Practical guidance:
+
+- if you do not know what to choose, ask one question first: "What OpenAI-compatible base URL and model name does our environment support?"
+- if you use an internal gateway, use the gateway's supported model list instead of guessing
+
+### `review.*`
+
+These settings control review quality, language, and pass-or-block behavior.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `review.threshold` | `6` | `6` | Lower it if you get too many false blocks; raise it if you want stricter gating | Misreading the rule: `score <= threshold` blocks, `score > threshold` passes |
+| `review.language` | `zh` | `zh` or `en`, depending on your team | Change it when your team wants review output in a different language | Assuming it changes Git behavior instead of review text |
+| `review.maxDiffChars` | `100000` | Leave default first | Lower it if very large diffs are too slow or costly | Setting it below `1000`, which fails validation |
+| `review.skill.id` | `code-review` | `code-review` | Change it when your repo needs domain-specific built-in review guidance | Using an unsupported id |
+| `review.skill.path` | empty string | Leave empty first | Set it when your team has a custom review rules file | Setting both a custom path and then wondering why the built-in id does not matter |
+| `review.skill.promptTuning` | empty string | Leave empty first | Add a short custom instruction when a full skill file is too heavy | Putting large policy documents into a tiny tuning string |
+
+Supported built-in review skill ids:
+
+- `code-review`
+- `frontend-code-review`
+- `mobile-code-review`
+- `python-code-review`
+- `golang-code-review`
+- `java-code-review`
+- `cpp-code-review`
+- `csharp-code-review`
+- `rust-code-review`
+- `php-code-review`
+
+When to choose a custom skill path:
+
+- your team has a fixed review checklist
+- you need security or compliance-specific review rules
+- you want domain rules that are too long for `promptTuning`
+
+### `commitMessage.*`
+
+These settings control where the commit message comes from and how it is validated.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `commitMessage.input` | empty string | Leave empty first | Set it when you already know the exact message you want | Setting it and expecting auto-generation to replace it |
+| `commitMessage.language` | `zh` | `zh` or `en` | Change it to match your team's commit language | Mixing a team English convention with a non-English expectation |
+| `commitMessage.autoGenerate` | `true` | `true` | Set `false` only if users always provide a message themselves | Turning it off with no provided message, which causes a commit-message-required error |
+| `commitMessage.hybridGenerate` | `false` | `false` | Set `true` when users provide a draft and want AI to refine it | Enabling it without understanding that it uses `commitMessage.input` as a draft |
+| `commitMessage.validation.protocol` | `none` | `none` first, then `conventional` if your team standardizes on it | Change it when your team enforces a commit style | Enabling validation before the team is ready |
+| `commitMessage.validation.pattern` | empty string | Leave empty first | Add a JavaScript regex only when your policy needs extra format checks | Writing an invalid regex pattern |
+| `commitMessage.validation.extractTicketIdFromBranch` | `true` | `true` if your branches contain ticket ids | Set `false` if your branch naming does not include tickets | Expecting ticket extraction from branches that have no ticket ids |
+| `commitMessage.validation.requireTicketIdInMessage` | `false` | `false` first | Set `true` only if your process really requires ticket ids in commit messages | Enforcing it before branch naming and generation are aligned |
+| `commitMessage.skill.id` | `conventional` | `conventional` | Change it when you prefer another built-in commit style | Using a commit skill id that does not match your validation expectations |
+| `commitMessage.skill.path` | empty string | Leave empty first | Set it when your team has its own commit-message policy file | Assuming a custom path still validates against the built-in id set |
+| `commitMessage.skill.promptTuning` | empty string | Leave empty first | Add light style nudges without creating a full skill file | Cramming a full handbook into one short string |
+
+How `hybridGenerate` actually works:
+
+- if `commitMessage.input` is present and `hybridGenerate=false`, the CLI validates and uses the provided message directly
+- if `commitMessage.input` is present and `hybridGenerate=true`, the CLI uses your draft as input to AI and returns a refined message
+- if `commitMessage.input` is empty and `autoGenerate=true`, the CLI generates from the diff
+- if `commitMessage.input` is empty and `autoGenerate=false`, the CLI errors because no message source exists
+
+Supported validation protocols:
+
+- `none`
+- `conventional`
+- `semantic`
+- `gitmoji`
+
+Supported built-in commit message skill ids:
+
+- `conventional`
+- `semantic`
+- `gitmoji`
+
+### `git.*`
+
+These settings control whether the CLI changes Git state.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `git.autoStageWhenNothingStaged` | `true` | `true` for convenience or `false` for stricter control | Set `false` if your team wants users to explicitly stage exact files | Forgetting it is enabled and wondering why unstaged files were included |
+| `git.autoCommit` | `true` | `false` | Set `true` only after review-only mode is stable | Leaving the default on during first rollout |
+| `git.autoPush` | `true` | `false` | Set `true` only after your team accepts automatic push behavior | Letting first rollout push unexpectedly |
+| `git.pushTimeoutMs` | `90000` | Leave default first | Increase it only if pushes are slow in your environment | Setting it below `5000`, which fails validation |
+
+Practical rollout advice:
 
-### Pass History
+- if you care more about safety than convenience, keep both `autoCommit` and `autoPush` off
+- if you care more about speed than strict staging hygiene, keep `autoStageWhenNothingStaged=true`
 
-- `passHistory.enabled`
-- `passHistory.dirPath`
-- `passHistory.maxEntries`
+### `passHistory.*`
 
-Pass history records store the runtime outcome of successful bridge runs.
+These settings control local storage for successful run history.
 
-The main event types are:
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `passHistory.enabled` | `false` | `true` if you want reporting later | Turn it on when you want local historical reporting | Forgetting to enable it and then expecting `report generate` to summarize past work |
+| `passHistory.dirPath` | empty string | Leave empty first or set `.smart-commit-cli` explicitly | Change it only if you want a custom location | Thinking empty means broken, when it actually falls back to the repo-local default directory |
+| `passHistory.maxEntries` | `3000` | `3000` | Change it only if you need much shorter or longer retention | Setting it to `0` or a non-integer, which fails validation |
 
-- `review_passed`
-- `commit_completed`
-- `commit_push_completed`
+If `passHistory.dirPath` is empty, the CLI automatically stores pass history under the repository's `.smart-commit-cli` directory.
 
-Each record also stores `autoCommit` and `autoPush`, so later reporting can distinguish configuration intent from actual runtime outcome.
+### `reporting.*`
 
-### Reporting
+These settings control report generation behavior.
 
-- `reporting.language`
-- `reporting.weekStartsOn`
-- `reporting.outputDirPath`
-- `reporting.prompt`
-- `reporting.ai.enabled`
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `reporting.language` | `zh` | `zh` or `en` | Change it when your team wants report output in another language | Assuming this changes review or commit-message language too |
+| `reporting.weekStartsOn` | `monday` | `monday` | Change it to `sunday` only if your reporting convention starts weeks on Sunday | Picking a week start different from your team's reporting habit |
+| `reporting.outputDirPath` | empty string | Leave empty first | Change it only when you want reports in a different directory | Thinking empty means invalid, when it actually falls back to the repo-local default directory |
+| `reporting.prompt` | empty string | Leave empty first | Add it when you want reports to emphasize business outcomes or another angle | Writing a very large prompt when a short focus instruction would do |
+| `reporting.ai.enabled` | `false` | `false` first | Enable it when you want richer AI-rendered reports instead of local-only rendering | Turning it on before confirming connection settings are valid |
 
-### Output
+If `reporting.outputDirPath` is empty, the CLI writes reports to `.smart-commit-cli/reports` under the repository root.
 
-- `output.format`
-- `output.logLevel`
+### `output.*`
+
+These settings control how results are presented.
+
+| Field | Built-in default | Recommended first value | When to change it | Common mistake |
+| --- | --- | --- | --- | --- |
+| `output.format` | `json` | `json` for automation, `text` for interactive terminal use | Change it based on whether a human or a script will read stdout | Using `text` in a hook or script that expects structured JSON |
+| `output.logLevel` | `info` | `info` | Use `debug` when diagnosing behavior, `warn` when you only want warnings and errors | Leaving `debug` on in normal automation and creating noisy logs |
+
+## Supported Value Sets
+
+These are the validated option sets enforced by the CLI.
+
+### Languages
+
+Supported output and commit-message languages:
+
+- `zh`
+- `en`
+- `de`
+- `fr`
+- `es`
+- `it`
+- `pt`
+- `tr`
+- `id`
+- `hi`
+- `ru`
+- `ko`
+- `ja`
+
+### Commit message validation protocols
+
+- `none`
+- `conventional`
+- `semantic`
+- `gitmoji`
+
+### Report week start
+
+- `monday`
+- `sunday`
+
+### Output format
+
+- `json`
+- `text`
+
+### Log levels
+
+- `debug`
+- `info`
+- `warn`
+- `error`
 
 ## Common CLI Flags
 
-Most frequently used:
+Most practical flags:
 
 ```bash
 --repo
@@ -185,94 +406,127 @@ SMART_COMMIT_REPORT_LANGUAGE
 SMART_COMMIT_REPORT_OUTPUT_DIR
 ```
 
-## Minimal Practical Config
+Useful boolean environment variables accept:
 
-If you want the smallest useful starting point:
+- `true`
+- `false`
+- `1`
+- `0`
 
-```json
-{
-  "smartCommitCli": {
-    "connection": {
-      "baseUrl": "https://api.openai.com/v1",
-      "apiKey": "env:SMART_COMMIT_API_KEY",
-      "model": "gpt-5"
-    },
-    "git": {
-      "autoCommit": false,
-      "autoPush": false
-    }
-  }
-}
+## Command-Specific Notes
+
+### `config resolve`
+
+Use this command to inspect the final merged config:
+
+```bash
+smart-commit config resolve --config ./smart-commit.json
 ```
 
-This gives you a safe review-first starting point.
+This is the fastest way to catch:
 
-## Safer Team Rollout Config
+- missing environment variables
+- invalid booleans or numbers
+- invalid protocol values
+- invalid regex patterns
+- unsupported skill ids
 
-Recommended early team setup:
+### `bridge`
 
-```json
-{
-  "smartCommitCli": {
-    "connection": {
-      "baseUrl": "https://api.openai.com/v1",
-      "apiKey": "env:SMART_COMMIT_API_KEY",
-      "model": "gpt-5"
-    },
-    "git": {
-      "autoStageWhenNothingStaged": true,
-      "autoCommit": false,
-      "autoPush": false
-    },
-    "passHistory": {
-      "enabled": true,
-      "dirPath": ".smart-commit-cli",
-      "maxEntries": 3000
-    },
-    "output": {
-      "format": "json",
-      "logLevel": "info"
-    }
-  }
-}
+`bridge` requires:
+
+- `--repo`
+- a valid repository path inside Git
+- a valid connection configuration
+- staged changes, unless auto-stage makes input available
+
+Safest first run:
+
+```bash
+smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push
 ```
 
-## Notes On Skills
+### `report generate`
 
-`review.skill.path` and `commitMessage.skill.path` let you point to custom instruction files.
+`report generate` requires:
 
-Use them when:
+- `--repo`
+- a valid repository path inside Git
 
-- your team has custom review standards
-- your team has custom commit-message style guidance
+Supported periods:
 
-`promptTuning` is useful when you want small additive guidance without creating a separate skill file.
+- `daily`
+- `weekly`
+- `monthly`
+- `quarterly`
+- `yearly`
 
-## Notes On Output
+If `--period` is omitted, it defaults to `weekly`.
 
-Use:
+## Validation Workflow
 
-- `output.format = "json"` for hooks, agents, and automation
-- `output.format = "text"` for humans in the terminal
+Before integrating the CLI into hooks or automation, use this sequence:
 
-Use:
+1. create or update `smart-commit.json`
+2. run `smart-commit config resolve --config ./smart-commit.json`
+3. run `smart-commit bridge --repo . --config ./smart-commit.json --dry-run`
+4. run `smart-commit bridge --repo . --config ./smart-commit.json --no-commit --no-push`
+5. only then consider enabling auto-commit or auto-push
 
-- `output.logLevel = "debug"` when diagnosing behavior
-- `output.logLevel = "info"` for normal use
-- `output.logLevel = "warn"` when you only care about warnings and errors
+This sequence catches configuration mistakes before they become Git side effects.
 
-## Validation Tips
+## Common Mistakes
 
-Always validate the final config before integration:
+### I set `env:SMART_COMMIT_API_KEY`, but validation fails
+
+Make sure the environment variable exists in the same shell session:
 
 ```bash
-smart-commit config resolve --config ./smart-commit.json
+export SMART_COMMIT_API_KEY="your-api-key"
 ```
 
-This is the fastest way to catch:
+### I expected `--config` to be mandatory everywhere
 
-- missing environment variables
-- invalid booleans or numbers
-- invalid protocol values
-- invalid regex patterns
-- unsupported skill ids
+It is recommended, but not strictly required.
+
+If omitted, the CLI still resolves from:
+
+- CLI flags
+- environment variables
+- built-in defaults
+
+Use `--config` whenever you want predictable, reusable team configuration.
+
+### I enabled `autoCommit` or `autoPush` too early
+
+For first rollout, keep this block safe:
+
+```json
+{
+  "smartCommitCli": {
+    "git": {
+      "autoCommit": false,
+      "autoPush": false
+    }
+  }
+}
+```
+
+Then verify the workflow in review-only mode first.
+
+### I still do not know what to change first
+
+Use this order:
+
+1. make `connection.baseUrl`, `connection.apiKey`, and `connection.model` valid
+2. set `git.autoCommit=false`
+3. set `git.autoPush=false`
+4. leave everything else near the defaults
+5. only tune `review.threshold`, languages, and reporting after you have one successful run
+
+## Where To Go Next
+
+- safe onboarding flow: [`getting-started.md`](./getting-started.md)
+- broader CLI overview: [`../README.md`](../README.md)
+- integration patterns: [`integrations.md`](./integrations.md)
+- machine-facing contracts: [`contracts.md`](./contracts.md)