docs(cli): improve package discoverability

README.md

@@ -5,15 +5,16 @@ A 3D building editor built with React Three Fiber and WebGPU.
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![npm @pascal-app/core](https://img.shields.io/npm/v/@pascal-app/core?label=%40pascal-app%2Fcore)](https://www.npmjs.com/package/@pascal-app/core)
 [![npm @pascal-app/viewer](https://img.shields.io/npm/v/@pascal-app/viewer?label=%40pascal-app%2Fviewer)](https://www.npmjs.com/package/@pascal-app/viewer)
+[![npm @pascal-app/cli](https://img.shields.io/npm/v/@pascal-app/cli?label=%40pascal-app%2Fcli)](https://www.npmjs.com/package/@pascal-app/cli)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/XRKsDcpqgS)
 [![X (Twitter)](https://img.shields.io/badge/follow-%40pascal__app-black?logo=x&logoColor=white)](https://x.com/pascal_app)
 
 https://github.com/user-attachments/assets/8b50e7cf-cebe-4579-9cf3-8786b35f7b6b
 
 ## Run the Editor Locally
 
-When `@pascal-app/cli` is available on npm, Node.js 22.13 or newer can create a
-persistent local Pascal installation without cloning this repository:
+Node.js 22.13 or newer can create a persistent local Pascal installation without
+cloning this repository:
 
 ```bash
 npx @pascal-app/cli editor
@@ -58,6 +59,7 @@ editor/
 │   ├── editor/          # Editing tools and UI components
 │   ├── nodes/           # Built-in node definitions, renderers, and systems
 │   ├── cli/             # Persistent local editor installer and process manager
+│   ├── mcp/             # Model Context Protocol server and scene storage
 │   └── ui/              # Shared UI components
 ```
 
@@ -70,6 +72,7 @@ editor/
 | **@pascal-app/editor** | Editing tools, panels, selection, and direct-manipulation UI |
 | **@pascal-app/nodes** | Built-in registry plugin with node definitions, renderers, geometry, and systems |
 | **@pascal-app/cli** | Installs and manages a versioned standalone editor runtime and persistent local data |
+| **@pascal-app/mcp** | Exposes scene tools, resources, prompts, and local storage to MCP-compatible AI hosts |
 | **apps/editor** | Standalone Next.js host for the editor packages |
 
 The **viewer** renders the scene with sensible defaults. The **editor** extends it with interactive tools, selection management, and editing capabilities.

SETUP.md

@@ -51,9 +51,8 @@ return 500.
 
 ## CLI-managed editor
 
-When `@pascal-app/cli` is available on npm, Node.js 22.13 or newer can install a
-persistent local runtime, start it in the background, and open it in the browser
-without a repository checkout:
+Node.js 22.13 or newer can install a persistent local runtime, start it in the
+background, and open it in the browser without a repository checkout:
 
 ```bash
 npx @pascal-app/cli editor

packages/cli/README.md

@@ -1,57 +1,131 @@
-# `@pascal-app/cli`
+# Pascal CLI
 
-Install, run, and manage a persistent local installation of the open-source Pascal
-Editor without cloning its repository. Node.js 22.13 or newer is required.
+Run the open-source [Pascal 3D building editor](https://editor.pascal.app) locally
+from your terminal—without cloning or building the Pascal repository.
+
+[![npm version](https://img.shields.io/npm/v/@pascal-app/cli?label=npm)](https://www.npmjs.com/package/@pascal-app/cli)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+[![Pascal documentation](https://img.shields.io/badge/docs-editor.pascal.app-111111)](https://editor.pascal.app/docs/developers/local-editor)
 
 ```bash
 npx @pascal-app/cli editor
 ```
 
-pnpm and Bun package runners can launch the same executable. npm must remain available
-because `pascal update` uses it to resolve published releases:
+The first run installs a versioned editor runtime, starts it in the background on
+your computer, waits for it to become healthy, and opens it at
+`http://pascal.localhost:<port>`. Your projects are stored separately from the
+runtime, so updating the CLI does not replace your work.
+
+## Why use the CLI?
+
+- Run a complete local Pascal editor with one command.
+- Keep projects on your machine in a local SQLite database.
+- Start and stop the editor independently from your terminal session.
+- Inspect health, logs, versions, storage, and project state from scripts or agents.
+- Update through a health-checked activation that rolls back if the new runtime fails.
+
+## Requirements
+
+- Node.js 22.13 or newer
+- npm, including when the CLI itself is launched with pnpm or Bun
+- A browser, unless you pass `--no-open`
+
+The initial supported release is macOS. The packed runtime also passes automated
+release smoke tests on Ubuntu; broader Linux and Windows support is still being
+verified.
+
+## Install and run
+
+Use your preferred package runner:
 
 ```bash
+# npm
+npx @pascal-app/cli editor
+
+# pnpm
 pnpm dlx @pascal-app/cli editor
+
+# Bun
 bunx @pascal-app/cli editor
 ```
 
-The first run copies the bundled editor into `~/.pascal/runtime/<version>`, starts it on
-loopback, waits for its health endpoint, and opens `http://pascal.localhost:<port>`.
-Projects remain in `~/.pascal/data/pascal.db` when the CLI or editor is updated.
-Passing `--port` only affects a new process; an already healthy editor is reused at its
-existing URL.
-
-Install globally if you prefer the shorter command:
+Or install the `pascal` command globally:
 
 ```bash
 npm install --global @pascal-app/cli
 pascal editor
 ```
 
+Use `--no-open` on a headless machine. Use `--foreground` when a process supervisor
+should own the editor or when you want logs attached to the current terminal.
+
 ```bash
-pascal status
-pascal logs --follow
-pascal restart
-pascal stop
-# Guarded recovery when the recorded editor is alive but unhealthy:
-pascal stop --force
-pascal doctor
-pascal info --json
-pascal project list
-pascal plugin list
+npx @pascal-app/cli editor --no-open
+npx @pascal-app/cli editor --foreground --no-open
 ```
 
-Updates health-check a candidate runtime and restore the previous runtime if activation
-fails. Installed versions are retained to support rollback, so `pascal doctor` warns when
-more than three versions have accumulated. A later `pascal editor` run replaces a damaged
-copy of its bundled runtime without touching project data. Detached logs rotate at 10 MiB.
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `pascal editor` | Install if needed, ensure the editor is running, and open it. |
+| `pascal start` | Ensure the editor is running without opening a browser. |
+| `pascal stop [--force]` | Stop the managed process; `--force` is a guarded recovery path. |
+| `pascal restart` | Restart the editor with its current configuration. |
+| `pascal status [--json]` | Show health, version, PID, URL, and runtime metadata. |
+| `pascal open` | Open the running editor in your default browser. |
+| `pascal logs [--follow]` | Read or follow the managed editor log. |
+| `pascal update [--version <version>]` | Health-check and activate a published runtime. |
+| `pascal doctor [--json]` | Diagnose Node.js, storage, runtime, process, and plugin state. |
+| `pascal info [--json]` | Print platform, paths, runtime, and plugin context. |
+| `pascal project list [--json]` | List projects in the running local editor. |
+| `pascal project open <id>` | Open a local project in your browser. |
+| `pascal plugin list [--json]` | Inspect the reserved managed-plugin lock. |
+
+When you do not install globally, prefix commands with a runner—for example,
+`npx @pascal-app/cli doctor`.
+
+## Local data and security
+
+Pascal binds only to `127.0.0.1` and uses the reserved `.localhost` hostname. The
+initial CLI does not expose an unauthenticated editor to your network.
+
+```text
+~/.pascal/
+  runtime/<version>/           installed editor runtimes
+  data/pascal.db               projects and scenes
+  logs/editor.log              detached editor output
+  run/editor.json              managed process identity
+  plugins/                     reserved verified-plugin storage
+  pascal.plugins.lock          reserved managed-plugin lock
+```
+
+Runtime installation, project data, process state, and logs have separate lifecycles.
+The CLI does not include a command that deletes project data. Updates retain the
+previous runtime for rollback, and `pascal doctor` warns when more than three versions
+have accumulated.
+
+## Plugins and AI agents
+
+The current CLI manages the local editor runtime; it does not yet download plugin code
+from GitHub or npm. Follow the [plugin authoring guide](https://editor.pascal.app/docs/developers/plugins)
+and the standalone [Nature plugin](https://github.com/pascalorg/plugin-trees) when
+building an extension today.
+
+Pascal also exposes a hosted Model Context Protocol endpoint for Claude Code, Codex,
+Cursor, OpenClaw, and other MCP clients. See [Connect an AI agent](https://editor.pascal.app/docs/developers/mcp)
+for the hosted setup and the relationship between hosted projects, the local editor,
+and `@pascal-app/mcp`.
+
+## Documentation and support
+
+- [Complete CLI guide](https://editor.pascal.app/docs/developers/local-editor)
+- [Plugin authoring guide](https://editor.pascal.app/docs/developers/plugins)
+- [MCP and AI-agent guide](https://editor.pascal.app/docs/developers/mcp)
+- [Open-source repository](https://github.com/pascalorg/editor)
+- [Issues and feature requests](https://github.com/pascalorg/editor/issues)
+- [Discord community](https://discord.gg/XRKsDcpqgS)
 
-Use `pascal editor --foreground --no-open` for attached logs and debugging. The initial
-release supports macOS. It does not install a startup service, bind beyond loopback, or
-install plugin code from GitHub or npm. Linux and Windows support is not verified yet.
+## License
 
-See the full [CLI guide](https://editor.pascal.app/docs/developers/local-editor) for
-commands, updates, storage paths, security behavior, current platform coverage, and
-troubleshooting. Plugin publishers can use the separate
-[plugin authoring guide](https://editor.pascal.app/docs/developers/plugins) for the
-manifest, node, panel, host-integration, privacy, and testing contracts.
+MIT

packages/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pascal-app/cli",
   "version": "0.1.0",
-  "description": "Install and manage a local Pascal editor",
+  "description": "Run and manage the open-source Pascal 3D building editor locally from your terminal",
   "type": "module",
   "bin": {
     "pascal": "dist/bin/pascal.js"
@@ -40,8 +40,13 @@
   "keywords": [
     "pascal",
     "editor",
+    "3d-editor",
     "3d",
     "architecture",
+    "building-design",
+    "cad",
+    "bim",
+    "local-first",
     "cli"
   ],
   "repository": {
@@ -50,6 +55,14 @@
     "directory": "packages/cli"
   },
   "license": "MIT",
+  "author": {
+    "name": "Pascal",
+    "email": "open@pascal.app",
+    "url": "https://pascal.app"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "homepage": "https://editor.pascal.app/docs/developers/local-editor",
   "bugs": "https://github.com/pascalorg/editor/issues"
 }

packages/mcp/README.md

@@ -3,6 +3,11 @@
 Model Context Protocol server for the Pascal 3D editor. Drives the
 `@pascal-app/core` scene graph from any MCP-compatible AI host.
 
+For the hosted Pascal MCP endpoint and copy-ready setup for Claude Code, Codex,
+Cursor, and OpenClaw, read [Connect an AI agent](https://editor.pascal.app/docs/developers/mcp).
+The hosted endpoint edits projects in a Pascal account; this package is the
+open-source, local server for custom hosts and local scene storage.
+
 The server runs headlessly in Bun with no browser, WebGPU, React, or external
 database service. It exposes the same scene mutations used by the editor UI
 (create walls, place items, cut openings, undo, etc.) as MCP tools, resources,