Existing Features

• auto-continue.md - Documentation for the auto-continue feature that streamlines package installation workflows
• exit-codes.md - Reference for npq and npq-hero process exit behavior
• json-output.md - Versioned, machine-readable audit-only output for CI and automation
• malicious-package.md - Documentation for known-malicious package detection through Snyk/OSV data
• pacote-dependency-reduction.md - Implementation summary for optional pacote dependency reduction

Documentation Standards

Structure

• Each feature gets its own markdown file in feature/
• Core functionality documented at the root docs level
• Technical implementation details included with code examples
• User-facing configuration documented with usage examples

Content Guidelines

• Overview: Brief description of the feature/component
• Technical Design: Architecture and implementation details
• Usage Examples: Practical examples with code snippets
• Testing: Coverage and validation information
• Future Considerations: Maintenance and evolution notes

Marshall Documentation

Marshall components are the core security validation modules in NPQ. Each marshall focuses on a specific security concern:

• Age Marshall (age.marshall.md) - Package age and maturity validation
• Signature Marshall - NPM registry signature verification (see signature-verification-fix.md)
• Provenance Marshall - Package build attestation verification
• Snyk Marshall - Vulnerability database integration
• Typosquatting Marshall - Package name similarity detection

Contributing to Documentation

When adding new features or making significant changes:

1. Feature Documentation: Create a new file in feature/ directory
2. Update Index: Add entry to this README
3. Cross-Reference: Update related documentation files
4. Examples: Include practical usage examples
5. Testing: Document test coverage and validation

Quick Reference

Project context

• Development - local setup, workflows, and useful commands.
• Testing - test commands, test organization, and verification expectations.
• Architecture - repository structure, package boundaries, and important flows.
• Conventions - coding, documentation, and maintenance conventions.

Design specifications

• Non-interactive install safety - approved design for fail-closed non-TTY installs with explicit automation and coding-agent opt-ins.

• Non-interactive install safety - test-first plan for fail-closed non-TTY install routing and coding-agent passthrough.

• Shell-free package manager launching - approved design for forwarding package-manager arguments without shell command reconstruction.

• Custom registry support - approved design for npm-compatible Artifactory and private registry support.

• Coding-agent JSON detection - approved design for automatically selecting JSON audit mode in coding-agent environments.

• JSON audit output - approved design for versioned, non-interactive machine-readable audit results.

• Expired-domain maintainer identity warnings - approved design for attributable expired-domain warnings.

• Expired-domain resolved version - design for resolving the exact dependency version for expired-domain checks.

Implementation plans

• Non-interactive install safety - test-first plan for fail-closed non-TTY install routing and coding-agent passthrough.
• Shell-free package manager launching - test-first plan for launching package managers without shell command reconstruction.
• Custom registry support - task-by-task implementation plan for issue #429.
• Coding-agent JSON detection - test-first implementation plan for issue #426 across npq and npq-hero.
• JSON audit output - task-by-task plan for versioned, audit-only JSON CLI output.
• Expired-domain resolved version - implementation plan for exact dependency-version resolution in expired-domain checks.
• Expired-domain maintainer identity warnings - test-first implementation plan for attributable expired-domain warnings.