# c65gm Agent Instructions

## Project Overview
c65gm is a high-level 6502 cross-compiler targeting the ACME Cross-Assembler for Commodore 64 and similar 6502-based platforms. It provides a more expressive language for writing 6502 assembly programs with modern programming constructs.

## Key Documentation Locations

### Primary Documentation
1. **README.md** - Project overview, building, usage, and requirements
2. **language.md** - Complete language reference with examples (1091 lines)
3. **syntax.md** - Syntax rules and preprocessor directives (646 lines)
4. **commands.md** - Complete command reference (776 lines)

### Code Structure
- **main.go** - Entry point and command-line interface
- **internal/compiler/** - Core compiler implementation
- **internal/preproc/** - Preprocessor implementation
- **internal/commands/** - Individual command implementations
- **internal/utils/** - Utility functions
- **lib/** - Standard library files for C64 development
- **examples/** - Example programs demonstrating language features

### Standard Library (lib/)
- **c64start.c65** - Required for C64 executables (BASIC loader setup)
- **c64defs.c65** - C64 hardware definitions (colors, addresses, etc.)
- **c64kernal.c65** - Kernal routine wrappers
- **c64scr.c65** - Screen manipulation functions
- **string.c65** - String handling functions
- **memlib.c65** - Memory management functions
- **fat16/** - FAT16 filesystem support
- **koalalib.c65** - Koala graphics support

## Language Features to Note

### Key Concepts
1. **Type system**: BYTE (8-bit) and WORD (16-bit) variables with scope resolution
2. **Functions**: Named functions with parameters and call graph analysis
3. **Control flow**: IF/ENDIF, WHILE/WEND, FOR loops, SWITCH/CASE
4. **Memory operations**: PEEK/POKE/PEEKW/POKEW with zero-page optimization
5. **Preprocessor**: File inclusion, macros, conditional compilation, Starlark scripting
6. **Optimizations**: Constant folding, self-assignment detection
7. **Safety features**: Compile-time detection of overlapping absolute addresses

### Important Syntax Rules
1. **No operator precedence**: Expressions evaluate strictly left-to-right
2. **Memory-mapped variables**: Use `@` to place variables at specific addresses
3. **Constants**: Prefer `BYTE CONST`/`WORD CONST` over `#DEFINE`
4. **Zero-page optimization**: Place frequently accessed pointers in zero page ($00-$FF)
5. **Include guards**: Always use `#IFNDEF` in library files

### Special Blocks
1. **ASM blocks**: Inline assembly code
2. **SCRIPT blocks**: Starlark code for compile-time code generation
3. **SCRIPT LIBRARY blocks**: Reusable Starlark functions
4. **SCRIPT MACRO blocks**: Parameterized macros for inline expansion

## Common Patterns

### Program Structure
```c65
#INCLUDE <c64start.c65>
#INCLUDE <c64defs.c65>

GOTO start  // Jump over function definitions

// Variables and functions here

LABEL start  // Program entry point
main()
```

### Library Structure
```c65
#IFNDEF __MY_LIBRARY
#DEFINE __MY_LIBRARY = 1

GOTO lib_mylib_skip

// Library code here

LABEL lib_mylib_skip
#IFEND
```

### Memory Operations
- Use `PEEK`/`POKE` for byte access
- Use `PEEKW`/`POKEW` for word (16-bit) access
- For indexed access, address must be a WORD variable in zero page

## Development Guidelines

### Environment Constraints
**Go is available**: The container has Go installed. The agent can run `go build`, `go test`, and other Go commands directly. However, always rebuild the Docker image first if you update the Dockerfile:

```bash
docker compose build
```

Then recreate the container: `docker compose up -d`.

### File Access Restrictions
**CRITICAL**: The agent must only access normal project files within the current working directory. The agent must NEVER:
1. Look at files outside the project directory (e.g., `/tmp/`, `/etc/`, `/home/`, etc.)
2. Read or attempt to access system files, environment files (`.env`), or configuration files outside the project
3. Search for or read files containing secrets, credentials, or sensitive information
4. Attempt to access files in parent directories or unrelated paths

All file operations must be restricted to the project's source code and documentation files only.

### When Modifying the Compiler
1. Check `internal/commands/` for command implementations
2. Check `internal/compiler/` for core compiler logic
3. Check `internal/preproc/` for preprocessor functionality
4. **DO NOT run tests** - provide instructions for the user to run tests

### When Adding New Features
1. Follow existing patterns in command implementations
2. Add comprehensive tests
3. Update documentation in appropriate .md files
4. Consider adding examples in `examples/` directory

### Testing and Rebuilding
**Go is available**: The agent can compile code and run tests directly.

#### Testing:
- Run all tests: `go test ./...`
- Run specific package tests: `go test ./internal/compiler`
- Test with verbose output: `go test -v ./...`
- Run specific test functions: `go test ./internal/compiler -v -run "TestMultiFuncGroup"`

#### Rebuilding c65gm:
Library files (`lib/*.c65`) are embedded into the binary at build time. After modifying any `.c65` file in `lib/`, you MUST use `build_c65gm.sh` (not `go build` directly) to ensure the updated library is embedded. The agent should:
1. Make code changes (Go files and/or .c65 files)
2. If .c65 files were modified: `sh build_c65gm.sh`
3. If only Go files were modified: `go build ./...` (for check) or `go build -o c65gm`
4. Run `go test ./...`
5. Test the changes with example .c65 files

#### Compiling .c65 files with the compiled binary:
```bash
C65LIBPATH=/app/lib ./c65gm -in input.c65 -out output.asm
```

## Common Pitfalls

1. **Expression evaluation**: Remember no operator precedence
2. **Zero-page requirements**: Indexed memory operations require zero-page addresses
3. **Include guards**: Essential for library files to prevent multiple inclusion
4. **Program structure**: Always use `GOTO start` to jump over function definitions
5. **String handling**: Strings are passed as pointers to WORD parameters

## Quick Reference

### Compilation
**IMPORTANT**: The agent can compile code. Run `go build ./...` or `sh build_c65gm.sh`.

#### New Self-Contained Method (Recommended)
```bash
./c65gm myprogram.c65                    # Creates myprogram.prg (compile + assemble)
./c65gm build -i myprogram.c65           # Same as above
./c65gm compile -i myprogram.c65         # Creates myprogram.asm only
```

#### Legacy Method (Still Supported)
```bash
./c65gm -in myprogram.c65 -out output.asm
acme -f cbm -o output.prg output.asm
```

### Environment Variables
- `C65LIBPATH`: Library search path for `#INCLUDE <file>`

### Editor Support
- Kate syntax: `editor_syntaxes/kate/`
- Sublime syntax: `editor_syntaxes/sublime/`

## Where to Look for Specifics

### Language Syntax
- `language.md`: Sections 1-10 cover all language features
- `syntax.md`: Detailed syntax rules and preprocessor directives
- `commands.md`: Complete command reference with examples

### Implementation Details
- `internal/compiler/compiler.go`: Main compiler logic
- `internal/commands/*.go`: Individual command implementations
- `internal/preproc/preproc.go`: Preprocessor implementation

### Examples
- `examples/`: Working example programs
- `lib/`: Standard library usage examples

### Testing
- `*_test.go` files throughout the codebase
- `examples/`: Functional test programs

## Tool Notes

### Shell Environment
- **Shell**: Only `/bin/sh` (BusyBox) is available, not bash
- **The `bash` tool** in the interface runs commands through `/bin/sh` (BusyBox)
- **BusyBox limitations**: Many GNU extensions are not available

### grep Limitations
The environment uses BusyBox grep which doesn't support GNU grep extensions:
- **NOT supported**: `--include="*.go"`, `--exclude="*.md"`, etc.
- **Use instead**: `find /app -name "*.go" -type f -exec grep -l "pattern" {} \;`
- **Example**: Instead of `grep -r "CheckUnusedFunctions" /app --include="*.go"`, use:
  ```bash
  find /app -name "*.go" -type f -exec grep -l "CheckUnusedFunctions" {} \;
  ```

### File Operations
- Use `find` with `-exec` for pattern-based file searches
- Use `grep` without GNU extensions for simple pattern matching
- Prefer the `bash` tool with proper BusyBox-compatible commands