Normalize doc naming and improve local run instructions

AGENTS.md

@@ -0,0 +1,4 @@
+# AGENTS.md
+
+Follow `CLAUDE.md` for repository-specific agent instructions.
+

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+## Project
+
+Java 21 REST Assured/JUnit 5 API automation framework for Conduit-style API
+coverage, contract checks, reliability evidence, and portfolio reporting.
+
+## Session Start
+
+Refresh the local code graph before structural discovery:
+
+`bash .agent/index-codebase-memory.sh`
+
+Current MCP project name:
+
+`home-vyaspc-Documents-Repo-aria-api-framework`
+
+## Commands
+
+- Install/use wrapper: `./gradlew --version`
+- Main verification: `./gradlew test`
+- Tagged tests: `./gradlew test -DincludeTags=smoke`
+- Format: `./gradlew spotlessApply`
+- Format check: `./gradlew spotlessCheck`
+- Static checks: `./gradlew spotbugsMain spotbugsTest`
+- Dependency/security artifacts: `./gradlew cyclonedxBom`
+
+## Layout
+
+- `src/main/java` - reusable API framework code, clients, config, reporting helpers.
+- `src/test/java` - JUnit 5 API, contract, reliability, and seeded-defect tests.
+- `src/test/resources` - test data, schemas, Allure/JUnit resources.
+- `docs/` - architecture, execution, reliability, writing-tests, and debugging guides.
+- `reliability/quarantine.yml` - quarantine policy and known reliability exceptions.
+- `portfolio/manifest.yml` - portfolio metadata.
+
+## Codebase Memory MCP
+
+Use graph tools before broad file reads:
+
+1. `list_projects`
+2. `get_architecture(project="home-vyaspc-Documents-Repo-aria-api-framework")`
+3. `search_graph`
+4. `trace_path`
+5. `get_code_snippet`
+6. `query_graph`
+
+Fall back to `rg` for literals, configs, docs, generated files, or insufficient graph results.
+
+## Agent Rules
+
+- Cite `file:line` for code claims whenever practical.
+- Keep changes scoped to the framework layer under test; avoid unrelated cleanup.
+- Prefer targeted Gradle tasks and tagged tests over full-suite reruns.
+- Do not commit `.codebase-memory/`, `codebase-memory/`, or `.agent/index-codebase-memory.sh`.
+

README.md

@@ -12,6 +12,11 @@ provider verification, OpenAPI endpoint coverage, security boundaries, redacted
 diagnostics, and CI quality gates. The name refers to REST API assertions and is
 not related to WAI-ARIA accessibility standards.
 
+The core engineering problem this framework answers: how do you get real Pact
+provider verification without depending on someone else's service? See
+[ADR-005](docs/adr/ADR-005-owned-provider-http-server.md) for the owned-provider
+answer, and the tech stack and project structure below for how it fits together.
+
 ## Reviewer Proof
 
 | Evidence | Link |
@@ -67,6 +72,10 @@ evidence. See [CHANGELOG.md](CHANGELOG.md).
 
 ## Run Locally
 
+```bash
+./gradlew clean test -Denv=dev
+```
+
 ```powershell
 .\gradlew.bat clean test -Denv=dev
 ```
@@ -75,9 +84,9 @@ The default `test` task is deterministic. It excludes tests tagged `live` and ru
 
 Run a tag:
 
-```powershell
-.\gradlew.bat test -Denv=dev --tests "*AuthTests"
-.\gradlew.bat smokeTest -Denv=dev
+```bash
+./gradlew test -Denv=dev --tests "*AuthTests"
+./gradlew smokeTest -Denv=dev
 ```
 
 Dedicated Gradle tasks are available for common deterministic suites: `smokeTest`, `regressionTest`, `contractTest`, `pactProviderVerificationTest`, `securityTest`, and `containerTest`. Use `test -DincludeTags=...` only when you intentionally want raw JUnit tag filtering; live tags require explicit credentials and network access.
@@ -86,6 +95,12 @@ JUnit tags are available as `smoke`, `regression`, `negative`, `known-demo-api-l
 
 Run live public API tests only when credentials and network access are intentionally available:
 
+```bash
+export BOOKER_USERNAME="<restful-booker-user>"
+export BOOKER_PASSWORD="<restful-booker-password>"
+./gradlew liveTest -Denv=dev
+```
+
 ```powershell
 $env:BOOKER_USERNAME="<restful-booker-user>"
 $env:BOOKER_PASSWORD="<restful-booker-password>"
@@ -96,27 +111,27 @@ Scheduled CI runs `liveSmokeTest` weekly (Sunday 00:00 UTC) against the configur
 
 Run the full quality gate used by CI:
 
-```powershell
-.\gradlew.bat clean check securityScan allureReport -Denv=dev
+```bash
+./gradlew clean check securityScan allureReport -Denv=dev
 ```
 
 Generate OpenAPI endpoint coverage:
 
