website/AGENTS.md

# CQRE.NET Website — Agent Guide

## Project Overview

This is the static site for [cqre.net](https://cqre.net), built with [Hugo](https://gohugo.io/). It is a bilingual (English and Czech) corporate website for CQRE.NET — the business name of CZ Expert, s.r.o., a Czech cybersecurity consultancy founded around 2000 and operating from Prague. The site promotes:

- **Open-source M365 governance tools**: PULSAR (audit log ingestion), ASTRAL (configuration snapshots / drift detection), and AURORA (commercial AI-assisted operations layer).
- **Consulting services**: Antifragile security consulting under the Brownhat methodology, and fractional vCISO engagements.

The site is intentionally simple: no JavaScript frameworks, no npm, no asset pipelines beyond Hugo itself. A single hand-written CSS file drives the dark-themed UI.

## Technology Stack

| Layer | Technology |
|-------|------------|
| Static Site Generator | Hugo Extended, v0.120+ |
| Templating | Hugo Go Templates |
| Styling | Single vanilla CSS file (`static/css/main.css`) |
| Content Format | Markdown with YAML front matter |
| Translations | Hugo i18n (`i18n/en.yaml`, `i18n/cs.yaml`) |
| Hosting | Static — deploy the `public/` directory |

## Project Structure

```
.
├── hugo.yaml              # Site config: baseURL, languages, params, markup
├── content/
│   ├── en/                # English content (default language)
│   │   ├── _index.md      # Homepage (front-matter only, no body)
│   │   ├── about.md       # About & contact
│   │   ├── vciso.md       # Virtual CISO service page
│   │   ├── consulting/
│   │   │   ├── _index.md  # Consulting methodology
│   │   │   └── skills.md  # 14 consulting modules listing
│   │   └── products/
│   │       ├── _index.md  # Products overview
│   │       ├── pulsar.md
│   │       ├── astral.md
│   │       └── aurora.md
│   └── cs/                # Czech content — mirrors en/ structure exactly
├── layouts/
│   ├── _default/
│   │   ├── baseof.html    # Base HTML skeleton (head, header, footer blocks)
│   │   ├── single.html    # Single page template (products, about, vciso)
│   │   └── list.html      # Section list template (consulting/, products/)
│   ├── index.html         # Homepage layout (heavily custom)
│   └── partials/
│       ├── head.html      # Meta tags, CSS link, favicon
│       ├── header.html    # Sticky nav with language switcher
│       └── footer.html    # Footer links and copyright
├── i18n/
│   ├── en.yaml            # English UI strings (nav, buttons, labels)
│   └── cs.yaml            # Czech UI strings
└── static/css/main.css    # Complete site stylesheet (dark theme, ~400 lines)
```

## Build and Development Commands

**Prerequisite**: Hugo Extended edition must be installed (v0.120 or newer).

```bash
# Local development server with draft content
hugo server -D
# Site is available at http://localhost:1313

# Production build (minified)
hugo --minify
# Output is written to public/
```

There is no test suite, no linting, and no package manager. The build is a single Hugo invocation.

## Content Editing Conventions

### Front Matter

Every content file uses YAML front matter. Common fields:

| Field | Purpose |
|-------|---------|
| `title` | Page title (used in `<title>`, headings, navigation) |
| `description` | Meta description and SEO |
| `eyebrow` | Small label above the main heading on single pages |
| `lead` | Introductory paragraph below the heading |
| `actions` | Array of CTA buttons `{ label, url, primary, external }` |
| `icon` | Emoji displayed in product cards |
| `badge` | Product badge `{ text, color }` where color is `green`, `orange`, or `blue` |

The homepage (`_index.md`) has no Markdown body. All homepage content is defined in front matter and rendered by `layouts/index.html`.

### Rich Layouts in Markdown

Because `markup.goldmark.renderer.unsafe` is enabled in `hugo.yaml`, content files may contain raw HTML for layout components. Common patterns:

- **Feature lists**: `<div class="feature-list">` containing `<div class="feature-item">` with an icon div and body div.
- **Pillars**: `<div class="pillars">` containing `<div class="pillar">` with a numbered heading.
- **Module grids**: `<div class="modules-grid">` containing `<div class="module-card">` with metadata badges.
- **CTA strips**: `<div class="cta-strip">` with a heading, paragraph, and action buttons.

When editing content that uses these blocks, preserve the CSS class names exactly — they are tightly coupled to `static/css/main.css`.

### Bilingual Content

- English is the default language (`defaultContentLanguage: en`).
- Czech content lives under `content/cs/` and mirrors the English structure file-for-file.
- The header partial generates language switcher links automatically via `.Translations`.
- Internal links in templates must use `relLangURL` to preserve the correct language prefix.
- UI strings (navigation labels, buttons, footer text) live in `i18n/en.yaml` and `i18n/cs.yaml`.

When adding a new page, create it in **both** `content/en/` and `content/cs/` and add any new UI strings to both i18n files.

## Code Style Guidelines

### Templates

- Use 2-space indentation in all HTML and Go template files.
- Prefer `relLangURL` for all internal links so language switching works correctly.
- Use `i18n` function for all user-facing strings in templates.
- The `baseof.html` layout defines a `main` block; all page templates override it with `{{ define "main" }}`.

### CSS

- The entire site uses a single stylesheet: `static/css/main.css`. Do not add additional CSS files.
- The design is a dark theme based on CSS custom properties in `:root` (navy backgrounds, sky-blue accent, muted text).
- Utility classes exist at the bottom of the file (e.g., `.mt-4`, `.text-center`).
- Keep CSS simple and dependency-free.

### Markdown / Content

- Use standard Markdown for prose.
- Use tables for structured comparisons (the about page uses this for principles).
- When embedding HTML in Markdown, keep it well-indented and use the established component classes.

## Testing

There are no automated tests. Verify changes by:

1. Running `hugo server -D`.
2. Checking both language versions of affected pages.
3. Testing responsive layout at mobile widths (the CSS has breakpoints at 768px and 480px).
4. Verifying internal links and the language switcher work correctly.

## Deployment

The `public/` directory is the deployable artifact. Copy it to any static web host.

The README includes an example Gitea Actions workflow (`.gitea/workflows/deploy.yml`) for self-hosted Gitea instances. The repo is also mirrored to GitHub (`github.com/cqrenet`).

## Security Considerations

- **`unsafe: true` is enabled** in the Goldmark renderer (`hugo.yaml`). This allows raw HTML inside Markdown content files. It is required because pages use rich layout components (feature lists, module grids, etc.) written as inline HTML. Do not disable this setting without migrating those components to shortcodes.
- The site has **no backend, no forms, and no user data collection**. It is a purely static read-only site.
- External links use `target="_blank" rel="noopener"` (generated by the `single.html` template when `external: true` is set in front matter).
- The favicon is an inline SVG data URI containing a lock emoji — no external image request.

## External References

- **GitHub org**: https://github.com/cqrenet
- **Gitea**: https://git.cqre.net
- **Contact email**: hello@cqre.net