jeo-code 0.1.0 → 0.4.4

package/README.md

@@ -1,342 +1,160 @@
-# jeo-code (`joc`)
-
-[![Bun Version](https://img.shields.io/badge/Bun-%3E%3D%201.3.14-blue?logo=bun)](https://bun.sh)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen)]()
-[![Tests Status](https://img.shields.io/badge/Tests-348%20Passed-brightgreen)]()
-
-> An interactive AI coding agent **and** a disciplined spec-first pipeline — one
-> lean, pure-TypeScript CLI on Bun.
-`jeo-code` is a single-package coding agent (binary `joc`) that you can use two ways:
-
-- **Interactive agent** — run bare `joc` to chat with an agent that reads, writes,
-  edits, and runs commands in a loop until your request is done (with a live TUI).
-- **Spec-first pipeline** — `deep-interview → ralplan → team → ultragoal`: crystallize
-  requirements before any code changes, plan, execute, then verify against acceptance criteria.
-
-It re-implements the [`gajae-code`](https://github.com/Yeachan-Heo/gajae-code) (`gjc`)
-workflow contract and adopts [`pi-mono`](https://github.com/badlogic/pi-mono) runtime
-ergonomics (minimal tool loop, persistent sessions, compaction, project context) — with
-**no native deps**: just Bun + TypeScript.
-
-```text
-joc                      →  interactive coding agent (TUI: live tools + status footer)
-
-joc deep-interview → joc ralplan → joc approve → joc team → joc ultragoal
- (Socratic clarify)   (blueprint)    (gate)        (execute)   (verify)
-        │
-  [Mutation Lock] — file edits blocked until ambiguity ≤ 20%
-```
+<p align="center">
+  <img src="assets/hero.png" alt="jeo-code autonomous coding-agent hero illustration" width="100%" />
+</p>
 
----
+<h1 align="center">jeo-code (jeo)</h1>
 
-## Quick start
+<p align="center">
+  <strong>Encode intention. Decode software.</strong><br />
+  A Bun-based AI coding-agent CLI — interviews, reviewed plans, gated execution, honest verification.
+</p>
 
-Install `joc` the same way you install `gjc` — a single Bun global install — then
-launch it from whatever repository you want it to operate on:
+<p align="center">
+  <a href="https://github.com/akillness/jeo-code"><img alt="license" src="https://img.shields.io/badge/license-MIT-green?style=flat-square"></a>
+  <img alt="runtime" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3.14-f9f1e1?style=flat-square&logo=bun&logoColor=black">
+  <img alt="zero native deps" src="https://img.shields.io/badge/native%20deps-0-blue?style=flat-square">
+</p>
 
-```bash
-# 1. Install (gjc parity: one bun global install)
-bun install -g jeo-code                                      # npm registry (once published)
-bun install -g github:akillness/jeo-code                     # GitHub shorthand
-bun install -g git+https://github.com/akillness/jeo-code.git # explicit Git URL
-#   …or bootstrap Bun + install from the Git URL in one shot:
-curl -fsSL https://raw.githubusercontent.com/akillness/jeo-code/main/scripts/install.sh | sh
-
-# 2. Configure a provider + default model (interactive)
-joc setup
-#    …or go fully local with Ollama, no key:
-ollama pull qwen2.5:0.5b
-export JOC_DEFAULT_MODEL=ollama/qwen2.5:0.5b
+<p align="center">
+  <img src="assets/character.png" alt="jeo-code character mascot" width="320" />
+</p>
 
-# 3. Verify the setup is reachable
-joc doctor
+<p align="center">
+  <b>English</b> ·
+  <a href="README.ko.md">한국어</a> ·
+  <a href="README.ja.md">日本語</a> ·
+  <a href="README.zh.md">中文</a>
+</p>
 
-# 4. Launch from the target repo (gjc-style entrypoints)
-joc                                   # interactive agent in the current checkout
-joc --tmux                            # create/attach a joc-managed tmux session
-joc --tmux --worktree ../joc-feature  # isolate work in a dedicated git worktree
-joc "add a /health route to server.ts and run the tests"  # one-shot request
-```
+Run `jeo` inside a repository and it reads files, edits them, runs commands, and drives the task to completion — streaming every step live in an inline, scrollback-friendly TUI.
 
-**Requirements:** Bun `v1.3.14+` (the installer auto-installs it if missing; the CLI re-checks at startup).
+## Highlights
 
----
+- **Multi-provider, one loop** — Anthropic / OpenAI (+Codex) / Gemini / Antigravity / Ollama behind a uniform JSON tool loop. OAuth login from the input box (`/provider login`), every model pick persists as the new default.
+- **Edit integrity** — read output carries content anchors (`42ab|`); anchored edits are verified against the current file, re-mapped when lines shifted, and rejected with fresh content instead of corrupting.
+- **Self-correcting verification loop** — configure a post-edit hook (tsc / eslint / tests) and the agent *sees* the diagnostics and fixes them in-loop; a red hook blocks `done` until resolved.
+- **Real gates, no theater** — `ralplan` consensus is a repo-grounded critic subagent whose `[OKAY]` verdict is persisted and *required* by `jeo approve`; `ultragoal` reports honestly (a suite run is a global signal, never fabricated per-criterion passes).
+- **Crash-durable, local-first** — all state under `.jeo/` with atomic writes, cross-process run locks, failed-task markers with partial-edit warnings on resume.
+- **Dynamic step budget** — turns extend while the tool window shows novel progress and consolidate gracefully when stalled; subagents keep exact step contracts.
+- **Inline TUI** — completed work flushes into real scrollback (tmux wheel works mid-turn), the normal query input box stays visible and editable while the agent runs, Ctrl+O toggles full detail, themes, clipboard image paste (Ctrl+V), CJK/emoji-safe width math.
 
-## Installation
+## Install
 
-`joc` installs exactly like `gjc`: a single Bun global install that registers the
-`joc` binary in `~/.bun/bin`. The installer also drops a compatibility symlink at
-`~/.local/bin/joc` and auto-installs Bun (enforcing the `1.3.14` floor) when it is missing.
+Requires Bun `1.3.14+`.
 
 ```bash
-bun install -g jeo-code                                      # npm registry (gjc parity, once published)
-bun install -g github:akillness/jeo-code                     # GitHub shorthand
-bun install -g git+https://github.com/akillness/jeo-code.git # explicit Git URL
-sh scripts/install.sh --repo https://github.com/akillness/jeo-code.git
-sh scripts/install.sh --ref v0.1.0                           # global install of a specific tag
-sh scripts/install.sh --binary                               # compile a standalone binary (no bun at runtime)
-sh scripts/uninstall.sh [--purge]                            # remove the bin + bun registry entry (--purge also wipes ~/.joc/)
+bun install -g jeo-code
+jeo --version
 ```
 
-### Registry-aware installs
-
-`joc` does **not** mutate your npm registry by default. Use `--registry` for a one-shot
-Bun install, and add `--persist-registry` only when you intentionally want the installer
-to run `npm config set ...`.
+## Quick start
 
 ```bash
-# One-shot registry for this install only
-sh scripts/install.sh --npm --registry https://registry.npmjs.org/
-sh scripts/install.sh --npm --registry https://npmjs.co.kr
-sh scripts/install.sh --npm --registry https://your-company-registry.com
-
-# Persist globally via npm config (official registry restore / mirror / private)
-sh scripts/install.sh --npm --registry https://registry.npmjs.org/ --persist-registry
-sh scripts/install.sh --npm --registry https://npmjs.co.kr --persist-registry
-sh scripts/install.sh --npm --registry https://your-company-registry.com --persist-registry
-
-# Scope-only registry (writes @my-org:registry, not the global registry)
-sh scripts/install.sh --npm --scope @my-org --registry https://your-company-registry.com --persist-registry
-
-# Project-pinned .npmrc instead of global npm config
-sh scripts/install.sh --npm --registry https://registry.npmjs.org/ --project-npmrc
-
-# Inspect / reset npm registry config
-sh scripts/install.sh --print-registry
-sh scripts/install.sh --delete-registry
+jeo                      # interactive agent in the current repo
+jeo "Tidy the README and run the tests"   # one-shot request
+jeo doctor               # config + live model connectivity check
+jeo setup                # API keys / OAuth / local models
+jeo --tmux               # run inside an isolated tmux session
 ```
 
-### Publishing `jeo-code` to npm
+## Slash commands
+
+Inside the `jeo` REPL (Tab autocompletes; `/` opens the palette).
 
-`bun install -g jeo-code` resolves through the npm registry, so the package must be
-published there. The package is configured for public npm publication
-(`publishConfig.registry=https://registry.npmjs.org/`, `publishConfig.access=public`)
-and keeps the executable bin as `joc -> src/cli.ts` with a Bun shebang.
+| Command | Description |
+| --- | --- |
+| `/model` · `/provider` | Pick model/provider; `/model` shows default/role badges, Ralph-style nested Set-as-role thinking choices, and the OpenAI Codex role preset in one flow |
+| `/provider login <name>` · `/logout` | OAuth login/logout from the input box |
+| `/agents [role]` · `/subagent` | Per-role (executor/planner/architect/critic) model · thinking · step config |
+| `/thinking [level]` | Show/set default reasoning budget (minimal…xhigh) |
+| `/fast [on|off|status]` | Toggle fast thinking mode when the active model advertises minimal/low reasoning |
+| `/skill` · `$<skill> [intent]` | List/run workflow skills (`$team "task"` style) |
+| `/view` · `/diff` · `/find` · `/search` | Code view, git diff, file/pattern search |
+| `/new` · `/resume` · `/sessions` | Session management |
+| `/history [n|all]` · `/export` | Reprint readable worked activity history into scrollback · transcript export |
+| `/retry` · `/btw <q>` | Retry last request · side question without touching history |
+| `/usage` · `/context` · `/compact` | Token usage, context breakdown, manual compaction |
+| `/theme` · `/config` · `/help` | Theme, runtime config, help |
+| `jeo autopilot status` | Ratchet status field with score direction, keep/revert counts, and next action |
+
+## Spec-first workflow
+
+Requirements → plan → approval → execution → verification, carried through `.jeo/state/` with **real, blocking gates** at every handoff:
 
 ```bash
-npm login --registry https://registry.npmjs.org/
-bun run publish:npm
-npm view jeo-code version bin --registry https://registry.npmjs.org/
-bun install -g jeo-code
-joc --version
+jeo deep-interview "Describe what you want to build"
+jeo ralplan
+jeo approve <plan-path>
+jeo team
+jeo ultragoal
 ```
 
-For CI/release publishing, add an npm token as the repository secret `NPM_TOKEN`,
-then run the `Publish npm package` GitHub Action (dry-run or publish) or publish a
-GitHub release. The workflow runs `bun install --frozen-lockfile`, `bun run typecheck`,
-`bun test`, `npm pack --dry-run`, then `npm publish --provenance`.
+- **deep-interview** — Socratic loop with ambiguity scoring; freezes a seed only when criteria are concrete (vague-only criteria are refused) and the seed round-trips its own parser. A new idea never silently reuses a completed interview.
+- **ralplan** — drafting passes plus a **repo-grounded critic subagent gate**: the critic reads the actual repository, must return `[OKAY]`/`[ITERATE]`/`[REJECT]`, and the verdict is persisted. Invalid plans (schema, unknown roles) are never marked complete.
+- **approve** — validates the exact contract `team` executes (schema + roles) *and* requires the persisted `[OKAY]` consensus verdict.
+- **team** — serial plan executor with a cross-process run lock, stale-plan reset, per-task subagent contracts, a parent-side mutation audit (a "completed" task with zero observed writes is flagged), and failed-task markers that warn about partial edits on resume.
+- **ultragoal** — honest verification: the suite runs once as a global signal; criteria are recorded, never fabricated as individually passed.
 
-Required npm token permissions:
+## Verification hooks (self-correction)
 
-1. npmjs.com → account settings → **Access Tokens** → create an **Automation** token, or
-   a **Granular Access Token** with package publish/read-write permission.
-2. If the npm account has 2FA enabled, the token must be allowed to **bypass 2FA for
-   publishing**. A read-only token or granular token without 2FA bypass fails with:
-   `Two-factor authentication or granular access token with bypass 2fa enabled is required`.
-3. GitHub repo → Settings → Secrets and variables → Actions → set `NPM_TOKEN` to that token.
-4. Re-run the `Publish npm package` workflow. After it succeeds, verify:
+Enable hooks once globally (`"hooks": { "enabled": true }` in `~/.jeo/config.json`), then add a post-edit check per project; the agent sees failures and fixes them before it may call `done`:
 
-```bash
-npm view jeo-code version bin --registry https://registry.npmjs.org/
-bun install -g jeo-code
-joc --version
+```jsonc
+// .jeo/hooks.json
+{
+  "enabled": true,
+  "hooks": [
+    { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
+  ]
+}
 ```
 
-From a clone, `./install.sh` performs the dev install (`bun link`) so source edits
-take effect immediately; `scripts/install.sh --help` lists every mode.
+Non-zero hook output is appended to the tool result the model reads (deduped per batch); a still-red hook triggers a `done` pushback naming the hook.
 
-```bash
-./install.sh                          # dev install from this clone (= scripts/install.sh --local)
-```
-
-Local dev without installing (from the repo root):
+## Local models
 
 ```bash
-bun run start --help     # = bun src/cli.ts --help
-bun run typecheck        # tsc -p tsconfig.json --noEmit
-bun test                 # unit tests (61 files, 372 tests)
+ollama pull qwen2.5:0.5b
+export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
+jeo doctor && jeo
 ```
 
----
-
-## Commands
+## Configuration
 
-| Command | What it does |
-| --- | --- |
-| `joc` / `joc launch ["request"]` | Interactive coding agent (TUI REPL, one-shot, or piped). `--tmux` (create/attach a joc tmux session), `--worktree <path>` (run in a dedicated git worktree), `--resume [id]`, `--list`, `--no-tui`, `--no-session`. |
-| `joc setup` | Interactive provider/model picker (API key / browser OAuth / local), with live model probing. |
-| `joc auth [login\|logout\|refresh\|status] [provider] [--token <bearer>]` | Real OAuth (PKCE) login + token storage with auto-refresh. |
-| `joc doctor [--strict] [--json]` | Probe provider connectivity, credentials, and OAuth expiry; report if the default model is reachable. Colorized status on a TTY. `--strict` exits non-zero when it isn't; `--json` emits a machine-readable report for CI. |
-| `joc deep-interview "<idea>" [--auto]` | Socratic requirements interview; freezes a spec when ambiguity ≤ 20%. `--auto` runs non-interactively (CI/pipes). |
-| `joc ralplan` | Planner/Architect/Critic blueprint from the frozen seed. |
-| `joc approve <plan-path>` | Approve the active plan blueprint; gates execution (`team` refuses to run until approved). Idempotent. |
-| `joc team` | Per-task executor loop (shared tool engine) against the plan. |
-| `joc ultragoal` | Verify acceptance criteria and write a report. |
-| `joc models [name] [--catalog] [--caps] [--check]` | Live model list from logged-in (OAuth/API) accounts + aliases & provider credentials. `--catalog` shows the capability catalog (context/out/thinking/images), `--caps` merges live models with capabilities (`--thinking=<lvl>`/`--images`/`--long` filters), `--check` is a per-provider auth/reachability probe. |
-| `joc skills [name]` | List bundled workflow skills; `joc skills <name>` prints details. |
-| `joc resume [id]` | Resume the latest interactive session (or a specific id). |
-| `joc chat "<msg>"` | Single-shot streaming chat (no tools) — renders the reply token-by-token. |
-| `joc mcp [serve\|tools]` | Run `joc` as an MCP stdio server (set `JOC_MCP_PIPELINE=1` to also expose the pipeline tools). |
-| `joc evolve [--step N] [--max M] [--animate] [--loop N] [--theme cosmic\|matrix\|solar\|mono] [--gradient] [--ascii] [--fit] [--width W] [--list] [--list-themes] [--json] [--no-color]` | Preview the **evolution TUI** identity — five ASCII-art stages with track + stage meter. `--gradient` truecolor (256/16/plain downgrade), `--theme` palettes, `--ascii` legacy-terminal fallback, `--fit`/`--width` terminal sizing, `--list`/`--list-themes`/`--json` for tooling. |
-
----
-
-## Interactive agent
-
-Run bare `joc` (or `joc launch`) for a conversational coding agent built on a shared,
-hardened tool-call engine (`src/agent/engine.ts`). It calls `read` / `write` / `edit` /
-`bash` / `find` / `search` in a loop until it signals done.
-
-- **TUI** — on a TTY it renders a differential UI (live tool-call list, `joc thinking`
-  progress status, `joc forge` tool stats, and boxed previews for `bash` / `write` /
-  `read` / `edit` calls); `--no-tui`, piped input, and non-TTY fall back to a
-  plain `stream:complete` / `stream:error` event stream.
-- **Evolution TUI** — the live view evolves with the agent's progress through five stages
-  (**Primordial Cell → Double Helix → Tool User → AI Coding Agent → Singularity**). The ASCII
-  art, spinner, progress meter, and footer track all advance in lockstep from one canonical
-  stage model (`src/tui/components/evolution.ts`); `finish()` records `Evolved to: <stage>`.
-  Preview it any time with `joc evolve` (try `--theme matrix --gradient --fit`). On a TTY the
-  live frame **fills the terminal** — art centered to the width, footer pinned to the bottom row —
-  and downgrades gracefully (truecolor→256→16→plain, unicode→ASCII) per terminal capability.
-- **Model & provider control (live)** — `<Tab>` autocompletes slash commands and their
-  arguments: model ids, providers, and subagent roles. `/model` and `/models` pull the
-  **real model list from your logged-in (OAuth / API-key) accounts** via live discovery —
-  pick by id or `#N`, set the session model or save it as default. `/provider` switches
-  providers (and lists that provider's live models), and `/agents <role> [model]` pins a per-role
-  model for the `executor` / `planner` / `architect` / `critic` subagents. `/roles [tier model]`
-  sets the `smol`/`slow`/`plan` model tiers; `/thinking` spans `minimal`→`xhigh`; `/view` / `/diff`
-  / `/find` / `/search` give an in-TUI code view.
-- **Sessions** — every turn is appended to `.joc/sessions/<id>.jsonl`; `joc launch --list`
-  and `joc launch --resume [id]` resume past conversations.
-- **tmux orchestration (gjc parity)** — `joc --tmux` creates/attaches a leader session named
-  `joc-<branch>`; add `--worktree <path>` to run inside a dedicated git worktree (auto-created
-  on a branch named after the path) so edits and evidence stay isolated from your main checkout.
-- **Project context** — the prompt auto-loads the first of `JEO.md` / `AGENTS.md` /
-  `.joc/context.md` / `CLAUDE.md`.
-- **Compaction** — long conversations are summarized automatically to stay within the context window.
-- **Progress guards** — if a (weak/local) model repeats the same tool call 3× or racks up 5
-  consecutive tool failures without signalling done, the loop stops with a clear message instead of burning steps.
-- **Token usage** — each turn prints a `(N in / M out tokens)` footer; all four provider
-  adapters report usage in both blocking `call` and streaming modes.
+- Global config: `~/.jeo/config.json` (model picks are MRU-persisted)
+- Project state/sessions: `<project>/.jeo/`
 
 ```bash
-joc                                   # REPL — slash: /model /models /provider /agents /roles /thinking /config /view /diff /find /search (Tab to autocomplete)
-joc launch "fix the failing test"     # one-shot
-echo "summarize src/agent" | joc      # piped / non-TTY (plain output)
-joc launch --resume                   # resume the latest session (or --resume <uuid>)
-joc --tmux                            # create/attach a joc-managed tmux session (named joc-<branch>)
-joc --tmux --worktree ../joc-feature  # isolate edits/evidence in a dedicated git worktree
+ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
+JEO_DEFAULT_MODEL=...           # e.g. ollama/qwen2.5:0.5b
+OLLAMA_HOST=http://localhost:11434
+JEO_TUI_THEME=cosmic            # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura
+JEO_TUI_ALT_SCREEN=1            # legacy alt-screen turn (default: inline scrollback)
+JEO_STEP_BASE=24                # dynamic step budget: rolling base
+JEO_STEP_HARD_CAP=600           # absolute termination guarantee
+JEO_STREAM_MAX_MS=300000        # opt-in overall stream deadline (default off; bounds slow-drip streams)
+JEO_TOOL_OUTPUT_MAX=4000        # model-visible tool output cap (full output spills to artifacts)
 ```
 
----
-
-## Spec-first pipeline
-
-Crystallize requirements before touching code. While a `deep-interview` is active, the
-**MutationGuard** blocks code-mutating tools — `write`/`edit` outside `.joc/`, and `bash`
-entirely — releasing once ambiguity ≤ 20%.
-
-1. **`joc deep-interview "<idea>"`** — Socratic loop scoring ambiguity across Goal clarity,
-   Constraint completeness, and Success/Acceptance criteria. Freezes a seed to
-   `.joc/seeds/seed-<slug>.yaml`.
-2. **`joc ralplan`** — multi-role (Planner/Architect/Critic) blueprint → `.joc/plans/plan-<slug>.yaml`.
-3. **`joc approve <plan-path>`** — approval gate: marks the plan approved so `team` will execute it.
-4. **`joc team`** — executes plan tasks via the shared tool engine; checkpoints to `.joc/state/team-state.json`.
-5. **`joc ultragoal`** — runs acceptance checks and writes `.joc/state/ultragoal-report.md`.
-
----
-
-## Providers, OAuth & local models
-
-Routing is inferred from the model id; credentials resolve from `~/.joc/config.json` (or env).
-
-| Provider | Model id example | Credential |
-| --- | --- | --- |
-| Anthropic | `claude-3-5-sonnet` | `ANTHROPIC_API_KEY` or OAuth (`ANTHROPIC_OAUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN`) |
-| OpenAI | `gpt-4o` / `openai/<model>` | `OPENAI_API_KEY` or `OPENAI_OAUTH_TOKEN` |
-| Gemini | `gemini-2.5-flash` | `GEMINI_API_KEY` or `GEMINI_OAUTH_TOKEN` |
-| Ollama (local) | `ollama/qwen2.5:0.5b` | none — offline via `OLLAMA_HOST` (default `http://localhost:11434`) |
-| OpenAI-compatible (LM Studio / vLLM / llama.cpp) | `openai/<model>` | optional key; set `openaiBaseUrl` / `OPENAI_BASE_URL` |
+Retry behavior is tunable via `retry` in `~/.jeo/config.json` (`requestMaxRetries`, `streamMaxRetries`, `rateLimitRetries`, `failFastStatuses`, …). The step budget is dynamic by default — it extends while recent tool calls show novel progress and consolidates with a wrap-up when stalled; `--max-steps N` restores a bounded flow.
 
-- **Real OAuth (PKCE):** `joc auth login <anthropic|openai|gemini>` opens the provider's
-  authorize URL, runs a local callback server (Anthropic `:54545`, OpenAI `:1455`,
-  Google `:8085`), exchanges the code, and stores `access` + `refresh` + `expires`. Tokens
-  **auto-refresh** on expiry (single-flight); `joc auth refresh <provider>` forces it. On
-  headless boxes, paste the redirect URL/code when prompted, or use
-  `joc auth login <provider> --token <bearer>` for a manual (non-refreshing) token.
-- **Compatibility:** OAuth beats API keys for the same provider, **except** the bundled
-  adapters fall back to the API key when the OAuth flow isn't end-to-end compatible.
-  Anthropic OAuth is verified e2e with the Messages adapter; OpenAI/Google OAuth tokens
-  target the Codex / Cloud-Code-Assist backends, so the bundled chat / generativelanguage
-  adapters prefer an API key (the CLI warns you up front).
-- **Local/offline:** set `JOC_DEFAULT_MODEL=ollama/<model>` after `ollama pull <model>` — no
-  key required. Any OpenAI-compatible endpoint works via `openaiBaseUrl`.
+## Publishing
 
----
+CI publishes via `.github/workflows/npm-publish.yml` — triggered by a published GitHub release, or manually with `workflow_dispatch` (optional dry-run). The workflow typechecks, tests, verifies the token (`npm whoami`), then runs `npm publish --provenance`.
 
-## Configuration
-
-| What | Where |
-| --- | --- |
-| Global config | `~/.joc/config.json` (dir `0700`, file `0600`); override dir with `JOC_CONFIG_DIR` |
-| Per-project runtime | `<cwd>/.joc/` → `seeds/`, `plans/`, `state/`, `sessions/` |
-
-`config.json` fields: `providers`, `oauth`, `defaultModel`, `ollamaBaseUrl`, `openaiBaseUrl`,
-`thinkingLevel` (`minimal`/`low`/`medium`/`high`/`xhigh`), `modelAliases`, `roles` (`smol`/`slow`/`plan`
-model tiers), `subagents` (per-role model/maxSteps), `retry`. Env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
-`GEMINI_API_KEY`, the `*_OAUTH_TOKEN` bearers, `OLLAMA_HOST`, `OPENAI_BASE_URL`,
-`JOC_DEFAULT_MODEL`) fill gaps but never override on-disk values. Verify everything with `joc doctor`.
-
-**Provider retry budgets (gjc parity).** `retry.requestMaxRetries` sets how many times a failed
-provider request is retried (the initial request is not counted); `retry.maxDelayMs` caps the
-exponential backoff. `retry.streamMaxRetries` / `retry.maxRetries` are accepted for gjc-config
-compatibility. Retries apply only to transient failures (network errors, `408/425/429/5xx/529`),
-honoring a server `Retry-After`; auth, bad-model, and malformed-request errors stay fail-fast.
-
-```json
-{ "defaultModel": "claude-3-5-sonnet", "retry": { "requestMaxRetries": 4, "maxDelayMs": 300000 } }
-```
-
----
-
-## Project structure
-
-```text
-jeo-code/
-├── package.json               # name: jeo-code, bin: { joc: src/cli.ts }, bun scripts
-├── tsconfig.json              # strict typecheck config
-├── install.sh                 # top-level shim → scripts/install.sh --local
-├── src/
-│   ├── cli.ts                 # entry: Bun version guard + dispatch
-│   ├── cli/runner.ts          # lazy command registry (bare joc → launch)
-│   ├── commands/              # launch, setup, auth, deep-interview, ralplan, approve, team, ultragoal, doctor, mcp, models, skills, resume, chat
-│   ├── agent/                 # engine (tool loop), loop, json, tools (+MutationGuard), session, compaction, context-files, state
-│   ├── ai/                    # provider adapters (anthropic/openai/gemini/ollama) + model-manager
-│   ├── auth/                  # storage (+auto-refresh), pkce, callback-server, refresh, flows/{anthropic,openai,google}
-│   ├── mcp/                   # MCP protocol + tools + stdio server
-│   └── tui/                   # differential renderer + components + LaunchTui
-├── scripts/                   # install.sh / uninstall.sh (bun install + bun link)
-├── test/                      # 61 suites (372 tests): oauth, engine, tools-fs, retry, config-schema, cli-runner, mutation-guard, approve, team-schema, session, compaction, streaming, evolution, ascii-art, footer, evolve, meter, install, model-discovery/picker/catalog/enrich/roles, provider-status, config-panel, code-view, tui-*
-├── docs/improvements.md       # architectural analysis & changelog (ralph passes)
-├── plan/                      # long-horizon work plans (TUI, features, install, model, provider)
-└── README.md
-```
-
----
-
-## Development
+Required npm token permissions (repository secret `NPM_TOKEN`):
 
-```bash
-bun install                                  # deps: zod (config validation), chalk (doctor colors)
-bun run typecheck                            # tsc -p tsconfig.json --noEmit
-bun test                                     # full suite
-GEMINI_OAUTH_CLIENT_SECRET=<x> bun test      # Google OAuth flow tests need this env var
-```
+- A **Granular Access Token** with Read/Write access to the `jeo-code` package, or a classic **Automation** token
+- "**bypass 2FA** for publishing" must be allowed — Automation tokens always bypass; granular tokens need the option enabled
 
-Design lineage and the milestone roadmap (TUI, features, install, model config, provider)
-live in [`plan/`](./plan/README.md); the running changelog is [`docs/improvements.md`](./docs/improvements.md).
+## Changelog
 
-## License
+<!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
+- **[0.4.3]** (2026-06-13) — Readability pass for autopilot, subagent activity, and worked-history review.
+- **[0.4.2]** (2026-06-13) — Thinking-loop termination guarantees (cycle guard + turn wall-clock budget), unboxed live status without step counters, self-contained `.jeo` namespace, live next-prompt input card, role-targeted model/thinking picker.
+- **[0.4.1]** (2026-06-12) — TUI card parity polish + done-time todo reconciliation.
+- **[0.4.0]** (2026-06-12) — Verified TUI, resilient engine, batch input, multilingual docs.
 
-MIT.
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+<!-- CHANGELOG:END -->

package/README.zh.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <img src="assets/hero.png" alt="jeo-code 自主编码代理主视觉插图" width="100%" />
+</p>
+
+<h1 align="center">jeo-code (jeo)</h1>
+
+<p align="center">
+  <strong>Encode intention. Decode software.</strong><br />
+  基于 Bun 的 AI 编码代理 CLI — 需求访谈、经评审的计划、带门禁的执行、诚实的验证。
+</p>
+
+<p align="center">
+  <a href="https://github.com/akillness/jeo-code"><img alt="license" src="https://img.shields.io/badge/license-MIT-green?style=flat-square"></a>
+  <img alt="runtime" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3.14-f9f1e1?style=flat-square&logo=bun&logoColor=black">
+  <img alt="zero native deps" src="https://img.shields.io/badge/native%20deps-0-blue?style=flat-square">
+</p>
+
+<p align="center">
+  <img src="assets/character.png" alt="jeo-code 吉祥物" width="320" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> ·
+  <a href="README.ko.md">한국어</a> ·
+  <a href="README.ja.md">日本語</a> ·
+  <b>中文</b>
+</p>
+
+在仓库内运行 `jeo`，它会读取文件、编辑代码、执行命令，并把任务推进到完成 — 每一步都通过滚动友好的内联 TUI 实时呈现。
+
+## 亮点
+
+- **多提供商、单一循环** — Anthropic / OpenAI(+Codex) / Gemini / Antigravity / Ollama 统一在一个 JSON 工具循环中。输入框内直接 OAuth 登录(`/provider login`)，模型选择即刻持久化为默认值。
+- **编辑完整性** — read 输出携带内容锚点(`42ab|`)；带锚点的编辑会与当前文件校验、行移动时自动重映射、不匹配时连同最新内容一起拒绝 — 绝不污染文件。
+- **自我修正的验证循环** — 配置 post-edit 钩子(tsc / eslint / 测试)，代理会*亲自读取*诊断并在循环内修复；钩子未通过时 `done` 会被阻断。
+- **没有表演的真实门禁** — `ralplan` 共识由真正读取仓库的 critic 子代理执行，`[OKAY]` 裁决被持久化且 `jeo approve` *强制要求*它；`ultragoal` 诚实报告(套件运行只是全局信号，绝不伪造逐条通过)。
+- **崩溃耐久、本地优先** — 全部状态位于 `.jeo/`，原子写入、跨进程运行锁、失败任务标记 + 恢复时的部分编辑警告。
+- **动态步数预算** — 只要近期工具调用展现新的进展就持续延长，停滞时优雅收敛为总结；子代理保持精确的步数契约。
+- **内联 TUI** — 已完成的工作流入真实滚动缓冲区(回合中也可用 tmux 滚轮)，代理运行时普通查询输入框仍保持可见并可编辑。Ctrl+O 详细信息切换、主题、剪贴板图片粘贴(Ctrl+V)、CJK/表情安全的宽度计算。
+
+## 安装
+
+需要 Bun `1.3.14+`。
+
+```bash
+bun install -g jeo-code
+jeo --version
+```
+
+## 快速开始
+
+```bash
+jeo                      # 在当前仓库启动交互式代理
+jeo "整理 README 并跑测试"   # 单次请求
+jeo doctor               # 配置 + 模型连通性实测
+jeo setup                # API 密钥 / OAuth / 本地模型配置
+jeo --tmux               # 在独立 tmux 会话中运行
+```
+
+## 斜杠命令
+
+在 `jeo` REPL 中使用(Tab 补全，输入 `/` 打开面板)。
+
+| 命令 | 说明 |
+| --- | --- |
+| `/model` · `/provider` | 选择模型/提供商；`/model` 在一个流程内显示默认/角色徽章、Ralph 风格嵌套角色·thinking 选择与 OpenAI Codex 角色预设 |
+| `/provider login <name>` · `/logout` | 在输入框内 OAuth 登录/登出 |
+| `/agents [role]` · `/subagent` | 按角色(executor/planner/architect/critic)配置模型·thinking·步数 |
+| `/thinking [level]` | 查看/设置默认推理预算(minimal…xhigh) |
+| `/fast [on|off|status]` | 当前模型支持 minimal/low 推理时切换 fast thinking 模式 |
+| `/skill` · `$<skill> [intent]` | 列出/运行工作流技能(`$team "任务"` 风格) |
+| `/view` · `/diff` · `/find` · `/search` | 代码查看、git diff、文件/模式搜索 |
+| `/new` · `/resume` · `/sessions` | 会话管理 |
+| `/history [n|all]` · `/export` | 将可读的工作活动历史重新输出到滚动区 · 导出记录 |
+| `/retry` · `/btw <问题>` | 重试上次请求 · 不写入历史的旁路提问 |
+| `/usage` · `/context` · `/compact` | Token 用量、上下文明细、手动压缩 |
+| `/theme` · `/config` · `/help` | 主题、运行时配置、帮助 |
+| `jeo autopilot status` | 显示分数方向、keep/revert 次数和下一步动作的 ratchet 状态字段 |
+
+## Spec-first 工作流
+
+需求 → 计划 → 批准 → 执行 → 验证，经由 `.jeo/state/` 串联，每次交接都有**可阻断的真实门禁**:
+
+```bash
+jeo deep-interview "描述你想构建的东西"
+jeo ralplan
+jeo approve <计划路径>
+jeo team
+jeo ultragoal
+```
+
+- **deep-interview** — 基于歧义度评分的苏格拉底循环；只有标准足够具体才冻结种子(纯含糊标准会被拒绝)，且种子必须通过自身解析器的往返校验。新想法绝不会静默复用已完成的访谈。
+- **ralplan** — 起草阶段 + **真正读取仓库的 critic 子代理门禁**: 强制并持久化 `[OKAY]`/`[ITERATE]`/`[REJECT]` 裁决。无效计划(schema、未知角色)不会被标记为 complete。
+- **approve** — 校验 `team` 执行的确切契约(schema+角色)，并要求持久化的 `[OKAY]` 共识裁决。
+- **team** — 串行计划执行器: 跨进程运行锁、过期计划重置、按任务的子代理契约、父侧变更审计(零写入的"完成"会被标记)、失败标记 + 恢复时的部分编辑警告。
+- **ultragoal** — 诚实验证: 套件作为全局信号只运行一次，标准只被记录，绝不伪造为逐条通过。
+
+## 验证钩子(自我修正)
+
+先全局启用一次(在 `~/.jeo/config.json` 中设置 `"hooks": { "enabled": true }`)，再为项目添加 post-edit 检查，代理会读取失败并在 `done` 之前修复:
+
+```jsonc
+// .jeo/hooks.json
+{
+  "enabled": true,
+  "hooks": [
+    { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
+  ]
+}
+```
+
+非零退出钩子的输出会附加到模型读取的工具结果中(批内去重)；钩子未通过就调用 `done` 会收到带钩子名称的回推。
+
+## 本地模型
+
+```bash
+ollama pull qwen2.5:0.5b
+export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
+jeo doctor && jeo
+```
+
+## 配置
+
+- 全局配置: `~/.jeo/config.json`(模型选择 MRU 持久化)
+- 项目状态/会话: `<project>/.jeo/`
+
+```bash
+ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
+JEO_DEFAULT_MODEL=...           # 例: ollama/qwen2.5:0.5b
+OLLAMA_HOST=http://localhost:11434
+JEO_TUI_THEME=cosmic            # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura
+JEO_TUI_ALT_SCREEN=1            # 旧版 alt-screen 回合(默认: 内联滚动缓冲)
+JEO_STEP_BASE=24                # 动态步数预算的滚动基数
+JEO_STEP_HARD_CAP=600           # 绝对终止保证
+JEO_STREAM_MAX_MS=300000        # 可选的整体流截止(默认关闭; 约束慢滴流)
+JEO_TOOL_OUTPUT_MAX=4000        # 模型可见的工具输出上限(全文溢出到 artifacts)
+```
+
+重试行为通过 `~/.jeo/config.json` 的 `retry` 调整(`requestMaxRetries`、`streamMaxRetries`、`rateLimitRetries`、`failFastStatuses` 等)。步数预算默认动态 — 只要看到新的进展就延长，停滞时收敛为总结；`--max-steps N` 恢复有界流程。
+
+## 发布 (Publishing)
+
+CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release 时自动触发，或手动 `workflow_dispatch`(可选 dry-run)。工作流执行类型检查、测试、令牌校验(`npm whoami`)后运行 `npm publish --provenance`。
+
+所需 npm 令牌权限(仓库 secret `NPM_TOKEN`):
+
+- 对 `jeo-code` 包具有 Read/Write 权限的 **Granular Access Token**，或经典 **Automation** 令牌
+- 必须允许"发布时 **bypass 2FA**" — Automation 令牌始终绕过，granular 令牌需启用该选项
+
+## 更新日志 (Changelog)
+
+<!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.4.4]** (2026-06-13) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
+- **[0.4.3]** (2026-06-13) — Readability pass for autopilot, subagent activity, and worked-history review.
+- **[0.4.2]** (2026-06-13) — Thinking-loop termination guarantees (cycle guard + turn wall-clock budget), unboxed live status without step counters, self-contained `.jeo` namespace, live next-prompt input card, role-targeted model/thinking picker.
+- **[0.4.1]** (2026-06-12) — TUI card parity polish + done-time todo reconciliation.
+- **[0.4.0]** (2026-06-12) — Verified TUI, resilient engine, batch input, multilingual docs.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+<!-- CHANGELOG:END -->