Simplify specification documentation structure and add an entry point

## Summary

Complete the first stage of the specification documentation cleanup:

1. Add a simple entry point for the documents that remain.
2. Delete 27 files that are clearly obsolete, invalid, superseded, or unused.
3. Keep the active documentation hierarchy flat.
4. Preserve the existing names and paths of retained documents.

Detailed content revisions are intentionally deferred to follow-up work.

## Scope

This issue covers documentation structure and the high-level document set only.

In scope:

- Create `documentation/README.md`.
- Identify the purpose of each retained document or multi-file document set.
- Delete documents that no longer have a valid purpose.
- Remove empty directories and assets made unused by those deletions.
- Update repository-owned links affected by deleted files.
- Repair outdated links in retained documents only where required by this cleanup.

Out of scope:

- Rewriting the detailed content of retained documents.
- Revalidating individual API, OAV, OAD, or linter rules.
- Updating commands, examples, runtime versions, or troubleshooting procedures inside retained documents.
- Refactoring `ci-fix.md`.
- Refactoring API reviewer-agent documentation.
- Moving implementation documentation into `eng/` or `.github/`.
- Reworking API Scenario or RESTler instructions.
- Renaming retained documents.
- Reorganizing external documentation.

## Task 1: Create `documentation/README.md`

- Create `documentation/README.md`.
- Keep the README short and focused on the documents that remain in this directory.
- Add one entry for each retained user-facing standalone document and multi-file document set.
- For each entry, include:
- Document name and link
- One-sentence purpose
- Primary audience
- TypeSpec, OpenAPI, or shared applicability
- Group entries with README headings rather than creating category directories.
- Include separate headings for:
- Getting started
- Validation and rule references
- Review tooling
- SDK and release automation implementation
- Specification testing
- Legacy OpenAPI samples

## Task 2: Retain the current document set

Keep the following documents at their existing names and paths. Detailed content changes are not part of this issue; only link-target repairs required by this cleanup are included.

### Getting started

- Keep `Getting-started-with-TypeSpec-specifications.md`.
- Keep `Getting started with OpenAPI specifications.md`.

### Validation and rule references

- Keep `ci-fix.md`.
- Keep `openapi-authoring-automated-guidelines.md`.
- Keep `openapi-authoring-manual-guidelines.md`.
- Keep `Semantic-and-Model-Violations-Reference.md`.
- Keep `BreakingChange-Oad-Rules-Mapping.md`.
- Keep `uniform-versioning.md`.
- Keep `x-ms-examples.md`.

### Review tooling

- Keep `api-reviewer-agent.md`.

### SDK and release automation implementation

- Keep `release-plan-auto-generation.md`.
- Keep `sdkautomation/README.md`.

### Specification testing

- Keep `api-scenario/`.
- Keep `restler/`.

### Legacy OpenAPI samples

- Keep `samplefiles/`.
- Keep `samplefiles-dp/`.
- Keep their existing legacy/obsolete warnings.

### Supporting files

- Keep `documentation/cspell.yaml`.
- Keep only images referenced by retained documents.

## Task 3: Delete obsolete and superseded documents

Delete only the files listed below. Every deletion must retain the reason in the pull request description.

