Agent Instructions — FedSpeak

Context

FedSpeak is a Federal Acronym Decoder maintained by MetaPhase. The core data lives in src/shared/data/acronyms.json. The API runs as Netlify Functions, the website is Vite + React.

When Adding Acronyms

1. Read the existing file first — src/shared/data/acronyms.json has 600+ entries. Do not create duplicates.
2. Follow the exact schema:

   "ACRONYM": {
     "full": "Full Name",
     "description": "Brief 1-2 sentence description.",
     "agency": "Parent agency acronym or 'General'",
     "category": "department|agency|office|bureau|program|process|regulation|system|general"
   }
   

3. Optional fields: url (official website), aliases (alternate spellings/abbreviations)
4. Keep keys sorted alphabetically in the JSON file.
5. Descriptions should be concise — what the thing IS or DOES, not its full history.
6. Agency field — use the parent department acronym (e.g., "DOD" for DISA, "DHS" for TSA, "General" for cross-cutting terms).
7. Category choices:
   • department — Cabinet-level departments (DOD, HHS, etc.)
   • agency — Independent agencies or major sub-agencies
   • office — Named offices within agencies
   • bureau — Named bureaus within departments
   • program — Government programs (SNAP, TRICARE, etc.)
   • process — Acquisition processes, reviews, milestones
   • regulation — Laws, acts, regulations, standards
   • system — IT systems, databases, platforms
   • general — Everything else (titles, terms, concepts)

When Modifying Code

• Run npm run lint && npm run typecheck && npm run test:run before committing.
• The shared logic in src/shared/ is used by the API functions, the website, and the npm package.
• Changes to types.ts affect all three consumers.
• The truncate.ts module has function overloads for both DecodeResponse and EncodeResponse.

When Working on the API

• Functions are in netlify/functions/ using Netlify Functions v2 format.
• Both decode and encode support GET (query params) and POST (JSON body).
• Always include CORS headers in responses.
• Responses are progressively truncated to stay under 2000 chars (handled by truncate).

When Working on the Website

• React 18 + React Router 7 + Tailwind 3.4
• Components in src/components/, pages in src/pages/
• The TryItDemo component uses the decoder directly (client-side), not the API.
• Swagger UI is loaded from CDN in ApiReference.tsx.

Git Workflow

• Work in dev branch (default).
• PR to main for production deploys to Netlify.
• Commit messages: imperative mood with prefix (feat:, fix:, docs:, chore:).