polydeukes 0.6.0 → 0.7.1

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

@@ -0,0 +1,119 @@
+# `pdks init`
+
+[English](./init.md) · **한국어**
+
+`pdks init`은 에이전트와 무관한 초기 파일을 만듭니다. 설정 파일과 텔레메트리 제외 항목
+둘입니다. 이 명령은 어느 에이전트도 알지 못합니다. 세션 표면 등록은 그 에이전트의 어댑터가
+맡는 별도 명령입니다. Claude Code는 `pdks-claude-code init`, Grok는 `pdks-grok init`입니다.
+
+<a id="init-syntax"></a>
+## 구문
+
+```sh
+pdks init
+```
+
+다른 인자를 주면 사용법을 출력하고 종료 코드 `2`를 반환합니다. 이미 있는 산출물은 보존하고
+`skipped`로 보고하며, 사전 검사에 실패하면 파일을 쓰지 않고 종료 코드 `2`를 반환합니다.
+
+<a id="init-common"></a>
+## `pdks init` — 초기 파일
+
+이 명령의 순서는 다음과 같습니다.
+
+1. 대상 프로젝트에서 `polydeukes`를 찾을 수 있는지 확인합니다.
+2. 공통 설정과 텔레메트리 제외 항목을 만듭니다.
+
+어느 표면이든 여기서 출발합니다.
+
+- `polydeukes.config.yaml`
+- `.gitignore`의 `.polydeukes/` 항목
+
+설정 파일에는 언어 블록, 보호 목록, 증인(witness) 블록, 주석으로 된 규율(discipline) 예제가
+있습니다. 완성된 정책이 아니라 프로젝트에 맞춰 고칠 출발점입니다.
+
+<a id="init-claude-code"></a>
+## 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/adapter-claude-code
+npx pdks-claude-code init
+```
+
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
+
+- `.claude/hooks/covenant-pretooluse.mjs`
+- `.claude/settings.json`
+- `.claude/rules/polydeukes.md`
+- `.claude/skills/discipline-draft/SKILL.md`
+
+산출물별 동작은 [표면 연결하기](../../how-to/connect-surfaces.ko.md#claude-code)에 있습니다.
+
+<a id="init-grok"></a>
+## Grok — `pdks-grok init`
+
+Grok 세션 표면은
+[`@polydeukes/adapter-grok`](../packages/adapter-grok.ko.md)가 설치합니다. 이
+어댑터에는 자체 실행 파일이 있습니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
+
+이 명령은 먼저 `pdks init`으로 초기 파일을 만든 뒤 Grok 등록 산출물을 씁니다.
+
+- `.grok/hooks/covenant-pretooluse.mjs`
+- `.grok/hooks/covenant-pretooluse.json`
+
+`.claude/` 파일을 만들거나 고치지 않습니다. 새 등록의 제한 시간은 60초입니다. Grok 호스트
+기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을 차단하지 않습니다(fail-open).
+두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+
+Grok는 Claude 세션 증인(witness) 밸브가 요구하는 인간 메시지 증거를 제공하지 않습니다.
+대화 기록은 Claude JSONL이 아니라 ACP `updates.jsonl`입니다.
+[Grok 복구 안내](../../troubleshooting.ko.md#grok-witness)를 참고하세요. 산출물별 동작은
+[표면 연결하기](../../how-to/connect-surfaces.ko.md#grok)에 있습니다.
+
+<a id="init-results"></a>
+## 결과와 실패 조건
+
+| 상황 | 결과 |
+|---|---|
+| 패키지를 찾고 대상 프로젝트의 초기 파일을 만들 수 있음 | 종료 `0` |
+| 요청한 산출물이 이미 있음 | `skipped`로 보고하고 종료 `0` |
+| 대상 프로젝트에서 패키지를 찾을 수 없음 | 종료 `2`, 파일을 쓰지 않음 |
+| 설정 파일이 여러 개라 모호함 | 종료 `2`, 파일을 쓰지 않음 |
+| 호스트 설정 파일을 읽거나 구문을 분석할 수 없음 | 종료 `2`, 파일을 쓰지 않음 |
+| 그 밖의 사전 검사 또는 파일 쓰기 실패 | 종료 `2` |
+
+사전 검사는 파일을 쓰기 전에 끝납니다. 하지만 이후 파일 쓰기에서 실패하면 일부 파일이
+이미 만들어졌을 수 있습니다. 설치 전체를 한꺼번에 되돌리는 기능은 아닙니다. 오류를 확인하고
+파일시스템 문제를 고친 뒤 다시 실행하세요. 설치가 실패했으니 아무 파일도 없을 것이라고
+가정해서는 안 됩니다.
+
+<a id="init-examples"></a>
+## 예제
+
+```sh
+pdks init
+npx pdks-claude-code init
+npx pdks-grok init
+```
+
+설치기는 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 설치 단위와 그 실행 파일
+- [`pdks docs`](./docs.ko.md)
+- [`pdks explain`](./explain.ko.md)
+- [설정 참조](../configuration/index.ko.md)
+- [`polydeukes`](../packages/polydeukes.ko.md)

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

@@ -0,0 +1,119 @@
+# `pdks init`
+
+**English** · [한국어](./init.ko.md)
+
+`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, and `pdks-grok init` for Grok.
+
+<a id="init-syntax"></a>
+## Syntax
+
+```sh
+pdks init
+```
+
+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>
+## `pdks init` — the scaffold
+
+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.
+
+The scaffold is the same one every surface starts from:
+
+- `polydeukes.config.yaml`
+- `.gitignore` with `.polydeukes/`
+
+The config file starts with the language block, a protection list, a witness block, and commented
+discipline examples. It is a starter policy, not a complete project policy.
+
+<a id="init-claude-code"></a>
+## Claude Code — `pdks-claude-code init`
+
+The Claude Code session surface is installed by
+[`@polydeukes/adapter-claude-code`](../packages/adapter-claude-code.md), which ships its own bin:
+
+```sh
+npm install --save-dev polydeukes @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`
+
+Details and the per-artifact behaviour are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#claude-code).
+
+<a id="init-grok"></a>
+## Grok — `pdks-grok init`
+
+The Grok session surface is installed by
+[`@polydeukes/adapter-grok`](../packages/adapter-grok.md), which ships its own bin:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-grok
+npx pdks-grok init
+```
+
+That command runs `pdks init` for the scaffold, then writes the Grok registration artifacts:
+
+- `.grok/hooks/covenant-pretooluse.mjs`
+- `.grok/hooks/covenant-pretooluse.json`
+
+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 both
+session adapters 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). Details are in
+[Connect the surfaces](../../how-to/connect-surfaces.md#grok).
+
+<a id="init-results"></a>
+## Results and failure conditions
+
+| Situation | Result |
+|---|---|
+| Package resolves and the target tree can be scaffolded | exit `0` |
+| A requested artifact already exists | Reported as skipped, but the command still exits `0` |
+| The package cannot be resolved from the target project | exit `2`, nothing written |
+| The config path is ambiguous | exit `2`, nothing written |
+| The settings file is unreadable or unparseable | exit `2`, nothing written |
+| Any other preflight or write failure | exit `2` |
+
+Preflight failures occur before writing. A later filesystem write failure can leave some
+artifacts created; the installer is not an atomic transaction. Inspect the error, repair the
+filesystem problem, and rerun rather than assuming every failed installation left an empty tree.
+
+<a id="init-examples"></a>
+## Examples
+
+```sh
+pdks init
+npx pdks-claude-code init
+npx pdks-grok init
+```
+
+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.
+- [`pdks docs`](../packages/polydeukes.md#polydeukes-bin) — the installed documentation reader lives
+in the same package.
+- [`pdks explain`](./explain.md)
+- [`Configuration reference`](../configuration/index.md)
+- [`polydeukes`](../packages/polydeukes.md)