diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2ffdd91
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# DocMachine (Utils)
+
+DocMachine is a CLI tool designed to simplify the process of creating technical documentation and presentations. 
+
+## Motivation
+
+This project aims to address the following challenges:
+
+* **Automation:** Automate the generation of high-quality technical content, including documentation and presentation slides.
+* **Consistency:** Ensure a consistent and polished look and feel across all content pieces.
+* **Efficiency:** Reduce the time and effort required to produce content by leveraging AI tools.
+
+## Features
+
+DocMachine offers a range of features to streamline the content creation process:
+
+* **Scaffolding:** Generate a well-structured project directory with all the necessary files.
+* **Building:** Compile and publish your content as HTML and PDF documents using Dockerized build processes.
+
+We are actively developing the following features for future releases:
+
+* **Planning:** Leverage LLMs (Large Language Models) to generate content outlines tailored to your specific needs and requirements.
+* **Writing:** Utilize LLMs to draft content for each section and subsection, saving you valuable time and effort.
+
+## Prerequisites
+
+FIXME: list prerequisites for crystal lang & dependencies
+
+## Getting Started
+
+Follow these steps to start using DocMachine:
+
+### Installation
+
+```bash
+git clone https://code.apps.glenux.net/glenux/docmachine-utils.git docmachine-utils
+cd docmachine-utils
+make build
+make install
+```
+
+### Create a New Project
+
+```bash
+docmachine scaffold my-doc-project 
+```
+
+This command will create a new directory named `my-doc-project` with the following structure:
+
+```
+my-doc-project
+├── _build
+├── docs
+│   └── images  # link to ../images
+├── slides
+│   └── images  # link to ../images
+└── images
+```
+
+### Start Writing Content
+
+* **Documentation:** Place your Markdown files inside the `docs` directory.
+* **Presentations:** Place your Markdown files (using Marp syntax) inside the `slides` directory.
+* **Images:** Store your images in the respective `images` directories.
+
+### Live-reload during writing
+
+```bash
+docmachine build -a watch
+```
+
+This command will start a Docker container and build your documentation and presentations:
+* **Documentation:** Built using MkDocs and served on `http://localhost:5100`.
+* **Presentations:** Built using Marp and served on `http://localhost:5200`.
+
+### Building content for publishing or presentation
+
+```bash
+docmachine build -a build-slides-pdf
+```
+
+```bash
+docmachine build -a build-docs-pdf
+```
+
+```bash
+docmachine build -a build-docs-html
+```
+
+This command will generate the HTML and PDF versions of your content.
+
+## Contributing
+
+We welcome contributions to DocMachine! To contribute:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Make your changes and commit them.
+4. Submit a pull request.
+
+## License
+
+DocMachine is licensed under the GPL-3.0-or-later license. See the `LICENSE`
+file for details.
+