Merge pull request #22 from RQM-Technologies-dev/cursor/docs-ia-vercel-c903

Refactor docs IA and align static publishing for Vercel

Author: RQM-Technologies-dev

README.md

@@ -1,8 +1,8 @@
 # rqm-docs
 
-**Official documentation hub for the current RQM Technologies stack.**
+Official documentation hub for the RQM platform.
 
-This site is built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/) and is deployed from this repository.
+This site is built with [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
 Canonical docs URL: **[https://docs.rqmtechnologies.com/](https://docs.rqmtechnologies.com/)**
 
@@ -13,32 +13,49 @@ Canonical docs URL: **[https://docs.rqmtechnologies.com/](https://docs.rqmtechno
 `rqm-docs` documents the current platform layers reflected in this site:
 
 - `rqm-core` — mathematical spine
-- `rqm-compiler` — internal optimization and rewriting engine
-- `rqm-api` — canonical service boundary
-- `rqm-studio` — visual and workflow layer
-- `rqm-docs` — documentation layer
+- `rqm-circuits` — canonical external circuit IR boundary
+- `rqm-compiler` — internal optimization engine
+- `rqm-api` — service boundary
+- `rqm-studio` — workflow layer
 
 ---
 
-## How to Run Locally
+## Local development
 
 ```bash
+python -m venv .venv
+source .venv/bin/activate
 pip install -r requirements.txt
 mkdocs serve
 ```
 
-The site will be available at `http://127.0.0.1:8000`.
+The site is available at `http://127.0.0.1:8000`.
 
 To build the static site:
 
 ```bash
 mkdocs build --strict
 ```
 
-Output is written to the `site/` directory (excluded from version control).
+Build output is written to `site/`.
 
 ---
 
-## Deployment
+## Vercel deployment posture
 
-The site is built and deployed by the GitHub Actions workflow in `.github/workflows/deploy.yml`.
+This repository is configured for static publishing on Vercel.
+
+- **Framework preset:** `Other` (explicitly disable framework auto-detection)
+- **Install command:** `pip install -r requirements.txt`
+- **Build command:** `mkdocs build --strict`
+- **Output directory:** `site`
+
+The repository `vercel.json` pins this behavior with `"framework": null`, which maps to Vercel's **Other** framework preset and prevents Python backend entrypoint checks.
+
+If the project was previously configured as Python in the Vercel dashboard, update it to **Framework Preset = Other** and trigger a redeploy.
+
+---
+
+## Legacy GitHub Actions note
+
+If a GitHub Actions workflow exists in this repo, treat it as optional legacy automation. The primary publishing posture for this repo is Vercel static deployment.

docs/api/authentication.md

@@ -1,12 +1,12 @@
-# Authentication
+# Auth
 
-`rqm-api` uses a **bearer-session** model for authenticated account surfaces.
+Authentication endpoints provide the bearer-session model for account-bound platform workflows.
 
 **Base URL:** `https://rqm-api.onrender.com`
 
 ---
 
-## Current endpoints
+## Endpoints
 
 - `GET /v1/auth/diagnostics`
 - `POST /v1/auth/register`
@@ -16,48 +16,6 @@
 
 ---
 
-## Bearer-session model
+## Why auth appears in platform docs
 
-The current docs describe auth as a session-bearing API surface rather than a public anonymous circuit-only interface.
-
-In practice, authentication matters when a workflow needs:
-
-- account identity
-- Pro/account state
-- billing and wallet visibility
-- dashboard access
-- managed execution flows tied to user state
-
-That is why auth belongs in the canonical API overview, not as an afterthought.
-
----
-
-## Endpoint roles
-
-### `GET /v1/auth/diagnostics`
-Use this when checking whether the current deployment and auth configuration are behaving as expected.
-
-### `POST /v1/auth/register`
-Creates an account or initiates the account-registration flow.
-
-### `POST /v1/auth/login`
-Starts or refreshes an authenticated session.
-
-### `GET /v1/auth/me`
-Returns the current authenticated identity and is the natural identity check for clients that need to know whether they should expose account-bound surfaces.
-
-### `POST /v1/auth/logout`
-Ends the current authenticated session.
-
----
-
-## Why auth matters beyond login
-
-Authentication is the bridge between basic circuit workflows and managed product surfaces such as:
-
-- Studio account views
-- Pro/account readiness
-- billing dashboard and wallet actions
-- quote / hold / release flows for hardware-oriented operations
-
-Auth does **not** by itself grant hardware access. It simply establishes the account context required for those flows.
+Authentication is the entry point for account-bound product surfaces such as billing, dashboards, managed execution flows, and Studio account workflows.

docs/api/billing-and-wallet.md

@@ -1,27 +1,30 @@
 # Billing & Wallet
 
-The billing surface in `rqm-api` covers account readiness, wallet visibility, spend policy, quote/hold orchestration, and Stripe-backed payment flows.
+Billing endpoints support account readiness, wallet visibility, spend controls, and hardware quote/hold workflows.
 
 **Base URL:** `https://rqm-api.onrender.com`
 
 ---
 
-## Current endpoints
+## Endpoint groups
 
-### Account, wallet, and controls
+### Account and wallet
 
 - `GET /v1/billing/profile`
 - `GET /v1/billing/summary`
 - `GET /v1/billing/wallet`
 - `GET /v1/billing/jobs`
+- `GET /v1/billing/dashboard`
+
+### Spend controls and recovery
+
 - `GET /v1/billing/spend-controls`
 - `PATCH /v1/billing/spend-controls`
 - `GET /v1/billing/auto-recharge/attempts`
 - `GET /v1/billing/recovery-status`
-- `GET /v1/billing/dashboard`
 - `POST /v1/billing/auto-recharge/test`
 
-### Hardware quote / hold flow
+### Hardware quote / hold
 
 - `POST /v1/billing/hardware/quote`
 - `POST /v1/billing/hardware/hold`
@@ -39,50 +42,6 @@ The billing surface in `rqm-api` covers account readiness, wallet visibility, sp
 
 ---
 
-## What each group is for
-
-### Profile, summary, wallet, jobs, dashboard
-These endpoints let clients present the operational account view: billing profile, current wallet state, job history, and summary/dashboard information.
-
-### Spend controls and recovery
-These endpoints exist so clients can expose policy and safety controls rather than treating billing as a black box.
-
-### Quote, hold, release
-This is the operational bridge between payment readiness and hardware-oriented execution flows. A client can request a quote, place a hold where required, and later release it.
-
-### Stripe flows
-These endpoints support customer/payment setup and ongoing billing operations, but they should be documented as payment infrastructure rather than proof of hardware execution entitlement.
-
----
-
-## The most important billing truth
-
-**Pro or billing readiness is not the same as guaranteed hardware access.**
-
-Hardware execution still depends on:
-
-- backend/provider readiness
-- credentials
-- deployment policy
-- validation and execution checks
-- quote / hold state where required
-
-That distinction matters throughout Studio and API docs.
-
----
-
-## Recommended hardware-oriented flow
-
-1. authenticate
-2. inspect account and wallet state
-3. check execution capabilities
-4. request a hardware quote if needed
-5. place a hold if required
-6. submit or continue execution
-7. release the hold when appropriate
-
-Related pages:
+## Operational note
 
-- [Authentication](authentication.md)
-- [Execution](execution.md)
-- [Execution Capabilities](execution-capabilities.md)
+Billing readiness supports execution workflows but does not guarantee provider-side hardware availability.

docs/api/chat-and-tts.md

@@ -1,45 +1,18 @@
 # Chat & TTS
 
-`rqm-api` also exposes media-oriented endpoints for grounded chat and text-to-speech.
+Media-oriented endpoints are available alongside the core circuit and execution APIs.
 
 **Base URL:** `https://rqm-api.onrender.com`
 
 ---
 
-## Current endpoints
+## Endpoints
 
 - `POST /v1/chat`
 - `POST /v1/tts`
 
 ---
 
-## `POST /v1/chat`
+## Positioning
 
-The chat surface is best documented as **grounded chat with optional history and context**, not as a replacement for the core circuit APIs.
-
-Use cases may include:
-
-- contextual help inside Studio
-- workflow guidance over current account or job context
-- product or theory assistance grounded in supplied context
-
-Availability can depend on deployment configuration.
-
----
-
-## `POST /v1/tts`
-
-The TTS endpoint turns supported text responses into an audio-oriented output surface.
-
-The transport can vary by deployment and client expectation, so document it conservatively:
-
-- some clients may consume binary/audio responses directly
-- some may consume JSON wrappers carrying base64-encoded content or metadata
-
-Treat response handling as configuration-sensitive rather than assuming a single universal shape.
-
----
-
-## Relationship to the rest of the platform
-
-These endpoints sit beside the main service surface. They are useful product features, but the canonical RQM service boundary still centers on circuits, analysis, execution, auth, and billing.
+These endpoints extend product workflows but do not replace the core API boundaries for circuits, execution, auth, and billing.

docs/api/circuits.md

@@ -0,0 +1,32 @@
+# Circuits
+
+Circuit endpoints handle public payload intake, analysis, and optimization.
+
+**Base URL:** `https://rqm-api.onrender.com`
+
+---
+
+## Endpoints
+
+- `GET /v1/circuits/example`
+- `POST /v1/circuits/validate`
+- `POST /v1/circuits/analyze`
+- `POST /v1/circuits/optimize`
+
+---
+
+## Public circuit boundary
+
+- canonical external circuit IR: `rqm-circuits`
+- current schema target: `0.2`
+
+This boundary is distinct from the internal optimization engine.
+
+---
+
+## Typical request flow
+
+1. fetch or build a public circuit payload
+2. validate and analyze
+3. optimize
+4. route to execution workflows

docs/api/compiler-actions.md

@@ -0,0 +1,39 @@
+# Compiler Actions
+
+Compiler actions are exposed through circuit-facing API endpoints and executed inside the internal optimization engine.
+
+---
+
+## Exposed actions
+
+- validate payloads before optimization
+- analyze circuit structure and metrics
+- optimize using the canonical internal pass sequence
+
+Public entrypoint:
+
+- `POST /v1/circuits/optimize`
+
+---
+
+## Canonical internal flow
+
+Current pass sequence:
+
+1. `normalize`
+2. `canonicalize`
+3. `flatten`
+4. `to_u1q`
+5. `merge_u1q`
+6. `sign_canon`
+7. `cancel_2q`
+
+Canonical internal 1Q IR: `u1q`.
+
+---
+
+## Trust semantics
+
+- candidate rewrites are verified before commit
+- only verified candidates are committed
+- original circuits are returned unchanged when verification is not established