01 / path

From a task to a merge.

Each step says what to click, what you should see and what to do if you don't. New words, like fork or commit, are explained just below ↓

1 · pick it2 minutes

[account]
Make a free GitHub accountAt github.com/signup. That is the only account you need.
[find]
Open the good first issuesThese tasks are small, self-contained and nobody has them yet. Each title starts with a code like [3C]: item C of milestone 3 of the plan.
[take]
Comment /takeIn the comment box at the bottom of the issue. A bot assigns it to you within seconds; no one has to approve it.
[rule]
One at a time/drop hands it back. After 14 quiet days it is freed for someone else, unless your pull request is open.

2 · change ityour pace

[open]
Open a CodespaceClick here and press Create codespace. Wait about a minute while it installs.
[see]
The demo opens in a preview tabThe sample year, with fictional data. It reloads when you save a file.
[edit]
Edit the file the issue namesChange only what the issue asks for. Smaller changes are reviewed faster.
[test]
Run its testIn the terminal at the bottom, for example python -m pytest tests/test_charts.py. The pull request runs everything else.
[save]
Commit and syncOpen Source Control (left bar), write a short message, press Commit, then Sync or Publish Branch. When GitHub offers to create your fork, say yes.

3 · send it1 minute

[open]
Press Compare & pull requestGitHub shows the button on the repository page right after you sync.
[write]
Write two linesCloses #123 with your issue's number, and one line on how you checked it.
[wait]
Your first test run waits for the ownerGitHub holds a newcomer's first run until the owner approves it. It is one click on our side, not a problem with your change.

Pick a task › open a codespace

// prefer your own computer? fork, clone, pip install -r requirements-dev.txt, then python -m lightning --demo (Python 3.11+, opens at http://127.0.0.1:8766) · Codespaces are free within GitHub's monthly allowance; stop yours when you finish

02 / words

Six words, in plain English.

GitHub has its own vocabulary. You only need these six.

01

Issue

One task, written as a page. It says what is wrong, what finished looks like and which file to open.

02

Fork

Your own copy of Lightning on your own GitHub account. You can change it freely; the original stays untouched.

03

Codespace

A code editor that runs in your browser tab, with Lightning already installed. Nothing to set up on your computer.

04

Commit

Saving your change with a short note on what you did. Like a named save point you can come back to.

05

Pull request

A request that says: “here is my change, please add it to Lightning.” We read it, discuss it and, if it is good, merge it.

06

Merge

Your change joins the official version. The task closes itself and your name stays in the history.

03 / after

What happens after you press send.

Nothing is lost and nothing is rushed. This is the order things go in.

01

Checks run

About five minutes. Three of them must pass: tests, dependency-review and analyze.

02

We review

We read the actual change. Questions come as comments on the pull request; answer them there.

03

We finish the paperwork

The changelog line, the docs and the brand-guideline details are ours to do. We push them to your branch, so don't worry about them.

04

Squash merge

Your commits join main as one tidy commit. The issue closes itself and we thank you on it.

04 / stuck

If something looks wrong.

The usual snags, and the way out of each.

common snagsand fixes

[bot]
/take did nothingSomeone may already have it, or it has the taken label. Pick another; the list only shows unassigned ones.
[tab]
The preview tab is blankGive the install another minute. Still blank: open the Ports tab and open port 8766.
[ci]
A check turned redOpen Details next to it, read the last lines, fix the file, commit and sync again. The pull request updates itself.
[quiet]
No answer for daysAIs don't watch GitHub on their own. Leave a comment on the pull request and the owner will ask for a review.

ask firstwhere to ask

[ask]
Ask on the issueEvery question goes on the task, so the next person can read the answer too.
[private]
Security problems stay privateFound a way to reach someone's data? Don't post it. Report it privately.
[chat]
Prefer to chatDiscord is for quick questions. Anything about a task goes back on its issue.

05 / rules

Ground rules.

Short, and the same for everyone.

01

Fictional data only

Never put real financial data, passwords, keys or screenshots of real money in a commit or issue.

