Complete first package walkthrough

What you will make

1. Check prerequisites

Open PowerShell. Studio requires 64-bit Python 3.12 or newer. Perl export verification requires perl and prove; Strawberry Perl is one suitable Windows distribution.

py --version
perl -v
prove --version

If a command is not found, install that runtime and open a new PowerShell window.

2. Install and launch Studio

Put the wheel in a writable folder, open PowerShell there, and run:

py -m pip install .\vfs_federation_studio-1.1.5-py3-none-any.whl
py -m vfs_federation.ide

Studio starts maximized. It restores the last valid workspace on later launches.

3. Create the example files

Leave Studio open. In PowerShell, create a project folder under Documents:

$Demo = Join-Path $env:USERPROFILE "Documents\VFS First Federation"
New-Item -ItemType Directory -Force "$Demo\content\root\docs" | Out-Null
New-Item -ItemType Directory -Force "$Demo\content\plugin" | Out-Null
Set-Content -Encoding utf8 "$Demo\content\root\docs\hello.txt" "Hello from the root VFS"
Set-Content -Encoding utf8 "$Demo\content\plugin\plugin.txt" "Hello from the embedded child"

4. Create the Chronicle workspace

1. In Studio choose New workspace.
2. Select the VFS First Federation folder created above.
3. Use filename federation.vfsworkspace.json.
4. Enter Root project name First Federation and Package namespace example.first.
5. Choose Create workspace.

If that filename already exists, the dialog offers the next unused name. Choose it to create another workspace, or cancel and use Open workspace to continue the existing one.

5. Add the root source

1. Choose Design federation.
2. Open the Sources tab and choose Add source….
3. Select First Federation.
4. Set Source file or directory to content\root and Virtual root to /.
5. Choose Save. The change is already persisted as the next Chronicle generation.

6. Add and mount the child project

1. On Projects, choose Add project…. Use Project name Demo Plugin and namespace example.first.plugin.
2. On Sources, choose Add source…. Select Demo Plugin, enter content\plugin, and use Virtual root /.
3. On Mounts, choose Add mount….
4. Select Parent First Federation, Child Demo Plugin, and prefix /plugins/demo.
5. Keep Delivery mode Embedded, Collision policy Error, and Priority 0. Choose Save.
6. On Build profiles, confirm one row for each project is marked Active, then close the editor.

If you make a mistake, use Undo or Redo in the editor. Each correction is a new saved generation; history is never silently erased.

7. Build the VFS and export Perl

1. Choose Build & export on Home, or Export Perl Package on the toolbar.
2. Keep VFS image output build\federation.vfsbin and Perl package parent dist.
3. Use Perl module Example::First and version 1.0.0.
4. Choose Build + Export Perl. Watch the log until the status says the build completed and was verified.

The child is built before the root. Output is staged and digest-checked before the destination is replaced. Perl syntax checks and generated tests run before the package is accepted. Cancelling leaves the previously committed destination unchanged.

To reproduce the same saved design from PowerShell, use the workspace as the authoritative input:

Set-Location $Demo
py -m vfs_federation_studio.tools.build_cli `
  .\build\federation.vfsbin --workspace .\federation.vfsworkspace.json `
  --perl-package .\dist --perl-module Example::First --perl-version 1.0.0

8. Independently inspect the image

Return to PowerShell:

Set-Location $Demo
py -m vfs_federation_studio.tools.inspect_cli `
  .\build\federation.vfsbin --deep-verify --resolve /docs/hello.txt --trace

py -m vfs_federation_studio.tools.inspect_cli `
  .\build\federation.vfsbin --resolve /plugins/demo/plugin.txt --trace

The first command must include verify  PASS and a resolve row for /docs/hello.txt. The second trace must resolve through the mounted child. Do not distribute an image that fails deep verification.

9. Test and try the Perl package

Set-Location "$Demo\dist\Example-First-1.0.0"
prove -Ilib -r t
perl .\bin\vfs-perl-assistant --ask "How do I read a VFS file?" --explain

prove must end with Result: PASS or All tests successful. Open the package root README.md for the VFS runtime, share\example-first\assistant\README.md for the actual model measurements and Perl respond() API, and examples\branch_agent\README.md for the exact specialist workflow. Copy the complete Example-First-1.0.0 directory—not selected files—to another machine with Perl to use it without Python or network access.

10. Reopen and continue

Close and launch Studio again. It reopens the last valid workspace. Federation Explorer shows the projects, sources, mount, and active profiles. Use Chronicle Center to inspect generations and recovery candidates. Use Path Resolution Lens on the built image for an interactive trace; click its checked toolbar icon again to hide it.

Optional next steps: train an assistant or a VFS specialist

The exported package already contains the reviewed bundled assistant. To replace the main assistant, follow Prepare assistant CSV and JSON data and Use the AI Workbench. To train a named pure-Perl branch that can return reviewed, proposal-only workspace recipes, follow Train an agent to propose workspace changes. Before such a branch can enter Chronicle review, follow Trust agent signers and set regression limits to trust its signer, sign the retained bundle, and verify admission. Training, signing, quality admission, human review, workspace application, and packaging remain distinct actions.