mparanza-studio-archive

---
name: mparanza-studio-archive
description: Use when Vera must create or resume one client's durable connected-folder engagement, import sources, prepare and close workflow runs, search a callable local archive, or search one client's read-only Gmail connector without mixing clients.
---

## Operational incident continuity

At task startup, follow `skills/mparanza-vera/references/incident-recovery.md`. Call the
local `vera_incident_register` tool with empty arguments to reuse the retained
installation identity over ordinary HTTPS. Its credentials stay private inside
the reporter; do not pass credentials to local tools. If local execution is
unavailable, operate `https://mparanza.com/vera/incident-recovery` through the
host's permitted browser controls, preserving the original owner and request
identifiers as the reference describes. Never put credentials in URLs or
diagnostic evidence. Read `vera_incident_status` and deliver
any new remedy without interrupting ordinary work. Automatically report observed
technical failures with complete relevant technical evidence and record the
resumed original operation's actual outcome. Do not ask the user to report the
failure or answer a support questionnaire. Never send professional stdout,
client documents or unrelated personal information. Service failure does not
block the original task. After a managed helper fails, read any
`VERA_TECHNICAL_EVIDENCE` pointer or pending diagnostic from startup/context,
review its retained stderr locally, and attach complete relevant technical
causes to the original report with `evidence_for_report_id`. Follow the reference
before declaring missing diagnostics. Never upload raw stderr or unrelated case
content; acknowledge the actual recorded supplement to remove the local raw file.

<!-- VERA_CONNECTED_KNOWLEDGE_BEGIN -->
## Connected studio knowledge

When the user or an adopted studio instruction requests relevant repository
evidence, read `../mparanza-vera/references/connected-studio-knowledge.md` before the
dependent work, including direct specialist invocation. Use only callable host
search/read tools; preserve citations and this workflow's qualification gates.
Without a repository, continue ordinary work. Studio skills remain independently
invoked by the user; Vera does not dispatch them.
<!-- VERA_CONNECTED_KNOWLEDGE_END -->

## Cowork execution contract

Select the exact files needed for this request. Folder access does not select
all its contents: if the task needs two files in a folder containing four, use
only those two. Resolve genuinely ambiguous choices with the user; reuse clear
choices without another confirmation.

Before parsing documents or creating a client, engagement or run, call
`check_studio_import_sources` with all selected paths on the actual importer
host. It needs no configured Archive and creates no records. If the MCP tool is
unavailable, use the packaged `check-import-sources --source-path <path>` CLI
through the maintained managed launcher on that same host (repeat the flag per
file). A cloud-shell `ls` is not proof of access by a computer-side importer.
Readable attachments, including `/mnt/user-data/uploads/` paths when the importer
can read them, continue directly without requiring a connected computer folder.

If files are unavailable, explain the cause immediately before creating anything:
"The file is in the chat, but the import tool looks for it on your computer."
Do not keep trying that same inaccessible path. Use this recovery sequence:

1. Inspect the host's actual callable file-transfer capabilities and the already
   connected folders. Reuse an authorized ordinary working folder outside the
   managed `Vera/engagements/.../inputs` tree. Offer **Add folder** from the **+**
   menu only when the current host offers it; otherwise explain the available
   connection method. Ask for a folder only if an accessible destination is needed.
2. With a supported bridge, copy only the selected original attachments to that
   folder as files. Compute each original SHA-256 through the host file tools.
   Do not recreate CSV text, convert encodings or line endings, relay document
   contents through model-authored tool arguments, guess a mount translation,
   overwrite a different file with the same name, or scan unrelated folders.
   A verified byte-for-byte copy may reuse its destination on retry.
3. Check the actual destination paths with `check_studio_import_sources`, passing
   `expected_sha256` as the original hashes in the same order as `source_paths`.
   The CLI takes one `--expected-sha256` per source. Archive hashes the destination
   locally and returns `ready=true` only when all supplied original hashes match.
   If no byte-preserving host transfer is available, say so and ask the user to
   save the original selected files to the accessible working folder; then verify
   them. Do not promise a bridge operation that is not callable.
