docs: rewrite README in formal style and rename philosophy section

Author: Reuben-Sun

README.md

@@ -2,37 +2,33 @@
 
 [中文](README.zh-CN.md)
 
-OpenKnowForge is an API-native, Git-backed knowledge base system.
-It connects note authoring, metadata governance, static publishing, and version traceability into one workflow.
+OpenKnowForge is an API-native, Git-backed knowledge engineering system.
+It unifies content generation, metadata governance, static publishing, and version traceability into a single workflow.
 
 ## OpenClaw-First Workflow (No Manual Note Writing)
 
-This project is designed to run with OpenClaw as the primary authoring engine.
-Human users do not need to manually write notes in markdown files.
+The project is designed around OpenClaw as the primary authoring engine.
+In normal operation, notes are not manually drafted one by one; OpenClaw handles creation and maintenance through APIs.
 
 Install this skill in OpenClaw first:
 
-- OpenKnowForge Skill: `https://github.com/Reuben-Sun/OpenKnowForge-Skill.git`
+- OpenKnowForge-Skill: `https://github.com/Reuben-Sun/OpenKnowForge-Skill.git`
 
-Recommended operating model:
+Recommended workflow:
 
-1. Install `OpenKnowForge-Skill` in OpenClaw from the repository above.
-2. Let OpenClaw create, edit, classify, and maintain notes through OpenKnowForge APIs.
-3. Keep human input focused on review and curation instead of raw note drafting.
+1. Install `OpenKnowForge-Skill` in OpenClaw.
+2. Let OpenClaw call OpenKnowForge APIs for note creation, editing, classification, and maintenance.
+3. Keep human effort focused on review, correction, and knowledge governance.
 
 ![Home](assets/Home.png)
 
-## Why This Project Matters
+## Design Philosophy
 
-OpenKnowForge is not just another markdown notebook.
-Its core value is turning knowledge management into an engineering system:
-
-- OpenClaw-native workflow: note creation can be fully delegated to OpenClaw with `OpenKnowForge-Skill`.
-- Programmable knowledge operations: notes are managed via HTTP APIs, so scripts/agents can create and maintain content reliably.
-- Git-level governance: every note change is committed, auditable, and easy to roll back.
-- Publish-ready architecture: data is edited dynamically but published as static pages for speed and low ops cost.
-- Structured knowledge schema: each note carries metadata (status, timestamps, tags, stats), enabling deterministic indexing and filtering.
-- Team-friendly delivery: local development is lightweight, deployment is CI-driven, and output is accessible through GitHub Pages.
+- Automation first: treat note-taking as an orchestrated knowledge pipeline driven by APIs.
+- Traceability first: keep every content change in Git history for auditability and rollback.
+- Publishing first: combine dynamic ingestion with static delivery for both velocity and reliability.
+- Structure first: use a consistent metadata model to support indexing, search, sorting, and rendering.
+- Collaboration first: keep local setup lightweight and deployment CI-driven for team adoption.
 
 ## Core Capabilities (Implemented)
 
@@ -48,46 +44,46 @@ Its core value is turning knowledge management into an engineering system:
 - Search notes: `GET /notes/search`
 - Push repository: `POST /git/push`
 
-### 2) Strong metadata model
+### 2) Structured metadata model
 
 Each note maintains:
 
-- `status`: `mature` or `draft`
-- `created_at`, `updated_at`, `submitted_at`
-- `tags`, `related`, `type`
-- `word_count`, `image_count`
+- Status: `status` (`mature` / `draft`)
+- Time fields: `created_at`, `updated_at`, `submitted_at`
+- Semantic fields: `tags`, `related`, `type`
+- Statistics: `word_count`, `image_count`
 
-This supports reliable sorting, filtering, and UI rendering.
+This model keeps sorting, filtering, rendering, and API responses consistent.
 
-### 3) Reliable content stats
+### 3) Automatic statistics and backfill
 
-Word/image statistics are calculated when creating and editing notes.
-Existing notes are also backfilled automatically on startup when needed.
+Word and image counts are computed on create and update.
+Legacy notes are backfilled when needed during startup to keep metadata consistent.
 
-### 4) Image ingestion and normalization
+### 4) Image ingestion and normalized storage
 
-The API accepts image inputs as:
+The API accepts image input as:
 
 - Data URL
 - HTTP(S) URL
 - Base64 string
 
-Images are stored under `docs/project/images/` and linked into the note body.
+Images are stored under `docs/project/images/` and injected into note content automatically.
 
-### 5) Auto index and site sync
+### 5) Auto index rebuild and site sync
 
