Newcomer Repo & Workers Guide

1. What you are looking at

Timed Trading is a Cloudflare Workers + Pages product:

Product entry for signed-in users is /today.html (not the retired /index-react.html).

2. Read in this order (~15–20 min)

Paths below are in the git repo root (e.g. /workspace/… on the agent VM, or the local clone):

1. AGENTS.md — onboarding contract, house rules, Cursor Cloud local tips
2. CONTEXT.md — stack, deploy, journey pages, condensed critical lessons
3. skills/README.md — index of how-to playbooks
4. skills/worker-topology.md — which worker runs which cron
5. skills/deploy.md — what to deploy when; merge ≠ deploy

Do not try to memorize CONTEXT.md lessons on day 1. Skim the Stack / Deploy / Product entry sections; grep lessons when something looks familiar.

3. Repo map

Mental model: four Cloudflare Worker scripts share one trading codebase; the bridge is a fifth script with its own tree. Pages is independent of Worker deploys.

4. Which worker runs what

Canonical detail: skills/worker-topology.md.

Cutover flags (do not dual-run)

Order: flip monolith *_EXTERNAL first, then enable the dedicated worker. Overlap corrupts state. Flags are dashboard vars (keep_vars = true); never wrangler secret put a name that already exists as a var.

Binding parity

Role workers declare their own bindings. A binding added only to worker/wrangler.toml is not on tt-engine/feed/research. DOs stay owned by the monolith — role workers reference them with script_name = "timed-trading-ingest". Silent if (env.SOME_BINDING) fallbacks have caused multi-day freshness outages; prefer surfacing misses in health/tombstones.

5. Pages vs Worker (critical)

• npm run deploy:worker does not update UI pages.
• Changing worker/ without redeploying tt-engine / tt-research leaves cron lanes on old code (npm run deploy:crons or CI).
• A green GitHub Actions run is not proof prod moved — check deployedSha on /timed/health or Cloudflare version dates (skills/deploy.md).
• For local API work against a local worker, temporarily point built react-app-dist/_worker.js at http://localhost:8787 (revert; do not commit).

6. How to run locally

Full notes live in AGENTS.md → Cursor Cloud specific instructions. Condensed:

Prerequisites

cd /workspace   # or clone root
npm install     # no lockfile; use install not ci

Create git-ignored worker/.dev.vars:

TIMED_API_KEY=local-dev-key
CF_ACCESS_AUD=local-dev-aud

Optional for live quotes / LLM: TWELVEDATA_API_KEY, OPENAI_API_KEY.

Without those secrets, wrangler dev returns 503 runtime_misconfigured.

Boot

# Terminal A — API (Miniflare KV/D1/DO; small seed universe)
cd worker && ../node_modules/.bin/wrangler dev --port 8787

# Terminal B — frontend (after build)
cd /workspace
npm run build:frontend
./node_modules/.bin/wrangler pages dev react-app-dist --port 8788

Port 8788 is allow-listed in worker CORS_ALLOW_ORIGIN.

Auth locally

Cloudflare Access (Google OAuth) cannot complete on a typical cloud VM — only public surfaces like /splash render in a browser. Exercise authenticated logic via curl + API key.

Useful local probes

curl -s "http://localhost:8787/timed/health"
curl -s "http://localhost:8787/timed/all?slim=1" -H "X-API-Key: local-dev-key" | head -c 200

# Crons do not auto-fire in wrangler dev:
curl "http://localhost:8787/cdn-cgi/handler/scheduled"

Local D1 starts empty; schema is created lazily by d1Ensure*Schema(). POST /timed/ingest-capture is a robust way to exercise ingest without a full scoring universe.

Tests (the only gate)

npm test          # vitest
# CI also: node --check on worker entrypoints + esbuild bundle check

There is no lint step. npm run build:frontend always dirties react-app-dist/ cache-bust stamps — revert if built only to verify.

7. Auth, tiers, and entitlements (day-1 version)

Canonical matrices: skills/user-state-matrix.md, skills/security-auth-patterns.md.

Live prices + proprietary scores go to Pro / VIP / Admin only:

