Playbooks

What are playbooks?

A playbook is a Markdown file that contains a structured protocol for diagnosing or fixing a specific IT problem. Think of it as a runbook — a set of expert instructions that tell Noah exactly what to investigate, what tools to use, and what actions to take.

For example, when you tell Noah "my WiFi keeps dropping," it activates the network-diagnostics playbook. That playbook tells Noah to:

1. Check if the WiFi interface is enabled and connected
2. Test DNS resolution and ping the default gateway
3. Look for packet loss and latency patterns
4. Check for conflicting DNS configurations
5. Suggest fixes based on what it finds

Without a playbook, Noah would still try to help — but with one, it follows a proven diagnostic path that covers edge cases and avoids dead ends.

How playbooks work

When you describe a problem to Noah, the following happens behind the scenes:

1. Matching

Noah sees a table of contents listing all available playbooks. Each playbook has a short description, so Noah knows which one is relevant. If your problem matches a playbook, Noah calls the activate_playbook tool to load it.

2. Activation

The full playbook content is loaded into Noah's context. This gives Noah the complete diagnostic protocol or step-by-step procedure. Noah then follows the playbook's instructions, calling system tools to gather data and propose actions.

3. Execution

Noah works through the playbook systematically:

• Diagnostic playbooks guide investigation. Noah runs checks, interprets results, and narrows down the root cause.
• Procedural playbooks have numbered steps. Noah shows progress ("Step 2 of 5: Configure DNS") and asks for approval before making changes.

4. Tracking

Every playbook execution is tracked: which steps completed, what tools were called, how long it took, and whether the issue was resolved. If your device is linked to a fleet, this report is sent to your admin dashboard.

Three sources

Playbooks can come from three different places. Each source has a different purpose and trust level:

All three sources live as .md files in the same directory on disk: knowledge/playbooks/ inside Noah's data folder. Noah loads them all into a single registry at startup, so the AI can use any playbook regardless of where it came from.

Precedence

When multiple sources provide a playbook with the same slug (name), only the highest-precedence version is used. Lower-precedence versions are preserved on disk but shadowed — Noah won't see them.

How shadowing works in practice

Using playbooks

You don't need to do anything special to use playbooks — Noah activates them automatically when relevant. But you can also use them directly:

Automatic activation

Just describe your problem naturally:

"My printer isn't working"
"WiFi keeps disconnecting"
"My Mac is running really slow"
"Help me set up SSH keys"

Noah matches your problem to the right playbook and activates it. You'll see the playbook name in the conversation.

Direct activation

If you know the playbook you want, ask for it directly:

"Run the network-diagnostics playbook"
"Activate printer-repair"
"Start the setup-ssh-key playbook"

Browsing available playbooks

To see what's available, go to the Knowledge tab in the Noah sidebar and look under the playbooks category. Each playbook shows its name, description, and source.

Progress tracking

Procedural playbooks (those with numbered steps) show a progress indicator in the conversation:

Step 2 of 5: Configure DNS servers
━━━━━━━━░░░░░░░░░░  40%

This is managed automatically — Noah advances through steps as it completes each one.

Creating your own playbooks

You can create custom playbooks for any recurring task or procedure specific to your environment. A playbook is just a Markdown file with YAML frontmatter.

Where to put them

Place your .md file in Noah's playbooks directory:

Basic structure

Every playbook needs YAML frontmatter (between --- markers) and a Markdown body:

---
name: my-vpn-setup
description: Set up the company VPN client on a new machine
source: local
platform: all
---

# Company VPN Setup

## When to activate
User needs to connect to the company network remotely,
or is setting up a new machine.

## Prerequisites
- Company email account is already configured
- User has received VPN credentials from IT

## Step 1: Download the VPN client
Download GlobalProtect from https://vpn.example.com/download

## Step 2: Install and configure
Run the installer with default settings.
Set the portal address to `vpn.example.com`.

## Step 3: Test connection
Connect using your company credentials.
Verify you can reach `intranet.example.com`.

## Escalation
If the user gets error code 502, escalate to the
network team — the VPN gateway may need a new cert.

Naming conventions

• The filename (without .md) is the slug: my-vpn-setup.md → slug my-vpn-setup
• The name field in frontmatter should match the slug
• Use lowercase and hyphens: setup-printer-fleet, not Setup_Printer_Fleet
• Keep names descriptive but short — they appear in the knowledge table of contents

Frontmatter reference

The YAML frontmatter block at the top of each playbook controls how Noah discovers, filters, and tracks it.

Minimal example

---
name: reboot-router
description: Guide user through router power cycle
source: local
---

Full example

---
name: network-diagnostics
description: Systematic connectivity troubleshooting for Wi-Fi, DNS, and internet issues
source: bundled
platform: macos
last_reviewed: 2026-03-04
author: noah-team
emoji: 🌐
---

