WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• AGPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

SiYuan is a privacy-first, self-hosted personal knowledge management system written in TypeScript (frontend) and Go (backend) that lets users build interconnected notes with bidirectional linking, full-text search, and local-first storage. It's a Notion/Obsidian alternative emphasizing data ownership and encryption, deployable as a desktop app (Electron-based) or Docker container. Monorepo structure: app/ contains the Electron frontend (TypeScript, SCSS styling in app/appearance/), API.md documents the REST/WebSocket backend contract, and the Go backend logic is housed in the root alongside CI workflows. Plugin ecosystem supported via appearance themes and icon sets (see app/appearance/icons/ and app/appearance/fonts/).

Knowledge workers, researchers, and students who want a PKM (personal knowledge management) tool without cloud vendor lock-in; also developers interested in contributing to an open-source full-stack TypeScript+Go application with a modern plugin architecture.

Production-ready and actively maintained: 4.9M+ LOC across TypeScript/Go, consistent monthly commits, robust CI/CD pipeline (see .github/workflows/cd.yml and auto_aur_release_stable.yml), and Docker support with 100k+ pulls. Project has clear versioning in releases and multi-language documentation (English, Chinese, Japanese, Turkish).

Moderate risk: single-org governance (B3Log, not a distributed maintainer model), AGPLv3 license is more restrictive than MIT/Apache for commercial users, and no explicit test coverage metrics visible in file list. However, CI/CD is robust and release cadence is healthy—monitor /issues for any licensing or stability concerns before production deployment.

Active development on UI/UX refinement, internationalization (langs support), and Docker deployment. GitHub Actions workflows (cd.yml, dockerimage.yml) indicate continuous release automation. AUR (Arch Linux) releases are auto-generated, suggesting Linux user adoption focus.

Clone and install: git clone https://github.com/siyuan-note/siyuan.git && cd siyuan. Frontend: cd app && npm install && npm run dev. Backend: Go version required (see root for version constraints). Full setup documented in .github/CONTRIBUTING.md and CONTRIBUTING_zh_CN.md.

Daily commands: Frontend dev: cd app && npm install && npm run dev. Backend: compile Go sources (setup varies; check .github/workflows/cd.yml for build matrix: Linux, macOS, Windows). Full app: npm run build in app folder creates distributable. Docker: docker run -it -v ~/siyuan:/root/siyuan -p 6806:6806 b3log/siyuan (port 6806 is default API).

• README.md — Entry point documentation covering the project's mission as a privacy-first, self-hosted knowledge management system and build/deployment instructions.
• Dockerfile — Defines containerized deployment strategy, critical for understanding how SiYuan is packaged and distributed.
• API.md — API specification document defining all backend endpoints and integration contracts that frontend and extensions depend on.
• .github/workflows/cd.yml — CI/CD pipeline definition controlling build, test, and release processes across all platforms (Windows, macOS, Linux, Docker).
• app/.npmrc — NPM configuration for the TypeScript frontend build, controlling dependency resolution and package management.
• .github/CONTRIBUTING.md — Contribution guidelines explaining development workflow, code standards, and PR expectations for new contributors.
• LICENSE — License file establishing the open-source legal framework (likely AGPL or similar based on privacy-first positioning).

Add a new theme variant

1. Create a new directory under app/appearance/themes/ (e.g., 'solarized') (app/appearance/themes/)
2. Create theme.json with metadata (name, description, isDark flag) (app/appearance/themes/daylight/theme.json)
3. Create theme.css with CSS variables for colors, typography, and component styles matching existing theme structure (app/appearance/themes/daylight/theme.css)
4. Register theme in the appearance configuration and rebuild the app (app/.npmrc)

Add internationalization support for a new language

1. Create new translation file using language code (e.g., de_DE.json for German) (app/appearance/langs/en_US.json)
2. Copy structure from en_US.json and translate all string values to the target language (app/appearance/langs/en_US.json)
3. Register language code in the i18n initialization and UI language selector (app/appearance/langs/)

Extend the REST API with a new endpoint

1. Document the new endpoint in API.md including HTTP method, path, request/response schema, and authentication requirements (API.md)
2. Implement the backend handler following the existing pattern (likely in a Go service module) (API.md)
3. Update API_zh_CN.md and API_ja_JP.md with translated documentation (API_zh_CN.md)
4. Add integration tests and update CHANGELOG.md with the new feature (CHANGELOG.md)

Set up development environment and build locally

1. Read CONTRIBUTING.md for detailed setup instructions, development tool requirements, and build commands (.github/CONTRIBUTING.md)
2. Install frontend dependencies using npm with configuration from app/.npmrc (app/.npmrc)
3. Build the application using defined scripts that compile TypeScript frontend and Go backend (.github/workflows/cd.yml)

