esedre 0.1.7 → 0.1.9

package/dist/esedre.mjs

@@ -9,7 +9,7 @@ import fs3 from "node:fs";
 import path3 from "node:path";
 
 // src/types.ts
-var CURRENT_ESEDRE_VERSION = "0.1.7";
+var CURRENT_ESEDRE_VERSION = "0.1.9";
 var EsedreConflictError = class extends Error {
   constructor(ticketId, currentHash, lastHash) {
     super(
@@ -539,12 +539,12 @@ async function generateProjectSnapshot(storage, projectCode, outputDir) {
 }
 
 // src/storage/filesystem.ts
-function isProjectMatch(code, slug, filter) {
+function isProjectMatch(code, filter) {
+  if (!code || !filter) return false;
   const f = filter.trim().toLowerCase();
   const c = code.trim().toLowerCase();
-  const s = slug.trim().toLowerCase();
-  if (c === f || s === f) return true;
-  if ((f === "prof" || f === "core" || f === "pasrc") && (c === "prof" || c === "core")) return true;
+  if (c === f) return true;
+  if ((f === "profe" || f === "prof" || f === "core" || f === "pasrc") && (c === "profe" || c === "prof" || c === "core")) return true;
   if ((f === "esedre" || f === "ese" || f === "docs") && (c === "esedre" || c === "docs")) return true;
   if ((f === "alce" || f === "web") && (c === "alce" || c === "web")) return true;
   return false;
@@ -572,6 +572,9 @@ function writeSafeFile(filePath, content) {
 var FilesystemStorageAdapter = class {
   workspaceRoot;
   config;
+  isConfigExplicit = false;
+  lastConfigCheck = 0;
+  configTtlMs = 3e3;
   duplicateProjectWarnings = [];
   getDuplicateProjectWarnings() {
     this.resolveProjectLocations();
@@ -581,13 +584,39 @@ var FilesystemStorageAdapter = class {
     this.workspaceRoot = workspaceRoot || this.resolveWorkspaceRoot();
     if (config) {
       this.config = config;
+      this.isConfigExplicit = true;
+      this.lastConfigCheck = Date.now();
     } else {
-      try {
-        const discovered = findEsedreConfig(this.workspaceRoot);
-        this.config = discovered.config || {};
-      } catch {
-        this.config = {};
+      this.config = {};
+      this.refreshConfig();
+    }
+  }
+  refreshConfig() {
+    try {
+      const discovered = findEsedreConfig(this.workspaceRoot);
+      this.config = discovered.config || {};
+    } catch {
+      this.config = {};
+    }
+    this.lastConfigCheck = Date.now();
+  }
+  ensureFreshConfig() {
+    if (this.isConfigExplicit && this.config.allowedProjects?.includes("*")) {
+      if (Date.now() - this.lastConfigCheck > this.configTtlMs) {
+        try {
+          const discovered = findEsedreConfig(this.workspaceRoot, { fallbackToGlobal: true });
+          this.config = {
+            ...discovered.config,
+            allowedProjects: ["*"]
+          };
+        } catch {
+        }
+        this.lastConfigCheck = Date.now();
       }
+      return;
+    }
+    if (!this.isConfigExplicit && Date.now() - this.lastConfigCheck > this.configTtlMs) {
+      this.refreshConfig();
     }
   }
   resolveWorkspaceRoot() {
@@ -606,6 +635,7 @@ var FilesystemStorageAdapter = class {
     return process.cwd();
   }
   resolveProjectLocations() {
+    this.ensureFreshConfig();
     const locations = [];
     const seenCodes = /* @__PURE__ */ new Set();
     const codeToSource = /* @__PURE__ */ new Map();
@@ -649,9 +679,6 @@ var FilesystemStorageAdapter = class {
           if (fs3.existsSync(pJsonPath)) {
             try {
               desc = JSON.parse(fs3.readFileSync(pJsonPath, "utf-8"));
-              if (desc && !desc.slug) {
-                desc.slug = (desc.code || ent.name).toLowerCase();
-              }
             } catch {
             }
           }
@@ -663,7 +690,7 @@ var FilesystemStorageAdapter = class {
                 try {
                   const hubProjs = JSON.parse(fs3.readFileSync(f, "utf-8"));
                   desc = hubProjs.find(
-                    (p) => p.code.toLowerCase() === ent.name.toLowerCase() || p.slug.toLowerCase() === ent.name.toLowerCase()
+                    (p) => p.code.toLowerCase() === ent.name.toLowerCase()
                   );
                   if (desc) break;
                 } catch {
@@ -675,7 +702,6 @@ var FilesystemStorageAdapter = class {
             desc = {
               id: locations.length + 1,
               code: ent.name,
-              slug: ent.name.toLowerCase(),
               name: ent.name,
               description: `${ent.name} project`
             };
@@ -727,7 +753,6 @@ var FilesystemStorageAdapter = class {
           descs = [{
             id: 1,
             code: pCode,
-            slug: pCode.toLowerCase(),
             name: pCode,
             description: `${pCode} project`
           }];
@@ -782,9 +807,6 @@ var FilesystemStorageAdapter = class {
           if (fs3.existsSync(cand)) {
             try {
               desc = JSON.parse(fs3.readFileSync(cand, "utf-8"));
-              if (desc && !desc.slug) {
-                desc.slug = (desc.code || code).toLowerCase();
-              }
               break;
             } catch {
             }
@@ -794,7 +816,6 @@ var FilesystemStorageAdapter = class {
           desc = {
             id: locations.length + 1,
             code,
-            slug: code.toLowerCase(),
             name: code,
             description: `${code} project`
           };
@@ -862,7 +883,6 @@ var FilesystemStorageAdapter = class {
           descs = [{
             id: 1,
             code: this.config.projectCode,
-            slug: this.config.projectCode.toLowerCase(),
             name: pName,
             description: `${pName} project`
           }];
@@ -894,7 +914,7 @@ var FilesystemStorageAdapter = class {
     const cleanCode = rawCode;
     const cleanName = input.name?.trim() || cleanCode;
     const cleanDesc = input.description?.trim() || `${cleanName} project`;
-    const slug = cleanCode.toLowerCase();
+    const cleanLower = cleanCode.toLowerCase();
     const colors2 = input.colors || {
       badge: "border-cyan-500/30 bg-cyan-500/10 text-cyan-300",
       dot: "bg-cyan-400",
@@ -978,7 +998,7 @@ ${formattedList}`
       const normalizedTargetHub = path3.resolve(targetHub).toLowerCase();
       const existingLocations = this.resolveProjectLocations();
       const existingConflict = existingLocations.find((l) => {
-        if (l.project.code.toLowerCase() !== slug) return false;
+        if (l.project.code.toLowerCase() !== cleanLower) return false;
         if (l.sourceType === "hub" && l.hubDir) {
           return path3.resolve(l.hubDir).toLowerCase() !== normalizedTargetHub;
         }
@@ -996,7 +1016,7 @@ ${formattedList}`
         try {
           const entries = fs3.readdirSync(hubProjectsDir, { withFileTypes: true });
           const matchedDir = entries.find(
-            (e) => e.isDirectory() && e.name.toLowerCase() === slug
+            (e) => e.isDirectory() && e.name.toLowerCase() === cleanLower
           );
           if (matchedDir) {
             resolvedDirName = matchedDir.name;
@@ -1024,7 +1044,6 @@ ${formattedList}`
       const projectDesc2 = {
         id: id2,
         code: resolvedCode2,
-        slug,
         name: cleanName,
         description: cleanDesc,
         colors: colors2
@@ -1034,7 +1053,7 @@ ${formattedList}`
       if (fs3.existsSync(hubProjectsFile)) {
         try {
           const arr = JSON.parse(fs3.readFileSync(hubProjectsFile, "utf-8"));
-          const idx = arr.findIndex((p) => p.code.toLowerCase() === slug);
+          const idx = arr.findIndex((p) => p.code.toLowerCase() === cleanLower);
           if (idx >= 0) {
             arr[idx] = projectDesc2;
           } else {
@@ -1059,12 +1078,11 @@ ${formattedList}`
       } catch {
       }
     }
-    const resolvedCode = existingPJson?.code && existingPJson.code.toLowerCase() === slug ? existingPJson.code : cleanCode;
+    const resolvedCode = existingPJson?.code && existingPJson.code.toLowerCase() === cleanLower ? existingPJson.code : cleanCode;
     const id = existingPJson?.id || 1;
     const projectDesc = {
       id,
       code: resolvedCode,
-      slug,
       name: cleanName,
       description: cleanDesc,
       colors: colors2
@@ -1074,7 +1092,7 @@ ${formattedList}`
     if (fs3.existsSync(projectsJsonPath)) {
       try {
         const arr = JSON.parse(fs3.readFileSync(projectsJsonPath, "utf-8"));
-        const idx = arr.findIndex((p) => p.code.toLowerCase() === slug);
+        const idx = arr.findIndex((p) => p.code.toLowerCase() === cleanLower);
         if (idx >= 0) {
           arr[idx] = projectDesc;
         } else {
@@ -1094,7 +1112,7 @@ ${formattedList}`
     if (prefixMatch) {
       const code = prefixMatch[1].toLowerCase();
       const num2 = parseInt(prefixMatch[2], 10);
-      const loc = locations.find((l) => isProjectMatch(l.project.code, l.project.slug, code));
+      const loc = locations.find((l) => isProjectMatch(l.project.code, code));
       if (!loc) return null;
       const ticketDir = path3.join(loc.ticketsDir, String(num2));
       const metaPath = path3.join(ticketDir, "meta.json");
@@ -1106,7 +1124,7 @@ ${formattedList}`
             meta.type = meta.type || meta.category || "Feature";
             meta.category = meta.type;
             const mProj = (meta.project || "").toLowerCase();
-            if (mProj && mProj !== code && mProj !== loc.project.slug.toLowerCase()) {
+            if (mProj && mProj !== code && mProj !== loc.project.code.toLowerCase()) {
               return null;
             }
           } catch {
@@ -1131,7 +1149,7 @@ ${formattedList}`
           const metaRaw = fs3.readFileSync(metaPath, "utf-8");
           const meta = JSON.parse(metaRaw);
           const matchedLoc = locations.find(
-            (l) => meta.projectId !== void 0 && l.project.id === meta.projectId || meta.project && (l.project.code.toLowerCase() === meta.project.toLowerCase() || l.project.slug.toLowerCase() === meta.project.toLowerCase())
+            (l) => meta.projectId !== void 0 && l.project.id === meta.projectId || meta.project && l.project.code.toLowerCase() === meta.project.toLowerCase()
           ) || loc;
           matches.push({ loc: matchedLoc, ticketDir, id: num });
         } catch {
@@ -1144,7 +1162,7 @@ ${formattedList}`
     if (this.config.projectCode) {
       const prefLower = this.config.projectCode.toLowerCase();
       const preferredMatch = matches.find(
-        (m) => m.loc.project.code.toLowerCase() === prefLower || m.loc.project.slug.toLowerCase() === prefLower
+        (m) => m.loc.project.code.toLowerCase() === prefLower
       );
       if (preferredMatch) return preferredMatch;
     }
@@ -1166,7 +1184,7 @@ ${formattedList}`
     for (const loc of locations) {
       if (filter?.project && filter.project !== "all") {
         const pLower = filter.project.toLowerCase();
-        if (!isProjectMatch(loc.project.code, loc.project.slug, filter.project)) {
+        if (!isProjectMatch(loc.project.code, filter.project)) {
           continue;
         }
       }
@@ -1198,7 +1216,7 @@ ${formattedList}`
           let effectiveLoc = loc;
           if (loc.isSharedDir) {
             const found = locations.find(
-              (l) => meta.projectId !== void 0 && l.project.id === meta.projectId || meta.project && (l.project.code.toLowerCase() === meta.project.toLowerCase() || l.project.slug.toLowerCase() === meta.project.toLowerCase())
+              (l) => meta.projectId !== void 0 && l.project.id === meta.projectId || meta.project && l.project.code.toLowerCase() === meta.project.toLowerCase()
             );
             if (found) effectiveLoc = found;
           }
@@ -1206,7 +1224,7 @@ ${formattedList}`
           meta.projectId = effectiveLoc.project.id;
           if (filter?.project && filter.project !== "all") {
             const pLower = filter.project.toLowerCase();
-            if (!isProjectMatch(meta.project, effectiveLoc.project.slug, filter.project)) {
+            if (!isProjectMatch(meta.project, filter.project)) {
               continue;
             }
           }
@@ -1373,7 +1391,7 @@ ${formattedList}`
     if (requestedIdentifier) {
       const lower = String(requestedIdentifier).trim().toLowerCase();
       targetLoc = locations.find(
-        (l) => l.project.code?.toLowerCase() === lower || l.project.slug?.toLowerCase() === lower || String(l.project.id) === lower || l.project.name?.toLowerCase() === lower
+        (l) => l.project.code?.toLowerCase() === lower || String(l.project.id) === lower || l.project.name?.toLowerCase() === lower
       );
       if (!targetLoc) {
         throw new Error(`Project '${requestedIdentifier}' is invalid or not registered in this workspace.`);
@@ -1410,7 +1428,62 @@ ${formattedList}`
       projectId: targetLoc.project.id,
       project: targetLoc.project.code
     };
-    const detailMd = `# Ticket #${nextId}: ${meta.title}
+    const rawDetail = (input.detailMarkdown || input.detail)?.trim();
+    let detailMd;
+    if (rawDetail) {
+      if (/^#\s+[^\n]+/m.test(rawDetail)) {
+        let processed = rawDetail.replace(/^#\s+[^\n]+/m, `# Ticket #${nextId}: ${meta.title}`);
+        if (!/\*\*(?:Type|Category)\*\*:/i.test(processed)) {
+          const metaBlock = `
+**Category**: ${meta.category}  
+**Complexity**: ${meta.complexity}  
+**Estimated Effort**: ${meta.estimatedEffort}  
+`;
+          processed = processed.replace(/^(# Ticket[^\n]+\n)/m, `$1${metaBlock}`);
+        }
+        if (!/(?:##|###)\s*(?:Summary|Rationale)/i.test(processed)) {
+          const summaryBlock = `
+### Summary
+${input.summary || "Summary to be defined."}
+`;
+          processed = processed.replace(/^((?:# Ticket[^\n]+\n)(?:\*\*[^\n]+\n)*)/m, `$1${summaryBlock}`);
+        }
+        detailMd = processed.endsWith("\n") ? processed : `${processed}
+`;
+      } else {
+        const hasSummary = /(?:##|###)\s*(?:Summary|Rationale)/i.test(rawDetail);
+        const hasBreakdown = /(?:##|###)\s*Feature Breakdown/i.test(rawDetail);
+        let body = "";
+        if (!hasSummary) {
+          body += `### Summary
+${input.summary || "Summary to be defined."}
+
+`;
+        }
+        if (!hasBreakdown && !rawDetail.startsWith("#")) {
+          body += `### Feature Breakdown
+${rawDetail}
+
+### Technical Details & Architecture
+- Architecture specifications to be documented.
+
+### Open Questions & Decisions
+- None recorded at initialization.
+`;
+        } else {
+          body += `${rawDetail}
+`;
+        }
+        detailMd = `# Ticket #${nextId}: ${meta.title}
+**Category**: ${meta.category}  
+**Complexity**: ${meta.complexity}  
+**Estimated Effort**: ${meta.estimatedEffort}  
+
+${body.trim()}
+`;
+      }
+    } else {
+      detailMd = `# Ticket #${nextId}: ${meta.title}
 **Category**: ${meta.category}  
 **Complexity**: ${meta.complexity}  
 **Estimated Effort**: ${meta.estimatedEffort}  
@@ -1428,6 +1501,7 @@ ${input.summary || "Summary to be defined."}
 ### Open Questions & Decisions
 - None recorded at initialization.
 `;
+    }
     writeSafeFile(path3.join(ticketDir, "meta.json"), JSON.stringify(meta, null, 2) + "\n");
     writeSafeFile(path3.join(ticketDir, "detail.md"), detailMd);
     const created = await this.getTicket(`${targetLoc.project.code}-${nextId}`);
@@ -2048,6 +2122,7 @@ Status: ${ticket.meta.status}`;
             complexity: { type: "string", description: "Complexity (e.g. Low, Medium, High)" },
             effort: { type: "string", description: "Estimated effort (e.g. 2.0 - 4.0 hours)" },
             summary: { type: "string", description: "Initial feature summary" },
+            detail: { type: "string", description: "Initial specification, feature breakdown, or technical detail markdown" },
             author: { type: "string", description: "Submitting author name" }
           },
           required: ["title"]
@@ -2138,6 +2213,8 @@ Status: ${ticket.meta.status}`;
           complexity: args.complexity,
           estimatedEffort: args.effort,
           summary: args.summary,
+          detail: args.detail || args.detailMarkdown,
+          detailMarkdown: args.detailMarkdown || args.detail,
           submittedBy: args.author || "Agent"
         });
         return created;
@@ -2579,11 +2656,13 @@ async function startDaemon(options = {}) {
   if (!pid) {
     throw new Error("Failed to spawn Esedre daemon background process.");
   }
+  const timeoutMs = process.platform === "win32" ? 1e4 : 5e3;
+  const pingTimeout = process.platform === "win32" ? 500 : 300;
   const startTime = Date.now();
   let ready = false;
-  while (Date.now() - startTime < 3500) {
-    await new Promise((r) => setTimeout(r, 100));
-    const ping = await pingDaemon(port, 150);
+  while (Date.now() - startTime < timeoutMs) {
+    await new Promise((r) => setTimeout(r, 150));
+    const ping = await pingDaemon(port, pingTimeout);
     if (ping.responding && ping.isEsedre) {
       ready = true;
       break;
@@ -2784,6 +2863,14 @@ exit /b %ERRORLEVEL%
 `;
 var WRAPPER_PS1 = `# Esedre Autonomous Ticketing & Project Planning Engine Wrapper (PowerShell)
 $ErrorActionPreference = "Stop"
+
+# Ensure UTF-8 console output and pipeline encoding on Windows
+try {
+    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+    [Console]::InputEncoding  = [System.Text.Encoding]::UTF8
+    $OutputEncoding = [System.Text.Encoding]::UTF8
+} catch {}
+
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 
 if (Get-Command "ese" -ErrorAction SilentlyContinue) {
@@ -2847,6 +2934,12 @@ REM Ese CLI short alias wrapper for Esedre (Windows CMD)
 call "%~dp0esedre.cmd" %*
 `;
 var ESE_WRAPPER_PS1 = `# Ese CLI short alias wrapper for Esedre (PowerShell)
+try {
+    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+    [Console]::InputEncoding  = [System.Text.Encoding]::UTF8
+    $OutputEncoding = [System.Text.Encoding]::UTF8
+} catch {}
+
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 & (Join-Path $scriptDir "esedre.ps1") @args
 exit $LASTEXITCODE
@@ -2858,7 +2951,9 @@ exec "$DIR/esedre" "$@"
 `;
 var HISTORIC_SKILL_HASHES = [
   "8611116c276fdfb598b965c716b251ce7c77c7f7",
-  "05f129fb6e06a18df00215af105567abcbf0bc67"
+  "05f129fb6e06a18df00215af105567abcbf0bc67",
+  "5d330ecf8fc96f383946e0351adb60378afa70f0",
+  "23716c9db561e52e5115dc364fe154d3a7bc1e23"
 ];
 var ESEDRE_SKILL_TEMPLATE = `---
 name: esedre
@@ -2869,9 +2964,18 @@ description: Tooling and workflow reference for interacting with the Esedre deve
 
 Esedre is the developer ticketing and LLM coding partner coordination platform. The engine codebase resides in the standalone repository \`aellinsar/esedre\` (\`../esedre\`), and operates on decoupled ticket repositories (such as \`aellinsar/esedre-data\` configured in \`.esedre/esedre.json\`). Interact with tickets via in-repo shell wrappers in \`.esedre/\` (\`.esedre/ese\`), or the global \`ese\` CLI.
 
-## 0. Instant Zero-Latency Context (\`.esedre/snapshot.json\`)
+## 0. Authoritative Ingress Hierarchy & Zero-Latency Context (\`.esedre/snapshot.json\`)
 
-Before querying tickets over the network or CLI, check \`.esedre/snapshot.json\` in the workspace root. It provides a local read-only projection containing all active and completed tickets, summaries, implementation plans, revision numbers, completion dates (\`completedAt\`), and staleness metrics (\`daysSinceUpdate\`).
+All ticket discovery, inspection, and state management strictly follow this positive ingress hierarchy:
+
+1. **Step 1 (Default for Read-Only Inspection) - Local Snapshot Projection**:
+   Always read \`.esedre/snapshot.json\` in the workspace root first. It provides an immediate, zero-latency local projection containing all active and completed tickets, summaries, implementation plans, revision numbers, completion dates (\`completedAt\`), and staleness metrics (\`daysSinceUpdate\`).
+2. **Step 2 (Dynamic Queries & State Mutations) - Esedre MCP Tools**:
+   Use first-class MCP tools when active in the session (\`esedre_list_tickets\`, \`esedre_get_ticket\`, \`esedre_get_plan\`, \`esedre_save_plan\`, \`esedre_update_ticket\`, \`esedre_add_comment\`).
+3. **Step 3 (Terminal & Script Fallback) - In-Repo CLI Wrapper**:
+   Use \`.esedre/ese\` (\`.esedre/ese get\`, \`.esedre/ese plan\`, \`.esedre/ese update\`, \`.esedre/ese snapshot\`, \`.esedre/ese refresh\`).
+4. **Storage Boundary**:
+   Backing ticket hubs (such as \`esedre-data\`) represent data storage managed by the engine. All agent interactions with roadmap tickets flow through the snapshot projection, MCP tools, or CLI wrappers.
 
 ## 1. Model Context Protocol (MCP) Tools
 
@@ -2883,7 +2987,7 @@ When Esedre MCP is active in your agent session (\`.agents/mcp_config.json\`), u
 | \`esedre_get_ticket\` | Full specification, summary, comments, revision & sha1 | \`ticketId\` (numeric e.g. \`96\` or compound e.g. \`Profe-96\`) |
 | \`esedre_get_plan\` | Active implementation plan markdown | \`ticketId\` (numeric or compound) |
 | \`esedre_save_plan\` | Save implementation plan markdown with OCC | \`ticketId\`, \`planMarkdown\`, \`lastHash\` |
-| \`esedre_create_ticket\` | Mint a new ticket with auto sequential ID | \`title\` (max 48 chars), \`type\`, \`project\`, \`effort\`, \`summary\` |
+| \`esedre_create_ticket\` | Mint a new ticket with auto sequential ID | \`title\` (max 48 chars), \`type\`, \`project\`, \`effort\`, \`summary\`, \`detail\` |
 | \`esedre_update_ticket\` | Update ticket attributes with OCC | \`ticketId\`, \`status\`, \`type\`, \`title\`, \`complexity\`, \`effort\`, \`inDevelopment\`, \`featureFlag\`, \`lastHash\` |
 | \`esedre_add_comment\` | Append developer or agent comment | \`ticketId\`, \`text\`, \`author\` |
 
@@ -2910,7 +3014,7 @@ Both \`esedre\` and \`ese\` work interchangeably:
 
 ### Create a Ticket
 \`\`\`bash
-.esedre/ese create --title "..." [-p|--project <code>] [-t|--type Feature] [--complexity Medium] [--effort "2.0 - 4.0 hours"] [--json]
+.esedre/ese create --title "..." [-p|--project <code>] [-t|--type Feature] [--complexity Medium] [--effort "2.0 - 4.0 hours"] [--detail "<md>"] [--file <path>] [--json]
 \`\`\`
 
 ### Update Ticket Status & Attributes
@@ -2929,6 +3033,7 @@ Both \`esedre\` and \`ese\` work interchangeably:
 ### Regenerate Snapshot
 \`\`\`bash
 .esedre/ese snapshot
+.esedre/ese refresh
 \`\`\`
 
 ### Server Lifecycle & Daemon Management
@@ -3228,7 +3333,6 @@ function configureWorkspace(targetDir, options = {}) {
       const projDesc = {
         id: 1,
         code: projectCode.toUpperCase(),
-        slug: projectCode.toLowerCase(),
         name: projectName || projectCode.toUpperCase(),
         description: `${projectName || projectCode.toUpperCase()} project`,
         colors: {
@@ -3281,6 +3385,18 @@ function configureWorkspace(targetDir, options = {}) {
   };
 }
 var initWorkspace = configureWorkspace;
+var ESEDRE_HUB_AGENTS_TEMPLATE = `# Agent Guidelines: esedre-data
+
+## 1. Role & Storage Boundary
+- **Backing Storage Repository**: \`esedre-data\` is a dedicated, decoupled data hub storing raw tickets, metadata manifests, and implementation plans managed by the Esedre engine.
+- **Authorized Ingress Channels**: Ticket discovery, read-only inspection, status updates, and plan authoring strictly ingress through the Esedre application layer in consuming project workspaces:
+  1. **Local Workspace Snapshot**: Check the consuming workspace's \`.esedre/snapshot.json\` first for instant, zero-latency read access to ticket summaries, plans, and statuses.
+  2. **Esedre MCP Tools**: Use \`esedre_get_ticket\`, \`esedre_list_tickets\`, \`esedre_get_plan\`, \`esedre_save_plan\`, and \`esedre_update_ticket\`.
+  3. **Esedre CLI**: Execute \`.esedre/ese get <id>\`, \`.esedre/ese list\`, or \`.esedre/ese plan\` from within the relevant project workspace.
+
+## 2. Ingress Redirection Protocol
+When inspecting or managing tickets for any project (such as \`Profe\`, \`Esedre\`, or \`Alce\`), navigate to that project's workspace and utilize its local \`.esedre/snapshot.json\`, Esedre MCP tools, or \`.esedre/ese\` CLI wrapper.
+`;
 function initHub(targetDir) {
   const resolved = path6.resolve(targetDir);
   if (!fs6.existsSync(resolved)) {
@@ -3298,9 +3414,16 @@ function initHub(targetDir) {
     fs6.writeFileSync(projectsJsonPath, "[]\n", "utf-8");
     projectsJsonCreated = true;
   }
+  const agentsMdPath = path6.join(resolved, "AGENTS.md");
+  let agentsMdCreated = false;
+  if (!fs6.existsSync(agentsMdPath)) {
+    fs6.writeFileSync(agentsMdPath, ESEDRE_HUB_AGENTS_TEMPLATE, "utf-8");
+    agentsMdCreated = true;
+  }
   return {
     projectsJsonCreated,
     projectsDirCreated,
+    agentsMdCreated,
     hubDir: resolved.replace(/\\/g, "/")
   };
 }
@@ -3401,16 +3524,30 @@ function sendJson(res, status, data) {
     "Content-Type": "application/json; charset=utf-8",
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, PATCH, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization"
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, x-esedre-allowed-projects"
   });
   res.end(JSON.stringify(data));
 }
-var cachedAllData = null;
-var cachedAllTimestamp = 0;
+var cachedAllData = /* @__PURE__ */ new Map();
 var CACHE_TTL_MS = 5e3;
 function invalidateApiCache() {
-  cachedAllData = null;
-  cachedAllTimestamp = 0;
+  cachedAllData.clear();
+}
+function getRequestStorage(baseStorage, req, url) {
+  const headerAllowed = req.headers["x-esedre-allowed-projects"];
+  const queryAllowed = url.searchParams.get("allowedProjects");
+  const rawAllowed = (typeof headerAllowed === "string" ? headerAllowed : Array.isArray(headerAllowed) ? headerAllowed[0] : null) || queryAllowed;
+  if (rawAllowed && typeof rawAllowed === "string") {
+    const list = rawAllowed.split(",").map((s) => s.trim()).filter(Boolean);
+    if (list.length > 0 && !list.includes("*")) {
+      const sortedKey = [...list].sort().join(",");
+      return {
+        storage: new SecurityFilter(baseStorage, { allowedProjects: list }),
+        cacheKey: sortedKey
+      };
+    }
+  }
+  return { storage: baseStorage, cacheKey: "*" };
 }
 function createApiHandler(storage, workspaceRoot) {
   return async (req, res) => {
@@ -3436,6 +3573,7 @@ function createApiHandler(storage, workspaceRoot) {
     if (pathname.startsWith("/esedre/api")) {
       pathname = pathname.slice("/esedre".length);
     }
+    const { storage: reqStorage, cacheKey } = getRequestStorage(storage, req, url);
     try {
       if (req.method === "GET") {
         if (pathname === "/api/ping") {
@@ -3443,7 +3581,7 @@ function createApiHandler(storage, workspaceRoot) {
           return true;
         }
         if (pathname === "/api/planning/projects") {
-          const projects = await storage.getProjects();
+          const projects = await reqStorage.getProjects();
           sendJson(res, 200, projects);
           return true;
         }
@@ -3453,7 +3591,7 @@ function createApiHandler(storage, workspaceRoot) {
           const type = url.searchParams.get("type") || url.searchParams.get("category") || void 0;
           const category = type;
           const search = url.searchParams.get("search") || void 0;
-          const tickets = await storage.listTickets({
+          const tickets = await reqStorage.listTickets({
             project: project === "all" ? void 0 : project,
             status,
             type,
@@ -3469,7 +3607,7 @@ function createApiHandler(storage, workspaceRoot) {
             sendJson(res, 400, { error: "Invalid ticket ID" });
             return true;
           }
-          const ticket = await storage.getTicket(idStr);
+          const ticket = await reqStorage.getTicket(idStr);
           if (!ticket) {
             sendJson(res, 400, { error: "Ticket not found" });
             return true;
@@ -3479,11 +3617,12 @@ function createApiHandler(storage, workspaceRoot) {
         }
         if (pathname === "/api/planning/all") {
           const now = Date.now();
-          if (cachedAllData && now - cachedAllTimestamp < CACHE_TTL_MS) {
-            sendJson(res, 200, cachedAllData);
+          const cached = cachedAllData.get(cacheKey);
+          if (cached && now - cached.timestamp < CACHE_TTL_MS) {
+            sendJson(res, 200, cached.data);
             return true;
           }
-          const tickets = await storage.listTickets({});
+          const tickets = await reqStorage.listTickets({});
           const metasMap = {};
           const detailsMap = {};
           const plansMap = {};
@@ -3513,7 +3652,7 @@ function createApiHandler(storage, workspaceRoot) {
               }
             }
           }
-          const projects = await storage.getProjects();
+          const projects = await reqStorage.getProjects();
           const responsePayload = {
             success: true,
             projects,
@@ -3526,13 +3665,12 @@ function createApiHandler(storage, workspaceRoot) {
             planHistory: {},
             ticketHistory: {}
           };
-          cachedAllData = responsePayload;
-          cachedAllTimestamp = now;
+          cachedAllData.set(cacheKey, { data: responsePayload, timestamp: now });
           sendJson(res, 200, responsePayload);
           return true;
         }
         if (pathname === "/api/planning/metas") {
-          const tickets = await storage.listTickets({});
+          const tickets = await reqStorage.listTickets({});
           const metasMap = {};
           for (const t of tickets) {
             metasMap[String(t.meta.id)] = t.meta;
@@ -3541,7 +3679,7 @@ function createApiHandler(storage, workspaceRoot) {
           return true;
         }
         if (pathname === "/api/planning/details") {
-          const tickets = await storage.listTickets({});
+          const tickets = await reqStorage.listTickets({});
           const detailsMap = {};
           for (const t of tickets) {
             if (t.detail?.raw) {
@@ -3552,7 +3690,7 @@ function createApiHandler(storage, workspaceRoot) {
           return true;
         }
         if (pathname === "/api/planning/plans") {
-          const tickets = await storage.listTickets({});
+          const tickets = await reqStorage.listTickets({});
           const plansMap = {};
           for (const t of tickets) {
             if (t.planMarkdown) {
@@ -3563,7 +3701,7 @@ function createApiHandler(storage, workspaceRoot) {
           return true;
         }
         if (pathname === "/api/planning/comments") {
-          const tickets = await storage.listTickets({});
+          const tickets = await reqStorage.listTickets({});
           const commentsMap = {};
           for (const t of tickets) {
             commentsMap[String(t.meta.id)] = t.comments || [];
@@ -3593,7 +3731,7 @@ function createApiHandler(storage, workspaceRoot) {
             sendJson(res, 400, { error: "Project query parameter is required for snapshot generation (no default fallback)." });
             return true;
           }
-          const snapshot = await generateProjectSnapshot(storage, projectCode, workspaceRoot);
+          const snapshot = await generateProjectSnapshot(reqStorage, projectCode, workspaceRoot);
           sendJson(res, 200, snapshot);
           return true;
         }
@@ -3602,7 +3740,7 @@ function createApiHandler(storage, workspaceRoot) {
         const body = await readJsonBody(req);
         if (pathname === "/api/planning/tickets") {
           invalidateApiCache();
-          const created = await storage.createTicket(body);
+          const created = await reqStorage.createTicket(body);
           sendJson(res, 201, { ticketId: String(created.meta.id), meta: created.meta });
           return true;
         }
@@ -3623,7 +3761,7 @@ function createApiHandler(storage, workspaceRoot) {
             return true;
           }
           invalidateApiCache();
-          const project = await storage.registerProject({
+          const project = await reqStorage.registerProject({
             code,
             name,
             description,
@@ -3636,27 +3774,27 @@ function createApiHandler(storage, workspaceRoot) {
         if (pathname === "/api/planning/plans") {
           const { ticketId, planMarkdown, lastHash } = body;
           invalidateApiCache();
-          await storage.savePlan(ticketId, planMarkdown, lastHash);
+          await reqStorage.savePlan(ticketId, planMarkdown, lastHash);
           sendJson(res, 200, { success: true });
           return true;
         }
         if (pathname === "/api/planning/comments") {
           const { ticketId, text, author } = body;
           invalidateApiCache();
-          await storage.addComment(ticketId, { author: author || "Developer", text });
-          const ticket = await storage.getTicket(ticketId);
+          await reqStorage.addComment(ticketId, { author: author || "Developer", text });
+          const ticket = await reqStorage.getTicket(ticketId);
           sendJson(res, 200, { comments: ticket?.comments || [] });
           return true;
         }
         if (pathname === "/api/planning/update-meta") {
           const { ticketId, updates, lastHash } = body;
-          const updated = await storage.updateTicket(ticketId, updates, lastHash);
+          const updated = await reqStorage.updateTicket(ticketId, updates, lastHash);
           sendJson(res, 200, { meta: updated.meta });
           return true;
         }
         if (pathname === "/api/planning/toggle-flag") {
           const { ticketId, flagged } = body;
-          const updated = await storage.updateTicket(ticketId, {
+          const updated = await reqStorage.updateTicket(ticketId, {
             featureFlag: flagged ? "chat_enhanced" : ""
           });
           sendJson(res, 200, { meta: updated.meta });
@@ -3665,7 +3803,7 @@ function createApiHandler(storage, workspaceRoot) {
         if (pathname === "/api/planning/details") {
           const { ticketId, detailMarkdown, metaUpdates } = body;
           if (metaUpdates) {
-            await storage.updateTicket(ticketId, metaUpdates);
+            await reqStorage.updateTicket(ticketId, metaUpdates);
           }
           sendJson(res, 200, { success: true, detail: detailMarkdown });
           return true;
@@ -3674,6 +3812,10 @@ function createApiHandler(storage, workspaceRoot) {
       sendJson(res, 404, { error: `Endpoint not found: ${pathname}` });
       return true;
     } catch (err) {
+      if (err.name === "EsedreAuthorizationError" || err.message?.includes("outside this workspace's authorized scope") || err.message?.includes("Access Denied")) {
+        sendJson(res, 403, { error: err.message });
+        return true;
+      }
       console.error("[Esedre API Error]:", err);
       sendJson(res, 500, { error: err.message });
       return true;
@@ -3847,7 +3989,7 @@ ${colors.bold}ROADMAP COMMANDS (Pair Programming & LLM Agents):${colors.reset}
   ${colors.bold}plan${colors.reset}        <id> [--file <path> | --set "<markdown>"] [--last-hash <sha1>] [--json]
                View or update implementation plan with optimistic concurrency control.
 
-  ${colors.bold}create${colors.reset}      --title "..." [-p|--project <code>] [-t|--type <type>] [--complexity <c>] [--effort "<e>"] [--summary "<s>"] [--json]
+  ${colors.bold}create${colors.reset}      --title "..." [-p|--project <code>] [-t|--type <type>] [--complexity <c>] [--effort "<e>"] [--summary "<s>"] [--detail "<md>"] [--file <path>] [--json]
                Mint a new roadmap ticket with sequential numeric ID.
 
   ${colors.bold}update${colors.reset}      <id> [-s|--status <status>] [-t|--type <type>] [--title "..."] [--complexity <c>] [--effort "<e>"] [--in-dev] [--flag <name>] [--last-hash <sha1>] [--force] [--json]
@@ -3856,7 +3998,7 @@ ${colors.bold}ROADMAP COMMANDS (Pair Programming & LLM Agents):${colors.reset}
   ${colors.bold}comment${colors.reset}     <id> ["<text>"] [--text "..."] [--author "..."] [--json]
                Append a research finding, test verification, or note to ticket history.
 
-  ${colors.bold}snapshot${colors.reset}    [--project <code>] [--json]
+  ${colors.bold}snapshot, refresh${colors.reset} [--project <code>] [--json]
                Generate lean read-only projection snapshot (.esedre/snapshot.json) for zero-latency agent context.
 
 ${colors.bold}SERVICE DAEMON COMMANDS:${colors.reset}
@@ -3900,6 +4042,8 @@ ${colors.bold}OPTIONS:${colors.reset}
   -t, --type <type>    Ticket type ('Feature', 'Platform', 'Tools', 'Idea', 'Bug').
   -s, --status <stat>  Ticket status ('Planned', 'In Development', 'Completed', 'Rejected').
   -q, --search <query> Case-insensitive substring search query.
+  --detail "<md>"      Specification markdown for ticket detail during create.
+  --file <path>        Path to markdown file for detail (create) or implementation plan (plan).
   --json              Output raw machine-readable JSON (strongly recommended for autonomous LLM coding agents).
   --last-hash <hash>  Optimistic concurrency control: last known sha1 hash of the ticket from 'get'.
   --force             Bypass optimistic concurrency last-hash conflict checks on writes.
@@ -4412,6 +4556,7 @@ ${colors.bold}Commands:${colors.reset}`);
         }
         return;
       }
+      case "refresh":
       case "snapshot": {
         const projectCode = flags["project"] || discovered.config?.projectCode;
         if (!projectCode) {
@@ -4435,17 +4580,22 @@ ${colors.bold}Commands:${colors.reset}`);
         return;
       }
       case "start": {
-        printDuplicateProjectWarnings(storage, isJson);
         const flagPort = flags["port"] ? parseInt(String(flags["port"]), 10) : void 0;
         const ports = resolvePorts(discovered.config, { port: flagPort });
         const port = ports.gateway;
         const isForeground = Boolean(flags["foreground"] || flags["f"]);
+        const serverConfig = {
+          ...discovered.config,
+          allowedProjects: ["*"]
+        };
+        const serverStorage = new FilesystemStorageAdapter(discovered.workspaceRoot, serverConfig);
+        printDuplicateProjectWarnings(serverStorage, isJson);
         if (isForeground) {
           const cluster = startGatewayCluster({
             gatewayPort: ports.gateway,
             uiPort: ports.ui,
             apiPort: ports.api,
-            storage,
+            storage: serverStorage,
             workspaceRoot: discovered.workspaceRoot
           });
           console.log(`${colors.bold}${colors.green}\u2714 Esedre Server active on http://localhost:${ports.gateway}${colors.reset}`);
@@ -4613,12 +4763,27 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
             content = fs9.readFileSync(filePath, "utf-8");
           }
           await storage.savePlan(id, content, lastHash);
-          console.log(`${colors.green}\u2714 Implementation plan saved for Ticket #${id}${colors.reset}`);
+          if (isJson) {
+            const updated = await storage.getTicket(id);
+            console.log(JSON.stringify({
+              success: true,
+              ticketId: id,
+              project: updated?.projectDescriptor?.code || updated?.meta?.project || "UNASSIGNED",
+              planMarkdown: content,
+              sha1: updated?.sha1 || updated?.meta?.sha1
+            }, null, 2));
+          } else {
+            console.log(`${colors.green}\u2714 Implementation plan saved for Ticket #${id}${colors.reset}`);
+          }
           return;
         }
         const plan = await storage.getPlan(id);
         if (!plan) {
-          console.log(`${colors.dim}No implementation plan found for Ticket #${id}.${colors.reset}`);
+          if (isJson) {
+            console.log(JSON.stringify({ ticketId: id, planMarkdown: null }, null, 2));
+          } else {
+            console.log(`${colors.dim}No implementation plan found for Ticket #${id}.${colors.reset}`);
+          }
           return;
         }
         if (isJson) {
@@ -4651,6 +4816,21 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
           console.error(`${colors.red}Error: ${val.error}${colors.reset}`);
           process.exit(1);
         }
+        const detailArg = flags["detail"];
+        const fileArg = flags["file"];
+        let detailMarkdown = detailArg;
+        if (fileArg) {
+          const filePath = path9.resolve(fileArg);
+          if (!fs9.existsSync(filePath)) {
+            if (isJson) {
+              console.error(JSON.stringify({ error: `Detail file "${fileArg}" not found` }));
+            } else {
+              console.error(`${colors.red}Error: Detail file "${fileArg}" not found.${colors.reset}`);
+            }
+            process.exit(1);
+          }
+          detailMarkdown = fs9.readFileSync(filePath, "utf-8");
+        }
         const created = await storage.createTicket({
           title,
           type,
@@ -4659,7 +4839,9 @@ ${colors.dim}Total: ${tickets.length} tickets${colors.reset}`);
           complexity,
           estimatedEffort,
           summary,
-          submittedBy
+          submittedBy,
+          detail: detailMarkdown,
+          detailMarkdown
         });
         if (isJson) {
           console.log(JSON.stringify(created, null, 2));