Consolidate repository documentation

Author: 2-mean

.gitattributes

@@ -5,3 +5,4 @@
 *.toml text eol=lf
 *.txt text eol=lf
 *.yml text eol=lf
+*.html text eol=lf

.gitignore

@@ -59,3 +59,6 @@ Thumbs.db
 .vscode/
 .idea/
 .ipynb_checkpoints/
+
+# Local preserved docs and legacy scratch material
+/local_archive/

CHANGELOG.md

@@ -4,9 +4,9 @@
 
 | 영역 | 변경 |
 |---|---|
-| package | canonical package를 `graphfl_lab`으로 통일 |
+| package | canonical package를 `graphfl_lab`로 통일 |
 | Flower app | Flower app path를 `graphfl_lab` 기준으로 정리 |
-| legacy surface | `spectral_fl`, `run_general_*`, `general_*` facade 제거 |
-| vision artifact | 새 결과명을 `result_vision_*`, `vision_suite_*`로 표준화 |
+| legacy surface | `spectral_fl`, `run_general_*`, `general_*` facade 정리 |
+| vision artifact | 결과 이름을 `result_vision_*`, `vision_suite_*`로 표준화 |
 | compatibility | 과거 JSON/config 입력을 위한 read-only alias 유지 |
 | unified runner | `run_experiment.py --track vision|cora` surface 추가 |

MIGRATION.md

@@ -1,12 +1,13 @@
 # GraphFL Lab Migration
 
-`graphfl_lab`가 canonical package다. Gate 6 cleanup과 public rename은 release `1.0.0`에서 완료되었다.
+`graphfl_lab`가 canonical package다. Public rename과 cleanup은 release `1.0.0` 기준으로 정리되었다.
 
 ## Canonical Surface
 
-| 영역 | Canonical |
+| Area | Canonical |
 |---|---|
 | package | `graphfl_lab` |
+| Flower app | `graphfl_lab.flower_app:server_app`, `graphfl_lab.flower_app:client_app` |
 | vision runner | `run_vision_*` |
 | unified runner | `run_experiment.py --track vision|cora` |
 | vision result | `result_vision_*` |
@@ -16,24 +17,29 @@
 
 ## Compatibility Alias
 
-| Legacy | Current |
-|---|---|
-| `configs/general/...` | `configs/vision/...` path alias |
-| `spectral_filter_strength` | JSON read alias for `graph_filter_strength` |
-| `spectral_filtered_*` | aggregation input alias |
-| `ours_spectral_filtered_*` | historical reporting tag |
+| Legacy | Current | Role |
+|---|---|---|
+| `configs/general/...` | `configs/vision/...` path alias | old config path read support |
+| `spectral_filter_strength` | JSON read alias for `graph_filter_strength` | old config key read support |
+| `spectral_filtered_*` | aggregation input alias | old target naming read support |
+| `ours_spectral_filtered_*` | historical reporting tag | old artifact/report parse support |
+| diagnostic trace key `spectral_filter_gain_*` | metric field name | old diagnostic field parse support |
 
 ## Removed Surface
 
 | Removed | Replacement |
 |---|---|
 | `spectral_fl` package shim | `graphfl_lab` |
-| `run_general_*` | `run_vision_*` |
+| `run_general_*` root entrypoints | `run_vision_*` |
 | `graphfl_lab/experiments/general/` | `graphfl_lab/experiments/vision/` |
 | `graphfl_lab/experiments/suites/general/` | `graphfl_lab/experiments/suites/vision/` |
+| `graphfl_lab/strategies/spectral/` facade | `graphfl_lab/strategies/graphfl/` |
+| `graphfl_lab/general_*`, `graphfl_lab/cli/general_*` | vision modules and unified runner |
 | `general_suite_*` artifact readers/writers | `vision_suite_*` |
 | `result_general_*` artifact readers/writers | `result_vision_*` |
