Add minimal root npm wrapper

README.md

@@ -226,7 +226,18 @@ python tests/utils/agent_trace_replay_runner.py
 python benchmarks/run_replay_continuity.py --iterations 250 --output-dir reports/replay_continuity
 ```
 
-Use the layout-specific validation commands in [`docs/validation.md`](docs/validation.md). The repository root intentionally has no `package.json`, so root npm commands are expected to fail with `ENOENT` and should not be used as validation evidence.
+Use the validation commands in [`docs/validation.md`](docs/validation.md). The root `package.json` is a wrapper for reviewer convenience. App dependencies remain in `dashboard/app` and `showcase/app`.
+
+Root wrapper checks:
+
+```bash
+npm run layout
+npm run typecheck
+npm run validate
+npm run build
+npm test
+npm run check
+```
 
 Dashboard app checks:
 

docs/AGENT_WORKFLOW.md

@@ -50,12 +50,10 @@ changes:
    records repository structure, project files, tests, workflows, and likely
    API/dashboard/report areas in `docs/reports/repo-intake-report.md` without
    reading sensitive payloads or requiring network access.
-2. Use the layout-specific commands in [`docs/validation.md`](validation.md)
-   as the local validation step. Run Python tests from the repository root, run
-   dashboard npm commands from `dashboard/app`, and run showcase npm commands
-   from `showcase/app`. Root npm commands are intentionally invalid because the
-   repository root has no `package.json`; an `ENOENT` package.json error at the
-   root is expected layout behavior, not validation evidence.
+2. Use the commands in [`docs/validation.md`](validation.md) as the local
+   validation step. Use root wrapper commands for broad validation, or
+   app-specific commands from `dashboard/app` and `showcase/app` for targeted
+   validation.
 3. Run `python scripts/generate_contract_fixtures.py` when API/dashboard/export
    contracts are touched. It regenerates
    `contracts/examples/api-dashboard.example.json` and writes

docs/BENCHMARK_INTEGRATION.md

@@ -65,7 +65,7 @@ Required experiment repository artifacts:
 - `docs/reports/sanitization-summary.json`
 - `docs/reports/report-contract-validation-report.md`
 
-Required Comptextv7 validation commands are layout-specific; see [`docs/validation.md`](validation.md). Run Python checks from the repository root and npm checks only inside the app directory that owns the change. Root npm commands are intentionally invalid because the repository root has no `package.json`.
+Required Comptextv7 validation commands are documented in [`docs/validation.md`](validation.md). Use root wrapper commands for broad validation, or app-specific commands for targeted validation.
 
 ```bash
 pytest -q

docs/validation.md

@@ -1,13 +1,14 @@
 # Validation Guide
 
-This repository intentionally has multiple validation surfaces. Use the commands
-for the app or test surface you are validating instead of running generic npm
-commands from the repository root.
+This repository intentionally has multiple validation surfaces. You can use the
+root npm wrapper commands for broad reviewer-friendly validation, or use direct
+app commands when you only need to validate one app.
 
 ## Repository layout
 
 ```text
 Comptextv7/
+├── package.json    # Root command wrapper only; no root dependencies
 ├── dashboard/app/  # Vite + TypeScript dashboard application
 ├── showcase/app/   # Vite + TypeScript showcase application
 ├── tests/          # Python regression, replay, and foundation tests
@@ -16,14 +17,42 @@ Comptextv7/
 └── docs/           # Reviewer and validation documentation
 ```
 
-The repository root does **not** contain a `package.json`. That is the expected
-layout. Root-level npm commands fail with `ENOENT: no such file or directory,
-open '.../package.json'` because there is no root Node project, not because the
-Vite apps are broken.
+The repository root contains a minimal `package.json` wrapper for reviewer
+convenience. It does not define workspaces, dependencies, or a root Node app.
+Dashboard and showcase remain the real Node applications, with their dependency
+management in `dashboard/app` and `showcase/app`.
+
+Root npm scripts use `npm --prefix` to delegate to the app directories and use
+`pytest` for Python validation. No root `node_modules` directory or root npm
+dependencies are required for the wrapper itself.
+
+## Root wrapper commands
+
+Run broad validation commands from the repository root:
+
+```bash
+npm run layout
+npm run typecheck
+npm run validate
+npm run build
+npm test
+npm run check
+```
+
+The root wrapper delegates as follows:
+
+- `npm run layout` runs `python scripts/check_repo_layout.py`.
+- `npm run typecheck` runs dashboard and showcase typechecks with
+  `npm --prefix`.
+- `npm run validate` runs showcase static validation with `npm --prefix`.
+- `npm run build` runs dashboard and showcase builds with `npm --prefix`.
+- `npm test` runs `pytest -q`.
+- `npm run check` chains layout, typecheck, validate, build, and Python tests.
 
 ## Dashboard app validation
 
