PythonWoods · PythonWoods-Dev · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026
diff --git a/.bumpversion.toml b/.bumpversion.toml
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 [tool.bumpversion]
-current_version = "0.9.2"
+current_version = "0.10.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 

diff --git a/.gitignore b/.gitignore
@@ -14,6 +14,7 @@
 *.tsbuildinfo
 .eslintcache
 _zenzic_core/
+.zenzic_cache/
 __pycache__/
 
 # Misc
@@ -52,3 +53,4 @@ mutmut*
 
 # VS Code Copilot agent definitions (local-only)
 .github/agents/
+.zenzic_cache/
diff --git a/.zenzic.toml b/.zenzic.toml
@@ -38,8 +38,11 @@ excluded_external_urls = [
     "https://spdx.org/licenses/",
     # GitHub PAT settings endpoint can intermittently time out from CI runners.
     "https://github.com/settings/tokens",
-    # GitHub API rate-limits unauthenticated CI runners (HTTP 429 / 403); prefix covers all github.com links.
-    #"https://github.com",
+    # External URLs excluded from the broken-link check to prevent CI flakiness
+    # caused by GitHub API rate-limiting and network timeouts.
+    "https://github.com/PythonWoods/zenzic",
+    "https://github.com/PythonWoods/zenzic-action",
+    "https://github.com/PythonWoods/zenzic-doc",
     # Facebook debugger consistently times out (>10 s) from CI environments.
     "https://developers.facebook.com/tools/debug/",
     # contributor-covenant.org consistently times out (> 10 s) from CI environments.
@@ -197,3 +200,10 @@ it = "i18n/it/docusaurus-plugin-content-docs-developers/current"
 #         uses: pythonwoods/zenzic-action@v1
 #       - name: Verify Badge Freshness
 #         run: uvx zenzic score --check-stamp
+
+# --- NETWORK I/O ---
+[network]
+# Cache external link resolution in .zenzic_cache/external_links.json
+# to eliminate network latency in CI and local re-runs.
+# Set to 0 to disable caching entirely (synchronous fallback).
+cache_ttl_hours = 24
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,50 +15,16 @@ No changes yet.
 
 ---
 
-## [0.9.2] - 2026-06-05
+## [0.10.0] - 2026-06-06
 
 ### Added
 
-- **Engine Guide — Supported Engine Versions table:** Added "Supported Engine Versions" section to `docs/reference/engines.mdx` (EN + IT) documenting the supported major-version line for each adapter: MkDocs `1.x`, Zensical `0.0.x`, Docusaurus `3.x`, Standalone (agnostic). Clarifies that version constraints apply to the config-file schema, not the installed engine binary.
-- **Z109 EXTERNAL_LINK_BROKEN:** Documented Z109 external link finding code (EN + IT) representing broken external URLs.
-- **Diátaxis Compliance Refactoring:** Restructured documentation portal for strict Diátaxis compliance (Batches 1-4), renaming example directories from `docs/how-to/examples/` to `docs/tutorials/examples/` to correctly separate tutorials from how-tos.
-- **Resolved route collisions and sidebar ordering:** Restructured examples and sidebar configurations to resolve overlapping routes and optimize navigation.
-
----
-
-## [0.9.1] - 2026-06-02
-
-### Added
-
-- Z-Code Gallery completion (EN + IT) aligned with the full release scope.
-- New documentation pages and galleries for `Z107 CIRCULAR_ANCHOR` and `Z104 FILE_NOT_FOUND`.
-
-### Changed
-
-- **Repository-Relative Suppression Config:** Updated `.zenzic.toml` `per_file_ignores` and `directory_policies` to use strictly repository-relative keys (prefixed with `docs/` or `docs/it/`).
-- **Strategic Navigation Exemption:** Added `directory_policies` exemption for `docs/how-to/examples/**` under `Z401` to prevent scoring penalties on example directories that intentionally lack index files.
-- **Score Badge telemetry:** Stamped quality score badge inline in `README.md` and `README.it.md` to show a passing score of `96/100`.
-- Hostile Precision UI standardization applied across release-facing documentation surfaces.
-- Terminal documentation debt removed by normalizing legacy snippets and inconsistent command narratives.
-- SVG asset governance aligned with ADR-037 compliance requirements.
-
----
-
-## [0.9.0] - 2026-05-31
-
-### Added
-
-- Historical archive split for v0.8.x and v0.7.x release notes under `changelogs/`.
-- `tutorials/examples.mdx` (EN + IT): full gallery of all 20 `zenzic lab` sandboxes with scenario matrix, exit-code column, and per-scenario prose.
-- 15 new gallery sections covering z102, z103, z105, z108, z202, z204, z301, z302, z303, z402, z403, z501, z502, z503, z505.
-- `finding-codes.mdx` (EN + IT): Z204 CLI output updated to `POLICY VIOLATION DETECTED` banner.
-- `privacy-gate.mdx` (EN + IT): Exit Behavior section and `[core]` table-header fix.
+- **Native CI Integration and Filtering Docs:** Documented the new `--ci` shorthand and `--format github-annotations` in CLI Reference and CI/CD integration guides (EN + IT). Documented the `--only` flag for targeted rule filtering.
+- **Blog Post:** Added new DevRel payload "Zenzic v0.10.0: Native GitHub Annotations and Progressive Adoption" demonstrating the killer features of v0.10.0.
 
 ### Changed
 
-- Documentation for local gates now mirrors the real `just verify` recipe sequence (pre-commit hooks → pytest → strict audit → score stamp → freshness gate).
-- Developers command matrix updated to remove obsolete preflight terminology.
-- v0.8.x narratives archived; v0.9.0 sprint material moved to this entry.
+- **ADR-037 Install Guide Refinement:** Removed the hardcoded version tag (`@v0.10.0`) from the Ephemeral GitHub execution instructions (`uvx --from git+...`) to decouple the command from temporal releases and point to the default branch.
 
 ---
 

diff --git a/README.it.md b/README.it.md
@@ -23,7 +23,7 @@ SPDX-License-Identifier: Apache-2.0
 [![REUSE 3.x compliant](https://img.shields.io/badge/REUSE-3.x%20compliant-0d9488?style=flat-square)](https://reuse.software/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-0d9488?style=flat-square)](LICENSE)
 [![Documentation: Diátaxis](https://img.shields.io/badge/Docs-Di%C3%A1taxis-brightgreen?style=flat-square)](https://diataxis.fr/)
-[![Zenzic](https://img.shields.io/badge/Zenzic-v0.9.2-blue?style=flat-square)](https://github.com/PythonWoods/zenzic)
+[![Zenzic](https://img.shields.io/badge/Zenzic-v0.10.0-blue?style=flat-square)](https://github.com/PythonWoods/zenzic)
 
 ---
 

diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ SPDX-License-Identifier: Apache-2.0
 [![REUSE 3.x compliant](https://img.shields.io/badge/REUSE-3.x%20compliant-0d9488?style=flat-square)](https://reuse.software/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-0d9488?style=flat-square)](LICENSE)
 [![Documentation: Diátaxis](https://img.shields.io/badge/Docs-Di%C3%A1taxis-brightgreen?style=flat-square)](https://diataxis.fr/)
-[![Zenzic](https://img.shields.io/badge/Zenzic-v0.9.2-blue?style=flat-square)](https://github.com/PythonWoods/zenzic)
+[![Zenzic](https://img.shields.io/badge/Zenzic-v0.10.0-blue?style=flat-square)](https://github.com/PythonWoods/zenzic)
 
 ---
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -8,9 +8,9 @@
 
 | Field    | Value      |
 | :------- | :--------- |
-| Version  | v0.9.2     |
+| Version  | v0.10.0     |
 | Codename | Graphite   |
-| Date     | 2026-06-05 |
+| Date     | 2026-06-06 |
 | Status   | Stable     |
 
 ## Release Checklist
@@ -47,11 +47,11 @@ git checkout main
 git pull origin main
 
 # 3. Tag the main branch and push
-git tag v0.9.2
+git tag v0.10.0
 git push origin main --tags
 ```
 
-- [ ] Create GitHub Release from the tag, using the `## v0.9.2` CHANGELOG section as the release body.
+- [ ] Create GitHub Release from the tag, using the `## v0.10.0` CHANGELOG section as the release body.
 
 ## Changelog Reference
 

diff --git a/blog/2026-06-06-native-ci-integration-and-progressive-adoption.mdx b/blog/2026-06-06-native-ci-integration-and-progressive-adoption.mdx
@@ -0,0 +1,50 @@
+---
+slug: zenzic-v0.10.0-native-github-annotations-and-progressive-adoption
+title: "Zenzic v0.10.0: Async Engine, Native Annotations, and Progressive Adoption"
+authors: [pythonwoods]
+tags: [release, ci-cd, architecture]
+---
+
+{/* SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev> */}
+{/* SPDX-License-Identifier: Apache-2.0 */}
+
+Zenzic v0.10.0 introduces a massive performance upgrade with a new **Async Network Engine**, alongside two architectural changes designed strictly for the CI/CD pipeline: **Native GitHub Annotations** and **Destructive Rule Filtering**.
+
+These features are not aesthetic. They are built to solve three specific operational bottlenecks: network-induced CI flakiness, context switching during Pull Request reviews, and the high friction of adopting static analysis in legacy documentation repositories.
+
+{/* truncate */}
+
+## Native GitHub Annotations (`--ci`)
+
+When a pipeline fails, developers do not want to dig through raw terminal logs to find the offending line of code.
+
+Zenzic v0.10.0 introduces the `--format github-annotations` formatter. Instead of drawing terminal UI panels, Zenzic emits raw `::error::` workflow commands. GitHub Actions parses these commands natively and injects them as inline annotations directly into the Pull Request diff.
+
+We also introduced the `--ci` shorthand flag. It performs two actions simultaneously:
+1. Forces `--strict` mode (escalating all warnings to blocking errors).
+2. Sets `--format github-annotations` automatically.
+
+**The result:** Developer Experience is unified. The error is surfaced exactly where the code was changed. The cognitive overhead of mapping a terminal line number back to a file in the IDE is eliminated.
+
+## Progressive Adoption (`--only`)
+
+Adopting a strict linter on a mature, undocumented legacy repository usually results in thousands of initial violations. Forcing a team to fix every broken link, missing alt text, and unused asset before merging a single PR is a failure of governance. It blocks adoption.
+
+The `--only` flag solves this by applying a destructive filter to the Zenzic analysis engine. It accepts a comma-separated list of Z-Codes and silently drops all findings that do not match.
+
+```bash
+# Block PRs strictly on credential leaks and nothing else
+uvx zenzic check all --ci --only Z201,Z204
+```
+
+This is the mechanism for **Progressive Adoption**. Tech Leads can deploy Zenzic to block critical security regressions (credential leaks, path traversal) without breaking the build over structural warnings. As the documentation debt is paid down, the `--only` filter can be expanded or removed entirely to enforce the full rule matrix.
+
+## The End of Network Non-Determinism
+
+Traditional linters fail in CI environments due to rate-limiting and external link timeouts, introducing unacceptable non-determinism into the build pipeline. Zenzic eliminates this bottleneck entirely by replacing synchronous network requests with an asynchronous I/O architecture.
+
+Zenzic v0.10.0 ships with a new **Async Network Engine** built on `asyncio` and `httpx`, enabling concurrent validation of external links. To eradicate latency across repeated CI runs, we deployed **Atomic Local Caching** with a configurable 24-hour TTL, saving results safely to `.zenzic_cache/external_links.json`.
+
+Furthermore, the engine now features an **Anti-Overfetching Smart Fallback**. When external servers arbitrarily block `HEAD` requests (e.g., returning 403 or 405), Zenzic immediately falls back to a streaming `GET` request, safely aborting the connection before downloading the actual payload. Zero false positives. Zero network non-determinism.
+
+Hostile precision, zero fluff. Upgrade to v0.10.0 via the official `PythonWoods/zenzic-action` composite action or locally via `uv tool upgrade zenzic`.
diff --git a/blog/tags.yml b/blog/tags.yml
@@ -3,6 +3,11 @@
 #
 # Zenzic Blog — Semantic Tag Registry
 
+ci-cd:
+  label: "CI/CD"
+  permalink: /ci-cd
+  description: "Continuous Integration and Continuous Deployment integration guides and features."
+
 release:
   label: "Release"
   permalink: /release

diff --git a/changelogs/README.md b/changelogs/README.md
@@ -8,6 +8,7 @@ For active development notes, see [../CHANGELOG.md](../CHANGELOG.md).
 
 | Version | Period | Archive |
 |---------|--------|---------|
-| v0.9.x | 2026-05-31 → active | [main CHANGELOG](../CHANGELOG.md) |
+| v0.10.x | 2026-06-06 → active | [main CHANGELOG](../CHANGELOG.md) |
+| v0.9.x | 2026-05-31 to 2026-06-05 | [v0.9.md](./v0.9.md) |
 | v0.8.x | — | [v0.8.md](./v0.8.md) |
 | v0.7.x | — | [v0.7.md](./v0.7.md) |
diff --git a/changelogs/v0.9.md b/changelogs/v0.9.md
@@ -1,8 +1,49 @@
 <!-- SPDX-FileCopyrightText: 2026 PythonWoods <dev@pythonwoods.dev> -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 <!-- markdownlint-disable MD024 -->
-# Changelog Archive — v0.9.x
+# Changelog Archive: v0.9.x
 
-> **v0.9.x is the active minor line.**
-> Release notes are maintained in the [main CHANGELOG](../CHANGELOG.md).
-> This file will be populated when v0.10.0 ships and the v0.9.x minor closes.
+## [0.9.2] - 2026-06-05
+
+### Added
+
+- **Engine Guide — Supported Engine Versions table:** Added "Supported Engine Versions" section to `docs/reference/engines.mdx` (EN + IT) documenting the supported major-version line for each adapter: MkDocs `1.x`, Zensical `0.0.x`, Docusaurus `3.x`, Standalone (agnostic). Clarifies that version constraints apply to the config-file schema, not the installed engine binary.
+- **Z109 EXTERNAL_LINK_BROKEN:** Documented Z109 external link finding code (EN + IT) representing broken external URLs.
+- **Diátaxis Compliance Refactoring:** Restructured documentation portal for strict Diátaxis compliance (Batches 1-4), renaming example directories from `docs/how-to/examples/` to `docs/tutorials/examples/` to correctly separate tutorials from how-tos.
+- **Resolved route collisions and sidebar ordering:** Restructured examples and sidebar configurations to resolve overlapping routes and optimize navigation.
+
+---
+
+## [0.9.1] - 2026-06-02
+
+### Added
+
+- Z-Code Gallery completion (EN + IT) aligned with the full release scope.
+- New documentation pages and galleries for `Z107 CIRCULAR_ANCHOR` and `Z104 FILE_NOT_FOUND`.
+
+### Changed
+
+- **Repository-Relative Suppression Config:** Updated `.zenzic.toml` `per_file_ignores` and `directory_policies` to use strictly repository-relative keys (prefixed with `docs/` or `docs/it/`).
+- **Strategic Navigation Exemption:** Added `directory_policies` exemption for `docs/how-to/examples/**` under `Z401` to prevent scoring penalties on example directories that intentionally lack index files.
+- **Score Badge telemetry:** Stamped quality score badge inline in `README.md` and `README.it.md` to show a passing score of `96/100`.
+- Hostile Precision UI standardization applied across release-facing documentation surfaces.
+- Terminal documentation debt removed by normalizing legacy snippets and inconsistent command narratives.
+- SVG asset governance aligned with ADR-037 compliance requirements.
+
+---
+
+## [0.9.0] - 2026-05-31
+
+### Added
+
+- Historical archive split for v0.8.x and v0.7.x release notes under `changelogs/`.
+- `tutorials/examples.mdx` (EN + IT): full gallery of all 20 `zenzic lab` sandboxes with scenario matrix, exit-code column, and per-scenario prose.
+- 15 new gallery sections covering z102, z103, z105, z108, z202, z204, z301, z302, z303, z402, z403, z501, z502, z503, z505.
+- `finding-codes.mdx` (EN + IT): Z204 CLI output updated to `POLICY VIOLATION DETECTED` banner.
+- `privacy-gate.mdx` (EN + IT): Exit Behavior section and `[core]` table-header fix.
+
+### Changed
+
+- Documentation for local gates now mirrors the real `just verify` recipe sequence (pre-commit hooks → pytest → strict audit → score stamp → freshness gate).
+- Developers command matrix updated to remove obsolete preflight terminology.
+- v0.8.x narratives archived; v0.9.0 sprint material moved to this entry.
diff --git a/docs/how-to/configuration-strategy.mdx b/docs/how-to/configuration-strategy.mdx
@@ -110,6 +110,15 @@ This is expected. To apply overrides in CI, write the file from a secret before
 
 ---
 
+### Disable network cache in ephemeral environments
+
+Zenzic caches external link responses for 24 hours by default. In highly ephemeral environments (like certain Dockerized CI pipelines) where persisting `.zenzic_cache/` between runs is impossible or undesirable, you can disable the cache entirely to force synchronous network validation on every run.
+
+```toml title=".zenzic.toml"
+[network]
+cache_ttl_hours = 0
+```
+
 ---
 
 > For the full field specification, see [Configuration Reference](../reference/configuration-reference.mdx).