@binarycheater/research-sidecar 0.1.0

package/scripts/codex-sidecar.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+import { access, cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = parseArgs(process.argv.slice(2));
+const baseUrl = args.url || "http://localhost:4317";
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const appRoot = resolve(scriptDir, "..");
+const repoRoot = resolve(appRoot, "..");
+const defaultAllowedWriteExtensions = [".md", ".markdown", ".html", ".htm", ".yaml", ".yml"];
+
+if (args.help) {
+  console.log(`Usage:
+  npm run codex:install -- --workspace /path/to/research-repo
+  npm run codex:call -- --title "Review" --context "Codex summary" --file SKILL.md --question "What should the sidecar inspect?"
+  npm run codex:ask -- --title "Review" --context "Codex summary" --question "What is the weakest assumption?"
+  npm run codex:session -- --title "Review" --context "Codex summary" --file SKILL.md --file notes.md
+
+Options:
+  --url       Sidecar server URL. Default: http://localhost:4317
+  --workspace Workspace directory to initialize for install mode.
+  --graph     Graph manifest path inside the workspace. Default: research/graph.yaml
+  --no-graph  Do not create a starter graph manifest.
+  --no-skills Do not copy bundled skills into the workspace.
+  --force     Overwrite install-managed files when possible.
+  --title     Session title.
+  --context   Manual context packet notes.
+  --file      Workspace-relative file path. Repeatable.
+  --question  Optional user question for call mode; required prompt for ask mode.
+  --model     Model string. Default server model is used when omitted.
+  --api       responses or chat.
+`);
+  process.exit(0);
+}
+
+if (args.command === "install") {
+  await installWorkspace(args);
+  process.exit(0);
+}
+
+if (args.command !== "call" && args.command !== "session" && args.command !== "ask") {
+  throw new Error(`Unknown command: ${args.command}`);
+}
+
+const session = await request(`${baseUrl}/api/sessions`, {
+  method: "POST",
+  body: JSON.stringify({
+    title: args.title || "Codex handoff",
+    model: args.model,
+    apiMode: args.api
+  })
+});
+
+if (args.context) {
+  await request(`${baseUrl}/api/sessions/${session.id}`, {
+    method: "PATCH",
+    body: JSON.stringify({ manualContext: args.context })
+  });
+}
+
+for (const file of args.files) {
+  await request(`${baseUrl}/api/sessions/${session.id}/files`, {
+    method: "POST",
+    body: JSON.stringify({ path: file })
+  });
+}
+
+if (args.command !== "ask" && args.question) {
+  await request(`${baseUrl}/api/sessions/${session.id}/messages`, {
+    method: "POST",
+    body: JSON.stringify({ role: "user", content: args.question })
+  });
+}
+
+console.log("Sidecar session ready");
+console.log(`${baseUrl}`);
+console.log(`Session: ${session.id}`);
+console.log(`Open: ${baseUrl}`);
+
+if (args.command === "ask") {
+  if (!args.question) {
+    throw new Error("--question is required for ask mode.");
+  }
+  console.log("");
+  console.log("Sidecar answer:");
+  await streamAnswer(`${baseUrl}/api/sessions/${session.id}/stream`, {
+    message: args.question,
+    enableTools: true,
+    includeInstructionFiles: false
+  });
+  console.log("");
+}
+
+function parseArgs(raw) {
+  const parsed = { command: "call", files: [] };
+  const first = raw[0];
+  const start = first && !first.startsWith("-") ? 1 : 0;
+  if (start) {
+    parsed.command = first;
+  }
+  for (let i = start; i < raw.length; i += 1) {
+    const key = raw[i];
+    const value = raw[i + 1];
+    if (key === "--help" || key === "-h") parsed.help = true;
+    if (key === "--url") parsed.url = value, i += 1;
+    if (key === "--workspace") parsed.workspace = value, i += 1;
+    if (key === "--graph") parsed.graph = value, i += 1;
+    if (key === "--no-graph") parsed.noGraph = true;
+    if (key === "--no-skills") parsed.noSkills = true;
+    if (key === "--force") parsed.force = true;
+    if (key === "--title") parsed.title = value, i += 1;
+    if (key === "--context") parsed.context = value, i += 1;
+    if (key === "--file") parsed.files.push(value), i += 1;
+    if (key === "--question") parsed.question = value, i += 1;
+    if (key === "--model") parsed.model = value, i += 1;
+    if (key === "--api") parsed.api = value, i += 1;
+  }
+  return parsed;
+}
+
+async function installWorkspace(args) {
+  const workspaceRoot = resolve(args.workspace || process.cwd());
+  const graphManifestPath = normalizeWorkspacePath(args.graph || "research/graph.yaml");
+  const sideDir = join(workspaceRoot, ".side");
+  const sessionsDir = join(sideDir, "sessions");
+
+  await mkdir(workspaceRoot, { recursive: true });
+  await mkdir(sessionsDir, { recursive: true });
+  await writeSidecarConfig(join(sideDir, "config.json"), graphManifestPath);
+  await writeFileIfMissing(join(sessionsDir, "index.json"), `${JSON.stringify({ sessions: [] }, null, 2)}\n`);
+  await ensureGitignore(workspaceRoot);
+
+  if (!args.noSkills) {
+    await installBundledSkills(workspaceRoot, Boolean(args.force));
+  }
+
+  if (!args.noGraph) {
+    await installStarterGraph(workspaceRoot, graphManifestPath, Boolean(args.force));
+  }
+
+  console.log("Research Sidecar workspace installed");
+  console.log(`Workspace: ${workspaceRoot}`);
+  console.log(`Config: ${join(sideDir, "config.json")}`);
+  console.log(`Graph: ${graphManifestPath}${args.noGraph ? " (not created)" : ""}`);
+  console.log("");
+  console.log("Run from a home/user-level Sidecar install:");
+  console.log(`SIDECAR_WORKSPACE_ROOT="${workspaceRoot}" npm run dev`);
+  console.log("");
+  console.log("Or, if the Sidecar app itself is copied into this workspace:");
+  console.log("cd sidecar && npm run dev");
+}
+
+async function writeSidecarConfig(configPath, graphManifestPath) {
+  const existing = await readJsonFile(configPath);
+  const config = {
+    ...existing,
+    graph: {
+      ...(existing.graph || {}),
+      manifestPath: graphManifestPath
+    },
+    tools: {
+      allowedWriteExtensions: defaultAllowedWriteExtensions,
+      ...(existing.tools || {})
+    }
+  };
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+async function installBundledSkills(workspaceRoot, force) {
+  const sourceRoot = await findBundledSkillsRoot();
+  if (!sourceRoot) return;
+  const names = await readdir(sourceRoot, { withFileTypes: true });
+  await mkdir(join(workspaceRoot, "skills"), { recursive: true });
+  for (const entry of names) {
+    if (!entry.isDirectory()) continue;
+    const source = join(sourceRoot, entry.name);
+    const target = join(workspaceRoot, "skills", entry.name);
+    if (!force && (await exists(target))) continue;
+    await cp(source, target, { recursive: true, force, errorOnExist: false });
+  }
+}
+
+async function findBundledSkillsRoot() {
+  for (const candidate of [join(repoRoot, "skills"), join(appRoot, "skills")]) {
+    if (await exists(candidate)) return candidate;
+  }
+  return null;
+}
+
+async function installStarterGraph(workspaceRoot, graphManifestPath, force) {
+  const graphPath = join(workspaceRoot, graphManifestPath);
+  const graphDir = dirname(graphPath);
+  const notePath = join(graphDir, "rq.main.md");
+  const graphBody = `root: rq.main
+
+ui:
+  layout: LR
+  expanded: [rq.main]
+
+nodes:
+  - id: rq.main
+    title: Core research question
+    type: question
+    file: ./rq.main.md
+    status: active
+    tags: [framing]
+
+edges: []
+`;
+  const noteBody = `# Core research question
+
+Use this note as the first graph node, or replace it with your existing research Markdown.
+`;
+  await mkdir(graphDir, { recursive: true });
+  await writeFileMaybe(graphPath, graphBody, force);
+  await writeFileMaybe(notePath, noteBody, force);
+}
+
+async function ensureGitignore(workspaceRoot) {
+  const path = join(workspaceRoot, ".gitignore");
+  const current = await readTextFile(path);
+  if (current === null) {
+    await writeFile(path, ".side/\n", "utf8");
+    return;
+  }
+  if (!current.split(/\r?\n/).some((line) => line.trim() === ".side/" || line.trim() === ".side")) {
+    const suffix = current.endsWith("\n") || current.length === 0 ? "" : "\n";
+    await writeFile(path, `${current}${suffix}.side/\n`, "utf8");
+  }
+}
+
+async function writeFileIfMissing(path, body) {
+  if (await exists(path)) return;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, body, "utf8");
+}
+
+async function writeFileMaybe(path, body, force) {
+  if (!force && (await exists(path))) return;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, body, "utf8");
+}
+
+async function readJsonFile(path) {
+  const raw = await readTextFile(path);
+  if (!raw?.trim()) return {};
+  return JSON.parse(raw);
+}
+
+async function readTextFile(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function normalizeWorkspacePath(path) {
+  const normalized = path.trim().replace(/^\.\//, "");
+  if (!normalized || normalized.startsWith("../") || normalized.includes("/../") || normalized === "..") {
+    throw new Error("Workspace paths must stay inside the workspace.");
+  }
+  return normalized;
+}
+
+async function request(url, init) {
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(init.headers || {})
+    }
+  });
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    throw new Error(body.error || response.statusText);
+  }
+  return response.json();
+}
+
+async function streamAnswer(url, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!response.ok || !response.body) {
+    const errorBody = await response.json().catch(() => ({}));
+    throw new Error(errorBody.error || response.statusText);
+  }
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const frames = buffer.split("\n\n");
+    buffer = frames.pop() || "";
+    for (const frame of frames) {
+      if (!frame.startsWith("data: ")) {
+        continue;
+      }
+      const payload = JSON.parse(frame.slice(6));
+      if (payload.type === "delta") {
+        process.stdout.write(payload.delta);
+      }
+      if (payload.type === "error") {
+        throw new Error(payload.error);
+      }
+    }
+  }
+}

