docs: define Ayatori platform vision

docs/concepts/api-design.md

@@ -0,0 +1,39 @@
+# API 设计原则
+
+## 合理抽象
+
+API 应当比后端简单，但不能剥夺自用场景真正需要的控制力。
+
+- 用户主动做出的资源决策进入产品 API。
+- 平台稳定的运维策略进入 Profile、Class 或 Policy。
+- 能够稳定推导的机械参数由 adapter 生成。
+- 罕见但合理的特殊需求使用受控 override。
+- 解析结果、外部 ID 和后端摘要通过只读 status 展示。
+
+例如 VM 用户可以指定 CPU、内存、磁盘、存储、镜像和逻辑网络；QEMU machine type、
+cloud-init 设备、bridge/VLAN 映射和默认 placement 由平台维护。
+
+## 不做虚假可移植性
+
+允许 API 表达当前真实后端的有用能力，但不接受任意 `rawConfig` 透传。未来出现第二个
+真实实现时，根据已经观察到的共同语义抽象，而不是预先猜测最低公分母。
+
+## 引用与依赖
+
+- 使用 typed reference 表达资源依赖，不复制动态地址和外部 ID。
+- 被引用资源暂时不存在或未 Ready 时，controller 应等待而不是要求 apply 顺序。
+- 长期依赖通过 API 关系推导；Flux `dependsOn` 只用于确实需要的提交顺序。
+
+## 生命周期基线
+
+所有受管资源必须定义：
+
+- `observedGeneration`
+- 结构化 `status.conditions`
+- ownership 与外部资源标识
+- finalizer 与删除策略
+- import/adopt/observe 行为
+- controller 重启后的恢复行为
+- 可重试错误与需要人工介入错误的区别
+
+对数据库、bucket、持久磁盘等资源，默认删除行为必须保守并显式表达。

docs/concepts/environments.md

@@ -0,0 +1,24 @@
+# 环境与发布
+
+Ayatori 从第一天维护 Dev 与 Prod 两套控制面，因为首个稳定产品能力会立即承载真实服务，
+同时后续能力仍需要破坏性集成测试。
+
+```text
+source commit
+   ↓
+immutable artifact
+   ↓
+Dev deployment + integration tests
+   ↓
+promotion review
+   ↓
+Prod deployment of the same artifact
+```
+
+不维护长期漂移的环境分支。Git 中分别声明 Dev 与 Prod 当前采用的不可变制品版本或 digest。
+
+Dev 应连接真实后端，但使用独立身份、地址空间和资源范围。Dev 凭据在后端权限层面不应
+具备修改 Prod 资源的能力。
+
+当前手工管理的基础设施视为 legacy 数据面，由 Prod 逐项 import/adopt 或替换；它不是
+第三套 Ayatori 控制面。

docs/concepts/execution-model.md

@@ -0,0 +1,48 @@
+# 执行模型
+
+Ayatori 将执行者统一视为具有不同能力与延迟特性的 executor。
+
+```text
+Action
+├── Machine executor
+│   ├── Kubernetes Pod
+│   ├── OpenSandbox
+│   ├── Terraform
+│   └── Ansible
+└── Human executor
+    └── Versioned Runbook
+```
+
+## Job 与 Sandbox
+
+`Job` 表达一次有限时长、有退出结果的批处理。第一执行后端是 Kubernetes Pod，第二
+执行后端通过 OpenSandbox API 获得强隔离环境。调用者表达资源、隔离与 capability
+需求，由调度策略选择后端。
+
+`Sandbox` 表达带 TTL 的交互环境，可提供 shell、文件、快照或临时 endpoint。它与
+`Job` 共享镜像、资源、网络、凭据和回收能力，但具有不同生命周期，不合并为带大量
+互斥字段的上帝资源。
+
+## 人工执行
+
+无法自动化的步骤使用 `ManualTask` 建模：
+
+```text
+Pending → Claimed → InProgress → Reported → Verifying → Succeeded
+```
+
+通知 controller watch 待处理任务，并发送到 Telegram、Email 或 UI。人依据绑定版本的
+Runbook 操作后提交 `TaskReport`；人只报告执行结果，不直接宣告系统状态成功。
+
+验证 controller 必须 observe 后端并验证证据，验证成功后更新 status，上游 reconcile
+自然继续。人工步骤因此是高延迟异步处理，而不是控制面之外的黑洞。
+
+## 自动化演进
+
+人工任务未来可以替换为机器 Job，但上游工作流不应改变：
+
+```text
+executor: Human  →  executor: Job
+```
+
+平台优先做到任务可建模、可通知、可追踪、可验证和可恢复，再逐步降低人工参与。