photon-skills 3.0.3.dev0__tar.gz → 3.0.3.dev17__tar.gz

{photon_skills-3.0.3.dev0 → photon_skills-3.0.3.dev17}/.gitignore

@@ -17,7 +17,7 @@ demo_*.png
 # figure color_palettes/figure_export selftest 渲染的 demo 图(可复现,不入库)
 _export_demo/
 
-# 本地客户端发现镜像（由 scripts/bootstrap_agent_skills.py 生成；canonical 仍是 skills/）
+# 舊多客戶端鏡像殘留(已退役;勿提交)
 .agents/
 .claude/
 .opencode/

photon_skills-3.0.3.dev17/AGENTS.md

@@ -0,0 +1,35 @@
+# Photon-skills 代理協作說明
+
+本 repo 是科研 / 競賽 / 創新項目的技能包，**以 Hermes 插件交付**（`src/photon/`）。請把 `src/photon/skills/`（8 個學生技能，隨插件安裝）與 `skills-academic/`（23 個進階技能，不隨插件安裝，作 extension 選擇性安裝）視為 canonical 技能源（Issue #47 拆分）；不要把維護者私人記憶、對話史、電郵、未公開研究、db01-db09、MCP 設定或本地知識庫內容寫進 repo。
+
+## 交付路徑（Issue #47 / P2）
+
+技能只經 Hermes 插件交付，沒有其他鏡像路徑：
+
+- `src/photon/skills/`：8 個學生技能，隨插件複製到 profile 的 `~/.hermes/skills/`（hash manifest 保護，改過的副本不會被覆蓋）。
+- `skills-academic/`：23 個進階技能，**不隨插件安裝**；以 `src/photon/extensions/academic-skills.zip` 靜態出貨，經 `hermes photon-skills extensions install academic-skills` 選裝。
+- 舊的 Codex / Claude Code / OpenCode 鏡像（`.agents/skills`、`.claude/skills`、`.opencode/skills`）與 `scripts/bootstrap_agent_skills.py` 已退役，不要再加回來；記錄見 `docs/legacy-multi-client.md`。
+
+## 開發紀律
+
+- commit 只署作者本人；標題和正文寫中文；不要加 Co-Authored-By。
+- 除非使用者明確要求，否則不要 push。
+- Python 命令前先設 `PYTHONUTF8=1`；臨時產物放 `.upgrade/_e2e`。
+- 面向使用者的腳本必須親手跑 `--selftest` 到 exit 0，不能相信「已完成」報告。
+- 動態事實、論文、DOI、star、連結、能力聲明查不到就寫 `unknown/待核查`。
+- 論文數據圖必須程序化生成；禁止 AI 生圖冒充數據圖。
+- R/ggplot2 是增強路徑，不是隱含前提：缺 R 或缺套件時，先給使用者「繼續 matplotlib 誠實降級 / 安裝或設定 R / 提供 Rscript 路徑」的選擇；非互動自動流程預設降級並標 `degraded=True`，不得擅自安裝。
+
+## 快速自測
+
+```powershell
+$env:PYTHONUTF8="1"
+python scripts/check_plugin_contract.py   # manifest / 技能結構 / zip parity / 版本同步
+python scripts/release.py --selftest
+python -m pytest tests -q
+hermes plugins validate src/photon        # 本機有 Hermes 時
+```
+
+## 明確邊界
+
+`Light0305/Light-skills` 是第三方的獨立專案：不 archive、不改它的 README、不在本 repo 以外動手；`LICENSE` 保留其版權聲明。

{photon_skills-3.0.3.dev0 → photon_skills-3.0.3.dev17}/CHANGELOG.md

@@ -6,6 +6,41 @@ The project follows a pragmatic release-note style rather than claiming strict s
 
 ## [Unreleased]
 
