stack-sh · konojunya · Sep 5, 2026 · Sep 5, 2026
diff --git a/README.md b/README.md
@@ -20,6 +20,15 @@ coding-agent guides explain this and share one copyable prompt from
 `content/agent-prompt.txt`. This avoids hand-maintaining the validation workflow
 both in a guide and a skill. `{{cliVersion}}` comes from the release lock.
 
+The English product story lives in `content/product-story.json`; Japanese,
+Chinese, and Korean UI copy lives in `content/product-story-locales.json`, keyed
+by the canonical benefit IDs. `{{productHome}}` generates homepage metadata and
+`{{productBenefits}}` generates the introduction's benefit list. Update those
+sources rather than copying marketing text into page templates. The homepage
+has only `hero.name` as its H1, a separate tagline, and a `description` field
+for page metadata and the website's supporting hero paragraph. The website
+owns rendering that paragraph; no example SVG is generated here.
+
 `generated/site/` contains complete Markdown inputs for the website. Website
 presentation, images, VitePress configuration, and deployment are not owned here.
 

diff --git a/content/product-story-locales.json b/content/product-story-locales.json
@@ -0,0 +1,71 @@
+{
+  "ja": {
+    "hero": {
+      "tagline": "構成を書くだけで、美しい図に。",
+      "description": "サービスとつながりをテキストで記述。Stackが配置とテーマを整え、ターミナルでもブラウザでも共有できるSVGを生成します。",
+      "primaryActionText": "最初の図を作る",
+      "secondaryActionText": "Playgroundで試す",
+      "logoAlt": "Stackロゴ"
+    },
+    "features": {
+      "beautiful-by-default": {
+        "title": "書くだけで、見た目が整う",
+        "details": "箱の位置や色ではなく、システムの構成に集中。自動配置と統一されたテーマで、手作業で整えなくても見やすい図になります。"
+      },
+      "consistent-everywhere": {
+        "title": "どこで作っても、一貫した図に",
+        "details": "Coding agent、ターミナル、ブラウザを行き来しても大丈夫。共通のエンジンが、同じソース・テーマ・アイコンパックから一貫した図を生成します。"
+      },
+      "fast-local-rendering": {
+        "title": "手元で、すばやく描画",
+        "details": "描画サーバーを介さず、書いて、描いて、すぐ見直す。ソースは手元に置いたまま、スクリプトや外部アセットを含まないSVGを書き出せます。"
+      }
+    }
+  },
+  "zh": {
+    "hero": {
+      "tagline": "写下技术架构，得到精美图表。",
+      "description": "用文本描述服务及其连接。Stack负责布局和主题，在终端或浏览器中生成可分享的SVG。",
+      "primaryActionText": "创建第一张图",
+      "secondaryActionText": "试用Playground",
+      "logoAlt": "Stack标志"
+    },
+    "features": {
+      "beautiful-by-default": {
+        "title": "无需手动美化",
+        "details": "专注描述系统，不必逐个调整方框。自动布局和协调的主题让图表保持清晰美观，无需手动定位或设置样式。"
+      },
+      "consistent-everywhere": {
+        "title": "不同工具，一致呈现",
+        "details": "在编程智能体、终端和浏览器之间自由切换。共享引擎让相同源文件、主题和图标包在不同工作流程中保持一致。"
+      },
+      "fast-local-rendering": {
+        "title": "本地快速渲染",
+        "details": "无需渲染服务器，修改后即可再次生成。源文件留在你的设备上，并可导出不含脚本或外部资源的独立SVG。"
+      }
+    }
+  },
+  "ko": {
+    "hero": {
+      "tagline": "구성을 쓰면, 아름다운 다이어그램으로.",
+      "description": "서비스와 연결을 텍스트로 설명하세요. Stack이 배치와 테마를 정리하고, 터미널이나 브라우저에서 공유할 수 있는 SVG를 만듭니다.",
+      "primaryActionText": "첫 다이어그램 만들기",
+      "secondaryActionText": "Playground에서 체험하기",
+      "logoAlt": "Stack 로고"
+    },
+    "features": {
+      "beautiful-by-default": {
+        "title": "직접 꾸미지 않아도 아름답게",
+        "details": "박스 하나하나가 아닌 시스템을 설명하세요. 자동 배치와 조화로운 테마로 위치와 스타일을 수작업으로 조정하지 않아도 정돈된 다이어그램을 만듭니다."
+      },
+      "consistent-everywhere": {
+        "title": "어디서나 일관된 결과",
+        "details": "코딩 에이전트, 터미널, 브라우저를 자유롭게 오가세요. 공유 엔진이 같은 소스, 테마, 아이콘 팩을 다양한 작업 환경에서 일관되게 렌더링합니다."
+      },
+      "fast-local-rendering": {
+        "title": "내 기기에서 빠르게 렌더링",
+        "details": "렌더링 서버 없이 수정하고, 그리고, 다시 확인하세요. 소스를 내 기기에 둔 채 스크립트나 외부 에셋이 없는 독립형 SVG로 내보낼 수 있습니다."
+      }
+    }
+  }
+}
diff --git a/content/site/guide/getting-started.md b/content/site/guide/getting-started.md
@@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack
 
 ## Write your first document
 
