madomeda/CONFIGURATION.md

Configuration Management

Configuration Directory

Madomeda stores its configuration in a platform-specific location:

• Windows: %USERPROFILE%\.config\madomeda
• macOS: ~/.config/madomeda
• Linux: ~/.config/madomeda

First Run

On first run, Madomeda automatically creates:

~/.config/madomeda/
├── .env                    # API configuration
├── templates/
│   └── default.json        # Default frontmatter template
├── rules/
│   ├── lowercase_keys.json
│   ├── summary_to_description.json
│   ├── tag_to_tags.json
│   └── tags_normalization.json
└── prompts/
    └── default.txt         # Default LLM prompt

Configuration Display

When running in an interactive shell, Madomeda displays configuration info:

Configuration directory: C:\Users\YourName\.config\madomeda
  .env file: C:\Users\YourName\.config\madomeda\.env
  Templates: C:\Users\YourName\.config\madomeda\templates
  Rules: C:\Users\YourName\.config\madomeda\rules
  Prompts: C:\Users\YourName\.config\madomeda\prompts
  API Key: Not configured (LLM features disabled)

In non-interactive mode (pipes, scripts), this info is suppressed.

API Key Configuration

The .env file supports three modes for OPENAI_API_KEY:

1. No API Key (Default)

OPENAI_API_KEY=""

Output:

API Key: Not configured (LLM features disabled)

Behavior: LLM features are disabled, only heuristics and original values used.

2. Environment Variable Reference

OPENAI_API_KEY=$MY_API_KEY

Output:

API Key: From environment variable $MY_API_KEY

Behavior:

• Reads key from environment variable MY_API_KEY
• Error if not found:

  ValueError: Environment variable 'MY_API_KEY' not found.
  Referenced in .env as OPENAI_API_KEY=$MY_API_KEY
  

Setup:

# Linux/macOS
export MY_API_KEY="sk-your-actual-key"

# Windows (PowerShell)
$env:MY_API_KEY = "sk-your-actual-key"

# Windows (CMD)
set MY_API_KEY=sk-your-actual-key

3. Plain Text Key

OPENAI_API_KEY=sk-1234567890abcdef

Output:

API Key: Configured (plain text)
WARNING: Storing API keys in plain text is a security risk!
         Consider using environment variable: OPENAI_API_KEY=$YOUR_ENV_VAR

Behavior: Works but shows security warning every run.

Best Practices

✅ Recommended: Environment Variable

# In .env file
OPENAI_API_KEY=$OPENAI_API_KEY

# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
export OPENAI_API_KEY="sk-your-actual-key"

Benefits:

• Key not stored in config file
• Can be different per user/machine
• Easy to rotate without editing files
• Can use system keyring tools

⚠️ Acceptable: Empty String

OPENAI_API_KEY=""

Use when:

• Don't have LLM access
• Only using heuristics
• Testing/development

❌ Not Recommended: Plain Text

OPENAI_API_KEY=sk-1234567890abcdef

Risks:

• Key visible to anyone with file access
• Accidentally committed to version control
• Hard to rotate across systems

Customizing Configuration

Custom Templates

Create in ~/.config/madomeda/templates/:

# Create minimal template
cat > ~/.config/madomeda/templates/minimal.json << 'EOF'
{
  "title": "heur|orig",
  "date": "heur|orig",
  "tags": "orig"
}
EOF

# Use it
madomeda --template minimal

Custom Rules

Create in ~/.config/madomeda/rules/:

cat > ~/.config/madomeda/rules/my_rule.json << 'EOF'
{
  "name": "my_custom_rule",
  "description": "My custom rule description",
  "type": "custom"
}
EOF

Note: Custom rules require code changes in core/rules.py to implement logic.

Custom Prompts

Create in ~/.config/madomeda/prompts/:

cat > ~/.config/madomeda/prompts/technical.txt << 'EOF'
You are a technical documentation expert.
Focus on API documentation and code examples.
...
EOF

Reference in template:

{
  "summary": "ai technical"
}

Multiple API Providers

Edit OPENAI_API_URL in .env:

# OpenAI
OPENAI_API_URL=https://api.openai.com/v1

# Azure OpenAI
OPENAI_API_URL=https://your-resource.openai.azure.com/

# Local LLM (Ollama)
OPENAI_API_URL=http://localhost:11434/v1

# Other OpenAI-compatible APIs
OPENAI_API_URL=https://api.your-provider.com/v1

Troubleshooting

Config Not Created

Ensure write permissions:

mkdir -p ~/.config/madomeda
chmod 755 ~/.config/madomeda

Environment Variable Not Found

Check it's set:

# Linux/macOS
echo $MY_API_KEY

# Windows (PowerShell)
echo $env:MY_API_KEY

If not set, add to shell profile or set before running:

MY_API_KEY="sk-key" madomeda

Wrong Config Location

Madomeda uses $USERPROFILE (Windows) or $HOME (Unix).

Check:

# Linux/macOS
echo ~/.config/madomeda

# Windows (PowerShell)
echo $env:USERPROFILE\.config\madomeda

API Key Warning on Every Run

This is intentional for plain text keys. Switch to environment variable to suppress.

Migration from Old Version

If you had local .env, templates/, rules/, prompts/ in the repo:

1. Copy to new location:

   cp -r templates ~/.config/madomeda/
   cp -r rules ~/.config/madomeda/
   cp -r prompts ~/.config/madomeda/
   cp .env ~/.config/madomeda/
   

2. Update .gitignore (no longer need to ignore these locally)

3. Old local files are now ignored by the program

Security Notes

• Never commit .env with plain text keys
• Use environment variables or secret management tools
• Config directory is user-specific (not shared)
• On shared systems, ensure ~/.config/madomeda/ has proper permissions:

  chmod 700 ~/.config/madomeda