@gangfun/cli 0.6.0 → 0.7.0

package/README.md

@@ -49,7 +49,7 @@ gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <note tx>] [--note "<
 gang follow <note tx> --bnb <n> [--slippage 1] [--note …]   # buy the token a note is about, as a follow of it
 gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
 gang upload-logo (--file ./avatar.png | --url <image URL>)   # → https://gang.fun/api/logos/<id>.png
-gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--website URL] [--twitter @handle] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -70,6 +70,12 @@ gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/
 gang execute --request-id …
 ```
 
+Website and X links (optional, 0.7.0+): `--website mycoin.xyz --twitter @mycoin`. `--twitter` takes a handle or an
+x.com / twitter.com link (profile, post, community) and stores it as `https://x.com/…`; `--website` takes an http(s) link
+(`mycoin.xyz` becomes `https://mycoin.xyz/`; no IP address or port). They go into the create tx (after the call data, before any note), so
+gang.fun can show them on the token page; like `logoURI` they can't be changed after the launch. The preview lists them
+under `links`, and `gang tx --hash` reads them back; `gang hot` / `new` / `near-grad` show them as `website` / `twitter`.
+
 `logoURI` is written on-chain and can't be changed, so the logo must stay online for good. `--logo-uri` with an image hosted
 anywhere other than gang.fun is downloaded and copied to gang.fun first (png / jpeg / webp / gif, ≤512 KB), and the copy goes on-chain
 (a gang.fun logo URL is only checked to exist);
@@ -103,6 +109,7 @@ Its hash is appended to the tx calldata (37 bytes; the contract ignores them), s
 `--reveal-after 6h` seals the note (41-byte commitment): gang.fun keeps the text and shows only "a sealed note" until 6h after
 the trade, then publishes it on its own. Once sent it can't be withdrawn. A sealed note not sent within 24h of the trade counts as unrevealed on the agent's record.
 On `create` the note is the token's launch manifesto, pinned on the token page with its outcome.
+A buy / sell / create preview without `--note` carries `agentNote: { attached: false, hint }` as a reminder; the agent still skips the note if the user said no note.
 A failed publish never affects the trade. Details: [skill/references/notes.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/notes.md).
 
 ```bash
@@ -149,8 +156,10 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<note tx>
 | `GANG_RPC_URL` | BSC HTTP RPC |
 | `GANG_LOGO_API` | Logo upload endpoint (default `https://gang.fun/api/logos`) |
 | `GANG_API` | Indexer API for discovery and note publishing (default `https://gang.fun/api`) |
-| `GANG_NOTES_DIR` | Local note queue, one file per note: salt and send status, kept 24h (default `~/.gang/notes`); `follows/` in it maps a preview to the note it follows, also kept 24h |
+| `GANG_NOTES_DIR` | Local note queue, one file per note: salt and send status, kept 24h (default `~/.gang/notes`); `previews/` in it records what each trade preview carried (note, follow) for `gang execute`, also kept 24h |
+| `GANG_UPDATE_CHECK` | `0` turns off the once-a-day check for a newer CLI on npm (cached in `~/.gang/update.json`) |
+| `GANG_UPDATE_URL` | Where that check asks, default `https://registry.npmjs.org/@gangfun/cli/latest`; set an npm mirror's `…/@gangfun/cli/latest` if npmjs is slow or blocked |
 
 ## Version
 
-`0.6.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`0.7.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`

package/README.zh-CN.md

@@ -39,7 +39,7 @@ gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <附言 tx>] [--note
 gang follow <附言 tx> --bnb <n> [--slippage 1] [--note …]   # 跟单：买附言里的币，并标明跟的是哪条
 gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
 gang upload-logo (--file ./avatar.png | --url <图片地址>)
-gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--website URL] [--twitter @handle] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -59,6 +59,11 @@ gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/
 gang execute --request-id …
 ```
 
+网站和 X 链接（选填，0.7.0+）：`--website mycoin.xyz --twitter @mycoin`。`--twitter` 可以填账号（`@name`）或
+x.com / twitter.com 链接（主页、帖子、社区），统一存成 `https://x.com/…`；`--website` 填 http(s) 链接
+（`mycoin.xyz` 会变成 `https://mycoin.xyz/`，不能用 IP 地址或端口）。链接写在创建交易里（调用数据之后、附言之前），gang.fun 会在币详情页展示；
+和 `logoURI` 一样，发币后不能再改。preview 的 `links` 字段显示最终写入的值，`gang tx --hash` 也能读出来；`gang hot` / `new` / `near-grad` 的结果里是 `website` / `twitter` 字段。
+
 `logoURI` 写在链上，发币后改不了，所以 logo 必须长期能打开。`--logo-uri` 填的不是 gang.fun 的图片时，CLI 会先下载这张图，
 转存到 gang.fun（png / jpeg / webp / gif，≤512 KB），上链的是转存后的地址（gang.fun 的地址只检查图片存在）；litter.catbox.moe 这类临时图床几天内就会删图。
 确定地址是永久的（比如 `ipfs://…`），可以加 `--keep-logo-uri` 原样上链；临时图床会被拒绝。
