docs: update templates.md and run-json.md for new features

templates.md:
- env var access section ({{ env.VAR }})
- |split filter entry in filter table
- strip_json5 toggle documentation
- {% extends %} + {% block %} pattern with full example
- Clarify deep-merge fallback is only used without {% extends %}

run-json.md:
- Custom executable checks: any non-built-in check name runs as binary
  with HCH_PROXY_ADDR + HCH_TIMEOUT env vars
- strip_json5 field documentation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hiddifydeveloper

docs/run-json.md

@@ -188,6 +188,8 @@ Empty = run locally. See [ssh-deploy.md](ssh-deploy.md).
 
 ## `checks` (array of strings)
 
+Built-in checks:
+
 | Value | What runs |
 |---|---|
 | `dns` | UDP DNS query via the proxy |
@@ -199,10 +201,45 @@ Empty = run locally. See [ssh-deploy.md](ssh-deploy.md).
 | `upload` | Upload throughput |
 | `speedtest` | Alias: `download` + `upload` + `ping` |
 
+**Custom executable check** — any path that is not a built-in name is
+executed as a binary. Exit code 0 = PASS, non-zero = FAIL.
+
+```json5
+"checks": [
+  "dns", "http",
+  // "./my-tester.sh",          // uncomment to enable custom check
+  // "/usr/local/bin/my-check"  // absolute path also works
+]
+```
+
+The binary receives these env vars:
+
+| Var | Value |
+|---|---|
+| `HCH_PROXY_ADDR` | `socks5://host:port` (the client SOCKS proxy) |
+| `HCH_TIMEOUT` | timeout in seconds |
+
+Stdout/stderr from the binary appears in the result `Extra` field (truncated to 200 chars).
+
 Default: `["dns", "http"]`.
 
 ---
 
+## `strip_json5` (bool, default `true`)
+
+When `true` (default), JSON5 extensions (comments, trailing commas) are stripped
+from rendered config files before passing them to the core binary.
+
+Set to `false` for cores that natively accept JSON5, or to debug rendered output:
+
+```json5
+{
+  "strip_json5": false
+}
+```
+
+---
+
 ## `before_start` / `after_stop` (array of strings)
 
 Shell commands (`sh -c`). `before_start` runs before any process starts;

docs/templates.md

@@ -3,7 +3,10 @@
 Config files are rendered through a two-stage pipeline:
 
 ```
-template source  →  Pongo2 render  →  JSON5 strip  →  [base merge]  →  valid JSON  →  core process
+template source  →  Pongo2 render  →  JSON5 strip  →  valid JSON  →  core process
+                         ↑                ↑
+               extends/block/include   skipped when strip_json5:false
+               resolves automatically
 ```
 
 ---
@@ -48,14 +51,30 @@ Both forms work:
 }
 ```
 
+### Environment variable access
+
+Templates can read OS environment variables via the `env` map:
+
+```json5
+"private_key": "{{ env.WG_SERVER_PRIVKEY }}",
+"api_token":   "{{ env.MY_API_KEY }}",
+{% if env.DEBUG %}"log_level": "debug",{% endif %}
+```
+
+Missing env vars render as empty string — no error.
+
 ### Loops
 
-Pass a structured context via the runner (future extension) for loops:
+Use `|split` filter to iterate over comma-separated strings:
 
 ```json5
