@companion-ai/feynman 0.2.0

package/scripts/patch-embedded-pi.mjs

@@ -0,0 +1,319 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appRoot = resolve(here, "..");
+const piPackageRoot = resolve(appRoot, "node_modules", "@mariozechner", "pi-coding-agent");
+const packageJsonPath = resolve(piPackageRoot, "package.json");
+const cliPath = resolve(piPackageRoot, "dist", "cli.js");
+const bunCliPath = resolve(piPackageRoot, "dist", "bun", "cli.js");
+const interactiveModePath = resolve(piPackageRoot, "dist", "modes", "interactive", "interactive-mode.js");
+const interactiveThemePath = resolve(piPackageRoot, "dist", "modes", "interactive", "theme", "theme.js");
+const piTuiRoot = resolve(appRoot, "node_modules", "@mariozechner", "pi-tui");
+const editorPath = resolve(piTuiRoot, "dist", "components", "editor.js");
+const workspaceRoot = resolve(appRoot, ".feynman", "npm", "node_modules");
+const webAccessPath = resolve(workspaceRoot, "pi-web-access", "index.ts");
+const sessionSearchIndexerPath = resolve(
+	workspaceRoot,
+	"@kaiserlich-dev",
+	"pi-session-search",
+	"extensions",
+	"indexer.ts",
+);
+const piMemoryPath = resolve(workspaceRoot, "@samfp", "pi-memory", "src", "index.ts");
+const settingsPath = resolve(appRoot, ".feynman", "settings.json");
+const workspaceDir = resolve(appRoot, ".feynman", "npm");
+const workspacePackageJsonPath = resolve(workspaceDir, "package.json");
+
+function ensurePackageWorkspace() {
+	if (!existsSync(settingsPath)) {
+		return;
+	}
+
+	const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+	const packageSpecs = Array.isArray(settings.packages)
+		? settings.packages
+			.filter((value) => typeof value === "string" && value.startsWith("npm:"))
+			.map((value) => value.slice(4))
+		: [];
+
+	if (packageSpecs.length === 0) {
+		return;
+	}
+
+	mkdirSync(workspaceDir, { recursive: true });
+
+	writeFileSync(
+		workspacePackageJsonPath,
+		JSON.stringify(
+			{
+				name: "pi-extensions",
+				private: true,
+				dependencies: Object.fromEntries(packageSpecs.map((spec) => [spec, "latest"])),
+			},
+			null,
+			2,
+		) + "\n",
+		"utf8",
+	);
+
+	const npmExec = process.env.npm_execpath;
+	const install = npmExec
+		? spawnSync(process.execPath, [npmExec, "install", "--prefix", workspaceDir, ...packageSpecs], {
+				stdio: "inherit",
+			})
+		: spawnSync("npm", ["install", "--prefix", workspaceDir, ...packageSpecs], {
+				stdio: "inherit",
+			});
+
+	if (install.status !== 0) {
+		console.warn("[feynman] warning: failed to preinstall default Pi packages into .feynman/npm");
+	}
+}
+
+ensurePackageWorkspace();
+
+if (existsSync(packageJsonPath)) {
+	const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	if (pkg.piConfig?.name !== "feynman" || pkg.piConfig?.configDir !== ".feynman") {
+		pkg.piConfig = {
+			...(pkg.piConfig || {}),
+			name: "feynman",
+			configDir: ".feynman",
+		};
+		writeFileSync(packageJsonPath, JSON.stringify(pkg, null, "\t") + "\n", "utf8");
+	}
+}
+
+for (const entryPath of [cliPath, bunCliPath]) {
+	if (!existsSync(entryPath)) {
+		continue;
+	}
+
+	const cliSource = readFileSync(entryPath, "utf8");
+	if (cliSource.includes('process.title = "pi";')) {
+		writeFileSync(entryPath, cliSource.replace('process.title = "pi";', 'process.title = "feynman";'), "utf8");
+	}
+}
+
+if (existsSync(interactiveModePath)) {
+	const interactiveModeSource = readFileSync(interactiveModePath, "utf8");
+	if (interactiveModeSource.includes("`π - ${sessionName} - ${cwdBasename}`")) {
+		writeFileSync(
+			interactiveModePath,
+			interactiveModeSource
+				.replace("`π - ${sessionName} - ${cwdBasename}`", "`feynman - ${sessionName} - ${cwdBasename}`")
+				.replace("`π - ${cwdBasename}`", "`feynman - ${cwdBasename}`"),
+			"utf8",
+		);
+	}
+}
+
+if (existsSync(interactiveThemePath)) {
+	let themeSource = readFileSync(interactiveThemePath, "utf8");
+	const desiredGetEditorTheme = [
+		"export function getEditorTheme() {",
+		"    return {",
+		'        borderColor: (text) => " ".repeat(text.length),',
+		'        bgColor: (text) => theme.bg("userMessageBg", text),',
+		'        placeholderText: "Type your message or /help for commands",',
+		'        placeholder: (text) => theme.fg("dim", text),',
+		"        selectList: getSelectListTheme(),",
+		"    };",
+		"}",
+	].join("\n");
+	themeSource = themeSource.replace(
+		/export function getEditorTheme\(\) \{[\s\S]*?\n\}\nexport function getSettingsListTheme\(\) \{/m,
+		`${desiredGetEditorTheme}\nexport function getSettingsListTheme() {`,
+	);
+	writeFileSync(interactiveThemePath, themeSource, "utf8");
+}
+
+if (existsSync(editorPath)) {
+	let editorSource = readFileSync(editorPath, "utf8");
+	const importOriginal =
+		'import { getSegmenter, isPunctuationChar, isWhitespaceChar, truncateToWidth, visibleWidth } from "../utils.js";';
+	const importReplacement =
+		'import { applyBackgroundToLine, getSegmenter, isPunctuationChar, isWhitespaceChar, truncateToWidth, visibleWidth } from "../utils.js";';
+	if (editorSource.includes(importOriginal)) {
+		editorSource = editorSource.replace(importOriginal, importReplacement);
+	}
+	const desiredRender = [
+		"    render(width) {",
+		"        const maxPadding = Math.max(0, Math.floor((width - 1) / 2));",
+		"        const paddingX = Math.min(this.paddingX, maxPadding);",
+		"        const contentWidth = Math.max(1, width - paddingX * 2);",
+		"        // Layout width: with padding the cursor can overflow into it,",
+		"        // without padding we reserve 1 column for the cursor.",
+		"        const layoutWidth = Math.max(1, contentWidth - (paddingX ? 0 : 1));",
+		"        // Store for cursor navigation (must match wrapping width)",
+		"        this.lastWidth = layoutWidth;",
+		'        const horizontal = this.borderColor("─");',
+		"        const bgColor = this.theme.bgColor;",
+		"        // Layout the text",
+		"        const layoutLines = this.layoutText(layoutWidth);",
+		"        // Calculate max visible lines: 30% of terminal height, minimum 5 lines",
+		"        const terminalRows = this.tui.terminal.rows;",
+		"        const maxVisibleLines = Math.max(5, Math.floor(terminalRows * 0.3));",
+		"        // Find the cursor line index in layoutLines",
+		"        let cursorLineIndex = layoutLines.findIndex((line) => line.hasCursor);",
+		"        if (cursorLineIndex === -1)",
+		"            cursorLineIndex = 0;",
+		"        // Adjust scroll offset to keep cursor visible",
+		"        if (cursorLineIndex < this.scrollOffset) {",
+		"            this.scrollOffset = cursorLineIndex;",
+		"        }",
+		"        else if (cursorLineIndex >= this.scrollOffset + maxVisibleLines) {",
+		"            this.scrollOffset = cursorLineIndex - maxVisibleLines + 1;",
+		"        }",
+		"        // Clamp scroll offset to valid range",
+		"        const maxScrollOffset = Math.max(0, layoutLines.length - maxVisibleLines);",
+		"        this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, maxScrollOffset));",
+		"        // Get visible lines slice",
+		"        const visibleLines = layoutLines.slice(this.scrollOffset, this.scrollOffset + maxVisibleLines);",
+		"        const result = [];",
+		'        const leftPadding = " ".repeat(paddingX);',
+		"        const rightPadding = leftPadding;",
+		"        const renderBorderLine = (indicator) => {",
+		"            const remaining = width - visibleWidth(indicator);",
+		"            if (remaining >= 0) {",
+		'                return this.borderColor(indicator + "─".repeat(remaining));',
+		"            }",
+		"            return this.borderColor(truncateToWidth(indicator, width));",
+		"        };",
+		"        // Render top padding row. When background fill is active, mimic the user-message block",
+		"        // instead of the stock editor chrome.",
+		"        if (bgColor) {",
+		"            if (this.scrollOffset > 0) {",
+		"                const indicator = `  ↑ ${this.scrollOffset} more`;",
+		"                result.push(applyBackgroundToLine(indicator, width, bgColor));",
+		"            }",
+		"            else {",
+		'                result.push(applyBackgroundToLine("", width, bgColor));',
+		"            }",
+		"        }",
+		"        else if (this.scrollOffset > 0) {",
+		"            const indicator = `─── ↑ ${this.scrollOffset} more `;",
+		"            result.push(renderBorderLine(indicator));",
+		"        }",
+		"        else {",
+		"            result.push(horizontal.repeat(width));",
+		"        }",
+		"        // Render each visible layout line",
+		"        // Emit hardware cursor marker only when focused and not showing autocomplete",
+		"        const emitCursorMarker = this.focused && !this.autocompleteState;",
+		"        const showPlaceholder = this.state.lines.length === 1 &&",
+		'            this.state.lines[0] === "" &&',
+		'            typeof this.theme.placeholderText === "string" &&',
+		"            this.theme.placeholderText.length > 0;",
+		"        for (let visibleIndex = 0; visibleIndex < visibleLines.length; visibleIndex++) {",
+		"            const layoutLine = visibleLines[visibleIndex];",
+		"            const isFirstLayoutLine = this.scrollOffset + visibleIndex === 0;",
+		"            let displayText = layoutLine.text;",
+		"            let lineVisibleWidth = visibleWidth(layoutLine.text);",
+		"            const isPlaceholderLine = showPlaceholder && isFirstLayoutLine;",
+		"            if (isPlaceholderLine) {",
+		"                const marker = emitCursorMarker ? CURSOR_MARKER : \"\";",
+		"                const rawPlaceholder = this.theme.placeholderText;",
+		'                const styledPlaceholder = typeof this.theme.placeholder === "function"',
+		"                    ? this.theme.placeholder(rawPlaceholder)",
+		"                    : rawPlaceholder;",
+		"                displayText = marker + styledPlaceholder;",
+		"                lineVisibleWidth = visibleWidth(rawPlaceholder);",
+		"            }",
+		"            else if (layoutLine.hasCursor && layoutLine.cursorPos !== undefined) {",
+		'                const marker = emitCursorMarker ? CURSOR_MARKER : "";',
+		"                const before = displayText.slice(0, layoutLine.cursorPos);",
+		"                const after = displayText.slice(layoutLine.cursorPos);",
+		"                displayText = before + marker + after;",
+		"            }",
+		"            // Calculate padding based on actual visible width",
+		'            const padding = " ".repeat(Math.max(0, contentWidth - lineVisibleWidth));',
+		"            const renderedLine = `${leftPadding}${displayText}${padding}${rightPadding}`;",
+		"            result.push(bgColor ? applyBackgroundToLine(renderedLine, width, bgColor) : renderedLine);",
+		"        }",
+		"        // Render bottom padding row. When background fill is active, mimic the user-message block",
+		"        // instead of the stock editor chrome.",
+		"        const linesBelow = layoutLines.length - (this.scrollOffset + visibleLines.length);",
+		"        if (bgColor) {",
+		"            if (linesBelow > 0) {",
+		"                const indicator = `  ↓ ${linesBelow} more`;",
+		"                result.push(applyBackgroundToLine(indicator, width, bgColor));",
+		"            }",
+		"            else {",
+		'                result.push(applyBackgroundToLine("", width, bgColor));',
+		"            }",
+		"        }",
+		"        else if (linesBelow > 0) {",
+		"            const indicator = `─── ↓ ${linesBelow} more `;",
+		"            const bottomLine = renderBorderLine(indicator);",
+		"            result.push(bottomLine);",
+		"        }",
+		"        else {",
+		"            const bottomLine = horizontal.repeat(width);",
+		"            result.push(bottomLine);",
+		"        }",
+		"        // Add autocomplete list if active",
+		"        if (this.autocompleteState && this.autocompleteList) {",
+		"            const autocompleteResult = this.autocompleteList.render(contentWidth);",
+		"            for (const line of autocompleteResult) {",
+		"                const lineWidth = visibleWidth(line);",
+		'                const linePadding = " ".repeat(Math.max(0, contentWidth - lineWidth));',
+		"                const autocompleteLine = `${leftPadding}${line}${linePadding}${rightPadding}`;",
+		"                result.push(bgColor ? applyBackgroundToLine(autocompleteLine, width, bgColor) : autocompleteLine);",
+		"            }",
+		"        }",
+		"        return result;",
+		"    }",
+	].join("\n");
+	editorSource = editorSource.replace(
+		/    render\(width\) \{[\s\S]*?\n    handleInput\(data\) \{/m,
+		`${desiredRender}\n    handleInput(data) {`,
+	);
+	writeFileSync(editorPath, editorSource, "utf8");
+}
+
+if (existsSync(webAccessPath)) {
+	const source = readFileSync(webAccessPath, "utf8");
+	if (source.includes('pi.registerCommand("search",')) {
+		writeFileSync(
+			webAccessPath,
+			source.replace('pi.registerCommand("search",', 'pi.registerCommand("web-results",'),
+			"utf8",
+		);
+	}
+}
+
+if (existsSync(sessionSearchIndexerPath)) {
+	const source = readFileSync(sessionSearchIndexerPath, "utf8");
+	const original = 'const sessionsDir = path.join(os.homedir(), ".pi", "agent", "sessions");';
+	const replacement =
+		'const sessionsDir = process.env.FEYNMAN_SESSION_DIR ?? process.env.PI_SESSION_DIR ?? path.join(os.homedir(), ".pi", "agent", "sessions");';
+	if (source.includes(original)) {
+		writeFileSync(sessionSearchIndexerPath, source.replace(original, replacement), "utf8");
+	}
+}
+
+if (existsSync(piMemoryPath)) {
+	let source = readFileSync(piMemoryPath, "utf8");
+	const memoryOriginal = 'const MEMORY_DIR = join(homedir(), ".pi", "memory");';
+	const memoryReplacement =
+		'const MEMORY_DIR = process.env.FEYNMAN_MEMORY_DIR ?? process.env.PI_MEMORY_DIR ?? join(homedir(), ".pi", "memory");';
+	if (source.includes(memoryOriginal)) {
+		source = source.replace(memoryOriginal, memoryReplacement);
+	}
+	const execOriginal = 'const result = await pi.exec("pi", ["-p", prompt, "--print"], {';
+	const execReplacement = [
+		'const execBinary = process.env.FEYNMAN_NODE_EXECUTABLE || process.env.FEYNMAN_EXECUTABLE || "pi";',
+		'      const execArgs = process.env.FEYNMAN_BIN_PATH',
+		'        ? [process.env.FEYNMAN_BIN_PATH, "--prompt", prompt]',
+		'        : ["-p", prompt, "--print"];',
+		'      const result = await pi.exec(execBinary, execArgs, {',
+	].join("\n");
+	if (source.includes(execOriginal)) {
+		source = source.replace(execOriginal, execReplacement);
+	}
+	writeFileSync(piMemoryPath, source, "utf8");
+}

package/skills/agentcomputer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: agentcomputer
+description: Delegate research tasks to remote Agent Computer machines for cloud execution. Manages machine discovery, remote agent sessions, task delegation, progress monitoring, result retrieval, and ACP bridging via the aicomputer CLI.
+allowed-tools: Bash(npm:*), Bash(npx aicomputer@latest:*), Bash(aicomputer:*), Bash(computer:*)
+---
+
+# Agent Computer
+
+Use Agent Computer to run Feynman research workflows on remote cloud machines when local compute is insufficient or when tasks should run unattended.
+
+## When to use
+
+- A research task needs GPU, large memory, or long-running compute
+- `/autoresearch` or `/deepresearch` should run unattended in the cloud
+- The user explicitly asks to delegate work to a remote machine
+- An experiment loop would take hours and should not block the local session
+
+## Prerequisites
+
+The `aicomputer` CLI must be installed and authenticated:
+
+```bash
+if command -v computer >/dev/null 2>&1; then
+  COMPUTER=computer
+elif command -v aicomputer >/dev/null 2>&1; then
+  COMPUTER=aicomputer
+else
+  npm install -g aicomputer
+  COMPUTER=computer
+fi
+$COMPUTER whoami || $COMPUTER login
+```
+
+## Fleet control
+
+### Discover machines and agents
+
+```bash
+$COMPUTER ls --json
+$COMPUTER agent agents <machine> --json
+```
+
+### Sessions
+
+Create, reuse, and manage named sessions on a machine:
+
+```bash
+$COMPUTER agent sessions new <machine> --agent claude --name research --json
+$COMPUTER agent sessions list <machine> --json
+$COMPUTER agent status <machine> --session <session_id> --json
+```
+
+### Prompting and monitoring
+
+```bash
+$COMPUTER agent prompt <machine> "<task>" --agent claude --name research
+$COMPUTER agent watch <machine> --session <session_id>
+```
+
+### Stopping and cleanup
+
+```bash
+$COMPUTER agent cancel <machine> --session <session_id> --json
+$COMPUTER agent interrupt <machine> --session <session_id> --json
+$COMPUTER agent close <machine> --session <session_id>
+```
+
+## Research delegation workflow
+
+1. Pick a machine: `$COMPUTER ls --json`
+2. Create a session: `$COMPUTER agent sessions new <machine> --agent claude --name research --json`
+3. Send a self-contained research prompt:
+
+```bash
+$COMPUTER agent prompt <machine> \
+  "Run a deep research workflow on <topic>. Write all outputs to /workspace/outputs/. When done, write a summary to /workspace/outputs/summary.md." \
+  --agent claude --name research
+```
+
+4. Monitor: `$COMPUTER agent watch <machine> --session <session_id>`
+5. Retrieve: `$COMPUTER agent prompt <machine> "cat /workspace/outputs/summary.md" --session <session_id>`
+6. Clean up: `$COMPUTER agent close <machine> --session <session_id>`
+
+## ACP bridge
+
+Expose a remote machine agent as a local ACP-compatible stdio process:
+
+```bash
+$COMPUTER acp serve <machine> --agent claude --name research
+```
+
+This lets local ACP clients (including Feynman's subagents) talk to a remote agent as if it were local. Keep the bridge process running; reconnect by restarting the command with the same session name.
+
+## Session naming
+
+Use short stable names that match the task:
+
+- `research` — general research delegation
+- `experiment` — autoresearch loops
+- `review` — verification passes
+- `literature` — literature sweeps
+
+Reuse the same name when continuing the same line of work.
+
+## References
+
+- [CLI cheatsheet](references/cli-cheatsheet.md) — full command reference
+- [ACP flow](references/acp-flow.md) — protocol details for the ACP bridge

package/skills/agentcomputer/references/acp-flow.md

@@ -0,0 +1,23 @@
+# ACP Flow
+
+The `computer acp serve` bridge makes a remote machine agent look like a local ACP server over stdio.
+
+## Basic shape
+
+1. The local client starts `computer acp serve <machine> --agent <agent> --name <session>`.
+2. The bridge handles ACP initialization on stdin/stdout.
+3. The bridge maps ACP session operations onto Agent Computer session APIs.
+4. Remote session updates are streamed back as ACP `session/update` notifications.
+
+## Good commands
+
+```bash
+computer acp serve my-box --agent claude --name research
+computer acp serve gpu-worker --agent claude --name experiment
+```
+
+## Recommended client behavior
+
+- Reuse a stable session name when reconnecting.
+- Treat the bridge as the single local command for remote-agent interaction.
+- Use the normal `computer agent ...` commands outside ACP when you need manual inspection or cleanup.

package/skills/agentcomputer/references/cli-cheatsheet.md

@@ -0,0 +1,68 @@
+# CLI Cheatsheet
+
+## Authentication
+
+```bash
+computer whoami
+computer login
+computer claude-login     # install Claude credentials on a machine
+computer codex-login      # install Codex credentials on a machine
+```
+
+## Machine discovery
+
+```bash
+computer ls --json
+computer fleet status --json
+```
+
+## Agent discovery
+
+```bash
+computer agent agents <machine> --json
+```
+
+## Sessions
+
+```bash
+computer agent sessions list <machine> --json
+computer agent sessions new <machine> --agent claude --name research --json
+computer agent status <machine> --session <session_id> --json
+```
+
+## Prompting
+
+```bash
+computer agent prompt <machine> "run the experiment" --agent claude --name research
+computer agent prompt <machine> "continue" --session <session_id>
+```
+
+## Streaming and control
+
+```bash
+computer agent watch <machine> --session <session_id>
+computer agent cancel <machine> --session <session_id> --json
+computer agent interrupt <machine> --session <session_id> --json
+computer agent close <machine> --session <session_id>
+```
+
+## ACP bridge
+
+```bash
+computer acp serve <machine> --agent claude --name research
+```
+
+## Machine lifecycle
+
+```bash
+computer create my-box
+computer open my-box
+computer open my-box --terminal
+computer ssh my-box
+```
+
+## Good defaults
+
+- Prefer machine handles over machine ids when both are available.
+- Prefer `--name` for human-meaningful persistent sessions.
+- Prefer `--json` when another program or agent needs to read the result.

package/skills/autoresearch/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: autoresearch
+description: Autonomous experiment loop that tries ideas, measures results, keeps what works, and discards what doesn't. Use when the user asks to optimize a metric, run an experiment loop, improve performance iteratively, or automate benchmarking.
+---
+
+# Autoresearch
+
+Run the `/autoresearch` workflow. Read the prompt template at `prompts/autoresearch.md` for the full procedure.
+
+Tools used: `init_experiment`, `run_experiment`, `log_experiment` (from pi-autoresearch)
+
+Session files: `autoresearch.md`, `autoresearch.sh`, `autoresearch.jsonl`

package/skills/deep-research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: deep-research
+description: Run a thorough, source-heavy investigation on any topic. Use when the user asks for deep research, a comprehensive analysis, an in-depth report, or a multi-source investigation. Produces a cited research brief with provenance tracking.
+---
+
+# Deep Research
+
+Run the `/deepresearch` workflow. Read the prompt template at `prompts/deepresearch.md` for the full procedure.
+
+Agents used: `researcher`, `verifier`, `reviewer`
+
+Output: cited brief in `outputs/` with `.provenance.md` sidecar.

package/skills/docker/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: docker
+description: Execute research code inside isolated Docker containers for safe replication, experiments, and benchmarks. Use when the user selects Docker as the execution environment or asks to run code safely, in isolation, or in a sandbox.
+allowed-tools: Bash(docker:*)
+---
+
+# Docker Sandbox
+
+Run research code inside Docker containers while Feynman stays on the host. The container gets the project files, runs the commands, and results sync back.
+
+## When to use
+
+- User selects "Docker Sandbox" as the execution environment in `/replicate` or `/autoresearch`
+- Running untrusted code from a paper's repository
+- Experiments that install packages or modify system state
+- Any time the user asks to run something "safely" or "isolated"
+
+## How it works
+
+1. Build or pull an appropriate base image for the research code
+2. Mount the project directory into the container
+3. Run experiment commands inside the container
+4. Results write back to the mounted directory
+
+## Running commands in a container
+
+For Python research code (most common):
+
+```bash
+docker run --rm -v "$(pwd)":/workspace -w /workspace python:3.11 bash -c "
+  pip install -r requirements.txt &&
+  python train.py
+"
+```
+
+For projects with a Dockerfile:
+
+```bash
+docker build -t feynman-experiment .
+docker run --rm -v "$(pwd)/results":/workspace/results feynman-experiment
+```
+
+For GPU workloads:
+
+```bash
+docker run --rm --gpus all -v "$(pwd)":/workspace -w /workspace pytorch/pytorch:latest bash -c "
+  pip install -r requirements.txt &&
+  python train.py
+"
+```
+
+## Choosing the base image
+
+| Research type | Base image |
+| --- | --- |
+| Python ML/DL | `pytorch/pytorch:latest` or `tensorflow/tensorflow:latest-gpu` |
+| Python general | `python:3.11` |
+| Node.js | `node:20` |
+| R / statistics | `rocker/r-ver:4` |
+| Julia | `julia:1.10` |
+| Multi-language | `ubuntu:24.04` with manual installs |
+
+## Persistent containers
+
+For iterative experiments (like `/autoresearch`), create a named container instead of `--rm`. Choose a descriptive name based on the experiment:
+
+```bash
+docker create --name <name> -v "$(pwd)":/workspace -w /workspace python:3.11 tail -f /dev/null
+docker start <name>
+docker exec <name> bash -c "pip install -r requirements.txt"
+docker exec <name> bash -c "python train.py"
+```
+
+This preserves installed packages across iterations. Clean up with:
+
+```bash
+docker stop <name> && docker rm <name>
+```
+
+## Notes
+
+- The mounted workspace syncs results back to the host automatically
+- Containers are network-enabled by default — add `--network none` for full isolation
+- For GPU access, Docker must be configured with the NVIDIA Container Toolkit

package/skills/jobs/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: jobs
+description: Inspect active background research work including running processes, scheduled follow-ups, and pending tasks. Use when the user asks what's running, checks on background work, or wants to see scheduled jobs.
+---
+
+# Jobs
+
+Run the `/jobs` workflow. Read the prompt template at `prompts/jobs.md` for the full procedure.
+
+Shows active `pi-processes`, scheduled `pi-schedule-prompt` entries, and running subagent tasks.

package/skills/literature-review/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: literature-review
+description: Run a literature review using paper search and primary-source synthesis. Use when the user asks for a lit review, paper survey, state of the art, or academic landscape summary on a research topic.
+---
+
+# Literature Review
+
+Run the `/lit` workflow. Read the prompt template at `prompts/lit.md` for the full procedure.
+
+Agents used: `researcher`, `verifier`, `reviewer`
+
+Output: literature review in `outputs/` with `.provenance.md` sidecar.

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

@@ -0,0 +1,12 @@
+---
+name: paper-code-audit
+description: Compare a paper's claims against its public codebase. Use when the user asks to audit a paper, check code-claim consistency, verify reproducibility of a specific paper, or find mismatches between a paper and its implementation.
+---
+
+# Paper-Code Audit
+
+Run the `/audit` workflow. Read the prompt template at `prompts/audit.md` for the full procedure.
+
+Agents used: `researcher`, `verifier`
+
+Output: audit report in `outputs/`.