v0.6.1a1 — Obsidian Bastion: Universal Discovery & VCS Awareness

🏰 Zenzic v0.6.1a1 — The Obsidian Bastion Release

Zenzic evolves into a VCS-aware Documentation Platform Analyser. This release marks the transition to a multi-source architecture, enabling deep integration with Docusaurus i18n and professional-grade exclusion management.

🚄 Universal Discovery Engine

The new discovery module centralizes file iteration across the entire framework. Zenzic now respects your workspace structure like never before, ensuring consistent results between the Scanner, Validator, and Shield.

🛡️ Layered Exclusion Management

Introducing a 4-level hierarchy for file and directory exclusions:

1. System Guardrails: Hardcoded protection for .git, .venv, node_modules, etc.
2. VCS Discovery: Optional support for .gitignore and .hgignore patterns.
3. Project Config: Granular control via zenzic.toml (now with forced inclusion support).
4. CLI Overrides: Dynamic control for specialized CI runs.

🌐 Docusaurus i18n & Metadata Routing

• Multi-source Discovery: Zenzic now automatically finds and lints translated docs in i18n/ locale trees.
• Slug Support: Frontmatter slug: overrides are now citizens of the Virtual Site Map (VSM).

🧩 Ecosystem Standardisation

• Integrations Namespace: MkDocs support has been moved to zenzic.integrations.mkdocs for a cleaner core.
• Pure Analysis: The serve command has been removed to preserve the Zero Subprocess Pillar.

🧪 Quality & Security

• Anti-ReDoS: Shield middleware now truncates pathologically long lines (>1MiB).
• Anti-Jailbreak: Hardened docs_root validation (Blood Sentinel Exit 3).
• Full Parity: 953 tests passed. Documentation synced at zenzic.dev.

v0.6.0a2 — Obsidian Glass

v0.6.0a2 — Obsidian Glass

Zenzic v0.6.0a2 is here, establishing a new standard for documentation integrity and security.

🚄 Universal Discovery & Metadata Routing

The new Discovery engine ensures that your exclusion rules are respected everywhere. Whether you use MkDocs, Docusaurus, or Zensical, Zenzic now maps your site topology using high-fidelity metadata.

🛡️ Hardened Security

The Zenzic Shield is now more vigilant than ever, operating as an IO middleware to catch secrets and path traversals before any parsing occurs.

🌐 New Home: zenzic.dev

Our documentation has moved! Visit zenzic.dev for the updated guides, the new Obsidian Style Guide, and deep dives into the Three Pillars of Zenzic.

📦 Installation (Pre-release)

Zenzic v0.6.0a2 is an Alpha release. To install it, you must specify the exact version or use the --pre flag.

Using uv (Recommended for speed)

# Run Zenzic instantly without installing
uvx --pre zenzic check all

# Or install it in your environment
uv pip install --pre zenzic

Using pip

# Install the specific alpha version
pip install zenzic==0.6.0a2

# Or always get the latest pre-release
pip install --pre zenzic

v0.6.0a1 — Obsidian Glass: The Headless Transition

🛡️ Zenzic v0.6.0a1 — "Obsidian Glass"

"The Sentinel no longer carries its own reflection; it watches the world through a prism of pure logic."

This release marks the most significant architectural evolution of Zenzic to date. We have officially transitioned to a Headless Architecture, decoupling the core analysis engine from the documentation site. Zenzic is now a pure, lightweight, and extremely fast security-first framework for any Markdown ecosystem.

---

⚠️ Alpha Release: The Headless Shift (Breaking Changes)

This is a pre-release. It introduces structural changes to the repository and the distribution model:

• Core Decoupling: The docs/ directory has been removed from the core repository. Documentation now lives in its own sovereign Bastion: zenzic-doc.
• Engine Agnosticism: All MkDocs-specific build dependencies and scripts have been purged. The core is now "clean" and focused 100% on static analysis.

---

⚓ What's New

💎 Docusaurus Native Support

Zenzic now speaks the language of the modern web. We’ve implemented a native DocusaurusAdapter (Pure Python) that enables:

• Full support for MDX files.
• i18n Ghost Routes: Automatic mapping of localized content in i18n/ to virtual site routes.
• Zero-Node.js Dependency: The adapter maps complex React-based documentation structures by analyzing the filesystem and static configurations, maintaining our "No Subprocesses" pillar.

🏗️ Core Hardening & Cleanup

• Fixed .mdx Classification: The engine now correctly identifies .mdx files as documents rather than assets.
• uvx / pipx Compatibility: Fixed the [project.scripts] entry point. You can now invoke the Sentinel directly via uvx --pre zenzic.
• Performance Optimization: By removing the documentation build overhead, the preflight check and general installation are now significantly faster.

