Developers FAQ

Q: How do I build the project?

Clone the repository, then run make build to compile all Go modules, make install to drop CLIs into ./bin, and make test to run the test suite. make ci runs the full local gate (gofmt + vet + tests), mirroring GitHub Actions. Prerequisites: Go 1.22+, GNU Make 4.x, Node.js 20+, Python 3.11+, Docker with Buildx.

Q: How do I add a new capability?

Author a SKILL.mtx (MatrixScript) file and grant it the version-pinned tool URIs it needs. To add a new tool server, register an MCP server entry in the agent manifest (agents/*.json). The manifest declares the server alias, transport, command, package digest, and an exhaustive list of every tool the server advertises. The executor rejects drift at boot if the manifest does not match.

Q: How do I add a new MCP tool server?

Add a server entry to the agent manifest with alias, transport (stdio or http), command/args, package_digest (sha256 of the published package), and an exhaustive tools array. Credential references use $env:NAME syntax in the env or headers fields; literal secrets in the manifest are forbidden. See the default.json manifest for the canonical structure.

Q: What is the tool URI scheme?

Tools are referenced as matrix://tool/mcp/ / @ . The version pin is resolved against the agent manifest at boot. The packagedigest in the manifest (sha256 of the published server package) makes digest changes auditable through the cortexsnapshot_hash of any plan.

Q: What is the bar for a PR?

A clean make ci plus make lint, tests for new behavior, no weakened tests, and a matrix.kvx update if you move a phase status or invariant. Design changes that move a locked decision need a design-review PR first. Issues, bug reports, and security disclosures are always welcome.

Clone the repository, then run make build to compile all Go modules, make install to drop CLIs into ./bin, and make test to run the test suite. make ci runs the full local gate (gofmt + vet + tests), mirroring GitHub Actions. Prerequisites: Go 1.22+, GNU Make 4.x, Node.js 20+, Python 3.11+, Docker with Buildx.

Author a SKILL.mtx (MatrixScript) file and grant it the version-pinned tool URIs it needs. To add a new tool server, register an MCP server entry in the agent manifest (agents/*.json). The manifest declares the server alias, transport, command, package digest, and an exhaustive list of every tool the server advertises. The executor rejects drift at boot if the manifest does not match.

Add a server entry to the agent manifest with alias, transport (stdio or http), command/args, package_digest (sha256 of the published package), and an exhaustive tools array. Credential references use $env:NAME syntax in the env or headers fields; literal secrets in the manifest are forbidden. See the default.json manifest for the canonical structure.

Not casually. The 10 verbs and 8 object kinds are closed vocabularies. Adding one requires a journaled migration with an explicit schema-version bump, not a one-line change. The closed-verb protocol is a core design decision that ensures intent between agents is always exact.

Dropping Cortex's derived state and rebuilding from the journal must yield a byte-identical OverallRoot. Any change to a Cortex mutation path must preserve this invariant and add a rebuild test. The invariant runs on every pull request via make ci. It guarantees that nothing an agent did is unaccounted for, and nothing it did not do is hidden.

Tools are referenced as matrix://tool/mcp/<server-alias>/<tool-name>@<version>. The version pin is resolved against the agent manifest at boot. The package_digest in the manifest (sha256 of the published server package) makes digest changes auditable through the cortex_snapshot_hash of any plan.

The gateway mediates every per-user daemon's LLM call to upstream providers (Fireworks, Together). It looks up the model in a versioned rate card, prices input/output tokens, debits the Postgres credit_ledger, and enforces a daily PAX hard-stop per actor. Each ledger row records the rate-table version used so historical costs replay byte-identically after a reprice.

A clean make ci plus make lint, tests for new behavior, no weakened tests, and a matrix.kvx update if you move a phase status or invariant. Design changes that move a locked decision need a design-review PR first. Issues, bug reports, and security disclosures are always welcome.