syntaxis/docs/wrappers/adr-decision-summary.md

# ADR-001: WRAPPER STRATEGY - DECISION SUMMARY

## The Question (Asked 3 Times! 🎯)
**"Are we going to use wrappers for installation? Should it be optional?"**

---

## The Deep Analysis: Wrapper Value Formula

```
Wrapper Justification = Frequency × User Burden Saved ÷ Maintenance Complexity

Good wrapper:  High Frequency + High Burden + Low Complexity = KEEP ✅
Bad wrapper:   Low Frequency + Low Burden + High Complexity = REMOVE ❌
```

---

## Pattern 1: Binary Execution Wrappers (EXISTING - KEEP ✅)

### Real-World Example
```bash
Without wrapper:
$ syntaxis-cli --config ~/.config/syntaxis/config.toml status
$ syntaxis-cli --config ~/.config/syntaxis/config.toml project list
$ syntaxis-cli --config ~/.config/syntaxis/config.toml task create
# ... 100s of times per day, 365 days a year

With wrapper:
$ syntaxis-cli status
$ syntaxis-cli project list
$ syntaxis-cli task create
```

### Analysis
- **Frequency**: 100s invocations per day
- **User Burden**: 50 chars per invocation (--config path)
- **Savings**: 50 × 100 × 365 = ~1.8 MILLION characters per year
- **Maintenance Complexity**: 3 layers (Bash → NuShell → Rust)

### Verdict
**VALUE >> COMPLEXITY** → KEEP THE WRAPPER ✅

### Why It Works
1. Called frequently (100s per day)
2. Solves real problem (config path typing)
3. Wrapper is transparent to users
4. Can be bypassed if needed (via .real extension)
5. Stable and proven system

---

## Pattern 2: Installation Wrapper (NEW - REMOVE ❌)

### Real-World Example
```bash
With wrapper:
$ ./provision full

Without wrapper:
$ bash install.sh --interactive
$ bash setup-config.sh --interactive
```

### Analysis
- **Frequency**: 1 invocation per user lifetime
- **User Burden**: 50 characters ONCE (not repeating)
- **Savings**: 50 characters total, one time only
- **Maintenance Complexity**: Multi-layer orchestration + shell detection

### Verdict
**COMPLEXITY >> VALUE** → REMOVE THE WRAPPER ❌

### Why It Doesn't Work
1. Called once per lifetime (not frequent)
2. User doesn't type --config path on install
3. Only saves ~5 seconds of typing (one-time)
4. Adds confusion: Which command to use?
   - `provision full` ?
   - `provision install` ?
   - `bash install.sh` ?
   - `bash setup-config.sh` ?
5. Violates philosophy: "No unnecessary complexity"

---

## The Key Insight (You Nailed It!)

> "Users don't want to add `--config path` for each call"

**Exactly!** That's why binary wrappers are ESSENTIAL.

But:
> "Installer wrappers add complexity... Are we going to use wrappers?"

**Right!** The installer wrapper adds complexity for a **one-time event** that doesn't have the `--config` problem.

---

## The Decision

### KEEP Binary Execution Wrappers ✅
```
Why:  Users invoke 100s times per day
      Typing burden is significant and repetitive
      Complexity is justified

What: Bash wrapper → NuShell wrapper → Real binary
      Auto-injects --config path
      Config discovery is automatic

Where: ~/.cargo/bin/syntaxis-cli (wrapper)
       ~/.cargo/bin/syntaxis-cli.real (binary)
       ~/.config/syntaxis/scripts/syntaxis-cli.nu (NuShell orchestrator)
```

### REMOVE Installation Wrapper ❌
```
Why:  Users install once
      Not a repetitive burden
      Complexity not justified
      Causes confusion

What: Delete provision.sh
      Keep only install.sh and setup-config.sh
      Simple two-step process

How:  bash install.sh --interactive
      bash setup-config.sh --interactive
```

---

## Implementation Plan

### What Changes
```diff
BEFORE (Confusing):
  Bundle contains:
  - provision.sh         ← Master wrapper (optional?)
  - install.sh           ← Direct installer (optional?)
  - setup-config.sh      ← Config helper (optional?)

  User confusion: Which one should I use?

AFTER (Clear):
  Bundle contains:
  - install.sh           ← Install binaries
  - setup-config.sh      ← Configure

  User knows: Two clear steps
```

### Steps
1. **Delete** `scripts/provisioning/provision.sh`
2. **Update** `configs/provisioning.toml` (remove provision.sh from scripts array)
3. **Update** `docs/docs/installation.md` (show two-step process)
4. **Update** `docs/BUNDLE_README.md` (show simple sequence)
5. **Rebuild** bundle with `nu scripts/provisioning/pack.nu`

### Result
```bash
# Before
tar -tzf dist/*.tar.gz | grep -E '(provision|install)'
  provision.sh        ← CONFUSION
  install.sh
  install.nu
  setup-config.sh

# After
tar -tzf dist/*.tar.gz | grep -E '(provision|install)'
  install.sh          ← CLARITY
  install.nu
  setup-config.sh
```

---

## Risk Assessment

### Very Low Risk ✅
- ✅ Removing an **optional** component
- ✅ Direct scripts are proven to work
- ✅ No impact on binary wrappers (which will stay)
- ✅ No impact on user experience
- ✅ Reduces maintenance burden

### If Something Goes Wrong
- Can always re-add `provision.sh`
- Direct scripts are bulletproof
- Bundle is self-contained

---

## Why This Matters

### Philosophy Alignment
SYNTAXIS says:
- ✅ "Configuration-driven design" → Wrappers help with config discovery
- ✅ "Modular with features to add or avoid" → Don't add unnecessary features
- ✅ "Users understand what's happening" → Direct scripts are transparent

Keeping both wrappers violates principle #2 and #3.

### Maintenance Burden
**Before**: Test 6 code paths × 3 shells × 4 platforms
**After**: Test 2 code paths × 3 shells × 4 platforms
= **75% reduction in test matrix**

### User Documentation
**Before**: "Use provision full OR provision install OR bash install.sh OR..."
**After**: "Run install.sh then setup-config.sh"
= **Much simpler!**

---

## The Bottom Line

### ✅ KEEP Binary Execution Wrappers
```
syntaxis-cli status    ← Wrapper auto-injects config
                          (saves millions of characters typed)
```

### ❌ REMOVE Installation Wrapper
```
bash install.sh        ← Direct script
bash setup-config.sh   ← Direct script
                          (one-time setup, no repetition)
```

### The Principle
**Wrappers should solve FREQUENT problems, not RARE ones.**

Installation happens once. Config path injection happens daily.

---

## Files
- **Decision Document**: `docs/adr/ADR-001-wrapper-architecture-strategy.md`
- **Status**: APPROVED - Ready to implement
- **Implementation**: Cleanup provisioning system as outlined above