Zenzic: Deterministic Documentation Quality Platform (DQP) for Engineering-Grade Knowledge Systems.
Stop broken links, leaked secrets, accessibility defects, and topological graph errors before they reach production.

---

Documentation Quality Platform (DQP)

A Documentation Quality Platform (DQP) enforces semantic correctness, structural topology, and governance policies across Markdown and MDX graphs. It treats documentation as a continuously validated engineering asset.

Where standard linters operate on isolated source files, a Documentation Quality Platform compiles and evaluates the entire knowledge graph as a unified, deterministic system.

Category Differentiation

Capability	Syntax Formatters & AST Linters	Prose & Style Checkers	Zenzic (DQP)
Scope of Analysis	Single file AST / formatting	Single file prose & dictionaries	Global graph topology & cross-file VSM
Link & Anchor Resolution	None	None	$O(N)$ cross-file & framework slug parity
Security Verification	None	None	Secret leak & path traversal guards (Exit Codes 2 & 3)
Technical Debt Management	Inline ignores only	Config ignores	Cryptographic baselines (.zenzic-baseline.json) & DQS scoring
Governance & Policy	Syntax rules	Style rules	Policy-as-Code schema enforcement & suppression budgeting
Enterprise Telemetry	Text stdout	Text stdout	Enriched SARIF v2.1.0 for security dashboards

• vs Syntax Formatters & AST Linters: While syntax formatters enforce whitespace, indentation, and isolated AST structure within individual files, Zenzic validates global graph topology (Virtual Site Map), cross-file reference integrity, and structural reachability.
• vs Prose & Style Checkers: While prose checkers validate dictionaries, readability scores, and stylistic tone, Zenzic enforces Policy-as-Code, tracks technical debt via cryptographic baselines, and provides deterministic security scanning against secret leaks and path traversal.
• Complementary Architecture: Zenzic runs alongside syntax formatters and style checkers in modern CI/CD pipelines, acting as the overarching Documentation Quality Platform for structural, security, and governance integrity.

---

Core Pillars (v0.30)

• Smart Link Graph: Fast $O(N)$ topological graph analysis with exact slugification parity for documentation frameworks, orphan detection, and circular link diagnostics (Z410, Z411).
• Baseline & Regression Tracking: Line-shift invariant debt freezing (.zenzic-baseline.json), allowing existing repositories to adopt strict quality gates immediately without blocking development.
• Policy-as-Code Governance: Centralized configuration rules for frontmatter schemas, domain allowlists, terminology restrictions, and suppression budgeting.
• Ecosystem Uniformity: 100% deterministic parity across the Zenzic CLI (Core Engine), VS Code Extension (Language Server Protocol), and GitHub Action CI/CD workflow.

---

⚡ Quick Start (< 60 Seconds)

1. Install Zenzic

Get started in 2 seconds with uv:

# Recommended: isolated tool install via uv
uv tool install zenzic

# Or run ephemerally without installing
uvx zenzic@0.30.0 check all

# Or via standard pip
pip install --upgrade zenzic

2. Initialize and Verify Your Repository

# Scaffold initial configuration
zenzic init

# Run full documentation graph analysis
zenzic check all

3. Automatically Fix Issues

# Preview automated fixes without touching files
zenzic fix --dry-run

# Atomically apply fixes across all Markdown documents
zenzic fix --apply

4. Git Pre-Commit Hook (Optional)

Catch broken links and leaked secrets before git commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/PythonWoods/zenzic
    rev: v0.30.0
    hooks:
      - id: zenzic-guard   # Fast staged-file credential scan
      - id: zenzic-verify  # Documentation integrity gate

---

🎯 What Zenzic Solves

