docs: prepare installer repository for public release

.github/CODEOWNERS

@@ -1,2 +1 @@
 * @cloudsmith-io/engineering
-BartoszBlizniak

.github/ISSUE_TEMPLATE/bug_report.md

@@ -27,5 +27,13 @@ labels: bug
 
 - **OS**: <!-- e.g., macOS 14.0, Ubuntu 22.04, Alpine 3.20, Windows 11 -->
 - **Script**: <!-- install.sh or install.ps1, and its release version -->
+- **CLI version requested**: <!-- e.g., latest or 1.19.0 -->
 - **Shell**: <!-- e.g., bash 5.2, dash, PowerShell 7.4, Windows PowerShell 5.1 -->
 - **CI system (if any)**: <!-- e.g., GitHub Actions, CircleCI, Azure DevOps -->
+
+## Additional Context
+
+<!--
+Include the exact command with secrets removed and any relevant stderr output.
+Do not include Cloudsmith API keys, tokens, credentials, or private URLs.
+-->

.github/ISSUE_TEMPLATE/config.yml

@@ -7,5 +7,5 @@ contact_links:
     url: https://docs.cloudsmith.com/developer-tools/cli
     about: Check the official Cloudsmith CLI documentation
   - name: Cloudsmith Support
-    url: https://cloudsmith.io/support/
+    url: https://support.cloudsmith.com/hc/en-us/requests/new
     about: Contact Cloudsmith support for account-specific issues

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,8 @@
-# Description
+## Summary
 
-<!-- Provide a brief description of the changes in this PR -->
+<!-- What changed, and why? -->
 
-## Type of Change
+## Type of change
 
 - [ ] Bug fix
 - [ ] New feature
@@ -11,6 +11,21 @@
 - [ ] Refactoring
 - [ ] Other (please describe)
 
-## Additional Notes
+## Validation
 
-<!-- Any additional context or screenshots -->
+<!-- List the commands or checks you ran and their results. -->
+
+## Compatibility
+
+<!--
+Describe any effect on supported targets, options, environment variables,
+installation paths, or the four-line output contract. Write "None" if there
+is no compatibility impact.
+-->
+
+## Checklist
+
+- [ ] I have added or updated tests where appropriate.
+- [ ] I have updated documentation and `CHANGELOG.md` where appropriate.
+- [ ] I have not included credentials, tokens, or other sensitive data.
+- [ ] I have called out any breaking change explicitly.

.github/workflows/release.yml

@@ -108,13 +108,12 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # TODO confirm vendor path with each integration's maintainers.
           - repo: cloudsmith-io/cloudsmith-cli-action
-            vendor_path: scripts/vendor/
+            integration: github-action
           - repo: cloudsmith-io/orb
-            vendor_path: scripts/vendor/
+            integration: circleci-orb
           - repo: cloudsmith-io/cloudsmith-ado-integration
-            vendor_path: scripts/vendor/
+            integration: azure-devops
     steps:
       - name: Checkout installer repo
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
@@ -129,33 +128,75 @@ jobs:
           set -eu
           git clone --depth 1 "https://x-access-token:${VENDOR_TOKEN}@github.com/${TARGET_REPO}.git" target-repo
 
-      - name: Vendor scripts with provenance header
+      - name: Vendor release assets
         env:
+          INTEGRATION: ${{ matrix.integration }}
           TAG: ${{ github.ref_name }}
-          SOURCE_REPO: ${{ github.repository }}
-          VENDOR_PATH: ${{ matrix.vendor_path }}
         run: |
           set -eu
