bench: add performance samples and report

- Add minimal samples for no includes, #include, #ref, #include+#ref cases
- Add samples/perf.md with detailed performance analysis
- Simplify root readme.md to focus on value prop, dnx go usage examples, and unchanged re-run numbers only
- Include the go.targets cache fix needed to demonstrate short-circuiting re-runs

Author: kzu

readme.md

@@ -1,4 +1,4 @@
-# go
+# go#
 
 [![Version](https://img.shields.io/nuget/vpre/go.svg?color=royalblue)](https://www.nuget.org/packages/go)
 [![Downloads](https://img.shields.io/nuget/dt/go.svg?color=darkmagenta)](https://www.nuget.org/packages/go)
@@ -18,8 +18,54 @@ OSMF tier. A single fee covers all of [Devlooped packages](https://www.nuget.org
 
 <!-- https://github.com/devlooped/.github/raw/main/osmf.md -->
 <!-- #content -->
+
+## What is `go#`?
+
+`go#` (go sharp) lets you run `.cs` files directly, like scripts, while still getting the full power of the .NET SDK (dependencies, compilation, AOT, etc.).
+
+It shines for:
+- Quick one-off tools and prototypes
+- File-based apps without a `.csproj`
+- Fast iteration with smart caching (subsequent runs are near-instant when nothing changed)
+- Easy sharing of small utilities (just the `.cs` file)
+
 ## Usage
-*go*
+
+```console
+# Run a file
+dnx go app.cs
+
+# Pass arguments to your app
+dnx go app.cs -- arg1 arg2
+
+# Pass arguments to the underlying `dotnet publish`
+dnx go app.cs /p:PublishAot=true -- arg1 arg2
+```
+
+## Performance
+
+The main advantage of `go#` is **fast unchanged re-runs**. The numbers below compare the three common approaches on pristine sources.
+
+**PublishAot=false**
+
+| Example            | `dotnet run app.cs` | `go app.cs`  | `dotnet publish ...; app.exe` |
+|--------------------|---------------------|--------------|-------------------------------|
+| a) no includes     | 1.306s              | 0.264s       | 5.044s                        |
+| b) #include        | 1.169s              | 0.198s       | 4.857s                        |
+| c) #ref            | 4.605s              | 0.191s       | 6.243s                        |
+| d) #include + #ref | 13.079s             | 0.227s       | 7.320s                        |
+
+**PublishAot=true** (NativeAOT)
+
+| Example            | `dotnet run app.cs` | `go app.cs`  | `dotnet publish ...; app.exe` |
+|--------------------|---------------------|--------------|-------------------------------|
+| a) no includes     | —                   | 0.227s       | 12.436s                       |
+| b) #include        | —                   | 0.164s       | 11.145s                       |
+| c) #ref            | —                   | 0.183s       | 32.874s                       |
+| d) #include + #ref | —                   | 0.269s       | 21.888s                       |
+
+**Observation**: `go#` re-runs are fast (~0.16–0.27s) — just launching the cached executable when no changes are detected in any of the input files (including the `#include` and `#ref` dependencies).
+
 <!-- #content -->
 ---
 <!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->

samples/include/app.cs

@@ -0,0 +1,8 @@
+#!/usr/bin/env dotnet
+#:property TargetFramework=net10.0
+
+#:include lib.cs
+
+using PerfInclude;
+
+Console.WriteLine("include: " + Helper.Message() + " (via #:include)");

samples/include/lib.cs

@@ -0,0 +1,6 @@
+namespace PerfInclude;
+
+public static class Helper
+{
+    public static string Message() => "included source merged";
+}

samples/incref/app.cs

@@ -0,0 +1,11 @@
+#!/usr/bin/env dotnet
+#:property TargetFramework=net10.0
+#:property ExperimentalFileBasedProgramEnableRefDirective=true
+
+#:include inclib.cs
+#:ref reflib.cs
+
+using PerfInc;
+using PerfRef;
+
+Console.WriteLine("incref: " + Helper.Message() + " | " + Greeter.Greet("both") + " (via #:include + #:ref)");

samples/incref/inclib.cs

@@ -0,0 +1,6 @@
+namespace PerfInc;
+
+public static class Helper
+{
+    public static string Message() => "included+ref source";
+}

samples/incref/reflib.cs

@@ -0,0 +1,10 @@
+#:property TargetFramework=net10.0
+#:property OutputType=Library
+#:property ExperimentalFileBasedProgramEnableRefDirective=true
+
+namespace PerfRef;
+
+public static class Greeter
+{
+    public static string Greet(string name) => $"hello from #:ref in combined, {name}";
+}

samples/noinc/app.cs

@@ -0,0 +1,6 @@
+#!/usr/bin/env dotnet
+#:property TargetFramework=net10.0
+
+// a) no includes, no refs
+
+Console.WriteLine("noinc: OK from file-based app (no directives beyond TF)");

samples/perf.md

