@ankhorage/paradox 0.0.0 → 0.0.2

package/.changeset/stable-usage-model.md

@@ -0,0 +1,5 @@
+---
+'@ankhorage/paradox': patch
+---
+
+Stabilize usage metadata, documentation model serialization, and deterministic output ordering.

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.0.1
+
+### Patch Changes
+
+- 17729fb: Add generated README usage and configuration sections from package metadata and `@config` doc tags.
+
 ## 0.0.0
 
 ### Initial Changes

package/README.md

@@ -2,23 +2,25 @@
 
 Deterministic documentation generator for TypeScript packages.
 
-## Package Exports
+## Usage
 
-### analyze
+```bash
+bunx @ankhorage/paradox
+```
 
-Runs the source analysis pipeline for a configured package.
+## Configuration
 
-### AnalysisComponent
+Create a `paradox.config.ts` file:
 
-Describes one React component and its extracted props.
+```ts
+import { defineParadoxConfig } from '@ankhorage/paradox';
 
-### AnalysisExport
+export default defineParadoxConfig({
+  // ...
+});
+```
 
-Describes one exported declaration discovered in a package.
-
-### AnalysisResult
-
-Complete analysis output used to build the documentation model.
+## Public API
 
 ### defineParadoxConfig
 
@@ -26,24 +28,4 @@ Defines a Paradox configuration object without changing its shape.
 
 ### ParadoxConfig
 
-Configuration for running Paradox against a TypeScript package.
-
-### buildModel
-
-Converts analysis output into a serializable documentation model.
-
-### DocumentationModel
-
-Serializable model consumed by renderers and writers.
-
-### render
-
-Renders the documentation model into README and artifact files.
-
-### RenderResult
-
-Rendered documentation files ready to be written to disk.
-
-### write
-
-Writes generated documentation artifacts to the configured output paths.
+Configuration for running Paradox.

