JishuDB setup

Install or connect the smallest safe JishuDB path for the user's actual machine and client. Keep Desktop as the sole owner of Desktop data.

Choose the route

Establish whether this Agent runs on the target machine. A cloud, container, or remote Agent cannot install the user's local Desktop application.
If the user supplied a remote JishuDB URL, use that target and do not install locally.
Probe the intended sibling /health without credentials and accept it only when product, healthSchema, and status identify JishuDB. Do not follow redirects.
Inspect bounded installed locations and a local jishudb binary with --version and mcp ... --help. Do not trust a filename alone.
Prefer direct Streamable HTTP for Desktop, an existing HTTP service, or a remote service. Use jishudb mcp serve only for an explicit standalone or headless data owner with an exact approved non-Desktop JISHUDB_DATA.
Report a stdio-only Desktop or remote client as BLOCKED. Do not stop Desktop, open its SQLite data, or install a proxy.

Automatic Desktop installation

Read references/installation-contract.md before installing or troubleshooting an installer transaction.

Use only the packaged helper for the current platform:

macOS arm64: scripts/install-macos.zsh
Windows x64: scripts/install-windows.ps1

Run the helper in plan mode first. The plan is read-only for product, installation, client, and release state and may create only private ephemeral evidence. It must resolve the exact release, asset digests, source revision, application/data destinations, client, configuration target, connection name, MCP URL, and default read-only profile.

Show the helper's complete redacted approval envelope and ask once for the exact default transaction: verified download, per-user installation, Desktop launch, and the named non-secret client entry. After approval, pass the unchanged plan path and SHA-256 to execute. Do not recreate release logic with ad hoc commands, select a newer release, retry a failed installer, or reuse the approval after drift.

OS publisher/Gatekeeper UI, first-administrator creation, scoped-token entry, and client trust remain user-presence gates. Wait and resume after them without requesting another Agent mutation approval. An upgrade, different destination, different endpoint/client, write-capable profile, retry, or repair requires a new approval.

If no eligible immutable stable release exists, return BLOCKED with the release-owner action. Never offer a mutable or manual download fallback.

Authorization and client configuration

Default to a default read-only scoped connection.
Request jishudb only when the user needs write or maintenance tools and has separately approved that privilege.
Direct the signed-in administrator to Settings -> MCP connections for current manual jkm_ creation. Never ask for a token in chat.
Preserve unrelated MCP entries and approvals. Prefer the client's official settings or command. If a file must be changed, atomically parse/merge/write it with a backup and only within the approved envelope.
Do not fabricate client trust. If the client lacks a protected secret entry mechanism, write only the non-secret entry and return USER_ACTION_REQUIRED.
After the server advertises MCP OAuth, prefer the client's native browser flow. Never read or copy OAuth access or refresh tokens.

Prove the effective path

Verify through the actual host client, not a parallel curl-only path:

Confirm the intended server entry loaded.
Complete authenticated initialize/discovery and tools/list.
Call kb_get_capabilities.
Record product, transport, protocol version, profile, tool-contract version, server version, and revision. Do not require a frozen tool count.

Return exactly one terminal state with its first recovery action:

READY: the real client call succeeded.
USER_ACTION_REQUIRED: an OS, administrator, secret-entry, or client-trust action is waiting.
BLOCKED: a required immutable release or supported transport is absent.
FAILED: an available prerequisite or protocol path behaved incorrectly.

Keep credential absence, generic upstream 401, origin/policy 403, proven profile insufficiency, unavailable service, wrong endpoint, protocol mismatch, invalid response, and rate limiting distinct. Do not guess whether a rejected credential is expired, revoked, malformed, or has the wrong secret.