metabuilder/docs/FILE_RELOCATION_GUIDE.md

Documentation File Relocation Guide

Overview

This document provides instructions for moving all documentation files from the project root into the /docs folder with proper organization.

Files to Move

Iteration History → docs/iterations/

Move these iteration summary files:

mv COMPLETE_ITERATION_25.md docs/iterations/iteration-25-complete.md
mv ITERATION_24_SUMMARY.md docs/iterations/iteration-24-summary.md
mv ITERATION_25_SUMMARY.md docs/iterations/iteration-25-summary.md
mv ITERATION_26_SUMMARY.md docs/iterations/iteration-26-summary.md
mv THE_TRANSFORMATION.md docs/iterations/the-transformation.md

Architecture Documentation → docs/architecture/

Move these architectural guides:

mv DATA_DRIVEN_ARCHITECTURE.md docs/architecture/data-driven-architecture.md
mv DECLARATIVE_COMPONENTS.md docs/architecture/declarative-components.md
mv GENERIC_PAGE_SYSTEM.md docs/architecture/generic-page-system.md

Package System Documentation → docs/packages/

Move these package-related guides:

mv PACKAGE_SYSTEM.md docs/packages/package-system.md
mv PACKAGE_IMPORT_EXPORT.md docs/packages/import-export.md
mv PACKAGE_SCRIPTS_GUIDE.md docs/packages/scripts-guide.md
mv MODULAR_PACKAGES_GUIDE.md docs/packages/modular-packages-guide.md
mv MODULAR_SEED_DATA_GUIDE.md docs/packages/modular-seed-data-guide.md
mv IRC_CONVERSION_GUIDE.md docs/packages/irc-conversion-guide.md

Lua Documentation → docs/lua/

Move these Lua-related guides:

mv LUA_INTEGRATION.md docs/lua/integration.md
mv LUA_SNIPPETS_GUIDE.md docs/lua/snippets-guide.md

Development Guides → docs/development/

Move these development guides:

mv TYPESCRIPT_REDUCTION_GUIDE.md docs/development/typescript-reduction-guide.md
mv CRUFT_REMOVAL_REPORT.md docs/development/cruft-removal-report.md
mv IMPROVEMENTS.md docs/development/improvements.md

Database Documentation → docs/database/

Move database documentation:

mv DATABASE.md docs/database/overview.md

Security Documentation → docs/security/

Move security guides:

mv SECURITY_GUIDE.md docs/security/guide.md

Reference Documentation → docs/reference/

Move reference materials:

mv QUICK_REFERENCE.md docs/reference/quick-reference.md
mv DOCUMENTATION_INDEX.md docs/reference/documentation-index.md
mv PLATFORM_GUIDE.md docs/reference/platform-guide.md

Files to Keep in Root

These files should remain in the project root:

• README.md - Main project readme
• PRD.md - Product Requirements Document
• LICENSE - Project license
• SECURITY.md - GitHub security policy

Directory Structure After Move

/workspaces/spark-template/
├── README.md (keep)
├── PRD.md (keep)
├── LICENSE (keep)
├── SECURITY.md (keep)
└── docs/
    ├── README.md (existing)
    ├── architecture/
    │   ├── data-driven-architecture.md
    │   ├── declarative-components.md
    │   └── generic-page-system.md
    ├── database/
    │   └── overview.md
    ├── development/
    │   ├── typescript-reduction-guide.md
    │   ├── cruft-removal-report.md
    │   └── improvements.md
    ├── iterations/
    │   ├── iteration-24-summary.md
    │   ├── iteration-25-summary.md
    │   ├── iteration-25-complete.md
    │   ├── iteration-26-summary.md
    │   └── the-transformation.md
    ├── lua/
    │   ├── integration.md
    │   └── snippets-guide.md
    ├── packages/
    │   ├── package-system.md
    │   ├── import-export.md
    │   ├── scripts-guide.md
    │   ├── modular-packages-guide.md
    │   ├── modular-seed-data-guide.md
    │   └── irc-conversion-guide.md
    ├── reference/
    │   ├── quick-reference.md
    │   ├── documentation-index.md
    │   └── platform-guide.md
    └── security/
        └── guide.md

