@decantr/cli 1.7.28 → 1.8.0

package/README.md

@@ -18,7 +18,7 @@ npx @decantr/cli new my-app --blueprint=agent-marketplace
 ```
 
 Use `decantr new` for a greenfield workspace in a fresh directory. With a blueprint/archetype it uses the runnable adapter and Decantr CSS; without registry content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
-Use `decantr analyze` first when you already have an app and want Decantr governance without adopting a blueprint.
+Use `decantr analyze` first when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, and only applies it when you explicitly accept or merge it.
 Use `decantr init` to attach Decantr contract/context files to an existing project or to create a contract-only workspace.
 
 Current starter adapter availability:
@@ -31,11 +31,14 @@ Explicit workflow/adoption flags:
 
 ```bash
 decantr init --workflow=greenfield --adoption=contract-only
-decantr init --existing --adoption=contract-only
+decantr analyze
+decantr init --existing --accept-proposal
+decantr init --existing --merge-proposal
 decantr init --existing --adoption=style-bridge
 decantr init --existing --adoption=decantr-css
 decantr init --project=apps/web --yes
 decantr init --assistant-bridge=preview
+decantr rules preview
 decantr rules apply
 ```
 
@@ -47,7 +50,9 @@ Adoption modes:
 
 Monorepos store both `workspaceRoot` and `appRoot`. In non-interactive workspace-root runs with multiple app candidates, pass `--project=<path>` so Decantr attaches to the intended app.
 
-Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, while `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks.
+Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, `decantr rules preview` prints the bridge, and `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks.
+
+Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. `decantr check --brownfield` uses the doctrine map to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, and unsafe defaults without treating current database migrations as stale docs.
 
 ## What It Does
 
@@ -55,6 +60,7 @@ Assistant rule integration is preview-first: `--assistant-bridge=preview` writes
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, and hybrid composition
 - generates execution-pack context files for AI coding assistants
 - audits projects against Decantr contracts
+- produces local Project Health reports and a localhost Studio dashboard for end-user drift triage
 - searches the registry and showcase benchmark corpus
 - validates, refreshes, and maintains `decantr.essence.json`
 
@@ -63,17 +69,45 @@ Assistant rule integration is preview-first: `--assistant-bridge=preview` writes
 ```bash
 decantr new my-app --blueprint=agent-marketplace
 decantr analyze
-decantr init --existing --yes --adoption=contract-only
+decantr init --existing --accept-proposal
+decantr check --brownfield
 decantr init --existing --blueprint=agent-marketplace
 decantr init --workflow=greenfield --adoption=contract-only
+decantr rules preview
 decantr rules apply
 decantr magic "AI-native analytics workspace"
 decantr audit
 decantr check
+decantr health --ci --fail-on error
+decantr studio --port 4319 --host 127.0.0.1
 decantr registry summary --namespace @official --json
 decantr showcase verification --json
 ```
 
+## Project Health And Studio
+
+`decantr health` is the local project observability command. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, and AI-ready remediation prompts.
+
+```bash
+decantr health
+decantr health --format json
+decantr health --markdown --output health.md
+decantr health --ci --fail-on error
+decantr health --ci --fail-on warn
+decantr health --prompt <finding-id>
+```
+
+Use `--json` for machines and schema validation, `--markdown` for CI summaries, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. `--ci --fail-on error` fails only when blocking errors exist; `--ci --fail-on warn` also fails on warnings.
+
+`decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
+
+```bash
+decantr studio
+decantr studio --port 4319 --host 127.0.0.1
+```
+
+Studio is for local triage, not Decantr admin telemetry. The tabs cover Overview, Routes, Drift, Findings, Remediation, CI, and Packs without uploading source code, prompts, file paths, or project data.
+
 ## Greenfield Certification
 
 Use the built-in certification harness before releases when you want to prove that representative blueprints still scaffold into runnable starter projects:
@@ -115,8 +149,10 @@ It covers:
 
 - greenfield blueprint bootstrap
 - greenfield contract-only
-- brownfield `analyze -> init --existing`
-- direct brownfield init
+- brownfield `analyze -> init --existing --accept-proposal -> check --brownfield`
+- brownfield doctrine maps and contract coverage checks
+- brownfield semantic route-domain sectioning
+- direct brownfield compatibility init
 - adoption modes (`contract-only`, `style-bridge`, `decantr-css`)
 - offline contract-only and offline blueprint flows
 - unsupported target contract-only fallback
@@ -146,6 +182,8 @@ Recommended read order for AI-assisted scaffolding:
 
 Treat the compiled execution packs as the source of truth. Use the narrative docs as secondary explanation, start with the shell and route structure first, and run `decantr check` plus `decantr audit` after implementation.
 
+For a broader health pass, run `decantr health` after `refresh`, before opening a pull request, or inside CI. Findings include remediation commands and can be turned into focused AI prompts with `decantr health --prompt <finding-id>`.
+
 For cold-start harness or certification runs, use only the scaffolded workspace files as the contract. If local scaffold files disagree, stop and report the mismatch rather than relying on repo-global Decantr assumptions.
 
 ## Related Packages

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-56VBV4MT.js";
-import "./chunk-GCDFX7UE.js";
-import "./chunk-RRRHQ45P.js";
+import "./chunk-Y45MCRGI.js";
+import "./chunk-USOO77A5.js";
+import "./chunk-DI2PLOJ6.js";