licita-app: Instructions file for Codex

Relicita Project Guidelines

Product context

Relicita is an agent-native public procurement intelligence product for professional teams. It indexes TED and, when enabled, PLACSP data to expose evidence-backed intelligence about tenders, buyers, suppliers, opportunities, and renewal signals through REST and MCP. The package name stays licita-agent and the MCP registry id stays licita.

Primary users:

• Procurement and business-development professionals evaluating public-sector opportunities.
• AI-agent and integration developers consuming the REST/MCP surfaces.
• The operator monitoring acquisition, usage, revenue, and data quality.

The primary product outcome is helping a professional decide where to focus procurement activity next. Human-facing UX must lead with that decision value; protocol, payment, and implementation details are secondary.

Engineering conventions

• Runtime: Node.js 22+, TypeScript, ESM, Fastify, PostgreSQL, raw SQL, and Zod validation. (Floor set by engines; jsdom/undici 8 in the test stack requires Node ≥ 22.19.)
• Public web surfaces live in src/web/; API routes live in src/api/routes/; payments live in src/pay/; migrations live in migrations/; tests live in test/.
• Preserve REST envelopes, MCP contracts, provenance, and explicit nulls. Never fabricate data.
• Validate untrusted input at the route boundary and enforce authorization server-side.
• Migrations are additive and replay-safe. Never modify production secrets or unrelated tooling files.
• Keep the public discovery surfaces stable: /llms.txt, /openapi.json, /v1/pricing, /docs, /mcp, the MCP server card, use-case/data routes, and /robots.txt.

Commands

npm test
npm run test:integration
npm run test:api-smoke
npm run typecheck
npm run build

Local services:

docker compose up --build -d
docker compose logs -f app

Definition of done

• The user, primary job, decision, scope, and acceptance scenarios are explicit.
• Tests are written before implementation for new behavior (strict TDD).
• npm test, relevant integration/smoke tests, typecheck, and build pass.
• Error, empty, loading, success, and disabled states are covered.
• Security, privacy, authorization, and data-retention implications are reviewed.
• Public API, MCP, discovery, and provenance contracts have regression coverage.
• Documentation, deployment, and rollback notes are updated when applicable.
• No UI is considered complete without browser evidence or an explicit Needs verification decision.