# ContextDB Cloud agent guide

## Scope

This is the private ContextDB Cloud repository. It depends on the public
Apache-2.0 `pycontextdb` SDK. Public integrators should read
https://contextdb.ai/for-agents.txt before changing their application.

## Read before editing

- Read `BOUNDARY.md` before moving or adding capability code.
- Read `docs/08-known-limitations.md` before stating that a feature exists.
- Read the nearest tests and contract document before changing an API.
- Treat site maturity labels and non-claims as product requirements.

## BOUNDARY rules

- Portable semantics and offline correctness belong in the public SDK.
- Public schemas, protocols, and compatibility tests may be opened.
- Tenant coordination, managed workers, billing, governance, and operated
  guarantees stay private.
- Stop for maintainer review when a change crosses these classes.

## Secret rules

- Project keys and Memory CI tokens are server credentials.
- Use `CONTEXTDB_API_KEY` and `CONTEXTDB_EVAL_TOKEN` through secret storage.
- Never put credentials in browser code, mobile code, fixtures, logs, prompts,
  screenshots, commits, or generated site files.
- Never use customer data in examples. Use clearly synthetic IDs and content.

## Canonical client flow

`recall -> remember -> evaluate_action -> confirm if required -> re-evaluate -> host action -> report_execution`

- Client `evaluate_action` maps to HTTP and MCP `recall_for_action`.
- ContextDB returns `act`, `ask`, or `abstain`. The customer host enforces it.
- The host authenticates the end user, authorizes the action, and checks current
  business state.
- Report `succeeded`, `failed`, or `skipped` with a stable idempotency key.

## Checks

- Run focused tests first, then the full repository test suite.
- Run `python site/build.py --check` after marketing-site changes.
- Run `ruff check .` for Python changes.
- Keep generated `site/dist/` output in sync only when the task requests it.