Remove test file

2025-10-23 18:33:48 +02:00
parent 0463d73ef9
commit 8c4f612e4b
33 changed files with 2718 additions and 25 deletions
@@ -0,0 +1,262 @@
+# 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
+
+1. Create `rules/my_rule.json`:
+   ```json
+   {
+     "name": "my_custom_rule",
+     "description": "Description of what this rule does",
+     "type": "custom"
+   }
+   ```
+
+2. Implement logic in `core/rules.py` (requires code modification)
+
+### 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
+   - `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.