package/scripts/prepare-package.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = resolve(appRoot, "..");
+const source = resolve(repoRoot, "skills");
+const target = join(appRoot, "skills");
+
+await rm(target, { recursive: true, force: true });
+await mkdir(target, { recursive: true });
+await cp(source, target, { recursive: true });

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

@@ -0,0 +1,183 @@
+---
+name: research-graph-sop
+description: Use when working in a research repository with graph.yaml, Markdown research notes, hypotheses, evidence, experiments, literature sources, or when Codex is asked to inspect, create, update, or maintain a lightweight research graph.
+---
+
+# Research Graph SOP
+
+Use the graph as a small, inspectable map of the research state. Put structure and relationships in `graph.yaml`; put reasoning, evidence details, quotes, experiment notes, and drafts in Markdown files.
+
+Core principle: **thin graph, thick notes, active agent**. The graph should reduce cognitive load, not become a database the researcher has to maintain.
+
+## First Move
+
+If `graph.yaml` exists, read it before proposing structure changes. Then read only the linked Markdown/source files needed to understand the active question, claims, evidence, methods, and tasks.
+
+If no graph exists, inspect nearby research notes, source files, experiment notes, and task files. Build the smallest useful graph that lets a reader answer:
+
+- What is being investigated?
+- What is currently believed or hypothesized?
+- Why believe, doubt, or test it?
+- What should happen next?
+
+## Three Entry Points
+
+### Explore Current Research
+
+Use this when opening an existing research repo or refreshing context.
+
+1. Identify the root question or active hypothesis.
+2. List active claims, rival explanations, methods, evidence, sources, and next tasks.
+3. Detect gaps: unsupported claims, missing rivals, unclear concepts, weak methods, stale tasks.
+4. Update the graph only when the update improves navigation or analysis.
+
+### Start From A Hypothesis
+
+Use this when the user gives a hypothesis before a graph exists or before the project is well framed.
+
+Create a minimal validation graph:
+
+- a `claim` node for the hypothesis
+- a `question` node it answers
+- one or more rival `claim` nodes when plausible
+- `concept` nodes only for necessary definitions or boundaries
+- `method`, `evidence`, `source`, or `task` nodes only when they need tracking
+
+Do not force every prediction, assumption, or falsifier into the graph. Put local details in the claim or method note unless they need separate links.
+
+### Maintain During Research
+
+Use this after experiments, readings, observations, or analysis updates.
+
+1. Add or update the relevant Markdown note first when there is substantive content.
+2. Link evidence to the exact claim it bears on.
+3. Use `supports` only for genuine support, `contradicts` for negative evidence or rival pressure, and `depends_on` for assumptions.
+4. If evidence changes the research direction, revise the question, boundary, method, or task instead of forcing the old hypothesis to survive.
+
+## Minimal Graph Vocabulary
+
+Prefer the existing Sidecar vocabulary:
+
+| Node type | Use for |
+| --- | --- |
+| `question` | research questions and decomposed subquestions |
+| `claim` | hypotheses, mechanism claims, rival explanations |
+| `concept` | definitions, variables, scope, boundary conditions |
+| `method` | experiments, operationalization, identification strategy |
+| `evidence` | observations, results, patterns, counterexamples |
+| `source` | papers, datasets, documents, external materials |
+| `task` | next research action |
+| `output` | draft conclusions, reports, paper sections |
+
+| Edge kind | Use for |
+| --- | --- |
+| `decomposes` | breaks a question into subquestions |
+| `answers` | a claim answers a question |
+| `operationalizes` | a method makes a claim observable |
+| `supports` | evidence/source supports a claim |
+| `contradicts` | evidence/source/rival weakens a claim |
+| `depends_on` | a claim or method relies on a premise |
+| `cites` | a node uses a source |
+| `leads_to` | a result creates a task or next step |
+
+## YAML Contract
+
+When creating or editing `graph.yaml`, keep it valid, boring YAML. Use two-space indentation, arrays with `-`, no tabs, and quote strings only when they contain characters that could confuse YAML (`:`, `#`, `{}`, `[]`, leading `*`, or multiline text).
+
+Top-level shape:
+
+```yaml
+root: rq.main
+
+ui:
+  layout: LR
+  expanded: [rq.main]
+
+nodes:
+  - id: rq.main
+    title: Core research question
+    type: question
+    summary: One sentence is enough when no note exists yet.
+    status: active
+    tags: [framing]
+
+edges:
+  - from: rq.main
+    to: claim.001
+    kind: answers
+```
+
+Required:
+
+- `root`: id of an existing node.
+- `nodes`: array of node objects.
+- each node: `id`, `title`, `type`.
+- `edges`: array, empty is fine.
+- each edge: `from`, `to`, `kind`; both ids must exist in `nodes`.
+
+Optional node fields:
+
+- `summary`: use for short, one-sentence nodes that do not need a document yet.
+- `file`: one linked Markdown/HTML/text document.
+- `files`: multiple linked documents. Use either strings or `{ path, title }` objects.
+- `status`: `active`, `draft`, `blocked`, or `done`.
+- `tags`: array of short labels.
+
+Valid document-link patterns:
+
+```yaml
+nodes:
+  - id: claim.short
+    title: Short claim
+    type: claim
+    summary: This node is intentionally just one sentence for now.
+
+  - id: evidence.single
+    title: Single note
+    type: evidence
+    file: ./evidence.md
+
+  - id: source.bundle
+    title: Source bundle
+    type: source
+    files:
+      - ./paper.md
+      - path: ./appendix.html
+        title: Appendix preview
+```
+
+Do not force every node to link to a document. Add `file` or `files` only when the longer note exists or when creating the link improves navigation. Missing linked files are allowed while drafting, but they should be intentional and called out in the change report.
+
+## Agent Discipline
+
+Act primarily as an active research assistant: propose subquestions, hypotheses, rival explanations, operationalizations, and next tasks.
+
+Also apply two constraints:
+
+- **Reviewer:** attack weak claims, hidden assumptions, unclear concepts, non-falsifiable hypotheses, and methods that build in their conclusion.
+- **Gatekeeper:** do not present a claim as settled unless it has relevant evidence and plausible rival explanations have been considered.
+
+New agent-created nodes should usually be `status: draft`. Use `active` when the researcher is actually pursuing the node, `blocked` when progress depends on missing material, and `done` only for completed tasks or stable source nodes.
+
+## Keep It Lightweight
+
+Add a graph node only when the item needs to be navigated, connected, reused, challenged, or tracked over time.
+
+Avoid:
+
+- duplicating long Markdown content in `summary`
+- making every sentence a node
+- adding schema fields the current repo does not already use
+- treating the graph as proof by itself
+- hiding uncertainty behind tidy structure
+
+Good graph changes make the current research easier to inspect in under a minute.
+
+## Change Report
+
+When updating the graph, summarize:
+
+- nodes added, changed, or removed
+- important edges added or changed
+- Markdown notes created or updated
+- remaining methodological gaps or next tasks

