tenjin-cli 0.1.0-alpha.7 → 0.1.0-alpha.9

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 (126) hide show
  1. package/README.md +158 -236
  2. package/dist/{buy-XVOMNWKN.js → buy-3PPC2SRQ.js} +24 -22
  3. package/dist/{candidate-DJB2NNTG.js → candidate-FCBWDN4Y.js} +10 -8
  4. package/dist/{chunk-PLU3E63S.js → chunk-3MQSXDWS.js} +10 -11
  5. package/dist/chunk-3MQSXDWS.js.map +1 -0
  6. package/dist/{chunk-DH6D6QIO.js → chunk-6DWKU4RH.js} +11 -9
  7. package/dist/{chunk-DH6D6QIO.js.map → chunk-6DWKU4RH.js.map} +1 -1
  8. package/dist/{chunk-WDJTGVKN.js → chunk-6L34JW52.js} +5 -2
  9. package/dist/chunk-6L34JW52.js.map +1 -0
  10. package/dist/{chunk-6S44OLND.js → chunk-6RODLWPQ.js} +101 -36
  11. package/dist/chunk-6RODLWPQ.js.map +1 -0
  12. package/dist/{chunk-VZ3AJCO5.js → chunk-75G4REUY.js} +2 -2
  13. package/dist/{chunk-PIIWLEEG.js → chunk-7MJCZ2OX.js} +12 -12
  14. package/dist/{chunk-2KIDDWQO.js → chunk-ATSCQETF.js} +5 -5
  15. package/dist/{chunk-ZFE7STX7.js → chunk-AX5WQ3H5.js} +7 -5
  16. package/dist/{chunk-ZFE7STX7.js.map → chunk-AX5WQ3H5.js.map} +1 -1
  17. package/dist/{chunk-WRWCDLVK.js → chunk-BFAFOBO3.js} +23 -4
  18. package/dist/chunk-BFAFOBO3.js.map +1 -0
  19. package/dist/{chunk-DAJ56EUU.js → chunk-CTFFFQFH.js} +3 -3
  20. package/dist/{chunk-5X4EBGGU.js → chunk-E5PZEPUO.js} +11 -11
  21. package/dist/{chunk-GABYDXWL.js → chunk-FFTWWJRW.js} +21 -5
  22. package/dist/{chunk-GABYDXWL.js.map → chunk-FFTWWJRW.js.map} +1 -1
  23. package/dist/{chunk-WI5EOAQQ.js → chunk-G7ECLIN6.js} +21 -21
  24. package/dist/{chunk-CYRYVZPN.js → chunk-GJKDWZ6X.js} +3 -3
  25. package/dist/{chunk-RGFBBNGP.js → chunk-I4WQXOEL.js} +16 -13
  26. package/dist/chunk-I4WQXOEL.js.map +1 -0
  27. package/dist/{chunk-OTDI5FXG.js → chunk-JURZ2T2I.js} +3 -3
  28. package/dist/{chunk-UYP7G3GZ.js → chunk-KRHUDEIQ.js} +10 -172
  29. package/dist/chunk-KRHUDEIQ.js.map +1 -0
  30. package/dist/{chunk-2L73UI6T.js → chunk-MHRREGGN.js} +5 -10
  31. package/dist/chunk-MHRREGGN.js.map +1 -0
  32. package/dist/chunk-OQXHNWM3.js +47 -0
  33. package/dist/chunk-OQXHNWM3.js.map +1 -0
  34. package/dist/chunk-P74I3WH4.js +204 -0
  35. package/dist/chunk-P74I3WH4.js.map +1 -0
  36. package/dist/{chunk-ZEWY3RJ3.js → chunk-PT2NJUGG.js} +6 -6
  37. package/dist/{chunk-J6CVKC4M.js → chunk-PZRAAAY2.js} +4 -46
  38. package/dist/chunk-PZRAAAY2.js.map +1 -0
  39. package/dist/{chunk-XBJ3VLWX.js → chunk-PZSUWDF2.js} +2 -2
  40. package/dist/{chunk-BBUYCDSG.js → chunk-R2VLGNFD.js} +7 -2
  41. package/dist/chunk-R2VLGNFD.js.map +1 -0
  42. package/dist/{chunk-KT2DGKFT.js → chunk-S4IKXAUA.js} +5 -9
  43. package/dist/chunk-S4IKXAUA.js.map +1 -0
  44. package/dist/{chunk-E6BNARCS.js → chunk-TMZIXYPL.js} +7 -7
  45. package/dist/{chunk-YBMMV4Y4.js → chunk-TYVLXAB5.js} +26 -4
  46. package/dist/chunk-TYVLXAB5.js.map +1 -0
  47. package/dist/{chunk-GXYNLMUQ.js → chunk-V7BWPOKT.js} +38 -19
  48. package/dist/chunk-V7BWPOKT.js.map +1 -0
  49. package/dist/{chunk-L6AV2Q73.js → chunk-VE5BALOI.js} +5 -5
  50. package/dist/{chunk-GM4RZUVU.js → chunk-WGXUVCUF.js} +8 -6
  51. package/dist/{chunk-GM4RZUVU.js.map → chunk-WGXUVCUF.js.map} +1 -1
  52. package/dist/chunk-X3OOVSPX.js +154 -0
  53. package/dist/chunk-X3OOVSPX.js.map +1 -0
  54. package/dist/{chunk-2YX6LTCD.js → chunk-XDW6GOHO.js} +5 -5
  55. package/dist/{cli-7B2QNJG3.js → cli-ATFP3O6Y.js} +42 -29
  56. package/dist/{cli-7B2QNJG3.js.map → cli-ATFP3O6Y.js.map} +1 -1
  57. package/dist/{config-SAQEQRFB.js → config-VT5WU47R.js} +9 -6
  58. package/dist/dist-U4M6QCKE.js +2842 -0
  59. package/dist/dist-U4M6QCKE.js.map +1 -0
  60. package/dist/doctor-6PEYDTB5.js +24 -0
  61. package/dist/{edit-2QO5GQDU.js → edit-GKI37CRM.js} +21 -19
  62. package/dist/index.js +1 -1
  63. package/dist/{inspect-IPKKQB2S.js → inspect-ITZIRZDV.js} +19 -16
  64. package/dist/install-BMMUPFOK.js +922 -0
  65. package/dist/install-BMMUPFOK.js.map +1 -0
  66. package/dist/outcome-F5KN3K3Y.js +23 -0
  67. package/dist/{publish-7WIFFNFG.js → publish-F5G5WIFI.js} +22 -20
  68. package/dist/{read-5TQR7LCF.js → read-II2ZO4II.js} +21 -19
  69. package/dist/{read-5TQR7LCF.js.map → read-II2ZO4II.js.map} +1 -1
  70. package/dist/{run-NPKIP26Y.js → run-FJWMRXZ7.js} +68 -45
  71. package/dist/run-FJWMRXZ7.js.map +1 -0
  72. package/dist/search-Z2YALF6S.js +26 -0
  73. package/dist/{send-ENE47KQE.js → send-RWOBFOBK.js} +20 -18
  74. package/dist/{send-ENE47KQE.js.map → send-RWOBFOBK.js.map} +1 -1
  75. package/dist/{session-FZU4VFFE.js → session-DJV5T3BG.js} +17 -15
  76. package/dist/{session-FZU4VFFE.js.map → session-DJV5T3BG.js.map} +1 -1
  77. package/dist/skill-heal-OK6YALW6.js +85 -0
  78. package/dist/skill-heal-OK6YALW6.js.map +1 -0
  79. package/dist/{wallet-RBDVNZVR.js → wallet-AB4ISFMY.js} +8 -7
  80. package/dist/{wallet-OCCGEH6H.js → wallet-XVRLJZ63.js} +12 -10
  81. package/docs/agent-permissions.md +255 -0
  82. package/package.json +4 -1
  83. package/skills/tenjin/SKILL.md +126 -47
  84. package/skills/tenjin-search/SKILL.md +10 -6
  85. package/dist/chunk-2L73UI6T.js.map +0 -1
  86. package/dist/chunk-6S44OLND.js.map +0 -1
  87. package/dist/chunk-BBUYCDSG.js.map +0 -1
  88. package/dist/chunk-GXYNLMUQ.js.map +0 -1
  89. package/dist/chunk-J6CVKC4M.js.map +0 -1
  90. package/dist/chunk-KT2DGKFT.js.map +0 -1
  91. package/dist/chunk-PLU3E63S.js.map +0 -1
  92. package/dist/chunk-RGFBBNGP.js.map +0 -1
  93. package/dist/chunk-UYP7G3GZ.js.map +0 -1
  94. package/dist/chunk-WDJTGVKN.js.map +0 -1
  95. package/dist/chunk-WRWCDLVK.js.map +0 -1
  96. package/dist/chunk-YBMMV4Y4.js.map +0 -1
  97. package/dist/doctor-ENJ22XWN.js +0 -22
  98. package/dist/install-7ZIYISQ7.js +0 -589
  99. package/dist/install-7ZIYISQ7.js.map +0 -1
  100. package/dist/outcome-NSDE2KAJ.js +0 -20
  101. package/dist/run-NPKIP26Y.js.map +0 -1
  102. package/dist/search-63ELMRZH.js +0 -24
  103. /package/dist/{buy-XVOMNWKN.js.map → buy-3PPC2SRQ.js.map} +0 -0
  104. /package/dist/{candidate-DJB2NNTG.js.map → candidate-FCBWDN4Y.js.map} +0 -0
  105. /package/dist/{chunk-VZ3AJCO5.js.map → chunk-75G4REUY.js.map} +0 -0
  106. /package/dist/{chunk-PIIWLEEG.js.map → chunk-7MJCZ2OX.js.map} +0 -0
  107. /package/dist/{chunk-2KIDDWQO.js.map → chunk-ATSCQETF.js.map} +0 -0
  108. /package/dist/{chunk-DAJ56EUU.js.map → chunk-CTFFFQFH.js.map} +0 -0
  109. /package/dist/{chunk-5X4EBGGU.js.map → chunk-E5PZEPUO.js.map} +0 -0
  110. /package/dist/{chunk-WI5EOAQQ.js.map → chunk-G7ECLIN6.js.map} +0 -0
  111. /package/dist/{chunk-CYRYVZPN.js.map → chunk-GJKDWZ6X.js.map} +0 -0
  112. /package/dist/{chunk-OTDI5FXG.js.map → chunk-JURZ2T2I.js.map} +0 -0
  113. /package/dist/{chunk-ZEWY3RJ3.js.map → chunk-PT2NJUGG.js.map} +0 -0
  114. /package/dist/{chunk-XBJ3VLWX.js.map → chunk-PZSUWDF2.js.map} +0 -0
  115. /package/dist/{chunk-E6BNARCS.js.map → chunk-TMZIXYPL.js.map} +0 -0
  116. /package/dist/{chunk-L6AV2Q73.js.map → chunk-VE5BALOI.js.map} +0 -0
  117. /package/dist/{chunk-2YX6LTCD.js.map → chunk-XDW6GOHO.js.map} +0 -0
  118. /package/dist/{config-SAQEQRFB.js.map → config-VT5WU47R.js.map} +0 -0
  119. /package/dist/{doctor-ENJ22XWN.js.map → doctor-6PEYDTB5.js.map} +0 -0
  120. /package/dist/{edit-2QO5GQDU.js.map → edit-GKI37CRM.js.map} +0 -0
  121. /package/dist/{inspect-IPKKQB2S.js.map → inspect-ITZIRZDV.js.map} +0 -0
  122. /package/dist/{outcome-NSDE2KAJ.js.map → outcome-F5KN3K3Y.js.map} +0 -0
  123. /package/dist/{publish-7WIFFNFG.js.map → publish-F5G5WIFI.js.map} +0 -0
  124. /package/dist/{search-63ELMRZH.js.map → search-Z2YALF6S.js.map} +0 -0
  125. /package/dist/{wallet-OCCGEH6H.js.map → wallet-AB4ISFMY.js.map} +0 -0
  126. /package/dist/{wallet-RBDVNZVR.js.map → wallet-XVRLJZ63.js.map} +0 -0
