### Install and setup ScholarAIO

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/index.md

Install the full ScholarAIO package and run the setup command. This is the quick start for using ScholarAIO.

```bash
pip install "scholaraio[full]"
scholaraio setup
```

--------------------------------

### Install and setup ScholarAIO

Source: https://github.com/zimoliao/scholaraio/blob/main/README.md

Clones the repository, installs the package in editable mode, and runs the setup command. Use this to get started with ScholarAIO.

```bash
git clone https://github.com/ZimoLiao/scholaraio.git
cd scholaraio
pip install -e .
scholaraio setup
```

--------------------------------

### Run scholaraio setup

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/installation.md

Run the interactive setup wizard to configure API keys and directories after installation.

```bash
scholaraio setup
```

--------------------------------

### Clone and Setup Development Environment

Source: https://github.com/zimoliao/scholaraio/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies in editable mode, initialize pre-commit hooks, and verify the installation by running tests.

```bash
# Clone and install
git clone https://github.com/zimoliao/scholaraio.git
cd scholaraio
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest
```

--------------------------------

### One-time setup: clone and install ScholarAIO

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/agent-setup.md

Clone the repository to a stable location, install with full extras, and run the setup command. This is the first step for manual fallback.

```bash
git clone https://github.com/ZimoLiao/scholaraio.git ~/.codex/scholaraio
cd ~/.codex/scholaraio
pip install -e ".[full]"
scholaraio setup
```

--------------------------------

### Setup and agent integration commands

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/guide/cli-reference.md

Lists the setup and agent integration commands. `setup` runs the interactive wizard; `setup check` reports status; `setup agent` previews integration; `setup agent --apply` performs automatic steps (restart the agent session afterward); `setup agent check` reports state without changes; `--target-project` writes project-local wrappers with absolute paths.

```text
scholaraio setup
scholaraio setup check
scholaraio setup agent
scholaraio setup agent --apply
scholaraio setup agent check
```

--------------------------------

### Clone and set up ScholarAIO repository

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/agent-setup.md

Clones the repository, installs the package with full extras, and runs the setup command. Use this when opening the repository directly for the full project context.

```bash
git clone https://github.com/ZimoLiao/scholaraio.git
cd scholaraio
pip install -e ".[full]"
scholaraio setup
```

--------------------------------

### Install scholaraio from PyPI

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/installation.md

Install the core package from PyPI, or use the full installation to include embed, topics, import, pdf, and office extras.

```bash
pip install scholaraio
```

```bash
pip install "scholaraio[full]"
```

--------------------------------

### Start the WebUI with scholaraio gui

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/guide/library-webui.md

Starts the ScholarAIO Library WebUI. By default it listens on 127.0.0.1:8765 and opens the page in your browser.

```bash
scholaraio gui
```

--------------------------------

### Check setup status

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/installation.md

Check what is already configured. This is the most complete initial diagnostic surface, covering core setup items and optional advanced items.

```bash
scholaraio setup check
```

--------------------------------

### Install scholaraio from source

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/installation.md

Clone the repository and install in editable mode for core only, or with the full extras (embed, topics, import, pdf, office). Use this path to inspect, edit, or contribute to the codebase.

```bash
git clone https://github.com/zimoliao/scholaraio.git
cd scholaraio
```

```bash
pip install -e .
```

```bash
pip install -e ".[full]"
```

--------------------------------

### Example ScholarAIO slash-commands

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/agent-setup.md

After installation, start a new Claude Code session in your target project. These slash-commands are available under the /scholaraio:* namespace.

```text
/scholaraio:search
/scholaraio:show
/scholaraio:workspace
```

--------------------------------

### Windows: clone and install ScholarAIO

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/agent-setup.md

Clone the repository on Windows using PowerShell, install with full extras, and run setup.

```powershell
git clone https://github.com/ZimoLiao/scholaraio.git "$env:USERPROFILE\.codex\scholaraio"
cd "$env:USERPROFILE\.codex\scholaraio"
pip install -e ".[full]"
scholaraio setup
```

--------------------------------

### PDF delivery object from GET /api/capabilities

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/superpowers/specs/2026-07-11-library-webui-clean-pdf-delivery-design.md

Example response from GET /api/capabilities showing the PDF delivery object. The mode field is either native or download, and target is windows, host, or client. The label provides the user-facing text for the action.

```json
{
  "pdf_delivery": {
    "mode": "native",
    "target": "windows",
    "label": "Open in default viewer",
    "reason": ""
  }
}
```

--------------------------------

### Prepare and check PDF desktop acceptance fixtures

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/design-docs/wsl-pdf-edit-mirror.md

Prepare an isolated fixture library for the real desktop acceptance test, then run the check after manual annotation. The prepare command creates small and 128 MiB valid PDFs, never launches a viewer itself, and refuses an existing fixture root. The check requires both files to match, differ from the original fixture, and report in_sync.

```bash
python scripts/validation/pdf_desktop_acceptance.py prepare \
  --root workspace/_system/output/pdf-desktop-acceptance
```

```bash
python scripts/validation/pdf_desktop_acceptance.py check \
  --root workspace/_system/output/pdf-desktop-acceptance
```

--------------------------------

### Rehearsal skeleton: build roots, migrate, verify, cleanup

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/internal/validation/upgrade-validation-matrix.md