4. Only after all selected sources are ready, select/create the client and
   engagement and import each through `import_studio_client_document` (CLI
   `import-document`). Pass that file's `expected_sha256` / `--expected-sha256`
   when a transfer was required. The importer checks it again during copying and
   creates the input ID and SHA receipt itself. Never manually populate `inputs`.

The path importer does not itself fetch chat attachments. Direct attachment use
requires actual importer access or a demonstrated host transfer. If neither an
importer-side check nor transfer is callable, explain the missing capability
before creating records; do not create a cloud-only replacement for a local Archive.

On any later import failure, disclose the existing `client_id` and `engagement_id`
and resume those same records. A folder-name collision calls for inspecting the
returned existing scope and reusing it when its identity matches; never clear old
folders or change the client's name just to get past the error. A deliberately
separate synthetic test may have a distinct name; retries retain their identities.
Documentless client work needs no file check. Standalone workflows check access
on their own execution host and do not require Archive or a computer folder when
that engine can read the inputs.

Public workflow names select skills; component IDs select module paths.
`financial-report-builder` uses component `report-builder`, `vouching` (historically
called Check Entries) uses `check-entries`, and `purchase-invoice-review` uses
`passive-invoice-audit`. These component IDs are not additional workflows.

For journal-sampling, open-item-reconciliation, journal-bank-reconciliation,
concordato-plan-review, financial-report-builder and vouching only, optional cache
cleanup uses the corresponding component ID from the installed Vera root:

```bash
python3 modules/<module>/scripts/implementation_bootstrap.py --repair
```

For a standalone module, use `python3 scripts/implementation_bootstrap.py --repair`
from its root. This validates the implementation first, then removes only regular,
single-link `__pycache__/*.pyc` files under that module's own `vendor` tree. It
leaves directories, other files, symlinks and shared vendor trees untouched.
This supported maintenance command is the only cache-cleanup exception to the
prohibition on editing the installed tree by hand. It is optional: ordinary
validation and execution tolerate incidental bytecode without removing it.
On a read-only installation, skip cleanup. If the command reports a permission
error, retain that error and continue the ordinary validated workflow when its
checks pass; do not chmod, delete files manually, copy or patch the installation,
or bypass the host's permissions to make cleanup succeed.
If `validate_implementation_tree` ever fails with a file/directory-contract
mismatch, do not delete or modify files inside the installed plugin tree by hand
and do not bypass a sandbox/permission rejection to do so. Stop and report the
exact error instead.

Work from the connected folder and supplied files first. Before a module's Python
helpers, locate the installed plugin root. When it contains `components.json` and
`scripts/managed_python_runtime.py` (as Vera does), run from that root:

```bash
python3 scripts/check_dependencies.py --module <module>
python3 scripts/managed_python_runtime.py --module <module> run scripts/<helper>.py <arguments>
```

If the enclosing plugin does not ship this managed launcher, use the module's
dependency checker and only already-installed dependencies; do not assume that a
standalone module script provisions them.

The managed launcher provisions and reuses one user-scoped CPython 3.12
environment per OS host with the published, hash-checked dependency locks, outside client
folders. Modules and products share this dependency environment; it does not
isolate client matters. This declared dependency setup is authorized as
part of running the workflow; never install arbitrary packages or use ambient
Python for subsequent module helpers. Repeat any declared `--requirements` options
on both commands. Missing ambient imports are a reason to run this setup, not to
abandon the calculation. If setup fails, report its exact error and do not replace
the required calculation with an invented result. Optional OCR setup still needs
separate approval. If setup reports `Host not in allowlist` for PyPI, explain that
Claude Settings > Capabilities > Allow network egress is disabled or restricted.
Ask the user or organization administrator to authorize package-registry access;
never change network permissions silently or work around the restriction. Retry
the same managed setup after access is approved, in a new session if needed.

