@laitszkin/apollo-toolkit 2.4.3 → 2.6.0

package/jupiter-development/references/official-docs.md

@@ -0,0 +1,157 @@
+# Jupiter Official Docs Reference
+
+Snapshot source: official Jupiter developer docs reviewed on 2026-03-20 from `https://dev.jup.ag/llms.txt` and linked first-party pages.
+
+## 1. Always refresh from these official entry points
+
+- Docs index: `https://dev.jup.ag/llms.txt`
+- Get started: `https://dev.jup.ag/get-started`
+- Developer portal and API keys: `https://dev.jup.ag/portal/setup.md`
+- Rate limits: `https://dev.jup.ag/portal/rate-limit.md`
+- Ultra docs root: `https://dev.jup.ag/docs/ultra-api`
+- Swap docs root: `https://dev.jup.ag/docs/swap/index.md`
+- Tokens docs root: `https://dev.jup.ag/docs/tokens/v2/token-information.md`
+- Price docs root: `https://dev.jup.ag/docs/price/index.md`
+- Lend docs root: `https://dev.jup.ag/docs/lend/index.md`
+
+If a task depends on exact schemas, jump from those pages into the matching OpenAPI reference before coding.
+
+## 2. Product selection cheatsheet
+
+| Need | Official Jupiter surface | Notes |
+| --- | --- | --- |
+| Best default swap flow | Ultra API `/ultra/v1/order` + `/ultra/v1/execute` | Current get-started docs point new integrators here first. |
+| Custom swap transaction or CPI composition | Metis Swap API | Use the lower-level swap docs only when the app must own quote/build behavior or compose instructions manually. |
+| Token search, metadata, verification, discovery | Tokens API V2 | Search by symbol, name, mint, tag, category, or recency. |
+| USD token prices | Price API V3 | Heuristic price engine; unreliable tokens may return `null`. |
+| Deposit-and-earn yield | Jupiter Lend Earn API or SDK | REST is enough for simple Earn flows; SDK gives instruction-level control. |
+| Borrow, repay, flashloan, or CPI lending | `@jup-ag/lend` plus `@jup-ag/lend-read` | Use SDK and product docs for instruction building and analytics. |
+| Limit orders / TP-SL style automation | Trigger API | Trigger V2 uses JWT auth; Trigger V1 remains documented for legacy flows. |
+| DCA | Recurring API | Time-based recurring orders. |
+| Wallet position aggregation | Portfolio API | Beta status. |
+
+## 3. Auth and operational rules
+
+- Current official docs say `api.jup.ag` requires `x-api-key`.
+- Current get-started examples still show public `lite-api.jup.ag` usage for some flows, while Jupiter's update/migration docs say deprecation was postponed and migration toward `api.jup.ag` is in progress.
+- Treat hostname choice as a time-sensitive implementation detail and refresh the exact product page before coding.
+- Generate keys at `https://portal.jup.ag`.
+- Rate limits are per account, not per key.
+- Free tier: 60 requests per 60 seconds.
+- Pro tiers: 10-second sliding windows; the Price API gets its own bucket on Pro.
+- Do not assume that creating more API keys increases throughput.
+
+## 4. Ultra and Metis swap essentials
+
+Primary docs:
+
+- `https://dev.jup.ag/get-started`
+- `https://dev.jup.ag/docs/ultra-api`
+- `https://dev.jup.ag/docs/swap/index.md`
+- `https://dev.jup.ag/docs/swap/get-quote`
+- `https://dev.jup.ag/docs/swap/build-swap-transaction`
+- `https://dev.jup.ag/docs/swap/build-swap-transaction#build-your-own-transaction-with-flash-fill-or-cpi`
+
+### Default path: Ultra API
+
+- Current get-started guidance points integrators to `GET /ultra/v1/order` and `POST /ultra/v1/execute`.
+- Use this path for the least integration work and the official default trade flow.
+
+### Advanced path: Metis Swap API
+
+- Use the lower-level swap docs when the integrator must own quote handling, transaction assembly, CPI composition, or Flash Fill style flows.
+- Reconfirm the current endpoint family on the exact swap page you use because Jupiter has been migrating between public and Portal-backed hosts.
+
+### Routing and option guardrails
+
+- Optional payer, referral, fee, or router-selection parameters are not neutral.
+- Re-read the exact product page before enabling them because they can affect routing, fees, or gasless support.
+- Do not assume all examples on older swap pages still describe the default production path.
+
+## 5. Tokens API V2 essentials
+
+Base URL: `https://api.jup.ag/tokens/v2`
+
+Primary docs:
+
+- `https://dev.jup.ag/docs/tokens/v2/token-information.md`
+- `https://dev.jup.ag/docs/tokens/organic-score.md`
+
+Important behaviors:
+
+- Search supports symbol, name, and mint-address lookup.
+- Tag queries support curated groups such as `verified` and `lst`.
+- Category queries support discovery sets such as `toporganicscore`, `toptraded`, and `toptrending`.
+- Recent tokens are keyed off first pool creation time, not token mint time.
+- Responses include metadata and market-quality signals such as organic score, holder count, market cap, liquidity, and trading stats.
+- The docs explicitly warn that the response schema may change as the API evolves.
+
+Organic score is meant to represent genuine token activity and health using wallet, liquidity, and trading signals while filtering out bot-like or wash-trade patterns.
+
+## 6. Price API V3 essentials
+
+Base URL: `https://api.jup.ag/price/v3`
+
+Primary docs:
+
+- `https://dev.jup.ag/docs/price/index.md`
+- `https://dev.jup.ag/docs/price/v3.md`
+- `https://dev.jup.ag/guides/how-to-get-token-price.md`
+
+Important behaviors:
+
+- Price V3 derives prices from the last swapped price and validates them with liquidity and market-health heuristics.
+- Up to 50 mint addresses can be queried per request according to the official guide.
+- Missing or `null` prices are expected for tokens that fail Jupiter's reliability checks.
+- Do not treat missing prices as transient transport errors by default.
+
+## 7. Jupiter Lend essentials
+
+Primary docs:
+
+- `https://dev.jup.ag/docs/lend/index.md`
+- `https://dev.jup.ag/docs/lend/api-vs-sdk.md`
+- `https://dev.jup.ag/docs/lend/program-addresses.md`
+- `https://dev.jup.ag/docs/lend/advanced/index.md`
+
+Packages mentioned by the official docs:
+
+- `@jup-ag/lend`
+- `@jup-ag/lend-read`
+- `@solana/web3.js`
+
+Practical split:
+
+- Use the REST API for straightforward Earn deposit and withdrawal flows.
+- Use the SDK when you need Borrow flows, CPI, flashloans, batched operations, address lookup tables, or read-side analytics.
+- For advanced recipes such as multiply, unwind, vault swap, and flashloans, expect large multi-instruction transactions and add compute budget when needed.
+- Public RPC endpoints are not recommended for production; the docs suggest dedicated providers.
+
+## 8. Other important Jupiter APIs
+
+### Trigger
+
+- Docs root: `https://dev.jup.ag/docs/trigger/index.md`
+- Trigger V2 uses a challenge-response auth flow and returns a JWT for subsequent requests.
+- Use it for single price orders, OCO, and OTOCO flows.
+
+### Recurring
+
+- Docs root: `https://dev.jup.ag/docs/recurring/index.md`
+- Use it for time-based DCA orders.
+- Jupiter keeper bots handle recurring execution after setup.
+
+### Portfolio
+
+- Docs root: `https://dev.jup.ag/docs/portfolio/index.md`
+- Beta API for wallet positions across Solana protocols, including Jupiter-specific positions.
+
+## 9. Implementation checklist
+
+- Confirm the exact Jupiter product surface first.
+- Confirm the latest official page and API version before editing code.
+- Confirm whether the chosen host requires `x-api-key`, and keep any key out of source control.
+- Preserve the default routing path unless the product requirement truly needs advanced payer, fee, or router controls.
+- Treat `null` token prices as a valid product outcome.
+- Use SDK flows for Jupiter Lend borrow, CPI, flashloan, and analytics work.
+- Report any remaining API-key, RPC, or wallet requirements explicitly.

