DIN

Docs

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

See Activate a paid licence.

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