# Architecture Documentation\n\nWelcome to the architecture documentation for the nushell-plugins project. This directory contains Architecture Decision Records (ADRs), design documents, and technical guides.\n\n---\n\n## Architecture Decision Records (ADRs)\n\n### [ADR-001: Plugin Exclusion System](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\n\n**Status**: ✅ Accepted & Implemented\n**Date**: 2025-12-03\n\nA configuration-driven system for excluding reference/documentation plugins from distributions while keeping them available for development and testing.\n\n**Key Points**:\n\n- Single source of truth in `etc/plugin_registry.toml`\n- Non-breaking - doesn't affect builds, tests, or development\n- Centralized filtering at collection and packaging stages\n- Foundation for future profile-based and conditional exclusions\n\n**When to Read**: If you want to understand WHY the exclusion system was implemented and how design decisions were made.\n\n---\n\n## Technical Specifications\n\n### [Plugin Exclusion System - Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)\n\n**Status**: ✅ Complete\n**Version**: 1.0.0\n\nDeep-dive into the technical implementation of plugin exclusions, including:\n\n- How the system works under the hood\n- Code implementation details\n- Error handling and resilience\n- Integration points with build/collect/package workflows\n- Performance impact analysis\n- Future enhancement possibilities\n\n**Sections**:\n\n- Overview and design principles\n- Configuration details\n- Implementation in collection system\n- Implementation in packaging system\n- Implementation in installation configuration\n- Behavior matrix (what happens in each scenario)\n- Use cases and examples\n- Error handling strategies\n- Maintenance procedures\n- Testing and verification\n\n**When to Read**: If you need to understand HOW the system works, maintain it, or extend it.\n\n---\n\n## Guides & Documentation\n\n### [Plugin Exclusion Guide - Quick Reference & Troubleshooting](../PLUGIN_EXCLUSION_GUIDE.md)\n\n**Status**: ✅ Complete\n**Version**: 1.0.0\n\nUser-friendly guide covering:\n\n- Quick reference for different user types\n- Common tasks (add/remove exclusions, verify builds, etc.)\n- Technical details for developers\n- Troubleshooting section\n- FAQs\n- Best practices\n- CI/CD integration examples\n\n**Sections**:\n\n- Quick start for users, developers, and release managers\n- Common tasks with step-by-step instructions\n- Technical workflow diagrams\n- Troubleshooting guide\n- FAQs\n- Best practices (DO/DON'T)\n- CI/CD integration examples\n\n**When to Read**: If you're learning the system, performing a task related to exclusions, or troubleshooting issues.\n\n---\n\n## Navigation Guide\n\n### By User Role\n\n**👤 End Users**:\nStart with: [Plugin Exclusion Guide - Quick Start (Users)](../PLUGIN_EXCLUSION_GUIDE.md#for-users)\n\n- Explains why some plugins aren't in distributions\n- Shows how to access excluded plugins if needed\n\n**👨💻 Plugin Developers**:\nStart with: [Plugin Exclusion Guide - Quick Start (Developers)](../PLUGIN_EXCLUSION_GUIDE.md#for-developers)\nThen read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)\n\n- How to exclude your plugin during development\n- How the filtering system works\n- Implementation details\n\n**📦 Release Managers**:\nStart with: [Plugin Exclusion Guide - Release Checklist](../PLUGIN_EXCLUSION_GUIDE.md#for-release-managers)\nThen read: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\n\n- Pre-release verification steps\n- How to test exclusions\n- Decision rationale for documentation\n\n**🔧 Maintainers/Architects**:\nStart with: [ADR-001](./ADR-001-PLUGIN_EXCLUSION_SYSTEM.md)\nThen read: [Technical Architecture](./PLUGIN_EXCLUSION_SYSTEM.md)\n\n- Design decisions and trade-offs\n- Implementation details\n- Extension points for future enhancements\n\n### By Task\n\n**"I want to exclude a plugin"**:\n→ [Plugin Exclusion Guide - Task 1](../PLUGIN_EXCLUSION_GUIDE.md#task-1-add-a-plugin-to-exclusion-list)\n\n**"I want to remove a plugin from exclusion"**:\n→ [P
