zaezd: Instructions file for Codex

Zaezd - agent brief

Trip engine that starts from a reason to travel. A person does not know where to go, they know why. The first vertical is IT conferences: the event catalogue (confcal MCP) says where and when, Tutu MCP supplies transport and lodging, and a deterministic composer turns both into at most three explainable packages on one screen.

The product specification lives in specs/ and is authoritative. Read specs/README.md first; it indexes all ten documents and names the three things that are never cut: the return leg, the deterministic date algorithm, and honest checkout link labels.

State of the repository

All five layers are written, specified and deployed: the pure core, the confcal and Tutu clients, the three optional enrichments, the orchestrator, the trip board and the three MCP tools with the ui:// widget. It ships as a container and runs behind whatever reverse proxy a deployment happens to have; npm run verify covers all of it offline against fixtures/.

ideas/ holds the reconnaissance the specs were built from. It ships with the public repository as history, not as product code, and nothing under src/ may import from it. research/ holds raw probes and review transcripts and stays out of git.

Commands

npm install          # once
npm start            # the server, ZAEZD_MODE=live or replay
npm run bdd          # executable Gherkin specifications (features/)
npm test             # unit tests (tests/)
npm run typecheck    # tsc over the Node tree and the browser tree
npm run lint         # eslint
npm run rules:sync   # regenerate .cursor/rules from .claude/rules
npm run docs:check   # every command the documentation names really exists
npm run build        # compile to dist/ and copy static assets
npm run verify       # all of the above except build, the gate before calling anything done

Runtime dependencies are added as the layer that needs them is built: zod with src/sources/normalize.ts, @modelcontextprotocol/sdk with the clients, @modelcontextprotocol/ext-apps with the ui:// resource. Leaflet and the Kite token extract are vendored under src/web/public/vendor/ with their licences, not installed. Unused dependencies are a scored defect here.