madomeda/ADD_ONLY_EXAMPLES.md

---
title: Add-Only Mode Examples
created: '2025-10-23T18:33:48+02:00'
status: draft
priority: 5
published: false
tags: []
reviewers: []
---
# Add-Only Mode Examples

## Overview

The `--add-only` flag preserves existing frontmatter keys while adding missing template fields.

## Example 1: Preserving Custom Fields

### Input File
```yaml
---
Summary: A comprehensive guide to neural networks
CustomField1: Important value
CustomField2: Another important value
Status: published
---

# Neural Networks Guide
...
```

### Regular Mode (Default)
```bash
python madomeda.py
```

**Result:**
```yaml
---
title: Neural Networks Guide
created: '2025-10-23T18:06:22+02:00'
changed: '2025-10-23T18:06:22+02:00'
authors:
- Test User
version: 44ed278
tags: []
---
```

⚠️ **Warning issued:** "Metadata will be discarded: Summary, CustomField1, CustomField2, Status"

### Add-Only Mode
```bash
python madomeda.py --add-only
```

**Result:**
```yaml
---
customfield1: Important value
customfield2: Another important value
status: published
description: This is a comprehensive guide to neural networks
title: Neural Networks Guide
created: '2025-10-23T18:06:22+02:00'
changed: '2025-10-23T18:06:22+02:00'
authors:
- Test User
version: 44ed278
tags: []
---
```

✅ **No warnings** - all fields preserved (after normalization)

## Example 2: Field Renaming Rules

Rules are still applied in add-only mode:

### Input
```yaml
---
Title: My Document
Tag: Python, AI
Summary: Introduction to Python
CustomKey: custom value
---
```

### Add-Only Result
```yaml
---
title: My Document              # Title → title (lowercase)
customkey: custom value         # CustomKey → customkey (lowercase)
description: Introduction to Python  # Summary → description (rule)
created: '2025-10-23T17:27:16+02:00'
changed: '2025-10-23T17:27:16+02:00'
authors:
- John Doe
version: 34d2d05
tags:                           # Tag → tags (rule)
- python                        # Python → python (normalized)
- ai                            # AI → ai (normalized)
---
```

## Rules Applied in Add-Only Mode

1. **Lowercase keys**: All keys converted to lowercase
2. **tag → tags**: Singular renamed to plural
3. **summary → description**: Field rename
4. **Tag normalization**: lowercase_with_underscores

## When to Use Each Mode

### Use Regular Mode When:
- Enforcing strict template compliance
- Starting fresh with standardized metadata
- You want only template-defined fields

### Use Add-Only Mode When:
- Enriching existing documentation
- Preserving custom workflow fields
- Migrating from another system
- You have valuable metadata not in the template

## Combining with Other Options

### Add-Only + WhatIf
Preview what will be added without making changes:
```bash
python madomeda.py --add-only --whatif
```

### Add-Only + No-Confirm
Process without confirmation prompts:
```bash
python madomeda.py --add-only --no-confirm
```

### Add-Only + Ignore-Paths
Preserve custom fields but skip certain directories:
```bash
python madomeda.py --add-only --ignore-paths archive drafts
```

## Field Ordering

In add-only mode, the final frontmatter contains:
1. Normalized original fields (custom keys)
2. Template fields (if not already present)

Order may vary as YAML dictionaries don't guarantee order.