diff --git a/.bob/custom_modes.yaml b/.bob/custom_modes.yaml
new file mode 100644
index 0000000..2ffa95b
--- /dev/null
+++ b/.bob/custom_modes.yaml
@@ -0,0 +1,21 @@
+customModes:
+  - slug: origit-build
+    name: 🧾 Origit Build
+    description: Build features with full provenance. Edits limited to src/**; declare what you read and what you added.
+    roleDefinition: >-
+      You are a senior engineer working in a regulated fintech. Every change you make is recorded by Origit
+      (what you read, what you wrote, which dependencies you added, which commands you ran) and attached to the
+      commit as tamper-evident evidence. Work in small, committable steps.
+    whenToUse: Use for implementing product features in repositories instrumented with Origit.
+    customInstructions: >-
+      Before writing code, read the documentation of any library you intend to use with the read_file tool so the
+      read is traced. When you add a dependency, add it with a pinned exact version and state the package name and
+      version in your final message. Finish each task with a short "Origit declaration" listing: files read, files
+      written, dependencies added, commands run.
+    groups:
+      - read
+      - - edit
+        - fileRegex: "^src/.*"
+          description: Source files only (src/**)
+      - execute
+      - todo
diff --git a/.bob/hooks/origit-trace.sh b/.bob/hooks/origit-trace.sh
new file mode 100755
index 0000000..1110bf7
--- /dev/null
+++ b/.bob/hooks/origit-trace.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+# Origit tracer — called by Bob IDE lifecycle hooks with the event JSON on stdin.
+# Appends every event to .origit/trace.jsonl. Never fails (exit 0), never blocks Bob.
+mkdir -p .origit
+top=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+for c in "$ORIGIT_BIN" "$(command -v origit 2>/dev/null)" "$top/origit/.venv/bin/origit" "$top/.venv/bin/origit"; do
+  if [ -n "$c" ] && [ -x "$c" ]; then "$c" trace --root . 2>>.origit/hook-errors.log; exit 0; fi
+done
+printf '{"ts":"%s","raw":' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> .origit/trace.jsonl
+cat >> .origit/trace.jsonl
+printf '}\n' >> .origit/trace.jsonl
+exit 0
diff --git a/.bob/rules-origit-build/01-origit-declare.md b/.bob/rules-origit-build/01-origit-declare.md
new file mode 100644
index 0000000..1362ce6
--- /dev/null
+++ b/.bob/rules-origit-build/01-origit-declare.md
@@ -0,0 +1,18 @@
+# Origit provenance rules (mode: origit-build)
+
+- Read library documentation through the file tools (`read_file`) before using a library. Origit traces those reads; a library you use without reading is invisible to the taint query.
+- Add dependencies with an exact pinned version (`npm install <name>@<x.y.z> --save-exact`). Never add a dependency you have not read the README or docs of.
+- Only edit files under `src/`. Tests live in `src/**/*.test.ts`.
+- Run the test suite (`npm test`) before you finish.
+- End every task with an **Origit declaration**:
+
+  ```
+  Origit declaration
+  read:  <paths / packages / URLs you consulted>
+  wrote: <paths>
+  added_deps: <name@version> (or none)
+  commands: <commands you ran>
+  ```
+
+- Do not touch `.bob/`, `.origit/`, `.githooks/`, `.env` or lockfiles by hand.
+- Synthetic data only. Use test PANs like 4111 1111 1111 1111. Never real card numbers or personal data.
diff --git a/.bob/settings.json b/.bob/settings.json
new file mode 100644
index 0000000..290d53d
--- /dev/null
+++ b/.bob/settings.json
@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "sh .bob/hooks/origit-trace.sh", "timeout": 5 } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": ".*", "hooks": [ { "type": "command", "command": "sh .bob/hooks/origit-trace.sh", "timeout": 5 } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": ".*", "hooks": [ { "type": "command", "command": "sh .bob/hooks/origit-trace.sh", "timeout": 5 } ] }
+    ],
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "sh .bob/hooks/origit-trace.sh", "timeout": 5 } ] }
+    ]
+  }
+}
diff --git a/.githooks/origit-bin.sh b/.githooks/origit-bin.sh
new file mode 100755
index 0000000..4c2c6da
--- /dev/null
+++ b/.githooks/origit-bin.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+# Locate the origit CLI: $ORIGIT_BIN, then PATH, then a venv inside the repo.
+top=$(git rev-parse --show-toplevel 2>/dev/null)
+for c in "$ORIGIT_BIN" "$(command -v origit 2>/dev/null)" "$top/origit/.venv/bin/origit" "$top/.venv/bin/origit"; do
+  [ -n "$c" ] && [ -x "$c" ] && { echo "$c"; exit 0; }
+done
+exit 1
diff --git a/.githooks/post-commit b/.githooks/post-commit
new file mode 100755
index 0000000..77365c8
--- /dev/null
+++ b/.githooks/post-commit
@@ -0,0 +1,4 @@
+#!/bin/sh
+# Origit post-commit: attach the pending record to HEAD as a git note (refs/notes/origit) and clear the trace.
+ORIGIT=$(sh "$(dirname "$0")/origit-bin.sh") || exit 0
+"$ORIGIT" record attach || echo "origit: WARNING record not attached to $(git rev-parse --short HEAD)" >&2
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000..dfae64c
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,5 @@
+#!/bin/sh
+# Origit pre-commit: fold the Bob trace into a pending record.
+# Rule: a commit without a record does not exist. Set ORIGIT_REQUIRE_TRACE=1 to refuse untraced (agent) commits.
+ORIGIT=$(sh "$(dirname "$0")/origit-bin.sh") || { echo "origit: CLI not found; refusing to commit without provenance (pip install -e origit/ or set ORIGIT_BIN)" >&2; exit 1; }
+"$ORIGIT" record fold || exit 1
diff --git a/.gitignore b/.gitignore
index d81f23f..543e844 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,6 @@ coverage/
 !.env.example
 # origit runtime state (folded into git notes)
 .origit/
+# origit runtime state
+.origit/trace.jsonl
+.origit/pending-record.json