ywatanabe1989 · ywatanabe1989 · Mar 14, 2026 · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026
diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,7 @@ GITIGNORED
 singularity
 
 ## Logs and temporary files
+logs/
 slurm_logs/
 coverage_report.txt
 /coverage-*.json
@@ -23,6 +24,7 @@ coverage_report.txt
 htmlcov/
 
 ## Sensitive files
+.env.d/
 .env.zenrows
 .env.local
 .env.*.local

diff --git a/README.md b/README.md
@@ -4,12 +4,16 @@
 !-- File: /home/ywatanabe/proj/scitex-python/README.md
 !-- --- -->
 
+# SciTeX (<code>scitex</code>)
+
 <p align="center">
   <a href="https://scitex.ai">
     <img src="docs/assets/images/scitex-logo-blue-cropped.png" alt="SciTeX" width="400">
   </a>
 </p>
 
+<p align="center"><b>Modular Python Toolkit for Researchers and AI Agents</b></p>
+
 <p align="center">
   <a href="https://badge.fury.io/py/scitex"><img src="https://badge.fury.io/py/scitex.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/scitex/"><img src="https://img.shields.io/pypi/pyversions/scitex.svg" alt="Python Versions"></a>
@@ -18,98 +22,81 @@
 </p>
 
 <p align="center">
-  <a href="https://scitex.ai">scitex.ai</a> · <a href="https://scitex-python.readthedocs.io">Read the Docs</a> · <code>pip install scitex</code>
+  <a href="https://scitex-python.readthedocs.io">Full Documentation</a> · <code>pip install scitex</code>
 </p>
 
 ---
 
-# SciTeX — Modular Python Toolkit for Researchers and AI Agents
+## Problem
 
->Four Freedoms for Research
->
->0. The freedom to **run** your research anywhere — your machine, your terms.
->1. The freedom to **study** how every step works — from raw data to final manuscript.
->2. The freedom to **redistribute** your workflows, not just your papers.
->3. The freedom to **modify** any module and share improvements with the community.
->
->AGPL-3.0 — because research infrastructure deserves the same freedoms as the software it runs on.
+Researchers face a fragmented toolchain — literature search, statistical analysis, figure creation, and manuscript writing each require separate tools with incompatible formats. AI agents can automate these steps, but lack a unified interface that connects them into a coherent pipeline.
+
+## Solution
+
+SciTeX provides a **modular Python toolkit** that unifies the research workflow from data to manuscript. Each module (scholar, stats, plt, writer, io) works standalone or together, accessible through Python API, CLI, and MCP (Model Context Protocol) for AI agents. A single `@scitex.session` decorator tracks every parameter, output, and log for full reproducibility.
 
 <p align="center">
     <img src="scripts/assets/workflow_out/workflow.png" alt="SciTeX Ecosystem" width="800">
 </p>
 
-## 🎬 Demo
+<p align="center"><sub><b>Figure 1.</b> SciTeX research pipeline — AI agents orchestrate the full workflow from literature search to manuscript compilation.</sub></p>
+
+## Demo
 
 **40 min, zero human intervention** — AI agent conducts full research pipeline:
 
 > Literature search → Data analysis → Statistics → Figures → 21-page manuscript → Peer review simulation
 
 <p align="center">
-  <a href="https://scitex.ai/demos/watch/scitex-automated-research/" title="▶ Watch full demo at scitex.ai/demos/">
+  <a href="https://scitex.ai/demos/watch/scitex-automated-research/" title="Watch full demo at scitex.ai/demos/">
     <img src="docs/assets/images/scitex-demo.gif" alt="SciTeX Demo" width="800">
   </a>
 </p>
 
-## 📦 Installation
-
+## Installation
 
 ``` bash
-uv pip install scitex          # Core (minimal)
-uv pip install scitex[plt,stats,scholar]  # Typical research setup
-uv pip install scitex[all]     # Recommended: Full installation
+pip install scitex               # Core (minimal)
+pip install scitex[plt,stats,scholar]  # Typical research setup
+pip install scitex[all]          # Recommended: Full installation
 ```
 