package/learn-skill-from-conversations/SKILL.md

@@ -15,7 +15,7 @@ description: Learn and evolve the local skill library from recent Codex conversa
 ## Standards
 
 - Evidence: Extract recent Codex session history first and derive reusable lessons only from actual conversation patterns.
-- Execution: Prefer creating a new skill unless the overlap with an existing skill is clearly strong, then apply the change through `skill-creator`.
+- Execution: Inventory the current skill catalog before editing, prioritize repeated requests, user corrections, and reported errors, then prefer a focused update to the strongest related skill or create a new skill only when the overlap is weak.
 - Quality: Take no action when there are no recent sessions, avoid unrelated broad refactors, and validate every changed skill.
 - Output: Report the analyzed sessions, extracted lessons, created or updated skills, and the reasoning behind each decision.
 
@@ -46,16 +46,25 @@ python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_co
 ### 2) Derive reusable lessons
 
 - Identify repeated user needs, recurring friction, and repeated manual workflows.
+- Give extra weight to moments where the user corrected the agent, rejected an earlier interpretation, or pointed out a missing preference or requirement.
+- Give extra weight to user-reported errors, regressions, or avoidable mistakes, then ask how a skill can prevent repeating that failure mode.
 - Ignore one-off issues that do not provide reusable value.