-Run dashboard validation from `dashboard/app`:
+Run dashboard validation directly from `dashboard/app` for targeted dashboard
+changes:
 
 ```bash
 cd dashboard/app
@@ -36,7 +65,8 @@ Use these commands for core dashboard TypeScript changes, including the
 
 ## Showcase app validation
 
-Run showcase validation from `showcase/app`:
+Run showcase validation directly from `showcase/app` for targeted showcase
+changes:
 
 ```bash
 cd showcase/app
@@ -61,17 +91,16 @@ pytest tests/test_paper_replay_bench.py tests/test_agent_trace_replay.py tests/t
 The focused replay command validates the deterministic paper replay, agent trace
 replay, and replay continuity surfaces without changing benchmark logic.
 
-## Known non-command: root npm
-
-Do **not** use these as validation commands from the repository root:
+Install the Python test dependency set:
 
 ```bash
-npm run typecheck
-npm run validate
-npm run build
-npm test
+python -m pip install -e '.[test]'
 ```
 
-They are intentionally invalid at the root because the root has no
-`package.json`. If npm reports an `ENOENT` package.json error at the root, switch
-to `dashboard/app` or `showcase/app` and run the app-specific commands above.
+Regenerate deterministic replay artifacts:
+
+```bash
+python tests/utils/paper_replay_runner.py
+python tests/utils/agent_trace_replay_runner.py
+python benchmarks/run_replay_continuity.py --iterations 250 --output-dir reports/replay_continuity
+```

package.json

@@ -0,0 +1,14 @@
+{
+  "name": "comptextv7-root",
+  "private": true,
+  "scripts": {
+    "build": "npm --prefix dashboard/app run build && npm --prefix showcase/app run build",
+    "typecheck": "npm --prefix dashboard/app run typecheck && npm --prefix showcase/app run typecheck",
+    "validate": "npm --prefix showcase/app run validate",
+    "test": "pytest -q",
+    "test:core": "pytest tests/test_core_foundation_ts.py -q",
+    "test:replay": "pytest tests/test_paper_replay_bench.py tests/test_agent_trace_replay.py tests/test_replay_continuity.py -q",
+    "layout": "python scripts/check_repo_layout.py",
+    "check": "npm run layout && npm run typecheck && npm run validate && npm run build && npm run test"
+  }
+}

scripts/check_repo_layout.py

@@ -1,7 +1,7 @@
 """Validate the expected multi-app repository layout.
 
-The repository root intentionally has no package.json. Dashboard and showcase
-Node commands belong to their app directories.
+The repository root has a minimal package.json command wrapper. Dashboard and
+showcase remain the real Node app directories.
 """
 
 from __future__ import annotations
@@ -10,6 +10,7 @@
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 REQUIRED_FILES = (
+    REPO_ROOT / "package.json",
     REPO_ROOT / "dashboard" / "app" / "package.json",
     REPO_ROOT / "showcase" / "app" / "package.json",
     REPO_ROOT / "artifacts" / "paper_replay_results.json",
@@ -18,17 +19,13 @@
 
 
 def check_repo_layout() -> list[str]:
-    """Return human-readable layout errors for missing or unexpected files."""
+    """Return human-readable layout errors for missing required files."""
     errors = [
         f"missing required file: {path.relative_to(REPO_ROOT)}"
         for path in REQUIRED_FILES
         if not path.is_file()
     ]
 
-    root_package = REPO_ROOT / "package.json"
-    if root_package.exists():
-        errors.append("unexpected root package.json: root npm commands are not part of this layout")
-
     return errors
 
 

tests/test_check_repo_layout.py

@@ -1,5 +1,8 @@
-from scripts.check_repo_layout import check_repo_layout
+from scripts.check_repo_layout import REPO_ROOT, check_repo_layout
 
 
 def test_expected_repo_layout_is_present():
+    assert (REPO_ROOT / "package.json").is_file()
+    assert (REPO_ROOT / "dashboard" / "app" / "package.json").is_file()
+    assert (REPO_ROOT / "showcase" / "app" / "package.json").is_file()
     assert check_repo_layout() == []