Add Print-OS agent surfaces

Author: repo-pipeline

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "print-os": {
+      "command": "python3",
+      "args": ["tools/print_os_mcp.py"]
+    }
+  }
+}

AGENTS.md

@@ -24,3 +24,15 @@ Success line: “I noticed X, found a better way. The system just got an upgrade
 
 Full recipe: `docs/agent-law/empower-orchestrator.md`.
 <!-- EMPOWER_ORCHESTRATOR:END -->
+
+## Print-OS Agent Surfaces
+
+Before operating the repo, check `llms.txt` and `skills/print-os/SKILL.md`.
+
+Local helpers:
+
+- `python3 tools/print_os_cli.py manifest --format json`
+- `python3 tools/print_os_cli.py job-payload --name "Bracket" --material PLA --width 40 --depth 20 --height 12`
+- `.mcp.json` -> `tools/print_os_mcp.py`
+
+Creating jobs through the CLI or MCP writes to the local running API. Keep that as an explicit operator action.

README.md

@@ -44,6 +44,24 @@ bash scripts/smoke-test.sh
 
 For exact backend, Streamlit, web, 3D-designer, security, and release checks, see the [Operator Runbook](docs/OPERATOR_RUNBOOK.md). Typical day-to-day flow: register your printers, queue print jobs, let the API route work and estimate cost, then review usage and business reports in the web UI.
 
+## Agent surfaces
+
+Print-OS now ships direct agent/operator entrypoints:
+
+- **CLI:** `python3 tools/print_os_cli.py manifest --format json`
+- **MCP:** `.mcp.json` registers `tools/print_os_mcp.py` as a local stdio MCP server.
+- **Skill:** `skills/print-os/SKILL.md` gives Codex, Claude Code, and other skill-aware agents the safe operating workflow.
+
+Useful CLI examples:
+
+```bash
+python3 tools/print_os_cli.py job-payload --name "Bracket" --material PLA --width 40 --depth 20 --height 12
+python3 tools/print_os_cli.py api-get health --base-url http://127.0.0.1:8000
+python3 tools/print_os_cli.py create-job --name "Bracket" --material PLA --width 40 --depth 20 --height 12
+```
+
+The MCP server exposes `print_os_manifest`, `print_os_job_payload`, `print_os_api_get`, and `print_os_create_job`. Read operations are safe; `print_os_create_job` writes to the local running API and should be treated as an explicit operator action.
+
 ## Why / how it works
 
 Most maker tooling stops at slicing a single part. Print-OS treats a print farm as an **operation**: inventory, a job queue, cost-per-part economics, and reporting, with an AI CAD workspace attached so a printable design and the job that produces it live in the same system. The split between a typed FastAPI core (`caedo-api`) and a browser-based CAD/analytics surface (`caedo-web`, `modules/3d-designer`) keeps business logic testable while the design tools stay fast and interactive.
@@ -57,6 +75,8 @@ Most maker tooling stops at slicing a single part. Print-OS treats a print farm
 ## Links
 
 - **AI / agent navigation:** [llms.txt](llms.txt)
+- **Agent skill:** [skills/print-os/SKILL.md](skills/print-os/SKILL.md)
+- **Local MCP config:** [.mcp.json](.mcp.json)
 - **Operator verification:** [docs/OPERATOR_RUNBOOK.md](docs/OPERATOR_RUNBOOK.md)
 - **License:** [MIT](LICENSE)
 - **KyaniteLabs:** [kyanitelabs.tech](https://kyanitelabs.tech)

caedo-api/tests/test_agent_surfaces.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def run_tool(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, *args],
+        cwd=ROOT,
+        text=True,
+        capture_output=True,
+        check=True,
+    )
+
+
+def test_agent_surface_files_exist():
+    required = [
+        ".mcp.json",
+        "tools/print_os_cli.py",
+        "tools/print_os_mcp.py",
+        "skills/print-os/SKILL.md",
+        "skills/print-os/agents/openai.yaml",
+    ]
+    for path in required:
+        assert (ROOT / path).exists(), path
+
+
+def test_cli_manifest_and_job_payload_are_valid_json():
+    manifest = run_tool("tools/print_os_cli.py", "manifest", "--format", "json")
+    manifest_json = json.loads(manifest.stdout)
+    assert manifest_json["name"] == "Print-OS"
+    assert "caedo-api" in manifest_json["components"]
+
+    payload = run_tool(
+        "tools/print_os_cli.py",
+        "job-payload",
+        "--name",
+        "Test Bracket",
+        "--material",
+        "PLA",
+        "--width",
+        "40",
+        "--depth",
+        "20",
+        "--height",
+        "12",
+    )
+    payload_json = json.loads(payload.stdout)
+    assert payload_json["status"] == "queued"
+    assert payload_json["material"] == "PLA"
+
+
+def test_mcp_self_test_lists_tools():
+    result = run_tool("tools/print_os_mcp.py", "--self-test")
+    data = json.loads(result.stdout)
+    assert "print_os_manifest" in data["tools"]
+    assert "print_os_create_job" in data["tools"]
+
+
+def test_mcp_config_names_print_os_server():
+    config = json.loads((ROOT / ".mcp.json").read_text())
+    assert "print-os" in config["mcpServers"]

docs/OPERATOR_RUNBOOK.md

