@decantr/cli 3.6.1 → 3.7.0

package/README.md

@@ -19,11 +19,11 @@ npx @decantr/cli new my-app --blueprint=esports-hq
 ```
 
 Use `decantr setup` when you are unsure which path applies. It detects whether the repo is empty, already attached, or a Brownfield app and recommends the right entry path.
-Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files, detects framework/routes/styling/static-hosting/assistant-rule signals, previews typed Contract graph readiness in memory when a Decantr contract already exists, reports the contract capsule source-handle count and limit, prints a terminal report, and writes no `.decantr` files or report artifacts. Add `--json` when automation needs the `ScanReportV1` payload.
+Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files through the shared verifier discovery substrate, detects workspace/app scope, package manager, framework, language, route signals, taskable routes, component inventory confidence, styling/static-hosting/assistant-rule signals, previews typed Contract graph readiness in memory when a Decantr contract already exists, reports the contract capsule source-handle count and limit, prints a terminal report, and writes no `.decantr` files or report artifacts. Add `--json` when automation needs the `ScanReportV2` payload.
 Use `decantr new` for a greenfield workspace in a fresh directory. With a starter-kit blueprint or archetype it uses the runnable adapter and Decantr CSS; without certified vocabulary content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr adopt` 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, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
-Use `decantr studio` after adoption when you want a local Control Room for routes, findings, evidence, authority, and next actions. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, `decantr resolve` when source and contract disagree, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and hosted packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Route and impact ranking use deterministic weighted traversal plus local personalized PageRank and task boosts. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
-In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Candidate discovery ranks product UI apps ahead of docs, Storybook, API, MCP helper, workbench, and package surfaces; `decantr workspace list --json` includes rank, category, score, and reason metadata so automation can explain why `apps/web`, `apps/remix`, or `apps/dashboard` was suggested first. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred hosted packs are optional context unless a present manifest references missing files.
+Use `decantr studio` after adoption when you want a local Control Room for routes, findings, evidence, authority, and next actions. Use `decantr connect cursor` when the opened workspace should get Cursor Agent MCP and project-rule activation; in monorepos use `decantr connect cursor --project apps/web` so the rule keeps the app scope. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, `decantr resolve` when source and contract disagree, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and hosted packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Route and impact ranking use deterministic weighted traversal plus local personalized PageRank and task boosts. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
+In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Candidate discovery ranks product UI apps ahead of docs, Storybook, API, MCP helper, workbench, and package surfaces; `decantr workspace list --json` includes rank, category, score, and reason metadata so automation can explain why `apps/web`, `apps/remix`, or `apps/dashboard` was suggested first. Once an app path is selected, scan/setup/adopt/doctor/task/verify/ci/connect preserve that app scope and inherit package-manager evidence from the workspace root, so a React app inside a pnpm Angular/React monorepo is reported as the React app, not the root or sibling app. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred hosted packs are optional context unless a present manifest references missing files.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
 App-scoped primitives now share the same `--project` posture as the primary workflow commands. From a workspace root, `health`, `status`, `upgrade`, `add`, `remove`, `theme`, `export`, `suggest`, `magic`, `rules`, and `telemetry` target the selected app instead of the root. Task/read paths, local-law summaries, and refresh change summaries are printed as openable workspace paths. Nonexistent project paths fail immediately, and Brownfield adoption refuses component packages unless you intentionally pass `--force-package`.
@@ -70,6 +70,7 @@ decantr init --existing --adoption=style-bridge
 decantr init --existing --adoption=decantr-css
 decantr init --project=apps/web --yes
 decantr init --assistant-bridge=preview
+decantr connect cursor --preview
 decantr rules preview
 decantr rules apply
 ```
@@ -93,7 +94,7 @@ pnpm exec decantr codify --map-pattern hero --project apps/web
 pnpm exec decantr ci init --project apps/web
 ```
 
