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.

For adopted monorepos, one registered project may contain bounded nested runtime candidates. The model records those candidates rather than collapsing the project to the first manifest it encounters, then aggregates the observed runtime families into workspace identity. This improves polyglot discovery without turning every nested directory into a separate registered project.

The workspace profile remains an explicit intended boundary, not a discovery filter. Changing it refreshes canonical manifest and workspace-contract identity; it does not hide observable providers or fabricate a different Knowledge Graph when the source evidence has not changed.

Current command

npx workspai workspace model --json --write

The write publishes one locked, rollback-capable artifact set: .workspai/reports/workspace-model.json and the derived .workspai/reports/workspace-knowledge-graph.json. The graph carries the model stable structural digest it was derived from. Graph, context, MCP, IDE, and agent consumers can therefore reject a graph whose hash, workspace identity, or project topology no longer matches the current model.

Project inventory is reconciled from filesystem discovery, imported and adopted registries, and workspace-contract declarations. If a contract still declares a project whose path is missing, the model preserves that identity and reports project.path.missing instead of silently deleting it.

Each connected project receives a bounded project lens derived from this same workspace truth. Portable grounding never publishes a user's absolute workspace path; that machine-local binding lives only in the project's gitignored .workspai/workspace-link.local.json.

For an operational decision, use the contract-backed runner so the model is consumed in canonical dependency order:

npx workspai workspace intelligence run --for-agent generic --strict --json

The canonical order is read directly from the versioned Workspace Intelligence chain contract. Individual commands remain useful for artifact inspection and targeted regeneration, but they do not define an alternative chain.

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.