From 26fa880615f1594d23fee2b0f8b141aaf11f7c64 Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sat, 25 Jul 2026 09:19:29 +0300
Subject: [PATCH 1/9] docs: add verified agent contribution guide

Add current-repository contribution rules for human and AI contributors.

Refs #90
---
 AGENTS.md       |  85 ++++++++++++++++++++
 CONTRIBUTING.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 286 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CONTRIBUTING.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9de4219
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,85 @@
+# AGENTS.md
+
+本文件适用于整个仓库，供 AI 编码 Agent 在一次读取后获得最小、可执行的工作约束。
+完整说明见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 事实来源
+
+开始任何修改前读取：
+
+1. 当前 issue、维护者评论和验收条件；
+2. `package.json`、`pnpm-workspace.yaml`、`eslint.config.ts`、`tsconfig.json`；
+3. 与任务相关的源文件、测试和 `.github/` 工作流；
+4. `CONTRIBUTING.md` 和 `README.md`。
+
+配置与旧文档冲突时，以当前分支的可执行配置和维护者最新说明为准，并在 PR 中说明。
+不要编造不存在的命令。
+
+## 仓库速览
+
+- 包管理器：pnpm
+- 默认分支：`main`
+- 应用：Next.js + React + TypeScript
+- UI：React Bootstrap、Less/CSS Module
+- 状态：MobX
+- 国际化：`translation/zh-CN.ts`、`translation/zh-TW.ts`、
+  `translation/en-US.ts`
+
+主要路径：
+
+```text
+pages/         页面、MDX 和 API 路由
+components/    React 组件
+models/        MobX 模型和客户端
+translation/   三种语言文案
+styles/        全局及模块样式
+lib/           领域工具
+.github/       CI 和仓库自动化
+```
+
+## 常用命令
+
+```bash
+pnpm install
+pnpm dev
+pnpm exec prettier --check <changed-files>
+pnpm exec eslint <changed-code-files>
+pnpm exec tsc --noEmit
+pnpm build
+```
+
+仅修改本指南时：
+
+```bash
+pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
+```
+
+注意：当前 `pnpm test` 会执行 `git add .`。在有无关修改的工作区运行前先读
+`package.json`，运行后检查暂存区。
+
+## 实现规则
+
+- 先搜索已有代码和开放 PR，避免重复实现。
+- 只修改任务需要的文件，不做顺手重构。
+- 跟随相邻代码模式；优先复用现有组件、模型、客户端和依赖。
+- TypeScript 保持 strict 兼容，遵循 ESLint 和 Prettier。
+- 用户可见文案使用 `I18nContext` / `t()`，同步三份翻译。
+- 不因方便而更新 lockfile、格式化全仓库或降低检查级别。
+- 不提交环境文件、token、cookie、密码、私钥或真实用户数据。
+
+## 奖励任务
+
+1. 检查 issue 的状态、assignee、评论、Development 和已有 PR。
+2. 留言声明范围；不要假设外部镜像的 claim 命令在这里有效。
+3. 开始前确认币种、结算方式和验收规则。
+4. 从最新 `main` 建分支。
+5. PR 中列出真实验证结果并使用 `Closes #<issue>`。
+6. 只有合并并完成奖励流程后，才把奖励记录为已获得。
+
+## 完成条件
+
+- diff 只包含相关修改；
+- 格式、类型、构建或范围对应的检查已运行；
+- 未运行的检查被明确说明；
+- PR 描述包含 Summary、Changes、Validation、Scope/Risks；
+- 没有凭据、调试残留、虚假结果或未授权副作用。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..cc1cfa9
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,201 @@
+# 贡献指南 / Contributing Guide
+
+感谢你为开源市集（Open Source Bazaar）做贡献。本指南同时适用于人工贡献者和
+AI 编码 Agent。目标是让每个变更都可审查、可验证，并且与仓库当前状态一致。
+
+## 1. 先确认事实来源
+
+仓库会持续更新。不要根据旧 PR、外部镜像或记忆猜测命令和版本。开始任务时按以下
+优先级读取信息：
+
+1. 当前任务的 issue、维护者评论和验收条件；
+2. 根目录的 `AGENTS.md`；
+3. 当前分支的 `package.json`、`pnpm-workspace.yaml`、`eslint.config.ts`、
+   `tsconfig.json` 和相关源文件；
+4. `.github/` 中的工作流、模板和专项说明；
+5. 本文档和 `README.md`。
+
+如果说明与实际配置冲突，以当前分支的可执行配置和维护者最新说明为准，并在 PR 中
+指出冲突。不要自行发明不存在的脚本。
+
+## 2. 项目概览
+
+本项目是使用 Next.js、React 和 TypeScript 构建的开源项目展示网站。当前主要目录：
+
+| 路径           | 用途                                |
+| -------------- | ----------------------------------- |
+| `pages/`       | Next.js 页面、MDX 内容和 API 路由   |
+| `components/`  | 可复用的 React 组件                 |
+| `models/`      | MobX 数据模型、配置和外部服务客户端 |
+| `translation/` | `zh-CN`、`zh-TW` 和 `en-US` 文案    |
+| `styles/`      | 全局样式和 Less/CSS Module          |
+| `lib/`         | 领域工具和数据处理逻辑              |
+| `constants/`   | 共享常量                            |
+| `public/`      | 静态资源                            |
+| `.github/`     | CI、issue/PR 模板和仓库自动化       |
+
+确切依赖版本以 `package.json` 和 `pnpm-lock.yaml` 为准。
+
+## 3. 开发环境
+
+CI 使用 Node.js 24；本地环境应使用兼容的现代 Node.js 版本和 pnpm。
+
+```bash
+node --version
+pnpm --version
+pnpm install
+pnpm dev
+```
+
+开发服务器默认运行在 <http://localhost:3000>。
+
+安装依赖时可能会执行 `package.json` 中的生命周期脚本。Agent 必须先阅读这些脚本，
+不得把凭据、私有 key-vault 内容或本地环境文件提交到仓库。
+
+## 4. 选择并声明任务
+
+1. 确认 issue 仍然开放，并检查 assignee、评论、Development 区域和已有 PR。
+2. 在开始前留言说明计划、范围和预计交付内容。不要假设某个外部镜像的
+   `/claim` 命令适用于本仓库。
+3. 如果已有实现，先判断是复用、补充还是避免重复；不要静默覆盖其他贡献者的工作。
+4. 奖励任务应在开始前确认币种、结算方式和验收规则。
+
+## 5. 分支和提交
+
+从最新的 `main` 创建一个范围明确的分支：
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feat/short-description
+```
+
+文档、修复和维护任务可以分别使用 `docs/`、`fix/`、`chore/` 前缀。提交信息应简洁
+说明意图，例如：
+
+```text
+docs: add agent-aware contribution guide
+fix(finance): preserve selected risk filter
+```
+
+每个 PR 只处理一个可审查目标。除非任务明确要求：
+
+- 不要改动无关文件；
+- 不要更新 lockfile；
+- 不要重新格式化整个仓库；
+- 不要提交生成目录、编辑器设置、环境文件或凭据。
+
+## 6. 代码规范
+
+### TypeScript 和导入
+
+- 保持 `strict` TypeScript 兼容，优先精确类型。
+- 遵循 ESLint；`interface` 是对象结构的默认形式。
+- 清除无用变量和导入，不新增无理由的 `any`。
+- 导入顺序由 `simple-import-sort` 规则管理。
+- 优先复用现有模型、客户端和 `web-utility` 等已安装依赖。
+
+### React、状态和界面
+
+- 先匹配相邻代码的现有模式，不做与任务无关的架构重写。
+- 优先复用 React Bootstrap 组件和现有组件。
+- 跨组件状态遵循已有 MobX 模型；不要创建重复的数据客户端。
+- 保留语义化 HTML、键盘操作和可访问标签。
+- 样式优先使用现有 Bootstrap utility、Less 或 CSS Module 结构。
+
+### 国际化
+
+面向用户的新文案应通过现有 `I18nContext` / `t()` 流程提供，并同步更新：
+
+- `translation/zh-CN.ts`
+- `translation/zh-TW.ts`
+- `translation/en-US.ts`
+
+不要只在 JSX 中硬编码一种语言。
+
+### 格式化
+
+根目录 `package.json` 是格式化规则的事实来源。当前关键规则包括：
+
+- 单引号；
+- 允许尾随逗号；
+- 100 字符打印宽度；
+- 单参数箭头函数不加括号。
+
+使用仓库安装的 Prettier，不要用个人全局配置覆盖项目规则。
+
+## 7. 验证
+
+根据变更范围运行最小但充分的验证。
+
+### 仅 Markdown
+
+```bash
+pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
+```
+
+同时手动检查链接、标题层级、代码块和命令是否存在。
+
+### TypeScript / React
+
+```bash
+pnpm exec prettier --check <changed-files>
+pnpm exec eslint <changed-files>
+pnpm exec tsc --noEmit
+pnpm build
+```
+
+如果变更涉及页面，启动 `pnpm dev` 并验证受影响路由、响应式布局和语言切换。
+
+### 关于 `pnpm test`
+
+当前 `test` 脚本会运行 `lint-staged`，随后执行 `git add .` 和 TypeScript 检查。
+它会修改 Git 暂存区，因此在共享或包含无关修改的工作区中不要盲目运行。使用前先读
+`package.json`，运行后检查 `git status`，并只提交本任务文件。
+
+无法运行某项验证时，在 PR 中写明原因；不要声称未执行的检查已经通过。
+
+## 8. Pull Request
+
+推送分支并创建 PR，目标分支为 `main`。PR 描述至少包含：
+
+- **Summary**：问题和解决方案；
+- **Changes**：修改的文件和行为；
+- **Validation**：实际运行的命令及结果；
+- **Scope / Risks**：未处理内容、兼容性或后续工作；
+- 对应 issue 的关闭引用，例如 `Closes #90`。
+
+填写 `.github/PULL_REQUEST_TEMPLATE.md` 中适用的清单项。只有实际设置了 label、
+assignee 或 reviewer 才勾选对应项目。
+
+奖励 issue 的自动化会在 issue 被合并后的关闭 PR 解决时生成奖励数据。合并前不要
+把奖励描述为已获得，也不要在代码、提交或评论中发布钱包私钥或其他凭据。
+
+## 9. AI Agent 工作协议
+
+Agent 在修改前必须完成以下步骤：
+
+1. 阅读 issue、`AGENTS.md` 和相关配置；
+2. 搜索已有实现、开放 PR 和相邻代码；
+3. 用一两句话定义边界和验收条件；
+4. 只修改完成任务所需的文件；
+5. 执行与范围匹配的验证；
+6. 检查 diff 中是否含凭据、调试输出或无关变更；
+7. 在 PR 中提供可复现的证据。
+
+Agent 不得：
+
+- 把历史讨论当成当前指令；
+- 编造脚本、测试结果、API 或项目规则；
+- 为通过检查而删除测试、降低安全性或使用 `[skip ci]`；
+- 未经明确授权执行付款、发布凭据或修改外部生产数据；
+- 将用户提示、token、cookie、密码或私钥写入仓库。
+
+## 10. 安全和报告
+
+普通 bug 和功能建议使用 GitHub issue。发现真实安全漏洞或可能泄露数据的问题时，
+不要公开 exploit、凭据或敏感样本；使用仓库 Security 页面提供的私密渠道，或先联系
+维护者确认安全报告方式。
+
+提交 PR 后保持可响应：处理 review，重新运行受影响检查，并在实现或验收条件变化时
+更新 PR 描述。

