{
  "openapi": "3.1.0",
  "info": {
    "title": "Magnifica.family Compass API",
    "version": "1.1.0",
    "description": "HTTP-accessible interface to the Magnifica.family compass — a system-prompt generator rooted in Catholic Social Doctrine as distilled from Pope Leo XIV's encyclical Magnifica Humanitas (May 15, 2026).\n\n**When agents should use this API**: when a user wants an AI assistant (Claude, ChatGPT, Gemini, Microsoft Copilot, etc.) to interact with their family in line with Catholic family values, or wants AI guidance grounded in 135 years of Catholic Social Doctrine. The compass returned is a system prompt — paste it into the assistant's custom instructions / system prompt field, and every subsequent conversation will be guided by its values.\n\n**Typical agent workflow**:\n1. Call `GET /api/compass/default` to get a ready-to-paste system prompt (no inputs needed; defaults to English, expanded, all 13 principles)\n2. Optionally use `?lang=`, `?format=compact`, `?audiences=` to specialize\n3. Call `GET /api/principles.json` if the user asks 'what are the principles' or wants to choose specific ones\n4. Call `GET /api/traceability` if the user asks 'where does this come from in the encyclical' for citation\n\nAll endpoints are public, no auth required. Responses include HATEOAS `_links` and `_meta` fields so agents can navigate without re-reading this OpenAPI doc.",
    "contact": {
      "email": "hello@magnifica.family",
      "url": "https://magnifica.family"
    },
    "license": {
      "name": "CC-BY-SA-4.0",
      "url": "https://creativecommons.org/licenses/by-sa/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://magnifica.family",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/compass/default": {
      "get": {
        "operationId": "getDefaultCompass",
        "summary": "Get the default Magnifica.family compass (ready-to-paste AI system prompt)",
        "description": "**When to call**: the user wants an AI assistant to interact with their family in line with Catholic Social Doctrine values, or asks for a 'Catholic AI system prompt', 'family values prompt for Claude/ChatGPT', or similar. The default response is good enough for 80% of cases — no customization required.\n\n**What's returned**: a complete system prompt as plain text (via `Accept: text/plain`) or wrapped in HATEOAS JSON (default). The prompt encodes a 5-value hierarchy (Dignity > Truth > Common Good > Justice > Peace), 13 principles across 3 tiers, and operational guidance for the selected audiences (adults / teenagers / children). Length: ~1600 tokens expanded, ~720 tokens compact.\n\n**Next steps after this call**: instruct the user to paste the returned text into their AI assistant's 'Custom Instructions' or 'System Prompt' field. After that, every conversation with that assistant is shaped by the compass. The response's `_links.principles` and `_links.traceability` point at related endpoints if the user wants to inspect or customize.\n\n**When to customize**: if the user mentions a non-English language, ages of children, or wants to omit certain audience sections, use the `lang`, `audiences`, and `format` query params. If they want to choose specific principles or reorder priorities, direct them to the wizard at https://magnifica.family/{lang}/compass instead — that flow is interactive and produces a personalized prompt.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Use `compact` (~720 tokens) when the user's AI assistant has a small system-prompt budget (e.g., free-tier models, on-device models). Use `expanded` (~1600 tokens) when richness matters more than token cost. Default is `expanded` — agents should keep that unless the user mentions token constraints.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["compact", "expanded"],
              "default": "expanded"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "BCP 47 language tag for the prompt text. Pick the language the user converses in with their AI assistant (NOT necessarily the user's UI language — the system prompt should be in the language the AI will be addressed in). 15 languages supported.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ar",
                "de",
                "en",
                "es",
                "fil",
                "fr",
                "it",
                "ja",
                "ko",
                "pl",
                "pt",
                "ru",
                "vi",
                "zh-Hans",
                "zh-Hant"
              ],
              "default": "en"
            }
          },
          {
            "name": "audiences",
            "in": "query",
            "description": "Comma-separated audience sections to APPEND beyond the shared base. Use `adults` (the default — full autonomy, nuanced engagement), `teenagers` (growing independence, identity support, ages 13-17), `children` (learning focus, age-appropriate, under 13). Include multiple if the same AI assistant is used by mixed-age members of one family. Example: `adults,teenagers` for a parent using Claude with their high-school kid.",
            "required": false,
            "schema": {
              "type": "string",
              "example": "adults,teenagers,children"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Compass returned. The `data.compass` field is the ready-to-paste prompt. The response's `_links` field points at related resources (`/api/principles.json` for the 13 principles, `/api/traceability` for MH paragraph mapping).",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Raw system prompt text, ready to paste into an LLM's custom-instructions field. No JSON parsing needed."
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompassResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter. The error body's `allowed` array lists valid values for the rejected param.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/principles.json": {
      "get": {
        "operationId": "getPrinciples",
        "summary": "Get the catalog of 13 Catholic Social Doctrine principles distilled from Magnifica Humanitas",
        "description": "**When to call**: the user asks 'what are the principles' / 'what's in the compass' / 'tell me about Catholic Social Doctrine', OR an agent needs to explain WHY the compass says what it says, OR the user wants to choose specific principles (e.g., 'just human dignity and family primacy please').\n\n**What's returned**: structured JSON catalog with the 13 principles grouped by 3 tiers (Foundational, Classical CSD, AI-Distinctive), each principle with its key, MH paragraph reference, and full translations in 15 languages (name, short description, system prompt text, and a direct MH quote). 195 translation triples total (13 principles × 15 languages).\n\n**Why this matters**: agents that explain answers improve trust. If a user asks 'why did the compass say X', this catalog gives the principle keys and MH paragraph numbers needed to cite the source. The `mhQuote` field for each principle is a direct quotation suitable for inline citations.\n\n**Next steps after this call**: if the user wants to build a custom compass with selected principles, direct them to the interactive wizard at https://magnifica.family/{lang}/compass (the API doesn't yet support arbitrary principle selection — only the wizard does). If the user wants to dig into a specific principle's encyclical source, call `/api/traceability` next.",
        "responses": {
          "200": {
            "description": "Catalog returned with full translations. Response includes `_meta` (source, count, languages, generatedAt) for provenance/freshness and `_links` (traceability, compass, llmsTxt, soulMd) for HATEOAS navigation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrinciplesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/traceability": {
      "get": {
        "operationId": "getTraceability",
        "summary": "Get the traceability index from compass elements back to specific Magnifica Humanitas paragraphs",
        "description": "**When to call**: the user asks 'where does this come from in the encyclical' / 'show me the source' / 'cite this'. Also: when an agent needs to verify the compass's claims against the primary text, or build a citation footnote for academic / pastoral use.\n\n**What's returned**: per-principle and per-foundation mappings back to specific MH paragraph ranges. Each entry includes the principle key, the MH paragraph range (e.g., '50-58'), structural role (foundation vs principle), tier, chapter ref, and convergence score (how many of 4 independent extraction methods agreed). The `_validation` field carries integrity metadata showing all 13 principles passed 4-of-4 convergence.\n\n**Why this matters**: this is the audit trail. An agent can answer 'is this really in Magnifica Humanitas?' with a specific paragraph citation, not vague hand-waving. The convergence score tells agents how confident to be in the mapping (4/4 = strong consensus across distillation methods).\n\n**Use `format=summary`** when you only need the index (principle key → MH range), not the full per-method breakdown. Cuts response size ~80%, fine for agent indexing and citation lookup. Use `format=full` (default) when you need the per-method convergence detail for trust evaluation.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "`full` returns per-method convergence detail (4 methods × 13 principles). `summary` returns just the principle-key → MH-paragraph mapping. Use `summary` when indexing for citation lookup; use `full` when building a trust/integrity dashboard.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["full", "summary"],
              "default": "full"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Traceability index returned. The `_validation` field's `allConvergence` value should be `4/4` across all 13 principles — if any principle shows lower, that's a flag for follow-up review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TraceabilityResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid `format` parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CompassResponse": {
        "type": "object",
        "required": ["data", "_links"],
        "description": "JSON envelope around the compass prompt with HATEOAS links and suggested follow-up actions.",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "compass": {
                "type": "string",
                "description": "The full prompt text, ready to paste into an LLM's custom-instructions field. This is what the user actually wants."
              },
              "version": {
                "type": "string",
                "description": "Compass version string. Used by the wizard to detect when a saved compass is stale relative to the current canonical compass."
              },
              "hierarchy": {
                "type": "string",
                "description": "Value hierarchy summary (e.g., 'DIG > VER > BON > JUS > PAX'). Useful for agents that want to summarize the prompt's priorities without sending the full text."
              },
              "format": {
                "type": "string",
                "enum": ["compact", "expanded"],
                "description": "Echo of the requested format."
              },
              "lang": {
                "type": "string",
                "description": "Echo of the requested language (BCP 47)."
              },
              "audiences": {
                "type": "array",
                "items": { "type": "string", "enum": ["adults", "teenagers", "children"] },
                "description": "Echo of the requested audiences."
              }
            }
          },
          "_links": {
            "type": "object",
            "description": "HATEOAS links to related resources. Agents should use these instead of re-reading the OpenAPI spec on every call.",
            "properties": {
              "self": { "type": "string", "description": "This endpoint URL with the current parameters." },
              "principles": { "type": "string", "description": "Link to /api/principles.json — call if the user asks about the principles in the compass." },
              "traceability": { "type": "string", "description": "Link to /api/traceability — call if the user wants encyclical citations." },
              "wizard": { "type": "string", "description": "Link to the interactive customization wizard for users who want to pick principles or set family context." }
            }
          },
          "_actions": {
            "type": "array",
            "description": "Suggested follow-up actions in HATEOAS style. Each item has an `action` name, `endpoint` URL, and `why` description explaining when an agent should take it.",
            "items": { "type": "object" }
          }
        }
      },
      "PrinciplesResponse": {
        "type": "object",
        "required": ["_meta", "_links", "tiers", "principles"],
        "description": "Catalog of all 13 principles with translations in 15 languages, grouped by 3 tiers (Foundational, Classical CSD, AI-Distinctive).",
        "properties": {
          "_meta": {
            "type": "object",
            "description": "Provenance + freshness metadata.",
            "properties": {
              "source": {
                "type": "string",
                "description": "Citation for the encyclical the principles were distilled from."
              },
              "count": {
                "type": "integer",
                "description": "Number of principles in the catalog (currently 13)."
              },
              "languages": {
                "type": "integer",
                "description": "Number of languages each principle is translated into (currently 15)."
              },
              "generatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp of when this catalog was last regenerated from source data."
              }
            }
          },
          "_links": {
            "type": "object",
            "description": "HATEOAS navigation to related resources.",
            "properties": {
              "self": { "type": "string" },
              "traceability": { "type": "string", "description": "MH paragraph mapping for each principle." },
              "compass": { "type": "string", "description": "Generate a compass that includes these principles." },
              "llmsTxt": { "type": "string", "description": "Project-level llms.txt." },
              "soulMd": { "type": "string", "description": "Project soul / mission statement in markdown." }
            }
          },
          "tiers": {
            "type": "array",
            "description": "The 3-tier organization. Tier 0 (Foundational) is anthropological bedrock; Tier 1 (Classical CSD) covers established Magisterium; Tier 2 (AI-Distinctive) is Magnifica Humanitas's distinctive contribution for the AI age.",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string", "description": "Tier index (0-2)." },
                "principleKeys": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string",
                      "enum": ["foundational", "classical_csd", "ai_distinctive"],
                      "description": "Tier identifier."
                    },
                    "principles": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "Principle keys in this tier, in canonical order."
                    }
                  }
                }
              }
            }
          },
          "principles": {
            "type": "array",
            "description": "The 13 principles. Each entry has a stable `key`, an MH paragraph reference, and translations in all 15 languages.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Stable identifier (e.g., 'human_dignity', 'subsidiarity'). Use in API calls and citations."
                },
                "mhParagraphs": {
                  "type": "string",
                  "description": "MH paragraph range (e.g., '50-58'). Citation-ready."
                },
                "translations": {
                  "type": "object",
                  "description": "Map of BCP 47 language tag → translation object. Each translation has `name`, `shortDescription`, `systemPromptText` (the operational language used in the compass), and `mhQuote` (a direct citation from the encyclical).",
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "shortDescription": { "type": "string" },
                      "systemPromptText": { "type": "string", "description": "Operational guidance language — what the AI should DO with this principle." },
                      "mhQuote": { "type": "string", "description": "Direct quotation from the encyclical." }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "TraceabilityResponse": {
        "type": "object",
        "required": ["_meta", "foundations", "principles"],
        "description": "Per-element traceability mapping back to specific Magnifica Humanitas paragraphs, with convergence scores from 4 independent extraction methods.",
        "properties": {
          "_meta": {
            "type": "object",
            "description": "Provenance + integrity metadata for the traceability index."
          },
          "_links": {
            "type": "object",
            "description": "HATEOAS links to related resources."
          },
          "foundations": {
            "type": "array",
            "description": "The 5 foundations of the value hierarchy (Dignity, Truth, Common Good, Justice, Peace), each mapped to its MH paragraphs.",
            "items": { "type": "object" }
          },
          "principles": {
            "type": "array",
            "description": "Per-principle traceability entries. Each includes the principle key, MH paragraph range, convergence score, tier, chapter ref, and structural role.",
            "items": { "type": "object" }
          },
          "_validation": {
            "type": "object",
            "description": "Integrity summary. `allConvergence` should be '4/4' across all principles — anything lower flags a candidate for re-review.",
            "properties": {
              "allConvergence": { "type": "string", "description": "Convergence score uniform across all entries (e.g., '4/4')." },
              "methodsCount": { "type": "integer", "description": "Number of independent extraction methods used (currently 4)." }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "description": "Error envelope returned for 4xx responses. Includes the rejected value and a list of allowed values so agents can self-correct without re-reading the OpenAPI spec.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human + agent-readable error message."
          },
          "allowed": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Valid values for the rejected parameter. Agents should pick one of these and retry."
          },
          "received": {
            "type": "string",
            "description": "The rejected value, echoed back for clarity."
          }
        }
      }
    }
  }
}