dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/mcp/assets/kb/entries/cabal-and-coordinated-launches.md

@@ -0,0 +1,28 @@
+---
+id: cabal-and-coordinated-launches
+title: Cabals: repeat co-buyers across launches and how dexterm would detect them
+tags:
+  - cabal
+  - coordination
+  - kol
+  - labels
+  - wallet-intelligence
+date: 2026-10-06
+confidence: low
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - dexterm research/data-firehose-inventory-2026-10-06.md §1f and §4 item 6 (no credible open label dataset; in-house labels from recorded history)
+  - dexterm ROADMAP.md pillar 2 and legal flag on wallet labelling accuracy
+  - dexterm SPEC.md §3.6 (Bundled %, Snipers definitions)
+---
+**Term.** In trench slang a *cabal* is a group (often KOLs, launch teams and their bots) that coordinates entries and exits across many tokens: they are early on each launch, promote it, and sell into the audience. It is a social claim about intent; on-chain it reduces to **the same wallets (or wallets funded from the same sources) appearing early on many launches that later dump**.
+
+**What is observable, and what dexterm can build (inventory §1f):** there is no credible open dataset of KOL/cabal wallets (GitHub search tops out at 7 stars; Nansen/Arkham/GMGN/Cielo are keyed or paid). The in-house path is: record every watched launch's first-N-slot buyers and their funding sources (Helius `getTransactionsForAddress`), store them, and score wallets on *early-entry rate*, *co-occurrence* with the same other wallets, and *realised PnL* of their exits. A "cabal candidate" is a cluster of wallets that co-occur early on ≥ k launches where the launches' later outcome was a dump. Thresholds and k are to be set from recorded history, not guessed.
+
+**Why confidence is low.** Until the local history recorder holds enough recorded launches to set the thresholds, this is a method, not a measurement. Co-occurrence also catches honest copy-traders and popular snipers. Mislabelling a real person's wallet as "cabal" is the labelling-accuracy legal flag in ROADMAP (counsel before anything public); inside dexterm labels are **private, evidence-linked and reversible** (`WalletLabel.evidence[]`).
+
+**Judgement (maintainers, reviewed 2026-10-15):** the useful trader signal is not "cabal yes/no" but "who holds the early float and what did those wallets do last time". Case files with verified outcomes (see `case_lookup`) are where this becomes checkable.
+
+**Rule:** never assert that a specific wallet is a cabal member from memory or from a KB entry; only from a label record with evidence returned by a tool.

package/dist/packages/mcp/assets/kb/entries/common-rug-patterns.md

@@ -0,0 +1,40 @@
+---
+id: common-rug-patterns
+title: Common rug patterns mapped to checkable chain facts
+tags:
+  - rug
+  - rug-pull
+  - honeypot
+  - patterns
+  - checklist
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://spl.solana.com/token (authorities)
+  - https://spl.solana.com/token-2022/extensions (default account state, permanent delegate, transfer hook)
+  - https://github.com/pump-fun/pump-public-docs (creator fields, PumpSwap lp_supply)
+  - https://docs.meteora.ag/core-products/dbc/migration-and-liquidity.md (unlocked vs locked liquidity)
+  - https://www.metaplex.com/docs/smart-contracts/token-metadata (Is Mutable)
+  - dexterm SPEC.md §3.6 (forensics definitions)
+---
+Each pattern names the **mechanism**, the **chain fact that proves the capability exists**, and the dexterm field. A pattern is a capability, not an event: a token can have the capability and never use it.
+
+| Pattern | Mechanism | Checkable fact | dexterm field |
+|---|---|---|---|
+| **LP pull** | LP-token holder withdraws both vaults; price → 0 | LP tokens not burned/locked; locker expiry | `rugcheck.lpLockedPct`, `audit.lpLockedPct` |
+| **Freeze honeypot** | `FreezeAccount` on buyers' token accounts; only the deployer cluster can sell | `freezeAuthority` not null on the mint | `audit.freezeAuthority == true`, `rugcheck.risks` |
+| **Token-2022 honeypot** | default-frozen accounts, transfer hook that blocks sells, permanent delegate pulls tokens | extension present on the mint | `rugcheck.tokenProgram == Token-2022`, GoPlus flags |
+| **Mint-and-dump** | `MintTo` inflates supply into the pool | `mintAuthority` not null | `audit.mintAuthority == true` |
+| **Bundled launch dump** | deployer's wallets bought a large float atomically at create and sell into the first bid | same-slot buys funded from one source | `get_dev_history.bundledPct`, `get_holders.labelled.sniper` |
+| **Dev dump / slow rug** | creator or linked cluster distributes into strength | creator balance falling, transfers to fresh wallets | `audit.devPct`, `get_trades.devSells` |
+| **Serial launcher** | same creator, many dead mints | creator's prior mints and their outcomes | `get_dev_history.devHistory.{launches,rugged}` |
+| **Copycat ticker** | same symbol as a trending token; buyers hit the wrong mint | metadata symbol is not unique; mint is | `get_token` ambiguity → candidates (see `metadata-and-copycats`) |
+| **Metadata swap** | mutable metadata renamed/re-imaged after listing | `Is Mutable` on the Metaplex metadata account | GoPlus `metadata_mutable` (read by the data layer as `metadataMutable`) |
+| **Fake volume to trend** | wash trading to reach trending lists | few wallets dominate the tape | `get_trades.top2WalletVolumeSharePct`, organic score |
+
+**Reading order used by the `rug-check` skill:** authorities → token program/extensions → LP → concentration and clusters → creator history → tape. Stop early with AVOID on a freeze/mint authority or a Token-2022 honeypot extension; otherwise weigh the rest.
+
+**What this entry cannot say:** anything about a specific live token. The skill reads each field from a tool and cites the tool and data age.

package/dist/packages/mcp/assets/kb/entries/dbc-mechanics.md

