coder · matifali · Jan 20, 2026 · Jan 17, 2026 · Jan 17, 2026 · Jan 17, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,168 +1,41 @@
 # AGENTS.md
 
-This file provides guidance to AI coding assistants when working with code in this repository.
+Coder Registry: Terraform modules/templates for Coder workspaces under `registry/[namespace]/modules/` and `registry/[namespace]/templates/`.
 
-## 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
+## Commands
 
 ```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
-bun run test
-
-# 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"]
----
+bun run fmt                                           # Format code (Prettier + Terraform) - run before commits
+bun run tftest                                        # Run all Terraform tests
+bun run tstest                                        # Run all TypeScript tests
+terraform init -upgrade && terraform test -verbose    # Test single module (run from module dir)
+bun test main.test.ts                                 # Run single TS test (from module dir)
+./scripts/terraform_validate.sh                       # Validate Terraform syntax
+./scripts/new_module.sh ns/name                       # Create new module scaffold
+.github/scripts/version-bump.sh patch | minor | major # Bump module version after changes
 ```
 
-## Testing Requirements
-
-### Module Testing
-
-- Every module MUST have `.tftest.hcl` test files
-- Optional `main.test.ts` files for container-based testing or complex business logic validation
-- 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
+## Structure
 
-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
+- **Modules**: `registry/[ns]/modules/[name]/` with `main.tf`, `README.md` (YAML frontmatter), `.tftest.hcl` (required)
+- **Templates**: `registry/[ns]/templates/[name]/` with `main.tf`, `README.md`
+- **Validation**: `cmd/readmevalidation/` (Go) validates structure/frontmatter; URLs must be relative, not absolute
 
-### Testing Workflow
+## Code Style
 
-- All modules must pass `terraform test`
-- Use `bun run test` for comprehensive testing
-- Format code with `bun run fmt` before submission
-- Manual testing recommended for templates
+- Every module MUST have `.tftest.hcl` tests; optional `main.test.ts` for container/script tests
+- README frontmatter: `display_name`, `description`, `icon`, `verified: false`, `tags`
+- Use semantic versioning; bump version via script when modifying modules
+- Docker tests require Linux or Colima/OrbStack (not Docker Desktop)
+- Use `tf` (not `hcl`) for code blocks in README; use relative icon paths (e.g., `../../../../.icons/`)
 
-### Namespace Management
+## PR Review Checklist
 
-- Each contributor gets unique namespace
-- Namespace avatar required (avatar.png/svg in .images/)
-- Namespace README with contributor info and frontmatter
+- Version bumped via `.github/scripts/version-bump.sh` if module changed (patch=bugfix, minor=feature, major=breaking)
+- Breaking changes documented: removed inputs, changed defaults, new required variables
+- New variables have sensible defaults to maintain backward compatibility
+- Tests pass (`bun run tftest`, `bun run tstest`); add diagnostic logging for test failures
+- README examples updated with new version number; tooltip/behavior changes noted
+- Shell scripts handle errors gracefully (use `|| echo "Warning..."` for non-fatal failures)
+- No hardcoded values that should be configurable; no absolute URLs (use relative paths)
+- If AI-assisted: include model and tool/agent name at footer of PR body (e.g., "Generated with [Amp](thread-url) using Claude")