@dinasor/mnemo-cli 0.0.3 → 0.0.6

package/memory_mac.sh

@@ -11,7 +11,7 @@
 #   sh ./memory_mac.sh --enable-vector --vector-provider gemini
 #
 # This creates:
-#   .cursor/memory/*, .cursor/rules/*, scripts/memory/*, .githooks/pre-commit
+#   .cursor/memory/*, .cursor/rules/*, .cursor/skills/*, scripts/memory/*, .githooks/pre-commit
 #   (and optional .githooks/post-commit when --enable-vector is used)
 
 set -eu
@@ -126,6 +126,17 @@ write_file() {
   printf '%s\n' "WROTE: $path"
 }
 
+install_template_file() {
+  # install_template_file <template_path> <dest_path>
+  template_path="$1"
+  dest_path="$2"
+  if [ ! -f "$template_path" ]; then
+    printf '%s\n' "WARNING: Template not found: $template_path"
+    return 0
+  fi
+  write_file "$dest_path" < "$template_path"
+}
+
 sync_dir_one_way() {
   src="$1"
   dst="$2"
@@ -599,6 +610,14 @@ This project uses Mnemo for structured AI memory. All memory lives in `.cursor/m
 - Clear active-context.md when task is merged
 EOF
 
+# -------------------------
+# Cursor project skills
+# -------------------------
+
+_skills_tpl_dir="$_INSTALLER_DIR/scripts/memory/installer/templates/skills/mnemo-codebase-optimizer"
+install_template_file "$_skills_tpl_dir/SKILL.md" "$CURSOR_DIR/skills/mnemo-codebase-optimizer/SKILL.md"
+install_template_file "$_skills_tpl_dir/reference.md" "$CURSOR_DIR/skills/mnemo-codebase-optimizer/reference.md"
+
 write_file "$MEM_SCRIPTS_DIR/customization.md" <<'EOF'
 # Mnemo Memory Customization Prompt (paste into an AI)
 
@@ -1843,6 +1862,17 @@ def _resolve_memory_root() -> Path:
     return script_repo / ".mnemo" / "memory"
 
 
+def _resolve_repo_root(memory_root: Path) -> Path:
+    root = memory_root.resolve()
+    if root.name == "memory" and root.parent.name in {".mnemo", ".cursor"}:
+        return root.parent.parent
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if candidate.joinpath(".mnemo", "memory").exists() or candidate.joinpath(".cursor", "memory").exists():
+            return candidate
+    return cwd
+
+
 def _parse_env_line(raw_line: str):
     line = raw_line.strip()
     if not line or line.startswith("#"):
@@ -1863,10 +1893,26 @@ def _parse_env_line(raw_line: str):
     return key, value
 
 
-def _load_project_env() -> None:
-    if os.getenv("GEMINI_API_KEY"):
-        return
-    env_path = Path(".env")
+def _is_missing_env_value(value):
+    if value is None:
+        return True
+    stripped = str(value).strip()
+    if not stripped:
+        return True
+    if stripped.startswith("${env:") and stripped.endswith("}"):
+        return True
+    return False
+
+
+def _get_env_value(name: str) -> str:
+    value = os.getenv(name)
+    if _is_missing_env_value(value):
+        return ""
+    return str(value).strip()
+
+
+def _load_project_env(repo_root: Path) -> None:
+    env_path = repo_root / ".env"
     if not env_path.exists():
         return
     try:
@@ -1875,16 +1921,28 @@ def _load_project_env() -> None:
             if not parsed:
                 continue
             key, value = parsed
-            os.environ.setdefault(key, value)
+            key = key.lstrip("\ufeff")
+            if _is_missing_env_value(os.getenv(key)):
+                os.environ[key] = value
     except OSError:
         pass
 
 
+def _resolve_provider() -> str:
+    configured = os.getenv("MNEMO_PROVIDER", "").strip().lower()
+    if configured.startswith("${env:") and configured.endswith("}"):
+        configured = ""
+    if configured in {"openai", "gemini"}:
+        return configured
+    return "gemini" if _get_env_value("GEMINI_API_KEY") else "openai"
+
+
 MEM_ROOT = _resolve_memory_root()
+REPO_ROOT = _resolve_repo_root(MEM_ROOT)
 _DB_OVERRIDE = os.getenv("MNEMO_DB_PATH", "").strip()
 DB_PATH = Path(_DB_OVERRIDE).expanduser().resolve() if _DB_OVERRIDE else (MEM_ROOT / "mnemo_vector.sqlite")
-_load_project_env()
-PROVIDER = os.getenv("MNEMO_PROVIDER", "gemini" if os.getenv("GEMINI_API_KEY") else "openai").lower()
+_load_project_env(REPO_ROOT)
+PROVIDER = _resolve_provider()
 
 SKIP_NAMES = {
     "README.md",
@@ -1911,14 +1969,14 @@ def _get_embed_client():
         return _EMBED_CLIENT
 
     if PROVIDER == "gemini":
-        key = os.getenv("GEMINI_API_KEY")
+        key = _get_env_value("GEMINI_API_KEY")
         if not key:
             raise RuntimeError("GEMINI_API_KEY is not set")
         from google import genai
         _EMBED_CLIENT = genai.Client(api_key=key)
         return _EMBED_CLIENT
 
-    key = os.getenv("OPENAI_API_KEY")
+    key = _get_env_value("OPENAI_API_KEY")
     if not key:
         raise RuntimeError("OPENAI_API_KEY is not set")
     from openai import OpenAI
@@ -2388,6 +2446,7 @@ GI_END="# <<< Mnemo (generated) >>>"
 ignore_lines=".mnemo/
 .cursor/memory/
 .cursor/rules/
+.cursor/skills/
 .cursor/mcp.json
 .agent/rules/
 scripts/memory/
@@ -2461,6 +2520,7 @@ fi
 echo ""
 echo "Setup complete. (Mnemo v$MNEMO_VERSION)"
 echo "Next:"
+echo "  skill: .cursor/skills/mnemo-codebase-optimizer/SKILL.md"
 echo "  sh ./scripts/memory/rebuild-memory-index.sh"
 echo "  sh ./scripts/memory/lint-memory.sh"
 if [ "$ENABLE_VECTOR" = "1" ] && [ "$DRY_RUN" != "1" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinasor/mnemo-cli",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Mnemo installer CLI for the current project folder.",
   "license": "MIT",
   "repository": {

package/scripts/memory/installer/features/gitignore_setup.ps1

@@ -1,68 +1,69 @@
-<#
-gitignore_setup.ps1 - Managed .gitignore block for Mnemo generated artifacts.
-Dot-sourced by bootstrap.ps1.
-#>
-
-function Update-MnemoGitignore {
-  param(
-    [Parameter(Mandatory=$true)][hashtable]$Ctx,
-    [switch]$EnableVector
-  )
-
-  $giPath = Join-Path $Ctx.RepoRoot ".gitignore"
-  $giBeginMarker = "# >>> Mnemo (generated) - do not edit this block manually <<<"
-  $giEndMarker   = "# <<< Mnemo (generated) >>>"
-
-  # User-facing default: ignore the full Mnemo generated footprint so target repos stay clean by default.
-  $ignoreLines = @(
-    ".mnemo/",
-    ".cursor/memory/",
-    ".cursor/rules/",
-    ".cursor/mcp.json",
-    ".agent/rules/",
-    "scripts/memory/",
-    ".githooks/"
-  )
-
-  $giLineEndings = "CRLF"
-  $giContent = ""
-  if (Test-Path $giPath) {
-    $giContent = Get-Content -Raw -Encoding UTF8 -ErrorAction SilentlyContinue $giPath
-    if ($null -eq $giContent) { $giContent = "" }
-    if ($giContent.Length -gt 0 -and [int]$giContent[0] -eq 0xFEFF) { $giContent = $giContent.Substring(1) }
-    $giLineEndings = if ($giContent -match "`r`n") { "CRLF" } else { "LF" }
-  }
-
-  $newBlock = $giBeginMarker + "`n" + ($ignoreLines -join "`n") + "`n" + $giEndMarker
-
-  if ($script:DryRun) {
-    Write-Host "[DRY RUN] WOULD UPDATE: $giPath (managed Mnemo block)" -ForegroundColor DarkCyan
-    return
-  }
-
-  $beginEsc = [regex]::Escape($giBeginMarker)
-  $endEsc   = [regex]::Escape($giEndMarker)
-  $blockPattern = "(?s)$beginEsc.*?$endEsc"
-
-  if ($giContent -match $blockPattern) {
-    $newContent = [regex]::Replace($giContent, $blockPattern, $newBlock.Replace('$', '$$'))
-    $existingNorm = $giContent -replace "`r?`n", "`n"
-    $newNorm      = $newContent -replace "`r?`n", "`n"
-    if ($newNorm -ne $existingNorm) {
-      $enc = New-Object System.Text.UTF8Encoding($false)
-      $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
-      [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
-      Write-Host "WROTE: $giPath (updated Mnemo managed block)" -ForegroundColor Green
-    } else {
-      Write-Host "SKIP (exists): $giPath (Mnemo managed block unchanged)" -ForegroundColor DarkYellow
-    }
-  } else {
-    $trimmed = $giContent.TrimEnd("`r", "`n")
-    $sep = if ($trimmed.Length -gt 0) { "`n`n" } else { "" }
-    $newContent = $trimmed + $sep + $newBlock + "`n"
-    $enc = New-Object System.Text.UTF8Encoding($false)
-    $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
-    [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
-    Write-Host "WROTE: $giPath (added Mnemo managed block)" -ForegroundColor Green
-  }
-}
+<#
+gitignore_setup.ps1 - Managed .gitignore block for Mnemo generated artifacts.
+Dot-sourced by bootstrap.ps1.
+#>
+
+function Update-MnemoGitignore {
+  param(
+    [Parameter(Mandatory=$true)][hashtable]$Ctx,
+    [switch]$EnableVector
+  )
+
+  $giPath = Join-Path $Ctx.RepoRoot ".gitignore"
+  $giBeginMarker = "# >>> Mnemo (generated) - do not edit this block manually <<<"
+  $giEndMarker   = "# <<< Mnemo (generated) >>>"
+
+  # User-facing default: ignore the full Mnemo generated footprint so target repos stay clean by default.
+  $ignoreLines = @(
+    ".mnemo/",
+    ".cursor/memory/",
+    ".cursor/rules/",
+    ".cursor/skills/",
+    ".cursor/mcp.json",
+    ".agent/rules/",
+    "scripts/memory/",
+    ".githooks/"
+  )
+
+  $giLineEndings = "CRLF"
+  $giContent = ""
+  if (Test-Path $giPath) {
+    $giContent = Get-Content -Raw -Encoding UTF8 -ErrorAction SilentlyContinue $giPath
+    if ($null -eq $giContent) { $giContent = "" }
+    if ($giContent.Length -gt 0 -and [int]$giContent[0] -eq 0xFEFF) { $giContent = $giContent.Substring(1) }
+    $giLineEndings = if ($giContent -match "`r`n") { "CRLF" } else { "LF" }
+  }
+
+  $newBlock = $giBeginMarker + "`n" + ($ignoreLines -join "`n") + "`n" + $giEndMarker
+
+  if ($script:DryRun) {
+    Write-Host "[DRY RUN] WOULD UPDATE: $giPath (managed Mnemo block)" -ForegroundColor DarkCyan
+    return
+  }
+
+  $beginEsc = [regex]::Escape($giBeginMarker)
+  $endEsc   = [regex]::Escape($giEndMarker)
+  $blockPattern = "(?s)$beginEsc.*?$endEsc"
+
+  if ($giContent -match $blockPattern) {
+    $newContent = [regex]::Replace($giContent, $blockPattern, $newBlock.Replace('$', '$$'))
+    $existingNorm = $giContent -replace "`r?`n", "`n"
+    $newNorm      = $newContent -replace "`r?`n", "`n"
+    if ($newNorm -ne $existingNorm) {
+      $enc = New-Object System.Text.UTF8Encoding($false)
+      $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
+      [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
+      Write-Host "WROTE: $giPath (updated Mnemo managed block)" -ForegroundColor Green
+    } else {
+      Write-Host "SKIP (exists): $giPath (Mnemo managed block unchanged)" -ForegroundColor DarkYellow
+    }
+  } else {
+    $trimmed = $giContent.TrimEnd("`r", "`n")
+    $sep = if ($trimmed.Length -gt 0) { "`n`n" } else { "" }
+    $newContent = $trimmed + $sep + $newBlock + "`n"
+    $enc = New-Object System.Text.UTF8Encoding($false)
+    $normalized = if ($giLineEndings -eq "CRLF") { $newContent -replace "`r?`n", "`r`n" } else { $newContent -replace "`r?`n", "`n" }
+    [System.IO.File]::WriteAllText($giPath, $normalized, $enc)
+    Write-Host "WROTE: $giPath (added Mnemo managed block)" -ForegroundColor Green
+  }
+}

package/scripts/memory/installer/features/memory_scaffold.ps1

@@ -436,6 +436,16 @@ function Install-MemoryScripts {
       -ForceWrite:$Force
   }
 
+  $cursorSkillTemplates = @("SKILL.md", "reference.md")
+  foreach ($f in $cursorSkillTemplates) {
+    Install-TemplateFile `
+      -TemplateName "skills\mnemo-codebase-optimizer\$f" `
+      -DestPath (Join-Path $Ctx.CursorDir "skills\mnemo-codebase-optimizer\$f") `
+      -InstallerRoot $InstallerRoot `
+      -LineEndings "LF" `
+      -ForceWrite:$Force
+  }
+
   if ($EnableVector) {
     Install-TemplateFile `
       -TemplateName "mnemo_vector.py" `

package/scripts/memory/installer/templates/mnemo_vector.py

@@ -77,10 +77,26 @@ def _parse_env_line(raw_line: str) -> tuple[str, str] | None:
     return key, value
 
 
+def _is_missing_env_value(value: str | None) -> bool:
+    if value is None:
+        return True
+    stripped = value.strip()
+    if not stripped:
+        return True
+    # Cursor MCP placeholders can arrive as literal strings in some launches.
+    if stripped.startswith("${env:") and stripped.endswith("}"):
+        return True
+    return False
+
+
+def _get_env_value(name: str) -> str:
+    value = os.getenv(name)
+    if _is_missing_env_value(value):
+        return ""
+    return value.strip()
+
+
 def _load_project_env(repo_root: Path) -> None:
-    # Keep shell-provided values authoritative; only fill missing vars from .env.
-    if os.getenv("GEMINI_API_KEY"):
-        return
     env_path = repo_root / ".env"
     if not env_path.exists():
         return
@@ -90,17 +106,28 @@ def _load_project_env(repo_root: Path) -> None:
             if not parsed:
                 continue
             key, value = parsed
-            os.environ.setdefault(key, value)
+            key = key.lstrip("\ufeff")
+            if _is_missing_env_value(os.getenv(key)):
+                os.environ[key] = value
     except OSError:
         pass
 
 
+def _resolve_provider() -> str:
+    configured = os.getenv("MNEMO_PROVIDER", "").strip().lower()
+    if configured.startswith("${env:") and configured.endswith("}"):
+        configured = ""
+    if configured in {"openai", "gemini"}:
+        return configured
+    return "gemini" if _get_env_value("GEMINI_API_KEY") else "openai"
+
+
 MEM_ROOT = _resolve_memory_root()
 REPO_ROOT = _resolve_repo_root(MEM_ROOT)
 _load_project_env(REPO_ROOT)
 _DB_OVERRIDE = os.getenv("MNEMO_DB_PATH", "").strip()
 DB_PATH = Path(_DB_OVERRIDE).expanduser().resolve() if _DB_OVERRIDE else (MEM_ROOT / "mnemo_vector.sqlite")
-PROVIDER = os.getenv("MNEMO_PROVIDER", "gemini" if os.getenv("GEMINI_API_KEY") else "openai").lower()
+PROVIDER = _resolve_provider()
 
 SKIP_NAMES = {
     "README.md", "index.md", "lessons-index.json",
@@ -158,14 +185,14 @@ def _get_embed_client():
         return _EMBED_CLIENT
 
     if PROVIDER == "gemini":
-        key = os.getenv("GEMINI_API_KEY")
+        key = _get_env_value("GEMINI_API_KEY")
         if not key:
             raise RuntimeError("GEMINI_API_KEY is not set")
         from google import genai
         _EMBED_CLIENT = genai.Client(api_key=key)
         return _EMBED_CLIENT
 
-    key = os.getenv("OPENAI_API_KEY")
+    key = _get_env_value("OPENAI_API_KEY")
     if not key:
         raise RuntimeError("OPENAI_API_KEY is not set")
     from openai import OpenAI

package/scripts/memory/installer/templates/skills/mnemo-codebase-optimizer/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: mnemo-codebase-optimizer
+description: Builds high-signal Mnemo memory quickly for any codebase by mapping architecture, ownership, workflows, risks, and commands, then writing optimized memo/hot-rules/active-context/lessons/journal entries and validating retrieval quality. Use when users ask to bootstrap Mnemo memory, optimize project context, or fill memory in a new or existing repository.
+---
+
+# Mnemo Codebase Optimizer
+
+## Purpose
+
+Use this skill to rapidly produce a detailed, reliable Mnemo knowledge base for any project.
+The goal is high retrieval quality with low token waste.
+
+## Quick Start
+
+Use this checklist and keep one step `in_progress` at a time:
+
+```text
+Memory Seeding Progress
+- [ ] 1) Confirm Mnemo install + paths
+- [ ] 2) Map codebase architecture and ownership
+- [ ] 3) Extract runbook commands and dev workflows
+- [ ] 4) Write/update core memory files
+- [ ] 5) Add initial lessons and journal summary
+- [ ] 6) Rebuild + lint + (optional) vector sync
+- [ ] 7) Validate retrieval quality and refine
+```
+
+## 1) Confirm Mnemo Install
+
+Verify these paths exist:
+- `.mnemo/memory/`
+- `.mnemo/rules/`
+- `scripts/memory/`
+
+If missing, run installer first and stop this skill until setup succeeds.
+
+## 2) Map Architecture Fast
+
+Collect only high-value context:
+- product purpose and core user flows
+- entrypoints and runtime boundaries (frontend/backend/workers/CLI)
+- module ownership and key responsibilities
+- data model sources and contracts
+- integration surfaces (APIs, queues, webhooks, external services)
+- quality/security constraints and release workflow
+
+Avoid copying large code blocks into memory files. Summarize and reference paths.
+
+## 3) Capture Operational Workflow
+
+Record:
+- install/build/test/lint commands
+- local run commands for each app/service
+- deployment/release commands and prerequisites
+- debugging commands and common failure signatures
+
+Prefer explicit command examples over vague prose.
+
+## 4) Write Core Memory Files
+
+Update these files in priority order:
+
+1. `.mnemo/memory/hot-rules.md`
+   - 10-20 lines max
+   - only hard invariants and "never do" rules
+2. `.mnemo/memory/memo.md`
+   - architecture map, ownership, critical paths, runbook
+3. `.mnemo/memory/active-context.md`
+   - current migration task + open risks + next actions
+
+Use short sections and bullets. Keep each bullet atomic and testable.
+
+## 5) Seed Lessons + Journal
+
+Create 3-8 starter lessons from known pitfalls:
+- naming conventions
+- data migration gotchas
+- environment/setup traps
+- release regressions and prevention checks
+
+Add one monthly journal entry summarizing:
+- what memory was seeded
+- why those sections matter
+- what remains unknown
+
+## 6) Rebuild and Validate
+
+Run:
+- `scripts/memory/rebuild-memory-index.ps1` (or shell equivalent)
+- `scripts/memory/lint-memory.ps1` (or shell equivalent)
+
+If vector mode is enabled:
+- run `vector_sync`
+- run `vector_health`
+
+## 7) Retrieval Quality Gate
+
+Ask 5-10 realistic queries and verify results:
+- architecture query (module boundaries)
+- workflow query (how to run/test/release)
+- ownership query (who owns what)
+- pitfall query (common mistakes)
+- troubleshooting query (known failure/fix)
+
+If retrieval misses:
+- tighten memo headings
+- split overloaded bullets
+- add a lesson instead of bloating memo
+- prune low-signal historical text
+
+## Memory Quality Rules
+
+- Keep `hot-rules.md` tiny and immutable-focused.
+- Keep `memo.md` as current truth, not raw history.
+- Put historical detail in journal, not memo.
+- Prefer lessons for reusable error-prevention patterns.
+- Use stable terminology for search consistency.
+- Every important claim should map to concrete file paths or commands.
+
+## Output Contract
+
+When done, return:
+
+1. **Coverage summary**
+   - what domains are now represented in memory
+2. **Files changed**
+   - list of memory files updated/created
+3. **Quality checks**
+   - rebuild/lint/vector status
+4. **Top retrieval queries**
+   - sample queries and expected hit files
+5. **Remaining unknowns**
+   - explicit gaps to fill in next pass
+
+## Additional Resources
+
+- Detailed templates: [reference.md](reference.md)

package/scripts/memory/installer/templates/skills/mnemo-codebase-optimizer/reference.md

@@ -0,0 +1,138 @@
+# Mnemo Codebase Optimizer Reference
+
+## Memo Template (Detailed)
+
+Use this structure for `.mnemo/memory/memo.md`:
+
+```markdown
+# Project Memo - <project>
+
+## Mission
+- One-paragraph purpose and primary user outcomes.
+
+## System Shape
+- Runtime components:
+  - `<component>`: `<responsibility>`
+- Boundaries:
+  - `<boundary>` -> `<dependency>`
+
+## Ownership Map
+- `<module/path>` -> `<team/owner>`
+- `<module/path>` -> `<team/owner>`
+
+## Critical Flows
+- Flow A:
+  - Trigger:
+  - Core path:
+  - Side effects:
+  - Failure modes:
+- Flow B:
+  - Trigger:
+  - Core path:
+  - Side effects:
+  - Failure modes:
+
+## Data Contracts
+- `<type/schema/file>`: purpose + key fields + constraints
+- `<type/schema/file>`: purpose + key fields + constraints
+
+## Commands Runbook
+- Install: `<command>`
+- Dev run: `<command>`
+- Tests: `<command>`
+- Lint/format: `<command>`
+- Build/release: `<command>`
+
+## Constraints and Guardrails
+- Non-negotiables:
+  - `<rule>`
+  - `<rule>`
+- Security/compliance:
+  - `<constraint>`
+
+## Known Risks
+- `<risk>` -> detection -> mitigation
+- `<risk>` -> detection -> mitigation
+```
+
+## Hot Rules Template
+
+Use this structure for `.mnemo/memory/hot-rules.md` (10-20 lines):
+
+```markdown
+# Hot Rules
+
+- Never bypass `<critical check>`.
+- Do not edit `<generated path>` manually.
+- Keep `<artifact>` synchronized with `<source>`.
+- Before release: run `<required command list>`.
+- If `<failure condition>`, stop and verify `<source of truth>`.
+```
+
+## Active Context Template
+
+Use this structure for `.mnemo/memory/active-context.md`:
+
+```markdown
+# Active Context
+
+## Current Task
+- Goal:
+- Scope:
+- Out of scope:
+
+## Working Notes
+- Current status:
+- Decisions made:
+- Risks and blockers:
+
+## Next Actions
+1. `<action>`
+2. `<action>`
+3. `<action>`
+```
+
+## Starter Lesson Template
+
+Use this for each `L-XXX-*.md`:
+
+```markdown
+---
+id: L-XXX
+title: "<short pitfall title>"
+tags: ["pitfall", "regression", "<domain>"]
+applies_to: ["<path/glob>"]
+rule: "<single actionable rule>"
+---
+
+## Context
+When this appears and why it happens.
+
+## Failure Pattern
+Observable signs and likely root causes.
+
+## Corrective Action
+Exact steps to fix safely.
+
+## Prevention Check
+How to detect it before merge/release.
+```
+
+## Retrieval Validation Query Set
+
+Run and confirm each query returns high-signal files:
+
+1. "What are the core runtime boundaries?"
+2. "Which files define the main data contracts?"
+3. "How do I run full tests and lint before release?"
+4. "What regressions happened before and how do we prevent them?"
+5. "Who owns `<critical module>` and what are the rules?"
+6. "What are the top production risks in this repo?"
+
+## Optimization Heuristics
+
+- Prefer one clear heading over long paragraphs.
+- Replace duplicate bullets with one canonical bullet.
+- If a memo section grows too long, split into lessons.
+- Keep journaling chronological; keep memo conceptual.
+- Remove stale TODOs from memo; keep only current truth.