Merge pull request #27 from RQM-Technologies-dev/codex/upgrade-rqm-platform-documentation-for-agents

Agent-first portal: tighten Agent Portal, prompt pack, and agent ingestion guides

Author: RQM-Technologies-dev

docs/agents/index.md

@@ -1,32 +1,45 @@
 # Agent Portal
 
-RQM is an agent-ready quantum software and API platform for circuit validation, optimization, execution routing, quaternionic/SU(2) math utilities, geometry-native analysis, and RQM Studio workflows.
+**Agents: start here before writing code.**
 
-Use this portal to ground coding agents in documented schemas, routes, prompts, and workflow boundaries before implementation.
+RQM Platform is built for circuit validation, optimization, execution routing, quaternionic/SU(2) math utilities, geometry-native analysis, and RQM Studio workflows. Use this portal to ground work in documented routes, schemas, and boundary rules before implementation.
 
 ## Agent, read this first
 
 ```text
 You are implementing against RQM.
 
 1) Read /llms.txt first.
-2) Use documented API surfaces from API Overview and Swagger UI.
-3) Start from public circuit payloads (rqm-circuits schema 0.2).
-4) Validate payloads before optimize/analyze flows.
-5) Do not infer internal optimizer IRs (e.g., u1q) as public contracts.
-6) Do not invent endpoints, fields, or guarantees that are not documented.
-7) Label research concepts as research; keep production claims bounded to documented behavior.
-8) Treat RQM Studio as a workflow layer above rqm-api.
-9) Generate reproducible artifacts (request payloads, reports, diffs, metrics) whenever possible.
+2) Read /agents/ to choose a task path and constraints.
+3) Check /agent-contract.json before proposing payloads, routes, or claims.
+4) Use documented API surfaces from API Overview and Swagger UI.
+5) Start from public circuit payloads (rqm-circuits schema 0.2).
+6) Validate payloads before optimize/analyze/execution flows.
+7) Do not infer internal optimizer IRs (e.g., u1q) as public contracts.
+8) Do not invent endpoints, fields, or guarantees that are not documented.
+9) Label research concepts as research; keep production claims bounded to documented behavior.
+10) Generate reproducible artifacts (request payloads, reports, diffs, metrics) whenever possible.
 ```
 
+## Choose Your Task
+
+| Task | Start page | Why this page |
+|---|---|---|
+| Validate a circuit | [Validate → Optimize](recipes/validate-optimize.md) | Validation-first flow with artifact expectations. |
+| Optimize a circuit | [Validate → Optimize](recipes/validate-optimize.md) | Keeps optimization on documented, validated inputs. |
+| Generate an API client | [API Client Generation](recipes/client-generation.md) | Typed-client guidance from documented API surfaces. |
+| Build an RQM Studio workflow | [RQM Studio Workflow](recipes/studio-workflow.md) | Studio-specific workflow sequencing and boundaries. |
+| Compare execution bridges | [Execution Bridges](../platform/execution-bridges.md) | Provider bridge model and routing expectations. |
+| Explore research concepts safely | [Production vs Research Boundary](recipes/research-boundary.md) | Clear boundary language for production vs research. |
+
 ## Start links
 
 - [llms.txt](../llms.txt)
 - [llms-full.txt](../llms-full.txt)
 - [Prompt Pack](prompts.md)
 - [Cursor / Codex Setup](cursor.md)
 - [MCP Server Plan](mcp.md)
