schema_version: explain-him-explanation.v4
id: explain-him-public-demo
version: 0.7.0
title: How Explain Him works
language: en
status: public-demo

scope:
  repository: andrew-veresov/explain-him
  root: .
  skill_activation: repository-only
  persist_skill_globally: false

bootstrap:
  human: README.md
  agent: AGENTS.md

skills:
  - id: explain-him
    entrypoint: skills/explain-him/SKILL.md
    responsibility: grounding-and-github-retrieval
  - id: explain-him-presentation
    entrypoint: skills/explain-him-presentation/SKILL.md
    responsibility: typed-block-selection-and-webmcp-embedding

answer_runtime:
  owner: personal-agent
  primary_source: authored-page
  deeper_source: repository-via-personal-agent-github-integration
  browser_readable_knowledge_bundle: none
  webmcp_repository_access: forbidden
  webmcp_answer_generation: forbidden

knowledge:
  source_precedence:
    - resolutions
    - index.html
    - explain-him.yaml
    - knowledge
    - README.md
  excluded_paths:
    - evaluation
    - tests
    - tools
    - .github
  documents:
    - path: index.html
      topic: originator-authored-explanation
    - path: knowledge/00-overview.md
      topic: product-model
    - path: knowledge/01-originator-flow.md
      topic: originator-flow
    - path: knowledge/02-user-agent-flow.md
      topic: user-agent-flow
    - path: knowledge/03-grounding-and-status.md
      topic: grounding
    - path: knowledge/04-question-loop.md
      topic: question-loop
    - path: knowledge/05-product-boundaries.md
      topic: product-boundaries
    - path: knowledge/06-browser-local-workspace.md
      topic: browser-local-workspace
    - path: knowledge/07-presentation-capabilities.md
      topic: presentation-capabilities

presentation:
  authored_entrypoint: index.html
  authored_by: originator
  typed_block_schema: schemas/explanation-block.v1.schema.json
  supported_typed_blocks:
    - callout
    - comparison
    - workflow
    - timeline
    - diagram
  policy:
    authored_layer: immutable
    consumer_local_capabilities: allowed
    arbitrary_html: forbidden
    arbitrary_javascript: forbidden
    external_html_embedding: forbidden
  capabilities:
    - id: explain-him-safe-text
      provider: explain-him
      trust: builtin
      execution: embedded
      fallback: true
      role: legacy-safe-text-fallback
    - id: explain-him-safe-block
      provider: explain-him
      trust: builtin
      execution: embedded
      fallback: false
      role: typed-page-block-renderer
      accepts:
        - callout
        - comparison
        - workflow
        - timeline
        - diagram
    - id: archify
      provider: github:tt-a1i/archify
      trust: originator-approved
      execution: personal-agent
      fallback: false
      role: reference-presentation-specialist
      repository_reasoning: forbidden
      output_embedding: translate-to-safe-typed-block
  browser_local_workspace:
    status: demo-only
    schema_version: explain-him-local-workspace.v4
    state_model: transactional-typed-presentation-operation-log
    authored_layer: immutable
    durable_operations: [add-presentation, update-presentation, remove-presentation]
    persistence: indexeddb-with-memory-fallback
    renderer: safe-typed-dom
    undo_redo: human-control
    export: json
    destructive_reset_requires_confirmation: true