+### Added
+
+- **`doctor`, `repair`, `feedback export` (P3).** `doctor` checks the bundled
+  skills, each profile copy (missing / edited / untracked / stale manifest
+  entries), extension payloads, install state, pip-era shims and `light-*`
+  leftovers, plus an optional project workspace; it exits 1 on errors so CI can
+  use it. `repair` applies only safe fixes (never overwrites an edited skill,
+  never touches a project) and takes `--force` for the one destructive action.
+  `feedback export` writes a skill diff plus session/mentor evidence to a folder
+  for a human-reviewed upstream proposal — nothing is uploaded. Design and
+  limits: `docs/design/self-repair.md`; `photon-orchestrator` now points at the
+  three commands when a skill misfires.
+
+### Documentation
+
+- **README rewritten as a plugin-first guide** (zh + en): the two real install
+  channels (PyPI into Hermes's own venv; git + pinned SHA for schools and
+  collaborators), migration from pip+shim and from Light-skills, the actual
+  11-command surface, troubleshooting, and a maintainer section. The retired
+  Codex / Claude Code / OpenCode instructions moved to
+  `docs/legacy-multi-client.md`; badges no longer claim 30 skills or client
+  readiness.
+
+### Removed
+
+- **Legacy multi-client path.** `scripts/bootstrap_agent_skills.py` (the Codex /
+  Claude Code / OpenCode mirror generator) and its CONTRIBUTING instructions are
+  gone; the Hermes plugin is the only supported distribution path, with the old
+  route recorded in `docs/legacy-multi-client.md`.
+- **`light_*` file naming.** `examples/e2e-research-demo/artifacts/light_e2e_case.md`
+  is now `photon_e2e_case.md`; the 23 academic `SKILL.md` files head that section
+  `## Bundled files / 隨附檔案 — Manual mode / 手動模式`, and
+  `docs/design/legacy-parity.md` records the 23↔23 mapping plus the 240
+  upstream-only references.
+
 ### Changed
 
 - **`skillset` removed (P0 cleanup).** The shipped bundle is the 8 student

{photon_skills-3.0.3.dev0 → photon_skills-3.0.3.dev17}/CONTRIBUTING.md

