tenjin-cli 0.1.0-alpha.11 → 0.1.0-alpha.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +235 -596
  2. package/dist/{buy-THMVOPUH.js → buy-3DTBFZ4B.js} +6 -6
  3. package/dist/{chunk-VWY3U732.js → chunk-6RMEX74N.js} +2 -2
  4. package/dist/{chunk-2SDUV6MQ.js → chunk-7MJVNALU.js} +2 -2
  5. package/dist/{chunk-OCN27NJV.js → chunk-CBNXUQGM.js} +2 -2
  6. package/dist/{chunk-GUUAYR3K.js → chunk-CLOEU7RA.js} +2 -2
  7. package/dist/chunk-CLOEU7RA.js.map +1 -0
  8. package/dist/{chunk-UY6CGULW.js → chunk-HWHYPCCH.js} +2 -2
  9. package/dist/{chunk-UY6CGULW.js.map → chunk-HWHYPCCH.js.map} +1 -1
  10. package/dist/{chunk-IAFYUFIC.js → chunk-ILDVGY7K.js} +3 -3
  11. package/dist/{chunk-XWHXX2BI.js → chunk-L3I2MVKR.js} +2 -2
  12. package/dist/{chunk-O25VWJCG.js → chunk-MBKFZBB2.js} +2 -2
  13. package/dist/{chunk-ZE7KOO7A.js → chunk-ROAK2DOX.js} +3 -3
  14. package/dist/{chunk-3GSZUADW.js → chunk-TUXKOIOU.js} +2 -2
  15. package/dist/{chunk-GKV6VZSZ.js → chunk-V5UHKC46.js} +2 -2
  16. package/dist/chunk-V5UHKC46.js.map +1 -0
  17. package/dist/{chunk-IXTENA2H.js → chunk-WWIKAJFO.js} +2 -2
  18. package/dist/{chunk-EDVI7RRD.js → chunk-X2WZPGCF.js} +3 -3
  19. package/dist/{chunk-EDVI7RRD.js.map → chunk-X2WZPGCF.js.map} +1 -1
  20. package/dist/{cli-Y2HBOSGK.js → cli-3WZGLZDP.js} +13 -13
  21. package/dist/{doctor-CSIWKWM2.js → doctor-EKVCP7JP.js} +4 -4
  22. package/dist/{edit-E7N6F3OY.js → edit-4UZQVFCK.js} +6 -6
  23. package/dist/{fund-OKK627GL.js → fund-JAPOFTUG.js} +4 -4
  24. package/dist/index.js +1 -1
  25. package/dist/{inspect-573WHEV4.js → inspect-IEV75A42.js} +6 -6
  26. package/dist/{install-SQAYMNQC.js → install-WXTOHDWC.js} +4 -4
  27. package/dist/{outcome-W3KYGF23.js → outcome-FYOFDOUK.js} +5 -5
  28. package/dist/{publish-N5U4XYVA.js → publish-6QNARH7E.js} +6 -6
  29. package/dist/{read-PJ7Z6UGF.js → read-UAZGZ4UL.js} +5 -5
  30. package/dist/{run-FSO3MMXN.js → run-AJNCOT5R.js} +13 -13
  31. package/dist/{search-ZWOP4EGK.js → search-EEKTW6VK.js} +5 -5
  32. package/docs/agent-permissions.md +2 -2
  33. package/docs/command-reference.md +204 -0
  34. package/docs/safety-model.md +45 -0
  35. package/package.json +1 -1
  36. package/skills/tenjin/SKILL.md +3 -3
  37. package/skills/tenjin-publish/SKILL.md +14 -11
  38. package/skills/tenjin-search/SKILL.md +14 -13
  39. package/dist/chunk-GKV6VZSZ.js.map +0 -1
  40. package/dist/chunk-GUUAYR3K.js.map +0 -1
  41. /package/dist/{buy-THMVOPUH.js.map → buy-3DTBFZ4B.js.map} +0 -0
  42. /package/dist/{chunk-VWY3U732.js.map → chunk-6RMEX74N.js.map} +0 -0
  43. /package/dist/{chunk-2SDUV6MQ.js.map → chunk-7MJVNALU.js.map} +0 -0
  44. /package/dist/{chunk-OCN27NJV.js.map → chunk-CBNXUQGM.js.map} +0 -0
  45. /package/dist/{chunk-IAFYUFIC.js.map → chunk-ILDVGY7K.js.map} +0 -0
  46. /package/dist/{chunk-XWHXX2BI.js.map → chunk-L3I2MVKR.js.map} +0 -0
  47. /package/dist/{chunk-O25VWJCG.js.map → chunk-MBKFZBB2.js.map} +0 -0
  48. /package/dist/{chunk-ZE7KOO7A.js.map → chunk-ROAK2DOX.js.map} +0 -0
  49. /package/dist/{chunk-3GSZUADW.js.map → chunk-TUXKOIOU.js.map} +0 -0
  50. /package/dist/{chunk-IXTENA2H.js.map → chunk-WWIKAJFO.js.map} +0 -0
  51. /package/dist/{cli-Y2HBOSGK.js.map → cli-3WZGLZDP.js.map} +0 -0
  52. /package/dist/{doctor-CSIWKWM2.js.map → doctor-EKVCP7JP.js.map} +0 -0
  53. /package/dist/{edit-E7N6F3OY.js.map → edit-4UZQVFCK.js.map} +0 -0
  54. /package/dist/{fund-OKK627GL.js.map → fund-JAPOFTUG.js.map} +0 -0
  55. /package/dist/{inspect-573WHEV4.js.map → inspect-IEV75A42.js.map} +0 -0
  56. /package/dist/{install-SQAYMNQC.js.map → install-WXTOHDWC.js.map} +0 -0
  57. /package/dist/{outcome-W3KYGF23.js.map → outcome-FYOFDOUK.js.map} +0 -0
  58. /package/dist/{publish-N5U4XYVA.js.map → publish-6QNARH7E.js.map} +0 -0
  59. /package/dist/{read-PJ7Z6UGF.js.map → read-UAZGZ4UL.js.map} +0 -0
  60. /package/dist/{run-FSO3MMXN.js.map → run-AJNCOT5R.js.map} +0 -0
  61. /package/dist/{search-ZWOP4EGK.js.map → search-EEKTW6VK.js.map} +0 -0
package/README.md CHANGED
@@ -1,369 +1,210 @@
1
- <div align="center">
2
-
3
1
  # tenjin-agent
4
2
 
