docs(skill): keep hub invite grants outside agent transcripts

[luvs01]

Summary

The operating skill tells an agent to execute ocx hub invite --json and relay the generated command, even though the output contains a one-time pairing grant. Update the entrypoint, invite recipe and remote-hub reference to hand that secret-returning step to an operator terminal and keep both the grant and generated command out of chat.

The agent still performs non-secret setup and verification, using expiry and bound browser origin for confirmation. This is guidance only: it does not change CLI behavior or introduce a technical enforcement boundary.

Verification

• bun test tests/ci-workflows/skill-ocx.test.ts: 16 pass, 0 fail, 227 assertions.
• bun run skill:surface:check, bun run structure:check, bun run privacy:scan, and git diff --check: passed.
• Skill Creator quick_validate.py: passed with UTF-8 input mode.
• Verified both invite output branches in src/cli/hub.ts and manually checked all three changed pages. No live pairing grant was minted.
• Existing checks cover skill structure and declared commands; they do not prove that every agent will follow the guidance. Exact-head Cross-platform CI 34760729556 passed all 26 jobs on this head. Attempt 1 failed only in the Windows 3/6 teardown, where removing an isolated auth-context temporary directory returned EPERM with no assertion failure; rerunning the failed jobs once produced a clean run, and the same focused test also passes locally on this head. Current dev is 32 commits ahead, so the latest-dev box stays unticked and this remains Draft rather than presenting a stale base as review-ready.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness evidence

Rebased onto dev at 15fbd49f3 and pushed. Published head is 3a45afe6a.

Local verification on that head: bun run typecheck, bun run structure:check, bun run privacy:scan and git diff --check all pass. This branch changes no source or test files; the diff is documentation under skills/ocx/, so the repository gates above are the applicable local checks.

The earlier head a6b1e93b completed hosted cross-platform CI green, 26 of 26 jobs, in run 34760729556 attempt 2. This head carries the same documentation content rebased onto newer dev, with a redundant self-referential Co-authored-by trailer removed from the commit message; the tree is otherwise unchanged.

Hosted cross-platform CI has not been re-dispatched on this head. On current dev the windows shard fails independently of this pull request in tests/clients/desktop-app-restart-posix.test.ts, a dev regression fixed separately in #4564. That failure is not attributable to a documentation-only change.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Documentation
  • Updated hub invitation guidance to require running the invite command in a human-operated terminal outside the agent session.
  • Clarified that command output contains a plaintext pairing grant and must not be exposed in agent transcripts.
  • Removed instructions to use JSON output as an agent-safe alternative.
  • Added guidance to share only non-secret confirmation details, such as expiry and browser-origin status.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 5a024a0f-95d5-45a2-8965-4bf990f05920

📥 Commits

Reviewing files that changed from the base of the PR and between 0a62878 and 4f62d29.

📒 Files selected for processing (3)

• skills/ocx/SKILL.md
• skills/ocx/references/03_recipes.md
• skills/ocx/references/05_remote_hub.md

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation now treats ocx hub invite output as secret-bearing. Operators must run it outside the agent session and transfer the printed command directly to the joining machine. Agents may request only non-secret verification details.

Changes

Hub invitation guidance

Layer / File(s)	Summary
Secret output policy and recipe skills/ocx/SKILL.md, skills/ocx/references/03_recipes.md	The documentation identifies plaintext pairing grants in text and JSON output. Recipe 10 now requires human-operated execution and limits agent-requested confirmation to expiry and the Bound browser origin: line.
Remote-hub handoff skills/ocx/SKILL.md, skills/ocx/references/05_remote_hub.md	The guidance requires execution outside the agent session. It prohibits relaying secret-bearing output and identifies the browser origin and expiry as non-secret verification details.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 4f62d

This documentation-only change keeps pairing grants out of agent transcripts without changing CLI behavior, so no merge-blocking risk is identified.

🚥 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 and concisely describes the main documentation change: keeping hub invite pairing grants outside agent transcripts.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request has been marked Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers notified: @lidge-jun @Ingwannu

[lidge-jun]

리뷰 · 우선순위 65 / 80