• TypeScript frontend — Type-safe UI development enabling faster feature iteration and fewer runtime errors in a complex editor interface
• Go backend — High-performance, statically-compiled server language suitable for file I/O, database operations, and API serving with minimal resource overhead
• Electron/Tauri desktop framework — Cross-platform (Windows, macOS, Linux) desktop packaging while reusing TypeScript codebase; enables native OS integration for notes
• Docker containerization — Enables self-hosted deployments on servers and cloud platforms without dependency conflicts; aligns with privacy-first mission
• Local SQLite database — Zero external dependency for data persistence; privacy-preserving local-first storage without requiring database server

• Local-first architecture with optional cloud sync

  • Why: Prioritizes user privacy and offline-first usage; data never leaves user's device unless explicitly synced
  • Consequence: Requires additional sync logic and conflict resolution; limits real-time multi-device updates without explicit infrastructure

• Single monolithic REST API rather than microservices

  • Why: Simpler deployment, easier to self-host, reduced operational complexity for privacy-conscious users
  • Consequence: Scaling individual features may require refactoring; potential bottleneck if feature complexity grows significantly

• Multiple language documentation files (API_zh_CN.md, API_ja_JP.md) rather than dynamic i18n

  • Why: Community-driven translation workflows; ensures translation quality for critical API docs
  • Consequence: Manual maintenance overhead; risk of documentation drift between language versions

• AppX Windows packaging alongside traditional installers

  • Why: Windows Store distribution enables easier updates and discoverability for Windows users
  • Consequence: Additional platform-specific build configuration and testing; AppX sandboxing constraints for file system access

• Real-time collaborative editing (no CRDT/OT built into core)
• Cloud-native multi-tenant SaaS (self-hosted only)
• Browser-first design (Electron desktop is primary platform)
• Mobile native apps (no iOS/Android native implementation)
• GraphQL API (REST-only exposure)
• Blockchain or decentralized sync (local-first with optional centralized sync service)

Port binding: Backend defaults to port 6806 (not standard HTTP), verify firewall/Docker networking. Database: SQLite local-only; no distributed DB support—backup strategy is essential for multi-device sync. Language packs: app/appearance/langs may require tooling to add new languages; check build config. AGPL license: linking or shipping modified code requires source disclosure—commercial/proprietary use needs clarification. Electron on Linux: may require specific desktop environment; test on target distribution.

• obsidianmd/obsidian-sample-plugin — Similar PKM ecosystem; shows how plugin architecture works for note-taking tools, useful for understanding SiYuan's extensibility model
• logseq/logseq — Direct competitor: open-source, local-first PKM with Markdown and outliner focus; reference implementation for feature comparison
• electron/electron — Framework used for SiYuan's desktop shell; essential for understanding app packaging, auto-updates, and native integration
• golang/go — Backend runtime language; necessary for understanding the server build, benchmarking, and performance tuning
• b3log/ld246 — Related B3Log open-source project (same org); may share build patterns, CI/CD practices, or community guidelines

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add API documentation for TypeScript/JavaScript SDK usage

The repo has API.md, API_zh_CN.md, and API_ja_JP.md files documenting REST endpoints, but lacks TypeScript/JavaScript SDK documentation. Given that the app/ directory is written in TypeScript and the project is a knowledge management tool with heavy API usage, contributors could create API_SDK.md documenting how to use the REST API from TypeScript/Node.js clients with code examples, authentication patterns, and common use cases.

• [ ] Review existing API.md to understand documented endpoints
• [ ] Create API_SDK.md with TypeScript/JavaScript client examples
• [ ] Document authentication flow and API key management for SDK users
• [ ] Add examples for common operations (creating notes, querying blocks, etc.)
• [ ] Include error handling and retry patterns specific to the SiYuan API

Add workflow automation tests for GitHub Actions (cd.yml, dockerimage.yml)

The repo has multiple critical CI/CD workflows (.github/workflows/cd.yml, dockerimage.yml, auto_aur_release_stable.yml) but no tests validating their correctness. A contributor could add a GitHub Action workflow that lints YAML syntax, validates workflow structure using tools like 'actionlint', and tests workflow conditional logic to catch configuration errors before they break releases.

• [ ] Install and configure 'actionlint' in a new .github/workflows/lint-workflows.yml file
• [ ] Add validation for all YAML files in .github/workflows/ directory
• [ ] Test for undefined secrets and missing environment variables across workflows
• [ ] Add documentation in CONTRIBUTING.md about workflow linting requirements
• [ ] Set up the workflow to run on PRs that modify files in .github/workflows/

Add locale translation completeness checker in CI

The repo supports 14+ languages (ar_SA, de_DE, en_US, es_ES, fr_FR, he_IL, it_IT, ja_JP, ko_KR, pl_PL, pt_BR, ru_RU, sk_SK, tr_TR, zh_CHT, zh_CN in app/appearance/langs/), but lacks automated checks ensuring all languages have the same keys. A contributor could add a Node.js script and GitHub Action to validate that all translation files have identical structure and flag missing keys before release.

• [ ] Create a Node.js script (e.g., scripts/validate-translations.js) to compare JSON keys across all lang files in app/appearance/langs/
• [ ] Script should report missing keys per language and exit with error code if mismatches found
• [ ] Add GitHub Action workflow (.github/workflows/validate-translations.yml) to run on PRs modifying lang files
• [ ] Document the validation process in CONTRIBUTING.md for translators
• [ ] Output should generate a summary showing translation completeness percentage per language

