Merge pull request 'docs: update README with project overview, structure and workflow' (#6) from docs/update-readme into main

Reviewed-on: https://codeberg.org/gurix/markusgraf_ch/pulls/6

README.md

@@ -1,23 +1,63 @@
-# Markus Graf - Personal Website
+# markusgraf.ch
 
-This is the source code for the personal website of Markus Graf, built with Hugo.
+Source code for [markusgraf.ch](https://markusgraf.ch) — personal website of Markus Graf, built with [Hugo](https://gohugo.io/).
 
-## LLM Friendliness
+## About
 
-This website includes an `llms.txt` file in the root directory (served from `static/llms.txt`) to help Large Language Models (LLMs) discover and understand the content of the site. This file follows the [llms.txt specification](https://llmstxt.org/).
+Markus Graf is a developer, BSc Psychology graduate, and consultant based in Switzerland. The site serves as his personal blog and digital CV. Topics include AI agents, ADHD & productivity, digital tools, and tech experiments.
 
-When adding new content, please ensure that:
-1.  Important pages are listed in `static/llms.txt`.
-2.  Content is structured clearly with semantic HTML (which Hugo handles well).
-3.  Future improvements may include generating `.md` versions of pages for direct LLM consumption.
+## Tech Stack
 
-## Development
+- **Static site generator**: [Hugo](https://gohugo.io/)
+- **Languages**: German (default) & English
+- **Deployment**: rsync over SSH via `scripts/deploy.sh`
+- **Hosted at**: markusgraf.ch
+
+## Site Structure
+
+```
+content/
+├── blog/           # Blog posts (bilingual, DE + EN)
+├── cv.de.md        # Lebenslauf (DE)
+└── cv.en.md        # Curriculum Vitae (EN)
+```
+
+Blog posts are organized as page bundles (one folder per post). Each post has a `translationKey` to link its language variants.
+
+## Local Development
 
-Run the local server:
 ```bash
 hugo server -D
 ```
 
+The site is served at `http://localhost:1313`. Draft posts (`-D`) are included.
+
 ## Deployment
 
-See `DEPLOYMENT.md`.
+The site is deployed via rsync. See [DEPLOYMENT.md](DEPLOYMENT.md) for the full guide.
+
+```bash
+hugo build
+export SSH_USER='user'
+export SSH_HOST='server.com'
+./scripts/deploy.sh
+```
+
+## Workflow
+
+All changes go through feature branches. See [AGENTS.md](AGENTS.md) for the full Git workflow and OpenSpec conventions.
+
+```bash
+git checkout -b feature/my-change
+# make changes
+git commit -m "feat: description"
+# open pull request
+```
+
+Commit message conventions: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
+
+## LLM Friendliness
+
+The site includes a `static/llms.txt` file following the [llms.txt specification](https://llmstxt.org/), listing key pages for LLM discovery. When adding content, keep `static/llms.txt` up to date.
+
+AI assistants working in this project should read [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) for project-specific instructions.