-Replace the editor content with this example:
+For the browser path, open the [Playground](https://stack-diagram.com/) and replace its editor content with this example. CLI users can save the same source as `diagram.stack` and repeat the check/render commands above:
 
 ```stack
 stack 1.0
@@ -196,10 +196,10 @@ If Stack finds a problem, the diagnostic shows its severity, stable code, locati
 
 ## Choose what to learn next
 
-- Read [Document and syntax](../language/syntax) for lexical rules and the complete grammar.
-- 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.
+- **Write with your coding agent:** install the optional [Stack skill](./coding-agents) and use the shared check/render workflow.
+- **Find a starting point:** open a [live example](../examples/) in the Playground, then explore [themes and icons](../language/themes-and-icons).
+- **Use your own setup:** [import provider icons](./provider-icons), then choose their local store through the [CLI configuration guide](https://github.com/stack-sh/cli/blob/main/docs/configuration.md). Configuration is a CLI contract; the browser uses explicit local pack import.
+- **Look up the details:** use the [language reference](../language/syntax) and [diagnostics and limits](../reference/diagnostics-and-limits) as you model a larger system.
 
 ## Update or uninstall
 

diff --git a/content/site/guide/what-is-stack.md b/content/site/guide/what-is-stack.md
@@ -31,12 +31,9 @@ The document says that a client calls a service. It does not say where either bo
 
 ## What Stack optimizes for
 
-- **Concise authoring:** useful diagrams need little more than named nodes and edges.
-- **Predictable generation:** each concept has one constrained representation that people and language models can produce reliably.
-- **Semantic source:** a document records topology and intent, not pixels.
-- **Polished output:** the renderer owns a coherent visual system.
-- **Actionable errors:** diagnostics point to source ranges and can include expected values, corrective help, and related declarations.
-- **Safe embedding:** source cannot execute code, fetch arbitrary assets, or inject HTML or SVG.
+{{productBenefits}}
+
+Consistency assumes matching engine versions and the same source, theme, and icon packs. Rendering stays local; installing tools, loading the website, and explicitly importing provider icons can require network access. See [versioning and safety](../reference/versioning-and-safety) for the exact boundaries.
 
 ## What Stack is not
 

diff --git a/content/site/index.md b/content/site/index.md
@@ -1,27 +1,4 @@
 ---
 layout: home
-
-hero:
-  name: Stack
-  text: Architecture, as source.
-  tagline: Write a small, semantic document. Get a consistent, accessible architecture diagram without drawing coordinates or styling every box.
-  image:
-    light: /favicon.svg
-    dark: /favicon.svg
-    alt: Stack logo
-  actions:
-    - theme: brand
-      text: Get started
-      link: /guide/getting-started
-    - theme: alt
-      text: Open Playground
-      link: https://stack-diagram.com/
-
-features:
-  - title: Describe the system
-    details: Nodes, groups, relationships, and layout intent stay readable in a compact .stack file.
-  - title: Keep meaning portable
-    details: A versioned language and structured diagnostics separate architecture meaning from renderer choices.
-  - title: Render safely
-    details: The engine produces standalone SVG without scripts, arbitrary HTML, or network-loaded assets.
+{{productHome}}
 ---
diff --git a/content/site/ja/guide/getting-started.md b/content/site/ja/guide/getting-started.md
@@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack
 
 ## 最初のdocumentを書く
 
-Editorを次のexampleへ置き換えます。
+ブラウザで試す場合は[Playground](https://stack-diagram.com/)を開き、エディタを次の作例に置き換えます。CLIの場合は同じソースを`diagram.stack`として保存し、上の検証・描画コマンドを実行できます。
 
 ```stack
 stack 1.0
@@ -196,10 +196,10 @@ Sourceは4つの要素で構成されています。
 
 ## 次に読むもの
 
-- Lexical ruleと完全なgrammarは[Documentとsyntax](../language/syntax)を参照します。
-- 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)を参照します。
+- **Coding agentと書く:** 任意の[Stackスキル](./coding-agents)を導入し、共通の検証・描画手順を使います。
+- **作例から始める:** [実行時に描画される作例](../examples/)をPlaygroundで開き、[テーマとアイコン](../language/themes-and-icons)を試します。
+- **自分の環境に合わせる:** [プロバイダーアイコンを取り込み](./provider-icons)、[CLI設定ガイド](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)で保存先を選びます。この設定はCLI用です。ブラウザではローカルのパックを明示的に読み込みます。
+- **詳しく調べる:** [言語リファレンス](../language/syntax)と[診断・制限](../reference/diagnostics-and-limits)を参照しながら、より大きなシステムを記述します。
 
 ## 更新・アンインストール
 