-          mkdir -p "target-repo/${VENDOR_PATH}"
-          for f in install.sh install.ps1; do
-            sha="$(sha256sum "$f" | awk '{print $1}')"
-            first_line="$(head -n1 "$f")"
-            dest="target-repo/${VENDOR_PATH}${f}"
-            {
-              case "$first_line" in
-                '#!'*) printf '%s\n' "$first_line" ;;
-              esac
-              printf '# Vendored from %s\n' "$SOURCE_REPO"
-              printf '# Source tag: %s\n' "$TAG"
-              printf '# Source commit: %s\n' "$GITHUB_SHA"
-              printf '# SHA-256 (pre-vendoring): %s\n' "$sha"
-              printf '# Do not edit directly; update via the source repository and re-vendor.\n'
-              case "$first_line" in
-                '#!'*) tail -n +2 "$f" ;;
-                *) cat "$f" ;;
-              esac
-            } > "$dest"
-          done
+          case "$INTEGRATION" in
+            github-action)
+              destination="target-repo/installer"
+              mkdir -p "$destination"
+              cp install.sh install.ps1 "$destination/"
+              printf '%s\n' "$TAG" > "$destination/VERSION"
+              (
+                cd "$destination"
+                sha256sum install.sh install.ps1 > SHA256SUMS
+              )
+              ;;
+            circleci-orb)
+              destination="target-repo/src/scripts"
+              mkdir -p "$destination"
+              cp install.sh "$destination/install.sh"
+              sha="$(sha256sum install.sh | awk '{print $1}')"
+              printf 'version=%s\nsha256=%s\n' "$TAG" "$sha" \
+                > "$destination/install.sh.version"
+              ;;
+            azure-devops)
+              destination="target-repo/cloudsmith-task/installer"
+              mkdir -p "$destination"
+              cp install.sh install.ps1 "$destination/"
+              printf '%s\n' "$TAG" > "$destination/VERSION"
+              ;;
+            *)
+              echo "unsupported integration: $INTEGRATION" >&2
+              exit 1
+              ;;
+          esac
+
+      - name: Verify vendored files
+        env:
+          INTEGRATION: ${{ matrix.integration }}
+        run: |
+          set -eu
+          case "$INTEGRATION" in
+            github-action)
+              destination="target-repo/installer"
+              cmp install.sh "$destination/install.sh"
+              cmp install.ps1 "$destination/install.ps1"
+              test -s "$destination/VERSION"
+              (cd "$destination" && sha256sum -c SHA256SUMS)
+              ;;
+            circleci-orb)
+              destination="target-repo/src/scripts"
+              cmp install.sh "$destination/install.sh"
+              expected="$(awk -F= '$1 == "sha256" {print $2}' "$destination/install.sh.version")"
+              actual="$(sha256sum install.sh | awk '{print $1}')"
+              test -n "$(awk -F= '$1 == "version" {print $2}' "$destination/install.sh.version")"
+              test "$expected" = "$actual"
+              ;;
+            azure-devops)
+              destination="target-repo/cloudsmith-task/installer"
+              cmp install.sh "$destination/install.sh"
+              cmp install.ps1 "$destination/install.ps1"
+              test -s "$destination/VERSION"
+              ;;
+            *)
+              echo "unsupported integration: $INTEGRATION" >&2
+              exit 1
+              ;;
+          esac
 
       - name: Commit and open vendoring PR
         env:

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial `install.sh` and `install.ps1`.
-- CI: lint, cross-platform tests, zizmor scanning, and a tag-triggered
-  release workflow.
+- Cross-platform `install.sh` and `install.ps1` installers for the standalone
+  Cloudsmith CLI.
+- Automatic platform detection and support for selecting a specific CLI
+  version or target.
+- SHA-256 verification, archive safety checks, atomic installation, and
+  concurrent-install locking.
+- Stable machine-readable output for CI/CD consumers.
+- Cross-platform test, security scanning, release, and integration-vendoring
+  workflows.

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thank you for helping improve the Cloudsmith CLI installers. Bug reports,
+documentation improvements, tests, and focused code changes are welcome.
+
+## Before you start
+
+- Search existing issues and pull requests before opening a duplicate.
+- Use the issue templates for bugs, feature requests, and usage questions.
+- Do not open a public issue for a suspected vulnerability. Follow
+  [SECURITY.md](SECURITY.md) instead.
+- Keep changes focused. The installers are vendored by multiple CI/CD
+  integrations, so compatibility and reviewability matter.
+
+## Development setup
+
+Fork and clone the repository, then create a branch from `main`.
+
+The shell suite requires bats-core 1.5 or later and Python 3:
+
+```sh
+bats tests/
+```
+
+Shell changes should also pass the checks used in CI:
+
+```sh
+sh -n install.sh
+shellcheck --shell=sh --severity=style install.sh
+```
+
+The Windows suite requires Pester 5.5 through 5.99:
+
+```powershell
+Install-Module Pester -MinimumVersion 5.5 -MaximumVersion 5.99 -Scope CurrentUser
+Import-Module Pester -MinimumVersion 5.5 -MaximumVersion 5.99
+Invoke-Pester -Path tests/Install.Tests.ps1
+```
+
+See [tests/README.md](tests/README.md) for more detail. Tests use local fixtures
+and do not require access to the public package repository.
+
+## Compatibility expectations
+
+Treat these interfaces as public contracts:
+
+- command-line options and PowerShell parameters
+- `CLOUDSMITH_CLI_*` environment variables
+- supported target identifiers
+- versioned installation layout
+- the four `key=value` output lines
+
+Changes to a public contract need explicit release notes, integration impact
+analysis, and an appropriate semantic-versioning decision. Preserve POSIX `sh`
+compatibility in `install.sh` and Windows PowerShell 5.1 compatibility in
+`install.ps1`.
+
+## Pull requests
+
+- Explain the problem and the chosen solution.
+- Add or update tests for behavior changes.
+- Update `README.md` and `CHANGELOG.md` when user-visible behavior changes.
+- List the validation commands you ran.
+- Keep commits free of credentials, private URLs, generated test artifacts, and
+  unrelated changes.
+
+Maintainers may request additional integration validation before merging a
+change that affects installer behavior or release distribution.