Checked AGENTS.md
This commit is contained in:
Oliver
@@ -0,0 +1,204 @@
|
||||
# AGENTS.md — NGO Landing Page
|
||||
|
||||
Read this file fully before taking any action.
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
Single-page static landing page for an NGO ERP product.
|
||||
|
||||
| Item | Detail |
|
||||
|---|---|
|
||||
| Pages | `index.html` — the only HTML file |
|
||||
| Styling | Tailwind CSS v3 · source `src/input.css` → compiled `assets/site.css` |
|
||||
| Data | `blog.json` — flat array of blog posts, loaded at runtime by inline JS |
|
||||
| i18n | Inline `translations` object inside `index.html` (EN / ES / DE) |
|
||||
| Blog renderer | Inline `<script>` in `index.html` — no external JS files |
|
||||
| Dev server | `./start` (runs `live-server`) |
|
||||
| Git remote | `git@git.odoo4projects.com:Oliver/NGO.git` |
|
||||
|
||||
### File map
|
||||
|
||||
```
|
||||
index.html ← only HTML file — layout + all inline JS + i18n
|
||||
src/input.css ← Tailwind source (edit here, then rebuild)
|
||||
assets/site.css ← compiled output — DO NOT edit by hand
|
||||
blog.json ← blog post data array
|
||||
tailwind.config.js ← design tokens (colors, fonts, shadows)
|
||||
```
|
||||
|
||||
### Design tokens (from `tailwind.config.js`)
|
||||
|
||||
| Token | Hex | Usage |
|
||||
|---|---|---|
|
||||
| `brand-ink` | `#201824` | default text / dark backgrounds |
|
||||
| `brand-primary` | `#603F57` | section labels, bullet accents |
|
||||
| `brand-accent` | `#F762B4` | CTA buttons, links |
|
||||
| `brand-sunrise` | `#F8B84A` | hero highlights, hover states |
|
||||
| `brand-emerald` | `#39B982` | positive indicators |
|
||||
| `brand-snow` | `#F5F2F7` | page background |
|
||||
| `brand-smoke` | `#E5DCE8` | borders, subtle dividers |
|
||||
|
||||
NEVER use raw hex values in HTML — always use the token class names above.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Goal
|
||||
|
||||
- Deliver an **SEO-optimised, fast-loading, responsive** single-page site.
|
||||
- Keep all edits **minimal and targeted** — preserve design, structure, and functionality.
|
||||
- NEVER introduce new frameworks, libraries, or external dependencies.
|
||||
|
||||
### Quality bar for every change
|
||||
|
||||
| Concern | Rule |
|
||||
|---|---|
|
||||
| SEO | Keep all existing meta tags, `ld+json`, `alt` attributes, and heading hierarchy |
|
||||
| Performance | No comments in production HTML, no unused CSS classes, no render-blocking additions |
|
||||
| Responsive | Every element must work on mobile (375 px), tablet (768 px), and desktop (1280 px+) |
|
||||
| Consistency | Use only brand token classes; match existing spacing and rounding patterns |
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Build CSS after editing src/input.css or tailwind.config.js
|
||||
npx tailwindcss -i src/input.css -o assets/site.css --minify
|
||||
|
||||
# Validate blog.json
|
||||
jq empty blog.json && echo "JSON valid"
|
||||
|
||||
# Start dev server
|
||||
./start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Rules
|
||||
|
||||
- ALWAYS work on **`main`** branch.
|
||||
- Pull before every session:
|
||||
```bash
|
||||
git pull origin main
|
||||
```
|
||||
- Commit messages must follow the pattern:
|
||||
- `blog: add post – <title>`
|
||||
- `fix: <short description>`
|
||||
- `content: <short description>`
|
||||
- Push immediately after committing — never leave unpushed commits.
|
||||
- Branch creation is permitted ONLY under the **Branch Handling Exception** (see bottom).
|
||||
|
||||
---
|
||||
|
||||
## File Safety Rules
|
||||
|
||||
- ONLY modify files required for the task.
|
||||
- NEVER delete or restructure content unrelated to the task.
|
||||
- NEVER remove existing blog posts from `blog.json`.
|
||||
- NEVER edit `assets/site.css` directly — always rebuild from `src/input.css`.
|
||||
|
||||
---
|
||||
|
||||
## Blog Post Schema
|
||||
|
||||
`blog.json` is a root-level JSON array. Every post object contains **exactly these five fields**:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"area": "Automation",
|
||||
"date": "2026-03-25",
|
||||
"title": "Article title as plain text",
|
||||
"teaser": "<p>One or two sentences visible before 'Read more'.</p>",
|
||||
"content": "<h3>Section</h3><p>Full article as HTML.</p>"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
| Field | Type | Constraint |
|
||||
|---|---|---|
|
||||
| `area` | plain string | Category label rendered above the title |
|
||||
| `date` | ISO 8601 (`YYYY-MM-DD`) | Used by `Intl.DateTimeFormat` |
|
||||
| `title` | plain string | Rendered as `<h3>` — no HTML |
|
||||
| `teaser` | HTML string | Always visible — wrap in `<p>` tags |
|
||||
| `content` | HTML string | Revealed by "Read more" toggle — use `<h3>`, `<p>`, `<ul>`, `<li>` |
|
||||
|
||||
NEVER add extra fields (`slug`, `author`, `tags`, `excerpt`, `hero_image`, etc.) — they are ignored by the renderer and pollute the file.
|
||||
|
||||
### Adding a new blog post (jq method)
|
||||
|
||||
```bash
|
||||
# 1. Pull latest
|
||||
git pull origin main
|
||||
|
||||
# 2. Backup (once per session)
|
||||
mkdir -p /backup && cp blog.json /backup/blog.json.$(date +%Y%m%d%H%M%S)
|
||||
|
||||
# 3. Prepend new post — $NEW_JSON must be a valid single post object
|
||||
jq --argjson new "$NEW_JSON" '. = [$new] + .' blog.json > tmp.json && mv tmp.json blog.json
|
||||
|
||||
# 4. Validate
|
||||
jq empty blog.json && echo "JSON valid"
|
||||
|
||||
# 5. Commit and push
|
||||
git add blog.json
|
||||
git commit -m "blog: add post – <title>"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
NEVER use Python, Node scripts, or manual text editing to modify `blog.json`.
|
||||
|
||||
---
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
Follow this order for every task:
|
||||
|
||||
1. `git pull origin main`
|
||||
2. Identify the exact files to change — nothing else.
|
||||
3. Apply minimal edits.
|
||||
4. If `src/input.css` or `tailwind.config.js` were changed → rebuild CSS.
|
||||
5. Validate: `jq empty blog.json` for JSON; visual check for HTML.
|
||||
6. Commit with a descriptive message.
|
||||
7. `git push origin main`
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Changes are minimal, validated, and committed.
|
||||
- `blog.json` is a valid array with exactly five fields per post.
|
||||
- `assets/site.css` reflects any CSS changes (rebuilt, not hand-edited).
|
||||
- HTML passes a visual check — layout and design unchanged except for the intended edit.
|
||||
- All commits pushed to `main`.
|
||||
|
||||
---
|
||||
|
||||
## Failure Conditions
|
||||
|
||||
These actions constitute a failure:
|
||||
|
||||
- Refusing to act due to perceived access restrictions.
|
||||
- Failing to push after committing.
|
||||
- Adding undeclared fields to `blog.json`.
|
||||
- Removing or overwriting existing blog posts.
|
||||
- Editing `assets/site.css` by hand.
|
||||
- Modifying files outside the scope of the task.
|
||||
- Leaving a branch open without merging.
|
||||
|
||||
---
|
||||
|
||||
## Branch Handling Exception
|
||||
|
||||
Branch creation is permitted **only** when:
|
||||
|
||||
- The task explicitly requires a feature branch, **or**
|
||||
- A direct push to `main` is blocked by branch protection.
|
||||
|
||||
If a branch is created it **must**:
|
||||
|
||||
- Follow the naming convention `<type>/<short-description>` (e.g. `fix/blog-json-schema`).
|
||||
- Be merged into `main` via PR immediately after the task is complete.
|
||||
- Be deleted after merge — never abandoned.
|
||||
Reference in New Issue
Block a user