kira-wallet 0.1.12 → 0.1.13

package/README.md

@@ -43,15 +43,16 @@ For a viewer without wallet or research actions, use `kira start --read-only`.
 Prefer an archive? [GitHub releases](https://github.com/realproject7/kira-wallet/releases/tag/v0.1.2)
 include the same package and its checksum.
 
-1. **Review optional coverage.** Free research is enabled by default. In **Workspace settings**, connect Alchemy for broader
-   ERC20 discovery. Free token sources have limited coverage; incomplete coverage
-   stays visible. An AI or browser wallet connection does not enable an indexer.
-2. **Add a watching wallet.** Paste a public address and give it a name. Add more
-   wallets whenever you need them. The form starts free research of native, common tokens and Mint Club assets, with keyless ERC20 transfer discovery on Ethereum, Base, Optimism, Arbitrum, Polygon and BNB. RPC checks candidate balances; unfinished history remains visible. First balances appear before detailed research finishes.
-   The basic scan saves usable results first. Choose **Start deep scan** for
-   additional discovery and one representative sell estimate per asset. Deep
-   scans show saved asset checks, available prices and unresolved checks. Pause
-   and resume from saved work at any time. Unknown coverage stays visible.
+1. **Connect Alchemy.** Alchemy supplies the token index across networks.
+   Open **Connect Alchemy** in Kira and follow the [simple setup guide](docs/ALCHEMY_SETUP.md).
+   Run `kira connect alchemy` in your terminal and enter your app key at the
+   hidden prompt. The key stays in a private local file. No wallet key is needed.
+2. **Add a watching wallet.** Paste a public EVM address and give it a name.
+   Kira checks every configured network and all discovered token candidates,
+   including the full reachable Mint Club registry. There is no 128-candidate
+   limit. Balances appear as they are checked; prices and artwork follow.
+   **Analyze sell routes** is optional. It estimates sales and redemptions from
+   saved holdings and does not discover more tokens. Pause and resume work in Activity.
 3. **Connect your AI.** Install and sign in to the
    [Codex CLI](https://developers.openai.com/codex/cli) or
    [Claude Code](https://code.claude.com/docs/en/quickstart), then choose your
@@ -144,13 +145,17 @@ Original code and Kira character assets are available under the [MIT license](LI
 Third-party artwork and references retain their own terms; see
 [Third-party notices](THIRD_PARTY_NOTICES.md).
 
-### Token coverage and optional Alchemy setup
+### Alchemy and token coverage
 
-Kira uses free public RPC with bounded fallback and checks a selected common-token
-list alongside native assets and Mint Club. Other ERC20 holdings can be missing.
-Incomplete results show recovery guidance on Home and the wallet page. Connect
-your own Alchemy account for broader discovery on supported networks, then
-refresh holdings. Public RPC remains the first choice for ordinary reads;
-Alchemy is a backup and supplies the dedicated token inventory API. See the
-[step-by-step Alchemy guide](docs/ALCHEMY_SETUP.md) and
-[RPC behavior](docs/FREE_RPC.md).
+An Alchemy connection is required for new holdings and price lookups. Alchemy
+RPC is preferred on configured supported networks; verified public endpoints
+remain a fallback where allowed. Dedicated indexes provide token candidates,
+then on-chain reads verify balances. Other configured networks still receive
+native and Mint Club registry checks, plus an available explorer index.
+Unsupported discovery and failed reads remain unknown.
+
+DEX spot prices require at least $1,000 of source-reported pool liquidity.
+Extremely one-sided pools are also excluded. This is a conservative estimate
+policy, not a claim that holdings can be sold at the displayed price. Saved
+thin-pool quotes are excluded from totals without changing their raw evidence.
+See the [Alchemy setup guide](docs/ALCHEMY_SETUP.md).

package/THIRD_PARTY_NOTICES.md

@@ -43,3 +43,7 @@ token safety, current balance, value or an exhaustive inventory. No service SDK
 or credential is distributed. Selected new known identities use issuer documents,
 PancakeSwap integration references and freshly verified on-chain metadata; their
 per-contract provenance is in the catalog.
+
+## Alchemy setup illustration
+
+`viewer/static/alchemy-create-app.png` is an unmodified example screenshot from Alchemy’s public API key walkthrough, used to explain app setup. Source: https://www.alchemy.com/docs/create-an-api-key . The image contains no Kira operator account or credential. Alchemy retains rights to its interface and illustration.

package/curve_pricing.py

@@ -12,13 +12,21 @@ def resolve(graph, prices):
     nodes={(r['chain_id'],r['address'].lower()):r for r in graph if r.get('address')}
     known={(r['chain_id'],r['address'].lower()):r for r in prices}
     cache={}
+    def rejected_reserve(key,seen):
+        if key in seen:return False
+        node=nodes.get(key);price=known.get(key)
+        if not node or not node.get('is_curve'):return bool(price and price.get('quality')=='unreliable')
+        if price and price.get('usd') is not None and price.get('basis')!='Curve spot' and price.get('quality') not in ('unfunded','unreliable'):return False
+        return rejected_reserve((key[0],node['reserve_token'].lower()),seen|{key})
     def visit(key,seen):
         if key in cache:return cache[key]
         if key in seen:return None
         existing=known.get(key)
         node=nodes.get(key)
+        if existing and existing.get('quality')=='unreliable' and not (node and node.get('is_curve')):
+            cache[key]={**existing,'usd':None};return cache[key]
         unfunded=node and not node.get('error') and node.get('is_curve') and node.get('funded') is False
-        if existing and existing.get('usd') is not None and existing.get('quality') not in ('unfunded','unreliable') and (existing.get('basis')!='Curve spot' or not unfunded):
+        if existing and existing.get('usd') is not None and existing.get('quality') not in ('unfunded','unreliable') and (existing.get('basis')!='Curve spot' or not unfunded and not rejected_reserve(key,set())):
             cache[key]=existing;return existing
         if not node or node.get('error') or not node.get('is_curve'):return None
         if not node['funded']:
@@ -27,6 +35,10 @@ def resolve(graph, prices):
                     'observed_at':node.get('observed_at'),'block_number':node.get('block_number')}
             cache[key]=record;return record
         parent=visit((key[0],node['reserve_token'].lower()),seen|{key})
+        if parent and parent.get('quality')=='unreliable':
+            record={'chain_id':key[0],'address':node['address'],'usd':None,'basis':'Curve spot','quality':'unreliable',
+                    'source':node.get('source'),'observed_at':node.get('observed_at'),'block_number':node.get('block_number')}
+            cache[key]=record;return record
         if not parent or parent.get('usd') is None:return None
         usd=float(node['price_in_reserve'])*parent['usd']
         if not math.isfinite(usd) or usd<0:return None
@@ -54,6 +66,8 @@ def enrich(snapshot,market,folder,deadline=None):
     if recorded.get('market_pending'):raise MarketPause('Reserve checks reached the market time budget. Resume saved checks in Activity.')
     ordinary=[r for r in graph if r.get('address') and r.get('is_curve') is False and r['chain_id'] in ALCHEMY]
     prices=list(market.get('tokens',[]))
+    rejected={(p['chain_id'],p['address'].lower()) for p in prices if p.get('quality')=='unreliable'}
+    ordinary=[r for r in ordinary if (r['chain_id'],r['address'].lower()) not in rejected]
     # Only reserve assets are requested. Identify prices by network and contract, never symbol.
     requests=[{'network':ALCHEMY[r['chain_id']],'address':r['address']} for r in ordinary]
     inverse={value:key for key,value in ALCHEMY.items()}

package/docs/ALCHEMY_SETUP.md

@@ -1,103 +1,63 @@
 # Connect Alchemy to Kira
 
-Kira works with free public RPC by default. It checks native assets, selected
-common token contracts and the Mint Club registry, and uses keyless transfer
-discovery on supported networks. Unfinished history and other ERC20 holdings
-may still be missing. For broader token discovery, connect your own Alchemy account.
-Kira runs these requests locally and does not operate a hosted relay.
+Alchemy supplies the token index Kira uses across networks. Kira requires your
+own Alchemy connection for new holdings and price research. No wallet keys,
+seed phrase, signature or spending permission is needed.
 
-## Create an Alchemy app
+The app includes a screenshot guide at `/alchemy-guide.html`, linked from
+**Connect Alchemy**. Its dashboard illustration is Alchemy’s published example;
+it contains no Kira operator account or key.
 
-1. Sign in to the [Alchemy dashboard](https://dashboard.alchemy.com/).
-   A new account may already have a default app. Use it, or open your team
-   menu, Team Overview, Apps, then Create new app.
-2. Name the app and select the mainnets you want to research. Check that the
-   app has Node API and Portfolio API access for those networks. Create it.
-3. Copy the app API key. The Endpoints tab shows its network URLs. Kira's
-   combined Alchemy setup needs the key, so you do not need to copy each URL.
+## 1. Get your app key
 
-These steps follow Alchemy's [official API key guide](https://www.alchemy.com/docs/create-an-api-key),
-checked on October 9, 2026. Dashboard wording can change.
+Open the [Alchemy dashboard](https://dashboard.alchemy.com/). A new account may
+already have a default app. Use it or choose **Apps → Create new app**. Enable
+the networks you use and confirm Node API and Portfolio API access. Copy the
+app API key from its details page. You do not need separate endpoint URLs.
 
-## Connect the key locally
+These steps follow the [official walkthrough](https://www.alchemy.com/docs/create-an-api-key).
+Dashboard labels can change. Review your account’s API access and usage limits.
 
-Create a private directory and file in your terminal:
+## 2. Connect locally
+
+Run this in your terminal:
 
 ```sh
-mkdir -p ~/.config/kira
-touch ~/.config/kira/alchemy.env
-chmod 600 ~/.config/kira/alchemy.env
+kira connect alchemy
 ```
 
-Open the file in a local text editor. On macOS, you can use:
+Paste the key at the hidden prompt and press Enter. Kira stores it in a private
+local file and queues the connection setup. The key never appears in the
+command, browser, chat, public job or analysis.
 
-```sh
-open -e ~/.config/kira/alchemy.env
-```
+For another workspace, use `kira --data-dir /path/to/workspace connect alchemy`.
+For an existing environment file, `kira config import-env --file PATH` retains
+that file reference. Add `--key-env NAME` when its variable has a different name.
+The browser’s advanced option accepts the variable name only.
 
-Add this line, replacing `YOUR_KEY` inside the editor:
+## 3. Add or refresh a wallet
 
-```dotenv
-ALCHEMY_API_KEY=YOUR_KEY
-```
+Return to Kira and choose **Check connection**. Add a public wallet, or refresh
+holdings for an existing wallet. A found local key does not prove every API or
+network is available; the holdings results record actual access and gaps.
 
-Save the file, then run:
+Each holdings lookup checks every configured network and all returned token
+candidates. Reachable Mint Club registries are enumerated too. There is no
+128-candidate cutoff. Unsupported indexes, failed balances and missing prices
+or artwork remain unknown.
 
-```sh
-kira config import-env --file ~/.config/kira/alchemy.env
-```
+**Analyze sell routes** is optional. It uses the saved balances and their
+original blocks to estimate a representative sale or redemption. It is not
+required for tokens, prices or logos and does not expand the holdings inventory.
+
+## Troubleshooting
+
+- Run the command in the workspace you are viewing.
+- Check the app’s networks, Node API, Portfolio API and usage in Alchemy.
+- Retry holdings after access or provider errors are resolved.
+- An unsupported network can still have native or Mint Club balances. An indexer
+  cannot guarantee every arbitrary token, and another provider cannot restart
+  a retired network.
 
-For a non-default workspace, supply its existing `--data-dir` before `config`.
-Kira stores the file reference. Credentials stay outside the browser, chat and
-published analysis. Do not commit this file to a repository. A process
-environment variable with the same name overrides the file value; check that
-if an old key remains active.
-
-If detailed research is running, import-env queues a Local connection setup
-job in Activity. The writer pauses safely, applies the file reference, and
-resumes detailed research automatically. Wait for the setup job to complete,
-then recheck the connection. The public job contains no key value or file path.
-A legacy CLI analysis keeps its writer lock; its queued setup waits until that
-analysis finishes or is stopped.
-
-## Check the connection and refresh
-
-Open Workspace settings, then Manage data connection. Select Alchemy and use
-"I added my key · check again". Save the connection. Finding the local key
-does not prove the account, API or network is working.
-
-For an existing wallet, choose Refresh this wallet's holdings or Refresh
-holdings on its page. A new analysis confirms access and coverage. Old saved
-analyses retain their original observations and warnings. Saving a connection
-does not register a wallet or start research automatically.
-
-## What uses the key
-
-Ordinary balances prefer public RPC. After two failed or unavailable public
-providers, Kira tries the configured custom backup within the read deadline.
-Advanced settings can choose custom first or require custom only. Existing
-explicit custom-only restrictions remain in force.
-
-Alchemy token discovery uses the key directly. Standard public RPC cannot
-enumerate arbitrary ERC20 holdings. Kira uses Alchemy's
-[Tokens By Wallet endpoint](https://www.alchemy.com/docs/data/portfolio-apis/portfolio-api-endpoints/portfolio-api-endpoints/get-tokens-by-address),
-then verifies discovered candidates with on-chain balance reads.
-
-## If tokens are still missing
-
-- **Local key unavailable:** confirm the file exists, its variable name matches
-  the connection settings, and you ran the import command in the right workspace.
-- **Discovery failed:** check the app's enabled APIs and networks and Alchemy's
-  usage dashboard. Correct access or limits, then retry holdings.
-- **Some balances could not be checked:** wait briefly and retry. Public and
-  custom providers both have outages and limits. Review Advanced read preferences
-  if a custom-only endpoint is unavailable.
-- **Unsupported network:** broader discovery is unavailable there. Connecting
-  Alchemy cannot cover every network or every token. Known-contract reads remain
-  useful, and missing holdings remain unknown.
-
-Alchemy has account allowances and throughput limits. Check the current
-[plans](https://www.alchemy.com/docs/reference/pricing-plans) and API availability
-before selecting a plan. Kira does not create an account, subscribe or upgrade
-it. Public-first balance reads reduce ordinary use of the key; discovery still
-consumes Alchemy allowance. No connection guarantees a complete token inventory.
+Kira makes requests locally through your account. Review Alchemy’s current
+[plans and limits](https://www.alchemy.com/docs/reference/pricing-plans).

package/docs/CLI.md

@@ -17,17 +17,22 @@ Registry publication remains an operator action. The code and original character
 
 ## Lifecycle
 
-Wallet registration and holdings refresh run a basic scan first. Use the saved
-result immediately, then choose **Start deep scan** in the wallet or Activity
-to check remaining networks and more complex markets. Deep scanning is optional,
-has no overall time limit, and supports **Pause scan** and **Resume deep scan**.
-It runs while Kira is running on this computer. App restart preserves saved
-results and requires an explicit resume for interrupted work.
-
-CLI equivalents are `kira jobs deepen BASIC_JOB_ID`, `kira jobs cancel JOB_ID`
-and `kira jobs resume JOB_ID`. A repeated deepen request uses the same child;
-it does not restart paused or finished work. Refreshing holdings starts a new
-basic scan. Neither basic nor deep completion guarantees all holdings or prices.
+Connect Alchemy once with `kira connect alchemy`. The operator enters the app
+key at a hidden terminal prompt. New wallet and price research requires this
+connection; saved portfolios remain readable without it.
+
+Wallet registration and holdings refresh check every configured network and all
+returned candidates, including the reachable Mint Club registry. There is no
+128-candidate cap. Saved balances appear as checks finish; price and artwork
+lookup is independent of optional sell analysis.
+
+Choose **Analyze sell routes** only for sale or redemption estimates. Internally,
+`kira jobs deepen HOLDINGS_JOB_ID` admits one child using that wallet’s immutable
+holdings source. It does not discover tokens or reread balances. Use `kira jobs
+cancel JOB_ID` to pause and `kira jobs resume JOB_ID` to continue. A newer holdings
+lookup supersedes earlier analysis. Old limited scans require a holdings refresh
+before the new sell-analysis action. Slices remain bounded, with no overall
+completion deadline or exhaustive-market guarantee.
 
 Use `kira setup` for your first setup. For everyday use, `kira start` starts
 the local app with browser controls and opens it in your browser. The default
@@ -58,12 +63,10 @@ Published 0.1.4 explains limited discovery before wallet registration and beside
 holdings. Missing coverage keeps the portfolio estimate partial. Existing snapshots require a holdings refresh after connecting
 an indexer; a price refresh does not discover missing tokens.
 
-Free research checks known assets, Mint Club and keyless token candidates on supported networks. Alchemy is optional. For broader ERC20 discovery,
-open Custom RPC & token coverage, select Alchemy and follow its local key guide.
-Published 0.1.5 uses one save for Alchemy RPC and discovery; chain overrides
-remain under Advanced. Never paste the key into the browser. `kira doctor`
-checks whether the configured key is available. Configuration alone does not
-prove complete coverage; inspect the recorded results and gaps.
+Alchemy is required for new research. Open **Workspace settings → Alchemy** and
+follow the [setup guide](ALCHEMY_SETUP.md). Alchemy reads run first; verified
+public RPC remains an allowed fallback. Existing custom-only preferences are
+preserved. Missing networks and token prices remain explicit in saved results.
 
 Connecting Codex or Claude is optional. Use Connect your AI when ready, verify
 a generic response and explicitly choose context permissions. Assistant answers
@@ -80,10 +83,11 @@ authentication. Verified adapter versions are Codex 0.158.x and Claude Code
 verified. This is a native CLI connection, with no Kira account, API-key proxy or
 hosted portfolio backend.
 
-From published 0.1.5, setup opens the existing Account / Permissions / Ready
-modal directly. Choose Codex or Claude, then Use default model or a readable
-model choice. Codex choices come from bounded native metadata; Claude offers
-Sonnet, Opus and Haiku aliases. A catalog is not proof of account access.
+Setup leaves the wallet checklist visible. Choose **Connect AI** or **Connect a
+model** to open the Account / Permissions / Ready modal. Choose Codex or Claude,
+then Use default model or a readable model choice. Codex choices come from
+bounded native metadata; Claude offers Sonnet, Opus and Haiku aliases. A catalog
+is not proof of account access.
 Advanced accepts a custom identifier and preserves saved identifiers absent
 from the catalog. Workspace settings reopens the same selector and permissions. Choose no automatic wallet context, one registered wallet,
 or the whole recorded portfolio. A generic response check sends no wallet data
@@ -114,7 +118,6 @@ assets and writable runtime files use separate roots.
 
 ```sh
 kira rpc public
-kira discovery none
 kira doctor
 kira doctor --live --chains 1,8453,81457 --budget 30
 ```
@@ -225,11 +228,11 @@ original encryption passphrase. No signing, key export or account deletion
 endpoint is exposed. OWS absence does not block ordinary address or browser
 wallet onboarding.
 
-## Free reads and broader token coverage
+## Provider reads and coverage
 
-Public RPC is preferred for ordinary reads, including when a custom backup is
-configured. Advanced settings can select custom first or custom only. For CLI
-configuration, use `kira rpc set --chain 8453 --url-env KIRA_BASE_RPC --priority
-public_first`. Existing custom-only choices remain unchanged. Alchemy token
-discovery uses the configured key directly. See [free RPC behavior](FREE_RPC.md)
-and the [Alchemy setup guide](ALCHEMY_SETUP.md).
+Alchemy token discovery uses your key directly. Configured Alchemy RPC reads
+run before public fallback. The browser exposes one Alchemy connection rather
+than free and expanded modes. Existing low-level RPC references remain available
+through the CLI. See [Alchemy setup](ALCHEMY_SETUP.md). `FREE_RPC.md` retains the
+historical free-discovery implementation and its evidence; it is not the current
+onboarding policy.

package/docs/FREE_RPC.md

@@ -1,4 +1,11 @@
-# Free RPC reads and token coverage
+# Historical free RPC reads and token coverage
+
+Current research requires Alchemy. Holdings check every configured network and
+all returned candidates with full reachable Mint Club enumeration. Alchemy reads
+run first. Sell analysis is optional and uses saved holdings only. See
+[Alchemy setup](ALCHEMY_SETUP.md). The free-discovery policies and acceptance
+limits below are retained as historical implementation evidence, not current
+onboarding defaults.
 
 Kira contacts public providers directly from the local research process. No
 Kira relay or shared credential is required. Free public services are best
@@ -147,6 +154,9 @@ RPC-verified balances. Other Routescan chains are not presumed supported.
 Explicit keyless opt-outs and custom-only preferences remain respected.
 
 Initial reports check Base, Ethereum and Blast, up to 128 candidates per chain.
+This scheduling scope also applies to Alchemy discovery. It is not a three-chain
+limit of public RPC. Initial price and artwork metadata has a separate bounded
+lookup, so unfinished sell-estimate research cannot suppress those lookups.
 Selected common contracts take priority. Remaining candidates and networks are
 explicitly pending. A user-selected deep scan checks every configured
 network, its recorded inventory policy and markets. In full mode, pinned registry counts,

package/docs/JOB_CONTRACT.md

@@ -187,37 +187,38 @@ secret value is copied into the request, receipt, viewer or model context.
 Explicit cancellation survives recovery and exception boundaries as stopped.
 A completed publication receipt still wins a cancellation race.
 
-## Basic scans and optional deep scans
-
-New wallet.add and wallet.refresh jobs have scan_policy: optional_depth_v1.
-The basic scan checks initial balances on Base, Ethereum and Blast and publishes
-usable results. Finishing a basic scan does not start more provider work.
-Unstarted legacy parents also do not acquire new child jobs on app restart.
-The viewer presents the result as "Basic scan ready", with coverage gaps visible.
-
-An explicit job.deepen request targets a succeeded or partial baseline with a
-saved result. It admits exactly one enrichment child per parent under the
-request lock. Concurrent clicks, new request keys and restart recovery all
-return that same child, including a previously paused child. A separate explicit
-job.resume is required to resume it. A newer basic generation rejects starting
-or resuming old deep work. No saved balances are copied into a new analysis.
-
-A deep scan has no overall twenty-minute completion deadline. It keeps the
-bounded, checkpointed engine slices, provider backoff, single writer,
-short-operation priority and no-progress protection described above.
-"Pause scan" uses job.cancel to stop the current worker and retain results and
-checkpoints. "Resume deep scan" requeues the same job. Publication still wins a
-pause race. Finished partial results describe unknown coverage, not failure to
-meet a time target or proof of exhaustive holdings.
-
-The wallet card and Activity restore their state from persisted jobs. Buttons
-require the existing protected local session and are disabled while disconnected,
-submitting or pausing. Sample and watch-only workspaces cannot start scans.
-Current-step bars use actual bounded counts. Unknown totals have no percentage.
-Only a stable measured step may show an expiring ETA range; overall time remains
-unknown. progress_observed_at advances on actual checked work or a saved initial
-publication, not repeated errors or provider waits. Quiet and disconnected states
-are explicit. Live announcements concern state transitions, not every count.
+## All-network holdings and optional sell analysis
+
+New wallet.add and wallet.refresh jobs record `scan_policy: alchemy_inventory_v1`.
+They require a configured local Alchemy key before registration or provider work.
+The internal baseline phase invokes `wallet.py --phase holdings`: every configured
+network, all indexer candidates, and full reachable Mint Club registry enumeration.
+The 128-read batch size remains an RPC payload bound, never a token-inventory cap.
+Newly checked chains are published progressively as immutable initial snapshots.
+Initial token prices stay unknown until the metadata pass checks them. Alchemy
+artwork can appear immediately. Final holdings include bounded price and artwork
+lookup without market-route analysis.
+
+An explicit `job.deepen` admits one enrichment child per current holdings parent.
+It invokes `--phase sell --holdings-snapshot SNAPSHOT`. The source must belong to
+that wallet and have `pipeline.phase: holdings`. Its balances, blocks and clocks
+are copied into the new analysis without running discovery, registry scans or
+balance refresh. Route checks use those recorded blocks. Partial historical
+scans require a new holdings lookup first. New holdings supersede older analysis.
+
+Pause and resume preserve the same job and its evidence. App restart requires
+explicit resume for queued or interrupted scans. Market slices, provider pacing,
+short-operation priority, immutable publication and no-progress protection remain.
+There is no overall twenty-minute deadline. Finite route work never proves every
+market has been searched. The viewer calls this optional action **Analyze sell
+routes**; holdings, token prices and artwork do not depend on it.
+Pending or failed route checks stay in sell-analysis progress and do not
+invalidate the saved holdings coverage.
+
+Current-step bars use real counts. Unknown durations have no ETA or percentage.
+Detailed stages remain in Activity; chat has one collapsed status line. Review
+not selected for this operator-authorized change. Earlier free-scan paragraphs
+in this contract are historical and do not override this section.
 
 ### Asset-focused market review
 

package/docs/RELEASE.md

@@ -79,7 +79,7 @@ The earlier unpublished 0.1.2 candidate is preserved in the ignored
 `dist/preserved-0.1.2-bad8f02/` directory. Use the current `dist/release.json`
 and its matching archive for publication; do not mix manifests from candidates.
 
-Keep published GitHub tags, release assets and npm versions through 0.1.11
+Keep published GitHub tags, release assets and npm versions through 0.1.12
 immutable. Do not rebuild them from later documentation commits. Future package
 changes need a new version. Release preparation does not publish a GitHub
 release, promote the website or publish to npm.
@@ -95,12 +95,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.12.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.13.tgz`. The ignored `dist/release.json` records its source
 commit, SHA-256 and member count. It never publishes. After reviewing that
 manifest, the operator's final command from the project root is:
 
 ```sh
-npm publish ./dist/kira-wallet-0.1.12.tgz --access public
+npm publish ./dist/kira-wallet-0.1.13.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
@@ -269,7 +269,7 @@ Use only the archive matching the final `dist/release.json` source commit,
 SHA-256 and installed member hashes. A registry dry run does not publish or
 establish registry credentials. Registry publication remains operator-only.
 
-## Release candidate: 0.1.12
+## Published 0.1.12
 
 This release consolidates the completed PR20 through PR29 stack into the default
 release branch. It includes the native HTML showcase, simpler local startup and
@@ -298,3 +298,53 @@ Prepare the final archive only after the release source has landed. Its exact
 commit and hashes belong in `dist/release.json`. Actual npm publication remains
 operator-only. Personal installations and paused automation are separate from
 release preparation.
+
+## Release candidate: 0.1.13
+
+Version 0.1.13 requires a locally available Alchemy key reference before wallet
+research. `kira connect alchemy` accepts the key privately in an interactive
+terminal. Onboarding has two steps, connecting Alchemy and adding a wallet,
+with an included guide using a public blank Alchemy example. AI connection is
+optional and its dialog opens only after an explicit connection action. Chat
+research status is a collapsible single line.
+
+Default holdings research attempts all 18 configured mainnets and six testnets.
+It checks every discovered, prior or known candidate and the available Mint Club
+registry. There is no 128-token candidate limit; 128 remains an RPC payload batch
+size. Failed network access and unavailable indexers remain explicit unknowns.
+This is not a guarantee of complete discovery on arbitrary EVM networks. Testnet
+values never enter portfolio USD totals. Existing limited snapshots need a new
+holdings refresh to gain the restored inventory coverage.
+
+Default holdings, prices and artwork do not require a deep scan. Optional
+`Analyze sell routes` reuses the same wallet's immutable saved balances, blocks
+and observation times. It researches liquidation paths without rediscovering
+tokens or refreshing balances. Bounded engine slices, provider pacing, pause,
+resume and no-progress protection remain. It has no overall time limit.
+
+Prices from DEX pools below USD 1,000 liquidity, or explicitly one-sided pools,
+cannot contribute to portfolio totals. Rejected reserve prices cannot reappear
+through cached indexer or dependent curve estimates. Balances remain visible
+with unknown USD values. Valid spot estimates still do not establish executable
+sale proceeds. Price-only updates preserve immutable holdings and prior market
+records, reuse fresh batched curve facts and publish explicit partial results
+when a bounded lookup cannot finish.
+
+Artwork uses chain and contract identity with Mint Club and Alchemy sources,
+including allowed Alchemy and CoinMarketCap hosts. The Mint Club image fallback
+retries once before initials. No original image is promised for an unknown token.
+Failed Mint Club detail batches receive one smaller retry, and remaining errors
+keep coverage partial rather than silently becoming completed records.
+
+The source in PR31 passed the full suite, clean installation and actual-wallet
+holdings, price, artwork and sell-only pause/resume checks. Release preparation
+reruns the required suite and clean installation, scans tracked source and
+history, and compares every final archive member with the landed source and
+its isolated installation. Product acceptance may be reused only for identical
+product bytes. Preserve raw history findings and apply only the exact normal
+CLI merge-metadata acceptance described above. Review not selected.
+
+Prepare the final archive from the landed version PR. Freeze its source commit,
+SHA-256 and member hashes, then dry-run that exact archive. npm publication is
+operator-only. Do not upgrade the personal app, resume paused automation,
+publish a GitHub release or deploy the website during preparation.

package/kira_agent.py

@@ -24,6 +24,7 @@ PROVIDERS = {
 }
 CODEX_DISABLED = ('shell_tool', 'unified_exec', 'shell_snapshot', 'apps', 'plugins', 'remote_plugin', 'browser_use', 'browser_use_external', 'computer_use', 'image_generation', 'view_image', 'multi_agent', 'hooks', 'memories', 'skill_search', 'skill_mcp_dependency_install', 'code_mode', 'code_mode_host', 'goals')
 SYSTEM = ('You are Kira, a careful wallet research partner. Answer in the language of the user. '
+    'Alchemy connection is required for new holdings and price research. Holdings lookups cover every configured network without a 128-candidate cap. Sell-route analysis is optional and uses saved holdings; it is not needed for token discovery, prices or artwork. '
     'Use only the provided recorded facts. Unknown data is not zero. Preserve chain and contract identities, '
     'observation times, coverage gaps, and the difference between curve spot estimates and executable prices. '
     'The current recorded context supersedes older facts in the conversation. '

package/kira_cli.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 from pathlib import Path
 import shutil
 import signal
@@ -144,6 +145,22 @@ def sample(root):
     atomic(root/'wallets.json',{'schema_version':1,'demo':True,'wallets':[{'address':address,'address_key':address,'tags':['Demo wallet'],
         'latest_snapshot':{'directory':folder,'result':folder+'/results.json'}}]})
 
+def connect_alchemy(root):
+    """Only the operator types the key, at a hidden terminal prompt."""
+    import getpass
+    from kira_jobs import JobStore
+    if not sys.stdin.isatty():raise ValueError('Run kira connect alchemy in an interactive terminal. The API key is entered privately there.')
+    key=getpass.getpass('Alchemy API key (hidden): ').strip()
+    if not key or len(key)>512 or not re.fullmatch(r'[A-Za-z0-9_-]+',key):raise ValueError('Enter the app API key, without an endpoint URL.')
+    directory=root/'.secrets';directory.mkdir(mode=0o700,exist_ok=True)
+    if directory.is_symlink():raise ValueError('The private key directory must not be a symlink.')
+    import tempfile
+    fd,name=tempfile.mkstemp(prefix='alchemy-',suffix='.env',dir=directory)
+    with os.fdopen(fd,'w') as stream:
+        stream.write('ALCHEMY_API_KEY='+key+'\n');stream.flush();os.fsync(stream.fileno())
+    store=JobStore(root);job=store.queue_import(name,'ALCHEMY_API_KEY');store.launch()
+    print(json.dumps({'status':'configuration_queued','job_id':job['job_id'],'note':'Your key is stored privately on this computer. Return to Kira and check the connection.'}))
+
 def main():
     parser=argparse.ArgumentParser(description=__doc__)
     parser.add_argument('--data-dir',default=os.environ.get('KIRA_DATA_DIR',str(Path.home()/'.local/share/kira-wallet')))
@@ -157,6 +174,7 @@ def main():
     setup=sub.add_parser('setup');setup.add_argument('--port',type=int,default=8787);setup.add_argument('--no-open',action='store_true')
     sub.add_parser('stop');sub.add_parser('status');sub.add_parser('wallets')
     sub.add_parser('tools')
+    connection=sub.add_parser('connect');connection.add_argument('provider',choices=['alchemy'])
     d=sub.add_parser('doctor');d.add_argument('--live',action='store_true');d.add_argument('--chains',default='1,8453,81457');d.add_argument('--budget',type=int,default=30)
     demo=sub.add_parser('demo');demo.add_argument('--port',type=int,default=8790)
     add=sub.add_parser('add');add.add_argument('address');add.add_argument('--tag',required=True);add.add_argument('--resume')
@@ -204,7 +222,8 @@ def main():
     from kira_config import load_config,config_path,redact
     try:
         initialize(root)
-        if args.command=='init':print(json.dumps({'status':'initialized','rpc_mode':load_config()['rpc']['mode']}))
+        if args.command=='connect':connect_alchemy(root)
+        elif args.command=='init':print(json.dumps({'status':'initialized','rpc_mode':load_config()['rpc']['mode']}))
         elif args.command=='start':
             url=start(root,args.port,args.controls)
             if not args.no_open:
@@ -215,7 +234,7 @@ def main():
             if not args.no_open:
                 import webbrowser
                 webbrowser.open(url)
-            print(json.dumps({'setup_url':url,'note':'Choose your native CLI account and context permissions in the local setup screen.'}))
+            print(json.dumps({'setup_url':url,'note':'Connect Alchemy, then add a public wallet. AI connection is optional.'}))
         elif args.command=='stop':stop(root)
         elif args.command=='status':
             item=live_record(root);print(json.dumps({'status':'running' if item else 'stopped','url':f"http://127.0.0.1:{item['port']}" if item else None}))