kira-wallet 0.1.0

package/docs/KIRA_REDESIGN_REPORT.md

@@ -0,0 +1,125 @@
+# Kira workspace redesign
+
+Development build 0.1.0-dev.3, 2026-10-04.
+
+## Result and design concept
+
+The prior dashboard hid research interaction below the portfolio. The new
+workspace makes Kira a persistent research partner beside the recorded evidence.
+Ink navigation, warm paper, restrained lavender and editorial scene captions
+give the character a coherent setting. Kira changes pose with the task instead
+of remaining a decorative image on every screen.
+
+Lazyweb product evidence informed the separated navigation, persistent partner
+panel and distinct activity history. Reviewed patterns included Intercom's
+dashboard hierarchy, OpenAI's logs tabs and sigmamind's analytics/activity views.
+These references guided layout decisions; no reference screenshots or third-party
+UI assets are redistributed.
+
+Four new transparent illustrations extend the existing original Kira identity:
+researching, explaining, reviewing and checking incomplete evidence. The
+existing notebook portrait remains the welcome state. Character provenance and
+exact generation prompts are in [workspace-generation.json](character/workspace-generation.json).
+
+![Synthetic desktop workspace](screenshots/kira-redesign-desktop.jpg)
+
+## Delivered behavior
+
+- The brand returns Home. There is no duplicate sidebar Home button.
+- Overview, All tokens and Activity have distinct tabs. Wallet selection stays
+  in the sidebar; add/settings controls stay together; wallet-specific actions
+  stay above the selected wallet.
+- Kira's deterministic briefing, evidence shortcuts and conversation draft sit
+  in the main section. Mobile has a direct Portfolio/Kira switch. Drafts stay
+  in that browser's local storage. Sending stays disabled until the account
+  route and portfolio disclosure scope are approved and implemented.
+- All tokens reuses recorded chain-plus-contract aggregates. It provides
+  search, network/pricing filters, sorting, explicit testnet inclusion and
+  50-row pagination. Unpriced and partly unpriced assets stay visible as unknown.
+  The catalog does not contact providers.
+- Active work has a compact strip linked to Activity. Full job history has
+  status filters, 20-row pagination, recorded stages and existing stop/resume
+  controls. Queued, running, completed, partial, interrupted, failed and stopped
+  states have distinct labels. Cancellation requests say Stopping until the
+  engine records an outcome.
+- New attempts record optional `started_at`. Timers show actual elapsed time
+  for these attempts and stop on terminal updates. Old jobs say Since request.
+  Queued jobs show their latest waiting interval. Missing timestamps say Unknown.
+  After a minute without a stage update, the UI states that it is awaiting an
+  update. A disconnected API shows the last recorded state and stops its spinner.
+  Neither condition fabricates completion or failure.
+- Synthetic demo sessions also reject resuming a saved provider research job.
+  Names/settings jobs and existing same-origin session protections remain intact.
+
+## Verification
+
+Verification uses synthetic data. `npm test` passed 66 Python tests, Node cache
+and outage checks, catalog/lifecycle checks and browser-source syntax. The suite covers the engine, local
+HTTP controls, cache/outage behavior and browser-source syntax. Catalog checks
+use 5,002 tokens and cover bounded pages, identity, unknown/partial prices,
+testnets, ordering and unchanged source evidence. Lifecycle checks cover all
+states, quiet stages, disconnection, cancellation and current-attempt timing.
+
+Browser checks exercised a 122-token synthetic portfolio with 121 mainnet tokens:
+50-row paging, search, unpriced filtering, token/network navigation, brand Home,
+wallet selection, saved analyses, settings, keyboard dismissal/focus return,
+local draft persistence and a real local names job completing through the worker.
+All seven job states were inspected using private fixtures, then removed before
+submitting a control action. No provider research ran during browser validation.
+Desktop 1280x720 and mobile 375x812/320x700 layouts had no document overflow;
+the Kira composer remained visible. Browser warnings/errors were empty.
+
+The clean install check passed with 51 archive members. It packs and installs in an isolated directory, serves all
+new assets, verifies private paths remain unavailable and executes only a
+synthetic names job. Verification results are recorded in the PR.
+
+Only the existing viewer was restarted for the operator portfolio. The
+projection was byte-identical across restart, and all 682 baseline private
+runtime files retained their hashes. Existing controls stayed enabled. No
+operator names, holdings, snapshots, credentials or research jobs were edited.
+
+![Synthetic activity](screenshots/kira-redesign-activity.jpg)
+
+## Publication and rollback
+
+Public code, comments and documentation use synthetic examples. A public-history
+check excludes runtime files, known operator portfolio identifiers, personal
+paths, loaded secrets and credential patterns. Images also received a visual
+privacy check. Public commits use a GitHub noreply identity. Private local
+history and session handoffs are not pushed.
+
+The `kira-workspace-v1` tag preserves the previous UI with a clean public
+foundation history. To restore just that interface while keeping the current
+backwards-compatible server and job timing support:
+
+```sh
+git restore --source=kira-workspace-v1 -- viewer/static/index.html viewer/static/app.js viewer/static/jobs.js viewer/static/style.css
+```
+
+Reload the browser. This changes tracked UI source only. Runtime portfolio
+files are outside that command. Restore those UI files from the redesign branch
+to return to this edition. The original pre-redesign branch also remains local.
+
+## Limits and next work
+
+Pagination bounds the catalog DOM and image work. The existing API still loads
+the full recorded projection, and client filtering/sorting scans that catalog.
+The 5,002-token test establishes behavior, not a performance guarantee for
+arbitrary portfolios. Tens of thousands of positions would warrant server
+pagination/indexing and a separate measured change.
+
+Activity reflects durable job evidence, not a worker heartbeat. A long silent
+stage can remain running; the UI makes that uncertainty explicit. Recovery is
+an engine decision. No stale operator job was altered during redesign.
+
+Connected model chat remains behind the existing account/session and disclosure
+gates. Watching wallet connection is the agreed next capability direction.
+Transfers, swaps and OWS Managed wallets require separate design and verification;
+see [wallet capability direction](WALLET_CAPABILITIES.md). No connection, signing,
+wallet creation or trading capability ships in this change.
+
+The follow-up [review and visual refinement](KIRA_REFINEMENT_REVIEW.md) records
+the inherited-head review, corrections and updated synthetic browser evidence.
+
+This build needs independent review before merge or release. No production
+deployment, registry publication or npm publication is part of this work.

