Development and contributions

Choose the right repositoryCopy Anchor Link

• KnowRealm-AI: desktop product, application services, and assistants.
• knowrealm-ai-website: website, downloads, and these public docs.

The steps below are for the desktop product. Website documentation editing is covered at the end.

Prepare desktop developmentCopy Anchor Link

You need Git, Node.js and pnpm, Python 3.12 or later and uv, plus Rust, Microsoft C++ build tools, and WebView2 for Tauri on Windows. Repository manifests and lockfiles define the exact version constraints.

Regular users can install the MSI without these development dependencies.

Get and start the productCopy Anchor Link

git clone https://github.com/youyu-youth/KnowRealm-AI.git
cd KnowRealm-AI
git switch main
pnpm install --frozen-lockfile
cd backend
uv sync --frozen
cd ..
pnpm --filter @knowrealm/desktop tauri dev

The desktop start command prepares the audio tools and starts the local service. The first run requires network access and the build environment. Do not run another service against your everyday data folder. Use a separate folder for debugging and acceptance checks.

A successful start opens the desktop window and onboarding wizard. AI features still require your own service configuration; installing dependencies does not include model credits.

Read before making changesCopy Anchor Link

Read AGENTS.md, PROJECT_PROGRESS.md, and GLOSSARY.md. Read directory rules when entering the desktop or backend code, and consult requirements and architecture decisions relevant to your change.

Frontend workspace and backend dependencies are managed separately. Update API contracts and callers together, and maintain both Chinese and English UI copy. Use the repository's current docs/agents/validation.md as the validation entry point.

Report issues and contributeCopy Anchor Link

In Issues, include app version, operating system, reproduction steps, and expected versus actual behavior. Remove keys and personal data from logs and screenshots.

Keep changes focused and describe behavior changes, checks you actually ran, and anything still unverified. For model, device, or display scaling changes, record each validation environment.

Edit the website documentationCopy Anchor Link

Docs live in content/docs/ as MDX. meta.json controls ordering and groups. Fumadocs handles rendering, full text search, the table of contents, and previous/next navigation. English pages use .en.mdx and meta.en.json; maintain both languages when changing public guidance.

git clone https://github.com/youyu-youth/knowrealm-ai-website.git
cd knowrealm-ai-website
pnpm install --frozen-lockfile
pnpm dev

After editing, run pnpm typecheck, pnpm lint, and pnpm build, and open the changed pages. For product capability changes, check the target version's source and release notes again rather than treating old docs as implementation evidence.