| Delete | Explicit reason | Replacement or disposition |
| --- | --- | --- |
| `Breaking changes guidelines.md` | The document marks itself deprecated. It also contains incomplete sections and guidance that conflicts with the current immutable-version and breaking-change process. Keeping it makes an obsolete policy appear normative. | Link directly to the current breaking-change policy and retain `BreakingChange-Oad-Rules-Mapping.md` only as a tool rule mapping. |
| `FAQ.md` | The page is Swagger-centric, uses obsolete `master` and private-repository process language, references removed checks, and duplicates current PR/check guidance. | Use the current PR/check documentation linked from `documentation/README.md`. |
| `SwaggerValidationTools.md` | It recommends Node.js 7.10, `oad@0.1.7`, old global-install commands, and an obsolete suppression location. These instructions can produce incorrect local environments and results. | Retain `ci-fix.md` as the repository check index and link current owning-tool documentation. |
| `creating-swagger.md` | The document is an 885-line Swagger 2.0 and early AutoRest tutorial last substantively maintained in 2019. It duplicates external format/tool documentation and teaches obsolete SDK-generation patterns. | Keep `Getting started with OpenAPI specifications.md` as the concise repository-specific legacy OpenAPI entry point. |
| `swagger-checklist.md` | It is a thin landing page whose useful targets are already directly accessible. It also links the archived `Azure/openapi-validation-tools` repository and an obsolete `arm-redis` path. | Link retained repository rule references directly from `documentation/README.md` and the OpenAPI entry page. |
| `swagger-extensions.md` | The file has contained only a three-line external redirect since 2017. Other documents link to anchors that do not exist in this file, so retaining it creates broken navigation. | Update inbound links to the current AutoRest extension documentation before deleting the file. |
| `swagger-bootstrap.json` | The file is not valid JSON: it contains C-style comments, a missing comma, a trailing comma, and a mismatched parameter reference. It is also inconsistent with the current TypeSpec-first authoring path. | Use the current TypeSpec project templates; the legacy OpenAPI entry page may link a valid external OpenAPI example if required. |
| `typespec-rest-api-dev-process.md` | The process is maintained elsewhere and this copy has drifted. It permits Node 18, contains conflicting `npm install`/`npm ci` guidance, includes obsolete private-branch details, and links the SDK lifecycle through a stale handoff. | Keep `Getting-started-with-TypeSpec-specifications.md` as the repository-specific checklist and link the current detailed process. |
| `directory-structure.md` | The content is maintained elsewhere and the local copy has already diverged: it still describes migration completion “by March 2026” after that date and does not reflect the current enforcement status. Retaining two copies causes future drift. | Replace affected inbound links with the current specification folder structure guide. |
| `glossary.md` | It duplicates the maintained specification glossary and is incomplete relative to terms used by nearby documents, including `service group`. It has no unique repository behavior to preserve. | Replace the inbound reference from `uniform-versioning.md` with the maintained specification glossary. |
| `swagger-authoring-descriptions.md` | Its general writing guidance is maintained elsewhere, while this copy contains dead `worldready.cloudapp.net` links and obsolete references to CodeFlow and old organizations. It has no current repository-specific workflow. | Link current API documentation and description guidance from the relevant entry page. |
| `swagger-accuracy-report.md` | It documents the removed traffic-validation flow, contains a broken `Engine Settings` link, and depends on screenshots from that obsolete pipeline. Keeping it implies that contributors can still run or receive this report. | No replacement is needed for the removed check. RESTler documentation remains available for currently supported RESTler usage. |
| `release-request/rules-for-release-request.md` | The file contains only one sentence and one link. It has no repository-specific instructions and is not discoverable as an independent workflow. | Put the link, if still needed, in the appropriate retained entry document or repository navigation. |
| `code-gen/configure-cli.md` | The file was last substantively updated in 2021 and describes the old AutoRest CLI generator/readme configuration. It also contains incorrect copied wording referring to JavaScript and duplicates Python SDK configuration. | Use current SDK-generation documentation; no repository-local CLI generator tutorial is required. |
| `code-gen/configure-go-sdk.md` | The file describes legacy `--track2` AutoRest generation and embeds SDK-repository testing instructions that do not belong in specification documentation. Its generator commands and automation model have drifted. | Use current SDK-generation and Go SDK repository documentation. |
| `code-gen/configure-python-sdk.md` | The file documents old AutoRest readme, multi-api, package-version, and output-folder configuration rather than the current TypeSpec emitter and SDK-generation path. | Use current SDK-generation and Python SDK repository documentation. |
| `code-gen/configure-typescript-sdk.md` | The file has not been substantively updated since 2020 and pins the obsolete `@microsoft.azure/autorest.typescript@4.2.2` generator while describing outdated multi-package behavior. | Use current SDK-generation and JavaScript SDK repository documentation. |
| `x-ms-pageable/example1.cs` | AutoRest v1 generated Track 1 C# using `Microsoft.Rest.Azure`, unchanged since 2016. Generated SDK output is not source documentation. | Retain current `x-ms-pageable` rule links in the automated-rule reference. |
| `x-ms-pageable/example2.cs` | AutoRest v1 generated Track 1 C# using `Microsoft.Rest.Azure`, unchanged since 2016. Generated SDK output is not source documentation. | Retain current `x-ms-pageable` rule links in the automated-rule reference. |
| `x-ms-pageable/example3.cs` | AutoRest v1 generated Track 1 C# using `Microsoft.Rest.Azure`, unchanged since 2016. Generated SDK output is not source documentation. | Retain current `x-ms-pageable` rule links in the automated-rule reference. |
| `x-ms-pageable/example1.yaml` | The YAML exists only as input for the obsolete generated C# example and is not linked as current authoring guidance. | Current extension/rule documentation is sufficient. |
| `x-ms-pageable/example2.yaml` | The YAML exists only as input for the obsolete generated C# example and is not linked as current authoring guidance. | Current extension/rule documentation is sufficient. |
| `x-ms-pageable/example3.yaml` | The YAML exists only as input for the obsolete generated C# example and is not linked as current authoring guidance. | Current extension/rule documentation is sufficient. |
| `api-scenario/how-to/armTemplate.png` | The image has no inbound reference anywhere in the repository, so it cannot be discovered or used by a reader. | No replacement is needed. |
| `images/check-in-restler-config.png` | The image is used only by the obsolete `swagger-accuracy-report.md` flow and becomes orphaned when that document is deleted. | No replacement is needed. |
| `images/traffic-validation-pipeline-artifacts.png` | The screenshot shows artifacts from the removed traffic-validation pipeline and is used only by `swagger-accuracy-report.md`. | No replacement is needed. |
| `images/traffic-validation-pipeline-comment.png` | The screenshot shows comments from the removed traffic-validation pipeline and is used only by `swagger-accuracy-report.md`. | No replacement is needed. |