package/skills/research-graph-sop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Research Graph SOP"
+  short_description: "Build and maintain lightweight research hypothesis graphs"
+  default_prompt: "Use $research-graph-sop to inspect this research repo, build or update graph.yaml, and keep hypothesis testing traceable."

package/skills/scholar-mode/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: scholar-mode
+description: Use when a task is explicitly framed as research, scholarship, literature analysis, theory building, methodology critique, paper reading, academic writing, research notes, or evaluating a research intuition.
+---
+
+# Scholar Mode
+
+Act as a research collaborator, not a coding agent. Optimize for conceptual precision, evidence quality, argument strength, and readable synthesis.
+
+## Scope
+
+Use for research thinking, papers, notes, claims, hypotheses, theory, methods, scholarly writing, literature reading, and judging research intuitions.
+
+Do not apply when the user's primary request is implementation, debugging, tests, repository operations, app design, software architecture, or ordinary factual help. If a turn mixes research and implementation, apply this skill only to the research-analysis portion.
+
+When this skill applies, do not propose code, architecture, tests, apps, agents, implementation plans, roadmaps, specs, or project structures unless explicitly requested. Do not turn research questions into software tasks or project-management framing. Do not scan repositories, run commands, install dependencies, start services, use git, or edit files unless directly useful for the research task or explicitly requested.
+
+## Judgment Protocol
+
+Before answering, internally check: What is being judged? What evidence or material is available? What assumptions are doing the work? What would weaken or falsify the claim?
+
+- Lead with the substantive conclusion, then give the basis and caveats.
+- Distinguish facts, inferences, assumptions, value judgments, and open questions.
+- Say weak evidence is weak; evaluate weak ideas instead of praising them by default.
+- Do not invent citations, paper titles, authors, findings, or consensus.
+- If relying on memory rather than checked sources, label it as memory or inference.
+
+## Research Graph Use
+
+When a workspace includes `graph.yaml`, treat it as the structural map of the research project: nodes, relationships, and file pointers. Treat Markdown files as the content layer. If the user asks to update research structure, prefer editing the graph manifest and the affected Markdown notes together.
+
+## Output
+
+Be brief, direct, and information-dense. For longer answers, start with a short TL;DR, then give the judgment, main reasons, caveats, and next move. Use tables only when comparison helps.

