@compr/opscontext-mcp 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -2,6 +2,111 @@
 
 All notable changes to OpsContext for AI Agents (previously ContextEngine — MCP server + CLI) are documented here.
 
+> Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
+
+## [2.4.2] — 2026-08-16 — Close the three holes 2.4.1 left in "a directory is not a project"
+
+2.4.1 made `score`'s scope explicit but enforced it on only one of three entry points. An
+adversarial review (30 agents, sandboxed) raised 26 findings, refuted 18, and confirmed 8 —
+clustering into the fixes below. Every repro was reproduced against the shipped build before
+being fixed, and re-run after.
+
+### Fixed
+
+- **`score .` re-created the exact incident 2.4.1's LOCK forbids.** `cd ~/Projects && score .`
+  wrote `~/Projects/SCORE.md` — *"Projects: 27/100 (F), Not a git repo"* — into the container of
+  37 repositories. The identical command *without* the `.` was correctly refused: the guard
+  existed, and the explicit-path entry point walked straight past it. Same for `score ~/Projects`,
+  `score ..` and `score /`. A path must now carry a build/VCS marker
+  (`.git`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Makefile`, …) to be
+  scoreable. Locked as `[RESOLVE-PATH-MUST-BE-A-PROJECT]`.
+- **A mistyped project name silently scored a subdirectory.** `score src`, `score dist`,
+  `score docs` no longer errored with the available-projects list — the bare token fell through
+  to path resolution against the cwd, scored the subdirectory, and wrote a `SCORE.md` into it.
+  In this repo `score dist` wrote `dist/SCORE.md`, which then ships inside the npm tarball. A
+  bare name now resolves against the fleet index **only**; the error names the directory it
+  found and offers `score ./src` as the explicit escape hatch.
+- **`score` in a subpackage reported "Not a git repo" from inside a git repo.** `cd server &&
+  score` stopped at the nearest `package.json` and reported *"server — 32% (F), Not a git repo,
+  No CI pipeline, README.md Missing"* — every claim false about the project the user was standing
+  in. `.git` is now the project boundary and wins over any nearer build file; a genuinely
+  standalone package still resolves to itself. Locked as `[GIT-ROOT-IS-THE-PROJECT-BOUNDARY]`.
+- **`CONTEXTENGINE_WORKSPACES` was read and ignored.** It was a fallback that applied only when
+  the config file defined no `workspaces` — so on the documented setup it did nothing, including
+  in every MCP config block this project ships. Precedence is now env var > config file >
+  auto-discovery. Locked as `[ENV-WORKSPACES-WINS]`.
+- Error messages no longer say "not an existing directory" about a directory that exists. Each
+  of the four failure modes (unknown name / no such path / not a directory / not a project) now
+  names the actual reason.
+
+### Documentation
+
+- README's "Config resolution order" table documented the pre-fix precedence and could not
+  describe both surfaces at once. Now split: config-file lookup, project-fleet lookup (env wins),
+  and an explicit note that the *search corpus* still prefers the config file.
+- `CLAUDE.md` still told every agent in this repo that `npx . score` scores all projects.
+
+### Tests
+
+373 pass (8 new). One pre-existing test asserted the old behaviour — a marker-less directory
+resolving as a project — and was corrected rather than deleted.
+
+## [2.4.1] — 2026-08-16 — `score` scope is now explicit: current project by default, `--all` to opt into the fleet
+
+### Changed (behaviour — read this before upgrading)
+
+- **`score` with no argument now scores only the current project**, walking up from the working
+  directory to the enclosing repo root. It previously scored all discovered projects **and wrote
+  a `SCORE.md` into every one of them** — which dirtied 26 repositories on the author's machine,
+  several of them auto-pushing on commit. Fleet-wide scoring now requires `--all`.
+  Locked as `[SCORE-FLEET-IS-OPT-IN]`.
+- `score --all` prints how many projects it is about to write into before doing it, and
+  `--all` combined with a project argument is now a hard error rather than a silently ignored flag.
+- The MCP `score_project` tool keeps its fleet-wide default — it never writes `SCORE.md`, so it
+  does not carry the hazard. The write is what must be asked for, not the scan.
+
+- **`score` with no argument now refuses to run outside a project** instead of scoring whatever
+  directory it is in. Run from `~/Projects` — a *container* of projects — it previously scored
+  the container and wrote a `SCORE.md` claiming `Projects: 27/100 (F)`; from `/` it would do the
+  same to the filesystem root. It now exits 1 and names the three ways to proceed.
+  Locked as `[SCORE-CWD-MUST-BE-A-PROJECT]`.
+
+### Fixed (documentation that shipped a working footgun)
+
+- **`skills/opscontext/SKILL.md` told agents to run `npx @compr/contextengine-mcp`** — a package
+  name npm freezes at **1.23.1**. Following the shipped skill downloaded a June scorer and ran a
+  fleet-wide write with a 94-point rubric that reports root-level `copilot-instructions.md` as
+  `Missing`. Ten call sites corrected, including three MCP-config blocks that would have
+  installed the frozen version as a long-running server. `skills/` now has zero references to it.
+- Same correction to the `.claude/settings.json` post-push reminder.
+
+### Added
+
+- **`score` accepts a path as well as a project name** — `score ~/Projects/PLANK.io`,
+  `score ../PLANK.io`, or an absolute path. Paths outside configured workspaces work too.
+  Previously `score /Users/yan/Projects/PLANK.io` failed with "Project not found" while listing
+  `PLANK.io` among the available projects — the lookup only ever compared basenames, so the
+  directory was never inspected. Locked as `[SCORE-ACCEPTS-PATH]`.
+- Same path support in the MCP `score_project` tool (strictly more accepting; no default changed).
+- `tests/project-resolution.test.ts` — 11 regression tests covering name/path/symlink/
+  file-not-a-directory/case-insensitivity/dotted names, and `findProjectRoot` termination.
+
+### Fixed
+
+- Polyglot repositories are scored against the languages they actually use (released here; committed
+  in 2.4.0's wake): test directories are aggregated across ecosystems rather than the first match
+  winning, `.dart` tests are counted, and Dart tooling (`analysis_options.yaml`) satisfies the
+  type-checking check instead of the project being marked down for a missing `tsconfig.json`.
+  PLANK.io 98%; KONIVE.com correctly reports 102 test files across two directories.
+
+### Investigated — no change
+
+- A report that the generated pre-commit hook regenerates and re-stages `SCORE.md` mid-commit
+  **does not reproduce**. `generatePreCommitHook()` only stats mtimes and greps staged files for
+  secrets; there is no score invocation and no `git add` in it, nor in the older custom hook the
+  reporting repo actually has installed. The observed empty commit is consistent with the
+  fleet-wide-write default above, which this release removes.
+
 ## [2.1.3] — 2026-06-26 — Tool manifest as single source of truth + server-meta.json for VS Code extension
 
 Tactical fix for a class of silent display drift: the VS Code info panel hardcoded "Active on all 17 MCP tools" while the npm package was at 21 tools. The README was at 20. None of these were tied to the actual `server.tool(...)` registrations, so adding a tool (e.g. `drift_status` in 2.1.0) left all displays stale.

package/README.md

@@ -248,9 +248,14 @@ npx @compr/opscontext-mcp list-sources
 # Discover and analyze all projects
 npx @compr/opscontext-mcp list-projects
 
-# AI-readiness score (one or all projects)
+# AI-readiness score — no argument scores the CURRENT project only
 npx @compr/opscontext-mcp score
-npx @compr/opscontext-mcp score ContextEngine
+npx @compr/opscontext-mcp score ContextEngine          # by project name
+npx @compr/opscontext-mcp score ~/Projects/PLANK.io    # or by path
+
+# Score every discovered project (writes a SCORE.md into each — opt in explicitly)
+npx @compr/opscontext-mcp score --all
+npx @compr/opscontext-mcp score --all --no-save        # scan without writing
 
 # Visual HTML report (opens in browser)
 npx @compr/opscontext-mcp score --html
@@ -343,13 +348,33 @@ For full control, create a `contextengine.json`:
 
 ### Config resolution order
 
+Which **config file** is read (both the search corpus and the project fleet):
+
 | Priority | Source |
 |----------|--------|
 | 1 | `CONTEXTENGINE_CONFIG` env var |
 | 2 | `./contextengine.json` |
 | 3 | `~/.contextengine.json` |
-| 4 | `CONTEXTENGINE_WORKSPACES` env var |
-| 5 | `~/Projects` auto-discover |
+
+Which **project fleet** is scanned — this is what `score --all`, `audit`, `list_projects`
+and `check_ports` operate on:
+
+| Priority | Source |
+|----------|--------|
+| 1 | `CONTEXTENGINE_WORKSPACES` env var (colon-separated) |
+| 2 | `workspaces` in the config file |
+| 3 | `~/Projects` auto-discover |
+
+**The env var wins.** It is set per-invocation, so it is the most specific statement of
+intent — and it is what the MCP config blocks in this README set. Use it to scope a run:
+
+```bash
+CONTEXTENGINE_WORKSPACES=/tmp/sandbox npx @compr/opscontext-mcp score --all
+```
+
+> Note: the **search corpus** (`search`, `reindex`, `list-sources`) still prefers the config
+> file's `workspaces` over the env var. If you rely on the env var to scope indexing, set
+> `CONTEXTENGINE_CONFIG` to a config without `workspaces`, or unset `workspaces` there.
 
 ## Plugin Adapters
 
@@ -436,6 +461,22 @@ The `score` command evaluates project AI-readiness across **documentation, infra
 
 **Grade scale:** A+ (90%+) · A (80%+) · B (70%+) · C (60%+) · D (50%+) · F (<50%)
 
+### What gets scored, and what gets written
+
+`score` writes a `SCORE.md` into each project it scores. Because that is a write into your
+repositories, the scope is never inferred:
+
+| Command | Scores | Writes `SCORE.md` to |
+|---|---|---|
+| `score` | the project you are standing in (walks up to the repo root) | that one project |
+| `score <name>` / `score <path>` | that one project | that one project |
+| `score --all` | every discovered project | **every** discovered project |
+| any of the above `--no-save` | as above | nothing |
+
+A project argument may be a **name** (`PLANK.io`) or a **path** (`~/Projects/PLANK.io`,
+`../PLANK.io`, or an absolute path). A path also works for projects outside your configured
+workspaces.
+
 ### Project Naming & Structure Tips
 
 The scorer discovers projects from your configured `workspaces` directories (default: `~/Projects`).

package/dist/agents.js

@@ -86,22 +86,48 @@ const AGENT_DOC_TOPICS = [
 function matchDocTopics(content, topics) {
     return topics.filter(t => t.patterns.test(content)).map(t => t.label);
 }
-function detectLanguage(p) {
-    if (existsSync(join(p, "package.json")))
-        return "js";
-    const pythonMarkers = ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "__manifest__.py"];
-    if (pythonMarkers.some(m => existsSync(join(p, m))))
-        return "python";
-    if (existsSync(join(p, "composer.json")))
-        return "php";
-    // Odoo addons and src-layout packages keep their markers one level down.
+/**
+ * ALL languages present, root and one level down — not just a winner.
+ *
+ * A single "primary language" is the wrong model for this fleet. PLANK.io is a Flutter app with a
+ * Node backend: picking one meant scoring a Dart codebase against `tsconfig.json` and calling its
+ * analyzer config missing. Returning the set lets each tooling check pass on whichever ecosystem
+ * actually configures it. Part of [SCORE-LANGUAGE-AWARE].
+ */
+const LANGUAGE_MARKERS = [
+    { lang: "dart", files: ["pubspec.yaml"] },
+    { lang: "python", files: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "__manifest__.py"] },
+    { lang: "js", files: ["package.json"] },
+    { lang: "php", files: ["composer.json"] },
+];
+function detectLanguages(p) {
+    const found = new Set();
+    const scan = (base) => {
+        for (const { lang, files } of LANGUAGE_MARKERS) {
+            if (files.some(f => existsSync(join(base, f))))
+                found.add(lang);
+        }
+    };
+    scan(p);
+    for (const sub of safeSubdirs(p))
+        scan(join(p, sub));
+    if (found.size === 0)
+        found.add("other");
+    return found;
+}
+/** First existing path among `candidates`, searched at the root and one level down. */
+function findConfig(p, candidates) {
+    for (const c of candidates) {
+        if (existsSync(join(p, c)))
+            return c;
+    }
     for (const sub of safeSubdirs(p)) {
-        if (pythonMarkers.some(m => existsSync(join(p, sub, m))))
-            return "python";
-        if (existsSync(join(p, sub, "package.json")))
-            return "js";
+        for (const c of candidates) {
+            if (existsSync(join(p, sub, c)))
+                return `${sub}/${c}`;
+        }
     }
-    return "other";
+    return null;
 }
 /** Immediate subdirectories worth searching — skips vendored, hidden and build output. */
 function safeSubdirs(p) {
@@ -184,9 +210,15 @@ function countTestFiles(dirPath, depth = 0) {
                 count += countTestFiles(fullPath, depth + 1);
             }
             else if (entry.isFile()) {
-                if (/\.(test|spec|_test)\.(ts|tsx|js|jsx|py|php)$/.test(entry.name) ||
-                    entry.name.startsWith("test_") ||
-                    entry.name.endsWith("_test.py")) {
+                // 🔒 [SCORE-LANGUAGE-AWARE] — the extension list is part of the language assumption.
+                // `dart` was absent, so PLANK.io's 68 Flutter tests in plank_app/test/ counted as ZERO:
+                // the directory was found, every file was skipped, and the row credited the Node backend
+                // alone. A test counter that silently ignores a language reports "no tests" for a suite
+                // that runs on every build. Add the extension when adding a language, not after someone
+                // notices their tests are invisible.
+                if (/\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|php|dart)$/.test(entry.name) ||
+                    /_(test|spec)\.(py|dart|go|rb)$/.test(entry.name) ||
+                    entry.name.startsWith("test_")) {
                     count++;
                 }
             }
@@ -1112,7 +1144,7 @@ export function scoreProject(dir) {
     const checks = [];
     const p = dir.path;
     // Language decides which tooling checks apply at all — see [SCORE-LANGUAGE-AWARE].
-    const lang = detectLanguage(p);
+    const langs = detectLanguages(p);
     // --- Documentation (30 points max) ---
     // copilot-instructions.md (6 pts) — scored on CONTENT, not length.
     // 🔒 LOCKED [SCORE-CONTENT-NOT-LENGTH] — 2026-08-14
@@ -1427,74 +1459,86 @@ export function scoreProject(dir) {
     ];
     const foundTests = testDirs.filter(td => existsSync(join(p, td)));
     if (foundTests.length > 0) {
-        const testDirPath = join(p, foundTests[0]);
-        const testIsSymlink = isSymlink(testDirPath);
-        const testFileCount = countTestFiles(testDirPath);
-        if (testIsSymlink) {
-            checks.push({ name: "Tests", category: "Code Quality", points: 3, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ is a symlink (${testFileCount} test files) — should be real test directory` });
+        // Count across EVERY test directory, not just the first match. PLANK.io has 68 Flutter tests
+        // in plank_app/test/ and 38 backend tests in backend/__tests__/; taking foundTests[0] credited
+        // the backend alone and rendered the larger codebase invisible. Any polyglot or multi-package
+        // repo hit this — the bug was the `[0]`, not the search.
+        const perDir = foundTests.map(td => ({ rel: td, count: countTestFiles(join(p, td)), symlink: isSymlink(join(p, td)) }));
+        const testFileCount = perDir.reduce((sum, d) => sum + d.count, 0);
+        const contributing = perDir.filter(d => d.count > 0);
+        const where = (contributing.length > 0 ? contributing : perDir)
+            .map(d => `${d.rel}/ (${d.count})`)
+            .slice(0, 3)
+            .join(", ") + (perDir.length > 3 ? `, +${perDir.length - 3} more` : "");
+        const allSymlinks = perDir.every(d => d.symlink);
+        if (allSymlinks) {
+            checks.push({ name: "Tests", category: "Code Quality", points: 3, maxPoints: 8, status: "partial", detail: `${where} — symlinked, should be real test directories` });
         }
         else if (testFileCount >= RUBRIC.testsFull) {
-            checks.push({ name: "Tests", category: "Code Quality", points: 8, maxPoints: 8, status: "pass", detail: `${foundTests[0]}/ — ${testFileCount} test files` });
+            checks.push({ name: "Tests", category: "Code Quality", points: 8, maxPoints: 8, status: "pass", detail: `${testFileCount} test files across ${contributing.length} dir(s): ${where}` });
         }
         else if (testFileCount > RUBRIC.testsPartial) {
-            checks.push({ name: "Tests", category: "Code Quality", points: 5, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ — only ${testFileCount} test files` });
+            checks.push({ name: "Tests", category: "Code Quality", points: 5, maxPoints: 8, status: "partial", detail: `only ${testFileCount} test files: ${where}` });
         }
         else {
-            try {
-                const hasAnyFiles = readdirSync(testDirPath).length > 0;
-                if (hasAnyFiles) {
-                    checks.push({ name: "Tests", category: "Code Quality", points: 4, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ has files but no standard test files detected` });
-                }
-                else {
-                    checks.push({ name: "Tests", category: "Code Quality", points: 1, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ exists but empty` });
+            let hasAnyFiles = false;
+            for (const d of perDir) {
+                try {
+                    if (readdirSync(join(p, d.rel)).length > 0) {
+                        hasAnyFiles = true;
+                        break;
+                    }
                 }
+                catch { /* unreadable dir counts as empty */ }
             }
-            catch {
-                checks.push({ name: "Tests", category: "Code Quality", points: 1, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ exists but unreadable` });
-            }
+            checks.push(hasAnyFiles
+                ? { name: "Tests", category: "Code Quality", points: 4, maxPoints: 8, status: "partial", detail: `${where} has files but no standard test files detected` }
+                : { name: "Tests", category: "Code Quality", points: 1, maxPoints: 8, status: "partial", detail: `${where} exists but empty` });
         }
     }
     else {
         checks.push({ name: "Tests", category: "Code Quality", points: 0, maxPoints: 8, status: "fail", detail: "No test directory" });
     }
