From 74f5a40986cb8de1797ff63df8bd8fb564543271 Mon Sep 17 00:00:00 2001
From: lisihao <lisihao@gmail.com>
Date: Fri, 5 Jun 2026 17:49:42 -0400
Subject: [PATCH 1/5] Clarify install deployment and agent path on homepage

---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 53e3e50c8..eb3289c3b 100644
--- a/README.md
+++ b/README.md
@@ -157,6 +157,9 @@ This is the operating model:
 | Model / operator registry | Available | Model aliases, physical operators, actors, hosts, capability/risk/cost profiles. |
 | Evidence-native evaluation | Available | Handoff, eval, node verdict, session logs, deterministic research gates. |
 | Remote worker path | Available / evolving | Remote sync, dispatch, monitor, and verification scripts are present. |
+| Plugin framework | Available / evolving | Harness can load and validate `harness/plugins/<id>/manifest.yaml` when plugin manifests are present. The public repo does not need to ship enabled third-party plugins by default. |
+| Solar-bundled skills | Available | Repository skills are copied into `~/.claude/skills/` by `install.sh`. Counts may change with the repo. |
+| Third-party skills | Optional | Installed separately through `SKILLS-INSTALL.md`; they are an enhancement, not required for the base install. |
 | Deep Research OS | Evolving | Evidence extraction, citation checking, research evaluation, and report gates. |
 | Context Map / PEEK-style layer | Planned / integrating | Orientation cache for repos, topics, vaults, and long-running projects. |
 | Meta Harness self-optimization | Planned / integrating | Optimizes text artifacts using evaluator score, side-info, replay, and promotion gates. |
@@ -166,6 +169,8 @@ This is the operating model:
 
 ## Quick Start
 
+### Human install
+
 ```bash
 git clone https://github.com/lisihao/Solar.git ~/Solar
 cd ~/Solar
@@ -177,10 +182,37 @@ What install does:
 - copies Solar Core assets into `~/.claude/`;
 - creates `~/.solar/`;
 - syncs the published `harness/` source into `~/.solar/harness/` when present;
+- copies optional packaged runtime components such as `mempalace/` and `codex-bridge/` when present;
 - creates `~/.solar/bin/solar-harness`;
-- runs install verification.
+- runs L1 + L2 install verification.
+
+### Agent install / deploy / self-check path
+
+If you want Claude, Codex, Cursor, Copilot, or another code agent to install Solar for you, give it this exact instruction:
+
+```text
+Install Solar from https://github.com/lisihao/Solar using INSTALL-AGENT.md.
+Follow the steps exactly. Before each command, report: purpose, command, and expected output.
+Do not use sudo/root. Stop immediately on any failure and show the exact output.
+After installation, run the L1 + L2 self-check:
+
+cd ~/Solar && ./install.sh
+~/.solar/bin/solar-harness help
+cd ~/Solar && ./scripts/sync-harness-runtime.sh
+~/.solar/bin/solar-harness help
 
-Harness runtime:
+If optional third-party skills are requested, use SKILLS-INSTALL.md, but do not install optional third-party skills without asking first.
+```
+
+Dedicated documents:
+
+| Document | Purpose |
+|---|---|
+| [`INSTALL-AGENT.md`](INSTALL-AGENT.md) | Step-by-step install/deploy/self-check protocol for AI agents. |
+| [`SKILLS-INSTALL.md`](SKILLS-INSTALL.md) | Optional skill expansion protocol for AI agents. |
+| [`scripts/sync-harness-runtime.sh`](scripts/sync-harness-runtime.sh) | Syncs repository `harness/` into the local runtime `~/.solar/harness/`. |
+
+### Harness runtime
 
 ```bash
 cd ~/Solar
@@ -197,6 +229,15 @@ Runtime boundary:
 
 Runtime logs, databases, private trajectories, local model caches, credentials, and machine-local state should not be committed as source.
 
+### Optional skills and plugins
+
+Base install is intentionally conservative:
+
+- Solar-bundled skills are copied from `skills/` into `~/.claude/skills/`.
+- Third-party skill packs are optional; use [`SKILLS-INSTALL.md`](SKILLS-INSTALL.md) and ask the user before installing optional repositories.
+- Harness plugin support is installed as framework code. Plugins must provide `harness/plugins/<id>/manifest.yaml` and pass plugin validation before they should be treated as usable.
+- API keys are optional for install. If you need API-backed features, copy `.env.template` to `.env` and fill values locally. Do not commit `.env`.
+
 ---
 
 ## Design Principles

From 525cd984f45bf88694b4638d353845a5a6338b24 Mon Sep 17 00:00:00 2001
From: lisihao <lisihao@gmail.com>
Date: Fri, 5 Jun 2026 17:51:35 -0400
Subject: [PATCH 2/5] Add environment template for optional API-backed features

---
 .env.template | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 .env.template

diff --git a/.env.template b/.env.template
new file mode 100644
index 000000000..8207c2dee
--- /dev/null
+++ b/.env.template
@@ -0,0 +1,25 @@
+# Solar optional API-backed features
+#
+# Installation does not require API keys. Copy this file to `.env` only when
+# you want API-backed model/tool integrations. Never commit `.env`.
+#
+# cp .env.template .env
+
+# Anthropic / Claude API
+ANTHROPIC_API_KEY=
+
+# OpenAI / Codex / GPT API
+OPENAI_API_KEY=
+
+# Zhipu GLM API
+ZHIPU_API_KEY=
+
+# DeepSeek API
+DEEPSEEK_API_KEY=
+
+# Google Gemini API
+GEMINI_API_KEY=
+
+# Optional local/runtime knobs
+SOLAR_HOME=$HOME/.solar
+HARNESS_DIR=$HOME/.solar/harness

