diff --git a/content/site/guide/getting-started.md b/content/site/guide/getting-started.md
index 5a37f6e..c2f0467 100644
--- a/content/site/guide/getting-started.md
+++ b/content/site/guide/getting-started.md
@@ -1,18 +1,126 @@
 # Getting started
 
-The fastest way to use Stack is the browser [Playground](https://stack-diagram.com/). It runs the formatter, validator, layout engine, and SVG renderer locally in WebAssembly; you do not need to install a command or send source to a rendering API.
+Choose one installer, then create your first SVG below. Prefer working in your terminal or with a [coding agent](./coding-agents)? Use the CLI. Want to try Stack without installing anything? Open the [Playground](https://stack-diagram.com/) and follow the browser example further down.
 
-## Install the native CLI
+## Install the CLI
 
-For terminal workflows and local automation, install the owner-maintained Homebrew formula with `brew install stack-sh/tap/stack`. It uses the canonical Stack CLI {{cliVersion}} release archive and supports Apple Silicon macOS plus glibc-based Linux on arm64 and x86_64 when the host meets Homebrew's current tier-1 requirements. Homebrew owns upgrades through `brew upgrade stack-sh/tap/stack`; uninstalling the formula leaves your Stack configuration and icon store in place. See the [CLI distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation) for the exact platform matrix, direct-install alternative, and recovery policy.
+Stack CLI {{cliVersion}} supports macOS and glibc Linux on arm64 and x86_64. Prebuilt archives require macOS 13 or glibc 2.31 or newer; Windows and Alpine/musl are not supported. Choose one installer so different copies do not compete on `PATH`. The [distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix) owns the exact support matrix.
 
-Rust users can install the same CLI from crates.io with a working Rust 1.85 or newer toolchain and native linker:
+### Homebrew
 
-`cargo install stack-diagram-cli --version {{cliVersion}} --locked`
+Use an existing Homebrew installation on Apple Silicon macOS or supported Linux. Homebrew’s own tier-1 host requirements also apply.
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+Use Rust 1.85 or newer with a native linker: Xcode Command Line Tools on macOS, or a C compiler/linker on Linux. Make sure Cargo’s bin directory is on `PATH`. The package is `stack-diagram-cli`; the installed command is `stack`.
+
+```text
+cargo install stack-diagram-cli --version {{cliVersion}} --locked
+```
+
+### Aqua
+
+In a Git repository, save the following as `aqua.yaml`:
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v{{cliVersion}}
+    registry: stack-sh
+```
+
+Save this narrowly scoped policy as `aqua-policy.yaml`, review it, then allow it and install with Aqua:
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+Commit `aqua.yaml`, `aqua-policy.yaml`, and the generated `aqua-checksums.json`. Aqua’s bin directory must be on `PATH`. The registry is pinned to an immutable revision; do not replace it with `main`.
+
+### Direct download
+
+With the [GitHub CLI](https://cli.github.com/) installed and authenticated, run this in a POSIX shell on a supported host. It downloads to a new temporary directory, verifies the checksum and exact tagged publisher identity before extraction, and refuses to replace an existing `~/.local/bin/stack`. The archive is ad-hoc signed on macOS, not notarized. Stop if any verification fails.
+
+```text
+(
+  set -eu
+  version={{cliVersion}}
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Create your first SVG
+
+In a new empty working directory, run:
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+Expected: `stack {{cliVersion}}`, a new `diagram.stack`, no check errors, and a non-empty `diagram.svg`. Open the SVG in a browser or add it to your README. `stack init` protects existing files; use a fresh directory instead of overwriting your work.
 
-This builds the `stack` binary from registry-only dependencies on macOS or glibc Linux, on arm64 or x86_64. Cargo owns upgrades: run the install command with the desired released version; uninstall with `cargo uninstall stack-diagram-cli`. Choose one installer for a given binary location to avoid competing copies on `PATH`; Stack does not update itself. Cargo does not install shell completion or manual files automatically; see the [Cargo installation contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation) for prerequisites and optional shell integration. Aqua users can use the [owner registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md).
+Edit `diagram.stack` to describe your system, then repeat check and render. Format it when needed:
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## Write your first document
 
@@ -92,3 +200,16 @@ If Stack finds a problem, the diagnostic shows its severity, stable code, locati
 - Read [Nodes and groups](../language/nodes-and-groups) to model components and boundaries.
 - Read [Edges and layout](../language/edges-and-layout) for relationships and placement intent.
 - Read [Themes and icons](../language/themes-and-icons) before selecting a visual system or explicit icon.
+
+## Update or uninstall
+
+Stack does not update itself. Use the installer that owns your binary. Configuration and imported icon packs remain in place when the binary is removed.
+
+| Installer | Update | Uninstall |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | Run the Cargo install command above with the desired version. | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | Run `aqua rm -m pl stack-sh,stack-sh/cli` while this configuration is present, then remove `stack-sh/cli` from `aqua.yaml`. Other projects using this package may reinstall it when needed. |
+| Direct download | Verify a new release and replace only your directly installed binary. | Remove only the direct binary you installed (`~/.local/bin/stack`). |
+
+For shell completions, manual pages, and recovery, see [shell integration](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md).
diff --git a/content/site/ja/guide/getting-started.md b/content/site/ja/guide/getting-started.md
index 0d98595..560d407 100644
--- a/content/site/ja/guide/getting-started.md
+++ b/content/site/ja/guide/getting-started.md
@@ -1,18 +1,126 @@
 # はじめる
 
-最短の利用方法はbrowser [Playground](https://stack-diagram.com/)です。Formatter、validator、layout engine、SVG rendererがWebAssemblyとしてlocalで動作するため、commandのinstallやrendering APIへのsource送信は不要です。
+導入方法を1つ選び、このページの手順で最初のSVGを作ります。ターミナルや[coding agent](./coding-agents)で使うならCLIを、インストールせず試すなら[Playground](https://stack-diagram.com/)と下のブラウザー向けの例を使ってください。
 
-## Native CLIをinstallする
+## CLIを導入する
 
-Terminal workflowとlocal automationでは、owner管理のHomebrew formulaを`brew install stack-sh/tap/stack`でinstallします。CanonicalなStack CLI {{cliVersion}} release archiveを使用し、Homebrewの現行Tier 1要件を満たすApple Silicon macOSと、arm64 / x86_64のglibc Linuxをsupportします。UpgradeはHomebrewが`brew upgrade stack-sh/tap/stack`で管理し、formulaをuninstallしてもStackのconfigとicon storeは保持されます。正確なplatform matrix、direct install、recovery policyは[CLI distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)を参照してください。
+Stack CLI {{cliVersion}}はarm64 / x86_64のmacOSとglibc Linuxに対応します。配布バイナリーの要件はmacOS 13以降またはglibc 2.31以降です。WindowsとAlpine/muslは対象外です。`PATH`上で複数のバイナリーが競合しないよう、導入方法を1つ選んでください。正確な対応表は[配布契約](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)が正本です。
 
-Rustを利用している場合は、Rust 1.85以降のtoolchainとnative linkerを用意し、crates.ioから同じCLIをinstallできます。
+### Homebrew
 
-`cargo install stack-diagram-cli --version {{cliVersion}} --locked`
+Apple Silicon macOSまたは対応するLinuxで、導入済みのHomebrewを使います。Homebrew自身のTier 1要件も満たす必要があります。
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+Rust 1.85以降とネイティブリンカーが必要です。macOSではXcode Command Line Tools、LinuxではCコンパイラーとリンカーを用意し、Cargoのbinディレクトリを`PATH`へ追加してください。パッケージ名は`stack-diagram-cli`、コマンド名は`stack`です。
+
+```text
+cargo install stack-diagram-cli --version {{cliVersion}} --locked
+```
+
+### Aqua
+
+Gitリポジトリ内に、次の内容を`aqua.yaml`として保存します。
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v{{cliVersion}}
+    registry: stack-sh
+```
+
+次の限定的なポリシーを`aqua-policy.yaml`として保存し、内容を確認してから許可・インストールします。
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+`aqua.yaml`、`aqua-policy.yaml`、生成された`aqua-checksums.json`をcommitしてください。Aquaのbinディレクトリを`PATH`に追加します。レジストリは不変のrevisionに固定しており、`main`へ置き換えないでください。
+
+### 直接ダウンロード
+
+[GitHub CLI](https://cli.github.com/)を導入・認証済みの対応ホストで、POSIXシェルから実行します。新しい一時ディレクトリへ取得し、チェックサムとタグ付き公開元の認証を検証してから展開します。既存の`~/.local/bin/stack`は置き換えません。macOSの署名はad-hocで、公証はされていません。検証に失敗したら中断してください。
+
+```text
+(
+  set -eu
+  version={{cliVersion}}
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 最初のSVGを作る
+
+新しい空の作業ディレクトリで実行します。
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+`stack {{cliVersion}}`と表示され、`diagram.stack`が作成され、checkがエラーなく終了し、空でない`diagram.svg`ができれば成功です。SVGはブラウザーで開いたりREADMEに貼ったりできます。`stack init`は既存ファイルを保護するため、上書きせず新しいディレクトリを使ってください。
 
-macOSまたはglibc Linuxのarm64 / x86_64で、registry由来の依存だけを使ってbinary `stack`をbuildします。Upgradeは目的の公開versionを指定してinstall commandを実行し、uninstallは`cargo uninstall stack-diagram-cli`です。同じbinaryの配置先には1つのinstallerを選び、`PATH`上の競合を避けてください。Stack自身は自己更新しません。Cargoはshell completionやmanualを自動配置しないため、前提条件と任意のshell連携は[Cargo installation contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)を参照してください。Aquaでは[owner registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)を利用できます。
+`diagram.stack`を自分の構成に書き換え、checkとrenderを繰り返します。整形が必要な場合は次を実行します。
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## 最初のdocumentを書く
 
@@ -92,3 +200,16 @@ Sourceは4つの要素で構成されています。
 - Componentとboundaryは[Nodeとgroup](../language/nodes-and-groups)を参照します。
 - Relationshipと配置intentは[Edgeとlayout](../language/edges-and-layout)を参照します。
 - Visual systemや明示iconを選ぶ前に[Themeとicon](../language/themes-and-icons)を参照します。
+
+## 更新・アンインストール
+
+Stack自身は更新を行いません。導入に使ったツールで管理します。バイナリーを削除しても設定とimport済みicon packは残ります。
+
+| 導入方法 | 更新 | アンインストール |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | 上のCargo導入コマンドで目的のversionを指定します。 | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | この設定がある状態で`aqua rm -m pl stack-sh,stack-sh/cli`を実行し、`aqua.yaml`から`stack-sh/cli`を削除します。他のプロジェクトが必要とする場合は再インストールされます。 |
+| 直接ダウンロード | 新しいreleaseを検証し、直接導入したバイナリーだけを差し替えます。 | 自分で導入したバイナリー（`~/.local/bin/stack`）だけを削除します。 |
+
+補完・man page・復旧手順は[シェル連携](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)、[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。
diff --git a/content/site/ko/guide/getting-started.md b/content/site/ko/guide/getting-started.md
index bd9fbe9..55f3348 100644
--- a/content/site/ko/guide/getting-started.md
+++ b/content/site/ko/guide/getting-started.md
@@ -1,18 +1,126 @@
 # 시작하기
 
-Stack을 가장 빠르게 사용하는 방법은 브라우저 [Playground](https://stack-diagram.com/)입니다. 포매터, 검증기, 레이아웃 엔진, SVG 렌더러가 WebAssembly로 로컬에서 실행되므로 명령 설치나 렌더링 API로의 소스 전송이 필요 없습니다.
+설치 방법 하나를 선택하고 이 페이지의 순서대로 첫 SVG를 만드세요. 터미널이나[coding agent](./coding-agents)에서 작업한다면 CLI를 사용하세요. 설치 없이 시험하려면 [Playground](https://stack-diagram.com/)를 열고 아래 브라우저 예제를 따라 하세요.
 
-## 네이티브 CLI 설치
+## CLI 설치
 
-터미널 워크플로와 로컬 자동화에서는 `brew install stack-sh/tap/stack`으로 Stack이 관리하는 Homebrew formula를 설치합니다. 이 formula는 표준 Stack CLI {{cliVersion}} 릴리스 아카이브를 사용하며, Homebrew의 현재 Tier 1 요구 사항을 충족하는 Apple Silicon macOS와 arm64 / x86_64 glibc Linux를 지원합니다. 업그레이드는 Homebrew가 `brew upgrade stack-sh/tap/stack`으로 관리하며, formula를 제거해도 Stack 설정과 아이콘 저장소는 유지됩니다. 정확한 플랫폼 매트릭스, 직접 설치 방법 및 복구 정책은 [CLI 배포 계약](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)을 참고하세요.
+Stack CLI {{cliVersion}}은 arm64 / x86_64 macOS와 glibc Linux를 지원합니다. 미리 빌드된 파일은 macOS 13 또는 glibc 2.31 이상이 필요하며 Windows와 Alpine/musl은 지원하지 않습니다. 여러 바이너리가 `PATH`에서 충돌하지 않도록 설치 방법 하나를 선택하세요. 정확한 지원 범위는 [배포 계약](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)이 정합니다.
 
-Rust 사용자는 Rust 1.85 이상의 도구 체인과 네이티브 링커를 준비한 뒤 crates.io에서 같은 CLI를 설치할 수 있습니다.
+### Homebrew
 
-`cargo install stack-diagram-cli --version {{cliVersion}} --locked`
+Apple Silicon macOS 또는 지원되는 Linux에서 이미 설치된 Homebrew를 사용하세요. Homebrew 자체의 Tier 1 호스트 요구 사항도 충족해야 합니다.
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+Rust 1.85 이상과 네이티브 링커가 필요합니다. macOS는 Xcode Command Line Tools, Linux는 C 컴파일러와 링커를 준비하세요. Cargo의 bin 디렉터리를 `PATH`에 추가하세요. 패키지 이름은 `stack-diagram-cli`, 설치되는 명령은 `stack`입니다.
+
+```text
+cargo install stack-diagram-cli --version {{cliVersion}} --locked
+```
+
+### Aqua
+
+Git 저장소에서 다음 내용을 `aqua.yaml`로 저장하세요.
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v{{cliVersion}}
+    registry: stack-sh
+```
+
+다음의 제한된 정책을 `aqua-policy.yaml`로 저장하고 검토한 뒤 허용 및 설치하세요.
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+`aqua.yaml`, `aqua-policy.yaml`, 생성된 `aqua-checksums.json`을 commit하세요. Aqua의 bin 디렉터리가 `PATH`에 있어야 합니다. 레지스트리는 불변 revision에 고정되어 있으며 `main`으로 바꾸면 안 됩니다.
+
+### 직접 다운로드
+
+지원되는 호스트에 [GitHub CLI](https://cli.github.com/)를 설치하고 로그인한 뒤 POSIX 셸에서 실행하세요. 새 임시 디렉터리에 다운로드하고 체크섬과 정확한 태그의 게시자 신원을 확인한 후 압축을 풉니다. 기존 `~/.local/bin/stack`은 교체하지 않습니다. macOS 파일은 ad-hoc 서명이며 공증되지 않았습니다. 검증이 실패하면 중단하세요.
+
+```text
+(
+  set -eu
+  version={{cliVersion}}
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 첫 SVG 만들기
+
+새로운 빈 작업 디렉터리에서 실행하세요.
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+`stack {{cliVersion}}`이 표시되고 `diagram.stack`이 생성되며 오류 없이 검사되고 비어 있지 않은 `diagram.svg`가 만들어지면 성공입니다. SVG를 브라우저에서 열거나 README에 넣으세요. `stack init`은 기존 파일을 보호하므로 덮어쓰는 대신 새 디렉터리를 사용하세요.
 
-macOS 또는 glibc Linux의 arm64 / x86_64에서 registry 의존성만으로 `stack` 바이너리를 빌드합니다. 업그레이드는 원하는 공개 버전을 지정해 설치 명령을 다시 실행하고, 제거는 `cargo uninstall stack-diagram-cli`를 사용합니다. 같은 바이너리 위치에는 하나의 설치 방식을 선택해 `PATH` 충돌을 피하세요. Stack은 자체 업데이트하지 않습니다. Cargo는 shell completion이나 매뉴얼 파일을 자동 배치하지 않으므로 사전 조건과 선택적 연동은 [Cargo 설치 계약](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)을 참고하세요. Aqua 사용자는 [공식 관리 registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)를 사용할 수 있습니다.
+`diagram.stack`을 자신의 시스템에 맞게 수정하고 check와render를 반복하세요. 필요할 때 다음 명령으로 포맷하세요.
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## 첫 문서 작성
 
@@ -92,3 +200,16 @@ diagram "Checkout" {
 - 컴포넌트와 경계는 [노드와 그룹](../language/nodes-and-groups)을 참고하세요.
 - 관계와 배치 의도는 [엣지와 레이아웃](../language/edges-and-layout)을 참고하세요.
 - 시각 시스템이나 명시적 아이콘을 고르기 전에 [테마와 아이콘](../language/themes-and-icons)을 읽으세요.
+
+## 업데이트 또는 제거
+
+Stack은 스스로 업데이트하지 않습니다. 바이너리를 설치한 도구로 관리하세요. 바이너리를 제거해도 설정과 가져온 아이콘 팩은 유지됩니다.
+
+| 설치 방법 | 업데이트 | 제거 |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | 원하는 버전으로 위 Cargo 설치 명령을 다시 실행하세요. | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 이 설정이 있는 상태에서 `aqua rm -m pl stack-sh,stack-sh/cli`를 실행하고 `aqua.yaml`에서 `stack-sh/cli`를 제거하세요. 다른 프로젝트에서 필요하면 다시 설치될 수 있습니다. |
+| 직접 다운로드 | 새release를 검증한 뒤 직접 설치한 바이너리만 교체하세요. | 직접 설치한 바이너리(`~/.local/bin/stack`)만 제거하세요. |
+
+자동 완성, man 페이지, 복구 절차는 [셸 통합](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [안전한 업데이트](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), [공급망 검증](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)을 참고하세요.
diff --git a/content/site/zh/guide/getting-started.md b/content/site/zh/guide/getting-started.md
index 2901295..d7fb8b7 100644
--- a/content/site/zh/guide/getting-started.md
+++ b/content/site/zh/guide/getting-started.md
@@ -1,18 +1,126 @@
 # 快速开始
 
-使用 Stack 最快的方法是浏览器 [Playground](https://stack-diagram.com/)。格式化器、验证器、布局引擎和 SVG 渲染器都通过 WebAssembly 在本地运行；无需安装命令，也不会把源文件发送到渲染 API。
+选择一种安装方式，按本页步骤生成第一个SVG。在终端或[coding agent](./coding-agents)中工作时使用CLI；无需安装即可体验的方式是打开[Playground](https://stack-diagram.com/)，并使用下方的浏览器示例。
 
-## 安装原生 CLI
+## 安装CLI
 
-对于终端工作流和本地自动化，请使用 `brew install stack-sh/tap/stack` 安装由 Stack 维护的 Homebrew formula。它使用规范的 Stack CLI {{cliVersion}} 发布归档，并支持符合 Homebrew 当前 Tier 1 要求的 Apple Silicon macOS，以及 arm64 / x86_64 的 glibc Linux。Homebrew 通过 `brew upgrade stack-sh/tap/stack` 管理升级；卸载 formula 不会删除 Stack 配置和图标存储。有关准确的平台矩阵、直接安装方式和恢复策略，请参阅 [CLI 分发约定](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)。
+Stack CLI {{cliVersion}}支持arm64 / x86_64的macOS和glibc Linux。预编译文件需要macOS 13或glibc 2.31及以上；不支持Windows和Alpine/musl。请选择一种安装方式，避免多个二进制文件在`PATH`中冲突。准确的支持范围以[分发契约](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)为准。
 
-Rust 用户也可以使用 Rust 1.85 或更高版本的工具链及原生链接器，从 crates.io 安装同一个 CLI：
+### Homebrew
 
-`cargo install stack-diagram-cli --version {{cliVersion}} --locked`
+在Apple Silicon macOS或受支持的Linux上使用已安装的Homebrew。主机还必须满足Homebrew自身的Tier 1要求。
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+需要Rust 1.85及以上和本地链接器：macOS使用Xcode Command Line Tools，Linux使用C编译器和链接器。将Cargo的bin目录加入`PATH`。包名为`stack-diagram-cli`，安装后的命令为`stack`。
+
+```text
+cargo install stack-diagram-cli --version {{cliVersion}} --locked
+```
+
+### Aqua
+
+在Git仓库中，将以下内容保存为`aqua.yaml`：
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v{{cliVersion}}
+    registry: stack-sh
+```
+
+将以下限定范围的策略保存为`aqua-policy.yaml`，审阅后允许该策略并安装：
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+提交`aqua.yaml`、`aqua-policy.yaml`和生成的`aqua-checksums.json`。确保Aqua的bin目录在`PATH`中。注册表固定到不可变revision，请勿改成`main`。
+
+### 直接下载
+
+在受支持的主机上安装并登录[GitHub CLI](https://cli.github.com/)，然后在POSIX shell中执行。此流程下载到新的临时目录，验证校验和与确切标签的发布者身份后才解压，并拒绝替换已有的`~/.local/bin/stack`。macOS文件使用ad-hoc签名，未经公证。任何验证失败时都应停止。
+
+```text
+(
+  set -eu
+  version={{cliVersion}}
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 生成第一个SVG
+
+在新的空工作目录中执行：
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+预期结果：显示`stack {{cliVersion}}`、生成`diagram.stack`、检查无错误，并生成非空的`diagram.svg`。用浏览器打开SVG或将其加入README。`stack init`会保护已有文件，请使用新目录而非覆盖原有工作。
 
-在 macOS 或 glibc Linux 的 arm64 / x86_64 上，它仅使用 registry 依赖构建 `stack` 二进制。升级时用目标已发布版本重新运行安装命令；卸载使用 `cargo uninstall stack-diagram-cli`。请为同一个二进制位置选择一种安装方式，避免 `PATH` 冲突；Stack 不会自行更新。Cargo 不会自动安装 shell 补全或手册文件，前提条件和可选集成请参阅 [Cargo 安装约定](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)。Aqua 用户可以使用[官方维护的 registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)。
+修改`diagram.stack`描述自己的系统，再次运行check和render。需要格式化时执行：
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## 编写第一份文档
 
@@ -92,3 +200,16 @@ diagram "Checkout" {
 - [节点与分组](../language/nodes-and-groups)介绍组件和边界建模。
 - [连线与布局](../language/edges-and-layout)介绍关系和布局意图。
 - 选择视觉系统或显式图标前，请阅读[主题与图标](../language/themes-and-icons)。
+
+## 更新或卸载
+
+Stack不会自行更新。请使用安装该二进制文件的工具进行管理。卸载二进制文件不会删除配置和已导入的图标包。
+
+| 安装方式 | 更新 | 卸载 |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | 用所需版本重新运行上面的Cargo安装命令。 | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 保留此配置时运行`aqua rm -m pl stack-sh,stack-sh/cli`，然后从`aqua.yaml`移除`stack-sh/cli`。其他项目需要此包时可能会重新安装。 |
+| 直接下载 | 验证新release后，仅替换直接安装的二进制文件。 | 仅删除自己直接安装的二进制文件（`~/.local/bin/stack`）。 |
+
+补全、man页面与恢复方法见[shell集成](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)和[供应链验证](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)。
diff --git a/generated/manifest.json b/generated/manifest.json
index fa17b38..5edad9e 100644
--- a/generated/manifest.json
+++ b/generated/manifest.json
@@ -24,7 +24,7 @@
     },
     {
       "path": "site/guide/getting-started.md",
-      "sha256": "1162aa9d07c7ac323ef877e0f971cc2a5b47ec5da97e650e0daa571040edb232"
+      "sha256": "a6001affc631efa8e52c37b80eee3d4228f255c934e6564266e7ae613bae9322"
     },
     {
       "path": "site/guide/playground.md",
@@ -52,7 +52,7 @@
     },
     {
       "path": "site/ja/guide/getting-started.md",
-      "sha256": "20546c410668abce3011fe18daed34cc86ab4c317bae8ab19b5b9ee8a7626e4b"
+      "sha256": "10838a254fce97b88a304bd1cdf8940c3f3522fdecb37428cea36cee0b35e978"
     },
     {
       "path": "site/ja/guide/playground.md",
@@ -108,7 +108,7 @@
     },
     {
       "path": "site/ko/guide/getting-started.md",
-      "sha256": "d45714fdb4a3c873e1a26803f6e4505c613e193ee854f89d226f9e4f4c5e8ace"
+      "sha256": "e8c3980411457ed25973fe2075c6d58f22d9c5b17aeadfaecd73d9d4e91f257f"
     },
     {
       "path": "site/ko/guide/playground.md",
@@ -192,7 +192,7 @@
     },
     {
       "path": "site/zh/guide/getting-started.md",
-      "sha256": "b2b851390a21c8534112c3691e9007dd49bd035c6fe7d5181ed43cfd865e075d"
+      "sha256": "0741c92878eeff3b378f229f99ebadcb98689d13f6458644e4523e6b46cf923b"
     },
     {
       "path": "site/zh/guide/playground.md",
diff --git a/generated/site/guide/getting-started.md b/generated/site/guide/getting-started.md
index 2570fd8..ced5fc6 100644
--- a/generated/site/guide/getting-started.md
+++ b/generated/site/guide/getting-started.md
@@ -1,18 +1,126 @@
 # Getting started
 
-The fastest way to use Stack is the browser [Playground](https://stack-diagram.com/). It runs the formatter, validator, layout engine, and SVG renderer locally in WebAssembly; you do not need to install a command or send source to a rendering API.
+Choose one installer, then create your first SVG below. Prefer working in your terminal or with a [coding agent](./coding-agents)? Use the CLI. Want to try Stack without installing anything? Open the [Playground](https://stack-diagram.com/) and follow the browser example further down.
 
-## Install the native CLI
+## Install the CLI
 
-For terminal workflows and local automation, install the owner-maintained Homebrew formula with `brew install stack-sh/tap/stack`. It uses the canonical Stack CLI 0.5.1 release archive and supports Apple Silicon macOS plus glibc-based Linux on arm64 and x86_64 when the host meets Homebrew's current tier-1 requirements. Homebrew owns upgrades through `brew upgrade stack-sh/tap/stack`; uninstalling the formula leaves your Stack configuration and icon store in place. See the [CLI distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation) for the exact platform matrix, direct-install alternative, and recovery policy.
+Stack CLI 0.5.1 supports macOS and glibc Linux on arm64 and x86_64. Prebuilt archives require macOS 13 or glibc 2.31 or newer; Windows and Alpine/musl are not supported. Choose one installer so different copies do not compete on `PATH`. The [distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix) owns the exact support matrix.
 
-Rust users can install the same CLI from crates.io with a working Rust 1.85 or newer toolchain and native linker:
+### Homebrew
 
-`cargo install stack-diagram-cli --version 0.5.1 --locked`
+Use an existing Homebrew installation on Apple Silicon macOS or supported Linux. Homebrew’s own tier-1 host requirements also apply.
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+Use Rust 1.85 or newer with a native linker: Xcode Command Line Tools on macOS, or a C compiler/linker on Linux. Make sure Cargo’s bin directory is on `PATH`. The package is `stack-diagram-cli`; the installed command is `stack`.
+
+```text
+cargo install stack-diagram-cli --version 0.5.1 --locked
+```
+
+### Aqua
+
+In a Git repository, save the following as `aqua.yaml`:
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v0.5.1
+    registry: stack-sh
+```
+
+Save this narrowly scoped policy as `aqua-policy.yaml`, review it, then allow it and install with Aqua:
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+Commit `aqua.yaml`, `aqua-policy.yaml`, and the generated `aqua-checksums.json`. Aqua’s bin directory must be on `PATH`. The registry is pinned to an immutable revision; do not replace it with `main`.
+
+### Direct download
+
+With the [GitHub CLI](https://cli.github.com/) installed and authenticated, run this in a POSIX shell on a supported host. It downloads to a new temporary directory, verifies the checksum and exact tagged publisher identity before extraction, and refuses to replace an existing `~/.local/bin/stack`. The archive is ad-hoc signed on macOS, not notarized. Stop if any verification fails.
+
+```text
+(
+  set -eu
+  version=0.5.1
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Create your first SVG
+
+In a new empty working directory, run:
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+Expected: `stack 0.5.1`, a new `diagram.stack`, no check errors, and a non-empty `diagram.svg`. Open the SVG in a browser or add it to your README. `stack init` protects existing files; use a fresh directory instead of overwriting your work.
 
-This builds the `stack` binary from registry-only dependencies on macOS or glibc Linux, on arm64 or x86_64. Cargo owns upgrades: run the install command with the desired released version; uninstall with `cargo uninstall stack-diagram-cli`. Choose one installer for a given binary location to avoid competing copies on `PATH`; Stack does not update itself. Cargo does not install shell completion or manual files automatically; see the [Cargo installation contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation) for prerequisites and optional shell integration. Aqua users can use the [owner registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md).
+Edit `diagram.stack` to describe your system, then repeat check and render. Format it when needed:
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## Write your first document
 
@@ -92,3 +200,16 @@ If Stack finds a problem, the diagnostic shows its severity, stable code, locati
 - Read [Nodes and groups](../language/nodes-and-groups) to model components and boundaries.
 - Read [Edges and layout](../language/edges-and-layout) for relationships and placement intent.
 - Read [Themes and icons](../language/themes-and-icons) before selecting a visual system or explicit icon.
+
+## Update or uninstall
+
+Stack does not update itself. Use the installer that owns your binary. Configuration and imported icon packs remain in place when the binary is removed.
+
+| Installer | Update | Uninstall |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | Run the Cargo install command above with the desired version. | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | Run `aqua rm -m pl stack-sh,stack-sh/cli` while this configuration is present, then remove `stack-sh/cli` from `aqua.yaml`. Other projects using this package may reinstall it when needed. |
+| Direct download | Verify a new release and replace only your directly installed binary. | Remove only the direct binary you installed (`~/.local/bin/stack`). |
+
+For shell completions, manual pages, and recovery, see [shell integration](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md).
diff --git a/generated/site/ja/guide/getting-started.md b/generated/site/ja/guide/getting-started.md
index 85ac6cc..6dcde83 100644
--- a/generated/site/ja/guide/getting-started.md
+++ b/generated/site/ja/guide/getting-started.md
@@ -1,18 +1,126 @@
 # はじめる
 
-最短の利用方法はbrowser [Playground](https://stack-diagram.com/)です。Formatter、validator、layout engine、SVG rendererがWebAssemblyとしてlocalで動作するため、commandのinstallやrendering APIへのsource送信は不要です。
+導入方法を1つ選び、このページの手順で最初のSVGを作ります。ターミナルや[coding agent](./coding-agents)で使うならCLIを、インストールせず試すなら[Playground](https://stack-diagram.com/)と下のブラウザー向けの例を使ってください。
 
-## Native CLIをinstallする
+## CLIを導入する
 
-Terminal workflowとlocal automationでは、owner管理のHomebrew formulaを`brew install stack-sh/tap/stack`でinstallします。CanonicalなStack CLI 0.5.1 release archiveを使用し、Homebrewの現行Tier 1要件を満たすApple Silicon macOSと、arm64 / x86_64のglibc Linuxをsupportします。UpgradeはHomebrewが`brew upgrade stack-sh/tap/stack`で管理し、formulaをuninstallしてもStackのconfigとicon storeは保持されます。正確なplatform matrix、direct install、recovery policyは[CLI distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)を参照してください。
+Stack CLI 0.5.1はarm64 / x86_64のmacOSとglibc Linuxに対応します。配布バイナリーの要件はmacOS 13以降またはglibc 2.31以降です。WindowsとAlpine/muslは対象外です。`PATH`上で複数のバイナリーが競合しないよう、導入方法を1つ選んでください。正確な対応表は[配布契約](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)が正本です。
 
-Rustを利用している場合は、Rust 1.85以降のtoolchainとnative linkerを用意し、crates.ioから同じCLIをinstallできます。
+### Homebrew
 
-`cargo install stack-diagram-cli --version 0.5.1 --locked`
+Apple Silicon macOSまたは対応するLinuxで、導入済みのHomebrewを使います。Homebrew自身のTier 1要件も満たす必要があります。
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+Rust 1.85以降とネイティブリンカーが必要です。macOSではXcode Command Line Tools、LinuxではCコンパイラーとリンカーを用意し、Cargoのbinディレクトリを`PATH`へ追加してください。パッケージ名は`stack-diagram-cli`、コマンド名は`stack`です。
+
+```text
+cargo install stack-diagram-cli --version 0.5.1 --locked
+```
+
+### Aqua
+
+Gitリポジトリ内に、次の内容を`aqua.yaml`として保存します。
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v0.5.1
+    registry: stack-sh
+```
+
+次の限定的なポリシーを`aqua-policy.yaml`として保存し、内容を確認してから許可・インストールします。
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+`aqua.yaml`、`aqua-policy.yaml`、生成された`aqua-checksums.json`をcommitしてください。Aquaのbinディレクトリを`PATH`に追加します。レジストリは不変のrevisionに固定しており、`main`へ置き換えないでください。
+
+### 直接ダウンロード
+
+[GitHub CLI](https://cli.github.com/)を導入・認証済みの対応ホストで、POSIXシェルから実行します。新しい一時ディレクトリへ取得し、チェックサムとタグ付き公開元の認証を検証してから展開します。既存の`~/.local/bin/stack`は置き換えません。macOSの署名はad-hocで、公証はされていません。検証に失敗したら中断してください。
+
+```text
+(
+  set -eu
+  version=0.5.1
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 最初のSVGを作る
+
+新しい空の作業ディレクトリで実行します。
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+`stack 0.5.1`と表示され、`diagram.stack`が作成され、checkがエラーなく終了し、空でない`diagram.svg`ができれば成功です。SVGはブラウザーで開いたりREADMEに貼ったりできます。`stack init`は既存ファイルを保護するため、上書きせず新しいディレクトリを使ってください。
 
-macOSまたはglibc Linuxのarm64 / x86_64で、registry由来の依存だけを使ってbinary `stack`をbuildします。Upgradeは目的の公開versionを指定してinstall commandを実行し、uninstallは`cargo uninstall stack-diagram-cli`です。同じbinaryの配置先には1つのinstallerを選び、`PATH`上の競合を避けてください。Stack自身は自己更新しません。Cargoはshell completionやmanualを自動配置しないため、前提条件と任意のshell連携は[Cargo installation contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)を参照してください。Aquaでは[owner registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)を利用できます。
+`diagram.stack`を自分の構成に書き換え、checkとrenderを繰り返します。整形が必要な場合は次を実行します。
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## 最初のdocumentを書く
 
@@ -92,3 +200,16 @@ Sourceは4つの要素で構成されています。
 - Componentとboundaryは[Nodeとgroup](../language/nodes-and-groups)を参照します。
 - Relationshipと配置intentは[Edgeとlayout](../language/edges-and-layout)を参照します。
 - Visual systemや明示iconを選ぶ前に[Themeとicon](../language/themes-and-icons)を参照します。
+
+## 更新・アンインストール
+
+Stack自身は更新を行いません。導入に使ったツールで管理します。バイナリーを削除しても設定とimport済みicon packは残ります。
+
+| 導入方法 | 更新 | アンインストール |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | 上のCargo導入コマンドで目的のversionを指定します。 | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | この設定がある状態で`aqua rm -m pl stack-sh,stack-sh/cli`を実行し、`aqua.yaml`から`stack-sh/cli`を削除します。他のプロジェクトが必要とする場合は再インストールされます。 |
+| 直接ダウンロード | 新しいreleaseを検証し、直接導入したバイナリーだけを差し替えます。 | 自分で導入したバイナリー（`~/.local/bin/stack`）だけを削除します。 |
+
+補完・man page・復旧手順は[シェル連携](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)、[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。
diff --git a/generated/site/ko/guide/getting-started.md b/generated/site/ko/guide/getting-started.md
index ea9085e..9683686 100644
--- a/generated/site/ko/guide/getting-started.md
+++ b/generated/site/ko/guide/getting-started.md
@@ -1,18 +1,126 @@
 # 시작하기
 
-Stack을 가장 빠르게 사용하는 방법은 브라우저 [Playground](https://stack-diagram.com/)입니다. 포매터, 검증기, 레이아웃 엔진, SVG 렌더러가 WebAssembly로 로컬에서 실행되므로 명령 설치나 렌더링 API로의 소스 전송이 필요 없습니다.
+설치 방법 하나를 선택하고 이 페이지의 순서대로 첫 SVG를 만드세요. 터미널이나[coding agent](./coding-agents)에서 작업한다면 CLI를 사용하세요. 설치 없이 시험하려면 [Playground](https://stack-diagram.com/)를 열고 아래 브라우저 예제를 따라 하세요.
 
-## 네이티브 CLI 설치
+## CLI 설치
 
-터미널 워크플로와 로컬 자동화에서는 `brew install stack-sh/tap/stack`으로 Stack이 관리하는 Homebrew formula를 설치합니다. 이 formula는 표준 Stack CLI 0.5.1 릴리스 아카이브를 사용하며, Homebrew의 현재 Tier 1 요구 사항을 충족하는 Apple Silicon macOS와 arm64 / x86_64 glibc Linux를 지원합니다. 업그레이드는 Homebrew가 `brew upgrade stack-sh/tap/stack`으로 관리하며, formula를 제거해도 Stack 설정과 아이콘 저장소는 유지됩니다. 정확한 플랫폼 매트릭스, 직접 설치 방법 및 복구 정책은 [CLI 배포 계약](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)을 참고하세요.
+Stack CLI 0.5.1은 arm64 / x86_64 macOS와 glibc Linux를 지원합니다. 미리 빌드된 파일은 macOS 13 또는 glibc 2.31 이상이 필요하며 Windows와 Alpine/musl은 지원하지 않습니다. 여러 바이너리가 `PATH`에서 충돌하지 않도록 설치 방법 하나를 선택하세요. 정확한 지원 범위는 [배포 계약](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)이 정합니다.
 
-Rust 사용자는 Rust 1.85 이상의 도구 체인과 네이티브 링커를 준비한 뒤 crates.io에서 같은 CLI를 설치할 수 있습니다.
+### Homebrew
 
-`cargo install stack-diagram-cli --version 0.5.1 --locked`
+Apple Silicon macOS 또는 지원되는 Linux에서 이미 설치된 Homebrew를 사용하세요. Homebrew 자체의 Tier 1 호스트 요구 사항도 충족해야 합니다.
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+Rust 1.85 이상과 네이티브 링커가 필요합니다. macOS는 Xcode Command Line Tools, Linux는 C 컴파일러와 링커를 준비하세요. Cargo의 bin 디렉터리를 `PATH`에 추가하세요. 패키지 이름은 `stack-diagram-cli`, 설치되는 명령은 `stack`입니다.
+
+```text
+cargo install stack-diagram-cli --version 0.5.1 --locked
+```
+
+### Aqua
+
+Git 저장소에서 다음 내용을 `aqua.yaml`로 저장하세요.
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v0.5.1
+    registry: stack-sh
+```
+
+다음의 제한된 정책을 `aqua-policy.yaml`로 저장하고 검토한 뒤 허용 및 설치하세요.
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+`aqua.yaml`, `aqua-policy.yaml`, 생성된 `aqua-checksums.json`을 commit하세요. Aqua의 bin 디렉터리가 `PATH`에 있어야 합니다. 레지스트리는 불변 revision에 고정되어 있으며 `main`으로 바꾸면 안 됩니다.
+
+### 직접 다운로드
+
+지원되는 호스트에 [GitHub CLI](https://cli.github.com/)를 설치하고 로그인한 뒤 POSIX 셸에서 실행하세요. 새 임시 디렉터리에 다운로드하고 체크섬과 정확한 태그의 게시자 신원을 확인한 후 압축을 풉니다. 기존 `~/.local/bin/stack`은 교체하지 않습니다. macOS 파일은 ad-hoc 서명이며 공증되지 않았습니다. 검증이 실패하면 중단하세요.
+
+```text
+(
+  set -eu
+  version=0.5.1
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 첫 SVG 만들기
+
+새로운 빈 작업 디렉터리에서 실행하세요.
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+`stack 0.5.1`이 표시되고 `diagram.stack`이 생성되며 오류 없이 검사되고 비어 있지 않은 `diagram.svg`가 만들어지면 성공입니다. SVG를 브라우저에서 열거나 README에 넣으세요. `stack init`은 기존 파일을 보호하므로 덮어쓰는 대신 새 디렉터리를 사용하세요.
 
-macOS 또는 glibc Linux의 arm64 / x86_64에서 registry 의존성만으로 `stack` 바이너리를 빌드합니다. 업그레이드는 원하는 공개 버전을 지정해 설치 명령을 다시 실행하고, 제거는 `cargo uninstall stack-diagram-cli`를 사용합니다. 같은 바이너리 위치에는 하나의 설치 방식을 선택해 `PATH` 충돌을 피하세요. Stack은 자체 업데이트하지 않습니다. Cargo는 shell completion이나 매뉴얼 파일을 자동 배치하지 않으므로 사전 조건과 선택적 연동은 [Cargo 설치 계약](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)을 참고하세요. Aqua 사용자는 [공식 관리 registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)를 사용할 수 있습니다.
+`diagram.stack`을 자신의 시스템에 맞게 수정하고 check와render를 반복하세요. 필요할 때 다음 명령으로 포맷하세요.
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## 첫 문서 작성
 
@@ -92,3 +200,16 @@ diagram "Checkout" {
 - 컴포넌트와 경계는 [노드와 그룹](../language/nodes-and-groups)을 참고하세요.
 - 관계와 배치 의도는 [엣지와 레이아웃](../language/edges-and-layout)을 참고하세요.
 - 시각 시스템이나 명시적 아이콘을 고르기 전에 [테마와 아이콘](../language/themes-and-icons)을 읽으세요.
+
+## 업데이트 또는 제거
+
+Stack은 스스로 업데이트하지 않습니다. 바이너리를 설치한 도구로 관리하세요. 바이너리를 제거해도 설정과 가져온 아이콘 팩은 유지됩니다.
+
+| 설치 방법 | 업데이트 | 제거 |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | 원하는 버전으로 위 Cargo 설치 명령을 다시 실행하세요. | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 이 설정이 있는 상태에서 `aqua rm -m pl stack-sh,stack-sh/cli`를 실행하고 `aqua.yaml`에서 `stack-sh/cli`를 제거하세요. 다른 프로젝트에서 필요하면 다시 설치될 수 있습니다. |
+| 직접 다운로드 | 새release를 검증한 뒤 직접 설치한 바이너리만 교체하세요. | 직접 설치한 바이너리(`~/.local/bin/stack`)만 제거하세요. |
+
+자동 완성, man 페이지, 복구 절차는 [셸 통합](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [안전한 업데이트](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), [공급망 검증](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)을 참고하세요.
diff --git a/generated/site/zh/guide/getting-started.md b/generated/site/zh/guide/getting-started.md
index 9f48dda..fd31c8d 100644
--- a/generated/site/zh/guide/getting-started.md
+++ b/generated/site/zh/guide/getting-started.md
@@ -1,18 +1,126 @@
 # 快速开始
 
-使用 Stack 最快的方法是浏览器 [Playground](https://stack-diagram.com/)。格式化器、验证器、布局引擎和 SVG 渲染器都通过 WebAssembly 在本地运行；无需安装命令，也不会把源文件发送到渲染 API。
+选择一种安装方式，按本页步骤生成第一个SVG。在终端或[coding agent](./coding-agents)中工作时使用CLI；无需安装即可体验的方式是打开[Playground](https://stack-diagram.com/)，并使用下方的浏览器示例。
 
-## 安装原生 CLI
+## 安装CLI
 
-对于终端工作流和本地自动化，请使用 `brew install stack-sh/tap/stack` 安装由 Stack 维护的 Homebrew formula。它使用规范的 Stack CLI 0.5.1 发布归档，并支持符合 Homebrew 当前 Tier 1 要求的 Apple Silicon macOS，以及 arm64 / x86_64 的 glibc Linux。Homebrew 通过 `brew upgrade stack-sh/tap/stack` 管理升级；卸载 formula 不会删除 Stack 配置和图标存储。有关准确的平台矩阵、直接安装方式和恢复策略，请参阅 [CLI 分发约定](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)。
+Stack CLI 0.5.1支持arm64 / x86_64的macOS和glibc Linux。预编译文件需要macOS 13或glibc 2.31及以上；不支持Windows和Alpine/musl。请选择一种安装方式，避免多个二进制文件在`PATH`中冲突。准确的支持范围以[分发契约](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)为准。
 
-Rust 用户也可以使用 Rust 1.85 或更高版本的工具链及原生链接器，从 crates.io 安装同一个 CLI：
+### Homebrew
 
-`cargo install stack-diagram-cli --version 0.5.1 --locked`
+在Apple Silicon macOS或受支持的Linux上使用已安装的Homebrew。主机还必须满足Homebrew自身的Tier 1要求。
 
-`stack --version`
+```text
+brew install stack-sh/tap/stack
+```
+
+### Cargo
+
+需要Rust 1.85及以上和本地链接器：macOS使用Xcode Command Line Tools，Linux使用C编译器和链接器。将Cargo的bin目录加入`PATH`。包名为`stack-diagram-cli`，安装后的命令为`stack`。
+
+```text
+cargo install stack-diagram-cli --version 0.5.1 --locked
+```
+
+### Aqua
+
+在Git仓库中，将以下内容保存为`aqua.yaml`：
+
+```yaml
+checksum:
+  enabled: true
+  require_checksum: true
+  supported_envs:
+    - all
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 42702cda91a4156901b9a601bd143c43dcf05766
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli@v0.5.1
+    registry: stack-sh
+```
+
+将以下限定范围的策略保存为`aqua-policy.yaml`，审阅后允许该策略并安装：
+
+```yaml
+registries:
+  - name: stack-sh
+    type: github_content
+    repo_owner: stack-sh
+    repo_name: cli
+    ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
+    path: aqua/registry.yaml
+packages:
+  - name: stack-sh/cli
+    registry: stack-sh
+    version: semver(">= 0.3.0")
+```
+
+```text
+aqua policy allow
+aqua update-checksum
+aqua install
+```
+
+提交`aqua.yaml`、`aqua-policy.yaml`和生成的`aqua-checksums.json`。确保Aqua的bin目录在`PATH`中。注册表固定到不可变revision，请勿改成`main`。
+
+### 直接下载
+
+在受支持的主机上安装并登录[GitHub CLI](https://cli.github.com/)，然后在POSIX shell中执行。此流程下载到新的临时目录，验证校验和与确切标签的发布者身份后才解压，并拒绝替换已有的`~/.local/bin/stack`。macOS文件使用ad-hoc签名，未经公证。任何验证失败时都应停止。
+
+```text
+(
+  set -eu
+  version=0.5.1
+  case "$(uname -s)/$(uname -m)" in
+    Darwin/arm64) target=aarch64-apple-darwin ;;
+    Darwin/x86_64) target=x86_64-apple-darwin ;;
+    Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
+    Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
+    *) echo "Unsupported platform" >&2; exit 1 ;;
+  esac
+  archive="stack-v${version}-${target}.tar.gz"
+  download_dir=$(mktemp -d)
+  cd "$download_dir"
+  gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
+  awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum --check archive-checksum.txt
+  else
+    shasum -a 256 --check archive-checksum.txt
+  fi
+  gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
+  tar -xzf "$archive"
+  mkdir -p "$HOME/.local/bin"
+  test ! -e "$HOME/.local/bin/stack"
+  install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
+)
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 生成第一个SVG
+
+在新的空工作目录中执行：
+
+```sh
+$ stack --version
+$ stack init
+$ stack check diagram.stack
+$ stack render diagram.stack -o diagram.svg
+```
+
+预期结果：显示`stack 0.5.1`、生成`diagram.stack`、检查无错误，并生成非空的`diagram.svg`。用浏览器打开SVG或将其加入README。`stack init`会保护已有文件，请使用新目录而非覆盖原有工作。
 
-在 macOS 或 glibc Linux 的 arm64 / x86_64 上，它仅使用 registry 依赖构建 `stack` 二进制。升级时用目标已发布版本重新运行安装命令；卸载使用 `cargo uninstall stack-diagram-cli`。请为同一个二进制位置选择一种安装方式，避免 `PATH` 冲突；Stack 不会自行更新。Cargo 不会自动安装 shell 补全或手册文件，前提条件和可选集成请参阅 [Cargo 安装约定](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)。Aqua 用户可以使用[官方维护的 registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)。
+修改`diagram.stack`描述自己的系统，再次运行check和render。需要格式化时执行：
+
+```sh
+$ stack fmt diagram.stack
+$ stack fmt --check diagram.stack
+```
 
 ## 编写第一份文档
 
@@ -92,3 +200,16 @@ diagram "Checkout" {
 - [节点与分组](../language/nodes-and-groups)介绍组件和边界建模。
 - [连线与布局](../language/edges-and-layout)介绍关系和布局意图。
 - 选择视觉系统或显式图标前，请阅读[主题与图标](../language/themes-and-icons)。
+
+## 更新或卸载
+
+Stack不会自行更新。请使用安装该二进制文件的工具进行管理。卸载二进制文件不会删除配置和已导入的图标包。
+
+| 安装方式 | 更新 | 卸载 |
+| --- | --- | --- |
+| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
+| Cargo | 用所需版本重新运行上面的Cargo安装命令。 | `cargo uninstall stack-diagram-cli` |
+| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 保留此配置时运行`aqua rm -m pl stack-sh,stack-sh/cli`，然后从`aqua.yaml`移除`stack-sh/cli`。其他项目需要此包时可能会重新安装。 |
+| 直接下载 | 验证新release后，仅替换直接安装的二进制文件。 | 仅删除自己直接安装的二进制文件（`~/.local/bin/stack`）。 |
+
+补全、man页面与恢复方法见[shell集成](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)和[供应链验证](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)。
diff --git a/package.json b/package.json
index 2933fbf..a40a338 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,7 @@
     "generate": "node scripts/generate.mjs",
     "check": "node scripts/generate.mjs --check",
     "test": "node --test scripts/*.test.mjs",
-    "smoke": "node scripts/smoke-skill.mjs"
+    "smoke": "node scripts/smoke-skill.mjs && node scripts/first-render.mjs"
   },
   "devDependencies": {
     "@stack-sh/engine": "0.7.0",
diff --git a/scripts/first-render.mjs b/scripts/first-render.mjs
new file mode 100644
index 0000000..3cc2f4b
--- /dev/null
+++ b/scripts/first-render.mjs
@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+const root = fileURLToPath(new URL('../', import.meta.url));
+export const expectedCommands = [
+  'stack --version',
+  'stack init',
+  'stack check diagram.stack',
+  'stack render diagram.stack -o diagram.svg',
+  'stack fmt diagram.stack',
+  'stack fmt --check diagram.stack',
+];
+
+export function walkthroughCommands(source) {
+  const commands = [...source.matchAll(/```sh\n([\s\S]*?)```/g)]
+    .flatMap(match => match[1].trim().split('\n'))
+    .map(line => {
+      assert.ok(line.startsWith('$ '), 'CLI examples need a copyable prompt');
+      return line.slice(2);
+    });
+  // Execute only the documented local walkthrough, never installer or shell text.
+  assert.deepEqual(commands, expectedCommands, 'First-render command contract drift');
+  return commands;
+}
+
+export async function verifyWalkthrough(binary, directory = root) {
+  assert.ok(binary && path.isAbsolute(binary), 'STACK_CLI_BIN must be an absolute path');
+  const release = JSON.parse(await readFile(path.join(directory, 'content/cli-release.json'), 'utf8'));
+  for (const locale of ['', 'ja/', 'zh/', 'ko/']) {
+    const source = await readFile(path.join(directory, `generated/site/${locale}guide/getting-started.md`), 'utf8');
+    const commands = walkthroughCommands(source);
+    const temporary = await mkdtemp(path.join(os.tmpdir(), 'stack-first-render-'));
+    try {
+      const env = { ...process.env, XDG_CONFIG_HOME: path.join(temporary, 'config'), XDG_DATA_HOME: path.join(temporary, 'data'), XDG_CACHE_HOME: path.join(temporary, 'cache') };
+      for (const command of commands) {
+        const [, ...args] = command.split(' ');
+        const result = await execute(binary, args, { cwd: temporary, env, timeout: 30_000 });
+        if (args[0] === '--version') assert.equal(result.stdout, `stack ${release.version}\n`);
+        assert.doesNotMatch(result.stderr, /error\[/, command);
+      }
+      const svg = await readFile(path.join(temporary, 'diagram.svg'), 'utf8');
+      assert.match(svg, /<svg\b/);
+      assert.match(svg, /<\/svg>/);
+      assert.doesNotMatch(svg, /<script\b|<foreignObject\b|\son\w+=/i);
+      console.log(`Verified ${locale || 'en/'}first render against published CLI ${release.version}.`);
+    } finally {
+      await rm(temporary, { recursive: true, force: true });
+    }
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await verifyWalkthrough(process.env.STACK_CLI_BIN);
+}
diff --git a/scripts/first-render.test.mjs b/scripts/first-render.test.mjs
new file mode 100644
index 0000000..4d37d04
--- /dev/null
+++ b/scripts/first-render.test.mjs
@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import test from 'node:test';
+import { expectedCommands, walkthroughCommands } from './first-render.mjs';
+
+const fixture = '```sh\n' + expectedCommands.map(command => '$ ' + command).join('\n') + '\n```';
+
+test('walkthrough reads the actual CLI examples and rejects missing or unsafe commands', () => {
+  assert.deepEqual(walkthroughCommands(fixture), expectedCommands);
+  assert.throws(() => walkthroughCommands(fixture.replace('$ stack init\n', '')), /contract drift/);
+  assert.throws(() => walkthroughCommands(fixture.replace('stack init', 'stack init --force')), /contract drift/);
+  assert.throws(() => walkthroughCommands(fixture.replace('stack init', 'stack init; curl example.com')), /contract drift/);
+});
+
+test('all locales keep identical installer blocks and a complete first-render walkthrough', async () => {
+  const blocks = source => [...source.matchAll(/```(text|yaml|sh)\n([\s\S]*?)```/g)].map(match => [match[1], match[2]]);
+  const english = await readFile(new URL('../content/site/guide/getting-started.md', import.meta.url), 'utf8');
+  assert.deepEqual(walkthroughCommands(english), expectedCommands);
+  assert.match(english, /cargo install stack-diagram-cli --version \{\{cliVersion\}\} --locked/);
+  assert.match(english, /--source-ref "refs\/tags\/v\$version" --deny-self-hosted-runners/);
+  assert.match(english, /test ! -e "\$HOME\/\.local\/bin\/stack"/);
+  for (const locale of ['ja', 'zh', 'ko']) {
+    const translated = await readFile(new URL(`../content/site/${locale}/guide/getting-started.md`, import.meta.url), 'utf8');
+    assert.deepEqual(blocks(translated), blocks(english), `${locale} installer or command drift`);
+  }
+});