Refresh Docs for Stack CLI 0.5.2 and runtime examples

CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to Stack documentation
+
+Canonical user documentation and generated agent guidance for Stack architecture diagrams.
+
+## Ownership
+
+See [machine resource distribution](./MACHINE_RESOURCES.md) for the versioned
+schema, grammar, diagnostics, examples, capability manifest, and consumer example.
+
+Edit the shared agent workflow in `content/agent-workflow.md`. Both the installable
+skill and the human-readable workflow are generated from this one source. Skill
+discovery metadata lives in `content/skill-metadata.json`, and published CLI
+identity lives in `content/cli-release.json`.
+
+The canonical four-locale site sources live in `content/site/`. Preserve route
+parity across English, Japanese, Chinese, and Korean pages when changing the site
+inventory. Four generated `guide/agent-workflow.md` pages expose the canonical
+English instructions used by the skill; the localized 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.
+
+Language syntax, schemas, and canonical examples remain owned by
+[stack-sh/specification](https://github.com/stack-sh/specification).
+[stack-sh/cli](https://github.com/stack-sh/cli) owns native command behavior and the
+`npx skills add stack-sh/cli` installation entry point.
+[stack-sh/web](https://github.com/stack-sh/web) owns the playground and deployment
+at [stack-diagram.com/docs](https://stack-diagram.com/docs).
+
+## Generate and verify
+
+Node.js 22 or newer is required. Generation uses only Node.js built-ins and has no
+install scripts. Tests and machine conformance checks require the pinned development
+dependencies; install them with `npm ci --ignore-scripts` first.
+
+```sh
+npm run generate
+npm test
+npm run check
+```
+
+Commit source and generated changes together. Do not edit `generated/` directly.
+Check mode rejects modified, missing, or unexpected generated files. Generation
+does not silently delete old files. The manifest records SHA-256 values and the
+published CLI revision; hashes prove byte integrity, not publisher identity.
+
+Consumers must pin a reviewed, merged commit and verify its manifest and files.
+The CLI's source revision is distinct from the documentation revision: updating
+instructions does not publish a new CLI binary. Recheck capability statements
+against the released binary's help when updating the release lock; changing a
+version string alone does not prove a feature is available.
+
+## Keep the published CLI reference current
+
+Run `npm run release:sync` after a stable CLI release. It resolves the published
+tag to its exact commit, updates `content/cli-release.json`, and regenerates all
+version declarations. Review changed capabilities and run tests and the verified
+release binary smoke before opening a PR. After merging, update both consumer
+Docs pins and verify the website deployment and CLI skill installation.
+
+`npm run release:check` and the read-only daily freshness workflow reject a newer
+unrecorded stable release or a retargeted tag. They do not publish, install a CLI,
+or merge changes. Scheduled runs can be delayed and GitHub notification settings
+control failure notifications. Web additionally audits the release it deploys.
+
+Site shell examples receive a generated `$ ` prompt; the installable skill keeps
+executable command lines without prompts. The canonical source remains shared.
+
+## Consumer freshness
+
+`npm run consumers:check` compares the current generated content with the CLI and
+Web main-branch pins and the website's public `/docs-source.json` deployment
+provenance. It verifies every pinned manifest hash and the actual CLI skill bytes.
+Equivalent content at an older commit is accepted; a website-only edit does not
+require a pointless CLI skill update. Website production provenance identifies the
+deployed source; it is not a substitute for checking rendered pages after release.
+
+The read-only Consumer freshness workflow runs after Docs main changes, daily,
+and on manual dispatch. A source change may intentionally fail this audit until
+the required consumer PRs and Web deployment finish. Update the affected pins,
+run consumer tests, merge and deploy, then rerun the audit. It never grants write
+permissions or silently auto-merges consumer updates.
+
+## Consumer ownership
+
+CLI consumes a reviewed Docs revision through `skills/docs-source.json`; Web uses
+`scripts/docs-source.json`. Both verify the manifest hash and generated file bytes.
+Do not edit the generated CLI skill or website Markdown inputs in those repositories.
+Edit the original content here, then update only the affected consumer pins through
+reviewed PRs. Equivalent generated content does not require a pin-only update.
+
+The website preserves the original four-locale routes and provides the machine
+discovery endpoint. Its language, example, link, and build gates must continue to
+pass. Source generation and deployment provenance alone do not prove rendered-site
+compatibility: check public HTML/Markdown, agent discovery, and the consumer example
+after deployment, then rerun the consumer freshness audit.

README.md

@@ -1,108 +1,81 @@
-# Stack documentation sources
+# Stack documentation
 
-Canonical user documentation and generated agent guidance for Stack architecture diagrams.
+The shared source for Stack's user guides, language reference, and coding-agent guidance.
+Stack turns text into architecture diagrams with consistent themes and fast, local rendering.
+This repository keeps the instructions used by people, the website, and coding agents in sync.
 
-## Ownership
+## Read the docs
 
-See [machine resource distribution](./MACHINE_RESOURCES.md) for the versioned
-schema, grammar, diagnostics, examples, capability manifest, and consumer example.
+- [English](https://stack-diagram.com/docs/)
+- [日本語](https://stack-diagram.com/docs/ja/)
+- [简体中文](https://stack-diagram.com/docs/zh/)
+- [한국어](https://stack-diagram.com/docs/ko/)
 
-Edit the shared agent workflow in `content/agent-workflow.md`. Both the installable
-skill and the human-readable workflow are generated from this one source. Skill
-discovery metadata lives in `content/skill-metadata.json`, and published CLI
-identity lives in `content/cli-release.json`.
+Start with [your first diagram](https://stack-diagram.com/docs/guide/getting-started),
+browse the [example gallery](https://stack-diagram.com/docs/examples/), or try the
+[Playground](https://stack-diagram.com/). Examples render from canonical `.stack`
+source in your browser; they are not separately maintained SVG exports.
 
-The four-locale site sources live in `content/site/`. They were imported from
-`stack-sh/web` commit `c0c773fd2721a177c56406732c010808269e30bc` under Apache-2.0.
-The original 56 page paths are preserved. Four generated `guide/agent-workflow.md`
-pages expose the canonical English instructions used by the skill; the localized
-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.
+## Use Stack with a coding agent
 
-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.
+Install the Stack skill through the official CLI repository:
 
-`generated/site/` contains complete Markdown inputs for the website. Website
-presentation, images, VitePress configuration, and deployment are not owned here.
+```sh
+npx skills add stack-sh/cli
+```
+
+The skill teaches an agent to write, check, format, and render Stack diagrams with
+the CLI. Its instructions are generated here from the same
+[agent workflow](https://stack-diagram.com/docs/guide/agent-workflow) published in
+the docs. Installing a skill does not install the Stack CLI; follow the
+[CLI installation guide](https://stack-diagram.com/docs/guide/getting-started) too.
+
+## Build an integration
+
+The public [machine resource index](https://stack-diagram.com/machine/index.json)
+provides versioned discovery for schemas, syntax highlighting, diagnostics,
+canonical examples, and implementation capabilities. Use it to find immutable,
+hash-verified resources rather than scraping documentation pages.
+
+See [Machine resource distribution](./MACHINE_RESOURCES.md) for the contract and
+the [working consumer example](./examples/read-machine-resources.mjs).
+A versioned capability snapshot is immutable; it is not an alias for the latest CLI.
 
-Language syntax, schemas, and canonical examples remain owned by
+## How the sources reach users
+
+| Source here | Consumer | Published result |
+| --- | --- | --- |
+| Guides and reference in `content/site/` | [stack-sh/web](https://github.com/stack-sh/web) | The four-language documentation site |
+| `content/agent-workflow.md` | Web and [stack-sh/cli](https://github.com/stack-sh/cli) | The readable agent workflow and installable skill |
+| Machine resource definitions | Web | The public machine resource index and versioned manifests |
+
+The deterministic generator produces `generated/` and a SHA-256 manifest.
+Consumers pin a reviewed commit and verify the generated bytes. Updating this
+repository does not by itself deploy the website or publish a CLI binary.
+
+Language semantics, schemas, and canonical example sources are owned by
 [stack-sh/specification](https://github.com/stack-sh/specification).
-[stack-sh/cli](https://github.com/stack-sh/cli) owns native command behavior and the
-`npx skills add stack-sh/cli` installation entry point.
-[stack-sh/web](https://github.com/stack-sh/web) owns the playground and deployment
-at [stack-diagram.com/docs](https://stack-diagram.com/docs).
+The [engine](https://github.com/stack-sh/engine) owns layout and rendering;
+Web owns presentation and deployment; CLI owns native command behavior.
 
-## Generate and verify
+## Contribute
 
-Node.js 22 or newer is required. Generation uses only Node.js built-ins and has no
-install scripts. Tests and machine conformance checks require the pinned development
-dependencies; install them with `npm ci --ignore-scripts` first.
+Use Node.js 22 or newer:
 
 ```sh
+npm ci --ignore-scripts
 npm run generate
 npm test
 npm run check
+npm run machine:check
 ```
 
-Commit source and generated changes together. Do not edit `generated/` directly.
-Check mode rejects modified, missing, or unexpected generated files. Generation
-does not silently delete old files. The manifest records SHA-256 values and the
-published CLI revision; hashes prove byte integrity, not publisher identity.
-
-Consumers must pin a reviewed, merged commit and verify its manifest and files.
-The CLI's source revision is distinct from the documentation revision: updating
-instructions does not publish a new CLI binary. Recheck capability statements
-against the released binary's help when updating the release lock; changing a
-version string alone does not prove a feature is available.
-
-## Keep the published CLI reference current
-
-Run `npm run release:sync` after a stable CLI release. It resolves the published
-tag to its exact commit, updates `content/cli-release.json`, and regenerates all
-version declarations. Review changed capabilities and run tests and the verified
-release binary smoke before opening a PR. After merging, update both consumer
-Docs pins and verify the website deployment and CLI skill installation.
-
-`npm run release:check` and the read-only daily freshness workflow reject a newer
-unrecorded stable release or a retargeted tag. They do not publish, install a CLI,
-or merge changes. Scheduled runs can be delayed and GitHub notification settings
-control failure notifications. Web additionally audits the release it deploys.
-
-Site shell examples receive a generated `$ ` prompt; the installable skill keeps
-executable command lines without prompts. The canonical source remains shared.
-
-## Consumer freshness
-
-`npm run consumers:check` compares the current generated content with the CLI and
-Web main-branch pins and the website's public `/docs-source.json` deployment
-provenance. It verifies every pinned manifest hash and the actual CLI skill bytes.
-Equivalent content at an older commit is accepted; a website-only edit does not
-require a pointless CLI skill update. Website production provenance identifies the
-deployed source; it is not a substitute for checking rendered pages after release.
-
-The read-only Consumer freshness workflow runs after Docs main changes, daily,
-and on manual dispatch. A source change may intentionally fail this audit until
-the required consumer PRs and Web deployment finish. Update the affected pins,
-run consumer tests, merge and deploy, then rerun the audit. It never grants write
-permissions or silently auto-merges consumer updates.
-
-## Consumer ownership
-
-CLI consumes a reviewed Docs revision through `skills/docs-source.json`; Web uses
-`scripts/docs-source.json`. Both verify the manifest hash and generated file bytes.
-Do not edit the generated CLI skill or website Markdown inputs in those repositories.
-Edit the original content here, then update only the affected consumer pins through
-reviewed PRs. Equivalent generated content does not require a pin-only update.
-
-The website preserves the original four-locale routes and provides the machine
-discovery endpoint. Its language, example, link, and build gates must continue to
-pass. Source generation and deployment provenance alone do not prove rendered-site
-compatibility: check public HTML/Markdown, agent discovery, and the consumer example
-after deployment, then rerun the consumer freshness audit.
+Edit `content/`, not `generated/`, and commit source and generated changes
+together. See [Contributing](./CONTRIBUTING.md) for source ownership, release
+synchronization, consumer updates, and verification.
+Bug reports and documentation improvements are welcome through
+[issues](https://github.com/stack-sh/docs/issues) and pull requests.
+
+## License
+
+[Apache-2.0](./LICENSE).

content/cli-release.json

@@ -1,5 +1,5 @@
 {
   "repository": "stack-sh/cli",
-  "revision": "1d5f64cc699e42f9ce52ac537903e40c0eb91432",
-  "version": "0.5.1"
+  "revision": "f6220c5c24bc515574ea6f6dd6d55af00d35f89d",
+  "version": "0.5.2"
 }

content/site/examples/index.md

@@ -1,7 +1,7 @@
 # Example gallery
 
-Start small, then explore groups, layout, and provider icons. Each preview loads a canonical `.stack` source and renders on your device with the same WASM engine as the Playground. Engine updates improve these previews too; no separate SVG images need regeneration.
+Start small, then explore groups, layout, and complete systems. Every example here uses built-in icons, so no additional packs are needed. Previews render canonical `.stack` source on your device with the same WASM engine as the Playground.
 
-This gallery uses built-in fallback shapes for provider icons. To use branded artwork in your own diagram, explicitly import the listed icon packs in the [Playground](../guide/provider-icons.md) or [CLI](../guide/getting-started.md). Source links remain available when JavaScript or preview loading is unavailable.
+Select an image to enlarge it. Use actual size to inspect details, or fit the diagram to your screen. The separate source link lets you read and reuse the `.stack` code, even when JavaScript or preview loading is unavailable.
 
 <ExampleGallery locale="en" />

content/site/ja/examples/index.md

@@ -1,7 +1,7 @@
 # 作例ギャラリー
 
-小さな構成図から始め、グループ、配置、サービスのアイコンへと表現を広げましょう。各プレビューは正本の `.stack` を読み込み、Playgroundと同じWASM engineで端末上に描画します。Engineを更新すれば作例にも反映され、SVG画像の再生成は不要です。
+小さな構成図から始め、グループ、配置、システム全体へと表現を広げましょう。ここに掲載する作例はすべて組み込みアイコンだけで描けるため、追加のパックは不要です。プレビューは正本の `.stack` を読み込み、Playgroundと同じWASM engineで端末上に描画します。
 
-このギャラリーではサービスのアイコンを組み込みの代替図形で表示します。自分の図でブランドのアイコンを使う場合は、表示されたicon packを[Playground](../guide/provider-icons.md)または[CLI](../guide/getting-started.md)に明示的に取り込んでください。JavaScriptやプレビューを利用できない場合も、ソースへのリンクから原稿を読めます。
+画像をタップすると拡大表示できます。「実寸で見る」で細部を確認したり、画面に合わせて全体を見渡したりできます。別のソースリンクから `.stack` を読んで再利用することもできます。JavaScriptやプレビューを利用できない場合も、ソースへのリンクは利用できます。
 
 <ExampleGallery locale="ja" />

content/site/ko/examples/index.md

@@ -1,7 +1,7 @@
 # 예제 갤러리
 
-작은 다이어그램으로 시작해 그룹, 레이아웃, 제공자 아이콘을 살펴보세요. 각 미리보기는 정본 `.stack` 소스를 불러와 Playground와 같은 WASM 엔진으로 기기에서 렌더링합니다. 엔진이 업데이트되면 미리보기에도 반영되므로 별도의 SVG 이미지를 다시 생성할 필요가 없습니다.
+작은 다이어그램으로 시작해 그룹, 레이아웃, 전체 시스템을 살펴보세요. 여기의 모든 예제는 기본 아이콘만 사용하므로 추가 팩이 필요하지 않습니다. 미리보기는 정본 `.stack` 소스를 불러와 Playground와 같은 WASM 엔진으로 기기에서 렌더링합니다.
 
-이 갤러리는 제공자 아이콘에 기본 대체 도형을 사용합니다. 자신의 다이어그램에 브랜드 아이콘을 사용하려면 [Playground](../guide/provider-icons.md) 또는 [CLI](../guide/getting-started.md)에서 표시된 아이콘 팩을 명시적으로 가져오세요. JavaScript나 미리보기를 사용할 수 없어도 소스 링크에서 원문을 읽을 수 있습니다.
+이미지를 누르면 확대할 수 있습니다. 실제 크기로 세부 내용을 확인하거나 화면에 맞춰 전체를 보세요. 별도의 소스 링크에서 `.stack` 코드를 읽고 재사용할 수 있으며, JavaScript나 미리보기를 사용할 수 없어도 소스에 접근할 수 있습니다.
 
 <ExampleGallery locale="ko" />