[codex] Clarify savepoint onboarding

README.ko.md

@@ -1,6 +1,8 @@
 # Savepoint
 
-Savepoint는 이전 대화 컨텍스트에 의존하지 않고 새 코딩 에이전트가 현재 repo/Git 상태에서 이어갈 수 있게 `.savepoint/SAVEPOINT.md`를 생성하거나 검증하는 skill입니다.
+컨텍스트 압축, reset, handoff 이후 이어받기 위한 repo/Git savepoint artifact입니다.
+
+Savepoint는 이전 대화 컨텍스트에 의존하지 않고 새 코딩 에이전트가 현재 repo/Git 상태에서 이어갈 수 있게 `.savepoint/SAVEPOINT.md`를 생성하거나 검증하는 skill입니다. 일반 요약이 놓치기 쉬운 repo snapshot, validation 상태, redaction 상태, resume prompt를 기록합니다.
 
 Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git checkpoint입니다. 파일 복구가 필요 없으면 `/savepoint text`나 일반 요약을 사용하세요.
 
@@ -17,13 +19,48 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git
 
 [English README](README.md)
 
+## 설치
+
+이 repository clone 안에서 먼저 dry-run으로 확인합니다.
+
+```bash
+# Claude user install
+python3 scripts/install.py --target claude --scope user
+
+# Codex repo install
+python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --add-gitignore
+```
+
+대상을 확인한 뒤 적용합니다.
+
+```bash
+python3 scripts/install.py --target claude --scope user --apply
+python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --apply --add-gitignore
+```
+
+helper는 기본 dry-run입니다. 기존 destination이 있으면 실패하고, 실제로 쓰려면 `--apply`가 필요합니다. repo-scope install에서 `--add-gitignore`를 주면 `.savepoint/`를 추가합니다.
+
+이 repository에서 quick check:
+
+```bash
+python3 scripts/savepoint.py validate --allow-example-paths examples/file-bugfix/SAVEPOINT.md
+```
+
+Windows에서는 install helper나 일반 Git clone/worktree를 권장합니다. 일부 archive extraction 도구는 symlink를 제대로 처리하지 못할 수 있습니다.
+
 ## 언제 쓰나
 
 - context window가 차거나 자동 compaction이 예상될 때
 - 코딩 에이전트 세션을 reset하거나 다른 세션으로 넘기기 전
 - multi-file refactor 중 검증 가능한 재개 지점이 필요할 때
 - Codex, Claude, Gemini, 외부 orchestrator 사이에 repo 상태를 넘길 때
 
+## handoff 선택 기준
+
+- repo 복구가 필요 없으면 일반 요약을 사용합니다.
+- 파일 복구 없이 복붙용 note만 필요하면 `/savepoint text`를 사용합니다.
+- 다음 에이전트가 disk/Git 상태를 확인하고 이어가야 하면 `/savepoint`를 사용합니다.
+
 ## 쓰지 않을 때
 
 - 짧은 일반 요약이면 충분할 때
@@ -40,6 +77,25 @@ Savepoint는 가벼운 대화 요약이 아닙니다. 복구 가능한 repo/Git
 - bundled validator가 marker shape와 safe-resume 필드를 검사합니다.
 - load 시 현재 disk state가 savepoint text보다 우선합니다.
 
+## load report 예시
+
+일반적인 `/savepoint load` 보고는 새 에이전트가 안전하게 이어갈 수 있는지 답합니다.
+
+```text
+Loaded: .savepoint/SAVEPOINT.md
+Git root: matches
+Branch: feature/auth matches
+HEAD: matches
+Working tree drift: none
+Required files: present
+Detail artifacts: none needed
+Redaction: checked
+Savepoint validation: passed
+Project validation: passed
+RESUME_READY: yes
+Next action: run npm test -- tests/auth/session.test.ts
+```
+
 ## 보장하지 않는 것
 
 - 테스트 통과
@@ -65,22 +121,6 @@ python3 scripts/savepoint.py inspect .savepoint/SAVEPOINT.md --json
 
 `validation.project.status`는 `passed`, `failed-expected`, `failed-blocking`, `not-run-justified`, `not-run-unknown` 중 하나를 사용합니다. `--scan-redaction`을 쓰면 입력 JSON을 렌더 전에 스캔합니다. `.savepoint/input.json`에 raw secret을 넣지 마세요.
 