+| CLI `spectral_filtered_*` choices | `graph_filtered_*` |
+| `--spectral-filter-strength` | `--graph-filter-strength` |
 
-## Canonical
+## Canonical Reference
 
-세부 migration, compatibility, gate-check contract는 `docs/maintenance/migration-and-compatibility.md`에서 관리한다.
+상세 migration, compatibility, removed-surface, golden baseline, serialized asset policy는 `docs/maintenance.md`에서 관리한다.

README.md

@@ -1,48 +1,109 @@
 # Graph-FL Design Lab
 
-Graph-FL Design Lab은 client update와 model state로 client graph를 만들고, matched control graph와 diagnostic metric으로 Graph-FL gain의 원인을 분해하는 실험 framework다.
+Graph-FL Design Lab는 Graph-FL gain이 실제 client relation graph에서 오는지 검증하기 위한 실험 framework다. 이 repository는 federated learning 실험, graph construction, matched controls, graph-free controls, diagnostics, Evidence artifact를 한 구조로 묶어 Graph-FL claim을 재현 가능한 표와 수치로 설명한다.
 
-핵심 질문:
+## Project Overview
+
+Graph-FL 계열 방법은 client 사이의 relation graph를 이용해 aggregation 또는 personalization을 바꾼다. 그러나 성능 향상은 relation graph 자체가 아니라 smoothing, dominance correction, clustering, optimizer 차이에서도 생길 수 있다. 이 repository의 목적은 그 효과를 분리해서 측정하는 것이다.
+
+| 질문 | Repository 기준 답 |
+|---|---|
+| Graph-FL gain은 어디서 오는가 | `graph_source`, `graph_mode`, `aggregation_target`, `correction_family`를 분리해 비교 |
+| real graph가 control보다 의미 있는가 | random, shuffled, uniform, identity, graph-free controls와 같은 artifact row에서 비교 |
+| prior work mechanism을 설명할 수 있는가 | FedAMP, SFL, pFedGraph, FedAGA mechanism을 component slot으로 매핑 |
+| metric이 해석 가능한가 | `DI`, `N_eff`, alignment, `LOO`, graph stats를 round/client/counterfactual artifact로 기록 |
+| framework로 확장 가능한가 | custom source, builder, preset, target이 trace와 artifact contract를 통과하는지 검증 |
+
+핵심 claim:
 
 ```text
-Graph-FL gain이 실제 client relation structure에서 오는가,
-아니면 dominance, norm, smoothing, optimizer effect로 설명되는가?
+Graph-FL gain
+= relation-specific effect
++ generic smoothing effect
++ clustering effect
++ dominance/norm correction effect
++ optimizer effect
 ```
 
-## 핵심 구조
+## Repository Contents
+
+| Area | Role | Main Paths |
+|---|---|---|
+| Graph-FL runtime | graph-aware aggregation과 diagnostics 실행 | `graphfl_lab/strategies/graphfl/`, `graphfl_lab/lifecycle/` |
+| graph construction | client state를 relation graph로 변환 | `graphfl_lab/graph/`, `graphfl_lab/designs/` |
+| diagnostics/artifacts | metric schema와 CSV/JSON row 작성 | `graphfl_lab/diagnostics/` |
+| experiment tracks | vision Non-IID, Cora graph ablation 실행 | `graphfl_lab/experiments/`, `run_experiment.py` |
+| Evidence pack | framework validity 검증 | `graphfl_lab/validation/`, `scripts/validation/` |
+| configs | tracked experiment presets | `configs/vision/`, `configs/cora/` |
+| tests | component, strategy, experiment, validation contract | `tests/` |
+| docs/demo | framework 설명, Evidence, repository layout, HTML demo | `docs/`, `docs/demos/graphfl-assembly-scratch.html` |
+
+## Framework Flow
+
+```text
+client local training
+├── graph_source              client state -> representation z_i
+├── graph_mode                relation score + topology -> adjacency A
+├── aggregation_target        graph filtering -> update / EMA update / weight
+├── correction_family         real graph vs matched controls
+├── diagnostics               DI, N_eff, alignment, LOO, graph stats
+└── artifact contract         round/client/graph/counterfactual/Evidence rows
+```
 
 | Layer | 역할 |
 |---|---|