-"users": [
-  {% for u in users %}
-  {"uuid": "{{ u.uuid }}", "email": "{{ u.email }}"},
+// run.json.j2 — auto-generate variant list
+"vars": [
+  {% for flow in ",xtls-rprx-vision"|split:"," %}
+  {
+    "TITLE":      "{% if flow %}vless-flow{% else %}plain-tls{% endif %}",
+    "VLESS_FLOW": "{{ flow }}"
+  },
   {% endfor %}
 ]
 ```
@@ -64,15 +83,14 @@ Pass a structured context via the runner (future extension) for loops:
 
 <https://github.com/flosch/pongo2?tab=readme-ov-file#filters>
 
-Common ones:
-
 | Filter | Example | Result |
 |---|---|---|
 | `default` | `{{ X\|default:"foo" }}` | `foo` if X empty |
 | `lower` | `{{ NAME\|lower }}` | lowercase |
 | `upper` | `{{ NAME\|upper }}` | UPPERCASE |
 | `truncatechars` | `{{ S\|truncatechars:8 }}` | first 8 chars |
 | `replace` | `{{ S\|replace:"a":"b" }}` | char replace |
+| `split` | `{{ "a,b"\|split:"," }}` | list (for `{% for %}`) |
 
 ---
 
@@ -98,35 +116,79 @@ standard JSON that proxy cores accept.
 }
 ```
 
-### What is NOT stripped
+### Disabling JSON5 stripping
+
+Some cores accept comments natively, or you want to debug rendered output.
+Set `"strip_json5": false` in `run.json`:
+
+```json5
+{
+  "strip_json5": false,   // keep // and # comments in rendered config
+  ...
+}
+```
+
+Default: `true` (strip — required by most proxy cores).
+
+### What is NOT stripped (when strip_json5:true)
 
 - `//` inside a string value: `"url": "https://example.com/path//foo"` → kept
 - `#` inside a string value: `"color": "#ff0000"` → kept
 - Single-quoted strings: `'value'` → normalised to `"value"`
 
 ---
 
-## Base template composition
+## Template inheritance: `{% extends %}` + `{% block %}`
 
-When a core has a `templates/base/<role>.json.j2` file (e.g.
-`examples/xray/templates/base/client.json.j2`), the runner:
+**Recommended pattern** — protocol templates extend the base template.
+Pongo2 handles composition natively; no Go-side merging.
 
-1. Renders the protocol template (e.g. `vless-xhttp/client.json.j2`)
-2. Renders the base template with the same resolved vars
-3. Deep-merges them: **base = defaults, protocol = overrides**
-
-This lets protocol templates be minimal (just `outbounds`) while the base
-provides the outer shell (`log`, `inbounds`/SOCKS, `routing`):
+`examples/xray/templates/base/client.json.j2`:
 
+```json5
+{
+  "log": {"loglevel": "{{ LOG_LEVEL }}"},
+  "inbounds": [
+    {"tag": "socks-in", "port": {{ SOCKS_PORT }}, "protocol": "socks"}
+  ],
+  "outbounds": [
+    {% block outbound %}
+    {"protocol": "freedom", "tag": "direct"}
+    {% endblock %}
+  ]
+}
 ```
-examples/xray/templates/base/client.json.j2   ← log + socks inbound + routing
-examples/xray/vless-xhttp/client.json.j2       ← just the vless outbound
-                                 ↓ deep merge
-                           full xray client config
+
+`examples/xray/vless-xhttp/client.json.j2`:
+
+```json5
+{% extends "../templates/base/client.json.j2" %}
+
+{% block outbound %}
+{
+  "tag": "vless-out",
+  "protocol": "vless",
+  "streamSettings": {
+    {% include "../templates/tls/client.tpl" %}
+    "network": "xhttp"
+  }
+},
+{"protocol": "freedom", "tag": "direct"}
+{% endblock %}
 ```
 
+- `{% extends %}` must be the first statement in the file
+- `{% include %}` still works inside blocks
+- When `{% extends %}` is detected, the Go-side deep-merge fallback is skipped
+
+## Deep-merge fallback (without `{% extends %}`)
+
+If a template does **not** use `{% extends %}`, the runner checks for
+`templates/base/<role>.json.j2` in ancestor directories and deep-merges:
+base = defaults, protocol = overrides.
+
 **Merge rules:**
-- Object keys present only in base → kept
+- Object keys only in base → kept
 - Object keys in both → protocol wins (recursive for nested objects)
 - Arrays → protocol array replaces base array entirely
 - `null` in protocol → removes the key from base