package/docs/ONBOARDING_CHAT_CONTRACT.md

@@ -0,0 +1,36 @@
+# Native CLI onboarding and conversation
+
+Kira connects the user's installed, unmodified Codex or Claude Code CLI. It does not collect account passwords, copy authentication, run an OAuth proxy, or add a hosted portfolio service. Installation and login happen through the vendor's CLI. A generic response test verifies the selected model before setup is saved. Subscription access and limits remain the vendor's responsibility.
+
+The setup flow separates account readiness, model choice, context permission, and confirmation. The conversation composer remains visible. It shows the connected CLI, automatic context scope, response state, cancellation, and a new conversation action. Enter sends; Shift+Enter adds a line; composition events never send.
+
+Automatic context is none, one explicitly selected registered wallet, or the whole recorded portfolio. An allowlisted projection preserves exact balances, contract and chain identities, timestamps, unknown values, and coverage gaps. It excludes credentials, RPC endpoints, paths, raw errors, jobs, and provider payloads. User-entered text is also sent to the selected provider. Scope, wallet, provider, or model changes start a new conversation and never replay old messages. Only a bounded current conversation is replayed.
+
+Kira uses fixed executable argv, stdin for prompts, a private empty working directory, bounded output, a timeout, and process-group cancellation. Codex ignores user config and rules, uses read-only sandboxing and ephemeral sessions, and disables shell, apps, browser, computer, image, multi-agent, hooks, memories, goals and skill discovery features. The supported Codex adapter is gated to the verified 0.158 series. A local synthetic Responses fixture verified the outgoing catalog has no shell, file, network, MCP, app, or skill tools. Claude Code 2.1.259 through 2.1.x uses restricted and safe modes, no built-in tools, empty strict MCP configuration, no Chrome, no permission prompts and no session persistence. Unsupported versions fail closed.
+
+Native CLI and administrator policy are a separate trust boundary. These settings are invocation controls, not an OS container. Claude managed policy can still apply. Setup requires explicit acknowledgement of the native CLI trust boundary. Kira-local retention controls Kira's conversation files only; vendor and managed CLI data policies are separate. History-off conversations stay in memory and the browser draft is not persisted. Previous saved conversations are preserved but never automatically attached to a new scope.
+
+Chat cannot sign, trade, run arbitrary commands, change settings, or automatically start research. Research remains in the existing explicit controls and protected durable job API. Responses and token metadata are untrusted text, rendered without HTML interpretation.
+
+All agent and chat endpoints require the existing same-origin local session, with bounded requests. Conversation jobs are separate from research jobs. Idempotent requests prevent duplicate sends. Cancellation, reset and configuration changes invalidate late responses. Tests cover disclosure projections, scope history isolation, retention, cancellation races, bounded output, unsupported CLIs, failures, duplicate sends and origin/session protection.
+
+Design evidence: [Lazyweb onboarding and AI conversation references](https://www.lazyweb.com/agentic-search/593c1118-8ec0-46bf-a608-4b100271930e). Granola informs separate permissions and readiness; Raycast informs compact model choice; Copilot informs the composer surface and aligned controls. Kira uses its own typography, artwork and component system.
+
+## Verification evidence
+
+`npm test` passes 83 Python tests, 31 Watching/chat UI and model cases, the
+RPC outage checks and the 5,002-token catalog fixture. Clean installation covers
+58 package members. Screenshots use a synthetic portfolio and fake model runner;
+they are visual evidence, not live provider acceptance. Desktop, short desktop
+and 390-pixel mobile views were checked in Chrome. Both supported native CLIs
+also completed a separate generic response check without wallet context.
+
+- [Conversation desktop](screenshots/kira-chat-desktop.png)
+- [Conversation mobile](screenshots/kira-chat-mobile.png)
+- [Account setup](screenshots/kira-onboarding-account.png)
+- [Permissions](screenshots/kira-onboarding-permissions.png)
+
+Private live read-only acceptance completed with recorded coverage gaps. Same-address
+aliases retain one canonical wallet and one published research run. Repeating the
+original request reuses its job. Portfolio identifiers and raw acceptance evidence
+stay outside Git and are not included in public reports.

package/docs/RELEASE.md

@@ -0,0 +1,45 @@
+# First release
+
+The public source includes the workspace, Watching connection, native CLI setup
+and chat. npm registry publication remains operator-only. No publish command is
+run by the coding agent.
+
+Required preparation:
+
+```sh
+npm test
+python3 scripts/check-install.py
+python3 scripts/check-public.py --history --ref HEAD
+python3 scripts/prepare-release.py
+```
+
+`prepare-release.py` checks the public package boundary and creates
+`dist/kira-wallet-0.1.0.tgz` with a SHA-256 manifest. It never publishes. From the
+reviewed source checkout, the operator's final command is:
+
+```sh
+npm publish ./dist/kira-wallet-0.1.0.tgz --access public
+```
+
+Use the operator's npm account and complete any npm authentication or OTP prompt.
+After registry publication, installation is `npm install -g kira-wallet`, then
+`kira setup`. Until publication, the public installation page uses the GitHub
+source route. It does not claim a published registry release.
+
+## Public website
+
+Only `site/` is deployed to the Vercel `kira-wallet` project. It contains a static
+introduction, synthetic product illustration, original character assets and
+installation instructions. It has no wallet inputs, portfolio API, chat API,
+analytics or third-party runtime scripts. The local viewer remains loopback-only.
+
+`kirawallet.app` uses Vercel nameservers and managed HTTPS. Project domain settings
+are managed in the operator's Vercel team. Keep `.vercel/` metadata out of Git.
+Future site deployments must use `--cwd site`, never the private portfolio root.
+
+Design evidence: [Lazyweb Coinbase and wallet installation references](https://www.lazyweb.com/agentic-search/32f91923-4607-4d3a-aa06-ac09828b9a66).
+
+Native extension approval, lock and account-change behavior remains a device
+acceptance check. Synthetic providers and manually supplied public addresses do
+not establish that native extension approval passed. These limitations do not
+grant signing, trading or custody capability.

package/docs/WALLET_CAPABILITIES.md

@@ -0,0 +1,98 @@
+# Wallet capability direction
+
+Agreed with the operator on 2026-10-04: begin with Watching wallet connection.
+Transfers, swaps and OWS Managed wallets need separate design and verification
+before implementation. This is a future direction, not a delivered capability.
+The account/session and portfolio disclosure gates remain unchanged.
+
+## Two wallet groups, distinct authority
+
+Watching Wallets contains manually entered or explicitly selected external
+addresses. An extension connection is an address source and a temporary signer
+session, not permission for Kira to spend. Disconnection removes the session
+while preserving the recorded watching address. A changing extension account
+must not silently add or replace a registered wallet.
+
+Kira Managed Wallets would identify local OWS wallets with explicitly delegated
+capabilities. A group name alone does not imply that Kira can sign. A locked,
+unconfigured, expired or revoked signer must remain visibly unavailable.
+The portfolio model remains keyed by chain and contract; source and execution
+capabilities are separate metadata.
+
+## First implementation scope: Watching connection
+
+The reviewed local `lptoken-fun` source was synced by fast-forward to
+`b5782b507758f78b6b29e2571bcf1c48f458756b`. Its wallet stack uses Wagmi
+3.7.6, `injected()`, EIP-6963 discovery and an explicit wallet chooser. This
+means an injected browser provider, not the Injective chain. Its bounded
+reconnect, explicit disconnect and separate network-switch behavior are useful
+references. Kira's vanilla browser does not require copying its entire React
+or RPC stack.
+
+A proposed first ticket will discover providers, let the user choose one,
+request accounts only from that choice and preview an address and exact name
+before the existing add-and-research operation. No login message, transaction,
+chain switch or permission expansion is needed to add a watching address.
+Handle absent extensions, user rejection, multiple providers, account changes,
+disconnect and late responses. Address registration and provider-consuming
+research remain an explicit user action. Mobile handoff is separate from a
+successful local connection. An embedded browser may have no extension.
+
+Primary references: [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963),
+[EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) and
+[MetaMask connection documentation](https://docs.metamask.io/metamask-connect/).
+
+## Transfers and swaps: design before implementation
+
+Reuse mature transaction and protocol libraries instead of writing custody or
+DEX contracts. Reuse does not remove integration, approval, slippage, RPC,
+protocol or supply-chain risk. Start by considering an external protocol handoff
+for swaps. A native transfer flow would still need a confirmed recipient,
+chain, asset, amount and fee estimate, fresh simulation and final approval in
+the external wallet. An agent cannot infer that approval from a conversation.
+
+An embedded swap needs a separate threat model and pinned provider selection.
+The quote's target, chain, calldata, allowance spender, amount, minimum output
+and deadline need independent checks. Default to exact allowances, visible
+price impact and slippage, no arbitrary unsigned calldata execution, and no
+cross-chain bridges in an initial scope. Review protocol guarantees rather than
+calling an intermediary UI risk-free.
+
+## OWS Managed wallets: correction and proposed boundary
+
+OWS is not seedless. Its current lifecycle derives accounts from a BIP-39
+mnemonic and stores encrypted wallet secrets locally. Password encryption does
+not remove backup and recovery responsibilities. The owner passphrase grants
+full access without agent policy evaluation. Delegated API tokens instead
+trigger policies and are themselves sensitive decryption capabilities.
+
+The current reference architecture performs decryption and signing in-process.
+It explicitly does not fully mitigate compromised process memory. A subprocess
+enclave is described as future work. Local policies are code-path controls,
+not an on-chain or hardware guarantee.
+
+The proposed Kira boundary is a trusted local signer outside the model process.
+The browser, model, prompts, research store, telemetry and Git never receive
+the mnemonic, private key, owner passphrase or delegated token. OS-protected
+credential access belongs to the signer. Model tools provide typed intents
+only. The signer enforces wallet, chain, contract, method, recipient, token,
+spending, fee, expiry and approval limits and rejects unsupported or undecoded
+requests. Generic message signing and policy/credential modification must not
+be exposed to the model. No environment credential inherited by an arbitrary
+agent shell is acceptable as the boundary.
+
+Before a Managed implementation, pin a specific OWS version and inspect its
+actual APIs and policy behavior. Define creation, encrypted backup, restore,
+revocation, audit retention, process isolation and OS-platform support. Begin
+with synthetic/testnet verification and independent security review. A local
+vault does not by itself justify unattended mainnet execution. Native secure
+credential UX may require a companion application beyond this loopback viewer.
+
+Primary references checked on 2026-10-04:
+[OWS specification](https://docs.openwallet.sh/),
+[wallet lifecycle](https://github.com/open-wallet-standard/core/blob/main/docs/06-wallet-lifecycle.md),
+[policy access model](https://github.com/open-wallet-standard/core/blob/main/docs/03-policy-engine.md),
+[current key isolation limits](https://github.com/open-wallet-standard/core/blob/main/docs/05-key-isolation.md).
+
+No OWS package, wallet creation, signing, transfer or trade was used during this
+research. These capabilities are not included in the workspace redesign PR.

package/docs/character/brand-generation.json

@@ -0,0 +1,20 @@
+{
+  "provider": "built-in image_gen",
+  "use_case": "logo-brand",
+  "reference": "viewer/static/kira.png",
+  "generation_prompt": "Use case: logo-brand. Asset type: Kira Wallet web app logo and favicon master. Reference image is the approved Kira character, for identity only. Create ONE centered compact square brand icon, with generous safe padding, no text or wordmark. Original crisp flat 2D webtoon emblem of an adult chic researcher: espresso hair in a recognizable loose low bun with side fringe, calm gray-violet eyes, composed subtle smile, ivory shirt and charcoal blazer neckline. Include a small simple lavender notebook at the lower edge. Simplify into bold clean shapes and restrained face lines that read at 32px; preserve adult proportions, no child/chibi look. Warm ivory, ink #292536, violet #6755CE and soft lavender. A rounded violet tile behind her, its outside truly transparent. No glow, gradients, detailed hatching, coins, wallet connector symbols, watermarks, scenery, multiple options or presentation sheet. The icon fills about 84% of the canvas and remains clear at small sizes.",
+  "refinement_prompt": "Clean the outside silhouette only; preserve face, espresso low bun, adult identity, lavender notebook, charcoal blazer, ivory shirt, violet tile and composition. Remove every stray pixel outside the tile, especially the white fragment below the bottom edge. Transparent exterior, no shadow, one icon, no text.",
+  "transparent_background": true,
+  "master": "viewer/static/kira-logo.png",
+  "secondary": "viewer/static/favicon.svg",
+  "secondary_method": "Original code-native notebook mark for tiny sizes; matching Kira's palette and accessory.",
+  "applications": [
+    "brand home link",
+    "Home button",
+    "Kira notes",
+    "empty state",
+    "add wallet dialog",
+    "browser icons",
+    "prototype navigation"
+  ]
+}

package/docs/character/workspace-generation.json

@@ -0,0 +1,29 @@
+{
+  "provider": "built-in image_gen",
+  "reference": "viewer/static/kira.png",
+  "transparent_background": true,
+  "identity": "Approved adult Kira: espresso low bun, ivory shirt, charcoal blazer, lavender notebook.",
+  "assets": [
+    {
+      "path": "viewer/static/kira-research.png",
+      "state": "Active research",
+      "prompt": "Use case: identity-preserve. Asset type: Kira Wallet application character illustration, transparent cutout. Input image: approved adult Kira identity reference only, keep exactly the same woman, espresso loose low bun with side fringe, gray-violet eyes, ivory shirt, charcoal tailored blazer, lavender notebook and refined mature webtoon drawing style. Primary request: a new waist-up pose for Kira actively researching. She is in a three-quarter profile, calmly focused, writing in the opened lavender notebook with a slender pen, looking down at her notes; both hands natural. Intelligent, chic, understated editorial mood. Composition: one waist-up woman centered, complete silhouette and generous safe margin, drawn with clean confident ink lines, restrained crosshatching and muted flat color, slightly simplified for a desktop app at 190px. Transparent background, no scenery or surrounding UI. No lettering, numbers, wallet addresses, charts, coins, symbols, logos, speech bubbles, extra people, juvenile proportions or glow. Preserve the character identity and palette."
+    },
+    {
+      "path": "viewer/static/kira-explain.png",
+      "state": "Wallet, token and network explanation",
+      "prompt": "Use case: identity-preserve. Asset type: Kira Wallet application character illustration, transparent cutout. The reference is the approved adult Kira. Preserve exactly her espresso low bun with side fringe, mature face, gray-violet eyes, ivory shirt, charcoal tailored blazer, lavender notebook, refined detailed webtoon ink style and muted palette. Create a NEW waist-up pose of Kira explaining a finding: looking toward the viewer, a subtle confident smile, one hand holding the lavender notebook against her waist, the other open palm held outward in a composed explanatory gesture. Intelligent editorial personality, natural hands and adult proportions. One centered woman with safe transparent margin and no scenery. Clean ink outlines and restrained crosshatching. No text, labels, digits, coins, addresses, charts, screens, logos, glow or extra characters."
+    },
+    {
+      "path": "viewer/static/kira-review.png",
+      "state": "Activity review",
+      "prompt": "Use case: identity-preserve. Asset type: Kira Wallet application character illustration, transparent cutout. Reference image is the approved adult Kira, identity and style only. Keep her identical espresso loose low bun and side fringe, gray-violet eyes, mature features, ivory shirt and charcoal blazer, understated lavender notebook and refined webtoon ink style. Primary request: NEW waist-up pose of Kira reviewing saved research. She wears slender elegant dark reading glasses, holds her lavender notebook open in one hand, lifting her gaze slightly toward the viewer with a knowing gentle smile; the other hand lightly adjusts the glasses at her temple. Chic and intelligent professional researcher, calm natural posture, realistic hands, restrained crosshatching and muted colors matching the reference. One centered person with safe margin on genuinely transparent background. No lettering, charts, addresses, coins, numbers, screens, scenery, glow, logos or other people. Adult proportions."
+    },
+    {
+      "path": "viewer/static/kira-attention.png",
+      "state": "Coverage gaps",
+      "prompt": "Use case: identity-preserve. Asset type: Kira Wallet application character illustration, transparent cutout. Reference is the approved adult Kira, preserve exactly her espresso loose low bun and side fringe, mature calm face, gray-violet eyes, ivory shirt, charcoal tailored blazer and lavender notebook, refined webtoon drawing style, ink contours, muted palette and subtle crosshatching. Create a NEW waist-up pose for carefully checking incomplete evidence: her eyebrows very slightly furrowed in concentration, gaze thoughtfully to one side, one hand lightly rests at her chin, other arm holds the lavender notebook against her torso. Composed intelligent adult professional, not distressed or alarmed. One centered woman, safe margins, naturally drawn hands, truly transparent background. No typography, digits, addresses, warning symbols, charts, screens, coins, scenery, extra people, logos or glow."
+    }
+  ],
+  "delivery": "Generated cutouts were copied to the workspace and resized to an 800 pixel maximum edge for local UI delivery. Original identity asset is unchanged."
+}