@@ -0,0 +1,30 @@
+---
+id: dbc-mechanics
+title: Meteora Dynamic Bonding Curve (DBC) lifecycle and migration
+tags:
+  - meteora
+  - dbc
+  - bonding-curve
+  - migration
+  - damm-v2
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://docs.meteora.ag/core-products/dbc/what-is-dbc.md (retrieved 2026-09-30 into solana-launchpad/docs/meteora/dbc-overview.md)
+  - https://docs.meteora.ag/core-products/dbc/migration-and-liquidity.md (solana-launchpad/docs/meteora/dbc-migration.md)
+  - https://docs.meteora.ag/core-products/dbc/fees/rate-limiter.md (solana-launchpad/docs/meteora/dbc-rate-limiter.md)
+---
+**Program:** `dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN` (pool authority PDA `FhVo3mqL8PW5pH5U2CN4XE33DokiyZnUwuGpH2hmHLuM`). A *partner* (launchpad front end) or creator publishes a `PoolConfig` (curve shape with 1–16 segments, fee scheduler, migration settings, liquidity distribution); creators deploy a `VirtualPool` from it.
+
+**States:** `PreBondingCurve` (not yet tradeable) → `PostBondingCurve` (trading on the curve) → `MigrationOngoing` (quote threshold hit) → `CreatedPool` (DAMM v2 pool live). "Swaps are only possible in `PostBondingCurve`; migration is only possible after the quote threshold is reached."
+
+**Graduation:** when the pool's quote balance reaches `migration_quote_threshold`, a keeper (Meteora runs two: `Asi5DTGEeiso6k7ya6ndDabEZ7DRCgfTpCBLPH5E3aQs`, `DeQ8dPv6ReZNQ45NfiWwS5CchWpB2BVq1QMyNV8L2uSW`) or the manual migrator calls migrate. Standard-keeper thresholds are set per quote mint (10 SOL, 750 USDC as retrieved 2026-09-30; Meteora's migration docs list the other supported quote mints and their thresholds). New configs must migrate to **DAMM v2** (v1 deprecated); a **0.2 % protocol liquidity migration fee** is deducted; the DAMM v2 pool opens at the curve's final price.
+
+**Liquidity after migration:** split into unlocked / permanently locked / vesting positions per config; at least 10 % must be permanently locked on day 1 for the standard keeper to migrate (see `lp-burn-vs-lock`).
+
+**Anti-sniper design that existed and is now deprecated:** the *rate limiter* base-fee mode raised the fee with buy size during the first ≤ 12 h (`max_limiter_duration` ≤ 43,200 s) and "does not apply to sells". New configs use fee schedulers (linear/exponential decay) plus optional dynamic fees instead, so **early-buy fees on DBC launches are time-based, not size-based**, and a big first buy is not penalised unless the scheduler's starting fee is high.
+
+**Reading a DBC token in dexterm:** `launchpad == "dbc"` (Jupiter `met-dbc`, Gecko `meteora-dbc`). The config is per partner, so the *same* program hosts launches with very different fee and lock rules; the config address decides, and there is no public REST for DBC state (inventory §1b), so curve state is read on-chain.

package/dist/packages/mcp/assets/kb/entries/dev-wallet-behaviour.md

