Command-line reference
Release 1.0.42. Every block on this page is what the program printed for --help (or the named command), captured from the 1.0.42 Linux build (the operator-only internal grading tier is left out of the producer help, and the dinctrl-store allow-list line names all three producers). The download carries fifteen programs; din is the one you type, and it runs the field, the console, the importer, the dependency audit, the capture producer, the library catalog client and the re-grade driver for you.
din
din - your own field, on your own box. Your records stay here (what leaves: README, 'What leaves your machine').
USAGE
din status: is the field up, what is in it, next steps
din doctor [--json] read-only check of this install: programs, PATH,
licence, field, autostart, catalog age; each
problem with its fix. Exit 1 when one FAILs
din setup --isolated a NEW field of your own in a tree of your own:
own token, own store, own auto-picked loopback
port, started without root, Postgres or systemd.
--port auto|N --prefix DIR --dry-run --force
din setup model how grading runs: your assistant CLI, your own
API key, or a local model
din setup workspace every project in din-workspace.json: field.sh,
capture launchers, scope.resolved.json.
Idempotent; never deletes.
--config P --check --dry-run --strict --project N
din scope validate|resolve <project>|file <project>|recall ...
din-workspace.json: what each project may READ
besides its own field (writes stay local)
din field start start the field on loopback and wait for it
din field stop stop the field this install started; it stays
stopped (nothing starts it on its own) until
`din field start`
din field status ask the field how it is
din field ensure start it if it is down and was not stopped on
purpose (what every verb below does first)
din autostart on|off|status also start it at login: a systemd user unit or
XDG entry, or a LaunchAgent on macOS.
Per user, no admin. `off` removes what `on` made.
`on --with-push` also runs `din hosted push`
at login (a hosted console must be connected).
din field log [-n N] the last N lines of the field's log
din field binding which field is ACTIVE, which are archived and KEPT
din field activate <id> bring an archived field back, whole (one at a time)
din field new <name> another field in this install: its own store,
token and loopback port; programs and plan are
shared. --port auto|N. It starts on first use.
Your plan sets how many: Free includes 1. Past
that it is refused (exit 3) and nothing is changed
din field list every field: port, records, active agent, and
the plan's allowance as N of M
din field use <name> the default field for recall, query, brief,
console and import (`main` is the install's own)
din field route <project> <field>
capture that project into that field (the plugin
reads $DIN_HOME/routes.json). --default <field>
sends every unrouted project there.
din field unroute <project>|--default
din field routes the routes. --import-capture-map FILE [--create]
turns an old capture-map.json into routes
din field attach <name> --store DIR [--port N] [--token-file FILE]
name another install's field on this machine,
so routes and `din capture --field` can place
into its store
din field detach <name> forget it, once no route names it; its store is
untouched
din field add <name> --store DIR --port N
a field whose store is DIR, with a stock unit
(systemd --user, else a launcher) in this
install's registry, so `din update` knows it
din field remove <name> its unit removed, unregistered; its store kept
din field adopt <unit> take over a hand-made unit or launcher, after
showing the diff to the stock one (--as NAME,
--yes, --dry-run); the original is kept
din update this install to the newest release: checked,
every program renamed in, every registered
unit pointed at them. Restarts only with
--restart (or a yes). --dry-run, --from DIR|URL.
The previous version is kept (--keep N)
din update --rollback put the previous version back: programs, field
units and registry. Never your data
din agent list which agents are wired here, and which one your
field serves (ACTIVE) or has set aside (ARCHIVED)
din agent add <name> [--yes] wire claude-code, cursor or opencode with the
plugin's own installer. On free it says first what
a second agent does and asks at a terminal.
din agent remove <name> unwire it; its records stay in your field, kept
din capture [status|on|off] the capture plugin's switch, in plugin.env
din capture exclude|unexclude|only|unonly <path>
never capture under a path, or capture ONLY the
listed paths. Applies from the next tool call.
din capture map-template [--write]
a capture map for copying THIS machine's
closed sessions to a field elsewhere
din capture --once one map pass now: live capture, PAID (no model
call unless you turned live grading on);
--dry-run says what it would record (any plan)
--field NAME places into that field;
--skip-headless leaves out `claude -p` and SDK
sessions (off by default: where all the work is
headless, leave it off and exclude paths instead)
din capture --backlog [--since DATE]
the same pass over sessions already on disk (PAID)
din capture install-task [--field NAME] [--skip-headless] [--print]
run --once every 10 minutes (PAID; a systemd
user timer, or a launchd agent on macOS).
--print shows it on any plan
din grade [status] live claim grading (the why-layer): it grades the
sessions live capture records, and live capture
is paid. On YOUR OWN inference: your assistant
CLI (Claude Code or Codex), your own API key or
a local model (`din setup model`). Plan,
credential (never printed), model, cap, spend
today, graded and pending
din grade on [--model M] [--via cli|codex|key|local] [--effort E] [--daily-cap USD]
switch it on; says the cost first (measured on
claude-sonnet-5: ~$0.46 a session median, $0.86
p90; `din grade estimate` prices yours).
--effort sets the reasoning effort (OpenAI
levels above medium need it)
din grade off switch it off (nothing is called)
din grade estimate [PATH...|--pending]
what grading would cost, by size; calls nothing
din regrade [--plan] [--model M] [--rate IN/OUT]
records graded by an older grader than this
install's: which, the scoped re-grade each takes,
and the cost on YOUR OWN inference. Free, and
calls nothing
din regrade --run [--max-spend USD]
re-grade them; lands through the store's
supersede path. Any plan; a cap you set holds
din webhooks [list|path] the field's outbound event subscriptions
din webhooks add <url> [--id NAME] [--events e1,e2] [--secret-stdin]
din webhooks remove|test <id>
https:// to any host (the field verifies it);
plain http:// on this machine only. A
host off this machine needs a signing secret,
piped in with --secret-stdin. The field re-reads
the file each rescan: no restart.
PAID: on a plan without webhooks a subscription
is saved, the field sends nothing and `test`
is refused
din console [--no-open] run the LOCAL console on loopback
din import [args...] the Upstream on-ramp (din import --dry-run first).
--source claude-code|codex|gemini-cli|qwen|cline|
chatgpt|grok ... (din import --help lists them);
grading an import runs on YOUR OWN inference,
free up to the Reader level (--ungraded places
it with no model call)
din import claude-ai <export>
your claude.ai and Claude desktop chats, from the
claude.ai data export: kept in ~/.din/vault, placed
ungraded, no model call. --grade grades them
(any plan, your own inference)
din recall <question> the compact, trust-marked digest
din recall --graded <q> the same, GRADED: ordered by what held (paid);
din recall --help
din query <filter> rows as TSV: facet=claims&state=disputed
din brief <question> the graded brief: decided / unproven / contradicted
din handoff <person> the offboarding packet for one person (paid):
what their agents worked on, the claims that
held and were refuted with receipts, the open
threads and a recall line. Says first what it
will include; asks at a terminal. --since
--project --out FILE --json; din handoff --help
din dep-audit [args] dependency risk: what your code REALLY imports,
crossed with whether the upgrade was ever shown.
JSON by default; --tsv for the human table.
READ-ONLY - it never writes the store.
din deps sync|inventory the library inventory of this machine's repositories
(lockfiles and manifests only, no network) and each
dependency's version truth: lockfile > install output >
manifest > mention. FREE.
din deps refresh|guard|brief|timer
PAID, the dependency watch (in every paid plan): a daily catalog of what
changed (vulnerabilities, deprecations, yanks, archives,
major releases, licence changes) with its blast radius,
the suspicious-package guard and the upgrade brief.
Refresh is opt-in and sends ONLY package names and
versions to public registries. `din deps help`
din org new|list|use|archive|restore NAME
client orgs (up to the signed org_cap), each its own fields,
stores, tokens and console; `din field new X --org
NAME`. Past the signed org_cap (or max_ops, `din org
ops new`) nothing is made, exit 3. `din org help`
din org whatif --map FILE the re-org simulator, before a structure change:
who would see what under a candidate org map and
owner tables, against what this install serves
today: per node gained / lost, unowned records.
--record-orgs FILE --overrides FILE --isolated N
READ-ONLY; needs no field running. Exit 1 = a
check failed. `din org whatif --help`
din plugin [status] [--json] the capture plugin's own report (what /din status
prints inside the agent): capture, spool, field,
token usage, coverage
din plugin install [args] install the capture plugin from this bundle
(Claude Code, Cursor, OpenCode; `din agent add`
wires one by name)
(also installed as `din-recall`, which the
plugin's /din recall calls by that name)
din activate <KEY> check a paid license key in (needs curl) and
install the signed entitlement it earns; it is
verified here first, or nothing is written.
`din activate -` reads the key from stdin.
din activate --file <PATH> the same OFFLINE, from a saved check-in reply
din activate --renew carry a paid install into its new billing period
from the saved key; silent when it works.
`din autostart on` runs it for you.
din license what tier this install runs as, and who decides
din license --check check the saved key in with the issuer first: a
licence the issuer has ENDED (a refund, a
cancellation at its end) goes to the free tier
now; no network changes nothing
din where every path and setting, resolved
din hosted connect|push|status|recall
ONLY if you have a HOSTED DIN console: push this
install's records to it (the one command that
sends records off this machine, and only when
run). `din hosted help` for the details.
din alm pr-check --repo OWNER/NAME --pr N --sha SHA --field https://FIELD
write what the field's record says about a PR
as ONE GitHub check run (neutral: it informs,
never blocks). Tokens from the environment
only. Paid. `din alm help` for the details.
din version
OPTIONS
--project P --since D --until D scope recall, query and brief to one project
or a date window (dates are YYYY-MM-DD)
--field NAME run status, console, import, recall, query,
brief, where, dep-audit, deps, org whatif or a
`din field` start|stop|status|ensure|log
against that field of this install
(din field list)
--k N recall: how many hits (1..50)
--json machine-readable, same rows, same grades.
On `din status` it is one JSON object with
the programs, the field, the token and the
plugin - the headless way to check an
install. Exit 0 = usable, 1 = incomplete.
--timeout-ms N give up on the field after N ms (default 8000)
START ON USE
status, console, recall, query, brief, field binding|activate and
import --status start the field first when it is down, the same way
`din field start` does, and say so on stderr. Not after `din field stop`,
never on a port something else holds, and not with DIN_FIELD_AUTOSTART=off.
WHERE IT LOOKS
$DIN_PREFIX, else the prefix this binary was installed into, else ~/din.
Settings come from <prefix>/.din/field.env; the process environment wins over
it. `din where` prints what was resolved and from where. A field din starts
is handed field.env and what din resolved, never din's own environment: a
setting for the field (DIN_PEOPLE_ROLLUP, FIELD_INDEX, ...) goes in field.env.
($DIN_HOME is NOT this. That one is the plugin's own state directory.)
REMOTE FIELDS
The field client speaks plain http, so the field token is only sent to this
machine (localhost, 127.0.0.0/8, ::1). A FIELD_URL, shared field or peer on
another host is refused unless DIN_ALLOW_REMOTE_FIELD=1 (put it behind your
own tunnel first: the token crosses the network in the clear).
din activate
USAGE
din activate <LICENSE_KEY> check the key in with the issuer and install the
signed entitlement it answers with (needs curl)
din activate - the same, the key read from stdin (keeps it out
of your shell history)
din activate the same, with the key saved in license.key
din activate --file <PATH> OFFLINE: install a saved check-in reply (the JSON
POST /api/license/verify answered) or a bare
signed envelope. No network, no curl.
din activate --renew check the saved key in again: carries a paid
install into its new billing period. Prints
nothing when it works, one line when it does
not. `din autostart on` runs it once a day.
If the issuer has ENDED the licence (a refund,
a cancellation that reached its end, a failed
payment), it says so in a signed answer and
this install goes to the free tier; the paid
file is kept as entitlement.json.revoked-<ts>.
No network, or an answer that is not signed,
changes nothing.
--url <BASE> the issuer, default https://api.dinctrl.com
(DIN_BILLING_URL sets it too)
Nothing is written unless the signed entitlement verifies on this box.
din setup --isolated
din setup --isolated - your own field, in your own tree, with no admin.
USAGE
din setup --isolated [--port auto|N] [--prefix DIR] [--force] [--dry-run]
WHAT IT LAYS DOWN, under the prefix (default: this install's prefix, else ~/din)
.din/field.token a freshly minted token, 0600, never printed
.din/field.env the settings, so `din recall` in this tree asks THIS field
.din/field.pid the running daemon, written after the kernel is asked
records/ an empty store. This field serves these and nothing else.
logs/field.log
field.sh start | stop | restart | status | log
README-FIELD.md how to run it, in the tree, so it travels with the tree
OPTIONS
--isolated required. The one recipe this command has.
--port auto|N auto (the default) scans for a free loopback port.
A number is used as given, and refused if it is taken.
--console-port auto|N
the same, for `din console` in this tree. auto scans
upward from the field's port + 1: to 8299 inside DIN's
port band (8200-8299), or the 100 ports above a field
whose port is past the band.
--prefix DIR where the tree goes.
--programs DIR where the programs are, when this tree borrows them from
an install elsewhere. Default: this install's bin/.
--force re-mint the token over an EXISTING field at this prefix.
Records are never deleted; the old token is kept beside
the new one as field.token.previous.
--no-start lay it down, do not start the daemon.
--dry-run print every step, touch nothing.
NO ROOT. NO POSTGRES. NO SYSTEMD. One loopback port, one token, one daemon
started by the user who will use it. It does not touch any other field.
NOT A WHOLE INSTANCE. It stands up no database, no service manager and no
machine. It makes a workspace its own private field on a box that already
works: if you wanted a tree of your own, this is the command you wanted.
din capture
Capture settings, and the capture pass: din capture --once records the closed Claude Code sessions of the project folders listed in ~/.din/capture-map.json with din-session-record --no-model (no model call, no cost). Live capture is a paid feature.
usage: din capture [status] [--json]
din capture on|off
din capture exclude <path> never capture under this path
din capture unexclude <path>
din capture only <path> capture ONLY the listed paths (an allowlist)
din capture unonly <path> (an empty allowlist captures every project)
usage: din capture --once | --backlog [--since DATE] [--dry-run]
[--field=NAME] [--skip-headless]
[--map FILE] [--state FILE] [--log FILE] [--spool DIR] [--projects-root DIR]
[--idle-secs N] [--reship-secs N] [--machine NAME] [--producer BIN]
[--b6-patterns FILE] [--verbose] [--scrub-secrets | --no-scrub-secrets]
[--live-grade] [--grade-settle-hours H] [--grade-daily-cap N] [--grade-model M]
din capture install-task [--field=NAME] [--skip-headless] [--print]
din capture map-template [--write] [--map FILE] [--machine NAME]
The map pass records the closed sessions of the project folders the capture map
allowlists (today the session store it reads is Claude Code's:
~/.claude/projects/<claude_dir>), one run dir each, with din-session-record
--no-model: no model call, no cost, unless you turned live grading on (below).
Nothing outside the map is read, and nothing is ever written into ~/.claude.
The pass is live capture, a PAID feature: --once, --backlog and install-task need
a licence that signs live_capture (din activate). --dry-run, install-task --print
and map-template run on any plan; history import (din import) is free.
--once one pass now (what install-task runs every 10 minutes)
--backlog the same pass, to catch up on the sessions already on disk
--since DATE only sessions last written on or after DATE
(YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ; needs --backlog)
--dry-run print what would be captured; write nothing at all
--field=NAME place through dinctrl-store into this field (din field list), unless
the project has a route of its own (din field route). With no
capture map, read every project din capture exclude|only allows,
from now on: --backlog asks for what is already on disk
--skip-headless leave out `claude -p` and SDK sessions (the map's
"skip_headless": true does too). Off by default. On a box where
all the work is headless (supervisor mode) do NOT turn it on: it
would leave out everything. Exclude only the dirs you do not want
captured, e.g. din capture exclude ~/agent-runs
--map FILE the capture map (default $DIN_HOME/capture-map.json)
--state FILE what was shipped, by content hash (default $DIN_HOME/capture-state.json)
--log FILE the pass log (default $DIN_HOME/capture.log)
--spool DIR run dirs waiting to ship (default $DIN_HOME/spool)
--projects-root DIR where the sessions are (default ~/.claude/projects)
--idle-secs N a session is closed once it has not grown for N s (default 900)
--reship-secs N re-ship a grown session at most every N s (default 21600)
--machine NAME this machine's name in the map (default: the map's, else the host's)
--producer BIN the din-session-record to run (default: $DIN_SESSION_RECORD_BIN,
else beside din, else PATH)
--b6-patterns FILE the B6 personal-content patterns (default $DIN_HOME/b6-patterns.json)
--scrub-secrets secret-scrub the shipped session.jsonl this pass, whatever the map says
(the default: the scrub is ON unless the map says false)
--no-scrub-secrets do NOT secret-scrub the shipped session.jsonl this pass, whatever the
map says (exposures are still detected and reported)
--verbose say why each session was captured or not
security: every captured session is checked for exposed credentials BEFORE the scrub; a
critical one is reported as a `[security] CRITICAL ...` line (class, fingerprint, where;
never the value) in the log and on stderr, and security.json ships with the run dir.
Rotate every credential it names.
live grading of captured sessions (live capture is paid; a model call on YOUR OWN model account, which costs
you money, never DIN's: your assistant CLI, your own API key or a local model):
--live-grade grade closed sessions this pass, whatever the map says
--grade-settle-hours H grade a session only once it has not grown for H hours (default 24)
--grade-daily-cap N at most N possibly-billed grading attempts per UTC day (default 10)
--grade-model M the model to grade with (default: din grade's, else the map's;
there is no vendor default: with none named, nothing is graded)
Each flag beats `din grade` and the map's live_grade for this pass.
A dollar cap (din grade on --daily-cap USD) cannot count a model no card prices on a
path that may bill per call (an OpenAI key, for one): there it is not used, and grading
is held to 3 attempts a day (or your own --grade-daily-cap N).
where a grading call goes: the plugin's hooks read the proxy and CA (HTTP_PROXY,
HTTPS_PROXY, ALL_PROXY, NO_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, CURL_CA_BUNDLE,
NODE_EXTRA_CA_CERTS), ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK/VERTEX,
CLAUDE_CONFIG_DIR, CODEX_HOME, XDG_CONFIG_HOME, DIN_TRANSCRIPTS and DIN_ENTITLEMENT from
~/.din/plugin.env only, never from a session's environment (with DIN_TRUST_ENV=1 in
plugin.env, from the environment too). `din setup model` copies your shell's proxy and CA
there. din capture itself takes the proxy, CA and transcript roots from its own environment.
install-task run `din capture --once` every 10 minutes (a systemd user timer, or a
launchd agent on macOS); --print shows it, installs nothing
map-template print the starter map: scrub_secrets ON, live grading OFF, one example
project NOT enabled. --write puts it at --map, only when no map is there
map keys (beside "projects"):
"scrub_secrets": true secret-scrub the shipped session.jsonl (absent: ON; only
the literal false turns it off)
"live_grade": {"enabled": true, "settle_hours": 24, "model": M}
grade at capture (absent or not literal true: OFF;
"daily_cap": N holds it to N attempts a day;
honoured on any plan that runs the pass, on your
own model account)
din grade
Live grading of captured sessions. It grades what live capture records, and live capture is a paid feature; an import grades on any plan, up to Reader on Free. It runs on your own inference: your assistant CLI (Claude Code or Codex), your own API key or a local model (din setup model); none of the Codex, key or local paths has been validated against a real vendor yet. din grade on --effort sets the reasoning effort (OpenAI levels above medium need it). din grade on says the cost first; din grade estimate makes no model call.
usage: din grade [status] [--json]
din grade on [--model M] [--via cli|codex|key|local] [--effort E] [--daily-cap USD] [--settle-hours H]
[--two-level [--scan-model M] [--deep-per-day N] | --one-level]
[--model-profile P | --chunk-chars N | --context-tokens N
| --output-reserve-tokens N | --chars-per-token X | --default-window]
din grade off
din grade estimate [PATH ...] [--pending] [--model M] [--json]
Live claim grading (the why-layer) grades the sessions live capture records, and
live capture is a paid feature (an import grades on any plan, up to Reader). It runs
on YOUR OWN inference, the first of these that can run your model: the Claude
Code CLI (`claude`); the Codex CLI (`codex`, on your ChatGPT plan, for a gpt- model);
your own key (ANTHROPIC_API_KEY for a Claude model,
OPENAI_API_KEY for an OpenAI model, DIN_MODEL_BASE_URL with DIN_MODEL_API_KEY for
any OpenAI-compatible endpoint); a local model (DIN_MODEL_BASE_URL at Ollama, vLLM
or llama.cpp on this machine). --via picks one; --effort sets the reasoning effort
where the path takes one, and a gpt- model's reading level hangs on it (default
medium: gpt-6-sol reads at Reader). `din setup model` sets any of
them up. Your key stays on this machine and goes only to the provider you chose.
DIN never pays for inference, never bills you for it, and never stops a run for
cost: the only cap is one you set with --daily-cap. Measured cost: about $0.46 a
session (median), $0.86 at the 90th percentile, on claude-sonnet-5 at list rates.
A model no card prices reads as unknown cost, never a guess, and a daily cap has
no dollars to count for it.
`estimate` prices sessions by size and calls nothing.
Two levels (--two-level): every session is read once at the Scanner level (the
card's cheapest Scanner model for your path, or --scan-model), a free rule picks
what that read found worth more (a decision, 3 or more claims, a read cut short),
and only those are read again with --model, which must be rated Archivist or
above. A session costs its scan, and a picked one its scan plus a whole deep read:
`estimate` prices both reads, and the daily cap counts both. An Archivist stamp
needs a paid plan and a whole read in one call; a read in chunks, or on Free, is
stamped Reader whatever the model. A ChatGPT plan has no dollars to cap, so
two levels on one need --deep-per-day N. `din capture` reads in two levels; your
agent's own capture (the plugin) reads in one pass with --model until din-regrade
drives its producer. --one-level turns it off.
The grading window: Free grades in 40,000-character chunks; a paid licence sets
the window by profile or explicitly. Profiles by reading level: scanner (a
32K-token window), reader (128K), analyst, archivist, scholar (the whole
thread read in one call: the window is opened to 1M tokens, and a chat larger
than your model reads is chunked and stays below Analyst; which of the three you reach
is your model's level). The older names still work: claude-sonnet-5,
claude-opus, claude-haiku (60,000 characters); ctx-32k, ctx-40k, ctx-64k,
ctx-128k. `--default-window` clears what was set.
din handoff
The offboarding packet for one person (paid: succession_packet, every paid plan). It asks the field's GET /api/succession/packet and writes what the field assembles; no model is called.
usage: din handoff <person> [--since DATE] [--until DATE] [--project P] [--out FILE] [--json] [--yes]
The offboarding packet for one person (paid: succession_packet, every paid plan).
<person> is the id their records carry (identity.by.id, e.g. ada@laptop); with
DIN_PEOPLE_ROLLUP=on, `GET /api/tree?people=under` on the field lists them.
It asks the field for the packet (GET /api/succession/packet), which holds:
- what the person's agents worked on, per project;
- the claims that HELD and the claims that were REFUTED, each with its grade,
the grader that wrote it and the record id + entry it came from;
- the open threads;
- one recall line for the successor to paste into their next session.
Only records whose provenance.b6 shows the personal-content filter ran give
any text; the others are counted and named by id. No model is called.
First it prints, on stderr, what the packet will include and how many records.
At a terminal it then asks before writing (--yes skips the question); not at a
terminal it writes without asking.
--since / --until a date (YYYY-MM-DD) or an RFC3339 time
--project P one project only
--out FILE write to FILE, created new (an existing file is refused),
owner-only on Linux and macOS; without it, stdout
--json the packet's JSON instead of its Markdown
--yes do not ask at a terminal
din import (din-import)
din import [args...] runs din-import with the same arguments. din import claude-ai <export> reads the claude.ai data export.
din-import - point DIN at your chats and it works.
Bare `din-import` runs the wizard. It looks before it asks, it tells you what an
import will cost before it starts, and it runs the review on your own inference:
the Claude Code CLI (`claude`), your own API key, or a local model (`din setup
model`), or, experimental, your own signed-in Codex CLI (--via codex). DIN never
runs model calls on our account.
USAGE
din-import wizard (default entry point)
din-import --source claude-code [--path P] detected sessions on disk
din-import --source codex [--path P] Codex rollouts on disk
din-import --source gemini-cli [--path P] Gemini CLI sessions on disk
din-import --source chatgpt --export P the data-export zip or directory
din-import claude-ai <export.zip|dir> your claude.ai and Claude desktop chats (the
claude.ai data export, or archive .txt files):
kept in your vault, placed ungraded, no model
call; --grade grades them (a cap you set with
--max-spend holds), on any plan, on your own inference
din-import --source grok --export P Grok chats in an X (Twitter) archive
din-import --source cline [--path P] Cline, Kilo Code or Roo Code tasks
din-import --source qwen [--path P] Qwen Code sessions on disk
din-import --source claude-mem [--path P] a claude-mem store's JSONL spine
din-import --source upload --file P generic, against the record contract
din-import --source inbox whatever you dropped in ~/din/inbox
din-import --dry-run the plan and a sample record, no calls
din-import --apply place it, free; with --grade, run the review on your own inference
din-import --model <id> pick the review model
din-import --via codex EXPERIMENTAL: grade on your signed-in Codex CLI
din-import --max-spend <amount> pause and ask at this running estimate
din-import --status progress, running cost, state
din-import --pause | --resume | --stop process control
din-import --log the verbose log for bug reports
din-import --advanced print the plan, run nothing
din-import --workers <n> override concurrency
din-import --tools show the tooling this wrapper drives
din-import scrub [--store D] re-redact a store with today's table (dry run;
--apply --backup B rewrites, originals to B)
WHERE YOUR CHATS GO
~/din/inbox. Drop exported conversations there and run din-import: the inbox
is scanned on every run, offered like any other source, and each file in it is
either read or named with the reason it cannot be. The directory and a short
guide (README.txt) are created the first time this runs. $DIN_HOME/inbox if
that is set, $DIN_INBOX if you set that.
OTHER FLAGS
--limit <n> consider at most this many conversations
--home <dir> state directory (default $DIN_HOME or ~/.din/import)
--field <dir> the record store this import writes into
--prompt <file> the interpretive contract to use instead of the one this
build ships. Bring your own: it is sent verbatim, exactly
as the shipped one is. Also settable as DIN_PROMPT
--run <id> operate on this run id instead of the latest
--yes answer yes to every confirmation (scripting)
--retry-escalated with --resume: try again a run that stopped retrying
after your provider refused it repeatedly
--retry-refused with --resume: send the conversations an earlier pass
recorded as refused or failed again (a plain --resume
never re-sends them: a refusal is never retried into
compliance, and a failure was already paid for)
--max-spend <usd> with --resume: continue under this ceiling instead of
the run's stored one. A resume always runs under the
run's ceiling, and one already reached needs a higher one
--max-calls <n> stop the run after this many model calls. Any grader;
the cap for one that reports no dollars (Codex on a
ChatGPT plan), where --max-spend cannot hold
--max-tokens <n> stop the run once this many tokens (in + out, as the CLI
reports them) are booked. Any grader
--stagger <secs> seconds between worker starts (default 15)
--vault <dir> claude-ai: where the originals are kept (default $DIN_VAULT,
else ~/.din/vault); the vault gets a claude-ai/ folder
--grade grade on your own model credential, any source, any plan
(free). claude-ai: prints the estimate first; a cap you
set (--max-spend, --max-calls or --max-tokens) holds. It also
grades what an earlier import placed ungraded
--regrade with --grade: also grade what an earlier run graded under
another contract, model or reading level. The old version
is kept by the writer. The same grade is not paid for twice
--ungraded place every conversation UNGRADED: no model call, nothing
spent, any source. The default when no model credential
is connected; a later --grade grades them
--no-scrub-secrets claude-ai: keep the byte-for-byte original in the vault,
credentials and all, instead of the secret-scrubbed copy
(the default). Exposed credentials are still reported
-h, --help this
-V, --version version
DRY RUN IS THE DEFAULT WHEN NOBODY IS THERE TO ASK
Run without a terminal and without --apply and you get the dry run: the plan,
the estimate, and a sample of the record this import would build, with no
model call and nothing written to your field. --apply is how you say go.
Interactive runs still ask on the cost screen instead.
WHAT IT COSTS
Nothing to us. The review runs on your Claude Code CLI (your signed-in
account or your own Anthropic key), on the Codex CLI you chose with
--via, on your own API key (key), or on a local model (local) that
`din setup model` connected; the bill goes to that provider, and a
local model bills nobody. --dry-run prints the estimate and imports
nothing.
GRADING ON CODEX (EXPERIMENTAL)
--via codex runs the review on the OpenAI Codex CLI you are already signed in
to (your ChatGPT plan), locked down: every tool turned off, its own
instructions replaced, your Codex config and rules not read. Never picked
for you: Claude stays the default even when all three are installed. Grades
from those models have not been validated against DIN's grading tests;
Claude is the validated path, and every record says which CLI graded it.
Codex reports no cost, so none is shown. DIN does not install it or sign you
in. --via gemini is refused: the Gemini CLI cannot be run with its read-only
tools turned off, and a conversation under grading is untrusted text.
CLAUDE.AI AND THE CLAUDE DESKTOP CHAT TAB
din import claude-ai <export>. Request the export at claude.ai, Settings,
Privacy, Export data; point at the zip, its folder, or conversations.json.
The desktop app's chats are the same account, so they are in it. A folder of
archive .txt conversations (Upstream DIN's form) reads too.
Every conversation is kept in ~/.din/vault/claude-ai/<yyyy-mm>/ with a line
in manifest.jsonl, and your export is only read. The kept copy is
secret-scrubbed (each credential replaced by [redacted:<class>]; the manifest
says so, with counts, never a value); --no-scrub-secrets keeps it byte for
byte instead. Before that, each conversation is checked for exposed
credentials: a critical one is reported as a `[security] CRITICAL ...` line
(its kind, where, a fingerprint, never the value). Rotate what it names. A
conversation already in the vault is skipped, so importing the same export
twice changes nothing. Records are placed UNGRADED: no model call, nothing to pay, free
tier included. --grade grades them, on any plan (free), through the review
above, on your own inference (your assistant CLI, your own API key or a local
model): the estimate is printed first, and a
--max-spend you set stops the run at that figure. --dry-run reads
and shows, and writes nothing.
din-grade
The grader. din-import hands it every grading command (din grade, a graded din import); it is not run by hand, and says so:
din-grade is the grader `din import` runs; it takes its command as a request on stdin (din-importer/DIN-GRADE-CONTRACT.md). Run din-import instead.
din dep-audit (din-dep-audit)
din dep-audit [args] runs din-dep-audit, passing its flags through. From din the report is JSON by default; --tsv asks for the table.
usage: din-dep-audit [-h] [--store STORE] [--scope {all,code}]
[--json] [--top TOP]
[--origin {external,stdlib,internal,unknown,all}]
[--lang LANG] [--dep DEP] [--stale-days STALE_DAYS]
[--evidence] [--out OUT] [--fail-over FAIL_OVER]
[--now NOW] [--cache CACHE]
Dependency risk from the call graph crossed with the honest record. READ-ONLY:
it never writes the store and never touches code.
options:
-h, --help show this help message and exit
--store STORE the durable record store dir (else $STORE). No baked-in
default.
--scope {all,code} which records to read (default all). code reads only
records carrying code (a code block, a source path, a
manifest name) or naming a dependency the code
imports, and skips the rest unparsed
--json the full report as JSON (schema din-dep-audit/1)
--top TOP rows to print (default 20; 0 = all)
--origin ORIGIN which origins to report (default external; repeatable)
--lang LANG restrict to a language (repeatable)
--dep DEP restrict to a named dependency (repeatable)
--stale-days DAYS no activity in the record for this long = quietly
unmaintained (default 120)
--evidence in TSV mode, print the cited claims/experiments under
the table
--out OUT write the report here instead of stdout - the ONLY path
this tool writes
--fail-over RISK exit 3 if any reported dependency scores above this risk
(a CI gate)
--now NOW fix 'now' for reproducible output (tests): the report's
generated_at, and the instant ages are measured
against. Without it generated_at is the clock and ages
are measured against the store's newest record (named
as ages_as_of), so an unchanged store reports the same
ages every time; when that record is more than 7 days
behind the clock the report says so (ages_lag)
--cache CACHE keep what this audit learned in CACHE (a directory
outside the store) so the next audit re-reads only
the records that changed. Never inside --store
dependencies facet (read from the store, no network):
Conversation records that carry the dependencies facet (top-level
`dependencies`, deps-v1, written by `dinctrl-store deps-scan`) add, per dependency: who
introduced it, in which session, when and from where, the version(s) in use
now, copied code, and the flags introduced_by_agent, version_drift,
copied_code and licence_risk. A store without the facet reports as before.
enrichment (OFF BY DEFAULT; CATALOG-ONLY BY DEFAULT):
--enrich maintenance, vulnerabilities and licence for the
reported external dependencies the catalog holds,
LIBRARY CATALOG on this machine: latest version and
how far behind, last release, deprecated/yanked,
archived/last commit, registry licence, OSV
vulnerabilities with severity, download counts.
NOTHING IS SENT: this tool contacts no host (the
catalog is downloaded by `din-libcatalog fetch` from
catalog.dinctrl.com, which is sent no package name).
A name the catalog lacks is not_in_catalog, and how
much it holds differs by ecosystem: some carry only
advisories, with no package facts at all (see
coverage in `din-libcatalog verify --installed`). With no
catalog installed it refuses (exit 2). Adds the flags
unmaintained, archived, deprecated, yanked,
known_vuln:<severity>, licence_risk. A dated snapshot
(as_of): it never changes a grade.
--libcatalog DIR the installed catalog (`din-libcatalog fetch`'s
`current` dir); else $DIN_LIBCATALOG, else
$DIN_HOME/deps/libcatalog/current (DIN_HOME defaults
to ~/.din). Refused past the expiry signed into its
trusted comment (deps-08); its age and expiry are in
the report (enrichment.local_source.catalog)
--allow-stale use a library catalog past its signed expiry anyway
(flagged expired in the report)
--enrich-registries OPT IN (NETWORK; the old name --live-fallback works
too): ask the PUBLIC registries for the names the
catalog lacks (every name, with no catalog). PRIVACY:
this SENDS PACKAGE NAMES AND VERSIONS to crates.io,
registry.npmjs.org, api.npmjs.org, pypi.org,
proxy.golang.org, rubygems.org, repo.packagist.org,
packagist.org, api.nuget.org, repo1.maven.org,
api.github.com and api.osv.dev - never a path, code
or record content, and never a name a private
registry may serve (the store's inventory; this
machine's .npmrc, pip.conf, cargo config, Maven
settings.xml, Gradle init scripts, Go env,
NuGet.Config). It also fetches the popular rankings
from azuresearch-usnc.nuget.org, hugovk.dev and
packagist.org; a ranking fetch is sent no package
name. Those are every host it contacts;
--registry-base replaces one. Needs curl.
--enrich-cache DIR where answers are kept (never inside --store); without
it, <--cache>/enrich
--enrich-ttl-hours N reuse a cached answer this long (default 24)
--offline answer from the cache only, whatever its age; nothing
is fetched (a missing answer is reported not_cached)
--slowing-days N no release or commit for N days = slowing (default 270)
--unmaintained-days N ...= unmaintained (default 548, about 18 months)
--github-token-file F a file holding a GitHub token, for the rate limit
(else the file named by $DIN_GITHUB_TOKEN_FILE).
Never a token on the command line
--registry-base NAME=URL
point one source at a mirror (crates, npm, pypi,
goproxy, rubygems, github, osv, npmdl, packagist,
packagistapi, nuget, nugetsearch, maven, pypitop);
repeatable
dependency library maintenance (subcommands; each has --help):
din-dep-audit inventory the version truth of every dependency (lockfile >
install output > manifest > mention) and version_drift
din-dep-audit refresh NETWORK: dated catalog snapshots, diffed into events
(new_vuln, vuln_fixed, deprecated, yanked, archived,
unmaintained, major_release, licence_changed)
din-dep-audit brief NAME the upgrade brief: what changed and its blast radius
din-dep-audit guard the suspicious-package guard over installs
din org whatif (the re-org simulator)
It needs a streamfieldd with the simulator (streamfieldd --whatif) and refuses by name a field server without it. It reads the store from disk, writes nothing and needs no field running, so it is safe beside a live field. Its exit code (0 pass, 1 a check failed) can gate a cutover.
din org whatif - the re-org simulator, before a structure change is applied.
USAGE
din org whatif --map FILE [--record-orgs FILE|none] [--overrides FILE|none]
[--isolated NODE,...] [--scopes NODE,...] [--json] [--field NAME]
Who would see what under a CANDIDATE org map and owner tables, read from
this field's store with the field's own rules, compared with what this
install serves today: per node the records a token bound there would read,
the records it gains and loses (a node that moved), records nobody owns,
and owners the candidate map has no node for.
--map FILE the candidate map (required)
--record-orgs FILE the candidate's record-orgs table; default: the one
the field runs with. `none` = no table.
--overrides FILE the candidate's override table; default: the one
the field runs with. `none` = no table.
--isolated NODE,... fail if any node outside NODE's subtree (and not above
it) would read NODE's records
--scopes NODE,... print only these nodes (the checks still cover all)
--json one JSON object, the simulator's own
THE BASELINE is this install: the map its field loads (FIELD_ORGMAP, else
projects-map.json beside streamfieldd) with the owner tables the field runs
with. A field started by din takes FIELD_RECORD_ORGS and
FIELD_RECORD_ORG_OVERRIDES from din's environment, not from field.env; when
field.env names a different table, the report says so. With no map served
there is no baseline, and the report shows the candidate alone.
READ-ONLY: it reads the store from disk, writes nothing, and needs no field
running. Exit 0 pass; 1 a check failed (a leak, an unowned record, or a
record owned only by nodes the candidate map lacks); 2 refused (usage, a
file the field would refuse, or a streamfieldd without the simulator).
din-record
The record producer. The plugin uses it to turn a session into records.
usage: din-record --run RUN [--model MODEL] [--no-model] [--repo-root REPO_ROOT]
[--prompt PROMPT] [--timeout TIMEOUT] [--org-node ORG_NODE]
[--by BY] [--by-kind {person,agent,machine,org,unknown}]
[--project PROJECT]
[--b6-off] [--b6-strict] [--b6-patterns PATH]
[--expect-prompt-version X]
[--two-pass]
[--tier free|paid] [--model-profile NAME] [--chunk-chars N]
[--context-tokens N] [--output-reserve-tokens N]
[--chars-per-token X] [--max-calls-per-record N]
[--runner claude|codex|http] [--claude-bin PATH] [--codex-bin PATH]
[--base-url URL] [--api-key-env NAME] [--effort E]
din-record --label-only --record RECORD.json --session LOG [--out PATH]
[--model MODEL] [--prompt PROMPT] [...]
DIN CTRL record producer: turns a run's receipts into a record; receipted only
when every receipt verifies against RECEIPT_HMAC_KEY (Rust port of
receipt/record.py). Without the key a signed-looking run is `logged` with the
flag `receipted_unverified`; DIN_RECEIPTS_SHAPE_ONLY=1 restores the old
shape-only grading.
options:
--run RUN run dir, e.g. runs/46
--model MODEL model for the ONE interpretive call (a pinned id on the
model card; default claude-sonnet-5 on the claude runner,
none on another)
--runner claude|codex|http the model runner (din-runner; also
DIN_RECORD_MODEL_TRANSPORT; default claude)
--claude-bin PATH --codex-bin PATH that runner's CLI (default: on PATH)
--base-url URL --api-key-env NAME the http runner's OpenAI-compatible
endpoint and the NAME of the env var holding its key
--effort E a reasoning effort the runner takes (codex, http)
--no-model observed facets only (honest-failure path, no model call)
--repo-root PATH where the FROZEN contracts live (default: two levels up)
--prompt PATH the interpretive contract to use, overriding --repo-root.
Without it: DIN_PROMPT, then <repo-root>/PROMPT-...-v1.md,
then the sealed din-contract provider.
--expect-prompt-version X
pin the contract for a re-grade (also
DIN_EXPECT_PROMPT_VERSION). A contract, file or sealed
provider, that states any other version or states
none exits 2 before any model call. A blank value
is refused (exit 2); it never unpins the env.
--contract-id print the contract a graded run would use (its stated
prompt_version and the sha256 of the instruction block)
and exit: no model call, no --run needed, no contract
text printed. Exit 2 when no contract would load.
--two-pass prompt 1.7.2 with a `## THE LABEL PROMPT` section: pass 1
extracts the claims (as today), pass 2 labels that FIXED
set (also DIN_TWO_PASS=1). Default: one pass.
--tier TIER grader 1.7.4 (a 1.7.4 contract): the licence tier the
caller resolved, free or paid (also DIN_TIER;
default free). Free grades in a fixed 40,000-char
window and refuses every window flag below; paid reads
to the model's budget, a chat that fits in one call, or
by profile or explicitly.
Below 1.7.4: no effect.
--model-profile NAME, --context-tokens N, --output-reserve-tokens N,
--chars-per-token X, --chunk-chars N
the chunk window (paid; --chunk-chars wins)
--max-calls-per-record N
grader 1.7.4's optional spend guard: at most N calls
(the record says what was left unread)
--label-only the cheap re-grade: pass 2 ALONE over --record's stored
claims, against --session; ids kept, the old labels kept
in provenance.relabel_history. Writes --out (default:
over --record).
--timeout TIMEOUT
--org-node ORG_NODE org node id for the run's channel (e.g. acme)
--by BY identity.by id - who this run is attributed to
--by-kind KIND kind for --by (default person): person, agent (an AI
agent), machine, org or unknown. A NODE is a person, an
AI agent or a machine; any other value is refused
--project PROJECT project_affiliation.primary for this run. Without it:
the base name of --repo-root when one is given, else
the run's own label (DIN_CHANNEL, else the base name
of the session cwd in <run>/meta.json), else empty.
--b6-off record deliberately WITHOUT the personal-content filter
(only this flag: DIN_B6 is ignored). On by default: it runs
over the grader's transcript before the model call and
over the record, and stamps provenance.b6.
--b6-strict redact the ambiguous shelf too
--b6-patterns PATH the B6 policy file. Without it: DIN_B6_PATTERNS, then
b6-patterns.json beside this binary or in ../scripts/,
then the copy compiled in.
Exit: 0 written; 1 a write failed, or the record has structural problems;
2 refused before any model call; 3 no receipts; 5 failed AFTER a model call
was made (it may have billed).
din-session-record
The capture producer. din capture --once runs it for each closed session, with --no-model.
usage: din-session-record --session SESSION --rundir RUNDIR [--model MODEL] [--no-model]
[--timeout TIMEOUT] [--channel-id ID] [--org-node NODE] [--flag F]...
[--capture-machine NAME] [--source-path ORIGINAL] [--by BY]
[--by-kind {person,agent,machine,org,unknown}] [--b6-off]
[--b6-patterns FILE]
[--b6-strict] [--b6-model-cmd CMD] [--prompt PATH]
[--expect-prompt-version X]
[--tier free|paid] [--model-profile NAME] [--chunk-chars N]
[--context-tokens N] [--output-reserve-tokens N]
[--chars-per-token X] [--max-calls-per-record N]
[--runner claude|codex|http] [--claude-bin PATH] [--codex-bin PATH]
[--base-url URL] [--api-key-env NAME] [--effort E]
DIN CTRL logged record producer (claude-code-jsonl); the Rust port of
session-recorder/session_record.py. Same arguments, same record.json and
records/code-*.json bytes, same summary line, same exit codes.
--session PATH Claude Code session .jsonl
--rundir DIR run dir to write record.json into
--model MODEL model for the ONE interpretive call (a pinned id on the model
card; default claude-sonnet-5 on the claude runner, none on another)
--runner claude|codex|http the model runner (din-runner; also DIN_RECORD_MODEL_TRANSPORT;
default claude); --claude-bin / --codex-bin PATH that runner's CLI;
--base-url URL --api-key-env NAME the http runner's endpoint and the
NAME of the env var holding its key; --effort E (codex, http)
--no-model observed facets only (honest-failure path; no model call)
--two-pass 1.7.2 with a label section: pass 1 extracts the claims, pass 2
labels that fixed set (also DIN_TWO_PASS=1). Default: one pass
--timeout SECS interpretive call ceiling (default 420)
--channel-id ID the recording channel id (a bus channel number, or a run
name such as cc-1a2b3c4d); default: <rundir>/channel.txt
--org-node NODE org node id for identity.agent_context (default $DIN_ORG_NODE)
--flag F extra flags[] entry (repeatable), e.g. unreceipted
--capture-machine M provenance.capture_machine: the machine the log was read on
--source-path PATH the ORIGINAL log path when --session is a verbatim copy
--by ID identity.by id (highest precedence; never a token)
--by-kind KIND kind for --by (default person): person, agent (an AI agent),
machine, org or unknown; any other value is refused
--b6-off disable the personal-content filter (only this flag: DIN_B6 is ignored)
--b6-patterns FILE pattern file (default $DIN_B6_PATTERNS, else the kit's
b6-patterns.json, else the built-in copy of it)
--b6-strict redact the AMBIGUOUS shelf too, without asking a model
--b6-model-cmd CMD OPTIONAL escalation hook program for ambiguous spans
--prompt PATH the interpretive contract to use (as din-record's --prompt);
a path that does not exist falls through to the chain below
--expect-prompt-version X
pin the contract for a re-grade (also
DIN_EXPECT_PROMPT_VERSION). A contract, file or sealed
provider, that states any other version or states
none exits 2 before any model call.
A blank value is refused (exit 2); it never unpins
the env.
--contract-id print the contract a graded run would use (its stated
prompt_version and the sha256 of the instruction
block) and exit: no model call, no --session or
--rundir needed, no contract text printed. Exit 2
when no contract would load.
--tier TIER grader 1.7.4 (a 1.7.4 contract): the licence tier the
caller resolved, free or paid (also
DIN_TIER; default free). Free grades in a fixed
40,000-char window and refuses every window flag
below; paid reads to the model's budget, a chat that
fits in one call, or by profile or explicitly.
Below
1.7.4: no effect.
--model-profile NAME, --context-tokens N, --output-reserve-tokens N,
--chars-per-token X, --chunk-chars N
the chunk window (paid; --chunk-chars wins)
--max-calls-per-record N
grader 1.7.4's optional spend guard: at most N calls
The contract for the interpretive call: --prompt, else
$DIN_CONTRACTS_DIR/PROMPT-interpretive-v1.md, else <this binary's
dir>/../PROMPT-interpretive-v1.md, else the sealed din-contract provider
din-record uses.
Exit: 0 written; 1 a write failed, or the record has structural problems;
2 refused before any model call; 5 failed AFTER a model call was made (it
may have billed).
dinctrl-store
The one writer that places records in the store.
dinctrl-store - DIN CTRL durable record store
USAGE:
dinctrl-store ingest --runs <root> --store <dir> [--b6-patterns FILE] [--regrade [--producer-allow FILE]]
[--producer PATH ...]
dinctrl-store ingest --run <dir|record.json> [--run ...] --store <dir> [--db FILE]
[--force [--no-downgrade]] [--rebuild-index]
[--no-git] [--fail-on-reject]
--no-git: the store is NOT staged (by default it is:
git init + git add -A, never a commit; see THE STORE IS
A GIT REPOSITORY below). --fail-on-reject: exit 4 when
something this pass did not land (see EXIT CODES).
ingest.py's flags: --force rewrites only records whose bytes
differ (the ingested_at stamp keeps the first placement);
--no-downgrade never replaces a distilled record with an
undistilled one; --db and --rebuild-index build NO index
(nothing live reads index.db) and print the INDEX line.
B6 is always on for ingest: DIN_B6 and DIN_B6_PATTERNS
inherited from the environment are ignored.
dinctrl-store ingest ... [--no-redact]
CREDENTIALS ARE REDACTED AT WRITE TIME, by default:
every record whose id is its content hash has each
high-confidence credential in its own text replaced by
[REDACTED] before it is compared or written, by
security-scan --write's own record pass (the shared
table, confirmed; low-confidence spans are counted and
left). The record's `security` facet carries the note
(redacted_by ingest-v1, spans, classes, fields; never a
value), its MANIFEST line counts it, and every pass
prints ONE stderr line: `redacted N spans in M records`.
The id, identity and content_hash never move. No copy of
the record as it arrived is written anywhere.
--no-redact: a FORENSIC import only. The spans stay in
the clear, are counted, and the pass warns loudly; no
wrapper passes it. security-scan --write redacts later.
dinctrl-store ingest ... [--weave | --weave-all | --no-weave]
THE WEAVE (plan §4d B2), default ON for schema 3.7.0+
records (--weave), OFF for older ones unless --weave-all;
--no-weave turns it off. Each new record's tested/observed
claims are fingerprinted (their preserved artifacts, else
verbatim_content) and linked to the field's earlier ones:
corroborates (same fingerprint), contradicts (same
fingerprint, opposite outcome), forks (same name, diverged
fingerprint). Edges are written to both ends,
<dir>/edges/<id>.jsonl, append-only, idempotent; the
record is never changed. SIGNAL RULES (signal-1): an
edge also needs the two CLAIMS to share their subject,
preserved artifacts to match literally (not only in
shape), contradicts a runner/claim verdict (not an exit
status), forks a real script/item name; one edge per
claim pair. Refused pairs are counted on the
`weave refused` line.
dinctrl-store weave --store <dir> [--rebuild [--all] [--no-swap]]
the live edges by type; --rebuild re-derives the
fingerprint index AND every edge from the stored
records by the current rules, without re-ingesting:
built in <dir>/.weave-rebuild-<stamp>/, then the live
edges/ and fpindex/ are MOVED to
<dir>/.weave-prev-<stamp>/ (never deleted) and the new
ones put in their place; --no-swap leaves them built
beside the live ones.
dinctrl-store fpindex --store <dir> [--rebuild] [--all]
the weave's fingerprint index (<dir>/fpindex/index.jsonl):
prints its size (and any torn line it skipped);
--rebuild re-derives it from the stored records (3.7.0+,
or every record with --all) and MOVES the live one to
<dir>/.fpindex-prev-<stamp>/ (never deleted). Edges are
never touched.
dinctrl-store deps-scan --store <dir> [--runs <root>] [--sessions <dir>]...
[--record <id>]... [--write]
THE DEPENDENCIES FACET BACKFILL (top-level `dependencies`): for
each conversation record whose exact session is found
(identity.content_hash = sha256 of session.jsonl, in
identity.path, <runs>/<channel>, or any *.jsonl under a
--sessions dir), builds the facet from the session's tool
calls and output: installs, manifest/lockfile changes,
external fetches, copied code, licences. An install whose
own flags (--registry, --@scope:registry, --index-url, -i,
--extra-index-url, --index, --source, --repository,
-DremoteRepositories) or `VAR=... cmd` / `export` variables
(NPM_CONFIG_REGISTRY, PIP_INDEX_URL, UV_INDEX_URL,
CARGO_REGISTRIES_*, GOPROXY, GOPRIVATE, ...) name a
non-default registry is source.type private_registry with
the registry's host only: never looked up or sent. Code
only: no model, no network. READ-ONLY (a dry run) unless --write;
with --write a changed record goes through superseded/
(the stored bytes copied first, verified), never in place,
and MANIFEST.jsonl gets one line. Re-running changes
nothing. Exit 1 when read-only and some record would
change, or when a write failed.
dinctrl-store deps-build --session <session.jsonl> [--record <record.json>]
[--splitlines]
print the facet one session gives (writes nothing)
dinctrl-store deps-sync --store <dir> [--path DIR]... [--roots-from-sessions DIR]...
[--machine NAME | --machine-id ID] [--now ISO] [--dry-run] [--json]
THE LIBRARY INVENTORY (store-owned record kind `inventory`,
<dir>/inventory/<machine>.jsonl). The machine is the
install's stable id (--machine-id, or DIN_MACHINE_ID; `din
deps sync` passes it) with the host name as its label, so
two machines that share a host name keep two files; a
host-name file this machine wrote before is merged in and
moved aside, never deleted. --machine NAME (or
DIN_MACHINE) keys it by that name instead. Every lockfile (exact
versions, basis lockfile) and manifest (declared
requirements, basis manifest) under the roots: Cargo,
npm/pnpm/yarn, poetry/uv/pdm/Pipfile/requirements*.txt,
go.mod/go.sum, Gemfile, composer, NuGet, Maven/Gradle.
Roots: --path, and the working directories of the session
transcripts under --roots-from-sessions (raised to their
git repository). Reads ONLY those files and .gitignore;
skips vendor/build trees, hidden and ignored dirs, never
follows a symlinked dir. Idempotent: first_seen kept,
last_seen = this sync, an entry no longer found is kept
and marked gone. No network, no model.
PRIVATE REGISTRIES: an entry from a registry that is not
the ecosystem's public one (lockfile record first, then
the package manager's config: .npmrc, pip.conf, uv,
.cargo/config.toml, GOPRIVATE / GONOPROXY / GONOSUMDB /
GOINSECURE and a non-public GOPROXY, composer, nuget.config,
Gemfile, pom.xml / settings.xml, build.gradle(.kts) /
settings.gradle / init scripts) is tagged source
private_registry with registry = its host, and is never
sent anywhere. Ambiguous means private: an index beside the
public one tags every package it may serve.
DIN_PUBLIC_MIRRORS=host,*.domain (or a file of hosts,
one per line, named by DIN_PUBLIC_MIRRORS_FILE) lists
company PROXIES OF THE PUBLIC registry (Artifactory, Nexus,
Verdaccio, a GOPROXY mirror): a package from such a host is
treated as public, so its maintenance data is kept. OFF by
default (empty: every non-default host is private). Never
overrides GOPRIVATE-style patterns. deps-scan and
deps-build read the same list for session installs.
dinctrl-store inventory-place --store <dir> [--org-node NODE] FILE... [--json]
THE ORG INVENTORY: places another machine's library
inventory (a deps-sync file, header first) into
<dir>/inventory/<machine>.jsonl, the header's machine
(<machine>@<NODE>.jsonl under --org-node, the header's
org_node: the node the field's org_scope reads it by;
ingest takes it from the run's org_node file, else its
records' stamp).
A MERGE, never a replace: the union of what was placed
and what arrived, the newer copy (synced_at) winning an
entry both have, the earlier first_seen kept, nothing
removed; an entry already placed for the same (machine,
lockfile sha) is deduped, and an unchanged file is not
rewritten. ingest does the same for every run that
carries <run>/inventory.jsonl (din capture ships one to
an org box on a paid install), once per file
(inventory/.placed-runs.ledger); --no-inventory skips it.
A RELAY-landed run (it carries the relay's .uploader) is
placed under its org_node file only (required; the
records' stamp is never the org source), into a file
bound to the uploader the relay authenticated (another
uploader's file is refused), newer by the relay's
receive time, never the client's synced_at. --relay-only
(or DIN_INVENTORY_PLACEMENT=relay) refuses the inventory
of every run the relay did not land: set it on a hosted
org box.
dinctrl-store ingest ... [--security | --no-security]
THE SECURITY FACET: by default a run's capture sidecar
(security.json, written from the RAW session before the
scrub) is merged into the record placed as `security`,
with `security_scanned_at`; --security also scans the
run's session.jsonl when there is no sidecar (and a code
record's body); --no-security does neither. A critical
exposure is said on a `!` line (class, never the value).
dinctrl-store ingest ... [--no-deps]
THE DEPENDENCIES FACET AT INGEST (1.0.39): every
conversation record placed, force-rewritten or re-graded
whose session is beside it (<run>/session.jsonl, else
identity.path; verified by identity.content_hash) gets
its top-level `dependencies` facet in the same pass, by
the build deps-scan uses. Idempotent: a re-ingest of the
same session writes the same bytes; a record already
stored and not rewritten is untouched (deps-scan is the
backfill). --no-deps turns it off.
dinctrl-store ingest ... [--sources DIR | --no-sources]
THE SOURCE STORE (provenance drill): the bytes every
record read this pass cites (identity.content_hash = its
source_id) are COPIED into DIR (default DIN_SOURCES, else
$DIN_HOME/sources; neither set: off): the run's capture
snapshot <run>/sources/<sha256>, its session.jsonl, else
identity.path, each re-hashed while it is streamed in.
Never inside the store; the original is never moved,
renamed, deleted or linked. A source not found is said
(not kept, and why) and indexed, never guessed.
`din-source` (source-view-rs) renders and backfills.
dinctrl-store security-scan --store <dir> [--runs <root>] [--write] [--include-low]
[--quarantine-superseded | --keep-superseded-plaintext] [--key-file FILE [--no-org-key]]
THE BACKFILL of the `security` facet over an existing
store. Code only, zero inference. DRY RUN by default:
counts by severity and class, never a value. Each record's
source is its run's capture sidecar, else its exact
session.jsonl (identity.path, else <runs>/<channel>),
else its own text. --write supersedes each changed
record (old bytes to superseded/<channel>/<id>/<when>/),
never in place; a re-run changes nothing. The superseding
copy also has every credential in the record's own text
(the store's pass, the whole table) replaced by
[REDACTED], AFTER the facet recorded it (redacted_by
scan-v1); --quarantine-superseded MOVES each replaced
version that still holds one to <dir>/.quarantine/.
Without it, the version this --write replaces because its
own text held credentials is moved there all the same;
--keep-superseded-plaintext keeps it in superseded/.
Each span of the table is CONFIRMED first: a `cookie`
outside a cookie context or without a session value, and
a placeholder `secret assignment` (one char repeated,
`your-...`, `${...}`, ...), are set aside and never
redacted; a bare 40-char `aws secret key` with no AWS
label near it, and a `secret assignment` under 8 chars,
are LOW confidence and are redacted only with
--include-low (the rest is high).
dinctrl-store security-scan --store <dir> --artifacts [--write] [--include-low] [--runs <root>] [--key-file FILE [--no-org-key]]
PRESERVED ARTIFACTS holding a credential the store's
pass finds (content-addressed, so the pass above never
rewrites them), each span CONFIRMED as above: set-aside
spans are counted and never redacted, LOW ones are
redacted only with --include-low. DRY RUN by default,
counts only. --write: each one's redacted copy
([REDACTED]) is written under its NEW sha256 (after the
store's own artifact re-check, with the spans left in
place masked, accepts it for every linking record); an
artifact with nothing to redact is left; every live record
linking the old sha is superseded with that link moved
(artifact_redacted_from: <old sha>, redacted_by:
scan-v1); the old artifact is MOVED to
<dir>/.quarantine/<channel>/artifacts/. A re-run writes 0.
dinctrl-store security-detect --in FILE|- [--format jsonl|text] [--label NAME]
[--out FILE] [--shipped-sha256 HEX] [--key-file FILE [--no-org-key]]
the detector over one RAW input (a capture or import
path, before its scrub): writes the sidecar
{detector, session_sha256, security} to --out (0600) or
stdout, and one `[security] CRITICAL ...` line per
distinct critical credential to stderr. Exit 0 with or
without findings, 2 on a usage or I/O error.
--key-file names the INSTALL key: an install joined to
an org still fingerprints under its org key (the named
file beside it for the password classes) unless
--no-org-key; security-scan prints the fingerprint_scope.
--fragment: a capture that scrubs PER CALL (din-capture)
reads one call's RAW events on stdin and gets that
call's facet, or null, as ONE line on stdout; nothing is
written and nothing said on stderr.
dinctrl-store security-seal --spool FILE --session FILE --out FILE [--label NAME]
merge a per-call capture's fragments (security.spool.jsonl:
{base, tool_use_id, facet|unscanned} per call) into the
sidecar security-detect writes, bound to the SHIPPED
--session's sha256, pointers moved to its lines. A
fragment past its end (a checkpoint snapshot) or on a
line without its call's id is left out. No sidecar when
no call was scanned. Says the same CRITICAL lines on
stderr, and `sealed: N call(s) scanned, M not scanned,
...` on stdout.
dinctrl-store layers --store <dir> [--key KEY] [--json]
read-only: every conversation's LAYER STACK, grouped by
its conversation key (session uuid / claude.ai uuid /
chat hash), never by record id. Each layer: its grader,
prompt version, reading level, gated or not, capture
hash, snapshot count; the current layer first; an
earlier layer whose capture is smaller says `shorter`
(it read an earlier version of the session). --key
shows one conversation.
dinctrl-store legacy-import --from <field-1 store> --into <field-2 store> [--dry-run] [--no-redact]
the LABELLED LEGACY LAYER: every conversation record of
field 1 (READ ONLY: never written, locked or staged)
becomes a new field-2 record in its own layer
(`legacy-<prompt>`, `legacy-capture` for an ungraded
capture), stamped reading_level: legacy, gated: false
and provenance.legacy (the OLD prompt version, grader
and model). Its annotations, adjudication and transcript
sidecars come with it (only `record_id` re-pointed);
layers/legacy-import.jsonl names every decision with its
resolved_by. Idempotent. REFUSES (exit 3, nothing
written) an unmarked mix (one record naming several
graders or prompt versions), an unstamped `legacy-*`
record already in field 2, and any copy that would
overwrite other bytes. --dry-run writes nothing: the
count by conversation key (byte-identical / grew /
shorter / only in one) and what would be written.
Each copy is REDACTED as ingest redacts (high-confidence
credentials become [REDACTED], with the redaction note;
`redacted N spans in M records` on stderr). --no-redact
is for a forensic import only: spans left in the clear,
counted, and said loudly.
dinctrl-store parity --field1 <store> --field2 <store>
read-only on both: field 1 retires by PARITY, not by
date. Every field-1 conversation reachable in field 2;
every field-1 conversation record's legacy copy present
and stamped, the count per legacy layer equal; every
annotations file and adjudication sidecar attached
beside its copy (only record_id differs) and every
decision in it named in layers/legacy-import.jsonl with
its resolved_by. Exit 0 when all hold; exit 1 on any
gap, each named on its own GAP line.
dinctrl-store check-ids --store <dir>
read-only: each record file by the id its bytes mint.
A record with no identity.content_hash is named by the
digest of its bytes as they ARRIVED; the store's B6 pass
may redact text in it after that, so such a record is
listed as `b` (B6-edited, expected), never as a fault.
dinctrl-store grader-of <id|--all> --store <dir> [--grader-table FILE]
read-only: which grader made each record, and how that
is known (see GRADERS below).
dinctrl-store scan-creds --store <dir>
read-only: every record, superseded copy, artifact and
sidecar that still carries a credential the store's pass
would hide (class counts and key paths, never text),
each span confirmed as security-scan does: set-aside
spans are counted by reason, low ones listed apart
(`~`). Exit 1 when a file carries a high one.
dinctrl-store chunk-sets --store <dir>
read-only: chunk sets complete (0..chunk_total-1 per
channel + content_hash), regime split, flag counts;
exit 1 when a set is incomplete (verify-dryrun.sh)
dinctrl-store backfill-transcripts --store <dir> [--runs <root>] [--write]
[--b6-patterns FILE] [--b6-strict]
dinctrl-store backfill-transcripts --refilter --store <dir> [--write]
[--b6-patterns FILE] [--b6-strict]
OPTIONS:
--runs <root> runs/ root to scan: <root>/*/record.json and
<root>/*/records/*.json
--store <dir> durable store dir; records land in <dir>/<channel>/<id>.json
--write backfill-transcripts only: write, instead of listing
--refilter backfill-transcripts only: re-derive EXISTING sidecars
through the personal-content filter and the table
--b6-patterns FILE
personal-content policy (default $DIN_B6_PATTERNS, else
b6-patterns.json beside this binary or in ../scripts/,
else the built-in copy), as din-session-record finds it
--b6-strict backfill-transcripts only: redact the ambiguous shelf too
--regrade ingest only: replace a stored record by a re-grade of it
(see RE-GRADE below)
--producer-allow FILE
with --regrade: the producer allow-list (default
$DIN_PRODUCER_ALLOW, else producer-allow.txt beside this
binary)
--producer PATH ingest (repeatable): the producer binary that made the
records (din-record, din-session-record, din-import), as
the caller that ran it hands it over. Each record placed
gets a line in <store>/GRADER-LEDGER.jsonl: the binary's
sha256 and the grader id it states (--grader-id), or
`unknown` and why (none handed, none fits the record, or
the record states another grader). Default
$DINCTRL_STORE_PRODUCERS (a PATH-style list). A record's
bytes are never changed for it
-h, --help show this message
ingest writes <dir>/<channel>/<id>.transcript.txt beside each new conversation
record whose run has a session.jsonl: the session's text, credentials
redacted, capped at DIN_TRANSCRIPT_MAX_BYTES (default 2 MiB); a session over
DIN_SESSION_MAX_BYTES (default 512 MiB) is never read, and a record over
DIN_RECORD_MAX_BYTES (default 64 MiB) is rejected. The dependencies facet
parses at most DIN_DEPS_SESSION_MAX_BYTES (default 64 MiB) of a session, up to
its last whole line, and says so in its basis.truncated. The field
searches it, so a record made without a model is found by what was said.
Personal content goes first: the producer's B6 filter runs over the text, set
from the record's provenance.b6 (always on when the record was filtered;
otherwise on; an inherited DIN_B6=0 is ignored). When B6 cannot run, NO
sidecar is written for that record and it is counted; the unfiltered text is
never written.
backfill-transcripts is READ-ONLY unless --write. It lists every conversation
record with no sidecar whose run (identity.path, else <runs>/<channel>) still
holds the exact session.jsonl the record was made from, and with --write
(identity.path counts only when its real directory is named for the record's
channel, and lies under --runs when given; a symlinked session.jsonl is never
read: both are listed as refused)
writes those sidecars, filtered as ingest filters them. Exit 1 when read-only
and some are missing, or when B6 could not run for some.
backfill-transcripts --refilter is READ-ONLY unless --write. It runs every
existing <dir>/<channel>/<id>.transcript.txt (and <dir>/<id>.transcript.txt)
through B6 and the table, using the record beside it when there is one, and
lists (with --write rewrites) only those whose bytes change. It needs no run,
so <dir> may be a quarantine copy. It never touches a record or the manifest.
Exit 1 when any would change or B6 could not run for any; with --write, 1
when B6 could not run for any or a write failed.
scan-creds is READ-ONLY (fix/redact-hardcoded-creds). The store's pass now
includes the table's strict half: hardcoded credentials (a short password in a
comparison or a `*_PASS` name, XML, a URL's userinfo, a CLI password flag, a
`user ... password ...` pair, a default-credential table, a bare Basic). A
sidecar written before it is fixed by `backfill-transcripts --refilter
--write`. A record's own text is the grader's (its pass is frozen until the
next grader) and is never rewritten here: scan-creds lists every *.json and
*.transcript.txt under <dir> that still carries one, by class and JSON key
path, printing no value. Exit 0 when there are none, 1 when there are.
check-ids is READ-ONLY. It lists every stored code record whose file is named
by the old content-hash-only id, which a re-ingest by this build would store a
second time under its new id. Exit 0 when there are none, 1 when there are.
ingest itself never stores such a record twice: a code record whose file is
absent under its new id, but present under its legacy id with the same card
and content hash (check-ids' own test), is left alone, printed as `~`, and
counted as `legacy present` in the summary. No file is renamed, rewritten or
deleted and no manifest line is added for it.
RE-GRADE. A record already in the store is never rewritten by ingest, so a
re-grade of the same source (same id) is skipped. `ingest --regrade` replaces
it, but only for a record that carries provenance.regrade with `by` and
`producer_sha256` (and a prompt_version there or in provenance), and an
identity.content_hash whose session binds: a session.jsonl in the record's
run (or at its identity.path, a run of the same channel), not a symlink, with
that sha256, and a producer_sha256 listed in the producer allow-list
(--producer-allow FILE, else $DIN_PRODUCER_ALLOW, else producer-allow.txt
beside this binary, which each release ships with the sha256 of its own
din-record, din-session-record and din-import; one sha256 per line, # comments). With
no usable list, or a producer not on it, nothing is replaced and the run
exits 1. Nothing is deleted:
- the stored bytes are copied, byte for byte, to
<dir>/superseded/<channel>/<id>/<when that version arrived, : as ->/<id>.json;
- the new record is written under the same id, keeping the first
ingested_at and adding regraded_at; the store stamps provenance.regrade
{of_sha256, at, by, producer_sha256, prompt_version, record_sha256,
claim_map, claim_match, superseded, earlier};
- claim_map[i] is the new index of old claim i, or null (no match);
- when <dir>/annotations/<id>.json exists, one `note` is APPENDED to it
recording the move; the field resolves the human stamps through the map.
Re-running the same --regrade changes nothing. Without --regrade such a record
is skipped as before, and the count is printed. Exit 1 when a re-grade note
could not be appended (the record was replaced; re-run to append it), or
when a replacement was refused by the producer allow-list.
GRADERS (core's G1). `dinctrl-store grader-of <id|--all> --store <dir>
[--grader-table FILE]` prints, per record, `<id> <grader id> <source> <how>`,
read-only. The source is the first that answers: `stamp` (the store's
re-grade stamp: provenance.regrade.grader_id, the producer's own
--grader-id, asked by din-regrade), `ledger` (GRADER-LEDGER.jsonl: the
producer the caller handed to plain ingest with --producer), `table` (the
producer sha256 a stamp or ledger line names, in the built-in table of
released producers, plus the release's own rows in grader-table.tsv beside
this program, plus FILE or $DIN_GRADER_TABLE), `record` (the record's
own provenance.grader_source_sha256, written by its producer while grading,
not checked against a binary), else `unproven`, saying what was missing.
Exit 0; 1 when an <id> is not in the store.
EXIT CODES of ingest. 0: every run dir gave a record, new or already stored
(`ingested: 0 new, N unchanged` is a real "everything already there"). A
record refused one by one (a bad shape, an id collision, B6 unavailable, its
write or its manifest line failing) is a `! REJECTED` line and is counted on
the `! N record(s) REJECTED` line; the pass goes on and, by default, still
exits 0. 1: the pass could not run (a bad argument, the store lock or the
store unwritable), or a re-grade was refused or its note not appended as above.
4: only with --fail-on-reject, something this pass did NOT land: a record
rejected, a transcript sidecar, artifact or inventory refused, a path name not
UTF-8, the weave or re-weave failed. What landed stays (a signal, not a
rollback). 1 wins over 4, 4 over 3. 3: a run
dir gave no record. That is:
- the pass read no record at all, in any run dir (a --runs that is empty or
not a directory, or runs in the wrong layout). It prints no `ingested:`
line, since there is nothing to count; a run dir holding <run>/inventory.jsonl
has a reason to be there and is not a failure;
- or a run dir holds record files directly (<run>/*.json) instead of in
<run>/records/, or holds only files that do not read as records. The other
runs' records still land and the `ingested:` line counts them.
A run dir with nothing that could be a record (a run still in progress) is
named but fails only a pass that read nothing. Each run dir is named on
stderr, and the last line says what was looked for and what was found.
THE STORE IS A GIT REPOSITORY. After each ingest pass the store is staged as
record_store.py did: `git init -q` when it is not a repo yet, then `git add -A`
over the whole store. Nothing is ever committed (whoever owns the store reviews
and commits). A git failure is reported, never fatal. --no-git skips both
(and says so); use it for a store on a synced or backed-up volume that should
hold no .git. No sqlite index is built (see --db).
din-contract
din-contract - the sealed interpretive contract provider
din-contract write the contract to stdout
din-contract --check open the blob and report on it, WITHOUT printing it
din-contract --sha256 the sha256 of the contract, and nothing else
din-contract --check-sealed FILE
does FILE open with this key? (sizes and hash only)
din-contract --help
din-contract --version
The contract is compiled into this binary as an encrypted blob. It is written
to stdout so a caller can capture it; it is never written to a file here and
never reaches the customer's disk through this program.
Refuses to write to a terminal unless you pass --to-terminal, so that a stray
invocation in a shared shell, a screen share or a CI log does not print the
contract into a scrollback buffer nobody meant to fill.
din-import-graphiti
The Graphiti / Zep reader, for a Graphiti or Zep endpoint you run.
din-import-graphiti - import a Graphiti/Zep graph and grade its edges against its episodes
USAGE
din-import-graphiti --dry-run [--fixture <file>] [--group <id>]...
din-import-graphiti --out <dir> [--fixture <file>] [--group <id>]...
WHAT IT DOES
Reads a group's EPISODES (the raw evidence) and its ENTITY EDGES (the graph's
own claims), then writes one Record Schema v3 record per group_id in which
every claim is anchored by episode uuid to the evidence it came from, with
Graphiti's valid_at/invalid_at/expired_at carried as the claim's temporal
window. An episode that carries a tool call or result as JSON structure, or
whose exact `source` is on DIN_GRAPHITI_TRUSTED_SOURCES, grades `logged` and
its claims `direct_output`. A source_description that merely SAYS "tool
output" grades `inferred` with claims `external_testimony`; prose grades
`inferred`. Records are written owner-only (dirs 0700, files 0600).
FLAGS
--fixture <file> read a Graphiti-shaped JSON document instead of an endpoint
--group <id> the group_id to read (repeatable; also DIN_GRAPHITI_GROUP_IDS)
--out <dir> write <dir>/<channel>/record.json per group
--dry-run map and report, write nothing
--print print the records to stdout as well
-h, --help this
ENVIRONMENT (the live path; an endpoint the tenant authorized, never a web UI)
DIN_GRAPHITI_URL required, e.g. http://127.0.0.1:8000
DIN_GRAPHITI_API_KEY required unless DIN_GRAPHITI_NO_AUTH=1
DIN_GRAPHITI_AUTH_SCHEME default Bearer (Zep hosted wants Api-Key)
DIN_GRAPHITI_AUTH_HEADER default Authorization
DIN_GRAPHITI_GROUP_IDS comma separated, if not given with --group
DIN_GRAPHITI_QUERY what to search the graph for, unless
DIN_GRAPHITI_EDGES_PATH names a list route
DIN_GRAPHITI_EPISODES_PATH default /episodes/{group}?last_n={last_n}
DIN_GRAPHITI_SEARCH_PATH default /search
DIN_GRAPHITI_EDGE_PATH default /entity-edge/{uuid}
DIN_GRAPHITI_EDGES_PATH optional list route, e.g. /edges/group/{group}
DIN_GRAPHITI_NO_HYDRATE=1 skip the per-uuid edge read (claims lose anchors)
DIN_GRAPHITI_LAST_N default 100 (a full page marks the record a slice)
DIN_GRAPHITI_MAX_FACTS default 200 (likewise)
DIN_GRAPHITI_TRUSTED_SOURCES comma separated exact episode `source` values
you vouch for as tool output (never message,
json or text); applies to --fixture too.
A `source` is set by whoever wrote the episode
and is not verified: list one only if every
writer to these groups is yours
EXIT CODES
0 done 1 something failed while working 2 refused (see the message)
din-libcatalog
The library catalog client. din deps refresh runs it (catalog mode, the default) to fetch and verify DIN's signed library catalog.
din-libcatalog: DIN's own library catalog, one signed database of package facts
CENTRAL (DIN runs these; the install never does):
din-libcatalog sign --dir DIR --secret-key FILE [--expires-days N | --expires ISO]
Sign manifest.json (minisign format; an UNENCRYPTED key, or use the minisign CLI, as
sign-and-publish.sh does). The trusted comment is fixed and carries the EXPIRY, which
every reader checks: din-libcatalog AS_OF manifest sha256 SHA expires WHEN
WHEN defaults to as_of + 14 days (--expires-days 1..90). Past it, installs refuse the
catalog: sign a newer one before then.
din-libcatalog seed [--store DIR]... [--inventory FILE]... [--seed FILE]... --out FILE
The seed list: ecosystem + name pairs only (no path, version, project or customer).
din-libcatalog diff OLD NEW [--out FILE]
The changes between two catalogs, as the watcher's event kinds.
din-libcatalog verify --dir DIR [--pubkey FILE]... [--staging-pubkey FILE]... [--allow-stale]
Check a published catalog: signature, the signed expiry, then every shard. A catalog in
the legacy comment format (no expiry) passes only under a --staging-pubkey key.
din-libcatalog keys [--pubkey FILE]...
The catalog key ids this binary trusts (production, next, test build or not), and of FILEs.
din-libcatalog keys --generate PREFIX [--label staging]
A NEW signing key pair: PREFIX.key (unencrypted minisign format, created 0600, never
overwritten) and PREFIX.pub. Prints the key id only, never the secret.
INSTALL (the client):
din-libcatalog fetch --dir DIR --ecosystems cargo,npm [--url URL] [--deps-catalog DIR]
[--allow-rollback] [--top-list N] [--max-age-days N] [--allow-stale] [--warn-age-days N]
Download the signed shards for these ecosystems (default URL https://catalog.dinctrl.com/v1),
verify them against the compiled-in key, install under DIR/current. No package name is sent.
PAID (the delivery, not the data): reads the install's SIGNED entitlement (DIN_ENTITLEMENT,
else $DIN_HOME/entitlement.json, else ~/.din/entitlement.json) and refuses a free install.
A catalog past the EXPIRY signed into its trusted comment is refused, so a stuck or
replaying mirror cannot hide new advisories; --allow-stale takes it (flagged EXPIRED).
One with no signed expiry (the legacy format) is refused. --max-age-days N adds a limit
of your own, refusing an as_of more than N days old (default none; --allow-stale lifts it).
Older than --warn-age-days (default 7) a catalog is flagged STALE.
din-libcatalog verify --installed DIR/current [--allow-stale] [--warn-age-days N]
Also prints the catalog's age_days, expires, `stale` when it is over 7 days, and its
`coverage` per ecosystem (package_facts: broad, thin, or advisories_only, no package facts);
refuses an expired catalog unless --allow-stale.
din-libcatalog lookup --dir DIR/current ECO NAME [VERSION]
PAID, as `fetch`.
din-libcatalog check [--api URL] [--key-file FILE] [--store DIR]... [--inventory FILE]...
[--package ECO:NAME[@VERSION]]... [--batch N] [--out FILE]
PAID, OPT-IN, SENDS PACKAGE NAMES: asks the catalog API (default
https://catalog.dinctrl.com/v1) about these packages, in batches of at most 500. The
ecosystem, name and exact version of each are sent; nothing else (no path, project or
record). The key file's key goes in a header, never in argv. `fetch` sends no name.
Every answer must be SIGNED by the API's answer key compiled into this binary, for this
request, within the hour; an unsigned, tampered or replayed answer is refused.
din-regrade
The re-grade driver. din regrade --run runs it; a cap you set with --max-spend is enforced here.
usage: din-regrade --store STORE --targets FILE --out DIR --model MODEL_ID
[--dry-run [--json]] [--max-spend USD] [--workers N] [--index FILE]
[--expect-prompt-version X] [--prompt FILE] [--timeout SECS] [--by OPERATOR]
[--session-producer PATH] [--record-producer PATH]
[--merge unit-id]
[--on-usage-limit pause-resume|fail] [--max-wait DUR]
[--max-resume-cycles N] [--reset-margin DUR] [--limit-backoff MIN..MAX]
[--retries N] [--backoff MIN..MAX] [--new-run]
din-regrade --resume --out DIR carry on: the command DIR was run with
din-regrade --status --out DIR the status of the run in DIR
din-regrade --resume-now --out DIR
wake the run paused on DIR now
din-regrade --two-level ... scan every target, read the picks deep
din-regrade session ... the same for one session (`din-regrade session --help`)
din-regrade --base-only --runs ROOT --out DIR [--workers N] [--dry-run] [--ingest STORE]
[--by ID [--by-kind KIND]] [--expect-prompt-version X]
base records (no model call) for every
capture run under ROOT
Re-grade an explicit list of store records into an OUTPUT DIR. Never writes the
store: land the results with `dinctrl-store ingest --regrade OUT/records`.
Runs on YOUR plan: your assistant CLI login (claude, codex) or your own endpoint.
DIN bills nothing.
--store STORE the record store to READ the target records from
--targets FILE one record id per line (# comments); nothing else is touched
--out DIR output dir: records/, work/<id>/attempt-N/, ledger.jsonl
--model MODEL_ID the FULL model id, passed to the producers: pinned on the
model card (din-runner; DIN_RUNNER_MODEL_CARD adds rows).
An alias such as `sonnet` is refused: it can drift
between calls. It must be one the runner below serves
--runner claude|codex|http, --claude-bin, --codex-bin, --base-url, --api-key-env,
--effort the runner the producers grade through (default: the
claude CLI on PATH), passed to them as given
--dry-run estimate, 0 model calls: from the store's receipts
(provenance.review_cost of earlier grades by the same
model and prompt; they lead when there are 5 or more)
and from what the producer would send under the
contract (--expect-prompt-version, else the dearest,
1.7.4: every chunk at the tier's window, 40000 chars
unless DIN_TIER is paid, each chunk with
its two retry halves; 1.7.2: 60000-char chunks, at most
16), input and output priced apart. Of a receipt only
its cost, model and prompt fields are kept; claim text
is never used or shown
--json with --dry-run: one JSON summary on stdout instead
--max-spend USD stop starting records once this run's spend reaches USD:
the producers' recorded provenance.review_cost, and the
high estimate for any call whose cost is not known.
Every producer is handed --max-calls-per-record N, N
sized from what is left under USD (each planned chunk
priced at the high end of its retries), and that
record's ceiling under N is reserved while it runs. A
record starts only while recorded spend PLUS every
reservation is under USD, and under a 1.7.4+ contract
a chunked record whose smallest guard (2 chunks) does
not fit is not started. So a long session cannot run
past its reservation and --workers never multiplies
the overrun; a short record (one transcript and its
retries) may still finish past the cap, as before. A
record capped by its guard says so (coverage.capped,
limit max_calls_per_record, unread_ranges)
--ack-unknown-spend USD
this run's ledger holds a call of UNKNOWN cost (no rate
for the model, nothing measured), so a capped resume is
refused. Look the cost up with your provider and state
it here; it is booked against the cap
--workers N records graded at once (default 1)
--index FILE triage index (id -> session path). Without it, each
record's own identity.path is used
--expect-prompt-version X
passed to the producers; they refuse a different prompt
(default: DIN_EXPECT_PROMPT_VERSION; a blank value is
refused). Pinned or not, a run is ONE contract: run.json
keeps the version and sha256 the producers name on the
first invocation, and a resume under another is refused
--prompt FILE a contract FILE to grade under (default: DIN_PROMPT, read
here): made absolute and handed to BOTH producers as
--prompt, with the pin, so both read the same file. It
needs a pin (--expect-prompt-version X or
DIN_EXPECT_PROMPT_VERSION) that the file states, else
nothing runs and the line to add is printed. Without
it: a contract file a producer finds by itself, with no
pin, is held to the version the sealed provider
(din-contract) states, so a stray file is refused before
any call; the sealed provider alone is unchanged.
--dry-run prints, per producer, the contract source, its
stated version and the pin. Only the version line of a
contract is read here; no contract text is shown
--timeout SECS passed to the producers (their interpretive call ceiling)
--by OPERATOR who ran the re-grade (stamped in provenance.regrade.by)
--session-producer PATH / --record-producer PATH
the grader binaries (default: beside this one, else PATH)
--merge unit-id a SCOPED re-grade (grader 1.7.4+): a target whose STORED
grade carries a unit_id on every unit is promoted asking
the store to merge by unit id (provenance.regrade.merge),
so `ingest --regrade` keeps every stored unit the new
grade did not read. A target graded before 1.7.4 (no
unit ids) is promoted whole, as without this flag
--two-level scan, then read deep, in place of --model: a Scanner-level
pass reads every target and an Archivist-level pass reads
those a free rule picks (--scan-model, --scan-effort,
--deep-model, --deep-effort, --deep-top N; the levels are
the card's; `din-regrade session --help` says the rest)
The producers always run with the personal-content filter (B6) ON: DIN_B6 and
DIN_B6_PATTERNS are removed from their environment, and a record that does not
show B6 applied is never promoted. The DIN_GRADE_* window overrides are removed
from their environment too (a paid window is a licence feature). One invocation
at a time per --out (a lock).
THE LICENCE is settled before any producer starts. DIN_ENTITLEMENT and
DIN_INSTALL_ID_FILE, when not set, are taken from this install as the field's
launcher hands them to the field (the install's .din/field.env, else its
.din/entitlement.json; the plugin's install-id) and handed to the producers. A
tier above free asked for (DIN_TIER=paid or internal) that the producers would
not honour is REFUSED (exit 2) before any call, with every place looked and the
fix; with no DIN_TIER, a licence that verifies paid grades at the paid window,
else the free window. --dry-run says the tier, window and reading level.
A USAGE LIMIT IS WAITED OUT, NOT FAILED. On your plan's usage limit (the 5-hour
window, the weekly cap, a quota) din-regrade starts no new producer, lets those
in flight finish, waits until the reset the limit names plus a margin, and
carries on with the same --out, cap and lock. A record whose call hit the limit
(or was refused at the door) is PENDING, never failed: it is tried again, and
what it cost is booked once. Only a real fault (a refusal, an answer that is not
a grade, a call that errored past its retries) fails a record.
--on-usage-limit pause-resume|fail
pause-resume (default) waits and carries on; fail stops
cleanly with the list intact (exit 4)
--max-wait DUR the longest one pause may be (default 6h): a reset further
off (a weekly cap days away) is a clean stop, resumable
(exit 4, state stopped-waiting). DUR: 30s, 15m, 6h, 2d
--max-resume-cycles N
how many times the run resumes, counted across --resume
(run.json; default 48). Past it the run stops; carry on
with `--resume --out DIR --max-resume-cycles N`, N above it
--reset-margin DUR waited past the reset the limit names (default 2m)
--limit-backoff MIN..MAX
when a limit names no reset (or the door refused the
call): wait MIN, doubling, at most MAX (default 5m..60m)
The lock <OUT>/.lock is held through a pause, with this process's id in it; a
lock whose process is gone is taken over, and said.
A PAUSE ENDS EARLY on another sign-in: when the CLI is signed in again (to
another seat, say), the run carries on at once, with no flag and no restart
(`login changed; resuming`). Only the CLI's credential file's metadata is
watched (claude: ~/.claude/.credentials.json or $CLAUDE_CONFIG_DIR; codex:
~/.codex/auth.json or $CODEX_HOME), never its content. Where the sign-in lives
in an OS keychain, wake it with `din-regrade --resume-now --out DIR`. If the
new sign-in is limited too, the run pauses until its own reset. An early wake
is one resume cycle; --max-spend stays the job's across sign-ins.
--retries N a server or network error (a 5xx, a dropped connection)
or a throttle that names no reset is not a limit: that
record is tried again N times (default 4), then fails,
saying why
--backoff MIN..MAX the wait before each retry: MIN doubling, at most MAX,
plus jitter, and at least a retry-after the error says
(default 10s..5m)
A LOST SIGN-IN STOPS THE RUN, RESUMABLE. An expired login, a revoked key, or a
model this account cannot use (read with din-runner's own classifiers) starts
no new producer, lets those in flight finish, leaves the record that met it
PENDING, and stops (state stopped-auth, exit 4) with one line saying how to sign
in again and `din-regrade --resume --out DIR`. A login is never retried in a
loop, whatever --on-usage-limit says.
THE CAP IS THE JOB'S. --max-spend is per --out and cumulative over every pause,
resume and re-launch on that out (its ledger). A NEW --out for a job that already
spent (the same store and targets, recorded in STORE/.din-regrade/budgets.jsonl,
never in a record) is REFUSED, naming the earlier out and what it spent:
--resume with --out DIR and nothing else: re-run the command DIR
was run with (DIR/run.json), the same out and cap
--new-run start a new budget for the job, on purpose
STATUS WITHOUT PARSING LOGS. <OUT>/status.json is written on every change and at
least every 60 s: state (running, paused, stopped-waiting, stopped-auth, done, failed),
paused_until, next_resume_at, reason, spend_usd, cap_usd, done, pending, failed,
remaining, resume_cycles, pid, updated_at, pause_reason (usage_limit, door,
auth; after an early wake login_changed or resume_now) and account (a
non-secret label: `changed-at <time>` once a new sign-in is seen). The same is
one stdout line on every
change: STATUS state=paused until=14:30Z spend=212.04/400.00 done=180 remaining=182
din-regrade --status --out DIR
prints it: exit 0 running, paused or done; 1 failed;
2 no status; 3 stopped-waiting, stopped-auth, or a run whose process
is gone (carry on with --resume)
BASE RECORDS FROM A RUNS TREE (--base-only). Every run under --runs ROOT (a
dir holding session.jsonl, as `din capture` leaves it) is handed to
din-session-record --no-model, with what the run's own files hold: the channel,
org node and capture machine from its capture record (record.json, else
coder.done), the source path from coder.done. Nothing is typed per run. A run
whose files do not name its org node or capture machine is failed, saying so;
it never fails the rest. The records land in DIR/<the run's path>/ (record.json,
records/, the producer's stdout.txt and stderr.txt). A run already there is
skipped and nothing is written for it, so the same command again makes nothing
new. The lock, status.json, the STATUS line, the ledger and --resume are the
re-grade's. --dry-run lists each run and its producer command.
--by ID, --by-kind KIND
who made the base records (identity.by); default: who
each run's capture record says
--workers N runs made at once (default 1)
--ingest STORE at the end, land every base record in DIR with the
store's own ingest (dinctrl-store ingest --run ...
--store STORE, beside din-regrade or on PATH)
Exit: 0 every target done; 1 some target failed or did not resolve;
2 refused before any call; 3 stopped at --max-spend;
4 stopped at a usage limit, the list intact (--on-usage-limit fail, a
reset past --max-wait, --max-resume-cycles), or on a lost sign-in
(stopped-auth): run it again (--resume) to carry on.
din-source
The source views of the provenance drill. It writes the redacted view of each kept source a record cites, and checks each claim's anchor in it; the field serves those views at /api/source/*.
din-source: the source store of the provenance drill (DESIGN-PROVENANCE-DRILL-2026-11-09)
din-source backfill --store DIR [--sources DIR] [--runs ROOT] [--sessions DIR]...
[--locate SET.tsv]... [--vault MANIFEST.jsonl] [--b6-patterns FILE] [--write]
For every record in the store, find the bytes its identity.content_hash
names and report: resolved, no_map_entry, path_gone, hash_mismatch,
too_large, not_kept (per record and per source), plus one line per
source not resolved (status, reason, last path; never contents).
DRY RUN unless --write (nothing is created or written). --write copies
each verified source in (streamed), appends an index line when an
answer changed, and renders every kept source that has no view yet.
A hash mismatch is REPORTED, never re-pointed. Idempotent. Never
writes a record.
din-source render --store DIR [--sources DIR] [--channel C]... [--record ID]... [--b6-patterns FILE]
The redacted view and per-claim anchor checks of each kept source the
named records cite (all records when none is named). Fails closed: a
source B6 or the redaction cannot clean gets no view, and says why.
din-source snapshot --run DIR
Copy the code files and documents a run's records cite into
DIR/sources/<sha256>, read on THIS machine, kept only when they still
hash to the record's content_hash; a source holding a credential is
withheld. The run then carries them to the field's ingest.
din-source put FILE --sources DIR [--sha SHA256]
Copy one file in (streamed; refused unless it hashes to --sha when given).
din-source verify --sources DIR [SHA256]...
Re-hash kept blobs (all when none is named).
din-source scan FILE...
The release gate's credential list over each file (a view, a window
answer): one line per file with its hit count and classes, never a
value. Exit 1 when any file has a hit.
--sources defaults to DIN_SOURCES, else $DIN_HOME/sources.
DIN_SOURCE_MAX_BYTES caps a source (default DIN_SESSION_MAX_BYTES, 512 MiB).
DIN_SOURCE_RENDER_MAX_BYTES: the largest kept source backfill and render
give a view in this run (default: all). A view is built in memory, up to
~18x a session log's size; under a memory cap a larger source is kept,
gets no view this run, and says so; a later run with more memory renders it.
din-referee
The review funnel: the referee between the field's collision detector and the human queue (/api/queue). Its rules (stage 0) and its pre-filter (--prefilter) ask no model and cost nothing.
din-referee --plan is free on every plan: it counts what would reach the judge and forecasts the cost, asks no model and writes nothing. The judge pass (--judge) runs on your own inference: your claude or codex CLI, or an OpenAI-compatible endpoint (a local model included). DIN never pays for it and never charges for it. It costs what your seat costs: --plan books $0.02 a judgment (--plan-per-item, the Sonnet measure) and about one judgment in ten asking a second opinion at five times that; a run needs a cap (--max-spend, or --max-calls / --max-tokens on a subscription), and a judgment already paid for is never paid twice. The judge pass is held to your plan's reading level, as grading is: on Free both seats must read at Reader or below on DIN's model card (for example --judge-model claude-sonnet-5-5 --second-model claude-sonnet-5) or run on your own hardware; the default second opinion (claude-opus-5-5, Archivist) needs a paid plan, and --plan says, for free, whether your seats may run. On a large field run it under a memory cap: it works one batch of records at a time, and --max-rss MB stops it cleanly (exit 7). It has no default field: name the field that serves --store with --field http://127.0.0.1:PORT, or let the store's own field.env name it (din-referee --plan --store ~/din/records reads the field ~/din/.din/field.env names); with neither it refuses before reading anything.
usage: din-referee [-h] [--field FIELD] [--token-file TOKEN_FILE] [--store STORE] [--project PROJECT]
[--since SINCE] [--until UNTIL] [--limit LIMIT] [--rules-only] [--model-step] [--model MODEL]
[--timeout TIMEOUT] [--workers WORKERS] [--no-stamps] [--stamps-only] [--force] [--dry-run] [--json]
[--log LOG] [--max-calls N] [--max-cost-usd USD] [--unknown-cost-usd USD] [--allow-remote-field]
[--prefilter] [--prefilter-checks LIST] [--judge] [--plan] [--judge-model MODEL] [--second-model MODEL]
[--judge-level LEVEL] [--max-spend USD] [--audit-every N] [--stage DIR] [--ledger PATH]
[--briefs-dir DIR] [--plan-per-item USD] [--plan-ids PATH] [--max-rss MB] [--judge-runner {claude,codex,http}]
[--second-runner {claude,codex,http}] [--codex-bin PATH] [--judge-effort EFFORT] [--second-effort EFFORT]
[--max-tokens N] [--declare-level MODEL[@EFFORT]=LEVEL] [--levels-file PATH]
[--plan-tokens-per-call N] [--base-url URL] [--api-key-env NAME] [--billing BASIS] [--price IN,OUT]
[--second-level LEVEL] [--override-levels] [--model-runner {claude,codex,http}] [--model-effort EFFORT]
[--max-down N]
din-referee: the pass between the DETECTOR and the HUMAN (SPEC 2 + 3).
THE FIELD (there is no default field: the pass reads the collisions of the field it is given and settles them
in the store it is given, so the two must be one field's):
the store --store > FIELD_STORE > DIN_HOME's records > the install's field.env: the FIELD_STORE line
of <prefix>/.din/field.env, the prefix found as din finds it (DIN_PREFIX, else the install
din-referee sits in, else ~/din), so on an install `din-referee --plan` needs no option.
None found: refused (exit 2), naming every place it looked
--field URL the field that serves --store, on loopback (http://127.0.0.1:PORT; a remote one needs
--allow-remote-field and https). It wins over everything below
without --field the field the store's own field.env names: <prefix>/.din/field.env (an install's, or
`din field new`'s; the store is <prefix>/records), else field.env beside the store; the
first whose FIELD_STORE is this store gives FIELD_URL, else http://FIELD_BIND (a store
taken from the install's field.env: that field.env's). The field used is said on stderr
otherwise refused before anything is read (exit 2): name the field with --field. FIELD_URL in the
environment is not read, and no port is ever guessed
the token FIELD_TOKEN, else --token-file / FIELD_TOKEN_FILE, else the FIELD_TOKEN_FILE line of the
field.env that gave the field (an install's has one), so on an install
`din-referee --plan --store <prefix>/records` needs nothing else. A token file must be
0600 (or 0400), wherever it is named, or it is refused unread
THE FUNNEL (stage 0 is the seven rules above; stages 1 and 2 are off unless asked):
--prefilter stage 1, FREE: token-overlap-only, agrees-with-refutation, reversed-later, duplicate,
experiment-object and corroboration (a second pass of a chat stands against a lone
read of it, at least as deep: two reads against one); stamped resolved_by=mechanical,
stage=prefilter
--prefilter-checks LIST a comma list of proposition,reversed,dedupe,experiment-object,corroboration,siblings (default all)
--judge stage 2, PAID (on your own runner: see THE RUNNERS; DIN never pays): one call per surviving open
collision; implies --prefilter and needs --max-spend. Held to your plan's reading level, as
grading is: each seat's level on DIN's model card at or below the licence's cap (free: Reader,
e.g. --judge-model claude-sonnet-5-5 --second-model claude-sonnet-5), or a model on your own
hardware; refused before any call otherwise
--plan FREE on every plan: count what would reach the judge and forecast the cost; asks no model,
writes nothing; a second line gives each stage's cut, and the columns add up to entries=;
in the release build a last line says whether your licence lets these seats run the judge.
It reads the field of THE FIELD above: give --field (or have the store's field.env name it)
and its token (the same field.env's FIELD_TOKEN_FILE serves, so --token-file is optional)
siblings one judge call per group: entries of one chat making one claim (same facet, state, regime,
date, polarity and targets; the wording only added to, nothing it names changed). The rest
carry its verdict, recorded as carried_from; to_judge= counts the calls, siblings= the rest
--judge-model MODEL default claude-sonnet-5-5
--second-model MODEL default claude-opus-5-5 (asked when the judge says COMPATIBLE at medium)
--judge-level LEVEL the reading level of an UNRATED judge model (reader, analyst, archivist, scholar);
a Scanner-level model can't be the judge
--second-level LEVEL the same, for an UNRATED second-opinion model
--max-spend USD the most a judge run may spend (required with --judge)
--audit-every N keep 1 in N AI-settled items as a human spot check (default 50; 0 = none)
--stage DIR write proposed sidecars under DIR (same relative paths); the store is not written
--ledger PATH the judge's resumable decisions (default <stage>/judge-ledger.jsonl, else
~/.din-referee/judge-ledger.jsonl); a decided entry at the same position_hash is never paid twice
--briefs-dir DIR escalation briefs as markdown (default <stage>/escalations)
--plan-per-item USD the plan's cost of one judgment (default 0.02, September's Sonnet measure)
--plan-ids PATH write one JSONL line per decided entry: {record_id, channel, entry, position_hash,
stage0, stage0_rule, prefilter, prefilter_rule, outcome, stored_verdict, collision_with, _source}; with --plan or
--dry-run it is the pass's only write; never inside --store
MEMORY (bounded: one batch of records is worked at a time; every cache is capped):
--max-rss MB stop cleanly once the resident size (VmRSS) passes MB (default 8192; 0 = off): exit 7,
batches already finished stand, nothing of the unfinished batch and no --plan-ids file
is written. The summary line and --json carry peak_rss_mb; --plan prints an expected
peak before the heavy work
THE RUNNERS (who asks the judge and the second opinion; DIN never pays: every call goes through din-runner, DIN's
one model-calling layer, with the transcript marked untrusted, so a runner that cannot turn its tools off is refused):
--judge-runner R claude (default: your `claude` CLI, $ under --max-spend), codex (your `codex` CLI on your
ChatGPT subscription login: no $, capped by --max-calls and/or --max-tokens; the login is
checked once before the first call) or http (an OpenAI-compatible endpoint: --base-url)
--second-runner R the second opinion's runner (default: the judge's)
--codex-bin PATH the codex CLI (default `codex` on PATH); each call is din-runner's verified lockdown:
`codex exec --json --ephemeral --ignore-user-config --ignore-rules --skip-git-repo-check
--color never -s read-only --disable <22 tool features> -c web_search="disabled" ...
-m MODEL -c model_reasoning_effort=E -` with the prompt on stdin, in an empty private temp
dir removed afterwards. A judge call that still uses a tool is an error (codex_tool_use),
never a verdict
--base-url URL an http seat's endpoint: https://HOST/v1 (OpenAI, xAI, OpenRouter, Together, Groq, ...) or
http://localhost:PORT/v1 (Ollama, vLLM, llama.cpp, LM Studio: $0)
--api-key-env NAME the NAME of the env var holding the endpoint's key (never the key; a remote one needs it).
A remote endpoint's cost is UNKNOWN unless it reports one: booked at --unknown-cost-usd
--billing B an http seat bills so, over the card: metered, list_equivalent, subscription, free or unknown
(a localhost tunnel to a paid GPU is not free)
--price IN,OUT an http seat's USD per million tokens, over the card
--judge-model / --second-model
REQUIRED for a codex or http seat (no model is assumed); every model is checked against
the model card (din-runner): an alias (sonnet, *-latest, auto) is refused
--judge-effort E codex or http: low, medium, high, xhigh or max (codex default high); `ultra`
(auto-delegation) is refused; refused with claude
--second-effort E the same, for the second opinion
--max-calls N the most judge calls this run, on every seat and every billing (it also caps the stage-0
model step, if on); a subscription seat needs this or --max-tokens
--max-tokens N the most subscription tokens (input + output) this run; a codex seat needs this or
--max-calls. A call that reports no usage counts --plan-tokens-per-call against it, never 0
--declare-level MODEL[@EFFORT]=LEVEL
declare a reading level (repeatable; the last wins; MODEL alone covers every effort;
yours fill a model the tables leave unrated; above a table's level they need
--override-levels, and never pass a level the operator's own rule
states, nor a Scanner row on ANY runner. Any codex or http model@effort in neither is UNRATED, and refused as judge or
second opinion. A declared level is a statement from evidence (measured reads), never from
a name, and is stamped `declared: true` with its source. A Scanner level (stated or
declared) can't be the judge or the second opinion.
--levels-file PATH declarations as data: one MODEL[@EFFORT]=LEVEL or MODEL<TAB>EFFORT<TAB>LEVEL a line
(EFFORT * = every effort; # comments); flags given after it override it
--override-levels a declaration may go above a table's level; the seat is stamped with it
--plan-tokens-per-call N the plan's (and an unknown-usage call's) tokens for one codex judgment (default 12000)
--model-runner R who asks the stage-0 --model-step: claude (default), codex or http (--base-url)
--model-effort E its reasoning effort (codex, http)
A usage limit, a rate limit, an auth failure, a model the account cannot use, a runner that is not installed, or a
call refused before it was sent stops new judge calls, and so do --max-down N calls in a row that get no answer
(an outage; default 20);
what is settled is kept and the rest stays open for the
next run. A judgment that gives no usable answer is never ledgered: it stays open too, and a later run asks it.
The ledger records each opinion's runner, model, cost basis and tokens; a verdict is reused only by the same seat.
the model card din-runner-card-2026-11-07a (din-runner): declared levels (basis declared, the operator's delegation): gpt-6.1-sol@medium=analyst (chatgpt-2026-11-05a), gpt-6.1-sol@high=archivist (chatgpt-2026-11-05a), gpt-6.1-sol@xhigh=scholar (chatgpt-2026-11-05a), gpt-6-sol@medium=reader (chatgpt-2026-11-05a), gpt-5.6-sol@low=scanner (chatgpt-2026-11-05a)
streamfieldd and dind-console
The field server and the local console. You do not run them by hand: each needs its token in the environment, and din field start and din console start them with it. streamfieldd --help prints its usage; dind-console run without its token says what it needs:
usage:
streamfieldd serve the field (settings are env: FIELD_TOKEN, FIELD_STORE, FIELD_BIND, ...)
streamfieldd --version | -V | version
streamfieldd --help | -h
streamfieldd --org-report <store> [--map <file>] [--min-confidence <0..1>]
streamfieldd --whatif --store <dir> --map <candidate map> [...] (streamfieldd --whatif alone for its usage)
streamfieldd --claim-ids <store> [--write] (the index -> id map, A8; a dry run without --write)
streamfieldd --source-attribution <store> [--ledger <file>] [--json] (what attribution mode `evidence` would move; reads only)
dind-console: DASH_FIELD_TOKEN is required - it is this tenant's own field token.
usage: DASH_FIELD_TOKEN=<token> ./dind-console (run.sh reads it from a 0600 file)
Versions
Eight of the fifteen programs answer --version (din-session-record, din-import-graphiti, din-libcatalog, din-regrade, din-source and din-referee print their usage, and din-grade says to run din-import, above):
din 1.0.42
din-contract 1.0.42
din-dep-audit 1.0.42
din-import 1.0.42
din-record 1.0.42
dinctrl-store 1.0.42
dind-console 1.0.42
streamfieldd 1.0.42