-| `graph_source` | client를 update, weight, EMA, classifier head 등으로 표현 |
-| `graph_mode` | relation score와 topology 구성 |
-| `aggregation_target` | graph를 update, EMA update, weight 등에 적용 |
-| `correction_family` | real graph, random, shuffled, uniform, identity, graph-free control 비교 |
+| `graph_source` | client를 update, weight, EMA update, classifier-head update로 표현 |
+| `graph_mode` | relation score와 topology를 adjacency로 구성 |
+| `aggregation_target` | graph filtering을 update, EMA update, weight에 적용 |
+| `correction_family` | real graph를 random, shuffled, uniform, identity, clustering-only, graph-free control과 비교 |
 | `diagnostics` | alignment, `DI`, `N_eff`, `LOO`, graph metric 기록 |
 
-## Evidence Claim
+## Evidence Snapshot
+
+| Evidence Axis | Verdict | Primary Artifact |
+|---|---|---|
+| construction drift | 18 graph modes pass, max abs diff `2.21e-12`, edge F1 `1.0` | `graph_parity_summary.csv` |
+| paper-mechanism alignment | pFedGraph, FedAMP, SFL, FedAGA mapping 5 / 5 rows pass | `external_mechanism_alignment.csv` |
+| diagnostic sensitivity | 60 framework diagnostic rows pass | `scenario_manifest.json`, `metric_validity_summary.csv` |
+| design-space coverage | 16 sources x 18 modes x 5 targets x 6 correction profiles = 8,640 / 8,640 checks pass | `design_space_matrix.csv`, `design_space_summary.csv` |
+| extensibility | custom source, builder, preset, target 4 / 4 contract checks pass | `extension_contract_summary.csv` |
+| measurement integrity | real/random/uniform measured nonzero, identity expected-zero control | `real_diagnostic_consistency.csv` |
+
+Evidence의 의미:
 
-| Claim | Evidence |
+| Claim | Repository Evidence |
 |---|---|
-| graph construction 재현성 | `graph_parity_summary.csv`, edge F1, drift |
-| paper mechanism 대응 | `external_mechanism_alignment.csv` |
-| diagnostic sensitivity | `scenario_manifest.json`, `metric_validity_summary.csv` |
-| design-space coverage | `design_space_matrix.csv`, `design_space_summary.csv` |
-| extensibility | `extension_contract_summary.csv` |
+| graph semantics 보존 | lifecycle assembly와 reference builder drift 비교 |
+| paper mechanism 대응 | prior work mechanism을 component slot으로 매핑 |
+| metric 해석 가능성 | synthetic expected-direction check와 real/control consistency |
+| framework 조합성 | built-in design space 전체 row-level calculation check |
+| 확장 가능성 | custom component가 trace, metadata, diagnostics, artifact contract를 보존 |
 
-Framework-quality 근거는 `docs/framework/evidence.md`에 정리한다.
+## Primary Artifacts
 
-## 문서 지도
+| Artifact | 내용 |
+|---|---|
+| `round_metrics.csv` | round-level pre/post aggregate, `DI`, `N_eff`, alignment, `LOO` |
+| `client_metrics.csv` | client contribution, update norm, alignment |
+| `graph_stats.csv` | density, degree, entropy, spectral graph metrics |
+| `counterfactual_metrics.csv` | real graph와 control graph gap |
+| `metric_validity_summary.csv` | synthetic expected-direction result |
+| `design_space_matrix.csv` | source/mode/target/control/diagnostic row validity |
+| `extension_contract_summary.csv` | custom component trace와 artifact preservation |
+
+## Main Run Paths
 