From 2f23985f65389686eb72cef3d18be2ba5b688884 Mon Sep 17 00:00:00 2001
From: lisihao <lisihao@gmail.com>
Date: Fri, 5 Jun 2026 17:52:29 -0400
Subject: [PATCH 3/5] Refresh agent install deploy self-check protocol

---
 INSTALL-AGENT.md | 398 +++++++++++++++++------------------------------
 1 file changed, 142 insertions(+), 256 deletions(-)

diff --git a/INSTALL-AGENT.md b/INSTALL-AGENT.md
index fb3283382..2e27491d7 100644
--- a/INSTALL-AGENT.md
+++ b/INSTALL-AGENT.md
@@ -1,366 +1,252 @@
-# Solar 安装代理任务 (8 步)
+# Solar Agent Install / Deploy / Self-Check Protocol
 
-你是 **Solar 安装代理**。用户已将此提示词粘贴给你,你的任务是引导用户完成 Solar **L1 基础安装**。
+> For Claude, Codex, Cursor, Copilot, or any code agent installing Solar on behalf of a user.
+
+This document is the authoritative agent-facing install protocol. The agent must not improvise commands, silently skip failures, or claim success without running the checks below.
 
 ---
 
-## 协议
+## Scope
 
-- **L1 基础** = clone 仓库 → `./install.sh` → L1 自检 PASS → 启动 Claude Code 输入 `solar`
-- **L2 高级** (协调器/Sprint) = 仓库 `harness/` 发布源 → `./install.sh` 同步到 `~/.solar/harness/`, 见 Step 8
-- **L3 项目** (Solar-MAX) = 完全可选, 见 Step 8
+Solar installs in layers:
 
-**严格规则**:
-- 每步必须先报告 "目的 + 命令 + 预期输出", 等用户点头才执行
-- 任一步失败立刻停下, 报告失败的具体输出, **不要静默跳过**
-- 不要承诺剧本里没写的命令；L2 命令以 `~/.solar/bin/solar-harness` 和 `~/.solar/harness/` 为准
-- 全程不需要 root/sudo
+| Layer | Installed by `./install.sh` | Runtime location | Notes |
+|---|---:|---|---|
+| **L1 Solar Core** | yes | `~/.claude/` and `~/.solar/` | `CLAUDE.md`, rules, skills, agents, hooks, core files. |
+| **L2 Solar Harness** | yes, when `harness/` exists | `~/.solar/harness` and `~/.solar/bin/solar-harness` | Requirement compiler, sprint control plane, DAG runtime, queue/lease/dispatch/eval. |
+| **L2 optional packaged components** | yes, when present | `~/.solar/mempalace`, `~/.solar/codex-bridge` | Copied only if the repository contains those directories. |
+| **Third-party skills** | no | `~/.claude/skills/` | Optional. Use `SKILLS-INSTALL.md` and ask before installing optional repositories. |
+| **API keys** | no | local `.env` only | Optional. Copy `.env.template` to `.env`; never commit `.env`. |
 
 ---
 
-## 安装前置条件
-
-| 项 | 要求 |
-|---|---|
-| 系统 | macOS (Apple Silicon/Intel) 或 Linux (x86_64/ARM64) |
-| 工具 | git ≥ 2.0, bash ≥ 3.2, sqlite3 |
-| 网络 | 能访问 github.com |
-| 磁盘 | 约 100 MB |
-| 时间 | 3-5 分钟 |
+## Non-negotiable rules for the installing agent
 
-**不支持**: Windows (请用 WSL2)
+1. Before each command, report **purpose + command + expected output**.
+2. Do not use `sudo` or root.
+3. Stop on the first failure and show the exact output.
+4. Do not invent missing paths or commands.
+5. Do not write API keys; the user edits `.env` locally if needed.
+6. Do not install optional third-party skills without asking the user first.
+7. Completion requires L1 + L2 checks, not just clone success.
 
 ---
 
-# Step 1: 系统检测
+## Step 1 — System check
 
-## 目的
-确认操作系统和架构, 排除 Windows。
+Purpose: confirm a supported OS and basic shell environment.
 
-## 命令
 ```bash
 uname -sm
 ```
 
-## 预期输出
-四种之一:
-```
-Darwin arm64       # macOS Apple Silicon
-Darwin x86_64      # macOS Intel
-Linux x86_64       # Linux Intel
-Linux aarch64      # Linux ARM
-```
+Expected examples:
 
-## 失败处理
-- 输出含 `MINGW` / `CYGWIN` / `Windows` → 报告: "本剧本不支持原生 Windows, 请用 WSL2"
-- `uname` 不存在 → 报告: "极端情况, 请手动 `cat /etc/os-release` 确认 Linux 发行版"
+```text
+Darwin arm64
+Darwin x86_64
+Linux x86_64
+Linux aarch64
+```
 
-## 通过条件
-输出匹配上述 4 种之一 → 进入 Step 2
+Unsupported: native Windows. Use WSL2.
 
 ---
 
-# Step 2: 依赖检测
+## Step 2 — Required dependencies
 
-## 目的
-确认必需工具齐全, 缺啥装啥。
+Purpose: confirm the minimum tools needed by the installer.
 
-## 命令
 ```bash
-# 必需
 which git && git --version
 which bash && bash --version | head -1
 which sqlite3 && sqlite3 --version
 
-# 可选 (用于高级功能)
-which jq python3 tmux 2>/dev/null
+# Optional but useful for L2 Harness work
+which python3 jq tmux 2>/dev/null || true
 ```
 
