문서: 설정 파일이 6개 필요한 것처럼 적혀 있던 것을 바로잡는다

앞 커밋의 표가 여섯 줄을 나란히 놓아서 "클론하면 여섯 개를 만들어야 한다" 로 읽혔다.
실제로 세어 보니 compose 로 띄우는 데 필요한 건 둘이다.

- .env            compose 가 env_file 로 읽는다
- nginx/site.conf compose 가 bind mount 한다

나머지 넷은 필수가 아니다.
- config.local.toml : 도커 이미지가 example 사본을 구워서 나온다(Dockerfile:24).
  호스트에서 python web_main.py 를 직접 돌릴 때만 손으로 만든다.
- config.test.toml  : pytest 를 돌릴 때만.
- 프론트 .env 둘    : VITE_* 가 전부 코드 폴백을 갖고 있고(?? 'http://localhost:9800',
  ?? window.location.host) compose 는 값을 직접 주입한다. 만들 이유가 없다.

표를 필수/선택/안 만들어도 됨으로 갈랐다. 클론 직후 명령도 둘로 줄이고,
toml 은 "호스트에서 돌릴 때만" 이라는 조건을 붙여 아래로 내렸다.

AGENTS.md

@@ -107,17 +107,19 @@ docker compose logs -f worker
 
 ## 설정 파일은 어느 폴더에 두나
 
-**실제 값은 하나도 커밋되지 않는다.** 커밋되는 건 `*.example` 뿐이고, 클론 직후 그걸 복사해
-값을 채우는 게 세팅의 전부다.
+**`docker compose up -d` 에 꼭 필요한 건 두 개다.** 나머지는 호스트에서 파이썬을 직접
+돌릴 때만 붙는다 — 앱마다 설정이 흩어져 있는 게 아니다.
 
-| 폴더 | 파일 | 담는 것 | 템플릿 |
+| | 폴더 | 파일 | 없으면 |
 |---|---|---|---|
-| **레포 루트** | `.env` | DB · JWT · 외부 API 키 · 수집 어댑터 · 발행/색인 · 포트 바인딩 | `.env.example` |
-| `solution/backend/config/` | `config.local.toml` | DB 접속 · JWT · 포트 · CORS(`client_url`) | `config.local.toml.example` |
-| `solution/backend/config/` | `config.test.toml` | 테스트 DB(`web4ai_test_db`) | `config.test.toml.example` |
-| `solution/frontend/` | `.env` | 이 앱의 `VITE_*` (API :9800 · 발행 호스트 · 개발 자동로그인) | `.env.example` |
-| `admin/frontend/` | `.env` | 이 앱의 `VITE_*` (API **:9801**) | `.env.example` |
-| `nginx/` | `site.conf` | 발행 사이트 정적 서빙 규칙 | `site.conf.example` |
+| **필수** | 레포 루트 | `.env` | compose 가 `env_file` 로 읽는다. DB·JWT·API 키가 안 들어간다 |
+| **필수** | `nginx/` | `site.conf` | compose 가 bind mount 한다. **Docker 가 그 자리에 디렉토리를 만들어** nginx 가 설정 없이 뜬다 |
+| 선택 | `solution/backend/config/` | `config.local.toml` | 호스트에서 백엔드를 직접 돌릴 때만. **도커 이미지는 이걸 구워서 나온다**(`Dockerfile:24`) |
+| 선택 | `solution/backend/config/` | `config.test.toml` | `pytest` 가 conftest import 단계에서 죽는다 |
+| 안 만들어도 됨 | `solution/frontend/` | `.env` | 코드에 폴백이 다 있고(`?? 'http://localhost:9800'`), compose 는 값을 직접 주입한다 |
+| 안 만들어도 됨 | `admin/frontend/` | `.env` | 〃 |
+
+전부 `*.example` 이 짝으로 있고, 실제 값은 하나도 커밋되지 않는다.
 
 **두지 않는 곳** — 두면 조용히 무시된다.
 
@@ -125,22 +127,22 @@ docker compose logs -f worker
 |---|---|
 | `solution/backend/` | `.env` 를 여기 두면 아무도 안 읽는다. dotenv 가 **레포 루트**를 본다 (`config/server_configs.py`) |
 | `admin/backend/` | 진입점 두 파일뿐이다. `config/` 는 `PYTHONPATH` 로 `solution/backend` 것을 그대로 쓴다 |
-| `solution/site/` | 렌더러는 런타임 env 를 안 쓴다 — 사이트별 값은 전부 `SitePayload` 로 들어온다. 그래야 payload 하나로 같은 HTML 이 재현된다. 프리렌더 옵션은 CLI 인자(`--payload` `--out`)이고, `INDEXNOW_KEY`·`PORT` 는 compose 가 프로세스에 넣는다 |
+| `solution/site/` | 렌더러는 런타임 env 를 안 쓴다 — 사이트별 값은 전부 `SitePayload` 로 들어온다. 프리렌더 옵션은 CLI 인자(`--payload` `--out`)이고, `INDEXNOW_KEY`·`PORT` 는 compose 가 프로세스에 넣는다 |
 | `solution/shared/` | 코드만 있다 |
 
 ### 클론 직후 한 번
 
 ```bash
-cp .env.example .env
+cp .env.example .env                          # JWT_* 는 반드시 채운다(아래 참고)
 cp nginx/site.conf.example nginx/site.conf
-cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml
-cp solution/backend/config/config.test.toml.example  solution/backend/config/config.test.toml
-cp solution/frontend/.env.example solution/frontend/.env    # compose 로만 쓰면 생략 가능
-cp admin/frontend/.env.example    admin/frontend/.env       # 〃
 ```
 
-`site.conf` 를 빼먹으면 Docker 가 그 자리에 **디렉토리**를 만들어 nginx 가 설정 없이 뜬다.
-`config.test.toml` 이 없으면 `pytest` 가 conftest import 단계에서 죽는다.
+호스트에서 백엔드를 돌리거나 `pytest` 를 쓸 때만 추가로:
+
+```bash
+cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml
+cp solution/backend/config/config.test.toml.example  solution/backend/config/config.test.toml
+```
 
 ### 누가 무엇을 읽나 — 우선순위
 

README.md

@@ -13,10 +13,10 @@
 ## 실행
 
 ```bash
-# 클론 직후 1회 — 설정 파일 복사 목록은 AGENTS.md "설정 파일은 어느 폴더에 두나"
-cp .env.example .env
+# 클론 직후 1회 — compose 에 필요한 건 이 둘뿐이다.
+# 호스트에서 백엔드·pytest 를 직접 돌릴 때 붙는 toml 은 AGENTS.md 참고.
+cp .env.example .env                          # JWT_* 를 채운다
 cp nginx/site.conf.example nginx/site.conf
-cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml
 
 docker compose up -d
 docker compose logs -f worker