-| 문서 | 용도 |
+| 목적 | Command |
 |---|---|
-| `docs/framework/overview.md` | project claim, research position, experiment design |
-| `docs/framework/metrics.md` | metric 정의, 수식, diagnostic 해석 |
-| `docs/framework/components.md` | lifecycle, interface, extension guide, prior-work mapping |
-| `docs/framework/evidence.md` | framework-quality evidence와 provenance |
-| `docs/maintenance/migration-and-compatibility.md` | migration, compatibility, gate-check contract |
-| `docs/archive/README.md` | archive summary |
+| unified runner help | `python run_experiment.py --help` |
+| vision single run | `python run_vision_experiment.py --config configs/vision/smoke/default_similarity_knn.json` |
+| vision suite | `python run_vision_suite.py --config configs/vision/diagnostic/smoke/default.json` |
+| vision stress grid | `python run_vision_stress_grid.py --help` |
+| vision client-count sweep | `python run_vision_client_count_sweep.py --help` |
+| Cora graph ablation | `python run_graph_ablation.py --config configs/cora/ablations/graph/graph_ablation_smoke.json` |
+| Evidence report | `python scripts/validation/graph_evidence_report.py --profile smoke --include-external --out-dir <out-dir>` |
 
-## 설치
+## Install
 
 Repository root에서 실행한다.
 
@@ -51,41 +112,57 @@ Repository root에서 실행한다.
 | dependency 설치 | `python -m pip install -r requirements.txt` |
 | editable install | `python -m pip install -e .` |
 
-## 검증
+## Verification
 
 | Check | Command |
 |---|---|
 | unit tests | `python -m unittest discover -s tests` |
 | vision CLI | `python run_vision_experiment.py --help` |
 | suite CLI | `python run_vision_suite.py --help` |
-| evidence report | `python scripts/validation/graph_evidence_report.py --profile smoke --include-external --out-dir <out-dir>` |
+| Evidence report | `python scripts/validation/graph_evidence_report.py --profile smoke --include-external --out-dir <out-dir>` |
 
-## 주요 실행 경로
+## Documentation
 
-| 목적 | Command |
+| Document | 내용 |
 |---|---|
-| vision single run | `python run_vision_experiment.py --config configs/vision/smoke/default_similarity_knn.json` |
-| vision suite | `python run_vision_suite.py --config configs/vision/diagnostic/smoke/default.json` |
-| Cora graph ablation | `python run_graph_ablation.py --config configs/cora/ablations/graph/graph_ablation_smoke.json` |
+| `docs/README.md` | 문서 index |
+| `docs/framework.md` | framework claim, lifecycle, components, metric |
+| `docs/evidence.md` | framework 정당성 실험, pass criteria, verdict, provenance |
+| `docs/research.md` | prior work positioning, design pattern survey |
+| `docs/repository.md` | repository tree, package/script/test layout, change routing |
+| `docs/maintenance.md` | migration, compatibility, removed surface, golden/asset policy |
+| `docs/history.md` | legacy experiment observation, migration phase 기록 |
+| `docs/demos/graphfl-assembly-scratch.html` | Graph-FL assembly scratch demo |
 
