dd3ok · dd3ok · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -21,7 +21,8 @@ jobs:
       - run: python3 scripts/validate-repo.py
       - run: python3 scripts/check-savepoint-renderer.py
       - run: python3 scripts/check-install-helper.py
-      - run: python3 scripts/validate_savepoint.py --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+      - run: python3 scripts/savepoint.py validate --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+      - run: python3 -m compileall -q skills/savepoint/scripts scripts
       - name: Check committed whitespace
         shell: bash
         run: |

diff --git a/AGENTS.md b/AGENTS.md
@@ -34,6 +34,6 @@ python3 scripts/validate-examples.py
 python3 scripts/validate-repo.py
 python3 scripts/check-savepoint-renderer.py
 python3 scripts/check-install-helper.py
-python3 scripts/validate_savepoint.py --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+python3 scripts/savepoint.py validate --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
 git diff --check
 ```
diff --git a/README.ko.md b/README.ko.md
@@ -1,51 +1,106 @@
 # Savepoint
 
-코딩 에이전트를 위한 continue/load 시스템입니다.
+Savepoint는 이전 대화 컨텍스트에 의존하지 않고 새 코딩 에이전트가 현재 repo/Git 상태에서 이어갈 수 있게 `.savepoint/SAVEPOINT.md`를 생성하거나 검증하는 skill입니다.
 
-Savepoint는 새 에이전트 세션이 이전 채팅 context에 의존하지 않고 현재 코딩 작업을 이어서 불러오도록 돕습니다.
+## 30초 사용법
 
-## Prompts
-
-| Prompt | 의미 |
-|---|---|
-| `/savepoint save` | `.savepoint/SAVEPOINT.md` 생성/갱신 |
-| `/savepoint load` | 기존 Savepoint 검증/로드. 요청됐고 안전할 때만 이어서 작업 |
-| `/savepoint text` | 파일 없이 복붙용 텍스트 인계 생성 |
+```text
+/savepoint        .savepoint/SAVEPOINT.md를 생성하거나 갱신합니다.
+/savepoint save   기본 동작과 같습니다.
+/savepoint load   기존 savepoint를 검증하고 이어가기 안전 여부를 보고합니다.
+/savepoint text   복붙용 텍스트만 출력합니다. 파일 복구 보장은 없습니다.
+```
 
-네이티브 slash-command 지원 여부는 클라이언트마다 다를 수 있습니다. 클라이언트가 custom slash prompt를 모델에 전달하지 않으면 `$savepoint로 저장해줘`, `$savepoint로 로드해줘`, `$savepoint 복붙용 텍스트로 만들어줘`처럼 자연어로 사용합니다.
+클라이언트가 custom slash prompt를 모델에 전달하지 않으면 `$savepoint로 저장해줘`, `$savepoint로 로드해줘`, `$savepoint 복붙용 텍스트로 만들어줘`처럼 자연어로 요청하세요.
 
 [English README](README.md)
 
-코딩 세션 상태, repo/Git 상태, 검증, redaction, 안전한 resume이 중요하면 기본적으로 파일 기반 **Savepoint**를 사용합니다. 기존 `.savepoint/SAVEPOINT.md`에서 이어갈 때는 `/savepoint load`를 사용합니다.
+## 언제 쓰나
 
-`복붙용`, `텍스트`, `파일 없이`처럼 파일 없는 전달을 명시한 경우에만 `/savepoint text`를 사용합니다.
+- context window가 차거나 자동 compaction이 예상될 때
+- 코딩 에이전트 세션을 reset하거나 다른 세션으로 넘기기 전
+- multi-file refactor 중 검증 가능한 재개 지점이 필요할 때
+- Codex, Claude, Gemini, 외부 orchestrator 사이에 repo 상태를 넘길 때
 
-## 사용 사례
+## 쓰지 않을 때
 
-- context window가 가득 찬 코딩 에이전트 세션을 새 세션에서 이어가기
-- 자동 context compaction 이후 또는 의도적인 session reset 전에 복구 가능한 상태 남기기
-- Codex 또는 Claude 세션 사이에서 repo/Git 상태 전달하기
-- 단발성 작업을 위한 `/savepoint text` 복붙용 인계 만들기
+- 짧은 일반 요약이면 충분할 때
+- SQL `SAVEPOINT` 설명 요청일 때
+- `/status`, `/new`, compaction 정책, PTY 제어, session rotation 요청일 때
+- checkpoint 의도 없는 직접 code/docs 수정이나 savepoint라는 이름의 기능 구현 요청일 때
+- Git commit, stash, branch history가 맞는 도구일 때
 
-짧은 단순 요약만 필요하면 일반 요약이 더 저렴할 수 있습니다. 구조화된 코딩 작업 전달이나 복구가 중요할 때 savepoint를 사용하세요.
+## 보장하는 것
 
-## Savepoint Artifact
+- file mode는 `.savepoint/SAVEPOINT.md`를 씁니다.
+- artifact는 repo/Git snapshot, `## Resume Prompt`, 마지막 `SAVEPOINT_V1` marker block을 포함합니다.
+- `REDACTION_CHECKED: yes` 전에 생성된 artifact의 secret-like 값을 스캔합니다.
+- bundled validator가 marker shape와 safe-resume 필드를 검사합니다.
+- load 시 현재 disk state가 savepoint text보다 우선합니다.
 