From 0466a18902686c1dca9b0eb64b96419288d28664 Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sat, 25 Jul 2026 09:43:24 +0300
Subject: [PATCH 2/9] docs: harden contribution workflow guidance

Document upstream synchronization, Corepack setup, CI limitations, reward metadata, and tracked environment-file safety.
---
 AGENTS.md       | 27 +++++++++++++++++----------
 CONTRIBUTING.md | 40 +++++++++++++++++++++++++++++-----------
 2 files changed, 46 insertions(+), 21 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9de4219..9ecccc0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,18 +40,22 @@ lib/           领域工具
 ## 常用命令
 
 ```bash
-pnpm install
-pnpm dev
-pnpm exec prettier --check <changed-files>
-pnpm exec eslint <changed-code-files>
-pnpm exec tsc --noEmit
-pnpm build
+corepack pnpm install --frozen-lockfile
+corepack pnpm dev
+corepack pnpm exec prettier --check <changed-files>
+corepack pnpm exec eslint <changed-code-files>
+corepack pnpm exec tsc --noEmit
+corepack pnpm build
 ```
 
+如果 pnpm 已安装，可省略 `corepack` 前缀。从 fork 开始工作时，先 fetch 正确的
+`upstream` 并从 `upstream/main` 创建分支。
+
 仅修改本指南时：
 
 ```bash
-pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
+corepack pnpm exec prettier --check CONTRIBUTING.md AGENTS.md \
+  .github/copilot-instructions.md
 ```
 
 注意：当前 `pnpm test` 会执行 `git add .`。在有无关修改的工作区运行前先读