-## ⚙️ Configuration
-
-Modular environment configuration via `.env.d/`:
+## Quick Start
 
-<details>
+```python
+import scitex
 
-```bash
-# 1. Copy examples
-cp -r .env.d.examples .env.d
+# Speak to the user
+scitex.audio.speak("Analysis starting")
 
-# 2. Edit with your credentials
-$EDITOR .env.d/
+# Load data and run statistics
+result = scitex.stats.test_ttest_ind(group1, group2, return_as="dataframe")
 
-# 3. Source in shell (~/.bashrc or ~/.zshrc)
-source /path/to/.env.d/entry.src
+# Create a publication-ready figure
+fig, ax = scitex.plt.subplots()
+ax.plot_line(x, y)
+ax.set_xyt("Time (s)", "Amplitude", "Signal")
+scitex.io.save(fig, "figure.png")  # Saves figure.png + figure.csv
 ```
 
-**Structure:**
-```
-.env.d/
-├── entry.src              # Single entry point
-├── 00_scitex.env          # Base settings (SCITEX_DIR)
-├── 00_crossref-local.env  # CrossRef database
-├── 00_figrecipe.env       # Plotting config
-├── 01_scholar.env         # OpenAthens, API keys
-├── 01_audio.env           # TTS backends
-└── ...                    # Per-module configs
-```
-
-→ **[Full configuration reference](./.env.d.examples/README.md)**
-
-</details>
-
 ## Three Interfaces
 
 <details>
-<summary><strong>🐍 Python API for Humans and AI Agents</strong></summary>
+<summary><strong>Python API</strong></summary>
 
 <br>
 
-**`@stx.session`** — Reproducible Experiment Tracking
+**`@scitex.session`** — Reproducible Experiment Tracking
 
 ```python
-import scitex as stx
+import scitex
 
-@stx.session
+@scitex.session
 def main(filename="demo.jpg"):
-    fig, ax = stx.plt.subplots()
+    fig, ax = scitex.plt.subplots()
     ax.plot_line(t, signal)
     ax.set_xyt("Time (s)", "Amplitude", "Title")
-    stx.io.save(fig, filename)
+    scitex.io.save(fig, filename)
     return 0
 ```
 
@@ -122,27 +109,27 @@ script_out/FINISHED_SUCCESS/2025-01-08_12-30-00_AbC1/
 └── logs/{stdout,stderr}.log    # Execution logs
 ```
 
-**`stx.io`** — Universal File I/O (30+ formats)
+**`scitex.io`** — Universal File I/O (30+ formats)
 
 ```python
-stx.io.save(df, "output.csv")
-stx.io.save(fig, "output.jpg")
-df = stx.io.load("output.csv")
+scitex.io.save(df, "output.csv")
+scitex.io.save(fig, "output.jpg")
+df = scitex.io.load("output.csv")
 ```
 
-**`stx.stats`** — Publication-Ready Statistics (23 tests)
+**`scitex.stats`** — Publication-Ready Statistics (23 tests)
 
 ```python
-result = stx.stats.test_ttest_ind(group1, group2, return_as="dataframe")
+result = scitex.stats.test_ttest_ind(group1, group2, return_as="dataframe")
 # Includes: p-value, effect size, CI, normality check, power
 ```
 
-→ **[Full module status](./docs/MODULE_STATUS.md)**
+> **[Full module status](./docs/MODULE_STATUS.md)**
 
 </details>
 
 <details>
-<summary><strong>🖥️ CLI Commands for Humans and AI Agents</strong></summary>
+<summary><strong>CLI Commands</strong></summary>
 
 <br>
 
