alva

What this skill does

# 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 equities, crypto, macro, on-chain, 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 | A persistent data pipeline that writes time-series or grouped outputs to ALFS and can back playbooks or alerts. | Data needs freshness, history, public reads, charts, release, or push. |
| 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>`. | The user explicitly asks for one 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 feed release, HTML,
README, lint, screenshot, release, and optional push 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**: feed release, playbook draft/release, lint,
   screenshots, visibility, creator notes, and canonical share URLs turn a
   pipeline into something a user can inspect.
5. **Action layer**: push subscriptions, signal feeds, trading execution, and
   alerts 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 feed release
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, push sidecar, 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 rules are the high-signal foundation. If you only remember one section,
make it this one.

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`, delivery channel 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 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 `/use-skill:` directive plus
   topic means plan once, then build.
9. **References own depth.** To