@@ -59,13 +63,14 @@ pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
 
 ## 实现规则
 
-- 先搜索已有代码和开放 PR，避免重复实现。
+- 先搜索已有代码，以及修改相同功能或文件的开放和关闭 PR，避免重复实现。
 - 只修改任务需要的文件，不做顺手重构。
 - 跟随相邻代码模式；优先复用现有组件、模型、客户端和依赖。
 - TypeScript 保持 strict 兼容，遵循 ESLint 和 Prettier。
 - 用户可见文案使用 `I18nContext` / `t()`，同步三份翻译。
 - 不因方便而更新 lockfile、格式化全仓库或降低检查级别。
-- 不提交环境文件、token、cookie、密码、私钥或真实用户数据。
+- 不向已跟踪的 `.env` 添加 secret；本地 secret 使用被忽略的 `.env.local`。
+- 不提交 token、cookie、密码、私钥、vault 内容或真实用户数据。
 
 ## 奖励任务
 
@@ -74,7 +79,8 @@ pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
 3. 开始前确认币种、结算方式和验收规则。
 4. 从最新 `main` 建分支。
 5. PR 中列出真实验证结果并使用 `Closes #<issue>`。
-6. 只有合并并完成奖励流程后，才把奖励记录为已获得。
+6. 奖励自动化只记录分配元数据，不验证价值、escrow 或实际付款。
+7. 只有合并并完成结算后，才把奖励记录为已获得。
 
 ## 完成条件
 
@@ -82,4 +88,5 @@ pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
 - 格式、类型、构建或范围对应的检查已运行；
 - 未运行的检查被明确说明；
 - PR 描述包含 Summary、Changes、Validation、Scope/Risks；
+- 已认识到外部 fork 的 CI 不一定执行 lint、类型检查或 build；
 - 没有凭据、调试残留、虚假结果或未授权副作用。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc1cfa9..54168f4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,19 +38,23 @@ AI 编码 Agent。目标是让每个变更都可审查、可验证，并且与
 
 ## 3. 开发环境
 
-CI 使用 Node.js 24；本地环境应使用兼容的现代 Node.js 版本和 pnpm。
+部署工作流使用 Node.js 24；本地环境应使用兼容的现代 Node.js 版本。可以使用已安装的
+pnpm，也可以通过 Corepack 运行：
 
 ```bash
 node --version
-pnpm --version
-pnpm install
-pnpm dev
+corepack pnpm --version
+corepack pnpm install --frozen-lockfile
+corepack pnpm dev
 ```
 
+如果系统已经安装 pnpm，直接使用对应的 `pnpm` 命令即可。
+
 开发服务器默认运行在 <http://localhost:3000>。
 
-安装依赖时可能会执行 `package.json` 中的生命周期脚本。Agent 必须先阅读这些脚本，
-不得把凭据、私有 key-vault 内容或本地环境文件提交到仓库。
+安装依赖时会执行 `package.json` 中的生命周期脚本。当前 `install` 脚本会尝试下载可选
+key-vault，失败不会中断安装。Agent 必须先阅读这些脚本，不得把下载的 vault 内容、
+凭据或本地环境文件提交到仓库。
 
 ## 4. 选择并声明任务
 
@@ -62,14 +66,19 @@ pnpm dev
 
 ## 5. 分支和提交
 
-从最新的 `main` 创建一个范围明确的分支：
+从上游仓库最新的 `main` 创建一个范围明确的分支，而不是只信任可能过期的 fork：
 
 ```bash
+git remote add upstream https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git
+git fetch upstream
 git switch main
-git pull --ff-only
+git merge --ff-only upstream/main
+git push origin main
 git switch -c feat/short-description
 ```
 
