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 Explorer).
• Note: A YAML file in notebook/ with a title, author, cells, and metadata. Compiled into the KLS.
• User entry: A cell added directly in the Explorer. Stored in the SIS.
• 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 the Explorer. Edit the YAML and rebuild to change them.
2. SIS user entries (bottom section, “Your notes”) — created and edited directly in the Explorer. Stored in the tenant’s SIS file. No rebuild needed.

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

Explorer 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: "Hospital Administration"
    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."

SIS Merge Protocol

Two analysts working independently can merge their SIS notebooks:

# Export events from analyst B's SIS
python3 scripts/sisdb.py --pack millesime --tenant domaine_zufferey --export-events events_b.json

# Import into analyst A's SIS
python3 scripts/sisdb.py --pack millesime --tenant domaine_zufferey --import-events events_b.json

# Or merge directly from another SIS file
python3 scripts/sisdb.py --pack millesime --tenant domaine_zufferey --merge /path/to/other_sis.duckdb

The merge is event-level: union by event_id (globally unique), no conflicts.

Deep Links

Link directly to a note:

/millesime.domaine_zufferey/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:.