@@ -0,0 +1,33 @@
+---
+id: dev-wallet-behaviour
+title: Dev (creator) wallets: where the address comes from and what to watch
+tags:
+  - dev
+  - creator
+  - dev-wallet
+  - forensics
+  - creator-fees
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://github.com/pump-fun/pump-public-docs (BondingCurve.creator; PumpSwap Pool.coin_creator; holder rewards)
+  - https://developers.jup.ag/docs/tokens (retrieved 2026-09-30; audit fields devBalancePercentage, devMints, isSus)
+  - dexterm research/data-firehose-inventory-2026-10-06.md §1d (RugCheck new_tokens.creator)
+  - dexterm SPEC.md §3.6 (Dev % definition)
+---
+**Where "the dev" is defined on-chain.** On pump.fun the `BondingCurve.creator` field "accrues creator fees" and carries over to `PumpSwap Pool.coin_creator` after migration; the `create` instruction's signer is the deploying wallet. On Raydium LaunchLab the creator share of fees accrues to `creator_fees_quote`. On Meteora DBC the creator is the VirtualPool deployer. These are facts a tool reads; dexterm exposes them as `get_dev_history.creator`.
+
+**Derived signals.** Jupiter `audit.devBalancePercentage` (creator's share of supply) and `audit.devMints` (how many tokens this creator has launched) and `audit.isSus`; RugCheck `new_tokens.creator` for fresh mints. SPEC §3.6: **Dev % = creator wallet's current balance share plus linked wallets when clustering is available.**
+
+**Why creator fees change behaviour.** Since pump.fun and LaunchLab pay creators a share of every swap, a creator earns from *volume*, not only from selling supply. A creator who keeps zero supply but earns fees has an incentive to keep the token trading; a creator holding 15–20 % has the opposite option. With `is_holder_reward` set, the fee goes to holders instead, which removes that incentive from the creator.
+
+**Patterns worth a flag (maintainers, reviewed 2026-10-15):**
+- Creator has many prior mints (`devMints` high) and most are dead: serial launcher.
+- Creator balance falling while price rises: distribution into strength.
+- Creator transfers supply to fresh wallets before launch: shows as "bundled" or as many same-funded holders (see `holder-concentration`).
+- Creator sells to zero in the first hour: not always bad on pump.fun (fees still accrue), but the token is now "CTO or nothing".
+
+**Rule:** the creator address and its history are per-token facts. Read them from `get_dev_history`; never from memory.

package/dist/packages/mcp/assets/kb/entries/glossary.md

@@ -0,0 +1,35 @@
+---
+id: glossary
+title: Trench glossary (terms as dexterm uses them)
+tags:
+  - glossary
+  - terminology
+  - trenches
+  - slang
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - dexterm SPEC.md §3.3 (model), §3.6 (forensics definitions), §5.4 (verdict words)
+  - https://github.com/pump-fun/pump-public-docs (bonding curve, migrate, king of the hill fields)
+  - https://docs.meteora.ag/core-products/dbc/what-is-dbc.md (migration states)
+---
+Terms with the precise meaning dexterm attaches to them. Where a term is slang with no on-chain definition, that is said.
+
+- **Trenches**: the stream of brand-new launches (minutes old, tiny market cap). "Trench scan" = screening that stream.
+- **Bonding / on the curve**: a pump.fun, LaunchLab or DBC token still trading on its launch curve, before migration. **Bonding progress**: share of the curve's real token reserve sold.
+- **Graduation / migration / "bonded"**: the curve completed and a real AMM pool was created (PumpSwap, Raydium CPMM, DAMM v2). On pump.fun `migrate` is permissionless.
+- **KOTH (king of the hill)**: pump.fun's label for the curve token with the highest market cap at the moment; a UI concept, not a program state.
+- **Mcap vs FDV**: market cap uses circulating supply, FDV uses total supply. For a 1 B-supply memecoin with no locked supply they are equal; `pair.mcap` and `pair.fdv` are both carried.
+- **Dev**: the creator address (`BondingCurve.creator` / `coin_creator` / LaunchLab creator); **dev %** = its balance share plus linked wallets (SPEC §3.6).
+- **Sniper**: a wallet that bought in the first 3 blocks or first 2 s on a curve (SPEC §3.6). **Bundle / bundled %**: supply bought in the launch transaction or by wallets funded from one source within 60 s of launch.
+- **Rug / rug pull**: liquidity or supply mechanics used against holders (see `common-rug-patterns`); **soft rug / slow rug**: the creator cluster sells over time instead of pulling LP; **honeypot**: holders cannot sell (freeze authority, Token-2022 extension or hook).
+- **LP burned / locked**: see `lp-burn-vs-lock`. **Unlocked LP**: withdrawable by its holder now.
+- **Jeet** (slang): a holder who sells early into any strength; no on-chain definition. **Paper hands / diamond hands**: same, slang.
+- **CTO (community takeover)** (slang): the original creator is gone and holders promote the token; DexScreener has a `community-takeovers` endpoint that lists claimed CTOs.
+- **Moon bag** (slang): the remainder left after taking profit; in an order plan, the share excluded from the sell legs.
+- **Cabal** (slang): coordinated group early on many launches; see `cabal-and-coordinated-launches`.
+- **Organic score**: Jupiter's 0–100 genuineness score; see `wash-trading-fake-volume`.
+- **Verdict words (SPEC §5.4)**: **WATCH** (worth tracking, no disqualifier), **SPECULATIVE** (no disqualifier found, but material risks that the answer must state), **AVOID** (a disqualifier is present), plus **INSUFFICIENT_DATA** and **AMBIGUOUS** from the skill schema. None is a recommendation to buy or sell.

package/dist/packages/mcp/assets/kb/entries/holder-concentration.md

@@ -0,0 +1,30 @@
+---
+id: holder-concentration
+title: Holder concentration, top-10 share and funding-source clusters
+tags:
+  - holders
+  - top10
+  - concentration
+  - bubble-map
+  - clusters
+  - helius
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - dexterm SPEC.md §3.6 (Top 10 % excludes LP vault and known CEX/bridge addresses)
+  - https://spl.solana.com/token (RPC methods getTokenLargestAccounts, getTokenAccountsByOwner, getTokenSupply)
+  - https://www.helius.dev/docs/das-api (solana-launchpad/docs/helius/das-api.md; getTokenAccounts by mint)
+  - dexterm research/data-firehose-inventory-2026-10-06.md §2 (bubble map from getTransactionsForAddress)
+---
+**How the numbers are made.** The public RPC's `getTokenLargestAccounts` returns the 20 largest token accounts for a mint (it 429s on the public endpoint in practice); Helius DAS `getTokenAccounts` returns all holders paginated (64 ms per 100 in the inventory probe). A token account is not a person: the LP vault, CEX deposit wallets and bridges hold large balances that are not "one holder". **dexterm's Top-10 % excludes the LP vault and a static allow-list of CEX/bridge addresses** (SPEC §3.6); the tool reports `top10PctExLp`.
+
+**Clusters.** Several wallets funded from the same source (one wallet sending SOL to many fresh wallets shortly before they buy) behave as one holder. dexterm builds this from Helius `getTransactionsForAddress` (first SOL inflow per wallet) and shows it as a bubble map; the Forensics record's `bundledPct` is the same idea restricted to the launch window.
+
+**Thresholds in use (maintainers, reviewed 2026-10-15; rough heuristics, not measured facts):** top-10 ex-LP under ~20 % is broad; 20–35 % is common for a young token; above ~50 % a handful of holders (one group, if they are linked) can decide the exit. Combine with `labelled.dev` and `labelled.sniper` from `get_holders`: 30 % spread over 10 unrelated whales is a different risk from 30 % in one funded cluster.
+
+**What the count hides.** Holder count (`stats.holderCount`, Jupiter) can be inflated cheaply by airdropping dust to thousands of wallets; `holders24hDelta` plus organic score (`wash-trading-fake-volume`) separates growth from dusting.
+
+**Rule:** concentration numbers for a live token come from `get_holders`/`get_token.audit.top10Pct` with their `fetchedAt`; the KB only explains how to read them.

package/dist/packages/mcp/assets/kb/entries/jito-bundles.md

@@ -0,0 +1,29 @@
+---
+id: jito-bundles
+title: Jito bundles, tips, and what "bundled" means on a launch
+tags:
+  - jito
+  - bundle
+  - bundling
+  - tips
+  - sniping
+  - forensics
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://docs.jito.wtf/lowlatencytxnsend/ (retrieved 2026-10-01 into solana-launchpad/docs/jito/bundles.md)
+  - dexterm SPEC.md §3.6 (Bundled % definition)
+  - dexterm research/data-firehose-inventory-2026-10-06.md §1e (bundle contents not exposed by Jito)
+---
+**Mechanics.** A Jito bundle is "a group of up to 5 transactions that execute sequentially and atomically (all-or-nothing)", submitted to the Jito block engine (`sendBundle`) and landed by validators running Jito-Solana. A bundle pays a **tip** (minimum 1,000 lamports) to one of 8 tip accounts; "higher tips win the auction during congestion". `getBundleStatuses` returns the landed `slot`. The live tip floor is at `https://bundles.jito.wtf/api/v1/bundles/tip_floor`.
+
+**Why launches get "bundled".** Because a bundle is atomic and ordered, a deployer can put the `create` instruction and several `buy`s from different wallets into the same bundle: the token is created and a chosen share of supply is bought in the same slot before anyone else can trade. The buyers in that bundle look like separate wallets but were funded and signed by one operator.
+
+**What is and is not observable.** Jito does not publish bundle contents or membership, so "this was a Jito bundle" is not directly readable. What *is* on-chain: the slot and ordering of the first buys, and the funding history of each buying wallet. dexterm's definition (SPEC §3.6): **Bundled % = share of supply bought in the launch transaction or by wallets funded by the same source within 60 s of launch.** This catches bundles and also non-Jito same-slot coordination; it misses operators who pre-fund wallets days ahead.
+
+**Trader reading.** A high bundled share means one party controls a large float and can sell it at once; many "bundled launches" dump the bundle into the first organic bid. But a bundle that *sells early and is absorbed* can leave a cleaner holder base afterwards (the fixture case F5 models this). The number to watch next is whether the bundle wallets still hold (`get_holders` labels `sniper`, `get_trades.sniperSells`).
+
+**Sandwich note:** Jito's `jitodontfront` convention (an account whose pubkey starts with `jitodontfront` in an instruction) makes the block engine reject bundles that would front-run that transaction; it protects the sender, not the token.

package/dist/packages/mcp/assets/kb/entries/launchlab-curve.md

@@ -0,0 +1,31 @@
+---
+id: launchlab-curve
+title: Raydium LaunchLab curves, graduation and the CPMM handoff
+tags:
+  - raydium
+  - launchlab
+  - letsbonk
+  - bonding-curve
+  - graduation
+  - fees
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://docs.raydium.io/products/launchlab/bonding-curve.md (retrieved 2026-09-30 into solana-launchpad/docs/raydium/launchlab-bonding-curve.md)
+  - https://docs.raydium.io/products/launchlab/platform-config.md (solana-launchpad/docs/raydium/launchlab-platform-pda.md)
+  - https://docs.raydium.io/products/cpmm/fees.md (creator fee only on InitializeWithPermission pools)
+---
+**Curve types** (selected at `Initialize`, stored in `LaunchState.curve_type`): `0` constant-product with virtual reserves (the pump-style default), `1` fixed-price, `2` linear-price (cost quadratic in tokens sold: "early buyers pay close to zero, late buyers pay substantially more").
+
+**Supply split:** `base_supply_graduation` is "usually 0.8 × base_supply_max; the remaining 20 % becomes the post-graduation pool's initial LP". `quote_reserve_target = cost(0, base_supply_graduation) × (1 + buy_fee_rate)`; the launch graduates when `quote_vault.balance ≥ quote_reserve_target`.
+
+**Fees on the curve:** per-buy `gross_fee = ceil(quote_in × buy_numerator / buy_denominator)` (e.g. 100/10,000 = 1 %), split into `lp_share` (stays in the quote vault), `protocol_share`, `creator_share` (accrues to `creator_fees_quote`).
+
+**Handoff:** at `Graduate`, `cpmm_quote_reserve = quote_vault − swept protocol fees − swept creator fees`, `cpmm_base_reserve = base_vault`, and for the constant-product curve the CPMM opening price equals the curve's marginal price, "so an observer switching from the curve UI to the CPMM UI sees no jump". Only CPMM pools created via `InitializeWithPermission` (LaunchLab graduations) have `enable_creator_fee = true`.
+
+**Platforms:** third-party front ends (LetsBonk is one) are *platform PDAs* with their own fee share and defaults; the launchpad label in dexterm (`bonk`, `raydium`) comes from Jupiter's `launchpad` field.
+
+**Trader reading:** a LaunchLab token on a linear curve has a steep late-buyer price; "graduated" means a Raydium CPMM pool now exists, seeded with the supply left after the curve (usually 20 %) as its base side; the creator earns fees for as long as the pool trades. LaunchLab has no public REST for per-mint state that worked in the inventory probe (500 on a guessed `platformId`), so state is read on-chain.

package/dist/packages/mcp/assets/kb/entries/lp-burn-vs-lock.md

@@ -0,0 +1,31 @@
+---
+id: lp-burn-vs-lock
+title: LP tokens, burn vs lock, and what lpLockedPct means
+tags:
+  - lp
+  - liquidity
+  - burn
+  - lock
+  - rug
+  - raydium
+  - meteora
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://github.com/pump-fun/pump-public-docs/blob/main/docs/PUMP_SWAP_README.md (lp_supply excludes burns)
+  - https://docs.meteora.ag/core-products/dbc/migration-and-liquidity.md (retrieved 2026-09-30; locked/vesting liquidity, 10 % permanent lock rule, 0.2 % migration fee)
+  - https://docs.raydium.io/products/cpmm/fees.md (retrieved 2026-09-30; LP fee stays in the vault, owned pro-rata by LP tokens)
+  - dexterm SPEC.md §3.6 (LP locked definition; pump.fun/PumpSwap treated as 100 %)
+---
+**Mechanics.** On a constant-product AMM (Raydium CPMM, PumpSwap, Meteora DAMM) the liquidity provider receives LP tokens that represent a pro-rata claim on both vaults; "the LP fee is never explicitly tracked — it remains in the vault as a reserve that all LP tokens proportionally own" (Raydium CPMM docs). Whoever holds the LP tokens can withdraw the pool's SOL and tokens. A "rug pull" in the narrow sense is the LP holder withdrawing liquidity, which drives the price to ~0 for everyone else.
+
+**Burn:** sending the LP tokens to an unrecoverable state (SPL `Burn`). PumpSwap's `Pool.lp_supply` is documented as "total LP supply excluding user burns", so a burned LP shows up as reduced supply. Burned liquidity can never be withdrawn, but it also cannot be migrated or upgraded.
+
+**Lock:** LP tokens held by a locker program or a vesting position with a release date. Meteora DBC graduations distribute DAMM v2 liquidity into positions that are *unlocked*, *permanently locked* ("cannot be withdrawn; earns trading fees forever") or *vesting* ("cliff + linear or periodic releases"), and "the config must ensure at least 10 % of liquidity is permanently locked on day 1 for the standard keeper to migrate the pool". A lock has an expiry; a permanent lock does not.
+
+**What the number means in dexterm:** `rugcheck.lpLockedPct` is RugCheck's estimate of the share of LP that is burned or locked. SPEC §3.6: pump.fun/PumpSwap pools are treated as 100 % because migrated liquidity is not held by the creator. Anything below 100 % on a Raydium/Meteora pair means someone can pull that share.
+
+**Judgement (maintainers, reviewed 2026-10-15):** "LP locked" is necessary, not sufficient. A 100 % locked LP with a live freeze authority is still a honeypot; a locked LP with 60 % supply in the deployer's cluster can still be dumped into the pool. Read LP together with authorities (`mint-freeze-authority`) and concentration (`holder-concentration`). A lock with a short expiry is a timer, not safety.

package/dist/packages/mcp/assets/kb/entries/metadata-and-copycats.md

@@ -0,0 +1,29 @@
+---
+id: metadata-and-copycats
+title: Token metadata, mutable names and why the ticker is not an identifier
+tags:
+  - metaplex
+  - metadata
+  - copycat
+  - ticker
+  - symbol
+  - mint
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://www.metaplex.com/docs/smart-contracts/token-metadata (retrieved 2026-09-30 into solana-launchpad/docs/metaplex/token-metadata-overview.md)
+  - https://github.com/pump-fun/pump-public-docs (create(user, name, symbol, uri, creator))
+  - dexterm SPEC.md §5.3 CL-05 analogue (tools take mints; symbol resolution prefers the row on screen)
+---
+**Where the name comes from.** A mint account holds supply, decimals and authorities, nothing human-readable. The Metaplex Token Metadata program attaches a **Metadata account** (PDA from the mint) with `name`, `symbol`, a `URI` to off-chain JSON (image, description, socials), a creators list with a `Verified` flag, and an `Is Mutable` attribute. pump.fun's `create(user, name, symbol, uri, creator)` writes these at creation.
+
+**Consequences.**
+- **Symbols are free text.** Anyone can create a token with the same name and symbol as a well-known one. There can be hundreds of mints with the same symbol; the mint address is the only identifier. dexterm's `get_token` returns *candidates* when a symbol is ambiguous and the skills must disambiguate by mint (or by the row on screen) before saying anything.
+- **Mutable metadata** (`Is Mutable` true) lets the update authority rename and re-image a token after it has been listed, which is how a dead mint is recycled into a trending name. Immutable metadata cannot be changed on-chain; the off-chain JSON stays fixed only if the URI also points at permanent storage (such as Arweave). GoPlus reports `metadata_mutable`.
+- **Off-chain URI content is untrusted text.** The description, socials and image live wherever the URI points; they can be changed if the URI host is mutable, and they are the main carrier of prompt-injection text. dexterm firewalls every such string (SPEC §5.3) and the analyst treats `<untrusted>` blocks as data.
+- **Verified creators** are signed by the creator key; an unverified creator entry is a claim, not a proof.
+
+**Rule for skills:** identify a token by mint in every output (`mint` field in the schema); never by symbol alone. When the user names a symbol and the tool returns more than one candidate, return `AMBIGUOUS` with the candidates instead of guessing.

package/dist/packages/mcp/assets/kb/entries/mint-freeze-authority.md

@@ -0,0 +1,31 @@
+---
+id: mint-freeze-authority
+title: Mint authority and freeze authority (SPL Token)
+tags:
+  - spl-token
+  - mint-authority
+  - freeze-authority
+  - honeypot
+  - rug
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://spl.solana.com/token (retrieved 2026-09-30 into solana-launchpad/docs/spl-token/spl-token-overview.md)
+  - https://github.com/solana-program/token (program source; InitializeMint, MintTo, FreezeAccount, SetAuthority)
+  - dexterm SPEC.md §3.3 Audit model (mintAuthority/freezeAuthority booleans)
+---
+**Mechanics (from the SPL Token program).** A token type is a `Mint` account created with `InitializeMint`. Two optional authorities live on the mint:
+- **mint authority**: can call `MintTo` and create new supply at will. It can be revoked by `SetAuthority` to `None`, after which supply is fixed forever. Tokens "when initially created by spl-token have no supply"; all supply is minted by this authority.
+- **freeze authority**: "The Mint may also contain a `freeze_authority` which can be used to issue `FreezeAccount` instructions." A frozen token account cannot transfer or sell. It can also be revoked, and cannot be re-added once revoked.
+
+Both are fields on the mint account, readable with `getAccountInfo(mint, jsonParsed)` (`mintAuthority`, `freezeAuthority`, `supply`, `decimals`). Jupiter's `audit` and GoPlus's `mintable`/`freezable` flags are derived from the same fields.
+
+**Why a trader cares.**
+- A live **mint authority** means the supply can be inflated at any time (mint-and-dump). Any market cap or "% of supply" number is provisional.
+- A live **freeze authority** is the honeypot primitive on Solana: the authority can freeze buyers' token accounts selectively so they cannot sell while the deployer's cluster can. It is also used legitimately by some stablecoins and regulated assets, so it is a red flag on a memecoin, not proof of fraud.
+- Launchpads differ: pump.fun creates coins with both authorities revoked by design (see `pump-bonding-curve`); tokens created by hand or through generic token creators on Raydium/Meteora can keep either authority.
+
+**What this entry does NOT tell you:** whether *this* token's authorities are revoked. That is a per-mint fact; read it from `get_token.audit.mintAuthority` / `.freezeAuthority` (true = still enabled) or `rugcheck.risks`.

package/dist/packages/mcp/assets/kb/entries/narrative-lifecycle.md

@@ -0,0 +1,32 @@
+---
+id: narrative-lifecycle
+title: Narrative lifecycle (DRAFT, needs maintainer review before any skill may cite it)
+tags:
+  - narrative
+  - meta
+  - lifecycle
+  - trending
+  - judgement
+date: 2026-10-06
+confidence: low
+owner: maintainers
+origin: maintainer-draft
+reviewed_by: none
+status: draft-unreviewed
+sources:
+  - dexterm research/data-firehose-inventory-2026-10-06.md §1c (Jupiter toptrending/toporganicscore, DexScreener boosts/profiles, GeckoTerminal trending_pools, DefiLlama venue share)
+  - dexterm ROADMAP.md north-star scenario (narrative summary, volume per narrative)
+---
+**Status.** This is the one entry in the KB that is trading judgement rather than protocol mechanics. It is a scaffold for the maintainers to replace; `confidence: low`, `status: draft-unreviewed`. The `narrative-scan` and `daily-digest` routines must refuse to cite it until `reviewed_by` is set.
+
+**What can be measured (facts, from tools):** which tokens are on Jupiter's `toptrending/{5m,1h,6h,24h}` and `toporganicscore` lists; DexScreener boosts and profiles (paid promotion); GeckoTerminal `trending_pools` and `new_pools` with DEX counts; per-DEX 24 h volume from DefiLlama; the *share of new launches whose name/description matches a theme* (string match over firewalled text); SOL funding/OI from Hyperliquid/OKX as the macro backdrop.
+
+**Scaffold of the lifecycle (to be rewritten by the maintainers):**
+1. *Spark*: a real-world event or one runner; a handful of mints with the theme appear within minutes.
+2. *Derivative wave*: dozens of same-theme launches; most are copycats; volume concentrates in one or two leaders.
+3. *Peak*: trending lists are dominated by the theme; late derivatives launch into falling attention.
+4. *Rotation*: volume per theme falls, leaders fade or hold, a new spark begins.
+
+**What a narrative routine may output:** counts and volumes per theme with the tool and data age, the leaders by organic score, and *proposals* (watch-list adds, alerts) for the user to confirm. It may not say that a theme "will run".
+
+**Open questions:** what counts as a theme match; the minimum number of same-theme launches before it is a narrative; whether DexScreener boosts count as a negative signal; which X lists (if any) seed the theme detector once 1289 lands.

package/dist/packages/mcp/assets/kb/entries/pump-bonding-curve.md

@@ -0,0 +1,33 @@
+---
+id: pump-bonding-curve
+title: pump.fun bonding curve mechanics
+tags:
+  - pump.fun
+  - bonding-curve
+  - graduation
+  - fees
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://github.com/pump-fun/pump-public-docs (README, retrieved 2026-10-01 into solana-launchpad/docs/pump-fun/docs-overview.md)
+  - https://github.com/pump-fun/pump-public-docs/blob/main/docs/PUMP_PROGRAM_README.md (solana-launchpad/docs/pump-fun/fees.md)
+---
+**What it is.** The Pump program (`6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P`) creates an SPL coin that is instantly tradeable on a constant-product curve with *synthetic* (virtual) reserves, Uniswap-v2 style. When the real token reserve is sold out the curve is `complete` and liquidity migrates to PumpSwap.
+
+**Numbers from the on-chain `Global` config (PDA `4wTV1YmiEkRvAtNtsSGPtUrqRYQMe5SKy2uB4Jjaxnjf`), as documented when retrieved 2026-10-01 (the config can change; a tool reads the live values):**
+- `initial_virtual_token_reserves` 1,073,000,000,000,000; `initial_virtual_sol_reserves` 30,000,000,000 lamports (30 SOL); `initial_real_token_reserves` 793,100,000,000,000; `token_total_supply` 1,000,000,000,000,000 (1 B tokens at 6 decimals).
+- `fee_basis_points` 100 = **1 %** on every buy and sell, paid to one of 8 fee-recipient accounts. A creator fee, when the coin has one, comes on top (the protocol sets its rate for SOL- and USDC-paired coins).
+- `pool_migration_fee` 15,000,001 lamports (~0.015 SOL) charged by `migrate`.
+
+**Per-coin `BondingCurve` account** (PDA seeds `["bonding-curve", mint]`): `virtual_token_reserves`, `virtual_sol_reserves` (pricing), `real_token_reserves`, `real_sol_reserves`, `complete` (true when `real_token_reserves == 0`), `creator` (accrues creator fees), `quote_mint` (default pubkey for SOL-paired coins), `is_holder_reward`.
+
+**Instructions:** `create`, `buy(amount, max_sol_cost)`, `sell(amount, min_sol_output)`, the v2 variants (`buy_v2`, `sell_v2`, `buy_exact_quote_in_v2`, all accounts mandatory), and `migrate(user, mint)` which is **permissionless**: anyone can trigger the migration once the curve is complete.
+
+**How to read "bonding progress":** progress = 1 − `real_token_reserves` / `initial_real_token_reserves`. The curve's price at any moment is `virtual_sol_reserves / virtual_token_reserves`. "Graduation" = `complete` flipped to true, followed by a `migrate` instruction that creates the PumpSwap pool (see `pumpswap-migration`).
+
+**What a trader can and cannot infer:** a pump.fun coin is created with its mint and freeze authority revoked (the program creates it that way; verify it on the mint account with a tool), and pre-graduation there is no LP token to lock or burn because liquidity lives in the curve PDA. The risks on the curve are **holder concentration, bundled first buys and the creator's behaviour**, not authorities or LP.
+
+**Tool mapping in dexterm:** `get_token` (launchpad, age, mcap), `get_dev_history` (creator, bundle share), `get_holders`. The `pumpfun` frontend API (S8) is undocumented and feature-flagged; the compliant source for curve state is the on-chain account via Helius.

package/dist/packages/mcp/assets/kb/entries/pumpswap-migration.md

@@ -0,0 +1,29 @@
+---
+id: pumpswap-migration
+title: PumpSwap migration and post-graduation pools
+tags:
+  - pump.fun
+  - pumpswap
+  - migration
+  - graduation
+  - lp
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://github.com/pump-fun/pump-public-docs/blob/main/docs/PUMP_SWAP_README.md (retrieved 2026-10-01 into solana-launchpad/docs/pump-fun/pumpswap-overview.md)
+  - https://github.com/pump-fun/pump-public-docs/blob/main/docs/PUMP_PROGRAM_README.md (fees)
+---
+**What it is.** PumpSwap (`pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA`) is pump.fun's own constant-product AMM. A completed bonding curve migrates here automatically (the `migrate` instruction on the Pump program is permissionless). Pools created by `migrate` use `CANONICAL_POOL_INDEX == 0`.
+
+**Fees (GlobalConfig PDA `ADyA8hdefvWN2dbGGWFotbzWxrAvLW83WG6QCVXvJKqw`):** `lp_fee_basis_points` 20 (0.20 %) + `protocol_fee_basis_points` 5 (0.05 %) = **0.25 % per swap**, plus the coin-creator fee where one applies (the protocol sets its rate); no fee on deposit/withdraw. Protocol fees go to one of 8 recipient pubkeys chosen at random per tx.
+
+**Pool account** (PDA seeds `["pool", index, creator, baseMint, quoteMint]`): `base_mint`, `quote_mint`, `lp_mint` (PDA `["pool_lp_mint", pool]`), vault ATAs, `lp_supply` (**total LP supply excluding user burns**), `coin_creator` (accrues creator fees), `virtual_quote_reserves` (i128; the docs, retrieved 2026-10-01, say it can be negative "starting September 30"; quoting must use `pool_quote_token_account.amount + virtual_quote_reserves`).
+
+**What "graduated" means for risk:** after migration the liquidity is a real AMM pool with an LP mint. Because `lp_supply` excludes burns, a pool whose LP has been burned shows a reduced `lp_supply`; RugCheck's `lpLockedPct` for pump.fun/PumpSwap pairs is treated as 100 % in dexterm (SPEC §3.6) because the migrated liquidity is not held by the creator. The creator still earns `coin_creator` fees on every swap, which is an incentive to keep the pool trading, and also an incentive to launch many coins.
+
+**Holder rewards:** when `is_holder_reward == true`, the creator fee is distributed to holders instead; `BuyEvent`/`SellEvent` carry `holder_rewards_bps`.
+
+**Tool mapping:** `get_token.pair.dex == "pumpswap"` identifies a graduated coin; `rugcheck.lpLockedPct`; the pool address is `pair.pairAddress`.

package/dist/packages/mcp/assets/kb/entries/sniping-and-snipers.md

@@ -0,0 +1,29 @@
+---
+id: sniping-and-snipers
+title: Sniping: how first-block buyers get in and how dexterm counts them
+tags:
+  - sniping
+  - snipers
+  - launch
+  - forensics
+  - pumpportal
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - dexterm SPEC.md §3.6 (Snipers definition)
+  - dexterm research/data-firehose-inventory-2026-10-06.md (PumpPortal create stream median 65 ms before Helius logs; Helius logsSubscribe metering)
+  - https://docs.meteora.ag/core-products/dbc/fees/rate-limiter.md (deprecated buy-size fee)
+  - https://docs.raydium.io/products/launchlab/bonding-curve.md (linear curve makes early buys cheap)
+---
+**Definition used by dexterm (SPEC §3.6):** snipers = distinct wallets that bought in the token's **first 3 blocks** (or first 2 s on a bonding curve). Needs parsed transaction history (Helius `getTransactionsForAddress`, Tier 1).
+
+**How snipers get there.** Bots subscribe to create events: PumpPortal's `subscribeNewToken` (free; in the 2026-10-06 probe its create messages arrived a median 65 ms *before* Helius `logsSubscribe` on a loaded socket), or `logsSubscribe` on the launchpad program, then submit a buy, often through a Jito bundle for ordering (see `jito-bundles`). On a constant-product curve with virtual reserves the first buys are the cheapest tokens the curve will ever sell; on a linear LaunchLab curve "early buyers pay close to zero".
+
+**Protocol-level deterrents.** Meteora DBC had a *rate limiter* fee that rose with buy size for up to 12 h; it is deprecated for new configs, replaced by time-decaying fee schedulers (high starting fee that decays), so a launch's anti-snipe protection is now "fee is high for the first minutes", if the partner configured it at all. pump.fun's documented curve fee is a flat 1 % (plus any creator fee), with no size- or time-based part.
+
+**Difference from bundling.** A sniper is an *outside* bot racing the public; a bundle is the *deployer's own* wallets inserted atomically. The chain shows both as early buys; funding-source clustering separates them (a sniper bot's wallets are funded by the bot operator, not by the creator).
+
+**Judgement (maintainers, reviewed 2026-10-15; rough heuristics, not yet measured):** a few snipers (2–5) on a popular launch are common and often sell within minutes; a dozen plus a high bundled share means the early float is in professional hands and the first candle is theirs to sell into. The useful number is sniper share *still held* at the time of analysis, not the count at launch.

