Workspace Model

The Workspace Model is the current structured view of a workspace.

The Workspace Model v1 contract is the field-level authority for this concept. Its reference page connects the model command, generated artifact, schema constraints, and downstream consumers.

It is not just a JSON file. It is the product boundary between raw project files and higher-level reasoning.

What the model should represent

The model should answer:

• Which projects are registered?
• Which projects were created by Workspai?
• Which projects were adopted or imported?
• Which runtime and framework markers were observed?
• Which lifecycle commands are safe to run?
• Which policies apply?
• Which contracts are present?
• Which generated reports exist?
• Which facts are fresh, stale, inferred, or unknown?

Why it matters

Without a model, every consumer has to rediscover the workspace:

IDE scans files
CI scans files
Agent scans files
Docs repeat assumptions
Human keeps context in memory

With a model, every consumer can ask the same source:

Model inputs

The model is built from observed and generated evidence:

• workspace markers,
• project metadata,
• runtime manifests,
• package manager files,
• lockfiles,
• scripts,
• policies,
• contracts,
• doctor reports,
• analyze reports,
• readiness reports,
• previous Workspace Intelligence artifacts.

Current command

npx workspai workspace model --json --write

The model should be followed by context, diff, impact, verify, or agent-sync depending on the workflow.

Model is not enough

A model tells you what exists. A graph explains relationships. Evidence tells you what to trust. Verification decides whether the state is ready, blocked, stale, or unknown.