From b8df50311f01be1d82165e3657441b639794dc2e Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Sun, 5 Jul 2026 00:21:37 +0800 Subject: [PATCH 1/3] docs: add agents guide for codex users --- docs/agents-guide.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/agents-guide.md diff --git a/docs/agents-guide.md b/docs/agents-guide.md new file mode 100644 index 0000000000..fd8be7459d --- /dev/null +++ b/docs/agents-guide.md @@ -0,0 +1,34 @@ +# Agents Guide + +## Purpose +This repository contains the Clinical KB application. It is a Next.js + Supabase + OpenAI RAG knowledge base for medical guidelines. Agents working with this project should follow these guidelines. + +## Getting Started +- Use Node 24 and npm 11; the project uses Next.js v16. +- Copy `.env.example` to `.env.local` and populate secrets. **Never commit actual secrets**. +- Use `npm run ensure` to start or verify the local dev server. It selects a stable port automatically. +- Start the ingestion worker in a separate terminal using `npm run worker`. + +## Development Guidelines +- Avoid changing `.env.example` values other than adding placeholders. Do not commit `.env.local`. +- When adding environment variables, update the schema in `src/lib/env.ts` and document them in `.env.example`. +- Use TypeScript and follow existing code patterns; avoid introducing new dependencies unless necessary. +- Run `npm run lint` and `npm run typecheck` before committing. +- Use `npm run test` and `npm run test:e2e` to ensure critical flows remain stable. +- Keep Supabase service role keys on the server; never expose them to the client. + +## Routing & Architecture +- The app uses the Next.js App Router under `src/app`. +- API routes live under `src/app/api`. +- Client components are in `src/components`. +- Supabase integration code is in `src/lib/supabase`. + +## Performance & Safety +- Use `zod` for request and environment validation. +- Enforce permissions server-side; do not rely on client-side checks. +- Respect the existing rate-limiting and source-governance logic. +- When adding new API endpoints, provide appropriate error handling and status codes. + +## Documentation +- Keep the README up to date if you change setup, scripts, or environment variables. +- Add high-level architectural changes or decisions in `docs/`. From f44b5f97227aa5e433ddbdbc232334711799ea45 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Sun, 5 Jul 2026 00:21:59 +0800 Subject: [PATCH 2/3] docs: fix step numbering in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f1f8803fb0..ac10276e30 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ belongs to this project, and starts the dev server in the background if needed. When you say `run` in this chat, Codex should use this command and return the printed URL. -7. In a second terminal, start the local ingestion worker: +8. In a second terminal, start the local ingestion worker: ```bash npm run worker From b082578c3bc42d226114f5a72b2ddfb84e4c26bd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 4 Jul 2026 17:07:50 +0000 Subject: [PATCH 3/3] fix: format docs/agents-guide.md to pass Prettier check --- docs/agents-guide.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/agents-guide.md b/docs/agents-guide.md index fd8be7459d..b7e935d531 100644 --- a/docs/agents-guide.md +++ b/docs/agents-guide.md @@ -1,15 +1,18 @@ # Agents Guide ## Purpose + This repository contains the Clinical KB application. It is a Next.js + Supabase + OpenAI RAG knowledge base for medical guidelines. Agents working with this project should follow these guidelines. ## Getting Started + - Use Node 24 and npm 11; the project uses Next.js v16. - Copy `.env.example` to `.env.local` and populate secrets. **Never commit actual secrets**. - Use `npm run ensure` to start or verify the local dev server. It selects a stable port automatically. - Start the ingestion worker in a separate terminal using `npm run worker`. ## Development Guidelines + - Avoid changing `.env.example` values other than adding placeholders. Do not commit `.env.local`. - When adding environment variables, update the schema in `src/lib/env.ts` and document them in `.env.example`. - Use TypeScript and follow existing code patterns; avoid introducing new dependencies unless necessary. @@ -18,17 +21,20 @@ This repository contains the Clinical KB application. It is a Next.js + Supabase - Keep Supabase service role keys on the server; never expose them to the client. ## Routing & Architecture + - The app uses the Next.js App Router under `src/app`. - API routes live under `src/app/api`. - Client components are in `src/components`. - Supabase integration code is in `src/lib/supabase`. ## Performance & Safety + - Use `zod` for request and environment validation. - Enforce permissions server-side; do not rely on client-side checks. - Respect the existing rate-limiting and source-governance logic. - When adding new API endpoints, provide appropriate error handling and status codes. ## Documentation + - Keep the README up to date if you change setup, scripts, or environment variables. - Add high-level architectural changes or decisions in `docs/`.