docs(skills): add management-API testing recipe skill

[luvs01]

Summary

• Add a development recipe for testing the management API without treating OPENCODEX_HOME as complete isolation. A disposable OS account/home, container or VM is now a prerequisite, with the macOS .zshrc cleanup and Raycast side effects stated before startup instructions.
• Redirect each client home as well as OpenCodex state, disable integrations, use one foreground process, and keep test credentials distinct from data-plane keys. This is not a claim that a settings flag sandboxes the process.
• Correct live Lab fields to the POST request body; explain required configured providers, explicit authorization for live requests, serialized policy writes, status inspection and nonzero shutdown outcomes.
• Remove machine-specific Bun PATH assumptions, desktop-window automation and Devin session/secret notes. Keep this development recipe distinct from the existing skills/ocx/ operating reference and AGENTS_INSTALL.md consent rules.

Verification

Follow-up 987b8097624e50e6c39b00aca145fe4755043c4b is a non-force fast-forward of the existing author branch. Only the recipe file changed; no runtime code or test-home settings were executed against a personal home.

Read-only hosted verification on this exact candidate: https://github.com/luvs01/opencodex/actions/runs/36294762844/job/108551497820

• Recipe frontmatter, removed session-specific instructions and required safety/correctness statements checked.
• Relevant planner, shell integration and CLI source paths checked.
• Native Bun 1.4.0 bun run typecheck, bun run privacy:scan, bun run structure:check, and git diff --exit-code passed.

This is documentation/static verification, not an end-to-end execution of the recipe on all operating systems. The helper workflow is absent from this PR's tree and ancestry. The separate #6047 validation job in that helper run failed its documentation size gate; the #6051 job passed independently. Latest-head PR CI and independent review remain required. The choice to adopt the new .agents/skills development-recipe location remains for maintainers; this update does not make it a replacement for the operating skill root. No merge was performed.

Checklist

• Scope remains documentation-only.
• Isolation warning and management-request examples corrected.
• Static recipe checks, typecheck, privacy and structure validation passed.
• Current-head PR CI and maintainer review complete.

Summary by CodeRabbit

• Documentation
  • Added a local testing guide for the OpenCodex management API, covering isolated test environments, separate scratch directories, startup, token authentication and restrictions, automation reads and writes, and shutdown and cleanup.
  • The guide also notes that some integrations may affect files under the OS home, policy writes may conflict when run concurrently, and automation requires live providers.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: edf21550-f64f-4556-8d84-73080786d2ac

📥 Commits

Reviewing files that changed from the base of the PR and between 21ab49c and 987b809.

📒 Files selected for processing (1)

• .agents/skills/testing-opencodex-management-api/SKILL.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds a local testing guide for the OpenCodex management API. It documents isolated setup, authentication, Lab automation requests and requirements, and shutdown and cleanup steps.

Changes

Management API testing

Layer / File(s)	Summary
Isolated setup and authentication .agents/skills/testing-opencodex-management-api/SKILL.md	The guide specifies disposable environments and distinct scratch directories. It notes that some integrations can still write under the OS home. It documents foreground startup and management API token requirements.
Lab automation .agents/skills/testing-opencodex-management-api/SKILL.md	The guide covers policy and run requests, concurrent policy-write behavior, fixture-only manual runs, live-route prerequisites, and scheduler limits.
Shutdown and cleanup .agents/skills/testing-opencodex-management-api/SKILL.md	The guide describes interrupt handling, process checks, scratch-tree cleanup, and redacted result capture.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 987b8

The guide is ready to merge after normal checks; no actionable issue remains established.

Architecture Summary

Architecture risk: 🔵 Low · up to 987b8

The changed surface does not map to a changed system, dependency edge, entrypoint, or external dependency.

Changed systems: None identified.

Architecture concerns
No architecture-level concerns identified.

Review details

Before / after behavior

