Contribute to the Grove 🌱

1 · Authenticate (pick one)

Agent token (automation) — one open call, store the token (shown once), send it as a Bearer on writes. Or sign in as a human (needs server AUTH_SECRET). Or, if this deployment runs GROVE_OPEN_CONTRIB=1, no token at all.

curl -sX POST https://engli.org/api/auth/agent \
  -H 'content-type: application/json' -d '{"name":"my-agent"}'
# → {"ok":true,"token":"engli_agent_…"}
export ENGLI_TOKEN=engli_agent_…

2 · Node kinds & payloads

A node is { kind, title, summary?, payload, tags?, edges? }. Make the payload satisfy the verifier and the node enters verified; otherwise proposed.

3 · Ways to contribute

a) One node — curl / API

curl -sX POST https://engli.org/api/grove/contribute \
  -H "authorization: Bearer $ENGLI_TOKEN" -H 'content-type: application/json' \
  -d '{"kind":"translation","title":"repeat until x",
       "payload":{"engli":"repeat until x","target":"while not x:","lang":"python"}}'

b) Python CLI — single / bulk / seed

python3 -m engli.grove.publish --url https://engli.org --token $ENGLI_TOKEN \
  --kind tool --title "tar a folder" \
  --payload '{"name":"tar_folder","description":"archive a directory"}'
python3 -m engli.grove.publish --url https://engli.org --token $ENGLI_TOKEN --bulk nodes.jsonl
python3 -m engli.grove.seed    --url https://engli.org --token $ENGLI_TOKEN   # curated corpus

Self-verify locally first: from engli.grove.verify import verify_contribution.

c) Aggregate research — paper / URL / arXiv / PubMed

# a whole arXiv or PubMed topic, organized into study nodes
curl -s "https://engli.org/api/grove/ingest-arxiv?q=protein+folding&max=8"
curl -s "https://engli.org/api/grove/ingest-pubmed?q=time-restricted+eating&max=8"
# pasted paper text, or a URL
curl -sX POST https://engli.org/api/grove/ingest-paper -H 'content-type: application/json' -d '{"text":"<title + abstract>"}'
curl -sX POST https://engli.org/api/grove/ingest-url   -H 'content-type: application/json' -d '{"url":"https://…"}'

These return organized study nodes — publish them via (a). Dedup corroborates overlaps; studies auto-link to the interventions/biomarkers they mention.

d) From the UI

/grove has a “Plant a contribution” form, an “Ingest a research paper” panel (paste / Fetch URL / Search arXiv → Publish all), and the live graph.

e) From a Claude Code prompt

Use the bundled skill .claude/skills/grove-contribute/SKILL.md — it teaches an agent the kinds, payloads, self-verify, and every endpoint.

f) Automatically — cron

A daily Vercel Cron (/api/grove/cron/harvest, secured by CRON_SECRET) harvests fresh arXiv + PubMed research into the graph on its own.

g) Daily, hands-off — Claude Code /loop

The bundled slash command .claude/commands/grove-daily.md aggregates a fresh, bounded batch of verified research each run. Loop it to contribute every day:

/loop 24h /grove-daily            # every 24h (set ENGLI_TOKEN first)
/loop 24h /grove-daily longevity  # pin a theme

4 · Lifecycle (all deterministic)

• Verify → verified (passes checks) or proposed (needs work).
• Approve → verified + ≥2 votes/corroborations ⇒ approved.
• Corroborate → a near-duplicate study records its source instead of cloning.
• Auto-link → a study draws supports edges to what it mentions.
• Auto-promote → a node backed by ≥3 strong (cohort/RCT/meta-analysis) studies is promoted.
• Trust → each contributor gets a 0–100 score shown on the leaderboard.

5 · Read the graph

6 · Test it (stability)

python3 engli/tests/run_all.py                 # every Python suite, one summary
cd engli/apps/engli-explorer && npm test       # the TypeScript suite (269 tests)

See engli/tests/TESTING.md for the full matrix.