How to run it, and what every answer means.

01What this is

Two tools that read construction documents

The contract engine reads a subcontract you are already bound by. It compiles every clock, gate, threshold and forfeiture the contract imposes, then flags the clauses that will cost you money.

The tender intake reads a tender you have not bid yet. It pulls the dates, the requirements, the bill and the terms, and drafts a proposal with every gap marked.

Installed on your own machine, both run there entirely. Nothing is uploaded, nothing is sent anywhere, and neither tool needs a network connection once installed. The hosted console is the same software on a server in Riyadh: you sign in, the file goes to that server over an encrypted connection, and it is read there.

02Installing it

Two steps, about five minutes

1. Install Node

Node version 18 or newer. Download it from nodejs.org, take the LTS option, accept every default. Check it worked by opening a terminal and typing:

node --version

Anything from v18 upward is fine.

2. Unzip the package

Put the folder wherever you keep working files. There is nothing to install and no administrator rights are needed. The tool has no dependencies at all, so there is no npm install step and nothing is fetched from the internet.

Optional, for PDF files

Reading PDFs needs Poppler, which provides pdftotext and pdfinfo. Word, Excel, HTML and text files are read natively and need nothing.

03Starting it

Double click, and it opens

Double click Kontra+ in the folder. It checks that Node is present, finds a free port, starts the engine and opens the screen in your browser. The first time you run it, it also puts a Kontra+ shortcut on your desktop, so from then on it behaves like any other program.

Closing the black window stops it. Nothing keeps running in the background and nothing is installed.

Prove it works before you trust it with anything

Open a terminal in the folder and run these two commands.

npm test
npm run demo

npm test runs 527 checks: the contract engine and the tender intake against a contract that ships with the software, the knowledge base against the clause records and the statute library, and the register against published contracts the engine had never seen. It should finish with all green. If it does not, stop and read Troubleshooting rather than continuing.

npm run demo prints a full analysis of that same contract. It is a deliberately one sided fit-out subcontract written for this purpose, with every party and figure invented. Read the output once before you put a real contract through it, so you know what a complete result looks like.

04Reading a contract

One command, one or more files

node src/cli.js "conditions.pdf" "appendix.docx"

To keep the result as data rather than text:

node src/cli.js "contract.pdf" --json --out profile.json

Accepted formats: .pdf, .docx, .xlsx, .html, .txt, .eml.

05Reading the report

Six blocks, in the order they matter

Provenance

Whether this is the signed contract. NOT_EXECUTED means blanks or signature lines remain, which is normal for a contract under review. The plan still compiles, but no clause verdict is presented as settled.

Document type

Whether it reads as a contract at all, with a confidence percentage. Below about 50 per cent, treat everything after it as unreliable.

Commercial terms

Retention, advance, performance security, mark up, caps and periods, each with a confidence marker.

Payment milestones

The schedule and whether it closes at 100 per cent. A schedule that does not sum to 100 means a stage is missing or misread.

Compliance plan

Read the forfeiture register first. It is the short list of ways to lose a claim on the calendar rather than on the facts.

Risk register

Each finding carries the sentence quoted from the contract, what it means in money, and the amendment to ask for. The verdict is set by how many critical findings there are.

The last one is not a pass. It usually means the document is not a construction subcontract, so the patterns do not apply.

06Tracking a live event

The part that saves the claim

A compliance plan is only worth having if something runs against it. Feed the plan an event and it returns every obligation that event opened, which are still live, which were missed, and which of the misses destroyed an entitlement.

node test/eot-scenario.js

That runs the worked example on the demo contract. It prints the same delay event twice, side by side.

Same event, same contract, same facts. The difference is a notice served on time.

When an obligation has been missed, the engine returns salvage routes rather than stopping: serve it late anyway, check when the clock actually started, check whether the same failure affects the main contractor upstream, and move the value to a route that has not expired.

To run it against your own contract, pass the file:

node test/eot-scenario.js "your-contract.pdf"

07Reading a tender

Before you commit to bidding

node src/rfp/cli.js "tender files..."

Pass the whole pack together: the instructions, the scope, the bill, the draft conditions and every addendum. They are one tender. Excel bills are read natively.

You get the submission clock with everything ambiguous flagged, the requirements with the disqualifying ones separated, the bill read back, the terms that will cost you, and a drafted proposal with every gap marked rather than invented.

08The interface

For people who do not use a terminal

Double click Kontra+, or run it from a terminal:

npm start

The console has two screens, switched from the header.

Once a contract is read, the header carries the project name and the subcontract number, and the page opens on the project overview: the engine verdict, the traps by tier, the next notice deadline, the forfeiture clocks and the number of rules compiled. Below it sit six tabs.

Two things on the screen are yours, not the engine's. Type the contract value into the money terms and the console works out what retention, security and the delay damages cap come to in riyals. Enter an event date in Clocks and it dates the deadlines that event opened, in calendar days, so check the contract's own definition of a day. Both are kept in your browser only and come back when you reopen the same subcontract.

09When it refuses

A refusal is a result, not a failure

10What it cannot do

Stated plainly, so nothing surprises you

• Scans need the opt in reader. A scanned signed contract with no text layer is refused. On the command line, --ocr=local reads it on this computer with a vision model running in LM Studio, so nothing leaves the machine; it takes about a minute and a half a page. --ocr instead sends the page images to an outside transcription service, so it is off unless you ask for it. The console uses neither. Numerals inside stamps and handwriting are the weak points of both.
• Party and appendix extraction is narrow. It reads specific subcontract conventions. On documents written to other conventions those fields come back empty rather than wrong.
• It is one machine, one operator. There are no accounts, no roles and no shared history.
• It does not store anything. Output is files and terminal, or the page in your browser. There is no record of who ran what.
• It is not legal advice. It reads what the document says and tells you what it will do to you. Whether to sign is a commercial and legal decision.

11Troubleshooting

The five things that actually go wrong

If npm test does not finish green on a clean copy, do not use the output for anything. Report it with the failing test names.

12Command reference

Everything, on one page