# cbrain

cbrain CLI — an Agent-native company knowledge brain

## Quick start (AI Agent)

**Step 1 — Install/update the CLI**

```bash
npm install -g cbrain
```

**Step 2 — Install/update the skill**

```bash
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**

```bash
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.

```bash
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**

```bash
cbrain me
```

After verification, **output the following**:

Usage guidance:
> Knowledge base <slug> has been authorized successfully. You can now use it to search and preserve company knowledge.
> Try one of these requests:
> Show me the knowledge-base structure.
> Check the project's progress.
> Save these meeting notes to the brain.
> Summarize recent customer updates.

When a user signs in for the first time, guide them through this request:
> Ask the user to introduce themselves. Help organize their name, preferred name, department, responsibilities, and access identifier (such as a WeChat bot ID), then create their personal wiki page.

Tailor the guidance to the user's permissions:
> For administrators, suggest:
> Managing directory maintenance rules, including the rules governing writes to each directory.
> For members with write access, suggest:
> Uploading complete customer interaction records to cbrain so cbrain can organize them automatically.
> For members with read access, suggest:
> Searching for general company information, project progress, customer information, and similar knowledge.



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

## Command reference

| 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 authorized knowledge base and capability scopes |
| Semantic search | `cbrain search "<question>" [--deep]` | Search before answering: vector nearest neighbors with citations |
| Write knowledge | `cbrain write <slug> --type <Type> --body-file <path> [--from raw/a,raw/b]` | Write a wiki page (body via `--body-file`, a UTF-8 file — never pipe non-ASCII text through a Windows shell); `--from` records raw provenance |
| Ingest evidence | `cbrain ingest --body-file <path> [--digest "<intent>"]` | Server plans semantic raw path + YAML tags + wiki routes from AGENTS before writing; ambiguous routing writes nothing and asks for confirmation |
| Update knowledge | `cbrain update "<intent>" [--dry-run]` | Describe the intent; the brain precisely rewrites actual content, including coordinated multi-page changes |
| 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 (wikilinks resolved) |
| Ingestion backlog | `cbrain backlog` | Raw evidence not yet referenced by any wiki page |
| Health report | `cbrain lint` | Read-only report: broken links, orphans, empty tags, stale pages |
| Browse tree | `cbrain tree` | Show a terminal directory tree for a quick knowledge-base overview |
| List pages | `cbrain list [--prefix customers/]` | List visible pages (JSON) |

## 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

## Admin console

Open: https://cbrain.intelli-spectrum.com/dash