openapi-agent-reference 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The project follows [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+## 2.0.0 - 2026-07-13
+
+### Added
+
+- `openapi-md` executable and `groups` / `generate` subcommands.
+- JSON group discovery with `groups --json`.
+- Standard input and standard output support through `-`.
+- Public CommonJS library entry point.
+- Cross-platform CLI integration tests and npm publishing safeguards.
+
+### Changed
+
+- The installed CLI command is now `openapi-md`.
+- The minimum supported Node.js version is now 22.
+
+## 1.0.2
+
+- Added exact primary-tag group filtering and group discovery.

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+## Development
+
+Use Node.js 22 or newer.
+
+```bash
+npm ci
+npm test
+```
+
+Run the CLI directly while developing:
+
+```bash
+node bin/openapi-md.js groups openapi.json
+node bin/openapi-md.js generate openapi.json --group "Access" --output -
+```
+
+## Pull requests
+
+- Add or update tests for behavior changes.
+- Keep the CLI backward compatible unless the change is intentionally released as a new major version.
+- Update `README.md` and `CHANGELOG.md` for user-visible changes.
+- Run `npm pack --dry-run` and inspect the publish file list before releasing.
+
+## Releases
+
+Use Semantic Versioning. Publishing is performed by the GitHub Actions release workflow through npm trusted publishing; do not add npm access tokens to the repository.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dikong1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,43 +1,161 @@
-# OpenAPI Agent Reference Generator
+# OpenAPI Agent Reference
 
-A zero-runtime-dependency Node.js CLI that turns an OpenAPI JSON document into a single navigable Markdown API reference. The output is designed for both developers and AI agents.
+Generate compact, navigable Markdown API references from OpenAPI JSON. The output is designed for developers and AI agents and includes authentication, parameters, request and response bodies, examples, and reusable schemas.
 
-It includes:
+## Requirements
 
-- endpoints grouped by their primary OpenAPI tag;
-- operation IDs, authentication requirements, deprecation status, and descriptions;
-- path, query, header, and cookie parameters with constraints;
-- request bodies and response bodies for every documented media type;
-- explicit and schema-generated JSON examples;
-- response headers and OpenAPI links;
-- OAuth, bearer, API-key, and other security scheme details;
-- a reusable schema catalog with required fields and `$ref` links;
-- OpenAPI 3.x support plus practical Swagger 2.0 compatibility.
+Node.js 22 or newer. The package has no runtime dependencies.
 
-## Requirements
+## Quick start
+
+Run the published package without installing it:
+
+```bash
+npx openapi-agent-reference@latest groups openapi.json
+npx openapi-agent-reference@latest generate openapi.json --group "Equipment Service" -o EQUIPMENT_SERVICE.md
+```
+
+Or install it in a project:
+
+```bash
+npm install --save-dev openapi-agent-reference
+```
+
+The short command is then available through `npx` and npm scripts:
+
+```bash
+npx openapi-md groups openapi.json
+npx openapi-md generate openapi.json -o API_REFERENCE.md
+```
+
+## CLI
+
+### Discover groups
+
+Groups are primary OpenAPI operation tags. List their exact, case-sensitive names before generating a focused reference:
+
+```bash
+openapi-md groups openapi.json
+```
+
+Example output:
+
+```text
+GROUP                     OPERATIONS
+------------------------  ----------
+Access                    9
+Equipment Service         49
+```
+
+For machine-readable output:
+
+```bash
+openapi-md groups openapi.json --json
+```
 
-Node.js 18 or newer. No package installation is required.
+```json
+[
+  { "name": "Access", "operations": 9 },
+  { "name": "Equipment Service", "operations": 49 }
+]
+```
 
-## Usage
+### Generate one group
 
 ```bash
-node src/openapi-to-markdown.js openapi.json -o API_REFERENCE.md
+openapi-md generate openapi.json --group "Access" --output ACCESS.md
 ```
 
-Or use the included npm script for the default paths:
+The result contains only the selected group's endpoints and the reusable schemas they reference, including transitive schema dependencies. A misspelled group produces a close-match suggestion and the complete list of valid groups.
+
+### Generate the complete reference
+
+```bash
+openapi-md generate openapi.json --output API_REFERENCE.md
+```
+
+### Pipelines and standard streams
+
+Use `-` for standard input or standard output:
 
 ```bash
-npm run generate
+curl https://example.com/openapi.json | openapi-md groups - --json
+openapi-md generate openapi.json --group Users --output -
 ```
 
-Options:
+Diagnostics are written to stderr, so Markdown and JSON output can be piped safely.
+
+### Options
 
 ```text
--o, --output <file>    Output file (default: API_REFERENCE.md)
---no-schema-catalog    Omit reusable schemas
---no-examples          Omit generated JSON examples
---include-extensions   Include x-* operation extensions
--h, --help             Show CLI help
+-o, --output <file|->     Output file, or - for stdout
+-g, --group <name>        Generate only the exact, case-sensitive group
+--json                    JSON output for the groups command
+--no-schema-catalog       Omit reusable schemas
+--no-examples             Omit generated JSON examples
+--include-extensions      Include x-* operation extensions
+-v, --version             Show the installed version
+-h, --help                Show CLI help
+```
+
+The original flag-based syntax remains available for backward compatibility:
+
+```bash
+openapi-md openapi.json --list-groups
+openapi-md openapi.json --group Access -o ACCESS.md
+```
+
+## Programmatic API
+
+The CommonJS entry point exposes the generator and OpenAPI inspection helpers:
+
+```js
+const fs = require('node:fs');
+const {
+  generateMarkdown,
+  groupList,
+} = require('openapi-agent-reference');
+
+const spec = JSON.parse(fs.readFileSync('openapi.json', 'utf8'));
+
+console.log(groupList(spec));
+
+const markdown = generateMarkdown(spec, {
+  group: 'Access',
+  examples: true,
+  schemaCatalog: true,
+});
 ```
 
-The generator never calls the API and does not resolve external `$ref` URLs. Local component references such as `#/components/schemas/User` are linked to the schema catalog.
+Public exports:
+
+- `generateMarkdown(spec, options)`
+- `groupList(spec)`
+- `collectOperations(spec)`
+- `formatGroupList(spec)`
+- `referencedSchemaNames(groups, spec)`
+- `sampleForSchema(schema, spec)`
+
+## Generated reference content
+
+- Endpoints grouped by their primary OpenAPI tag
+- Operation IDs, descriptions, authentication, and deprecation state
+- Path, query, header, and cookie parameters with constraints
+- Request and response bodies for every documented media type
+- Explicit and schema-generated JSON examples
+- Response headers and OpenAPI links
+- OAuth, bearer, API-key, and other security scheme details
+- Linked reusable schemas with required fields and recursive-reference protection
+- OpenAPI 3.x support and practical Swagger 2.0 compatibility
+
+Local `$ref` values are resolved and linked. External `$ref` URLs are preserved but are not downloaded.
+
+## Development and releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and release guidance. Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+Publishing uses npm trusted publishing from GitHub Actions. Before the first automated release, configure `npm-publish.yml` as the trusted publisher in the package settings on npmjs.com.
+
+## License
+
+MIT

package/bin/openapi-md.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/cli');
+
+main();

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "openapi-agent-reference",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Generate agent-friendly Markdown API reference documentation from OpenAPI JSON.",
   "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "openapi-to-md": "src/openapi-to-markdown.js"
+    "openapi-md": "bin/openapi-md.js"
   },
   "scripts": {
-    "generate": "node src/openapi-to-markdown.js openapi.json -o API_REFERENCE.md",
-    "test": "node --test"
+    "generate": "node bin/openapi-md.js generate openapi.json -o API_REFERENCE.md",
+    "groups": "node bin/openapi-md.js groups openapi.json",
+    "test": "node --test",
+    "prepublishOnly": "npm test"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "license": "MIT",
   "repository": {
@@ -23,7 +30,22 @@
     "url": "https://github.com/Dikong1/extractOpenApi/issues"
   },
   "files": [
+    "bin/",
     "src/",
-    "README.md"
-  ]
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "keywords": [
+    "openapi",
+    "swagger",
+    "markdown",
+    "api-documentation",
+    "ai-agent",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/cli.js

@@ -0,0 +1,167 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const packageJson = require('../package.json');
+const {
+  collectOperations,
+  formatGroupList,
+  generateMarkdown,
+  groupList,
+} = require('./openapi-to-markdown');
+
+function usage() {
+  return `Usage:
+  openapi-md groups [openapi.json|-] [--json]
+  openapi-md generate [openapi.json|-] [options]
+  openapi-md [openapi.json|-] [options]       Legacy syntax
+
+Commands:
+  groups                    List exact primary-tag group names and operation counts
+  generate                  Generate a full or single-group Markdown reference
+
+Options:
+  -o, --output <file|->     Output Markdown file, or - for stdout (default: API_REFERENCE.md)
+  -g, --group <name>        Generate only the exact, case-sensitive group
+  --json                    Emit machine-readable JSON from the groups command
+  --list-groups             Legacy alias for the groups command
+  --no-schema-catalog       Omit the reusable schema catalog
+  --no-examples             Omit generated JSON examples
+  --include-extensions      Include x-* operation extensions
+  -v, --version             Show the package version
+  -h, --help                Show this help
+
+Use - as the input path to read OpenAPI JSON from stdin.
+`;
+}
+
+function requiredValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('-')) throw new Error(`${option} requires a value`);
+  return value;
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  let command = 'generate';
+  if (args[0] === 'groups' || args[0] === 'generate') command = args.shift();
+
+  const options = {
+    command,
+    input: 'openapi.json',
+    output: 'API_REFERENCE.md',
+    schemaCatalog: true,
+    examples: true,
+    includeExtensions: false,
+    group: undefined,
+    json: false,
+  };
+  let inputSet = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') options.help = true;
+    else if (arg === '-v' || arg === '--version') options.version = true;
+    else if (arg === '--list-groups') options.command = 'groups';
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--no-schema-catalog') options.schemaCatalog = false;
+    else if (arg === '--no-examples') options.examples = false;
+    else if (arg === '--include-extensions') options.includeExtensions = true;
+    else if (arg === '-g' || arg === '--group') {
+      options.group = requiredValue(args, index, arg);
+      index += 1;
+    } else if (arg === '-o' || arg === '--output') {
+      const value = args[index + 1];
+      if (value === undefined) throw new Error(`${arg} requires a value`);
+      options.output = value;
+      index += 1;
+    } else if (arg === '-' && !inputSet) {
+      options.input = arg;
+      inputSet = true;
+    } else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+    else if (!inputSet) {
+      options.input = arg;
+      inputSet = true;
+    } else throw new Error(`Unexpected argument: ${arg}`);
+  }
+  if (options.command === 'groups' && options.group !== undefined) {
+    throw new Error('The groups command cannot be combined with --group');
+  }
+  if (options.command !== 'groups' && options.json) {
+    throw new Error('--json is only available with the groups command');
+  }
+  return options;
+}
+
+function readSpec(input) {
+  const label = input === '-' ? 'stdin' : path.resolve(input);
+  const source = fs.readFileSync(input === '-' ? 0 : label, 'utf8').replace(/^\uFEFF/, '');
+  let spec;
+  try { spec = JSON.parse(source); } catch (error) { throw new Error(`Invalid JSON in ${label}: ${error.message}`); }
+  if (!spec || typeof spec !== 'object' || (!spec.openapi && !spec.swagger) || !spec.paths || typeof spec.paths !== 'object') {
+    throw new Error('Input is not a valid OpenAPI document with a paths object');
+  }
+  return spec;
+}
+
+function writeFileSafely(outputPath, content) {
+  const absolutePath = path.resolve(outputPath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  const temporaryPath = path.join(
+    path.dirname(absolutePath),
+    `.${path.basename(absolutePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  fs.writeFileSync(temporaryPath, content, 'utf8');
+  try {
+    fs.renameSync(temporaryPath, absolutePath);
+  } catch (error) {
+    if (!['EEXIST', 'EPERM'].includes(error.code)) throw error;
+    fs.copyFileSync(temporaryPath, absolutePath);
+    fs.unlinkSync(temporaryPath);
+  } finally {
+    if (fs.existsSync(temporaryPath)) fs.unlinkSync(temporaryPath);
+  }
+  return absolutePath;
+}
+
+function run(argv = process.argv.slice(2), streams = process) {
+  let options;
+  try { options = parseArgs(argv); } catch (error) {
+    streams.stderr.write(`Error: ${error.message}\n\n${usage()}`);
+    return 1;
+  }
+  if (options.help) {
+    streams.stdout.write(usage());
+    return 0;
+  }
+  if (options.version) {
+    streams.stdout.write(`${packageJson.version}\n`);
+    return 0;
+  }
+  try {
+    const spec = readSpec(options.input);
+    if (options.command === 'groups') {
+      const output = options.json ? `${JSON.stringify(groupList(spec), null, 2)}\n` : formatGroupList(spec);
+      streams.stdout.write(output);
+      return 0;
+    }
+
+    const markdown = generateMarkdown(spec, options);
+    const groups = collectOperations(spec).filter(([name]) => options.group === undefined || name === options.group);
+    const operations = groups.reduce((count, [, items]) => count + items.length, 0);
+    if (options.output === '-') {
+      streams.stdout.write(markdown);
+      return 0;
+    }
+    const outputPath = writeFileSafely(options.output, markdown);
+    const scope = options.group === undefined ? '' : ` for group ${JSON.stringify(options.group)}`;
+    streams.stdout.write(`Generated ${outputPath}${scope} (${operations} operations, ${Buffer.byteLength(markdown)} bytes)\n`);
+    return 0;
+  } catch (error) {
+    streams.stderr.write(`Error: ${error.message}\n`);
+    return 1;
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  process.exitCode = run(argv);
+}
+
+module.exports = { main, parseArgs, readSpec, run, usage, writeFileSafely };

package/src/index.js

@@ -0,0 +1,17 @@
+const {
+  collectOperations,
+  formatGroupList,
+  generateMarkdown,
+  groupList,
+  referencedSchemaNames,
+  sampleForSchema,
+} = require('./openapi-to-markdown');
+
+module.exports = {
+  collectOperations,
+  formatGroupList,
+  generateMarkdown,
+  groupList,
+  referencedSchemaNames,
+  sampleForSchema,
+};

package/src/openapi-to-markdown.js

@@ -1,49 +1,5 @@
-#!/usr/bin/env node
-
-const fs = require('node:fs');
-const path = require('node:path');
-
 const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
 
-function usage() {
-  return `Usage: openapi-to-md [openapi.json] [options]
-
-Options:
-  -o, --output <file>       Output Markdown file (default: API_REFERENCE.md)
-  --no-schema-catalog       Omit the reusable schema catalog
-  --no-examples             Omit generated JSON examples
-  --include-extensions      Include x-* operation extensions
-  -h, --help                Show this help
-`;
-}
-
-function parseArgs(argv) {
-  const options = {
-    input: 'openapi.json',
-    output: 'API_REFERENCE.md',
-    schemaCatalog: true,
-    examples: true,
-    includeExtensions: false,
-  };
-  let inputSet = false;
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === '-h' || arg === '--help') options.help = true;
-    else if (arg === '--no-schema-catalog') options.schemaCatalog = false;
-    else if (arg === '--no-examples') options.examples = false;
-    else if (arg === '--include-extensions') options.includeExtensions = true;
-    else if (arg === '-o' || arg === '--output') {
-      if (!argv[index + 1]) throw new Error(`${arg} requires a file path`);
-      options.output = argv[++index];
-    } else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
-    else if (!inputSet) {
-      options.input = arg;
-      inputSet = true;
-    } else throw new Error(`Unexpected argument: ${arg}`);
-  }
-  return options;
-}
-
 function escapeTable(value) {
   return String(value ?? '—').replace(/\r?\n/g, '<br>').replace(/\|/g, '\\|');
 }
@@ -264,6 +220,83 @@ function collectOperations(spec) {
   });
 }
 
+function formatGroupList(spec) {
+  const groups = collectOperations(spec);
+  const width = Math.max('GROUP'.length, ...groups.map(([name]) => name.length));
+  return [
+    `${'GROUP'.padEnd(width)}  OPERATIONS`,
+    `${'-'.repeat(width)}  ----------`,
+    ...groups.map(([name, operations]) => `${name.padEnd(width)}  ${operations.length}`),
+    '',
+  ].join('\n');
+}
+
+function groupList(spec) {
+  return collectOperations(spec).map(([name, operations]) => ({
+    name,
+    operations: operations.length,
+  }));
+}
+
+function levenshteinDistance(left, right) {
+  const a = left.toLocaleLowerCase();
+  const b = right.toLocaleLowerCase();
+  const previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let row = 1; row <= a.length; row += 1) {
+    const current = [row];
+    for (let column = 1; column <= b.length; column += 1) {
+      current[column] = Math.min(
+        current[column - 1] + 1,
+        previous[column] + 1,
+        previous[column - 1] + (a[row - 1] === b[column - 1] ? 0 : 1),
+      );
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[b.length];
+}
+
+function closestGroup(name, groups) {
+  if (!groups.length) return undefined;
+  const candidates = groups
+    .map(([candidate]) => ({ candidate, distance: levenshteinDistance(name, candidate) }))
+    .sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate));
+  const best = candidates[0];
+  const threshold = Math.max(2, Math.floor(Math.max(name.length, best.candidate.length) / 3));
+  return best.distance <= threshold ? best.candidate : undefined;
+}
+
+function referencedSchemaNames(groups, spec) {
+  const names = new Set();
+  const visitedRefs = new Set();
+  const visitedObjects = new Set();
+
+  function visit(value) {
+    if (!value || typeof value !== 'object' || visitedObjects.has(value)) return;
+    visitedObjects.add(value);
+    if (typeof value.$ref === 'string' && value.$ref.startsWith('#/')) {
+      const schemaMatch = value.$ref.match(/^#\/(?:components\/schemas|definitions)\/(.+)$/);
+      if (schemaMatch) {
+        const name = decodeURIComponent(schemaMatch[1].replace(/~1/g, '/').replace(/~0/g, '~'));
+        names.add(name);
+      }
+      if (!visitedRefs.has(value.$ref)) {
+        visitedRefs.add(value.$ref);
+        visit(resolveLocalRef(spec, value.$ref));
+      }
+    }
+    for (const nested of Object.values(value)) visit(nested);
+  }
+
+  for (const [, operations] of groups) {
+    for (const { operation, pathItem } of operations) {
+      visit(operation);
+      visit(pathItem.parameters);
+    }
+  }
+  return names;
+}
+
 function renderParameters(parameters, spec) {
   if (!parameters.length) return '';
   const lines = ['#### Parameters', '', '| Name | In | Required | Type | Description / constraints |', '|---|---|:---:|---|---|'];
@@ -418,27 +451,40 @@ function renderSchema(name, schema, spec, options) {
   return lines.join('\n');
 }
 
-function renderSchemas(spec, options) {
+function renderSchemas(spec, options, includedNames) {
   const schemas = spec.components?.schemas || spec.definitions || {};
-  if (!options.schemaCatalog || !Object.keys(schemas).length) return '';
-  const lines = ['## Schema catalog', '', `${Object.keys(schemas).length} reusable schema(s).`, ''];
-  for (const [name, schema] of Object.entries(schemas).sort(([a], [b]) => a.localeCompare(b))) {
+  const entries = Object.entries(schemas)
+    .filter(([name]) => !includedNames || includedNames.has(name))
+    .sort(([a], [b]) => a.localeCompare(b));
+  if (!options.schemaCatalog || !entries.length) return '';
+  const lines = ['## Schema catalog', '', `${entries.length} reusable schema(s).`, ''];
+  for (const [name, schema] of entries) {
     lines.push(renderSchema(name, schema, spec, options));
   }
   return lines.join('\n');
 }
 
 function generateMarkdown(spec, options = {}) {
-  options = { schemaCatalog: true, examples: true, includeExtensions: false, ...options };
+  options = { schemaCatalog: true, examples: true, includeExtensions: false, group: undefined, ...options };
   if (!spec || typeof spec !== 'object') throw new Error('The OpenAPI document must be a JSON object');
   if (!spec.openapi && !spec.swagger) throw new Error('Missing required "openapi" or "swagger" version field');
   if (!spec.paths || typeof spec.paths !== 'object') throw new Error('Missing required "paths" object');
 
   const title = spec.info?.title || 'API Reference';
-  const groups = collectOperations(spec);
+  const allGroups = collectOperations(spec);
+  let groups = allGroups;
+  if (options.group !== undefined) {
+    groups = allGroups.filter(([name]) => name === options.group);
+    if (!groups.length) {
+      const available = allGroups.map(([name]) => name).join(', ') || '(none)';
+      const suggestion = closestGroup(options.group, allGroups);
+      const hint = suggestion ? ` Did you mean ${JSON.stringify(suggestion)}?` : '';
+      throw new Error(`Unknown group ${JSON.stringify(options.group)}.${hint} Available groups: ${available}`);
+    }
+  }
   const operationCount = groups.reduce((count, [, operations]) => count + operations.length, 0);
   const lines = [
-    `# ${title} API Reference`,
+    `# ${title}${options.group !== undefined ? ` — ${options.group}` : ''} API Reference`,
     '',
     '> Generated from the OpenAPI document. Optimized for human readers and AI agents: use operation IDs for tool names, honor required parameters, and validate request/response bodies against the linked schemas.',
     '',
@@ -477,40 +523,18 @@ function generateMarkdown(spec, options = {}) {
     for (const item of operations) lines.push(renderOperation(item, spec, options));
   }
 
-  const schemas = renderSchemas(spec, options);
+  const includedSchemas = options.group !== undefined ? referencedSchemaNames(groups, spec) : undefined;
+  const schemas = renderSchemas(spec, options, includedSchemas);
   if (schemas) lines.push(schemas);
   lines.push('---', '', '_Generated by openapi-agent-reference. Do not edit manually; regenerate after the OpenAPI document changes._', '');
   return lines.join('\n').replace(/\n{4,}/g, '\n\n\n');
 }
 
-function main(argv = process.argv.slice(2)) {
-  let options;
-  try { options = parseArgs(argv); } catch (error) {
-    console.error(`Error: ${error.message}\n\n${usage()}`);
-    process.exitCode = 1;
-    return;
-  }
-  if (options.help) {
-    process.stdout.write(usage());
-    return;
-  }
-  try {
-    const inputPath = path.resolve(options.input);
-    const outputPath = path.resolve(options.output);
-    const source = fs.readFileSync(inputPath, 'utf8').replace(/^\uFEFF/, '');
-    let spec;
-    try { spec = JSON.parse(source); } catch (error) { throw new Error(`Invalid JSON in ${inputPath}: ${error.message}`); }
-    const markdown = generateMarkdown(spec, options);
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-    fs.writeFileSync(outputPath, markdown, 'utf8');
-    const operations = collectOperations(spec).reduce((count, [, items]) => count + items.length, 0);
-    console.log(`Generated ${outputPath} (${operations} operations, ${Buffer.byteLength(markdown)} bytes)`);
-  } catch (error) {
-    console.error(`Error: ${error.message}`);
-    process.exitCode = 1;
-  }
-}
-
-if (require.main === module) main();
-
-module.exports = { generateMarkdown, parseArgs, sampleForSchema, collectOperations };
+module.exports = {
+  collectOperations,
+  formatGroupList,
+  generateMarkdown,
+  groupList,
+  referencedSchemaNames,
+  sampleForSchema,
+};