-## 预期输出
-必需 3 项都返回路径 + 版本号。可选 3 项缺失也可继续。
-
-## 失败处理
-
-### git 缺失
-- macOS: `xcode-select --install`
-- Linux Debian/Ubuntu: `sudo apt install -y git`
-- Linux RHEL/Fedora: `sudo dnf install -y git`
-
-### bash 太老 (3.2.x, macOS 默认)
-非阻塞 — `install.sh` 兼容 bash 3.2。L2 高级模式才需要 bash 5.x:
-- macOS: `brew install bash`
-
-### sqlite3 缺失
-- macOS: 系统自带, 通常不会缺
-- Linux: `sudo apt install -y sqlite3` 或 `sudo dnf install -y sqlite`
-
-## 通过条件
-`git`, `bash`, `sqlite3` 三个 `which` 都返回路径 → 进入 Step 3
+Required to proceed: `git`, `bash`, and `sqlite3` must exist.
 
 ---
 
-# Step 3: Clone 仓库
+## Step 3 — Clone or update Solar
 
-## 目的
-拉取 `lisihao/Solar` 单仓库到 `~/Solar`。
+Purpose: get the public Solar repository.
 
-## 命令
 ```bash
-# 如果 ~/Solar 已存在,先决定是不是要覆盖
-ls -d ~/Solar 2>/dev/null && echo "已存在,先备份: mv ~/Solar ~/Solar-old-$(date +%Y%m%d)" || \
+if [ -d ~/Solar/.git ]; then
+  cd ~/Solar && git pull --ff-only
+else
   git clone https://github.com/lisihao/Solar.git ~/Solar
+fi
 ```
 
-## 预期输出
-```
-Cloning into '/Users/<you>/Solar'...
-remote: Enumerating objects: ...
-remote: Compressing objects: 100% (...)
-Receiving objects: 100% (...), X.XX MiB
-Resolving deltas: 100% (...)
-```
-
-## 失败处理
-
-### `Permission denied (publickey)`
-仓库当前是 PUBLIC, 不应该出现这个错。如果出现:
-- 改用 HTTPS: `git clone https://github.com/lisihao/Solar.git ~/Solar` (上面命令已是)
-
-### 网络超时
-- 中国大陆环境配代理: `git config --global http.proxy http://...`
-- 或者用镜像: 用户自行解决
-
-### `~/Solar` 已存在
-- 备份后重 clone: `mv ~/Solar ~/Solar-old-$(date +%Y%m%d) && git clone ...`
-- 或者更新: `cd ~/Solar && git pull`
+Check:
 
-## 通过条件
 ```bash
 test -f ~/Solar/install.sh && test -f ~/Solar/CLAUDE.md && echo OK
 ```
-输出 `OK` → 进入 Step 4
+
+Expected: `OK`.
 
 ---
 
-# Step 4: 环境变量 (可选)
+## Step 4 — Optional local env template
 
-## 目的
-配置 API keys。**不配也能装完, 只是部分功能不能用。**
+Purpose: create an optional local `.env` for API-backed features. Installation does not require keys.
 
-## 命令
 ```bash
-# 复制模板
-cp ~/Solar/.env.template ~/Solar/.env
-# 编辑 (用户自己选编辑器)
-echo "请编辑 ~/Solar/.env 填入下面任一个 API key (至少填一个):"
-echo "  - ANTHROPIC_API_KEY (https://console.anthropic.com/settings/keys)"
-echo "  - ZHIPU_API_KEY    (https://open.bigmodel.cn/usercenter/apikeys)"
-echo "  - DEEPSEEK_API_KEY (https://platform.deepseek.com/api_keys)"
+cd ~/Solar
+if [ -f .env.template ] && [ ! -f .env ]; then
+  cp .env.template .env
+  echo "Created .env from template. User may edit it later."
+else
+  echo "No env action needed."
+fi
 ```
 
-## 预期输出
-`.env` 文件已创建, 用户已编辑填入至少一个 key。
-
-## 失败处理
-- 用户暂时没有 API key → **跳过本步**, install.sh 不依赖 .env
-- 编辑器问题 → 用 `nano ~/Solar/.env` 或 VSCode
-
-## 通过条件
-- 跳过本步 OK → 进入 Step 5
-- 或 `grep -E '^[A-Z_]+_API_KEY=.+' ~/Solar/.env` 至少一行 → 进入 Step 5
+Do not fill in values yourself unless the user explicitly provides them in the local machine context.
 
 ---
 
-# Step 5: 跑 install.sh
+## Step 5 — Run installer
 
-## 目的
-执行核心安装: 备份现有 `~/.claude/` → 复制仓库内容到 `~/.claude/` → 创建 `~/.solar/`。
+Purpose: install L1 Solar Core and sync L2 Solar Harness runtime.
 
-## 命令
 ```bash
-cd ~/Solar && ./install.sh
-```
-
-## 预期输出
+cd ~/Solar
+./install.sh
 ```
-🚀 Solar 一键部署 (L1 基础安装)
-================================
-
-📁 创建 /Users/<you>/.claude ...    (或: 💾 备份现有配置到 ...)
-📋 复制 CLAUDE.md ...
-📋 复制 rules ...
-📋 复制 skills ...
-📋 复制 agents ...
-📋 复制 hooks ...
-📋 复制 core ...
 
-📂 创建 /Users/<you>/.solar ...
-🗄️  初始化数据库...   (或: ℹ️  无 schema.sql, 跳过 db 初始化)
+Expected high-level output:
 
+```text
+🚀 Solar 一键部署 (L1 + L2 全栈)
+...
 🔍 安装自检