Diagnostic vs. procedural playbooks

Playbooks fall into two categories based on their structure. Noah handles each differently.

Diagnostic playbooks

Designed for investigation. Noah follows a decision tree to narrow down the root cause. These playbooks use ### (h3) headers for their steps and typically include sections like:

• When to activate — What symptoms trigger this playbook
• Key signals — What to look for in the diagnostic data
• Caveats — When the standard approach doesn't apply
• Escalation — When to stop and ask for human help

Diagnostic playbooks do not show step progress in the UI — investigation is non-linear.

Procedural playbooks

Designed for setup tasks and known fixes. They have numbered steps using ## (h2) headers:

## Step 1: Download the installer
## Step 2: Run the installer
## Step 3: Configure settings
## Step 4: Verify installation

Noah shows a progress bar and step label in the conversation. Steps are executed in order, and Noah asks for approval before making system changes.

Step header formats

Noah recognizes these patterns as procedural steps:

## Step 1: Check Environment
## Step 2 — Install Dependencies
## 1. Check Environment
## 2. Install Dependencies

All of these produce the same result: a numbered step with a label shown in the progress UI.

Fleet playbooks

If your device is linked to a Noah Fleet dashboard, your IT admin can push playbooks to your device remotely. This is how organizations distribute standard procedures, compliance checks, and custom workflows.

How fleet delivery works

1. Admin authors a playbook in the fleet dashboard UI.
2. Admin assigns it to a group or individual device.
3. On next checkin (every ~6 hours, or after a health check), your device downloads the assigned playbooks.
4. Files are written to disk as .md files with source: fleet in the frontmatter.
5. Registry reloads and the playbook is immediately available to Noah.

Assignment and cleanup

• When an admin assigns a playbook, it appears on your device at the next checkin.
• When an admin unassigns a playbook, the file is automatically removed from your device at the next checkin.
• Fleet playbooks never overwrite your local (source: local) files. If there's a slug conflict, fleet takes precedence but your file stays on disk.

Fleet playbooks and auto-heal

Fleet playbooks are fully integrated with Noah's auto-heal system. An admin can push a playbook that automatically runs when a specific health check fails — no user intervention needed.

Auto-heal

Noah's auto-heal system connects health monitoring to playbooks. When a health check fails, Noah can automatically run the appropriate playbook to fix it.

How it works

1. Health scanners detect a failing check (e.g., "DNS resolution failed" or "system updates pending").
2. Triage — Noah's AI evaluates the failing checks and picks the best playbook to address them.
3. If auto-heal is ON — Noah creates a session, activates the playbook, and runs it autonomously. Actions that require approval still prompt in the UI.
4. If auto-heal is OFF — Noah sends a notification that a fix is available. You can choose to run it manually.
5. Cooldown — Each check gets a 24-hour cooldown after an attempt, so Noah doesn't retry the same fix repeatedly.

Auto-heal can be toggled in Noah's settings. It's off by default.

Run reports

Every playbook execution (manual, auto-heal, or fleet-dispatched) generates a run report containing:

• Which playbook was run and which version (content hash)
• How it was triggered (user, auto-heal, or fleet dispatch)
• Which health check it was addressing
• Steps completed, tools called, total duration
• Health score before and after
• Whether it succeeded or failed

If your device is fleet-linked, these reports are automatically sent to the admin dashboard for visibility.

Versioning

Every playbook is versioned by its content hash — the first 12 hexadecimal characters of a SHA-256 hash of the file's full content.

# Example content hash
a1b2c3d4e5f6

This hash is:

• Computed automatically when Noah loads or reloads the playbook registry
• Stored in playbook metadata alongside source and description
• Included in run reports so you can tell exactly which version of a playbook was used for a given fix
• Used for change detection — when a fleet checkin delivers playbooks, Noah can skip re-writing files whose content hash hasn't changed

There's no version number to manage. Any change to the file content produces a new hash. This keeps versioning automatic and conflict-free.

Playbooks and the knowledge base

Playbooks live inside Noah's knowledge base — a structured directory of Markdown files that Noah uses for context. The knowledge base has several categories:

Playbooks are special because they're the only knowledge files that Noah can activate (load into its working context for structured execution). Other knowledge files are searchable — Noah can look them up when it needs context.

Folder playbooks

For complex procedures, you can organize a playbook as a folder with multiple sub-modules:

playbooks/
  setup-vpn/
    playbook.md       ← Main entry point
    install-client.md  ← Sub-module
    configure.md       ← Sub-module
    troubleshooting.md ← Sub-module

The main playbook.md file is what Noah activates. It can reference sub-modules, and Noah can load them individually using activate_playbook setup-vpn/troubleshooting.

Bundled playbooks reference

Noah ships with the following built-in playbooks. They're updated with each app release.

Diagnostics

Setup procedures

Security & compliance

Health & monitoring