mucm 0.2.0

Why MUCM?

Documentation that travels with your code. MUCM is a documentation compiler that turns structured data (TOML or SQLite) into beautifully formatted markdown documentation. Write once, generate multiple perspectives for developers, testers, business analysts, and product managers.

The Problem

• Online tools create barriers - contributors need accounts, logins, permissions just to read/edit docs
• Documentation lives separately from code - not in your repo, not in pull requests, not in your workflow
• Keeping it structured manually is painful - consistent formatting across dozens of use cases is tedious
• Vendor lock-in - your documentation is trapped in proprietary systems

The Solution

Edit TOML files (just like config files), commit to git, and get:

• Customizable templates without coding - Handlebars templates you can edit to format output exactly how you want
• Version-controlled source of truth in your repo, no servers, no online services, zero barriers
• Auto-generated test scaffolding with safe zones so your code survives regeneration
• Smart cross-references that automatically link use cases, actors, and preconditions
• CI/CD ready - generate docs automatically in GitHub Actions, no installation needed for contributors.
• Multi-view documentation tailored for different teams (same data, different perspectives)

See It In Action

→ E-Commerce Demo - Complete authentication system with use cases, personas, tests, and Mermaid diagrams. Built in 10 minutes. Zero manual markdown.

Features

🔧 Extend Everything
Create custom methodologies for your industry. Add support for new test languages. Build your own template fields. MUCM adapts to your workflow, not the other way around.

🎨 Customize Templates Without Coding
Edit Handlebars templates to format your documentation exactly how you want. Change headings, reorder sections, add custom fields - no programming experience required. Copy the templates to your project, tweak them in any text editor, and regenerate. Your documentation, your style.

🔗 Smart Cross-References That Never Break
Type ||UC:UC-AUTH-001:depend in any precondition - MUCM automatically generates clickable markdown links to the right use case. Rename a file? Move a category? All references update automatically. No more hunting for broken links.

🧪 Test Scaffolding That Survives Regeneration
Generate test files in Python, Rust, Java or JavaScript (and soon many more) with protected "safe zones" for your code. Write your test logic once between the markers - regenerate docs 100 times and your implementation stays intact. Only the scaffolding updates.

📊 Interactive Diagrams Built From Your Scenarios
Describe your workflow in scenario steps - MUCM generates Mermaid sequence diagrams automatically. Actors, interactions, all visualized. Change a step, regenerate, diagram updates. No drawing tools needed.

👥 Rich Actor Profiles
Create realistic personas (background, motivations, technical skills) and system actors (APIs, databases, external services). Every actor gets an emoji, a full profile page, and appears consistently across all scenarios.

🎯 Four Methodology Views (Or Mix Them)
Generate documentation tailored for different audiences from the same source:

• Developer - API specs, data models, security requirements, technical architecture
• Tester - Test scenarios, coverage areas, automation status, quality gates
• Business - ROI analysis, stakeholder requirements, business value, success metrics
• Feature - User stories, acceptance criteria, agile workflows, sprint planning

⚡ Two Ways to Work

• Interactive Mode (mucm -i) - Guided menus, perfect for getting started or complex edits
• CLI Mode - Lightning-fast commands for automation, scripting, and CI/CD pipelines

💾 Choose Your Storage

• TOML (Recommended) - Human-readable files, beautiful diffs, perfect for code review and version control
• SQLite (Experimental) - Database backend for projects with 100+ use cases, complex queries, and better performance

Quick Start

Installation

Using Cargo (Recommended)

cargo install mucm

From Source

git clone https://github.com/Guillaumecoi/markdown-use-case-manager
cd markdown-use-case-manager
cargo install --path .

Create Your First Project

Option 1: Interactive Mode (Recommended)

mucm      # or mucm -i or mucm --interactive

Than follow the prompts to set up your project, choose a methodology, and create your first use case, etc...

→ Interactive Mode Guide

Option 2: CLI Mode

Or use direct commands (Better for automation)

# Initialize project
mucm init --methodology developer

# Create a use case
mucm create "User Authentication" --category security

...

→ Standard CLI guide

What You Get

Configuration & Templates:

After initialization, MUCM creates configuration files and copies template assets into your project: All these files live in .config/.mucm/ and can be customized as needed.

.config/.mucm/
├── mucm.toml                   # Project configuration
└── template-assets/            # Customizable templates (copied from source-templates)
    ├── methodologies/          # Settings and templates per methodology
    │   ├── developer/
    │   ├── feature/
    │   └── ...
    └── languages/              # Settings and templates per programming language
        ├── rust/
        ├── python/
        └── ...

Input (Your Data):

Your single source of truth for use cases is stored in structured toml files (or SQLite). That way, your data is always version controlled and easy to edit.

use-cases-data/
├── actors/
│   ├── admin-user.toml         # Persona definitions
│   └── auth-service.toml       # System actor definitions
└── security/
    └── UC-SEC-001.toml         # Use case source data

Or if you use SQLite backend:

└── mucm.db                     # SQLite database file with all data

Output (Generated Documentation):

MUCM generates clean, organized markdown files for your use cases.

docs/
├── use-cases/
│   ├── README.md                             # Auto-generated overview
│   └── security/
│       ├── README.md                         # Category overview (auto-generated)
│       └── UC-SEC-001/                       # Each use case has its own folder
│           ├── README.md                     # Main documentation (single view)
│           ├── UC-SEC-001-feature-normal.md  # Or multiple methodology views
│           └── UC-SEC-001-developer-normal.md
├── personas/
│   ├── admin-user.md                         # Persona documentation
│   └── auth-service.md                       # System actor documentation

tests/use-cases/
└── security/
    └── uc_sec_001.rs                         # Test scaffolding (optional)

Documentation

Start Here:

• E-Commerce Demo - See MUCM in action with a real project
• Getting Started - Installation and your first use case
• CLI Reference - All commands and options

Guides:

• Interactive Mode - Menu-driven interface walkthrough
• Choosing a Methodology - Pick the right view
• Template Customization - Make MUCM yours

Deep Dive:

• Architecture - Technical design and implementation
• Full Documentation Index - Everything else

Community & Support

Questions? Join the discussions
Found a bug? Open an issue
Want to contribute? See our Contributing Guide

We especially encourage:

• New methodology templates for different industries
• Additional programming language support for test generation
• Documentation improvements and examples
• Feature requests and bug reports
• Feature development, code contributions and bug fixes

License

MIT License - see LICENSE for details.