developer-portal AGENTS.md

AGENTS.md — AI agent guide for the Cardano Developer Portal

Use yarn, not npm, for all dependency and script management. Requires Node 22 (see .nvmrc). The self-contained apps under examples/ are the exception: each manages its own dependencies with its own package manager.

This file gives AI coding agents (and their operators) the context to contribute correctly to the Cardano Developer Portal (developers.cardano.org), a Docusaurus site. Read it before making changes. Human contributors should start with README.md and CONTRIBUTING.md.

---

Scope and intent

• Prefer small, reviewable, single-purpose PRs. Keep diffs minimal; do not bundle cosmetic churn with a fix.
• For non-trivial changes, open an issue or discussion first.
• This repo is documentation, a developer curriculum, and a curated list of builder tools. It is not a place for marketing copy.
• All PRs target the staging branch. Maintainers merge staging into main for production periodically.

---

Project philosophy

• Community-owned: the portal is maintained by the Cardano community, not a single entity.
• Incremental: prefer small, continuous changes over large rewrites.
• Discussion first: align on non-trivial changes before implementing them.

---

Essential resources

• README.md — overview and local setup.
• CONTRIBUTING.md — contribution workflow (fixing content, adding builder tools, writing docs).
• Style guide (docs/contribute/portal-style-guide.md) — the editorial voice. Mandatory for content and UI copy.
• src/data/builder-tools/tags.js — the builder-tools taxonomy (categories, languages, interfaces). The source of truth for valid tool metadata.

---

Repository map

• docs/ — content: developers/ (the curriculum), operators/, community/, contribute/. Doc images are co-located in img/ folders next to the pages that use them.
• blog/ — the developer blog (tags.yml defines the allowed tags).
• src/
  • pages/ — standalone React pages (for example talent/, tools/).
  • data/ — site data: builder-tools/ (tools.js entries + tags.js taxonomy + validation), templates/, contracts/, navbar.js, footer.js, redirects.js.
  • components/, theme/, css/, utils/, svg/ — UI.
• static/ — site-owned assets, grouped by consumer under static/img/ (home/, blog/, tools/, tool-icons/, brand/, og/, …).
• examples/ — runnable, self-contained example projects (templates/ holds the dApp starters). Not served by Docusaurus; see examples/README.md.
• plugins/ — custom Docusaurus plugins (tools-routes, templates-routes).
• scripts/ — build helpers wired into yarn start/yarn build: generate-stats.js (writes static/stats.json), generate-og.js (renders the social-preview cards for every doc, blog post, and site page into the gitignored static/img/og/docs|blog|pages/; the background frames in static/img/og/_template/ are tracked), fix-llms-paths.js (path fixes for the generated llms.txt).
• Config: docusaurus.config.js (site), sidebars.js (navigation — hand-authored, see below), netlify.toml (redirects + security headers), searchconfig.json (Algolia crawler), .nvmrc (Node version — the source of truth).