Update to Clara

{
  "description": "Prepare and operate Clara-hosted external voice interviews: select an exact versioned research campaign or define a scoped one-off case interview, create an expiring no-login participant link, check its status, and retrieve the completed JSON bundle and post-interview quality review. Use when the user asks to interview a client, stakeholder, expert, research participant, or other external respondent through a hosted browser link, or asks to retrieve or review that interview's result. Do not use for interviewing the user in chat, advisor voice debriefs, uploading or transcribing existing recordings, bulk outreach or email campaigns, or importing Hosted Voice bundles.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 274
    }
  ],
  "name": "hosted-interview",
  "skill_md_contents": "---\nname: hosted-interview\ndescription: \"Prepare and operate Clara-hosted external voice interviews: select an exact versioned research campaign or define a scoped one-off case interview, create an expiring no-login participant link, check its status, and retrieve the completed JSON bundle and post-interview quality review. Use when the user asks to interview a client, stakeholder, expert, research participant, or other external respondent through a hosted browser link, or asks to retrieve or review that interview's result. Do not use for interviewing the user in chat, advisor voice debriefs, uploading or transcribing existing recordings, bulk outreach or email campaigns, or importing Hosted Voice bundles.\"\n---\n\n<!-- CLARA_OPENAI_ONBOARDING_BEGIN -->\nOnboarding is optional. Continue ordinary professional work immediately,\nincluding direct specialist invocation, without checking or completing a local\nonboarding profile. Missing, unfinished, inaccessible or corrupt onboarding state,\nor unavailable voice/window controls, must never block ordinary work. Do not\nautomatically start, resume or repeatedly offer onboarding.\nOnly for a user-requested tutorial or a native teaching handoff, read\n`../clara/references/local-onboarding.md`. A verified paired lesson worker\nexecutes only its bound lesson and token; never bypass tutorial validation.\nTutorial profiles, progress, examples and feedback remain local; never send a\nchange request, stamp a tutorial receipt or call hosted interviews for a tutorial.\nCurrent user requests take precedence over saved preferences.\n<!-- CLARA_OPENAI_ONBOARDING_END -->\n\n# Interview\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n\n## Output Location Rule\n\nNever write run outputs inside this Git workspace, `static/shared`,\n`protected_downloads`, or another static-site folder. Keep receipts, briefs,\nbundles, reviews, and `codex_run_review.md` in the user's project/output folder.\n\nUse this skill for the external-participant workflow. An authenticated preparer\ndefines the brief and creates a bearer link; the participant opens that link\nwithout signing in and speaks with Clara's adaptive browser interviewer for up\nto 15 minutes. This is separate from `transcribe`, which captures or imports an\nadvisor discussion or existing recording.\n\n## Boundaries\n\nThis skill owns:\n\n- selecting one exact registered campaign or drafting one scoped custom brief;\n- choosing `case_interview` or `research_interview` from the intended output;\n- creating a participant-specific expiring link only when the user asks;\n- checking a known link's status;\n- retrieving its JSON bundle and post-call quality review before expiry;\n- handing the retrieved evidence to the main `clara` case workflow only when\n  the user explicitly asks to add it to a case.\n\nIt does not own:\n\n- interviewing the user in chat;\n- consultant debriefs, uploaded recordings, or Hosted Voice bundles—use\n  `transcribe`;\n- deck changes from spoken feedback—use `deck-correction`;\n- bulk outreach, invitation email, campaign-registry changes, revocation,\n  raw-media download, or cross-interview synthesis;\n- treating the generated review as proof that every statement is correct.\n\nThe participant URL is a bearer credential. Show it to the requesting user, but\nnever send it to another person or mailing list unless the user explicitly asks\nfor that external action. Keep it in the private `0600` receipt written by the\nhelper; never put the URL/token, authentication cookies, or magic links directly\nin command arguments, shell history, ordinary logs, or source files.\n\n## Interview Modes\n\nUse `case_interview` when the output should represent one situation deeply:\ncontext, chronology, constraints, decisions, risks, bottlenecks, and unresolved\nquestions. Use `research_interview` when the output must preserve natural\nconversation while covering common dimensions well enough for later comparison.\n\nDo not turn either mode into a fixed questionnaire. A custom brief supplies the\npurpose, context, priority topics, prepared questions, red flags, and boundaries;\nthe server-side interviewer decides how to cover them adaptively.\n\nSupported configured languages are `it`, `en`, `fr`, `de`, and `es`. The participant\npage uses microphone audio. Do not promise screen capture or raw-media download.\n\n## Authenticated Helper\n\nRun commands from the Clara plugin directory. Keep the magic link or Cookie\nheader in a temporary local file with restrictive permissions. Prefer the magic\nlink file; delete the secret file after the authenticated operation.\n\nCheck the plugin environment before using the helper:\n\n```bash\npython scripts/check_dependencies.py\n```\n\nList the registered versioned campaigns:\n\n```bash\npython scripts/manage_hosted_interview.py \\\n  --magic-link-file <private-magic-link.txt> \\\n  list-campaigns --output <project-output-folder>/interview_campaigns.json\n```\n\nThe currently registered campaigns are returned by the server. Never guess an\nID, silently fall back to another brief, or reuse an ID after its meaning has\nchanged.\n\nPrepare one participant link from an exact campaign:\n\n```bash\npython scripts/manage_hosted_interview.py \\\n  --magic-link-file <private-magic-link.txt> \\\n  prepare-campaign <exact-campaign-id> \\\n  --case-id <non-sensitive-participant-id> \\\n  --participant-name \"<participant>\" \\\n  --language it \\\n  --output <project-output-folder>/hosted_interview_receipt.json\n```\n\nFor a one-off interview, Codex writes a private brief JSON and submits it:\n\n```bash\npython scripts/manage_hosted_interview.py \\\n  --magic-link-file <private-magic-link.txt> \\\n  prepare <project-output-folder>/hosted_interview_brief.json \\\n  --output <project-output-folder>/hosted_interview_receipt.json\n```\n\nThe custom brief uses the server contract:\n\n```json\n{\n  \"interview_campaign_id\": \"client-operations-interview-v1\",\n  \"case_id\": \"participant-001\",\n  \"case_name\": \"Operations discovery\",\n  \"participant_name\": \"Participant name\",\n  \"client_project\": \"Project label\",\n  \"interview_title\": \"Operations interview\",\n  \"interviewee_role\": \"Operations lead\",\n  \"interview_mode\": \"case_interview\",\n  \"language\": \"it\",\n  \"purpose\": \"Understand the current operating bottlenecks.\",\n  \"participant_intro\": \"A short participant-facing explanation.\",\n  \"background_context\": \"Private context for the interviewer.\",\n  \"hypotheses_to_test\": [],\n  \"priority_topics\": [],\n  \"questions\": [],\n  \"red_flags\": [],\n  \"boundaries\": [\"Do not ask for confidential client details.\"],\n  \"expires_in_hours\": 168\n}\n```\n\nThe custom campaign ID must be a lowercase, hyphenated, explicitly versioned\nidentifier ending in `-v1`, `-v2`, and so on. Treat `participant_name`,\n`case_name`, `interview_title`, and `participant_intro` as participant-visible.\nIf `participant_intro` is empty, the public page falls back to `purpose`, so the\npurpose must also be participant-safe in that case. The unauthenticated status\nendpoint exposes `case_name` and `interview_title`. Keep all of those fields\nnon-sensitive; only the remaining brief fields are private interviewer context.\nThe helper restricts both the input brief and output receipt to local `0600`\npermissions.\n\nIf no authentication material is available, the helper can request a magic\nlink and prompt for it:\n\n```bash\npython scripts/manage_hosted_interview.py \\\n  --request-magic-link <authorized-email> list-campaigns\n```\n\nDo not claim link creation succeeded until the server returns `public_url`,\n`expires_at`, and `interview_campaign_id`.\n\n## Completion and Retrieval\n\nCheck a known participant link without putting its bearer token in the command:\n\n```bash\npython scripts/manage_hosted_interview.py status \\\n  --receipt <project-output-folder>/hosted_interview_receipt.json \\\n  --output <project-output-folder>/hosted_interview_status.json\n```\n\nIf no receipt exists, save the participant URL by itself in a private local file\nand use `--participant-link-file <private-link.txt>`. Never paste it as a\npositional command argument.\n\nStatuses include `ready`, `started`, `completed`, `failed_technical`,\n`incomplete`, and `unusable`. An unchanged status is not an error. Do not create\na replacement link unless the user asks or the known link cannot be retried.\n\nAfter completion, retrieve the bundle and review before the bearer link expires:\n\n```bash\npython scripts/manage_hosted_interview.py \\\n  --magic-link-file <private-magic-link.txt> \\\n  bundle --receipt <project-output-folder>/hosted_interview_receipt.json \\\n  --output <project-output-folder>/hosted_interview_bundle.json\n\npython scripts/manage_hosted_interview.py \\\n  --magic-link-file <private-magic-link.txt> \\\n  review --receipt <project-output-folder>/hosted_interview_receipt.json \\\n  --output <project-output-folder>/hosted_interview_review.json\n```\n\nThe bundle contains the prepared record, completion data, current-run events,\ntranscript material, media metadata, and any generated review. It is not a ZIP\nand does not contain raw audio or video bytes. The review should distinguish\nevidence-backed claims, uncertainties, contradictions, missed opportunities,\nand follow-up questions. Inspect the transcript evidence before repeating any\nreview conclusion.\n\nThere is no automatic hosted-interview-to-case importer. If the user asks to\nuse the result in a Clara case, preserve the downloaded JSON as source material,\nthen use the main `clara` workflow to index and interpret it. Do not pass it to\nthe Hosted Voice bundle importers; the schemas are different.\n\n## Codex-Native Run UX\n\nUse a short checklist covering brief selection, participant fields,\nauthentication, link creation, status, retrieval, and handoff.\n\nBefore creating a link, show a compact Run Intake table with interview mode,\ncampaign or custom brief, participant, language, expiry, boundaries, receipt\nfolder, and whether any external sending was requested. Use a Decision Table\nonly for unresolved material choices such as case versus research mode, a\nmissing exact campaign ID, an ambiguous participant-facing introduction, or a\nboundary that materially changes the interview.\n\nDefault output policy: create one participant link plus a private receipt, then\nretrieve a bundle and quality review only when the interview completes or the\nuser asks. These are not choices to propose when the user asked for the normal\nhosted-interview lifecycle. Creating a participant link is the approval\ncheckpoint; sending it to someone is a separate external action and requires\nexplicit authorization.\n\nBefore write-heavy or external work, show an execution checkpoint naming the\nauthenticated endpoint, non-secret inputs, expected receipt, and external side\neffect. End with an Artifact Card listing the participant link, expiry, status,\nreceipt, bundle, review, and any unavailable artifact. Create\n`codex_run_review.md` only when the run is blocked or exposes a repeatable gap.\nNever edit generated ZIPs during a run.\n"
}