• Add missing unit tests in app/ for TypeScript components (check CI/CD—test coverage not explicitly shown in file list; start with app/appearance/boot or icon loading logic)
• Expand internationalization: add language files to app/appearance/langs for underrepresented locales (Turkish, Japanese, Korean variants); follow existing zh_CN + ja_JP pattern
• Document Go backend architecture: repo has extensive API.md but no ARCHITECTURE.md for backend logic; write a contributor guide explaining kernel structure, DB schema, and WebSocket protocol

• High · Dockerfile uses 'latest' Alpine tag — Dockerfile (final stage). The final stage uses 'FROM alpine:latest' without pinning to a specific version. This introduces supply chain risks and makes builds non-reproducible, as the base image can change unexpectedly between builds. Fix: Pin Alpine to a specific version, e.g., 'FROM alpine:3.19' or the latest stable release with known security patches.
• High · Missing CA certificates installation — Dockerfile (final stage, RUN apk command). The Dockerfile installs 'ca-certifi' (likely a typo for 'ca-certificates'), but the command appears incomplete. This could result in SSL/TLS verification failures for HTTPS connections. Fix: Verify the correct package name is 'ca-certificates' and ensure the installation completes successfully. Test SSL/TLS connections in the final image.
• High · Node.js build stage uses 'node:21' without specific patch version — Dockerfile (node-build stage). The Node.js builder stage uses 'node:21' without pinning to a specific patch version (e.g., '21.x.x-alpine'). This creates inconsistency and potential security issues with Node.js updates. Fix: Pin to a specific Node.js LTS version with patch, e.g., 'node:21.7.0-alpine3.19'. Regularly update and rebuild when security patches are available.
• Medium · Unsafe npm registry configuration — Dockerfile (npm config set registry). The Dockerfile allows setting a custom NPM registry via ARG without validation. A malicious registry could serve compromised packages. No integrity checks (lock file verification) are evident. Fix: Validate the NPM_REGISTRY input, use only trusted registries, ensure pnpm-lock.yaml is committed and verified, and consider using npm audit in the CI/CD pipeline.
• Medium · Go build stage enables CGO without sanitization — Dockerfile (go-build stage, CGO_ENABLED=1). CGO_ENABLED=1 is set without visible input validation. If external code or dependencies are compiled, this could introduce C-level vulnerabilities. The go mod download step has limited visibility. Fix: Document CGO usage, use go mod verify to ensure dependency integrity, perform static analysis on C dependencies, and consider disabling CGO if not required.
• Medium · Build artifacts copied without verification — Dockerfile (mv appearance stage guide changelogs). The Dockerfile copies build artifacts (appearance, stage, guide, changelogs) from the node-build stage without checksums or signature verification. Artifacts could be tampered with. Fix: Implement artifact verification using checksums or signatures. Generate and verify SHA256 hashes of critical build outputs.
• Medium · No health checks or security scanning in Dockerfile — Dockerfile (overall structure). The Dockerfile lacks HEALTHCHECK directives and doesn't include vulnerability scanning steps (e.g., using trivy or grype). Runtime health and security posture are unverified. Fix: Add HEALTHCHECK directive, integrate container image scanning in CI/CD, and use tools like trivy or Snyk to scan for known vulnerabilities.
• Low · Build cache strategy could expose sensitive data — Dockerfile (go-build stage, RUN with --mount=type=cache). The Dockerfile uses --mount=type=cache for go-build and go/pkg, which could potentially cache sensitive build artifacts or credentials across builds. Fix: Ensure cache directories don't contain secrets, use separate cache mounts per build stage, and regularly purge build caches in CI/CD systems.
• Low · Missing LABEL metadata for security tracking — Dockerfile (LABEL section). The Dockerfile has minimal LABELs. Important security-related metadata (build date, VCS reference, vulnerability scanner info) is missing for image verification and tracking. Fix: Add comprehensive LABELs: org.opencontainers.image.created, org.opencontainers.image.revision, org.opencontainers.image.source, and security scanner info.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/siyuan-note/siyuan shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live siyuan-note/siyuan repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/siyuan-note/siyuan.

What it runs against: a local clone of siyuan-note/siyuan — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in siyuan-note/siyuan | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of siyuan-note/siyuan. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/siyuan-note/siyuan.git
#   cd siyuan
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of siyuan-note/siyuan and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "siyuan-note/siyuan(\\.git)?\\b" \\
  && ok "origin remote is siyuan-note/siyuan" \\
  || miss "origin remote is not siyuan-note/siyuan (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "API.md" \\
  && ok "API.md" \\
  || miss "missing critical file: API.md"
test -f ".github/workflows/cd.yml" \\
  && ok ".github/workflows/cd.yml" \\
  || miss "missing critical file: .github/workflows/cd.yml"
test -f "app/.npmrc" \\
  && ok "app/.npmrc" \\
  || miss "missing critical file: app/.npmrc"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/siyuan-note/siyuan"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.