syntaxis/docs/bundle-docs-reference.md

# Bundle Documentation Reference

This document explains where bundle documentation lives, how to update it, and how it flows through the provisioning system.

## Quick Answer

**Where are they?**
```
docs/BUNDLE_README.md      ← Source for bundle README.md
docs/docs/installation.md            ← Source for bundle docs/installation.md
docs/QUICK_START.md        ← Source for bundle QUICK_START.md
docs/CONFIG.md             ← Source for docs/CONFIG.md in bundle
docs/TROUBLESHOOTING.md    ← Source for docs/TROUBLESHOOTING.md in bundle
docs/PACK.md               ← Source for docs/PACK.md in bundle
```

**How to update for next pack:**
1. Edit the source files in `docs/` folder directly
2. Run `nu scripts/provisioning/pack.nu`
3. New bundle will include your changes
4. Checksums will be recalculated automatically

**What gets reused?**
Everything. Each pack run:
- Reads `configs/provisioning.toml` for file references
- Copies latest versions of docs/*.md
- Renames/places them in bundle structure
- Calculates fresh checksums

---

## Complete Workflow

### 1. Source Documentation (Always in docs/)

```
BUNDLE DOCUMENTATION:
├── BUNDLE_README.md      [6.5K] User-facing bundle overview
├── docs/installation.md            [8.2K] Installation guide (generic, no platform-specific)
├── QUICK_START.md        [3.8K] 5-minute getting started tutorial
├── CONFIG.md             [8.2K] Configuration reference for all apps
├── TROUBLESHOOTING.md    [9.7K] Common issues and solutions
└── PACK.md               [9.3K] Provisioning system documentation (for developers)

DEVELOPMENT DOCUMENTATION (NOT in bundle):
├── ARCHITECTURE.md       Project architecture (developers)
├── CLI_QUICK_REFERENCE.md CLI reference (developers)
├── SURREALDB_*.md        SurrealDB guides (developers/advanced)
└── PERSISTENCE_*.md      Database persistence (developers)

DEPRECATED (can be deleted):
├── CONFIG_GUIDE.md       [OLD - superseded by CONFIG.md]
└── BUNDLE_docs/installation.md     [OLD - superseded by docs/installation.md]
```

### 2. Configuration (provisioning.toml)

Located: `configs/provisioning.toml`

References which docs to include:
```toml
[artifacts]
docs = [
    "docs/BUNDLE_README.md",         # Bundle overview (becomes README.md at root)
    "docs/docs/installation.md",               # Installation guide (generic, no platform-specific)
    "docs/QUICK_START.md",           # 5-minute getting started guide
    "docs/CONFIG.md",                # Configuration reference for all apps
    "docs/TROUBLESHOOTING.md",       # Common issues and solutions
    "docs/PACK.md",                  # Provisioning system documentation
]

scripts = [
    "scripts/provisioning/provision.sh",     # Master provisioner (install + config orchestrator)
    "scripts/provisioning/install.sh",       # Bash installer for offline bundles
    "scripts/provisioning/install.nu",       # NuShell installer (if available)
    "scripts/provisioning/setup-config.sh",  # Interactive configuration helper
]
```

### 3. Pack Process (pack.nu)

Located: `scripts/provisioning/pack.nu`

Process:
```
1. Read configs/provisioning.toml
2. Find all referenced files:
   - docs/BUNDLE_README.md
   - docs/docs/installation.md
   - docs/QUICK_START.md
   - docs/CONFIG.md
   - docs/TROUBLESHOOTING.md
   - docs/PACK.md
   - scripts/provisioning/*.sh
3. Create bundle structure:
   - Rename BUNDLE_README.md → README.md (at root)
   - Place docs/installation.md at root
   - Place QUICK_START.md at root
   - Place CONFIG.md in docs/
   - Place TROUBLESHOOTING.md in docs/
   - Place PACK.md in docs/
   - Place scripts at root with executable permissions
4. Generate manifest.toml with artifact list
5. Calculate SHA256 checksums for every file
6. Create archive (tar.gz or zip)
```

### 4. Bundle Output

Located: `dist/`

```
dist/
├── syntaxis-v0.1.0-aarch64-apple-darwin.tar.gz
├── syntaxis-v0.1.0-aarch64-apple-darwin.checksums.toml

When extracted:
syntaxis-v0.1.0-aarch64-apple-darwin/
├── README.md              [from BUNDLE_README.md]
├── docs/installation.md             [from docs/docs/installation.md]
├── QUICK_START.md         [from docs/QUICK_START.md]
├── provision.sh           [from scripts/provisioning/provision.sh]
├── install.sh             [from scripts/provisioning/install.sh]
├── setup-config.sh        [from scripts/provisioning/setup-config.sh]
└── docs/
    ├── CONFIG.md          [from docs/CONFIG.md]
    ├── TROUBLESHOOTING.md [from docs/TROUBLESHOOTING.md]
    └── PACK.md            [from docs/PACK.md]
```

---

## How to Update Documentation for Next Pack

### Step 1: Identify What Needs Updating

Each document has a specific purpose:

| File | Purpose | Audience | Update When |
|------|---------|----------|-------------|
| **BUNDLE_README.md** | Bundle overview, what's inside | New users | Adding features, changing bundle contents |
| **docs/installation.md** | Installation methods and options | Users installing | Changing installation workflow, new platforms |
| **QUICK_START.md** | First 5 minutes, basic workflow | New users | Changing basic workflow, new quick commands |
| **CONFIG.md** | All configuration options | Users configuring | Adding config options, database changes |
| **TROUBLESHOOTING.md** | Common issues and solutions | Users with problems | New issues discovered, bugs fixed |
| **PACK.md** | Provisioning system internals | Developers building bundles | Pack.nu changes, new features |

### Step 2: Edit the Source File

All files are markdown in `docs/`:

```bash
# Edit installation guide
nano docs/docs/installation.md

# Edit configuration reference
nano docs/CONFIG.md

# Edit quick start
nano docs/QUICK_START.md

# Edit troubleshooting
nano docs/TROUBLESHOOTING.md

# Edit bundle overview
nano docs/BUNDLE_README.md

# Edit provisioning docs
nano docs/PACK.md
```

### Step 3: Create New Bundle

After editing, create a new bundle with your changes:

```bash
# Generate new bundle (for current platform)
nu scripts/provisioning/pack.nu

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

# Or verify before creating
nu scripts/provisioning/pack.nu --verify
```

### Step 4: Verify Changes

Check the bundle contains your updates:

```bash
# Extract and verify
tar -tzf dist/syntaxis-v0.1.0-*.tar.gz | grep -E '(README|INSTALL|QUICK|CONFIG)'

# View specific document
tar -xzOf dist/syntaxis-v0.1.0-*.tar.gz syntaxis-v0.1.0-*/docs/installation.md | head -20
```

---

## File Naming Conventions

| Source File | Bundle Name | Location | Notes |
|---|---|---|---|
| `docs/BUNDLE_README.md` | `README.md` | Root | Renamed for standard naming |
| `docs/docs/installation.md` | `docs/installation.md` | Root | High visibility |
| `docs/QUICK_START.md` | `QUICK_START.md` | Root | High visibility |
| `docs/CONFIG.md` | `CONFIG.md` | docs/ | Supplementary |
| `docs/TROUBLESHOOTING.md` | `TROUBLESHOOTING.md` | docs/ | Supplementary |
| `docs/PACK.md` | `PACK.md` | docs/ | Developer reference |

---

## Content Guidelines

### BUNDLE_README.md

**What to include:**
- What SYNTAXIS is (brief)
- What's in the bundle
- Quick 2-3 step installation
- What's next
- Links to other docs

**What to avoid:**
- Project history or philosophy (save for website)
- Development setup instructions
- Links to GitHub issues/PRs

### docs/installation.md

**What to include:**
- System requirements
- Multiple installation methods
- Step-by-step instructions
- Environment setup
- Troubleshooting common install issues

**What to avoid:**
- Platform-specific variations (keep generic)
- Development installation (users are end-users)
- Bleeding-edge/git installation

### CONFIG.md

**What to include:**
- All configuration files and their locations
- Every configuration option with examples
- Environment variables
- How to apply changes
- Common customization scenarios

**What to avoid:**
- Development-only settings
- Internal/debug options
- Experimental features

### TROUBLESHOOTING.md

**What to include:**
- Common problems users encounter
- Solutions with commands
- Diagnostic steps
- When to seek help
- Where to report issues

**What to avoid:**
- Development debugging
- Known but unfixable issues
- Workarounds for bugs (fix the bug instead)

### QUICK_START.md

**What to include:**
- 5-minute timeline
- Minimal steps to working system
- "Next steps" with references
- Common commands reference

**What to avoid:**
- Options and customization
- Full documentation
- Advanced features

---

## Local Development Editing

### Using Version Control

When updating docs:

```bash
# Create feature branch
git checkout -b docs/update-install-guide

