refactor: move permanent documentation to docs/ folder and clarify organization policy

BREAKING: Documentation organization has been restructured to enforce a core policy:
  All permanent documentation is now in docs/ folder, not in .github/ subdirectories.

Changes:
- Move FILE_ORGANIZATION.md to docs/ (now the central organization reference)
- Move COPILOT_TASKS.md to docs/COPILOT_TASKS.md
- Move custom-instructions.md to docs/CUSTOM_INSTRUCTIONS.md
- Create scripts/README.md documenting build and automation scripts
- Update .github/README.md to clarify that permanent docs are in docs/ folder
- Update docs/FILE_ORGANIZATION.md with core policy statement and examples

Organization principle:
  .github/ = Infrastructure, configuration, transient work (projects, reports)
  docs/    = All permanent, versioned documentation
  tmp/     = Temporary files (no README.md)
  logs/    = Log files (no README.md)
  Root folders = Should have README.md describing their purpose

Every .github/ subdirectory already has a README.md. Only scripts/ folder in root was missing one - now created.

This improves discoverability and ensures documentation is properly versioned with the codebase.

Author: ashleyshaw

.github/README.md

@@ -14,11 +14,21 @@ This directory contains GitHub-specific configuration files for the {{theme_name
 ## Contents
 
 - **agents/** - AI agent configurations for automated development tasks
-- **chatmodes/** - Custom chat mode configurations for AI assistants
 - **instructions/** - Development instructions and guidelines for AI tools
+- **projects/** - Active Copilot projects and in-progress work
 - **prompts/** - Reusable prompt templates for AI-assisted development
+- **reports/** - Completed task reports and validation outcomes
+- **schemas/** - JSON schemas and configuration templates
 - **workflows/** - GitHub Actions CI/CD workflow definitions
 
+## Documentation
+
+Permanent documentation is stored in the [docs/](../docs/) folder, not here. See:
+
+- [docs/FILE_ORGANIZATION.md](../docs/FILE_ORGANIZATION.md) - File organization guide
+- [docs/COPILOT_TASKS.md](../docs/COPILOT_TASKS.md) - Copilot task definitions
+- [docs/CUSTOM_INSTRUCTIONS.md](../docs/CUSTOM_INSTRUCTIONS.md) - Custom AI instructions
+
 ## Workflows
 
 | Workflow | Description |

.github/copilot-tasks.md docs/COPILOT_TASKS.md.github/copilot-tasks.md renamed to docs/COPILOT_TASKS.md

@@ -11,6 +11,21 @@ date: 2025-12-09
 
 This document explains where different types of files are stored in the block-theme-scaffold repository and the rationale for each location.
 
+## Core Policy: Documentation Location
+
+**🔑 Key Rule:** All permanent documentation must be stored in the `docs/` folder, not in `.github/` subdirectories.
+
+- `.github/` is for infrastructure, configuration, and transient work (projects, reports)
+- `docs/` is for permanent, versioned documentation
+- `tmp/` and `logs/` do NOT include README.md files
+
+This separation ensures:
+
+- Clear distinction between infrastructure and documentation
+- Permanent docs are discoverable and grouped together
+- Easier navigation for developers and AI agents
+- Reduces cognitive overhead
+
 ### Directory Structure Overview
 
 ```bash
@@ -23,16 +38,19 @@ block-theme-scaffold/
 │   ├── agents/               # Agent specifications and code
 │   ├── workflows/            # GitHub Actions CI/CD
 │   └── prompts/              # Prompt templates for AI generation
-├── docs/                     # Permanent documentation
+├── docs/                     # ⭐ ALL permanent documentation here
+│   ├── GOVERNANCE-START-HERE.md  # Navigation hub
 │   ├── GOVERNANCE.md         # Core policies & standards
 │   ├── ARCHITECTURE.md       # Project structure
-│   ├── GOVERNANCE-START-HERE.md  # Navigation hub
-│   └── [other docs]/         # Comprehensive guides
+│   ├── FILE_ORGANIZATION.md  # This file
+│   ├── CUSTOM_INSTRUCTIONS.md    # Custom AI instructions
+│   ├── COPILOT_TASKS.md      # Copilot task definitions
+│   └── [other comprehensive guides]/
 ├── src/                      # Source code (JS, CSS)
 ├── inc/                      # PHP includes
 ├── tests/                    # Test files
 ├── bin/                      # Build & utility scripts
-└── [other theme files]/
+└── [other theme folders]/
 ```
 
 ## File Categories & Locations

.github/custom-instructions.md docs/CUSTOM_INSTRUCTIONS.md.github/custom-instructions.md renamed to docs/CUSTOM_INSTRUCTIONS.md

@@ -0,0 +1,66 @@
+---
+title: Build & Automation Scripts
+description: Utility scripts for theme building, generation, and automation
+category: Project
+type: Index
+audience: Developers, Build Tools
+date: 2025-12-09
+---
+
+## Build & Automation Scripts
+
+This directory contains utility scripts for building, generating, and automating theme-related tasks.
+
+## Scripts
+
+### `agent-script.js`
+
+Orchestrates AI agent execution and coordination. Used by the build system to run agents for theme generation and validation.
+
+### `audit-frontmatter.js`
+
+Audits frontmatter metadata in documentation files. Ensures all markdown files have proper YAML frontmatter with required fields (title, description, category, type, audience, date).
+
+### `block-theme-build.agent.js`
+
+The primary build agent for the block theme. Handles:
+
+- Theme compilation and validation
+- Block registration
+- Style processing
+- Configuration generation
+- Pre-commit linting validation in scaffold mode
+
+See [.github/agents/block-theme-build.agent.md](.github/agents/block-theme-build.agent.md) for full documentation.
+
+### `scaffold-generator.agent.js`
+
+Generates new block theme instances from the scaffold template. Used to create production themes from this scaffold with mustache variable replacement.
+
+**Usage:** Run as part of the generation workflow to:
+
+- Replace template variables ({{theme_slug}}, {{version}}, etc.)
+- Generate theme configuration
+- Create custom block and pattern files
+
+## Running Scripts
+
+Scripts are typically invoked through npm:
+
+```bash
+npm run build        # Uses block-theme-build.agent.js
+npm run generate     # Uses scaffold-generator.agent.js
+npm run lint:dry-run # Uses lint-dry-run.js (in bin/)
+```
+
+For direct execution:
+
+```bash
+node scripts/script-name.js [options]
+```
+
+## Related
+
+- [bin/](../bin/) - Main build and utility scripts
+- [.github/agents/](.github/agents/) - Agent specifications and documentation
+- [docs/BUILD_PROCESS.md](../docs/BUILD_PROCESS.md) - Build workflow documentation