+- Distinguish between:
+  - repeated trigger intent that deserves a new skill
+  - repeated workflow fragments across multiple skills that should be extracted into a shared skill
+  - skill gaps that are better handled by tightening an existing skill's guardrails
 
 ### 3) Decide new skill vs existing skill (default: new skill)
 
+- First read the relevant skills already present in the working repository so you do not create a duplicate under a different name.
 - Prefer creating a new skill.
 - Edit an existing skill only when the lesson is strongly related.
 - Treat relation as strong only when all three conditions hold:
   - Same primary trigger intent.
   - At least 70% workflow overlap.
   - The update does not dilute the existing skill's scope.
+- When the recurring lesson is mainly about preventing a known mistake, prefer updating the existing skill that should have prevented it instead of creating a parallel skill.
+- When several skills repeat the same narrow workflow fragment, prefer extracting that fragment into a dedicated shared skill instead of copying the same guidance again.
 - If uncertain, create a new skill instead of expanding an old one.
 
 ### 4) Apply changes through skill-creator
@@ -76,7 +85,7 @@ python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-p
 
 ### 6) Report result
 
-- Summarize analyzed sessions, extracted lessons, created/updated skills, and why each decision was made.
+- Summarize analyzed sessions, repeated needs, user corrections, error-driven lessons, created/updated skills, and why each decision was made.
 
 ## Guardrails
 

package/lib/cli.js

@@ -371,7 +371,7 @@ async function run(argv, context = {}) {
       return 1;
     }
 
