> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Minimal-Trace Export

> Analytical export of an organisation's discourse graph (sessions, Pattern cards, shared entities & tags, strands) as CSV or JSON, with no audio, transcript text or free-text prose.

## Overview

The minimal-trace export gives org admins a graph of how discussion patterns connect across sessions, for analysis outside Kair Voice (for example Gephi or a spreadsheet). It carries **structure and short labels**: ids, types, counts, scores, enums, timestamps, session dates, topic labels, entity names, tags and strand titles. Audio, transcript text and free-text prose are never included. Entity names, tags and strand titles are exported as stored, without redaction: a full export is a full export.

It is not a GDPR export. Data subject exports are described in [Data Subject Requests](https://docs.kair.is/platform/data-subject-requests). For how the four exports differ by organisation kind, see [Exports](https://docs.kair.is/platform/exports.md).

No new tables. The export is read-only and is built on request.

## Endpoint

```
POST /organisations/:organisation_id/minimal-trace-export
Authorization: session token (fresh sign-in required)

{ "format": "json" | "csv" }
```

| Status | When |
| - | - |
| 200 | `application/json` (`format: json`) or `application/zip` (`format: csv`) |
| 403 | Caller is not an org admin or platform admin; API key or OAuth/MCP token; sign-in older than 10 minutes (`Fresh authentication required`); organisation is personal |
| 404 | Organisation does not exist (only reachable by platform admins) |
| 500 | Loading rows or rendering failed. Details are logged server-side without content |

The UI handles the 403 for a stale sign-in with its step-up modal and retries.

The route is a `POST` so the request is captured by the `audit_events` middleware. No per-route audit logging is added.

## What it contains

Every session in the organisation's workspaces that is not soft-deleted becomes a node, whether or not it has a discourse analysis.

| Node type | Source | Label | Properties |
| - | - | - | - |
| `session` | `session` | `Session YYYY-MM-DD` (UTC date of `created_at`) | `planned_headcount`, `actual_headcount`, `created_at`, `analysed_at`, `discourse_intensity`, `tension`, `consensus_confidence`, `attribution_mode` |
| `pattern_card` | latest `moderator_insights` analysis | card `name` | `structural_type`, `scale`, `stance`, `mention_count`, `confidence`, `translatable`, `capability_link`, `action_link`, `reason_code`, `speaker_count` |
| `divergence` | analysis | `topic` | `intensity`, `unresolved`, `positions_count`, `start_time_seconds` |
| `convergence` | analysis | `topic` | `agreement`, `endorsement_kind`, `consensus_score`, `start_time_seconds` |
| `entity` | `pattern_card_entity_links` | `entity_name` | none. Shared across sessions by normalised name |
| `tag` | `pattern_card_tags` | tag text | none. Shared across sessions by normalised text |
| `strand` | `strands` + current revision | revision `title` | `kind`, `status`, `scope` |

Edges:

| Edge type | From → to | Weight |
| - | - | - |
| `session_has_card` / `session_has_divergence` / `session_has_convergence` | session → item | none |
| `card_mentions_entity` | card → entity | summed `mention_count` |
| `card_tagged` | card → tag | none |
| `divergence_about_card` / `convergence_about_card` | point → card whose name matches the topic | none |
| `strand_appears_in_session` | strand → session | none |
| `strand_relation` | strand → strand, with `relation_type` | none |

Ids are stable and typed: `session:<uuid>`, `card:<session uuid>:<card key>`, `divergence:<session uuid>:<index>`, `convergence:<session uuid>:<index>`, `entity:<key>`, `tag:<key>`, `strand:<uuid>`. Card keys are the normalised card name, as elsewhere in the app.

Inclusion rules:

* Analysis: the newest `moderator_insights` row per session, as the session's discourse-insight endpoint serves it. A row that no longer deserialises is skipped and logged by session id only.
* Strands: only `active` and `provisional` strands of the organisation. `dismissed`, `merged` and `expired` are dropped.
* Strand relations: only `accepted` ones, with both ends in the export.
* Entities, tags, divergences and convergences only appear when their card or session is in the export.

## What is excluded

The output is built field by field from explicit types. A new source column cannot reach the export unless it is added to the builder.

* Audio, transcripts, segments and every excerpt or quote
* Free text: card source context, frame, open question, intention, item text, objections, divergence summaries and positions, convergence summaries, consensus caveats, analysis headline, intervention reason, strand statements and reasons, entity descriptions, practice outputs
* Speaker and device labels. Counts are emitted instead (`speaker_count`, `positions_count`)
* User, actor and API-key ids
* Session titles, metadata and file names
* Email addresses

`metadata.excluded` lists these categories in the export itself.

## Archive layout

**JSON**: one pretty-printed document with `metadata`, `nodes` and `edges`.

**CSV**: a zip containing:

* `nodes.csv`: `Id,Label,node_type,session_id,workspace_id,properties`
* `edges.csv`: `Source,Target,edge_type,Weight,properties`
* `metadata.json`: `export_version` (1), `profile` (`minimal_trace`), `organisation_id`, `exported_at`, `node_counts` and `edge_counts` per type, `excluded`

Headers follow Gephi's import names (`Id`, `Label`, `Source`, `Target`, `Weight`). `properties` is compact JSON.

CSV cells are RFC 4180 quoted. A cell whose first non-space character is `=`, `+`, `-`, `@`, tab or CR is prefixed with a single quote, so spreadsheets show it as text rather than running a formula.

## Access

* Org admin of the target organisation, or platform admin (`require_org_admin`).
* Session auth only. API keys and OAuth/MCP tokens are rejected.
* Fresh sign-in, at most 10 minutes old (`require_fresh_auth`).
* Only team organisations. Personal organisations return 403.

## Audit

* **`audit_events`**: the request is recorded automatically as a write (actor, method, path, status, hashed IP). No content is written.
* **`audit_trail`**: nothing is written, because no rows change.
* Tables touched: none. No triggers, migrations or new columns.

## Implementation

* Pure builder and CSV writer: `api/crates/core/src/minimal_trace.rs` (unit tests cover exclusions, the session date label, shared entities, divergence matching, strand filtering, CSV escaping and the formula guard).
* Loader and route: `api/crates/api/src/routes/organisation/organisation_routes_export.rs`, mounted from `organisation/mod.rs`.
* The loader runs one query per table, batched with `is_in` over session and strand ids. It does not query per session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.