> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# App agents

# sequency-app — Agent Instructions

GitHub: [sequencyhq/sequency-app](https://github.com/sequencyhq/sequency-app)

**Primary local guide:** `CLAUDE.md` in this directory (zero-mock policy, data architecture,
API proxy pattern). Parent product map: `../AGENTS.md`, `../CLAUDE.md`. Threat model:
`../THREATMODEL.md` when touching auth, broker, or secrets.

This file adds Grok-oriented conventions, design system truth, and cross-repo boundaries.

## Mission

Next.js UI for opportunity discovery, stock/options workspaces, research/lab, trade flows,
and agent surfaces. All market truth comes from sequency-data (FastAPI + streams) — never
mock, never call Alpaca from Next routes.

## Stack

* Next.js App Router (`app/`), React, TypeScript
* Vitest for unit/component tests (**not** Jest)
* Design tokens: `styles/design-tokens.css` + Paper Terminal v2
* Deploy: Vercel (frontend); data plane remains OVH

## Absolute rules

1. **Zero mock financial data** — show No Data / Unavailable / retry, never placeholders that look real.
2. **Proxy only** — `Frontend → /api/* → WORKER_API_URL (worker.sequency.sh) → FastAPI`.
3. **Never hardcode hex** for product UI — use tokens. Accent = indigo/periwinkle; emerald =
   marketing only; green in-app **only** for gain/profit.
4. **Design before new pages** — Paper Terminal composition contracts; render every designed
   element or an explicit empty state.
5. **react-query v5:** `failureCount` resets at the start of every poll — use monotonic
   `errorUpdateCount` for cross-poll failure thresholds (app#441).

## Design system (canonical)

| Source                                         | Role                                                 |
| ---------------------------------------------- | ---------------------------------------------------- |
| `../design_corpus/DESIGN_v2_Paper_Terminal.md` | Authoritative PT v2                                  |
| `styles/design-tokens.css`                     | Runtime tokens (light \~L167, dark \~L420)           |
| `documentation/design/VISUAL_STYLE_GUIDE.md`   | **Deprecated** "Layered Luminance" — do not re-adopt |

Layout: **center** content on wide screens (floated margin-inline), data tables full-width.
Tabular nums; glow = focal-only.

## Routes (post strategies-tree removal)

Prefer: `/lab`, `/trade/[symbol]`, `/research`, `/ops` (and stock/options workspaces).
Canonical product docs for new specs: `docs/` (and `documentation/` for historical API notes).

## Verification

```bash theme={null}
npx vitest run path/to/test
npm test
npm run type-check
npm run build
```

Pretest/prebuild may regenerate Conviction tiers — generated output must be clean or explained.

Vitest + `@vitejs/plugin-react` can hang in **symlinked worktrees** — use isolated config if needed.

## Cross-repo

| Concern                             | Owner                           |
| ----------------------------------- | ------------------------------- |
| Chart engine / DisplayList          | sequency-charts (`../charts`)   |
| Market data, scores, lifecycle APIs | sequency-data (`../data`)       |
| Phoenix signal stream               | data `services/signal-delivery` |
| Schema/migration numbers            | data only                       |

Contract changes land in data first; app adapts. One PR per repo.

## Worktrees

If this root is dirty, create `~/projects/sequency/.worktrees/app-<topic>` from the intended
base. Do not mix unrelated feature packets.

## Issues

`gh issue create -R sequencyhq/sequency-app` for frontend-only work.

## Pattern corpus / DSOM awareness (added 2026-08-05)

1. **DSOM governs pattern/setup/signal/proposal/execution work** —
   `data/docs/superpowers/specs/2026-08-04-decision-support-object-model.md` (five objects:
   Observation→Setup→Signal→Proposal→Execution). Read it before touching any of those.
2. **OA-13** dual-key: `lifecycle_id` = Setup identity, `event_id` = confirmation fact (NULL
   on prospects). **OA-14**: the word "revision" is banned — three named refs replace it.
   **OA-15**: "Evidence Envelope" is the semantic name for the existing Decision Lens wire
   object; `chart_contracts.Observation` remains the documented legacy wire name (no breaking
   rename).
3. **Chart geometry/levels come only from** `GET /pattern-events/symbol/{symbol}/insights`
   (corpus-backed, CT-01). The legacy AI-trendline analyze path is gone in-app (app #503).
   No drawn/actionable chart price may ever originate from an LLM — standing invariant,
   security-review-verified.
4. **Data-repo Python: lint via `scripts/lint-api.sh` ONLY** (CI-pinned ruff 0.16.0; venv
   ruff lies). `api-lint` is a required check; after merging to data `main`, verify the
   **deploy** run, not just PR checks — merged ≠ deployed.
5. **Pattern-catalogue work is governed by epic data#1654** (production-readiness spec
   `data/docs/superpowers/specs/2026-08-07-geometric-detection-production-readiness.md`).
   Class A construction is AUTHORIZED in tranches under the ratified classification pass
   (`2026-08-06-class-a-adj2-classification-pass.md`) + OQ-PDE-002 discipline — but nothing
   persists `_shape` facts until the feature substrate exists (data#1634), contextual shapes
   are gated on AC-CTX (data#1588), and every new detector lands with its OQ cases. Classes
   B–G need their own ratified classification passes first.
6. **Screener filters fail closed** — build requests with registry ids; an unsupported leaf
   returns `422 unsupported_filter`, never a silent drop.