arkaos 4.5.0 → 4.7.0

package/core/runtime/mcp_telemetry.py

@@ -0,0 +1,184 @@
+"""MCP usage telemetry (audit E2E v4.3.6, P1).
+
+Writer + summarizer for ``~/.arkaos/telemetry/mcp-usage.jsonl``. The
+PostToolUse hook calls :func:`record` on every tool event; MCP tool
+names (``mcp__<server>__<tool>``) are parsed and appended as one JSONL
+line, everything else is ignored. Before this module the only usage
+signal was grepping session transcripts.
+
+Mirrors ``core.governance.enforcement_telemetry`` so periods,
+malformed-line tolerance, and zero-division safety behave the same way
+across telemetry surfaces. :func:`summarise` is read-only.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+DEFAULT_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "mcp-usage.jsonl"
+_VALID_PERIODS: frozenset[str] = frozenset({"today", "week", "month", "all"})
+_TOP_SERVERS: int = 10
+_TOP_TOOLS: int = 5
+_MCP_PREFIX = "mcp__"
+
+
+@dataclass(frozen=True)
+class McpUsageSummary:
+    """Aggregated MCP usage over a time slice."""
+    period: str
+    total_calls: int
+    unique_servers: int
+    top_servers: list[tuple[str, int]] = field(default_factory=list)
+    top_tools: list[tuple[str, int]] = field(default_factory=list)
+    corrupt_line_count: int = 0
+
+
+def parse_mcp_tool(tool_name: str) -> tuple[str, str] | None:
+    """Split ``mcp__<server>__<tool>`` into (server, tool).
+
+    Returns None for non-MCP tool names. Handles servers whose slug
+    contains single underscores (``claude_ai_Canva``, plugin servers
+    like ``plugin_claude-mem_mcp-search``) by splitting on the FIRST
+    double underscore after the prefix.
+    """
+    if not tool_name.startswith(_MCP_PREFIX):
+        return None
+    rest = tool_name[len(_MCP_PREFIX):]
+    server, sep, tool = rest.partition("__")
+    if not sep or not server or not tool:
+        return None
+    return server, tool
+
+
+def record(
+    tool_name: str,
+    *,
+    session_id: str = "",
+    path: Path | None = None,
+) -> bool:
+    """Append one usage line when tool_name is an MCP tool.
+
+    Never raises — the caller is a hook that must not block on
+    telemetry. Returns True when a line was written.
+    """
+    parsed = parse_mcp_tool(tool_name)
+    if parsed is None:
+        return False
+    server, tool = parsed
+    dest = path or DEFAULT_PATH
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "server": server,
+        "tool": tool,
+        "session": session_id,
+    }
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with dest.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError:
+        return False
+    return True
+
+
+def summarise(period: str, *, path: Path | None = None) -> McpUsageSummary:
+    """Return a McpUsageSummary for the requested period.
+
+    period: one of "today", "week", "month", "all".
+    path:   override telemetry source (used by tests; defaults to DEFAULT_PATH).
+    """
+    if period not in _VALID_PERIODS:
+        raise ValueError(f"invalid period: {period!r}")
+    src = path or DEFAULT_PATH
+    cutoff = _period_cutoff(period)
+    entries, corrupt = _read_jsonl(src, cutoff)
+    return _build_summary(period, entries, corrupt)
+
+
+def _period_cutoff(period: str, now: datetime | None = None) -> datetime | None:
+    ref = now or datetime.now(timezone.utc)
+    if period == "today":
+        return ref.replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "week":
+        return ref - timedelta(days=7)
+    if period == "month":
+        return ref - timedelta(days=30)
+    return None
+
+
+def _read_jsonl(src: Path, cutoff: datetime | None) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    # Line-stream to keep memory O(1) — this file grows on every MCP call.
+    try:
+        with src.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    corrupt += 1
+                    continue
+                if not isinstance(entry, dict):
+                    corrupt += 1
+                    continue
+                if cutoff is not None and not _within_cutoff(entry, cutoff):
+                    continue
+                entries.append(entry)
+    except OSError:
+        return entries, corrupt
+    return entries, corrupt
+
+
+def _within_cutoff(entry: dict[str, Any], cutoff: datetime) -> bool:
+    ts = _parse_ts(entry.get("ts"))
+    if ts is None:
+        return False
+    return ts >= cutoff
+
+
+def _parse_ts(raw: Any) -> datetime | None:
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _build_summary(
+    period: str,
+    entries: Iterable[dict[str, Any]],
+    corrupt: int,
+) -> McpUsageSummary:
+    total = 0
+    servers: Counter[str] = Counter()
+    tools: Counter[str] = Counter()
+    for entry in entries:
+        server = str(entry.get("server", ""))
+        tool = str(entry.get("tool", ""))
+        if not server:
+            continue
+        total += 1
+        servers[server] += 1
+        if tool:
+            tools[f"{server}/{tool}"] += 1
+    return McpUsageSummary(
+        period=period,
+        total_calls=total,
+        unique_servers=len(servers),
+        top_servers=servers.most_common(_TOP_SERVERS),
+        top_tools=tools.most_common(_TOP_TOOLS),
+        corrupt_line_count=corrupt,
+    )

package/core/runtime/mcp_telemetry_cli.py

@@ -0,0 +1,62 @@
+"""CLI entry for the MCP usage telemetry summarizer.
+
+Invoked as ``python -m core.runtime.mcp_telemetry_cli <period>`` where
+``<period>`` is one of: today, week, month, all (default: today).
+
+Output is plain markdown so it renders cleanly in both the terminal and
+the ``/arka status`` skill which concatenates it into its report.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.runtime.mcp_telemetry import McpUsageSummary, summarise
+
+
+def _sanitize_md(value: str) -> str:
+    """Strip markdown-breaking characters before rendering JSONL strings.
+
+    Telemetry is local-writer-only, but a malformed server/tool value
+    (newline, backtick) can still distort the markdown if /arka status
+    pipes the output to a UI.
+    """
+    return value.replace("\n", " ").replace("\r", " ").replace("`", "").strip()
+
+
+def _render(summary: McpUsageSummary) -> str:
+    lines = [
+        f"# MCP usage — {summary.period}",
+        "",
+        f"- Calls: **{summary.total_calls}**",
+        f"- Servers in use: **{summary.unique_servers}**",
+    ]
+    if summary.top_servers:
+        lines += ["", "## Top servers"]
+        for server, count in summary.top_servers:
+            lines.append(f"- `{_sanitize_md(server)}` — {count}")
+    if summary.top_tools:
+        lines += ["", "## Top tools"]
+        for tool, count in summary.top_tools:
+            lines.append(f"- `{_sanitize_md(tool)}` — {count}")
+    if summary.corrupt_line_count:
+        lines += ["", f"_Skipped {summary.corrupt_line_count} corrupt line(s)._"]
+    if summary.total_calls == 0:
+        lines += ["", "_No MCP calls recorded for this period._"]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    period = args[0] if args else "today"
+    try:
+        summary = summarise(period)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(_render(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/synapse/engine.py

@@ -181,7 +181,6 @@ def create_default_engine(
         BranchLayer,
         CommandHintsLayer,
         QualityGateLayer,
-        TimeLayer,
         KnowledgeRetrievalLayer,
         KBContextLayer,
         ForgeContextLayer,
@@ -221,7 +220,10 @@ def create_default_engine(
     engine.register_layer(BranchLayer())
     engine.register_layer(CommandHintsLayer(commands=commands))
     engine.register_layer(QualityGateLayer())
-    engine.register_layer(TimeLayer())
+    # L7 TimeLayer removed (prompt-surface P0 2026-07-08): the time-of-day tag
+    # had no consumer rule and invalidated the prompt cache at every
+    # 5h/12h/18h boundary — same rationale as the session-start hook's
+    # time-of-day removal.
     engine.register_layer(ForgeContextLayer())
     # L7.5 (PR4 v3.75.0) — Pattern Library injection. Surfaces prior
     # `PatternCard`s when the user prompt has matching keywords, so

package/core/synapse/layers.py

@@ -496,55 +496,6 @@ class QualityGateLayer(Layer):
         )
 
 
-# --- L7: Time Signal ---
-
-
-class TimeLayer(Layer):
-    """L7: Time-of-day signal for context-aware behavior."""
-
-    @property
-    def id(self) -> str:
-        return "L7"
-
-    @property
-    def name(self) -> str:
-        return "Time"
-
-    @property
-    def cache_ttl(self) -> int:
-        # 1 hour — time-of-day period only changes at 5/12/18 boundaries.
-        # Cache bucket drift of up to 1h is acceptable for a low-signal tag
-        # and dramatically improves prompt-cache hit rate.
-        return 3600
-
-    @property
-    def priority(self) -> int:
-        return 70
-
-    def compute(self, ctx: PromptContext) -> LayerResult:
-        start = time.time()
-        import datetime
-
-        hour = datetime.datetime.now().hour
-        if 5 <= hour < 12:
-            period = "morning"
-        elif 12 <= hour < 18:
-            period = "afternoon"
-        else:
-            period = "evening"
-
-        tag = f"[time:{period}]"
-        ms = int((time.time() - start) * 1000)
-        return LayerResult(
-            layer_id=self.id,
-            tag=tag,
-            content=period,
-            tokens_est=1,
-            compute_ms=ms,
-            cached=False,
-        )
-
-
 # --- L3.5: Knowledge Retrieval ---
 
 

package/dashboard/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "nuxt-ui-template-dashboard",
+  "name": "arkaos-dashboard",
   "private": true,
   "type": "module",
   "scripts": {

package/departments/brand/SKILL.md

@@ -8,17 +8,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Brand & Design Department — ArkaOS v2
@@ -52,7 +44,7 @@ does not replace the vault.
 | **Isabel** | Visual Designer | 2 | I+S | Colors, logos, mockups, visual assets |
 | **Sofia D.** | UX/UI Designer | 2 | C+I | Wireframes, usability, accessibility |
 
-## Brand Creation Method (NON-NEGOTIABLE: strategy before visuals)
+## Brand Creation Method (MUST: strategy before visuals)
 
 ```
 Level 1 — FOUNDATION (Mateus leads)
@@ -103,7 +95,7 @@ Level 4 — DELIVERY (Valentina leads)
 When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
 
 - Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
-- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Quality Gate dispatch model: constitution `quality_gate.model_policy` (single source — best-available via Model Fabric; veto is model-independent)
 - Default to `sonnet` if the agent YAML has no `model` field
 - Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
 

package/departments/brand/skills/archetype-finder/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Archetype Finder — `/brand archetype <brand>`

package/departments/brand/skills/colors/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Colors — `/brand colors <mood>`

package/departments/brand/skills/design-review/SKILL.md

@@ -1,9 +1,17 @@
 ---
 name: brand/design-review
 description: >
-  Open a design tool (Figma, Sketch, Canva desktop) and compare live designs
-  against brand guidelines. Screenshot and annotate differences.
-  Requires Computer Use (/mcp → computer-use).
+  Visual review of live designs against brand guidelines — opens Figma,
+  Sketch, or Canva desktop via Computer Use, screenshots each artboard, and
+  annotates palette, typography, spacing, and logo deviations. Requires
+  Computer Use (/mcp -> computer-use). TRIGGER: "/brand design-review",
+  "design review", "visual review", "revê o design", "compara com o
+  brandbook", "está on-brand?", "visual QA", "UI review" of mockups or
+  screenshots, design file paths (*.fig, *.sketch, Canva links). SKIP:
+  reviewing the CODE behind a UI (components, CSS, diffs, PRs) ->
+  dev/code-review wins; SOLID/style sweep of frontend code ->
+  dev/clean-code-review wins; trying to break flows or find abuse vectors ->
+  dev/adversarial-review wins.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/brand/skills/design-system/SKILL.md

@@ -7,17 +7,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Design System — `/brand design-system`

package/departments/brand/skills/identity-system/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Identity System — `/brand identity <name>`

package/departments/brand/skills/logo-brief/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Logo — `/brand logo <brief>`

package/departments/brand/skills/mockup-generate/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Mockup — `/brand mockup <type>`

package/departments/brand/skills/naming-evaluate/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Brand Naming — `/brand naming <project>`

package/departments/brand/skills/positioning-statement/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Positioning Statement — `/brand positioning <name>`

package/departments/brand/skills/primal-audit/SKILL.md

@@ -7,17 +7,9 @@ allowed-tools: [Read, Write, Edit, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Primal Brand Audit — `/brand audit`

package/departments/brand/skills/ux-audit/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Ux Audit — `/brand ux-audit <url>`

package/departments/brand/skills/voice-guide/SKILL.md

@@ -6,17 +6,9 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
 <!-- arka:kb-first-prefix begin -->
-## KB-First Research (non-negotiable)
-
-Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
-
-1. Call `mcp__obsidian__search_notes` on the query first.
-2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
-3. Only after (1) and (2) may external tools run.
-
-The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
-treat them as your default source. External research supplements, it
-does not replace the vault.
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
 <!-- arka:kb-first-prefix end -->
 
 # Voice Guide — `/brand voice <context>`