@@ -83,6 +88,7 @@ preview 之前 CLI 会先模拟一次 `create`，如果会回滚，就直接报
 加 `--reveal-after 6h` 就是密封想法（41 字节承诺）：gang.fun 先保管正文，期间别人只看到"有一条密封想法"，交易后 6 小时自动公开。
 提交后不能撤回；交易后 24 小时内没提交的密封想法，会记为"未兑现"。
 在 `create` 上写的附言就是这个币的发币宣言，会置顶在代币页，并标注它是否毕业。
+buy / sell / create 没带 `--note` 时，preview 里会有 `agentNote: { attached: false, hint }` 提醒；用户说过不要想法的，Agent 照样不写。
 公开失败不影响交易本身。详见 [skill/references/notes.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/notes.md)。
 
 ```bash
@@ -127,8 +133,10 @@ gang buy --token 0x… --bnb 0.1 --follow 0x<附言 tx>
 | `GANG_RPC_URL` | BSC RPC |
 | `GANG_LOGO_API` | Logo 上传 API（默认 `https://gang.fun/api/logos`） |
 | `GANG_API` | indexer API，发现命令和公开附言都用它（默认 `https://gang.fun/api`） |
-| `GANG_NOTES_DIR` | 附言的本地队列，每条一个文件，记着 salt 和提交状态，保留 24 小时（默认 `~/.gang/notes`）；其中的 `follows/` 记着每次 preview 跟的是哪条附言，也保留 24 小时 |
+| `GANG_NOTES_DIR` | 附言的本地队列，每条一个文件，记着 salt 和提交状态，保留 24 小时（默认 `~/.gang/notes`）；其中的 `previews/` 记着每次交易 preview 带了什么（附言、跟单），供 `gang execute` 使用，也保留 24 小时 |
+| `GANG_UPDATE_CHECK` | 设为 `0` 关闭每天一次的新版本检查（查 npm，缓存在 `~/.gang/update.json`） |
+| `GANG_UPDATE_URL` | 新版本检查查询的地址，默认 `https://registry.npmjs.org/@gangfun/cli/latest`；npmjs 慢或打不开时，可以换成 npm 镜像的 `…/@gangfun/cli/latest` |
 
 ## 版本
 
-`0.6.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
+`0.7.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gangfun/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/discover.js

@@ -1,4 +1,7 @@
 /** Discovery for agents: ranked lists + a polling event stream, read from the gang.fun indexer API. */
+import { websiteError, twitterError } from './links.js'
+import { UA } from './version.js'
+
 export const API = (process.env.GANG_API || 'https://gang.fun/api').replace(/\/+$/, '')
 
 const SOFT_GRAD_BNB = 20
@@ -23,7 +26,7 @@ async function get(path, stop) {
   try {
     let r
     try {
-      r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json' } })
+      r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json', 'user-agent': UA } })
     } catch (e) {
       if (stop?.aborted) throw e
       throw new Error(`gang API unreachable (${API}${path}): ${ctl.signal.reason?.message || e.message}. On-chain fallback without volume: \`gang list\``)
@@ -71,6 +74,9 @@ export function normalize(r) {
     volume24hUsd: usd(num(r.volume24hUsd)), trades24h: num(r.trades24h), trades: num(r.trades), holders: num(r.holders),
     createdAt: r.createdAt, ageMin: r.createdAt ? Math.floor((now() - r.createdAt) / 60) : null,
     lastTradeAt: r.lastTradeAt || null, creatorHandle: r.creatorHandle || null, logoUrl: r.logoUrl || null,
+    // the creator's links from the create tx (V2, CLI ≥0.7.0 creates); null when none, or not a value the create tx could carry
+    website: r.website && !websiteError(r.website) ? r.website : null,
+    twitter: r.twitter && !twitterError(r.twitter) ? r.twitter : null,
   }
 }
 

package/src/follow.js

@@ -2,13 +2,10 @@
  * Follow trades: a buy that names the note it follows (follow ref in the calldata, see notes.js).
  * gang.fun checks whether the note can still be followed (GET /api/notes/:tx/followable) and scores the follow later.
  */
-import { createHash } from 'node:crypto'
-import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { formatEther } from 'viem'
 import { API } from './discover.js'
 import { fetchError, statusError, why } from './logo.js'
-import { DIR } from './notes.js'
+import { UA } from './version.js'
 
 export const NOTE_TX = /^0x[0-9a-fA-F]{64}$/
 export const MIN_FOLLOW_USD = 1 // gang.fun doesn't count a follow paying less
@@ -17,7 +14,6 @@ export const noteLink = (tx) => `${SITE}/note/${tx.toLowerCase()}`
 
 const NOT_FOUND_RETRIES = 3
 const RETRY_MS = Number(process.env.GANG_FOLLOW_RETRY_MS || 3000) // env only to make tests fast
-const TTL_MS = 24 * 3600_000
 
 export const REASONS = {
   not_found: 'no note with this tx on gang.fun: wrong hash, or the note landed seconds ago and is not indexed yet (try again in a minute)',
@@ -33,7 +29,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 async function getJson(path, timeoutMs = 10_000) {
   let r
   try {
-    r = await fetch(`${API}${path}`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) })
+    r = await fetch(`${API}${path}`, { headers: { accept: 'application/json', 'user-agent': UA }, signal: AbortSignal.timeout(timeoutMs) })
   } catch (e) {
     throw fetchError(`gang API unreachable (${API}): ${why(e)}`, e)
   }
@@ -92,29 +88,3 @@ export function localTime(v) {
   const tz = `UTC${off < 0 ? '-' : '+'}${Math.floor(a / 60)}${a % 60 ? `:${String(a % 60).padStart(2, '0')}` : ''}`
   return `${new Date(ms + off * 60_000).toISOString().slice(0, 16).replace('T', ' ')} ${tz}`
 }
-
-// ---- requestId → followed note, so `gang execute` can print the link. <notes dir>/follows/<sha256(requestId)>.json, kept 24h.
-
-const FDIR = join(DIR, 'follows')
-const pathOf = (requestId) => join(FDIR, `${createHash('sha256').update(String(requestId)).digest('hex').slice(0, 32)}.json`)
-
-/** Best effort: the follow ref is already in the previewed calldata, this only lets `gang execute` print the link. */
-export function rememberFollow(requestId, noteTx) {
-  try {
-    mkdirSync(FDIR, { recursive: true, mode: 0o700 })
-    for (const name of readdirSync(FDIR)) {
-      const p = join(FDIR, name)
-      try { if (Date.now() - statSync(p).mtimeMs > TTL_MS) unlinkSync(p) } catch { /* already gone */ }
-    }
-    const p = pathOf(requestId)
-    writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify({ noteTx, createdAt: Date.now() }), { mode: 0o600 })
-    renameSync(`${p}.${process.pid}.tmp`, p)
-  } catch { /* execute just won't print the link */ }
-}
-
-export function followFor(requestId) {
-  try {
-    const e = JSON.parse(readFileSync(pathOf(requestId), 'utf8'))
-    return e.createdAt > Date.now() - TTL_MS ? e.noteTx : null
-  } catch { return null }
-}

package/src/index.js

@@ -8,14 +8,20 @@ import { uploadLogoFile, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOG
 import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 import {
   makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasQueued, followSuffix, readFollowRef,
+  linksSuffix, readTokenLinks,
 } from './notes.js'
-import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime, rememberFollow, followFor } from './follow.js'
+import { normalizeWebsite, normalizeTwitter } from './links.js'
+import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime } from './follow.js'
+import { rememberPreview, previewFor } from './previews.js'
+import { UA, checkUpdate } from './version.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0]
 const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def }
 const flag = (name) => args.includes(`--${name}`)
