fix: prepare 0.1.0 stable release

Author: tensornull

.github/workflows/ci.yml

@@ -97,6 +97,8 @@ jobs:
         run: npm run build
       - name: Validate the package shape
         run: npm run test:package
+      - name: Execute the documented examples against a packed artifact
+        run: npm run test:examples
       - name: Verify live-smoke semantic checks with mocked transport
         run: npm run test:live-contract
       - name: Test packed-package fixtures
@@ -188,6 +190,7 @@ jobs:
     name: Latest OpenAI 6.x canary / Node.js 24
     if: >-
       github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch' ||
       (github.event_name == 'pull_request' && github.actor == 'dependabot[bot]')
     runs-on: ubuntu-latest
     timeout-minutes: 20

.github/workflows/publish.yml

@@ -135,6 +135,7 @@ jobs:
           npm run test:package -- \
             --tarball "${{ steps.pack.outputs.tarball }}" \
             --tag "${{ github.event.release.tag_name }}"
+          npm run test:examples -- --tarball "${{ steps.pack.outputs.tarball }}"
           npm run test:fixtures -- --tarball "${{ steps.pack.outputs.tarball }}"
       - name: Upload the verified release artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

.github/workflows/release-please.yml

@@ -14,7 +14,7 @@ concurrency:
 
 jobs:
   release-please:
-    name: Prepare or publish a reviewed release
+    name: Prepare a reviewed release pull request
     if: vars.RELEASE_PLEASE_ENABLED == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 10
@@ -27,3 +27,4 @@ jobs:
         with:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
+          skip-github-release: true

AGENTS.md

@@ -51,18 +51,13 @@ repository.
   merely to complete lifecycle cleanup. Fail closed and report the exact state
   whenever a required cleanliness, fetch, or fast-forward condition is not met.
 
-## Current Milestone: Public Preview
-
-Private Remote Validation and Public Preview pre-visibility preparation are
-complete. The repository remains private at the visibility authorization gate.
-Repository-local source, tests, documentation, metadata, fixtures, and
-workflows may be changed and verified locally. Private topic pushes, pull
-requests, merges, and credential-free CI are permitted only when the current
-maintainer request explicitly authorizes them; this file records scope and does
-not grant that authorization. Stop before changing repository visibility:
-making the canonical repository public and configuring or exercising
-public-only settings, protected environments, secrets, or live smoke require
-separate explicit maintainer authorization.
+## Current Milestone: Stable 0.1.0
+
+Private Remote Validation, Public Preview, and Registry Alpha are complete.
+The canonical repository is public, and `0.1.0-alpha.3` is available from npm's
+`next` channel with OIDC provenance and verified public-install evidence. The
+current work promotes the existing 0.1 protocol surface to `0.1.0` on npm's
+`latest` channel. Do not begin the 0.2 provider adapters during this milestone.
 
 The accepted identity is:
 
@@ -82,28 +77,13 @@ The unscoped `cometapi` package is the primary Node SDK. `@cometapi` is the
 standard scope for future official scoped packages; do not introduce new
 official packages under `@cometapi-dev`.
 
-Before requesting visibility-change authorization:
-
-1. Confirm the current `main` includes every approved private closeout and that
-   its blocking Node.js 22 and 24 CI checks pass.
-2. Run the complete local offline, package, fixture, compatibility,
-   self-containment, public-content, secret, workflow-static-validation, and
-   Public Preview gates from the final private `main`.
-3. Review open failing dependency-update pull requests before visibility
-   changes and repair, close, or explicitly defer them with a recorded reason;
-   do not treat their branch failures as evidence that the current `main`
-   failed validation.
-4. Confirm the repository remains private and that public-only repository or
-   tag rules, Private Vulnerability Reporting, secrets, protected environments,
-   Trusted Publishing, live smoke, tags, releases, and registry publication
-   have not been configured or exercised.
-5. Record the final private evidence and stop for explicit maintainer
-   authorization before changing repository visibility.
-
-Private repository creation, the sanitized first history, and the initial push
-are complete historical steps and must not be repeated. Their procedure and
-evidence belong in `RELEASING.md`. Keep Release Please disabled through the
-initial manual alpha.
+Stable promotion uses Release Please only for its reviewed version and
+changelog pull request. Because the pinned Release Please v5 path is vulnerable
+to an upstream single-package tagging defect, it must skip GitHub release
+creation. A maintainer creates and reviews the immutable `v0.1.0` release
+manually against the exact merged release commit. The publish workflow then
+performs exact-artifact verification, the bounded live smoke, npm OIDC
+publication, and registry verification.
 
 ## Product Contract
 
