AGENTS.md

Guidance for coding agents working on alexandrai-tools. This project is a static Astro site of fast, no-signup, single-purpose browser tools.

Project Overview

The site is mostly client-side and should not upload user input to a backend. Tools are self-contained, auto-discovered, and surfaced through SEO metadata, sitemap output, and the tools hub.

Each tool should keep pure logic separate from DOM wiring:

• src/tools//index.ts: meta plus pure logic.
• src/tools//index.test.ts: Vitest coverage for the pure logic.
• src/pages/tools/.astro: thin page using shared layout/chrome and inline browser wiring.

Setup Commands

bashnpm install
npm run dev
npm test
npm run typecheck
npm run build
npm run preview

Deployment is production-only and uses ./deploy.sh. Do not run deploy commands unless the user explicitly asks for production release work.

Add A Tool

1. Copy an existing simple tool such as json-formatter as a structural reference.
2. Create src/tools//index.ts with meta and pure functions only.
3. Add src/tools//index.test.ts before or alongside implementation.
4. Add src/pages/tools/.astro as a thin UI wrapper.
5. Keep tool-specific styling minimal; reuse src/styles/global.css and shared helpers.

The meta.description should stay concise enough for search snippets, and meta.keywords should be real search terms rather than filler.

SEO And Static Output

• Use existing helpers under src/lib/seo.ts.
• Preserve canonical URLs, Open Graph metadata, SoftwareApplication JSON-LD, sitemap generation, and robots output.
• Do not hand-maintain the hub or sitemap when the existing import.meta.glob discovery path already covers the tool.

Code Style

• Keep browser tools deterministic and side-effect-light.
• Do not add a backend route for a task that can run locally in the browser.
• Keep parsing, formatting, validation, and conversion logic testable without DOM APIs.
• Use src/lib/dom.ts helpers for page wiring when possible.
• Avoid per-tool dependency additions unless the tool genuinely needs a library already approved for client-side use.

Testing

Use:

bashnpm test
npm run typecheck
npm run build

For a changed tool, run or add its index.test.ts. If metadata, routing, or sitemap logic changes, build the whole site.

Privacy And Safety

• Assume pasted content can be sensitive.
• Do not send tool input to remote services.
• Avoid logging user input.
• Do not publish ad slot changes, analytics changes, or production deploy steps unless requested.

Commit And PR Rules

• One tool per small change is preferred.
• Keep logic, tests, and UI page together for new tools.
• Summaries should name the exact tool slug and verification commands run.