Merge pull request #58 from alanshurafa/contrib/alanshurafa/default-visible-nav

[dashboards] Default-visible CRM + wiki nav with setup states

Author: alanshurafa

dashboards/open-brain-dashboard-pro/.env.example

@@ -12,3 +12,19 @@ SESSION_SECRET=
 # column on the thoughts table). Leave unset to hide the lock/unlock toggle.
 # Generate with: echo -n "your-passphrase" | shasum -a 256
 # RESTRICTED_PASSPHRASE_HASH=
+
+# Optional: controls whether the Contacts/Proposals (CRM) and Wiki nav entries
+# show up before their backend schema is installed. Leave unset (or any value
+# other than "auto") for the default: always show them, with a setup card
+# explaining how to enable the surface. Set to "auto" to hide each entry until
+# its schema/routes are detected, matching this dashboard's pre-milestone
+# behavior. NEXT_PUBLIC_* vars are inlined at build time — changing this
+# requires a rebuild, not just a restart.
+# NEXT_PUBLIC_OPTIONAL_NAV=
+
+# Optional: base URL for the schema-folder links on the setup cards (e.g.
+# https://github.com/YOUR-ORG/YOUR-REPO/tree/main). Defaults to the
+# alanshurafa/OB1 fork, where all the optional schemas currently live. Set this
+# to your own repo/mirror if you maintain one. Build-time, like the other
+# NEXT_PUBLIC_* vars above.
+# NEXT_PUBLIC_SCHEMA_REPO_BASE=

dashboards/open-brain-dashboard-pro/README.md

