AGENTS.md

Guidance for coding agents working on the AlexandrAI Tools ToolChrome UI role.

Project Overview

ToolChrome is the shared page wrapper for individual utilities. It owns breadcrumbs, title and lede, the tool content slot, in-content ad placement, about prose, related tools from the same category, and cross-category popular links.

Project Map

• src/components/ToolChrome.astro defines the wrapper and related/popular link sections.
• src/components/AdSlot.astro reserves ad placement without per-tool layout churn.
• src/lib/tools.ts provides tool metadata and category lookup.
• src/lib/i18n.ts provides localePath() and shared labels.
• src/pages/tools/[slug].astro passes English strings and the Body component into ToolChrome.
• src/pages/[lang]/tools/[slug].astro handles localized tool pages.
• src/tools/*/Body.astro files provide the actual utility interface.

Setup Commands

bashnpm test
npm run typecheck
npm run build

Change Rules For Agents

• Keep ToolChrome generic; do not add tool-specific UI branches.
• Keep the primary tool UI in the default slot.
• Keep educational or FAQ content in the about slot.
• Keep related tools scoped by shared category.
• Keep popular tools curated and filtered so the current tool is not self-linked.
• Use localePath() for internal links.
• Do not add per-tool CSS to ToolChrome.
• Preserve reserved ad space to avoid layout shift.

Verification

bashnpm run typecheck
npm run build

Open at least one developer tool, one converter, and one image or PDF tool after wrapper changes to catch slot and related-link regressions.

Security Notes

ToolChrome should not collect user input, upload files, or log tool contents. Tool data should stay inside the browser-specific Body component.

PR Checklist

• Breadcrumbs and headings render.
• Tool slot renders before about content.
• Related and popular links exclude the current slug.
• Localized labels fall back cleanly.
• Build succeeds.