Bash Script for Relocation

Create and run this bash script to move all files at once:

#!/bin/bash

# Navigate to project root
cd /workspaces/spark-template

# Create directories
mkdir -p docs/iterations
mkdir -p docs/architecture
mkdir -p docs/packages
mkdir -p docs/lua
mkdir -p docs/development
mkdir -p docs/database
mkdir -p docs/security
mkdir -p docs/reference

# Move iteration history
mv COMPLETE_ITERATION_25.md docs/iterations/iteration-25-complete.md 2>/dev/null
mv ITERATION_24_SUMMARY.md docs/iterations/iteration-24-summary.md 2>/dev/null
mv ITERATION_25_SUMMARY.md docs/iterations/iteration-25-summary.md 2>/dev/null
mv ITERATION_26_SUMMARY.md docs/iterations/iteration-26-summary.md 2>/dev/null
mv THE_TRANSFORMATION.md docs/iterations/the-transformation.md 2>/dev/null

# Move architecture docs
mv DATA_DRIVEN_ARCHITECTURE.md docs/architecture/data-driven-architecture.md 2>/dev/null
mv DECLARATIVE_COMPONENTS.md docs/architecture/declarative-components.md 2>/dev/null
mv GENERIC_PAGE_SYSTEM.md docs/architecture/generic-page-system.md 2>/dev/null

# Move package docs
mv PACKAGE_SYSTEM.md docs/packages/package-system.md 2>/dev/null
mv PACKAGE_IMPORT_EXPORT.md docs/packages/import-export.md 2>/dev/null
mv PACKAGE_SCRIPTS_GUIDE.md docs/packages/scripts-guide.md 2>/dev/null
mv MODULAR_PACKAGES_GUIDE.md docs/packages/modular-packages-guide.md 2>/dev/null
mv MODULAR_SEED_DATA_GUIDE.md docs/packages/modular-seed-data-guide.md 2>/dev/null
mv IRC_CONVERSION_GUIDE.md docs/packages/irc-conversion-guide.md 2>/dev/null

# Move Lua docs
mv LUA_INTEGRATION.md docs/lua/integration.md 2>/dev/null
mv LUA_SNIPPETS_GUIDE.md docs/lua/snippets-guide.md 2>/dev/null

# Move development docs
mv TYPESCRIPT_REDUCTION_GUIDE.md docs/development/typescript-reduction-guide.md 2>/dev/null
mv CRUFT_REMOVAL_REPORT.md docs/development/cruft-removal-report.md 2>/dev/null
mv IMPROVEMENTS.md docs/development/improvements.md 2>/dev/null

# Move database docs
mv DATABASE.md docs/database/overview.md 2>/dev/null

# Move security docs
mv SECURITY_GUIDE.md docs/security/guide.md 2>/dev/null

# Move reference docs
mv QUICK_REFERENCE.md docs/reference/quick-reference.md 2>/dev/null
mv DOCUMENTATION_INDEX.md docs/reference/documentation-index.md 2>/dev/null
mv PLATFORM_GUIDE.md docs/reference/platform-guide.md 2>/dev/null

echo "✅ Documentation files moved successfully!"
echo "📁 Check the /docs directory for the organized documentation"

Verification

After running the script, verify the move with:

# List root directory - should only show key files
ls -1 *.md

# Should show:
# README.md
# PRD.md
# SECURITY.md

# List docs directory structure
tree docs/ -L 2

# Should show the organized structure

Update References

After moving files, you may need to update internal references in:

1. README.md links
2. PRD.md links
3. Any cross-references between documentation files

Notes

• The 2>/dev/null redirects suppress "file not found" errors if a file doesn't exist
• All files are renamed to lowercase with hyphens for consistency
• The directory structure provides clear categorization
• This organization matches modern documentation best practices