📝 docs: 생활쓰레기·급식 hosted proxy 문서 정합성 및 skill-docs 회귀 테스트

- setup.md·k-skill-setup: 생활쓰레기/급식을 기본 hosted·unset base URL 문구에 포함, 서버 키(DATA_GO_KR·KEDU) 명시
- 표·다음 문서: 생활쓰레기 행·가이드 링크, pageNo/numOfRows 필수
- proxy README·feature doc·household-waste 스킬: 키·페이지네이션·400 계약 보강
- skill-docs.test.js: hosted 생활쓰레기/급식 흐름 회귀 테스트, 예시 secrets에 KEDU_INFO_KEY 금지

Made-with: Cursor

docs/features/k-skill-proxy.md

@@ -19,7 +19,7 @@ client/skill -> k-skill-proxy -> upstream public API
 - `GET /v1/korea-weather/forecast`
 - `GET /v1/seoul-subway/arrival`
 - `GET /v1/han-river/water-level`
-- `GET /v1/household-waste/info` (생활쓰레기 배출정보)
+- `GET /v1/household-waste/info` (생활쓰레기 배출정보, `DATA_GO_KR_API_KEY`; 쿼리 `pageNo`·`numOfRows` 필수, 값 `1`·`100`)
 - `GET /v1/korean-stock/search`
 - `GET /v1/korean-stock/base-info`
 - `GET /v1/korean-stock/trade-info`
@@ -156,7 +156,7 @@ curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/neis/school-meal' \
   --data-urlencode 'mealDate=20260410'
 ```
 
-생활쓰레기 배출정보 endpoint (`pageNo` / `numOfRows`는 반드시 `1` / `100`만 허용. 그 외 값·비정수 문자열은 `400`):
+생활쓰레기 배출정보 endpoint. 쿼리에 **`pageNo`와 `numOfRows`를 반드시 포함**하고, 값은 각각 **`1`**, **`100`**만 허용한다(`page_no` / `num_of_rows` 동일). 누락·다른 값·숫자만이 아닌 문자열이면 **`400`**(upstream 미호출):
 
 ```bash
 curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \

docs/setup.md

@@ -1,6 +1,6 @@
 # 공통 설정 가이드
 
-`k-skill` 전체 스킬을 설치한 뒤, 인증 정보가 필요한 기능(SRT 예매, KTX 예매, 한국 법령 검색의 로컬 CLI/MCP 경로용 `LAW_OC`, 한국 특허 정보 검색의 KIPRIS Plus 경로용 `KIPRIS_PLUS_API_KEY`, self-host 프록시 운영용 서울 지하철/한국 날씨/미세먼지/한강홍수통제소 upstream key, 또는 배포 확인이 끝난 proxy URL 공유)이 있으면 이 절차를 진행하면 된다. 미세먼지, 한강 수위, 주유소 가격, 부동산 실거래가, 한국 주식 정보 조회는 기본 hosted proxy를 쓰므로 사용자 쪽 키가 불필요하다.
+`k-skill` 전체 스킬을 설치한 뒤, 인증 정보가 필요한 기능(SRT 예매, KTX 예매, 한국 법령 검색의 로컬 CLI/MCP 경로용 `LAW_OC`, 한국 특허 정보 검색의 KIPRIS Plus 경로용 `KIPRIS_PLUS_API_KEY`, self-host 프록시 운영용 서울 지하철/한국 날씨/미세먼지/한강홍수통제소 upstream key, 또는 배포 확인이 끝난 proxy URL 공유)이 있으면 이 절차를 진행하면 된다. 미세먼지, 한강 수위, 주유소 가격, 부동산 실거래가, 한국 주식 정보 조회, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 기본 hosted proxy를 쓰므로 사용자 쪽 키가 불필요하다(단, hosted 프록시 운영 측에서 `DATA_GO_KR_API_KEY`·`KEDU_INFO_KEY` 등은 서버에 설정되어 있어야 한다).
 
 ## Credential resolution order
 
@@ -34,7 +34,7 @@ chmod 0600 ~/.config/k-skill/secrets.env
 
 실제 값을 채운다.
 
-서울 지하철 도착정보와 한국 날씨 조회는 hosted public route rollout 이 끝나기 전까지 `KSKILL_PROXY_BASE_URL` 을 self-host 또는 배포 확인이 끝난 proxy URL 로 채워야 한다. 미세먼지, 한강 수위, 주유소 가격은 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 그대로 쓴다.
+서울 지하철 도착정보와 한국 날씨 조회는 hosted public route rollout 이 끝나기 전까지 `KSKILL_PROXY_BASE_URL` 을 self-host 또는 배포 확인이 끝난 proxy URL 로 채워야 한다. 미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 그대로 쓴다.
 
 한국 법령 검색의 로컬 CLI/MCP 경로용 `LAW_OC` 는 `korean-law-mcp` 로컬 실행에 쓴다. 로컬 CLI/MCP 경로는 `LAW_OC` 를 채운 뒤 `npm install -g korean-law-mcp` 와 `korean-law list` 로 설치 상태를 확인한다.
 
