Welcome to sv-nd-scribe - NaturalDocs and Linting for SystemVerilog!

Never write undocumented or unformatted SystemVerilog again.

The sv-nd-scribe toolkit combines:

• NaturalDocs-based documentation rules
• Static linter for detecting issues in source files
• AI agent with deterministic syntax auto-fixers, LLM backends, and TODO [SVND]: placeholder resolvers
• Workspace setup doctor that validates prerequisites and automatically repairs missing configurations
• Model Context Protocol (MCP) server for AI assistants/IDEs
• Curated knowledge base of 14 SystemVerilog documentation skills
• VS Code extension for real-time in-editor feedback and Quick Fix actions

sv-nd-scribe is available under the MIT License and can be used without restriction in both open-source and commercial applications.

Also, check out other open-source projects by IC Verimeter:

• The Shunt: An Open Source Client/Server TCP/IP socket-based communication library designed for integrating SystemVerilog simulations with external applications in C, SystemC, and Python.
• SVDB Gateway: A bridge between SystemVerilog and SQLite databases, allowing SystemVerilog code to interact with SQLite through the Direct Programming Interface (DPI).
• icecream_sv: IceCream for SystemVerilog!

---

🚀 Fast Track for VS Code users: Jump directly to the VS Code 3-Step Getting Started Guide to set up and verify in under 2 minutes.

---

Documentation Map

Each core subsystem of sv-nd-scribe has its own dedicated documentation:

Component	Description	Documentation Link
🔍 Static Linter	AST-based static analyzer with .f manifest and JSON output support	linter/README.md
📋 Linting Rules	Full catalog of all 41 Wellknown (WKL) and NaturalDocs (ND) rules	linter/rules/RULES.md
🤖 AI Agent & Auto-Fixer	Deterministic syntax engine, TODO [SVND]: resolver, comment cleaner, LLM backends, and setup doctor	agent/README.md
🔌 MCP Server	Model Context Protocol server exposing lint, check, and fix tools to AI IDEs	agent/README.md#model-context-protocol-mcp-server
📚 Skills Knowledge Base	14 reference guides, technical documentation standards, and troubleshooting skills	skills/README.md
💻 VS Code Extension	Real-time diagnostics, Lightbulb (Ctrl+.) Quick-Fixes, TODO resolvers, and auto-fix	vscode/README.md · ⚡ Quick Start

---

Getting Started (3 Steps)

Get up and running in under 2 minutes:

---

Step 1 — Clone the Repository & Check Prerequisites

Clone the sv-nd-scribe repository to your local machine:

git clone https://github.com/xver/sv-nd-scribe.git
cd sv-nd-scribe

Ensure the following prerequisites are installed:

1. Python 3.9+ (python3 --version or python --version)
   • Linux: sudo apt update && sudo apt install -y python3 python3-pip
   • macOS: brew install python
   • Windows: Install from python.org (check "Add Python to PATH").
2. Verible (verible-verilog-syntax --version)
   • Download prebuilt binaries from the ChipsAlliance Verible releases page and ensure verible-verilog-syntax is in your PATH (or set VERIBLE_HOME).
   • WSL Note: A Windows .exe build of Verible in your Windows PATH is reachable in WSL automatically as verible-verilog-syntax.exe.
3. PyYAML

   pip install pyyaml

---

Step 2 — Run Automated Workspace Setup

From the repository root, run the setup automation:

cd makedir && make setup_workspace
# or:
python3 makedir/setup_workspace.py

This single command automatically configures:

• .vscode/settings.json — Preconfigures linter and agent paths, terminal environment variables, and .sv/.svh/.v file associations.
• .env — Generates workspace root environment file (SVND_SCRIBE_HOME, PYTHONPATH, SV_ND_SCRIBE_PROJECT_CONFIG).
• makedir/env.sh — Creates shell sourcing script for terminal command lines (source makedir/env.sh).
• linter/configs/lint_config.json — Prepares default linter configuration.

---

Step 3 — Verify Environment & Install VS Code Extension

Option A: Terminal Verification with Agent Doctor

# Source environment variables
source makedir/env.sh

# Run comprehensive environment doctor (7 health checks)
python3 -m agent --doctor

Auto-Repair: If any check fails, run python3 -m agent --fix-setup to automatically repair missing files and configurations.