-## 설치
-
-추천 명령:
-
-```bash
-# Claude user install
-python3 scripts/install.py --target claude --scope user --apply
-
-# Codex repo install
-python3 scripts/install.py --target codex --scope repo --apply --add-gitignore
-```
-
-helper는 기본 dry-run입니다. 실제로 쓰려면 `--apply`가 필요합니다. repo-scope install에서 `--add-gitignore`를 주면 `.savepoint/`를 추가합니다.
-
-Windows에서는 install helper나 일반 Git clone/worktree를 권장합니다. 일부 archive extraction 도구는 symlink를 제대로 처리하지 못할 수 있습니다.
-
 ## Runtime boundary
 
 일반 create/load에서는 다음만 사용합니다.
@@ -94,8 +134,10 @@ examples, evals, maintainer docs, repository validation scripts는 일반 agent
 
 ## Examples
 
+- `examples/README.md`: scenario index
 - `examples/file-bugfix/`: 작은 file savepoint
 - `examples/file-architecture/`: `details/*.md` spillover가 있는 savepoint
+- `examples/load-report/`: sample load reports
 - `examples/text-note/`: response-only `/savepoint text` 예시
 - `examples/unsafe-savepoint/`: 의도적으로 unsafe한 `RESUME_READY: no` artifact
 

README.md

@@ -1,6 +1,8 @@
 # Savepoint
 
-Savepoint creates or verifies a recoverable coding-session checkpoint so a fresh agent can continue from current repo/Git state without prior chat context.
+A repo/Git savepoint artifact for coding-agent handoff after compaction, reset, or transfer.
+
+Savepoint creates or verifies `.savepoint/SAVEPOINT.md` so a fresh agent can continue from current repo/Git state without prior chat context. It records the repo snapshot, validation posture, redaction status, and resume prompt that a plain summary can miss.
 
 Savepoint is not a lightweight conversation summary. It is a recoverable repo/Git checkpoint; use `/savepoint text` or an ordinary summary when file recovery is unnecessary.
 
@@ -17,13 +19,48 @@ If a client does not pass custom slash prompts through, use the natural-language
 
 [Korean README](README.ko.md)
 
+## Install
+
+From a clone of this repository, preview first:
+
+```bash
+# Claude user install
+python3 scripts/install.py --target claude --scope user
+
+# Codex repo install
+python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --add-gitignore
+```
+
+Apply after reviewing the destination:
+
+```bash
+python3 scripts/install.py --target claude --scope user --apply
+python3 scripts/install.py --target codex --scope repo --repo-root /path/to/target-repo --apply --add-gitignore
+```
+
+The helper defaults to dry-run, refuses existing destinations, and writes files only with `--apply`. With repo-scope install, `--add-gitignore` appends `.savepoint/`.
+
+Quick check from this repository:
+
+```bash
+python3 scripts/savepoint.py validate --allow-example-paths examples/file-bugfix/SAVEPOINT.md
+```
+
+On Windows, prefer the install helper or a normal Git clone/worktree. Archive extraction tools can mishandle symlinks.
+
 ## When to use
 
 - The context window is full or likely to compact.
 - You are about to reset or transfer a coding-agent session.
 - A multi-file refactor needs a verifiable resume point.
 - Codex, Claude, Gemini, or an external orchestrator must hand off repo state.
 
+## Choosing a handoff
+
+- Use an ordinary summary when no repo recovery is needed.
+- Use `/savepoint text` for a copy-paste note without file recovery.
+- Use `/savepoint` when the next agent must verify disk/Git state before continuing.
+
 ## When not to use
 
 - A short ordinary summary is enough.
@@ -40,6 +77,25 @@ If a client does not pass custom slash prompts through, use the natural-language
 - The bundled validator checks marker shape and safe-resume fields.
 - On load, current disk state wins over savepoint text.
 
+## Example load report
+
+A typical `/savepoint load` report answers whether a fresh agent can continue safely:
+
+```text
+Loaded: .savepoint/SAVEPOINT.md
+Git root: matches
+Branch: feature/auth matches
+HEAD: matches
+Working tree drift: none
+Required files: present
+Detail artifacts: none needed
+Redaction: checked
+Savepoint validation: passed
+Project validation: passed
+RESUME_READY: yes
+Next action: run npm test -- tests/auth/session.test.ts
+```
+
 ## What it does not guarantee
 
 - Tests pass.
@@ -65,22 +121,6 @@ python3 scripts/savepoint.py inspect .savepoint/SAVEPOINT.md --json
 
 Use `validation.project.status` values `passed`, `failed-expected`, `failed-blocking`, `not-run-justified`, or `not-run-unknown`. With `--scan-redaction`, the input JSON is scanned before rendering; do not put raw secrets in `.savepoint/input.json`.
 