02

Nobody pushes to main

Every change, ours included, reaches main through a reviewed pull request.

03

Money lives in Python

Financial calculations stay in the Python services, never in templates or JavaScript.

04

You keep your copyright

By sending a pull request you confirm the work is yours to give, and let the owner use, change and relicense it as part of Lightning, commercially too. The licence is linked at the foot of every page.

// maintainers and AI teammates: who does what, and the gates before a merge ↓

06 / team

Who does what, and how we work.

The repository is the only channel, for people and AI teammates alike. You need none of this for a first pull request: it is how the team keeps one picture.

whopeople and ai

[owner]
The ownerControls the repository settings and merging, and may authorize AI sessions to review and merge through the connected owner account.
[you]
ContributorsYour own account, your fork, your branch. You never need the owner's account or write access.
[ai]
AI teammatesClaude, Codex and Luna work on branches and open pull requests like you, and merge only authorized work, under the same gates.
[never]
Nobody, everPushes straight to main, skips a check, shares the owner's credentials, or publishes a release without the owner.

gatesbefore any merge

[pr]
Pull request onlyNo pushes to main, no force-push, linear history.
[ci]
Three green checkstests, dependency-review and analyze (CodeQL), up to date with main.
[fresh]
The latest version, reviewedNew changes need another look, and every conversation is resolved first.
[path]
Sensitive paths wait for the ownerWorkflows and templates, packaging/, android/, cloudflare/, scripts, tests/conftest.py, AGENTS.md, CLAUDE.md, LICENSE, SECURITY.md and v* release tags.

// how the team works day to day (NOW.md, claims, small steps, hand-off): AGENTS.md ↗ · every term: ai/GLOSSARY.md ↗

07 / product

What Lightning is.

A local-first money app for salaried people in Egypt. It runs on your own computer and phone; your data never has to leave them.

01

The loop

Record or import activity, sort out unclear names and categories, read the analysis, save towards goals.

02

Where vs what

Two questions stay apart: where value is held (CIB, the cash wallet, gold at home) and what is held (EGP, shares, fund units, gold grams, dollars).

03

Three layers

Ledger is real money. Plan is what-if and moves nothing. Report reads both and stores nothing. Every screen says which one a number comes from.

04

Where it ships

Mainly a Windows app with encrypted profiles, plus an Android phone app that hands the ledger to the PC over local Wi-Fi. Arabic (Egyptian) and English throughout.

what you can do todayfeature map

[ledger]
Accounts and transactionsMoney in, out and between accounts; edit, void, restore, search; check an account against the bank.
[import]
CSV and bank SMS importEvery row is reviewed before it posts; duplicates are flagged.
[plan]
Budget and cash planningPlanned, spent and left; safe to spend; bills, loans, reserves and a three-month forecast.
[invest]
Investments and goldTrades, positions, certificates, US stocks in USD, foreign cash, physical gold.
[egypt]
Made for EgyptGam'eya savings circles, zakat estimate, EGX instruments, CIB and NBE SMS.

decisions that holdfor every change

[one]
One name, one calculationEach figure has a single name and a single function. Screens never compute their own.
[local]
Local firstProfile data and backups stay on your device, never in Git. Dummy data only, always.
[quiet]
No silent resultsEvery action shows feedback. A wrong or silent result is worse than an extra click.
[brand]
Strict brand guidelineCSS that differs from the guideline is wrong. Whole EGP on big figures, no coloured headers, no card in a card.

08 / built

How it is built.

The layers, the stack and the posting rule live on the home page: › one process, one file. Here are the four things to know before you open the code.

01

One writer

Only TransactionService writes postings. Everything else builds a validated posting and asks it.

02

Figures registry

lightning/core/figures.py names every figure, its layer and its function. Routes never compute them.

03

Try it

python -m lightning --demo opens the fictional household at http://127.0.0.1:8766, rebuilt on every start.

04

The sample year

tests/test_mohab_year.py lives a whole year through the screens. It is the acceptance test.

Pick it.Change it.Send it.