photon-skills 3.0.3.dev3__tar.gz → 3.0.3.dev19__tar.gz

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/.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.dev19/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.dev3 → photon_skills-3.0.3.dev19}/CHANGELOG.md

@@ -6,6 +6,31 @@ 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.
+
+### Changed
+
+- **`doctor` explains drift instead of calling everything an edit.** A copy that
+  differs from the bundle now reports `N changed / N extra / N missing` with an
+  example path, so a template a student added reads as `1 extra` rather than as
+  an edited skill. `repair` also drops profiles from the install state whose home
+  is gone, which used to raise a permanent harmless warning.
+- **`photon-debate-coach` ships an evidence sheet** (`templates/evidence-sheet.md`);
+  Stage A now produces `debate-prep/evidence-sheet.md` when a case rests on
+  numbers — original source, quotable line, denominator, what the evidence does
+  *not* prove, and a 待核查 column that never goes on stage.
+
 ### Documentation
 
 - **README rewritten as a plugin-first guide** (zh + en): the two real install
@@ -16,6 +41,18 @@ The project follows a pragmatic release-note style rather than claiming strict s
   `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.dev3 → photon_skills-3.0.3.dev19}/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.dev3 → photon_skills-3.0.3.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: photon-skills
-Version: 3.0.3.dev3
+Version: 3.0.3.dev19
 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
@@ -146,6 +146,9 @@ hermes photon-skills sync --remote water-filter   # 發佈到 GitHub(預設 priv
 | `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) |
 
 ## 技能
@@ -215,6 +218,8 @@ hermes photon-skills extensions remove  academic-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/`
@@ -253,3 +258,6 @@ X.Y.Z`),commit,再 tag `vX.Y.Z`。CI 會驗證 tag = tree 才發佈,CI 不會改
 
 MIT — 見 [LICENSE](LICENSE)。作者:Uniterra Solutions Ltd;原始 Light-skills
 作者:Light0305。
+
+Photon 是獨立衍生專案,與原作者的 `Light0305/Light-skills` repo 無隸屬或背書
+關係;該 repo 未被本專案修改。MIT 要求保留上述版權聲明,授權檔亦隨 wheel 附上。

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/README.en.md

@@ -140,6 +140,9 @@ hermes photon-skills sync --remote water-filter   # publish to GitHub (private b
 | `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
@@ -219,6 +222,8 @@ Mentors do not install anything:
 | `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
@@ -261,3 +266,8 @@ programmatic figures → LaTeX PDF.
 
 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.

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/README.md

