@postman/sdk-config 0.0.0 → 0.0.1

package/README.md

@@ -1,9 +1,70 @@
 # @postman/sdk-config
 
-Namespace placeholder for `@postman/sdk-config`.
+Shared, runtime-validated configuration contracts for Postman's SDK generation pipeline.
 
-Real releases ship from CI via OIDC Trusted Publishing — see the linked
-repository for the release workflow. This `0.0.0` stub exists only to claim
-the name under the `@postman` scope and apply least-privilege team
-permissions. It is private (`--access restricted`); the first real release
-makes the package public if/when the team decides.
+This package is the source of truth for `SdkConfigIr`. It is intended for sdk-gen-core,
+sdk-gen-api, Postman and Fern CLIs, and translators that normalize producer-specific configuration
+before generation.
+
+## Install
+
+The package is configured as a restricted package in the `@postman` npm scope.
+
+```sh
+npm install @postman/sdk-config
+```
+
+## Use
+
+Prefer the versioned entry point at transport and persistence boundaries:
+
+```ts
+import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';
+
+const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);
+```
+
+The package also exposes `@postman/sdk-config` and `@postman/sdk-config/sdk-config-ir` as convenient
+current-version entry points. Persisted payloads must still include `schemaVersion`.
+
+Both ESM `import` and CommonJS `require` consumers are supported.
+
+## Project layout
+
+```text
+src/
+  sdk-config-ir/
+    v1/                 # Versioned schema, inferred types, and contract reference
+tests/
+  fixtures/
+    sdk-config-ir/v1/   # Canonical portable payloads
+  sdk-config-ir/v1/     # Contract behavior tests
+docs/
+  migration.md          # sdk-gen-core adoption sequence
+```
+
+## Develop
+
+Requires Node.js 24 or newer. If you use nvm, run `nvm use` from the repository root.
+
+```sh
+npm install
+npm run check
+npm pack --dry-run
+```
+
+`npm run check` verifies formatting, linting, TypeScript, tests, and the dual-format package build.
+
+## Versioning and publishing
+
+- npm access is `restricted`; do not set package.json `private: true`, because npm would refuse to
+  publish it.
+- Additive v1 fields require a package minor version and a consumer-first rollout because v1 uses
+  strict runtime objects: an older consumer rejects fields it does not know.
+- Breaking wire changes get a new schema directory and discriminator such as `sdk-config-ir/v2`.
+- Keep the previous version exported while consumers migrate.
+
+Release automation is intentionally not included in the initial scaffold. It will be added and
+validated separately once the repository and its `develop` → `main` release process are established.
+
+See the [SDK Config IR v1 reference](src/sdk-config-ir/v1/README.md) for the complete contract.