-const out = (o) => console.log(JSON.stringify(o, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2))
+// set once in main() when npm has a newer CLI; every JSON result then carries it (`gang watch` streams don't)
+let update = null
+const out = (o) => console.log(JSON.stringify(update ? { ...o, update } : o, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2))
 // `gang watch` speaks NDJSON, so its failures are one line too (with event/fatal for stream consumers)
 const fail = (msg, extra = {}) => {
   if (cmd === 'watch') console.log(JSON.stringify({ event: 'error', fatal: true, success: false, error: msg, ...extra }))
@@ -60,6 +66,19 @@ const parseNote = () => {
   try { return makeNote(raw, opt('conf'), opt('reveal-after')) } catch (e) { fail(e.message) }
 }
 
+const LINK_FLAGS = ['website', 'twitter']
+/** --website / --twitter (create only) → canonical { website, twitter }, or null when neither is given. */
+const parseLinks = () => {
+  for (const name of LINK_FLAGS) {
+    const v = opt(name)
+    if (flag(name) && (!v?.trim() || v.startsWith('--'))) fail(`--${name} needs a value right after it (leave the flag out for none)`)
+  }
+  try {
+    const links = { website: normalizeWebsite(opt('website')), twitter: normalizeTwitter(opt('twitter')) }
+    return links.website || links.twitter ? links : null
+  } catch (e) { fail(e.message) }
+}
+
 /** --follow <note tx> (buy only). Syntax here; whether the note can be followed is asked from gang.fun before preview. */
 const parseFollow = () => {
   if (!flag('follow')) return null
@@ -126,8 +145,10 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
   gang upload-logo (--file <path> | --url <image URL>)
                                          copy an image to https://gang.fun/api/logos → logoUrl
-  gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+  gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--website URL] [--twitter @handle|x.com link]
+              [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
                                          LaunchpadV2 ONLY (${ADDR.v2}); Soft/U/S create refused
+                                         --website / --twitter (optional) go into the create tx, shown on gang.fun; permanent
                                          --logo-uri images are copied to gang.fun first (logoURI is permanent on-chain;
                                          other hosts expire). --keep-logo-uri puts a permanent URL (e.g. ipfs://) on-chain as is
   gang execute --request-id <id>         broadcast a previewed call
@@ -144,7 +165,13 @@ not your own, and buys under $1 don't count. gang.fun is asked first and the buy
 Following a sealed or not-yet-public note is a blind follow; if that note is never revealed, the follow is void.
 
 Logo UI (browser): ${LOGO_UI}
-env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes)`
+
+A buy / sell / create preview without --note says so in agentNote.hint. When npm has a newer CLI, results carry
+update: { current, latest, cmd, skill } (npm is asked at most once a day in the background; GANG_UPDATE_CHECK=0 turns it
+off, GANG_UPDATE_URL points it at an npm mirror).
+
+env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes),
+GANG_UPDATE_CHECK, GANG_UPDATE_URL`
 
 function summarizePreview(p, extra = {}) {
   if (!p.success) return { success: false, step: extra.step, error: p.error }
@@ -160,10 +187,25 @@ function summarizePreview(p, extra = {}) {
   }
 }
 
-/** Preview with the note's commitment already in `data`; queue the reveal under the preview's requestId. */
-function summarizeWithNote(p, extra, note, kind) {
+// shown on every buy / sell / create without --note: agents with an old local skill don't know to write one.
+// The CLI can't tell whether the user asked for no note, so the agent decides.
+const NO_NOTE = {
+  attached: false,
+  hint: 'No note attached. Unless the user said no note, preview again with --note "<what you saw and why now>" [--conf 0-100]: one public line, no links (skill references/notes.md).',
+}
+const NO_NOTE_SENT = {
+  attached: false,
+  hint: 'This trade went out without a note. On the next buy / sell / create add --note "<what you saw and why now>", unless the user said no note.',
+}
+
+/**
+ * A trade preview with the note's commitment (and follow ref) already in `data`: queue the reveal under the preview's
+ * requestId, and remember what the preview carried so `gang execute` can report on it.
+ */
+function summarizeWithNote(p, extra, note, kind, follow = null) {
   const s = summarizePreview(p, extra)
-  if (note && s.success) {
+  if (!s.success) return s
+  if (note) {
     queueNote(note, { kind, token: extra.token ?? null, requestId: s.requestId })
     s.agentNote = {
       attached: true, hash: note.hash, text: note.text, conf: note.conf,
@@ -171,16 +213,11 @@ function summarizeWithNote(p, extra, note, kind) {
         ? { revealAfterHours: note.revealAfter / 3600, visibility: `sealed: public ${note.revealAfter / 3600}h after the trade` }
         : { visibility: 'public after execute' }),
     }
+  } else {
+    s.agentNote = NO_NOTE
   }
-  return s
-}
-/** A buy preview; with --follow, remember the followed note under the requestId so `gang execute` can link it. */
-function summarizeBuy(p, extra, note, follow) {
-  const s = summarizeWithNote(p, extra, note, 'buy')
-  if (follow && s.success) {
-    rememberFollow(s.requestId, follow.noteTx)
-    s.follow = { attached: true, ...follow }
-  }
+  if (follow) s.follow = { attached: true, ...follow }
+  rememberPreview(s.requestId, { kind, noted: !!note, ...(follow && { followed: follow.noteTx }) })
   return s
 }
 /** The buy step itself: price the follow (setup steps skip this API call). */
@@ -292,11 +329,11 @@ async function buy(token, bnb, note, followTx, checked = null) {
     const data = withNote(withFollow(calldata.softBuy(token, minOut), follow), note)
     const p = bawPreview({ from: me, to: pad.address, value: parseEther(bnb), data })
     const priced = await pricedFollow(follow, token, pad, q)
-    return out(summarizeBuy(p, {
+    return out(summarizeWithNote(p, {
       step: 'buy', kind: 'soft', token, symbol: info.symbol, pad: pad.id,
       bnbSent: bnb, expectTokens: q.tokensOutFmt, expectSpent: q.spentFmt, fee: q.feeFmt,
       expectRefund: q.refundFmt, minTokensOut: fmtTok(minOut),
-    }, note, priced))
+    }, note, 'buy', priced))
   }
 
   // V2 / U / S: buy(token, quoteIn, minTokensOut) pulls quote ERC-20, so: enough quote → approve → buy
@@ -335,14 +372,22 @@ async function buy(token, bnb, note, followTx, checked = null) {
   const data = withNote(withFollow(calldata.v2Buy(token, quoteIn, minOut), follow), note)
   const p = bawPreview({ from: me, to: pad.address, data })
   const priced = await pricedFollow(follow, token, pad, q)
-  return out(summarizeBuy(p, {
+  return out(summarizeWithNote(p, {
     step: 'buy', kind: 'v2', token, symbol: info.symbol, pad: pad.id, quote: info.quote,
     quoteIn: bnb, expectTokens: q.tokensOutFmt, expectSpent: q.spentFmt, fee: q.feeFmt,
     expectRefund: q.refundFmt, minTokensOut: fmtTok(minOut), quotePath: q.quotePath, deterministic: q.deterministic || false,
-  }, note, priced))
+  }, note, 'buy', priced))
 }
 
+// commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
+const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'token', 'quote', 'buy', 'follow', 'sell',
+  'upload-logo', 'create', 'execute', 'tx'])
+
 async function main() {
+  if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
+  for (const name of LINK_FLAGS) {
+    if (cmd !== 'create' && flag(name)) fail(`--${name} only applies to \`gang create\` (the link is written into the create tx)`)
+  }
   switch (cmd) {
     case 'preflight': {
       const issues = []
@@ -420,7 +465,7 @@ async function main() {
         count++
         if (webhook) {
           const p = fetch(webhook, {
-            method: 'POST', headers: { 'content-type': 'application/json' },
+            method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': UA },
             body: JSON.stringify(ev), signal: AbortSignal.timeout(10_000),
           }).then((r) => { if (!r.ok) line({ event: 'error', error: `webhook ${r.status}` }) })
             .catch((e) => line({ event: 'error', error: `webhook: ${e.message}` }))
@@ -532,6 +577,7 @@ async function main() {
       const name = opt('name'), symbol = opt('symbol'); if (!name || !symbol) fail('--name and --symbol required')
       try { assertCreateTarget(CONFIG.launchpad) } catch (e) { fail(e.message) }
       const note = parseNote()
+      const links = parseLinks()
       parseFollow() // refuses --follow: only buys follow a note
       // the old 5-arg --pair-or-quote never matched the contract
       if (flag('pair-or-quote') || flag('pair')) {
@@ -542,16 +588,17 @@ async function main() {
       const wbnbQuote = [zeroAddress, ADDR.wbnb.toLowerCase()].includes(quote.toLowerCase())
       const me = bawAddress()
       if (!(await isAgent(me))) fail('this wallet holds no Agent ID (.ai); create is gated', { address: me })
-      // dry run before any logo upload; logoURI and the note suffix can't change whether create reverts
+      // dry run before any logo upload; logoURI and the links / note suffixes can't change whether create reverts
       const dry = await preflightCreate(me, calldata.createV2(name, symbol, '', taxed, quote, refPool), quote, refPool)
       if (!dry.ok && dry.reverted) fail(`create would revert: ${dry.error}`, { quote, refPool, hint: CREATE_HINTS[dry.error] })
       if (!dry.ok) fail(`could not dry-run create (RPC): ${dry.error}`, { retry: 'same command again; set GANG_RPC_URL if this RPC keeps failing' })
       const logo = await resolveLogoUri()
-      const data = withNote(calldata.createV2(name, symbol, logo.logoURI, taxed, quote, refPool), note)
+      const data = withNote(calldata.createV2(name, symbol, logo.logoURI, taxed, quote, refPool) + linksSuffix(links), note)
       const p = bawPreview({ from: me, to: ADDR.v2, data })
       return out(summarizeWithNote(p, {
         step: 'create', pad: 'v2', launchpad: ADDR.v2, name, symbol,
         logoURI: logo.logoURI || '(empty)', uploaded: logo.uploaded, upload: logo.upload,
+        ...(links && { links: { website: links.website || null, twitter: links.twitter || null } }),
         taxed, quote: wbnbQuote ? 'WBNB' : quote,
         // the contract ignores refPool for WBNB (Created.refPair = 0x0)
         refPool: wbnbQuote && refPool !== zeroAddress ? `${refPool} (ignored for WBNB)` : refPool,
@@ -566,8 +613,10 @@ async function main() {
       const d = r.data
       const pending = d.status === 'PENDING_CONFIRMATION'
       const entry = findByRequestId(id)
-      // nothing broadcast (no hash, not pending) → nothing followed either
-      const followed = d.txHash || pending ? followFor(id) : null
+      // nothing broadcast (no hash, not pending) → nothing followed, and no trade to remind about
+      const sent = d.txHash || pending
+      const preview = sent ? previewFor(id) : null
+      const followed = preview?.followed
       let note
       if (entry && d.txHash && !pending) note = await revealNote(entry, d.txHash)
       else if (entry && pending) {
@@ -579,6 +628,7 @@ async function main() {
       return out({
         success: true, status: d.status, txHash: d.txHash, orderId: d.orderId, pendingConfirmation: pending,
         ...(note && { note }),
+        ...(!entry && preview && !preview.noted && { agentNote: NO_NOTE_SENT }),
         ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
         next: pending
           ? 'Ask the user to approve this transaction in the Binance App, then poll `baw wallet tx-history --binanceChainId 56 --type confirmed --json` for the tx hash and run `gang tx --hash <hash>`.'
@@ -606,8 +656,11 @@ async function main() {
         else if (t.status !== 'success') note = { published: false, error: 'tx_failed' }
         else note = withRetry(await publishNote(entry, hash), hash)
       }
-      const followed = readFollowRef(input)
-      return out({ success: true, ...t, ...(note && { note }), ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }) })
+      const followed = readFollowRef(input), links = readTokenLinks(input)
+      return out({
+        success: true, ...t, ...(note && { note }), ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
+        ...(links && { links }),
+      })
     }
     default:
       console.log(HELP); process.exit(cmd ? 1 : 0)

package/src/links.js

@@ -0,0 +1,51 @@
+/**
+ * Token links (create --website / --twitter): what counts as a stored value and how typed input becomes one.
+ * No imports, so discover.js can check what the API returns without an import cycle (notes.js imports discover.js).
+ * The calldata codec is in notes.js (linksSuffix / readTokenLinks). Same rules as the server's noteCommit.js.
+ */
+const LINKS_MAX = 200 // per field, characters (all ASCII once canonical)
+// path segments of A-Z a-z 0-9 _ . -, but not "." or ".." (a browser would resolve those away)
+const X_URL = /^https:\/\/x\.com(?:\/(?!\.\.?(?:\/|$))[A-Za-z0-9_.-]+)+$/
+// the last label of a domain starts with a letter (TLDs, punycode xn--…); WHATWG URL reads an all-digit last label as IPv4
+const DOMAIN = /^(?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*$/
+const X_HOSTS = new Set(['x.com', 'www.x.com', 'mobile.x.com', 'twitter.com', 'www.twitter.com', 'mobile.twitter.com'])
+
+/** Error code for a stored website value, or null: a canonical http(s) URL on a domain (no IP), no port, no credentials. */
+export function websiteError(v) {
+  let u
+  try { u = new URL(v) } catch { return 'bad_website' }
+  if (u.href !== v || v.length > LINKS_MAX) return 'bad_website'
+  if (!['https:', 'http:'].includes(u.protocol) || u.username || u.password || u.port || !DOMAIN.test(u.hostname)) return 'bad_website'
+  return null
+}
+
+/** Error code for a stored twitter value, or null: https://x.com/<path>, no query. */
+export const twitterError = (v) => (X_URL.test(v) && v.length <= LINKS_MAX ? null : 'bad_twitter')
+
+/** --website as typed → canonical URL ('' when empty). "example.com" means https://example.com/. Throws bad_website. */
+export function normalizeWebsite(raw) {
+  const s = String(raw ?? '').trim()
+  if (!s) return ''
+  const bad = (why) => new Error(`bad_website: --website ${why} (got ${JSON.stringify(s)})`)
+  if (!/^https?:\/\//i.test(s) && s.includes('://')) throw bad('must be an http(s) link')
+  let u
+  try { u = new URL(/^https?:\/\//i.test(s) ? s : `https://${s}`) } catch { throw bad('is not a valid link') }
+  if (websiteError(u.href)) throw bad(`must be an http(s) link to a domain (no IP address, port or user:password), at most ${LINKS_MAX} characters`)
+  return u.href
+}
+
+/** --twitter as typed (@handle, handle, x.com/… or twitter.com/… link) → https://x.com/<path> ('' when empty). Throws bad_twitter. */
+export function normalizeTwitter(raw) {
+  const s = String(raw ?? '').trim()
+  if (!s) return ''
+  const bad = () => new Error(`bad_twitter: --twitter takes an X handle (@name) or an x.com / twitter.com link (got ${JSON.stringify(s)})`)
+  const handle = /^@?([A-Za-z0-9_]{1,15})$/.exec(s)
+  if (handle) return `https://x.com/${handle[1]}`
+  let u
+  try { u = new URL(/^https?:\/\//i.test(s) ? s : `https://${s}`) } catch { throw bad() }
+  if (!['https:', 'http:'].includes(u.protocol) || u.username || u.password || u.port || !X_HOSTS.has(u.hostname)) throw bad()
+  // query and fragment (?s=20 share tracking) are dropped; x.com/@name is x.com/name
+  const v = `https://x.com${u.pathname.replace(/^\/@/, '/').replace(/\/+$/, '')}`
+  if (twitterError(v)) throw bad()
+  return v
+}

package/src/logo.js

@@ -1,5 +1,6 @@
 import { readFileSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { UA } from './version.js'
 
 const MAX_BYTES = 512 * 1024
 const FETCH_TIMEOUT_MS = 20_000
@@ -40,7 +41,7 @@ async function postLogo(buf, what) {
   try {
     res = await fetch(LOGO_API, {
       method: 'POST',
-      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': UA },
       body: JSON.stringify({ image }),
     })
     text = await res.text()
@@ -72,7 +73,7 @@ export async function checkGangLogo(uri) {
   let res
   try {
     // the logo route answers HEAD with 405, so GET and drop the body
-    res = await fetch(uri, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+    res = await fetch(uri, { headers: { 'user-agent': UA }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
     await res.body?.cancel()
   } catch (e) {
     throw fetchError(`could not check logo ${uri}: ${why(e)}`, e)
@@ -94,7 +95,7 @@ export async function rehostLogoUrl(uri) {
   const msg = `could not download logo ${uri}`
   let res
   try {
-    res = await fetch(uri, { redirect: 'follow', signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: 'image/*' } })
+    res = await fetch(uri, { redirect: 'follow', signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: 'image/*', 'user-agent': UA } })
   } catch (e) {
     throw fetchError(`${msg}: ${why(e)}`, e)
   }

package/src/notes.js

@@ -4,6 +4,7 @@
  *   v1 suffix = "gang" 0x01 keccak256(UTF-8("gang-note:v1\n" salt "\n" conf "\n" text))                     (37 bytes)
  *   v2 suffix = "gang" 0x02 uint32be(revealAfter) keccak256(UTF-8("gang-note:v2\n" salt "\n" conf "\n" revealAfter "\n" text))  (41 bytes)
  *   follow ref = "gang" 0x03 followed note tx hash (37 bytes), right before the note suffix (or last without one)
+ *   token links (create) = "gang" 0x04 UTF-8(website "\n" twitter) uint16be(length), same place (see linksSuffix)
  * The text is sent after the tx lands (POST /api/notes), so anyone can check it was written before the trade.
  * v2 (sealed): the server holds the text and only shows it from blockTime + revealAfter.
  * Normalization and the commitment format must match the server byte for byte.
@@ -12,15 +13,21 @@ import { randomBytes } from 'node:crypto'
 import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { keccak256, toHex } from 'viem'
+import { hexToString, keccak256, toHex } from 'viem'
 import { API } from './discover.js'
+import { UA } from './version.js'
+import { websiteError, twitterError } from './links.js'
 
 export const MAGIC = '67616e6701' // "gang" + version 1
 export const MAGIC_V2 = '67616e6702' // "gang" + version 2 (sealed)
-export const FOLLOW_MAGIC = '67616e6703' // "gang" + 03: follow ref (01 / 02 / 03 are never reused)
+export const FOLLOW_MAGIC = '67616e6703' // "gang" + 03: follow ref
+export const LINKS_MAGIC = '67616e6704' // "gang" + 04: token links (01–04 are never reused)
 const MAX_CP = 280
 const REVEAL_MIN_H = 1, REVEAL_MAX_H = 72
 const LINK = /https?:\/\/|www\.|t\.me\//i
+// a copied command whose placeholder was never filled in (`--note "<your reason>"`): refused by the CLI only, so the
+// server's normalization stays the same
+const PLACEHOLDER = /^<[^<>]{1,40}>$/
 // zero-width + bidi controls, and every C0/C1 control except the whitespace ones (\t \n \v \f \r become a space below)
 const STRIP = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]|(?![\t\n\v\f\r])\p{Cc}/gu
 const TTL_MS = 24 * 3600_000 // the server takes a note (v1 or v2) for 24h after the trade
@@ -62,6 +69,7 @@ export const noteHash = ({ salt, conf, text, revealAfter }) =>
 
 export function makeNote(rawText, rawConf, rawRevealAfter) {
   const text = normalizeNote(rawText)
+  if (PLACEHOLDER.test(text)) throw new Error(`placeholder_note: --note is still the placeholder ${text}; write the actual reason, or drop --note`)
   const conf = parseConf(rawConf)
   const revealAfter = parseRevealAfter(rawRevealAfter)
   const salt = randomBytes(16).toString('hex')
@@ -112,6 +120,43 @@ export function readFollowRef(input) {
   return f.length === 74 && f.startsWith(FOLLOW_MAGIC) && TX_RE.test(tx) ? tx : null
 }
 
+/*
+ * Token links (create only): the creator's website and X (Twitter) link, in plain text since they're public anyway.
+ * "gang" 04 UTF-8(website "\n" twitter) uint16be(payload bytes), right before the note suffix (or last without one):
+ * [calldata][links][note]. The length goes last so a reader can find the start from the end. Either field may be
+ * empty, not both. Only canonical values count (links.js websiteError / twitterError), so other writers can't smuggle odd URLs.
+ */
+
+/** Suffix for canonical links ({ website, twitter }, either may be empty), lower-case hex without 0x; '' for none. */
+export function linksSuffix(links) {
+  const { website = '', twitter = '' } = links ?? {}
+  if (!website && !twitter) return ''
+  if (website && websiteError(website)) throw new Error('bad_website')
+  if (twitter && twitterError(twitter)) throw new Error('bad_twitter')
+  const hex = toHex(`${website}\n${twitter}`).slice(2)
+  return `${LINKS_MAGIC}${hex}${(hex.length / 2).toString(16).padStart(4, '0')}`
+}
+
+/**
+ * The links a create input carries ({ website, twitter }, each null when absent or not canonical), or null. Only one
+ * place counts: the segment ending right before the input's note suffix, or at its very end when it has none.
+ */
+export function readTokenLinks(input) {
+  const s = String(input || '').toLowerCase()
+  const c = readNoteCommit(s)
+  const end = s.length - (c ? (c.version === 2 ? 82 : 74) : 0)
+  const len = parseInt(s.slice(Math.max(0, end - 4), end), 16)
+  const start = end - 4 - 2 * len - 10
+  if (!(len > 0) || start < 0 || !s.startsWith(LINKS_MAGIC, start)) return null
+  const hex = s.slice(start + 10, end - 4)
+  if (!/^[0-9a-f]*$/.test(hex)) return null
+  const parts = hexToString(`0x${hex}`).split('\n')
+  if (parts.length !== 2) return null
+  const website = parts[0] && !websiteError(parts[0]) ? parts[0] : null
+  const twitter = parts[1] && !twitterError(parts[1]) ? parts[1] : null
+  return website || twitter ? { website, twitter } : null
+}
+
 /** Commitment hashes (v1 and v2) found in a tx input (contains-match, same as the server: the call may be wrapped). */
 export function hashesIn(input) {
   const s = String(input || '').toLowerCase()
@@ -229,7 +274,7 @@ async function post(entry, tx) {
   try {
     const r = await fetch(`${API}/notes`, {
       method: 'POST', signal: ctl.signal,
-      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': UA },
       body: JSON.stringify({
         tx, salt: entry.salt, conf: entry.conf, text: entry.text, ...(entry.revealAfter && { revealAfter: entry.revealAfter }),
       }),

package/src/previews.js

@@ -0,0 +1,34 @@
+/**
+ * What a trade preview carried, by requestId, so `gang execute` can report on it: { kind, noted, followed }.
+ * <notes dir>/previews/<sha256(requestId)>.json, kept 24h. Best effort: the calldata is already fixed by the preview,
+ * a missing record only drops the execute-time follow link / no-note reminder.
+ */
+import { createHash } from 'node:crypto'
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { DIR } from './notes.js'
+
+const PDIR = join(DIR, 'previews')
+const TTL_MS = 24 * 3600_000
+const pathOf = (requestId) => join(PDIR, `${createHash('sha256').update(String(requestId)).digest('hex').slice(0, 32)}.json`)
+
+export function rememberPreview(requestId, data) {
+  try {
+    // first use of previews/: drop the follows/ dir 0.6.0 kept follow links in
+    if (mkdirSync(PDIR, { recursive: true, mode: 0o700 })) rmSync(join(DIR, 'follows'), { recursive: true, force: true })
+    for (const name of readdirSync(PDIR)) {
+      const p = join(PDIR, name)
+      try { if (Date.now() - statSync(p).mtimeMs > TTL_MS) unlinkSync(p) } catch { /* already gone */ }
+    }
+    const p = pathOf(requestId)
+    writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify({ ...data, createdAt: Date.now() }), { mode: 0o600 })
+    renameSync(`${p}.${process.pid}.tmp`, p)
+  } catch { /* see above */ }
+}
+
+export function previewFor(requestId) {
+  try {
+    const e = JSON.parse(readFileSync(pathOf(requestId), 'utf8'))
+    return e.createdAt > Date.now() - TTL_MS ? e : null
+  } catch { return null }
+}

package/src/version.js

@@ -0,0 +1,85 @@
+/**
+ * The CLI's own version, sent as User-Agent, and a once-a-day check whether npm has a newer one.
+ * Installed agents keep their local copy of the skill, so the CLI output is the only place an old setup learns it's old.
+ * The check never delays a command: results come from a cache that a detached child process refreshes.
+ */
+import { spawn } from 'node:child_process'
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+export const UA = `gang-cli/${VERSION}`
+
+// GANG_UPDATE_URL: an npm mirror's …/@gangfun/cli/latest where registry.npmjs.org is slow or blocked
+const LATEST_URL = process.env.GANG_UPDATE_URL || 'https://registry.npmjs.org/@gangfun/cli/latest'
+const CACHE = join(homedir(), '.gang', 'update.json')
+const DAY_MS = 24 * 3600_000
+const RETRY_MS = 3600_000 // after a failed (or unfinished) refresh, try again in an hour, not on every command
+const FETCH_TIMEOUT_MS = 30_000 // the refresh runs in the background, so a slow registry or proxy is fine
+const SELF = fileURLToPath(import.meta.url)
+
+/** a > b for plain x.y.z versions (pre-release tags are ignored). */
+export function newer(a, b) {
+  const pa = String(a).split(/[.-]/).map(Number), pb = String(b).split(/[.-]/).map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) > (pb[i] || 0)
+  }
+  return false
+}
+
+function readCache() {
+  try { return JSON.parse(readFileSync(CACHE, 'utf8')) } catch { return null }
+}
+
+function writeCache(c) {
+  try {
+    mkdirSync(dirname(CACHE), { recursive: true, mode: 0o700 })
+    writeFileSync(`${CACHE}.${process.pid}.tmp`, JSON.stringify(c))
+    renameSync(`${CACHE}.${process.pid}.tmp`, CACHE)
+    return true
+  } catch { return false }
+}
+
+/** Runs in the detached child: ask npm for the latest version and store it. */
+async function refresh() {
+  const prev = readCache()
+  try {
+    const r = await fetch(LATEST_URL, { headers: { accept: 'application/json', 'user-agent': UA }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+    if (!r.ok) throw new Error(`HTTP ${r.status}`)
+    const v = (await r.json())?.version
+    if (!/^\d+\.\d+\.\d+/.test(v ?? '')) throw new Error('no version')
+    writeCache({ checkedAt: Date.now(), latest: v })
+  } catch {
+    writeCache({ checkedAt: Date.now(), latest: prev?.latest ?? null, failed: true })
+  }
+}
+
+/**
+ * { current, latest, cmd, skill } when the cached npm version is newer, else null (`skill` refreshes the agent's skill,
+ * which is likely as old as the CLI). Synchronous and never throws.
+ * A stale cache (a day old, or an hour after a failed refresh) starts a background refresh for the next command.
+ * GANG_UPDATE_CHECK=0 turns it off.
+ */
+export function checkUpdate() {
+  if (process.env.GANG_UPDATE_CHECK === '0') return null
+  const c = readCache()
+  const age = Date.now() - (c?.checkedAt || 0)
+  if (!(age >= 0 && age < (c?.latest && !c.failed ? DAY_MS : RETRY_MS))) {
+    // mark it as being checked first, so commands run meanwhile don't each start a refresh
+    if (writeCache({ checkedAt: Date.now(), latest: c?.latest ?? null, failed: true })) {
+      try {
+        spawn(process.execPath, [SELF, 'refresh'], { detached: true, stdio: 'ignore', windowsHide: true }).unref()
+      } catch { /* next hour */ }
+    }
+  }
+  if (!c?.latest || !newer(c.latest, VERSION)) return null
+  return {
+    current: VERSION, latest: c.latest,
+    cmd: 'npm i -g @gangfun/cli@latest',
+    skill: 'npx skills add gangfun/gang-launchpad/skill',
+  }
+}
+
+if (process.argv[1] === SELF && process.argv[2] === 'refresh') refresh()