# Edit docs
nano docs/docs/installation.md

# Commit
git add docs/docs/installation.md
git commit -m "docs: update installation guide for new setup-config flow"

# Push and create PR
git push origin docs/update-install-guide
```

### Testing Doc Changes

Before packing:

```bash
# Check TOML syntax of markdown (if using front matter)
cat docs/docs/installation.md | head -20

# Verify references to other docs work locally
grep -n "CONFIG.md\|QUICK_START.md" docs/docs/installation.md

# Check markdown syntax (with mdl if installed)
mdl docs/docs/installation.md
```

---

## Cleanup: Removing Deprecated Files

Old files that can be deleted (replaced by newer versions):

```bash
rm docs/CONFIG_GUIDE.md          # Replaced by CONFIG.md
rm docs/BUNDLE_docs/installation.md        # Replaced by docs/installation.md
```

These were superseded by the new naming scheme.

---

## Summary: Update Cycle

```
1. Source Files          2. Configuration        3. Pack Process        4. Distribution
   (always in docs/)        (provisioning.toml)     (pack.nu)             (user bundle)

   BUNDLE_README.md ─┐
   docs/installation.md       ├─→ provisioning.toml ──→ pack.nu ──→ dist/ ──→ bundle
   QUICK_START.md   ├─→  [artifacts.docs]      [reads & copies]      tar.gz
   CONFIG.md        ├─→  [artifacts.scripts]   [generates manifest]
   TROUBLESHOOTING  ├─→                        [calculates checksums]
   PACK.md          ┘

Edit Here         Configure Here    Processes Here   Users Extract Here
Simple!           Simple!            Automatic!       Get Latest!
```

---

## Quick Reference: Common Updates

### Users report installation issue
1. Edit `docs/TROUBLESHOOTING.md`
2. Add issue + solution
3. Run `nu scripts/provisioning/pack.nu`
4. Distribute new bundle

### Configuration option changes
1. Edit `docs/CONFIG.md`
2. Update examples and descriptions
3. Run `nu scripts/provisioning/pack.nu`
4. Distribute new bundle

### Workflow improvements
1. Edit `docs/QUICK_START.md` and/or `docs/docs/installation.md`
2. Update instructions
3. Run `nu scripts/provisioning/pack.nu`
4. Distribute new bundle

### System changes
1. Edit `docs/PACK.md` if provisioning system changes
2. Run `nu scripts/provisioning/pack.nu`
3. Distribute new bundle

---

**Key Point:** Your source of truth is always `docs/`. Edit there, run pack.nu, distribute the bundle. Each pack automatically includes the latest versions of everything.

---

**SYNTAXIS** v0.1.0 • [syntaxis.dev](https://syntaxis.dev)