kira-wallet 0.2.1 → 0.2.2

package/README.md

@@ -15,7 +15,7 @@ web app to manage wallets, inspect token markets and follow research. Your
 existing AI agent can use the same records and actions through the Kira CLI or
 optional MCP connection, then open the web app beside your conversation.
 
-**This branch prepares 0.2.1.** Kira now supplies wallet tools and a full-window
+**This branch prepares 0.2.2.** Kira now supplies wallet tools and a full-window
 management app. Your agent host manages its own conversations, models, files and
 approvals. Kira does not launch a model CLI or require a model login.
 

package/docs/CLI.md

@@ -1,9 +1,9 @@
 # CLI and provider configuration
 
-Kira 0.2.1 is a local wallet engine, CLI and web interface. Any capable agent
+Kira 0.2.2 is a local wallet engine, CLI and web interface. Any capable agent
 can use the CLI; MCP is optional. Your agent host supplies its own model,
 conversation, general tools and approvals. Kira does not start a model process.
-This branch prepares 0.2.1. Registry publication remains an operator action.
+This branch prepares 0.2.2. Registry publication remains an operator action.
 
 ## Install and choose a workspace
 
@@ -35,7 +35,9 @@ use the supported CLI for a consistent data root.
 
 `--json` is accepted anywhere in the command. `info` returns the version,
 data directory, capabilities, connection readiness, saved-data revision, job
-status, UI availability and packaged skill path. Use `--help` for syntax.
+status, UI availability and packaged skill path. Its `research_connection.status`
+is `ready` when Alchemy is connected and `connection_required` before that.
+`--data-dir` also works before or after the subcommand. Use `--help` for syntax.
 
 ## Open the local app
 
@@ -90,7 +92,8 @@ reject the import and preserve the configuration.
 RPC, discovery and import commands apply synchronously when idle. If research
 owns the writer, they return a queued receipt; `--json` always returns a queued
 receipt without waiting. Inspect the resulting job before reporting the
-configuration applied. Safe configuration output contains references, not values.
+configuration applied; its `result.provider_configuration` lists the applied
+modes and reference names. Safe configuration output contains references, not values.
 
 New configurations allow verified public RPC fallback. `--custom-only`
 disables fallback; `--public-fallback` restores it. Existing opt-outs persist.
@@ -122,7 +125,8 @@ kira prices 'Daily wallet' --idempotency-key prices-daily-001 --json
 ```
 
 The first tag is the display name. Exact names and registered addresses select
-wallets. Reuse an idempotency key only when retrying the same intended request.
+wallets. `add` runs the first full holdings lookup itself; use `refresh` for
+later updates. Reuse an idempotency key only when retrying the same intended request.
 
 `add`, `refresh` and `prices` persist a durable job before doing research.
 `--json` or `--enqueue` returns its receipt immediately and starts a separate
@@ -175,10 +179,16 @@ kira call holdings_query --arguments '{"mode":"search","query":"ETH"}' --json
 kira call wallet_read --arguments '{"wallet":"Daily wallet","offset":0,"limit":100}' --json
 kira call token_read --arguments '{"chain_id":8453,"address":"native"}' --json
 kira call snapshots_list --arguments '{"wallet":"Daily wallet","limit":20}' --json
-kira call job_list --arguments '{"state":"running","offset":0,"limit":20}' --json
+kira call job_list --arguments '{"state":"active","offset":0,"limit":20}' --json
 kira ui context --json
 ```
 
+`job_list` accepts `state` groups `all` (default), `active` (queued or
+running), `succeeded` (succeeded or partial), `attention` (interrupted or
+failed) and `cancelled`, or one exact state: `queued`, `running`, `partial`,
+`interrupted` or `failed`. Add `wallet` to limit results to one registered
+wallet.
+
 Follow returned `next_offset` values when complete pages are needed. Use
 `holdings_query` for server-computed ranking, counts and aggregates across the
 full inventory. Same-symbol tokens may differ by chain and contract; retain

package/docs/RELEASE.md

@@ -1,6 +1,36 @@
 # Release preparation
 
