orto-skills/INSTALLATION_GUIDE.md

# Orto Skills Suite — Installation Guide

**Version:** 1.0  
**Release Date:** 2026-03-06  
**Status:** Production-Ready

---

## Quick Start (60 seconds)

### Step 1: Install Locally

```bash
# Clone or download orto-skills/build/dist/*.skill

# Install all 9 skills:
mkdir -p ~/.openclaw/skills/orto-suite
unzip -d ~/.openclaw/skills/orto-suite ~/.openclaw/workspace/orto-skills/build/dist/*.skill

# Verify:
ls ~/.openclaw/skills/orto-suite/orto-*/SKILL.md | wc -l
# Output: 9 (all installed)
```

### Step 2: Create Your First Garden

```bash
# Initialize a new garden
openclaw invoke ~/.openclaw/skills/orto-suite/orto-init/SKILL.md \
  --id orto_mytown_001 \
  --name "My First Garden" \
  --provincia Roma \
  --regione Lazio \
  --lat 41.8782 \
  --lon 12.4922

# Output: Garden created at ~/.openclaw/workspace/Orti/orto_mytown_001/
```

### Step 3: Run Onboarding

```bash
openclaw invoke ~/.openclaw/skills/orto-suite/orto-onboarding/SKILL.md \
  --orto-id orto_mytown_001

# Fills 5 questionnaire blocks interactively
# Output: GardenConfig + CommunityProfile saved
```

### Step 4: Generate Master Plan

```bash
openclaw invoke ~/.openclaw/skills/orto-suite/orto-orchestratore/SKILL.md \
  --orto-id orto_mytown_001

# Runs all 7 skills, merges outputs, generates PlanBundle
# Output: Complete seasonal plan + weekly briefing
```

---

## Detailed Installation Options

### Option 1: Local Installation (Recommended for Testing)

**Pros:** Fast, no internet, full control  
**Cons:** Limited to one machine

```bash
# 1. Download/copy orto-skills/build/dist/ folder

# 2. Extract all .skill files
cd ~/.openclaw/skills/
mkdir orto-suite
unzip "~/Downloads/orto-skills/build/dist/*.skill" -d orto-suite/

# 3. Verify installation
find orto-suite -name "SKILL.md" | head -5

# 4. Use in your workflow
# Reference: ~/.openclaw/skills/orto-suite/orto-init/SKILL.md
```

### Option 2: System-Wide Installation (OpenClaw CLI)

**Pros:** Integrated with OpenClaw CLI, auto-discovery  
**Cons:** Requires OpenClaw v25.7+

```bash
# 1. Install skills to default location
openclaw skills install /path/to/orto-skills/build/dist/orto-*.skill

# 2. Verify registration
openclaw skills list | grep orto

# 3. Invoke by name (no path needed)
openclaw invoke orto-init --id orto_test_001 ...
```

### Option 3: ClawHub Publication (Production Distribution)

**Pros:** Global availability, versioning, community  
**Cons:** Requires ClawHub account, internet

```bash
# 1. Setup ClawHub account (one-time)
clawhub auth login

# 2. Publish all 9 skills
cd orto-skills/build/dist/
for skill in *.skill; do
  clawhub publish "$skill"
done

# 3. Verify on clawhub.com
# View: https://clawhub.com/orto-suite

# 4. Install from ClawHub
clawhub install orto-init
clawhub install orto-orchestratore
# ... etc
```

---

## Troubleshooting

### Issue: "Command not found: openclaw"

**Solution:**
```bash
# Ensure OpenClaw is in PATH
which openclaw

# If not found, add to PATH:
export PATH="/usr/local/bin:$PATH"  # or your installation dir
```

### Issue: "SKILL.md not found"

**Solution:**
```bash
# Verify .skill files extracted correctly
unzip -l ~/.openclaw/workspace/orto-skills/build/dist/orto-init.skill

# If missing, re-extract:
rm -rf ~/.openclaw/skills/orto-suite/*
unzip -d ~/.openclaw/skills/orto-suite ~/.openclaw/workspace/orto-skills/build/dist/orto-*.skill
```

### Issue: "Garden already exists"

**Solution:**
```bash
# Use unique orto_id:
openclaw invoke orto-init --id orto_mytown_002  # Instead of 001

# Or remove existing:
rm -rf ~/.openclaw/workspace/Orti/orto_mytown_001/
```

### Issue: "Weather API unreachable"

**Solution:**
```bash
# wttr.in fallback to open-meteo (automatic)
# If both fail, meteo-decisioni will use cached/default forecast

# Check connectivity:
curl -s wttr.in/Roma
# Should return weather forecast
```

---

## Configuration

### Customize Knowledge Base

Edit references before packaging:

```bash
# 1. Modify crop varieties
vim orto-skills/references/colture_it.md

# 2. Add regional calendars
vim orto-skills/references/calendario_it.md

# 3. Re-package skills
cd orto-skills/build
for skill in orto-*/; do
  python3 ~/.nvm/versions/node/v25.7.0/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py "${skill%/}" ./dist
done
```

