@renanlido/tia-openness-mcp 1.1.1 → 1.3.0

package/README.md

@@ -16,6 +16,27 @@ publicado no **npm público** via **semantic-release** — rode com um one-liner
 npx -y @renanlido/tia-openness-mcp
 ```
 
+## Operating guide embedded (tia_guide)
+
+The harness operating guide ships **inside the MCP itself**, in three layers:
+
+1. **Server `instructions`** — the always-on operating brief (`content/brief.md`) travels in the
+   MCP handshake (`instructions` field). Any client that honors `instructions` (Claude Code,
+   Claude Desktop, ...) gets the gates/serial-only/pipeline rules automatically, with zero setup.
+2. **`tia_guide(topic)`** — a tool that returns the bundled guide chapters on demand:
+   `toc` (default) | `full` | `brief` | `gates-guards` | `gui-gates` | `gotchas` | `pipeline` |
+   `recipes` | `spec-format`. Call it with `{"topic":"pipeline"}` before the first build on a
+   project, and `{"topic":"gui-gates"}` when a tool returns `requires_human_action` or a compile
+   error mentions a GUI-only setting.
+3. **Teaching errors on gate signals** — gate responses (`requires_human_action`, the
+   `guiGateHints` on compile results, etc.) carry the relevant next steps inline, so the guide
+   reinforces itself at the moment a gate is actually hit, not only up front.
+
+`tia_guide` is **pure and offline**: it never calls the `serve` API and never returns `isError` —
+unlike every other tool in this package, it works **even with the `serve` down**. The chapters are
+generated from `mcp/content/*.md` (the canonical source) into `src/content.gen.ts` via
+`npm run sync` — see [scripts/sync-guide.mjs](scripts/sync-guide.mjs).
+
 ## Tools
 
 ### Diagnóstico + M1 read-only (classe R, auto-aprováveis)
@@ -23,6 +44,7 @@ npx -y @renanlido/tia-openness-mcp
 |---|---|---|
 | `tia_ping` | `GET /health` + `GET /readiness` | Diagnostica conectividade e ATIVAÇÃO do `serve`. `{ base, reachable, activated, latencyMs, hint }`. Ideal p/ Mac→VM. |
 | `tia_readiness` | `GET /readiness` | Prontidão do ambiente **no host do serve** (x64, grupo Windows, PublicAPI, registro, instâncias). |
+| `tia_guide` | — (bundled content, no HTTP call) | Returns the operating guide (see "Operating guide embedded" above). Topics: `toc` (default) \| `full` \| `brief` \| `gates-guards` \| `gui-gates` \| `gotchas` \| `pipeline` \| `recipes` \| `spec-format`. Pure/offline — works with the `serve` down. |
 
 **M1 (read-only, 1:1 com os GET da API):** `tia_instances`, `tia_status`, `tia_projects`, `tia_project_info`,
 `tia_project_languages`, `tia_plcs`, `tia_devices`, `tia_device_tree`, `tia_device_connections`,
@@ -81,7 +103,7 @@ Aceita o **project-spec** estruturado (`docs/TIA-BEST-PRACTICES.md` §13.2; JSON
 - **`tia_spec_plan`** (sem serve): transforma um spec válido na sequência ordenada de operações (subnets→devices→módulos→rede→tags→blocos→compile).
 - **`tia_spec_apply`**: orquestra o build OFFLINE num projeto aberto (valida → G5 → executa serial → compila), **para no 1º erro** e **nunca baixa** (download é o GATE G3, sempre humano). `dryRun:true` devolve o plano.
 
-> **MCP M0–M5 COMPLETO** (~74 tools), **validado em runtime** contra um TIA Portal V21 real (incluindo **deploy em hardware** num S7-1200) e **publicado no npm**. Roadmap e marcos em `docs/ROADMAP.md` §3.
+> **MCP M0–M5 COMPLETO** (76 tools), **validado em runtime** contra um TIA Portal V21 real (incluindo **deploy em hardware** num S7-1200) e **publicado no npm**. Roadmap e marcos em `docs/ROADMAP.md` §3.
 
 ## Configuração (env)