-===========
-  ✅ CLAUDE.md 已就位
-  ✅ CLAUDE.md 含 Solar 标识
-  ✅ ~/.claude/rules/ 已就位
-  ✅ ~/.claude/skills/ 已就位
-  ✅ ~/.claude/agents/ 已就位
-  ✅ ~/.solar/ 目录已建
-
-✅ L1 基础安装完成 (6/6 通过)
+  ✅ [L1] ...
+  ✅ [L2] ...
+✅ Solar L1 + L2 安装完成 (14/14 通过)
 ```
 
-## 失败处理
-
-### `set -e` 中途退出
-- 看 last 5 行输出, 一般是某个 cp 失败
-- 检查 `ls -la ~/Solar/{rules,skills,agents,hooks,core}` 仓库目录是否完整
-
-### 自检 FAIL
-脚本自身已经给出排查命令, 按提示执行。
-
-## 通过条件
-脚本退出码 0 + 末尾输出 `✅ L1 基础安装完成 (6/6 通过)` → 进入 Step 6
+If any check fails, stop and report the failing line.
 
 ---
 
-# Step 6: 二次验收
+## Step 6 — Independent L1/L2 self-check
 
-## 目的
-独立确认安装产物 (不信脚本自检, 用户/AI 自查)。
+Purpose: verify install artifacts without trusting installer logs only.
 
-## 命令
 ```bash
-ls -la ~/.claude/CLAUDE.md ~/.claude/rules ~/.claude/skills ~/.claude/agents ~/.solar/ && \
-  echo "" && echo "=== L1 验收 ===" && \
-  echo "CLAUDE.md 大小: $(wc -c < ~/.claude/CLAUDE.md) bytes" && \
-  echo "rules 数量:    $(ls ~/.claude/rules/ 2>/dev/null | wc -l)" && \
-  echo "skills 数量:   $(ls ~/.claude/skills/ 2>/dev/null | wc -l)" && \
-  echo "agents 数量:   $(ls ~/.claude/agents/ 2>/dev/null | wc -l)" && \
-  echo "" && \
-  echo "✅ Solar L1 验收通过"
-```
-
-## 预期输出
+test -f ~/.claude/CLAUDE.md && \
+test -d ~/.claude/rules && \
+test -d ~/.claude/skills && \
+test -d ~/.claude/agents && \
+test -d ~/.solar && \
+test -f ~/.solar/harness/coordinator.sh && \
+test -x ~/.solar/harness/solar-harness.sh && \
+test -L ~/.solar/bin/solar-harness && \
+echo "Solar L1+L2 filesystem check PASS"
 ```
--rw-r--r-- ... CLAUDE.md
-drwxr-xr-x ... rules
-drwxr-xr-x ... skills
-...
 
-=== L1 验收 ===
-CLAUDE.md 大小: <数千> bytes
-rules 数量:    <若干>
-skills 数量:   <若干>
-agents 数量:   <若干>
+Expected:
 
-✅ Solar L1 验收通过
+```text
+Solar L1+L2 filesystem check PASS
 ```
 
-## 失败处理
-- 任何 `ls` 报 No such file → 重跑 Step 5, 检查 `set -e` 错误
-- CLAUDE.md 大小 = 0 → cp 失败, 回 Step 5
-
-## 通过条件
-所有 ls 都成功 + 5 个数量都 > 0 → 进入 Step 7
-
 ---
 
-# Step 7: Troubleshoot (常见问题快速诊断)
-
-| 症状 | 可能原因 | 解决 |
-|------|---------|------|
-| `bash: ./install.sh: Permission denied` | 脚本无可执行权限 | `chmod +x ~/Solar/install.sh` |
-| 自检 `❌ ~/.claude/rules/ 已就位` | 仓库 rules 目录空 | `cd ~/Solar && git pull` 拉最新 |
-| 自检 `❌ CLAUDE.md 含 Solar 标识` | CLAUDE.md 内容不对 | 检查 `head ~/.claude/CLAUDE.md` |
-| Claude Code 输入 `solar` 没反应 | CLAUDE.md 没生效 | 重启 Claude Code |
-| `~/.solar/solar.db` 不存在 | 缺 schema.sql | 非阻塞, Solar 启动时会自建 |
-| 想完全卸载 | 清理产物 | `rm -rf ~/.claude/CLAUDE.md ~/.claude/rules ~/.claude/skills ~/.claude/agents ~/.claude/hooks ~/.claude/core ~/.solar/` (注意备份) |
+## Step 7 — Harness command self-check
 
-任何上面没列的问题, 提交 issue: https://github.com/lisihao/Solar/issues
+Purpose: confirm the Harness CLI is usable.
 
-## 通过条件
-没遇到问题, 或者用 troubleshoot 表已解决 → 进入 Step 8
+```bash
+~/.solar/bin/solar-harness help >/tmp/solar-harness-help.txt
+cat /tmp/solar-harness-help.txt | head -40
+```
 
----
+Expected: help text that includes Harness commands. If this fails, inspect:
 
-# Step 8: 高级模式 (可选, 跳过也能正常用)
+```bash
+ls -la ~/.solar/bin/solar-harness ~/.solar/harness/solar-harness.sh
+bash -n ~/.solar/harness/solar-harness.sh
+```
 
-L1 安装完成已经能用 Solar 大部分功能 (触发词、agents、skills、rules)。仓库现在同时发布 L2 Harness:
+---
 
-## L2 高级模式: Solar Harness (协调器 / Sprint / 牛马链路)
+## Step 8 — Runtime re-sync check
 
-- **是什么**: bash + python 协调系统, 实现"规划者→建设者→审判官"多 pane 自动派发
-- **能做什么**: Sprint 状态机, verify cmd 自动跑, 牛马 (GLM/Gemini/DeepSeek) 调用
-- **发布目录**: `~/Solar/harness/`，来自 GitHub 仓库 `lisihao/Solar`
-- **运行目录**: `~/.solar/harness/`
-- **安装方式**: `./install.sh` 会自动运行 `scripts/sync-harness-runtime.sh`，把 `~/Solar/harness/` 同步到 `~/.solar/harness/`，并创建 `~/.solar/bin/solar-harness`
-- **手动重同步**:
+Purpose: confirm the repo-published Harness can be synced into the runtime directory.
 
 ```bash
 cd ~/Solar
 ./scripts/sync-harness-runtime.sh
+~/.solar/bin/solar-harness help >/tmp/solar-harness-help-after-sync.txt
+grep -E "graph|context|help|start" /tmp/solar-harness-help-after-sync.txt | head -20 || true
 ```
 
