docs: 로컬 체크아웃 대상 시작하기 가이드 추가

README.md

@@ -24,7 +24,7 @@ targets.local.yaml -> workspace -> Gitleaks -> Finding -> local store -> report
 - synthetic corpus로 precision, recall, false negative를 계산합니다.
 - Ollama-compatible verifier로 finding의 triage 상태를 보조합니다.
 
-자세한 진행 상황은 [progress dashboard](docs/dashboards/progress.html)와 [project overview](docs/views/00-project-overview-and-strategy.md)에 정리되어 있습니다.
+자세한 진행 상황은 [progress dashboard](docs/dashboards/progress.html)와 [project overview](docs/views/project-overview-and-strategy.md)에 정리되어 있습니다.
 
 ## 현재 지원 범위
 
@@ -51,41 +51,24 @@ targets.local.yaml -> workspace -> Gitleaks -> Finding -> local store -> report
 
 ## 빠른 시작
 
-필요한 도구:
+전제: `uv`, `gitleaks` v8, `security-scanner` source checkout, 스캔할 별도 로컬 checkout이 준비되어 있습니다.
 
-- `uv`
-- `gitleaks`
-- 스캔할 로컬 checkout
-
-의존성을 설치합니다.
+아래 명령은 `security-scanner` 저장소 root에서 실행합니다. `targets.local.yaml`에는 스캔 대상 저장소 경로를 적습니다.
 
 ```bash
 uv sync
-```
-
-예제 설정을 복사합니다.
-
-```bash
 cp examples/targets.local.example.yaml targets.local.yaml
-```
-
-기본 스캔을 실행합니다.
+# targets.local.yaml에 로컬 checkout 경로를 적습니다.
 
-```bash
-uv run security-scanner scan \
-  --manifest targets.local.yaml \
-  --output private/findings.jsonl
-
-uv run security-scanner report \
-  --findings private/findings.jsonl
-
-uv run security-scanner gate \
-  --findings private/findings.jsonl \
-  --max 0
+uv run security-scanner scan   --manifest targets.local.yaml --output private/findings.jsonl
+uv run security-scanner report --findings private/findings.jsonl
+uv run security-scanner gate   --findings private/findings.jsonl --max 0
 ```
 
 `private/`는 gitignore 대상입니다. 실제 스캔 결과와 로컬 설정은 이 경계 안에 두세요.
 
+단계별 설명, manifest 필드, 트러블슈팅은 [시작하기 가이드](docs/views/getting-started.md)를 참고하세요.
+
 ## 로컬 NoSQL 저장소
 
 DynamoDB-compatible backend는 로컬에서 조회 패턴을 검증하기 위한 저장소입니다. 관리형 저장소 연동은 현재 지원 범위가 아닙니다.
@@ -112,7 +95,7 @@ uv run security-scanner gate \
 
 스캔을 실행하면 `Scan run ID`가 출력됩니다. 특정 실행 결과만 보고 싶으면 그 값을 `--scan-run-id`로 넘깁니다. 저장소 전체를 대상으로 판단할 때만 생략합니다.
 
-Schema와 조회 기준은 [소스 스캔 결과 NoSQL Schema](docs/views/02-source-scan-results-nosql-schema.md)에 정리되어 있습니다.
+Schema와 조회 기준은 [소스 스캔 결과 NoSQL Schema](docs/views/source-scan-results-nosql-schema.md)에 정리되어 있습니다.
 
 ## 평가와 verifier
 
@@ -130,19 +113,40 @@ uv run security-scanner evaluate \
 
 Verifier 적용 전후도 같은 방식으로 비교합니다.
 
+Ollama가 scanner를 실행하는 Ubuntu host에 설치되어 있으면 host는 localhost로 둡니다.
+
 ```bash
+export SECURITY_SCANNER_OLLAMA_HOST=http://127.0.0.1:11434
+export SECURITY_SCANNER_OLLAMA_MODEL=lfm2.5-thinking
+
 uv run security-scanner verify \
   --findings private/eval-findings.jsonl \
-  --output private/eval-verified-findings.jsonl \
-  --ollama-host "$SECURITY_SCANNER_OLLAMA_HOST" \
-  --ollama-model "$SECURITY_SCANNER_OLLAMA_MODEL"
+  --output private/eval-verified-findings.jsonl
 
 uv run security-scanner evaluate \
   --expected eval/synthetic-corpus/expected-findings.example.json \
   --findings private/eval-findings.jsonl \
   --after-findings private/eval-verified-findings.jsonl
 ```
 
