# Project pack: SilverBullet @ 3ee1f82

Facts about **SilverBullet** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> SilverBullet is a self-hosted notebook where every page is a plain Markdown file. It adds backlinks, tasks, and live queries (for example "all my open tasks tagged #home"), and lets you write small scripts in the Space itself. It works offline in the browser and keeps your files on your own server.

## Version and source
- Repository: https://github.com/silverbulletmd/silverbullet
- Pinned commit: `3ee1f82deedf4d083bb1adde43f131448082abc6`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/silverbulletmd/silverbullet/archive/3ee1f82deedf4d083bb1adde43f131448082abc6.zip
- Official docs: https://silverbullet.md/Manual
- Live demo: https://play.silverbullet.md/. Public playground. Don't enter anything private.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/silverbulletmd/silverbullet bespoke-silverbullet
  cd bespoke-silverbullet
  git checkout --detach 3ee1f82deedf4d083bb1adde43f131448082abc6
  # Prepare development requirements and local configuration first.
  npm install
  npm run build
  npm test
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name silverbullet -p 3000:3000 -v silverbullet-space:/space ghcr.io/silverbulletmd/silverbullet:latest
  # then open http://localhost:3000
  ```

- Needs: Docker for a trial, Node 22 and the Go toolchain for development
- Develop: `npm run build`
- Test: `npm test`
- Check/lint: `npm run lint`
- Stack: typescript, go, lua (Deno-free TypeScript client, Go server, CodeMirror). Difficulty for a non-developer with an AI: **moderate**. Most personal changes are pages, templates and Lua scripts inside your own space, with no fork. Changing the editor or server itself means working in a TypeScript client and a small server.

## Customisation points (settings → extend → code)
- **pages-and-templates** [settings]: Page templates, daily notes and index pages without any code. → `Pages in your space, tagged page templates`
- **live-queries** [settings]: Dashboards of tasks, notes by tag, or reading lists. → `Query blocks in any page`
- **space-lua** [extend]: Small scripts that add commands, widgets and slash-menu items. → `Space Lua blocks and the Library`
- **styles** [extend]: Colours, fonts and layout. → `A page tagged for custom CSS in your space`
- **client-ui** [code]: Editor behaviour and built-in screens. → `client/`

## Must keep working
- Page storage as plain Markdown files. Never change how files are saved or named.
- Authentication when SB_USER is set.
- Offline sync between the browser and the server.

## Staying updatable
Stay inside your space (pages, templates, Lua and CSS). Nothing to merge on upgrade. Fork only for editor or server changes.

## Data, costs and safety
- Personal data: **yes**. Stored in: Markdown files in the space folder (/space in Docker). Back up the space folder. It is just files, so Git or any sync tool works.
- Setting `SB_USER` (**secret**: the person enters it themselves, never in chat): Optional login in the form user:password. Set it before putting the notebook online. Never paste the value into an AI chat.
- Without SB_USER the notebook has no login. Set one before exposing it beyond your own computer.
- Scripts you paste into a space can read and change your pages. Read them first.

---

# Customising SilverBullet

Most of SilverBullet is customised from inside the notebook, not in the source code. Start there and only fork for deeper changes.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Your pages, templates and scripts | The space folder (/space in Docker), not the source repo |
| Editor and screens | client/ |
| Server | server/ and server-common/ |
| Built-in plugs (indexing, tasks, links) | plugs/ |
| Standard library pages | libraries/ |
| Plug API for scripts | plug-api/ |
| Documentation | docs/ |

## Use the gentlest change first

1. **Settings (no code):** page templates, tags and live queries in your own pages.
2. **Extend:** Space Lua blocks, commands and custom CSS pages.
3. **Code:** the TypeScript client and the server, built from this repo.

## Recipes

- **New dashboard:** add a page with a query block over your tasks or tagged pages.
- **New command:** write a Space Lua block that registers it, then run it from the command palette.
- **Restyle:** add a page for custom styles and paste your CSS there.

## Running and checking your changes

- `npm run build`, then run the server on a throwaway space folder.
- `npm test` for unit tests and `npm run lint` before you finish.
- Try a refresh while offline to confirm the browser still loads your pages.

## Pitfalls

- Use a copy of your space when testing scripts. A bad script can rewrite pages.
- Don't commit your space folder if it holds private notes.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/silverbullet/3ee1f82/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/silverbullet/3ee1f82/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/silverbullet/3ee1f82/r2/SKILL.md)