> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prysm1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Governance

> Score, generate, and snapshot workspace manifests for agentic-control-plane readiness.

<Note>
  All workspace endpoints require **Bearer token** authentication.
</Note>

The Workspace Governance API gives agentic tools a shared vocabulary for expressing what a repo is
configured to allow, protect, and audit. A workspace manifest (the common input) is a lightweight
JSON object — no files on disk, no agent running — so every call is pure and deterministic.

***

## POST /v1/workspace/readiness

Score a repo manifest on Agentic Control Plane maturity (0–100). Use this to gate deployments,
generate a shareable readiness badge, or surface the highest-leverage improvements.

<Note>
  **POST** `https://api.prysm1.com/v1/workspace/readiness` · Auth required
</Note>

### Request Body

<ParamField body="workspace_id" type="string" required>
  Unique identifier for this workspace. Anchors the signed handoff ledger.
</ParamField>

<ParamField body="project_name" type="string">
  Human-readable project name (appears in generated AGENTS.md / CLAUDE.md).
</ParamField>

<ParamField body="stack" type="string[]">
  Technology stack (e.g. `["python", "fastapi", "react"]`). Used to tailor generated instructions.
</ParamField>

<ParamField body="protected_paths" type="string[]">
  Paths that require elevated approval before an agent can write to them
  (e.g. `["backend/eval/", ".env", "go.sum"]`).
</ParamField>

<ParamField body="forbidden_commands" type="string[]">
  Shell commands that must never be executed in this workspace
  (e.g. `["rm -rf", "git push --force"]`).
</ParamField>

<ParamField body="require_handoffs" type="boolean">
  Whether agents must create a signed handoff entry before handing off context.
</ParamField>

<ParamField body="require_risk_gate" type="boolean">
  Whether agents must pass the risk gate before executing agentic actions.
</ParamField>

### Response