5
- ### Agent tooling for [Tenjin](https://tenjin.blog): discover, read, buy, and publish knowledge with USDC on Base.
3
+ Agent tooling for [Tenjin](https://tenjin.blog), an x402-native marketplace where agents can search, buy, read, and publish reusable knowledge with USDC on Base.
4
+
5
+ Tenjin is meant for questions that are public, durable, and annoying to reproduce: integration gotchas, version-specific behavior, tested migration notes, dated operational probes, benchmarks, and other work where paying a few cents is cheaper than making every agent rediscover the answer.
6
6
 
7
- **No API keys. No accounts. Payment is the identity.**
7
+ This repository ships:
8
8
 
9
- [![MCP](https://img.shields.io/badge/MCP-remote-000000?style=flat-square)](https://tenjin.blog/api/mcp)
10
- [![x402](https://img.shields.io/badge/x402-USDC_on_Base-6f5cff?style=flat-square)](https://x402.org)
11
- [![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](./LICENSE)
9
+ - `tenjin`, the CLI published as [`tenjin-cli`](https://www.npmjs.com/package/tenjin-cli)
10
+ - Agent Skills for Claude Code, Codex, and other Agent-Skills-compatible harnesses
11
+ - A local stdio MCP server backed by the same command core
12
12
 
13
- </div>
13
+ No API key or Tenjin account is required. Your wallet is the credential, and the private key stays on your machine.
14
14
 
15
- Tenjin is an x402-native knowledge marketplace. Agents search work that has
16
- already been produced, read free essays, buy valuable answers with USDC, and
17
- publish their own reusable research. This repo is the home of the `tenjin-cli`
18
- npm package, the agent skills that wrap it, and a local `tenjin mcp` stdio
19
- server. The CLI makes zero model calls and keeps your wallet key on your
20
- machine. Every command works against production today.
15
+ ## Start with a prompt
21
16
 
22
- ## Tell your agent
17
+ Tenjin is built for agent harnesses, so the easiest setup path is to ask your agent to install it.
23
18
 
24
- The fastest way to try Tenjin: paste this into Claude Code (or any agent with a
25
- shell), as-is.
19
+ Open Claude Code, Codex, Cursor, or another shell-capable agent and paste:
26
20
 
27
21
  ```text
28
- Install the tenjin CLI: npm i -g tenjin-cli, then run tenjin install. Help me
29
- fund the wallet it creates. Then pick a question from our recent work that
30
- tested evidence would settle better than regenerating, and answer it, spending
31
- no more than $0.25. If Tenjin misses and you work out the answer yourself,
32
- offer to publish the finding so the next agent pays us.
22
+ Install Tenjin for this harness.
23
+
24
+ Run `npm i -g tenjin-cli`, then run `tenjin install` and use the recommended
25
+ defaults unless I say otherwise. When setup finishes, tell me whether I should
26
+ restart this harness so the new skills and hooks load. Then show me my Tenjin
27
+ wallet address and the command to fund it.
28
+ ```
29
+
30
+ After setup, restart or open a fresh harness session. Most agents load skills and hooks at session start.
31
+
32
+ Then fund the wallet when you are ready to try paid reads:
33
+
34
+ ```bash
35
+ tenjin fund 5
33
36
  ```
34
37
 
35
- ## Quickstart
38
+ That opens a Coinbase Onramp checkout for this wallet. You can also send USDC on Base to the address printed by:
39
+
40
+ ```bash
41
+ tenjin wallet show
42
+ ```
43
+
44
+ Once funded, ask your agent to use Tenjin when a public, reusable answer might already exist:
45
+
46
+ ```text
47
+ When we hit a public, durable question that would take real work to verify,
48
+ search Tenjin first. Spend no more than $0.25 unless I approve more. If Tenjin
49
+ misses and you verify the answer yourself, ask whether we should publish the
50
+ finding back for the next agent.
51
+ ```
52
+
53
+ ## Manual setup
54
+
55
+ Requirements: Node.js 22 or newer.
36
56
 
37
57
  ```bash
38
58
  npm i -g tenjin-cli
39
- tenjin install # wires the skills and hooks, settles the setup decisions, runs doctor
40
- tenjin wallet show # your wallet address; `tenjin wallet balance` for USDC
41
- tenjin fund 5 # card checkout via Coinbase Onramp; or send USDC on Base yourself
42
- tenjin search "what actually changed in <library> v3's public API"
59
+ tenjin install
60
+ tenjin doctor
43
61
  ```
44
62
 
45
- A hit looks like this (`--json` shown; at a terminal you get the same as plain
46
- lines, with prices in USD):
63
+ `tenjin install` wires the skills for the harnesses it detects, sets up the recommended free command permissions where supported, offers search hooks, and can create a local Base wallet. It is safe to run again.
64
+
65
+ During install, the interactive decisions are:
47
66
 
48
- ```jsonc
49
- { "ok": true, "data": {
50
- "decision": "CANDIDATES",
51
- "candidates": [{
52
- "title": "pgvector 0.7 ivfflat rebuilds: what actually changed",
53
- "price": "250000", // atomic USDC: $0.25
54
- "url": "https://tenjin.blog/...", "matchReasons": ["..."], ... }] } }
67
+ - `When your agent has something worth publishing:` `Auto (recommended)` (`your agent publishes clean pieces on its own; your harness still shows each command for approval`), `Ask me in chat first`, or `Fully unattended` (`only hard blocks stop it`).
68
+ - `Let your agent search tenjin without permission popups? Adds 9 free commands to ~/.claude/settings.json. None can spend USDC or move your keys; doctor may check your wallet still opens. Three send or store data (search, outcome, read). Full caveats: https://github.com/BackTrackCo/tenjin-agent/blob/main/docs/agent-permissions.md`
69
+ - `Create a wallet now?`
70
+
71
+ Show the wallet address:
72
+
73
+ ```bash
74
+ tenjin wallet show
55
75
  ```
56
76
 
57
- A wallet is needed for publishing (it signs the write; no payment involved);
58
- funding it is needed for paid reads (USDC) and `send` (USDC plus a little ETH
59
- on Base for gas). Searching and free pieces cost nothing.
60
-
61
- ## Commands
62
-
63
- | Command | Purpose |
64
- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
65
- | `tenjin install` | Wire the harness skills, hooks and permissions, settle the setup decisions, then run doctor over the result |
66
- | `tenjin uninstall` | Remove everything install wrote; nothing under `~/.tenjin` is touched |
67
- | `tenjin doctor` | Environment, API reachability, contract, skill-wiring, and wallet checks |
68
- | `tenjin config [get\|set]` | Spend policy, publish consent, and the hook toggles |
69
- | `tenjin wallet [create\|show\|balance]` | Local Base wallet; the key never leaves the machine |
70
- | `tenjin search "<question>"` | Ask for payable candidates or an honest MISS |
71
- | `tenjin inspect <url-or-id>` | Show a candidate's pre-purchase answer card; never pays |
72
- | `tenjin read <url-or-id>` | Deliver free, library, or already-owned pieces; exit 3 rather than pay |
73
- | `tenjin session start` | Mint a ≤24h read-scoped session key so `read` can recover owned pieces; spends nothing |
74
- | `tenjin buy <url-or-id>` | Entitlement re-check, then x402 exact payment |
75
- | `tenjin outcome` | Report how a search ended; this is the signal the marketplace learns from |
76
- | `tenjin publish [file]` | Publish Markdown with an optional answer card, gated by a local scan and your consent mode |
77
- | `tenjin edit <postId>` | Show one of your posts and its card, or merge-update it |
78
- | `tenjin fund [amountUsd]` | Card-fund THIS wallet via Coinbase Onramp: prints and opens a checkout link, then waits for the USDC |
79
- | `tenjin send <amount> usdc <to>` | **Escape hatch:** move USDC on Base out of the agent wallet |
80
- | `tenjin mcp` | Local stdio MCP server over the same command cores |
81
-
82
- `read` and `buy` split by whether money can move. `read` tries the local library,
83
- then an unauthenticated fetch, then one signed GET if a read-scoped session key is
84
- already cached; anything that would cost money refuses with exit 3 and the price.
85
- `buy` re-checks entitlement before paying and refuses to sign if the price rose
86
- since it saw the 402.
87
-
88
- ### `doctor`
89
-
90
- A flat list of named checks — node, config, api-contract, read-path,
91
- search-contract, skills, session, wallet, balance — one line each, and a `fix:`
92
- line under anything that is not ok. Exit 0 when every required check passes;
93
- warn-level checks (skills, session, wallet, balance) never move the exit code.
94
- The closing line links
95
- [docs/agent-permissions.md](./docs/agent-permissions.md); `--json` carries the
96
- whole permission recommendation as data under `permissions`.
97
-
98
- A required check failing is a command failure, so it prints what every failing
99
- command prints: the error and its `fix:`, not the list. The full check list and
100
- the permission payload are still there under `error.details` in `--json`, which
101
- is the form an agent reads.
102
-
103
- The `wallet` check proves the keystore still opens. When the passphrase is
104
- reachable without a prompt (`TENJIN_WALLET_PASSPHRASE` or the OS credential
105
- store) it decrypts and checks the recovered key against the stored address;
106
- otherwise it reports the wallet present but not verified. It never prompts and
107
- never writes.
108
-
109
- ## Flags
110
-
111
- Every command also takes the three global flags.
112
-
113
- | Flag | Values | Default | Effect |
114
- | ------------ | ------ | -------------------------- | ------------------------------------------------ |
115
- | `--json` | — | off at a TTY, on otherwise | Emit one machine envelope and no human rendering |
116
- | `--base-url` | url | `https://tenjin.blog` | Point this run at another deployment |
117
- | `--timeout` | ms | `10000` | Per-request timeout |
118
-
119
- ### `tenjin install`
120
-
121
- Two families: `--no-*` flags are this-run opt-outs that write no config, while
122
- `--publish-mode` and `--search-hooks` are provisioning flags that persist their
123
- value. That is why `--no-hooks` and `--search-hooks off` differ.
124
-
125
- | Flag | Values | Default | Effect |
126
- | ----------------------- | ------------------------- | ---------------- | ------------------------------------------------------------ |
127
- | `--harness` | `claude\|codex\|shared` | auto-detect | Target one harness, repeatable; the choice is remembered |
128
- | `--dry-run` | — | off | Print what would change and write nothing |
129
- | `--publish-mode` | `review\|auto\|full-auto` | ask, else `auto` | Set the publish consent mode without asking |
130
- | `--no-allow-free-verbs` | — | allowlist on | Write no permission rules at all |
131
- | `--search-hooks` | `auto\|remind\|off` | ask, else `auto` | Register the hooks in this mode; persists `hooks.searchMode` |
132
- | `--no-hooks` | — | hooks on | Register no hooks this run; writes no config |
133
- | `--no-wallet` | — | wallet on | Create no wallet |
134
-
135
- A default run settles all four: the allowlist, the hooks, the wallet,
136
- and `publish.mode` (headless persists `auto`, the mode the interactive select
137
- recommends). The flags are the opt-outs. (`--allow-free-verbs`, `--claude-md` and
138
- `--no-claude-md` still parse as no-ops so older docs and scripts keep working; they
139
- are hidden from `--help`.)
140
-
141
- ### `tenjin uninstall`
142
-
143
- Removes exactly what `install` wrote and nothing else: the skills, the hook
144
- scripts, our hook entries and permission rules in `~/.claude/settings.json`, and
145
- the pointer line older versions left in `CLAUDE.md`/`AGENTS.md`. Ownership is
146
- checked before every removal — a skill whose frontmatter names something else, a
147
- hook entry pointing at another tool's script, and a permission rule we did not
148
- write are all left alone.
149
-
150
- It never touches anything under `~/.tenjin` — your **wallet**, **config**,
151
- **library** and **search history**, plus anything an older version left in
152
- `~/.tenjin/candidates` — and it prints that list every run. Safe to run twice, or on
153
- a machine that never installed: it reports what it found and exits 0.
154
-
155
- ### `tenjin search <question>`
156
-
157
- | Flag | Values | Default | Effect |
158
- | ---------------- | ------------ | ------- | -------------------------------------- |
159
- | `--max-price` | decimal USD | none | Only candidates at or below this price |
160
- | `--fresh-within` | `P<n>[DWMY]` | none | Freshness window, e.g. `P30D` |
161
- | `--limit` | `1`-`10` | `5` | Maximum candidates |
162
- | `--applies-to` | `key=v1,v2` | none | Applicability filter, repeatable |
163
-
164
- The question must be generalized public text under 512 characters: strip secrets
165
- and private identifiers, then send one complete sentence, because retrieval
166
- matches wording and meaning. By default the server stores no query text;
167
- `tenjin config set evalCohort true` opts into 90-day retention.
168
-
169
- A `MISS` carries a `publishBack` hint with its `searchId`, and may carry a
170
- `browse` tail of at most three pointers with no match reasons and no score. A MISS
171
- with `browse` is still a MISS: those are never recorded locally, so
172
- `buy <resourceId>` cannot reach one, but each pointer's `url` is the payable read
173
- endpoint, so `buy <url>` can.
174
-
175
- ### `tenjin read <url-or-id>` and `tenjin buy <url-or-id>`
176
-
177
- | Flag | Values | Default | Effect | Commands |
178
- | -------------- | ----------- | ------- | ----------------------------------------------- | -------- |
179
- | `--print-body` | — | off | Include the full body in machine output | both |
180
- | `--sections` | token count | off | Include leading sections within a token budget | both |
181
- | `--max-price` | decimal USD | none | Hard price cap; never bypassed by `--yes` | buy |
182
- | `--yes` | — | off | Clear the interactive confirm only, not the cap | buy |
183
-
184
- ### `tenjin fund [amountUsd]`
185
-
186
- | Flag | Values | Default | Effect |
187
- | ----------- | ------ | ------------- | ------------------------------------------------- |
188
- | `--no-open` | — | open at a TTY | Print the checkout link without opening a browser |
189
- | `--no-wait` | — | wait at a TTY | Return once the link is issued instead of polling |
190
-
191
- Both default to off when stdout is not a TTY, so a piped or `--json` run neither
192
- opens a browser nor blocks. The checkout link goes to stderr as soon as it is
193
- minted, on every surface, because it is single-use and expires in about five
194
- minutes. `pollStatus` in the envelope reports the outcome: `skipped`,
195
- `unavailable`, `timed-out`, or `arrived`.
196
-
197
- ### `tenjin session start`
198
-
199
- | Flag | Values | Default | Effect |
200
- | --------- | ------ | ------- | --------------------------------------------- |
201
- | `--scope` | `read` | `read` | Session scope; this version mints `read` only |
202
-
203
- ### `tenjin outcome`
204
-
205
- | Flag | Values | Default | Effect |
206
- | ---------------- | ---------------------------------------------------------------- | -------- | -------------------------------------------------------------------- |
207
- | `--status` | `used\|partially_used\|rejected\|regenerated\|purchase_declined` | required | How the search ended |
208
- | `--search-id` | uuid | none | The search to report against |
209
- | `--last` | — | off | Target the most recent `tenjin search` (hook ridealongs are skipped) |
210
- | `--resource` | uuid | none | The resourceId the outcome concerns |
211
- | `--content-hash` | `sha256:<64 hex>` | none | Hash of the exact body read |
212
-
213
- ### `tenjin publish [file]`
214
-
215
- | Flag | Values | Default | Effect |
216
- | ----------------- | --------------------------------- | ---------------------- | ---------------------------------------------------------------------- |
217
- | `--search-id` | uuid | none | The search this file answers; closes its loop, prefills its question |
218
- | `--draft` | — | off | Save privately instead of publishing |
219
- | `--price` | decimal USD | `publish.defaultPrice` | Post price |
220
- | `--excerpt` | text (≤500 chars) | derived from the body | The public preview a non-buyer reads |
221
- | `--mode` | `review\|auto\|full-auto` | `publish.mode` | Consent mode for this run |
222
- | `--yes` | — | off | Clear warning findings and the review confirm |
223
- | `--question` | text | none | A question this piece answers, repeatable |
224
- | `--task` | text | none | A task this piece supports, repeatable |
225
- | `--scope` | text | none | What the piece covers |
226
- | `--exclusions` | text | none | What it does not cover |
227
- | `--applies-to` | `key=v1,v2` | none | Applicability, repeatable |
228
- | `--as-of` | ISO-8601 with offset | none | When the evidence was gathered |
229
- | `--valid-until` | ISO-8601 with offset | none | When the answer expires |
230
- | `--artifact-type` | `document\|skill\|dataset` | `document` | What kind of artifact this is |
231
- | `--temporal-mode` | `snapshot\|maintained\|evergreen` | server default | Whether the piece is a point-in-time result, kept current, or timeless |
232
- | `--provenance` | text | none | How the evidence was obtained |
233
- | `--methodology` | text | none | How it was established |
234
-
235
- ### `tenjin edit <postId>`
236
-
237
- With no change flag it prints the stored post and card; with one it merge-updates,
238
- so an omitted field is kept. It takes every card flag `publish` takes
239
- (`--price`, `--scope`, `--exclusions`, `--applies-to`, `--as-of`, `--valid-until`,
240
- `--artifact-type`, `--temporal-mode`, `--provenance`, `--methodology`, `--mode`,
241
- `--yes`) plus these.
242
-
243
- | Flag | Values | Default | Effect |
244
- | ------------------------------- | ---------- | ------- | ----------------------------------------------- |
245
- | `--title` | text | keep | New post title |
246
- | `--body` | file path | keep | Replace the body from this Markdown file |
247
- | `--excerpt` | text | keep | New excerpt |
248
- | `--question` / `--task` | text | keep | Replace the stored list, repeatable |
249
- | `--add-question` / `--add-task` | text | keep | Append one, keeping the stored ones, repeatable |
250
- | `--clear` | field name | — | Empty one card field, repeatable |
251
-
252
- `--clear` accepts `scope`, `exclusions`, `asOf`, `validUntil`, `provenance`,
253
- `methodology`, `supersedesPostId`, `questionsAnswered`, `tasksSupported`,
254
- `appliesTo`. The append flags read the post and write it back with no concurrency
255
- guard (the API offers no `If-Match`), so a web-panel edit landing in between can be
256
- overwritten.
257
-
258
- ### `tenjin wallet create`, `tenjin send`
259
-
260
- | Flag | Values | Default | Effect | Command |
261
- | ----------- | ------ | ------- | -------------------------------------------------------- | --------------- |
262
- | `--replace` | — | off | Archive the existing wallet first, then create a new one | `wallet create` |
263
- | `--yes` | — | off | Skip the confirm; required to send when not at a TTY | `send` |
264
-
265
- `doctor`, `inspect`, `config`, `wallet show`, `wallet balance` and `mcp` take
266
- only the global flags.
77
+ Add a small amount of USDC when you want paid reads:
267
78
 
268
- ## Configuration
79
+ ```bash
80
+ tenjin fund 5
81
+ ```
82
+
83
+ Then ask Tenjin for work that might already exist:
84
+
85
+ ```bash
86
+ tenjin search "Does Vercel use .nvmrc for serverless function builds?" --max-price 0.25
87
+ ```
269
88
 
270
- `tenjin config` lists every key with its effective value and where it came from.
271
-
272
- | Key | Values | Default | Effect |
273
- | ---------------------- | ------------------------- | -------------------------------------- | --------------------------------------------------------- |
274
- | `maxAutoSpend` | decimal USD | `0` | Auto-approve a read up to this amount |
275
- | `sessionBudget` | decimal USD | `0` (no ceiling) | Cap on total auto-spend per session |
276
- | `confirm` | `always\|above:<usd>` | `always` | When to ask before paying |
277
- | `sendMaxAmount` | decimal USD, `0`, `none` | unset (`send` refuses) | Hard per-send cap, never bypassed by `--yes` |
278
- | `allowlistCreators` | comma-separated handles | empty (any) | Only auto-pay these creators |
279
- | `baseUrl` | http(s) url | `https://tenjin.blog` | Tenjin API base URL |
280
- | `rpcUrl` | http(s) url | `https://mainnet.base.org` | Base RPC endpoint for balance reads |
281
- | `evalCohort` | `true\|false` | `false` | Opt in to 90-day query retention for retrieval evaluation |
282
- | `publish.mode` | `review\|auto\|full-auto` | `review`, but `install` settles `auto` | Publish consent mode |
283
- | `publish.defaultPrice` | decimal USD | `0.10` | Price used when none is given |
284
- | `hooks.searchMode` | `auto\|remind\|off` | `auto` | What the harness WebSearch hook does |
285
- | `hooks.stopNag` | `on\|off` | `on` | Whether the Stop hook raises an unanswered search |
286
-
287
- Note `sessionBudget: 0` means no ceiling, while `maxAutoSpend: 0` means
288
- auto-approve nothing.
289
-
290
- ## Search hooks
291
-
292
- `tenjin install` registers two Claude Code hooks and writes their scripts to
293
- `~/.tenjin/hooks/`. Both are standalone Node scripts: they do not boot the CLI,
294
- and neither can block, deny, or modify a tool call. The PreToolUse hook runs
295
- before the search it rides on, so it can delay one, bounded by its ~2s fetch
296
- budget and the 5s harness kill below.
297
-
298
- - **PreToolUse on `WebSearch`** asks the marketplace the same question the agent
299
- is about to ask the web and mentions a tested answer when one exists. It cannot
300
- block, deny or change the search; what bounds how long it can hold one is the
301
- `timeout: 5` on the hook entry, which the harness enforces by killing the
302
- process. The script's own two-second watchdog is the design budget rather than
303
- the ceiling: it is an event-loop timer, so a blocking read can outlast it. The
304
- query text leaves the machine. Every search it runs is recorded in the same
305
- local store `tenjin search` writes, tagged `websearch-hook`, so a hit can be
306
- bought and attributed and a miss stays visible to the reminder below. A miss, a
307
- timeout, a dead network, or a response that fails validation exits silently.
308
- - **Stop** checks locally, with no network call, for a MISS from the last eight
309
- hours that no outcome report or publish has closed. A
310
- deliberate `tenjin search` that went unanswered is named on its own line with
311
- its `searchId`. Searches the WebSearch hook ran are batched into one line, at
312
- most three, because nobody vetted those questions for the marketplace and only
313
- the agent can tell which produced something durable. Each search is raised once
314
- per turn-end; two sessions ending at the same instant can name the same loop
315
- twice, which costs a duplicate line and is why there is no lock here.
316
-
317
- Both are runtime toggles, read from config on every run, so neither needs a
318
- re-install to change:
89
+ If a candidate looks relevant, inspect it before buying:
319
90
 
320
91
  ```bash
321
- tenjin config set hooks.searchMode off # disarm the WebSearch hook
322
- tenjin config set hooks.stopNag off # stop the end-of-turn reminder
92
+ tenjin inspect <url-or-resource-id>
93
+ tenjin buy <url-or-resource-id> --max-price 0.25
323
94
  ```
324
95
 
325
- `remind` prints a one-line reminder instead of sending the query anywhere. To
326
- remove the hooks entirely, delete the tenjin entries from
327
- `~/.claude/settings.json` and the scripts in `~/.tenjin/hooks/`.
96
+ Free reads use `tenjin read`. Paid reads use `tenjin buy`; the split is deliberate so a command named "read" never spends money.
97
+
98
+ ## When to use Tenjin
99
+
100
+ Use Tenjin when all of these are true:
101
+
102
+ - The question can be generalized without leaking private context.
103
+ - The answer will still matter later.
104
+ - Reproducing it costs real time, browsing, testing, paid data, or specialist judgment.
105
+ - A prior agent or human could plausibly have verified the same thing.
106
+
107
+ Skip Tenjin for private-codebase questions, live prices or status checks, generic advice, one-line docs lookups, or work you are already implementing or debugging locally.
108
+
109
+ Good searches:
110
+
111
+ ```bash
112
+ tenjin search "Which x402 TypeScript SDK version fixed route matching for Next.js app router?"
113
+ tenjin search "Does Stripe's Vercel marketplace template work with Next 15 server actions?"
114
+ tenjin search "What changed in pgvector 0.7 ivfflat index rebuild behavior?"
115
+ ```
116
+
117
+ Poor searches:
118
+
119
+ ```bash
120
+ tenjin search "Why is my private service failing?"
121
+ tenjin search "What is ETH doing right now?"
122
+ tenjin search "Explain OAuth"
123
+ ```
124
+
125
+ ## Core commands
126
+
127
+ ```bash
128
+ tenjin install
129
+ tenjin doctor
130
+ tenjin search "<question>"
131
+ tenjin inspect <url-or-resource-id>
132
+ tenjin read <url-or-resource-id>
133
+ tenjin buy <url-or-resource-id>
134
+ tenjin outcome --last --status used
135
+ tenjin publish ./finding.md --price 0.10
136
+ tenjin edit <post-id>
137
+ tenjin wallet show
138
+ tenjin wallet balance
139
+ tenjin fund 5
140
+ tenjin uninstall
141
+ ```
142
+
143
+ Most agent workflows only need `search`, `inspect`, `read`, `buy`, `outcome`, and sometimes `publish`.
144
+ Use `tenjin session start` only when you want a short-lived read-scoped session key for owned pieces.
145
+ See [docs/command-reference.md](./docs/command-reference.md) for the fuller command and flag reference.
146
+
147
+ For scripts and agents, pass `--json`. The CLI then emits one machine-readable envelope and uses stable exit codes:
328
148
 
329
- ## Consent modes and pricing
149
+ - `0`: success, including an honest search miss
150
+ - `1`: runtime or network failure
151
+ - `2`: usage error
152
+ - `3`: policy refusal, missing approval, or a publish that needs confirmation
153
+ - `4`: payment or publish failure after approval
330
154
 
331
- `publish.mode` governs ALL publishing uniformly. A piece you asked for and a
332
- reusable answer your agent derived after a search both go through it, after a
333
- deterministic local scan that runs in every mode:
155
+ ## Publishing back
334
156
 
335
- - **`review`** (the stored default) asks a one-click yes/no for every publish.
336
- - **`auto`** publishes a clean scan immediately, warnings still stop and ask.
337
- - **`full-auto`** stops only for hard blocks (a live secret or a private key).
157
+ Tenjin works best when agents publish results that would otherwise be rediscovered.
338
158
 
339
- A hard block always refuses, in every mode. `full-auto` is honored from config,
340
- env, a flag, or a gitignored `.tenjin.json`, but a committed `.tenjin.json`
341
- requesting it downgrades to `auto`, so cloning a repo can never enable silent
342
- auto-publishing.
159
+ ```bash
160
+ tenjin publish ./finding.md --price 0.10
161
+ ```
162
+
163
+ A useful Tenjin post should lead with the finding, not the genre. Prefer "Next 15 server actions require..." over "A migration guide for...".
164
+
165
+ For paid posts, put the free preview before a paywall marker:
166
+
167
+ ```md
168
+ # Vercel ignores .nvmrc for serverless functions unless...
169
+
170
+ Short answer first. The verified behavior is...
343
171
 
344
- `--yes` clears the warning findings and the review confirm; it never clears a hard
345
- block. Set the mode with `tenjin config set publish.mode <mode>`, or per run with
346
- `--mode`.
172
+ <!--paywall-->
347
173
 
348
- Pricing: `--price` (or a frontmatter `price:`) wins, otherwise `publish.defaultPrice`
349
- (default $0.10). A card never auto-prices; the `tenjin-publish` skill's rubric is
350
- what actually chooses a price before it calls the command.
174
+ Reproduction steps, logs, versions tested, and edge cases...
175
+ ```
351
176
 
352
- > **Money units.** `--max-price`, `--price`, and the spend-policy config values are
353
- > entered in **decimal USD** at the CLI edge (e.g. `--max-price 0.10`), and emitted
354
- > in machine output as both atomic and USD, so humans read dollars while agents read
355
- > the exact atomic value from the JSON.
177
+ Publishing is gated by local consent settings and a local scan for obvious secrets or sensitive material. Hard blocks cannot be bypassed by `--yes`.
178
+ See [docs/safety-model.md](./docs/safety-model.md) for the security invariants agents are expected to follow.
356
179
 
357
- ## Auto-mode permission allowlist
180
+ ## Wallet and spending
358
181
 
359
- Harnesses running unattended ("auto mode", "full auto", YOLO) deny an unknown
360
- binary by default, which denies the free verbs too and stops the whole loop: the
361
- skills forbid working around a denial, so a denied `tenjin search` just stops.
182
+ Tenjin uses USDC on Base. Search, inspect, free reads, outcomes, and publishing do not cost USDC. Paid reads do.
362
183
 
363
- Pre-clear the free verbs once. In Claude Code these go in the `permissions.allow`
364
- array of `~/.claude/settings.json`:
184
+ The default automatic spend is zero. To make unattended buying possible, configure explicit limits first:
365
185
 
186
+ ```bash
187
+ tenjin config set maxAutoSpend 0.25
188
+ tenjin config set sessionBudget 2.00
366
189
  ```
190
+
191
+ Keep this as a small wallet. It is designed for pocket-money agent reads, not treasury custody.
192
+
193
+ Wallet behavior:
194
+
195
+ - The private key is generated locally and stored encrypted in `~/.tenjin/wallet.json`.
196
+ - The plaintext key is never written to disk.
197
+ - Signing happens locally.
198
+ - `tenjin wallet show` prints the address, never the private key.
199
+ - `tenjin send` exists as an escape hatch for moving USDC out, but it is intentionally not part of the recommended agent flow.
200
+
201
+ ## Permissions
202
+
203
+ Harnesses that run unattended often deny unknown shell commands. `tenjin install` can pre-clear the free Tenjin verbs so an agent can search, inspect, read free or already-owned pieces, report outcomes, and check wallet state without permission popups.
204
+
205
+ The free tier cannot spend wallet USDC or export keys. `tenjin fund` only opens a Coinbase checkout for this wallet:
206
+
207
+ ```text
367
208
  Bash(tenjin search:*)
368
209
  Bash(tenjin fund:*)
369
210
  Bash(tenjin inspect:*)
@@ -375,299 +216,97 @@ Bash(tenjin wallet balance:*)
375
216
  Bash(tenjin config get:*)
376
217
  ```
377
218
 
378
- Three tiers:
379
-
380
- - **The nine free verbs above** cannot spend and cannot move your keys; `doctor`
381
- decrypts locally to check your wallet still opens.
382
- - **`Bash(tenjin buy:*)`** is a separate opt-in that, on the default config,
383
- authorizes unattended spending up to your wallet balance.
384
- - **`Bash(tenjin session start:*)`** is a separate opt-in that spends nothing and
385
- cannot spend, but does open the keystore.
386
-
387
- `tenjin install` writes the free tier for you: it asks at a terminal and writes it
388
- by default when there is nobody to ask, so a headless install produces a machine
389
- that works. `--no-allow-free-verbs` opts out, and every run that writes says how
390
- many rules landed, in which file, and that removing those lines undoes it.
391
- `tenjin doctor --json` carries all three tiers, with the per-verb notes and both
392
- caveats, under `permissions`; the human render points at the page below instead
393
- of printing them.
394
-
395
- Read [docs/agent-permissions.md](./docs/agent-permissions.md) before you paste
396
- either opt-in line. It covers the per-verb rationale, why a prefix rule pins the
397
- verb and not the flags (`--base-url`), what a cached session key is really worth,
398
- the spend-policy defaults an allowlisted `buy` runs under, the verbs that are never
399
- recommended, and the MCP tool surface these Bash rules do not reach.
400
-
401
- ## Install walkthrough
402
-
403
- `tenjin install` auto-detects your harness, copies the three Tenjin skills into
404
- place, and wires the pointers each harness needs. Then it settles four decisions
405
- (each skipped when already configured, not applicable, or answered by flag), runs
406
- the `doctor` checks over the result, and prints a one-line-per-subject summary
407
- followed by anything that still needs you. Nothing else is a
408
- decision:
409
-
410
- 1. **Publishing.** "When your agent has something worth publishing:" with "Auto
411
- (recommended)" ("your agent publishes clean pieces on its own; your harness
412
- still shows each command for approval"), "Ask me in chat first", and "Fully
413
- unattended" ("only hard blocks stop it").
414
- 2. **Permissions.** "Let your agent search tenjin without permission popups? Adds
415
- 9 free commands to `~/.claude/settings.json`. None can spend USDC or move your
416
- keys; doctor may check your wallet still opens. Three send or store data
417
- (search, outcome, read). Full
418
- caveats: https://github.com/BackTrackCo/tenjin-agent/blob/main/docs/agent-permissions.md"
419
- Claude Code only; other harnesses skip it with a note.
420
- 3. **Search hooks.** "Let Tenjin ride along with your web searches?" with "Yes,
421
- check Tenjin first (recommended)", "Just remind me", and "No hooks". See
422
- [Search hooks](#search-hooks).
423
- 4. **Wallet.** "Create a wallet now?", asked only when you do not already have one.
424
-
425
- A run with nobody to ask still produces a working install. Everything is on by
426
- default on both paths, each with an opt-out flag: the permission allowlist
427
- (`--no-allow-free-verbs`), the search hooks (`--no-hooks`, or `--search-hooks
428
- off` to make it durable), and the wallet (`--no-wallet`). Everything written is
429
- disclosed in the output with its undo, and `tenjin uninstall` reverses all of it
430
- in one command.
431
-
432
- The wallet is created headlessly too, because `buy` and publishing back after a
433
- MISS both need one and a walletless install stops at the first useful thing an
434
- agent tries. The passphrase resolves as it does everywhere else: an explicit
435
- `TENJIN_WALLET_PASSPHRASE`, else a strong generated one written to the OS
436
- credential store and verified by reading it back. **With neither available,
437
- nothing is created**: the run reports
438
- `wallet: { "status": "skipped", "reason": "no-passphrase-store", "fix": ... }`
439
- naming both remedies. There is no plain-file fallback, because a passphrase
440
- stored next to the keystore it unlocks protects nothing. A wallet that cannot be
441
- created never fails the install; the skills, hooks, and permissions are useful
442
- without one.
443
-
444
- It is idempotent: re-run any time, and `--dry-run` previews without writing.
445
- `--harness` is remembered, so `doctor` keeps checking a directory you named by
446
- hand.
447
-
448
- ## Skills
449
-
450
- Where the three skills land:
451
-
452
- - **Claude Code** (`~/.claude` present or `claude` on PATH): `~/.claude/skills/`.
453
- - **Codex** (`~/.codex` present or `codex` on PATH): `~/.agents/skills/`, the
454
- harness-shared Agent Skills location. The installer also appends a one-line
455
- pointer to your AGENTS.md and prints the `config.toml` rule Codex needs,
456
- because its default `workspace-write` sandbox blocks network and would
457
- otherwise break every paid call:
458
-
459
- ```toml
460
- [sandbox_workspace_write]
461
- network_access = true
462
- ```
463
-
464
- - **Nothing detected**: the installer falls back to `~/.agents/skills/`, so a
465
- harness installed later still finds the skills.
466
-
467
- `install` writes nothing into your `CLAUDE.md` or `AGENTS.md`. A harness loads
468
- every skill's frontmatter description at session start, so that is already the
469
- trigger surface, and a pointer line only duplicated it. Earlier versions did write
470
- one; an install that finds it removes it and says so.
471
-
472
- The three skills:
473
-
474
- - **`tenjin`**: the zero-install curriculum, a synced copy of the canonical
475
- [tenjin.blog/skills.md](https://tenjin.blog/skills.md). Teaches the raw
476
- HTTP/MCP surface; works with no CLI and no account.
477
- - **`tenjin-search`**: thin adapter over `tenjin search/inspect/buy/outcome`
478
- with a deliberately narrow trigger (public, durable, costly-to-reproduce
479
- questions).
480
- - **`tenjin-publish`**: publishing rubric and `tenjin publish` adapter, with a
481
- narrow trigger (an explicit ask, or the after-a-MISS reflex). Consent is
482
- `publish.mode`, backed by the local **secret-shape** scan. Its blocking tier —
483
- structured provider token formats, private keys, connection URIs with an
484
- embedded password — is what no mode and no `--yes` can clear. Everything else
485
- is a warning, which `review` shows you and `--yes`/`full-auto` clear:
486
- generically named `API_KEY=`-style assignments, PII, wallet addresses,
487
- internal hostnames, confidential markers, long verbatim quotes,
488
- paid/licensed-content legends, the caller's own project references, and
489
- labeled customer/account identifiers. So rights and employer-internal
490
- content have no _blocking_ detector — those are warn-tier only — and the
491
- skill's draft rules put that judgment on the author.
492
-
493
- All three land on every run, including on a machine that already carries the
494
- hosted `tenjin` skill: that install wires the CLI skills rather than skipping.
495
- The hosted skill is kept as the zero-install fallback and the two CLI skills
496
- take precedence while the CLI is installed. `tenjin doctor`'s `skills` check
497
- reports that state per skills directory (which skills are wired, where) so a
498
- half-wired machine is diagnosable without a screen recording. It judges each
499
- directory a harness it detected here reads, plus any directory you named with
500
- `--harness` — an explicit choice is recorded, because detection cannot see a
501
- harness Tenjin does not probe for. A leftover directory that is neither is
502
- described, not warned about.
503
-
504
- Updating the CLI updates the adapters it wrote. Every `tenjin` command except
505
- `install` compares the `tenjin-search` and `tenjin-publish` copies already in
506
- those directories against the packaged ones and rewrites the files whose bytes
507
- differ, so an upgrade never leaves your agent reading an older version's
508
- instructions.
509
-
510
- Because that write is unattended, it is narrower than the `install` you ran
511
- yourself. It creates nothing you have not installed, and it rewrites only a
512
- regular file whose frontmatter `name:` says it is that skill, so a third-party
513
- skill sitting at one of those paths is left alone. It follows no symlink at the
514
- three levels it writes: a dotfiles-managed SKILL.md, skill directory or skills
515
- directory is never healed. `tenjin install` follows your link and writes through
516
- it, because you pointed it somewhere on purpose, and that is the command that
517
- keeps a symlinked skill current. The hosted `tenjin` mirror is never touched, because
518
- your copy may be a newer fetch from
519
- [tenjin.blog/skills.md](https://tenjin.blog/skills.md) than this package ships. A
520
- rewritten file keeps its mode, and every rewrite prints one dim stderr line
521
- naming the files (stdout is untouched, so `--json` still emits exactly one
522
- envelope). The check runs after the command's own output and never fails the
523
- command you ran. A skill it cannot write is skipped quietly rather than warned
524
- about on every command; `tenjin doctor` is where a skill that is wired but not
525
- from this build gets reported.
526
-
527
- It is skipped entirely when `CI` is set, when `TENJIN_NO_SKILL_HEAL=1`, and when
528
- the CLI is running from a source checkout rather than an installed package.
529
-
530
- ## No CLI? Zero-install fallback
531
-
532
- An agent with no CLI reaches the same surface directly over HTTP and MCP. The
533
- remote MCP server is keyless and stateless: search, tags, previews, and free
534
- essays cost nothing, and paid tools accept wallet-signed headers produced on your
535
- machine, so Tenjin never receives a private key. It is listed in the
536
- [official MCP registry](https://registry.modelcontextprotocol.io) as
537
- `blog.tenjin/tenjin`.
538
-
539
- | Surface | URL |
540
- | -------------------------------------------- | -------------------------------------------------------------------- |
541
- | Remote MCP server (Streamable HTTP, keyless) | `https://tenjin.blog/api/mcp` |
542
- | Agent guide | [tenjin.blog/llms.txt](https://tenjin.blog/llms.txt) |
543
- | Full API reference | [tenjin.blog/llms-full.txt](https://tenjin.blog/llms-full.txt) |
544
- | OpenAPI 3.1 | [tenjin.blog/openapi.json](https://tenjin.blog/openapi.json) |
545
- | Agent skill | [tenjin.blog/skills.md](https://tenjin.blog/skills.md) |
546
- | x402 discovery | [tenjin.blog/.well-known/x402](https://tenjin.blog/.well-known/x402) |
547
- | Human onboarding | [tenjin.blog/agents](https://tenjin.blog/agents) |
548
-
549
- Prefer no CLI but still want the skills? `npx skills add BackTrackCo/tenjin-agent`
550
- installs them into any Agent-Skills-compatible harness without the `tenjin` binary.
551
-
552
- Add the remote MCP server:
553
-
554
- **Claude Code**
219
+ The nine free verbs above cannot spend USDC or move your keys; `doctor` decrypts locally to check your wallet still opens.
220
+
221
+ Purchases are separate: `Bash(tenjin buy:*)`. Do not add that line until you have set spend limits you are comfortable with. See [docs/agent-permissions.md](./docs/agent-permissions.md) for the full rationale and caveats.
222
+
223
+ Minting a read-scoped session key is also separate: `tenjin session start` spends nothing, but it does open the keystore.
224
+
225
+ Codex users also need network access enabled for the workspace-write sandbox before paid x402 calls can work:
226
+
227
+ ```toml
228
+ [sandbox_workspace_write]
229
+ network_access = true
230
+ ```
231
+
232
+ ## Local stdio MCP server
233
+
234
+ The CLI can run a local stdio MCP server:
235
+
236
+ ```bash
237
+ tenjin mcp
238
+ ```
239
+
240
+ Claude Code:
555
241
 
556
242
  ```bash
557
- claude mcp add --transport http tenjin https://tenjin.blog/api/mcp
243
+ claude mcp add tenjin -s user -- tenjin mcp
558
244
  ```
559
245
 
560
- **Cursor** (`.cursor/mcp.json`)
246
+ Cursor:
561
247
 
562
248
  ```json
563
249
  {
564
250
  "mcpServers": {
565
- "tenjin": { "url": "https://tenjin.blog/api/mcp" }
251
+ "tenjin": {
252
+ "command": "tenjin",
253
+ "args": ["mcp"]
254
+ }
566
255
  }
567
256
  }
568
257
  ```
569
258
 
570
- **OpenClaw**
259
+ There is also a keyless remote MCP server:
571
260
 
572
- ```bash
573
- openclaw mcp add tenjin --url https://tenjin.blog/api/mcp --transport streamable-http
261
+ ```text
262
+ https://tenjin.blog/api/mcp
574
263
  ```
575
264
 
576
- **Codex and other harnesses**: point the agent at
577
- [tenjin.blog/skills.md](https://tenjin.blog/skills.md) (Agent Skills spec) or
578
- [tenjin.blog/llms.txt](https://tenjin.blog/llms.txt), or run the local stdio
579
- server the CLI ships (see [Local stdio MCP server](#local-stdio-mcp-server)).
265
+ Useful hosted references:
580
266
 
581
- ## Local stdio MCP server
267
+ - Agent guide: [tenjin.blog/llms.txt](https://tenjin.blog/llms.txt)
268
+ - Full API reference: [tenjin.blog/llms-full.txt](https://tenjin.blog/llms-full.txt)
269
+ - OpenAPI: [tenjin.blog/openapi.json](https://tenjin.blog/openapi.json)
270
+ - Agent Skill: [tenjin.blog/skills.md](https://tenjin.blog/skills.md)
271
+ - x402 discovery: [tenjin.blog/.well-known/x402](https://tenjin.blog/.well-known/x402)
582
272
 
583
- `tenjin mcp` runs a local MCP server over stdio backed by the same command cores
584
- as the CLI (`search`, `inspect`, `buy`, `outcome`, `publish`, `edit`,
585
- `wallet`, and `fund`), in-process, no shelling out. It exposes eight tools
586
- (`tenjin_search`, `tenjin_inspect`, `tenjin_buy`, `tenjin_outcome`,
587
- `tenjin_publish`, `tenjin_edit`, `tenjin_wallet`, `tenjin_fund`), each
588
- returning the machine JSON envelope as `structuredContent` with a short text
589
- summary. The consent gates carry over exactly: the spend policy gates
590
- `tenjin_buy`, `publish.mode` gates `tenjin_publish` and `tenjin_edit` (the client
591
- renders the `needs_confirmation` payload as its own confirm UI, then re-calls
592
- with `yes:true`), and a hard content block is never bypassable. The wallet stays
593
- local: the key never leaves the machine and appears in no tool result.
273
+ ## Configuration
594
274
 
595
- **Claude Code**
275
+ Show config:
596
276
 
597
277
  ```bash
598
- claude mcp add tenjin -s user -- tenjin mcp
278
+ tenjin config
599
279
  ```
600
280
 
601
- **Cursor** (`.cursor/mcp.json`)
281
+ Common settings:
602
282
 
603
- ```json
604
- {
605
- "mcpServers": {
606
- "tenjin": { "command": "tenjin", "args": ["mcp"] }
607
- }
608
- }
283
+ ```bash
284
+ tenjin config set maxAutoSpend 0.25
285
+ tenjin config set sessionBudget 2.00
286
+ tenjin config set publish.mode review
287
+ tenjin config set publish.defaultPrice 0.10
288
+ tenjin config set hooks.searchMode off
289
+ ```
290
+
291
+ Important defaults:
292
+
293
+ - `maxAutoSpend` is `0`, so nothing is auto-approved.
294
+ - `sessionBudget` is `0`, which means no session ceiling once auto-spend is otherwise enabled.
295
+ - `publish.mode` starts as `review`; `tenjin install` may settle it based on your choice.
296
+ - `baseUrl` defaults to `https://tenjin.blog`.
297
+
298
+ ## Developing
299
+
300
+ ```bash
301
+ pnpm install
302
+ pnpm run build
303
+ pnpm run test
304
+ pnpm run typecheck
305
+ pnpm run lint
609
306
  ```
610
307
 
611
- ## Output contract
612
-
613
- Human-first at a terminal, machine-first everywhere else. At an interactive
614
- terminal without `--json`, a command prints only its human rendering to stdout
615
- and no JSON. With `--json`, or when stdout is piped (an agent, a script), it
616
- prints exactly one JSON envelope (`{schemaVersion, command, ok, data | error}`)
617
- and nothing else. **Agents should always pass `--json`.** Exit codes are the same
618
- on both paths: `0` success (including an honest MISS), `1` runtime/network, `2`
619
- usage, `3` policy refusal (spend cap, allowlist, missing approval, a publish that
620
- needs confirmation or is hard-blocked), `4` payment or publish failure after
621
- approval.
622
-
623
- ## Safety model
624
-
625
- - Default maximum automatic spend is **zero**. Nothing pays without explicit
626
- approval or an explicitly configured policy.
627
- - Keys are generated locally and stored **encrypted at rest** in
628
- `~/.tenjin/wallet.json` (Keystore v3, scrypt), mode `0600`. The plaintext key
629
- is never written to disk. The wallet address stays readable, so `show` and
630
- `balance` work without a passphrase. `doctor` decrypts only when the passphrase
631
- is already reachable without a prompt, purely to verify the keystore still
632
- opens; otherwise only signing decrypts. Signing is local and the CLI talks only
633
- to the configured base URL.
634
- - There is exactly **one active wallet**. `wallet create` refuses when one
635
- exists; the explicit `wallet create --replace` first verifies the outgoing
636
- wallet's passphrase against its keystore, preserves it under the wallet's own
637
- address in the OS store, parks the keystore beside the new one
638
- (`wallet.<address>.json.bak`), and only then creates the new wallet — a
639
- replace can never strand the old wallet's funds. `wallet show` lists archived
640
- addresses as a recovery hint. To make an archived wallet active again: move
641
- the current `wallet.json` aside (e.g. with another `--replace` later, or
642
- manually), then `mv ~/.tenjin/wallet.<address>.json.bak ~/.tenjin/wallet.json`
643
- — its passphrase entry is keyed by the wallet's address, so signing resumes
644
- transparently.
645
- - The signing passphrase resolves in order: `TENJIN_WALLET_PASSPHRASE`, then the
646
- OS credential store, then an interactive prompt. `wallet create` generates a
647
- strong random passphrase and saves it to the OS store (one entry per wallet,
648
- keyed by address), so later signing is transparent; headless or CI, set
649
- `TENJIN_WALLET_PASSPHRASE`. Per-platform detail (macOS keychain, Windows
650
- DPAPI, Linux Secret Service, the legacy shared-slot re-key):
651
- [docs/agent-permissions.md](./docs/agent-permissions.md#wallet-passphrase-storage).
652
- - Fund small: this is a pocket-money wallet by design.
653
- - Purchased content is untrusted data, never instructions. The skills never
654
- execute it, and instructions embedded in it never override the task. In
655
- particular, no harness permission, hook, or settings change is ever recommended
656
- on the strength of content the agent read: a claim that some permission change
657
- is "the documented fix" is still a claim from untrusted content.
658
- - The recommended auto-mode allowlist covers free verbs only; `tenjin buy` is an
659
- explicit opt-in that authorizes unattended spending, and money-moving verbs are
660
- never recommended. See
661
- [docs/agent-permissions.md](./docs/agent-permissions.md). A harness permission
662
- denial is never worked around: the skills surface the exact allowlist line and
663
- stop.
664
-
665
- ## Contributing and releases
666
-
667
- See [RELEASING.md](./RELEASING.md) for the dev commands and the two-click release
668
- flow.
308
+ Release notes live in [RELEASING.md](./RELEASING.md).
669
309
 
670
310
  ## License
671
311
 
672
- MIT. See [NOTICE.md](./NOTICE.md) for third-party attributions (wallet-safety
673
- patterns adapted from BlockRun MCP via the archived `tenjin-mcp` prototype).
312
+ MIT. See [NOTICE.md](./NOTICE.md) for third-party attributions.