# Tsugumi documents

The concept, and a walkthrough with real screens, are in the [README](../index.md).
Start from the document that fits what you want to read. To read with moving figures, there is the [web version](https://gen740.github.io/Tsugumi/) (the same documents). For AI, [llms.txt](https://gen740.github.io/Tsugumi/llms.txt) points to the Markdown of each page.

## Getting started

| Document | Contents |
| --- | --- |
| [features.md](features.md) | Find a feature by task; Card kinds, execution rules and Nix environments |
| [INSTALL.md](install.md) | Installing and updating the desktop app and the `tsugumi` command (Mac, Linux, Windows), and building from source |
| [Usage.md](usage.md) | Canvas tools, running from a Card, chart updates, settings and Agent controls |
| [Demos.md](demos.md) | Choose a demo, try changes and interpret its results |
| [CardGuide.md](cardguide.md) | Build a Card that takes an input and computes, with examples in Python, Bash, C++, R, Julia, Ruby, Go, Rust and C# |
| [RunHistory.md](runhistory.md) | Inspect and compare runs, check runtime packages and open saved artifacts |
| [RemoteExecution.md](remoteexecution.md) | Register a C++ remote worker and run a Code Card on its Linux host |
| [CSharp.md](csharp.md) | C# typed ports, Tasks, NuGet dependencies and the .NET worker lifetime |
| [Visualization.md](visualization.md) | Editable library/shape scaffolds, data parameters, saved figures and reports |
| [Marimo.md](marimo.md) | Committed notebook runs, typed inputs/outputs, saved cell results and the interactive-session boundary |
| [Reports.md](reports.md) | R Markdown and Quarto report Cards, saved HTML and parameterized rendering |
| [WebUI.md](webui.md) | The browser workbench and the `tsugumi` command on Mac, Linux and Windows through WSL2 |
| [BinaryCaches.md](binarycaches.md) | Attic, Cachix and other signed binary caches, private authentication and VM-wide trust |
| [claude-code.md](claude-code.md) | Having Claude Code make and run Cards through the Claude Code plugin, shown in the Web UI |

## The ideas

| Document | Contents |
| --- | --- |
| [Philosophy.md](philosophy.md) | "What to build so that we are not used by AI": the concern behind Tsugumi, its name and its author |
| [Rationale.md](rationale.md) | Why design, implementation and checking share one Workflow: answers to the three reasons for hesitating to hand research to AI (an invisible process, reproducibility, data), the measures that keep trial and error light |
| [Vision.md](vision.md) | Applications: learning research decisions, growing tools, handing work to the next person, and the idea of business automation |
| [Limitations.md](limitations.md) | Checks before relying on a result and links to execution constraints |

## How it works

| Document | Contents |
| --- | --- |
| [Versions.md](versions.md) | Versions: the project's git, each run's version and result (git notes), the version tree and "Start from This Version" |
| [security.md](security.md) | What is and is not protected, the four isolation boundaries (VM, project, Card, RPC), API keys, where data is kept, and known limitations |
| [Protocol.md](protocol.md) | The project RPC requests and notifications (generated from `protocol/tsugumi.fbs`) |
| [Glossary.md](glossary.md) | Card, Draft, Run, invocation, version and other terms |

## Dependencies and distribution

| Document | Contents |
| --- | --- |
| [LicenseAudit.md](licenseaudit.md) | License bundling, VM source distribution and dependency updates |