feat: add released versions section to index.md with per-version guide and API links

Agent-Logs-Url: https://github.com/petesramek/polyline-algorithm-csharp/sessions/b02a112c-f47f-48ac-ac0e-6da6ec9b5c69

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>

Author: Copilot

.github/workflows/publish-documentation.yml

@@ -91,6 +91,11 @@ jobs:
           docfx metadata assembly-metadata.json
           mv temp ${{ env.friendly-version }}
 
+      - name: 'Snapshot guide for v${{ env.friendly-version }}'
+        shell: bash
+        run: |
+          cp -r api-reference/guide api-reference/${{ env.friendly-version }}/guide
+
       - name: 'Discover all versions'
         id: discover-versions
         shell: bash
@@ -116,7 +121,10 @@ jobs:
           cp api-reference/api-reference.json /tmp/api-reference.json
           for ver in $(echo "${{ steps.discover-versions.outputs.versions }}" | tr ',' ' '); do
             jq --arg ver "$ver" --arg group "v${ver}" \
-               '.build.content += [{"dest": "", "files": ["*.yml"], "group": $group, "src": $ver, "rootTocPath": "~/toc.html"}] |
+               '.build.content += [
+                  {"dest": "",      "files": ["*.yml"],          "group": $group, "src": $ver,               "rootTocPath": "~/toc.html"},
+                  {"dest": "guide", "files": ["*.{md,yml}"], "group": $group, "src": ($ver + "/guide"), "rootTocPath": "~/toc.html"}
+               ] |
                 .build.groups = (.build.groups // {}) |
                 .build.groups[$group] = {"dest": $ver}' \
                /tmp/api-reference.json > /tmp/api-reference-new.json
@@ -131,7 +139,7 @@ jobs:
           {
             echo "### YamlMime:TableOfContent"
             echo "- name: Guide"
-            echo "  href: guide/"
+            echo "  href: ${latest}/guide/introduction.html"
             echo "- name: Reference"
             echo "  dropdown: true"
             echo "  items:"
@@ -145,6 +153,11 @@ jobs:
             done
           } > api-reference/toc.yml
 
+      - name: 'Inject latest version into index.md'
+        shell: bash
+        run: |
+          sed -i "s|{version}|${{ steps.discover-versions.outputs.latest }}|g" api-reference/index.md
+
       - name: 'Build documentation'
         shell: bash
         run: docfx build api-reference/api-reference.json

api-reference/1.0/guide/advanced-scenarios.md

@@ -0,0 +1,168 @@
+# Advanced Usage
+
+PolylineAlgorithm is designed for extensibility and integration with advanced .NET scenarios.  
+This guide covers custom types, integrations, and best practices for power users.
+
+---
+
+## Custom Coordinate and Polyline Types
+
+You can encode and decode custom coordinate or polyline representations by extending the abstract base classes:
+
+- `AbstractPolylineEncoder<TCoordinate, TPolyline>`
+- `AbstractPolylineDecoder<TPolyline, TCoordinate>`
+
+### Example: Custom Encoder
+
+```csharp
+public sealed class MyPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string>
+{
+    public MyPolylineEncoder() : base() { }
+
+    public MyPolylineEncoder(PolylineEncodingOptions options)
+        : base(options) { }
+
+    protected override double GetLatitude((double Latitude, double Longitude) coordinate)
+        => coordinate.Latitude;
+
+    protected override double GetLongitude((double Latitude, double Longitude) coordinate)
+        => coordinate.Longitude;
+
+    protected override string CreatePolyline(ReadOnlyMemory<char> polyline)
+        => polyline.ToString();
+}
+```
+
+---
+
+## Example: Custom Decoder
+
+```csharp
+public sealed class MyPolylineDecoder : AbstractPolylineDecoder<string, (double Latitude, double Longitude)>
+{
+    public MyPolylineDecoder() : base() { }
+
+    public MyPolylineDecoder(PolylineEncodingOptions options)
+        : base(options) { }
+
+    protected override (double Latitude, double Longitude) CreateCoordinate(double latitude, double longitude)
+        => (latitude, longitude);
+
+    protected override ReadOnlyMemory<char> GetReadOnlyMemory(ref string polyline)
+        => polyline.AsMemory();
+}
+```
+
+---
+
+# Registering Custom Encoder and Decoder with `IServiceCollection`
+
+For ASP.NET Core or DI-enabled .NET applications, you can easily register your custom polyline encoder and decoder as services with `IServiceCollection` by defining an extension method. This enables constructor injection and central DI management.
+
+---
+
+## Example: Register Custom Polyline Encoder/Decoder
+
+Suppose you have the following custom encoder and decoder (see [Advanced Usage](./advanced.md)):
+
+```csharp
+public sealed class MyPolylineEncoder : AbstractPolylineEncoder<(double Latitude, double Longitude), string>
+{
+    public MyPolylineEncoder(PolylineEncodingOptions options = null)
+        : base(options) { }
+
+    // ... override required members ...
+}
+
+public sealed class MyPolylineDecoder : AbstractPolylineDecoder<string, (double Latitude, double Longitude)>
+{
+    public MyPolylineDecoder(PolylineEncodingOptions options = null)
+        : base(options) { }
+
+    // ... override required members ...
+}
+```
+
+---
+
+## IServiceCollection Extension Method
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using PolylineAlgorithm;
+
+public static class PolylineServiceCollectionExtensions
+{
+    public static IServiceCollection AddMyPolylineEncoderDecoder(
+        this IServiceCollection services,
+        PolylineEncodingOptions options = null)
+    {
+        // Register encoder and decoder as singletons (adjust lifetime as needed)
+        services.AddSingleton<IPolylineEncoder<(double Latitude, double Longitude), string>>(
+            _ => new MyPolylineEncoder(options));
+        services.AddSingleton<IPolylineDecoder<string, (double Latitude, double Longitude)>>(
+            _ => new MyPolylineDecoder(options));
+        return services;
+    }
+}
+```
+
+---
+
+## Usage
+
+In your application startup (e.g., `Program.cs` or `Startup.cs`):
+
+```csharp
+using PolylineAlgorithm;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddMyPolylineEncoderDecoder(
+    PolylineEncodingOptionsBuilder.Create()
+        .WithStackAllocLimit(1024)
+        .Build()
+);
+
+// Now you can inject IPolylineEncoder<(double, double), string> and IPolylineDecoder<string, (double, double)>
+```
+
+---
+
+## Benefits
+
+- **Central DI management** for polyline components
+- Plug-and-play integration with ASP.NET Core and modern .NET project styles
+- Easily swap out or configure encoders/decoders for different environments
+
+---
+
+> **Tip:**  
+> You can generalize the extension method for different encoder/decoder types or include multiple algorithms by adding extra parameters.
+
+---
+
+## Integration Guidance
+
+- **Batch or incremental processing:**  
+  For large datasets, control the stack allocation limit via `PolylineEncodingOptions.StackAllocLimit`.
+- **Thread safety:**  
+  Default encoders/decoders are stateless and thread-safe. If extending for mutable types, ensure synchronization.
+- **Logging:**  
+  Integrate with .NET's `ILoggerFactory` when diagnostics or audit trails are needed.
+
+---
+
+## Best Practices
+
+- Always validate input data—leverage built-in validation or extend for custom rules.
+- Document all public APIs using XML comments for seamless integration with the auto-generated docs.
+- For non-standard coordinate systems or precision, clearly specify semantics in your custom encoder/decoder.
+
+---
+
+## More Resources
+
+- [Configuration](./configuration.md)
+- [FAQ](./faq.md)
+- [API Reference](https://petesramek.github.io/polyline-algorithm-csharp/)

api-reference/1.0/guide/configuration.md

@@ -0,0 +1,75 @@
+# Configuration
+
+PolylineAlgorithm offers flexible configuration for encoding and decoding polylines, allowing you to fine-tune performance, control validation, and integrate diagnostics and logging.
+
+---
+
+## PolylineEncodingOptions
+
+Most configuration is handled via the `PolylineEncodingOptions` object, which you can build using the fluent `PolylineEncodingOptionsBuilder`.
+
+### Example: Customizing Stack Alloc Limit
+
+```csharp
+using PolylineAlgorithm;
+
+var options = PolylineEncodingOptionsBuilder.Create()
+    .WithStackAllocLimit(1024) // Set stack allocation threshold (bytes)
+    .Build();
+
+var encoder = new PolylineEncoder(options);
+```
+
+---
+
+## Logging and Diagnostics
+
+PolylineAlgorithm supports internal logging for advanced scenarios and diagnostic purposes.
+
+- Use your preferred .NET logging framework (`ILoggerFactory`)
+- Attach loggers for encoding/decoding diagnostics, especially in automated or agent-based environments
+
+---
+
+## Validation
+
+Input validation is always enabled by default:
+
+- Latitude: must be between -90 and 90
+- Longitude: must be between -180 and 180
+- Invalid or malformed coordinates throw descriptive exceptions
+
+For custom validation (e.g., for custom coordinate types), extend the provided interfaces or abstract base classes.
+
+---
+
+## Advanced Configuration Options
+
+When using `PolylineEncodingOptionsBuilder`, you may set:
+
+- **Stack alloc limit:** Configure the threshold below which buffers are stack-allocated vs. rented from `ArrayPool<char>`
+- **Logging hooks:** Integrate your logger for troubleshooting/instrumentation
+- **(Future)** Custom precision, additional metadata (as needed)
+
+See the XML API documentation for all available builder methods.
+
+---
+
+## Example: Full Custom Encoder with Options
+
+```csharp
+var options = PolylineEncodingOptionsBuilder.Create()
+    .WithStackAllocLimit(512)
+    .WithLoggerFactory(myLoggerFactory)
+    .Build();
+
+var encoder = new PolylineEncoder(options);
+```
+
+---
+
+## Further Reading
+
+- [Getting Started Guide](./guide.md)
+- [Advanced Usage](./advanced.md)
+- [API Reference](https://petesramek.github.io/polyline-algorithm-csharp/)

api-reference/1.0/guide/faq.md

@@ -0,0 +1,63 @@
+# FAQ
+
+Frequently Asked Questions for PolylineAlgorithm
+
+---
+
+## General
+
+**Q: What coordinate ranges are valid?**  
+A: Latitude must be between -90 and 90; longitude must be between -180 and 180. Passing out-of-range values throws `ArgumentOutOfRangeException`.
+
+**Q: Which .NET versions are supported?**  
+A: Any platform supporting `netstandard2.1`, including .NET Core, .NET 5+, Xamarin, Unity, and Blazor.
+
+**Q: Can the library be used in Unity, Xamarin, Blazor, or other .NET-compatible platforms?**  
+A: Yes! Any environment that supports `netstandard2.1` can use this library.
+
+---
+
+## Usage & Extensibility
+
+**Q: How do I add a new polyline algorithm or coordinate type?**  
+A: Implement your own encoder/decoder using `AbstractPolylineEncoder<TCoordinate, TPolyline>` and `AbstractPolylineDecoder<TPolyline, TCoordinate>`. Add unit tests and XML doc comments, then submit a PR.
+
+**Q: How do I customize encoding options (e.g., buffer size, logging)?**  
+A: Use `PolylineEncodingOptionsBuilder` to set options, and pass the result to the encoder or decoder constructor.
+
+**Q: Is the library thread-safe?**  
+A: Yes, main encoding/decoding APIs are stateless and thread-safe. If you extend using shared mutable resources, ensure proper synchronization.
+
+**Q: What happens if I pass invalid or malformed input to the decoder?**  
+A: The decoder throws descriptive exceptions for malformed polyline strings. Ensure proper exception handling in your application.
+
+**Q: Does the library support streaming or incremental decoding of polylines?**  
+A: Currently, only batch encode/decode is supported. For streaming scenarios, implement your own logic using `PolylineEncoding` utilities.
+
+---
+
+## Features & Support
+
+**Q: Is there support for elevation, timestamps, or third coordinate values?**  
+A: Not currently, and not planned for the core library. You may implement your own encoder/decoder using `PolylineEncoding` methods for extended coordinate data.
+
+**Q: How do I contribute documentation improvements?**  
+A: Update XML doc comments in the codebase and submit a pull request. To improve guides, update relevant markdown files in `/api-reference/guide`.
+
+**Q: Where can I report bugs or request features?**  
+A: Open a GitHub issue using the provided templates and tag `@petesramek`.
+
+---
+
+## Documentation & Community
+
+**Q: Where can I find detailed API documentation?**  
+A: [API Reference](https://petesramek.github.io/polyline-algorithm-csharp/)
+
+**Q: How do I contribute?**  
+A: Read [CONTRIBUTING.md](../CONTRIBUTING.md), follow coding style and testing guidelines, and use issue/PR templates.
+
+**Q: Need more help?**  
+A: Open an issue in the [GitHub repository](https://github.com/petesramek/polyline-algorithm-csharp/issues).
+
+---