-After note changes, the system automatically rebuilds:
+After note mutations, the system rebuilds:
 
 - Notes index pages
 - English note alias files
 - `docs/public/search-index.json`
 
-So local docs preview and static site outputs stay in sync with the latest content.
+This keeps local preview and static output aligned with current content.
 
 ### 6) Built-in Git traceability
 
-Note create/update/delete operations auto-stage and auto-commit content updates.
-The API response includes commit hash/time when a commit is generated.
+Create, update, and delete operations perform automatic staging and committing.
+When a commit is created, the API response includes the commit hash and timestamp.
 
 ## Architecture
 
@@ -111,9 +107,9 @@ GitHub Pages
 
 - Backend API: FastAPI
 - Content format: Markdown + YAML frontmatter
-- Site generator: VitePress
-- Index/search source: `docs/public/search-index.json`
-- CI/CD: GitHub Actions + GitHub Pages
+- Docs engine: VitePress
+- Search index source: `docs/public/search-index.json`
+- Delivery pipeline: GitHub Actions + GitHub Pages
 
 ## Quick Start
 
@@ -145,20 +141,18 @@ npm run docs:dev
 
 ## GitHub Pages Deployment
 
-This repository already contains workflow config at:
-
-- `.github/workflows/pages.yml`
+The repository already includes workflow configuration at `.github/workflows/pages.yml`.
 
-Deploy steps:
+Deployment steps:
 
-1. In GitHub repo settings, enable Pages and choose `GitHub Actions` as source.
+1. Enable GitHub Pages in repository settings and select `GitHub Actions` as the source.
 2. Push commits to `main`.
-3. The Pages workflow builds and publishes docs automatically.
+3. The workflow builds and publishes the site automatically.
 
 ## Project Layout (High-level)
 
 - API code: `api/`
-- UI/guide docs: `docs/ui/`
+- UI and guides: `docs/ui/`
 - User notes: `docs/project/entries/`
 - User images: `docs/project/images/`
 - Search index: `docs/public/search-index.json`

README.zh-CN.md

@@ -2,36 +2,33 @@
 
 [English](README.md)
 
-OpenKnowForge 是一个 API 原生、Git 驱动的知识库系统。
-它把笔记生产、元数据治理、静态发布、版本追踪整合成一条可工程化的工作流。
+OpenKnowForge 是一套以 API 为核心、以 Git 为底座的知识工程系统。
+它将内容生成、结构化治理、静态发布与版本审计整合为统一流程，用于构建可持续演进的知识库。
 
-## OpenClaw 全自动工作流（无需人工写笔记）
+## OpenClaw First：无需人工撰写笔记
 
-这个项目的设计前提是以 OpenClaw 作为主要内容生产引擎。
-日常使用中不需要人类手动维护 markdown 笔记正文。
+本项目默认采用 OpenClaw 作为内容生产引擎。
+在常规工作流中，笔记创建与维护并不依赖人工逐篇撰写，而是由 OpenClaw 通过 API 自动完成。
 
-请优先在 OpenClaw 中安装这个 Skill：
+请先在 OpenClaw 中安装以下 Skill：
 
 - OpenKnowForge-Skill：`https://github.com/Reuben-Sun/OpenKnowForge-Skill.git`
 
-推荐使用方式：
+推荐流程如下：
 
-1. 在 OpenClaw 中从上述仓库安装 `OpenKnowForge-Skill`。
-2. 由 OpenClaw 通过 OpenKnowForge API 完成笔记创建、编辑、分类和维护。
-3. 人类主要负责复核与知识治理，而不是手工撰写原始笔记。
+1. 在 OpenClaw 中安装 `OpenKnowForge-Skill`。
+2. 由 OpenClaw 调用 OpenKnowForge API 完成新建、编辑、分类与维护。
+3. 人类仅承担复核、校正与知识治理工作。
 
 ![Home](assets/Home.png)
 
-## 项目含金量
+## 设计哲学
 