-## L3 项目模式: Solar-MAX
+Expected: sync completes and `solar-harness help` still works.
+
+---
 
-- **是什么**: 独立 GitHub 仓库 `lisihao/Solar-MAX`
-- **能做什么**: 五阶段流程 + Gate 模式 + 抗失忆 STATE.md/DECISIONS.md 三文件架构
-- **当前状态**: 私有仓库, 只对监护人本人可见
-- **如何获得**: 不对外开放
+## Step 9 — Optional skill expansion
 
-## L1 用户该跑啥
+Purpose: install third-party skills only if the user asks.
 
-只装 L1 的话:
-```bash
-# 启动 Claude Code, 然后输入下面任一触发词
-solar              # 启动 Solar 主脑
-我要开发           # 进入开发模式
-我要研究 X         # 进入研究模式
-@Coder 优化函数    # 直接调 Coder agent
-/commit            # 调 Skill
+Default behavior: do not install third-party skill packs.
+
+If the user asks for skill expansion, follow:
+
+```text
+SKILLS-INSTALL.md
 ```
 
+Important: Solar's base install already copies repository-bundled skills from `skills/` into `~/.claude/skills/`. Third-party skills are enhancements, not required for the base system.
+
 ---
 
-## 完成验收
+## Step 10 — Final report to the user
 
-到这里 L1 已就位。最终一条 sanity check:
+Report in this format:
 
-```bash
-# 仓库 + 安装产物 + 数据库
-test -d ~/Solar && \
-test -f ~/.claude/CLAUDE.md && \
-test -d ~/.claude/rules && \
-test -d ~/.claude/skills && \
-test -d ~/.claude/agents && \
-test -d ~/.solar && \
-echo "🎉 Solar L1 全链路 PASS"
+```text
+Solar install report
+- Repo: ~/Solar
+- L1 Core: PASS/FAIL
+- L2 Harness: PASS/FAIL
+- Harness CLI: PASS/FAIL
+- Runtime sync: PASS/FAIL
+- Optional .env: created/skipped
+- Optional third-party skills: installed/skipped
+- Failures: none / exact failing command + output
+- Next command for user: start Claude Code and type `solar`, or run `~/.solar/bin/solar-harness start`
 ```
 
-输出 `🎉 Solar L1 全链路 PASS` → 完整安装成功。
-
 ---
 
-## 全步通过条件汇总
+## Troubleshooting quick table
 
-| Step | 通过判定 |
-|------|---------|
-| 1 | `uname -sm` 输出匹配 4 种系统之一 |
-| 2 | `git`, `bash`, `sqlite3` 都 `which` 命中 |
-| 3 | `~/Solar/install.sh` + `~/Solar/CLAUDE.md` 同时存在 |
-| 4 | `.env` 已创建 (或用户选择跳过) |
-| 5 | `install.sh` 退出码 0 + L1/L2 自检通过 |
-| 6 | `~/.claude/{CLAUDE.md,rules,skills,agents}` + `~/.solar/` 都存在 |
-| 7 | Troubleshoot 表查不到的问题已开 issue |
-| 8 | 用户决定是否进高级模式 (L1 已可用) |
+| Symptom | Check | Likely fix |
+|---|---|---|
+| `./install.sh: Permission denied` | `ls -l ~/Solar/install.sh` | `chmod +x ~/Solar/install.sh` |
+| `sqlite3` missing | `which sqlite3` | Install sqlite3 through system package manager. |
+| Harness symlink missing | `ls -la ~/.solar/bin/solar-harness` | Re-run `cd ~/Solar && ./scripts/sync-harness-runtime.sh`. |
+| `solar-harness help` fails | `bash -n ~/.solar/harness/solar-harness.sh` | Report syntax/output; do not guess. |
+| Optional skills missing | `ls ~/.claude/skills` | Use `SKILLS-INSTALL.md` only after user approval. |
 
 ---
 
-## 给 AI agent 的元规则
+## Completion criteria
 
-执行本剧本时:
-1. **不擅自跳步** — 上一步未通过不进下一步
-2. **不假报成功** — 命令 exit code 非 0 必须报告
-3. **不静默修复** — 失败处理之前先告诉用户错误是什么
-4. **不假装路径** — L2 Harness 的发布源是 `~/Solar/harness`, 运行源是 `~/.solar/harness`
-5. **不超出范围** — 用户没要求 L2/L3, 不主动安装
+Installation is complete only when these are true:
+
+```bash
+test -f ~/.claude/CLAUDE.md
+test -d ~/.claude/skills
+test -d ~/.solar/harness
+test -x ~/.solar/harness/solar-harness.sh
+test -L ~/.solar/bin/solar-harness
+~/.solar/bin/solar-harness help >/dev/null
+```

From cebef5ab80929ad8771436720da72560e146ed33 Mon Sep 17 00:00:00 2001
From: lisihao <lisihao@gmail.com>
Date: Fri, 5 Jun 2026 17:54:47 -0400
Subject: [PATCH 4/5] Clarify optional third-party skill installation

---
 SKILLS-INSTALL.md | 249 +++++++++++++++++++++++++---------------------
 1 file changed, 134 insertions(+), 115 deletions(-)

diff --git a/SKILLS-INSTALL.md b/SKILLS-INSTALL.md
index dc3c50274..6d44413fc 100644
--- a/SKILLS-INSTALL.md
+++ b/SKILLS-INSTALL.md
@@ -1,193 +1,212 @@
-# SKILLS-INSTALL — 给 AI Agent 看的 Skills 安装剧本
+# Solar Skills Install Protocol
 
