Data & administration

Importing & content packs

If you were testing before SQUAT — persona notes in files, a spreadsheet of pass/fail runs, a homegrown harness — you don't start the ledger from zero. Bring the personas and history with you, while keeping test credentials outside SQUAT. And when you'd rather start from ready-made material than your own files, content packs install governed starter content the same reviewable way.

Connected panel dialogue and governed persona sources are protected automatically when SQUAT accepts them. You provide ordinary structured content and do not supply a content-protection key.

Why bother backfilling?

SQUAT's value beyond a single round is the trend: did the product get more or less trustworthy over time, which scenarios regressed, which personas keep hitting the same wall. If your history starts the day you migrated, none of that pre-migration signal exists — you'd be throwing away months of real data because it lived in a different format yesterday.

Backfilled rounds are inserted into the ledger at the point in time they actually happened, not at import time. They're marked (backfill) so you can always tell them apart, and they count fully in every trend — distinguishable, never second-class.

Importing personas

Two paths, depending on where your persona material lives:

• A document in hand (research notes, an avatar sheet): bring it to a recruiting conversation and choose verbatim import or baseline adaptation — see Recruiting testers.
• Persona files on disk: ask SQUAT to stage personas from a folder, giving the absolute path. A local helper preserves each ID and bounded display name without copying raw file bodies into the broadly readable persona record. SQUAT then completes each through its protected source, communication range, synthetic audition, and actor-briefing activation.

After any persona import, SQUAT runs a depth check: imports are where thin, document-generated profiles slip in, and the moment of import is the cheapest time to catch one. Each imported persona gets a depth card — what's rich, what's missing, and an offer to fill the gaps with a short enrichment interview from your memory of the real person. See Recruiting.

Staged personas are marked with origin “import” and remain pending. A governed import/validation flow must save the complete original as a protected source and activate the exact reviewed actor briefing before the persona can run.

Loading dialogue from an interrupted panel

An interrupted panel uses a different path from historical round import. If a hosted panel had already started and your client preserved an already-authorized turn whose hosted append failed, SQUAT can load that receipt-backed turn into the same open round as canonical dialogue. A disconnected client cannot obtain the next question or answer authorization, so it pauses before generating another exchange.

The local recovery file remains ordinary readable research content on your device until import. Store it securely. After SQUAT accepts the batch, the hosted dialogue is protected automatically and reads back through the same aligned transcript view with a recovered-import origin.

1. Check the round. SQUAT confirms that the panel is still open and its hosted dialogue still ends at the same checkpoint recorded in the local file.

2. Review the load. You see how many turns will be added. Loading changes the hosted ledger, so SQUAT waits for your approval.

3. Confirm the receipt. SQUAT loads the full batch or none of it, then identifies the panel by its readable project and round context and returns the number of turns added and an import receipt. The stable round ID remains available as secondary, copyable metadata for an exact lookup. The local file is not changed.

If the hosted dialogue advanced, the round closed, a role receipt is absent, or any turn does not match the saved cast or panel guide, nothing is loaded. Both versions remain available while you decide how to reconcile them. A repeated load of the exact same file returns the original receipt instead of duplicating turns.

Importing historical rounds

First: the order matters

Every historical round references the personas and scenarios it ran. Those must exist in your workspace before the rounds that point at them. The importer checks this before committing anything: every referenced tester is matched against your squad by ID first, then by name (an import that says maya_chen matches your squad member “Maya Chen” and is relabeled automatically). Anything that still doesn't match blocks the entire import — nothing partial lands — and you're offered four ways forward: import the missing personas first, supply an explicit mapping, skip the unmatched material (import everything that matches, drop the rest — the right call for junk like a stray “sample” tester in old run data), or accept the orphans knowingly. So:

1. Create or import your personas.