-Savepoint는 아래 파일을 씁니다.
+## 보장하지 않는 것
 
-```text
-.savepoint/SAVEPOINT.md
+- 테스트 통과
+- 코드 정답성
+- 작업 완료
+- 미래 충돌 없음
+- text mode만으로 repo 상태를 복구할 수 있음
+
+## Runtime command
+
+public entrypoint는 다음입니다.
+
+```bash
+python3 scripts/savepoint.py save --input .savepoint/input.json --output .savepoint/SAVEPOINT.md --assert-no-active-commands --scan-redaction --validate
+python3 scripts/savepoint.py init-input --output .savepoint/input.json
+python3 scripts/savepoint.py validate .savepoint/SAVEPOINT.md
+python3 scripts/savepoint.py inspect .savepoint/SAVEPOINT.md --json
+python3 scripts/savepoint.py text --input .savepoint/input.json
+```
+
+portable skill entrypoint는 `skills/savepoint/scripts/savepoint.py`입니다. repository-local 명령은 `scripts/savepoint.py`를 사용합니다.
+
+`inspect --json`은 파일과 marker가 valid이면 `0`, savepoint-like 파일을 읽었지만 invalid이면 `1`, 파일을 읽을 수 없거나 savepoint artifact가 아니면 `2`로 종료합니다.
+
+## 설치
+
+추천 명령:
+
+```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
 ```
 
-`SAVEPOINT.md`는 `## Resume Prompt`와 마지막 `SAVEPOINT_V1` marker block을 포함합니다. field schema는 `skills/savepoint/schemas/savepoint-v1.schema.json`, marker semantics는 `docs/reference/savepoint-contract.md`에 있습니다.
+helper는 기본 dry-run입니다. 실제로 쓰려면 `--apply`가 필요합니다. repo-scope install에서 `--add-gitignore`를 주면 `.savepoint/`를 추가합니다.
+
+## Runtime boundary
+
+일반 create/load에서는 다음만 사용합니다.
+
+- `skills/savepoint/SKILL.md`
+- `skills/savepoint/scripts/savepoint.py`
+- 고급 edge case가 있을 때만 `skills/savepoint/references/*.md`
+- marker schema를 debug할 때만 `skills/savepoint/schemas/savepoint-v1.schema.json`
+
+examples, evals, maintainer docs, repository validation scripts는 일반 agent context가 아닙니다.
+
+## Examples
+
+- `examples/file-bugfix/`: 작은 file savepoint
+- `examples/file-architecture/`: `details/*.md` spillover가 있는 savepoint
+- `examples/text-note/`: response-only `/savepoint text` 예시
+- `examples/unsafe-savepoint/`: 의도적으로 unsafe한 `RESUME_READY: no` artifact
 