-## Repository 구조
+## Repository Layout
 
 ```text
-graphfl_lab/
-├── designs/                 GraphFLDesign registry and presets
-├── graph/                   graph source, builder, control, diagnostics
-├── lifecycle/               lifecycle contracts and traces
-├── strategies/graphfl/      Graph-FL runtime strategy
-├── diagnostics/             result schema and artifact writers
-└── experiments/             vision and Cora orchestration
-
-configs/
-├── vision/
-└── cora/
-
-docs/
-├── framework/
-├── research/
-├── maintenance/
-└── archive/
+.
+├── graphfl_lab/
+│   ├── designs/              GraphFLDesign registry and presets
+│   ├── graph/                graph source, builder, control, diagnostics
+│   ├── lifecycle/            lifecycle contracts and traces
+│   ├── strategies/
+│   │   ├── baselines/        graph-free and baseline strategies
+│   │   └── graphfl/          Graph-FL runtime strategy modules
+│   ├── diagnostics/          result schema and artifact writers
+│   ├── experiments/
+│   │   ├── vision/           vision single run, suite, stress, sweeps
+│   │   ├── cora/             Cora single run and graph ablation
+│   │   └── suites/vision/    suite features, variants, reporting
+│   └── validation/           Evidence pack validation logic
+├── configs/
+│   ├── vision/               baseline, diagnostic, probe, smoke, stress, sweep configs
+│   └── cora/                 graph ablation configs
+├── scripts/
+│   ├── checks/               preflight, evidence bundle, parity checks
+│   ├── validation/           Evidence pack entry points
+│   ├── reports/              plot and dashboard helpers
+│   └── smoke/                smoke command wrappers
+├── tests/                    CLI, graph, lifecycle, strategy, experiment, validation tests
+└── docs/
+    ├── *.md                  canonical project documentation
+    └── demos/                HTML demo artifacts
 ```
+
+상세 layout과 change routing은 `docs/repository.md`에서 관리한다.

configs/README.md

@@ -1,35 +1,48 @@
 # Config
 
+`configs/`는 tracked experiment preset의 canonical 위치다. Vision track은 `configs/vision/`, Cora graph ablation은 `configs/cora/`를 사용한다.
+
 ## Canonical Tree
 
 ```text
-configs/vision/
-configs/cora/
+configs/
+├── vision/
+│   ├── baselines/
+│   ├── diagnostic/
+│   │   ├── smoke/
+│   │   ├── core/
+│   │   └── extend/
+│   ├── probes/
+│   ├── smoke/
+│   ├── stress/
+│   └── sweeps/
+└── cora/
+    └── ablations/
 ```
 
-## Vision Config Group
+## Vision Config Groups
 
-| Folder | 용도 |
+| Folder | Purpose |
 |---|---|
-| `configs/vision/diagnostic/smoke/` | 빠른 diagnostic smoke |
-| `configs/vision/diagnostic/core/` | 핵심 diagnostic suite |
-| `configs/vision/diagnostic/extend/` | 확장 diagnostic 설정 |
-| `configs/vision/probes/` | graph/source/target probe |
-| `configs/vision/stress/` | Non-IID stress 설정 |
-| `configs/vision/sweeps/` | sweep 설정 |
+| `configs/vision/diagnostic/smoke/` | quick diagnostic smoke |
+| `configs/vision/diagnostic/core/` | core diagnostic suite |
+| `configs/vision/diagnostic/extend/` | extension diagnostic configs |
+| `configs/vision/probes/` | graph/source/target probes |
+| `configs/vision/stress/` | Non-IID stress configs |
+| `configs/vision/sweeps/` | sweep configs |
 
-## Cora Config Group
+## Cora Config Groups
 
-| Folder | 용도 |
+| Folder | Purpose |
 |---|---|
 | `configs/cora/ablations/` | Cora graph ablation |
 
 ## Compatibility
 
-| Legacy | Current |
-|---|---|
-| `configs/general/...` | `configs/vision/...` path alias |
-| `general_suite_*` | `vision_suite_*` |
-| `result_general_*` | `result_vision_*` |
+| Legacy | Current | Role |
+|---|---|---|
+| `configs/general/...` | `configs/vision/...` path alias | old path read support |
+| `general_suite_*` | `vision_suite_*` | old suite artifact parse support |
+| `result_general_*` | `result_vision_*` | old result artifact parse support |
 
-세부 compatibility 정책은 `docs/removed-materials.md`에 기록한다.
+상세 compatibility policy는 `docs/maintenance.md`에서 관리한다.