Zenzic VS Code Extension¶

The official Zenzic VS Code Extension (pythonwoods.zenzic-vscode) brings sub-50ms deterministic diagnostics, credential scanning, and real-time topological validation directly into your authoring environment.

Thin Client Architecture¶

The extension is designed as a Thin Client. It contains zero parsing engines, zero regex logic, and zero validation rules.

Instead, it relies on the Language Server Protocol (LSP) over stdio to communicate directly with your local Zenzic Python binary (zenzic lsp). This guarantees 100% parity between local editor feedback and CI/CD pipeline enforcement.

flowchart LR
    VS["VS Code Extension<br><code>pythonwoods.zenzic-vscode</code>"] <-->|"JSON-RPC 2.0 (stdio)"| ZLS["Zenzic Language Server<br><code>zenzic lsp</code>"]

    style VS fill:#0284c7,stroke:#0369a1,color:#ffffff,stroke-width:2px
    style ZLS fill:#4f46e5,stroke:#4338ca,color:#ffffff,stroke-width:2px

Requirements¶

• Zenzic Core: v0.30.0 or higher. Automatically provisioned on first use if not present (see the Auto-Provisioning section).
• VS Code: v1.125.0 or higher.

Installation & Setup¶

code --install-extension pythonwoods.zenzic-vscode

# Recommended: Global binary via uv
uv tool install --force zenzic

# Alternative: Standard pip install
pip install zenzic

Auto-Provisioning¶

Starting with v0.31.0 of the VS Code extension, manual installation of the Zenzic CLI is optional for VS Code users.

On first activation, if the extension cannot find a zenzic binary (via the configured path, system $PATH, or standard binary locations), it shows a consent prompt:

Zenzic CLI not found. Install it automatically in an isolated environment?

Clicking Install triggers the Auto-Provisioning Engine, which:

1. Creates an isolated virtual environment inside VS Code's own global storage (~/.config/Code/User/globalStorage/pythonwoods.zenzic-vscode/env/).
2. Installs zenzic >= 0.30.0 using uv pip install (primary path) or pip install in a python3 -m venv (fallback).
3. Verifies the installed binary version before starting the Language Server.
4. Persists the binary path in VS Code globalState to skip re-installation on subsequent activations.

To disable auto-provisioning (e.g., for corporate proxy environments or air-gapped machines), set the following in your user or workspace settings:

{
  "zenzic.autoProvision": false
}

When autoProvision is false, the extension reverts to the manual-install flow and displays an actionable error message with a link to the installation documentation.

Path Resolution & Local Development¶

The extension resolves the zenzic executable using a strict deterministic priority order:

1. Explicit Custom Path: If zenzic.executablePath is set (e.g. ${workspaceFolder}/.venv/bin/zenzic or ~/bin/zenzic), the extension tests and uses this explicit path first, scanning across all active workspace folders in multi-root setups.
2. Active Virtual Environment: Any active virtual environment on the current system or shell $PATH.
3. Global System $PATH: System directories containing a globally installed zenzic executable.
4. Fallback Directories: Standard user-level binary directories (~/.local/bin, ~/.cargo/bin, ~/.uv/bin).
5. Auto-Provisioned Isolated Engine: The sandboxed virtual environment in VS Code global storage (pythonwoods.zenzic-vscode/env/).

Configuration¶

The extension automatically discovers zenzic in standard $PATH directories and user bin locations (~/.local/bin, ~/.cargo/bin, ~/.uv/bin).

If you use a custom virtual environment or isolated installation, configure zenzic.executablePath in your workspace settings.json:

{
  "zenzic.executablePath": "${workspaceFolder}/.venv/bin/zenzic"
}

Supported Settings¶

Commands¶

The extension contributes the following commands to the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Inline Diagnostics & Code Actions¶

The extension exposes real-time LSP diagnostics directly in the PROBLEMS panel and editor margin.

Zenzic provides automated Quick Fixes for specific structural and content findings (e.g., injecting placeholder text for empty links Z108, adding language tags to code blocks Z505, and removing dead suppressions Z603).

In addition, Zenzic offers automated "Suppress this finding" Code Actions (<!-- zenzic:ignore:ZXXX -->) for all suppressible diagnostics. Hovering over a finding allows you to insert an inline suppression directive on the line above with a single click. To enforce security governance, suppression Code Actions are intentionally disabled for Security findings (Z2xx), which must be remediated at the source.

Domain Boundaries & Supported Files¶

To uphold Domain-Aware Discovery and Radical Unawareness:

• File Extensions: The extension and Language Server exclusively target Markdown (.md) and MDX (.mdx) files. Non-documentation files (e.g. OWNERS, .gitignore, config.yaml) are automatically filtered out.
• Configured Domain: Only files residing within the configured docs_dir (default: docs/) or extra_content_roots are evaluated. Out-of-bounds files in the workspace (such as root README.md when docs_dir = "docs") produce zero diagnostics.

Having issues? See the Troubleshooting Guide.