Alva

What is Alva

Alva is an agentic finance platform. It provides unified access to 250+

financial data sources spanning crypto, equities, ETFs, macroeconomic

indicators, on-chain analytics, and social sentiment -- including spot and

futures OHLCV, funding rates, company fundamentals, price targets, insider and

senator trades, earnings estimates, CPI, GDP, Treasury rates, exchange flows,

DeFi metrics, news feeds, social media and more!

What Alva Skills Enables

The Alva skill connects any AI agent or IDE to the full Alva platform. With it

you can:

• Access financial data -- query any of Alva's 250+ data SDKs

programmatically, or bring your own data via HTTP API or direct upload.

• Run cloud-side analytics -- write JavaScript that executes on Alva Cloud

in a secure runtime. No local compute, no dependencies, no infrastructure to

manage.

• Build agentic playbooks -- create data pipelines, trading strategies, and

scheduled automations that run continuously on Alva Cloud.

• Deploy trading strategies -- backtest with the Altra trading engine and

run continuous live paper trading.

• Release and share -- turn your work into a hosted playbook web app at

https://alva.ai/u//playbooks/, and share it with

the world.

• Remix existing playbooks -- take any published playbook as a template,

read its feed scripts and HTML source, customize parameters/logic/UI, and

deploy as your own new playbook.

In short: turn your ideas into a forever-running finance agent that gets things

done for you.

Pre-flight

Run these checks on first use each session before doing anything else.

1. Version Check

bash "<this skill's directory>/scripts/version_check.sh"

• No output → up to date, proceed.
• Output present → display to user, apply the update, then proceed.

2. Alva CLI Setup

The alva CLI (@alva-ai/toolkit) is the required way to interact with the

Alva platform. It manages authentication, provides self-documenting help for

every command, and eliminates the need for manual curl/header management.

Check whether the CLI is already installed by running alva --help.

• If not installed, install it:

```bash

npm install -g @alva-ai/toolkit

```

• If already installed, upgrade to the latest version to ensure access to

the newest commands and fixes:

```bash

npm install -g @alva-ai/toolkit@latest

```

Then check authentication (see step 2a below).

Discover commands:

alva --help              # list all commands
alva <command> --help    # detailed usage, flags, and examples for any command

Use alva --help to discover usage — the help text includes all

flags, parameter types, and practical examples.

Third-party vendor secrets belong in Alva Secret Manager

(require("secret-manager")), not in the CLI config.

2a. Authentication Check

Run alva whoami. If it fails (no API key), run alva auth login to open

browser-based login, then re-run alva whoami to confirm.

3. User Profile

alva whoami

{"id":1, "subscription_tier":"free", "telegram_username":"alice_tg", "username":"alice"}

Session variables:

• username — for public URLs and ALFS paths.
• subscription_tier — "pro" or "free" (default). Determines release

flow (Step 7): pro can keep playbooks private.

• telegram_username — if set, recommend push-enabled feeds; if null,

guide user to connect Telegram first.

4. Arrays JWT Check

Data skills require ARRAYS_JWT. The _meta.arrays_jwt field in the

alva whoami output above shows its status — if it needs attention (missing,

renewal_needed: true, or absent), use alva arrays token to manage it

(status to inspect, ensure to provision or refresh).

5. Load Memory

If you have not read the user's memory in this conversation, read it now.

alva fs read --path '~/memory/MEMORY.md'

If the file exists, read each file listed in the index (at minimum user.md).

If '~/memory/' does not exist or is empty, skip — it will be seeded on next

sign-in.

Use the loaded memory to tailor your responses to the user's profile,

preferences, and investment style. See the Memory section below for

reading and writing rules.

Communication

Vocabulary — use the terms in language.md exactly.

Key terms: automation (not "cronjob"), feed, playbook, script.

Full definitions and "avoid" labels are in that file.

No ALFS paths, API payloads, automation IDs, raw function names, internal jargon,

or implementation details in user-facing responses. Say what it DOES, not how it

works. These details are operating instructions for you, not content for the

user.

Lead with the result, not the process. The first thing the user reads should be

