diff --git a/README.md b/README.md
index c37d677..60bdf54 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,91 @@
-# blog
+# Blog / Knowledge Base
 
-Blogging structure with SEO markup
\ No newline at end of file
+A lightweight, drop-in blog or knowledge base site for static or dynamic content. Designed for developers and technical users who prefer writing in **Markdown** or simplified **PHP**.
+
+## Features
+
+- Markdown-based article system with YAML frontmatter
+- Optional simplified PHP templates (e.g. `marketing.php`)
+- SEO-friendly output with sitemap generation
+- Lightweight footprint — no database required
+- Easy to theme with `template.inc`
+
+## Directory Structure
+
+```
+.
+├── index.php          # Blog listing and router
+├── sitemap.php        # Generates XML sitemap
+├── template.inc       # Base template
+├── articles/          # Markdown or PHP articles
+│   ├── example.md
+│   └── announcement.php
+└── README.md
+```
+
+## Writing Articles
+
+Articles live in the `articles/` folder and can be written as:
+
+### Markdown (`.md`)
+
+Use YAML frontmatter to describe article metadata:
+
+```markdown
+---
+title: "New Feature Release"
+date: 2025-06-10
+tags: [update, release]
+slug: new-feature-release
+---
+
+We’re happy to announce...
+```
+
+### Simplified PHP (`.php`)
+
+For more control or dynamic output, use a basic PHP file:
+
+```php
+<!--
+---
+title: Special Announcement
+date: "2025-06-10"
+tags: ['announcement', 'promo']
+---
+-->
+<p>This is rendered directly in PHP.</p>
+```
+
+## Installation
+
+This site is designed to run under any PHP 7+ web host or server:
+
+```bash
+git clone https://tea.kuzik.com/jittr/blog.git myblog
+cd myblog
+```
+
+Ensure your server routes requests to `index.php`, and PHP has read access to the `articles/` directory.
+
+## Configuration
+
+- Articles are auto-discovered from `articles/`
+- Optional `.htaccess` is provided for clean URLs (Apache)
+- Customize the look via `template.inc`
+
+## Security Notes
+
+- PHP articles are executed directly — avoid untrusted uploads.
+- No authentication is included by default.
+
+## TODO / Roadmap
+
+- [ ] Pagination support
+- [ ] Tag-based filtering
+- [ ] Atom/RSS feed generation
+- [ ] Admin or CLI article previewing
+
+## License
+
+MIT — use freely for personal or commercial use.
\ No newline at end of file