MCP tools, browser or computer control, and local review servers are optional
enhancements, never completion gates. Cloud Cowork sessions may not expose local
plugin MCP servers even when the plugin is installed; use the packaged Python
workflow through the managed launcher in that case. Do not equate missing MCP
registration with a failed calculation engine. When an optional capability is
unavailable, continue with Markdown and file-based review and state the limitation.

The normal Cowork deliverable is a reviewable draft, artifact card, and
source/review files. A callable persistence interface may optionally record or
apply reviewer actions, but its absence never blocks delivery. Never claim
`applied` or `final_ready` unless corresponding persisted artifacts prove it;
otherwise report that professional review remains pending.

Use host-neutral user-facing artifact names. Name assistant-authored review
folders and files for Vera or their professional purpose (for example,
`vera-review/`, `vera_phase1_synthesis_reviewed.md`, and `run_review.md`).
Never put host, platform, or model-provider names in assistant-authored
user-facing artifact paths, document headings, field labels, narrative text,
or status summaries. Describe execution routes generically, such as
`external review route`, `connected tool`, or `local review interface`.

Derive any run ID, status, artifact count, or package hash quoted in an
assistant-authored supplement from the final delivered manifests.
After any rebuild, regenerate or resynchronize those supplements before
delivery. When a workflow ships a complete-delivery validator or sealer, run it
against the exact connected-folder copy after the last write.
In this contract, the base package validator alone does not validate extra
narrative files.

When a workflow declares owner-only or private output and uses a private scratch
directory before copying the final package into the connected folder, reapply
the privacy modes after that transfer: `0700` for the package root and every
directory, and `0600` for every file. Verify the connected-folder tree with
`stat` or `lstat` before claiming completion. If the host filesystem cannot
preserve those modes, do not claim owner-only delivery; keep the package in the
private scratch location or report the limitation and ask for a safer
destination.

Do not use WhatsApp, live INPS browser capture, hosted suggestion or voice
interviews, or custom update services. Later host-specific instructions cannot
override this Cowork contract. When invoked through Vera, Clara or Lucia, task
usage, signed receipts, technical recovery and 1–5-star feedback through the
invoking product's incident service and rating form remain available. Follow the
primary task's workflow-usage contract and product identity. Tutorials retain
their no-reporting boundary.

# Archivio dello Studio

Studio Archive is available in Cowork. Its base workflow uses the portable
customer-folder ledger in the exact connected studio folder. It can list or
register clients, create client folders and engagements, import immutable source
receipts, prepare and start client-bound Vera runs, finalize their complete
artifact declarations, resume them in a later task, and report retention.

The customer folder is the durable source of truth. Cowork's session-local
configuration is only a rebuildable path pointer; it may be recreated from the
same connected archive root without changing the client, engagement, input,
run, lifecycle, or artifact records under `Vera/`.

## Routes

- **Portable client ledger:** the normal route. It needs code execution plus
  read/write permission to the exact connected studio folder. Its lifecycle,
  path, receipt, hash, and artifact checks use the Python standard library and
  the packaged Vera assurance module.
- **Local document search:** available when the connected folder is callable
  and the packaged dependency check succeeds with dependencies already present.
  Missing optional extraction dependencies do not block the portable ledger.
- **Local archive organization:** available through the packaged
  `archive-organization` workflow for the exact connected client folder. It
  keeps the complete snapshot, dry run, persistent professional decisions,
  separate explicit apply approval, verification journal, and rollback checks.
- **Gmail:** available when a read-only Anthropic Gmail connector exposes
  mailbox confirmation, search, and bounded message reading.
- **Guarded WhatsApp Desktop review and native Google Drive OAuth:** not enabled
  as Cowork routes. Do
  not substitute an unguarded screen-control flow, browser login, copied token,
  or generic Drive access. Continue with the portable ledger and connected
  files.

Do not redirect the user to another product. Do not claim a route ran when its
capability was unavailable.

## Packaged command

Resolve the installed Vera root from this skill directory, not from a guessed
AppData path. Generate one UUID for this task and retain that exact value in
all commands, including separate shell calls. Use a new UUID for a new task;
never share configuration across concurrent tasks. The session helper passes
that identity to the managed runtime and the archive subprocess.

