Notes Guide

Notes are investigation narratives with embedded evidence — the story layer of jinflow.

Concepts

• Notebook: One per tenant. Contains all notes (from YAML) and user entries (from JinDesk).
• Note: A YAML file in notebook/ with a title, author, cells, and metadata. Compiled into the KLS.
• User entry: A cell added directly in JinDesk. Stored in the OPS.
• Cell: An entry within a note or the user section — narrative, view, reference, discussion, or action.

Two Sources, One Page

The notebook page (/{tenant}/notebook) shows content from two sources:

1. KLS notes (top section) — compiled from YAML files during jinflow make. Read-only in JinDesk. Edit the YAML and rebuild to change them.
2. User entries (bottom section, “Your notes”) — created and edited directly in JinDesk. Stored in the tenant’s OPS. No rebuild needed.

If your entries have changed since the last build, a drift banner appears: “Unpublished changes — notes have been modified since the last build.”

JinDesk Editing

Creating entries

Use the toolbar buttons at the top of the “Your notes” section:

Button	Creates
+ Note	A narrative cell (Markdown supported)
+ Discussion	An empty discussion thread
+ Action	A tracked task with assignee

Editing narratives

Hover over a narrative cell to reveal the edit button (top-right). Click to switch to an inline editor. Modify the text and click Save.

Deleting entries

Hover over any cell to reveal the delete button (top-right). Click to remove the cell. This is immediate — no confirmation dialog.

Discussion replies

Click + Add reply at the bottom of a discussion thread. Type your reply and click Reply.

Action status

Click the status badge on an action cell to toggle between proposed and completed.

Adding findings to the notebook

On any finding detail page, click Add to notebook. This creates:

• A reference cell pointing to the signal
• A narrative cell with the finding interpretation (or AI explanation if generated)

Note Files (YAML)

Notes live in the AFS notebook/ directory as YAML files:

afs/notebook/
  nb_io_article_reconciliation.yaml
  nb_zufferey_taxonomy_provenance.yaml

Filename must match the notebook_id inside the YAML.

Cell Types

Type	Purpose	Content
narrative	Free-text observation or analysis	Markdown (tri-lingual)
view	Link to a dimension/findings page	Target page + filters/sort
reference	Link to a signal, thesis, entity, SMEbit	Kind + target ID
discussion	Threaded conversation	Author, date, text per message
action	Tracked task	Status, assignee, description, result

Writing a Note (YAML)

notebook_id: nb_my_investigation
version: "1"
title:
  en: "My Investigation"
  de: "Meine Untersuchung"
author:
  name: "Analyst Name"
  role: "Role"
  date: "2026-03-19"
scope:
  tenant_id: "*"
  time_range: "2024"
status: active
tags: [investigation, material-flow]

cells:
  - id: context
    type: narrative
    content:
      en: |
        ## Context
        This note documents...

  - id: view_top_delta
    type: view
    description:
      en: "Top articles by value delta"
    target:
      page: dimensions
      entity: io_article_reconciliation
      sort: value_delta
      order: desc
      filters:
        - column: year
          value: "2024"

  - id: ref_io_probe
    type: reference
    kind: signal
    target: probe_io_coefficient
    note:
      en: "Monthly I/O coefficient per material"

  - id: action_mapping
    type: action
    status: proposed
    assignee: "Operations"
    description:
      en: "Fill in the ABT→KST mapping"

  - id: discussion
    type: discussion
    thread:
      - author: "Analyst"
        date: "2026-03-19"
        text:
          en: "We should investigate further."

Sharing notes between machines

Notes live in the OPS (Operational Store) — a per-tenant SQLite store, or a Cloudflare D1 in the cloud. Unlike the KLS it is never rebuilt: jin make does not regenerate it, so the way back from a loss is a restore, not a rebuild.

jin ops backup <pack.tenant>      # online backup, safe while in use
jin ops restore <pack.tenant> <dir>   # deliberate — overwrites
jin ops sync <pack.tenant>        # union local ↔ cloud (event-keyed citizens)

jin ops sync unions the citizens where two stores cannot disagree — the navigation journal and run history. It deliberately refuses notes, desks and saved views: the same note edited on two machines is a conflict rather than a union, and resolving one is reconcile’s job (not yet built). Until then, move notes with a backup and a restore, or keep a single writer.

Deep Links

Link directly to a note:

/hrcentral.vai/notebook?note=nb_zufferey_taxonomy_provenance

Clicking a note card in the index also updates the URL for sharing.

View Cells from Saved Views

Use the copy-as-YAML button on saved view pills to generate a view cell:

  - id: view_year_2024
    type: view
    description:
      en: "year=2024, sorted by value delta"
    target:
      page: dimensions
      entity: io_article_reconciliation
      params: "f.year=2024&sort=value_delta&order=desc"

Paste into any note file under cells:.