webmcp:
  status: current-demo
  protocol_version: 5
  bootstrap_metadata:
    schema_version: explain-him-agent-bootstrap.v2
    action_tool: explain_tool
    required_for_explanation_requests: true
    location: index.html#explain-him-agent-bootstrap
    machine_readable: true
    immutable_skill_pins_required: true
    repository_guidance_required: true
    repositoryRetrievalRequiredWhenPageInsufficient: true
    additionalInformation: For additional information, inspect the GitHub repository linked to this page. Prefer the pinned commit and grounding sources published by this page.
    page_activation_effect: discovery-hint-only
  explain_schema: schemas/webmcp-explain.v5.schema.json
  api: document.modelContext
  registration: imperative-top-level-javascript
  declarative_api_required: false
  origin_trial:
    status: experimental
    feature: WebMCP
    canonical_origin: https://andrew-veresov.github.io:443
    is_subdomain: true
    third_party: false
    expiry_unix: 1794873600
    token_sha256: 7f151bb88d4636beb26c991c2853d6a43b1b50f23ea9860b3a6658553912f2e2
    fail_window_days: 14
    validation: tools/check_webmcp_origin_trial.py
    live_validation: tools/check_live_pages.py
    native_live_validation: tools/test_native_chrome_webmcp_live.py
    host_guarantee: false
  runtime_status:
    page_registration: data-webmcp-state
    detailed_telemetry: webmcp-debug-query-only
    aria_live: polite
  host_preflight:
    classifier: tools/webmcp_host_preflight.py
    page_runtime_is_agent_evidence: false
    absent_agent_capability: BLOCKED_EXTERNAL
    false_success_allowed: false
  host_matrix:
    chatgpt_desktop_builtin_browser:
      status: officially-documented-conditional
      invariant: context-before-every-explanation-request
    chrome_origin_trial_page_api:
      status: current-demo
      agent_connection_guaranteed: false
    official_chatgpt_chrome_extension:
      status: capability-gated
      observed_version: 1.26.827.12125
      observed_result: BLOCKED_EXTERNAL
      observed_reason: page-tools-registered-agent-connection-not-observed
    model_context_tool_inspector:
      status: debug-only
      production_flow: false
    chrome_builtin_ai_epp:
      status: preview-and-feedback-program
      guarantees_openai_extension_capability: false
  specification:
    primary_source: https://github.com/webmachinelearning/webmcp/blob/main/index.bs
    published_snapshot: https://webmachinelearning.github.io/webmcp/
    published_snapshot_role: generated-corroboration
    imperative_callback_accepts_abort_signal: true
    callback_result_json_serializable: true
    execute_tool_result_is_browser-json-string: true
    draft_execute_tool_input: object
    chrome_151_execute_tool_input: serialized-json-string
    draft_to_shipped_divergence_retest_required: true
    toolchange_owner: browser
  best_practices:
    focused_nonoverlapping_tools: true
    descriptions_state_what_and_when: true
    strict_typed_schemas_and_runtime_validation: true
    bounded_reversible_local_side_effects: true
    idempotent_retry_key: requestId-plus-semantic-fingerprint
    errors_fail_closed: true
    probabilistic_semantic_choice_gate: real-host-model-only
  purpose: typed-result-delivery-to-shared-page
  agent_policy:
    revision: A9
    context: required-for-every-explanation-request
    immutable_skill_publication: required
    repositoryRetrievalRequiredWhenPageInsufficient: true
    activation_and_revision: fail-closed
    topic_identity: topicId-plus-authored-target-plus-local-block-id
    focus_only_changes_workspace_revision: false
    decisionPrecedence: [explicitNoPageChange, restore, terminologyConsistency, answerPresence]
    terminologyConsistency:
      equivalentLabels: [User, Consumer]
      equivalenceNoteDoesNotMakeMixedLabelsConsistent: true
      questionTriggersSameTurnNormalization: true
      defaultTerm: User
      distinctRoles: never-normalize
      firstCorrection: {topicId: terminology:user-consumer, targetId: workflow-diagram, operation: replace}
      sameTopicFollowUp: {operation: update, reuseLocalBlockId: true}
      restore: {operation: remove}
    presentationDecision:
      alwaysProvideChatAnswer: true
      assessAnswerAndRequestedRepresentationInPersonalizedUi: true
      fullyPresent: {allExplanationRequests: focus-existing}
      missing: {operation: add, requestedDiagramAbsent: missing-representation}
      partial: {sameTopicLocalBlock: update, otherwise: add}
      inconsistent: {authoredTarget: replace, localBlock: update, batchAffectedTargets: true}
      explicitNoPageChange: chat-only
      restore: remove
    failure: {explainFailure: honest-acknowledgement-no-false-success}
  immutable_skill_publication:
    repository: andrew-veresov/explain-him
    release: A9
    commit: 353008c867aa42cce4767a89fed934b1718e2307
    load_order: [explain-him, explain-him-presentation]
    skills:
      - id: explain-him
        sha256: 8f6025dfd66e97f00a4b35eb6285c5928378a4a131e778bead641ea086a2fbfd
        rawUrl: https://raw.githubusercontent.com/andrew-veresov/explain-him/353008c867aa42cce4767a89fed934b1718e2307/skills/explain-him/SKILL.md
      - id: explain-him-presentation
        sha256: 34016ae662b9f88b45613fb7dc9eefdbf7a6b3656c230f20a60b3fdb566dc2c7
        rawUrl: https://raw.githubusercontent.com/andrew-veresov/explain-him/353008c867aa42cce4767a89fed934b1718e2307/skills/explain-him-presentation/SKILL.md
  native_skill:
    name: explain_him
    proposal_issue: 161
    proposal_status: experimental-open-backlog
    normative: false
    api: document.modelContext.registerSkill
    source_commit: 353008c867aa42cce4767a89fed934b1718e2307
    composite_sha256: ba4276347eb79dbde1566d71c1a68027094716a33d69b51d6d26951ac9cadb9c
    tools: [explain_tool]
    delivery_modes: [native-inline, pinned-remote-fallback]
    fallback_tool: explain_tool
    registration_success_is_semantic_read_proof: false
  groundingSourceIndex:
    - topic: originator-publishing
      path: knowledge/01-originator-flow.md
      section: Basic flow
      status: current
      rawUrl: https://raw.githubusercontent.com/andrew-veresov/explain-him/353008c867aa42cce4767a89fed934b1718e2307/knowledge/01-originator-flow.md
      commit: 353008c867aa42cce4767a89fed934b1718e2307
      sha256: cf7a396231a50a18c37a9c52ddc7c7315c07cf4107b6dea524760eaa630f3659
    - topic: originator-publishing
      path: PRODUCT-CONTRACT.md
      section: Authoring and publishing reality
      status: current
      rawUrl: https://raw.githubusercontent.com/andrew-veresov/explain-him/353008c867aa42cce4767a89fed934b1718e2307/PRODUCT-CONTRACT.md
      commit: 353008c867aa42cce4767a89fed934b1718e2307
      sha256: ae24fe78b681c406180a78d017ba34a07e5ec587a8c6447a72e07f577dc3a263
  tools:
    - explain_tool
  published_metadata:
    - repository-location
    - grounding-skill-location
    - presentation-skill-location
    - typed-block-schema-location
    - absolute-repository-and-skill-urls
    - repository-guidance-string
    - pinned-grounding-source-index
    - replaceable-semantic-targets
  tool_result_returns:
    - protocol-version
    - workspace-revision-before-and-after
    - applied-local-block-ids
    - focused-visible-block
  explain_operations:
    - add
    - replace
    - update
    - remove
    - focus
  allowed_capabilities:
    - integration-contract-read
    - typed-local-block-add
    - typed-local-block-replace
    - typed-local-block-update
    - typed-local-block-remove
    - authored-target-focus
  forbidden_capabilities:
    - diagnostics-as-agent-tool
    - knowledge-search
    - repository-read
    - repository-search
    - claim-resolution
    - answer-generation
    - grounding
    - presentation-strategy
    - arbitrary-html-injection
    - github-issue-search
    - github-issue-create