-> 如果你是用户的 AI agent (Claude / Codex / Cursor / Copilot 等), 用户把这个文档贴给你, 你的任务是按下面剧本帮用户在他机器上**自动**安装 Solar 系统所需的 Skills。
+> For AI agents installing optional third-party skills after the base Solar install.
+
+Solar does not require third-party skills to complete the base install. `./install.sh` copies repository-bundled skills from `skills/` into `~/.claude/skills/`. This document is only for optional skill expansion.
 
 ---
 
-## 协议
+## Rules for the installing agent
 
-- **Solar 仓库自身只打包 12 个 Solar 自有 skill** (`~/Solar/skills/`), `install.sh` 已经把它们装到 `~/.claude/skills/`
-- **真正完整体验需要 1500+ skills**, 来自 Anthropic 官方 + 第三方 + Karpathy 编程技能等
-- **本剧本目的**: 让 AI agent 自动 clone 这些 skill 仓库, 不需要用户手动 git
-- **执行边界**: 全程不需要 root/sudo, 只在 `~/.claude/skills/` 下操作
+1. Do not install optional third-party repositories without asking the user first.
+2. Do not delete or overwrite the user's existing skills.
+3. Do not claim success without checking the installed paths.
+4. Do not use `sudo` or root.
+5. If a git clone fails, report the error and ask whether to retry with a proxy/mirror.
+6. Keep all installations under `~/.claude/skills/` unless the user explicitly asks otherwise.
 
 ---
 
-## 安装前检查
-
-执行前先确认:
+## Preflight
 
 ```bash
-# Solar L1 + L2 已装
-test -f ~/.claude/CLAUDE.md && echo "✅ Solar 已装" || echo "❌ 先跑 ~/Solar/install.sh"
+# Solar base install should already be present
+test -f ~/.claude/CLAUDE.md && echo "Solar core present" || echo "Run: cd ~/Solar && ./install.sh"
+
+test -d ~/.claude/skills && echo "Skills directory present" || mkdir -p ~/.claude/skills
 
-# git 可用
 which git && git --version | head -1
 ```
 
-如果 Solar 没装, 先停下让用户跑 `cd ~/Solar && ./install.sh`。
+Stop if `git` is missing.
 
 ---
 
-## Step 1: Karpathy 编程技能集 (~210 个 skill, 强烈推荐)
+## What is already installed by Solar
 
-**来源**: `forrestchang/andrej-karpathy-skills` — Karpathy 编码哲学 + 工具技能合集
-**为什么需要**: Solar `CLAUDE.md` 里的 "Karpathy 编码四原则" 引用这些技能
+Base install copies the repository's bundled skills:
 
 ```bash
-# 检查是否已装
-if [ -d ~/.claude/skills/python-pro ] || [ -d ~/.claude/skills/code-reviewer ]; then
-    echo "✅ Karpathy skills 似乎已装"
+cd ~/Solar
+find skills -maxdepth 2 -type f | head
+ls ~/.claude/skills | head
+```
+
+The exact number of bundled skills can change with the repository. Do not hard-code a count in user reports.
+
+---
+
+## Optional Pack A — Karpathy-style programming skills
+
+Ask first:
+
+```text
+Do you want to install the optional Karpathy-style programming skill pack into ~/.claude/skills/?
+```
+
+Install only after approval:
+
+```bash
+mkdir -p ~/.claude/skills
+cd ~/.claude/skills
+if [ -d .karpathy-tmp ]; then
+  rm -rf .karpathy-tmp
+fi
+git clone --depth=1 https://github.com/forrestchang/andrej-karpathy-skills.git .karpathy-tmp
+if [ -d .karpathy-tmp/skills ]; then
+  cp -Rn .karpathy-tmp/skills/* ~/.claude/skills/
 else
-    cd ~/.claude/skills
-    # 临时 clone 到子目录, 然后展开
-    git clone --depth=1 https://github.com/forrestchang/andrej-karpathy-skills.git .karpathy-tmp
-    cp -r .karpathy-tmp/skills/* ~/.claude/skills/ 2>/dev/null || cp -r .karpathy-tmp/* ~/.claude/skills/
-    rm -rf .karpathy-tmp
-    echo "✅ Karpathy skills 装好"
+  cp -Rn .karpathy-tmp/* ~/.claude/skills/
 fi
+rm -rf .karpathy-tmp
 ```
 
-**预期结果**: `~/.claude/skills/` 增加 ~200 个 skill 目录 (python-pro / code-reviewer / debugger / 等)
+Check:
 
-**失败处理**:
-- `git clone` 失败 → 配代理或换 SSH (`git@github.com:forrestchang/andrej-karpathy-skills.git`)
-- 用户在中国大陆 → 试 `https://gitclone.com/github.com/forrestchang/andrej-karpathy-skills.git` 镜像
-
-**通过条件**: `ls ~/.claude/skills/ | wc -l` 输出 ≥ 50 → 进入 Step 2
+```bash
+ls ~/.claude/skills | grep -E "python|review|debug|test" | head || true
+```
 
 ---
 
-## Step 2: Anthropic 官方 Claude Code Skills (~50 个)
+## Optional Pack B — Claude Code built-in skills
 