On native Windows, use PowerShell and the packaged launcher (replace the UUID
placeholder with the one generated for this task):

```powershell
& "<installed-vera-root>\scripts\studio_archive_windows.ps1" -SessionId "<task-uuid>" diagnose
& "<installed-vera-root>\scripts\studio_archive_windows.ps1" -SessionId "<task-uuid>" check
& "<installed-vera-root>\scripts\studio_archive_windows.ps1" -SessionId "<task-uuid>" clients
```

The launcher probes `py -3`, `python`, and `python3`, then uses the verified
interpreter's absolute path. `-PythonExecutable` may select an explicit existing
interpreter. Do not copy or rename python.exe, uninstall another Python, create
junctions, change execution policy, or change Windows security settings. If host
policy blocks PowerShell, report the denial; do not bypass it. If bootstrap is
unavailable, distinguish a missing/unusable interpreter from package access;
request the exact attempted command and error, not client documents.

On a Linux or macOS execution surface (including a Cowork VM), run from the
installed Vera root using a callable Python:

```bash
python3 scripts/studio_archive_session.py --session-id <task-uuid> diagnose
python3 scripts/studio_archive_session.py --session-id <task-uuid> check
python3 scripts/studio_archive_session.py --session-id <task-uuid> <command> [arguments]
```

`diagnose` checks package readability without provisioning or archive writes.
`check` prepares and checks the managed runtime. Every archive command must use
this session helper; invoking the archive CLI without its task identity can
select a different configuration on every process. The actual workflow remains
`scripts/managed_python_runtime.py --module studio-archive run scripts/studio_archive.py`.

The bootstrap may start under ambient Python; the workflow runs under managed
CPython 3.12. Setup uses only published shared requirements and respects host
network permissions. Optional OCR remains an explicitly approved feature. A
setup failure must be resolved before execution; do not bypass it with an
ambient interpreter. Run relevant optional dependency checks before indexing,
extraction, OCR or Google client code.

## Check supplied files before starting client work

Select the exact files needed for this request. Folder access does not select
all its contents: if the task needs two files in a folder containing four, use
only those two. Resolve genuinely ambiguous choices with the user; reuse clear
choices without another confirmation.

Before parsing documents or creating a client, engagement or run, call
`check_studio_import_sources` with all selected paths on the actual importer
host. It needs no configured Archive and creates no records. If the MCP tool is
unavailable, use the packaged `check-import-sources --source-path <path>` CLI
through the maintained managed launcher on that same host (repeat the flag per
file). A cloud-shell `ls` is not proof of access by a computer-side importer.
Readable attachments, including `/mnt/user-data/uploads/` paths when the importer
can read them, continue directly without requiring a connected computer folder.

If files are unavailable, explain the cause immediately before creating anything:
"The file is in the chat, but the import tool looks for it on your computer."
Do not keep trying that same inaccessible path. Use this recovery sequence:

1. Inspect the host's actual callable file-transfer capabilities and the already
   connected folders. Reuse an authorized ordinary working folder outside the
   managed `Vera/engagements/.../inputs` tree. Offer **Add folder** from the **+**
   menu only when the current host offers it; otherwise explain the available
   connection method. Ask for a folder only if an accessible destination is needed.
2. With a supported bridge, copy only the selected original attachments to that
   folder as files. Compute each original SHA-256 through the host file tools.
   Do not recreate CSV text, convert encodings or line endings, relay document
   contents through model-authored tool arguments, guess a mount translation,
   overwrite a different file with the same name, or scan unrelated folders.
   A verified byte-for-byte copy may reuse its destination on retry.
3. Check the actual destination paths with `check_studio_import_sources`, passing
   `expected_sha256` as the original hashes in the same order as `source_paths`.
   The CLI takes one `--expected-sha256` per source. Archive hashes the destination
   locally and returns `ready=true` only when all supplied original hashes match.
   If no byte-preserving host transfer is available, say so and ask the user to
   save the original selected files to the accessible working folder; then verify
   them. Do not promise a bridge operation that is not callable.
