passwerk
README.md
# Passwerk
**Offline EU Battery Passport Compiler.**
Drop in a supplier's messy documents (BOMs, Excel exports, energy bills, supplier
declarations). Get back a conformant Digital Battery Passport in the official AAS format
(IDTA 02035-1 to -7) plus a legally cited gap report of what is still missing.
100 % offline. Zero API keys. Agent-agnostic: an MCP server for Claude Desktop, Claude Code,
Codex, Cursor and OpenCode, a scriptable CLI, a plain TypeScript library, and a client-side
web app with QR preview.
## Quick start
**Claude Desktop:** download `passwerk-<version>.mcpb` from the
[releases page](https://github.com/ShahriarBijoy/passwerk/releases) and open it. Claude Desktop
installs the server, asks for your document folder, and the twelve passwerk tools are ready
after a restart. Details in [docs/install/claude-desktop.md](docs/install/claude-desktop.md).
**Everything else:**
```sh
npx -y @passwerk/server # MCP server over stdio, offline, no keys
claude mcp add passwerk -- npx -y @passwerk/server
npx -y @passwerk/cli audit passport.draft.json
docker run -e PASSWERK_AUTH_TOKEN=$(openssl rand -hex 32) -p 127.0.0.1:3777:3777 ghcr.io/shahriarbijoy/passwerk
```
Host snippets for Codex, Cursor, OpenCode and plain HTTP are in [docs/install](docs/install).
The agent workflow (ingest, map, validate, fix, emit) is taught by the bundled skill in
[skills/passwerk](skills/passwerk/SKILL.md).
## Why
Regulation (EU) 2023/1542, Art. 77: from **18 February 2027** every EV, light-means-of-transport
and industrial >2 kWh battery placed on the EU market needs a Digital Battery Passport. The
passport is roughly 90 data points scattered across a supplier's ERP, spreadsheets and PDFs.
Every commercial platform sells to OEMs and Tier-1s. passwerk is the on-ramp for the Tier-2
and Mittelstand supplier who receives the data request and has no tooling to answer it.
Conformance is measured, not asserted. Every emitted golden passport is replayed through the
official `aas-test-engines` oracle on every CI run ([docs/CONFORMANCE.md](docs/CONFORMANCE.md));
the badge reports verdict parity with that oracle, expected failures included. Mapping quality
on unseen supplier documents is scored in [docs/EVALUATION.md](docs/EVALUATION.md). A
sovereignty test and a `--network none` Docker job prove zero network calls. None of this is a
certification of battery-passport compliance; the template (L3) and plausibility (L4) checks
are passwerk's own.
## Packages
| Package | Role |
|---|---|
| `@passwerk/rules` | Bundled, checksummed IDTA 02035 templates, AAS schemas, EC data-point matrix, attribute knowledge base (DE/EN), legal timeline |
| `@passwerk/core` | MCP-free library: ingest (PDF, XLSX, DOCX, CSV, TXT), extract, map, validate (4 layers), gap report, emit AAS JSON / AASX / HTML, data carrier (UID, GS1 Digital Link, QR) |
| `@passwerk/server` | MCP server over stdio and Streamable HTTP: twelve tools, reference resources, workflow prompts, and the workbench as an MCP App |
| `@passwerk/cli` | `passwerk audit \| extract \| emit \| gaps \| obligations \| carrier \| tools \| chat` with CI-friendly exit codes ([reference](skills/passwerk/references/cli.md)) |
| `@passwerk/web` | Client-side web app: project, documents, facts, review, gaps, export |
| `@passwerk/mcp-app` | The same workbench inside Claude Desktop's iframe, opened by `review_passport` |
`rules`, `core`, `server` and `cli` make no network call and no model call, ever. The two
exceptions are opt-in and bring-your-own-key: the web app's mapping assist, which only ever
sees labels and values and only ever names attributes, and the `passwerk chat` demo loop.
Point the assist at `http://localhost:11434/v1` and it runs against Ollama without a byte
leaving the building.
## Command line
The CLI runs the same tools as the MCP server, in-process and offline, with exit codes a CI
job can gate on (`audit`: 0 valid, 1 warnings, 2 invalid; `gaps`: 0 when no required data
point is open).
```sh
passwerk obligations --type EV --role manufacturer --placed-on-market 2027-06-01
passwerk extract ./supplier-docs --category EV --out facts.json
passwerk audit passport.draft.json
passwerk gaps passport.draft.json --lang de
passwerk emit passport.draft.json --out ./passport
passwerk carrier passport.draft.json --out passport.qr.svg
```
## Web app
`apps/web` runs the whole pipeline in the browser as six steps: project, documents, facts,
review, gaps and export. Documents never leave the browser; the autosave keeps your decisions,
facts and proposals in IndexedDB, never the uploaded files. Inside Claude Desktop the same
workbench runs as a fixed-height instrument in the host's iframe.
```sh
pnpm install && pnpm build
pnpm --filter @passwerk/web dev
```
## Development
Requires Node 22.13 or newer and pnpm 10.
```sh
pnpm install
pnpm check # lint + typecheck + test
pnpm build
pnpm oracle # replay golden passports through aas-test-engines (needs uv)
```
Contributor instructions for humans and coding agents live in `AGENTS.md`. Architecture and
scope are in `docs/BUILD_PLAN.md`, every non-obvious choice in `docs/DECISIONS.md`.
## Security and privacy
`PRIVACY.md` says what passwerk sends and stores, with the tests that enforce it: nothing
leaves the machine unless you switch on one of the two optional model features. `SECURITY.md`
says how to report a vulnerability privately and where the trust boundaries are, the document
parsers first.
## Not legal advice
passwerk cites the regulation and the standards it implements, but it is a tool, not a
lawyer. Every legal claim it emits carries its sources and an `isNotLegalAdvice: true` flag.
## License
Apache-2.0. See `LICENSE` and `NOTICE`. Bundled third-party artefacts are documented with
their sources, versions, checksums and licences in `packages/rules/PROVENANCE.md`.
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessUnresponsive