[Improvement] Document installation, invocation context, and smoke-test handoff

[Hanjo92]

Summary / 요약

처음 사용하는 사람이 스킬 설치/등록부터 smoke test까지 따라갈 수 있도록 문서를 보강합니다.

Current Problem / 현재 문제

README는 .env 설정과 스크립트 실행부터 시작하지만, 스킬을 어디에 설치/복사하는지, agents/openai.yaml이 어디에서 소비되는지, $google-jules-control discoverability를 어떻게 확인하는지 설명이 부족합니다. 또한 python3 scripts/jules_api.py와 python3 google-jules-control/scripts/jules_api.py가 섞여 있어 실행 위치가 헷갈릴 수 있고, repo-to-source 결과를 create-session으로 넘기고 session id를 summary/cleanup에 넘기는 handoff가 copy-paste 흐름으로 보이지 않습니다.

Why It Matters / 왜 중요한가

이 스킬은 인증, 로컬 경로, 원격 Jules source, session id가 이어지는 운영 도구입니다. 첫 실행 문서가 모호하면 사용자가 잘못된 작업 디렉터리에서 .env를 만들거나, source/session 값을 잘못 넘기거나, 스킬이 등록되지 않은 상태에서 API helper만 테스트할 수 있습니다.

Proposed Change / 제안 변경

• First-time installation / registration 섹션을 추가합니다.
• agents/openai.yaml의 역할과 $google-jules-control 호출 가능 여부 확인 방법을 설명합니다.
• “skill root에서 실행하는 경우”와 “repo root에서 실행하는 경우”의 명령 예시를 구분합니다.
• smoke test를 source handoff, session id handoff, cleanup까지 end-to-end로 정리합니다.
• 예상 compact 출력 예시와 placeholder 치환 규칙을 추가합니다.

Acceptance Criteria / 완료 기준

• README 또는 setup guide에서 설치/등록/발견성 확인 절차가 설명된다.
• 실행 위치별 helper invocation 예시가 명확하다.
• smoke test가 repo-to-source → create-session → summary → cleanup 흐름으로 copy-paste 가능하다.
• .env 위치와 export 파일 위치가 target repo와 skill repo를 혼동하지 않게 안내된다.

References / 참고 자료

• README.md
• docs/setup-and-test.md
• google-jules-control/agents/openai.yaml
• google-jules-control/SKILL.md
• 분석일: 2026-04-24

[Hanjo92]

Pushed branch codex/issue-13-onboarding-smoke-test with commit faf95dc (Document Jules onboarding smoke test).

What changed:

• Added first-time installation/registration and $google-jules-control discoverability guidance.
• Clarified the role of agents/openai.yaml and separated skill repository root vs skill root invocation examples.
• Reworked the smoke test into a copy-paste handoff: repo-to-source -> create-session -> summary -> optional export -> cleanup.
• Clarified .env lookup order and export output location to avoid confusing the skill repo with the target repo.

Verification:

• git diff --check
• python3 -m py_compile google-jules-control/scripts/jules_api.py
• python3 -m unittest discover -s tests (20 tests)
• rg check for installation, invocation-context, smoke-test handoff, and path-clarity guidance