# Project pack: SiYuan @ bfe3610

Facts about **SiYuan** 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.

> SiYuan is a notebook for your thoughts, journals, studies and plans. You write in a clean editor and can link or embed any paragraph from one note into another, so ideas connect up. It has daily notes, tables and card databases, flashcards for revision, PDF annotation and an optional AI helper. Notes stay in a folder on your own computer, with apps for desktop and phone, or a web version you run yourself.

## Version and source
- Repository: https://github.com/siyuan-note/siyuan
- Pinned commit: `bfe36100477b7bbd66db1a8b8cff5547b2ccdb59`. 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/siyuan-note/siyuan/archive/bfe36100477b7bbd66db1a8b8cff5547b2ccdb59.zip
- Official docs: https://siyuan-en.b3log.org/
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations. Some features, such as SiYuan's cloud sync, need a paid membership.

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

  ```sh
  git clone https://github.com/siyuan-note/siyuan bespoke-siyuan
  cd bespoke-siyuan
  git checkout --detach bfe36100477b7bbd66db1a8b8cff5547b2ccdb59
  # Prepare development requirements and local configuration first.
  # Setup notes: then in app/: pnpm install && pnpm run install:electron && pnpm run dev && pnpm run start
  cd kernel && go build -tags "fts5 sqlcipher" -o ../app/kernel/SiYuan-Kernel && cd ../app/kernel && ./SiYuan-Kernel serve --mode=dev
  ```

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
  # Easiest: download the app for Windows, Mac, Linux, Android or iPhone from https://b3log.org/siyuan/en/download.html
  # Or run the web version in Docker, on this computer only:
  docker run -d --name siyuan -p 127.0.0.1:6806:6806 -v siyuan-workspace:/siyuan/workspace b3log/siyuan serve --workspace=/siyuan/workspace/ --accessAuthCode=choose-a-long-password
  # Then open http://localhost:6806 and enter that password.
  ```

- Needs: The desktop or phone app, or Docker for the web version (browser only; no PDF/Word export or Markdown import there), For development, Node 24 with pnpm (version in app/package.json) and Go (version in kernel/go.mod)
- Develop: `cd kernel && go build -tags "fts5 sqlcipher" -o ../app/kernel/SiYuan-Kernel && cd ../app/kernel && ./SiYuan-Kernel serve --mode=dev   # then in app/: pnpm install && pnpm run install:electron && pnpm run dev && pnpm run start`
- Test: `cd app && pnpm test   # Go kernel: targeted go test runs, e.g. cd kernel && go test ./apicontract/...`
- Check/lint: `cd app && pnpm run lint   # gofmt for Go changes`
- Build: `cd app && pnpm run build`
- Stack: go, typescript, javascript, css (Gin, Lute, Electron, webpack). Difficulty for a non-developer with an AI: **advanced**. Themes, CSS and JavaScript snippets, templates, plugins from the built-in marketplace and a full HTTP API let you change a lot without touching the code. The code itself is large and strict: a Go kernel plus a TypeScript front end (no framework) built with webpack, generated API contracts, and a detailed AGENTS.md with rules that agents must follow.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `.github/CONTRIBUTING.md`.

## Customisation points (settings → extend → code)
- **appearance** [settings]: Light or dark theme, theme from the marketplace, font and size, icons, and 22 interface languages. → `Settings - Appearance (app/src/config/tabs/appearanceTab.ts); built-in themes in app/appearance/themes/daylight and midnight`
- **editor** [settings]: Full width or narrow, line numbers, spell check, list behaviour, and how embeds and backlinks show. → `Settings - Editor (app/src/config/tabs/editorTab.ts)`
- **snippets** [settings]: Small CSS or JavaScript tweaks, e.g. a softer heading colour or hiding a toolbar button. → `Settings - Appearance - Code snippets (app/src/config/util/snippets.ts, stored in workspace/data/snippets/)`
- **ai-provider** [settings]: Choose a cloud AI or a local Ollama / LM Studio model, or leave AI off. → `Settings - AI (app/src/config/tabs/ai/aiTab.ts, presets in aiProviderPresets.ts; kernel/model/ai.go)`
- **templates-and-daily-notes** [settings]: A daily journal page with your own headings and prompts, created automatically each day. → `Templates in workspace/data/templates/ (docs/TEMPLATE-MANAGER.md); daily note template in each notebook's settings`
- **databases** [settings]: Track books, habits or recipes as tables or cards inside your notes. → `Database blocks (table, kanban and gallery views; kernel/av/)`
- **plugins-and-marketplace** [extend]: Install or write plugins that add commands, panels, toolbar buttons and settings. → `Settings - Marketplace (app/src/config/bazaar.ts); plugin API in app/src/plugin/ and the siyuan-note/petal repository; docs/PLUGIN-PUBLISH.md`
- **http-api** [extend]: Create notes, append to today's journal, search or export from scripts and shortcuts. → `HTTP API on port 6806 with the token from Settings - Authentication - API token (docs/API.md, kernel/api/)`
- **mcp-and-cli** [extend]: Let an AI agent or a script search and read your notes. → `MCP server (kernel/mcp/) and command-line interface (kernel/cli/cmd/; README → Command-line Interface)`
- **frontend** [code]: New screens or editor behaviour. Run pnpm run lint in app/ after changes. → `app/src/ (editor in app/src/protyle/, settings in app/src/config/, mobile in app/src/mobile/), text in app/appearance/langs/*.json`
- **kernel** [code]: New data or behaviour in the Go kernel. Regenerate API contracts as docs/API-CONTRACTS.md explains. → `kernel/model/ (logic), kernel/api/ (routes), kernel/sql/ (indexes); API contracts in kernel/apicontract/`

