feat(cli): prepare npm release

.github/workflows/deploy.yml

@@ -85,3 +85,5 @@ jobs:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           workingDirectory: apps/mcp-server
+          # This subdirectory has no Bun lockfile, so automatic detection falls back to npm.
+          packageManager: bun

.github/workflows/release.yml

@@ -31,6 +31,7 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 24
+          registry-url: https://registry.npmjs.org
 
       - run: bunx --package vite-plus@0.2.9 vp install --frozen-lockfile
 
@@ -41,3 +42,5 @@ jobs:
           publish-script: bun run release:publish
           commit-message: "chore(release): version packages"
           pr-title: "chore(release): version packages"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -2,28 +2,61 @@
 
 [![Web](https://img.shields.io/github/v/tag/superdoc/ooxml-dev?filter=%40ooxml-dev%2Fweb%40*&label=Web&color=blue)](https://ooxml.dev)
 [![MCP Server](https://img.shields.io/github/v/tag/superdoc/ooxml-dev?filter=%40ooxml-dev%2Fmcp-server%40*&label=MCP%20Server&color=blue)](https://api.ooxml.dev/mcp)
+[![npm](https://img.shields.io/npm/v/%40ooxml-dev%2Fcli?label=CLI&color=CB3837&logo=npm)](https://www.npmjs.com/package/@ooxml-dev/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 The OOXML spec, explained by people who actually implemented it.
 
+> [!NOTE]
+> The CLI and MCP server use the production ooxml.dev service. You may need to create an account and sign in. Sign-in is only used to control usage; the service is free.
+
 ## What is this?
 
-An interactive reference for OOXML, built by the team behind [SuperDoc](https://superdoc.dev). Every page combines XML structure, live rendered previews, and implementation notes the spec leaves out. The MCP server exposes the same knowledge to AI assistants: prose search across the spec PDFs and deterministic schema lookup over the parsed XSDs.
+ooxml.dev is an interactive OOXML reference built by the team behind [SuperDoc](https://superdoc.dev). It combines XML examples, live previews, and implementation notes with searchable specification text and schema data.
 
-- **Live previews** - Edit XML and see it render in real-time. Every example is a working document.
-- **Implementation notes** - Where Word diverges from the spec, what will break your code, and what to do about it.
-- **Semantic spec search** - 18,000+ spec chunks searchable by meaning via MCP server.
-- **Structural schema lookup** - Element children, attributes, types, enums, namespaces. Same MCP server, deterministic answers from the parsed XSDs.
+- **Live previews** — Edit XML and see the result immediately. Every example is a working document.
+- **Implementation notes** — Learn where Word differs from the specification and which details can break an implementation.
+- **Specification search** — Search more than 18,000 specification chunks by meaning.
+- **Schema lookup** — Inspect element children, attributes, types, enums, and namespaces from the parsed XSDs.
 
 ## Why?
 
-The ECMA-376 spec is 5,000+ pages and it lies. Word's actual behavior diverges from the standard in ways you only discover by building against it. The knowledge to implement OOXML correctly is locked inside a handful of companies that have no incentive to share it.
+ECMA-376 is more than 5,000 pages, and Word sometimes behaves differently from the standard or fills in details the text leaves unclear. Many of these differences appear only while building a document engine.
+
+We found these gaps while building SuperDoc. This project records what we learned so other implementers do not need to discover the same edge cases alone.
+
+## CLI
+
+Install the CLI with npm. Node.js 20 or later is required.
+
+```bash
+npm install --global @ooxml-dev/cli
+```
+
+Sign in, then query the reference:
+
+```bash
+ooxml login
+ooxml search "paragraph spacing"
+ooxml element w:p
+```
+
+See the [CLI README](apps/cli/README.md) for all commands.
+
+## Agent skill
 
-We faced this at SuperDoc — building a document engine on native OOXML with no roadmap beyond an unreliable spec. We wrote down everything we learned and made it public. No one should have to reverse-engineer Word alone.
+The [`research-ooxml`](skills/research-ooxml/SKILL.md) skill teaches coding agents how to combine specification search and schema evidence through the CLI. Install the CLI first, then add the skill:
+
+```bash
+npx skills add superdoc/ooxml-dev --skill research-ooxml -g -y
+```
 
 ## MCP Server
 
-Ask questions in natural language and get answers grounded in the spec, or query the schema graph for precise structural answers. Works with Claude Code, Codex CLI, Cursor, and any MCP-compatible client.
+Search specification prose or query the schema graph for precise structural answers. The server works with Claude Code, Codex CLI, Cursor, and other MCP clients.
+
+> [!NOTE]
+> The hosted server uses MCP `2026-07-28` and remains compatible with current 2024 and 2025 clients.
 
 **Claude Code**
 
@@ -44,7 +77,9 @@ Or in `~/.codex/config.toml`:
 url = "https://api.ooxml.dev/mcp"
 ```
 
-**Cursor** — add to your MCP settings:
+**Cursor**
+
+Add the server to your MCP settings:
 
 ```json
 {
@@ -61,10 +96,6 @@ Four tool families share one server:
 - **Package metadata** (curated from Part 1 §11.3.x / §12.3.x / §13.3.x / §15.x): `ooxml_package_part`
 - **Preset shapes** (generated from Part 1 Annex D): `ooxml_preset_shape`
 
-### Authentication
-
-`/mcp` uses OAuth 2.1. Compatible MCP clients register automatically, open the ooxml.dev sign-in and consent pages, and receive a token limited to this MCP server. Clerk handles user identity; the MCP server handles dynamic client registration, PKCE, tokens, refresh, and revocation.
-
 ## Development
 
 ```bash
@@ -75,15 +106,13 @@ bun run build                                             # Production build
 bun run build:prod                                        # Build with .env.prod
 ```
 
-Vite+ owns the web development, build, formatting, linting, workspace task, and Git hook
-workflows. Bun remains the package manager and test runtime because the test suite uses `bun:test`.
+Vite+ handles local development, builds, formatting, linting, workspace tasks, and Git hooks. Bun remains the package manager and test runtime because the tests use `bun:test`.
 
-`build:prod` requires a live Clerk publishable key. This prevents production deploys from using the
-auth fallback or a test Clerk instance.
+`build:prod` requires a live Clerk publishable key. This prevents a production deployment from using the auth fallback or a test Clerk instance.
 
 ## Contributing
 
-Contributions welcome. Add implementation notes, fix examples, or improve the reference.
+Contributions are welcome. Add implementation notes, fix examples, or improve the reference.
 
 ## License
 

apps/cli/README.md

@@ -1,22 +1,38 @@
 # OOXML CLI
 
-Use the OOXML reference from a terminal or an agent skill. Sign in with Clerk to query the hosted ooxml.dev service.
+Use the OOXML reference from a terminal or an agent skill.
 
-While the package is private, run it from the repository root:
+## Install
+
+Node.js 20 or later is required.
 
 ```bash
-bun run ooxml login
-bun run ooxml search "paragraph spacing"
-bun run ooxml element w:p
-bun run ooxml children w:p
-bun run ooxml attributes w:p
-bun run ooxml logout
+npm install --global @ooxml-dev/cli
 ```
 
-During this private test, the CLI stores sign-in tokens as plain text in your application data directory. Do not use it from a shared account. The CLI does not store queries or results.
+## Use the CLI
 
-The bundled [`research-ooxml`](../../skills/research-ooxml/SKILL.md) skill tells agents which commands to use and how to combine schema and specification evidence.
+Sign in, then query the reference:
 
-MCP is an internal transport detail. It is not part of the CLI or skill interface.
+```bash
+ooxml login
+ooxml search "paragraph spacing"
+ooxml element w:p
+ooxml children w:p
+ooxml attributes w:p
+ooxml logout
+```
+
+The CLI uses the production ooxml.dev service. You may need to create an account and sign in. Sign-in is only used to control usage; the service is free.
+
+The CLI stores sign-in tokens as plain text in your application data directory. Do not use it from a shared account. It does not store queries or results.
 
-The package remains private while we test it. Secure credential storage and npm publishing are separate release steps.
+## Install the agent skill
+
+The bundled [`research-ooxml`](../../skills/research-ooxml/SKILL.md) skill tells coding agents which commands to use and how to combine schema and specification evidence.
+
+```bash
+npx skills add superdoc/ooxml-dev --skill research-ooxml -g -y
+```
+
+MCP is an internal transport detail. It is not part of the CLI or skill interface.

apps/cli/package.json

@@ -2,20 +2,24 @@
   "name": "@ooxml-dev/cli",
   "version": "0.1.0",
   "description": "Query the ooxml.dev reference from a terminal or agent skill.",
-  "private": true,
+  "license": "MIT",
   "type": "module",
   "bin": {
-    "ooxml": "./dist/cli.mjs"
+    "ooxml": "dist/cli.mjs"
   },
   "files": [
     "dist"
   ],
   "engines": {
     "node": ">=20"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "vp pack --clean",
     "dev": "bun src/cli.ts",
+    "prepublishOnly": "bun run build",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package.json

@@ -54,13 +54,7 @@
   "overrides": {
     "vite": "catalog:"
   },
-  "devEngines": {
-    "packageManager": {
-      "name": "bun",
-      "version": "1.3.14",
-      "onFail": "download"
-    }
-  },
+  "packageManager": "bun@1.3.14",
   "catalog": {
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",