• Server: canAccessLivePrices() + redactTickerMapForTier() in worker/api.js
• UI display gate: window._ttIsPro
• Members and anon get neither; prefer structured 200s with _redacted / tier_required, not noisy 4xx on poll endpoints

• CF Access gates authenticated HTML pages (Google OAuth).
• Stripe drives Pro subscription state; VIP codes / admin grants use subscription_status='manual'.
• API key (TIMED_API_KEY) is operator/admin path — prefer X-API-Key header; ?key= is deprecated.

8. Price pipeline (invariants to internalize)

Full rules: workspace .cursor/rules/price-data-pipeline.mdc + CONTEXT lessons. Do not invent alternate change math.

1. TwelveData first (DATA_PROVIDER=twelvedata); Alpaca is execution / fallback.
2. getDailyChange(t) in react-app/shared-price-utils.js is the only client daily-change path.
3. KV timed:prices short keys: p, pc, dc, dp, … Extended: ahp, ahdc, ahdp.
4. Value timestamps are mandatory: q_ts (quote receipt) and p_ts (last price move). Freshness gates key off these — never poll t. Writers must stamp and never regress stamps.
5. PriceStream DO (TwelveData WS) must own symbols in timed:prices; orphan symbols can get clobbered by KV eventual consistency between cron and DO.
6. Outside RTH, preserve day-change and EXT fields appropriately; never write AH fields during RTH.
7. Footer must include "Market data powered by Twelve Data" (licensing).

If prices look "stuck on yesterday," check value stamps and /timed/health (valueStaleCount), not just t.

9. Where to look for common tasks

Full index: skills/README.md. If more than ~3 tool calls inventing a procedure, write a skill before leaving.

10. House rules (do not skip)

From AGENTS.md / CONTEXT:

• No emojis in code, commits, or PRs unless asked.
• User-facing product copy: avoid "you / your" (compliance).
• Never inline daily change math — use getDailyChange.
• Gate live prices + scores to Pro/VIP/Admin.
• Plan non-trivial work in tasks/todo.md (append; avoid merge-conflict churn on the Active header from feature PRs).
• Stop after two failed attempts at the same approach — re-plan.
• Verify before done; after operator corrections, update tasks/lessons.md + a one-liner in CONTEXT.
• One logical change per commit/PR; before pushing an existing branch run bash scripts/check-branch-merge-state.sh.

11. First-week checklist

Day 1 — Orient

• Read AGENTS.md + CONTEXT Stack/Deploy/Product sections + skills README
• Skim worker-topology.md and this guide’s architecture companion
• Map the five Worker scripts and what Pages serves
• Clone/build: npm install, npm test green (or know why not)

Day 2 — Local loop

• worker/.dev.vars with placeholder secrets
• Boot wrangler dev on 8787; hit /timed/health and a keyed /timed/all?slim=1
• Build frontend; understand Pages→production proxy caveat
• Trigger a scheduled handler once; note crons don’t auto-fire locally

Day 3 — Data plane

• Inspect timed:prices shape (KV skill); find q_ts / p_ts
• Trace one ticker from TwelveData → PriceStream/cron → KV → UI getDailyChange
• Read skills/all-snapshot.md (slim index vs full payload OOM history)

Day 4 — Auth & gating

• Walk user-state-matrix; confirm Member vs Pro vs VIP vs Admin
• Call an endpoint without key (redacted) vs with key (full)
• Read security-auth-patterns (route guards, WS tickets, no unguarded mutators)

Day 5 — Deploy awareness

• Read deploy.md decision tree; list which scripts a worker/** change touches
• Know how to verify deployedSha / version dates (merge ≠ deploy)
• Note Pages vs Worker independence (UI field without worker stamp = blank badges)

Days 6–7 — One vertical slice

• Pick a small skill-backed task (rescore, KV inspect, Discord dry-run, or a UI token fix)
• Ship behind the usual PR/check-branch-merge-state discipline
• Grep tasks/lessons.md for the area touched before claiming done

12. Architecture visual

Mermaid + partner-facing detail: engineering partner onboarding.

13. Unknowns / do not invent