### Local Development Quick Start

Source: https://github.com/refactoringhq/tolaria/blob/main/README.md

Commands to install dependencies and start the development server for Tolaria.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Create Getting Started Vault with Explicit Target Path

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/adr/0046-starter-vault-cloned-from-github.md

This function creates the getting started vault by cloning a public repository to a user-specified target path. It replaces the previous method that defaulted to a specific directory.

```rust
async fn create_getting_started_vault(target_path: &Path) -> Result<(), anyhow::Error> {
    let repo_url = LAPUTA_GETTING_STARTED_REPO_URL;
    clone_public_repo(target_path, repo_url).await
}
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/GETTING-STARTED.md

Install project dependencies and run the development server locally. Use `pnpm dev` for a browser-based version or `pnpm tauri dev` for the full Tauri application.

```bash
# Install dependencies
pnpm install

# Run in browser (no Rust needed — uses mock data)
pnpm dev
# Open http://localhost:5173

# Run with Tauri (full app, requires Rust)
pnpm tauri dev
```

--------------------------------

### Install Linux System Dependencies (Fedora)

Source: https://github.com/refactoringhq/tolaria/blob/main/README.md

Installs necessary system packages for Tauri 2 on Fedora 38+.

```bash
sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file \
  libappindicator-gtk3-devel librsvg2-devel
```

--------------------------------

### Spreadsheet File Structure Example

Source: https://github.com/refactoringhq/tolaria/blob/main/src-tauri/resources/agent-docs/pages/reference/spreadsheet-format.md

This example demonstrates the structure of a spreadsheet note, including YAML frontmatter with display and sheet-specific metadata, followed by a CSV-like body containing data and formulas.

```markdown
---
type: Project
_display: sheet
tags:
  - planning
_sheet:
  show_grid_lines: true
  frozen_rows: 1
  frozen_columns: 1
  columns:
    A:
      width: 180
  rows:
    "1":
      height: 32
  cells:
    E6:
      num_fmt: "0.00%"
      bold: true
---
Metric,January,February,March,Q1 Total
Subscriptions,1200,1350,1500,=SUM(B2:D2)
Expenses,650,700,760,=SUM(B3:D3)
Net,=B2-B3,=C2-C3,=D2-D3,=SUM(B4:D4)
Growth,,=(C4-B4)/B4,=(D4-C4)/C4,=(E4-B4)/B4
```

--------------------------------

### Install Linux System Dependencies (Debian/Ubuntu)

Source: https://github.com/refactoringhq/tolaria/blob/main/README.md

Installs necessary system packages for Tauri 2 on Debian or Ubuntu (22.04+).

```bash
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev \
  libsoup-3.0-dev patchelf
```

--------------------------------

### Example Vault File Structure

Source: https://github.com/refactoringhq/tolaria/blob/main/site/reference/file-layout.md

Illustrates a typical vault organization with notes, research, attachments, and special folders.

```txt
my-vault/
  project-alpha.md
  weekly-review.md
  research/
    source-notes.md
  attachments/
    diagram.png
    source.pdf
  project.md
  person.md
  views/
    active-projects.yml
```

--------------------------------

### Install Linux System Dependencies (Arch/Manjaro)

Source: https://github.com/refactoringhq/tolaria/blob/main/README.md

Installs necessary system packages for Tauri 2 on Arch Linux or Manjaro.

```bash
sudo pacman -S --needed webkit2gtk-4.1 base-devel curl wget file openssl \
  appmenu-gtk-module libappindicator-gtk3 librsvg
```

--------------------------------

### Build Linux AppImage and Installers

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/GETTING-STARTED.md

Builds the application for Linux, creating AppImage, deb, and rpm packages using pnpm and Tauri.

```bash
pnpm tauri build --target x86_64-unknown-linux-gnu --bundles deb,rpm,appimage
```

--------------------------------

### Sheet Node Frontmatter and Body Example

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/adr/0134-sheet-nodes-with-plain-text-workbook-storage.md

This example shows the frontmatter configuration for a sheet node, including display settings and sheet-specific presentation metadata, followed by the CSV-like plain text content of the sheet.

```yaml
---
type: Project
_display: sheet
_sheet:
  frozen_rows: 1
  frozen_columns: 1
  columns:
    B:
      width: 180
  cells:
    C6:
      num_fmt: "0.00%"
      bold: true
      font_size: 15
      border_top: "thin #ff0000"
