Getting Started¶

Installation¶

uv add menard

Quick Start¶

# Initialize
menard init

# Audit docs for trackability (in Claude Code)
> Audit my documentation and apply the suggestions

# Auto-generate convention-based links
menard bootstrap --apply

# Validate and check coverage
menard validate-links
menard coverage

Pre-Commit Setup¶

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: menard-check
        name: menard-check
        entry: uv run menard check
        language: system
        pass_filenames: false
        always_run: true

Then install:

pre-commit install

Now commits will block if docs are stale:

git commit -m "refactor auth"
# ❌ Blocked: docs/api.md#Authentication unchanged since src/auth.py changed

Real-World Example¶

This walkthrough shows the complete menard onboarding workflow from an actual session onboarding portolan-cli.

Step 1: Initialize¶

$ menard init
✓ Created .menard/links.toml
✓ Added [tool.menard] to pyproject.toml

Fix the source directory if needed:

# pyproject.toml
[tool.menard]
require_links = ["portolan_cli/**/*.py"]  # Not src/

Step 2: Check Coverage¶

$ menard coverage
Documentation Coverage: 0.0%
  Total code files: 60
  Documented: 0

Step 3: Create Initial Links¶

Identify key code→doc relationships:

# .menard/links.toml

[[link]]
code = "portolan_cli/cli.py"
docs = ["docs/reference/cli.md"]

[[link]]
code = "portolan_cli/config.py"
docs = ["docs/reference/configuration.md"]

[[link]]
code = "portolan_cli/conversion_config.py"
docs = ["docs/reference/configuration.md#Conversion Configuration"]

Step 4: Run Audit Skill¶

In Claude Code:

> Audit my documentation and apply the suggestions

The audit identifies:

Suggested links from file path mentions
Protected sections for .menard/donttouch
Restructuring recommendations

Step 5: Add Protections¶

Protect content that shouldn't be flagged as stale when related code changes:

$ cat .menard/donttouch
# License sections
README.md#License
docs/contributing.md#License

# Brand colors
docs/BRANDING.md#Color Palette

# Version requirements (this project's minimum Python version)
"Python 3.10+"

Note: The protected literal above is portolan-cli's Python requirement. Your project may have different literals to protect (version badges, license text, brand colors, etc.).

Step 6: Bootstrap Additional Links¶

$ menard bootstrap --apply
Found 8 suggested links
Applied all suggestions to .menard/links.toml

Step 7: Final Coverage¶

$ menard coverage
Documentation Coverage: 26.7%
  Total code files: 60
  Documented: 16

Step 8: Test the Workflow¶

Make a change to code:

$ git add portolan_cli/cli.py
$ git commit -m "feat: add --verbose flag"

menard: ❌ commit blocked

Stale documentation detected:
  docs/reference/cli.md
    Code: portolan_cli/cli.py
    Reason: File unchanged since portolan_cli/cli.py changed

Update docs, then commit succeeds:

$ git add docs/reference/cli.md
$ git commit -m "feat: add --verbose flag"
✓ menard check passed