workspai 0.45.0 → 0.46.0

package/docs/creating-workspaces-and-projects.md

@@ -0,0 +1,649 @@
+# Creating Workspaces and Projects
+
+This guide explains, in plain language, what Workspai does when you create a
+workspace or a project. It covers interactive commands, automation, project
+locations, workspace linking, supported kits, and the most important flags.
+
+For a compact list of command syntax, see
+[commands-reference.md](./commands-reference.md).
+
+## The two things you can create
+
+A **workspace** is the governed boundary that holds project registrations,
+policies, contracts, and Workspace Intelligence reports.
+
+A **project** is an application or service, such as a FastAPI API, Go service,
+Spring Boot service, .NET API, or frontend application.
+
+The canonical commands are:
+
+```bash
+npx workspai create workspace <name>
+npx workspai create project <kit> <name>
+```
+
+Use the canonical commands in scripts and documentation. The older
+`workspai <name> --template <kit>` form is supported for compatibility, but it
+does not have exactly the same behavior.
+
+## Quick decision table
+
+| What you want                                                   | Command                                                                     |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Choose interactively                                            | `npx workspai create`                                                       |
+| Create a managed workspace                                      | `npx workspai create workspace platform --yes`                              |
+| Create a workspace under the current directory                  | `npx workspai create workspace platform --here --yes`                       |
+| Create a project and use the current/default workspace behavior | `npx workspai create project gofiber.standard api`                          |
+| Turn the current folder into a workspace before creating        | `npx workspai create project gofiber.standard api --create-workspace --yes` |
+| Create a project without workspace management                   | `npx workspai create project gofiber.standard api --no-workspace --yes`     |
+| Preview a supported create plan                                 | `npx workspai create project frontend.nextjs web --dry-run`                 |
+
+# Creating a workspace
+
+## Create in the managed Workspai location
+
+```bash
+npx workspai create workspace platform --yes
+```
+
+The default target is:
+
+```text
+~/.workspai/workspaces/platform
+```
+
+With `--yes`, Workspai does not ask questions. If you do not provide a
+profile, it uses `minimal`.
+
+## Create under the current directory
+
+```bash
+npx workspai create workspace platform --here --yes
+```
+
+If the current directory is `/home/me/code`, the result is:
+
+```text
+/home/me/code/platform
+```
+
+`--here` means "create the named workspace as a child of this directory." It
+does not turn the current directory itself into a workspace.
+
+## Create under another parent directory
+
+```bash
+npx workspai create workspace platform --output /data/workspaces --yes
+```
+
+The result is:
+
+```text
+/data/workspaces/platform
+```
+
+`--output` is always the parent directory. Workspai adds the workspace name to
+it.
+
+Relative output paths are resolved from the current directory:
+
+```bash
+npx workspai create workspace platform --output teams --yes
+```
+
+This creates `<current-directory>/teams/platform`.
+
+## Use the interactive workspace wizard
+
+```bash
+npx workspai create workspace
+```
+
+When values are missing, Workspai can ask for:
+
+- The workspace name
+- The managed home or current-directory location
+- The author name
+- The workspace profile
+- Whether to install the optional Python engine
+- The Python environment method when installation is selected
+
+You can also start one level higher:
+
+```bash
+npx workspai create
+```
+
+In an interactive terminal, this first asks whether you want to create a
+workspace or a project.
+
+## Workspace profiles
+
+| Profile       | Intended runtime scope                           | Python engine by default |
+| ------------- | ------------------------------------------------ | ------------------------ |
+| `minimal`     | Lightweight workspace foundation                 | No                       |
+| `node-only`   | Node.js projects                                 | No                       |
+| `go-only`     | Go projects                                      | No                       |
+| `java-only`   | Java projects                                    | No                       |
+| `dotnet-only` | .NET projects                                    | No                       |
+| `python-only` | Python projects                                  | Yes                      |
+| `polyglot`    | Multiple runtimes                                | Yes                      |
+| `enterprise`  | Multiple runtimes with governance-oriented setup | Yes                      |
+
+Example:
+
+```bash
+npx workspai create workspace platform --profile go-only --yes
+```
+
+## Keep a Python-aware profile without installing Python now
+
+```bash
+npx workspai create workspace platform \
+  --profile polyglot \
+  --skip-python-engine \
+  --yes
+```
+
+The workspace remains `polyglot`, but its metadata records the Python engine as
+`skipped`. Workspace Intelligence, project registration, import, adopt, model,
+context, and verify remain available.
+
+Use `--skip-python-engine` for workspace creation. For project creation, use
+`--skip-install` instead.
+
+## If Python is not installed
+
+Python-free profiles do not require Python.
+
+For a Python-aware profile, interactive mode offers guidance and fallback
+choices. In non-interactive `--yes` mode, Workspai falls back to a Python-free
+profile when Python is unavailable:
+
+| Requested profile | Fallback profile |
+| ----------------- | ---------------- |
+| `python-only`     | `minimal`        |
+| `polyglot`        | `node-only`      |
+| `enterprise`      | `node-only`      |
+
+If Poetry is selected but unavailable, Workspai can use a local virtual
+environment instead.
+
+## Git behavior for a new workspace
+
+Git initialization is enabled by default. Disable it with:
+
+```bash
+npx workspai create workspace platform --skip-git --yes
+```
+
+If the target is already inside another Git worktree, Workspai avoids creating
+a nested repository. A missing Git installation or a failed initial commit
+produces a warning but does not remove an otherwise valid workspace.
+
+## Preview workspace creation
+
+```bash
+npx workspai create workspace platform \
+  --profile polyglot \
+  --skip-python-engine \
+  --skip-git \
+  --dry-run
+```
+
+The preview shows the target, profile, Python plan, Git plan, expected files,
+and next steps. It does not create a workspace, install Python, initialize Git,
+or update a registry.
+
+## Existing target directories
+
+Workspace creation does not merge into or overwrite an existing target. If the
+resolved directory already exists, choose another name or output parent.
+
+To bring an existing repository into Workspai, use `adopt` or `import` instead:
+
+```bash
+npx workspai adopt /path/to/project
+```
+
+## Main workspace files
+
+A normal workspace includes:
+
+```text
+.workspai-workspace
+.workspai/workspace.json
+.workspai/toolchain.lock
+.workspai/policies.yml
+.workspai/cache-config.yml
+.workspai/workspace.contract.json
+.workspai/workspace-registry.v1.json
+.gitignore
+README.md
+```
+
+The user-level workspace registry is stored under the Workspai home, normally:
+
+```text
+~/.workspai/workspaces.json
+```
+
+# Creating a project
+
+## Choose a kit interactively
+
+```bash
+npx workspai create project
+```
+
+Workspai asks for a kit and project name. You can also use the top-level wizard:
+
+```bash
+npx workspai create
+```
+
+If you choose project creation, the same project flow is used.
+
+When the terminal is interactive and the current directory is not inside a
+workspace, **every supported backend and frontend kit** shows the workspace
+management question before scaffolding:
+
+```text
+This project is outside a Workspai workspace. How should it be managed?
+
+1. Link it to the managed default workspace (recommended)
+2. Turn the current folder into a workspace
+3. Create it without workspace management
+```
+
+This applies to direct commands and interactive kit selection.
+
+## Create a project with an explicit kit
+
+```bash
+npx workspai create project <kit> <name>
+```
+
+Examples:
+
+```bash
+npx workspai create project fastapi.standard api
+npx workspai create project gofiber.standard gateway
+npx workspai create project springboot.standard orders
+npx workspai create project dotnet.webapi.clean billing
+npx workspai create project frontend.nextjs dashboard
+```
+
+The shorter frontend alias remains available:
+
+```bash
+npx workspai create frontend nextjs dashboard
+```
+
+## Supported backend kits
+
+| Kit                   | Runtime | Scaffold owner       | Core module mutation |
+| --------------------- | ------- | -------------------- | -------------------- |
+| `fastapi.standard`    | Python  | RapidKit Core        | Yes                  |
+| `fastapi.ddd`         | Python  | RapidKit Core        | Yes                  |
+| `nestjs.standard`     | Node.js | RapidKit Core bridge | Yes                  |
+| `gofiber.standard`    | Go      | Workspai npm CLI     | No                   |
+| `gogin.standard`      | Go      | Workspai npm CLI     | No                   |
+| `springboot.standard` | Java    | Workspai npm CLI     | No                   |
+| `dotnet.webapi.clean` | .NET    | Workspai npm CLI     | No                   |
+
+NestJS runs on Node.js, but its current scaffold is provided through the
+RapidKit Core bridge.
+
+## Supported frontend generators
+
+Workspai has official-generator paths for:
+
+| Frontend             | Common kit name               |
+| -------------------- | ----------------------------- |
+| Next.js              | `nextjs` or `frontend.nextjs` |
+| React Router / Remix | `remix`                       |
+| React with Vite      | `vite-react`                  |
+| Vue with Vite        | `vite-vue`                    |
+| Svelte with Vite     | `vite-svelte`                 |
+| Solid with Vite      | `vite-solid`                  |
+| Vanilla Vite         | `vite-vanilla`                |
+| Nuxt                 | `nuxt`                        |
+| Angular              | `angular`                     |
+| Astro                | `astro`                       |
+| SvelteKit            | `sveltekit`                   |
+
+The ecosystem's official generator creates the application. Workspai then adds
+project metadata and performs the selected workspace registration.
+
+# Where the project is created
+
+The project path is always:
+
+```text
+(--output or current directory) + project name
+```
+
+Without `--output`:
+
+```bash
+npx workspai create project gofiber.standard gateway
+```
+
+This creates `<current-directory>/gateway`.
+
+With a relative output parent:
+
+```bash
+npx workspai create project gofiber.standard gateway --output services
+```
+
+This creates `<current-directory>/services/gateway`.
+
+With an absolute output parent:
+
+```bash
+npx workspai create project gofiber.standard gateway --output /data/apps
+```
+
+This creates `/data/apps/gateway`.
+
+Workspai does not overwrite or merge into an existing project directory.
+
+# Project creation inside a workspace
+
+## Create at the workspace root
+
+If the current directory is `/home/me/platform` and it is a workspace:
+
+```bash
+npx workspai create project gofiber.standard gateway
+```
+
+The project is created at `/home/me/platform/gateway` and registered with that
+workspace.
+
+## Create from a workspace subdirectory
+
+If the current directory is `/home/me/platform/services`, the same command
+creates `/home/me/platform/services/gateway`. Workspai does not force every
+project into the workspace root.
+
+## Create outside the current workspace with `--output`
+
+```bash
+npx workspai create project gofiber.standard gateway --output /data/apps
+```
+
+The project stays at `/data/apps/gateway` and is linked to the current
+workspace as an external project. Workspai does not move or copy its source.
+
+## Create directly inside another workspace
+
+If the final project path is inside workspace B but the command was launched
+from workspace A, the workspace found from the final project path takes
+priority. The project is registered with workspace B.
+
+# Project creation outside a workspace
+
+## Interactive behavior
+
+When no workspace is found and you did not provide an explicit workspace flag,
+Workspai asks how the project should be managed before scaffolding.
+
+The same question is shown for:
+
+- RapidKit Core-backed projects
+- Go, Spring Boot, and .NET npm-backed projects
+- All supported frontend generators
+- Direct `create project <kit> <name>` commands
+- Interactive `create` and `create project` kit selection
+
+## Choice 1: Link to the managed default workspace
+
+This is the recommended option.
+
+The project is created in the path you requested. After a successful scaffold,
+Workspai creates or reuses:
+
+```text
+~/.workspai/workspaces/workspai
+```
+
+The managed default workspace uses:
+
+| Setting                       | Value              |
+| ----------------------------- | ------------------ |
+| Name                          | `workspai`         |
+| Profile                       | `polyglot`         |
+| Python engine                 | `skipped`          |
+| Git initialization            | skipped            |
+| External project relationship | `linked` / adopted |
+
+The project is not moved and is not copied.
+
+The workspace is created only after the project scaffold succeeds. A failed
+scaffold does not create a new managed default workspace for that project.
+
+## Choice 2: Turn the current folder into a workspace
+
+Choose this interactively, or use:
+
+```bash
+npx workspai create project gofiber.standard gateway \
+  --create-workspace \
+  --yes
+```
+
+Unlike `create workspace --here`, this turns the current directory itself into
+a workspace. It then creates the project under the requested output parent.
+
+For example, from `/home/me/platform`:
+
+```text
+Workspace: /home/me/platform
+Project:   /home/me/platform/gateway
+```
+
+This uses the full current-folder workspace registration flow.
+
+## Choice 3: Create without workspace management
+
+Choose this interactively, or use:
+
+```bash
+npx workspai create project gofiber.standard gateway \
+  --no-workspace \
+  --yes
+```
+
+The project is scaffolded, but Workspai does not:
+
+- Create the managed default workspace
+- Turn the current directory into a workspace
+- Add the project to the global workspace registry
+- Link or adopt the project
+- Synchronize a workspace contract
+
+Do not combine `--create-workspace` and `--no-workspace`. In the current CLI,
+`--no-workspace` takes precedence.
+
+## Non-interactive behavior and `--yes`
+
+In CI, a non-interactive terminal, or when `--yes` is supplied, Workspai cannot
+ask the three-way question. If no explicit workspace flag is present, it uses
+the managed default workspace behavior.
+
+```bash
+npx workspai create project gofiber.standard gateway --yes
+```
+
+To opt out in automation, be explicit:
+
+```bash
+npx workspai create project gofiber.standard gateway --no-workspace --yes
+```
+
+To turn the current directory into a workspace in automation:
+
+```bash
+npx workspai create project gofiber.standard gateway --create-workspace --yes
+```
+
+# How external linking works
+
+If a project is physically outside its workspace, Workspai records a linked
+relationship. The source remains in its original path.
+
+Project metadata includes:
+
+```text
+.workspai/project.json
+.workspai/adopt.json
+.workspai/adopt-readiness.json
+```
+
+Workspace metadata includes:
+
+```text
+.workspai/imported-projects.json
+.workspai/workspace.contract.json
+.workspai/workspace-registry.v1.json
+```
+
+The adoption policy records:
+
+```text
+mode: linked
+moved_source: false
+copied_source: false
+```
+
+Projects physically inside a workspace are registered normally and generally
+do not need `adopt.json`.
+
+# Common project flags
+
+| Flag                 | Meaning                                                                         |
+| -------------------- | ------------------------------------------------------------------------------- |
+| `--yes`              | Do not ask optional questions; use managed-default behavior outside a workspace |
+| `--output <parent>`  | Choose the parent directory for the project                                     |
+| `--create-workspace` | Turn the current directory into a workspace before scaffolding                  |
+| `--no-workspace`     | Scaffold without workspace registration or linking                              |
+| `--skip-install`     | Defer dependency installation or warm-up where the generator supports it        |
+| `--skip-git`         | Skip generator/wrapper Git initialization where supported                       |
+| `--dry-run`          | Show a create plan without normal finalization                                  |
+
+`--skip-install` has stack-specific behavior:
+
+| Project type        | Behavior                                                       |
+| ------------------- | -------------------------------------------------------------- |
+| FastAPI and NestJS  | Defers dependency and lock work                                |
+| Go Fiber and Go Gin | Skips `go mod tidy`                                            |
+| Spring Boot         | Skips Maven wrapper/dependency warm-up                         |
+| .NET                | Accepted, but there is no separate dependency warm-up step     |
+| Frontend            | Passed to official generators that support a no-install option |
+
+Project-level `--skip-python-engine` is rejected. It is only a workspace
+creation option.
+
+## Project dry runs
+
+All supported project dry runs are read-only and show the resolved kit, target,
+generator, and flags without creating the project tree.
+
+```bash
+npx workspai create project fastapi.standard api --dry-run
+npx workspai create project frontend.nextjs web --dry-run
+npx workspai create project gofiber.standard api --dry-run
+```
+
+# Workspace profile checks during project creation
+
+When a project is created from inside a workspace, Workspai compares the
+project runtime with the workspace profile.
+
+| Policy mode | Incompatible runtime behavior |
+| ----------- | ----------------------------- |
+| `warn`      | Show a warning and continue   |
+| `strict`    | Stop before registration      |
+
+Frontend projects are checked as Node.js projects. `--no-workspace` disables
+final registration, but it does not necessarily bypass the profile policy of an
+enclosing workspace.
+
+# Unsupported create requests
+
+Workspai does not guess a native scaffold for every ecosystem. Projects such as
+WordPress, Laravel, Symfony, Rails, generic PHP, Ruby, Rust, and other
+unregistered stacks should be created with their ecosystem tooling and then
+adopted:
+
+```bash
+npx workspai adopt /path/to/project
+```
+
+See [create-planner-capabilities.md](./create-planner-capabilities.md) for the
+native, official, and existing-project lanes.
+
+# Failure and cleanup behavior
+
+| Situation                                                | Result                                 |
+| -------------------------------------------------------- | -------------------------------------- |
+| Invalid name                                             | Stops before normal scaffold writes    |
+| Target directory already exists                          | Stops without merging or overwriting   |
+| Project scaffold fails                                   | Workspace linking does not run         |
+| Git initialization fails                                 | Usually warns and keeps the scaffold   |
+| Go or Maven dependency warm-up fails                     | Warns and keeps the scaffold           |
+| Workspace registration/finalization fails after scaffold | Lifecycle rollback restores metadata and removes a newly owned project tree |
+
+Create finalization uses a durable lifecycle transaction. On failure it restores
+captured metadata and removes only newly owned project/workspace trees; it never
+deletes pre-existing source. A residue is possible only if rollback cleanup
+itself fails, in which case the command reports the cleanup failure and leaves a
+recovery journal.
+
+# Recommended command patterns
+
+Interactive local use:
+
+```bash
+npx workspai create project
+```
+
+Automated creation linked to the managed default workspace:
+
+```bash
+npx workspai create project gofiber.standard api --yes --skip-install
+```
+
+Automated creation in a new current-folder workspace:
+
+```bash
+npx workspai create project gofiber.standard api \
+  --create-workspace \
+  --yes \
+  --skip-install
+```
+
+Automated standalone project creation:
+
+```bash
+npx workspai create project gofiber.standard api \
+  --no-workspace \
+  --yes \
+  --skip-install
+```
+
+Explicit workspace creation followed by project creation:
+
+```bash
+npx workspai create workspace platform \
+  --profile polyglot \
+  --skip-python-engine \
+  --yes
+
+cd ~/.workspai/workspaces/platform
+npx workspai create project frontend.nextjs web --yes
+npx workspai create project fastapi.standard api --yes --skip-install
+```

package/docs/doctor-command.md

@@ -304,7 +304,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '20.19.0'
       - run: npm ci
       - run: npx workspai doctor
 ```
@@ -313,8 +313,9 @@ jobs:
 
 | Code | Meaning                        |
 | ---- | ------------------------------ |
-| `0`  | checks passed or warnings only |
-| `1`  | blocking issues found          |
+| `0`  | Passed; local-profile warnings remain advisory |
+| `1`  | Errors, or warnings under `release`/`enterprise-strict`/`--strict` |
+| `2`  | Warning-only result under the `ci` profile or `--ci` |
 
 ## Enterprise Probe Extensions
 
@@ -457,7 +458,7 @@ Legacy evidence without `schemaVersion` is still accepted. Unknown versions are
 
 ```bash
 npx workspai bootstrap [--profile <profile>]
-npx workspai setup <python|node|go> [--warm-deps]
+npx workspai setup <python|node|go|java|dotnet> [--warm-deps]
 npx workspai workspace list
 npx workspai cache <status|clear|prune|repair>
 npx workspai mirror <status|sync|verify|rotate>