---
Metric,January,February
Revenue,1200,=B2*1.1
```

--------------------------------

### Example Vault Structure

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/ABSTRACTIONS.md

Illustrates the flat file structure of the vault where notes are stored at the root and their types are defined in the frontmatter.

```markdown
```
~/Laputa/
├── my-project.md          ← type: Project (in frontmatter)
├── weekly-review.md       ← type: Procedure
├── john-doe.md            ← type: Person
├── some-topic.md          ← type: Topic
├── AGENTS.md              ← canonical Tolaria AI guidance
├── CLAUDE.md              ← compatibility shim pointing at AGENTS.md
├── GEMINI.md              ← optional Antigravity/Gemini shim pointing at AGENTS.md
├── project.md             ← type: Type (definition document)
├── person.md              ← type: Type (definition document)
├── ...
```
```

--------------------------------

### Startup Sequence Diagram

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

Illustrates the sequence of events during application startup, from Tauri initialization to note rendering.

```mermaid
sequenceDiagram
    participant T as Tauri (Rust)
    participant A as App.tsx
    participant VL as useVaultLoader
    participant MCP as MCP Server
    participant U as User

    T->>T: apply Linux WebKit env safeguards<br/>(Wayland/AppImage)
    T->>T: start background legacy vault housekeeping<br/>(does not block setup)
    T->>MCP: start background initial ws-bridge sync<br/>(if active vault exists)
    T->>A: App mounts

    A->>A: useOnboarding — vault exists?
    alt Vault missing
        A-->>U: WelcomeScreen
    else Vault found
        A->>VL: useVaultLoader fires
        VL->>T: invoke('reload_vault') → allow requested vault roots in asset scope + scan_vault_cached()
        T-->>VL: VaultEntry[]
        VL->>T: invoke('get_modified_files')
        alt Runtime vault path disappears
            VL->>T: invoke('check_vault_exists')
            VL-->>A: unavailable vault path + cleared stale state
            A-->>U: WelcomeScreen (vault missing)
        end
        A->>T: useMcpStatus — check explicit MCP setup state
        A->>T: sync_mcp_bridge_vault(selected path)
        VL-->>A: entries ready
    end

    U->>A: clicks note in NoteList
    A->>T: invoke('get_note_content')
    T-->>A: raw markdown
    A->>A: resolveBlocksForTarget(path, raw markdown)
    alt tab cache or parsed-block cache hit
        A->>A: reuse exact-source BlockNote blocks
    else large common Markdown
        A->>A: direct Markdown-to-block parser
    else unsupported Markdown or cold small note
        A->>A: tryParseMarkdownToBlocks()
    end
    A->>A: inject wikilinks, math, and durable schema blocks
    A-->>U: Editor renders note
```

--------------------------------

### Install Tolaria via Homebrew

Source: https://github.com/refactoringhq/tolaria/blob/main/README.md

Use this command to install Tolaria on macOS using Homebrew.

```batch
brew install --cask tolaria
```

--------------------------------

### YAML Frontmatter Example

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/ABSTRACTIONS.md

Demonstrates standard YAML frontmatter with various data types including strings, lists, and wikilinks. Ensure frontmatter is enclosed by '---' delimiters.

```yaml
---
title: Write Weekly Essays
type: Procedure
status: Active
belongs_to:
  - "[[grow-newsletter]]"
related_to:
  - "[[writing]]"
alias:
  - Weekly Writing
---

```

--------------------------------

### Check Claude Code Agent Installation

Source: https://github.com/refactoringhq/tolaria/blob/main/site/troubleshooting/ai-agent-not-found.md

Run this command directly in your terminal to verify if the Claude Code agent is installed and accessible.

```bash
claude --version
```

--------------------------------

### Run Native App QA Commands

Source: https://github.com/refactoringhq/tolaria/blob/main/AGENTS.md

Starts the Tauri development server, waits for it to be ready, and then executes scripts for focusing the application and taking a screenshot. This is used for native application quality assurance.

```bash
pnpm tauri dev &
sleep 10
bash ~/.openclaw/skills/tolaria-qa/scripts/focus-app.sh laputa
bash ~/.openclaw/skills/tolaria-qa/scripts/screenshot.sh /tmp/qa-native.png
```

--------------------------------

### Example Mermaid Markdown Block

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/adr/0088-markdown-durable-mermaid-diagrams.md

This is an example of how a Mermaid diagram is represented within a Markdown file using fenced code blocks.

```markdown
```mermaid
graph TD
    A[Start] --> B{Choose an option};
    B -->|Option 1| C[Option 1];
    B -->|Option 2| D[Option 2];
```
```

--------------------------------

### Run Unit Tests with Coverage

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/GETTING-STARTED.md

Execute unit tests and generate a code coverage report. The build will fail if coverage is below 70%.

```bash
# Unit tests with coverage (must pass ≥70%)
pnpm test:coverage
```

--------------------------------

### Note Anatomy Example

Source: https://github.com/refactoringhq/tolaria/blob/main/site/concepts/notes.md

Illustrates the structure of a Tolaria note, including YAML frontmatter and the main H1 title.

```markdown
---
type: Project
status: Active
belongs_to:
  - "[[workspace]]"
---

# Launch Documentation

Draft the public Tolaria docs and keep them close to code changes.
```

--------------------------------

### Linux AppImage Packaging Note

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

This note describes the use of Tauri's stock linuxdeploy AppImage output plugin for Linux packaging. It mentions the availability of local tools for advanced AppRun patching but explains why they are not used in the release process.

```text
Linux AppImage release jobs use Tauri's stock linuxdeploy AppImage output plugin. `scripts/appimage-launcher-tools.mjs` remains available for local experiments with symlink-safe AppRun patching and fcitx module bundling, but release packaging does not pre-seed that shim because linuxdeploy currently exits before sealing the AppImage when the shim replaces the stock output plugin in Tauri's tools cache.
```

--------------------------------

### Telemetry Consent and Initialization Sequence Diagram

Source: https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md

Visualizes the user interaction and system flow for telemetry consent, including initialization of Sentry and PostHog.

```mermaid
sequenceDiagram
    participant User
    participant App
    participant Settings
    participant Sentry
    participant PostHog

    Note over App: First launch or upgrade
    App->>User: TelemetryConsentDialog
    alt Accept
        User->>Settings: telemetry_consent=true, anonymous_id=UUID
        Settings->>Sentry: init(DSN, release, anonymous_id)
        Settings->>PostHog: init(key, anonymous_id)
    else Decline
        User->>Settings: telemetry_consent=false
        Note over Sentry,PostHog: Zero network requests
    end

    Note over App: Settings panel toggle change
    User->>Settings: crash_reporting_enabled=false
    Settings->>Sentry: teardown()
    Settings->>App: reinit_telemetry (Tauri cmd)
```