[codex] Document Jules onboarding and smoke-test handoff

README.md

@@ -12,6 +12,15 @@ This repository contains a skill for controlling Google Jules from an LLM agent.
   Google Jules REST API와 Jules CLI를 통해 세션 생성, 상태 조회, 후속 지시, 정리 리포트, merge 확인, 세션 종료를 수행합니다.  
   Controls Google Jules sessions through the Jules REST API and Jules CLI, including session creation, status checks, follow-up instructions, cleanup reports, merge checks, and session closure.
 
+## 설치 및 등록 / Installation And Registration
+
+- 스킬을 등록하려면 `SKILL.md`가 들어 있는 `google-jules-control/` 폴더를 에이전트의 skills 디렉터리에 둡니다. Codex에 수동으로 로컬 스킬을 설치할 때는 보통 `${CODEX_HOME:-$HOME/.codex}/skills/google-jules-control` 위치를 사용합니다.
+  To register the skill, place the `google-jules-control/` folder that contains `SKILL.md` in the agent skills directory. For manual local Codex skill installs, this usually means `${CODEX_HOME:-$HOME/.codex}/skills/google-jules-control`.
+- `google-jules-control/agents/openai.yaml`은 이 manifest를 지원하는 OpenAI 계열 에이전트가 표시 이름, 짧은 설명, 기본 프롬프트를 읽을 때 쓰는 파일입니다. Python helper가 실행 중에 읽는 설정 파일은 아닙니다.
+  `google-jules-control/agents/openai.yaml` is for OpenAI-style agents that support this manifest and need the display name, short description, and default prompt. The Python helper does not read it at runtime.
+- 등록 확인은 새 에이전트 컨텍스트에서 `$google-jules-control`을 호출해 `doctor --compact` 실행을 요청하는 방식으로 확인합니다. 인식되지 않으면 설치 위치와 `SKILL.md`의 `name: google-jules-control`을 확인합니다.
+  Verify discoverability by invoking `$google-jules-control` in a fresh agent context and asking it to run `doctor --compact`. If it is not recognized, check the install location and the `name: google-jules-control` front matter in `SKILL.md`.
+
 ## 저장소 구조 / Repository Layout
 
 ```text
@@ -38,25 +47,39 @@ google-jules-skill/
 
 ## 빠른 시작 / Quick Start
 
-1. `google-jules-control/.env.example`를 바탕으로 `.env`를 준비합니다.  
-   Create a `.env` file from `google-jules-control/.env.example`.
-2. `.env`에 `JULES_API_KEY`를 넣습니다.  
-   Put your `JULES_API_KEY` into `.env`.
-3. 준비 상태를 확인합니다.  
+1. 이 스킬 저장소 clone의 루트에서 시작합니다.
+   Start from the root of this skill repository clone.
+
+```bash
+cd google-jules-skill
+```
+
+2. `google-jules-control/.env.example`를 `google-jules-control/.env`로 복사합니다.
+   Copy `google-jules-control/.env.example` to `google-jules-control/.env`.
+
+```bash
+cp google-jules-control/.env.example google-jules-control/.env
+```
+
+3. `.env`에 `JULES_API_KEY`를 넣습니다. 저장소 루트 `.env`가 이미 있으면 스크립트가 그 파일을 먼저 읽으므로, 그 파일에도 `JULES_API_KEY`가 있어야 합니다.
+   Put your `JULES_API_KEY` into `.env`. If a repository-root `.env` already exists, the script reads that file first, so it must also contain `JULES_API_KEY`.
+4. 준비 상태를 확인합니다.
    Run a readiness check.
 
 ```bash
 python3 google-jules-control/scripts/jules_api.py doctor --compact
 ```
 
-4. 저장소를 Jules source로 해석합니다.  
+5. 저장소를 Jules source로 해석합니다.
    Resolve a repository to a Jules source.
 
 ```bash
 python3 google-jules-control/scripts/jules_api.py repo-to-source --repo owner/repo --compact
 ```
 
-5. 자세한 사용법은 `google-jules-control/SKILL.md`를 참고합니다.  
+6. 복사해서 따라갈 수 있는 smoke test는 `docs/setup-and-test.md`를 참고합니다.
+   For a copy-paste smoke test, read `docs/setup-and-test.md`.
+7. 자세한 사용법은 `google-jules-control/SKILL.md`를 참고합니다.
    Read `google-jules-control/SKILL.md` for the full operating guide.
 
 ## 가이드 / Guides

docs/setup-and-test.md

@@ -18,12 +18,50 @@ JULES_API_KEY=your_jules_api_key
 
 권장 위치 / Recommended locations:
 
-1. 저장소 루트 `.env` / Repository root `.env`
-2. 스킬 루트 `google-jules-control/.env` / Skill root `google-jules-control/.env`
+1. 스킬 루트 `google-jules-control/.env` / Skill root `google-jules-control/.env`
+2. 저장소 루트 `.env` / Repository root `.env`
 
 스크립트는 현재 작업 디렉토리를 먼저 보고, 없으면 스킬 루트를 봅니다.  
 The script checks the current working directory first, then the skill root.
 
+현재 작업 디렉토리에 `.env`가 이미 있으면 그 파일만 읽습니다. 그 파일에 `JULES_API_KEY`가 없으면 스킬 루트 `.env`로 자동 fallback하지 않습니다.
+If the current working directory already has `.env`, only that file is loaded. If it does not contain `JULES_API_KEY`, the helper does not fall back to the skill-root `.env`.
+
+## 설치와 호출 컨텍스트 / Install And Invocation Context
+
+`google-jules-control/` 폴더 자체가 스킬 패키지입니다. 에이전트가 스킬을 찾으려면 `SKILL.md`가 들어 있는 이 폴더를 skills 디렉터리에 등록합니다. Codex에 수동으로 로컬 스킬을 설치할 때는 보통 `${CODEX_HOME:-$HOME/.codex}/skills/google-jules-control`을 사용합니다.
+The `google-jules-control/` folder is the skill package. Register that folder, including its `SKILL.md`, in the agent skills directory. For manual local Codex skill installs, this usually means `${CODEX_HOME:-$HOME/.codex}/skills/google-jules-control`.
+
+`google-jules-control/agents/openai.yaml`은 이 manifest를 지원하는 OpenAI 계열 에이전트가 스킬 카드와 기본 프롬프트를 구성할 때 쓰는 파일입니다. `jules_api.py`의 runtime 설정은 `.env`와 CLI 인자로만 결정됩니다.
+`google-jules-control/agents/openai.yaml` is for OpenAI-style agents that support this manifest and need skill cards or default prompts. `jules_api.py` runtime behavior comes from `.env` and CLI arguments, not from that YAML file.
+
+등록 확인 / Discoverability check:
+
+```text
+Use $google-jules-control to run doctor --compact and summarize the result.
+```
+
+에이전트가 `$google-jules-control`을 모른다면 설치 위치, 폴더 이름, `SKILL.md` front matter의 `name: google-jules-control`을 확인합니다.
+If the agent does not recognize `$google-jules-control`, check the install path, folder name, and `name: google-jules-control` front matter in `SKILL.md`.
+
+스킬 저장소 루트에서 실행 / Run from this skill repository root:
+
+```bash
+python3 google-jules-control/scripts/jules_api.py doctor --compact
+python3 google-jules-control/scripts/jules_api.py repo-to-source --repo owner/repo --compact
+```
+
+스킬 루트에서 실행 / Run from the skill root:
+
+```bash
+cd google-jules-control
+python3 scripts/jules_api.py doctor --compact
+python3 scripts/jules_api.py repo-to-source --repo owner/repo --compact
+```
+
+`export --output` 경로는 현재 shell 작업 디렉토리 기준입니다. 대상 저장소와 스킬 저장소가 헷갈리면 절대 경로를 쓰거나 `pwd`로 위치를 먼저 확인합니다.
+`export --output` paths are relative to the current shell working directory. If the target repo and skill repo are easy to confuse, use an absolute path or check `pwd` first.
+
 ## 상태 점검 / Readiness Check
 
 ```bash