-## Maintainer Validation
+## Maintainer validation
 
-생성된 Savepoint artifact에는 `scripts/validate_savepoint.py`를 사용합니다. 이 도구는 `SAVEPOINT.md` 파일을 검증하는 portable runtime check입니다.
+생성된 artifact는 `scripts/savepoint.py validate .savepoint/SAVEPOINT.md`로 검증합니다.
 
-`scripts/validate-repo.py`는 이 저장소를 유지보수할 때만 사용합니다. packaging, examples, trigger evals, marker/schema contract를 확인합니다.
+`scripts/validate-repo.py`는 이 저장소를 유지보수할 때만 사용합니다. packaging, examples, trigger evals, marker/schema contracts를 검사합니다.
 
-저장소 변경을 커밋하기 전에는 아래 검증을 실행합니다.
+커밋 전에는 다음을 실행합니다.
 
 ```bash
 python3 scripts/check-frontmatter.py
@@ -55,6 +110,7 @@ python3 scripts/validate-examples.py
 python3 scripts/validate-repo.py
 python3 scripts/check-savepoint-renderer.py
 python3 scripts/check-install-helper.py
-python3 scripts/validate_savepoint.py --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+python3 scripts/savepoint.py validate --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+python3 -m compileall -q skills/savepoint/scripts scripts
 git diff --check
 ```
diff --git a/README.md b/README.md
@@ -1,90 +1,80 @@
 # Savepoint
 
-A continue/load system for coding agents.
+Savepoint creates or verifies a recoverable coding-session checkpoint so a fresh agent can continue from current repo/Git state without prior chat context.
 
-Savepoint helps a fresh agent session load the current coding run without relying on prior chat context.
+## 30-second usage
 
-## Prompts
+```text
+/savepoint        Create or refresh .savepoint/SAVEPOINT.md.
+/savepoint save   Same as default.
+/savepoint load   Verify an existing savepoint and report whether continuation is safe.
+/savepoint text   Print a copy-paste handoff only; no file recovery guarantee.
+```
 
-| Prompt | Meaning |
-|---|---|
-| `/savepoint save` | Create or refresh `.savepoint/SAVEPOINT.md`. |
-| `/savepoint load` | Load and verify an existing Savepoint. Continue only if requested and safe. |
-| `/savepoint text` | Produce a response-only copy-paste handoff. No file, no recovery guarantee. |
+If a client does not pass custom slash prompts through, use the natural-language equivalent: `Use $savepoint to save`, `Use $savepoint to load`, or `Use $savepoint to create a text handoff`.
 
-Native slash-command support depends on the client. If a client does not pass custom slash prompts through to the model, use the natural-language equivalent: `Use $savepoint to save`, `Use $savepoint to load`, or `Use $savepoint to create a text handoff`.
+[Korean README](README.ko.md)
 
-[한국어 README](README.ko.md)
+## When to use
 
-The file-backed Savepoint path is the default for preserving coding-session state, repo/Git state, validation, redaction, or safe resume. Use `/savepoint load` when continuing from an existing `.savepoint/SAVEPOINT.md`.
+- 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.
 
-Use `/savepoint text` only for explicit copy-paste, text, or no-file requests that do not need file recovery guarantees.
+## When not to use
 
-## Use Cases
+- A short ordinary summary is enough.
+- The user asks about SQL `SAVEPOINT`.
+- The request is only `/status`, `/new`, compaction policy, PTY control, or session rotation.
+- The user asks for direct code/docs edits without checkpoint intent, or an app feature named savepoint.
+- Git commit, stash, or branch history is the right tool.
 
-- Resume a coding-agent session after the context window is full.
-- Recover coding state after automatic context compaction or before an intentional session reset.
-- Transfer repo/Git state from one Codex or Claude session to another.
-- Create a `/savepoint text` copy-paste handoff for a quick one-off transfer.
+## What it guarantees
 