+오탐 감소 흐름은 detector-visible documentation candidate를 포함한 별도 corpus로 확인합니다.
+
+```bash
+uv run security-scanner scan \
+  --manifest eval/verifier-corpus/targets.local.example.yaml \
+  --output private/verifier-findings.jsonl
+
+uv run security-scanner verify \
+  --findings private/verifier-findings.jsonl \
+  --output private/verifier-verified-findings.jsonl
+
+uv run security-scanner evaluate \
+  --expected eval/verifier-corpus/expected-findings.example.json \
+  --findings private/verifier-findings.jsonl \
+  --after-findings private/verifier-verified-findings.jsonl \
+  --precision-min 0.5
+```
+
 Verifier는 detector가 아닙니다. Finding을 삭제하지 않고, 사람이 검토할 때 참고할 triage 상태만 붙입니다.
 
 응답 실패, timeout, 낮은 confidence는 모두 “검토 필요” 상태로 남깁니다.
@@ -163,20 +167,20 @@ core <- scanners/storage/llm/adapters <- cli/runtime
 - `llm/ollama/`는 redacted metadata 기반 verifier 호출을 담당합니다.
 - `adapters/aws_future/`는 현재 실행 경로가 아닙니다.
 
-더 자세한 설명은 [시스템 구조와 실행 환경](docs/views/01-system-architecture-and-runtime.md)을 보세요.
+더 자세한 설명은 [시스템 구조와 실행 환경](docs/views/system-architecture-and-runtime.md)을 보세요.
 
 ## 문서
 
 문서의 시작점은 [docs/README.md](docs/README.md)입니다.
 
-- [프로젝트 개요와 추진 전략](docs/views/00-project-overview-and-strategy.md)
-- [시스템 구조와 실행 환경](docs/views/01-system-architecture-and-runtime.md)
-- [소스 스캔 결과 NoSQL Schema](docs/views/02-source-scan-results-nosql-schema.md)
-- [탐지 결과와 지표](docs/views/03-secret-detection-results-and-metrics.md)
-- [Local Scan Orchestration 목표 구조](docs/views/04-local-scan-orchestration-target-architecture.md)
-- [확장 경로와 운영 기준](docs/views/05-operations-transition-architecture.md)
-- [리서치 요약과 기술 결정](docs/views/06-research-and-technical-decisions.md)
-- [공개 저장소 안전 정책](docs/views/09-public-repo-safety-policy.md)
+- [프로젝트 개요와 추진 전략](docs/views/project-overview-and-strategy.md)
+- [시스템 구조와 실행 환경](docs/views/system-architecture-and-runtime.md)
+- [소스 스캔 결과 NoSQL Schema](docs/views/source-scan-results-nosql-schema.md)
+- [탐지 결과와 지표](docs/views/secret-detection-results-and-metrics.md)
+- [Local Scan Orchestration 목표 구조](docs/views/local-scan-orchestration-target-architecture.md)
+- [확장 경로와 운영 기준](docs/views/operations-transition-architecture.md)
+- [리서치 요약과 기술 결정](docs/views/research-and-technical-decisions.md)
+- [공개 저장소 안전 정책](docs/views/public-repo-safety-policy.md)
 
 `docs/views/`, `docs/assets/`, `docs/dashboards/`는 publish 후보입니다.
 
@@ -193,7 +197,7 @@ core <- scanners/storage/llm/adapters <- cli/runtime
 3. 파일명을 지정해서 stage합니다. `git add -A`와 `git add .`는 피합니다.
 4. 실제 증거 자료는 `private/` 또는 저장소 밖에 둡니다.
 
-세부 기준은 [공개 저장소 안전 정책](docs/views/09-public-repo-safety-policy.md)에 있습니다.
+세부 기준은 [공개 저장소 안전 정책](docs/views/public-repo-safety-policy.md)에 있습니다.
 
 ## 다음 작업
 

docs/README.md

@@ -21,25 +21,27 @@
 
 ## 먼저 읽을 문서
 
