Workspace and desktop
| Symptom | Resolution |
|---|---|
| “That workspace already exists” | Choose the offered unused filename to create another workspace. To continue the existing file, cancel and choose Open workspace. Existing workspaces are never replaced by New workspace. |
Workspace creation reports permission denied for a lock under C:\Users | Select or type a user-owned project folder such as the walkthrough folder under Documents, and confirm the complete target in the ready message. The dotted filename is Chronicle's sibling lock; do not run Studio as administrator to write directly into C:\Users. |
| The previous project did not reopen | The saved path may have moved or become invalid. Choose Open workspace, select the .vfsworkspace.json file, and close normally so the valid path is remembered. |
| Design federation, Build, or Export is disabled | Create or open a valid Chronicle workspace first. |
| An edit was wrong | Use Undo in Federation Workspace Editor. It creates a compensating generation; inspect both changes in Chronicle Center. |
| A child project cannot be removed | Remove every mount that references it first. The root project cannot be removed. |
| Path Lens or Rule Lab covers the status bar | Close and reopen the panel. Panels are scroll-safe and should remain above the status bar; record the screen scaling and resolution if the repaired layout still fails. |
Agent reconfiguration
| Symptom | Resolution |
|---|---|
| Signer is not trusted | In Chronicle Center > Agent trust, confirm the complete public-key ID through a separate channel, record the accountable authority, and trust that public key. |
| Signature is missing or expired | Do not modify an existing signed bundle. Train into a new versioned review directory and sign it with an active trusted key. |
| Signer is revoked | Stop using all bundles from that key. Rotate the signing identity and produce a new signed bundle; Chronicle never restores a revoked key. |
| Accuracy, benchmark rows, or regression failed | Improve the agent against the unchanged independent benchmark. Do not weaken policy or replace held-out questions merely to admit it. |
| Training or benchmark label coverage failed | Make both CSV files cover exactly the ordered model/manifest label set. Correct the sources and train a new bundle; do not edit a signed manifest. |
| Training/benchmark leakage detected | Remove every question that overlaps after case-folding and whitespace normalization. Write genuinely held-out questions, then train a new bundle. |
| Benchmark replay differs from the signed claim | Stop admission. Preserve both reports and compare the exact model and benchmark digests, evaluator version, row count, label order, confusion matrix, and per-class results. |
| Labels or benchmark changed | Use a new agent ID and establish a fresh reviewed baseline instead of comparing unlike tasks. |
| Agent bundle is not registered and accepted | In Chronicle Center > Proposals, register the exact retained branch bundle, inspect its fingerprint and authority block, then record a named acceptance. |
Answer has no workspace_actions | The branch returned a clarification or selected an explanatory article. Improve the request or reviewed training/knowledge; do not convert answer text into commands. |
| Action plan is stale | The workspace configuration changed after drafting. Draft a new proposal against the current workspace; never hand-edit its fingerprint. |
| Agent source escapes the workspace | Use an existing regular path below the folder containing the workspace, expressed as a relative path without link traversal. |
| Apply is disabled | Select an accepted, unapplied agent-workspace-action whose exact proposing bundle is accepted and whose plan still validates. |
| Plan was accepted but nothing changed | Expected: acceptance records review only. Enter a separate application authority, choose Apply accepted plan, then confirm. Build/export is still another step. |
Build and export
| Symptom | Resolution |
|---|---|
| Source path does not exist | Relative source paths start in the folder containing the workspace file. In PowerShell, use Set-Location there and Test-Path .\your\source. |
| Source path is a symbolic link | Select the real file or directory. The deterministic workspace route rejects links rather than following a mutable target. |
| Duplicate virtual mapping | Two sources produced the same path. Change one Virtual root, remove one source, or reorganize the input directories. |
| Bundled/external provider is unsupported | Edit the mount and use Embedded for the current complete workflow. The build intentionally emits no partial image. |
| Perl or prove not found | Install a Perl toolchain, open a new terminal, and confirm perl -v and prove --version. Use Build VFS when you only need the image. |
| Package destination already exists | Change the Perl version or select a clean package parent. A release folder is not overwritten in place. |
| Generated package is difficult to navigate | Start with its root README.md. Use share\<slug>\assistant\README.md for the Perl assistant and evaluator, examples\branch_agent\README.md for a specialist, and docs\API.md for the complete runtime methods. |
| Build was cancelled | Run it again when ready. Cancellation terminates the bounded child process; a staged temporary does not replace the committed image. |
Build stops at commit.py::_fsync_file with [Errno 9] Bad file descriptor | Upgrade to Studio 1.1.7 or newer. Studio 1.1.7 opened the staging file read-only before the Windows durability flush; the repaired commit path uses the Windows-compatible descriptor without weakening fingerprint or atomic-replacement checks. |
Build + Export Perl stops at prove.BAT -lr t with exit status 1 | Upgrade to Studio 1.1.8 or newer. The writable Perl runtime now releases its image reader before the Windows replacement step and reopens it after verification. If a different Perl test still fails, copy the stdout and stderr retained in this build log; Studio no longer hides them behind CalledProcessError. |
| Image does not resolve an expected path | Run inspect_cli IMAGE --deep-verify --resolve /path --trace. Check the source Virtual root and mount prefix shown in Design federation. |
AI Workbench and CSV
| Symptom | Resolution |
|---|---|
| CSV columns rejected | Save UTF-8 CSV with exactly utterance,intent. Quote questions containing commas or quotes. |
| Benchmark leakage | Write genuinely independent benchmark questions; do not copy or lightly rephrase normalized training rows. |
| Knowledge coverage missing | Add at least one reviewed knowledge article for every training intent. |
| Training buttons remain disabled | Save the settings JSON, run Preflight, and correct every reported error before starting training. |
| Approved candidate is not in a package | Approval is review evidence, not selection. Select the candidate explicitly, then build with that candidate through the supported package route. |
Monk Loom attachment errors
| Message | Resolution |
|---|---|
| Attachment requires Monk policy | Embed the exact MonkProfile in the same image. |
| Fingerprint mismatch | The policy or image changed. Review and explicitly rebind a new attachment. |
| JSON is not canonical | Use the typed writer; do not hand-edit embedded attachment bytes. |
| Missing or unknown feature | Supply every declared feature and remove undeclared names. |
| Python/Perl score differs | Compare attachment SHA-256, feature integers, runtime version, and evaluation JSON. |
| Proposal did not change the image | Expected: proposals are review-only. Apply through a separate typed, verified build. |
Search Help from a terminal
vfs-federation-help --search "source path does not exist"
vfs-federation-help --context workspace.authoring
vfs-federation-help --context workspace.agent-actions
vfs-federation-help --context build.export
vfs-federation-help --topic studio-quick-startAll Help topics are packaged locally and require no browser or network connection.