┌─────────────────────────────────────────────────────────────────────────────┐
│                             ZENZIC CORE ENGINE                              │
├──────────────────────┬──────────────────────┬───────────────────────────────┤
│  🔗 Broken Links &   │  🔐 Leaked Secrets   │  ♿ Semantic Accessibility    │
│     Orphan Pages     │     & Credentials    │     & Editorial Governance    │
│  ──────────────────  │  ──────────────────  │  ───────────────────────────  │
│  • Cross-file links  │  • API tokens / keys │  • Duplicate headings (Z513)  │
│  • Anchor validation │  • AWS / Stripe keys │  • Generic image alt (Z514)   │
│  • Missing assets    │  • Path traversal    │  • Malformed lists (Z520)     │
│  • Unused images     │  • Non-suppressible  │  • Policy-as-Code (Z610–Z619) │
└──────────────────────┴──────────────────────┴───────────────────────────────┘

---

🛡️ Core Capabilities

1. High-Speed Graph Topology (VSM)

Zenzic's in-memory Virtual Site Map (VSM) indexes thousands of Markdown pages, anchors, and media assets in seconds. Renaming a document or moving a heading immediately flags all broken cross-references across the repository.

2. Zero Subprocesses & Deterministic Safety

• Zero Subprocesses (ADR-002): Analysis executes in-process without spawning external shell processes, guaranteeing maximum security and predictable sub-50ms execution.
• Google RE2 Regular Expressions: All pattern matching is protected against catastrophic backtracking (ReDoS) and unbounded execution loops.

3. Atomic Mutator (zenzic fix)

Remediation must be lossless and idempotent:

• Wraps bare URLs in standard <url> notation (Z515).
• Strips trailing punctuation from headings (Z517).
• Transforms fake paragraph lists into valid Markdown bullet lists (Z520).
• Injects missing language tags on code blocks (Z505).
• Cleans up dead inline suppressions (Z603).

4. Deterministic Quality Score (DQS)

Zenzic calculates a mathematical health score (0–100) based on active findings, severities, and technical debt. Enforce strict team standards in CI (fail_under = 90) and track improvements over time with status badges.

$ zenzic score

✨ Quality Score: 94/100

╭─ Quality Breakdown ──────────────────────────────────────╮
│   Category     Issues  Weight  Raw Pts  Applied Pts      │
├──────────────────────────────────────────────────────────┤
│ ✓ structural      0      30%      0           0          │
│ ✓ navigation      0      25%      0           0          │
│ ✗ content         2      20%     -4          -4          │
│ ✓ brand           0      25%      0           0          │
├──────────────────────────────────────────────────────────┤
│   Σ Subtotal                                96           │
╰──────────────────────────────────────────────────────────╯
  ! Technical Debt (2 suppressions)          -2 pts
  = Final Quality Score                      94 / 100

5. Policy-as-Code Governance

Define organizational conventions directly in .zenzic.toml:

[policies]
required_frontmatter_keys = ["title", "description"]
allowed_external_domains = ["github.com", "zenzic.dev"]
enable_passive_voice_check = true
weasel_words = ["clearly", "simply", "obviously"]
forbidden_content_patterns = ["(?i)\\bconfidential\\b"]
max_document_complexity = 45

6. Custom Rule SDK v3

Extend Zenzic with organization-specific invariants. The Custom Rule SDK v3 (zenzic.sdk) lets you author typed, deterministic AST visitor plugins in Python with guaranteed $O(N)$ execution and full SARIF integration.

---

🏗️ Architecture & Engine Deep Dive

Zenzic is engineered from the ground up as a deterministic compiler rather than a loose collection of linters. It delivers $O(N)$ execution speed, scanning thousands of Markdown documents in milliseconds through pure-function compilation and zero-subprocess architecture.

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ZENZIC COMPILATION PIPELINE                        │
├─────────────────┬─────────────────┬───────────────────┬─────────────────────┤
│  1. AST Parser  │  2. VSM Builder │  3. Rule Engine   │  4. Atomic Mutator  │
│  ────────────── │  ────────────── │  ──────────────── │  ────────────────── │
│  • Token stream │  • Global graph │  • Pure functions │  • AST patcher      │
│  • Heading tree │  • Route index  │  • RE2 regex ACL  │  • Idempotent fix   │
│  • Lossless map │  • Ghost routes │  • DQS evaluation │  • Zero formatting  │
│                 │                 │  • SARIF reporter │    corruption       │
└─────────────────┴─────────────────┴───────────────────┴─────────────────────┘

