@binarycheater/research-sidecar 0.1.3 → 0.1.4

package/README.md

@@ -2,20 +2,6 @@
 
 English | [中文](README.zh.md)
 
-Research Sidecar is a local web app and npm CLI for graph-backed research work. It is designed to run beside Codex: Codex can create or update research notes, while Research Sidecar gives you a readable graph, document preview, and explicit review surface for judging the work.
-
-The important rule is simple: **the directory where you run `research-sidecar` is the workspace**. The app reads and writes only inside that workspace, and stores private local state under `.side/`.
-
-## Why It Exists
-
-Research work often starts from vague questions and evolves through experiments, reports, partial conclusions, and revisions. A linear folder of Markdown files becomes hard to inspect. Research Sidecar separates the problem into three layers:
-
-- `graph.yaml`: the structural map of questions, methods, claims, evidence, tasks, and outputs.
-- Markdown/HTML files: the detailed reasoning, experiment reports, tables, formulas, and drafts.
-- `.side/`: local private app state, selected graph, sessions, and provider config.
-
-This gives Codex a concrete structure to maintain while giving the human reader a compact interface for understanding what happened.
-
 ## Install
 
 Global install:
@@ -40,6 +26,20 @@ Open:
 http://localhost:4317
 ```
 
+Research Sidecar is a local web app and npm CLI for graph-backed research work. It is designed to run beside Codex: Codex can create or update research notes, while Research Sidecar gives you a readable graph, document preview, and explicit review surface for judging the work.
+
+The important rule is simple: **the directory where you run `research-sidecar` is the workspace**. The app reads and writes only inside that workspace, and stores private local state under `.side/`.
+
+## Why It Exists
+
+Research work often starts from vague questions and evolves through experiments, reports, partial conclusions, and revisions. A linear folder of Markdown files becomes hard to inspect. Research Sidecar separates the problem into three layers:
+
+- `graph.yaml`: the structural map of questions, methods, claims, evidence, tasks, and outputs.
+- Markdown/HTML files: the detailed reasoning, experiment reports, tables, formulas, and drafts.
+- `.side/`: local private app state, selected graph, sessions, and provider config.
+
+This gives Codex a concrete structure to maintain while giving the human reader a compact interface for understanding what happened.
+
 ## CLI Commands
 
 Start the app for the current directory:
@@ -194,7 +194,8 @@ research-sidecar install-skills
 This copies bundled skills into:
 
 ```txt
-<workspace>/skills/
+<workspace>/.agents/skills/
+<workspace>/.claude/skills/
 ```
 
 Existing skill directories are skipped by default. Use `--force` when you intentionally want to overwrite install-managed skills.

package/README.zh.md

@@ -2,20 +2,6 @@
 
 [English](README.md) | 中文
 
-Research Sidecar 是一个用于 graph-backed research workflow 的本地 Web 应用和 npm CLI。它适合和 Codex 一起工作：Codex 可以生成、澄清、修改研究笔记；Research Sidecar 提供可读的研究图、文档预览和明确的 review 界面，帮助人判断这些工作是否合理。
-
-最重要的规则是：**你在哪里运行 `research-sidecar`，哪里就是 workspace**。应用只在这个 workspace 内读写文件，并把私有本地状态保存在 `.side/`。
-
-## 为什么需要它
-
-研究工作通常从模糊问题开始，逐步形成实验、报告、局部结论和修订。如果所有内容只是散落在 Markdown 文件里，人很难快速理解当前状态。Research Sidecar 把研究拆成三层：
-
-- `graph.yaml`：研究结构图，包括问题、方法、claim、证据、任务和输出。
-- Markdown/HTML 文件：详细推理、实验报告、表格、公式和草稿。
-- `.side/`：本地私有状态，包括当前选择的 graph、session 和 provider 配置。
-
-这样 Codex 有一个明确结构可以维护，人也能通过 UI 快速理解研究进展。
-
 ## 安装
 
 全局安装：
@@ -40,6 +26,20 @@ npx research-sidecar
 http://localhost:4317
 ```
 
+Research Sidecar 是一个用于 graph-backed research workflow 的本地 Web 应用和 npm CLI。它适合和 Codex 一起工作：Codex 可以生成、澄清、修改研究笔记；Research Sidecar 提供可读的研究图、文档预览和明确的 review 界面，帮助人判断这些工作是否合理。
+
+最重要的规则是：**你在哪里运行 `research-sidecar`，哪里就是 workspace**。应用只在这个 workspace 内读写文件，并把私有本地状态保存在 `.side/`。
+
+## 为什么需要它
+
+研究工作通常从模糊问题开始，逐步形成实验、报告、局部结论和修订。如果所有内容只是散落在 Markdown 文件里，人很难快速理解当前状态。Research Sidecar 把研究拆成三层：
+
+- `graph.yaml`：研究结构图，包括问题、方法、claim、证据、任务和输出。
+- Markdown/HTML 文件：详细推理、实验报告、表格、公式和草稿。
+- `.side/`：本地私有状态，包括当前选择的 graph、session 和 provider 配置。
+
+这样 Codex 有一个明确结构可以维护，人也能通过 UI 快速理解研究进展。
+
 ## CLI 命令
 
 把当前目录作为 workspace 启动：
