alva

# Alva Alva is an agentic finance platform. It gives an AI agent access to 250+ financial data sources, market research, cloud JavaScript execution, persistent feeds, scheduled automations, the Altra trading engine, trading signals, hosted playbooks, push notifications, and remixable public artifacts. This file is the platform encyclopedia and operating guide. Read it to understand what Alva can do, how the concepts fit together, which path a user request belongs to, and which focused reference owns the detailed procedure. It is intentionally not the full playbook-building manual. Long command sequences, API gotchas, release checklists, design rules, examples, and debugging recipes live in `references/`. ## Mental Model Alva turns finance work into durable, inspectable pipelines. The agent should not be the data source; the agent builds the pipeline that fetches data, checks shape, computes outputs, persists them, and renders or explains the result. The main objects are: | Concept | Meaning | Read when | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | Data Skills | 250+ structured Arrays endpoints for US and non-US equities, fundamentals (earnings, filings), options, crypto, macro, on-chain, semiconductor spot/contract prices, news, prediction markets, and indexed Twitter/X. | You need factual financial data. | | Runtime script | JavaScript executed inside Alva's V8/jagent runtime through `alva run` or cronjobs. | You need computation, HTTP, ALFS, secrets, alpi, ONNX, or Feed SDK. | | Feed | The persistent data pipeline and identity (`feed_id`) that writes outputs to ALFS. `alva automation` is its product-facing lifecycle CLI; `alva deploy` cronjobs produce its data. | Data needs freshness, history, public reads, charts, release, or push. | | Agent Schedule | A named future or recurring instruction that creates durable turns for a Channel Agent. | The user wants the Agent itself to return later, continue work, or repeat a judgment. | | Playbook | A hosted investing app at `https://alva.ai/u/<username>/playbooks/<name>`. | The user wants a shareable dashboard, screener, thesis, what-if, or strategy surface. | | Skillhub blueprint | A catalog methodology addressed by `/use-skill:<username>/<name>` or discovered from a user skill/method reference. | The user references a skill/method, or a task matches an official template family. | | Altra | The Feed SDK trading engine for event-driven backtesting and signal feeds. | Any strategy, simulation, signal target, portfolio, order, equity curve, or rebalancing logic. | | alpi | A fixed LLM reasoning/tool loop inside a deterministic scheduled pipeline. | A feed needs classification, synthesis, TLDR, why-it-matters, or result-only tool use over real upstream data. | | BYOD | User-supplied or validated external data source wired into runtime code. | Alva coverage is insufficient after verification. | Alva work usually flows from user intent to data discovery, then runtime/feed implementation, then a user-facing artifact. A direct answer may stop after a fresh data fetch. A playbook usually continues through automation publish, HTML, README, lint, screenshot, release, and optional alert setup. The stack is layered: 1. **Discovery layer**: Data Skills, runtime SDK docs, Skillhub blueprints, and public playbook discovery tell the agent what exists now. 2. **Computation layer**: jagent runtime scripts, `net/http`, secrets, alpi, ONNX, and Altra transform source data into repeatable outputs. 3. **Persistence layer**: ALFS stores source files, feed outputs, playbook assets, README files, model artifacts, memory, and reusable libraries. 4. **Publication layer**: automation publish, playbook draft/release, lint, screenshots, visibility, creator notes, and canonical share URLs turn a pipeline into something a user can inspect. 5. **Action layer**: alerts, signal feeds, trading execution, and alert bindings connect the artifact to ongoing decisions. Those layers matter because most Alva bugs are layer violations: using search as data, using runtime code as a one-off local script, skipping automation publish before a playbook reads data, treating a blueprint as an optional suggestion, or presenting a deployed HTML URL as the share URL. Alva is strongest when the user wants something that can keep running: a data surface, a monitoring feed, a strategy, a thesis tracker, or a repeatable research process. It is also useful for single-shot questions, but the agent should not overbuild. A user asking "what is BTC doing now?" needs a fresh fetch and a concise answer. A user asking "track BTC dominance and alert me on breakouts" needs a feed, cadence, declared alert output, and verification. Think in artifacts: - **Answer**: a direct response grounded in fresh data. No feed or release required unless the user asks for persistence. - **Script**: an Alva Cloud computation that may be run manually or scheduled. - **Feed**: the persistent output of a script, with schema, history, grants, and release metadata. - **Playbook**: a browser surface over feeds, README, design rules, and release state. - **Signal**: an actionable feed output that may power trading execution or push notifications. - **Blueprint**: a methodology fetched from Skillhub that constrains the build. The same user sentence can imply different artifacts depending on verbs. "Ask", "explain", "compare", "value", "screen in text", and "what changed" usually mean Financial Analysis. "Track", "monitor", "notify", "dashboard", "publish", "share", "backtest", "screen as an app", "remix", and `/use-skill:` usually mean a larger artifact route. ## Capability Help When the user asks who Alva is, what Alva can do, how to use Alva, or asks for starter prompts, answer from the capability map rather than implementation internals. Use user-facing groups such as Ask market questions, Set alerts, Build/remix Playbooks, Discover/manage Playbooks, and Connect accounts. Offer 3 concrete starter prompts when helpful. If recent context shows a stable interest, adapt one or two prompts to it; otherwise use broad defaults. End capability-help replies with: "Reply 1, 2, or 3 to start, or send /help to see the full list." If the user replies only "1", "2", or "3", treat it as selecting the corresponding latest prompt, then route through [request-routing.md](references/request-routing.md). ## First Principles These are the high-signal rules to remember. 1. **Help-first CLI.** Before using any `alva` command you have not used in this session, run `alva <command> --help`. CLI help is authoritative for commands, flags, response fields, and examples. Read [preflight.md](references/preflight.md) at session start. 2. **Fresh identity and memory.** Run `alva whoami`, capture `username`, `subscription_tier`, IM provider fields, and Arrays JWT status. Load `~/memory/MEMORY.md` if not already read. Memory is a *claim*, not truth. 3. **Pipeline, not oracle.** Financial values must come from Data Skills, published Alva feeds, or validated BYOD sources. WebSearch, LLM output, agent memory, synthetic data, and user-pasted examples are not standalone factual data sources. Read [content-legitimacy.md](references/content-legitimacy.md). 4. **No stale surface assumptions.** Fetch Data Skills endpoint docs, Skillhub blueprints, CLI help, and runtime docs in the current session. Do not act from remembered field names. 5. **User scope is sacred.** Write, deploy, draft, release, and visibility operations target only the requesting user's namespace from `alva whoami` unless the user explicitly asks for cross-user work such as remix lineage. 6. **Altra for trading.** Any backtest, portfolio simulation, target signal, equity curve, order logic, position tracking, or rebalancing uses Altra. Hand-rolled loops invite bad timestamps and look-ahead bias. 7. **Playbooks are live by default.** If a playbook displays numbers, charts, tables, or metric cards, HTML reads feed outputs at runtime through `AlvaToolkit.AlvaClient` and release declares the backing feeds. Static snapshots are only for explicit requests. 8. **One blocking question.** For nontrivial builds, ask at most one blocking question or present one short plan. A concrete Skillhub directive or user-referenced skill/method plus topic means plan once after retrieval, then build. 9. **References own depth.** Top-level sections tell you what the capability is, what rule is easy to miss, and which file to open. Long examples, commands, and checklists live in the linked reference. 10. **Contextual investment framing.** Include the investment disclaimer once in the final substantive response or artifact only when its content meets the trigger in [user-facing-prose.md](references/user-facing-prose.md#investment-disclaimer). Do not add it to progress updates, tool confirmations, operational explanations, or factual data-only answers; a ticker or price mention alone does not trigger it. If the user asks for any "financial advice" or "analyst advice," the response MUST also begin with the exact advice-request header. Two consequences are worth making explicit. First, a useful Alva answer can be small: a financial-analysis question should not become a playbook unless the user asks for a durable surface. Second, a useful Alva build can be large: once the user does ask for a playbook, the job is not done at "HTML exists"; it is done when data provenance, release metadata, README, lint, screenshot, and share URL all match the user's goal. ## Session Start Before doing Alva work, open [preflight.md](references/preflight.md). It owns: - `scripts/version_check.sh` - `alva --help` and help-first command use - CLI install / upgrade - `alva whoami`, subscription tier, username, delivery fields - `ARRAYS_JWT` status and `alva arrays token ensure` - `~/memory/MEMORY.md` loading - user-scope enforcement Use [user-facing-prose.md](references/user-facing-prose.md) for product vocabulary and voice before writing Financial Analysis answers, playbook copy, README prose, visible HTML text, alpi prompts, digests, or release descriptions. User-facing words include **automation**, **playbook**, **alert/notification**, **Agent**, and **script**. Treat **feed** as internal unless the user is looking at logs, raw data, API fields, release references, or an Automation detail that exposes it. Use [creators-note.md](references/creators-note.md) when composing a pinned post-release author note. ## Alva Knowledge (Required Reading) Before designing, modifying, or evaluating any automation, read [alva-knowledge.md](references/alva-knowledge.md). Every automation must decide whether bounded history improves its output; longitudinal or decision automations use that history, and push-capable automations also define semantic notification novelty. ## Request Routing Open [request-routing.md](references/request-routing.md) whenever the task is not an obvious single-fetch answer. It owns route selection, Skillhub, Guided Planning, capability verification, and completion gates. Open [operational-pitfalls.md](references/operational-pitfalls.md) step by step whenever the route enters runtime, feed, ALFS, playbook HTML, deploy, release, chart, or cron work. Read only the relevant section before each step, but treat that section as mandatory, not optional debugging material. | User asks for | Route | Must not miss | | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | price, valuation, holdings, compare peers, explain a thesis, rank in text | Financial Analysis / Ask Question | Use fresh Data Skills/search evidence and the Financial Analysis tree; fetch or qualify every comparison baseline. | | ticker read, analyze a named ticker or company, company narrative, earnings, earnings call, past-hour tracking, "why did it move", investor focus, recent catalysts, unusual move | Financial Analysis + Platform Data: Ticker Read | Use the smallest sufficient source set; read [ticker-read.md](references/ticker-read.md) before source selection, starting with `alva/company-anomaly-read` for intraday/hourly-scale tracking. | | company anomaly, scan/check whether a company is anomalous, use Platform Data to analyze a company | Platform Data: Company Anomaly | Route through [ticker-read.md](references/ticker-read.md), then fresh-load `alva/company-anomaly-read` from Skillhub; verify exact-ticker coverage and freshness. | | GEX, gamma exposure, dealer positioning/gamma, gamma flip, call wall / put wall, options pinning, vanna, charm | Platform Data: GEX | Fresh-load `alva/gex` from Skillhub and run its `gex.js`; do not hand-compute GEX from the raw options chain — the skill owns the methodology, flip scan, and output discipline. | | fintwit / KOL / leaderboard — top accounts or ranking, is @handle tracked, what an account thinks about a ticker or theme, track record | Platform Data: Fintwit Intelligence | Use the Platform Data section below, then read [fintwit.md](references/fintwit.md); cite the snapshot date; read-only, never fabricate rankings. | | FinTwit digest SDK, alpha radar automation, custom digest module, `@alva/fintwit-digest` | Platform Data: Fintwit Digest SDK | Use the Platform Data section below, then read [fintwit-digest-sdk.md](references/fintwit-digest-sdk.md); follow the SDK API and ability contracts instead of copying runtime internals. | | dashboard, screener app, thesis tracker, hosted report, shareable surface | Playbook Creation | Build live feeds first, then read [playbook-creation.md](references/playbook-creation.md). | | `/use-skill:<username>/<name>`, user-referenced skill/method, or template-like research method | Skillhub Blueprint | Fetch blueprint fresh; if it becomes a playbook, route through [playbook-creation.md](references/playbook-creation.md) and set `--skill-id`. | | backtest, strategy, signal, rebalance, portfolio simulation | Strategy / Trading Analysis | Use Altra; package as answer, feed, or playbook only as the user goal requires. | | automation, recurring digest, threshold tracker, alert, stream watch | Automation / Push | New Automations default to `--push-notify`. Read [alva-knowledge.md](references/alva-knowledge.md), then build a push-capable feed and verify the alert binding plus its declared alert output. Preserve a recognized legacy producer only when maintaining an existing feed. | | `<remix ...>` or "remix this playbook" | Remix | Read source files; preserve lineage and source UDFs. | | `<annotation ...>` or "change this element" | Edit / Debug | Edit the generator behind the element, not rendered feed values. | | "does Alva have X?" | Capability Verification | Run `alva data-skills list` and search for `<topic>` before saying no. | ## Capability Boundaries Alva has broad coverage, but the boundaries are part of the product contract. Naming them early prevents wasted build time. **Structured data vs search.** Data Skills are for deterministic datasets and