virtualian · virtualian · Dec 8, 2025 · Dec 8, 2025
diff --git a/.claude/marr/MARR-PROJECT-CLAUDE.md b/.claude/marr/MARR-PROJECT-CLAUDE.md
@@ -10,7 +10,7 @@
 
 MARR (Making Agents Really Reliable) provides project-level AI agent configuration.
 
-See `.claude/marr/README.md` for how MARR works.
+See `.claude/marr/README.md` for how MARR works, or visit [virtualian.github.io/marr](https://virtualian.github.io/marr).
 
 ## What is a Standard
 

diff --git a/.claude/marr/standards/prj-documentation-standard.md b/.claude/marr/standards/prj-documentation-standard.md
@@ -13,100 +13,78 @@ triggers:
 
 # Documentation Standard
 
-> **AI Agent Instructions**: This document defines documentation organization and maintenance. Follow these rules for all documentation work.
+> **AI Agent Instructions**: Follow these rules for all documentation work.
+>
+> **Scope**: All documentation activities
+>
+> **Rationale**: Consistent documentation organization ensures projects remain discoverable and maintainable.
 
 ---
 
 ## Core Rules (NEVER VIOLATE)
 
-1. **Documentation lives in designated directories** because scattered docs are invisible
-2. **Update docs when code changes** because outdated docs mislead users
-3. **Use clear, direct language** because technical documentation is not marketing
-4. **Provide examples** because concrete is clearer than abstract
-5. **No AI attribution comments** because code and docs stand on merit, not origin
+1. **All documentation lives in `docs/`** because scattered docs are invisible
+2. **Organize by role first, then content type** because users identify by role before need
+3. **Keep content types distinct** because mixed purposes confuse readers
+4. **Update docs when code changes** because outdated docs mislead users
+5. **No AI attribution** because content stands on merit, not origin
 
 ---
 
-## Documentation Organization
+## Structure
 
-### Recommended Structure
+All project documentation MUST be organized by user role, then by content type within each role.
 
-- **docs/** — Project documentation organized by audience or purpose
-- **examples/** — Real-world reference implementations
-- **plans/** — Implementation plans (if applicable)
+**Content types** follow the [Diátaxis framework](https://diataxis.fr/). Consult the framework documentation to understand its principles before organizing documentation:
+- **how-to/** — Task-oriented guides for accomplishing specific goals
+- **reference/** — Technical descriptions of system components
+- **explanation/** — Conceptual content about design decisions and trade-offs
 
-### Directory Purposes
+**Role-first organization** means users navigate to their role before choosing content type. This matches how users think: "I'm an administrator" comes before "I need a how-to guide."
 
-**docs/**
-- Technical specifications and guides
-- Organized by user role or topic
-- Updated when system design changes
-
-**examples/**
-- Working code examples
-- Real configurations from actual use
-- Include README explaining each example
+---
 
-**plans/**
-- Implementation plans for specific work
-- Created per issue/feature
-- Archived or deleted when complete
+## Content Type Requirements
 
----
+### How-To Guides
+- MUST solve a specific task the user has chosen to do
+- MUST assume competence — no teaching, just steps
+- MUST title with the task: "How to configure X", "How to deploy Y"
 
-## Documentation Quality Standards
+### Reference
+- MUST describe the system accurately and completely
+- MUST be structured around code or product architecture
+- MUST be optimized for lookup, not sequential reading
 
-### Clarity
-- Use simple, direct language
-- Avoid jargon unless necessary
-- Define terms when first used
-- Use examples to clarify concepts
+### Explanation
+- MUST discuss the "why" behind implementations
+- MUST NOT include step-by-step instructions
+- MUST connect concepts across the system
 
-### Accuracy
-- Keep docs synchronized with implementation
-- Update examples when code changes
-- Remove obsolete information
-- Verify links and references work
+---
 
-### Completeness
-- Cover all major features
-- Provide examples for complex concepts
-- Include rationale for key decisions
-- Document exceptions and edge cases
+## Quality Requirements
 
-### Discoverability
-- Logical directory structure
-- Clear file naming
-- README files in each major directory
-- Cross-references between related docs
+- Use clear, direct language — technical documentation is not marketing
+- Keep docs synchronized with implementation — remove obsolete content
+- Provide examples for complex concepts — concrete is clearer than abstract
+- Maintain one source of truth per topic — no redundant documentation
 
 ---
 
-## Writing Style
+## Exceptions
 
-### Technical Documentation
-- Clear, direct, technical
-- Assume reader is technical
-- Use examples to clarify
-- Explain WHY, not just WHAT
+**Platform conventions take precedence.** GitHub repository and community files belong at project root per GitHub's conventions.
 
-### READMEs
-- Start with what the project/directory does
-- Include quick start or usage instructions
-- Link to more detailed documentation
-- Keep concise and scannable
+**Documentation systems define their own structure.** When using Docusaurus, MkDocs, Sphinx, or similar systems, follow their conventions — but integrate role-first organization and Diátaxis content types where the system allows.
+
+**Non-compliant documentation requires user input.** When existing documentation does not meet this standard, ask the user whether they want to maintain, refine, restructure, or recreate it.
 
 ---
 
 ## Anti-Patterns (FORBIDDEN)
 
-- **Scattering documentation** — Use designated directories only
-- **Creating redundant docs** — One source of truth per topic
-- **Leaving outdated docs** — Update or remove, never ignore
-- **Using marketing language** — This is technical documentation
-- **Adding AI attribution** — No "Generated with AI" comments
-- **Documenting obvious code** — Don't explain what is self-evident
-
----
-
-**This documentation standard ensures projects remain discoverable, understandable, and maintainable.**
+- **Placing docs outside `docs/`** — All documentation in designated directory
+- **Mixing content types** — How-to guides with theory, reference that teaches, explanations with procedures
+- **Leaving stale docs** — Update or remove, never ignore
+- **Creating redundant docs** — One authoritative source per topic
diff --git a/.claude/marr/standards/prj-workflow-standard.md b/.claude/marr/standards/prj-workflow-standard.md
@@ -19,12 +19,13 @@ triggers:
 
 ## Core Rules (NEVER VIOLATE)
 
-1. **Verify issue exists BEFORE any action** because working without tracking causes chaos
-2. **Delete merged branches** because clean repos prevent confusion
-3. **Always squash merge** because linear history is easier to understand and debug
-4. **Branch from main only** (except hotfixes from production tags) because branching from branches creates complexity
-5. **Maximum 5-day branch lifetime** because short-lived branches reduce merge conflicts
-6. **Use issue-based branch naming** because traceability matters
+1. **NEVER make code changes on the main branch** because main must always be deployable and all work must be traceable to a feature branch
+2. **Verify issue exists BEFORE any action** because working without tracking causes chaos
+3. **Delete merged branches** because clean repos prevent confusion
+4. **Always squash merge** because linear history is easier to understand and debug
+5. **Branch from main only** (except hotfixes from production tags) because branching from branches creates complexity
+6. **Maximum 5-day branch lifetime** because short-lived branches reduce merge conflicts
+7. **Use issue-based branch naming** because traceability matters
 
 ---
 
@@ -47,10 +48,11 @@ triggers:
 1. Start from current main branch
 2. Pull latest changes
 3. Create issue-based branch
-4. Develop incrementally with meaningful commits
-5. Push to remote with upstream tracking
-6. Create draft PR immediately for CI checks
-7. When ready, mark PR ready for review
+4. **Before making ANY code changes**: Verify you are on a feature branch (not main). If on main, STOP and create a branch first.
+5. Develop incrementally with meaningful commits
+6. Push to remote with upstream tracking
+7. Create draft PR immediately for CI checks
+8. When ready, mark PR ready for review
 
 ---
 
@@ -81,6 +83,7 @@ triggers:
 
 ## Anti-Patterns (FORBIDDEN)
 
+- **Making changes on main** — All code changes must be on a feature branch, even "quick fixes"
 - **Working without an issue** — All work must be tracked
 - **Long-lived branches** — Merge or close within 5 days
 - **Merge commits** — Always squash merge

diff --git a/docs/appendix.md → deprecated/docs-v1/appendix.md b/docs/appendix.md → deprecated/docs-v1/appendix.md
diff --git a/docs/audit-installed-packages.md → ...cated/docs-v1/audit-installed-packages.md b/docs/audit-installed-packages.md → ...cated/docs-v1/audit-installed-packages.md
diff --git a/docs/credential-rotation-script.md → ...ted/docs-v1/credential-rotation-script.md b/docs/credential-rotation-script.md → ...ted/docs-v1/credential-rotation-script.md
diff --git a/docs/development-guide.md → deprecated/docs-v1/development-guide.md b/docs/development-guide.md → deprecated/docs-v1/development-guide.md
diff --git a/docs/generate-summary-report.md → ...ecated/docs-v1/generate-summary-report.md b/docs/generate-summary-report.md → ...ecated/docs-v1/generate-summary-report.md
diff --git a/docs/how-it-works.md → deprecated/docs-v1/how-it-works.md b/docs/how-it-works.md → deprecated/docs-v1/how-it-works.md
diff --git a/docs/integration-guidelines.md → deprecated/docs-v1/integration-guidelines.md b/docs/integration-guidelines.md → deprecated/docs-v1/integration-guidelines.md
diff --git a/docs/migration-to-unified-audit.md → ...ted/docs-v1/migration-to-unified-audit.md b/docs/migration-to-unified-audit.md → ...ted/docs-v1/migration-to-unified-audit.md
diff --git a/docs/npm-install-monitor.md → deprecated/docs-v1/npm-install-monitor.md b/docs/npm-install-monitor.md → deprecated/docs-v1/npm-install-monitor.md
diff --git a/docs/npm-scanner.md → deprecated/docs-v1/npm-scanner.md b/docs/npm-scanner.md → deprecated/docs-v1/npm-scanner.md
diff --git a/docs/npm-security-audit.md → deprecated/docs-v1/npm-security-audit.md b/docs/npm-security-audit.md → deprecated/docs-v1/npm-security-audit.md
diff --git a/docs/npmrc-security-config.md → deprecated/docs-v1/npmrc-security-config.md b/docs/npmrc-security-config.md → deprecated/docs-v1/npmrc-security-config.md
diff --git a/docs/output-formats.md → deprecated/docs-v1/output-formats.md b/docs/output-formats.md → deprecated/docs-v1/output-formats.md
diff --git a/docs/overview.md → deprecated/docs-v1/overview.md b/docs/overview.md → deprecated/docs-v1/overview.md
diff --git a/docs/package-validator.md → deprecated/docs-v1/package-validator.md b/docs/package-validator.md → deprecated/docs-v1/package-validator.md
diff --git a/docs/recursive-audit-script.md → deprecated/docs-v1/recursive-audit-script.md b/docs/recursive-audit-script.md → deprecated/docs-v1/recursive-audit-script.md
diff --git a/docs/scheduled-audit-script.md → deprecated/docs-v1/scheduled-audit-script.md b/docs/scheduled-audit-script.md → deprecated/docs-v1/scheduled-audit-script.md
diff --git a/docs/security-indicators.md → deprecated/docs-v1/security-indicators.md b/docs/security-indicators.md → deprecated/docs-v1/security-indicators.md
diff --git a/docs/README.md b/docs/README.md
@@ -1,122 +1,32 @@
 # npm-scanner Documentation
 
-Complete technical documentation for the npm-scanner security toolkit.
+## Users
 
-## 📚 Documentation Structure
+### How-To Guides
 
-### Getting Started
-- [**How It Works**](how-it-works.md) - What npm-scanner detects and how
-- [**Overview**](overview.md) - System architecture and design principles
-- [**Development Guide**](development-guide.md) - Technical reference for contributors
+- [Set Up npm-scanner](users/how-to/getting-started.md)
+- [Scan Projects](users/how-to/scan-projects.md)
+- [Validate Packages](users/how-to/validate-packages.md)
+- [Integrate with CI/CD](users/how-to/integrate-with-ci.md)
 
-### Commands
+### Reference
 
-The main entry point is [`npm-scanner.sh`](npm-scanner.md):
+- [Command Reference](users/reference/command-reference.md)
 
-- **scan** - Scan installed packages or project dependencies
-- **validate** - Check a package before installation
-- **list-iocs** - Display all current indicators of compromise
+### Explanation
 
-### Script Documentation (in `scripts/`)
+- [Threat Model](users/explanation/threat-model.md)
 
-#### Core Security Scripts
-1. [**audit-installed-packages.sh**](audit-installed-packages.md) - Unified scanning tool
-2. [**npm-security-audit.sh**](npm-security-audit.md) - Single project scanner (used internally)
-3. [**npm-audit-lib.sh**](overview.md#shared-library) - Shared library with common functions
-4. [**scheduled-audit-script.sh**](scheduled-audit-script.md) - Automation wrapper with alerting
+## Contributors
 
-#### Pre-Installation Tools
-5. [**package-validator.js**](package-validator.md) - Pre-installation risk assessment
-6. [**npm-install-monitor.js**](npm-install-monitor.md) - Real-time network monitoring
+### How-To Guides
 
-#### Response & Configuration
-7. [**credential-rotation-script.sh**](credential-rotation-script.md) - Incident response guide
-8. [**generate-summary-report.sh**](generate-summary-report.md) - Report aggregation tool
-9. [**npmrc-security-config.sh**](npmrc-security-config.md) - Security configuration template
+- [Contribute](contributors/how-to/contributing.md)
 
-### Reference Documentation
-
-- [**Security Indicators**](security-indicators.md) - Threat vectors and detection methods
-- [**Output Formats**](output-formats.md) - Report formats and exit codes
-- [**Integration Guidelines**](integration-guidelines.md) - CI/CD, hooks, and monitoring
-- [**Appendix**](appendix.md) - Troubleshooting and best practices
-
-## 🚀 Quick Links
-
-### By Use Case
-
-**Initial Setup**
-- Start with [Overview](overview.md)
-- Configure with [npmrc-security-config.sh](npmrc-security-config.md)
-- Set up scanning: [scheduled-audit-script.sh](scheduled-audit-script.md)
-
-**Regular Security Auditing**
-- Scan projects: `./npm-scanner.sh scan --project ~/code`
-- Scan global packages: `./npm-scanner.sh scan --global`
-- Automated: [scheduled-audit-script.sh](scheduled-audit-script.md)
-
-**Before Installing Packages**
-- Validate package: `./npm-scanner.sh validate <package>`
-- Monitor installation: [npm-install-monitor.js](npm-install-monitor.md)
-
-**Incident Response**
-- Follow guide: [credential-rotation-script.sh](credential-rotation-script.md)
-- Review indicators: [Security Indicators](security-indicators.md)
-
-**CI/CD Integration**
-- See examples: [Integration Guidelines](integration-guidelines.md)
-- Understand outputs: [Output Formats](output-formats.md)
-
-### By Script Type
-
-All scripts are in the `scripts/` directory.
-
-**Shell Scripts (.sh)**
-- [audit-installed-packages.sh](audit-installed-packages.md)
-- [npm-security-audit.sh](npm-security-audit.md)
-- [scheduled-audit-script.sh](scheduled-audit-script.md)
-- [credential-rotation-script.sh](credential-rotation-script.md)
-- [generate-summary-report.sh](generate-summary-report.md)
-- [npmrc-security-config.sh](npmrc-security-config.md)
-
-**Node.js Scripts (.js)**
-- [package-validator.js](package-validator.md)
-- [npm-install-monitor.js](npm-install-monitor.md)
-
-## 📖 Documentation Conventions
-
-### Code References
-- **Bash blocks**: Shell script examples
-- **JavaScript blocks**: Node.js script examples
-- **YAML blocks**: CI/CD configurations
-- **JSON blocks**: Configuration and data formats
-
-### Symbols
-- ✓ Success/Recommended
-- ⚠ Warning/Caution
-- ✗ Error/Failed
-- 🚨 Critical Alert
-- 📊 Statistics/Metrics
-- 📝 Documentation/Notes
-
-### File Paths
-- Entry point: `./npm-scanner.sh` (from project root)
-- Scripts: `./scripts/*.sh` and `./scripts/*.js`
-- Absolute: `/path/to/file`
-- Home: `~/.npmrc` (user home directory)
-
-## 🔗 Navigation
-
-Each documentation file includes:
-- **Forward navigation**: Link to next related topic
-- **Backward navigation**: Link to previous topic
-- **Cross-references**: Links to related documentation
-
----
-
-**Version:** 1.0  
-**Last Updated:** October 31, 2025  
-**Maintainer:** Security Automation Team
+### Reference
 
+- [Architecture](contributors/reference/architecture.md)
 
+### Explanation
 
+- [Design Decisions](contributors/explanation/design-decisions.md)