-For short one-off summaries, a plain summary may be cheaper; use savepoint when structured coding transfer or recovery matters.
+- File mode writes `.savepoint/SAVEPOINT.md`.
+- The artifact includes a repo/Git snapshot, `## Resume Prompt`, and one final `SAVEPOINT_V1` marker block.
+- Generated artifacts are scanned for secret-like values before `REDACTION_CHECKED: yes`.
+- The bundled validator checks marker shape and safe-resume fields.
+- On load, current disk state wins over savepoint text.
 
-## Why Savepoint
+## What it does not guarantee
 
-Savepoint turns open-ended discovery, inference, and retry work from free-form transfer notes into a short, structured check of Git/disk state and savepoint consistency.
+- Tests pass.
+- The code is correct.
+- The task is complete.
+- Future conflicts are impossible.
+- Repo recovery from text mode.
 
-## Savepoint Artifact
+## Runtime command
 
-Savepoints write:
+The public entrypoint is:
 
-```text
-.savepoint/SAVEPOINT.md
+```bash
+python3 scripts/savepoint.py save --input .savepoint/input.json --output .savepoint/SAVEPOINT.md --assert-no-active-commands --scan-redaction --validate
+python3 scripts/savepoint.py init-input --output .savepoint/input.json
+python3 scripts/savepoint.py validate .savepoint/SAVEPOINT.md
+python3 scripts/savepoint.py inspect .savepoint/SAVEPOINT.md --json
+python3 scripts/savepoint.py text --input .savepoint/input.json
 ```
 
-`SAVEPOINT.md` embeds `## Resume Prompt` and ends with a `SAVEPOINT_V1` marker block. The field schema lives in `skills/savepoint/schemas/savepoint-v1.schema.json`; marker semantics live in `docs/reference/savepoint-contract.md`.
-
-## Runtime Boundary
+The portable skill entrypoint is `skills/savepoint/scripts/savepoint.py`; repository-local commands use `scripts/savepoint.py`.
 
-Normal create/load uses:
+`inspect --json` exits `0` when the file and marker are valid, `1` when a savepoint-like file is parsed but invalid, and `2` when the file cannot be read or is not a savepoint artifact.
 
-- Skill router: `skills/savepoint/SKILL.md`
-- Renderer/finalizer: `skills/savepoint/scripts/render_savepoint.py`
-- Portable validator: `skills/savepoint/scripts/validate_savepoint.py`
-- Shared marker/snapshot helpers: `skills/savepoint/scripts/savepoint_contract.py`
-- Marker schema: `skills/savepoint/schemas/savepoint-v1.schema.json`
+## Install
 
-Reference docs, templates, examples, evals, orchestrators, and `scripts/validate-repo.py` are maintainer/debug assets, not normal agent context. The root `scripts/validate_savepoint.py` and `scripts/render_savepoint.py` forward to the portable runtime tools.
+Recommended commands:
 
