# SilverBullet MCP Server Instructions

You are connected to a SilverBullet instance, a knowledge management tool with a Lua interpreter, via its Runtime API.

## 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

## 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

-- Find pages tagged #task
local tasks = query[[
  from p = index.tag "task"
  select p.name
]]
-- Find pages that link to a specific page
local links = query[[
  from l = index.tag "link"
  where l.toPage == "TargetPage"
  select l.fromPage
]]
-- 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 }
]]
-- 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")
-- 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
```

## Fetching SilverBullet Documentation

The official SilverBullet instance at `silverbullet.md` serves raw Markdown pages. When you need details on any Space Lua feature, API, or concept, fetch the docs directly:

```lua
-- Fetch a specific docs page by name (URL-encode spaces and slashes)
local content = net.readURI("https://silverbullet.md/.fs/Space%20Lua.md")

-- List all docs pages to find what you need (requires X-Sync-Mode header)
local result = http.request("https://silverbullet.md/.fs", {
  headers = { ["X-Sync-Mode"] = "true" }
})
-- result.body is an array of {name, size, lastModified, ...}
for _, p in ipairs(result.body) do
  -- p.name e.g. "Space Lua/Quirks.md"
end

```

## Gotchas

- `System: Reload` via `editor.invokeCommand` is **asynchronous**: it returns before the reload has actually completed. Any verification that must observe the post-reload runtime state should happen in a separate `execute_lua` call a moment later, not immediately after the reload in the same script.
  ```lua
  local ok, err = pcall(editor.invokeCommand, "System: Reload")
  if not ok then return { reload_ok = false, reload_err = tostring(err) } end
  return { reload_ok = true }
  ```

## Notes

- Always `return` values from lua_script because `print()` output is not captured
- 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`
- Wiki-link syntax is `[[target|display]]` (not display|target), e.g. `[[tag:project|📌 project]]` shows "📌 project" linking to the tag:project virtual page