| Explore | Drill | Roll |
|---|
| Follow connected states and study both players' roles. | Review flashcards with spaced repetition and film-study clips. | Choose an attack, pass, escape or continuation and play out its possible outcomes. |
A state is not always a position
A roll never leaves the state machine. It changes which kind of state the players are in.
| State | What it represents |
|---|
| Position | A relatively stable configuration, such as mount or closed guard. Players can still move, apply pressure and fight for control. Stable does not mean motionless. |
| Transition | A transient state: players are moving, applying forces and actively trying to change the configuration. A pass, sweep or escape is a state in the model, not just an arrow between positions. |
| Submission | A transient attacking state, like a transition, with the possibility of ending the game. An established attack can be finished, defended or changed into something else. Entering it is not the same as getting a tap. |
The arrows connect states. Attempt weights describe which techniques are attempted from a position and role. Outcome probabilities describe where an attempt can lead: success, failure or a counter. A submission finish can reach game-over; an unsuccessful attempt continues the exchange.
Positions have Top / Bottom perspectives. Transitions and submissions have Attacker / Defender perspectives. The role is part of the state, not a label for who is winning. Reference hubs group those perspectives for reading; they are not extra playable states.
The app interprets this model rather than stopping on every intermediate node. Submission attacks have their own choices, including a separate Finish action. The architecture reference separates the authored graph from its display and runtime behavior.
Study it, then try a decision
- Explore from either side. Open a state, read its explanation, watch a teaching clip, or follow a connected technique. Principles and systems highlight related material without starting a roll.
- Drill what you want to retain. Flashcards and per-deck mastery track recall. These are study measures, not a Brazilian jiu-jitsu rank.
- Roll through the model. Pick from the available moves and see where the exchange goes. The question has a timer; choosing a move does not. The simulation is not a prediction of your next sparring round.
- Share a class or game plan. Collect techniques into a list and send a partner one link.
Progress stays in your browser. Sign in only if you want cross-device sync.
The data
| Authored JSON files | Count |
|---|
| Positions | 133 |
| Transitions | 1,025 |
| Submissions | 353 |
These are source-file counts, not the number of playable orbs. Submission files include 63 family hubs, which group occurrences rather than model executable attacks. Source probabilities are authored per ruleset, with distinct gi and no-gi values.
| Read or download | What you get |
|---|
| Latest release | Start here. Two attached assets, graph.json and graph.json.gz: role nodes, attempt weights, outcomes, flashcards and reference material. A snapshot of the graph behind the published site. No account, no API key, no clone. |
content/ | Authored JSON alongside generated Markdown pages. Edit the JSON, not the Markdown. |
graph.json | The same graph at the current revision, in the repository. Around 50 MB, so GitHub will not preview it in the browser; take the release asset or the raw file. |
CITATION.cff | Citation metadata for this project. |
# Authored offers from bottom closed guard, not a runtime-filtered hand.
jq '.positions["closed-guard/bottom"].transitions[] | {technique, attemptProbabilityByRuleset, successRate}' graph.json
# One transient state's performer role, success rates and destinations.
jq '.transitions["kneebar-entry-from-inverted-guard/attacker"] | {fromRole, successRateByRuleset, outcomes}' graph.json
Two findings you can recompute
- Reachability changes with the ruleset. The no-gi walk excludes 124 techniques and 22 position role-nodes. Those roles belong to eleven guard sites: Collar Sleeve, Double Sleeve, Inverted Lasso, Lapel, Lasso, Piranha, Ringworm, Russian Leg Lasso, Spider, Squid and Worm. The walk follows the frame's probabilities from standing and deals only what the game deals: a move is followed from its own position and seat, never from a listing elsewhere. It does not match guard names.
- Attempt weight and success rate answer different questions. Summing the authored no-gi attempt weights across all position-role rows puts Knee Slice Pass first (577 points across 41 rows) and Triangle Setup third (368 across 22). Their emitted attacker success rates are 53.6% and 28%. These sums give each source row equal weight, including unreachable rows; they are not roll frequencies, match statistics or a recommendation ranking.
Count authored files in this checkout:
find content/Positions -name '*.json' | wc -l
find content/Transitions -name '*.json' | wc -l
find content/Submissions -name '*.json' | wc -l
Emit the local payload before checking availability, so the validator checks the shipped wire as well as the source graph:
python3 scripts/regenerate_neural_data.py
npm run validate:availability
Read counts.nogi and excluded.nogi.positions in tests/artifacts/ruleset_availability.json. The ranking uses positions[*].transitions[].attemptProbabilityByRuleset.nogi, grouped by target, excluding null cells; success rates come from transitions["<target>/attacker"].successRate. Hubs carry no attempt rows. The content standards explain why null is not zero.
What the numbers do not prove
Probabilities are authored estimates, checked by schema and graph validators and open to correction by pull request. Calibration and community feedback can change them. A graph that is internally consistent can still be wrong about jiu-jitsu.
State boundaries, technical descriptions, safety, ruleset assumptions and probability estimates need review by a panel of black-belt Brazilian jiu-jitsu practitioners. This README does not claim that validation has happened. Generated content and passing automated checks are not substitutes for it.
Use this alongside coached practice, not as permission to attempt a submission or as a measure of anyone's belt level. If a claim looks wrong, open a correction with the state, role, ruleset and your reasoning.
How it is built
Authored JSON → Jinja2 templates → generated Markdown → static pages
└──────→ graph data + deferred study chunks ────→ canvas app
- Content and pipeline:
content/, templates/ and scripts/. The data, schema and build contracts are documented in Architecture and Content.
- App:
neural/, with the main imperative canvas component in neural/src/app.src.jsx. It loads a compact graph, deck manifest and curriculum, then fetches study content as needed.
- Static build: Quartz, the MIT project under
source/, emits the pages and crawlable fallback beneath the app.
- Delivery: Cloudflare Pages and share-preview Functions in
functions/. Supabase provides optional account sync; PostHog provides analytics.
- Checks: validators in
scripts/, node tests in tests/ and Playwright journeys in e2e/.
Contributing
A correction is more useful than a new feature built on a wrong assumption. Propose one through an issue or a PR against the authored JSON. Include the evidence or technical reasoning that changed your answer.
npm run validate:json
npm run validate:graph
npm run regenerate:build
The full regeneration command can invoke paid AI content enrichment and rewrites generated artifacts. Read CONTRIBUTING.md for prerequisites and the workflow before running it. Never edit generated content/*.md; keep one change per PR and stage files by explicit path. Bot PRs receive the same review as human ones.
For app work, read CLAUDE.md section 6 before editing. It records the implementation traps that are not obvious from a screenshot.
Licence and contact
Source-available, not open source. BJJGraph uses the PolyForm Noncommercial 1.0.0 licence. Noncommercial use is permitted under its terms; commercial use requires separate permission. The licence text is authoritative.
For the corpus or app, open a GitHub issue. For a human conversation, contact Diogo Seca on LinkedIn.
