AGENTS.md — Project Instructions

What is this

Bilingual (English + Hebrew) cybersecurity research blog built with Jekyll. Deployed on GitHub Pages from main branch.

Live site: https://danieloz147.github.io

Language — CRITICAL

• The user communicates in Hebrew. Always respond in Hebrew unless writing code/content for the English version of the site.
• Every content change must be made in BOTH languages. English posts live in _posts/, Hebrew translations in _he/. If you add, edit, or remove content in one — do the same in the other. No exceptions.
• UI strings are in _data/i18n.yml — every key must have both en and he values.
• Hebrew pages use dir="rtl". Code/terminal elements inside Hebrew pages need dir="ltr" and unicode-bidi: embed to display correctly.

File structure

_posts/           English posts (markdown)
_he/              Hebrew posts (markdown, same filenames)
_layouts/         default.html (main layout), post.html
_includes/        home.html, posts-list.html, analytics.html
_data/i18n.yml    All UI strings (EN + HE)
assets/css/       main.css (single file, no framework)
assets/js/        site-analytics.js
assets/images/og/ Auto-generated OG images (via scripts/generate-og.js)
scripts/          OG image generator (Node.js, Satori + resvg)
_config.yml       Jekyll config — requires server restart on changes

Running locally

.\server-up.ps1

This runs Jekyll in Docker on port 4000. _config.yml changes require stopping and re-running.

OG images

When adding a new post, generate its OG image:

cd scripts && node generate-og.js

Then add og_image: /assets/images/og/<slug>.png to the post’s front matter (both EN and HE versions). Hebrew posts get he- prefix: he-<slug>.png.

Post conventions

• Front matter must include: layout, title, subtitle, date, post_id, tags, description, og_image
• post_id determines ordering on the homepage — higher = newer
• Tags are lowercase kebab-case
• English and Hebrew posts share the same filename (date-slug format)

Hidden features

• CTF: 10 flags hidden across the site (console, HTML source, robots.txt, 404, CSS, data attribute, invisible text, Konami code, favicon SVG, XOR cipher). Console says “1 of 10”.
• Tab animation: When user leaves the tab, title animates with hacker-themed messages, then restores on return.
• Console message: ASCII art + first CTF flag shown in DevTools.
• Report form: Terminal-style modal using Formsubmit.co (hash in _config.yml). Hidden iframe submission, no CORS issues.

Formsubmit

Email hash: 8fbbc51c2ebddb2866cb47922566cc69 (in _config.yml). Do NOT change this — it’s the working hash that delivers emails.

Deployment

• GitHub Pages from main branch (repo must stay public for free Pages)
• Push to main triggers automatic build
• No custom GitHub Actions workflow — uses default Pages deployment

Style

• Terminal/hacker aesthetic — dark theme primary, light theme supported
• Accent color: #00e5b0 (green), secondary: #5b9fff (blue)
• Fonts: JetBrains Mono (code/headings), Inter (body), Heebo (Hebrew)
• No frameworks, no jQuery — everything is vanilla JS and CSS
• Keep the design consistent: dark bg, green accents, monospace feel

Writing — avoid AI tells

The blog is written by a human. Content must read like a human wrote it.

Patterns to avoid:

• Symmetric phrasing: “X is not Y — it’s Z”, “not A, but B”
• Clean parallel structures: three bullet points that all start the same way
• Formulaic hedging: “it’s worth noting”, “this is not trivial”, “to be clear”
• Overly tidy lists: real arguments don’t come in perfectly matched sets of three
• Starting paragraphs with “And” or “But” repeatedly as a rhythm trick
• Wrapping up too neatly — real writing leaves some edges rough
• Em dash overuse (—) as a crutch for every aside
• Ending sections with a “punchy one-liner” that sounds like a TED talk

Characters and phrases that scream AI (EN):

• “It’s worth noting that…”
• “This is not trivial.”
• “Perhaps more importantly…”
• “The implications are clear.”
• “This is not just about X — it’s about Y.”
• “Let that sink in.”
• “In other words…”
• “To put it simply…”
• Excessive use of colons before lists
• “Indeed,” at the start of a sentence

Characters and phrases that scream AI (HE):

• “זה לא זניח”
• “שווה לציין ש…”
• “במילים אחרות…”
• “בו-זמנית” as a sentence ender
• “פשוט בהצהרה ומורכב בביצוע” or any symmetric formula
• “זה לא X — זה Y” pattern
• “ודווקא כאן…”
• “התשובה, כצפוי, מורכבת”

How to check: Read it out loud. If it sounds like a LinkedIn post, a consulting deck, or a conference keynote — rewrite. If every paragraph lands on a neat conclusion — break one. If the structure is too clean — mess it up a little. Real expertise sounds confident but imperfect.