Trades-Runtime

Private TypeScript runtime for a shadow-first AI operating system / company operating intelligence layer. Field trades: HVAC, plumbing, electrical, sewer, and cross-trades.

Author / identity: Aziel Eliab only. See IDENTITY.md. No legal name, home, or county on exports.
Version: 1.0.0 (Local Softwares 1.0, installable)
Role: trades-runtime
License: Apache-2.0
Release: free software (Apache-2.0). Clone it and run the local shadow on your machine. Aziel Eliab is the author, not the operator, and is not running a company pilot.
Public Worker (if deployed): https://trades-runtime.vibelock.workers.dev
Try on Glama (intended listing): https://glama.ai/mcp/servers/AzielEliab/trades-runtime — pack is in-repo (glama.json, Dockerfile, cli/mcp-stdio.mjs). Do not treat Install Server as LIVE from this git tree alone. Checked 2026-10-02: Glama Latest/releaseVersion is 1.0.0-local. The public badge is still 1.0.0-local and does not match the in-repo Softwares cite tip 1.0.0. Catch-up pending. The Official MCP Registry still measures 1.0.0-local. This cut does not republish it. Local Softwares 1.0. That gap is not a Field 1.0 claim and not Office Softwares 1.0. This cut does not Make Release. See docs/GLAMA.md.
Status: 1.0.0 installable Local Softwares 1.0 (Track L gate; pilot not started; live_backends false; not a Field 1.0 claim) — 0.4.12 familiar commands (help, softwares, version, health) so a person can discover the product without reading the whole README; desk features stay frozen (pilot not started) — 0.4.11 giveaway human UI on the VibeLock Worker (browser / PWA) without downloading first; optional counted pack; operator desk still local (pilot not started) — 0.4.10 local time tracking, service-coverage switches, and right-tech suggestions on the Monitoring desk (pilot not started) — 0.4.9 local inbound quality report for ServiceTitan and ProBooks fragments, alert-to-action stubs with refused write-back, and an Option C start-gate prep panel (pilot not started) — 0.4.8 local miles driven and drive performance, a ranked employee and department performance board, work-together suggestions across departments, and an employee friction rate beside that board (pilot not started) — 0.4.7 part cost with regional market adaptation, per-tech trainingNeeded, good and bad department behavior flags, and local truck counts (pilot not started) — 0.4.6 per-call classify reasons, callback / warranty / not-classified filters, a loopback weekly callback-rate digest, and a tech morning huddle (pilot not started) — 0.4.5 local callback and warranty counts, alert-digest export, score explanations, and booking-block receipt (pilot not started) — 0.4.4 local operator desk polish (theme, lane view, printable snapshot; pilot not started) — 0.4.3 Option C BYO pilot prep (local runbook + npm run pilot:prep; pilot not started) — 0.4.2 local alert rules on the operator desk — 0.4.1 named trades-app vendor profiles on the 0.4.0 universal drop-in — lockstep with Property Intelligence v1.0 in-tree — live-pure core + honest stubs — BYO local ServiceTitan + ProBooks + trades-app inbound — no live writes, tenant data, ST/ProBooks write-back, phone-home, DOIs, hosted uploader, or production company-OS claim — Option C code-ready / pilot not started — Option D not started

The product is the software in src/. docs/ is a thin local catalog/UI. GitHub Pages is intentionally disabled (live_backends: false). There is no Pages workflow. PDFs are never published. Implementer specs live at repo-root specs/ (not under docs/).

Standing rule: every PDF Aziel sends is a spec to implement as coded software.