-    await syncToolkitHome({
+    const syncResult = await syncToolkitHome({
       sourceRoot,
       toolkitHome,
       version: packageJson.version,
@@ -380,6 +380,7 @@ async function run(argv, context = {}) {
     const installResult = await installLinks({
       toolkitHome,
       modes,
+      previousSkillNames: syncResult.previousSkillNames,
       env: {
         ...env,
         APOLLO_TOOLKIT_HOME: toolkitHome,

package/lib/installer.js

@@ -112,6 +112,7 @@ async function stageToolkitContents({ sourceRoot, destinationRoot, version }) {
 async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
   const parentDir = path.dirname(toolkitHome);
   const tempDir = path.join(parentDir, `.apollo-toolkit.tmp-${process.pid}-${Date.now()}`);
+  const previousSkillNames = await listSkillNames(toolkitHome).catch(() => []);
 
   await fsp.rm(tempDir, { recursive: true, force: true });
   await stageToolkitContents({ sourceRoot, destinationRoot: tempDir, version });
@@ -127,6 +128,7 @@ async function syncToolkitHome({ sourceRoot, toolkitHome, version }) {
 
   return {
     toolkitHome,
+    previousSkillNames,
     skillNames: await listSkillNames(toolkitHome),
   };
 }
@@ -191,13 +193,17 @@ async function replaceWithSymlink(sourcePath, targetPath) {
   await fsp.symlink(sourcePath, targetPath, type);
 }
 
-async function installLinks({ toolkitHome, modes, env = process.env }) {
+async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [] }) {
   const skillNames = await listSkillNames(toolkitHome);
   const targets = await getTargetRoots(modes, env);
   const linkedPaths = [];
+  const staleSkillNames = previousSkillNames.filter((skillName) => !skillNames.includes(skillName));
 
   for (const target of targets) {
     await ensureDirectory(target.root);
+    for (const staleSkillName of staleSkillNames) {
+      await fsp.rm(path.join(target.root, staleSkillName), { recursive: true, force: true });
+    }
     for (const skillName of skillNames) {
       const sourcePath = path.join(toolkitHome, skillName);
       const targetPath = path.join(target.root, skillName);

package/{codex-subagent-orchestration → marginfi-development}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Yamiyorunoshura
+Copyright (c) 2026 LaiTszKin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/marginfi-development/README.md

@@ -0,0 +1,31 @@
+# Marginfi Development
+
+`marginfi-development` is a reusable skill for building or reviewing integrations on the marginfi protocol with official documentation as the source of truth.
+
+It helps an agent:
+
+1. Choose the correct marginfi development surface.
+2. Reconfirm official addresses, groups, and environment details.
+3. Implement or explain deposits, borrows, repayments, withdrawals, flash loans, liquidations, or permissionless banks.
+4. Map raw `mfi-v2` instructions and errors when SDK helpers are not enough.
+
+## Repository layout
+
+- `SKILL.md`: trigger rules, workflow, and guardrails
+- `agents/openai.yaml`: agent-facing metadata
+- `references/official-development-notes.md`: condensed official development guidance
+- `references/source-index.md`: quick source routing for official docs
+
+## Main use cases
+
+Use this skill for:
+
+- marginfi SDK integration work
+- Solana bots or backends that interact with marginfi
+- bank configuration and The Arena permissionless-bank flows
+- flash-loan or liquidation implementation reviews
+- raw instruction or error mapping against `mfi-v2`
+
+## License
+
+MIT. See `LICENSE`.

package/marginfi-development/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: marginfi-development
+description: Build or analyze integrations on the Solana-based marginfi protocol using the official TypeScript SDK, Rust CLI, and protocol docs. Use when implementing or reviewing marginfi deposits, withdrawals, borrows, repayments, flash loans, liquidations, permissionless banks, bank configuration, account-health logic, or raw instruction mapping, and ground the work in official marginfi documentation before coding.
+---
+
+# Marginfi Development
+
+## Dependencies
+
+- Required: none.
+- Conditional: `answering-questions-with-research` when the user needs marginfi guidance combined with fresh external verification or local repository discovery.
+- Optional: none.
+- Fallback: If official docs do not confirm a requested parameter, address, or workflow, say so explicitly instead of guessing.
+
+## Standards
+
+- Evidence: Start from official marginfi docs and official source links, and re-check time-sensitive values before hardcoding them.
+- Execution: Pick the correct integration surface first (TypeScript SDK, Rust CLI, or raw program instructions), then scope the exact bank, group, account, and environment involved.
+- Quality: Preserve Solana and Anchor conventions, validate margin account health assumptions, and never invent bank config or oracle defaults.
+- Output: Provide copy-pastable implementation steps, the exact official source pages consulted, and concrete caveats for unresolved risks.
+
+## Goal
+
+Build or review marginfi integrations with the smallest correct implementation that still respects the protocol's account model, bank risk parameters, oracle rules, and operational constraints.
+
+## Workflow
+
+### 1) Classify the task before coding
+
+Map the request to one of these paths:
+
+- application integration with the TypeScript SDK
+- operational/admin work with the Rust CLI
+- raw on-chain instruction work against `mfi-v2`
+- permissionless bank creation in The Arena
+- liquidations, health, or risk-model analysis
+- flash loan composition
+
+Then load only the matching reference sections from `references/official-development-notes.md`.
+
+### 2) Reconfirm official docs when values can drift
+
+Re-check live official docs when the task depends on:
+
+- current program or group addresses
+- package names or environment configs
+- current bank parameters or listing rules
+- The Arena flows or permissionless-bank requirements
+
+Use `references/source-index.md` to jump to the right official page quickly.
+
+### 3) Choose the correct development surface
+
+#### TypeScript SDK
+
+Use for frontends, bots, services, scripts, or integration tests.
+
+- Start with `MarginfiClient.fetch(getConfig(...), wallet, connection)`.
+- Fetch or create the authority's marginfi account before user actions.
+- Resolve banks by token symbol, mint, or public key before depositing, borrowing, repaying, or withdrawing.
+- Prefer SDK helpers for instruction construction, transaction processing, flash loans, and account reloads.
+
+#### Rust CLI
+
+Use for operator workflows, group or bank administration, and quick protocol interaction from the terminal.
+
+- Configure the correct profile and environment first.
+- Use the CLI for account creation, deposits, borrows, repayments, withdrawals, transfers, emissions setup, and bank-management flows.
+- When creating or updating banks, provide explicit config values; do not infer hidden defaults.
+
+#### Raw program work
+
+Use when you need exact instruction names, account constraints, or error mapping.
+
+- Read the `mfi-v2` instruction and error sections first.
+- Keep flash-loan state transitions and end-instruction indexing exact.
+- Map protocol errors back to the user-visible cause instead of returning opaque Solana failures.
+
+### 4) Apply the task-specific playbook
+
+#### Deposits / borrows / withdrawals / repayments
+
+- Confirm the target group and bank.
+- Load or create the user's marginfi account.
+- Fetch fresh bank data and oracle-backed pricing before reasoning about health.
+- Use SDK or CLI helpers instead of hand-writing instructions unless the task explicitly needs raw instruction control.
+
+#### Flash loans
+
+- Treat flash loans as a begin/end instruction pair or use the SDK helper that builds the full transaction.
+- Ensure the end instruction index is correct and that every temporary borrow is repaid within the same transaction.
+- Watch for flash-loan-specific errors such as illegal nesting or missing end instructions.
+
+#### Permissionless banks / The Arena
+
+- Collect the mint, oracle setup, risk tier, asset/liability weights, deposit and borrow limits, operational state, and rate configuration before coding.
+- Use the official The Arena guidance and listing criteria as the source of truth.
+- Surface any missing config explicitly; never invent safe-looking defaults.
+
+#### Liquidations and health analysis
+
+- Distinguish collateral, borrow-only, and isolated assets.
+- Explain how asset weights, liability weights, utilization-based rates, and oracle staleness checks affect account health.
+- Use official terminology when describing liquidatable states and liquidation flows.
+
+### 5) Respect protocol guardrails
+
+- marginfi relies on Pyth and Switchboard oracle feeds with confidence and staleness checks; do not assume any quoted price is always usable.
+- Interest rates are utilization-based and piecewise; account economics depend on bank config, not just spot balances.
+- Current docs describe verified builds, audits, fuzz testing, and bug-bounty coverage; do not bypass those assumptions when proposing deployment or upgrade steps.
+
+### 6) Output expectations
+
+When finishing marginfi work:
+
+- name the exact official pages consulted
+- state the chosen integration surface
+- list the concrete accounts, banks, and env values the implementation needs
+- call out any unverified addresses, parameters, or bank settings
+- keep examples minimal and directly runnable when possible
+
+## References
+
+- `references/official-development-notes.md`: condensed marginfi development guidance from official docs.
+- `references/source-index.md`: official page index and when to consult each source.

package/marginfi-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Marginfi Development"
+  short_description: "Build or review integrations on the marginfi protocol"
+  default_prompt: "Use $marginfi-development to ground the task in official marginfi docs, choose the correct development surface (TypeScript SDK, Rust CLI, or raw program instructions), load the relevant reference sections, and then implement or explain the smallest correct marginfi integration without guessing bank config, oracle setup, or protocol addresses."

package/marginfi-development/references/official-development-notes.md

@@ -0,0 +1,191 @@
+# Official Marginfi Development Notes
+
+Checked against official marginfi docs on 2026-03-20.
+
+## Canonical official sources
+
+- Docs home: `https://docs.marginfi.com/`
+- TypeScript SDK docs: `https://docs.marginfi.com/ts-sdk`
+- Rust CLI docs: `https://docs.marginfi.com/rust-sdk`
+- Protocol design: `https://docs.marginfi.com/protocol-design`
+- Program docs (`mfi-v2`): `https://docs.marginfi.com/mfi-v2`
+- The Arena docs: `https://docs.marginfi.com/the-arena`
+
+## 1. Protocol model to keep in mind
+
+marginfi is a pooled-balance lending protocol on Solana. The main developer objects are:
+
+- `MarginfiGroup`: protocol-wide configuration and shared state for a deployment.
+- `Bank`: the per-asset pool with oracle config, risk weights, limits, and utilization-driven rates.
+- `MarginfiAccount`: the user's margin account that holds deposits and liabilities across banks.
+
+Important protocol-design facts from the official docs:
+
+- Risk is controlled by asset weights, liability weights, and loan-to-value style constraints.
+- Oracles come from Pyth and Switchboard, with confidence and staleness checks before prices are accepted.
+- Docs mention a maximum oracle staleness of 60 seconds and a 95% confidence interval requirement.
+- Pyth EMA pricing is described as roughly 5,921 slots (about 1 hour) for smoothing.
+- Interest rates use a two-segment utilization curve: rates rise with utilization, then increase more aggressively after the optimal-utilization threshold.
+- Asset risk tiers include collateral-style assets, borrow-only assets, and isolated assets.
+
+Use these facts when reasoning about account health, liquidations, and bank config; do not reduce health checks to simple spot-price math.
+
+## 2. Official addresses and environments
+
+The official docs currently expose these environment values across the docs home and protocol-design pages:
+
+- Mainnet program: `MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA`
+- Mainnet group: `FCPfpHAjHn9R6vWQbtyzcN8PjjobJABQj9rChmC6Cv5j`
+- Staging program: `stag8sTKDs4Df2RehcgddBVAtDx6gbDp7YkA94R6HvK`
+- Staging group: `2rpQwP4ofD6P2AojSeyjc9kUCzjscX4oMtd2N4eySe7W`
+
+Treat these as time-sensitive. Re-check the docs page before hardcoding them in new work.
+
+## 3. TypeScript SDK essentials
+
+Official docs point to the npm package `@mrgnlabs/marginfi-client-v2` plus `@mrgnlabs/mrgn-common` helpers.
+
+Core setup flow from the docs:
+
+1. Create a Solana `Connection`.
+2. Build a wallet adapter or `NodeWallet`.
+3. Load `getConfig("production")` or another environment config.
+4. Call `MarginfiClient.fetch(config, wallet, connection)`.
+5. Fetch existing marginfi accounts for the authority, or create one.
+6. Resolve the target bank, then perform actions.
+
+Minimal example pattern:
+
+```ts
+import { Connection } from "@solana/web3.js";
+import { MarginfiClient, getConfig } from "@mrgnlabs/marginfi-client-v2";
+import { NodeWallet } from "@mrgnlabs/mrgn-common";
+
+const connection = new Connection(process.env.RPC_URL!, "confirmed");
+const wallet = NodeWallet.local();
+const config = getConfig("production");
+const client = await MarginfiClient.fetch(config, wallet, connection);
+
+const accounts = await client.getMarginfiAccountsForAuthority();
+const account = accounts[0] ?? (await client.createMarginfiAccount());
+const bank = client.getBankByTokenSymbol("SOL");
+if (!bank) throw new Error("SOL bank not found");
+
+await account.deposit(1, bank.address);
+```
+
+Useful SDK objects and methods called out in the docs:
+
+- Client bootstrap: `MarginfiClient.fetch`, `getConfig`
+- Bank lookup: `getBankByTokenSymbol`, `getBankByMint`, `getBankByPk`
+- Oracle helpers: `getOraclePriceByBank`
+- Account discovery: `getMarginfiAccountsForAuthority`
+- Account creation: `createMarginfiAccount`
+- Permissionless-bank support: `createLendingPool`
+- Transaction helper: `processTransaction`
+- Margin-account actions on `MarginfiAccountWrapper`: `deposit`, `withdraw`, `borrow`, `repay`, `reload`
+
+Prefer these helpers before assembling raw instructions manually.
+
+## 4. Flash-loan development notes
+
+Official TS SDK docs describe `buildFlashLoanTx` as the preferred helper for building full flash-loan transactions.
+
+The program docs describe flash loans as:
+
+- `lending_account_start_flashloan`
+- user instructions that consume the temporary liquidity
+- `lending_account_end_flashloan`
+
+Important implementation rules:
+
+- Flash loans must begin and end in the same transaction.
+- The end instruction must reference the correct end index.
+- Nested or malformed flash-loan flows are rejected.
+- Relevant program errors include `AccountInFlashloan`, `IllegalFlashloan`, `IllegalFlag`, and `NoFlashloanInProgress`.
+
+If you need raw control, mirror the exact begin/end instruction ordering from the official docs.
+
+## 5. Rust CLI essentials
+
+The Rust CLI docs describe profile-based configuration through `marginfi profile` and account or bank operations through `marginfi group` and `marginfi account` subcommands.
+
+Representative CLI flows from the docs:
+
+- profile and authority setup: `marginfi profile create`, `marginfi profile set`
+- account flows: `marginfi account create`, `deposit`, `borrow`, `withdraw`, `repay`
+- bank and admin flows: `marginfi group add-bank`, `configure-bank`, `collect-fees`, `setup-emissions`, `update-emissions`
+- permissionless-bank creation: `marginfi group add-bank-permissionless`
+
+Use the CLI when the job is operational, administrative, or quick to script from the terminal. Use the TS SDK when embedding marginfi into apps or bots.
+
+## 6. Permissionless banks and The Arena
+
+The Arena docs describe a permissionless flow where developers can create marginfi banks from listed tokens.
+
+Important configuration areas surfaced in the official docs:
+
+- `asset_weight_init` / `asset_weight_maint`
+- `liability_weight_init` / `liability_weight_maint`
+- deposit and borrow limits
+- interest-rate curve parameters such as optimal utilization, plateau rate, max rate, and fees
+- `risk_tier`
+- `operational_state`
+- `oracle_setup`
+
+The official TS docs also show `BankConfigOpt`, `InterestRateConfigOpt`, `OracleSetup`, `RiskTier`, and `OperationalState` in the permissionless-bank example.
+
+When implementing bank creation:
+
+- treat every config field as an explicit input
+- validate the oracle source and required feed accounts
+- keep listing-criteria and The Arena docs open while coding
+- do not fabricate safe defaults for weights or limits
+
+## 7. Program instruction map
+
+The `mfi-v2` docs expose the on-chain instruction set and typed errors.
+
+Key instruction families to consult before raw program work:
+
+- marginfi-group initialization and configuration
+- bank creation and configuration
+- margin-account creation
+- deposit / withdraw
+- borrow / repay
+- emissions setup and update
+- liquidate
+- flash-loan begin / end
+- account transfer flows
+
+Useful error names exposed in the docs include:
+
+- `Unauthorized`
+- `BankNotFound`
+- `MarginfiAccountNotFound`
+- `OperationWithdrawOnly`
+- `IllegalLiquidation`
+- `IllegalFlashloan`
+- `AccountInFlashloan`
+- `NoFlashloanInProgress`
+- `SwitchboardStalePrice`
+- `CannotCloseOutstandingEmissions`
+
+When surfacing failures to users, translate these into the failed business condition instead of echoing raw Solana logs only.
+
+## 8. Security and operational notes
+
+The docs highlight:
+
+- Halborn and Sec3 audits
+- fuzz testing
+- a bug-bounty program
+- verifiable-build support via `solana-verify`
+
+The official verification example is:
+
+```bash
+solana-verify verify-from-repo -um --program-id MFv2hWf31Z9kbCa1snEPYctwafyhdvnV7FZnsebVacA https://github.com/mrgnlabs/marginfi-v2
+```
+
+Use these references when the task touches deployment verification, trust assumptions, or upgrade review.

package/marginfi-development/references/source-index.md

@@ -0,0 +1,31 @@
+# Marginfi Official Source Index
+
+Use this file to jump to the official page that matches the task.
+
+## Primary docs
+
+- `https://docs.marginfi.com/`
+  - Read for current program IDs, group IDs, lookup-table references, and top-level navigation.
+- `https://docs.marginfi.com/ts-sdk`
+  - Read for TypeScript integration, SDK classes, helper methods, and flash-loan or permissionless-bank examples.
+- `https://docs.marginfi.com/rust-sdk`
+  - Read for CLI workflows, operator tasks, profiles, group commands, and bank administration.
+- `https://docs.marginfi.com/protocol-design`
+  - Read for risk model, oracle rules, utilization-based interest design, and liquidation reasoning.
+- `https://docs.marginfi.com/mfi-v2`
+  - Read for raw instruction names, account schemas, and error definitions.
+- `https://docs.marginfi.com/the-arena`
+  - Read for permissionless-bank flows and links to listing criteria.
+
+## When to open which source
+
+- App, bot, backend, or frontend integration: start with `ts-sdk`, then `protocol-design`.
+- CLI or ops automation: start with `rust-sdk`.
+- Custom Anchor or raw Solana instruction work: start with `mfi-v2`.
+- Health checks, liquidation analysis, or risk explanations: start with `protocol-design`, then confirm relevant instruction behavior in `mfi-v2`.
+- Permissionless bank creation: start with `the-arena`, then open `ts-sdk` or `rust-sdk` depending on the chosen toolchain.
+- Address or deployment verification: start with the docs home page, then follow its linked source or verification references.
+
+## Working rule
+
+If the request depends on a value that can change over time, reopen the live official page even if this skill already contains a summary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.4.3",
+  "version": "2.6.0",
   "description": "Apollo Toolkit npm installer for managed skill linking across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",