Collaboration Guide

jinflow uses git for collaboration. Every tenant AFS is a git repository from birth. Teams share work through GitHub (or any git remote).

Three rooms, three collaboration modes

Collaboration in jinflow happens in three distinct modes — the Studio, the Salon, and the Lab — each with its own protocol.

• Studio (build): git is the protocol. Two authors collaborate through branches, pull requests, and jinflow afs push/pull. Asynchronous. Conflicts are structural and resolved with merge tools.
• Lab (test): the KLS is the protocol. Shared, read-only. Best experienced shoulder-to-shoulder or via a P2P2P session with a remote expert.
• Salon (meet): the URL is the protocol. P2P2P was built for the Salon — the data owner starts a proxy, viewers click the link, everyone sees the same live data. When the meeting ends, Ctrl+C unplugs everything.

This guide covers the Studio mode (git-based). For the Lab and Salon modes, see Studio / Salon / Lab.

Two Ways to Start

1. New Tenant (First Analyst)

Create a tenant from a domain pack, connect to GitHub, push:

# Create from pack
jinflow init --pack millesime --tenant szo

# Connect to GitHub (create the repo on GitHub first)
jinflow afs remote https://github.com/org/afs-millesime-domaine_zufferey.git

# Push initial state
jinflow afs push -m "initial setup"

2. Join Existing Tenant (Second Analyst)

Clone the AFS from GitHub — no pack needed:

# Clone from GitHub
jinflow init --clone https://github.com/org/afs-millesime-domaine_zufferey.git

# Sync data and build
jinflow make --tenant millesime.domaine_zufferey --sync --clean

This creates the full tenant layout (raw/, build/, store/) around the cloned AFS. The pack is not needed — the AFS IS the analytical framework.

Daily Workflow

# Start of day: pull team changes
jinflow afs pull

# Work: edit signals, theses, notes
# Build and explore
jinflow make
jinflow explore

# End of day: push your changes
jinflow afs push -m "added io_coefficient signal"

AFS Commands

jinflow afs remote                    # show current remote
jinflow afs remote <url>              # set remote (add or update)
jinflow afs status                    # show branch, tags, changes
jinflow afs log                       # build logbook (git log)
jinflow afs log -n 10                 # last 10 entries
jinflow afs pull                      # pull from remote (fast-forward only)
jinflow afs push                      # commit all changes + push
jinflow afs push -m "message"         # with custom commit message

What Gets Versioned

The AFS (afs/) is the git repo. It contains:

Content	Versioned	Notes
Signals, theses, verdicts	Yes	The analytical instruments
SMEbits, BitBundles	Yes	Expert knowledge
Notebooks	Yes	Investigation notes
Entities, lineage, contracts	Yes	Schema definitions
dbt macros, seeds, tests	Yes	Data transformation logic
Models (bronze, silver, gold)	Yes	SQL source models
jinflow.yml	Yes	Pack config
tenant/ (config, logo, seeds)	Yes	Tenant-specific content

What is NOT in git (lives alongside the AFS):

Content	Location	Notes
Raw CSVs	raw/	Immutable source data from DLZ
Build artifacts	build/	Compiled SQL, enriched CSVs (regenerable)
KLS + SIS	store/	Built databases (regenerable via make)

Auto-Commits

jinflow make auto-commits a structured one-liner after each build:

jinflow make: ok | clean | 34/0/1 | v0.7.9 | darwin | mig | millesime.domaine_zufferey | 12.3s

jinflow afs update --do-it auto-commits after syncing pack content.

These auto-commits create a build logbook visible via jinflow afs log.

Packs

Domain packs are independent git repos (e.g., jinflow-pack-millesime). They’re cloned manually:

git clone https://github.com/jinflow-io/jinflow-pack-millesime.git

Configure the pack root so jinflow can find them:

jinflow us --pack-root ~/jinflow-packs

Pack changes flow into tenant AFS via jinflow afs update --do-it.

Conflict Resolution

jinflow afs update uses three-way merge (SHA-256 manifest):

• Only pack changed → safe update (auto-applied)
• Only tenant changed → preserved (your customization wins)
• Both changed → conflict (NOT overwritten, flagged for manual resolution)
• Force mode → --force makes pack win on conflicts

jinflow afs pull uses fast-forward only. If local and remote diverge, it tells you to resolve manually with git pull --rebase.