Implement persistent and scoped environment variable management

.augment/rules/build-all.md

@@ -0,0 +1,31 @@
+---
+type: "manual"
+---
+
+# Complete Atom Project Build
+
+Build the entire Atom project from scratch using the CMake build system.
+During the build process:
+
+1. Execute a complete build of all project components
+2. Identify and document every error, warning, or build failure
+3. For each issue encountered:
+   - Investigate the root cause thoroughly using available tools
+   - Implement a proper, complete fix (no placeholders, no TODOs)
+   - Verify the fix resolves the issue
+4. Continue iterating through the build-fix cycle until the entire project
+   builds successfully with zero errors
+5. Do not skip any errors or leave any issues unresolved
+6. Provide a summary of all issues found and how each was resolved
+
+## Requirements
+
+- Use the existing CMake configuration in the project
+- Apply real, working solutions only - no temporary workarounds
+- Ensure all downstream changes are made (update all callers, tests)
+- Verify the final build completes successfully before concluding
+
+## Goal
+
+A fully functional, clean build of the entire Atom project with all
+compilation issues genuinely resolved.

.augment/rules/build-examples-fix.md

@@ -0,0 +1,61 @@
+---
+type: "manual"
+---
+
+# Build All Example Projects
+
+Build all example projects in the Atom repository's `example/` directory using
+the MSVC compiler and vcpkg dependency manager. For each example, perform a
+complete build cycle and systematically resolve any compilation, linking, or
+runtime issues encountered.
+
+## Specific Requirements
+
+1. **Discovery Phase:**
+   - Identify all example projects/subdirectories within `example/`
+   - Determine the build system used for each example (CMake targets, standalone projects, etc.)
+   - Verify which Atom modules each example depends on
+
+2. **Build Process:**
+   - Configure and build each example using the MSVC toolchain with vcpkg
+   - Use appropriate CMake presets or build commands consistent with the project's build system
+   - Enable parallel compilation where possible
+   - Build in both Debug and Release configurations if feasible
+
+3. **Issue Resolution:**
+   - Fix all compilation errors (syntax errors, missing headers, type mismatches)
+   - Resolve all linking errors (missing libraries, undefined symbols)
+   - Address MSVC-specific compatibility issues using conditional compilation
+   - Ensure cross-platform compatibility is maintained (don't break GCC/Clang)
+   - Install any missing dependencies through vcpkg or package managers
+
+4. **Verification:**
+   - Confirm each example executable builds successfully without errors
+   - If the examples have associated tests, run them to verify correctness
+   - If no automated tests exist, perform basic smoke testing by running each
+     example binary to ensure it executes without crashing
+
+5. **Documentation:**
+   - Track all changes made to fix build issues (file paths, errors, solutions)
+   - Note any new dependencies added or build configuration changes
+   - Document any platform-specific workarounds implemented
+
+## Expected Deliverables
+
+Provide a comprehensive summary containing:
+
+- **Examples Built:** Complete list of all example projects found and their
+  build status (success/failure)
+- **Issues Encountered:** Detailed description of each build error, linking
+  error, or runtime issue discovered
+- **Resolutions Applied:** Specific fixes implemented for each issue (code
+  changes, dependency installations, configuration updates)
+- **Verification Results:** Confirmation that each example compiles, links,
+  and runs successfully
+- **Build Artifacts:** Location of generated executables and any relevant
+  build outputs
+- **Compatibility Notes:** Any MSVC-specific changes made and verification
+  that cross-platform compatibility is preserved
+
+Focus on achieving a complete, successful build of all examples while
+maintaining code quality and cross-platform compatibility.

.augment/rules/build-linux.md

@@ -0,0 +1,33 @@
+---
+type: "manual"
+---
+
+# Linux-Style Build Configuration
+
+Build the entire Atom project using Linux-style build configuration
+(GCC/Clang toolchain) on the current Windows environment. During the build
+process:
+
+1. Configure the project to use a Linux-compatible build approach (e.g.,
+   using MinGW, WSL, or similar Unix-like environment)
+2. Attempt a complete build of all modules and components
+3. Identify and fix ALL compilation errors, linking errors, and build
+   failures that occur
+4. Pay special attention to platform-specific and compiler-specific
+   compatibility issues between different toolchains (MSVC vs GCC/MinGW)
+5. When encountering compiler-specific incompatibilities, use preprocessor
+   macros to conditionally compile code based on the compiler and platform:
+   - Use `#ifdef _MSC_VER` for MSVC-specific code
+   - Use `#ifdef __GNUC__` for GCC/MinGW-specific code
+   - Use `#ifdef __clang__` for Clang-specific code
+   - Use `#ifdef _WIN32` or `#ifdef __linux__` for platform-specific code
+6. Ensure that the fixes maintain cross-platform compatibility and don't
+   break builds on other platforms/compilers
+7. Document any significant changes or workarounds needed for Linux-style
+   build compatibility
+
+## Goal
+
+Achieve a successful, complete build of the Atom project using Linux-compatible
+build tools while maintaining compatibility with other build environments
+(especially MSVC) through appropriate use of conditional compilation.

.augment/rules/build-mingw.md

@@ -0,0 +1,39 @@
+---
+type: "manual"
+---
+
+# MinGW64 Build Configuration
+
+Build the entire Atom project using the MSYS2 (MinGW64) preset and resolve
+all compilation/linking issues that arise during the build process.
+
+## Specific Requirements
+
+1. **Build Configuration:**
+   - Use the MSYS2 MinGW64 environment (not MSVC)
+   - Configure CMake to use the MinGW64 compiler toolchain
+   - Ensure all build presets and scripts work correctly with MinGW64
+
+2. **Issue Resolution:**
+   - Fix ALL compilation errors, warnings, and linking issues encountered
+   - Address any platform-specific incompatibilities between MSVC and MinGW/GCC
+   - Resolve any missing dependencies or library linking problems
+
+3. **Cross-Compiler Compatibility:**
+   - When encountering code that is incompatible between MSVC and MinGW/GCC,
+     use preprocessor macros to distinguish between environments
+   - Use appropriate compiler detection macros such as:
+     - `#ifdef _MSC_VER` for MSVC-specific code
+     - `#ifdef __GNUC__` or `#ifdef __MINGW64__` for MinGW/GCC-specific code
+   - Ensure the codebase remains compatible with both MSVC and MinGW64
+
+4. **Testing:**
+   - Verify that the build completes successfully without errors
+   - Ensure all modules compile and link correctly
+   - Test that the built binaries function properly
+
+## Expected Outcome
+
+A fully functional build of the Atom project using MSYS2 MinGW64, with all
+compiler-specific issues resolved through appropriate conditional compilation
+directives, maintaining cross-platform compatibility.

.augment/rules/build-mix.md

@@ -0,0 +1,45 @@
+---
+type: "manual"
+---
+
+# Cross-Compilation Build
+
+Build the entire Atom project using cross-compilation mode and resolve all
+compilation, linking, and configuration issues that arise during the build
+process.
+
+## Specific Requirements
+
+1. **Cross-Compilation Setup:**
+   - Identify and configure the appropriate cross-compilation toolchain
+   - Set up CMake toolchain files for cross-compilation if needed
+   - Configure build system to use cross-compiler instead of native
+
+2. **Build Execution:**
+   - Attempt a complete cross-compilation build of all modules
+   - Use appropriate CMake configuration flags for cross-compilation
+   - Example: `CMAKE_TOOLCHAIN_FILE`, `CMAKE_SYSTEM_NAME`,
+     `CMAKE_SYSTEM_PROCESSOR`
+
+3. **Issue Resolution:**
+   - Fix ALL compilation errors during cross-compilation
+   - Resolve linking errors related to cross-platform libraries
+   - Address platform-specific incompatibilities (endianness, word size, ABI)
+   - Handle missing or incompatible dependencies for target platform
+   - Fix architecture-specific code issues (x86 vs ARM, 32-bit vs 64-bit)
+
+4. **Platform Compatibility:**
+   - Ensure proper handling of platform-specific code paths
+   - Verify that all dependencies are available for target platform
+   - Address system library differences between host and target
+
+5. **Verification:**
+   - Confirm cross-compilation build completes successfully
+   - Verify all modules compile and link correctly for target platform
+   - Document cross-compilation configuration and changes made
+
+## Expected Outcome
+
+A successful cross-compilation build of the Atom project for the target
+platform, with all cross-platform compatibility issues resolved and
+documented.

.augment/rules/build-msvc-vcpkg.md

@@ -0,0 +1,26 @@
+---
+type: "manual"
+---
+
+# MSVC Build with vcpkg
+
+Build the entire Atom project using MSVC (Microsoft Visual C++) compiler
+with vcpkg as the dependency manager. During the build process:
+
+1. Configure the project to use MSVC toolchain and vcpkg for dependencies
+2. Attempt a complete build of all modules and components
+3. Identify and fix ALL compilation, linking, and build failures
+4. Pay special attention to platform-specific compatibility issues between
+   MSVC and other compilers (MinGW, GCC, Clang)
+5. When encountering compiler-specific incompatibilities, use preprocessor
+   macros to conditionally compile code based on the compiler being used
+   (e.g., `#ifdef _MSC_VER` for MSVC, `#ifdef __GNUC__` for GCC/MinGW)
+6. Ensure that the fixes maintain cross-platform compatibility and don't
+   break builds on other platforms
+7. Document any significant changes or workarounds needed for MSVC
+
+## Goal
+
+Achieve a successful, complete build of the Atom project using the MSVC +
+vcpkg toolchain while maintaining compatibility with other build
+environments through appropriate use of conditional compilation.

.augment/rules/commit-fix.md

@@ -0,0 +1,34 @@
+---
+type: "manual"
+---
+
+# Complete Git Commit and Push
+
+Complete the git commit and push to the remote repository, fixing all
+pre-commit hook issues that arise during the process.
+
+## Requirements
+
+1. Stage all current changes for commit
+2. Attempt to commit the changes
+3. If pre-commit hooks fail, analyze and fix ALL issues reported by the hooks
+   (including but not limited to: linting errors, formatting issues, test
+   failures, type checking errors)
+4. Re-run the commit after fixes until pre-commit hooks pass successfully
+5. Push the committed changes to the remote repository
+6. Ensure that ALL existing functionality remains intact - do not break any
+   current features or tests while fixing pre-commit issues
+
+## Constraints
+
+- Use appropriate git commands for staging, committing, and pushing
+- Apply fixes that align with the project's coding standards and conventions
+- If pre-commit hooks include formatters (like clang-format, black, etc.),
+  allow them to auto-fix when possible
+- Verify that all tests still pass after applying fixes
+- Do not skip or bypass pre-commit hooks - all issues must be properly
+  resolved
+
+Note: The instruction is in Chinese. Translation: "Complete this commit to
+remote, and fix all pre-commit issues encountered, without affecting existing
+functionality"

.augment/rules/complete-missing-files.md

@@ -0,0 +1,43 @@
+---
+type: "manual"
+---
+
+# Complete Missing Standard Files
+
+Complete all standard files required for a professional GitHub repository for
+the Atom project. Ensure the following:
+
+## Essential GitHub Files
+
+Create or update as needed:
+
+- `.gitignore` - Comprehensive ignore patterns for C++, Python, CMake build
+  artifacts, IDE files, and platform-specific files
+- `LICENSE` - Appropriate open-source license file (if not already present)
+- `CONTRIBUTING.md` - Contribution guidelines including code style, commit
+  conventions, PR process, and testing requirements
+- `CODE_OF_CONDUCT.md` - Community code of conduct
+- `.github/ISSUE_TEMPLATE/` - Issue templates for bug reports and feature
+  requests
+- `.github/PULL_REQUEST_TEMPLATE.md` - Pull request template
+- `CHANGELOG.md` - Version history and release notes (if applicable)
+
+## Quality Standards
+
+- All files should follow industry best practices and conventions
+- Content should be accurate, professional, and reflect the actual project
+  structure
+- Reference existing project documentation (README.md, AGENTS.md, CLAUDE.md,
+  STYLE_OF_CODE.md) for consistency
+- Ensure all templates and guidelines align with the project's C++/Python
+  nature and CMake build system
+
+## Verification
+
+- Review existing files first to avoid duplication
+- Ensure all content is relevant to the Atom astronomical software library
+  project
+- Maintain consistency with the project's existing coding standards
+
+Do NOT create files that already exist with adequate content. Only create or
+update files that are missing or incomplete.