+如果 `upstream` 已存在，先验证其 URL，不要重复添加。
+
 文档、修复和维护任务可以分别使用 `docs/`、`fix/`、`chore/` 前缀。提交信息应简洁
 说明意图，例如：
 
@@ -83,7 +92,7 @@ fix(finance): preserve selected risk filter
 - 不要改动无关文件；
 - 不要更新 lockfile；
 - 不要重新格式化整个仓库；
-- 不要提交生成目录、编辑器设置、环境文件或凭据。
+- 不要提交生成目录、编辑器设置、本地环境文件或凭据。
 
 ## 6. 代码规范
 
@@ -155,6 +164,10 @@ pnpm build
 
 无法运行某项验证时，在 PR 中写明原因；不要声称未执行的检查已经通过。
 
+当前 CI/CD 在 push 时触发，但 checkout、Node 设置和部署取决于 Vercel secrets。它不为
+外部 fork 提供通用的 lint、类型检查或 build 门禁，而且首次 fork workflow 可能等待维护者
+批准。因此 PR 中必须提供本地验证证据，不能只依赖绿色状态。
+
 ## 8. Pull Request
 
 推送分支并创建 PR，目标分支为 `main`。PR 描述至少包含：
@@ -168,8 +181,10 @@ pnpm build
 填写 `.github/PULL_REQUEST_TEMPLATE.md` 中适用的清单项。只有实际设置了 label、
 assignee 或 reviewer 才勾选对应项目。
 
-奖励 issue 的自动化会在 issue 被合并后的关闭 PR 解决时生成奖励数据。合并前不要
-把奖励描述为已获得，也不要在代码、提交或评论中发布钱包私钥或其他凭据。
+带有 `reward` label 的 issue 经合并 PR 关闭后，自动化会找到一个已合并的关闭 PR，并在
+Git tag 和 issue 评论中记录奖励分配数据。它不会验证币种价值、escrow、实际转账或验收
+承诺。应先向 issue 中的 payer 确认这些条件，结算完成前不要把奖励描述为已获得，也不要
+在代码、提交或评论中发布钱包私钥或其他凭据。
 
 ## 9. AI Agent 工作协议
 
@@ -197,5 +212,8 @@ Agent 不得：
 不要公开 exploit、凭据或敏感样本；使用仓库 Security 页面提供的私密渠道，或先联系
 维护者确认安全报告方式。
 
+仓库已跟踪的 `.env` 包含运行配置，但不得向其中添加 secret。本地 secret 应放入被
+Git 忽略的 `.env.local` 等本地文件。
+
 提交 PR 后保持可响应：处理 review，重新运行受影响检查，并在实现或验收条件变化时
 更新 PR 描述。

From 0ea7170c8fce2886a7a3ec84079bc418ddb73329 Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sat, 25 Jul 2026 09:43:51 +0300
Subject: [PATCH 3/9] docs: align Copilot instructions with current repository

Replace stale commands, versions, routes, and validation assumptions with current executable configuration.
---
 .github/copilot-instructions.md | 348 ++++++++++----------------------
 1 file changed, 106 insertions(+), 242 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 165e2cc..b64ce8f 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,281 +1,145 @@
-# Open Source Bazaar - GitHub Copilot Instructions
+# Open Source Bazaar — GitHub Copilot Instructions
 
-Open Source Bazaar is an open-source project showcase platform built with Next.js 15, TypeScript, React Bootstrap, and MobX. It includes license filters, Wiki knowledge base, volunteer showcase, Lark integration, and other features.
+These instructions apply to the entire repository. Read
+[`AGENTS.md`](../AGENTS.md) first and use
+[`CONTRIBUTING.md`](../CONTRIBUTING.md) for the complete workflow.
 
-Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+## Source of truth
 
-## Critical Requirements
+Before changing code, inspect the current issue, maintainer comments, relevant
+source files, tests, `package.json`, `pnpm-workspace.yaml`,
+`eslint.config.ts`, `tsconfig.json`, and affected workflows.
 
-⚠️ **MANDATORY NODE.JS VERSION**: This project requires **Node.js >=20**. The build works on Node.js 20+ but may have warnings.
+Executable configuration and the latest maintainer direction take precedence
+over prose. Do not repeat commands, versions, routes, or project assumptions
+from an older PR without verifying them in the current branch.
 
-- Check Node.js version: `node --version`
-- Development and linting commands work on Node.js 20+
-- Use **PNPM** as package manager, not NPM or Yarn
+## Current repository
 
-## Working Effectively
+- Default branch: `main`
+- Package manager: pnpm
+- Application: Next.js 16, React 19, and strict TypeScript 5
+- UI and styles: React Bootstrap, Bootstrap utilities, Less/CSS Modules
+- State and clients: MobX and the existing models
+- Internationalization: `translation/zh-CN.ts`,
+  `translation/zh-TW.ts`, and `translation/en-US.ts`
 
-### Initial Setup (REQUIRED for all development)
+Treat `package.json` and the lockfile as authoritative for exact versions.
 
-1. **Install global pnpm**: `npm install -g pnpm`
-2. **Install dependencies**: `pnpm install` -- takes 1-3 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
-3. **Verify setup**: `pnpm --version` (should be 10.x+)
+## Setup
 
