tenjin-cli 0.1.0-alpha.5 → 0.1.0-alpha.8

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 (121) hide show
  1. package/README.md +169 -199
  2. package/dist/{buy-YMXXVNFH.js → buy-K2G6XQY2.js} +20 -18
  3. package/dist/{candidate-H7FR4AU5.js → candidate-DJB2NNTG.js} +7 -8
  4. package/dist/{chunk-ZW3B5LWX.js → chunk-2YX6LTCD.js} +5 -5
  5. package/dist/{chunk-4WVKXKDK.js → chunk-6OE2IJMH.js} +29 -238
  6. package/dist/chunk-6OE2IJMH.js.map +1 -0
  7. package/dist/{chunk-ADJYSM45.js → chunk-6ZBZCBR7.js} +27 -13
  8. package/dist/chunk-6ZBZCBR7.js.map +1 -0
  9. package/dist/{chunk-HTDALK7M.js → chunk-B7YB4MMU.js} +15 -12
  10. package/dist/{chunk-HTDALK7M.js.map → chunk-B7YB4MMU.js.map} +1 -1
  11. package/dist/{chunk-NFSOVL3C.js → chunk-BBUYCDSG.js} +12 -3
  12. package/dist/chunk-BBUYCDSG.js.map +1 -0
  13. package/dist/chunk-C3S6725N.js +337 -0
  14. package/dist/chunk-C3S6725N.js.map +1 -0
  15. package/dist/chunk-CYRYVZPN.js +213 -0
  16. package/dist/chunk-CYRYVZPN.js.map +1 -0
  17. package/dist/{chunk-MDDGEGSW.js → chunk-DAJ56EUU.js} +3 -3
  18. package/dist/{chunk-IOPWPMT2.js → chunk-DH6D6QIO.js} +5 -5
  19. package/dist/{chunk-NJF2WENW.js → chunk-DQDGBWWH.js} +4 -2
  20. package/dist/chunk-DQDGBWWH.js.map +1 -0
  21. package/dist/chunk-EDENZN2Q.js +614 -0
  22. package/dist/chunk-EDENZN2Q.js.map +1 -0
  23. package/dist/chunk-GABYDXWL.js +190 -0
  24. package/dist/chunk-GABYDXWL.js.map +1 -0
  25. package/dist/{chunk-LAM66WFJ.js → chunk-GM4RZUVU.js} +6 -8
  26. package/dist/{chunk-LAM66WFJ.js.map → chunk-GM4RZUVU.js.map} +1 -1
  27. package/dist/{chunk-PAUXMRSF.js → chunk-J6CVKC4M.js} +73 -2
  28. package/dist/chunk-J6CVKC4M.js.map +1 -0
  29. package/dist/chunk-L6AV2Q73.js +105 -0
  30. package/dist/chunk-L6AV2Q73.js.map +1 -0
  31. package/dist/{chunk-PYNSGYBE.js → chunk-NVHQCTIC.js} +249 -552
  32. package/dist/chunk-NVHQCTIC.js.map +1 -0
  33. package/dist/{chunk-CVX6JNGD.js → chunk-OTDI5FXG.js} +3 -5
  34. package/dist/{chunk-CVX6JNGD.js.map → chunk-OTDI5FXG.js.map} +1 -1
  35. package/dist/{chunk-3IRDP7TN.js → chunk-P3FBESBB.js} +6 -4
  36. package/dist/{chunk-3IRDP7TN.js.map → chunk-P3FBESBB.js.map} +1 -1
  37. package/dist/{chunk-FU6MCSLG.js → chunk-PCLPVJ3J.js} +16 -78
  38. package/dist/chunk-PCLPVJ3J.js.map +1 -0
  39. package/dist/chunk-QB2NNV6C.js +143 -0
  40. package/dist/chunk-QB2NNV6C.js.map +1 -0
  41. package/dist/{chunk-C444K6MI.js → chunk-RGFBBNGP.js} +42 -17
  42. package/dist/{chunk-C444K6MI.js.map → chunk-RGFBBNGP.js.map} +1 -1
  43. package/dist/{chunk-TXPPMK4L.js → chunk-RGTTACP3.js} +5 -5
  44. package/dist/chunk-SGK2B724.js +67 -0
  45. package/dist/chunk-SGK2B724.js.map +1 -0
  46. package/dist/{chunk-ZDY2KY5X.js → chunk-URSGGRO4.js} +28 -11
  47. package/dist/chunk-URSGGRO4.js.map +1 -0
  48. package/dist/{chunk-5SCU253N.js → chunk-UYP7G3GZ.js} +2 -2
  49. package/dist/{chunk-ZIYVN4CD.js → chunk-VZ3AJCO5.js} +3 -5
  50. package/dist/{chunk-ZIYVN4CD.js.map → chunk-VZ3AJCO5.js.map} +1 -1
  51. package/dist/{chunk-QONTBYQW.js → chunk-WRWCDLVK.js} +4 -6
  52. package/dist/{chunk-QONTBYQW.js.map → chunk-WRWCDLVK.js.map} +1 -1
  53. package/dist/chunk-XBJ3VLWX.js +35 -0
  54. package/dist/chunk-XBJ3VLWX.js.map +1 -0
  55. package/dist/{chunk-RTJLLPFA.js → chunk-XFHZWORF.js} +123 -24
  56. package/dist/chunk-XFHZWORF.js.map +1 -0
  57. package/dist/{chunk-BIKAUVC2.js → chunk-ZA3RFDAV.js} +40 -6
  58. package/dist/chunk-ZA3RFDAV.js.map +1 -0
  59. package/dist/{cli-IW76QTN3.js → cli-KNCYWMAG.js} +237 -25
  60. package/dist/cli-KNCYWMAG.js.map +1 -0
  61. package/dist/{config-VCOS7P5K.js → config-SAQEQRFB.js} +5 -6
  62. package/dist/dist-U4M6QCKE.js +2842 -0
  63. package/dist/dist-U4M6QCKE.js.map +1 -0
  64. package/dist/{doctor-WS65JG3V.js → doctor-FBRQNOUQ.js} +10 -9
  65. package/dist/{publish-DSFWQRUN.js → edit-IZZ2HIMR.js} +20 -18
  66. package/dist/index.js +1 -1
  67. package/dist/{inspect-SFJWUQHO.js → inspect-BFWZ5XOP.js} +17 -16
  68. package/dist/{install-RVPQPCKH.js → install-QXZCHIBT.js} +400 -166
  69. package/dist/install-QXZCHIBT.js.map +1 -0
  70. package/dist/outcome-VXCBEGNC.js +20 -0
  71. package/dist/publish-5NTCRF2V.js +40 -0
  72. package/dist/read-T6OTMU72.js +158 -0
  73. package/dist/read-T6OTMU72.js.map +1 -0
  74. package/dist/{run-OMPKA43G.js → run-5OGX64IY.js} +106 -32
  75. package/dist/{run-OMPKA43G.js.map → run-5OGX64IY.js.map} +1 -1
  76. package/dist/search-LIIWUMWV.js +24 -0
  77. package/dist/{send-3G4C64HJ.js → send-ENE47KQE.js} +7 -7
  78. package/dist/session-HY4QIWHV.js +87 -0
  79. package/dist/session-HY4QIWHV.js.map +1 -0
  80. package/dist/{wallet-PP22LAX7.js → wallet-OCCGEH6H.js} +7 -7
  81. package/dist/{wallet-B7KJS2R5.js → wallet-RBDVNZVR.js} +5 -5
  82. package/dist/wallet-RBDVNZVR.js.map +1 -0
  83. package/docs/agent-permissions.md +255 -0
  84. package/package.json +3 -1
  85. package/skills/tenjin/SKILL.md +57 -13
  86. package/skills/tenjin-publish/SKILL.md +12 -4
  87. package/skills/tenjin-search/SKILL.md +68 -12
  88. package/dist/chunk-2JQ5JSG6.js +0 -68
  89. package/dist/chunk-2JQ5JSG6.js.map +0 -1
  90. package/dist/chunk-4WVKXKDK.js.map +0 -1
  91. package/dist/chunk-ADJYSM45.js.map +0 -1
  92. package/dist/chunk-BIKAUVC2.js.map +0 -1
  93. package/dist/chunk-FU6MCSLG.js.map +0 -1
  94. package/dist/chunk-L4IHCN6B.js +0 -63
  95. package/dist/chunk-L4IHCN6B.js.map +0 -1
  96. package/dist/chunk-NFSOVL3C.js.map +0 -1
  97. package/dist/chunk-NJF2WENW.js.map +0 -1
  98. package/dist/chunk-PAUXMRSF.js.map +0 -1
  99. package/dist/chunk-PYNSGYBE.js.map +0 -1
  100. package/dist/chunk-RTJLLPFA.js.map +0 -1
  101. package/dist/chunk-ZDY2KY5X.js.map +0 -1
  102. package/dist/cli-IW76QTN3.js.map +0 -1
  103. package/dist/install-RVPQPCKH.js.map +0 -1
  104. package/dist/outcome-GNYCSZ7J.js +0 -20
  105. package/dist/search-KOI6Y7P6.js +0 -24
  106. /package/dist/{buy-YMXXVNFH.js.map → buy-K2G6XQY2.js.map} +0 -0
  107. /package/dist/{candidate-H7FR4AU5.js.map → candidate-DJB2NNTG.js.map} +0 -0
  108. /package/dist/{chunk-ZW3B5LWX.js.map → chunk-2YX6LTCD.js.map} +0 -0
  109. /package/dist/{chunk-MDDGEGSW.js.map → chunk-DAJ56EUU.js.map} +0 -0
  110. /package/dist/{chunk-IOPWPMT2.js.map → chunk-DH6D6QIO.js.map} +0 -0
  111. /package/dist/{chunk-TXPPMK4L.js.map → chunk-RGTTACP3.js.map} +0 -0
  112. /package/dist/{chunk-5SCU253N.js.map → chunk-UYP7G3GZ.js.map} +0 -0
  113. /package/dist/{config-VCOS7P5K.js.map → config-SAQEQRFB.js.map} +0 -0
  114. /package/dist/{doctor-WS65JG3V.js.map → doctor-FBRQNOUQ.js.map} +0 -0
  115. /package/dist/{inspect-SFJWUQHO.js.map → edit-IZZ2HIMR.js.map} +0 -0
  116. /package/dist/{outcome-GNYCSZ7J.js.map → inspect-BFWZ5XOP.js.map} +0 -0
  117. /package/dist/{publish-DSFWQRUN.js.map → outcome-VXCBEGNC.js.map} +0 -0
  118. /package/dist/{search-KOI6Y7P6.js.map → publish-5NTCRF2V.js.map} +0 -0
  119. /package/dist/{wallet-B7KJS2R5.js.map → search-LIIWUMWV.js.map} +0 -0
  120. /package/dist/{send-3G4C64HJ.js.map → send-ENE47KQE.js.map} +0 -0
  121. /package/dist/{wallet-PP22LAX7.js.map → wallet-OCCGEH6H.js.map} +0 -0