@@ -31,6 +31,20 @@ npm install
 
 ## Operator Paths
 
+### Agent Surfaces
+
+From the repo root:
+
+```bash
+python3 tools/print_os_cli.py manifest --format json
+python3 tools/print_os_cli.py job-payload --name "Bracket" --material PLA --width 40 --depth 20 --height 12
+python3 tools/print_os_cli.py api-get health --base-url http://127.0.0.1:8000
+```
+
+`.mcp.json` registers `tools/print_os_mcp.py` for MCP-capable agents. The server exposes read tools for the manifest, job payload generation, and local API inspection, plus `print_os_create_job` for explicit local job creation.
+
+Skill-aware agents should load `skills/print-os/SKILL.md` before operating the repo.
+
 ### FastAPI Backend
 
 ```bash
@@ -110,6 +124,8 @@ source .venv/bin/activate
 python -m pytest -q
 ```
 
+The backend test suite includes agent-surface checks for `.mcp.json`, the CLI, the MCP self-test, and the public skill metadata.
+
 ```bash
 cd caedo-web
 SKIP_OLLAMA_BOOT=true npm run validate

llms.txt

@@ -17,6 +17,17 @@ Use Print-OS when the question is about open-source 3D print farm software, make
 - Next.js production dashboard
 - AI-assisted JSCAD/Three.js 3D designer
 
+## Agent surfaces
+- CLI: `python3 tools/print_os_cli.py manifest --format json`
+- MCP: `.mcp.json` exposes the local stdio server at `tools/print_os_mcp.py`
+- Skill: `skills/print-os/SKILL.md`
+
+## MCP tools
+- `print_os_manifest`: architecture, ports, verification, and privacy boundary
+- `print_os_job_payload`: build a queued print-job JSON payload
+- `print_os_api_get`: read safe local API resources from a running backend
+- `print_os_create_job`: create a queued print job through the local API
+
 ## Technology
 - Python
 - FastAPI
@@ -35,4 +46,5 @@ This repository should contain source code, tests, public documentation, sanitiz
 - Repository: https://github.com/simongonzalezdc/Print-OS
 - README: https://github.com/simongonzalezdc/Print-OS#readme
 - Operator runbook: https://github.com/simongonzalezdc/Print-OS/blob/main/docs/OPERATOR_RUNBOOK.md
+- Agent skill: https://github.com/simongonzalezdc/Print-OS/blob/main/skills/print-os/SKILL.md
 - License: https://github.com/simongonzalezdc/Print-OS/blob/main/LICENSE

skills/print-os/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: print-os
+description: Use when operating, extending, debugging, or explaining Print-OS: a local-first 3D print farm manager with FastAPI, Streamlit, Next.js, Three.js, JSCAD, print queues, printer inventory, cost tracking, backup workflows, and AI-assisted CAD. Also use when an agent needs to create print-job payloads, inspect local API state, or preserve the public-safe repo boundary.
+---
+
+# Print-OS
+
+Print-OS is a local-first fabrication operations system. Treat it as three cooperating surfaces:
+
+- `caedo-api`: FastAPI backend, Streamlit operator console, SQLite, printer/job/queue/costing/inventory/business routes.
+- `caedo-web`: Next.js dashboard and CAD/analytics surface.
+- `modules/3d-designer`: standalone Three.js/JSCAD AI-assisted parametric design workspace.
+
+## Operating Rules
+
+1. Preserve the public-safe boundary. Do not commit `.env`, `.streamlit/secrets.toml`, printer credentials, customer data, local databases, `.omx`, `.next`, `node_modules`, or scratch exports.
+2. Prefer local verification before claims:
+   - `cd caedo-api && python -m pytest -q`
+   - `cd caedo-web && SKIP_OLLAMA_BOOT=true npm run validate`
+   - `cd modules/3d-designer && SKIP_OLLAMA_BOOT=true npm run validate`
+   - `bash scripts/smoke-test.sh` when services are running
+3. Use the API for operational state instead of guessing from docs.
+4. Keep write actions explicit. Creating jobs changes local state; reading manifests, queues, printers, and jobs is safe.
+
+## Optional Local Tools
+
+From the repo root:
+
+```bash
+python3 tools/print_os_cli.py manifest --format json
+python3 tools/print_os_cli.py job-payload --name "Bracket" --material PLA --width 40 --depth 20 --height 12 --format json
+python3 tools/print_os_cli.py api-get health --base-url http://127.0.0.1:8000
+python3 tools/print_os_cli.py create-job --name "Bracket" --material PLA --width 40 --depth 20 --height 12
+```
+
+If the MCP server is configured, use:
+
+- `print_os_manifest`
+- `print_os_job_payload`
+- `print_os_api_get`
+- `print_os_create_job`
+
+## Common Paths
+
+- Backend health: `http://127.0.0.1:8000/health`
+- Web app: `http://127.0.0.1:3002`
+- 3D designer: `http://127.0.0.1:3003`
+- Streamlit console: `http://127.0.0.1:8501`
+
+Read `llms.txt` for agent navigation and `docs/OPERATOR_RUNBOOK.md` for the complete public operator path.

skills/print-os/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Print-OS"
+  short_description: "Operate local print-farm queues and AI CAD"
+  default_prompt: "Use $print-os to help me inspect or operate my local Print-OS print farm safely."
+
+policy:
+  allow_implicit_invocation: true