Documentation Index

This page is the documentation front door for the perl-lsp workspace.

Diataxis Quick Guide

Use this quick classifier when you are reading or adding docs:

If your question sounds like...	Doc type	Primary docs folder
"Can you teach me this from scratch?"	Tutorial	docs/tutorials/
"How do I complete a specific task?"	How-to	docs/how-to/
"What is the exact behavior/contract?"	Reference	docs/reference/
"Why is it designed this way?"	Explanation	docs/explanation/

Rule of thumb:

• Tutorials optimize for learning flow.
• How-to guides optimize for successful outcomes.
• Reference docs optimize for completeness and lookup speed.
• Explanation docs optimize for understanding tradeoffs and rationale.

Start Here

Choose the path that matches what you are trying to do:

I want to...	Read this first
Install the language server	Installation Guide
Integrate perl-lsp into GitHub Actions	GitHub Actions Integration
Upgrade an existing installation	Upgrading
Get a working editor setup quickly	Getting Started
Set up continuous testing and watch loops	Continuous Testing
Configure editor or workspace settings	Configuration Reference
Share project settings with my team	Project Configuration File (.perl-lsp.toml)
Migrate from perltidy or perlcritic to native tooling	Native Tooling Migration
Troubleshoot startup, indexing, or editor issues	Troubleshooting
Troubleshoot Perl binary, @INC, PERL5LIB, perldoc, or DAP setup	Perl Setup Troubleshooting
Understand editor trust, fallbacks, and receipts	Editor Trust
Understand the server architecture	Architecture Overview
Understand measured editor trust and the Rust Perl replacement path	Measured Perl Editor Trust
Understand the compiler-backed LSP direction	Compiler-Backed LSP Roadmap
Work on LSP features as a contributor	LSP Development Guide
Run builds, tests, and CI commands	Commands Reference
Add or audit public API documentation	Missing Documentation Guide
Understand stability and compatibility	Stability Policy
Understand the native stack product policy	Native Stack Product Policy
Read the historical analyses and launch material	Articles and Research Notes
Decide where a doc belongs in Diataxis	Diataxis Authoring Guide
Contribute code to perl-lsp	Contributing Guide
Develop the VS Code extension locally	VS Code Extension Dev Guide
Navigate the 89 helper scripts	Scripts Directory Index

Documentation Map

Tutorials

Hands-on guides for learning the system by doing (learning-oriented).

• Getting Started
• LSP Development Guide
• DAP User Guide
• Comprehensive Testing Guide
• AI Build Guide

How-to Guides

Task-focused instructions for common workflows (goal-oriented).

• Installation Guide
• GitHub Actions Integration
• Upgrading
• Editor Setup
• Native Tooling Migration
• Troubleshooting
• Perl Setup Troubleshooting
• Editor Trust
• Continuous Testing
• Contributing LSP Features
• Threading Configuration Guide
• Performance Tuning
• Security Development Guide

Reference

Authoritative descriptions of commands, options, data, and feature contracts (information-oriented).

• Commands Reference
• Configuration Reference
• Architecture Overview
• LSP Features
• Missing Documentation Guide
• API Documentation Standards
• Diataxis Authoring Guide
• FAQ
• Parser Feature Matrix
• Known Limitations

Explanation

Background material that explains why the system is designed the way it is (understanding-oriented).

• LSP Documentation
• Measured Perl Editor Trust
• Cancellation Architecture Guide
• Pure Rust Parser
• Slash Disambiguation

Project / ADR / Specs

Decision records, project status, and planning documents.

• ADR Index — chronological index plus a topic guide for parser, runtime, DAP, security, and swarm decisions
• 0.14.0 Readiness Queue — current-release meta-roadmap: drain queue + implementation phase + release lock
• Project Roadmap
• Compiler-Backed LSP Roadmap
• Preview Before Edit ADR
• PR Queue Disposition Spec
• Receiver-Fact Completion Spec
• Edit-Producing Provider Safety Spec
• Workspace Trust Report Spec
• Support Claim Map Spec
• Trust-Lane CI Routing Spec
• User-Facing Trust Surfaces Spec
• Agent Build Storage and Gates Spec
• Refactor Acceptance Spec
• Native Stack Product Surface Spec
• Receiver Expression Facts Spec, Receiver Facts Implementation Plan, and Receiver Facts Status
• Project Milestones
• Feature Governance
• Metric Stack — contributor-facing summary of the layered scorecard model and the ratchet
• Latency Caps SLO Spec
• Native Formatter and Critic Replacement Contract
• Release Candidate Baseline

Historical Analyses

Long-form historical writing plus the supporting research notes that fed it.

• Articles and Research Notes
• Five Eras of AI-Assisted Development
• Agentic Swarm Development
• Parsing Perl
• Zero-Panic Reliability and Security
• Curiosities, Records, and Surprising Facts

Contributing & Development

Resources for contributors working on the codebase itself.

• Contributing Guide — first-time setup checklist, workflow, coding standards, PR process
• CLAUDE.md — architecture overview, crate map, agent pipeline, key commands
• VS Code Extension Dev Guide — build, test, and point at a local binary
• Scripts Directory Index — categorized guide to the 89 helper scripts
• LSP Development Guide — how to implement and test LSP features
• ADR Index — design decisions and rationale

Suggested Reading Order for New Contributors

1. Getting Started
2. Installation Guide
3. Commands Reference
4. Architecture Overview
5. LSP Development Guide

CLI Quick Reference

These commands are especially useful when validating an installation or triaging an environment issue:

perllsp --version
perllsp --health
perllsp --info
perllsp --check path/to/file.pl
perllsp --completion bash

For the complete option list and behavior, see the Commands Reference.