## Summary

replaces #77378 
fixes #77290

 * Replace the 4000+ line `spec_oas3.json` file with one ~75 line overview file `entrypoint.yaml` which imports the various pieces from other directories.
 * Switched from JSON to YAML for "source" files because they're less noisy & more human-friendly. `package-registry` & `package-spec` both define specs in YAML as well. We can always convert them to JS for any library that needs it.



## Dev docs
### New structure

```
openapi/
├── README.md
├── bundled.json
├── bundled.yaml
├── components/
├── entrypoint.yaml
└── paths/
```

There are `README.md` files in `openapi`, `openapi/components`, & `openapi/paths` with information about the purpose, conventions, decisions, etc for that directory

* `entrypoint.yaml` is the overview file which links to the various files on disk.
* `bundled.{yaml,json}` is the resolved output of that entry & other files in a single file. 
    <details><summary>how these were generated (requires node 12+)</summary>

    ```
    nvm use 12;
    npx @redocly/openapi-cli bundle entrypoint.yaml -o bundled.json
    npx @redocly/openapi-cli bundle entrypoint.yaml -o bundled.yaml
    ```
    </details>

    <details><summary>How to generate with node 10+</summary>

    ```
    npx swagger-cli bundle -o bundled.json -t json entrypoint.yaml
    npx swagger-cli bundle -o bundled.yaml -t yaml entrypoint.yaml
    ```
    </details>

 * [Paths](paths/README.md): Started with a flat `paths` directory with each path in a separate file. We can move on to a nested file-per-operation like #77378 or any other approach later

    <details><summary><code>tree ./paths</code></summary>

    ```
    paths/
    ├── README.md
    ├── agent_policies.yaml
    ├── agent_policies@delete.yaml
    ├── agent_policies@{agent_policy_id}.yaml
    ├── agent_policies@{agent_policy_id}@copy.yaml
    ├── agent_status.yaml
    ├── agents.yaml
    ├── agents@bulk_upgrade.yaml
    ├── agents@enroll.yaml
    ├── agents@setup.yaml
    ├── agents@{agent_id}.yaml
    ├── agents@{agent_id}@acks.yaml
    ├── agents@{agent_id}@checkin.yaml
    ├── agents@{agent_id}@events.yaml
    ├── agents@{agent_id}@unenroll.yaml
    ├── agents@{agent_id}@upgrade.yaml
    ├── enrollment_api_keys.yaml
    ├── enrollment_api_keys@{key_id}.yaml
    ├── epm@categories.yaml
    ├── epm@packages.yaml
    ├── epm@packages@{pkgkey}.yaml
    ├── install@{os_type}.yaml
    ├── package_policies.yaml
    ├── package_policies@{package_policy_id}.yaml
    └── setup.yaml
    ```
    </details>

  * [Components](components/README.md): Reusable components like [`schemas`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject), [`responses`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject) [`parameters`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject), etc
    <details><summary><code>tree ./components</code></summary>

    ```
    components/
    ├── README.md
    ├── callbacks
    ├── examples
    ├── headers
    │   └── kbn_xsrf.yaml
    ├── links
    ├── parameters
    │   ├── kuery.yaml
    │   ├── page_index.yaml
    │   └── page_size.yaml
    ├── request_bodies
    ├── responses
    ├── schemas
    │   ├── access_api_key.yaml
    │   ├── agent.yaml
    │   ├── agent_event.yaml
    │   ├── agent_metadata.yaml
    │   ├── agent_policy.yaml
    │   ├── agent_status.yaml
    │   ├── agent_type.yaml
    │   ├── bulk_upgrade_agents.yaml
    │   ├── enrollment_api_key.yaml
    │   ├── new_agent_event.yaml
    │   ├── new_agent_policy.yaml
    │   ├── new_package_policy.yaml
    │   ├── package_info.yaml
    │   ├── package_policy.yaml
    │   ├── search_result.yaml
    │   └── upgrade_agent.yaml
    └── security_schemes
    ```    
</details>