# SilverBullet MCP Server Instructions

You are connected to a SilverBullet instance via its Runtime API. SilverBullet is a creative coding knowledge management tool with an embedded Lua scripting language called Space Lua.

## Available Tools

- **execute_lua**: Run Space Lua scripts. Use for reading/writing pages, querying data, and all Space Lua operations.
- **screenshot**: Capture current viewport as a PNG image.
- **console_logs**: Retrieve recent console log entries. Useful for debugging.

## Space Lua Essentials

Space Lua is a custom Lua implementation embedded in SilverBullet. Key differences from standard Lua:

- **camelCase** for all variables and functions (not snake_case)
- No coroutines (not supported)
- No `_ENV` (planned, not yet available)
- `print()` output is swallowed in Runtime API — use `return` to send results back
- `query[[...]]` is LIQ (Lua Integrated Query), a SQL/LINQ-inspired query syntax embedded in Lua

## Page Operations

```lua
-- Read a page
local content = space.readPage("MyPage")

-- Write a page
space.writePage("MyPage", "# Hello\n\nContent here")

-- Delete a page
space.deletePage("MyPage")

-- Check if a page exists
if space.pageExists("MyPage") then
  -- ...
end

-- List all pages
local pages = space.listPages()

-- Get page metadata
local meta = space.getPageMeta("MyPage")
-- meta.name, meta.lastModified
```

## Querying with LIQ

LIQ (`query[[...]]`) is the primary way to search and filter data:

```lua
-- Find pages tagged #task
local tasks = query[[
  from p = index.tag "task"
  select p.name
]]

-- Filter by frontmatter
local projects = query[[
  from p = index.tag "page"
  where p.status == "active"
  order by p.lastModified desc
  select p.name
  limit 10
]]

-- Count items in a group
local counts = query[[
  from p = index.tag "tag"
  group by p.name
  select { name = name, count = #group }
]]
```

## File/Document Operations

```lua
-- List all files
local files = space.listFiles()

-- Read a file (returns bytes as string)
local data = space.readFile("image.png")

-- Write a file
space.writeFile("data.json", jsonString)

-- Read a specific section
local section = space.readRef("MyPage#Introduction")
```

## Common Patterns

### Working with Frontmatter

SilverBullet pages can have YAML frontmatter. Query against indexed tags and frontmatter fields:

```lua
local pages = query[[
  from p = index.tag "page"
  where p.priority == "high"
  select { name = p.name, priority = p.priority }
]]
```

### Working with Tasks

```lua
local tasks = query[[
  from t = index.tag "task"
  where t.state == "todo"
  order by t.lastModified desc
  select { name = t.name, page = t.page }
]]
```

### Links and References

```lua
-- Find pages that link to a specific page
local links = query[[
  from l = index.tag "link"
  where l.toPage == "TargetPage"
  select l.fromPage
]]
```

### Combining Lua and LIQ

```lua
-- Multi-step workflow
local pages = query[[
  from p = index.tag "page"
  where p.name:startsWith("Project/")
  select p.name
]]

for _, p in ipairs(pages) do
  local content = space.readPage(p.name)
  -- process content
  space.writePage(p.name, updatedContent)
end

return pages
```

## Important Notes

- Always `return` values from lua_script — `print()` output is not captured
- The `X-Timeout` header controls execution timeout (1-21600 seconds, default 120)
- Use `space.readRef("Page#Header")` to read specific sections
- Use explicit variable binding in LIQ: `from p = ...` (not bare `from ...`)
- Namespace your functions: `myPlugin = myPlugin or {}; function myPlugin.doThing() ... end`
- Use `-- priority: N` comments to control script load order (higher = earlier)