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): encode agent bootstrap and capability-parity map

Cursor Agentd11c7a731fc1
diff --git a/AGENTS.md b/AGENTS.md
index 3303df3e..4e84b5bf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -71,6 +71,8 @@ official [`mso-mcp-feature-engineering`](./claude-skills/mso-mcp-feature-enginee
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.
+Agents *using* MSO over MCP start from [`docs/AGENT-BOOTSTRAP.md`](./docs/AGENT-BOOTSTRAP.md)
+and official skill `mso-agent-bootstrap`, not by jumping to `exec_run`.
## Cognitive-runtime work
diff --git a/claude-skills/mso-agent-bootstrap/SKILL.md b/claude-skills/mso-agent-bootstrap/SKILL.md
new file mode 100644
index 00000000..93b4282e
--- /dev/null
+++ b/claude-skills/mso-agent-bootstrap/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: mso-agent-bootstrap
+description: "Use this when connecting to MSO via MCP (ChatGPT, Cursor, Grok, or other clients), when an agent needs the first-call orientation sequence, or when checking capability parity across Alfa, CLI, and MCP before mutating the host."
+metadata:
+ mso:
+ risk: low
+ policy: orient-then-act
+---
+
+# /mso-agent-bootstrap — first-call map for every AI surface
+
+MSO is one capability kernel with several presentations. ChatGPT, Cursor, the terminal
+`mso` agent, and Alfa-via-gateway all reach the same maximal host power. Compact
+schemas, `dot.case` Alfa names, and catalog-first terminal packs are presentation,
+not missing features.
+
+## Trigger and boundaries
+
+- **Use when:** starting an MCP session, teaching an agent how MSO works, or choosing
+ the first tools before a mutation.
+- **Do not use when:** a narrower official skill already matches (deploy, repo-work,
+ camoufox, integrations) and you already know the map.
+- **Required context:** token scope (`read`/`write`/`exec`) and whether the project
+ id/path is already known.
+
+## Fast route
+
+1. `skills_search` query `mso-agent-bootstrap`, or `skills_read` this id. ChatGPT may
+ already have the published copy; still prefer the live catalog when unsure.
+2. `projects_list` if the project is unresolved. Honor `scan.truncated`.
+3. `workflow_start` once for multi-step work; pass exact `workflow_id` thereafter.
+ Skip this on a read token. Do not call `skills_search` immediately before startup
+ for the same task.
+4. Project MCP: `project_capabilities` → `project_mcp_tools` → `project_mcp_call`.
+ Never fuse discover and call. Never copy project tool names into the global catalog.
+5. Credentials: `integration_query` → private setup/verify → `integration_execute`.
+ Never put secrets in chat or tool arguments.
+6. Prefer `read_pipeline` and bounded `fs_*`/`sys_*`/`vps_status` before `exec_run`.
+7. Mutate infra only through bounded tools with `confirm`. Doctor/health first.
+
+Then verify and `workflow_finish`, or `workflow_cancel`.
+
+## Surface tips
+
+| Surface | Entry tip |
+|---|---|
+| ChatGPT MCP | Published skill + compact `tools/list`. Follow `initialize.instructions`. Page tools are UI, not extra power. |
+| Cursor / Grok MCP | Full schemas. Same sequence. `initialize.instructions` is the prefill. |
+| Terminal `mso` agent | Catalog-first packs already pick maximal tools. `/skill mso-agent-bootstrap` if you need the map. Do not `skills_search` when the needed tool is visible. |
+| Alfa via gateway | Same MCP server as Cursor. Use this sequence. |
+| Alfa in-shell | `dot.case` host tools + owner UI. MCP-only tools are identity boundaries, not holes. |
+
+## Tool routing
+
+| Need | Preferred | Avoid |
+|---|---|---|
+| Orientation | this skill, then `workflow_start` | jumping to `exec_run` |
+| One read | bounded read / `read_pipeline` | shell for a single file |
+| Project MCP | capabilities → tools → call | inventing global tool names |
+| Credentials | `integration_query` then private setup | pasting keys into chat |
+| Infra change | bounded provider tool + confirm | raw `systemctl` / secret env |
+| Long build | `exec_job_start` + status | blocking `exec_run` |
+
+## Hard constraints
+
+Do not hide ChatGPT tools to compress context. Do not fuse project MCP discover/call.
+Do not put secrets in args. Keep `read < write < exec`. Reusing an index or recipe
+does not skip auth.
+
+Full matrix: [`docs/AGENT-BOOTSTRAP.md`](../../docs/AGENT-BOOTSTRAP.md).
+
+## Verification contract
+
+- **Expected state:** the agent can name the next bounded tool for the task.
+- **Targeted checks:** scope matches the tool; `workflow_id` is exact when required.
+- **Runtime proof:** live `GET /mcp` toolset and a real call through the chosen path.
+- **Visual proof:** `screen_capture` only when UI actually changed.
+- **Diff boundary:** no unrelated refactors; no credential values in traces.
+
+## Failure and rollback
+
+Stop when project identity or scope is ambiguous. Preserve the first error. Never
+force-push, dump `~/.mso`, or treat a zero exit as proof.
+
+## Recipe memory
+
+Save redacted steps only. Never persist file bodies, tokens, cookies, or secret-bearing
+argv. A failed run is evidence, not a replacement for a verified recipe.
diff --git a/claude-skills/mso-agent-bootstrap/agents/openai.yaml b/claude-skills/mso-agent-bootstrap/agents/openai.yaml
new file mode 100644
index 00000000..89ee6b1e
--- /dev/null
+++ b/claude-skills/mso-agent-bootstrap/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "MSO Agent Bootstrap"
+ short_description: "Call these MSO tools first"
+ default_prompt: "Use $mso-agent-bootstrap before mutating the host. Follow its first-call sequence, then the normal discover-to-act loop."
diff --git a/claude-skills/mso-agent-bootstrap/contract.yaml b/claude-skills/mso-agent-bootstrap/contract.yaml
new file mode 100644
index 00000000..f2432770
--- /dev/null
+++ b/claude-skills/mso-agent-bootstrap/contract.yaml
@@ -0,0 +1,35 @@
+version: 1
+routing:
+ use_when:
+ - "connecting to MSO via MCP"
+ - "agent needs the first-call orientation sequence"
+ - "capability parity across Alfa, CLI, and MCP"
+ do_not_use_when:
+ - "A narrower official MSO skill exactly matches the requested task and the agent already knows the map."
+ fallback: false
+ prefer_over:
+ - mso
+context:
+ target: mso-agent-bootstrap
+ mode: read
+ actor: operator
+lifecycle:
+ discover:
+ - skills_search
+ - skills_read
+ - projects_list
+ - workflow_start
+ validate:
+ - token-scope
+ - project-identity
+ verify:
+ - workflow_finish
+state:
+ source_of_truth: live
+ refresh: always
+safety:
+ risk: low
+ confirmation: none
+ concurrency: none
+presentation:
+ authority: hybrid
diff --git a/claude-skills/mso/SKILL.md b/claude-skills/mso/SKILL.md
index 7691eef8..ff46fc1e 100644
--- a/claude-skills/mso/SKILL.md
+++ b/claude-skills/mso/SKILL.md
@@ -52,6 +52,9 @@ Use the absolute CLI path above in automation. `$HOME/.local/bin/mso` is a conve
## Learning loop — bootstrap once, keep the fastest verified path
+MCP clients: read `/mso-agent-bootstrap` first (or `skills_search` query `mso-agent-bootstrap`).
+That skill is the first-call map. This skill is the operational policy once you already know it.
+
For any task likely to need two or more operational calls:
1. Call `workflow_start` directly with the user's complete intent, project hint and constraints. It already searches trusted skills, the live MCP tool catalog and learned recipes, resolves project aliases, and reports the current toolset.
diff --git a/docs/AGENT-BOOTSTRAP.md b/docs/AGENT-BOOTSTRAP.md
new file mode 100644
index 00000000..74a43b70
--- /dev/null
+++ b/docs/AGENT-BOOTSTRAP.md
@@ -0,0 +1,99 @@
+# MSO agent bootstrap
+
+This is the canonical **first-call sequence** for every AI surface that drives MSO.
+Implementation and presentation may differ (schema size, tool names, UI), but no
+surface is a permanent second-class citizen for core ops.
+
+The machine-readable copy lives in [`lib/mcp/instructions.ts`](../lib/mcp/instructions.ts)
+and is injected into MCP `initialize.instructions`, `workflow_start.bootstrap.orientation`,
+and the official skill [`mso-agent-bootstrap`](../claude-skills/mso-agent-bootstrap/SKILL.md).
+
+## Canonical sequence
+
+Copy this. Do not skip to `exec_run`.
+
+1. **`skills_search` or `skills_read`** — learn how MSO wants to be used. Query
+ `mso-agent-bootstrap` (or `skills_list` with `trust=official` if you already know
+ the id). ChatGPT also receives this skill through the published MCP Skills
+ extension; still call it when the live catalog may have moved on.
+2. **`projects_list`** — resolve the project if the user named one you have not
+ located. Use the returned id/path; do not guess across containers. Check
+ `scan.truncated` before concluding a project is absent.
+3. **`workflow_start`** — for any task that needs two or more operational calls.
+ Pass complete intent, project hint, and constraints. Carry the **exact**
+ `workflow_id` on every later call in this conversation. Do not call
+ `skills_search` immediately before `workflow_start` for the same task; startup
+ already searches skills/recipes. Read-only tokens cannot start a workflow.
+4. **Project MCP** — `project_capabilities` → `project_mcp_tools` → `project_mcp_call`.
+ Keep discover and call as two tools. Project tool names never join the global
+ MSO catalog. `project=@host` is this VPS; any other value is one exact project.
+5. **Credentials** — `integration_query` → private setup/verify → `integration_execute`.
+ Never put secrets, tokens, or passwords in chat or tool arguments. Open
+ `integration_setup_open` (ChatGPT Page) or native `mso integrations` when a
+ connection is genuinely missing. Mutations need `confirm=true`.
+6. **Reads before shell** — prefer `read_pipeline` and bounded `fs_*` / `sys_*` /
+ `vps_status` / `apps_*` before `exec_run`. Long tests/builds use `exec_job_start`
+ and poll `exec_job_status`, not a blocking `exec_run`.
+7. **Mutating infra** — only bounded tools (`dokploy_*`, `cloudflare_*`,
+ `hostinger_*`, `infra_provider_doctor`) with explicit confirm. Doctor/health
+ first. No raw `systemctl` wildcards, no secret env dumps.
+
+Then verify independently and call `workflow_finish` with the same id (or
+`workflow_cancel` to abandon). A recipe is guidance, not permission.
+
+## Hard constraints
+
+- Do **not** hide callable tools from ChatGPT `tools/list` to compress context.
+- Do **not** fuse `project_mcp_tools` into `project_mcp_call`.
+- Do **not** put secrets in tool args; setup grants stay private.
+- Keep the scope ladder `read < write < exec`. Routing may hide a schema from one
+ model turn; it never elevates permission.
+- Reusing indexes, recipes, or cached descriptors does **not** skip auth.
+
+## Surface variants
+
+Same capability map; different entry tips.
+
+| Surface | Entry | Tips |
+|---|---|---|
+| **ChatGPT MCP** | OAuth connector, compact `tools/list`, published Skills extension | Read published skill `mso-agent-bootstrap` first. Compact descriptions are short; follow `initialize.instructions` and this sequence. Page tools (`render_mso_page`, `integration_setup_open`) are ChatGPT UI, not extra host power. |
+| **Cursor / Grok MCP** | Full generic catalog (~same tools as ChatGPT, longer schemas) | `initialize.instructions` carries the numbered sequence. Use the full descriptions. Still start with the skill or `workflow_start` for multi-step work. |
+| **Terminal `mso` agent** | Catalog-first router, phase-aware packs | The harness already selects a maximal pack for this turn (`workflow_start` first on repo changes). Do not pay extra `skills_search` when the needed tool is visible. `/skill mso-agent-bootstrap` loads this map. Write/exec need `--approve-scope`. |
+| **Alfa via `mso` gateway** | Same MCP server as ChatGPT/Cursor | Treat it as **MCP full**. Use this sequence. Gateway does not shrink capabilities. |
+| **Alfa in-shell** | Browser assistant, `dot.case` host tools | Same host ops through Alfa tools / Files / Organization / Integrations UI. Several MCP-only tools are **identity boundaries** (external principal, ChatGPT Page, durable MCP session), not missing power. See the matrix. |
+
+## Parity matrix
+
+Legend: **Reach** = how this surface performs the capability. **Gap** = accidental hole
+(should close) vs **Intentional** = documented identity/presentation difference.
+
+| Capability | CLI `mso` / terminal agent | MCP full (Cursor/Grok/gateway) | MCP ChatGPT | Alfa in-shell |
+|---|---|---|---|---|
+| Project discovery | `mso projects` / `projects_list` | `projects_list` | same tool, compact schema | Files app + `fs.list`; no `projects.list` (**Intentional**: sidebar already enumerates) |
+| Skills | `mso skills *` / `skills_*` | `skills_search/list/read` | same + 5 published skills | `skills.search/list/read` |
+| Integrations | `mso integrations` | `integration_query` → setup → `integration_execute` | same + `integration_setup_open` Page | Owner Integrations UI; no Alfa credential-owner identity (**Intentional**) |
+| Project MCP | `project_mcp_*` | `project_capabilities` → `project_mcp_tools` → `project_mcp_call` | same; must not hide either tool | inspect `.mcp.json` via fs; no dynamic global catalog (**Intentional**) |
+| Workflows / RASMIC | catalog-first + `workflow_*` | `workflow_start` then exact `workflow_id` | same; `workflow_status` is app-only progress UI | in-app thread is the run boundary; no external `workflow.start` (**Intentional**) |
+| Host reads | `mso ls/cat/stats` / `fs_*` `sys_*` `read_pipeline` | same MCP tools | same | `fs.*` / `sys.*` |
+| Bounded infra | `infra_*` `dokploy_*` `cloudflare_*` `hostinger_*` | same | same compact schemas | dedicated infra apps / Integrations; MCP DNS upsert stays external (**Intentional**) |
+| Doctor / health | `mso doctor`, `sys_stats`, `vps_status`, `infra_provider_doctor` | `vps_status`, `sys_stats`, `infra_provider_doctor` | same | Monitor app + `sys.stats` |
+| Deploys | `mso-deploy` skill / `bun run ship` / Dokploy tools | same tools + skill | same; Page is not a deploy button | owner UI / CLI; no extra Alfa deploy primitive (**Intentional**) |
+
+Presentation differences (ChatGPT 56-character descriptions, terminal pack routing,
+Alfa `dot.case` names) are **not** capability holes.
+
+## Follow-ups (not in this change)
+
+These remain designed-not-shipped. They must not block agents from the sequence above.
+
+- Host file index / replay-by-handle for DRY results across turns.
+- Deeper ChatGPT context compression that does **not** hide callable tools.
+- Closing an Alfa in-shell identity boundary only when a shared principal exists.
+
+## Related contracts
+
+- [`COGNITIVE-RUNTIME.md`](./COGNITIVE-RUNTIME.md) — provider-neutral harness, catalog-first routing.
+- [`MCP.md`](./MCP.md) — OAuth, scope ladder, published skills, `initialize.instructions`.
+- [`RASMIC.md`](./RASMIC.md) — workflow isolation, recipes, verification.
+- [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) — ChatGPT connector and Skills extension.
+- [`MCP-HOW-TO.md`](./MCP-HOW-TO.md) — operator onboarding, including Bahasa Indonesia.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 3bc44dcd..a9937601 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -170,6 +170,8 @@ MSO exposes exactly three user-visible MCP App classes instead:
`workflow_start` is orchestration-only and headless: it still owns workflow isolation, skill/recipe
lookup, collision detection, tracing, evidence, and learning, but no longer binds a UI resource.
+MCP agents learn the first-call map from `mso-agent-bootstrap` and `initialize.instructions`;
+see [`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md).
`project_get`, `project_diff`, and `vps_status` likewise remain pure data tools. The previous
`render_mso_surface` and `workflow_status` actions are app-only compatibility shims for cached
widgets; prior Block/Page URIs plus the previous workflow/surface resource URIs remain readable aliases but are not advertised. Page tools use the standard MCP Apps `ui.resourceUri` binding only; the legacy ChatGPT `openai/outputTemplate` alias is intentionally absent so one tool result maps to one Page mount.
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index a8f12e17..fd6be1cb 100644
--- a/docs/CHATGPT-PLUGIN.md
+++ b/docs/CHATGPT-PLUGIN.md
@@ -72,7 +72,7 @@ After the Fresh 3 rescan exposed `Output schema recommended` on non-UI actions,
### Native MCP skill snapshot
-Fresh 3 also advertises the bounded `io.modelcontextprotocol/skills` extension. `skills/list`, `skills/get`, and `resources/read` publish a submission-time snapshot of exactly five general official MSO skills: `mso`, `mso-repo-work`, `mso-service-debug`, `mso-deploy`, and `mso-mcp-feature-engineering`. Each published skill is now a reviewed bundle containing `SKILL.md`, `contract.yaml`, and `agents/openai.yaml` (plus any skill-specific resources). `contract.yaml` carries structured routing/lifecycle/safety metadata; `agents/openai.yaml` carries concise OpenAI display/default-prompt metadata. Publication fails closed when either structured file is missing or invalid. The manifest still includes complete resources plus `sha256:` digests, refuses symlinks/path normalization conflicts/oversize files, and never publishes operator, project, verified-third-party, or untrusted skill roots. The ordinary `skills_search/list/read` actions remain the live runtime catalog for the rest.
+Fresh 3 also advertises the bounded `io.modelcontextprotocol/skills` extension. `skills/list`, `skills/get`, and `resources/read` publish a submission-time snapshot of exactly five general official MSO skills: `mso-agent-bootstrap`, `mso`, `mso-repo-work`, `mso-service-debug`, and `mso-deploy`. `mso-agent-bootstrap` is first: it is the first-call orientation sequence for MCP agents. Implementer skill `mso-mcp-feature-engineering` stays in the live `skills_search` catalog. Each published skill is now a reviewed bundle containing `SKILL.md`, `contract.yaml`, and `agents/openai.yaml` (plus any skill-specific resources). `contract.yaml` carries structured routing/lifecycle/safety metadata; `agents/openai.yaml` carries concise OpenAI display/default-prompt metadata. Publication fails closed when either structured file is missing or invalid. The manifest still includes complete resources plus `sha256:` digests, refuses symlinks/path normalization conflicts/oversize files, and never publishes operator, project, verified-third-party, or untrusted skill roots. The ordinary `skills_search/list/read` actions remain the live runtime catalog for the rest.
For the complete non-ChatGPT MSO catalog, scopes, limits, A2A, providers, Tool Forge and other generic capabilities, see [`MCP.md`](./MCP.md).
diff --git a/docs/COGNITIVE-RUNTIME.md b/docs/COGNITIVE-RUNTIME.md
index 97d54f4a..b2ec55f5 100644
--- a/docs/COGNITIVE-RUNTIME.md
+++ b/docs/COGNITIVE-RUNTIME.md
@@ -8,6 +8,17 @@ This document is the current contract for the MCP-first Cognitive Runtime throug
used when available, but correctness must not depend on OpenAI-, Anthropic-, Google-, Qwen-, GLM-,
DeepSeek-, or other vendor-specific hidden state.
+## Agent bootstrap (first calls)
+
+Every MCP client receives the numbered first-call sequence in `initialize.instructions`.
+The official skill is `mso-agent-bootstrap`. ChatGPT publishes it first in the five-slot
+Skills extension. Terminal `mso` agent uses catalog-first packs that already start
+repository work with `workflow_start`. Alfa-via-gateway is the same MCP server.
+
+The full sequence, surface variants, and capability-parity matrix live in
+[`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md). Presentation (schema size, tool names, UI)
+may differ; core ops must remain reachable.
+
## Invariants
1. **Authentication is not conversation state.** OAuth/client identity owns durable user state and learned
diff --git a/docs/MCP-HOW-TO.md b/docs/MCP-HOW-TO.md
index fac45593..65cac31c 100644
--- a/docs/MCP-HOW-TO.md
+++ b/docs/MCP-HOW-TO.md
@@ -102,14 +102,21 @@ atau memanggil MCP proyek memerlukan `exec`. Prompt tidak bisa menaikkan scope t
## 5. Urutan tool untuk agent
-Untuk satu pembacaan sederhana, gunakan tool read yang sesuai. Untuk tugas multi-langkah:
+Urutan resmi (sama di ChatGPT/Cursor/CLI/Alfa-via-gateway) ada di
+[`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md) dan skill `mso-agent-bootstrap`:
```text
-workflow_start (sekali) → inspeksi target → perubahan yang diizinkan
-→ verifikasi hasil → workflow_finish
+1. skills_search / skills_read mso-agent-bootstrap
+2. projects_list jika proyek belum diketahui
+3. workflow_start sekali → simpan workflow_id
+4. project_capabilities → project_mcp_tools → project_mcp_call
+5. integration_query → setup/verify → integration_execute (tanpa secret di chat)
+6. read_pipeline / fs_* / sys_* sebelum exec_run
+7. infra bounded + confirm
```
-`workflow_start` sudah mencari skill/konteks yang relevan; jangan mengulang `skills_search`
+Untuk satu pembacaan sederhana, cukup tool read. Untuk tugas multi-langkah, panggil
+`workflow_start` sekali. Ia sudah mencari skill/konteks; jangan mengulang `skills_search`
sebelumnya untuk tugas sama. Contoh argumen bootstrap:
```json
diff --git a/docs/MCP.md b/docs/MCP.md
index 2d8f0b46..626850a2 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -1,7 +1,9 @@
# MCP — drive this VPS from ChatGPT, Claude.ai or Cursor
> **First connection?** Start with [How to use MSO MCP — Bahasa Indonesia](./MCP-HOW-TO.md)
-> for setup, example prompts, workflow usage, and troubleshooting.
+> for setup, example prompts, workflow usage, and troubleshooting. Agents should follow
+> the first-call sequence in [`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md) (official skill
+> `mso-agent-bootstrap`) before mutating the host.
> **Current deep reference.** For ChatGPT specifically, use
> [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) for current custom-MCP-app terminology,
@@ -457,7 +459,7 @@ reported but is not declared beaten on a non-comparable metric.
In addition to the live `skills_*` actions, MSO advertises `capabilities.extensions["io.modelcontextprotocol/skills"]` for ChatGPT/OpenAI plugin scans. The extension is intentionally **static and bounded**: it publishes at most five general official skills from `claude-skills/`, then serves the same complete entry through `skills/list` and `skills/get` and every declared `skill://mso/...` resource through `resources/read`. Each resource is read with `O_NOFOLLOW`, capped before allocation, path-normalized, included in the per-skill 100-file / 5 MiB budget, and hashed as `sha256:<hex>`.
-The published set is `mso`, `mso-repo-work`, `mso-service-debug`, `mso-deploy`, and `mso-mcp-feature-engineering`. This is deliberately separate from MSO's much larger live catalog: operator `~/.mso/skills`, per-project skills, local skills, and third-party/verified/untrusted roots can still be searched/read at runtime but never silently become plugin-submission instructions.
+The published set is `mso-agent-bootstrap`, `mso`, `mso-repo-work`, `mso-service-debug`, and `mso-deploy`. Orientation is first so a ChatGPT import that only takes the syllabus still learns the first-call sequence. Implementer skill `mso-mcp-feature-engineering` remains official and searchable but is not in the five-slot ChatGPT snapshot. This is deliberately separate from MSO's much larger live catalog: operator `~/.mso/skills`, per-project skills, local skills, and third-party/verified/untrusted roots can still be searched/read at runtime but never silently become plugin-submission instructions.
## Semantic skill search and learned workflows
@@ -498,13 +500,17 @@ or token budget. This is a small local semantic router for MSO's skill/tool cata
not a general-purpose cloud embedding model. A future encoder can re-index recipes
because every saved vector carries its version.
-Connected clients receive the bootstrap, terminal-batching, verification and visible-trace policy in MCP `initialize.instructions`:
+Connected clients receive the bootstrap sequence in MCP `initialize.instructions` (see
+[`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md)). The exec-scope form is:
```text
-workflow_start → bounded tools or one scoped terminal batch → verify → workflow_finish
-interrupted run → workflow_cancel with the exact workflow id
+MSO agent bootstrap: 1) skills_search|skills_read … 7) bounded infra + confirm
+Then verify and workflow_finish, or workflow_cancel.
```
+Read-scope tokens get the same map minus `workflow_start`. ChatGPT additionally hears
+that project MCP names never join the global catalog.
+
A recipe is guidance, not permission. The connector still checks current tool
availability, token scope, project context and safety constraints before reusing it.
Recipes that reference a missing or renamed tool are marked and ranked down.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 73e51b9c..1cd75dfa 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,15 @@
+## 2026-09-19 — MCP agent bootstrap and capability-parity map
+
+MCP clients were skipping `workflow_start` / `skills_search` and jumping to `exec_run` because
+the full `tools/list` had no explicit first-call contract. The canonical sequence now lives in
+`lib/mcp/instructions.ts` and is injected into `initialize.instructions`,
+`workflow_start.bootstrap.orientation`, and official skill `mso-agent-bootstrap` (ChatGPT
+published skill #1). ChatGPT still sees every callable MSO tool; project MCP discover/call stay
+two tools; secrets stay out of args. The parity matrix in `docs/AGENT-BOOTSTRAP.md` separates
+presentation differences from intentional Alfa identity boundaries. Catalog routing now matches
+orientation prompts to `skills_search`/`skills_read` instead of shell. Follow-ups (host file
+index, replay-by-handle) are documented, not shipped.
+
## 2026-09-18 — Close external-editor review around durable session policy and owner stores
The latest PR review found four boundary issues after the cookie-policy epoch landed. CLI device
diff --git a/docs/README.md b/docs/README.md
index 7a8e6b85..f0eda6d2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,6 +23,7 @@ evidence and review freshness. The repository quality gate runs both automatical
| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | Current runtime, shell, role, host, Agent/Local Agent/subagent, MCP and deployment architecture |
| [`GATEWAY.md`](./GATEWAY.md) | Provider-neutral gateway state, health, ownership, supervisor and deployment contract |
| [`COGNITIVE-RUNTIME.md`](./COGNITIVE-RUNTIME.md) | Provider-neutral MCP/session/context/tool-routing runtime and benchmark contract |
+| [`AGENT-BOOTSTRAP.md`](./AGENT-BOOTSTRAP.md) | Canonical first-call sequence and capability-parity matrix across CLI, MCP, and Alfa |
| [`RASMIC.md`](./RASMIC.md) | Risk-aware orchestration, repo-local memory/evidence, collision detection and recipe/script promotion |
| [`COMPARISON.md`](./COMPARISON.md) | Generated product comparison methodology, evidence and notes |
| [`COMPETITIVE-ROADMAP.md`](./COMPETITIVE-ROADMAP.md) | Executed comparison plan, deliberate specialist boundaries and next investments |
diff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.md
index 0cdcf467..648e0b9d 100644
--- a/docs/generated/MCP-CATALOG.md
+++ b/docs/generated/MCP-CATALOG.md
@@ -4,13 +4,13 @@
## Full MSO catalog
-<!-- mcp-toolset: server=1.15.1 version=2026.09.18.1 tools=111 read=54 write=35 exec=22 -->
+<!-- mcp-toolset: server=1.15.1 version=2026.09.19.1 tools=111 read=54 write=35 exec=22 -->
| Fact | Current source value |
|---|---:|
| MCP server | `1.15.1` |
-| Toolset | `2026.09.18.1` |
-| Toolset changed at | `2026-09-18T07:18:00+07:00` |
+| Toolset | `2026.09.19.1` |
+| Toolset changed at | `2026-09-19T15:00:00+07:00` |
| Transport tools | **113** |
| Model/operator tools | **111** |
| Read | **54** |
@@ -145,7 +145,7 @@
## ChatGPT model profile
-<!-- mcp-chatgpt-profile: server=1.15.1 version=2026.09.18.1 tools=111 read=54 write=35 exec=22 app-only=2 total=113 -->
+<!-- mcp-chatgpt-profile: server=1.15.1 version=2026.09.19.1 tools=111 read=54 write=35 exec=22 app-only=2 total=113 -->
The ChatGPT profile automatically projects the complete MSO-owned generic model/operator catalog. OAuth scope is still enforced independently; app-only compatibility bridges stay app-only, and project-owned MCP tool names remain dynamic data behind the generic project bridge.
diff --git a/lib/mcp/chatgpt-profile.test.ts b/lib/mcp/chatgpt-profile.test.ts
index ebd97278..d71c4916 100644
--- a/lib/mcp/chatgpt-profile.test.ts
+++ b/lib/mcp/chatgpt-profile.test.ts
@@ -33,6 +33,10 @@ describe("ChatGPT full generic MCP profile", () => {
const bytes = Buffer.byteLength(JSON.stringify(tools));
if (process.env.MSO_PROFILE_METRICS === "1") console.info(`CHATGPT_PROFILE_METRICS tools=${tools.length} bytes=${bytes} roughTokens4=${Math.ceil(bytes/4)} maxToolBytes=${Math.max(...tools.map((tool)=>Buffer.byteLength(JSON.stringify(tool))))}`);
expect(bytes).toBeLessThan(96 * 1024);
+ const start = tools.find((tool) => tool.name === "workflow_start") as { description?: string };
+ expect(String(start?.description)).toMatch(/First call for multi-step work/i);
+ const search = tools.find((tool) => tool.name === "skills_search") as { description?: string };
+ expect(String(search?.description)).toContain("mso-agent-bootstrap");
expect(tools.some((tool) => tool.name === "local_agent_inbox")).toBe(true);
expect(tools.some((tool) => tool.name === "project_mcp_tools")).toBe(true);
expect(tools.some((tool) => tool.name === "project_mcp_call")).toBe(true);
diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.ts
index 05359e8b..f8983d41 100644
--- a/lib/mcp/dispatch.test.ts
+++ b/lib/mcp/dispatch.test.ts
@@ -42,6 +42,8 @@ describe("protocol", () => {
expect(execInstructions).toContain("workflow_start");
expect(execInstructions).toContain("workflow_cancel");
expect(execInstructions).toContain("workflow_finish");
+ expect(execInstructions).toContain("mso-agent-bootstrap");
+ expect(execInstructions).toContain("read_pipeline");
});
it("does not impersonate modern server/discover with an initialize-shaped result", async () => {
diff --git a/lib/mcp/dispatch.ts b/lib/mcp/dispatch.ts
index ba7d8a52..f83484cb 100644
--- a/lib/mcp/dispatch.ts
+++ b/lib/mcp/dispatch.ts
@@ -7,6 +7,7 @@ import { dispatchToolCall } from "./dispatch-tools";
import { readMcpFileResource } from "./file-transfer-resource";
import { toolDescriptor, visibleToolsForProfile, type McpToolProfile } from "./tool-contract";
import { MCP_PROTOCOL_LATEST, MCP_PROTOCOLS, negotiateMcpProtocol } from "./protocol";
+import { mcpInstructions } from "./instructions";
import { rpcFail, rpcOk, type McpAgentContext, type RpcRequest } from "./dispatch-types";
export type { McpAgentContext, RpcRequest } from "./dispatch-types";
@@ -24,15 +25,7 @@ const visibleTools = (scope: Scope, profile: McpToolProfile = "full", allowedToo
const toolList = (scope: Scope, profile: McpToolProfile = "full", allowedTools?: readonly string[]) =>
visibleTools(scope, profile, allowedTools).map((tool) => toolDescriptor(tool, profile));
-function instructions(scope: Scope, profile: McpToolProfile = "full", allowedTools?: readonly string[]): string {
- const startup = allowedTools
- ? `This machine token is restricted to: ${allowedTools.join(", ")}.`
- : scope === "read"
- ? "This token is read-only: use skills_search for capability discovery, then bounded read tools."
- : "For multi-step work call workflow_start once, pass its exact workflow_id on every operation in this conversation, verify, then workflow_finish or workflow_cancel.";
- const projectBoundary = profile === "chatgpt" ? " Project-owned MCP tools never join this catalog: use project_mcp_tools then project_mcp_call." : "";
- return `${startup}${projectBoundary} Call agent_session_open for provider-neutral sessions, then send params._meta[mso/sessionId]. Use flow_catalog to inspect required inputs before flow_run; flow_status waits for completion. Session/workflow state is isolated per conversation. Prefer bounded tools and exec_job_start for long builds. Never expose hidden transcripts, credentials, or private chain-of-thought.`;
-}
+const instructions = mcpInstructions;
export async function dispatch(req: RpcRequest, scope: Scope, actor?: string, agentContext?: McpAgentContext): Promise<Record<string, unknown>> {
const id = req.id ?? null;
diff --git a/lib/mcp/instructions.test.ts b/lib/mcp/instructions.test.ts
new file mode 100644
index 00000000..9b2ab170
--- /dev/null
+++ b/lib/mcp/instructions.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import {
+ AGENT_BOOTSTRAP_SKILL,
+ AGENT_BOOTSTRAP_STEPS,
+ mcpInstructions,
+ workflowOrientation,
+} from "./instructions";
+
+describe("MSO agent bootstrap instructions", () => {
+ it("keeps a stable seven-step first-call sequence", () => {
+ expect(AGENT_BOOTSTRAP_SKILL).toBe("mso-agent-bootstrap");
+ expect(AGENT_BOOTSTRAP_STEPS.map((step) => step.n)).toEqual([1, 2, 3, 4, 5, 6, 7]);
+ const joined = AGENT_BOOTSTRAP_STEPS.map((step) => `${step.call} ${step.detail}`).join(" ");
+ for (const token of [
+ "skills_search", "projects_list", "workflow_start", "project_capabilities",
+ "project_mcp_tools", "project_mcp_call", "integration_query", "integration_execute",
+ "read_pipeline", "exec_run",
+ ]) expect(joined).toContain(token);
+ expect(joined).not.toMatch(/secret|token|password|api[_-]?key/i);
+ });
+
+ it("advertises the sequence at initialize time without promoting write tools on a read token", () => {
+ const read = mcpInstructions("read");
+ expect(read).toContain(AGENT_BOOTSTRAP_SKILL);
+ expect(read).toContain("skills_search");
+ expect(read).toContain("read-only");
+ expect(read).not.toContain("workflow_start");
+ expect(read).not.toContain("workflow_finish");
+ expect(read).not.toContain("workflow_cancel");
+
+ const exec = mcpInstructions("exec");
+ expect(exec).toContain("workflow_start");
+ expect(exec).toContain("workflow_finish");
+ expect(exec).toContain("workflow_cancel");
+ expect(exec).toContain("read_pipeline");
+ expect(mcpInstructions("exec", "chatgpt")).toContain("project_mcp_tools then project_mcp_call");
+ });
+
+ it("omits workflow_start from read-scope orientation returned by workflow bootstrap", () => {
+ const read = workflowOrientation("read");
+ expect(read.skill).toBe(AGENT_BOOTSTRAP_SKILL);
+ expect(read.steps.some((step) => step.call.includes("workflow_start"))).toBe(false);
+ expect(workflowOrientation("exec").steps.some((step) => step.call.includes("workflow_start"))).toBe(true);
+ });
+});
diff --git a/lib/mcp/instructions.ts b/lib/mcp/instructions.ts
new file mode 100644
index 00000000..a1a0b1b5
--- /dev/null
+++ b/lib/mcp/instructions.ts
@@ -0,0 +1,72 @@
+import type { Scope } from "./scope";
+import type { McpToolProfile } from "./tool-contract";
+
+/** Official orientation skill. Keep this id stable: MCP `skills_search` and ChatGPT publication both use it. */
+export const AGENT_BOOTSTRAP_SKILL = "mso-agent-bootstrap";
+
+export type AgentBootstrapStep = {
+ n: number;
+ call: string;
+ when: string;
+ detail: string;
+};
+
+/** Canonical first-call sequence. Presentation may differ by surface; this order does not. */
+export const AGENT_BOOTSTRAP_STEPS: readonly AgentBootstrapStep[] = [
+ { n: 1, call: "skills_search|skills_read", when: "Learn the map", detail: `Query or read official skill ${AGENT_BOOTSTRAP_SKILL} before expensive mutations.` },
+ { n: 2, call: "projects_list", when: "Project unresolved", detail: "Resolve id/path/alias; do not guess across roots." },
+ { n: 3, call: "workflow_start", when: "Multi-step work", detail: "Call once; pass exact workflow_id on every later operation." },
+ { n: 4, call: "project_capabilities→project_mcp_tools→project_mcp_call", when: "Project MCP", detail: "Keep discover and call as two tools; never copy project names into the global catalog." },
+ { n: 5, call: "integration_query→setup/verify→integration_execute", when: "Credentials", detail: "Never put secrets in chat or tool arguments." },
+ { n: 6, call: "read_pipeline|bounded reads", when: "Inspect", detail: "Prefer these before exec_run." },
+ { n: 7, call: "bounded infra + confirm", when: "Mutate infra", detail: "Doctor/health first; mutations need confirm." },
+];
+
+export function formatAgentBootstrapSteps(scope: Scope = "exec"): string {
+ const steps = scope === "read"
+ ? AGENT_BOOTSTRAP_STEPS.filter((step) => step.n !== 3)
+ : AGENT_BOOTSTRAP_STEPS;
+ return steps.map((step) => `${step.n}) ${step.call} (${step.when}: ${step.detail})`).join(" ");
+}
+
+export function workflowOrientation(scope: Scope = "exec") {
+ const steps = scope === "read"
+ ? AGENT_BOOTSTRAP_STEPS.filter((step) => step.n !== 3)
+ : AGENT_BOOTSTRAP_STEPS;
+ return {
+ skill: AGENT_BOOTSTRAP_SKILL,
+ scope,
+ steps,
+ finish: scope === "read"
+ ? "Read-only tokens cannot start or finish workflows; stay on bounded reads."
+ : "After independent verification call workflow_finish with this exact workflow_id; abandon with workflow_cancel.",
+ };
+}
+
+export function workflowStartPolicy(classification: { risk: string; isolation: string }) {
+ return {
+ simple: "LOW-risk work may run directly with a targeted check; branch/worktree is a safety tool, not a goal.",
+ isolation: classification.risk === "high"
+ ? "HIGH-risk work requires isolation plus explicit verification before integration."
+ : classification.isolation === "optional-worktree"
+ ? "Use a short-lived branch/worktree when it reduces current contention."
+ : "Direct work is acceptable when scope remains isolated.",
+ repository: "For short repository-wide search/git checks use one narrow exec_run batch; for tests/builds that may exceed 30 seconds use exec_job_start and poll exec_job_status.",
+ progress: "Show only high-level feature/tool badges and outcomes; never private chain-of-thought.",
+ manualUserTest: "When the user reports a manual test result, persist it with project_memory_upsert source=user-manual; a failed manual test outranks an automated healthy assumption.",
+ finish: "Call workflow_finish with this exact workflow id only after independent verification; new HIGH-risk workflows require structured evidence. Use workflow_cancel for an abandoned run.",
+ };
+}
+
+export function mcpInstructions(scope: Scope, profile: McpToolProfile = "full", allowedTools?: readonly string[]): string {
+ const bootstrap = formatAgentBootstrapSteps(scope);
+ const startup = allowedTools
+ ? `This machine token is restricted to: ${allowedTools.join(", ")}.`
+ : scope === "read"
+ ? `This token is read-only. MSO agent bootstrap: ${bootstrap} Multi-step mutation tools are unavailable at this scope.`
+ : `MSO agent bootstrap: ${bootstrap} Then verify and workflow_finish, or workflow_cancel.`;
+ const projectBoundary = profile === "chatgpt"
+ ? " Project-owned MCP tools never join this catalog: use project_mcp_tools then project_mcp_call."
+ : "";
+ return `${startup}${projectBoundary} Call agent_session_open for provider-neutral sessions, then send params._meta[mso/sessionId]. Use flow_catalog to inspect required inputs before flow_run; flow_status waits for completion. Session/workflow state is isolated per conversation. Prefer bounded tools and exec_job_start for long builds. Never expose hidden transcripts, credentials, or private chain-of-thought.`;
+}
diff --git a/lib/mcp/skills-extension.test.ts b/lib/mcp/skills-extension.test.ts
index c1fc908d..db53c751 100644
--- a/lib/mcp/skills-extension.test.ts
+++ b/lib/mcp/skills-extension.test.ts
@@ -11,6 +11,8 @@ describe("MCP Skills extension", () => {
const listed = await dispatch({ id: 2, method: "skills/list", params: {} }, "read", "skills-test");
const skills = (listed.result as { skills: Array<{ uri: string; frontmatter: Record<string, unknown>; resources: Array<{ uri: string; digest: string }> }>; nextCursor?: string }).skills;
expect(skills).toHaveLength(5);
+ expect(CHATGPT_PUBLISHED_SKILLS[0]).toBe("mso-agent-bootstrap");
+ expect(CHATGPT_PUBLISHED_SKILLS).toHaveLength(5);
expect(skills.map((skill) => skill.frontmatter.name)).toEqual([...CHATGPT_PUBLISHED_SKILLS]);
expect((listed.result as { nextCursor?: string }).nextCursor).toBeUndefined();
for (const skill of skills) {
diff --git a/lib/mcp/skills-extension.ts b/lib/mcp/skills-extension.ts
index 7a4936f1..9347db55 100644
--- a/lib/mcp/skills-extension.ts
+++ b/lib/mcp/skills-extension.ts
@@ -10,12 +10,13 @@ export const MCP_SKILL_SCHEME = "skill:";
// OpenAI currently imports at most five skills. Keep this as a deliberately small
// operator syllabus rather than exposing project/local/untrusted instructions.
+// mso-agent-bootstrap is first so a partial ChatGPT import still gets the first-call map.
export const CHATGPT_PUBLISHED_SKILLS = [
+ "mso-agent-bootstrap",
"mso",
"mso-repo-work",
"mso-service-debug",
"mso-deploy",
- "mso-mcp-feature-engineering",
] as const;
const SERVER_NAMESPACE = "mso";
diff --git a/lib/mcp/tools-discovery.ts b/lib/mcp/tools-discovery.ts
index 277b400f..5ab6d950 100644
--- a/lib/mcp/tools-discovery.ts
+++ b/lib/mcp/tools-discovery.ts
@@ -50,9 +50,11 @@ export const DISCOVERY_TOOLS: McpTool[] = [
"Enumerate the owner's projects across EVERY configured project container (each OS_FS_READ_ROOTS entry and its projects/ subdirectory), not just ~/projects. " +
"Returns a globally unique id (<rootId>/<name>, so two roots may hold a project of the same name), absolute path, its container root, package name/version, bounded Git branch/head, and opt-in MCP/function capability summary. " +
"USE THIS FIRST when the user names a project you have not located — it is one call, needs no shell scope, and its id or path is the input to workflow_start. " +
+ "After orientation (mso-agent-bootstrap), this is the project-resolution step. " +
"Hidden directories, symlinks, credential paths and directories not owned by the MSO user are excluded. " +
"ALWAYS check `scan.truncated`: when true the listing is incomplete and `scan.truncationReasons` says which cap was hit — do not report that a project is absent from a truncated scan. " +
"Every cap is resumable: pass `scan.continuation.cursor` back as `cursor` to continue, and use `nextOffset`/`hasMore` for ordinary paging within one scan.",
+ chatgptDescription: "Resolve project before workflow_start or MCP calls.",
scope: "read",
annotations: READ_ONLY,
limit: { key: "projects.list", max: 30, windowMs: 60_000 },
diff --git a/lib/mcp/tools-infra.ts b/lib/mcp/tools-infra.ts
index aadae0c3..41e9f322 100644
--- a/lib/mcp/tools-infra.ts
+++ b/lib/mcp/tools-infra.ts
@@ -22,7 +22,8 @@ const BASE_INFRA_TOOLS: McpTool[] = [
},
{
name: "infra_provider_doctor",
- description: "Live-check one configured infrastructure provider against its real API. Use infra_providers_list first. Tokens are read from MSO private state and never passed in tool arguments.",
+ description: "Live-check one configured infrastructure provider against its real API. Use infra_providers_list first. Tokens are read from MSO private state and never passed in tool arguments. Doctor/health before mutating infra.",
+ chatgptDescription: "Live-check one provider; never pass tokens.",
scope: "read",
annotations: { readOnlyHint: true, openWorldHint: true },
inputSchema: S({ id: { type: "string", enum: [...INFRA_PROVIDER_IDS] } }, ["id"]),
diff --git a/lib/mcp/tools-learning.test.ts b/lib/mcp/tools-learning.test.ts
index e946dd95..10f6e2c6 100644
--- a/lib/mcp/tools-learning.test.ts
+++ b/lib/mcp/tools-learning.test.ts
@@ -68,6 +68,7 @@ describe("workflow_start bootstrap", () => {
repository: { package: { name?: string; version?: string; scripts: string[] }; git: { statusChecked: boolean } };
toolset: { toolCount: number; names: string[]; hash: string };
trace: string[];
+ orientation: { skill: string; scope: string; steps: Array<{ n: number; call: string }> };
};
search: { hits: Array<{ kind: string; name: string; trust?: string }> };
};
@@ -84,8 +85,14 @@ describe("workflow_start bootstrap", () => {
expect(result.bootstrap.trace).toEqual(expect.arrayContaining([
expect.stringContaining("[MSO]"),
expect.stringContaining("[Project]"),
+ expect.stringContaining("[Orient]"),
expect.stringContaining("[Plan]"),
]));
+ expect(result.bootstrap.orientation).toMatchObject({
+ skill: "mso-agent-bootstrap",
+ scope: "write",
+ });
+ expect(result.bootstrap.orientation.steps.map((step: { n: number }) => step.n)).toEqual([1, 2, 3, 4, 5, 6, 7]);
expect(result.search.hits).toEqual(expect.arrayContaining([
expect.objectContaining({ kind: "skill", name: "mso-repo-work", trust: "official" }),
]));
diff --git a/lib/mcp/tools-mutate.ts b/lib/mcp/tools-mutate.ts
index 788c6fa0..54a64554 100644
--- a/lib/mcp/tools-mutate.ts
+++ b/lib/mcp/tools-mutate.ts
@@ -203,9 +203,11 @@ export const MUTATE_TOOLS: McpTool[] = [
},
description:
"Run a shell command on the VPS as the owner and return stdout, stderr and exit code. " +
+ "Do not use this as the first call: start multi-step work with workflow_start and prefer bounded reads or read_pipeline. " +
"FULL HOST POWER — prefer fs_* and sys_* tools whenever they cover the task; they are bounded and " +
"this is not. Catastrophic patterns (rm -rf /, fork bombs, disk wipes) are refused by the server. " +
"Long-running or interactive commands will time out: this is not a terminal session.",
+ chatgptDescription: "Last resort shell; prefer reads/read_pipeline first.",
scope: "exec",
annotations: { destructiveHint: true, openWorldHint: true },
result: { maxTextBytes: 48 * 1024, overflowHint: "Command output was compacted; rerun a narrower command (grep/head/tail) for the omitted evidence." },
diff --git a/lib/mcp/tools-read-pipeline.ts b/lib/mcp/tools-read-pipeline.ts
index 92c31a5e..6a38de96 100644
--- a/lib/mcp/tools-read-pipeline.ts
+++ b/lib/mcp/tools-read-pipeline.ts
@@ -22,7 +22,8 @@ export const READ_PIPELINE_TOOLS: McpTool[] = [{
name: "read_pipeline",
description:
"Execute 1-6 independent READ-ONLY MSO tool calls server-side, then deterministically filter/project/sort/unique/limit/aggregate their results before returning them to the model. " +
- "Use this when several reads can be batched or raw lists/log metadata would waste context. It cannot call write/exec tools, workflow_status, screenshots, wait/poll tools, arbitrary code, shell, or nested pipelines. Child calls inherit this session/workflow and retain their own rate limits.",
+ "Prefer this over exec_run when several reads can be batched or raw lists/log metadata would waste context. It cannot call write/exec tools, workflow_status, screenshots, wait/poll tools, arbitrary code, shell, or nested pipelines. Child calls inherit this session/workflow and retain their own rate limits.",
+ chatgptDescription: "Batch bounded reads before jumping to exec_run.",
scope: "read",
annotations: { readOnlyHint: true, idempotentHint: true },
limit: { key: "read.pipeline", max: 30, windowMs: 60_000 },
diff --git a/lib/mcp/tools-read.ts b/lib/mcp/tools-read.ts
index a930e141..dc5adfe7 100644
--- a/lib/mcp/tools-read.ts
+++ b/lib/mcp/tools-read.ts
@@ -119,8 +119,9 @@ export const READ_TOOLS: McpTool[] = [
name: "skills_search",
description:
"Semantic search across trusted SKILL.md files, the live MCP tool catalog and learned successful workflows. " +
- "Use this alone for capability research or unfamiliar single-step work. For a multi-step task call workflow_start directly — it already performs this search and avoids a duplicate startup call. " +
+ "For MCP orientation, query mso-agent-bootstrap. Use this alone for capability research or unfamiliar single-step work. For a multi-step task call workflow_start directly — it already performs this search and avoids a duplicate startup call. " +
"The embedding runs locally with no API cost; untrusted skill instructions are excluded unless explicitly requested.",
+ chatgptDescription: "Find mso-agent-bootstrap or research capabilities.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({
diff --git a/lib/mcp/tools-workflow-start.ts b/lib/mcp/tools-workflow-start.ts
index 1bae6c36..7d436e22 100644
--- a/lib/mcp/tools-workflow-start.ts
+++ b/lib/mcp/tools-workflow-start.ts
@@ -13,11 +13,13 @@ import type { McpTool } from "./tool-kit";
import { opt, S, str } from "./tool-kit";
import { toolsetInfo } from "./toolset";
import { optionalStringList, visibleTools, WORKFLOW_PROGRESS_OUTPUT, workflowProgress } from "./tools-learning-shared";
+import { AGENT_BOOTSTRAP_SKILL, workflowOrientation, workflowStartPolicy } from "./instructions";
export const WORKFLOW_START_TOOL: McpTool =
{
name: "workflow_start",
- description: "Start one isolated multi-step workflow, resolve project context, and search trusted skills/recipes/graphs. Use the returned workflow_id on later steps.",
+ description: "First call for multi-step work: resolve project context, search trusted skills/recipes/graphs, and return workflow_id. Carry that exact id on later steps. Read official skill mso-agent-bootstrap when learning the MSO map.",
+ chatgptDescription: "First call for multi-step work; keep workflow_id.",
scope: "write",
annotations: { idempotentHint: false },
outputSchema: WORKFLOW_PROGRESS_OUTPUT,
@@ -197,20 +199,11 @@ export const WORKFLOW_START_TOOL: McpTool =
...(reusableScript ? [`[Automation] ${reusableScript.status} script ${reusableScript.id} available`] : []),
...(contention.conflictingWorkflowCount ? [`[Collision] ${contention.conflictingWorkflowCount} workflow(s) overlap declared paths/resources`] : []),
...(discovery.complete ? [] : [`[Discovery] partial scan — ${search.catalog.truncationReasons.join(", ")}; do not conclude something is absent`]),
+ `[Orient] follow ${AGENT_BOOTSTRAP_SKILL} then the discover→act loop`,
"[Plan] classify → retrieve minimal memory → isolate if required → execute → progressive verify → learn → workflow_finish",
],
- policy: {
- simple: "LOW-risk work may run directly with a targeted check; branch/worktree is a safety tool, not a goal.",
- isolation: classification.risk === "high"
- ? "HIGH-risk work requires isolation plus explicit verification before integration."
- : classification.isolation === "optional-worktree"
- ? "Use a short-lived branch/worktree when it reduces current contention."
- : "Direct work is acceptable when scope remains isolated.",
- repository: "For short repository-wide search/git checks use one narrow exec_run batch; for tests/builds that may exceed 30 seconds use exec_job_start and poll exec_job_status.",
- progress: "Show only high-level feature/tool badges and outcomes; never private chain-of-thought.",
- manualUserTest: "When the user reports a manual test result, persist it with project_memory_upsert source=user-manual; a failed manual test outranks an automated healthy assumption.",
- finish: "Call workflow_finish with this exact workflow id only after independent verification; new HIGH-risk workflows require structured evidence. Use workflow_cancel for an abandoned run.",
- },
+ orientation: workflowOrientation(context.scope),
+ policy: workflowStartPolicy(classification),
},
search: compactSearch,
instruction: "Use the smallest useful returned memory context and any safe recipe. Follow the risk/isolation policy, verify progressively, then call workflow_finish with evidence.",
diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.ts
index 739be7e7..3ef7598a 100644
--- a/lib/mcp/toolset.ts
+++ b/lib/mcp/toolset.ts
@@ -4,8 +4,8 @@ import type { McpTool } from "./tool-kit";
import { toolDescriptor, type McpToolProfile } from "./tool-contract";
export const MCP_SERVER_VERSION = "1.15.1";
-export const MCP_TOOLSET_VERSION = "2026.09.18.1";
-export const MCP_TOOLSET_CHANGED_AT = "2026-09-18T07:18:00+07:00";
+export const MCP_TOOLSET_VERSION = "2026.09.19.1";
+export const MCP_TOOLSET_CHANGED_AT = "2026-09-19T15:00:00+07:00";
export type McpToolsetInfo = {
serverVersion: string;
diff --git a/lib/orchestration/capability-catalog.mjs b/lib/orchestration/capability-catalog.mjs
index f5f97da8..887d5332 100644
--- a/lib/orchestration/capability-catalog.mjs
+++ b/lib/orchestration/capability-catalog.mjs
@@ -1,4 +1,8 @@
const ROUTES = [
+ { id: "agent-bootstrap", priority: 108, patterns: [
+ /\b(mso-agent-bootstrap|agent bootstrap|mcp bootstrap|orient(?:ation)? sequence|first tools? to call|how (?:does|do i) (?:mso|this mcp) work|cara pakai mso(?:\s+mcp)?)\b/i,
+ /\b(capability parity|maximal mso capabilities)\b/i,
+ ], tools: ["skills_search", "skills_read"], budget: 10_000 },
{ id: "automation-flow", priority: 105, patterns: [/\b(automation flow|workflow graph|workflow|flow_catalog|flow_run|mso flow|reusable flow|alur otomatis|otomasi provider|n8n)\b/i], tools: ["workflow_graph", "flow_catalog", "flow_run", "flow_status", "flow_manage", "integration_query"], budget: 12_000 },
{ id: "project-mcp-add", priority: 105, patterns: [/\b(add|connect|tambah|pasang)\b.{0,30}\bmcp\b/i], tools: ["project_mcp_manage", "project_mcp_tools", "integration_query", "integration_setup_open"], budget: 10_000 },
{ id: "project-asset", priority: 105, patterns: [/\b(attach|save|kirim|simpan)\b.{0,40}\b(asset|image|gambar)\b.{0,30}\b(project|proyek)\b/i], tools: ["session_artifacts", "project_asset_attach"], budget: 8_000 },
diff --git a/scripts/mso-agent-runtime.mjs b/scripts/mso-agent-runtime.mjs
index 05b65bb0..9448e572 100644
--- a/scripts/mso-agent-runtime.mjs
+++ b/scripts/mso-agent-runtime.mjs
@@ -39,7 +39,7 @@ function sessionSystem(agentSession, skillContext = null) {
"For setup, inspect the native Integrations connection model and use bounded provider checks when an operation needs them; credential users, providers, named connections, sources, and auth belong to one Integrations surface.",
"Credentials are entered through the private native `mso integrations` setup flow and are never exposed to you; never ask the user to paste API tokens into chat or shell commands. `/provider` and `/providers` are legacy compatibility aliases, not the product-facing setup surface.",
"Use dokploy_* and cloudflare_*/hostinger_* tools after the user has configured those providers. Cloudflare DNS must remain per-record and DNS-only unless the user explicitly asks for proxying.",
- "If multiple operational calls are needed, use workflow_start, pass its workflow_id to later calls, follow its risk/isolation guidance, verify progressively, then workflow_finish with concrete evidence. If the task is abandoned, workflow_cancel.",
+ "If multiple operational calls are needed, use workflow_start, pass its workflow_id to later calls, follow its risk/isolation guidance, verify progressively, then workflow_finish with concrete evidence. If the task is abandoned, workflow_cancel. Official orientation skill: mso-agent-bootstrap.",
"When the user reports a manual test outcome (for example still frozen, fixed, pass, or failed), persist that observation with project_memory_upsert using source=user-manual. Never let an automated pass silently override a newer failed manual user test.",
"Write and exec tools may be denied by the user's approval prompt. Never retry a denied call unchanged.",
"USER.md and MEMORY.md below are a frozen snapshot captured when this MSO session started. Do not silently live-refresh them during this session. Never store secrets in agent memory.",
diff --git a/scripts/mso-agent-tool-router.test.ts b/scripts/mso-agent-tool-router.test.ts
index 0c8191af..08a00028 100644
--- a/scripts/mso-agent-tool-router.test.ts
+++ b/scripts/mso-agent-tool-router.test.ts
@@ -52,6 +52,14 @@ describe("MSO per-turn tool router", () => {
expect(out.selectedNames).toContain("skills_search");
});
+ it("routes MCP orientation prompts to the agent-bootstrap pack instead of exec_run", () => {
+ const out = selectToolsForTurn(catalog, [{ role: "user", text: "How does MSO MCP work? What are the first tools to call?" }]);
+ expect(out.routeIds).toContain("agent-bootstrap");
+ expect(out.selectedNames).toEqual(expect.arrayContaining(["skills_search", "skills_read"]));
+ expect(out.selectedNames).not.toContain("exec_run");
+ expect(out.catalogMatched).toBe(true);
+ });
+
it("uses only bounded continuation context instead of replaying long history into routing", () => {
const history = [
{ role: "user", text: "why is hermes down? inspect its logs" },
diff --git a/skills/README.md b/skills/README.md
index 9499c939..5d8fbb9e 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -113,7 +113,10 @@ and minor typos without a cloud embedding API. Untrusted skill instructions rema
excluded by default.
A multi-step MCP client can bracket work with `workflow_start` and
-`workflow_finish`. MSO records only redacted terminal tool steps, explicitly allowlisted scalar
+`workflow_finish`. The first-call map is official skill `mso-agent-bootstrap`
+([`docs/AGENT-BOOTSTRAP.md`](../docs/AGENT-BOOTSTRAP.md)). `workflow_start` already
+searches this catalog, so do not call `skills_search` immediately before startup
+for the same task. MSO records only redacted terminal tool steps, explicitly allowlisted scalar
arguments, timings and the verified outcome in `~/.mso/skill-memory.json`, merges semantically equivalent
intents, and retains the fastest successful sequence as a future recipe. Failed
attempts remain evidence but never replace a successful path. Recipes are ranked