-**Important**: If you see "node_modules missing" error, you MUST run `pnpm install` first before any other commands.
-
-### Development Workflow (FULLY VALIDATED)
-
-- **Start development server**: `pnpm dev` -- starts in 5-15 seconds on http://localhost:3000
-- **Run linting**: `pnpm lint` -- takes 15 seconds. NEVER CANCEL. Set timeout to 2+ minutes.
-- **Run tests**: `pnpm test` -- runs lint-staged + lint, takes 15 seconds. Set timeout to 2+ minutes.
-
-### Build Process
-
-- **Production build**: `pnpm build` -- works on Node.js 20+ (estimated 30s-2 minutes)
-  - NEVER CANCEL. Set timeout to 5+ minutes.
-- **Static export**: Available but not commonly used in development
-
-## Validation Scenarios
-
-After making ANY changes, ALWAYS validate by running through these scenarios:
-
-### Manual Testing Requirements
-
-1. **Start development server**: `pnpm dev` and verify it starts without errors
-2. **Navigate to homepage**: Visit http://localhost:3000 and verify page loads with navigation menu
-3. **Test core pages**:
-   - License filter: http://localhost:3000/license-filter (interactive license selection tool)
-   - Wiki pages: http://localhost:3000/policy (policy documents from GitHub)
-   - Volunteer page: http://localhost:3000/volunteer (contributor showcase)
-   - Projects: http://localhost:3000/project (GitHub repository listings)
-4. **Test API endpoints**: Verify GitHub API integrations work
-5. **Check responsive design**: Test mobile/desktop layouts with React Bootstrap components
-6. **Verify i18n functionality**: Check Chinese/English language switching works
-
-### Pre-commit Validation
-
-ALWAYS run before committing changes:
+The deployment workflow uses Node.js 24. Use a compatible modern Node.js
+version and either an installed pnpm command or Corepack:
 
 ```bash
-npm test     # Runs linting + staged file checks
+node --version
+corepack pnpm --version
+corepack pnpm install --frozen-lockfile
+corepack pnpm dev
 ```
 
-## Key Project Structure
-
-### Important Directories
-
-- `pages/` - Next.js pages and API routes
-- `components/` - Reusable React components with Bootstrap styling
-- `models/` - MobX stores and data models
-- `translation/` - i18n language files (zh-CN, en-US, zh-TW)
-- `styles/` - CSS and styling files
-- `public/` - Static assets
-
-### Configuration Files
-
-- `package.json` - Dependencies and scripts
-- `next.config.ts` - Next.js configuration with MDX support
-- `tsconfig.json` - TypeScript configuration
-- `eslint.config.ts` - ESLint configuration
-- `babel.config.js` - Babel configuration
-
-### Key Dependencies
-
-- **Next.js 15** - React framework
-- **React Bootstrap 2.10** - UI component library
-- **MobX 6.13** - State management
-- **MobX-GitHub 0.4** - GitHub API integration
-- **MobX-i18n 0.7** - Internationalization
-- **License-Filter 0.2** - License filtering functionality
-- **Marked 16.2** - Markdown processing
-
-## Development Standards and Best Practices
-
-Based on comprehensive PR review analysis, follow these critical development standards:
-
-### Architecture and Code Organization
-
-#### Component and Import Standards
-
-- **ALWAYS use React Bootstrap components** instead of custom HTML elements
-- Use utilities from established libraries: 'web-utility'
-- Import `'./Base'` in model files for proper configuration
-
-#### Error Handling and Static Generation
-
-- **Natural error throwing** for static generation - let errors bubble up to catch build issues
-- Ensure build passes before pushing - resolve issues at compile time
-
-### UI/UX Standards
-
-#### Component Usage Patterns
-
-```typescript
-// ✅ Correct - use React Bootstrap components
-import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap';
-
-<Button variant="outline-primary" size="sm" href={url} target="_blank">
-  {t('edit_on_github')}
-</Button>
-
-<Badge bg="secondary">{label}</Badge>
-
-// ❌ Wrong - custom HTML elements
-<a href={url} className="btn btn-outline-primary">Edit</a>
-<span className="badge bg-secondary">{label}</span>
-```
-
-#### Semantic HTML Structure
-
-- Use ordered lists (`<ol>`) for countable items, unordered lists (`<ul>`) for navigation
-- Apply proper semantic structure: `<article>`, `<header>`, `<section>`
-- Use `list-unstyled` class for first-level lists to remove default styling
-
-### Code Quality Standards
+If pnpm is already installed, the equivalent `pnpm` commands are valid.
 
-#### Modern ECMAScript Features
+Read lifecycle scripts before installation. The current `install` script
+attempts an optional key-vault download and tolerates failure; never commit
+downloaded vault content, credentials, tokens, or local environment files.
 
-- Use optional chaining and modern JavaScript features
-- Let TypeScript infer types when possible to avoid verbose annotations
-- Use modern ECMAScript patterns for cleaner, more maintainable code
+## Synchronize a fork
 