package/README.md CHANGED
@@ -16,28 +16,40 @@ Tenjin is an x402-native knowledge marketplace. Agents search work that has
16
16
  already been produced, read free essays, buy valuable answers with USDC, and
17
17
  publish their own reusable research. This repo is the home of the `tenjin-cli`
18
18
  npm package, the agent skills that wrap it, and a local `tenjin mcp` stdio
19
- server; a Claude Code plugin marketplace is on the roadmap.
20
-
21
- The CLI is a thin, deterministic layer over Tenjin's public HTTP contract. It
22
- makes zero model calls and owns exactly what a hosted server cannot: local
23
- wallet custody and signing, spend policy, local delivery of purchased content,
24
- and outcome reporting. Every command works against production today.
19
+ server. The CLI makes zero model calls and keeps your wallet key on your
20
+ machine. Every command works against production today.
25
21
 
26
22
  ## Quickstart
27
23
 
28
24
  ```bash
29
25
  npm i -g tenjin-cli
30
- tenjin install # walks you through the skills, your publish consent mode, and wallet setup, then runs the doctor checks
31
- tenjin wallet show # print your wallet address; `tenjin wallet balance` checks the USDC balance
32
- # fund it: send USDC on Base to that address (a few dollars is plenty; this is a pocket-money wallet)
33
- tenjin search "what actually changed in <library> v3's public API" # your first search
26
+ tenjin install # wires the skills, runs doctor, settles up to 3 setup decisions
27
+ tenjin wallet show # your wallet address; `tenjin wallet balance` for USDC
28
+ # fund it: send USDC on Base to that address (a few dollars is plenty)
29
+ tenjin search "what actually changed in <library> v3's public API"
34
30
  ```