@@ -211,6 +191,7 @@ npm run lint
 npm run format:check
 npm run test:secrets
 npm run test:package
+npm run test:examples
 npm run test:live-contract
 npm run test:fixtures
 npm run test:compat
@@ -266,7 +247,7 @@ Before Public Preview, run `npm run check:public-preview`. The gate must fail
 after reporting all violations until canonical identity, contacts, repository
 metadata, and durable public-facing content are complete.
 
-### First-publication bootstrap
+### First-publication bootstrap history
 
 The normal npm release path uses Trusted Publishing on a GitHub-hosted runner
 with Node.js 22.14.0 or later, npm CLI 11.5.1 or later, and an exact
@@ -278,10 +259,9 @@ short-lived granular read/write token with the minimum available scope and
 non-interactive 2FA bypass from an owner account protected by 2FA. Expose it
 only through a protected GitHub Environment for one reviewed immutable-tag run,
 publish with public access and provenance, then immediately configure OIDC,
-remove the secret, revoke the token, restrict token-based publishing, and
-publish `0.1.0-alpha.2` through OIDC. Verify its provenance and confirm the
-`next` dist-tag resolves to `0.1.0-alpha.2`. Never make this exception a
-reusable workflow path.
+remove the secret, revoke the token, and restrict token-based publishing. This
+historical bootstrap ended with `0.1.0-alpha.1`; `0.1.0-alpha.3` subsequently
+verified the OIDC-only path. Never make the exception a reusable workflow path.
 
 ## Authorization and evidence
 

COMPATIBILITY.md

@@ -84,6 +84,7 @@ streaming, and model-list return types.
 ```bash
 npm run test
 npm run test:package
+npm run test:examples
 npm run test:live-contract
 npm run test:fixtures
 npm run test:compat

README.md

@@ -53,6 +53,7 @@ For source-checkout testing, retain and verify one exact tarball:
 mkdir -p .artifacts
 npm pack --pack-destination .artifacts
 npm run test:package -- --tarball .artifacts/cometapi-0.1.0-alpha.3.tgz
+npm run test:examples -- --tarball .artifacts/cometapi-0.1.0-alpha.3.tgz
 npm run test:fixtures -- --tarball .artifacts/cometapi-0.1.0-alpha.3.tgz
 ```
 
@@ -93,6 +94,17 @@ const response = await client.responses.create({
 });
 
 console.log(response.output_text);