-## Prepared release: 0.2.1
+## Prepared release: 0.2.2
+
+Fixes two agent contract findings from the published 0.2.1 fresh-agent test.
+`job_list` now publishes its accepted `state` values in the tool schema and
+accepts each exact job state, such as `running`, as well as the existing
+groups. Invalid values return the accepted list. Documented `kira call`
+examples are checked against the published schemas. Global `--data-dir` now
+works before or after a subcommand, like `--json`.
+
+A fresh Claude Code test of this candidate found four more contract gaps, now
+fixed. `research_connection.status` is `ready` only when Alchemy is connected
+and `connection_required` before that, instead of always `configured`. A
+finished settings job reports the settings it applied, not the ones it
+replaced. Native rows in `wallet_read` keep `address: null`, like
+`holdings_query`. `snapshots_list` rows carry `phase`, so progress saved during
+a running lookup is distinct from finished lookups. The skill now explains
+`kira add`, import side effects, per-operation progress, price refresh
+history, float position values and `head_status`.
+
+A second, read-only Claude Code check of the fixed candidate led to three
+more changes. A partial price job now names its reasons in `result.gaps`.
+`kira --help` shows the `kira` program name and a line for every command.
+The skill corrects `head_status`, notes the native `address: null`, the
+100-event job window and older settings receipts. Wallet records, research,
+financial projections and the web app are unchanged.
+
+Preserve the published 0.2.1 archive and every earlier archive. Freeze 0.2.2
+from the accepted clean commit with `scripts/prepare-release.py`, dry-run that
+exact archive and leave registry publication to the operator. Review not selected.
+
+## Published 0.2.1
 
 Includes the external-agent architecture described in the preserved 0.2.0
 candidate below and four approved UI refinements. Short desktop windows can
@@ -9,16 +39,10 @@ one line, a single wallet card fills its available grid width, and token detail
 captions and addresses use larger, darker text. Wallet records, research,
 financial projections, CLI and MCP behavior are unchanged.
 
-Preserve the already frozen 0.2.0 archive and manifest. This 0.2.1 candidate is
-the next publication target; an unpublished earlier candidate is not overwritten.
-Before freezing, run the full repository suite, clean package installation,
-source and history privacy checks, responsive browser acceptance including short
-windows and multiple wallets, and exact source/archive/installed-member checks.
-Freeze from the accepted clean commit, dry-run the exact archive and leave
-registry publication to the operator. Review not selected.
-
-The separate real-device acceptance, fresh public website screenshots and site
-content update remain a follow-up after installation of the new version.
+The operator published 0.2.1. Its archive SHA-256 is
+`aed02bc57c0fec8eec8b8fe8539ddcc45592d7876f04b86045e1d136b51804e0`; the
+installed package and all 93 members matched it. The real-device acceptance
+and website update that followed installation are complete.
 
 ## Preserved candidate: 0.2.0
 
@@ -135,7 +159,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.20
+Keep published GitHub tags, release assets and npm versions through 0.2.1
 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.
@@ -151,12 +175,12 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.2.1.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.2.2.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.2.1.tgz --access public
+npm publish ./dist/kira-wallet-0.2.2.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.

package/kira_cli.py

@@ -186,48 +186,51 @@ def finish_configuration(store,job,*,enqueue=False):
     return 0
 
 def main():
-    parser=argparse.ArgumentParser(description=__doc__)
+    parser=argparse.ArgumentParser(prog='kira',description=__doc__)
     parser.add_argument('--version',action='version',version=json.loads((ASSETS/'package.json').read_text())['version'])
     parser.add_argument('--json',action='store_true',help='Return structured output; research commands enqueue without waiting.')
-    parser.add_argument('--data-dir',default=os.environ.get('KIRA_DATA_DIR',str(Path.home()/'.local/share/kira-wallet')))
+    parser.add_argument('--data-dir',default=os.environ.get('KIRA_DATA_DIR',str(Path.home()/'.local/share/kira-wallet')),help='Workspace directory. Accepted before or after the subcommand.')
     sub=parser.add_subparsers(dest='command',required=True)
-    sub.add_parser('init');s=sub.add_parser('start');s.add_argument('--port',type=int,default=8787)
+    sub.add_parser('init',help='Create or check the data directory without changing records.');s=sub.add_parser('start',help='Open the local app.');s.add_argument('--port',type=int,default=8787)
     mode=s.add_mutually_exclusive_group()
     mode.add_argument('--read-only',dest='controls',action='store_false',help='View recorded holdings without local browser actions.')
     mode.add_argument('--controls',dest='controls',action='store_true',help=argparse.SUPPRESS)
     s.set_defaults(controls=True)
     s.add_argument('--no-open',action='store_true',help='Print the local app URL without opening a browser.')
