# WordPress work rules for AI agents

This directory contains the live WordPress site for `https://contabilitatea-md.ideea.studio`.
Use this file as the local operating guide when you work inside `wordpress`.

## Project scope

You are working on the production WordPress implementation of
`https://contabilitatea-md.ideea.studio`. The goal is to keep the site stable, editable through
ACF Pro, and consistent across templates, global settings, and frontend output.

Key paths:

- WordPress root: `wordpress`
- Active theme:
  `wordpress/wp-content/themes/contabilitatea-theme`

## Main rule

Do not redesign sections, reorder items, or introduce new layout freedom
unless the user explicitly asks for it. Preserve the established structure and
editing model of the custom theme.

## What is editable and what is fixed

When you change a section, decide this explicitly before editing code:

- theme templates control structure, layout, order, and fixed composition
- ACF controls text, images, links, and repeaters that were intentionally made
  editable
- the client must not receive edit controls that can break the layout

If a section has a fixed number of cards, steps, stats, or timeline items in
the theme design, keep that structure fixed in WordPress too.

## Required workflow for any page or section

For every migration, fix, or content parity task, verify in this order:

1. Read the PHP template that renders the section.
2. Read the helper or ACF field definitions that feed the template.
3. Check the real saved WordPress data, not only fallback values.
4. Review the CSS and JS that affect the final behavior.
5. Verify the served HTML from WordPress.
6. Verify the section visually in a browser on desktop and mobile.

Do not consider a task complete only because the template source looks
correct. Confirm what WordPress actually serves.

## WordPress-specific implementation rules

When editing the theme:

- prefer changes in the custom theme, not in WordPress core
- keep reusable logic in `inc/helpers.php` when multiple templates depend on
  it
- define or update ACF local field groups in `inc/acf-fields.php`
- keep seed and fallback data synchronized in `inc/default-content.php`
- use WordPress escaping correctly:
  - text: `esc_html()`
  - attributes: `esc_attr()`
  - URLs: `esc_url()`
  - limited markup: `wp_kses_post()` or explicit `wp_kses()`
- sanitize any input or admin-side data before storing or using it
- add capability checks and nonces for any new write action or custom form

## Rules for ACF and fallback data

Do not rely on PHP fallback content alone.

When you add or change editable content:

- update the fallback in the theme
- update the matching ACF field definitions if needed
- add or version the seed migration in `inc/default-content.php`
- keep the seed conservative and idempotent
- do not overwrite real user content

If the frontend looks correct only because of fallback values while ACF fields
are empty in admin, the task is not finished.

## Rules for images and assets

Asset parity matters. Matching layout is not enough if the live site serves the
wrong image, crop, logo variant, or SVG.

Always verify:

- the actual image URL served by WordPress
- the visual appearance in the live WordPress page
- the correct variant for dark, transparent, or hover states
- a reasonable `alt` value or fallback

Do not replace a correct asset with a similar-looking one just because the file
name is convenient.

## Rules for diacritics and Romanian copy

When fixing Romanian text:

- inspect both the template fallback and the saved WordPress data
- correct the real content source, not only runtime output
- treat helper-based normalization only as a compatibility measure
- verify the final served HTML contains the correct diacritics

## Homepage rule

Before debugging homepage content, confirm that WordPress is configured to use
a static front page and that the tested page is the actual `page_on_front`.
Without that, homepage conclusions may be wrong.

## Validation minimum

After any meaningful change in this directory, run at least:

- `php -l` for every modified PHP file
- served HTML verification for the affected page
- browser verification for the affected section
- desktop and mobile checks for layout, spacing, buttons, and critical images

If the task affects hover, focus, current-state navigation, sticky elements, or
mobile menus, verify those states in the browser too.

## Reporting rule

When you close a WordPress task, report clearly:

- which file controls the section
- whether the structure is fixed or editable via ACF
- what you verified in code
- what you verified in the browser
- any remaining risk or follow-up

## Avoid these mistakes

- do not edit WordPress core files
- do not move layout control into ACF when the design is fixed
- do not leave helper calls to undefined functions
- do not add fallback logic without syncing seed data
- do not claim parity without checking served HTML and the browser
- do not assume homepage data is correct before checking `page_on_front`