Clarify README messaging for BEAR

Author: rore

README.md

@@ -1,30 +1,41 @@
-# BEAR (bear-cli)
+# BEAR
+
+Block Enforceable Architectural Representation
 
 <p align="center">
   <img src="assets/logo/bear-header-1400x320-clean.png" alt="BEAR logo" width="100%" />
 </p>
 
-BEAR is a deterministic governance CLI and CI gate for agentic backend development.
+Agents can generate large amounts of code very quickly.
+The dangerous changes are often structural: new dependencies, widened boundaries, and new authority surfaces.
+
+BEAR makes those architectural changes explicit and visible in CI.
+
+BEAR is a deterministic governance CLI and CI gate for agent-driven backend development.
+
+Demo repo: [bear-account-demo](https://github.com/rore/bear-account-demo)
 
-You edit code plus BEAR IR, then BEAR reports stable, machine-parseable signals: either green, or a precise failure with a remediation hint.
+When boundary authority changes, the agent updates BEAR IR first, BEAR compiles deterministic structural constraints, and then implementation code fits inside those constraints.
+The result is a stable, machine-parseable governance signal: either green, or a precise failure with a remediation hint.
 
 ```mermaid
 %% id: bear-workflow-v1
 flowchart LR
-  A[Agent / Dev edits code]:::actor --> B[Edit BEAR IR file]:::ir
+  A[Agent / Dev identifies boundary change]:::actor --> B[Update BEAR IR]:::ir
   B --> C[bear compile]:::cmd
-  C --> D[Generate boundary glue]:::gen
-  D --> E[bear check]:::cmd
-  E --> F{CI green?}:::gate
-  F -- yes --> G[Merge]:::ok
-  F -- no --> H[Fix code or IR]:::bad
+  C --> D[Generate structural constraints]:::gen
+  D --> E[Agent / Dev implements inside constraints]:::actor
+  E --> F[bear check]:::cmd
+  F --> G{CI green?}:::gate
+  G -- yes --> H[Merge]:::ok
+  G -- no --> I[Fix code or IR]:::bad
 
-  I[bear pr-check]:::cmd --> J{Boundary delta in PR?}:::gate
-  J -- none --> F
-  J -- expansion/bypass --> H
+  J[bear pr-check]:::cmd --> K{Boundary delta in PR?}:::gate
+  K -- none --> G
+  K -- expansion/bypass --> I
 
-  E -. emits .-> S1[[CI contract output:<br/>exit code + CODE/PATH/REMEDIATION]]:::signal
-  I -. emits .-> S2[[PR output:<br/>pr-delta + verdict + footer]]:::signal
+  F -. emits .-> S1[[CI contract output:<br/>exit code + CODE/PATH/REMEDIATION]]:::signal
+  J -. emits .-> S2[[PR output:<br/>pr-delta + verdict + footer]]:::signal
 
   classDef actor fill:#EEF2FF,stroke:#6366F1,color:#0B1220;
   classDef ir fill:#FFFBEB,stroke:#F59E0B,color:#0B1220;
@@ -39,11 +50,11 @@ flowchart LR
 
 ## What BEAR does (plain terms)
 
-- An agent updates code and (when needed) a small YAML IR contract (BEAR IR).
+- When boundary authority must change, the agent updates a small YAML IR contract (BEAR IR) first.
 - A block is a governed backend unit; its operations, allowed effects, and ports are declared in BEAR IR.
-- BEAR generates deterministic guardrails (wrappers/ports) from that declaration.
+- BEAR compiles that declaration into deterministic guardrails (wrappers, ports, manifests).
+- The agent then implements code inside those guardrails instead of inventing the boundary shape ad hoc.
 - Blocks interact only through declared ports; cross-boundary access outside a declared port is flagged as a violation (or PR signal).
-- Implementation can evolve freely inside those guardrails.
 - CI gets deterministic governance signals from `check` and `pr-check`.
 
 ## What you get
@@ -157,3 +168,7 @@ The demo currently showcases three PR outcomes:
 - Primary containment enforcement path is Java plus Gradle wrapper when `impl.allowedDeps` is declared.
 
 This project uses [Minimap](https://github.com/rore/minimap) for repo-local roadmap and feature planning.
+
+
+
+

docs/context/state.md

@@ -29,4 +29,6 @@ The packaged downstream CI integration is complete and stable, and `main` now al
 - Imported the parked Node discovery work into minimap and kept the recommendation intentionally narrow: do not pursue Node unless the product explicitly accepts the `node-ts-pnpm-single-package-v1` profile.
 - Added parked .NET discovery docs as a stronger-fit second-target candidate, focused on a narrow C# SDK-style profile with deterministic `dotnet` verification and project/package governance.
 - Archived or removed stale process docs that no longer earn their keep in a public repo, including the old simulation, grading, checkpoint, and duplicate board docs.
-- Verification: `./gradlew.bat --no-daemon :kernel:test`, `./gradlew.bat --no-daemon :app:test`, `./gradlew.bat --no-daemon :app:test :kernel:test`, `./gradlew.bat --no-daemon :app:test --tests com.bear.app.ContextDocsConsistencyTest`, `./gradlew.bat :app:compileJava :app:compileTestJava :kernel:compileJava :kernel:compileTestJava`.
+- Tightened README and public docs wording so the intended agent loop is explicit: boundary changes update IR first, BEAR compiles constraints, then implementation happens inside those constraints.
+- Verification: ./gradlew.bat --no-daemon :kernel:test, ./gradlew.bat --no-daemon :app:test, ./gradlew.bat --no-daemon :app:test :kernel:test, ./gradlew.bat --no-daemon :app:test --tests com.bear.app.ContextDocsConsistencyTest, ./gradlew.bat :app:compileJava :app:compileTestJava :kernel:compileJava :kernel:compileTestJava.
+

docs/public/DEMO.md

@@ -3,8 +3,9 @@
 BEAR is a deterministic governance CLI and CI gate for agentic backend development.
 
 In plain terms:
-- an agent updates code and BEAR IR
-- `bear compile` generates deterministic boundary glue
+- when boundary authority changes, the agent updates BEAR IR first
+- `bear compile` generates deterministic structural constraints from that IR
+- the agent implements code inside those constraints
 - `bear check` verifies repo consistency and covered bypasses
 - `bear pr-check` tells you whether a pull request widened governed boundary authority
 
@@ -115,3 +116,4 @@ If you want the packaged CI and PR-review model used by the demo, continue with:
 
 - [CI_INTEGRATION.md](CI_INTEGRATION.md)
 - [PR_REVIEW.md](PR_REVIEW.md)
+

docs/public/FOUNDATIONS.md

@@ -19,11 +19,12 @@ BEAR exists to make boundary authority changes explicit, enforceable, and CI-vis
 ## Intended Workflow Loop
 
 Agent loop:
-1. Update implementation + IR from domain intent.
+1. Update IR first when domain intent changes boundary authority.
 2. Run `bear validate`.
-3. Run `bear compile` or `bear fix`.
-4. Run `bear check --collect=all --agent` until `status=ok`.
-5. Run `bear pr-check --base <ref> --collect=all --agent` for governance classification.
+3. Run `bear compile` or `bear fix` to materialize the governed structural constraints.
+4. Update implementation inside those constraints.
+5. Run `bear check --collect=all --agent` until `status=ok`.
+6. Run `bear pr-check --base <ref> --collect=all --agent` for governance classification.
 
 Developer role:
 - review explicit boundary signals in PR/CI
@@ -60,3 +61,4 @@ It is intentionally not full behavioral verification or runtime policy enforceme
 - [ENFORCEMENT.md](ENFORCEMENT.md)
 - [PR_REVIEW.md](PR_REVIEW.md)
 - [CONTRACTS.md](CONTRACTS.md)
+

docs/public/OVERVIEW.md

@@ -8,8 +8,9 @@ The goal is to move trust from intent to machine-checkable gates and explicit go
 
 ## What BEAR does
 
-- **Agent updates** code and IR when boundary authority must change.
-- **BEAR compiles** deterministic wrappers/ports/manifests from IR.
+- **Agent updates IR first** when boundary authority must change.
+- **BEAR compiles** deterministic wrappers, ports, and manifests from that IR.
+- **Agent updates code inside those constraints** instead of widening structure implicitly.
 - **BEAR checks** repo state for drift and covered boundary bypasses.
 - **BEAR governs PR deltas** with explicit boundary-expansion classification.
 
@@ -38,3 +39,4 @@ The agent updates IR as needed; developers review resulting governance signals.
 - [PR_REVIEW.md](PR_REVIEW.md)
 - [CI_INTEGRATION.md](CI_INTEGRATION.md) for the packaged downstream CI pattern and GitHub Actions usage
 - [FOUNDATIONS.md](FOUNDATIONS.md) for full mechanics
+

docs/public/QUICKSTART.md

@@ -22,10 +22,10 @@ Set-Location ..\bear-account-demo
 .\.bear\tools\bear-cli\bin\bear.bat --help
 ```
 
-3. Let your agent implement the spec.
+3. Let your agent update the IR if boundary authority changes, then implement the code inside the generated constraints.
 
 ```text
-Implement the specs.
+Implement the specs. Update BEAR IR first if the boundary must change.
 ```
 
 4. Compile deterministic generated artifacts.
@@ -107,3 +107,4 @@ If something fails, go to [troubleshooting.md](troubleshooting.md).
 - [ENFORCEMENT.md](ENFORCEMENT.md)
 - [CONTRACTS.md](CONTRACTS.md)
 - [CI_INTEGRATION.md](CI_INTEGRATION.md)
+

tools/minimap/ui/app.js

@@ -4,6 +4,7 @@ const SCOPE_WIDTH_STORAGE_KEY = "roadmap-ui.scope-width";
 const DEFAULT_SCOPE_WIDTH = 272;
 const MIN_SCOPE_WIDTH = 240;
 const MAX_SCOPE_WIDTH = 440;
+const EDITOR_MODES = new Set(["preview", "structured", "raw"]);
 
 const state = {
   workspace: null,
@@ -271,6 +272,50 @@ function updateWorkspaceSummary() {
   workspaceSummaryElement.textContent = state.workspace ? `${items} items / ${groups} groups` : "Unavailable";
 }
 
+function normalizeEditorMode(mode) {
+  return EDITOR_MODES.has(mode) ? mode : "preview";
+}
+
+function readRouteState() {
+  const rawHash = window.location.hash.startsWith("#") ? window.location.hash.slice(1) : "";
+  const params = new URLSearchParams(rawHash);
+  return {
+    itemId: params.get("item") || "",
+    mode: normalizeEditorMode(params.get("mode") || "preview"),
+  };
+}
+
+function buildRouteHash(itemId = state.selectedItemId, mode = state.editorMode) {
+  const params = new URLSearchParams();
+
+  if (itemId) {
+    params.set("item", itemId);
+  }
+
+  const normalizedMode = normalizeEditorMode(mode);
+  if (normalizedMode !== "preview") {
+    params.set("mode", normalizedMode);
+  }
+
+  const serialized = params.toString();
+  return serialized ? `#${serialized}` : "";
+}
+
+function syncRouteState({ replace = false } = {}) {
+  const nextHash = buildRouteHash();
+  if (window.location.hash === nextHash) {
+    return;
+  }
+
+  const nextUrl = `${window.location.pathname}${window.location.search}${nextHash}`;
+  if (replace) {
+    window.history.replaceState(null, "", nextUrl);
+    return;
+  }
+
+  window.history.pushState(null, "", nextUrl);
+}
+
 function isStackedLayout() {
   return stackedLayoutMedia.matches;
 }
@@ -954,11 +999,40 @@ function resetAncillaryEditModes() {
   state.scopeDirty = false;
 }
 
-async function loadWorkspace(preferredItemId = state.selectedItemId) {
+async function applyRouteStateFromLocation() {
+  const route = readRouteState();
+  const routeItemId = route.itemId || "";
+  const currentItemId = state.selectedItemId || "";
+
+  if (routeItemId && routeItemId !== currentItemId) {
+    await loadWorkspace(routeItemId, {
+      preferredMode: route.mode,
+      syncRoute: false,
+    });
+    return;
+  }
+
+  if (!routeItemId && currentItemId) {
+    await loadWorkspace(undefined, {
+      preferredMode: route.mode,
+      syncRoute: false,
+    });
+    return;
+  }
+
+  const nextMode = normalizeEditorMode(route.mode);
+  if (nextMode !== state.editorMode) {
+    state.editorMode = nextMode;
+    applyEditorMode();
+  }
+}
+
+async function loadWorkspace(preferredItemId = state.selectedItemId, options = {}) {
   try {
     const workspace = await fetchJson("/api/workspace");
     resetAncillaryEditModes();
     state.workspace = workspace;
+    state.editorMode = normalizeEditorMode(options.preferredMode ?? state.editorMode);
     roadmapPathElement.textContent = workspace.roadmapPath;
     syncWorkspaceChrome();
     renderBoard();
@@ -967,9 +1041,15 @@ async function loadWorkspace(preferredItemId = state.selectedItemId) {
 
     const itemIdToLoad = preferredItemId && workspace.items?.[preferredItemId] ? preferredItemId : getFirstBoardItemId(workspace);
     if (itemIdToLoad) {
-      await loadItem(itemIdToLoad, false);
+      await loadItem(itemIdToLoad, false, {
+        syncRoute: options.syncRoute,
+        replaceRoute: options.replaceRoute,
+      });
     } else {
       resetEditor();
+      if (options.syncRoute !== false) {
+        syncRouteState({ replace: options.replaceRoute !== false });
+      }
     }
   } catch (error) {
     state.workspace = null;
@@ -984,7 +1064,7 @@ async function loadWorkspace(preferredItemId = state.selectedItemId) {
   }
 }
 
-async function loadItem(itemId, rerenderBoard = true) {
+async function loadItem(itemId, rerenderBoard = true, options = {}) {
   try {
     const item = await fetchJson(`/api/items/${encodeURIComponent(itemId)}`);
     state.selectedItemId = itemId;
@@ -993,6 +1073,9 @@ async function loadItem(itemId, rerenderBoard = true) {
     if (rerenderBoard) {
       renderBoard();
     }
+    if (options.syncRoute !== false) {
+      syncRouteState({ replace: options.replaceRoute === true });
+    }
     setBanner("");
   } catch (error) {
     setBanner(error.message, "error");
@@ -1050,7 +1133,7 @@ function applyEditorMode() {
   }
 }
 
-function switchEditorMode(nextMode) {
+function switchEditorMode(nextMode, options = {}) {
   if (nextMode === state.editorMode) {
     return;
   }
@@ -1075,6 +1158,10 @@ function switchEditorMode(nextMode) {
 
   state.editorMode = nextMode;
   applyEditorMode();
+
+  if (options.syncRoute !== false) {
+    syncRouteState({ replace: options.replaceRoute !== false });
+  }
 }
 
 async function saveCurrentItem() {
@@ -1229,6 +1316,10 @@ for (const button of modeButtons) {
   });
 }
 
+window.addEventListener("hashchange", () => {
+  void applyRouteStateFromLocation();
+});
+
 desktopScopeLayoutMedia.addEventListener("change", () => {
   renderScopeChrome();
 });
@@ -1239,6 +1330,20 @@ stackedLayoutMedia.addEventListener("change", () => {
 });
 
 resetEditor();
+const initialRoute = readRouteState();
+state.editorMode = initialRoute.mode;
 renderScopeChrome();
 applyEditorMode();
-void loadWorkspace();
+void loadWorkspace(initialRoute.itemId || state.selectedItemId, {
+  preferredMode: initialRoute.mode,
+  syncRoute: false,
+}).then(() => {
+  if (initialRoute.itemId || initialRoute.mode !== "preview") {
+    void applyRouteStateFromLocation();
+    return;
+  }
+
+  if (state.selectedItemId) {
+    syncRouteState({ replace: true });
+  }
+});