docs(repo): rewrite readmes and drop internal superpowers docs

Rewrite both README files into usage-first documentation with concrete state, packet, and runtime examples instead of internal planning language.

Remove docs/superpowers from version control and ignore that path so internal planning material is not published to GitHub.

Author: M1hono

.gitignore

@@ -22,6 +22,7 @@ eclipse
 run
 logs
 .worktrees
+docs/superpowers
 
 # Files from Forge MDK
 forge*changelog.txt

README.MD

@@ -2,90 +2,171 @@
 
 [English](README_EN.md)
 
-`PiSerializeKit` 是 Pi 系列的独立序列化基础库。
-
-它负责统一 value codec、NBT codec 与 packet codec 的边界，让多个 Pi 仓库在“如何描述数据”这件事上使用同一套语言，而不是每个模组都重新定义一层。
-
-它也应成为 `PiDataGraph` 对象计数、反应链状态与图节点数据的强类型序列化底座。
-
-## Start Stage 目标
-
-1. 提供稳定的 serializer、type key 与 service 查询接口；
-2. 为 `Pibrary`、`PiNet`、`PiKubeJSCompat` 与未来 engine repos 提供共享序列化边界；
-3. 保持独立仓库身份，不再塞回 `Pibrary` 单体结构；
-4. 把 state schema 与 packet schema 收束到同一套字段语言上。
-
-## 当前已提供
-
-1. `PiSerializer`
-   聚合 value codec、NBT codec、packet codec。
-2. `PiNbtCodec`
-   `CompoundTag` 编解码契约。
-3. `PiPacketCodec`
-   `FriendlyByteBuf` 编解码契约。
-4. `PiSerializerType`
-   稳定的 serializer 类型标识。
-5. `PiSerializeService`
-   注册与查询统一入口。
-6. `PiSerializeServices`
-   当前 runtime service 的安装与获取入口。
-7. `@PiSyncModel` / `@PiField`
-   编译期生成 state binding、projection、delta 与 schema migration 绑定。
-8. `@PiPacket` / `@PiPacketNamespace` / `@PiPacketUpgrade`
-   编译期生成 packet binding、packet provider、packet id、packet version 与 packet migration 链。
-9. `PiSchemas` / `PiPackets`
-   基于 `ServiceLoader` 的 schema / packet runtime registry，可按类型或 packet id 查询。
-10. `PiDecodeContext`
-    结构化 decode 诊断收集器，支持字段路径、fatal 标记与 migration 失败信息。
-11. `PiRuntimeLookupException` / `PiRuntimeConflictException` / `PiRuntimeBootstrapException`
-    统一的 runtime 异常模型，用于缺失绑定、冲突注册与 provider bootstrap 失败，并暴露最小 machine-readable 上下文。
-
-## 作者侧硬约束
-
-第一次写 `@PiSyncModel` / `@PiPacket` 前，当前需要明确这些规则：
-
-1. `@PiSyncModel.version` 与 `@PiPacket.version` 必须 `>= 1`；
-2. schema id 与 packet id 在同一轮编译内必须唯一，重复声明会编译期失败；
-3. `@PiSyncModel`、`@PiPacket`、`@PiLivingService` 必须是 top-level concrete class；
-4. `@PiSyncModel` 需要可访问的无参构造器，且该构造器不能声明 checked exception；
-5. `@PiPacket` 用于生成 decode 的构造器必须和 `@PiField` 顺序匹配，且不能声明 checked exception；
-6. `@PiField(serializer = ...)` provider 需要可访问的无参构造器，且不能声明 checked exception；
-7. `@PiAfterDecode`、`@PiSchemaUpgrade`、`@PiPacketUpgrade` 方法不能声明 checked exception。
-
-## 验证门槛
-
-当前仓库把下面这条命令视为合并前的最低冷验证门槛：
+`PiSerializeKit` 是 Pi 系列里负责“数据怎么写、怎么读、怎么升级、怎么进包”的底层库。
 