## Must keep working
- Existing notes, assets and data snapshots. Back up workspace/data before any change.
- The .sy file format and block IDs. Links and embeds between notes depend on them (docs/SY-FORMAT.md).
- Encrypted notebooks and the data repo key. Losing the key makes synced snapshots unreadable.
- Generated files. Don't hand-edit app/stage/build/, lute.min.js or API contract outputs; follow AGENTS.md.
- The HTTP API. Plugins and the mobile apps rely on it; add endpoints rather than change existing ones.

## Staying updatable
Settings, snippets, templates, marketplace plugins and the API cover most personal needs, and they survive updates. Upstream accepts pull requests on the dev branch; its AGENTS.md sets strict rules for AI agents (never commit or push unless asked, never run pnpm build, run pnpm run lint). Keep larger personal changes in your own copy or a plugin.

## Data, costs and safety
- Personal data: **yes**. Stored in: A workspace folder: notes as .sy JSON files per notebook in workspace/data/, plus assets, templates, snippets, plugins and SQLite search indexes. In Docker, the mounted /siyuan/workspace volume. Journals and notes can be very personal. Back up the workspace/data folder (or use Export Data and the built-in data snapshots) before upgrades or code changes. Don't put the workspace in Dropbox, OneDrive or similar sync folders; upstream warns it can corrupt data. Keep the data repo key if you use sync.
- Service: AI provider (OpenAI, Anthropic, Gemini, Mistral, DeepSeek, OpenRouter, Groq and others, or local Ollama / LM Studio) (optional, pay-per-use with your own key, or free with a local model): Writing help, summaries and chat about your notes in the editor.
- Service: SiYuan cloud sync and membership (optional, paid membership): Encrypted sync and backup between devices, and syncing through your own S3 or WebDAV storage.
- Service: Community marketplace (bazaar) (optional, free): Download themes, icons, templates, widgets and plugins made by other users.
- Service: OpenID Connect sign-in (Google, Microsoft, GitHub or your own) (optional, free): Log in to the Docker version instead of using the lock-screen password.
- Setting `SIYUAN_ACCESS_AUTH_CODE` (**secret**: the person enters it themselves, never in chat): Docker only. The password for the web version (or pass --accessAuthCode). Without it, anyone who can reach the port can read your notes. Never paste it into an AI chat.
- Setting `SIYUAN_WORKSPACE_PATH`: Docker only. Where your notes live inside the container (or pass --workspace). Must be on a mounted volume.
- Setting `PUID`: User ID that owns the workspace folder on the host (default 1000). PGID sets the group.
- Setting `TZ`: Your time zone, e.g. Europe/London (the image defaults to Asia/Shanghai).
- Setting `SIYUAN_LANG`: Interface language, e.g. en. If set, it overrides the language chosen in Settings at every start.
- Setting `SIYUAN_OIDC_ENABLED`: Set to true to log in with an identity provider. Goes with SIYUAN_OIDC_PROVIDER, SIYUAN_OIDC_CLIENT_ID, SIYUAN_OIDC_REDIRECT_URL and SIYUAN_OIDC_CLAIM_RULES.
- Setting `SIYUAN_OIDC_CLIENT_SECRET` (**secret**: the person enters it themselves, never in chat): Client secret for single sign-on. Never paste it into an AI chat.
- Setting `SIYUAN_ACCESS_AUTH_CODE_BYPASS`: Set to true to run without a password. Only for a container nobody else can reach.
- Always set a strong access password (SIYUAN_ACCESS_AUTH_CODE) on the Docker version, and use HTTPS through a reverse proxy before putting it on the internet.
- The AI features send the text you select or ask about to the provider you choose. Use Ollama or LM Studio to keep it on your own machine.
- Plugins, widgets and JavaScript snippets run with full access to your notes. Install only ones you trust.
- Keep the API token, AI keys and the data repo key out of AI chats and out of git.

---

# Customising SiYuan

SiYuan is a Go "kernel" (the engine that stores and indexes your notes) with a TypeScript front end that runs in Electron, on phones and in the browser. **Almost everything a person wants to change can be done with settings, snippets, templates, marketplace plugins or the API.** The code is large and has strict rules, so treat it as the last resort.

