Back to the game

CRYPT user manual

CRYPT turns a project's dependency tree into a creature, one limb per package, and lets a team heal it by playing a text adventure. This manual covers day-to-day use. Background and design live in the README, DEMO.md (the live pull request walkthrough), ACCESSIBILITY.md (measurements) and KIRO.md.

Quick start for testers

You do not need to know what jQuery is. This page walks you through the live demo in about five minutes. Nothing you do here changes any real project.

The demo shows a small project as a creature. Each package the project depends on is a limb. JQUERY is one of those limbs: jQuery is a JavaScript library that many websites use, and the demo project depends on an old version of it that has known security problems. The game tells you what is wrong with it.

  1. Open the live page. Click the Command box, type EXAMINE JQUERY and press Enter. The game describes the limb: its state, how many known vulnerabilities (CVEs, public security bug reports) it has and how likely they are to be attacked.
  2. Type GRAFT JQUERY and press Enter. This asks for a fix. The page shows a dry-run pull request in the "Dry-run PR payload" panel. It is a preview only. Nothing is sent anywhere, and a person would still have to merge a real one.
  3. Read the plate (the picture of the creature). Each limb has a glyph and a word, so colour is never the only clue. # POSSESSED (orange) means the vulnerability is being used by attackers right now. % ROTTING (yellow-green) means a known vulnerability exists. . HEALTHY (dim green) means none is known. HEALED (bright green) means the fix was merged.
  4. Type RAID and press Enter to start the 15 minute timer and the team score.
  5. Type SEAL CRYPT and press Enter to freeze every agent action. After that, any GRAFT or RAID is rejected. In the browser the seal lasts until you reload the page.

Commands use capital letters only and exactly one space between words. Anything else is rejected, and nothing happens. The rest of this manual has the details.

1. Install and first raid

Node 20 or newer is required.

npm install --global @e-1305/crypt     # installs the `crypt` command
crypt raid <path-or-github-url>

From a checkout of this repository, use the local command:

npm ci
npx --no-install crypt raid fixtures/vulnerable-npm --offline

The first run builds the Inform 6 and dfrotz toolchain into ~/.cache/crypt/toolchain (set CRYPT_TOOLCHAIN_DIR to move it). That step needs git, make, a C compiler and network access, once. out/, crypt-audit.log and .crypt-seal are written to the directory you run the command from.

crypt raid runs the whole ritual: exhume the lockfile, rank the findings, raise the story file, print the plate (the picture of the creature) and open the game prompt.

Commands

Commands
CommandWhat it does
crypt raid <target>Exhume, raise, show the plate and play. Start here.
crypt exhume <target>Scan the dependencies and write out/creature.json.
crypt raise [creature]Build out/creature.z8 from the creature file.
crypt playPlay out/creature.z8.
crypt graft <LIMB>Request one fix for a limb.
crypt inquisit <LIMB>Check the CI of that limb's pull request.
crypt reraiseAfter a human landed pull requests, mark those limbs healed and recompile.
crypt seal / crypt unsealStop every agent action / lift the stop.

<target> is a local directory or https://github.com/<owner>/<repo>. A GitHub URL is shallow-cloned into a temporary directory that is removed afterwards. Only the lockfile and CODEOWNERS are read. Nothing from the target runs and nothing is installed. crypt --help lists every flag.

Supported inputs: package-lock.json (v2 and v3) and requirements.txt (== pins only). A limb whose status cannot be established shows as unknown, never as clean.

Exit codes

Exit codes
CodeMeaning
0ok
1runtime failure
2usage error
3toolchain missing or failed to build
4target unreadable (clone failed, no manifest)
130interrupted

2. Playing the game

Commands are matched against a strict grammar. Capital letters only, one space between words, no extra text. Anything else is rejected before any action happens.

