Workspai helps people and tools understand the same software system. Use these guides to connect existing projects, create new ones, map their relationships, check changes, prepare AI context, and automate release checks.
Start with the main README for the product overview, or use the
quickstart below. workspai is the main package and command; wspai is only a
shorter optional name.
Connect an existing project without moving it, then create one saved, checkable view for developers, CI, IDEs, MCP clients, and AI agents:
cd /absolute/path/to/project
npx workspai adopt .adopt keeps the project in place and creates or reuses the minimal default
workspace. Continue from the same project terminal:
npx workspai project workspace status --json
npx workspai workspace intelligence run --for-agent generic --strict --jsonThe first command proves which canonical workspace owns the project. Workspai
uses a gitignored machine-local binding and portable project grounding, so
workspace commands and compatible agents do not need a manual cd.
Use generic for a vendor-neutral context pack, or select codex, claude,
cursor, or orca. Agent Sync also publishes shared files for GitHub Copilot,
VS Code, and AGENTS.md consumers.
Use the release pipeline when you need the broader release workflow:
npx workspai pipeline --json --strictAdoption keeps source in place. The command maps the system and its
connections, checks what changes may affect, runs health and release checks,
and prepares focused AI context under .workspai/. When the workspace is not
ready, the report shows the reason and points to the files or reports behind
it. Automation details and supported AI tools are documented in the
Unified runner. See the
Artifact Catalog for exact paths, writers,
schemas, and consumers.
To start with a new workspace instead:
npx workspai create workspace my-workspace --profile minimal --yes
cd ~/.workspai/workspaces/my-workspace
npx workspai create project nextjs web --yesFrom the workspace terminal, create a project, use adopt to link one in place,
or use import to copy or clone one into the workspace.
- Choose a guide by goal
- User documentation
- Operations & security
- AI module recommendations
- Technical contracts
- Contributor documentation
- Validation commands
| I want to… | Start here | Expected outcome |
|---|---|---|
| Create a workspace or project | Creating workspaces and projects | A registered project with canonical .workspai metadata |
| Bring an existing repository under governance | Workspace operations | Source stays in place with adopt, or is copied/cloned with import |
| Run the complete intelligence loop | Unified runner | One ordered run report with durable stage evidence |
| Set a release, security, or coverage outcome | Verified engineering goals | A durable success contract with a current evidence-backed verdict |
| Ask an architecture or dependency question | Workspace Knowledge Graph | A bounded answer with proof references rather than the whole graph |
| Measure agent token, cost, and outcome efficiency | Workspace Intelligence Evaluation | A live, provenance-aware report suitable for CLI, IDE, and CI |
| Integrate CI or release gates | CI workflows | Machine-readable exit codes and uploadable evidence |
| Find the writer, schema, or path for an output | Artifact Catalog | One canonical source instead of path guessing |
| Understand Workspai terminology | Glossary | Shared meanings for model, graph, evidence, gate, and artifacts |
| Review or change the main product README | README content contract | Stable narrative, claim boundaries, and machine-enforced drift rules |
| Contribute to the CLI | Development | Local build, test, contract, and documentation gates |
There are two different AI-facing features. Workspace Intelligence is deterministic, proof-backed, and does not require an AI API key. The optional module recommender uses embeddings to suggest FastAPI or NestJS modules; start with AI Quickstart only when that is your goal.
| Document | Description |
|---|---|
| creating-workspaces-and-projects.md | Plain-language guide to every workspace and project creation scenario |
| commands-reference.md | Full CLI syntax, profiles, and policy keys |
| workspace-operations.md | Import, adopt, snapshots, archives, contracts, infra |
| workspace-run.md | Polyglot fleet orchestration (workspace run) |
| workspace-intelligence-runner.md | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption |
| workspace-knowledge-graph.md | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement |
| graph-benchmark-methodology.md | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules |
| workspace-intelligence-evaluation.md | Provider usage, cost provenance, verified outcomes, comparison, and extension consumption |
| GLOSSARY.md | Plain-language definitions for workspace, model, graph, evidence, gates, and AI integrations |
| README_CONTENT_CONTRACT.md | Required root README journey, architecture statements, claim policy, and drift guard |
| create-planner-capabilities.md | Native create, official, and existing lanes |
| ../contracts/project-entry-capability.v1.json | Contract: any readable project can enter through adopt/import when it can be registered |
| from-code-to-shared-understanding.md | GitHub-rendered Workspace Intelligence diagram |
| OPEN_SOURCE_USER_SCENARIOS.md | Role-based workflows (junior → enterprise) |
| doctor-command.md | Doctor scopes, CI exit codes, JSON evidence |
| config-file-guide.md | User config file (~/.workspairc.json, workspai.config.*, with legacy fallbacks) |
| WORKSPACE_MARKER_SPEC.md | Workspace marker format |
| PACKAGE_MANAGER_POLICY.md | npm-only policy for this repository |
Common tasks
- Create a workspace or project: creating-workspaces-and-projects.md
- Adopt an existing repo: workspace-operations.md#import-and-adoption
- Scaffold a frontend app: commands-reference.md (
create project nextjs <name>) - Canonical intelligence gate:
workspace intelligence run --for-agent generic --strict --json - Broader CI release gate: commands-reference.md (
pipeline,readiness) - Targeted model/context inspection — schemas in contracts/workspace-intelligence/
| Document | Description |
|---|---|
| SECURITY.md | Vulnerability reporting and supported versions |
| policies.workspace.example.yml | Workspace policy template |
| governance-policy.enterprise.example.json | Sigstore governance allowlist template |
| mirror-config.enterprise.example.json | Mirror + evidence export template |
FastAPI/NestJS module suggestions via OpenAI embeddings (optional).
| Document | Description |
|---|---|
| AI_QUICKSTART.md | 60-second setup |
| AI_FEATURES.md | Complete feature reference |
| AI_EXAMPLES.md | Use-case examples |
| AI_DYNAMIC_INTEGRATION.md | Integration architecture |
JSON schemas and ownership rules for tooling parity.
| Location | Description |
|---|---|
| contracts/README.md | Core CLI JSON contracts + generator scripts |
| contracts/COMMAND_OWNERSHIP_MATRIX.md | npm wrapper vs Core command ownership |
| contracts/RUNTIME_SUPPORT_MATRIX.md | Scaffold/import/lifecycle support tiers |
| contracts/RUNTIME_ACCEPTANCE_MATRIX.md | Runtime acceptance test expectations |
| ../contracts/ | Canonical JSON schemas (published in npm tarball) |
Regenerate and verify:
npm run generate:contracts
npm run check:generated-contracts
npm run contracts:validate| Document | Description |
|---|---|
| DEVELOPMENT.md | Local dev, testing, debugging |
| SETUP.md | Build gates, smoke flows, release hygiene |
| ci-workflows.md | GitHub Actions workflow map |
| OPTIMIZATION_GUIDE.md | Performance and improvement notes |
| UTILITIES.md | Internal cache and metrics helpers |
Also see ../CONTRIBUTING.md and ../CHANGELOG.md.
npm run validate:docs # links + drift guard + examples + README smoke
npm run check:markdown-links # local markdown link integrity
npm run validate:docs-examples # example JSON/YAML in docs
npm run smoke:readme # CLI help smoke for documented commandsworkspai/
├── README.md # Monorepo overview
├── package.json # Private workspace root
└── packages/
└── cli/
├── README.md # CLI user hub (install, quickstarts, doc links)
├── CHANGELOG.md
├── RELEASE_NOTES.md
├── releases/ # Per-version release notes
└── docs/
├── README.md # This index
├── README_CONTENT_CONTRACT.md
├── commands-reference.md
├── workspace-knowledge-graph.md
├── workspace-intelligence-evaluation.md
├── workspace-operations.md
├── workspace-run.md
├── ci-workflows.md
├── doctor-command.md
├── OPEN_SOURCE_USER_SCENARIOS.md
├── config-file-guide.md
├── SECURITY.md
├── SETUP.md
├── DEVELOPMENT.md
├── contracts/ # Contract docs (mirrors + matrices)
└── … # AI guides, policies, examples
Enterprise governance runbooks are maintained outside this OSS docs tree.