docs: add validated architecture visuals

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- add three validated AnyCap explanatory diagrams and two deterministic contract diagrams;
+- add text equivalents, visual provenance, integrity hashes, multi-size validation evidence, and
+  generated-image metadata scanning.
+
 ## 0.1.0 - 2026-09-02
 
 Initial public MVP:

DOCS-INDEX.md

@@ -4,7 +4,7 @@ authority: canonical
 status: canonical
 title: Sandbox Runtime API documentation index
 genre: spec
-last_verified: 2026-09-02
+last_verified: 2026-09-03
 ---
 
 # Documentation Index
@@ -36,6 +36,7 @@ network policy enforcement, snapshots, PTY, and port forwarding remain outside t
 - [Local Provider](docs/providers/local.md)
 - [Testing and conformance](docs/testing.md)
 - [Clean-room policy](docs/clean-room-policy.md)
+- [Visual source and validation register](docs/visuals/README.md)
 
 ## Process and release evidence
 

README.md

@@ -14,6 +14,12 @@ tools.
 The project standardizes portable lifecycle and capability semantics. It is not a hosted sandbox
 platform, an agent framework, or an open-source distribution of any private system.
 
+![统一 Sandbox 运行时：应用通过 SDK、HTTP/SSE 或 CLI 进入可移植核心，再由 Provider SPI 连接实现。](docs/assets/runtime-overview.png)
+
+The access methods converge on one portable runtime boundary. Provider implementations remain
+replaceable behind a single SPI; the dashed future Provider is a roadmap extension, not part of the
+v0.1 delivery.
+
 ## Why
 
 Agent applications need similar execution primitives but encounter provider-specific APIs for
@@ -27,19 +33,6 @@ This project separates those concerns into:
 - provider conformance checks;
 - future transport mappings and client SDKs.
 
-```text
-Application or Harness Runtime
-             |
-     Sandbox Runtime API
-             |
-    +--------+---------+----------+
-    |                  |          |
-  Local               Mock       Future custom
- Provider            Provider      Provider
-             |
-        sandbox agent
-```
-
 ## Relationship to Harness Runtime API
 
 [`harness-runtime-api`](https://github.com/capa-cloud/harness-runtime-api) standardizes how an

README.zh-CN.md

@@ -13,6 +13,11 @@ Sandbox Runtime API `v0.1` 是一个独立设计、Provider 中立的公共契
 项目只标准化可移植的生命周期和能力语义。它不是托管 Sandbox 平台，不是 Agent 框架，也不是
 任何私有系统的开源发行版。
 
+![统一 Sandbox 运行时：应用通过 SDK、HTTP/SSE 或 CLI 进入可移植核心，再由 Provider SPI 连接实现。](docs/assets/runtime-overview.png)
+
+SDK、HTTP/SSE 和 CLI 最终汇入同一个可移植 Runtime；具体实现隐藏在唯一 Provider SPI 后面。
+虚线的未来 Provider 只是扩展方向，不属于 v0.1 已交付能力。
+
 ## 解决什么问题
 
 Agent 应用通常需要相似的执行能力，但不同 Provider 对生命周期、就绪、命令、文件、终端、
@@ -25,19 +30,6 @@ Agent 应用通常需要相似的执行能力，但不同 Provider 对生命周
 - Provider 一致性测试；
 - 后续的传输协议映射和客户端 SDK。
 
-```text
-应用或 Harness Runtime
-          |
-  Sandbox Runtime API
-          |
-  +-------+--------+----------+
-  |                |          |
-Local             Mock       Future custom
-Provider         Provider      Provider
-          |
-     sandbox agent
-```
-
 ## 与 Harness Runtime API 的关系
 
 [`harness-runtime-api`](https://github.com/capa-cloud/harness-runtime-api) 规范应用如何控制 Agent

docs/providers/local.md

@@ -4,7 +4,7 @@ authority: reference
 status: active
 title: Local Provider boundary
 genre: primer
-last_verified: 2026-09-02
+last_verified: 2026-09-03
 ---
 
 # Local Provider
@@ -23,6 +23,13 @@ working directory, but command arguments are not a kernel security boundary.
 
 Never run untrusted or AI-generated code with this Provider.
 
+![Local Provider 安全边界：文件 API 受资源目录限制，但命令进程仍拥有当前宿主用户权限。](../assets/local-provider-boundary.svg)
+
+Text equivalent: file API requests pass sandbox-relative path, real-path, symbolic-link, and size
+checks before reaching files inside one generation directory. Commands start with that directory as
+their working directory but remain ordinary host processes and may access anything available to the
+current OS user.
+
 ## Implemented capability
 
 - bounded non-interactive command execution;

docs/testing.md

@@ -4,7 +4,7 @@ authority: reference
 status: active
 title: Testing and provider conformance
 genre: how-to
-last_verified: 2026-09-02
+last_verified: 2026-09-03
 ---
 
 # Testing and Provider Conformance
@@ -38,12 +38,18 @@ by the public-content scan and production dependency audit.
 
 ## Conformance runner
 
+![Provider conformance：先验证清单与就绪，再并列检查命令和文件，校验结构并清理资源。](assets/provider-conformance.png)
+
 `runProviderConformance(provider, options)` checks behavior declared by the Provider manifest. A
 Provider that declares `commandExecution` must supply `options.commandRequest` with a safe command
 known to exist in that runtime; the portable core does not assume POSIX utilities or a particular
 language runtime. Each invocation uses a unique synthetic resource identity and cleans it up. A failed
 check means the Provider must not claim compatibility. Passing conformance does not certify isolation,
 production availability, or performance.
 
+Text equivalent: each run uses a unique synthetic resource, validates `describe`, `provision`, and
+bounded readiness, checks declared command and file behavior as independent cases, validates complete
+result shapes, and calls `terminate` before reporting pass or fail.
+
 Provider-specific real-account tests must be opt-in, use environment-provided credentials, and stay
 outside default CI.