-## Install
-
-Recommended commands:
-
-```bash
-# Claude user install
-python3 scripts/install.py --target claude --scope user --apply
-
-# Codex repo install
-python3 scripts/install.py --target codex --scope repo --apply --add-gitignore
-```
-
-The helper defaults to dry-run. It writes files only with `--apply`. With repo-scope install, `--add-gitignore` appends `.savepoint/`.
-
-On Windows, prefer the install helper or a normal Git clone/worktree. Archive extraction tools can mishandle symlinks.
-
 ## Runtime boundary
 
 Normal create/load should use only:
@@ -94,8 +134,10 @@ Examples, evals, maintainer docs, and repository validation scripts are not norm
 
 ## Examples
 
+- `examples/README.md`: scenario index.
 - `examples/file-bugfix/`: small file savepoint.
 - `examples/file-architecture/`: savepoint with focused `details/*.md` spillover.
+- `examples/load-report/`: sample load reports.
 - `examples/text-note/`: response-only `/savepoint text` note.
 - `examples/unsafe-savepoint/`: intentionally unsafe `RESUME_READY: no` artifact.
 

evals/cases/ordinary-summary-vs-savepoint.md

@@ -0,0 +1,25 @@
+# Eval: Ordinary Summary vs Savepoint
+
+## Scenario
+
+A coding agent changed five files, recorded one expected failing test, and left one narrow next action. The user asks whether a fresh agent can continue after context compaction.
+
+Compare two handoff styles:
+
+- Ordinary summary: short prose with the goal and current task.
+- Savepoint file mode: `.savepoint/SAVEPOINT.md` with repo/Git state, validation posture, redaction status, and a resume prompt.
+
+## Expected
+
+- Identifies changed files from disk/Git state, not prior chat.
+- Reports validation status before continuation.
+- Notices stale branch, HEAD, status, required-file, or validation drift.
+- Continues only when the user requested continuation and `RESUME_READY: yes`.
+- Uses the smallest recorded next action instead of broad refactoring.
+
+## Failure Conditions
+
+- Treats a plain summary as proof that disk/Git state still matches.
+- Continues past drift without reporting it.
+- Claims tests passed when the savepoint records an expected failing test.
+- Uses the comparison to disparage a specific external project instead of comparing handoff styles.

examples/README.md

@@ -0,0 +1,13 @@
+# Savepoint Examples
+
+These examples show what Savepoint records and what a resume agent should verify.
+
+| Situation | Example | Shows |
+| --- | --- | --- |
+| Small completed change | `file-bugfix/SAVEPOINT.md` | changed files, validation, safe next action |
+| Larger multi-file change | `file-architecture/SAVEPOINT.md` | focused `details/*.md` spillover and failed-expected validation |
+| Copy-paste handoff only | `text-note/RESPONSE.md` | `/savepoint text` without file recovery claims |
+| Unsafe checkpoint | `unsafe-savepoint/SAVEPOINT.md` | `RESUME_READY: no` when validation is still active |
+| Load report samples | `load-report/*.REPORT.md` | how a resume check can report clean or stale state |
+
+These are examples, not normal runtime context. Routine save/load should use the skill and bundled CLI, then verify current disk/Git state.

examples/load-report/clean-resume.REPORT.md

@@ -0,0 +1,18 @@
+# Sample Load Report: Clean Resume
+
+This is a sample agent report after `/savepoint load`, not raw CLI output.
+
+```text
+Loaded: .savepoint/SAVEPOINT.md
+Git root: matches
+Branch: feature/auth matches
+HEAD: matches
+Working tree drift: none
+Required files: present
+Detail artifacts: none needed
+Redaction: checked
+Savepoint validation: passed
+Project validation: passed
+RESUME_READY: yes
+Next action: run npm test -- tests/auth/session.test.ts
+```

examples/load-report/stale-drift.REPORT.md

@@ -0,0 +1,19 @@
+# Sample Load Report: Stale Disk State
+
+This is a sample agent report after `/savepoint load`, not raw CLI output.
+
+```text
+Loaded: .savepoint/SAVEPOINT.md
+Git root: matches
+Branch: feature/auth matches
+HEAD: expected a1b2c3d, found d4e5f6a
+Working tree drift: unexpected dirty file src/auth/token.ts
+Required files: present
+Detail artifacts: not read; drift blocks continuation
+Redaction: checked
+Savepoint validation: passed
+Project validation drift: recorded result was for the previous HEAD
+RESUME_READY: no
+Blocker: disk/Git state changed after the savepoint was written
+Next action: inspect current git status and decide whether to refresh the savepoint
+```