Establish the Koi Swagger parser release

Prepare the OpenAPI parser and Dart generator as a publishable Koi package with CLI entrypoint, docs, examples, tests, and pub.dev release metadata.

Constraint: Initial GitHub import follows koi_blueprint_flutter identity mr.koi <i@mrkoi.is>.

Rejected: Keep local runtime state in the initial repository | .dart_tool, .omx, and pubspec.lock are ignored for a reusable package source tree.

Confidence: high

Scope-risk: moderate

Directive: Keep generated-output behavior covered by parser and generator tests before changing rendering rules.

Tested: dart analyze; dart test; PUB_HOSTED_URL=https://pub.dev dart pub publish --dry-run

Not-tested: End-to-end downstream build_runner compilation of generated Retrofit/Freezed output.

README.md

@@ -0,0 +1,137 @@
+# koi_swagger_parser
+
+`koi_swagger_parser` 是一个面向 Koi 生态的新一代 OpenAPI 解析与 Dart 代码生成器，目标不是继续修补旧式 Swagger 生成链，而是为未来的 `koi_blueprint_flutter` 提供一套更稳、更清晰、更可扩展的基础设施。
+
+当前版本聚焦 Koi/FastAPI 场景，优先解决这几类问题：
+
+- OpenAPI 3.1 下 `anyOf[T, null]`、`type: [T, null]` 的 nullable 解析。
+- FastAPI `code/message/data` 成功 envelope 的识别与外部泛型包装。
+- `multipart/form-data` 请求体生成 `@MultiPart()` + `@Part()`，并按 preset 选择二进制类型。
+- `oneOf` / `anyOf` + discriminator 生成 sealed union wrapper。
+- 以 Koi 目录结构输出 `api/`、`api_models/request|result|shared|enums/`。
+- 兼容旧版 `generator_config.yaml`，平滑替换 `swagger_generator_flutter`。
+
+## 设计目标
+
+- 解析层和 Koi 业务约束解耦：parser core 不硬编码 `BaseResult`。
+- 先产出中间表示（IR），再做 Koi 风格渲染，方便未来扩展到 `koi_blueprint_flutter`。
+- 默认以 Retrofit + Freezed 为输出基线，但 response wrapper 可配置。
+- 对 FastAPI/SQLAlchemy 风格服务端有良好适配，同时不把服务端补丁写死在生成器里。
+
+## 配置文件
+
+推荐使用 `koi_swagger_parser.yaml`：
+
+```yaml
+input:
+  swagger_urls:
+    - url: ./openapi.json
+      enabled: true
+
+output:
+  base_dir: ./lib/src
+  api_dir: ./lib/src/api
+  models_dir: ./lib/src/api_models
+  included_tags:
+    - auth
+    - stores
+    - materials
+  split_by_tags: true
+  extract_version_from_url: false
+
+generation:
+  preset:
+    name: koi_flutter
+  api:
+    enabled: true
+    use_retrofit: true
+    cancel_token_support: true
+    client:
+      class_name: DbaApiClient
+      file_name: dba_api_client
+    response_wrapper:
+      mode: external_generic
+      success_data_field: data
+      detect_standard_envelope: true
+      external_generic:
+        import: package:dba_network/dba_network.dart
+        class_name: BaseResult
+  models:
+    enabled: true
+    class_prefix: Koi
+    default_non_nullable_list_to_empty: true
+    json_serializable:
+      checked: true
+      explicit_to_json: true
+      include_if_null: false
+formatting:
+  run_dart_format: true
+```
+
+也兼容旧版 `generator_config.yaml`：
+
+- `generation.api.base_result_import` 会自动映射为 `response_wrapper.mode = external_generic`。
+- `output.included_tags`、`generation.models.class_prefix` 等旧字段会继续生效。
+
+## 命令行
+
+```bash
+dart run koi_swagger_parser generate --all
+```
+
+常用参数：
+
+- `--config`：指定配置文件路径。
+- `--cwd`：指定工作目录。
+- `--dry-run`：只解析与渲染，不落盘。
+- `--verbose`：打印更多诊断信息。
+
+## 输出结构
+
+默认会生成：
+
+```text
+lib/src/
+  api/
+    dba_api_client.dart
+    index.dart
+    v1/
+      index.dart
+      auth_api.dart
+      stores_api.dart
+  api_models/
+    api_models.dart
+    request/
+    result/
+    shared/
+    enums/
+```
+
+## 当前能力
+
+当前版本已经覆盖 Koi 当前最需要的能力：
+
+- OpenAPI 3.1 文档加载（本地 JSON/YAML、远程 URL、多 source merge）。
+- `object` / `array` / `enum` / `additionalProperties` / `allOf` 基础支持。
+- nullable query/path/body 字段解析。
+- FastAPI envelope 检测与 `BaseResult<T>` 外部包装。
+- `multipart/form-data` 生成 `MultipartFile` / `File` / `Uint8List` / `String` 等 preset 驱动参数。
+- `oneOf` / `anyOf` + discriminator 生成 sealed union wrapper，并可被其他模型继续引用。
+- Retrofit API 文件、Freezed 模型文件、分组 index 文件生成。
+
+下一阶段可以继续往前加：
+
+- 更丰富的 multipart metadata（如 encoding / runtime fileName / contentType preset）。
+- 无 discriminator 的更强联合类型兜底策略。
+- 更多 preset（例如 Chopper / blueprint preset / 网络层集成 preset）。
+- 与 `koi_blueprint_flutter` 的一键联动模板。
+
+## 开发与验证
+
+```bash
+dart pub get
+dart format .
+dart test
+```
+
+架构设计说明见 `doc/ARCHITECTURE.md`。