Make the brownfield attach-web path explicit in docs

The attach-web workflow was implemented, but first-contact docs still described brownfield adoption conceptually instead of leading with the shipped CLI path. README, CLI docs, and the bring-your-own-web-app guides now start from 'fulora attach web', show the canonical attach->dev->package sequence, and explain that bridge drift is fixed explicitly with 'fulora generate types' rather than hidden auto-repair.

The implementation plan document is also updated to reflect the actual status of the slice so future work does not have to infer completion from code archaeology. Docs governance now enforces the brownfield wording so this path stays aligned with the shipped CLI.

Constraint: The approved DX slice explicitly avoided introducing doctor-style automation or hidden auto-fix behavior
Rejected: Leave the docs as conceptual architecture guidance only | users would still miss the shipped attach-web entry point
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep brownfield docs anchored on the explicit attach->dev->package flow unless the CLI path changes first
Tested: dotnet test tests/Agibuild.Fulora.Docs.UnitTests/Agibuild.Fulora.Docs.UnitTests.csproj
Tested: dotnet test tests/Agibuild.Fulora.Governance.UnitTests/Agibuild.Fulora.Governance.UnitTests.csproj --filter AutomationLaneGovernanceTests
Tested: dotnet tool restore && dotnet docfx docs/docfx.json
Tested: git diff --check
Not-tested: Broader project test suite beyond docs/governance surfaces (docs-only change)

Author: Hongwei-MB

README.md

