docs: clarify main project guides

Author: 2-mean

README.md

@@ -2,6 +2,17 @@
 
 Client update를 이용해 프레임워크 내부에서 다양한 client graph를 구성·교체하고, control graph ablation을 통해 Graph-FL gain이 실제 client relation structure 때문인지 아니면 dominance, norm, smoothing, optimizer 효과 때문인지 분해하는 실험 프레임워크.
 
+Graph-FL Design Lab의 중심은 graph를 만드는 방식과 graph를 검증하는 방식을 같은
+실험대 위에 올리는 것이다. 많은 Graph-FL 방법은 client representation, relation
+score, topology, edge weight, aggregation target 중 일부를 바꾸며 발전한다. 이
+저장소는 그 차이를 공통 부품으로 표현하고, 같은 control과 diagnostic metric으로
+비교할 수 있게 만든다.
+
+따라서 결과 해석은 단순한 `FedAvg` 대비 성능 비교에서 멈추지 않는다. real graph,
+matched control, graph-free correction, mechanism metric을 함께 읽어 graph gain이
+relation 정보에서 왔는지, smoothing이나 dominance correction으로도 설명되는지,
+어떤 graph 구성요소가 민감한지 확인한다.
+
 ## Naming
 
 | Area | Canonical | Notes |
@@ -21,23 +32,41 @@ Client update를 이용해 프레임워크 내부에서 다양한 client graph
 | Primary evidence | real-control gap, graph-free control gap, alignment, LOO, DI / N_eff |
 | Minimum experiments | Non-IID stress preflight; real vs counterfactual + graph-free controls; source/mode/target attribution; diagnostic mechanism chain |
 
+## How To Read This Project
+
+| Layer | What It Answers |
+|---|---|
+| Graph authoring | 어떤 client signal로 graph를 만들고, 어떤 topology와 aggregation target에 연결하는가 |
+| Controls | 같은 조건에서 relation 의미, smoothing, coarse community, dominance correction을 어떻게 분리하는가 |
+| Diagnostics | accuracy/loss 변화와 alignment, DI, N_eff, LOO, graph metrics가 함께 움직이는가 |
+| Prior-work mapping | 기존 Graph-FL/PFL 방법을 exact reproduction, proxy, interface target 중 어디에 놓을 수 있는가 |
+
 | Document | Link |
 |---|---|
 | Experimental design | [docs/framework/graph_fl_experimental_design.md](docs/framework/graph_fl_experimental_design.md) |
 | Metric reference | [docs/framework/graph_fl_experimental_design_appendix.md](docs/framework/graph_fl_experimental_design_appendix.md) |
 | Docs index | [docs/README.md](docs/README.md) |
+| Visual demo | [docs/demos/graphfl-assembly-scratch.html](docs/demos/graphfl-assembly-scratch.html) |
 
 ## Quick Start
 
-Run from repository root. Python 3.11 recommended.
+Run from repository root. Python 3.11 is the reference version. Commands below
+use `python`; replace it with the interpreter from your own virtual environment
+when needed. No absolute local path is required.
 
 ### Environment
 
 | Step | Command |
 |---|---|
 | Create venv | `python3.11 -m venv .venv` |
-| Install deps | `.venv/bin/python -m pip install -r requirements.txt` (Windows: `.venv\Scripts\python.exe`) |
-| Editable install | same interpreter: `-m pip install -e .` |
+| Install deps | `python -m pip install -r requirements.txt` |
+| Editable install | `python -m pip install -e .` |
+
+Datasets are loaded through the repository data helpers and cached under the
+project data directory. Experiment outputs are written under the configured
+`out_dir`, usually an ignored experiment-output directory. Keep generated
+results out of source commits unless a document explicitly asks for a summary
+or fixture.
 
 ### Verify
 
@@ -47,6 +76,15 @@ Run from repository root. Python 3.11 recommended.
 | Vision CLI | `python run_vision_experiment.py --help` |
 | Suite CLI | `python run_vision_suite.py --help` |
 