@@ -0,0 +1,88 @@
+# Performance Analysis (detailed)
+
+This document contains the full performance measurements for reference. The main `readme.md` only highlights the key "unchanged re-run" numbers.
+
+## Approaches
+
+- `go app.cs` — invoked via the RID-specific published binary (never `dotnet run` on the tool project)
+- `dotnet run app.cs` — built-in file-based run (no AOT)
+- `dotnet publish app.cs /p:PublishAot=... ; artifacts/app/app.exe`
+
+## Examples
+
+Four minimal, package-free examples live under `samples/`:
+
+- **a) no includes** — `samples/noinc/app.cs`
+- **b) #include** — `samples/include/{app.cs, lib.cs}`
+- **c) #ref** — `samples/ref/{app.cs, lib.cs}`
+- **d) #include + #ref** — `samples/incref/{app.cs, inclib.cs, reflib.cs}`
+
+All declare `TargetFramework=net10.0` (plus the Experimental flag for #ref cases).
+
+## Methodology
+
+- Environment: Windows + .NET 11.0.100-preview.5 SDK.
+- All timings via `pwsh` `Measure-Command`.
+- `go` binary: always the RID-specific published exe (win-x64, --no-self-contained).
+- AOT control via `/p:PublishAot=false|true`.
+- Scenarios captured:
+  - first-run (clean state)
+  - unchanged re-runs (pristine sources)
+  - run/edit/run
+- Raw data is in the goal scratch directory (`perf-logs/`).
+
+The tool provides fast re-runs for unchanged sources through its build caching.
+
+## Unchanged re-runs (pristine sources – last observed)
+
+**PublishAot=false**
+
+| Example            | `dotnet run app.cs` | `go app.cs` (RID exe) | `dotnet publish ... ; app.exe` |
+|--------------------|---------------------|-----------------------|--------------------------------|
+| a) no includes     | 1.306s              | 0.264s                | 5.044s                         |
+| b) #include        | 1.169s              | 0.198s                | 4.857s                         |
+| c) #ref            | 4.605s              | 0.191s                | 6.243s                         |
+| d) #include + #ref | 13.079s             | 0.227s                | 7.320s                         |
+
+**PublishAot=true** (NativeAOT)
+
+| Example            | `dotnet run app.cs` | `go app.cs` (RID exe) | `dotnet publish ... ; app.exe` |
+|--------------------|---------------------|-----------------------|--------------------------------|
+| a) no includes     | —                   | 0.227s                | 12.436s                        |
+| b) #include        | —                   | 0.164s                | 11.145s                        |
+| c) #ref            | —                   | 0.183s                | 32.874s                        |
+| d) #include + #ref | —                   | 0.269s                | 21.888s                        |
+
+**Observation**: `go` re-runs (both AOT modes) are now ~0.16–0.27s — just launching the already-published executable.
+
+## First-run (clean state)
+
+AOT=true first runs are significantly slower due to NativeAOT compilation.
+
+| Example | `dotnet run` | `go` (AOT=false) | `publish` (AOT=false) | `go` (AOT=true) | `publish` (AOT=true) |
+|---------|--------------|------------------|-----------------------|-----------------|----------------------|
+| a) noinc | 6–12s       | ~20s            | ~8–13s               | ~20s           | ~17–23s             |
+| b) include | ~5–11s    | ~20s            | ~7s                  | ~18s           | ~20s                |
+| c) ref  | ~6–7s       | ~19s            | ~8s                  | ~20s           | ~18s                |
+| d) incref | ~11s      | ~38s            | ~7.5s                | ~32s           | ~27s                |
+
+## run / edit / run
+
+After editing the source, the next invocation was measured (with prior artifacts left in place).
+
+See the raw logs for exact per-cell values. The important takeaway is that once a native AOT executable has been produced by `go`, launching it remains extremely fast even after source changes (until a rebuild is triggered).
+
+## Full raw data
+
+All `Measure-Command` output and per-run summaries live in the private scratch directory used during measurement (typically under the goal session temp folder).
+
+Example commands used:
+
+```pwsh
+& '...\go-tool-rid\go.exe' app.cs -- /p:PublishAot=false
+& '...\go-tool-rid\go.exe' app.cs -- /p:PublishAot=true
+```
+
+---
+
+*This file is for future reference. The primary user-facing numbers are in the root `readme.md`.*

samples/ref/app.cs

@@ -0,0 +1,9 @@
+#!/usr/bin/env dotnet
+#:property TargetFramework=net10.0
+#:property ExperimentalFileBasedProgramEnableRefDirective=true
+
+#:ref lib.cs
+
+using PerfRef;
+
+Console.WriteLine("ref: " + Greeter.Greet("perf") + " (via #:ref)");

samples/ref/lib.cs

@@ -0,0 +1,10 @@
+#:property TargetFramework=net10.0
+#:property OutputType=Library
+#:property ExperimentalFileBasedProgramEnableRefDirective=true
+
+namespace PerfRef;
+
+public static class Greeter
+{
+    public static string Greet(string name) => $"hello from separate #:ref assembly, {name}";
+}