-**来源**: Anthropic Claude Code 自带 — 通常用户装 Claude Code 时已经在 `~/.claude/skills/` 或 `/Applications/Claude.app/Contents/Resources/skills/` 里
-**为什么需要**: `gstack/Superpowers` 触发词链路依赖
+Claude Code may already ship its own skills. Link/copy only after user approval.
 
 ```bash
-# 检查 Claude Code 是否已装
-which claude || open -a "Claude" 2>/dev/null
-
-# 看 Claude Code 自带 skills 位置
-for path in /Applications/Claude.app/Contents/Resources/skills \
-            ~/Library/Application\ Support/Claude/skills \
-            ~/.config/claude/skills; do
-    if [ -d "$path" ]; then
-        echo "找到 Claude Code 自带 skills: $path"
-        # 软链或复制 (建议软链, 跟 Claude Code 升级同步)
-        ln -sf "$path"/* ~/.claude/skills/ 2>/dev/null || cp -r "$path"/* ~/.claude/skills/
-    fi
+for path in \
+  /Applications/Claude.app/Contents/Resources/skills \
+  "$HOME/Library/Application Support/Claude/skills" \
+  "$HOME/.config/claude/skills"; do
+  if [ -d "$path" ]; then
+    echo "Found Claude skills: $path"
+  fi
 done
 ```
 
-**通过条件**: `ls ~/.claude/skills/ | grep -E "^(brainstorming|writing-plans|systematic-debugging)$"` 至少命中 1 个
+If the user wants them installed:
+
+```bash
+mkdir -p ~/.claude/skills
+for path in \
+  /Applications/Claude.app/Contents/Resources/skills \
+  "$HOME/Library/Application Support/Claude/skills" \
+  "$HOME/.config/claude/skills"; do
+  if [ -d "$path" ]; then
+    cp -Rn "$path"/* ~/.claude/skills/ 2>/dev/null || true
+  fi
+done
+```
 
 ---
 
-## Step 3: gstack 工具集 (网页浏览/QA/部署 等)
+## Optional Pack C — gstack setup
 
-**来源**: gstack 是 Solar 自有的扩展, 通过 `~/.claude/skills/gstack/setup` 安装
-**为什么需要**: Solar `CLAUDE.md` 的"gstack (核心模块)"章节, 触发词 `/browse` `/review` `/ship` 等都依赖它
+If `~/.claude/skills/gstack/setup` exists, it can be initialized after user approval:
 
 ```bash
-# Solar L1 安装时 gstack 子目录已经在 ~/.claude/skills/gstack/, 只需跑 setup
 if [ -f ~/.claude/skills/gstack/setup ]; then
-    cd ~/.claude/skills/gstack && ./setup
-    echo "✅ gstack 已 setup"
+  cd ~/.claude/skills/gstack
+  ./setup
+  echo "gstack setup complete"
 else
-    echo "⚠️  ~/.claude/skills/gstack/ 不存在, 先跑 ~/Solar/install.sh"
+  echo "gstack setup script not found; skip"
 fi
 ```
 
-**通过条件**: `~/.claude/skills/gstack/bin/$B` 或 `~/.solar/bin/$B` 可执行
+Check:
+
+```bash
+find ~/.claude/skills/gstack -maxdepth 3 -type f | head 2>/dev/null || true
+```
 
 ---
 
-## Step 4: Skill Retriever MCP (按场景动态加载 Skill)
+## Optional Pack D — Skill retriever MCP
 
-**来源**: Solar `core/mcp-servers/skill-retriever/` (已随 install.sh 装到 `~/.claude/core/`)
-**为什么需要**: Solar `CLAUDE.md` 的"技能分层检索 (MCP v2.0)"章节, 让 Claude 按用户意图动态拉 skill
+This is optional and depends on the user's Claude Code MCP setup.
 
 ```bash
-# 注册到 Claude Code MCP
 SKILL_MCP=$(find ~/.claude/core ~/.claude/mcp-servers -name "*skill-retriever*" -type d 2>/dev/null | head -1)
 if [ -n "$SKILL_MCP" ]; then
-    cd "$SKILL_MCP"
-    [ -f package.json ] && npm install --silent
-    [ -f main.ts ] && claude mcp add skill-retriever -- node $SKILL_MCP/main.js
-    echo "✅ skill-retriever MCP 已注册"
+  echo "Found skill retriever candidate: $SKILL_MCP"
+else
+  echo "No skill retriever MCP found; skip"
 fi
 ```
 
-**通过条件**: `claude mcp list | grep skill-retriever | grep -v Failed` 命中
-
----
-
-## Step 5: 第三方 Skills (按需选装)
-
-下面是用户**可能**想要的额外 skill 仓库, **AI 应该问用户哪些要装** 不要全装:
-
-| 仓库 | 内容 | 何时装 |
-|------|------|-------|
-| `anthropics/claude-cookbooks` | API 用法示例 | 用户开发 Claude API 时 |
-| `langchain-ai/langgraph-skills` | LangGraph 工作流 skill | 用户做 agent 编排时 |
-| `mlflow/mlflow-skills` | ML 实验跟踪 | 用户搞 ML 时 |
+If the user approves registration and `claude` CLI is available:
 
 ```bash
-# 询问用户后再装
-read -p "要装 LangGraph skills 吗? [y/N] " yn
-if [[ "$yn" =~ ^[Yy]$ ]]; then
-    git clone --depth=1 https://github.com/langchain-ai/langgraph-skills.git ~/.claude/skills/langgraph 2>&1
+if [ -n "$SKILL_MCP" ] && command -v claude >/dev/null 2>&1; then
+  cd "$SKILL_MCP"
+  [ -f package.json ] && npm install --silent
+  if [ -f main.js ]; then
+    claude mcp add skill-retriever -- node "$SKILL_MCP/main.js"
+  elif [ -f main.ts ]; then
+    echo "main.ts found; compile/register manually according to this MCP package"
+  fi
 fi
 ```
 
 ---
 
-## Step 6: 验收
+## Optional third-party repositories
 