@@ -53,39 +91,66 @@ REST API만 쓴다면 `jules_cli=no`는 문제 아닙니다.
 
 ## 기본 스모크 테스트 / Basic Smoke Test
 
-1. 소스 목록 확인 / Verify source listing
+아래 예시는 스킬 저장소 루트에서 실행하는 copy-paste 흐름입니다. `owner/repo`와 `main`만 실제 값으로 바꿉니다.
+The example below is a copy-paste flow from this skill repository root. Replace only `owner/repo` and `main`.
+
+1. 소스 확인과 handoff 값 저장 / Resolve the source and keep the handoff value
 
 ```bash
-python3 google-jules-control/scripts/jules_api.py list-sources
+OWNER_REPO=owner/repo
+BRANCH=main
+SOURCE="$(python3 google-jules-control/scripts/jules_api.py repo-to-source --repo "$OWNER_REPO" --compact)"
+test -n "$SOURCE" || { echo "No Jules source found. Connect $OWNER_REPO in Jules, then retry."; exit 1; }
+printf '%s\n' "$SOURCE"
 ```
 
-2. 저장소를 source로 해석 / Resolve a repository
+예상 출력 / Expected output:
 
-```bash
-python3 google-jules-control/scripts/jules_api.py repo-to-source --repo owner/repo --compact
+```text
+sources/github/owner/repo
 ```
 
-3. 가벼운 테스트 세션 생성 / Create a lightweight test session
+2. 가벼운 테스트 세션 생성과 session id 저장 / Create a lightweight session and keep the session id
 
 ```bash
