Tests and documentation update

README.md

@@ -32,9 +32,9 @@ validates the setup, and how QNX-specific authentication and licensing fit in.
 - [Repository layout](docs/repository_layout.md)
 - [Extension API](docs/extension_api.md)
 - [Generation flow](docs/generation_flow.md)
-- [Examples and validation](docs/examples_and_validation.md)
+- [Tests and validation](docs/tests_and_validation.md)
 - [QNX integration](docs/qnx_integration.md)
-- [Test Suite](docs/test_suite.md) - Comprehensive test documentation
+- [Test Suite](docs/test_suite.md)
 - [Maintenance](docs/maintenance.md)
 
 ## Quick Summary

docs/extension_api.md

@@ -104,7 +104,7 @@ configuration such as:
 --extra_toolchains=@score_gcc_toolchain//:x86_64-linux-gcc_12.2.0
 ```
 
-The example workspace under `examples/` provides complete `.bazelrc`
+The test workspace under `tests/` provides complete `.bazelrc`
 configurations for this activation step.
 
 ## Behavior Notes

docs/maintenance.md

@@ -23,8 +23,9 @@ Adding support for a new toolchain variant usually touches several layers:
 2. add a package BUILD descriptor under `packages/linux/` or `packages/qnx/`,
 3. ensure the required template placeholders already exist, or extend the
    platform template files,
-4. update the example workspace if the new variant should be validated by the
-   smoke-test matrix,
+4. update the test workspace under `tests/` if the new variant should be
+   validated by the test matrix (add a matching `--config` entry in
+   `tests/.bazelrc`),
 5. add or update documentation in this Markdown source and the repository README.
 
 ## When To Use The Version Matrix
@@ -43,20 +44,25 @@ experimental, or intentionally not part of the default support matrix.
 - QNX `aarch64` naming differs from some underlying SDK paths,
 - QNX licensing and authentication requirements live outside Bazel target
   analysis and must be configured in the execution environment,
-- documentation examples must stay aligned with actual `examples/.bazelrc`
+- documentation examples must stay aligned with actual `tests/.bazelrc`
   configuration names.
 
 ## Recommended Validation After Changes
 
 For repository changes that affect toolchain resolution, package metadata, or
-template generation, validate with the example workspace:
+template generation, validate with the test workspace (a separate Bazel
+workspace, so run the commands from `tests/`):
 
 ```bash
-cd examples
-./test.sh --list
-./test.sh host_config_1
-./test.sh --keep-going
+cd tests
+bazel test --config x86_64-linux //...
+bazel test --config x86_64-linux //:feature_verification_tests
+bazel test --config x86_64-linux //:language_and_standards_tests
 ```
 
+The available `--config` values (for example `x86_64-linux`, `aarch64-linux`,
+`x86_64-qnx`, `aarch64-qnx`, `x86_64-linux-autosd10`, `aarch64-linux-ebclfsa`)
+are defined in `tests/.bazelrc`.
+
 For documentation-only changes, build or preview the Markdown site to catch
 markup and table-of-contents/navigation issues before publishing.

docs/overview.md

@@ -24,8 +24,8 @@ It exists to answer three practical needs:
 
 - provide a single Bazel-native way to declare Linux and QNX C/C++ toolchains,
 - keep package provenance, compiler flags, and platform constraints consistent,
-- validate those toolchains through an example workspace instead of relying on
-  ad hoc local setup.
+- validate those toolchains through a dedicated test workspace instead of
+  relying on ad hoc local setup.
 
 ## What The Repository Contains
 
@@ -38,7 +38,7 @@ them as `cc_toolchain` targets:
 - package metadata in `packages/`
 - generated-file templates in `templates/`
 - authentication helpers in `tools/`
-- an example validation workspace in `examples/`
+- a dedicated test workspace in `tests/`
 
 ## Supported Platform Families
 

docs/repository_layout.md

@@ -22,7 +22,7 @@ The repository is organized by subsystem rather than by platform product:
 ```text
 .
 |- docs/        Markdown documentation sources
-|- examples/    Example workspace and smoke tests
+|- tests/       Test workspace and validation suites
 |- extensions/  Bzlmod extension entry points
 |- packages/    Toolchain package descriptors and version matrix
 |- rules/       Repository rules and shared helpers
@@ -58,13 +58,13 @@ QNX because the execution environment, sysroot layout, and licensing model are
 different.
 > NOTE: Future plan is to have a single template for toolchain configuration.
 
-`examples/`
+`tests/`
 
-A standalone Bazel workspace used as an integration surface. It declares
-representative toolchain configurations and validates them with a smoke-test
-runner.
-> NOTE: These tests are just a sanity check. They should not be used as reference
-> points for platform development.
+A standalone Bazel workspace used as the integration and validation surface. It
+declares representative toolchain configurations and validates them with
+feature-verification and language-standard test suites.
+> NOTE: These tests validate toolchain generation. They should not be used as
+> reference points for platform development.
 
 `tools/`