@@ -78,6 +78,7 @@ bash scripts/check-setup.sh
 | 한국 날씨 조회 | self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL` |
 | 사용자 위치 미세먼지 조회 | `KSKILL_PROXY_BASE_URL` 또는 `AIR_KOREA_OPEN_API_KEY` |
 | 한강 수위 정보 조회 | 사용자 시크릿 불필요 (기본 hosted proxy 사용) |
+| 생활쓰레기 배출정보 조회 | 사용자 시크릿 불필요 (프록시에 `DATA_GO_KR_API_KEY`가 설정된 hosted/self-host; API 호출 시 `pageNo=1`, `numOfRows=100` 필수) |
 | 학교 급식 식단 조회 | 사용자 시크릿 불필요 (프록시에 `KEDU_INFO_KEY`가 설정된 hosted/self-host 사용) |
 
 ## 다음에 볼 문서
@@ -94,6 +95,7 @@ bash scripts/check-setup.sh
 - [하이패스 영수증 발급 가이드](features/hipass-receipt.md)
 - [한국 주식 정보 조회 가이드](features/korean-stock-search.md)
 - [근처 가장 싼 주유소 찾기 가이드](features/cheap-gas-nearby.md)
+- [생활쓰레기 배출정보 조회 가이드](features/household-waste-info.md)
 - [학교 급식 식단 조회 가이드](features/k-schoollunch-menu.md)
 - [보안/시크릿 정책](security-and-secrets.md)
 

household-waste-info/SKILL.md

@@ -116,7 +116,8 @@ curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
 - 프록시 서버에 `DATA_GO_KR_API_KEY`가 없거나 만료된 경우 (`serviceKey` 주입 실패)
 - 검색 지역명이 API 데이터와 불일치하여 결과가 비는 경우
 - 공공데이터 API 일시 장애/트래픽 제한
-- 필수 파라미터 누락(`cond[SGG_NM::LIKE]`)
+- 필수 파라미터 누락(`cond[SGG_NM::LIKE]`, 또는 `pageNo` / `numOfRows` 미전달)
+- `pageNo` / `numOfRows` 값이 `1` / `100`이 아니거나, 숫자만으로 표현되지 않은 문자열인 경우(proxy `400`, upstream 미호출)
 
 ## Notes
 

k-skill-setup/SKILL.md

@@ -77,7 +77,7 @@ chmod 0600 ~/.config/k-skill/secrets.env
 
 유저에게 물어서 실제 값을 채운다.
 
-서울 지하철 도착정보와 한국 날씨 조회는 hosted public route rollout 이 끝나기 전까지 `KSKILL_PROXY_BASE_URL` 을 self-host 또는 배포 확인이 끝난 proxy URL 로 채운다. 미세먼지, 한강 수위, 주유소 가격은 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 그대로 쓴다.
+서울 지하철 도착정보와 한국 날씨 조회는 hosted public route rollout 이 끝나기 전까지 `KSKILL_PROXY_BASE_URL` 을 self-host 또는 배포 확인이 끝난 proxy URL 로 채운다. 미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 그대로 쓴다.
 
 한국 법령 검색은 로컬 `korean-law-mcp` 경로를 쓸 때만 `LAW_OC` 를 채운다. remote endpoint는 사용자 `LAW_OC` 없이 `url`만 등록하면 되고, 기존 경로 장애 시에는 `법망`(`https://api.beopmang.org`)을 fallback으로 안내한다.
 
@@ -87,6 +87,8 @@ chmod 0600 ~/.config/k-skill/secrets.env
 
 생활쓰레기 배출정보 조회는 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 호출하고, `serviceKey`(`DATA_GO_KR_API_KEY`)는 proxy 서버에서 주입/관리하므로 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다.
 
+학교 급식 식단 조회는 `k-skill-proxy`의 `/v1/neis/school-search`·`/v1/neis/school-meal`을 호출하고, `KEDU_INFO_KEY`는 프록시 서버에만 두므로 사용자 쪽에 둘 필요가 없다.
+
 근처 가장 싼 주유소 찾기는 기본 hosted proxy를 경유하므로 사용자 쪽 `OPINET_API_KEY` 가 불필요하다.
 
 
@@ -105,7 +107,8 @@ chmod 0600 ~/.config/k-skill/secrets.env
 - 한국 부동산 실거래가 조회: 사용자 시크릿 불필요 (기본 hosted proxy 사용)
 - 한국 특허 정보 검색: `KIPRIS_PLUS_API_KEY`
 - 한국 주식 정보 조회: 사용자 시크릿 불필요 (기본 hosted proxy 사용, 운영자만 `KRX_API_KEY`)