package/README.md CHANGED
@@ -16,120 +16,143 @@ 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
 
36
- ## Commands
32
+ A hit looks like this (`--json` shown; at a terminal you get the same as plain
33
+ lines, with prices in USD):
37
34
 
38
- | Command | Purpose |
39
- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
40
- | `tenjin install` | Walk you through harness skills, your publish consent mode, and wallet setup, then run the doctor checks |
41
- | `tenjin doctor` | Environment, API reachability, contract, skill-wiring, and wallet checks |
42
- | `tenjin config [get\|set]` | Spend policy (`maxAutoSpend`, `sessionBudget`, `confirm`, allowlists) and `publish.mode` / `publish.defaultPrice` |
43
- | `tenjin wallet [create\|show\|balance]` | Local Base wallet; the key never leaves the machine |
44
- | `tenjin search "<question>"` | Ask for payable candidates or an honest MISS; prints the compact JSON verbatim |
45
- | `tenjin inspect <url-or-id>` | Show a candidate's pre-purchase card from the 402 body; never pays |
46
- | `tenjin buy <url-or-id> [--max-price <usd>] [--yes]` | Entitlement re-check (free re-read if owned), then x402 exact payment |
47
- | `tenjin outcome --search-id <id> --status <s>` | Report `used` / `partially_used` / `rejected` / `regenerated` / `purchase_declined` |
48
- | `tenjin publish <file.md> [--price <usd>] [--mode <m>]` | Publish a Markdown piece with an optional answer card, gated by a local scan and your consent mode |
49
- | `tenjin publish --candidate <id>` | Publish a parked candidate (its `draft.md`); clears it on success |
50
- | `tenjin candidate [add\|list\|drop]` | Park, list, or discard local publish drafts; a search MISS nudges you about parked ones |
51
- | `tenjin send <amount> usdc <to> [--yes]` | **Escape hatch:** move USDC on Base out of the agent wallet (preview, explicit confirm, then the tx hash) |
52
-
53
- `send` is human-invoked only: it is deliberately absent from the MCP toolset and
54
- the harness skills, and nothing is signed until the previewed (checksummed)
55
- recipient, amount, and network fee are confirmed, interactively at a TTY or
56
- explicitly with `--yes` when headless. It refuses when the active wallet's
57
- passphrase entry is missing. The `sendMaxAmount` hard per-send cap has no
58
- default: `tenjin send` refuses until you run `tenjin config set sendMaxAmount
59
- <usd|0|none>` (`0` disables the verb, `none` opts in to uncapped), and `--yes`
60
- can never bypass the cap or the unset refusal.
61
- For routing FUTURE revenue away from the agent wallet entirely, connect the
62
- agent to your own Tenjin account instead (delegation); `send` exists for funds
63
- already sitting on the agent key.
64
-
65
- `buy` re-reads an entitled resource for free before ever paying, re-delivers
66
- already-bought content from the local library without paying again, and refuses to
67
- sign if the price rose since it first saw the 402. Spend policy is enforced in the
68
- wallet provider layer before any payment.
69
-
70
- Read output defaults to a heading outline, not the body: `--print-body` includes
71
- the full body, and `--sections <tokens>` includes the leading sections within a
72
- token budget (deterministic, no model calls).
73
-
74
- A `MISS` may carry a `browse` tail: at most three pointers (`resourceId`, `url`,
75
- `title`, `price`, `creator.handle`) into the broad discoverable corpus, with no
76
- match reasons and no score. They are "you might browse this" hints, not ranked
77
- answers, so a MISS with `browse` is still a MISS. They are never recorded
78
- locally, so `buy <resourceId>` cannot reach one; the `url` is the payable read
79
- endpoint, so `buy <url>` can, which is why the human hint line prints each
80
- pointer's price alongside its title.
81
-
82
- The search question must be **generalized public text**: strip secrets, private
83
- identifiers, and internal context, then send what is left as one complete
84
- natural-language sentence. Retrieval matches wording and meaning, so compressing
85
- the question to keywords throws away signal. By default the server stores no
86
- query text at all; `tenjin config set evalCohort true` opts into 90-day retention
87
- of the question for retrieval evaluation.
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
+ ```
88
43
 
89
- > **Money units.** `--max-price`, `--price`, and the spend-policy config values are
90
- > entered in **decimal USD** at the CLI edge (e.g. `--max-price 0.10`), and emitted
91
- > in machine output as both atomic and USD, so humans read dollars while agents read
92
- > the exact atomic value from the JSON.
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
+
48
+ ## Commands
49
+
50
+ | Command | Purpose |
51
+ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | `tenjin install` | Wire the harness skills and run the doctor checks, then settle up to three setup decisions: publishing, harness permissions, wallet |
53
+ | `tenjin doctor` | Environment, API reachability, contract, skill-wiring, and wallet checks |
54
+ | `tenjin config [get\|set]` | Spend policy (`maxAutoSpend`, `sessionBudget`, `confirm`, allowlists) and `publish.mode` / `publish.defaultPrice` |
55
+ | `tenjin wallet [create\|show\|balance]` | Local Base wallet; the key never leaves the machine |
56
+ | `tenjin search "<question>"` | Ask for payable candidates or an honest MISS; prints the compact JSON verbatim |
57
+ | `tenjin inspect <url-or-id>` | Show a candidate's pre-purchase card from the 402 body; never pays |
58
+ | `tenjin read <url-or-id>` | Deliver a free piece, re-deliver from the local library, or recover one you own with a cached session key (never a payment); refuses with exit 3 if it would cost |
59
+ | `tenjin session start [--scope read]` | Open the wallet once to mint a ≤24h read-scoped session key, so `read` can recover owned pieces unattended; spends nothing |
60
+ | `tenjin buy <url-or-id> [--max-price <usd>] [--yes]` | Entitlement re-check (free re-read if owned), then x402 exact payment |
61
+ | `tenjin outcome --search-id <id> --status <s>` | Report `used` / `partially_used` / `rejected` / `regenerated` / `purchase_declined` |
62
+ | `tenjin publish <file.md> [--price <usd>] [--mode <m>]` | Publish a Markdown piece with an optional answer card, gated by a local scan and your consent mode |
63
+ | `tenjin publish --candidate <id>` | Publish a parked candidate (its `draft.md`); clears it on success |
64
+ | `tenjin edit <postId> [flags] [--yes]` | Show one of your posts and its card, or merge-update it: omitted fields are kept, `--clear <field>` clears one |
65
+ | `tenjin candidate [add\|list\|drop]` | Park, list, or discard local publish drafts; a search MISS nudges you about parked ones |
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) |
67
+
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.
77
+
78
+ `buy` is the paying verb: it re-reads an entitled resource for free before ever
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`
93
+
94
+ `edit` sends only the fields you pass, so an omitted field is kept; `--clear
95
+ <field>` is the one way to empty a card field, and `--question` / `--task`
96
+ replace the stored list while `--add-question` / `--add-task` append to it. The
97
+ append flags read the post and then write it back with no concurrency guard (the
98
+ API offers no `If-Match`), so a web-panel edit landing between the two calls can
99
+ be overwritten. Re-running the same command writes nothing.
100
+
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.
93
114
 
