@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/phylogenetics/references/iqtree_inference.md

@@ -1,181 +0,0 @@
-# IQ-TREE 2 Phylogenetic Inference Reference
-
-## Basic Command Syntax
-
-```bash
-iqtree2 -s alignment.fasta --prefix output -m TEST -B 1000 -T AUTO --redo
-```
-
-## Key Parameters
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-s` | Input alignment file | Required |
-| `--prefix` | Output file prefix | alignment name |
-| `-m` | Substitution model (or TEST) | GTR+G |
-| `-B` | Ultrafast bootstrap replicates | Off |
-| `-b` | Standard bootstrap replicates (slow) | Off |
-| `-T` | Number of threads (or AUTO) | 1 |
-| `-o` | Outgroup taxa name(s) | None (unrooted) |
-| `--redo` | Overwrite existing results | Off |
-| `-alrt` | SH-aLRT test replicates | Off |
-
-## Model Selection
-
-```bash
-# Full model testing (automatically selects best model)
-iqtree2 -s alignment.fasta -m TEST --prefix test_run -B 1000 -T 4
-
-# Specify model explicitly
-iqtree2 -s alignment.fasta -m GTR+G4 --prefix gtr_run -B 1000
-
-# Protein sequences
-iqtree2 -s protein.fasta -m TEST --prefix prot_tree -B 1000
-
-# Codon-based analysis
-iqtree2 -s codon.fasta -m GY --prefix codon_tree -B 1000
-```
-
-## Bootstrapping Methods
-
-### Ultrafast Bootstrap (UFBoot, recommended)
-```bash
-iqtree2 -s alignment.fasta -B 1000  # 1000 replicates
-# Values ≥95 are reliable
-# ~10× faster than standard bootstrap
-```
-
-### Standard Bootstrap
-```bash
-iqtree2 -s alignment.fasta -b 100  # 100 replicates (very slow)
-```
-
-### SH-aLRT Test (fast alternative)
-```bash
-iqtree2 -s alignment.fasta -alrt 1000 -B 1000  # Both SH-aLRT and UFBoot
-# SH-aLRT ≥80 AND UFBoot ≥95 = well-supported branch
-```
-
-## Branch Support Interpretation
-
-| Bootstrap Value | Interpretation |
-|----------------|----------------|
-| ≥ 95 | Well-supported (strongly supported) |
-| 70–94 | Moderately supported |
-| 50–69 | Weakly supported |
-| < 50 | Unreliable (not supported) |
-
-## Output Files
-
-| File | Description |
-|------|-------------|
-| `{prefix}.treefile` | Best ML tree in Newick format |
-| `{prefix}.iqtree` | Full analysis report |
-| `{prefix}.log` | Computation log |
-| `{prefix}.contree` | Consensus tree from bootstrap |
-| `{prefix}.splits.nex` | Network splits |
-| `{prefix}.bionj` | BioNJ starting tree |
-| `{prefix}.model.gz` | Saved model parameters |
-
-## Advanced Analyses
-
-### Molecular Clock (Dating)
-
-```bash
-# Temporal analysis with sampling dates
-iqtree2 -s alignment.fasta -m GTR+G \
-        --date dates.tsv \           # Tab-separated: taxon_name  YYYY-MM-DD
-        --clock-test \               # Test for clock-like evolution
-        --date-CI 95 \              # 95% CI for node dates
-        --prefix dated_tree
-```
-
-### Concordance Factors
-
-```bash
-# Gene concordance factor (gCF) - requires multiple gene alignments
-iqtree2 --gcf gene_trees.nwk \
-        --tree main_tree.treefile \
-        --cf-verbose \
-        --prefix cf_analysis
-```
-
-### Ancestral Sequence Reconstruction
-
-```bash
-iqtree2 -s alignment.fasta -m LG+G4 \
-        -asr \                      # Marginal ancestral state reconstruction
-        --prefix anc_tree
-# Output: {prefix}.state (ancestral sequences per node)
-```
-
-### Partition Model (Multi-Gene)
-
-```bash
-# Create partition file (partitions.txt):
-# DNA, gene1 = 1-500
-# DNA, gene2 = 501-1000
-
-iqtree2 -s concat_alignment.fasta \
-        -p partitions.txt \
-        -m TEST \
-        -B 1000 \
-        --prefix partition_tree
-```
-
-## IQ-TREE Log Parsing
-
-```python
-def parse_iqtree_log(log_file: str) -> dict:
-    """Extract key results from IQ-TREE log file."""
-    results = {}
-    with open(log_file) as f:
-        for line in f:
-            if "Best-fit model" in line:
-                results["best_model"] = line.split(":")[1].strip()
-            elif "Log-likelihood of the tree:" in line:
-                results["log_likelihood"] = float(line.split(":")[1].strip())
-            elif "Number of free parameters" in line:
-                results["free_params"] = int(line.split(":")[1].strip())
-            elif "Akaike information criterion" in line:
-                results["AIC"] = float(line.split(":")[1].strip())
-            elif "Bayesian information criterion" in line:
-                results["BIC"] = float(line.split(":")[1].strip())
-            elif "Total CPU time used" in line:
-                results["cpu_time"] = line.split(":")[1].strip()
-    return results
-
-# Example:
-# results = parse_iqtree_log("output.log")
-# print(f"Best model: {results['best_model']}")
-# print(f"Log-likelihood: {results['log_likelihood']:.2f}")
-```
-
-## Common Issues and Solutions
-
-| Issue | Likely Cause | Solution |
-|-------|-------------|---------|
-| All bootstrap values = 0 | Too few taxa | Need ≥4 taxa for bootstrap |
-| Very long branches | Alignment artifacts | Re-trim alignment; check for outliers |
-| Memory error | Too many sequences | Use FastTree; or reduce `-T` to 1 |
-| Poor model fit | Wrong alphabet | Check nucleotide vs. protein specification |
-| Identical sequences | Duplicate sequences | Remove duplicates before alignment |
-
-## MAFFT Alignment Guide
-
-```bash
-# Accurate (< 200 sequences)
-mafft --localpair --maxiterate 1000 input.fasta > aligned.fasta
-
-# Medium (200-1000 sequences)
-mafft --auto input.fasta > aligned.fasta
-
-# Fast (> 1000 sequences)
-mafft --fftns input.fasta > aligned.fasta
-
-# Very large (> 10000 sequences)
-mafft --retree 1 input.fasta > aligned.fasta
-
-# Using multiple threads
-mafft --thread 8 --auto input.fasta > aligned.fasta
-```

package/skills/phylogenetics/scripts/phylogenetic_analysis.py

@@ -1,272 +0,0 @@
-"""
-Phylogenetic Analysis Pipeline
-===============================
-Complete workflow: MAFFT alignment → IQ-TREE tree → ETE3 visualization.
-
-Requirements:
-    conda install -c bioconda mafft iqtree
-    uv pip install ete3
-
-Usage:
-    python phylogenetic_analysis.py sequences.fasta --type nt --threads 4
-    python phylogenetic_analysis.py proteins.fasta --type aa --fasttree
-"""
-
-import argparse
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-
-def check_dependencies():
-    """Check that required tools are installed."""
-    tools = {
-        "mafft": "conda install -c bioconda mafft",
-        "iqtree2": "conda install -c bioconda iqtree",
-    }
-    missing = []
-    for tool, install_cmd in tools.items():
-        result = subprocess.run(["which", tool], capture_output=True)
-        if result.returncode != 0:
-            missing.append(f"  {tool}: {install_cmd}")
-
-    if missing:
-        print("Missing dependencies:")
-        for m in missing:
-            print(m)
-        sys.exit(1)
-    print("All dependencies found.")
-
-
-def count_sequences(fasta_file: str) -> int:
-    """Count sequences in a FASTA file."""
-    with open(fasta_file) as f:
-        return sum(1 for line in f if line.startswith('>'))
-
-
-def run_mafft(input_fasta: str, output_fasta: str, n_threads: int = 4,
-               method: str = "auto") -> str:
-    """Run MAFFT multiple sequence alignment."""
-    n_seqs = count_sequences(input_fasta)
-    print(f"MAFFT: Aligning {n_seqs} sequences...")
-
-    # Auto-select method based on dataset size
-    if method == "auto":
-        if n_seqs <= 200:
-            cmd = ["mafft", "--localpair", "--maxiterate", "1000",
-                   "--thread", str(n_threads), "--inputorder", input_fasta]
-        elif n_seqs <= 1000:
-            cmd = ["mafft", "--auto", "--thread", str(n_threads),
-                   "--inputorder", input_fasta]
-        else:
-            cmd = ["mafft", "--fftns", "--thread", str(n_threads),
-                   "--inputorder", input_fasta]
-    else:
-        cmd = ["mafft", f"--{method}", "--thread", str(n_threads),
-               "--inputorder", input_fasta]
-
-    with open(output_fasta, 'w') as out:
-        result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)
-
-    if result.returncode != 0:
-        raise RuntimeError(f"MAFFT failed:\n{result.stderr[:500]}")
-
-    print(f"  Alignment complete → {output_fasta}")
-    return output_fasta
-
-
-def run_iqtree(aligned_fasta: str, prefix: str, seq_type: str = "nt",
-                bootstrap: int = 1000, n_threads: int = 4,
-                outgroup: str = None) -> str:
-    """Run IQ-TREE 2 phylogenetic inference."""
-    print(f"IQ-TREE 2: Building maximum likelihood tree...")
-
-    cmd = [
-        "iqtree2",
-        "-s", aligned_fasta,
-        "--prefix", prefix,
-        "-m", "TEST",           # Auto model selection
-        "-B", str(bootstrap),   # Ultrafast bootstrap
-        "-T", str(n_threads),
-        "--redo",
-        "-alrt", "1000",        # SH-aLRT test
-    ]
-
-    if outgroup:
-        cmd += ["-o", outgroup]
-
-    result = subprocess.run(cmd, capture_output=True, text=True)
-
-    if result.returncode != 0:
-        raise RuntimeError(f"IQ-TREE failed:\n{result.stderr[:500]}")
-
-    tree_file = f"{prefix}.treefile"
-
-    # Extract best model from log
-    log_file = f"{prefix}.log"
-    if os.path.exists(log_file):
-        with open(log_file) as f:
-            for line in f:
-                if "Best-fit model" in line:
-                    print(f"  {line.strip()}")
-
-    print(f"  Tree saved → {tree_file}")
-    return tree_file
-
-
-def run_fasttree(aligned_fasta: str, output_tree: str, seq_type: str = "nt") -> str:
-    """Run FastTree (faster alternative for large datasets)."""
-    print("FastTree: Building approximate ML tree (faster)...")
-
-    if seq_type == "nt":
-        cmd = ["FastTree", "-nt", "-gtr", "-gamma", aligned_fasta]
-    else:
-        cmd = ["FastTree", "-lg", "-gamma", aligned_fasta]
-
-    with open(output_tree, 'w') as out:
-        result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)
-
-    if result.returncode != 0:
-        raise RuntimeError(f"FastTree failed:\n{result.stderr[:500]}")
-
-    print(f"  Tree saved → {output_tree}")
-    return output_tree
-
-
-def visualize_tree(tree_file: str, output_png: str, outgroup: str = None) -> None:
-    """Visualize the phylogenetic tree with ETE3."""
-    try:
-        from ete3 import Tree, TreeStyle, NodeStyle
-    except ImportError as exc:
-        # TreeStyle and NodeStyle live in ete3's Qt-backed treeview module, so
-        # this also fires when ete3 itself imported fine but PyQt5 is missing.
-        print(f"ETE3 rendering unavailable ({exc}). Skipping visualization.")
-        print("  Install: uv pip install ete3 PyQt5")
-        return
-
-    t = Tree(tree_file)
-
-    # Root the tree
-    if outgroup and outgroup in [leaf.name for leaf in t.get_leaves()]:
-        t.set_outgroup(outgroup)
-        print(f"  Rooted at outgroup: {outgroup}")
-    else:
-        # Midpoint rooting
-        t.set_outgroup(t.get_midpoint_outgroup())
-        print("  Applied midpoint rooting")
-
-    # Style
-    ts = TreeStyle()
-    ts.show_leaf_name = True
-    ts.show_branch_support = True
-    ts.mode = "r"  # rectangular
-
-    try:
-        t.render(output_png, tree_style=ts, w=800, units="px")
-        print(f"  Visualization saved → {output_png}")
-    except Exception as e:
-        print(f"  Visualization failed (display issue?): {e}")
-        # Save tree in Newick format as fallback
-        rooted_nwk = output_png.replace(".png", "_rooted.nwk")
-        t.write(format=1, outfile=rooted_nwk)
-        print(f"  Rooted tree saved → {rooted_nwk}")
-
-
-def tree_summary(tree_file: str) -> dict:
-    """Print summary statistics for the tree."""
-    try:
-        from ete3 import Tree
-        t = Tree(tree_file)
-        t.set_outgroup(t.get_midpoint_outgroup())
-
-        leaves = t.get_leaves()
-        branch_lengths = [n.dist for n in t.traverse() if n.dist > 0]
-
-        stats = {
-            "n_taxa": len(leaves),
-            "total_branch_length": sum(branch_lengths),
-            "mean_branch_length": sum(branch_lengths) / len(branch_lengths) if branch_lengths else 0,
-            "max_branch_length": max(branch_lengths) if branch_lengths else 0,
-        }
-
-        print("\nTree Summary:")
-        for k, v in stats.items():
-            if isinstance(v, float):
-                print(f"  {k}: {v:.6f}")
-            else:
-                print(f"  {k}: {v}")
-
-        return stats
-    except Exception as e:
-        print(f"Could not compute tree stats: {e}")
-        return {}
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Phylogenetic analysis pipeline")
-    parser.add_argument("input", help="Input FASTA file (unaligned)")
-    parser.add_argument("--type", choices=["nt", "aa"], default="nt",
-                        help="Sequence type: nt (nucleotide) or aa (amino acid)")
-    parser.add_argument("--threads", type=int, default=4, help="Number of threads")
-    parser.add_argument("--bootstrap", type=int, default=1000,
-                        help="Bootstrap replicates for IQ-TREE")
-    parser.add_argument("--fasttree", action="store_true",
-                        help="Use FastTree instead of IQ-TREE (faster, less accurate)")
-    parser.add_argument("--outgroup", help="Outgroup taxon name for rooting")
-    parser.add_argument("--mafft-method", default="auto",
-                        choices=["auto", "linsi", "einsi", "fftnsi", "fftns"],
-                        help="MAFFT alignment method")
-    parser.add_argument("--output-dir", default="phylo_results",
-                        help="Output directory")
-
-    args = parser.parse_args()
-
-    # Setup
-    os.makedirs(args.output_dir, exist_ok=True)
-    prefix = os.path.join(args.output_dir, Path(args.input).stem)
-
-    print("=" * 60)
-    print("Phylogenetic Analysis Pipeline")
-    print("=" * 60)
-    print(f"Input: {args.input}")
-    print(f"Sequence type: {args.type}")
-    print(f"Output dir: {args.output_dir}")
-
-    # Step 1: Multiple Sequence Alignment
-    print("\n[Step 1/3] Multiple Sequence Alignment (MAFFT)")
-    aligned = run_mafft(
-        args.input,
-        f"{prefix}_aligned.fasta",
-        n_threads=args.threads,
-        method=args.mafft_method
-    )
-
-    # Step 2: Tree Inference
-    print("\n[Step 2/3] Tree Inference")
-    if args.fasttree:
-        tree_file = run_fasttree(aligned, f"{prefix}.tree", seq_type=args.type)
-    else:
-        tree_file = run_iqtree(
-            aligned, prefix,
-            seq_type=args.type,
-            bootstrap=args.bootstrap,
-            n_threads=args.threads,
-            outgroup=args.outgroup
-        )
-
-    # Step 3: Visualization
-    print("\n[Step 3/3] Visualization (ETE3)")
-    visualize_tree(tree_file, f"{prefix}_tree.png", outgroup=args.outgroup)
-    tree_summary(tree_file)
-
-    print("\n" + "=" * 60)
-    print("Analysis complete!")
-    print(f"Key outputs:")
-    print(f"  Aligned sequences: {aligned}")
-    print(f"  Tree file: {tree_file}")
-    print(f"  Visualization: {prefix}_tree.png")
-
-
-if __name__ == "__main__":
-    main()

package/skills/pi-agent/references/compaction.md

@@ -1,76 +0,0 @@
-# Compaction and Branch Summarization
-
-Source: https://pi.dev/docs/latest/compaction
-
-Pi has two summarization mechanisms that share the same structured summary format and track file operations cumulatively.
-
-| Mechanism | Trigger | Purpose |
-|---|---|---|
-| Compaction | context exceeds threshold, or `/compact` | Summarize old messages to free context |
-| Branch summarization | `/tree` navigation | Preserve context when switching branches |
-
-Both use fresh routing session IDs and, where the provider supports it, disable prompt-cache writes because these one-off prompts are unlikely to be reused.
-
-## Auto-Compaction
-
-Triggers when `contextTokens > contextWindow - reserveTokens`. Defaults: `reserveTokens` 16384, `keepRecentTokens` 20000, configured under `compaction` in global or project settings. `/compact [instructions]` works even with auto-compaction disabled.
-
-Steps: walk backwards from the newest message accumulating token estimates until `keepRecentTokens` is reached (the cut point) → collect messages from the previous kept boundary (or session start) to the cut point → summarize with the structured format, passing any previous summary as iterative context → append a `CompactionEntry` → rebuild the context for the next request as summary plus messages from `firstKeptEntryId`.
-
-On repeated compactions the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry, falling back to the entry after the previous compaction when that kept entry is not on the path. This re-includes messages that survived the earlier pass. `tokensBefore` is recalculated from the rebuilt context before writing the new entry.
-
-Valid cut points: user messages, assistant messages, bash execution messages, and custom messages (`custom_message`, `branch_summary`). Pi never cuts at tool results.
-
-## Split Turns
-
-A turn starts with a user message and includes all assistant responses and tool calls until the next user message. When a single turn exceeds `keepRecentTokens`, the cut lands mid-turn at an assistant message (`isSplitTurn`). Pi then generates two summaries — a history summary for previous context and a turn-prefix summary for the early part of the split turn — and merges them.
-
-## Branch Summarization
-
-On `/tree` navigation to a different branch: find the deepest common ancestor, walk from the old leaf back to it, include messages up to the token budget newest-first, summarize, and append a `BranchSummaryEntry` at the navigation point — the summary lands on the destination branch's new leaf, not on the branch being left.
-
-Both mechanisms extract file operations from the tool calls being summarized **and** from previous compaction/branch-summary `details`, so read/modified file tracking accumulates across passes.
-
-## Entry Shapes
-
-`CompactionEntry`: `type`, `id`, `parentId`, `timestamp`, `summary`, `firstKeptEntryId`, `tokensBefore`, optional `usage` (LLM usage that generated the summary; counted in session totals), optional `fromHook` (legacy name for "provided by extension"), optional `details`.
-
-`BranchSummaryEntry`: same plus `fromId` instead of `firstKeptEntryId`.
-
-Default `details` is `{ readFiles: string[], modifiedFiles: string[] }`; extensions may store any JSON-serializable structure. Newer harness-generated compactions also embed `retainedTail` — see `references/session-format.md`.
-
-## Summary Format
-
-Sections: `## Goal`, `## Constraints & Preferences`, `## Progress` (Done / In Progress / Blocked), `## Key Decisions`, `## Next Steps`, `## Critical Context`, then `<read-files>` and `<modified-files>` blocks.
-
-## Message Serialization
-
-`serializeConversation()` renders messages as `[User]:`, `[Assistant thinking]:`, `[Assistant]:`, `[Assistant tool calls]:`, `[Tool result]:` lines so the model does not treat the input as a conversation to continue. Tool results are truncated to 2000 characters during serialization, with a marker showing how many characters were dropped — `read` and `bash` results are usually the largest contributors to context.
-
-## Extension Hooks
-
-`session_before_compact` receives `{ preparation, branchEntries, customInstructions, reason, willRetry, signal }`. `preparation` exposes `messagesToSummarize`, `turnPrefixMessages`, `previousSummary`, `fileOps`, `tokensBefore`, `firstKeptEntryId`, and `settings`; `reason` is `"manual"`, `"threshold"`, or `"overflow"`; `willRetry` indicates overflow recovery. Return `{ cancel: true }` or `{ compaction: { summary, firstKeptEntryId, tokensBefore, usage?, details? } }`.
-
-To summarize with your own model, convert messages first:
-
-```ts
-import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
-
-const text = serializeConversation(convertToLlm(preparation.messagesToSummarize));
-```
-
-`session_before_tree` receives `{ preparation, signal }` with `targetId`, `oldLeafId`, `commonAncestorId`, `entriesToSummarize`, and `userWantsSummary`. It always fires, whether or not the user chose to summarize. Return `{ cancel: true }` to cancel navigation, or `{ summary: { summary, usage?, details? } }` (used only when `userWantsSummary`).
-
-For direct programmatic summarization, `generateSummary()` returns the text and `generateSummaryWithUsage()` returns `{ text, usage }`.
-
-## Settings
-
-```json
-{
-  "compaction": {
-    "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
-  }
-}
-```

