AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Registry and Hub Agent Guide

Project-specific AGENTS.md guidance for the AlexandrAI Tools auto-discovered registry, category grouping, hub rendering, sitemap inputs, and tool metadata contract.

AGENTS.md

Guidance for coding agents working on the AlexandrAI Tools registry and hub role.

Project Overview

The registry and hub layer lets every browser utility live in its own folder without editing a central list. Each tool exports meta from index.ts, the registry discovers all tool modules, sorts them, derives categories, and feeds the hub, related links, dynamic routes, and sitemap inputs.

Project Map

  • src/lib/tools.ts defines ToolMeta, the import.meta.glob registry, tools, categories, toolsByCategory(), and getTool().
  • src/components/Hub.astro renders category groups and search behavior.
  • src/pages/index.astro and src/pages/[lang]/index.astro render the root and localized hubs.
  • src/pages/tools/[slug].astro and src/pages/[lang]/tools/[slug].astro use getTool() to bind slugs to pages.
  • src/tools/*/index.ts files export each tool's meta and pure logic.
  • package.json defines test, typecheck, and build commands.

Setup Commands

bashnpm install
npm test
npm run typecheck
npm run build

Change Rules For Agents

  • Add tools by creating a self-contained src/tools// folder.
  • Keep meta.slug equal to the folder name.
  • Keep meta.description concise enough for search result snippets.
  • Keep meta.category stable; add shell translations when a new category appears.
  • Keep tool logic pure in index.ts and DOM wiring in Body.astro or the page shell.
  • Do not add a manual registry list.
  • Keep tools sorted by title through the registry.
  • Update tests whenever metadata drives routing, sitemap, or related links.

Verification

bashnpm test
npm run typecheck
npm run build

After adding a tool, confirm it appears on the hub and in the generated static route output.

Security Notes

Tool metadata is public. Do not include private hosts, unpublished customer names, credentials, or local paths in titles, descriptions, or keywords.

PR Checklist

  • Tool folder has index.ts, index.test.ts, i18n.ts, and Body.astro when localized.
  • meta.slug matches the folder.
  • Category is intentional and translated in shared shell labels if new.
  • Pure logic tests pass.
  • Static build succeeds.