Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(mcp): add reverse-engineering implementation playbook

Rahman3ab5b66b00e5
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..9b9862b2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# AGENTS.md — MSO agent instructions
+
+`CLAUDE.md` is the full repository/operator contract and remains authoritative. Read it
+before changing MSO. This file gives non-Claude agents the minimum routing needed to avoid
+re-discovering the same failure patterns.
+
+## Systematic implementation default
+
+For debugging, integrations, refactors, deployments, and MCP work, use this loop:
+
+1. **Resolve the real target** — identify the canonical repository, active branch, running
+ process/container, deployed version, state directory, and public route. Never edit the
+ first matching clone, package cache, generated build, or `/tmp` checkout.
+2. **Observe before changing** — reproduce the behavior and preserve the first concrete
+ error, response, screenshot, cookie, process state, or diff that proves it.
+3. **Map the pattern end to end** — trace entry point → adapter/schema → handler → shared
+ guard/state → UI/client → deploy/runtime. Find a working sibling implementation before
+ inventing a new architecture.
+4. **Name the limits** — record scope, permissions, trust, client caches, pagination/cursors,
+ process lifetime, ports/domains, persistence, cross-repo contracts, and deployment
+ boundaries. Separate facts, inferences, and unknowns.
+5. **Run the smallest discriminating experiment** — test one hypothesis at a time. Do not
+ stack several speculative fixes or retry an unchanged command without new information.
+6. **Make one reversible change** — preserve current configuration and data, keep a rollback,
+ and change the smallest authoritative layer rather than patching symptoms in every caller.
+7. **Verify in layers** — targeted test → contract/parity check → build → runtime health →
+ browser/mobile/session-restart proof when applicable. A zero exit code is not proof of the
+ requested behavior.
+8. **Record the reusable pattern** — durable workflow policy belongs in `AGENTS.md`,
+ `CLAUDE.md`, or a trusted `SKILL.md`; implementation contracts belong in current docs;
+ volatile host facts stay in project/runbook notes.
+
+## MCP feature work
+
+Use [`docs/MCP-FEATURE-IMPLEMENTATION.md`](./docs/MCP-FEATURE-IMPLEMENTATION.md) and the
+official [`mso-mcp-feature-engineering`](./claude-skills/mso-mcp-feature-engineering/SKILL.md)
+skill. Public MCP tool names, schemas, scope, audit metadata, parity, toolset signature,
+external mappings, skill trust/routing, and client action refresh are one release contract.
+Do not declare an MCP change complete until that full contract is verified.
+
+## Shipping
+
+Follow `CLAUDE.md`: update `docs/PROGRESS.md`, run the relevant gates, and ship through
+`bun run ship "<conventional commit>"`. Do not replace the repository's release path with a
+bare push.
diff --git a/CLAUDE.md b/CLAUDE.md
index d51db59d..b6351785 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -34,6 +34,8 @@ agent — it runs AS a host process and controls its own machine.
that historical context.
- `frontend/slices/assistant/CONTRACT.md` — current, and authoritative for what an
Agent / Tool / Skill / Playbook is and what reaches the model.
+- `docs/MCP-FEATURE-IMPLEMENTATION.md` — stepwise observe/map/bound/reverse-engineer/
+ verify playbook for MCP tools, trusted skills and project capabilities.
**The doc set, and the one rule.** `docs/README.md` is the map. `docs/PROGRESS.md` is
the SSOT for historical WHY; current reference docs describe today's contracts; dated
@@ -48,6 +50,15 @@ is the WHY; CHANGELOG is the WHAT, and it is what Settings → About renders as
**New workflow skills use `bun run skill:new`, then `bun run skill:check`.** The source template is `templates/mso-skill-flow/SKILL.md.template`; do not hand-copy an untrusted skill into the official root.
+**Systematic implementation is the default.** Resolve the canonical source and running target;
+reproduce before editing; map the end-to-end pattern and every relevant limit; compare a working
+analogue; run one discriminating experiment at a time; make the smallest reversible change; then
+verify targeted contract, build, runtime and browser/client state. Do not repeatedly retry the same
+failed operation, edit temporary/generated copies, or claim completion from a zero exit code. For
+MCP features use `docs/MCP-FEATURE-IMPLEMENTATION.md` and the
+`mso-mcp-feature-engineering` skill; tool name/schema/scope/audit/parity/toolset/client refresh and
+skill trust/routing are one release contract.
+
**Shipping is `bun run ship "<conventional commit>"`, not `git push`.** Prod is
systemd with NO webhook, so a pushed commit changes nothing the owner can see until
someone rebuilds. The script does changelog → commit+push (gates run) → build →
@@ -298,6 +309,8 @@ toolset metadata, workflow activity and dispatch; routes live under `/mcp`, `/oa
and `/.well-known/oauth-*`. **`OS_MCP_ENABLED=1` or every one of those routes 404s** —
that is the kill switch, and demo mode forces it off. Read `docs/MCP.md`; for ChatGPT
setup/diagrams use `docs/CHATGPT-PLUGIN.md`.
+Implementation changes must also follow `docs/MCP-FEATURE-IMPLEMENTATION.md`; inspect
+the real runtime and working analogue before changing a tool or skill contract.
- **`/mcp` is deliberately NOT under `/api`.** `proxy.ts` blocks mutating `/api` that
cannot prove same-origin and an MCP client is cross-origin by definition; the bearer
is the control, not the CSRF gate. `proxy.ts` exempts `/mcp`, `/oauth/token`,
diff --git a/claude-skills/mso-mcp-feature-engineering/SKILL.md b/claude-skills/mso-mcp-feature-engineering/SKILL.md
new file mode 100644
index 00000000..55711075
--- /dev/null
+++ b/claude-skills/mso-mcp-feature-engineering/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: mso-mcp-feature-engineering
+description: "Implement or repair MSO MCP tools, trusted skills, project function capabilities, scopes, audits, and client refresh behavior by reverse-engineering the live path, changing one reversible layer at a time, and proving parity plus runtime behavior."
+metadata:
+ mso:
+ risk: medium
+ policy: observe-map-bound-reverse-engineer-verify
+---
+
+# /mso-mcp-feature-engineering — MCP Feature Engineering
+
+Use this skill for a durable MSO MCP implementation or repair. The detailed checklist lives in
+[`docs/MCP-FEATURE-IMPLEMENTATION.md`](../../docs/MCP-FEATURE-IMPLEMENTATION.md).
+
+## Trigger and boundaries
+
+- **Use when:** adding, removing, renaming, debugging, or extending an MCP tool; changing
+ OAuth/scope/audit/toolset behavior; adding trusted skill discovery/routing; or adding an
+ opt-in project function capability.
+- **Do not use when:** answering a one-off MCP question, performing one direct bounded read, or
+ changing an unrelated product feature that does not alter MCP/skill contracts.
+- **Required context:** canonical repository and branch, running service/container and version,
+ current toolset descriptor, affected state owner, working analogue, and exact user-visible
+ failure or desired contract.
+
+## Non-negotiable pattern
+
+1. **Resolve the target.** Distinguish source checkout, generated bundle, installed package,
+ running service/container, state volume, reverse proxy and external client snapshot. Never
+ edit a temporary audit clone or first search match.
+2. **Observe.** Reproduce and preserve the first concrete error or behavioral evidence.
+3. **Map.** Trace client/descriptor → route → schema → dispatcher → shared host guard/state →
+ response → UI/client. For skills, trace root → trust → id → search/read → model context.
+4. **Bound.** List scope, trust, audit, limits, cursors, client cache, cross-repo names, process
+ lifetime, persistence, domain/port and release constraints. Separate fact/inference/unknown.
+5. **Reverse-engineer.** Find the nearest working sibling and reuse its authoritative seam.
+6. **Experiment.** Run the smallest test that can reject one hypothesis; do not stack guesses or
+ retry unchanged inputs.
+7. **Change.** Make one reversible mutation in the authoritative layer and preserve state.
+8. **Prove.** Verify targeted contract, build, runtime and external-client behavior before
+ finishing.
+
+## Tool contract
+
+For a public MCP tool, inspect and update all affected surfaces:
+
+- stable public name and input schema;
+- scope tier plus list-time and call-time enforcement;
+- thin delegation to `lib/host` or another existing guarded capability;
+- audit action/target for mutation or exec;
+- rate, size, timeout, path, pagination and continuation limits;
+- Alfa/MCP parity or an explicit documented MCP-only reason;
+- toolset version/hash/count and public descriptor;
+- connectors-gateway literals and other external action mappings;
+- current docs, progress rationale and client-rescan instructions.
+
+Never create a parallel raw `fs`/`child_process` path inside a tool. Never rename a public tool
+without checking the external mapping contract.
+
+## Skill contract
+
+For a trusted workflow skill:
+
+- generate with `bun run skill:new` and keep it under 200 lines;
+- make use/do-not-use triggers and required context precise enough for semantic routing;
+- prefer bounded direct tools; use one `workflow_start` for multi-step work and carry its exact
+ `workflow_id` on every operational call;
+- define expected state, targeted checks, runtime/visual proof, diff boundary and rollback;
+- keep volatile project facts and every secret out of the skill;
+- validate with `bun run skill:check` and confirm `skills_search` routes intended prompts;
+- remember that trust is derived from root/provenance/ownership, never frontmatter.
+
+## Project function contract
+
+Keep project function names as data behind the stable `project_capabilities` and
+`project_function_call` pair. Validate `.mso/functions.json`, declared arguments, working
+directory, scope and refusal behavior. Do not add one global MCP tool per project function.
+
+## Fast route
+
+- One direct operation: use the exact bounded tool and verify it.
+- Multi-step task: call `workflow_start` once with complete intent/project/constraints; do not
+ call `skills_search` first for the same task.
+- Repository search, Git, tests, build, or three or more related reads: use one narrow
+ `exec_run` batch when exec scope is available.
+- Long-running MSO release: use the repository handoff path and poll its owner unit/log; replacing
+ `mso.service` terminates the MCP request that initiated it.
+
+## Verification contract
+
+- **Expected state:** source, descriptor, scope, audit, skill/tool routing and live behavior agree.
+- **Targeted checks:** schema/helper tests; list/call scope tests; audit/limit tests; skill check;
+ parity and external mapping checks.
+- **Runtime proof:** live `GET /mcp` toolset signature, service health/version, state ownership,
+ and a real call through the changed path.
+- **Visual proof:** required for UI/mobile/auth changes; test actual scroll/viewport/session close
+ and reopen rather than inferring from CSS or cookie source.
+- **Diff boundary:** MCP/skill/doc surfaces required by the contract only; no provider, runtime,
+ domain or unrelated refactor changes without separate justification.
+
+## Failure and rollback
+
+- Preserve the first error before retrying.
+- Stop on ambiguous project/runtime identity, missing scope, or truncated discovery without a
+ continuation cursor.
+- Roll back the smallest changed layer while preserving state and configured domains.
+- Never force-push, delete user data, expose credentials, or claim live success from source/build
+ evidence alone.
+
+## Recipe memory
+
+Save only redacted, replayable steps and the pattern that worked. Do not store file bodies,
+tokens, cookies, private URLs, auth callbacks, secrets, or volatile PIDs. A failed attempt is
+evidence, not the replacement for a verified recipe.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index a45b102b..6f43846e 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -6,6 +6,10 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
## 2026-08-26
+**Added**
+
+- `mcp` add reverse-engineering implementation playbook
+
**Docs**
- refresh changelog
diff --git a/docs/MCP-FEATURE-IMPLEMENTATION.md b/docs/MCP-FEATURE-IMPLEMENTATION.md
new file mode 100644
index 00000000..c31df679
--- /dev/null
+++ b/docs/MCP-FEATURE-IMPLEMENTATION.md
@@ -0,0 +1,195 @@
+# MCP feature implementation — reverse-engineering playbook
+
+> **Current implementation note.** This document describes how to add or repair MSO MCP
+> tools, trusted skills, project function capabilities, OAuth/scope behavior, and client
+> action definitions without guessing. Protocol and security authority remains
+> [`MCP.md`](./MCP.md); Alfa/Tool/Skill/Playbook semantics remain
+> [`frontend/slices/assistant/CONTRACT.md`](../frontend/slices/assistant/CONTRACT.md).
+
+## 1. Default loop: observe → map → bound → reverse-engineer → change → prove
+
+Large integration failures are rarely one missing line. They usually cross a runtime owner,
+transport contract, client cache, persistence boundary, and deployment path. Work in explicit
+stages:
+
+1. **Resolve the canonical target.** Record the real repository/worktree, branch and SHA,
+ running service/container, image/package version, state directory, public origin, and
+ ownership model. A package cache, generated bundle, npm global install, temporary clone,
+ and live container are different targets.
+2. **Capture the current behavior.** Reproduce it with the smallest request or viewport.
+ Preserve the first error and the evidence needed to compare after the fix.
+3. **Draw the execution path.** Follow public descriptor/client → MCP route → tool schema →
+ dispatcher → shared host capability → state/audit → response. For skills, follow discovery
+ root → trust calculation → catalog id → search/read → model context.
+4. **List contracts and limits.** Include scope tier, token/client identity, path jail,
+ approval/audit behavior, scan caps and cursors, external action mappings, client-side tool
+ snapshot, process lifetime, release handoff, state persistence, and domain/port behavior.
+5. **Find the working analogue.** Compare with a sibling tool, Hermes/OpenClaw managed app,
+ existing skill, or the in-app Alfa surface. Reuse the established seam; do not create a
+ parallel implementation just because it looks faster.
+6. **State hypotheses.** Label each as fact, inference, or unknown. Run the smallest experiment
+ that can reject one hypothesis. Do not retry the same failed operation unless the inputs or
+ environment changed.
+7. **Change one authoritative layer.** Prefer a small reversible mutation with preserved state
+ and an explicit rollback. Do not patch generated output, every caller, or a temporary copy.
+8. **Prove the user-visible outcome.** Targeted tests and build are necessary but not sufficient;
+ verify the running route, mobile geometry, cookie/session restart, external client refresh,
+ or other exact behavior the request concerns.
+
+## 2. Reverse-engineering map
+
+Before implementation, fill this map:
+
+| Question | Required evidence |
+|---|---|
+| What owns the runtime? | systemd unit, container, package launcher, or Next service plus exact version/SHA |
+| What owns persistent state? | canonical directory/database/cookie and its mount/domain/lifetime |
+| What is the public contract? | tool name/schema, OAuth discovery, scope, annotations, response shape |
+| What is cached elsewhere? | ChatGPT/Claude/Cursor tool snapshot, browser state, reverse proxy, image tag |
+| What is the working analogue? | exact sibling files and why their lifecycle matches |
+| What is optional? | domain, provider, UI shell, CLI, external mapping, or project capability |
+| What is the rollback? | previous commit/image/config and state-preserving restore path |
+| What proves completion? | test, descriptor/hash, runtime health, browser/action refresh, and live result |
+
+If any row is unknown and materially affects the change, inspect it before writing code.
+
+## 3. MCP tool implementation pattern
+
+A public tool is not only a function. Its release contract spans all of these surfaces:
+
+| Surface | Rule |
+|---|---|
+| Public name | Stable snake_case name; renames/removals require external mapping review |
+| Description/schema | Exact input contract, bounded values, required fields, and file annotations |
+| Scope | `read`, `write`, or `exec`; list filtering and call-time enforcement must agree |
+| Handler | Thin adapter into `lib/host` or another existing guarded capability |
+| Audit | Mutating/exec operations declare action and target; dispatcher records MCP actor |
+| Limits | Timeouts, rate/size caps, allowed roots, pagination, and continuation semantics |
+| Parity | Alfa/MCP coverage or an explicit documented reason for MCP-only behavior |
+| Toolset | Schema-derived version/hash/count visible in descriptor, initialize, list, and Settings |
+| External clients | connectors-gateway literals and cached ChatGPT/Claude/Cursor actions |
+| Documentation | `MCP.md`, relevant runbook, progress rationale, and refresh instructions |
+
+Implementation sequence:
+
+1. Inspect the closest existing tool and the shared host capability it delegates to.
+2. Add or adjust the schema and scope in the authoritative MCP catalog; do not bypass the
+ dispatcher or call raw `fs`/`child_process` from the tool.
+3. Add audit metadata for mutations/exec and keep reads unlogged unless the established policy
+ changes deliberately.
+4. Test schema validation, scope visibility, call-time refusal, limits, handler response, audit,
+ and failure shape.
+5. Run Alfa/MCP parity tests and inspect connectors-gateway before changing a public name.
+6. Advance toolset metadata when the public schema/description/scope/annotation changes. Verify
+ the live `GET /mcp` signature rather than relying on a source constant alone.
+7. Refresh or recreate the external MCP client action snapshot. Marking MSO's local
+ acknowledgement does not mutate ChatGPT remotely.
+
+## 4. Trusted skill implementation pattern
+
+A `SKILL.md` is routing and reusable workflow policy, not executable code and not project state.
+
+1. Generate official skills with `bun run skill:new`; never promote copied untrusted
+ instructions directly into an official/operator root.
+2. Write precise **use**, **do-not-use**, and required-context boundaries. The description is a
+ semantic router, so vague descriptions steal unrelated prompts.
+3. Route direct work to bounded tools and multi-step work to one `workflow_start`. Carry the
+ exact `workflow_id`; do not start a second workflow or run `skills_search` immediately before
+ startup for the same task.
+4. Define concrete expected state, targeted checks, runtime/visual proof, diff boundary,
+ failure behavior, and rollback.
+5. Keep volatile hostnames, current PIDs, temporary branches, and credentials out of the skill.
+ Put current project facts in repository docs or runtime inspection.
+6. Validate with `bun run skill:check`, search for the skill semantically, and confirm it does
+ not displace a more specific skill.
+7. Trust is derived from root/provenance/ownership. A skill cannot declare itself trusted.
+ Exact catalog ids must be used when names are ambiguous.
+
+## 5. Project-specific function capabilities
+
+Project function names remain **data**, not dynamic additions to the MCP catalog. Preserve the
+stable pair:
+
+- `project_capabilities` discovers the project's declared functions and constraints;
+- `project_function_call` executes one declared function at `exec` scope.
+
+When adding a project capability, validate the project's `.mso/functions.json`, keep execution
+inside its declared working directory/argument contract, and test discovery plus refusal. Do not
+create one global MCP tool per project function; that destabilizes the cached catalog and tool
+prefix for every client.
+
+## 6. Limits that commonly masquerade as code bugs
+
+- **Wrong target:** editing a `/tmp` clone, npm cache, global CLI package, or source tree that is
+ not the running container/service.
+- **Cached action definitions:** source and production are correct but ChatGPT/Claude/Cursor is
+ still calling an old schema until tools are rescanned.
+- **Truncated discovery:** `maxProjects`, `maxProjectSkills`, deadline, and entry caps produce a
+ partial catalog. Continue only with the returned cursor; no cursor means stop paging.
+- **Ambiguous skill names:** a bare id must be refused when several projects expose it.
+- **Scope mismatch:** a tool may exist globally but be hidden/refused for the bearer tier.
+- **Long-running release:** replacing `mso.service` terminates the MCP caller; release handoff
+ must be polled through the owner update unit/log until final verification.
+- **Optional domains:** a port-capable app must not treat DNS as an install dependency; preserve
+ configured domains and retain public-IP/localhost fallback according to the app contract.
+- **Session persistence:** a valid JWT without persistent cookie attributes is still a browser
+ session cookie. Verify expiry, Secure behavior, host/domain scope, and browser restart.
+- **Mobile viewport:** `100vh` can describe the layout viewport while the software keyboard
+ changes the visual viewport. Verify real geometry, scroll ownership, safe areas, and focus.
+- **Secrets:** never persist tokens, cookies, auth callback URLs, private keys, or raw secret-
+ bearing command arguments in skills, recipes, logs, or progress notes.
+
+## 7. Verification ladder
+
+Use the lowest layer that can reject the current hypothesis, then climb:
+
+1. Pure helper/schema test.
+2. Tool list/call scope and validation test.
+3. Handler/shared-host integration test.
+4. Parity, docs, skill, link, and toolset-signature gates.
+5. Production build from a clean/writable temporary state.
+6. Runtime descriptor, health, version, state mount, and route verification.
+7. Browser/mobile/action test, including close/reopen for persisted sessions.
+8. External MCP client rescan and a real tool call when the public contract changed.
+
+Compare a patched run against an unchanged control when the upstream suite has known failures.
+A passing targeted suite plus an identical control/patched failure set is stronger evidence than
+claiming a historically red full suite is green.
+
+## 8. Reusable implementation note template
+
+Copy this structure into the task's issue, progress entry, or handoff—not into a second permanent
+progress log:
+
+```text
+Feature / symptom:
+Expected user-visible behavior:
+Observed evidence:
+Canonical repository + branch/SHA:
+Running owner + version/image:
+Persistent state owner:
+Working analogue:
+Public contracts affected:
+Known limits and optional dependencies:
+Facts / inferences / unknowns:
+Smallest discriminating experiment:
+Chosen authoritative change:
+Rollback:
+Targeted checks:
+Build/contract checks:
+Runtime/browser proof:
+External client refresh required:
+Durable docs/skill updated:
+```
+
+## 9. Definition of done
+
+An MCP feature is complete only when:
+
+- the canonical source and running target are identified;
+- the public schema, scope, audit, limits, parity and external-name contracts agree;
+- targeted tests, docs/skill gates and the required build pass;
+- state and rollback are preserved;
+- the exact live behavior is verified;
+- affected external clients have refreshed their cached actions;
+- the reusable pattern is captured without storing secrets or volatile host facts.
diff --git a/docs/MCP.md b/docs/MCP.md
index 050a2efa..dc16f1a6 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -5,6 +5,11 @@
> setup values and diagrams. This file owns protocol, tool, discovery, workflow and
> security internals.
+> For implementation or repair work, follow
+> [`MCP-FEATURE-IMPLEMENTATION.md`](./MCP-FEATURE-IMPLEMENTATION.md): resolve the live
+> target, map patterns and limits, reverse-engineer a working analogue, change one reversible
+> layer, then prove tool/skill parity and runtime behavior.
+
mso ships an MCP server so an AI client can call the same host operations the web
UI does: list and read files, write them, check CPU/memory/disk, list processes and
managed apps, and — if you grant it — run shell commands.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index f61f807f..4578f243 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -9,6 +9,24 @@ Running log of what shipped each phase. Newest at top.
> [`docs/README.md`](./README.md) and [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md); keep old
> entries intact as historical evidence even when their commands/counts have been superseded.
+## 2026-08-27 — systematic reverse-engineering + MCP feature playbook (DONE)
+
+Implementation work now has one durable default across Claude, Codex/general agents and MSO:
+resolve the canonical source/runtime first, reproduce and preserve evidence, map the end-to-end
+pattern and limits, compare a working analogue, test one hypothesis at a time, make the smallest
+reversible change, and prove the exact live outcome. This prevents the repeated failure mode where
+an agent edits a temporary clone, retries a connector with the same invalid shape, stacks several
+speculative fixes, or reports success from a build without checking the running feature.
+
+`docs/MCP-FEATURE-IMPLEMENTATION.md` records the complete MCP implementation contract for tools,
+trusted skills and project functions: public schema/name stability, scope, thin `lib/host`
+delegation, audit metadata, limits/cursors, Alfa parity, toolset signature, external mappings,
+client action refresh, trust/id routing, release handoff and layered runtime/browser proof. The
+new official `mso-mcp-feature-engineering` skill makes that workflow searchable and reusable,
+while root `AGENTS.md` gives non-Claude agents the same repository routing. Global agent
+instruction files point to the same pattern; volatile host facts and secrets remain outside the
+skill and repository policy.
+
## 2026-08-25 — 9Router configured-domain UI + official icon correction (DONE)
The first public-IP fallback pass made the fallback the preference: because every managed
diff --git a/docs/README.md b/docs/README.md
index 425ad6f3..3f366b3d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -24,6 +24,7 @@ machine-verifiable facts. The repository quality gate runs it automatically.
| [`DEVELOPMENT.md`](./DEVELOPMENT.md) | Development and release workflow |
| [`CLI.md`](./CLI.md) | Generated `mso` CLI contract |
| [`MCP.md`](./MCP.md) | MCP/OAuth internals and full external-tool security model |
+| [`MCP-FEATURE-IMPLEMENTATION.md`](./MCP-FEATURE-IMPLEMENTATION.md) | Stepwise reverse-engineering workflow for MCP tools, trusted skills and project capabilities |
| [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) | ChatGPT custom MCP app setup, diagrams, scopes and file bridge |
| [`CONNECTORS-GATEWAY-INTEGRATION.md`](./CONNECTORS-GATEWAY-INTEGRATION.md) | MSO ↔ connectors-gateway action-name contract |
| [`MANAGED-APPS.md`](./MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, backup/restore and dashboard access boundary |