agent-primers cleanup

Author: MatrixManAtYrService

agent-primers/ci-workflow.md

@@ -30,7 +30,7 @@ The CI workflows trigger on:
 
 ### Workflow Jobs
 
-#### 1. **Lint and Analysis Job** (Implemented)
+#### 1. Lint and Analysis Job
 - **Runner**: `ubuntu-latest`
 - **Purpose**: Fast feedback on code quality
 - **File**: `.github/workflows/test.yml`
@@ -43,7 +43,7 @@ The CI workflows trigger on:
     - `nix run .#rust-analysis`
     - `nix run .#python-analysis`
 
-#### 2. **Test Job** (Implemented)
+#### 2. Test Job
 - **Runner**: `ubuntu-latest`
 - **Purpose**: Comprehensive testing across all environments
 - **File**: `.github/workflows/test.yml`
@@ -63,7 +63,7 @@ The CI workflows trigger on:
       - `pytest -m cli` (pytest-cli devshell)
   - Generate documentation: `nix run .#python-docs`
 
-#### 3. **Build htty-core Wheels Job** (Matrix Strategy) (Implemented)
+#### 3. Build htty-core Wheels Job (Matrix Strategy)
 - **Purpose**: Build htty-core wheels for multiple architectures
 - **File**: `.github/workflows/release.yml` (job: `build-htty-core-wheels`)
 - **Matrix Dimensions**:
@@ -97,7 +97,7 @@ The CI workflows trigger on:
   - Test wheel installation and functionality (native builds only)
   - Upload wheel as artifact
 
-#### 4. **Build htty Source Distribution Job** (Implemented)
+#### 4. Build htty Source Distribution Job
 - **Purpose**: Build htty pure Python source distribution
 - **File**: `.github/workflows/release.yml` (job: `build-htty-sdist`)
 - **Steps**:
@@ -106,7 +106,7 @@ The CI workflows trigger on:
   - Build htty source distribution: `nix build .#htty-sdist`
   - Upload source distribution as artifact
 
-#### 5. **Publish to PyPI Job** (Implemented)
+#### 5. Publish to PyPI Job
 - **Runner**: `ubuntu-latest`
 - **File**: `.github/workflows/release.yml` (job: `publish-to-pypi`)
 - **Dependencies**: Requires successful completion of both `build-htty-core-wheels` and `build-htty-sdist` jobs
@@ -123,27 +123,27 @@ The CI workflows trigger on:
 
 ### Cross-Compilation Implementation
 
-#### Current State (Implemented)
+#### Current State
 The `nix/packages/htty-core-wheel.nix` has been enhanced to support cross-compilation for all target architectures using maturin best practices.
 
 #### Implemented Features in `htty-core-wheel.nix`
 
-1. **Target system parameter** (✅ Implemented):
+1. Target system parameter:
    ```nix
    { inputs, pkgs, targetSystem ? null, ... }:
    ```
 
-2. **Cross-compilation detection** (✅ Implemented):
+2. Cross-compilation detection:
    - Detects when `targetSystem` is different from `pkgs.stdenv.hostPlatform.system`
    - Sets up appropriate Rust target mapping
    - Configures Rust toolchain with required targets
 
-3. **Maturin with Zig cross-compilation** (✅ Implemented):
-   - Uses `maturin build --zig` for cross-compilation (following maturin best practices)
+3. Maturin with Zig cross-compilation:
+   - Uses `maturin build --zig` for cross-compilation
    - Automatic cross-compilation toolchain via Zig
    - No manual GCC/linker configuration needed
 
-4. **Target platform mappings** (✅ Implemented):
+4. Target platform mappings:
    ```nix
    rustTargetMap = {
      "aarch64-linux" = "aarch64-unknown-linux-gnu";
@@ -153,16 +153,16 @@ The `nix/packages/htty-core-wheel.nix` has been enhanced to support cross-compil
    };
    ```
 
-### CI Infrastructure (Implemented)
+### CI Infrastructure
 
-#### Nix Setup and Caching (✅ Implemented)
+#### Nix Setup and Caching
 - **File**: `.github/actions/setup-nix/action.yml`
 - Uses `nixbuild/nix-quick-install-action@v30` for Nix installation
 - Uses `nix-community/cache-nix-action@v6` for Nix store caching
 - Cache key: `nix-store-${{ runner.os }}-${{ hashFiles('**/flake.lock') }}`
 - Garbage collection: Keep store under 8GB before caching
 
-#### Artifact Management (✅ Implemented)
+#### Artifact Management
 - Upload each htty-core wheel with platform-specific artifact names (`htty-core-wheel-{system}`)
 - Upload htty source distribution as separate artifact (`htty-sdist`)
 - Merge all artifacts in the publish job using `merge-multiple: true`
@@ -175,33 +175,33 @@ The `nix/packages/htty-core-wheel.nix` has been enhanced to support cross-compil
 - Both packages should maintain synchronized versions
 - CI should validate version consistency across packages
 
