Deterministic audit of documentation structures with bidirectional traceability.
Tiered code governance, frozen security contracts, and RE2-backed deterministic scanning.

---

⚡ Try it now — Zero Installation

Got a folder of Markdown files? Run an instant security and link audit using uv:

uvx zenzic check all ./your-folder

Zenzic identifies your engine via its configuration files or defaults to Standalone Mode for plain Markdown folders — providing immediate protection for links, credentials, and file integrity.

---

🚀 Quick Start

pip install zenzic
cd my-docs-repo
zenzic init       # Establish the workspace boundary (creates .zenzic.toml)
zenzic check all  # Audit the current directory

🧠 Core Pillars

• Pure, deterministic engine: identical inputs produce identical findings and exits.
• Tiered code model: Core, Structure, and Governance findings grouped by tier.
• Frozen contracts for integrators: FROZEN_CODES, NON_SUPPRESSIBLE_CODES, and PLUGIN_FORBIDDEN_EXITS provide stable enforcement surfaces for CI and plugins.
• Inspect-first workflow: use zenzic inspect codes to validate live code semantics before touching docs or release notes.

📖 Full docs → · 🏅 Badges · 🔄 CI/CD guide

---

⚙️ Commands Overview

Command	Purpose
zenzic init	Scaffold workspace configuration (.zenzic.toml)
zenzic check all [PATH]	Full documentation audit — links, credentials, orphans
zenzic score [--fail-under N] [--stamp]	Compute the Documentation Quality Score (0–100)
zenzic diff [--base PATH]	Detect debt regression against a saved baseline
zenzic guard scan [PATH]	Defense-in-Depth credential pre-gate (fatal on security findings: exit 2)
zenzic inspect codes	Query live error-code semantics and suppressibility

---

🚀 CI/CD Ready: Use the Official Zenzic Action to run Zenzic in GitHub Actions — findings surface directly in Code Scanning, PR annotations, and the Security tab.

- uses: PythonWoods/zenzic-action@v1
  with:
    format: sarif
    upload-sarif: "true"

---

🔌 Multi-Engine Support

Engine	Adapter	Highlights
Docusaurus	DocusaurusAdapter	Versioned docs, @site/ alias, Ghost Route detection
MkDocs	MkDocsAdapter	i18n suffix + folder modes, fallback_to_default
Zensical	ZensicalAdapter	Transparent Proxy bridges mkdocs.yml
Any folder	StandaloneAdapter	File integrity checks — orphan detection disabled without a nav contract

See the Adapter API for the plugin interface. Third-party adapters install via the zenzic.adapters entry-point group.

---

⚙️ Configuration

Zero-config by default. See the Configuration Guide for the full .zenzic.toml schema and pyproject.toml embedding.

zenzic init        # Generate .zenzic.toml with auto-detected values

---

🔄 CI/CD Integration

- uses: PythonWoods/zenzic-action@v1
  with:
    format: sarif
    upload-sarif: "true"

For zero-install uvx integration and regression gates, see the CI/CD guide.

---

📦 Installation

# Zero-install, one-shot audit (recommended for CI and exploration)
uvx zenzic check all ./docs

# Global CLI tool
uv tool install zenzic

# Pinned dev dependency
uv add --dev zenzic

# pip
pip install zenzic

---

📖 Documentation

Area	URL	Audience
👤 User Guide	zenzic.dev/docs	Install, configure, CI/CD, finding codes
🔧 Developer Portal	zenzic.dev/developers	Adapters, ADRs, CLI architecture, mutation testing
🛡️ Security	Engineering Ledger · SECURITY.md	Security reviewer

---

🤝 Contributing

1. Open an issue to discuss the change.
2. Read the Contributing Guide.
3. Every PR must pass just verify and include SPDX headers on new files.

See also: Code of Conduct · Security Policy

📎 Citing

A CITATION.cff is present at the root. Click "Cite this repository" on GitHub for APA or BibTeX output.

📄 License

Apache-2.0 — see LICENSE.

---

Engineered with precision by PythonWoods in Italy 🇮🇹
"Building the Standard for Technical Document Integrity."

Documentation · GitHub · Blog