-#### Import and Type Management
-
-- Import from established sources: ContentModel from mobx-github, utilities from web-utility
-- Import configuration files where needed: `'./Base'` for GitHub client setup
-- Use minimal exports and avoid unnecessary custom implementations
-- Use configured clients rather than creating new ones
-
-### Translation and Internationalization
-
-#### Critical Translation Requirements
-
-- **ALL user-facing text** MUST be translated using i18n system
-- This includes button text, labels, error messages, placeholder text, and dynamic content
-- Use the `t()` function from I18nContext for all translations
-
-#### Translation Patterns
-
-- Use the `t()` function from I18nContext for all user-facing text
-- Translate all button text, labels, error messages, and dynamic content
-- Avoid hardcoded text in any language
-
-#### Translation Key Management
-
-- Use generic terms unless specifically scoped: `t('knowledge_base')` not `t('policy_documents')`
-- Add translation keys to ALL language files: `zh-CN.ts`, `en-US.ts`, `zh-TW.ts`
-- Remove unused translation keys when replacing with generic ones
-
-### Data Modeling and Content Management
-
-#### Content Model Patterns
-
-- Use ContentModel with configured client from mobx-github
-- Import configuration via `'./Base'` to ensure proper GitHub client setup
-- Handle Base64 content decoding when processing GitHub API responses
-
-#### Tree Structure and Navigation
-
-- Use `treeFrom` utility from web-utility for hierarchical data structures
-- Follow established patterns for tree node organization and navigation
-
-### GitHub Integration Standards
-
-#### API Usage Patterns
-
-- Import configured `githubClient` from `models/Base.ts`
-
-#### Authentication and Rate Limiting
-
-- GitHub API authentication is configured in `models/Base.ts`
-- Use the configured client to avoid rate limiting and authentication issues
-- Don't create separate GitHub API instances
-
-### Build and Development Process
-
-#### Pre-commit Standards
-
-1. **Run linting**: `pnpm lint` to auto-fix formatting
-2. **Check build**: Ensure `pnpm build` passes
-3. **Validate translations**: Verify all text is properly translated
-4. **Remove unused code**: Clean up unused imports and translation keys
-
-#### Code Review Compliance
-
-- **Follow exact code suggestions** from reviews when provided
-- Use **minimal approach** - only include explicitly requested functionality
-- **Don't add extra features** not specified in requirements
-- **Address reviewer feedback completely** before requesting re-review
-
-## Common Commands Reference
-
-### Package Management
+Create work from the current upstream `main`, not merely a potentially stale
+fork branch:
 
 ```bash
-pnpm install          # Install dependencies (1-3 minutes)
-pnpm --version        # Check pnpm version
+git remote add upstream https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git
+git fetch upstream
+git switch main
+git merge --ff-only upstream/main
+git push origin main
+git switch -c feat/short-description
 ```
 
-### Development
+If `upstream` already exists, verify its URL instead of adding it again. Use a
+`docs/`, `fix/`, or `chore/` prefix when that better describes the task.
 
-```bash
-pnpm dev             # Start development server (5-15s)
-pnpm build           # Production build (30s-2min)
-pnpm start           # Start production server
-```
-
-### Code Quality
+## Commands that exist
 
 ```bash
-pnpm lint            # Run ESLint with auto-fix (15s)
-pnpm test            # Run tests (lint-staged + lint, 15s)
+pnpm dev
+pnpm build
+pnpm start
+pnpm exec prettier --check <changed-files>
+pnpm exec eslint <changed-code-files>
+pnpm exec tsc --noEmit
 ```
 
-## Troubleshooting
-
-### Common Issues and Solutions
+There is no `pnpm lint` script. Do not invent one.
 
-#### Build and Development Issues
+The current `pnpm test` command runs `lint-staged`, then `git add .`, then
+`tsc --noEmit`. It mutates the Git index and only formats files already staged
+when `lint-staged` starts. Read `package.json`, inspect `git status` before and
+afterward, and do not stage unrelated work.
 
-- **"Unsupported engine" warnings**: Expected on Node.js <22, development still works
-- **Build hangs**: Never cancel builds - they may take several minutes, set appropriate timeouts
-- **Missing dependencies**: Always run `pnpm install` first
+## Implementation rules
 
-#### Component and Styling Issues
+- Search the current code and every open or closed PR touching the same
+  function or files before implementing.
+- Keep one reviewable goal per PR and avoid unrelated refactors.
+- Reuse existing components, models, clients, dependencies, and nearby
+  patterns.
+- Follow ESLint and Prettier; the current formatting uses single quotes,
+  trailing commas, a 100-character print width, and no parentheses around a
+  single arrow-function parameter.
+- Keep strict TypeScript compatibility. Object shapes normally use
+  `interface`, and imports are managed by `simple-import-sort`.
+- Use `I18nContext` / `t()` for new user-facing text and update all three
+  translation files.
+- Preserve semantic HTML, keyboard access, labels, and responsive behavior.
+- Do not update the lockfile, reformat the repository, or add dependencies
+  unless the task requires it.
 
-- **Custom HTML not working**: Replace with React Bootstrap components
-- **Translation not showing**: Ensure all text uses `t()` function and keys exist in all language files
-- **GitHub API errors**: Verify you're using configured `githubClient` from `models/Base.ts`
+The tracked `.env` contains repository runtime configuration. Do not add
+secrets to it. Put local secrets in an ignored local environment file such as
+`.env.local`, and never commit credentials or private user data.
 
-#### Data and Content Issues
+## Validation and CI limits
 
-- **Base64 content errors**: Use `atob(item.content)` to decode GitHub API responses
-- **Missing content**: Check ContentModel configuration and repository access
-- **Tree structure problems**: Use `treeFrom()` utility from web-utility
+Run checks that match the changed scope. For TypeScript or UI work, normally
+run:
 
-### Development Environment Setup
-
-- Clear browser cache if components don't render properly
-- Restart development server after major configuration changes
-- Verify all translation files are updated when adding new keys
-
-## Project-Specific Patterns
+```bash
+pnpm exec prettier --check <changed-files>
+pnpm exec eslint <changed-code-files>
+pnpm exec tsc --noEmit
+pnpm build
+```
 
-### Wiki System Architecture
+For page changes, also run `pnpm dev` and inspect the affected routes,
+responsive layout, and language switching.
 
-- Uses GitHub ContentModel to access policy documents from `fpsig/open-source-policy` repository
-- Renders markdown content with front-matter metadata
-- Supports hierarchical document structure with breadcrumb navigation
+The current CI/CD workflow is triggered by pushes, but checkout, Node setup,
+and deployment are conditional on Vercel secrets. It does not provide a
+general PR lint, type-check, or build gate for external forks. A fork workflow
+may also wait for maintainer approval. Local validation evidence in the PR is
+therefore required.
 
