Checked AGENTS.md

2026-03-27 16:23:57 -03:00
1 parent 05719aae4e
commit 4d2f57c20c
@@ -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.
@@ -1,78 +1,4 @@
 [
-  {
-    "title": "ODOO has 1,000,000 NGOs online!",
-    "slug": "odoo-1m-ngos-online",
-    "publish_date": "2026-03-27",
-    "author": "Odoo4Projects",
-    "meta_description": "Odoo reaches 1,000,000 NGOs online—discover cost savings, scalability, admin efficiency, and next steps for nonprofits to modernize with Odoo.",
-    "seo_keywords": [
-      "Odoo NGO",
-      "nonprofit ERP",
-      "NGO software",
-      "donor management",
-      "NGO scalability"
-    ],
-    "hero_image": "odoo-1m-ngos-hero.jpg",
-    "tags": [
-      "NGO",
-      "Digital Transformation",
-      "Odoo"
-    ],
-    "ctas": {
-      "book_meeting": "{{book_meeting_url}}",
-      "free_trial": "{{free_trial_url}}",
-      "case_studies": "{{case_studies_url}}"
-    },
-    "content_html": "<h1>ODOO has 1,000,000 NGOs online!</h1>\n<p>Today marks a major milestone: Odoo is now powering 1,000,000 NGOs online. For NGO decision-makers and tech leads, this is more than a number — it’s proof that modern, integrated software can scale mission impact, reduce operational overhead, and accelerate service delivery across organisations of every size.</p>\n\n<h2>Why this matters for nonprofits</h2>\n<p>Reaching one million NGO deployments signals maturity. It means a broad ecosystem of community contributors, ready-made modules for common NGO needs, and a tested platform that can handle volunteer management, fundraising, finance, and program delivery simultaneously.</p>\n\n<h2>Practical benefits you can expect</h2>\n<ul>\n  <li><strong>Cost savings:</strong> Consolidate multiple point solutions into a single platform to reduce subscription, maintenance, and training costs.</li>\n  <li><strong>Scalability:</strong> Move from a single office to national programs without swapping tools; Odoo scales with user counts and transaction volumes.</li>\n  <li><strong>Admin efficiency:</strong> Automate repetitive tasks — reporting, reconciliations, and donor acknowledgements — freeing staff to focus on programs.</li>\n  <li><strong>Integrations:</strong> Connect to payment gateways, CRM systems, GIS tools, and third-party analytics with ready APIs and community-built connectors.</li>\n</ul>\n\n<h2>Real-world, anonymized use case</h2>\n<p>Consider a composite example based on several midsize NGOs that transitioned to Odoo last year. Before migrating, finance and program teams spent 20–30% of their time on manual reconciliations, duplicated data entry across spreadsheets, and fragmented volunteer tracking. After consolidating onto Odoo, these organisations reported:</p>\n<ul>\n  <li>A 30% reduction in administrative time spent on routine finance and reporting.</li>\n  <li>Lower annual software spend by consolidating 4–6 subscription services into one platform.</li>\n  <li>Faster donor acknowledgment workflows that improved donor retention and reporting transparency.</li>\n</ul>\n<p>These gains translated into more time for frontline work, better financial visibility for leadership, and budget freed to expand program delivery.</p>\n\n<h2>How to evaluate Odoo for your NGO</h2>\n<p>Start with a clear list of priorities: finance, grants management, volunteers, CRM, and field data capture. Pilot a minimal set of modules for 3–6 months, measure baseline KPIs (admin hours, cost per transaction, donor response time), and iterate.</p>\n\n<h2>Next steps — a practical roadmap</h2>\n<ol>\n  <li>Book a scoping session to map your current systems and identify consolidation opportunities.</li>\n  <li>Run a short pilot (3 months) on finance and donor management to measure quick wins.</li>\n  <li>Expand modules based on pilot outcomes, integrating volunteer and project management next.</li>\n  <li>Scale nationally or regionally with role-based access, multi-company setups, and automated reporting.</li>\n</ol>\n\n<h2>Ready to act?</h2>\n<p>Celebrate this milestone with action. If your NGO is looking to reduce costs, improve admin efficiency, and scale programs with confidence, now is a great time to evaluate Odoo.</p>\n\n<p>Choose a next step:</p>\n<p><a href=\"{{book_meeting_url}}\" style=\"display:inline-block;padding:10px 16px;margin-right:8px;background:#007bff;color:#fff;border-radius:4px;text-decoration:none;\">Book a meeting</a> <a href=\"{{free_trial_url}}\" style=\"display:inline-block;padding:10px 16px;margin-right:8px;background:#28a745;color:#fff;border-radius:4px;text-decoration:none;\">Start a free trial</a> <a href=\"{{case_studies_url}}\" style=\"display:inline-block;padding:10px 16px;background:#6c757d;color:#fff;border-radius:4px;text-decoration:none;\">Read the full Odoo NGO case studies</a></p>\n\n<p><em>Author: Odoo4Projects • Published: 2026-03-27</em></p>"
-  },
-  {
-    "title": "Localisation in practice: shifting power and funding to local partners effectively",
-    "slug": "localisation-in-practice-shifting-power-and-funding-to-local-partners-effectively",
-    "publish_date": "2026-03-27",
-    "author": "ODOO4projects",
-    "language": "English",
-    "meta_title": "Localisation for NGOs: Shifting Power & Funding",
-    "meta_description": "Practical, NGO-focused guidance on shifting power and funding to local partners. Six actionable steps, short case examples, and how Odoo for NGOs supports localisation.",
-    "primary_keyword": "localisation for NGOs",
-    "tags": [
-      "localisation",
-      "partnerships",
-      "funding",
-      "NGO best practices",
-      "Odoo for NGOs"
-    ],
-    "hero_image": {
-      "src": "/images/blog/localisation-partners.jpg",
-      "alt": "Local NGO partners collaborating in a community planning session"
-    },
-    "body": "<h1>Localisation in practice: shifting power and funding to local partners effectively</h1>\n\n<p><strong>Introduction</strong></p>\n<p>Localisation for NGOs is not an abstract goal — it is a set of operational choices that redistribute decision-making, resources, and responsibility to local actors. Done well, it increases programme relevance, sustainability, and accountability. This practical guide outlines clear steps NGOs can use to shift power and funding to local partners while managing risk and maintaining programmatic quality.</p>\n\n<h2>Why deliberate localisation matters</h2>\n<p>Local organisations bring contextual knowledge, trust and cost-effectiveness. However, asymmetric power, restricted funding instruments, and unrealistic compliance expectations often block meaningful transfer of power. Addressing these barriers requires policy shifts inside international NGOs and concrete changes in partnership and finance practices.</p>\n\n<h2>Six practical steps to shift power and funding</h2>\n\n<h3>1. Reframe partnership agreements</h3>\n<p>Start contracts from a partnership perspective rather than a sub-award model. Co-design objectives, roles and performance indicators so local partners shape outcomes, not just deliver tasks. Include governance clauses that give partners representation in strategic decisions for the programme or consortium.</p>\n\n<h3>2. Offer flexible, multi-year funding</h3>\n<p>Short, restricted grants undermine local organisational development. Whenever possible, provide core or flexible funding and multi-year cycles to allow local partners to plan, build systems, and invest in staff and infrastructure. If donors require restricted budgets, negotiate a percentage for flexible use and capacity investment.</p>\n\n<h3>3. Simplify compliance and reporting</h3>\n<p>Align reporting requirements with partner capacity. Use risk-based assurance rather than blanket procedures: increase oversight where risks are high and reduce administrative burden where risks are low. Invest in shared financial management tools and templates to standardise processes and reduce duplicative effort.</p>\n\n<h3>4. Build two-way capacity strengthening</h3>\n<p>Move beyond one-directional training. Co-develop capacity plans driven by partner-identified needs. Provide technical assistance that embeds local expertise and hands-on coaching. Recognise that international NGOs also have learning needs (e.g., localisation-sensitive donor engagement) and document mutual learning.</p>\n\n<h3>5. Reform internal incentives and KPIs</h3>\n<p>Change the metrics that drive staff behaviour. Reward teams for successful partner leadership, locally led innovations, and delegated funding. Adjust risk appetite frameworks to distinguish between tolerable and intolerable risks and avoid defaulting to centralized control because it is administratively convenient.</p>\n\n<h3>6. Use technology to increase transparency and autonomy</h3>\n<p>Digital systems can simplify grant flows, automate compliance where appropriate, and provide partners with real-time visibility of budgets and deliverables. Implement shared dashboards and accounting workflows that allow partners to manage funds directly while enabling donors and lead agencies to monitor progress without micromanaging.</p>\n\n<h2>Practical examples and short case-style bullets</h2>\n<ul>\n  <li><strong>Case: Multi-year core support</strong> — An international federation converted a portion of programme funding into three-year core grants for local partners, enabling recruitment of technical staff and reducing turnover. Result: improved programme continuity and lower operational costs.</li>\n  <li><strong>Case: Risk-tiered compliance</strong> — A country office implemented a risk matrix that reduced audit frequency for partners with strong financial controls and increased mentoring support for smaller groups. Result: administrative time cut by 30% and higher partner satisfaction.</li>\n  <li><strong>Case: Co-designed M&E</strong> — A consortium co-created indicators with community-based organisations (CBOs), integrating traditional accountability practices. Result: more relevant indicators and greater community ownership of monitoring data.</li>\n  <li><strong>Case: Shared digital ledger</strong> — Using a common, cloud-based accounting workflow, a lead NGO enabled direct partner access to budget and spend reports. Result: faster payments, fewer reconciliation errors, and clearer audit trails.</li>\n</ul>\n\n<h2>Implementation checklist (quick wins)</h2>\n<ul>\n  <li>Review existing contracts and identify clauses that limit partner decision-making.</li>\n  <li>Allocate a pilot percentage of flexible funding to test local grants for 12–36 months.</li>\n  <li>Map partner capacities and co-create a capacity-strengthening plan.</li>\n  <li>Introduce a risk-tier system to tailor compliance requirements.</li>\n  <li>Set internal KPIs that measure partner leadershipLine truncated
-    "excerpt": "Practical steps for NGOs to shift power and funding to local partners: six actionable recommendations, quick implementation checklist, short case examples, and how Odoo for NGOs can support partner-led programming."
-  },
-  {
-    "insert_at_top": true,
-    "title": "Reduce NGO Admin by 20–40%: 7 Workflows You Can Automate This Month",
-    "slug": "reduce-ngo-admin-by-20-40-7-workflows-automate-this-month",
-    "date": "2026-03-25",
-    "author": "Odoo4Projects NGO Team",
-    "tags": [
-      "NGO",
-      "automation",
-      "workflows",
-      "productivity"
-    ],
-    "hero_image": "/images/blog/reduce-ngo-admin.jpg",
-    "excerpt": "Cut admin time 20–40% with seven practical automations using Odoo and n8n—fewer forms, faster reports, more mission time.",
-    "content": "\"Maria runs a small education NGO and spent nights buried in paperwork, donor emails, and overlapping spreadsheets. She often cried quietly at the kitchen table, knowing every hour spent on admin was an hour taken from the children she serves.\"\n\nMaria’s problem is common: scattered information, repeated manual steps, and slow acknowledgements that frustrate donors and staff alike. An ERP system gives you one single place for contacts, donations, invoices, and project tasks so people stop copying the same data into five different tools. With templates and central records the chance for mistakes falls, approvals move faster, and regular reports are generated automatically so leaders can see the big picture without hunting through files.\n\nPut simply, Odoo becomes the central hub and n8n runs the glue that connects the tools you already use. Use Odoo for Contacts, Donations (or Sales/Invoices), Projects, and Documents; then create n8n workflows to trigger automatic donor receipts, update contact records when forms are submitted, schedule follow-up tasks, and push summary reports to Slack or email. These automations remove repeated typing, erase copy/paste errors, and make sure no donor message goes unanswered—freeing up coordinators to focus on program work. Expect clear time savings: common NGO implementations show 20–40% fewer administrative hours within weeks by removing routine manual steps and automating reminders and acknowledgements.\n\n\"After we set up Odoo and a few n8n flows, Maria’s team stopped doing nightly admin sprints and began checking a single dashboard each morning. She now spends time coaching teachers, visiting communities, and planning programs instead of reconciling spreadsheets, and her staff feel calmer and more productive.\"\n\nBook a meeting: https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ3DDbaiHFlhNhWySszAQoPXE_H73QLqYT3w7H9IYWC76RA_TgNIhLESjb4N7ep_D2D_OyW9q4-c",
-    "meta_description": "Cut NGO admin 20–40% fast with 7 Odoo + n8n automations—faster donor receipts, fewer spreadsheets, more mission time.",
-    "seo_keywords": [
-      "NGO automation",
-      "reduce admin NGO",
-      "Odoo for NGOs",
-      "n8n workflows",
-      "NGO productivity"
-    ],
-    "seo_summary": "Expected impact: Reduce routine administrative hours by 20–40% within weeks through practical automations.\nAddresses common NGO pain points: duplicated data, slow acknowledgements, and time lost to manual reporting."
-  },
  {
    "area": "Donor Communication",
    "title": "How Maya Turned Donor Chaos into Clear Connections",