# Repository Instructions

## Scope

This repository contains design documents and a first runnable demo for SQL Catalog and the broader SQL analysis / inspection / governance platform.

Primary content lives under:

- `design/discuss_1/`: first-round design discussions.
- `design/discuss_2/`: second-round grounded design and planning.
- `backend/`: Python standard-library backend and API server.
- `frontend/`: React + Vite + TypeScript frontend. Frontend package files, Vite config, TypeScript config, lockfile, and `node_modules` belong inside this directory.

## Working Rules

- Treat design documents as the source of product semantics.
- Keep the backend dependency-light.
- Build UI with the same stack and interaction style as Clinic slow-log-explorer and `tidb-slowlog-selection`: React, Vite, TypeScript, Tailwind, React Query, lucide icons, dense tool UI.
- Do not change first-round documents when continuing later discussions unless the user asks for a revision.
- Add new discussion artifacts under a new `design/discuss_*` directory, or update the active discussion directory when the user explicitly asks to solidify the current round.
- Keep product terminology consistent:
  - `Finding` is an external standard input.
  - `SQL Catalog Item` is the long-lived digest dossier.
  - `Treatment` is one governance / intervention lifecycle.
  - `Record` is a structured-fields plus Markdown note.
  - `Timeline` records important history for Catalog Items and Treatments.
- Use `SQL Catalog` for the product/module name and `Catalog` for the navigation entry.

## Validation

For documentation-only changes, review the affected Markdown manually and check that headings, lists, and terminology remain consistent.

For demo app changes, run:

```bash
python3 -m py_compile backend/sql_catalog/server.py
cd frontend && pnpm build
```

Then verify `GET /api/v1/healthz`, `POST /api/v1/findings`, and the Vite dev app at `http://127.0.0.1:5173`.