docs(guides): add adoption guides for cli, rest, and mcp

Author: kryptobaseddev

.cleo/tasks.db

@@ -37,6 +37,9 @@
 * [LLM Agent Guide](guides/llm-agent-guide.md)
 * [Schema Extension Guide](guides/schema-extension.md)
 * [Compliance Pipeline Guide](guides/compliance-pipeline.md)
+* [LAFS for CLI Tools](guides/lafs-for-cli.md)
+* [LAFS for REST APIs](guides/lafs-for-rest.md)
+* [LAFS for MCP Tool Servers](guides/lafs-for-mcp.md)
 
 ## Implementation Guides
 

docs/SUMMARY.md

@@ -0,0 +1,58 @@
+# LAFS for CLI Tools
+
+Use LAFS envelopes to make CLI output deterministic for scripts and agents.
+
+## Producer pattern
+
+```typescript
+import { createEnvelope, enforceCompliance } from "@cleocode/lafs-protocol";
+
+export function buildCliEnvelope(requestId: string) {
+  const envelope = createEnvelope({
+    success: true,
+    result: { items: ["a", "b"] },
+    meta: {
+      operation: "cli.items.list",
+      requestId,
+      transport: "cli",
+      strict: true,
+      mvi: "standard",
+      contextVersion: 0,
+    },
+  });
+
+  const gate = enforceCompliance(envelope, {
+    checkConformance: true,
+    requireJsonOutput: true,
+    flags: { jsonFlag: true },
+  });
+
+  if (!gate.ok) {
+    throw new Error(JSON.stringify(gate.issues));
+  }
+
+  return envelope;
+}
+```
+
+## Consumer pattern
+
+```typescript
+import { LafsError, parseLafsResponse } from "@cleocode/lafs-protocol";
+
+try {
+  const result = parseLafsResponse<{ items: string[] }>(envelopeJson);
+  console.log(result.items.length);
+} catch (error) {
+  if (error instanceof LafsError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+## Diagnostic checks
+
+```bash
+lafs-conformance --envelope ./envelope.json
+lafs-conformance --flags ./flags.json
+```

docs/guides/lafs-for-cli.md

@@ -0,0 +1,34 @@
+# LAFS for MCP Tool Servers
+
+For MCP servers, normalize `CallToolResult` into LAFS envelopes.
+
+## Wrapper pattern
+
+```typescript
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { enforceCompliance, wrapMCPResult } from "@cleocode/lafs-protocol";
+
+export function wrapToolResult(result: CallToolResult, toolName: string) {
+  const envelope = wrapMCPResult(result, `tools/${toolName}`);
+
+  const gate = enforceCompliance(envelope, { checkConformance: true });
+  if (!gate.ok) {
+    throw new Error(JSON.stringify(gate.issues));
+  }
+
+  return envelope;
+}
+```
+
+## Parse downstream
+
+```typescript
+import { parseLafsResponse } from "@cleocode/lafs-protocol";
+
+const payload = parseLafsResponse(envelope);
+```
+
+## Notes
+
+- `wrapMCPResult` converts MCP content/error signals into the LAFS success/error model.
+- Keep transport details in `_extensions`; keep core semantics in envelope fields.

docs/guides/lafs-for-mcp.md

@@ -0,0 +1,57 @@
+# LAFS for REST APIs
+
+Adopt LAFS at HTTP boundaries so every endpoint returns one parseable shape.
+
+## Express example
+
+```typescript
+import crypto from "node:crypto";
+import express from "express";
+import { createEnvelope, enforceCompliance } from "@cleocode/lafs-protocol";
+
+const app = express();
+
+app.get("/api/users", (_req, res) => {
+  const envelope = createEnvelope({
+    success: true,
+    result: { users: [] },
+    meta: {
+      operation: "users.list",
+      requestId: crypto.randomUUID(),
+      transport: "http",
+      strict: true,
+      mvi: "standard",
+      contextVersion: 0,
+    },
+  });
+
+  const gate = enforceCompliance(envelope, { checkConformance: true });
+  if (!gate.ok) {
+    res.status(500).json({ issues: gate.issues });
+    return;
+  }
+
+  res.json(envelope);
+});
+```
+
+## Error response pattern
+
+```typescript
+import { createEnvelope } from "@cleocode/lafs-protocol";
+
+const errorEnvelope = createEnvelope({
+  success: false,
+  error: {
+    code: "E_NOT_FOUND_RESOURCE",
+    message: "user not found",
+    category: "NOT_FOUND",
+    retryable: false,
+  },
+  meta: {
+    operation: "users.get",
+    requestId: "req_123",
+    transport: "http",
+  },
+});
+```