kira-wallet 0.1.12 → 0.1.14

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
@@ -48,12 +60,16 @@ def enrich(snapshot,market,folder,deadline=None):
     networks=json.loads((h.ASSETS/'sources/rpc-candidates.json').read_text())
     input_path=folder/'reserve-graph-input.json'
     atomic(input_path,{'wallet':snapshot['wallet_address'],'tokens':snapshot['tokens'],'networks':networks,
-        'market_budget_ms':max(0,int((deadline-time.monotonic())*1000)) if deadline is not None else 180_000})
+        # Leave time for Node startup and the final atomic graph publication
+        # before the parent's hard stop. Completed checkpoints remain useful.
+        'market_budget_ms':max(0,int((deadline-time.monotonic()-1)*1000)) if deadline is not None else 180_000})
     run_node('reserves',input_path,folder/'reserve-graph.json',deadline=deadline)
     recorded=json.loads((folder/'reserve-graph.json').read_text());graph=recorded['tokens']
     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,78 @@
 # 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
 
-```sh
-mkdir -p ~/.config/kira
-touch ~/.config/kira/alchemy.env
-chmod 600 ~/.config/kira/alchemy.env
-```
-
-Open the file in a local text editor. On macOS, you can use:
-
-```sh
-open -e ~/.config/kira/alchemy.env
-```
-
-Add this line, replacing `YOUR_KEY` inside the editor:
-
-```dotenv
-ALCHEMY_API_KEY=YOUR_KEY
-```
-
-Save the file, then run:
+Run this in your terminal:
 
 ```sh
-kira config import-env --file ~/.config/kira/alchemy.env
+kira connect alchemy
 ```
 
-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.
+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.
+
+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.
+
+## 3. Add or refresh a wallet
+
+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.
+
+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.
+
+Price responses also supply artwork by network and contract. Kira reuses that
+metadata instead of requiring another successful lookup for the same logo.
+Completed reserve-price paths remain usable when a bounded pass pauses;
+unfinished paths keep their original unknown state.
+Further reserve traversal focuses on funded curves whose USD price is still
+unknown. Bounded checks leave time to save their completed results.
+
+**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.
+
+Kira makes requests locally through your account. Review Alchemy’s current
+[plans and limits](https://www.alchemy.com/docs/reference/pricing-plans).
+
+The research engine spaces its private Alchemy node reads at least 250 ms apart
+in one shared lane across Alchemy networks. An Alchemy throughput response cools
+that lane before queued reads can use another Alchemy host. Public and other
+custom RPC endpoints keep their existing pacing and fallback behavior. Canonical
+block checks and provider backoff still apply. This is a local scheduling policy,
+not a guarantee about an account's available capacity. Alchemy's
+[throughput allowance is shared across apps and chains](https://support.alchemy.com/articles/3788245542-is-alchemy-s-throughput-cu-s-limit-shared-across-all-apps-or-set-per-chain).

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