-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. When `.decantr/graph/contract-capsule.json` exists, `decantr task` includes it in the read list and JSON payload so CLI-only agents can load the typed Contract capsule and its SourceArtifact path index before route-specific edits. When `.decantr/graph/graph.snapshot.json` exists, `decantr task --json` also includes `graph.routeContext`: the route node, scoped page/shell/pattern/component/token nodes, local law/style bridge nodes, behavior-obligation LocalRule nodes, open findings/evidence IDs, deterministic ranked nodes boosted by the task text, and the supporting edges. Accepted `.decantr/local-patterns.json` `behavior_obligations` also appear in `localLaw.patterns[].behaviorObligations` and `localLaw.behaviorObligations` so agents see project-owned dialog/form obligations before editing. If git changed files resolve to SourceArtifact nodes, `decantr task --json` also includes `graph.changedFileContext` so an agent can see source-file blast radius before editing or repairing the current diff.
+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. Cursor has a direct connector: `decantr connect cursor` writes `.cursor/mcp.json` and `.cursor/rules/decantr.mdc`, preserving existing MCP servers; use `--preview` to inspect first and `--project <app>` from a monorepo root. When `.decantr/graph/contract-capsule.json` exists, `decantr task` includes it in the read list and JSON payload so CLI-only agents can load the typed Contract capsule and its SourceArtifact path index before route-specific edits. When `.decantr/graph/graph.snapshot.json` exists, `decantr task --json` also includes `graph.routeContext`: the route node, scoped page/shell/pattern/component/token nodes, local law/style bridge nodes, behavior-obligation LocalRule nodes, open findings/evidence IDs, deterministic ranked nodes boosted by the task text, and the supporting edges. Accepted `.decantr/local-patterns.json` `behavior_obligations` also appear in `localLaw.patterns[].behaviorObligations` and `localLaw.behaviorObligations` so agents see project-owned dialog/form obligations before editing. If git changed files resolve to SourceArtifact nodes, `decantr task --json` also includes `graph.changedFileContext` so an agent can see source-file blast radius before editing or repairing the current diff.
 
 `decantr scan` is different from the mutating Brownfield primitives: it is look-don't-touch reconnaissance for fit, route/style evidence, GitHub Pages hints, typed Contract graph readiness, capsule source-handle bounds, and next-command guidance. For attached Essence V4 apps it derives the graph preview in memory, reports stale/missing `.decantr/graph` artifacts, and still writes nothing. `decantr analyze` 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. It also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. 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. Theme variants are observed in the theme inventory without changing Essence V4. `decantr adopt` writes the first typed Contract graph baseline before verification so Project Health, task context, and agents can anchor to graph artifacts immediately. `decantr codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json` with Hybrid authority guidance, source-derived button/card/form/theme evidence, variant hints, confidence tiers, and optional `behavior_obligations` for form controls and destructive confirmation dialogs when source evidence is strong; `decantr codify --style-bridge` proposes `.decantr/style-bridge.proposal.json`, mapping Decantr intent to project-owned tokens/classes without requiring `@decantr/css`; `decantr codify --map-pattern <slug>` maps a hosted or bundled registry pattern into an advisory local-law proposal without changing source. After review, `decantr codify --accept` promotes whichever proposals exist. `decantr doctor` reports whether the app is contract-only, Hybrid local law, style bridge, Decantr CSS, or Hybrid composition. `decantr task` prints that authority block and warns before mixing runtimes or adding Decantr CSS to a non-Decantr-CSS app. `decantr suggest --from-code` surfaces accepted local patterns and style bridge mappings from the app root or selected `--project`, and `decantr ci` prints accepted local-rule findings, behavior-obligation findings, plus style bridge status in text, markdown, and JSON reports. `decantr verify --brownfield --local-patterns` uses the Brownfield guard layer plus accepted local law to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, behavior-obligation drift, style drift, raw local-rule violations, and unsafe defaults without treating current database migrations as stale docs.
 
@@ -101,10 +102,12 @@ Assistant rule integration is preview-first: `--assistant-bridge=preview` writes
 
 - scaffolds Decantr projects from blueprints, archetypes, or prompts
 - previews existing apps with read-only Brownfield scan reports
-- guides users through human workflow commands: setup, adopt, doctor, task, verify, ci, and codify
+- emits `scan-report.v2` JSON with discovery evidence, app scope, route signal/taskable route counts, component inventory confidence, and limitations
+- guides users through human workflow commands: setup, adopt, doctor, task, verify, ci, codify, and connect
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, Hybrid local law, Hybrid style bridge, Hybrid Decantr CSS, and hybrid composition
 - ranks monorepo app candidates with explainable metadata so product UI apps come before docs, Storybook, API, helper packages, and workbench surfaces
 - generates execution-pack context files for AI coding assistants
