@oddessentials/odd-docs 2.0.4 → 2.1.0

package/README.md

@@ -1,5 +1,11 @@
 # odd-docs
 
+[![npm version](https://img.shields.io/npm/v/@oddessentials/odd-docs.svg)](https://www.npmjs.com/package/@oddessentials/odd-docs)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
+[![License: OEL](https://img.shields.io/badge/license-OEL-blue)](./LICENSE)
+
+> **License Notice:** This project is source-available under the [Odd Essentials License (OEL)](./LICENSE). Commercial use requires a separate license. See [LICENSE](./LICENSE) for full terms.
+
 `odd-docs` is a documentation generation utility within the **oddessentials-mcp** ecosystem. It produces deterministic, structured documentation for MCP-compatible tools, servers, or repositories by inspecting manifests, schemas, and related metadata.
 
 It can be used in two distinct execution modes:
@@ -11,6 +17,31 @@ Although both modes generate documentation automatically, they differ fundamenta
 
 ---
 
+## Requirements
+
+- **Node.js ≥22.0.0** (see [.nvmrc](./.nvmrc))
+- npm or npx
+
+---
+
+## Quick Start
+
+```bash
+# Show version
+npx @oddessentials/odd-docs --version
+
+# Generate documentation for the current directory
+npx @oddessentials/odd-docs generate .
+
+# Validate without generating
+npx @oddessentials/odd-docs validate .
+
+# Start a local preview server
+npx @oddessentials/odd-docs serve .
+```
+
+---
+
 ## What odd-docs does
 
 At a high level, `odd-docs`:
@@ -41,7 +72,16 @@ npx @oddessentials/odd-docs --help
 
 ---
 
-## Manual CLI usage
+## Global Options
+
+```bash
+odd-docs --version, -V   # Show version number
+odd-docs --help          # Show help for any command
+```
+
+---
+
+## CLI Commands
 
 ### Command structure
 
@@ -57,73 +97,106 @@ odd-docs <command> <path> [options]
 
 ---
 
-### Generating documentation
+### generate
+
+Generate documentation for an MCP repository.
 
 ```bash
-odd-docs generate <repo-path>
+odd-docs generate <repo-path> [options]
 ```
 
-By default, this:
+**Options:**
 
-- Reads documentation inputs from `<repo-path>`
-- Writes generated output to a documentation directory within the repository
+| Option                  | Default          | Description                            |
+| ----------------------- | ---------------- | -------------------------------------- |
+| `-f, --format <format>` | `md`             | Output format: `md`, `html`, or `both` |
+| `-o, --output <dir>`    | `docs/generated` | Output directory for generated files   |
+| `--introspect <url>`    | —                | MCP server URL for live introspection  |
 
-Common options include:
-
-```bash
---format md|html|both
---output <directory>
-```
-
-Example:
+**Example:**
 
 ```bash
 odd-docs generate . --format both --output docs/generated
 ```
 
-Outputs may include:
+**Outputs:**
 
 - One or more `.md` and/or `.html` files
 - A machine-readable intermediate representation (IR) JSON file
 
+**Exit codes:**
+
+- `0` — Success
+- `1` — Error (missing manifest, invalid schema, etc.)
+
 When run manually, **all generated files persist on disk** until you remove them.
 
 ---
 
-### Validating documentation inputs
+### validate
+
+Validate documentation inputs without writing output files.
 
 ```bash
-odd-docs validate <repo-path>
+odd-docs validate <repo-path> [options]
 ```
 
-Validation checks include:
+**Options:**
+
+| Option         | Description                                   |
+| -------------- | --------------------------------------------- |
+| `-s, --strict` | Fail on unknown safety-affecting capabilities |
+
+**Validation checks:**
 
 - Required manifest fields
 - Schema presence and consistency
 - Capability declarations
 - Structural correctness
 
-Validation does **not** write output files.
-It exits with a non-zero code if errors are found, making it suitable for CI.
+**Exit codes:**
+
+- `0` — Validation passed
+- `1` — Validation failed or error encountered
+
+Suitable for CI pipelines.
 
 ---
 
-### Serving documentation locally
+### serve
+
+Start a local development server for generated documentation.
 
 ```bash
-odd-docs serve <repo-path>
+odd-docs serve <repo-path> [options]
 ```
 
-This command:
+**Options:**
+
+| Option                     | Default          | Description                                                     |
+| -------------------------- | ---------------- | --------------------------------------------------------------- |
+| `-p, --port <port>`        | `3000`           | Port to listen on                                               |
+| `-H, --host <host>`        | `localhost`      | Host to bind (localhost for safety)                             |
+| `-o, --output <dir>`       | `docs/generated` | Documentation output directory                                  |
+| `--no-watch`               | —                | Disable file watching                                           |
+| `--watch-mode <mode>`      | `auto`           | Watch mode: `auto` or `poll` (use `poll` for Docker/NFS)        |
+| `--reload <mode>`          | `ws`             | Reload mechanism: `ws`, `sse`, `poll`, `none`                   |
+| `--no-open`                | —                | Do not open browser on start                                    |
+| `--introspect <target>`    | —                | MCP target: `http://host:port` or `stdio:<cmd>`                 |
+| `--enable-mutations`       | —                | Enable mutation API endpoints (requires token)                  |
+| `--mutation-token <token>` | —                | Token for mutation endpoints (or `ODD_DOCS_MUTATION_TOKEN` env) |
+
+**Behavior:**
 
 - Generates documentation if it does not already exist
 - Starts a local HTTP server for viewing the docs
-- Optionally watches source files and regenerates on change
+- Watches source files and regenerates on change (unless `--no-watch`)
+- Auto-switches to SSE for non-localhost bindings (safer for K8s)
 
-Defaults:
+**Exit codes:**
 
-- Host: `localhost`
-- Port: `3000`
+- `0` — Clean shutdown (SIGINT/SIGTERM)
+- `1` — Error starting server
 
 This mode is intended for local development and inspection.
 
@@ -206,3 +279,22 @@ They differ in **who owns execution and filesystem lifecycle**.
 - Temporary directories created under MCP control are always ephemeral
 
 Choose the execution mode based on **ownership and persistence requirements**, not on automation level.
+
+---
+
+## License
+
+This project is source-available under the [Odd Essentials License (OEL)](./LICENSE).
+
+**Commercial use is prohibited** without a separate license from Odd Essentials, LLC.
+See [LICENSE](./LICENSE) for full terms.
+
+---
+
+## Resources
+
+- [Contributing](./CONTRIBUTING.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Changelog](./CHANGELOG.md)
+- [Deployment Guide](./docs/deployment.md)
+- [Specification](./docs/spec.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/odd-docs",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "MCP-native documentation generator for clients, servers, and tools",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,8 @@
     "clean": "rimraf dist",
     "ci": "npm run lint && npm run format:check && npm run typecheck && npm run build && npm run test",
     "release:dry-run": "semantic-release --dry-run",
-    "prepare": "husky"
+    "prepare": "husky",
+    "postinstall": "git config core.hooksPath .husky || true"
   },
   "keywords": [
     "mcp",
@@ -58,7 +59,9 @@
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",
     "@commitlint/config-conventional": "^19.0.0",
+    "@oddessentials/repo-standards": "^4.3.0",
     "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.2",
     "@types/node": "^22.0.0",