• observed — Modified behavior in .agents/skills/testing-opencodex-management-api/SKILL.md: Added isolation instructions requiring a disposable OS home and distinct scratch directories for OpenCodex and client homes. The guide warns that changing OPENCODEX_HOME does not redirect all client or shell-integration writes, and that disabled integrations may still remove owned artifacts; it specifies scratch configuration and cautions against relying on a single flag for isolation.
• observed — Modified behavior in .agents/skills/testing-opencodex-management-api/SKILL.md: Added startup and authentication instructions: use locked dependencies and the repository’s Bun version, start one foreground instance, and avoid detached or persistent service paths. Management requests require the generated admin token or a test-only OPENCODEX_ADMIN_AUTH_TOKEN, distinct from data-plane keys; valid authentication does not bypass route-specific requirements.
• observed — Modified behavior in .agents/skills/testing-opencodex-management-api/SKILL.md: Added Lab automation guidance covering policy and run reads, policy updates, and fixture-only manual runs. It notes that concurrent policy writers can overwrite changes, specifies request-body requirements for live-route runs and their provider and credential prerequisites, and directs testers to inspect returned status and configured scheduler limits.
• observed — Modified behavior in .agents/skills/testing-opencodex-management-api/SKILL.md: Added shutdown and cleanup instructions: send one interrupt and allow bounded cleanup, treat a second signal as forced termination, verify test-owned processes have stopped before deleting the exact scratch tree, and capture only redacted results.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and specifies that it adds a management-API testing recipe skill, which matches the pull request's primary change.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[lidge-jun]

리뷰 · 우선순위 52 / 80

관리 API를 로컬에서 시험하는 방법을 스킬 문서로 적습니다. 코드는 그대로입니다. 추가된 파일은 .agents/skills/testing-opencodex-management-api/SKILL.md 하나입니다.

OPENCODEX_HOME은 opencodex 자기 집만 옮깁니다. config.json, 관리 토큰, 실험실 상태가 거기 있습니다. Codex, Grok, Claude 집은 안 옮겨집니다. 시작하면서 진짜 ~/.codex, ~/.grok, ~/.claude에 쓸 수 있습니다. 문서가 권하는 설정은 그 연동을 끄고, 집 환경변수도 임시 폴더로 돌리라고 합니다. 관리 호출은 x-opencodex-api-key 또는 Authorization: Bearer 입니다. 실험실 자동화의 조회, 정책 저장, 수동 실행도 적습니다.

베이스는 dev입니다. types.ts / config.ts 분할이 아니라서 닫을 중복 PR은 없습니다.

라인 - 설명 첫머리, 시작 명령 근처. 설명이 "Windows + bun"입니다. bun이 PATH에 없다는 문장은 한 개발 기계의 상태를 저장소 규칙처럼 적습니다. 남는 쓰기 중 위험한 쪽은 맥의 ~/.zshrc입니다.

라인 - 잔여 쓰기 문단. 권하는 scratch 설정은 claudeCode.systemEnv를 켜지 않습니다. 맥에서는 injectSystemEnv가 주입을 건너뛰고, reconcileShellHook(false)가 진짜 ~/.zshrc에서 # opencodex claude-env hook 블록을 지웁니다. src/server/system-env-shell.ts의 reconcileShellHook은 맥이 아니면 바로 돌아갑니다. 훅이 이미 있는 개발 맥에서는 시험 시작이 그 훅을 뺍니다. 일회용 사용자로 돌리라는 문장은 그 경우에 맞습니다. 그 앞의 권장 설정만 따르면 훅이 지워집니다.

라인 - 수동 실행 문단. live_route_compatibility의 providerName과 modelId는 설정 파일이 아니라 POST /api/lab/automation/run 본문입니다. 그 이름의 공급자가 config.providers에 있어야 합니다. src/lab/automation/planner.ts의 planManualLabRun은 본문에 없으면 live manual run requires providerName and modelId로 거절합니다.

라인 - 종료 문단. Ctrl+C 한 번의 종료 코드가 항상 0은 아닙니다. src/cli/index.ts는 정리와 드레인이 둘 다 됐을 때만 0이고, 아니면 1입니다. 두 번째 신호는 500ms 뒤에 130으로 끝납니다.