-1. [프로젝트 개요와 추진 전략](views/00-project-overview-and-strategy.md)
-2. [시스템 구조와 실행 환경](views/01-system-architecture-and-runtime.md)
-3. [소스 스캔 결과 NoSQL Schema](views/02-source-scan-results-nosql-schema.md)
-4. [탐지 결과와 지표](views/03-secret-detection-results-and-metrics.md)
-5. [Local Scan Orchestration 구조](views/04-local-scan-orchestration-target-architecture.md)
-6. [progress dashboard](dashboards/progress.html)
+1. [프로젝트 개요와 추진 전략](views/project-overview-and-strategy.md)
+2. [시스템 구조와 실행 환경](views/system-architecture-and-runtime.md)
+3. [소스 스캔 결과 NoSQL Schema](views/source-scan-results-nosql-schema.md)
+4. [탐지 결과와 지표](views/secret-detection-results-and-metrics.md)
+5. [Local Scan Orchestration 구조](views/local-scan-orchestration-target-architecture.md)
+6. [시작하기](views/getting-started.md)
+7. [progress dashboard](dashboards/progress.html)
 
 ## 공개 후보 문서
 
 | 문서 | 읽으면 알 수 있는 것 |
 | --- | --- |
-| [00-project-overview-and-strategy.md](views/00-project-overview-and-strategy.md) | 이 프로젝트가 해결하려는 문제, 현재 지원 범위, 성공 기준 |
-| [01-system-architecture-and-runtime.md](views/01-system-architecture-and-runtime.md) | 전체 구조, 실행 흐름, codebase dependency boundary |
-| [02-source-scan-results-nosql-schema.md](views/02-source-scan-results-nosql-schema.md) | 스캔 결과를 어떻게 저장하고 어떤 질문에 답하려는지 |
-| [03-secret-detection-results-and-metrics.md](views/03-secret-detection-results-and-metrics.md) | 어떤 결과를 공개할 수 있고, 지표를 어떻게 해석하는지 |
-| [04-local-scan-orchestration-target-architecture.md](views/04-local-scan-orchestration-target-architecture.md) | Local Scan Orchestration의 Python file 참조 관계와 runtime call chain |
-| [05-operations-transition-architecture.md](views/05-operations-transition-architecture.md) | 로컬 실행 경로에서 반복 실행과 확장 adapter로 넘어가는 기준 |
-| [06-research-and-technical-decisions.md](views/06-research-and-technical-decisions.md) | 왜 Gitleaks-first인지, 다른 도구는 어떤 위치인지 |
-| [09-public-repo-safety-policy.md](views/09-public-repo-safety-policy.md) | 공개 저장소에 쓰면 안 되는 것과 커밋 전 확인 기준 |
+| [project-overview-and-strategy.md](views/project-overview-and-strategy.md) | 이 프로젝트가 해결하려는 문제, 현재 지원 범위, 성공 기준 |
+| [system-architecture-and-runtime.md](views/system-architecture-and-runtime.md) | 전체 구조, 실행 흐름, codebase dependency boundary |
+| [source-scan-results-nosql-schema.md](views/source-scan-results-nosql-schema.md) | 스캔 결과를 어떻게 저장하고 어떤 질문에 답하려는지 |
+| [secret-detection-results-and-metrics.md](views/secret-detection-results-and-metrics.md) | 어떤 결과를 공개할 수 있고, 지표를 어떻게 해석하는지 |
+| [local-scan-orchestration-target-architecture.md](views/local-scan-orchestration-target-architecture.md) | Local Scan Orchestration의 Python file 참조 관계와 runtime call chain |
+| [operations-transition-architecture.md](views/operations-transition-architecture.md) | 로컬 실행 경로에서 반복 실행과 확장 adapter로 넘어가는 기준 |
+| [research-and-technical-decisions.md](views/research-and-technical-decisions.md) | 왜 Gitleaks-first인지, 다른 도구는 어떤 위치인지 |
+| [getting-started.md](views/getting-started.md) | 이미 클론된 로컬 저장소로 첫 스캔을 끝까지 돌리는 절차 |
+| [public-repo-safety-policy.md](views/public-repo-safety-policy.md) | 공개 저장소에 쓰면 안 되는 것과 커밋 전 확인 기준 |
 
 ## 시각 자료
 

docs/_harness/doc-map.yml

@@ -32,7 +32,7 @@ source_sets:
 human_views:
   - view_id: project-overview-and-strategy
     title: 프로젝트 개요와 추진 전략
