Your first change (the developer quickstart)

A 30–60 minute path from a fresh clone to one small, real, gate-green change. Follow it in order; every step says what to run and what to expect. By the end you will have seen the whole loop: edit → prove → commit conventions → where to go next.

Step 1, Clone and install (5 minutes)

git clone git@github.com:oimlsmart/smart.git && cd smart/browser
npm install

You also want the kernel and the SST checkouts beside the smart repo (the gates and the sim-backed suites use them): primmel/sst, the SST framework, and oimlsmart/sst, the OIML instrument library (the pre-split sim-instruments repository was archived on 2026-08-01).

cd .. && git clone git@github.com:primmel/primmel-ts.git ../primmel/primmel-ts
git clone git@github.com:primmel/sst.git ../primmel/sst
git clone git@github.com:oimlsmart/sst.git ../oimlsmart/sst
cd ../oimlsmart/sst && npm install

(Adjust the clone paths so the four repos sit in this layout: src/oimlsmart/smart, src/primmel/primmel-ts, src/primmel/sst, src/oimlsmart/sst. The library’s declared file: dependency finds the framework at ../../primmel/sst, and the smart repo’s live-sim legs resolve the two from the declared envs SST_REPO and SST_LIBRARY_PATH.)

Step 2, Prove the system works before you touch it (10 minutes)

Point the app at the kernel and run the core gates. Every one of these must be green before you change anything, a red gate now means the environment, not you.

cd smart/browser
export PRIMMEL_TS=/Users/<you>/src/primmel/primmel-ts/packages/primmel
npx vitest run            # expect: every test file passed, zero failed
npm run validate          # expect: ALL CHECKS PASSED, 0 errors
npm run test:ssot         # expect: SSOT GUARD PASSED, byte-clean both directions

The warning count is the documented named-gap class (not errors), and the suite totals move as the platform grows; the chapter on knowing it works explains what each gate proves. If everything is green, your environment is right. If a gate is red on a fresh checkout, the common causes are a busy port, a stale build cache, or a missing sibling checkout; the gate’s own output names what it could not find.

Step 3, Make one tiny real change (15 minutes)

The change: make the temperature-failure sample’s thermal-hysteresis memory a little stronger. It is small enough to see the whole loop and real enough that the gates which can see it must answer.

1. Open oimlsmart/sst/packages/kinds/sst-r60/physics-chain.yaml and read the compression stages: the physics is data, three stages per construction, and every stage declares what it consumes and produces (read the header comment; that is the house style).

2. In oimlsmart/sst/packages/kinds/sst-r60/scenarios.yaml, find the temp-fail scenario: it sets thermalHysteresisPerDegC: 0.0002. Change it to 0.00025, a 25% stronger memory, still inside a plausible class range. The instance sample pins its own value as the boot-time chain of custody, so make the same change in oimlsmart/sst/packages/instances/acme-lc500/samples/temp-fail.yaml (thermal_hysteresis_per_degC).

3. Run the library’s gate from the library root:

   npm run validate

   Every package (12) must validate against the real runtime. Then boot the changed sample and see the physics you moved:

   npm start -- temp-fail   # the LC-500, temp-fail sample, on :5290

   Place a load and sweep the temperature on the world channel; the memory you strengthened is exactly the reading that does not come back.

4. Run the framework’s suite with the library declared, it proves the machinery your change rides on:

   cd ../../primmel/sst
   SST_LIBRARY_PATH=../../oimlsmart/sst npm test
   npm run typecheck

What you just did is the system’s innermost loop: a physical parameter changed as data, the library’s gate proved the packages still hold against the real runtime, and the framework’s suite proved the machinery the parameter drives.

Step 4, Prove the platform side is untouched (5 minutes)

The smart repo’s sim-backed suites read the sim through its channels. Run them to prove your change didn’t disturb the contract:

cd smart/browser
export SST_REPO=/Users/<you>/src/primmel/sst
export SST_LIBRARY_PATH=/Users/<you>/src/oimlsmart/sst
npx vitest run src/__tests__/sim-twin-acceptance.test.ts
npx vitest run src/__tests__/twin-fidelity-probe.test.ts

Both must pass (they boot the real sim from the declared positions; undeclared, the live-sim legs skip honestly). The temp-fail knob you changed is not in the acceptance paths, but the habit is the point: every change runs the gates that could see it.

Step 5, Commit conventions (5 minutes)

• Stage exact paths only (git add <file>, never git add -A).
• The message says what changed and why, with the evidence: scenario: temp-fail thermal memory 0.0002 → 0.00025 (class-plausible; validate clean, framework suite 255/259 with 4 skip-honest).
• Do not commit generated files (browser/src/data/generated/**, data/ trees are generated, the SSOT guard will catch you anyway).
• Do not push or merge unless the task asked for it.

The five rules you can’t break (one line each)

1. SSOT, author in primmel-packages/; data/ and browser/src/data/generated/ are generated, guarded byte-clean.
2. Gates before merge, vitest, validate, ssot, and the repo-relevant suites green, every time.
3. Honesty, silence is not evidence (unprovable ⇒ indeterminate); failures are unavailable, never exceptions.
4. One dialect, verdict engine, certificate machine, OCL evaluator: one each, reused, never write a second one.
5. Epistemic wall, the app never calls a sim’s /world outside the declared practice seam; certification reads only /twin.

Where to go next

• The map of everything: docs/architecture/for-agents.md, every component, what it owns, its proof command.
• The conventions for your area: AGENTS.d/, the topic index is in AGENTS.md; read the topic file before you change that area.
• The roadmap: docs/future/README.md, the TODO.v3 wave; ask before starting an item so work isn’t duplicated.
• The demo: npm run reset-db && npm run dev → http://localhost:5190/app (any password), see the system as a user sees it before you change it.

---

Back to the index.