feat: enable NuGet publishing and update docs with feature switches

Enable ENABLE_NUGET and document all 5 CI feature switches
(ENABLE_NUGET, NUGET_USE_OIDC, ENABLE_INSTALLERS, ENABLE_ANDROID,
ENABLE_IOS) across README, CONTRIBUTING, and VitePress docs (EN/ZH).
Add init script references to getting-started guides.

Made-with: Cursor

Author: Hongwei-MB

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ env:
   DOTNET_CLI_TELEMETRY_OPTOUT: true
   NUKE_TELEMETRY_OPTOUT: true
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-  ENABLE_NUGET: 'false'
+  ENABLE_NUGET: 'true'
   NUGET_USE_OIDC: 'false'
   ENABLE_INSTALLERS: 'true'
   ENABLE_ANDROID: 'false'

CONTRIBUTING.md

@@ -31,6 +31,20 @@ Common targets:
 | `./build.sh Format` | Verify code formatting |
 | `./build.sh Pack` | Create NuGet packages |
 | `./build.sh ShowVersion` | Display current version |
+| `./build.sh Benchmark` | Run BenchmarkDotNet benchmarks (requires `benchmarks/` projects) |
+| `./build.sh MutationTest` | Run Stryker.NET mutation testing |
+
+## CI Feature Switches
+
+The CI pipeline behavior is controlled by boolean switches in `.github/workflows/ci.yml` under `env:`:
+
+| Switch | Default | Purpose |
+|--------|---------|---------|
+| `ENABLE_NUGET` | `true` | NuGet package generation and publishing |
+| `NUGET_USE_OIDC` | `false` | `false` = API key, `true` = Trusted Publishing (OIDC) |
+| `ENABLE_INSTALLERS` | `true` | Platform installer zips (Publish + PackageApp) |
+| `ENABLE_ANDROID` | `false` | Android workload in build matrix |
+| `ENABLE_IOS` | `false` | iOS workload in build matrix |
 
 ## Development Workflow
 

README.md

@@ -76,16 +76,33 @@ Product Code (src/) + Tests (tests/)
 
 ## Quick Start
 