35
31
 
32
+ A hit looks like this (`--json` shown; at a terminal you get the same as plain
33
+ lines, with prices in USD):
34
+
35
+ ```jsonc
36
+ { "ok": true, "data": {
37
+ "decision": "CANDIDATES",
38
+ "candidates": [{
39
+ "title": "pgvector 0.7 ivfflat rebuilds: what actually changed",
40
+ "price": "250000", // atomic USDC: $0.25
41
+ "url": "https://tenjin.blog/...", "matchReasons": ["..."], ... }] } }
42
+ ```
43
+
44
+ A wallet is needed for publishing (it signs the write; no payment involved);
45
+ funding it is needed for paid reads (USDC) and `send` (USDC plus a little ETH
46
+ on Base for gas). Searching and free pieces cost nothing.
47
+
36
48
  ## Commands
37
49
 
38
50
  | Command | Purpose |
39
51
  | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
- | `tenjin install` | Walk you through harness skills, your publish consent mode, and wallet setup, then run the doctor checks |
52
+ | `tenjin install` | Wire the harness skills and run the doctor checks, then settle up to three setup decisions: publishing, harness permissions, wallet |
41
53
  | `tenjin doctor` | Environment, API reachability, contract, skill-wiring, and wallet checks |
42
54
  | `tenjin config [get\|set]` | Spend policy (`maxAutoSpend`, `sessionBudget`, `confirm`, allowlists) and `publish.mode` / `publish.defaultPrice` |
43
55
  | `tenjin wallet [create\|show\|balance]` | Local Base wallet; the key never leaves the machine |
@@ -53,116 +65,89 @@ tenjin search "what actually changed in <library> v3's public API" # your firs
53
65
  | `tenjin candidate [add\|list\|drop]` | Park, list, or discard local publish drafts; a search MISS nudges you about parked ones |
54
66
  | `tenjin send <amount> usdc <to> [--yes]` | **Escape hatch:** move USDC on Base out of the agent wallet (preview, explicit confirm, then the tx hash) |
55
67
 
56
- `send` is human-invoked only: it is deliberately absent from the MCP toolset and
57
- the harness skills, and nothing is signed until the previewed (checksummed)
58
- recipient, amount, and network fee are confirmed, interactively at a TTY or
59
- explicitly with `--yes` when headless. It refuses when the active wallet's
60
- passphrase entry is missing. The `sendMaxAmount` hard per-send cap has no
61
- default: `tenjin send` refuses until you run `tenjin config set sendMaxAmount
62
- <usd|0|none>` (`0` disables the verb, `none` opts in to uncapped), and `--yes`
63
- can never bypass the cap or the unset refusal.
64
- For routing FUTURE revenue away from the agent wallet entirely, connect the
65
- agent to your own Tenjin account instead (delegation); `send` exists for funds
66
- already sitting on the agent key.
67
-
68
- `read` and `buy` split delivery by whether money can move, not by how much work is
69
- involved. `read` is free-only and tries three things in order: the local library,
70
- then an unauthenticated fetch (which delivers free pieces), then — only if a
71
- read-scoped session key is already cached — one signed GET presenting that
72
- delegation, which delivers a piece this wallet already bought. A paid piece that
73
- none of the three reaches hard-refuses (exit 3) with the price and a pointer at
74
- `buy`; the refusal's `entitlementCheck` says whether a session was actually
75
- presented (`session`) or there was none to present (`not_performed`).
76
-
77
- `tenjin session start --scope read` is what mints that key: one wallet signature,
78
- ≤24h, spends nothing. It is a separate opt-in verb precisely so `read` never needs
79
- the wallet — `read` imports no wallet, payment, or session-MINTING module, and its
80
- import graph is test-pinned to stay clear of all three. It cannot unlock a
81
- keystore at all and never consults the spend policy. The key it may present is
82
- P-256: the wrong curve for the EIP-712/secp256k1 signature an EIP-3009 transfer
83
- authorization needs, so `read` cannot pay however it is refactored.
84
-
85
- The session file itself is a **wallet-derived credential** — treat it like one.
86
- Its scope is not a containment boundary, so do not read "read-scoped" as a limit
87
- on what a copied file is worth. What actually bounds it: it expires within 24h
88
- (server-clamped), it is stored 0600, and it records the origin it was minted for
89
- and is never presented anywhere else. That last one is why a stray `--base-url`
90
- cannot redirect it to a host an agent picked.
68
+ ### `read` vs `buy`
69
+
70
+ They split by whether money can move. `read` is free-only: it tries the local
71
+ library, then an unauthenticated fetch (free pieces), then — only if a
72
+ read-scoped session key is already cached — one signed GET that delivers a piece
73
+ this wallet already bought. Anything that would cost money hard-refuses (exit 3)
74
+ with the price and a pointer at `buy`. Output defaults to a heading outline;
75
+ `--print-body` includes the full body, `--sections <tokens>` the leading sections
76
+ within a token budget.
91
77
 