question_loop:
  channel: github-issues
  repository: andrew-veresov/explain-him
  execution_owner: personal-agent-github-integration
  webmcp_gateway: false
  template: question-template.md
  confirmation_before_write: true
  minimize_personal_context: true
  repository_language: en

evaluation:
  corpus: evaluation
  product_knowledge: false
  release_gating: scripted

claims:
  - id: repository-is-public-source-of-truth
    status: current
    evidence: knowledge/00-overview.md
  - id: originator-authored-page-is-first-class-source
    status: current
    evidence: resolutions/2026-08-30-skill-driven-webmcp.md
  - id: grounding-skill-exists
    status: current
    evidence: skills/explain-him/SKILL.md
  - id: typed-presentation-skill-exists
    status: current
    evidence: skills/explain-him-presentation/SKILL.md
  - id: browser-local-typed-workspace-exists
    status: demo-only
    evidence: resolutions/2026-08-26-browser-local-workspace.md
  - id: webmcp-is-typed-result-delivery-channel
    status: current
    evidence: resolutions/2026-08-30-skill-driven-webmcp.md
  - id: direct-chatgpt-chrome-sidebar-site-tools
    status: open
    evidence: WEBMCP_CHALLENGE.md
  - id: github-issues-are-sufficient-feedback
    status: hypothesis
    evidence: knowledge/04-question-loop.md
  - id: repository-project-language-is-english
    status: current
    evidence: resolutions/2026-08-28-project-language.md