diff --git a/content/site/ja/guide/what-is-stack.md b/content/site/ja/guide/what-is-stack.md
@@ -31,12 +31,9 @@ diagram "Service architecture" {
 
 ## Stackが重視すること
 
-- **簡潔なauthoring:** 名前付きnodeとedgeだけで有用なdiagramを書けます。
-- **予測可能な生成:** 人とlanguage modelが同じconceptを安定して記述できます。
-- **Semantic source:** Pixelではなくtopologyとintentを記録します。
-- **整ったoutput:** 一貫したvisual systemをrendererが所有します。
-- **修正可能なerror:** Diagnosticはsource range、expected value、help、related declarationを示せます。
-- **安全な埋め込み:** Sourceはcode実行、任意asset取得、HTML/SVG注入ができません。
+{{productBenefits}}
+
+一貫した結果には、同じエンジンのバージョン・ソース・テーマ・アイコンパックが必要です。描画は手元で行いますが、ツールの導入、サイトの読み込み、明示的なプロバイダーアイコンの取り込みにはネットワークを使う場合があります。詳しい境界は[バージョニングと安全性](../reference/versioning-and-safety)を参照してください。
 
 ## Stackではないもの
 

diff --git a/content/site/ja/index.md b/content/site/ja/index.md
@@ -1,27 +1,4 @@
 ---
 layout: home
-
-hero:
-  name: Stack
-  text: Architectureをsourceとして。
-  tagline: 小さなsemantic documentを書くだけで、座標やboxごとのstyleを指定せず、一貫したaccessibleなarchitecture diagramを生成できます。
-  image:
-    light: /favicon.svg
-    dark: /favicon.svg
-    alt: Stackロゴ
-  actions:
-    - theme: brand
-      text: はじめる
-      link: /ja/guide/getting-started
-    - theme: alt
-      text: Playgroundを開く
-      link: https://stack-diagram.com/
-
-features:
-  - title: Systemを記述する
-    details: Node、group、relationship、layout intentを、簡潔な.stack fileとして読みやすく保ちます。
-  - title: 意味をportableにする
-    details: Version付きlanguageとstructured diagnosticが、architectureの意味をrendererの選択から分離します。
-  - title: 安全にrenderする
-    details: Script、任意HTML、network assetを含まないstandalone SVGをengineが生成します。
+{{productHome}}
 ---
diff --git a/content/site/ko/guide/getting-started.md b/content/site/ko/guide/getting-started.md
@@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack
 
 ## 첫 문서 작성
 
-에디터 내용을 다음 예제로 바꿉니다.
+브라우저에서 체험하려면 [Playground](https://stack-diagram.com/)를 열고 에디터 내용을 다음 예제로 바꾸세요. CLI 사용자는 같은 소스를 `diagram.stack`으로 저장한 뒤 위의 검사·렌더링 명령을 다시 실행할 수 있습니다.
 
 ```stack
 stack 1.0
@@ -196,10 +196,10 @@ diagram "Checkout" {
 
 ## 다음으로 읽을 내용
 
-- 어휘 규칙과 전체 문법은 [문서와 문법](../language/syntax)을 참고하세요.
-- 컴포넌트와 경계는 [노드와 그룹](../language/nodes-and-groups)을 참고하세요.
-- 관계와 배치 의도는 [엣지와 레이아웃](../language/edges-and-layout)을 참고하세요.
-- 시각 시스템이나 명시적 아이콘을 고르기 전에 [테마와 아이콘](../language/themes-and-icons)을 읽으세요.
+- **코딩 에이전트와 작성하기:** 선택 사항인 [Stack 스킬](./coding-agents)을 설치하고 공통 검사·렌더링 흐름을 사용하세요.
+- **예제에서 시작하기:** [실시간 렌더링 예제](../examples/)를 Playground에서 열고 [테마와 아이콘](../language/themes-and-icons)을 살펴보세요.
+- **내 환경에 맞추기:** [공급자 아이콘을 가져온](./provider-icons) 다음 [CLI 설정 가이드](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)에서 로컬 저장소를 선택하세요. 이 설정은 CLI용이며, 브라우저에서는 로컬 팩을 명시적으로 가져옵니다.
+- **세부 사항 찾아보기:** 더 큰 시스템을 모델링할 때 [언어 레퍼런스](../language/syntax)와 [진단과 제한](../reference/diagnostics-and-limits)을 참고하세요.
 
 ## 업데이트 또는 제거
 

diff --git a/content/site/ko/guide/what-is-stack.md b/content/site/ko/guide/what-is-stack.md
@@ -31,12 +31,9 @@ diagram "Service architecture" {
 
 ## Stack의 설계 목표
 
-- **간결한 작성:** 이름이 있는 노드와 엣지만으로 유용한 다이어그램을 만듭니다.
-- **예측 가능한 생성:** 사람과 언어 모델이 같은 개념을 하나의 제한된 방식으로 안정적으로 표현합니다.
-- **의미 기반 소스:** 픽셀이 아니라 토폴로지와 의도를 기록합니다.
-- **정돈된 출력:** 렌더러가 일관된 시각 시스템을 소유합니다.
-- **실행 가능한 오류:** 진단은 소스 범위, 예상 값, 수정 도움말, 관련 선언을 제공할 수 있습니다.
-- **안전한 임베딩:** 소스는 코드를 실행하거나 임의 에셋을 가져오거나 HTML/SVG를 삽입할 수 없습니다.
+{{productBenefits}}
+
+일관된 결과를 얻으려면 엔진 버전, 소스, 테마, 아이콘 팩이 같아야 합니다. 렌더링은 로컬에서 수행되지만 도구 설치, 웹사이트 로딩, 명시적인 공급자 아이콘 가져오기에는 네트워크가 필요할 수 있습니다. 정확한 범위는 [버전과 안전성](../reference/versioning-and-safety)을 참고하세요.
 
 ## Stack이 아닌 것
 

diff --git a/content/site/ko/index.md b/content/site/ko/index.md
@@ -1,27 +1,4 @@
 ---
 layout: home
-
-hero:
-  name: Stack
-  text: 아키텍처를 소스로.
-  tagline: 작은 의미 기반 문서를 작성하면 좌표나 박스별 스타일을 지정하지 않아도 일관되고 접근 가능한 아키텍처 다이어그램을 만들 수 있습니다.
-  image:
-    light: /favicon.svg
-    dark: /favicon.svg
-    alt: Stack 로고
-  actions:
-    - theme: brand
-      text: 시작하기
-      link: /ko/guide/getting-started
-    - theme: alt
-      text: Playground 열기
-      link: https://stack-diagram.com/
-
-features:
-  - title: 시스템 설명
-    details: 노드, 그룹, 관계, 레이아웃 의도를 간결하고 읽기 쉬운 .stack 파일로 유지합니다.
-  - title: 의미의 이식성
-    details: 버전이 있는 언어와 구조화된 진단이 아키텍처 의미를 렌더러 선택과 분리합니다.
-  - title: 안전한 렌더링
-    details: 엔진은 스크립트, 임의 HTML, 네트워크 에셋이 없는 독립형 SVG를 생성합니다.
+{{productHome}}
 ---
diff --git a/content/site/zh/guide/getting-started.md b/content/site/zh/guide/getting-started.md
@@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack
 
 ## 编写第一份文档
 
-将编辑器内容替换为下面的示例：
+在浏览器中试用时，打开[Playground](https://stack-diagram.com/)，将编辑器内容替换为下面的示例。CLI用户可以将相同源文件保存为`diagram.stack`，然后再次执行上面的检查与渲染命令：
 
 ```stack
 stack 1.0
@@ -196,10 +196,10 @@ diagram "Checkout" {
 
 ## 接下来阅读
 
-- [文档与语法](../language/syntax)介绍词法规则和完整语法。
-- [节点与分组](../language/nodes-and-groups)介绍组件和边界建模。
-- [连线与布局](../language/edges-and-layout)介绍关系和布局意图。
-- 选择视觉系统或显式图标前，请阅读[主题与图标](../language/themes-and-icons)。
+- **与编程智能体协作：** 安装可选的[Stack技能](./coding-agents)，使用共享的检查与渲染流程。
+- **从示例开始：** 在Playground中打开[实时渲染的示例](../examples/)，再尝试[主题与图标](../language/themes-and-icons)。
+- **适配你的环境：** [导入供应商图标](./provider-icons)，然后通过[CLI配置指南](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)选择本地存储位置。这些配置属于CLI；浏览器需要显式导入本地图标包。
+- **查阅细节：** 描述更大的系统时，参考[语言文档](../language/syntax)和[诊断与限制](../reference/diagnostics-and-limits)。
 
 ## 更新或卸载
 

diff --git a/content/site/zh/guide/what-is-stack.md b/content/site/zh/guide/what-is-stack.md
@@ -31,12 +31,9 @@ diagram "Service architecture" {
 
 ## Stack 的设计目标
 
-- **简洁编写：** 只需命名节点和连线即可得到有用的图。
-- **可预测生成：** 人和语言模型都能用一种受约束的方式稳定表达概念。
-- **语义源文件：** 记录拓扑和意图，而不是像素。
-- **一致输出：** 渲染器拥有统一的视觉系统。
-- **可操作错误：** 诊断可指向源码范围，并给出候选值、修复帮助和相关声明。
-- **安全嵌入：** 源文件不能执行代码、获取任意资源或注入 HTML/SVG。
+{{productBenefits}}
+
+一致的结果要求引擎版本、源文件、主题和图标包相同。渲染在本地完成，但安装工具、加载网站以及主动导入供应商图标可能需要网络。具体边界请参阅[版本与安全](../reference/versioning-and-safety)。
 
 ## Stack 不是什么
 

diff --git a/content/site/zh/index.md b/content/site/zh/index.md
@@ -1,27 +1,4 @@
 ---
 layout: home
-
-hero:
-  name: Stack
-  text: 将架构写成源代码。
-  tagline: 编写一份简洁的语义文档，无需指定坐标或逐个设置方框样式，即可生成一致且无障碍的架构图。
-  image:
-    light: /favicon.svg
-    dark: /favicon.svg
-    alt: Stack 标志
-  actions:
-    - theme: brand
-      text: 快速开始
-      link: /zh/guide/getting-started
-    - theme: alt
-      text: 打开 Playground
-      link: https://stack-diagram.com/
-
-features:
-  - title: 描述系统
-    details: 用简洁、可读的 .stack 文件记录节点、分组、关系和布局意图。
-  - title: 保持语义可移植
-    details: 带版本的语言和结构化诊断将架构语义与渲染器选择分离。
-  - title: 安全渲染
-    details: 引擎生成不含脚本、任意 HTML 或网络资源的独立 SVG。
+{{productHome}}
 ---