syntaxis/docs/guides/bundle-docs.md

SYNTAXIS Bundle Documentation Guide

Quick reference for managing bundle documentation.

---

📍 Where Documents Live

All bundle documentation is in docs/:

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

# 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):

[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

# 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

# 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

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

Tip 3: Update Multiple Docs at Once

# 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

# 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

# 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.