+- connects Cursor Agent to Decantr MCP and project rules with `decantr connect cursor`
 - generates typed Contract graph artifacts, replayable snapshot history, graph diffs, manifests, source-file impact context, style-bridge Token nodes, behavior-obligation LocalRule nodes, and `contract-capsule.json` for agent sessions
 - audits projects against Decantr contracts
 - produces local Project Health reports, Evidence Bundles, workspace health, and a localhost Studio dashboard for end-user drift triage
@@ -117,7 +120,7 @@ Assistant rule integration is preview-first: `--assistant-bridge=preview` writes
 
 ## Security And Permissions
 
-The CLI is intentionally a local project inspector and artifact writer. It reads selected project/workspace files, package manifests, routing/style/config files, `.decantr` artifacts, and Decantr cache/config files. It writes `decantr.essence.json`, `DECANTR.md`, `.decantr/*`, generated context packs, `.decantr/graph/*` typed graph artifacts, optional CI workflows/snippets, optional style/export files, and auth/telemetry config only when explicitly requested. `decantr scan` is the exception by design: it reads and prints only, and does not create `.decantr`, save reports, upload source, run package scripts, or install dependencies.
+The CLI is intentionally a local project inspector and artifact writer. It reads selected project/workspace files, package manifests, routing/style/config files, `.decantr` artifacts, and Decantr cache/config files. It writes `decantr.essence.json`, `DECANTR.md`, `.decantr/*`, generated context packs, `.decantr/graph/*` typed graph artifacts, optional CI workflows/snippets, optional Cursor MCP/rule files, optional style/export files, and auth/telemetry config only when explicitly requested. `decantr scan` is the exception by design: it reads and prints only, and does not create `.decantr`, save reports, upload source, run package scripts, or install dependencies.
 
 Telemetry is disabled by default. Hosted registry, hosted pack hydration, hosted critique/audit, and browser evidence are explicit command paths; screenshots and Evidence Bundles stay local unless a hosted workflow is invoked. Release audits prove the installed package with `npm pack --dry-run --json`. See [security permissions](https://decantr.ai/reference/security-permissions.md).
 
@@ -155,6 +158,8 @@ decantr init --existing --blueprint=esports-hq
 decantr init --workflow=greenfield --adoption=contract-only
 decantr rules preview
 decantr rules apply
+decantr connect cursor
+decantr connect cursor --project apps/web --preview
 decantr magic "AI-native analytics workspace"
 decantr audit
 decantr check

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-TGVBWTDK.js";
-import "./chunk-SIDKK73N.js";
+import "./chunk-O7N4CCWS.js";
+import "./chunk-NDH3BDXY.js";
 import "./chunk-56HUEUO3.js";
 import "./chunk-WAGVDMJV.js";
 import "./chunk-24JR4ZNG.js";

package/dist/{chunk-SIDKK73N.js → chunk-NDH3BDXY.js}

@@ -5075,65 +5075,65 @@ function generateSyntheticSlots(patternId, description) {
   const desc = description.toLowerCase();
   const syntheticSlots = {};
   if (patternId.includes("feature") || desc.includes("feature")) {
-    syntheticSlots["grid"] = "Grid of feature cards (icon + title + description)";
+    syntheticSlots.grid = "Grid of feature cards (icon + title + description)";
     syntheticSlots["feature-card"] = "Individual feature with icon, heading, and description text";
   }
   if (patternId.includes("pricing") || desc.includes("pricing")) {
-    syntheticSlots["tiers"] = "Pricing tier cards (name, price, features list, CTA button)";
-    syntheticSlots["toggle"] = "Monthly/annual billing toggle (optional)";
+    syntheticSlots.tiers = "Pricing tier cards (name, price, features list, CTA button)";
+    syntheticSlots.toggle = "Monthly/annual billing toggle (optional)";
   }
   if (patternId.includes("testimonial") || desc.includes("testimonial")) {
-    syntheticSlots["quotes"] = "Testimonial cards (quote text, author name, role, avatar)";
+    syntheticSlots.quotes = "Testimonial cards (quote text, author name, role, avatar)";
   }
   if (patternId.includes("cta") || desc.includes("call-to-action") || desc.includes("call to action")) {
-    syntheticSlots["headline"] = "CTA headline text";
-    syntheticSlots["description"] = "Supporting description text";
-    syntheticSlots["actions"] = "CTA button(s)";
+    syntheticSlots.headline = "CTA headline text";
+    syntheticSlots.description = "Supporting description text";
+    syntheticSlots.actions = "CTA button(s)";
   }
   if (patternId.includes("how-it-works") || desc.includes("how it works") || desc.includes("timeline") || desc.includes("steps")) {
-    syntheticSlots["steps"] = "Numbered steps (step number, title, description)";
+    syntheticSlots.steps = "Numbered steps (step number, title, description)";
   }
   if (patternId.includes("team") || desc.includes("team")) {
-    syntheticSlots["members"] = "Team member cards (avatar, name, role)";
+    syntheticSlots.members = "Team member cards (avatar, name, role)";
   }
   if (patternId.includes("story") || desc.includes("story") || desc.includes("about")) {
-    syntheticSlots["content"] = "Story/about narrative text content";
+    syntheticSlots.content = "Story/about narrative text content";
   }
   if (patternId.includes("values") || desc.includes("values")) {
-    syntheticSlots["values"] = "Value cards (icon/emoji, title, description)";
+    syntheticSlots.values = "Value cards (icon/emoji, title, description)";
   }
   if (patternId.includes("form") || desc.includes("form") || desc.includes("contact")) {
-    syntheticSlots["fields"] = "Form fields (name, email, message, etc.)";
-    syntheticSlots["submit"] = "Submit button";
+    syntheticSlots.fields = "Form fields (name, email, message, etc.)";
+    syntheticSlots.submit = "Submit button";
   }
   if (patternId.includes("content") || desc.includes("legal") || desc.includes("privacy") || desc.includes("policy")) {
-    syntheticSlots["body"] = "Long-form text content with headings and paragraphs";
-    syntheticSlots["toc"] = "Table of contents sidebar (optional)";
+    syntheticSlots.body = "Long-form text content with headings and paragraphs";
+    syntheticSlots.toc = "Table of contents sidebar (optional)";
   }
   if (patternId.includes("settings") || desc.includes("settings") || desc.includes("preferences")) {
-    syntheticSlots["sections"] = "Settings sections (label, description, input/toggle)";
+    syntheticSlots.sections = "Settings sections (label, description, input/toggle)";
   }
   if (patternId.includes("security") || desc.includes("security") || desc.includes("password")) {
-    syntheticSlots["sections"] = "Security sections (password change, MFA toggle, session list)";
+    syntheticSlots.sections = "Security sections (password change, MFA toggle, session list)";
   }
   if (patternId.includes("session") || desc.includes("session")) {
-    syntheticSlots["list"] = "Active sessions list (device, location, last active, revoke button)";
+    syntheticSlots.list = "Active sessions list (device, location, last active, revoke button)";
   }
   if (patternId.includes("message") || desc.includes("message") || desc.includes("chat")) {
-    syntheticSlots["messages"] = "Message bubbles (user/assistant, content, timestamp)";
+    syntheticSlots.messages = "Message bubbles (user/assistant, content, timestamp)";
   }
   if (patternId.includes("input") && desc.includes("chat")) {
-    syntheticSlots["textarea"] = "Auto-expanding message input";
-    syntheticSlots["actions"] = "Attach file button, send button";
+    syntheticSlots.textarea = "Auto-expanding message input";
+    syntheticSlots.actions = "Attach file button, send button";
   }
   if (patternId.includes("empty") || desc.includes("empty")) {
-    syntheticSlots["illustration"] = "Empty state illustration or icon";
-    syntheticSlots["message"] = "Welcome/empty state message";
-    syntheticSlots["suggestions"] = "Suggested actions or prompts";
+    syntheticSlots.illustration = "Empty state illustration or icon";
+    syntheticSlots.message = "Welcome/empty state message";
+    syntheticSlots.suggestions = "Suggested actions or prompts";
   }
   if (patternId.includes("header") && desc.includes("chat")) {
-    syntheticSlots["title"] = "Conversation title or model name";
-    syntheticSlots["actions"] = "Header action buttons (new chat, settings)";
+    syntheticSlots.title = "Conversation title or model name";
+    syntheticSlots.actions = "Header action buttons (new chat, settings)";
   }
   return syntheticSlots;
 }