-#### Publishing Strategy (✅ Implemented)
+#### Publishing Strategy
 - **htty-core**: Publish architecture-specific wheels for each supported platform (4 wheels)
 - **htty**: Publish single source distribution that depends on htty-core (1 sdist)
-- Uses PyPI's trusted publishing with OIDC for secure, keyless publishing
+- Uses PyPI's trusted publishing with OIDC for keyless publishing
 - Supports dry-run mode for testing releases
 
-#### Supported Platforms (✅ Implemented)
-Following the same strategy as polars and other Rust-based Python packages:
+#### Supported Platforms
+Builds packages for these platforms:
 - **Linux**: x86_64, aarch64 (cross-compiled with maturin --zig)
 - **macOS**: x86_64 (Intel), aarch64 (Apple Silicon)
 - **Windows**: Not currently supported (can be added later)
 
-### Security and Best Practices (✅ Implemented)
+### Security and Best Practices
 
-#### Trusted Publishing (✅ Implemented)
+#### Trusted Publishing
 - Uses PyPI's trusted publishing instead of API tokens
 - Requires GitHub repository to be configured as trusted publisher in PyPI
 - Uses `id-token: write` permission for OIDC authentication
 - Environment: `release` for additional protection
 
-#### Artifact Verification (✅ Implemented)
+#### Artifact Verification
 - Verifies expected number of packages (4 wheels + 1 sdist)
 - Tests wheel installation on native platforms before publishing
 - Shows package details and sizes before publishing
 - Validates artifact completeness across matrix builds
 
-#### Secrets Management (✅ Implemented)
+#### Secrets Management
 - No API keys or tokens stored in repository
 - All authentication handled via OIDC trusted publishing
 - Cross-compilation tooling (Zig) installed via Nix packages
@@ -226,7 +226,7 @@ Following the same strategy as polars and other Rust-based Python packages:
 
 ### ✅ Completed Implementation
 
-All major phases of the CI workflow have been successfully implemented:
+All major phases of the CI workflow have been implemented:
 
 #### Phase 1: Cross-Compilation Setup (✅ Complete)
 - ✅ Enhanced `nix/packages/htty-core-wheel.nix` with cross-compilation support
@@ -246,7 +246,7 @@ All major phases of the CI workflow have been successfully implemented:
 - ✅ PyPI trusted publishing configuration
 - ✅ Dry-run support for testing releases
 
-### 🚧 Remaining Work
+### Remaining Work
 
 #### Phase 2: Version Management System (Future Enhancement)
 - Create `nix/lib/version.nix` as single source of truth for version information
@@ -259,14 +259,14 @@ All major phases of the CI workflow have been successfully implemented:
 - Additional platforms (Windows support)
 - Additional quality gates (coverage, benchmarks, security scanning)
 
-### 🎯 Current Status
+### Current Status
 
-The CI workflow is **fully functional and ready for production use**. It provides:
+The CI workflow is functional. It provides:
 
-- ✅ **Comprehensive testing** across all environments on every PR
-- ✅ **Multi-architecture builds** with cross-compilation
-- ✅ **Secure PyPI publishing** with trusted publishing
-- ✅ **Two-package distribution** (htty-core + htty)
-- ✅ **Dry-run capabilities** for testing releases
+- Testing across all environments on every PR
+- Multi-architecture builds with cross-compilation
+- PyPI publishing with trusted publishing
+- Two-package distribution (htty-core + htty)
+- Dry-run capabilities for testing releases
 
-The implementation follows maturin best practices and mirrors successful Rust-Python projects like polars, ensuring reliable and efficient CI/CD for the htty project.
+The implementation uses maturin for building Python wheels with Rust components.

agent-primers/codegen.md

@@ -2,13 +2,13 @@
 
 ## Overview
 