-```bash
-bash ./gradlew clean test --no-daemon
+如果你需要下面这些事，就会用到它：
+
+1. 给一个状态类写持久化和同步结构；
+2. 给一个 packet 写稳定 id、版本和 decode 逻辑；
+3. 给某个类型提供统一 serializer；
+4. 在运行时按 authored class 取回对应的 schema binding 或 packet binding。
+
+大多数作者平时只会接触三层东西：
+
+1. 注解：`@PiSyncModel`、`@PiField`、`@PiPacket`
+2. 运行时入口：`PiSchemas`、`PiPackets`、`PiSerializeServices`
+3. 少量 serializer API：`PiSerializer`、`PiSerializers`
+
+你通常不需要手写或直接依赖 `_PiSchema`、`_PiPacket` 这类 generated class。
+
+## 典型用法
+
+### 1. 写一个可持久化、可同步的状态类
+
+```java
+@PiSyncModel(id = "example:mana_state", version = 1)
+public final class ManaState {
+    @PiField(id = "mana", sync = PiSyncScope.TRACKING, persist = true)
+    public int mana;
+
+    @PiField(id = "selected_spell", sync = PiSyncScope.OWNER, persist = true)
+    public String selectedSpell = "";
+}
+```
+
+运行时你拿到的是 binding，而不是自己去找 generated class：
+
+```java
+PiStateBinding<ManaState> binding = PiSchemas.require(ManaState.class);
+
+CompoundTag full = binding.saveFull(state);
+binding.loadFull(restored, full, PiDecodeContext.strict());
+```
+
+如果你只想写默认 client view、persisted view 或 delta，也都走 binding：
+
+```java
+CompoundTag clientView = binding.saveClientView(state);
+CompoundTag persisted = binding.savePersisted(state);
+CompoundTag delta = binding.writeClientDelta(state, dirtySet);
 ```
 
-仓库同时提供 `.github/workflows/ci.yml`，把同一条 `clean test` 变成固定 CI gate，而不是只依赖本地偶尔手跑。
+### 2. 写一个 packet
+
+先在包上提供 namespace，避免每个包都重复写：
+
+```java
+@PiPacketNamespace("example")
+package com.example.packet;
+```
 
-## API 稳定边界
+然后写 packet 本体：
 
-当前建议按下面三层理解兼容边界：
+```java
+@PiPacket
+public final class CastSkillPacket extends PiServerPacket {
+    @PiField(id = "skill", sync = PiSyncScope.OWNER, persist = false)
+    public String skill;
 
-1. 稳定作者 API：
-   `org.pickaid.piserializekit.api.schema`、`api.packet`、`api.service`、`api.runtime`，以及运行时入口 `PiSchemas`、`PiPackets`、`PiSerializeServices`。
-2. 内部实现 API：
-   `processor.*`、`processor.support.*`、`processor.model.*`、`runtime.*.support`、`runtime.*.codec` 等包默认不承诺稳定，不建议下游直接依赖。
-3. 生成物命名边界：
-   `_PiSchema`、`_PiFields`、`_PiPacket`、`_PiPacketProvider` 这类 generated type 主要是编译产物；下游更推荐通过 `PiSchemas` / `PiPackets` 或上层 pack 暴露的 host API 间接消费，而不是把这些名字当手写稳定契约。
+    @PiField(id = "level", sync = PiSyncScope.OWNER, persist = false)
+    public int level;
 
-## 当前明确不做满
+    public CastSkillPacket(String skill, int level) {
+        this.skill = skill;
+        this.level = level;
+    }
+
+    @Override
+    protected void handle(PiServerPacketContext context) {
+    }
+}
+```
+
+运行时同样按 authored class 或稳定 id 取 binding：
+
+```java
+PiPacketBinding<CastSkillPacket, ?> binding = PiPackets.require(CastSkillPacket.class);
+FriendlyByteBuf buf = new FriendlyByteBuf(Unpooled.buffer());
+
+binding.codec().write(buf, new CastSkillPacket("fireball", 2));
+CastSkillPacket decoded = binding.codec().read(buf);
+```
 
-本仓库当前仍然不负责：
-1. channel 安装、发送目标、线程切换与 transport guard；
-2. capability / host runtime 绑定与 gameplay service 生命周期；
-3. 面向具体 UI / render / world runtime 的高层 author magic；
-4. 反射式黑盒自动读写器；
-5. 针对单个 engine 的重度运行时打包逻辑。
+### 3. 安装或临时覆盖 serializer runtime
 
-## 仓库定位
+如果你只是要 built-in serializer：
+
+```java
+PiSerializeRuntime runtime = new PiSerializeRuntime();
+PiBuiltInSerializers.install(runtime);
+PiSerializeServices.install(runtime);
+```
+
+如果你只是想在某个局部逻辑里临时切换 runtime：
+
+```java
+PiSerializeServices.withScope(runtime, () -> {
+    PiSerializer<String> serializer = PiSerializeServices.requireSerializer(PiSerializers.STRING);
+});
+```
+
+这个 scoped override 很适合测试、局部覆盖或上层 pack 做隔离策略。
+
+## 你实际会依赖哪些 API
+
+稳定的作者侧入口主要是这些：
+
+1. `org.pickaid.piserializekit.api.schema.*`
+2. `org.pickaid.piserializekit.api.packet.*`
+3. `org.pickaid.piserializekit.api.service.*`
+4. `org.pickaid.piserializekit.api.runtime.*`
+5. `PiSchemas`
+6. `PiPackets`
+7. `PiSerializeServices`
+
+下面这些默认按内部实现处理，不建议下游直接写死依赖：
+
+1. `processor.*`
+2. `processor.support.*`
+3. `processor.model.*`
+4. `runtime.*.support`
+5. `runtime.*.codec`
+6. generated class 名字本身
+
+## 作者侧规则
+
+第一次写 `@PiSyncModel` / `@PiPacket` 前，先记住这些硬规则：
+
+1. `@PiSyncModel.version` 和 `@PiPacket.version` 必须 `>= 1`
+2. schema id 和 packet id 在同一轮编译里必须唯一
+3. `@PiSyncModel`、`@PiPacket`、`@PiLivingService` 必须是 top-level concrete class
+4. `@PiSyncModel` 需要可访问的无参构造器，而且不能声明 checked exception
+5. `@PiPacket` 的 decode 构造器必须和 `@PiField` 顺序一致，而且不能声明 checked exception
+6. `@PiField(serializer = ...)` provider 需要可访问的无参构造器，而且不能声明 checked exception
+7. `@PiAfterDecode`、`@PiSchemaUpgrade`、`@PiPacketUpgrade` 方法不能声明 checked exception
+
+## 这个库不负责什么
+
+这些事不属于 `PiSerializeKit`：
+
+1. channel 安装、发送目标、线程切换、transport guard
+2. capability / host runtime 绑定
+3. gameplay service 生命周期
+4. UI、render、world 的高层 author magic
+5. 黑盒反射式自动读写
+
+换句话说：
+
+1. `PiSerializeKit` 负责数据如何描述、升级、诊断、绑定
+2. `PiNet` 负责 packet 如何发送、路由、守卫
+3. `Pibrary` 和后续 packs 负责这些 schema / packet 如何进入实际 gameplay host
+
+## 验证
+
+这个仓库当前把下面这条命令当作最低冷验证门槛：
+
+```bash
+bash ./gradlew clean test --no-daemon
+```
 
-1. 这是独立基础仓库；
-2. 它可被多个 Pi repo 直接消费；
-3. 它负责“数据模型如何被描述、升级、诊断与绑定”；
-4. `PiNet` 负责“这些 packet 如何被发送、路由与守卫”；
-5. `Pibrary` 与后续 packs 负责“这些 schema / packet 如何进入具体 gameplay host”。
+仓库里也有 `.github/workflows/ci.yml`，会在 GitHub 上跑同一条 `clean test`。