From c2d36977b9bde51b0c615d8f06a9f4d9f365d423 Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Sat, 5 Sep 2026 00:19:03 +0800
Subject: [PATCH 1/2] docs(architecture): audit Tools and capabilities group
 against implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audit the three Tools and capabilities documents from the #3522
documentation audit against the current implementation (22715e84f).

mcp-runtime-architecture-draft.zh-CN.md: the load-bearing contracts
resolve as written (tool naming mcp__{server}__{tool} with the 64-char
hash suffix, categoryHint network_send default, the 30s/60s/15s/600s
timeout matrix, the stdio env allowlist, the four package boundaries).
The PermissionEngine mention is the one the tracking issue already
verified as correct. No drift; added the standard frontmatter.

skill-catalog-policy.md: every named symbol resolves, and the budget
constants match the code exactly (MAX_SKILLS_PROMPT_CHARS 18000,
MIN/MAX_SKILLS_PROMPT_TOKENS 4_000/8_000, SKILLS_PROMPT_CONTEXT_RATIO
0.02). No drift; added the standard frontmatter.

web-search-provider-capability.md: one drift fixed — the execution
surfaces table still listed the retired Headless Harbor surface and
its MAKA_WEB_SEARCH_ENABLED opt-in, which #2605 removed on 2026-08-11
when Headless became the minimal Eval kernel; the row now records the
retirement instead of presenting the surface as current. The rest
verifies (routeWebSearchTools, model-web-search.ts, providerExecuted
replay, the DeepSeek V4 Flash anthropic-compatible rule). Added the
standard frontmatter.

Refs #3522

Generated-by: GLM-5.3-Flash (ZCode)
---
 .../mcp-runtime-architecture-draft.zh-CN.md   | 12 +++++++++++
 docs/skill-catalog-policy.md                  | 12 +++++++++++
 docs/web-search-provider-capability.md        | 21 ++++++++++++++++---
 3 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/docs/architecture/mcp-runtime-architecture-draft.zh-CN.md b/docs/architecture/mcp-runtime-architecture-draft.zh-CN.md
index 14532fc9e5..166fd0126b 100644
--- a/docs/architecture/mcp-runtime-architecture-draft.zh-CN.md
+++ b/docs/architecture/mcp-runtime-architecture-draft.zh-CN.md
@@ -1,3 +1,15 @@
+---
+doc_id: architecture.mcp-runtime-architecture-draft
+title: "Maka MCP runtime architecture"
+language: zh-CN
+source_language: zh-CN
+implementation_status: current
+document_status: current
+translation_status: source-only
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/skill-catalog-policy.md b/docs/skill-catalog-policy.md
index c312f64c1e..a6a9314893 100644
--- a/docs/skill-catalog-policy.md
+++ b/docs/skill-catalog-policy.md
@@ -1,3 +1,15 @@
+---
+doc_id: skill-catalog-policy
+title: "Skill catalog policy"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: source-only
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/web-search-provider-capability.md b/docs/web-search-provider-capability.md
index 9ddb26df06..811ac30736 100644
--- a/docs/web-search-provider-capability.md
+++ b/docs/web-search-provider-capability.md
@@ -1,3 +1,15 @@
+---
+doc_id: web-search-provider-capability
+title: "Provider-hosted web search capability"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: source-only
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -71,10 +83,13 @@ All production `AiSdkBackend` composition roots use the same
 | Desktop | persisted `webSearch.enabled/defaultProvider` settings | May add provider-native `WebSearch` |
 | CLI / TUI / `maka run` | the same persisted settings | May add provider-native `WebSearch` |
 | Runtime Host | runtime-policy web-search settings | May add provider-native `WebSearch` |
-| Headless Harbor | explicit `MAKA_WEB_SEARCH_ENABLED=true` | May add provider-native `WebSearch` |
 
-Headless remains opt-in because silently enabling network search would change
-benchmark semantics and historical baselines. Merely speaking Anthropic
+The former Headless Harbor surface was retired by #2605 (2026-08-11, replaced
+by the minimal Eval kernel); its `MAKA_WEB_SEARCH_ENABLED=true` opt-in no
+longer exists. Its opt-in rationale — silently enabling network search would
+change benchmark semantics and historical baselines — now applies to eval
+subjects, which must enable provider-native search explicitly in their own
+configuration. Merely speaking Anthropic
 Messages is not enough to infer hosted-search support; Maka uses explicit model
 metadata or narrow model-id rules, including DeepSeek V4 Flash on an
 `anthropic-compatible` connection.

From 2f25ebf88b96875564e86f2ccf4a224264ae12b2 Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Sat, 5 Sep 2026 21:00:14 +0800
Subject: [PATCH 2/2] docs: state the current Eval no-web contract in the
 search capability doc

Review (hqhq1025) flagged the Eval paragraph for documenting an enablement
path that does not exist: current benchmark subjects cannot turn on
provider-native search in their own configuration. packages/eval/README.md
removes WebSearch, WebFetch, and FetchURL from every subject and the metering
proxy structurally strips named and native web tools from external-harness
requests. Reword the retired Headless Harbor opt-in rationale as the reason
Eval subjects have web search removed outright for parity, keeping the
enablement story historical.

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/web-search-provider-capability.md | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/web-search-provider-capability.md b/docs/web-search-provider-capability.md
index 811ac30736..289bde170f 100644
--- a/docs/web-search-provider-capability.md
+++ b/docs/web-search-provider-capability.md
@@ -88,11 +88,14 @@ The former Headless Harbor surface was retired by #2605 (2026-08-11, replaced
 by the minimal Eval kernel); its `MAKA_WEB_SEARCH_ENABLED=true` opt-in no
 longer exists. Its opt-in rationale — silently enabling network search would
 change benchmark semantics and historical baselines — now applies to eval
-subjects, which must enable provider-native search explicitly in their own
-configuration. Merely speaking Anthropic
-Messages is not enough to infer hosted-search support; Maka uses explicit model
-metadata or narrow model-id rules, including DeepSeek V4 Flash on an
-`anthropic-compatible` connection.
+subjects inverted: current benchmark subjects have no enablement path at all.
+Every subject removes `WebSearch`, `WebFetch`, and `FetchURL` from the
+provider-visible tool list, and the Eval metering proxy structurally strips
+named and provider-native web tools from external-harness requests, so
+results stay comparable across providers and baselines. Merely speaking
+Anthropic Messages is not enough to infer hosted-search support; Maka uses
+explicit model metadata or narrow model-id rules, including DeepSeek V4 Flash
+on an `anthropic-compatible` connection.
 
 An explicit `BackendFactoryContext.tools` list is a hard ceiling. Root surfaces
 may add native search, but scoped child agents do not gain it unless their