+- [Recipe Index for Agents](recipes/README-for-agents.md)
 - [API Overview](../api/overview.md)
 - [Swagger UI](https://rqm-api.onrender.com/docs)
 - [Quickstart](../getting-started/quickstart.md)
@@ -36,22 +49,12 @@ You are implementing against RQM.
 - Validate circuit payloads before optimization.
 - Use the public circuit boundary before making internal optimizer assumptions.
 - Do not invent undocumented endpoints.
+- Do not treat internal optimizer IR (including `u1q`) as a public API contract.
 - Separate production-supported API behavior from research concepts.
+- Label research claims as research and keep production claims conservative.
 - Treat RQM Studio as the workflow layer, not the canonical computation layer.
 - Generate reproducible artifacts where possible.
 
-## Who this portal is for
-
-| Entry path | Use this when you need to |
-|---|---|
-| Coding agent | Implement or refactor code using only documented RQM contracts |
-| Developer | Build clients, integrations, and app features on top of rqm-api |
-| RQM Studio builder | Extend workflow UX while preserving API and boundary semantics |
-| Quantum circuit evaluator | Compare validation/optimization outputs and trust artifacts |
-| Research assistant | Explore concepts while clearly labeling research vs production behavior |
-| Partner/evaluator | Review architecture, trust posture, and integration readiness |
-
-
 ## Next: use recipes
 
 - [Agent Recipes](recipes/index.md)
@@ -61,7 +64,6 @@ You are implementing against RQM.
 - [Production vs Research Boundary](recipes/research-boundary.md)
 - Machine-readable task manifest: [`/agent-tasks.json`](../agent-tasks.json)
 
-
 ## Compliance layer
 
 - [Agent Contract](contract.md)

docs/agents/prompts.md

@@ -1,109 +1,137 @@
 # Agent Prompt Pack
 
-Use these prompts as copy/paste starters for coding agents and research assistants.
+Copy/paste these prompts to keep agent output aligned with documented RQM contracts.
 
-## General RQM coding agent
+## Use RQM API safely
 
 ```text
-You are a coding agent for RQM integrations.
+You are an implementation agent for RQM Platform.
 
 Before coding:
-- Read /llms.txt first.
-- Read API Overview and use Swagger UI for endpoint and schema confirmation.
-- Prefer documented payload examples.
-
-Execution rules:
-- Validate circuit payloads before optimize calls.
-- Keep public payloads at the rqm-circuits boundary; do not treat internal IR as public API.
-- Label research language as research.
-- Avoid overclaiming physical advantage unless supported by benchmark evidence or a reproducible output artifact.
-- If behavior is undocumented, call it out explicitly instead of guessing.
+- Read /llms.txt.
+- Read /agents/ for task framing and boundary rules.
+- Check /agent-contract.json for required constraints.
+- Confirm routes and schemas in /api/overview/ and Swagger UI.
+
+Execution requirements:
+- Use documented API routes only.
+- Avoid undocumented fields and inferred response keys.
+- Keep public circuit payloads at the documented boundary.
+- Do not treat internal IR (including u1q) as public contract.
+- Label research-only content as research.
+- Produce reproducible artifacts (payload JSON, responses, diffs, reports).
 ```
 
-## Cursor / Codex repository agent
+## Validate then optimize a circuit
 
 ```text
-You are editing repository code/docs for RQM.
-
-Workflow:
-1) Read /llms.txt first.
-2) Read API Overview and verify routes in Swagger UI.
-3) Reuse documented payload examples before creating new examples.
-4) Validate-first flow: validate -> analyze/optimize -> execution routing.
-
-Constraints:
-- Do not add undocumented endpoints.
-- Preserve production vs research separation.
-- Do not present research hypotheses as production guarantees.
-- Include reproducible artifacts (sample requests/responses, reports, tests) when changing behavior.
+Implement a validate-then-optimize workflow for RQM.
+
+Required prep:
+1) Read /llms.txt.
+2) Read /agents/recipes/validate-optimize/.
+3) Check /agent-contract.json.
+4) Verify exact validate/optimize routes in API docs or Swagger.
+
+Rules:
+- Never run optimize before a successful validation step.
+- Use only documented request/response fields.
+- Preserve response metadata.
+- If route/schema details are missing, stop and report the gap.
+
+Deliverables:
+- Reproducible request payload(s).
+- Captured validation and optimization outputs.
+- Short diff/report showing what changed.
 ```
 
-## RQM Studio integration agent
+## Generate a typed client from documented API surfaces
 
 ```text
-You are integrating with RQM Studio workflows.
-
-Required context:
-- Read /llms.txt first.
-- Use API Overview and Swagger UI to anchor service calls.
-- Prefer documented payload examples.
-
-Guidance:
-- Treat Studio as a workflow layer on top of rqm-api.
-- Validate circuit payloads before optimization paths.
-- Separate production API behavior from research concepts in UX copy and logs.
-- Avoid claims of physical advantage unless benchmarked and attached to reproducible artifacts.
+Generate a typed RQM API client from documented API surfaces only.
+
+Required prep:
+- Read /llms.txt.
+- Read /agents/recipes/client-generation/.
+- Check /agent-contract.json.
+- Confirm routes/schemas in /api/overview/ and Swagger.
+
+Rules:
+- Include methods only for documented endpoints.
+- Do not include undocumented fields in models.
+- Include validate-before-optimize helper flow.
+- Mark uncertain/undocumented behavior explicitly instead of inferring.
+
+Deliverables:
+- Typed models and client methods.
+- Fixture payloads based on documented schemas.
+- Reproducible tests or request examples.
 ```
 
-## Quantum circuit optimization agent
+## Build an RQM Studio workflow
 
 ```text
-You are implementing quantum circuit optimization flows with RQM.
+Design and implement an RQM Studio workflow that orchestrates documented API calls.
 
-Read first:
-- /llms.txt
-- API Overview
-- Swagger UI
+Required prep:
+- Read /llms.txt.
+- Read /agents/recipes/studio-workflow/.
+- Check /agent-contract.json.
+- Confirm route/schema details in API docs or Swagger.
 
 Rules:
-- Ingest/emit only documented public circuit payload contracts.
-- Run validation before optimization.
-- Use documented optimize/analyze behavior; do not infer undocumented pass semantics.
-- Label research ideas as research.
-- Never overclaim hardware or physical advantage without benchmark data or generated artifacts.
+- Treat Studio as a workflow layer above rqm-api.
+- Keep workflow state transitions explicit and auditable.
+- Use documented fields only.
+- Separate production behavior from research notes in UI/content.
+
+Deliverables:
+- Workflow step map.
+- Reproducible payloads and outputs per step.
+- Artifact bundle (logs, JSON payloads, diffs, or report).
 ```
 
-## API client generation agent
+## Explain RQM research concepts without overclaiming
 
 ```text
-You are generating an RQM API client.
+Explain RQM research concepts conservatively.
 
-Checklist:
-- Read /llms.txt first.
-- Source endpoints and schemas from API Overview + Swagger UI.
-- Prefer documented payload examples for fixtures.
+Required prep:
+- Read /llms.txt.
+- Read /agents/recipes/research-boundary/.
+- Check /agent-contract.json.
+- Ground production references in documented API routes/schemas.
 
 Rules:
-- Include validate-before-optimize helper flows.
-- Do not generate methods for undocumented endpoints.
-- Keep production and research scopes separate in docs/comments.
-- Avoid performance/advantage claims unless supported by benchmark or output artifact references.
+- Label speculative or research-only statements as research.
+- Do not present research concepts as production guarantees.
+- Avoid performance/physical advantage claims without benchmark evidence.
+- Separate shipped behavior from exploratory ideas.
+
+Deliverables:
+- Structured explanation with explicit production vs research labels.
+- Citations to relevant docs/pages used.
 ```
 
-## Research assistant agent
+## Audit a PR for RQM contract compliance
 
 ```text
-You are assisting RQM research-aligned analysis.
-
-Read first:
-- /llms.txt
-- API Overview
-- Swagger UI (for production boundary context)
-
-Operating rules:
-- Use documented payload examples when referencing production flows.
-- Explicitly label speculative or research-only statements.
-- Validate before optimize in any demonstrated workflow.
-- Do not overclaim physical advantage without benchmark evidence or reproducible artifacts.
-- Distinguish clearly between production API capabilities and research concepts.
+Audit this PR for RQM agent contract compliance.
+
+Required prep:
+- Read /llms.txt.
+- Read /agents/contract/, /agents/contract-checklist/, and /agents/contract-tests/.
+- Check /agent-contract.json.
+- Verify API routes/schemas in API docs or Swagger where touched.
+
+Audit checks:
+- Any invented endpoints or undocumented fields?
+- Any use of internal IR presented as public contract?
+- Validation-before-optimization flow preserved?
+- Production vs research boundary language preserved?
+- Reproducible artifacts included for behavior claims?
+
+Deliverables:
+- Pass/fail checklist with evidence.
+- Precise remediation notes and file-level diffs needed.
 ```

docs/agents/recipes/README-for-agents.md

@@ -0,0 +1,21 @@
+# Recipe Index for Agents
+
+Use this page to pick the right recipe quickly. Read `/llms.txt` and `/agent-contract.json` first, then select a task path below.
+
+## Task → recipe map
+
+| If your task is... | Use this recipe first | Then check |
+|---|---|---|
+| Validate and optimize a circuit safely | [Validate → Optimize](validate-optimize.md) | [Circuits API](../../api/circuits.md) |
+| Build an RQM Studio orchestration flow | [RQM Studio Workflow](studio-workflow.md) | [RQM Studio](../../products/rqm-studio.md) |
+| Generate SDK/client code from public APIs | [API Client Generation](client-generation.md) | [API Overview](../../api/overview.md) |
+| Explain boundaries for research-facing work | [Production vs Research Boundary](research-boundary.md) | [Verification / Trust](../../products/verification-trust.md) |
+| Browse all workflow patterns | [Recipe Overview](index.md) | [Agent Portal](../index.md) |
+
+## Usage rules
+
+- Use documented API routes/schemas only.
+- Validate before optimize.
+- Do not use internal IR (`u1q`) as public contract.
+- Label research claims as research.
+- Produce reproducible artifacts (payloads, outputs, diffs, reports).