1. Lossless AST & Atomic Mutator (zenzic.core.mutator)

Unlike regex-based search-and-replace tools that corrupt code fences, frontmatter, and inline math, Zenzic parses Markdown into a structured Abstract Syntax Tree (AST).

Mutations are executed directly on AST nodes and serialized back through a lossless emitter, guaranteeing:

• Zero Syntax Corruption: Comments, indentation, code fences, and blank lines remain byte-for-byte identical outside the target node.
• Strict Idempotence: Running zenzic fix --apply multiple times produces the exact same AST state without duplicate edits: $$\text{mutate}(\text{mutate}(\text{AST})) = \text{mutate}(\text{AST})$$

2. Virtual Site Map (VSM) & Topological Graph (zenzic.core.vsm)

Zenzic builds an in-memory topological routing graph (the Virtual Site Map) across all documents and static assets in your workspace.

The VSM maintains:

• Exact Slug Parity: Heading anchors are slugified according to the active build adapter (MkDocs Material, Zensical, or Standalone) without running the generator itself.
• Cross-File Resolution: Validates relative paths, root-relative links, anchor fragments (#section-id), and media assets.
• Ghost Route Registry: Recognizes virtual and dynamically generated routes to eliminate false positives in complex documentation graphs.

3. Deterministic Quality Score (DQS) Mathematical Model

Zenzic computes an objective, reproducible 0–100 documentation quality score using a weighted deduction model:

$$\text{DQS} = \max\left(0, 100 - \sum \text{Penalties} - \text{Suppression Debt}\right)$$

Category	Severity Range	Description
Security (Z2xx)	10.0 pts (Fatal)	Leaked credentials, secret tokens, path traversal
Structure (Z1xx, Z516)	3.0–5.0 pts	Broken links, missing files, multiple H1 headers
References (Z3xx)	2.0–3.0 pts	Dead definitions, duplicate reference labels
Assets (Z4xx)	1.0–2.0 pts	Missing images, orphan assets, missing indexes
Content & A11y (Z5xx)	1.0–2.0 pts	Duplicate headings, generic alt text, malformed lists
Governance (Z6xx)	1.0–4.0 pts	Policy violations, forbidden terms, complexity caps

Under Zenzic's Flat-Cost Model, every inline suppression comment (<!-- zenzic:ignore ZXXX -->) costs exactly 1.0 DQS point, ensuring technical debt is visible, quantified, and capped (suppression_cap = 30).

4. RE2 Discipline & Sovereign Runtime (ADR-002, ADR-075)

• $O(N)$ Execution Performance: Scans thousands of Markdown files in milliseconds with linear time complexity and minimal memory overhead.
• Zero Subprocesses (ADR-002): Zenzic executes 100% in-process with zero subprocess.Popen invocations, ensuring safe, lightweight execution across sandbox environments.
• Google RE2 Non-Backtracking Engine: All regex operations are backed by Google RE2 via an Access Control Layer (zenzic.core.regex), guaranteeing $O(N)$ execution time and mathematical immunity to Regular Expression Denial of Service (ReDoS).
• Pure-Function Determinism: Analysis has zero global state and zero network dependencies, guaranteeing bit-for-bit identical results on every machine and operating system.

---

🛠️ CLI Commands & Tooling Capabilities

The zenzic CLI provides a complete suite of developer commands for local workflows, batch remediation, and CI/CD automation:

Command	Primary Use Case	Key Options
zenzic check	Run graph integrity, security, and quality analysis	all, --strict, --fail-under <N>, --format sarif
zenzic fix	Automatically apply idempotent AST mutations	--dry-run, --apply
zenzic score	Calculate DQS metrics and update status badges	--stamp, --check-stamp, --badge-json
zenzic audit	Generate formal compliance and technical debt reports	--format markdown, --output <file>
zenzic lab	Interactive finding lab and scenario runner	list, run <act-id>, inspect <act-id>
zenzic init	Scaffold .zenzic.toml configuration or plugin template	--pyproject, --local, --engine <name>, --plugin
zenzic config explain	Introspect active policies, discovery paths, and rules	--all, --json

---

📊 Headless Data Pipeline (SARIF v2.1.0)

Zenzic functions natively as a headless data compiler. For enterprise security and code scanning pipelines, Zenzic exports industry-standard SARIF v2.1.0 (Static Analysis Results Interchange Format):

# Output enriched SARIF for CI/CD ingestion
zenzic check all --format sarif --output results.sarif

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "zenzic",
          "version": "0.30.0",
          "rules": [
            {
              "id": "Z101",
              "shortDescription": { "text": "BROKEN_LOCAL_LINK" }
            }
          ]
        }
      }
    }
  ]
}

