{"owner":"TraderAlice","repo":"OpenAlice","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"@AGENTS.md\n\n<!--\n  AGENTS.md is the canonical repository instruction file. Claude Code supports\n  importing it directly; keep Claude-specific additions exceptional and short.\n-->\n","AGENTS.md":"# OpenAlice\n\nOpenAlice is a local trading workspace for native coding-agent CLIs. The main\nprocess is a Workspace launcher and trading-context injector; broker credentials,\nconnections, and trading state belong to the separate UTA process. Persisted\nstate is file-backed rather than database-backed.\n\nKeep this file short. It contains rules that apply to every task. Detailed\narchitecture and operating procedures live in the owner guides linked below.\nCurrent code, tests, rendered behavior, and GitHub state override stale prose.\n\nDurable subsystem truth lives under [[docs/README.md]]. Active multi-step\nimplementation work lives under [[PLANS.md]]. Keep both indexes current when a\nchange introduces a new owner guide or execution plan.\n\n## Start Here\n\n```bash\npnpm install              # full local install, including Electron\npnpm dev                  # Guardian -> UTA + Alice + Vite\npnpm dev --takeover       # replace the recorded local Guardian owner tree\npnpm build                # packages + UI + UTA + Alice\npnpm test                 # monorepo Vitest suite\npnpm test:e2e             # non-trading product/integration E2E\n```\n\nBefore changing files:\n\n1. Run `git fetch origin`, `git status -sb`, and inspect the current diff.\n2. Preserve unrelated user changes. Do not reset, overwrite, stash, or commit\n   them merely to obtain a clean tree.\n3. Routine work starts from current `dev` on a focused feature branch. If the\n   checkout is on `master`, a merged branch, or a surprising historical branch,\n   stop and establish the intended base before editing.\n4. Start from the real surface: reproduce UI/runtime behavior, inspect the\n   relevant current code, and read the applicable owner guide before designing.\n5. Before adding a data migration, compatibility parser, or dual-read path,\n   establish whether the affected persisted shape shipped in a released\n   version. Unreleased `dev`-only shapes are not supported upgrade boundaries:\n   replace them directly, adjust local development state once when necessary,\n   and do not leave permanent migration or compatibility code behind.\n\n## UI Design Workflow\n\nFor frontend visual, layout, or interaction changes, separate product design\nfrom implementation instead of treating the first workable patch as the\ndesign.\n\n- In serial/interactive work, first present multiple viable approaches with\n  their user impact and tradeoffs, recommend one, and align with the maintainer\n  before moving into detailed design and implementation.\n- After alignment, state the chosen interaction model, responsive behavior,\n  accessibility implications, and shared primitive ownership before editing\n  the feature surface. Verify the result in the real browser route.\n- In autonomous/topic work, follow the same sequence without waiting for live\n  approval: record the alternatives and comparison in the execution plan or PR,\n  explicitly choose one, and explain why it is the best fit before implementing\n  it. Do not imply that the maintainer approved an autonomously selected design.\n- Keep the ceremony proportional for small fixes, but do not skip the design\n  decision merely because implementation is easy.\n\n## Product and Architecture Boundaries\n\n- `src/` is Alice: Workspace lifecycle, tools, data domains, HTTP/IPC surfaces,\n  file-backed state, and the UTA client boundary.\n- `services/uta/` owns broker implementations, accounts, approvals, snapshots,\n  FX, and every trading write. Do not move broker state back into Alice.\n- The model loop runs in native CLIs (`claude`, `codex`, `opencode`, `pi`).\n  Alice owns credentials and injection, not an in-process chat-agent loop.\n- New agent-facing capabilities normally ship as Workspace templates, skills,\n  or satellite repositories. Do not grow a parallel workflow engine in `src/`.\n- UTA is optional for non-trading use. Startup, onboarding, and Chat must remain\n  usable in lite/read-only mode when no broker carrier is available.\n- Chat and AutoQuant V2 workspaces are durable and reusable by default.\n  AutoQuant's internal projects and experiments remain owned by its Coding\n  Agent; do not reproduce that lifecycle in Alice.\n- `OPENALICE_HOME` is the user-state root. Changes to persisted state must use\n  the migration framework; never hide one-off cleanup in startup code.\n- Secrets never belong in tracked files, logs, fixtures, PR bodies, or agent\n  instructions. Treat account, auth, provider, and sealing paths as sensitive.\n\nSee [[docs/project-structure.md]] ([Project structure](docs/project-structure.md))\nfor current ownership and entry points.\n\n## Delivery and Branch Policy\n\n- `dev` is the integration lane. Routine PRs target `dev`.\n- `dev` is also the active preview channel: installer work must pass against\n  both the checked-out tree and the matching `raw/.../dev/install` +\n  `--branch dev` network path before promotion.\n- `master` is the stable/user-facing lane. Only human-directed promotions from\n  `dev` and explicit emergency hotfixes target `master`.\n- A merge to `master` is a versioned release event, not a post-release staging\n  step. Stable CDN aliases are updated only from the resulting tag.\n- Do not commit directly to `master`. Avoid direct commits to `dev` unless the\n  maintainer explicitly requests integration work.\n- Never force-push or delete `master` or `dev`.\n- Feature branches are disposable execution lanes. Keep them while work is\n  unmerged; delete them after GitHub records a successful merge.\n- Prefer merge commits for ordinary PRs so intentional commit history survives.\n  Squash only when the user asks or the branch history is genuinely disposable.\n- The remote `local` branch is a legacy collaboration lane, not the default\n  workflow. Do not use or delete it without first auditing its unmerged state.\n\nChoose delivery authority before implementation:\n\n| Mode | Trigger | Delivery to `dev` |\n|---|---|---|\n| Serial / interactive | Default: the user is actively requesting and steering concrete work | After proportional local verification, open and merge the PR without waiting for pending remote CI; delete the feature branch and return to updated `dev` unless the user says to pause |\n| Autonomous / topic contribution | Explicit `/goal` or direct request to autonomously find and contribute improvements | Keep one community-facing Draft PR for the active topic, add related work as atomic commits, and leave the topic unmerged for later acceptance |\n\nInternal agent decomposition must not become one GitHub PR per finding. Define a\ncoherent topic and acceptance boundary, keep a single integrator responsible for\nits branch, and accumulate independently reviewable commits in that Draft PR.\nFinish or freeze the active topic before opening another by default. Split only\nfor a genuinely different topic, a material risk/release boundary, or explicit\nmaintainer direction.\n\nLabel the topic PR with `workflow:parallel`, exactly one `theme:*`, and at least\none `area:*`; add another area only when the topic intentionally crosses owner\nboundaries. Add `review:deep` for trading writes, persisted configuration,\ncredentials, destructive actions, security boundaries, or substantial\ncross-surface structure. A later interactive message does not retroactively\nauthorize merging an autonomous topic PR. Related work may continue while its\nlatest CI is pending, but a known failure must be repaired before adding more\nscope. In serial work, pending CI likewise must not become a synchronous lock;\ninspect the previous PR checks and post-merge `dev` run before publishing the\nnext increment. `master` promotions, releases, explicit review pauses, and\nuntrusted contributions keep their full synchronous gates. Detailed topic,\nbranch, PR, promotion, hotfix, and external-contribution procedures live in\n[[docs/development-workflow.md]]\n([Development workflow](docs/development-workflow.md)).\n\n## Verification\n\nFor code changes, always run:\n\n```bash\nnpx tsc --noEmit\npnpm test\n```\n\nAdd checks according to the touched surface:\n\n| Surface | Required extra verification |\n|---|---|\n| `ui/` | `cd ui && npx tsc -b`; verify the real route in browser/dev |\n| UI `/api/*` contract or demo surface | Update `ui/src/demo/` handlers and walk `pnpm -F open-alice-ui dev:demo` |\n| `packages/<name>/` | `pnpm -F @traderalice/<name> typecheck` |\n| UTA state machine, ledger, staging, or sync logic | `pnpm test:e2e` for the MockBroker lifecycle, plus the targeted unit specs listed in [UTA live testing](docs/uta-live-testing.md) |\n| Broker adapter, order writes, or UTA permissions | Choose the smallest live-paper scenario from [UTA live testing](docs/uta-live-testing.md); verify the configured account is demo/paper first and leave it flat |\n| Workspace issues, schedules, headless dispatch | Follow [Workspace issues and scheduling](docs/workspace-issues-and-scheduling.md) |\n| Guardian locks, process ownership, takeover | `pnpm test:guardian-recovery`; exercise the real launcher path |\n| Desktop, IPC, PTY, managed Pi, shell, packaging | Follow [Managed Workspace runtime](docs/managed-workspace-runtime.md) and run the matching Electron/package smoke |\n| Root installer or distributed CLI payload | Follow [CLI installer](docs/cli-installer.md) and run `pnpm test:install:docker`; manually walk the interactive playground before release |\n| Docker/server image, Compose, remote deployment | Follow [Docker deployment](docs/docker-deployment.md) and run `pnpm docker:smoke`; before release, opt into the credentialed agent/CLI check documented there |\n| Persisted data shape | First apply the release-boundary rule above. For a shipped shape, add an idempotent migration + spec, register it, then run `pnpm build:migration-index`; replace unreleased shapes directly |\n| Onboarding/first run/auth | Use isolated data; exercise dev and packaged onboarding paths where relevant |\n\n`pnpm test:e2e` is non-trading: it must never load configured broker accounts\nor submit orders. Live-paper acceptance is a separate, explicit lane:\n`OPENALICE_UTA_LIVE_PAPER=1 pnpm test:uta:live-paper`. Never run that lane as\nroutine CI or against real-money accounts. Inspect the account mode and the\npre-test positions/orders before acknowledging it, then verify the account is\nflat after the run even when a test fails. Do not call a change verified when\nthe surface-specific path was skipped; state the remaining gap.\n\nFor local package verification, prefer `pnpm electron:smoke:workspace`: it owns\nan isolated package output and removes that large expanded app after the smoke\nexits. Use `pnpm electron:pack` only when a persistent artifact is actually\nneeded. A package passed through `--skip-pack` is externally owned and must\nnever be deleted by the smoke runner; use `--keep-package` to preserve a\ntemporary smoke package for investigation.\n\nCode signing and notarization are release gates, not routine development\nchecks. Serial/parallel `dev` work, ordinary PR package smokes, and local\npackaged-runtime debugging must build unsigned (`CSC_IDENTITY_AUTO_DISCOVERY=false`)\nand must not read release signing secrets. Run a real signed/notarized build\nonly for a versioned release candidate, an explicit release rehearsal, or a\nchange whose subject is the signing/notarization/update chain. State that\nrelease-only residual risk instead of making every development iteration pay\nthe signing cost.\n\nWhen optimizing CI/CD, preserve the lane boundaries above. First remove\nduplicate jobs, cancel superseded runs, narrow path triggers, reuse caches and\nunsigned build artifacts, and measure the slow step before considering larger\nrunners. Do not trade away the full `master` promotion/release gates merely to\nmake routine `dev` feedback look faster.\n\n## Deferred Work and Issues\n\nUse GitHub issues for concrete deferred findings. Do not create repo TODO files\nor route new work to Linear.\n\nAn actionable issue includes:\n\n- symptom and reproduction evidence;\n- suspected files or subsystem;\n- why it is deferred;\n- related PRs, commits, logs, or screenshots.\n\nHandle in-scope findings in the current PR instead of filing an issue for work\nthe same change already owns. Product-roadmap ideas still belong to the user's\nplanning surface rather than being silently converted into engineering tasks.\n\n## Implementation Plans\n\nUse `plans/<topic>.md` for substantial work that spans multiple surfaces,\nincrements, or sessions. [[PLANS.md]] is the compact index and lifecycle\ncontract.\n\n- A plan records scope, decisions, ordered work, verification, and live\n  progress. It is not an owner guide and must link to the relevant `docs/`\n  contract instead of copying it.\n- Update the plan in the same change as meaningful progress, newly discovered\n  constraints, scope changes, or completion. Checkboxes must reflect repository\n  truth rather than intent.\n- Keep one canonical plan per initiative. Extend or supersede it explicitly\n  instead of creating parallel TODO notes.\n- Active plans stay in `plans/`; completed plans remain as a concise execution\n  record and move to the Completed section of [[PLANS.md]].\n- GitHub issues remain the external defect/deferred-work surface. Reference\n  related issues and PRs from the plan; do not use a plan to hide actionable\n  deferred findings from the issue tracker.\n\n## Owner Guides\n\nRead the relevant guide before editing its subsystem:\n\n- [[docs/README.md]] — [Owner-guide index](docs/README.md) and maintenance rules.\n- [[docs/project-structure.md]] — [Project structure](docs/project-structure.md): process boundaries,\n  directories, state roots, and architectural ownership.\n- [[docs/development-workflow.md]] — [Development workflow](docs/development-workflow.md): branches, PRs,\n  delivery modes, promotions, external contributions, and risk gates.\n- [[docs/managed-workspace-runtime.md]] — [Managed Workspace runtime](docs/managed-workspace-runtime.md): Electron\n  packaging, managed Pi, PortableGit/Bash, runtime profiles, and Workspace PATH.\n- [[docs/model-semantics-and-runtime-injection.md]] — [Model semantics and runtime injection](docs/model-semantics-and-runtime-injection.md):\n  credential access, model/effort semantics, Workspace-local defaults, and\n  one-run native CLI overrides.\n- [[docs/broker-packs.md]] — [Broker Packs](docs/broker-packs.md): optional broker SDK\n  packaging, UI installation, activation, runtime loading, and release assets.\n- [[docs/cli-installer.md]] — [CLI installer](docs/cli-installer.md): consent, installed layout,\n  atomic updates, PATH integration, installer tests, and release checks.\n- [[docs/cli-supervisor.md]] — [Shell CLI Supervisor](docs/cli-supervisor.md): top-level\n  Runtime lifecycle, status/JSON presentation, browser opening, completion,\n  compatibility aliases, and Supervisor TUI boundary.\n- [[docs/local-runtime.md]] — [Local Runtime and CLI bootstrap](docs/local-runtime.md): source-backed\n  localhost startup, dependency bootstrap, Runtime ownership, and the headless bundle boundary.\n- [[docs/data-locations.md]] — [Data locations](docs/data-locations.md): complete-home selection,\n  desktop launcher preferences, concurrent instances, and directory safety.\n- [[docs/docker-deployment.md]] — [Docker deployment](docs/docker-deployment.md): server image topology,\n  remote-host safety, persistence, health, and container acceptance.\n- [[docs/remote-access.md]] — [Remote access](docs/remote-access.md): SSH tunnel experiment,\n  local/remote ownership, and staged remote-control boundaries.\n- [[docs/connector-service.md]] — [Connector Service](docs/connector-service.md): optional external Inbox\n  notification adapters, sealed credentials, health, and Guardian lifecycle.\n- [[docs/ui-interaction-and-motion.md]] — [UI interaction and motion](docs/ui-interaction-and-motion.md):\n  clickable affordances, shared motion primitives, and reduced-motion policy.\n- [[docs/workspace-agent-guidance.md]] — [Workspace agent guidance](docs/workspace-agent-guidance.md): prompt\n  layers, skill ownership, live CLI authority, and guidance versioning.\n- [[docs/workspace-lifecycle.md]] — [Workspace and Session lifecycle](docs/workspace-lifecycle.md): offboarding,\n  departed desks, handoff, restore/purge, and resumeId retirement.\n- [[docs/workspace-manager.md]] — [Workspace Manager](docs/workspace-manager.md): launcher-owned\n  control-plane cwd, WebPi quick start, peer inventory, and no-root-artifact boundary.\n- [[docs/workspace-template-upgrade.md]] — [Workspace Template Upgrade](docs/workspace-template-upgrade.md):\n  managed-asset baselines, three-way review, safe apply, recovery, and the future Merge/Absorb boundary.\n- [[docs/workspace-absorb.md]] — [Workspace Absorb](docs/workspace-absorb.md): directional\n  Workspace consolidation, file collisions, archived source identity, and recovery.\n- [[docs/uta-live-testing.md]] — [UTA live testing](docs/uta-live-testing.md): broker/trading acceptance loops.\n- [[docs/ibkr-wire-protocol.md]] — [IBKR wire protocol](docs/ibkr-wire-protocol.md): TWS/Gateway inbound framing and decoder failure isolation.\n- [[docs/workspace-issues-and-scheduling.md]] — [Workspace issues and scheduling](docs/workspace-issues-and-scheduling.md): Issue board, schedules, headless runs, and Inbox delivery.\n- [[docs/conversation-provenance.md]] — [Workspace Session and artifact provenance](docs/conversation-provenance.md): `resumeId` identity, artifact trails, Issue responsibility, and the provenance-before-collaboration delivery order.\n- [[docs/event-system.md]] — [Event-system retirement note](docs/event-system.md): removed Alice event-bus scheduler; UTA journal utility only.\n- [[docs/market-data-architecture.md]] — [Market data architecture](docs/market-data-architecture.md): TraderHub, K-line providers, and the private compatibility package.\n- `src/migrations/INDEX.md` — generated migration inventory and affected paths.\n\n`README.md` is public product positioning. After a genuinely large product\nshift, identify stale sections, but ask the user for framing before rewriting\nthe tagline, pillars, or other marketing copy.\n\n## Code Conventions\n\n- ESM only; include `.js` extensions in TypeScript imports.\n- Strict TypeScript, ES2023 target.\n- Zod for config schemas; TypeBox for tool parameter schemas.\n- `decimal.js` for financial arithmetic.\n- For standard UI controls, prefer the shared shadcn/Base UI primitives under\n  `ui/src/components/ui/`. Extend that layer before hand-rolling portals,\n  positioning, focus, dismissal, keyboard behavior, or bespoke control styling\n  inside a feature component.\n- Frontend reads of backend-owned data must go through a domain hook rather\n  than calling an API or reaching into a transport/polling context from a\n  feature component. Keep presentation components prop-driven, and cover each\n  data hook with unit tests for its selection plus loading/error semantics.\n- Prefer structured Workspace launcher logs; the main process currently uses\n  `console` and does not have a universal pino sink.\n"},"files":{"CLAUDE.md":"@AGENTS.md\n\n<!--\n  AGENTS.md is the canonical repository instruction file. Claude Code supports\n  importing it directly; keep Claude-specific additions exceptional and short.\n-->\n","AGENTS.md":"# OpenAlice\n\nOpenAlice is a local trading workspace for native coding-agent CLIs. The main\nprocess is a Workspace launcher and trading-context injector; broker credentials,\nconnections, and trading state belong to the separate UTA process. Persisted\nstate is file-backed rather than database-backed.\n\nKeep this file short. It contains rules that apply to every task. Detailed\narchitecture and operating procedures live in the owner guides linked below.\nCurrent code, tests, rendered behavior, and GitHub state override stale prose.\n\nDurable subsystem truth lives under [[docs/README.md]]. Active multi-step\nimplementation work lives under [[PLANS.md]]. Keep both indexes current when a\nchange introduces a new owner guide or execution plan.\n\n## Start Here\n\n```bash\npnpm install              # full local install, including Electron\npnpm dev                  # Guardian -> UTA + Alice + Vite\npnpm dev --takeover       # replace the recorded local Guardian owner tree\npnpm build                # packages + UI + UTA + Alice\npnpm test                 # monorepo Vitest suite\npnpm test:e2e             # non-trading product/integration E2E\n```\n\nBefore changing files:\n\n1. Run `git fetch origin`, `git status -sb`, and inspect the current diff.\n2. Preserve unrelated user changes. Do not reset, overwrite, stash, or commit\n   them merely to obtain a clean tree.\n3. Routine work starts from current `dev` on a focused feature branch. If the\n   checkout is on `master`, a merged branch, or a surprising historical branch,\n   stop and establish the intended base before editing.\n4. Start from the real surface: reproduce UI/runtime behavior, inspect the\n   relevant current code, and read the applicable owner guide before designing.\n5. Before adding a data migration, compatibility parser, or dual-read path,\n   establish whether the affected persisted shape shipped in a released\n   version. Unreleased `dev`-only shapes are not supported upgrade boundaries:\n   replace them directly, adjust local development state once when necessary,\n   and do not leave permanent migration or compatibility code behind.\n\n## UI Design Workflow\n\nFor frontend visual, layout, or interaction changes, separate product design\nfrom implementation instead of treating the first workable patch as the\ndesign.\n\n- In serial/interactive work, first present multiple viable approaches with\n  their user impact and tradeoffs, recommend one, and align with the maintainer\n  before moving into detailed design and implementation.\n- After alignment, state the chosen interaction model, responsive behavior,\n  accessibility implications, and shared primitive ownership before editing\n  the feature surface. Verify the result in the real browser route.\n- In autonomous/topic work, follow the same sequence without waiting for live\n  approval: record the alternatives and comparison in the execution plan or PR,\n  explicitly choose one, and explain why it is the best fit before implementing\n  it. Do not imply that the maintainer approved an autonomously selected design.\n- Keep the ceremony proportional for small fixes, but do not skip the design\n  decision merely because implementation is easy.\n\n## Product and Architecture Boundaries\n\n- `src/` is Alice: Workspace lifecycle, tools, data domains, HTTP/IPC surfaces,\n  file-backed state, and the UTA client boundary.\n- `services/uta/` owns broker implementations, accounts, approvals, snapshots,\n  FX, and every trading write. Do not move broker state back into Alice.\n- The model loop runs in native CLIs (`claude`, `codex`, `opencode`, `pi`).\n  Alice owns credentials and injection, not an in-process chat-agent loop.\n- New agent-facing capabilities normally ship as Workspace templates, skills,\n  or satellite repositories. Do not grow a parallel workflow engine in `src/`.\n- UTA is optional for non-trading use. Startup, onboarding, and Chat must remain\n  usable in lite/read-only mode when no broker carrier is available.\n- Chat and AutoQuant V2 workspaces are durable and reusable by default.\n  AutoQuant's internal projects and experiments remain owned by its Coding\n  Agent; do not reproduce that lifecycle in Alice.\n- `OPENALICE_HOME` is the user-state root. Changes to persisted state must use\n  the migration framework; never hide one-off cleanup in startup code.\n- Secrets never belong in tracked files, logs, fixtures, PR bodies, or agent\n  instructions. Treat account, auth, provider, and sealing paths as sensitive.\n\nSee [[docs/project-structure.md]] ([Project structure](docs/project-structure.md))\nfor current ownership and entry points.\n\n## Delivery and Branch Policy\n\n- `dev` is the integration lane. Routine PRs target `dev`.\n- `dev` is also the active preview channel: installer work must pass against\n  both the checked-out tree and the matching `raw/.../dev/install` +\n  `--branch dev` network path before promotion.\n- `master` is the stable/user-facing lane. Only human-directed promotions from\n  `dev` and explicit emergency hotfixes target `master`.\n- A merge to `master` is a versioned release event, not a post-release staging\n  step. Stable CDN aliases are updated only from the resulting tag.\n- Do not commit directly to `master`. Avoid direct commits to `dev` unless the\n  maintainer explicitly requests integration work.\n- Never force-push or delete `master` or `dev`.\n- Feature branches are disposable execution lanes. Keep them while work is\n  unmerged; delete them after GitHub records a successful merge.\n- Prefer merge commits for ordinary PRs so intentional commit history survives.\n  Squash only when the user asks or the branch history is genuinely disposable.\n- The remote `local` branch is a legacy collaboration lane, not the default\n  workflow. Do not use or delete it without first auditing its unmerged state.\n\nChoose delivery authority before implementation:\n\n| Mode | Trigger | Delivery to `dev` |\n|---|---|---|\n| Serial / interactive | Default: the user is actively requesting and steering concrete work | After proportional local verification, open and merge the PR without waiting for pending remote CI; delete the feature branch and return to updated `dev` unless the user says to pause |\n| Autonomous / topic contribution | Explicit `/goal` or direct request to autonomously find and contribute improvements | Keep one community-facing Draft PR for the active topic, add related work as atomic commits, and leave the topic unmerged for later acceptance |\n\nInternal agent decomposition must not become one GitHub PR per finding. Define a\ncoherent topic and acceptance boundary, keep a single integrator responsible for\nits branch, and accumulate independently reviewable commits in that Draft PR.\nFinish or freeze the active topic before opening another by default. Split only\nfor a genuinely different topic, a material risk/release boundary, or explicit\nmaintainer direction.\n\nLabel the topic PR with `workflow:parallel`, exactly one `theme:*`, and at least\none `area:*`; add another area only when the topic intentionally crosses owner\nboundaries. Add `review:deep` for trading writes, persisted configuration,\ncredentials, destructive actions, security boundaries, or substantial\ncross-surface structure. A later interactive message does not retroactively\nauthorize merging an autonomous topic PR. Related work may continue while its\nlatest CI is pending, but a known failure must be repaired before adding more\nscope. In serial work, pending CI likewise must not become a synchronous lock;\ninspect the previous PR checks and post-merge `dev` run before publishing the\nnext increment. `master` promotions, releases, explicit review pauses, and\nuntrusted contributions keep their full synchronous gates. Detailed topic,\nbranch, PR, promotion, hotfix, and external-contribution procedures live in\n[[docs/development-workflow.md]]\n([Development workflow](docs/development-workflow.md)).\n\n## Verification\n\nFor code changes, always run:\n\n```bash\nnpx tsc --noEmit\npnpm test\n```\n\nAdd checks according to the touched surface:\n\n| Surface | Required extra verification |\n|---|---|\n| `ui/` | `cd ui && npx tsc -b`; verify the real route in browser/dev |\n| UI `/api/*` contract or demo surface | Update `ui/src/demo/` handlers and walk `pnpm -F open-alice-ui dev:demo` |\n| `packages/<name>/` | `pnpm -F @traderalice/<name> typecheck` |\n| UTA state machine, ledger, staging, or sync logic | `pnpm test:e2e` for the MockBroker lifecycle, plus the targeted unit specs listed in [UTA live testing](docs/uta-live-testing.md) |\n| Broker adapter, order writes, or UTA permissions | Choose the smallest live-paper scenario from [UTA live testing](docs/uta-live-testing.md); verify the configured account is demo/paper first and leave it flat |\n| Workspace issues, schedules, headless dispatch | Follow [Workspace issues and scheduling](docs/workspace-issues-and-scheduling.md) |\n| Guardian locks, process ownership, takeover | `pnpm test:guardian-recovery`; exercise the real launcher path |\n| Desktop, IPC, PTY, managed Pi, shell, packaging | Follow [Managed Workspace runtime](docs/managed-workspace-runtime.md) and run the matching Electron/package smoke |\n| Root installer or distributed CLI payload | Follow [CLI installer](docs/cli-installer.md) and run `pnpm test:install:docker`; manually walk the interactive playground before release |\n| Docker/server image, Compose, remote deployment | Follow [Docker deployment](docs/docker-deployment.md) and run `pnpm docker:smoke`; before release, opt into the credentialed agent/CLI check documented there |\n| Persisted data shape | First apply the release-boundary rule above. For a shipped shape, add an idempotent migration + spec, register it, then run `pnpm build:migration-index`; replace unreleased shapes directly |\n| Onboarding/first run/auth | Use isolated data; exercise dev and packaged onboarding paths where relevant |\n\n`pnpm test:e2e` is non-trading: it must never load configured broker accounts\nor submit orders. Live-paper acceptance is a separate, explicit lane:\n`OPENALICE_UTA_LIVE_PAPER=1 pnpm test:uta:live-paper`. Never run that lane as\nroutine CI or against real-money accounts. Inspect the account mode and the\npre-test positions/orders before acknowledging it, then verify the account is\nflat after the run even when a test fails. Do not call a change verified when\nthe surface-specific path was skipped; state the remaining gap.\n\nFor local package verification, prefer `pnpm electron:smoke:workspace`: it owns\nan isolated package output and removes that large expanded app after the smoke\nexits. Use `pnpm electron:pack` only when a persistent artifact is actually\nneeded. A package passed through `--skip-pack` is externally owned and must\nnever be deleted by the smoke runner; use `--keep-package` to preserve a\ntemporary smoke package for investigation.\n\nCode signing and notarization are release gates, not routine development\nchecks. Serial/parallel `dev` work, ordinary PR package smokes, and local\npackaged-runtime debugging must build unsigned (`CSC_IDENTITY_AUTO_DISCOVERY=false`)\nand must not read release signing secrets. Run a real signed/notarized build\nonly for a versioned release candidate, an explicit release rehearsal, or a\nchange whose subject is the signing/notarization/update chain. State that\nrelease-only residual risk instead of making every development iteration pay\nthe signing cost.\n\nWhen optimizing CI/CD, preserve the lane boundaries above. First remove\nduplicate jobs, cancel superseded runs, narrow path triggers, reuse caches and\nunsigned build artifacts, and measure the slow step before considering larger\nrunners. Do not trade away the full `master` promotion/release gates merely to\nmake routine `dev` feedback look faster.\n\n## Deferred Work and Issues\n\nUse GitHub issues for concrete deferred findings. Do not create repo TODO files\nor route new work to Linear.\n\nAn actionable issue includes:\n\n- symptom and reproduction evidence;\n- suspected files or subsystem;\n- why it is deferred;\n- related PRs, commits, logs, or screenshots.\n\nHandle in-scope findings in the current PR instead of filing an issue for work\nthe same change already owns. Product-roadmap ideas still belong to the user's\nplanning surface rather than being silently converted into engineering tasks.\n\n## Implementation Plans\n\nUse `plans/<topic>.md` for substantial work that spans multiple surfaces,\nincrements, or sessions. [[PLANS.md]] is the compact index and lifecycle\ncontract.\n\n- A plan records scope, decisions, ordered work, verification, and live\n  progress. It is not an owner guide and must link to the relevant `docs/`\n  contract instead of copying it.\n- Update the plan in the same change as meaningful progress, newly discovered\n  constraints, scope changes, or completion. Checkboxes must reflect repository\n  truth rather than intent.\n- Keep one canonical plan per initiative. Extend or supersede it explicitly\n  instead of creating parallel TODO notes.\n- Active plans stay in `plans/`; completed plans remain as a concise execution\n  record and move to the Completed section of [[PLANS.md]].\n- GitHub issues remain the external defect/deferred-work surface. Reference\n  related issues and PRs from the plan; do not use a plan to hide actionable\n  deferred findings from the issue tracker.\n\n## Owner Guides\n\nRead the relevant guide before editing its subsystem:\n\n- [[docs/README.md]] — [Owner-guide index](docs/README.md) and maintenance rules.\n- [[docs/project-structure.md]] — [Project structure](docs/project-structure.md): process boundaries,\n  directories, state roots, and architectural ownership.\n- [[docs/development-workflow.md]] — [Development workflow](docs/development-workflow.md): branches, PRs,\n  delivery modes, promotions, external contributions, and risk gates.\n- [[docs/managed-workspace-runtime.md]] — [Managed Workspace runtime](docs/managed-workspace-runtime.md): Electron\n  packaging, managed Pi, PortableGit/Bash, runtime profiles, and Workspace PATH.\n- [[docs/model-semantics-and-runtime-injection.md]] — [Model semantics and runtime injection](docs/model-semantics-and-runtime-injection.md):\n  credential access, model/effort semantics, Workspace-local defaults, and\n  one-run native CLI overrides.\n- [[docs/broker-packs.md]] — [Broker Packs](docs/broker-packs.md): optional broker SDK\n  packaging, UI installation, activation, runtime loading, and release assets.\n- [[docs/cli-installer.md]] — [CLI installer](docs/cli-installer.md): consent, installed layout,\n  atomic updates, PATH integration, installer tests, and release checks.\n- [[docs/cli-supervisor.md]] — [Shell CLI Supervisor](docs/cli-supervisor.md): top-level\n  Runtime lifecycle, status/JSON presentation, browser opening, completion,\n  compatibility aliases, and Supervisor TUI boundary.\n- [[docs/local-runtime.md]] — [Local Runtime and CLI bootstrap](docs/local-runtime.md): source-backed\n  localhost startup, dependency bootstrap, Runtime ownership, and the headless bundle boundary.\n- [[docs/data-locations.md]] — [Data locations](docs/data-locations.md): complete-home selection,\n  desktop launcher preferences, concurrent instances, and directory safety.\n- [[docs/docker-deployment.md]] — [Docker deployment](docs/docker-deployment.md): server image topology,\n  remote-host safety, persistence, health, and container acceptance.\n- [[docs/remote-access.md]] — [Remote access](docs/remote-access.md): SSH tunnel experiment,\n  local/remote ownership, and staged remote-control boundaries.\n- [[docs/connector-service.md]] — [Connector Service](docs/connector-service.md): optional external Inbox\n  notification adapters, sealed credentials, health, and Guardian lifecycle.\n- [[docs/ui-interaction-and-motion.md]] — [UI interaction and motion](docs/ui-interaction-and-motion.md):\n  clickable affordances, shared motion primitives, and reduced-motion policy.\n- [[docs/workspace-agent-guidance.md]] — [Workspace agent guidance](docs/workspace-agent-guidance.md): prompt\n  layers, skill ownership, live CLI authority, and guidance versioning.\n- [[docs/workspace-lifecycle.md]] — [Workspace and Session lifecycle](docs/workspace-lifecycle.md): offboarding,\n  departed desks, handoff, restore/purge, and resumeId retirement.\n- [[docs/workspace-manager.md]] — [Workspace Manager](docs/workspace-manager.md): launcher-owned\n  control-plane cwd, WebPi quick start, peer inventory, and no-root-artifact boundary.\n- [[docs/workspace-template-upgrade.md]] — [Workspace Template Upgrade](docs/workspace-template-upgrade.md):\n  managed-asset baselines, three-way review, safe apply, recovery, and the future Merge/Absorb boundary.\n- [[docs/workspace-absorb.md]] — [Workspace Absorb](docs/workspace-absorb.md): directional\n  Workspace consolidation, file collisions, archived source identity, and recovery.\n- [[docs/uta-live-testing.md]] — [UTA live testing](docs/uta-live-testing.md): broker/trading acceptance loops.\n- [[docs/ibkr-wire-protocol.md]] — [IBKR wire protocol](docs/ibkr-wire-protocol.md): TWS/Gateway inbound framing and decoder failure isolation.\n- [[docs/workspace-issues-and-scheduling.md]] — [Workspace issues and scheduling](docs/workspace-issues-and-scheduling.md): Issue board, schedules, headless runs, and Inbox delivery.\n- [[docs/conversation-provenance.md]] — [Workspace Session and artifact provenance](docs/conversation-provenance.md): `resumeId` identity, artifact trails, Issue responsibility, and the provenance-before-collaboration delivery order.\n- [[docs/event-system.md]] — [Event-system retirement note](docs/event-system.md): removed Alice event-bus scheduler; UTA journal utility only.\n- [[docs/market-data-architecture.md]] — [Market data architecture](docs/market-data-architecture.md): TraderHub, K-line providers, and the private compatibility package.\n- `src/migrations/INDEX.md` — generated migration inventory and affected paths.\n\n`README.md` is public product positioning. After a genuinely large product\nshift, identify stale sections, but ask the user for framing before rewriting\nthe tagline, pillars, or other marketing copy.\n\n## Code Conventions\n\n- ESM only; include `.js` extensions in TypeScript imports.\n- Strict TypeScript, ES2023 target.\n- Zod for config schemas; TypeBox for tool parameter schemas.\n- `decimal.js` for financial arithmetic.\n- For standard UI controls, prefer the shared shadcn/Base UI primitives under\n  `ui/src/components/ui/`. Extend that layer before hand-rolling portals,\n  positioning, focus, dismissal, keyboard behavior, or bespoke control styling\n  inside a feature component.\n- Frontend reads of backend-owned data must go through a domain hook rather\n  than calling an API or reaching into a transport/polling context from a\n  feature component. Keep presentation components prop-driven, and cover each\n  data hook with unit tests for its selection plus loading/error semantics.\n- Prefer structured Workspace launcher logs; the main process currently uses\n  `console` and does not have a universal pino sink.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"@AGENTS.md\n\n<!--\n  AGENTS.md is the canonical repository instruction file. Claude Code supports\n  importing it directly; keep Claude-specific additions exceptional and short.\n-->\n","category":"root","tokens":45},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# OpenAlice\n\nOpenAlice is a local trading workspace for native coding-agent CLIs. The main\nprocess is a Workspace launcher and trading-context injector; broker credentials,\nconnections, and trading state belong to the separate UTA process. Persisted\nstate is file-backed rather than database-backed.\n\nKeep this file short. It contains rules that apply to every task. Detailed\narchitecture and operating procedures live in the owner guides linked below.\nCurrent code, tests, rendered behavior, and GitHub state override stale prose.\n\nDurable subsystem truth lives under [[docs/README.md]]. Active multi-step\nimplementation work lives under [[PLANS.md]]. Keep both indexes current when a\nchange introduces a new owner guide or execution plan.\n\n## Start Here\n\n```bash\npnpm install              # full local install, including Electron\npnpm dev                  # Guardian -> UTA + Alice + Vite\npnpm dev --takeover       # replace the recorded local Guardian owner tree\npnpm build                # packages + UI + UTA + Alice\npnpm test                 # monorepo Vitest suite\npnpm test:e2e             # non-trading product/integration E2E\n```\n\nBefore changing files:\n\n1. Run `git fetch origin`, `git status -sb`, and inspect the current diff.\n2. Preserve unrelated user changes. Do not reset, overwrite, stash, or commit\n   them merely to obtain a clean tree.\n3. Routine work starts from current `dev` on a focused feature branch. If the\n   checkout is on `master`, a merged branch, or a surprising historical branch,\n   stop and establish the intended base before editing.\n4. Start from the real surface: reproduce UI/runtime behavior, inspect the\n   relevant current code, and read the applicable owner guide before designing.\n5. Before adding a data migration, compatibility parser, or dual-read path,\n   establish whether the affected persisted shape shipped in a released\n   version. Unreleased `dev`-only shapes are not supported upgrade boundaries:\n   replace them directly, adjust local development state once when necessary,\n   and do not leave permanent migration or compatibility code behind.\n\n## UI Design Workflow\n\nFor frontend visual, layout, or interaction changes, separate product design\nfrom implementation instead of treating the first workable patch as the\ndesign.\n\n- In serial/interactive work, first present multiple viable approaches with\n  their user impact and tradeoffs, recommend one, and align with the maintainer\n  before moving into detailed design and implementation.\n- After alignment, state the chosen interaction model, responsive behavior,\n  accessibility implications, and shared primitive ownership before editing\n  the feature surface. Verify the result in the real browser route.\n- In autonomous/topic work, follow the same sequence without waiting for live\n  approval: record the alternatives and comparison in the execution plan or PR,\n  explicitly choose one, and explain why it is the best fit before implementing\n  it. Do not imply that the maintainer approved an autonomously selected design.\n- Keep the ceremony proportional for small fixes, but do not skip the design\n  decision merely because implementation is easy.\n\n## Product and Architecture Boundaries\n\n- `src/` is Alice: Workspace lifecycle, tools, data domains, HTTP/IPC surfaces,\n  file-backed state, and the UTA client boundary.\n- `services/uta/` owns broker implementations, accounts, approvals, snapshots,\n  FX, and every trading write. Do not move broker state back into Alice.\n- The model loop runs in native CLIs (`claude`, `codex`, `opencode`, `pi`).\n  Alice owns credentials and injection, not an in-process chat-agent loop.\n- New agent-facing capabilities normally ship as Workspace templates, skills,\n  or satellite repositories. Do not grow a parallel workflow engine in `src/`.\n- UTA is optional for non-trading use. Startup, onboarding, and Chat must remain\n  usable in lite/read-only mode when no broker carrier is available.\n- Chat and AutoQuant V2 workspaces are durable and reusable by default.\n  AutoQuant's internal projects and experiments remain owned by its Coding\n  Agent; do not reproduce that lifecycle in Alice.\n- `OPENALICE_HOME` is the user-state root. Changes to persisted state must use\n  the migration framework; never hide one-off cleanup in startup code.\n- Secrets never belong in tracked files, logs, fixtures, PR bodies, or agent\n  instructions. Treat account, auth, provider, and sealing paths as sensitive.\n\nSee [[docs/project-structure.md]] ([Project structure](docs/project-structure.md))\nfor current ownership and entry points.\n\n## Delivery and Branch Policy\n\n- `dev` is the integration lane. Routine PRs target `dev`.\n- `dev` is also the active preview channel: installer work must pass against\n  both the checked-out tree and the matching `raw/.../dev/install` +\n  `--branch dev` network path before promotion.\n- `master` is the stable/user-facing lane. Only human-directed promotions from\n  `dev` and explicit emergency hotfixes target `master`.\n- A merge to `master` is a versioned release event, not a post-release staging\n  step. Stable CDN aliases are updated only from the resulting tag.\n- Do not commit directly to `master`. Avoid direct commits to `dev` unless the\n  maintainer explicitly requests integration work.\n- Never force-push or delete `master` or `dev`.\n- Feature branches are disposable execution lanes. Keep them while work is\n  unmerged; delete them after GitHub records a successful merge.\n- Prefer merge commits for ordinary PRs so intentional commit history survives.\n  Squash only when the user asks or the branch history is genuinely disposable.\n- The remote `local` branch is a legacy collaboration lane, not the default\n  workflow. Do not use or delete it without first auditing its unmerged state.\n\nChoose delivery authority before implementation:\n\n| Mode | Trigger | Delivery to `dev` |\n|---|---|---|\n| Serial / interactive | Default: the user is actively requesting and steering concrete work | After proportional local verification, open and merge the PR without waiting for pending remote CI; delete the feature branch and return to updated `dev` unless the user says to pause |\n| Autonomous / topic contribution | Explicit `/goal` or direct request to autonomously find and contribute improvements | Keep one community-facing Draft PR for the active topic, add related work as atomic commits, and leave the topic unmerged for later acceptance |\n\nInternal agent decomposition must not become one GitHub PR per finding. Define a\ncoherent topic and acceptance boundary, keep a single integrator responsible for\nits branch, and accumulate independently reviewable commits in that Draft PR.\nFinish or freeze the active topic before opening another by default. Split only\nfor a genuinely different topic, a material risk/release boundary, or explicit\nmaintainer direction.\n\nLabel the topic PR with `workflow:parallel`, exactly one `theme:*`, and at least\none `area:*`; add another area only when the topic intentionally crosses owner\nboundaries. Add `review:deep` for trading writes, persisted configuration,\ncredentials, destructive actions, security boundaries, or substantial\ncross-surface structure. A later interactive message does not retroactively\nauthorize merging an autonomous topic PR. Related work may continue while its\nlatest CI is pending, but a known failure must be repaired before adding more\nscope. In serial work, pending CI likewise must not become a synchronous lock;\ninspect the previous PR checks and post-merge `dev` run before publishing the\nnext increment. `master` promotions, releases, explicit review pauses, and\nuntrusted contributions keep their full synchronous gates. Detailed topic,\nbranch, PR, promotion, hotfix, and external-contribution procedures live in\n[[docs/development-workflow.md]]\n([Development workflow](docs/development-workflow.md)).\n\n## Verification\n\nFor code changes, always run:\n\n```bash\nnpx tsc --noEmit\npnpm test\n```\n\nAdd checks according to the touched surface:\n\n| Surface | Required extra verification |\n|---|---|\n| `ui/` | `cd ui && npx tsc -b`; verify the real route in browser/dev |\n| UI `/api/*` contract or demo surface | Update `ui/src/demo/` handlers and walk `pnpm -F open-alice-ui dev:demo` |\n| `packages/<name>/` | `pnpm -F @traderalice/<name> typecheck` |\n| UTA state machine, ledger, staging, or sync logic | `pnpm test:e2e` for the MockBroker lifecycle, plus the targeted unit specs listed in [UTA live testing](docs/uta-live-testing.md) |\n| Broker adapter, order writes, or UTA permissions | Choose the smallest live-paper scenario from [UTA live testing](docs/uta-live-testing.md); verify the configured account is demo/paper first and leave it flat |\n| Workspace issues, schedules, headless dispatch | Follow [Workspace issues and scheduling](docs/workspace-issues-and-scheduling.md) |\n| Guardian locks, process ownership, takeover | `pnpm test:guardian-recovery`; exercise the real launcher path |\n| Desktop, IPC, PTY, managed Pi, shell, packaging | Follow [Managed Workspace runtime](docs/managed-workspace-runtime.md) and run the matching Electron/package smoke |\n| Root installer or distributed CLI payload | Follow [CLI installer](docs/cli-installer.md) and run `pnpm test:install:docker`; manually walk the interactive playground before release |\n| Docker/server image, Compose, remote deployment | Follow [Docker deployment](docs/docker-deployment.md) and run `pnpm docker:smoke`; before release, opt into the credentialed agent/CLI check documented there |\n| Persisted data shape | First apply the release-boundary rule above. For a shipped shape, add an idempotent migration + spec, register it, then run `pnpm build:migration-index`; replace unreleased shapes directly |\n| Onboarding/first run/auth | Use isolated data; exercise dev and packaged onboarding paths where relevant |\n\n`pnpm test:e2e` is non-trading: it must never load configured broker accounts\nor submit orders. Live-paper acceptance is a separate, explicit lane:\n`OPENALICE_UTA_LIVE_PAPER=1 pnpm test:uta:live-paper`. Never run that lane as\nroutine CI or against real-money accounts. Inspect the account mode and the\npre-test positions/orders before acknowledging it, then verify the account is\nflat after the run even when a test fails. Do not call a change verified when\nthe surface-specific path was skipped; state the remaining gap.\n\nFor local package verification, prefer `pnpm electron:smoke:workspace`: it owns\nan isolated package output and removes that large expanded app after the smoke\nexits. Use `pnpm electron:pack` only when a persistent artifact is actually\nneeded. A package passed through `--skip-pack` is externally owned and must\nnever be deleted by the smoke runner; use `--keep-package` to preserve a\ntemporary smoke package for investigation.\n\nCode signing and notarization are release gates, not routine development\nchecks. Serial/parallel `dev` work, ordinary PR package smokes, and local\npackaged-runtime debugging must build unsigned (`CSC_IDENTITY_AUTO_DISCOVERY=false`)\nand must not read release signing secrets. Run a real signed/notarized build\nonly for a versioned release candidate, an explicit release rehearsal, or a\nchange whose subject is the signing/notarization/update chain. State that\nrelease-only residual risk instead of making every development iteration pay\nthe signing cost.\n\nWhen optimizing CI/CD, preserve the lane boundaries above. First remove\nduplicate jobs, cancel superseded runs, narrow path triggers, reuse caches and\nunsigned build artifacts, and measure the slow step before considering larger\nrunners. Do not trade away the full `master` promotion/release gates merely to\nmake routine `dev` feedback look faster.\n\n## Deferred Work and Issues\n\nUse GitHub issues for concrete deferred findings. Do not create repo TODO files\nor route new work to Linear.\n\nAn actionable issue includes:\n\n- symptom and reproduction evidence;\n- suspected files or subsystem;\n- why it is deferred;\n- related PRs, commits, logs, or screenshots.\n\nHandle in-scope findings in the current PR instead of filing an issue for work\nthe same change already owns. Product-roadmap ideas still belong to the user's\nplanning surface rather than being silently converted into engineering tasks.\n\n## Implementation Plans\n\nUse `plans/<topic>.md` for substantial work that spans multiple surfaces,\nincrements, or sessions. [[PLANS.md]] is the compact index and lifecycle\ncontract.\n\n- A plan records scope, decisions, ordered work, verification, and live\n  progress. It is not an owner guide and must link to the relevant `docs/`\n  contract instead of copying it.\n- Update the plan in the same change as meaningful progress, newly discovered\n  constraints, scope changes, or completion. Checkboxes must reflect repository\n  truth rather than intent.\n- Keep one canonical plan per initiative. Extend or supersede it explicitly\n  instead of creating parallel TODO notes.\n- Active plans stay in `plans/`; completed plans remain as a concise execution\n  record and move to the Completed section of [[PLANS.md]].\n- GitHub issues remain the external defect/deferred-work surface. Reference\n  related issues and PRs from the plan; do not use a plan to hide actionable\n  deferred findings from the issue tracker.\n\n## Owner Guides\n\nRead the relevant guide before editing its subsystem:\n\n- [[docs/README.md]] — [Owner-guide index](docs/README.md) and maintenance rules.\n- [[docs/project-structure.md]] — [Project structure](docs/project-structure.md): process boundaries,\n  directories, state roots, and architectural ownership.\n- [[docs/development-workflow.md]] — [Development workflow](docs/development-workflow.md): branches, PRs,\n  delivery modes, promotions, external contributions, and risk gates.\n- [[docs/managed-workspace-runtime.md]] — [Managed Workspace runtime](docs/managed-workspace-runtime.md): Electron\n  packaging, managed Pi, PortableGit/Bash, runtime profiles, and Workspace PATH.\n- [[docs/model-semantics-and-runtime-injection.md]] — [Model semantics and runtime injection](docs/model-semantics-and-runtime-injection.md):\n  credential access, model/effort semantics, Workspace-local defaults, and\n  one-run native CLI overrides.\n- [[docs/broker-packs.md]] — [Broker Packs](docs/broker-packs.md): optional broker SDK\n  packaging, UI installation, activation, runtime loading, and release assets.\n- [[docs/cli-installer.md]] — [CLI installer](docs/cli-installer.md): consent, installed layout,\n  atomic updates, PATH integration, installer tests, and release checks.\n- [[docs/cli-supervisor.md]] — [Shell CLI Supervisor](docs/cli-supervisor.md): top-level\n  Runtime lifecycle, status/JSON presentation, browser opening, completion,\n  compatibility aliases, and Supervisor TUI boundary.\n- [[docs/local-runtime.md]] — [Local Runtime and CLI bootstrap](docs/local-runtime.md): source-backed\n  localhost startup, dependency bootstrap, Runtime ownership, and the headless bundle boundary.\n- [[docs/data-locations.md]] — [Data locations](docs/data-locations.md): complete-home selection,\n  desktop launcher preferences, concurrent instances, and directory safety.\n- [[docs/docker-deployment.md]] — [Docker deployment](docs/docker-deployment.md): server image topology,\n  remote-host safety, persistence, health, and container acceptance.\n- [[docs/remote-access.md]] — [Remote access](docs/remote-access.md): SSH tunnel experiment,\n  local/remote ownership, and staged remote-control boundaries.\n- [[docs/connector-service.md]] — [Connector Service](docs/connector-service.md): optional external Inbox\n  notification adapters, sealed credentials, health, and Guardian lifecycle.\n- [[docs/ui-interaction-and-motion.md]] — [UI interaction and motion](docs/ui-interaction-and-motion.md):\n  clickable affordances, shared motion primitives, and reduced-motion policy.\n- [[docs/workspace-agent-guidance.md]] — [Workspace agent guidance](docs/workspace-agent-guidance.md): prompt\n  layers, skill ownership, live CLI authority, and guidance versioning.\n- [[docs/workspace-lifecycle.md]] — [Workspace and Session lifecycle](docs/workspace-lifecycle.md): offboarding,\n  departed desks, handoff, restore/purge, and resumeId retirement.\n- [[docs/workspace-manager.md]] — [Workspace Manager](docs/workspace-manager.md): launcher-owned\n  control-plane cwd, WebPi quick start, peer inventory, and no-root-artifact boundary.\n- [[docs/workspace-template-upgrade.md]] — [Workspace Template Upgrade](docs/workspace-template-upgrade.md):\n  managed-asset baselines, three-way review, safe apply, recovery, and the future Merge/Absorb boundary.\n- [[docs/workspace-absorb.md]] — [Workspace Absorb](docs/workspace-absorb.md): directional\n  Workspace consolidation, file collisions, archived source identity, and recovery.\n- [[docs/uta-live-testing.md]] — [UTA live testing](docs/uta-live-testing.md): broker/trading acceptance loops.\n- [[docs/ibkr-wire-protocol.md]] — [IBKR wire protocol](docs/ibkr-wire-protocol.md): TWS/Gateway inbound framing and decoder failure isolation.\n- [[docs/workspace-issues-and-scheduling.md]] — [Workspace issues and scheduling](docs/workspace-issues-and-scheduling.md): Issue board, schedules, headless runs, and Inbox delivery.\n- [[docs/conversation-provenance.md]] — [Workspace Session and artifact provenance](docs/conversation-provenance.md): `resumeId` identity, artifact trails, Issue responsibility, and the provenance-before-collaboration delivery order.\n- [[docs/event-system.md]] — [Event-system retirement note](docs/event-system.md): removed Alice event-bus scheduler; UTA journal utility only.\n- [[docs/market-data-architecture.md]] — [Market data architecture](docs/market-data-architecture.md): TraderHub, K-line providers, and the private compatibility package.\n- `src/migrations/INDEX.md` — generated migration inventory and affected paths.\n\n`README.md` is public product positioning. After a genuinely large product\nshift, identify stale sections, but ask the user for framing before rewriting\nthe tagline, pillars, or other marketing copy.\n\n## Code Conventions\n\n- ESM only; include `.js` extensions in TypeScript imports.\n- Strict TypeScript, ES2023 target.\n- Zod for config schemas; TypeBox for tool parameter schemas.\n- `decimal.js` for financial arithmetic.\n- For standard UI controls, prefer the shared shadcn/Base UI primitives under\n  `ui/src/components/ui/`. Extend that layer before hand-rolling portals,\n  positioning, focus, dismissal, keyboard behavior, or bespoke control styling\n  inside a feature component.\n- Frontend reads of backend-owned data must go through a domain hook rather\n  than calling an API or reaching into a transport/polling context from a\n  feature component. Keep presentation components prop-driven, and cover each\n  data hook with unit tests for its selection plus loading/error semantics.\n- Prefer structured Workspace launcher logs; the main process currently uses\n  `console` and does not have a universal pino sink.\n","category":"root","tokens":4731}]}