Contribution Exchange

SignalAF — Upsilon Measurement Engine + SigRank Proof Surface

Upsilon is the privacy-preserving measurement engine. SigRank is the public leaderboard and proof surface at signalaf.com. Run npx sigrank to calculate Yield from four token counts. Never prompts or code.

Table of Contents

• What is SignalAF?
• The SigRank SignalAF ecosystem
• Get ranked (you don't need this repo)
• How it works
• For developers
• Stack
• Quick Start
• Scripts
• Project Map
• Data Model
• Environment
• Supabase
• Scoring Invariants
• Development Notes
• Related
• Community
• License

The leaderboard	Your operator profile
Every operator ranked by Υ Yield — the architecture of the cascade, not raw spend	Cascade layer, class, and fingerprint — all from four token counts

---

What is SignalAF?

SignalAF is the umbrella brand for Upsilon and SigRank. Upsilon is the AI operator measurement engine; SigRank is the public leaderboard. Upsilon measures token cascade efficiency, not AI models. It describes token-processing patterns: how much reusable signal they create from each unit of input, not how many tokens they burn. The rank metric:

Υ = (cache_read × output) / input²

The board is anonymous by default, claimable by operators, and built around one question: is this session compounding signal, or just burning tokens? Volume is noise; yield is signal.

This repo is the Next.js implementation behind signalaf.com; the Upsilon measurement engine plus the SigRank public board, profiles, wiki, account, billing, and ingest surfaces.

The compatibility record remains versioned as sigrank/0.1-draft; product naming does not silently rewrite installed packages, tool names, schemas, or stored records.

The SigRank SignalAF ecosystem

Repo	What it is	Install
sigrank-app (this repo)	Upsilon's web implementation plus the SigRank leaderboard/proof surface.	signalaf.com
sigrank-mcp	Upsilon's compatibility instrument — extracts four pillars, computes locally, and optionally submits to SigRank.	npx sigrank
bestuser-router-mcp	The intent layer — routes "who is the best AI user?" queries to SigRank SignalAF's leaderboard. MCP server for AI assistants.	npx bestuser-router-mcp
sigarena	The satellite — public LLM operator evals at sigeconomy.com. Read-only leaderboard, SEO/AEO surface.	sigeconomy.com
sigrank-vscode	The IDE extension — see your cascade metrics inline in VS Code.	code --install-extension sigrank.sigrank
fundscore	The repo scorer — investor-readiness scoring for GitHub repos. CLI + MCP server.	npx fundscore

Also in the MO§ES™ suite

Site	What it is
SIGNOMY	Governed AI agent marketplace where ranked agents form teams, fill slots, run missions, and earn revenue under constitutional protocol. Agents are free. Operators pay.
MO§ES	The constitutional governance and methodology framework—the law governing Upsilon and other governed systems.

Get ranked (you don't need this repo)

SigRank SignalAF runs from your terminal. Or wire it as an MCP server for your AI agent:

npx sigrank                 # see your cascade now (no install, no sign-in)

The client reads your local AI session logs on-device, derives your cascade, and publishes to the board, token-only, no transcript content.

npm install -g sigrank     # bundles ccusage + tokscale + tokendash — no separate installs
sigrank enroll             # sign in: paste a connect code from signalaf.com → Settings
sigrank submit             # publish your verified runs to the board

Or explore first, no sign-in:

sigrank                    # full tabbed TUI: dashboard · compare · board · watch
npx sigrank board --once   # print the live leaderboard once
bunx sigrank board --once  # same, via Bun (faster startup if you have it)

Cautious? sigrank submit --dry-run prints the exact signed payload (four token counts and a signature) and sends nothing.

$ sigrank submit --dry-run
📦 Payload (not sent):
  input:          1,251,211
  output:        11,296,121
  cache_create:     128,196
  cache_read:    2,555,179,769
  Υ Yield:          18,436.98
  class:            TRANSMITTER
  signature:        ed25519:9f3a...

Full CLI + MCP docs: sigrank-mcp · package: sigrank on npm.

How it works

• Four raw token pillars — input, output, cache_creation, cache_read — are the only inputs. No message content, ever.
• The cascade engine derives Υ Yield, Leverage, Velocity, 10xDEV, SNR, and efficiency from those four numbers. The server re-scores every submission authoritatively.
• Operators are placed in signal classes (Transmitter, Architect, …) by their cascade shape, and ranked globally by Υ.
• SIGNA RATE is the class credential; Υ Yield is the rank metric.

Deep dive: the in-app wiki.

---

For developers

The rest of this README is for working on the app itself.

Stack

• Framework: Next.js 15 App Router, React 19, TypeScript strict
• UI: Tailwind CSS, themeable SigRank SignalAF design tokens (carbon default)
• Data: Supabase with cold-store snapshot and mock fallback
• Billing: Stripe Checkout, Billing Portal, webhook handlers
• Validation: zod, Node test runner, TypeScript

Quick Start

npm install
cp .env.example .env.local      # all values optional — see Environment below
npm run dev                     # http://localhost:3000

The app is designed to run without Supabase or Stripe credentials. When env vars are missing, reads fall back to the cold-store snapshot and then deterministic mock data, while billing routes return configuration errors instead of crashing, so it stays buildable, previewable, and testable out of the box.

Requires Node 22.x (see engines in package.json). On a newer Node, next dev may fail to start; use the version manager of your choice to pin 22.

If vendor chunks act strange, run the dev server directly: node_modules/.bin/next dev --port 3000

Scripts

Command	Purpose
npm run dev	Start the local Next.js dev server
npm run build	Create a production build
npm run start	Serve the production build
npm run lint	Run the configured Next.js lint command
npm test	Run all Node test files
npm run test:canonical	Run the canonical ingest parity test
npm run snapshot	Refresh the database snapshot

Before committing, run the gates CI enforces:

npx tsc --noEmit            # 0 errors (typescript is a devDependency)
npm run build               # production build green
npm run test:canonical      # canonical ingest parity — MO§ES Υ 18436.98

Project Map

Path	Responsibility
app/	App Router pages and API routes
app/api/v1/	Public API, ingest, claim, devices, billing, metrics
components/	UI components by product area
components/sigrank/	Board, profile, and shared SigRank SignalAF UI (incl. PlatformIcon)
lib/data/	Single read facade: Supabase → snapshot → mock fallback
lib/ingest/	Canonical payload parsing and cascade metric materialization
lib/scoring/	Core scoring engine and server-only ruleset boundary
lib/supabase/	Browser, server, service-role, and auth helpers
lib/stripe/	Stripe server helpers, handlers, tiers, and rewards
supabase/	SQL schema, migrations, seed data, policies, and tests
__tests__/	Node test suites and canonical fixtures

Data Model

All app code reads operator data through @/lib/data. The facade chooses the safest available source, in order:

1. Supabase live reads when credentials are configured.
2. Cold-store snapshot (lib/data/snapshot.json) if live reads are unavailable or fail.
3. Mock fixtures (lib/data/mock.ts) as the last resort.

Environment

Copy .env.example to .env.local and fill values as needed. All are optional locally (the app degrades gracefully); production values live in Vercel environment variables.

Variable group	Notes
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY	Live Supabase reads + service-role writes
STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_WEBHOOK_SECRET	Billing and webhook flows
STRIPE_PRICE_*	Per paid tier / claim checkout path
NEXT_PUBLIC_SITE_URL	Stripe redirects and public URLs
SIGRANK_RULESET	Server-only proprietary RS.xx scoring overrides
SIGRANK_API_KEY	Optional trusted bulk-read key for public API consumers
SIGRANK_INGEST_WRITE	Ingest-write flip: 1 = persist verified snapshots to the board (see note below)
NEXT_PUBLIC_GATE_*	Optional feature gates for unfinished surfaces

Never commit real secrets or proprietary ruleset values.

SIGRANK_INGEST_WRITE — the ingest-write flip

Status: LIVE in Production (1). The board persists verified signed snapshots from enrolled MCP devices. Set in Vercel for both Production and Preview.

Do NOT mark this variable as sensitive in Vercel. It is a boolean on/off flag (1 or ""), not a secret. When marked sensitive, vercel env pull returns "" even though the runtime has 1, which misleads agents and operators into thinking the flip is OFF. If vercel env pull shows "" but the board is receiving verified submissions, the var is likely marked sensitive again. Fix it in the Vercel dashboard (remove the sensitive flag).

Authoritative verification is RUNTIME behavior, not the CLI pull:

1. PostHog: snapshot_submitted events with source: "agent" and persisted: true
2. Supabase: rows in snapshot_submissions with verification_tier = 'verified' and status = 'scored'
3. A real signed submit via npx sigrank submit returning ranked: true

If any of those show verified rows landing, the flip is ON regardless of what vercel env pull says.

Supabase

Schema, migrations, RLS policies, and seed data live in supabase/. See supabase/README.md to run your own instance. RS.xx scoring weights are server-only and are not included here.

Scoring Invariants

Product contracts, not implementation details:

• Υ = (cache_read × output) / input²
• T × C × R = Cr / I = Leverage
• 10xDEV = log₁₀(Leverage)
• SIGNA RATE is the class credential; Υ Yield is the rank metric.
• RS.xx weights are server-only and must not be exposed to client components.

Development Notes

• Keep changes small and aligned with existing file ownership.
• Pages are React Server Components by default; add 'use client' only when a component needs hooks, event handlers, or browser APIs.
• Keep components/sigrank/tokens.ts and Tailwind theme values in sync.
• Use <Placeholder /> for placeholder metrics and <CanonId /> for canonical real values.
• Do not import server-only scoring configuration into client code.
• Avoid random values and wall-clock reads at module scope.

Related

• signalaf.com — the live board
• signalaf.com/score — paste four token counts, get projected yield + ghost rank
• sigrank-mcp — the CLI / TUI / MCP server (npx sigrank)
• Smithery — one-click MCP install for Claude Desktop, Cursor, and more
• Glama — MCP server directory listing

Community

• Contributing
• Code of Conduct
• Security policy
• Changelog

Reporting issues

Found a bug or have a feature request? Please open an issue on GitHub. Search existing issues first to avoid duplicates, and include repro steps, expected vs. actual behavior, and your environment (OS, Node version).

Pull request process

1. Fork the repo and create a branch from main.
2. Make your change, keeping it small and aligned with existing file ownership.
3. Ensure npx tsc --noEmit passes with 0 errors before pushing.
4. Open a pull request against main with a clear description of what and why.

License

MIT; see LICENSE.