chore: Improve token efficience

README.md

@@ -109,6 +109,40 @@ This interactive command:
 - Includes dry-run mode to preview changes
 - Works with Claude Code, Cursor, Windsurf, Codex, Continue.dev, and more
 
+### Compact Profiles
+
+dotcontext now ships a compact-first MCP contract. Workflow handlers return machine-first state by default, while onboarding/tutorial payloads stay available through explicit flags such as `verbose`, `includeGuidance`, `includeLegacy`, and `includeOrchestration`.
+
+Server profile selection is controlled by `DOTCONTEXT_MCP_PROFILE`:
+
+| Profile | Tool surface | Best for |
+| --- | --- | --- |
+| `standalone` | Full surface | Discovery, onboarding, mixed sessions |
+| `planning` | Planning surface without `sync` | Spec and plan generation |
+| `execution` | Lean PREVC loop | Tight workflow execution |
+
+Aliases `codex` and `claude-code` map to `execution`.
+
+```bash
+DOTCONTEXT_MCP_PROFILE=execution npx dotcontext mcp
+```
+
+Current compact surfaces:
+
+- `workflow-init`, `workflow-advance`, and `workflow-manage` support `verbose`, `includeGuidance`, and `includeLegacy`
+- `workflow-status` also supports `revision`, `notModified`, and `includeOrchestration`
+- `context` supports `verbose`, `includeGuidance`, and `includeContent` for inline planning payloads
+- Help resources are available at `workflow://guide/{topic}` for `overview`, `profiles`, `workflow-init`, `workflow-status`, `workflow-advance`, and `workflow-manage`
+
+Current benchmark snapshot from `node scripts/benchmark-mcp-efficiency.js` after `npm run build`:
+
+| Scenario | Compact est. tokens | Compatibility est. tokens | Non-MCP fixture | Compact delta |
+| --- | ---: | ---: | ---: | ---: |
+| Planning | 311 | 3508 | 523 | -91.1% vs compatibility / -40.5% vs non-MCP |
+| Workflow loop | 366 | 3464 | 441 | -89.4% vs compatibility / -17.0% vs non-MCP |
+
+Benchmark artifacts and raw payload examples live in [docs/benchmarks/mcp-token-efficiency/README.md](./docs/benchmarks/mcp-token-efficiency/README.md). A narrative summary lives in [docs/mcp-token-efficiency.md](./docs/mcp-token-efficiency.md).
+
 ### Manual Configuration
 
 Alternatively, manually configure for your preferred tool.
@@ -257,6 +291,9 @@ Add to your Codex CLI config (`~/.codex/config.toml`):
 [mcp_servers.dotcontext]
 command = "npx"
 args = ["--yes", "@dotcontext/cli@latest", "mcp"]
