Create comprehensive MARR documentation (#29)

.claude/marr/MARR-PROJECT-CLAUDE.md

@@ -62,13 +62,6 @@ Read this standard when:
 - WHEN investigating test failures or flaky tests
 - WHEN making code changes that should have test coverage
 
-### `prj-ui-ux-standard.md`
-Read this standard when:
-- WHEN creating or modifying UI components or layouts
-- WHEN making visual design or styling decisions
-- WHEN implementing user interactions, forms, or navigation
-- WHEN evaluating accessibility or usability
-
 ### `prj-workflow-standard.md`
 Read this standard when:
 - WHEN starting any feature, task, or implementation work

.claude/marr/README.md

@@ -1,41 +1,31 @@
-# MARR Configuration Directory
+# MARR Project Configuration
 
-**MARR (Making Agents Really Reliable)** is an AI agent configuration system that provides consistent project context and standards across all your projects.
+This directory contains MARR (Making Agents Really Reliable) configuration for this project.
 
-For full documentation, see the [MARR repository](https://github.com/virtualian/marr#readme).
-
-## How MARR Works
-
-MARR uses a two-layer configuration system:
-
-1. **User-level** (`~/.claude/marr/MARR-USER-CLAUDE.md`) - Personal preferences, communication style, approval requirements. Applied across all projects.
-
-2. **Project-level** (this directory) - Project-specific standards and context. Overrides user config for technical standards while preserving user preferences.
-
-## This Directory
+## Structure
 
 ```
 .claude/marr/
-├── MARR-PROJECT-CLAUDE.md   # Project configuration (imported by CLAUDE.md)
+├── MARR-PROJECT-CLAUDE.md   # Project-specific AI agent configuration
 ├── README.md                # This file
-└── standards/               # Project-level standards
-    ├── prj-documentation-standard.md
-    ├── prj-mcp-usage-standard.md
-    ├── prj-testing-standard.md
-    ├── prj-ui-ux-standard.md
+└── standards/               # Project-level standards (optional)
     ├── prj-workflow-standard.md
-    └── prj-writing-prompts-standard.md
+    ├── prj-testing-standard.md
+    └── ...
 ```
 
-## How It Loads
+## How It Works
 
 1. Project root `CLAUDE.md` imports `@.claude/marr/MARR-PROJECT-CLAUDE.md`
-2. MARR-PROJECT-CLAUDE.md lists standards with "Read before..." triggers
-3. When a trigger is met, Claude Code reads the relevant standard
-4. Standards define required behavior for that type of work
+2. MARR-PROJECT-CLAUDE.md defines trigger conditions for standards
+3. When a trigger is met, the AI agent reads that standard before proceeding
 
 ## Customization
 
 Edit files in this directory to match your project's needs. Changes are version-controlled with your project.
 
-Run `marr validate` to check configuration is correct.
+## Commands
+
+- `marr validate` - Check configuration is correct
+- `marr standard list` - List installed standards
+- `marr standard sync` - Regenerate trigger list from frontmatter

.claude/marr/standards/prj-documentation-standard.md

@@ -13,181 +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**: Clear documentation organization ensures projects are discoverable and understandable.
-
----
-
-## Triggers
-
-**You MUST follow this standard when:**
-- Creating or modifying documentation files
-- Restructuring project documentation
-- Adding READMEs or guides
-- Updating existing documentation
+> **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
-
-**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
+**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."
 
 ---
 
-## Content Types (Diátaxis Framework)
-
-Documentation content falls into three types for technical projects. Each type serves a different user need—keep them distinct.
-
-See [Diátaxis](https://diataxis.fr/) for the full framework.
-
-### How-To Guides (Task-Oriented)
-
-**Purpose:** Help users accomplish specific tasks they've already decided to do.
-
-- Solve a particular problem the user has chosen to tackle
-- Assume competence—no teaching required
-- Focus on practical steps to achieve the goal
-- Title with the task: "How to configure X", "How to deploy Y"
-
-### Reference (Information-Oriented)
-
-**Purpose:** Provide technical descriptions of how the system works.
-
-- Describe the machinery and how to operate it
-- Structure around the code or product architecture
-- Be accurate, comprehensive, and austere
-- Optimized for lookup, not reading cover-to-cover
-
-### Explanation (Understanding-Oriented)
+## Content Type Requirements
 
-**Purpose:** Clarify concepts, design decisions, and context.
+### 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"
 
-- Discuss the "why" behind implementations
-- Explore alternatives and trade-offs
-- Connect ideas across the system
-- No step-by-step instructions—this is about understanding
+### Reference
+- MUST describe the system accurately and completely
+- MUST be structured around code or product architecture
+- MUST be optimized for lookup, not sequential reading
 
-### Role-First Navigation (Optional)
-
-When documentation serves multiple user roles with different needs, organize by role first:
-
-```
-docs/
-  administrator/
-    how-to/
-    reference/
-    explanation/
-  user/
-    how-to/
-    reference/
-```
-
-Users think "I'm an administrator" before "I need a how-to guide." Role-first navigation reduces cognitive load.
-
-### Avoiding Content Collapse
-
-Documentation naturally wants to blur boundaries between types. Resist this.
-
-**Warning signs:**
-- How-to guides that digress into theory unrelated to the task
-- Reference material that teaches rather than describes
-- Explanation content with step-by-step instructions
-
-**Fix:** Ask two questions:
-1. Is this **action** (practical) or **cognition** (theoretical)?
-2. Is this **acquisition** (learning) or **application** (problem-solving)?
-
-The answers reveal where content belongs.
+### Explanation
+- MUST discuss the "why" behind implementations
+- MUST NOT include step-by-step instructions
+- MUST connect concepts across the system
 
 ---
 
-## Documentation Quality Standards
+## Quality Requirements
 
-### Clarity
-- Use simple, direct language
-- Avoid jargon unless necessary
-- Define terms when first used
-- Use examples to clarify concepts
-
-### 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
-
-### 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
+
+**Platform conventions take precedence.** GitHub repository and community files belong at project root per GitHub's conventions.
 
-### Technical Documentation
-- Clear, direct, technical
-- Assume reader is technical
-- Use examples to clarify
-- Explain WHY, not just WHAT
+**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.
 
-### READMEs
-- Start with what the project/directory does
-- Include quick start or usage instructions
-- Link to more detailed documentation
-- Keep concise and scannable
+**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

.claude/marr/standards/prj-mcp-usage-standard.md

@@ -14,20 +14,6 @@ triggers:
 # MCP Usage Standard
 
 > **AI Agent Instructions**: This document defines how to use Model Context Protocol (MCP) tools. Follow these rules when using MCP tools or integrating external services.
->
-> **Scope**: All MCP tool usage
->
-> **Rationale**: MCP tools are powerful but require clear usage patterns to avoid confusion and errors.
-
----
-
-## Triggers
-
-**You MUST follow this standard when:**
-- Using any MCP tool
-- Integrating external services via MCP
-- Selecting which MCP tool to use for a task
-- Troubleshooting MCP tool behavior
 
 ---
 

.claude/marr/standards/prj-testing-standard.md

@@ -14,20 +14,6 @@ triggers:
 # Testing Standard
 
 > **AI Agent Instructions**: This document defines testing philosophy and practices. Follow these rules when running, writing, or modifying tests.
->
-> **Scope**: All testing activities
->
-> **Rationale**: Testing ensures code works correctly and prevents regressions.
-
----
-
-## Triggers
-
-**You MUST follow this standard when:**
-- Running tests
-- Writing new tests
-- Modifying existing tests
-- Making code changes that require test coverage
 
 ---
 

.claude/marr/standards/prj-ui-ux-standard.md

@@ -14,20 +14,6 @@ triggers:
 # UI/UX Development Standard
 
 > **AI Agent Instructions**: This document defines UI/UX development standards. Follow these rules for all component generation, design decisions, and user interface work.
->
-> **Scope**: All UI/UX development activities
->
-> **Rationale**: Consistent UI/UX standards ensure accessible, usable, and professional interfaces.
-
----
-
-## Triggers
-
-**You MUST follow this standard when:**
-- Generating UI components
-- Making design decisions
-- Implementing user interfaces
-- Reviewing UI/UX work
 
 ---
 

.claude/marr/standards/prj-workflow-standard.md

@@ -14,20 +14,6 @@ triggers:
 # Workflow Standard
 
 > **AI Agent Instructions**: This document defines the development workflow. Follow these rules for all implementation work.
->
-> **Scope**: All development work involving git, branches, commits, and pull requests
->
-> **Rationale**: Consistent workflow ensures traceability, prevents errors, and enables collaboration.
-
----
-
-## Triggers
-
-**You MUST follow this standard when:**
-- Starting any feature, task, or implementation work
-- Performing git operations (branching, committing, pushing)
-- Creating or updating pull requests
-- Working on the main branch
 
 ---