docs: EN README for public — install, permissions, models discovery

CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+Keep PRs small and focused. Use English only.
+
+1. Fork, branch from `main`, make minimal changes.
+2. Run relevant tests (`tests/test-run.sh` if touching `scripts/`).
+3. Bump `version` in `.claude-plugin/plugin.json` if publishing.
+4. Ensure `codex CLI >=0.151` and `jq` requirements are respected.
+5. Open PR with clear description and verification steps.
+6. Be respectful and constructive in review.

README.md

@@ -1,58 +1,66 @@
 # codex-crew
 
-Codex CLI as a first-class Claude Code subagent: task delegation, code
+Codex CLI as a first-class Claude Code subagent: delegate, review, consult. Respects your `~/.codex/config.toml`, sessions resumable, stall watchdog.
-review, second opinion. Inherits the user's `~/.codex/config.toml` (no
-sandboxes, no restrictions), sessions are resumable, hangs are detected by a
-deterministic watchdog.
-
-## Contents
-
-- `agents/codex.md` — transport subagent (sonnet). Holds the codex session:
-  follow-ups via SendMessage continue the same dialogue. The task must
-  include `cwd:`; optional `codex options:` (model/sandbox/effort) and
-  `review scope:`.
-- `skills/codex-agent` — delegate execution.
-- `skills/codex-review` — review a branch/commit/uncommitted/files.
-- `skills/codex-consult` — second opinion on a spec/plan, iterate to
-  consensus.
-- `scripts/codex-run.sh` — wrapper around `codex exec --json` with a
-  watchdog (`CODEX_STALL_TIMEOUT`, default 600s of output stagnation → kill;
-  the session continues via resume). Tests: `tests/test-run.sh`.
-
-## How it works
-
-The orchestrator spawns the `codex` subagent with a task. The subagent
-writes a prompt file (transport preamble + task), launches `codex-run.sh`
-in the background, and polls the status file.
-
-Review mode: the codex CLI can't combine a scope flag
-(`--base`/`--commit`/`--uncommitted`) with a custom prompt, so with a
-non-empty prompt file the script translates the scope into prompt text
-automatically; with no prompt file the native `codex exec review <scope>`
-path is used.
-
-Prompt convention: wrapper instructions outside, the codex task between
-`=== TASK FOR CODEX ===` / `=== END TASK ===` markers — the wrapper forwards
-only the marked block, so it never mistakes the task for its own job, and
-wrapper instructions never leak into the codex prompt.
 
 ## Install
 
 ```
-claude plugin marketplace add <path-or-github-url>
+/plugin marketplace add smartass/codex-crew
-claude plugin install codex-crew@codex-crew
+/plugin install codex-crew@codex-crew
 ```
 
-Requires codex CLI ≥0.142.
+Requires `codex CLI >=0.151` and `jq`.
 
-Update after push (Claude Code doesn't re-fetch the cache; `plugin update`
+## How it works
-compares the version from plugin.json — no version bump, no content update):
+
+Orchestrator → `codex` subagent (`agents/codex.md`) → `scripts/codex-run.sh` → `codex exec --json` (`--skip-git-repo-check -o last.md`). Non-empty `prompt.md` is fed via stdin `-` so flags and prompt combine. Stall watchdog (`CODEX_STALL_TIMEOUT`, default 600s of event silence → kill; resume via `thread_id`). `cwd:` in task is mandatory; `codex options:` forwarded verbatim. Review scope (`--base`/`--commit`/`--uncommitted`) is translated to prompt text when a custom prompt is present (CLI forbids scope + prompt together), otherwise native `codex exec review <scope>`.
+
+## Skills
+
+| Skill | Trigger |
+|---|---|
+| `codex-agent` | `delegate to codex`, `have codex do` — execution, bugfix, research |
+| `codex-review` | `codex review` — branch (`--base`), commit, uncommitted, or files |
+| `codex-consult` | `second opinion`, `have codex review the spec/plan` — iterate to consensus (max 5 rounds) |
+
+Details: `skills/references/common.md`.
+
+## Permissions & Sandbox
+
+Default inherits `~/.codex/config.toml` (no flags injected). Override per-task via `codex options:`:
+
+- `-s read-only | workspace-write | danger-full-access`
+- `--add-dir <dir>` — extra writable directory
+- `--dangerously-bypass-approvals-and-sandbox` — dangerous, only in an externally sandboxed environment
+
+Example: `codex options: -s workspace-write --add-dir /tmp`
+
+Flags are saved per-job and re-applied on `resume`.
+
+## Models & Reasoning
+
+Default from `~/.codex/config.toml` (`model`, `model_reasoning_effort`). Discovery:
 
 ```
-# 1. bump version in .claude-plugin/plugin.json, commit, push
+./scripts/codex-models.sh
-claude plugin marketplace update codex-crew
+# or
-claude plugin update codex-crew@codex-crew
+codex debug models | jq '[.models[] | select(.visibility=="list") | {slug, levels: [.supported_reasoning_levels[].effort]}]'
 ```
 
-then `/reload-plugins` or restart the session (agent/skill definitions are
+Pass via `codex options: -m <model-from-discovery> -c model_reasoning_effort="<effort-from-discovery>"` (values from `scripts/codex-models.sh` output).
-snapshotted on reload; hot-patching the cache doesn't work).
+
+## Updating
+
+Bump `version` in `.claude-plugin/plugin.json`, commit, push, then:
+
+```
+/plugin marketplace update codex-crew
+/plugin update codex-crew@codex-crew
+/reload-plugins
+```
+
+No version bump → no update (Claude Code caches by version).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — keep changes minimal and EN-only.