설명
이 PR(초안)은 ocx 스킬 문서에서 ocx hub invite가 만들어 내는 일회용 페어링 grant·명령줄을 에이전트 트랜스크립트에 넣지 말라고 바꿉니다. CLI 동작은 그대로이고, 안내만 바꿉니다. tip(d7c7b493b)의 스킬은 아직 “에이전트가 hub에서 ocx hub invite를 실행하고 명령줄을 넘긴다”는 톤입니다. 키 회전에 대해선 이미 “시크릿 반환 단계는 사람 터미널로”라고 막아 두었는데, invite는 같은 경계를 hub invite에도 확장합니다.

바뀌는 곳은 세 파일입니다. skills/ocx/SKILL.md 엔트리포인트에 invite 경계를 키 회전과 나란히 적고, 허브 설명도 “오퍼레이터가 세션 밖에서 실행”으로 고칩니다. skills/ocx/references/03_recipes.md 레시피 10은 ocx status로 비밀 아닌 상태만 본 뒤, invite·명령줄은 사람 터미널로 돌리게 합니다. --json도 에이전트용 안전 출력이 아니라고 명시합니다. skills/ocx/references/05_remote_hub.md도 같은 손으로 옮기고, stderr의 Bound browser origin:은 비밀이 아니라 확인용이라고 정리합니다.

tip 방향(보안·운영 실수 줄이기, hub/원격)과 잘 맞습니다. 기술 강제(에이전트가 명령을 아예 못 돌리게 막는 것)는 없고 가이드만이라, 에이전트가 무시하면 그대로 새어 나갈 수 있습니다. 본문도 그걸 인정합니다. 초안(draft)이고, 체크리스트에 로컬 전체 CI·Codex/CodeRabbit 해결이 비어 있습니다. 스킬 테스트·surface/structure/privacy는 통과했다고 합니다.

skills/ocx/SKILL.md - invite를 키 회전과 같은 “사람 터미널 핸드오프”로 묶습니다. tip의 기존 문장(“Run ocx hub invite on the hub”)을 바꾸는 방향이 맞습니다.
skills/ocx/references/03_recipes.md - 레시피 10에서 ocx hub invite --json 예시 블록을 제거한 것은 좋습니다. 다만 오퍼레이터가 실제로 칠 명령 예시가 본문에 약해지면, 사람이 다시 손으로 ocx connect를 조립할 수 있습니다. “세션 밖 터미널에서 ocx hub invite” 한 줄 예시는 남겨 두는 편이 덜 헷갈립니다.
skills/ocx/references/05_remote_hub.md - placeholder를 “라이브 grant를 중계하라는 뜻이 아님”으로 못 박은 것은 명확합니다.
경로/심볼 - 가이드만이라 강제력이 없습니다. 에이전트가 그래도 invite를 돌리면 grant가 채팅에 남을 수 있습니다. CLI에 soft-warn을 넣을지는 별 결정입니다.
경로/심볼 - draft 상태입니다. ready 전에 tip rebase와 호스티드 체크를 맞추세요.

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

• 문서 가이드만으로 충분한지, CLI/ocx hub invite에 “에이전트 세션 감지 시 경고” 같은 soft guard를 후속으로 넣을지.
• 레시피에 오퍼레이터용 최소 명령 예시를 다시 한 줄 넣을지.
• draft를 ready로 올리기 전에 스킬 회귀 테스트 외에 전체 CI를 필수로 둘지.

너의 추천
방향은 맞고 tip에도 바로 들어갈 만합니다. 레시피 10에 “오퍼레이터 터미널: ocx hub invite” 한 줄 예시만 보강한 뒤 undraft하고, CI 초록이면 머지하세요. CLI 강제 경고는 이 PR 범위 밖으로 두고 후속으로 여는 걸 추천합니다.

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

[luvs01]

Thanks for checking the operator handoff. The requested one-line command is already present in the published head a6b1e93: recipe 10 says, “Have the operator run ocx hub invite in a human-operated terminal outside the agent session.” The following paragraph directs the operator to transfer the generated command directly and explicitly says not to assemble it by hand or put it in chat. I kept the command as inline prose so it is clearly an operator action, rather than an agent-executable recipe block. No CLI enforcement change is included.

Validation update: the exact-head Cross-platform CI run 34760729556 failed only in the Windows 3/6 test teardown when removal of an isolated auth-context temporary directory returned EPERM. The same focused test passes locally on that head. A single rerun of the failed jobs is in progress; I am not marking full CI green yet. The branch is also beyond the latest-dev tolerance, so it remains Draft rather than invalidating the current run with an immediate rebase.