@binarycheater/research-sidecar 0.1.0 → 0.1.1

package/package.json

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

package/skills/sidecar-thinking/SKILL.md

@@ -1,40 +1,80 @@
 ---
 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.
+description: Use when the user explicitly asks to use Research Sidecar, open/start/connect to the sidecar app, inspect or select a sidecar research graph, install sidecar workspace skills, or run an external/second-opinion sidecar thinking pass.
 ---
 
 # 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.
+Research Sidecar is an opt-in external tool. Do not invoke it just because the task involves research, reports, Markdown, YAML, or graph-like structure.
 
-## Start Or Find The App
+## Strict Trigger
 
-If the server is not already running, start it from the workspace root:
+Use this skill only when the user explicitly asks for at least one of these:
+
+- Use, open, start, run, connect to, or inspect Research Sidecar.
+- Use the sidecar graph view, select/save a graph, preview graph-linked documents, or inspect a sidecar research graph.
+- Do an external, out-of-band, second-opinion, or sidecar thinking pass.
+- Install the sidecar bundled skills into the current workspace.
+
+Do not use this skill for ordinary research reasoning, report writing, code edits, Markdown/HTML generation, YAML editing, or generic graph work unless the user ties the request to Sidecar.
+
+## Current CLI Shape
+
+Start the app only when the user asked for Sidecar to be used or started:
 
 ```bash
 research-sidecar
 ```
 
-Default URL: `http://localhost:4317`.
+Useful variants:
+
+```bash
+research-sidecar --workspace /path/to/workspace
+research-sidecar --graph dingyi/synthetic/graph.yaml
+research-sidecar --port 4317
+```
+
+Initialize a workspace:
+
+```bash
+research-sidecar init --graph research/graph.yaml
+research-sidecar init --graph research/graph.yaml --no-skills
+```
 
-The directory where `research-sidecar` is launched becomes the workspace root. The workspace config lives at `.side/config.json`.
+Install bundled skills into the workspace:
 
-## Default Handoff
+```bash
+research-sidecar install-skills
+research-sidecar install-skills --force
+```
 
-Prefer staging a session for the user:
+If installed as a project dependency, use the same commands through `npx`:
 
 ```bash
-cd sidecar
-npm run codex:call -- --title "Review" --context "Codex summary..." --file research/graph.yaml --question "What is the weakest assumption?"
+npx research-sidecar
+npx research-sidecar install-skills
 ```
 
-Use automatic ask mode only when the user explicitly wants Codex to relay the answer:
+For one-shot use without a local install:
 
 ```bash
-cd sidecar
-npm run codex:ask -- --title "Review" --context "Codex summary..." --question "What should Codex do next?"
+npx @binarycheater/research-sidecar
 ```
 
+The directory where `research-sidecar` runs is the workspace root unless `--workspace` is supplied. Private state lives in `.side/config.json`. Default URL: `http://localhost:4317`.
+
+## Sessions And API
+
+Use the API only after the Sidecar server is running and the user asked for Sidecar involvement.
+
+Common session sequence:
+
+1. `POST /api/sessions`
+2. `PATCH /api/sessions/:id` with manual context
+3. `POST /api/sessions/:id/files` for workspace-relative files
+4. `POST /api/sessions/:id/messages` to stage a user question
+5. `POST /api/sessions/:id/stream` only if the user asked Codex to relay the sidecar answer
+
 ## Research Graph
 
 The graph is manifest-first:
@@ -44,7 +84,7 @@ The graph is manifest-first:
 - 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`.
+Default manifest path: `research/graph.yaml`. Override with `--graph`, or save the active graph in `.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
 

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

@@ -1,4 +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."
+  short_description: "Use Research Sidecar only when explicitly requested"
+  default_prompt: "Use $sidecar-thinking only when I explicitly ask to use/open/start Research Sidecar, inspect a sidecar research graph, install sidecar workspace skills, or run an external sidecar thinking pass."