<ResponseField name="object" type="string">`repo.readiness`</ResponseField>
<ResponseField name="score" type="integer">0–100 readiness score.</ResponseField>
<ResponseField name="rating" type="string">`excellent` | `good` | `fair` | `poor` | `critical`</ResponseField>
<ResponseField name="checks" type="object[]">Per-check breakdown: `id`, `label`, `weight`, `passed`.</ResponseField>
<ResponseField name="recommendations" type="object[]">Highest-weight failing checks, sorted by impact.</ResponseField>
<ResponseField name="earned_weight" type="integer">Sum of weights for passing checks.</ResponseField>
<ResponseField name="total_weight" type="integer">Sum of all check weights (the denominator).</ResponseField>
<ResponseField name="version" type="string">Scoring algorithm version.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.prysm1.com/v1/workspace/readiness \
    -H "Authorization: Bearer prysm_sk_..." \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "ws-myrepo",
      "project_name": "MyApp",
      "stack": ["python", "fastapi"],
      "protected_paths": ["backend/eval/", ".env"],
      "require_handoffs": true,
      "require_risk_gate": true
    }'
  ```

  ```python Python theme={null}
  import httpx

  client = httpx.Client(headers={"Authorization": "Bearer prysm_sk_..."})
  resp = client.post("https://api.prysm1.com/v1/workspace/readiness", json={
      "workspace_id": "ws-myrepo",
      "project_name": "MyApp",
      "stack": ["python", "fastapi"],
      "protected_paths": ["backend/eval/", ".env"],
      "require_handoffs": True,
      "require_risk_gate": True,
  })
  print(resp.json()["score"], resp.json()["rating"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "repo.readiness",
    "version": "repo-readiness-v0.1",
    "score": 75,
    "rating": "good",
    "earned_weight": 75,
    "total_weight": 100,
    "checks": [
      {"id": "has_project_name", "label": "Project name declared", "weight": 10, "passed": true},
      {"id": "has_protected_paths", "label": "Protected paths declared", "weight": 15, "passed": true}
    ],
    "recommendations": [
      {"id": "has_tests", "label": "Test suite declared", "weight": 10, "rec": "Add test_runner to manifest."}
    ]
  }
  ```
</ResponseExample>

***

## POST /v1/workspace/generate

Generate `AGENTS.md`, `CLAUDE.md`, and `.cursor/rules/*.mdc` from a canonical workspace manifest.
Same manifest as `/readiness` — score first, then generate. Output is deterministic (same manifest
yields byte-identical artifacts).

<Note>
  **POST** `https://api.prysm1.com/v1/workspace/generate` · Auth required ·
  Internal-only until the Patent §18.1–18.2 continuation is filed.
</Note>

### Request Body

Same fields as `/v1/workspace/readiness`.

### Response

<ResponseField name="version" type="string">Generator version.</ResponseField>
<ResponseField name="workspace_id" type="string">Echoed from the request.</ResponseField>

<ResponseField name="artifacts" type="object[]">
  Array of `{path, content}` objects. Paths: `AGENTS.md`, `CLAUDE.md`,
  `.cursor/rules/prysm-security.mdc`, `.cursor/rules/prysm-docs.mdc`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.prysm1.com/v1/workspace/generate \
    -H "Authorization: Bearer prysm_sk_..." \
    -H "Content-Type: application/json" \
    -d '{"workspace_id": "ws-myrepo", "project_name": "MyApp", "stack": ["typescript"]}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "version": "agents-md-v0.1",
    "workspace_id": "ws-myrepo",
    "artifacts": [
      {"path": "AGENTS.md", "content": "# AGENTS.md\n\n..."},
      {"path": "CLAUDE.md", "content": "# CLAUDE.md\n\n..."},
      {"path": ".cursor/rules/prysm-security.mdc", "content": "..."},
      {"path": ".cursor/rules/prysm-docs.mdc", "content": "..."}
    ]
  }
  ```
</ResponseExample>

***

## GET /v1/workspace/{workspace_id}/snapshot

Audit-dashboard snapshot for a workspace: count, time range, risk-tier distribution, signed share,
chain integrity verdict, and a tail of recent entries. Use this to render a workspace health view
without re-implementing the chain verification math.

<Note>
  **GET** `https://api.prysm1.com/v1/workspace/{workspace_id}/snapshot` · Auth required
</Note>

### Path Parameters

<ParamField path="workspace_id" type="string" required>
  The workspace to snapshot.
</ParamField>

### Query Parameters

<ParamField query="limit" type="integer">
  Cap the tail (1–200; default 50).
</ParamField>

### Response

<ResponseField name="workspace_id" type="string">Echoed workspace ID.</ResponseField>
<ResponseField name="count" type="integer">Total handoffs in this workspace.</ResponseField>
<ResponseField name="risk_distribution" type="object">Counts per tier: `auto`, `confirm`, `approve`, `block`.</ResponseField>
<ResponseField name="avg_risk_score" type="number | null">Mean risk score across all handoffs.</ResponseField>
<ResponseField name="signed_share" type="number">Fraction of handoffs that are Ed25519-signed (0–1).</ResponseField>
<ResponseField name="integrity" type="object">Chain integrity verdict: `ok`, `n`, `first_broken_index`, `reasons`.</ResponseField>
<ResponseField name="tail" type="object[]">Last N handoffs summarized (id, objective, from\_tool, to\_tool, created\_at, risk\_tier, risk\_score, signed).</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.prysm1.com/v1/workspace/ws-myrepo/snapshot?limit=10" \
    -H "Authorization: Bearer prysm_sk_..."
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "workspace.snapshot",
    "workspace_id": "ws-myrepo",
    "count": 12,
    "risk_distribution": {"auto": 10, "confirm": 1, "approve": 1, "block": 0, "unknown": 0},
    "avg_risk_score": 18,
    "signed_share": 1.0,
    "integrity": {"ok": true, "n": 12, "first_broken_index": null, "reasons": []},
    "tail": [
      {
        "id": "ho_abc123",
        "objective": "Refactor auth module",
        "from_tool": "cursor",
        "to_tool": "claude-code",
        "created_at": "2026-06-15T10:00:00+00:00",
        "risk_tier": "auto",
        "risk_score": 12,
        "signed": true
      }
    ]
  }
  ```
</ResponseExample>