docs: truth-up architecture.md + 3 new domain pages + Linux/Arch caveats in localized READMEs

[aashir-athar]

Summary

• Fix stale QuickJS / rquickjs skill-runtime references throughout gitbooks/developing/architecture.md — the runtime was removed and src/openhuman/skills/ is metadata-only per CLAUDE.md, but multiple diagrams, tables, and prose sections still described it as active.
• Also correct two related factual bugs in the same file: "Yarn workspace" → "pnpm workspace" (root package.json declares pnpm@10.10.0); rewrite the row referring to a top-level skills/ directory (does not exist) to point at the real src/openhuman/skills/ and describe what it actually is now.
• Add three contributor-audience architecture pages under gitbooks/developing/architecture/ for memory_tree, mcp_registry, and security — currently-thin gitbook areas where the source-side README.md / mod.rs rustdoc is rich but no public page exists. Linked from gitbooks/SUMMARY.md.
• Backfill the Linux Wayland warning + AUR pointer block (present in README.md since CEF prewarm webview triggers a fatal X_ConfigureWindow BadWindow crash on Wayland #2463) into README.zh-CN.md, README.ja-JP.md, README.ko.md, README.de.md. English content under <!-- TODO: translate (xx) --> markers — native-speaker translation follow-up invited.

Problem

The architecture book diverged from the code on three load-bearing points:

1. Stale runtime model. CLAUDE.md is explicit: "Skills runtime removed: the QuickJS / rquickjs runtime that previously executed skill packages is gone. src/openhuman/skills/ is now a metadata-only domain." Yet gitbooks/developing/architecture.md still describes a QuickJS runtime engine, per-skill 64 MB sandbox limits, "QuickJS Skill Instance executes tool" in the MCP flow diagram, and the same in the end-to-end data flow. New contributors get an inaccurate mental model on day one.
2. Stale build-tool reference. "Yarn workspace openhuman-app" in the repo-layout table, but package.json declares pnpm@10.10.0 and CI runs pnpm install --frozen-lockfile.
3. Stale path reference. The layout table mentions a top-level skills/ directory; it does not exist.

Three active and substantial domains (memory_tree, mcp_registry, security) have no gitbook architecture page despite being among the most-touched in recent weeks (#2556, #2559) and despite each having a rich internal-audience README.md / mod.rs rustdoc that's invisible to the public gitbook.

The Linux Wayland warning + AUR pointer (README.md lines 73–75) was only added to the English README; localized READMEs never received the backfill — a German / Korean / Japanese / Chinese reader running the install command on Arch + Wayland hits an unexplained crash with no caveat in their language.

Solution

gitbooks/developing/architecture.md — purged QuickJS references from the high-level architecture diagram, the performance table, the MCP flow diagram, the security architecture diagram + bullet, and the end-to-end data flow. Where a replacement was needed (e.g. "Sandboxed QuickJS per skill (64 MB)"), used what the code actually does today: tool execution gated by SecurityPolicy + a host-selected sandbox backend from src/openhuman/security/ (Docker / Bubblewrap / Firejail / Landlock / Noop). Three intentional "QuickJS was removed" historical references retained (clearly marked as such) to make the migration explicit. Fixed "Yarn workspace" → "pnpm workspace" and rewrote the stale skills/ row to point at src/openhuman/skills/ and describe what it actually is now (metadata-only).

Three new architecture pages — followed the existing agent-harness.md / frontend.md / tauri-shell.md convention: YAML frontmatter with description: (multi-line >-) + icon: (FontAwesome name), H1 with the source path in backticks, ASCII diagram of how the domain plugs into the wider system, layout table sourced from the existing README.md / mod.rs, "Calls into" / "Called by" / "Tests" / "Related" sections. Each page describes only what the code currently does — no aspirational claims. Tables Prettier-aligned to match the existing style.

Localized READMEs — inserted the Linux/Arch block right after the install bash code-block (matching the structural position in README.md), wrapped in <!-- TODO: translate (xx) --> / <!-- /TODO --> markers so native speakers know exactly what needs translation in a follow-up PR.

Submission Checklist

Summary by CodeRabbit

• Documentation
  • Added Linux installation caveats to translated READMEs (German, Japanese, Korean, Chinese) with Wayland compatibility notes and AUR package guidance.
  • Updated architecture documentation reflecting changes to tool execution and system design.
  • Added new documentation pages for Memory Tree, MCP Registry, and Security components.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds translated installation documentation for Linux systems and substantially updates OpenHuman's architecture documentation to reflect a runtime refactor moving from in-process QuickJS skill execution to a metadata-only skills model with native Rust tool execution and Node-backed helpers, along with three new comprehensive architecture pages documenting the MCP Registry, Memory Tree, and Security modules.

Changes

Documentation Updates

Layer / File(s)	Summary
Installation caveats in translated READMEs README.de.md, README.ja-JP.md, README.ko.md, README.zh-CN.md	Linux-specific installation notes documenting AppImage crashes under Wayland, Arch Linux sharun: Interpreter not found! issues, and AUR installation guidance for openhuman-bin are added consistently across all four language variant README files with TODO markers for translation sync.
Architecture overview refactoring gitbooks/developing/architecture.md, gitbooks/SUMMARY.md	Main architecture documentation is refactored to describe the shift from in-process QuickJS skill runtime to metadata-only skills with native Rust tool execution and Node-backed helpers via runtime_node. Repository layout, runtime diagrams, frontend↔core communication, performance characterization, MCP protocol flow (mcp:toolCall routed by tool_name to unified Tool Registry), security sandbox model (runtime-selected backends: Docker/bubblewrap/firejail/Landlock/Noop), and end-to-end data flow are all updated. GitBook navigation is updated to link the three new architecture pages.
MCP Registry architecture documentation gitbooks/developing/architecture/mcp-registry.md	New page documents the dynamic user-facing MCP client registry (src/openhuman/mcp_registry/), covering module purpose, system flow from Smithery browsing through SQLite persistence to subprocess spawning, transport model (local stdio JSON-RPC), boot-time error handling, internal layout, public exports, integration points, test locations, and related references.
Memory Tree architecture documentation gitbooks/developing/architecture/memory-tree.md	New page documents the kind-agnostic Memory Tree generic engine (src/openhuman/memory_tree/), defining responsibilities, key invariants (no kind branching, no persistence, no policy), module layout by subcomponent (tree, summarisation, retrieval, scoring), write/read flow mechanics with bucket sealing and hotness-ordered retrieval, controller registry re-exports, and related references.
Security architecture documentation gitbooks/developing/architecture/security.md	New page documents the security trust boundary module (src/openhuman/security/), enumerating public surface (policy, autonomy/risk classification, sandbox abstraction, secret store, audit logging, pairing guard, log redaction), sandbox backend selection strategy, autonomy ladder semantics, module/file layout, inter-module call relationships, and test coverage references.

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly Related PRs

• tinyhumansai/openhuman#2465: Adds the same Linux/Wayland AppImage crash caveat and Arch installation guidance to README.md (English source).
• tinyhumansai/openhuman#2005: Introduces Japanese README variant that this PR now updates with installation caveats.
• tinyhumansai/openhuman#1789: Documents the same runtime/skills refactor (QuickJS to metadata-only/native Rust execution) in agent-context documentation.

Suggested Labels

documentation, architecture

Suggested Reviewers

• graycyrus
• senamakel

Poem

🐰 Four README tongues now speak of Wayland's plight,
While architecture docs shine new and bright—
From QuickJS dreams to Rust's efficient way,
Three module tales our humble PR convey. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main categories of changes: architecture documentation updates, three new domain pages, and Linux/Arch caveats in localized READMEs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

gitbooks/developing/architecture.md (1)

253-253: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add newline before section heading.

Line 253 is missing a blank line before the --- section separator, which breaks Markdown formatting conventions and may cause rendering issues.

📝 Proposed fix

 Memory encryption keys derive from user credentials via Argon2id, ensuring memory files are unreadable without authentication. The hybrid search combines semantic understanding (vector similarity) with keyword precision (SQLite FTS5) for reliable recall.
+
 ---

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@gitbooks/developing/architecture.md` at line 253, Add a blank line
immediately before the Markdown section separator '---' so that the separator is
on its own line preceded by an empty line; locate the stray '---' in the content
(the section separator at line with '---') and insert one newline above it to
restore proper Markdown heading/section separation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@gitbooks/developing/architecture.md`:
- Line 253: Add a blank line immediately before the Markdown section separator
'---' so that the separator is on its own line preceded by an empty line; locate
the stray '---' in the content (the section separator at line with '---') and
insert one newline above it to restore proper Markdown heading/section
separation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 71304988-917c-4486-b7ad-be92cdd51cd9

📥 Commits

Reviewing files that changed from the base of the PR and between d997394 and 0b51243.

📒 Files selected for processing (9)

• README.de.md
• README.ja-JP.md
• README.ko.md
• README.zh-CN.md
• gitbooks/SUMMARY.md
• gitbooks/developing/architecture.md
• gitbooks/developing/architecture/mcp-registry.md
• gitbooks/developing/architecture/memory-tree.md
• gitbooks/developing/architecture/security.md