@@ -133,6 +133,9 @@ hermes photon-skills sync --remote water-filter   # 發佈到 GitHub(預設 priv
 | `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) |
 
 ## 技能
@@ -202,6 +205,8 @@ hermes photon-skills extensions remove  academic-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/`
@@ -240,3 +245,6 @@ X.Y.Z`),commit,再 tag `vX.Y.Z`。CI 會驗證 tag = tree 才發佈,CI 不會改
 
 MIT — 見 [LICENSE](LICENSE)。作者:Uniterra Solutions Ltd;原始 Light-skills
 作者:Light0305。
+
+Photon 是獨立衍生專案,與原作者的 `Light0305/Light-skills` repo 無隸屬或背書
+關係;該 repo 未被本專案修改。MIT 要求保留上述版權聲明,授權檔亦隨 wheel 附上。

photon_skills-3.0.3.dev19/docs/compatibility/agent-client-compatibility.md

@@ -0,0 +1,14 @@
+# Agent-client compatibility (retired) / 客戶端兼容性(已退役)
+
+> **Retired.** Photon is a Hermes plugin now. The Codex / Claude Code / OpenCode
+> discovery paths and `bootstrap_agent_skills.py` are no longer supported: the
+> plugin copies its skills into the active Hermes profile and that is the only
+> supported layout.
+>
+> **已退役。** Photon 現在是 Hermes 插件;Codex / Claude Code / OpenCode 的發現
+> 路徑與 `bootstrap_agent_skills.py` 不再支援。
+
+- Record of the old layouts and why they were dropped:
+  [docs/legacy-multi-client.md](../legacy-multi-client.md)
+- Supported install and migration:
+  [README.md](../../README.md)

photon_skills-3.0.3.dev19/docs/design/legacy-parity.md

@@ -0,0 +1,82 @@
+# Legacy pack parity / 舊版覆蓋報告
+
+> Issue #47 follow-up (P2). Answers one question with evidence: **is the old
+> `Light-skills` pack fully covered by Photon?** 23 legacy skills, 23 academic
+> skills, measured on the tree at this commit.
+>
+> Issue #47 後續(P2)。用可重跑的數字回答一個問題:舊 `Light-skills` 包是否已被
+> Photon 完全覆蓋。
+
+## Verdict / 結論
+
+| Dimension | Result |
+|---|---|
+| Skill names | **23 / 23 mapped**, no gaps, no extras |
+| Instructions (`SKILL.md` + `references/`) | covered |
+| Executable helpers (`scripts/`, `assets/`, `examples/`) | **not shipped** — 240 referenced paths are upstream-only (manual mode) |
+| Old install path (Codex / Claude Code / OpenCode + bootstrap) | retired — [legacy-multi-client.md](legacy-multi-client.md) |
+| Original repo (`Light0305/Light-skills`) | third-party, left untouched; Photon is an independent derivative (MIT attribution kept) |
+
+So "covered" means **naming + instructions**, not tooling. That was a deliberate
+trade-off: shipping the academic helpers pushes the plugin security scan from
+`safe` to `caution`, and a non-catalog git install is refused at `caution`. The
+helpers stay in the repository at `skills-academic/`, and every affected
+`SKILL.md` says so in a `Manual mode` section.
+
+## Mapping / 對照
+
+Generated from the tree by `scripts/check_plugin_contract.py`-style inspection
+(regenerate with the snippet at the bottom).
+
+| Legacy | Photon | Files in `skills-academic/` | Missing referenced paths |
+|---|---|---|---|
+| `light-citation` | `photon-citation` | 8 | 9 |
+| `light-consistency` | `photon-consistency` | 5 | 10 |
+| `light-data-engineering` | `photon-data-engineering` | 8 | 17 |
+| `light-experiment-coding` | `photon-experiment-coding` | 9 | 26 |
+| `light-figure` | `photon-figure` | 11 | 13 |
+| `light-file-reading` | `photon-file-reading` | 8 | 10 |
+| `light-frontend-design` | `photon-frontend-design` | 9 | 8 |
+| `light-idea-critique` | `photon-idea-critique` | 10 | 11 |
+| `light-idea-generation` | `photon-idea-generation` | 10 | 11 |
+| `light-literature-search` | `photon-literature-search` | 7 | 16 |
+| `light-memory-pm` | `photon-memory-pm` | 3 | 17 |
+| `light-paper-writing` | `photon-paper-writing` | 14 | 11 |
+| `light-patent-disclosure` | `photon-patent-disclosure` | 4 | 1 |
+| `light-project-structure` | `photon-project-structure` | 5 | 2 |
+| `light-research-ethics` | `photon-research-ethics` | 6 | 15 |
+| `light-orchestrator` | `photon-research-orchestrator` | 7 | 8 |
+| `light-research-plan` | `photon-research-plan` | 12 | 9 |
+| `light-result-analysis` | `photon-result-analysis` | 9 | 15 |
+| `light-review-rebuttal` | `photon-review-rebuttal` | 12 | 10 |
+| `light-software-copyright` | `photon-software-copyright` | 4 | 2 |
+| `light-system-design` | `photon-system-design` | 11 | 5 |
+| `light-typesetting` | `photon-typesetting` | 12 | 7 |
+| `light-venue-matching` | `photon-venue-matching` | 9 | 7 |
+
+`light-orchestrator` is the one rename that is not a pure prefix swap
+(`photon-research-orchestrator`) because `photon-orchestrator` is the student
+session skill.
+
+## What still says "Light" (and why)
+
+| Location | Status |
+|---|---|
+| `LICENSE` | kept — Light0305 is the original author, attribution is required |
+| `docs/competitors/*` | kept — research notes written in the Light era, not installed |
+| `docs/releases/v1.0.0.md` | kept with a historical banner |
+| `examples/e2e-research-demo/artifacts/photon_e2e_case.md` | renamed from `light_e2e_case.md` |
+| `scripts/bootstrap_agent_skills.py` | deleted |
+| `README.md` / `README.en.md` | rewritten plugin-first; old path archived in `legacy-multi-client.md` |
+
+## Regenerate
+
+```python
+import re
+from pathlib import Path
+root = Path("skills-academic")
+REF = re.compile(r"(?<![\w/.-])((?:scripts|templates|references|examples|assets)/[A-Za-z0-9_./-]+)")
+for skill in sorted(root.glob("photon-*")):
+    refs = set(REF.findall((skill / "SKILL.md").read_text(encoding="utf-8")))
+    print(skill.name, len([r for r in refs if not (skill / r).exists()]))
+```

photon_skills-3.0.3.dev19/docs/design/self-repair.md

@@ -0,0 +1,113 @@
+# Self-diagnosis, repair, and human-gated improvement
+
+> P3 deliverable. Three CLI verbs that make a Photon installation inspectable and
+> fixable by the person using it: `doctor`, `repair`, `feedback export`.
+>
+> P3 交付物:三個 CLI 指令,令使用者自己檢查、修復、並把改進交回上游。
+
+## Why this exists
+
+Photon copies its skills into the active profile and records a content hash per
+copy. That rule is deliberately non-destructive — a copy the student edited is
+kept and reported, never silently overwritten. The cost is **silent drift**:
+
+- a skill can be missing (deleted, partial sync, old install) and nothing says so;
+- a pip-era shim can shadow the real plugin while `plugins list` still shows it
+  enabled;
+- an edited skill stops receiving upstream fixes, and neither side can tell;
+- an installed extension can lose its payload or its skills.
+
+None of that is fixable by the Hermes core: `hermes plugins validate` checks the
+plugin directory, not the profile copies. Hence a product-level doctor.
+
+## Commands
+
+```bash
+hermes photon-skills doctor [--dir PROJECT] [--json] [--verbose]
+hermes photon-skills repair [--profile NAME] [--force]
+hermes photon-skills feedback export [--dir PROJECT] [--since YYYY-MM-DD] [--out DIR]
+```
+
+`doctor` is read-only and exits `1` when any check is an **error** (usable in
+CI). `repair` only writes inside the profile's `skills/` dir and the plugin
+state file. `feedback export` only writes the output directory you give it.
+
+## What `doctor` checks
+
+| Check | What it reports | Severity |
+|---|---|---|
+| `bundled skills` | the plugin dir has skills, and each has `SKILL.md` | error |
+| `profile` | the active profile's home exists | error |
+| `skills dir` | `<profile>/skills` exists | error |
+| `skill sync` | bundled skill missing; a copy that differs from the bundle (per-file `N changed / N extra / N missing`, with an example path); untracked by the manifest; all in sync | error / warn / ok |
+| `manifest` | stale entries pointing at removed skills | warn |
+| `manifest version` | manifest records an older plugin version | warn |
+| `extension` | installed payload missing, payload hash changed, extension skills missing; or none installed | warn / ok |
+| `state` | removed `skillset` key still present; active profile not registered; profiles listed but missing on disk | warn |
+| `legacy install` | a pip-era shim (`from photon import register`) shadows the plugin | error |
+| `legacy skills` | retired `light-*` skill directories in the profile | warn |
+| `distribution` | a pip distribution version differs from the loaded plugin | warn |
+| `project files` | `--dir`: `project-card.md`, logs, `.photon-project`, `session-log/`, `mentor-feedback/` | error |
+| `project git` | `--dir`: not a Git repo, or uncommitted changes | warn / ok |
+
+Local edits are detected by comparing the copy with the **bundle**, not with the
+last recorded hash: adopting an edit as the new baseline (which `sync` does) must
+not make the divergence invisible. The comparison is per file, so an added
+template reads as `1 extra`, not as an edit of the whole skill.
+
+## What `repair` does
+
+| Situation | Safe (default) | `--force` |
+|---|---|---|
+| bundled skill missing | copy it from the bundle, record its hash | same |
+| skill edited locally | keep the edit, update the baseline hash | restore the bundled copy (destructive) |
+| extra file added to a skill copy | keep it | delete it (the copy is restored from the bundle) |
+| file deleted from a skill copy | restored on the next `setup`; `repair` reports it | restored from the bundle |
+| state lists a profile that is not on disk | drop it from the state | same |
+| skill present but untracked | adopt it only when byte-identical to the bundle | same |
+| stale manifest entry (skill no longer bundled) | drop the entry | same |
+| stale `skillset` key in state | drop it | same |
+| project folder | **never touched** | **never touched** |
+
+`repair` never deletes a skill directory it did not create, never edits the
+plugin dir, and never touches a project.
+
+## What `feedback export` produces
+
+```
+photon-feedback-YYYYMMDD/
+├── skill-patches.diff   # unified diff: bundle → your edited copy (per skill)
+├── EVIDENCE.md          # session-log/*.md, mentor-feedback/*.md, audit-report-*.md
+└── manifest.json        # changed skills, evidence file names, project path
+```
+
+Nothing is uploaded, and no issue is filed automatically: a human reviews the
+bundle and opens a PR or an issue. That is the deliberate shape of
+"self-improvement" here — the plugin may improve **with** its users, but the
+plugin directory itself stays read-only (Hermes plugin rule: no self-updating
+code).
+
+## Limits worth stating
+
+- If the plugin does not load at all, `doctor` cannot run either — the README's
+  manual fallback (remove the shim, uninstall, reinstall, enable) is the only
+  path, and `doctor` is for "loaded but broken".
+- A local edit still pins that skill to its edited version: upstream fixes arrive
+  only after `repair --force` or a manual merge. The doctor warning is the
+  signal; `feedback export` is the constructive follow-up.
+- The doctor reads state and disk. It does not inspect Hermes's own logs; use
+  `HERMES_PLUGINS_DEBUG=1` for loader problems.
+
+## Verification
+
+```bash
+# unit tests: missing / edited / orphan / stale-state / shim / project / export
+python -m pytest tests/test_health.py -q
+
+# on a throwaway home
+HERMES_HOME=$(mktemp -d) hermes photon-skills setup --yes --profiles default --no-soul-md
+HERMES_HOME=... hermes photon-skills doctor
+rm -rf "$HERMES_HOME/skills/photon-session"
+HERMES_HOME=... hermes photon-skills doctor; echo "exit=$?"   # 1, skill missing
+HERMES_HOME=... hermes photon-skills repair
+```

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/docs/legacy-multi-client.md

@@ -75,8 +75,12 @@ hermes photon-skills extensions install academic-skills
    `~/.hermes/skills/`, and `hermes photon-skills setup --yes` keeps them in
    sync.
 
-The old upstream repository (`Light0305/Light-skills`) is archived and points
-here; its history is still readable, but it receives no updates.
+The original project, `Light0305/Light-skills`, belongs to a third party and is
+unchanged by this repository — it is not ours to archive or edit. Photon is an
+independent derivative: the 23 academic skills were renamed `photon-*` and the
+multi-client install path was removed here, while attribution stays in
+[`LICENSE`](../LICENSE) and the README credits. If upstream ever moves, this page
+is the record of what was derived from it.
 
 ## Historical note
 

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/docs/releases/v1.0.0.md

@@ -1,5 +1,10 @@
 # Photon Skills v1.0.0 Release Notes
 
+> **Historical note (2026-10).** This release describes the multi-client era
+> (Codex / Claude Code / OpenCode + `bootstrap_agent_skills.py`). Photon is now a
+> Hermes plugin and that install path is retired — see
+> [docs/legacy-multi-client.md](../legacy-multi-client.md) and the README.
+
 Release date: 2026-07-05
 
 Photon Skills v1.0.0 is the first public release of the rebuilt Photon Skills package: a domain-independent AI workflow skill library for research, competitions, and innovation projects.

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/examples/e2e-research-demo/README.md

@@ -11,7 +11,7 @@
 - `data/synthetic_experiment.csv`：可复现实验数据。
 - `figures/research_figure_gallery.png`：九宫格科研图廊；每个 panel 使用独立合成数据，图面不写工具名。
 - `figures/panels/`：九宫格的 9 个单图 panel，其中一部分由 Python/matplotlib 生成，一部分由 R/ggplot2 生成。
-- `artifacts/light_e2e_case.md`：把 Photon Skills 的 23 个技能如何接力写成一个端到端案例。
+- `artifacts/photon_e2e_case.md`：把 Photon Skills 的 23 个技能如何接力写成一个端到端案例。
 
 ## 一键复现
 

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/projects/photocatalytic-dye-kinetics-study/paper/main.tex

@@ -24,7 +24,7 @@ This synthetic study demonstrates a reproducible environmental-chemistry workflo
 \textbf{Honesty boundary.} All concentration traces are synthetic and generated by the repository script. The package demonstrates a science-style workflow: data, analysis, figures, references, manuscript, LaTeX source, PDF, and preview.
 
 \section{Introduction}
-Semiconductor photocatalysis is a long-running route for light-driven environmental remediation~\cite{fujishima1972,hoffmann1995,pelaez2012}. A realistic computational demonstration should include time-resolved concentration traces, kinetic fitting, design-factor response surfaces, diagnostics, and mechanistic perturbation. This project uses that structure to showcase Light Skills without inventing experimental evidence.
+Semiconductor photocatalysis is a long-running route for light-driven environmental remediation~\cite{fujishima1972,hoffmann1995,pelaez2012}. A realistic computational demonstration should include time-resolved concentration traces, kinetic fitting, design-factor response surfaces, diagnostics, and mechanistic perturbation. This project uses that structure to showcase Photon Skills without inventing experimental evidence.
 
 \begin{figure}[htbp]
 \centering

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "photon-skills"
-version = "3.0.3.dev3"
+version = "3.0.3.dev19"
 description = "Photon — STEAM research, debate, and pitch competition companion for primary/secondary students"
 authors = [
     { name = "Uniterra Solutions Limited", email = "harryw07801@uniterra-solutions.com" },

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-citation/SKILL.md

@@ -270,12 +270,12 @@ passes and passport records `delivered`.
 - [ ] citation gate and stage-10 checkpoint pass.
 - [ ] typesetting consumed the delivered BibTeX/citekeys.
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/citation_checklist.md`
 > - `scripts/citation_four_gate.py`

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-consistency/SKILL.md

@@ -312,12 +312,12 @@ Round 3.1 再补 `consistency_delta.py`：两次 `light.findings.v1` 直接比
 - 事实源模板:[`assets/`](assets/)——`glossary.yaml` / `method_lock.yaml` / `metric_registry.yaml` / `claims_registry.yaml`(复制进项目 `.light/consistency/` 填真实值)
 - 可运行示例:[`examples/`](examples/)——`materials_paper.txt` / `materials_ppt.txt`(论文 vs PPT 指标/术语冲突)
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/claims_registry.yaml`
 > - `assets/consistency-registry.example.json`

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-data-engineering/SKILL.md

@@ -306,12 +306,12 @@ GX 哲学的轻量同构，纯 pandas+PyYAML）。
 - 地基契约：[`_shared/README.md`](../../_shared/README.md)（`findings_schema` · `gate_runner` · 规范 bootstrap）
 - 上游/下游：[`photon-idea-generation`](../photon-idea-generation/)（stage 3，立项卡"数据可行性必答字段"，2⊣3 前置回边）· [`photon-research-orchestrator/scripts/run_checkpoint.py`](../photon-research-orchestrator/scripts/run_checkpoint.py)（stage 2 聚合 critical fail→exit 1）· [`reroute.py`](../photon-research-orchestrator/scripts/reroute.py)（ROUTES[2] 建议 2⊣3）· research-plan(stage 5，派生评测集回边)
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/data_card_template.md`
 > - `scripts/check_access_level.py`

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-experiment-coding/SKILL.md

@@ -206,12 +206,12 @@ lineage 与 keep/discard。这里的实际增量是：
 
 诚实落后项：没有 MLflow 式查询 UI、DVC remote、GPU scheduler、仓库语义索引或自主 experiment search；静态门仍有边界。
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/project-scaffold/.github/workflows/ci.yml`
 > - `assets/project-scaffold/.pre-commit-config.yaml`

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-figure/SKILL.md

@@ -226,12 +226,12 @@ python figure_visual_qa.py --shapes shapes.json   # 纯几何;或在绘图脚本
 - **竞品诚实重述（Round 2 R1）**：截轴/双轴/render-then-look/出版规格/色盲是**同类共识**（scipilot 530★ 18-pitfall、davila7 28.2K★ 13-pt checklist 都覆盖），**非 Light 独创**；Light 真增量=把同一 catalog 做成**确定性机读 critical 门 + 绑 result-analysis 证据档(`misrepresent_evidence`，10 同类零覆盖) + 9→7 回炉 + 集合预算**——同类全是 prose 规则 + refusal 启发 + 人工 checklist。见 truth_source §0.A/§0.C。
 - **零 MCP/零本地库**：framework 图用 Draw.io（diagram-as-code，CLI 导出）/TikZ 程序化生成，不依赖 MCP；venue 规格在线查/用户给，不内嵌本地期刊库。
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/nature.mplstyle`
 > - `assets/publication.mplstyle`

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-file-reading/SKILL.md

@@ -320,12 +320,12 @@ Light 的价值**不是会读**，而是把理解落成**有输入画像、有
 - 理解状态机示例：[`assets/reading-contract.example.json`](assets/reading-contract.example.json)（故意 fail-closed，展示盲测类缺口）
 - 项目记忆归属：[`../photon-memory-pm/SKILL.md`](../photon-memory-pm/SKILL.md)（理解笔记登记落 `.light/`，本技能不自管台账）
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/extraction-benchmark.example.json`
 > - `assets/reading-contract.example.json`

{photon_skills-3.0.3.dev3 → photon_skills-3.0.3.dev19}/skills-academic/photon-frontend-design/SKILL.md

@@ -219,12 +219,12 @@ sha256；对比度报告必须是 `light.visual_qa.v1`，浏览器报告必须
 - **零本地库 = 灵感/版本在线查**：但灵感站多图、可能 WebFetch 受限（Mobbin/Dribbble）→ 诚实降级 unavailable，不假装看到了。
 - **非 DAG 节点**：本技能不进科研流水线、不产 findings、不阻断;它是「要做界面时叫一下」的按需工具,别期待它像主线技能那样被总控自动编排。
 
-## Bundled files / 隨附檔案
+## Bundled files / 隨附檔案 — Manual mode / 手動模式
 
-> This build ships this skill's `SKILL.md` and references only. The
-> helper files below live in the upstream repository, not in the
-> installed plugin (Issue #47 slim build). Run the steps in this
-> document manually, or clone upstream when you need them:
+> This build ships this skill's `SKILL.md` and references only: **manual mode**.
+> The helper files listed below live in the upstream repository, not in the
+> installed plugin (Issue #47 slim build). Run the steps in this document by
+> hand, or clone upstream when you need them:
 
 > - `assets/gsap-horizontal-pan.tsx`
 > - `assets/gsap-sticky-stack.tsx`