what they got ("Your dashboard is live at …"), not what you did ("I deployed

3 feeds and wrote the HTML"). During multi-step builds, give a short status

update at each milestone so the user knows work is progressing.

Data provenance in direct answers. When a direct answer cites specific

financial figures, each number must either come from a fresh SDK/BYOD fetch

(attributed inline to its source) or be explicitly qualified as an estimate

that the user should verify with current sources.

Request Routing

Choose Template (mandatory when /use-template: is present)

If the user's message contains a /use-template: directive (e.g. /use-template:thesis, /use-template:screener), this step is mandatory and must run before Guided Planning and before any build work.

1. Resolve to skills/alva/templates//template.md (relative to this skill).
2. Read that template file via the filesystem — do not proceed from memory of a prior session. If the file does not exist, list the directories under templates/ and ask the user which to use.
3. Treat the template as the authoritative blueprint for layout, sections, widgets, data contracts, and cadence. Deviate only where the user explicitly overrides it.
4. In the plan you present during Guided Planning, state which template is being used and call out any intentional deviations.

Content arrangement. A template's default sections are a floor, not a ceiling. Lead with whatever carries the user's core question, proactively add sections the request demands, and cut or fold near-empty sections into neighbors rather than padding them.

Push-driven requests — if the user's primary outcome is a recurring push (digest, threshold tracker, stream watch, periodic alert), the ai-digest template is purpose-built for that shape and worth offering during Guided Planning. Push can also be added to any other playbook via Step 9 — the template is one good option, not a requirement.

No /use-template: directive → skip this step and proceed to Guided Planning normally.

Guided Planning

For all routes except Data Query, present a plan and get user approval

before building. Even seemingly clear requests ("build a BTC dashboard") have

real choices — which data, timeframe, widgets — that are cheaper to resolve

upfront than to rebuild.

1. Understand intent — Ask clarifying questions one at a time, prefer

multiple-choice. Focus on what's missing: asset, scope, output type, or

purpose. Skip this step if the request already specifies all of these.

1. Propose approaches — Offer 2-3 concrete options with trade-offs. Lead

with your recommendation.

1. Confirm the plan — List the specific feeds and widgets (5-8 lines, no

implementation details). Build only after approval.

If the user says "just do it" at any point, skip planning for the rest of the

session.

Completion Gate

For Dashboard/Playbook and Backtest/Strategy requests, the default goal

is to leave the user with a result they can actually use. In many cases that

means a released playbook and a published_url, but do not force that path if

the user only asked for code, analysis, debugging help, or an intermediate

artifact.

Before finishing, verify that the delivered result matches the user's actual

goal. When a shareable playbook was part of the task, verify:

• [ ] A playbook was released and a published_url was returned

Must Do After Completion Gate:

• [ ] Summarize the whole process and what is delivered to the user.

Content Legitimacy Rules

These rules are non-negotiable. Violations produce misleading content that

displays fabricated data as if it were real. They apply to **every response

that surfaces financial values to the user** — playbook builds, dashboards,

query-mode answers, remixes, edits, and follow-ups — regardless of whether the

session ends with a released playbook.

Core principle: the agent's role is to build the pipeline, not to **be

the data source**. Any quantitative value the user sees must trace back to an

Alva SDK module, a published Alva feed, or a BYOD HTTP source that is either

user-provided or explicitly validated and wired into the feed pipeline. Agent

knowledge, LLM output, WebSearch snippets, random/synthetic generators, and

user-pasted snapshots are not legitimate data sources — regardless of

whether they appear as HTML literals, feed-script literals, backfilled

history, or agent-authored opinion columns. When the SDK has no coverage for

the requested domain, report the gap and stop; do not manufacture

plausible-looking data.

Data Sourcing

1. **All quantitative data displayed in charts, tables, or metric cards MUST

originate from Alva feeds** (SDK modules or BYOD via require("net/http")).

Never hardcode data as inline JavaScript literals in playbook HTML.

1. Playbook HTML MUST fetch data at runtime from feed output paths:

```javascript

const resp = await fetch(

"$ALVA_ENDPOINT/api/v1/fs/read?path=/alva/home//feeds//v1/data//

/@last/",

);

const data = await resp.json();

renderChart(data);

```

Static content (labels, colors, layout config) is fine. Quantitative data is

not — it must flow through the feed pipeline.

1. **Verification claims and quoted tool outputs must reflect actual tool

calls.** Do not describe a screenshot you did not take ("the dashboard

looks good"). When citing a tool-returned value such as published_url,

feed_id, or an ALFS path, copy it verbatim from the response. The

user-facing share link is the canonical

https://alva.ai/u//playbooks/ URL; published_url

is the deployed HTML URL used for verification steps such as screenshots.

Do not present one as if it were the other. If you need a value, re-read

the tool response first.

Prohibited Data Sources for Charts, Tables, and Query Answers

1. WebSearch / WebFetch results must NOT be embedded as data. Web search is

only legitimate for: reading documentation, finding API endpoints for BYOD,

understanding user requirements. It may help you discover a legitimate BYOD

source, but discovered values themselves must never be quoted as the answer

or injected as static data literals in feed scripts or playbook HTML. This

rule applies even when Alva API auth fails — in that case, report the

failure and stop; do NOT substitute a web-sourced value.

1. LLM / ADK output must NOT be presented as factual sourced data. ADK is

for reasoning, classification, summarization, and synthesis of real data — not

for generating numbers, statistics, events, or reports that claim to be from

real sources. If ADK produces quantitative output, it must be clearly labeled

as "AI-generated analysis".

1. Agent training knowledge must NOT fill data gaps. If an SDK does not have

the requested data type, report the gap as a blocker. Do not invent data from

your own knowledge to fill the hole.

Feed Scope Isolation

Do not reference other feeds or other playbooks' feeds. When building a

playbook, only read from feeds created for this playbook in the current

session.

Reference an existing feed only when the user explicitly asks for it (e.g.

"reuse my btc-ema feed", "pull data from @alice/macro-dashboard"). Otherwise,

build the playbook's own feeds from scratch so its data lineage is

self-contained and the playbook remains portable.

Qualitative analysis (ratings, theses, outlook text) is not data and must not

appear as feed output columns or "data" fields in HTML tables. If the user

asks for a rating, either compute it from SDK fundamentals with the formula

shown, or place it in a clearly labelled "AI analysis" section separated from

data-driven metrics.

SDK Coverage Gaps

1. When an SDK partition lacks the requested data type, reduce scope:
• Omit the missing data section from the playbook and note the gap

(e.g. "ECB, BOJ, BOE rates — data source not yet available").

• If the user has provided a specific data source URL, use BYOD

(require("net/http")) to fetch from it.

• Do NOT hardcode point-in-time values in HTML — they become stale

immediately and violate content legitimacy rules.

• Do NOT fabricate events or fill gaps from agent knowledge.

1. **When >20% of requested symbols fail SDK lookup, report a data-quality

blocker.** Do not silently substitute with estimated or fabricated values

marked live: false.

Release Gate: --feeds Is a Declaration, Not a Shortcut

alva release playbook --feeds '[]' is only valid when the released HTML

renders zero quantitative values at runtime (landing pages, UI-only demos).

If the HTML shows any numbers, charts, tables, or metric cards, the release

MUST reference deployed feeds in --feeds and the HTML MUST fetch() them

at runtime. alva run is a test run of a feed, not a substitute for

deploying one — if you used alva run to source data, deploy that same

logic as a feed and reference it.

Thematic Ticker Curation

When building sector or thematic dashboards with curated ticker lists:

1. Do NOT rely on agent knowledge for ticker-to-sector mapping.
2. After assembling the list, cross-check each ticker's sector using an SDK

call (e.g. getStockCompanyDetail) to verify it belongs to the intended

segment.

1. Remove mismatches before building the feed. A single wrong ticker (e.g. a

cybersecurity company in a battery segment) can distort the entire analysis.

Description and Provenance Accuracy

1. **Playbook descriptions and methodology sections must only list data sources

that were actually called successfully.** Do not claim "Brave Search",

"ClinicalTrials.gov", or any other source unless the feed script actually

fetches from it at runtime.

1. Update frequency claims must match actual deployment. If cronjob

deployment failed, do not claim "updated every N hours" in the playbook

description. Either fix the cronjob or remove the claim.

Narrative Voice Rules

All user-facing prose the agent writes — playbook description and

display_name, hand-written HTML copy (hero text, intro cards, methodology

modal body, chart footnotes, rationale paragraphs), and any ADK system

prompts that produce narrative (TLDRs, digests, why-it-matters, delta

bodies, push-line headlines) — must follow

narrative-voice.md. Read that file before

writing or generating any user-facing prose.

The rules ban a specific list of AI-tell tokens and shapes (significance

inflation, negative parallelism, rule-of-three, generic closers, em-dash

overuse) and ship as a copy-paste system-prompt block with embedded

few-shots for ADK calls. Pure structured fields (numbers, tickers, dates,

enum labels, button labels) are exempt.

Capabilities & Common Workflows

1. ALFS (Alva FileSystem)

The foundation of the platform. ALFS is a cloud filesystem with per-user

isolation. Every user has a private home directory; all paths are private by

default and only accessible by the owning user. Public read access can be

explicitly granted on specific paths via grant. Scripts, data feeds, playbook

assets, and shared libraries all live on ALFS.

Key operations: read, write, mkdir, stat, readdir, remove, rename, copy,

symlink, chmod, grant, revoke.

In shell and documentation, wrap ALFS path arguments in single quotes (e.g.

'~/feeds/...', '/alva/home/...') so they are not confused with paths on your

local machine. See Filesystem.

2. JS Runtime

Run JavaScript on Alva Cloud in a sandboxed V8 isolate. Code executed via

alva run runs entirely on Alva's servers -- it cannot access

the host machine's filesystem, environment variables, or processes. The runtime

has access to ALFS, data skills via HTTP, runtime libraries, LLM access, and

the Feed SDK.

3. Data Skills

Financial data APIs across 16+ domains, served by the Arrays backend

($ARRAYS_ENDPOINT, defaults to https://data-tools.prd.space.id). To find

the right API for a task, use the alva skills CLI (public, no auth):

1. Discover available data skills: alva skills list — returns all data

skills with their names and descriptions. Use this to find the skill that

matches your data need.

1. Fetch the skill summary: alva skills summary --name — returns

the endpoints table for that domain.

1. Fetch endpoint detail: alva skills endpoint --name --file

— use the File value from the summary endpoints table (e.g. rates,

macro-index-historical, earnings-calendar) to get full parameters,

response fields, and examples. The File column is the endpoint slug;

the Path column is the REST URL path and is NOT accepted here (e.g. for

treasury rates, use --file rates, not --file macro/treasury-rates).

1. Call Arrays data endpoints with Authorization: Bearer .

In runtime code, load the token via secret.loadPlaintext('ARRAYS_JWT').

The token is verified during preflight (see Arrays JWT Check);

if a call returns 401, re-run alva arrays token ensure. Do not use X-API-Key header.

Coverage Overview

Data skills span spot and derivatives markets across stocks, ETFs, options,

and crypto; equity fundamentals, estimates, events, and ownership flows;

on-chain metrics and exchange flows; macro and economic indicators; news;

and prediction markets. Run alva skills list for the live catalog.

Data skill doc lookup is mandatory. Always fetch the endpoint detail before

writing code that calls it. Do not guess paths, parameter names, or response

shapes from memory. The doc lookup ensures you use the correct endpoint and

handle the actual response format.

Enforcement: Before any Arrays data HTTP call or alva run that hits one,

you MUST have completed alva skills endpoint --name --file for

that endpoint in this session (passing the File column value, not the Path). If the call fails with an unexpected shape,

re-fetch the endpoint detail rather than guessing.

Runtime Libraries

Built-in modules that run inside the jagent V8 runtime via require(). These

are not data APIs — they are pure computation and utility libraries

available in every script execution.

To discover available modules and their documentation:

• alva sdk partitions — list all runtime module groups
• alva sdk partition-summary --partition — one-line summaries per group
• alva sdk doc --name — full doc for a specific runtime module

Pick a module group → partition-summary to see modules → sdk doc for full

documentation.

For unstructured content — news articles, social discussions, videos, podcasts

— see Content Search below.

You can also bring your own data by uploading files to ALFS or fetching from

external HTTP APIs within the runtime.

Content Search

Search across Twitter/X, news, Reddit, YouTube, podcasts, and general web.

Use whenever the playbook needs content beyond structured data SDKs — from

targeted queries ("what are people saying about NVDA earnings") to broad

discovery ("trending crypto discussions this week"), including social

discussions, market narratives, news coverage, sentiment, analyst commentary,

and community reactions.

Content search modules live in the unified_search runtime-library

partition. Discover them via the same partition API as the other runtime

libraries (GET /api/v1/sdk/partitions/unified_search/summary → module

listing; GET /api/v1/sdk/doc?name=... → full per-module documentation).

See search.md for per-source SDK usage,

enrichment patterns, and gotchas.

4. Altra (Alva Trading Engine)

A feed-based event-driven backtesting engine for quantitative trading

strategies. A trading strategy IS a feed: all output data (targets, portfolio,

orders, equity, metrics) lives under a single feed's ALFS path. Altra supports

historical backtesting and continuous live paper trading, with custom

indicators, portfolio simulation, and performance analytics.

5. Deploy on Alva Cloud

Once your data analytics scripts and feeds are ready, deploy them as scheduled

cronjobs on Alva Cloud. They run continuously on your chosen schedule (e.g.

every hour, every day). All data is private by default; grant public access to

specific paths so anyone -- or any playbook page -- can read the data.

User scope enforcement: All write, deploy, and release operations MUST

target only the requesting user's namespace. Before any fs/write,

draft/playbook, or release/playbook call, verify the target path and

username match the authenticated user (from alva whoami). If you have

access to multiple API keys (e.g. from prior sessions), identify the requesting

user and scope all operations to that user only. Do NOT write to or release

playbooks under other users' namespaces unless the request explicitly asks for

cross-user operations (e.g. remix with lineage).

Signal feeds require Altra: Any feed that produces signal/targets or

signal/alerts output MUST use FeedAltra. Manual signal construction

(building target records without Altra) bypasses bar alignment, portfolio

simulation, and look-ahead bias prevention. Use FeedAltra even for simple

signal logic — it ensures correct timestamps and prevents forward-looking bugs.

This applies to ALL feed types that produce signal output — including

monitoring feeds, alert feeds, and notification feeds, not just backtest

strategies. If the feed pushes signals to Telegram or triggers alerts, it

MUST use FeedAltra.

Push notifications for followers: Feeds can produce actionable,

subscription-worthy signals that get pushed to playbook followers via Telegram.

To make a feed push-capable:

1. Add a signal/targets output to the feed script (see

feed-sdk.md Pattern D) and write signal records

using the Altra target format ({date, instruction, meta}), where

meta.reason is the human-readable message followers will see.

1. Set --push-notify in the alva deploy create command, or

update the existing cronjob with alva deploy update --id ID --push-notify.

The platform reads /data/signal/targets after each successful

execution and pushes the signal content to all eligible followers.

AlvaAsk + owner notifications: Feeds can use @alva/alvaask to call

Alva's agent and push the result to the feed owner — useful for scheduled

reports, heartbeat monitoring, and proactive alerts. Write to

notify/message (see feed-sdk.md Pattern E):

const result = ask("Brief crypto market update with key levels.");
await ctx.self.ts("notify", "message").append([{
  date: Date.now(),
  title: "Daily Briefing",
  text: result.text,
}]);

The platform reads /data/notify/message/@last/1 and pushes title + text

to the owner on all connected channels (Telegram, Discord, Web). No playbook

or followers required.

Two-step deploy is mandatory for Pattern E. --push-notify alone is not

enough; without alva release feed the platform fires the push but the body

arrives empty. Always pair them:

alva deploy create --name <feed> --path '~/feeds/<feed>/v1/src/index.js' \
  --cron "<expr>" --push-notify
alva release feed --name <feed> --version 1.0.0 \
  --cronjob-id <ID_FROM_DEPLOY> --description "<one-sentence purpose>"

Pattern D (followers, signal/targets) needs only --push-notify, but it

also needs at least one playbook follower — a subscribed playbook with no

followers pushes to nobody.

See Step 9 below for the full post-release subscription flow.

6. Build the Playbook Web App

After your data pipelines are deployed and producing data, build the playbook's

web interface. Create HTML5 pages with Alva Design System that read from Alva's

data gateway and visualize the results. Follow the Alva Design System for

styling, layout, and component guidelines. Unless the user explicitly asks for a

static snapshot, default to a live playbook.

Data fetching requirement: Apply the

Content Legitimacy Rules when building the UI.

All quantitative data in charts, tables, or metric cards must come from feed

outputs read at runtime (no inline literals for data).

7. Release

Common steps (all users)

1. Write HTML to ALFS: alva fs write --path '~/playbooks/{name}/index.html' --file ./index.html --mkdir-parents
2. Create playbook draft: alva release playbook-draft — creates DB

records, writes draft files and playbook.json to ALFS automatically.

This request must include both the URL-safe name and the human-readable

display_name. Use [subject/theme] [analysis angle/strategy logic], put

the subject/theme first, and keep it within 40 characters. Avoid personal

markers such as My, Test, or V2, and generic-only titles such as

Stock Dashboard or Trading Bot.

Trading symbols: If the playbook involves specific trading assets,

include "trading_symbols" in the request — an array of base asset

tickers (e.g. ["BTC", "ETH"], ["NVDA", "AAPL"]). The backend

resolves each symbol to a full trading pair object and stores the result

in the playbook metadata. Max 50 symbols per request. Unknown symbols

are silently skipped.

1. Screenshot: Take a screenshot to verify the released playbook renders

correctly from the deployed published URL (for example,

https://.playbook.alva.ai//v1.0.0/index.html):

```bash

alva screenshot --url --out /tmp/screenshot.png

```

The CLI handles authentication automatically. See

screenshot.md for full parameter details.

Pro users (subscription_tier = "pro")

1. Show draft link: Output the playbook URL —

https://alva.ai/u//playbooks/. The draft is

accessible only to the creator.

1. Ask: "Your playbook is ready. Would you like to publish it publicly, or

keep it private for now?"

• Publish → call alva release playbook → output the public URL.
• Keep private → done. Remind the user that only they can access the

draft URL.

Free users (subscription_tier = "free")

1. Publish directly: Call alva release playbook — free playbooks

are always public. Output the public URL:

https://alva.ai/u//playbooks/

1. Upsell only on friction: Do not proactively suggest upgrading.

But when the user's experience is degraded because of free-tier

limitations — wanting private playbooks, hitting the cronjob cap,

resource limits, or any other pro-gated feature — acknowledge the

limitation and offer the upgrade path:

"This feature is available on the Pro plan. You can upgrade at

to [specific benefit, e.g. keep playbooks

private / deploy more cronjobs / ...]."

Use the playbook name and the username from alva whoami to construct the

canonical share URL. Use published_url from the release response for

verification steps such as screenshots; do not present it as the share link.

Pre-Release Validation

Before calling alva release playbook, verify all of the following:

1. Deployment coverage: Every feed the released playbook reads at runtime

must have had a successful alva deploy create AND its feed_id must

appear in --feeds. alva run is a test step, not a deployment — a

run-tested but undeployed feed has no data at its public @last path and

the HTML will fail to read it.

1. Cronjobs are active: All feeds referenced by the playbook have

successfully deployed cronjobs.

1. HTML fetches from feeds: The playbook HTML reads quantitative data from

feed output paths at runtime (not from inline literals), consistent with the

Content Legitimacy Rules.

1. Data is fresh: Read the latest data point from each referenced feed

(via @last/1) and check its timestamp. If the latest timestamp is older

than 2x the cron interval, warn the user that the playbook will display

stale data.

1. Description is accurate: Update frequency claims match actual cronjob

status. Data source claims match actual SDK/BYOD calls in the feed script.

1. Target user is correct: The playbook is being released under the

requesting user's namespace (see user scope enforcement above).

8. Remix (Create from Existing Playbook)

Users can remix any published playbook to create a customized version. The Remix

prompt uses the format @{owner}/{name} to identify the source playbook — e.g.

Playbook(@alice/btc-momentum). The agent reads the source playbook's feed

scripts (strategy logic) and HTML (dashboard UI), customizes them per the user's

request, and deploys a new playbook under their own namespace. If the user does

not specify what to change, the agent should ask before proceeding.

See remix-workflow.md for the full step-by-step

guide. alva remix commands are exclusively for lineage registration — to

read any playbook's files, use alva fs read.

9. Post-release push notification flow

After a playbook is released or kept as draft (Step 7 complete), proactively

evaluate whether any deployed feeds produce push-worthy content. Do not wait for

the user to ask.

Identify push-worthy feeds

Scan the feeds backing this playbook and classify each:

• Push-worthy (recommend): price signals, crossover/breakout alerts,

trading instructions, anomaly detection, periodic research summaries —

anything actionable and time-sensitive.

• Not push-worthy (skip): static fundamentals, historical snapshots,

low-frequency reference data.

If no feed qualifies, skip this flow entirely.

Check Telegram binding

Read telegram_username from the session (Pre-flight Step 3). If null, tell

the user:

"To receive push notifications, connect your Telegram at

. After connecting, I can set up push alerts for

[specific feed description]." Then skip the rest of this flow.

Recommend specific feeds

Present a concrete recommendation, not a generic "want push?":

> "This playbook's BTC EMA crossover signal feed produces actionable

> alerts when the trend flips. Want to enable Telegram push notifications

> for it?"

• User says yes → configure end-to-end (see "Configure and verify" below).

Do not stop after toggling the flag.

• User says no → accept and move on. Do not ask again.
• User requests push for a different feed → honor their choice.

If the feed already has signal/targets and push_notify: true, skip — it's

already configured.

Configure and verify

A push is "set up" only after every step below succeeds. Stopping early is

the most common cause of "configured but nothing arrives" — do not skip

verification.

1. Add signal/targets output to the feed script (see

feed-sdk.md Pattern D). meta.reason is the

text followers receive.

1. Enable the flag on the cronjob: alva deploy update --id --push-notify.
2. Verify a real run produced push content: trigger a run (or wait for

the next cron fire) and read @last/1 of signal/targets. Confirm the

record is fresh and meta.reason is non-empty.

1. Confirm to the user with the specifics: which feed, what the next

push will say, when it will fire.

If Step 3 returns no record or an empty body, **do not claim push is set

up** — diagnose (missing output write, wrong path, run failure) and fix

before reporting success.

Detailed sub-documents (read these for in-depth reference):

CLI Reference

Important: Always read the reference docs before making CLI calls. Use

alva --help for quick flag/usage reminders.

Reference docs:

• User Info — alva whoami
• Secrets — alva secrets
• Filesystem — alva fs
• Run — alva run
• Deploy Cronjob — alva deploy
• Release — alva release
• Remix — alva remix
• SDK — alva sdk
• Playbook Comments — alva comments
• Screenshot — alva screenshot
• Trading — alva trading
• Notifications — alva notifications
• Push Subscriptions — alva push-subscriptions
• Error Responses

Runtime Modules Quick Reference

Scripts executed via alva run run in a sandboxed V8 isolate on Alva's

servers -- they cannot access the host machine's filesystem, environment

variables, or shell. Host-agent permissions still apply. See

jagent-runtime.md for full details.

Runtime libraries: Built-in computation modules available via require()

(e.g. @alva/technical-indicators/rsi:v1.0.0). Version suffix is optional

(defaults to v1.0.0). To discover function signatures, use

alva sdk doc --name "...". Module groups: feed_widgets,

technical_indicator_calculation_helpers, unified_search.

Data APIs: Financial data (crypto, stock, macro, ETF) is fetched via HTTP

from the Arrays backend — see the Data Skills section. Load

ARRAYS_JWT via secret.loadPlaintext('ARRAYS_JWT') and call Arrays endpoints

with Authorization: Bearer .

Secret Manager: use const secret = require("secret-manager"); then

secret.loadPlaintext("OPENAI_API_KEY"). This returns a string when present or

null when the current user has not uploaded that secret.

Key constraints: No top-level await (wrap script in

(async () => { ... })();). No Node.js builtins (fs, path, http). Module

exports are frozen.

Feed SDK Quick Reference

See feed-sdk.md for full details.

Feeds are persistent data pipelines that store time series data, readable via

filesystem paths.

const { Feed, feedPath, makeDoc, num } = require("@alva/feed");
const http = require("net/http");
const secret = require("secret-manager");
const { indicators } = require("@alva/algorithm");

const ARRAYS_JWT = secret.loadPlaintext("ARRAYS_JWT");
const ARRAYS_BASE = "https://data-tools.prd.space.id";

const feed = new Feed({ path: feedPath("btc-ema") });

feed.def("metrics", {
  prices: makeDoc("BTC Prices", "Close + EMA10", [num("close"), num("ema10")]),
});

(async () => {
  await feed.run(async (ctx) => {
    const raw = await ctx.kv.load("lastDate");
    const lastDateMs = raw ? Number(raw) : 0;

    const now = Math.floor(Date.now() / 1000);
    const start =
      lastDateMs > 0 ? Math.floor(lastDateMs / 1000) : now - 30 * 86400;

    const resp = await http.fetch(
      `${ARRAYS_BASE}/api/v1/crypto/ohlcv?symbol=BTCUSDT&start_time=${start}&end_time=${now}&interval=1h&limit=10000`,
      { headers: { Authorization: "Bearer " + ARRAYS_JWT } }
    );
    const bars = JSON.parse(await resp.text()).data.slice().reverse();
    const closes = bars.map((b) => b.close);
    const ema10 = indicators.ema(closes, { period: 10 });

    const records = bars
      .map((b, i) => ({
        date: b.date,
        close: b.close,
        ema10: ema10[i] || null,
      }))
      .filter((r) => r.date > lastDateMs);

    if (records.length > 0) {
      await ctx.self.ts("metrics", "prices").append(records);
      await ctx.kv.put("lastDate", String(records[records.length - 1].date));
    }
  });
})();

Feed output is readable at (ALFS — quote in CLI):

'~/feeds/btc-ema/v1/data/metrics/prices/@last/100'

Data Modeling Patterns

All data produced by a feed should use feed.def() + ctx.self.ts().append().

Do not use alfs.writeFile() for feed output data.

Pattern A -- Snapshot (latest-wins): For data that represents current state

(company detail, ratings, price target consensus). Use start-of-day as the date

so re-runs overwrite.

const today = new Date();
today.setHours(0, 0, 0, 0);
await ctx.self
  .ts("info", "company")
  .append([
    { date: today.getTime(), name: company.name, sector: company.sector },
  ]);

Read @last/1 for current snapshot, @last/30 for 30-day history.

Pattern B -- Event log: For timestamped events (insider trades, news,

senator trades). Each event uses its natural date. Same-date records are

auto-grouped.

const records = trades.map((t) => ({
  date: new Date(t.transactionDate).getTime(),
  name: t.name,
  type: t.type,
  shares: t.shares,
}));
await ctx.self.ts("activity", "insiderTrades").append(records);

Pattern C -- Tabular (versioned batch): For data where the whole set

refreshes each run (top holders, EPS estimates). Stamp all records with the same

run timestamp; same-date grouping stores them as a batch.

const now = Date.now();
const records = holdings.map((h, i) => ({
  date: now,
  rank: i + 1,
  name: h.name,
  marketValue: h.value,
}));
await ctx.self.ts("research", "institutions").append(records);

See feed-sdk.md for detailed data modeling examples

and deduplication behavior.

Deploying Feeds

Every feed follows a 6-step lifecycle including every newly created feed or re-created feed:

1. Write -- define schema + incremental logic with ctx.kv
2. Upload — write script to '~/feeds//v1/src/index.js'
3. Test — alva run --entry-path '~/feeds//v1/src/index.js' to verify output.

For SDK modules you haven't used before in this session, first run a

shape-check snippet to verify response structure:

```js

const r = await mod.someFunction({ symbol: "AAPL" });

console.log(JSON.stringify(r).slice(0, 500));

```

Verify the actual response nesting (e.g. {success, response: {rates:[]}}

vs flat array) matches your feed script's parsing logic before proceeding.

alva run is a test step — it does NOT write to the production @last

path. Never skip alva deploy below on the assumption that the run

"already produced the data".

1. Grant -- make feed data publicly readable:

```bash

alva fs grant --path '~/feeds/' --subject "special:user:*" --permission read

```

Grant on the feed root path (not on data/). Subject format:

special:user:* (public), special:user:+ (authenticated only), user:

(specific user).

1. Deploy -- alva deploy create for scheduled execution
2. Release -- alva release feed to register the feed in the

database (requires the cronjob_id from the deploy step)

Pre-Release Verification

Before calling alva release feed or alva release playbook,

verify these prerequisites:

1. Grant check — confirm special:user:* read permission exists on the

feed path. If missing, run the grant step now.

1. Data check — fetch the feed data path without authentication and

confirm HTTP 200 (not 403).

1. HTML check (playbook only) — confirm the playbook HTML file exists in

ALFS at the expected path.

If the build was interrupted and resumed, re-run this checklist from the top.

Do not assume prior steps completed successfully.

See deployment.md for the full deployment guide and

API reference.

Error Transparency

When SDK modules fail or are unavailable, you MUST be transparent with the user.

Do not silently fall back to inferior data sources.

Pro / Subscription-Gated SDKs

When an SDK module returns a Pro-only or subscription error:

1. Inform the user which module is unavailable and why (subscription tier).
2. Assess scope impact — determine whether the gated module is the sole

data source for the playbook, or one of several.

• Partial dependency (other free-tier modules can still power most of

the playbook): proceed with a reduced-scope build. Omit the gated

section and note it in the playbook (e.g. "Congressional trading data

requires Pro — section omitted"). Deliver what you can.

• Full dependency (the entire playbook hinges on this module): tell

the user specifically: *"This data requires a Pro subscription. You can

upgrade, or provide a custom data source URL and I'll wire it up via

BYOD."* Do NOT leave an open-ended question; give exactly these two

actionable options.

1. Never stop with zero output. If you can build any useful subset of

the requested playbook with free-tier modules, do so.

1. Never silently substitute with LLM-fabricated data.

Coverage Limitations

When the user requests data outside Alva's supported asset classes (e.g. forex

pairs, which are not in the Data Skills catalog), state the limitation upfront

rather than discovering it through failed searches. Suggest BYOD alternatives

if a public API exists.

Debugging Feeds

Resetting Feed Data (development only)

During development, use the CLI to clear stale or incorrect data. **Do not use

this in production.**

# Clear a specific time series output
alva fs remove --path '~/feeds/my-feed/v1/data/market/ohlcv' --recursive

# Clear an entire group (all outputs under "market")
alva fs remove --path '~/feeds/my-feed/v1/data/market' --recursive

# Full reset: clear ALL data + KV state (removes the data mount, re-created on next run)
alva fs remove --path '~/feeds/my-feed/v1/data' --recursive

Inline Debug Snippets

Test data skill response shapes before building a full feed:

alva run --code '(async()=>{const http=require("net/http");const secret=require("secret-manager");const jwt=secret.loadPlaintext("ARRAYS_JWT");const r=await http.fetch("https://data-tools.prd.space.id/api/v1/crypto/ohlcv?symbol=BTCUSDT&start_time=1735689600&end_time=1735776000&interval=1h&limit=5",{headers:{Authorization:"Bearer "+jwt}});console.log(JSON.stringify(JSON.parse(await r.text()).data[0]));})();'

Memory

You have a persistent, file-based memory system on ALFS at '~/memory/'. This

directory is created automatically when the user's account is provisioned. Use

it to accumulate knowledge about the user across conversations — their identity,

preferences, investment style, and any context that would be useful in future

sessions.

Memory files are user-visible and editable. The user can read, modify, or

delete any memory file through the Alva dashboard or ALFS API. Write memories

as if the user will read them.

Storage layout

ALFS paths — use single quotes in the shell (example: '~/memory/MEMORY.md').

~/memory/
├── MEMORY.md     # Concise index — read at the start of every conversation
└── user.md       # User profile, preferences, expertise, investment style

MEMORY.md is the entrypoint. Read it at the start of every conversation to

discover what's stored. Keep it concise — under 200 lines. Each entry is one

line linking to a topic file:

- [user.md](user.md) — User identity, investment style, knowledge level
- [market-views.md](market-views.md) — Current macro thesis, conviction trades

Topic files (like user.md) hold the actual content. They are read on demand

when relevant to the user's request.

user.md — Who is this user

Persistent facts about the user. Update when you learn something new.

# User Profile

> Auto-maintained by Alva Agent. You can edit directly.

## Identity

- Name:
- Role: <!-- e.g. Independent Trader, PM at Fund, Research Analyst, Student -->
- Timezone:
- Language:

## Investment Style

- Markets: <!-- e.g. US Equities, Crypto, Macro, Commodities -->
- Strategy: <!-- e.g. Momentum, Mean Reversion, Fundamental, Event-driven -->
- Holding period: <!-- Intraday / Swing / Position / Long-term -->
- Risk tolerance: <!-- Conservative / Moderate / Aggressive -->
- Watching:

## Knowledge

- Level: <!-- Beginner / Intermediate / Advanced / Professional -->
- Strong: <!-- e.g. Technical analysis, On-chain, Macro -->
- Learning:
- External tools: <!-- e.g. TradingView, Bloomberg, Dune -->

## Preferences

- Communication style: <!-- e.g. terse / detailed / visual -->
- Notification channel:

When to update: User shares personal info, corrects a preference, reveals

expertise level, states investment convictions, or you learn something that

changes how you should work with them.

Additional topic files

Create new files in '~/memory/' for knowledge that doesn't fit in user.md —

market convictions, strategy assumptions, portfolio rules. Add a pointer to

MEMORY.md for each new file.

What NOT to save

• Ephemeral conversation details (current debugging session, temp state)
• Things derivable from code or ALFS files
• Raw data or large outputs (store on ALFS as feed data, not in memory)
• Anything already in the Alva skill docs
• Market data that changes every minute (save your interpretation, not the

data)

Writing rules

1. Read '~/memory/MEMORY.md' first — check if a relevant file already exists
2. Update existing file if the topic matches. Don't create duplicates
3. Create new file only if no existing file covers the topic
4. Update MEMORY.md — add a one-line entry for each new file
5. Keep MEMORY.md as a concise index — one line per file, under 120 characters
6. Every write → confirm in chat: 📌 Memory updated: {one-sentence summary}

Reading rules

• Every conversation start: Read '~/memory/MEMORY.md' via ALFS. Then read

user.md and any topic files relevant to the user's request.

• User references prior work: "that strategy from last time" / "the rules

we discussed" → read the relevant memory file.

• User explicitly asks: "do you remember" / "check my profile" → you

must read.

• User says to ignore memory: Proceed as if '~/memory/' is empty.

Memory is a claim, not truth

Memory records what was true when the memory was written. Before acting on

a memory:

• Memory names a feed or playbook → verify it exists on ALFS before

referencing it.

• Memory names a cronjob or parameter → verify current state before

recommending changes.

• Memory records a market view → treat as the user's last-known position,

not current fact.

• Memory records user preferences → apply directly (these are stable).

If a memory conflicts with what the user just told you, **trust what the user

says now** — and update the memory.

Secret Manager

Use Alva Secret Manager whenever a playbook or runtime script needs a

third-party credential such as an LLM API key, search token, exchange key, or

webhook secret.

• Preferred upload path: ask the user to add or edit the secret in the web

UI at . Assume this page is available.

• Do not ask the user to paste sensitive third-party secrets into chat when

the web upload flow is feasible.

• Do not hardcode secrets in source code, ALFS files, .env, shell

snippets, or released playbook assets.

• Runtime access: load secrets inside Alva Cloud code with

require("secret-manager").loadPlaintext("NAME").

• loadPlaintext(name) returns the plaintext string when present, or null

when the secret is missing for the current user.

• If a required secret is missing, stop and tell the user exactly which secret

name to upload at .

• For agent-managed setup, inspection, or cleanup, authenticated CRUD endpoints

are available via alva secrets.

Read secret-manager.md whenever the task

involves uploading, naming, rotating, listing, or using third-party secrets.

Altra Trading Engine Quick Reference

Always use Altra for backtesting. Altra handles bar.endTime timestamps,

data alignment, and portfolio simulation automatically. Do not manually loop

over SDK data (e.g. getCryptoKline) to evaluate trading conditions — this

leads to incorrect timestamps and look-ahead bias. Use Altra for all

strategies regardless of complexity; it supports any interval ("1min" to

"1w") and any combination of OHLCV + external data via registerRawData.

**After a successful backtest, you should package the results in a form the user

can use.** That may be a playbook, a dashboard, or a concise analytical summary,

depending on the request. A backtest that only prints raw console output is

usually incomplete — see

Request Routing above.

See altra-trading.md for full details.

const { FeedAltraModule } = require("@alva/feed");
const { FeedAltra, e, Amount } = FeedAltraModule;
const { AltraModule } = require("@alva/graph");
const { createArraysOhlcvProvider } = AltraModule;
const secret = require("secret-manager");

const ARRAYS_JWT = secret.loadPlaintext("ARRAYS_JWT");
const ohlcvProvider = createArraysOhlcvProvider({ jwt: ARRAYS_JWT });

const altra = new FeedAltra(
  {
    path: "~/feeds/my-strategy/v1",
    startDate: Date.parse("2025-01-01T00:00:00Z"),
    portfolioOptions: { initialCash: 1_000_000 },
    simOptions: { simTick: "1min", feeRate: 0.001 },
    perfOptions: { timezone: "UTC", marketType: "crypto" },
  },
  ohlcvProvider,
);

const dg = altra.getDataGraph();
dg.registerOhlcv("BINANCE_SPOT_BTC_USDT", "1d"); // any interval: "1min" to "1w"
dg.registerFeature({ name: "rsi" /* ... */ });

altra.setStrategy(strategyFn, {
  trigger: { type: "events", expr: e.ohlcv("BINANCE_SPOT_BTC_USDT", "1d") },
  inputConfig: {
    ohlcvs: [{ id: { pair: "BINANCE_SPOT_BTC_USDT", interval: "1d" } }],
    features: [{ id: "rsi" }],
  },
  initialState: {},
});

(async () => {
  await altra.run(Date.now());
})();

ADK (Agent Development Kit) Quick Reference

See adk.md for the full API, tool-calling patterns, memory

patterns, and implementation examples.

ADK is a universal agent development kit that runs inside the Jagent V8 runtime.

Use it to build LLM-powered agents that can reason over tasks, call tools,

gather context from multiple sources, and return structured outputs.

It is best suited for workflows where the "thinking" step cannot be expressed as

pure deterministic code, such as research synthesis, document analysis,

classification, and summarization over real upstream data.

When to Use ADK

Use ADK when you need an agent to:

• Fetch real data through tools, APIs, SDKs, or files
• Reason over multiple inputs before producing an answer
• Synthesize findings into structured notes, summaries, or classifications
• Power periodic research or analysis workflows that run on a schedule
• Add an LLM-driven transformation step inside a larger data pipeline

When NOT to Use ADK

ADK must never be used to fabricate data that should come from real sources.

Specifically:

• Do NOT use ADK to generate hiring statistics, financial events, analyst

reports, or any quantitative data that claims to originate from a real data

pipeline.

• Do NOT present ADK-generated content as if it were sourced from SDKs, APIs,

or databases.

• If a data source is unavailable, report the limitation as a blocker — do not

use ADK as a fallback data generator.

ADK output that involves reasoning over real data (sentiment classification,

trend summarization) is fine, but must be labeled as AI-generated analysis.

Deployment Quick Reference

See deployment.md for full details.

Deploy feed scripts or tasks as cronjobs for scheduled execution:

alva deploy create --name btc-ema-update --path '~/feeds/btc-ema/v1/src/index.js' --cron "0 */4 * * *"

Cronjobs execute the script via the same jagent runtime as alva run. Min

interval: 1 minute.

Name format: All resource names (cronjobs, feeds, playbooks) must be 1–63

lowercase alphanumeric characters or hyphens, and cannot start or end with a

hyphen (DNS label format). Example: btc-ema-update, not BTC EMA Update.

After deploying a cronjob, register the feed, create a playbook draft, then

release the playbook for public hosting. The playbook HTML must already be

written to ALFS at '~/playbooks/{name}/index.html' via fs/write before

releasing.

Important: Feed names and playbook names must be unique within your user

space. Before creating a new feed or playbook, use

alva fs readdir --path '~/feeds' or

alva fs readdir --path '~/playbooks' to check for existing names and avoid

conflicts.

# 1. Release feed (register in DB, link to cronjob)
alva release feed --name btc-ema --version 1.0.0 --cronjob-id 42 \
  --description "Fetches BTC/USDT 1h klines from Binance and emits the 20-period EMA as a time series"
# → {"feed_id":100,"name":"btc-ema","feed_major":1}

# 2. Create playbook draft (creates DB record + ALFS draft files automatically)
#    Include trading_symbols when the playbook involves specific assets.
alva release playbook-draft --name btc-dashboard --display-name "BTC Trend Dashboard" --description "BTC market dashboard" --feeds '[{"feed_id":100}]' --trading-symbols '["BTC"]'
# → {"playbook_id":99,"playbook_version_id":200}

# 3. Release playbook (reads HTML from ALFS, uploads to CDN, writes release files automatically)
alva release playbook --name btc-dashboard --version v1.0.0 --feeds '[{"feed_id":100}]' --changelog "Initial release"
# → {"playbook_id":99,"version":"v1.0.0","published_url":"https://alice.playbook.alva.ai/btc-dashboard/v1.0.0/index.html"}

# After release, output the canonical share link to the user:
# https://alva.ai/u/<username>/playbooks/<playbook_name>
# e.g. https://alva.ai/u/alice/playbooks/btc-dashboard

Alva Design System

Always read design-system.md first — it covers tokens,

typography, theme, and page-level layout. Then read only the spec you need:

1. Generating a widget or chart →

design-widgets.md

1. Using a component (Button, Tag, Dropdown, Tab, etc.) →

design-components.md

1. Building a trading strategy playbook →

design-playbook-trading-strategy.md

1. Only need global rules → stay in design-system.md

Filesystem Layout Convention

Prefer using the Feed SDK for all data organization, including point-in-time

snapshots. Store snapshots as single-record time series rather than raw JSON

files via alfs.writeFile(). This keeps all data queryable through a single

consistent read pattern (@last, @range, etc.).

Common Pitfalls

• @last returns chronological (oldest-first) order, consistent with

@first and @range. No manual sorting needed.

• Time series reads return flat JSON records. Paths with @last, @range,

etc. return JSON arrays of flat records like

[{"date":...,"close":...,"ema10":...}]. Regular paths return file content

with Content-Type: application/octet-stream.

• last(N) limits unique timestamps, not records. When multiple records

share a timestamp (grouped via append()), auto-flatten may return more than

N individual records.

• The data/ in feed paths is the synth mount. feedPath("my-feed") gives

'~/feeds/my-feed/v1', and the Feed SDK mounts storage at /data/.

Don't name your group "data" or you'll get data/data/....

• Public reads require absolute paths. Unauthenticated reads must use

'/alva/home//...' (not '~/...'). Discover your username via

alva whoami.

• Top-level await is not supported. Wrap async code in

(async () => { ... })();.

• require("alfs") uses absolute paths. Inside the V8 runtime,

alfs.readFile() needs full paths like '/alva/home/alice/...'. Get your

username from require("env").username.

• No Node.js builtins. require("fs"), require("path"), require("http")

do not exist. Use require("alfs") for files, require("net/http") for HTTP.

• Altra run() is async. FeedAltra.run() returns a Promise.

Always await it: const result = await altra.run(endDate);

• Altra lookback: feature vs strategy. Feature lookback controls how many

bars the feature computation sees. Strategy lookback controls how many feature

outputs the strategy function sees. They are independent.

• Quote ~ paths to prevent shell expansion. The shell expands bare ~ to

your local home (e.g. /Users/alice/), not the ALFS home

('/alva/home/alice/'). Always quote paths: --path '~/feeds/...'.

• Home directory not provisioned? If you get PERMISSION_DENIED on all

ALFS operations (including '~/'), your home directory was not created during

sign-up. Call alva fs mkdir --path '~/' to provision it. This is idempotent

and safe to call anytime.

• Cronjob path must point to an existing script. The deploy API validates

the entry_path exists via filesystem stat before creating the cronjob.

• Always create a draft before releasing. alva release playbook

requires the playbook to already exist (created via

alva release playbook-draft).

• Create new playbooks from scratch unless you are doing a version update.

Only version updates may refer to an existing playbook. For all other new

playbooks, do not read existing ones.

• ECharts: use type: 'time' for date axes. Do not pass raw epoch

millisecond values as category labels — users will see numbers like

1773840600000 instead of dates. Use type: 'time' axis, which handles

formatting automatically, or format dates before passing to a category axis.

• ECharts graph: validate node/edge data. For type: 'graph' series with

layout: 'none', verify every edge source/target matches an existing

node name, no duplicate node names exist, and node names don't contain

special characters that break ECharts internals. Add a try/catch wrapper

around chart initialization with a fallback message if rendering fails.

• ECharts sizing: allocate sufficient height. Heatmaps need

height = max(300px, numRows * 40px). Primary charts on overview tabs should

be at least 400px tall and visually dominant over metric cards. Do not compress

charts to fit everything above the fold.

• Separate lastDate watermarks per data source. When a feed combines

multiple data sources with different update frequencies (e.g. ETF OHLCV +

VIX + CPI), use a separate ctx.kv key for each source's watermark (e.g.

lastDate_etf, lastDate_vix, lastDate_cpi). A shared watermark causes

slower-updating sources to be permanently filtered out after the first run.

Resource Limits