Option B: VS Code Extension Verification

1. Install the packaged extension:

   code --install-extension vscode/sv-nd-scribe-vscode-0.1.8.vsix

2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run:
   SV_Scribe: Verify linter installation
3. If any configuration is missing, click "Auto-Fix with Agent" directly in the notification.

---

Quick Start & CLI Reference

1. Automation via Makefile

The makedir/ directory contains automation targets for linting, documentation, testing, and IDE configuration:

cd makedir

# Auto-configure workspace environment (.vscode/settings.json, .env, shell env)
make setup_workspace

# Check linter dependencies and environment health
make status

# Check AI agent status and LLM connectivity
make agent_status

# Lint production template files
make lint

For complete Makefile options, see Running the Linter.

---

2. Running the Static Linter

Lint individual files or batch process manifests using standard .f files:

# Check dependencies
python3 -m linter --status

# Lint specific SystemVerilog files
python3 -m linter src/my_module.sv src/my_if.sv

# Batch lint with manifest
python3 -m linter -f makedir/template_sv.f

👉 Full linter documentation: linter/README.md
👉 Complete rule catalog (41 rules): linter/rules/RULES.md

---

3. Running the AI Fixer Agent

Automatically resolve linter violations using high-speed deterministic transforms or LLMs:

# Comprehensive environment health check
python3 -m agent --doctor

# Auto-repair missing workspace settings and configurations
python3 -m agent --fix-setup

# Check agent status and provider configuration
python3 -m agent --status

# Deterministic batch fix (CI/CD mode, no backups)
python3 -m agent --llm none --batch --no-backup -f makedir/template_sv.f

# Dry-run preview: display proposed diffs without writing to disk
python3 -m agent --dry-run tests/test_bad_sv/nd_driver.sv

# Resolve a specific TODO [SVND]: marker near a line number (e.g. line 42)
python3 -m agent --resolve-todo 42 src/my_module.sv

# Resolve all TODO [SVND]: and placeholder markers across a file
python3 -m agent --resolve-todo src/my_module.sv

# Remove redundant and nested comment markers (e.g. // /* or // //)
python3 -m agent --clean-comments src/my_module.sv

# Re-apply corporate header template
python3 -m agent --overwrite-header src/my_module.sv

👉 Full AI agent and CLI guide: agent/README.md

---

4. Model Context Protocol (MCP) Server

Connect sv-nd-scribe tools directly to AI assistants and IDEs (Antigravity, Cursor, Claude Desktop, VS Code MCP):

{
  "mcpServers": {
    "sv-nd-scribe": {
      "command": "python3",
      "args": ["-m", "agent.mcp_server"],
      "env": {
        "SVND_SCRIBE_HOME": "/path/to/sv-nd-scribe"
      }
    }
  }
}

Tools provided: list_violations, check_file, fix_file, get_status.

👉 MCP Server guide and tool reference: agent/README.md#model-context-protocol-mcp-server

---

5. NaturalDocs Skills Knowledge Base

A library of 14 modular skills defining syntactic standards, comment structures, and setup diagnostics:

• Setup & Environment: setup_troubleshooter
• File & Containers: file_header, sv_constructs, group_heading
• Methods & Logic: function_task, process_assign, assertion_property
• Data & Types: type_doc, variable_doc, inline_doc, coverage_doc
• Conventions & Quality: nd_comment, sv-technical-doc, triage

👉 Full skills catalog & keyword tables: skills/README.md

---

6. VS Code Extension

Install the packaged extension (v0.1.8) for in-editor linting, Lightbulb (Ctrl+.) Quick-Fix actions, interactive TODO [SVND]: marker resolution, redundant comment cleaning, 7-step setup verification, and header template management:

# Install the extension
code --install-extension vscode/sv-nd-scribe-vscode-0.1.8.vsix

# Configure workspace environment: .vscode/settings.json, .env, shell env variables
cd makedir && make setup_workspace

👉 VS Code 3-Step Quick Start: vscode/README.md#getting-started-3-steps
👉 Full VS Code extension guide: vscode/README.md

---

Support

For assistance with integration or customization, contact us at icshunt.help@gmail.com.

Report bugs and feature requests to GitHub Issues.

---

Copyright (c) 2026 IC Verimeter