-    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('info')
-    wallets=sub.add_parser('wallets');walletsub=wallets.add_subparsers(dest='wallet_action')
+    setup=sub.add_parser('setup',help='Open the local app at first-run setup.');setup.add_argument('--port',type=int,default=8787);setup.add_argument('--no-open',action='store_true')
+    sub.add_parser('stop',help='Stop the local app.');sub.add_parser('status',help='Show whether the local app is running.');sub.add_parser('info',help='Show version, data directory, readiness and active jobs.')
+    wallets=sub.add_parser('wallets',help='List wallets or change their names.');walletsub=wallets.add_subparsers(dest='wallet_action')
     tags=walletsub.add_parser('tags');tags.add_argument('wallet');tags.add_argument('--tag',action='append',required=True);tags.add_argument('--idempotency-key')
-    tools=sub.add_parser('tools');tools.add_argument('--allow-writes',action='store_true')
-    call=sub.add_parser('call');call.add_argument('tool');call.add_argument('--arguments',default='{}')
-    sub.add_parser('skill')
-    ui=sub.add_parser('ui');ui.add_argument('action',choices=['context'])
-    archive=sub.add_parser('archive');archive.add_argument('action',choices=['list','read','workspaces','files','export']);archive.add_argument('conversation',nargs='?');archive.add_argument('--path');archive.add_argument('--output')
-    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')
-    refresh=sub.add_parser('refresh');refresh.add_argument('wallet');refresh.add_argument('--resume')
-    prices=sub.add_parser('prices');prices.add_argument('wallet')
+    tools=sub.add_parser('tools',help='Serve Kira tools over MCP stdio.');tools.add_argument('--allow-writes',action='store_true')
+    call=sub.add_parser('call',help='Run one Kira tool with JSON arguments.');call.add_argument('tool');call.add_argument('--arguments',default='{}')
+    sub.add_parser('skill',help='Print the agent instructions.')
+    ui=sub.add_parser('ui',help="Read the app's last recorded selection.");ui.add_argument('action',choices=['context'])
+    archive=sub.add_parser('archive',help='Read earlier conversations and generated files.');archive.add_argument('action',choices=['list','read','workspaces','files','export']);archive.add_argument('conversation',nargs='?');archive.add_argument('--path');archive.add_argument('--output')
+    connection=sub.add_parser('connect',help='Enter an Alchemy key at a hidden local prompt.');connection.add_argument('provider',choices=['alchemy'])
+    d=sub.add_parser('doctor',help='Check RPC settings, optionally with live probes.');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',help='Open a sample portfolio.');demo.add_argument('--port',type=int,default=8790)
+    add=sub.add_parser('add',help='Register a public wallet and run its first holdings lookup.');add.add_argument('address');add.add_argument('--tag',required=True);add.add_argument('--resume')
+    refresh=sub.add_parser('refresh',help='Run a new holdings lookup for a wallet.');refresh.add_argument('wallet');refresh.add_argument('--resume')
+    prices=sub.add_parser('prices',help='Refresh prices without changing balances.');prices.add_argument('wallet')
     for mutation in (add,refresh,prices):mutation.add_argument('--idempotency-key');mutation.add_argument('--enqueue',action='store_true')
-    jobs=sub.add_parser('jobs');jobsub=jobs.add_subparsers(dest='action',required=True)
+    jobs=sub.add_parser('jobs',help='List, follow and control durable jobs.');jobsub=jobs.add_subparsers(dest='action',required=True)
     jobsub.add_parser('list');jobsub.add_parser('run')
     wait=jobsub.add_parser('wait');wait.add_argument('job_id');wait.add_argument('--timeout',type=float,default=30)
     for action in ('read','resume','cancel','deepen'):
         item=jobsub.add_parser(action);item.add_argument('job_id');item.add_argument('--idempotency-key')
