# Agent instructions (Ordio landingpage) **Last Updated:** 2026-04-10 Use **`@`** to attach only the files you need. For cost- and context-efficient habits, see [`CURSOR_TOKEN_EFFICIENCY.md`](CURSOR_TOKEN_EFFICIENCY.md). ## Quick route (task → one hub → rule hint) | If you are doing… | Open first | Rule / skill (typical) | |-------------------|------------|-------------------------| | Blog / lexikon / ratgeber content | [`CONTENT_SYSTEM_INDEX.md`](../content/blog/CONTENT_SYSTEM_INDEX.md), phase map [`BLOG_AGENT_PHASE_RUNBOOK.md`](../content/blog/BLOG_AGENT_PHASE_RUNBOOK.md) | `ordio-blog-content-router`; `.cursor/rules/blog-*.mdc` by task | | Tools / calculators (PHP + SEO docs) | [`docs/content/tools/DATA_COLLECTION_TOOLS.md`](../content/tools/DATA_COLLECTION_TOOLS.md) | `tools-pages.mdc`, `tools-prioritization.mdc` | | Industry / static marketing pages | [`DATA_COLLECTION_BRANCHEN.md`](../content/pages/industry-pages/DATA_COLLECTION_BRANCHEN.md), [`DATA_COLLECTION_STATIC_SITE.md`](../content/pages/static-pages/DATA_COLLECTION_STATIC_SITE.md) | `industry-pages.mdc`, `static-pages.mdc` | | Homepage `/` (keywords, meta, FAQ accordion + data SSOT) | [`homepage-documentation.md`](../content/pages/homepage/homepage-documentation.md) (`homepage-faq-items.php` vs `landing-transparency-faq-items.php`), [`DATA_COLLECTION_STATIC_SITE.md`](../content/pages/static-pages/DATA_COLLECTION_STATIC_SITE.md) § *Homepage `/`* | `homepage.mdc` | | Product feature pages (10 Funktionen) | [`FEATURE_PAGES_CONTENT_INDEX.md`](../content/pages/product-pages/FEATURE_PAGES_CONTENT_INDEX.md) | `product-pages.mdc`; skill `ordio-feature-page-seo-workflow` | | Improve existing live pages (SEO) | [`PAGE_IMPROVEMENT_DATA_PLAYBOOK.md`](../content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md) | `page-improvement-data-baseline.mdc` | | New public site pages (OG, registry) | [`WEBSITE_PAGE_PUBLICATION_INDEX.md`](../content/WEBSITE_PAGE_PUBLICATION_INDEX.md) | `ordio-new-page-og-carousel` | | FAQs (any surface) | [`FAQ_WEBSITE_STANDARD.md`](../content/FAQ_WEBSITE_STANDARD.md) | `faq-cross-surface.mdc`, `ordio-faq-workflow` | | Pillar pages `/insights/*` (GSC/SISTRIX, FAQ data under `docs/…/pillar-pages/{slug}/`) | [`DATA_COLLECTION_PILLAR.md`](../content/pages/pillar-pages/DATA_COLLECTION_PILLAR.md), [`SEO_DATA_COLLECTION_MATRIX.md`](../content/SEO_DATA_COLLECTION_MATRIX.md), [`PAGE_IMPROVEMENT_DATA_PLAYBOOK.md`](../content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md) | `pillar-pages.mdc`, `page-improvement-data-baseline.mdc` | | Cursor / Agent / MCP usage | [`cursor-playbook.md`](cursor-playbook.md) | `global.mdc`; `mcp-usage.mdc` when using MCP | | Product Updates admin auth (Google OAuth, @ordio.com) | [`PRODUCT_UPDATES_ADMIN_OAUTH.md`](../systems/product-updates/PRODUCT_UPDATES_ADMIN_OAUTH.md) | `produkt-updates-admin-oauth.mdc` | | Local Gemini (blog featured images, OG `--gemini-visuals`, FAQ/SEO scripts) | [`GEMINI_API_KEY_LOCAL.md`](../development/GEMINI_API_KEY_LOCAL.md), model policy [`GEMINI_OPTIMIZATION_GUIDE.md`](../development/GEMINI_OPTIMIZATION_GUIDE.md) | `gemini-local-api-key.mdc`; `og-image-generation.mdc` for OG | | Production Gemini (live site, Firmennamen API, SSH env) | [`GEMINI_API_KEY_PRODUCTION.md`](../development/GEMINI_API_KEY_PRODUCTION.md) | `gemini-local-api-key.mdc` (covers both); `tools-firmennamen-api.mdc` for public API | --- ## Hot Path Reading Order (Token-Efficient) Use this order for most tasks to avoid loading unnecessary context: 1. `docs/ai/agent-workflows.md` (Quick route table only) 2. Open the single relevant hub doc for the task type 3. Read only the matching `.cursor/rules/*.mdc` files for touched files 4. Open `docs/ai/CURSOR_TOKEN_EFFICIENCY.md` if scope starts expanding 5. Open `docs/ai/cursor-playbook.md` only for complex/multi-surface work For MCP-heavy tasks, read `.cursor/rules/mcp-usage.mdc` only when MCP tools are actually needed. --- ## Content & SEO pipelines ### Blog, templates, and tools (content) - Hub: [`docs/content/blog/CONTENT_SYSTEM_INDEX.md`](../content/blog/CONTENT_SYSTEM_INDEX.md) (workflows, Make targets, rules). - **Tools SEO data (SISTRIX, GSC, per-tool research):** [`docs/content/tools/DATA_COLLECTION_TOOLS.md`](../content/tools/DATA_COLLECTION_TOOLS.md). - After refreshing GSC/GA/SISTRIX exports for a tool sprint, run: `php v2/scripts/tools/generate-tool-data-synthesis.php --tool={slug} --output=docs/content/tools/{slug}/DATA_DRIVEN_SYNTHESIS.md` so outlines and iteration use one metrics file. - **Tools FAQ refresh (GSC/SISTRIX-backed):** [`docs/content/tools/_templates/TOOL_FAQ_REFRESH_CHECKLIST.md`](../content/tools/_templates/TOOL_FAQ_REFRESH_CHECKLIST.md). ### Branchen / industry + static (Tier A) - **Portfolio GSC + GA4 refresh (static, tools, product, Branchen + international by country):** `bash v2/scripts/seo/run-marketing-portfolio-gsc-ga4.sh` — see [`SEO_DATA_COLLECTION_MATRIX.md`](../content/SEO_DATA_COLLECTION_MATRIX.md) · `--skip-international` omits `docs/strategy/international-expansion/data/*-by-country.json`. - [`docs/content/pages/industry-pages/DATA_COLLECTION_BRANCHEN.md`](../content/pages/industry-pages/DATA_COLLECTION_BRANCHEN.md) - [`docs/content/pages/static-pages/DATA_COLLECTION_STATIC_SITE.md`](../content/pages/static-pages/DATA_COLLECTION_STATIC_SITE.md) - VIP baseline (when credits allow): `bash v2/scripts/marketing-pages/run-page-research-pipeline.sh ` with optional `--with-gsc-queries`, `--with-sistrix-serp`, `--with-sistrix-domain-kw`, `--with-synthesis`, `--with-competitor-faq-scrape` - Cheaper SERP: `php v2/scripts/product-pages/collect-feature-page-keyword-serp.php --page=` - Synthesis: `generate-industry-data-synthesis.php` or `generate-static-data-synthesis.php` - Utilization gate (new JSON → synthesis + `KEYWORD_DECISION.md`): [`VIP_MARKETING_SEO_DATA_TIERS.md`](../content/pages/marketing-pages/VIP_MARKETING_SEO_DATA_TIERS.md) ### Product feature pages (10 Funktionen, registry `feature-*`) - [`docs/content/pages/product-pages/FEATURE_PAGES_CONTENT_INDEX.md`](../content/pages/product-pages/FEATURE_PAGES_CONTENT_INDEX.md) - VIP SISTRIX: [`VIP_MARKETING_SEO_DATA_TIERS.md`](../content/pages/marketing-pages/VIP_MARKETING_SEO_DATA_TIERS.md) - Orchestrator: `bash v2/scripts/product-pages/run-feature-page-research-pipeline.sh feature-{id}` (`--with-sistrix-serp` → `data/sistrix-keyword-serp.json`; optional `--with-sistrix-domain-kw` → `data/sistrix-domain-kw-serp.json`, cap 5) - Standalone: `collect-feature-page-keyword-serp.php` / `collect-marketing-page-domain-kw-serp.php` - Synthesis: `generate-feature-page-data-synthesis.php` - Skill: `ordio-feature-page-seo-workflow` · Make: `feature-research`, `feature-serp`, `feature-synthesis` ### Tools FAQ schema (site) - Data: `v2/data/tools-faqs/*.json` + `ordio_echo_tools_faq_jsonld_script()` after footer (see [`TOOLS_CONTENT_WORKFLOW.md`](../guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md) § FAQ JSON-LD) - Audits: `php v2/scripts/tools/audit-tools-faq-schema-status.php`, `php v2/scripts/dev-helpers/audit-faq-jsonld-context.php`, `php v2/scripts/dev-helpers/verify-faq-jsonld-parity.php --all-tools` --- ## Improve existing pages (any surface) - [`docs/content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md`](../content/PAGE_IMPROVEMENT_DATA_PLAYBOOK.md) - [`docs/content/PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md`](../content/PAGE_IMPROVEMENT_ITERATION_CHECKLIST.md) (period compare, Firecrawl, handoff template) - `.cursor/rules/page-improvement-data-baseline.mdc` --- ## New website pages (OG, carousels, registry) - [`docs/content/WEBSITE_PAGE_PUBLICATION_INDEX.md`](../content/WEBSITE_PAGE_PUBLICATION_INDEX.md) - Skill: `ordio-new-page-og-carousel` - `make og-audit` · `make og-audit-marketing` (registry vs disk for `get_og_image_for_page` callers) --- ## Blog post JSON - Do **not** edit `v2/data/blog/posts/**/*.json` by hand for body content. - Use `v2/scripts/blog/update-post-content.php` per [`BLOG_CONTENT_EDIT_WORKFLOW.md`](../content/blog/BLOG_CONTENT_EDIT_WORKFLOW.md). --- ## FAQs (all surfaces) - Start: [`docs/content/FAQ_WEBSITE_STANDARD.md`](../content/FAQ_WEBSITE_STANDARD.md) and `.cursor/rules/faq-cross-surface.mdc` - Blog detail: `docs/content/blog/FAQ_*.md` and `blog-faq-optimization.mdc` - **Comparison pages:** `v2/data/compare-faqs/{slug}.json` + `render-compare-faq.php` + `include-compare-faq-jsonld.php` after footer (no FAQPage in head `@graph`); verify `--all-compare`, `audit-compare-faq-ssot.php` - **Marketing JSON FAQs (pricing, industry, pillar, downloads, partner, …):** `misc-faqs/` or `industry-faqs/` + `render-faq-json.php` + `include-marketing-faq-jsonld.php`; verify `--all-misc-faqs`, `audit-marketing-faq-ssot.php` --- ## Cursor, skills, and docs - **Agent Skills:** `.cursor/skills/*/SKILL.md` (e.g. `ordio-blog-content-router`, `ordio-faq-workflow`, `ordio-feature-page-seo-workflow`) - Usage and subagents: [`cursor-playbook.md`](cursor-playbook.md) (section **Content workflows**); official Cursor links: [`CURSOR_OFFICIAL_DOCS_REFERENCE.md`](CURSOR_OFFICIAL_DOCS_REFERENCE.md) - **Documentation maintenance:** [`docs/DOCUMENTATION_HYGIENE_LOG.md`](../DOCUMENTATION_HYGIENE_LOG.md); inventory: `python3 scripts/documentation/inventory-documentation.py` then `python3 scripts/documentation/check-redundancy.py`; tiers: [`scripts/documentation/README.md`](../../scripts/documentation/README.md) - **Global guardrails:** `.cursor/rules/global.mdc` · MCP behaviour: `.cursor/rules/mcp-usage.mdc` (read when using MCP tools) --- ## HubSpot & MCP - MCP setup: [`docs/development/HUBSPOT_MCP_OAUTH_SETUP.md`](../development/HUBSPOT_MCP_OAUTH_SETUP.md) - Bulk CRM / audits: `v2/scripts/hubspot/` and [`MCP_INTEGRATION.md`](../development/MCP_INTEGRATION.md) (HubSpot section), not MCP for bulk jobs - **Ordio Loop affiliate HubSpot cache sync:** [`CRON_SYNC_RUNBOOK.md`](../systems/affiliate/CRON_SYNC_RUNBOOK.md) — hourly = **server cron** (`sync-affiliate-hubspot.php`); GitHub `hubspot-sync-cron.yml` = **2×/day backup only** (not hourly). --- ## Policy links (internal URLs) - Do not link to `/kostenlos-testen` from editorial content. Use `/demo-vereinbaren`. Post-submit redirects to `/kostenlos-testen/danke` stay as implemented. See `.cursor/rules/no-internal-kostenlos-testen-links.mdc`. --- ## Error pages & shared components - **404 / Insights:** [`ERROR_PAGES.md`](../systems/error-pages/ERROR_PAGES.md) - **Three-card testimonials:** [`THREE_CARD_TESTIMONIALS.md`](../systems/shared-components/THREE_CARD_TESTIMONIALS.md) — `v2/data/three-card-testimonials.php` + partial; no duplicated quote HTML - **Schichtplan Nano WebGL:** [`SCHICHTPLAN_NANO_LIQUID_METAL_WEBGL.md`](../systems/shared-components/SCHICHTPLAN_NANO_LIQUID_METAL_WEBGL.md) — `npm run minify` after JS/CSS; optional `node v2/scripts/dev-helpers/smoke-schichtplan-nano-webgl.mjs` - **Komplettlösung 4-tab carousel:** [`KOMPLETTLOESUNG_FEATURES_CAROUSEL_4.md`](../systems/shared-components/KOMPLETTLOESUNG_FEATURES_CAROUSEL_4.md) - **Customer spotlight carousel:** [`VIDEO_CAROUSEL_IMPLEMENTATION_SUMMARY.md`](../systems/video-carousel/VIDEO_CAROUSEL_IMPLEMENTATION_SUMMARY.md) — one include per page; audit: `php v2/scripts/dev-helpers/audit-customer-spotlight-css.php`