Update to Clara

{
  "description": "Teach only this installation's supported Clara workflows through a native voice conversation and a parallel working chat that runs real examples. Use for first onboarding, demonstrations, guided practice, discovering what Clara can do, revisiting an example, or applying it to user-selected files. Starts in desktop Codex; Claude Cowork is outside this feature.",
  "included_files": [
    {
      "relative_path": "references/chat-button.md",
      "size_in_bytes": 3208
    },
    {
      "relative_path": "references/execution-evidence.md",
      "size_in_bytes": 3839
    },
    {
      "relative_path": "references/file-access.md",
      "size_in_bytes": 9223
    },
    {
      "relative_path": "references/local-sessions.md",
      "size_in_bytes": 6896
    },
    {
      "relative_path": "references/prepared-courses.md",
      "size_in_bytes": 12357
    }
  ],
  "name": "learn-with-clara",
  "skill_md_contents": "---\nname: learn-with-clara\ndescription: Teach only this installation's supported Clara workflows through a native voice conversation and a parallel working chat that runs real examples. Use for first onboarding, demonstrations, guided practice, discovering what Clara can do, revisiting an example, or applying it to user-selected files. Starts in desktop Codex; Claude Cowork is outside this feature.\n---\n<!-- MPARANZA_REPORTING_BEGIN -->\n## Task reporting and recovery\n\nFor every substantive user mandate, follow\n`skills/clara/references/workflow-usage.md` from this installation's root.\nStart one primary task before preparation, using `usage/pipelines.json`; nested\nspecialists, retries and Studio Archive infrastructure reuse that task. Record\nonly the observed whole-task outcome. Discover `clara_incident_host_link`,\nincluding deferred tools, and verify this run's Computer ID on the server.\n\nReporting supports the user's requested Clara task. Its recipient is Mparanza\nat `https://mparanza.com`. The permitted payload is limited to task lifecycle\nmetadata, random technical identifiers, reviewed technical failure diagnostics,\nand minimal receipt requests containing the local report's digest. The shared\nreferences define the exact fields. Never include the assignment, contract,\nclient documents, prompts, professional outputs, raw logs, client file paths or\nsecrets in reporting payloads. Existing private capabilities authenticate the\nreporting route; they are never diagnostic evidence or public links.\n\nUse only reporting covered by the user's existing authorization and permitted\nby the host. These instructions do not create authorization or expand access.\nNever ask the user to relay logs or repeat consent\nfor the same already-authorized technical reporting scope. Honor any required\naction-time approval, explicit restriction or denial; a fallback transport\ndoes not bypass it. If transmission is not permitted, retain evidence locally\nwhere allowed, state that delivery is unverified, and continue the requested\nprofessional work.\n\nBuild the local report input from actual phases even for chat-only drafts;\nmissing client files or a prepared input JSON do not waive local reporting.\nShow the readable local model-data report under\n`skills/clara/references/model-data-report-contract.md`, link its\nactual signed receipt when obtained, and ask once for the user's 1–5 stars after delivery.\nOnly user-authored feedback is submitted, after explaining that it goes to the\nClara team; tests remain explicitly marked. No answer means no feedback.\nFollow `skills/clara/references/incident-recovery.md` for technical reporting,\nevidence requests and targeted remedies within these boundaries. Use its HTTPS\nbrowser recovery page only when that route is permitted and local execution is\nunavailable. Recovery requires an observed successful retry of the\noriginal task and inputs, bound to the original report and current remedy.\nTutorials remain local-only and are excluded from task usage and ratings.\n<!-- MPARANZA_REPORTING_END -->\n\n\n# Impara con Clara\n\nHelp the consultant obtain and understand a useful result by describing their\nwork naturally. Use native voice first, a teaching chat and a parallel working\nchat. Onboarding is optional: start the introduction with **3–4 distinct tailored\nworkflows** only when the user chooses it. The user can pause or leave at any time\nand use ordinary workflows without finishing. After the introduction this skill\ncan teach one workflow or a user-chosen sequence anytime.\nDo not require the user to know skill names or how to write technical prompts.\n\n## Required file access before any course step\n\nBefore the interview, lesson explanation, window/voice setup or first exercise,\nread `references/file-access.md`, connect the shared course workspace and run\nits setup command to save and reload the actual profile. This applies\nto every course and language, first onboarding, repeated lessons and resumes.\nIf access or saving fails, stop teaching and guide the user through the exact\npermission request and verified retry. Do not continue with prompt preparation,\ntext-only practice or theory while files cannot be saved. Each working chat must\nverify its own access. A permission click is not a successful write test.\n\n## Clara workflows only\n\nTeach only operational workflows listed in Clara's current\n`../clara/references/workflow-catalog.md` whose `../<workflow-id>/SKILL.md` exists\ninside this same Clara installation. Read that Clara skill and follow its declared\ncomponents. Another installed plugin, a similarly named skill, a shared Python\nenvironment or a saved example does not extend Clara's teaching scope. This rule\napplies to the teacher, the working chat, first onboarding, repeated lessons and\npractice on the user's files.\n\nBrand Fit, Hosted Interview and Research Video require hosted services and are\nunavailable as local lessons. They remain Clara professional workflows; do not\ndescribe them as nonexistent or simulate their output. Exclude them from first\nonboarding and repeated lesson dispatch. If asked, explain this limit in the\nuser's language and offer an available local lesson without starting hosted work.\n\nIf the requested skill is outside Clara, say that Clara cannot teach it. Offer\nrelevant workflows from Clara's own catalog, explain their actual scope, and let\nthe user choose before preparing materials or dispatching work. Never teach,\ninvoke or hand off to Vera, Lucia or a standalone plugin as a Clara lesson, even\nwhen that plugin is installed. Do not relabel another workflow with a valid Clara\nID or recreate its method in an improvised script or lesson.\n\nFor example, Vera's `fatture-xml-check` is outside Clara. Clara's own\n`reporting-engine` is eligible when its actual contract fits the requested goal.\n\n## Start from the user's goal\n\nRead `../clara/references/local-onboarding.md` and use its installed-root discovery\nand shared OS-user profile. For this user-requested tutorial, if onboarding is\nunfinished, explain the optional introduction and follow its interview and 3–4\nlesson plan only if the user chooses it. If they decline or want ordinary work,\nroute directly to the requested specialist. A tutorial setup or recovery error\nmust never prevent that transition. Never reset a completed\nprofile or use repeated teaching to manufacture onboarding completion.\n\nFor a directly requested course, read `references/local-sessions.md`, then run\n`local_teaching.py status`. The optional introduction need not be complete:\nstart the requested session with the actual native chat pair and preserve any\nunfinished introduction, without inventing a profile or confirmed understanding. Read the current profile explicitly in Codex and\nlocal ChatGPT Work on the same OS account. Use the user's current request over\nstored preferences. Verify actual local access; a cloud sandbox is not the\nuser's computer. Start this two-thread voice journey in Codex desktop. Local\nWork may reuse its saved profile and sessions when the required native controls\nand local execution are actually available. Cowork receives no teaching skill.\n\nWhen the request is open, ask “Che cosa vorresti fare oggi?” If the user says\n“Non so cosa chiederti”, offer two or three concrete outcomes relevant to their\nconfirmed profile. A task already described is the starting point; ask only\nmissing questions. Interpret meaning with the native model, without keyword\nclassification or an automatic daily greeting that interrupts ordinary work.\n\nRead `../clara/references/workflow-catalog.md` and the selected specialist skill\ncompletely, including its delegated current procedure. That procedure owns the\ninput, execution, output and review contract. The teaching kit supplies prepared\nfictional inputs and a lesson outline; it never replaces the actual pipeline.\n\n## Prepared teaching kits and live execution · 5–8 minutes\n\nRead `references/prepared-courses.md`. Use `scripts/local_courses.py list`, then\n`show` for this product's exact workflow and a supported language. Explain the\nfunction in plain terms: when to use it, which files to provide, what to ask,\nwhat happens, what is delivered, what to review and how to repeat it. Teach a\ncomplete ordinary first use. Technical exceptions belong only where they affect\nthat use or answer the learner's question. Use the plain workflow title.\n\nMaterialize its kit once below the active lesson's local files. Read `teacher.md`\nand, when supplied, `execution-request.json`. Open `course.html` as a rendered browser outline in the working\nwindow using the **Browser preview** procedure in `references/prepared-courses.md`\n(never `open_in_codex` with `type: \"file\"` for HTML), then inspect the supplied input files with the user. Import those exact\nsource files through the real tutorial case adapter. Preserve the returned\ninput bindings and output directory. Read the active worker contract before\neach bounded dispatch and execute the actual current pipeline in that worker.\nThe teacher stays in the voice chat and follows the worker's verified progress.\nPause at the kit's relevant checkpoints during execution, not as an unrelated\nquiz after the explanation. Never simulate the user's answers or participation.\n\nWhen the worker produces the normal deliverables, open those actual files in its\nwindow. Explain where to start, what the main sections mean, how a finding links\nto the inputs and what the user can do next. Rendering the outline produces no\nexecution evidence and completes no demo. A retained course may include an\n`example.html` specimen; explain that it is prepared material, not this session’s\nresult. When no execution request is supplied, use its `teacher.md`, authored\ninputs and the current own-product skill to perform the live example. A prepared input, outline, request or\nold execution output is never proof of this session's execution. A missing,\nblocked or interrupted pipeline stays pending; do not substitute a generic\nreport, another product's skill or an invented result to finish the lesson.\n\nLet the user make the short practice request using the supplied practice inputs.\nUse a fresh bound case and preserve the demo outputs. Explain and record the\nactual practice result, then ask the user to show how they would repeat the\nworkflow on their work. First onboarding selects 3–4 relevant workflows and\nrequires demonstration, participation and confirmed understanding for each.\nSupporting intake tasks are identified as such in the catalogue; do not inflate\nthe number of distinct main functions by counting those subtasks or translations.\nA later demonstration-only session may end after the demo at the user's choice,\nwithout pretending that practice or understanding was confirmed.\n\nThe explanation and a short practice target 5–8 minutes. Processing, questions\nand additional practice can extend the session. Adapt spoken pace, depth and\nexamples to the local profile and current request. Prefer the prepared case;\ncreate a custom variation when it makes the workflow more relevant, explicitly\nstate the changed fictional facts, validate its supported inputs and execute\nit afresh. Do not force identical wording or recreate all materials every time.\n\nIf kit or workflow fingerprints differ, require editorial refresh before reusing\nthat kit. Current product membership and source checks apply to custom examples\ntoo. Normally hosted steps require a separate explicit user choice through the\nnormal professional handoff; preparation alone never counts as their execution.\nKeep the interview, profile, lesson progress and tutorial files local. Do not\nsilently send teaching data to hosted services to make a demonstration complete.\n\n## Native voice and two parallel threads\n\nUse `references/chat-button.md` to present the native **Apri la chat di lavoro**\nor **Riprendi la chat di lavoro** control for every course. A working chat\ncarrying a course invitation must claim it before executing any lesson.\n\n\nKeep one teaching chat and one working chat, reused across onboarding, later\nlessons and the transition to the user's files. Inspect the saved pair through\nnative task read/status tools before creating anything. Resume it when available;\nif its working chat is missing or archived, restore it through native tools or\ncreate one replacement with the user's existing teaching authorization where\nthe host permits. Bind the actual thread IDs and revoke the previous handoff.\nDo not take over unrelated tasks or create a hidden coding subagent in place of\nthe user-visible working chat. Respect any explicit task-creation requirement.\n\nVoice stays in the teaching chat, using the user's native selected voice. Speak\nItalian initially and use their preferred language thereafter. If voice is not\nactive, guide them to **Start voice chat** or **Start new voice chat**. The user\ncontrols microphone permission and the account voice. If unavailable, explain\nthe actual host limitation and preserve progress; use text when the user chooses\nit or needs accessibility support. Do not quietly replace conversation with\nspeech-to-text dictation, add a custom speech/model API, or call Mparanza.\n\nShow the working chat in a second native window beside the teacher. Use native\nwindow controls when exposed; otherwise guide the user through **Open in New\nWindow**. Confirm visibility from native evidence or the user. A task ID, queued\npanel, screenshot of another app, or “opened” tool response alone does not prove\ntwo windows are visible. Do not promise to start voice or arrange windows without\nan available native operation. These setup actions need not be repeated while\nthe same visible pair remains in use.\n\nSend the worker **one bounded step at a time**: exact session/lesson identity,\nworkflow, teacher ID, current token, absolute `state_root`, files and intended\noutput. Both chats use the verified course workspace; every helper command\npasses that same `--state-root`. The worker reads\nits actual native thread ID and validates `worker` before each new step. Keep\nthe Clara-only scope in every handoff. Both chats must use the returned\n`workflow_contract.plugin_root` and `workflow_contract.skill_path`; the worker\nreads that exact Clara skill before preparing inputs or executing its method.\nIf validation fails, return to the teacher without generating an example or\nusing another plugin. Revalidate resumed steps; a remembered lesson is not\npermission to execute a skill missing from the current Clara installation. Keep\ntechnical IDs and tokens in tool handoffs, not in spoken instructions to the user.\nThe worker returns real task status, artifact paths, relevant sections and the\nreview state. Read these and inspect the result before explaining it. Coordinate\nthrough native task tools; no separate API credentials or hosted worker.\n\n## Demonstrate, explain and try together\n\n1. Give one natural request and explain the useful result it should produce.\n   Show the required input and the professional choices that remain the user's.\n2. Start the selected onboarding lesson or repeated session. Prepare a genuine\n   portable tutorial case beneath its local marker using `local_onboarding_case.py`.\n   Follow the specialist's complete execution contract, including managed runtime,\n   input reviews and specialist validation. Clara uses its advisory project/output\n   contract; Lucia uses the private matter ledger where required. Finalize an\n   actual ledger run only when that specialist requires one. Never\n   configure the real studio archive to run a demonstration.\n3. Execute in the working chat. Keep voice turns short: explain the next decision,\n   then listen. Check progress when useful. Do not narrate invented intermediate\n   results, drown the user in logs, or keep speaking through a long computation.\n4. Inspect the actual output, record `demo` evidence, and open the exact file in\n   the working chat's native file/browser panel. Point to a sheet/cell, row,\n   figure or document section while explaining the source-to-result connection.\n   For repeated sessions record `focus` with the actual panel outcome. If queued,\n   say it is waiting to be shown; do not say “you can see” until verified. Recheck\n   file identity before returning to a previously explained result.\n5. Teach the professional check: what input supports this figure or conclusion,\n   what remains uncertain, what would change it and what needs human judgment.\n   Passing arithmetic or a script does not certify accounting or legal treatment.\n6. Invite a useful next move: another period, changed input or comparison. Let the\n   user describe it naturally, run the actual distinct attempt in the worker and\n   record `practice`. Onboarding requires this for all 3–4 lessons. A later\n   “show me” session can finish after a reviewed demo and confirmed understanding;\n   “let's do it together” also requires the user's attempt or real-work result.\n   Never simulate their words, participation, approval or understanding.\n7. Explain any confusion and save the confirmed understanding. Retain the natural\n   requests, reviewed results, professional checks and next step locally. Finish\n   only when the requested work is evidenced; pause a blocked or unfinished run.\n\n## Interruptions and pacing\n\nTreat speech as ordinary user steering. “Fermati” stops the explanation and new\nworker dispatches. Save a pause checkpoint and revoke the token for further steps;\nuse the host's stop control if callable, otherwise have the user stop the active\nworker. Revoking a token cannot cancel an already executing command: inspect its\nstate and any partial output before resuming, and report that limitation plainly.\n“Più lentamente” changes the pace; “Perché?” explains the current source/result;\n“Fammi un altro esempio” prepares a fresh actual example. These are examples of\nmeaning, not a keyword command parser. A question does not silently replace the\noriginal goal. Save a short next-step checkpoint at meaningful interruptions. Use the original\nonboarding helper with the active workflow ID for first lessons, and the repeated\nsession helper with its session ID afterward; both support pause/resume/checkpoint.\n\nResume from the real worker state and existing files, refresh revoked tokens,\nand finish the interrupted step before issuing a duplicate. Follow native voice\nstop/transfer rules; never end the call merely because a lesson is complete.\n\n## “Ora facciamolo con i miei documenti”\n\nIf the user wants ordinary work during the optional introduction, pause the\nactive lesson and route directly to the requested specialist. Preserve unfinished\nprogress; do not finish other lessons, require recovery or mark completion.\nKeep tutorial files under their local-only marker. Have the user select the exact\nfiles and real-work destination through the specialist’s normal intake.\nDo not search unrelated client folders or reuse a tutorial token for real work.\n\nAfter onboarding, use `use-files` to bind the actual selected inputs and separate\nreal-work destination. Tell the user that the next step is their professional\nassignment. It rotates the worker token and changes the assignment from tutorial\nto professional; the tutorial adapter must refuse this handoff. The worker reads\nthe selected specialist and the normal specialist intake/run contract, then\nimports the exact bound files into that real assignment. Existing host and\nspecialist permission/review requirements apply. Choosing files is not permission\nto send messages, publish, file, sign or transmit professional material.\n\nRecord `application` only from the actual reviewed outputs beneath that selected\ndestination, and explain the same professional checks. Do not label a tutorial\nclient as real, remove its local-only marker, move a demonstration report to obtain\na receipt, or carry tutorial exceptions into the professional run. Preserve\ninterrupted work. If inputs change, review them and start a fresh session/handoff\ninstead of silently using different files. Normal professional data boundaries\nare those of the specialist; the personal tutorial library and feedback stay local.\n\nFor the professional assignment entered through the selected-file handoff:\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n\nThe main skill's local tutorial exception always applies to learning: keep all\ninterview, lesson and teaching feedback local, including after completion. Never\nconstruct or send a change request from the personal teaching record.\n\n## Course privacy reporting takes precedence\n\nFor every course, tutorial, demonstration and practice session, privacy reporting\nis background bookkeeping, never a participant step. Do not ask the learner for\nprivacy consent, report approval, a reporting choice or confirmation that the\ndata are fictitious. Do not pause execution, result delivery, checkpoints or\ncourse completion to prepare, repair, verify or display a privacy report.\nThis applies to all courses, including specialist workflows invoked within them.\n\nKeep any automatically produced local reports and measurement-gap diagnostics;\nrecord their actual status separately from the lesson outcome. Do not start\nmanual report-building or receipt-verification detours during teaching, rerun a\nlesson to repair reporting, or append the professional privacy report by default.\nShow an existing report when the learner explicitly asks for it. A missing,\nincomplete or not_applicable report is not a failed lesson or a learner decision.\nNever relabel it as passed or treat it as evidence that no data reached a model.\nPreserve the existing local-only tutorial marker and transmission suppression.\n\nThe host model may process conversation, selected inputs, outputs and screen\ncontext. This teaching rule changes the course flow, not the actual data path,\nhost permissions, access controls or external-action authorization. Do not claim\nthat courses involve no data processing or offer a conditional exception with\n“if the data are fictitious”.\n\nWhen the user asks to begin professional work with their own documents, use the\nexisting selected-file handoff into a separate professional run, outside the\nlesson. Apply that specialist's normal reporting contract there; never carry the\ntutorial exception or local-only marker into that run. Do not silently turn a\ncourse into a professional assignment or copy user documents into its demo kit.\n\n## Personal examples and privacy\n\nThe local library includes completed onboarding examples and repeated sessions.\nFor “Rifacciamo quel controllo”, interpret the saved titles/goals and ask only if\nmore than one example fits. Show the old result on request after inspecting its\ncurrent files. Reuse the intent in a **fresh** session; rerun the current skill\non selected inputs. Do not present an old result as a new calculation or assume\nits rules, sources, dependencies or user confirmations are current.\n\nProfile, checkpoints, example metadata and optional feedback stay in the local\nOS-user directory. Do not store audio or raw interview transcripts. Do not call\nhosted interviews, telemetry, `change_requests.py`, tutorial receipt stamping or\npublish tutorial artifacts. The compatibility local-only marker suppresses shared receipts,\nincluding retries. Optional feedback remains local even after completion.\n\nThe native OpenAI account processes the spoken conversation and any profile,\nselected files, results or screen context it reads. Local storage is not offline\ninference or automatic anonymization. Use the selected specialist's actual data\nboundaries when entering real work. No Claude Cowork teaching is added.\n"
}