---

🛠️ Technical Specs

• Logic: 100% Pure Python 3.11+.
• Tests: 767 passed (100% regression coverage).
• Adapter Logic: Recursive Θ(V+E) graph mapping for Docusaurus v3.
• Governance: REUSE 3.3 compliant.

📖 Documentation & Contribution

For the latest guides, architecture deep-dives, and to contribute to the documentation, visit our portal:
👉 zenzic.pythonwoods.dev

v0.5.0a5 — The Sentinel Codex

🛡️ Zenzic v0.5.0a5 — "The Sentinel Codex"

"Rigour in code must extend to every single pixel the user sees."

This release marks the end of the "hand-crafted" era for Zenzic. With v0.5.0a5, the Safe Harbor receives its visual constitution (The Sentinel Style Guide) and full automation of its documentation assets. This version establishes the final structural baseline before the promotion to Release Candidate.

⚓ Release Highlights:

1. Sentinel Visual Language (ZRT-DOC-002):

   • Canonical Style Guide: Implemented a binding internal standard for UI/UX consistency.
   • Card Grid Refactoring: Transitioned from cluttered navigation to a high-density, single-action-link pattern.
   • Admonition Taxonomy: Enforced strict semantic roles for callouts (e.g., danger is now exclusively reserved for security incidents).

2. Graph Integrity & i18n Stability (ZRT-DOC-004):

   • 102 Strategic Anchor IDs: Injected explicit anchors across 70 files to ensure link stability between English and Italian translations.
   • Icon Normalization: Purged all Material Icons in favor of the clinical precision of Lucide and Octicons.

3. Visual Truth Automation:

   • Deterministic SVG Pipeline: All 5 documentation screenshots are now auto-generated from live sandbox fixtures. No more manual XML editing.
   • Metadata Alignment: Full synchronization of version strings across CITATION.cff, pyproject.toml, and __init__.py.

4. Hardened Security & CLI Validation:

   • E2E Test Suite: 8 new end-to-end tests validating the exit code contract (3 > 2 > 1 > 0) with zero mocks.
   • Critical Fix: Resolved a bug in the check all command where the --exit-zero flag could inadvertently silence security incidents. The Sentinel is now unconditionally vigilant.

🧪 Harbour Metrics:

• 767 regression tests passed successfully.
• 86.7% Mutation Score (testing effectiveness).
• i18n Parity: 100% coverage between EN and IT documentation.

v0.5.0a4

v0.5.0a4 — The Hardened Sentinel

Pre-release alpha. Not recommended for production use.

The Sentinel now detects system-path traversal attacks, link cycle violations,
and hex-encoded payloads — with surgical noise control for advisory findings.

---

🩸 Blood Sentinel — Exit Code 3

Links that escape docs/ and target OS system directories (/etc/, /root/,
/var/, /proc/, /sys/, /usr/) are classified as security_incident and
exit with code 3. Priority order: 3 > 2 (Shield) > 1 (errors). Never
suppressed by --exit-zero.

🔗 Graph Integrity — Θ(V+E)

Iterative DFS cycle detection runs once after the in-memory resolver is built
(Phase 1.5). Every Phase 2 per-link lookup is O(1). CIRCULAR_LINK is reported
at severity info — mutual navigation links are intentional in hypertext docs
and never block CI.

🛡 Hex Shield

New credential pattern: hex-encoded-payload — 3 or more consecutive \xNN
escape sequences. Catches obfuscated payloads embedded in documentation source,
including inside fenced code blocks.

💡 Signal-to-Noise Control

info findings are suppressed by default. A footer note counts them:
"N info findings suppressed — use --show-info for details."
Available on all 7 check commands.

🐛 ZRT-005 Bootstrap Paradox

zenzic init now works correctly in a completely empty directory. The generated
zenzic.toml includes a commented Shield block documenting all 8 credential
pattern families.

---

What's Changed

• validator.py — iterative DFS graph integrity, Blood Sentinel classification
• reporter.py — security_incident badge, show_info filter, suppression note
• cli.py — --show-info on all 7 commands, Shield block in init template
• shield.py — hex-encoded-payload pattern family
• checks.md (EN+IT) — Blood Sentinel, Circular Links, References/Shield section
• architecture.md (EN+IT) — new, documents O(V+E) graph integrity design
• INTERNAL_GLOSSARY.toml — canonical EN/IT term registry
• 3 terminal SVG screenshots integrated into the manual
• Shield comment block in all 9 example zenzic.toml files
• safety_demonstration.md — live Sentinel demo for first-time users

759 tests · preflight green · bilingual docs (EN + IT)

---