-    // TypeScript / type checking (5 pts)
-    const tsconfigPath = join(p, "tsconfig.json");
-    if (existsSync(tsconfigPath)) {
-        const tsconfigContent = readFileSync(tsconfigPath, "utf-8").trim();
-        const tsconfigIsSymlink = isSymlink(tsconfigPath);
-        // Detect minimal/reference-only tsconfigs (just project references with no real config)
-        const isSubstantive = tsconfigContent.length > RUBRIC.tsconfigSubstantive && (tsconfigContent.includes('"compilerOptions"') || tsconfigContent.includes('"extends"'));
-        if (tsconfigIsSymlink) {
-            checks.push({ name: "TypeScript", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "tsconfig.json is a symlink — create root config" });
+    // TypeScript / type checking (5 pts) — see [SCORE-LANGUAGE-AWARE].
+    // Checks every ecosystem the repo actually uses, so a Flutter app with a Node backend is not
+    // told its Dart analyzer config is a missing tsconfig.
+    {
+        const tsCfg = findConfig(p, ["tsconfig.json"]);
+        const dartCfg = langs.has("dart") ? findConfig(p, ["analysis_options.yaml"]) : null;
+        const pyCfg = langs.has("python") ? findConfig(p, ["mypy.ini", ".mypy.ini", "pyrightconfig.json"]) : null;
+        const pyprojectPath = findConfig(p, ["pyproject.toml"]);
+        const pyproject = pyprojectPath ? readFileSync(join(p, pyprojectPath), "utf-8") : "";
+        const pyInline = langs.has("python") && /\[tool\.(mypy|pyright)\]/.test(pyproject);
+        if (tsCfg) {
+            const content = readFileSync(join(p, tsCfg), "utf-8").trim();
+            const substantive = content.length > RUBRIC.tsconfigSubstantive && (content.includes('"compilerOptions"') || content.includes('"extends"'));
+            if (isSymlink(join(p, tsCfg))) {
+                checks.push({ name: "TypeScript", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: `${tsCfg} is a symlink — create a real config` });
+            }
+            else if (substantive) {
+                checks.push({ name: "TypeScript", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${tsCfg} present` });
+            }
+            else {
+                checks.push({ name: "TypeScript", category: "Code Quality", points: 3, maxPoints: 5, status: "partial", detail: `${tsCfg} is minimal — add compilerOptions for full type safety` });
+            }
         }
-        else if (isSubstantive) {
-            checks.push({ name: "TypeScript", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: "tsconfig.json present" });
+        else if (dartCfg) {
+            checks.push({ name: "Type checking", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${dartCfg} — Dart analyzer configured` });
         }
-        else {
-            checks.push({ name: "TypeScript", category: "Code Quality", points: 3, maxPoints: 5, status: "partial", detail: "tsconfig.json is minimal — add compilerOptions for full type safety" });
+        else if (pyCfg || pyInline) {
+            checks.push({ name: "Type checking", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${pyCfg ?? pyprojectPath} — static type checking configured` });
         }
-    }
-    else if (existsSync(join(p, "jsconfig.json"))) {
-        checks.push({ name: "Type checking", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "jsconfig.json only" });
-    }
-    else if (lang === "python") {
-        // See [SCORE-LANGUAGE-AWARE]. Python type checking is mypy/pyright, not tsconfig.
-        const pyTypeMarkers = ["mypy.ini", ".mypy.ini", "pyrightconfig.json"];
-        const foundPyType = pyTypeMarkers.filter(m => existsSync(join(p, m)));
-        const pyproject = existsSync(join(p, "pyproject.toml")) ? readFileSync(join(p, "pyproject.toml"), "utf-8") : "";
-        if (foundPyType.length > 0 || /\[tool\.(mypy|pyright)\]/.test(pyproject)) {
-            checks.push({ name: "Type checking", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${foundPyType[0] ?? "pyproject.toml"} — static type checking configured` });
+        else if (existsSync(join(p, "jsconfig.json"))) {
+            checks.push({ name: "Type checking", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "jsconfig.json only" });
+        }
+        else if (langs.has("js") || langs.has("dart") || langs.has("python")) {
+            const want = [langs.has("js") && "tsconfig.json", langs.has("dart") && "analysis_options.yaml", langs.has("python") && "mypy/pyright"].filter(Boolean).join(" or ");
+            checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "fail", detail: `No ${want} found — add static type checking` });
         }
         else {
-            checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "fail", detail: "Python project with no mypy/pyright config — add one for static type checking" });
+            checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "unknown", detail: "❔ No type-checking convention known for this project type — not assessed" });
         }
     }