@@ -59,27 +59,13 @@ python scripts/release.py --selftest
 python -m pytest tests -q
 ```
 
-Legacy multi-client mirrors (being retired — the Hermes plugin is the supported
-distribution path):
-
-On Windows PowerShell:
-
-```powershell
-$env:PYTHONUTF8="1"
-python scripts\bootstrap_agent_skills.py --check-only
-```
+Skill changes reach users through the Hermes plugin only; the old Codex /
+Claude Code / OpenCode mirrors are retired — see
+[docs/legacy-multi-client.md](docs/legacy-multi-client.md). The contract script
+already checks skill structure, frontmatter names, and every local reference.
 
 If you modify a script, add or run the relevant self-test. A script that claims to support `--selftest` or an equivalent check should run successfully before the change is submitted.
 
-If you modify a skill, manually inspect the generated client layout when relevant:
-
-```powershell
-$env:PYTHONUTF8="1"
-python scripts\bootstrap_agent_skills.py --targets agents --mode auto --force
-python scripts\bootstrap_agent_skills.py --targets claude --mode auto --force
-python scripts\bootstrap_agent_skills.py --targets opencode --mode auto --force
-```
-
 ## Skill quality rules
 
 Every skill should be:

photon_skills-3.0.3.dev17/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.5
+Name: photon-skills
+Version: 3.0.3.dev17
+Summary: Photon — STEAM research, debate, and pitch competition companion for primary/secondary students
+Author-email: Uniterra Solutions Limited <harryw07801@uniterra-solutions.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/logo.png" alt="Photon Skills logo" width="170">
+
+# Photon Skills
+
+**Hermes Agent 的 STEAM 專案助手:8 個雙語學生技能 + Git 專案工作區**
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/Hermes-plugin-5B6FE0.svg" alt="Hermes plugin">
+  <img src="https://img.shields.io/badge/student%20skills-8-22C55E.svg" alt="8 student skills">
+  <img src="https://img.shields.io/badge/language-zh--Hant%20%2B%20EN-7C3AED.svg" alt="zh-Hant and English">
+  <img src="https://img.shields.io/badge/telemetry-none-6B7280.svg" alt="No telemetry">
+</p>
+
+<p><strong>繁體中文</strong> · <a href="README.en.md">English</a></p>
+
+</div>
+
+---
+
+## 這是什麼
+
+Photon 是一個 **Hermes Agent 插件**。它幫中小學生由真實生活問題出發,完成
+**腦力激盪 → 找資料 → 規劃方法 → 動手做 → 準備 pitch** 的專案旅程,
+並把整個過程寫入一個由 Git 追蹤的專案資料夾,讓導師/老師看得到進度與 AI 分工。
+
+- **學生是工作的擁有者**:Photon 是研究助理,引導但不代勞。
+- **一個專案一個資料夾**:`project-card.md`、`source-log.md`、`task-log.md`、
+  `session-log/`、`decisions.md`、`mentor-feedback/`。
+- **Session 連續性**:開始時載入專案脈絡,結束時寫紀錄並自動 commit。
+- **安全與誠信內建**:內容護欄、AI/學生分工標示、`audit-report` 給教育者審查。
+- **零遙測、零第三方依賴**:資料留在學生的電腦,只有主動 `sync` 才會上傳。
+
+> 這份 README 是唯一的安裝說明。舊版的多客戶端安裝(Codex / Claude Code /
+> OpenCode + `bootstrap_agent_skills.py`)已退役,見
+> [docs/legacy-multi-client.md](docs/legacy-multi-client.md)。
+
+## 需求
+
+| 項目 | 要求 |
+|---|---|
+| Hermes Agent | 需要 `hermes plugins` 子命令(2026-09 之後的版本) |
+| Python | 3.10+(Hermes 自帶的 venv 已滿足) |
+| Git | 2.30+(專案資料夾用 Git 追蹤) |
+| 系統 | macOS、Linux、Windows PowerShell |
+
+## 安裝
+
+### A. 公開安裝(PyPI)— 個人/學生
+
+這個 repo 是 private,公開渠道是 PyPI。**必須裝進 Hermes 自己的 venv**,
+否則 `import photon` 找不到。
+
+```bash
+# 1) 確認 Hermes 的 venv 位置(通常是 ~/.hermes/hermes-agent/venv)
+dirname "$(dirname "$(which hermes)")"
+
+# 2) 裝進去(macOS / Linux)
+~/.hermes/hermes-agent/venv/bin/pip install --upgrade photon-skills
+
+# Windows PowerShell:
+# & "$env:USERPROFILE\.hermes\hermes-agent\venv\Scripts\pip.exe" install --upgrade photon-skills
+
+# 3) 啟用
+hermes plugins enable photon-skills
+```
+
+驗證:
+
+```bash
+hermes plugins list --user --plain | grep photon-skills
+hermes photon-skills status          # 應顯示目前版本與 Bundled skills: 8
+```
+
+### B. 學校/協作者(git,釘 SHA)
+
+有 repo 權限的話,一條指令完成,而且可以釘死某個 commit:
+
+```bash
+hermes plugins install Uniterra-Solutions/Photon-skills/src/photon \
+  --ref <40 位 commit SHA> --enable
+```
+
+`src/photon` 是插件目錄;subdir 安裝只會複製該目錄,技能已放在裡面。
+釘 SHA 之後 `hermes plugins update` 會拒絕移動版本,要換版本就再跑一次
+`plugins install ... --ref <新 SHA> --force`。
+
+### C. 由舊版遷移
+
+| 你之前裝過 | 要做什麼 |
+|---|---|
+| pip `photon-skills` + 手寫 `~/.hermes/plugins/photon-skills/` shim | `hermes plugins remove photon-skills` → `rm -rf ~/.hermes/plugins/photon-skills` → `pip uninstall photon-skills` → 用上面 A 或 B 重裝 |
+| `photon` 1.0.0(PR #26 時代) | `pip uninstall photon`,並移除 `~/.hermes/plugins/photon/` |
+| `Light0305/Light-skills` 的本機 clone + `.agents/skills`、`.claude/skills`、`.opencode/skills` | 刪掉**你本機**的 clone 與鏡像目錄(上游 repo 不屬本專案,不受影響);Photon 只用 Hermes profile 的 `~/.hermes/skills/`。舊 `light-*` 技能可直接刪;23 個學術技能已改名 `photon-*` 並改以 extension 提供 |
+| 舊版留在 profile 的 `photon-*` 技能 | 換版本後跑一次 `hermes photon-skills setup --yes`,會按內容 hash 更新;你改過的副本會被保留並報告 |
+
+**專案資料夾(`~/Photon/...`、`session-log/`、`source-log.md`)在任何安裝/
+升級/移除過程中都不會被觸碰。**
+
+## 第一個專案
+
+```bash
+hermes photon-skills start-project "Water Filter Design" --steam SCIENCE
+cd ~/Photon/"Water Filter Design"
+
+hermes photon-skills session-start        # 載入 project-card 與最近 session
+# … 與 Photon 一起工作 …
+
+hermes photon-skills session-end \
+  --focus "測試三種濾材" \
+  --work-done "完成第一輪過濾實驗" \
+  --next "量測濁度" \
+  --ai-notes "AI 協助整理變因" \
+  --student-notes "我自己設計裝置"
+
+hermes photon-skills mentor-summary       # 一頁導師摘要
+hermes photon-skills sync --remote water-filter   # 發佈到 GitHub(預設 private)
+```
+
+## 指令
+
+| 指令 | 用途 |
+|---|---|
+| `setup [--profiles A,B] [--yes] [--soul-md\|--no-soul-md] [--force-soul-md]` | 把 8 個技能(可選 SOUL.md)同步到 profile |
+| `status` | 每個 profile 的版本、技能數、SOUL.md |
+| `update` | **已棄用**;更新走 `hermes plugins update` 或重新 `pip install --upgrade` |
+| `start-project <名稱> [--steam ...] [--dir ...]` | 建立專案工作區(含 `git init`) |
+| `session-start [--dir ...]` | 載入專案脈絡 |
+| `session-end --focus ... [--source ...] [--decision ...] [--task ...] [--stage ...]` | 寫 session-log、更新來源/決策/任務、自動 commit |
+| `audit-report [--dir ...]` | 教育者審計(AI vs 學生分工) |
+| `mentor-summary [--dir ...]` | 一頁導師摘要 |
+| `sync [--message ...] [--remote <repo>] [--public]` | 本地 commit / 建 GitHub remote 並 push / 離線模式 |
+| `extensions list\|install\|remove <name> [--profiles A,B]` | 選裝技能包(目前:`academic-skills`) |
+| `doctor [--dir ...] [--json]` | 診斷技能同步、state、extension、舊安裝與專案狀態(有 error 時 exit 1) |
+| `repair [--profile ...] [--force]` | 套用安全修復;`--force` 才會覆蓋你改過的技能 |
+| `feedback export [--dir ...] [--since ...] [--out ...]` | 匯出技能 diff + 專案證據供人審閱(不上傳) |
+| `selftest` | 快速自測 workspace 邏輯(exit 0) |
+
+## 技能
+
+### 學生技能(8 個,隨插件安裝,雙語)
+
+| 技能 | 作用 |
+|---|---|
+| `photon-orchestrator` | Session 入口:讀 `project-card.md`,決定下一步 |
+| `photon-session` | Session 開始/結束的紀錄與交接 |
+| `photon-brainstorm` | 引導式腦力激盪,產出衝刺/穩妥/保底點子 |
+| `photon-source-filter` | 判斷來源可不可信、有沒有用 |
+| `photon-method-planner` | 把點子變成可執行方法:步驟、材料、變因、對照、安全 |
+| `photon-progress-tracker` | 管理 `task-log.md`,依狀態建議下一步 |
+| `photon-pitch-coach` | Pitch 敘事弧線與排練 |
+| `photon-debate-coach` | 辯論/研討會:雙邊論點地圖、反駁路線、計時大綱 |
+
+詳細設計:[學生技能審計](docs/design/student-skill-audit.md) ·
+[安全與隱私](docs/design/safety-privacy.md) · [Git 持久化](docs/design/git-persistence.md)
+
+### 學術技能(23 個,選裝,manual mode)
+
+研究編排、文獻搜尋、論文寫作、圖表、排版、期刊匹配、專利、軟著等 23 個進階
+技能**不隨插件安裝**(它們的參考文件會令安裝掃描由 `safe` 變 `caution`,
+非 catalog 來源會被拒絕)。它們以靜態 zip 隨插件出貨,按需解壓:
+
+```bash
+hermes photon-skills extensions list
+hermes photon-skills extensions install academic-skills
+hermes photon-skills extensions remove  academic-skills
+```
+
+> **Manual mode**:這 23 個技能只附 `SKILL.md` 與 `references/`。文中引用的
+> `scripts/`、`assets/` 不隨此建置發佈(共 240 條引用),需要時按文件手動
+> 執行步驟,或到上游 repo 取得。這是刻意的取捨,不是缺漏。完整清單與技能地圖見
+> [skills-academic/README.md](skills-academic/README.md)。
+
+<p align="center">
+  <img src="assets/research-workflow.zh.svg" alt="Photon 學術版:從問題到交付的七階段可審計流程" width="900">
+</p>
+
+## 隱私與安全
+
+- **不收集個資**:不要求、不儲存全名、地址、電話或聯絡方式。
+- **零遙測**:Photon 不對外發送任何資料,亦無任何分析/追蹤碼。
+- **不外傳**:只有明確執行 `sync` 才會 commit/push,而且預設 private。
+- **AI 分工透明**:`session-log` 分開記錄 `ai-notes` 與 `student-notes`;
+  `audit-report` 給老師核對 AI 參與程度。
+- 完整版:[docs/design/safety-privacy.md](docs/design/safety-privacy.md)
+
+## 導師怎麼用
+
+導師不需要安裝任何東西:
+
+1. 學生把專案資料夾(或 GitHub repo 網址)給你。
+2. 直接讀 `project-card.md`、`session-log/`、`source-log.md`、`task-log.md`、
+   `mentor-feedback/`。
+3. 學生用 `hermes photon-skills mentor-summary` 產生一頁摘要;你的回饋由學生
+   記錄進 `mentor-feedback/`。
+4. 需要核對 AI 參與時,請學生跑 `hermes photon-skills audit-report`。
+
+## 疑難排解
+
+| 症狀 | 處理 |
+|---|---|
+| `hermes photon-skills: not a hermes command` | 插件未啟用:先 `hermes plugins list`,再 `hermes plugins enable photon-skills` |
+| `status` 顯示 `0 tracked` | 技能未同步:跑 `hermes photon-skills setup --yes` |
+| 版本顯示舊版 | 裝的是舊 wheel 或舊 pin:`pip install --upgrade photon-skills`,或 `plugins install ... --ref <新 SHA> --force` |
+| 你改過的技能沒有更新 | `setup` 會保留你的副本並報告(`kept your edited copy of …`),這是設計;要取回官方版就備份後刪掉該技能目錄再 `setup` |
+| `doctor` 報 `skill sync` warning | 你的副本與官方版本不同:保留改動就繼續用,想交回上游就跑 `feedback export`,想還原官方版就跑 `repair --force` |
+| 不確定哪裡壞了 | 先跑 `hermes photon-skills doctor`(加 `--json` 可貼給我);安全修復用 `repair` |
+| 完全載入不到 | `HERMES_PLUGINS_DEBUG=1 hermes plugins list` 看發現/載入日誌;`hermes logs --level WARNING \| grep -i plugin` |
+
+**手動 fallback**(插件連載入都失敗時):刪 `~/.hermes/plugins/photon-skills/`
+→ `pip uninstall photon-skills` → 用上面 A 或 B 重裝 → `hermes plugins enable
+photon-skills`。專案資料夾不受影響。
+
+## 開發與發佈(維護者)
+
+```bash
+python scripts/check_plugin_contract.py   # 契約檢查(本機有 hermes 會順便跑 validate)
+python scripts/release.py --selftest
+python -m pytest tests/ -q
+hermes plugins validate src/photon
+```
+
+發佈流程:先在 default branch 寫入版本(`python scripts/release.py --set
+X.Y.Z`),commit,再 tag `vX.Y.Z`。CI 會驗證 tag = tree 才發佈,CI 不會改寫版本。
+詳見 [CONTRIBUTING.md](CONTRIBUTING.md) 與
+[docs/design/plugin-distribution.md](docs/design/plugin-distribution.md)。
+
+> catalog 上架暫不可行:curated catalog 要求公開 repo,本 repo 是 private。
+> 現時渠道是 PyPI(公開)與 git + SHA(學校/協作者)。
+
+## 論文與圖表示範
+
+學術版技能的完整交付形態:從合成數據、分析、程序化圖表到 LaTeX PDF。
+
+<p align="center">
+  <a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">
+    <img src="projects/photocatalytic-dye-kinetics-study/paper/main-preview.png" alt="English science paper preview" width="540">
+  </a><br>
+  <sub><a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">閱讀 PDF</a></sub>
+</p>
+
+## 授權
+
+MIT — 見 [LICENSE](LICENSE)。作者:Uniterra Solutions Ltd;原始 Light-skills
+作者:Light0305。
+
+Photon 是獨立衍生專案,與原作者的 `Light0305/Light-skills` repo 無隸屬或背書
+關係;該 repo 未被本專案修改。MIT 要求保留上述版權聲明,授權檔亦隨 wheel 附上。

photon_skills-3.0.3.dev17/README.en.md

@@ -0,0 +1,273 @@
+<div align="center">
+
+<img src="assets/logo.png" alt="Photon Skills logo" width="170">
+
+# Photon Skills
+
+**A STEAM project companion for Hermes Agent: 8 bilingual student skills + a Git-backed project workspace**
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/Hermes-plugin-5B6FE0.svg" alt="Hermes plugin">
+  <img src="https://img.shields.io/badge/student%20skills-8-22C55E.svg" alt="8 student skills">
+  <img src="https://img.shields.io/badge/language-zh--Hant%20%2B%20EN-7C3AED.svg" alt="zh-Hant and English">
+  <img src="https://img.shields.io/badge/telemetry-none-6B7280.svg" alt="No telemetry">
+</p>
+
+<p><a href="README.md">繁體中文</a> · <strong>English</strong></p>
+
+</div>
+
+---
+
+## What this is
+
+Photon is a **Hermes Agent plugin**. It takes primary/secondary students from a
+real-life problem through **brainstorming → source exploration → method
+planning → building → pitch preparation**, and writes the whole journey into a
+Git-tracked project folder so mentors and teachers can see the progress and the
+AI/student split of the work.
+
+- **Students stay the owners of the work**: Photon is a research assistant — it
+  guides, it does not do the work for the student.
+- **One folder per project**: `project-card.md`, `source-log.md`,
+  `task-log.md`, `session-log/`, `decisions.md`, `mentor-feedback/`.
+- **Session continuity**: context is loaded at session start; the session is
+  recorded and auto-committed at the end.
+- **Safety and integrity built in**: content guardrails, AI/student
+  contribution labels, and `audit-report` for educators.
+- **Zero telemetry, zero third-party dependencies**: everything stays on the
+  student's machine until they explicitly run `sync`.
+
+> This README is the only install guide. The old multi-client setup (Codex /
+> Claude Code / OpenCode + `bootstrap_agent_skills.py`) is retired — see
+> [docs/legacy-multi-client.md](docs/legacy-multi-client.md).
+
+## Requirements
+
+| Item | Requirement |
+|---|---|
+| Hermes Agent | must provide the `hermes plugins` subcommand (2026-09 or later) |
+| Python | 3.10+ (the venv Hermes ships already satisfies this) |
+| Git | 2.30+ (project folders are Git-tracked) |
+| OS | macOS, Linux, Windows PowerShell |
+
+## Install
+
+### A. Public install (PyPI) — individuals
+
+This repository is private, so the public channel is PyPI. The package **must**
+be installed into Hermes's own venv, or `import photon` will not resolve.
+
+```bash
+# 1) confirm Hermes's venv (usually ~/.hermes/hermes-agent/venv)
+dirname "$(dirname "$(which hermes)")"
+
+# 2) install into it (macOS / Linux)
+~/.hermes/hermes-agent/venv/bin/pip install --upgrade photon-skills
+
+# Windows PowerShell:
+# & "$env:USERPROFILE\.hermes\hermes-agent\venv\Scripts\pip.exe" install --upgrade photon-skills
+
+# 3) enable
+hermes plugins enable photon-skills
+```
+
+Verify:
+
+```bash
+hermes plugins list --user --plain | grep photon-skills
+hermes photon-skills status          # current version and "Bundled skills: 8"
+```
+
+### B. Schools / collaborators (git, SHA-pinned)
+
+With repository access, one command does it, and it pins an exact commit:
+
+```bash
+hermes plugins install Uniterra-Solutions/Photon-skills/src/photon \
+  --ref <40-hex commit SHA> --enable
+```
+
+`src/photon` is the plugin directory; a subdir install copies only that
+directory, and the skills live inside it. Once pinned, `hermes plugins update`
+refuses to move the version — install again with
+`plugins install ... --ref <new SHA> --force` to change it.
+
+### C. Migrating from an older install
+
+| What you had | What to do |
+|---|---|
+| pip `photon-skills` + a hand-written `~/.hermes/plugins/photon-skills/` shim | `hermes plugins remove photon-skills` → `rm -rf ~/.hermes/plugins/photon-skills` → `pip uninstall photon-skills` → reinstall with A or B |
+| `photon` 1.0.0 (PR #26 era) | `pip uninstall photon` and remove `~/.hermes/plugins/photon/` |
+| A local clone of `Light0305/Light-skills` plus `.agents/skills`, `.claude/skills`, `.opencode/skills` | delete **your local** clone and mirror directories (the upstream repo is third-party and unaffected); Photon only uses the Hermes profile's `~/.hermes/skills/`. The old `light-*` skills can be deleted; the 23 academic skills are now `photon-*` and ship as an extension |
+| Old `photon-*` copies left in a profile | after upgrading, run `hermes photon-skills setup --yes`; it updates by content hash, and a copy you edited is kept and reported |
+
+**Project folders (`~/Photon/...`, `session-log/`, `source-log.md`) are never
+touched by install, upgrade, or removal.**
+
+## Your first project
+
+```bash
+hermes photon-skills start-project "Water Filter Design" --steam SCIENCE
+cd ~/Photon/"Water Filter Design"
+
+hermes photon-skills session-start        # load project-card and recent sessions
+# … work with Photon …
+
+hermes photon-skills session-end \
+  --focus "testing three filter media" \
+  --work-done "finished the first filtration run" \
+  --next "measure turbidity" \
+  --ai-notes "AI helped organise the variables" \
+  --student-notes "I designed the rig myself"
+
+hermes photon-skills mentor-summary       # one-page mentor summary
+hermes photon-skills sync --remote water-filter   # publish to GitHub (private by default)
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `setup [--profiles A,B] [--yes] [--soul-md\|--no-soul-md] [--force-soul-md]` | Sync the 8 skills (optionally SOUL.md) into profiles |
+| `status` | Version, skill count, and SOUL.md per profile |
+| `update` | **Deprecated**; update through `hermes plugins update` or `pip install --upgrade` |
+| `start-project <name> [--steam ...] [--dir ...]` | Scaffold a project workspace (incl. `git init`) |
+| `session-start [--dir ...]` | Load project context |
+| `session-end --focus ... [--source ...] [--decision ...] [--task ...] [--stage ...]` | Write session-log, update source/decision/task logs, auto-commit |
+| `audit-report [--dir ...]` | Educator audit (AI vs student split) |
+| `mentor-summary [--dir ...]` | One-page mentor summary |
+| `sync [--message ...] [--remote <repo>] [--public]` | Local commit / create a GitHub remote and push / offline mode |
+| `extensions list\|install\|remove <name> [--profiles A,B]` | Optional skill packs (currently `academic-skills`) |
+| `doctor [--dir ...] [--json]` | Diagnose skill sync, state, extensions, legacy installs, and a project (exit 1 on errors) |
+| `repair [--profile ...] [--force]` | Apply safe fixes; `--force` also restores skills you edited |
+| `feedback export [--dir ...] [--since ...] [--out ...]` | Export skill diffs + project evidence for human review (nothing uploaded) |
+| `selftest` | Quick workspace self-test (exit 0) |
+
+## Skills
+
+### Student skills (8, shipped with the plugin, bilingual)
+
+| Skill | Purpose |
+|---|---|
+| `photon-orchestrator` | Session entry point: reads `project-card.md` and decides the next step |
+| `photon-session` | Session start/end recording and handover |
+| `photon-brainstorm` | Guided brainstorming into stretch/solid/safe ideas |
+| `photon-source-filter` | Judges whether a source is credible and useful |
+| `photon-method-planner` | Turns an idea into an executable method: steps, materials, variables, controls, safety |
+| `photon-progress-tracker` | Maintains `task-log.md` and suggests the next step |
+| `photon-pitch-coach` | Pitch narrative arc and rehearsal |
+| `photon-debate-coach` | Debate/symposium: both-side argument maps, rebuttal lines, timed outlines |
+
+Design docs: [Student skill audit](docs/design/student-skill-audit.md) ·
+[Safety & privacy](docs/design/safety-privacy.md) ·
+[Git persistence](docs/design/git-persistence.md)
+
+### Academic skills (23, opt-in, manual mode)
+
+The 23 advanced skills (research orchestration, literature search, paper
+writing, figures, typesetting, venue matching, patents, software copyright…)
+are **not installed with the plugin**: their reference material moves the
+install scan from `safe` to `caution`, and a non-catalog source is refused at
+`caution`. They ship as a static zip and are unpacked on demand:
+
+```bash
+hermes photon-skills extensions list
+hermes photon-skills extensions install academic-skills
+hermes photon-skills extensions remove  academic-skills
+```
+
+> **Manual mode**: these 23 skills ship `SKILL.md` and `references/` only. The
+> `scripts/` and `assets/` they mention are not part of this build (240
+> referenced paths in total) — follow the steps by hand, or take the helpers
+> from the upstream repository. That is a deliberate trade-off, not a gap. Full
+> catalogue and skill map: [skills-academic/README.md](skills-academic/README.md).
+
+<p align="center">
+  <img src="assets/research-workflow.en.svg" alt="Photon academic pack: seven auditable stages from question to delivery" width="900">
+</p>
+
+## Privacy and safety
+
+- **No PII collected**: no full names, addresses, phone numbers, or contact
+  details are requested or stored.
+- **Zero telemetry**: Photon sends no data anywhere and contains no analytics or
+  tracking code.
+- **No external sharing**: only an explicit `sync` commits/pushes, private by
+  default.
+- **Transparent AI split**: `session-log` records `ai-notes` and
+  `student-notes` separately; `audit-report` shows educators how much the AI
+  contributed.
+- Full version: [docs/design/safety-privacy.md](docs/design/safety-privacy.md)
+
+## How mentors use it
+
+Mentors do not install anything:
+
+1. The student shares the project folder (or the GitHub repo URL).
+2. Read `project-card.md`, `session-log/`, `source-log.md`, `task-log.md`, and
+   `mentor-feedback/` directly.
+3. The student runs `hermes photon-skills mentor-summary` for a one-page
+   summary; mentor feedback is recorded by the student into
+   `mentor-feedback/`.
+4. To check the AI/student split, ask the student to run
+   `hermes photon-skills audit-report`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `hermes photon-skills: not a hermes command` | plugin not enabled: check `hermes plugins list`, then `hermes plugins enable photon-skills` |
+| `status` shows `0 tracked` | skills were not synced: run `hermes photon-skills setup --yes` |
+| Version shows an older release | you have an old wheel or an old pin: `pip install --upgrade photon-skills`, or `plugins install ... --ref <new SHA> --force` |
+| A skill you edited is not updating | `setup` keeps your copy and reports it (`kept your edited copy of …`) by design; to take the official version, back up and delete that skill directory, then run `setup` |
+| `doctor` reports a `skill sync` warning | your copy differs from the shipped one: keep it, run `feedback export` to propose it upstream, or `repair --force` to restore the official version |
+| You are not sure what is broken | run `hermes photon-skills doctor` (add `--json` to share it); safe fixes are `repair` |
+| Nothing loads at all | `HERMES_PLUGINS_DEBUG=1 hermes plugins list` for discovery/load logs; `hermes logs --level WARNING \| grep -i plugin` |
+
+**Manual fallback** (when even loading fails): delete
+`~/.hermes/plugins/photon-skills/` → `pip uninstall photon-skills` → reinstall
+with A or B → `hermes plugins enable photon-skills`. Project folders are
+unaffected.
+
+## Development and releases (maintainers)
+
+```bash
+python scripts/check_plugin_contract.py   # contract checks (+ real validator when hermes has it)
+python scripts/release.py --selftest
+python -m pytest tests/ -q
+hermes plugins validate src/photon
+```
+
+Release flow: write the version on the default branch
+(`python scripts/release.py --set X.Y.Z`), commit, then tag `vX.Y.Z`. CI
+verifies tag = tree before publishing and never rewrites the version. See
+[CONTRIBUTING.md](CONTRIBUTING.md) and
+[docs/design/plugin-distribution.md](docs/design/plugin-distribution.md).
+
+> Catalog admission is not available yet: the curated catalog requires a public
+> repository, and this one is private. The current channels are PyPI (public)
+> and git + SHA (schools/collaborators).
+
+## Paper and figure demo
+
+The academic pack's full deliverable shape: synthetic data → analysis →
+programmatic figures → LaTeX PDF.
+
+<p align="center">
+  <a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">
+    <img src="projects/photocatalytic-dye-kinetics-study/paper/main-preview.png" alt="English science paper preview" width="540">
+  </a><br>
+  <sub><a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">Read the PDF</a></sub>
+</p>
+
+## License
+
+MIT — see [LICENSE](LICENSE). Author: Uniterra Solutions Ltd; original
+Light-skills author: Light0305.
+
+Photon is an independent derivative: it is not affiliated with or endorsed by
+the original Light-skills author, and that repository is left untouched. MIT
+requires keeping the copyright notice above; the licence file ships inside the
+wheel as well.