## Level 1: Settings (no code)
- **Look:** Settings - Appearance. Light (*daylight*) or dark (*midnight*) theme, themes and icons from the marketplace, font and size, 22 interface languages.
- **Code snippets:** Settings - Appearance - Code snippets. Add small CSS or JavaScript tweaks (colours, spacing, hiding buttons). They are saved in `workspace/data/snippets/` and survive updates.
- **Editor:** Settings - Editor. Width, line numbers, spell check, embed and backlink display, list behaviour.
- **Daily notes and templates:** each notebook's settings set where daily notes go and which template they use. Templates are files in `workspace/data/templates/` (see `docs/TEMPLATE-MANAGER.md`).
- **Databases:** insert a database block and switch between table, kanban and gallery views for reading logs, habits or collections.
- **Flashcards:** Settings - Flashcard, then mark blocks as cards and review them on a schedule.
- **AI:** Settings - AI. Choose a provider preset (OpenAI, Anthropic, Gemini, DeepSeek, Mistral, OpenRouter, Groq and more) or a local Ollama / LM Studio model.
- **Docker:** `--accessAuthCode` / `SIYUAN_ACCESS_AUTH_CODE`, `--workspace`, `PUID`/`PGID`, `TZ`, `SIYUAN_LANG`, and `SIYUAN_OIDC_*` for single sign-on (README → Docker Hosting).

## Level 2: Extend (no fork)
- **Marketplace:** Settings - Marketplace installs themes, icons, templates, widgets and plugins from the community `siyuan-note/bazaar` index.
- **Plugins:** TypeScript plugins built on the API in `app/src/plugin/` (published as the `siyuan-note/petal` package). They can add commands, top-bar and dock panels, toolbar buttons, settings and event listeners. Publishing rules: `docs/PLUGIN-PUBLISH.md`.
- **HTTP API:** `http://localhost:6806/api/...` with `Authorization: Token <token>` from Settings - Authentication - API token. Notebooks, documents (create from Markdown), blocks (insert, append, update), attributes, SQL queries, templates, files, export and notifications. Reference: `docs/API.md`.
- **MCP and CLI:** the kernel includes an MCP server (`kernel/mcp/`) for AI agents and a command-line interface for search and export (README → Command-line Interface).

## Level 3: Code
Read upstream `AGENTS.md` first. It is long and specific; key rules are summarised under Pitfalls.

| Change | Where |
|---|---|
| Editor behaviour and rendering | `app/src/protyle/` |
| Settings screens | `app/src/config/tabs/` (AI in `tabs/ai/`) |
| Layout, docks, menus, dialogs | `app/src/layout/`, `app/src/menus/`, `app/src/dialog/` |
| Mobile web UI | `app/src/mobile/` |
| Themes | `app/appearance/themes/daylight/`, `midnight/` |
| Text | `app/appearance/langs/*.json` (all languages) |
| Kernel logic | `kernel/model/` |
| API routes | `kernel/api/` (contracts in `kernel/apicontract/`, see `docs/API-CONTRACTS.md`) |
| Databases (attribute views) | `kernel/av/` |
| Search index | `kernel/sql/` |

## Running locally
- **Just use it:** download the app from https://b3log.org/siyuan/en/download.html, or run Docker on this computer only:
  1. `docker run -d --name siyuan -p 127.0.0.1:6806:6806 -v siyuan-workspace:/siyuan/workspace b3log/siyuan serve --workspace=/siyuan/workspace/ --accessAuthCode=choose-a-long-password`
  2. Open http://localhost:6806 and enter the password.
  3. The web version can't export PDF/Word/HTML or import Markdown files; use the desktop app for those.
- **Develop** (see `.github/CONTRIBUTING.md`):
  1. Switch to the `dev` branch. Install Node 24 and pnpm (`npm install -g pnpm@<version in app/package.json>`), and Go.
  2. Kernel: `cd kernel && go build -tags "fts5 sqlcipher" -o ../app/kernel/SiYuan-Kernel`, then `cd ../app/kernel && ./SiYuan-Kernel serve --mode=dev`.
  3. Front end: in `app/`, `pnpm install`, `pnpm run install:electron`, `pnpm run dev`, then `pnpm run start`. In a plain browser, open `/stage/build/desktop/`.
- **Check:** `pnpm run lint` and `pnpm test` in `app/`; `gofmt` and targeted `go test` runs in `kernel/`.

## Pitfalls
- Back up `workspace/data/` first. Don't keep the workspace in a Dropbox/OneDrive-style sync folder.
- AGENTS.md: don't run `pnpm build` while a developer runs `pnpm dev`; don't hand-edit generated files (`app/stage/build/`, `lute.min.js`, API contract outputs); never commit or push unless asked.
- Text changes must be made in every language file, or the language checks fail.
- Block IDs and the `.sy` format are what links and embeds rely on. Never rewrite them in bulk.

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