92
78
  `buy` is the paying verb: it re-reads an entitled resource for free before ever
93
- paying, re-delivers already-bought content from the local library without paying
94
- again, and refuses to sign if the price rose since it first saw the 402. Spend
95
- policy is enforced in the wallet provider layer before any payment.
79
+ paying, re-delivers already-bought content from the local library, and refuses to
80
+ sign if the price rose since it first saw the 402. Spend policy is enforced
81
+ before any payment.
82
+
83
+ ### Session keys
84
+
85
+ `tenjin session start --scope read` mints the key `read` may present: one wallet
86
+ signature, ≤24h, spends nothing, and the P-256 key is the wrong curve to
87
+ authorize a USDC transfer, so `read` cannot pay however it is refactored. The
88
+ session file is still a wallet-derived credential; what it is really worth and
89
+ when to pre-clear the verb is covered in
90
+ [docs/agent-permissions.md](./docs/agent-permissions.md).
91
+
92
+ ### `edit`
96
93
 
97
94
  `edit` sends only the fields you pass, so an omitted field is kept; `--clear
98
95
  <field>` is the one way to empty a card field, and `--question` / `--task`
99
96
  replace the stored list while `--add-question` / `--add-task` append to it. The
100
- append flags read the post and then write it back, with no concurrency guard (the
97
+ append flags read the post and then write it back with no concurrency guard (the
101
98
  API offers no `If-Match`), so a web-panel edit landing between the two calls can
102
- be overwritten. Reading your own post is owner-scoped, so even the no-flag show
103
- signs with your wallet on first use, minting a read-scoped 24h session; only a run
104
- that intends to write asks for a write-capable one. An edit sends only what
105
- actually changes, so re-running the same command writes nothing.
106
-
107
- Read output defaults to a heading outline, not the body: `--print-body` includes
108
- the full body, and `--sections <tokens>` includes the leading sections within a
109
- token budget (deterministic, no model calls).
110
-
111
- A `MISS` may carry a `browse` tail: at most three pointers (`resourceId`, `url`,
112
- `title`, `price`, `creator.handle`) into the broad discoverable corpus, with no
113
- match reasons and no score. They are "you might browse this" hints, not ranked
114
- answers, so a MISS with `browse` is still a MISS. They are never recorded
115
- locally, so `buy <resourceId>` cannot reach one; the `url` is the payable read
116
- endpoint, so `buy <url>` can, which is why the human hint line prints each
117
- pointer's price alongside its title.
118
-
119
- The search question must be **generalized public text**: strip secrets, private
120
- identifiers, and internal context, then send what is left as one complete
121
- natural-language sentence. Retrieval matches wording and meaning, so compressing
122
- the question to keywords throws away signal. By default the server stores no
123
- query text at all; `tenjin config set evalCohort true` opts into 90-day retention
124
- of the question for retrieval evaluation.
99
+ be overwritten. Re-running the same command writes nothing.
125
100
 
126
- > **Money units.** `--max-price`, `--price`, and the spend-policy config values are
127
- > entered in **decimal USD** at the CLI edge (e.g. `--max-price 0.10`), and emitted
128
- > in machine output as both atomic and USD, so humans read dollars while agents read
129
- > the exact atomic value from the JSON.
101
+ ### Search questions and results
102
+
103
+ The question must be **generalized public text**: strip secrets, private
104
+ identifiers, and internal context, then send one complete natural-language
105
+ sentence — retrieval matches wording and meaning, so keyword-compression throws
106
+ away signal. By default the server stores no query text;
107
+ `tenjin config set evalCohort true` opts into 90-day retention for retrieval
108
+ evaluation.
109
+
110
+ A `MISS` may carry a `browse` tail: at most three "you might browse this"
111
+ pointers with no match reasons and no score, so a MISS with `browse` is still a
112
+ MISS. They are never recorded locally, so `buy <resourceId>` cannot reach one;
113
+ each pointer's `url` is the payable read endpoint, so `buy <url>` can.
130
114
 
131
115
  ## Consent modes and pricing
132
116
 
133
117
  `publish.mode` governs ALL publishing uniformly. A piece you asked for and a
134
118
  reusable answer your agent derived after a search both go through it, after a
135
- deterministic local scan (secrets, keys, PII, wallet addresses) that runs in
136
- every mode:
137
-
138
- - **`review`** (the default) asks a one-click yes/no for every publish, even a
139
- clean scan. This is the safe default: nothing leaves your machine unseen.
140
- - **`auto`** publishes a clean scan immediately, including answers your agent
141
- derives; any warning finding stops and asks; a hard block (a live secret or
142
- private key) always refuses.
143
- - **`full-auto`** does not stop for warnings, only for hard blocks. It is honored
144
- from config, env, a flag, or a gitignored `.tenjin.json`, but a committed
145
- `.tenjin.json` requesting it downgrades to `auto`, so cloning a repo can never
146
- enable silent auto-publishing.
119
+ deterministic local scan that runs in every mode:
120
+
121
+ - **`review`** (the stored default) asks a one-click yes/no for every publish.
122
+ - **`auto`** publishes a clean scan immediately, warnings still stop and ask.
123
+ - **`full-auto`** stops only for hard blocks (a live secret or a private key).
124
+
125
+ A hard block always refuses, in every mode. `full-auto` is honored from config,
126
+ env, a flag, or a gitignored `.tenjin.json`, but a committed `.tenjin.json`
127
+ requesting it downgrades to `auto`, so cloning a repo can never enable silent
128
+ auto-publishing.
147
129
 
148
130
  `--yes` clears the warning findings and the review confirm; it never clears a hard
149
131
  block. Set the mode with `tenjin config set publish.mode <mode>`, or per run with
150
- `--mode`. `tenjin install` asks once on an interactive setup and otherwise leaves
151
- the default (review); change it any time with `tenjin config set publish.mode`.
132
+ `--mode`.
152
133
 
153
134
  Pricing: `--price` (or a frontmatter `price:`) wins, otherwise `publish.defaultPrice`
154
135
  (default $0.10). A card never auto-prices; the `tenjin-publish` skill's rubric is
155
136
  what actually chooses a price before it calls the command.
156
137
 
138
+ > **Money units.** `--max-price`, `--price`, and the spend-policy config values are
139
+ > entered in **decimal USD** at the CLI edge (e.g. `--max-price 0.10`), and emitted
140
+ > in machine output as both atomic and USD, so humans read dollars while agents read
141
+ > the exact atomic value from the JSON.
142
+
157
143
  ## Auto-mode permission allowlist
158
144
 
159
- Coding harnesses running unattended ("auto mode", "full auto", YOLO) classify each
160
- shell command before running it, and an unknown binary is denied by default. That
161
- denies the free verbs too, which breaks the whole marketplace loop: the skills
162
- forbid working around a denial, so a denied `tenjin search` just stops.
145
+ Harnesses running unattended ("auto mode", "full auto", YOLO) deny an unknown
146
+ binary by default, which denies the free verbs too and stops the whole loop: the
147
+ skills forbid working around a denial, so a denied `tenjin search` just stops.
163
148
 
164
149
  Pre-clear the free verbs once. In Claude Code these go in the `permissions.allow`
165
- array of `.claude/settings.json`:
150
+ array of `~/.claude/settings.json`:
166
151
 
167
152
  ```
168
153
  Bash(tenjin search:*)
@@ -176,124 +161,55 @@ Bash(tenjin config get:*)
176
161
  Bash(tenjin candidate list:*)
177
162
  ```
178
163
 
179
- None of those can spend, and none can open the keystore. That is the definition of
180
- this tier, and it is deliberately narrower than "signs nothing": `tenjin read` can
181
- present a session key that already exists (below), which is a signature — a P-256
182
- delegation, the wrong curve to authorize a USDC transfer. It cannot mint one; that
183
- needs the wallet.
184
-
185
- Worth knowing before you paste the `read` line: once a session key exists, `read`
186
- **transmits that wallet-derived credential** to the origin it was minted for. That
187
- origin binding is what keeps a stray `--base-url` from redirecting it, and it is
188
- the reason the binding exists rather than a nicety.
189
-
190
- Three are not read-only, which is worth knowing before you pre-clear them:
191
- `tenjin search` POSTs your generalized question off-machine, and `tenjin outcome`
192
- POSTs a report that moves the marketplace's reuse signal — both unauthenticated
193
- and free, neither carrying a credential — while `tenjin read` writes locally,
194
- saving a delivered piece to your library.
195
-
196
- `tenjin install` prints this block, and `tenjin doctor` reprints it on every run
197
- (including in `doctor --json` under `permissions`, on the failure envelope as well
198
- as the success one), so an agent that just got denied can point you at the exact
199
- line.
200
-
201
- **A prefix rule pins the verb, not the flags.** Every line above also clears
202
- `--base-url <url>` on that verb, because the CLI accepts the global flags on every
203
- subcommand. `--base-url` is validated as a URL and nothing more, and it wins
204
- settings precedence, so it moves where the question goes, where `doctor` probes,
205
- and (with the `buy` line below) where a SIWX signature and an EIP-3009 payment
206
- authorization are sent. The origin pin only checks that a resource URL shares an
207
- origin with the _configured_ base, so an attacker-controlled pair satisfies it.
208
- There is no prefix syntax for "this verb but not that flag", so treat this as a
209
- disclosed limit: set your base URL in config, and allowlist these verbs only if
210
- you are content for an agent to be able to choose the destination host. The
211
- skills tell agents never to pass `--base-url` on an allowlisted verb, but that is
212
- a convention rather than an enforced boundary.
213
-
214
- Purchases are a **separate, explicit opt-in**:
215
-
216
- ```
217
- Bash(tenjin buy:*)
218
- ```
219
-
220
- Read this before pasting it: **on the default config that line authorizes
221
- unattended spending up to your wallet balance.** `--yes` is an ordinary flag on
222
- the same allowlisted verb and it clears the confirm gate outright, so `confirm:
223
- always` does not put a human on every purchase once the agent can pass `--yes`.
224
- Walking the defaults: `allowlistCreators` is empty (gate off), `maxAutoSpend` is
225
- `0` and `confirm` is `always`, which together only ask for a confirmation that
226
- `--yes` satisfies, and `sessionBudget` is `0`, which the policy reads as **no
227
- ceiling at all**, not a zero one. Set real values first:
228
-
229
- ```bash
230
- tenjin config set maxAutoSpend 0.25
231
- tenjin config set sessionBudget 2.00
232
- ```
164
+ Three tiers:
233
165
 
234
- The allowlist line itself never raises a spend cap. That is true, and it is not
235
- the same as saying the caps stop an allowlisted `buy`.
166
+ - **The nine free verbs above** cannot spend and cannot open the keystore.
167
+ - **`Bash(tenjin buy:*)`** is a separate opt-in that, on the default config,
168
+ authorizes unattended spending up to your wallet balance.
169
+ - **`Bash(tenjin session start:*)`** is a separate opt-in that spends nothing and
170
+ cannot spend, but does open the keystore.
236
171
 
237
- Minting a session key is the **other** explicit opt-in — it spends nothing and
238
- cannot spend, but it opens the keystore:
172
+ `tenjin install` offers to write the free tier for you (`--allow-free-verbs`
173
+ headlessly), and `tenjin doctor` reprints all three tiers on every run, including
174
+ under `doctor --json`.
239
175
 
240
- ```
241
- Bash(tenjin session start:*)
242
- ```
176
+ Read [docs/agent-permissions.md](./docs/agent-permissions.md) before you paste
177
+ either opt-in line. It covers the per-verb rationale, why a prefix rule pins the
178
+ verb and not the flags (`--base-url`), what a cached session key is really worth,
179
+ the spend-policy defaults an allowlisted `buy` runs under, the verbs that are never
180
+ recommended, and the MCP tool surface these Bash rules do not reach.
243
181
 
244
- `tenjin session start --scope read` takes one wallet signature and leaves a ≤24h
245
- P-256 delegation in `~/.tenjin/session.json` (0600), which `tenjin read` then
246
- presents to recover pieces you already own. The key is the wrong curve to sign an
247
- EIP-3009 payment authorization, so the line can never become a spend grant.
248
-
249
- Do not read the `read` scope as more than that. The scope is enforced only on the
250
- request shape that carries a session signature alongside the delegation header; a
251
- copy of the same delegation presented differently is not scope-checked, so treat
252
- the file as a credential carrying your wallet's authority. Its real bounds are the
253
- 24h expiry, the 0600 mode, and the origin binding.
254
-
255
- What you are clearing is **unattended keystore access**: on an encrypted wallet
256
- the passphrase comes from the environment rather than from you, and the
257
- `--base-url` caveat above bites hardest here, because a mint against a host an
258
- agent chose is a wallet signature you did not intend to make. `tenjin doctor`
259
- reports whether a session exists, for which origin, at what scope, and when it
260
- expires.
261
-
262
- Deliberately **never** recommended, because each is a human decision: `tenjin send`
263
- (moves USDC out of the wallet, and is not bounded by the buy spend policy), `tenjin
264
- publish`, `tenjin wallet create`, `tenjin config set` (it can widen the agent's own
265
- spend policy), `tenjin candidate add` / `tenjin candidate drop`, `tenjin install`,
266
- and `tenjin mcp`
267
- (it re-exposes every command core, so clearing it clears everything). For the same
268
- reason, prefer the narrow rules above over a broad `Bash(tenjin:*)`, `Bash(tenjin
269
- wallet:*)`, or `Bash(tenjin config:*)`, which would swallow them.
270
-
271
- Two gaps worth knowing, both of which fail closed (denied, never wrongly allowed):
272
- bare `tenjin config` is as read-only as `config get` but no prefix rule reaches it
273
- without also covering `config set`, so use `tenjin config get <key>`; and group-level
274
- flag forms like `tenjin wallet --json show` are not covered, so put global flags
275
- after the leaf verb (`tenjin wallet show --json`).
276
-
277
- **Running the local MCP server instead?** That is a different permission surface:
278
- the harness gates tools there, and these Bash rules do not apply. If you follow
279
- the [MCP section](#local-stdio-mcp-server) as well, leave
280
- `mcp__tenjin__tenjin_publish` and `mcp__tenjin__tenjin_wallet` gated, treat
281
- `mcp__tenjin__tenjin_candidate` as gated for its add/drop actions, and treat
282
- `mcp__tenjin__tenjin_buy` as the same opt-in decision as the `buy` line above.
283
-
284
- This harness allowlist is unrelated to the `allowlistCreators` spend-policy key:
285
- that one gates **who you may pay**, this one gates **which commands may run**.
286
-
287
- ## Skills (installed by `tenjin install`)
182
+ ## Install walkthrough
288
183
 
289
184
  `tenjin install` auto-detects your harness, copies the three Tenjin skills into
290
- place, wires the pointers each harness needs, and runs the `doctor` checks as its
291
- last step. It is idempotent: re-run any time, `--dry-run` previews the changes
292
- without writing, and `--harness claude|codex|shared` (repeatable) targets a
293
- specific one, which is remembered so `doctor` keeps checking it. `--publish-mode
294
- <mode>` sets your consent mode non-interactively.
295
-
296
- Where the skills land:
185
+ place, wires the pointers each harness needs, and runs the `doctor` checks. Then
186
+ it settles up to three decisions (each is skipped when already configured, not
187
+ applicable, or answered by flag) and prints a summary of at most five lines.
188
+ Nothing else is a decision:
189
+
190
+ 1. **Publishing.** "When your agent has something worth publishing:" with three
191
+ options: "Auto (recommended)" ("your agent publishes clean pieces on its own;
192
+ your harness still shows each command for approval"), "Ask me in chat first",
193
+ and "Fully unattended" ("only hard blocks stop it").
194
+ 2. **Permissions.** "Let your agent search tenjin without permission popups? Adds
195
+ 9 free commands to `~/.claude/settings.json`. None can spend USDC or open your
196
+ wallet keystore; three send or store data (search, outcome, read). Full
197
+ caveats: tenjin doctor." Yes merges the free-verb allowlist into that file.
198
+ Claude Code only; other harnesses skip it with a note.
199
+ 3. **Wallet.** "Create a wallet now?", asked only when you do not already have one.
200
+
201
+ Every question has a flag, so a headless install never waits on one:
202
+ `--publish-mode <mode>`, `--allow-free-verbs`, and `--no-wallet`. Under `--json`
203
+ or a pipe it asks nothing at all and emits the envelope.
204
+
205
+ It is idempotent: re-run any time, `--dry-run` previews the changes without
206
+ writing, and `--harness claude|codex|shared` (repeatable) targets a specific one,
207
+ which is remembered so `doctor` keeps checking it. `--claude-md` / `--no-claude-md`
208
+ control the one-line search nudge in `~/.claude/CLAUDE.md`.
209
+
210
+ ## Skills
211
+
212
+ Where the three skills land:
297
213
 
298
214
  - **Claude Code** (`~/.claude` present or `claude` on PATH): `~/.claude/skills/`.
299
215
  - **Codex** (`~/.codex` present or `codex` on PATH): `~/.agents/skills/`, the
@@ -342,7 +258,31 @@ directory a harness it detected here reads, plus any directory you named with
342
258
  harness Tenjin does not probe for. A leftover directory that is neither is
343
259
  described, not warned about.
344
260
 
345
- A funded wallet is only needed for paid reads and publishing.
261
+ Updating the CLI updates the adapters it wrote. Every `tenjin` command except
262
+ `install` compares the `tenjin-search` and `tenjin-publish` copies already in
263
+ those directories against the packaged ones and rewrites the files whose bytes
264
+ differ, so an upgrade never leaves your agent reading an older version's
265
+ instructions.
266
+
267
+ Because that write is unattended, it is narrower than the `install` you ran
268
+ yourself. It creates nothing you have not installed, and it rewrites only a
269
+ regular file whose frontmatter `name:` says it is that skill, so a third-party
270
+ skill sitting at one of those paths is left alone. It follows no symlink at the
271
+ three levels it writes: a dotfiles-managed SKILL.md, skill directory or skills
272
+ directory is never healed. `tenjin install` follows your link and writes through
273
+ it, because you pointed it somewhere on purpose, and that is the command that
274
+ keeps a symlinked skill current. The hosted `tenjin` mirror is never touched, because
275
+ your copy may be a newer fetch from
276
+ [tenjin.blog/skills.md](https://tenjin.blog/skills.md) than this package ships. A
277
+ rewritten file keeps its mode, and every rewrite prints one dim stderr line
278
+ naming the files (stdout is untouched, so `--json` still emits exactly one
279
+ envelope). The check runs after the command's own output and never fails the
280
+ command you ran. A skill it cannot write is skipped quietly rather than warned
281
+ about on every command; `tenjin doctor` is where a skill that is wired but not
282
+ from this build gets reported.
283
+
284
+ It is skipped entirely when `CI` is set, when `TENJIN_NO_SKILL_HEAL=1`, and when
285
+ the CLI is running from a source checkout rather than an installed package.
346
286
 
347
287
  ## No CLI? Zero-install fallback
348
288
 
@@ -458,30 +398,12 @@ approval.
458
398
  — its passphrase entry is keyed by the wallet's address, so signing resumes
459
399
  transparently.
460
400
  - The signing passphrase resolves in order: `TENJIN_WALLET_PASSPHRASE`, then the
461
- OS credential store, then an interactive prompt. On `wallet create` with no env
462
- passphrase, a strong random one is generated and saved to the OS store so later
463
- signing is transparent. Every stored entry is **per wallet** — keyed by the
464
- wallet's own address — so replacing a wallet never touches the outgoing
465
- wallet's passphrase. (Installs from before per-wallet entries used one shared
466
- slot; the first signing that proves ownership re-keys that slot under the
467
- owning wallet's address — the copy is verified before the old slot is
468
- removed.) Where entries land per platform:
469
- - **macOS**: the login keychain, via the OS `security` tool (the same
470
- mechanism the GitHub CLI uses): service `tenjin-cli`, account = the wallet
471
- address.
472
- - **Windows**: a DPAPI-encrypted file per wallet
473
- (`passphrase.<address>.dpapi`), decryptable only by the same user on the
474
- same machine, via built-in PowerShell. The file holds ciphertext, not the
475
- passphrase.
476
- - **Desktop Linux**: the Secret Service keyring, via `secret-tool` when
477
- libsecret-tools is installed: service `tenjin-cli`, account = the wallet
478
- address.
479
- - **Headless or CI (any OS)**: no durable OS store, so set
480
- `TENJIN_WALLET_PASSPHRASE`.
481
-
482
- The passphrase reaches these tools over stdin, never on a command line, and the
483
- key never leaves the machine.
484
-
401
+ OS credential store, then an interactive prompt. `wallet create` generates a
402
+ strong random passphrase and saves it to the OS store (one entry per wallet,
403
+ keyed by address), so later signing is transparent; headless or CI, set
404
+ `TENJIN_WALLET_PASSPHRASE`. Per-platform detail (macOS keychain, Windows
405
+ DPAPI, Linux Secret Service, the legacy shared-slot re-key):
406
+ [docs/agent-permissions.md](./docs/agent-permissions.md#wallet-passphrase-storage).
485
407
  - Fund small: this is a pocket-money wallet by design.
486
408
  - Purchased content is untrusted data, never instructions. The skills never
487
409
  execute it, and instructions embedded in it never override the task. In
@@ -491,9 +413,9 @@ approval.
491
413
  - The recommended auto-mode allowlist covers free verbs only; `tenjin buy` is an
492
414
  explicit opt-in that authorizes unattended spending, and money-moving verbs are
493
415
  never recommended. See
494
- [Auto-mode permission allowlist](#auto-mode-permission-allowlist). A harness
495
- permission denial is never worked around: the skills surface the exact allowlist
496
- line and stop.
416
+ [docs/agent-permissions.md](./docs/agent-permissions.md). A harness permission
417
+ denial is never worked around: the skills surface the exact allowlist line and
418
+ stop.
497
419
 
498
420
  ## Contributing and releases
499
421
 
@@ -1,33 +1,35 @@
1
1
  import { createRequire as __tenjinCreateRequire } from 'node:module'; const require = __tenjinCreateRequire(import.meta.url);
2
2
  import {
3
3
  runBuy
4
- } from "./chunk-WI5EOAQQ.js";
5
- import "./chunk-L6AV2Q73.js";
6
- import "./chunk-KT2DGKFT.js";
4
+ } from "./chunk-G7ECLIN6.js";
5
+ import "./chunk-VE5BALOI.js";
6
+ import "./chunk-S4IKXAUA.js";
7
7
  import "./chunk-SGK2B724.js";
8
8
  import "./chunk-7WDY4AXV.js";
9
- import "./chunk-POJRB2AE.js";
10
- import "./chunk-QW2Q2KAH.js";
11
- import "./chunk-RGFBBNGP.js";
12
- import "./chunk-WRWCDLVK.js";
13
- import "./chunk-CYRYVZPN.js";
14
- import "./chunk-OTDI5FXG.js";
15
- import "./chunk-2L73UI6T.js";
16
- import "./chunk-WWX32ML4.js";
17
- import "./chunk-GXYNLMUQ.js";
18
- import "./chunk-WDJTGVKN.js";
19
- import "./chunk-XBJ3VLWX.js";
20
- import "./chunk-2I4QTOLB.js";
21
- import "./chunk-BBUYCDSG.js";
22
9
  import "./chunk-KZAAWQNP.js";
23
10
  import "./chunk-S5RYMCV6.js";
11
+ import "./chunk-POJRB2AE.js";
24
12
  import "./chunk-YLYINX2H.js";
25
- import "./chunk-DAJ56EUU.js";
26
- import "./chunk-YBMMV4Y4.js";
27
- import "./chunk-UO22YNY4.js";
28
- import "./chunk-UYP7G3GZ.js";
29
- import "./chunk-J6CVKC4M.js";
13
+ import "./chunk-QW2Q2KAH.js";
30
14
  import "./chunk-MJZZTKCC.js";
15
+ import "./chunk-I4WQXOEL.js";
16
+ import "./chunk-BFAFOBO3.js";
17
+ import "./chunk-GJKDWZ6X.js";
18
+ import "./chunk-JURZ2T2I.js";
19
+ import "./chunk-MHRREGGN.js";
20
+ import "./chunk-WWX32ML4.js";
21
+ import "./chunk-V7BWPOKT.js";
22
+ import "./chunk-6L34JW52.js";
23
+ import "./chunk-PZSUWDF2.js";
24
+ import "./chunk-R2VLGNFD.js";
25
+ import "./chunk-CTFFFQFH.js";
26
+ import "./chunk-TYVLXAB5.js";
27
+ import "./chunk-UO22YNY4.js";
28
+ import "./chunk-KRHUDEIQ.js";
29
+ import "./chunk-OQXHNWM3.js";
30
+ import "./chunk-P74I3WH4.js";
31
+ import "./chunk-2I4QTOLB.js";
32
+ import "./chunk-PZRAAAY2.js";
31
33
  import "./chunk-7FK2UN2T.js";
32
34
  import "./chunk-M2O56UK7.js";
33
35
  import "./chunk-UHTVXQ2O.js";
@@ -41,4 +43,4 @@ import "./chunk-ZXTAQYNA.js";
41
43
  export {
42
44
  runBuy
43
45
  };
44
- //# sourceMappingURL=buy-XVOMNWKN.js.map
46
+ //# sourceMappingURL=buy-3PPC2SRQ.js.map
@@ -3,19 +3,21 @@ import {
3
3
  runCandidateAdd,
4
4
  runCandidateDrop,
5
5
  runCandidateList
6
- } from "./chunk-2YX6LTCD.js";
7
- import "./chunk-VZ3AJCO5.js";
6
+ } from "./chunk-XDW6GOHO.js";
7
+ import "./chunk-75G4REUY.js";
8
8
  import "./chunk-WWX32ML4.js";
9
- import "./chunk-2I4QTOLB.js";
10
- import "./chunk-BBUYCDSG.js";
11
- import "./chunk-DAJ56EUU.js";
9
+ import "./chunk-R2VLGNFD.js";
10
+ import "./chunk-CTFFFQFH.js";
12
11
  import "./chunk-UO22YNY4.js";
13
- import "./chunk-UYP7G3GZ.js";
14
- import "./chunk-J6CVKC4M.js";
12
+ import "./chunk-KRHUDEIQ.js";
13
+ import "./chunk-OQXHNWM3.js";
14
+ import "./chunk-P74I3WH4.js";
15
+ import "./chunk-2I4QTOLB.js";
16
+ import "./chunk-PZRAAAY2.js";
15
17
  import "./chunk-ZXTAQYNA.js";
16
18
  export {
17
19
  runCandidateAdd,
18
20
  runCandidateDrop,
19
21
  runCandidateList
20
22
  };
21
- //# sourceMappingURL=candidate-DJB2NNTG.js.map
23
+ //# sourceMappingURL=candidate-FCBWDN4Y.js.map
@@ -3,28 +3,27 @@ import {
3
3
  SESSION_CHAIN_ID,
4
4
  createSessionKeyAuth,
5
5
  createSiwxAuth
6
- } from "./chunk-ZFE7STX7.js";
6
+ } from "./chunk-AX5WQ3H5.js";
7
7
  import {
8
8
  rateLimitError
9
- } from "./chunk-2L73UI6T.js";
9
+ } from "./chunk-MHRREGGN.js";
10
10
  import {
11
11
  ATOMIC_RE,
12
12
  UUID_RE
13
13
  } from "./chunk-WWX32ML4.js";
14
14
  import {
15
- CLIENT_HEADER,
16
15
  httpRequest
17
- } from "./chunk-GXYNLMUQ.js";
16
+ } from "./chunk-V7BWPOKT.js";
18
17
  import {
19
18
  trimSlash
20
- } from "./chunk-XBJ3VLWX.js";
19
+ } from "./chunk-PZSUWDF2.js";
21
20
  import {
22
21
  PublishModeSchema
23
- } from "./chunk-UYP7G3GZ.js";
22
+ } from "./chunk-KRHUDEIQ.js";
24
23
  import {
25
24
  CliError,
26
25
  external_exports
27
- } from "./chunk-J6CVKC4M.js";
26
+ } from "./chunk-PZRAAAY2.js";
28
27
 
