docs: add status sections, fix the React quick start, drop the broken CSS import

[darrenapfel]

What this fixes. Four documentation problems. First, the root README's React quick start imported @deepgram/ui/styles.css, which fails to build against the published @deepgram/ui 0.1.4 because that file ships raw Tailwind source rather than compiled CSS (a fix is proposed separately in the deepgram/ui repository). The import is also unnecessary: @deepgram/ui embeds its compiled styles in the JavaScript bundle and injects them automatically. Second, the same quick start rendered AgentConversation with no children and placed the components outside the data-dg-agent element that scopes the injected styles, so a copied example showed no transcript and no theming. The four React examples (10 to 13) had the same empty AgentConversation. Third, none of the READMEs stated the packages' maturity. Fourth, the development and contribution instructions cloned over SSH, which fails without a GitHub SSH key.

The change.

• The React quick start drops the CSS import, wraps the components in a <div data-dg-agent>, renders the conversation through the useAgentConversation hook in a child component, and says under the example that the injected styles apply only inside an element carrying data-dg-agent.
• Examples 10, 11, 12 and 13 import useAgentConversation and AgentMessage, render one AgentMessage per conversation entry, and show the same code they execute.
• Status sections in the root README and in both package READMEs (packages/sdk, packages/widget, the files npmjs.com renders) carry neutral factual wording: the packages are pre-1.0, interfaces may change between minor versions, and releases follow the libraries rather than a fixed schedule. The root README's status paragraph names the surfaces the family provides (browser SDKs, React hooks and UI components, an embeddable widget). An earlier revision called the packages experimental and pointed production users to @deepgram/sdk; that wording was withdrawn pending a positioning decision with Corey, and whatever is agreed will be applied to all three status sections together.
• The root README's clone command and the three clone commands in .github/CONTRIBUTING.md use HTTPS. The core-SDK package README shows npm install first with bun as the alternative.
• .github/workflows/cdn-dryrun.yml (Greg Holmes, eb7f1ed): the credentialed CDN dry-run job skips on pull requests from forks, since GitHub withholds repository secrets from them. Same-repository pull requests and manual runs still perform the dry-run. Build, typecheck and tests run unchanged.

Validation. Build, typecheck and all 144 tests pass on the current head. The examples app builds clean with Vite. The corrected React quick start is the pattern that built in a clean-room Vite 8 project on 2026-08-24, and the [data-dg-agent] scoping of the message variables was confirmed against the published @deepgram/ui@0.1.4 bundle. The widget quick start (npm install @deepgram/agents-widget, import { init }) was built clean-room the same day.

Provenance. This change was written by an artificial-intelligence coding agent operating on a local clone, at the direction of Darren Apfel, and was validated as described above.

🤖 Generated with Claude Code

[darrenapfel]

Per review: the positioning sentences ("experimental" and the production-path steering toward @deepgram/sdk) are replaced with neutral factual status wording (pre-1.0, interfaces may change) pending the wording-alignment conversation — the full before/after set is documented, and either version can land once the positioning call is made.

🤖 Generated with Claude Code

[GregHolmes]

Fixed the fork-only CDN check in eb7f1ed. GitHub intentionally withholds repository secrets from pull_request workflows originating from forks, so the credentialed CDN dry-run now skips for fork PRs while the standard build/typecheck/test CI continues to run. Same-repository PRs and manual runs still perform the AWS dry-run.

Current checks: build-and-test passed; dryrun-widget skipped as intended.

[GregHolmes]

@darrenapfel - re-reviewed against current main at 92dfae1. The PR head remains eb7f1ed.

Verdict: request changes

Title: [B1] React quick start omits the @deepgram/ui styling scope

Summary: @deepgram/ui@0.1.4 injects compiled CSS from its JavaScript entry, so removing the separate CSS import is correct. However, its token bridge, extended message and interaction variables, dark-mode behavior, and preflight are scoped to [data-dg-agent]; AgentProvider does not render that wrapper.

