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 CBRAINSERVICEURL). 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.

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.

Seven mandatory rules

1. Identify the brain; the server owns the rules: The first time company knowledge is involved in a session, run cbrain me to confirm which company's brain is connected and who you operate as. You do not need to read any rules page first—the server applies the knowledge base's own AGENTS rules to every operation (ingest/update/ask). For ingest, do not choose or inspect target directories—routing is the server's job. Only before an advanced direct write, read the target directory's AGENTS page (or its nearest ancestor) with cbrain read; if none exists, proceed without it.
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; check your own authority first: AGENTS pages (root and directory level) govern every Agent in the company, so treat editing one as privileged. Before concluding you cannot change a rule, read operator.mayeditagents from cbrain me. If it is true, you may change the rule directly: state the exact edit, get the user's confirmation, apply it with cbrain update, and append a dated entry to the page's change log. Only if it is false should you fall back: save the proposed change under wiki/proposals/AGENTS-change-<date> (type: note) and tell the user an administrator must apply it — cbrain has no automated approval queue, so an unapplied proposal page stays inert. Never edit an AGENTS page as a side effect of an unrelated task.
7. Identity comes from cbrain me, never from search: When the user asks a first-person question ("who am I", "我是谁", "my role", "my team"), answer only from the operator block returned by cbrain me and the profile page it references (operator.profile.slug). Never answer first-person identity questions from semantic search — people pages found by search are third-person data about someone else, and any name you carry from local context is a guess, not an identity. If operator.profile is null or its exists is false, this is the user's first sign-in: ask them to introduce themselves (name, preferred name, department, responsibilities), save the introduction to a temp UTF-8 file, then create and bind their profile with cbrain profile wiki/people/<short-name> --body-file <tmp-file> --display-name "<name>".

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 "who am I" / about their own identity
  → cbrain me → answer from the operator block (display name, role, team) + operator.profile page
  → operator.profile missing? → first sign-in: interview the user, then
    cbrain profile wiki/people/<short-name> --body-file <tmp-file> --display-name "<name>"
  → NEVER use cbrain search to answer first-person identity questions
User asks a company-related question
  → cbrain me (first time only; identify the brain and the operator)
  → 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.