<div align="right">

[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)

</div>

# MisakaNet

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.
>
> Agent-native interfaces: [MCP server](https://misakanet.org/mcp) (7 tools), WebMCP (browser
> `navigator.modelContext`), `llms.txt` / `llms-full.txt`, and A2A discovery through
> `.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"/>
</p>

<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/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>
  <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Ikalus1988/MisakaNet?color=blueviolet" alt="License"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/stargazers"><img src="https://img.shields.io/github/stars/Ikalus1988/MisakaNet?style=social" alt="Stars"></a>
</p>

<p align="center">
  <em>Install</em>
  &nbsp;&nbsp;
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python"></a>
  <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>
</p>

---

## Install (30 seconds)

| Your host | Command |
|---|---|
| **DeepSeek Harness** | `dsh plugin --profile web add misakanet` — or type `misakanet` in the host's **Add plugin** dialog |
| **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 |
| **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>

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

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.

**In 2.40.0 — published.** These six seats are what `npm view misakanet version` gives you today.

| 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.

| 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`). |

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`.

## 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.

| | |
|---|---|
| **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.

| 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 |

### What it can and cannot answer

![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)

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.

### 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?

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.

Latest aggregated data: [`docs/benchmarks/latest.json`](docs/benchmarks/latest.json) (2026-09-22, two
independent runs of ≈500 scenarios each):

| 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% |

**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.

**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).

**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.

<!-- BEGIN generated: benchmark-trend -->

| Date | with_lesson hit rate | plain hit rate | n |
|---|---|---|---|
| 2026-08-30 | 46.4% | 23.9% | 358 |
| 2026-08-31 | 49.1% | 25.1% | 398 |
| 2026-09-06 | 48.3% | 24.1% | 455 |
| 2026-09-14 | 46.6% | 23.4% | 494 |
| 2026-09-21 | 46.1% | 23.3% | 512 |

_1155 run(s) in `latest.json` carry no `run_at` and are excluded; they predate the stamp added alongside this generator._

```
with_lesson hit rate (per run date)
46.1% │ ▁
46.6% │ ▂
48.3% │ ▆
49.1% │ █
46.4% │ ▁
      └──────────────────
       08  08  09  09  09
       30  31  06  14  21
```

<!-- 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:

| 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.

## Why failure-memory?

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.

Three deliberate engineering choices, each of which trades something:

* **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.

## 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):

| 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 |
| the library in my own code | `pip install misakanet-core` | nothing |

**The two-package trap** (this one 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}}}'
```

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
([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)

### 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).

```yaml
on:
  workflow_run:
    workflows: ["CI"]                # your CI workflow's name
    types: [completed]
permissions:
  actions: read                      # read the failing job's log (required)
  pull-requests: write               # post the comment
  issues: write                      # the comment endpoint is issues.createComment
jobs:
  intake:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: Ikalus1988/MisakaNet@v1
        with:
          mode: suggest-only         # or suggest-and-intake, to report new errors too
          source: ${{ github.repository }}
```

→ [inputs and outputs](docs/agents/external-usage.md) · [why `actions: read` is not optional](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) |
| 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) |

## 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)

## Security

⚠️ **Always sandbox your Agent before executing retrieved commands.** Lessons are community-contributed — review before run.

CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick injection). See [SECURITY.md](SECURITY.md).

See [LIMITATIONS.md](docs/LIMITATIONS.md) for known constraints and non-goals — we believe honest disclosure builds trust.

## Troubleshooting

Most failures already have a documented answer — start from the index, not from this page:

| 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) |
| 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) |

## 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.*

## Contributors

<a href="https://github.com/Ikalus1988/MisakaNet/graphs/contributors">
  <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.* ⚡

## License

[Apache-2.0](LICENSE) — Copyright 2026 Ikalus1988. Lessons are contributed under the same license, and
every commit carries a DCO `Signed-off-by` (see [CONTRIBUTING.md](CONTRIBUTING.md)).