{
  "id": "2026-05-08-agent-json-human-html-artifact-da103469dc",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-08-agent-json-human-html-artifact.json",
  "source_kind": "json",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.742Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.v1",
  "title": "Agent JSON, Human HTML Artifact Standard",
  "summary": "RedKey should make structured JSON the canonical machine artifact and intentional HTML the human review surface. Markdown remains useful for notes and exports, but not as the canonical format for governed work.",
  "format_source": "json",
  "status": "draft",
  "sections": [
    {
      "title": "Problem",
      "level": 2,
      "body": "- summary: Important RedKey work is currently split across Markdown docs, JSONB Studio artifacts, JSON wrappers containing Markdown, repo state files, and rendered Studio views. This is workable for agents, but it is not yet a clean operating model for humans or durable agent execution.\n- pain points: 5 items"
    },
    {
      "title": "Thesis",
      "level": 2,
      "body": "RedKey should make structured JSON the canonical machine artifact and intentional HTML the human review surface. Markdown remains useful for notes and exports, but not as the canonical format for governed work."
    },
    {
      "title": "Decision",
      "level": 2,
      "body": "- recommendation: Adopt the dual-surface model for governed RedKey artifacts: structured JSON for agents and systems, intentional HTML for Justin and other humans.\n- next action: Use this prototype pair to decide whether to formalize schemas, renderer contracts, and enforcement checks."
    },
    {
      "title": "Architecture",
      "level": 2,
      "body": "- layers: 6 items\n- diagram: type: string, nodes: object"
    },
    {
      "title": "Implementation Plan",
      "level": 2,
      "body": "- Prototype Pair: phase: number, name: string, deliverables: object, status: string\n- Schemas and Renderers: phase: number, name: string, deliverables: object, status: string\n- Studio Integration: phase: number, name: string, deliverables: object, status: string\n- Knowledge Console: phase: number, name: string, deliverables: object, status: string"
    },
    {
      "title": "Risks",
      "level": 2,
      "body": "- Renderer sprawl: name: string, impact: string, mitigation: string\n- Schema rigidity: name: string, impact: string, mitigation: string\n- HTML chaos: name: string, impact: string, mitigation: string\n- Duplicate truth: name: string, impact: string, mitigation: string"
    },
    {
      "title": "Open Questions",
      "level": 2,
      "body": "- Should generated HTML be stored in Supabase or rendered on demand first?\n- Should platform specs in repo move to JSON immediately, or only new governed specs?\n- What artifact types should allow prose exports?\n- Should Mermaid, SVG, or React Flow be the first diagram layer?\n- What is the minimum accessibility gate for generated artifact views?"
    }
  ],
  "html_path": "artifacts/2026-05-08-agent-json-human-html-artifact-da103469dc.html",
  "json_path": "artifacts/2026-05-08-agent-json-human-html-artifact-da103469dc.json"
}