Full Changelog: v0.5.0a3...v0.5.0a4

v0.5.0a3 — The Sentinel: Smart Init, Mutation War & Aesthetic Sprint

GitHub Release

Tag: v0.5.0a3

Release title:
v0.5.0a3 — The Sentinel: Smart Init, Mutation War & Aesthetic Sprint

Release description:

Highlights

Smart Initialization — zenzic init now detects pyproject.toml and offers to
embed configuration as [tool.zenzic] instead of creating a standalone zenzic.toml.
Use --pyproject to skip the prompt. Engine auto-detection works in both modes.

Mutation Testing Campaign — 80 new targeted tests raise mutation score from 58%
to 86.7% on rules.py (target was 75%). Hypothesis property-based testing integrated
with tiered profiles (dev/ci/purity).

The Breathing Sentinel — native col_start/match_text propagation replacing
fragile regex workarounds. Surgical caret rendering, traceback gutter with 2-space
padding, and vertical breathing between findings.

Agnostic Target — zenzic check all README.md or zenzic check all content/
scopes audits to a single file or directory. VanillaAdapter auto-selected for
out-of-docs targets.

Plugin SDK — zenzic init --plugin <name> scaffolds a ready-to-edit rule package.
zenzic.rules public namespace is now stable.

Z001/Z002 Split — broken links (error) vs orphan-page links (warning).

Quality Gates

pytest             706 passed, 0 failed
coverage           ≥ 80% branch (hard gate)
mutation score     86.7% (242/279 killed on rules.py)
ruff check src/    0 violations
mypy src/          0 errors
reuse lint         compliant
zenzic check all   7/7 OK (self-dogfood)

Install / Upgrade

uvx --pre zenzic check all           # zero-install one-shot (requires --pre for alpha)
uv tool install zenzic==0.5.0a3      # pin this exact pre-release
pip install zenzic==0.5.0a3          # pin this exact pre-release

Full changelog: CHANGELOG.md · Release notes: RELEASE.md

---

v0.5.0a2: The Refined Sentinel (Native UI & Unified Workflow)"

🛡️ Zenzic v0.5.0a2 — The Refined Sentinel

Second alpha of the v0.5 "Sentinel" cycle. This release is a consolidation sprint focused on developer experience, package honesty, UI professionalization, and toolchain hardening.

🌀 What's new

Lean & Agnostic by Design
The zenzic[docs] public extra has been removed. Zenzic performs static analysis of your configuration files — it does not execute the build engine or its plugins. Install MkDocs independently; Zenzic stays lightweight and dependency-free.

Unified Developer Workflow via just
Contributors now have a single, coherent command surface.

• just check: The Sentinel's self-linting duty (Zenzic vs Zenzic).
• just verify: The pre-push quality gate (Preflight + Production build).
• just sync, just build, just serve: Standardized environment and doc management.

Native Material UI Restoration
Removed custom header overrides in favor of native MkDocs-Material Tabs. The repository widget now displays stars, forks, and versioning on a single horizontal line, following industry best practices for a clean, professional look.

Toolchain & Security Hardening

• PEP 440 Compliance: bump-my-version is now hardened to handle alpha sequences (a2 → a3) automatically.
• Dependency Refresh: Updated 115 packages, resolving potential security vulnerabilities and upgrading to mkdocs-material v9.7.6.

📋 Full changelog

See CHANGELOG.md — ## [0.5.0a2] section.

v0.5.0a1 The Sentinel

Summary

v0.5.0a1 "The Sentinel" finalizes the adaptive scanning milestone with a deterministic, allowlist-driven plugin model, improved runtime efficiency, and fully green release gates.

Highlights

• Plugin-enabled scanning with Safe Harbor semantics

  • Added explicit plugins = [...] allowlist support in configuration.
  • Rule loading is deterministic and controlled.
  • Duplicate configured plugin IDs are now de-duplicated while preserving declaration order.

• Unified adaptive scan API

  • scan_docs_references(...) -> (reports, link_errors) is the single entry point.
  • Sequential/parallel execution remains adaptive by repository size.

• Parallel link-validation optimization

  • In parallel + validate_links=True, Phase B now collects links without re-running rule checks.

• Runtime robustness and UX

  • Added fail-fast validation for invalid workers values.
  • Improved technical docstrings around read behavior and execution model.

• Plugin discovery stability

  • Plugin list output is deterministically sorted, including core fallback scenarios.

• Documentation polish

  • Added/updated release-track messaging.
  • Fixed Italian wording in docs/it/about/index.md.

Verification

• Full preflight pipeline passed (ruff, mypy, pytest, reuse, docs build, self-check).
• Test suite green with coverage threshold satisfied.

v0.4.0-rc5

