cbrain

cbrain · Company Knowledge Brain

Use the cbrain CLI to search and preserve company knowledge; use the admin console for administration. You are connected (or about to connect) to an organizational knowledge base that uses markdown-in-git as its single source of truth and provides semantic search plus read/write access.

Installation and configuration

Step 1 - Install/update the CLI

npm install -g cbrain

Step 2 - Install/update the skill

npx skills add https://cbrain.intelli-spectrum.com --skill cbrain -g -y

Origin scheme: production-style (HTTPS). Do not rewrite the skill URL to http://—HTTPS-only redirects break npx skills add discovery. Use the skill URL exactly as written in this document. Step 2 is mandatory and must exit 0. Updating the CLI alone is not enough. If npx skills add fails (for example, "No skills found"), stop and report the error. Do not continue with an already-installed older local skill.

Step 3 - Point the CLI at this deployment

cbrain config set-url https://cbrain.intelli-spectrum.com

This persists the service URL (same origin as this document / server CBRAIN_SERVICE_URL). Do not substitute localhost or rewrite the scheme. Without this step, auth login may fall back to a local-dev default.

Step 4 - Authorize with OAuth

Long-running interactive command: Run this command in the background with a PTY (background+pty), extract the exact authorization URL it prints to stdout/stderr, and send it to the user. You must include this prompt: Click or copy the following link to complete authorization in your browser:. The command exits automatically after the user completes authorization in the browser.

URL output rule: Treat the URL as an immutable opaque string. Do not alter it in any way, including URL encoding/decoding, adding whitespace or punctuation, or reconstructing its query string. Show it to the user in a separate code block containing only the original URL.

cbrain auth login

When running this command:

• You must install/update the CLI and the skill first, and run Step 3 (config set-url).
• If it fails or times out, do not retry; report the error directly to the user.

Step 5 - Verify

cbrain me

After verification, output only the following:

Knowledge base xxx has been authorized successfully. You can now use it to search and preserve company knowledge. Try one of these requests: Check the progress of Project A. Save these meeting notes to the brain. Summarize recent customer updates.

You can also describe your knowledge workflow directly and ask the Agent to handle it.

Replace xxx with the actual knowledge-base (company) slug returned by cbrain me. If authorization fails, output the failure details.

Command reference

The verbs encode the user's intent: ingest = submit evidence and let cbrain maintain raw/ + wiki/; update = evolve wiki knowledge from an intent; write = advanced direct wiki authoring when you intentionally provide the full text; search/ask/read = retrieval.

Operation	Command	Purpose
Authorize	cbrain auth login	Sign in through browser OAuth and save credentials
Log out	cbrain auth logout	Clear locally stored OAuth credentials
Inspect identity	cbrain me	Show the connected brain, page count, and capability scopes
Semantic search	cbrain search "<question>" [--deep] [--include-raw]	Search before answering: wiki-first by default; include raw evidence when verification is needed
Write knowledge	cbrain write <slug> --type <Type> --body-file <path> [--from raw/a,raw/b]	Write/maintain a wiki page (body via --body-file; see "Body input" below); --from records raw provenance in frontmatter sources
Ingest evidence	cbrain ingest --body-file <path> [--digest "<intent>"]	Submit evidence without a path; before writing, the server reads AGENTS rules and plans a semantic raw path, YAML tags, and wiki routes. Ambiguity returns a question with zero writes; --raw-only persists only the planned raw page
Update knowledge	cbrain update "<intent>" [--dry-run]	Describe the intent; the brain rewrites actual content precisely (including coordinated multi-page changes; see references/MUTATE.md)
Intelligent Q&A/organization	cbrain ask "<intent>"	Have the brain search and organize read-only, then answer with citations
Read a page	cbrain read <slug>	Read a page by slug
Reverse links	cbrain backlinks <slug>	List the pages citing a slug ([[basename]] wikilinks are resolved); navigate entity hubs beyond vector search
Ingestion backlog	cbrain backlog	List raw evidence not yet referenced by any wiki page (what still needs digesting)
Health report	cbrain lint [--prefix wiki/customers/]	Read-only report: broken links, orphan pages, empty tags, stale pages, raw backlog. Never auto-fixes
Browse tree	cbrain tree	Show a terminal directory tree for a quick knowledge-base overview
List pages	cbrain list [--prefix wiki/customers/]	List visible pages

Body input — always use --body-file

