Operating Modes

Where things live. Where make happens. How AFS, KLS, and SIS flow between actors.

The same product runs in five different topologies. What varies is where each store lives and who runs the build. The code paths converge.

---

The Three Stores

• AFS — the analytical framework. Git repo. All YAML, SQL, contracts, published notes/bookmarks. Written by humans and by make.
• KLS — the knowledge store. DuckDB file. Built from the AFS by make. Read-only once built.
• SIS — the system information store. DuckDB file. Notes, bookmarks, audit, preferences. Mutable. Lives next to the user.

---

One Build Command

make is the single build entrypoint. It gathers inputs, publishes SIS content into the AFS, then builds the KLS — in that order, with every side effect committed to git.

Why the AFS is the build input

make is the security boundary. Whoever controls make controls the analytical truth. Extraction and SIS publishing run inside make but commit their outputs to the AFS before the build reads them, which means:

• Every build is reproducible from the AFS commit it was built on.
• Everything that went into the build is in git — auditable, reversible.
• The post-extraction, post-publish portion of make consumes only the AFS, nothing else.

The AFS commit produced at the end of each build (make: ...) captures the full preparation in its history.

Inspection and flush helpers

jinflow inspect                                # read-only view of the extraction surface
jinflow inspect --contract                     # full pipeline.yml contract (purpose, source, output, expected)
jinflow inspect --check                        # verify SHA-256 hashes without running extraction
jinflow sis flush                              # publish pending SIS notes/bookmarks to AFS (runs anyway inside make)

inspect never runs extraction — for that, use jinflow make. sis flush is the rare case where you want to publish SIS content without rebuilding the KLS.

The key: make knows where the SIS is. In local mode, it reads the file. In cloud mode, it calls JinDesk API. The developer doesn’t care.

---

The Five Modes

Mode 1 — Local

Everything on one machine. The developer’s laptop.

• Who runs make: the developer, on the same machine
• Auth: none (god mode). Git identity from local git config
• Git: local. Push to GitHub when ready

Mode 2 — Proxy (P2P2P)

KLS on the data owner’s machine. JinDesk in the cloud. One SIS in the cloud.

• Who runs make: the data owner, locally
• Auth: stealth (none) or GitHub OAuth for identified sessions
• Git: owner pushes AFS; remote users never touch git
• One SIS: lives in the cloud. Everyone — owner, CFO, analyst — reads and writes the same SIS

See: P2P2P concept page.

Mode 3 — Cloud (R2)

KLS uploaded to R2. JinDesk and SIS in the cloud.

• Who runs make: the developer, locally. Then jinflow cloud sync pushes KLS to R2
• Auth: GitHub OAuth for all cloud users
• Why: always-on, low-latency, shareable via URL. The tradeoff: data leaves the site

Mode 4 — Semi-Cloud

KLS stays local. SIS in the cloud. No KLS upload.

• Who runs make: the developer, locally
• Why: compliance — analytical data can’t leave the site, but user activity (SIS) is fine in the cloud
• Auth: GitHub OAuth for cloud users

Mode 5 — Make-as-a-Service

make runs in the cloud. No local machine needed.

• Who runs make: a cloud service (GitHub Actions, Fly.io Machine, Cloudflare Worker)
• Trigger: git push to AFS, scheduled cron, or manual (jinflow make --remote)
• Auth: GitHub for developers (push triggers build). OAuth for JinDesk users

This is the endgame. The developer never runs make locally. They push AFS changes; the cloud worker runs make (extract + publish + build); JinDesk serves the result.

---

The SIS — Messenger and Memory

The SIS serves two roles:

Role	Content	Retention	Published to AFS?
Memory	Notes, bookmarks	Long-term	Yes (make Phase 1d → YAML)
Memory	Audit trail, acknowledgments, preferences	Long-term	No (SIS-only)
Messenger	Recents (navigation journal)	Short-term, rotated	No (ephemeral)
Messenger	Session state (current filters, scroll)	Session-only	No (ephemeral)

One SIS per tenant. Not local + cloud. One instance, one truth. Location is a deployment decision:

Mode	SIS lives…	Accessed by…
Local	Developer’s machine	JinDesk (localhost)
Proxy / Semi-Cloud / Cloud	Cloud (JinDesk server or R2)	JinDesk (cloud) + make (remote fetch during Phase 1d)
Make-as-a-Service	Cloud	JinDesk + cloud make (direct)

Nobody needs git to create notes. Git is only needed to run make, which publishes SIS content into the AFS before it builds the KLS.

---

Decision Matrix

Factor	Local	Proxy	Cloud	Semi-Cloud	Make-as-Service
Data location	Local	Local	Cloud (R2)	Local (KLS) / Cloud (SIS)	Cloud
Who runs make	Developer	Owner	Developer	Developer	Cloud worker
Operational compliance	✅ Best	✅ Best	❌ KLS in cloud	✅ KLS local	❌ Full cloud
Collaboration	Single user	Multi-user (session)	Multi-user (always on)	Multi-user	Multi-user
Internet required	No	Yes	Yes	Yes	Yes
Git knowledge needed	Author only	Author only	Author only	Author only	Author only
Setup complexity	Trivial	One command	R2 credentials	Proxy + cloud SIS	CI/CD + deploy keys
Viewer login	—	Optional (stealth)	Required	Required	Required

Recommendation: Start with Local (Mode 1) + Proxy (Mode 2) for sensitive data. Move to Cloud (Mode 3) for non-sensitive. Make-as-a-Service (Mode 5) is the long-term vision for scale.

---

The Cut

The cut inside make — between input gathering (Phase 0 extract, Phase 1d SIS publish) and the build proper — is the security boundary.

• The input phases have side effects: they pull from the DLZ, talk to the SIS, write to the AFS, and commit to git.
• The build phases have none: they read the AFS, write the KLS. That’s it.

Everything that feeds the build is in git — auditable, reproducible, reversible. The SIS is the collaboration layer: it doesn’t need git, it doesn’t need make, it’s where people work. Everything else is infrastructure.

---

Related

• Pipeline Overview — the layer-by-layer transformation
• Deploy Guide — how to stand each mode up in practice
• P2P2P concept — deep dive on Mode 2
• Make guide — day-to-day usage