-    else if (lang === "php" || lang === "other") {
-        checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "unknown", detail: `❔ No type-checking convention known for this project type (${lang}) — not assessed` });
-    }
-    else {
-        checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "fail", detail: "No tsconfig/jsconfig" });
-    }
     // Linting config (4 pts) — verifies linting tools are installed, not just config
     const lintConfigs = [".eslintrc.js", ".eslintrc.json", ".eslintrc.yml", "eslint.config.js", "eslint.config.mjs", ".prettierrc", "phpcs.xml"];
     const foundLint = lintConfigs.filter(l => existsSync(join(p, l)));
@@ -1511,10 +1555,16 @@ export function scoreProject(dir) {
             checks.push({ name: "Linting", category: "Code Quality", points: 4, maxPoints: 4, status: "pass", detail: foundLint.join(", ") });
         }
     }
-    else if (lang === "python") {
+    else if (langs.has("dart") && findConfig(p, ["analysis_options.yaml"])) {
+        // Dart's analyzer IS the linter — analysis_options.yaml is enforced on every build.
+        checks.push({ name: "Linting", category: "Code Quality", points: 4, maxPoints: 4, status: "pass", detail: `${findConfig(p, ["analysis_options.yaml"])} — Dart analyzer lints` });
+    }
+    else if (langs.has("python")) {
         // See [SCORE-LANGUAGE-AWARE]. Python linting is ruff/flake8/pylint, not eslint.
-        const pyLint = ["ruff.toml", ".ruff.toml", ".flake8", ".pylintrc", "tox.ini", "setup.cfg"].filter(l => existsSync(join(p, l)));
-        const pyproject = existsSync(join(p, "pyproject.toml")) ? readFileSync(join(p, "pyproject.toml"), "utf-8") : "";
+        const pyLintCfg = findConfig(p, ["ruff.toml", ".ruff.toml", ".flake8", ".pylintrc", "tox.ini", "setup.cfg"]);
+        const pyLint = pyLintCfg ? [pyLintCfg] : [];
+        const pyprojectRel = findConfig(p, ["pyproject.toml"]);
+        const pyproject = pyprojectRel ? readFileSync(join(p, pyprojectRel), "utf-8") : "";
         if (pyLint.length > 0 || /\[tool\.(ruff|flake8|pylint|black)\]/.test(pyproject)) {
             checks.push({ name: "Linting", category: "Code Quality", points: 4, maxPoints: 4, status: "pass", detail: pyLint[0] ?? "pyproject.toml" });
         }
@@ -1522,7 +1572,7 @@ export function scoreProject(dir) {
             checks.push({ name: "Linting", category: "Code Quality", points: 0, maxPoints: 4, status: "fail", detail: "Python project with no ruff/flake8/pylint config — add one" });
         }
     }
-    else if (lang === "other") {
+    else if (langs.has("other") && langs.size === 1) {
         checks.push({ name: "Linting", category: "Code Quality", points: 0, maxPoints: 4, status: "unknown", detail: "❔ No linting convention known for this project type — not assessed" });
     }
     else {

package/dist/cli.d.ts

@@ -10,7 +10,7 @@
  *   contextengine list-projects       Discover and analyze all projects
  *   contextengine list-learnings      List all permanent learnings
  *   contextengine save-learning        Save a learning (terminal fallback for MCP)
- *   contextengine score [project]     AI-readiness score (writes SCORE.md to each project)
+ *   contextengine score [project|path] AI-readiness score for one project (default: cwd; --all for fleet)
  *   contextengine audit               Run compliance audit across all projects
  *   contextengine help                Show this message
  */

package/dist/cli.js

@@ -10,7 +10,7 @@
  *   contextengine list-projects       Discover and analyze all projects
  *   contextengine list-learnings      List all permanent learnings
  *   contextengine save-learning        Save a learning (terminal fallback for MCP)
- *   contextengine score [project]     AI-readiness score (writes SCORE.md to each project)
+ *   contextengine score [project|path] AI-readiness score for one project (default: cwd; --all for fleet)
  *   contextengine audit               Run compliance audit across all projects
  *   contextengine help                Show this message
  */
@@ -517,7 +517,7 @@ async function runInit() {
 // ---------------------------------------------------------------------------
 // CLI Engine — shared initialization for all CLI subcommands
 // ---------------------------------------------------------------------------
-import { loadSources, loadProjectDirs, loadConfig } from "./config.js";
+import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot, looksLikePath } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -697,12 +697,34 @@ async function cliDeleteLearning(id) {
         process.exit(1);
     }
 }
-async function cliScore(project, html = false, save = true) {
+/**
+ * 🔒 LOCKED [SCORE-FLEET-IS-OPT-IN] — 2026-08-16
+ * ⛔ NEVER make a bare `contextengine score` iterate the whole fleet again, and never
+ *    let the no-argument path write SCORE.md anywhere but the resolved project root.
+ * WHY: `score` with no argument scored all 37 discovered projects AND wrote a SCORE.md
+ *      into every one of them. Three separate agent sessions ran it expecting to score
+ *      the repo they were standing in, and dirtied 26 unrelated repositories — several of
+ *      which auto-push to Google Drive on commit, so the noise propagated off-machine
+ *      before anyone noticed. The blast radius of the default was the entire fleet while
+ *      the intent behind typing it was almost always a single project.
+ * FIX: the destructive-at-scale operation must be *asked for*. `--all` opts in; no
+ *      argument scores the current working directory's project root. A fleet-wide write
+ *      is a deliberate choice, never a default the user backs into.
+ *      Note the MCP `score_project` tool is read-only (it never writes SCORE.md), which
+ *      is why its fleet-wide default is left alone — the hazard here is the write, not
+ *      the scan.
+ */
+async function cliScore(project, html = false, save = true, all = false) {
     const gate = gateCheck("score_project");
     if (gate) {
         console.error(gate);
         process.exit(1);
     }
+    if (project && all) {
+        console.error(`❌ Cannot combine --all with a project argument ("${project}").`);
+        console.error(`   Use --all for the whole fleet, or name one project/path.`);
+        process.exit(1);
+    }
     // [SCORE-CANARY] — every health signal must read exactly as pinned before we are allowed to
     // write a single SCORE.md. A drifting scorer that silently rewrites 37 reports is the failure
     // this blocks; it does not test for one known bug, it refuses to proceed on ANY deviation.
@@ -718,17 +740,69 @@ async function cliScore(project, html = false, save = true) {
     }
     const projectDirs = loadProjectDirs();
     let scores;
-    if (project) {
-        const dir = projectDirs.find((d) => d.name.toLowerCase() === project.toLowerCase());
+    if (all) {
+        if (save) {
+            console.error(`⚠️  --all: scoring ${projectDirs.length} projects and writing a SCORE.md into each.`);
+            console.error(`   Use --no-save to scan without writing.\n`);
+        }
+        scores = projectDirs.map((d) => scoreProject(d));
+    }
+    else if (project) {
+        // [SCORE-ACCEPTS-PATH] — a path is as valid an identifier as a name.
+        const dir = resolveProjectDir(project, projectDirs);
         if (!dir) {
-            console.error(`❌ Project not found: "${project}"`);
-            console.error(`Available: ${projectDirs.map((d) => d.name).join(", ")}`);
+            // Say which of the three failures actually happened. "Not found" for a
+            // directory that plainly exists is the same absence-as-verdict mistake
+            // [SCORE-ACCEPTS-PATH] was written to fix — do not reintroduce it here.
+            const abs = resolve(project.replace(/^~/, homedir()));
+            const exists = existsSync(abs);
+            const isDir = exists && statSync(abs).isDirectory();
+            if (!looksLikePath(project)) {
+                // A bare name that missed the fleet index. Deliberately NOT resolved as a
+                // relative directory — that is what silently scored ./src and ./dist.
+                console.error(`❌ Project not found: "${project}"`);
+                if (isDir) {
+                    console.error(`   A directory named "${project}" exists here, but it is not a`);
+                    console.error(`   project in your fleet. To score it anyway: contextengine score ./${project}`);
+                }
+                console.error(`Available: ${projectDirs.map((d) => d.name).join(", ")}`);
+            }
+            else if (!exists) {
+                console.error(`❌ No such directory: ${abs}`);
+            }
+            else if (!isDir) {
+                console.error(`❌ Not a directory: ${abs}`);
+            }
+            else {
+                console.error(`❌ Not a project: ${abs}`);
+                console.error(`   The directory exists, but has no .git, package.json, pyproject.toml`);
+                console.error(`   or other build file — so it looks like a container, not a project.`);
+                console.error(`   If you meant the projects INSIDE it, use: contextengine score --all`);
+            }
             process.exit(1);
         }
         scores = [scoreProject(dir)];
     }
     else {
-        scores = projectDirs.map((d) => scoreProject(d));
+        // [SCORE-FLEET-IS-OPT-IN] — no argument means "the project I am standing in",
+        // never "every project on this machine".
+        // [SCORE-CWD-MUST-BE-A-PROJECT] — and if I am not standing in a project, say so
+        // rather than scoring whatever directory happens to be here.
+        const root = findProjectRoot(process.cwd());
+        if (!root) {
+            console.error(`❌ Not inside a project: ${process.cwd()}`);
+            console.error(`   No .git or package.json found here or in any parent directory.`);
+            console.error(`   Do one of:`);
+            console.error(`     • cd into a project, then run: contextengine score`);
+            console.error(`     • name it:                     contextengine score <name|path>`);
+            console.error(`     • score the whole fleet:       contextengine score --all`);
+            process.exit(1);
+        }
+        const known = projectDirs.find((d) => resolve(d.path) === resolve(root));
+        const dir = known ?? { name: basename(root), path: root };
+        console.error(`📍 Scoring current project: ${dir.name} (${dir.path})`);
+        console.error(`   Use --all to score every discovered project.\n`);
+        scores = [scoreProject(dir)];
     }
     if (html) {
         const htmlContent = generateScoreHTML(scores);
@@ -2111,7 +2185,11 @@ Usage:
                                        Fetch community-contributed learnings (Tier A = GitHub
                                        public, Tier B = api.compr.ch Pro). Daily run recommended.
                                        Network failures fall back to cached store.
-  contextengine score [project] [--html] [--no-save] AI-readiness score (Pro, writes SCORE.md)
+  contextengine score [project|path] [--all] [--html] [--no-save]
+                                       AI-readiness score (Pro, writes SCORE.md).
+                                       No argument scores the CURRENT project only.
+                                       Accepts a project name or a directory path.
+                                       --all scores every discovered project (writes to each).
   contextengine audit                  Run compliance audit (Pro)
   contextengine activate <key> <email> Activate a Pro license
   contextengine deactivate             Remove license and premium modules
@@ -2195,8 +2273,9 @@ else if (command === "score") {
     const args = process.argv.slice(3);
     const htmlFlag = args.includes("--html");
     const noSaveFlag = args.includes("--no-save");
+    const allFlag = args.includes("--all");
     const project = args.filter(a => !a.startsWith("--"))[0];
-    cliScore(project, htmlFlag, !noSaveFlag).catch((err) => {
+    cliScore(project, htmlFlag, !noSaveFlag, allFlag).catch((err) => {
         console.error("Error:", err);
         process.exit(1);
     });

package/dist/config.d.ts

@@ -66,6 +66,19 @@ export declare function loadSources(): KnowledgeSource[];
  * Returns one entry per top-level project found.
  */
 export declare function loadProjectDirs(): ProjectDirectory[];
+/**
+ * Does this token look like a filesystem path rather than a bare project name?
+ *
+ * Deliberately conservative: only strings that CANNOT be a directory basename
+ * (they contain a separator, or start with `~`/`.`) are treated as
+ * path-only. Everything else stays eligible for name lookup first, so
+ * `score KONIVE.com` keeps resolving exactly as it did before this existed.
+ */
+export declare function looksLikePath(token: string): boolean;
+/** Does this directory carry any build/VCS marker that makes it a project? */
+export declare function hasProjectMarker(dir: string): boolean;
+export declare function resolveProjectDir(token: string, dirs: ProjectDirectory[]): ProjectDirectory | null;
+export declare function findProjectRoot(start: string): string | null;
 /**
  * Load the raw config (for checking flags like collectSystemOps).
  */

package/dist/config.js

@@ -1,4 +1,4 @@
-import { resolve, join } from "path";
+import { resolve, join, basename, dirname, sep } from "path";
 import { homedir } from "os";
 import { readFileSync, existsSync, readdirSync, statSync } from "fs";
 import { discoverClaudeMemory } from "./claude-integration.js";
@@ -188,12 +188,27 @@ export function loadProjectDirs() {
             workspaceDirs = config.workspaces.map((w) => resolve(configPath, "..", w.replace(/^~/, homedir())));
         }
     }
-    // Env var fallback
-    if (workspaceDirs.length === 0) {
-        const envWorkspaces = process.env.CONTEXTENGINE_WORKSPACES;
-        if (envWorkspaces) {
-            workspaceDirs = envWorkspaces.split(":").filter(Boolean);
-        }
+    /**
+     * 🔒 LOCKED [ENV-WORKSPACES-WINS] — 2026-08-16
+     * ⛔ NEVER demote CONTEXTENGINE_WORKSPACES back to a fallback that only applies when the
+     *    config file happens not to define `workspaces`.
+     * WHY: it WAS such a fallback (`if (workspaceDirs.length === 0)`), so on any machine with a
+     *      contextengine.json defining workspaces — which is the documented setup — the env var
+     *      was read, ignored, and never reported. Every MCP config block we ship in
+     *      skills/opscontext/SKILL.md sets `env: { CONTEXTENGINE_WORKSPACES: ... }`, so our own
+     *      documented integration silently did nothing.
+     *      Caught the hard way: an attempt to sandbox a review agent by pointing this variable at
+     *      a scratch directory was ignored, and `score --all` wrote SCORE.md into 28 real
+     *      repositories instead. The sandbox reported success because the variable was accepted
+     *      without complaint — absence of an error read as confirmation.
+     * FIX: standard precedence — an explicit env var beats a config file beats auto-discovery.
+     *      It is set per-invocation and is therefore the most specific statement of intent.
+     */
+    const envWorkspaces = process.env.CONTEXTENGINE_WORKSPACES;
+    if (envWorkspaces) {
+        const fromEnv = envWorkspaces.split(":").filter(Boolean);
+        if (fromEnv.length > 0)
+            workspaceDirs = fromEnv;
     }
     // Auto-discover fallback
     if (workspaceDirs.length === 0) {
@@ -227,6 +242,145 @@ export function loadProjectDirs() {
     }
     return dirs;
 }
+/**
+ * Does this token look like a filesystem path rather than a bare project name?
+ *
+ * Deliberately conservative: only strings that CANNOT be a directory basename
+ * (they contain a separator, or start with `~`/`.`) are treated as
+ * path-only. Everything else stays eligible for name lookup first, so
+ * `score KONIVE.com` keeps resolving exactly as it did before this existed.
+ */
+export function looksLikePath(token) {
+    return (token.includes("/") ||
+        token.includes(sep) ||
+        token.startsWith("~") ||
+        token === "." ||
+        token === "..");
+}
+/**
+ * 🔒 LOCKED [SCORE-ACCEPTS-PATH] — 2026-08-16
+ * ⛔ NEVER narrow this back to `dirs.find(d => d.name === token)` alone.
+ * WHY: `contextengine score /Users/yan/Projects/PLANK.io` failed with
+ *      "Project not found: /Users/yan/Projects/PLANK.io" while listing PLANK.io
+ *      among the available projects. A path is the natural first guess for a
+ *      tool that prints absolute paths in its own output, and the error named
+ *      the one thing the user had clearly just given it. The directory was
+ *      never inspected — the lookup only ever compared basenames, so this was
+ *      [ABSENCE-IS-NOT-A-VERDICT] at the argument-parsing layer: "not in my
+ *      name index" was reported as "does not exist".
+ * FIX: resolve names AND paths. A path that exists AND carries a project marker is a
+ *      project, whether or not it sits under a configured workspace — that is what makes
+ *      the tool usable outside `~/Projects`.
+ *
+ * 🔒 LOCKED [RESOLVE-PATH-MUST-BE-A-PROJECT] — 2026-08-16
+ * ⛔ NEVER accept "it is a directory that exists" as proof that a path is a project, and
+ *    NEVER let a bare name that missed the index fall through to path resolution.
+ * WHY: the first cut did both, and an adversarial review reproduced three consequences.
+ *      1. `cd ~/Projects && score .` wrote `~/Projects/SCORE.md` — "Projects: 27/100 (F),
+ *         Not a git repo" — into the CONTAINER of 37 repositories. The identical command
+ *         WITHOUT the `.` was correctly refused, so the guard existed and one entry point
+ *         walked straight past it. Same for `score ~/Projects`, `score ..`, and `score /`.
+ *      2. `score src`, `score dist`, `score docs` — a typo or a half-remembered name — no
+ *         longer errored with "Available: …". The bare token fell through to
+ *         `resolve(token)` against the cwd, so it silently scored a SUBDIRECTORY and wrote
+ *         a SCORE.md into it. In this repo `score dist` writes `dist/SCORE.md`, which then
+ *         ships inside the npm tarball.
+ *      3. It made the sibling LOCK a half-truth: [SCORE-CWD-MUST-BE-A-PROJECT] promises a
+ *         non-project is never scored, but enforced it on the no-argument path only.
+ * FIX: a directory must carry a build/VCS marker to be scoreable, and a bare name resolves
+ *      against the fleet index ONLY. Configured projects always pass — they are the fleet
+ *      by definition. Absence of a marker is a measurement, not permission to write.
+ */
+const PROJECT_MARKERS = [
+    ".git", "package.json", "pyproject.toml", "requirements.txt", "setup.py",
+    "composer.json", "pubspec.yaml", "go.mod", "Cargo.toml", "Gemfile",
+    "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
+];
+/** Does this directory carry any build/VCS marker that makes it a project? */
+export function hasProjectMarker(dir) {
+    return PROJECT_MARKERS.some((m) => existsSync(join(dir, m)));
+}
+export function resolveProjectDir(token, dirs) {
+    // A bare name resolves against the fleet index ONLY. It must never silently
+    // become a cwd-relative directory — that is how `score src` wrote src/SCORE.md
+    // instead of printing "Project not found. Available: …". Use `./src` to mean a path.
+    if (!looksLikePath(token)) {
+        return (dirs.find((d) => d.name.toLowerCase() === token.toLowerCase()) ?? null);
+    }
+    // Path resolution — absolute, relative, or `~`-prefixed.
+    const abs = resolve(token.replace(/^~/, homedir()));
+    try {
+        if (!statSync(abs).isDirectory())
+            return null;
+    }
+    catch {
+        return null; // ENOENT / EACCES — not a usable directory.
+    }
+    // A configured project is a project by definition, marker or not.
+    const known = dirs.find((d) => resolve(d.path) === abs);
+    if (known)
+        return known;
+    // Otherwise it must look like a project. `~/Projects` and `/` do not.
+    return hasProjectMarker(abs) ? { name: basename(abs), path: abs } : null;
+}
+/**
+ * 🔒 LOCKED [SCORE-CWD-MUST-BE-A-PROJECT] — 2026-08-16
+ * ⛔ NEVER fall back to returning `start` when no project marker is found. A directory
+ *    that is not a project must produce null, and the caller must refuse to score it.
+ * WHY: the first cut of this returned `start` on failure, reasoning that "an un-versioned
+ *      directory is still scoreable — it just scores badly." That is exactly the
+ *      absence-as-verdict mistake this codebase keeps relearning. Running `score` from
+ *      `~/Projects` — a CONTAINER of 37 projects, not a project — walked to the filesystem
+ *      root, found nothing, fell back, scored the container as though it were a project,
+ *      and wrote `~/Projects/SCORE.md` claiming "Projects: 27/100 (F)". Run from `/` it
+ *      would do the same to the filesystem root. "I cannot tell which project you mean" is
+ *      an unknown, and the safe response to an unknown scope is to ask, never to write.
+ * FIX: return null and let the caller error out with the three things the user can do
+ *      instead (cd into a project, name one, or --all). Found by an adversarial review
+ *      agent that ran the real CLI from `/` and `~/Projects`.
+ *
+ * 🔒 LOCKED [GIT-ROOT-IS-THE-PROJECT-BOUNDARY] — 2026-08-16
+ * ⛔ NEVER return the nearest `package.json` directory without first checking whether a
+ *    `.git` sits above it.
+ * WHY: stopping at the nearest marker meant `cd ContextEngine/server && score` reported
+ *      **"Scoring current project: server ... 32% (F) — Not a git repo, No CI pipeline,
+ *      README.md Missing"** and wrote `server/SCORE.md`. Every one of those statements is
+ *      false about the project the user is standing in: the repo root has `.git`, CI, and
+ *      a README. A build file marks a *package*; `.git` marks the *project*. Reporting
+ *      "Not a git repo" from inside a git repo is the scorer describing a boundary it
+ *      invented — absence-as-verdict again, this time about where the project ends.
+ * FIX: `.git` wins. Walk up looking for it, remembering the nearest build file on the way,
+ *      and fall back to that remembered directory only if no `.git` exists anywhere above.
+ *      A genuinely standalone package (no git anywhere) still resolves to itself.
+ *
+ * Walk up from `start` to the enclosing project root. Returns null when nothing is
+ * found anywhere above `start`.
+ */
+const BUILD_FILE_MARKERS = [
+    "package.json", "pyproject.toml", "requirements.txt", "setup.py",
+    "composer.json", "pubspec.yaml", "go.mod", "Cargo.toml", "Gemfile",
+    "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
+];
+export function findProjectRoot(start) {
+    let dir = resolve(start);
+    let nearestBuildFile = null;
+    for (;;) {
+        // .git is the project boundary and always wins, however far up it sits.
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        if (nearestBuildFile === null &&
+            BUILD_FILE_MARKERS.some((m) => existsSync(join(dir, m)))) {
+            nearestBuildFile = dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    // No .git anywhere above — a standalone package resolves to itself; a plain
+    // directory (a container, or /) resolves to nothing at all.
+    return nearestBuildFile;
+}
 /**
  * Load the raw config (for checking flags like collectSystemOps).
  */

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { loadSources, loadProjectDirs, loadConfig } from "./config.js";
+import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
@@ -474,7 +474,7 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
     project: z
         .string()
         .optional()
-        .describe("Project name to score. Omit to score all projects."),
+        .describe("Project name OR absolute directory path to score. Omit to score all projects."),
 }, async ({ project }) => {
     const gate = gateCheck("score_project");
     if (gate)
@@ -482,13 +482,15 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
     const projectDirs = loadProjectDirs();
     let scores;
     if (project) {
-        const dir = projectDirs.find((d) => d.name.toLowerCase() === project.toLowerCase());
+        // [SCORE-ACCEPTS-PATH] — resolve names and paths alike. This tool never writes
+        // SCORE.md, so unlike the CLI its fleet-wide default is harmless and is kept.
+        const dir = resolveProjectDir(project, projectDirs);
         if (!dir) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Project "${project}" not found. Available: ${projectDirs.map((d) => d.name).join(", ")}`,
+                        text: `Project "${project}" not found — not a known project name, and not an existing directory. Available: ${projectDirs.map((d) => d.name).join(", ")}`,
                     },
                 ],
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",

package/skills/opscontext/SKILL.md

@@ -14,7 +14,7 @@ ContextEngine turns your project documentation into a **queryable knowledge base
 ### 1. Initialize (one-time per project)
 
 ```bash
-npx @compr/contextengine-mcp init
+npx @compr/opscontext-mcp init
 ```
 
 Creates `contextengine.json` config + `.github/copilot-instructions.md` template in the current directory.
@@ -39,14 +39,16 @@ ContextEngine auto-discovers documentation files from 7 common patterns:
 ContextEngine also works as a standalone CLI tool — no MCP client needed:
 
 ```bash
-npx @compr/contextengine-mcp search "docker nginx"    # Search knowledge base
-npx @compr/contextengine-mcp list-sources              # Show indexed sources
-npx @compr/contextengine-mcp list-projects             # Discover all projects
-npx @compr/contextengine-mcp score                     # AI-readiness score
-npx @compr/contextengine-mcp score --html               # Visual HTML report
-npx @compr/contextengine-mcp list-learnings security   # List learnings by category
-npx @compr/contextengine-mcp audit                     # Compliance audit
-npx @compr/contextengine-mcp help                      # Show all commands
+npx @compr/opscontext-mcp search "docker nginx"      # Search knowledge base
+npx @compr/opscontext-mcp list-sources               # Show indexed sources
+npx @compr/opscontext-mcp list-projects              # Discover all projects
+npx @compr/opscontext-mcp score                      # Score the CURRENT project (writes its SCORE.md)
+npx @compr/opscontext-mcp score ~/Projects/PLANK.io  # Score one project by name or path
+npx @compr/opscontext-mcp score --all --no-save      # Score every project, write nothing
+npx @compr/opscontext-mcp score --html               # Visual HTML report
+npx @compr/opscontext-mcp list-learnings security    # List learnings by category
+npx @compr/opscontext-mcp audit                      # Compliance audit
+npx @compr/opscontext-mcp help                       # Show all commands
 ```
 
 ## MCP Server Setup
@@ -62,7 +64,7 @@ Add to `.vscode/mcp.json` in your project root:
   "servers": {
     "contextengine": {
       "command": "npx",
-      "args": ["-y", "@compr/contextengine-mcp"],
+      "args": ["-y", "@compr/opscontext-mcp"],
       "env": {
         "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
       }
@@ -80,7 +82,7 @@ Add to Claude Desktop MCP config:
   "mcpServers": {
     "contextengine": {
       "command": "npx",
-      "args": ["-y", "@compr/contextengine-mcp"],
+      "args": ["-y", "@compr/opscontext-mcp"],
       "env": {
         "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
       }
@@ -98,7 +100,7 @@ Add to your OpenClaw `openclaw.json` MCP servers section:
   "mcpServers": {
     "contextengine": {
       "command": "npx",
-      "args": ["-y", "@compr/contextengine-mcp"],
+      "args": ["-y", "@compr/opscontext-mcp"],
       "env": {
         "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
       }
@@ -186,7 +188,7 @@ load_session --name "project-x"
 
 ## Configuration
 
-Create `contextengine.json` in your project root (or run `npx @compr/contextengine-mcp init`):
+Create `contextengine.json` in your project root (or run `npx @compr/opscontext-mcp init`):
 
 ```json
 {
@@ -220,14 +222,14 @@ Create `contextengine.json` in your project root (or run `npx @compr/contextengi
 - First run downloads the embedding model (~22MB) — subsequent runs use cache
 - Keyword search is available instantly at startup; semantic search becomes available once the model loads
 - License: BSL-1.1 (Business Source License)
-- npm: `@compr/contextengine-mcp`
+- npm: `@compr/opscontext-mcp`
 
 ### Post-Commit Verification
 
 After every `git push`, call `end_session` to verify nothing was missed:
 
 - **MCP tool**: `end_session` — use when ContextEngine MCP server is connected
-- **CLI fallback**: `npx @compr/contextengine-mcp end-session` — use when MCP is not connected (Cursor, Copilot, terminal sessions)
+- **CLI fallback**: `npx @compr/opscontext-mcp end-session` — use when MCP is not connected (Cursor, Copilot, terminal sessions)
 
 Resolve any FAIL items before finishing. Workflow: `commit → push → end_session → verify → fix anything it catches → re-commit if needed`.