package/skills/pi-agent/references/containerization.md

@@ -1,80 +0,0 @@
-# Containerization
-
-Source: https://pi.dev/docs/latest/containerization
-
-Pi runs with all permissions by default. Two general approaches: run the whole `pi` process inside an isolated environment, or run `pi` on the host and route tool execution into an isolated environment.
-
-| Pattern | What is isolated | Best for | Notes |
-|---|---|---|---|
-| Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | `examples/extensions/gondolin/` |
-| Plain Docker | Whole `pi` process | Simplest local container boundary | Provider API keys enter the container |
-| OpenShell | Whole `pi` process | Local or remote policy-controlled sandbox | Requires an OpenShell gateway |
-
-Extensions run wherever the `pi` process runs. If host Pi routes built-ins into a VM, other custom extension tools still run on the host unless they delegate too.
-
-## Gondolin
-
-[Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
-
-```bash
-cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
-cd ~/.pi/agent/extensions/gondolin
-npm install --ignore-scripts
-
-cd /path/to/project
-pi -e ~/.pi/agent/extensions/gondolin
-```
-
-The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`. User `!` commands are routed into the VM as well, and file changes under `/workspace` write through to the host.
-
-Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU installed through your package manager.
-
-## Plain Docker
-
-`Dockerfile.pi`:
-
-```dockerfile
-FROM node:24-bookworm-slim
-
-RUN apt-get update \
-  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
-  && rm -rf /var/lib/apt/lists/*
-RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
-
-WORKDIR /workspace
-ENTRYPOINT ["pi"]
-```
-
-```bash
-docker build -t pi-sandbox -f Dockerfile.pi .
-
-docker run --rm -it \
-  -e ANTHROPIC_API_KEY \
-  -v "$PWD:/workspace" \
-  -v pi-agent-home:/root/.pi/agent \
-  pi-sandbox
-```
-
-`-v "$PWD:/workspace"` means reads and writes inside `/workspace` affect host files directly. Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions — mounting host `~/.pi/agent` exposes host auth and session files to the container.
-
-## OpenShell
-
-[NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) provides a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. It runs sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. Every sandbox requires an active gateway:
-
-```bash
-openshell gateway add <gateway-url> --name <name>
-openshell gateway select <name>
-
-openshell sandbox create --name pi-sandbox --from pi -- pi
-```
-
-The whole `pi` process runs inside the sandbox, so built-in tools, `!` commands, and extension tools all execute inside the boundary.
-
-Remote gateways do not bind-mount host project files, so sandbox writes are not reflected on your machine. Clone the repository inside the sandbox or transfer files explicitly:
-
-```bash
-openshell sandbox upload pi-sandbox ./repo /workspace
-openshell sandbox download pi-sandbox /workspace/repo ./repo-out
-```
-
-OpenShell providers can keep raw model API keys outside the sandbox: with inference routing configured, code inside the sandbox calls `https://inference.local` and the gateway injects provider credentials upstream. Point Pi at the corresponding OpenAI-compatible or Anthropic-compatible endpoint to use that route.