-### License Filter Integration
+## Pull requests and rewards
 
-- Interactive multi-step license selection process
-- Uses `license-filter` package for license recommendation logic
-- Supports multiple languages with comprehensive i18n coverage
+- Check the issue state, assignees, comments, Development links, and all
+  related open and closed PRs before starting.
+- Fill the repository PR checklist truthfully and include Summary, Changes,
+  Validation, and Scope/Risks.
+- Use `Closes #<issue>` only when the PR should close that issue.
+- Do not claim an external mirror task unless its claim protocol is confirmed
+  for this repository.
 
-### Volunteer Management
+For issues labelled `reward`, closing through a merged PR triggers automation
+that finds one merged closing PR and writes reward metadata to a Git tag and
+issue comment. This records allocation data; it does not verify a currency's
+value, escrow funds, transfer payment, or guarantee acceptance. Confirm those
+terms with the named payer, and record a reward as earned only after settlement.
 
-- Displays GitHub organization contributors
-- Integrates with OSS Insight widgets for contributor analytics
-- Uses GitHub API for real-time contributor data
+## Security
 
-Always prioritize these project-specific standards over generic Next.js or React guidance when working in this specific codebase.
+Never expose tokens, cookies, passwords, private keys, key-vault data, or
+production user data. Report vulnerabilities through the repository's private
+Security reporting channel rather than publishing exploit details.

From f9298180d28d6f403c3fb2e23220ca8582c09d0b Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sat, 25 Jul 2026 10:08:22 +0300
Subject: [PATCH 4/9] ci: review contribution guides with CodeRabbit

---
 .coderabbit.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index 7d9899d..9fd01e9 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -23,6 +23,9 @@ reviews:
         - "components/**"
         - "models/**"
         - "!**/*.md"
+        - "AGENTS.md"
+        - "CONTRIBUTING.md"
+        - ".github/copilot-instructions.md"
         - "!**/*.{bin,csv}"
         - "!node_modules/**"
         - "!.next/**"

From 06316ae5d743015eda60d8e7e1186607d7d76ccd Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sat, 25 Jul 2026 10:11:42 +0300
Subject: [PATCH 5/9] ci: resolve CodeRabbit markdown filter precedence

---
 .coderabbit.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index 9fd01e9..6bbd2dd 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -22,7 +22,7 @@ reviews:
         - "pages/**"
         - "components/**"
         - "models/**"
-        - "!**/*.md"
+        - "!pages/**/*.md"
         - "AGENTS.md"
         - "CONTRIBUTING.md"
         - ".github/copilot-instructions.md"

From 039160692624f322089a68b8c4430f479b0ebc7c Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sun, 26 Jul 2026 19:34:58 +0300
Subject: [PATCH 6/9] docs: address contribution guide review feedback

---
 .github/copilot-instructions.md | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index b64ce8f..be8fe54 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -50,7 +50,15 @@ Create work from the current upstream `main`, not merely a potentially stale
 fork branch:
 
 ```bash
-git remote add upstream https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git
+upstream_url=https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git
+if git remote get-url upstream >/dev/null 2>&1; then
+  if [ "$(git remote get-url upstream)" != "$upstream_url" ]; then
+    echo "upstream points to an unexpected repository" >&2
+    exit 1
+  fi
+else
+  git remote add upstream "$upstream_url"
+fi
 git fetch upstream
 git switch main
 git merge --ff-only upstream/main
@@ -58,17 +66,20 @@ git push origin main
 git switch -c feat/short-description
 ```
 
-If `upstream` already exists, verify its URL instead of adding it again. Use a
-`docs/`, `fix/`, or `chore/` prefix when that better describes the task.
+The URL check deliberately stops the sequence when an existing `upstream`
+points elsewhere. Use a `docs/`, `fix/`, or `chore/` prefix when that better
+describes the task.
 
 ## Commands that exist
 
+Replace the existing example path below with the files changed by the PR:
+
 ```bash
 pnpm dev
 pnpm build
 pnpm start
-pnpm exec prettier --check <changed-files>
-pnpm exec eslint <changed-code-files>
+pnpm exec prettier --check pages/index.tsx
+pnpm exec eslint pages/index.tsx
 pnpm exec tsc --noEmit
 ```
 
@@ -103,12 +114,12 @@ secrets to it. Put local secrets in an ignored local environment file such as
 
 ## Validation and CI limits
 
-Run checks that match the changed scope. For TypeScript or UI work, normally
-run:
+Run checks that match the changed scope. For TypeScript or UI work, replace
+the existing example path with the files changed by the PR:
 
 ```bash
-pnpm exec prettier --check <changed-files>
-pnpm exec eslint <changed-code-files>
+pnpm exec prettier --check pages/index.tsx
+pnpm exec eslint pages/index.tsx
 pnpm exec tsc --noEmit
 pnpm build
 ```

From 03179dc8946c90ecaa269d61feaf6b2ea8addbca Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sun, 26 Jul 2026 19:34:59 +0300
Subject: [PATCH 7/9] docs: address contribution guide review feedback

---
 AGENTS.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9ecccc0..6cf4177 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,11 +39,14 @@ lib/           领域工具
 
 ## 常用命令
 
