@async/api-contract 0.1.0 → 0.1.1

package/API_SURFACE.md

@@ -0,0 +1,184 @@
+# @async/api-contract API Surface Ledger
+
+This file is the generated review ledger for semantic API contract features. It is current-state contract documentation, not a changelog or tutorial.
+
+## Async API Contract CLI
+
+Contract: `@async/api-contract.cli`
+
+### Analysis
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `cli.diff` | Package contract diff command | public | stable | active |  | [docs](https://github.com/async/api-contract#cli) |
+| `cli.impact` | Consumer impact report command | public | stable | active |  | [docs](https://github.com/async/api-contract#cli) |
+| `cli.usage.scan` | Line-oriented dependency usage scan command | beta | preview | active |  | [docs](https://github.com/async/api-contract#cli) |
+
+### Ledger
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `cli.ledger` | API surface ledger generation and drift check command | public | stable | active |  | [docs](https://github.com/async/api-contract#cli) |
+
+### Manifest
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `cli.check` | Manifest validation command | public | stable | active |  | [docs](https://github.com/async/api-contract#cli) |
+
+## Async API Contract Package Exports
+
+Contract: `@async/api-contract.package-exports`
+
+### Bin
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `bin.api-contract` | api-contract executable | public | stable | active |  | [docs](https://github.com/async/api-contract#cli) |
+
+### Exports
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `export.root` | Runtime API root export | public | stable | active |  | [docs](https://github.com/async/api-contract#quick-start) |
+| `export.types` | Type-only contract helper export | public | stable | active |  | [docs](https://github.com/async/api-contract#type-only-contracts) |
+
+## Async API Contract Runtime API
+
+Contract: `@async/api-contract.runtime`
+
+### Catalog
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.catalog.defineFeatureCatalog` | Feature catalog declaration helper | public | stable | active |  |  |
+
+### Compare
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.compare.compareSurface` | Required-versus-supported surface comparison | public | stable | active |  |  |
+
+### Derive
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.derive.deriveSurface` | Runtime value-to-surface derivation | public | stable | active |  |  |
+
+### Diff
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.diff.diffPackageContracts` | Package manifest diff calculation | public | stable | active |  |  |
+
+### Hash
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.hash.surfaceHash` | Stable surface hash calculation | public | stable | active |  |  |
+
+### Impact
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.impact.createImpactReport` | Consumer impact report calculation | public | stable | active |  |  |
+
+### Ledger
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.ledger.renderApiSurfaceMarkdown` | API surface markdown ledger renderer | public | stable | active |  |  |
+
+### Manifest
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.manifest.parsePackageContractManifest` | Package contract manifest parser and validator | public | stable | active |  |  |
+
+### Surface
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.surface.createSurface` | Normalized API surface creation | public | stable | active |  |  |
+
+### Usage
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.usage.scanUsageTarget` | Line-oriented source usage scanner | beta | preview | active |  |  |
+
+## Async API Contract Type Exports
+
+Contract: `@async/api-contract.type-exports`
+
+### Model
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `type.PackageContractManifest` | Package contract manifest type | public | stable | active |  |  |
+| `type.Surface` | Normalized API surface type | public | stable | active |  |  |
+
+### Type Contracts
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `type.AssertCompatible` | Compile-time compatibility assertion | public | stable | active |  | [docs](https://github.com/async/api-contract#type-only-contracts) |
+| `type.ContractRef` | Phantom contract reference type | public | stable | active |  | [docs](https://github.com/async/api-contract#type-only-contracts) |
+| `type.Expect` | Compile-time expectation helper | public | stable | active |  | [docs](https://github.com/async/api-contract#type-only-contracts) |
+| `type.RequiresContract` | Required contract phantom type | public | stable | active |  | [docs](https://github.com/async/api-contract#type-only-contracts) |
+| `type.SupportsContract` | Supported contract phantom type | public | stable | active |  | [docs](https://github.com/async/api-contract#type-only-contracts) |
+
+## Async API Contract Package Metadata
+
+Contract: `@async/api-contract.package-metadata`
+
+### Engines
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `metadata.engines.node` | Node.js engine floor | public | stable | active |  |  |
+
+### Files
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `metadata.files.ledger` | API surface ledger is included in package files | public | stable | active |  |  |
+| `metadata.files.manifest` | API contract manifest is included in package files | public | stable | active |  |  |
+
+### Metadata
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `metadata.license.mit` | MIT license declaration | public | stable | active |  |  |
+| `metadata.repository.github` | GitHub repository metadata | public | stable | active |  |  |
+| `metadata.sideEffects.false` | Side-effect-free package declaration | public | stable | active |  |  |
+
+### Package Manager
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `metadata.packageManager.pnpm` | pnpm package manager declaration | public | stable | active |  |  |
+
+### Publish
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `metadata.publish.public` | Public npm publish access | public | stable | active |  |  |
+
+## Supported Surfaces
+
+| Contract | Hash | Features |
+| --- | --- | --- |
+| `@async/api-contract.cli` | `sha256:f3a9be69ec7b7f71c660c3e3395b5fe6619804248c16ad33fdba63ccc2d67a38` | `cli.check`, `cli.diff`, `cli.impact`, `cli.ledger`, `cli.usage.scan` |
+| `@async/api-contract.package-exports` | `sha256:5ba4fde2647d791f7e2b21e0a9809b820a80a5329ea43b036e856fd2d65eb9b3` | `bin.api-contract`, `export.root`, `export.types` |
+| `@async/api-contract.package-metadata` | `sha256:d7f3950ee79a616b25eb90d0e9947dac55bd14688b4beffa5420154009448927` | `metadata.engines.node`, `metadata.files.ledger`, `metadata.files.manifest`, `metadata.license.mit`, `metadata.packageManager.pnpm`, `metadata.publish.public`, `metadata.repository.github`, `metadata.sideEffects.false` |
+| `@async/api-contract.runtime` | `sha256:f4d7605badb38a4ed10ec8c6c73aa6d41b653679700f95b25e2e77e5a8bdcf96` | `runtime.catalog.defineFeatureCatalog`, `runtime.compare.compareSurface`, `runtime.derive.deriveSurface`, `runtime.diff.diffPackageContracts`, `runtime.hash.surfaceHash`, `runtime.impact.createImpactReport`, `runtime.ledger.renderApiSurfaceMarkdown`, `runtime.manifest.parsePackageContractManifest`, `runtime.surface.createSurface`, `runtime.usage.scanUsageTarget` |
+| `@async/api-contract.type-exports` | `sha256:b4804f2bb2ac9ac2d159ae81e3150a25980dfbd5badf99e2f65d3ed1643563a8` | `type.AssertCompatible`, `type.ContractRef`, `type.Expect`, `type.PackageContractManifest`, `type.RequiresContract`, `type.SupportsContract`, `type.Surface` |
+
+## Required Surfaces
+
+| Contract | Hash | Features |
+| --- | --- | --- |
+| `@async/api-contract.cli` | `sha256:109f7d81379d251bd8df213020a09e5cb60ff5a0725701b944d95d5de35ba4bf` | `cli.check`, `cli.ledger` |
+| `@async/pipeline.cli` | `sha256:d98fbabdc807d0a093266381164ba0442c8fe65c172b9fc7009280f91b236e8e` | `cli.github.check`, `cli.github.generate`, `cli.publish.github`, `cli.publish.npm`, `cli.release.doctor`, `cli.run`, `cli.run-task`, `cli.sync.check`, `cli.sync.generate` |
+| `@async/pipeline.declaration` | `sha256:e0bea5c3eafe5addbd08abbb37b9e9df010995567fc878aba996a41fc1cfd625` | `config.definePipeline`, `config.env`, `config.github.pages`, `config.job`, `config.sync.github`, `config.sync.tasks`, `config.task`, `config.trigger.github`, `config.trigger.manual`, `step.shell` |

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1
+
+- Align package scripts, generated GitHub Actions, release/preview lifecycle, GitHub Pages, and API surface ledger generation with `@async/pipeline`.
+- Add pnpm-first docs and release guidance for the shared Async repo workflow.
+
 ## 0.1.0
 
 - Initial development version.

package/README.md

@@ -21,6 +21,10 @@ Package versions, release tags, docs text, and metadata do not decide compatibil
 
 ## Quick start
 
+```sh
+pnpm add @async/api-contract
+```
+
 ```ts
 import {
   compareSurface,
@@ -145,6 +149,28 @@ api-contract usage scan --target src --package-name @async/consumer --dependency
 
 `usage scan` is a line-oriented source preflight. It records dependency and feature-string evidence, but it is not a full parser or proof of semantic usage.
 
+## Maintainer workflow
+
+The repository's package scripts and GitHub Actions are generated from `pipeline.ts` through `@async/pipeline`.
+
+```sh
+pnpm run pipeline:verify
+pnpm run pipeline:api-surface
+pnpm run pipeline:api-surface:generate
+pnpm run pipeline:github:check
+pnpm run pipeline:sync:check
+pnpm run release:check
+```
+
+Release and preview lifecycle commands are also synced from `pipeline.ts`:
+
+```sh
+pnpm run pipeline:preview
+pnpm run pipeline:snapshot
+pnpm run pipeline:publish
+pnpm run pipeline:release:doctor
+```
+
 ## Relationship to @async/claims
 
 `@async/claims` can wrap surfaces with issuer, evidence, trust, policy, and signatures. It should not redefine feature ids, hashes, derivation, or compatibility rules.

package/api-contract.json

@@ -0,0 +1,424 @@
+{
+  "format": "api-contract.package.v1",
+  "packageName": "@async/api-contract",
+  "catalogs": [
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/api-contract.cli",
+      "title": "Async API Contract CLI",
+      "features": [
+        {
+          "id": "cli.check",
+          "title": "Manifest validation command",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "manifest",
+          "docsUrl": "https://github.com/async/api-contract#cli"
+        },
+        {
+          "id": "cli.diff",
+          "title": "Package contract diff command",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "analysis",
+          "docsUrl": "https://github.com/async/api-contract#cli"
+        },
+        {
+          "id": "cli.impact",
+          "title": "Consumer impact report command",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "analysis",
+          "docsUrl": "https://github.com/async/api-contract#cli"
+        },
+        {
+          "id": "cli.ledger",
+          "title": "API surface ledger generation and drift check command",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "ledger",
+          "docsUrl": "https://github.com/async/api-contract#cli"
+        },
+        {
+          "id": "cli.usage.scan",
+          "title": "Line-oriented dependency usage scan command",
+          "releaseTag": "beta",
+          "stability": "preview",
+          "lifecycle": "active",
+          "group": "analysis",
+          "docsUrl": "https://github.com/async/api-contract#cli"
+        }
+      ]
+    },
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/api-contract.package-exports",
+      "title": "Async API Contract Package Exports",
+      "features": [
+        {
+          "id": "bin.api-contract",
+          "title": "api-contract executable",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "bin",
+          "docsUrl": "https://github.com/async/api-contract#cli"
+        },
+        {
+          "id": "export.root",
+          "title": "Runtime API root export",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "exports",
+          "docsUrl": "https://github.com/async/api-contract#quick-start"
+        },
+        {
+          "id": "export.types",
+          "title": "Type-only contract helper export",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "exports",
+          "docsUrl": "https://github.com/async/api-contract#type-only-contracts"
+        }
+      ]
+    },
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/api-contract.runtime",
+      "title": "Async API Contract Runtime API",
+      "features": [
+        {
+          "id": "runtime.catalog.defineFeatureCatalog",
+          "title": "Feature catalog declaration helper",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "catalog"
+        },
+        {
+          "id": "runtime.compare.compareSurface",
+          "title": "Required-versus-supported surface comparison",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "compare"
+        },
+        {
+          "id": "runtime.derive.deriveSurface",
+          "title": "Runtime value-to-surface derivation",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "derive"
+        },
+        {
+          "id": "runtime.diff.diffPackageContracts",
+          "title": "Package manifest diff calculation",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "diff"
+        },
+        {
+          "id": "runtime.hash.surfaceHash",
+          "title": "Stable surface hash calculation",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "hash"
+        },
+        {
+          "id": "runtime.impact.createImpactReport",
+          "title": "Consumer impact report calculation",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "impact"
+        },
+        {
+          "id": "runtime.ledger.renderApiSurfaceMarkdown",
+          "title": "API surface markdown ledger renderer",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "ledger"
+        },
+        {
+          "id": "runtime.manifest.parsePackageContractManifest",
+          "title": "Package contract manifest parser and validator",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "manifest"
+        },
+        {
+          "id": "runtime.surface.createSurface",
+          "title": "Normalized API surface creation",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "surface"
+        },
+        {
+          "id": "runtime.usage.scanUsageTarget",
+          "title": "Line-oriented source usage scanner",
+          "releaseTag": "beta",
+          "stability": "preview",
+          "lifecycle": "active",
+          "group": "usage"
+        }
+      ]
+    },
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/api-contract.type-exports",
+      "title": "Async API Contract Type Exports",
+      "features": [
+        {
+          "id": "type.AssertCompatible",
+          "title": "Compile-time compatibility assertion",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "type-contracts",
+          "docsUrl": "https://github.com/async/api-contract#type-only-contracts"
+        },
+        {
+          "id": "type.ContractRef",
+          "title": "Phantom contract reference type",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "type-contracts",
+          "docsUrl": "https://github.com/async/api-contract#type-only-contracts"
+        },
+        {
+          "id": "type.Expect",
+          "title": "Compile-time expectation helper",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "type-contracts",
+          "docsUrl": "https://github.com/async/api-contract#type-only-contracts"
+        },
+        {
+          "id": "type.PackageContractManifest",
+          "title": "Package contract manifest type",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "model"
+        },
+        {
+          "id": "type.RequiresContract",
+          "title": "Required contract phantom type",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "type-contracts",
+          "docsUrl": "https://github.com/async/api-contract#type-only-contracts"
+        },
+        {
+          "id": "type.Surface",
+          "title": "Normalized API surface type",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "model"
+        },
+        {
+          "id": "type.SupportsContract",
+          "title": "Supported contract phantom type",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "type-contracts",
+          "docsUrl": "https://github.com/async/api-contract#type-only-contracts"
+        }
+      ]
+    },
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/api-contract.package-metadata",
+      "title": "Async API Contract Package Metadata",
+      "features": [
+        {
+          "id": "metadata.engines.node",
+          "title": "Node.js engine floor",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "engines"
+        },
+        {
+          "id": "metadata.files.ledger",
+          "title": "API surface ledger is included in package files",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "files"
+        },
+        {
+          "id": "metadata.files.manifest",
+          "title": "API contract manifest is included in package files",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "files"
+        },
+        {
+          "id": "metadata.license.mit",
+          "title": "MIT license declaration",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "metadata"
+        },
+        {
+          "id": "metadata.packageManager.pnpm",
+          "title": "pnpm package manager declaration",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "package-manager"
+        },
+        {
+          "id": "metadata.publish.public",
+          "title": "Public npm publish access",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "publish"
+        },
+        {
+          "id": "metadata.repository.github",
+          "title": "GitHub repository metadata",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "metadata"
+        },
+        {
+          "id": "metadata.sideEffects.false",
+          "title": "Side-effect-free package declaration",
+          "releaseTag": "public",
+          "stability": "stable",
+          "lifecycle": "active",
+          "group": "metadata"
+        }
+      ]
+    }
+  ],
+  "supported": [
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/api-contract.cli",
+      "features": [
+        "cli.check",
+        "cli.diff",
+        "cli.impact",
+        "cli.ledger",
+        "cli.usage.scan"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/api-contract.package-exports",
+      "features": [
+        "bin.api-contract",
+        "export.root",
+        "export.types"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/api-contract.package-metadata",
+      "features": [
+        "metadata.engines.node",
+        "metadata.files.ledger",
+        "metadata.files.manifest",
+        "metadata.license.mit",
+        "metadata.packageManager.pnpm",
+        "metadata.publish.public",
+        "metadata.repository.github",
+        "metadata.sideEffects.false"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/api-contract.runtime",
+      "features": [
+        "runtime.catalog.defineFeatureCatalog",
+        "runtime.compare.compareSurface",
+        "runtime.derive.deriveSurface",
+        "runtime.diff.diffPackageContracts",
+        "runtime.hash.surfaceHash",
+        "runtime.impact.createImpactReport",
+        "runtime.ledger.renderApiSurfaceMarkdown",
+        "runtime.manifest.parsePackageContractManifest",
+        "runtime.surface.createSurface",
+        "runtime.usage.scanUsageTarget"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/api-contract.type-exports",
+      "features": [
+        "type.AssertCompatible",
+        "type.ContractRef",
+        "type.Expect",
+        "type.PackageContractManifest",
+        "type.RequiresContract",
+        "type.Surface",
+        "type.SupportsContract"
+      ]
+    }
+  ],
+  "required": [
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/api-contract.cli",
+      "features": [
+        "cli.check",
+        "cli.ledger"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/pipeline.cli",
+      "features": [
+        "cli.github.check",
+        "cli.github.generate",
+        "cli.publish.github",
+        "cli.publish.npm",
+        "cli.release.doctor",
+        "cli.run",
+        "cli.run-task",
+        "cli.sync.check",
+        "cli.sync.generate"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/pipeline.declaration",
+      "features": [
+        "config.definePipeline",
+        "config.env",
+        "config.github.pages",
+        "config.job",
+        "config.sync.github",
+        "config.sync.tasks",
+        "config.task",
+        "config.trigger.github",
+        "config.trigger.manual",
+        "step.shell"
+      ]
+    }
+  ]
+}

package/docs/README.md

@@ -0,0 +1,26 @@
+# @async/api-contract
+
+`@async/api-contract` publishes semantic API surfaces, review ledgers, and impact checks for Async packages.
+
+## Maintainer tasks
+
+```sh
+pnpm run pipeline:verify
+pnpm run pipeline:api-surface
+pnpm run pipeline:api-surface:generate
+pnpm run pipeline:github:check
+pnpm run pipeline:sync:check
+pnpm run release:check
+```
+
+## Consumer install
+
+```sh
+pnpm add @async/api-contract
+```
+
+## Package contract
+
+- [API_SURFACE.md](https://github.com/async/api-contract/blob/main/API_SURFACE.md) is the generated review ledger.
+- [api-contract.json](https://github.com/async/api-contract/blob/main/api-contract.json) is the checked manifest that produces the ledger.
+- [README.md](https://github.com/async/api-contract/blob/main/README.md) has the public API and CLI examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/api-contract",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Semantic API contract surfaces, ledgers, and impact checks for Async packages.",
   "license": "MIT",
   "type": "module",
@@ -29,20 +29,36 @@
     "async-pipeline": "async-pipeline",
     "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
     "pack:check": "npm --cache .async/npm-cache pack --dry-run",
+    "pipeline:api-surface": "async-pipeline run-task api-surface",
+    "pipeline:api-surface:generate": "async-pipeline run-task api-surface-generate",
     "pipeline:github:check": "async-pipeline github check",
     "pipeline:github:generate": "async-pipeline github generate",
+    "pipeline:pages": "async-pipeline run pages",
+    "pipeline:preview": "async-pipeline run preview",
     "pipeline:publish": "async-pipeline run publish",
+    "pipeline:publish:github:main": "async-pipeline publish github main --package .",
+    "pipeline:publish:github:pr": "async-pipeline publish github pr --package .",
+    "pipeline:publish:github:release": "async-pipeline publish github release --package .",
+    "pipeline:publish:npm": "async-pipeline publish npm --package .",
+    "pipeline:release-doctor": "async-pipeline run release-doctor",
+    "pipeline:release:doctor": "async-pipeline release doctor --package .",
+    "pipeline:release:ensure": "async-pipeline release ensure --package .",
+    "pipeline:snapshot": "async-pipeline run snapshot",
     "pipeline:sync:check": "async-pipeline sync check",
+    "pipeline:sync:generate": "async-pipeline sync generate",
     "pipeline:verify": "async-pipeline run verify",
-    "release:check": "pnpm pipeline:verify",
-    "release:publish": "node scripts/publish-npm.mjs",
-    "test": "pnpm build && pnpm typecheck:contracts && node --test test/*.test.js",
+    "pipeline:verify:force": "async-pipeline run verify --force",
+    "release:check": "pnpm run pipeline:verify:force",
+    "test": "pnpm run build && pnpm run typecheck:contracts && node --test test/*.test.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "typecheck:contracts": "tsc --ignoreConfig --noEmit --module NodeNext --moduleResolution NodeNext --target ES2024 --strict test/types.test-d.ts"
   },
   "files": [
     "dist",
+    "docs",
     "examples",
+    "api-contract.json",
+    "API_SURFACE.md",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -51,7 +67,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@async/pipeline": "0.2.4",
+    "@async/pipeline": "0.4.3",
     "@types/node": "24.12.4",
     "typescript": "6.0.3"
   }