### Customize Automation Policies

Edit orchestratore conflict resolution:

```bash
# 1. Modify conflict policies
vim orto-skills/build/orto-orchestratore/SKILL.md
# Search: "Conflict Resolution"

# 2. Update QA thresholds
# Search: "QA Score"

# 3. Re-package
python3 ... package_skill.py orto-orchestratore ./dist
```

---

## Running a Full Garden Planning Session

### Step-by-Step Workflow

```bash
# 1. Init
openclaw invoke orto-init --id orto_test_001 --name "Test" --provincia Roma --regione Lazio --lat 41.8782 --lon 12.4922

# 2. Onboarding (answer 5 blocchi interactively)
openclaw invoke orto-onboarding --orto-id orto_test_001

# 3. Full plan (all skills)
openclaw invoke orto-orchestratore --orto-id orto_test_001

# Output files generated at:
# ~/.openclaw/workspace/Orti/orto_test_001/
#   ├── config/
#   │   ├── garden_config.md
#   │   └── community_profile.md
#   ├── dati/
#   │   ├── colture/piano_colture_annuale.md
#   │   ├── calendario/calendario_operativo_settimanale.md
#   │   ├── layout/aiuole_dimensioni.md
#   │   ├── irrigazione/sistema_irrigazione.md
#   │   ├── meteo/dati_meteo_giornalieri.md
#   │   └── trattamenti/diagnosi_problemi.md
#   └── log/
#       ├── audit_trail.md
#       └── PlanBundle_Master.md

# 4. Weekly briefing (every Monday)
openclaw invoke orto-meteo-decisioni --orto-id orto_test_001 --week-ahead

# Output:
# briefing_settimanale_week_N.md (weekly task list + meteo alerts)
```

### Expected Output

All files are **markdown** (human-readable, editable):

```markdown
# PlanBundle Master — orto_test_001

**Garden:** Test (Roma, Lazio, 41.8782°N)
**Community:** 4 people, Misto diet, Dilettante
**Area:** 50 m², Zone: Centro (Frost: 15 apr - 25 oct)

## Plan Summary
- Crops: 12 varieties (Pomodoro, Basilico, Lattuga, ...)
- Annual yield: ~100 kg
- Maintenance: 3-4h/week
- Water: ~10,000 L/season
- Weekly briefing: See briefing_settimanale_week_1.md

## Weekly Task (Week 1)
- [ ] Preparazione semenzaio (1.5h)
- [ ] Controllo strumenti (0.5h)
- [ ] Meteo: Mixed (rain Wed-Thu)
- [ ] Irrigazione: Baseline

[... full plan continues ...]
```

---

## Support & Documentation

### Included Documentation

- **README.md** — Quick overview
- **COMPLETION_SUMMARY.md** — Delivery summary
- **PACKAGING_COMPLETE.md** — Packaging details
- **Each SKILL.md** — Full skill documentation + examples

### Additional Resources

- **ClawHub:** https://clawhub.com/orto-suite
- **OpenClaw Docs:** https://docs.openclaw.ai
- **GitHub Issues:** Report problems

### Getting Help

**Questions about specific skills:**
```bash
# Read skill documentation
cat ~/.openclaw/skills/orto-suite/orto-init/SKILL.md | less

# Run with --help flag
openclaw invoke orto-init --help
```

**Integration questions:**
- See `ORTO_SKILL_ANALYSIS.md` (architecture overview)
- See `TEST_PLAN.md` (testing strategy)

---

## System Requirements

| Requirement | Version | Notes |
|------------|---------|-------|
| OpenClaw | ≥ 25.7 | For skill orchestration |
| Python | ≥ 3.8 | For scripts |
| Bash | ≥ 4.0 | For workflow automation |
| Filesystem | POSIX | Linux/macOS/WSL2 |
| Internet | Optional | For weather API (fallback available) |

---

## Uninstallation

```bash
# Remove local installation
rm -rf ~/.openclaw/skills/orto-suite/

# Remove garden projects
rm -rf ~/.openclaw/workspace/Orti/

# If via clawhub:
clawhub uninstall orto-init
clawhub uninstall orto-orchestratore
# ... etc
```

---

## License & Attribution

**Orto Skills Suite v1.0** — Derived from Orto v1 Framework (2026-03-06)

Transformed into AgentSkills format by automated pipeline.

**Language:** Italian (Italiano)  
**Domain:** Garden management (Italian climate, regions, crops)

---

## Next Steps

1. ✅ **Installation:** Choose option (local, system, or ClawHub)
2. ✅ **First Garden:** Run init + onboarding + orchestratore
3. ✅ **Weekly Briefing:** Set up recurring meteo-decisioni calls
4. ✅ **Feedback:** Share improvements/suggestions

**Ready?** Start with: `openclaw invoke orto-init --id orto_mytown_001 ...`

🌱 **Happy gardening!**