Workspai docs

Give the work a measurable finish line

The natural-language front door compiles intent into a workspai.goal-pack.v1 pack and workspai.goal-agent-handoff.v1 handoff. Verified Goals preserve release, dependency-security, or coverage success criteria across CLI, CI, IDE, and agent sessions. Planning records the goal; only npx workspai workspace goal verify <goal-id> --json can publish the governed verdict to .workspai/reports/verified-goal-last-run.json.

Make the change carry its own proof

Proof-Carrying Change pins the active Goal and architecture generation before mutation, then keeps authorization, observed effects, the actual Graph delta, verification, and remaining uncertainty in a workspai.proof-carrying-change-capsule.v1 capsule. Prediction can guide the agent, but it never becomes proof. Use npx workspai change list --json to discover durable changes and npx workspai change capsule validate --change <change-id> --json before trusting or exporting one.

Enter through the canonical project boundary

The workspai.agent-entry.v1 entry resolves its governing workspace in canonical-first mode. The workspai.agent-bootstrap-receipt.v1 receipt requires at least 6 bounded read-order items, keeps live source as exact-implementation, and permits verification claims only from cli-evidence-only. Runtime-aware Skills use workspace-operational-skill.v1 and workspace-skills-index.v1 contracts.

Classify the project before judging it

The workspace-model.v1 Model distinguishes 11 project kinds and records runtime units, lifecycle commands, test surfaces, package structure, CI, release, and ownership evidence. Governance remains explicit as repository, external-declared, external-observed, unknown. Cache reuse also requires semantic producer workspace-model-producer.v3, so a structurally valid but semantically obsolete model is rebuilt.

Diagnose causally, then repair transactionally

Doctor emits the workspai.doctor-diagnosis.v1 diagnosis across 6 required domains. Repair then uses 13 typed adapter families across 4 scope types, 10 failure families, and 6 terminal recovery paths. Mutation authority stays cli-only. Missing tools, unsupported adapters, or risk beyond approval remain decision-required. Compact workspai.doctor-summary.v1 output and the durable workspai.doctor-receipt.v1 receipt preserve verdict, freshness, affected projects, blockers, and the next governed action. The aggregate Studio surface is contract-bound across 32 card kinds; one repair transaction still owns only one causal finding family and one canonical project at a time.

Keep analysis, readiness, and proof separate

Analyze publishes ready, needs-attention, blocked findings. Readiness evaluates env, doctor, analyze, verify, dependency gates for the requested action. Verify then emits a workspace-verify.v1 receipt with ready, needs-attention, blocked verdicts, explicit missing evidence, affected-subgraph coverage, and exit codes 0, 1, 2.

Plan a polyglot fleet before executing it

Plan mode discovers bounded runtime units without running them. Real test, build, and start stages use npm, Python, Go, Cargo, Maven, Gradle, NuGet, CMake, Meson providers and enforce doctor-workspace and readiness by default. The workspace-run-v1 result is retained at .workspai/reports/workspace-run-last.json. Strict mode turns failed or warning gates into a non-zero exit; verification follows the finding's exact sourceCommand and sourceArtifact instead of guessing a producer.

Ask the Workspace Knowledge Graph first

Workspai first reconciles the canonical Workspace Model, then derives and enriches this graph from the projects that model authorizes. The graph is bound to the model's stable structural hash and live project fingerprint, using hybrid-git-content-v2 with git-worktree-v2 or content-merkle-v1 per scope, so stale or mismatched graph evidence is rejected. Scoped search removes low-value query terms, ranks relevant identities deterministically, and keeps repeated logical interfaces together while preserving their individual source proofs. Provider results remain explicit when evidence is partial, skipped, failed, or expected but missing. The agent projection reports an omission budget for entities, relations, relatedEntities, proofs, proofReferences, aliases, attributeValues rather than silently truncating evidence. Its schema exposes 24 entity kinds and 25 relation kinds. Runtime registration and endpoint implementation remain distinct, while ambiguous source dispatch stays unbound. CMake, Meson, Bazel, and Protobuf providers enrich native and cross-language relationships. Linked proof paths remain portable and omit machine-local absolute paths by default.

Measure without overclaiming

Evaluation artifacts preserve observed payload and model-usage evidence. Compare compatible runs instead of presenting one fixture as a universal token-saving claim.