Self-Executing
Markdown (SEM)

1. What is a SEM File?

A SEM (Self-Executing Markdown) file uses the .sem.md extension and is valid standard Markdown. Any markdown viewer renders it perfectly as documentation. When passed to aimd run, the AIMD CLI parses it into an interactive step-by-step wizard — extracting executable shell blocks, prompting for variables, and running each step under user control.

Think of it as a README that also ships as a runbook. Write once. Read anywhere. Execute anywhere.

2. Executable Block Syntax

The AIMD runtime scans your .sem.md file for code blocks marked with one of three supported execution directives. Only tagged blocks are executed — all other blocks remain inert documentation.

Method A — Annotated Fence

Add execute after the language identifier:

```bash execute
npm install
npm run build
```

Method B — Inline Directive

Add a comment as the first line inside the block:

```bash
# aimd:execute
echo "Deploying to production..."
```

Method C — HTML Comment Directive

```bash
<!-- execute -->
docker compose up -d
```

3. Variable Substitution

Use {{double_curly_braces}} to declare runtime variables anywhere in an executable block. When the CLI encounters them, it pauses before execution and prompts the user interactively.

```bash execute
# aimd:execute
docker build -t {{image_name}} .
docker push {{registry_url}}/{{image_name}}:{{version}}
```

The CLI displays a smart prompt for each variable including a description hint and sensible defaults. Pressing Enter without input accepts the default value.

4. Running a SEM File

Install the CLI and run any .sem.md file interactively:

# Install the CLI globally
npm install -g @getaimd/cli

# Authenticate
aimd login

# Run a local runbook
aimd run ./deploy.sem.md

# Run with resume support (picks up where you left off)
aimd run ./deploy.sem.md --resume

# Dry-run — shows steps without executing
aimd run ./deploy.sem.md --dry-run

# Inject workspace secrets into the child process environment
aimd run ./deploy.sem.md --secrets

5. Step Names & Structure

The CLI derives step names from Markdown headings (##, ###) that precede each executable block. If no heading is found, steps are auto-numbered. A well-structured SEM file looks like:

# My Deployment Runbook

## Step 1: Install Dependencies

```bash execute
npm ci
```

## Step 2: Run Tests

```bash execute
npm test
```

## Step 3: Deploy

```bash execute
./scripts/deploy.sh --env {{environment}}
```

6. Stateful Resume

If a run is interrupted (failure, q to quit, or network issue), the CLI writes state to ~/.config/aimd/run-state.json, recording the last completed step index and all variable values. Running with --resume restores this state and jumps directly to the next incomplete step — no re-entering variables.

7. Validating Before Publishing

Use aimd test to validate your runbook before listing it on AIMD. It runs six automated checks without executing any shell commands:

# Basic validation
aimd test ./my-runbook.sem.md

# Full verbose output with mock variable injection
aimd test ./my-runbook.sem.md --verbose --mock-env "env=production,port=3000"

8. Publishing to the Marketplace

Once validated, push your runbook to the AIMD Marketplace as a versioned listing. The push command runs a pre-flight security scan, compresses the package, and uploads a new draft version for review.

# Push a new version to your workspace listing
aimd push -l <listing-slug> -w <workspace-slug> -m "Initial release"

# Install a published runbook from the registry
aimd install workspace-slug/listing-slug

# Run it directly
aimd run ./aimd_packages/workspace-slug/listing-slug/runbook.sem.md

Ready to publish your first runbook? Open Creator Hub → or read the Publisher Documentation for listing setup, pricing, and DRM controls.