Every SARIF diagnostic includes:

• Precise 1-indexed line and column ranges.
• Deductive DQS score penalty and taxonomy category.
• Direct documentation remediation URLs (helpUri).
• Full rule descriptions and severity ratings (error, warning, note).

Seamlessly feeds directly into GitHub Code Scanning, SonarQube, GitLab Security Dashboards, and DefectDojo.

---

🔌 Multi-Engine Support & VSM Adapters

Documentation frameworks use varying link slugification, asset pathing, and directory index conventions. Zenzic bridges these differences through its Virtual Site Map (VSM) Adapter Architecture:

• MkDocs & Material for MkDocs: Parses mkdocs.yml, navigation hierarchies, and Material anchor slugification natively without invoking Python subprocesses.
• Zensical: Validates multi-language document hierarchies and configuration trees.
• Standalone / Standard Markdown: Performs universal link and asset resolution across any arbitrary directory structure.

---

🚦 CI/CD Enforcement & Exit Code Contract

Under ADR-075 (Radical Unawareness), Zenzic guarantees a strict exit code contract that CI/CD systems can rely on deterministically:

Exit Code	Meaning	CI Behavior
0	Success	All checks passed, or warnings managed within suppression budget.
1	Quality Gate Failure	Broken links, structural defects, or DQS score below fail_under.
2	Fatal Credential Leak	Leaked secrets or API keys. Non-suppressible security block.
3	Fatal Path Traversal	Directory traversal sequence detected. Non-suppressible security block.

---

🌐 The Unified Zenzic Ecosystem

Zenzic provides consistent, identical analysis across every development touchpoint:

Platform	Primary Use Case	Delivery
Zenzic CLI (Core)	Local development, batch auto-fixes, and scriptable audits	uv tool install zenzic
VS Code Extension	Real-time wavy-line diagnostics, LSP Quick Fixes (Ctrl+.), and status telemetry	VS Code Marketplace
GitHub Action	CI/CD pull request gate, SARIF Code Scanning alerts, and merge blocking	GitHub Marketplace

---

📖 Documentation & Guides

• Quick Start Tutorial: Step-by-step introduction.
• Finding Codes Catalog: Complete reference for all Z1xx–Z6xx finding codes.
• Policy-as-Code Guide: Enforce repository standards.
• Custom Rule SDK v3: Author deterministic, typed Python linting plugins.
• CI/CD Configuration: Set up automated GitHub Actions pipelines.

For deep architectural explanations, configuration strategies, and the full finding taxonomy, visit zenzic.dev.

---

🗺️ Roadmap

Zenzic evolves strictly within its deterministic, AST-driven architecture. Upcoming milestones include:

• Adapter Ecosystem: Native Virtual Site Map (VSM) adapters for Docusaurus, Sphinx (MyST), and Hugo to support cross-engine slugification and taxonomy out of the box.
• Multi-Repository Documentation Graph: Cross-repository link resolution and contract validation across polyrepo documentation architectures without network calls.
• Auto-Fix Expansion: Extended lossless AST mutations for additional structural codes (Z1xx), reference normalization (Z3xx), and frontmatter standardization (Z6xx).

---

📄 License

Licensed under the Apache License, Version 2.0. Copyright (c) 2026 PythonWoods <dev@pythonwoods.dev>.