Paper trail: TR-1.0-GATE-2026-09-28 (Track L Local Softwares 1.0 gate; pilot not started) · TR-COMMANDS-2026-09-27 (common CLI commands help, softwares, version, health; desk frozen; pilot not started) · TR-OPS-2026-09-27 (local time tracking, coverage switches, right-tech suggestions; pilot not started) · TR-DESK-VIEW-2026-09-27 (local show/hide checkboxes; Softwares card grids unchanged; pilot not started) · TR-MOBILE-DESK-2026-09-27 (phone-width local desk; Softwares cards unchanged; pilot not started) · TR-QUALITY-2026-09-27 (inbound quality, alert-action stubs, Option C start gate; pilot not started) · TR-DRIVE-2026-09-27 (miles driven, drive performance, ranked employee and department board; pilot not started) · TR-SOFTWARES-2026-09-27 (part cost and market adaptation, trainingNeeded, department behavior flags, local truck counts; pilot not started) · TR-HUDDLE-2026-09-26 (per-call classify reason, call filters, weekly callback rate, morning huddle; pilot not started) · TR-CALLS-2026-09-26 (callback and warranty counts, alert digest, score why, booking-block receipt; pilot not started) · TR-DESK-POLISH-2026-09-25 (local desk polish; pilot not started) · TR-OPTION-C-PILOT-RUNBOOK-2026-10-02 (human Option C start path; catalog pilot not started) · TR-PILOT-START-2026-10-02 (explicit pilot:start --branch on the operator isolate; not Field 1.0; not Office Softwares 1.0) · TR-OPTION-C-PREP-2026-09-25 (Option C box prep; pilot not started) · TR-ALERTS-2026-09-25 (local alert rules) · TR-VENDOR-2026-09-25 (named vendor profiles) · TR-DESK-2026-09-25 (universal drop-in + local human desk) · TR-AUDIT-2026-09-18C · TR-AUDIT-2026-09-18B · TR-AUDIT-2026-09-18 · TR-AUDIT-2026-09-17 · TR-CUT-2026-09-17 · TR-BOT-2026-09-17 (standing brief) · TR-BYO-2026-09-17 (amends TR-BOT §9 and TR-CUT R2–R3).

Try it on your machine

Merging this repository does not start a pilot. Aziel Eliab wrote the software. He is not the operator, he is not a customer, and he is not running a shop on this repo. live_backends stays false. There is no write-back. A fresh clone needs no ServiceTitan or ProBooks tenant and no secrets.

git clone https://github.com/AzielEliab/trades-runtime.git
cd trades-runtime
npm install
npm test
npm run demo
npm run shadow:office
npm run shadow:field
npm run desk

What you will see:

• npm run demo prints a synthetic shadow day in the terminal. It is a fixture. It is not a company result and it does not print an accuracy percent.

• npm run shadow:office runs the office shadow on the sample branch named sample-shop. Fixtures are already in test/fixtures/sample-branch/office/. The receipt says office_softwares_1_0: false, pilot_started: false, and live_backends: false. You will see admitted sample jobs, a huddle count, inbound quality as a checklist, and alert stubs that refuse write-back. That command does not load field flags.

• npm run shadow:field runs the field shadow on the same sample branch, from test/fixtures/sample-branch/field/. You will see local flags (needsParts, safetyHold, vanDown, and a row that names a label without a van, which does not invent a van), a time card, coverage places, and a right-tech suggestion. field_softwares_1_0 is false. It is not a live GPS feed and not Field 1.0. It is a separate command from the office shadow.

• npm run desk opens the local desk at http://127.0.0.1:4174/ . With empty inbound folders the page is labeled synthetic demo. It is not your company and not a live tenant. Dropping your own exports into data/inbound/ is optional and stays on your machine.

When you have a real branch on your own machine, and only then:

npm run pilot:prep
npm run pilot:start -- --branch <branchId>

That is the only software path that sets pilot_started true, and it does it on your isolate only. It refuses a missing or bad branch, prep that is not ready, and --claim-company when inbound is empty or only synthetic. The shipped catalog stays pilot_started false. Mode stays SHADOW-SEALED. Writes require operator approval; default off. The receipt is not a live company OS, not Office Softwares 1.0, and not Field 1.0.

Related MCP server: NeuroLink

Install, test, demo

npm install
npm test
npm run typecheck
npx tsx src/cli.ts help
npx tsx src/cli.ts softwares
npx tsx src/cli.ts version
npx tsx src/cli.ts health
npm run demo
npm run byo:admit-demo
npm run drop-in:demo
npm run desk
npm run shadow:office
npm run shadow:field
npm run pilot:prep
npm run pilot:start -- --branch <branchId>
npm run health:local
npm run shadow:sealed-demo
npm run manifest
npm run mcp

help prints the command list (--help and -h do the same). softwares lists each module's slug, status, and one line in plain language (Softwares matches in any letter case). version prints the product name and version, then one honesty line: live_backends false, pilot_started false (--version and -V do the same). health is the same local honesty card as health-local. An unknown command prints that it is unknown, then the help text, and exits non-zero. No command still prints help and exits zero.