@@ -27,7 +27,9 @@ If your brain runs the CRM truth layer (the `crm-core` + `crm-engagement` schema
 | **Contact** (`/contacts/:id`) | Editable fact panel with per-field origin, locks, and evidence; contact methods and aliases; this contact's open proposals with accept/reject; a notes / tasks / important-dates panel; and an activity view with a merged timeline and the raw change log. |
 | **Proposals** (`/proposals`) | Inbox of machine-suggested field changes filtered by status, with per-row accept/reject and bulk accept/reject for a whole import run. |
 
-The Contacts and Proposals nav entries, and the open-proposals badge on the sidebar, appear **only when the brain exposes the `/crm` surface**. The dashboard probes for it once at login and caches the result in the session, so a brain without the CRM layer never shows these entries and behaves exactly as before. Each CRM read also degrades on its own: if an individual route is missing or errors, that panel renders empty instead of blanking the page.
+The Contacts and Proposals nav entries appear **by default, whether or not the brain has the CRM layer installed yet**. Visiting either page on a brain without it shows a setup card: which schema(s) to apply (`schemas/crm-core` + `schemas/crm-engagement`), where to run them (your Supabase project's SQL editor), a link to the schema README, a reminder that `open-brain-rest` needs the `/crm/*` route group deployed, and a **Re-check now** button that re-probes the brain and refreshes the page — no sign-out required. The setup card's schema links point at the `alanshurafa/OB1` fork by default because the optional schemas haven't landed upstream yet; override with `NEXT_PUBLIC_SCHEMA_REPO_BASE` (see [Configuration](#configuration)). The open-proposals badge only ever renders a real count, so it stays hidden until CRM is actually enabled. Each CRM read also degrades on its own: if an individual route is missing or errors after CRM is enabled, that panel renders empty instead of blanking the page.
+
+Prefer the old hide-until-detected behavior? Set `NEXT_PUBLIC_OPTIONAL_NAV=auto` (see [Configuration](#configuration)) and rebuild — the dashboard probes for `/crm` once at login, caches the result in the session, and only then shows the Contacts/Proposals entries.
 
 ## Wiki (optional)
 
@@ -38,7 +40,9 @@ If your brain runs the persistent-wiki layer (the `schemas/wiki-pages` schema an
 | **Wiki** (`/wiki`) | Page list filtered by kind (topic / entity / autobiography / custom), with section counts and a "new page" form. |
 | **Wiki page** (`/wiki/:slug`) | Sections in display order, each with its markdown body rendered sanitized, an origin chip (yours / generated), a lock toggle, and an evidence chip listing supporting thought ids. Edit a section inline (your edit takes ownership); add a section; archive the page. When a machine writer proposes an update to a section you own, a review panel shows the current body against the proposed draft with **accept / reject**. |
 
-Wiki pages are reachable at `/wiki` (a dedicated sidebar entry lands in a later change). The dashboard probes for the `/wiki` surface once at login and caches the result in the session. When the schema is absent — the probe comes back negative, or `GET /wiki/pages` returns 404 — the page renders a short inline notice ("Wiki schema not installed — apply `schemas/wiki-pages` to enable") instead of an error, so a brain without the wiki layer behaves exactly as before.
+The Wiki nav entry appears **by default, whether or not the brain has the wiki layer installed yet**. Visiting `/wiki` on a brain without it — the login-time probe came back negative, a re-check still says no, or `GET /wiki/pages` returns 404 — shows a setup card: apply `schemas/wiki-pages`, confirm `open-brain-rest` exposes the `/wiki/*` route group, and a **Re-check now** button that re-probes the brain and refreshes the page without a sign-out.
+
+Prefer the old hide-until-detected behavior? Set `NEXT_PUBLIC_OPTIONAL_NAV=auto` (see [Configuration](#configuration)) and rebuild — the dashboard probes for `/wiki` once at login, caches the result in the session, and only then shows the Wiki entry.
 
 Archived pages are hidden from the list but stay fetchable — and editable — by slug; unarchive is a future gateway addition.
 
@@ -64,6 +68,8 @@ All configuration is through environment variables. **The app refuses to start i
 | `NEXT_PUBLIC_API_URL` | Yes | Base URL of your Open Brain REST API, typically `https://YOUR-PROJECT-REF.supabase.co/functions/v1/open-brain-rest`. |
 | `SESSION_SECRET` | Yes | 32+ character secret used by `iron-session` to encrypt the session cookie. Generate with `openssl rand -hex 32`. |
 | `RESTRICTED_PASSPHRASE_HASH` | No | SHA-256 hash of a passphrase that unlocks restricted/sensitive content. Only meaningful if your brain has a `sensitivity_tier` column on `public.thoughts`. There is no official sensitivity-tiers primitive upstream yet — either add your own migration (see PR #192 for pattern) or wait for the primitive to land. On stock OB1, this dashboard's restricted-content toggle is hidden at startup. Generate with `echo -n "your-passphrase" \| shasum -a 256`. |
+| `NEXT_PUBLIC_OPTIONAL_NAV` | No | Controls whether the Contacts/Proposals (CRM) and Wiki nav entries show before their schema is installed. Default (unset, or any value other than `auto`): always show them, with a setup card on the page itself. Set to `auto` to restore hide-until-enabled behavior, gated on the login-time probe cached in the session. This is a `NEXT_PUBLIC_*` var, so it's inlined at **build** time — changing it needs a rebuild, not just a restart. |
+| `NEXT_PUBLIC_SCHEMA_REPO_BASE` | No | Base URL for the schema-folder links on the setup cards, e.g. `https://github.com/YOUR-ORG/YOUR-REPO/tree/main`. Defaults to the `alanshurafa/OB1` fork, where all the optional schemas currently live (they haven't landed upstream yet). Set it to your own repo/mirror if you maintain one. Build-time, like the other `NEXT_PUBLIC_*` vars. |
 
 Copy `.env.example` to `.env.local` (gitignored) and fill it in.
 
@@ -112,8 +118,8 @@ The dashboard calls these endpoints on your Open Brain REST gateway (all authent
 | `/thought/:id/connections` | GET | Detail page connections panel | Optional — panel hides if it errors |
 | `/duplicates`, `/duplicates/resolve` | GET / POST | Duplicates page | Optional — page shows an error otherwise |
 | `/ingest`, `/ingestion-jobs`, `/ingestion-jobs/:id`, `/ingestion-jobs/:id/execute` | POST / GET | Ingest page | Optional — page still loads without jobs |
-| `/crm/*` (contacts, proposals, notes, tasks, important-dates, timeline, history, …) | GET / POST / PATCH | Contacts, Proposals, contact detail panels | Optional — CRM surface is hidden unless `/crm` is detected at login |
-| `/wiki/*` (pages, pages/:slug, sections/:id/accept-pending, reject-pending, lock, …) | GET / POST / PUT / DELETE | Wiki list, wiki page, section edit / lock / draft review | Optional — wiki surface degrades to an inline notice unless `/wiki` is detected at login |
+| `/crm/*` (contacts, proposals, notes, tasks, important-dates, timeline, history, …) | GET / POST / PATCH | Contacts, Proposals, contact detail panels | Optional — nav entries show by default; the pages themselves render a setup card until `/crm` is detected |
+| `/wiki/*` (pages, pages/:slug, sections/:id/accept-pending, reject-pending, lock, …) | GET / POST / PUT / DELETE | Wiki list, wiki page, section edit / lock / draft review | Optional — nav entry shows by default; the page itself renders a setup card until `/wiki` is detected |
 
 > **On `/reflections/*`:** The ExoCortex upstream dashboard staged a reflections feature. This fork does not yet ship a reflections UI surface, but the architecture is ready: if you add a reflection panel later and your gateway doesn't serve `/reflections/*`, expect a 404 that the UI should swallow. The existing optional endpoints already degrade this way — the Connections panel, Duplicates page, and Ingest history all swallow fetch errors and render an empty/neutral state instead of crashing.
 

dashboards/open-brain-dashboard-pro/app/api/capabilities/recheck/route.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from "next/server";
+import { requireSession, getSession, AuthError } from "@/lib/auth";
+import { crmAvailable, wikiAvailable } from "@/lib/api";
+
+/**
+ * POST /api/capabilities/recheck — re-probes both optional surfaces (CRM,
+ * wiki) and writes the results into the session. Lets a user who just applied
+ * a schema pick it up immediately via the "Re-check now" button instead of
+ * signing out and back in (the only other way to re-run the login-time probe).
+ */
+export async function POST() {
+  let apiKey: string;
+  try {
+    ({ apiKey } = await requireSession());
+  } catch (err) {
+    if (err instanceof AuthError)
+      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    throw err;
+  }
+
+  let crmEnabled: boolean;
+  let wikiEnabled: boolean;
+  try {
+    [crmEnabled, wikiEnabled] = await Promise.all([
+      crmAvailable(apiKey),
+      wikiAvailable(apiKey),
+    ]);
+  } catch (err) {
+    // crmAvailable/wikiAvailable already swallow their own upstream errors and
+    // resolve to false — this catch only guards against something unexpected
+    // (e.g. a thrown non-ApiError) so the route never 500s on a re-check.
+    console.error("[capabilities/recheck]", err);
+    return NextResponse.json(
+      { error: "Failed to re-check capabilities" },
+      { status: 500 }
+    );
+  }
+
+  const session = await getSession();
+  session.crmEnabled = crmEnabled;
+  session.wikiEnabled = wikiEnabled;
+  await session.save();
+
+  return NextResponse.json({ crmEnabled, wikiEnabled });
+}

dashboards/open-brain-dashboard-pro/app/contacts/page.tsx

@@ -2,6 +2,7 @@ import Link from "next/link";
 import { fetchCrmContacts, ApiError } from "@/lib/api";
 import { requireSessionOrRedirect, getSession } from "@/lib/auth";
 import { FormattedDate } from "@/components/FormattedDate";
+import { SetupState } from "@/components/SetupState";
 
 export const dynamic = "force-dynamic";
 
@@ -34,6 +35,15 @@ export default async function ContactsPage({
   const q = params.q || "";
   const tier = params.privacy_tier || "";
 
+  // If we already know from login (or a re-check) the brain has no CRM
+  // surface, short-circuit to the setup state without a doomed fetch.
+  // `crmEnabled === false` is the only negative signal we trust; `undefined`
+  // (old cookie, pre-dating this field) falls through to the fetch below,
+  // whose 404 handling covers the schema-missing case anyway.
+  if (session.crmEnabled === false) {
+    return <SetupState surface="crm" />;
+  }
+
   let data;
   try {
     data = await fetchCrmContacts(apiKey, {
@@ -46,6 +56,11 @@ export default async function ContactsPage({
   } catch (err) {
     if (err instanceof ApiError) {
       console.error("[contacts] upstream", err.status, err.upstreamBody);
+      // 404 → the brain doesn't have the crm-core schema/routes. Show the
+      // same setup state as the cached-negative case.
+      if (err.status === 404) {
+        return <SetupState surface="crm" />;
+      }
     } else {
       console.error("[contacts]", err);
     }

dashboards/open-brain-dashboard-pro/app/layout.tsx

@@ -32,10 +32,14 @@ export default async function RootLayout({
     process.env.RESTRICTED_PASSPHRASE_HASH &&
       process.env.RESTRICTED_PASSPHRASE_HASH.length > 0
   );
-  // Feature detection: the CRM sidebar entry only appears when the brain
-  // exposed the /crm surface at login (probed and cached in the session).
+  // Feature detection, cached at login (and refreshable via the "Re-check
+  // now" button on each surface's setup state — see
+  // app/api/capabilities/recheck/route.ts). Nav visibility itself defaults to
+  // always-on; these flags only drive the open-proposals badge here and the
+  // NEXT_PUBLIC_OPTIONAL_NAV=auto hide-until-enabled branch inside Sidebar.
   const session = await getSession();
   const crmEnabled = session.crmEnabled === true;
+  const wikiEnabled = session.wikiEnabled === true;
 
   // Open-proposals badge: a best-effort read that never blocks the shell. An
   // older brain without the count route (or any transient error) degrades to no
@@ -60,7 +64,12 @@ export default async function RootLayout({
       className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
     >
       <body className="min-h-screen flex bg-bg-primary text-text-primary">
-        <Sidebar restrictedConfigured={restrictedConfigured} crmEnabled={crmEnabled} openProposals={openProposals} />
+        <Sidebar
+          restrictedConfigured={restrictedConfigured}
+          crmEnabled={crmEnabled}
+          wikiEnabled={wikiEnabled}
+          openProposals={openProposals}
+        />
         <main className="flex-1 ml-56 min-h-screen">
           <div className="max-w-6xl mx-auto px-8 py-8">
             {children}

dashboards/open-brain-dashboard-pro/app/proposals/page.tsx

@@ -1,11 +1,12 @@
 import Link from "next/link";
 import { revalidatePath } from "next/cache";
 import { fetchCrmProposals, resolveCrmProposal, resolveCrmProposalsByRun, ApiError } from "@/lib/api";
-import { requireSessionOrRedirect } from "@/lib/auth";
+import { requireSessionOrRedirect, getSession } from "@/lib/auth";
 import { FormattedDate } from "@/components/FormattedDate";
 import { ProposalDecision } from "./ProposalDecision";
 import type { ResolveResult } from "./ProposalDecision";
 import { RunBulkActions } from "./RunBulkActions";
+import { SetupState } from "@/components/SetupState";
 
 export const dynamic = "force-dynamic";
 
@@ -99,17 +100,32 @@ export default async function ProposalsPage({
   searchParams: Promise<Record<string, string | undefined>>;
 }) {
   const { apiKey } = await requireSessionOrRedirect();
+  const session = await getSession();
   const params = await searchParams;
   const page = parseInt(params.page || "1", 10);
   const status = params.status || "open";
   const runId = params.run_id || undefined;
 
+  // If we already know from login (or a re-check) the brain has no CRM
+  // surface, short-circuit to the setup state without a doomed fetch.
+  // `crmEnabled === false` is the only negative signal we trust; `undefined`
+  // (old cookie, pre-dating this field) falls through to the fetch below,
+  // whose 404 handling covers the schema-missing case anyway.
+  if (session.crmEnabled === false) {
+    return <SetupState surface="crm" />;
+  }
+
   let data;
   try {
     data = await fetchCrmProposals(apiKey, { page, per_page: 25, status, run_id: runId });
   } catch (err) {
     if (err instanceof ApiError) {
       console.error("[proposals] upstream", err.status, err.upstreamBody);
+      // 404 → the brain doesn't have the crm-core schema/routes. Show the
+      // same setup state as the cached-negative case.
+      if (err.status === 404) {
+        return <SetupState surface="crm" />;
+      }
     } else {
       console.error("[proposals]", err);
     }

dashboards/open-brain-dashboard-pro/app/wiki/page.tsx

@@ -3,6 +3,7 @@ import { fetchWikiPages, ApiError } from "@/lib/api";
 import { requireSessionOrRedirect, getSession } from "@/lib/auth";
 import { FormattedDate } from "@/components/FormattedDate";
 import { NewPageForm } from "./NewPageForm";
+import { SetupState } from "@/components/SetupState";
 import type { WikiPageKind } from "@/lib/types";
 
 export const dynamic = "force-dynamic";
@@ -17,26 +18,6 @@ function KindBadge({ kind }: { kind: string }) {
   );
 }
 
-// Shared inline empty-state shown when the wiki schema/routes are absent. Kept
-// deliberately minimal and self-contained: a later PR replaces this with a
-// shared setup-state component, so there is nothing here to migrate but one <p>.
-function WikiNotInstalled() {
-  return (
-    <div className="space-y-6">
-      <div>
-        <h1 className="text-2xl font-semibold mb-1">Wiki</h1>
-      </div>
-      <div className="bg-bg-surface border border-border rounded-lg p-8">
-        <p className="text-text-secondary text-sm max-w-prose">
-          Wiki schema not installed — apply <code className="font-mono text-xs px-1 py-0.5 rounded bg-bg-elevated border border-border text-text-primary">schemas/wiki-pages</code>{" "}
-          to your brain and deploy the <code className="font-mono text-xs px-1 py-0.5 rounded bg-bg-elevated border border-border text-text-primary">/wiki</code>{" "}
-          gateway routes to enable persistent wiki pages. See the repo README for the setup steps.
-        </p>
-      </div>
-    </div>
-  );
-}
-
 export default async function WikiPage({
   searchParams,
 }: {
@@ -54,7 +35,7 @@ export default async function WikiPage({
   // negative signal we trust; `undefined` (old cookie) falls through to the fetch,
   // whose 404 handling covers the schema-missing case anyway.
   if (session.wikiEnabled === false) {
-    return <WikiNotInstalled />;
+    return <SetupState surface="wiki" />;
   }
 
   let data;
@@ -68,9 +49,9 @@ export default async function WikiPage({
     if (err instanceof ApiError) {
       console.error("[wiki] upstream", err.status, err.upstreamBody);
       // 404 → the brain doesn't have the wiki schema/routes. Show the same
-      // inline empty-state as the cached-negative case.
+      // setup state as the cached-negative case.
       if (err.status === 404) {
-        return <WikiNotInstalled />;
+        return <SetupState surface="wiki" />;
       }
     } else {
       console.error("[wiki]", err);