2. Playing the game
CommandEffect
EXAMINE <LIMB>Describes the limb: state, number of CVEs, top EPSS score and the surgeon of record (from CODEOWNERS).
ASSIGN <LIMB>Names the owner of the limb.
GRAFT <LIMB>Asks for a fix. In the terminal and in the browser this writes a dry-run pull request payload (out/prs/ in the terminal, the "Dry-run PR payload" panel in the browser). With --live it opens a real pull request.
SEAL CRYPTFreezes every agent action. Later GRAFT and RAID commands are rejected. In the browser the seal lasts until the page is reloaded.
RAIDStarts the 15-minute raid timer (see section 5).
HELPLists the commands. Prints text only.
HINTNames the limb to EXAMINE or GRAFT next. Works in every state, including after SEAL CRYPT. Prints text only.
WAIT, SING, SLEEP, HELLOPass a moment in the crypt. The vault has a few more replies, so try other words. Text only.

Each limb has a personality (grumpy elder, nervous intern, show-off and others) picked from its package name, and its description changes with its state: healed, rotting or possessed. A limb with a high exploit chance (EPSS 0.5 or more) gets a worse line. The room text follows the worst state in the vault, and now and then the crypt adds an atmosphere line such as The lights flicker. These extra words never ask for a fix and never reach the pull request step.

<LIMB> is the package name in capitals, up to 32 letters, for example GRAFT JQUERY. Try the offline check with npm run necromancer:check: GRAFT JQUERY gives one payload, and after SEAL CRYPT a GRAFT LODASH gives none.

crypt seal writes .crypt-seal in the current directory and crypt unseal removes it. While it exists, every graft is rejected. If the story file fails to load in the browser, no command works, including RAID: reload the page.

3. Reading the creature

Each limb is one package. The state is shown by a glyph and a word, never by colour alone.

3. Reading the creature
StatePlate glyphColour (3D wall)Meaning
POSSESSED#orange #ff6a3dA known vulnerability is actively exploited (CISA KEV). Heal these first.
ROTTING%yellow-green #c8e63cA known vulnerability exists (OSV).
HEALEDclean linesbright green #33ff33The fix was merged by a human and the creature was recompiled.
HEALTHY.dim green #22b022No known vulnerability.

Ranking uses KEV and EPSS data and is plain deterministic code. No AI model scores or ranks anything.

Awaiting human merge

When a fix pull request has green CI, the limb is marked awaiting-human-merge. The plate keeps showing it as POSSESSED or ROTTING, because the limb is not healed yet. The raid score counts it (section 5). It becomes HEALED only after a person merges the pull request on GitHub and crypt reraise (or the web page, when it loads the updated creature) sees the merge. A red CI result changes nothing: the limb stays as it was.

4. Guarantees

The full rule list is in .kiro/steering/failsafe.md and .kiro/steering/blameless.md.

Live mode

crypt raid <github-url> --live opens a real pull request, watches its test check and leaves the merge to a person. It needs a fine-grained GITHUB_TOKEN limited to the target repository (Contents and Pull requests: read and write, Checks: read). Classic tokens are refused. Without a token, runs are dry runs. Use --timeout <seconds> (10 to 3600, default 600) to set how long to wait for CI. Steps for a full demonstration are in DEMO.md.

5. The web player

The hosted page is e-1305.github.io/Crypt. This manual is also hosted, at e-1305.github.io/Crypt/manual.html, and the page links to it as "How to play (manual)". To run it locally:

npm ci
npm run setup      # builds the toolchain once
npm run web        # serves http://127.0.0.1:8080/ (set PORT to change)

The page opens on a demo creature built from fixtures/vulnerable-npm. GRAFT in the browser is a rehearsal: it shows the dry-run payload and sends nothing.

URL flags

URL flags
FlagEffect
?creature=<slug>Opens a gallery creature.
?theatre=offLoads the plain 2D page and skips three.js.
?record=1Starts in recording mode (below).
?simulate=green or ?simulate=redReplays a simulated CI result on the first sick limb when the page loads.

Flags combine with &, for example ?theatre=off&simulate=green.

