# Getting Started

This guide is the fastest safe path from a fresh setup to a successful `smart-commit-host-agent bridge --review-only` run.

It is written for first-time users who want to:

- get the CLI working quickly
- understand what each step proves
- avoid accidental commit or push side effects

## What You Will Accomplish

By the end of this guide, you will:

1. choose how you want to run the CLI
2. prepare a minimal config (no LLM API key)
3. validate the final merged config
4. run review-only mode through one Host-Agent turn
5. optionally enable pass history and reporting
6. optionally review an existing PR or MR

## Prerequisites

Before you start, make sure you have:

- `Node.js >= 20`
- `git` available in your shell
- a Git repository to operate on
- staged changes, or a config that allows auto-stage
- a Host Agent (Cursor, Codex, …) for commands that emit `needs_host_agent`

Important command requirements:

- `bridge` requires `--repo`
- `report generate` requires `--repo`
- `pull-request review` requires a PR/MR URL
- `my-pull-request list` requires PR auth but not a Host-Agent turn
- `my-pull-request batch-review` requires PR auth and Host-Agent turns for review
- `config resolve` does not require `--repo`
- this CLI never requires `SMART_COMMIT_API_KEY` or a `connection` block

## Choose How To Run The CLI

You have three common options.

### Option 1: Use the published package

Install globally:

```bash
npm install -g smart-commit-host-agent
smart-commit-host-agent --help
```

Or use `npx` directly:

```bash
npx smart-commit-host-agent --help
```

### Option 2: Run from a local checkout

From the repository root:

```bash
npm install
npm run build
node out/cli.js --help
```

### Option 3: Decide once, use one command form everywhere

All examples below use:

```bash
smart-commit-host-agent
```

If you did not install the binary, replace it with:

```bash
node out/cli.js
```

If you run the CLI from a Cursor or Codex skill, the skill should wrap the `needs_host_agent` loop for you. The same commands still apply.

## Step 1: Create A Minimal Config File

In your target repository, create `smart-commit.host-agent.json`:

```json
{
  "smartCommitHostAgent": {
    "review": {
      "threshold": 6,
      "language": "zh-cn"
    },
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}
```

There is no `connection` block. Model text comes from the Host Agent that runs this CLI, not from an LLM HTTP API.

This config is intentionally conservative:

- `autoCommit=false` prevents creating a local commit
- `autoPush=false` prevents pushing to remote

Built-in defaults currently enable `git.autoCommit`, `git.autoPush`, and `pullRequestCreation.autoCreateAfterPush`. First-use configs should set those to `false` explicitly.

If you want a fuller example, see `examples/config.host-agent.json`, but do not copy side-effect settings blindly for first use.

## Step 2: Validate The Final Config

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json
```

This is the recommended first real command because it shows:

- merged config after CLI args, env vars, file config, and defaults
- secret redaction
- validation errors before execution

For a more readable terminal view:

```bash
smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json --output text
```

You should expect:

- `status: "resolved"`
- no `connection` field
- `git.autoCommit` and `git.autoPush` are `false`

## Step 3: Prepare Some Staged Changes

Inside your target repository:

```bash
git add -A
git status --short
```

`bridge` works on staged content, so this step matters.

If nothing is staged and `git.autoStageWhenNothingStaged` is disabled, `bridge` will block.

## Step 4: Run Review-Only Mode

This is the safest way to onboard the CLI into a real workflow:

```bash
smart-commit-host-agent bridge --review-only --repo . --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

This lets you verify:

- review execution
- threshold behavior
- structured JSON output
- the Host-Agent turn loop

without running commit-message generation or validation, and without creating a commit or pushing to remote.

What you should expect on the first run:

- exit code `10`
- `status: "needs_host_agent"`
- `sessionPath`, `requestPath`, and `turnId`

The Host Agent reads `turns/NNNN.request.json`, writes `turns/NNNN.response.json`, then the same command is resumed:

```bash
smart-commit-host-agent bridge --review-only --repo . --session <sessionPath> --output json
```

Expected result after resume:

- `status: "passed"` if the review passes
- `status: "blocked"` if the review score is at or below `review.threshold`
- `status: "error"` if config or runtime setup is invalid

If you want the main bridge workflow to still generate or validate the commit message but stop before creating a local commit, use `--no-commit` instead.

When the review returns a numeric score, the final pass or block result is determined by comparing that score with the configured `review.threshold`.

## Step 5: Enable Pass History When You Are Ready

If you want reporting later, enable pass history in config:

```json
{
  "smartCommitHostAgent": {
    "passHistory": {
      "enabled": true,
      "writeStage": "review_passed"
    }
  }
}
```

Then run review-only again. Successful runs write local JSONL history.

`passHistory.writeStage` controls the earliest successful stage that is allowed to create a record. After that point, the same run updates the same record if it later reaches commit or push success, so the stored `eventType` always reflects the furthest successful stage reached by that run.

- `review_passed` writes as soon as review succeeds
- `commit_completed` waits until the local commit succeeds
- `commit_push_completed` waits until both the local commit and push succeed

## Step 6: Generate A Report

```bash
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json --period weekly
```

Supported periods:

- `daily`
- `yesterday`
- `weekly`
- `last-week`
- `monthly`
- `last-month`
- `quarterly`
- `last-quarter`
- `yearly`

If `--period` is omitted, the CLI defaults to `weekly`.

Useful follow-up checks:

- confirm `outputFilePath`
- confirm `renderMode`
- inspect the generated Markdown

Optional AI-enhanced reporting (Host-Agent turn; local fallback on non-turn failures):

```bash
smart-commit-host-agent report generate --repo . --config ./smart-commit.host-agent.json \
  --period weekly --report-ai --session-base /tmp/scha --output json
```

## Optional: Review An Existing PR Or MR

After the staged-change workflow is working, you can use the same review engine against a remote GitHub pull request or GitLab merge request. Put the provider token in config as `pullRequest.authToken` (for example `"authToken": "env:SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN"`), or export the environment variable:

```bash
export SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN="your-provider-token"

smart-commit-host-agent pull-request review \
  https://github.com/org/repo/pull/123 \
  --repo . \
  --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha \
  --dry-run \
  --output json
```

Dry-run still reads the PR/MR and runs the Host-Agent review, but it skips comments, approval, and merge. Remove `--dry-run` only after `pullRequestReview.*` and provider permissions are set the way you want.

## Suggested First Rollout

For a new repository, skill, or team, use this order:

1. validate config with `config resolve`
2. run `bridge --review-only` and complete the Host-Agent turn
3. wire the same review-only command into your skill
4. enable pass history
5. add reporting
6. optionally dry-run `pull-request review` against a test PR/MR
7. only then consider automatic commit, push, approval, or merge automation

This rollout keeps the first adoption phase safe while still validating the full workflow.

## Troubleshooting Checklist

If your first run fails, check these in order:

1. Did you pass `--repo` for `bridge` or `report generate`?
2. Are there staged changes?
3. Does `smart-commit-host-agent config resolve --config ./smart-commit.host-agent.json` succeed?
4. Are `autoCommit` and `autoPush` still disabled while you test?
5. If the command exited `10`, did the Host Agent write `turns/NNNN.response.json` before you resumed with `--session`?
6. Did you pass `--api-key` / `--base-url` / `--model`? This package rejects those flags.

## Where To Go Next

- broader overview and safe rollout guidance: [`../README.md`](../README.md)
- configuration details: [`configuration.md`](./configuration.md)
- integration patterns: [`integrations.md`](./integrations.md)
- machine-facing contracts: [`contracts.md`](./contracts.md)