Probably functional. Testing

CONFIGURATION.md

@@ -0,0 +1,287 @@
+# 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)
+
+```bash
+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
+
+```bash
+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:**
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+OPENAI_API_KEY=""
+```
+
+**Use when:**
+- Don't have LLM access
+- Only using heuristics
+- Testing/development
+
+### ❌ Not Recommended: Plain Text
+
+```bash
+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/`:
+
+```bash
+# 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/`:
+
+```bash
+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/`:
+
+```bash
+cat > ~/.config/madomeda/prompts/technical.txt << 'EOF'
+You are a technical documentation expert.
+Focus on API documentation and code examples.
+...
+EOF
+```
+
+Reference in template:
+```json
+{
+  "summary": "ai technical"
+}
+```
+
+## Multiple API Providers
+
+Edit `OPENAI_API_URL` in `.env`:
+
+```bash
+# 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:
+```bash
+mkdir -p ~/.config/madomeda
+chmod 755 ~/.config/madomeda
+```
+
+### Environment Variable Not Found
+
+Check it's set:
+```bash
+# Linux/macOS
+echo $MY_API_KEY
+
+# Windows (PowerShell)
+echo $env:MY_API_KEY
+```
+
+If not set, add to shell profile or set before running:
+```bash
+MY_API_KEY="sk-key" madomeda
+```
+
+### Wrong Config Location
+
+Madomeda uses `$USERPROFILE` (Windows) or `$HOME` (Unix).
+
+Check:
+```bash
+# 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:
+   ```bash
+   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:
+  ```bash
+  chmod 700 ~/.config/madomeda
+  ```