@@ -160,16 +147,16 @@ scitex mcp list-tools                # List all MCP tools (120+ tools)
 scitex introspect api scitex.stats   # List APIs for specific module
 ```
 
-→ **[Full CLI reference](./docs/CLI_COMMANDS.md)**
+> **[Full CLI reference](./docs/CLI_COMMANDS.md)**
 
 </details>
 
 <details>
-<summary><strong>🔧 MCP Tools — 120+ tools for AI Agents</strong></summary>
+<summary><strong>MCP Server — for AI Agents</strong></summary>
 
 <br>
 
-Turn AI agents into autonomous scientific researchers.
+Turn AI agents into autonomous scientific researchers via the [Model Context Protocol](https://modelcontextprotocol.io/).
 
 **Typical workflow**: Scholar (find papers) → Stats (analyze) → Plt (visualize) → Writer (manuscript) → Capture (verify)
 
@@ -192,7 +179,11 @@ Turn AI agents into autonomous scientific researchers.
 | ui | 5 | Notifications |
 | linter | 3 | Code pattern checking |
 
-**Claude Desktop** (`~/.config/claude/claude_desktop_config.json`):
+<sub><b>Table 1.</b> 120+ MCP tools organized by category. All tools accept JSON parameters and return structured results.</sub>
+
+#### Claude Code Setup
+
+Add `.mcp.json` to your project root. Use `SCITEX_ENV_SRC` to load all configuration from a `.src` file — this keeps `.mcp.json` static across environments:
 
 ```json
 {
@@ -208,11 +199,67 @@ Turn AI agents into autonomous scientific researchers.
 }
 ```
 
-→ **[Full MCP tool reference](./docs/MCP_TOOLS.md)**
+Then switch environments via your shell profile:
+
+```bash
+# Local machine
+export SCITEX_ENV_SRC=~/.scitex/scitex/local.src
+
+# Remote server
+export SCITEX_ENV_SRC=~/.scitex/scitex/remote.src
+```
+
+Generate a template `.src` file:
+
+```bash
+scitex env-template -o ~/.scitex/scitex/local.src
+```
+
+Or install globally:
+
+```bash
+scitex mcp installation
+```
+
+> **[Full MCP tool reference](./docs/MCP_TOOLS.md)**
 
 </details>
 
-## 🧩 Standalone Packages
+<details>
+<summary><strong>Configuration</strong></summary>
+
+<br>
+
+Modular environment configuration via `.env.d/`:
+
+```bash
+# 1. Copy examples
+cp -r .env.d.examples .env.d
+
+# 2. Edit with your credentials
+$EDITOR .env.d/
+
+# 3. Source in shell (~/.bashrc or ~/.zshrc)
+source /path/to/.env.d/entry.src
+```
+
+**Structure:**
+```
+.env.d/
+├── entry.src              # Single entry point
+├── 00_scitex.env          # Base settings (SCITEX_DIR)
+├── 00_crossref-local.env  # CrossRef database
+├── 00_figrecipe.env       # Plotting config
+├── 01_scholar.env         # OpenAthens, API keys
+├── 01_audio.env           # TTS backends
+└── ...                    # Per-module configs
+```
+
+> **[Full configuration reference](./.env.d.examples/README.md)**
+
+</details>
+
+## Standalone Packages
 
 SciTeX integrates several standalone packages that can be used independently:
 
@@ -236,21 +283,29 @@ pip install scitex[plt]      # Or via scitex
 
 </details>
 
-## 📖 Documentation
+## Part of SciTeX
+
+SciTeX is an open-source research automation platform at [scitex.ai](https://scitex.ai).
 
 - **[Read the Docs](https://scitex-python.readthedocs.io/)**: Complete API reference
 - **[Examples](./examples/)**: Usage examples and demonstrations
+- **[Contributing](CONTRIBUTING.md)**: We welcome contributions
 
-## 🤝 Contributing
+The SciTeX system follows the Four Freedoms for Research below, inspired by [the Free Software Definition](https://www.gnu.org/philosophy/free-sw.en.html):
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).
+>Four Freedoms for Research
+>
+>0. The freedom to **run** your research anywhere — your machine, your terms.
+>1. The freedom to **study** how every step works — from raw data to final manuscript.
+>2. The freedom to **redistribute** your workflows, not just your papers.
+>3. The freedom to **modify** any module and share improvements with the community.
+>
+>AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.
 
 ---
 
 <p align="center">
   <a href="https://scitex.ai" target="_blank"><img src="docs/assets/images/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
-  <br>
-  AGPL-3.0
 </p>
 
-<!-- EOF -->
+<!-- EOF -->