- Remove `code-gen/`, `release-request/`, `x-ms-pageable/`, and `images/` after the listed files are deleted and the directories are empty.
- Do not delete any additional file without adding its explicit reason and replacement/disposition to this issue first.

## Task 4: Repair structural links only

- Search the repository for links to deleted documents.
- Remove links that no longer have a useful destination.
- Replace links with a canonical destination when one already exists.
- Update `documentation/README.md` after all deletions.
- Do not rewrite surrounding document content beyond what is required to prevent broken navigation.
- Do not rename or move retained documents.
- Verify that retained images and sample directories still have active inbound links.

## Expected structure

The resulting structure should remain flat except for existing multi-file document sets:

```text
documentation/
├── README.md
├── Getting started with OpenAPI specifications.md
├── Getting-started-with-TypeSpec-specifications.md
├── BreakingChange-Oad-Rules-Mapping.md
├── Semantic-and-Model-Violations-Reference.md
├── api-reviewer-agent.md
├── ci-fix.md
├── cspell.yaml
├── image-3.png
├── openapi-authoring-automated-guidelines.md
├── openapi-authoring-manual-guidelines.md
├── release-plan-auto-generation.md
├── sdkautomation/
├── uniform-versioning.md
├── x-ms-examples.md
├── api-scenario/
├── restler/
├── samplefiles/
└── samplefiles-dp/
```

Referenced images may remain in their current locations.

## Follow-up work

Create separate follow-up issues after this structural cleanup for:

- Detailed TypeSpec entry-page updates.
- Detailed legacy OpenAPI entry-page updates.
- `ci-fix.md` simplification.
- Rule and violation reference validation.
- API reviewer-agent documentation restructuring.
- Moving implementation documentation beside code.
- API Scenario and RESTler content updates.
- Documentation link and freshness automation.

## Acceptance criteria

- `documentation/README.md` exists and lists every retained document and document set.
- The active documentation hierarchy is flat except for existing multi-file document sets.
- Retained documents keep their existing names and paths.
- All 27 files identified for deletion are removed.
- Empty directories and newly orphaned assets are removed.
- No repository-owned link points to a deleted document.
- Every retained user-facing document and document set is reachable from `documentation/README.md`.
- No detailed content rewrite is included in this change.