lowlightstudio/the-lineage

THE LINEAGE

A photograph goes in. The skill measures ten traits on the user's machine, reads which decade those traits belong to, and builds the photo's family tree: one look per decade on the trunk from the 1930s to the 2020s, two more beside it as branches, every one a named film, cinematographer, photographer, campaign or process with the reason it belongs. Then it studies the trunk's direction and grows a 2027 branch in the place where the library has no look at all: a name, a recipe, what it inherits from whom, and the proof that it is a gap ("None of the 107 looks is this warm and this grainy at once"). That gap sentence is the signature: it is what makes the branch a look nobody has made yet, not a guess.

Everything up to the branch is local arithmetic and costs nothing. The only thing that generates is the final re-light of the user's own photo into that branch, and it runs on the user's Higgsfield account after they say yes.

Install

bash install.sh              # the skill, your studio folder, a check of the optional tools
bash install.sh --higgsfield # also the Higgsfield CLI + MCP, to generate on your own account

Standard library Python only. JPEG and HEIC are opened through sips (macOS) or ffmpeg; PNG needs nothing.

How to run it

When the user asks for it, Claude:

1. Traces the photo. python3 scripts/lineage.py trace "<photo>" --project "<project>" (any JPG, PNG or HEIC; the project defaults to the-lineage). It prints the four readings (light, grain, framing, colour), the decade with its share of the score and the runner-up, and the trunk from the 1930s to now with what each look shares with the photo. Tell the user the decade first, then the two or three trunk looks that matter most. If it says "a close call", say both decades: that is the honest reading.
2. Grows the branch. python3 scripts/lineage.py grow latest --project "<project>". It prints the 2027 branch: its name and statement, the recipe (light, colour, blacks, grain, optics, format), what it inherits and from which look, and the gap. If the user wants another option, --seed 1 (2, 3…) finds another gap with the same rules.
3. Exports it. python3 scripts/lineage.py export latest --project "<project>" writes trees/<id>.svg (a printable poster: the trunk climbing from 1930, the crimson 2027 bud at the top), trees/<id>.json (every number) and trees/<id>-branch.md (the branch card with the recipe). Open the poster (open <file> on a Mac) and say in one line what to look at first: the bud and the trunk look right under it.
4. Stops and asks before generating. Only if the user wants the branch on their own photo: python3 scripts/lineage.py request latest --project "<project>" writes one image-edit request. Tell them it is one generation and what it costs on their Higgsfield plan, and wait for a yes. Then run it (below) and check with python3 scripts/lineage.py status latest --project "<project>".

Explaining a node: python3 scripts/lineage.py node <id> prints a look in full (why it is in the lineage, what it passes down, people, where to find it, parents). python3 scripts/lineage.py library --decade 1970 lists a decade. Their own references: python3 scripts/lineage.py add --name "..." --year 1994 --why "..." --image ref.jpg measures the image and adds the look to their lineage for every tree after that (references are global to the machine, not per project; --project is accepted and ignored).

Try it with the bundled example (nothing spent): python3 scripts/lineage.py example --project demo (or --photo pool for the second still). To check it works on this machine: python3 scripts/selftest.py.

How to judge the result

• Warn about weak ground. Without people, a visible light source or studio light the meter has little to hold on to: matches under 30 percent across the trunk mean the photo is a poor fit, so say it before the user reads the tree as history.

• The decade is a reading, not a verdict. A share above 25 percent with a clear gap to the runner-up is a firm reading; under 5 points apart is a close call and both decades are fair. Re-compressing a photo changes its grain and can move it.

• A trunk look earns its place when it shares two distinctive traits with the photo (the shares line), not just a colour. A match above 50 percent is close kin; under 30 percent the decade simply had nothing nearer, so say so.

• A branch is good when its gap sentence names a pair of strong traits no look in the library has together, its nearest existing look is at 70 percent or less, and it still keeps the photo's frame. Refuse a branch whose recipe contradicts itself on film (split toning on black and white): grow another seed.

• Solid lines are documented influence; dotted lines are kinship of traits. Never present a dotted line as history.

• The local numbers are arithmetic you can check in the tree JSON; references/method.md explains every one and its limits. library/reading-card.md is the same reading done by eye.

Generating on the user's Higgsfield account

Nothing in this skill generates by itself. request writes ~/LOWLIGHT STUDIO/<project>/requests/<id>.json (prompt, the user's photo as reference, aspect ratio). Claude runs it through the Higgsfield MCP signed in as the user, then files the result:

python3 scripts/studio_bus.py requests <project>
python3 scripts/studio_bus.py receive <project> <id> <downloaded file>

It is an image edit: the prompt describes only the light, colour and film surface of the branch. Use an edit model the user's plan offers (Nano Banana Pro or a Seedream edit model work well). Before running anything, tell the user how many generations it is and what it will cost on their plan, and wait for a yes. See references/generation.md.

Talks to the other departments

See references/studio.md. It reads taste from The Eye when it exists (likes and refusals nudge where the 2027 branch grows; the branch says taste_used) and publishes lineage: the last twelve trees with their nodes and branch, which The Eye can use as an extra deck. Without other departments it works the same.

Files

Path	What it is
scripts/lineage.py	the motor and its command line: example, trace, grow, export, request, status, trees, library, node, add
scripts/meter.py	the photo meter: ten traits, readouts, palette, format (python3 scripts/meter.py photo.jpg --brief)
scripts/demo_photo.py	draws the two example stills from code (no one's pictures are bundled)
scripts/selftest.py	a dry run with synthetic photos and the examples: python3 scripts/selftest.py
library/lineage.json	the 107 looks, 1930s to 2020s: people, reason, traits, palette, parents
library/examples/	the two example stills, drawn from code (see its README)
library/reading-card.md	the same reading by eye, for a photo on a wall or a phone
references/method.md	how the meter, the decade, the trunk and the gap are computed, and their limits
references/library.md	how a look is written, how to add or correct one
references/generation.md	Higgsfield setup and how the request is built
references/studio.md	the shared bus between THE STUDIO departments

Outputs land in ~/LOWLIGHT STUDIO/<project>/: trees/, requests/, received/.