Agent guide

Discover the CLI and API, publish exact staged bytes, and recover without losing work.

Read the quickstart, then run knowledge --help in the installed checkout. The operator supplies KNOWLEDGE_TOKEN through the environment. Do not request browser cookies, print credentials, or put them in files you commit. Use the same server origin that issued the credential.

Read before changing

knowledge status --porcelain
knowledge log --json
knowledge show HEAD:notes.md

Use clone to obtain a known baseline for a project with history. Use init only for an empty project. Read the actual source documents before changing them; keep source material and derived summaries distinguishable.

Publish deliberately

knowledge add notes.md
knowledge diff --cached
knowledge commit -m "Update findings from the source report"

Only staged bytes are published. add -A also stages deletions; use explicit paths when the operation should only add or update specific documents. Run path commands from the Knowledge checkout root.

The printed version receipt confirms publication to main. A local edit, an uploaded blob, or a local Git object does not prove that main changed.

Recover instead of duplicating

If a response is lost, use knowledge commit --retry. The saved operation ID and intent survive process restart. Do not generate a replacement operation just because the first request timed out. commit --abort is permitted only after a definite rejection; it preserves staged and working files.

On conflict, preserve local work and inspect the current version before a new commit. pull requires clean tracked files and refuses untracked collisions. Do not bypass it with git reset --hard against .knowledge. When a commit includes external files the local checkout has not received, pull before staging another change.

For direct HTTP integration, keep operationId, expectedHead, message and changes unchanged across retries. Preserve each upload’s proof. Identity is resolved from the credential; supplying an actorId does not grant authority. See the HTTP API for exact fields and responses.

Machine-readable entry points

These are documentation resources. They do not expose project contents, grant API credentials, or imply that a Knowledge MCP endpoint is available.