docs: separate user guide from contrib guide (#477)

* More cleanly separates our "Users Guide" from our "Developer Guide" (for internal azldev contributions).
* Refreshes root-level repo .md files.
* Fixes broken links.

Author: reubeno

CHANGELOG.md

@@ -7,3 +7,4 @@ Resources:
 - [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
 - [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
 - Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns
+- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support)

CODE_OF_CONDUCT.md

@@ -1,286 +1,23 @@
-# Contributing to azldev-preview
+# Contribution Guidelines
 
-Thank you for your interest in contributing to the azldev-preview project! This document provides guidelines and standards that all contributors should follow.
+## Contributing License Agreement
 
-## Code of Conduct
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com).
 
-This project follows Microsoft's Open Source Code of Conduct, see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for details.
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
 
-## License
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
 
-By contributing to this project, you agree that your contributions will be licensed under the same license as the project (MIT License).
+## Security
 
-### Contribution License Agreement (CLA)
+Please review our project's [Security Guidelines](./SECURITY.md).
 
-This project welcomes contributions from the community. Most contributions require you to sign a Contribution License Agreement (CLA) to clarify the terms under which contributions are made (you have the right to, and do, grant us a license to use your contributions). For more details, visit
-[Microsoft's CLA page](https://cla.microsoft.com/).
+## Development
 
-When you submit a pull request, if you have not already done so, you will be prompted to sign the CLA.
-
-## Getting Started
-
-### Prerequisites
-
-- **Go 1.25+** - Required for building and running the application
-- **Git** - For version control and submitting changes
-- **Mage** - Our build automation tool
-
-  ```bash
-  # Mage is not technically required, the build tools may also be invoked
-  # directly via `go run magefile.go` or `./magefile.go`
-  go install github.com/magefile/mage@latest
-  ```
-
-### Initial Setup
-
-1. Fork the repository (strongly recommended for all contributors)
-2. Clone your fork locally
-3. Install dependencies:
-
-   ```bash
-   dnf install -y golang
-   ```
-
-4. Verify the build works:
-
-   ```bash
-   mage build
-   ```
-
-5. Install the built tools to your `$GOPATH/bin` directory:
-
-   ```bash
-   mage install
-   ```
-
-   After running `mage install`, the tools will be available in your `$GOPATH/bin` directory.
-   Not all systems will have this directory in their `$PATH` by default, so you may need to add it.
-
-#### Azure Linux 3.0 as a development host
-
-```bash
-# These instructions work for AzureLinux (https://github.com/microsoft/azurelinux)
-# While the tools should build and run on any system with golang installed, some of the runtime dependencies
-# may not be available on all systems (e.g., `mock`).
-tdnf install -y golang ca-certificates glibc-devel
-
-git clone <URL>
-cd <REPO>
-
-# You may want to permanently add $GOPATH/bin to your $PATH via
-#     echo 'export GOPATH=$(go env GOPATH)' >> $HOME/.bashrc
-#     echo 'export PATH=$PATH:${GOPATH}/bin' >> $HOME/.bashrc
-export GOPATH=$(go env GOPATH)
-export PATH=$PATH:${GOPATH}/bin
-go install github.com/magefile/mage@latest
-mage build
-mage install
-```
-
-## Build Reference
-
-All code in this repo is written in `golang`. The `golang` package is required to build and run the tools.
-
-The build system uses mage, which can be installed with `go install github.com/magefile/mage@latest`. Alternatively, a zero-install approach is available through `go run magefile.go` or `./magefile.go`, which automatically downloads the required dependencies without manual installation. All additional build tools are managed automatically by go, and no manual tool installation is required.
-
-All other tooling dependencies are handled by `go tool`, which will automatically get the required tools when using `mage`. See [the tools section](./tools/README.md) for more information.
-
-This repo contains configs for the `golangci-lint` linter. It is installed as part of the [VSCode go extension](https://marketplace.visualstudio.com/items?itemName=golang.go). It's also optionally available as a [binary release](https://golangci-lint.run/welcome/install/#local-installation).
-
-### Mage Commands
-
-| Command | Description | When to Use |
-|---------|-------------|-------------|
-| `mage -l` | List all available targets | To see all options |
-| `mage all` | Full build, test, and check pipeline | Before submitting PR |
-| `mage build` | Build Go binaries | After code changes |
-| `mage install` | Build Go binaries and install | Outer-loop testing |
-| `mage unit` | Run unit tests | After writing tests |
-| `mage scenario` | Run scenario tests (SLOW) | For major changes |
-| `mage scenarioUpdate` | Update test snapshots | When test expectations change |
-| `mage check all` | Run all quality checks | Before committing |
-| `mage fix all` | Auto-fix code issues | When linting fails |
-| `mage generate` | Run code generation | Automatic with build/test |
-
-**Note**: Dependencies run automatically in correct order
-(i.e. `mage build` and `mage unit` automatically run code generation as needed).
-
-### Code Generation
-
-The project uses automatic code generation including:
-
-- `go:generate` directives
-- Stringer for enums
-- Schema generation
-- Mocks generated by `mockgen`
-
-You typically don't need to run `mage generate` manually as it's included in build dependencies.
-
-See [tools documentation](tools/README.md#invoking-the-tool-as-part-of-gogenerate) for more details on how to use tools with `go tool` in `go:generate` directives.
-
-## Ideal Development Workflow
-
-### Before Making Changes
-
-1. **Understand the codebase**: Review existing code patterns and architecture
-2. **Run the full test suite**: Execute `mage all` to ensure clean state
-3. **Create an issue**: For non-trivial changes, discuss the approach first
-
-### Making Changes
-
-1. **Create a feature branch**: Use descriptive names (e.g., `user/feature/add-config-validation`)
-2. **Write tests first**: Consider adding tests for new functionality before implementing
-3. **Follow coding standards**: See standards section below
-4. **Make incremental commits**: Use clear, descriptive commit messages following conventional commit format. Conventional commit naming will be enforced by the CI pipeline for the final PR title.
-
-### Validating Changes
-
-Before submitting, ensure your changes pass all checks:
-
-```bash
-mage all  # Comprehensive validation (will also invoke scenario tests, which will be slow)
-```
-
-For faster iteration during development:
-
-```bash
-mage build     # Rebuild the tool
-mage unit      # Fast unit tests
-mage check all # Code quality checks
-mage fix all   # Auto-fix issues
-```
-
-For scenario tests, use:
-
-```bash
-mage scenario  # Run all scenario tests (may take time)
-```
-
-To see all available Mage targets, run:
-
-```bash
-mage -l
-```
-
-## Coding Standards
-
-### Go Code Style
-
-- **Follow Go conventions**: Use `mage fix lint` for formatting (fallback: `gofmt`), and standard Go idioms
-- **Naming**: Use clear, descriptive names for variables, functions, and types
-- **Error handling**: Always handle errors appropriately with context. Use the following pattern:
-
-  ```go
-  // ErrOperationFailed is a global error for operation failures
-  var ErrOperationFailed = errors.New("operation failed")
-
-  // someOperation returns an error
-  func someOperation() error {
-      return fmt.Errorf("failed to connect to service: %w", ErrOperationFailed)
-  }
-
-  // Example usage in a function
-  func performOperation() error {
-      err := someOperation()
-      // Wrap the error with context
-      if err != nil {
-          return fmt.Errorf("performing operation: %w", err)
-      }
-      return nil
-  }
-  ```
-
-- **Comments**: Document exported functions, types, and complex logic
-- **Package organization**: Follow the existing package structure
-- **String formatting**: Prefer `%#q` format specifier for strings
-
-### Code Quality Requirements
-
-- **Linting**: All code must pass `golangci-lint` checks (use `mage check lint` and `mage fix lint` to fix some issues automatically)
-  - Avoid using `//nolint` comments unless absolutely necessary. If you must use it, specify the linter (e.g., `//nolint:golint`).
-- **Testing**: New functionality requires unit tests
-- **Coverage**: Maintain reasonable test coverage for critical paths
-- **Documentation**: Update relevant documentation for user-facing changes
-
-### File Organization
-
-- **Business logic**: Place in `internal/` packages
-- **Command handlers**: Keep minimal logic in `cmd/` packages
-- **Unit Tests**: Co-locate with source files using `_test.go` suffix
-- **Scenario Tests**: Use `scenario/` for scenario tests
-- **Configuration**: Use TOML format, provide defaults in `defaultconfigs/`
-
-### Command Structure
-
-- See [azldev command guidelines](docs/reference/command-guidelines.md) for details on command structure and naming conventions.
-
-### Logging Guidelines
-
-- Use structured logging with the `slog` package
-- Include relevant context in log messages
-- Use appropriate log levels (Debug, Info, Warn, Error)
-
-## Testing
-
-Testing can be run with `mage`, or directly using `go test`. The `mage` build system is preferred as it can also automatically run the scenario tests and update the test expectations.
-
-```bash
-# Run the unit tests
-mage unit
-
-# Run the coverage tests, producing an .html report
-mage coverage
-
-# Run scenario tests
-mage scenario
-```
-
-See the [testing documentation](docs/how-to/testing.md) for detailed guidelines on writing and running tests.
-
-## Pull Request Process
-
-### Before Submitting
-
-- [ ] `mage all` passes successfully
-- [ ] Code follows the style guidelines
-- [ ] Documentation is updated if needed
-- [ ] All dynamically generated code is covered by `mage generate`
-- [ ] Update [CHANGELOG.md](CHANGELOG.md) with your changes
-
-### PR Guidelines
-
-- **Title**: Use a clear, descriptive title following conventional commit format (e.g., `feat: add user authentication`, `fix: resolve memory leak in parser`, `docs: update installation guide`)
-- **Description**: Explain what changes were made and why
-- **Testing**: Describe how the changes were tested
-- **Breaking changes**: Clearly document any breaking changes
-
-## Configuration Management
-
-### Adding New Configuration
-
-- Add schema definitions to appropriate config structs
-- Provide sensible defaults in `defaultconfigs/`
-- Update configuration documentation if user-facing
-- Test configuration loading and validation
-
-### Configuration Best Practices
-
-- Use TOML format for configuration files
-- Validate configuration early in application startup
-- Provide clear error messages for invalid configurations
-- Support environment variable overrides where appropriate
-
-## Troubleshooting
-
-### Common Issues
-
-- **Build failures**: Ensure Go version is 1.25+ and all dependencies are installed. Try running `mage build -v`. Ensure `GOPATH` is configured.
-- **Test failures**: Run `mage generate` to ensure generated code is up to date
-- **Lint errors**: Address specific linting issues or discuss exceptions with maintainers
-- **Command not found**: Run `mage install`, ensure `GOPATH` is in your `$PATH`.
-
-## Questions and Support
-
-If you have any questions about contributing, please open an issue in the repository.
-
-Thank you for contributing to azldev-preview!
+Please consult our [Developer Guide](./docs/developer/)

CONTRIBUTING.md

@@ -1,21 +1,21 @@
-    MIT License
+MIT License
 
-    Copyright (c) Microsoft Corporation.
+Copyright (c) Microsoft Corporation.
 
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE