01Start Here

What NED is, in five lines — and how to use this guide.

How to use this guide

• Read 02 Prompting first — the mindset, the shared vocabulary, and the phrase-book. That's how you talk to your agent like the owner does.
• 04 The Edge Loop and 05 Case Studies teach how the owner actually works. The method behind every verdict, told through the real studies (real numbers, no invention).
• 06 The Trap List — each trap has a body attached. Read it before testing any idea.
• 07 The Two Seats and 08 Per-Sport Recipe are the operational how-to: how we ship without stepping on each other, and exactly what a sport file is.
• 09 Ground Rules is the constitution recap — everyone inherits it automatically via AGENTS.md.
• 03 Vocabulary is a searchable reference — come back to it whenever a term is unfamiliar.
• 10 Owner's Data Points is the owner's map of what matters in each sport and where to look.

GitHub & the context files — if you've never collaborated on a repo

GitHub is where the project's shared copy lives. It holds the source code and nothing else. No money data ever goes there — the live ledgers, the bankroll, and every key stay on the owner's machines and are excluded from git. Your copy starts with empty ledgers. That's correct, not broken.

Three words cover almost everything you'll do:

• CLONE — download your own full copy of the project to your machine.
• BRANCH — a private working line inside your copy, so your changes touch nothing shared until they're ready.
• PR (pull request) — "here's my change, please review it." The owner reviews and folds it into the main project.

The context files. The repo carries its own memory. These files teach your agent everything about the project:

02Prompting — Talk Like the Owner

The repo teaches your agent the project. This page teaches you the owner's operating style: the mindset, the phrases, and the shape of a good prompt.

The one-paragraph version

Talk to the agent like a sharp, trusting boss who has zero tolerance for self-deception. Point it at one thing, hand it the wheel, name the guardrails, and demand proof. You don't need to be formal or write clean prose. Messy, conversational, even voice-to-text rambling is fine — as long as every prompt lands three things: the goal, the guardrails (what must never happen), and "verify it / prove it / tell me honestly." That's the whole game.

The mindset — six values in every prompt

1. Honesty over hope. Never accept a pretty number. "Make sure it's exactly what would happen on Polymarket." "Small n is honest, not flattered." If tests fail, you want to hear it. A result you can't trust is worse than no result.
2. Edge before scale. Prove the edge first. Don't add bots or size to paper over a weak one. One lane at a time — build it out fully, watch it, then move on. Scale = more proven lanes, not a bigger bet.
3. Anti-overfit is religion. A locked strategy is never re-tuned ("just one more filter" is banned). You measure a signal before you wire it live, and everything faces an out-of-sample gate — a test on data the idea never saw. A loop that optimizes on its own data just finds "prettier noise faster."
4. Delegate, then verify. "You've got the wheel — go." But in the same breath: test it, adversarially review it, don't tell me it's done until it's proven. Trust is high; the bar for "done" is higher.
5. Gates, not vibes. Nothing goes real until it clears a gate — a big enough sample n, a Wilson lower bound above breakeven. real_capital = NO until the math says otherwise. Report the claim as the lower bound, not the point estimate.
6. Speed is an edge. Get information as fast as possible — faster feeds, warmer connections, lower latency — across every bot.

The owner's phrase-book — real phrases, steal them

The anatomy of an owner-style prompt

Not every prompt has all five, but the good ones hit Goal → Wheel → Guardrails → Verify → Persist:

1. Goal — one thing, concretely. "Add a signal that fades order-flow imbalance on my sport."
2. Wheel — hand over the how. "You've got the wheel — figure out the cleanest way."
3. Guardrails — what must never happen. "Paper only, zero orders, don't touch the engine files, don't re-tune anything locked."
4. Verify — the proof you want. "Run the test suite, keep it green, and show me the honest read — Wilson LB, not the point estimate."
5. Persist — capture it. "Then update the docs so the next session and my friends can follow."

Template you can copy:

"Working on [one lane / one question]. You've got the wheel — [do the thing], but [guardrails: paper, zero orders, no re-tune, don't touch engine files]. Prove it — run the tests, and give me the honest read (small n is fine, just say so). Then update the docs to a T."

Worked example — adding a sport to Togi

Weak prompt (what NOT to do):

"make my sport bot win more, tune it until the win rate is good"

That asks the agent to overfit (banned), has no guardrails, and no proof standard. The agent that follows this project's rules will push back on it.

Owner-style prompt (do this):

"New lane: add [my sport] to Togi. You've got the wheel — one new file in the sports package, follow the existing sport as the template so it auto-discovers. Keep it paper, zero orders, don't touch the frozen engine files, and don't re-tune anything that's locked. Wire the staleness edge the same way the other sports do. Run the mm test suite and keep it green, add tests for my sport, and give me the honest readout — what's the edge, and how far is it from the gate. Then commit to a branch and update the docs so I can PR it."

Notice: one file, template-following, guardrails named, tests demanded, gate-honest, persisted. That's the whole style.

The real thing — prompts the owner actually sent, verbatim

Everything above is the theory. These six are the practice: real kickoff prompts from the owner's own sessions, lightly trimmed. Read them for the shape, not the polish — messy words, sharp intent.

The bans — the owner never asks for these; don't either

Getting started — point the agent at the context

You don't have to explain the project — it's in the repo. First thing, tell your agent:

"Read AGENTS.md, BUILD_STATE.md (the top checkpoint), and NEXT_SESSION_PLAN.md before you touch anything. Then [your task]."

03Vocabulary — the Shared Language

The agent knows these terms cold. Using them makes you 3× faster and keeps you inside the guardrails. Plain-English glosses — type to filter.

04The Edge Loop — the Whole Method on One Page

Every edge in this project — validated, accruing, or dead — went through the same seven steps. No exceptions, no shortcuts, and the order matters.

How to prompt for this — the edge-work phrasings

The phrase-book in 02 Prompting covers the general style. These are the edge-work phrasings specifically — the owner's moves and what each one tells the agent to do:

05Case Studies — How It Actually Went

Every number below is a real number from this repo's studies. If you're about to test an idea, read these first: the graveyard is half the moat.

06The Trap List

Each one has a body attached — a real study in this repo that hit it (or dodged it).

07The Two Seats

Two friends, two tool setups, one loop. Ownership per AGENTS.md: the owner runs Loki, the live fleet, and the mm/ plug-in surface; the friends own Togi sport sets A and B.

git clone git@github.com:bavatharannanthan7-lang/ned-v1.1.git ned
cd ned
git switch -c feat/togi-<sport>
# save Claude's file as iterations/togi/<sport>.py, then:
git add iterations/togi/<sport>.py
git commit -m "togi: add <SPORT> sport module"
git push -u origin feat/togi-<sport>

08The Per-Sport Recipe

What a sport file actually is, mirrored from the real one (iterations/togi/mlb.py).

"""TOGI · <SPORT> — pre-game moneylines."""
from togi import core

core.register(
    "<SPORT>",           # must match sports_feed.SPORTS: MLB / NBA / NFL / NHL / WNBA
    home_edge=0.035,     # home-field prob bump (MLB uses +3.5pp)
    min_edge=0.07,       # log floor — below this the divergence is noise
    max_edge=0.15,       # log cap — above this the model is MISSING a feature, not finding edge
    # prob_fn=my_model,  # def my_model(game, cfg) -> P(home win); the seam where Mimir FV plugs in
)

That's the whole registration. The engine signature is

core.register(code, *, home_edge, min_edge=0.07, max_edge=0.15, prob_fn=None, model="log5")

— your file provides the config, core.py provides scan → dedup shadow-log → settle vs on-chain outcomePrices. Your prob_fn (if you pass one) receives the game dict from sports_feed.games() (home/away with rec/wpct, state) and returns P(home win) in (0,1), or None to skip. core only bets state == "pre" games — leak-safe by construction.

Where the edge actually comes from — read this before "improving" the model

Data-point ideas go in the other plug-in surface

A pitcher/lineup/park/rest idea isn't a sport — it's one file in iterations/mm/signals/<name>.py calling signals.register(name, fn, cap_c=0.5) with fn(ctx) -> (delta_p, confidence, note). Auto-discovered, hard-capped at 0.5¢ until it self-validates on the tape (total cap 1¢), scored in SUGGESTION-mode — the harness recommends a cap change, the owner applies it. Copy example_probable_pitcher.py. Signal fns must be fail-open and read from cached/local stores (the live ones read the mlb_features cache, the weather cache, or the lake events tape) — never make blocking network calls inside a scan pass (timer passes do the fetching).

What it must pass before the owner merges

• The full suite green: cd iterations && NED_PUSH_DISABLE=1 python3 -m unittest discover -s mm/tests -q (any test that could touch notify paths MUST set NED_PUSH_DISABLE=1 — that's the notify contract).
• A dry python3 -m togi that prints sane reads for your sport.
• Honest n reporting. Report what the sample supports and say how small it is — Wilson lower bound, not the point estimate. "It worked 3 times" is not evidence; small n stated honestly is fine.
• The diff stays inside your file(s). One sport file (or one signal file), tests if you added logic.

What NOT to do

09Ground Rules — the Constitution Recap

From AGENTS.md. Everyone inherits these automatically — the repo teaches your agent. Everything is PAPER, real_capital = NO, fleet-wide; that never changes.

1. PAPER only. real_capital = NO fleet-wide until the canonical gate (data.gate) is met AND the owner flips the governor switches.
2. Zero orders in mm/ — by construction: no wallet, no key, no order call exists in the package.
3. One lane at a time (owner directive) — don't start a lane the owner hasn't sequenced.
4. NO RE-TUNES, EVER on locked specs; the tuning levers were exhausted to null by repeated audits.
5. Engine files are single-maintainer. The plug-in surface is togi/<sport>.py, mm/signals/, and mm/params.py — nothing else.
6. Single-owner live data. Ledgers, launchd/systemd jobs, keys: owner's machines only, all gitignored. Never write or "fix" a live book by hand — code changes only, via PR.
7. Gates, not vibes. Every edge claim = the live gate object / Wilson lower bound, never a stale snapshot or a point estimate. Exits COUNT as losses in the gate.
8. SUGGESTION-mode everywhere. Studies and scorers recommend; the owner applies. Nothing self-mutates its own deploy.
9. Settle against reality. On-chain outcomePrices always; fees exact; a fill exists only on a real print. Measure a signal before wiring it live, and prove it out-of-sample.
10. Rewards/rebates are ledgered separately and never flip a gate green.

10Owner's Per-Sport Data Points

The owner's domain map: what matters in each sport, where to look, and how each point feeds the model. The data-point lists are the owner's own words, organized. The "how it feeds the model" framing is the build-side synthesis. The constitution still applies: one point = one measured signal, paper only, no re-tunes, the scoreboard decides.

How ANY data point becomes edge here — read this first

A data point can earn in exactly three ways:

1. NUDGE — a small capped adjustment vs the sharp line (the mm/signals/ pattern: one file, 0.5¢ starter cap, self-scoring earn→1.0¢ / hold / shrink). This is where most fundamentals land — MLB already runs four (platoon splits, pitcher form, weather/park, scratch-veto).
2. VETO — information the line may not have absorbed yet (a late scratch, an inactive, a weather flip) that blocks a take entirely. Often the highest-value form, because it's about SPEED, not disagreement.
3. MODEL FEATURE — for markets with no live sharp reference (many props), the points feed the sport's prob_fn directly and BECOME the fair value. This is where deep domain maps like the NFL one below matter most, because there's no sharp line doing the work for you.

NFL — the owner's deepest map (for the NFL friend)

Team context

Coaching & scheme (OC / DC)

The matchup engine (player-vs-coverage — the heart of the props model)

Pressure ↔ QB conversion (the owner's two-sided read)

How NFL feeds the model: moneyline/spread → team-level nudges vs the sharp. But the real prize is the matchup engine → player props — receptions/yards vs coverage type. Props are exactly the "softer markets" our market-making work already flagged as the winnable pond (wider spreads, weaker lines, sometimes no sharp reference at all — so the model feature path applies). The synergy: owner's map picks the direction, the friend builds it as signals/prob_fn, our lake + books data says which prop markets are liquid enough to take.

MLB — the NFL pattern applied (for the MLB friend)

Four of these are ALREADY LIVE as capped signals (platoon splits, pitcher form, weather/park, scratch-veto) — the MLB friend extends the same pattern, one file per point.

Pitching (the "offense" of MLB edges)

Hitting & splits

The "lines" analog + context

NBA · UFC — owner's maps coming next

The combination play — why this three-way split wins

Owner's domain map (what actually matters in the sport) × friend's build (one signal file per point, measured honestly) × the platform (sharp anchor + the data lake + self-scoring + gates) = the model.

• The owner doesn't have to code; the friends don't have to know where the edge hides; the platform doesn't have to have opinions. Each supplies the piece the others can't.
• Every point self-scores (hit-rate Wilson-LB, CLV vs the close, ICIR consistency). The scoreboard decides, not the loudest voice — a point the owner loves that doesn't beat the close shrinks to 0¢, and that's the system working, not an insult.
• Bookmaker odds run through everything twice: as the anchor each nudge is measured against, and as the speed edge (staleness) when the sharp moves and the market lags — both already built.
• Priority order for a new sport: (1) the veto-class points first (scratches/inactives — cheap, high value), (2) the matchup engine for props (where lines are softest), (3) team-level nudges last (where lines are sharpest). That's deliberately backwards from how most people start — and it's why it works.