From b60c5ee619e46f9d1cbbf002a1c5e80c0827a92c Mon Sep 17 00:00:00 2001
From: th <th@skilleven.de>
Date: Tue, 7 Apr 2026 22:45:33 +0200
Subject: [PATCH] readme

---
 README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e60328
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+# hyprcrd
+
+A self-hosted card/note manager with markdown, tags, image galleries, and Obsidian-compatible export.
+
+## Requirements
+
+- PHP 8.3+
+- Apache with `mod_rewrite`
+- PHP extensions: `pdo_sqlite`, `zip`
+
+No external dependencies. All frontend libraries load from CDN.
+
+## Quick Start (Docker)
+
+```bash
+git clone https://git.uesome.de/tanztee/hyprcrd.git
+cd hyprcrd
+docker build -t hyprcrd .
+docker run -d -p 8080:80 -v hyprcrd-data:/var/www/html/data hyprcrd
+```
+
+Open `http://localhost:8080` and set your password on first visit.
+
+The `-v hyprcrd-data:/var/www/html/data` flag persists the database across container restarts.
+
+## Manual Installation
+
+### 1. Clone
+
+```bash
+git clone https://git.uesome.de/tanztee/hyprcrd.git
+cd hyprcrd
+```
+
+### 2. Set document root
+
+Point your web server's document root to the `public/` directory.
+
+**Apache vhost example:**
+
+```apache
+<VirtualHost *:80>
+    ServerName hyprcrd.local
+    DocumentRoot /path/to/hyprcrd/public
+
+    <Directory /path/to/hyprcrd/public>
+        AllowOverride All
+        Require all granted
+    </Directory>
+</VirtualHost>
+```
+
+Make sure `mod_rewrite` is enabled:
+
+```bash
+a2enmod rewrite
+systemctl restart apache2
+```
+
+### 3. Set permissions
+
+```bash
+mkdir -p data public/uploads
+chmod 755 data
+chmod 777 public/uploads
+```
+
+The web server user (e.g. `www-data`) needs write access to both directories.
+
+### 4. PHP settings (optional)
+
+For larger image uploads, adjust in `php.ini`:
+
+```ini
+upload_max_filesize = 20M
+post_max_size = 22M
+```
+
+### 5. Open and set password
+
+Navigate to your URL. On first visit, you'll be prompted to set a password (min. 4 characters). That's it.
+
+## Directory Structure
+
+```
+hyprcrd/
+├── config.php              # App constants (auto-configured)
+├── Dockerfile
+├── docker-entrypoint.sh
+├── src/
+│   ├── bootstrap.php       # Initialization
+│   └── Database.php        # SQLite schema & migrations
+├── public/                 # Document root
+│   ├── index.php           # Entry point & API
+│   ├── .htaccess           # URL rewriting
+│   ├── css/style.css
+│   ├── js/
+│   │   ├── app.js          # Orchestrator
+│   │   └── modules/        # Feature modules
+│   └── uploads/            # User media (writable)
+└── data/
+    └── hyprcrd.db          # SQLite database (auto-created)
+```
+
+## Features
+
+- **Cards** with markdown body, color, tags, and position
+- **Buckets** for organizing cards into groups
+- **Tags** written as `#tagname` or hierarchical `#parent/child` in card body, extracted automatically
+- **Markdown** with `[[Card Title]]` wiki-links, ```` ```gallery ```` image galleries, ```` ```tree ```` list views
+- **Search** combining text and `#tag` filters (e.g. `#project meeting notes`)
+- **Image gallery** with orphan detection and fullscreen viewer
+- **Split view** showing tag-related and content-related cards
+- **Import/Export** as JSON+media ZIP or Obsidian/Logseq-compatible markdown vault
+- **Drag & drop** card reordering and grouping
+- **Keyboard shortcuts**: `Ctrl+K` search, `Shift+scroll` zoom, arrow keys in autocomplete
+
+## Data & Backup
+
+All data lives in two places:
+
+- `data/hyprcrd.db` — SQLite database (cards, buckets, settings)
+- `public/uploads/` — uploaded images and audio
+
+Back up both to preserve everything. The database auto-migrates on startup.
+
+## Export Formats
+
+- **JSON export** (`export` button) — full backup with media, re-importable
+- **Markdown vault** (`vault` button) — Obsidian/Logseq-compatible structure:
+  ```
+  Bucket Name/
+    Card Title.md      # YAML frontmatter + markdown body
+  attachments/
+    image.jpg
+  ```
+
+## Security
+
+- Bcrypt password hashing
+- CSRF protection on all mutations
+- Rate-limited login (5 attempts/60s)
+- Upload directory blocks PHP execution
+- DOMPurify sanitizes all rendered markdown
+- Security headers (X-Frame-Options, HSTS, etc.)
+
+## License
+
+MIT