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:

[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/:

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

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

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

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

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

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