-    config=sub.add_parser('config');configsub=config.add_subparsers(dest='setting',required=True)
+    config=sub.add_parser('config',help='Show settings or import a key file reference.');configsub=config.add_subparsers(dest='setting',required=True)
     configsub.add_parser('show')
     imp=configsub.add_parser('import-env');imp.add_argument('--file',required=True);imp.add_argument('--key-env',default='ALCHEMY_API_KEY')
-    rpc=sub.add_parser('rpc');rpcsub=rpc.add_subparsers(dest='setting',required=True)
+    rpc=sub.add_parser('rpc',help='Choose public or custom RPC references.');rpcsub=rpc.add_subparsers(dest='setting',required=True)
     rpcsub.add_parser('public')
     custom=rpcsub.add_parser('set');custom.add_argument('--chain',type=int,required=True);custom.add_argument('--url-env',required=True);custom.add_argument('--priority',choices=['public_first','custom_first']);fallback=custom.add_mutually_exclusive_group();fallback.add_argument('--public-fallback',action='store_true',default=None);fallback.add_argument('--custom-only',dest='public_fallback',action='store_false')
-    discovery=sub.add_parser('discovery');discovery.add_argument('provider',choices=['none','alchemy']);discovery.add_argument('--key-env',default='ALCHEMY_API_KEY');discovery.add_argument('--explorers',action='store_true')
+    discovery=sub.add_parser('discovery',help='Choose the token discovery provider.');discovery.add_argument('provider',choices=['none','alchemy']);discovery.add_argument('--key-env',default='ALCHEMY_API_KEY');discovery.add_argument('--explorers',action='store_true')
     argv=sys.argv[1:]
-    # A global machine-output switch works before or after a subcommand.
+    # Global switches work before or after a subcommand.
     if '--json' in argv:argv=['--json']+[a for a in argv if a!='--json']
+    for index,item in enumerate(argv):
+        if item=='--data-dir' and index+1<len(argv):argv=argv[index:index+2]+argv[:index]+argv[index+2:];break
+        if item.startswith('--data-dir='):argv=[item]+argv[:index]+argv[index+1:];break
     args=parser.parse_args(argv);root=Path(args.data_dir).expanduser().resolve();os.environ['KIRA_DATA_DIR']=str(root)
     if sys.version_info<(3,11):raise ValueError('Python 3.11 or newer is required.')
     if os.name!='posix':raise ValueError('This development build requires a POSIX host. macOS is verified.')

package/kira_config.py

@@ -82,9 +82,10 @@ def public_status(root=None):
     rpc=cfg['rpc'];discovery=cfg['discovery']
     public=rpc['mode']=='public' or rpc['allow_public_fallback']
     import_command=f"kira config import-env --file PATH --key-env {discovery['key_env']}"