라인 - shouldSyncCodexOnStart 문장. 그 함수는 clientIntegrations.codex만 보지 않습니다. src/codex/desired-state.ts에서 이 머신이 허브이고 루프백 리스너가 꺼져 있으면, 스위치가 없어도 동기화를 안 합니다. Grok도 같습니다.

라인 - 관리 토큰 문장. 환경변수에 빈 문자열이 아니면 된다는 말은, 그 값이 데이터 평면 비밀과 같으면 틀립니다. src/server/management-auth.ts의 ready는 그때 관리 API를 503으로 막습니다.

라인 - 윈도우 창 조작과 Devin Secrets Needed. super+r과 computer tool은 Devin 세션 메모입니다. 기여자 조리법이 아닙니다. 저장소가 에이전트에게 읽히라고 정한 스킬은 skills/ocx/이고, AGENTS.md에 있습니다. .agents/skills는 이 PR이 처음 만들고, 그걸 검사하는 테스트는 없습니다.

메인테이너의 판단이 필요한 지점

코딩 에이전트용 스킬 뿌리를 .agents/skills로 새로 받을지 정해 주세요. 집 격리 주의만 skills/ocx나 기여자 문서에 두고 Devin 절을 빼는 쪽도 있습니다.

동시 PUT이 한쪽 정책을 잃는다는 설명은 맞습니다. 읽기와 저장이 잠금을 따로 잡습니다. src/server/management/lab-automation-routes.ts의 PUT이 loadLabAutomationConfig와 saveLabAutomationConfig를 따로 부릅니다. 이 경주를 코드에서 고칠지, 문서 경고로 둘지 정해 주세요.

너의 추천

격리 경고는 남기세요. OPENCODEX_HOME만으로는 부족하다는 말이 이 문서에서 건질 부분입니다. 맥에서는 권장 설정이 진짜 ~/.zshrc 훅을 지운다고 앞에 적고, 그 경우는 일회용 홈으로 돌리라고 적으세요. live 실행 필드는 요청 본문으로 고치세요. 종료 코드가 항상 0이라는 문장은 빼세요. Devin 창 조작과 Secrets 절은 지우세요. 베이스는 dev로 두세요. 닫을 중복 PR은 없습니다.

이 댓글은 grok-bot이 작성했습니다

[luvs01]

Addressed the author-action review in 987b8097624e50e6c39b00aca145fe4755043c4b: disposable OS-home isolation is now a prerequisite (including macOS .zshrc cleanup), live provider/model fields are correctly shown as request-body fields, authentication requires a distinct test secret, and shutdown is no longer described as unconditionally successful. Removed Devin window-control/Secrets notes and machine-specific PATH claims. The recipe retains the established operating skill and consent references; acceptance of the new development-recipe location remains a maintainer decision.

Exact-candidate static checks, native Bun typecheck, privacy and structure checks passed in the independently successful #6051 job: https://github.com/luvs01/opencodex/actions/runs/36294762844/job/108551497820 . No personal-home execution or end-to-end cross-platform recipe run is claimed. Existing review requests are preserved; please re-review the latest head.

[luvs01]

Current-head author check follow-up for 987b8097624e50e6c39b00aca145fe4755043c4b: re-ran the cancelled label and target/description checks individually. Both now passed on their latest attempts: https://github.com/lidge-jun/opencodex/actions/runs/36294913833 and https://github.com/lidge-jun/opencodex/actions/runs/36294913800 . No recipe, runtime, test or review requirement was changed in this follow-up. Maintainer review of the development-recipe location and adoption remains separate; no PR merge was performed.

[lidge-jun]

Thank you @luvs01 for the management API test recipe. It landed on dev through #6124 (merge commit 296f0ce), with your authorship recorded in Co-authored-by trailers. The carry kept the disposable-home recipe, added Codex SQLite-home precedence and Lab-startup guidance, and linked it from AGENTS.md. Closing this PR as carried; the full review trail is on the lane PR linked from #6124.