add changelog and update readme

Author: aplgr

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on *Keep a Changelog* and the project follows a pragmatic form of semantic versioning.
+
+
+
+## [0.1.0] - 2026-01-17
+
+### Added
+- Convert FastNotepad exports to Obsidian-ready Markdown (one note per file).
+- Parse FastNotepad multi-block export format (`index` preview + `_<id>` full text).
+- CLI options:
+  - `--by-category` to write notes into category subfolders
+  - `--tag` to add `fastnotepad` + category tag
+  - `--dry-run` to plan outputs without writing files
+  - `--no-frontmatter` to write plain Markdown
+  - `--encoding` to force input encoding
+- Filename collision handling with ` (2)`, ` (3)`, ...
+- Anonymized example dataset and pytest-based test suite.

README.md

@@ -1,37 +1,59 @@
 # FastNotepad → Obsidian Migrator
 
-Convert Android **FastNotepad** exports into **Obsidian-ready Markdown**.
+[![Tests](https://github.com/aplgr/fastnotepad-to-obsidian/actions/workflows/tests.yml/badge.svg)](https://github.com/aplgr/fastnotepad-to-obsidian/actions/workflows/tests.yml)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](../../pulls)
+
+Convert Android **FastNotepad** exports into **Obsidian-ready Markdown** (one note per file).
 
 - One note per `.md` file
-- Optional category folders
-- Optional Obsidian tags
-- Optional YAML front matter
-- Handles the FastNotepad export quirk where the **preview** lives in the `index` block, while the **full note body** is stored separately as `_<id>` keys.
+- Optional category folders (`--by-category`)
+- Optional Obsidian tags (`--tag`)
+- Optional YAML front matter (default) or plain Markdown (`--no-frontmatter`)
+- Handles the FastNotepad export quirk where the **preview** lives in the `index` block, while the **full note body** is stored separately as `_<id>` keys
+
 
 ## Requirements
 
 - Python 3.9+
 
-## Install (optional)
+## Install
+
+### Recommended: pipx (isolated CLI install)
+
+Install directly from GitHub:
+
+```bash
+pipx install git+https://github.com/aplgr/fastnotepad-to-obsidian.git
+```
+
+### Alternative: pip
 
 ```bash
 pip install .
 ```
 
 This installs a CLI command: `fastnotepad2obsidian`.
 
+### No install (run from source)
+
+```bash
+python3 scripts/fastnotepad2obsidian.py --help
+# or
+PYTHONPATH=src python3 -m fastnotepad_to_obsidian --help
+```
+
 ## Quickstart
 
 ```bash
 fastnotepad2obsidian FastNotepad_2026-01-05 Vault/Inbox --by-category
 ```
 
-Or without installation:
+Dry-run (show what would be created, but write nothing):
 
 ```bash
-python3 scripts/fastnotepad2obsidian.py FastNotepad_2026-01-05 Vault/Inbox --by-category
-# or
-PYTHONPATH=src python3 -m fastnotepad_to_obsidian FastNotepad_2026-01-05 Vault/Inbox --by-category
+fastnotepad2obsidian FastNotepad_2026-01-05 Vault/Inbox --by-category --dry-run
 ```
 
 ## CLI options
@@ -60,7 +82,7 @@ tags: [fastnotepad, work]
 
 ### No front matter
 
-Write plain markdown without YAML front matter:
+Write plain Markdown without YAML front matter:
 
 ```bash
 fastnotepad2obsidian FastNotepad_2026-01-05 Vault/Inbox --no-frontmatter
@@ -90,13 +112,36 @@ Supported values depend on Python, e.g.: `utf-8`, `utf-8-sig`, `utf-16`, `utf-16
 - Collisions are resolved with ` (2)`, ` (3)`, ...
 - With `--by-category`, notes are written into subfolders by category (slugified). Empty category becomes `Unsorted`.
 
-## Limitations
+## Supported export format
+
+This tool supports the FastNotepad export format that looks like:
+
+- `<prefix>#<json_block_1>{[!*|@]}<json_block_2>{[!*|@]}...`
+- `json_block_1` contains `index` with `^!` note records (metadata + preview text)
+- Later blocks contain the full texts keyed as `_<id>`
+
+If your app uses a different format, open an issue with a **sanitized** snippet.
+
+## Safety & privacy
+
+- This tool runs locally and does **not** make network requests.
+- Your export file may contain highly sensitive data (passwords, addresses, etc.).
+  Please do **not** attach real exports to public issues. If you need help, redact the content first.
 
-- This supports the export format that looks like:
-  - `<prefix>#<json_block_1>{[!*|@]}<json_block_2>{[!*|@]}...`
-  - `json_block_1` contains `index` with `^!` note records
-  - Later blocks contain the full texts keyed as `_<id>`
-- If your app uses a different format, open an issue with a **sanitized** snippet.
+## Troubleshooting
+
+- **`JSONDecodeError: Extra data`**: Your export has multiple blocks / trailing content. This tool extracts and merges JSON blocks separated by `{[!*|@]}`.
+- **Some notes remain short**: Those notes may not have a corresponding `_<id>` full-text entry in the export. The tool will fall back to the preview text from the `index` block.
+- **Weird characters**: rerun with `--encoding ...` (e.g. `latin-1`, `utf-16`).
+
+## Contributing
+
+PRs and format samples are welcome.
+
+If you open an issue because your export differs, please include:
+- the app name + version
+- a **sanitized** export snippet (header + one note record + the `_<id>` mapping)
+- the exact command you ran and the output
 
 ## Development
 
@@ -107,6 +152,11 @@ pip install -e .[dev]
 pytest
 ```
 
+## Roadmap (on purpose)
+
+- Improve slugging/filename templates
+- More resilient format detection if FastNotepad changes the export structure
+
 ## License
 
 MIT