chore: establish contribution branch flow

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @WaylandYang

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- Explain the problem, root cause, and the scoped change. -->
+
+## Branch flow
+
+- [ ] This PR is `feat/**` → `dev`, or `@WaylandYang`'s `dev` → `main` promotion PR.
+- [ ] This PR does not bypass the required integration path with a direct feature → `main` merge.
+
+## Validation
+
+<!-- List the exact commands run and their results. -->
+
+- [ ] Backend tests and ontology guards pass when affected.
+- [ ] Frontend lint/build pass when affected.
+- [ ] Documentation and configuration examples are updated when affected.
+- [ ] UI changes include current screenshots.
+- [ ] English and Chinese user-facing copy are updated together.
+
+## Compatibility and security
+
+- [ ] No credentials, `.env` files, production data, runtime data, benchmark caches, or generated exports are included.
+- [ ] Public API, MCP, release-manifest, provenance, or configuration changes include compatibility notes and tests.

.github/workflows/ci.yml

@@ -2,9 +2,39 @@ name: CI
 
 on:
   push:
+    branches:
+      - main
+      - dev
   pull_request:
+    branches:
+      - main
+      - dev
 
 jobs:
+  branch-flow:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate pull request branch flow
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          HEAD_BRANCH: ${{ github.head_ref }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          if [[ "$BASE_BRANCH" == "dev" && "$HEAD_BRANCH" == feat/* ]]; then
+            echo "Valid feature flow: $HEAD_BRANCH -> $BASE_BRANCH"
+            exit 0
+          fi
+
+          if [[ "$BASE_BRANCH" == "main" && "$HEAD_BRANCH" == "dev" && "$PR_AUTHOR" == "WaylandYang" ]]; then
+            echo "Valid owner release flow: $HEAD_BRANCH -> $BASE_BRANCH"
+            exit 0
+          fi
+
+          echo "Invalid pull request branch flow: $HEAD_BRANCH -> $BASE_BRANCH"
+          echo "Allowed flows are feat/** -> dev and owner-authored dev -> main."
+          exit 1
+
   backend:
     runs-on: ubuntu-latest
     defaults:

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to OntoPilot are documented in this file. The project follows
+[Semantic Versioning](https://semver.org/) while it evolves toward a stable 1.0 release.
+
+## [0.1.0] - 2026-08-13
+
+Initial public release.
+
+### Added
+
+- A self-hosted workspace for building TBox, SKOS terminology, and ABox data from source documents.
+- Governed human–AI review queues for conflicts, entity resolution, terminology, and ABox validation.
+- Evidence and provenance linking statements to documents, chunks, models, prompt snapshots, actors, and review actions.
+- Versioned ontology releases with semantic Diff, immutable published snapshots, deployment, restore, and layered exports.
+- User- and knowledge-system-scoped REST and MCP access for read, proposal, edit, review, and lifecycle workflows.
+- English and Simplified Chinese interfaces, documentation, and independently configurable backend prompt languages.
+- Docker Compose deployment, source-development workflows, benchmark suites, and operator documentation.
+
+[0.1.0]: https://github.com/deeplethe/ontopilot/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -4,6 +4,41 @@ Thank you for helping build an open, reliable ontology-governance system.
 
 Participation in this project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
 
+[中文贡献指南](#中文贡献指南)
+
+## Required Branch Flow
+
+Every change must follow this branch flow:
+
+```text
+feat/**  →  dev  →  main
+```
+
+1. Update local `dev` and create a branch whose name starts with `feat/`. Do not develop directly on `dev` or `main`.
+2. Open a pull request from `feat/**` into `dev`. Pull requests from any other source into `dev` fail the branch-flow CI check.
+3. After review and all required checks pass, merge the feature pull request into `dev`.
+4. Only the project owner, GitHub user `@WaylandYang`, promotes `dev` to `main` through a `dev` → `main` pull request. Contributors must not open feature pull requests directly against `main` or merge `dev` into `main` themselves.
+
+Start work with:
+
+```bash
+git fetch origin
+git switch dev
+git pull --ff-only origin dev
+git switch -c feat/<short-description>
+```
+
+Push and open the feature pull request with:
+
+```bash
+git push -u origin feat/<short-description>
+gh pr create --base dev --head feat/<short-description>
+```
+
+Use lowercase, hyphen-separated branch descriptions, for example `feat/review-date-filters`. A branch under `feat/**` may contain product work, fixes, documentation, tests, refactors, or maintenance needed for one scoped pull request; the prefix describes the required integration path, not only user-facing features.
+
+Direct pushes to `dev` and `main` are prohibited. The repository CI validates pull-request topology. GitHub branch rules should additionally require pull requests, passing checks, and code-owner review whenever the repository plan supports protected private branches.
+
 ## Before You Start
 
 - Use GitHub Issues for reproducible bugs, focused feature proposals, and design discussion.
@@ -68,6 +103,7 @@ The release manifest, N-Quads shard naming, and provenance JSONL are public inte
 
 ## Pull Requests
 
+- Target `dev` from a `feat/**` branch; only the project owner may target `main` from `dev`.
 - Describe the problem and root cause.
 - List the validation commands you ran.
 - Include screenshots for user-interface changes.
@@ -76,3 +112,53 @@ The release manifest, N-Quads shard naming, and provenance JSONL are public inte
 - Do not commit `.env`, runtime data, benchmark caches, generated exports, or credentials.
 
 By submitting a contribution, you agree that it is licensed under Apache License 2.0.
+
+## 中文贡献指南
+
+感谢你参与建设开放、可靠的本体治理系统。参与本项目即表示你同意遵守[行为准则](CODE_OF_CONDUCT.md)，提交的贡献采用 Apache License 2.0。
+
+### 强制分支流程
+
+所有改动必须遵循：
+
+```text
+feat/**  →  dev  →  main
+```
+
+1. 从最新的 `dev` 创建以 `feat/` 开头的分支，禁止直接在 `dev` 或 `main` 上开发。
+2. 从 `feat/**` 向 `dev` 发起 Pull Request；其他来源分支提交到 `dev` 会被 CI 的分支流检查拒绝。
+3. 代码审核和全部检查通过后，将功能 PR 合并到 `dev`。
+4. 只有项目所有者 GitHub 用户 `@WaylandYang` 可以通过 `dev` → `main` Pull Request 发布到 `main`。贡献者不得把功能分支直接提交到 `main`，也不得自行将 `dev` 合并到 `main`。
+
+开始开发：
+
+```bash
+git fetch origin
+git switch dev
+git pull --ff-only origin dev
+git switch -c feat/<简短描述>
+```
+
+推送并创建 PR：
+
+```bash
+git push -u origin feat/<简短描述>
+gh pr create --base dev --head feat/<简短描述>
+```
+
+分支描述使用小写英文和连字符，例如 `feat/review-date-filters`。`feat/**` 是统一的集成路径前缀；一个范围明确的 PR 即使主要内容是 Bug 修复、文档、测试、重构或维护，也使用该前缀。
+
+禁止直接推送到 `dev` 和 `main`。仓库 CI 会校验 PR 的源分支和目标分支；当 GitHub 套餐支持私有仓库保护规则时，还应在服务端强制 PR、通过状态检查和 Code Owner 审核。
+
+### 提交前检查
+
+请按上文的开发环境步骤安装依赖，并运行“Required Checks”列出的后端测试、TBox 守卫、前端检查、构建和 Compose 校验。涉及抽取边界、发布清单或溯源格式的改动，还必须满足对应章节中的回归与兼容要求。
+
+### Pull Request 要求
+
+- 清楚描述问题、根因和改动范围。
+- 列出已经运行的验证命令和结果。
+- 界面改动附真实截图。
+- 中英文界面文案同步更新。
+- 行为或配置变化同步更新文档。
+- 不得提交 `.env`、运行数据、Benchmark 缓存、生成的导出文件或任何凭据。

README.md

@@ -6,10 +6,10 @@
 
 Build, review, version, publish, and serve TBox, SKOS terminology, and ABox data from one self-hosted workspace.
 
-[简体中文](README.zh-CN.md) · [Documentation](#documentation) · [Architecture](docs/architecture.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md)
+[简体中文](README.zh-CN.md) · [Documentation](#documentation) · [Architecture](docs/architecture.md) · [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md)
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-007595)](LICENSE)
-![Release](https://img.shields.io/badge/status-pre--1.0-f59e0b)
+[![Release](https://img.shields.io/badge/release-v0.1.0-2563eb)](CHANGELOG.md)
 ![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)
 ![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=111827)
 ![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white)
@@ -25,6 +25,7 @@ Build, review, version, publish, and serve TBox, SKOS terminology, and ABox data
 <summary><strong>Contents</strong></summary>
 
 - [Why OntoPilot](#why-ontopilot)
+- [Benchmark Highlight](#benchmark-highlight)
 - [Capabilities](#capabilities)
 - [Product Interface](#product-interface)
 - [How It Works](#how-it-works)
@@ -44,14 +45,30 @@ Build, review, version, publish, and serve TBox, SKOS terminology, and ABox data
 
 ## Why OntoPilot
 
-LLMs can propose ontology content quickly, but production ontology work also needs boundaries, evidence, review, access control, and stable delivery. OntoPilot treats model output as a governed proposal—not an unquestioned final artifact.
+OntoPilot is an ontology production workspace for companies and domain teams that need to turn knowledge buried in policies, manuals, product specifications, research, and operational documents into structured ontology data—fast.
 
-- **TBox stays conceptual.** Independent role critics and domain-neutral guards keep named individuals and literal values out of the schema.
-- **ABox stays scalable.** Instances live in a separate graph and export asynchronously as checksummed N-Quads shards.
-- **Terminology stays governed.** OWL entities map to SKOS concepts; uncertain aliases, mappings, and hierarchy changes enter human review.
-- **Every decision stays traceable.** Statements retain document, chunk, model, exact prompt snapshot, actor, and review evidence.
-- **Published versions stay immutable.** Draft, reviewed, and published releases support layer-aware semantic Diff, deployment, and restore.
-- **Agents stay accountable.** Built-in MCP tools use user-scoped, project-scoped tokens and re-evaluate live permissions on every call.
+It goes beyond asking an LLM to “generate an ontology.” OntoPilot puts domain experts, reviewers, and agents on the same production line: **AI reads and drafts at scale, people resolve ambiguity and make accountable decisions, and the platform governs evidence, permissions, versions, and releases.** The result is not a one-off model response, but a living knowledge asset that can be reviewed, published, served, and continuously evolved.
+
+- **From documents to computable domain knowledge.** Convert scattered language into a connected TBox, SKOS terminology, and ABox while retaining the source behind every statement.
+- **Human–AI co-creation with governance built in.** Models propose; experts review, correct, and approve through focused queues instead of rebuilding machine output by hand.
+- **From a promising draft to a production asset.** Semantic Diff, immutable releases, rollback, REST APIs, and MCP carry approved knowledge into business systems and agent workflows.
+- **Traceable by design, not by afterthought.** Every decision can be traced to its document chunk, model, prompt snapshot, actor, and review history.
+
+## Benchmark Highlight
+
+### Gains across directly comparable projects
+
+| Protocol F1 | Wine<br>Food & Beverage | GeoNames<br>Geography | OWL-Time<br>Units & Measurements |
+| --- | ---: | ---: | ---: |
+| OntoLearner reference · Qwen3-8B | 18.60%¹ | 19.70%¹ | 14.08%² |
+| **OntoPilot evaluation · Qwen3-8B** | **28.95%** | **27.03%** | **16.67%** |
+| **Improvement** | **+10.35 pp / +55.6%** | **+7.33 pp / +37.2%** | **+2.58 pp / +18.3%** |
+| Result | **New SOTA** | Same-model lead | Prompt gain |
+
+¹ OntoLearner paper result. ² Controlled OntoLearner-prompt baseline because the paper does not
+report OWL-Time individually. Wine and OWL-Time use OntoPilot's frozen prompt; GeoNames currently
+uses the unchanged OntoLearner prompt in our adapter. See the
+[benchmark methodology and full results](docs/benchmarks/ontolearner-multidomain.md).
 
 ## Capabilities
 
@@ -124,7 +141,7 @@ SQLite is supported for single-process local development. PostgreSQL is the supp
 ### Requirements
 
 - Docker Engine 27+ with Docker Compose v2
-- About 4 GB of free memory for a comfortable build and first start
+- At least 2 GB of available memory; 4 GB is recommended for smoother Docker builds and startup
 - An OpenAI-compatible API credential for extraction; the application can start without one
 
 ### 1. Configure
@@ -341,7 +358,7 @@ cd ..
 docker compose config --quiet
 ```
 
-The gold set covers recurring TBox/ABox boundary failures such as named countries, regions, organizations, admission plugins, reusable Kubernetes kinds, and XSD datatypes. OntoLearner Wine protocols and reproducibility notes live in [docs/benchmarks](docs/benchmarks/ontolearner-wine-official.md). Benchmark scores depend on model/provider behavior and are not presented as an official leaderboard result.
+The gold set covers recurring TBox/ABox boundary failures such as named countries, regions, organizations, admission plugins, reusable Kubernetes kinds, and XSD datatypes. Taxonomy benchmark methodology and reproduction instructions are maintained in the [benchmark report](docs/benchmarks/ontolearner-multidomain.md).
 
 See [docs/acceptance.md](docs/acceptance.md) for the manual end-to-end acceptance path.
 

README.zh-CN.md

@@ -6,10 +6,10 @@
 
 在一个自托管工作台中完成 TBox、SKOS 术语、ABox 的构建、审阅、版本化、发布与服务。
 
-[English](README.md) · [文档](#文档与接口) · [架构](docs/architecture.md) · [路线图](ROADMAP.md) · [参与贡献](CONTRIBUTING.md) · [行为准则](CODE_OF_CONDUCT.md) · [安全策略](SECURITY.md)
+[English](README.md) · [文档](#文档与接口) · [架构](docs/architecture.md) · [更新日志](CHANGELOG.md) · [路线图](ROADMAP.md) · [参与贡献](CONTRIBUTING.md) · [行为准则](CODE_OF_CONDUCT.md) · [安全策略](SECURITY.md)
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-007595)](LICENSE)
-![Release](https://img.shields.io/badge/status-pre--1.0-f59e0b)
+[![Release](https://img.shields.io/badge/release-v0.1.0-2563eb)](CHANGELOG.md)
 ![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)
 ![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=111827)
 ![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white)
@@ -24,7 +24,8 @@
 <details>
 <summary><strong>目录</strong></summary>
 
-- [项目定位](#项目定位)
+- [为什么选择 OntoPilot](#为什么选择-ontopilot)
+- [Benchmark 亮点](#benchmark-亮点)
 - [核心能力](#核心能力)
 - [产品界面](#产品界面)
 - [工作流程](#工作流程)
@@ -42,16 +43,32 @@
 
 </details>
 
-## 项目定位
+## 为什么选择 OntoPilot
 
-大模型可以快速提出本体候选，但真正可用于生产的本体工程还需要边界、证据、审阅、权限和稳定交付。OntoPilot 把模型输出视为“待治理提案”，而不是不经验证的最终结果。
+OntoPilot 是面向企业与业务团队的本体生产工作台：把散落在制度、手册、产品资料、研究成果和业务文档中的知识，快速沉淀为结构化、可计算的本体数据。
 
-- **TBox 保持概念层。** 独立角色判定器和领域无关守卫阻止具体实例、字面量误入模式层。
-- **ABox 可扩展。** 实例位于独立图中，并异步导出为带校验和的 N-Quads 分片。
-- **术语可治理。** OWL 实体映射为 SKOS 概念；不确定的别名、映射和层级进入人工审核。
-- **决策可追溯。** 语句保留文档、chunk、模型、完整提示词快照、操作者和审核证据。
-- **发布版本不可变。** 草稿、已审核和已发布版本支持分层语义 Diff、部署与恢复。
-- **Agent 权责明确。** 内置 MCP 使用“用户 + 知识体系”范围的 Token，并在每次调用时重新检查实时权限。
+它不只是让大模型“生成一份本体”。OntoPilot 把领域专家、审核者与 Agent 放进同一条知识生产线：**AI 负责规模化阅读与起草，人负责消除歧义、校准和决策，平台负责证据、权限、版本与发布治理。** 最终交付的不是一次性的模型回答，而是一套能够被审核、被发布、被系统调用，并持续演进的企业知识资产。
+
+- **从业务文档到可计算的领域知识。** 将分散的自然语言转化为相互关联的 TBox、SKOS 术语与 ABox，同时保留每条语句的原始依据。
+- **让人机协作真正可治理。** 模型规模化提出候选，专家在聚焦的审核队列中修正与裁决，不必从头返工，也不必盲信生成结果。
+- **从“看起来可用”走到生产可用。** 通过语义 Diff、不可变发布、回滚、REST API 与 MCP，把审核后的知识稳定交付给业务系统和 Agent。
+- **可追溯不是补丁，而是底座。** 每项决策都能回到文档 chunk、模型、提示词快照、操作者与完整审核历史。
+
+## Benchmark 亮点
+
+### 在可直接对比项目上的提升
+
+| 协议 F1 | Wine<br>食品与饮料 | GeoNames<br>地理 | OWL-Time<br>单位与度量 |
+| --- | ---: | ---: | ---: |
+| OntoLearner 参照 · Qwen3-8B | 18.60%¹ | 19.70%¹ | 14.08%² |
+| **OntoPilot 评测 · Qwen3-8B** | **28.95%** | **27.03%** | **16.67%** |
+| **提升** | **+10.35 个百分点 / +55.6%** | **+7.33 个百分点 / +37.2%** | **+2.58 个百分点 / +18.3%** |
+| 结论 | **新 SOTA** | 同模型领先 | 提示词提升 |
+
+¹ OntoLearner 论文成绩。² 论文未单列 OWL-Time，因此使用受控的 OntoLearner 提示词基线。
+Wine 和 OWL-Time 使用 OntoPilot 冻结提示词；GeoNames 目前仍使用未修改的 OntoLearner
+提示词运行于我们的适配器。完整方法、六个数据集、消融和复现见
+[Benchmark 方法与完整报告](docs/benchmarks/ontolearner-multidomain.md)。
 
 ## 核心能力
 
@@ -124,7 +141,7 @@ SQLite 适用于单进程本地开发；共享环境和 Docker 部署使用 Post
 ### 环境要求
 
 - Docker Engine 27+ 和 Docker Compose v2
-- 建议至少 4 GB 可用内存，以便顺利构建和首次启动
+- 至少 2 GB 可用内存；建议使用 4 GB，以便更顺畅地完成 Docker 构建和启动
 - 抽取时需要 OpenAI 兼容 API 凭据；没有凭据时应用仍可启动
 
 ### 1. 配置
@@ -341,7 +358,7 @@ cd ..
 docker compose config --quiet
 ```
 
-项目金标覆盖命名国家、地区、组织、准入插件、可复用 Kubernetes Kind、XSD 数据类型等常见 TBox/ABox 边界错误。OntoLearner Wine 协议和可复现说明位于 [docs/benchmarks](docs/benchmarks/ontolearner-wine-official.md)。模型和供应商行为会影响得分，本项目不把该结果表述为官方排行榜成绩。
+项目金标覆盖命名国家、地区、组织、准入插件、可复用 Kubernetes Kind、XSD 数据类型等常见 TBox/ABox 边界错误。Taxonomy 评测方法和复现说明统一维护在 [Benchmark 报告](docs/benchmarks/ontolearner-multidomain.md) 中。
 
 完整人工端到端路径见 [docs/acceptance.md](docs/acceptance.md)。