Skip to content

Your First Audit

What you'll achieve: go from zero to a passing Zenzic report in under three minutes. Zenzic detects leaked credentials, orphan pages, and broken links. No configuration file required to start.

Prerequisites

You need uv on your PATH. Everything else is handled automatically.

Why start with the Lab?

zenzic lab runs every scanner against pre-built fixtures. It covers a security breach scenario and a clean-documentation scenario. Total run time: under 60 seconds.

Step 1 — Run Zenzic without installing it

Point Zenzic at your project root. No virtual environment, no pip install:

uvx zenzic check all

uvx fetches Zenzic in an isolated environment and discards it when the command finishes. Run this from the directory that contains your .zenzic.toml (or from the repo root). Zenzic auto-discovers the configuration and activates the correct engine — including orphan detection (Z402) when a nav contract is present. If a blog/ directory exists on disk, zenzic check all includes blog posts in the scan scope automatically. No extra setting required. No blog_dir to configure. This is the recommended workflow for CI and for trying Zenzic on an unfamiliar repo.

Step 2 — Credential Scanner Live Demo

Before configuring anything, watch Zenzic protect a deliberately broken repo:

Credential scanner demo — run the Z201 credential scenario:

uvx zenzic lab z201

Zenzic scans the bundled z201-credentials fixture and fires exit code 2 with the 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.

Link Integrity Demo (Zenzic Audit Badge) — now run the Z101 LINK_BROKEN scenario:

uvx zenzic lab z101

The Zenzic Audit Badge: link findings detected, exit 1. The contrast is the proof — the same engine that caught the secret confirms that clean documentation is genuinely clean.

Interactive Demo — No installation required

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_SECRET), uvx zenzic lab z101 (LINK_BROKEN).

Step 3 — Initialize your Exclusion Zone

When you're ready to commit Zenzic to your project, generate a .zenzic.toml in one command:

Workspace required

Zenzic analyses workspaces, not arbitrary directories. It performs an upward traversal from the target path to locate a root marker (.git/ or .zenzic.toml). If you see:

ERROR: Could not locate repo root: no .git directory or .zenzic.toml found

Run zenzic init in the root directory of your project to establish the workspace boundary. See Discovery & Exclusion — The Authority of Root for the full rationale.

cd your-project/
zenzic init

Zenzic inspects the directory and pre-configures the engine for you:

Created .zenzic.toml
  Engine pre-set to mkdocs (detected from mkdocs.yml).

Edit the file to enable rules, adjust directories, or set a quality threshold.
Run zenzic check all to validate your documentation.

The generated file is annotated — every option is commented out with a short explanation. Open it, uncomment what you need, leave the rest.

Using pyproject.toml?

zenzic init --pyproject

This appends a [tool.zenzic] section to your existing pyproject.toml instead of creating a separate file.

Step 4 — Run your first real audit

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. For details on exit code definitions and security tiers, see the Exit Code Contract.

A clean run looks like this — the Zenzic Audit Badge:

Exit 0 confirms that every link resolves, every page is reachable, and no credential is exposed within the analyzed scope.

Deliberate Failure — The Traceability Proof

Insert a broken link in any file:

docs/intro.md
[See the guide](./nonexistent-page.md)

Run zenzic check all. The finding is exact:

docs/intro.mdx:3  Z101  Internal link resolves to no page in the VSM  → ./nonexistent-page.mdx

File path. Line number. Finding code. No finding without a physical origin. This is deterministic traceability — the same guarantee in CI as in local development.

Run uvx zenzic score on your own repo to obtain a baseline score without installing anything.

What's next?

  • Measure your score — run uvx zenzic score to get a precise 0–100 baseline for your repo
  • Add a CI gate — see CI/CD Integration for automated quality enforcement
  • SARIF export — zenzic check all --format sarif for GitHub Code Scanning inline annotations
  • Strict mode — add --strict to also validate external URLs
  • Custom rules — add [[custom_rules]] entries to .zenzic.toml to enforce your own patterns
  • Finding codes — see the Finding Codes reference for the full

Zxxx diagnostic catalogue