Getting Started

Set the project path once (absolute), then run the installer with only the project path and no answer flags. An agent asks the user nothing before this run.

PROJECT=/absolute/path/to/project
./install.sh --project "$PROJECT"   # asks the questions at a terminal; otherwise prints them, the flag for each answer and a one-time token

Without a terminal: ask the user the printed questions, wait for the answers, then rerun with the flags the answers give (below) and --answers with the printed token, within an hour. Add --dry-run to that rerun first to see the plan. Answer flags passed without a valid token are listed as ignored. Never pick the answers yourself: Jev’s safety floor works without any key, so a missing key is not a reason to answer “no Jev”.

# only if the user chose host Jev
python3 scripts/jev_host_install.py --client claude --client codex --client cursor \
  --datarim-project "$PROJECT" --dry-run
python3 scripts/jev_host_install.py --client claude --client codex --client cursor \
  --datarim-project "$PROJECT"

python3 scripts/jev_host_install.py --client claude --client codex --client cursor --dry-run
python3 scripts/jev_host_install.py --client claude --client codex --client cursor

Only when the user said “defaults”: --without-jev, --client with the clients installed on the machine, --init and --permissions ask.

out="$(./install.sh --project "$PROJECT" <flags> 2>&1)"
token="$(printf '%s\n' "$out" | sed -n 's/.*--answers \([0-9a-f][0-9a-f]*\) .*/\1/p' | tail -n 1)"
[ -n "$token" ] || { printf '%s\n' "$out" >&2; exit 1; }
./install.sh --project "$PROJECT" --answers "$token" <flags>

The install is project-local: a pinned snapshot of the framework goes into .datarim-runtime/, the /dr-* commands go where each client finds them (Claude Code → .claude/commands/, Codex → .agents/skills/, Cursor → .cursor/skills/), and everything it writes is hidden from git status through .git/info/exclude. It does not touch your home directory, your shell startup files, AGENTS.md or .gitignore. Since 4.1, Claude Code reads AGENTS.md natively; the installer never creates CLAUDE.md. Per-client details: Runtimes.

Jev is optional. It adds a deterministic safety floor — a hook that refuses destructive shell commands, with no key or network needed — and, with an API key, model-tier routing advice. The advice is a suggestion: it does not switch the running model and grants no permissions.

$EDITOR ~/.config/jev/credentials/api-key   # host Jev; project Jev: config/credentials/jev/api-key

jev permissions          # show the current mode
jev permissions full     # jev* launchers start clients without permission prompts
jev permissions ask      # back to the client's own prompts (default)

cd "$PROJECT"
git status --short                       # expect: nothing from Datarim
source .datarim-runtime/activate.sh      # current shell only
jev doctor --agent=claude                # or --agent=codex / --agent=cursor

Expected jev doctor output (JSON), exit code 0:

• "scope": "project" (or "host" with --host-jev), "datarim_enabled": true;
• "findings": [] — a finding names what is missing (for example claude: executable missing, or cursor: Jev hook file missing (...)) and makes the exit code 1. Without --agent, doctor checks all three clients, so a client you do not use becomes a finding;
• "hook_clients" — the clients whose Jev hooks this install registered;
• "config_path" — the Jev settings file in use (.datarim-runtime/jev-config.json, or ~/.config/jev/config.json with host Jev); null without Jev;
• "native_agents_live" — per client, "state": "live" with a delivery count and the last delivery time once the ledger holds a hook_delivery record from that client; not_measured (with a reason) until the client has run a hook. When more than one client is registered, it lists every registered client, not only the one in --agent; a client without deliveries shows “no deliveries yet”;
• "key_ready": false until you add a key (true means the file is non-empty, not that the key is valid);
• "api": "not_measured" — offline doctor makes no network call; this is neither a pass nor a failure;
• "source_sha" — the commit you installed.

After adding a Jev key, jev doctor --api should exit 0 with "api": {"ok": true, "model": "...", ...}; a missing key gives "reason": "key missing" and exit code 1.

printf '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"cwd":"%s","session_id":"check"}' "$PWD" \
  | python3 .datarim-runtime/scripts/jev_hook.py claude PreToolUse      # project Jev
# host Jev: pipe the same payload into  ~/.local/share/jev/bin/jev-hook claude PreToolUse

cd ~/src/datarim
git fetch --tags origin
git checkout "$(git describe --tags --abbrev=0 --match 'v*' origin/main)"   # or: git checkout main && git pull
./update.sh --project "$PROJECT"   # the choices you installed with are remembered

update.sh runs the same installer as one transaction: it checks every file first, refuses to overwrite anything you edited, and rolls back on failure.

Your install choices are remembered. --with-jev, --host-jev, --context, --client, --expose-skills are recorded in .datarim-runtime/installation.json, so a plain update.sh --project keeps them, and the permission mode stays as it is. Pass an option only to change it: --without-jev withdraws the project’s Jev hooks and jev-config.json (the key file stays), --no-host-jev returns to project hooks, --no-context withdraws nested repositories, --client sets a new client list. Installs made before 4.0 have no recorded client list and keep all three.

Kept across an update: datarim/, config/credentials/, .datarim-runtime/state/ (ledger, on/off and permission switches), and .datarim-runtime/jev-config.json while Jev stays on. Anything else inside .datarim-runtime/ is replaced, including the plugin links under .datarim-runtime/local/: run /dr-plugin sync after the update. The previous runtime is kept in .datarim-runtime-previous/, older ones in .datarim-runtime-backups/. Host Jev: rerun scripts/jev_host_install.py with the same --client and --datarim-project options from the updated checkout; Codex keeps its trust, because the hook command names a stable entry point.

~/src/datarim/install.sh --project "$PROJECT" --uninstall --dry-run
~/src/datarim/install.sh --project "$PROJECT" --uninstall

This restores the files the install changed to their pre-install content, removes the command files and hook entries it added, and moves the runtime to .datarim-uninstalled/. Task state (datarim/), keys (config/credentials/) and runtime backups stay, still hidden from git; delete them yourself when you no longer need them. A second uninstall refuses while .datarim-uninstalled/ exists. Files you edited after install stop the uninstall until you reconcile them.

Host Jev has no uninstaller. jev off stops all Jev API calls on the host. To remove it, delete the Jev entries (commands naming ~/.local/share/jev/bin/jev-hook) from the client configs, then ~/.local/bin/{jev,jevclaude,jevcodex,jevcursor}, ~/.local/share/jev/, ~/.config/jev/ (holds the key) and ~/.local/state/jev/ (holds install backups).

Something went wrong? The troubleshooting table in INSTALL.md maps each installer message to its cause and fix.

Every Datarim-managed repo and product site must organise its documentation per Diátaxis: four orthogonal categories — tutorials/ (learning), how-to/ (problem-solving), reference/ (lookup), explanation/ (understanding).

documentation/
├── tutorials/        # learning-oriented
├── how-to/           # problem-solving (testing, deployment, gotchas)
├── reference/        # information-oriented (architecture, api, cli)
└── explanation/      # understanding-oriented (design, concepts)

Closed set: faq, glossary, troubleshooting, examples, overview, samples — mappable, never separate top-level types. Stack-agnostic — SSG/CMS choice per-project. /dr-init create project scaffolds this layout under documentation/; /dr-optimize gives a soft drift warning, and a hard CI gate is deferred.