Sense 29 — The Atelier

Sense 29 · Forming · Last touched 2026-08-20

• last_verified: 2026-07-27

Synced from docs/design/sense_29_the_atelier.md in the engine repo — that’s the source; this page is a build-time mirror.

A workshop for the AFS. Intelligent, git-aware, role-gated. The place where craft happens.

Status: proposed (2026-05-06) Lives in: async, slow, structure-output authoring — “the smell is sawdust”

Why

Editing the AFS today happens in a text editor with no domain awareness. The schema lives in contracts/*.json; the editor doesn’t read it. Cross-references (a Thesis citing a Signal that doesn’t exist) only fail when jin make runs. Domain experts who write Subject Matter and Notebooks need terminal proficiency to commit their work. There’s no single place where “a change to the analytical framework” is staged, validated, and tracked — every entry path uses different conventions and surfaces different risks.

The Atelier is that place. A workshop that knows the contracts, knows the cross-references, knows the git story, and respects the role/pass model. It joins CLI + text editor + git as a Studio-mode inhabitant — not a replacement for them, but a higher-leverage option for the people and the work that warrant it.

The five guiding principles

1. The AFS is craft. Editing it is not data entry; it’s authoring an analytical framework that someone else will read, run, and stake a verdict on. The Atelier treats every artifact as a thing being shaped, not a row in a form.
2. Intelligencia is layered, each layer optional. Solo mode can ship lean; richer modes turn on more layers. No layer is load-bearing for the next.
3. Atelier owns the validation, not the gate. The promise is “if you go through the Atelier, everything is validated and tracked.” It is not “you can’t edit any other way.” Power users keep direct git access; the Atelier just makes the safe path easier than the unsafe one.
4. Same API, two shells. Solo (browser, no auth, single-AFS, file://) and embedded (in JinDesk, multi-user, multi-AFS) share one typed API. Different deployments, same contract.
5. Identity & Passes (Sense 18) gates capabilities, not navigation. Anyone can open the Atelier. What they can change depends on their role. Read-only browsing is always permitted.

The five layers of intelligencia

Each layer adds value without requiring the next. Solo mode can ship layers 1–2 and be useful; embedded mode adds 3–5 over time.

Layer	What it adds	Depends on
1. Structural	Render YAMLs in typed forms instead of raw text. A signal looks like a signal, not a 200-line string.	Nothing — pure presentation.
2. Schema validation	Real-time check against contracts/*.json. Errors surface as you type, not after jin make.	Pack contracts mounted alongside AFS.
3. Cross-reference completion	Typing signal_id: shows existing IDs from the AFS index. Renaming an artifact propagates references.	A live AFS index (cheap to build at session start).
4. KLS-grounded preview	Show the SQL the YAML compiles to, the expected row shape, sample rows from the current KLS.	A read-only KLS handle.
5. LLM suggestion	Co-pilot drafts Subject Matter prose, suggests thesis interpretations, flags inconsistencies.	An LLM endpoint + the user’s own Pass.

Artefact taxonomy — who edits what

Not every artefact in the AFS calls for the same shell. The Atelier defaults to human-first for the prose layer (where domain expertise lives) and declarative-first for the structural layer (where mistakes have blast radius). LLM assistance lives on top of the human layer, never replacing it.

Tier	Artefacts	Typical author	Atelier role
Strategic prose	Observation (Sense 15), Verdict explanation/recommendation, Thesis statement + interpretation, Dossier narrative, Notebook	Domain expert	First-class form. Trilingual fields side-by-side. LLM-translate button per locale.
Captured knowledge	Subject Matter — Statement (Level 0) and Check (Level 1)	Domain expert + analyst	First-class form. Provider attribution, anchors to signals/theses surface as autocomplete.
Declarative shape	Signal YAML, Perspective YAML, Lens YAML, Entity YAML, Lineage YAML	Analyst	Form with schema validation. SQL stays in side-by-side editor, not coerced into the form — the YAML carries the metadata, the .sql carries the logic.
Infrastructural	Channel declarations (Sense 31 — The Inlet), pipeline.yml, source-system manifests	Analyst with operator authority	Form with strict schema validation + enum-only dispatch fields. Phase 3+ — not part of Phase 1. Higher blast radius than the analytical tiers; a typo breaks the build, not the chart. See “Auth grows with the tiers” below.
AI-maintained, human-reviewed	i18n translations of any prose field; interpretation parameterisation hints; cross-reference suggestions; vocabulary consistency checks	LLM with human accept	Suggestion panel, not background edits. Every AI write is staged and shown before commit.
Compiled / never edited	build/lenses/*.json, _jinflow_* schema tables, sync manifests, dbt output	Compiler	Not exposed in the Atelier. Read-only diagnostics only.

The split matters for the form-renderer’s priorities: the strategic-prose tier is where most sessions actually spend their time; the declarative tier is where most fields exist. Time spent polishing the prose-tier UX returns more session value than time spent on the declarative-tier form density.

Validation — three tiers, three latencies

Editing is forgiving until a commit lands; the moment of commit is firm. Three tiers, increasing cost, deliberately staggered:

Tier	When	What	Latency	Blocking?
A — Schema	On every keystroke (debounced ~300ms)	Field types, required-fields, enums, regex patterns from contracts/*.json	<100ms	Inline warning only — never blocks typing
B — Integrity	On Save (before commit)	Cross-references resolve (thesis cites a signal that exists), IDs match filename, i18n locales complete for required-multilingual fields, YAML re-parses to the same object after dump → load round-trip	<1s	Blocks the commit — save button disabled with a clear “fix N issues” surface
C — Compile	Post-commit, async background	Run the artefact’s existing compiler (signalcompile.py, thesiscompile.py, etc.) against the new artefact in isolation	~5s per artefact	Surfaces as a passive badge on the artefact card: ✓ / ⚠ / ✗. Does NOT revert the commit.

What the Atelier deliberately does NOT do at save-time:

• Run jinflow make (minutes; that’s a separate, explicit action)
• Touch the KLS or any tenant data
• Execute the signal/check SQL against real data (Layer 4’s KLS-preview is opt-in per session, not save-time)

The Tier C passive badge is the bridge: when a Subject Matter Check has a syntactically valid SQL block that fails to compile against the gold model, the badge turns ⚠ and links back into the Atelier — the author sees the failure without it derailing their save flow.

User support — for the infrequent expert

The Atelier is operated mostly by people whose primary job is something else (clinician, dean, compliance officer, domain expert at a partner organisation) and who open it maybe once a quarter. The UX is calibrated for that audience, not for daily editors.

Five principles:

1. Plain-language everything. No CLI terms in surface UI. “Save and commit” reads as “Save”; “branch” reads as “version”; “push to remote” reads as “share with the team” — with the underlying git terminology revealed on hover for the curious. The translation between domain-speak and engineering-speak is the Atelier’s job, not the user’s.

2. Examples in place, not in a manual. Every field has a “Show example” affordance that pulls a real value from another artefact in the same AFS — not a fabricated demo. A first-time Subject Matter author writing the why field clicks to see how three real entries phrased theirs, then types their own. The pattern lives in the data, not in documentation that drifts.

3. First-touch tour, not first-launch tour. Generic onboarding (here’s the menu, here’s the save button) is forgettable two days later. Instead, when the user first opens an artefact type they’ve never touched, a contextual two-step coach surfaces inline: “you’re editing a Thesis — here’s the part that goes to C-level, here’s the evidence chain, save when you’re ready.” Tied to artefact type, not session.

4. Undo is git. The most common “oh no” is editing the wrong field or the wrong tenant. Because save=commit, every change is recoverable: the Atelier surfaces the last five commits per artefact with a one-click revert button. No separate undo stack to lose.

5. Vocabulary stability. The Atelier shows the display vocabulary (Subject Matter, Statement, Dossier, Observation, Thesis, Verdict) consistently — never the internal slugs (smebit, bitbundle, fiftycents) which leak in some current JinDesk surfaces. The same word means the same thing everywhere a user looks, including error messages, save toasts, and breadcrumbs.

The bar to clear: a domain expert who hasn’t opened the Atelier in three months should sit down, find the right artefact, edit it, see it land in the AFS history, and not have asked a developer a single question along the way.

Git as the spine

The Atelier owns the git interaction:

• Save = commit. No “draft” state that lives outside git. Long sessions can be squashed on close, but the canonical event is a commit.
• Branch awareness. Every session opens against a branch. Switching branches discards in-progress edits with a confirm dialog.
• Conflict resolution surfaces. When jin afs pull would conflict, the Atelier shows the conflict in its native form (artifact-by-artifact, not text-by-text) and offers a side-by-side resolver.
• jin afs push is the export verb. The Atelier delegates push to the existing CLI mechanics rather than reimplementing them.

Who commits — the Scribe (Sense 38)

The Atelier’s writer answers “may this user save?” through the role/pass model below — but “who carries the save across the git boundary?” is a separate axis. Sense 38 (The Scribe) names it.

On a solo laptop the question collapses: the user is the deployment, their git config is the Scribe, no ceremony introduced. The moment a second user enters the picture — a Reader leaving a comment on a Bell ring via a proxy tunnel, a CFO authorising a save through cloud-Atelier, a webhook-triggered commit from action-cell side effects — the Scribe identity must diverge from the actor identity. The actor is recorded in the YAML body (actor: sarah); the Scribe is what git logs (Atelier <atelier@<tenant>>).

Practically: the current atelier_writer.ts uses local git config for both author and committer. That’s correct for the bootstrap (local-laptop, owner-as-everyone) state and structurally insufficient the moment the cloud-Atelier ships. The fix is to read a Scribe identity from afs/jinflow.yml and fall back to git config when none is declared — see Sense 38 for the configuration shape and the rationale.

Role/Pass model (Sense 18 link)

Edit access scopes per artifact type per role:

• Apprentice — edits Notebooks and Subject Matter; reads everything else.
• Author — edits all analytical artifacts (strategic prose, captured knowledge, declarative shape); can run jin afs push.
• Operator — Author + edits infrastructural artifacts (channel declarations, pipeline.yml). Distinct from Author because the blast radius differs: a broken analysis is a wrong chart; a broken channel is a stopped pipeline.
• Steward (Sense 24) — can edit pack-level artifacts when an alignment event opens that lane.

Every edit produces an audit row through Sense 21 (The Heartbeat). Identity is recorded; intent (the commit message) is recorded; outcome (the commit SHA) is recorded.

Auth grows with the tiers

Each new artefact tier the Atelier learns to edit adds at least one capability and possibly a role to the matrix. The progression is deliberate, not free:

Phase	Artefacts	Roles touching them	Capabilities introduced
1 (proven)	Subject Matter	Apprentice, Author	edit:smebit
2 (strategic prose)	Observation, Verdict, Thesis, Dossier, Notebook	Apprentice (Notes only), Author	edit:observation, edit:verdict, edit:thesis, edit:dossier, edit:notebook
3 (declarative analytics)	Signal, Perspective, Lens, Entity, Lineage YAML	Author	edit:signal, edit:perspective, edit:lens, edit:entity, edit:lineage
4 (infrastructural — Sense 31)	Channel declarations, pipeline.yml	Operator (new)	edit:channel, edit:pipeline

The infrastructural tier is the first that genuinely needs a role distinct from Author. Until then, the matrix is “everyone can read, fewer can write the strategic stuff.” After Phase 4, it’s “and infrastructural changes are a separate, narrower lane” — because the people who write Subject Matter are usually not the people who configure SAP exports, and an honest auth model says so out loud.

Two invariants that keep this from becoming bureaucracy:

• Capabilities are additive, never deductive. A role is a set of grants. The Atelier never invents a deny:* ladder on top.
• Read is always allowed. Anyone with the Atelier open can read every artefact in scope. The matrix only governs writes. This keeps the tool legible to people who are exploring the framework, not just changing it.

Solo vs embedded

	Solo	Embedded
Shell	SvelteKit standalone, served by jin atelier	Panel inside JinDesk, served alongside KLS routes
Auth	None — single user, single AFS	Identity & Passes
Multi-AFS	One AFS per session	Tenant switcher
LLM	User’s own key	Org-managed Pass
Use case	Solo editing, local-only sessions, offline work	Team editing, governed change, multi-tenant ops

Same component tree. Different shells. Same typed API behind both.

Phase 1 — first cut

Smallest end-to-end slice that proves the spine.

• One artifact type only: Subject Matter (small schema, frequent edits, low blast radius).
• Layers 1 + 2: structural form + schema validation.
• Solo mode only.
• Save = git commit -m "atelier: <smebit_id>".
• No cross-ref completion, no KLS preview, no LLM, no Identity & Passes.

If a non-engineering domain expert can edit a SMEbit YAML safely without touching a terminal — and the resulting commit lands cleanly in the AFS history alongside jinflow make: build receipts — the spine is real and subsequent layers can land iteratively.

What the Atelier is not

• Not a replacement for the text editor. Power users editing 40 signal YAMLs in a refactor will reach for VSCode + grep, not a form-based UI. The Atelier doesn’t try to compete on bulk operations.
• Not a CMS. It doesn’t host content, doesn’t render previews of websites, doesn’t manage assets. It edits AFS YAMLs.
• Not a workflow engine. It doesn’t enforce review chains or approval gates. It can log who changed what (Heartbeat), but the policy layer is the role/pass model, not a state machine.

How this manifests in jinflow

The Atelier is JinDesk’s writable surface for AFS artefacts. Six edit surfaces are live: signals, theses, verdicts, perspectives, Subject Matter entries, and Dossiers. Each one knows its YAML schema, validates against the pack contract, and routes the save through the Scribe (Sense 38) so every commit carries proper attribution. The Signal Builder is the first-class authoring path; the others edit existing artefacts in place.

• In the app: Atelier landing · Edit signals · Edit theses · Edit verdicts · Signal Builder
• Writes to: tenant AFS, via the Scribe boundary — never bypasses git
• Reads from: KLS (the current built state) + AFS (the current source of truth)

Status: embedded mode shipped (in JinDesk, with the Sense 25 role/pass model gating capability). Solo mode (browser-only, file://, single-AFS) is forming — same API, different shell.

Open questions for later phases

• Multi-cursor sessions — when two Apprentices edit the same SMEbit, optimistic concurrency or pessimistic lock? (Probably optimistic with a conflict surface.)
• Pack template drift detection — should the Atelier surface “this artifact differs from the pack template” the way jin afs update does today? Probably yes, as a passive indicator, not a blocker.
• AI agency level — does the LLM ever commit on its own, or only suggest? Suggest-only for v1; revisit when the audit trail and capability gating are mature.

Related

• The jinflow — the five names. The Atelier shapes Strategy, Expertise, and the rules behind Analysis.
• Sense 18 — The Ledger — Identity & Passes.
• Sense 21 — The Heartbeat — audit trail.
• Sense 24 — The Steward — pack-level alignment.
• Sense 38 — The Scribe — who commits the save once the Atelier has authorised it. Composes with the role/pass model above.

---

Numerical neighbors: ← Sense 28: The Direct Line — Data Skips the Middle · Sense 30: The Wire — The Outward Contract →