Create and Adopt

Workspace Intelligence is not limited to frameworks Workspai can scaffold. The project-entry capability contract states the rule in plain language:

Any readable project can enter Workspace Intelligence through adopt/import.

There are two separate capabilities:

Existing projects can enter through adopt/import even when Workspai does not own their scaffold path. Registration still depends on a readable project path and enough observable metadata to create valid workspace records. Only specific kits can be created natively.

The runtime signals in the create planner are examples for detection, not a closed allowlist. Existing projects in other languages or frameworks can still enter Workspace Intelligence through adopt/import when they are readable and can be registered.

Create planner lanes

For an official path, Workspai runs the ecosystem's stable generator, records what was resolved, and then registers and synchronizes the resulting project. The ecosystem generator still owns its template; Workspai owns the workspace boundary and evidence around it.

latest-stable does not mean "ignore the current machine." The create planner publishes runtime requirements for generator paths that need a particular Node.js or ecosystem-tool version. Workspai checks those requirements before delegating. An available generator means the path is supported by Workspai; it can still require a compatible local runtime before it can execute.

Native create kits

Current native create coverage includes:

• fastapi.standard
• fastapi.ddd
• nestjs.standard
• springboot.standard
• gofiber.standard
• gogin.standard
• dotnet.webapi.clean
• rust.axum

Available official generator paths

Current official generator coverage includes:

• frontend.nextjs
• frontend.remix
• frontend.vite-react
• frontend.vite-vue
• frontend.vite-svelte
• frontend.vite-solid
• frontend.vite-vanilla
• frontend.nuxt
• frontend.angular
• frontend.astro
• frontend.sveltekit
• desktop.tauri
• desktop.electron
• extension.vscode
• php.laravel

Planned official handoffs include:

• wordpress-site
• wordpress-block
• symfony
• rails

Start with an existing project

The shortest path is to enter the project and adopt the current directory:

cd ~/code/storefront-web
npx workspai adopt .

When adopt runs outside an existing workspace, Workspai creates or reuses the managed minimal workspace, links the source project without moving it, and creates a project-native entry point. The project receives portable grounding and a bounded context lens, while the machine-local workspace path remains in a gitignored link file:

• AGENTS.md explains how an agent should enter the architecture;
• .workspai/reports/project-context-agent.json contains the project lens;
• .workspai/workspace-link.local.json resolves the governing workspace only on the current machine.

You can keep working from the project directory. Workspace-aware commands use the local link to resolve the governing workspace:

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

To choose a specific workspace explicitly:

npx workspai adopt . --workspace ~/workspaces/my-workspace

Use import when the source should be copied or cloned into the workspace instead of linked in place:

cd ~/workspaces/my-workspace
npx workspai import ~/code/orders-api --json

Create, adopt, import, and connect operations synchronize the workspace model, derived graph, report index, project lens, grounding, and selected agent surfaces. The project does not need to be moved for its agents and terminal to resolve the same workspace truth.

Re-running adopt is a refresh operation, not a duplicate registration. It reconciles project metadata and the linked boundary before regenerating model, graph, and grounding evidence. For a linked project, proof paths remain portable as external/<project>/...; machine-local absolute paths are not part of the default consumer payload.

What workspace creation leaves behind

A successful workspace creation ends with one compact terminal receipt. It names the workspace, profile, location, runtime foundation, synchronized consumer surfaces, evidence index, and the two useful next commands.

Workspai also writes a profile-aware README.md in the workspace. Its managed section shows:

• the current profile and registered-project count;
• whether the optional Python engine is installed;
• the canonical loop read from the versioned intelligence-chain contract;
• the evidence and agent entry points;
• focused create, sync, model, graph, Doctor, and intelligence commands.

Project creation, adoption, import, connection, and workspace sync refresh that managed section. If a user has added their own README content, Workspai preserves it and updates only the Workspai-managed section.

Start a new project

The interactive command groups kits by project kind:

npx workspai create

Current kinds include Backend, Frontend, Desktop, and Extension. Workspai does not install the optional Python engine merely because a workspace is created. Python setup is requested only when the selected project or module actually needs the Python-backed engine.

Project kind is operational, not decorative metadata. Doctor keeps Electron projects in the Desktop boundary and VS Code projects in the Extension boundary, so neither inherits unrelated generic frontend gates.

For automation, select a kit directly:

npx workspai create project rust.axum accounts-api --yes
npx workspai create project desktop.tauri operator-console --yes
npx workspai create project extension.vscode editor-tools --yes

Use adopt/import for existing repositories, unsupported scaffold paths, or systems that should enter Workspace Intelligence without being regenerated.

Do not read the create planner's existing runtime signals as the only supported adopt/import technologies. They are planner hints; the architecture boundary is the readable project and its observable workspace evidence.

Claim boundary

It is correct to say:

Existing projects can enter Workspace Intelligence through adopt/import.

It is not correct to say:

Workspai natively scaffolds every language and framework.

The first claim is architecture. The second claim would exceed the create planner contract.