@cejel/cejel 0.1.3 → 0.1.4

package/README.md

@@ -41,14 +41,15 @@ product, and you can falsify it in ten seconds:
 docker run --rm --network=none -v "$PWD:/w" -w /w -v "$PWD/cejel:/cejel:ro" debian:stable-slim /cejel .
 ```
 
-**npm.**
+**npm (scoped package).**
 
 ```bash
-npx @cejel/cejel .
+npx --yes --package @cejel/cejel cejel .
 ```
 
-> **On the name.** npm rejects the unscoped `cejel` package name as too similar to an
-> existing package (`level`). The published package is the scoped `@cejel/cejel`.
+The package is published under the `@cejel` scope while the unscoped name is under npm
+registry review. The installed executable remains `cejel`. For a global install, run
+`npm install --global @cejel/cejel`, then invoke `cejel .`.
 
 **GitHub Action** — score every PR and publish the badge:
 
@@ -70,6 +71,49 @@ Released binaries: `cejel-Darwin-arm64`, `cejel-Linux-x86_64`. A Homebrew tap an
 remaining architectures are in progress; they are not listed here because they do not exist
 yet.
 
+## Leaderboard
+
+This repo ships the [Cejel OSS trust leaderboard](./leaderboard/leaderboard.md): the whole
+corpus scored and published in the open — elite OSS projects, Cejel itself, and the private
+studio monorepo Cejel was built inside — with a per-repository evidence report for every
+row under [`leaderboard/reports/`](./leaderboard/reports/). The board is also hosted at
+[cejel.dev](https://cejel.dev). Every score on this board is produced by the same sealed
+public scorer used by `npx cejel .` — check out the source commit printed in the
+report, run the tool, and you will get this number. A required guard does exactly that for
+every corpus row and compares score, verdict, measured coverage, and evidence. No private
+domain collector contributes to any published score, ours included; nobody is exempt.
+
+### Redaction policy
+
+A path is published exactly when the reader can check it. Every public repository on the
+board cites full evidence paths and line numbers, everywhere, in every artifact — a
+certificate whose evidence you cannot open is not evidence. The two private-repository
+entries (this monorepo's own transparency entry, and Cejel's own source sub-package inside
+it) never cite a source path, anywhere, in any field or format — but the finding itself, its
+dimension, status, score, and content hash always survive; only the location is withheld,
+marked uniformly as "path withheld — private repository". Redaction removes a location, never
+a fact: a private repository failing its own check still shows up on its certificate, by
+name. The v3 repository scanner marks B1 and B5 not applicable for every repository,
+including ours; it does not accept structured substrate evidence for them. They remain
+defined for other rubric inputs, while the repository ranking excludes them fail-closed.
+Nobody is scored on evidence the public scanner cannot collect.
+
+### Known false positives (fixed before publishing)
+
+Calibrating a rubric against real, elite repositories surfaces mistakes; the record is part
+of the trust claim, not something to bury. Two dimensions produced a punitive score for the
+*absence* of a ratable surface rather than a real weakness, and both are fixed:
+Django was flagged critical on dependency hygiene for using version ranges instead of exact
+pins — normal, deliberate practice for a library, not an app; the rubric now scores
+dependency hygiene against archetype-appropriate norms. OSSF Scorecard — Google's own
+supply-chain security auditing tool — was flagged critical on audit-trail completeness for
+publishing release notes via GitHub Releases instead of a committed `CHANGELOG.md`; a
+repository with no ratable audit surface now returns "insufficient data" (excluded from the
+composite) instead of a punitive score. The board also publishes a measured-coverage
+indicator per row: a score reflects only its *measured* dimensions, and a row scored on fewer
+than half of its applicable dimensions is shown as unranked rather than ordered against
+better-evidenced rows.
+
 ## Usage
 
 ```bash
@@ -80,11 +124,18 @@ Scores the current directory with sensible defaults: no flags, no signup, fully
 Prints a concise terminal certificate and writes to `.cejel/`:
 
 - `report.json` — the full structured report
+- `attestation.json` — an unsigned in-toto statement binding the report digest, repository
+  revision, rubric, and scored-or-abstained outcome; ready for an external signer
 - `certificate.html` — a self-contained HTML certificate (no external assets)
 - `badge.json` — a [shields.io endpoint](https://shields.io/badges/endpoint-badge) payload
 - `badge.svg` — a static, self-contained trust-score badge
 - `summary.json` — a compact digest (score, verdict, top findings)
 
+The attestation is deliberately explicit about its assurance level: Cejel creates the
+statement, but it does not pretend to be an independent signer. Until a customer, reviewer,
+or provenance system signs it, `assurance.status` is `unsigned` and `issuer` is
+`self-generated`. An abstained scan carries only the refusal reason, never a numeric score.
+
 ### Flags
 
 - `<path>` — repo to score (default: current directory)
@@ -227,7 +278,7 @@ Add it to an MCP client config:
   "mcpServers": {
     "cejel": {
       "command": "npx",
-      "args": ["-y", "--package=@cejel/cejel", "cejel-mcp"]
+      "args": ["-y", "--package=cejel", "cejel-mcp"]
     }
   }
 }
@@ -238,9 +289,9 @@ The server exposes one tool and two resources:
 - `scan` — input `{ path, format? }`; scores the repository at `path` and returns the trust
   cert as JSON (`format: "summary"`, the default, is the compact digest; `format: "json"` is
   the full report, identical to the CLI's `report.json`).
-- `cejel-cejel://last-scan/certificate.html` and `cejel-cejel://last-scan/badge.svg` — the
+- `cejel://last-scan/certificate.html` and `cejel://last-scan/badge.svg` — the
   HTML certificate and SVG badge for the most recent scan (the URI scheme derives from the
-  npm package name, `@cejel/cejel` → `cejel-cejel`).
+  npm package name).
 
 Like the CLI, scoring over MCP is fully offline: no network calls, no telemetry, no signup,
 and the server writes no files.
@@ -248,10 +299,24 @@ and the server writes no files.
 ## What "offline" means here
 
 Scoring a repo — `cejel .` itself, and the Action's scoring step — makes zero network
-calls: no telemetry, no signup, no model call. Fetching the `@cejel/cejel` package the
+calls: no telemetry, no signup, no model call. Fetching the `cejel` package the
 first time (like any npm-distributed CLI, including this Action's own dependency install)
 does need network; that's a one-time install cost, not part of the scoring guarantee.
 
+## Help validate Cejel
+
+Cejel does not collect telemetry. External validation is therefore opt-in and inspectable:
+
+- [Report a calibration result](https://github.com/BargLabs/cejel/issues/new?template=calibration.yml)
+  when a score, finding, evidence pointer, or refusal is wrong. The form asks permission before
+  a correction is added to the public error ledger.
+- [Join a pack design-partner pilot](https://github.com/BargLabs/cejel/issues/new?template=pack-interest.yml)
+  for the Quant or Healthcare Pack. Both remain pilot surfaces until their domain-specific
+  calibration gates pass.
+
+Submit only public or redacted evidence. Never put credentials, proprietary strategy code,
+patient data, or protected health information in a GitHub issue.
+
 ## The public leaderboard: what we redact, what we exclude, and where we were wrong
 
 We publish a trust board scoring a corpus of well-known open-source repositories alongside