-python3 google-jules-control/scripts/jules_api.py create-session \
-  --source sources/github/owner/repo \
-  --branch main \
+SESSION_JSON="$(python3 google-jules-control/scripts/jules_api.py create-session \
+  --source "$SOURCE" \
+  --branch "$BRANCH" \
   --title "Smoke test" \
   --prompt "Smoke test only: inspect the repository at a high level and summarize the top-level structure without making code changes." \
-  --require-plan-approval
+  --require-plan-approval)"
+SESSION="$(printf '%s\n' "$SESSION_JSON" | python3 -c 'import json, sys; print(json.load(sys.stdin)["name"])')"
+printf '%s\n' "$SESSION"
 ```
 
-4. 세션 확인 / Check the session
+예상 출력 / Expected output:
+
+```text
+sessions/1234567890
+```
+
+3. 세션 확인 / Check the session
 
 ```bash
-python3 google-jules-control/scripts/jules_api.py summary --session sessions/SESSION_ID
+python3 google-jules-control/scripts/jules_api.py summary --session "$SESSION"
+```
+
+4. 필요하면 summary를 파일로 export / Optionally export the summary to a file
+
+```bash
+python3 google-jules-control/scripts/jules_api.py export \
+  --session "$SESSION" \
+  --kind summary \
+  --output jules-session-summary.json
 ```
 
+스킬 저장소 루트에서 실행했다면 `jules-session-summary.json`도 스킬 저장소 루트에 생기며, 대상 `owner/repo` 저장소에는 쓰이지 않습니다.
+When this is run from the skill repository root, `jules-session-summary.json` is written there, not into the target `owner/repo` repository.
+
 5. 테스트 세션 정리 / Clean up the test session
 
 ```bash
-python3 google-jules-control/scripts/jules_api.py delete-session --session sessions/SESSION_ID
+python3 google-jules-control/scripts/jules_api.py delete-session --session "$SESSION"
 ```
 
 ## 자주 쓰는 명령 / Common Commands

google-jules-control/SKILL.md

@@ -9,6 +9,8 @@ Use this skill to delegate coding work to Google Jules from an agentic workflow.
 
 ## Quick Start
 
+The command examples in this file assume your shell is in the skill root (`google-jules-control/`). From this skill repository root, prefix script paths with `google-jules-control/`, for example `python3 google-jules-control/scripts/jules_api.py doctor --compact`.
+
 1. Verify one control path is available.
    - API path: put `JULES_API_KEY` in a `.env` file from `https://jules.google.com/settings`.
    - CLI path: install `@google/jules`, then run `jules login`.
@@ -526,7 +528,7 @@ You can start from `.env.example`.
 
 `.gitignore` excludes `.env`, so the real key file is less likely to be committed by accident.
 
-The script auto-loads `.env` from the current working directory first, then from the skill root.
+The script auto-loads `.env` from the current working directory first, then from the skill root. If the current working directory has `.env`, that file must contain `JULES_API_KEY`; the helper does not merge it with the skill-root `.env`.
 
 ## Read More Only When Needed