From 36f65f294ce33325a9eea9b7a8629706a4def721 Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Thu, 30 Apr 2026 17:06:31 +0100
Subject: feat(doc-mode): rename surfaced label "Directive" → "Contract" (#109)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 2: cosmetic UI rename only. Database tables, API paths, hook names,
and CLI commands all stay as 'directive' for now — we'll phase out the
existing standalone /contracts table later.

Surface changes:
- Sidebar header "Documents" → "Contracts"; root folder "directives/" →
  "contracts/"; empty state "No directives yet" → "No contracts yet".
- Editor placeholders, breadcrumb header, "back to document" → "back to
  contract", right-click menu header.
- NavStrip: when documentModeEnabled is on, the "Directives" link renders
  as "Contracts" (href stays /directives so links don't break).
- Save bar message "saving will replan the directive" → "the contract".

No backend changes — directive.goal etc. all still work the same.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 makima/frontend/src/components/NavStrip.tsx        | 35 +++++++++++++---------
 .../src/components/directives/DocumentEditor.tsx   |  8 ++---
 makima/frontend/src/routes/document-directives.tsx | 24 +++++++--------
 3 files changed, 37 insertions(+), 30 deletions(-)

diff --git a/makima/frontend/src/components/NavStrip.tsx b/makima/frontend/src/components/NavStrip.tsx
index a6e483d..6fe4ba9 100644
--- a/makima/frontend/src/components/NavStrip.tsx
+++ b/makima/frontend/src/components/NavStrip.tsx
@@ -62,20 +62,27 @@ export function NavStrip() {
       <div className="flex flex-wrap gap-2 items-center flex-1">
         {NAV_LINKS.filter(
           (link) => !(documentMode && link.hideInDocumentMode),
-        ).map((link) => (
-          <span key={link.label} className="relative inline-flex items-center">
-            <RewriteLink
-              to={link.href}
-              disabled={link.requiresAuth && !hasAccess}
-              external={link.external}
-            >
-              {link.label}
-            </RewriteLink>
-            {link.label === "Directives" && directiveQuestionCount > 0 && (
-              <span className="ml-0.5 inline-block w-2 h-2 rounded-full bg-amber-400 animate-pulse" title={`${directiveQuestionCount} pending question(s)`} />
-            )}
-          </span>
-        ))}
+        ).map((link) => {
+          // In document mode, the directive concept is surfaced to the user
+          // as "Contracts" — keep the same href (/directives) so existing
+          // links and bookmarks continue to work.
+          const displayLabel =
+            documentMode && link.label === "Directives" ? "Contracts" : link.label;
+          return (
+            <span key={link.label} className="relative inline-flex items-center">
+              <RewriteLink
+                to={link.href}
+                disabled={link.requiresAuth && !hasAccess}
+                external={link.external}
+              >
+                {displayLabel}
+              </RewriteLink>
+              {link.label === "Directives" && directiveQuestionCount > 0 && (
+                <span className="ml-0.5 inline-block w-2 h-2 rounded-full bg-amber-400 animate-pulse" title={`${directiveQuestionCount} pending question(s)`} />
+              )}
+            </span>
+          );
+        })}
       </div>
       <div className="flex items-center gap-2 pl-2.5 border-l border-[rgba(117,170,252,0.35)]">
         {isAuthenticated && isAuthConfigured ? (
diff --git a/makima/frontend/src/components/directives/DocumentEditor.tsx b/makima/frontend/src/components/directives/DocumentEditor.tsx
index 3dd8522..08e4d73 100644
--- a/makima/frontend/src/components/directives/DocumentEditor.tsx
+++ b/makima/frontend/src/components/directives/DocumentEditor.tsx
@@ -638,7 +638,7 @@ function EditorContextMenu({
       style={{ left: x, top: y }}
     >
       <div className="px-3 py-1.5 text-[10px] font-mono text-[#556677] uppercase border-b border-[rgba(117,170,252,0.2)]">
-        Document
+        Contract
       </div>
       <button
         type="button"
@@ -727,7 +727,7 @@ function SaveCountdownBar({
     }
   } else if (state === "dirty") {
     label = orchestratorRunning
-      ? "Unsaved changes — saving will replan the directive."
+      ? "Unsaved changes — saving will replan the contract."
       : "Unsaved changes.";
     progressPct = 0;
   } else if (state === "saving") {
@@ -1129,10 +1129,10 @@ export function DocumentEditor({
               <RichTextPlugin
                 contentEditable={
                   <ContentEditable
-                    aria-placeholder="Describe the directive's goal…"
+                    aria-placeholder="Describe the contract's goal…"
                     placeholder={
                       <div className="pointer-events-none absolute text-[#445566] font-mono text-[13px] mt-2">
-                        Describe the directive's goal…
+                        Describe the contract's goal…
                       </div>
                     }
                     className="outline-none font-mono text-[13px] leading-relaxed text-[#dbe7ff] [&_.makima-doc-h1]:text-[24px] [&_.makima-doc-h1]:font-medium [&_.makima-doc-h1]:text-white [&_.makima-doc-h1]:mb-3 [&_.makima-doc-h1]:tracking-tight [&_.makima-doc-paragraph]:my-2 [&_.makima-doc-paragraph]:text-[13px] [&_.makima-doc-paragraph]:text-[#c0d0e0] relative"
diff --git a/makima/frontend/src/routes/document-directives.tsx b/makima/frontend/src/routes/document-directives.tsx
index 9cb984b..ada8a3d 100644
--- a/makima/frontend/src/routes/document-directives.tsx
+++ b/makima/frontend/src/routes/document-directives.tsx
@@ -657,17 +657,17 @@ function DocumentSidebar({
       {/* Sidebar header */}
       <div className="flex items-center justify-between px-3 py-2 border-b border-dashed border-[rgba(117,170,252,0.2)]">
         <span className="text-[11px] font-mono text-[#9bc3ff] uppercase tracking-wide">
-          Documents
+          Contracts
         </span>
         <span className="text-[10px] font-mono text-[#556677]">
           {directives.length}
         </span>
       </div>
 
-      {/* Top-level "directives/" folder header (informational, non-interactive). */}
+      {/* Top-level "contracts/" folder header (informational, non-interactive). */}
       <div className="flex items-center gap-1.5 px-3 py-1.5 text-[11px] font-mono text-[#9bc3ff]">
         <FolderIcon open />
-        <span>directives/</span>
+        <span>contracts/</span>
       </div>
 
       {/* Body */}
@@ -678,7 +678,7 @@ function DocumentSidebar({
           </div>
         ) : directives.length === 0 ? (
           <div className="px-3 py-6 text-center text-[#556677] font-mono text-[11px]">
-            No directives yet
+            No contracts yet
           </div>
         ) : (
           sorted.map((d) => (
@@ -735,10 +735,10 @@ function EditorShell({
       <div className="flex-1 flex items-center justify-center h-full">
         <p className="text-[#556677] font-mono text-[12px]">
           {listLoading
-            ? "Loading documents..."
+            ? "Loading contracts..."
             : hasDirectives
-            ? "Select a document from the sidebar"
-            : "No documents yet — create one from the legacy UI"}
+            ? "Select a contract from the sidebar"
+            : "No contracts yet — create one from the legacy UI"}
         </p>
       </div>
     );
@@ -747,7 +747,7 @@ function EditorShell({
   if (loading && !directive) {
     return (
       <div className="flex-1 flex items-center justify-center h-full">
-        <p className="text-[#556677] font-mono text-[12px]">Loading document...</p>
+        <p className="text-[#556677] font-mono text-[12px]">Loading contract...</p>
       </div>
     );
   }
@@ -755,7 +755,7 @@ function EditorShell({
   if (!directive) {
     return (
       <div className="flex-1 flex items-center justify-center h-full">
-        <p className="text-[#7788aa] font-mono text-[12px]">Document not found</p>
+        <p className="text-[#7788aa] font-mono text-[12px]">Contract not found</p>
       </div>
     );
   }
@@ -772,11 +772,11 @@ function EditorShell({
 
   return (
     <div className="flex-1 flex flex-col h-full overflow-hidden">
-      {/* Document header — breadcrumb-like, mirrors a code editor's tab bar */}
+      {/* Contract header — breadcrumb-like, mirrors a code editor's tab bar */}
       <div className="px-6 py-3 border-b border-dashed border-[rgba(117,170,252,0.2)]">
         <div className="flex items-center gap-2 text-[10px] font-mono uppercase tracking-wide text-[#7788aa]">
           <FileIcon />
-          <span>directives /</span>
+          <span>contracts /</span>
           <span className="text-[#9bc3ff]">{directive.id.slice(0, 8)}</span>
           {selectedTaskId && (
             <>
@@ -787,7 +787,7 @@ function EditorShell({
                 onClick={onClearTask}
                 className="ml-2 px-1.5 py-0.5 text-[#7788aa] hover:text-white border border-[#2a3a5a] rounded normal-case"
               >
-                back to document
+                back to contract
               </button>
             </>
           )}
-- 
cgit v1.2.3