-- 생활쓰레기 배출정보 조회: 사용자 시크릿 불필요 (`serviceKey`는 proxy 서버 주입)
+- 생활쓰레기 배출정보 조회: 사용자 시크릿 불필요 (`serviceKey`는 proxy 서버 주입, 호출 시 `pageNo=1`·`numOfRows=100` 필수)
+- 학교 급식 식단 조회: 사용자 시크릿 불필요 (`KEDU_INFO_KEY`는 proxy 서버만)
 - 근처 가장 싼 주유소 찾기: 사용자 시크릿 불필요 (기본 hosted proxy 사용)
 - 서울 지하철: self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL`
 - 한국 날씨: self-host 또는 배포 확인이 끝난 `KSKILL_PROXY_BASE_URL`

packages/k-skill-proxy/README.md

@@ -9,7 +9,7 @@
 - `GET /v1/korea-weather/forecast`
 - `GET /v1/seoul-subway/arrival`
 - `GET /v1/han-river/water-level`
-- `GET /v1/household-waste/info` — 생활쓰레기 배출정보(시군구)
+- `GET /v1/household-waste/info` — 생활쓰레기 배출정보(`DATA_GO_KR_API_KEY`; `pageNo=1`, `numOfRows=100` 필수)
 - `GET /v1/neis/school-search` — 나이스 학교기본정보(교육청명·학교명 검색)
 - `GET /v1/neis/school-meal` — 나이스 급식식단정보(일자별 메뉴)
 - `GET /v1/korean-stock/search`

scripts/skill-docs.test.js

@@ -2090,3 +2090,67 @@ test("MFDS public-health skill docs require interview-first safety flow and offi
   assert.match(sources, /https:\/\/openapi\.foodsafetykorea\.go\.kr\/api\/sample\/I0490\/json\/1\/5/);
   assert.doesNotMatch(sources, /http:\/\/openapi\.foodsafetykorea\.go\.kr/);
 });
+
+test("docs/setup.md and k-skill-setup document hosted household waste proxy flow", () => {
+  const setup = read(path.join("docs", "setup.md"));
+  const setupSkill = read(path.join("k-skill-setup", "SKILL.md"));
+  
+  assert.match(
+    setup,
+    /한국 주식 정보 조회, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 기본 hosted proxy를 쓰므로/,
+    "setup.md intro should list household waste among hosted-proxy features with no user-side key",
+  );
+  assert.match(setup, /DATA_GO_KR_API_KEY.*서버에 설정/);
+  assert.match(
+    setup,
+    /미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path\(`k-skill-proxy\.nomadamas\.org`\)/,
+    "setup.md should list fine dust, Han River, gas, household waste, and school lunch when KSKILL_PROXY_BASE_URL is unset",
+  );
+  assert.match(
+    setupSkill,
+    /미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 `KSKILL_PROXY_BASE_URL`/,
+    "k-skill-setup SKILL should mirror setup.md hosted-proxy unset-base-URL guidance",
+  );
+
+  assert.match(setup, /\| 생활쓰레기 배출정보 조회 \|/);
+  assert.match(setup, /DATA_GO_KR_API_KEY/);
+  assert.match(setup, /pageNo=1.*numOfRows=100|numOfRows=100.*pageNo=1/);
+  assert.match(setup, /\[생활쓰레기 배출정보 조회 가이드\]\(features\/household-waste-info\.md\)/);
+
+  assert.match(setupSkill, /\/v1\/household-waste\/info/);
+  assert.match(setupSkill, /DATA_GO_KR_API_KEY/);
+  assert.match(setupSkill, /생활쓰레기 배출정보 조회: 사용자 시크릿 불필요/);
+});
+
+test("docs/setup.md and k-skill-setup document hosted school lunch proxy flow", () => {
+  const setup = read(path.join("docs", "setup.md"));
+  const setupSkill = read(path.join("k-skill-setup", "SKILL.md"));
+  const examplesSecrets = read(path.join("examples", "secrets.env.example"));
+  assert.match(setup, /학교 급식 식단 조회는 기본 hosted proxy/);
+  assert.match(setup, /KEDU_INFO_KEY.*서버에 설정/);
+  assert.match(
+    setup,
+    /미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 `KSKILL_PROXY_BASE_URL` 을 비워 두면 기본 hosted path\(`k-skill-proxy\.nomadamas\.org`\)/,
+    "setup.md should list fine dust, Han River, gas, household waste, and school lunch when KSKILL_PROXY_BASE_URL is unset",
+  );
+  assert.match(
+    setupSkill,
+    /미세먼지, 한강 수위, 주유소 가격, 생활쓰레기 배출정보 조회, 학교 급식 식단 조회는 `KSKILL_PROXY_BASE_URL`/,
+    "k-skill-setup SKILL should mirror setup.md hosted-proxy unset-base-URL guidance",
+  );
+
+  assert.match(setup, /\| 학교 급식 식단 조회 \|/);
+  assert.match(setup, /KEDU_INFO_KEY/);
+  assert.match(setup, /\[학교 급식 식단 조회 가이드\]\(features\/k-schoollunch-menu\.md\)/);
+
+  assert.match(setupSkill, /\/v1\/neis\/school-search/);
+  assert.match(setupSkill, /\/v1\/neis\/school-meal/);
+  assert.match(setupSkill, /KEDU_INFO_KEY/);
+  assert.match(setupSkill, /학교 급식 식단 조회: 사용자 시크릿 불필요/);
+
+  assert.doesNotMatch(
+    examplesSecrets,
+    /^KEDU_INFO_KEY=/m,
+    "client secrets example must not encourage KEDU_INFO_KEY (proxy server only)",
+  );
+});