+下面的 `pages/index.tsx` 是语法有效的现有示例路径；验证实际变更时，将其替换为本次
+修改的文件路径。
+
 ```bash
 corepack pnpm install --frozen-lockfile
 corepack pnpm dev
-corepack pnpm exec prettier --check <changed-files>
-corepack pnpm exec eslint <changed-code-files>
+corepack pnpm exec prettier --check pages/index.tsx
+corepack pnpm exec eslint pages/index.tsx
 corepack pnpm exec tsc --noEmit
 corepack pnpm build
 ```
@@ -78,7 +81,7 @@ corepack pnpm exec prettier --check CONTRIBUTING.md AGENTS.md \
 2. 留言声明范围；不要假设外部镜像的 claim 命令在这里有效。
 3. 开始前确认币种、结算方式和验收规则。
 4. 从最新 `main` 建分支。
-5. PR 中列出真实验证结果并使用 `Closes #<issue>`。
+5. PR 中列出真实验证结果；仅当该 PR 应关闭对应 issue 时使用 `Closes #<issue>`。
 6. 奖励自动化只记录分配元数据，不验证价值、escrow 或实际付款。
 7. 只有合并并完成结算后，才把奖励记录为已获得。
 

From a12c623312cf7e96c296909728693edbb9d79e1a Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Sun, 26 Jul 2026 19:35:01 +0300
Subject: [PATCH 8/9] docs: address contribution guide review feedback

---
 CONTRIBUTING.md | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 54168f4..725d72c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -69,7 +69,15 @@ key-vault，失败不会中断安装。Agent 必须先阅读这些脚本，不
 从上游仓库最新的 `main` 创建一个范围明确的分支，而不是只信任可能过期的 fork：
 
 ```bash
-git remote add upstream https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git
+upstream_url=https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git
+if git remote get-url upstream >/dev/null 2>&1; then
+  if [ "$(git remote get-url upstream)" != "$upstream_url" ]; then
+    echo "upstream points to an unexpected repository" >&2
+    exit 1
+  fi
+else
+  git remote add upstream "$upstream_url"
+fi
 git fetch upstream
 git switch main
 git merge --ff-only upstream/main
@@ -77,7 +85,7 @@ git push origin main
 git switch -c feat/short-description
 ```
 
-如果 `upstream` 已存在，先验证其 URL，不要重复添加。
+该 URL 检查会在已有 `upstream` 指向其他地址时停止流程，避免从错误的上游同步。
 
 文档、修复和维护任务可以分别使用 `docs/`、`fix/`、`chore/` 前缀。提交信息应简洁
 说明意图，例如：
@@ -140,16 +148,19 @@ fix(finance): preserve selected risk filter
 ### 仅 Markdown
 
 ```bash
-pnpm exec prettier --check CONTRIBUTING.md AGENTS.md
+pnpm exec prettier --check CONTRIBUTING.md AGENTS.md .github/copilot-instructions.md
 ```
 
 同时手动检查链接、标题层级、代码块和命令是否存在。
 
 ### TypeScript / React
 
+下面的 `pages/index.tsx` 是语法有效的现有示例路径；验证实际变更时，将其替换为本次
+修改的文件路径。
+
 ```bash
-pnpm exec prettier --check <changed-files>
-pnpm exec eslint <changed-files>
+pnpm exec prettier --check pages/index.tsx
+pnpm exec eslint pages/index.tsx
 pnpm exec tsc --noEmit
 pnpm build
 ```
@@ -176,7 +187,7 @@ pnpm build
 - **Changes**：修改的文件和行为；
 - **Validation**：实际运行的命令及结果；
 - **Scope / Risks**：未处理内容、兼容性或后续工作；
-- 对应 issue 的关闭引用，例如 `Closes #90`。
+- 仅当该 PR 应关闭对应 issue 时，添加关闭引用，例如 `Closes #90`。
 
 填写 `.github/PULL_REQUEST_TEMPLATE.md` 中适用的清单项。只有实际设置了 label、
 assignee 或 reviewer 才勾选对应项目。

From 6695c224f5978389e8ef60f7d33af0c338a1db44 Mon Sep 17 00:00:00 2001
From: Frediano Campione <f.campione@mcallcenter.biz>
Date: Mon, 27 Jul 2026 03:36:38 +0300
Subject: [PATCH 9/9] docs: avoid pushing fork main during setup

---
 .github/copilot-instructions.md | 10 ++++------
 CONTRIBUTING.md                 |  6 ++----
 2 files changed, 6 insertions(+), 10 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index be8fe54..c81db9f 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -60,15 +60,13 @@ else
   git remote add upstream "$upstream_url"
 fi
 git fetch upstream
-git switch main
-git merge --ff-only upstream/main
-git push origin main
-git switch -c feat/short-description
+git switch -c feat/short-description upstream/main
 ```
 
 The URL check deliberately stops the sequence when an existing `upstream`
-points elsewhere. Use a `docs/`, `fix/`, or `chore/` prefix when that better
-describes the task.
+points elsewhere. Creating the feature branch directly from `upstream/main`
+also avoids modifying the fork's remote `main`. Use a `docs/`, `fix/`, or
+`chore/` prefix when that better describes the task.
 
 ## Commands that exist
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 725d72c..6c4b1d1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -79,13 +79,11 @@ else
   git remote add upstream "$upstream_url"
 fi
 git fetch upstream
-git switch main
-git merge --ff-only upstream/main
-git push origin main
-git switch -c feat/short-description
+git switch -c feat/short-description upstream/main
 ```
 
 该 URL 检查会在已有 `upstream` 指向其他地址时停止流程，避免从错误的上游同步。
+直接从 `upstream/main` 创建功能分支也不会修改 fork 的远程 `main`。
 
 文档、修复和维护任务可以分别使用 `docs/`、`fix/`、`chore/` 前缀。提交信息应简洁
 说明意图，例如：