madomeda/GETTING_STARTED.md

---
title: Getting Started with Madomeda
created: '2025-10-23T18:33:48+02:00'
status: draft
priority: 5
published: false
tags: []
reviewers: []
---
# Getting Started with Madomeda

## Prerequisites

- Python 3.7+
- Git repository with markdown files
- (Optional) OpenAI-compatible API for LLM features

## Installation

1. **Clone or download** the Madomeda repository

2. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **(Optional) Configure LLM:**
   Edit `.env` file:
   ```
   OPENAI_API_URL=https://api.openai.com/v1
   OPENAI_MODEL=gpt-4
   OPENAI_API_KEY=your-actual-api-key
   ```

## Your First Run

1. **Navigate to your markdown repository:**
   ```bash
   cd /path/to/your/markdown/repo
   ```

2. **Run in dry-run mode** to see what would change:
   ```bash
   python /path/to/madomeda/madomeda.py --whatif
   ```

3. **Review the output** - it will show:
   - Files discovered
   - Existing frontmatter (if any)
   - Proposed changes
   - Warnings about discarded metadata

4. **Run for real** if you're happy with the changes:
   ```bash
   python /path/to/madomeda/madomeda.py
   ```

5. **Check the results:**
   - Open modified markdown files
   - Review `madomeda_changelog.txt`
   - Inspect database: `python /path/to/madomeda/inspect_db.py madomeda.db`

## Understanding the Output

### Already Conformant
```
Processing: example.md
  Found existing frontmatter
  OK Already conformant
```
**Meaning:** File has correct frontmatter, no changes needed.

### Will Update
```
Processing: example.md
  Found existing frontmatter
  WARNING Metadata will be discarded: CustomField
  Would update frontmatter:
    Changes: +created, +authors, -CustomField
```
**Meaning:** File will be updated. Custom fields not in template will be removed.

### No Frontmatter
```
Processing: example.md
  No frontmatter found
  Would update frontmatter:
    Changes: +title, +created, +changed, +authors, +version, +tags
```
**Meaning:** New frontmatter will be added.

## Common Workflows

### Preview Changes
```bash
python madomeda.py --whatif
```

### Process Specific Directory
```bash
python madomeda.py --dir ~/Documents/wiki
```

### Skip Confirmations
```bash
python madomeda.py --no-confirm
```

### Ignore Certain Paths
```bash
python madomeda.py --ignore-paths archive drafts templates
```

### Force Regeneration
```bash
python madomeda.py --force
```

### Use Custom Template
```bash
python madomeda.py --template minimal
```
(First create `templates/minimal.json`)

## Customization

### Create Custom Template

1. Create `templates/mytemplate.json`:
   ```json
   {
     "title": "heur|orig",
     "date": "heur|orig",
     "tags": "orig|ai default",
     "author": "heur|orig"
   }
   ```

2. Use it:
   ```bash
   python madomeda.py --template mytemplate
   ```

### Add Custom Rule

See [RULES_GUIDE.md](RULES_GUIDE.md) for comprehensive rule writing documentation.

1. Create `~/.config/madomeda/rules/60_my_rule.json`:
   ```json
   {
     "name": "my_custom_rule",
     "description": "Description of what this rule does",
     "field": "my_field",
     "priority": 60,
     "action": "normalize_value",
     "pattern": "[^a-z]",
     "replacement": "",
     "llm_prompt": "Instructions for LLM"
   }
   ```

2. Rules are automatically loaded - no code changes needed!

### Customize LLM Prompt

1. Create `prompts/custom.txt`:
   ```
   You are a documentation expert. Analyze the content and suggest metadata...
   ```

2. Reference in template:
   ```json
   {
     "summary": "ai custom"
   }
   ```

## Troubleshooting

### "Not a git repository"
**Solution:** Ensure you're in a directory with `.git/` folder or use `--dir` to specify one.

### "Module not found"
**Solution:** Run `pip install -r requirements.txt`

### "LLM error: 401"
**Solution:** 
- Update `.env` with valid API key
- Or ensure template doesn't require `ai` strategy
- The tool works fine without LLM using `heur` and `orig` strategies

### "Metadata will be discarded"
**Solution:** 
- Review the warning
- Add fields to template if you want to keep them
- Use `--no-confirm` to auto-accept
- Press 'n' to skip that file

### Database locked
**Solution:** Close any programs accessing `madomeda.db`

## Best Practices

1. **Always test first:** Use `--whatif` before making changes
2. **Commit before processing:** Ensure you can revert if needed
3. **Review warnings:** Check what metadata will be lost
4. **Customize templates:** Match your needs, not defaults
5. **Version control:** Commit the database to track history
6. **Regular runs:** Process new files as they're added

## Files Generated

- `madomeda.db` - SQLite database (gitignored by default)
- `madomeda_changelog.txt` - Change log
- `templates/` - Created if missing
- `rules/` - Created if missing
- `prompts/` - Created if missing

## Getting Help

1. Check documentation:
   - `README.md` - Overview
   - `USAGE.md` - Detailed examples
   - `RULES_GUIDE.md` - Writing custom rules
   - `LITERAL_VALUES.md` - Template literal values
   - `CONFIGURATION.md` - Configuration options
   - `STRUCTURE.md` - Architecture
   - `IMPLEMENTATION.md` - Technical details

2. Inspect database:
   ```bash
   python inspect_db.py
   ```

3. Review changelog:
   ```bash
   cat madomeda_changelog.txt
   ```

## Example Session

```bash
# Navigate to your repo
cd ~/my-knowledge-base

# First run (dry run)
python ~/tools/madomeda/madomeda.py --whatif

# Output shows what will change
# Review and decide

# Run for real
python ~/tools/madomeda/madomeda.py

# Check results
cat madomeda_changelog.txt
git diff

# Commit changes
git add .
git commit -m "Normalize frontmatter with Madomeda"
```

## Tips

- Start with `--whatif` always
- Use `--no-confirm` for batch processing
- Keep `madomeda.db` to track history
- Review `madomeda_changelog.txt` after runs
- Create templates for different doc types
- Tags are automatically collected and normalized

## Success!

If you see:
```
Processing complete!
Total unique tags in repository: X
```

You're done! Your frontmatter has been normalized and tracked.