94
115
  ## Consent modes and pricing
95
116
 
96
117
  `publish.mode` governs ALL publishing uniformly. A piece you asked for and a
97
118
  reusable answer your agent derived after a search both go through it, after a
98
- deterministic local scan (secrets, keys, PII, wallet addresses) that runs in
99
- every mode:
100
-
101
- - **`review`** (the default) asks a one-click yes/no for every publish, even a
102
- clean scan. This is the safe default: nothing leaves your machine unseen.
103
- - **`auto`** publishes a clean scan immediately, including answers your agent
104
- derives; any warning finding stops and asks; a hard block (a live secret or
105
- private key) always refuses.
106
- - **`full-auto`** does not stop for warnings, only for hard blocks. It is honored
107
- from config, env, a flag, or a gitignored `.tenjin.json`, but a committed
108
- `.tenjin.json` requesting it downgrades to `auto`, so cloning a repo can never
109
- 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.
110
129
 
111
130
  `--yes` clears the warning findings and the review confirm; it never clears a hard
112
131
  block. Set the mode with `tenjin config set publish.mode <mode>`, or per run with
113
- `--mode`. `tenjin install` asks once on an interactive setup and otherwise leaves
114
- the default (review); change it any time with `tenjin config set publish.mode`.
132
+ `--mode`.
115
133
 
