docs: add documentation guide

Author: RamazanKara

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to vmod-wasm will be documented in this file.
 
+## Unreleased
+
+### Changed
+- Added a documentation guide that gives operators and module authors a clearer
+  reading path through production, development, configuration, compatibility,
+  architecture, and security docs.
+- Included documentation media assets and all example README files in the
+  Automake source distribution.
+
 ## [4.3.5] - 2026-05-25
 
 ### Added

Makefile.am

@@ -26,7 +26,6 @@ EXTRA_DIST = \
 	autogen.sh \
 	scripts/perf-test.sh \
 	scripts/soak-test.sh \
-	.github/dependabot.yml \
 	.github/PULL_REQUEST_TEMPLATE.md \
 	.github/ISSUE_TEMPLATE/bug_report.md \
 	.github/ISSUE_TEMPLATE/config.yml \
@@ -38,18 +37,27 @@ EXTRA_DIST = \
 	docs/CONFIGURATION.md \
 	docs/DEVELOPMENT.md \
 	docs/PRODUCTION.md \
+	docs/README.md \
 	docs/SECURITY.md \
+	docs/assets/proxy-wasm-live-validation.mp4 \
+	docs/assets/proxy-wasm-live-validation.mp4.sha256 \
+	docs/assets/vmod-wasm-perf-demo.gif \
+	docs/assets/vmod-wasm-perf-demo.mp4 \
 	examples/Cargo.lock \
 	examples/Cargo.toml \
 	examples/README.md \
 	examples/rustfmt.toml \
 	examples/rust/Cargo.toml \
+	examples/rust/README.md \
 	examples/rust/src/lib.rs \
 	examples/proxy-wasm-filter/Cargo.toml \
+	examples/proxy-wasm-filter/README.md \
 	examples/proxy-wasm-filter/src/lib.rs \
 	examples/passthrough/Cargo.toml \
+	examples/passthrough/README.md \
 	examples/passthrough/src/lib.rs \
 	examples/transform/Cargo.toml \
+	examples/transform/README.md \
 	examples/transform/src/lib.rs \
 	examples/edge-security-filter/Cargo.toml \
 	examples/edge-security-filter/README.md \

README.md

@@ -183,19 +183,17 @@ under `perf-logs/`.
 
 ## Documentation
 
-- Start with the [Production Guide](docs/PRODUCTION.md) if you are deciding how
-  to run this safely.
-- Start with the [Development Guide](docs/DEVELOPMENT.md) if you are writing a
-  module.
-- Use the [Compatibility Matrix](docs/COMPATIBILITY.md) to check whether an
-  existing Proxy-Wasm filter can run unchanged.
-
-- [Development Guide](docs/DEVELOPMENT.md) — Writing, building, and testing Proxy-Wasm modules
-- [Configuration Reference](docs/CONFIGURATION.md) — All VCL functions with parameters
-- [Architecture](docs/ARCHITECTURE.md) — Component design and request lifecycle
-- [Proxy-Wasm Compatibility](docs/COMPATIBILITY.md) — ABI coverage matrix
-- [Security Model](docs/SECURITY.md) — Isolation, threat model, supply chain security
-- [Production Guide](docs/PRODUCTION.md) — Deployment, hot-reload, monitoring, capacity planning
+Use the [Documentation Guide](docs/README.md) as the reading map. The short
+version:
+
+- [Production Guide](docs/PRODUCTION.md) — install, constrain, monitor, reload,
+  and roll back vmod-wasm safely.
+- [Development Guide](docs/DEVELOPMENT.md) — write, build, and test
+  Proxy-Wasm modules.
+- [Compatibility Matrix](docs/COMPATIBILITY.md) — check ABI coverage before
+  porting an existing Proxy-Wasm filter.
+- [Configuration Reference](docs/CONFIGURATION.md) — exact `wasm.*` VCL API,
+  defaults, return values, and valid scopes.
 
 ## License
 

docs/README.md

@@ -0,0 +1,61 @@
+# Documentation Guide
+
+This directory contains the operator, developer, and design documentation for
+vmod-wasm. The project targets Varnish 9.x with Wasmtime 44.0.0, so the docs
+assume that release contract unless a section says otherwise.
+
+## Start Here
+
+- Read [Production Deployment](PRODUCTION.md) when deciding how to install,
+  constrain, monitor, reload, and roll back vmod-wasm in front of real traffic.
+- Read [Development Guide](DEVELOPMENT.md) when writing or adapting a
+  Proxy-Wasm module for Varnish.
+- Read [Proxy-Wasm Compatibility](COMPATIBILITY.md) before porting an existing
+  filter from another Proxy-Wasm host.
+- Read [Configuration Reference](CONFIGURATION.md) when you need exact VCL
+  function names, return values, defaults, and valid scopes.
+
+## Documents
+
+| Document | Use it for |
+|----------|------------|
+| [Production Deployment](PRODUCTION.md) | Release bundles, runtime limits, monitoring, VCL reloads, canaries, rollback, capacity planning |
+| [Development Guide](DEVELOPMENT.md) | Building Rust/Wasm modules, SDK callback shape, HTTP callouts, tests, debugging |
+| [Configuration Reference](CONFIGURATION.md) | Complete `wasm.*` VCL API reference with parameters, return values, and examples |
+| [Proxy-Wasm Compatibility](COMPATIBILITY.md) | ABI support matrix, properties, pseudo-headers, limitations |
+| [Architecture](ARCHITECTURE.md) | Engine lifetime, store pooling, HTTP callout flow, VDP response-body integration, file map |
+| [Security Model](SECURITY.md) | Sandbox boundaries, SSRF controls, module supply-chain guidance, incident response |
+
+## Example Modules
+
+The [`examples/`](../examples/) workspace contains small, focused modules that
+exercise the VMOD from VTC tests:
+
+- [`proxy-wasm-filter`](../examples/proxy-wasm-filter/) is the best starting
+  point for a normal Rust `proxy-wasm` SDK module.
+- [`passthrough`](../examples/passthrough/) is a no-op lifecycle baseline.
+- [`transform`](../examples/transform/) shows a minimal response-header
+  mutation.
+- [`rust`](../examples/rust/) demonstrates raw vmod-wasm host functions.
+- [`edge-security-filter`](../examples/edge-security-filter/) is a realistic
+  reference fixture covering config, metrics, shared data, callouts, body
+  callbacks, and local responses.
+
+For production edge-security deployments, use the standalone
+[vmod-wasm Edge Security Filter](https://github.com/RamazanKara/vmod-wasm-edge-security-filter)
+repository. The in-tree filter remains a fixture so vmod-wasm can test a
+realistic workload without depending on another repository during CI.
+
+## Release Checks
+
+Before promoting a release, the documentation and source distribution should
+survive the same checks as the code:
+
+```bash
+docker build -t vmod-wasm-ci .
+docker run --rm vmod-wasm-ci make check
+docker run --rm vmod-wasm-ci make distcheck DISTCHECK_CONFIGURE_FLAGS="--with-wasmtime=/opt/wasmtime"
+```
+
+Use `make perf-test` for a short local throughput comparison and
+`make soak-test` for longer VCL reload, pooling, and sustained-traffic checks.