[amafjarkasi]

Verified every README claim against the actual codebase (CLI, emitters, generated SDKs, files). Found and fixed several inaccuracies.

Code examples (TypeScript) — were broken

• `bearerAuth`/`apiKeyAuth` are emitted only when the spec declares those security schemes (the petstore fixture has none). Added a clarifying note.
• `streamSse` is not re-exported from `index.ts` (the barrel omits `./streaming`). Fixed the import to `./streaming`.
• `client.request()` lives on `ApiClient`, not the `SdkClient` returned by `createClient()`. Showed streaming via `ApiClient` directly.
• Go and Rust examples verified 100% accurate (no changes).

CLI reference — stale subset

• Replaced a 13-command subset block (missing 12 commands, wrong order) with a pointer to `specforge --help` + the most-used commands.
• `generate`: removed bogus `-V, --version` (it's a top-level flag); added 6 real undocumented flags (`--include-webhooks`, `--locale`, `--changelog`, `--changelog-previous`, `--version-prefix`, `--plugin`).
• `check`: added 5 real undocumented flags (`--deprecations`, `--disable`, `--enable`, `--severity`, `--config`).
• Added the missing `version` command to the subcommand table.

Roadmap + version pins — stale

• Added `v1.6.0`/`v1.6.1` checkpoints (the roadmap stopped at v1.5.0, implying it was current); updated the closing statement to 1.6.1.
• GitHub Action pin `@v0.2.2` → `@v1` (was badly stale).
• Release example tag `v0.1.0` → `v1.6.1`.

Supersedes #2 (which only had the roadmap fix). Doc-only.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[qodo-code-review]

PR Summary by Qodo

Docs: Correct README examples, CLI flags, roadmap, and version pins

📝 Documentation 🕐 10-20 Minutes

AI Description

• Fix TypeScript README examples to match actual SDK exports and client APIs.
• Refresh CLI docs to match current specforge --help output and real flags.
• Update roadmap/checkpoints and CI/release examples to current v1.6.1 pins.

Diagram

graph TD
  A["README.md"] --> B["TS examples"] --> C["SDK exports / API"]
  A --> D["CLI reference"] --> E["specforge --help"]
  A --> F["Roadmap & pins"] --> G["Release/Action versions"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Generate CLI docs from `specforge --help` in CI

• ➕ Prevents README drift when commands/flags change
• ➕ Reduces manual maintenance and review overhead
• ➕ Makes discrepancies detectable via automated checks
• ➖ Help output isn’t always ideal long-form documentation (needs curation)
• ➖ Requires a stable formatting contract for help text
• ➖ Adds CI/build complexity (doc generation step)

2. Doctest / compile-check README snippets

• ➕ Catches broken imports/exports and API mismatches automatically
• ➕ Keeps examples executable as the SDK surface evolves
• ➖ Requires harnessing paths/fixtures for generated SDKs
• ➖ May increase CI time (especially across languages)

Recommendation: The PR’s manual accuracy sweep is the right immediate fix and improves trust in the README. For longer-term durability, consider adding lightweight automation: (1) generate or at least validate the CLI command/flag section against specforge --help, and/or (2) add a small CI check that compiles/runs the TypeScript README snippet against a fixture SDK to prevent future export/API drift.

Files changed (1) +56 / -32

Documentation (1) +56 / -32

README.mdAlign README with actual TS SDK surface, CLI flags, and current versions +56/-32

Align README with actual TS SDK surface, CLI flags, and current versions

• Fixes TypeScript examples to use the correct imports ('streamSse' from './streaming'), clarifies when auth helpers are emitted, and demonstrates SSE streaming via 'ApiClient.request()'. Replaces a stale CLI command subset with guidance to use 'specforge --help', adds missing/undocumented flags for 'generate' and 'check', and adds the missing 'version' command to the command table. Updates roadmap checkpoints through v1.6.1 and refreshes release/GitHub Action version pins and guidance.

README.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (0) 📜 Skill insights (0)

1. Tree-shaking claim incorrect 🐞 Bug ≡ Correctness

Description

README now states that createClient() returns a "tree-shakeable" tag namespace, but the generated
TS SDK explicitly warns that createClient() imports all tag modules and is not the tree-shakeable
path. This can mislead users into shipping larger bundles than expected.

Code

README.md[334]

+> `createClient()` returns a tree-shakeable tag namespace (`client.pets.listPets`). For raw requests / streaming, use the `ApiClient` directly. The auth helpers (`bearerAuth`, `apiKeyAuth`) appear only when your spec declares those schemes.

Evidence

The generated TS barrel documents that createClient() imports all tag modules and recommends
direct tag imports for tree-shaking, contradicting the README claim.

examples/petstore-ts/sdk/src/index.ts[4-16]
examples/petstore-ts/sdk/src/index.ts[45-55]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README claims `createClient()` is tree-shakeable, but generated SDK docs state the opposite (it eagerly imports all tags). This mismatch misguides users about bundle size behavior.

## Issue Context
The generated TS barrel (`src/index.ts`) documents tree-shaking behavior and explicitly recommends importing individual tag modules instead of using `createClient()` when bundle size matters.

## Fix Focus Areas
- README.md[334-335]

## Proposed fix
Change the note to something like:
- “`createClient()` returns a convenient tag namespace (`client.pets.listPets`), but it imports all tags. For tree-shaking, import individual tag modules directly.”

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Streaming client drops auth 🐞 Bug ≡ Correctness

Description

The updated streaming example constructs a new ApiClient without passing auth, so streaming
requests will default to anonymousAuth() even though the example configures bearerAuth earlier.
This will fail (401/403) for authenticated streaming endpoints and is misleading as a copy/paste
snippet.

Code

README.md[R327-328]

+const api = new ApiClient({ baseUrl: "https://api.example.com" });
+const res = await api.request("GET", "/events");

Evidence

The generated ApiClient defaults auth to anonymousAuth() when opts.auth is omitted, so the
README’s separate ApiClient instance will not use bearer/apiKey credentials.

examples/petstore-ts/sdk/src/client.ts[111-116]
examples/petstore-ts/sdk/src/auth.ts[10-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README’s streaming example creates `new ApiClient({ baseUrl })` which drops the configured auth. In generated SDKs, omitting `auth` defaults to `anonymousAuth()`, so secured streaming endpoints won’t receive credentials.

## Issue Context
Earlier in the snippet, `createClient({... auth: bearerAuth(...) ...})` is shown. The streaming example should reuse the same options (at least `auth`) to avoid a surprising unauthenticated request.

## Fix Focus Areas
- README.md[315-331]

## Proposed fix
Refactor to share options:
```ts
const options = {
 baseUrl: "https://api.example.com",
 auth: bearerAuth(() => process.env.API_TOKEN!),
 maxConcurrent: 8,
 dedupe: true,
 idempotency: true,
 retry: { maxRetries: 3 },
};

const client = createClient(options);

const api = new ApiClient(options);
const res = await api.request("GET", "/events");
```
(Or at minimum: `new ApiClient({ baseUrl, auth: bearerAuth(...) })`.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Action pin docs mismatch 🐞 Bug ⚙ Maintainability

Description

README updates the GitHub Action pin to @v1, but docs-site/docs/intro.md still recommends
@v0.2.2, leaving conflicting guidance within this repo. Users following different docs pages will
end up on different action versions.

Code

README.md[1068]

+- uses: amafjarkasi/specforge-openapi-sdk-codegen@v1

Evidence

The docs-site intro page still contains the old @v0.2.2 pin, which now conflicts with the README’s
updated @v1 recommendation.

docs-site/docs/intro.md[909-923]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The README now recommends using `amafjarkasi/specforge-openapi-sdk-codegen@v1`, but the docs-site intro page still shows `@v0.2.2`, creating inconsistent instructions.

## Issue Context
This PR changed README’s pin; to keep the documentation set coherent, update the docs-site GitHub Action snippet (and any similar snippets elsewhere) to match the chosen recommendation.

## Fix Focus Areas
- docs-site/docs/intro.md[909-923]

## Proposed fix
Update the docs-site snippet to use `@v1` (or explain why it intentionally differs), and optionally mirror the README’s pinning guidance (major pin vs exact tag).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-code-review]

1. Tree-shaking claim incorrect 🐞 Bug ≡ Correctness

README now states that createClient() returns a "tree-shakeable" tag namespace, but the generated
TS SDK explicitly warns that createClient() imports all tag modules and is not the tree-shakeable
path. This can mislead users into shipping larger bundles than expected.

Agent Prompt

## Issue description
README claims `createClient()` is tree-shakeable, but generated SDK docs state the opposite (it eagerly imports all tags). This mismatch misguides users about bundle size behavior.

## Issue Context
The generated TS barrel (`src/index.ts`) documents tree-shaking behavior and explicitly recommends importing individual tag modules instead of using `createClient()` when bundle size matters.

## Fix Focus Areas
- README.md[334-335]

## Proposed fix
Change the note to something like:
- “`createClient()` returns a convenient tag namespace (`client.pets.listPets`), but it imports all tags. For tree-shaking, import individual tag modules directly.”

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Streaming client drops auth 🐞 Bug ≡ Correctness

The updated streaming example constructs a new ApiClient without passing auth, so streaming
requests will default to anonymousAuth() even though the example configures bearerAuth earlier.
This will fail (401/403) for authenticated streaming endpoints and is misleading as a copy/paste
snippet.

Agent Prompt

## Issue description
README’s streaming example creates `new ApiClient({ baseUrl })` which drops the configured auth. In generated SDKs, omitting `auth` defaults to `anonymousAuth()`, so secured streaming endpoints won’t receive credentials.

## Issue Context
Earlier in the snippet, `createClient({... auth: bearerAuth(...) ...})` is shown. The streaming example should reuse the same options (at least `auth`) to avoid a surprising unauthenticated request.

## Fix Focus Areas
- README.md[315-331]

## Proposed fix
Refactor to share options:
```ts
const options = {
  baseUrl: "https://api.example.com",
  auth: bearerAuth(() => process.env.API_TOKEN!),
  maxConcurrent: 8,
  dedupe: true,
  idempotency: true,
  retry: { maxRetries: 3 },
};

const client = createClient(options);

const api = new ApiClient(options);
const res = await api.request("GET", "/events");
```
(Or at minimum: `new ApiClient({ baseUrl, auth: bearerAuth(...) })`.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

3. Action pin docs mismatch 🐞 Bug ⚙ Maintainability

README updates the GitHub Action pin to @v1, but docs-site/docs/intro.md still recommends
@v0.2.2, leaving conflicting guidance within this repo. Users following different docs pages will
end up on different action versions.

Agent Prompt

## Issue description
The README now recommends using `amafjarkasi/specforge-openapi-sdk-codegen@v1`, but the docs-site intro page still shows `@v0.2.2`, creating inconsistent instructions.

## Issue Context
This PR changed README’s pin; to keep the documentation set coherent, update the docs-site GitHub Action snippet (and any similar snippets elsewhere) to match the chosen recommendation.

## Fix Focus Areas
- docs-site/docs/intro.md[909-923]

## Proposed fix
Update the docs-site snippet to use `@v1` (or explain why it intentionally differs), and optionally mirror the README’s pinning guidance (major pin vs exact tag).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools