Train an agent to propose workspace changes

What is—and is not—being trained

This release uses reviewed action recipes, not free-form code generation. The action values are exactly those stored in the selected knowledge article; a model does not invent UUIDs, paths, or names from arbitrary prose. Create a specific article for each change you are prepared to review.

Before you begin

1. Complete Complete first package walkthrough. Keep the Chronicle workspace and generated Perl distribution.
2. Work on a copy of the VFS image. Branch training creates a new VFS generation and refuses to overwrite an existing agent ID.
3. Choose a new review-bundle directory. The training command refuses to overwrite it.
4. Create a signing identity and confirm its public-key ID as explained in Trust agent signers and set regression limits. Keep the encrypted private key outside the workspace and bundle.
5. Keep the workspace, action source files, and proposal JSON in a trusted local folder. Agent-added sources must be regular paths below the workspace folder and must already exist.

1. Read the exact workspace identities

From the folder containing the workspace, run:

vfs-federation-workspace show .\federation.vfsworkspace.json
vfs-federation-workspace show .\federation.vfsworkspace.json --document

Copy the workspace_id, root_project_id, and any source, mount, or profile IDs used by your recipe. Do not guess an ID. The example below renames only the root project, so it needs the root project ID.

2. Create specialist training and benchmark CSV

Save both files as UTF-8 with the exact header utterance,intent. Training and benchmark questions must be independent. Use multiple natural phrasings for each intent.

Studio later reparses the retained bytes. Both corpora must cover exactly workspace_naming and workspace_governance, their labels must match the ordered labels in model.json and the manifest, and no case-folded, whitespace-normalized question may appear in both files.

agent-training.csv

utterance,intent
"Use our approved production federation name",workspace_naming
"Apply the reviewed root naming plan",workspace_naming
"Prepare the production root name change",workspace_naming
"Select the authorized name for the federation root",workspace_naming
"Draft the approved workspace title update",workspace_naming
"Propose our reviewed package root name",workspace_naming
"Explain why agent changes require review",workspace_governance
"Can the VFS agent commit its own plan?",workspace_governance
"Describe the separate accept and apply gates",workspace_governance
"Does signing let an agent alter the workspace?",workspace_governance
"Who reviews a specialist branch plan?",workspace_governance
"Can an accepted plan start a build?",workspace_governance

agent-benchmark.csv

utterance,intent
"Propose the approved release name for this workspace",workspace_naming
"Draft our authorized federation title",workspace_naming
"Use the reviewed root name",workspace_naming
"Prepare the release-facing workspace name",workspace_naming
"Who has authority to apply an agent plan?",workspace_governance
"What does a bundle signature authorize?",workspace_governance
"Why is application separate from acceptance?",workspace_governance
"May the branch agent run Build and Export?",workspace_governance

3. Create reviewed knowledge with one action recipe

Replace ROOT_PROJECT_UUID_FROM_STEP_1 before saving. The payload is a normal Chronicle command payload. The reason is displayed to the reviewer and written into the audit trail.

{
  "schema": "vfs-perl-nn-knowledge",
  "version": 1,
  "name": "Workspace naming specialist",
  "articles": [
    {
      "id": "approved-production-name",
      "title": "Use the approved production name",
      "intent": "workspace_naming",
      "answer": "I can propose the reviewed production name. Chronicle must validate, accept, and separately apply it.",
      "tags": ["workspace", "rename", "proposal"],
      "queries": ["approved release name", "rename the root project"],
      "workspace_actions": [
        {
          "kind": "rename_project",
          "payload": {
            "project_id": "ROOT_PROJECT_UUID_FROM_STEP_1",
            "name": "Production Federation"
          },
          "reason": "Use the reviewed production-facing root name."
        }
      ]
    },
    {
      "id": "agent-authority",
      "title": "Keep agent and host authority separate",
      "intent": "workspace_governance",
      "answer": "The agent supplies proposal data only. A named reviewer accepts it, a named operator applies it, and build/export remains separate.",
      "tags": ["authority", "Chronicle"],
      "queries": ["who applies a plan", "can an agent commit"]
    }
  ]
}

Only articles that should propose a change receive workspace_actions. An ordinary explanatory article should omit it.

4. Train, verify, publish, and retain the bundle

Open PowerShell in the generated Perl distribution. Use a working image path and a new bundle directory:

perl .\bin\vfs-agent-branch `
  --image "C:\VFS-Demo\agent-working.vfsbin" `
  --agent-id workspace-planner `
  --data "C:\VFS-Demo\agent-training.csv" `
  --knowledge "C:\VFS-Demo\agent-knowledge.json" `
  --benchmark "C:\VFS-Demo\agent-benchmark.csv" `
  --bundle-output "C:\VFS-Demo\review-bundles\workspace-planner" `
  --minimum-accuracy 0.80 `
  --workers 4

The command trains only because you ran it. It checks the measured quality floor, reloads the model, checks knowledge coverage and every artifact digest, commits the validated bundle at /agents/workspace-planner, and retains the identical directory bundle for Studio. If validation or publication fails, no partial agent is published. Existing agent IDs and bundle directories are never overwritten.

Success ends with these four result lines. The percent, commit digest, and absolute directory are computed values rather than fixed sample text:

published agent workspace-planner at /agents/workspace-planner
accuracy: <measured percent>% (independent-benchmark)
commit: <64 lowercase hexadecimal characters>
review bundle: C:\VFS-Demo\review-bundles\workspace-planner

4A. Independently replay the benchmark

Keep replay results outside the bundle so the bundle remains a closed artifact set:

New-Item -ItemType Directory -Force "C:\VFS-Demo\review-evidence" | Out-Null
perl .\bin\plnn-text-evaluate `
  --model "C:\VFS-Demo\review-bundles\workspace-planner\model.json" `
  --data "C:\VFS-Demo\review-bundles\workspace-planner\benchmark.csv" `
  --json `
  --output "C:\VFS-Demo\review-evidence\workspace-planner.metrics.json" `
  --predictions "C:\VFS-Demo\review-evidence\workspace-planner.predictions.csv"

Require an exit code of zero, rows: 8, and an accuracy equal to the bundle manifest’s quality.measured_accuracy. Review the confusion matrix and every per-class row. Studio validates the actual corpora during admission but does not yet run this metric replay automatically.

5. Trust the signer, sign the retained bundle, and verify admission

If you do not already have a signing identity, create one outside the workspace and bundle. The command prompts twice for an encryption password:

vfs-federation-agent-actions keygen `
  --label "VFS agent release signer" `
  --private-key "C:\VFS-Keys\agent-release-signer.pem" `
  --public-key "C:\VFS-Keys\agent-release-signer.public.json"

In Chronicle Center → Agent trust, enter the accountable authority and verification note, choose Trust public key, and select the .public.json file. Trust it only after confirming its complete key ID through a separate channel. Then sign the retained directory and inspect it against this workspace:

vfs-federation-agent-actions sign-bundle `
  "C:\VFS-Demo\review-bundles\workspace-planner" `
  --private-key "C:\VFS-Keys\agent-release-signer.pem" `
  --expires-days 90

vfs-federation-agent-actions bundle-inspect `
  "C:\VFS-Demo\review-bundles\workspace-planner" `
  --workspace "C:\VFS-Demo\federation.vfsworkspace.json"

Continue only when trust_status is trusted, the corpus-validation matches are true with overlap 0, and admission.accepted is true. The first accepted version establishes the regression baseline. Later versions under the same agent ID must retain the same labels and benchmark digest.

6. Ask the named branch for proposal data

perl .\bin\vfs-perl-assistant `
  --agent-id workspace-planner `
  --image "C:\VFS-Demo\agent-working.vfsbin" `
  --ask "Propose the approved release name for this workspace" `
  --json | Set-Content -Encoding utf8 "C:\VFS-Demo\agent-answer.json"

Open agent-answer.json. A confident match to the naming article includes workspace_actions and workspace_action_authority: "proposal-only". A clarification or the governance article has no actions. Never turn a clarification into a plan.

7. Bind the answer to the current workspace

Drafting adds the exact workspace ID, configuration fingerprint, generation, agent fingerprint, summary, and rationale. It also performs the first dry run. The output path must be new.

vfs-federation-agent-actions draft `
  "C:\VFS-Demo\federation.vfsworkspace.json" `
  --agent-bundle "C:\VFS-Demo\review-bundles\workspace-planner" `
  --actions "C:\VFS-Demo\agent-answer.json" `
  --summary "Use the approved production root name" `
  --rationale "The workspace naming specialist selected the reviewed release recipe." `
  --proposal-id production-name-001 `
  --output "C:\VFS-Demo\production-name-001.proposal.json"

vfs-federation-agent-actions validate `
  "C:\VFS-Demo\federation.vfsworkspace.json" `
  "C:\VFS-Demo\production-name-001.proposal.json"

If the workspace configuration changes after drafting, the plan becomes stale and is rejected. Draft again against the new configuration; do not edit away the fingerprint.

8. Register and accept the exact agent

1. Open the workspace in Studio and choose Agent reconfiguration, or open Chronicle Center and select Proposals.
2. Choose Register agent bundle and select review-bundles\workspace-planner.
3. Select its pending perl-nn-agent-bundle row. Inspect the signer key ID and expiry, bundle fingerprint, labels, accuracy, benchmark digest and rows, regression result, artifact count, and permanent authority limits.
4. Enter the accountable reviewer or role and a note. Choose Accept.

Accepting the bundle establishes which exact trained agent may submit plans. It does not accept a plan and does not change the federation.

9. Import, preview, and accept the plan

1. Choose Import action proposal and select production-name-001.proposal.json.
2. Select the new agent-workspace-action row.
3. Read the summary, rationale, proposing agent fingerprint, every numbered action and reason, before/after counts, destructive-action count, and warnings.
4. If anything is unexpected, choose Reject. To replace an obsolete plan without applying it, choose Mark superseded.
5. If the exact visible diff is correct, enter a named review authority and note, then choose Accept.

Acceptance remains review-only. The root project still has its old name.

10. Apply as a separate operation

1. With the accepted plan selected, read the preview again.
2. Enter the accountable application authority and an application note.
3. Choose Apply accepted plan and confirm the displayed action and destructive counts.

Studio validates the plan again, requires the exact accepted agent, applies every item through the ordinary Chronicle command layer, marks the plan applied, and saves the complete batch atomically. A failure leaves the last committed workspace authoritative. The audit log records each action plus the separate application record.

11. Inspect, build, and export

1. Confirm the new name and generation in Home, Federation Explorer, and Chronicle History.
2. Open Design federation and inspect the resulting projects, sources, mounts, and profiles.
3. Use Path Resolution Lens and Monk Rule Lab when the change affects resolution or policy.
4. Choose Build & export. This remains a separate action and reuses the same staged verification route as a manual edit.
5. Run deep image verification and prove -Ilib -r t as shown in Build and export a Perl package.
6. Read the emitted package’s root README.md, share\example-first\assistant\README.md, and examples\branch_agent\README.md. They document the actual module, model measurements, Perl response fields, evaluator command, and specialist handoff in that export.

Permitted action families

One plan contains 1 to 64 actions. Remove actions are counted and highlighted as destructive. Floats, unknown fields, noncanonical identities, missing paths, stale configurations, invalid command sequences, or unaccepted agents stop the plan before registration or application.

Permanent limits

• No action can run a shell command, execute answer text, write an arbitrary file, access a network, alter credentials, or load a plugin.
• No action can change Monk policy, attach a neural model, decide trust, resolve another proposal, or bypass image/package verification.
• No agent can accept its own bundle, accept its own plan, invoke Apply, start Build, promote a recovery candidate, or publish a release.
• Artifact digests prove integrity. A trusted Ed25519 signature proves authorship of the exact manifest for a bounded time. Neither proves that advice is correct; the reviewer remains accountable for meaning.

Command-line equivalent for trust and review gates

vfs-federation-agent-actions trust-key WORKSPACE SIGNER.public.json `
  --authority "Trust administrator" --note "Key ID independently confirmed"
vfs-federation-agent-actions sign-bundle REVIEW_BUNDLE --private-key SIGNER.pem
vfs-federation-agent-actions bundle-inspect REVIEW_BUNDLE --workspace WORKSPACE
vfs-federation-agent-actions register-agent WORKSPACE REVIEW_BUNDLE
vfs-federation-agent-actions review WORKSPACE AGENT_PROPOSAL_ID accepted `
  --authority "Release reviewer" --note "Bundle, metrics, and authority checked."
vfs-federation-agent-actions register WORKSPACE PLAN.proposal.json
vfs-federation-agent-actions review WORKSPACE PLAN_ID accepted `
  --authority "Workspace reviewer" --note "Every visible action matches the request."
vfs-federation-agent-actions apply WORKSPACE PLAN_ID `
  --authority "Workspace operator" --note "Applied after separate acceptance."

Use the proposal IDs printed by the preceding commands. The CLI enforces the same ordering and does not combine review with application.

Troubleshooting