chore: add AGENTS.md

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

AGENTS.md

@@ -0,0 +1,144 @@
+# AGENTS.md
+
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+## Project Overview
+
+The Coder Registry is a community-driven repository for Terraform modules and templates that extend Coder workspaces. It's organized with:
+- **Modules**: Individual components and tools (IDEs, auth integrations, dev tools)
+- **Templates**: Complete workspace configurations for different platforms
+- **Namespaces**: Each contributor has their own namespace under `/registry/[namespace]/`
+
+## Common Development Commands
+
+### Formatting
+```bash
+bun run fmt        # Format all code (Prettier + Terraform)
+bun run fmt:ci     # Check formatting (CI mode)
+```
+
+### Testing
+```bash
+# Test all modules with .tftest.hcl files
+./scripts/terraform_test_all.sh
+
+# Test specific module (from module directory)
+terraform init -upgrade
+terraform test -verbose
+
+# Validate Terraform syntax
+./scripts/terraform_validate.sh
+```
+
+### Module Creation
+```bash
+# Generate new module scaffold
+./scripts/new_module.sh namespace/module-name
+```
+
+### TypeScript Testing & Setup
+The repository uses Bun for TypeScript testing with utilities:
+- `test/test.ts` - Testing utilities for container management and Terraform operations
+- `setup.ts` - Test cleanup (removes .tfstate files and test containers)
+- Container-based testing with Docker for module validation
+
+## Architecture & Organization
+
+### Directory Structure
+```
+registry/[namespace]/
+├── README.md          # Contributor info with frontmatter
+├── .images/           # Namespace avatar (avatar.png/svg)
+├── modules/           # Individual components
+│   └── [module]/      # Each module has main.tf, README.md, tests
+└── templates/         # Complete workspace configs
+    └── [template]/    # Each template has main.tf, README.md
+```
+
+### Key Components
+
+**Module Structure**: Each module contains:
+- `main.tf` - Terraform implementation
+- `README.md` - Documentation with YAML frontmatter
+- `.tftest.hcl` - Terraform test files (required)
+- `run.sh` - Optional startup script
+
+**Template Structure**: Each template contains:
+- `main.tf` - Complete Coder template configuration
+- `README.md` - Documentation with YAML frontmatter
+- Additional configs, scripts as needed
+
+### README Frontmatter Requirements
+All modules/templates require YAML frontmatter:
+```yaml
+---
+display_name: "Module Name"
+description: "Brief description"
+icon: "../../../../.icons/tool.svg"
+verified: false
+tags: ["tag1", "tag2"]
+---
+```
+
+## Testing Requirements
+
+### Module Testing
+- Every module MUST have `.tftest.hcl` test files
+- Tests use Docker containers with `--network=host` flag
+- Linux required for testing (Docker Desktop on macOS/Windows won't work)
+- Use Colima or OrbStack on macOS instead of Docker Desktop
+
+### Test Utilities
+The `test/test.ts` file provides:
+- `runTerraformApply()` - Execute Terraform with variables
+- `executeScriptInContainer()` - Run coder_script resources in containers
+- `testRequiredVariables()` - Validate required variables
+- Container management functions
+
+## Validation & Quality
+
+### Automated Validation
+The Go validation tool (`cmd/readmevalidation/`) checks:
+- Repository structure integrity  
+- Contributor README files
+- Module and template documentation
+- Frontmatter format compliance
+
+### Versioning
+Use semantic versioning for modules:
+- **Patch** (1.2.3 → 1.2.4): Bug fixes
+- **Minor** (1.2.3 → 1.3.0): New features, adding inputs  
+- **Major** (1.2.3 → 2.0.0): Breaking changes
+
+## Dependencies & Tools
+
+### Required Tools
+- **Terraform** - Module development and testing
+- **Docker** - Container-based testing
+- **Bun** - JavaScript runtime for formatting/scripts
+- **Go 1.23+** - Validation tooling
+
+### Development Dependencies
+- Prettier with Terraform and shell plugins
+- TypeScript for test utilities
+- Various npm packages for documentation processing
+
+## Workflow Notes
+
+### Contributing Process
+1. Create namespace (first-time contributors)
+2. Generate module/template files using scripts
+3. Implement functionality and tests
+4. Run formatting and validation
+5. Submit PR with appropriate template
+
+### Testing Workflow
+- All modules must pass `terraform test`
+- Use `./scripts/terraform_test_all.sh` for comprehensive testing
+- Format code with `bun run fmt` before submission
+- Manual testing recommended for templates
+
+### Namespace Management
+- Each contributor gets unique namespace
+- Namespace avatar required (avatar.png/svg in .images/)
+- Namespace README with contributor info and frontmatter

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md