Expected: Copying the quick start produces fully styled components using the automatically injected CSS.

Observed: Variables including --msg-user-bg, --msg-user-border, and --primary-hover are undefined, and scoped dark-mode/base behavior is absent because no ancestor has data-dg-agent.

Recommended fix: Wrap the controls in the styling scope:

<AgentProvider config={config}>
  <div data-dg-agent>
    <AgentStartButton />
    <Conversation />
    <AgentTextInput />
  </div>
</AgentProvider>

Title: [B2] Four React examples still render an empty transcript

Summary: The PR correctly identifies that AgentConversation renders only its children, but the same empty component remains in the four runnable conversation examples advertised by the root README.

Expected: Every React example with a conversation panel renders current conversation entries.

Observed: examples/10-react-sidebar/index.html:94, examples/11-react-inline/index.html:76, examples/12-react-floating/index.html:92, and examples/13-react-ui-standalone/index.html:80 render AgentConversation without children, so no transcript messages appear.

Recommended fix: In all four examples, import useAgentConversation and AgentMessage, render one AgentMessage per conversation entry, and update the displayed code to match the executable example.

Title: [B3] Package-status positioning has no agreed final version

Summary: The PR body says the status sections call the packages "experimental" and steer production users to @deepgram/sdk. The current head removes both claims, and the follow-up comment says the neutral wording is pending the wording-alignment conversation.

Expected: The checked-in status copy and PR description reflect one approved positioning decision.

Observed: The files contain neutral pre-1.0 wording, the PR body describes stronger experimental/production-path wording, and the latest author note says the decision is still pending.

Recommended fix: Confirm the intended status framing with Corey, apply it consistently to all three status sections, and update the PR body to describe the actual wording and changed CI scope.

Title: [S1] Contributor setup still uses the SSH clone path

Summary: The root development command moves to HTTPS so developers without a configured GitHub SSH key can clone the repo, but the contribution guide retains the SSH URL.

Expected: Either setup path can clone the public repository without an SSH key.

Observed: .github/CONTRIBUTING.md:17 still uses git clone git@github.com:deepgram/agent.git.

Recommended fix: Change it to git clone https://github.com/deepgram/agent.git.

Title: [S2] Status copy describes the whole package family as browser components

Summary: The family includes a core session SDK, React hooks/provider, UI components, and a widget. Calling all of them "embeddable browser components" understates the non-component packages.

Expected: The status paragraph accurately names the distinct developer surfaces.

Observed: README.md:11 says the whole family exists "to provide embeddable browser components."

Recommended fix: Use: "The packages in this family build on the Deepgram Voice Agent API to provide browser SDKs, React hooks and UI components, and an embeddable widget."

Verified: Full build, typecheck, and all 144 tests pass. The clean-room React sample compiles against published @deepgram/ui@0.1.4; restoring the removed CSS import reproduces the Vite failure; and the fork workflow guard behaves correctly.

[darrenapfel]

@GregHolmes thanks for the re-review. Pushed 5273ad4 with the following.

B1. The React quick start now wraps the components in a <div data-dg-agent>, and the note under the example says the injected styles apply only inside an element with that attribute. I confirmed in the published @deepgram/ui@0.1.4 bundle that --msg-user-bg and the other message variables sit under the [data-dg-agent] rule.

B2. Examples 10, 11, 12 and 13 now import useAgentConversation and AgentMessage, render one AgentMessage per conversation entry through a small Conversation component, and the displayed code matches the executable code. The examples app builds clean with Vite.

B3. I did not change the status wording. The neutral pre-1.0 text stays in all three status sections until Corey and I settle the positioning, and I will apply whatever we agree to all three at once. I have updated the PR description so it describes the wording that is actually in the files and the fork guard you added to the CDN dry-run workflow.

S1. The contribution guide now clones all three sibling repositories over HTTPS.

S2. Applied your sentence for the status paragraph as written.

Build, typecheck and the 144 tests pass locally on the new head.