4. Only after all selected sources are ready, select/create the client and
   engagement and import each through `import_studio_client_document` (CLI
   `import-document`). Pass that file's `expected_sha256` / `--expected-sha256`
   when a transfer was required. The importer checks it again during copying and
   creates the input ID and SHA receipt itself. Never manually populate `inputs`.

The path importer does not itself fetch chat attachments. Direct attachment use
requires actual importer access or a demonstrated host transfer. If neither an
importer-side check nor transfer is callable, explain the missing capability
before creating records; do not create a cloud-only replacement for a local Archive.

On any later import failure, disclose the existing `client_id` and `engagement_id`
and resume those same records. A folder-name collision calls for inspecting the
returned existing scope and reusing it when its identity matches; never clear old
folders or change the client's name just to get past the error. A deliberately
separate synthetic test may have a distinct name; retries retain their identities.
Documentless client work needs no file check. Standalone workflows check access
on their own execution host and do not require Archive or a computer folder when
that engine can read the inputs.

## Connected archive setup

Use one exact connected folder whose immediate child directories are client
folders. Never infer the archive root or a client from a filename.

1. Run `diagnose-access --archive-root <exact-connected-root>` before first
   configuration. It must confirm path resolution and listing without returning
   the private path in its result.
2. If the user has an existing archive, select that exact connected root.
   "Not configured" means this session has no pointer; it does not mean the
   archive was deleted. Ask for the original folder if it is not connected.
   Do not create a replacement, move folders, or scan unrelated directories.
   Run `configure --archive-root <exact-connected-root>`, then `recover-ledger`
   and `clients`, all through the same session helper.
3. At the start of a later task, run `clients` first. With the same retained
   owner-private profile, the helper revalidates the approved connected root,
   creates fresh session configuration and recovers confirmed aliases and stable
   client IDs without another folder selection. Existing sessions remain pinned.
   If the host provides a new/ephemeral home or the selected folder is no longer
   accessible, reconnect the exact original folder; do not claim host persistence
   that was not observed. Run `recover-ledger` when ledger verification is needed.
   Recovery reads stable identities from `Vera/client.json`, not folder labels.
4. If the connected root is unavailable or read-only, stop before client,
   engagement, import, or lifecycle writes. Report the permission limitation.

Do not put private identity registries, OAuth material, credentials, tokens, or
mail content in the customer ledger. The session-local index and configuration
are rebuildable aids, not engagement evidence.

## Client and engagement workflow

Use this sequence for archived client work. Explicit standalone invoice/answer
work follows Vera's `references/standalone-work.md` and retains task artifacts
without this archive configuration or client-registration gate.

Complete the supplied-file checks above before these record-creation steps.

1. Run `clients`. Select one returned stable client semantically from the
   user's instruction. If ambiguous, ask; never choose by recency or filename.
2. For an existing unregistered folder, run `configure-client` with its exact
   returned scope ID and at least one user-confirmed legal name, full email/PEC,
   or tax identifier. For a new client, run `create-client` only after the user
   chooses New client; the resulting relationship remains
   `new_client_workflow_pending`.
3. Run `create-engagement` or `engagements` and select one exact engagement.
4. Explain that import preserves the original and creates an immutable copy and
   SHA-256 receipt. After authorization, run `import-document` separately for
   each selected file with role `source`, `journal`, or `support`.
5. Run `prepare-workflow` with the exact workflow ID, input IDs, and any exact
   finalized same-engagement upstream artifacts. Repeating the same request is
   idempotent; use `--new-run` only for an explicitly separate run.
6. Run `start-workflow`. Pass the returned `client_engagement_path` unchanged to
   the specialist module. Execute only its hydrated input bindings and write
   only below its exact output directory.
7. After the final write, run `finalize-workflow` with every physical output,
   including a unique artifact ID, relative path, concrete purpose, audience,
   and media type. An empty, changed, partial, or undeclared tree is not ready.
