PCTL-2: stabilize CLI and package identity

.github/workflows/ci.yml

@@ -38,6 +38,14 @@ jobs:
       - name: Run tests
         run: go test ./...
 
+      - name: Verify Go developer fallback identity
+        run: |
+          GOBIN="${RUNNER_TEMP}/go-bin"
+          mkdir -p "${GOBIN}"
+          GOBIN="${GOBIN}" go install ./cmd/profitctl
+          test -x "${GOBIN}/profitctl"
+          test "$("${GOBIN}/profitctl" --version)" = "profitctl dev"
+
   verify-install-smoke:
     runs-on: ubuntu-latest
     steps:
@@ -71,13 +79,36 @@ jobs:
       - name: Run installer smoke test
         run: |
           INSTALL_DIR="${RUNNER_TEMP}/profitctl-bin"
+          TEST_HOME="${RUNNER_TEMP}/profitctl-home"
           mkdir -p "${INSTALL_DIR}"
+          mkdir -p "${TEST_HOME}"
           PROFITCTL_DOWNLOAD_BASE_URL="${PROFITCTL_TEST_MIRROR}" \
           PROFITCTL_VERSION=v0.0.0-ci \
           PROFITCTL_INSTALL_DIR="${INSTALL_DIR}" \
           bash scripts/install.sh
-          "${INSTALL_DIR}/profitctl" --help >/dev/null
-          "${INSTALL_DIR}/profitctl" validate -f examples/mix_profit.yml >/dev/null
+          env -i \
+            HOME="${TEST_HOME}" \
+            PATH="${INSTALL_DIR}:/usr/bin:/bin" \
+            CONFIG_FILE="${GITHUB_WORKSPACE}/examples/mix_profit.yml" \
+            CATALOG_FILE="${GITHUB_WORKSPACE}/test/fixtures/provider_catalog_valid.yml" \
+            sh -eu <<'EOF'
+          test "$(command -v profitctl)" = "${PATH%%:*}/profitctl"
+          test "$(profitctl --version)" = "profitctl v0.0.0-ci"
+          test "$(profitctl version)" = "profitctl v0.0.0-ci"
+          profitctl --help >/dev/null
+          profitctl validate -f "${CONFIG_FILE}" >/dev/null
+          profitctl doctor -f "${CONFIG_FILE}" --catalog "${CATALOG_FILE}" >/dev/null
+
+          set +e
+          doctor_output="$(profitctl doctor -f "${HOME}/missing-profit.yml" --catalog "${HOME}/missing-catalog.yml" 2>&1)"
+          doctor_status=$?
+          set -e
+          test "${doctor_status}" -eq 2
+          printf '%s\n' "${doctor_output}" | grep -F "[fail] config:" >/dev/null
+          printf '%s\n' "${doctor_output}" | grep -F "profitctl init --file" >/dev/null
+          printf '%s\n' "${doctor_output}" | grep -F "[fail] catalog:" >/dev/null
+          printf '%s\n' "${doctor_output}" | grep -F "no fallback or local state change was performed" >/dev/null
+          EOF
 
   security-scan:
     runs-on: ubuntu-latest

README.md

@@ -16,6 +16,7 @@ It helps teams model fixed + variable costs, simulate growth and stress scenario
 - `calibrate`: normalize YAML, JSON, or CSV calibration exports into ProfitCtl calibration artifacts
 - `validate`: validate config structure and rules
 - `detect`: scan repository config files and return JSON service/dependency analysis
+- `doctor`: check local binary, runtime, config, and catalog readiness without changing local state
 - pricing modes: `tiered`, `mix`, and `hybrid`
 - workspace-aware pricing and minimum-floor scenario modeling
 - payment-fee modeling with monthly vs annual billing mix
@@ -35,6 +36,8 @@ It helps teams model fixed + variable costs, simulate growth and stress scenario
 curl -fsSL https://raw.githubusercontent.com/IntelIP/ProfitCtl/main/scripts/install.sh | bash
 ```
 
+The installer downloads a GitHub Release archive, verifies it against that release's `SHA256SUMS`, and installs `profitctl` to `~/.local/bin` unless a custom prefix is selected.
+
 ### Homebrew
 
 ```bash
@@ -44,21 +47,26 @@ brew install profitctl
 
 See [Install Guide](docs/INSTALL.md) for pinned versions, Homebrew, custom prefixes, and source-based installs.
 
-### Build from source
+### Developer build from source
 
 ```bash
 git clone https://github.com/IntelIP/ProfitCtl.git
 cd ProfitCtl
 go build -o profitctl .
-./profitctl --help
+./profitctl --version
+./profitctl doctor -f examples/valid_profit.yml --catalog /path/to/provider-catalog.yml
 ```
 
-### Go install
+### Developer install with Go
 
 ```bash
-go install github.com/IntelIP/ProfitCtl@latest
+go install github.com/IntelIP/ProfitCtl/cmd/profitctl@<version>
 ```
 
+Choose a commit or future tag that contains `cmd/profitctl`; the current published
+`v0.2.0` tag predates this package. Go-based paths are explicit developer fallbacks.
+GitHub Release installation is the supported user path; Homebrew is secondary.
+
 ## Quick Usage
 
 ```bash

cmd/commands.go

@@ -5,5 +5,5 @@ import "github.com/spf13/cobra"
 func AddCommands(root *cobra.Command) {
 	var cfgFile string
 	root.PersistentFlags().StringVarP(&cfgFile, "file", "f", "profit.yml", "Configuration file path")
-	root.AddCommand(initCmd, simulateCmd, compareCmd, validateCmd, calibrateCmd, detectCmd)
+	root.AddCommand(initCmd, simulateCmd, compareCmd, validateCmd, calibrateCmd, detectCmd, versionCmd, doctorCmd)
 }