polydeukes 0.6.1 → 0.8.0

package/dist/docs/reference/cli/init.ko.md

@@ -2,85 +2,118 @@
 
 [English](./init.md) · **한국어**
 
-프로젝트를 세션 표면에 연결합니다. `claude-code`와 `grok` 두 형식 모두 대상 프로젝트에서
-설치된 패키지를 찾을 수 있는지 먼저 검사합니다. 그 검사가 끝나기 전에는 파일을 쓰지 않습니다.
+`pdks init`은 에이전트와 무관한 초기 파일을 만듭니다. 설정 파일과 텔레메트리 제외 항목
+둘입니다. 이 명령은 어느 에이전트도 알지 못합니다. 세션 표면 등록은 그 에이전트의 어댑터가
+맡는 별도 명령입니다. Claude Code는 `pdks-claude-code init`, Grok는 `pdks-grok init`,
+Codex는 `pdks-codex init`입니다.
 
 <a id="init-syntax"></a>
 ## 구문
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
 ```
 
-두 형식 모두 다시 실행할 수 있습니다. 이미 있는 산출물은 보존하고 `skipped`로 보고합니다.
-사전 검사에 실패하면 파일을 쓰지 않고 종료 코드 `2`를 반환합니다.
+다른 인자를 주면 사용법을 출력하고 종료 코드 `2`를 반환합니다. 이미 있는 산출물은 보존하고
+`skipped`로 보고하며, 사전 검사에 실패하면 파일을 쓰지 않고 종료 코드 `2`를 반환합니다.
 
 <a id="init-common"></a>
-## 공통 사전 검사와 초기 파일
+## `pdks init` — 초기 파일
 
-설치 순서는 다음과 같습니다.
+이 명령의 순서는 다음과 같습니다.
 
 1. 대상 프로젝트에서 `polydeukes`를 찾을 수 있는지 확인합니다.
 2. 공통 설정과 텔레메트리 제외 항목을 만듭니다.
-3. 표면별 등록 파일을 추가합니다.
 
-두 설치기가 공통으로 만드는 것은 `polydeukes.config.yaml`과 `.gitignore`의 `.polydeukes/`
-항목입니다. 설정 파일에는 언어 블록, 보호 목록, 증인 블록, 주석으로 된 규율 예제가 있습니다.
-완성된 정책이 아니라 프로젝트에 맞춰 고칠 출발점입니다.
+어느 표면이든 여기서 출발합니다.
+
+- `polydeukes.config.yaml`
+- `.gitignore`의 `.polydeukes/` 항목
+
+설정 파일에는 언어 블록, 보호 목록, 증인(witness) 블록, 주석으로 된 규율(discipline) 예제가
+있습니다. 완성된 정책이 아니라 프로젝트에 맞춰 고칠 출발점입니다.
 
 <a id="init-claude-code"></a>
-## `pdks init claude-code`
+## Claude Code — `pdks-claude-code init`
+
+Claude Code 세션 표면은
+[`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
 
-Claude Code 세션 표면에 필요한 파일은 다음과 같습니다.
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
 
 - `.claude/hooks/covenant-pretooluse.mjs`
 - `.claude/settings.json`
 - `.claude/rules/polydeukes.md`
 - `.claude/skills/discipline-draft/SKILL.md`
-- `polydeukes.config.yaml`
-- `.gitignore`
 
