Move docs/ and samples/ out of packages/expreszo to the repo root

The documentation and the Monaco-based playground are repo-level
concerns, not part of any published npm package. Both are now at
the workspace root next to mkdocs.yml.

* git mv packages/expreszo/docs           -> docs/
* git mv packages/expreszo/samples        -> samples/
* git mv packages/expreszo/mkdocs.yml     -> mkdocs.yml

Wiring:

* samples/language-service-sample/serve-sample.cjs — special-cases
  `/dist/...` URLs to resolve them inside packages/expreszo/dist
  (the bundle still lives there). Other URLs continue to resolve
  against the new repo-root server root, so /docs/logo.png picks
  up the moved logo automatically.
* root package.json gains `playground`, `docs:build`, `docs:serve`
  scripts that drive the new layout. The matching `playground`
  script in packages/expreszo/package.json is removed since it
  no longer fits at the package level.
* packages/expreszo/vitest.config.ts drops the now-stale
  `samples/**` coverage exclude.
* deploy-playground.yml runs `mkdocs build` from the repo root
  (mkdocs.yml is here now) and copies samples / dist / site from
  the root and from packages/expreszo as appropriate.
* CLAUDE.md adds docs/, samples/, and the new yarn root scripts
  to the repository-layout section.

Verified locally: mkdocs build --strict clean (writes to ./site),
yarn workspaces run lint/type-check/test all green
(2186 + 100 + 12 = 2298 tests pass).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Sander Toonen

.github/workflows/deploy-playground.yml

@@ -45,18 +45,19 @@ jobs:
         run: pip install mkdocs-material==9.7.1
 
       - name: Build documentation
-        working-directory: packages/expreszo
+        # mkdocs.yml lives at the repo root now; mkdocs reads docs/ from
+        # there and writes the rendered site to ./site.
         run: mkdocs build
 
       - name: Prepare playground files
         run: |
           mkdir -p _site/dist
-          cp packages/expreszo/samples/language-service-sample/index.html _site/
-          cp packages/expreszo/samples/language-service-sample/app.js _site/
-          cp packages/expreszo/samples/language-service-sample/examples.js _site/
-          cp packages/expreszo/samples/language-service-sample/styles.css _site/
+          cp samples/language-service-sample/index.html _site/
+          cp samples/language-service-sample/app.js _site/
+          cp samples/language-service-sample/examples.js _site/
+          cp samples/language-service-sample/styles.css _site/
           cp packages/expreszo/dist/bundle.js _site/dist/
-          cp -r packages/expreszo/site _site/docs
+          cp -r site _site/docs
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

CLAUDE.md

@@ -12,12 +12,15 @@ This is a **yarn workspace monorepo** with three published packages:
 │   ├── expreszo/             # @pro-fa/expreszo — core expression evaluator
 │   ├── expreszo-datetime/    # @pro-fa/expreszo-datetime — optional Luxon plugin
 │   └── expreszo-mcp-server/  # @pro-fa/expreszo-mcp-server — MCP server CLI
+├── docs/                     # mkdocs source — published to GitHub Pages by deploy-playground.yml
+├── samples/                  # Monaco-based language-service playground (also deployed to Pages)
+├── mkdocs.yml                # mkdocs site config (reads docs/, writes site/)
 ├── eslint.config.js          # shared eslint config
 ├── tsconfig.base.json        # shared TS compiler options (each package extends this)
 └── package.json              # private workspace root
 ```
 
-The core never depends on Luxon or `@modelcontextprotocol/sdk` — those live only in their respective companion packages.
+`docs/` and `samples/` are intentionally outside `packages/` — they are repo-level concerns, not part of any published npm package. The core never depends on Luxon or `@modelcontextprotocol/sdk` either; those live only in their respective companion packages.
 
 ## Commands
 
@@ -41,6 +44,14 @@ yarn coverage                       # 80% threshold required
 yarn bench                          # parser benchmarks
 ```
 
+Docs and the playground are wired up at the workspace root:
+
+```bash
+yarn playground                     # build expreszo UMD + serve the Monaco playground at :8080
+yarn docs:serve                     # mkdocs dev server with live reload
+yarn docs:build                     # produce ./site for the deploy-playground.yml workflow
+```
+
 ## Core architecture (`@pro-fa/expreszo`)
 
 Safe, extensible expression evaluator — a configurable alternative to `eval()`. Uses a **Pratt parser** and an **immutable AST**: