npm - misakanet - Versions diffs - 2.44.1 → 2.45.0 - Mend

misakanet 2.44.1 → 2.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -8,13 +8,18 @@
 mcp-name: io.github.Ikalus1988/misakanet
-> **Stop debugging the same error twice.** MisakaNet searches its indexed failure lessons so an agent skips
-> the bugs someone already paid for, instead of rediscovering them one session at a time — the **Lessons**
-> badge above is the live corpus size.
+> **The same failure, paid for twice.**
 >
-> Agent-native interfaces: [MCP server](https://misakanet.org/mcp) (8 tools), WebMCP (browser
-> `navigator.modelContext`), `llms.txt` / `llms-full.txt`, and A2A discovery through
-> `.well-known/agent-card.json`.
+> A `pip install` times out behind a corporate proxy. An agent finds the fix. Days later the same
+> timeout appears on another machine, under another model — and is debugged from scratch, because the
+> fix was never written down anywhere the next agent looks.
+>
+> MisakaNet is that place: a git-backed **failure memory**. Every lesson is a Markdown file in this
+> repository — graded by evidence, reviewed like code, retrieved by an agent instead of guessed at.
+> You fail once; the next agent does not.
+Agent-native interfaces: [MCP server](https://misakanet.org/mcp) (8 tools), WebMCP, `llms.txt`,
+A2A discovery via `.well-known/agent-card.json`.
 <p align="center">
   <img src="promotional/misaka-compare.jpg" width="720" alt="MisakaNet — Before: 30+ min manual debugging vs After: 0.02s with MCP"/>
@@ -23,7 +28,7 @@ mcp-name: io.github.Ikalus1988/misakanet
 <p align="center">
   <em>Core</em>
   &nbsp;&nbsp;
-  <a href="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-quality-gate.yml"><img src="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-quality-gate.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-checks.yml"><img src="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-checks.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/Ikalus1988/MisakaNet/tree/main/lessons"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/lessons.json" alt="Lessons"></a>
   <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/scripts/mcp_server.py"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/tools.json" alt="MCP Tools"></a>
   <a href="https://misakanet.org/api/search-index"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/retrieval.json" alt="Retrieval backend (today)"></a>
@@ -38,161 +43,118 @@ mcp-name: io.github.Ikalus1988/misakanet
   <a href="https://pypi.org/project/misakanet/"><img src="https://img.shields.io/pypi/v/misakanet" alt="PyPI"></a>
   <a href="https://www.npmjs.com/package/misakanet"><img src="https://img.shields.io/npm/v/misakanet" alt="npm"></a>
   <a href="https://github.com/marketplace/actions/misakanet-intake-bot"><img src="https://img.shields.io/badge/Marketplace-MisakaNet%20Intake%20Bot-blue?logo=github" alt="GitHub Marketplace"></a>
-  <a href="https://dsh-plugin.org/plugins/ikalus1988/misakanet"><img src="https://dsh-plugin.org/badges/listed.svg" alt="Listed on dsh-plugin.org"></a>
-  <a href="https://dsh.directory/plugins/ikalus1988/misakanet"><img src="https://dsh.directory/badges/listed.svg" alt="Listed on DSH Directory"></a>
-  <a href="https://www.dsh.so/artifact/misakanet/"><img src="https://www.dsh.so/badge/install/misakanet.svg" alt="dsh.so install"></a>
 </p>
 <p align="center">
   <em>Ecosystem</em>
   &nbsp;&nbsp;
-  <a href="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/score"><img src="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/badges/score.svg" alt="Glama score"></a>
-  <a href="https://glama.ai/mcp/connectors/org.misakanet/misaka-net"><img src="https://glama.ai/mcp/connectors/org.misakanet/misaka-net/badges/score.svg" alt="MisakaNet MCP connector – tool definition quality and endpoint health on Glama"></a>
-  <a href="https://mcptoplist.com/server/io.github.Ikalus1988%2Fmisakanet"><img src="https://mcptoplist.com/badge/io.github.Ikalus1988%2Fmisakanet.svg" alt="MCP Toplist"></a>
-  <!-- Smithery badge uses a shields.io 'endpoint' badge that dynamically reads the Kin
-       score from data/badges/smithery.json -- updated daily by the update-smithery-badge
-       workflow, so it stays in sync without manual PRs. -->
-  <a href="https://smithery.ai/servers/misakanet/misakanet"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/refs/heads/data/badges/smithery.json" alt="Smithery"></a>
-  <!-- HOL badge: the link still points at hol.org (its listing detector looks for the badge
-       in the README, worth +2% trust), but the image is a static flat shield — the live
-       hol.org/api/... endpoint is slow/unstable through shields.io and rendered as
-       "inaccessible" / a mismatched for-the-badge style. -->
-  <a href="https://hol.org/registry/plugins/Ikalus1988%2FMisakaNet"><img src="https://img.shields.io/badge/HOL%20Registry-listed-5599FE?style=flat" alt="MisakaNet on HOL Registry"></a>
-  <a href="https://github.com/Ikalus1988/MisakaNet/tree/main/docs/benchmarks"><img src="https://img.shields.io/badge/Benchmark-Weekly%20Workers%20AI-blue" alt="Benchmark"></a>
+  <a href="https://glama.ai/mcp/connectors/org.misakanet/misaka-net"><img src="https://glama.ai/mcp/connectors/org.misakanet/misaka-net/badges/score.svg" alt="MisakaNet MCP connector on Glama"></a>
+  <a href="https://mcptoplist.com/server/io.github.Ikalus1988%2Fmisakanet"><img src="https://img.shields.io/badge/MCP-Toplist-blue" alt="MCP Toplist"></a>
 </p>
 ---
 ## Install (30 seconds)
+The point of an install is a first **successful search**, not the install. None of these needs an
+account or a token.
 | Your host | Command |
 |---|---|
-| **DeepSeek Harness** | `dsh plugin --profile web add misakanet` — or type `misakanet` in the host's **Add plugin** dialog |
+| **DeepSeek Harness** | `dsh plugin --profile web add misakanet` — or type `misakanet` in **Add plugin** |
 | **Claude Code** | `/plugin marketplace add Ikalus1988/MisakaNet` then `/plugin install misakanet@misakanet` |
-| **Codex, Cursor, Gemini CLI, Copilot CLI, OpenCode, …** | `npx @misaka-net/misakanet-setup` — writes the MCP row into each host's own config |
-| **Any other MCP client** | point it at `https://misakanet.org/mcp` — the endpoint is public and reads are anonymous |
+| Installer-managed | Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro |
+| **Any other MCP client** | point it at `https://misakanet.org/mcp` — public endpoint, anonymous reads |
 | **Your own code** | `pip install misakanet-core` (library) · `pip install misakanet` (stdio server) |
-<p align="center">
-  <img src="docs/assets/dsh-plugin-add.png" width="760" alt="DeepSeek Harness plugin page: (1) the plugin icon in the sidebar, (2) the 添加插件 (Add plugin) button, (3) the Add-plugin dialog with the package name misakanet typed in"/>
-</p>
-<p align="center"><em>DeepSeek Harness: sidebar <b>插件</b> (1) → <b>添加插件</b> (2) → type <code>misakanet</code> (3) → <b>安装</b>.<br/>The dialog takes the same package name the CLI command above uses (its own hint: a package name, a GitHub URL, or a local path).</em></p>
+The installer-managed row is what `npx @misaka-net/misakanet-setup` writes into each host's config.
 Updates: `dsh plugin --profile web update misakanet@latest`.
-Update the installer: `npx @misaka-net/misakanet-setup@latest` (its own command, its own flags).
-No account, no token, no Python needed for the plugin path: the npm bundle mounts the hosted endpoint.
-Declared hosts and what was measured: [compatibility](docs/compatibility.md). Every channel, the
-prerequisites, and the two-package trap that costs people an install: [How to use it](#how-to-use-it).
-## What the DeepSeek Harness plugin adds
+Installer updates: `npx @misaka-net/misakanet-setup@latest`.
+Full prerequisites and the two-package trap: [How to use it](#how-to-use-it).
-Version 2.40.0 ships the browser half, and 2.41.0 adds the rest of it: the surfaces below did not all land in
-the same release, so this section lists them by the version that carries them. It is not a dialog: it puts
-MisakaNet where the session already is.
+## Your first five minutes
-**In 2.40.0 — published.** These six seats are what `npm view misakanet version` gives you today.
+**1. Ask it something you have actually broken.** No client installed? This `curl` is the whole interface:
-| Where | What you get |
-| --- | --- |
-| **Left column** | A permanent `MisakaNet` entry directly under `Plugins`. It is a shortcut, not the panel: clicking it opens a full page in the main column. Root scope — it does not come and go with a session. |
-| **Conversation tab** | A `MisakaNet` tab beside Chat and Trajectory: what this session asked, what came back, and what you filed, rebuilt from the conversation's own rows. |
-| **Right column** | The same panel as a pane, so it can sit next to the file tree, a terminal, or a document. |
-| **Tool call rows** | Every `misakanet_search` and `misakanet_submit_intake` call gets its own row on the tool card: the query as it was sent, whether a lesson came back, and which lesson is on top, with the raw result one disclosure away. The row reports and never posts — the vote belongs on the answer's action row below. |
-| **Assistant action row** | 👍 / 👎 on the answer that used a lesson. Those two are the only things the page ever sends — counters live in the browser, not on a server. |
-| **Voice** | An off-by-default switch that explains both mechanisms: the cue the server names on the next search, and the local hook a page cannot read. |
-<p align="center">
-  <img src="docs/assets/dsh-client-left-column.png" width="820" alt="DeepSeek Harness: a permanent MisakaNet entry in the left column under Plugins, and the full page it opens"/>
-</p>
-<p align="center">
-  <img src="docs/assets/dsh-client-right-panel.png" width="820" alt="The MisakaNet pane in the right column of a DeepSeek Harness session"/>
-</p>
-**With 2.41.0 — [release PR #2591](https://github.com/Ikalus1988/MisakaNet/pull/2591).** These six surfaces
-are in `main` and ship in 2.41.0; a 2.40.0 install does not have them yet.
+```bash
+curl -sS https://misakanet.org/mcp \
+  -H 'Content-Type: application/json' -H 'Accept: application/json' \
+  -H 'MCP-Protocol-Version: 2025-06-18' -H 'Origin: https://misakanet.org' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
+       "params":{"name":"misakanet_search","arguments":{"query":"database is locked","top":3}}}'
+```
-| Where | What you get |
-| --- | --- |
-| **`/misakanet` in the composer** | Type `/misakanet pip install timeout` and press Enter: the lessons come back in a card inside the composer, with no agent in the loop. The query is the only thing it sends. |
-| **Frame-wide toast** | After a `/misakanet` search comes back with lessons, a card appears over every column with the top hit; dismiss it or click through to the lesson. |
-| **Sidebar foot** | One action beside Settings: copy this session's MisakaNet activity as a summary for an issue or a PR body. |
-| **中文 / English** | Every MisakaNet surface follows the host language: the panel, the `/misakanet` card, the settings row, and the plugin page's own title and description. |
-| **Settings → General** | A MisakaNet preference row: play voice cues in this browser, and how much the surfaces show (compact / full). Both stay in the browser. |
-| **Plugin page** | The MCP row's effective configuration — endpoint, transport, timeout — shown read-only, next to where it is edited (the profile's `cordis.patch.yml`). |
+**2. Read what came back.** A hit returns the lesson, its `evidence_level`, and its path — open the
+file and read the fix before running any command in it. A miss returns `no_match` plus a ready-to-call
+intake: the corpus saying it does not know this one yet.
-Which seats the half occupies and why they are `root` or `session` scope, with the host's own contract text
-quoted: [compatibility](docs/compatibility.md). Running a host of your own and want a check that cannot
-touch your profile: `python3 scripts/install_smoke.py dsh-client --serve`.
+**3. Check the trust signal, not the tone.** `E0`–`E3` say how far a lesson was verified; `E4` is the
+one nobody can write or vote into.
 ## What is MisakaNet?
-**Git-backed failure memory for AI coding agents.** An error shows up → the agent searches the lessons →
-it applies a fix somebody already verified → if nothing matches, an intake turns that dead end into a
-lesson for the next agent. Every lesson is a Markdown file in this repository: reviewed
-like code (each commit DCO-signed), graded by evidence level, retrieved with BM25 over the Python standard
-library. No vector database, no embedding model, no server unless you want one.
+**Git-backed failure memory for AI coding agents.** An error shows up → the agent searches → it
+applies a fix somebody already verified → if nothing matches, the miss becomes an intake, and the
+intake becomes a lesson for the next agent.
+Every lesson is a Markdown file: reviewed like code, graded by evidence, retrieved with BM25 over the
+Python standard library. No vector database, no embedding model, no server unless you want one.
 | | |
 |---|---|
 | **Lessons** | failure-recovery knowledge base, open and auditable under `lessons/` |
 | **Domains** | rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows … |
-| **Evidence levels** | E0 intake → E1 CI → E2 merged PR → E3 maintainer → E4 production reuse |
-Registry listings ([Glama](https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/score),
-[Smithery](https://smithery.ai/servers/misakanet/misakanet), MCP Toplist) proxy the hosted endpoint, which
-serves **indexed failure-recovery lessons** — *indexed*, never "verified": evidence level is what says
-how much a lesson has been proven.
+| **Evidence** | E0 intake → E1 reviewed → E2 reproduced → E3 CI verified → **E4 observed reuse by two or more distinct clients** |
-| MisakaNet is NOT | What it is instead |
-|------------------|-------------------|
-| ❌ A general-purpose memory system | ✅ Failure-recovery knowledge layer |
-| ❌ An Agent runtime or framework | ✅ Searchable lesson database |
-| ❌ A vector database or RAG system | ✅ BM25 keyword search — **stdlib only**, no third-party packages, but a **Python ≥ 3.10 interpreter is still required** |
-| ❌ A cloud service requiring signup | ✅ `git clone` → search locally |
-| ❌ A skill marketplace | ✅ Debugging knowledge from real sessions |
+| It is not | It is |
+|---|---|
+| ❌ a general memory system | ✅ a failure-recovery knowledge layer |
+| ❌ an agent runtime | ✅ a searchable lesson database |
+| ❌ a vector database / RAG stack | ✅ BM25 keyword search, stdlib only (Python ≥ 3.10 still required) |
+| ❌ a skill marketplace | ✅ debugging knowledge from real sessions |
+| ❌ a retrieval benchmark | ✅ a corpus graded by evidence; the benchmark we have is paused |
-### What it can and cannot answer
+### What it answers — and what it does not
-![Four-panel comic: the mascot promises to prevent every AI error; the cats ask about pizza and an oil barrel and it deflates — then a cat shows npm ERESOLVE and it lights up. MisakaNet knows the failures that have been indexed, not general knowledge.](promotional/misakanet-scope-comic.webp)
+![Four-panel comic: an agent asks about a failure, gets an indexed lesson back, or gets "no_match" and a ready-to-call intake form](promotional/misakanet-scope-comic.webp)
-It answers for **the failures it has indexed**, not general knowledge. A query that finds nothing returns
-`no_match` plus a ready-to-call intake — a miss is how a gap gets recorded, so a miss is an answer too.
+MisakaNet answers for the failures it has indexed, and only those. When nothing matches the reply is
+`no_match` plus a ready-to-call `intake` — the corpus saying "not this one yet", not a dead end.
 ### Lesson vs Skill
-A **skill** teaches an agent *how to do something*. A **lesson** records *what went wrong before, and how
-not to fail again*. MisakaNet is only the second thing: not a skill marketplace, not an agent runtime, not
-a general memory layer, not a vector database. → [FAQ](FAQ.md)
-## Benchmark: how much of a lesson does a model reproduce when handed one?
+A **skill** teaches an agent how to do something; a **lesson** records what went wrong before and how
+not to fail again. MisakaNet is only the second thing. → [FAQ](FAQ.md)
-Weekly benchmark (Cloudflare Workers AI). **Read the metric before the numbers** — the scenario in this benchmark is each lesson's own title, the "matching lesson" injected into the `with_lesson` arm is *that same lesson*, and the
-score is `lesson_hit_rate`: **the share of the injected lesson's commands reproduced in the answer**.
-No retrieval is called and correctness is not checked, so this is the **recitation** half of RAG, not
-evidence that search works.
+## Where it is today
-Latest aggregated data: [`docs/benchmarks/latest.json`](docs/benchmarks/latest.json) (2026-09-22, two
-independent runs of ≈500 scenarios each):
+- **The numbers that move are badges**, on purpose: the Lessons badge renders
+  `data/badges/lessons.json`, regenerated by `update-badges.yml`, so it can lag a run but is never a
+  hand-typed total.
+- **The top of the evidence ladder is empty, and this page says so.** `E4` needs an observation —
+  two distinct clients actually retrieving a lesson — and the corpus has none yet
+  ([distribution](docs/trust-semantics.md), regenerated and checked by CI).
+- **Search is BM25, so it matches words, not meaning.** A failure described in vocabulary the corpus
+  has never seen is a miss, and no retriever tuning fixes a corpus gap — which is why a miss returns
+  `no_match` plus an intake instead of an empty page.
+- **Reported gaps arrive faster than they are triaged.** The intake queue is the honest bottleneck.
-| Condition | Run 1 hit rate | Run 2 hit rate | Avg | n (per run) | Actionable |
-|---|---|---|---|---|---|
-| plain (no lesson) | 0.239 | 0.233 | **23.3%** | ≈510 | 82–83% |
-| with_lesson (pasted) | 0.464 | 0.461 | **46.1%** | ≈512 | 76–77% |
+## Benchmark: what it measured, and why it is paused
-**Reproducibility.** Two runs with identical config produce hit rates within 0.3% of each other
-(0.464 vs 0.461 for `with_lesson`; 0.239 vs 0.233 for `plain`), confirming the metric is stable.
+One narrow question: **when you hand a model a lesson, how much of that lesson comes back?** The
+metric is `lesson_hit_rate` — the share of the injected lesson's commands reproduced in the answer.
+Read the setup before the number: the scenario in this benchmark is each lesson's own title, the injected
+lesson is *that same lesson*,
+no retrieval call is made, and correctness is not checked. It measures the **recitation** half of RAG:
+necessary for MisakaNet to help, and **not evidence that search finds anything**.
-**Aggregation.** Each run evaluates every lesson in the corpus as a scenario. The `with_lesson` arm pastes the matching lesson
-into the prompt; `plain` uses no lesson. `actionable` is a boolean per scenario indicating whether the
-model produced a usable answer. Actionable rates are stable across runs (76–77% with lesson, 82–83% plain).
+The run is **paused**. Two independent runs of ≈500 scenarios each on 2026-09-22: **46.1%** with the
+lesson pasted in, **23.3%** without. What remains is the last snapshot plus its dated record —
+[`docs/benchmarks/latest.json`](docs/benchmarks/latest.json).
-**Trend.** Rows below are **generated** by [`scripts/update_readme_benchmark.py`](scripts/update_readme_benchmark.py)
-from [`docs/benchmarks/latest.json`](docs/benchmarks/latest.json) — regenerate them with
-`python3 scripts/update_readme_benchmark.py`. Do not hand-edit: a second source of truth is what made the
-previous copy go stale while the paragraph directly above it explained what the metric does and does not mean.
+The table below is generated by [`scripts/update_readme_benchmark.py`](scripts/update_readme_benchmark.py);
+do not hand-edit it.
 <!-- BEGIN generated: benchmark-trend -->
@@ -221,109 +183,58 @@ with_lesson hit rate (per run date)
 <!-- END generated: benchmark-trend -->
-A model repeats more of a document it was handed, and the weaker the model the bigger the relative
-difference. That is *necessary* for the product to help and it is not sufficient — the claim "search finds the
-right lesson for a failure you described" is measured nowhere yet. Details:
-[`docs/benchmarks/latest.json`](docs/benchmarks/latest.json) · per-run files in
-[`docs/benchmarks/`](docs/benchmarks/) · metric definition: `METRIC_DEFINITION` in
-[`scripts/benchmark_workers_ai.py`](scripts/benchmark_workers_ai.py)
-→ [Full changelog](CHANGELOG.md) · [Release notes](https://github.com/Ikalus1988/MisakaNet/releases)
-**Beware of a single number.** A benchmark is only as good as what it measures, so here is what these mean
-and where this design loses:
+Per-run files: [`docs/benchmarks/`](docs/benchmarks/) · metric definition: `METRIC_DEFINITION` in
+[`scripts/benchmark_workers_ai.py`](scripts/benchmark_workers_ai.py).
-| Metric | What it measures | Why it matters here |
-|---|---|---|
-| Hit rate | share of the **injected** lesson's commands reproduced in the answer — a recitation check; the scenario is that lesson's own title and no retrieval happens | it is the ceiling on usefulness, not the measure of it: a corpus can be recitable and still unfindable |
-| Gain (with − without) | how much more of that lesson appears when it is pasted in | separates "the model can use a lesson" from "the model guessed the same words" — it says nothing about finding the lesson |
-| Actionable | whether the model produced a usable answer at all (boolean per scenario) | a high hit rate on an answer that is not actionable is noise; this tracks whether the model engages with the problem |
-| Cost / latency | tokens and wall-clock per answer | the whole premise is cheaper than re-debugging, so it has to stay cheap |
-**Where it loses on purpose:** BM25 matches words, not meaning. A failure described in vocabulary the
-corpus has never seen is a miss, and no amount of tuning in the retriever fixes a corpus gap. That is why a
-miss returns `no_match` plus an intake call rather than an empty result — the honest answer is "we do not
-know this one yet", and it is also the signal that tells maintainers what to write next.
+## Take part
-## Why failure-memory?
+**1. Report a failure the corpus does not have.** Search first, then call `misakanet_submit_intake` —
+no account, no email, no token, a five-line report is enough. It becomes a tracked issue.
-Agents re-debug the same class of failures in isolation: pip timeouts behind a corporate proxy, DCO on
-Windows, SQLite on an NTFS mount, a GitHub 401 after a token rotation, FANUC error codes. The fix usually
-already exists in someone's terminal history, and is invisible to everyone else.
+**2. Reuse a lesson and leave the trace.** A "this helped" vote is recorded as an `E3` hint, not as
+proof. The proof is quieter: your retrieval is counted, anonymously, as one more distinct client.
-Three deliberate engineering choices, each of which trades something:
+**What you get back: attribution.** A lesson cites the intake that produced it (`source:`,
+`provenance.issue:`), and the pipeline can emit a receipt naming the lesson and its evidence level.
-* **Git is the source of truth.** A lesson is a file, so it diffs, reverts, forks and reviews like code.
-  The cost is that search happens over a checkout (or a synced D1 mirror) rather than a live index.
-* **No third-party packages by default.** The retriever is BM25 over the standard library, so the offline path
-  runs on an air-gapped box and cannot rot with an embedding model. The cost is recall on paraphrases.
-* **Evidence is graded, not asserted.** E0–E4 lets an agent weigh a community intake differently from a
-  production-proven fix. The cost is bookkeeping, and most lessons sit at E0–E2.
+Nothing here is a bounty: this repository pays nothing and promises nothing. Some issues carry
+third-party reward banners added by our own automation; we do not administer them — see
+[Contributing](#contributing).
 ## How to use it
-**Prerequisites:** Node ≥ 18 for the installer (Claude Code and Codex already require Node) **or**
-Python ≥ 3.10 for the library and the stdio server. Nothing else.
-Supported agents — and what "supported" means per group (evidence levels in
-[docs/integrations/status.md](docs/integrations/status.md)):
-| Group | Agents | What you get |
-|---|---|---|
-| Installer-managed | Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro | `npx @misaka-net/misakanet-setup` writes each client's own MCP config, a rules block where the client has one, and (Claude Code only) a turn-counting hook — the five JSON-file clients (Cursor, Gemini CLI, Copilot CLI, OpenCode, Kiro) get the MCP entry alone; `--verify` checks whatever was written |
-| MCP by hand | Cursor · Gemini CLI · Windsurf · OpenCode · Copilot · DeepSeek Harness | the endpoint is standard MCP over HTTP; add the URL in that client's own config. Cursor also has a rules-file mode |
-| Anything else that speaks MCP over HTTP | — | the endpoint is public, reads are anonymous and unmetered |
-Pick one channel — they are independent, and none of them needs an account (the Claude Code row needs a Claude Code version with plugin support):
+Pick one channel; they are independent.
 | I want… | Command | What it touches |
 |---|---|---|
-| my assistant to search the lessons | `npx @misaka-net/misakanet-setup` | writes the MCP endpoint into each assistant's own config; optionally a rules block and a hook |
-| my **Claude Code** assistant to search the lessons, as a plugin | `/plugin marketplace add Ikalus1988/MisakaNet` then `/plugin install misakanet@misakanet` | adds the hosted MCP tools to Claude Code from this repository — no installer, no local process |
-| to call the endpoint myself | the `curl` below | nothing to install |
+| my assistant to search the lessons | `npx @misaka-net/misakanet-setup` | writes the MCP endpoint into each assistant's config; optionally a rules block and a hook |
+| **Claude Code**, as a plugin | `/plugin marketplace add Ikalus1988/MisakaNet` then `/plugin install misakanet@misakanet` | the hosted MCP tools, no installer, no local process |
+| **DeepSeek Harness** | `dsh plugin --profile web add misakanet` | `mcp__misakanet__*` tools plus the session panel |
+| to call the endpoint myself | the `curl` in [Your first five minutes](#your-first-five-minutes) | nothing |
 | the library in my own code | `pip install misakanet-core` | nothing |
-**The two-package trap** (this one cost a real install failure, #1849):
+**The two-package trap** (it cost a real install failure, #1849):
 | Looks like | Actually is | Use it for |
 |---|---|---|
 | `@misaka-net/misakanet-setup` (npm) | the **installer** — has `bin`, no plugin entry | teaching your assistant to search |
-| `misakanet` (npm) | the **DSH / Codex plugin** (`index.js`, `SKILL.md`) | `dsh plugin --profile web add misakanet` |
-| this repository (git) | also a **Claude Code plugin marketplace** (`.claude-plugin/`) | `/plugin marketplace add Ikalus1988/MisakaNet` — the Claude channel is repo-based on purpose: a marketplace resolves the plugin from the repository, so the npm bundle stays the DSH/Codex artifact |
-| `misakanet` (PyPI) | ships the stdio **MCP server** | `python3 -m misakanet.server` |
-| `misakanet-core` (PyPI) | the **library** (stdlib-only BM25 — Python ≥ 3.10 required, no third-party packages) | `from misakanet.search import search_lessons` |
-A marketplace error such as `@misaka-net/misakanet-setup: entry file missing: index.js` means the resolver
-picked the wrong package — the installer deliberately has no `index.js`.
-**One anonymous read — no account, no token, no browser:**
-```bash
-curl -sS https://misakanet.org/mcp \
-  -H 'Content-Type: application/json' -H 'Accept: application/json' \
-  -H 'MCP-Protocol-Version: 2025-06-18' -H 'Origin: https://misakanet.org' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
-       "params":{"name":"misakanet_search","arguments":{"query":"database is locked","top":3}}}'
-```
+| `misakanet` (npm) | the **DSH / Codex plugin** | `dsh plugin --profile web add misakanet` |
+| this repository (git) | also a **Claude Code plugin marketplace** | `/plugin marketplace add Ikalus1988/MisakaNet` |
+| `misakanet` (PyPI) | the stdio **MCP server** | `python3 -m misakanet.server` |
+| `misakanet-core` (PyPI) | the **library** (stdlib-only BM25) | `from misakanet.search import search_lessons` |
-Reads are unlimited and anonymous — the only limit is a per-address burst window, which is a speed limit,
-not a quota. **Registration is for writing**, not for reading: it unlocks `misakanet_write_lesson` and
-`misakanet_preflight` and returns a token valid ~30 days
+**Reads are anonymous and unlimited** (a per-address burst window is a speed limit, not a quota).
+**Registration is for writing**: it unlocks `misakanet_write_lesson` and `misakanet_preflight`
 ([why](AGENTS.md#33-注册与配额)).
-Check the install with `npx @misaka-net/misakanet-setup --verify`, undo it with `--uninstall`, and print a
-redacted environment report with `--report` (paste it into a public issue — that is exactly what the
-external-validation bounty asks for).
-→ [Quickstart](docs/quickstart.md) · [Install guide](https://misakanet.org/install/) ·
-[MCP docs](docs/mcp.md) · [what the installer writes](integrations/agent-autostart/README.md) ·
-[WebMCP setup](docs/cloudflare-worker.md)
+Verify an install with `npx @misaka-net/misakanet-setup --verify`; undo it with `--uninstall`.
+Prerequisites: Node ≥ 18 for the installer, Python ≥ 3.10 for the library and stdio server.
 ### Use it as a GitHub Action
-The same corpus, wired to your CI: when a workflow fails, the action searches the lessons, comments
-the closest match on the pull request, and (optionally) reports the new error so someone turns it
-into a lesson. Published on [GitHub Marketplace](https://github.com/marketplace/actions/misakanet-intake-bot).
+When a workflow fails, the action searches the lessons and comments the closest match on the pull
+request (optionally reporting the new error). Published on
+[GitHub Marketplace](https://github.com/marketplace/actions/misakanet-intake-bot).
 ```yaml
 on:
@@ -345,107 +256,61 @@ jobs:
           source: ${{ github.repository }}
 ```
-→ [inputs and outputs](docs/agents/external-usage.md) · [why `actions: read` is not optional](docs/agents/external-usage.md)
+→ [inputs and outputs](docs/agents/external-usage.md)
 ## Documentation
-**Choose your journey** — MisakaNet is useful in different ways depending on what you are trying to do:
-| I am... | Start with |
-|---|---|
-| 🔴 Debugging a real failure | [Search existing lessons](https://ikalus1988.github.io/MisakaNet/search/) before retrying |
-| 🤖 Building an AI agent / tool | Use lessons as [failure-memory](docs/mcp-quickstart.md) for your workflow |
-| 🧪 Using DeepSeek Harness | `dsh plugin --profile web add misakanet`, then [what it registers](docs/integration/deepseek-harness.md) — skill + `mcp__misakanet__*` tools, no local Python |
-| 🔧 Contributing a fix | Read [CONTRIBUTING.md](CONTRIBUTING.md) for code style + PR checklist, check [related lessons](https://ikalus1988.github.io/MisakaNet/search/), then open a small PR |
-| 📝 Sharing a failure case | Submit a [5-line failure note](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — no polished PR required |
-| 📊 Evaluating agent learning | Run the [benchmarks](scripts/retrieval_noisebench.py) and compare reuse behavior |
-| 💬 Reporting friction | [MCP intake](docs/integrations/mcp-remote.md) or [journey report #510](https://github.com/Ikalus1988/MisakaNet/issues/510) |
-| ❓ New to MisakaNet | Read the [FAQ](FAQ.md) for installation, MCP pairing, troubleshooting, and contribution answers |
-> 👉 **New here?** [Search failure lessons →](https://ikalus1988.github.io/MisakaNet/search/)
->
-> No GitHub account? Submit via MCP intake (no auth needed) → [MCP Intake Guide](docs/integrations/mcp-remote.md)
->
-> Understanding the system → [Label system](docs/label-system.md) · [Troubleshooting](docs/troubleshooting.md)
-**The rest of the map:**
 | Topic | Where |
 |---|---|
-| Open the network in a browser | <https://misakanet.org/> · <https://ikalus1988.github.io/MisakaNet/search/> |
 | Install, verify, uninstall | [docs/quickstart.md](docs/quickstart.md) · <https://misakanet.org/install/> |
-| MCP: protocol, tool reference, transports | [docs/mcp.md](docs/mcp.md) · [API.md](API.md) |
+| MCP: protocol, tools, transports | [docs/mcp.md](docs/mcp.md) · [API.md](API.md) |
 | CLI | [docs/cli-reference.md](docs/cli-reference.md) · `python3 search_knowledge.py "…"` |
-| Architecture and the three paths | [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md) |
-| Submitting an intake (for agents and humans) | [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md) |
-| What the labels mean | [docs/label-system.md](docs/label-system.md) |
-| Troubleshooting (error scene index) | [docs/troubleshooting.md](docs/troubleshooting.md) |
-| Known limitations, stated plainly | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) |
-| Benchmarks | [docs/benchmarks/](docs/benchmarks/) · [docs/lesson-reuse-benchmark.md](docs/lesson-reuse-benchmark.md) |
-| Competitive landscape | [docs/competitive-analysis.md](docs/competitive-analysis.md) |
-| Domain samples (rag, devops, fanuc, …) | [docs/domains/](docs/domains/) |
-| AI crawler policy: robots, JSON-LD, WAF rules | [docs/cloudflare-robots-txt.md](docs/cloudflare-robots-txt.md) · [docs/json-ld-schema.md](docs/json-ld-schema.md) · [docs/cloudflare-waf-rules.md](docs/cloudflare-waf-rules.md) |
-| Roadmap | [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) |
+| Architecture | [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md) |
+| Contributing a fix | [CONTRIBUTING.md](CONTRIBUTING.md) · [label system](docs/label-system.md) |
+| Submitting an intake | [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md) · [mcp-remote](docs/integrations/mcp-remote.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Known limitations | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) |
+| Benchmarks | [docs/benchmarks/](docs/benchmarks/) |
+| Roadmap / changelog | [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) |
+| Competitors, domains, crawler policy | [competitive](docs/competitive-analysis.md) · [domains](docs/domains/) · [robots](docs/cloudflare-robots-txt.md) |
 ## Contributing
-> **Zero bounty. Maximum rigor. Merge earns credit.** Every merged PR proves your agent can survive
-> real-world CI gating.
->
-> "Zero bounty" is a statement about *this repository*: MisakaNet pays nothing and promises nothing.
-> It is not a statement about the issue you are looking at. Some issues carry an Opire banner
-> advertising a third-party reward, added automatically by our own
-> [`scripts/question_autopilot.py`](scripts/question_autopilot.py) — Opire is not mentioned anywhere
-> in `CONTRIBUTING.md` and we do not administer those payouts. **Verify any reward offer independently
-> before you plan work around it.** The only thing this repository has ever honoured is a merged PR.
-> ([#2903](https://github.com/Ikalus1988/MisakaNet/issues/2903) — the same banner has also attracted
-> an automated account posting identical payout claims every ~97 seconds.)
-1. Check the checkout works: `python3 scripts/misakanet_cli.py smoke`
-2. Search before writing: `python3 search_knowledge.py "your error here"`
-3. Found nothing? **[Share your failure lesson →](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml)**
-   — a five-line note is enough, no polished PR required. Two places say what is missing, and they measure
-   different things: the [demand board](workers/README.md#insights-endpoints-issue-591) aggregates anonymous
-   *search* misses (`/api/insights/unsolved-map`; measured 2026-09-25 it held **one** signal in 30 days,
-   because the intake path does not feed it — [#2224](https://github.com/Ikalus1988/MisakaNet/issues/2224)),
-   and the [open intake issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3Aintake)
-   are where the real gaps currently arrive.
-→ [CONTRIBUTING.md](CONTRIBUTING.md) · [good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ·
-[active competitions](https://github.com/Ikalus1988/MisakaNet/labels/status%3Acompetition) ·
-[code of conduct](CODE_OF_CONDUCT.md)
+> **Zero bounty. Maximum rigor. Merge earns credit.**
-## Security
+"Zero bounty" is a statement about *this repository*: MisakaNet pays nothing and promises nothing. It
+is not a statement about the issue you are looking at. Some issues carry an **Opire** banner
+advertising a third-party reward, added automatically by our own
+[`scripts/question_autopilot.py`](scripts/question_autopilot.py) — we do not administer those payouts,
+and Opire is not mentioned in `CONTRIBUTING.md`. **Verify any reward offer independently** before you
+plan work around it. The only thing this repository has ever honoured is a merged PR.
+([#2903](https://github.com/Ikalus1988/MisakaNet/issues/2903))
-⚠️ **Always sandbox your Agent before executing retrieved commands.** Lessons are community-contributed — review before run.
+1. Check the checkout: `python3 scripts/misakanet_cli.py smoke`
+2. Search before writing: `python3 search_knowledge.py "your error here"`
+3. Found nothing? [Share your failure lesson](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — five lines is enough
-CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick injection). See [SECURITY.md](SECURITY.md).
+→ [CONTRIBUTING.md](CONTRIBUTING.md) · [good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [code of conduct](CODE_OF_CONDUCT.md)
-See [LIMITATIONS.md](docs/LIMITATIONS.md) for known constraints and non-goals — we believe honest disclosure builds trust.
+## Security
-## Troubleshooting
+⚠️ **Sandbox your agent before executing retrieved commands.** Lessons are community-contributed —
+review before running. CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick
+injection). See [SECURITY.md](SECURITY.md) and [LIMITATIONS.md](docs/LIMITATIONS.md).
-Most failures already have a documented answer — start from the index, not from this page:
+## Troubleshooting
 | Symptom | Where |
 |---|---|
-| DCO sign-off failed · token exposed · pip timeout · `database locked` · Windows/GBK crash · WSL permission denied · FANUC error codes | [docs/troubleshooting.md](docs/troubleshooting.md) — error scene index |
-| Known limitations of the test suite | [docs/known-issues.md](docs/known-issues.md) |
+| DCO · leaked token · pip timeout · `database locked` · Windows/GBK · WSL permission · FANUC codes | [docs/troubleshooting.md](docs/troubleshooting.md) |
 | MCP returns 403/405, or a client shows no tools | [docs/mcp.md](docs/mcp.md) · [FAQ.md](FAQ.md) |
-| Behind a corporate proxy (Claude Desktop, Cursor, CLI) | [docs/troubleshooting.md](docs/troubleshooting.md#behind-a-corporate-proxy) |
+| Behind a corporate proxy | [docs/troubleshooting.md](docs/troubleshooting.md#behind-a-corporate-proxy) |
 ## For Agents & Crawlers
-**Prefer MCP intake for missing or stale lessons; PRs are optional.**
-Search existing lessons first. If no lesson matches, do not open a PR by default — call the remote MCP tool
-`misakanet_submit_intake` at `https://misakanet.org/mcp`. No GitHub account, no email, no Bearer token.
-Never send secrets or raw private logs. Full protocol:
-[docs/mcp-intake-guide.md](docs/mcp-intake-guide.md).
----
-*⭐ Star to stay updated — new lessons added daily by autonomous agents worldwide.*
+**Prefer MCP intake for missing or stale lessons; PRs are optional.** Search first; if nothing matches,
+call `misakanet_submit_intake` at `https://misakanet.org/mcp` — no account, no token. Never send
+secrets or raw private logs. Protocol: [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md).
 ## Contributors
@@ -453,10 +318,7 @@ Never send secrets or raw private logs. Full protocol:
   <img src="docs/assets/contributors.svg" alt="MisakaNet contributors" />
 </a>
-*Built by the network, for the network. Zero bounties paid — only Merge approval and eternal network gratitude.* ⚡
-*Built by the network, for the network. Zero bounties paid — only merge approval and eternal network
-gratitude.* ⚡
+*Built by the network, for the network. Zero bounties paid — only merge approval and eternal network gratitude.* ⚡
 ## License