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.

[npx sigrank]   [Star this repo]

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

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

Also in the MO§ES™ suite

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 installssigrank enroll             # sign in: paste a connect code from signalaf.com → Settingssigrank submit             # publish your verified runs to the board

Or explore first, no sign-in:

sigrank                    # full tabbed TUI: dashboard · compare · board · watchnpx sigrank board --once   # print the live leaderboard oncebunx 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 installcp .env.example .env.local      # all values optional — see Environment belownpm 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

Before committing, run the gates CI enforces:

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

Project Map

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.

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.