Imported from slackspac3/ce-hub (AGENTS.md). Install upstream with npx skills add slackspac3/ce-hub. Copyright stays with the author.

AGENTS.md

Product

• Product name: Commercial Economics Hub.
• Internal shorthand: CE Hub.
• Repo: ce-hub.
• This is a secure internal consulting economics demo app.
• UX clarity is a first-class requirement.
• Do not build a spreadsheet clone or generic CRUD portal.

Engineering standards

• Always use TypeScript.
• Prefer simple, maintainable code over clever abstractions.
• Use Prisma migrations for schema changes.
• Use Zod validation on server inputs.
• Keep trusted costing calculations server-side.
• Add or update tests when changing calculations, auth, RBAC, scenario logic, or admin mutations.
• Run lint, typecheck, unit tests, and build before declaring done.

Documentation maintenance

• Review this section for every code or infrastructure change. Update the affected documents in the same change; leave them untouched only when their documented behavior and topology remain accurate.
• Update README.md when setup, scripts, deployment, credentials, or user-visible capabilities change.
• Update docs/architecture-ux-plan.md when runtime components, data stores, auth, AI/RFP stages, integrations, trust boundaries, or deployment topology change.
• Update docs/azure-migration-notes.md when the Azure target, migration phases, production gates, networking, identity, storage, or retention decisions change.
• Update docs/api/openapi.yaml and the relevant ADR when their contract or decision changes.
• For RFP or historical-memory changes, keep the equal manual/RFP paths, server-only normalization and OCR provenance, leased progress polling, fixed allowlisted gpt-5.1 Responses provider, explicit embedding capability flag, deterministic costing, human accept/apply/publish gates, ACL reauthorization, encrypted retention, and production blockers synchronized across the README, diagrams, ADRs, and security review. Never infer or claim a completed live acceptance matrix from deterministic tests.
• Architecture-affecting work is not done until the diagrams and docs/README.md index still match the implementation.

Security rules

• Never expose CTC, compensation components, or restricted assumptions to unauthorized client components.
• PROJECT_MANAGER and BID_MANAGER must not access restricted human-capital cost data.
• Every admin mutation must write an audit log entry.
• Every sensitive read of human-capital cost data should write an audit log entry if practical.
• No real salary data, real employee names, or real client names.
• Dummy rates must be clearly marked as demo/sample data.
• Do not commit .env, secrets, database URLs, tokens, or passwords.

UX rules

• Use plain business language.
• Make the core PM journey obvious.
• Use helper text and empty states.
• Show users what to do next.
• Prefer progressive disclosure over dense forms.
• Mask complexity from PM/Bid users.
• Reserve technical terms like CTC, compensation components, statutory factor, productive denominator, and formula version for restricted admin screens.

Done means

• App runs locally.
• Database migrates and seeds successfully.
• Demo users can log in.
• Core PM workflow works end-to-end.
• Admin user can manage users and roles.
• Scenario calculations are correct.
• RBAC is enforced server-side.
• Railway deployment instructions exist.
• README documents demo credentials, limitations, and future Azure path.
• Architecture and Azure migration diagrams match the current implementation and target plan.