-```bash
-echo "=== Solar Skills 安装结果 ==="
-TOTAL=$(ls ~/.claude/skills/ 2>/dev/null | wc -l | tr -d ' ')
-echo "总 skill 目录: $TOTAL"
+These should be installed only when the user explicitly asks for that domain:
 
-# 关键 skill 抽检
-for s in python-pro code-reviewer brainstorming writing-plans gstack; do
-    [ -d ~/.claude/skills/$s ] && echo "  ✅ $s" || echo "  ❌ $s 缺失"
-done
+| Domain | Example source | When to install |
+|---|---|---|
+| Claude API examples | `anthropics/claude-cookbooks` | User is developing Claude API apps. |
+| Agent orchestration | LangGraph-related skills if available | User is building LangGraph/agent workflow demos. |
+| ML experiments | MLflow-related materials if available | User is doing ML experiment tracking. |
 
-echo ""
-if [ "$TOTAL" -ge 50 ]; then
-    echo "✅ Skills 安装完成 (≥ 50 个)"
-    echo "下一步: 启动 Claude Code, 输入 'solar' 看 Solar 启动宣告"
-else
-    echo "⚠️ 数量偏少 ($TOTAL < 50), 至少 Step 1 (Karpathy) 应该装"
-fi
-```
+Do not promise a fixed repository is maintained unless you have verified it at install time.
 
 ---
 
-## 给 AI agent 的元规则
-
-执行本剧本时:
+## Verification
 
-1. **不擅自装第 5 步可选 skills** — 必须先问用户
-2. **不假装成功** — 每步检查 exit code, 失败明确报告
-3. **不删用户已有 skill** — 用 `cp -n` 不覆盖, 或软链
-4. **遇到 git 网络问题** — 提示用户配代理或换镜像, 不卡死
-5. **遇到 Claude Code 未装** — 停下提示用户先装 Claude Code: https://claude.ai/code
+```bash
+echo "=== Solar Skills Summary ==="
+test -d ~/.claude/skills && echo "skills_dir=ok" || echo "skills_dir=missing"
+TOTAL=$(find ~/.claude/skills -maxdepth 1 -mindepth 1 2>/dev/null | wc -l | tr -d ' ')
+echo "skill_entries=$TOTAL"
 
----
+for s in gstack python-pro code-reviewer brainstorming writing-plans systematic-debugging; do
+  [ -e ~/.claude/skills/$s ] && echo "present: $s" || true
+done
+```
 
-## 可选高级:让用户的 AI 自动维护 skills
+A small number of skills is not a Solar install failure. Third-party skills are optional enhancements.
 
-监护人级用户 (有 GitHub PAT) 可以让 AI agent 跑后台脚本周期性 `git pull` 更新 skills:
+---
 
-```bash
-# crontab 每周日凌晨 3 点更新 Karpathy skills
-(crontab -l 2>/dev/null; echo "0 3 * * 0 cd ~/.claude/skills/.karpathy-tmp && git pull --quiet") | crontab -
+## Final report format
+
+```text
+Skills install report
+- Base Solar skills: present/missing
+- Optional Karpathy pack: installed/skipped/failed
+- Optional Claude built-ins: installed/skipped/failed
+- Optional gstack setup: done/skipped/failed
+- Optional MCP registration: done/skipped/failed
+- Total skill entries: N
+- Failures: none / exact command + output
 ```
 
-**默认不设**, 用户主动要才配置。
-
 ---
 
-**底线**: 本剧本帮 AI 装的 skills 是**增强**Solar 体验, 不是必需。即使全部 skip 失败, Solar L1 + L2 (CLAUDE.md + harness + mempalace) 已经能跑大部分核心功能。
+## Bottom line
+
+Solar's base system should install and run without third-party skill packs. Use this protocol only to expand the available skill surface after the user approves the extra repositories or MCP registrations.

From 30c6fb66f00d0a9ac153b77aafcae5c0772acd37 Mon Sep 17 00:00:00 2001
From: lisihao <lisihao@gmail.com>
Date: Fri, 5 Jun 2026 17:55:31 -0400
Subject: [PATCH 5/5] Clarify optional skill packs in installer output

---
 install.sh | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/install.sh b/install.sh
index a1799617a..5b552b6fe 100755
--- a/install.sh
+++ b/install.sh
@@ -17,7 +17,7 @@
 #   - 不 git clone 别的仓库
 #   - 不写入 API keys (用户自己编辑 .env)
 #   - 不跑 Python 依赖 (mempalace 需 chromadb/mcp/sentence-transformers, 见 SKILLS-INSTALL.md)
-#   - 不安装 1500+ Skills (Anthropic Claude Code 自带 + 第三方仓库, 见 SKILLS-INSTALL.md 让 AI 装)
+#   - 不安装第三方 skill packs；仓库内置 skills 会复制，第三方增强包见 SKILLS-INSTALL.md
 
 set -e
 
@@ -159,13 +159,13 @@ if [ "$FAIL" -eq 0 ]; then
     echo ""
     echo "📝 下一步:"
     echo "  1. (可选) 配置 API keys: cp $SOLAR_DIR/.env.template $SOLAR_DIR/.env"
-    echo "     编辑填入: ANTHROPIC_API_KEY / ZHIPU_API_KEY / DEEPSEEK_API_KEY"
+    echo "     编辑填入需要的 API key；安装本身不依赖 API key"
     echo ""
     echo "  2. (可选) Python 依赖 (MemPalace 需要):"
     echo "     python3.11 -m pip install --user chromadb sentence-transformers langdetect mcp pyyaml"
     echo ""
-    echo "  3. (推荐) 让你的 AI 装 Skills 增强:"
-    echo "     把 $SOLAR_DIR/SKILLS-INSTALL.md 给 AI agent (Claude/Cursor 等), 它会自动 clone 第三方 skills"
+    echo "  3. (可选) Skills 增强:"
+    echo "     让 AI agent 按 $SOLAR_DIR/SKILLS-INSTALL.md 安装第三方 skill packs；必须先征得用户同意"
     echo ""
     echo "  4. 启动 Claude Code, 输入 'solar' 看启动宣告"
     echo ""