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.

┌─────────────────────────┐   JSON-RPC 2.0 (stdio)   ┌──────────────────────────────┐
│  VS Code Extension      ├─────────────────────────►│  Zenzic Language Server      │
│  (pythonwoods-vscode)   │◄─────────────────────────┤  (zenzic lsp)                │
└─────────────────────────┘                          └──────────────────────────────┘

Requirements & Baseline¶

Zenzic Core: v0.23.1 or higher installed on your system or virtual environment.
VS Code: v1.125.0 or higher.

Installation¶

1. Install the Core Engine¶

The VS Code extension requires the Zenzic Python core binary to perform analysis:

uv tool install --force zenzic

Alternatively, install via pip or inside your active virtual environment:

pip install zenzic

2. Install the Extension¶

Search for Zenzic in the VS Code Extensions panel (Ctrl+Shift+X / Cmd+Shift+X), or install via the VS Code CLI:

code --install-extension pythonwoods.zenzic-vscode

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 VS Code settings.json:

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

Supported Settings¶

Setting	Type	Default	Description
`zenzic.executablePath`	`string`	`"zenzic"`	Absolute path or binary name for the Zenzic executable.

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.

Troubleshooting¶

`Zenzic: Not Found (ENOENT)`¶

Symptom: Status bar shows $(error) Zenzic: Not Found or prompt reads Zenzic binary not found.

Cause: The zenzic executable is not installed or not present in system $PATH / standard user directories (~/.local/bin, ~/.uv/bin).

Resolution: 1. Install Zenzic globally via uv tool install zenzic. 2. Or configure zenzic.executablePath in VS Code settings with the full path to your virtual environment binary (e.g., /home/user/project/.venv/bin/zenzic).

`Zenzic: Outdated Core`¶

Symptom: Status bar shows $(error) Zenzic: Outdated Core or notification requests upgrading.

Cause: The installed Zenzic Core binary version is lower than the required minimum baseline (v0.23.1).

Resolution: Update the Zenzic executable to the latest version:

uv tool install --force zenzic

Server Version Check Errors¶

Symptom: Notification reads Could not verify Zenzic Core version.

Cause: Executing zenzic --version returned an error or non-zero exit code.

Resolution: Verify that zenzic --version runs cleanly in your terminal and check permissions on zenzic.executablePath.