package/dist/packages/mcp/assets/kb/entries/token2022-extensions-risk.md

@@ -0,0 +1,32 @@
+---
+id: token2022-extensions-risk
+title: Token-2022 extensions a trader must check
+tags:
+  - token-2022
+  - transfer-fee
+  - transfer-hook
+  - permanent-delegate
+  - honeypot
+date: 2026-10-06
+confidence: high
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://spl.solana.com/token-2022/extensions (retrieved 2026-09-30 into solana-launchpad/docs/spl-token/token2022-extensions.md)
+  - Token-2022 program id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb (solana-launchpad/docs/INDEX.md gap note)
+---
+Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`) adds extensions to mints and token accounts. A token's program id tells you which rules apply (`rugcheck.tokenProgram`, GoPlus fields). Extensions that change what a holder can do:
+
+| Extension | What the docs say | Trader reading |
+|---|---|---|
+| **Transfer fee** | "On every transfer, some amount is withheld on the recipient account, untouchable by the recipient"; fee in basis points plus a maximum fee; a *withdraw withheld authority* can collect it. | A tax on every trade. Check the bps and who holds the withheld-withdraw authority. A fee authority can raise the fee later. |
+| **Default account state** | "can force all new token accounts to be frozen. Users must interact with some service to unfreeze." | Buyers start frozen: a honeypot by construction unless the project unfreezes everyone. |
+| **Permanent delegate** | "unlimited delegate privileges over any account for that mint, meaning that it can burn or transfer any amount of tokens." | The issuer can take tokens out of your wallet. Disqualifying for a memecoin. |
+| **Transfer hook** | Token-2022 "calls into the program" the creator deployed on every transfer. | Arbitrary code on every transfer: can block sells, whitelist wallets, or tax. Treat it as unknown until you have read what the hook program does; an upgradeable hook can change later. |
+| **Non-transferable** | "soul-bound" tokens; the owner can still burn and close. | Cannot be sold at all. |
+| **Mint close authority** | the mint can be closed; "closing and reinitializing a mint with different extensions can lead to problems if any token accounts exist". | Rare on memecoins. A mint can only be closed while its supply is zero, so it cannot be closed under holders who still hold tokens; the risk is to empty token accounts left behind if it is closed and re-created. |
+| **Interest-bearing** | "entirely cosmetic"; no new tokens are created. | UI balance grows, value does not. |
+| **CPI guard, immutable owner, required memo** | protections for the account owner. | Neutral. |
+
+**Mapping:** GoPlus Solana token-security returns `transfer_fee`, `transfer_hook`, `default_account_state`, `non_transferable`, `balance_mutable_authority`, `closable`; dexterm surfaces the dangerous ones through `rugcheck.risks` and the Audit record. A legacy SPL Token (`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`) has none of these: only mint and freeze authority matter (see `mint-freeze-authority`).

package/dist/packages/mcp/assets/kb/entries/wash-trading-fake-volume.md

@@ -0,0 +1,33 @@
+---
+id: wash-trading-fake-volume
+title: Wash trading, fake volume and the organic score
+tags:
+  - wash-trading
+  - fake-volume
+  - organic-score
+  - volume
+  - jupiter
+date: 2026-10-06
+confidence: medium
+owner: maintainers
+origin: primary-doc
+reviewed_by: maintainers@2026-10-15
+sources:
+  - https://developers.jup.ag/docs/tokens (retrieved 2026-09-30 into solana-launchpad/docs/jupiter/tokens-api.md; Organic Score section)
+  - https://developers.jup.ag/blog/what-is-organic-score (linked from the Tokens API doc)
+  - dexterm SPEC.md §3.3 Stats (numTraders, numNetBuyers, buyVol/sellVol per window)
+---
+**What the aggregator measures.** Jupiter's Organic Score (0–100) "measures how genuine a token's trading activity is, filtering out bots, snipers, and copy-trading tools"; it combines organic volume, organic holders, organic traders and organic buyers after removing wallets that trade through known bot channels. The docs' own caveats: it is **relative, not absolute** (normalised against the ecosystem; SOL and USDC sit near 100), **early growth counts most** (10 → 100 organic buyers moves it far more than 10,000 → 10,100), and the raw score beats the `high/medium/low` label. dexterm shows the raw score (≥ 70 green, 40–69 amber, < 40 red; SPEC §3.6).
+
+**How volume is faked.** Two or more wallets controlled by one party buy and sell to each other; each round trip pays the trading fee (1 % on a pump.fun curve and 0.25 % on PumpSwap, each plus any creator fee; 0.25 % on the common Raydium CPMM tier) plus network fees and little else, so "$1 M volume" costs roughly $2,500 on a 0.25 % pool and about $10,000 on a 1 % curve. The goal is to appear on volume-sorted screeners and trending lists. Volume-boost services sell exactly this.
+
+**Signals that separate it (maintainers, reviewed 2026-10-15):**
+- `get_trades.top2WalletVolumeSharePct` high (two wallets are most of the tape) and `distinctWallets` low relative to `count`.
+- `stats.perWindow.h1.numTraders` small while `pair.volume.h1` is large: volume per trader is far above a retail ticket.
+- `buyVol ≈ sellVol` to the dollar across windows with no price trend: ping-pong.
+- Organic score low while raw volume ranks high.
+- Candle volume evenly spaced in time (bot cadence) rather than bursty.
+
+**What it is not:** high volume from a few big wallets that are *not* round-tripping (a whale accumulating) looks similar on share-of-volume alone; the buy/sell symmetry and price response distinguish them.
+
+**Rule:** the KB describes the pattern; whether *this* token shows it comes from `get_trades`, `get_token.stats` and `get_candles` with their data ages.