Suggested command skeleton for local-clone validation. Starts by copying config and data into disposable rehearsal roots, seeds a fresh-layout root for Gate G1, then runs baseline migration status/plan/verify, migrates each store with `migrate run --store ... --migration-id mig-<stamp> --confirm` followed by `migrate verify`, rebuilds index and embeddings, and finishes with cleanup. Uses `python -m scholaraio.cli` instead of `scholaraio` when the editable install is not active. This is only the migration skeleton; feature smokes and evidence capture are still required around it.

```bash
# 1. build disposable rehearsal roots
cp ../scholaraio/config.yaml workspace/release-validation/<stamp>/legacy-root/config.yaml
# optional only when provider-backed canaries are intentionally in scope
# cp ../scholaraio/config.local.yaml workspace/release-validation/<stamp>/legacy-root/config.local.yaml
cp -R ../scholaraio/data workspace/release-validation/<stamp>/legacy-root/data
cp -R ../scholaraio/workspace workspace/release-validation/<stamp>/legacy-root/workspace

# 1b. seed a fresh-layout root for Gate G1
cp ../scholaraio/config.yaml workspace/release-validation/<stamp>/fresh-root/config.yaml
mkdir -p workspace/release-validation/<stamp>/fresh-root/data/libraries
cp -R workspace/release-validation/<stamp>/migrated-root/data/libraries/papers \
  workspace/release-validation/<stamp>/fresh-root/data/libraries/papers
cp -R workspace/release-validation/<stamp>/migrated-root/data/libraries/explore \
  workspace/release-validation/<stamp>/fresh-root/data/libraries/explore
cp -R workspace/release-validation/<stamp>/migrated-root/data/libraries/toolref \
  workspace/release-validation/<stamp>/fresh-root/data/libraries/toolref
cp workspace/release-validation/<stamp>/migrated-root/data/index.db \
  workspace/release-validation/<stamp>/fresh-root/data/index.db

# 2. baseline
export SCHOLARAIO_CONFIG=/path/to/legacy-root/config.yaml
python -m scholaraio.cli migrate status
python -m scholaraio.cli migrate plan --migration-id mig-<stamp>
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>

# 3. migrate store by store
python -m scholaraio.cli migrate upgrade --migration-id mig-<stamp> --confirm

# 3b. lower-level equivalent for debugging store-by-store behavior
python -m scholaraio.cli migrate run --store citation_styles --migration-id mig-<stamp> --confirm
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>
python -m scholaraio.cli migrate run --store toolref --migration-id mig-<stamp> --confirm
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>
python -m scholaraio.cli migrate run --store explore --migration-id mig-<stamp> --confirm
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>
python -m scholaraio.cli migrate run --store proceedings --migration-id mig-<stamp> --confirm
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>
python -m scholaraio.cli migrate run --store spool --migration-id mig-<stamp> --confirm
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>
python -m scholaraio.cli migrate run --store papers --migration-id mig-<stamp> --confirm
python -m scholaraio.cli index --rebuild
python -m scholaraio.cli embed --rebuild
python -m scholaraio.cli migrate verify --migration-id mig-<stamp>

# 4. cleanup rehearsal
python -m scholaraio.cli migrate cleanup --migration-id mig-<stamp>
python -m scholaraio.cli migrate cleanup --migration-id mig-<stamp> --confirm
```

--------------------------------

### Upgrade from 2.0.0 Beta 1: Force reinstall stable

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/upgrading-to-2.0.md

Replace the beta package explicitly because pip may consider the stable artifact equal to an installed beta. Then run pip check and setup check.

```bash
python -m pip install --force-reinstall --no-deps "scholaraio==2.0.0"
python -m pip check
scholaraio setup check
```

--------------------------------

### Common scoped runs for agent setup

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/getting-started/agent-setup.md

Examples of scoped runs: register Codex/OpenClaw global skills, prepare project-local wrappers for all hosts, and inspect status in Chinese. Use --apply to modify files.

```bash
# Codex / OpenClaw global skill registration plus shell config
scholaraio setup agent --agent codex --apply

# Prepare project-local wrappers for supported hosts
scholaraio setup agent --all --target-project ~/repos/my-software-project --apply

# Inspect status in Chinese
scholaraio setup agent check --lang zh
```

--------------------------------

### Run scholaraio insights with default and custom day ranges

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/guide/insights.md

Shows basic usage of the `scholaraio insights` command. The default behavior uses the metrics store at `data/state/metrics/metrics.db` for new instances, while existing `data/metrics.db` installations are auto-discovered. The `--days` flag allows specifying the number of days to summarize, with examples for 7 and 30 days.

```bash
scholaraio insights
scholaraio insights --days 7
scholaraio insights --days 30
```

--------------------------------

### Manually Install Nature Skills Locally

Source: https://github.com/zimoliao/scholaraio/blob/main/docs/guide/nature-workflow-quickstart.md

Manually installs Nature Skills locally by cloning the upstream repository and copying whole skill directories into ~/.codex/skills. Copying only SKILL.md is not enough; the entire directory must be copied.

```bash
git clone https://github.com/Yuan1z0825/nature-skills.git
cd nature-skills
mkdir -p ~/.codex/skills
cp -R skills/_shared ~/.codex/skills/
for d in skills/nature-*; do
  cp -R "$d" ~/.codex/skills/
done
```