Add Apache 2.0 headers to every .cs file; refresh README index (#20)

A repo-wide cleanup pass for professionalism / licensing hygiene:

## Apache 2.0 license header

Prepended the standard Firefly Software Foundation Apache 2.0 header
to every C# source file in src/, samples/, and tests/ — 344 files in
total, all of which previously lacked a header. The text is the same
notice used in the Java sources, normalised to C# `//` line comments:

    // Copyright 2024-2026 Firefly Software Foundation
    //
    // Licensed under the Apache License, Version 2.0 (the "License");
    // you may not use this file except in compliance with the License.
    // You may obtain a copy of the License at
    //
    //     http://www.apache.org/licenses/LICENSE-2.0
    //
    // Unless required by applicable law or agreed to in writing, software
    // distributed under the License is distributed on an "AS IS" BASIS,
    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    // implied. See the License for the specific language governing
    // permissions and limitations under the License.

The header sits above the first using directive, separated by a blank
line. Insertion was idempotent (skipped any file already containing
"Firefly Software Foundation"); re-running on top is a no-op. Build:
0 errors / 0 warnings; 346/346 tests still pass.

## Documentation index

Removed `docs/AUDIT.md` (Java↔.NET parity audit) per the user's
direction — the same information now lives implicitly in the README
quickstarts, the per-project READMEs, and the new index pages added
in this PR. All references to AUDIT.md are stripped from README.md.

Added three new top-level README index pages:

* `docs/README.md` — indexes ARCHITECTURE / MODULES / SERVICE-SCAFFOLDING
  / CONFIGURATION / MIGRATION-GUIDE with audience tags and a recommended
  reading order. Replaces the navigation role AUDIT.md served.

* `src/README.md` — lists every src/* project organised by tier
  (Foundational / Platform / Adapters / Starters), with a one-line
  description of each and a link to its own README. Calls out the
  conventions every project follows: Apache header, file-scoped
  namespaces, `<IsPackable>true</IsPackable>` default, options + DI
  extension naming, and the no-silent-stubs rule.

* `tests/README.md` — describes the single-test-project layout, how
  to run filtered subsets, the three test categories (framework
  internals / adapter shape / extras), and the conventions for new
  tests (WireMock for HTTP adapters, NSubstitute for SDK-fronted
  ones, xUnit-native asserts).

## README touch-up

Updated the top-level `README.md` to reflect the new structure:

* "Repository layout" tree shows the three new index READMEs and
  drops the AUDIT.md line.
* "Documentation" section points at `docs/README.md` as the
  recommended starting point and removes the AUDIT.md row.
* Per-project + index READMEs are explicitly cross-linked so a
  reader landing in any of `src/`, `samples/`, `tests/`, or `docs/`
  finds the right next page within one click.

## Verification

* `dotnet build FireflyFramework.sln` — 0 errors / 0 warnings.
* `dotnet test FireflyFramework.sln --no-build` — 346 / 346 passing.
* `find src tests samples -name '*.cs' -exec grep -L 'Firefly Software Foundation' {} \;` — empty (every file has the header).
* `head -2 src/FireflyFramework.Cqrs/Commands/ICommand.cs` shows the
  header sits above the first `using` directive, not inside it.

Co-authored-by: Andres Contreras <andres.contreras@soon.es>

Author: ancongui

README.md

@@ -389,21 +389,23 @@ The full schema — verified against the actual `*Options` classes — is in
 
 ```
 fireflyframework-dotnet/
-├── docs/                              Long-form documentation
+├── docs/                              Long-form documentation (start with docs/README.md)
+│   ├── README.md                      Index — recommended reading order
 │   ├── ARCHITECTURE.md                Tier diagram, dependency graph, process model
 │   ├── SERVICE-SCAFFOLDING.md         Canonical 5-project service layout
 │   ├── MIGRATION-GUIDE.md             Java to .NET cookbook
 │   ├── CONFIGURATION.md               Every Firefly:* options section
-│   ├── MODULES.md                     Per-project description with Java mapping
-│   └── AUDIT.md                       Java vs .NET feature parity audit
-├── src/                               Framework projects (foundational → starters)
+│   └── MODULES.md                     Per-project description with Java mapping
+├── src/                               Framework projects, indexed by tier in src/README.md
 ├── samples/                           Reference services in canonical 5-project layout
+│   ├── README.md
 │   ├── FireflyFramework.Samples.OrdersService.Interfaces/
 │   ├── FireflyFramework.Samples.OrdersService.Models/
 │   ├── FireflyFramework.Samples.OrdersService.Core/
 │   ├── FireflyFramework.Samples.OrdersService.Web/
 │   └── FireflyFramework.Samples.OrdersService.Sdk/
-├── tests/FireflyFramework.Tests/      Cross-tier test suite
+├── tests/                             Cross-tier test suite (see tests/README.md)
+│   └── FireflyFramework.Tests/
 ├── Directory.Build.props              Parent build properties (net10.0, version, metadata)
 ├── Directory.Build.targets            Cross-project test wiring
 ├── Directory.Packages.props           Central Package Management — every NuGet pinned
@@ -421,14 +423,17 @@ public surface, options class, and usage examples.
 
 ## Documentation
 
+[`docs/README.md`](docs/README.md) is the recommended starting point — it indexes the doc set and suggests a reading order.
+
 | Document | Purpose |
 |---|---|
 | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Tier-by-tier reference, dependency-direction graph, process model, versioning policy |
 | [`docs/SERVICE-SCAFFOLDING.md`](docs/SERVICE-SCAFFOLDING.md) | The canonical 5-project layout, naming conventions, dependency graph, bootstrap recipe |
 | [`docs/MIGRATION-GUIDE.md`](docs/MIGRATION-GUIDE.md) | Java → .NET cookbook covering Reactor, Spring DI, web layer, persistence, CQRS, EDA, resilience, observability |
 | [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) | Every `Firefly:*` configuration section with example values |
 | [`docs/MODULES.md`](docs/MODULES.md) | One-line description of every project plus its Java original |
-| [`docs/AUDIT.md`](docs/AUDIT.md) | Java vs .NET feature parity audit |
+
+Per-project READMEs live alongside each project under [`src/`](src) and [`samples/`](samples). [`src/README.md`](src/README.md) indexes them by tier; [`tests/README.md`](tests/README.md) describes the test suite layout.
 
 ---
 

docs/AUDIT.md

@@ -0,0 +1,38 @@
+# Firefly Framework Documentation
+
+Long-form documentation for the .NET port of the Firefly Framework.
+Each file targets a specific audience or task; this index is the
+recommended starting point.
+
+| Document | Audience | What it covers |
+|---|---|---|
+| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Anyone integrating with the framework | The four-tier layering (Foundational → Platform → Adapters → Starters), inter-project dependency direction, the process model the runtime assumes, and the framework's versioning policy. |
+| [`MODULES.md`](MODULES.md) | Anyone picking which package(s) to install | One-line description of every `src/*` project paired with its Java original, organised by tier. The "what's in this package" reference. |
+| [`SERVICE-SCAFFOLDING.md`](SERVICE-SCAFFOLDING.md) | Service authors building on the framework | The canonical five-project layout (`.Interfaces` / `.Models` / `.Core` / `.Web` / `.Sdk`), naming conventions, dependency graph, and a step-by-step bootstrap recipe modelled on the Orders sample. |
+| [`CONFIGURATION.md`](CONFIGURATION.md) | Service authors + operators | Every `Firefly:*` configuration section with the real `*Options` type signatures, default values, and worked examples. |
+| [`MIGRATION-GUIDE.md`](MIGRATION-GUIDE.md) | Teams porting an existing Java service | Mapping table from Reactor / Spring DI / Spring Web / Spring Data R2DBC / Spring Cloud / Resilience4j / Micrometer / Logback to their .NET 10 counterparts, with side-by-side code samples. |
+
+## Reading order
+
+If you're new to the framework, read in this order:
+
+1. **[`ARCHITECTURE.md`](ARCHITECTURE.md)** — orient on the layering model and the dependency direction. Five minutes.
+2. **[`SERVICE-SCAFFOLDING.md`](SERVICE-SCAFFOLDING.md)** — see what a real service looks like end-to-end before reading individual module docs. Ten minutes.
+3. **[`MODULES.md`](MODULES.md)** — skim the catalogue; bookmark the modules you'll use.
+4. **[`CONFIGURATION.md`](CONFIGURATION.md)** — keep open while wiring up your `appsettings.json`.
+
+If you're porting an existing Java service, start with [`MIGRATION-GUIDE.md`](MIGRATION-GUIDE.md) instead.
+
+## Per-project documentation
+
+Each project under [`src/`](../src) ships its own `README.md`
+describing its public surface, options class, and short usage examples.
+The same is true of every project under [`samples/`](../samples).
+[`src/README.md`](../src/README.md) indexes them by tier.
+
+## Top-level project README
+
+The repository root [`README.md`](../README.md) covers the
+five-minute pitch, the architecture diagram, the canonical
+service-shape, two quickstart paths (run the sample / build your
+first service from scratch), and the release-publish workflow.

docs/README.md

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using FireflyFramework.Samples.OrdersService.Interfaces.Dtos.V1;
 using FireflyFramework.Samples.OrdersService.Models.Entities.V1;
 

samples/FireflyFramework.Samples.OrdersService.Core/Mappers/OrderMapper.cs

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using FireflyFramework.Cqrs.Queries;
 using FireflyFramework.Samples.OrdersService.Core.Mappers;
 using FireflyFramework.Samples.OrdersService.Interfaces.Dtos.V1;

samples/FireflyFramework.Samples.OrdersService.Core/Services/Orders/V1/GetOrderHandler.cs

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using FireflyFramework.Cqrs.Queries;
 using FireflyFramework.Samples.OrdersService.Interfaces.Dtos.V1;
 

samples/FireflyFramework.Samples.OrdersService.Core/Services/Orders/V1/GetOrderQuery.cs

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using FireflyFramework.Cqrs.Commands;
 using FireflyFramework.Cqrs.Validation;
 

samples/FireflyFramework.Samples.OrdersService.Core/Services/Orders/V1/PlaceOrderCommand.cs

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using FireflyFramework.Cqrs.Commands;
 using FireflyFramework.Samples.OrdersService.Interfaces.Enums.V1;
 using FireflyFramework.Samples.OrdersService.Models.Entities.V1;

samples/FireflyFramework.Samples.OrdersService.Core/Services/Orders/V1/PlaceOrderHandler.cs

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using FireflyFramework.Samples.OrdersService.Interfaces.Enums.V1;
 
 namespace FireflyFramework.Samples.OrdersService.Interfaces.Dtos.V1;

samples/FireflyFramework.Samples.OrdersService.Interfaces/Dtos/V1/OrderDto.cs

@@ -1,3 +1,17 @@
+// Copyright 2024-2026 Firefly Software Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 namespace FireflyFramework.Samples.OrdersService.Interfaces.Dtos.V1;
 
 public sealed record PlaceOrderRequest(string Sku, int Quantity, decimal UnitPrice);