2. Create or import your scenarios — using the same scenario IDs your history references. If your scenario definitions live in a file (a scenario-library document, say), ask SQUAT to read the file by its full path and save each scenario — the local file reader brings it into the conversation and the assistant does the parsing, keeping your IDs exactly. Missing scenarios block the import, just like missing testers — you'll be offered the choice to enter them right then (from your library file or by describing each one), map them onto scenarios you already have, or skip the affected results and import the rest.

3. Then import the round history that references them.

If your history is in structured run folders

If your prior process wrote structured files to disk — one folder per round, one subfolder per attempt — SQUAT's bulk importer may be able to read them directly: ask SQUAT to import rounds from your runs directory. It converts what it finds, tolerates missing or malformed files per-session rather than aborting everything, carries the full original files along as evidence, and marks anything it could not confidently score as an Inconsistency for your review.

Any other format: Round Import Format v1

Everything else — a spreadsheet, a Notion export, a wiki of “known issues per release,” a homegrown script's JSON — goes through one door: SQUAT's published Round Import Format v1. The workflow is a deliberate two-step, which keeps the conversion inspectable and re-runnable instead of a black box:

1. Convert. Hand your export to your AI client along with the format specification (ask SQUAT for the round import format). It writes one JSON file per historical round into a directory — dates, participants, and one result per persona×scenario attempt, each file carrying the marker "format": "squat-round-import@1". You can read the files it produced before anything is imported.

2. Import. Point the bulk importer at that directory. Files in the format are recognized and imported directly — one OK/error line per file, no further guessing.

The essentials of a round file:

{
  "format": "squat-round-import@1",
  "startedAt": "2025-08-14T00:00:00.000Z",
  "completedAt": "2025-08-16T00:00:00.000Z",
  "personaIds": ["dana-power-user"],
  "scenarioIds": ["checkout-flow"],
  "results": [
    { "personaId": "dana-power-user",
      "scenarioId": "checkout-flow",
      "status": "pass",
      "notes": "Source: QA log row 22; date is the sheet's own 'Run date' column." }
  ]
}

Validation is strict and up front — dates must be real past dates with the end no earlier than the start, participant lists can't be empty, and every failed result must say what kind of failure it was (app, test, or agent). A file that breaks a rule is rejected with a clear error, never silently patched.

Moving a project between local and hosted work

If a project began in a local UAT setup, ask SQUAT to prepare a project migration package. With the plugin, /concierge is the guided entry point; a bare-MCP client can invoke the concierge prompt or use the same request. SQUAT collects the history, supporting evidence, and attached artifacts it can safely identify, shows you what needs review, and lets you import the approved rounds after the personas and scenarios are ready.

You can also ask SQUAT to export the current workspace for review or handoff. The portable copy contains current records and round/report information; attached files remain available through their artifact references. Login credentials and other access secrets are never included.

What happens in each direction

• Local to hosted: SQUAT first makes a reviewable package. You approve the project and identity mappings, then import personas and scenarios before the historical rounds that reference them. The ledger keeps the rounds' original dates and marks them as backfill. Artifacts are uploaded separately into the project's artifact library; a migration package does not silently create a panel, expose an image, or save a Research Report.
• Hosted to local: a portable export gives you the current readable records and round/report metadata for review or handoff. Artifact references are included so authorized files can be retrieved later. If you need a recovery-grade copy before deletion or a major change, request a full backup instead; it includes retained artifact bytes and archived/trash content after the server confirms the backup is complete.
• Remote versus local clients: a connected remote client can validate a reviewed package and request an authorized export, but it cannot read arbitrary folders on your device. A local launcher is required to inspect or write the package on disk, and it only reads project directories you explicitly allow.

The accuracy rules of conversion

The format's conversion guidance exists to produce a faithful import, not just a valid one. The rules your AI follows — worth knowing because they protect your trend line:

• Never round an unclear result up to pass. Absence of a documented failure is not evidence of success. Genuinely ambiguous history imports as an Inconsistency for review.
• Dates follow evidence. Exact dates are used exactly; inferred dates use the best available evidence (a file's timestamp, an adjacent record) at only the precision the evidence supports, with the inference stated plainly in the notes. History with no dating evidence at all is flagged to you, never fabricated — a round backfilled at the wrong point in time actively damages the trend this feature exists to preserve.
• Sources are preserved verbatim. The original row or record travels in the result's evidence; the converter's reasoning goes in notes. A summary can be regenerated from the source later; the reverse is impossible.
• IDs are never invented. If your source references a persona or scenario that doesn't exist in the workspace, the conversion stops and says so — a plausible-looking made-up ID would produce a silently wrong import, which is worse than an error.

Preparing test credentials

Do not ask SQUAT or a generic file helper to read a login .env.local: that places secret values inside the agent/tool boundary. With the operator present, move each dedicated UAT account directly into the operating system credential store or approved password manager, configure only the scenario's non-secret authentication policy, verify the exact-origin login through an approved local setup method, then remove the old file through a human-controlled process.

SQUAT does not import or host those secrets. Only the scenario's non-secret authentication policy and a readiness attestation enter the workspace.

What you get afterward

The ledger shows imported rounds interleaved with live rounds in true chronological order, each flagged as backfill. Comparing a backfilled round with a later live round works exactly like comparing two live rounds. Your trend line is true from day one — no cliff at “the week we switched tools.”

Content packs: installing ready-made material

Everything above brings your material in. A content pack works in the other direction: a versioned set of ready-made squad material — personas, scenarios, discussion guides, squads — published for SQUAT, which you preview and then install into your workspace. The free tutorial pack is the built-in starter; further packs appear in the catalog as they're published.

A pack, or your own people?

Recruiting stays the right move when a persona should be grounded in a real user of your product — that grounding is what makes the resulting trend line worth believing. Reach for a pack when you want a working starting point today: practice material for learning the workflow, a ready-built discussion guide, or a persona you'd rather adapt than author from scratch. The two mix freely — a squad can hold recruited, imported, and installed members side by side.

What “governed” means for you

Installing a pack is not a template copy-paste. Three properties protect you:

• Pinned versions. An installation records the exact pack version and the exact version of every item in it. Rounds that use installed material record those exact versions too, so a later pack update can never quietly change what your history means.
• License terms up front. The preview shows the pack's license alongside its contents, before you approve anything.
• The normal pipelines. Installed items are materialized through the same governed paths as content you create yourself. A pack persona arrives complete — protected source, communication range, clearly synthetic audition, and actor briefing — marked with origin “catalog”; scenarios, discussion guides, and squads land as ordinary workspace records tagged with the pack and version they came from.

Installing a pack

1. Browse. Ask “what content packs are available?” (content_pack_browse) to see each pack's title, contents, and versions. Every workspace role can look, and browsing changes nothing.

2. Preview. Ask to preview the pack (content_pack_install_preview). SQUAT shows exactly what would land — each item, its version, its provenance basis, and the pack's license — before anything is written. Nothing installs from a browse or a preview.

3. Install. An owner or admin approves the installation (content_pack_install). SQUAT checks that the workspace holds the pack's entitlement, then materializes each item. An interrupted install is safe to re-run: items that already landed are recognized, not duplicated.

After installation, it's yours to work with

Installed records are ordinary workspace content. Owners and admins edit them like anything else, and an installed persona can go through the normal adaptation interview before it runs — exactly like an imported one — or run as delivered. Each record remembers which pack and version it came from, so you always know what you've changed.

Updates and revocation

• Updates are offered, never forced. When a new pack version exists, an owner or admin previews and approves it (content_pack_update). Updating appends new versions of the installed records; the versions your historical rounds recorded are never rewritten.
• Revocation blocks the future, not the past. Revoking a pack's entitlement (content_pack_revoke) stops future installs and updates of that pack. It deletes nothing: content already in your workspace stays where it is, and past rounds keep their exact pinned references.