# SYNTAXIS Bundle Documentation Guide

**Quick reference for managing bundle documentation.**

---

## 📍 Where Documents Live

All bundle documentation is in `docs/`:

```bash
docs/
├── BUNDLE_README.md         ← Bundle overview (becomes README.md in bundle)
├── docs/installation.md               ← Installation guide
├── QUICK_START.md           ← 5-minute getting started
├── CONFIG.md                ← Configuration reference
├── TROUBLESHOOTING.md       ← Common issues & solutions
├── PACK.md                  ← Provisioning system docs
├── BUNDLE_DOCS_REFERENCE.md ← (This document - detailed reference)
│
├── (Development docs - NOT in bundle)
├── ARCHITECTURE.md
├── CLI_QUICK_REFERENCE.md
├── SURREALDB_*.md
└── PERSISTENCE_*.md
```

---

## 🔄 Update & Rebuild Cycle

```
1. Edit docs/    → 2. Run pack.nu  → 3. Distribute bundle

   Edit:                   Build:          Users get:
   docs/docs/installation.md         nu scripts/     syntaxis-v0.1.0-*.tar.gz
   docs/CONFIG.md          provisioning/   (includes latest docs)
   docs/QUICK_START.md     pack.nu
   (any source files)
```

---

## ✏️ How to Update for Next Pack

### Quick Steps

```bash
# 1. Edit a document
nano docs/docs/installation.md

# 2. Build new bundle
nu scripts/provisioning/pack.nu

# 3. That's it! Bundle in dist/ has latest docs
```

### Detailed: Where Each Doc Goes

| Source File | Bundle Location | Purpose |
|---|---|---|
| `docs/BUNDLE_README.md` | `README.md` (root) | First thing users see |
| `docs/docs/installation.md` | `docs/installation.md` (root) | High visibility |
| `docs/QUICK_START.md` | `QUICK_START.md` (root) | First 5 minutes |
| `docs/CONFIG.md` | `docs/CONFIG.md` | Configuration reference |
| `docs/TROUBLESHOOTING.md` | `docs/TROUBLESHOOTING.md` | Problem solving |
| `docs/PACK.md` | `docs/PACK.md` | Provisioning info |

---

## 📋 What to Update When

| If... | Edit This | Reason |
|---|---|---|
| Users report installation issues | `docs/TROUBLESHOOTING.md` | Help future users |
| Configuration options change | `docs/CONFIG.md` | Keep docs accurate |
| Installation workflow changes | `docs/docs/installation.md` | Users follow new steps |
| Getting started changes | `docs/QUICK_START.md` | First impression matters |
| Bundle contents change | `docs/BUNDLE_README.md` | Describe what's inside |
| Provisioning system changes | `docs/PACK.md` | Document the system |

---

## 🔗 Configuration: provisioning.toml

Located: `configs/provisioning.toml`

Currently references (automatically used by pack.nu):

```toml
[artifacts]
docs = [
    "docs/BUNDLE_README.md",
    "docs/docs/installation.md",
    "docs/QUICK_START.md",
    "docs/CONFIG.md",
    "docs/TROUBLESHOOTING.md",
    "docs/PACK.md",
]

scripts = [
    "scripts/provisioning/provision.sh",
    "scripts/provisioning/install.sh",
    "scripts/provisioning/install.nu",
    "scripts/provisioning/setup-config.sh",
]
```

**To add a new doc:** Add line to `docs = [...]` array, save, run pack.nu.

---

## 📦 Automatic Reuse

Each time you run `pack.nu`:

✅ Reads latest `provisioning.toml`
✅ Finds all referenced doc files
✅ Copies latest versions
✅ Renames/places them correctly
✅ Generates SHA256 checksums
✅ Creates bundle archive

**No duplication needed.** Edit once, use forever.

---

## 🛠️ Build Commands

```bash
# Build for current system
nu scripts/provisioning/pack.nu

# Build for specific platform
nu scripts/provisioning/pack.nu --target x86_64-unknown-linux-gnu

# Different format (zip instead of tar.gz)
nu scripts/provisioning/pack.nu --format zip

# Verify bundle integrity
nu scripts/provisioning/pack.nu --verify

# Preview what would be packaged
nu scripts/provisioning/pack.nu --dry-run
```