@@ -32,12 +32,40 @@ Go deeper with [Getting Started](docs/articles/getting-started.md), the [Documen
 
 You do not need to rebuild your frontend to adopt Fulora.
 
-The recommended path is:
+The canonical brownfield path is:
+
+```text
+attach web -> dev -> package
+```
+
+In practice, start by wiring the existing frontend into a Fulora workspace:
+
+```bash
+fulora attach web \
+  --web ./app/web \
+  --desktop ./app/desktop \
+  --bridge ./app/bridge \
+  --framework react \
+  --web-command "npm run dev" \
+  --dev-server-url http://localhost:5173
+```
+
+Then use the saved `fulora.json` wiring for the normal loop:
+
+```bash
+fulora dev --preflight-only
+fulora package --profile desktop-public --preflight-only
+```
+
+The recommended flow is:
 
 1. keep your existing React/Vue/Next-style web app
-2. point Fulora at your dev server during development
-3. switch to embedded or packaged static assets in production
-4. add native capabilities gradually through typed app services
+2. run `fulora attach web` once to scaffold Fulora-owned files and persist `fulora.json`
+3. point Fulora at your dev server during development
+4. switch to embedded or packaged static assets in production
+5. add native capabilities gradually through typed app services
+
+If bridge artifacts drift, fix them explicitly with `fulora generate types`; the preflight commands report drift instead of silently auto-fixing files behind your back.
 
 In development, that usually looks like:
 

docs/articles/bring-your-own-web-app-quickstart.md

@@ -2,12 +2,31 @@
 
 If you already have a React, Vue, or similar web application, you can adopt Fulora without rewriting your frontend.
 
-The recommended path is:
+The recommended brownfield path is:
+
+```text
+attach web -> dev -> package
+```
+
+Start by wiring your existing frontend into a Fulora workspace:
+
+```bash
+fulora attach web \
+  --web ./app/web \
+  --desktop ./app/desktop \
+  --bridge ./app/bridge \
+  --framework react \
+  --web-command "npm run dev" \
+  --dev-server-url http://localhost:5173
+```
+
+This creates Fulora-owned wiring, writes `fulora.json`, and leaves the existing web app structure intact.
 
 1. keep your existing web project
-2. add a lightweight Avalonia + Fulora desktop host
-3. connect the host to your web dev server in development
-4. add native capabilities gradually through typed services
+2. run `fulora attach web` once
+3. add a lightweight Avalonia + Fulora desktop host
+4. connect the host to your web dev server in development
+5. add native capabilities gradually through typed services
 
 ## Development model
 
@@ -79,11 +98,14 @@ const profile = await services.userProfile.get();
 ## Useful commands
 
 ```bash
+fulora attach web --web ./app/web --framework react
 fulora dev --preflight-only
 fulora package --profile desktop-public --preflight-only
 fulora generate types --project ./app/bridge/MyProduct.Bridge.csproj
 ```
 
+If bridge artifacts are missing or stale, run `fulora generate types` explicitly. Fulora preflight checks report drift instead of silently rewriting files.
+
 ## Next step
 
 For the full recommended structure, integration steps, and troubleshooting guidance, see the full guide:

docs/articles/bring-your-own-web-app.md

@@ -6,6 +6,26 @@ If you already have a React, Vue, or similar web application, you do not need to
 
 This guide explains the recommended architecture, development flow, and best practices for that adoption path.
 
+The canonical brownfield path is:
+
+```text
+attach web -> dev -> package
+```
+
+Start by wiring the existing frontend into Fulora explicitly:
+
+```bash
+fulora attach web \
+  --web ./app/web \
+  --desktop ./app/desktop \
+  --bridge ./app/bridge \
+  --framework react \
+  --web-command "npm run dev" \
+  --dev-server-url http://localhost:5173
+```
+
+This scaffolds the Fulora-owned desktop + bridge wiring, creates `fulora.json`, and keeps your existing frontend business code intact.
+
 ## When to use this approach
 
 This guide is for teams that:
@@ -25,6 +45,24 @@ Typical fits include:
 
 If you are starting from scratch, use the standard Fulora template path first. If you already have a product, this “bring your own web app” path is usually the better starting point.
 
+## Brownfield workflow at a glance
+
+Use the commands in this order:
+
+```bash
+fulora attach web --web ./app/web --framework react
+fulora dev --preflight-only
+fulora package --profile desktop-public --preflight-only
+```
+
+If bridge artifacts drift, regenerate them explicitly:
+
+```bash
+fulora generate types --project ./app/bridge/MyProduct.Bridge.csproj
+```
+
+Fulora reports drift in preflight output instead of silently auto-fixing generated files during `dev` or `package`.
+
 ## Fulora’s role in an existing web app architecture
 
 When adopting Fulora in an existing product, the best mental model is:

docs/cli.md

@@ -26,6 +26,34 @@ fulora new MyApp --frontend vue --shell-preset app-shell
 | `--frontend`, `-f` | **Required.** `react`, `vue`, or `vanilla` |
 | `--shell-preset` | Desktop shell preset: `baseline` or `app-shell` |
 
+### `fulora attach web`
+
+Attach an existing web app to a Fulora desktop host without rewriting the frontend first.
+
+```bash
+fulora attach web --web ./app/web --desktop ./app/desktop --bridge ./app/bridge --framework react
+fulora attach web --web ./app/web --framework vue --web-command "npm run dev" --dev-server-url http://localhost:5173
+```
+
+This is the canonical brownfield path:
+
+```text
+attach web -> dev -> package
+```
+
+The command creates Fulora-owned wiring, writes `fulora.json`, and leaves your existing frontend business code intact.
+
+| Option | Description |
+|---|---|
+| `--web` | **Required.** Existing web project directory containing `package.json` |
+| `--desktop` | Desktop project directory to create/reuse |
+| `--bridge` | Bridge project directory to create/reuse |
+| `--framework` | `react`, `vue`, or `generic` |
+| `--web-command` | Existing frontend dev command to echo in next steps |
+| `--dev-server-url` | Existing frontend dev server URL such as `http://localhost:5173` |
+
+`fulora attach web` establishes the structure once. If generated bridge artifacts later drift, regenerate them explicitly with `fulora generate types`; Fulora reports drift in preflight checks instead of silently auto-fixing generated files.
+
 ### `fulora dev`
 
 Start the Vite dev server and Avalonia desktop app together. Run from the solution root.
@@ -47,6 +75,8 @@ Press **Ctrl+C** to stop both processes.
 
 Use `--preflight-only` when you want to validate bridge artifact consistency and project wiring without launching Vite or the desktop host.
 
+When `fulora.json` is present, `fulora dev` reuses the attached brownfield workspace configuration before falling back to heuristics.
+
 ### `fulora package`
 
 Package your app for distribution. The recommended first path is to start with a named profile.
@@ -86,6 +116,8 @@ The command now emits **preflight notes** before packaging when the selected pro
 
 Use `--preflight-only` when you want those checks without triggering `dotnet publish` or `vpk`.
 
+When `fulora.json` is present, `fulora package` reuses the configured desktop project before falling back to heuristics.
+
 ## Advanced Workflows
 
 Use these commands after the main path is already working.
@@ -111,6 +143,8 @@ fulora gen types --project ./MyApp.Bridge/MyApp.Bridge.csproj --output ./MyApp.W
 
 The generated `bridge.manifest.json` records the bridge project identity, artifact directory, build configuration, target framework, bridge assembly hash, and artifact hashes so `fulora dev` and `fulora package` can detect missing or stale generated outputs without relying only on timestamps.
 
+Use this command explicitly when bridge artifacts drift. Fulora surfaces the mismatch in preflight output; it does not silently auto-fix generated files during `dev` or `package`.
+
 ### `fulora add service <name>`
 
 Scaffold a new bridge service with three files: