Reframe Feynman for general research workflows

.gitignore

@@ -7,3 +7,9 @@ dist
 *.tgz
 outputs/*
 !outputs/.gitkeep
+papers/*
+!papers/.gitkeep
+notes/*
+!notes/.gitkeep
+experiments/*
+!experiments/.gitkeep

.pi/settings.json

@@ -5,7 +5,6 @@
     "npm:pi-web-access",
     "npm:pi-markdown-preview",
     "npm:@aliou/pi-processes",
-    "npm:pi-wandb",
     "npm:pi-zotero"
   ]
 }

.pi/themes/feynman.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "feynman",
+  "vars": {
+    "ink": "#d9d3c7",
+    "paper": "#1f1c19",
+    "paper2": "#26221e",
+    "paper3": "#2f2a25",
+    "stone": "#8c8378",
+    "ash": "#6c655d",
+    "oxide": "#b76e4c",
+    "gold": "#d0a85c",
+    "sage": "#88a88a",
+    "teal": "#7aa6a1",
+    "rose": "#c97b84",
+    "violet": "#a98dc6",
+    "selection": "#3a342e"
+  },
+  "colors": {
+    "accent": "gold",
+    "border": "ash",
+    "borderAccent": "gold",
+    "borderMuted": "ash",
+    "success": "sage",
+    "error": "rose",
+    "warning": "oxide",
+    "muted": "stone",
+    "dim": "ash",
+    "text": "ink",
+    "thinkingText": "stone",
+
+    "selectedBg": "selection",
+    "userMessageBg": "paper3",
+    "userMessageText": "ink",
+    "customMessageBg": "paper3",
+    "customMessageText": "ink",
+    "customMessageLabel": "violet",
+    "toolPendingBg": "paper2",
+    "toolSuccessBg": "#243028",
+    "toolErrorBg": "#362725",
+    "toolTitle": "gold",
+    "toolOutput": "ink",
+
+    "mdHeading": "gold",
+    "mdLink": "teal",
+    "mdLinkUrl": "stone",
+    "mdCode": "teal",
+    "mdCodeBlock": "ink",
+    "mdCodeBlockBorder": "ash",
+    "mdQuote": "stone",
+    "mdQuoteBorder": "ash",
+    "mdHr": "ash",
+    "mdListBullet": "gold",
+
+    "toolDiffAdded": "sage",
+    "toolDiffRemoved": "rose",
+    "toolDiffContext": "stone",
+
+    "syntaxComment": "stone",
+    "syntaxKeyword": "gold",
+    "syntaxFunction": "teal",
+    "syntaxVariable": "ink",
+    "syntaxString": "sage",
+    "syntaxNumber": "oxide",
+    "syntaxType": "violet",
+    "syntaxOperator": "ink",
+    "syntaxPunctuation": "stone",
+
+    "thinkingOff": "ash",
+    "thinkingMinimal": "stone",
+    "thinkingLow": "teal",
+    "thinkingMedium": "gold",
+    "thinkingHigh": "violet",
+    "thinkingXhigh": "rose",
+
+    "bashMode": "oxide"
+  },
+  "export": {
+    "pageBg": "#171411",
+    "cardBg": "#211d19",
+    "infoBg": "#312821"
+  }
+}

README.md

@@ -54,8 +54,11 @@ Inside the REPL:
 - `/lit-review <topic>` expands the literature-review prompt template
 - `/replicate <paper or claim>` expands the replication prompt template
 - `/reading-list <topic>` expands the reading-list prompt template
+- `/research-memo <topic>` expands the general research memo prompt template
+- `/compare-sources <topic>` expands the source comparison prompt template
 - `/paper-code-audit <item>` expands the paper/code audit prompt template
 - `/paper-draft <topic>` expands the paper-style writing prompt template
+- `/research-memo <topic>` expands the general research memo prompt template
 
 ## Custom Tools
 
@@ -78,9 +81,7 @@ Feynman loads a lean research stack from [.pi/settings.json](/Users/advaitpaliwa
 - `pi-docparser` for PDFs, Office docs, spreadsheets, and images
 - `pi-web-access` for broader web, GitHub, PDF, and media access
 - `pi-markdown-preview` for polished Markdown and LaTeX-heavy research writeups
-- `@kaiserlich-dev/pi-session-search` for recall across long-running research threads
 - `@aliou/pi-processes` for long-running experiments and log tails
-- `pi-wandb` for experiment tracking
 - `pi-zotero` for citation-library workflows
 
 ## Layout

package-lock.json

@@ -1,15 +1,15 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@companion-ai/feynman",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "hasInstallScript": true,
       "dependencies": {
-        "@companion-ai/alpha-hub": "^0.1.1",
+        "@companion-ai/alpha-hub": "^0.1.2",
         "@mariozechner/pi-ai": "^0.56.1",
         "@mariozechner/pi-coding-agent": "^0.56.1",
         "@sinclair/typebox": "^0.34.41",
@@ -29,7 +29,7 @@
     },
     "../alpha-hub/cli": {
       "name": "@companion-ai/alpha-hub",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.27.1",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     ]
   },
   "dependencies": {
-    "@companion-ai/alpha-hub": "^0.1.1",
+    "@companion-ai/alpha-hub": "^0.1.2",
     "@mariozechner/pi-ai": "^0.56.1",
     "@mariozechner/pi-coding-agent": "^0.56.1",
     "@sinclair/typebox": "^0.34.41",

prompts/compare-sources.md

@@ -0,0 +1,17 @@
+---
+description: Compare multiple sources on a topic and produce a source-grounded matrix of agreements, disagreements, and confidence.
+---
+Compare sources for: $@
+
+Requirements:
+- Identify the strongest relevant primary sources first.
+- Inspect the top sources directly before comparing them.
+- Build a comparison matrix covering:
+  - source
+  - key claim
+  - evidence type
+  - caveats
+  - confidence
+- Distinguish agreement, disagreement, and uncertainty clearly.
+- End with a `Sources` section containing direct URLs for every source used.
+- Save the comparison to `outputs/` as markdown if the user wants a durable artifact.

prompts/lit-review.md

@@ -10,4 +10,5 @@ Requirements:
 - Prefer primary sources and note when something appears to be a preprint or secondary summary.
 - Separate consensus, disagreements, and open questions.
 - When useful, propose concrete next experiments or follow-up reading.
+- End with a `Sources` section containing direct URLs for every paper or source used.
 - If the user wants an artifact, write the review to disk as markdown.

prompts/paper-code-audit.md

@@ -9,4 +9,5 @@ Requirements:
 - If a public repo exists, inspect it with `alpha_read_code`.
 - Compare claimed methods, defaults, metrics, and data handling against the repository.
 - Call out missing code, mismatches, ambiguous defaults, and reproduction risks.
+- End with a `Sources` section containing paper and repository URLs.
 - Save the audit to `outputs/` as markdown.

prompts/paper-draft.md

@@ -16,4 +16,5 @@ Requirements:
   - limitations
   - conclusion
 - If citations are available, include citation placeholders or references clearly enough to convert later.
+- Add a `Sources` appendix with direct URLs for all primary references used while drafting.
 - Save the draft to `papers/` as markdown.

prompts/reading-list.md

@@ -9,4 +9,5 @@ Requirements:
 - Use `alpha_ask_paper` when a paper's fit is unclear.
 - Group papers by role when useful: foundational, strongest recent work, methods, benchmarks, critiques, replication targets.
 - For each paper, explain why it is on the list.
+- Include direct URLs for each recommended source.
 - Save the final reading list to `outputs/` as markdown.

prompts/replicate.md

@@ -12,3 +12,4 @@ Requirements:
 - If enough information is available locally, implement and run the replication steps.
 - Save notes, scripts, and results to disk in a reproducible layout.
 - Be explicit about what is verified, what is inferred, and what is still missing.
+- End with a `Sources` section containing paper and repository URLs.

prompts/research-memo.md

@@ -0,0 +1,11 @@
+---
+description: Produce a general research memo grounded in explicit sources and direct links.
+---
+Write a research memo about: $@
+
+Requirements:
+- Start by finding the strongest relevant sources.
+- Read or inspect the top sources directly before making strong claims.
+- Distinguish facts, interpretations, and open questions.
+- End with a `Sources` section containing direct URLs for every source used.
+- Save the memo to `outputs/` as markdown if the user wants a durable artifact.

skills/research/literature-review/SKILL.md

@@ -33,6 +33,7 @@ Use this skill when the user wants:
    - what remains unresolved
 7. If the user wants a durable artifact, write a markdown brief to disk.
 8. If you discover an important gotcha about a paper, save it with `alpha_annotate_paper`.
+9. End with a `Sources` section that lists direct URLs, not just titles.
 
 ## Pitfalls
 
@@ -50,3 +51,4 @@ Prefer this structure:
 - disagreements or caveats
 - open questions
 - recommended next reading or experiments
+- sources

skills/research/paper-code-audit/SKILL.md

@@ -32,6 +32,7 @@ Use this skill for:
 6. Record concrete mismatches, not vibes.
 7. Save the audit in `outputs/`.
 8. If you find a durable gotcha, save it with `alpha_annotate_paper`.
+9. End with a `Sources` section for the paper and repository.
 
 ## Pitfalls
 
@@ -48,3 +49,4 @@ Include:
 - mismatches or omissions
 - reproducibility risks
 - recommended next actions
+- sources

skills/research/paper-writing/SKILL.md

@@ -29,6 +29,7 @@ Use this skill for:
 4. Use LaTeX only where equations or notation genuinely improve clarity.
 5. Keep claims falsifiable and scoped.
 6. Save polished drafts to `papers/`.
+7. Add a `Sources` appendix with direct URLs to all inspected references.
 
 ## Pitfalls
 

skills/research/reading-list/SKILL.md

@@ -32,6 +32,7 @@ Use this skill for:
    - move to strongest methods
    - finish with edges, critiques, or adjacent work
 6. Write the final list as a durable markdown artifact in `outputs/`.
+7. For every paper, include a direct URL.
 
 ## Pitfalls
 

skills/research/research-memo/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: research-memo
+description: Use this when the user wants a source-grounded memo, briefing, landscape summary, or background note that is broader than a single paper.
+---
+
+# Research Memo
+
+## When To Use
+
+Use this skill for:
+- background research
+- topic briefings
+- market or field overviews
+- synthesis across multiple sources
+- internal memos that need traceable evidence
+
+## Procedure
+
+1. Find relevant sources first.
+2. Inspect the strongest sources directly before synthesizing.
+3. Separate:
+   - established facts
+   - plausible inferences
+   - unresolved questions
+4. Write a memo with clear sections and a concise narrative.
+5. End with a `Sources` section containing direct links.
+6. Save the memo to `outputs/` when the user wants a durable artifact.
+
+## Pitfalls
+
+- Do not summarize from search snippets alone.
+- Do not omit the source list.
+- Do not present inference as fact.
+
+## Deliverable
+
+Include:
+- topic
+- key findings
+- disagreements or caveats
+- open questions
+- sources

skills/research/source-comparison/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: source-comparison
+description: Use this when the task is to compare multiple papers, reports, or sources and produce a grounded matrix of agreements, disagreements, and confidence.
+---
+
+# Source Comparison
+
+## When To Use
+
+Use this skill for:
+- comparing papers on the same topic
+- reconciling conflicting claims
+- assessing multiple sources before making a recommendation
+- producing evidence matrices
+
+## Procedure
+
+1. Find and inspect the strongest relevant sources first.
+2. For each source, extract:
+   - main claim
+   - evidence type
+   - caveats
+   - what would falsify or weaken the claim
+3. Build a comparison table or matrix.
+4. Separate:
+   - points of agreement
+   - points of disagreement
+   - unresolved questions
+5. End with a `Sources` section containing direct URLs.
+
+## Pitfalls
+
+- Do not compare sources you have not actually opened.
+- Do not blur disagreement into consensus.
+- Do not omit source links.
+
+## Deliverable
+
+Include:
+- matrix
+- agreement summary
+- disagreement summary
+- confidence assessment
+- sources

src/feynman-prompt.ts

@@ -13,6 +13,8 @@ Operating rules:
 - Use the installed Pi research packages for broader web/PDF access, document parsing, session recall, background processes, experiment tracking, citations, and delegated subtasks when they reduce friction.
 - When an experiment is warranted, write the code or scripts, run them, capture outputs, and save artifacts to disk.
 - Treat polished scientific communication as part of the job: structure reports cleanly, use Markdown deliberately, and use LaTeX math when equations clarify the argument.
+- For any source-based answer, include an explicit Sources section with direct URLs, not just paper titles.
+- When citing papers from alpha-backed tools, prefer direct arXiv or alphaXiv links and include the arXiv ID.
 - Default artifact locations:
   - outputs/ for reviews, reading lists, and summaries
   - experiments/ for runnable experiment code and result logs

src/index.ts

@@ -33,6 +33,8 @@ function printHelp(): void {
 	  /lit-review <topic>       Expand the literature review prompt template
 	  /replicate <paper>        Expand the replication prompt template
 	  /reading-list <topic>     Expand the reading list prompt template
+	  /research-memo <topic>    Expand the general research memo prompt template
+	  /compare-sources <topic>  Expand the source comparison prompt template
 	  /paper-code-audit <item>  Expand the paper/code audit prompt template
 	  /paper-draft <topic>      Expand the paper-style writing prompt template
 
@@ -156,6 +158,7 @@ function normalizeFeynmanSettings(
 	if (!settings.defaultThinkingLevel) {
 		settings.defaultThinkingLevel = defaultThinkingLevel;
 	}
+	settings.theme = "feynman";
 
 	const authStorage = AuthStorage.create(authPath);
 	const modelRegistry = new ModelRegistry(authStorage);
@@ -175,6 +178,19 @@ function normalizeFeynmanSettings(
 	writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
 }
 
+function syncFeynmanTheme(appRoot: string, agentDir: string): void {
+	const sourceThemePath = resolve(appRoot, ".pi", "themes", "feynman.json");
+	const targetThemeDir = resolve(agentDir, "themes");
+	const targetThemePath = resolve(targetThemeDir, "feynman.json");
+
+	if (!existsSync(sourceThemePath)) {
+		return;
+	}
+
+	mkdirSync(targetThemeDir, { recursive: true });
+	writeFileSync(targetThemePath, readFileSync(sourceThemePath, "utf8"), "utf8");
+}
+
 async function main(): Promise<void> {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const appRoot = resolve(here, "..");
@@ -209,6 +225,7 @@ async function main(): Promise<void> {
 	const sessionDir = resolve(values["session-dir"] ?? resolve(homedir(), ".feynman", "sessions"));
 	mkdirSync(sessionDir, { recursive: true });
 	mkdirSync(feynmanAgentDir, { recursive: true });
+	syncFeynmanTheme(appRoot, feynmanAgentDir);
 	const feynmanSettingsPath = resolve(feynmanAgentDir, "settings.json");
 	const feynmanAuthPath = resolve(feynmanAgentDir, "auth.json");
 	const thinkingLevel = normalizeThinkingLevel(values.thinking ?? process.env.FEYNMAN_THINKING) ?? "medium";