Document HTTP typekits import and experimental status

[Copilot]

HTTP typekits were undocumented, requiring users to discover the required import @typespec/http/experimental/typekit through trial and error. Users also had no indication the API is experimental and subject to breaking changes.

Changes

• Usage section: Import instructions and code example showing typekit initialization
• Experimental warning: Caution banner indicating volatile API surface and potential breaking changes

Example

// This import was previously undocumented
import "@typespec/http/experimental/typekit";
import { $ } from "@typespec/compiler/typekit";
import { getHttpOperation } from "@typespec/http";

const [httpOperation] = getHttpOperation(program, operation);
const responses = $(program).httpOperation.flattenResponses(httpOperation);

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: Http typekits are not exposed and documentation is missing info on how to use</issue_title>
<issue_description>### Describe the bug

I had to add

import "@typespec/http/experimental/typekit";

To make them work in a non Alloy environment. Otherwise typescript doesn't see merged typekit declaration and missing all http typekits.

This should be either documented or exposed and working with http module import.

Reproduction

import { getHttpOperation } from "@typespec/http";
import { $ } from "@typespec/compiler/typekit";
// import "@typespec/http/experimental/typekit"; // uncomment to make this work


const [httpOperation] = getHttpOperation(program, operation);
$(program).httpOperation.flattenResponses(httpOperation);

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.</issue_description>

<agent_instructions>Indicate in the documentation for http typekits how to import the typekits. Also ensure thatr the documentation indicates that the typekits are experimental and may have breaking changes without notice.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@markcowl @artsiommiksiuk The typekit for http is currently experimental, the API surface area is volatile, and it is not documented so that customers do not inadvertently take a dependency on it without understanding the risks. This is why it is both exported as experimental and undocumented.

If the ask is to get the API to move the API from experimental to part of the public exports, that is ongoing work, but we cna use this issue to track it, if you like</comment_new>

• Fixes [Bug]: Http typekits are not exposed and documentation is missing info on how to use #8575

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.