-    return {'status':'configured','rpc_mode':rpc['mode'],'read_order':('custom_first' if discovery['provider']=='alchemy' else rpc.get('priority','public_first')) if public else 'custom_only',
+    ready=discovery['provider']=='alchemy' and available
+    return {'status':'ready' if ready else 'connection_required','rpc_mode':rpc['mode'],'read_order':('custom_first' if discovery['provider']=='alchemy' else rpc.get('priority','public_first')) if public else 'custom_only',
             'custom_chain_count':len(rpc['chains']) if rpc['mode']=='custom' else 0,
-            'discovery_provider':discovery['provider'],'discovery_key_available':discovery['provider']=='alchemy' and available,
+            'discovery_provider':discovery['provider'],'discovery_key_available':ready,
             'key_env':discovery['key_env'],'public_discovery':False,'required_provider':'alchemy',
             'import_command':import_command,
             'guide':'Open Workspace settings > Alchemy. Run kira connect alchemy in a terminal and enter the app key at its hidden prompt. Return to Kira to check the connection, then refresh holdings. Actual results establish network access. Never enter or request a key in chat or the browser.',

package/kira_jobs.py

@@ -35,6 +35,10 @@ def signal_process_group(pgid, sig):
 State = Literal['queued', 'running', 'interrupted', 'succeeded', 'partial', 'failed', 'cancelled']
 Operation = Literal['wallet.add','wallet.refresh','prices.refresh','wallet.setTags','settings.rpc','settings.discovery','settings.provider','settings.importEnv']
 TERMINAL = {'succeeded', 'partial', 'failed', 'cancelled', 'interrupted'}
+# Web history uses the groups. Agents may also filter by an exact state they read on a job.
+STATE_FILTERS = {'all': None, 'active': {'queued','running'}, 'succeeded': {'succeeded','partial'},
+                 'attention': {'interrupted','failed'}, 'cancelled': {'cancelled'},
+                 **{state: {state} for state in ('queued','running','partial','interrupted','failed')}}
 ADDRESS = re.compile(r'0x[0-9a-fA-F]{40}')
 
 class Request(TypedDict):
@@ -133,6 +137,11 @@ def fields(value, required):
     if not isinstance(value, dict) or set(value) != set(required):
         raise JobError('invalid_input', 'Unexpected or missing operation fields.')
 
+def provider_summary(config):
+    """Settings facts and environment names only, never values."""
+    return {'rpc_mode':config['rpc']['mode'],'discovery_provider':config['discovery']['provider'],
+            'public_fallback':config['rpc']['allow_public_fallback'],'endpoint_refs':{cid:row['url_env'] for cid,row in config['rpc']['chains'].items()}}
+
 def identifier(value):
     if not isinstance(value, str): raise JobError('invalid_id', 'Expected a job ID.')
     try:
@@ -238,12 +247,10 @@ class JobStore:
     def page(self, offset=0, limit=50, state='all', wallet=None):
         from kira_state import page_bounds
         page_bounds(offset, limit)
-        groups = {'all': None, 'active': {'queued','running'}, 'succeeded': {'succeeded','partial'},
-                  'attention': {'interrupted','failed'}, 'cancelled': {'cancelled'}}
-        if state not in groups:raise JobError('invalid_state','Choose a supported job state filter.')
+        if state not in STATE_FILTERS:raise JobError('invalid_state','Choose a job state filter: '+', '.join(STATE_FILTERS)+'.')
         selected = self.wallet(wallet)['address_key'] if wallet else None
         with self.locked():
-            rows = [r for r in self.summaries() if (groups[state] is None or r['state'] in groups[state])
+            rows = [r for r in self.summaries() if (STATE_FILTERS[state] is None or r['state'] in STATE_FILTERS[state])
                     and (selected is None or (r['input'].get('wallet') or r['input'].get('address','')).lower() == selected)]
             rows.sort(key=lambda r: r['created_at'], reverse=True)
             jobs = [self.get(r['job_id']) for r in rows[offset:offset+limit]]
@@ -545,7 +552,13 @@ class JobStore:
         paths = {w['latest_snapshot']['directory'] for w in read(self.root / 'wallets.json')['wallets'] if w['address_key'] == key and w.get('latest_snapshot')}
         for run in read(self.root / 'wallets.json').get('research_runs', []):
             if run['address_key'] == key: paths.add(run['snapshot'])
-        return sorted([{'snapshot_id': p, 'compiled_at': self.snapshot(p).get('compiled_at'), 'status': self.snapshot(p).get('status')} for p in paths],key=lambda r:r['compiled_at'] or '')
+        rows = []
+        for path in paths:
+            # phase "initial" marks progress published while a holdings lookup was still running.
+            snapshot = self.snapshot(path)
+            rows.append({'snapshot_id': path, 'compiled_at': snapshot.get('compiled_at'), 'status': snapshot.get('status'),
+                         'phase': (snapshot.get('pipeline') or {}).get('phase')})
+        return sorted(rows, key=lambda r: r['compiled_at'] or '')
 
     def publication(self, job):
         if job['operation'].startswith('settings.') or job['operation']=='wallet.setTags':
@@ -568,7 +581,8 @@ class JobStore:
             previous = read(projection) if projection.exists() else {}
             value = read(overlay)
             if (previous.get('observed_at') or '') <= value['observed_at']: atomic(projection, value)
-            return {'snapshot_id': item['snapshot_id'], 'overlay': item['overlay'], 'status': item['status']}
+            return {'snapshot_id': item['snapshot_id'], 'overlay': item['overlay'], 'status': item['status'],
+                    **({'gaps': value['job_result_gaps']} if isinstance(value.get('job_result_gaps'), list) else {})}
         manifest = folder / 'run.json'
         if not manifest.exists() or not (folder / 'results.json').exists(): return None
         result = read(folder / 'results.json')
@@ -710,7 +724,8 @@ class JobStore:
                 if job['input']['provider']=='alchemy' and not secret_values(config).get(job['input']['key_env']):
                     raise JobError('connection_key_missing','Kira cannot find the local Alchemy key. Follow the connection guide, then retry. Existing settings are unchanged.')
             atomic(config_path(),config)
-            result={'status':'completed','setting':job['operation']};atomic(self.jobs/'results'/(job['job_id']+'.json'),result);return result
+            result={'status':'completed','setting':job['operation'],'provider_configuration':provider_summary(config)}
+            atomic(self.jobs/'results'/(job['job_id']+'.json'),result);return result
         self.require_connection()
         env = {**os.environ, 'KIRA_DATA_DIR': str(self.root), 'KIRA_JOB_ID': job['job_id'], 'KIRA_JOB_SNAPSHOT': job['checkpoint'], 'KIRA_ANALYSIS_FD': str(writer.fileno()), 'PYTHONUNBUFFERED': '1', 'KIRA_RESEARCH_GENERATION':job.get('parent_job_id',job['job_id'])}
         command=self.engine_command(job)
@@ -815,10 +830,10 @@ class JobStore:
                         if entry.get('research_generation') not in (None,job.get('parent_job_id')):
                             job.update(state='cancelled',stage='stopped',errors=[{'code':'superseded','message':'Newer holdings research replaced this detailed run. Earlier evidence is preserved.'}]);self.save(job);writer.close();continue
                     if job:
-                        from kira_config import load_config
-                        config=load_config()
-                        job['provider_configuration']={'rpc_mode':config['rpc']['mode'],'discovery_provider':config['discovery']['provider'],
-                            'public_fallback':config['rpc']['allow_public_fallback'],'endpoint_refs':{cid:row['url_env'] for cid,row in config['rpc']['chains'].items()}}
+                        # Research records the settings it ran with. Settings jobs report their result instead.
+                        if not job['operation'].startswith('settings.'):
+                            from kira_config import load_config
+                            job['provider_configuration']=provider_summary(load_config())
                         job.update(state='running', stage='starting', started_at=now(), attempt=job['attempt'] + 1, errors=[]); self.save(job)
                 if not job:
                     time.sleep(.5)

package/kira_records.py

@@ -209,7 +209,7 @@ def projection(root, config, *, token_id=None, limit=12, offset=0, wallet_key=No
 def compact_wallet_facts(rows):
     asset_fields=('id','chain_id','address','display_identity','symbol','name','environment','balance','is_native','value_usd','historical_value_usd','balance_observed_at','price','pools','pools_recorded','pools_omitted','exit_quote_recorded','archived')
     return [{**row,'assets':[{key:asset[key] for key in asset_fields if key in asset and
-                           (asset[key] is not None or key in ('value_usd','price'))}
+                           (asset[key] is not None or key in ('address','value_usd','price'))}
                           for asset in row['assets']]} for row in rows]
 
 def recorded_valuation(assets):

package/kira_service.py

@@ -4,7 +4,7 @@ import json
 from pathlib import Path
 import time
 import uuid
-from kira_jobs import JobStore, JobError, atomic, fields
+from kira_jobs import JobStore, JobError, atomic, fields, STATE_FILTERS
 from kira_state import StateCache, page, page_bounds
 from kira_research_tools import ResearchTools, CATALOG
 
@@ -21,8 +21,12 @@ for row in CATALOG:
         properties[name]={**schema,'description':description}
     if row['name'] in ('portfolio_read','job_list','snapshots_list'):
         properties.update(offset=INTEGER,limit={'type':'integer','minimum':1,'maximum':100})
-    if row['name']=='job_list':properties.update(state=STRING,wallet=STRING)
-    READ_TOOLS.append({'name':row['name'],'description':row['description'],
+    summary=row['description']
+    if row['name']=='job_list':
+        summary='Read a newest-first page of durable jobs. Optionally filter by state or registered wallet.'
+        properties.update(state={'type':'string','enum':list(STATE_FILTERS),'description':'Default all. Groups: active (queued, running), succeeded (succeeded, partial), attention (interrupted, failed). The other values match one exact state.'},
+                          wallet={**STRING,'description':'registered address or exact name'})
+    READ_TOOLS.append({'name':row['name'],'description':summary,
         'inputSchema':{'type':'object','properties':properties,'required':list(row['arguments']),'additionalProperties':False},
         'annotations':{'readOnlyHint':True,'destructiveHint':False,'idempotentHint':True,'openWorldHint':False}})
 
@@ -63,6 +67,8 @@ def validate(arguments,schema):
         field=schema['properties'][name];types=field['type'] if isinstance(field['type'],list) else [field['type']]
         if not any((type(value) in kinds[k] if isinstance(kinds[k],tuple) else type(value) is kinds[k]) for k in types):
             raise JobError('invalid_input','Invalid argument type: '+name)
+        if 'enum' in field and value not in field['enum']:
+            raise JobError('invalid_input','Choose '+name+' from: '+', '.join(map(str,field['enum']))+'.')
         if isinstance(value,str) and (len(value)>field.get('maxLength',500) or len(value)<field.get('minLength',0)):
             raise JobError('invalid_input','Use a bounded identifier: '+name)
         if type(value) in (int,float) and (value<field.get('minimum',value) or value>field.get('maximum',value)):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-wallet",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Local wallet research for your agent session and a human-controlled web workspace.",
   "license": "MIT",
   "private": false,

package/skills/kira-wallet/SKILL.md

@@ -12,8 +12,9 @@ and MCP operations.
 
 ## Start with the existing workspace
 
-1. Run `kira --version`, then `kira info --json` and inspect readiness and
-   `data_dir`. The commands below require 0.2.0 or later. If installation is
+1. Run `kira --version`, then `kira info --json` and inspect `data_dir` and
+   `research_connection.status`: `ready` means Alchemy is connected;
+   `connection_required` means new research cannot start yet. The commands below require 0.2.0 or later. If installation is
    part of the request, use `npm install -g kira-wallet` or the supplied
    prepared package archive. Requirements are Node.js 22+, Python 3.11+ and
    POSIX; macOS is verified.
@@ -44,8 +45,12 @@ kira config show --json
 
 An existing private environment file can be referenced with
 `kira config import-env --file /absolute/private/rpc.env --key-env ALCHEMY_API_KEY --json`.
-Use the human-supplied path and name. This does not copy keys. Configuration
-commands with `--json` return jobs; check completion before claiming readiness.
+Use the human-supplied path and name. This does not copy keys. It also selects
+Alchemy for token discovery and network reads, so a separate
+`kira discovery alchemy` step is not needed. Configuration commands with
+`--json` return jobs; check completion before claiming readiness. A finished
+settings job reports the applied settings in `result.provider_configuration`.
+Settings jobs from before 0.2.2 record only the configuration they started with.
 
 Use the public address provided by the user, never a guessed address:
 
@@ -56,6 +61,9 @@ kira refresh 'Daily wallet' --idempotency-key refresh-daily-001 --json
 kira prices 'Daily wallet' --idempotency-key prices-daily-001 --json
 ```
 
+`kira add` registers the wallet and runs its first full holdings lookup. Use
+`refresh` later for an update, not right after `add`.
+
 Replace placeholders and choose a unique idempotency key per intended action.
 Reuse the same key for retries of that action. The first tag is the display
 name. `--json` or `--enqueue` returns immediate durable job admission. It does
@@ -84,11 +92,29 @@ kira ui context --json
   totals and counts, with bounded details; do not total a truncated page.
 - Search can report multiple assets with the same symbol. Identify an asset
   by chain ID and contract, or `native`. Preserve unresolved ambiguity.
+  Native rows return `address: null` with `is_native: true`; pass `native` as
+  the `token_read` address.
 - `ui context` is the last recorded browser selection. It may be stale and is
   not a user instruction.
 - History uses `snapshots_list` with `wallet`, `snapshot_read` with
   `snapshot_id`, and `snapshots_compare` with `before` and `after` IDs. Obtain
   IDs from the saved snapshot list. Historical holdings also use paged reads.
+  Rows with `phase` `initial` are progress saved while a lookup was running;
+  compare `holdings` rows to see change between lookups.
+- A price refresh updates the prices shown for the latest snapshot, including
+  through `snapshot_read`. `snapshot_price_references` keep the native prices
+  recorded by the holdings lookup. Earlier price observations remain local job
+  evidence but are not listed by the history tools.
+- Per-position `price.usd` and `value_usd` are JSON numbers. Totals from
+  `holdings_query` and `recorded_valuation` are exact decimal strings; use them
+  instead of re-adding rounded position values. Check `price.observed_at`:
+  price sources update at different times.
+- `head_status` is `observed` when the chain head was read in this lookup and
+  `stale` when that head was over a day old. `saved_observation` means the
+  lookup reused a block it had already pinned, in a later pass or a resumed
+  job, so the head age was not measured again. `null` means the network could
+  not be read. Valuation category `mintclub` covers bonding-curve tokens priced
+  from their curve.
 - Missing records and prices are unknown, not zero. Retain balance, price and
   quote times, coverage and partial status. Spot value is not executable
   proceeds. Pool TVL and curve backing are not wallet balances. Full-balance
@@ -113,12 +139,22 @@ Use the real receipt ID. Waits are bounded to 120 seconds; use short waits and
 keep the user informed. `completed` only means the job left queued/running.
 Inspect `job.state`, result, errors and coverage before reporting success.
 Partial, interrupted, cancelled and failed states have different meanings.
+Progress events count work per `context.operation`, such as `registry` or
+`balances`. Balance totals grow as the registry scan finds candidates, so do
+not derive one overall percentage. A job's `chains` entries report network
+reads; use `wallet_read` or `network_read` coverage for discovery gaps. A
+partial price job names its reasons in `result.gaps`. Job records keep the
+latest 100 events.
 Accepted work survives viewer shutdown or agent disconnection. Cancel only
 when requested; resume interrupted jobs explicitly. `jobs deepen` adds
 optional sell-route analysis from saved holdings without rediscovering tokens.
 
 Use `call job_list` with optional `state`, `wallet`, `offset` and `limit` for
-paged job discovery. `kira jobs run` starts queued work, not interrupted jobs.
+paged job discovery. `state` is `all` (default), a group (`active`,
+`succeeded`, `attention`, `cancelled`) or an exact state (`queued`, `running`,
+`partial`, `interrupted`, `failed`). `succeeded` includes partial results;
+check `job.state` to separate them.
+`kira jobs run` starts queued work, not interrupted jobs.
 
 ## Shared tools and earlier archives
 

package/viewer/refresh_prices.py

@@ -162,7 +162,15 @@ for w in selected:
   overlay=job_folder/'prices.json'
   output['snapshot_id']=w['latest_snapshot']['directory']
   missing_native=any(c.get('environment')=='mainnet' and float(c.get('native_balance') or 0)>0 and c.get('native_symbol')+'_USD' not in fresh_native for c in snapshot.get('coverage',[]))
-  output['job_result_status']='completed_with_coverage_gaps' if output.get('market_discovery_status')=='partial' or missing_native or retained or output.get('reserve_price_status')=='partial' or (output.get('reserve_price_graph') or {}).get('errors') or rpc.get('errors') or any('error' in p for p in rpc['tokens']) or any(isinstance(r['response'],dict) and 'transport_error' in r['response'] for r in fetched) else 'completed'
+  # Name each gap so a partial price job explains itself.
+  output['job_result_gaps']=[name for name,found in (
+      ('market_discovery_partial',output.get('market_discovery_status')=='partial'),
+      ('native_price_missing',missing_native),
+      ('earlier_prices_retained',bool(retained)),
+      ('reserve_pricing_partial',output.get('reserve_price_status')=='partial' or bool((output.get('reserve_price_graph') or {}).get('errors'))),
+      ('curve_reads_incomplete',bool(rpc.get('errors')) or any('error' in p for p in rpc['tokens'])),
+      ('provider_request_failed',any(isinstance(r['response'],dict) and 'transport_error' in r['response'] for r in fetched))) if found]
+  output['job_result_status']='completed_with_coverage_gaps' if output['job_result_gaps'] else 'completed'
   atomic(overlay,output)
   atomic(job_folder/'price-publication.json',{'schema_version':1,'snapshot_id':w['latest_snapshot']['directory'],
       'overlay':str(overlay.relative_to(h.ROOT)),'projection':str(destination.relative_to(h.ROOT)),