116
134
  Pricing: `--price` (or a frontmatter `price:`) wins, otherwise `publish.defaultPrice`
117
135
  (default $0.10). A card never auto-prices; the `tenjin-publish` skill's rubric is
118
136
  what actually chooses a price before it calls the command.
119
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
+
120
143
  ## Auto-mode permission allowlist
121
144
 
122
- Coding harnesses running unattended ("auto mode", "full auto", YOLO) classify each
123
- shell command before running it, and an unknown binary is denied by default. That
124
- denies the free verbs too, which breaks the whole marketplace loop: the skills
125
- 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.
126
148
 
127
149
  Pre-clear the free verbs once. In Claude Code these go in the `permissions.allow`
128
- array of `.claude/settings.json`:
150
+ array of `~/.claude/settings.json`:
129
151
 
130
152
  ```
131
153
  Bash(tenjin search:*)
132
154
  Bash(tenjin inspect:*)
155
+ Bash(tenjin read:*)
133
156
  Bash(tenjin outcome:*)
134
157
  Bash(tenjin doctor:*)
135
158
  Bash(tenjin wallet show:*)
@@ -138,88 +161,55 @@ Bash(tenjin config get:*)
138
161
  Bash(tenjin candidate list:*)
139
162
  ```
140
163
 
141
- None of those touches the wallet, signs anything, or moves money. Two are not
142
- read-only, which is worth knowing before you pre-clear them: `tenjin search` POSTs
143
- your generalized question off-machine, and `tenjin outcome` POSTs a report that
144
- moves the marketplace's reuse signal. Both are unauthenticated and free; neither
145
- carries a credential.
146
-
147
- `tenjin install` prints this block, and `tenjin doctor` reprints it on every run
148
- (including in `doctor --json` under `permissions`, on the failure envelope as well
149
- as the success one), so an agent that just got denied can point you at the exact
150
- line.
151
-
152
- **A prefix rule pins the verb, not the flags.** Every line above also clears
153
- `--base-url <url>` on that verb, because the CLI accepts the global flags on every
154
- subcommand. `--base-url` is validated as a URL and nothing more, and it wins
155
- settings precedence, so it moves where the question goes, where `doctor` probes,
156
- and (with the `buy` line below) where a SIWX signature and an EIP-3009 payment
157
- authorization are sent. The origin pin only checks that a resource URL shares an
158
- origin with the _configured_ base, so an attacker-controlled pair satisfies it.
159
- There is no prefix syntax for "this verb but not that flag", so treat this as a
160
- disclosed limit: set your base URL in config, and allowlist these verbs only if
161
- you are content for an agent to be able to choose the destination host. The
162
- skills tell agents never to pass `--base-url` on an allowlisted verb, but that is
163
- a convention rather than an enforced boundary.
164
-
165
- Purchases are a **separate, explicit opt-in**:
166
-
167
- ```
168
- Bash(tenjin buy:*)
169
- ```
170
-
171
- Read this before pasting it: **on the default config that line authorizes
172
- unattended spending up to your wallet balance.** `--yes` is an ordinary flag on
173
- the same allowlisted verb and it clears the confirm gate outright, so `confirm:
174
- always` does not put a human on every purchase once the agent can pass `--yes`.
175
- Walking the defaults: `allowlistCreators` is empty (gate off), `maxAutoSpend` is
176
- `0` and `confirm` is `always`, which together only ask for a confirmation that
177
- `--yes` satisfies, and `sessionBudget` is `0`, which the policy reads as **no
178
- ceiling at all**, not a zero one. Set real values first:
179
-
180
- ```bash
181
- tenjin config set maxAutoSpend 0.25
182
- tenjin config set sessionBudget 2.00
183
- ```
184
-
185
- The allowlist line itself never raises a spend cap. That is true, and it is not
186
- the same as saying the caps stop an allowlisted `buy`.
187
-
188
- Deliberately **never** recommended, because each is a human decision: `tenjin send`
189
- (moves USDC out of the wallet, and is not bounded by the buy spend policy), `tenjin
190
- publish`, `tenjin wallet create`, `tenjin config set` (it can widen the agent's own
191
- spend policy), `tenjin candidate add` / `tenjin candidate drop`, `tenjin install`,
192
- and `tenjin mcp`
193
- (it re-exposes every command core, so clearing it clears everything). For the same
194
- reason, prefer the narrow rules above over a broad `Bash(tenjin:*)`, `Bash(tenjin
195
- wallet:*)`, or `Bash(tenjin config:*)`, which would swallow them.
164
+ Three tiers:
196
165
 
