From 7e94452fe48171e06ab81176c76be19649d5940b Mon Sep 17 00:00:00 2001
From: SikongJueluo <selfconfusion@gmail.com>
Date: Wed, 16 Sep 2026 21:36:09 +0800
Subject: [PATCH] docs: add bilingual README

- add an English README and a Chinese translation with cross links,
  following the standard README.zh-CN.md convention
- cover packages, install prerequisites (authorizer chain), development
  workflow, and license
---
 README.md       | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 README.zh-CN.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 README.md
 create mode 100644 README.zh-CN.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..22425b0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# pi-extensions
+
+English | [简体中文](README.zh-CN.md)
+
+Personal extensions for the [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) coding agent, focused on Bash permissions: unwrap, inspect, and re-adjudicate commands before they run.
+
+## Packages
+
+| Package | Description |
+|---|---|
+| [pi-permission-ai-judge](packages/pi-permission-ai-judge) | AI judge — a model rules allow / deny / defer on each pending Bash ask; shadow logs only, enforce auto-approves |
+| [pi-permission-inner-cmd](packages/pi-permission-inner-cmd) | Unwraps transparent Bash wrappers (`timeout`, `time`, …) and authorizes the inner command |
+
+## Install
+
+```bash
+pi install git:github.com/SikongJueluo/pi-extensions
+```
+
+The package manifest (root `package.json`, `pi.extensions`) mounts both extensions declaratively — effective in any directory. Prerequisites:
+
+1. Enable [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) ≥ 32
+2. Add the extensions to the authorizer chain — order is consultation order, UI sessions only:
+
+```jsonc
+// ~/.pi/agent/extensions/pi-permission-system/config.json
+{ "authorizerChain": ["inner-cmd", "ai-bash-judge"] }
+```
+
+See the ai-judge [README](packages/pi-permission-ai-judge/README.md) for modes, judge model, and guardrails.
+
+## Development
+
+pnpm workspace, TypeScript + vitest.
+
+```bash
+pnpm install
+pnpm check   # tsc --noEmit
+pnpm test    # vitest run
+```
+
+Design decisions live in [docs/adr/](docs/adr/).
+
+## License
+
+GPL-3.0
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..c15465b
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,46 @@
+# pi-extensions
+
+[English](README.md) | 简体中文
+
+[pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 编码代理的个人扩展集，专注 Bash 权限：放行前拆包、审视、再审。
+
+## 包
+
+| 包 | 说明 |
+|---|---|
+| [pi-permission-ai-judge](packages/pi-permission-ai-judge) | AI 判官。模型对每条待确认的 Bash 命令给出 allow / deny / defer；shadow 只记日志，enforce 代批放行 |
+| [pi-permission-inner-cmd](packages/pi-permission-inner-cmd) | 解包透明包装命令（`timeout`、`time` 等），按内层命令授权 |
+
+## 安装
+
+```bash
+pi install git:github.com/SikongJueluo/pi-extensions
+```
+
+包清单（根 `package.json` 的 `pi.extensions`）声明式挂载两个扩展，任意目录生效。前提：
+
+1. 启用 [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) ≥ 32
+2. 把扩展挂进授权链——顺序即咨询顺序，仅 UI 会话生效：
+
+```jsonc
+// ~/.pi/agent/extensions/pi-permission-system/config.json
+{ "authorizerChain": ["inner-cmd", "ai-bash-judge"] }
+```
+
+ai-judge 的模式、判官模型与防线见其 [README](packages/pi-permission-ai-judge/README.md)。
+
+## 开发
+
+pnpm workspace，TypeScript + vitest。
+
+```bash
+pnpm install
+pnpm check   # tsc --noEmit
+pnpm test    # vitest run
+```
+
+设计决策见 [docs/adr/](docs/adr/)。
+
+## License
+
+GPL-3.0