diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..058ab6b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,152 @@
+# AGENTS.md - Developer Guidelines for ahmza.dad
+
+## Project Overview
+
+This is a simple personal static website hosted at ahmza.dad. The site consists of:
+- `index.md` - Source markdown content
+- `index.html` - Generated HTML (via pandoc)
+- `styles.css` - Styling (retro terminal aesthetic with lime on black)
+- `nginx.conf` - Nginx server configuration
+
+## Build Commands
+
+### Generate HTML from Markdown
+
+```bash
+pandoc index.md -s -o index.html --css styles.css
+```
+
+This single command regenerates `index.html` from the markdown source.
+
+### Development Workflow
+
+1. Edit `index.md` to change content
+2. Run the pandoc command above to regenerate HTML
+3. Test locally by opening `index.html` in a browser
+
+### Deployment
+
+This is a static site served by nginx. The `nginx.conf` shows the configuration:
+- Serves from `/usr/share/nginx/html`
+- Uses `index.html` as the default index
+- Has gzip compression enabled
+- Caches static assets (images, CSS, JS) for 1 year
+
+To deploy, copy the files to the nginx html directory:
+```bash
+# Copy files to nginx directory (adjust path as needed)
+cp index.html styles.css /usr/share/nginx/html/
+# Reload nginx
+nginx -s reload
+```
+
+## Code Style Guidelines
+
+### General Principles
+
+- Keep it simple - this is a minimal static site
+- No JavaScript required unless absolutely necessary
+- No build tools, no frameworks
+
+### Markdown (index.md)
+
+- Use standard Markdown syntax
+- Front matter (YAML) goes at the top between `---` delimiters
+- Keep paragraphs concise and readable
+- Use minimal formatting - the site doesn't need complex markdown features
+
+### HTML (index.html)
+
+This file is GENERATED by pandoc - DO NOT EDIT DIRECTLY. All changes should be made to `index.md` and then regenerated.
+
+If you must hand-edit HTML:
+- Use 2 spaces for indentation
+- Lowercase tags and attributes
+- Quote all attribute values
+- Self-closing tags for void elements (`<meta />`, `<link />`, etc.)
+- Keep attributes in consistent order: `class`, `id`, `src`, `alt`, `href`, etc.
+
+### CSS (styles.css)
+
+The existing style uses a retro terminal aesthetic:
+- Background: black (`#000`)
+- Text: lime green (`lime` or `#00FF00`)
+- Font: Verdana/sans-serif, 14px base size
+
+When modifying:
+- Use 2 spaces for indentation
+- One selector per line, properties on new lines
+- Properties: value with space after colon
+- Use hex colors or named colors (like `lime`)
+- Group related styles together
+- Keep specificity low - avoid overly specific selectors
+
+Example:
+```css
+body {
+    background: #000;
+    color: lime;
+}
+
+.title {
+    color: lime;
+    padding: 10px;
+}
+```
+
+### Naming Conventions
+
+- Files: lowercase with hyphens (e.g., `styles.css`, `index.html`)
+- CSS classes: lowercase with hyphens (e.g., `.title`, `.text`)
+- IDs: lowercase with hyphens when needed
+
+### Error Handling
+
+There is no error handling in this static site. If the page doesn't load:
+1. Check that `index.html` exists and is valid
+2. Verify `styles.css` is linked correctly
+3. Check nginx error logs: `/var/log/nginx/error.log`
+
+## File Structure
+
+```
+ahmza-dad/
+├── index.md        # SOURCE - edit this file
+├── index.html      # GENERATED - do not edit directly
+├── styles.css      # Stylesheet
+├── nginx.conf      # Nginx configuration
+├── .gitignore      # Git ignore rules
+└── .gitea/
+    └── README.md   # Project notes
+```
+
+## Common Tasks
+
+### Adding a new page
+
+1. Create new markdown file (e.g., `about.md`)
+2. Add front matter with title
+3. Run: `pandoc about.md -s -o about.html --css styles.css`
+4. Add to nginx.conf or link from existing pages
+
+### Adding images
+
+1. Place images in the same directory as `index.html`
+2. Reference with relative path: `<img src="image.png" alt="description">`
+3. Images are cached for 1 year per nginx.conf
+
+### Changing the theme
+
+Edit `styles.css`. The current theme is:
+- Black background with lime green text
+- Verdana font
+- Centered content with padding
+
+## Notes for Agents
+
+- This is a very simple project - no complexity is needed
+- Always edit `index.md` not `index.html` for content changes
+- Run the pandoc command after any markdown changes
+- No tests exist - manual verification is sufficient
+- No linting configured
+- Commit messages should be clear but brief