Contracts

How Workspai.dev stays aligned with Workspai CLI contracts and claim boundaries.

Workspai.dev is contract-aware. The public knowledge portal should teach what the shipped Workspai architecture can support, not invent separate marketing claims.

Source contracts

The canonical contracts are maintained in the Workspai CLI repository under:

packages/cli/contracts/

This site syncs those files into its local contracts/ directory and checks them during lint.

npm run sync:workspai-contracts
npm run check:workspai-contracts
npm run check:knowledge-claims

The complete field-level reference is generated from every synchronized file:

Every contract page explains its architectural role, consumers, fields, constraints, producing commands, and durable artifacts. The raw JSON remains the authority behind each educational projection.

Contract families

Contract family	Purpose
Architecture	Category positioning, inputs, core loop, consumers, claim boundaries
Project entry	The open-ended adopt/import rule for readable projects
Create planner	Native, official, and existing project-entry reality
Runtime command surface	Supported commands, runtimes, module support, workspace commands
Agent customization	Generated agent surfaces and grounding inventory
Doctor evidence	Workspace/project diagnostics and remediation plans
Workspace Intelligence	Model, diff, impact, verify, context, graph, freshness, history
Release and pipeline	Readiness, analyze, pipeline, and operational gates
Workspace discovery	Shared workspace identity, project registration, list/sync behavior, and consumer alignment

Architecture contract

The top-level architecture contract defines:

canonical positioning,
input sources,
the Workspace Intelligence loop,
evidence principles,
consumers,
claim boundaries,
create planner reality.

The category name is Workspace Intelligence.

The current primary promise is:

Workspai turns repositories, projects, dependencies, rules, changes, and evidence into shared understanding for developers, CI, IDEs, and AI agents.

The most important evidence principle is:

Evidence is the source of understanding; documentation is an output, not the authority.

Claim boundaries

Allowed public claims:

Workspai is Open-Source Workspace Intelligence for Software Systems.
One shared model of structure, context, impact, and verification.
Workspai can create projects only for native kits and available official generator paths listed in the create planner contract.
Any readable project can enter Workspace Intelligence through adopt/import when it can be registered.
Existing projects can enter Workspace Intelligence through adopt/import when they are readable and can be registered, even when native scaffold is unavailable.
Existing runtime signals in the create planner are examples for detection, not a closed allowlist of adopt/import support.
Agent grounding is available through workspace context, agent-sync, generated agent files, skills index, and MCP evidence access.
Verification and governance claims must reference doctor, analyze, readiness, pipeline, workspace verify, or generated evidence artifacts.
Workspace discovery claims must preserve the CLI contract: the same workspace identity should be discoverable by terminal commands, CI, IDEs, and agent surfaces.

In shorter documentation, the same creation boundary can be stated as: Native project creation is limited to create planner support.

Forbidden unless implemented:

unlimited native scaffold coverage across all languages and frameworks,
module support for runtimes where module contracts say it is unavailable,
hosted product experiences or repository chat in the CLI unless shipped,
inferred or unknown facts presented as verified,
documentation described as the source of truth.

Documentation rule

Docs can teach, summarize, and connect ideas. They do not replace evidence. When the CLI emits a contract, report, model, or verification artifact, that artifact has priority over prose.

Cross-platform workspace discovery

Workspace discovery is a release-critical contract because the CLI, VS Code, CI, and future portals all need to resolve the same workspace identity.

The educational rule is simple:

create/adopt/import establish a workspace boundary,
workspace sync reconciles the project registry for that boundary,
workspace list shows the registered workspace set,
consumers should use the shared workspace identity instead of inventing a separate registry or naming scheme.

Implementation details can change, but documentation should teach the stable concept: one workspace identity shared across tools.

Enterprise developer platforms fail when every surface tells a slightly different story. A CLI says one thing, a website says another, an extension implements a third interpretation, and agents receive a fourth set of rules.

Workspai avoids that by treating contracts as the bridge between implementation, documentation, marketing, IDEs, and future product surfaces.