8. Review the declaration, then run `complete-workflow`. Record `fail-workflow`
   or `cancel-workflow` instead of presenting a partial folder as a result.

Journal Sampling and Check Entries keep their exact handoff: finalize the
normalized population, diagnostics, and sample first; import each later support
batch separately; then use `start-check-entries-from-sample`. Check Entries
checks only the bound sample and never discovers later files implicitly.

## Saved-input verification and document continuations

Before claiming an import or earlier working note is preserved, use the callable
`verify_studio_client_inputs` MCP tool, or run the maintained `verify-inputs`
command through the same session helper. Select the exact client, engagement
and input IDs from native import or `engagements` results. Never improvise a
verifier that reads raw `engagement.json` or `receipt.json` for hydrated paths.

The command takes `--client-id`, `--engagement-id` and repeated `--input-id`.
Supply `--expected-receipts-json` with the prior `input_id` and `content_sha256`
pair for every selected input when checking preservation. Use
`--require-exact-input-set` only when the selection is the complete expected
engagement population. Inspect `verified`, each input and `failures`; a blocked
check exits nonzero and never repairs the archive. Do not invent a baseline.

The result supplies verified controlled paths for any separately authorized
content read. Complete file hashing is local; IDs, names, roles, paths, sizes,
file and receipt hashes and check results may enter the host model context,
but this operation returns no document text. Verification does not establish
document meaning, payment, authored lineage or professional approval.

For a document-only continuation, import the new derived note as `support`,
retain the earlier receipt and verify both versions against their prior import
receipts. For an exact retry, retain the actual import result `already_imported`
and the same input ID; verification cannot invent a historical retry outcome.
The full contract is in the component's `references/input-verification.md`.

## Local document search

When the dependency check succeeds, `refresh`, `search`, and `open` may index
and verify one exact connected scope. Refresh hashes the supported files and
re-extracts changed content. Search results are candidates, not evidence; open
every source used, require its current hash to match, and cite the returned
locator. Do not claim complete coverage when extraction issues, OCR gaps, file
bounds, or unsupported formats remain.

## Connected Gmail

Use Gmail only when the user asks for it. Confirm the mailbox, process exactly
one client, and construct the address set only from complete email or PEC
addresses supplied or explicitly confirmed in the current task. When no full
address is confirmed, run one discovery-only query using the supplied client
name or identifier and return at most 20 candidates. Read only the smallest
useful candidate shortlist, propose complete participant addresses from the
returned metadata, and obtain one explicit confirmation before using any
candidate message as client evidence.

After confirmation, search only the confirmed addresses, in batches of at most
ten, with the user's topic or date bounds when useful. Request at most 20
results per page and paginate only when the requested coverage materially
requires older messages. Read only the scoped shortlist. For every message,
compare all available From, To, Cc, and Bcc values case-insensitively against
the confirmed address set. Automatic routing requires a parseable From value,
parseable returned recipient values, exactly one selected client, and no visible
other-client or ambiguous external participant. Inspect Cc and Bcc whenever
exposed; an absent optional field alone is not incomplete, and returned fields
cannot prove the absence of an undisclosed Bcc recipient.

Use read actions only. Never send, draft, forward, archive, trash, delete,
label, move, download, or otherwise mutate mail. Do not use IMAP or browser
scraping as a fallback. Gmail evidence remains connector evidence rather than a
hash-verified ledger input unless the user separately supplies and imports an
authorized export.

## Model and privacy boundary

The model may receive the selected client directory rows with stable IDs,
labels, status, and counts; the task instructions; exact workflow context and
artifact declarations; bounded search candidates and opened source passages;
and the selected Gmail evidence described above. Stored private identity values,
absolute archive paths, raw file hashes, the SQLite index, and unselected files
remain outside model context unless a specific professional operation requires
an exact value or opened source.

This is purpose-based minimization, not anonymization or pseudonymization. Do
not remove names, account labels, amounts, relationships, or evidence locators
when they are necessary to select the right client, interpret the accounting
evidence, or support the professional result.