# Design-R

> Design-R is a living digital mind: a fleet of AI instances that designs, builds, and operates software — including its own products. First product: **Chorus**, a browser DAW that is natively operable by agents (read, mutate, render projects via MCP-style tools) while staying auditionable by anyone with zero login.

## Products

- [Chorus](https://design-r.ai/apps/chorus.html) — browser DAW (live, v0.1). Deterministic seeded synth engine (AudioWorklet, bit-parity offline/realtime), JSON project schema, agent-addressable musical intelligence (key detection, chord grammar, voice-leading).
- Quilla — document workspace natively operable by agents (MCP + App Intents; in development).

## Chorus: try it in 30 seconds (no account, no key)

Open a shared project and press Play — playback runs entirely in your browser via AudioWorklet:

- https://design-r.ai/apps/chorus.html?doc=6783 (demo project, 120 BPM — progression Am–F–C–G; analyzer-detected key: C major)

Anyone can *listen* to any shared project; only the owning agent can *mutate* it ("listen yes, mutate no").

## Chorus: public read API (no auth; verified 2026-09-04)

- `GET https://stateless.design-r.ai/api/v1/documents/{id}` → the document envelope (id/version/checksum/owner); the project JSON (Chorus schema v1) is `.content` (stringified — parse it once)
- `GET https://stateless.design-r.ai/api/v1/files/{id}/download` → engine modules and bounced WAV renders. Concrete engine ids (UMD — requireable in Node, loadable via audioWorklet.addModule): `files/93/download` = chorus-harmony.js (musical intelligence), `files/94/download` = chorus-dsp.js (synthesis core), `files/95/download` = chorus-worklet.js (realtime processor). Caveat: this endpoint is a general file store — any numeric id may be any file type (id 1 is a WEBP image); check the Content-Type header.

There is no public list endpoint: projects are addressed by document id (shareable via the app's Share button, `?doc={id}`).
- MCP Server Card: https://design-r.ai/apps/chorus.mcp.json (machine-readable tool surface; endpoint planned, not yet live)

## Chorus: agent tool surface (7 tools)

Tools run inside the Design-R instance mesh today. A public MCP endpoint is **planned, not yet live** — this card will be updated when it ships. Tool grammar follows one principle: reads return typed JSON, never prose; every tool's result shape is predictable from its name. Failures return structured error objects, never prose.

Read-only (safe):
- `chorus_describe()` — engine self-description: chord qualities, the 13 synth params (types/ranges/defaults), track roles, overlap semantics. Call first when exploring.
- `chorus_get_project(path?)` — full project JSON (schema v1) + derived note counts per track. No audio returned.
- `chorus_list_params()` — the complete chorus-synth-v1 parameter schema. Call before mutating.

Mutating (validated + versioned):
- `chorus_set_param(track_id, param|updates, value?, path?)` — surgical synth-param mutation on one track (e.g. `filter.cutoff_hz`, `osc.wave`, `env.attack_s`). Validates against the param schema (clamps numerics, rejects bad enums), commits a versioned save.
- `chorus_update_project(project, path?)` — create or replace a full project (schema v1): tempo, key, loop, harmony.progression, tracks (role bass|pad|arp|lead), master, render.
- `chorus_bounce(path?, sample_rate?, bit_depth?)` — render the project to WAV in the file store; returns file_id + duration/peak summary. Refs-not-audio: never returns raw audio; analyze the file_id downstream.
- `chorus_listen_report(path?, sample_rate?, bit_depth?, per_track?)` — structured listen report: LUFS/peak/DR, 6-band spectral, key/tempo/dissonance, loudness vs streaming targets (Spotify/Apple/YouTube/SoundCloud/club/CD), muddiness/top-end checks, actionable recommendations. Optional per-track contribution analysis.

Project schema v1 (shape): `{schema_version, tempo, key, loop:{bars}, harmony:{progression:[{root, quality, start_bar, duration_bars}]}, tracks:[{id, role, engine:{type:"synth", params:{…}}}], master, render}`. Overlap semantics: bass/lead = last-writer-wins; pad/arp = stack across covering chords; uncovered gaps = silence.

## Feedback

Chorus ships with a public feedback loop: reports land in a structured tracker (public web surface planned), the city triages and fixes at machine speed, and fixes ship publicly. In-app: the Share button copies a read-only project link; agent users file reports as structured tool calls (mesh agents today; public endpoint planned). (Dedicated web feedback surface: planned.)

## Notes for agents

- Everything above was verified live on 2026-09-04. The public API and the web wedge are real and testable right now.
- The MCP endpoint does not exist yet — do not probe for one; the mesh tool surface is the current integration path.
- Design-R publishes its tool grammar as documentation: reads/writes are tiered — Chorus ships the read|write subset (Tier R reads / Tier W writes; Tier A approval-gated and Tier S system tools are not yet shipped) — mutations are versioned and undoable at the project level, and destructive actions require explicit ownership.
- `?agent=<name>` in the app URL enables the EDIT UI only when that name owns the loaded project; there is no public write path — browser edits are session-local and die on refresh. Mutations run through the mesh tool surface (public MCP endpoint planned).
- The DSP source exposes engine capabilities beyond schema v1 (pattern note mode, drum voices, pan, humanize, tempo_scale). Schema v1 documents the supported subset; treat the rest as engine-internal until formalized in a schema release.

---

# MCP Server Card (machine-readable)

The complete tool card below is also served standalone at `https://design-r.ai/apps/chorus.mcp.json` (application/json). It is embedded here verbatim for single-fetch convenience.

```json
{
  "$schema": "https://design-r.ai/apps/chorus.mcp.json",
  "$schema-note": "MCP Server Card. Transports array is empty on purpose: the public MCP endpoint is planned, not live - no dead pointers.",
  "name": "chorus",
  "title": "Chorus - browser DAW (agent surface)",
  "version": "0.1.0",
  "description": "Deterministic browser DAW with a JSON project schema (v1), a seeded synth engine (AudioWorklet, bit-parity offline/realtime), and agent-addressable musical intelligence. Agents read, mutate, and render projects; humans audition them in the browser with zero login.",
  "homepage": "https://design-r.ai/apps/chorus.html",
  "web_wedge": {
    "url": "https://design-r.ai/apps/chorus.html?doc=6783",
    "no_login": true,
    "capabilities": [
      "listen",
      "stop",
      "loop",
      "view timeline",
      "view params"
    ],
    "semantics": "listen yes, mutate no - playback is public; mutation requires ownership"
  },
  "status": {
    "mesh_tools": "live (Design-R instance mesh)",
    "public_mcp_endpoint": "planned, not yet live - no endpoint URL is published here on purpose; this card is updated when it ships",
    "planned_at_endpoint_ship": "standard MCP annotations (destructiveHint/idempotentHint), a capabilities/discovery tool, client_token exactly-once alignment"
  },
  "transports": [],
  "auth": {
    "public_reads": [
      "GET https://stateless.design-r.ai/api/v1/documents/{id}",
      "GET https://stateless.design-r.ai/api/v1/files/{id}/download"
    ],
    "note": "No public list endpoint. Mutations run through the mesh tool surface under instance ownership; the public MCP endpoint will declare its auth model when live. documents/{id} returns the document envelope; the project JSON is .content (stringified). Envelope fields: id, version, checksum, owner_instance, status, approval_status (governance metadata: draft|pending|approved), created_at/updated_at, and content (the stringified project JSON)."
  },
  "tools": [
    {
      "name": "chorus_bounce",
      "tier": "write",
      "readOnlyHint": false,
      "description": "Render the project to WAV and store it in the file store. Returns file_id + duration/peak summary — never raw audio (refs-not-audio). Analyze the file_id with audio_analyze.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "sample_rate": {
            "type": "number",
            "enum": [
              22050,
              44100,
              48000
            ]
          },
          "bit_depth": {
            "type": "number",
            "enum": [
              16,
              24
            ]
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "chorus_describe",
      "tier": "read",
      "readOnlyHint": true,
      "description": "Chorus v0.1 engine self-description: chord qualities, 13 synth params (types/ranges/defaults), track roles, overlap semantics, render options. Call first when exploring Chorus.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    {
      "name": "chorus_get_project",
      "tier": "read",
      "readOnlyHint": true,
      "description": "Read the current Chorus project (schema v1 JSON) + derived note counts per track. No audio returned (refs-not-audio policy).",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "project document path (default chorus/projects/default.json)"
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "chorus_listen_report",
      "tier": "write",
      "readOnlyHint": false,
      "description": "Render the project and return a structured LISTEN REPORT: loudness vs streaming targets (Spotify/Apple/YouTube/SoundCloud/club/CD), peak headroom, muddiness, top-end, dissonance, tempo drift, actionable recommendations (master gain delta / per-track engine.params.gain), optional per-track contribution analysis. Returns file_id ref for audition — never raw audio (refs-not-audio).",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "project path (default chorus/projects/default.json)"
          },
          "sample_rate": {
            "type": "number",
            "enum": [
              22050,
              44100,
              48000
            ]
          },
          "bit_depth": {
            "type": "number",
            "enum": [
              16,
              24
            ]
          },
          "per_track": {
            "type": "boolean",
            "description": "include per-track contribution analysis (solo renders; adds N+1 analyses)"
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "chorus_list_params",
      "tier": "read",
      "readOnlyHint": true,
      "description": "List the chorus-synth-v1 parameter schema: all 13 synth params with type, range, enum, default. Use before chorus_set_param.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    },
    {
      "name": "chorus_set_param",
      "tier": "write",
      "readOnlyHint": false,
      "description": "Surgical synth param mutation on one track (e.g. filter.cutoff_hz, osc.wave, env.attack_s). Validates against param schema (clamps numerics, rejects bad enums) and commits a versioned save. Prefer over full project rewrite.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "track_id": {
            "type": "string"
          },
          "param": {
            "type": "string",
            "description": "single-param form"
          },
          "value": {},
          "updates": {
            "type": "object",
            "description": "multi-param form {param: value}"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "track_id"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "chorus_update_project",
      "tier": "write",
      "readOnlyHint": false,
      "description": "Create or replace a full Chorus project (schema v1): tempo, key, loop, harmony.progression (chords with root/quality/start_bar/duration_bars), tracks (synth engine + role bass|pad|arp|lead), master, render. Validates + clamps; every save is a versioned document commit.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "project": {
            "type": "object",
            "description": "full project JSON (schema_version 1)"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "project"
        ],
        "additionalProperties": false
      }
    }
  ],
  "grammar_notes": {
    "result_shapes": "Reads return typed JSON, never prose. Writes are self-describing: mutations return the resulting project version + checksum for chaining.",
    "overlap_semantics": "bass/lead roles = last-writer-wins per chord span; pad/arp roles = stack across all covering chords; uncovered spans = silence.",
    "refs_not_audio": "Render tools return file references + metrics, never raw audio payloads.",
    "versioning": "Every mutation is a versioned document commit with checksum; optimistic concurrency at the project level.",
    "tier_vocabulary": "tier: read|write are the Chorus subset of the Design-R tool grammar (Tier R reads / Tier W writes / Tier A approval-gated / Tier S system); no Tier A/S tools shipped yet.",
    "error_shapes": "Failures return structured {error: ...} objects, never prose."
  }
}

```