+### Run Paths
+
+| Path | Use When | Entrypoint |
+|---|---|---|
+| Single vision run | one assembled graph design or one baseline should be checked quickly | `python run_vision_experiment.py --config <config.json>` |
+| Vision diagnostic suite | real graph, controls, graph-free correction, and diagnostics should be compared together | `python run_vision_suite.py --config <config.json>` |
+| Cora graph ablation | graph-structured input path and summary writer should be checked | `python run_graph_ablation.py --config <config.json>` |
+| Evidence check | a produced result JSON should be checked for schema and attribution fields | `python scripts/checks/result_evidence_bundle.py <result.json> --kind single-run` |
+
 ### Smallest Graph Smoke
 
 | Step | Command |
@@ -186,7 +224,7 @@ Guide: [docs/framework/extension-guide.md](docs/framework/extension-guide.md)
 |---|---|
 | [CHANGELOG.md](CHANGELOG.md) | release notes |
 | [docs/README.md](docs/README.md) | docs index |
-| [docs/demos/graphfl-assembly-scratch.html](docs/demos/graphfl-assembly-scratch.html) | 발표용 조립식 인터랙티브 데모 |
+| [docs/demos/graphfl-assembly-scratch.html](docs/demos/graphfl-assembly-scratch.html) | graph_source, graph_mode, aggregation_target, controls, diagnostics를 실제 실행 JSON 흐름으로 조립하는 발표용 데모 |
 | [docs/structure.md](docs/structure.md) | edit routing and responsibility boundaries |
 | [docs/framework/claim.md](docs/framework/claim.md) | claim boundary |
 | [docs/framework/graph_fl_experimental_design.md](docs/framework/graph_fl_experimental_design.md) | current experimental design |

docs/README.md

@@ -3,12 +3,19 @@
 Use `framework/` for current work. Use `research/` for background notes. Use
 `archive/` only for prior direction or migration history.
 
+현재 문서는 세 갈래로 구성된다. `framework/`는 주장의 형태와 실험 설계를
+담고, `structure.md`는 실제 파일과 실행 경로를 찾는 지도 역할을 한다. 발표나
+공유가 필요할 때는 `capstone-prior-work-positioning.md`와
+`demos/graphfl-assembly-scratch.html`이 프로젝트의 의미와 조립식 구조를 가장
+빠르게 보여준다.
+
 | Document | Role |
 |---|---|
 | [README.md](README.md) (this file) | docs index and run-path checklist |
 | [structure.md](structure.md) | **detailed** repo map, scripts, tests, edit routing |
 | [removed-materials.md](removed-materials.md) | Gate 6 removals and read-only aliases |
 | [../README.md](../README.md) | install, quick start, **abbreviated** repo layout |
+| [capstone-prior-work-positioning.md](capstone-prior-work-positioning.md) | 선행연구 흐름에서 프로젝트가 자연스럽게 나오는 이유와 현재 구현 범위 |
 
 Post-Gate-6 rename/cleanup is **complete** on `main` (2026-05-22). Active policy:
 [naming-and-compatibility.md](framework/naming-and-compatibility.md).
@@ -46,6 +53,7 @@ docs/
 
 | Need | Document |
 |---|---|
+| project story / prior work position | [capstone-prior-work-positioning.md](capstone-prior-work-positioning.md) |
 | project direction | [framework/claim.md](framework/claim.md) |
 | experimental design | [framework/graph_fl_experimental_design.md](framework/graph_fl_experimental_design.md) |
 | metric definitions | [framework/graph_fl_experimental_design_appendix.md](framework/graph_fl_experimental_design_appendix.md) |
@@ -60,6 +68,9 @@ docs/
 
 ## Current Run Path
 
+All commands are repository-relative. Use the Python interpreter from the active
+environment; the docs avoid machine-specific paths.
+
 | Step | Command |
 |---|---|
 | Unit tests | `python -m unittest discover -s tests` |
@@ -69,11 +80,30 @@ docs/
 | Cora ablation smoke | `python run_graph_ablation.py --config configs/cora/ablations/graph/graph_ablation_smoke.json` |
 | Gate check | `python scripts/dev/run.py gate-check 6` |
 