Zenzic v0.4.0-rc5

Release date: 2026-04-01
Status: Release Candidate

Highlights

• Synced ZensicalAdapter to the official Zensical v0.0.31+ schema ([project].nav).
• Improved MkDocs static parsing resilience for:
  • !ENV, !relative, and unknown YAML tags
  • plugin declarations in both mapping and list formats
• Fixed orphan detection to rely on adapter route classification (engine semantics), not raw set subtraction.
• Restored and hardened language switcher behavior in the custom Material header override.
• Added canonical fixtures:
  • examples/mkdocs-basic/
  • examples/zensical-basic/
• Completed EN/IT documentation parity updates for migration guidance, architecture notes, changelog, and README.
• Finalized version alignment to 0.4.0rc5 across package and docs metadata.
• Removed .zenzic-score.json from tracking and kept it ignored as derived metadata.

What Is Included In RC5

• Zensical v0.0.31+ compatibility sync
• MkDocs compatibility and resilience hardening
• documentation and examples coherence pass
• scanner semantics fix that resolves false orphan reports in self-audit

Deferred

• Multiprocessing CLI/runtime rollout is deferred to a later cycle.

Validation

• uv run nox -s preflight
• BUILD_DATE=dev uv run mkdocs build --strict
• zenzic check all --strict
• Full test suite passed (535 passed)

Upgrade Notes

• No breaking config change for MkDocs users.
• Projects using Zensical should use [project].nav as the canonical nav schema.
• .zenzic-score.json is intentionally no longer versioned.

🚀 Release v0.4.0-rc4 — The Virtual Site Map Edition

🇬🇧 English

🚀 Overview

Zenzic v0.4.0-rc4 marks a major milestone in documentation linting. By introducing the Virtual Site Map (VSM), Zenzic now understands the "intent" of your build engine, allowing for unprecedented accuracy in link validation and internationalization (i18n) support.

🌀 Major Features

• Virtual Site Map & Ghost Routes: Support for MkDocs-Material's automatic language switchers. No more false positives for /it/ or /fr/ routes that exist in the build but not in the source tree.
• Tiered SHA-256 Caching: Up to 90% faster incremental runs. Zenzic now remembers which files are valid and only re-checks what actually changed.
• Standardized Rule Engine: Introduction of the Z001 (Broken Link) rule powered by VSM. Errors now provide raw source context for a better developer experience.
• O(n) Performance: Engineered for scale. Whether you have 10 files or 10,000, Zenzic remains lightning fast.

🛠 Technical Internals

• Migrated from RuleFinding to the rich Violation dataclass.
• Implemented BaseRule.check_vsm() for routing-aware linting.
• Enhanced MkDocsAdapter with redundant configuration warnings (e.g., extra.alternate detection).

Tech Lead Note:
"With rc4, Zenzic evolves from a simple linter into a robust static analysis framework. We've proven that extreme performance can coexist with architectural purity."

---

🇮🇹 Italiano

🚀 Panoramica

Zenzic v0.4.0-rc4 segna una pietra miliare nel linting della documentazione. Introducendo la Virtual Site Map (VSM), Zenzic ora comprende l'"intento" del motore di build, permettendo una precisione senza precedenti nella validazione dei link e nel supporto all'internazionalizzazione (i18n).

🌀 Novità Principali

• Virtual Site Map & Ghost Routes: Supporto per i selettori lingua automatici di MkDocs-Material. Niente più falsi positivi per le rotte /it/ o /fr/ che esistono nel build finale ma non nell'albero dei sorgenti.
• Cache SHA-256 a livelli: Esecuzioni incrementali fino al 90% più veloci. Zenzic ora ricorda quali file sono validi e ricontrolla solo ciò che è effettivamente cambiato.
• Rule Engine Standardizzato: Introduzione della regola Z001 (Broken Link) basata su VSM. Gli errori ora forniscono il contesto sorgente "raw" per una migliore esperienza di sviluppo (DX).
• Performance O(n): Progettato per la scalabilità. Che tu abbia 10 file o 10.000, Zenzic rimane velocissimo.

🛠 Dettagli Tecnici

• Migrazione da RuleFinding alla ricca dataclass Violation.
• Implementazione di BaseRule.check_vsm() per un linting consapevole del routing.
• Potenziamento di MkDocsAdapter con avvisi per configurazioni ridondanti (es. rilevamento di extra.alternate).

Nota del Tech Lead:
"Con la rc4, Zenzic si evolve da semplice linter a un robusto framework di analisi statica. Abbiamo dimostrato che performance estreme possono coesistere con la purezza architetturale."

---

Full Changelog: [v0.3.0-rc3...v0.4.0-rc4]