+
+const stream = await client.chat.completions.create({
+  model: "gpt-5.4",
+  messages: [{ role: "user", content: "Write one sentence about comets." }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}
+process.stdout.write("\n");
 ```
 
 ## CommonJS quick start
@@ -103,6 +115,12 @@ const { CometAPI } = require("cometapi");
 const client = new CometAPI();
 
 async function main() {
+  const completion = await client.chat.completions.create({
+    model: "gpt-5.4",
+    messages: [{ role: "user", content: "Reply with one short greeting." }],
+  });
+  console.log(completion.choices[0]?.message?.content ?? "");
+
   const models = await client.models.list();
   for (const model of models.data) {
     console.log(model.id);
@@ -115,26 +133,10 @@ main().catch((error) => {
 });
 ```
 
-## Streaming Chat Completions
-
-```js
-import { CometAPI } from "cometapi";
-
-const client = new CometAPI();
-const stream = await client.chat.completions.create({
-  model: "gpt-5.4",
-  messages: [{ role: "user", content: "Write one sentence about comets." }],
-  stream: true,
-});
-
-for await (const chunk of stream) {
-  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
-}
-```
-
 Runnable ESM and CommonJS examples are in [`examples/`](./examples/). The
-packed fixtures execute equivalent mocked public calls; executing live examples
-against a packed artifact remains a separately authorized release gate.
+offline example gate executes these exact files against the packed artifact with
+a fail-closed mocked transport. Executing them against the live API remains a
+separately authorized operation.
 
 ## Custom options
 
@@ -186,6 +188,7 @@ npm run lint
 npm run format:check
 npm run test:secrets
 npm run test:package
+npm run test:examples
 npm run test:live-contract
 npm run test:fixtures
 npm run test:compat

RELEASING.md

@@ -82,13 +82,11 @@ evidence is complete only when `npm owner ls cometapi` lists the
 maintainer-confirmed `cometapi_dev` account; until then this remains a Registry
 Alpha prerequisite.
 
-For the current Public Preview milestone, private topic pushes, pull requests,
-merges, and credential-free CI are the only remote actions that may be
-authorized before the visibility transition. This document defines allowable
-release mechanics but grants no standing remote-write permission; the current
-maintainer request must explicitly authorize each task's remote actions.
-Changing repository visibility and every subsequent public-only configuration
-or live action require separate authorization.
+Public Preview and Registry Alpha are complete. For the current stable
+milestone, topic pushes, pull requests, merges, the immutable GitHub Release,
+the bounded live smoke, npm publication, and environment approvals still
+require authorization from the current maintainer request. This document
+defines allowable mechanics but grants no standing remote-write permission.
 
 ## Candidate verification gate
 
@@ -103,6 +101,7 @@ npm run lint
 npm run format:check
 npm run test:secrets
 npm run test:package
+npm run test:examples
 npm run test:live-contract
 npm run test:fixtures
 npm run test:compat
@@ -119,7 +118,10 @@ failures, skipped checks, and unavailable runtime/tool checks.
 
 `npm run test:package` builds and inspects a candidate tarball and runs package
 metadata, export, declaration, `publint`, Are the Types Wrong, and dry-run pack
-checks. `npm run test:fixtures` installs a candidate tarball into clean ESM,
+checks. `npm run test:examples` installs one exact tarball with the locked OpenAI
+version, checks dependency deduplication, and executes the canonical README ESM
+and CommonJS examples with fail-closed mocked transport.
+`npm run test:fixtures` installs a candidate tarball into clean ESM,
 CommonJS, and compatible-OpenAI host applications. Both commands accept
 `--tarball <path>` so the publication workflow can pack once, inspect and
 install the exact artifact, then upload that same file. `npm run test:compat`
@@ -206,8 +208,8 @@ or publishing the immutable release. Validate the exact committed state with:
 
 ```bash
 node scripts/validate-release.mjs \
-  --tag v0.1.0-alpha.1 \
-  --release-prerelease true \
+  --tag v0.1.0 \
+  --release-prerelease false \
   --require-final \
   --require-releasable-docs
 ```
@@ -229,10 +231,16 @@ The repository maintains four independently auditable workflows:
   concurrency group. Scheduled and manual live execution requires
   `LIVE_SMOKE_ENABLED=true`.
 - `release-please.yml`: a human-reviewed version and changelog PR from
-  Conventional Commits and requires `RELEASE_PLEASE_ENABLED=true`. It remains
-  disabled through the initial manual alpha. Merging a later release PR prepares
-  a draft GitHub release; a maintainer must review and publish the draft so its
-  `release.published` event can trigger publication.
+  Conventional Commits and requires `RELEASE_PLEASE_ENABLED=true`. It uses the
+  default `GITHUB_TOKEN` and deliberately skips tag and GitHub Release creation.
+  Because that token does not trigger CI for its generated PR, a maintainer
+  commits the stable README, security, support, compatibility, and roadmap
+  state to the generated branch, then manually dispatches `ci.yml` with that
+  branch as `ref`. Merge is forbidden unless `gh pr checks` reports every
+  required context on the exact final PR head; if GitHub does not associate the
+  dispatched checks with that commit, stop rather than bypass protection.
+  The manual dispatch also runs the latest-compatible OpenAI 6.x lane so the
+  candidate head has minimum, locked, and latest-within-major evidence.
 - `publish.yml`: rejects mutable releases and tag commits outside `main`, packs
   and tests one exact artifact, requires a protected live smoke for that release
   tag, and publishes the same file through npm OIDC. Registry token credentials
@@ -410,6 +418,22 @@ executed README examples against the packed artifact, release-PR/tag/changelog/
 manifest version agreement, reviewed security and compatibility status, and
 post-publication registry evidence.
 
+Release Please is limited to the stable PR because its v5 single-package path
+has an open upstream tagging defect when component names are omitted from tags.
+After the reviewed release PR merges, create a draft `v0.1.0` GitHub Release
+manually against the exact merge commit, review it with `prerelease=false`, and
+publish it only once immutable releases are enabled. After successful manual
+tagging, change the merged Release Please PR label from `autorelease: pending`
+to `autorelease: tagged` so future release PRs are not blocked.
+
+Release Please does not author the final public status text. After it opens the
+`0.1.0` PR, a maintainer pushes a focused documentation commit to that same
+branch: README switches from `next`/prerelease to `latest`/stable and records
+the exact publication approval; SECURITY and SUPPORT remove prerelease-only
+policy; COMPATIBILITY and ROADMAP identify the stable candidate without
+claiming it is already released. If Release Please updates the branch again,
+repeat the review and CI dispatch against the new final head.
+
 ## Verification record
 
 Every release candidate records these evidence layers separately:

ROADMAP.md

@@ -1,7 +1,7 @@
 # CometAPI TypeScript and Node.js SDK Roadmap
 
-Status: Public Preview and Registry Alpha complete; 0.1.0 stable planned
-Last updated: 2026-07-27
+Status: Public Preview and Registry Alpha complete; 0.1.0 stable in progress
+Last updated: 2026-07-28
 Repository contract: This roadmap is self-contained and is the public source
 of truth for this repository's release sequence.
 
@@ -29,7 +29,7 @@ available from npm's `next` channel.
 | Private Remote Validation  | Complete    | The sanitized private repository passes real credential-free default-branch CI; public-only controls and live tests remain disabled.      |
 | Public Preview             | Complete    | The public repository has blocking CI, repository rules, security reporting, protected environments, and authorized live-smoke evidence.  |
 | 0.1.x Registry Alpha       | Complete    | Early adopters can install a functional, provenance-verified prerelease from npm's `next` channel through the OIDC-only publication path. |
-| 0.1.0 Stable               | Planned     | Users can install a fully verified package from npm's default channel.                                                                    |
+| 0.1.0 Stable               | In progress | Users can install a fully verified package from npm's default channel.                                                                    |
 | 0.2.0 provider-native text | Planned     | Users can opt into Anthropic Messages and Gemini text adapters through isolated subpath exports.                                          |
 | 0.3.0 CometAPI resources   | Planned     | Users receive typed access to the first stable CometAPI-specific account or platform resources.                                           |
 | Media and task APIs        | Later       | Users receive typed image, video, audio, upload, polling, and task lifecycle helpers after their contracts are stable.                    |
@@ -311,6 +311,11 @@ Stable publication requires a human-reviewed release PR and protected npm
 environment approval while the SDK remains pre-1.0. Manual workflows may build
 or dry-run packages but may not publish an arbitrary commit.
 
+For the 0.1.0 promotion, Release Please creates only the reviewed PR and skips
+tag and Release creation. After that PR merges, a maintainer manually creates
+the immutable `v0.1.0` Release against its exact merge commit; publishing the
+Release triggers the existing verified OIDC pipeline.
+
 Public Preview needs no registry workflow. Registry Alpha publishes from a
 human-reviewed immutable prerelease tag under the `next` dist-tag through OIDC
 or, only when npm cannot preconfigure Trusted Publishing, through the one-time

examples/README.md

@@ -8,11 +8,12 @@ default example model, `gpt-5.4`.
   Models.
 
 They require `COMETAPI_KEY` for authorized live use. Do not run them against the
-live API without an explicit request budget and authorization. Release fixtures
-execute equivalent calls with mocked transport against the exact packed
-tarball; mocked execution is package evidence, not live compatibility evidence.
+live API without an explicit request budget and authorization. The
+`test:examples` gate executes these original files with a fail-closed mocked
+transport against the exact packed tarball; mocked execution is package
+evidence, not live compatibility evidence.
 
-After the Registry Alpha is published under npm's `next` dist-tag:
+Registry Alpha is available under npm's `next` dist-tag:
 
 ```bash
 npm install cometapi@next

package.json

@@ -62,6 +62,7 @@
     "test:live": "node scripts/live-smoke.mjs",
     "test:live-contract": "node scripts/test-live-smoke-contract.mjs",
     "test:package": "node scripts/test-package.mjs",
+    "test:examples": "node scripts/test-examples.mjs",
     "test:fixtures": "node scripts/test-fixtures.mjs",
     "test:compat": "node scripts/test-compat.mjs",
     "test:secrets": "node scripts/check-secrets.mjs",