---

## 📂 File Structure After Pack

Bundle created in: `dist/`

```
dist/
├── syntaxis-v0.1.0-aarch64-apple-darwin.tar.gz      ← User distributes this
├── syntaxis-v0.1.0-aarch64-apple-darwin.checksums.toml  ← Optional checksum file
```

When user extracts:

```
syntaxis-v0.1.0-aarch64-apple-darwin/
├── README.md                # From docs/BUNDLE_README.md
├── docs/installation.md               # From docs/docs/installation.md
├── QUICK_START.md           # From docs/QUICK_START.md
├── provision.sh             # Master provisioner (recommended)
├── install.sh               # Bash installer (optional)
├── setup-config.sh          # Config helper
└── docs/
    ├── CONFIG.md            # From docs/CONFIG.md
    ├── TROUBLESHOOTING.md   # From docs/TROUBLESHOOTING.md
    └── PACK.md              # From docs/PACK.md
```

---

## 💡 Pro Tips

### Tip 1: Check What's In Your Bundle

```bash
# List all files in latest bundle
tar -tzf dist/syntaxis-v0.1.0-*.tar.gz | head -30

# Extract and view specific doc
tar -xzOf dist/syntaxis-v0.1.0-*.tar.gz \
  'syntaxis-v0.1.0-*/docs/installation.md' | head -20
```

### Tip 2: Verify Changes Made It In

```bash
# Before and after comparison
tar -tzf dist/syntaxis-v0.1.0-*.tar.gz | grep README.md
```

### Tip 3: Update Multiple Docs at Once

```bash
# Edit all bundle docs
nano docs/BUNDLE_README.md
nano docs/docs/installation.md
nano docs/QUICK_START.md
nano docs/CONFIG.md

# One pack command includes all changes
nu scripts/provisioning/pack.nu
```

### Tip 4: Version Control

```bash
# Track doc changes with git
git add docs/docs/installation.md
git commit -m "docs: update installation steps for new provision script"

# Pack the new version
nu scripts/provisioning/pack.nu

# Users get latest with next bundle distribution
```

---

## 🧹 Cleanup

Old files removed (superseded by new ones):

- ~~`docs/CONFIG_GUIDE.md`~~ → replaced by `docs/CONFIG.md`
- ~~`docs/BUNDLE_docs/installation.md`~~ → replaced by `docs/docs/installation.md`

**Development-only docs (NOT in bundle):**
- `docs/ARCHITECTURE.md` - For developers
- `docs/CLI_QUICK_REFERENCE.md` - For developers
- `docs/SURREALDB_*.md` - Advanced/developer
- `docs/PERSISTENCE_*.md` - Advanced/developer

---

## 🚀 Example: Adding a New Guide

**Scenario:** You want to add a "First Deployment" guide to bundles

```bash
# 1. Create the new guide
cat > docs/FIRST_DEPLOYMENT.md << 'EOF'
# First Deployment Guide
...content here...
EOF

# 2. Add it to provisioning.toml
# Edit: configs/provisioning.toml
# In [artifacts] docs array, add:
#   "docs/FIRST_DEPLOYMENT.md",

# 3. Rebuild bundle
nu scripts/provisioning/pack.nu

# 4. New bundle includes it automatically
```

---

## 📞 Quick Reference Card

```
LOCATION:    docs/
CONFIG:      configs/provisioning.toml [artifacts] docs = [...]
BUILD:       nu scripts/provisioning/pack.nu
OUTPUT:      dist/syntaxis-v0.1.0-*.tar.gz
EDIT:        nano docs/<filename>.md
THEN:        nu scripts/provisioning/pack.nu
DONE:        Bundle ready for distribution with latest docs
```

---

## 📖 Related Documentation

For more detailed information, see:

- **`docs/BUNDLE_DOCS_REFERENCE.md`** - Comprehensive reference
- **`docs/PACK.md`** - Provisioning system details
- **`docs/docs/installation.md`** - Installation guide
- **`configs/provisioning.toml`** - Bundle configuration

---

**SYNTAXIS** v0.1.0

Bundle Documentation is user-focused, source-controlled, and automatically included in every pack.

Simple workflow: Edit → Pack → Distribute → Users get latest docs.