madomeda/LITERAL_VALUES.md

# Template Strategy: Literal Values

## Overview

Templates support static/literal values using the `lit:` prefix. This allows you to specify fallback values when other strategies don't produce results.

## Syntax

```json
{
  "field": "strategy1|strategy2|lit:static value"
}
```

## Strategy Types

1. **heur** - Use heuristics (git history, document analysis)
2. **orig** - Use original frontmatter value
3. **ai <prompt>** - Use LLM inference
4. **lit:value** - Use literal/static value

## Execution Order

Strategies are tried **left to right** until one returns a non-null value.

## Examples

### Example 1: Author Fallback

If git history has no authors, use a default:

```json
{
  "authors": "heur|orig|lit:Ole Valente <ole@covalente.dk>"
}
```

**Behavior:**
- Try heuristics (git authors)
- If empty, try original frontmatter
- If still empty, use "Ole Valente <ole@covalente.dk>"

### Example 2: Status Field

Always set a status field to "draft":

```json
{
  "status": "lit:draft"
}
```

**Behavior:**
- Immediately use "draft" (no other strategies)

### Example 3: Version with Fallback

```json
{
  "version": "heur|orig|lit:0.1.0"
}
```

**Behavior:**
- Try git tag/hash
- If no git, try original
- If still nothing, use "0.1.0"

### Example 4: Category

```json
{
  "category": "orig|lit:uncategorized"
}
```

**Behavior:**
- Use original category if exists
- Otherwise mark as "uncategorized"

### Example 5: Complete Template with Fallbacks

```json
{
  "title": "heur|orig|lit:Untitled Document",
  "created": "heur|orig",
  "changed": "heur|orig",
  "authors": "heur|orig|lit:Unknown Author",
  "version": "heur|orig|lit:0.1.0",
  "tags": "heur|orig|ai default",
  "status": "lit:draft",
  "category": "orig|lit:general"
}
```

## List Values

For list fields (like tags), use JSON array notation:

```json
{
  "tags": "heur|orig|lit:[]"
}
```

This creates an empty list if no tags are found.

Or with default tags:

```json
{
  "keywords": "orig|lit:[\"general\", \"misc\"]"
}
```

**Note:** List values in `lit:` are parsed as strings, so complex structures should be avoided. For lists, prefer empty `[]` or use AI inference.

## Common Patterns

### Pattern 1: Required Field with Default

```json
{
  "author": "orig|lit:Anonymous"
}
```

### Pattern 2: Preserve Original or Set Default

```json
{
  "priority": "orig|lit:medium"
}
```

### Pattern 3: Try Everything, Then Default

```json
{
  "summary": "orig|ai default|lit:No description available"
}
```

### Pattern 4: Static Value (No Fallback Needed)

```json
{
  "type": "lit:document",
  "format": "lit:markdown"
}
```

## Use Cases

### 1. Personal Knowledge Base

Set yourself as default author:

```json
{
  "authors": "heur|lit:Jane Doe <jane@example.com>"
}
```

### 2. Organization Defaults

```json
{
  "organization": "lit:Acme Corp",
  "license": "lit:MIT",
  "confidential": "lit:false"
}
```

### 3. Workflow States

```json
{
  "status": "orig|lit:draft",
  "reviewed": "orig|lit:false",
  "published": "orig|lit:false"
}
```

### 4. Document Classification

```json
{
  "type": "lit:article",
  "category": "orig|ai default|lit:uncategorized",
  "audience": "orig|lit:internal"
}
```

## Special Considerations

### Empty Strings

```json
{
  "note": "lit:"
}
```

This sets the field to an empty string.

### Spaces in Values

Spaces are preserved:

```json
{
  "title": "lit:My Document Title"
}
```

Results in: `title: "My Document Title"`

### Multiple Words

No quotes needed in template:

```json
{
  "author": "lit:John Smith"
}
```

### Email Addresses

Special characters work fine:

```json
{
  "contact": "lit:admin@example.com"
}
```

### Lists (Advanced)

For simple lists, you can use:

```json
{
  "reviewers": "lit:[]"
}
```

But for populated lists, prefer AI or heuristics as literal list parsing is string-based.

## Testing Your Template

### Test with --whatif

```bash
madomeda --template my-template --whatif
```

### Check a specific file

```bash
# Process just one file
madomeda --template my-template | grep -A 10 "Processing: myfile.md"
```

## Troubleshooting

### Literal Value Not Applied

**Issue:** Field is empty even with `lit:value`

**Cause:** Another strategy succeeded earlier in the chain

**Solution:** Move `lit:` to the beginning if you want it to always apply:
```json
{
  "status": "lit:draft"  // Always use draft
}
```

### Wrong Value Type

**Issue:** List field gets string instead of array

**Cause:** `lit:` with complex JSON isn't parsed

**Solution:** Use `lit:[]` for empty lists, or use AI/heuristics for populated lists

## Complete Example Template

**File:** `~/.config/madomeda/templates/blog-post.json`

```json
{
  "title": "heur|orig|lit:Untitled Post",
  "date": "heur|orig",
  "author": "heur|orig|lit:Blog Team",
  "category": "orig|lit:general",
  "tags": "orig|ai default",
  "status": "lit:draft",
  "published": "orig|lit:false",
  "featured": "orig|lit:false",
  "excerpt": "orig|ai excerpt"
}
```

**Usage:**
```bash
madomeda --template blog-post
```

**Result for new file:**
```yaml
---
title: My Blog Post  # From # heading
date: '2025-10-23T19:30:00+02:00'  # From git
author: Blog Team  # Literal fallback (no git author found)
category: general  # Literal (no original)
tags:  # From AI
- blogging
- tutorials
status: draft  # Literal
published: false  # Literal
featured: false  # Literal
excerpt: A comprehensive guide...  # From AI
---
```

## Best Practices

1. **Always provide fallbacks** for critical fields
2. **Use heur first** to leverage git metadata
3. **Use orig second** to preserve existing values
4. **Use lit last** as safety net
5. **Keep literals simple** - avoid complex structures
6. **Document your templates** in comments (though JSON doesn't support them, keep external docs)

## See Also

- [CONFIGURATION.md](CONFIGURATION.md) - Template configuration
- [USAGE.md](USAGE.md) - Template usage examples
- [STRUCTURE.md](STRUCTURE.md) - Template system architecture