197
- Two gaps worth knowing, both of which fail closed (denied, never wrongly allowed):
198
- bare `tenjin config` is as read-only as `config get` but no prefix rule reaches it
199
- without also covering `config set`, so use `tenjin config get <key>`; and group-level
200
- flag forms like `tenjin wallet --json show` are not covered, so put global flags
201
- after the leaf verb (`tenjin wallet show --json`).
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.
202
171
 
203
- **Running the local MCP server instead?** That is a different permission surface:
204
- the harness gates tools there, and these Bash rules do not apply. If you follow
205
- the [MCP section](#local-stdio-mcp-server) as well, leave
206
- `mcp__tenjin__tenjin_publish` and `mcp__tenjin__tenjin_wallet` gated, treat
207
- `mcp__tenjin__tenjin_candidate` as gated for its add/drop actions, and treat
208
- `mcp__tenjin__tenjin_buy` as the same opt-in decision as the `buy` line above.
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`.
209
175
 
210
- This harness allowlist is unrelated to the `allowlistCreators` spend-policy key:
211
- that one gates **who you may pay**, this one gates **which commands may run**.
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.
212
181
 
213
- ## Skills (installed by `tenjin install`)
182
+ ## Install walkthrough
214
183
 
215
184
  `tenjin install` auto-detects your harness, copies the three Tenjin skills into
216
- place, wires the pointers each harness needs, and runs the `doctor` checks as its
217
- last step. It is idempotent: re-run any time, `--dry-run` previews the changes
218
- without writing, and `--harness claude|codex|shared` (repeatable) targets a
219
- specific one, which is remembered so `doctor` keeps checking it. `--publish-mode
220
- <mode>` sets your consent mode non-interactively.
221
-
222
- 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:
223
213
 
224
214
  - **Claude Code** (`~/.claude` present or `claude` on PATH): `~/.claude/skills/`.
225
215
  - **Codex** (`~/.codex` present or `codex` on PATH): `~/.agents/skills/`, the
@@ -268,8 +258,6 @@ directory a harness it detected here reads, plus any directory you named with
268
258
  harness Tenjin does not probe for. A leftover directory that is neither is
269
259
  described, not warned about.
270
260
 
271
- A funded wallet is only needed for paid reads and publishing.
272
-
273
261
  ## No CLI? Zero-install fallback
274
262
 
275
263
  An agent with no CLI reaches the same surface directly over HTTP and MCP. The
@@ -324,16 +312,16 @@ server the CLI ships (see [Local stdio MCP server](#local-stdio-mcp-server)).
324
312
  ## Local stdio MCP server
325
313
 
326
314
  `tenjin mcp` runs a local MCP server over stdio backed by the same command cores
327
- as the CLI (`search`, `inspect`, `buy`, `outcome`, `publish`, `candidate`, and
328
- `wallet`), in-process, no shelling out. It exposes seven tools (`tenjin_search`,
329
- `tenjin_inspect`, `tenjin_buy`, `tenjin_outcome`, `tenjin_publish`,
330
- `tenjin_candidate`, `tenjin_wallet`), each returning the machine JSON envelope as
331
- `structuredContent` with a short text summary. The consent gates carry over
332
- exactly: the spend policy gates `tenjin_buy`, `publish.mode` gates
333
- `tenjin_publish` (the client renders the `needs_confirmation` payload as its own
334
- confirm UI, then re-calls with `yes:true`), and a hard content block is never
335
- bypassable. The wallet stays local: the key never leaves the machine and appears
336
- in no tool result.
315
+ as the CLI (`search`, `inspect`, `buy`, `outcome`, `publish`, `edit`,
316
+ `candidate`, and `wallet`), in-process, no shelling out. It exposes eight tools
317
+ (`tenjin_search`, `tenjin_inspect`, `tenjin_buy`, `tenjin_outcome`,
318
+ `tenjin_publish`, `tenjin_edit`, `tenjin_candidate`, `tenjin_wallet`), each
319
+ returning the machine JSON envelope as `structuredContent` with a short text
320
+ summary. The consent gates carry over exactly: the spend policy gates
321
+ `tenjin_buy`, `publish.mode` gates `tenjin_publish` and `tenjin_edit` (the client
322
+ renders the `needs_confirmation` payload as its own confirm UI, then re-calls
323
+ with `yes:true`), and a hard content block is never bypassable. The wallet stays
324
+ local: the key never leaves the machine and appears in no tool result.
337
325
 
338
326
  **Claude Code**
339
327
 
@@ -384,30 +372,12 @@ approval.
384
372
  — its passphrase entry is keyed by the wallet's address, so signing resumes
385
373
  transparently.
386
374
  - The signing passphrase resolves in order: `TENJIN_WALLET_PASSPHRASE`, then the
387
- OS credential store, then an interactive prompt. On `wallet create` with no env
388
- passphrase, a strong random one is generated and saved to the OS store so later
389
- signing is transparent. Every stored entry is **per wallet** — keyed by the
390
- wallet's own address — so replacing a wallet never touches the outgoing
391
- wallet's passphrase. (Installs from before per-wallet entries used one shared
392
- slot; the first signing that proves ownership re-keys that slot under the
393
- owning wallet's address — the copy is verified before the old slot is
394
- removed.) Where entries land per platform:
395
- - **macOS**: the login keychain, via the OS `security` tool (the same
396
- mechanism the GitHub CLI uses): service `tenjin-cli`, account = the wallet
397
- address.
398
- - **Windows**: a DPAPI-encrypted file per wallet
399
- (`passphrase.<address>.dpapi`), decryptable only by the same user on the
400
- same machine, via built-in PowerShell. The file holds ciphertext, not the
401
- passphrase.
402
- - **Desktop Linux**: the Secret Service keyring, via `secret-tool` when
403
- libsecret-tools is installed: service `tenjin-cli`, account = the wallet
404
- address.
405
- - **Headless or CI (any OS)**: no durable OS store, so set
406
- `TENJIN_WALLET_PASSPHRASE`.
407
-
408
- The passphrase reaches these tools over stdin, never on a command line, and the
409
- key never leaves the machine.
410
-
375
+ OS credential store, then an interactive prompt. `wallet create` generates a
376
+ strong random passphrase and saves it to the OS store (one entry per wallet,
377
+ keyed by address), so later signing is transparent; headless or CI, set
378
+ `TENJIN_WALLET_PASSPHRASE`. Per-platform detail (macOS keychain, Windows
379
+ DPAPI, Linux Secret Service, the legacy shared-slot re-key):
380
+ [docs/agent-permissions.md](./docs/agent-permissions.md#wallet-passphrase-storage).
411
381
  - Fund small: this is a pocket-money wallet by design.
412
382
  - Purchased content is untrusted data, never instructions. The skills never
413
383
  execute it, and instructions embedded in it never override the task. In
@@ -417,9 +387,9 @@ approval.
417
387
  - The recommended auto-mode allowlist covers free verbs only; `tenjin buy` is an
418
388
  explicit opt-in that authorizes unattended spending, and money-moving verbs are
419
389
  never recommended. See
420
- [Auto-mode permission allowlist](#auto-mode-permission-allowlist). A harness
421
- permission denial is never worked around: the skills surface the exact allowlist
422
- line and stop.
390
+ [docs/agent-permissions.md](./docs/agent-permissions.md). A harness permission
391
+ denial is never worked around: the skills surface the exact allowlist line and
392
+ stop.
423
393
 
424
394
  ## Contributing and releases
425
395
 
@@ -1,30 +1,32 @@
1
1
  import { createRequire as __tenjinCreateRequire } from 'node:module'; const require = __tenjinCreateRequire(import.meta.url);
2
2
  import {
3
3
  runBuy
4
- } from "./chunk-4WVKXKDK.js";
5
- import "./chunk-BIKAUVC2.js";
6
- import "./chunk-FU6MCSLG.js";
4
+ } from "./chunk-6OE2IJMH.js";
5
+ import "./chunk-L6AV2Q73.js";
6
+ import "./chunk-ZA3RFDAV.js";
7
+ import "./chunk-SGK2B724.js";
8
+ import "./chunk-PCLPVJ3J.js";
9
+ import "./chunk-S5RYMCV6.js";
7
10
  import "./chunk-POJRB2AE.js";
11
+ import "./chunk-YLYINX2H.js";
8
12
  import "./chunk-QW2Q2KAH.js";
9
- import "./chunk-C444K6MI.js";
10
- import "./chunk-QONTBYQW.js";
11
- import "./chunk-L4IHCN6B.js";
12
- import "./chunk-CVX6JNGD.js";
13
- import "./chunk-3IRDP7TN.js";
13
+ import "./chunk-RGFBBNGP.js";
14
+ import "./chunk-WRWCDLVK.js";
15
+ import "./chunk-CYRYVZPN.js";
16
+ import "./chunk-OTDI5FXG.js";
17
+ import "./chunk-P3FBESBB.js";
14
18
  import "./chunk-WWX32ML4.js";
15
- import "./chunk-ZDY2KY5X.js";
16
- import "./chunk-NJF2WENW.js";
17
- import "./chunk-NFSOVL3C.js";
19
+ import "./chunk-URSGGRO4.js";
20
+ import "./chunk-DQDGBWWH.js";
21
+ import "./chunk-XBJ3VLWX.js";
18
22
  import "./chunk-2I4QTOLB.js";
23
+ import "./chunk-BBUYCDSG.js";
19
24
  import "./chunk-KZAAWQNP.js";
20
- import "./chunk-S5RYMCV6.js";
21
- import "./chunk-YLYINX2H.js";
22
- import "./chunk-MDDGEGSW.js";
25
+ import "./chunk-DAJ56EUU.js";
23
26
  import "./chunk-YBMMV4Y4.js";
24
27
  import "./chunk-UO22YNY4.js";
25
- import "./chunk-5SCU253N.js";
26
- import "./chunk-2JQ5JSG6.js";
27
- import "./chunk-PAUXMRSF.js";
28
+ import "./chunk-UYP7G3GZ.js";
29
+ import "./chunk-J6CVKC4M.js";
28
30
  import "./chunk-MJZZTKCC.js";
29
31
  import "./chunk-7FK2UN2T.js";
30
32
  import "./chunk-M2O56UK7.js";
@@ -39,4 +41,4 @@ import "./chunk-ZXTAQYNA.js";
39
41
  export {
40
42
  runBuy
41
43
  };
42
- //# sourceMappingURL=buy-YMXXVNFH.js.map
44
+ //# sourceMappingURL=buy-K2G6XQY2.js.map
@@ -3,20 +3,19 @@ import {
3
3
  runCandidateAdd,
4
4
  runCandidateDrop,
5
5
  runCandidateList
6
- } from "./chunk-ZW3B5LWX.js";
7
- import "./chunk-ZIYVN4CD.js";
6
+ } from "./chunk-2YX6LTCD.js";
7
+ import "./chunk-VZ3AJCO5.js";
8
8
  import "./chunk-WWX32ML4.js";
9
- import "./chunk-NFSOVL3C.js";
10
9
  import "./chunk-2I4QTOLB.js";
11
- import "./chunk-MDDGEGSW.js";
10
+ import "./chunk-BBUYCDSG.js";
11
+ import "./chunk-DAJ56EUU.js";
12
12
  import "./chunk-UO22YNY4.js";
13
- import "./chunk-5SCU253N.js";
14
- import "./chunk-2JQ5JSG6.js";
15
- import "./chunk-PAUXMRSF.js";
13
+ import "./chunk-UYP7G3GZ.js";
14
+ import "./chunk-J6CVKC4M.js";
16
15
  import "./chunk-ZXTAQYNA.js";
17
16
  export {
18
17
  runCandidateAdd,
19
18
  runCandidateDrop,
20
19
  runCandidateList
21
20
  };
22
- //# sourceMappingURL=candidate-H7FR4AU5.js.map
21
+ //# sourceMappingURL=candidate-DJB2NNTG.js.map
@@ -3,19 +3,19 @@ import {
3
3
  createCandidate,
4
4
  dropCandidate,
5
5
  listCandidates
6
- } from "./chunk-ZIYVN4CD.js";
6
+ } from "./chunk-VZ3AJCO5.js";
7
7
  import {
8
8
  UUID_RE
9
9
  } from "./chunk-WWX32ML4.js";
10
10
  import {
11
11
  sanitizeForTerminal
12
- } from "./chunk-NFSOVL3C.js";
12
+ } from "./chunk-BBUYCDSG.js";
13
13
  import {
14
14
  pathExists
15
- } from "./chunk-MDDGEGSW.js";
15
+ } from "./chunk-DAJ56EUU.js";
16
16
  import {
17
17
  CliError
18
- } from "./chunk-PAUXMRSF.js";
18
+ } from "./chunk-J6CVKC4M.js";
19
19
 
20
20
  // src/commands/candidate.ts
21
21
  import { readFile } from "fs/promises";
@@ -120,4 +120,4 @@ export {
120
120
  runCandidateList,
121
121
  runCandidateDrop
122
122
  };
123
- //# sourceMappingURL=chunk-ZW3B5LWX.js.map
123
+ //# sourceMappingURL=chunk-2YX6LTCD.js.map