-```powershell
-.\gradlew.bat openApiCoverageReport
+```bash
+./gradlew openApiCoverageReport
 ```
 
 Generate Allure:
 
-```powershell
-.\gradlew.bat allureReport
+```bash
+./gradlew allureReport
 ```
 
 Run with Docker:
 
-```powershell
-$env:ENV="dev"
-$env:GITHUB_TOKEN="<token>"
+```bash
+export ENV=dev
+export GITHUB_TOKEN="<token>"
 docker compose up --build
 ```
 
@@ -177,14 +192,14 @@ The metrics contract reports zero test-level retries by design. See the [reliabi
 
 Generate a local SBOM plus OSV scan instructions:
 
-```powershell
-.\gradlew.bat securityScan
+```bash
+./gradlew securityScan
 ```
 
 If `osv-scanner` is installed, `securityScan` runs it against `build/reports/cyclonedx/bom.json` and fails on reported vulnerabilities. To fail when the scanner is missing, run:
 
-```powershell
-.\gradlew.bat securityScan -PrequireOsvScanner=true
+```bash
+./gradlew securityScan -PrequireOsvScanner=true
 ```
 
 ## Project Structure
@@ -236,21 +251,21 @@ Do not distribute `.gradle/`, `.idea/`, or `build/` as part of the portfolio sou
 
 ## Documentation
 
-- [Portfolio Review Guide](docs/Portfolio_Review_Guide.md)
+- [Portfolio Review Guide](docs/portfolio-review-guide.md)
 - [Current verification record](docs/evidence/latest-verification.md)
 - [Enterprise adaptation](docs/enterprise-adaptation.md)
-- [Configuration Guide](docs/Configuration_Guide.md)
-- [Execution Guide](docs/Execution_Guide.md)
-- [Writing Tests](docs/Writing_Tests.md)
-- [Debugging Test Failures](docs/Debugging_Test_Failures.md)
-- [Dos and Don'ts](docs/Dos_And_Dont.md)
+- [Configuration Guide](docs/configuration-guide.md)
+- [Execution Guide](docs/execution-guide.md)
+- [Writing Tests](docs/writing-tests.md)
+- [Debugging Test Failures](docs/debugging-test-failures.md)
+- [Dos and Don'ts](docs/dos-and-dont.md)
 - [Security Test Strategy](docs/SECURITY_TEST_STRATEGY.md)
 - [Threat Model](docs/security/aria-api-framework-threat-model.md)
 - [Reliability and Quarantine Policy](docs/RELIABILITY_POLICY.md)
 - [Failure Example and Triage](docs/failure-example.md)
 - [Seeded Defect Examples](docs/seeded-defects.md)
 - [Architecture](docs/ARCHITECTURE.md)
-- [Architecture Decision Records](docs/Adr/README.md)
+- [Architecture Decision Records](docs/adr/README.md)
 
 ## Repository Governance
 

docs/evidence/latest-verification.md

@@ -10,7 +10,7 @@
 | Evidence class | Controlled and scheduled-live |
 | Result counts | 66 tests, 66 passed, 0 failed, 0 errors, 0 skipped (13.695s), from JUnit XML |
 | Report | [Allure report](https://qa-test-automation-frameworks.github.io/aria-api-framework/) |
-| Known limitations | [Known issues](../known-issues.md) and [review guide](../Portfolio_Review_Guide.md) |
+| Known limitations | [Known issues](../known-issues.md) and [review guide](../portfolio-review-guide.md) |
 
 The machine-readable record with the exact SHA, run ID/URL, conclusion, and result
 counts is published at [`latest-verification.json`](latest-verification.json). This

docs/Portfolio_Review_Guide.md → docs/portfolio-review-guide.md

@@ -4,7 +4,7 @@ This guide is a short evidence-based path through the repository. Claims below l
 
 ## Recommended Review Order
 
-1. Read the [architecture](ARCHITECTURE.md) and [ADR index](Adr/README.md).
+1. Read the [architecture](ARCHITECTURE.md) and [ADR index](adr/README.md).
 2. Inspect [`BaseApiClient`](../src/main/java/com/aria/framework/clients/BaseApiClient.java), services, and typed request/response models.
 3. Review [`RedactionPolicy`](../src/main/java/com/aria/framework/reporting/RedactionPolicy.java) and the [threat model](security/aria-api-framework-threat-model.md).
 4. Read the owned fixture and atomic concurrency test under [`src/test`](../src/test/java/com/aria/framework/).