29
28
  // src/lib/scan.ts
30
29
  var LONG_QUOTE_WORDS = 80;
@@ -1031,7 +1030,7 @@ async function publishPost(input, auth, opts) {
1031
1030
  const res = await httpRequest(url, {
1032
1031
  method: "POST",
1033
1032
  timeoutMs: opts.timeoutMs,
1034
- headers: { "x-tenjin-client": CLIENT_HEADER, ...authHeaders },
1033
+ headers: { ...authHeaders },
1035
1034
  jsonBody: body,
1036
1035
  ...opts.fetchImpl !== void 0 ? { fetchImpl: opts.fetchImpl } : {}
1037
1036
  });
@@ -1129,7 +1128,7 @@ async function getOwnPost(id, auth, opts) {
1129
1128
  const res = await httpRequest(url, {
1130
1129
  method: "GET",
1131
1130
  timeoutMs: opts.timeoutMs,
1132
- headers: { accept: "application/json", "x-tenjin-client": CLIENT_HEADER, ...authHeaders },
1131
+ headers: { accept: "application/json", ...authHeaders },
1133
1132
  ...opts.fetchImpl !== void 0 ? { fetchImpl: opts.fetchImpl } : {}
1134
1133
  });
1135
1134
  if (!res.ok) throw writeTransportError(url, res);
@@ -1167,7 +1166,7 @@ async function updatePost(id, input, auth, opts) {
1167
1166
  const res = await httpRequest(url, {
1168
1167
  method: "PUT",
1169
1168
  timeoutMs: opts.timeoutMs,
1170
- headers: { "x-tenjin-client": CLIENT_HEADER, ...authHeaders },
1169
+ headers: { ...authHeaders },
1171
1170
  jsonBody: body,
1172
1171
  ...opts.fetchImpl !== void 0 ? { fetchImpl: opts.fetchImpl } : {}
1173
1172
  });
@@ -1369,4 +1368,4 @@ export {
1369
1368
  dedupeFindings,
1370
1369
  describeFindings
1371
1370
  };
1372
- //# sourceMappingURL=chunk-PLU3E63S.js.map
1371
+ //# sourceMappingURL=chunk-3MQSXDWS.js.map