@@ -194,7 +194,8 @@ research-sidecar install-skills
 这会把 bundled skills 复制到：
 
 ```txt
-<workspace>/skills/
+<workspace>/.agents/skills/
+<workspace>/.claude/skills/
 ```
 
 默认不会覆盖已有 skill 目录。如果你明确想覆盖 install-managed skills，使用 `--force`。

package/dist-server/lib/workspaceInstall.js

@@ -2,6 +2,7 @@ import { access, cp, mkdir, readdir, readFile, writeFile } from "node:fs/promise
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const DEFAULT_ALLOWED_WRITE_EXTENSIONS = [".md", ".markdown", ".html", ".htm", ".yaml", ".yml"];
+const SKILL_INSTALL_ROOTS = [".agents/skills", ".claude/skills"];
 export async function installWorkspaceScaffold(workspaceRoot, options = {}) {
     const root = resolve(workspaceRoot);
     const graphManifestPath = normalizeWorkspacePath(options.graphManifestPath || "research/graph.yaml");
@@ -28,21 +29,32 @@ export async function installBundledSkills(workspaceRoot, options = {}) {
     if (!sourceRoot)
         return { sourceRoot: null, installed: [], skipped: [] };
     const entries = await readdir(sourceRoot, { withFileTypes: true });
-    const targetRoot = join(resolve(workspaceRoot), "skills");
+    const root = resolve(workspaceRoot);
+    const targetRoots = SKILL_INSTALL_ROOTS.map((target) => join(root, target));
     const installed = [];
     const skipped = [];
-    await mkdir(targetRoot, { recursive: true });
+    await Promise.all(targetRoots.map((targetRoot) => mkdir(targetRoot, { recursive: true })));
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
         const source = join(sourceRoot, entry.name);
-        const target = join(targetRoot, entry.name);
-        if (!options.force && (await exists(target))) {
+        let copied = false;
+        let alreadyPresent = false;
+        for (const targetRoot of targetRoots) {
+            const target = join(targetRoot, entry.name);
+            if (!options.force && (await exists(target))) {
+                alreadyPresent = true;
+                continue;
+            }
+            await cp(source, target, { recursive: true, force: true });
+            copied = true;
+        }
+        if (copied) {
+            installed.push(entry.name);
+        }
+        if (alreadyPresent) {
             skipped.push(entry.name);
-            continue;
         }
-        await cp(source, target, { recursive: true, force: true });
-        installed.push(entry.name);
     }
     return { sourceRoot, installed, skipped };
 }

package/dist-server/lib/workspaceMeta.js

@@ -105,7 +105,7 @@ async function listFiles(root, maxDepth, dir = "", depth = 0) {
     }
     const results = [];
     for (const entry of entries) {
-        if (entry.name.startsWith(".") && entry.name !== ".agents")
+        if (entry.name.startsWith(".") && entry.name !== ".agents" && entry.name !== ".claude")
             continue;
         if (SKIP_DIRS.has(entry.name))
             continue;
@@ -130,9 +130,11 @@ function parseSkillFrontmatter(content) {
     };
 }
 function skillPriority(path) {
-    if (/^skills\/[^/]+\/SKILL\.md$/i.test(path))
-        return 3;
     if (/^\.agents\/skills\/[^/]+\/SKILL\.md$/i.test(path))
+        return 4;
+    if (/^\.claude\/skills\/[^/]+\/SKILL\.md$/i.test(path))
+        return 3;
+    if (/^skills\/[^/]+\/SKILL\.md$/i.test(path))
         return 2;
     return 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@binarycheater/research-sidecar",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local research graph sidecar and CLI for Codex-assisted research workflows.",
   "keywords": [
     "research",

package/skills/research-graph-sop/SKILL.md

@@ -17,6 +17,15 @@ Prefer this reasoning backbone:
 
 `question -> claim -> method -> evidence -> revision/task/output`
 
+Prefer a tree-like shape for the primary reading path. The graph may remain a DAG when shared evidence, sources, or claims genuinely need reuse, but the default shape should branch outward from the root rather than tangle back into earlier layers.
+
+For visual clarity:
+
+- Point hierarchy edges away from the root along the main reasoning flow.
+- Avoid edges that point back toward ancestors unless the reversal captures a real contradiction, dependency, or revision that cannot be expressed forward.
+- Keep lines short, direct, and easy to scan; remove vague cross-links that make the graph look dense without improving navigation.
+- Prefer one clear parent plus a small number of meaningful lateral links over many convenience links.
+
 A useful graph should let a reader answer:
 
 1. What question is being decomposed?