-    path: docs/views/00-project-overview-and-strategy.md
+    path: docs/views/project-overview-and-strategy.md
     output_path: confluence://프로젝트-개요-및-추진-전략
     generated_by: human_doc_curator
     generated_at: 2026-05-23
@@ -49,7 +49,7 @@ human_views:
       - docs/assets/supported-workflow-map.svg
   - view_id: system-architecture-and-runtime
     title: 시스템 구조와 실행 환경
-    path: docs/views/01-system-architecture-and-runtime.md
+    path: docs/views/system-architecture-and-runtime.md
     output_path: confluence://프로젝트-개요-및-추진-전략/시스템-구조-및-실행-환경
     generated_by: human_doc_curator
     generated_at: 2026-05-23
@@ -68,7 +68,7 @@ human_views:
       - docs/assets/codebase-architecture.svg
   - view_id: source-scan-results-nosql-schema
     title: 소스 스캔 결과 NoSQL Schema
-    path: docs/views/02-source-scan-results-nosql-schema.md
+    path: docs/views/source-scan-results-nosql-schema.md
     output_path: confluence://프로젝트-개요-및-추진-전략/소스코드-스캔-결과-NoSQL-Schema
     generated_by: human_doc_curator
     generated_at: 2026-05-23
@@ -81,7 +81,7 @@ human_views:
       - docs/assets/schema-access-patterns.svg
   - view_id: secret-detection-results-and-metrics
     title: 탐지 결과와 지표
-    path: docs/views/03-secret-detection-results-and-metrics.md
+    path: docs/views/secret-detection-results-and-metrics.md
     output_path: confluence://프로젝트-개요-및-추진-전략/Secret-Detection-결과
     generated_by: human_doc_curator
     generated_at: 2026-05-23
@@ -98,7 +98,7 @@ human_views:
       - docs/assets/metrics-flow.svg
   - view_id: local-scan-orchestration-target-architecture
     title: Local Scan Orchestration 구조
-    path: docs/views/04-local-scan-orchestration-target-architecture.md
+    path: docs/views/local-scan-orchestration-target-architecture.md
     output_path: confluence://프로젝트-개요-및-추진-전략/Local-Scan-Orchestration-구조
     generated_by: human_doc_curator
     generated_at: 2026-05-24
@@ -118,7 +118,7 @@ human_views:
       - docs/assets/local-scan-target-scenario-seams.drawio
   - view_id: operations-transition-architecture
     title: 확장 경로와 운영 기준
-    path: docs/views/05-operations-transition-architecture.md
+    path: docs/views/operations-transition-architecture.md
     output_path: confluence://프로젝트-개요-및-추진-전략/운영-전환-및-배포-아키텍처
     generated_by: human_doc_curator
     generated_at: 2026-05-23
@@ -135,7 +135,7 @@ human_views:
       - docs/assets/operations-transition.svg
   - view_id: research-and-technical-decisions
     title: 리서치 요약과 기술 결정
-    path: docs/views/06-research-and-technical-decisions.md
+    path: docs/views/research-and-technical-decisions.md
     output_path: confluence://프로젝트-개요-및-추진-전략/리서치-요약-및-기술-결정
     generated_by: human_doc_curator
     generated_at: 2026-05-23
@@ -150,9 +150,19 @@ human_views:
       docs/workbench/context/legacy-source/06-evaluation-loop.md: a6778be2cc57d0b1c4e26d62f1fc0c11abe75bc38e175644f8b1d3b2d9ac0e1e
     assets:
       - docs/assets/decision-matrix.svg
+  - view_id: getting-started
+    title: 시작하기
+    path: docs/views/getting-started.md
+    output_path: confluence://프로젝트-개요-및-추진-전략/시작하기
+    generated_by: human_doc_curator
+    generated_at: 2026-05-25
+    safety_class: public
+    source_docs: []
+    source_hashes: {}
+    assets: []
   - view_id: public-repo-safety-policy
     title: 공개 저장소 안전 정책
-    path: docs/views/09-public-repo-safety-policy.md
+    path: docs/views/public-repo-safety-policy.md
     output_path: confluence://프로젝트-개요-및-추진-전략/데이터-취급-및-공개-범위-관리
     generated_by: human_doc_curator
     generated_at: 2026-05-23