npm test runs constitutional rule tests including Human Authority, confidence≠truth, CrossTrade secondary-only routing, v0.2 recognition / pricebook lock / mission board / location economics, the 0.3.3 execution spine (FragGate inbound, durable receipts, runAction), restart-replay of append-only JSONL receipts (data/receipts.jsonl or {tmpdir}/tr-replay-*/receipts.jsonl), the synthetic BYO admit demo, the universal drop-in demo, the local operator desk, Option C sealed-shadow scaffolding (no auto-promote, engagement drop-back, required settlement fields), and Option C pilot prep (machine checks, synthetic admit, desk boot, pilot_started: false).

CI (.github/workflows/ci.yml) runs npm ci, npm run typecheck, and npm test on pull requests and pushes to main. GitHub Pages is intentionally disabled — do not treat a github.io URL as a test gate.

npm run demo runs a synthetic shadow-day: Call-Fit, sealed counterfactual, human override, hash-chained receipts, trajectory rebase.

Software map

Approval-gated writes

Writes require operator approval; default off.

Every write the runtime can make from a tool call or action goes through one gate, src/approvals/gate.ts. Nothing writes without an approval.

1. A write tool call creates a pending approval request that lists the tool, the target, and a payload summary. Nothing is written yet.

2. A local human operator answers yes or no, either in the Write permissions and approvals panel on the loopback desk (http://127.0.0.1:4174/#approvals-board) or from a terminal:

   npm run approvals                 # list pending requests
   npm run approve -- <id> yes       # run that one call once
   npm run approve -- <id> no        # refuse it; the refusal is recorded

3. A yes runs that one call once. Approvals are single-use. A pending request expires after approvalTtlSeconds (default 900). An expired approval fails.

4. Every request, refusal, decision, expiry, and result is appended to data/runtime/<instanceId>/approvals.jsonl. That file is a hash chain built on the existing durable receipt store (src/spine/durable-receipts.ts). Credentials are never written to it.

5. The requester can never approve its own request. The local MCP has no approve or deny tool. The desk's approve/deny and settings endpoints are loopback only. They need the per-process desk token embedded in the desk page, refuse any request that carries an mcp-session-id, and refuse cross-origin browser requests.

Permission settings

The settings live in the desk panel, in data/runtime/<instanceId>/permissions.json (copy data/runtime/permissions.json.example), and in npm run permissions.

autoApprove is off by default and only works in all mode. In selected mode it is ignored. With it on, enabled writes run without a per-call yes or no, and each one is still logged.

npm run permissions                                        # show current settings
npm run permissions -- --enable field_events.write         # selected mode: turn one on
npm run permissions -- --disable field_events.write
npm run permissions -- --mode all                          # every permission on, still asks per call
npm run permissions -- --mode all --auto-approve on        # no per-call prompt (off by default)

Each permission maps to one real write path in this repo:

A permission that is off returns a clear refusal, and that refusal is logged.

The desk's own buttons, such as job price, clock events, flags, coverage switches, and alert acknowledge, are the operator acting directly on this machine, so they don't go through the gate. The gate covers tool calls and agent actions.

Write-back backends and credentials

No backend and no credential ship in this repo. live_backends stays false in the committed catalog. A ServiceTitan, ProBooks, or trades-app write-back runs only when both of these are true:

• the operator wrote data/runtime/<instanceId>/write-backends.json on their own machine (copy data/runtime/write-backends.json.example). It holds an https baseUrl and the name of an environment variable, never the secret itself. Inline tokens are refused.

• the operator approved that one call.

Otherwise the call returns no-backend-configured and writes nothing. A vendor error is reported as vendor-error. Neither one is ever turned into a success. The request shape (method, path, body) is passed to the vendor as given. This repo has not been tested against a live ServiceTitan or ProBooks tenant.

Local MCP

npm run desk also serves JSON-RPC MCP at POST http://127.0.0.1:4174/mcp, loopback only. A stdio client can bridge to it:

TRADES_RUNTIME_URL=http://127.0.0.1:4174 npm run mcp

In tools/list, write tools carry requiresApproval: true, their permission, and permissionEnabled. Calling one returns { "status": "pending", "approvalId": ... }, or a refusal when the permission is off. trades_runtime_approvals_list and trades_runtime_approval_status are read-only. The public giveaway Worker (trades-runtime.vibelock.workers.dev) stays read-only. It holds no tenant data, so it has nothing to write.

This does not claim Field 1.0 or Office Softwares 1.0, and it does not start a pilot. pilot_started stays false.

BYO inbound (TR-BYO-2026-09-17)

Each user incorporates their own ServiceTitan and their own ProBooks into their local runtime. The authoring node / GitHub is not a data custodian. No central dump. No hosted uploader. No phone-home.

Local inbound on that machine (contents gitignored):

• data/inbound/servicetitan/ — ST export or read-only pull the user places

• data/inbound/probooks/ — ProBooks books / items / costs / vendor files the user places

• data/inbound/trades-app/ — other field-service / job / pricebook / customer / appointment exports. Named profiles: Jobber, Housecall Pro, Service Fusion, QuickBooks-shaped books, ServiceM8, AccuLynx, SuccessWare, Xero, FieldEdge, ServiceTrade. Generic CSV/JSON when no fingerprint matches.

• data/runtime/<instanceId>/receipts.jsonl and ledger.jsonl — isolate per runtime instance

Not data/tenants/ (that word implies a hosted multi-tenant service). Optional local config lists paths or read-endpoint hints only — no cloud account, and the runtime does not call those hints. Tokens stay on the user’s machine or their sealed vault.

FragGate first-class sourceKind values: servicetitan (MEDIUM, hashed, live:false write:false), probooks (same), trades-app (same, generic class), operator-file (LOW until origin tagged servicetitan, probooks, or trades-app; still not truth), human (manager correction on Chain C with actor id). Wrapper ≠ verified. Scrape, central-dump, hosted-upload, and silent promotion to VERIFIED are refused.

Universal drop-in (TR-DESK-2026-09-25)

ServiceTitan and ProBooks stay named peer classes. A third inbound class, trades-app, admits the same family of exports without a new paper for each vendor. The drop-in sniffs JSON/CSV shape and applies a mapping profile. 0.4.1 prefers a named profile when keys, headers, or the filename match: Jobber, Housecall Pro, Service Fusion, QuickBooks Online, QuickBooks Desktop, ServiceM8, AccuLynx, SuccessWare, Xero, FieldEdge, and ServiceTrade. Otherwise it uses generic JSON or generic CSV. A file that still looks like ServiceTitan or ProBooks stays on that peer class. ServiceM8, SuccessWare, and ServiceTrade files are now admitted through their platform connectors, so each of those has one path (see data/inbound/README.md). See TR-VENDOR-2026-09-25.

npm run drop-in:demo

That demo copies synthetic fixtures from test/fixtures/byo/ into a temp inbound tree, admits them through FragGate, hashes packets, writes temp isolate receipts, and proves writes still throw. It is not a customer dump.

Real exports stay in the gitignored drop folders. data/inbound/local.json (copied from local.json.example) may name paths and read-endpoint hints. Hints are documentation for the operator. This process does not fetch them.

Platform peers (TR-PLATFORMS-2026-10-19)

Jobber, Housecall Pro, Square, QuickBooks Online, FieldEdge, Service Fusion, and (wave 2, TR-PLATFORMS-2-2026-10-19) Successware, Workiz, ServiceTrade, BuildOps, FieldPulse, Kickserv, mHelpDesk, ServiceM8, Simpro, Commusoft, and Wintac are first-class inbound peers. Successware was named by the owner. The other ten were picked from public research (Software Advice 2026 plumbing list, an independent HVAC dispatch ranking, vendor developer docs), not usage data. No market share is claimed. The reasons and sources for each are in src/spine/platforms/catalog-wave2.ts. Each one has its own folder, data/inbound/<kind>/. Drop a JSON or CSV export into that folder, and it is mapped to the vendor's documented object names, then admitted as MEDIUM, unverified, live: false.

You can also pull data yourself with npm run pull -- <platform>. This is a read-only call against the vendor's documented public API. The env var that holds the token is named in data/inbound/local.json. No credential is kept in the repo, in Pages, or in the Worker.

Each platform also carries a mapping confidence: documented, partial, or guessed. Documented: FieldEdge, Workiz, ServiceTrade. Partial: FieldPulse, Kickserv, mHelpDesk, Simpro, and the platforms not re-checked in this pass. Guessed: Successware, BuildOps, Wintac. The desk platform list shows which mappers need a real shop export to confirm. Sources and details are in data/inbound/README.md.

Shop exports are supplied by each shop; none ship in this repo. Drop your own export into data/inbound/<kind>/, then run npm run mapping:check -- <kind> <file>. It reports the matched, unmatched, and missing required fields and writes a starter override to data/runtime/<instanceId>/mappings/<kind>.json. That file is local and gitignored, and it wins over the built-in mapper. Guessed mappings are confirmed by your export, not by this repo. See "Your own export" in data/inbound/README.md.

All of this is tested against fixtures only. Not tested against a live tenant. Each platform's <kind>.writeback goes through the approval gate. It is off by default and asks yes or no on every call. When no backend is configured, it returns no-backend-configured. It never reports a success that didn't happen. Run npm run platforms to list them.

Local compliance, revenue, and ops modules (TR-MODULES-2026-10-19)

Each module reads a local file, data/runtime/<instanceId>/<module>.json (gitignored; examples in data/runtime/*.json.example), plus whatever admitted inbound rows already carry the data. Each one has a desk panel on http://127.0.0.1:4174/, a JSON route, and a read tool on the local MCP. Writes need their own permission and a yes from the operator on each call.

Refrigerant rules, as read on the eCFR on 2026-10-19:

• The leak rate is calculated per 40 CFR 82.152.

• Section 608 leak repair covers ODS refrigerant at a full charge of 50 lb or more (40 CFR 82.157).

• The AIM Act rule covers HFC refrigerant at a full charge of 15 lb or more, from 2026-01-01. It excludes residential and light-commercial AC (40 CFR 84.106).

• Trigger rates are 20% for commercial refrigeration, 30% for industrial process, and 10% for comfort cooling and other appliances.

This is a record-keeping aid. It is not an EPA filing and not legal advice.

The modules never estimate a number:

• Revenue at risk uses only prices the shop supplies: a price on each agreement, or an optional plan price list (settings.planPrices). An agreement without either is counted as price unknown. The example prices are synthetic placeholders.

• Warranty filing windows show up only when the shop enters them.

• A van that was never counted is unknown, not zero.

• A callback links to its original job only through an explicit reference.

live_backends and pilot_started both stay false.

Human operator desk

The desk is the human surface. The public Worker MCP stays a read-only bridge without this chrome. On the operator machine, the desk's loopback POST /mcp lets an agent request writes. Writes require operator approval; default off. See Approval-gated writes.

npm run desk
# http://127.0.0.1:4174/

npm run shadow:field and npm run shadow:office print one local shadow read of that same desk snapshot. Both commands, and the desk page, read data/runtime/<instanceId>/field-events.jsonl (Clock in, Clock out, Start Meal, End Meal, Drive time home) and the job price record in data/runtime/<instanceId>/job-prices.json (typed part cost, labor, task fees, margin, locked discount). They do not keep a second event log. The AZTrades shell on this desk is Local Softwares only. live_backends false. pilot_started false. Not Field 1.0. This is not Office Softwares 1.0. ServiceTitan, Jobber, and other bring-your-own profiles are ingested read-only. Writes require operator approval; default off. SupplyHouse is a public GET when a number returns; the typed cost remains when unavailable (403 or no number); no order path. This read does not invent a price. Other named suppliers stay empty until a permitted account. The property card is company history only. Zillow, Redfin, and a county assessor are not connected until a permitted source. Local login: the first user is okayed; later users need higher approval. No ServiceTitan or Jobber write-back from this shell.

It binds to 127.0.0.1 only. The page shows job/completion charts, a capacity chart, a mission board and a tech board, a morning huddle, fulfillment progress, alerts, and scores. Callback calls, warranty calls, and a not-classified bucket sit on the metrics and the mission board. Each call row carries the classify reason when the export named a label, and says not classified when the export is silent. Filters are ?calls=callback, ?calls=warranty, and ?calls=not-classified on the page, /api/snapshot, /api/view, /api/receipt, and the SSE stream. /api/calls/week.json is the trailing-week callback rate by trade lane. /api/huddle prints the morning huddle and /api/huddle.json is the same board as JSON. The huddle names trainingNeeded (severity and reason) from procedure observations. It is not a skill score. Part cost, department behavior, and truck counts are on the same page. /api/stock reads on-van and warehouse counts. Miles driven and drive performance sit beside a ranked employee and department performance board. /api/drive and /api/performance are the loopback JSON for those boards. An optional miles file is data/runtime/<instanceId>/drive-miles.json or data/inbound/drive-miles.json. A missing file stays unknown once a local export is admitted. The empty-folder desk labels a synthetic demo. That demo is not a company export and not a telematics feed. The rank is not a skill score and it does not set trainingNeeded. No GPS vendor is claimed. Work together lists positive collaboration from Chain D, cross-trade, and recognition flags and names who or which lane should pair or hand off for service techs when needed and for install. /api/work-together is that board. Employee friction rate sits on the same performance board and at /api/friction. It counts handoff failures, coordination flags, explicit callbacks, and delayed handoffs on this machine. A silent export stays unknown. Friction rank 1 is the highest known friction, not the best performance. It is not a hosted HR system and it does not set trainingNeeded. Those routes stay on this machine. Each score and pace band includes a short why. Current alert-rule hits export as JSON or CSV from /api/alerts/digest.json and /api/alerts/digest.csv on this machine. /api/receipt prints what blocked booking when a block is present, and says when nothing is blocking. TR-DESK-POLISH-2026-09-25 adds spacing and type, a light/dark theme stored in this browser (trades-desk-theme), a lane view, and a printable snapshot at /api/receipt. The lane is a slot count, or a known trade token when the export names one (hvac, plumbing, electrical, sewer, cross-trades). A city name is not a lane. No map is drawn. The snapshot is HTML the operator can print or save as PDF. It cites local receipt identifiers and does not include receipt bodies. Nothing on that page phones home. Scores use mission pace, the evidence trust band, verification (UNVERIFIED), and recommendBlock. Prediction confidence stays withheld on a BYO drop. The recorded synthetic shadow-day confidence appears only on the synthetic demo, labeled as a fixture. An empty inbound folder shows that synthetic demo. Dropping a file updates the next SSE tick (about 2s) and the label switches to BYO-admitted, or BYO-admitted synthetic drill when every file declares synthetic: true.

Local alert rules (TR-ALERTS-2026-09-25)

The same scores drive local thresholds: capacity (open slots, only when a lane exists), late jobs (unfinished rows against the mission clock), trust-band (evidence-trust floor or a drop remembered on this machine), booking block (recommendBlock), and verification stall (the verification score stays UNVERIFIED or CONFLICTED for N minutes from the oldest observation). No accuracy percent is computed. A missing clock does not invent a stall. Blank open slots on a BYO desk do not invent a utilization percent.

Copy data/runtime/alerts.json.example to data/runtime/<instanceId>/alerts.json (gitignored). data/inbound/local.json may set alertsPath or an alerts object. The desk banner shows unacknowledged rules. The alerts panel shows active rules, history, and acknowledge. Acknowledge is a local POST on 127.0.0.1 and writes only alert-state.json. Optional hooks append a local JSONL file or POST to loopback (127.0.0.1, localhost, ::1). Any other webhook host is refused. No phone-home.

Inbound quality, alert stubs, and Option C start gate (TR-QUALITY-2026-09-27)

/api/inbound-quality and /api/inbound-quality.txt score ServiceTitan and ProBooks fragments already on this machine. The desk charts volume by sourceKind, checklist-score distribution, and top defect classes from that local report. Empty folders use a labeled synthetic fixture. The checklist is not an accuracy percent and not a live tenant pull. Files land at data/runtime/<instanceId>/inbound-quality.json, .txt, and .jsonl.

/api/alert-actions returns stubs only. A firing alert expands to a label, a rationale, the required human authority, and refused: write-back. The Human Authority Rule is on the panel. Stubs do not call ServiceTitan or ProBooks.

/api/option-c-start-gate lists the start conditions. Every gate stays blocked-until. Option C remains prep until a human operator starts a real pilot. Option D is out of scope. There is no cutover. The shipped catalog keeps pilot_started false. live_backends stays false. The panel does not start the pilot.

/api/monitoring is one desk view: local or demo tech and truck pins, time cards, a coverage livemap, right-tech suggestions, drive score cards, tech score cards, a dispatch-style call board, and KPI charts. Pins come from data/runtime/<instanceId>/positions.json, data/inbound/positions.json, or coordinates copied off a local miles file. Copy data/runtime/positions.json.example. An empty folder uses a labeled synthetic demo. A refused file is not replaced by that demo. Mile totals still ignore coordinates. The address map stays undrawn. This is not a live GPS feed and not a telematics vendor. The view recomputes when local files change. Monitoring only. The Human Authority Rule stays on the panel. Nothing writes back to ServiceTitan or ProBooks.

/api/time-tracking is the local time board: clocked time on the current call, elapsed, estimated remaining, and idle or travel segments. Copy data/runtime/time-cards.json.example to data/runtime/<instanceId>/time-cards.json or data/inbound/time-cards.json. The desk writes time-tracking.json and time-tracking.jsonl under data/runtime/<instanceId>/. A missing file stays empty once a local export is admitted. The empty-folder desk labels a synthetic demo. That demo is not a company timeclock and not a GPS feed.

/api/coverage is zip codes, counties, cities, and roads or highways, with on/off switches. Copy data/runtime/coverage.json.example to data/runtime/<instanceId>/coverage.json or data/inbound/coverage.json. Switches persist in coverage-layers.json on this machine (POST /api/coverage/layers). Counts are places, jobs, and techs from that local file. Not a live map-tile vendor. The address map stays undrawn.

/api/right-tech (and /api/tech-fit) ranks techs for an open or scheduled job from geolocation, estimated time remaining, and skill fit. Optional ?job=. Suggestions only. No auto-dispatch. No write-back. Friction and heavy local drive minutes are flags. Geography is not the only factor.

The operator can turn boards, metrics, KPIs, techs, scores, charts, lanes, alerts, call columns, and mission measures on or off. Every box starts on. The choice is stored in this browser under trades-desk-view and is not sent off the machine. TR-DESK-VIEW-2026-09-27.

The same page is usable at about 375px. A sticky domain nav jumps to each board. Header links, monitor charts, and wide tables scroll inside the page instead of widening it. Theme, filters, acknowledge, the stub disclosure, print, and any input, select, or textarea are at least 44px tall, with safe-area padding. Wide-window Softwares card grids stay as they are. There is still no tenant data-entry form. TR-MOBILE-DESK-2026-09-27. The public Worker cards are not part of this cut.

The public Worker may cite npx tsx src/cli.ts desk and /local-desk as install notes. It does not host the desk, the alert hooks, or tenant metrics. This repo does not deploy the Worker.

npm run byo:admit-demo is operator-software proof with synthetic fixtures under test/fixtures/byo/. It copies those fixtures into a temp inbound dir, admits via FragGate as servicetitan + probooks, hashes packets, writes isolate receipts under a temp data/runtime/<id>/, prints hashes, and proves wrapper ≠ VERIFIED while ST/ProBooks writes still throw. It is not a customer dump. The authoring node is not a data custodian.

Real user exports belong only on that user's machine under data/inbound/{servicetitan,probooks,trades-app}/ (gitignored except .gitkeep).

Inherited names come only from specs/aziel-runtime-inheritance.txt. This is not a wholesale copy of aziel-runtime Softwares.

Ladder (honest)

Software for Option C exists (named branch, engagement rules, sealed settlement harness, synthetic demo). That is not a company or field pilot. Do not tell a GM the company OS is live. Do not fake Option C as a live company pilot. Option D is still NO.

TR-OPTION-C-PREP-2026-09-25 is the operator-box checklist: local install, inbound drop folders, example config, synthetic admit, desk and alerts, SHADOW-SEALED expectations, refuse-write proof, and what not to do. npm run pilot:prep runs those checks and prints a receipt. ready: true means the machine passed. That receipt keeps pilot_started false. The command does not open a sealed day against company actuals and does not write to ServiceTitan, ProBooks, or a trades app.

TR-OPTION-C-PILOT-RUNBOOK-2026-10-02 is how an operator starts a real pilot with the shipped command. After prep is green, a person on the operator box runs npm run pilot:start -- --branch <branchId> (CLI pilot-start). One named branch is required. The command reuses the prep checks. It refuses a missing or bad branch, prep that is not ready, and --claim-company when inbound is empty or only synthetic. Success writes data/runtime/<instanceId>/pilot.json and a line on receipts.jsonl for that isolate only. The shipped catalog, default health, glama.json, and the giveaway Worker pin stay 1.0.0 with pilot_started false. Mode stays SHADOW-SEALED. live_backends stays false. Writes require operator approval; default off. An explicit mode change does not start the pilot. The receipt says this is not a live company OS, not Field 1.0, and not Office Softwares 1.0. Merging this documentation does not start a pilot. A human must run the command on a real prep-ready branch. TR-PILOT-START-2026-10-02 is the cut that shipped the command. This repository does not deploy the Worker and does not Make Release.

Still human/operator-only: a real ServiceTitan path on their box, a named GM, and sealed days against their actuals. The authoring node does not hold that dump. A prep receipt is not that pilot.

Public giveaway Worker

Operator-authorized public surface is a Cloudflare Worker:

https://trades-runtime.vibelock.workers.dev

Worker script name: trades-runtime (same vibelock workers.dev account pattern as aziel-runtime.vibelock.workers.dev). Source: workers/giveaway/.

What it is:

• Human giveaway UI on this VibeLock host (browser / PWA): honesty, cite, MCP, skill, and stats, usable without downloading first

• Optional counted Apache-2.0 tarball at GET /download (increments only after a verified gzip 200)

• /local-desk cites the local npx tsx src/cli.ts desk install. It does not host tenant metrics or a live company board

• Thin read-only /openapi.json and POST /mcp for AI clients (health / stats / cite / skill only)

• Growth-ON crawl surfaces: /robots.txt (full Allow + Content-Signal), /sitemap.xml, /ai.txt, /humans.txt, /.well-known/mcp.json, /person.jsonld, /graph.jsonld

• Stdio MCP bridge for Glama / Claude Desktop / Cursor: npm run mcp → cli/mcp-stdio.mjs (forwards to Worker POST /mcp)

• Honest Workers KV counters (COUNTS): views and downloads start at 0; increment only on successful 200 responses; no sampling, no seed, no inflation

Deploy (operator / box with wrangler auth)

This repository does not deploy the Worker. First time on the vibelock account:

npm ci
npm test
cd workers/giveaway
npm ci
npx wrangler kv namespace create COUNTS
# paste the printed id into wrangler.jsonc kv_namespaces[0].id
npm run pack
npx wrangler deploy

Later deploys from repo root:

npm run giveaway:pack
cd workers/giveaway && npx wrangler deploy

Local smoke (Miniflare KV, no Cloudflare auth required):

npm run giveaway:pack
cd workers/giveaway
npx wrangler dev
# GET http://127.0.0.1:8787/  /download  /v1/health  /v1/stats  /robots.txt  /sitemap.xml  /ai.txt

Counters: see workers/giveaway/README.md.

Glama (Install Server pack)

Intended listing: Try on Glama

The listing URL is documented so agents and humans can find it. The Git pack (glama.json + Dockerfile + cli/mcp-stdio.mjs) is what Glama needs to index and host a stdio process. Install Server is not claimed LIVE from this git tree alone. Steps: docs/GLAMA.md.

Do not invent Glama TDQS scores. The listing Latest still measures 1.0.0-local and does not match the in-repo Softwares cite tip 1.0.0. Catch-up pending. That gap is not Field 1.0 and not Office Softwares 1.0.

Checked 2026-10-02: Glama Latest/releaseVersion is 1.0.0-local (latestRelease.version on https://glama.ai/mcp/servers/@AzielEliab/trades-runtime). The public badge is still 1.0.0-local and does not match the in-repo Softwares cite tip 1.0.0. Catch-up pending. The Official MCP Registry still measures 1.0.0-local. This cut does not republish it. Local Softwares 1.0. That gap is not a Field 1.0 claim and not Office Softwares 1.0. glama.json version is the in-repo claim file (1.0.0) and does not yet match the public badge 1.0.0-local. Catch-up pending. The Worker source in this repo is 1.0.0. The giveaway Worker version pin is 1.0.0. Checked 2026-09-28: the already-running Worker is still 0.4.12. This cut does not deploy and does not Make Release. pilot_started false. live_backends false.

Local / Docker:

npm run mcp
# or
node cli/mcp-stdio.mjs
docker build -t trades-runtime-mcp .
docker run --rm -i trades-runtime-mcp

Pages (intentionally disabled)

GitHub Pages is intentionally disabled. There is no .github/workflows/pages.yml. Do not add a Pages deploy workflow. Do not enable Pages on the repository. Do not treat a github.io URL as a live product surface.

The software is free to clone. GitHub Pages stays off. Do not enable Pages. Do not add PDFs under docs/. A browser UI, if a Worker is already deployed, is https://trades-runtime.vibelock.workers.dev. This repository does not deploy that Worker. The counted tarball is optional.

Local UI preview (Pages stay off):

python3 -m http.server 4173 --directory docs

Machine catalog: docs/v1/runtime.json. Module UI: /modules/.

What this is not (§1.2)

Not a simple dispatch optimizer. Not a revenue-as-skill leaderboard. Not a fixed morning route planner. Not an autonomous black box that silently overrules humans. Not photo-as-proof of misconduct. Not fuel-first. Not an automatic 30-day callback penalty. Not a PDF portal.

License

Apache License 2.0. See LICENSE.