-훅은 `polydeukes/claude-code`에 판정을 맡깁니다. 설정에는 PreToolUse 등록을 병합하고,
-문서 안내 파일은 AI 파트너가 웹 검색 대신 `pdks docs`를 쓰도록 알려 줍니다.
-스킬은 설명된 규율 문제를 설정 항목으로 바꾸는 절차를 제공합니다.
+산출물별 동작은 [표면 연결하기](../../how-to/connect-surfaces.ko.md#claude-code)에 있습니다.
 
-기존 훅, 설정 데이터, 문서 안내, 스킬 파일은 보존합니다. 호스트 설정에는 필요한 등록을
-병합하고 `.gitignore`에는 빠진 항목만 추가합니다. 아래 설명처럼 기존 Grok 등록을 조정할
-수도 있으므로 재실행이 언제나 아무것도 바꾸지 않는 것은 아닙니다.
+<a id="init-grok"></a>
+## Grok — `pdks-grok init`
 
-패키지 버전을 올려도 사용자가 수정한 스킬은 덮어쓰지 않습니다. 임시 프로젝트에서 새 사본을
-만들어 기존 파일과 비교한 뒤, 백업하고 필요한 부분만 반영하세요. 강제로 다시 만들려고
-작업 중인 프로젝트의 스킬을 지우지는 마세요.
+Grok 세션 표면은
+[`@polydeukes/adapter-grok`](../packages/adapter-grok.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
 
-<a id="init-grok"></a>
-## `pdks init grok`
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-grok
+npx pdks-grok init
+```
 
-Grok 전용 프로젝트에는 다음 파일을 만듭니다.
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Grok 등록 산출물을 씁니다.
 
 - `.grok/hooks/covenant-pretooluse.mjs`
 - `.grok/hooks/covenant-pretooluse.json`
-- `polydeukes.config.yaml`
-- `.gitignore`
-
-Claude Code 형식과의 차이는 다음과 같습니다.
-
-- `.claude/` 파일을 만들지 않고 Grok 훅 JSON에 등록합니다.
-- Claude 위임 훅이 이미 있으면 새 훅을 만들지 않고 Grok JSON에서 기존 파일을 지정합니다.
-- 새 등록의 제한 시간은 60초입니다. Grok 호스트 기본값은 5초이며, 훅 실행이 시간 초과로
-  끝나면 해당 호출을 차단하지 않습니다(fail-open). Claude 설정에 같은 명령이 등록돼 있으면
-  Grok의 매칭 조건도 맞춰
-  명령과 조건이 모두 같게 만듭니다.
-- 어느 설치기를 다시 실행하든, 설치기가 만든 Grok 훅 명령을 기존 Claude 파일로 바꾸고
-  매칭 조건을 맞출 수 있습니다. 사용자가 다른 곳을 지정한 명령은 그대로 두며 기존 제한
-  시간도 유지합니다.
-- 나중에 Claude 설정을 제거했다면 Grok JSON을 다시 만들어 Grok 기본 매칭 조건을 복원하세요.
-  사용자 설정부터 백업해야 합니다. 변경 뒤에는 Grok의 Hooks 탭을 다시 불러오거나 새 세션을
-  시작합니다.
-
-Grok는 Claude 세션 증인 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
+
+`.claude/` 파일을 만들거나 고치지 않습니다. 새 등록의 제한 시간은 60초입니다. Grok 호스트
+기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을 차단하지 않습니다(fail-open).
+세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+
+Grok는 Claude 세션 증인(witness) 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
 대화 기록은 Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
-[Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요.
+[Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요. 산출물별 동작은
+[표면 연결하기](../../how-to/connect-surfaces.ko.md#grok)에 있습니다.
+
+<a id="init-codex"></a>
+## Codex — `pdks-codex init`
+
+Codex 세션 표면은
+[`@polydeukes/adapter-codex`](../packages/adapter-codex.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-codex
+npx pdks-codex init
+```
+
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Codex 등록 산출물을 씁니다.
+
+- `.codex/hooks/covenant-pretooluse.mjs`
+- `.codex/hooks.json`
+
+`hooks.json`은 덮어쓰지 않고 병합합니다. 다른 이벤트, 다른 matcher, 설치기가 모르는 키는
+그대로 둡니다. 초기 설정은 기본적으로 `.codex/hooks`를 보호하므로, 이 설치기가 만드는 등록
+파일은 같은 설치가 만든 설정이 지킵니다.
+
+**훅 승인까지가 설치입니다.** Codex는 훅 정의의 해시로 신뢰를 기록하므로, 생성된 훅은 검토
+대상으로 표시되고 `/hooks`에서 승인하기 전까지 건너뛰어집니다. 누군가 승인하기 전까지는
+아무것도 판정되지 않습니다. `init`이 실행할 때마다 바이트가 같은 명령 문자열을 쓰는 이유가
+이것입니다. 문자열이 바뀌면 다시 승인해야 합니다.
+
+Codex는 모든 파일 편집을 `apply_patch` 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를
+보냅니다. `Edit`과 `Write`는 `.codex/hooks.json`에 적을 수 있는 matcher 별칭이며 도구 이름으로
+도착하지 않습니다. 패치 하나가 여러 파일을 건드리면 파일마다 IR 원소 하나가 실리고, 그중
+하나라도 차단되면 호출 전체가 차단됩니다.
+
+Codex에는 대화 기록 채널이 없어서 세션 증인(witness) 밸브가 읽을 사람 메시지 증거가
+없습니다. 의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 산출물별 동작은
+[표면 연결하기](../../how-to/connect-surfaces.ko.md#codex)에 있습니다.
 
 <a id="init-results"></a>
 ## 결과와 실패 조건
@@ -103,16 +136,22 @@ Grok는 Claude 세션 증인 밸브가 요구하는 인간 메시지 증거를
 ## 예제
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
+npx pdks-claude-code init
+npx pdks-grok init
+npx pdks-codex init
 ```
 
-설치기는 CLI 명령입니다. `polydeukes`나 `polydeukes/claude-code` 계약의 공개 심볼이
-아닙니다.
+설치기는 CLI 명령입니다. `polydeukes` 계약의 공개 심볼이 아닙니다.
 
 <a id="init-see-also"></a>
 ## 함께 보기
 
+- [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.ko.md) — Claude Code 설치
+단위와 그 실행 파일
+- [`@polydeukes/adapter-grok`](../packages/adapter-grok.ko.md) — Grok 설치 단위와 그 실행 파일
+- [`@polydeukes/adapter-codex`](../packages/adapter-codex.ko.md) — Codex 설치 단위와 그 실행
+파일
 - [`pdks docs`](./docs.ko.md)
 - [`pdks explain`](./explain.ko.md)
 - [설정 참조](../configuration/index.ko.md)

package/dist/docs/reference/cli/init.md

@@ -2,31 +2,30 @@
 
 **English** · [한국어](./init.ko.md)
 
-`pdks init` wires a project into the session surface. The command has two forms: `claude-code` and
-`grok`. Both start with the same preflight: the package must resolve from the target project before
-anything is written.
+`pdks init` creates the agent-neutral project scaffold: the config file and the telemetry ignore
+line. It knows no agent. Registering a session surface is a separate command owned by that
+agent's adapter — `pdks-claude-code init` for Claude Code, `pdks-grok init` for Grok, and
+`pdks-codex init` for Codex.
 
 <a id="init-syntax"></a>
 ## Syntax
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
 ```
 
-Both forms are idempotent. Existing artifacts are left in place and reported as skipped. A preflight
-failure writes nothing and exits `2`.
+Any other argument prints usage and exits `2`. The command is idempotent: existing artifacts are
+left in place and reported as skipped, and a preflight failure writes nothing and exits `2`.
 
 <a id="init-common"></a>
-## Shared preflight and scaffold
+## `pdks init` — the scaffold
 
-The installer does three things in order:
+The command does two things in order:
 
 1. Resolve `polydeukes` from the target project.
 2. Create the shared project-side scaffold: config and telemetry ignore line.
-3. Add the surface-specific registration artifacts.
 
-The shared scaffold is the same for both installers:
+The scaffold is the same one every surface starts from:
 
 - `polydeukes.config.yaml`
 - `.gitignore` with `.polydeukes/`
@@ -35,64 +34,85 @@ The config file starts with the language block, a protection list, a witness blo
 discipline examples. It is a starter policy, not a complete project policy.
 
 <a id="init-claude-code"></a>
-## `pdks init claude-code`
+## Claude Code — `pdks-claude-code init`
 
-This form installs the Claude Code session surface.
+The Claude Code session surface is installed by
+[`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md), which ships its own bin:
 
-Created artifacts:
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+That command runs `pdks init` for the scaffold, then writes the Claude Code registration
+artifacts:
 
 - `.claude/hooks/covenant-pretooluse.mjs`
 - `.claude/settings.json`
 - `.claude/rules/polydeukes.md`
 - `.claude/skills/discipline-draft/SKILL.md`
-- `polydeukes.config.yaml`
-- `.gitignore`
-
-What each artifact does:
-
-- The hook file is a delegator that imports `polydeukes/claude-code`.
-- The settings file merges a PreToolUse registration instead of replacing the whole file.
-- The discovery file tells the AI partner to use `pdks docs` instead of web search.
-- The skill file turns a described discipline problem into a config entry.
-- The config and ignore line come from the shared scaffold.
 
-Existing hook, config, discovery, and skill files are preserved. Settings registrations are
-merged and the ignore entry is appended if absent. Re-running can also reconcile a generated
-Grok registration as described below; it is not an unconditional no-op.
-
-Package upgrades do not overwrite a customized skill. Generate a fresh copy in a disposable
-project, compare it with the existing file, and merge the selected changes after taking a backup.
-Do not delete the working project's skill merely to force regeneration.
+Details and the per-artifact behaviour are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#claude-code).
 
 <a id="init-grok"></a>
-## `pdks init grok`
+## Grok — `pdks-grok init`
+
+The Grok session surface is installed by
+[`@polydeukes/adapter-grok`](../packages/adapter-grok.md), which ships its own bin:
 
-This form installs the Grok session surface.
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-grok
+npx pdks-grok init
+```
 
-Created artifacts:
+That command runs `pdks init` for the scaffold, then writes the Grok registration artifacts:
 
 - `.grok/hooks/covenant-pretooluse.mjs`
 - `.grok/hooks/covenant-pretooluse.json`
-- `polydeukes.config.yaml`
-- `.gitignore`
-
-What differs from the Claude Code form:
-
-- It does not create `.claude/` files.
-- It writes a Grok hook JSON registration instead of `.claude/settings.json`.
-- If a Claude delegator already exists, the Grok JSON names it instead of creating another
-delegator.
-- Generated registrations use a timeout of 60 seconds. The Grok host default is 5 seconds, and a
-  timed-out hook fails open. When Claude settings register the same command, the Grok matcher
-  follows that registration so command and matcher agree.
-- Re-running either installer can retarget a generated Grok-delegator command to the existing
-  Claude file and reconcile its matcher. A custom command is left alone; an existing timeout stays.
-- If you later remove Claude settings, regenerate the Grok JSON to restore the Grok-native matcher.
-  Back up custom settings first. Reload Grok's Hooks tab or start a new session after changes.
+
+It does not create or rewrite `.claude/` files. Generated registrations use a timeout of 60
+seconds. The Grok host default is 5 seconds, and a timed-out hook fails open. Installing more
+than one session adapter in one project can run the judge twice per call.
 
 Grok does not supply the human-message evidence required by the Claude session witness valve.
 The session log is ACP `updates.jsonl`, not Claude's JSONL.
-See [Grok recovery](../../troubleshooting.md#grok-witness).
+See [Grok recovery](../../troubleshooting.md#grok-witness). Details are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#grok).
+
+<a id="init-codex"></a>
+## Codex — `pdks-codex init`
+
+The Codex session surface is installed by
+[`@polydeukes/adapter-codex`](../packages/adapter-codex.md), which ships its own bin:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-codex
+npx pdks-codex init
+```
+
+That command runs `pdks init` for the scaffold, then writes the Codex registration artifacts:
+
+- `.codex/hooks/covenant-pretooluse.mjs`
+- `.codex/hooks.json`
+
+`hooks.json` is merged rather than overwritten: other events, other matchers, and keys the
+installer does not know are left in place. The scaffold config protects `.codex/hooks` by
+default, so the registration this installer writes is covered by the config it writes.
+
+**Approving the hook is part of the install.** Codex records trust against the hash of a hook's
+definition, so the generated hook is listed for review and skipped until you approve it with
+`/hooks`. Until someone does, nothing is judged. This is why `init` writes a byte-identical
+command string on every run — a changed string needs approving again.
+
+Codex normalises every file edit into one tool, `apply_patch`, and delivers the patch text
+rather than a path argument. `Edit` and `Write` are matcher aliases you may write in
+`.codex/hooks.json`; they never arrive as the tool name. One patch that touches several files
+carries one IR element per file, and any one of them blocking blocks the whole call.
+
+Codex supplies no transcript channel, so the session witness valve has no human-message
+evidence to read. For an intentional blocked edit, use your own terminal. Details are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#codex).
 
 <a id="init-results"></a>
 ## Results and failure conditions
@@ -114,16 +134,22 @@ filesystem problem, and rerun rather than assuming every failed installation lef
 ## Examples
 
 ```sh
-pdks init claude-code
-pdks init grok
+pdks init
+npx pdks-claude-code init
+npx pdks-grok init
+npx pdks-codex init
 ```
 
-The installer is a CLI command. It is not a symbol on the `polydeukes` or
-`polydeukes/claude-code` contract.
+The installers are CLI commands. They are not symbols on the `polydeukes` contract.
 
 <a id="init-see-also"></a>
 ## See also
 
+- [`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md) — the Claude Code
+install unit and its bin.
+- [`@polydeukes/adapter-grok`](../packages/adapter-grok.md) — the Grok install unit and its bin.
+- [`@polydeukes/adapter-codex`](../packages/adapter-codex.md) — the Codex install unit and its
+bin.
 - [`pdks docs`](../packages/polydeukes.md#polydeukes-bin) — the installed documentation reader lives
 in the same package.
 - [`pdks explain`](./explain.md)