The 3D operating theatre

On a browser with WebGL2, the page shows a 3D bench: a CRT with the game, the plate on the wall, a lamp and a bench drawer. Type as usual. Keys go to the real command input. The camera moves toward the CRT on the first key press. A title card shows for 3 seconds (any key or click skips it).

The page loads the plain 2D view instead when any of these hold: no WebGL2, reduced motion is requested in the operating system, reader mode is on, or the URL has ?theatre=off. A "Plain page" link on the bench does the same.

Bench drawer. Use the drawer toggle to open "Download the playable report" and "Exhume a public repo" (opens that creature when it is in the gallery). Escape closes the drawer and returns focus to the toggle.

Sound. The "Sound: off" button turns on synthesised audio (a CRT hum, a heartbeat that quickens with possessed limbs, thunder when a limb heals). Sound starts off and only a click on the button starts it. No audio files are loaded.

Recording mode. The "Recording mode" button, or ?record=1, hides the header, event log, plain-page link, sound button and the raid and CI buttons so the CRT and plate fill a screen capture. Escape leaves it. The announcer still speaks while recording, so screen-reader users hear events.

Simulated CI

The "Simulate CI: green" and "Simulate CI: red" buttons replay a dry-run graft for the first sick limb. Everything is labelled SIMULATED CI, uses no token or network, and is kept out of the raid score. Green heals the limb on screen with a flash and thunder. Red makes the limb convulse and leaves its state unchanged. After a green result the plate marks the limb HEALED within three seconds, the event log adds "SIMULATED: jquery healed" and a screen reader hears it. After a red result the limb stays ROTTING and the log says so. Real heals appear when the page loads a creature file in which a limb has become healthy after a human merge.

The raid

Type RAID in the game input, or press "Start the 15 minute raid". The readout shows:

Scores are for the team. CRYPT does not rank, total or compare individuals, and has no leaderboard. Raid state is stored in the browser, per creature, so clearing site data resets it.

Share your creature

After paste your repo, and again when a raid ends, a share panel draws a 1200 by 627 PNG card in your browser: the plate, the creature's name, N findings -> M monsters, possessed and rotting counts, limbs healed, and the line "Don't abandon your creature" with the site address. The raid card adds the team score, limbs healed and the raid time. Nothing is uploaded and nothing is tracked.

Game feel

The raid adds arcade touches on top of the team score. They are display only: the team risk removed and the rank above do not change because of them. Nothing here is counted per person.

Getting started

A strip above the game walks through the first minute on the demo creature in three steps: look at the plate, type GRAFT <limb>, then open the Bench and press "Simulate CI: green" and watch the limb heal. The strip names a limb that has a rehearsal pull request.

The seal on the page

Typing SEAL CRYPT shows a badge, "SEALED: no graft will run.", on the 2D page and over the 3D bench. A GRAFT is then rejected and no payload is made. The "Unseal" button lifts the seal for this page only.

Pressure

While a raid runs, "Possession spread" shows how far the possession has spread, from 0 to 100 percent, as a text line and a progress bar. It rises with the clock and climbs faster while KEV limbs stay open. Healing a KEV limb lowers it again. Warnings appear at 10, 5 and 1 minutes left, in text, and the 10 and 5 minute warnings are announced, and the last minute is announced by the raid timer. Pressure is display only: it does not change the team risk removed, the rank or the grade. It never pulses, and it looks the same with reduced motion, high-contrast reader mode and the 2D page.

Run history and SLA trend

Each crypt autopsy and crypt gazette run appends one line per limb to out/crypt-history.jsonl: time, limb, state, KEV, EPSS, owner team and deadline, with a source label (real or sample). Lines of one limb less than five minutes apart count as one run, so autopsy and gazette in one job add one point. A deadline counts from the limb's found time when the creature has one, else from the first history line. The autopsy page and the War Room show open KEV limbs over time, the age of each limb, deadline breaches and the mean time to heal (only from Healed lines that carry their own time; landing time is shown apart). A value the file does not hold reads unknown.

