alva

name	alva
description	Use this skill when the user asks for financial data ("price of BTC", "P/E ratio of NVDA"), market analysis, stock or crypto research, quant strategies, backtesting ("backtest a momentum strategy"), tracking assets or portfolios, or help turning investing ideas into live playbooks, dashboards, and analytics on Alva. Powered by 250+ financial data sources across crypto, equities, macro, on-chain, and social data, along with cloud-side analytics and backtesting. Also use when the user asks about Alva platform capabilities.
metadata	{"author":"alva","version":"v1.22.1"}

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.

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 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.
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. 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. 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 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 when composing a pinned post-release author note.

Alva Knowledge (Required Reading)

Before designing, modifying, or evaluating any automation, read 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 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 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 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, 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; 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; 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.
/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 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, 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