# Agent Guidance for Craft++ Repository

## Commands

Run from repository root unless noted.

```bash
dotnet build codelanguage/codelanguage.csproj -c Release -f net8.0
dotnet build codelanguage/codelanguage.csproj -c Release -f net8.0-windows -p:EnableWindowsTargeting=true
dotnet test codelanguage/CraftPlusPlus.Tests/CraftPlusPlus.Tests.csproj -c Release
dotnet test codelanguage/CraftPlusPlus.Tests/CompilerValidation/CompilerValidation.csproj -c Release
dotnet test codelanguage/CraftPlusPlus.Tests/RuntimeValidation/RuntimeValidation.csproj -c Release
```

- `net8.0` is the portable headless build; `net8.0-windows` is the WPF IDE and fails on non-Windows builders without `EnableWindowsTargeting=true`.
- CI (`validate` job) runs the same test commands from `codelanguage/` with `--no-restore`, `ContinuousIntegrationBuild=true`, and per-project `.trx` outputs.
- Filter examples: `dotnet test codelanguage/CraftPlusPlus.Tests/CraftPlusPlus.Tests.csproj --filter "FullyQualifiedName~DocumentWorkflowTests"`.
- If VSTest cannot use its local socket, run the compiler assertions in-process: `dotnet run --project codelanguage/CraftPlusPlus.Tests/CompilerValidation/CompilerValidation.csproj`.
- Release: `./build-release.sh` (delegates to `./build_and_upload.sh`); on Windows use `.\installer\build-release.ps1 -SkipTests`.
- Release requires `.NET 8 SDK`, `zip`, `sha256sum`, `python3`, and `curl`; optional remote deployment uses `UPDATE_SERVER_SSH`/`UPDATE_SERVER_DIR`.

## Architecture

- Core compiler/runtime is flat under `codelanguage/`: `Lexer.cs`, `Tokens.cs`, `Keywords.cs`, `Parser.cs`, `AST.cs`, `Stmt.cs`, `SemanticAnalyzer.cs`, `Interpreter*.cs`, builtins, runtime services.
- `codelanguage/README.md` documents language features and known project notes; `codelanguage/DEVELOPMENT.md` documents focused test commands and manual IDE checks.
- WPF-only files are removed by csproj for `net8.0`; test files that create WPF controls are removed from `CraftPlusPlus.Tests.csproj` when targeting `net8.0`.
- `CompilerValidation` is an xUnit executable that explicitly compiles a subset of front-end sources; edit its `<Compile Include=...>` list when adding compiler test dependencies.
- Recursive `CraftPlusPlus.Tests/**` files are excluded from the parent test project to avoid duplicate compilation.
- Release artifacts are written under `codelanguage/artifacts/` (`publish/`, `updateddata/`, `installer/`), not `bin/` or `obj/`.

## Conventions and Gotchas

- `CS4014` (unawaited async) is configured as an error; common nullability warnings are suppressed in `codelanguage.csproj`.
- Language blocks are indentation-only; literal `{ }` blocks and inline bodies are rejected. Update `CompilerSyntaxTests` and legacy brace-based fixtures accordingly.
- `CraftPlusPlusVersion` defaults in `codelanguage/Directory.Build.props` (`1.0.68`). Builds and release scripts override it via `-p:CraftPlusPlusVersion=...`; release resolves the next patch without editing the props file.
- The update script validates BASE_URL, feed/archive hashes, and refuses to publish unless the candidate version is newer than the live feed.
- Document workflow tests are Windows-only and create WPF controls on an STA thread; cross-compilation does not validate them.
- On Linux, use `EnableWindowsTargeting=true` only for target validation or release builds; runtime WPF behavior still requires Windows.

## When Unsure

1. Check `codelanguage/DEVELOPMENT.md` for focused commands and manual checks.
2. Check `codelanguage/README.md` for language behavior and IDE limitations.
3. Inspect `codelanguage/codelanguage.csproj` and `codelanguage/Directory.Build.props` for target-specific includes and versioning.