PythonWoods · PythonWoods-Dev · Jun 3, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/docs/how-to/configure-privacy-gate.mdx b/docs/how-to/configure-privacy-gate.mdx
@@ -120,4 +120,4 @@ are appended to any patterns declared in `.zenzic.toml`. They do not replace the
 
 - [Configuration Reference](../reference/configuration-reference.mdx) — full `forbidden_patterns` field specification
 - [Configuration Strategy](./configuration-strategy.mdx) — troubleshooting the two-file model
-- [Examples Overview](../tutorials/examples.mdx) — runnable Z-code gallery scenarios
+- [Examples Overview](../tutorials/examples/index.mdx) — runnable Z-code gallery scenarios
diff --git a/docs/tutorials/examples.mdx b/docs/tutorials/examples.mdx
diff --git a/docs/tutorials/examples/_category_.json b/docs/tutorials/examples/_category_.json
@@ -2,7 +2,7 @@
   "label": "Z-Code Gallery",
   "position": 3,
   "link": {
-    "type": "generated-index",
-    "description": "Self-contained Z-code violation fixtures. Each example isolates one violation class — the minimum setup required to reproduce the reported exit code."
+    "type": "doc",
+    "id": "tutorials/examples/index"
   }
 }
diff --git a/docs/tutorials/examples/index.mdx b/docs/tutorials/examples/index.mdx
@@ -0,0 +1,59 @@
+---
+sidebar_position: 1
+title: "Examples Overview"
+sidebar_label: "Overview"
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Z-Code Gallery
+
+This section contains interactive, reproducible examples of every diagnostic code emitted by Zenzic. 
+
+## Quick-Run Pattern
+
+To run any of these scenarios locally:
+
+```bash
+uvx zenzic lab           # gallery menu
+uvx zenzic lab z101      # run the Z101 scenario
+uvx zenzic lab all       # run all 20 scenarios
+```
+
+## Diagnostic Categories
+
+<DocCardList />
+
+## Feature-to-Example Matrix
+
+| Z-Code | Violation Class | Example |
+| :---: | :--- | :--- |
+| Z101 | Broken internal links | [z101-broken-links](z1xx-links/z101-broken-links) |
+| Z102 | Fragment anchor not defined | [z102-anchor-missing](z1xx-links/z102-anchor-missing) |
+| Z103 | Link to nav-orphaned page | [z103-orphan-link](z1xx-links/z103-orphan-link) |
+| Z105 | Absolute path in link | [z105-absolute-path](z1xx-links/z105-absolute-path) |
+| Z108 | Empty link text | [z108-empty-link-text](z1xx-links/z108-empty-link-text) |
+| Z201 | Credential / secret detection | [z201-credentials](z2xx-security/z201-credentials) |
+| Z202 | Docs-root path traversal | [z202-path-traversal](z2xx-security/z202-path-traversal) |
+| Z204 | Forbidden governance term | [z204-forbidden-term](z2xx-security/z204-forbidden-term) |
+| Z301 | Dangling reference-style link | [z301-dangling-ref](z3xx-references/z301-dangling-ref) |
+| Z302 | Unused reference definition | [z302-dead-def](z3xx-references/z302-dead-def) |
+| Z303 | Duplicate reference definition | [z303-duplicate-def](z3xx-references/z303-duplicate-def) |
+| Z402 | Markdown page not in nav | [z402-orphan-page](z4xx-topology/z402-orphan-page) |
+| Z403 | Image missing alt text | [z403-missing-alt](z4xx-topology/z403-missing-alt) |
+| Z405 | Unreferenced asset on disk | [z405-unused-assets](z4xx-topology/z405-unused-assets) |
+| Z501 | Stub / TODO placeholder content | [z501-placeholder](z5xx-content/z501-placeholder) |
+| Z502 | Page below minimum word count | [z502-short-content](z5xx-content/z502-short-content) |
+| Z503 | Python snippet syntax error | [z503-snippet-error](z5xx-content/z503-snippet-error) |
+| Z505 | Untagged fenced code block | [z505-untagged-code-block](z5xx-content/z505-untagged-code-block) |
+| Z601 | Deprecated brand name in content | [z601-brand-obsolescence](z6xx-brand/z601-brand-obsolescence) |
+| Z602 | i18n locale file parity gap | [z602-i18n-parity](z6xx-brand/z602-i18n-parity) |
+
+---
+
+## See Also {#see-also}
+
+- [Architecture](../../explanation/architecture) — Adapter vs Integration model.
+- [Discovery & Exclusion](../../explanation/discovery) — How the Layered Exclusion hierarchy works.
+- [Checks Reference](../../reference/checks) — All available `zenzic check` commands and their findings.
+- [CLI Reference — lab](../../reference/cli#lab) — Full documentation for `zenzic lab`.
diff --git a/docs/tutorials/examples/z1xx-links/z103-orphan-link.mdx b/docs/tutorials/examples/z1xx-links/z103-orphan-link.mdx
@@ -100,5 +100,5 @@ Exit code 1 is triggered. To fix this, register the target page in the `nav` sec
 
 - [z101 — Broken Links](z101-broken-links) — the target file does not exist on disk.
 - [z102 — Anchor Missing](z102-anchor-missing) — the target file exists but the heading anchor does not.
-- [z402 — Orphan Page](../../examples#example-z402) — the inverse: a page that is not in the nav and has no link pointing to it at all.
+- [z402 — Orphan Page](../../examples/z4xx-topology/z402-orphan-page) — the inverse: a page that is not in the nav and has no link pointing to it at all.
 - [Checks Reference](../../../reference/checks) — full rule specification.
diff --git a/docs/tutorials/examples/z1xx-links/z105-absolute-path.mdx b/docs/tutorials/examples/z1xx-links/z105-absolute-path.mdx
@@ -83,5 +83,5 @@ Exit code 1. Replace the root-relative path link with a document-relative path l
 
 - [z101 — Broken Links](z101-broken-links) — the target file does not exist on disk.
 - [z108 — Empty Link Text](z108-empty-link-text) — the link label is empty, breaking screen reader accessibility.
-- [z202 — Path Traversal](../../examples#example-z202) — a link that escapes the `docs/` directory boundary.
+- [z202 — Path Traversal](../../examples/z2xx-security/z202-path-traversal) — a link that escapes the `docs/` directory boundary.
 - [Checks Reference](../../../reference/checks) — full rule specification.
diff --git a/docs/tutorials/examples/z1xx-links/z108-empty-link-text.mdx b/docs/tutorials/examples/z1xx-links/z108-empty-link-text.mdx
@@ -91,5 +91,5 @@ Exit code 1. Add descriptive, accessible label text inside the Markdown link bra
 
 - [z101 — Broken Links](z101-broken-links) — the target file does not exist on disk.
 - [z105 — Absolute Path](z105-absolute-path) — the link uses a non-portable absolute path.
-- [z403 — Missing Alt Text](../../examples#example-z403) — the same accessibility principle applied to images.
+- [z403 — Missing Alt Text](../../examples/z4xx-topology/z403-missing-alt) — the same accessibility principle applied to images.
 - [Checks Reference](../../../reference/checks) — full rule specification.
diff --git a/docs/tutorials/first-audit.mdx b/docs/tutorials/first-audit.mdx
@@ -59,7 +59,7 @@ Security Breach banner — the non-suppressible alert for a leaked credential:
 
 The masked credential and non-zero exit code are the expected output of the credential scanner.
 
-**The Credential Scanner (Zenzic Audit Badge)** — now run the Z101 link integrity scenario:
+**Link Integrity Demo (Zenzic Audit Badge)** — now run the Z101 LINK_BROKEN scenario:
 
 ```bash
 uvx zenzic lab z101
@@ -77,7 +77,7 @@ uvx zenzic lab
 Launches the gallery menu of 5 Z-code scenarios: credential leaks, broken links, orphan
 assets, brand obsolescence, and i18n parity. No installation. No configuration required.
 
-→ Pick any scenario from the menu, or run a specific one: `uvx zenzic lab z201` (credential scanner), `uvx zenzic lab z101` (link integrity).
+→ Pick any scenario from the menu, or run a specific one: `uvx zenzic lab z201` (CREDENTIAL_SECRET), `uvx zenzic lab z101` (LINK_BROKEN).
 :::
 
 ---
@@ -138,14 +138,7 @@ zenzic check all
 
 Zenzic scans every Markdown file, validates internal links against the Virtual Site Map,
 checks anchors, scans for credentials, and runs your custom rules — then prints a structured
-report and exits with a machine-readable code:
-
-| Code | Meaning |
-| :---: | :--- |
-| **0** | Clean — no issues found |
-| **1** | Findings — documentation quality issues detected |
-| **2** | Credential scanner — leaked credential detected (never suppressed) |
-| **3** | Path traversal guard — path traversal attempt detected (never suppressed) |
+report and exits with a machine-readable code. For details on exit code definitions and security tiers, see the [Exit Code Contract](../reference/finding-codes#exit-code-contract).
 
 A clean run looks like this — the **Zenzic Audit Badge**:
 

diff --git a/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-privacy-gate.mdx b/i18n/it/docusaurus-plugin-content-docs/current/how-to/configure-privacy-gate.mdx
@@ -124,4 +124,4 @@ vengono aggiunti a eventuali pattern dichiarati in `.zenzic.toml`. Non li sostit
 
 - [Riferimento Configurazione](../reference/configuration-reference.mdx) — specifica completa del campo `forbidden_patterns`
 - [Strategia di Configurazione](./configuration-strategy.mdx) — troubleshooting del modello a due file
-- [Panoramica degli Esempi](../tutorials/examples.mdx) — scenari Z-code eseguibili
+- [Panoramica degli Esempi](../tutorials/examples/index.mdx) — scenari Z-code eseguibili