+
+[mcp_servers.dotcontext.env]
+DOTCONTEXT_MCP_PROFILE = "execution"
 ```
 
 ### Google Antigravity

docs/benchmarks/mcp-token-efficiency/README.md

@@ -0,0 +1,40 @@
+# MCP Token Efficiency Report
+
+Generated: 2026-03-22T06:10:43.006Z
+
+## Scenario Summary
+
+| Scenario | Current MCP (legacy) | Optimized MCP (compact) | Non-MCP fixture | Compact vs legacy | Compact vs non-MCP |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Planning | 3508 | 311 | 523 | -91.1% | -40.5% |
+| Workflow loop | 3464 | 366 | 441 | -89.4% | -17.0% |
+
+## Tool Surface
+
+| Profile | Registered tools | Notes |
+| --- | ---: | --- |
+| `standalone` | 10 | Full onboarding, planning, sync, workflow, and skills surface |
+| `planning` | 9 | Drops `sync` but keeps planning and orchestration tools |
+| `execution` | 6 | Keeps the hot path: workflow tools, `plan`, and `explore` |
+
+## Payload Benchmarks
+
+| Payload | Mode | Bytes | Chars | Est. tokens | Delta vs legacy |
+| --- | --- | ---: | ---: | ---: | ---: |
+| getCodebaseMap | compact | 388 | 388 | 97 | -31.2% |
+| scaffoldPlan | compact | 853 | 853 | 214 | -93.6% |
+| getCodebaseMap | legacy | 563 | 563 | 141 | baseline |
+| scaffoldPlan | legacy | 13472 | 13466 | 3367 | baseline |
+| workflow-init | compact | 510 | 510 | 128 | -90.1% |
+| workflow-status | compact | 616 | 616 | 154 | -84.8% |
+| workflow-advance | compact | 335 | 335 | 84 | -92.8% |
+| workflow-status | notModified | 61 | 61 | 16 | -98.4% |
+| workflow-init | legacy | 5149 | 5147 | 1287 | baseline |
+| workflow-status | legacy | 4044 | 4044 | 1011 | baseline |
+| workflow-advance | legacy | 4664 | 4664 | 1166 | baseline |
+
+## Raw Payload Examples
+
+- Compact and legacy payload examples are written to `docs/benchmarks/mcp-token-efficiency/`.
+- `notModified-workflow-status.json` captures the cached polling path when a client sends the current `revision`.
+- The non-MCP baseline remains a checked-in prompt fixture so the comparison stays repeatable without external tooling.

docs/benchmarks/mcp-token-efficiency/compact-getCodebaseMap.json

@@ -0,0 +1,29 @@
+{
+  "success": true,
+  "section": "architecture",
+  "defaultSectionApplied": true,
+  "explicitAllHint": "Request section: \"all\" only when you need the full map payload.",
+  "data": {
+    "layers": [
+      {
+        "name": "CLI",
+        "directories": [
+          "src"
+        ],
+        "dependsOn": [
+          "services"
+        ]
+      },
+      {
+        "name": "MCP",
+        "directories": [
+          "src/services/mcp"
+        ],
+        "dependsOn": [
+          "workflow"
+        ]
+      }
+    ]
+  },
+  "mapPath": "/tmp/planning-benchmark-DQHJj0/.context/docs/codebase-map.json"
+}

docs/benchmarks/mcp-token-efficiency/compact-scaffoldPlan.json

@@ -0,0 +1,24 @@
+{
+  "instruction": "Plan template created. Fill it with project-specific details via context({ action: \"fillSingle\", filePath: \"/tmp/planning-benchmark-DQHJj0/.context/plans/compact-plan.md\" }).",
+  "_warning": "ACTION REQUIRED",
+  "status": "incomplete",
+  "complete": false,
+  "success": true,
+  "planPath": "/tmp/planning-benchmark-DQHJj0/.context/plans/compact-plan.md",
+  "contentIncluded": false,
+  "guidanceIncluded": false,
+  "contextType": "plan",
+  "contextResource": "context://codebase/plan",
+  "classification": {
+    "projectType": "unknown",
+    "confidence": "low",
+    "reasoning": [
+      "Unable to determine project type from detected stack",
+      "Primary language: typescript"
+    ]
+  },
+  "nextStep": {
+    "action": "Call fillSingle to get plan-scoped context, then write the completed plan",
+    "example": "context({ action: \"fillSingle\", filePath: \"/tmp/planning-benchmark-DQHJj0/.context/plans/compact-plan.md\" })"
+  }
+}

docs/benchmarks/mcp-token-efficiency/compact-workflow-advance.json

@@ -0,0 +1,13 @@
+{
+  "success": true,
+  "profile": "standalone",
+  "currentPhase": {
+    "code": "R",
+    "name": "Review"
+  },
+  "startWith": "architect-specialist",
+  "bundleId": "0312c9dc1d11",
+  "nextAction": "Start architect-specialist for Review phase",
+  "hint": "Begin with architect-specialist, then hand off or call workflow-advance when Review is complete.",
+  "revision": "0aa8bbf55219"
+}

docs/benchmarks/mcp-token-efficiency/compact-workflow-init.json

@@ -0,0 +1,21 @@
+{
+  "success": true,
+  "name": "benchmark-execution",
+  "scale": "Medium",
+  "currentPhase": {
+    "code": "P",
+    "name": "Planning"
+  },
+  "settings": {
+    "autonomous_mode": true,
+    "require_plan": true,
+    "require_approval": true
+  },
+  "startWith": "architect-specialist",
+  "bundleId": "74e1bc42f8a4",
+  "nextAction": "Start architect-specialist for Planning phase",
+  "hint": "Begin with architect-specialist, then hand off or call workflow-advance when Planning is complete.",
+  "helpRef": "workflow://guide/workflow-init",
+  "profile": "standalone",
+  "revision": "e620f1cb64b5"
+}

docs/benchmarks/mcp-token-efficiency/compact-workflow-status.json

@@ -0,0 +1,49 @@
+{
+  "success": true,
+  "name": "benchmark-execution-legacy",
+  "scale": "Medium",
+  "profile": "standalone",
+  "currentPhase": {
+    "code": "P",
+    "name": "Planning"
+  },
+  "progress": {
+    "completed": 0,
+    "total": 4,
+    "percentage": 0
+  },
+  "isComplete": false,
+  "phases": [
+    {
+      "code": "P",
+      "name": "Planning",
+      "status": "in_progress",
+      "startedAt": "2026-03-22T06:10:42.931Z"
+    },
+    {
+      "code": "R",
+      "name": "Review",
+      "status": "pending"
+    },
+    {
+      "code": "E",
+      "name": "Execution",
+      "status": "pending"
+    },
+    {
+      "code": "V",
+      "name": "Validation",
+      "status": "pending"
+    }
+  ],
+  "activeAgents": [],
+  "gates": {
+    "canAdvance": true
+  },
+  "approval": {
+    "planCreated": false,
+    "planApproved": false
+  },
+  "bundleId": "74e1bc42f8a4",
+  "revision": "879c16d404c4"
+}

docs/benchmarks/mcp-token-efficiency/legacy-getCodebaseMap.json

@@ -0,0 +1,54 @@
+{
+  "success": true,
+  "section": "all",
+  "defaultSectionApplied": false,
+  "data": {
+    "stack": {
+      "runtime": "node",
+      "language": "typescript"
+    },
+    "structure": {
+      "root": [
+        "src",
+        ".context"
+      ]
+    },
+    "architecture": {
+      "layers": [
+        {
+          "name": "CLI",
+          "directories": [
+            "src"
+          ],
+          "dependsOn": [
+            "services"
+          ]
+        },
+        {
+          "name": "MCP",
+          "directories": [
+            "src/services/mcp"
+          ],
+          "dependsOn": [
+            "workflow"
+          ]
+        }
+      ]
+    },
+    "symbols": {
+      "classes": [],
+      "interfaces": [],
+      "functions": [],
+      "types": [],
+      "enums": []
+    },
+    "publicAPI": [],
+    "dependencies": [],
+    "stats": {
+      "files": 2
+    },
+    "keyFiles": [],
+    "navigation": {}
+  },
+  "mapPath": "/tmp/planning-benchmark-DQHJj0/.context/docs/codebase-map.json"
+}