package/skills/scholar-mode/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Scholar Mode"
+  short_description: "Research judgment, literature reasoning, theory, methods, and scholarly writing"
+  default_prompt: "Use $scholar-mode to analyze the research idea, evidence, assumptions, and next scholarly move."

package/skills/sidecar-thinking/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sidecar-thinking
+description: Use when Codex should call the local Research Sidecar app, create or inspect a Sidecar session, hand off explicit context, maintain a research graph, or use the Sidecar API/CLI for a second-opinion review.
+---
+
+# Sidecar Thinking
+
+Use this skill to connect Codex with the local Research Sidecar app. The app is a workspace-aware web UI with chat sessions, a manifest-backed research graph, Markdown/HTML previews, and restricted workspace tools.
+
+## Start Or Find The App
+
+If the server is not already running, start it from the workspace root:
+
+```bash
+research-sidecar
+```
+
+Default URL: `http://localhost:4317`.
+
+The directory where `research-sidecar` is launched becomes the workspace root. The workspace config lives at `.side/config.json`.
+
+## Default Handoff
+
+Prefer staging a session for the user:
+
+```bash
+cd sidecar
+npm run codex:call -- --title "Review" --context "Codex summary..." --file research/graph.yaml --question "What is the weakest assumption?"
+```
+
+Use automatic ask mode only when the user explicitly wants Codex to relay the answer:
+
+```bash
+cd sidecar
+npm run codex:ask -- --title "Review" --context "Codex summary..." --question "What should Codex do next?"
+```
+
+## Research Graph
+
+The graph is manifest-first:
+
+- `graph.yaml` is the authority for nodes, edges, UI defaults, and file pointers.
+- Markdown and HTML files hold node content.
+- Markdown frontmatter can supply local metadata, but `graph.yaml` wins on conflicts.
+- Graph file links are relative to the graph manifest directory by default. Use a leading `/` for an explicit workspace-root-relative link.
+
+Default manifest path: `research/graph.yaml`. Override with `SIDECAR_GRAPH_MANIFEST` or `.side/config.json` at `graph.manifestPath`. The UI can discover graph files across the workspace and save the selected graph to `.side/config.json`.
+
+## API Quick Reference
+
+- `GET /api/config`
+- `PATCH /api/config`
+- `GET /api/graphs`
+- `GET /api/workspace`
+- `POST /api/workspace/skills/install`
+- `GET /api/workspace/file?path=<workspace-relative-path>`
+- `GET /api/workspace/raw?path=<workspace-relative-path>`
+- `GET /api/research-graph`
+- `GET /api/sessions`
+- `POST /api/sessions`
+- `GET /api/sessions/:id`
+- `PATCH /api/sessions/:id`
+- `POST /api/sessions/:id/files`
+- `POST /api/sessions/:id/messages`
+- `POST /api/sessions/:id/stream`
+
+All workspace paths are constrained to the configured workspace root.

package/skills/sidecar-thinking/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Sidecar Thinking"
+  short_description: "Call the local Research Sidecar app and maintain its research graph"
+  default_prompt: "Use $sidecar-thinking to create a Sidecar review session, inspect the graph, or update graph-backed research notes."