-1. Create your repository from this template:  
+1. Create your repository from this template:
    [Use this template](https://github.com/AGIBuild/dotnet.CI.template/generate)
-2. Configure `release` environment in GitHub (`Settings` -> `Environments`)
-3. Optional: add `NUGET_API_KEY`
-4. Push to `main` and approve release deployment in Actions
+2. Run the init wizard to rename everything:
 
 ```bash
-git push origin main
+./init.sh              # interactive (Linux/macOS)
+./init.ps1             # interactive (Windows)
 ```
 
+3. Configure `release` environment in GitHub (`Settings` -> `Environments`)
+4. Add `NUGET_API_KEY` secret (if `ENABLE_NUGET` is `true`)
+5. Review [Feature Switches](#feature-switches), then push to `main`
+
+## Feature Switches
+
+All switches live in `.github/workflows/ci.yml` under the top-level `env:` block.
+
+| Switch | Default | Purpose |
+|---|---|---|
+| `ENABLE_NUGET` | `true` | NuGet package generation and publishing |
+| `NUGET_USE_OIDC` | `false` | `false` = API key, `true` = Trusted Publishing (OIDC) |
+| `ENABLE_INSTALLERS` | `true` | Platform installer zips (Publish + PackageApp) |
+| `ENABLE_ANDROID` | `false` | Android workload in build matrix |
+| `ENABLE_IOS` | `false` | iOS workload in build matrix |
+
+When `ENABLE_NUGET` is `true`, either `NUGET_API_KEY` secret or OIDC trust policy must be configured; otherwise the release will fail with a clear error.
+
 ## Key Commands
 
 ```bash
@@ -94,6 +111,8 @@ git push origin main
 ./build.sh UpdateVersion --VersionPrefix 1.0.0    # set exact version
 ./build.sh Test                                   # build + test
 ./build.sh Pack                                   # build + test + pack
+./build.sh Benchmark                              # run benchmarks (benchmarks/ projects)
+./build.sh MutationTest                           # run Stryker.NET mutation testing
 ```
 
 ## Documentation

docs/contributing/ci-cd.md

@@ -54,12 +54,12 @@ For a quick release walkthrough, see: [Releasing](releasing.md).
 
 ### `release`
 - Requires `release` environment approval (single approval gate)
-- Downloads NuGet packages, verifies release manifest SHA256 integrity
-- Pushes NuGet packages to nuget.org (skipped if `NUGET_API_KEY` is not configured)
+- If `ENABLE_NUGET` is `true`: downloads NuGet packages, verifies release manifest SHA256 integrity, pushes to nuget.org via API key or OIDC (controlled by `NUGET_USE_OIDC`)
+- If `ENABLE_INSTALLERS` is `true`: downloads platform installer zips
 - Generates SBOM (SPDX format, `anchore/sbom-action`)
-- Creates Artifact Attestation (`actions/attest-build-provenance`, signs build provenance for NuGet packages and installer zips)
+- Creates Artifact Attestation for all available artifacts (NuGet packages and/or installer zips)
 - Creates a git tag and pushes to remote
-- Creates a GitHub Release with platform installer zips + SBOM file attached
+- Creates a GitHub Release with available assets (installer zips and/or SBOM)
 
 ### `build-docs`
 - Runs on every push/PR, in parallel with `build-and-test` (pre-check)
@@ -87,8 +87,24 @@ The repository includes built-in VitePress documentation support. To enable docu
 - Expected documentation URL: `https://<owner>.github.io/<repo>/`
 - The `Resolve Version` summary displays this URL for quick access
 
+### Feature Switches
+
+All switches live in `ci.yml` under the top-level `env:` block. Change their values to `'true'` or `'false'` to enable or disable pipeline features.
+
+| Switch | Default | Purpose |
+|--------|---------|---------|
+| `ENABLE_NUGET` | `true` | NuGet package generation (Pack) and publishing to nuget.org |
+| `NUGET_USE_OIDC` | `false` | `false` = push via `NUGET_API_KEY` secret; `true` = push via OIDC Trusted Publishing |
+| `ENABLE_INSTALLERS` | `true` | Platform installer zips (Publish + PackageApp) |
+| `ENABLE_ANDROID` | `false` | Include Android workload in the build matrix |
+| `ENABLE_IOS` | `false` | Include iOS workload in the build matrix |
+
+When `ENABLE_NUGET` is `true`:
+- If `NUGET_USE_OIDC` is `false`, the `NUGET_API_KEY` secret must be configured; otherwise the release fails with an explicit error.
+- If `NUGET_USE_OIDC` is `true`, a Trusted Publishing trust policy must be configured on nuget.org for the repository.
+
 ### Secrets
-- `NUGET_API_KEY`: NuGet.org API key (configure at the repo or `release` environment level)
+- `NUGET_API_KEY`: NuGet.org API key (required when `ENABLE_NUGET` is `true` and `NUGET_USE_OIDC` is `false`)
 
 ---
 

docs/contributing/releasing.md

@@ -9,7 +9,7 @@ Goal: **Complete a standard Release quickly**.
 
 - You have write access to the repository
 - `main` branch is up to date and CI is passing
-- If publishing to NuGet, the `NUGET_API_KEY` secret is configured
+- If `ENABLE_NUGET` is `true`: the `NUGET_API_KEY` secret (or OIDC trust policy) is configured
 - A `release` environment is created in GitHub (Settings → Environments) with required reviewers
 
 ---
@@ -45,8 +45,8 @@ After a successful run, you should see:
 
 - A new tag (e.g., `v0.2.0`)
 - A new GitHub Release
-- Release assets including platform installer zips (`app-linux-x64.zip`, `app-win-x64.zip`, etc.) and the SBOM file
-- A corresponding package version on NuGet.org (if `NUGET_API_KEY` is configured)
+- Release assets: installer zips (if `ENABLE_INSTALLERS` is `true`) and the SBOM file
+- A corresponding package version on NuGet.org (if `ENABLE_NUGET` is `true`)
 - If Pages is enabled: documentation deployed automatically
 
 ---
@@ -70,7 +70,7 @@ After committing the change to `main`, CI automatically builds and publishes wit
 - `Tag already exists`: This version was already released; bump `VersionPrefix` and retry
 - `No .nupkg files found`: No artifacts from the packaging stage; check Build/Test/Pack logs
 - `Hash mismatch`: Build artifacts were corrupted during transfer; re-trigger the workflow
-- NuGet push failed: Verify that the `NUGET_API_KEY` secret is configured
+- NuGet push failed: Verify that `ENABLE_NUGET` is `true` and the credential (API key or OIDC) is configured correctly
 
 ---
 

docs/guide/getting-started.md

@@ -22,7 +22,13 @@ var quotient = calculator.Divide(10, 2); // 5
 ## Using as a Template
 
 1. Click **Use this template** on the [GitHub repository](https://github.com/AGIBuild/dotnet.CI.template).
-2. Rename solution, projects, and namespaces to match your product.
+2. Run the init wizard to rename solution, projects, and namespaces:
+
+```bash
+./init.sh              # Linux / macOS
+./init.ps1             # Windows (PowerShell)
+```
+
 3. Replace the sample `Calculator` class with your own code.
 4. Update `Directory.Build.props` with your package metadata.
 5. Configure the `release` environment in GitHub Settings (see [Releasing](../contributing/releasing.md)).

docs/zh-cn/contributing/ci-cd.md

@@ -54,12 +54,12 @@ push / PR to main + weekly
 
 ### `release`
 - 需要 `release` environment approval（唯一的审批入口）
-- 下载 NuGet 包，验证 release manifest SHA256 完整性
-- 推送 NuGet 包到 nuget.org（如未配置 `NUGET_API_KEY` 则跳过）
+- 若 `ENABLE_NUGET` 为 `true`：下载 NuGet 包，验证 release manifest SHA256 完整性，通过 API key 或 OIDC 推送到 nuget.org（由 `NUGET_USE_OIDC` 控制）
+- 若 `ENABLE_INSTALLERS` 为 `true`：下载各平台安装包 zip
 - 生成 SBOM（SPDX 格式，`anchore/sbom-action`）
-- 创建 Artifact Attestation（`actions/attest-build-provenance`，为 NuGet 包和安装包签署构建来源证明）
+- 创建 Artifact Attestation（为所有可用产物签署构建来源证明）
 - 创建 git tag 并推送到 remote
-- 创建 GitHub Release，附带各平台安装包 zip + SBOM 文件
+- 创建 GitHub Release，附带可用产物（安装包 zip 和/或 SBOM 文件）
 
 ### `build-docs`
 - 每次 push/PR 均运行，与 `build-and-test` 并行（前置检查）
@@ -87,8 +87,24 @@ push / PR to main + weekly
 - 预期文档地址：`https://<owner>.github.io/<repo>/`
 - `Resolve Version` 的 Summary 会固定显示该地址，便于快速访问
 
+### 功能开关
+
+所有开关位于 `ci.yml` 顶层 `env:` 块中，将值改为 `'true'` 或 `'false'` 即可启用/禁用对应功能。
+
+| 开关 | 默认值 | 作用 |
+|------|--------|------|
+| `ENABLE_NUGET` | `true` | NuGet 包生成（Pack）和发布到 nuget.org |
+| `NUGET_USE_OIDC` | `false` | `false` = 使用 `NUGET_API_KEY`；`true` = 使用 OIDC Trusted Publishing |
+| `ENABLE_INSTALLERS` | `true` | 平台安装包 zip（Publish + PackageApp） |
+| `ENABLE_ANDROID` | `false` | 构建矩阵中包含 Android workload |
+| `ENABLE_IOS` | `false` | 构建矩阵中包含 iOS workload |
+
+当 `ENABLE_NUGET` 为 `true` 时：
+- 若 `NUGET_USE_OIDC` 为 `false`，必须配置 `NUGET_API_KEY` secret，否则 release 会明确报错。
+- 若 `NUGET_USE_OIDC` 为 `true`，需要在 nuget.org 上为该仓库配置 Trusted Publishing 信任策略。
+
 ### Secrets
-- `NUGET_API_KEY`：NuGet.org API key（在 repo 或 `release` environment 级别配置）
+- `NUGET_API_KEY`：NuGet.org API key（当 `ENABLE_NUGET` 为 `true` 且 `NUGET_USE_OIDC` 为 `false` 时必须配置）
 
 ---
 

docs/zh-cn/contributing/releasing.md

@@ -9,7 +9,7 @@
 
 - 你有仓库写权限
 - `main` 分支是最新、CI 通过
-- 如果要推 NuGet，仓库已配置 `NUGET_API_KEY` secret
+- 如果 `ENABLE_NUGET` 为 `true`：已配置 `NUGET_API_KEY` secret（或 OIDC 信任策略）
 - GitHub 仓库已创建 `release` environment（Settings → Environments），并配置 required reviewers
 
 ---
@@ -45,8 +45,8 @@ resolve-version─┤                                                   ├→ d
 
 - 新 tag（例如 `v0.2.0`）
 - 一个新的 GitHub Release
-- Release 附件里有各平台安装包 zip（`app-linux-x64.zip`、`app-win-x64.zip` 等）和 SBOM 文件
-- NuGet.org 上有对应版本的包（如已配置 `NUGET_API_KEY`）
+- Release 附件：安装包 zip（若 `ENABLE_INSTALLERS` 为 `true`）和 SBOM 文件
+- NuGet.org 上有对应版本的包（若 `ENABLE_NUGET` 为 `true`）
 - 如果已启用 Pages：文档自动部署
 
 ---
@@ -70,7 +70,7 @@ resolve-version─┤                                                   ├→ d
 - `Tag already exists`: 版本已发过，先提升 `VersionPrefix` 再重试
 - `No .nupkg files found`: 打包阶段没有产物，先看 Build/Test/Pack 日志
 - `Hash mismatch`: 构建产物在传递过程中损坏，重新触发 workflow
-- NuGet 推送失败: 确认 `NUGET_API_KEY` secret 已配置
+- NuGet 推送失败: 确认 `ENABLE_NUGET` 为 `true` 且凭据（API key 或 OIDC）已正确配置
 
 ---
 

docs/zh-cn/guide/getting-started.md

@@ -22,7 +22,13 @@ var quotient = calculator.Divide(10, 2); // 5
 ## 作为模板使用
 
 1. 在 [GitHub 仓库](https://github.com/AGIBuild/dotnet.CI.template)点击 **Use this template**。
-2. 重命名解决方案、项目和命名空间以匹配你的产品。
+2. 运行初始化向导，自动重命名解决方案、项目和命名空间：
+
+```bash
+./init.sh              # Linux / macOS
+./init.ps1             # Windows (PowerShell)
+```
+
 3. 用你自己的代码替换示例 `Calculator` 类。
 4. 更新 `Directory.Build.props` 中的包元数据。
 5. 在 GitHub Settings 中配置 `release` environment（参见[发版指南](../contributing/releasing.md)）。