-## Repository Layout
+```bash
+# Claude user install
+python3 scripts/install.py --target claude --scope user --apply
 
-```text
-.
-├── README.md
-├── README.ko.md
-├── SECURITY.md
-├── AGENTS.md
-├── skills/
-│   └── savepoint/
-│       ├── SKILL.md
-│       ├── LICENSE.txt
-│       ├── agents/openai.yaml
-│       ├── schemas/savepoint-v1.schema.json
-│       └── scripts/
-│           ├── render_savepoint.py
-│           ├── savepoint_contract.py
-│           └── validate_savepoint.py
-├── docs/
-│   └── reference/
-│       ├── context-packaging.md
-│       ├── savepoint-contract.md
-│       └── savepoint-template.md
-├── examples/
-├── evals/
-├── orchestrators/
-└── scripts/
+# Codex repo install
+python3 scripts/install.py --target codex --scope repo --apply --add-gitignore
 ```
 
-## Installation
+The helper defaults to dry-run. It writes files only with `--apply`. With repo-scope install, `--add-gitignore` appends `.savepoint/`.
 
 Typical skill locations:
 
@@ -93,49 +83,27 @@ Typical skill locations:
 - Claude user skill: `$HOME/.claude/skills/savepoint/`
 - Claude project skill: `<repo>/.claude/skills/savepoint/`
 
-Repo symlink example:
-
-```bash
-mkdir -p .agents/skills .claude/skills
-ln -s ../../skills/savepoint .agents/skills/savepoint
-ln -s ../../skills/savepoint .claude/skills/savepoint
-```
+## Runtime boundary
 
-Safe install helper:
+Normal create/load should use only:
 
-```bash
-python3 scripts/install.py --target claude --scope user
-python3 scripts/install.py --target codex --scope repo --apply --add-gitignore
-```
+- `skills/savepoint/SKILL.md`
+- `skills/savepoint/scripts/savepoint.py`
+- `skills/savepoint/references/*.md` only for advanced edge cases
+- `skills/savepoint/schemas/savepoint-v1.schema.json` only when debugging marker schema
 
-The helper defaults to dry-run. It writes files only with `--apply`; `--add-gitignore` is repo-scope only and appends `.savepoint/`.
+Examples, evals, maintainer docs, and repository validation scripts are not normal agent context.
 
 ## Examples
 
-- `examples/file-bugfix/`: small Savepoint.
-- `examples/file-architecture/`: Savepoint with focused `details/*.md` spillover.
+- `examples/file-bugfix/`: small file savepoint.
+- `examples/file-architecture/`: savepoint with focused `details/*.md` spillover.
 - `examples/text-note/`: response-only `/savepoint text` note.
-- `examples/unsafe-savepoint/`: intentionally unsafe Savepoint with `RESUME_READY: no`.
-
-## Maintainer Evals
-
-`evals/trigger-queries.json` records should-trigger and should-not-trigger prompts, including SQL/database `SAVEPOINT` near misses.
-
-Core expectations:
+- `examples/unsafe-savepoint/`: intentionally unsafe `RESUME_READY: no` artifact.
 
-- `/savepoint text` output is short and does not claim repo recovery.
-- Savepoint output writes `.savepoint/SAVEPOINT.md`.
-- Savepoint output embeds `## Resume Prompt`.
-- Large Savepoints use focused detail artifacts instead of bloating `SAVEPOINT.md`.
-- Load/resume verifies disk state before continuation or implementation.
-- Disk state wins over savepoint text.
-- Secrets are redacted.
-- `SAVEPOINT_V1` marker block is present and honest.
-- Unsafe state never emits `RESUME_READY: yes`.
+## Maintainer validation
 
-## Maintainer Validation
-
-Use `scripts/validate_savepoint.py` for generated Savepoint artifacts. It validates a `SAVEPOINT.md` file and is the portable runtime check.
+Use `scripts/savepoint.py validate .savepoint/SAVEPOINT.md` for generated artifacts.
 
 Use `scripts/validate-repo.py` only for maintaining this repository. It checks packaging, examples, trigger evals, and marker/schema contracts.
 
@@ -149,16 +117,11 @@ python3 scripts/validate-examples.py
 python3 scripts/validate-repo.py
 python3 scripts/check-savepoint-renderer.py
 python3 scripts/check-install-helper.py
-python3 scripts/validate_savepoint.py --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+python3 scripts/savepoint.py validate --allow-example-paths examples/SAVEPOINT.filled.example.md examples/file-bugfix/SAVEPOINT.md examples/file-architecture/SAVEPOINT.md examples/unsafe-savepoint/SAVEPOINT.md
+python3 -m compileall -q skills/savepoint/scripts scripts
 git diff --check
 ```
 
-To validate a generated Savepoint:
-
-```bash
-python3 scripts/validate_savepoint.py .savepoint/SAVEPOINT.md
-```
-
 ## Orchestrators
 
 External PTY controllers may parse the final `SAVEPOINT_V1` block and decide whether to rotate sessions. This skill only prepares file artifacts or text notes; orchestration remains outside the skill.