-The htty project uses [Cog](https://nedbatchelder.com/code/cog/) for automated code generation to maintain consistency across multiple languages (Rust, Python) and file formats (TOML, source files). This ensures that constants and version information stay synchronized throughout the codebase.
+The htty project uses [Cog](https://nedbatchelder.com/code/cog/) for automated code generation to maintain consistency across multiple languages (Rust, Python) and file formats (TOML, source files). Constants and version information are synchronized throughout the codebase.
 
 ## Architecture
 
 ### Central Source Files
 
-The code generation system is driven by two central Nix files that serve as the single source of truth:
+The code generation system is driven by two central Nix files:
 
 #### 1. `nix/lib/version.nix` - Version Management
 Contains all version-related information for the project:
@@ -30,9 +30,9 @@ Contains all version-related information for the project:
 }
 ```
 
-**Key Features:**
-- Single source of truth for all version information
-- Automatic git SHA integration
+Features:
+- Central version information
+- Git SHA integration
 - Python PEP 440 compatible prerelease format
 - Package-specific version formatting
 
@@ -61,10 +61,10 @@ Contains all shared constants used across the codebase:
 }
 ```
 
-**Key Features:**
-- Centralized configuration for the entire project
+Features:
+- Centralized configuration for the project
 - Language-agnostic constant definitions
-- Comprehensive documentation with usage references
+- Documentation with usage references
 - Consistent naming conventions
 
 ### Code Generation Process
@@ -91,7 +91,7 @@ Used to import constants from Nix environment variables:
 //[[[end]]]
 ```
 
-**Purpose**: Loads constants from environment variables into Cog variables for use in generation blocks.
+Purpose: Loads constants from environment variables into Cog variables for use in generation blocks.
 
 ### Code Generation Block
 
@@ -107,7 +107,7 @@ pub const DEFAULT_TERMINAL_ROWS: u16 = 30;
 //[[[end]]]
 ```
 
-**Purpose**: Generates the actual code that gets compiled/executed. The content between the block markers is automatically updated.
+Purpose: Generates the actual code that gets compiled/executed. The content between the block markers is automatically updated.
 
 ### Version Block (Simple)
 
@@ -122,32 +122,32 @@ version = "0.2.1-dev202507140024"
 # [[[end]]]
 ```
 
-**Purpose**: Inserts version strings into configuration files.
+Purpose: Inserts version strings into configuration files.
 
 ## File Types and Patterns
 
 ### Rust Files (`*.rs`)
 
-**Comments**: Use `//` and `/**/` comment styles
-**Pattern**: Import environment variables, then generate constants
-**Example files**:
+Comments: Use `//` and `/**/` comment styles
+Pattern: Import environment variables, then generate constants
+Example files:
 - `htty-core/src/rust/constants.rs` - Project constants
 - `htty-core/src/rust/cli.rs` - Version info for `--version` flag
 
 ### Python Files (`*.py`)
 
-**Comments**: Use `#` comment style
-**Pattern**: Similar to Rust but with Python syntax
-**Example files**:
+Comments: Use `#` comment style
+Pattern: Similar to Rust but with Python syntax
+Example files:
 - `htty/src/htty/constants.py` - Project constants
 - `htty/src/htty/cli.py` - Version info for `--version` flag
 - `htty/src/htty/__init__.py` - Module version
 
 ### Configuration Files (`*.toml`)
 
-**Comments**: Use `#` comment style
-**Pattern**: Simple version insertion, no complex logic
-**Example files**:
+Comments: Use `#` comment style
+Pattern: Simple version insertion, no complex logic
+Example files:
 - `htty-core/Cargo.toml` - Rust package version
 - `htty-core/pyproject.toml` - Python package version (htty-core)
 - `htty/pyproject.toml` - Python package version (htty)
@@ -189,7 +189,7 @@ The Nix build system automatically converts constants to environment variables:
 
 ### Constants Files
 
-**Rust**: `htty-core/src/rust/constants.rs`
+Rust: `htty-core/src/rust/constants.rs`
 ```rust
 // Terminal configuration
 pub const DEFAULT_TERMINAL_COLS: u16 = 60;
@@ -199,7 +199,7 @@ pub const DEFAULT_TERMINAL_ROWS: u16 = 30;
 pub const COORDINATION_DELAY: Duration = Duration::from_millis(200);
 ```
 
-**Python**: `htty/src/htty/constants.py`
+Python: `htty/src/htty/constants.py`
 ```python
 # Terminal configuration
 DEFAULT_TERMINAL_COLS = 60
@@ -211,14 +211,14 @@ COORDINATION_DELAY_MS = 200
 
 ### Version Files
 
-**Cargo.toml**:
+Cargo.toml:
 ```toml
 [package]
 name = "htty_core"
 version = "0.2.1-dev202507140024"
 ```
 
-**Python __init__.py**:
+Python __init__.py:
 ```python
 __version__ = "0.2.1-dev202507140024"
 ```
@@ -234,20 +234,20 @@ Generated content is between Cog markers:
 //[[[end]]]
 ```
 
-**Always edit the source Nix files instead:**
+Always edit the source Nix files instead:
 - Edit `nix/lib/version.nix` for version changes
 - Edit `nix/lib/constants.nix` for constant changes
 - Run `nix run .#codegen` to regenerate
 
 ### Avoiding Cog Conflicts
 
-**Problem**: Type annotations with nested brackets can confuse Cog:
+Problem: Type annotations with nested brackets can confuse Cog:
 ```python
 # This breaks Cog because it ends with ]]]
 actions: list[tuple[str, Optional[str]]] = []
 ```
 
-**Solution**: Use type aliases:
+Solution: Use type aliases:
 ```python
 # At module level
 ActionTuple: TypeAlias = tuple[str, Optional[str]]
@@ -258,12 +258,12 @@ actions: list[ActionTuple] = []
 
 ### Version Format Requirements
 
-**Python**: Must follow PEP 440
-- ✅ `0.2.1-dev202507140024` (prerelease with timestamp)
-- ✅ `0.2.1` (stable release)
+Python: Must follow PEP 440
+- `0.2.1-dev202507140024` (prerelease with timestamp)
+- `0.2.1` (stable release)
 - ❌ `0.2.1-2025-July-14-00-24` (month names not allowed)
 
-**Rust**: More flexible, but we use same format for consistency
+Rust: More flexible, but we use same format for consistency
 
 ### Environment Variable Access