package/knip.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/knip@latest/schema.json",
+  "entry": ["src/index.ts", "eslint.config.mjs", ".prettierrc.js", "paradox.config.ts"],
+  "project": ["src/**/*.ts", "tests/**/*.ts"],
+  "ignore": ["tests/fixtures/**"],
+  "ignoreBinaries": ["eslint", "prettier"],
+  "ignoreUnresolved": ["bun-types"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {

package/paradox/exports.json

@@ -1,24 +1,4 @@
 [
-  {
-    "name": "analyze",
-    "description": "Runs the source analysis pipeline for a configured package.",
-    "kind": "function"
-  },
-  {
-    "name": "AnalysisComponent",
-    "description": "Describes one React component and its extracted props.",
-    "kind": "type"
-  },
-  {
-    "name": "AnalysisExport",
-    "description": "Describes one exported declaration discovered in a package.",
-    "kind": "type"
-  },
-  {
-    "name": "AnalysisResult",
-    "description": "Complete analysis output used to build the documentation model.",
-    "kind": "type"
-  },
   {
     "name": "defineParadoxConfig",
     "description": "Defines a Paradox configuration object without changing its shape.",
@@ -26,32 +6,7 @@
   },
   {
     "name": "ParadoxConfig",
-    "description": "Configuration for running Paradox against a TypeScript package.",
+    "description": "Configuration for running Paradox.",
     "kind": "type"
-  },
-  {
-    "name": "buildModel",
-    "description": "Converts analysis output into a serializable documentation model.",
-    "kind": "function"
-  },
-  {
-    "name": "DocumentationModel",
-    "description": "Serializable model consumed by renderers and writers.",
-    "kind": "type"
-  },
-  {
-    "name": "render",
-    "description": "Renders the documentation model into README and artifact files.",
-    "kind": "function"
-  },
-  {
-    "name": "RenderResult",
-    "description": "Rendered documentation files ready to be written to disk.",
-    "kind": "type"
-  },
-  {
-    "name": "write",
-    "description": "Writes generated documentation artifacts to the configured output paths.",
-    "kind": "function"
   }
 ]

package/paradox/exports.md

@@ -1,28 +1,4 @@
-# Package Exports
-
-## analyze
-
-Kind: `function`
-
-Runs the source analysis pipeline for a configured package.
-
-## AnalysisComponent
-
-Kind: `type`
-
-Describes one React component and its extracted props.
-
-## AnalysisExport
-
-Kind: `type`
-
-Describes one exported declaration discovered in a package.
-
-## AnalysisResult
-
-Kind: `type`
-
-Complete analysis output used to build the documentation model.
+# Public API
 
 ## defineParadoxConfig
 
@@ -34,34 +10,4 @@ Defines a Paradox configuration object without changing its shape.
 
 Kind: `type`
 
-Configuration for running Paradox against a TypeScript package.
-
-## buildModel
-
-Kind: `function`
-
-Converts analysis output into a serializable documentation model.
-
-## DocumentationModel
-
-Kind: `type`
-
-Serializable model consumed by renderers and writers.
-
-## render
-
-Kind: `function`
-
-Renders the documentation model into README and artifact files.
-
-## RenderResult
-
-Kind: `type`
-
-Rendered documentation files ready to be written to disk.
-
-## write
-
-Kind: `function`
-
-Writes generated documentation artifacts to the configured output paths.
+Configuration for running Paradox.

package/paradox/paradox.json

@@ -1,27 +1,22 @@
 {
   "packageName": "@ankhorage/paradox",
+  "packageId": "@ankhorage/paradox",
   "description": "Deterministic documentation generator for TypeScript packages.",
+  "usage": {
+    "packageName": "@ankhorage/paradox",
+    "commands": [
+      {
+        "name": "paradox",
+        "command": "bunx @ankhorage/paradox"
+      }
+    ]
+  },
+  "config": {
+    "exportName": "ParadoxConfig",
+    "configFile": "paradox.config.ts",
+    "factoryName": "defineParadoxConfig"
+  },
   "exports": [
-    {
-      "name": "analyze",
-      "description": "Runs the source analysis pipeline for a configured package.",
-      "kind": "function"
-    },
-    {
-      "name": "AnalysisComponent",
-      "description": "Describes one React component and its extracted props.",
-      "kind": "type"
-    },
-    {
-      "name": "AnalysisExport",
-      "description": "Describes one exported declaration discovered in a package.",
-      "kind": "type"
-    },
-    {
-      "name": "AnalysisResult",
-      "description": "Complete analysis output used to build the documentation model.",
-      "kind": "type"
-    },
     {
       "name": "defineParadoxConfig",
       "description": "Defines a Paradox configuration object without changing its shape.",
@@ -29,33 +24,8 @@
     },
     {
       "name": "ParadoxConfig",
-      "description": "Configuration for running Paradox against a TypeScript package.",
+      "description": "Configuration for running Paradox.",
       "kind": "type"
-    },
-    {
-      "name": "buildModel",
-      "description": "Converts analysis output into a serializable documentation model.",
-      "kind": "function"
-    },
-    {
-      "name": "DocumentationModel",
-      "description": "Serializable model consumed by renderers and writers.",
-      "kind": "type"
-    },
-    {
-      "name": "render",
-      "description": "Renders the documentation model into README and artifact files.",
-      "kind": "function"
-    },
-    {
-      "name": "RenderResult",
-      "description": "Rendered documentation files ready to be written to disk.",
-      "kind": "type"
-    },
-    {
-      "name": "write",
-      "description": "Writes generated documentation artifacts to the configured output paths.",
-      "kind": "function"
     }
   ],
   "components": []

package/src/analyze/analyze.ts

@@ -6,6 +6,7 @@ import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
 import { createProject } from './project.js';
 import type { AnalysisResult } from './types.js';
+import { createUsageFromPackageJson, type PackageJsonModel } from './usage.js';
 
 /***
  * Runs the source analysis pipeline for a configured package.
@@ -14,11 +15,12 @@ export async function analyze(config: ParadoxConfig): Promise<AnalysisResult> {
   const root = config.package?.root ?? process.cwd();
 
   const pkg = await readPackageJson(root);
+  const usage = createUsageFromPackageJson(pkg);
 
   const project = createProject(root);
   const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
 
-  const exports = analyzeExports(project, {
+  const { config: configMetadata, exports } = analyzeExports(project, {
     root,
     entrypoints,
   });
@@ -26,21 +28,18 @@ export async function analyze(config: ParadoxConfig): Promise<AnalysisResult> {
 
   return {
     packageName: config.docs?.title ?? pkg.name,
+    packageId: pkg.name,
     description: config.docs?.description ?? pkg.description ?? null,
 
     exports,
     components,
+    usage,
+    config: configMetadata,
   };
 }
 
-async function readPackageJson(root: string): Promise<{
-  name: string;
-  description?: string;
-}> {
+async function readPackageJson(root: string): Promise<PackageJsonModel> {
   const raw = await readFile(join(root, 'package.json'), 'utf-8');
 
-  return JSON.parse(raw) as {
-    name: string;
-    description?: string;
-  };
+  return JSON.parse(raw) as PackageJsonModel;
 }

package/src/analyze/exports.ts

@@ -7,6 +7,13 @@ import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
 
+interface AnalyzeExportsResult {
+  exports: AnalysisExport[];
+  config: {
+    exportName: string;
+  } | null;
+}
+
 /***
  * Collects exported declarations from configured package entrypoints.
  */
@@ -16,8 +23,9 @@ export function analyzeExports(
     root: string;
     entrypoints: readonly string[];
   },
-): AnalysisExport[] {
+): AnalyzeExportsResult {
   const exports: AnalysisExport[] = [];
+  let config: AnalyzeExportsResult['config'] = null;
 
   for (const sourceFile of getEntryPointSourceFiles(project, options)) {
     const exported = sourceFile.getExportSymbols();
@@ -27,7 +35,15 @@ export function analyzeExports(
       const [decl] = resolved.getDeclarations();
 
       const rawComment = getParadoxComment(decl);
-      const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
+      const parsed = rawComment
+        ? parseParadoxComment(rawComment)
+        : { description: null, isConfig: false };
+
+      if (parsed.isConfig) {
+        config = {
+          exportName: resolved.getName(),
+        };
+      }
 
       exports.push({
         name: resolved.getName(),
@@ -38,7 +54,10 @@ export function analyzeExports(
     }
   }
 
-  return exports;
+  return {
+    exports,
+    config,
+  };
 }
 
 function getEntryPointSourceFiles(

package/src/analyze/types.ts

@@ -24,13 +24,30 @@ export interface AnalysisComponent {
   }[];
 }
 
+export interface AnalysisUsage {
+  packageName: string;
+  commands: AnalysisUsageCommand[];
+}
+
+export interface AnalysisUsageCommand {
+  name: string;
+  command: string;
+}
+
 /***
  * Complete analysis output used to build the documentation model.
  */
 export interface AnalysisResult {
   packageName: string;
+  packageId: string;
   description: string | null;
 
   exports: AnalysisExport[];
   components: AnalysisComponent[];
+
+  usage: AnalysisUsage | null;
+
+  config: {
+    exportName: string;
+  } | null;
 }

package/src/analyze/usage.ts

@@ -0,0 +1,53 @@
+import type { AnalysisUsage } from './types.js';
+
+export interface PackageJsonModel {
+  name: string;
+  description?: string;
+  bin?: string | Record<string, string>;
+}
+
+export function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null {
+  if (pkg.bin == null) return null;
+
+  if (typeof pkg.bin === 'string') {
+    return {
+      packageName: pkg.name,
+      commands: [
+        {
+          name: getPackageBaseName(pkg.name),
+          command: `bunx ${pkg.name}`,
+        },
+      ],
+    };
+  }
+
+  const entries = Object.keys(pkg.bin).sort((a, b) => a.localeCompare(b));
+
+  if (entries.length === 0) return null;
+
+  if (entries.length === 1) {
+    const [name] = entries;
+
+    return {
+      packageName: pkg.name,
+      commands: [
+        {
+          name,
+          command: `bunx ${pkg.name}`,
+        },
+      ],
+    };
+  }
+
+  return {
+    packageName: pkg.name,
+    commands: entries.map((name) => ({
+      name,
+      command: `bunx ${pkg.name} ${name}`,
+    })),
+  };
+}
+
+function getPackageBaseName(packageName: string): string {
+  return packageName.split('/').pop() ?? packageName;
+}

package/src/analyze/utils/parseParadoxComment.ts

@@ -1,23 +1,37 @@
 /***
  * Parsed representation of a Paradox doc comment.
  */
-export interface ParsedParadoxComment {
+interface ParsedParadoxComment {
   description: string | null;
+  isConfig: boolean;
 }
 
 /***
  * Parses a Paradox doc comment into structured metadata.
  */
 export function parseParadoxComment(rawComment: string): ParsedParadoxComment {
-  const body = rawComment
+  const lines = rawComment
     .replace(/^\/\*\*\*/, '')
     .replace(/\*\/$/, '')
     .split('\n')
-    .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd())
+    .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+
+  let isConfig = false;
+
+  const description = lines
+    .filter((line) => {
+      if (line.trimStart().startsWith('@config')) {
+        isConfig = true;
+        return false;
+      }
+
+      return true;
+    })
     .join('\n')
     .trim();
 
   return {
-    description: body.length > 0 ? body : null,
+    description: description.length > 0 ? description : null,
+    isConfig,
   };
 }

package/src/config/types.ts

@@ -1,5 +1,7 @@
 /***
- * Configuration for running Paradox against a TypeScript package.
+ * Configuration for running Paradox.
+ *
+ * @config
  */
 export interface ParadoxConfig {
   mode?: 'safe' | 'write';

package/src/index.ts

@@ -1,9 +1,2 @@
-export { analyze } from './analyze/analyze.js';
-export type { AnalysisComponent, AnalysisExport, AnalysisResult } from './analyze/types.js';
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
 export type { ParadoxConfig } from './config/types.js';
-export { buildModel } from './model/buildModel.js';
-export type { DocumentationModel } from './model/types.js';
-export { render } from './render/render.js';
-export type { RenderResult } from './render/types.js';
-export { write } from './write/write.js';

package/src/model/buildModel.ts

@@ -1,25 +1,112 @@
-import type { AnalysisResult } from '../analyze/types.js';
-import type { DocumentationModel } from './types.js';
+import type { ComponentModel, DocumentationModel, ExportKind, ExportModel } from './types.js';
+
+interface BuildModelInput {
+  packageName: string;
+  packageId: string;
+  description: string | null;
+  exports: {
+    name: string;
+    description: string | null;
+    kind: ExportKind;
+  }[];
+  components: {
+    name: string;
+    description: string | null;
+    props: {
+      name: string;
+      type: string;
+      required: boolean;
+      description: string | null;
+    }[];
+  }[];
+  usage: {
+    packageName: string;
+    commands: {
+      name: string;
+      command: string;
+    }[];
+  } | null;
+  config: {
+    exportName: string;
+  } | null;
+}
 
 /***
  * Converts analysis output into a serializable documentation model.
  */
-export function buildModel(analysis: AnalysisResult): DocumentationModel {
-  const exportsByName = new Map(
-    analysis.exports.map((item) => [
-      item.name,
-      {
-        name: item.name,
-        description: item.description,
-        kind: item.kind,
-      },
-    ]),
-  );
+export function buildModel(analysis: BuildModelInput): DocumentationModel {
+  const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item)]));
+  const exports = sortByName([...exportsByName.values()]);
 
   return {
     packageName: analysis.packageName,
+    packageId: analysis.packageId,
     description: analysis.description,
-    exports: [...exportsByName.values()],
-    components: analysis.components,
+    usage:
+      analysis.usage !== null
+        ? {
+            packageName: analysis.usage.packageName,
+            commands: sortByName(
+              analysis.usage.commands.map((command) => ({
+                name: command.name,
+                command: command.command,
+              })),
+            ),
+          }
+        : null,
+    config:
+      analysis.config !== null
+        ? {
+            exportName: analysis.config.exportName,
+            configFile: getDefaultConfigFileName(analysis.packageId),
+            factoryName: findConfigFactoryName(analysis.config.exportName, [
+              ...exportsByName.keys(),
+            ]),
+          }
+        : null,
+    exports,
+    components: sortByName(analysis.components.map(mapComponent)),
+  };
+}
+
+function mapExport(item: BuildModelInput['exports'][number]): ExportModel {
+  return {
+    name: item.name,
+    description: item.description,
+    kind: item.kind,
+  };
+}
+
+function mapComponent(component: BuildModelInput['components'][number]): ComponentModel {
+  return {
+    name: component.name,
+    description: component.description,
+    props: sortByName(
+      component.props.map((prop) => ({
+        name: prop.name,
+        type: prop.type,
+        required: prop.required,
+        description: prop.description,
+      })),
+    ),
   };
 }
+
+function findConfigFactoryName(configExportName: string, exportNames: string[]): string | null {
+  const prefix = configExportName.endsWith('Config')
+    ? configExportName.slice(0, -'Config'.length)
+    : configExportName;
+  const expectedFactoryName = `define${prefix}Config`;
+
+  return exportNames.includes(expectedFactoryName) ? expectedFactoryName : null;
+}
+
+function getDefaultConfigFileName(packageId: string): string {
+  const packageBaseName = packageId.split('/').pop() ?? packageId;
+
+  return `${packageBaseName}.config.ts`;
+}
+
+function sortByName<T extends { name: string }>(items: readonly T[]): T[] {
+  return [...items].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/model/types.ts

@@ -1,19 +1,49 @@
-import type { AnalysisComponent, AnalysisResult } from '../analyze/types.js';
-
 /***
  * Serializable model consumed by renderers and writers.
  */
 export interface DocumentationModel {
   packageName: string;
+  packageId: string;
   description: string | null;
-  exports: {
-    name: string;
-    description: string | null;
-    kind: string;
-  }[];
-  components: AnalysisComponent[];
+  usage: UsageModel | null;
+  config: ConfigModel | null;
+  exports: ExportModel[];
+  components: ComponentModel[];
 }
 
-export type SerializableAnalysisResult = Omit<AnalysisResult, 'exports'> & {
-  exports: DocumentationModel['exports'];
-};
+export interface UsageModel {
+  packageName: string;
+  commands: UsageCommandModel[];
+}
+
+export interface UsageCommandModel {
+  name: string;
+  command: string;
+}
+
+export interface ConfigModel {
+  exportName: string;
+  configFile: string;
+  factoryName: string | null;
+}
+
+export interface ExportModel {
+  name: string;
+  description: string | null;
+  kind: ExportKind;
+}
+
+export type ExportKind = 'function' | 'type' | 'unknown';
+
+export interface ComponentModel {
+  name: string;
+  description: string | null;
+  props: PropModel[];
+}
+
+export interface PropModel {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string | null;
+}

package/src/render/render.ts

@@ -21,8 +21,41 @@ function renderReadme(model: DocumentationModel): string {
     lines.push(model.description, '');
   }
 
+  if (model.usage !== null) {
+    lines.push('## Usage', '');
+    lines.push('```bash');
+    for (const command of model.usage.commands) {
+      lines.push(command.command);
+    }
+    lines.push('```', '');
+  }
+
+  if (model.config !== null) {
+    lines.push('## Configuration', '');
+    lines.push(`Create a \`${model.config.configFile}\` file:`, '');
+    lines.push('```ts');
+
+    if (model.config.factoryName !== null) {
+      lines.push(`import { ${model.config.factoryName} } from '${model.packageId}';`);
+      lines.push('');
+      lines.push(`export default ${model.config.factoryName}({`);
+      lines.push('  // ...');
+      lines.push('});');
+    } else {
+      lines.push(`import type { ${model.config.exportName} } from '${model.packageId}';`);
+      lines.push('');
+      lines.push('const config = {');
+      lines.push('  // ...');
+      lines.push(`} satisfies ${model.config.exportName};`);
+      lines.push('');
+      lines.push('export default config;');
+    }
+
+    lines.push('```', '');
+  }
+
   if (model.exports.length > 0) {
-    lines.push('## Package Exports', '');
+    lines.push('## Public API', '');
 
     for (const item of model.exports) {
       lines.push(`### ${item.name}`, '');
@@ -34,7 +67,7 @@ function renderReadme(model: DocumentationModel): string {
 }
 
 function renderExports(model: DocumentationModel): string {
-  const lines = ['# Package Exports', ''];
+  const lines = ['# Public API', ''];
 
   for (const item of model.exports) {
     lines.push(`## ${item.name}`, '');

package/tests/__snapshots__/basic.components.md

@@ -6,5 +6,5 @@ Renders the fixture button component.
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| label | `string` | yes | Visible button label. |
 | disabled | `boolean \| undefined` | no | Optional disabled state. |
+| label | `string` | yes | Visible button label. |

package/tests/__snapshots__/basic.exports.md

@@ -1,4 +1,4 @@
-# Package Exports
+# Public API
 
 ## Button
 
@@ -11,3 +11,9 @@ Renders the fixture button component.
 Kind: `type`
 
 Props accepted by the fixture button.
+
+## ToolConfig
+
+Kind: `type`
+
+Configuration for the fixture package.

package/tests/__snapshots__/basic.readme.md

@@ -2,7 +2,27 @@
 
 Generated fixture docs.
 
-## Package Exports
+## Usage
+
+```bash
+bunx @fixture/basic
+```
+
+## Configuration
+
+Create a `basic.config.ts` file:
+
+```ts
+import type { ToolConfig } from '@fixture/basic';
+
+const config = {
+  // ...
+} satisfies ToolConfig;
+
+export default config;
+```
+
+## Public API
 
 ### Button
 
@@ -11,3 +31,7 @@ Renders the fixture button component.
 ### ButtonProps
 
 Props accepted by the fixture button.
+
+### ToolConfig
+
+Configuration for the fixture package.

package/tests/__snapshots__/multi-bin.readme.md

@@ -0,0 +1,16 @@
+# Multi Bin Fixture
+
+Fixture docs for multiple binaries.
+
+## Usage
+
+```bash
+bunx fixture-multi-bin alpha
+bunx fixture-multi-bin beta
+```
+
+## Public API
+
+### example
+
+Example public function.

package/tests/analyze.test.ts

@@ -3,9 +3,13 @@ import { join } from 'node:path';
 
 import { describe, expect, test } from 'bun:test';
 
-import { analyze, buildModel, render } from '../src/index.js';
+import { analyze } from '../src/analyze/analyze.js';
+import { createUsageFromPackageJson } from '../src/analyze/usage.js';
+import { buildModel } from '../src/model/buildModel.js';
+import { render } from '../src/render/render.js';
 
 const fixtureRoot = join(import.meta.dir, 'fixtures/basic');
+const multiBinFixtureRoot = join(import.meta.dir, 'fixtures/multi-bin');
 const snapshotRoot = join(import.meta.dir, '__snapshots__');
 
 describe('analyze', () => {
@@ -21,8 +25,24 @@ describe('analyze', () => {
       },
     });
 
-    expect(analysis.exports.map((item) => item.name)).toEqual(['Button', 'ButtonProps']);
+    expect(analysis.exports.map((item) => item.name)).toEqual([
+      'Button',
+      'ToolConfig',
+      'ButtonProps',
+    ]);
     expect(analysis.exports.map((item) => item.name)).not.toContain('internalHelper');
+    expect(analysis.usage).toEqual({
+      packageName: '@fixture/basic',
+      commands: [
+        {
+          name: 'fixture-basic',
+          command: 'bunx @fixture/basic',
+        },
+      ],
+    });
+    expect(analysis.config).toEqual({
+      exportName: 'ToolConfig',
+    });
 
     expect(analysis.components).toEqual([
       {
@@ -51,6 +71,79 @@ describe('analyze', () => {
     await expectSnapshot('basic.exports.md', output.exportsMarkdown);
     await expectSnapshot('basic.components.md', output.components);
   });
+
+  test('renders multiple bin commands deterministically', async () => {
+    const analysis = await analyze({
+      docs: {
+        title: 'Multi Bin Fixture',
+        description: 'Fixture docs for multiple binaries.',
+      },
+      package: {
+        root: multiBinFixtureRoot,
+        entrypoints: ['src/index.ts'],
+      },
+    });
+
+    expect(analysis.usage).toEqual({
+      packageName: 'fixture-multi-bin',
+      commands: [
+        {
+          name: 'alpha',
+          command: 'bunx fixture-multi-bin alpha',
+        },
+        {
+          name: 'beta',
+          command: 'bunx fixture-multi-bin beta',
+        },
+      ],
+    });
+
+    const output = render(buildModel(analysis));
+
+    await expectSnapshot('multi-bin.readme.md', output.readme);
+  });
+
+  test('normalizes string bin usage', () => {
+    expect(
+      createUsageFromPackageJson({
+        name: 'fixture-string-bin',
+        bin: './src/cli.ts',
+      }),
+    ).toEqual({
+      packageName: 'fixture-string-bin',
+      commands: [
+        {
+          name: 'fixture-string-bin',
+          command: 'bunx fixture-string-bin',
+        },
+      ],
+    });
+  });
+
+  test('normalizes missing bin usage', () => {
+    expect(
+      createUsageFromPackageJson({
+        name: 'fixture-no-bin',
+      }),
+    ).toBeNull();
+  });
+
+  test('normalizes scoped string bin usage', () => {
+    expect(
+      createUsageFromPackageJson({
+        name: '@fixture/string-bin',
+        bin: './src/cli.ts',
+      }),
+    ).toEqual({
+      packageName: '@fixture/string-bin',
+      commands: [
+        {
+          name: 'string-bin',
+          command: 'bunx @fixture/string-bin',
+        },
+      ],
+    });
+  });
 });
 
 async function expectSnapshot(name: string, actual: string): Promise<void> {

package/tests/fixtures/basic/package.json

@@ -1,5 +1,8 @@
 {
   "name": "@fixture/basic",
   "description": "Fixture package for Paradox tests.",
-  "type": "module"
+  "type": "module",
+  "bin": {
+    "fixture-basic": "./src/index.ts"
+  }
 }

package/tests/fixtures/basic/src/config.ts

@@ -0,0 +1,8 @@
+/***
+ * Configuration for the fixture package.
+ *
+ * @config
+ */
+export interface ToolConfig {
+  enabled: boolean;
+}

package/tests/fixtures/basic/src/index.ts

@@ -1,2 +1,3 @@
 export { Button } from './ui.js';
+export type { ToolConfig } from './config.js';
 export type { ButtonProps } from './ui.js';

package/tests/fixtures/multi-bin/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "fixture-multi-bin",
+  "description": "Fixture package with multiple binaries.",
+  "type": "module",
+  "bin": {
+    "beta": "./src/beta.ts",
+    "alpha": "./src/alpha.ts"
+  }
+}

package/tests/fixtures/multi-bin/src/alpha.ts

@@ -0,0 +1 @@
+export function alpha(): void {}

package/tests/fixtures/multi-bin/src/beta.ts

@@ -0,0 +1 @@
+export function beta(): void {}

package/tests/fixtures/multi-bin/src/index.ts

@@ -0,0 +1,4 @@
+/***
+ * Example public function.
+ */
+export function example(): void {}

package/tests/fixtures/multi-bin/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}