-OpenKnowForge 不是普通的 Markdown 笔记集合，它的价值在于把“记笔记”变成“可编排的知识工程”：
-
-- OpenClaw 原生工作流：通过 `OpenKnowForge-Skill` 可将笔记创作全程交给 OpenClaw。
-- 可编程知识管理：通过 HTTP API 管理笔记，便于脚本与 Agent 自动化接入。
-- Git 级别治理：每次变更可追踪、可审计、可回滚，天然适配协作场景。
-- 生产可发布架构：写入是动态 API，输出是静态站点，兼顾开发效率与线上稳定性。
-- 结构化知识模型：每条笔记具备状态、时间戳、标签、统计信息，支持稳定检索与排序。
-- 团队可落地：本地启动轻量，部署通过 CI 自动化，最终站点可直接托管在 GitHub Pages。
+- 自动化优先：将“写笔记”升级为“知识工程流水线”，核心操作通过 API 可编排执行。
+- 可追溯优先：所有内容修改均进入 Git 历史，便于审计、对比与回滚。
+- 发布优先：动态写入、静态发布，兼顾内容更新效率与线上稳定性。
+- 结构化优先：以统一元数据驱动索引、检索、排序与展示。
+- 协作优先：本地环境轻量、CI 自动部署，适配个人与团队共建。
 
 ## 核心能力（已实现）
 
@@ -44,49 +41,49 @@ OpenKnowForge 不是普通的 Markdown 笔记集合，它的价值在于把“
 - 删除笔记：`DELETE /note/{slug}`
 - 全量列表：`GET /notes`
 - 草稿列表：`GET /notes/drafts`
-- 笔记搜索：`GET /notes/search`
+- 条件搜索：`GET /notes/search`
 - 推送远端：`POST /git/push`
 
-### 2) 强约束元数据模型
+### 2) 结构化元数据模型
 
-每条笔记都维护：
+每条笔记维护以下关键字段：
 
-- `status`：`mature`（成熟知识）或 `draft`（草稿）
-- `created_at`、`updated_at`、`submitted_at`
-- `tags`、`related`、`type`
-- `word_count`、`image_count`
+- 状态：`status`（`mature` / `draft`）
+- 时间：`created_at`、`updated_at`、`submitted_at`
+- 语义：`tags`、`related`、`type`
+- 统计：`word_count`、`image_count`
 
-这些字段让排序、筛选、展示逻辑更稳定。
+该模型保证排序、筛选、渲染与接口返回的一致性。
 
-### 3) 自动统计机制
+### 3) 统计自动计算与回填
 
-在创建和编辑笔记时会自动统计字数与图片数量。
-对历史笔记也会在需要时自动补齐统计，保证数据一致性。
+系统在创建和编辑笔记时自动计算字数与图片数。
+对于历史笔记，启动阶段会在需要时自动补齐统计字段，以维持数据一致。
 
-### 4) 图片写入能力
+### 4) 图片接入与规范化存储
 
-API 支持以下图片输入格式：
+API 支持以下图片输入形式：
 
 - Data URL
-- HTTP(S) 链接
+- HTTP(S) URL
 - Base64 字符串
 
-图片落地到 `docs/project/images/`，并自动写入笔记内容。
+图片统一保存至 `docs/project/images/`，并自动写入笔记正文。
 
-### 5) 索引与站点自动同步
+### 5) 索引自动重建与站点同步
 
-每次笔记变更后会自动重建：
+每次笔记变更后，系统会自动重建：
 
 - Notes 索引页
 - 英文笔记别名文件
 - `docs/public/search-index.json`
 
-保证本地预览与静态构建结果始终和内容同步。
+因此，本地预览与静态构建结果可与最新内容保持同步。
 
 ### 6) 内建 Git 追踪
 
-新增/编辑/删除笔记会自动执行暂存和提交。
-接口返回中会带上 commit hash 与提交时间（当实际产生提交时）。
+新增、编辑、删除操作会自动执行暂存与提交。
+当实际产生提交时，API 返回中包含 commit hash 与提交时间。
 
 ## 架构链路
 
@@ -110,9 +107,9 @@ GitHub Pages
 
 - 后端 API：FastAPI
 - 内容格式：Markdown + YAML frontmatter
-- 文档站点：VitePress
-- 搜索索引：`docs/public/search-index.json`
-- 持续部署：GitHub Actions + GitHub Pages
+- 文档引擎：VitePress
+- 检索索引：`docs/public/search-index.json`
+- 发布链路：GitHub Actions + GitHub Pages
 
 ## 快速开始
 
@@ -144,15 +141,13 @@ npm run docs:dev
 
 ## GitHub Pages 部署
 
-仓库已包含工作流配置：
-
-- `.github/workflows/pages.yml`
+仓库已包含工作流配置：`.github/workflows/pages.yml`。
 
 部署步骤：
 
 1. 在 GitHub 仓库设置中启用 Pages，Source 选择 `GitHub Actions`。
 2. 推送提交到 `main` 分支。
-3. 工作流会自动构建并发布文档站点。
+3. 工作流自动构建并发布文档站点。
 
 ## 项目结构（高层）