write and ingest take the page body from --body-file <path> (recommended), a stdin pipe, or --body "<text>".

Always prefer --body-file: write the body to a temporary file with your file-write tool (UTF-8), pass its path, and delete the file afterwards. The path is plain ASCII, so no non-ASCII text ever crosses the shell.

Never pipe non-ASCII text through a Windows shell. Windows PowerShell 5.1 and cmd.exe re-encode pipe content (US-ASCII / OEM codepage by default), silently turning Chinese and other non-ASCII characters into ? before the CLI ever sees them — and raw/ is immutable, so the corruption is permanent. echo "..." | cbrain ... is acceptable only on POSIX shells (macOS / Linux), and even there --body-file is more robust for multi-line content.

The CLI decodes body files as UTF-8 (with or without BOM) or UTF-16 (with BOM) and rejects anything it cannot decode, so a wrongly encoded file fails loudly instead of polluting the knowledge base.

Six mandatory rules

1. Identify the brain, then read its rules: The first time company knowledge is involved in a session, run cbrain me to confirm which company's brain is connected, then run cbrain read AGENTS to read the connected knowledge base's global context (a page inside the brain—never a local source repository's AGENTS.md file). For ingest, do not choose or inspect target directories—routing is the server's job. Before an advanced direct write, read the target directory's AGENTS page (or its nearest ancestor) with cbrain read.
2. Search before answering: Before answering any company-related question, you must run cbrain search. Never answer from memory or speculation; if search returns nothing, state plainly that nothing was found.
3. Cite sources: Append [[source slug]] from a search hit to every conclusion. Do not output company facts without citations. See references/CITATIONS.md.
4. Plan before persistence; cbrain owns paths and tags: Submit source material with ingest --body-file <path>. Never invent a raw slug, YAML tags, or raw/wiki directory—the server plans a semantic raw path plus tags and wiki routes from the knowledge base's own AGENTS rules before any write. If it returns needs_confirmation, no content was persisted: ask the user its question, then rerun the same command with the original body and --confirm-route <chosen-candidate>. Do not follow ingest with write or Git operations.
5. Do not imply hidden content exists: Treat content that search/read cannot find as nonexistent. Do not speculate that it "might exist but be invisible." Higher-classification content is entirely invisible to you by design.
6. Rules confer authority: Only administrators may modify AGENTS pages at the root or directory level. If a rule needs updating, save the proposed change as a proposal page (wiki/proposals/AGENTS-change-<date>, type: Proposal), remind the user to have an administrator approve it, and do not edit the rule directly.

Version updates (self-healing)

When any cbrain command returns an UPGRADE_REQUIRED error, follow the steps in the error JSON's instructions field to update the CLI and skill. Credentials are preserved, so do not run auth login again. Then retry the original command once. Full documentation: https://cbrain.intelli-spectrum.com/doc/cli-update.md

Minimal workflow

User asks a company-related question
  → cbrain me (first time only) → cbrain read AGENTS (first time only; read global rules)
  → cbrain search "<question>"  ── any hits?
        ├─ Yes → answer from the hits + append [[slug]] to every conclusion
        └─ No  → state plainly that no relevant content was found; suggest adding it if appropriate
User provides new notes/conclusions (full recipe: references/INGEST.md)
  → Save the body to a temp UTF-8 file, then submit it once:
    cbrain ingest --body-file <tmp-file>
      --digest "<optional emphasis, not a directory>"
  → cbrain reads AGENTS and plans semantic raw path + YAML tags + wiki routes before writing.
  → If needs_confirmation: ask the user the returned question, then:
    cbrain ingest --body-file <same-tmp-file> --confirm-route <chosen-candidate>
    (the first call persisted nothing; resend the same body)
  → If clear: cbrain writes the planned raw page, then updates wiki, indexes, DB, and git.
  → Do NOT manually create wiki pages or run git commit/push after ingest.
  → Verify: cbrain lint --prefix <dir>（坏链/空标签/积压是否清零）
User wants to change existing knowledge (for example, customer contact A→B), especially across pages
  → **Describe the intent** to cbrain update "<intent>"—the brain reads the actual content, makes precise changes, and commits atomically
    (You **do not need** and **cannot** construct byte-level diffs yourself; see references/MUTATE.md.)

Progressive disclosure: Read the relevant file under references/ only when details are needed. Do not load them routinely; this saves tokens.