In the GitHub Action the file is in the artifact. To keep it between runs, set history-branch: crypt-history and give the job contents: write. Only a branch named crypt-history that is not the default branch is accepted. To read another file, run crypt autopsy --history <file>. The War Room shows the real crypt-demo events of 2026-11-18 from fixtures/history/crypt-demo-2026-11-18.jsonl.

6. Accessibility

The text game is the core, so screen readers work with the same text the game prints. The transcript is a live log region, every command has a labelled input, state is told by glyph and word, and events are announced through a polite status region. Reduced motion turns off all animation. The Lighthouse score is 100 on the default 2D page. Full measurements are in ACCESSIBILITY.md.

Limits of the 3D bench, stated plainly:

7. Troubleshooting

7. Troubleshooting
SymptomWhat to do
Exit code 3The toolchain did not build. Install git, make and a C compiler, make sure the network is reachable, then run npm run setup or rerun crypt raid. Build output is in ~/.cache/crypt/toolchain/build.log.
Exit code 4The target has no readable manifest or the clone failed. Check the path or URL and that a package-lock.json or pinned requirements.txt exists.
Exit code 2A flag or argument is wrong. Run crypt --help.
Grafts say "The crypt is sealed"Run crypt unseal in the directory that holds .crypt-seal.
npx crypt tries to download somethingInside a checkout use npx --no-install crypt. Elsewhere use npx @e-1305/crypt.
A command is rejectedUse capitals and one space: GRAFT JQUERY. The limb is the package name in capitals.
Plain page loads instead of the 3D benchCheck WebGL2 support, the reduced-motion setting, reader mode and that the URL has no ?theatre=off.
No soundPress "Sound: off" to turn it on. Browsers allow audio only after a click.
--live is refusedSet GITHUB_TOKEN to a fine-grained token limited to the one target repository.
Offline run has no data for a package--offline answers only from the cache in data/cache/osv/. Run once with network access to fill it.

How it works

One lockfile in, one playable story out, and a human at the end. Each arrow is a file you can read.

lockfile --> OSV + CISA KEV + EPSS --> creature.json --> Inform 6 --> creature.z8
   (Z-machine story) --prints--> [[CRYPT GRAFT JQUERY]] --> watcher --> Necromancer
   --> fix PR (dry run by default) --> CI --> a person merges --> reraise --> limb HEALED

Why a Z-machine. The story is one small file that runs anywhere. Infocom's interpreters (Frotz, Lectrote, Parchment) open the .z8 you download from the page. The game is the interface, so there is no dashboard to build.

Only the game triggers anything. The watcher reacts to [[CRYPT ...]] markers that the story prints after it accepts a command. Text you type never counts as a marker, and the command grammar is strict (capitals, one space).

The failsafe. There is no merge call anywhere in the code. SEAL CRYPT blocks every graft. Every agent action goes to crypt-audit.log. Without GITHUB_TOKEN, a graft is a dry run and writes its payload to out/prs/. A person merges every pull request. failsafe.md lists the rules, and property-based tests enforce them.

Why the story says (at). The plate shows an owner as @team, and the story text shows (at)team. The Inform 6 compiler reads @ as an escape inside strings, so src/raise/sanitize.ts spells it (at) in every generated string, and the same pass strips brackets and quotes. Same owner, same CODEOWNERS entry, two spellings by design.

One file format, two front ends. The Pages site and the CLI read the same creature.json. The page can rehearse: play the story, read dry-run payloads and simulate CI. Only the CLI can open a real pull request (crypt raid <url> --live). Tier 1 scope: npm and pip lockfiles.

Built with Kiro

CRYPT was built with Kiro, using four of its features together:

KIRO.md has the evidence and the limits. The playtest loop in PLAYTEST_LOG.md and BACKLOG.md shows how a judge persona and a product manager persona drive each round of fixes.

Back to the game