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).

Two protocols, one team

jinflow’s collaboration runs on two protocols, each suited to a different tempo.

• Async authoring runs on git: two authors collaborate through branches, pull requests, and jinflow afs push/pull. Conflicts are structural and resolved with merge tools.
• Live looking runs on P2P2P: 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 git-based mode.

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 hrcentral --tenant rmc

# Connect to GitHub (create the repo on GitHub first)
jinflow afs remote https://github.com/org/afs-hrcentral-vai.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-hrcentral-vai.git

# Sync data and build
jinflow make --tenant hrcentral.vai --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 desk

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

Inviting People

Tenants are private by default

Any URL whose first path segment names a tenant requires authentication, regardless of which host serves the request. To publish a tenant for anonymous browsing, add it to the public_tenants allow-list in explorer/hosts.yml — that’s the only way data leaves the auth wall.

A new tenant ships locked; a typo in a host config can’t silently expose it. The audit surface is the short allow-list, not the much longer “everything you didn’t think to block.”

A principal is a person (or role, or group) recognised in a tenant. Each principal carries a stable slug (principal_id), a display name, and — for human users — an identity like owner, analyst, or viewer that determines what they can do.

Identity authority lives in Clerk

When you invite someone, the assignment is recorded on their Clerk account in publicMetadata.jinflow.tenants. The AFS holds a materialised view; the KLS bakes the display data. JinDesk reads from both at runtime — auth from Clerk (live), display from KLS (cached). See Sense 46 — The Roster for the full model.

Send an invitation

jinflow invite alice@example.com numetrix.rmc \
  --identity analyst --principal-id alice

This:

1. Writes afs/principals/user_alice.yaml locally
2. Fires a Clerk invitation email to alice@example.com
3. Stamps the returned clerk_invitation_id onto the YAML

Alice receives the email, clicks the magic link, signs up (or signs in if she already has a Clerk account), and lands on the tenant page.

After acceptance — materialise the binding

Once Alice has accepted, run:

jinflow sync-principals numetrix.rmc

This walks Clerk’s accepted invitations for the tenant, matches them to AFS principal YAMLs by clerk_invitation_id, and stamps clerk_user_id + accepted_at onto each one. Idempotent — safe to re-run; --dry-run previews changes without writing.

Propagate

jinflow ship numetrix.rmc --do-it

Rebuilds the KLS with Alice’s pinned binding, syncs to R2, refreshes Fly. Her badge now shows green in JinDesk with her identity.

Removing Someone

jinflow revoke alice numetrix.rmc

This:

1. Calls Clerk to surgically remove publicMetadata.jinflow.tenants["numetrix.rmc"] from Alice’s record — other tenant assignments she holds are preserved
2. Marks her YAML status: archived and stamps left_at (the file stays — analytical authorship references continue to resolve)
3. Refuses self-revocation (you can’t lock yourself out)

After jinflow ship, Alice’s access to the tenant disappears. She keeps her Clerk account; she just no longer belongs to this tenant.

Re-inviting

If you revoke someone and later want them back, re-run jinflow invite with the same email and slug. The archived YAML gets resurrected with fresh active state; a new Clerk invitation is sent. Lifecycle history (previous clerk_user_id, accepted_at, left_at) survives in git.

Consent is a one-way door each direction

A human’s identity record can never be modified by another human without their consent. Not even by the owner of a tenant. The invitation email is the consent surface for enrollment; opt-out (user-initiated removal from a tenant) is the symmetric direction and is the subject of an in-app surface still being designed. See Sense 46 §10 for the full architectural principle.

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 + OPS	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 | hrcentral.vai | 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-hrcentral). They’re cloned manually:

git clone https://github.com/jinflow-io/jinflow-pack-hrcentral.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.