+| Run Type | Role |
+|---|---|
+| single vision run | one graph design, one config, one result JSON |
+| diagnostic suite | multiple variants under one environment, used for real/control/graph-free comparison |
+| Cora ablation | graph-structured input path smoke and summary validation |
+| result evidence check | confirms schema fields needed for attribution are present |
+
+New configs should keep the chosen `track`, `dataset`, `graph_source`,
+`graph_mode`, `aggregation_target`, `correction_family`, controls, and
+diagnostics explicit. This makes the result readable later without relying on
+local notes or unstated defaults.
+
 ## Presentation Demo
 
 | Artifact | Purpose |
 |---|---|
-| [demos/graphfl-assembly-scratch.html](demos/graphfl-assembly-scratch.html) | 발표용 Scratch-style lifecycle 조립 데모 (브라우저에서 열기) |
+| [demos/graphfl-assembly-scratch.html](demos/graphfl-assembly-scratch.html) | graph_source, relation cue, graph_mode, aggregation target, control, diagnostic을 블록처럼 조립해 실제 config JSON 흐름으로 보여주는 발표용 데모 |
+
+이 데모는 repo 실행 축과 맞춘 시각적 조립 화면이다. palette의 주요 블록은 현재
+`graphfl_lab`의 실행 축을 따르며, custom dataset/config/graph component 이름을
+직접 넣어 새 graph 후보를 같은 구조에 얹는 흐름을 보여준다. 비교 열은 같은
+환경에서 real graph, controls, graph-free correction을 나란히 놓는 방식으로
+자라며, 발표에서는 “그래프가 효과가 있었는가”와 “그렇다면 어떤 구성요소 때문인가”를
+한 화면에서 설명할 수 있다.
 
 ## Document Policy
 

docs/capstone-prior-work-positioning.md

@@ -50,6 +50,12 @@ client representation
 -> shared diagnostics
 ```
 
+이 구조의 장점은 graph를 만드는 과정과 graph를 검증하는 과정을 같은 언어로
+다룬다는 데 있다. 어떤 client signal을 썼는지, relation score가 무엇인지, edge를
+어떻게 남겼는지, graph가 update와 weight 중 어디에 작용했는지가 분리된다. 새
+방법이 나와도 바뀐 부품을 같은 lifecycle에 연결하고, 동일한 controls와 metrics로
+비교할 수 있다.
+
 새로운 graph 후보는 이 흐름의 특정 지점에 들어간다. representation을 바꾸는
 방법, relation score를 바꾸는 방법, topology를 바꾸는 방법, aggregation target을
 바꾸는 방법이 같은 실행 구조 위에서 비교된다.
@@ -117,6 +123,12 @@ client update delta
 -> shared result schema and diagnostics
 ```
 
+현재 구현은 이 pipeline을 최소 실행 경로로 삼고, 그 위에 대체 source, topology,
+aggregation target, correction/control family를 얹는다. 발표용 assembly demo도
+같은 축을 사용한다. 화면의 블록은 `graph_source`, `graph_mode`,
+`aggregation_target`, `correction_family`, diagnostic addon으로 이어지고, 조립된
+구성은 config JSON과 실행 명령의 형태로 내려간다.
+
 조립식 확장은 이 pipeline의 특정 조각을 교체한다. classifier-head relation은
 source 교체, EMA-history relation은 source와 target 교체, RBF-style relation은
 relation score 또는 edge weight 교체, graph-free dominance control은 correction
@@ -131,6 +143,11 @@ family 교체로 표현된다.
 
 ## 4. Modular Graph Design
 
+이 프레임워크에서 graph를 만든다는 것은 하나의 adjacency matrix 생성보다 넓다.
+client를 표현하는 신호, relation을 계산하는 규칙, edge를 남기는 방식, edge
+weight와 normalization, graph를 적용할 target, control family를 각각 선택할 수
+있다. 이 조립 단위가 선행연구의 차이를 배치하는 기준이 된다.
+
 | 조립 위치 | 만들 수 있는 것 | 의미 |
 |---|---|---|
 | client representation | update delta, model weight, EMA update, classifier-head update, classifier-head weight | client를 표현하는 신호 |